okstra 0.186.7 → 0.187.0

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

@@ -8,10 +8,10 @@ roles:
     max: 5
     duty: planning-worker
   - role: critic
-    min: 1
+    min: 0
     recommended: 1
     max: 1
-    duty: acceptance-critic
+    duty: scope-critic
   - role: report-writer
     min: 1
     recommended: 1
@@ -44,7 +44,8 @@ roles:
   - **Ticket Tagging.** Tag every section 1–5 item with its related ticket. Use `Issue / Ticket`, fall back to Task ID, then `unknown`; comma-separate multiple tickets.
   - route by the planning input contract before analysis. A run carrying `selected-direction.json` uses the selected-direction procedure. Only a legacy rerun without that snapshot uses candidate comparison.
   - **Selected-direction planning procedure** — perform these steps in order and no others:
-    1. Read `selected-direction.json` and the original requirements ledger end-to-end.
+    1. Read `selected-direction.json` and the original requirements ledger end-to-end. The ledger is not a separate file: it is the brief's `Expected Behavior` / `Preserved Behavior` / `Expected Outcome` sections (`EB-` / `PB-` / `EO-` ids), carried verbatim in the analysis packet's `## Task-Specific Brief Extract`.
+    1a. Fill `selectedDirectionRef` from that snapshot: copy `sourceReport`, `sourceDataSha256`, and `optionId` verbatim from the file; write `snapshotPath` as the snapshot's path relative to the **task root** (`instruction-set/selected-direction.json`, never project-relative and never absolute) and `snapshotSha256` as the SHA-256 of its exact bytes. Those last two are the only ref fields the snapshot does not carry.
     2. Concretize the selected direction into files, interfaces, stages, validation, and rollback without changing its mechanism or boundaries.
     3. Link every planned file and stage bidirectionally to the original requirements.
     4. If current evidence requires changing the selected direction, emit `direction-invalidated` and stop planning.
@@ -67,8 +68,9 @@ roles:
     - A stage whose `status` is `done` is already implemented and will not be executed again. Carry its plan body forward as written; do not rewrite its steps, and do not fold its work into a new stage.
     - Every stage number in the ledger is taken. A new stage takes the next number after the highest one listed; numbers are never reused or reordered. **Not yet machine-enforced** — the validator for this rule lands with the plan-amendment feature.
     - The ledger answers two questions from two sources, and the block names both. `sourcePlan` is the plan the completed stages were actually built against; `latestPlan` is the plan the `stages` list came from and is therefore the numbering authority. When they differ, the completed work followed the former and the highest taken number comes from the latter.
-    - A `planDivergence` entry means the two plans disagree about a stage that is already `done` — the same number naming different work, or a completed stage the latest plan no longer declares. Do not pick one of the two yourself; register it as a `Blocks=approval` clarification row and assign no new stage number until it is resolved.
+    - A `planDivergence` entry means one of two things: the two plans disagree about a stage that is already `done` — the same number naming different work, or a completed stage the latest plan no longer declares — or the plan the completed stages were built against could not be read at all, so that comparison never ran. Both block the same way: do not pick one of the two plans yourself; register it as a `Blocks=approval` clarification row and assign no new stage number until it is resolved. Completed stages built against an *earlier* plan are not a divergence — that is the normal shape of an amended plan and the ledger folds it silently.
     - The block is absent ONLY on a task's first planning run. Its absence then means there is no prior plan, not that no stage is done. When the ledger could not be read, the packet says so under the same heading with a reason instead of going silent — in that state, assign no new stage number and report the reason as a blocker.
+  - **Prior Planning Run (read before re-deriving anything):** on a re-run the packet carries a `## Prior Planning Run` block with the previous planning run's clarification rows, its Stage Map one line per stage, the findings its convergence left `contested` / `worker-unique`, and the path to the report itself. It is context, not an approved plan — the previous run did not reach approval. Use it so a stage you are not changing keeps the wording it already had and a settled question is not re-opened under a new `P-*` number; where the brief, the directive, or a clarification answer disagrees with it, they win. The block is absent on a first planning run and on a clarification re-run, which receives the same rows through `## Clarification Carry-In Extract` instead. **Enforced:** `okstra_ctl.prior_planning.build_prior_planning_summary` assembles it and `okstra_ctl.analysis_packet._prior_planning_block` renders it; nothing checks that a worker read it.
 - Primary focus areas:
   - requirement gaps
   - affected components and boundaries
@@ -88,14 +90,15 @@ roles:
   - dependency and risk visibility
   - recommended execution order
   - 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.
+  - a `blocked` `endStateCoverage` row MUST carry `blockedBy` — `kind` one of `clarification` / `finding` / `execution` / `upstream` / `not-observed`, plus a `ref` for the first two. `blocked` on its own carries all five situations at once, and only `clarification` is something a person can answer; without the field nothing downstream can tell "the reporter must decide" from "the server would not boot". A `clarification` ref must be a `C-NNN` row of this report or one carried in — the same row the approval-decision ledger holds, not an id you only named in prose. A `finding` ref is required but not resolved: it legitimately points at the approved plan or an upstream report (`VC-003`, `CA-001`). **Enforced:** `validators/validate-run.py` `_validate_end_state_blocked_by`.
 - 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-v2.0.schema.json` `$defs.DesignSurfaceCoverage` enforces the row shape.
+  - **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:** `scripts/okstra_ctl/report_projections.py` `project_design` reruns that detector against the plan and raises `ReportProjectionError` when the snapshot's surfaces do not match it, so a hand-authored keyword list cannot survive projection.
+  - **Exactly-once coverage:** for every detector-produced `(stage, kind)`, exactly one `designSurfaceCoverage` row exists on that stage. **Enforced:** the rows are written once by `scripts/okstra_ctl/design_snapshot.py` `build_design_snapshot` (one per detected trigger, carrying its evidence) and `scripts/okstra_ctl/report_projections.py` `project_design` refuses any snapshot whose `(stage, kind)` set or trigger evidence differs from a fresh detector run — that is where a missing, duplicated, or evidence-drifted row stops; `schemas/final-report-v2.0.schema.json` `$defs.DesignSurfaceCoverage` enforces the row shape.
   - **Disposition:** the design-surface detector snapshot uses `inline-contract` only when the stage already states the kind-specific minimum implementation contract; otherwise it uses `prep-item`. `not-applicable` is legal only with a concrete rationale consistent with the stage action. **Enforced:** `scripts/okstra_ctl/report_projections.py::project_design`, `schemas/final-report-v3.0.schema.json`, and `P-Prep-S<stage>-<kind>` verification.
-  - **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.
+  - **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; the stage ↔ PREP link is not checked afterwards because it is not authored — `scripts/okstra_ctl/design_snapshot.py` `build_design_snapshot` emits each coverage row's `prepItemId` and the matching item's `stageRefs` in the same pass, so the two sides cannot disagree. `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-v2.0.schema.json` permits its planner-authored shape, and `prompts/lead/plan-body-verification.md` verifies the stage-action rationale.
+  - **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 `scripts/okstra_ctl/report_projections.py` `project_design`; 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:** the detector's `RULES` in `scripts/okstra_ctl/design_surfaces.py` contain no `manual-user-test` rule, so every such row is planner-authored by construction and none can arrive through the detector snapshot; `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, its input uses `designPreparation.mode: no-design-inputs`, an empty `items` array, and a concrete reason tied to the plan. **Enforced:** `schemas/final-report-v3.0.schema.json` and `scripts/okstra_ctl/report_assembly.py`.
 - Approval gate (phase-specific addendum to shared authority rule):
   - The report record `frontmatter.approved` field is the only authorised approval gate. report-writer always emits `false`. The user clears it by invoking the next phase with `--approve`, or by confirming approval in the in-session wizard. Editing the full reading copy does not approve the plan. `okstra_ctl.run._validate_approved_plan` reads this field and refuses entry until it is `true`.
