okstra 0.165.2 → 0.165.4

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/team.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 
 import argparse
 import json
+import subprocess
 import sys
 from pathlib import Path
 from typing import Any, Mapping, Sequence
@@ -202,11 +203,11 @@ def _reclaimable_panes(
 ) -> list[dict[str, str]]:
     """Everything this run owns and may close.
 
-    Under cmux the recorded ids are the whole list. There is no per-pane tag API
-    to sweep with, and scanning by title would be worse than nothing: cmux labels
-    its own agent surfaces with the same glyph okstra's tmux cleanup treats as a
-    teammate marker, so a sweep could close the lead. Only surfaces okstra
-    created are recorded, so only those can be closed.
+    Under cmux the recorded ids are the only candidates. There is no per-pane tag
+    API to sweep with, and scanning by title would be worse than nothing: cmux
+    labels its own agent surfaces with the same glyph okstra's tmux cleanup
+    treats as a teammate marker, so a sweep could close the lead. Only surfaces
+    okstra created are recorded, so only those can be closed.
     """
     seen: set[str] = set()
     panes: list[dict[str, str]] = []
@@ -214,13 +215,36 @@ def _reclaimable_panes(
         if isinstance(record, dict):
             _append_pane(panes, seen, str(record.get("paneId", "")), "worker")
     if _is_cmux_run(manifest):
-        return panes
+        return _still_open_surfaces(panes)
     lead_pane = tmux.resolve_caller_pane()
     for pane in tmux.list_run_panes(run_dir, lead_pane=lead_pane):
         _append_pane(panes, seen, pane.pane_id, pane.kind)
     return panes
 
 
+def _still_open_surfaces(panes: list[dict[str, str]]) -> list[dict[str, str]]:
+    """The recorded surfaces cmux still shows.
+
+    `workerDispatches` is append-only and nothing prunes it, so a surface closed
+    at an earlier round boundary stays recorded for the rest of the run. Taking
+    the ledger as the residual set makes the run-end cleanup gate offer to close
+    panes that left the screen rounds ago, on a workspace holding none.
+
+    An unreachable cmux keeps the ledger rather than reporting an empty set: a
+    wedged app is not evidence that the surfaces are gone, closing one that
+    already went away is a silent no-op, and skipping a live one strands it on
+    the user's screen for the rest of the session.
+    """
+    workspace = cmux.resolve_lead_workspace()
+    if not workspace:
+        return panes
+    try:
+        open_ids = cmux.open_surface_ids(workspace)
+    except (RuntimeError, OSError, subprocess.SubprocessError):
+        return panes
+    return [pane for pane in panes if pane["paneId"] in open_ids]
+
+
 def _append_pane(panes: list[dict[str, str]], seen: set[str], pane_id: str, kind: str) -> None:
     if pane_id and pane_id not in seen:
         panes.append({"paneId": pane_id, "kind": kind})

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,
 )
