okstra 0.150.0 → 0.151.1

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

@@ -20,7 +20,7 @@
       - **External Tier 3 de-duplication exception.** A DB/IO/SQL surface covered by an in-scope Tier 3 entry whose `requires` include `db`, `http`, or `external` is governed by the External QA outcome policy. Its non-PASS or unavailable result MUST NOT generate a second legacy db-test-not-configured or mock-only blocker solely for that same Tier 3 non-PASS or unavailable result. Tier 1 or Tier 2 failures remain blocking, and DB surfaces without declared external Tier 3 coverage remain blocking.
     - no new defects introduced — the diff does not break previously-working behaviour and adds no new bug (logic/off-by-one, null/empty handling, resource leaks, broken error paths)
     - scope conformance — the delivered diff stays within the approved plan's scope; flag out-of-scope edits, unrelated file changes, leftover debug/commented-out code, and unintended deletions
-    - project review-rule packs (when present) — search `<PROJECT_ROOT>/skills/*review*`, `<PROJECT_ROOT>/.claude/skills/*review*`, and up to two parent directories' `skills/*review*/SKILL.md`; read the matching `SKILL.md` + referenced `references/*.md` and apply their rules as an acceptance overlay (record `project-review-rules: <paths read>` or `project-review-rules: none found`). This is a static review pass, not a PR-comment workflow — do NOT dispatch reviewer subagents. Because this phase verifies the **whole-task merged diff**, it is the gate that catches **cross-stage findings a per-stage `implementation` verifier structurally cannot see** (each implementation run reviews only its own stage diff): most importantly two cross-stage conditions: (a) the same helper stack / transform / domain rule duplicated across stages or services — byte-identical duplication is always an Acceptance Blocker, and semantically-equivalent transforms across services are blockers unless the approved plan explicitly justified keeping them separate; (b) an API newly orphaned because its only caller was removed in a different stage. A confirmed cross-stage duplication of this kind is an Acceptance Blocker (`major`+) that cites every `path:line` location and names the shared-module location to converge on. (Single-stage scope sees only one stage, so it cannot raise cross-stage findings — note that limitation rather than implying coverage.)
+    - project review-rule packs (when brief-cited) — apply a project review rule pack only when the task brief's `Source Material` or `Reporter Confirmations` cites its exact `SKILL.md` path; read only that cited file and the `references/*.md` files it directly names. Do not search parent directories or host skill catalogs. Apply the cited rules as an acceptance overlay (record `project-review-rules: <paths read>` or `project-review-rules: none cited`). This is a static review pass, not a PR-comment workflow — do NOT dispatch reviewer subagents. Because this phase verifies the **whole-task merged diff**, it is the gate that catches **cross-stage findings a per-stage `implementation` verifier structurally cannot see** (each implementation run reviews only its own stage diff): most importantly two cross-stage conditions: (a) the same helper stack / transform / domain rule duplicated across stages or services — byte-identical duplication is always an Acceptance Blocker, and semantically-equivalent transforms across services are blockers unless the approved plan explicitly justified keeping them separate; (b) an API newly orphaned because its only caller was removed in a different stage. A confirmed cross-stage duplication of this kind is an Acceptance Blocker (`major`+) that cites every `path:line` location and names the shared-module location to converge on. (Single-stage scope sees only one stage, so it cannot raise cross-stage findings — note that limitation rather than implying coverage.)
   - Residual-tracked — note as Residual Risk unless severe enough to block:
     - unresolved edge cases
     - regression risk in adjacent code paths not directly changed

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

@@ -42,7 +42,7 @@
   - **Follow established patterns**: in existing codebases, conform to current conventions. Targeted cleanup of a file you are already modifying is acceptable; unrelated refactors are not.
   - **Variation-point extraction (OCP)**: when the same behavior is served by two or more resources / implementations — stated in the brief, or foreseeable from a sibling task or the code you inspected — the plan MUST record it in `variationPointAnalysis` and include an option that extracts the variation point behind an interface (a port, or a strategy the next implementation plugs into), scored against the non-extracted option in the trade-off matrix. Penalize an option that branches on resource identity inside a service (one `if` / `switch` arm per implementation): adding the next implementation then means editing that same call site again, which is the closed-for-extension shape this principle exists to catch. This does not contradict YAGNI below: YAGNI drops *speculative* variation (a second implementation nobody named), while a behavior with two implementations already on the table is a present fact, not a forecast. **Enforced:** the `variationPointAnalysis` bullet under `Required deliverable shape` names the schema / validator / `P-Var-*` enforcement points.
   - **YAGNI ruthlessly**: drop features, abstractions, and configuration knobs that do not serve the stated requirement.
