okstra 0.173.0 → 0.175.1

package/runtime/prompts/profiles/_implementation-verifier.md

@@ -10,8 +10,8 @@ at Phase 5, BEFORE constructing the verifier worker dispatch prompts.
 ## Verifier roles (resolved at run-prep time)
 
 - **Verifier dispatch labelling.** The core functional role label is `<provider>-verifier` (here, and identically in `final-verification`). Provider, role, and model identity are owned by `prompts/lead/okstra-lead-contract.md` "Model assignments"; the selected runtime adapter owns provider-native dispatch-label mapping (including any `name` / `**Pane role:**` fields) and token-attribution wiring under its "Semantic operation mapping". This functional label is NOT what the run's PROGRESS checkpoints carry: `phase-4-dispatch` / `phase-5-collect` name the roster role team-state records (`Claude worker`, `Codex worker`), because that is the entry the Phase 7 conformance check matches them against.
-- The verifier slots are `Claude verifier` and `Codex verifier`, plus `Antigravity verifier` **only when `antigravity` is in the resolved `--workers` roster**. Every verifier in the resolved roster is dispatched regardless of which provider holds the executor role; the executor's own provider is run *separately* as a verifier (a fresh CLI session with no shared context) so that no verdict is produced from the same session that wrote the diff. Verifiers MUST NOT call Edit, Write, or any Bash command that mutates files outside the run's artifact directories. If a verifier wants a fix, it records the recommendation in its worker result; it does not apply the fix itself.
-- Session isolation — not model-variant divergence — is the primary self-review safeguard: each verifier is a separate CLI invocation with its own context window, so reusing the same model variant for executor and same-provider verifier is acceptable. Different model variants (e.g. executor=opus / Claude verifier=sonnet) remain recommended when available.
+- The verifier slots are `Claude verifier` and `Codex verifier`, plus `Antigravity verifier` **only when `antigravity` is in the resolved `--workers` roster**. Every verifier in the resolved roster is dispatched except the one whose worker ID holds the executor role this run: that ID materializes as the executor on every dispatch (`scripts/okstra_ctl/worker_prompt_policy.py`), so the executor's own provider has no separate verifier session in the current plumbing — a follow-up design item. Independence still holds where it counts: every verdict comes from a fresh CLI session with no shared context, never from the session that wrote the diff. Verifiers MUST NOT call Edit, Write, or any Bash command that mutates files outside the run's artifact directories. If a verifier wants a fix, it records the recommendation in its worker result; it does not apply the fix itself.
+- Session isolation — not model-variant divergence — is the primary self-review safeguard: each verifier is a separate CLI invocation with its own context window, so a verifier reusing the executor's model variant is acceptable. Different model variants (e.g. executor=opus / Claude verifier=sonnet) remain recommended when available.
 - Phase-specific model defaults override the shared defaults: `Claude verifier`=`opus`, `Codex verifier`=`gpt-5.6-sol`, `Antigravity verifier`=`gemini-3.1-pro` (only when present in the roster). The `Executor`'s model is taken from the provider-specific worker model corresponding to `--executor`: claude→`--claude-model` (default `opus`), codex→`--codex-model` (default `gpt-5.6-sol`), antigravity→`--antigravity-model` (default `gemini-3.1-pro`).
 - Verifiers read from the SAME working tree path the Executor used so they observe the exact diff the Executor produced. Verifiers remain strictly read-only there.
 

package/runtime/prompts/profiles/change-impact-analysis.md

@@ -1,5 +1,21 @@
 # Change Impact Analysis Profile
 
+```yaml
+roles:
+  - role: analyser
+    count: 2
+    optionalCount: 3
+    duty: analysis-worker
+    minDistinctProviders: 2
+  - role: report-writer
+    count: 1
+    duty: report-writer
+  - role: verifier
+    count: 0
+    duty: reverification-worker
+    dynamic: true
+```
+
 - Purpose: assess the read-only impact of a proposed change, including preserved behavior, affected dependencies, and constraints that a later planning phase must resolve
 - Required workers:
   - claude

package/runtime/prompts/profiles/error-analysis.md

@@ -1,5 +1,25 @@
 # Error Analysis Profile
 
+```yaml
+roles:
+  - role: analyser
+    count: 2
+    optionalCount: 3
+    duty: diagnosis-worker
+    minDistinctProviders: 2
+  - role: critic
+    count: 0
+    optionalCount: 1
+    duty: scope-critic
+  - role: report-writer
+    count: 1
+    duty: report-writer
+  - role: verifier
+    count: 0
+    duty: reverification-worker
+    dynamic: true
+```
+
 - Purpose: analyse reported errors or incidents and identify likely causes, missing evidence, and validation paths
 - Required workers:
   - claude
@@ -27,7 +47,7 @@
 - Structured diagnosis and routing contract:
   - `errorAnalysis` is the source of truth for reproduction status, `EA-NNN` cause candidates, the sharp next diagnostic, and the next route.
   - A route to `implementation-option-selection` requires a credible leading cause referenced by `routing.leadingCauseId` and `begin-option-selection` as the direction. A route back to `error-analysis` requires the sharp next diagnostic and `continue-investigation` as the direction.
-  - Structure is enforced by `schemas/final-report-v1.0.schema.json` `$defs.ErrorAnalysis`. Cross-field diagnosis and route semantics are enforced by `validators/validate-run.py::_validate_error_analysis_consistency`.
+  - Structure is enforced by `schemas/final-report-v2.0.schema.json` `$defs.ErrorAnalysis`. Cross-field diagnosis and route semantics are enforced by `validators/validate-run.py::_validate_error_analysis_consistency`.
 - Primary focus areas:
   - symptom and trigger clarification
   - root-cause candidates

package/runtime/prompts/profiles/feature-analysis.md

@@ -1,5 +1,21 @@
 # Feature Analysis Profile
 