@@ -48,10 +49,11 @@ _NON_BODY_PREFIXES = (
     "Assigned worker prompt history path:",
     "**Worker Preamble Path:**",
     _EVIDENCE_LEDGER_HEADER_PREFIX,
+    "**Evidence citations:**",
     *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_headers.py

@@ -38,6 +38,23 @@ READ_SCOPE_HEADER = (
 )
 EVIDENCE_LEDGER_HEADER = "**Evidence ledger:** required-v1"
 
+# `required-v1` is a mode name; what it demands lives in the Worker Preamble's
+# "Evidence read ledger". But the preamble reaches the worker as a *path* —
+# eager-include inlines only the role sidecars — so a worker that never opens it
+# gets the switch without the rule, and Phase 7 then fails its result over a
+# citation form the prompt never stated. Restating it inline is what
+# READ_SCOPE_HEADER does, for the same reason: the rule has to be in front of the
+# worker before its first citation, not in a file it may never read.
+EVIDENCE_CITATION_HEADER = (
+    "**Evidence citations:** Append one `- Evidence read: <project-relative "
+    "path, no line suffix>` row to the audit sidecar for every file you open as "
+    "claim evidence, and cite that file in your result with backticks, a line "
+    "suffix, and the identical project-relative path — `src/config/env.ts:1-22`, "
+    "never the bare filename `env.ts:1-22`. A bare filename does not match its "
+    "ledger row and fails exactly like a file you never opened, however many "
+    "times you cited the full path earlier."
+)
+
 # `agy`'s write tool validates the target against the Gemini artifact store
 # whenever the model attaches ArtifactMetadata, and rejects every path outside
 # `~/.gemini/antigravity-cli/brain/<uuid>/`. All okstra worker outputs live under
@@ -103,7 +120,7 @@ def worker_prompt_headers(
             f"**Coding preflight pack:** {_coding_preflight_pack_path(active_context)}"
         )
     if dispatch_kind == "initial" and plan.audience != "report-writer":
-        headers.append(EVIDENCE_LEDGER_HEADER)
+        headers += [EVIDENCE_LEDGER_HEADER, EVIDENCE_CITATION_HEADER]
     headers.extend([
         f"**Errors log path:** {errors_log_path}",
         f"**Errors sidecar path:** {errors_sidecar_path}",

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/python/okstra_ctl/worktree.py

@@ -219,7 +219,7 @@ def resolve_stage_worktree_decision(
     safe_task = _safe_segment(task_id_segment)
     existing = worktree_registry.lookup(
         safe_project, safe_group, safe_task, stage_number=stage_number)
-    if existing is not None and existing.status == "active":
+    if existing is not None and _stage_entry_is_reusable(existing):
         return StageWorktreeDecision(
             status="reused",
             path=existing.worktree_path,
@@ -237,6 +237,22 @@ def resolve_stage_worktree_decision(
     )
 
 
+def _stage_entry_is_reusable(entry: worktree_registry.WorktreeEntry) -> bool:
+    """Whether a registered stage worktree can be entered by this run.
+
+    `active` is the live-run case. `released` with the directory still on disk is
+    the fix-run case: a stage whose verifier returned FAIL records a `failed`
+    consumers row, which frees the occupancy but deliberately keeps the worktree
+    and its branch as the reviewable stack. Re-entry MUST reuse that tree —
+    provisioning anew refuses on the existing path and branch. After whole-task
+    final-verification removes the directory the entry stops being reusable, so
+    the stage provisions from scratch.
+    """
+    if entry.status == "active":
+        return True
+    return entry.status == "released" and Path(entry.worktree_path).is_dir()
+
+
 def _safe_segment(value: str) -> str:
     """Sanitise a single path/branch segment.
 

package/runtime/schemas/final-report-v1.0.schema.json

@@ -5042,6 +5042,10 @@
             "type": "string",
             "minLength": 1
           }
+        },
+        "withheld": {
+          "type": "string",
+          "minLength": 1
         }
       }
     },

package/runtime/schemas/final-report-v2.0.schema.json

@@ -7114,6 +7114,10 @@
             "type": "string",
             "minLength": 1
           }
+        },
+        "withheld": {
+          "type": "string",
+          "minLength": 1
         }
       }
     },

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.
@@ -45,9 +51,10 @@ Every initial implementation prompt begins with these generated common anchors i
 6. `**Worker Error Contract Path:** <absolute-path>`
 7. `**Coding preflight pack:** <absolute-path>`
 8. `**Evidence ledger:** required-v1`
-9. `**Errors log path:** <absolute-path>`
-10. `**Errors sidecar path:** <absolute-path>`
-11. `**Read scope:** <allowlist>`
+9. `**Evidence citations:** <rule>` — the ledger-row and citation-path rule of §"Evidence read ledger", restated inline so it is in front of you before your first citation.
+10. `**Errors log path:** <absolute-path>`
+11. `**Errors sidecar path:** <absolute-path>`
+12. `**Read scope:** <allowlist>`
 
 The implementation body additionally carries `**Worktree:**` and its role-sidecar inputs. Do not synthesize any missing path.
 

package/runtime/templates/reports/final-report.template.md

@@ -674,6 +674,9 @@ Carried-forward plan items retain their prior verdicts verbatim; each such item
 ### 5.7.5 Stage Sidecar Evidence
 
 - Stage: `{{ implementation.stageSidecarEvidence.stageNumber }}` — {{ implementation.stageSidecarEvidence.stageTitle }}
+{% if implementation.stageSidecarEvidence.withheld -%}
+- Carry sidecar **withheld** — not written to `carry/stage-{{ implementation.stageSidecarEvidence.stageNumber }}.json`: {{ implementation.stageSidecarEvidence.withheld }}
+{% endif -%}
 - Carry sidecar JSON:
   ```json
   {{ implementation.stageSidecarEvidence.carryJson | indent(2) }}

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

@@ -43,9 +43,10 @@ Every initial analysis prompt begins with these generated anchors in this exact
 6. `**Worker Preamble Path:** <absolute-path>` — selects this analysis preamble.
 7. `**Worker Error Contract Path:** <absolute-path>` — shared by every initial audience.
 8. `**Evidence ledger:** required-v1`
-9. `**Errors log path:** <absolute-path>`
-10. `**Errors sidecar path:** <absolute-path>`
-11. `**Read scope:** <allowlist>`
+9. `**Evidence citations:** <rule>` — the ledger-row and citation-path rule of §"Evidence read ledger", restated inline so it is in front of you before your first citation.
+10. `**Errors log path:** <absolute-path>`
+11. `**Errors sidecar path:** <absolute-path>`
+12. `**Read scope:** <allowlist>`
 
 `final-verification` additionally carries its six verification-target anchors. `improvement-discovery` carries `**Phase 1.5 Grilling Log:**`. Reverify prompts are lightweight and do not use this preamble.
 

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/runtime/validators/validate-run.py

@@ -5061,6 +5061,13 @@ def _validate_stage_carry_sidecar_exists(
     stage = evidence.get("stageNumber")
     if not isinstance(stage, int):
         return
+    # A stage whose verifier returned FAIL must NOT persist its carry: the carry
+    # file is what marks the stage `done`, and doing that would stack the next
+    # stage on a confirmed regression. Such a run states the reason in
+    # `withheld` and records a `failed` consumers row instead, so the absent
+    # file is the correct outcome, not a gap.
+    if str(evidence.get("withheld") or "").strip():
+        return
     # Carry sidecars are stage-SHARED: the next stage's carry-in and
     # `consumers.backfill_done_from_carry` glob them without knowing the
     # producing run's layout. `RunRef.carry()` owns that flat-vs-staged rule;