-  - **Project review-rule preflight**: before choosing the recommended option, look for project-local review rule packs such as `<PROJECT_ROOT>/skills/*review*`, `<PROJECT_ROOT>/.claude/skills/*review*`, and up to two parent directories' `skills/*review*/SKILL.md`. If present, read the relevant `SKILL.md` plus referenced `references/*.md` files and treat their rules as planning constraints. Do not run the PR-review workflow here; extract only the rules. For Fonts Ninja-style TS/NestJS review packs, this means planning away known review findings before code exists: shared transforms instead of duplicate helper stacks, behavioral tests instead of collaborator-tautology assertions, domain rules in domain modules rather than repositories/adapters, domain objects under `domain/`, plain-English functions, truthful/specific names, and no dead APIs introduced by the plan.
+  - **Project review-rule preflight**: apply a project review rule pack only when the task brief's `Source Material` or `Reporter Confirmations` cites its exact `SKILL.md` path. Read only that cited file and the `references/*.md` files it directly names. Do not search parent directories or host skill catalogs. Do not run the PR-review workflow here; extract only the rules. For Fonts Ninja-style TS/NestJS review packs, this means planning away known review findings before code exists: shared transforms instead of duplicate helper stacks, behavioral tests instead of collaborator-tautology assertions, domain rules in domain modules rather than repositories/adapters, domain objects under `domain/`, plain-English functions, truthful/specific names, and no dead APIs introduced by the plan.
 - Expected output emphasis:
   - feasible plan options
   - dependency and risk visibility
@@ -80,11 +80,12 @@
     - admissible — the answer selects between behaviours the code must implement, fixes a requirement the plan would otherwise satisfy incorrectly, or resolves a safety/data-integrity question.
     - NOT admissible → use `Blocks=none` — QA-harness or tooling scope, report notation and wording, numbering or citation-range cleanup, anything inside an option the plan does not recommend, and anything the codebase answers (which the codebase-first rule already forbids raising at all). These belong in `## 5. Missing Information and Risks` or a Working Assumption; they are recorded, not gating.
     - A row you would answer with "the plan would still produce the same code either way" is by construction `Blocks=none`.