@@ -103,8 +106,8 @@ roles:
   - Phase 5.5 finding convergence runs in **adversarial mode** for this phase (`convergence.adversarial=true`). Verifiers actively try to refute each worker finding (requirement gap / risk / plan item) by re-inspecting its cited evidence; the burden of proof sits on the claim. See `prompts/lead/convergence.md` §"Adversarial Verification Mode".
   - §5.5.9 plan-body verification runs with an **adversarial posture** (`prompts/lead/plan-body-verification.md` §"Adversarial plan-body posture"): verifiers open and confirm every cited path / command and put the burden of proof on the plan. The gate threshold is majority-based for kinds `b`/`c`/`e`, but a single `DISAGREE` blocks on its own for the concrete, safety-critical kind `a` (path/symbol mismatch) — and `f` on `P-Req-*` items. `P-Var-*` items are excepted from the kind-`a` exception: a variation-point defect takes a majority. Rollback ordering (`d`) is advisory and never blocks the gate — a rollback is executed by a human, not by okstra's workers or verifiers. A majority also needs ≥2 participating votes, so a lone dissent whose peer returned a non-result does not block on a majority-gated kind (see that contract's §"Adversarial plan-body posture").
   - **Incremental re-verification scope (clarification re-runs):** when the lead's `okstra incremental-scope` decision is `mode == "incremental"` (procedure in `prompts/launch.template.md` §"Clarification Response Carried In"), workers re-analyze ONLY the stages listed in `reverify_stages` (the downstream closure of the impacted stages). Workers MUST NOT re-open, re-score, or re-judge any stage in `carry_stages` — those stages' prior plan-item verdicts are carried forward verbatim, and a worker never overwrites a carried verdict with its own judgement. When the decision is `mode == "full"` (the default), every stage is re-analyzed as usual.
-  - **Single incremental-scope decision:** the lead calls `okstra incremental-scope` once the inputs are complete, passing the answered `C-NNN` ids through `--answered-clarifications`, changed design-preparation IDs through `--prep-items`, and any lead-resolved stage numbers through `--impacted`; the CLI unions all three before applying the existing dependency closure and cutoff. The clarification ids are resolved to stages by the CLI from the prior report's own `planItems[].clarificationId` and `blocked C-NNN` coverage links — the lead does not map answers to stage numbers. An answer that changes the selected planning payload, Stage Map, or execution approach is not a local impact: pass `--full-reason`, which is the only structural path that still forces `mode == "full"`. A clarification id that traces to no stage returns `mode == "unresolved"` — ask the user for stage numbers and call again with `--impacted`; do not treat it as full and do not silently drop the id. Unknown PREP IDs or invalid `stageRefs` still return an explicit full decision instead of being guessed. When the wizard pin is `auto` and the CLI returns `mode == "incremental"`, keep it — do not upgrade to full. When the user pinned a scope at the wizard (`REVERIFY_SCOPE_MODE` / `REVERIFY_SCOPE_STAGES` in `prompts/launch.template.md` §"Clarification Response Carried In" step 0), that pin is an input to this same call — `full` supplies the `--full-reason`, and pinned stage numbers join `--impacted` — never a bypass of the CLI's closure and cutoff.
-  - **Stage-aware carry:** for an incremental decision, the report writer copies each `carry_stages` stage row unchanged into its narrative. After plan-item seeding, pass the decision's `carry_stages` and `reverify_stages` CSVs unchanged to `okstra incremental-carry --cur-narrative ... --state ... --out-state ...`. The helper rejects a changed or missing carried stage and copies prior `P-Step-*` / `P-Prep-*` verdicts for `carry_stages`, plus unchanged `P-Val-*` / `P-Req-*` / `P-Rb-*` rows whose extract `contentHash` still matches. It rewrites `dispatchQueue` and the sibling `plan-items-*.json` so the next prompt does not re-score a carried checklist row. Overlap, omissions, and canonical conflicts return `CarryError`. On that error, discard the partial state and run full re-verification.
+  - **Single incremental-scope decision:** the lead calls `okstra incremental-scope` once the inputs are complete, passing the answered `C-NNN` ids through `--answered-clarifications`, changed design-preparation IDs through `--prep-items`, and any lead-resolved stage numbers through `--impacted`; the CLI unions all three before applying the existing dependency closure and cutoff. The clarification ids are resolved to stages by the CLI from the prior report's own `planItems[].clarificationId` and `blocked C-NNN` coverage links — the lead does not map answers to stage numbers. An answer that changes the selected planning payload, Stage Map, or execution approach is not a local impact: pass `--full-reason`, which is the only structural path that still forces `mode == "full"`. A clarification id that traces to no stage returns `mode == "unresolved"` — ask the user for stage numbers and call again with `--impacted`; do not treat it as full and do not silently drop the id. **When this run only ADDS stages** — every prior stage is `done` and none of them is being re-opened — there are no stage numbers to give: pass `--carry-all-reason` instead. Pinning any prior stage as impacted makes `incremental-carry` demand it from the current snapshot, which no longer holds it (a `done` stage is not in this run's narrative), so that path has no answer that works. `--carry-all-reason` still applies the base-ref check: if the branch moved, the decision degrades to `full` because the prior stages are no longer "as written". Unknown PREP IDs or invalid `stageRefs` still return an explicit full decision instead of being guessed. When the wizard pin is `auto` and the CLI returns `mode == "incremental"`, keep it — do not upgrade to full. When the user pinned a scope at the wizard (`REVERIFY_SCOPE_MODE` / `REVERIFY_SCOPE_STAGES` in `prompts/launch.template.md` §"Clarification Response Carried In" step 0), that pin is an input to this same call — `full` supplies the `--full-reason`, `carry-all` supplies the `--carry-all-reason`, and pinned stage numbers join `--impacted` — never a bypass of the CLI's closure and cutoff.
+  - **Stage-aware carry:** for an incremental decision, `okstra incremental-scope` writes the decision to the record this run's manifest names in `incrementalDecisionPath`. The report writer's duty to copy each `carry_stages` stage row unchanged is not stated here — it is generated into that writer's own authoring contract from the same record, with this run's stage numbers in it (`okstra_ctl.report_synthesis_packet.ReportSynthesisPacket._carry_instructions`). After plan-item seeding, run `okstra incremental-carry --cur-narrative ... --state ... --out-state ...` against that record. The helper rejects a changed or missing carried stage and copies prior `P-Step-*` / `P-Prep-*` verdicts for `carry_stages`, plus unchanged `P-Val-*` / `P-Req-*` / `P-Rb-*` rows whose extract `contentHash` still matches. It rewrites `dispatchQueue` and the sibling `plan-items-*.json` so the next prompt does not re-score a carried checklist row. Overlap, omissions, and canonical conflicts return `CarryError`. On that error, discard the partial state and run full re-verification.
 {{INCLUDE:_coverage-critic.md}}
 - Non-goals:
   - code-level micro-optimization unless it changes the implementation approach
@@ -115,16 +118,17 @@ roles:
   - writing artifacts anywhere except `<PROJECT_ROOT>/.okstra/` — the run's `reports/` directory is the canonical location for this phase
 - Clarification request policy (phase-specific addenda — shared policy is in `_common-contract.md`):
 {{INCLUDE:_clarification-recommendation.md}}
