okstra 0.151.0 → 0.152.0

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,16 @@
     - 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 Markdown scan in `collect_validation_errors` live inside `validate_phase_boundary`, which returns immediately when `schemaVersion == "2.0"` — they gate historical v1 Markdown only. The v2 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.
+- Per-stage vertical slice and TDD contract (BLOCKING — enforced on the data, not on heading tokens):
+  - Every stage declares `sliceValue`, `acceptance`, and the three cases `testCaseSuccess` / `testCaseBoundary` / `testCaseFailure` — happy path, edge/boundary input, failure input. **Enforced:** the v2 schema's `if not tddExemption then require` conditional on `ImplementationPlanStage`.
+  - The first `stepwiseExecution` row's `action` starts with `RED:` and its `expected` reads FAIL; some later row's `action` starts with `GREEN:` and its `expected` reads PASS. **Enforced (S10c):** `collect_data_validation_errors` in `validators/validate-implementation-plan-stages.py`, run from `validate-run.py` `_append_stage_data_failures`.
+  - `tddExemption` waives both rules above, and only for `doc-only`, `config-only`, or `pure-rename` work. An empty or arbitrary reason waives nothing. **Enforced (S10e):** same function — the schema alone cannot reject it, because it types the field as a plain string and keys its conditional on the property merely being present.
+  - `stageMap[].dependsOn` must form a DAG (no self-dependency, no unknown stage, no cycle), each row's `stepCount` must equal its stage's actual `stepwiseExecution` row count, and two `(none)`-dependency stages must not name the same file in their `exitContract` — they run as concurrent implementation runs in separate worktrees. **Enforced (S8/S4/S9):** same function.
 - 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 +193,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/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

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.
 

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

@@ -59,6 +59,30 @@ def _check_stage_map_present(text: str) -> List[ValidationError]:
     return []
 
 
+def _parse_depends_on_cell(raw: str) -> List[int] | None:
+    """Stage numbers in a `depends-on` cell; None when the cell is unparseable.
+
+    Schema v2 keeps the same literal cell text in `stageMap[].dependsOn`, so
+    both the Markdown scan and the data scan read it through here.
+    """
+    value = raw.strip()
+    if value in ("(none)", ""):
+        return []
+    try:
+        return [int(x.strip()) for x in value.split(",") if x.strip()]
+    except ValueError:
+        return None
+
+
+def _stage_numbers_monotonic(stages: List[StageMeta]) -> List[ValidationError]:
+    return [
+        ValidationError("S2", r.stage_number,
+            f"stage numbers must be 1..N monotonic, got {r.stage_number} at row {i}")
+        for i, r in enumerate(stages, start=1)
+        if r.stage_number != i
+    ]
+
+
 def _parse_stage_map(text: str) -> Tuple[List[StageMeta], List[ValidationError]]:
     m = STAGE_MAP_HEADING.search(text)
     if not m:
@@ -80,29 +104,19 @@ def _parse_stage_map(text: str) -> Tuple[List[StageMeta], List[ValidationError]]
             n = int(cells[0])
         except ValueError:
             continue
-        depends_raw = cells[2].strip()
-        if depends_raw in ("(none)", ""):
-            depends = []
-        else:
-            try:
-                depends = [int(x.strip()) for x in depends_raw.split(",") if x.strip()]
-            except ValueError:
-                # 비정수 depends_on 셀 → 행 skip (비정수 stage_number 와 동일). raw
-                # ValueError 를 흘리면 _stage_map_reject_detail·handoff 의 except
-                # PrepareError 를 우회해 traceback 으로 죽으므로, 누락된 행을 하류
-                # S2(비단조) 검사가 잡게 한다.
-                continue
+        depends = _parse_depends_on_cell(cells[2])
+        if depends is None:
+            # 비정수 depends_on 셀 → 행 skip (비정수 stage_number 와 동일). raw
+            # ValueError 를 흘리면 _stage_map_reject_detail·handoff 의 except
+            # PrepareError 를 우회해 traceback 으로 죽으므로, 누락된 행을 하류
+            # S2(비단조) 검사가 잡게 한다.
+            continue
         try:
             step_count = int(cells[3])
         except ValueError:
             step_count = -1
         rows.append(StageMeta(n, cells[1], depends, step_count, cells[4]))