-- Section heading contract (BLOCKING — validator scans for these literal English substrings):
-  - The final report MUST include section headings containing each of the following exact strings — this list mirrors `PLANNING_REQUIRED_SECTIONS` in `validators/validate-run.py`, which is the SSOT: `Option Candidates`, `Trade-off`, `Recommended Option`, `Stage Map`, `Stepwise Execution Order`, `Dependency`, `Validation Checklist`, `Rollback`, `Requirement Coverage`, `Plan Body Verification`, `Cross-Project Dependencies`, `Decision Drafts`. (Approval is no longer a body section — it is the YAML frontmatter `approved` field.) Three further headings are enforced elsewhere, not by that scan: `Stage Exit Contract` and `Stage Validation` are per-stage subsections checked by `validators/validate-implementation-plan-stages.py`, and `Implementation Design Preparation` is enforced and rendered by `schemas/final-report-v1.0.schema.json` plus `templates/reports/final-report.template.md` from its required data block.
-  - Korean translations are allowed in parentheses (e.g. `### Recommended Option (Korean gloss)`), but the English keyword must be present verbatim in the heading line.
-  - The shape and ordering follow `final-report-template.md` sections 5.4 (`Implementation Plan Deliverables`) + 5.5 (`Stage Map`). `validators/validate-run.py` substring-matches the raw report text, so a Korean-only heading fails the gate — the cause of repeated observed failures.
-  - Beyond substring matching, when the Plan Body Verification gate result is `passed` / `passed-with-dissent`, `validators/validate-run.py` runs the **structural** Stage Map validator (`validators/validate-implementation-plan-stages.py`) at the planning boundary — not deferred to the `implementation` entry gate. It enforces: the exact `## 5.5 Stage Map` heading, each `## 5.5.<i> Stage <i>:` section with its four required subsections, the per-stage effective step count (≤8), the `depends-on` DAG, and the per-stage vertical-slice contract (S10). S10 scans for the literal in-section strings `Slice value:`, `Acceptance:`, the three `Test case (success):` / `Test case (boundary):` / `Test case (failure):` lines (S10d), and the Stepwise `action`-cell prefixes `RED:` / `GREEN:` (or a `TDD exemption:` line, which waives both the test-case lines and the RED/GREEN check) — keep these tokens verbatim for the same reason as the heading keywords above.
+- Deliverable completeness contract (BLOCKING — the schema checks data keys, not heading strings):
+  - The plan lives in `data.json` under `implementationPlanning`, and `schemas/final-report-v2.0.schema.json` requires every one of these keys: `optionCandidates`, `tradeoffMatrix`, `recommendedOption`, `stageMap`, `stages`, `dependencyMigrationRisk`, `validationChecklist`, `rollbackStrategy`, `requirementCoverage`, `planBodyVerification`, `crossProjectDependencies`, `decisionDrafts`, `skippedAdrCandidates`, `variationPointAnalysis`, `userNarrative`. A missing block fails schema validation; there is nothing to satisfy by naming a heading. (Approval is not a body section — it is the YAML frontmatter `approved` field.)
+  - Each `stages[]` entry requires `stage`, `title`, `sliceValue`, `acceptance`, `carryIn`, `stepwiseExecution` (1–6 rows), `exitContract`, and `stageValidation`. Each `stageMap[]` row requires `stage`, `title`, `dependsOn`, `stepCount`, `exitContractSummary`.
+  - Beyond the schema, `validators/validate-run.py` reads the same data.json for `_validate_planning_conformance_declared`, `_validate_end_state_coverage`, `_validate_requirement_provenance`, `_validate_stage_has_requirement`, and `_validate_plan_body_state_file`. These run for every planning report regardless of schema version.
+  - **Do not chase English heading substrings.** `PLANNING_REQUIRED_SECTIONS` and the structural Stage Map scan (`validators/validate-implementation-plan-stages.py`) live inside `validate_phase_boundary`, which returns immediately when `schemaVersion == "2.0"` — they gate historical v1 Markdown only. The v2 AI-handoff template renders nine headings and serialises the plan as JSON beneath them, so those substrings cannot appear, and a report is not defective for lacking them.
+  - *Guideline, not gated:* write each `stepwiseExecution` row's `action` with a `RED:` / `GREEN:` prefix (or state a TDD exemption in `stageValidation`), and name the success / boundary / failure cases in `acceptance`. The v1 scan checked those tokens literally; v2 requires only that the fields be non-empty, so this is now review-enforced rather than validator-enforced.
 - Required deliverable shape (final report, in addition to the standard sections):
   - at least two implementation options. **Each option must include**:
     - **File Structure**: an explicit list of files to create / modify / delete with each file's responsibility (one-line each). Use the form `Create: path — responsibility` / `Modify: path:line-range — change summary` / `Delete: path — reason`. Write every `path` in full and `<PROJECT_ROOT>`-relative — never ellipsis-abbreviated (`…` / `...` / a trailing `/…`); an abbreviated path does not resolve and is rejected by plan-body verification as a kind-b path mismatch.
@@ -188,7 +189,7 @@
   3. **Internal consistency** — option file lists, trade-off matrix, and recommended step list must agree on file paths, names, and signatures. A symbol called `clearLayers()` in the matrix and `clearFullLayers()` in the steps is a bug.
   4. **Ambiguity check** — any requirement that could be read two ways must be made explicit or moved to the `## 1. Clarification Items` table as a `Blocks=approval` row.
   5. **Scope check** — if the recommended plan now spans multiple independent subsystems, recommend splitting into separate planning runs rather than shipping an oversized plan. Then walk the plan in the expansion direction: for every stage, name the Requirement Coverage row that demanded it, and for every requirement row, read its `Source` cell as a skeptic — does the cited brief heading actually exist, and does a `derived:` rationale state a real technical consequence rather than a preference? Move anything that fails to a `Blocks=approval` clarification row.