-  - **Evidence note required inside `Statement`**: every clarification row includes `Evidence checked: <path:line>` or `Evidence checked: none — <human-only reason>` in the `Statement` cell. `none` is allowed ONLY when the row's nature is "only a human can answer this" (reporter intent, business priority, organisational decision). A row with `none` that *could* have been answered by the codebase is a defect of this phase, restated from the pre-planning rule above. **Enforced:** `validators/validate-run.py` `_validate_clarification_evidence_note` requires the note to exist and to be either a concrete `<path>:<line>` or the `none — <reason>` form. The check proves the note exists, not that the lookup happened — a false `none` is caught by review, but it is now an attributable claim rather than a silent omission.
+  - **Evidence note required inside `Statement`**: every clarification row includes `Evidence checked: <path:line>` or `Evidence checked: none — <human-only reason>` in the `Statement` cell. `none` is allowed ONLY when the row's nature is "only a human can answer this" (reporter intent, business priority, organisational decision). A row with `none` that *could* have been answered by the codebase is a defect of this phase, restated from the pre-planning rule above. **Not machine-checked.** The note's presence used to be checked and no longer is: a check on the literal `Evidence checked:` could only prove the string was typed, never that the lookup happened, and it became one of the most-fired failures in the validator without catching a single false `none`. The note is still required of you — it turns "nobody looked" into an attributable claim the §5.5.9 round and the user can both read — but the thing that catches a wrong one is review, which was always true.
   - **`Blocks=approval` admissibility (scope boundary).** Requirement Coverage has an admissibility test and Clarification rows did not, so anything at all could acquire approval-blocking force — a prose inconsistency inside a discarded plan detail blocked a plan with the same weight as a business decision. A row earns `Blocks=approval` only when, **absent an answer, the `implementation` run would produce wrong or unsafe code**. Apply the test to the row's consequence, not its topic:
     - admissible — the answer selects between behaviours the code must implement, fixes a requirement the plan would otherwise satisfy incorrectly, or resolves a safety/data-integrity question.
     - NOT admissible → use `Blocks=none` — QA-harness or tooling scope, report notation and wording, numbering or citation-range cleanup, anything outside the chosen realization, and anything the codebase answers (which the codebase-first rule already forbids raising at all). These belong in `## 5. Missing Information and Risks` or a Working Assumption; they are recorded, not gating.
     - A row you would answer with "the plan would still produce the same code either way" is by construction `Blocks=none`.
+  - **Backtrace at authoring (`Blocks=approval` rows).** Every approval blocker this run opens must be traceable to the plan by the time the report is assembled, through one of the two link shapes `okstra incremental-scope` reads: an activity citing the row's `C-NNN` in `clarificationRefs` and the affected `P-*` ids in `planItemIds` (assembly derives the plan items' `clarificationRefs` from exactly this — a row opened before plan items existed gets its backtrace on a later activity once the Stage Map is written), or the blocked requirement's coverage row carrying `blocked C-NNN`. An unlinked id cannot auto-narrow the answered re-run: `incremental-scope` returns `mode == "unresolved"` and the user must name stage numbers by hand. The plan-body promotion path (step 8) already records these links; this rule extends the same obligation to rows raised during planning itself — the observed unlinked rows were all of that class. A genuinely plan-wide blocker links the plan-wide items it judges (`P-Dir-1`, `P-Dep-*`); it still cannot narrow, and that is the honest answer for it. **Enforced (advisory):** `validators/validate-run.py` `_validate_approval_clarification_backtrace` fails an open approval blocker with no link or a link resolving to no stage.
 - Deliverable completeness contract (BLOCKING — the schema checks data keys, not heading strings):
   - For a selected-direction plan, the plan-ready schema branch requires `planningContract`, `outcome`, `selectedDirectionRef`, `directionRealization`, `stageMap`, `stages`, `designPreparation`, `dependencyMigrationRisk`, `validationChecklist`, `rollbackStrategy`, `requirementCoverage`, `coverageSummary`, `variationPointAnalysis`, and `planBodyVerification`. Its `direction-invalidated` branch contains no execution fields.
   - Each `stages[]` entry requires `stage`, `title`, `sliceValue`, `acceptance`, `carryIn`, `stepwiseExecution` (1–6 rows), `exitContract`, and `stageValidation`. Each `stageMap[]` row requires `stage`, `title`, `dependsOn`, `stepCount`, `exitContractSummary`.
   - Beyond the schema, `validators/validate-run.py` reads the same data.json for `_validate_planning_conformance_declared`, `_validate_end_state_coverage`, `_validate_requirement_provenance`, `_validate_stage_has_requirement`, and `_validate_plan_body_state_file`. These run for every planning report regardless of schema version.
-  - **Do not chase English heading substrings.** `PLANNING_REQUIRED_SECTIONS` and the Markdown scan in `collect_validation_errors` live inside `validate_phase_boundary`, which returns immediately when `schemaVersion == "2.0"` — they gate historical v1 Markdown only. The v2 full reading copy template renders nine headings and serialises the plan as JSON beneath them, so those substrings cannot appear, and a report is not defective for lacking them.
+  - **Do not chase English heading substrings.** The Markdown heading scan (`collect_validation_errors`) is the fallback branch of `collect_plan_errors` in `validators/validate-implementation-plan-stages.py` and runs only for a report carrying no `implementationPlanning` data — historical v1 Markdown. A v2 report is validated from its data (`collect_data_validation_errors`, same file). The v2 full reading copy template renders nine headings and serialises the plan as JSON beneath them, so the v1 heading substrings cannot appear, and a report is not defective for lacking them.
 - Per-stage vertical slice and TDD contract (BLOCKING — enforced on the data, not on heading tokens):
   - Every stage declares `sliceValue`, `acceptance`, and the three cases `testCaseSuccess` / `testCaseBoundary` / `testCaseFailure` — happy path, edge/boundary input, failure input. **Enforced:** the v2 schema's `if not tddExemption then require` conditional on `ImplementationPlanStage`.
   - The first `stepwiseExecution` row's `action` starts with `RED:` and its `expected` reads FAIL; some later row's `action` starts with `GREEN:` and its `expected` reads PASS. **Enforced (S10c):** `collect_data_validation_errors` in `validators/validate-implementation-plan-stages.py`, run from `validate-run.py` `_append_stage_data_failures`.
@@ -136,7 +140,7 @@ roles:
   - 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-v2.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. Keep it to one sentence — there is no validator on its length, so the split between `summary` and `details` is the thing to get right, not a character count.
         - `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.`
@@ -169,7 +173,7 @@ roles:
       - **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 stands alone as a step's assertion: `okstra worktree-status --check-clean`. Validator S13 rejects the bare form. Do not add a `git tag stage-<N>-exit` to the step — okstra writes that tag itself when it settles the stage, at the commit the carry evidence records, and a step that tags mid-stage puts it on an earlier commit.
       - **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,...])` — declare that a Tier3 verification script will prove 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. This phase emits the line and the `requires` set only. Do NOT write `<task_root>/qa/scripts/stage-<N>.*` and do NOT add a `runCommand` or `conformance-manifest.json` entry here — the matching `implementation` stage run creates the script file and the manifest `runCommand`. A plan that declares tests with no script file on disk is valid at this gate.
+      - `Conformance tests: stage-<N> — <task_root>/qa/scripts/stage-<N>.<ext> (requires=[db|io|http|external,...])` — declare that a Tier3 verification script will prove 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. This phase emits the line and the `requires` set only. Do NOT write `<task_root>/qa/scripts/stage-<N>.*` and do NOT add a `runCommand` or `conformance-manifest.json` entry here — the matching `implementation` stage run creates the script file and the manifest `runCommand`. A plan that declares tests with no script file on disk is valid at this gate. The data.json `conformanceTests` value carries only the remainder after the `Conformance tests: stage-<N> — ` prefix — never the `stage-<N> — ` label itself (report assembly strips a leftover label at publication, and the implementation entry gate rejects one).
       - `Conformance exemption: <reason>` — only for stages that touch no db/io/http/external surface, or where unit tests fully cover the increment. Exemption stays a planning declaration; do not move it to implementation. (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.)
       - **External QA outcome guideline:** after satisfying the S11 declaration above, a line whose `requires` contains
         `db`, `http`, or `external` should name those capabilities here so the later `runCommand` can be written against them.
@@ -180,8 +184,9 @@ roles:
       Layout split (the implementer writes these, not this phase): executable scripts (conformance + any real-IO test) live under `<task_root>/qa/scripts/`; data sidecars (`conformance-manifest.json`, `result-*.json`) stay at the `qa/` root. This declaration is enforced at four layers: `validators/validate-implementation-plan-stages.py` check **S11** forces every stage to carry one of the two lines; at the planning boundary `validators/validate-run.py` `_validate_planning_conformance_declared` accepts a well-formed `Conformance tests:` line even when the script file and manifest entry are absent (malformed `requires` still fails); the matching `implementation` stage run that inherited `Conformance tests:` fails closed when the script file is missing (`_validate_conformance`); and the manifest JSON structure — including each entry's `script` living under `qa/scripts/` and a `runCommand` that does not change cwd — is enforced by `validate_conformance_manifest` when the implementer writes the entry.
     - `### Stage Exit Contract` — predicted added/modified files, newly exposed identifiers/types/endpoints, downstream-usable resources.
     - `### Stage Validation` — pre / mid / post exact commands or observable outcomes for this stage only.
