okstra 0.205.1 → 0.206.1

package/runtime/{prompts/profiles → python/okstra_ctl/phases/implementation/instructions}/_implementation-executor.md

@@ -13,6 +13,7 @@ until Phase 5 ends, then drop from active context for Phase 6/7.
 - When the thin core's Task worktree block resolves status to `created` or `reused`, the Executor MUST run every Edit / Write / build / test / commit command with the worktree path as cwd. Treat it as `project_root` for the duration of this run. Do NOT mutate the caller's original checkout. Do NOT `cd` out of the worktree to reach files. If a file outside the worktree is genuinely needed, treat it as a planning gap: record it in `Out-of-plan edits` and continue.
   - **How to set the working directory**: every command and native edit MUST target `{{EXECUTOR_WORKTREE_PATH}}`, never the lead session's original project directory. The selected runtime adapter owns the exact native command syntax. Provider CLI wrappers inject the worktree at the CLI layer. For tools that accept an explicit working-directory flag (`git -C <path>`, `cargo --manifest-path`, `pytest --rootdir`), prefer that form.
 - **Synced okstra state directory.** At provision time Okstra may symlink `.project-docs/` from the repo's **main worktree** into the task worktree. This is NOT an independent copy — writes through it land in the main worktree. Inside this run the executor MUST confine okstra artifact writes to its own task scope (i.e. `.okstra/tasks/<this-task-id>/...`). Other synced directories, if present due to local configuration, are not implicit okstra context; read them only when the brief explicitly cites them as source material.
+- **Dependency installs stay in this worktree.** Before a package install (`yarn install`, `npm ci`, `pnpm install`, and the like), check the `node_modules` of the directory you install in. When it is a symlink that resolves outside this worktree, remove the link and install into a real `node_modules`: an install through the link rewrites the other checkout's dependencies. This is a guideline: nothing blocks the command, and the write audit only reports such a link as a `dependency tree links outside the assigned worktree` warning (`scripts/okstra_ctl/execution_mutation_audit.py`).
 
 **Enforced:** the worktree path reaches this worker as the `**Worktree:**` anchor (`scripts/okstra_ctl/worker_prompt_policy.py` `IMPLEMENTATION_HEADERS`), the CLI wrapper is started with that path as cwd by `scripts/okstra_ctl/dispatch_core.py`, and `scripts/okstra_ctl/execution_mutation_audit.py` `_source_changes` reports a mutation that landed outside the attempt's `writePolicy` roots.
 
@@ -20,8 +21,8 @@ until Phase 5 ends, then drop from active context for Phase 6/7.
 
 - **Three BLOCKING gates bind this run, and their bodies travel with this prompt** — inlined under their own headings, or named by path under `## Required prompt resources`. Follow the delivered body verbatim; a gate re-typed from memory is a skipped gate. Each gate's own body owns its rule list, so nothing here restates it:
   - `Coding-conventions preflight` (`prompts/profiles/_coding-conventions-preflight.md`) — before the first `Edit` / `Write`. It loads the conventions and binds the TDD loop below; close it by stating in ONE line which conventions apply (e.g. `Applying TS + hexagonal overlay; domain at src/domains/*/domain/`).
-  - `Pre-commit diff review sweep` (`prompts/profiles/_implementation-diff-review.md`) — after the stage's last `Edit` / `Write`, before the final commit. Sweep `git diff <stage-base>..HEAD` against the conventions the preflight loaded, fix findings in place while they are inside this stage's scope, and write its `Coverage:` footer to your audit sidecar.
-  - `Implementation self-check` (`prompts/profiles/_implementation-self-check.md`) — before you append the `status:"done"` row. Write the confirming evidence per item to your audit sidecar.
+  - `Pre-commit diff review sweep` (`scripts/okstra_ctl/phases/implementation/instructions/_implementation-diff-review.md`) — after the stage's last `Edit` / `Write`, before the final commit. Sweep `git diff <stage-base>..HEAD` against the conventions the preflight loaded, fix findings in place while they are inside this stage's scope, and write its `Coverage:` footer to your audit sidecar.
+  - `Implementation self-check` (`scripts/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md`) — before you append the `status:"done"` row. Write the confirming evidence per item to your audit sidecar.
 
 <!--
 Gate delivery (lead / maintainer — stripped before this body reaches a worker).
