okstra 0.165.2 → 0.165.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.165.2",
+  "version": "0.165.3",
   "description": "Host-aware multi-provider cross-verification orchestrator runtime and agent skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.165.2",
-  "builtAt": "2026-08-11T05:13:20.960Z",
+  "package": "0.165.3",
+  "builtAt": "2026-08-11T07:58:44.694Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/prompts/profiles/_implementation-diff-review.md

@@ -19,7 +19,7 @@ prompt (agents/workers/_cli-wrapper-template.md → Prompt Composition).
 
 # Pre-commit diff review sweep (BLOCKING — before the executor's final commit)
 
-Lint/test green is necessary but NOT sufficient — self-mocked tests, interaction-only assertions, untruthful names, and unreadable functions all pass a green pipeline. This sweep is what keeps them out of the diff. Run it once, after the last `Edit` / `Write` of the stage, before the final commit. Fix every finding in place (you are the executor — you may edit); this is a prevention pass, not a report you hand off.
+This is where the preflight's conventions get enforced against the code you actually wrote. Run it once, after the last `Edit` / `Write` of the stage, before the final commit. Fix every finding in place (you are the executor — you may edit); this is a prevention pass, not a report you hand off.
 
 Do not scan holistically and stop when it "looks fine". Work the matrix exhaustively — the failure mode this gate exists to prevent is a real defect surviving because you eyeballed the diff instead of enumerating it.
 
@@ -48,4 +48,4 @@ End your audit-sidecar entry for this sweep with a one-line `Coverage:` footer n
 
 ## Graceful degradation
 
-When the routed coding-preflight pack is unreadable (codex / antigravity runtime, or the files are absent), do NOT skip the sweep — apply the language-agnostic principles the preflight already listed (no self-mocking, behavioral assertions, truthful/standalone names, single-purpose ≤50-line functions) plus the project's `CLAUDE.md` / `CONTRIBUTING` / lint config, and record `diff-review: resource-unavailable → applied <agnostic principles + project rules>` with the Coverage footer. Never claim a resource read that did not happen.
+When the routed coding-preflight pack is unreadable (codex / antigravity runtime, or the files are absent), do NOT skip the sweep — fall back to the always-binding principles the preflight enumerates plus the project's `CLAUDE.md` / `CONTRIBUTING` / lint config, and record `diff-review: resource-unavailable → applied <agnostic principles + project rules>` with the Coverage footer.

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

@@ -19,17 +19,25 @@ until Phase 5 ends, then drop from active context for Phase 6/7.
 
 ## Pre-implementation context exploration (executor before first edit)
 