+```yaml
+roles:
+  - role: analyser
+    count: 2
+    optionalCount: 3
+    duty: analysis-worker
+    minDistinctProviders: 2
+  - role: report-writer
+    count: 1
+    duty: report-writer
+  - role: verifier
+    count: 0
+    duty: reverification-worker
+    dynamic: true
+```
+
 - Purpose: analyse a confirmed feature target's behavior, rules, state changes, external calls, and test coverage scope without designing or changing an implementation
 - Required workers:
   - claude

package/runtime/prompts/profiles/final-verification.md

@@ -1,5 +1,21 @@
 # Final Verification Profile
 
+```yaml
+roles:
+  - role: verifier
+    count: 2
+    optionalCount: 3
+    duty: acceptance-verifier
+    minDistinctProviders: 2
+  - role: critic
+    count: 0
+    optionalCount: 1
+    duty: acceptance-critic
+  - role: report-writer
+    count: 1
+    duty: report-writer
+```
+
 - Purpose: analyse completed work and identify remaining defects, omissions, and delivery risk before final acceptance
 - Required workers:
   - claude

package/runtime/prompts/profiles/implementation-option-selection.md

@@ -1,5 +1,21 @@
 # Implementation Option Selection Profile
 
+```yaml
+roles:
+  - role: designer
+    count: 3
+    optionalCount: 2
+    duty: direction-selection-worker
+    minDistinctProviders: 3
+  - role: report-writer
+    count: 1
+    duty: report-writer
+  - role: verifier
+    count: 0
+    duty: reverification-worker
+    dynamic: true
+```
+
 - Purpose: compare feasible implementation directions before planning, preserving a read-only record of the evidence and trade-offs that selects the direction to plan
 - Required workers:
   - claude

package/runtime/prompts/profiles/implementation-planning.md

@@ -1,5 +1,25 @@
 # Implementation Planning Profile
 
+```yaml
+roles:
+  - role: planner
+    count: 2
+    optionalCount: 3
+    duty: planning-worker
+    minDistinctProviders: 2
+  - role: critic
+    count: 0
+    optionalCount: 1
+    duty: acceptance-critic
+  - role: report-writer
+    count: 1
+    duty: report-writer
+  - role: verifier
+    count: 0
+    duty: reverification-worker
+    dynamic: true
+```
+
 - Purpose: turn an upstream-selected direction into an executable plan; legacy reruns may retain candidate comparison
 - Required workers:
   - claude