+      - **Run-executable only (BLOCKING).** A `validationChecklist` row that carries `stageRefs` gates that stage's carry, so it MUST be executable by the implementation run itself — no deployment, no manual walk-through, no observation "by hand", no credentials the run does not hold. The implementation phase forbids deploys and holds no deploy credentials, so such a row can never pass and blocks a stage with zero code defects (observed: dev-10341 VC-013/VC-014). Manual or deployed-environment verification belongs in the brief's `External Gates` and final-verification's user-owned external QA — record it there without `stageRefs`. **Enforced:** `okstra_ctl.implementation_direction.validate_selected_direction_plan` (`_stage_validation_executability_errors`) rejects stage-gating rows whose observation text requires a manual or deployed-environment step.
       - **Dependency precondition (stages that run the project toolchain).** The planning worktree is created without installed dependencies, so a stage whose steps call `npm` / `yarn` / `pytest` / `cargo` / equivalent cannot have those commands succeed at plan time — they exit `127`, not RED/GREEN. Declare the install **once** as a `phase: pre` row in `### Validation Checklist` (e.g. `VC-008 — the implementation run's stage worktree has workspace dependencies installed`) and have every such stage's `Stage Validation` cite that `VC-NNN` in its `pre:` line. Do not repeat the install commands per stage, and do not silently assume the tooling is present: a plan that never states the precondition produces steps whose commands never resolve, which the §5.5.9 round then reports as unverifiable. **Enforced (advisory):** `validators/validate-run.py` `_detect_missing_dependency_precondition` warns when a toolchain-invoking stage cites no `VC-NNN`, or cites one that is not `phase: pre`. Whether the cited row genuinely covers dependencies is a §5.5.9 judgement, not a machine check. Detection uses the token allowlist in `scripts/okstra_ctl/build_tools.py`; a project overrides it with `buildToolTokens` in `.okstra/project.json`.
-  - **Vertical-slice-first partition rule (1st-class):** the grouping anchor is a **thin end-to-end vertical slice** — one stage delivers a single user-observable increment, crossing whatever layers are needed (data → service → API → UI) to make that one increment work. File/module proximity is demoted to the **intra-slice grouping rule**: within a slice, keep steps touching the same file/directory/module together so the diff, PR, and rollback unit stay cohesive. **Horizontal layer-splitting is forbidden** — never carve "the DB layer" into one stage and "the service layer" into the next; that produces stages that ship no standalone user value. A stage is split ONLY when (a) a real `depends-on` data/contract dependency exists, (b) effective steps would exceed 8, or (c) it is a distinct vertical slice (a different user-value increment). Maximising the number of parallel stages is NOT a reason to split — parallelism is an emergent property of independent stages, never a partitioning goal.
+  - **Vertical-slice-first partition rule (1st-class):** the grouping anchor is a **thin end-to-end vertical slice** — one stage delivers a single user-observable increment, crossing whatever layers are needed (data → service → API → UI) to make that one increment work. File/module proximity is demoted to the **intra-slice grouping rule**: within a slice, keep steps touching the same file/directory/module together so the diff, PR, and rollback unit stay cohesive. **Horizontal layer-splitting is forbidden** — never carve "the DB layer" into one stage and "the service layer" into the next; that produces stages that ship no standalone user value. A stage is split ONLY when (a) a real `depends-on` data/contract dependency exists, (b) effective steps would exceed 8, or (c) it is a distinct vertical slice (a different user-value increment). Maximising the number of parallel stages is NOT a reason to split — parallelism is an emergent property of independent stages, never a partitioning goal. **Config propagation is not a slice (BLOCKING):** a dependent stage whose planned paths are all configuration/CI files (`Dockerfile`, `docker-compose*`, `*.yml` / `*.yaml`, `.env*`) merely propagates a value another stage introduced — it ships no user-value increment of its own. Fold that work into the introducing stage as its own step(s) and separate it by **commits**, never by stages: each extra stage costs a full implementation run (executor + verifiers, 30min+ observed) for a few config lines. A first stage with no dependency is exempt — a task whose whole scope is configuration is legitimate. **Enforced:** `okstra_ctl.implementation_direction.validate_selected_direction_plan` (`_micro_stage_fold_errors`).
   - **Project-boundary partition rule (hard boundary):** a *project* boundary is either (a) a different repository / `PROJECT_ROOT`, or (b) a different top-level independently-deployable module within one repo. A stage maps to a single worktree on one repo/branch, so **no stage may contain edits belonging to more than one project** — this is a hard split that overrides the ≤8-step merging allowance; never co-locate two projects' changes in one stage to save a stage. Two cases:
     - **Same repo, different modules** — put each project/module's increment in its own stage. Their file sets are disjoint, so they default to `depends-on (none)` and run in parallel; add a `depends-on` link ONLY when a real cross-module contract / shared-schema / deploy-order dependency exists.
     - **Different repos** — a single okstra task **cannot** span repos: every stage worktree is a `git worktree add` in one repo's main checkout (one `<project-id>`), the run-index / manifests / registry are keyed to that one project, and the edit allowlist only covers that project's tree plus `~/.okstra/worktrees/**`. This is a structural limit, not a style preference. Therefore cross-repo work MUST be split into **a separate okstra run per repo** — never modelled as stages of one task. State, in the Stage Map `Cross-project parallelism:` line, whether those per-repo runs can proceed in parallel. To avoid re-deriving shared analysis, the second repo's run should consume the first run's relevant plan/decision artifacts as brief Source Material (see the cross-project dependency rows below).