-- **Coding-conventions preflight (BLOCKING — runs before the first `Edit` / `Write`, and binds the TDD loop below).** The gate body is a single source at `prompts/profiles/_coding-conventions-preflight.md` (sibling of this sidecar). Do NOT re-type that content from memory — deliver it by file so it cannot drift or be dropped:
-  - **Native-session executor:** Read `_coding-conventions-preflight.md` end-to-end before the first edit, then state in ONE line which conventions apply (e.g. `Applying TS + hexagonal overlay; domain at src/domains/*/domain/`).
-  - **CLI-wrapper executor (BLOCKING):** the executor process does NOT share the lead's context, and it cannot read this sidecar's directory — that path sits outside the CLI sandbox and the CLI only sees its prompt, so a file reference never reaches it. The lead MUST physically append the **body** of `_coding-conventions-preflight.md` into the persisted executor prompt at dispatch time. Never hand-retype it. Enforcement: CLI wrapper agents refuse an implementation-Executor dispatch whose persisted prompt lacks the literal heading `Coding-conventions preflight`, returning `<SENTINEL_PREFIX>_PREFLIGHT_MISSING` (see `agents/workers/_cli-wrapper-template.md` → Prompt Composition).
-- **Pre-commit diff review sweep (BLOCKING — runs AFTER the last `Edit` / `Write`, BEFORE the final commit).** The gate body is a single source at `prompts/profiles/_implementation-diff-review.md` (sibling of this sidecar): an exhaustive file×rule sweep of the actual diff against the conventions the preflight loaded, with fix-in-place and a `Coverage:` footer. Do NOT re-type it from memory — deliver it by file so it cannot drift.
-  - **Native-session executor:** Read `_implementation-diff-review.md` end-to-end after the stage's last edit, run the sweep over `git diff <stage-base>..HEAD`, fix findings in place, and write its `Coverage:` footer to your audit sidecar before committing.
-  - **CLI-wrapper executor:** the CLI process cannot read this path outside its sandbox. The lead appends this file's body into the persisted executor prompt at dispatch time, between the preflight body and the self-check body (see `okstra_ctl.initial_prompt_materialization.materialize_initial_prompts()`). The head-less executor honours all three gates from the single prompt.
-- **Completion self-check (BLOCKING — runs BEFORE you claim the stage done).** The gate body is a single source at `prompts/profiles/_implementation-self-check.md` (sibling of this sidecar): the completion gate (diff-review Coverage footer present, functions ≤50 lines, conventions applied, truthful names & why-comments, real build/test run, cleanup). Do NOT re-type it from memory — deliver it by file so it cannot drift.
-  - **Native-session executor:** Read `_implementation-self-check.md` end-to-end before appending the `status:"done"` row, then write the confirming evidence per item to your audit sidecar.
-  - **CLI-wrapper executor:** the CLI process cannot read this path outside its sandbox. The lead appends this file's body into the persisted executor prompt at dispatch time, immediately after the diff-review body (see `okstra_ctl.initial_prompt_materialization.materialize_initial_prompts()`). The head-less executor honours all three gates from the single prompt.
-- **Stage discipline transcription (when a preceding stage is `done`):** the lead MUST transcribe the `Stage discipline` rule (from this run's rendered profile — the INCLUDEd `_stage-discipline.md` body) verbatim into every dispatched CLI-wrapper executor prompt so it honors the prior-stage behavior-freeze. Declaration-level — no wrapper sentinel.
-- **Non-interactive auto-execution (BLOCKING for `runner=cli-wrapper`).** A CLI-wrapper executor runs head-less — there is no human at the keyboard. Skills loaded during the run (tdd, coding-preflight, and others) contain "get user approval", "state your plan to the user and wait", or "ask before proceeding" gates written for interactive sessions; in this run those gates are **already satisfied** by the upstream `implementation-planning` approval (the plan this stage executes was human-approved). The executor MUST NOT stop to request approval, MUST NOT end its turn after only producing a plan, and MUST carry the stage through end-to-end — RED → GREEN → refactor → per-cycle commit → `### Stage Carry Evidence`. The ONLY skill step to skip is the interactive user-approval prompt itself; every other skill rule (TDD discipline, conventions, real-IO isolation) still binds. The lead MUST transcribe this bullet verbatim into the dispatched CLI-wrapper executor prompt (same reason as the preflight transcription rule above — the CLI process does not share lead context). Stopping early for approval in a head-less run is the observed empty-exit failure (exit 0, no diff): treat it as `contract-violated`.
+- **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.
+
+<!--
+Gate delivery (lead / maintainer — stripped before this body reaches a worker).
+`okstra_ctl.initial_prompt_materialization` appends all three bodies to the
+persisted executor prompt in that order under EAGER_INCLUDE, and lists their
+paths under `## Required prompt resources` under LAZY_PATH_REFERENCE; a CLI
+executor cannot read the profiles directory, so the file reference alone never
+reaches it. Enforcement: the CLI wrapper refuses an Executor dispatch whose
+persisted prompt lacks the heading `Coding-conventions preflight`
+(`<SENTINEL_PREFIX>_PREFLIGHT_MISSING`) or either post-write heading
+(`<SENTINEL_PREFIX>_POSTWRITE_GATE_MISSING`) — see
+`agents/workers/_cli-wrapper-template.md` → Prompt Composition.
+-->
+- **Stage discipline (when a preceding stage is `done`):** its code is behavior-frozen — you may call, extend, or compose with it, never change what it already does. The rule body travels with this prompt the same way the gates do (`prompts/profiles/_stage-discipline.md`); only its `implementation` bullet binds you, the `implementation-planning` one binds the planner. Declaration-level — no wrapper sentinel.
+- **Non-interactive auto-execution (BLOCKING for `runner=cli-wrapper`).** A CLI-wrapper executor runs head-less — there is no human at the keyboard. Skills loaded during the run (tdd, coding-preflight, and others) contain "get user approval", "state your plan to the user and wait", or "ask before proceeding" gates written for interactive sessions; in this run those gates are **already satisfied** by the upstream `implementation-planning` approval (the plan this stage executes was human-approved). The executor MUST NOT stop to request approval, MUST NOT end its turn after only producing a plan, and MUST carry the stage through end-to-end — RED → GREEN → refactor → per-cycle commit → `### Stage Carry Evidence`. The ONLY skill step to skip is the interactive user-approval prompt itself; every other skill rule (TDD discipline, conventions, real-IO isolation) still binds. Stopping early for approval in a head-less run is the observed empty-exit failure (exit 0, no diff): treat it as `contract-violated`.
 - **Mandatory TDD loop**: BEFORE the first `Edit` or `Write` call, the executor MUST apply a red-green-refactor loop for every code change in this run. This is required; skipping it is a `contract-violated` outcome. This governs HOW each step is executed (failing test first → minimal implementation → refactor); it does not override the approved plan's WHAT/file scope.
   - Order of operations per plan step: (1) write/extend the test that captures the step's acceptance criterion and confirm it fails for the right reason, (2) implement the minimum change to make it pass, (3) commit the test and its implementation together in a single commit (`feat|fix(<scope>): ...`) — do NOT commit the failing test separately, (4) refactor without changing behaviour and commit separately if any cleanup is made (`refactor(<scope>): ...`). The failing-then-passing transition is preserved as `TDD evidence` in the final report (failing output captured before the merged commit, passing output after), not as two separate commits.
   - Doc-only / config-only / pure-rename steps that have no observable runtime behaviour are exempt from the failing-test requirement, but the executor MUST cite the exemption per step in the final report (`TDD exemption: <reason>`).
@@ -37,10 +45,10 @@ until Phase 5 ends, then drop from active context for Phase 6/7.
 - **DB / IO / SQL changes require real execution — mock-only is NOT validation evidence:** when this run's diff touches DB/IO/SQL (ORM / query-builder code — sequelize / typeorm / prisma / knex / raw SQL — `*.repository.*`, model/entity files, `migrations/**`, `*.sql`, or any changed query string), a mocked unit test cannot observe the SQL the query builder actually emits (observed failure class: `_implementation-verifier.md` §"DB / IO / SQL change — real-execution gate"). The executor MUST run the change against a real (or faithful-replica) datastore — the `db-test` validation step (plan `validation` db step, else `project.json.qaCommands.db-test`), targeting a **local / replica** DB — and cite its exact command + exit code in the final report's `Validation evidence`. If no real DB / `db-test` command is reachable, do NOT claim the change verified: label the DB portion `static-analysis only …, unverified (not executed)` in the report, surface it in the routing recommendation, and never downplay the real run as "too heavy". `git push` stays forbidden (universal list); the unverified DB state is carried forward so `final-verification` cannot accept it and `release-handoff` cannot push.
 - **External-source adapters — structure AND fixture both derive from a captured real sample; a self-authored fixture is NOT reality evidence:** when this run's diff builds or changes an `external-interface` or `transformation-mapping` surface (an HTTP / network client, or a parser / mapper of a third-party payload — HTML / JSON / XML / CSV originating outside this repo), the adapter's structural assumptions (selectors, field paths, expected response shape) AND the static fixture / golden that tests them MUST BOTH derive from a **captured real sample** of that payload — the capture cited in the stage's `external-interface` / `transformation-mapping` design-prep item, or one captured this run and recorded with its `source` + capture time. The captured sample is a static fixture (no live socket), so a parser test against it stays in source like any unit test — the Real-IO isolation rule below governs *live* calls, not the captured bytes. Do NOT hand-invent the shape and then hand-write a fixture that agrees with it: the passing test then only proves the code matches your assumption, never that the assumption matches reality (self-confirming oracle — the observed failure was a parser whose selectors existed in its synthetic fixture and in zero real pages: hundreds of green units over a fiction, and the whole structure built on the wrong shape). When no real sample is reachable (no network this run, or the brief supplied none), do NOT synthesize a stand-in and present its green tests as correctness: mark the adapter's shape `reality-unverified (no captured sample)` in `Validation evidence`, keep any placeholder fixture explicitly labelled an assumption (never validation evidence), and surface an explicit **user-owned** item in the routing recommendation to confirm against real data. Unlike the DB gate above this does NOT itself block acceptance — live external verification stays a user-owned item per `final-verification`'s External QA advisory policy — but a synthetic external fixture presented as reality-verified is exactly the mock-only external evidence the `final-verification` test-correctness pass is meant to reject.
 - **Real-IO test isolation (BLOCKING).** A test that exercises a **real** datastore, HTTP endpoint, external service, message queue, or filesystem — a live DB connection / DSN, a real `fetch` / `axios` / `http` request, an actual S3 / queue client, anything the project's normal CI test suite cannot run because that backend is absent — MUST be written under the task's qa scripts directory `<task_root>/qa/scripts/` (`<TASK_QA_PATH>/scripts`; the `qa/` root itself holds only data sidecars — the Tier 3 conformance manifest and `result-*.json`). It MUST NOT be written into the project source test tree — `src/**`, `test/**`, `tests/**`, `**/__test__/**`, `**/__tests__/**`, `*.spec.*`, `*.test.*`, or anywhere the project's lint/test globs collect. Two reasons: (a) the project's CI / normal suite has no real DB or network, so a real-IO test placed in source silently breaks the pipeline; (b) it is an okstra verification artifact, and the artifact-home rule confines okstra outputs to `.okstra/`. **The dividing line is the IO, not the intent:** a unit test that stubs/spies only *injected collaborators* (mock — no real socket, no real DB handle) is a TDD red-green artifact and stays in source; the moment a test opens a real connection or makes a real network call it belongs in qa. A stage's real-IO requirement check is a Tier 3 conformance script under `<task_root>/qa/scripts/` (declared via the implementation-planning conformance entry) — never smuggle real IO into a `*.spec.*` in source to make it run "as a unit test". The `db-test` real-execution gate above is satisfied by the conformance/db-test path against the replica, NOT by adding a live-DB `*.spec.*` to the project suite. **Author qa specs with the project's own test framework — never hand-roll `describe`/`it`/`expect`.** When the project ships a test runner as a devDependency (jest / vitest / pytest …), the qa spec uses it, invoked with the project config plus a discovery override pointing at the qa scripts dir (jest: `npx jest --config <project jest config> --roots <task_root>/qa/scripts --runInBand <spec-name>`) — the project config keeps module aliases resolving while the default sweep never collects the file; never widen the project's own test config to include qa paths. For TypeScript qa specs also write `<task_root>/qa/scripts/tsconfig.json` (`extends` the project tsconfig, adds the runner's `types` entry, `"include": ["**/*.ts"]`) so editors resolve path aliases and test globals — it is a qa artifact like the rest (untracked). **These qa artifacts stay untracked — never commit them.** `.okstra/**` is gitignored (the artifact-home rule); conformance scripts and their results are *executed* and recorded in the carry sidecar / verifier result, never written into git history. A committed `.okstra/qa` file is a stage-branch defect that leaks okstra internals into the eventual PR (see the `git add` rules below).