-  6. **Review-rule preflight check** — if a project review rule pack exists, map each relevant rule to the recommended option. Reject the draft if it knowingly creates a violation that the later PR reviewer would flag, unless the plan records a specific rationale and follow-up. In particular, scan for repeated helper stacks across planned files, tests that assert delegation to the same calculator/helper they exercise, public names that hide side effects, domain rules placed in repositories/adapters, and APIs made dead by this change.
+  6. **Review-rule preflight check** — if the task brief cites a project review rule pack under `Source Material` or `Reporter Confirmations`, map each relevant rule to the recommended option. Reject the draft if it knowingly creates a violation that the later PR reviewer would flag, unless the plan records a specific rationale and follow-up. In particular, scan for repeated helper stacks across planned files, tests that assert delegation to the same calculator/helper they exercise, public names that hide side effects, domain rules placed in repositories/adapters, and APIs made dead by this change.
   7. **Plan-body verification reconciliation (BLOCKING for implementation-planning).** For every §5.5.9 `planItems[]` entry whose verdicts make it `majority-disagree`, set that item's `clarificationId` to a `C-<N>` row that MUST exist in `## 1. Clarification Items` with `Kind` chosen per the standard policy and `Blocks=approval`. **Enforced:** `validators/validate-run.py` `_validate_plan_body_clarification_matching` recomputes each item's class and fails when a majority-disagree item has no `clarificationId`, or its `clarificationId` is dangling / points at a non-`approval` row. For `partial-consensus` and `dissent-isolated` plan-items, the dissenting opinion lives in §5.5.9 `Dissent log` and is NOT promoted to §5.
   8. **Stage Map self-check** — for every stage, count the effective rows of its `Stepwise Execution Order` table by hand; reject the draft if any stage exceeds 8. Confirm each stage declares a non-empty `Slice value:` and `Acceptance:` line, the three `Test case (success|boundary|failure):` lines (or carries a `TDD exemption:` line), and that its first step `action` starts with `RED:` with a later `GREEN:` — this is what validator S10 enforces, including S10d on the test-case lines. Read each stage's three test-case lines as a reviewer: reject any that restates the happy path in all three slots, leaves `boundary` blank, or writes `N/A` where a real edge input exists. Walk the `depends-on` graph and confirm it is a DAG (no cycle, no self-reference). For each `depends-on` link, confirm it encodes a real data/contract dependency — do NOT add links to serialise unrelated work, and do NOT split a stage merely to create more parallel stages. **Parallel-safety:** for every pair of `depends-on (none)` stages, confirm their `Stage Exit Contract` predicted file sets are disjoint; if they share a file, merge them or add a `depends-on` link (validator S9 rejects overlap). **Project-boundary:** confirm no stage mixes edits from two projects (different repo/`PROJECT_ROOT` or different top-level deployable module); if any stage does, split it per project. For multi-project plans, confirm each stage's `title` carries its `[<project>]` tag and the `Cross-project parallelism:` line under the table records the parallel-vs-sequenced determination (with the forcing dependency) for every project pair; for cross-repo work, confirm it is split into separate per-repo runs (required — one run structurally cannot touch another repo) rather than crammed into one task's stages.
   9. **Cross-project dependency check** — confirm you have not missed a dependency on another repo / another top-level deployable module / a published package. If `dependencyMigrationRisk` has a `kind: cross-project` row, confirm a matching `direction: upstream-precondition` `XP-NNN` row exists in `crossProjectDependencies`, and re-read as a reviewer whether its `requiredWork` is the concrete work the other side must actually build rather than an abstract phrase ("other side's work done") — validator S only checks existence, so concreteness is the self-review's responsibility. Confirm cross-repo work is split into a separate run + XP row instead of being crammed into one task's stages, and that the cross-project substance is not duplicated in `§3 Recommended Next Steps` but lives only in `§5.4 Cross-Project Dependencies`.

package/runtime/python/okstra_ctl/analysis_packet.py