@@ -190,7 +195,7 @@ roles:
   - **Cross-project dependency rows (`crossProjectDependencies` array — replaces the old `## Cross-Repo Carry` appendix):** a dependency on another project (a different repo / a different top-level independently-deployable module / a published package) is recorded not as the freeform `## Cross-Repo Carry` appendix but as an **`XP-NNN` row of the structured field `crossProjectDependencies`**. Put one XP row per project dependency and fill in whichever `direction` applies (rendered as `### Cross-Project Dependencies` §5.4; a single-project plan uses an empty array). The row fields replace the old three subsections with — `requiredWork` (the concrete work the other side must build) / `verificationSignal` (the signal this run will observe) / `linkedWork` (the stage/step of this plan that is blocked until the signal is met) / `howToStart` (the exact handoff in the other repo).
     - `direction: upstream-precondition` — this run **waits on the other side's prerequisite work (precondition required)**: `requiredWork` = the concrete work the other side must implement first, `verificationSignal` = the signal this run must observe before proceeding (PR merged / endpoint live / version published), `linkedWork` = the stage/step of this plan that is blocked until the signal is met, `howToStart` = in the other repo, `okstra-brief-gen` (**cite this report's absolute path as Source Material** — the only permitted cross-`<PROJECT_ROOT>` read) → `okstra-run`.
     - `direction: downstream-carry` — this run **produces what the other side will consume (the existing carry)**: `requiredWork` = the self-contained B-portion the other side will implement next (from the other side's perspective, a new `R-NNN`, proposed stages, and affected files), `verificationSignal` = the (this-run-delivered) signal the other side confirms before proceeding, `linkedWork` = the stage/step of this plan that delivers that signal, `howToStart` is the same as upstream. Do not hand over this run's already-`done` stages as if they were the other side's stages — include only the portion the other side still has to build.
-    - **A cross-repo dependency cannot be expressed with `depends-on`:** that gate only resolves commits inside a single repo's git graph (`scripts/okstra_ctl/run.py` `_resolve_stage_base_commit`), so it cannot point at a commit in another repo. Cross-repo work is split into a separate okstra run + XP row rather than a stage (the Different-repos rule). The other run is structurally independent, so it does not automatically recognise this run's completed stages as `done` (nor should it — that is this repo's work); the XP row is only a narrative input that seeds the other side's planning. This run does not write to the other repo's tree or its `.okstra/` (it emits only this report's XP rows). The old "Recognition caveat" wording has been moved into a render note (i18n `crossProjectRecognitionNote`) and is emitted automatically in the `### Cross-Project Dependencies` section.
+    - **A cross-repo dependency cannot be expressed with `depends-on`:** that gate only resolves commits inside a single repo's git graph (`scripts/okstra_ctl/stage_targets.py` `resolve_stage_base_commit`), so it cannot point at a commit in another repo. Cross-repo work is split into a separate okstra run + XP row rather than a stage (the Different-repos rule). The other run is structurally independent, so it does not automatically recognise this run's completed stages as `done` (nor should it — that is this repo's work); the XP row is only a narrative input that seeds the other side's planning. This run does not write to the other repo's tree or its `.okstra/` (it emits only this report's XP rows). The old "Recognition caveat" wording has been moved into a render note (i18n `crossProjectRecognitionNote`) and is emitted automatically in the `### Cross-Project Dependencies` section.
   - **Stage exit contract is the carry surface:** keep it as narrow as possible. Wider surface = more downstream coupling.
   - dependency / migration risk assessment (ordering constraints, data backfills, feature-flag prerequisites, repo-internal sequencing)
   - **Cross-Project Dependencies (conditionally required):** when the plan depends on work in another project / repo / published package, add (a) a `kind: cross-project` DM row to `dependencyMigrationRisk`, and (b) a matching `XP-NNN` row to `crossProjectDependencies`. An upstream-precondition row must have concrete `requiredWork` / `verificationSignal` / `howToStart` — `validators/validate-run.py` enforces that a DM `cross-project` ⇒ at least one `direction: upstream-precondition` XP row, and the schema enforces non-empty row fields. A cross-project dependency is recorded as this structured precondition, not as a soft Recommended Next Step. A single-project plan uses an empty array.

package/runtime/prompts/profiles/implementation.md

@@ -35,7 +35,8 @@ roles:
   - 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 **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.
+  - Wherever this profile mentions the `Executor`, it refers to the role bound above. Every roster worker **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). Verifier dispatches remain strictly read-only.
+  - **Every roster slot names its role.** The executor holds its own roster slot. A worker ID is always `<provider>-<role>` — `claude-implementer` for the executor, `claude-verifier` for a verifier, `antigravity-verifier` even when antigravity fills only that one slot — and each slot carries its own `initial/<id>` invocation assignment. A repeated `(provider, role)` pair (two Claude verifiers on different models) numbers the later ones: `claude-verifier-2`. Read every worker ID off the roster; never assume it equals the provider name. Both roster rows may carry the same model — reusing the executor's model behind an independent verifier session is allowed; what is not allowed is two verifiers on the same model. **Enforcement:** `scripts/okstra_ctl/run.py` `_canonical_worker_id` issues the ID; `validators/validate-run.py` refuses a `duplicate worker role detected` roster.
   - **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}}
@@ -45,7 +46,7 @@ roles:
   - The `--approve` flag is meaningful ONLY with `--task-type implementation` and `--approved-plan <path>`; any other use raises `PrepareError`. Idempotent — re-running with `approved: true` already set does not write again.
   - determine the plan branch from the sibling data.json `implementationPlanning.planningContract`. For `selected-direction`, the authoritative scope is `selectedDirectionRef`, its validated snapshot, `directionRealization`, and the selected stage; the plan MUST be `plan-ready` with exact coverage, and both an `implementation-option:` frontmatter field and `--implementation-option` are forbidden. A direction change routes to `implementation-option-selection`; a detail-only plan correction routes to `implementation-planning`.
   - for the legacy candidate-comparison branch, the authoritative scope is the Option Candidate named by the report record `frontmatter.implementationOption` field. **If that field is empty, fall back to the plan's `Recommended Option`** (this is a soft fallback, not a hard block). The chosen option's step list becomes the authoritative scope. Any deviation MUST be justified in the final report AND routed to a new `implementation-planning` run; never silently expand scope. If the chosen option name does not match any heading under `Option Candidates`, record it as a deviation.