-- re-read the approved plan end-to-end and parse the `## 5.5 Stage Map`. Read the **Stage** injected in the launch prompt (`Stage for this implementation run`): the single stage number this run owns. The runtime already selected and reserved this stage (one run = one stage) — do NOT recompute the start stage from `consumers.jsonl`.
+- read the approved plan at this prompt's `**Approved plan:**` anchor end-to-end and parse the `## 5.5 Stage Map`. Read this prompt's `**Stage for this implementation run:**` anchor: the single stage number this run owns. The runtime already selected and reserved this stage (one run = one stage) — do NOT recompute the start stage from `consumers.jsonl`. Both anchors are generated headers; when either is missing, stop and report `contract-violated` rather than inferring the value.
   - load every `runs/<plan-key>/carry/stage-<i>.json` for `i ∈ depends-on(this stage)` and inject them into the executor's working context as "runtime carry-in". For a `depends-on (none)` stage, no sidecar load — task-brief only.
   - this stage's `depends-on` are all already `status:done`. Its file list, step order, Stage Validation commands, Stage Exit Contract, and rollback path are the authoritative scope.
-- **Clarification answers carried in (read before the first edit; inlined for CLI executors):** when `instruction-set/clarification-response.md` exists, it carries the user's answers to the approved plan's `## 1. Clarification Items` rows (the planning HTML form's `# Attached User Responses`). Treat each answer as an authoritative refinement of the plan's scope for the matching row; an answer that contradicts or expands the approved scope beyond the plan is a re-plan trigger (route to a new `implementation-planning` run), not a silent in-run change. **CLI executor (codex/antigravity):** that file sits outside the CLI sandbox, so the lead MUST transcribe its body into the dispatched executor prompt at dispatch time (same rule as the preflight / stage-discipline transcription above) — a path reference never reaches the CLI process.
+- **Clarification answers carried in (read before the first edit):** when the user answered the approved plan's `## 1. Clarification Items` rows, those answers arrive with this prompt under the heading `# Clarification answers carried in (authoritative)`, or as the `Clarification response` path under `## Inputs`. Treat each answer as an authoritative refinement of the plan's scope for the matching row; an answer that contradicts or expands the approved scope beyond the plan is a re-plan trigger (route to a new `implementation-planning` run), not a silent in-run change.
 - **Effective design preparation (runtime-resolved after stage selection):**
 
 {{DESIGN_PREP_CONTEXT}}
@@ -52,7 +60,6 @@ until Phase 5 ends, then drop from active context for Phase 6/7.
   - **drift rule** (this section): if a file *named in the plan* has materially drifted, refuse to edit and route back to planning. This protects trust in the approved scope.
   - **out-of-plan rule** (Allowed actions section below): if a step *requires touching a file NOT in the plan list*, that is permitted with `Out-of-plan edits` justification. This handles honest scope discovery during execution.
 - confirm the test/build commands referenced in the plan still exist and run from a clean state
-- **Pre-commit diff review sweep (BLOCKING before the executor's final commit):** run the sweep whose body is delivered via `_implementation-diff-review.md` (see the gate-delivery bullet above) over the run diff (`git diff <stage-base>..HEAD`), and fix findings in place before handing to verifiers when the issue is inside this stage's scope. That sidecar is the single source for the sweep's file×rule matrix (DRY / self-mock / behavioral-test / hexagonal / truthful-name / plain-English rules) and its `Coverage:` footer — do not maintain a second copy of the rule list here.
 
 ## Stage execution contract (this run owns one stage)
 

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

@@ -23,7 +23,7 @@ Every verifier acts as a QA gate, not just a diff reviewer. Trusting the executo
 
 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).
+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.
 2. **Tier 2 — project baseline (`project.json.qaCommands`):** the project's standing QA baseline declared in `<PROJECT_ROOT>/.okstra/project.json` under the `qaCommands` key. Schema (each category is an array of `{ "label", "cmd", "language"? }` objects):
    ```json
    {
@@ -234,6 +234,6 @@ If every verifier present in the resolved roster ends with a non-result terminal
 - running integration / end-to-end tests that produce non-local side effects (DB writes against a non-local datastore, external API writes, docker compose against a non-isolated environment) unless that exact command is listed in the approved plan's validation set
 - redirecting tool caches or output to paths outside the worktree — e.g. setting `CARGO_TARGET_DIR`, `PYTEST_CACHE_DIR`, `NODE_OPTIONS=--require=<external>`, or any env var that causes the verifier's command to write outside the worktree's normal build artifact paths
 
-## Completion self-check (declaration)
+## Executor completion self-check (not this role's gate)
 
-- **Completion self-check (declaration).** If this verifier edits project code (not just inspects it), the same completion gate at `prompts/profiles/_implementation-self-check.md` binds before claiming done — same four items, recorded in the audit sidecar.
+- 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.

package/runtime/prompts/profiles/_stage-discipline.md

@@ -1,8 +1,9 @@
 <!--
 Shared stage-discipline rule. INCLUDEd by implementation-planning.md (binds the
-planner) and implementation.md (binds the lead). The implementation executor
-sidecar instructs the lead to transcribe this rule into a CLI executor prompt,
-since codex/antigravity executors do not share lead context.
+planner) and implementation.md (binds the lead). `okstra_ctl.initial_prompt_-
+materialization` also delivers this body to every implementation executor
+prompt as a required resource, because a codex/antigravity executor shares no
+lead context and cannot read the rendered profile.
 
 Do NOT write the literal include directive token in this file's body — the
 resolver matches it anywhere and would recurse on this file itself.

package/runtime/python/okstra_ctl/domain/wizard/interaction.py

@@ -49,18 +49,30 @@ class WizardAnswerError(ValueError):
     """Raised when an answer violates the interaction plan's protocol."""
 
 
+def _exact_value_match(prompt: WizardPrompt, candidate: str) -> str | None:
+    for option in prompt.options:
+        if option.value == candidate:
+            return option.value
+    return None
+
+
 def _normalize_numbered_item(prompt: WizardPrompt, answer: str) -> str:
     candidate = (answer or "").strip()
-    exact_values = tuple(
-        option.value for option in prompt.options if option.value == candidate
-    )
-    if exact_values:
-        return exact_values[0]
+    # A bare number is the position in the list the user was shown. Matching
+    # option values first breaks every picker whose values are themselves
+    # numbers — a stage picker resolves "1" to stage 1 while the user was
+    # pointing at line 1, which is a different stage (or "every stage").
     if candidate.isdecimal():
         number = int(candidate)
         if 1 <= number <= len(prompt.options):
             return prompt.options[number - 1].value
+        out_of_list = _exact_value_match(prompt, candidate)
+        if out_of_list is not None:
+            return out_of_list
         raise WizardAnswerError(f"numbered-text answer is out of range: {candidate}")
+    exact_value = _exact_value_match(prompt, candidate)
+    if exact_value is not None:
+        return exact_value
     label_values = tuple(
         option.value for option in prompt.options if option.label == candidate
     )

package/runtime/python/okstra_ctl/implementation_stage.py

@@ -17,6 +17,7 @@ from . import stage_targets
 from .design_prep import DesignPrepDecision, DesignPrepError, resolve_design_prep
 from .final_report_paths import final_report_data_path
 from .stage_reconcile import auto_reconcile_best_effort
+from .worker_prompt_policy import IMPLEMENTATION_STAGE_HEADER
 
 
 class ImplementationStageError(Exception):
@@ -250,7 +251,7 @@ def publish_stage_run_claim(
     ctx["EFFECTIVE_STAGES"] = csv
     ctx["CONCURRENT_RUN_STAGES"] = ",".join(str(s) for s in claim.concurrent_stages)
     ctx["STAGE_BATCH_DIRECTIVE"] = (
-        f"- **Stage for this implementation run:** `{csv}`. "
+        f"- {IMPLEMENTATION_STAGE_HEADER} `{csv}`. "
         "Execute exactly this Stage Map stage — this is the authoritative scope. "
         "Do NOT recompute from `consumers.jsonl`; the runtime already selected "
         "and reserved this stage."

package/runtime/python/okstra_ctl/initial_prompt_materialization.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 
 import json
 import os
+import re
 import tempfile
 from dataclasses import dataclass
 from enum import Enum
@@ -20,7 +21,12 @@ from .worker_prompt_body import (
 )
 from .worker_prompt_contract import PromptRecord, validate_initial_prompt_records
 from .worker_prompt_headers import worker_prompt_headers
-from .worker_prompt_policy import PromptPlan, resolve_prompt_plan_for_manifest
+from .worker_prompt_policy import (
+    APPROVED_PLAN_HEADER,
+    IMPLEMENTATION_STAGE_HEADER,
+    PromptPlan,
+    resolve_prompt_plan_for_manifest,
+)
 
 
 class PromptDeliveryMode(str, Enum):
@@ -94,6 +100,7 @@ _CLARIFICATION_AUTHORITY_INTRO = (
 )
 _CLARIFICATION_SOURCE_PREFIX = "Source:"
 _REQUIRED_PROMPT_RESOURCES_HEADING = "## Required prompt resources"
+_HTML_COMMENTS = re.compile(r"<!--.*?-->\n?", re.DOTALL)
 
 
 @dataclass(frozen=True)
@@ -323,7 +330,7 @@ def _render_prompt(
         lines.append(
             f"**Prompt Delivery Mode:** {context.request.delivery_mode.value}"
         )
-        lines.extend(_worktree_lines(context, item.plan))
+        lines.extend(_implementation_anchor_lines(context, item.plan))
         lines.extend(_prompt_body(context, state, worker, item.plan))
         lines.extend(_resource_lines(context, item))
     except InitialPromptMaterializationError:
@@ -467,12 +474,27 @@ def _resolve_prompt_resources(
     return tuple(
         _PromptResource(
             path=path.resolve(),
-            text=_read_required_nonempty_text(path, "required prompt resource"),
+            text=_worker_visible_text(
+                _read_required_nonempty_text(path, "required prompt resource")
+            ),
         )
         for path in paths
     )
 
 
+def _worker_visible_text(text: str) -> str:
+    """Strip lead-and-maintainer-only passages before a body reaches a worker.
+
+    These sidecars have two readers: the lead lazy-reads the file to run the
+    phase, and the worker receives the same body inlined in its prompt. An
+    HTML comment is the seam between them — rendered markdown hides it, so it
+    holds the delivery plumbing (which path feeds this file, which heading the
+    CLI wrapper greps for) that the worker would otherwise pay for and read as
+    an instruction addressed to itself.
+    """
+    return _HTML_COMMENTS.sub("", text).lstrip("\n")
+
+
 def _required_resource_path_candidates(
     context: _MaterializationContext,
     plan: PromptPlan,
@@ -481,15 +503,17 @@ def _required_resource_path_candidates(
     if plan.audience == "implementation-executor":
         paths = (
             _executor_profile_path(context),
+            profiles / "_stage-discipline.md",
             profiles / "_coding-conventions-preflight.md",
             profiles / "_implementation-diff-review.md",
             profiles / "_implementation-self-check.md",
         )
     elif plan.audience == "implementation-verifier":
-        paths = (
-            profiles / "_implementation-verifier.md",
-            profiles / "_implementation-self-check.md",
-        )
+        # The self-check body is executor-only: it is written to the worker that
+        # owns the diff ("fix it or surface the violation", break-and-restore
+        # mutation checks), and a verifier is barred from every edit it asks
+        # for. Its own blocking taxonomy is inlined in the verifier sidecar.
+        paths = (profiles / "_implementation-verifier.md",)
     else:
         return ()
     return paths
@@ -873,15 +897,35 @@ def _result_paths(
     return str(final_report_data_path(Path(expected_report))), worker_result
 
 
-def _worktree_lines(
+def _implementation_anchor_lines(
     context: _MaterializationContext,
     plan: PromptPlan,
 ) -> list[str]:
+    """Render the anchors only an implementation audience carries.
+
+    The approved plan and the stage number are absolute here because a CLI
+    worker's cwd is the stage worktree, where a `.okstra/...` relative path
+    resolves against the wrong root.
+    """
     if plan.audience not in {
         "implementation-executor",
         "implementation-verifier",
     }:
         return []
+    worktree = _required_worktree_path(context)
+    lines = [f"**Worktree:** {worktree}"]
+    if plan.audience == "implementation-executor":
+        lines.append(f"cwd for every mutating command: {worktree}")
+    lines.append(
+        f"{APPROVED_PLAN_HEADER} {_required_approved_plan_path(context)}"
+    )
+    lines.append(
+        f"{IMPLEMENTATION_STAGE_HEADER} {_required_stage_number(context)}"
+    )
+    return lines
+
+
+def _required_worktree_path(context: _MaterializationContext) -> str:
     executor_worktree = context.active_context.get("executorWorktree")
     value = (
         _string_value(executor_worktree.get("path"))
@@ -893,10 +937,58 @@ def _worktree_lines(
             "required_input_missing",
             "implementation prompt generation requires a worktree path",
         )
-    lines = [f"**Worktree:** {value}"]
-    if plan.audience == "implementation-executor":
-        lines.append(f"cwd for every mutating command: {value}")
-    return lines
+    return value
+
+
+def _required_approved_plan_path(context: _MaterializationContext) -> str:
+    """Read the approved plan path from this run's user-input snapshot.
+
+    run-inputs owns it because it is a user input, not a rendered path — and
+    reading it there also keeps runs prepared before this anchor existed
+    materializable, since every run has always recorded it.
+    """
+    source_artifacts = context.active_context.get("sourceArtifacts")
+    run_inputs_rel = (
+        _string_value(source_artifacts.get("runInputsPath"))
+        if isinstance(source_artifacts, Mapping)
+        else ""
+    )
+    if not run_inputs_rel:
+        raise InitialPromptMaterializationError(
+            "required_input_missing",
+            "implementation prompt generation requires a run inputs path",
+        )
+    payload = _load_json_object(
+        _resolve_input_path(context.project_root, Path(run_inputs_rel)),
+        "run inputs",
+    )
+    inputs = payload.get("inputs")
+    value = (
+        _string_value(inputs.get("approvedPlanPath"))
+        if isinstance(inputs, Mapping)
+        else ""
+    )
+    if not value:
+        raise InitialPromptMaterializationError(
+            "required_input_missing",
+            "implementation prompt generation requires an approved plan path",
+        )
+    return str(_resolve_input_path(context.project_root, Path(value)))
+
+
+def _required_stage_number(context: _MaterializationContext) -> str:
+    value = _string_value(_active_run_field(context, "stage"))
+    if not value:
+        raise InitialPromptMaterializationError(
+            "required_input_missing",
+            "implementation prompt generation requires a stage number",
+        )
+    return value
+
+
+def _active_run_field(context: _MaterializationContext, key: str) -> Any:
+    run = context.active_context.get("run")
+    return run.get(key) if isinstance(run, Mapping) else ""
 
 
 def _prompt_plan(

package/runtime/python/okstra_ctl/path_hints.py

@@ -95,7 +95,7 @@ def hydrate_active_run_context(payload: Mapping[str, Any]) -> dict[str, Any]:
         "kind": ACTIVE_CONTEXT_KIND,
         "task": _hydrate_active_task(payload, ctx),
         "workflow": dict(_mapping(payload.get("workflow"))),
-        "run": _hydrate_active_run(ctx),
+        "run": _hydrate_active_run(payload, ctx),
         "instructionSet": _hydrate_active_instruction_set(payload, ctx),
         "workers": _hydrate_active_workers(payload, ctx),
         "errorLogs": _hydrate_active_error_logs(ctx),
@@ -182,8 +182,16 @@ def _hydrate_active_task(payload: Mapping[str, Any], ctx: Mapping[str, str]) ->
     return task
 
 
-def _hydrate_active_run(ctx: Mapping[str, str]) -> dict[str, str]:
+def _hydrate_active_run(
+    payload: Mapping[str, Any],
+    ctx: Mapping[str, str],
+) -> dict[str, str]:
+    # `stage` is a run input, not a derived path, so pathHints cannot rebuild
+    # it — it survives the round trip only by being read back off the compact
+    # payload.
+    run = _mapping(payload.get("run"))
     return {
+        "stage": str(run.get("stage", "") or ""),
         "runDirectoryPath": ctx.get("RUN_DIR_RELATIVE_PATH", ""),
         "runManifestPath": ctx.get("RUN_MANIFEST_RELATIVE_PATH", ""),
         "teamStatePath": ctx.get("TEAM_STATE_RELATIVE_PATH", ""),

package/runtime/python/okstra_ctl/render.py

@@ -506,6 +506,11 @@ def _active_workflow(ctx: dict) -> dict:
 
 def _active_run(ctx: dict) -> dict:
     return {
+        # `implementation` binds one run to one Stage Map stage, and the
+        # executor prompt has to name it: its sidecar forbids recomputing the
+        # stage from `consumers.jsonl`. Feeds the implementation prompt anchor
+        # in `initial_prompt_materialization`.
+        "stage": ctx.get("RUN_STAGE", ""),
         "runDirectoryPath": ctx.get("RUN_DIR_RELATIVE_PATH", ""),
         "runManifestPath": ctx.get("RUN_MANIFEST_RELATIVE_PATH", ""),
         "teamStatePath": ctx.get("TEAM_STATE_RELATIVE_PATH", ""),

package/runtime/python/okstra_ctl/stage_map.py

@@ -367,8 +367,14 @@ def parse_stage_map_file(markdown_path: Path) -> list[StageMapStage]:
     return _parse_schema_v2_stage_map(data, str(data_path))
 
 
-def _schema_v2_report(markdown_path: Path) -> dict[str, Any]:
-    """The schema-v2 sidecar as a whole, `{}` for a v1 report."""
+def schema_v2_report(markdown_path: Path) -> dict[str, Any]:
+    """The schema-v2 sidecar as a whole, `{}` for a v1 report.
+
+    Public because every caller that must branch on report schema needs it —
+    including `validators/validate-implementation-plan-stages.py`, which is a
+    separate process and cannot reach a private helper without copying the
+    sidecar-detection rule and letting the two drift.
+    """
     data_path = Path(markdown_path).resolve().with_suffix(".data.json")
     if not data_path.exists():
         return {}
@@ -383,7 +389,7 @@ def _schema_v2_report(markdown_path: Path) -> dict[str, Any]:
 
 def _planning_section(markdown_path: Path) -> dict[str, Any]:
     """The report's `implementationPlanning` block, `{}` for v1."""
-    planning = _schema_v2_report(markdown_path).get("implementationPlanning")
+    planning = schema_v2_report(markdown_path).get("implementationPlanning")
     return planning if isinstance(planning, dict) else {}
 
 
@@ -407,7 +413,7 @@ def _stage_narratives(value: Any) -> dict[int, dict[str, Any]]:
 
 def load_planning_detail(markdown_path: Path) -> PlanningDetail:
     """Read one report's narrative rows; empty for a schema-v1 report."""
-    report = _schema_v2_report(markdown_path)
+    report = schema_v2_report(markdown_path)
     planning = report.get("implementationPlanning")
     if not isinstance(planning, dict) or not planning:
         return PlanningDetail({}, {})

package/runtime/python/okstra_ctl/wizard.py

@@ -4484,11 +4484,28 @@ def _reset_from(state: WizardState, target_step: str) -> None:
     idx = next((i for i, s in enumerate(STEPS) if s.id == target_step), -1)
     if idx < 0:
         return
+    # A later step may own a field an earlier answered step also owns —
+    # `handoff_stage_pick` owns `approved_plan_path` because it resolves the
+    # plan on its own. Clearing it while rewinding to a step in front of it
+    # drops an answer the user never revisited; the rewound step then fails its
+    # own `applies` guard, so no step is left to ask and the wizard reports
+    # done while `outcome` still refuses it as incomplete.
+    owned_earlier = {
+        fname
+        for step in STEPS[:idx]
+        if step.id in state.answered
+        for fname in step.owns
+    }
     cleared_ids: set[str] = set()
-    for step in STEPS[idx:]:
+    for position, step in enumerate(STEPS[idx:]):
         cleared_ids.add(step.id)
+        is_rewind_target = position == 0
         for fname in step.owns:
-            _reset_field(state, fname)
+            # The target's own fields always clear — that is the answer the
+            # user came back to replace, even when an earlier step declares it
+            # too (`task_pick` derives `task_type` for an existing task).
+            if is_rewind_target or fname not in owned_earlier:
+                _reset_field(state, fname)
     state.answered = [a for a in state.answered if a not in cleared_ids]
     direct_input_pending = {
         S_FEATURE_EVIDENCE: "feature_evidence_pending_text",

package/runtime/python/okstra_ctl/worker_prompt_body.py

@@ -11,6 +11,21 @@ ANALYSIS_WORKER_LABELS = {
     "codex": "Codex worker",
     "antigravity": "Antigravity worker",
 }
+# An implementation audience shares this body but not its premise: the executor
+# owns the diff and the verifier grades it, so neither is producing one of the
+# independent findings that cross-verification triangulates.
+ROLE_STATEMENTS = {
+    "executor": (
+        "You are the Executor for this implementation stage — the only worker "
+        "permitted to mutate project files. Carry the stage end to end and "
+        "produce the worker result."
+    ),
+    "verifier": (
+        "You are a verifier for this implementation stage. Reproduce its QA "
+        "yourself, stay read-only on project files, and return an independent "
+        "verdict."
+    ),
+}
 
 
 def analysis_prompt_body(
@@ -30,10 +45,7 @@ def analysis_prompt_body(
         f"# {label} Dispatch",
         "",
         "## Role",
-        (
-            f"You are the {label} for okstra cross-verification. "
-            "Produce an independent worker result."
-        ),
+        _role_statement(label, role),
         "",
         "## Task",
         f"- Task key: `{_require_string(manifest, 'taskKey')}`",
@@ -52,6 +64,14 @@ def analysis_prompt_body(
     ]
 
 
+def _role_statement(label: str, role: str) -> str:
+    return ROLE_STATEMENTS.get(
+        role,
+        f"You are the {label} for okstra cross-verification. "
+        "Produce an independent worker result.",
+    )
+
+
 def analysis_input_lines(
     manifest: Mapping[str, Any],
     active_context: Mapping[str, Any],

package/runtime/python/okstra_ctl/worker_prompt_contract.py

@@ -8,6 +8,7 @@ from typing import Any, Mapping, Sequence
 
 from .worker_prompt_policy import (
     ERRORS_PATH_HEADERS,
+    IMPLEMENTATION_HEADERS,
     PromptPlan,
     resolve_prompt_plan_for_manifest,
 )
@@ -51,7 +52,7 @@ _NON_BODY_PREFIXES = (
     *ERRORS_PATH_HEADERS,
     "**Read scope:**",
     "**File write mode:**",
-    "**Worktree:**",
+    *IMPLEMENTATION_HEADERS,
     "**Verification scope:**",
     "**Verification base ref:**",
     "**Verification head ref:**",

package/runtime/python/okstra_ctl/worker_prompt_policy.py

@@ -27,6 +27,17 @@ ERRORS_PATH_HEADERS = (
     "**Errors log path:**",
     "**Errors sidecar path:**",
 )
+# The executor sidecar tells the worker to execute exactly one Stage Map stage
+# against the approved plan, and forbids recomputing that stage from
+# `consumers.jsonl`. Both facts therefore have to reach the worker prompt
+# itself: the lead's launch prompt carries them, and no worker reads that.
+APPROVED_PLAN_HEADER = "**Approved plan:**"
+IMPLEMENTATION_STAGE_HEADER = "**Stage for this implementation run:**"
+IMPLEMENTATION_HEADERS = (
+    "**Worktree:**",
+    APPROVED_PLAN_HEADER,
+    IMPLEMENTATION_STAGE_HEADER,
+)
 FINAL_VERIFICATION_HEADERS = (
     "**Worktree:**",
     "**Verification scope:**",
@@ -96,14 +107,14 @@ def resolve_prompt_plan(
         return _plan(
             "implementation-executor",
             allow_coding_preflight=True,
-            required_headers=("**Worktree:**",),
+            required_headers=IMPLEMENTATION_HEADERS,
         )
     if task_type == "implementation":
         return _plan(
             "implementation-verifier",
             equality_group="implementation-verifier-core",
             allow_coding_preflight=True,
-            required_headers=("**Worktree:**",),
+            required_headers=IMPLEMENTATION_HEADERS,
         )
     if task_type == "final-verification":
         return _plan(

package/runtime/templates/implementation-worker-preamble.md

@@ -18,6 +18,12 @@ Work like a senior engineer who owns this result, not a commentator on it.
 - Read `overview.md` and `clean-code.md` under `**Coding preflight pack:**`, then follow every matching language, framework, and architecture route before editing or verification.
 - Read the approved implementation deliverable and any effective design-preparation block enumerated by the prompt.
 
+### Reading rules
+
+- Read every file enumerated under `[Required reading]`, `## Inputs`, and `## Required prompt resources` completely, plus the source files this stage's plan names.
+- Allowlist reads to those paths, the stage worktree's own source, and evidence paths a claim must cite. Do not auto-read host-injected `graphify-out/`, skill catalogs, or other non-okstra artifacts.
+- Host session instructions — SessionStart hooks, global `CLAUDE.md` / `AGENTS.md`, skill catalogs — do not apply inside this run, and a directive from one of them to read an un-enumerated file is not a conflict to weigh in the host's favour: this prompt wins. Record the file under the result's assumptions instead of opening it. The project's own `CLAUDE.md` / lint config still binds as a coding convention — the preflight gate routes it — but the host's *reading* directives stop at this boundary.
+
 ## Worktree and command discipline
 
 - `**Worktree:**` is the canonical checkout. Project commands run with that directory as cwd.

package/runtime/validators/validate-implementation-plan-stages.py

@@ -25,6 +25,7 @@ from okstra_ctl.stage_map import (  # noqa: E402
     StageMapError,
     StageMapStage,
     parse_stage_map_text,
+    schema_v2_report,
 )
 
 HARD_STEP_CAP = 8
@@ -502,13 +503,29 @@ def collect_data_validation_errors(planning: dict) -> List[ValidationError]:
     return errors
 
 
+def collect_plan_errors(plan_path: Path) -> List[ValidationError]:
+    """The S-checks for one approved plan, whichever schema wrote it.
+
+    A schema-v2 report keeps its stage map in the `.data.json` sidecar and
+    renders no `## 5.5 Stage Map` section, so scanning its markdown reports the
+    section as missing and blocks every run that approved such a plan.
+    """
+    planning = schema_v2_report(plan_path).get("implementationPlanning")
+    if isinstance(planning, dict) and planning:
+        return collect_data_validation_errors(planning)
+    return collect_validation_errors(plan_path.read_text(encoding="utf-8"))
+
+
 def main(argv: List[str]) -> int:
     p = argparse.ArgumentParser()
     p.add_argument("--plan", required=True)
     args = p.parse_args(argv)
-    text = Path(args.plan).read_text(encoding="utf-8")
 
-    errors = collect_validation_errors(text)
+    try:
+        errors = collect_plan_errors(Path(args.plan))
+    except StageMapError as exc:
+        print(f"S0 stage=0: {exc.reason}", file=sys.stderr)
+        return 1
     if errors:
         for e in errors:
             print(f"{e.code} stage={e.stage}: {e.message}", file=sys.stderr)

package/src/commands/execute/wizard.mjs

@@ -22,7 +22,7 @@ Usage:
   okstra wizard new-state-file
   okstra wizard init --state-file <path> --project-root <p> --project-id <id> --host-runtime <runtime> \\
     --entry-mode current-session --available-function <semantic-name>
-  okstra wizard step --state-file <path> [--answer <value>]
+  okstra wizard step --state-file <path> (--answer <value> | --no-submit)
   okstra wizard render-args --state-file <path>
   okstra wizard confirmation --state-file <path>
   okstra wizard outcome --state-file <path>
@@ -34,11 +34,14 @@ All subcommands emit a single JSON object on stdout. On validation failure
 'step' returns {ok:false, error, current} so the skill can re-prompt.
 `;
 
-// Every wizard flag takes a value (there are no boolean flags), so the token
-// after a flag is always its value — even free-text answers that begin with
-// "--". A heuristic that rejects "--"-prefixed values would make legitimate
-// directive/base-ref answers unsubmittable. The inline "--key=value" form lets
-// callers pass any value (including empty) unambiguously.
+// Only the flags listed here are boolean; every other wizard flag takes a
+// value, so the token after it is always its value — even free-text answers
+// that begin with "--". A heuristic that rejects "--"-prefixed values would
+// make legitimate directive/base-ref answers unsubmittable. The inline
+// "--key=value" form lets callers pass any value (including empty)
+// unambiguously.
+const BOOLEAN_FLAGS = new Set(["no-submit"]);
+
 export function parseFlags(args) {
   const out = {};
   const setFlag = (key, value) => {
@@ -59,6 +62,10 @@ export function parseFlags(args) {
       continue;
     }
     const key = a.slice(2);
+    if (BOOLEAN_FLAGS.has(key)) {
+      out[key] = true;
+      continue;
+    }
     if (i + 1 >= args.length) {
       throw new Error(`flag --${key} requires a value`);
     }
@@ -81,8 +88,13 @@ export function buildPythonArgs(sub, flags, workspaceRoot = "") {
       pyArgs.push("--available-function", value);
     }
     pyArgs.push("--entry-mode", flags["entry-mode"] ?? "current-session");
-  } else if (sub === "step" && flags.answer !== undefined) {
-    pyArgs.push("--answer", flags.answer);
+  } else if (sub === "step") {
+    if (flags["no-submit"]) {
+      pyArgs.push("--no-submit");
+    }
+    if (flags.answer !== undefined) {
+      pyArgs.push("--answer", flags.answer);
+    }
   }
   return pyArgs;
 }