@@ -53,6 +53,7 @@ WORKER_PROFILE_SECTIONS_BY_TASK_TYPE = {
     ),
     "implementation-planning": (
         "Worker planning procedure",
+        "Pre-planning context exploration",
         "Design principles applied when scoring options",
     ),
     "final-verification": (

package/runtime/python/okstra_ctl/convergence.py

@@ -123,7 +123,21 @@ def _parser() -> argparse.ArgumentParser:
     subparsers = parser.add_subparsers(dest="operation", required=True)
 
     example = subparsers.add_parser(
-        "example", help="print a deterministic input artifact example"
+        "example",
+        help="print a deterministic input artifact example",
+        description=(
+            "Print one deterministic valid example as JSON.\n\n"
+            "`groups` feeds `seed --groups` and `round-results` feeds "
+            "`apply-round --results`, but `critic-results` is the critic "
+            "worker's own result document — NOT the `apply-critic-gaps "
+            "--results` input. That input is the coverage batch the lead "
+            "assembles from those candidates plus each analyser's vote "
+            '({schemaVersion, taskKey, mode: "coverage", provider, '
+            "modelExecutionValue, dispatches[], gaps[]}); see "
+            'prompts/lead/convergence.md §"Coverage critic". Feeding this '
+            "example straight into `apply-critic-gaps` is rejected, by design."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
     )
     example.add_argument(
         "--kind",

package/runtime/python/okstra_ctl/dispatch_state.py

@@ -275,7 +275,11 @@ def validate_initial_prompts(
         PromptRecord(job.worker_id, job.dispatch_kind, job.prompt_path)
         for job in jobs
     ]
-    errors = validate_initial_prompt_records(manifest=manifest, records=records)
+    errors = validate_initial_prompt_records(
+        manifest=manifest,
+        records=records,
+        require_evidence_ledger=True,
+    )
     if errors:
         task_type = require_string(manifest, "taskType")
         raise DispatchError(f"{task_type} prompt contract: " + "; ".join(errors))

package/runtime/python/okstra_ctl/initial_prompt_materialization.py

@@ -521,6 +521,7 @@ def _validate_prepublication_set(
         errors = validate_initial_prompt_records(
             manifest=context.manifest,
             records=[record],
+            require_evidence_ledger=True,
         )
         if errors:
             raise InitialPromptMaterializationError(
@@ -530,6 +531,7 @@ def _validate_prepublication_set(
     errors = validate_initial_prompt_records(
         manifest=context.manifest,
         records=records,
+        require_evidence_ledger=True,
     )
     if errors:
         raise InitialPromptMaterializationError(
@@ -577,6 +579,7 @@ def _validate_existing_prompt(
     basic_errors = validate_initial_prompt_records(
         manifest=context.manifest,
         records=[basic_record],
+        require_evidence_ledger=True,
     )
     if basic_errors:
         raise InitialPromptMaterializationError(
@@ -593,6 +596,7 @@ def _validate_existing_prompt(
     expected_errors = validate_initial_prompt_records(
         manifest=context.manifest,
         records=[expected_record],
+        require_evidence_ledger=True,
     )
     if expected_errors:
         reason = _existing_metadata_reason(expected_errors)
@@ -765,6 +769,7 @@ def _validate_published_set(
         errors = validate_initial_prompt_records(
             manifest=context.manifest,
             records=[record],
+            require_evidence_ledger=True,
         )
         if errors:
             raise InitialPromptMaterializationError(
@@ -774,6 +779,7 @@ def _validate_published_set(
     errors = validate_initial_prompt_records(
         manifest=context.manifest,
         records=records,
+        require_evidence_ledger=True,
     )
     if errors:
         raise InitialPromptMaterializationError(
@@ -983,6 +989,7 @@ def _validate_existing_record_subset(
     errors = validate_initial_prompt_records(
         manifest=manifest,
         records=records,
+        require_evidence_ledger=True,
     )
     if errors:
         raise InitialPromptMaterializationError(

package/runtime/python/okstra_ctl/report_finalize.py

@@ -1,10 +1,15 @@
 """Phase 7 report post-processing — the single reference point.
 
 Phase 7 turns a Phase 6 final-report data.json into shippable artifacts through
-four ordered steps: usage substitution, html view rendering, follow-up task
-spawning, and run validation. The order is load-bearing — rendering before
-substitution ships `--` token cells, and validating before rendering trips the
-report-views contract.
+five ordered steps: English-SSOT verification, usage substitution, html view
+rendering, follow-up task spawning, and run validation. The order is
+load-bearing — rendering before substitution ships `--` token cells, and
+validating before rendering trips the report-views contract.
+
+The translation sidecar is NOT one of these steps. `render-views` overlays it,
+so a non-English run dispatches the translator before this sequence starts —
+after verifying the data.json is English, which is why `check-source` is also
+available as a standalone command.
 
 Every lead adapter drives Phase 7 through this module: the Codex adapter calls
 it in-process (``codex_dispatch``), and a Claude-led run reaches the same code
@@ -24,12 +29,17 @@ from .final_report_paths import final_report_data_path, final_report_markdown_pa
 from .paths import task_dir, task_manifest_file
 
 
+STEP_CHECK_SOURCE = "check-source"
 STEP_TOKEN_USAGE = "token-usage"
 STEP_RENDER_VIEWS = "render-views"
 STEP_SPAWN_FOLLOWUPS = "spawn-followups"
 STEP_VALIDATE_RUN = "validate-run"
 
 STEP_ORDER = (
+    # First, because everything after it derives from the data.json: rendering
+    # a Korean SSOT into English chrome, spawning follow-ups from it, and
+    # validating it all succeed on a record the next phase cannot read.
+    STEP_CHECK_SOURCE,
     STEP_TOKEN_USAGE,
     STEP_RENDER_VIEWS,
     STEP_SPAWN_FOLLOWUPS,
@@ -205,6 +215,19 @@ def build_commands(ctx: FinalizeContext) -> list[tuple[str, list[str]]]:
     """Assemble the ordered Phase 7 argv list. Order is contractual."""
     markdown_path = ctx.markdown_path
     return [
+        (
+            STEP_CHECK_SOURCE,
+            [
+                sys.executable,
+                str(
+                    resolve_workspace_script(
+                        ctx.workspace_root, "okstra-report-translate.py"
+                    )
+                ),
+                "check-source",
+                str(ctx.data_path),
+            ],
+        ),
         (
             STEP_TOKEN_USAGE,
             [

package/runtime/python/okstra_ctl/report_translation.py

@@ -393,6 +393,35 @@ def overlay(
     return out, OverlayReport(applied, untranslated, tuple(sorted(unresolved)))
 
 
+# Above this share of Hangul, the prose was authored in Korean rather than
+# quoting some. Measured across real reports: Korean-authored ones sit at
+# 35-38%, English ones that quote a Korean brief or a worker's Korean phrase
+# reach 8% at most. The gap is wide enough that no threshold inside it is
+# delicate. Only the strings `extract` offers are counted — a verbatim quote of
+# the user's request is structural and never reaches this.
+HANGUL_PROSE_LIMIT = 0.20
+
+
+def hangul_share(data: Mapping[str, Any]) -> tuple[float, int]:
+    """Return the Hangul share of the report's authored prose, and its length."""
+    text = "".join(extract(data).values())
+    if not text:
+        return 0.0, 0
+    hangul = sum(1 for char in text if "가" <= char <= "힣")
+    return hangul / len(text), len(text)
+
+
+def prose_is_english(data: Mapping[str, Any]) -> bool:
+    """Whether the data.json was authored in English, as the SSOT contract requires.
+
+    The report language names what the human HTML renders in, not what the
+    worker writes. A worker that authors Korean anyway hands every later phase,
+    validator and agent a record in a language they do not read.
+    """
+    share, _ = hangul_share(data)
+    return share < HANGUL_PROSE_LIMIT
+
+
 def _schema_string_keys(schema: Mapping[str, Any], *, enums: bool) -> set[str]:
     found: set[str] = set()
 

package/runtime/python/okstra_ctl/worker_prompt_body.py

@@ -128,6 +128,7 @@ def report_writer_input_lines(
     team_state: Mapping[str, Any],
 ) -> list[str]:
     inputs = [
+        ("Analysis packet", instruction_path(manifest, active_context, "analysisPacketPath")),
         ("Task brief", instruction_path(manifest, active_context, "taskBriefPath")),
         ("Analysis profile", instruction_path(manifest, active_context, "analysisProfilePath")),
         ("Analysis material", instruction_path(manifest, active_context, "analysisMaterialPath")),
@@ -193,8 +194,9 @@ def run_path(
 
 def mcp_pointer_line() -> str:
     return (
-        '**MCP servers:** follow the task brief\'s "## Available MCP Servers" '
-        "section (already in your Required reading)."
+        '**MCP servers:** follow the analysis packet\'s "Available MCP Servers" '
+        "section. If the section is absent or says none, treat MCP as unavailable "
+        "for this run; never infer tools from host configuration."
     )
 
 

package/runtime/python/okstra_ctl/worker_prompt_contract.py

@@ -11,6 +11,7 @@ from .worker_prompt_policy import (
     PromptPlan,
     resolve_prompt_plan_for_manifest,
 )
+from .worker_prompt_headers import EVIDENCE_LEDGER_HEADER
 
 
 MAX_FINAL_VERIFICATION_DIRECTIVE_LINES = 40
@@ -24,6 +25,7 @@ FORBIDDEN_ACTIONS_HEADER = "**Forbidden actions:**"
 
 _DIRECTIVE_HEADING = "## Run-specific directive"
 _WORKER_ERROR_CONTRACT_HEADER = "**Worker Error Contract Path:**"
+_EVIDENCE_LEDGER_HEADER_PREFIX = "**Evidence ledger:**"
 _PRIMARY_PACKET_RE = re.compile(
     r"(?im)^-\s+Primary analysis packet:\s+`[^`\n]*analysis-packet\.md`\s*$"
 )
@@ -45,6 +47,7 @@ _NON_BODY_PREFIXES = (
     "**Audit sidecar path:**",
     "Assigned worker prompt history path:",
     "**Worker Preamble Path:**",
+    _EVIDENCE_LEDGER_HEADER_PREFIX,
     *ERRORS_PATH_HEADERS,
     "**Read scope:**",
     "**File write mode:**",
@@ -239,8 +242,13 @@ def validate_initial_prompt_records(
     *,
     manifest: Mapping[str, Any],
     records: Sequence[PromptRecord],
+    require_evidence_ledger: bool = False,
 ) -> list[str]:
-    """Validate prompt audiences and compare their normalized equality groups."""
+    """Validate prompt audiences and compare their normalized equality groups.
+
+    Newly published prompts opt into the evidence-ledger requirement. Persisted
+    historical prompts still validate under the contract they were written with.
+    """
     errors: list[str] = []
     equality_groups: dict[str, dict[str, str]] = {}
     for record in records:
@@ -262,6 +270,15 @@ def validate_initial_prompt_records(
             f"{record.worker_id}: {error}"
             for error in _validate_record_metadata(text, record)
         )
+        errors.extend(
+            f"{record.worker_id}: {error}"
+            for error in _validate_evidence_ledger_header(
+                text,
+                plan,
+                record.dispatch_kind,
+                required=require_evidence_ledger,
+            )
+        )
         if plan.equality_group:
             group = equality_groups.setdefault(plan.equality_group, {})
             group[record.worker_id] = text
@@ -289,6 +306,29 @@ def _validate_record_metadata(text: str, record: PromptRecord) -> list[str]:
     return errors
 
 
+def _validate_evidence_ledger_header(
+    text: str,
+    plan: PromptPlan,
+    dispatch_kind: str,
+    *,
+    required: bool,
+) -> list[str]:
+    values = _header_values(text, _EVIDENCE_LEDGER_HEADER_PREFIX)
+    if dispatch_kind != "initial":
+        return []
+    if plan.audience == "report-writer":
+        if values:
+            return ["Evidence ledger header is forbidden for report-writer"]
+        return []
+    if not values:
+        if required:
+            return [f"exactly one `{EVIDENCE_LEDGER_HEADER}` header is required"]
+        return []
+    if values != ["required-v1"]:
+        return [f"exactly one `{EVIDENCE_LEDGER_HEADER}` header is required"]
+    return []
+
+
 def _validate_delivery_mode(
     values: list[str],
     expected: str | None,

package/runtime/python/okstra_ctl/worker_prompt_headers.py

@@ -36,6 +36,7 @@ READ_SCOPE_HEADER = (
     "un-enumerated file seems essential, record it under *Missing Information "
     "or Assumptions* instead of reading it."
 )
+EVIDENCE_LEDGER_HEADER = "**Evidence ledger:** required-v1"
 
 # `agy`'s write tool validates the target against the Gemini artifact store
 # whenever the model attaches ArtifactMetadata, and rejects every path outside
@@ -101,6 +102,8 @@ def worker_prompt_headers(
         headers.append(
             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.extend([
         f"**Errors log path:** {errors_log_path}",
         f"**Errors sidecar path:** {errors_sidecar_path}",

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

@@ -25,6 +25,14 @@ Work like a senior engineer who owns this result, not a commentator on it.
 - Only the executor may mutate source files. Verifiers remain read-only except for okstra result/audit artifacts and project-declared QA commands.
 - Execute the role sidecar's pre-write, post-write, QA, and return gates without substituting analysis Sections 1–6 or report-authoring instructions.
 
+## Evidence read ledger
+
+When `**Evidence ledger:** required-v1` is present, append one canonical row to the audit sidecar immediately after opening every file used as claim evidence:
+
+- Evidence read: `<project-relative path without a line suffix>`
+
+Every file citation in the result MUST use backticks and a line suffix, for example `src/config/env.ts:1-22`. A cited path without a matching ledger row fails Phase 7 in `validators/validate-run.py` `validate_worker_results_audit()`. Do not add a row for a file you did not open.
+
 ## Anchor headers
 
 Every initial implementation prompt begins with these generated common anchors in this exact order, before its implementation-specific body:
@@ -36,9 +44,10 @@ Every initial implementation prompt begins with these generated common anchors i
 5. `**Worker Preamble Path:** <absolute-path>`
 6. `**Worker Error Contract Path:** <absolute-path>`
 7. `**Coding preflight pack:** <absolute-path>`
-8. `**Errors log path:** <absolute-path>`
-9. `**Errors sidecar path:** <absolute-path>`
-10. `**Read scope:** <allowlist>`
+8. `**Evidence ledger:** required-v1`
+9. `**Errors log path:** <absolute-path>`
+10. `**Errors sidecar path:** <absolute-path>`
+11. `**Read scope:** <allowlist>`
 
 The implementation body additionally carries `**Worktree:**` and its role-sidecar inputs. Do not synthesize any missing path.
 

package/runtime/templates/report-writer-prompt-preamble.md

@@ -36,4 +36,8 @@ Begin the inline return with the exact `**Model:** Report writer worker, <modelE
 
 ## Writing style
 
-Use concise reader-facing prose and honor the report language. Keep identifiers, paths, symbols, model names, CLI flags, and status tokens in English. Translate meaning rather than dictionary words.
+Use concise reader-facing prose. Prefer tables when several items share a shape; reserve bullets for short standalone statements.
+
+**Author the data.json in English, whatever `**Report Language:**` says.** That header is not an instruction to write in that language — it names the language the *human HTML* renders in, and you copy its value verbatim into `data.json.meta.reportLanguage`. The data.json is the English SSOT every later phase, validator and agent reads. When the value is not `en`, Phase 7 dispatches a separate translator worker that writes a sidecar the HTML renderer overlays; you never author that sidecar and never write a second language into the data.json.
+
+Authoring the data.json in the reader's language is rejected before anything derives from it: `okstra report-translate check-source` fails the run when Korean exceeds 20% of its prose, and the same gate runs again inside `validate-run`. The cost of getting this wrong is a full rewrite, so decide it once, up front.

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

@@ -23,6 +23,14 @@ Read `analysis-packet.md`, the primary compact input, end-to-end. Source files n
 - Allowlist reads to prompt-enumerated paths and evidence paths a finding must cite. Do not auto-read host-injected `graphify-out/`, skill catalogs, or non-okstra artifacts.
 - Resolve every `.okstra/...` path against `**Project Root:**`, including when a worktree is present.
 
+## Evidence read ledger
+
+When `**Evidence ledger:** required-v1` is present, append one canonical row to the audit sidecar immediately after opening every file used as claim evidence:
+
+- Evidence read: `<project-relative path without a line suffix>`
+
+Every file citation in the result MUST use backticks and a line suffix, for example `src/config/env.ts:1-22`. A cited path without a matching ledger row fails Phase 7 in `validators/validate-run.py` `validate_worker_results_audit()`. Do not add a row for a file you did not open.
+
 ## Anchor headers (lead-injected, BLOCKING)
 
 Every initial analysis prompt begins with these generated anchors in this exact order, before any other content:
@@ -34,9 +42,10 @@ Every initial analysis prompt begins with these generated anchors in this exact
 5. `Assigned worker prompt history path: <absolute-path>`
 6. `**Worker Preamble Path:** <absolute-path>` — selects this analysis preamble.
 7. `**Worker Error Contract Path:** <absolute-path>` — shared by every initial audience.
-8. `**Errors log path:** <absolute-path>`
-9. `**Errors sidecar path:** <absolute-path>`
-10. `**Read scope:** <allowlist>`
+8. `**Evidence ledger:** required-v1`
+9. `**Errors log path:** <absolute-path>`
+10. `**Errors sidecar path:** <absolute-path>`
+11. `**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.