@@ -88,7 +89,7 @@ template's check; that template is gone.
   ```
 
   The file MUST NOT exist before the run starts (overwrite is refused — see `--force-stage` non-goal). **Enforced:** `validators/validate-run.py` `_validate_stage_carry_sidecar_exists` fails a run that declares `stageSidecarEvidence` without the file on disk. Transcribing the JSON into the report is not the same as writing it: `consumers` treats the carry file as the source of truth for marking the stage `done`, so a missing file leaves the stage permanently incomplete and blocks every dependent stage with a `PrepareError` — while this run reports success.
-- **Verifier gates are not yours to run (BLOCKING).** The self-mock detector (`validators/detect_self_mock.py`) belongs to the implementation verifier and is never delegated to you (`_implementation-verifier.md` §"Self-mock detection"). The coding-conventions preflight names it as the enforcement behind the no-self-mocking principle — that names who will check your diff, not a command for you to run. You MUST NOT invoke it and MUST NOT write `<task_root>/qa/self-mock-*.json`; running it early does not pre-satisfy the gate, because the verifier runs it again under its own duty. **Enforced:** that sidecar is not among the paths your attempt's `writePolicy.artifactPolicy.allowedPaths` carries, so the write audit closes the attempt as `error` with `artifact-root change exceeds batch policy union` (`scripts/okstra_ctl/execution_mutation_audit.py`) — a stage whose every gate passed still lands as a failed run.
+- **Verifier gates are not yours to run (BLOCKING).** The self-mock detector (`validators/detect_self_mock.py`) belongs to the implementation verifier and is never delegated to you (`_implementation-verifier.md` §"Self-mock detection"). The coding-conventions preflight names it as the enforcement behind the no-self-mocking principle — that names who will check your diff, not a command for you to run. You MUST NOT invoke it and MUST NOT write `<task_root>/qa/self-mock-*.json`; running it early does not pre-satisfy the gate, because the verifier runs it again under its own duty. **Enforced:** that sidecar is not among the paths your attempt's `writePolicy.artifactPolicy.allowedPaths` carries, so the write audit closes the attempt as `error` with `artifact-root change exceeds batch policy union` (`scripts/okstra_ctl/execution_mutation_audit.py`) — a stage whose every gate passed still lands as a failed run. The same holds for the conformance results `<task_root>/qa/result-*.json`: you may run a conformance script to check your work, but the verifier records every result, including an earlier stage's result that your rewrite of its script made stale. When the approved plan tells you to write one, leave it and name it in your result as a plan step the verifier owns.
 - **An external Tier 3 non-PASS does NOT withhold the carry evidence.** A Tier 3 entry whose `requires` include `http`, `external`, or `db` is advisory. Its FAIL, MISSING, no result, startup failure, or credential / network / service absence gets recorded honestly — exact command, exit code, output tail, marked `ADVISORY` in `Validation evidence` — and you emit the carry evidence anyway. Only Tier 1 and Tier 2 failures withhold it. Withholding on an external result is what actually blocks the stage: the carry file is the only thing that can mark a stage `done`, the verifier re-runs that same command from the host (where a call your sandbox could not complete often passes), and a stage the verifier then PASSes can never be closed because its evidence was never written.
 - **Reverse link (BLOCKING).** The runtime already appended a `status:"started"` row for this stage before the run began. The terminal row belongs to the lead's post-stage persistence and is verdict-gated — `status:"done"` with `carry_path` on a non-`FAIL` verdict, `status:"failed"` on `FAIL` (`_implementation-deliverable.md` §"Lead post-stage persistence").
 - **No PR / push in this phase.** This run produces local commits, carry sidecar evidence, verifier results, and the implementation final report only. Push and PR creation belong exclusively to the later `release-handoff` phase after `final-verification` returns `accepted`.

package/runtime/{prompts/profiles → python/okstra_ctl/phases/implementation/instructions}/_implementation-verifier.md

@@ -32,7 +32,7 @@ A target mismatch or changed fingerprint invalidates this check's evidence. Reco
 Verifier obtains the QA command set from exactly two declared sources, in order — there is **no fallback to guessing tools from manifest files**.
 
 1. **Tier 1 — plan validation set (task-specific):** every command listed under the approved plan's `validation` block (pre / mid / post). The plan is the file at this prompt's `**Approved plan:**` anchor, scoped to the stage its `**Stage for this implementation run:**` anchor names; both are generated headers, so a missing one is `contract-violated`, never a value to infer. Each checklist row also carries `phase`, and the phase is part of what the row asserts: `pre` runs before the stage edits, `mid` between the edits and the stage commit, `post` after the commit. A `mid` diff-scope check (`git diff --name-only` listing the touched paths) is reproduced over the stage range — `git diff --name-only <stage base>...HEAD` — once the stage has committed; its empty output on the clean post-commit tree is the plan's own step order, not a divergence. A `Discrepancy` that cites a checklist row names the row and its phase as `VC-NNN (phase: mid)`; a verifier that reads the command without the phase has read half the row. **Enforced:** `_validate_verifier_discrepancy_names_checklist_phase` in `validators/validate-run.py` fails a divergence that cites a `VC-` row without that row's phase.
-2. **Tier 2 — project baseline:** the project's standing QA baseline from the `Project QA Commands` section emitted by `okstra model-io project-context --project-root <PROJECT_ROOT> --task-ref <task-ref>`.
+2. **Tier 2 — project baseline:** the project's standing QA baseline from the `Project QA Commands` section emitted by `okstra model-io project-context --project-root <PROJECT_ROOT> --task-ref <TASK_KEY>` (the full `Task key` your dispatch prompt names).
    ```json
    {
      "qaCommands": {
@@ -75,7 +75,7 @@ lock the core, gate, and accepted-report behavior respectively.
 An `io`-only non-PASS remains BLOCKING. Manifest/schema/source-mutation defects
 also remain contract violations.
 
-- **Source.** The conformance manifest is `<task_root>/qa/conformance-manifest.json` (the directory is the `TASK_QA_PATH` token). This run's stage conformance entry is the manifest `entries[]` item whose `stageKey` equals this run's stageKey — `<task-id>-stage-<N>`, where `<N>` is the injected Stage number. Find that one entry; ignore the others (other stages are run by their own implementation runs or by final-verification).
+- **Source.** The conformance manifest is `<task_root>/qa/conformance-manifest.json` (the directory is the `TASK_QA_PATH` token). This run's stage conformance entry is the manifest `entries[]` item whose `stageKey` equals this run's stageKey — `<task-id>-stage-<N>`, where `<N>` is the injected Stage number. Find that one entry. Also run every other entry whose `script` appears in this stage's `plannedPaths`: this stage rewrote that script, so the result its own stage recorded is stale, and you write that entry's result sidecar exactly as below. Ignore the rest (other stages are run by their own implementation runs or by final-verification).
 - **Exemption / waiver → do NOT run.** If the entry carries an `exemption` (or a user `waiver`), the verifier does NOT execute the script. It records the fact and the reason (`exemption.reason` / `waiver.reason` + `waiver.acknowledgedBy`) in the Read-only command log AND writes the result sidecar reflecting the skip. An `exemption` passes outright. An external-advisory waiver is reported as `ADVISORY` with `conditional=false`; only an `io`-only blocking waiver is conditional. An empty `requires` list cannot be waived; it is declaration/contract trouble and remains BLOCKING. No script runs in either permitted waiver case.
 - **Otherwise run `runCommand` in the worktree cwd.** Execute the entry's `runCommand` verbatim from the worktree cwd. Inject env from `<PROJECT_ROOT>/.okstra/project.json`'s `qaEnv` (replica DB DSN / app base URL / env file — declared in Phase 4e). This is a **replica / test environment only** path — never run it against shared / staging / prod, identical to the DB real-execution gate principle above.
 - **Interpret the standard interface.** Parse the process exit code together with stdout: the `QA-RESULT: PASS|FAIL` marker line (if several appear, the last one wins) and the per-requirement `REQ <id>: PASS|FAIL: <reason>` lines. If no `QA-RESULT` marker is emitted, the overall result is `MISSING`; classify it according to the entry's blocking or external-advisory capability policy above.
@@ -173,7 +173,7 @@ Re-running commands proves the diff *builds and passes*; it does NOT prove the d
 - **Scope (no silent sampling).** Enumerate every changed source/test file via `git diff --name-only <base>...HEAD` and review each one. Skipping a changed file silently is a `contract-violated` outcome. If a file's language has no reference and is not covered by the agnostic checks below, record `design-review skipped: <file> (language=<x> no reference)` — never pass it silently.
 - **Load the same conventions the executor used via the routed pack.** Use this worker prompt's `**Coding preflight pack:**` anchor header as the absolute path to the installed routed pack. Read `overview.md` first, then `clean-code.md`, then apply the router's three ordered stages: language, framework, architecture. In each stage, iterate every rule, treat a rule as matched when any listed condition is true, and accumulate every matching resource — including `frameworks/node-server.md` for server-side Node work and `architectures/hexagonal.md` for ports-and-adapters / NestJS-hex layouts. Degrade to the agnostic checks below when the resolved pack is unreadable, and record either `coding-conventions: resources=<...>` or `coding-conventions: resource-unavailable → applied <project rules + agnostic principles>`. The verifier does NOT inline language rules — it loads the same situation-specific resources as the executor preflight.
 - **Load the project's review rule packs.** Run the project-context projection above and union its `Project Review Rule Packs` entries with exact `SKILL.md` paths cited by the task brief's `Source Material` / `Reporter Confirmations`. Read only those files and the `references/*.md` files they directly name. Do not search parent directories or host skill catalogs. Apply the rules as an overlay on this static review, but do NOT dispatch extra reviewer agents unless the task explicitly configured them. Record `project-review-rules: <paths read>`, `project-review-rules: declared <path> unreadable`, or `project-review-rules: none declared or cited` in the worker result — an unreadable declared pack is a recorded gap, not a skip.
-- **Declared architecture style promotes the placement overlay from advisory to binding.** Take `Architecture style` from that projection and record `architecture-style: <hexagonal|layered|none>` in the worker result next to the `coding-conventions:` line. A declared `hexagonal` counts the overlay as loaded even when none of the router's Stage 3 layout signals matched, so the **Hexagonal** blocking check below applies in full, and the concrete-adapter injection listed under Advisory findings is promoted to a blocking finding → verdict `FAIL`, not a `should-fix`. A declared `layered` has no pack resource; its binding invariant is direction — an upper layer may import a lower one, never the reverse — so a changed file whose import list reaches back up a layer, or around a layer boundary, is a blocking placement violation cited `path:line` from that import list. The `layered` half is worker judgement: no machine check reads layer names, so a missed reverse dependency is a missed finding, not a validator failure. A `none` or absent projected style leaves Stage 3 detection-driven and the placement items advisory. **Enforced:** `scripts/okstra_project/resolver.py` `resolve_architecture` reads the same stored field for the planning-side rule in `validators/validate-run.py` `_validate_variation_point_analysis`, and `_validate_verifier_fail_blocks_verdict` keeps the resulting `FAIL` from being dropped during synthesis.
+- **Declared architecture style promotes the placement overlay from advisory to binding.** Take `Architecture style` from that projection and record `architecture-style: <hexagonal|layered|none>` in the worker result next to the `coding-conventions:` line. A declared `hexagonal` counts the overlay as loaded even when none of the router's Stage 3 layout signals matched, so the **Hexagonal** blocking check below applies in full, and the concrete-adapter injection listed under Advisory findings is promoted to a blocking finding → verdict `FAIL`, not a `should-fix`. A declared `layered` has no pack resource; its binding invariant is direction — an upper layer may import a lower one, never the reverse — so a changed file whose import list reaches back up a layer, or around a layer boundary, is a blocking placement violation cited `path:line` from that import list. The `layered` half is worker judgement: no machine check reads layer names, so a missed reverse dependency is a missed finding, not a validator failure. A `none` or absent projected style leaves Stage 3 detection-driven and the placement items advisory. **Enforced:** `scripts/okstra_project/resolver.py` `resolve_architecture` reads the same stored field for the planning-side rule in `scripts/okstra_ctl/phases/implementation_planning/plan_body.py` `_validate_variation_point_analysis`, and `_validate_verifier_fail_blocks_verdict` keeps the resulting `FAIL` from being dropped during synthesis.
 - **Blocking checks (any hit → verdict `FAIL`, cited `path:line` + rule name, recommended fix recorded — the verifier does NOT apply it):**
   - **New duplication / DRY:** two or more newly added or meaningfully modified blocks implement the same helper stack, transform, or domain rule. Literal copy-paste is always blocking; semantically equivalent transforms across services are blocking unless the approved plan explicitly justified keeping them separate. Recommend the shared module location.
   - **Self-mocking:** a test for `Foo` stubs/spies a method on the `Foo` instance under test (`jest.spyOn(sut, ...)`, `spyOn(FooService.prototype, ...)` in `foo.*.spec.*`, `vi.mocked(sut)` + stub). Mocking injected collaborators is fine.
@@ -255,7 +255,7 @@ If every verifier present in the resolved roster ends with a non-result terminal
 
 ## Executor completion self-check (not this role's gate)
 
-- The executor's `Implementation self-check` gate (`prompts/profiles/_implementation-self-check.md`) belongs to the worker that owns the diff, and its body is deliberately not delivered here: it asks for in-place fixes and break-then-restore mutation checks, every one of which this verifier is forbidden to perform. Do not re-derive its items or claim to have run it. What grades the same defects from this side is the blocking taxonomy above, applied to the diff you re-read yourself. When the executor's `Coverage:` / `Self-check coverage:` lines are among the inputs this prompt enumerates, a missing line or one whose file list does not reconcile with the diff is a blocking finding — the gate was skipped or partially run.
+- The executor's `Implementation self-check` gate (`scripts/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md`) belongs to the worker that owns the diff, and its body is deliberately not delivered here: it asks for in-place fixes and break-then-restore mutation checks, every one of which this verifier is forbidden to perform. Do not re-derive its items or claim to have run it. What grades the same defects from this side is the blocking taxonomy above, applied to the diff you re-read yourself. When the executor's `Coverage:` / `Self-check coverage:` lines are among the inputs this prompt enumerates, a missing line or one whose file list does not reconcile with the diff is a blocking finding — the gate was skipped or partially run.
 
 ## Plan differences and completion recovery
 

package/runtime/{prompts/profiles/implementation.md → python/okstra_ctl/phases/implementation/profile.md}

@@ -25,8 +25,8 @@
   - the run brief MUST cite `--approved-plan <path>` pointing to a `final-report-implementation-planning-<seq>.data.json` report record produced by a prior `implementation-planning` run located under `runs/implementation-planning/.../reports/`
   - that plan's report record MUST carry `frontmatter.approved: true`. report-writer emits `false` by default; the user authorises this run with `--approve` or the in-session wizard. Free-form approvals such as "lgtm" / "go ahead" / paraphrased confirmations are NOT accepted; editing the full reading copy does not approve the plan (`okstra_ctl.run._apply_cli_approval`).
   - 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.
+  - 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. Record whether a deviation changes the selected direction or only plan details; the lead applies `prompts/lead/phase-routing.md`.
+  - 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; never silently expand scope. The lead applies `prompts/lead/phase-routing.md`. If the chosen option name does not match any heading under `Option Candidates`, record it as a deviation.
 - 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`.
@@ -48,9 +48,9 @@ The bulk of this profile's body is split into three sidecars so the lead's Phase
 
 | Sidecar | Read at | Purpose |
 |---------|---------|---------|
-| `prompts/profiles/_implementation-executor.md` | Start of Phase 5 (after Stage Map parse, before Executor's first Edit / Write) | Executor role binding, Pre-implementation context exploration, TDD loop, Stage execution contract, allowed actions, commit-message format |
-| `prompts/profiles/_implementation-verifier.md` | Phase 5, between Executor stage completion and the first verifier dispatch | Verifier roles, Two-tier command lookup, deny-list, discrepancy rule, Read-only command log, verifier-specific forbidden actions |
-| `prompts/profiles/_implementation-deliverable.md` | Start of Phase 6 (after Phase 5.5 convergence completes, before report-writer dispatch prompt construction) | Required deliverable shape, Validation / TDD evidence rules, Verifier results structure, Self-review pass, Lead post-stage persistence |
+| `scripts/okstra_ctl/phases/implementation/instructions/_implementation-executor.md` | Start of Phase 5 (after Stage Map parse, before Executor's first Edit / Write) | Executor role binding, Pre-implementation context exploration, TDD loop, Stage execution contract, allowed actions, commit-message format |
+| `scripts/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md` | Phase 5, between Executor stage completion and the first verifier dispatch | Verifier roles, Two-tier command lookup, deny-list, discrepancy rule, Read-only command log, verifier-specific forbidden actions |
+| `scripts/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md` | Start of Phase 6 (after Phase 5.5 convergence completes, before report-writer dispatch prompt construction) | Required deliverable shape, Validation / TDD evidence rules, Verifier results structure, Self-review pass, Lead post-stage persistence |
 
 **Entering Phase 5 / 6 while the relevant sidecar is not in the lead's context is BLOCKING — the phase entry is refused.** After reading a sidecar, the lead must continue into the phase's follow-up action within a single turn (i.e. the sidecar's rules take effect starting from the very turn it is read).
 

package/runtime/python/okstra_ctl/{report_html/view_models/implementation.py → phases/implementation/report.py}

@@ -1,9 +1,9 @@
 """Human-first implementation delivery view model."""
 from __future__ import annotations
 
-from ..common import evidence_index
-from ..models import HumanReportView, VisualNode
-from ..visualizations import change_map_figure
+from okstra_ctl.report_html.common import evidence_index
+from okstra_ctl.report_html.models import HumanReportView, VisualNode
+from okstra_ctl.report_html.visualizations import change_map_figure
 
 # Record fields this template anchors as `id-<row id>` (see
 # `HumanReportView.anchored_fields`); ids elsewhere land in the ledger.

package/runtime/{templates/reports → python/okstra_ctl/phases/implementation/report_assets}/implementation-input.template.md

@@ -52,7 +52,7 @@ taskType: "{{FM_TASK_TYPE}}"
 
 > The executor MUST NOT modify items listed here, even when an edit looks "trivial" or "while I'm in this file". Excluded items that block plan execution are reported back as a recommended follow-up task and the run halts for re-planning rather than silently expanding scope. This section is enforced together with `Forbidden In This Run` below.
 
-**Enforced (delivery only):** `tests/contract/test_scope_boundary_delivery.py` pins that a filled section reaches every analysis worker through `okstra_ctl.analysis_packet` — drop it from `CANONICAL_BRIEF_SECTIONS` and every run's exclusions vanish silently. The exclusions themselves are prose and are **not** machine-checked: only the codebase-scan `out-of-scope` frontmatter is a path list, and `validators/validate_improvement_report.py` checks that one.
+**Enforced (delivery only):** `tests/contract/test_scope_boundary_delivery.py` pins that a filled section reaches every analysis worker through `okstra_ctl.analysis_packet` — drop it from `CANONICAL_BRIEF_SECTIONS` and every run's exclusions vanish silently. The exclusions themselves are prose and are **not** machine-checked: only the codebase-scan `out-of-scope` frontmatter is a path list, and `scripts/okstra_ctl/phases/improvement_discovery/validation.py` checks that one.
 
 **Enforced (declared edits only):** `_validate_out_of_plan_edits_are_real` in `validators/validate-run.py` fails an `Out-of-plan edits` row naming a file that is absent from `diffSummary`. The other direction — a file changed outside the approved plan and never declared — needs the plan's own file list resolved through `approvedPlanReference.planFile`, and is not built.
 

package/{docs/task-process/implementation.md → runtime/python/okstra_ctl/phases/implementation/spec.md}

@@ -64,7 +64,7 @@ here because they were previously readable only by tracing the runtime sources.
   the automatic attachment is the fallback for an implementation run that supplies none
   (`scripts/okstra_ctl/run.py`, the `implementation` carry-in branch).
 - **Who reads it, and when.** The executor, before its first edit
-  (`prompts/profiles/_implementation-executor.md`). A CLI executor (codex/antigravity)
+  (`scripts/okstra_ctl/phases/implementation/instructions/_implementation-executor.md`). A CLI executor (codex/antigravity)
   cannot reach that path from inside its sandbox, so the lead transcribes the file's body
   into the dispatched executor prompt — a path reference alone never arrives.
 - **What happens when an answer contradicts the plan.** Each answer is an authoritative
@@ -217,10 +217,22 @@ This phase does not declare final acceptance. It says only ready for final-verif
 
 ## 8. Verified code
 
-- [`prompts/profiles/implementation.md`](../../prompts/profiles/implementation.md)
-- [`templates/reports/implementation-input.template.md`](../../templates/reports/implementation-input.template.md)
-- [`scripts/okstra_ctl/run.py`](../../scripts/okstra_ctl/run.py)
-- [`scripts/okstra_ctl/wizard/`](../../scripts/okstra_ctl/wizard/)
-- [`validators/validate-implementation-plan-stages.py`](../../validators/validate-implementation-plan-stages.py)
-- [`scripts/okstra_ctl/qa_commands.py`](../../scripts/okstra_ctl/qa_commands.py)
-- [`prompts/lead/okstra-lead-contract.md`](../../prompts/lead/okstra-lead-contract.md)
+- [`scripts/okstra_ctl/phases/implementation/profile.md`](profile.md)
+- [`scripts/okstra_ctl/phases/implementation/report_assets/implementation-input.template.md`](report_assets/implementation-input.template.md)
+- [`scripts/okstra_ctl/run.py`](../../run.py)
+- [`scripts/okstra_ctl/wizard/`](../../wizard)
+- [`validators/validate-implementation-plan-stages.py`](../../../../validators/validate-implementation-plan-stages.py)
+- [`scripts/okstra_ctl/qa_commands.py`](../../qa_commands.py)
+- [`prompts/lead/okstra-lead-contract.md`](../../../../prompts/lead/okstra-lead-contract.md)
+
+## Phase ownership
+
+`entry.py` owns stage claim preparation, design-preparation checks and execution context publication. `wizard.py` owns implementation stage selection policy. `validation.py` enforces independent rerun and discrepancy verdicts. `tests/test_implementation_stage.py` checks claims and consumer publication; `tests/test_verifier_results.py` checks verifier verdicts. Shared plan records, stage lifecycle state and worktree registry remain common contracts. Report schema definitions remain in `schemas/final-report-v2.0.schema.json` and `schemas/final-report-v3.0.schema.json` under `implementation`.
+
+## Guarantees
+
+| ID | Guarantee | Enforcement |
+|---|---|---|
+| I-1 | An empty independent rerun record fails validation. | `scripts/okstra_ctl/phases/implementation/validation.py::_validate_verifier_reran_independently` |
+| I-2 | A verifier cannot report a discrepancy with a PASS verdict. | `scripts/okstra_ctl/phases/implementation/validation.py::_validate_verifier_discrepancy_is_not_passed` |
+| I-3 | Frozen legacy instruction pointers resolve within the selected installation without rewriting the frozen profile. | `scripts/okstra_ctl/phases/implementation/tests/test_assets.py::test_frozen_sidecar_reference_reads_the_owned_installation` |

package/runtime/python/okstra_ctl/phases/implementation/validation.py

@@ -0,0 +1,205 @@
+"""구현 검증자의 독립 재현과 판정 일관성 검사."""
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+
+_PASSING_VERDICT_TOKENS = frozenset({"accepted", "conditional-accept"})
+_CHECKLIST_ID_RE = re.compile(r"\bVC-\d{3,}\b")
+_CHECKLIST_PHASE_RE = re.compile(r"\bphase\W{0,3}(pre|mid|post)\b", re.IGNORECASE)
+
+
+def _validate_verifier_reran_independently(data: dict, failures: list[str]) -> None:
+    """`independentValidationRerun` 칸이 비어 있지 않아야 한다.
+
+    스키마는 필드 존재만 강제하고 값은 보지 않는다. 빈 칸은 재현 없이
+    통과시킨 것과 구별되지 않는다.
+
+    executor 인용 표현을 잡던 정규식 갈래는 삭제했다. 표현을 세는 검사라
+    같은 재현을 어떻게 서술했느냐로 통과가 갈렸다.
+    """
+    for who, row in _verifier_rows(data):
+        rerun = row.get("independentValidationRerun")
+        if not isinstance(rerun, str) or not rerun.strip():
+            failures.append(
+                f"verifier-rerun: {who} 가 independentValidationRerun 을 비워 뒀다 — "
+                "재현 없이 통과시킨 것과 구별되지 않는다"
+            )
+
+
+def _validate_verifier_discrepancy_is_not_passed(
+    data: dict, failures: list[str]
+) -> None:
+    """재현 결과가 executor 보고와 갈렸는데 PASS 로 넘기지 못하게 한다.
+
+    규칙(§"Discrepancy rule")은 Tier 1/2 와 blocking io-only Tier 3 의 divergence 에
+    `FAIL` 을 요구하고, Tier 3 외부 자문 divergence 만 제외한다. 리포트 구조에는
+    tier 필드가 없어 그 둘을 여기서 가릴 수 없다. 그래서 `PASS` 만 막는다 —
+    자문 divergence 는 `CONCERNS` 로 기록할 자리가 이미 있고, `PASS` 는 "갈렸는데
+    아무 일도 없었다" 는 뜻이라 어느 tier 로도 정당화되지 않는다.
+    """
+    for who, row in _verifier_rows(data):
+        discrepancy = row.get("discrepancy")
+        if not isinstance(discrepancy, str) or not discrepancy.strip():
+            continue
+        if row.get("verdict") == "PASS":
+            failures.append(
+                f"verifier-discrepancy: {who} 가 divergence 를 기록하고도 PASS 를 냈다 "
+                f"— FAIL(또는 자문 divergence 면 CONCERNS)이어야 한다: "
+                f"{discrepancy.strip()[:120]}"
+            )
+
+
+def _verifier_rows(data: dict):
+    """(표시 이름, verifierResults 행) 쌍."""
+    implementation = data.get("implementation")
+    if not isinstance(implementation, dict):
+        return
+    for row in implementation.get("verifierResults") or []:
+        if not isinstance(row, dict):
+            continue
+        yield str(row.get("verifier") or row.get("role") or "verifier"), row
+
+
+def _warn_out_of_plan_edits_not_in_diff(data: dict, warnings: list[str], changed_files: list[str]) -> None:
+    """소스 차이 목록은 별도 QA 산출물의 변경 여부를 증명하지 못한다."""
+    implementation = data.get("implementation")
+    if not isinstance(implementation, dict):
+        return
+    rows = implementation.get("outOfPlanEdits")
+    if not isinstance(rows, list) or not rows:
+        return
+    changed = set(changed_files)
+    if not changed:
+        return
+    for row in rows:
+        if not isinstance(row, dict):
+            continue
+        target = row.get("file")
+        if isinstance(target, str) and target and target not in changed:
+            warnings.append(
+                f"out-of-plan-edit: {row.get('id') or 'OOP-???'} 가 `{target}` 을 "
+                "계획 밖 편집으로 신고했지만 diffSummary 에 그 파일이 없다"
+            )
+
+
+def _validate_verifier_discrepancy_names_checklist_phase(
+    data: dict,
+    plan: dict | None,
+    failures: list[str],
+) -> None:
+    """계획 `validationChecklist` 행을 근거로 적은 divergence 는 그 행의 `phase` 를 인용한다.
+
+    2026-09-05 실측(fontsninja-v3-site dev-10626 stage-1): codex 검증자가 `VC-003` 의
+    `git diff --name-only` 가 커밋 뒤 빈 출력이라며 FAIL 을 냈다. 그 행은 계획 레코드에
+    `phase: mid` — 편집과 커밋 사이의 체크포인트 — 로 선언돼 있어, 커밋 뒤의 빈 출력은
+    계획의 단계 순서 그 자체였다. 수렴에서 제기자 본인이 반대 읽기에 AGREE 했지만 FAIL
+    행은 남아 stage 가 `failed` 로 갔고, 리드도 그 주장을 열어 보지 않고 라우팅에 옮겼다.
+    `pre`/`mid`/`post` 는 행이 언제 성립하는지를 정하므로, 행을 인용하는 문장이 그 값을
+    함께 적어야 한다 — 읽지 않은 행을 근거로 쓰는 문장은 그러면 쓸 수 없다.
+
+    행에 `phase` 가 없거나 계획 레코드를 못 찾으면 판정하지 않는다.
+    """
+    if plan is None:
+        return
+    planning = plan.get("implementationPlanning")
+    rows = planning.get("validationChecklist") if isinstance(planning, dict) else None
+    phases = {
+        str(row["id"]): str(row["phase"]).strip().lower()
+        for row in (rows if isinstance(rows, list) else [])
+        if isinstance(row, dict)
+        and isinstance(row.get("id"), str)
+        and isinstance(row.get("phase"), str)
+    }
+    if not phases:
+        return
+    for who, row in _verifier_rows(data):
+        discrepancy = row.get("discrepancy")
+        if not isinstance(discrepancy, str) or not discrepancy.strip():
+            continue
+        cited = sorted(set(_CHECKLIST_ID_RE.findall(discrepancy)) & set(phases))
+        if not cited:
+            continue
+        named = {
+            match.group(1).lower()
+            for match in _CHECKLIST_PHASE_RE.finditer(discrepancy)
+        }
+        missing = [
+            f"{row_id} (phase: {phases[row_id]})"
+            for row_id in cited
+            if phases[row_id] not in named
+        ]
+        if missing:
+            failures.append(
+                f"verifier-discrepancy: {who} 가 계획 체크리스트 행을 근거로 divergence 를 "
+                f"적었지만 그 행의 phase 를 인용하지 않았다 — {', '.join(missing)}. "
+                "`pre`/`mid`/`post` 는 행이 언제 성립하는지를 정하므로 인용 문장에 "
+                "`VC-NNN (phase: <값>)` 으로 적는다 (`_implementation-verifier.md` § Tier 1)."
+            )
+
+
+def _validate_verifier_command_log_is_read_only(
+    data: dict,
+    failures: list[str],
+    verifier_mutation_hits: Callable[[str], list[tuple[str, str]]],
+) -> None:
+    """검증자의 Read-only command log 에 변조 모드가 없어야 한다.
+
+    규칙은 prompts/profiles/_implementation-verifier.md 가 "런타임 AND 검증자가
+    거부해야 한다"고 BLOCKING 으로 선언해 왔지만 런타임 검사는 없었다. 스키마는
+    로그의 **존재**만 강제하고 내용은 아무도 읽지 않았다 — 검증자가
+    `eslint --fix` 로 자기가 검증할 소스를 고쳐 놓아도 통과한다.
+
+    로그는 리포트에 그대로 복사되므로 여기서 읽는 것이 정본이다.
+    """
+    implementation = data.get("implementation")
+    if not isinstance(implementation, dict):
+        return
+    rows = [r for r in (implementation.get("verifierResults") or []) if isinstance(r, dict)]
+    if not rows:
+        return
+    for row in rows:
+        log = row.get("readOnlyCommandLog")
+        if not isinstance(log, str) or not log.strip():
+            continue
+        who = str(row.get("workerId") or row.get("role") or "verifier")
+        for label, line in verifier_mutation_hits(log):
+            failures.append(
+                f"verifier-command-log: {who} 의 read-only 로그에 변조 모드 "
+                f"`{label}` 이 있다: {line[:120]}"
+            )
+
+
+def _validate_verifier_fail_blocks_verdict(data: dict, failures: list[str]) -> None:
+    """A verifier FAIL cannot be dropped during synthesis.
+
+    `implementation.verifierResults[]` was written, read by the stage-fix carry
+    helper, and by nothing else — no check compared a recorded `FAIL` against
+    the verdict the lead published. A FAIL lost in synthesis lets
+    `final-verification` reach `accepted` and `release-handoff` push work a
+    verifier rejected.
+    """
+    implementation = data.get("implementation")
+    if not isinstance(implementation, dict):
+        return
+    failed = sorted({
+        str(row.get("verifier") or "<unknown>")
+        for row in (implementation.get("verifierResults") or [])
+        if isinstance(row, dict) and str(row.get("verdict") or "").strip() == "FAIL"
+    })
+    if not failed:
+        return
+    token = str((data.get("finalVerdict") or {}).get("verdictToken") or "").strip()
+    if token in _PASSING_VERDICT_TOKENS:
+        failures.append(
+            f"final-report data.json: verifier(s) {failed} recorded "
+            f"`verdict: FAIL` but `finalVerdict.verdictToken` is `{token}`. A "
+            "verifier rejection MUST survive into the published verdict — "
+            "dropping it during synthesis is how rejected work reaches "
+            "`release-handoff`. Carry the FAIL into a blocking verdict. There "
+            "is no synthesis-time override: a verifier that produced no "
+            "verdict records `not-run` and a Tier 3 advisory divergence "
+            "records `CONCERNS`, and both are the verifier's to write, not "
+            "the lead's to substitute "
+            '(`_implementation-verifier.md` "All-verifier-failure policy").'
+        )

package/runtime/python/okstra_ctl/phases/implementation/wizard.py

@@ -0,0 +1,39 @@
+"""구현 단계 선택의 상태 표기와 선택 가능 조건."""
+from __future__ import annotations
+
+from okstra_ctl.wizard.ids import ALL_STAGES
+from okstra_ctl.wizard.state import WizardError
+
+_STAGE_MARKER_KEYS = {
+    "done": "mark_done",
+    "active": "mark_active",
+    "ready": "mark_ready",
+    "blocked": "mark_blocked",
+}
+
+
+def _impl_stage_marker(t, lifecycle) -> str:
+    return t["options"][_STAGE_MARKER_KEYS[lifecycle.status]]
+
+
+def _impl_chosen_stages(t, picks, answer, all_nums, occupied) -> set:
+    if ALL_STAGES in picks:
+        if len(picks) > 1:
+            raise WizardError(t["errors"]["all_exclusive"])
+        chosen = {n for n in all_nums if n not in occupied}
+        if not chosen:
+            raise WizardError(t["errors"]["nothing_selectable"])
+        return chosen
+    try:
+        nums = {int(p) for p in picks}
+    except ValueError:
+        raise WizardError(t["errors"]["bad_number"].format(answer=answer))
+    unknown = sorted(nums - all_nums)
+    if unknown:
+        raise WizardError(t["errors"]["unknown_stage"].format(
+            bad=", ".join(map(str, unknown))))
+    bad = sorted(nums & occupied)
+    if bad:
+        raise WizardError(t["errors"]["occupied"].format(
+            bad=", ".join(map(str, bad))))
+    return nums

package/runtime/python/okstra_ctl/phases/implementation_option_selection/__init__.py

@@ -0,0 +1 @@
+"""구현 방향 비교와 후보 검증 단계의 정본."""

package/runtime/python/okstra_ctl/phases/implementation_option_selection/authoring.py

@@ -0,0 +1,80 @@
+"""후보 평가 결과를 작성하는 보고서 계약."""
+from __future__ import annotations
+
+from typing import Sequence
+
+from .validation import (
+    EVALUATION_CRITERIA,
+    MAX_CRITERION_VALUE,
+    MAX_RANKED_OPTIONS,
+    MAX_RAW_CANDIDATES_PER_ANALYSER,
+    MIN_CRITERION_VALUE,
+    MIN_FEASIBLE_VOTES,
+)
+from okstra_ctl.exact_coverage import COVERAGE_VERDICT_PRECEDENCE
+
+
+def requirement_instructions(original_requirement_ids: Sequence[str], participating_analysers: Sequence[str]) -> list[str]:
+    criteria = ", ".join(f"`{item}`" for item in EVALUATION_CRITERIA)
+    requirement_ids = ", ".join(
+        f"`{item}`" for item in original_requirement_ids
+    )
+    analysers = ", ".join(
+        f"`{item}`" for item in participating_analysers
+    )
+    return [
+        f"Original requirement ids, in order: {requirement_ids}.",
+        f"Participating analysers: {analysers}.",
+        f"Evaluation criteria, in exact order: {criteria}.",
+        "Every `rankedOptions` and `candidateAudit` row must contain one "
+        "`requirementCoverage` row per original requirement id and one "
+        "`criterionScores` row per evaluation criterion. Weights and scores "
+        f"are integers from {MIN_CRITERION_VALUE} through {MAX_CRITERION_VALUE}; "
+        "`weightedScore` is the recalculated weighted mean.",
+        "`proposedBy` names exactly one participating analyser id, never a "
+        "list. Counting `rankedOptions` and `candidateAudit` together, each "
+        f"analyser may propose at most {MAX_RAW_CANDIDATES_PER_ANALYSER} raw "
+        "candidates and the run may hold at most "
+        f"{MAX_RAW_CANDIDATES_PER_ANALYSER} times the analyser count.",
+        "`coverageSummary` is recalculated from the row's `requirementCoverage` "
+        "statuses and `scopeCommitments`, and every field must equal the "
+        "recalculation: `totalCount` = number of original requirement ids; "
+        "`coveredCount` = rows with status `covered`; `coveragePercent` = "
+        "round(coveredCount / totalCount * 100, 2); `unmappedCommitments` = "
+        "commitment ids whose `requirementIds` is empty or names an id outside "
+        "the original set; `scopePrecisionPercent` = round((commitments - "
+        "unmapped) / commitments * 100, 2); `contradictedRequirements` = "
+        "original ids with status `contradicted`, in original order; "
+        "`coverageVerdict` = the first that applies of "
+        + ", ".join(f"`{verdict}`" for verdict in COVERAGE_VERDICT_PRECEDENCE)
+        + " (any contradicted; coveredCount below totalCount; any unmapped; "
+        "otherwise).",
+        "A ranked option is valid only when every participating analyser "
+        "supplied one feasibility vote, at least "
+        f"{MIN_FEASIBLE_VOTES} votes are `feasible`, and both `safetyBlockers` "
+        "and `unresolvedFeasibilityFacts` are empty.",
+        ("Classify each `unresolvedFeasibilityFacts` entry with `resolutionKind`: "
+        "`user-decision` requires nonempty `clarificationRefs` linking that fact "
+        "to actual C-NNN records, including answered records; `technical-verification` "
+        "requires no user question. Preserve the fact, whyItMatters, and evidence. "
+        "Historical unclassified facts remain readable but require classification "
+        "before blocked report reassembly. Saving does not lift blocked routing."),
+        ("After a linked decision is answered, preserve its disposition and selected "
+        "value. Update humanSummary.actions, verdictCard.nextStep, and selection "
+        "guidance to name remaining technical verification separately from unanswered "
+        "user decisions; never reopen an answered question to permit saving."),
+        "Each `feasibilityVotes` row states that analyser's own verdict, "
+        "rationale, and strongest counterevidence as its result gives them. "
+        "Two non-`uncertain` votes with identical rationale and "
+        "counterevidence are rejected as one worker's text copied under "
+        "another's name.",
+        f"Rank at most {MAX_RANKED_OPTIONS} valid options by descending "
+        "`requirement-fit`, `correctness-risk`, `architecture-fit`, "
+        "`weightedScore`, then id.",
+        "In `candidate-comparison`, keep `preselectedDirection` null. In "
+        "`preselected-validation`, emit exactly one validated option, an empty "
+        "`candidateAudit`, and a cited `preselectedDirection`.",
+        "Record candidate validity and selection mode; the lead chooses the next "
+        "phase under `## implementation-option-selection` in "
+        "`prompts/lead/phase-routing.md`.",
+    ]

package/runtime/python/okstra_ctl/phases/implementation_option_selection/boundary.json

@@ -0,0 +1,10 @@
+{
+  "allowed": "  - candidate-comparison evidence for up to three options per worker\n  - preselected-validation of exactly ONE candidate: every analyser returns its own feasibility verdict on that one direction, `candidateAudit` stays empty, and no analyser generates an alternative. It is not a re-evaluation of the merged set — `okstra_ctl.phases.implementation_option_selection.validation._validate_mode` rejects a preselected-validation report carrying more than one option or a non-empty audit\n  - a ranked display of at most three options with requirement mappings\n  - an audit record for every rejected candidate\n  - one endStateCoverage row per brief end-state id (this phase authors no goal of its own)",
+  "forbidden": [
+    "source or configuration edits, refactors, or fix attempts",
+    "tests, builds, migrations, deployments, or any state-mutating command",
+    "detailed file lists, stage maps, execution commands, or plan approval",
+    "starting `implementation-planning` or `implementation` inside this run",
+    "displaying more than three merged candidates or omitting rejected-candidate audit records"
+  ]
+}