@@ -58,13 +78,13 @@
   - one `endStateCoverage` row per brief end-state id, whose `coveredBy` names the `R-NNN` row that carries it. The two tables are a chain, not duplicates: `endStateCoverage` proves no reporter requirement was dropped, `requirementCoverage` proves each one reaches a stage.
 - Implementation Design Preparation (`implementation-design-prep-v1`, BLOCKING):
   - **Detector SSOT:** the planner MUST run the V1 detector defined by `scripts/okstra_ctl/design_surfaces.py` (`detect_design_surfaces()` over the detector's `RULES`) and MUST NOT invent or copy a second keyword list into the plan or prompt. **Enforced:** `validators/validate-run.py` `_validate_detector_coverage` reruns that detector and compares every `(stage, kind)` plus its trigger evidence.
-  - **Exactly-once coverage:** for every detector-produced `(stage, kind)`, the planner MUST write exactly one `designSurfaceCoverage` row on that stage. **Enforced:** `validators/validate-run.py` `_validate_detector_coverage` rejects missing, duplicate, extra-detector-kind, or evidence-mismatched rows; `schemas/final-report-v1.0.schema.json` `$defs.DesignSurfaceCoverage` enforces the row shape.
-  - **Disposition:** a row MUST use `inline-contract` only when the stage already states the kind-specific minimum implementation contract; otherwise it MUST use `prep-item` and reference one or more `designPreparation.items`. `not-applicable` is legal only with a concrete rationale consistent with the stage action. **Enforced:** `schemas/final-report-v1.0.schema.json` `$defs.DesignSurfaceCoverage` enforces the disposition-specific fields, and `prompts/lead/plan-body-verification.md` `P-Prep-S<stage>-<kind>` verifies semantic sufficiency.
-  - **AI-prepared proposal:** every referenced PREP item MUST record `kind`, `stageRefs`, `need`, evidence-cited `knownFacts`, `openQuestions`, a concrete evidence-backed `aiProposal` (`summary`, `details`, `assumptions`, `evidence`, `confidence`), `humanConfirmation`, explicit `status`, and the safest reversible default available. **Enforced:** `schemas/final-report-v1.0.schema.json` `$defs.DesignPrepItem` / `$defs.DesignPrepProposal` enforce required fields, `validators/validate-run.py` `_validate_prep_references` enforces the bidirectional stage/kind link, and `prompts/lead/plan-body-verification.md` rejects empty or non-implementable proposals.
-  - **Status choice:** prefer `provisional` with a `workingAssumption`, concrete `guardrails`, `reviewAt`, `ifStillOpen`, and canonical `requestPath`; use `blocked` only for business policy, external authority, a destructive migration decision, or the absence of any safe reversible assumption. **Enforced:** `schemas/final-report-v1.0.schema.json` `$defs.DesignPrepItem` enforces state-specific fields, `validators/validate-run.py` `_validate_design_prep_states` enforces confirmation/request invariants, and `prompts/lead/plan-body-verification.md` judges whether the disposition is justified. A declared `blocked` status does not by itself fail plan-body verification.
+  - **Exactly-once coverage:** for every detector-produced `(stage, kind)`, the planner MUST write exactly one `designSurfaceCoverage` row on that stage. **Enforced:** `validators/validate-run.py` `_validate_detector_coverage` rejects missing, duplicate, extra-detector-kind, or evidence-mismatched rows; `schemas/final-report-v2.0.schema.json` `$defs.DesignSurfaceCoverage` enforces the row shape.
+  - **Disposition:** a row MUST use `inline-contract` only when the stage already states the kind-specific minimum implementation contract; otherwise it MUST use `prep-item` and reference one or more `designPreparation.items`. `not-applicable` is legal only with a concrete rationale consistent with the stage action. **Enforced:** `schemas/final-report-v2.0.schema.json` `$defs.DesignSurfaceCoverage` enforces the disposition-specific fields, and `prompts/lead/plan-body-verification.md` `P-Prep-S<stage>-<kind>` verifies semantic sufficiency.
+  - **AI-prepared proposal:** every referenced PREP item MUST record `kind`, `stageRefs`, `need`, evidence-cited `knownFacts`, `openQuestions`, a concrete evidence-backed `aiProposal` (`summary`, `details`, `assumptions`, `evidence`, `confidence`), `humanConfirmation`, explicit `status`, and the safest reversible default available. **Enforced:** `schemas/final-report-v2.0.schema.json` `$defs.DesignPrepItem` / `$defs.DesignPrepProposal` enforce required fields, `validators/validate-run.py` `_validate_prep_references` enforces the bidirectional stage/kind link, and `prompts/lead/plan-body-verification.md` rejects empty or non-implementable proposals.
+  - **Status choice:** prefer `provisional` with a `workingAssumption`, concrete `guardrails`, `reviewAt`, `ifStillOpen`, and canonical `requestPath`; use `blocked` only for business policy, external authority, a destructive migration decision, or the absence of any safe reversible assumption. **Enforced:** `schemas/final-report-v2.0.schema.json` `$defs.DesignPrepItem` enforces state-specific fields, `validators/validate-run.py` `_validate_design_prep_states` enforces confirmation/request invariants, and `prompts/lead/plan-body-verification.md` judges whether the disposition is justified. A declared `blocked` status does not by itself fail plan-body verification.
   - **External-reality anchoring (`external-interface` / `transformation-mapping` surfaces):** these two detector kinds are correct only against data whose shape lives *outside this repository* (a third-party response body / external payload format). For such a surface the referenced PREP item's `aiProposal` MUST derive the assumed shape — selectors, field paths, response structure — from a **captured real sample** and cite it in `knownFacts` / `evidence` (source + capture time); a shape invented from internal reasoning and marked `confidence: high` is the disallowed move, because a plan built on an assumed shape yields an implementation whose parser and fixture only ever agree with each other. When the brief supplies no sample and none is capturable at plan time, the item MUST stay `provisional` with a `workingAssumption` that the external shape is unverified against reality, a `guardrails` line forbidding the implementation from presenting a synthetic-fixture green run as reality-verified, and an `ifStillOpen` that routes to user confirmation against real data — it MUST NOT be dispositioned `inline-contract` / settled. **Enforced (semantic):** the surface's presence is machine-checked by `_validate_detector_coverage`; whether its proposal's evidence is genuinely external is judged by the §5.5.9 `P-Prep-S<stage>-<kind>` round (this phase runs it adversarially).
-  - **Planner-only test surface:** add `manual-user-test` only when a test prerequisite changes the implementation interface or acceptance contract; the V1 detector never emits it. **Enforced:** `validators/validate-run.py` `_validate_detector_coverage` rejects detector-produced `manual-user-test`, `schemas/final-report-v1.0.schema.json` permits its planner-authored shape, and `prompts/lead/plan-body-verification.md` verifies the stage-action rationale.
-  - **Trivial task:** when the detector returns no surfaces and no interface/acceptance-changing manual test input exists, `designPreparation` MUST use `mode: no-design-inputs`, an empty `items` array, and a concrete reason tied to the plan. **Enforced:** `schemas/final-report-v1.0.schema.json` `$defs.DesignPreparation` requires the reason and empty array for that mode; `validators/validate-run.py` `_validate_design_prep_contract` validates the marked V1 payload.
+  - **Planner-only test surface:** add `manual-user-test` only when a test prerequisite changes the implementation interface or acceptance contract; the V1 detector never emits it. **Enforced:** `validators/validate-run.py` `_validate_detector_coverage` rejects detector-produced `manual-user-test`, `schemas/final-report-v2.0.schema.json` permits its planner-authored shape, and `prompts/lead/plan-body-verification.md` verifies the stage-action rationale.
+  - **Trivial task:** when the detector returns no surfaces and no interface/acceptance-changing manual test input exists, `designPreparation` MUST use `mode: no-design-inputs`, an empty `items` array, and a concrete reason tied to the plan. **Enforced:** `schemas/final-report-v2.0.schema.json` `$defs.DesignPreparation` requires the reason and empty array for that mode; `validators/validate-run.py` `_validate_design_prep_contract` validates the marked V1 payload.
 - Approval gate (phase-specific addendum to shared authority rule):
   - The YAML frontmatter `approved: true|false` field is the only authorised approval gate. report-writer always emits `approved: false`. The user clears it either by (a) editing the frontmatter line to `approved: true` directly, or (b) invoking the next phase with `--approve` so the CLI flips the frontmatter on the user's behalf. `okstra_ctl.run._validate_approved_plan` reads this field and refuses entry until it is `true`.
 - Cross-verification mode:
@@ -103,7 +123,7 @@
   - Legacy candidate-comparison requires at least two implementation options. **Each option must include**:
     - **File Structure**: an explicit list of files to create / modify / delete with each file's responsibility (one-line each). Use the form `Create: path — responsibility` / `Modify: path:line-range — change summary` / `Delete: path — reason`. Write every `path` in full and `<PROJECT_ROOT>`-relative — never ellipsis-abbreviated (`…` / `...` / a trailing `/…`); an abbreviated path does not resolve and is rejected by plan-body verification as a kind-b path mismatch.
       - **Two-tier change description.** Each `fileStructure` row carries `summary` **and** optional `details`, and they are not interchangeable:
-        - `summary` — one plain-language sentence a reviewer who has never opened this file can follow: what changes and why it is needed. Name behaviour and domain nouns, not identifiers. No function/type/variable names, no call chains, no line numbers, no conditional logic spelled out. **Enforced:** `schemas/final-report-v1.0.schema.json` `$defs.OptionCandidate.fileStructure.items.summary` caps it at 120 characters, so a dense identifier dump fails schema validation.
+        - `summary` — one plain-language sentence a reviewer who has never opened this file can follow: what changes and why it is needed. Name behaviour and domain nouns, not identifiers. No function/type/variable names, no call chains, no line numbers, no conditional logic spelled out. **Enforced:** `schemas/final-report-v2.0.schema.json` `$defs.OptionCandidate.fileStructure.items.summary` caps it at 120 characters, so a dense identifier dump fails schema validation.
         - `details` — the technical specifics that used to be crammed into `summary`: exact symbol names, signatures, comparison semantics, line ranges, enum members. Omit the field when there is nothing beyond the summary.
         - Bad `summary` (identifier dump, no readable claim): `Widen the return of retrieveFontFamilyGroupWithFontVersionId to also yield the matched FontFamily (own key and enabled flag) and the matched Font.status.`
         - Good — `summary`: `Carry enough information out of the font lookup to tell whether the matched family is switched off.` / `details`: `Add the matched FontFamily (own key + enabled) and Font.status to the return of retrieveFontFamilyGroupWithFontVersionId. Both are already in scope in the :102-104 loop and dropped at return.`
@@ -111,12 +131,12 @@
     - estimated blast radius (units, configs, deployment manifests, data migrations)
   - trade-off matrix across options (rows = options, columns at minimum: complexity, risk, reversibility, test coverage cost, rollout cost)
   - recommended option with rationale tied to the design principles above
-  - `recommendedOption.testSeams` is a mandatory array with one row per boundary a test injects at and replaces: `boundary`, `injectedAs`, and `replacedInTest`. An empty array is legal only with a defensible reason. `schemas/final-report-v1.0.schema.json` requires the array and all three row fields; the §5.5.9 `P-Var-*` round rejects a seam whose construction or wiring point is not actually replaceable.
+  - `recommendedOption.testSeams` is a mandatory array with one row per boundary a test injects at and replaces: `boundary`, `injectedAs`, and `replacedInTest`. An empty array is legal only with a defensible reason. `schemas/final-report-v2.0.schema.json` requires the array and all three row fields; the §5.5.9 `P-Var-*` round rejects a seam whose construction or wiring point is not actually replaceable.
   - Record non-blocking working assumptions inside the Recommended Option. A required answer belongs in a `Blocks=approval` clarification instead. Omit the assumptions only when there are none.
   - The YAML frontmatter carries `implementation-option:` directly under `approved:` so the user can select an Option Candidate after planning.
 - Required deliverable shape (final report, in addition to the standard sections):
   - In the selected-direction branch, `directionRealization` is the sole design payload. Its `fileStructure`, interfaces, blast radius, test seams, assumptions, and invariants concretize the snapshot without introducing another option or recommendation.
-  - **Variation-point analysis (`variationPointAnalysis`, mandatory — every plan emits the block, rendered as §5.5.11):** declare `hasMultipleImplementations`, and when it is `true`, one `points[]` row per varying behavior carrying `behavior`, the two or more `implementations` that serve it, `evidence` (a `path:line`, or the sibling task / stage that already implements it), and an `extractionDecision` of `extract` / `interfaceKind` / `coveredBy` (the Stage Map stage that builds the interface) / `rationale`. **A `false` declaration is not an omission — it is a claim**, so it carries a written `noVariationRationale` and an empty `points` array; the two are mutually exclusive, because declared points would be silently dropped from verification under a `false` header. A project whose `.okstra/project.json` sets `architecture.style: hexagonal` extracts a point as a port (`interfaceKind: "port"`), never as a shared helper. **Enforced:** `schemas/final-report-v1.0.schema.json` `$defs.VariationPointAnalysis` / `$defs.VariationPoint` make the block required and pin the row shape; `validators/validate-run.py` `_validate_variation_point_analysis` rejects a `false` declaration with no rationale, a `false` declaration carrying points, a `true` declaration with no point, an `extract: true` decision naming no `interfaceKind` or no `coveredBy`, and a hexagonal project extracting as anything but a port; and every point becomes a `P-Var-<N>` plan item judged in §5.5.9 (`prompts/lead/plan-body-verification.md`) — a plan declaring no variation point is still verified, through the lone `P-Var-0`.
+  - **Variation-point analysis (`variationPointAnalysis`, mandatory — every plan emits the block, rendered as §5.5.11):** declare `hasMultipleImplementations`, and when it is `true`, one `points[]` row per varying behavior carrying `behavior`, the two or more `implementations` that serve it, `evidence` (a `path:line`, or the sibling task / stage that already implements it), and an `extractionDecision` of `extract` / `interfaceKind` / `coveredBy` (the Stage Map stage that builds the interface) / `rationale`. **A `false` declaration is not an omission — it is a claim**, so it carries a written `noVariationRationale` and an empty `points` array; the two are mutually exclusive, because declared points would be silently dropped from verification under a `false` header. A project whose `.okstra/project.json` sets `architecture.style: hexagonal` extracts a point as a port (`interfaceKind: "port"`), never as a shared helper. **Enforced:** `schemas/final-report-v2.0.schema.json` `$defs.VariationPointAnalysis` / `$defs.VariationPoint` make the block required and pin the row shape; `validators/validate-run.py` `_validate_variation_point_analysis` rejects a `false` declaration with no rationale, a `false` declaration carrying points, a `true` declaration with no point, an `extract: true` decision naming no `interfaceKind` or no `coveredBy`, and a hexagonal project extracting as anything but a port; and every point becomes a `P-Var-<N>` plan item judged in §5.5.9 (`prompts/lead/plan-body-verification.md`) — a plan declaring no variation point is still verified, through the lone `P-Var-0`.
   - **Stage Map (mandatory — always emitted, even when N=1):** a table of all stages with `stage | title | depends-on | step-count | exit-contract-summary`. `depends-on` is `(none)` or a comma-separated stage number list. Stages with `depends-on (none)` can be implemented in parallel by two simultaneous `implementation` runs.
     - **Keep the table at exactly 5 columns** — do NOT add a column. `validators/validate-implementation-plan-stages.py` parses `stage | title | depends-on | step-count | exit-contract-summary` and silently skips any row that is not exactly 5 cells, so a 6th column would drop every stage and bypass S2–S11.
     - **Multi-project plans only** (the plan's work spans more than one project — see the Project-boundary partition rule below): prefix each stage's `title` cell with a `[<project>]` tag (e.g. `[okstra] Add X`) so the project each stage belongs to is readable at a glance, and add exactly one line directly under the Stage Map table — `Cross-project parallelism: <which per-project stages run in parallel, which are sequenced, and the cross-project dependency that forces each sequencing>`. Single-project plans omit both the tag and the line.
@@ -132,6 +152,9 @@
   - **Per-stage subsections** (`## 5.5.<i> Stage <i>: <title>` for each `i`), each containing the four required subsections:
     - `### Carry-In` — for `depends-on (none)`: task-brief only. Otherwise: each depended-on stage's static exit contract + runtime sidecar path `runs/<impl-key>/carry/stage-<i>.json` placeholder.
     - `### Stepwise Execution Order` — bite-sized table with `step | action | files | command | outcome | expected`. `outcome` is one word — `PASS` or `FAIL` — and `expected` is the sentence saying what that looks like here; a verdict written inside the sentence is not read as one. The `files` cell lists each touched path in full and `<PROJECT_ROOT>`-relative — never ellipsis-abbreviated (`…` / `...`), which does not resolve and is rejected by plan-body verification as a kind-b path mismatch. **Effective row count ≤ 8** (excluding header / divider / blank). Each step is one cohesive, self-contained change (no lower time bound; it may span several files that change together); for code steps include actual code or diff sketch. **TDD ordering is MUST, not a preference:** the **first** effective step's `action` cell MUST start with the literal `RED:` and describe the failing test(s) that capture this stage's `Acceptance` **and the three declared `Test case (success|boundary|failure)` lines** (`outcome` = `FAIL`) — the RED step encodes the case set, not a single happy-path assertion; at least one later `action` cell MUST start with the literal `GREEN:` and describe the minimal implementation that makes it pass (`outcome` = `PASS`); an optional refactor step starts with `REFACTOR:`. **Exemption:** doc-only / config-only / pure-rename stages with no observable runtime behaviour may omit RED/GREEN by declaring one line `TDD exemption: <reason>` in the stage section (mirrors the executor's per-step exemption in `_implementation-executor.md`). Validator S10c enforces RED-first + GREEN; the `outcome` cell agreeing with its `RED:` / `GREEN:` prefix is a schema conditional (`StageStepRow.allOf`), so a plan whose data.json says otherwise never reaches the validator. S10e rejects a `TDD exemption:` whose reason is not one of doc-only / config-only / pure-rename (both in `validators/validate-implementation-plan-stages.py`).
+    - **The `command` cell runs inside an okstra task worktree, not a bare checkout (BLOCKING).** okstra provisions `.okstra`, the configured sync entries (`.project-docs`, `.claude`, …), and — for `implementation` — a nested `stage-<N>/` worktree into the tree the step executes in. Two consequences bind every command you write:
+      - **Clean-tree assertions use `okstra worktree-status --check-clean`.** A bare `git status --porcelain` is never empty there, so an assertion built on one fails on okstra's scaffolding rather than on the stage's work. The okstra command asks the same question over source paths only and exits 1 when dirty, so it chains: `okstra worktree-status --check-clean && git tag -f stage-<N>-exit`. Validator S13 rejects the bare form.
+      - **Never read an `.okstra/` artifact back out of a git object.** `.okstra/**` is gitignored and never committed — the executor aborts a commit that stages an ignored path and the verifier reports a committed `.okstra` path as a branch defect — so `git cat-file -e <tag>:.okstra/…`, `git show <tag>:.okstra/…`, and every variant of that read can never resolve, at any tag, in any stage. A later stage that needs a QA artifact reads it from the working tree or receives it through the carry sidecar / verifier result; do not design a stage contract around one being reachable from a tag. Validator S12 rejects the read.
     - **Per-stage conformance declaration (mandatory one line, in the stage section — same placement freedom as `TDD exemption:`):** the stage MUST carry exactly one of:
       - `Conformance tests: stage-<N> — <task_root>/qa/scripts/stage-<N>.<ext> (requires=[db|io|http|external,...])` — a Tier3 verification script that proves this stage's upstream requirements (brief / requirements-discovery / error-analysis / improvement-discovery → this stage's `Acceptance`) hold against **real** DB rows, real endpoints, or the real external API — NOT mocks. When you emit this line you MUST also (a) write the script to `<task_root>/qa/scripts/stage-<N>.<ext>` and (b) add a matching entry to `<task_root>/qa/conformance-manifest.json` with fields `stageKey` (= `<task-id>-stage-<N>`), `script`, `runCommand`, `requirementIds`, `requires` (subset of `{db, io, http, external}`), `passContract`, `exemption: null`, `waiver: null`. The script's standard interface: a `main` that exits `0`=PASS / non-zero=FAIL, and whose stdout ends with `QA-RESULT: PASS|FAIL` followed by one `REQ <id>: PASS|FAIL: <reason>` line per requirement. When the verification body is a test spec, author it with the project's own test framework (devDependency) invoked via a discovery override at `<task_root>/qa/scripts/` (jest: `--config <project config> --roots <task_root>/qa/scripts`) — never hand-roll `describe`/`expect` and never widen the project's own test config; for TypeScript specs also write `<task_root>/qa/scripts/tsconfig.json` extending the project tsconfig with the runner's `types` entry so editors resolve the file.
       - `Conformance exemption: <reason>` — only for stages that touch no db/io/http/external surface, or where unit tests fully cover the increment. (If the eventual `implementation` diff actually touches one of those surfaces, `validate-run.py`'s diff-surface cross-check is BLOCKING — an exemption cannot hide a real db/io/http/external change.)

package/runtime/prompts/profiles/implementation.md

@@ -1,5 +1,20 @@
 # Implementation Profile
 
+```yaml
+roles:
+  - role: implementer
+    count: 1
+    duty: implementation-executor
+  - role: verifier
+    count: 2
+    optionalCount: 1
+    duty: implementation-verifier
+    minDistinctProviders: 2
+  - role: report-writer
+    count: 1
+    duty: report-writer
+```
+
 - Purpose: realise the approved `implementation-planning` deliverable as actual source changes, with cross-model verification, while keeping the run reversible
 - **Run-level fixed cost:** the verifier set, Phase 5.5 convergence, and the Phase 6 report-writer run exactly once per implementation run, over this run's single stage diff — never once per step.
 - **Fix run (profile carries a "Fix-Run Carry" block):** the executor's scope is the carried blocking findings plus the previous routing recommendation — it MUST NOT re-execute plan steps the previous run completed. Verifiers apply the "Fix-run incremental scope" section of `_implementation-verifier.md`; the report writer applies "Fix-run incremental authoring" in `report-writer.md`. The full validation-command re-run is NOT reduced.
@@ -16,7 +31,8 @@
   - Executor model: `{{EXECUTOR_MODEL_DISPLAY}}` (CLI launch value: `{{EXECUTOR_MODEL_EXECUTION_VALUE}}`; host-native launch value: `{{EXECUTOR_HOST_MODEL_VALUE}}`)
   - Executor runner: `{{EXECUTOR_RUNNER}}`
   - Executor dispatch mode: `{{EXECUTOR_DISPATCH_MODE}}`
-  - Wherever this profile mentions the `Executor`, it refers to the role bound above. **Every** analysis provider in the resolved roster is also dispatched as a verifier — including the executor's own provider, which runs *separately* as a fresh session with no shared context so no verdict comes from the session that wrote the diff (`_implementation-verifier.md` owns this rule). Verifier dispatches remain strictly read-only.
+  - Wherever this profile mentions the `Executor`, it refers to the role bound above. Every analysis provider in the resolved roster **except `{{EXECUTOR_WORKER_ID}}`** is dispatched as a verifier, each in a fresh session with no shared context, so no verdict comes from the session that wrote the diff (`_implementation-verifier.md` owns this rule). The executor's own provider gets **no** second, verifier-role session in the current plumbing: `worker_prompt_policy` materializes that worker ID as the executor on every dispatch, so there is no way to ask for one — treat that as a follow-up design item, never as something to work around from the lead. Verifier dispatches remain strictly read-only.
+  - **Dispatch order (BLOCKING).** Executor and verifiers are **two** dispatches, never one batch — a batch holding both makes every verifier observe base HEAD instead of the stage diff. Dispatch the executor alone, settle it with `okstra team await`, then dispatch the verifiers with a `--workers` list that **omits `{{EXECUTOR_WORKER_ID}}`**: that worker ID is materialized as the executor on every dispatch, so a second batch still carrying it is refused again. **Enforcement:** `scripts/okstra_ctl/dispatch_core.py` `_validate_implementation_phase_order` refuses such a batch, in `--dry-run` as well as in a real dispatch.
 {{INCLUDE:_common-contract.md}}
 {{INCLUDE:_stage-discipline.md}}
 - Pre-implementation gate (mandatory — refuse to start if any item fails):

package/runtime/prompts/profiles/improvement-discovery.md

@@ -1,5 +1,21 @@
 # Improvement Discovery Profile
 
+```yaml
+roles:
+  - role: analyser
+    count: 3
+    optionalCount: 2
+    duty: discovery-worker
+    minDistinctProviders: 3
+  - role: report-writer
+    count: 1
+    duty: report-writer
+  - role: verifier
+    count: 0
+    duty: reverification-worker
+    dynamic: true
+```
+
 - Purpose: scan a codebase scope through a fixed lens whitelist and surface ranked improvement candidates with multi-worker consensus classification
 - Required workers:
   - claude

package/runtime/prompts/profiles/project-analysis.md

@@ -1,5 +1,21 @@
 # Project Analysis Profile
 
+```yaml
+roles:
+  - role: analyser
+    count: 2
+    optionalCount: 3
+    duty: analysis-worker
+    minDistinctProviders: 2
+  - role: report-writer
+    count: 1
+    duty: report-writer
+  - role: verifier
+    count: 0
+    duty: reverification-worker
+    dynamic: true
+```
+
 - Purpose: map a bounded project area so later work can navigate components, dependencies, entry points, repositories, and external integrations without changing the source
 - Required workers:
   - claude

package/runtime/prompts/profiles/release-handoff.md

@@ -1,5 +1,9 @@
 # Release Handoff Profile
 
+```yaml
+roles: []
+```
+
 - Record the handoff shape in `releaseHandoff.handoffScope`: `mode` always, plus `stages`
   and `collectorBranch` in stage-group mode. The report is the only place a reader learns
   which stages shipped — the collector branch name does not say.
@@ -9,7 +13,7 @@
 - Lead-only contract (replaces the shared team contract for this phase):
   - The host-native Okstra lead is the sole agent for this run. No worker dispatch, no teammates, no parallel sub-agents, no convergence loop.
   - The lead drafts the PR title and PR body **inline** by reading the run brief, the cited final-verification report, `git log --oneline <base>..HEAD`, and `git diff <base>..HEAD --stat`. No drafter worker is dispatched.
-  - The lead authors the final-report file directly (no `Report writer worker` dispatch). The report still conforms to the standard `templates/reports/final-report.template.md` structure, including the `## 5.6 Release Handoff Deliverables` section.
+  - The lead authors the final-report file directly (no `Report writer worker` dispatch). The report still conforms to the standard `templates/reports/final-report-v2.template.md` structure, including the `## 5.6 Release Handoff Deliverables` section.
   - The shared anti-escalation rule from the common contract still applies: do not start any other lifecycle phase from inside this run.
   - The shared "authority & permissions assumption" rule from the common contract still applies: assume the user holds every permission needed; do not block on hypothetical approvals.
   - The shared "MCP read-only" rule still applies if the brief lists MCP servers, though most release-handoff runs do not use MCP.

package/runtime/prompts/profiles/requirements-discovery.md

@@ -1,5 +1,25 @@
 # Requirements Discovery Profile
 
+```yaml
+roles:
+  - role: analyser
+    count: 2
+    optionalCount: 3
+    duty: analysis-worker
+    minDistinctProviders: 2
+  - role: critic
+    count: 0
+    optionalCount: 1
+    duty: scope-critic
+  - role: report-writer
+    count: 1
+    duty: report-writer
+  - role: verifier
+    count: 0
+    duty: reverification-worker
+    dynamic: true
+```
+
 - Purpose: classify the work request, identify missing requirement evidence, and route the task to the safest next lifecycle phase before implementation starts
 - Required workers:
   - claude

package/runtime/prompts/wizard/prompts.ko.json

@@ -480,6 +480,22 @@
         "no": "아니오 — 단계별로 다시 입력"
       }
     },
+    "role_count": {
+      "label": "{role} 역할 인스턴스 수를 선택하세요 ({minimum}..{maximum}, 기본 {default})",
+      "echo_template": "role-count: {value}",
+      "options": {
+        "count": "{count}개{default_suffix}",
+        "default_suffix": " (기본)"
+      }
+    },
+    "role_model": {
+      "label": "{role} 역할 {ordinal}/{count} 인스턴스의 모델을 선택하세요",
+      "echo_template": "role-model: {value}",
+      "options": {
+        "model": "{model_ref} — {display}{default_suffix}",
+        "default_suffix": " (기본 후보)"
+      }
+    },
     "defaults_or_custom": {
       "label": "역할별 모델 선택 단계입니다 (참여 워커 구성을 바꾸는 게 아닙니다).\n이번 run 에서 모델을 고를 역할:\n{role_models}\n· 기본값으로 진행 — 위 추천 모델을 그대로 쓰고, directive·관련 task 없이 바로 넘어갑니다.\n· 커스터마이즈 — 위 역할별 모델을 직접 고르고, 추가 directive·관련 task 도 지정합니다.\n(추천 값은 runtime 기본값으로 해소됩니다. 분석에 참여하지 않는 역할은 위 목록에 나오지 않습니다 — 예: antigravity 는 implementation 의 executor 로 선택했을 때만 표시됩니다.)",
       "echo_template": "customize: {value}",
@@ -587,6 +603,8 @@
   },
   "confirmation": {
     "header": "선택 확인:",
+    "static_role": "  static-role   : {role}#{ordinal} / {model}",
+    "dynamic_role": "  dynamic-role  : {role} / reuse selected participant model",
     "workers_implementation_default": "  workers       : (프로필 기본 — executor + verifier 2 + report-writer)",
     "base_ref_stage_isolated": "  base-ref      : (stage 격리 — 의존 stage 기준으로 run 준비 시점에 자동 해소)",
     "base_ref_reuse_task_dir": "  base-ref      : (기존 `{task_key}` 디렉터리 재사용 — 최초 base 유지)",

package/runtime/python/okstra_ctl/adapters/dispatch/__init__.py

@@ -39,16 +39,11 @@ def default_worker_dispatch_port(
         if provider_registry is not None
         else None
     )
-    default_backend = (
-        dispatch_core.BACKEND_TMUX_PANE
-        if descriptor.launch_mode == "team"
-        else dispatch_core.BACKEND_CLI_WRAPPER
-    )
     return CliWrapperDispatchPort(
         supported_worker_wrappers=wrappers,
         unsupported_worker_label=f"{descriptor.id} lead",
         required_lead_runtime=descriptor.id,
-        default_backend=default_backend,
+        default_backend=dispatch_core.BACKEND_CLI_WRAPPER,
     )
 
 

package/runtime/python/okstra_ctl/adapters/dispatch/cli_wrapper.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 from collections.abc import Mapping
 
 from ... import dispatch_core
+from ...domain.worker_exec import WorkerWriteCapability
 from ...ports.worker_dispatch import WorkerDispatchPlan, WorkerDispatchRequest
 
 
@@ -17,6 +18,9 @@ class CliWrapperDispatchPort:
         default_backend: str = dispatch_core.BACKEND_CLI_WRAPPER,
         cli_wrapper_assignments_only: bool = False,
         default_provider_by_worker_id: Mapping[str, str] | None = None,
+        worker_write_capability: WorkerWriteCapability = WorkerWriteCapability(
+            "none"
+        ),
     ) -> None:
         self._supported_worker_wrappers = supported_worker_wrappers or {}
         self._unsupported_worker_label = unsupported_worker_label
@@ -26,6 +30,7 @@ class CliWrapperDispatchPort:
         self._default_provider_by_worker_id = dict(
             default_provider_by_worker_id or {}
         )
+        self._worker_write_capability = worker_write_capability
 
     def build_plan(self, request: WorkerDispatchRequest) -> WorkerDispatchPlan:
         backend_plan = None
@@ -52,3 +57,6 @@ class CliWrapperDispatchPort:
             backend_plan=backend_plan,
             dispatch_mode="render-only",
         )