-- Stage worktree (provisioned by `okstra-ctl` at this implementation run's prep time):
+- Stage worktree (provisioned by Okstra at this implementation run's prep time):
   - Status: `{{EXECUTOR_WORKTREE_STATUS}}` (one of: `created` | `reused` | `skipped-in-worktree` | `skipped-not-git`)
   - Working tree path: `{{EXECUTOR_WORKTREE_PATH}}` — when status is `created` or `reused`, this is this run's isolated stage worktree rooted at `~/.okstra/worktrees/<project>/<task-group>/<task-id>/stage-<N>/`. When skipped, this is the caller's `project_root`.
   - Branch: `{{EXECUTOR_WORKTREE_BRANCH}}` — empty when status is `skipped-*`. Branch name = `<work-category-namespace>/<task-id-segment>-s<N>` (e.g. `feature/dev-9436-s2`), globally unique via `~/.okstra/worktrees/registry.json`.

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

@@ -8,7 +8,7 @@ roles:
     max: 5
     duty: discovery-worker
   - role: critic
-    min: 1
+    min: 0
     recommended: 1
     max: 1
     duty: scope-critic
@@ -99,6 +99,7 @@ roles:
   - next recommended phase and safe resume guidance
   - canonical-term resolution for every `terminology:*` brief item as `<term> = <definition>`, plus whether `<PROJECT_ROOT>/.okstra/glossary.md` should be updated
   - one `endStateCoverage` row per brief end-state id (`EB-NNN` / `PB-NNN` / `EO-NNN`). `coveredBy` names the routing decision, the fan-out unit id, or the `C-NNN` clarification that accounts for it. This phase does NOT author a goal of its own — the brief already pinned the end state, and restating it here is how four phases end up with four different targets. **Enforced:** `validators/validate-run.py` `_validate_end_state_coverage`.
+  - a `blocked` `endStateCoverage` row MUST carry `blockedBy` — `kind` one of `clarification` / `finding` / `execution` / `upstream` / `not-observed`, plus a `ref` for the first two. `blocked` on its own carries all five situations at once, and only `clarification` is something a person can answer; without the field nothing downstream can tell "the reporter must decide" from "the server would not boot". A `clarification` ref must be a `C-NNN` row of this report or one carried in — the same row the approval-decision ledger holds, not an id you only named in prose. A `finding` ref is required but not resolved: it legitimately points at the approved plan or an upstream report (`VC-003`, `CA-001`). **Enforced:** `validators/validate-run.py` `_validate_end_state_blocked_by`.
 - Report assembly instructions:
   - write canonical-term resolutions in a new `Domain Alignment` subsection of the final report; actual glossary writes happen via `okstra-brief-gen` Step 4.5 on a subsequent run
 - Clarification request policy (phase-specific addenda — shared policy is in `_common-contract.md`):

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

@@ -101,6 +101,13 @@
       "errors": {
         "none": "같은 task에서 선택할 implementation-option-selection 최종 보고서를 찾을 수 없습니다.",
         "unknown": "목록에 없는 selected-direction 경로입니다: {value}"
+      },
+      "labels": {
+        "options": "{path} — 후보 {ids}",
+        "no_options": "{path} — 후보 없음 (이 리포트로는 계획을 열 수 없습니다)"
+      },
+      "echo_variants": {
+        "cleared_clarification": "selected-direction: {value} (새 계획이므로 clarification-response 는 비웁니다 — 답변 사이드카는 이 방향과 함께 전달됩니다)"
       }
     },
     "brief_keep": {
@@ -410,23 +417,32 @@
     },
     "reverify_scope_pick": {
       "label": "재검증 범위를 어떻게 할까요? (답변한 항목이 모두 직전 리포트의 stage 에 연결돼 있어 범위를 좁힐 수 있는 상태입니다 — 최종 확정은 run 시점 base-ref 비교)",
-      "label_unlinked": "답변한 항목 중 직전 리포트의 stage 에 연결되지 않은 것이 있습니다. 다시 볼 stage 번호를 지정하거나 전체 재검증을 고르세요. 연결되지 않은 id 가 재실행 전체를 full 로 만들지는 않습니다.",
+      "label_unlinked": "답변한 항목 중 직전 리포트의 stage 에 연결되지 않은 것이 있습니다. 다시 볼 stage 번호를 지정하거나, 이번 재실행이 stage 를 추가만 한다면 전부 이월을, 아니면 전체 재검증을 고르세요. 연결되지 않은 id 가 재실행 전체를 full 로 만들지는 않습니다.",
       "echo_template": "reverify-scope: {value}",
       "options": {
         "auto": "관련 stage 만 (추천) — 답변이 닿는 stage 와 그 하위만 다시 검증하고 나머지는 직전 판정을 그대로 이월",
         "full": "전체 재검증 — stage 전부를 처음부터 다시 교차검증 (시간은 더 들지만 계획 형태가 바뀌었을 때 안전)",
-        "__free_input__": "직접 입력 — 다시 볼 stage 번호를 지정"
+        "__free_input__": "직접 입력 — 다시 볼 stage 번호를 지정",
+        "carry-all": "재검증 없이 전부 이월 — 직전 stage 는 모두 완료됐고 이번 재실행은 stage 를 추가만 합니다. 기존 stage 는 직전 판정을 그대로 가져오고 새 stage 만 봅니다 (브랜치가 움직였으면 자동으로 전체 재검증으로 내려갑니다)",
+        "full_recommended": "전체 재검증 (추천) — 되짚기가 stage 를 못 냈으므로 좁힐 근거가 없습니다. 시간은 더 들지만 답변의 영향 범위를 놓치지 않습니다"
       },
       "echo_suffixes": {
         "auto": "reverify-scope: auto (좁힐 수 있으면 좁힘)",
-        "full": "reverify-scope: full (전체 재검증)"
+        "full": "reverify-scope: full (전체 재검증)",
+        "carry-all": "reverify-scope: carry-all (재검증 없이 전부 이월)"
       },
       "errors": {
-        "unlinked_auto": "직전 리포트의 stage 에 연결되지 않은 답변이 있어 자동 판정을 쓸 수 없습니다: {ids}. stage 번호를 지정하거나 전체 재검증을 고르세요."
+        "unlinked_auto": "직전 리포트의 stage 에 연결되지 않은 답변이 있어 자동 판정을 쓸 수 없습니다: {ids}. stage 번호를 지정하거나 전체 재검증을 고르세요.",
+        "no_answers_auto": "직전 리포트에 답변된 clarification 이 없어 자동 판정을 쓸 수 없습니다 — 되짚을 답이 없으면 자동은 전체 재검증으로만 떨어집니다. 다시 볼 stage 번호를 지정하거나 전체 재검증을 고르세요."
+      },
+      "label_no_answers": "직전 리포트에 답변된 clarification 이 없어 자동으로 좁힐 근거가 없습니다. 이번 재실행에서 다시 볼 stage 번호를 직접 지정하거나 전체 재검증을 고르세요 — 지정한 번호는 그대로 impacted 로 들어갑니다. 최종 확정은 run 시점 base-ref 비교.",
+      "labels": {
+        "unlinked_ids": " 연결되지 않은 항목: {ids}.",
+        "no_basis": " 무엇을 다시 볼지는 이번 재실행의 목적에만 달려 있어, 이 run 이 추천할 근거는 없습니다."
       }
     },
     "reverify_scope_stages": {
-      "label": "다시 볼 stage 번호를 쉼표로 입력하세요 (예: 2,3 — 직전 리포트 Stage Map 에 있는 번호만 유효. 지정한 stage 의 하위 stage 까지 함께 재검증됩니다. 빈 줄이면 자동 판정)",
+      "label": "다시 볼 stage 번호를 쉼표로 입력하세요 (예: 2,3 — 직전 리포트 Stage Map 에 있는 번호만 유효. 지정한 stage 의 하위 stage 까지 함께 재검증됩니다. 빈 줄은 되짚을 답이 있을 때만 자동 판정으로 떨어집니다)",
       "echo_template": "reverify-scope: stage {value}",
       "echo_suffixes": {
         "auto": "reverify-scope: auto (좁힐 수 있으면 좁힘)"
@@ -435,7 +451,8 @@
         "not_a_number": "stage 번호는 정수여야 합니다: {token}",
         "unknown_stage": "직전 리포트의 Stage Map 에 없는 stage 입니다: {stages} (Stage Map 의 번호: {known})",
         "no_stage_map": "직전 리포트에서 Stage Map 을 읽을 수 없어 stage 번호를 검증할 수 없습니다: {reason}",
-        "unlinked_empty": "직전 리포트의 stage 에 연결되지 않은 답변이 있어 빈 입력(자동)을 쓸 수 없습니다: {ids}. stage 번호를 입력하세요."
+        "unlinked_empty": "직전 리포트의 stage 에 연결되지 않은 답변이 있어 빈 입력(자동)을 쓸 수 없습니다: {ids}. stage 번호를 입력하세요.",
+        "no_answers_empty": "직전 리포트에 답변된 clarification 이 없어 빈 입력(자동)을 쓸 수 없습니다. 다시 볼 stage 번호를 입력하세요."
       }
     },
     "pr_template_pick": {
@@ -497,9 +514,12 @@
       "label": "선택 역할 {role} 을(를) 이번 run 에 추가할까요? (최대 {maximum}개)",
       "echo_template": "role-add: {value}",
       "options": {
-        "skip": "추가 안 함{default_suffix}",
+        "skip": "추가 안 함{skip_warning}{default_suffix}",
         "add": "{count}개 추가{default_suffix}",
-        "default_suffix": " (기본)"
+        "default_suffix": " (기본)",
+        "skip_warnings": {
+          "critic": " — 차단 kind 에서 분석자 표가 1대1 동수면 가를 주체가 없어, 그 항목마다 승인 결정과 Blocks=approval clarification 행이 열립니다 (자동 tie-break 대신 사용자 질문. phase 는 계속 진행됩니다)"
+        }
       }
     },
     "role_model": {
@@ -636,6 +656,7 @@
     "reverify_scope_unlinked": "  reverify-scope: stage 번호 필요 — {ids} 이(가) 직전 리포트의 어느 stage 에도 연결되지 않음 (자동 판정 불가; full 로 강제되지는 않음)",
     "reverify_scope_full": "  reverify-scope: full 예상 — {reason}\n                  (좁히지 못하는 것은 재검증 범위이지 답변이 아닙니다 — 답변은 모두 carry-in 되어 반영되고, 대신 stage 전체를 다시 검증합니다)",
     "reverify_scope_user_full": "  reverify-scope: full (사용자 지정 — 전체 재검증)",
+    "reverify_scope_user_carry_all": "  reverify-scope: carry-all (사용자 지정 — 재검증 없이 직전 판정 전부 이월, 새 stage 만 검증; 브랜치가 움직였으면 full 로 내려감)",
     "reverify_scope_user_stages": "  reverify-scope: stage {stages} 재검증 지정 (사용자 지정 — 하위 stage 포함, 나머지는 직전 판정 이월)",
     "stage_whole_task": "전체 task",
     "handoff_scope_whole_task": "전체 task (whole-task 검증 기반)",

package/runtime/python/okstra_ctl/__init__.py

@@ -1,4 +1,4 @@
-"""okstra-ctl 와 okstra-central 가 공유하는 순수 헬퍼 패키지.
+"""okstra 런타임이 공유하는 순수 헬퍼 패키지.
 
 기존 단일 모듈 `okstra_ctl_lib` 를 도메인 단위 서브모듈로 분해한 결과이며,
 모든 public 심볼을 패키지 루트에서 재노출한다. 호출자는
@@ -8,15 +8,13 @@ from __future__ import annotations
 
 # Public API — keep import order topological (leaves first) to avoid surprises.
 from .ids import (
-    build_container_session_name,
     build_run_id,
     parse_run_id,
-    run_id_to_session_name,
     slugify_task_segment,
     _escape_segment_for_join,
     _safe_fs_segment,
 )
-from .locks import central_lock, task_lock_filename
+from .locks import central_lock
 from .invocation import invocation_path, save_invocation, load_invocation
 from .jsonl import (
     append_jsonl,
@@ -52,23 +50,17 @@ from .reconcile import (
     normalize_central_status,
     normalize_reconciled_report_status,
     reconcile_active,
+    reconcile_home,
     reconcile_recent,
+    settle_run_row,
 )
 from .listing import (
     _parse_since,
     absolute_final_report_path,
-    find_row_by_run_id,
-    format_projects_table,
-    format_runs_table,
-    format_show,
-    list_projects,
     list_runs,
 )
-from .resolver import ResolveError, _all_run_ids, resolve_last, resolve_run_id
 from .run_index_row import read_run_index
 from .sequence import predict_next_run_seq
-from .tmux import _shell_quote, build_tmux_command
-from .batch import expand_selectors, make_batch_id, write_batch_meta
 from .backfill import (
     _apply_backfill_meta,
     backfill_project,
@@ -86,28 +78,18 @@ from .run_context import (
 
 __all__ = [
     "DEFAULT_ABORT_AFTER_SECONDS",
-    "ResolveError",
     "absolute_final_report_path",
     "append_jsonl",
     "backfill_project",
-    "build_container_session_name",
     "build_run_id",
-    "build_tmux_command",
     "central_lock",
     "compute_and_write_run_context",
     "compute_run_paths",
     "discover_project_roots",
-    "expand_selectors",
-    "find_row_by_run_id",
-    "format_projects_table",
-    "format_runs_table",
-    "format_show",
     "invocation_path",
-    "list_projects",
     "list_runs",
     "load_invocation",
     "load_project_meta",
-    "make_batch_id",
     "mark_backfilled",
     "next_run_seq",
     "normalize_central_status",
@@ -119,21 +101,18 @@ __all__ = [
     "read_run_context",
     "read_run_inputs",
     "reconcile_active",
+    "reconcile_home",
     "reconcile_recent",
+    "settle_run_row",
     "record_start",
     "remove_jsonl_row",
     "remove_reservation",
     "reserve_run_in_active",
-    "resolve_last",
-    "resolve_run_id",
     "resolve_under_root",
     "rotate_recent_if_needed",
-    "run_id_to_session_name",
     "save_invocation",
     "slugify_task_segment",
-    "task_lock_filename",
     "task_mutex",
     "upsert_project_meta",
-    "write_batch_meta",
     "write_run_inputs",
 ]

package/runtime/python/okstra_ctl/adapters/hosts/claude-code/relay.md

@@ -141,7 +141,7 @@ For a `host-text` mapping, render each numbered item as its option label followe
 | `read_artifacts` | Use the host file-read primitive and preserve the core contract's read order. |
 | `write_artifact` | Use the host file-write primitive only for paths authorized by the active lifecycle phase. |
 | `prompt_user` | Use `AskUserQuestion` for approvals and clarifications that fit `nativeLimits`. Do not print a numbered list in chat while that tool is available. Do not infer an answer from silence. |
-| `dispatch_worker` | First verify the materialized invocation metadata. Dispatch `runner=native-session` through `Agent(name: "<role>", run_in_background: true)` without `team_name`, passing the verified final prompt and `hostModelValue`. Dispatch `runner=cli-wrapper` with the deterministic shell command `okstra worker-dispatch --project-root <root> --run-manifest <path> --workers <ids>`; never wrap that process in another `Agent(...)` call. **Not in a cmux run:** when the run manifest's `terminalBackend` is `cmux-pane`, `prompts/lead/adapters/cmux.md` overrides this row. |
+| `dispatch_worker` | First verify the materialized invocation metadata. Dispatch `runner=native-session` through `Agent(name: "<role>", run_in_background: true)` without `team_name`, with `hostModelValue` and a summon message only — never the prompt body. The summon is exactly: `Your complete dispatch instructions are the document at <absolute promptPath>. Read that document in full before doing anything else — every line, continuing with offset until end of file — then execute it exactly. Do not act on this message alone.` The verified `promptPath` is already persisted and metadata-verified; inlining its body into the `Agent` call duplicates it in the lead context and lets the two copies drift. Dispatch `runner=cli-wrapper` with the deterministic shell command `okstra worker-dispatch --project-root <root> --run-manifest <path> --workers <ids>`; never wrap that process in another `Agent(...)` call. **Not in a cmux run:** when the run manifest's `terminalBackend` is `cmux-pane`, `prompts/lead/adapters/cmux.md` overrides this row. |
 | `await_workers` | Arm one background shell poll for the pending Result Paths; the spawn acknowledgement is not completion. |
 | `redispatch_worker` | Materialize and verify a fresh invocation, then use a fresh native `Agent(...)` session or `okstra worker-dispatch` attempt according to the persisted runner. |
 | `shutdown_workers` | For each confirmed-complete worker selected for cleanup, send `SendMessage(to: <name>, message: { type: "shutdown_request" })` to idle the roster member **and** call `TaskStop(task_id: "<name>")` to stop its background task. Both are required; neither subsumes the other. |
@@ -206,11 +206,10 @@ For a `host-text` mapping, render each numbered item as its option label followe
 - At run start, record `teamName` as the audit label in team-state and populate `lead.sessionId`; the session transcript lives under `~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl`. You do NOT write `teamCreate`: `okstra team dispatch` records the implicit-team marker (`{ attempted: false, status: "implicit" }`) itself, on every dispatch path, because v2.1.178 made that value a constant rather than a judgment. The one marker that IS yours is the concurrent-run decision — a concurrent run records `teamCreate: { attempted: false, status: "skipped", reason: "concurrent-run" }` **before** the first dispatch, and dispatch then leaves it alone.
 - Collect and persist token usage before any live-roster cleanup, including cleanup between batches and the run-end shutdown sequence.
 - Before each new worker batch (and before the next phase's render-bundle), close the panes of the dispatches that finished in the prior round, in two passes. First count: `okstra team reclaim --project-root "<PROJECT_ROOT>" --run-manifest "<RUN_MANIFEST_PATH>" --dry-run` closes nothing and prints one `<paneId>\t<kind>` line per pane it would close — count those lines as `<n>`. Then run the same command **without** `--dry-run` to close them, and emit the neutral contract's `PROGRESS: phase-batch-cleanup panes=<n>` checkpoint with that count. Call both passes after collecting that round's results and token usage and before the next dispatch. The command reads each dispatch's recorded status, so an in-progress worker keeps its pane whichever moment you call it — you do not scope the pass by hand. It closes only the panes okstra opened and recorded; a pane the harness opened for itself carries no recorded id and is not okstra's to close. A `cli-wrapper` run holds no pane at all, so `<n>` is `0` — still emit the checkpoint.
-- Reclaiming a pane does not stop the worker's background task. Every `dispatch_worker` Agent runs with `run_in_background: true`, so a worker whose result is already collected stays a live background task for the rest of the session — that residue is what fills the harness's exit-time `Background work is running` list. At the same batch boundary, right after the pane reclaim, call `TaskStop(task_id: "<name>")` once per worker of the completed batch, passing the exact `name` used at dispatch (`<workerId>-worker`, `<workerId>-worker-reverify-r<N>`, `<provider>-worker-critic`, `report-writer`). Stop only workers whose results were already collected — never an in-flight worker, never the lead, and keep `report-writer` while it is in flight, matching the pane pass's `--keep report-writer-worker`. `TaskStop` on an already-finished task is a no-op; treat a failure as benign, record nothing, and continue the boundary. This runs in a non-tmux session too, where the pane passes no-op but the background tasks still exist.
+- Reclaiming a pane does not stop the worker's background task. Every `dispatch_worker` Agent runs with `run_in_background: true`, so a worker whose result is already collected stays a live background task for the rest of the session — that residue is what fills the harness's exit-time `Background work is running` list. At the same batch boundary, right after the pane reclaim, call `TaskStop(task_id: "<name>")` once per worker of the completed batch, passing the exact `name` used at dispatch (`<workerId>-worker`, `<workerId>-worker-reverify-r<N>`, `<provider>-worker-critic`, `report-writer`). Stop only workers whose results were already collected — never an in-flight worker, never the lead, and keep `report-writer` while it is in flight, matching the pane pass's `--keep report-writer-worker`. `TaskStop` on an already-finished task is a no-op; treat a failure as benign, record nothing, and continue the boundary. This runs even when the pane passes found nothing to close, because the background tasks exist either way.
 - Before any `prompt_user`/`AskUserQuestion` that follows worker dispatch — an approval, clarification, or decision gate — run the same two passes used at a round boundary: `okstra team reclaim … --dry-run` to count `<n>`, then the same command without `--dry-run` to close, and emit `PROGRESS: phase-gate-cleanup panes=<n>`. Then `TaskStop(task_id: "<name>")` each completed worker, exactly as at a batch boundary. A bare `TaskStop` idles the roster task and closes no pane, so it is never cleanup on its own. This keeps the user from being shown a gate while finished worker panes are still open. After that cleanup, follow the lead contract "User confirmation before an approval blocker": read cited plan items, worker findings, and files before asking, and ask in the user's language with each option's outcome.
 - After batch cleanup, record the current live session generation with `okstra token-usage "<TEAM_STATE_PATH>" --record-observed-session --project-root "<PROJECT_ROOT>"`. This protects usage accounting when Claude Code re-issues the session id after resume or compaction.
 - Claude Code cannot delete the implicit team or surgically remove an idle roster entry. Explain that teammates may remain visible until session end and, when needed, give the manual action `Delete team <teamName> in Teams/FleetView`.
-- The `SessionEnd` hook runs `$HOME/.okstra/bin/okstra-team-reconcile.sh --session-end` as the safety net for the current live session.
 
 ### Run-end cleanup sequence (BLOCKING)
 
@@ -222,6 +221,6 @@ For a `host-text` mapping, render each numbered item as its option label followe
    > <quoted `--list` output>
    > (Yes) Close everything and clean up teammates / (No) Keep everything
 5. On `keep`, preserve every residual resource and show `okstra team teardown --project-root "<PROJECT_ROOT>" --run-manifest "<RUN_MANIFEST_PATH>"` plus the manual Teams/FleetView action. Tell the user that `keep` holds only until the next boundary: if this session goes on to another phase/batch, that transition's round-boundary cleanup reclaims the kept **completed** panes unattended (in-flight resources and the lead pane are never touched).
-6. On approved `clean`, emit the teardown checkpoint, run `okstra team teardown --project-root "<PROJECT_ROOT>" --run-manifest "<RUN_MANIFEST_PATH>"`, then run `$HOME/.okstra/bin/okstra-team-reconcile.sh --project-root "<PROJECT_ROOT>" --fallback-team "session-<lead.sessionId-prefix>"` exactly once. The resolver reads the current live session's `~/.claude/teams/session-<live>/config.json`, falling back to the snapshot directory only when the live directory is absent, and prints `dismissible-member: <name>` records.
-7. Send `SendMessage(to: <name>, message: { type: "shutdown_request" })` to each printed, confirmed-complete non-lead member. The `message` MUST be the object literal shown, NEVER a JSON string in a text field. Never target the lead.
+6. On approved `clean`, emit the teardown checkpoint and run `okstra team teardown --project-root "<PROJECT_ROOT>" --run-manifest "<RUN_MANIFEST_PATH>"` exactly once.
+7. Send `SendMessage(to: <name>, message: { type: "shutdown_request" })` to each confirmed-complete non-lead teammate this run dispatched. The `message` MUST be the object literal shown, NEVER a JSON string in a text field. Never target the lead.
 8. Call `TaskStop(task_id: "<name>")` for every worker this run dispatched, reusing the step-7 names plus any batch worker already reclaimed earlier. `shutdown_request` only idles the roster member and the step-6 pane reclaim only closes the pane — neither ends the background task, so this step is the one that empties the harness's exit-time `Background work is running` list. Never target the lead; a `TaskStop` on an already-finished task is a benign no-op.

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

@@ -37,6 +37,25 @@ DESCRIPTOR = HostDescriptor(
 
 
 def _okstra_home_write_checks(context) -> tuple[dict[str, object], ...]:
+    """Whether THIS codex session can host the lead, not whether the run can go.
+
+    okstra's cross-project state lives in `~/.okstra`, and every run takes the
+    worktree registry lock there before the wizard starts. A codex session the
+    Codex app started under its `workspace-write` default cannot write that
+    path, and macOS seatbelt is inherited by children, so no okstra process
+    launched from inside that session can either.
+
+    That is a fact about the session, not about the machine. okstra already
+    knows how to run codex with no sandbox — `LeadLaunchSpec.sandbox_waiver`
+    puts `-s danger-full-access` on every lead it spawns itself. The waiver has
+    nowhere to go in `current-session` mode because there is no process being
+    launched. So the answer is to launch one: this check reports
+    `lead-must-spawn`, and the run proceeds in `spawn-process` mode.
+
+    It is deliberately not a blocker. Stopping here asked the user to widen
+    their whole Codex sandbox for a boundary okstra does not want anywhere else
+    — every provider CLI now runs without one.
+    """
     if context.entry_mode != "current-session":
         return ({"id": "okstra-home-write", "status": "not-applicable"},)
 
@@ -51,8 +70,8 @@ def _okstra_home_write_checks(context) -> tuple[dict[str, object], ...]:
     except PermissionError:
         return ({
             "id": "okstra-home-write",
-            "status": "required",
-            "action": "switch-codex-to-full-access-and-rerun",
+            "status": "lead-must-spawn",
+            "action": "spawn-unsandboxed-codex-lead",
         },)
     return ({"id": "okstra-home-write", "status": "accepted"},)
 

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

@@ -10,9 +10,10 @@ from okstra_ctl.adapters.hosts.capability_adapter import (
     INTERACTION_FUNCTIONS,
     PENDING_HOST_PORT,
     CapabilityHostAdapter,
+    no_automatic_claim,
     numbered_interaction_port,
 )
-from okstra_ctl.domain.host import HostClaim, HostDescriptor, HostResolutionContext
+from okstra_ctl.domain.host import HostDescriptor
 from okstra_ctl.ports.host_model import FailClosedHostModelBindingPort
 from okstra_ctl.registry.provider_registry import ProviderRegistry
 
@@ -34,16 +35,6 @@ DESCRIPTOR = HostDescriptor(
 )
 
 
-def _detect_tmux(context: HostResolutionContext) -> HostClaim | None:
-    if "tmux" not in context.signals:
-        return None
-    return HostClaim(
-        DESCRIPTOR.id,
-        10,
-        "No Claude Code host signal; tmux is available.",
-    )
-
-
 def create_adapter(
     *,
     executable_finder: Callable[[str], str | None] = shutil.which,
@@ -69,7 +60,7 @@ def create_adapter(
         worker_dispatch_port=worker_dispatch_port,
         usage_accounting_port=usage_accounting_port,
         supported_functions=INTERACTION_FUNCTIONS,
-        detector=_detect_tmux,
+        detector=no_automatic_claim,
         provider_registry=provider_registry,
         host_model_port=(
             host_model_port or FailClosedHostModelBindingPort(DESCRIPTOR.id)