-    errors: List[ValidationError] = []
-    for i, r in enumerate(rows, start=1):
-        if r.stage_number != i:
-            errors.append(ValidationError("S2", r.stage_number,
-                f"stage numbers must be 1..N monotonic, got {r.stage_number} at row {i}"))
-    return rows, errors
+    return rows, _stage_numbers_monotonic(rows)
 
 
 def _slice_stage_section(text: str, stage_number: int) -> str:
@@ -358,16 +372,8 @@ def _extract_exit_contract_files(section: str) -> set:
     return set(PATH_TOKEN.findall(body))
 
 
-def _check_parallel_safety(text: str, stages: List[StageMeta]) -> List[ValidationError]:
-    """S9: two `depends-on (none)` stages must not predict the same file —
-    otherwise two parallel implementation runs would edit it concurrently."""
-    files = {
-        s.stage_number: _extract_exit_contract_files(
-            _slice_stage_section(text, s.stage_number)
-        )
-        for s in stages
-        if not s.depends_on
-    }
+def _report_shared_parallel_files(files: dict) -> List[ValidationError]:
+    """S9 over an already-extracted {stage_number: {path}} map."""
     errs: List[ValidationError] = []
     nums = sorted(files)
     for i in range(len(nums)):
@@ -381,6 +387,18 @@ def _check_parallel_safety(text: str, stages: List[StageMeta]) -> List[Validatio
     return errs
 
 
+def _check_parallel_safety(text: str, stages: List[StageMeta]) -> List[ValidationError]:
+    """S9: two `depends-on (none)` stages must not predict the same file —
+    otherwise two parallel implementation runs would edit it concurrently."""
+    return _report_shared_parallel_files({
+        s.stage_number: _extract_exit_contract_files(
+            _slice_stage_section(text, s.stage_number)
+        )
+        for s in stages
+        if not s.depends_on
+    })
+
+
 def collect_validation_errors(text: str) -> List[ValidationError]:
     """All S1–S11 checks against the report text; empty list means valid.
 
@@ -404,6 +422,130 @@ def collect_validation_errors(text: str) -> List[ValidationError]:
     return errors
 
 
+def _data_stage_metas(
+    stage_map: List[dict],
+) -> Tuple[List[StageMeta], List[ValidationError]]:
+    rows = []
+    for row in stage_map:
+        if not isinstance(row, dict) or not isinstance(row.get("stage"), int):
+            continue
+        depends = _parse_depends_on_cell(str(row.get("dependsOn") or ""))
+        if depends is None:
+            continue
+        rows.append(StageMeta(
+            row["stage"],
+            str(row.get("title") or ""),
+            depends,
+            row.get("stepCount") if isinstance(row.get("stepCount"), int) else -1,
+            str(row.get("exitContractSummary") or ""),
+        ))
+    return rows, _stage_numbers_monotonic(rows)
+
+
+def _check_data_slice_tdd(stage: dict) -> List[ValidationError]:
+    """S10c / S10e over one schema-v2 `stages[]` entry.
+
+    The schema already requires `sliceValue`, `acceptance`, and — through its
+    `if not tddExemption then testCase*` conditional — the three test cases, so
+    S10a/S10b/S10d are covered declaratively. Two rules a JSON Schema cannot
+    state are left: the RED→GREEN ordering across `stepwiseExecution` rows, and
+    that a `tddExemption` naming no allowed category cannot waive them. The
+    schema types `tddExemption` as a plain string, so `""` currently satisfies
+    the conditional and drops all three test cases with no reason given.
+    """
+    number = stage.get("stage") if isinstance(stage.get("stage"), int) else 0
+    if "tddExemption" in stage:
+        reason = str(stage.get("tddExemption") or "").lower()
+        if not any(cat in reason for cat in TDD_EXEMPTION_ALLOWED):
+            return [ValidationError("S10", number,
+                "S10e: 'tddExemption' reason must be one of "
+                + " / ".join(TDD_EXEMPTION_ALLOWED)
+                + " — an empty or arbitrary reason cannot waive RED/GREEN "
+                "and the three test cases")]
+        return []
+
+    steps = [s for s in (stage.get("stepwiseExecution") or []) if isinstance(s, dict)]
+    actions = [str(s.get("action") or "") for s in steps]
+    if not (actions and actions[0].startswith("RED:")
+            and any(a.startswith("GREEN:") for a in actions)):
+        return [ValidationError("S10", number,
+            "S10c: first stepwiseExecution action must start with 'RED:' and "
+            "some action with 'GREEN:', or declare a 'tddExemption'")]
+
+    errs: List[ValidationError] = []
+    for step in steps:
+        action = str(step.get("action") or "")
+        expected = str(step.get("expected") or "")
+        if action.startswith("RED:") and "FAIL" not in expected.upper():
+            errs.append(ValidationError("S10", number,
+                f"S10c: 'RED:' step's expected must read FAIL, got '{expected}'"))
+        elif action.startswith("GREEN:") and "PASS" not in expected.upper():
+            errs.append(ValidationError("S10", number,
+                f"S10c: 'GREEN:' step's expected must read PASS, got '{expected}'"))
+    return errs
+
+
+def _check_data_step_counts(
+    stage_map: List[StageMeta], stages: List[dict]
+) -> List[ValidationError]:
+    """The Stage Map row is the plan's own index of its stage body. A row
+    claiming a step count the body does not have makes the map unusable for
+    sizing a stage, which is the only reason the cell exists."""
+    by_number = {
+        s.get("stage"): s for s in stages
+        if isinstance(s, dict) and isinstance(s.get("stage"), int)
+    }
+    errs: List[ValidationError] = []
+    for meta in stage_map:
+        stage = by_number.get(meta.stage_number)
+        if stage is None:
+            errs.append(ValidationError("S3", meta.stage_number,
+                "stageMap row has no matching stages[] entry"))
+            continue
+        actual = len([
+            s for s in (stage.get("stepwiseExecution") or []) if isinstance(s, dict)
+        ])
+        if meta.step_count != actual:
+            errs.append(ValidationError("S4", meta.stage_number,
+                f"stageMap stepCount {meta.step_count} != "
+                f"{actual} stepwiseExecution rows"))
+    for number in sorted(n for n in by_number if n not in {m.stage_number for m in stage_map}):
+        errs.append(ValidationError("S3", number,
+            "stages[] entry has no matching stageMap row"))
+    return errs
+
+
+def collect_data_validation_errors(planning: dict) -> List[ValidationError]:
+    """The S-checks that schema v2 cannot express, over `implementationPlanning`.
+
+    `collect_validation_errors` scans rendered v1 Markdown, and
+    `validate_phase_boundary` returns before calling it for a v2 report — so on
+    the current schema nothing enforced the depends-on DAG, parallel-stage file
+    safety, RED→GREEN ordering, or the TDD-exemption vocabulary. The schema
+    covers presence and cardinality; this covers the relationships between
+    fields, which is what a JSON Schema has no way to say.
+    """
+    stage_map, errors = _data_stage_metas(planning.get("stageMap") or [])
+    stages = [s for s in (planning.get("stages") or []) if isinstance(s, dict)]
+    if not stage_map and not stages:
+        return errors
+
+    errors.extend(_check_data_step_counts(stage_map, stages))
+    errors.extend(_check_depends_on(stage_map))
+    errors.extend(_report_shared_parallel_files({
+        meta.stage_number: set(PATH_TOKEN.findall(
+            str((next(
+                (s for s in stages if s.get("stage") == meta.stage_number), {}
+            )).get("exitContract") or "")
+        ))
+        for meta in stage_map
+        if not meta.depends_on
+    }))
+    for stage in stages:
+        errors.extend(_check_data_slice_tdd(stage))
+    return errors
+
+
 def main(argv: List[str]) -> int:
     p = argparse.ArgumentParser()
     p.add_argument("--plan", required=True)