+
+    def worker_write_capability(self) -> WorkerWriteCapability:
+        return self._worker_write_capability

package/runtime/python/okstra_ctl/adapters/dispatch/cmux.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 from collections.abc import Mapping
 
 from ... import dispatch_core
+from ...domain.worker_exec import WorkerWriteCapability
 from ...ports.worker_dispatch import (
     WorkerDispatchPlan,
     WorkerDispatchPort,
@@ -25,6 +26,9 @@ class CmuxDispatchPort:
         required_lead_runtime: str | None = None,
         cli_wrapper_assignments_only: bool = False,
         default_provider_by_worker_id: Mapping[str, str] | None = None,
+        worker_write_capability: WorkerWriteCapability = WorkerWriteCapability(
+            "none"
+        ),
     ) -> None:
         self._backend_port = CliWrapperDispatchPort(
             supported_worker_wrappers=supported_worker_wrappers,
@@ -33,6 +37,7 @@ class CmuxDispatchPort:
             default_backend=dispatch_core.BACKEND_CMUX_PANE,
             cli_wrapper_assignments_only=cli_wrapper_assignments_only,
             default_provider_by_worker_id=default_provider_by_worker_id,
+            worker_write_capability=worker_write_capability,
         )
 
     def build_plan(self, request: WorkerDispatchRequest) -> WorkerDispatchPlan:
