Refinement¶

Refinement lets an app route change requests against generated artifacts. It is optional. Most CRUD apps, fixed workflow apps, and simple assistants only need app/config/ai.json.

Use refinement when the app needs routed revisions, scoped artifact patches, checkpoint decisions, or workflow re-entry based on request meaning.

Files¶

Minimal Policy¶

schema_version: mozaiks.refinement.policy.v1
enabled: true

llm_profiles:
  classifier:
    purpose: Classify refinement requests into stable change classes.
    expected_behavior: deterministic structured classification
    llm_config:
      api_type: openai
      model: gpt-5-nano
  codegen:
    purpose: Generate scoped code or artifact patches.
    expected_behavior: deterministic code and artifact generation
    llm_config:
      api_type: openai
      model: gpt-5.2-codex
      temperature: 0.1

classifier:
  enabled: true
  llm_profile: classifier
coding:
  enabled: true
  llm_profile: codegen

Model parameters belong inside each profile's llm_config. For models that support temperature, use llm_config.temperature. Profile fields are strict: purpose, expected_behavior, and llm_config. The unused default_temperature field is rejected. Every enabled capability must name a declared profile with a non-empty model; inline capability llm_config and unknown capability fields are rejected when the policy loads.

Model profiles and coding agents¶

llm_profiles configures AG2 structured-output calls. A profile name describes the work; its llm_config.model selects the model for that call.

Use a flat llm_config with model and optional api_type. Enabled refinement profiles reject config_list because AG2 would select its first entry instead of the declared flat model.

The first-party policy uses these profiles:

The policy names the two contract-surface steps separately:

contract_surface:
  enabled: true
  llm_profile: impact_analyzer
  regeneration_llm_profile: codegen

llm_profile selects affected surfaces. regeneration_llm_profile selects the file-generation model and must resolve to a declared profile with a non-empty model before regeneration starts. To tune generation independently, declare a surface_regeneration profile and reference it here. This works even when structured patch coding is disabled.

coding.providers.acp.adapter is a separate execution choice. For example, adapter: claude_code starts the Claude Code ACP agent when ACP is enabled and eligible; it does not turn llm_profiles.codegen.llm_config.model into a Claude model. That model is used for structured-output patch coding and for a permitted fallback after an ACP attempt. The current app-bundle ACP adapter uses its coding CLI's default model; ACP model selection is independent of this profile.

The architecture profile is currently an advisory workflow-context label; workflow execution does not resolve its model from this policy yet. planner_replanner and reviewer_validator currently describe optional dry-run plan roles, rather than separate live model calls. The first-party policy leaves them undeclared.

Optional ACP coding provider¶

The ACP coding provider remains disabled until an isolated worker is connected to the refinement route. Its coding.providers.acp.budget accepts only max_files, max_diff_bytes, and max_wall_seconds. These limit one provider attempt. The unused max_retries setting is rejected; it never controlled provider retries. This does not change provider-specific retry parameters inside llm_config.

A trusted ACP-only worker can pass an approved ControlPlaneACPProviderConfig directly to ACPCodingProvider(provider_config=...). That worker does not make structured-output calls, so it does not need a synthetic codegen model profile. Normal refinement routing still loads the full policy and requires a named model profile for enabled coding and its structured fallback. The direct provider configuration does not authorize a worker launch or relax isolation.

Minimal Harness¶

schema_version: mozaiks.refinement_harness.v1
extends: mozaiks.default_refinement_harness
overrides: {}

The default OSS harness supplies the standard artifact routes, checkpoint chain, tools, policies, and prompts. Add local overrides.routing, overrides.checkpoints, config/tools.yaml, config/policies.yaml, or prompts/*.yaml only for real app-specific deltas.

Every workflow_sequence referenced by the effective harness must exist in the effective workflows/extended_orchestration/extension_registry.json.

Code Context By Checkpoint¶

Refinement should use code context progressively:

Do not dump a repository into prompts. The current AppIntelligenceSnapshot summarizes architecture and ownership; SourceContextBundle stores selected redacted files, chunks, symbols, and imports; agents retrieve exact evidence through tools only when their checkpoint needs it.

Boundaries¶

Read Next¶

• AI Startup
• Workflow Registry
• Refinement Harness Architecture