@@ -46,6 +51,9 @@ class CmuxDispatchPort:
             relay_contract=CMUX_RELAY_CONTRACT,
         )
 
+    def worker_write_capability(self) -> WorkerWriteCapability:
+        return self._backend_port.worker_write_capability()
+
 
 def dispatch_port_for_terminal_backend(
     terminal_backend: str,

package/runtime/python/okstra_ctl/adapters/dispatch/native_team.py

@@ -1,13 +1,26 @@
 """Native host-team dispatch planning."""
 from __future__ import annotations
 
+from ...domain.worker_exec import WorkerWriteCapability
 from ...ports.worker_dispatch import WorkerDispatchPlan, WorkerDispatchRequest
 
 
 class NativeTeamDispatchPort:
+    def __init__(
+        self,
+        *,
+        worker_write_capability: WorkerWriteCapability = WorkerWriteCapability(
+            "none"
+        ),
+    ) -> None:
+        self._worker_write_capability = worker_write_capability
+
     def build_plan(self, request: WorkerDispatchRequest) -> WorkerDispatchPlan:
         return WorkerDispatchPlan(
             mode="native-team",
             request=request,
             dispatch_mode="team",
         )
+
+    def worker_write_capability(self) -> WorkerWriteCapability:
+        return self._worker_write_capability

package/runtime/python/okstra_ctl/adapters/hosts/antigravity/adapter.py

@@ -60,7 +60,7 @@ def create_adapter(
         detector=no_automatic_claim,
         provider_registry=provider_registry,
         host_model_port=host_model_port or NativeExecutionValueHostModelBindingPort(
-            DESCRIPTOR.id,
-            DESCRIPTOR.native_provider_id,
+            host_runtime=DESCRIPTOR.id,
+            native_provider=DESCRIPTOR.native_provider_id,
         ),
     )

package/runtime/python/okstra_ctl/adapters/hosts/claude-code/adapter.py

@@ -15,6 +15,7 @@ from okstra_ctl.adapters.hosts.capability_adapter import (
     numbered_interaction_port,
 )
 from okstra_ctl.domain.host import HostClaim, HostDescriptor, HostResolutionContext
+from okstra_ctl.domain.provider import HostModelBinding
 from okstra_ctl.ports.host_model import (
     HostModelBindingError,
     HostModelBindingRequest,
@@ -42,27 +43,46 @@ DESCRIPTOR = HostDescriptor(
 class ClaudeFamilyHostModelBindingPort:
     _FAMILIES = ("fable", "opus", "sonnet", "haiku")
 
-    def resolve(self, request: HostModelBindingRequest) -> str | None:
+    def resolve(self, request: HostModelBindingRequest) -> HostModelBinding:
         if request.runner == "cli-wrapper":
-            return None
+            return HostModelBinding(
+                runner=request.runner,
+                catalog_execution_value=request.model_execution_value,
+                resolved_execution_value=request.execution_value,
+                host_model_value=None,
+                binding_fidelity="exact",
+                worker_write_capability=request.worker_write_capability,
+            )
         if (
             request.runner != "native-session"
             or request.host_runtime != DESCRIPTOR.id
             or request.provider != DESCRIPTOR.native_provider_id
         ):
             raise self._unsupported(request)
-        segments = request.model_execution_value.lower().split("-")
+        segments = request.execution_value.lower().split("-")
         matches = [family for family in self._FAMILIES if family in segments]
         if len(matches) != 1:
             raise self._unsupported(request)
-        return matches[0]
+        if request.version_kind == "pinned":
+            raise HostModelBindingError(
+                "exact binding unavailable: "
+                f"host={request.host_runtime!r}, model={request.model_ref!r}"
+            )
+        return HostModelBinding(
+            runner=request.runner,
+            catalog_execution_value=request.model_execution_value,
+            resolved_execution_value=request.execution_value,
+            host_model_value=matches[0],
+            binding_fidelity="channel",
+            worker_write_capability=request.worker_write_capability,
+        )
 
     @staticmethod
     def _unsupported(request: HostModelBindingRequest) -> HostModelBindingError:
         return HostModelBindingError(
             "unsupported host model: "
             f"host={request.host_runtime!r}, provider={request.provider!r}, "
-            f"model={request.model_execution_value!r}"
+            f"model={request.execution_value!r}"
         )
 
 

package/runtime/python/okstra_ctl/adapters/hosts/codex/adapter.py

@@ -83,7 +83,7 @@ def create_adapter(
         provider_registry=provider_registry,
         readiness_probe=_okstra_home_write_checks,
         host_model_port=host_model_port or NativeExecutionValueHostModelBindingPort(
-            DESCRIPTOR.id,
-            DESCRIPTOR.native_provider_id,
+            host_runtime=DESCRIPTOR.id,
+            native_provider=DESCRIPTOR.native_provider_id,
         ),
     )

package/runtime/python/okstra_ctl/adapters/hosts/external/adapter.py

@@ -13,6 +13,7 @@ from okstra_ctl.adapters.hosts.capability_adapter import (
     numbered_interaction_port,
 )
 from okstra_ctl.domain.host import HostClaim, HostDescriptor, HostResolutionContext
+from okstra_ctl.ports.host_model import FailClosedHostModelBindingPort
 from okstra_ctl.registry.provider_registry import ProviderRegistry
 
 
@@ -70,5 +71,7 @@ def create_adapter(
         supported_functions=INTERACTION_FUNCTIONS,
         detector=_detect_tmux,
         provider_registry=provider_registry,
-        host_model_port=host_model_port,
+        host_model_port=(
+            host_model_port or FailClosedHostModelBindingPort(DESCRIPTOR.id)
+        ),
     )