okstra 0.178.0 → 0.179.0

package/runtime/python/okstra_ctl/write_policy.py

@@ -131,6 +131,7 @@ def build_invocation_write_contract(
     artifact_paths: Sequence[Path],
     maximum_precision: BoundaryPrecision,
     planned_paths: Sequence[str] = (),
+    planned_paths_declared: bool = True,
     scratch_roots: Sequence[Path] = (),
     generated_paths: Sequence[str] = (),
     auxiliary_roots: Sequence[Path] = (),
@@ -146,6 +147,7 @@ def build_invocation_write_contract(
         "projectRoot": str(root),
         "artifactPaths": list(relative_artifacts),
         "plannedPaths": list(planned_paths),
+        "plannedPathsDeclared": planned_paths_declared,
         "protectedPaths": [".okstra", ".git"],
         "generatedPaths": list(generated_paths),
         "scratchRoots": [str(path) for path in scratch_roots],
@@ -198,6 +200,14 @@ def planned_paths_from_run_manifest(
     return _planned_paths_from_report(Path(approved), int(stage_value))
 
 
+def planned_paths_declared(project_root: Path, manifest: Mapping[str, Any]) -> bool:
+    """Whether this run's approved plan states its paths in the declared column."""
+    try:
+        return planned_paths_from_run_manifest(project_root, manifest)[1]
+    except WritePolicyError:
+        return False
+
+
 def derive_write_enforcement(
     policy: WritePolicy,
     maximum_precision: BoundaryPrecision,
@@ -466,7 +476,11 @@ def _relative_to_root(path: Path, root: Path, label: str) -> str:
     return relative
 
 
-def _planned_paths_from_report(report_path: Path, stage: int) -> tuple[str, ...]:
+def _planned_paths_from_report(
+    report_path: Path, stage: int
+) -> tuple[tuple[str, ...], bool]:
+    """(paths, declared). `declared` is False for a plan written before the
+    structured `plannedPaths` column existed."""
     payload = _read_json(report_path.with_suffix(".data.json"), "approved plan data")
     planning = payload.get("implementationPlanning")
     stages = planning.get("stages") if isinstance(planning, Mapping) else None
@@ -478,15 +492,40 @@ def _planned_paths_from_report(report_path: Path, stage: int) -> tuple[str, ...]
         None,
     ) if isinstance(stages, list) else None
     steps = selected.get("stepwiseExecution") if isinstance(selected, Mapping) else None
+    # `plannedPaths`, not `files`: the latter is prose written for a reader and
+    # splitting it on commas produced entries like `.npmrc (template only` and
+    # `no literal token)`, while a single cell naming a glob migration counted
+    # as one literal path. Every file the plan actually asked for then read as
+    # an unauthorized source change, which is a failure the executor cannot
+    # avoid by following the plan.
+    rows = steps if isinstance(steps, list) else []
     paths = {
+        str(path).strip().strip("`")
+        for step in rows if isinstance(step, Mapping)
+        for path in (step.get("plannedPaths") or [])
+        if isinstance(path, str) and path.strip()
+    }
+    if paths:
+        return _relative_paths(tuple(sorted(paths))), True
+    # A plan approved before `plannedPaths` existed carries its paths only in
+    # the prose `files` cell. Deriving them there is exactly what this change
+    # removed — it mis-splits globs and parentheticals — so the derived set is
+    # not used to reject anything. It travels with `plannedPathsDeclared:
+    # false`, which turns the path comparison off for that stage rather than
+    # failing every file the plan asked for. An in-flight task keeps running;
+    # the next planning run produces a plan the audit can actually enforce.
+    derived = {
         part.strip().strip("`")
-        for step in steps if isinstance(step, Mapping)
+        for step in rows if isinstance(step, Mapping)
         for part in str(step.get("files") or "").replace("<br>", ",").split(",")
         if part.strip()
-    } if isinstance(steps, list) else set()
-    if not paths:
-        raise WritePolicyError("implementer write policy stage has no planned paths")
-    return _relative_paths(tuple(sorted(paths)))
+    }
+    if not derived:
+        raise WritePolicyError(
+            "implementer write policy stage has no planned paths: the approved "
+            "plan's stepwise rows carry neither `plannedPaths` nor `files`"
+        )
+    return _relative_paths(tuple(sorted(derived))), False
 
 
 def _rooted(project_root: Path, value: str) -> Path:

package/runtime/python/okstra_project/state.py

@@ -104,7 +104,7 @@ def read_task_manifest(task_root: Path) -> Optional[dict]:
 
     **디스크는 건드리지 않는다.** 승격한 값을 여기서 되적으면 lock 없는
     read-modify-write 가 되어, 파싱과 쓰기 사이에 다른 프로세스가 적은
-    `currentPhase` · `phaseStates` · `latestReportPath` 를 되돌린다
+    `currentPhase` · `phaseStates` · `latestReportRecordPath` 를 되돌린다
     (`os.replace` 는 찢어진 읽기만 막고 갱신 유실은 못 막는다). 이 분기는
     디스크 포인터가 아직 문자열일 때 — 즉 업그레이드 직후 진행 중인 task 가
     살아 있을 때 — 만 발화하므로 되돌릴 수 있는 값이 바로 phase 진행 상태다.
@@ -155,7 +155,7 @@ _DERIVED_STATUS_STRING_FIELDS = (
     "workStatus",
     "currentStatus",
     "latestRunStatus",
-    "latestReportPath",
+    "latestReportRecordPath",
 )
 
 

package/runtime/python/okstra_token_usage/__init__.py

@@ -25,6 +25,6 @@ from .pricing import (
 )
 from .report import (
     SubstituteRefusedError,
-    populate_and_render,
+    populate_token_cells,
     populate_data_token_cells,
 )

package/runtime/python/okstra_token_usage/cli.py

@@ -9,7 +9,7 @@ from pathlib import Path
 from .collect import collect
 from .report import (
     SubstituteRefusedError,
-    populate_and_render,
+    populate_token_cells,
 )
 
 
@@ -130,7 +130,7 @@ def main() -> int:
 
     if args.substitute_data is not None:
         try:
-            cells_changed, bytes_written = populate_and_render(
+            cells_changed = populate_token_cells(
                 args.substitute_data,
                 updated,
             )
@@ -142,7 +142,7 @@ def main() -> int:
             return 2
         print(
             f"final-report substitution: populated {cells_changed} cell(s) in "
-            f"{args.substitute_data}, re-rendered {bytes_written} bytes of markdown.",
+            f"{args.substitute_data}. The full reading copy is on-demand.",
             file=sys.stderr,
         )
 

package/runtime/python/okstra_token_usage/report.py

@@ -18,11 +18,6 @@ from okstra_ctl.design_prep import (  # noqa: E402
     DesignPrepError,
     materialize_design_prep_requests,
 )
-from okstra_ctl.final_report_paths import final_report_markdown_path  # noqa: E402
-from okstra_ctl.render_final_report import (  # noqa: E402
-    FinalReportRenderError,
-    render_to_file,
-)
 
 from .task_totals import task_cumulative_usage  # noqa: E402
 
@@ -270,28 +265,16 @@ def populate_data_token_cells(data_path: Path, team_state: dict) -> int:
     return changes
 
 
-def populate_and_render(
+def populate_token_cells(
     data_path: Path,
     team_state: dict,
-    *,
-    output_path: Path | None = None,
-) -> tuple[int, int]:
-    """Mutate data.json + render the markdown sibling. Returns
-    ``(cells_changed, bytes_written)``.
-
-    The caller is normally Phase 7 step 1 (token-usage CLI with the
-    ``--substitute-data`` flag). The rendered markdown is the canonical
-    user-facing artifact; data.json is the SSOT.
+) -> int:
+    """Mutate data.json token cells and materialize design-prep requests.
+
+    The full reading copy is rendered on demand with
+    ``okstra render-final-report``.
     """
     changes = populate_data_token_cells(data_path, team_state)
-
-    if output_path is None:
-        output_path = final_report_markdown_path(data_path)
-
-    try:
-        bytes_written = render_to_file(data_path, output_path)
-    except FinalReportRenderError as exc:
-        raise SubstituteRefusedError(f"render after substitute failed: {exc}") from exc
     if data_path.name.startswith("final-report-implementation-planning-"):
         try:
             materialize_design_prep_requests(data_path)
@@ -299,4 +282,4 @@ def populate_and_render(
             raise SubstituteRefusedError(
                 f"design-prep request materialization failed: {exc}"
             ) from exc
-    return changes, bytes_written
+    return changes

package/runtime/schemas/convergence-groups-v1.0.schema.json

@@ -38,7 +38,7 @@
       "additionalProperties": false,
       "properties": {
         "workerId": { "type": "string", "pattern": "\\S" },
-        "audience": { "enum": ["analysis", "report-writer"] }
+        "audience": { "enum": ["analysis", "lead", "report-writer"] }
       }
     },
     "Group": {

package/runtime/schemas/convergence-groups-v2.0.schema.json

@@ -56,7 +56,7 @@
       "additionalProperties": false,
       "properties": {
         "workerId": { "type": "string", "pattern": "\\S" },
-        "audience": { "enum": ["analysis", "report-writer"] },
+        "audience": { "enum": ["analysis", "lead", "report-writer"] },
         "participantRef": { "type": "string", "pattern": "\\S" },
         "sourceRoleExecutionRef": { "type": "string", "pattern": "\\S" }
       }

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

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://okstra.dev/schemas/final-report-v2.0.json",
   "title": "OKSTRA Final Report Data (v2.0)",
-  "description": "JSON SSOT for okstra final reports. Written by report-writer-worker in Phase 6, then consumed independently by the AI handoff Markdown renderer and the task-specific human HTML renderer.",
+  "description": "JSON SSOT for okstra final reports. Written by report-writer-worker in Phase 6, then consumed independently by the on-demand full reading copy Markdown renderer and the task-specific human HTML renderer.",
   "type": "object",
   "required": [
     "schemaVersion",
@@ -8627,6 +8627,7 @@
         "step",
         "action",
         "files",
+        "plannedPaths",
         "command",
         "outcome",
         "expectedDetail"
@@ -8645,6 +8646,15 @@
           "type": "string",
           "minLength": 1
         },
+        "plannedPaths": {
+          "description": "Repository-relative paths this step may write, one per entry. `files` is prose for a human reader and cannot serve as a path ledger — it carries globs, exclusions and counts — so the implementer write policy reads this list instead.",
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
         "command": {
           "type": "string",
           "minLength": 1

package/runtime/skills/okstra-inspect/facets/history.md

@@ -17,14 +17,14 @@ Trigger phrases: "okstra history", "past runs", "run history", "re-run", "list t
    - `--task-group <group>` → keep entries whose `taskGroup` matches.
 3. Sort by `updatedAt` desc.
 4. Page: default `--limit 20`. If truncated, add `... <N> more (pass --limit <N> to see all)`.
-5. Extract: `taskKey`, `taskType`, `currentStatus`, `latestRunStatus`, `latestRunManifestPath`, `updatedAt`, `latestReportPath`, `latestResumeCommandPath`, `historyTimelinePath`.
+5. Extract: `taskKey`, `taskType`, `currentStatus`, `latestRunStatus`, `latestRunManifestPath`, `updatedAt`, `latestReportRecordPath`, `latestResumeCommandPath`, `historyTimelinePath`.
 
 ```markdown
 ## okstra Task History — <project-id>
 
 | # | Task Key | Type | currentStatus | latestRunStatus | Last Run | Report |
 |---|----------|------|---------------|------------------|----------|--------|
-| 1 | proj:group:id | error-analysis | completed | completed | 2026-04-05 22:59 | .project-docs/.../final-report-*.md |
+| 1 | proj:group:id | error-analysis | completed | completed | 2026-04-05 22:59 | .project-docs/.../final-report-*.data.json |
 | 2 | proj:group:id2 | final-verification | todo | error | 2026-04-04 15:30 | -- |
 ```
 
@@ -47,7 +47,7 @@ When a user selects a specific task:
 
 | # | Timestamp | Type | Status | Report |
 |---|-----------|------|--------|--------|
-| 1 | 2026-04-05 22:59 | error-analysis | completed | .../final-report-*.md |
+| 1 | 2026-04-05 22:59 | error-analysis | completed | .../final-report-*.data.json |
 | 2 | 2026-04-04 15:30 | error-analysis | error | -- |
 ```
 

package/runtime/skills/okstra-inspect/facets/recap.md

@@ -26,7 +26,7 @@ Parse the stdout JSON (`{taskKey, runCount, transitions[], latestPhaseStates}`)
 
 `nextRecommendedPhase` in each entry is an **object** `{phase, status, rationale}`, not a phase-name string. Narrate it as `phase` when `phase` is non-empty, and as what `status` says otherwise — `pending` (that run did not settle the route), `blocked` (it stopped on something outside the run), `terminal` (the lifecycle ended there). Printing the object itself puts a raw dict in front of the reader.
 
-For a run that has a `reportPath`, read that final-report to enrich the summary only when the user wants a deeper one (do not read them all automatically).
+For a run that has a `reportPath`, read that report record (`.data.json`) to enrich the summary only when the user wants a deeper one (do not read them all automatically).
 
 ### recap.3 — Free-form Q&A loop
 

package/runtime/skills/okstra-inspect/facets/report.md

@@ -14,20 +14,20 @@ task-key format: `<project-id>:<task-group>:<task-id>`.
 
 Lookup methods (in priority order):
 
-A. **`task-catalog.json` (fast):** read `.okstra/discovery/task-catalog.json`, match `taskKey` lowercase. `latestReportPath` is task-type-agnostic "most recent report".
+A. **`task-catalog.json` (fast):** read `.okstra/discovery/task-catalog.json`, match `taskKey` lowercase. `latestReportRecordPath` is task-type-agnostic "most recent report".
 
-B. **`task-manifest.json` (direct):** if catalog missing, slugify task-group / task-id, read `.okstra/tasks/<group-segment>/<task-id-segment>/task-manifest.json`, use `latestReportPath` (task-type-agnostic).
+B. **`task-manifest.json` (direct):** if catalog missing, slugify task-group / task-id, read `.okstra/tasks/<group-segment>/<task-id-segment>/task-manifest.json`, use `latestReportRecordPath` (task-type-agnostic).
 
 C. **`timeline.json` (specific run):** for a specific date or run, read `.okstra/tasks/<group-segment>/<id-segment>/history/timeline.json`, filter `runs[]` by `runTimestamp` / `status` / `taskType`, use `runs[].reportPath`.
 
-D. **Specific task-type (fallback):** `latestReportPath` is task-type-agnostic. For a specific task-type's latest report, look under `.okstra/tasks/<group-segment>/<id-segment>/runs/<task-type-segment>/reports/`, filename pattern `final-report-<task-type-segment>-<NNN>.md` per `scripts/okstra_ctl/sequence.py:30`. Highest seq is latest. Stage-isolated runs (`implementation`, single-stage `final-verification`) keep their reports one level deeper at `runs/<task-type-segment>/stage-<N>/reports/` — scan those subdirectories too; seq is independent per stage. Cross-verify with `timeline.json`'s `runs[].taskType` filter.
+D. **Specific task-type (fallback):** `latestReportRecordPath` is task-type-agnostic. For a specific task-type's latest report, look under `.okstra/tasks/<group-segment>/<id-segment>/runs/<task-type-segment>/reports/`, filename pattern `final-report-<task-type-segment>-<NNN>.data.json`. Highest seq is latest. Stage-isolated runs (`implementation`, single-stage `final-verification`) keep their reports one level deeper at `runs/<task-type-segment>/stage-<N>/reports/` — scan those subdirectories too; seq is independent per stage. Cross-verify with `timeline.json`'s `runs[].taskType` filter. If the user wants the full reading copy, render it with `okstra render-final-report <that data.json>`.
 
 ### report.2 — Confirm existence
 
-1. Verify `latestReportPath` is non-empty AND the file exists on disk. Either signal indicates report presence (tolerant).
+1. Verify `latestReportRecordPath` is non-empty AND the file exists on disk. Either signal indicates report presence (tolerant).
 2. If present, display the path and ask the user whether to read it.
 3. If absent, check `task-manifest.json` signals:
-   - `latestReportPath` empty/missing AND `currentStatus != completed` AND `workStatus != done` AND `workflow.nextRecommendedPhase.status != "terminal"` → `This task is not yet complete (currentStatus: <currentStatus>, workStatus: <workStatus>).`
+   - `latestReportRecordPath` empty/missing AND `currentStatus != completed` AND `workStatus != done` AND `workflow.nextRecommendedPhase.status != "terminal"` → `This task is not yet complete (currentStatus: <currentStatus>, workStatus: <workStatus>).`
    - Any signal indicates completion but the file is missing → `Report file does not exist: <path>`
 
 `workStatus` enum: `todo | in-progress | blocked | done`. `currentStatus`: `completed` / `contract-violated` etc. `"completed"` string does NOT exist in `workStatus` — do not confuse the two.

package/runtime/skills/okstra-inspect/facets/status.md

@@ -21,7 +21,7 @@ Read `.okstra/discovery/task-catalog.json`. The catalog is the authoritative sou
 | `nextRecommendedPhase` | next-phase pointer — an **object** `{phase, status, rationale}`, never a string. `status` is `ready` / `pending` / `blocked` / `terminal`. The lead writes `phase` only under `ready`, but that is an authoring rule, not a constraint the struct enforces — `prepare` lowers a `ready` pointer to `pending` and keeps its `phase`, so a non-`ready` pointer that still names a phase is a normal state to read. Decide launchability from `status` alone. Render `phase` (or `--` when it is empty) — never the object itself. |
 | `awaitingApproval` | whether awaiting approval |
 | `latestRunStatus` | latest run status |
-| `latestReportPath` | latest report path |
+| `latestReportRecordPath` | latest report path |
 | `latestResumeCommandPath` | latest resume command |
 | `workStatus` | user-managed work status (todo / in-progress / blocked / done; default in-progress) |
 | `updatedAt` | last update time |
@@ -51,7 +51,7 @@ Given a specific `task-key` or `task-group + task-id`:
 2. If necessary, read `.okstra/tasks/<task-group>/<task-id>/task-manifest.json` directly.
 3. If you need the latest run information, read `history/timeline.json` along with the latest run manifest.
 
-Required fields: `taskKey`, `taskType`, `workCategory`, `currentStatus`, `latestRunStatus`, `workflow.{currentPhase, currentPhaseState, phaseStates, lastCompletedPhase, nextRecommendedPhase, awaitingApproval, lastSafeCheckpoint}`, `workStatus`, `workStatusUpdatedAt`, `workStatusNote`, `latestReportPath`, `latestResumeCommandPath`, `historyTimelinePath`.
+Required fields: `taskKey`, `taskType`, `workCategory`, `currentStatus`, `latestRunStatus`, `workflow.{currentPhase, currentPhaseState, phaseStates, lastCompletedPhase, nextRecommendedPhase, awaitingApproval, lastSafeCheckpoint}`, `workStatus`, `workStatusUpdatedAt`, `workStatusNote`, `latestReportRecordPath`, `latestResumeCommandPath`, `historyTimelinePath`.
 
 `workflow.nextRecommendedPhase` is the `{phase, status, rationale}` object described in `status.1` — read its three fields, do not print it whole. A `task-manifest.json` written before the object existed still holds a bare string there; `scripts/okstra_ctl/next_phase.py::promote` is what turns that string into the object, and every CLI-projected surface you can read instead (`task-catalog.json`, `okstra rollup`, `okstra recap`) has already applied it. Prefer those over a raw manifest rather than promoting a legacy string yourself.
 

package/runtime/skills/okstra-pr-gen/SKILL.md

@@ -112,7 +112,7 @@ okstra's own artifact identifiers are out of the allowlist — drop them:
 
 - report item ids — `F-001`, `C-001`, `R-001`, `D-0001`, `PREP-001`
 - run artifact names and their `<task-type>-<seq>` suffixes —
-  `final-report-implementation-3.md`, `run-manifest-implementation-3.json`
+  `final-report-implementation-3.data.json`, `run-manifest-implementation-3.json`
 - phase / stage / worker labels — `final-verification`, `stage-2`, `codex-worker`
 - any path under `.okstra/` — reports, decisions, glossary, user-response sidecars
 

package/runtime/skills/okstra-run/SKILL.md

@@ -384,7 +384,7 @@ Do not read the wizard state file directly. `okstra wizard outcome` exposes any
 | `No module named okstra_ctl.wizard` | Install predates wizard module | `npx okstra@latest install` to refresh. |
 | `wizard step` returns `ok: false` repeatedly | User keeps giving invalid answers | Echo the error verbatim and re-prompt the same step — do not advance. |
 | `task root not found for <key>` | catalog entry stale or task-key typo | Restart the wizard (`okstra wizard init`) to refresh the pick list. |
-| `approved plan is not yet approved (frontmatter ...)` | `implementation` without proper approval | Ask the user to flip the plan's frontmatter `approved` field to `true` (manual edit or `--approve`), or pick a different task-type. |
+| `approved plan is not yet approved (frontmatter ...)` | `implementation` without proper approval | Ask the user to re-run with `--approve` or confirm approval in the in-session wizard, or pick a different task-type. Editing the full reading copy does not approve the plan. |
 
 ## Output Rules
 

package/runtime/skills/okstra-schedule-gen/SKILL.md

@@ -96,7 +96,7 @@ If 0 tasks remain, output `All tasks in this task-group are done. There is no sc
 
 ### Step 3: Per-task stage extraction (Stage Map source)
 
-For each in-scope task, the **authoritative source is its `implementation-planning` Stage Map resolved by the CLI**. Do not hand-parse it or use `latestReportPath` to choose its source. Call:
+For each in-scope task, the **authoritative source is its `implementation-planning` Stage Map resolved by the CLI**. Do not hand-parse it or use `latestReportRecordPath` to choose its source. Call:
 
 ```bash
 okstra stage-map <task-key> --json

package/runtime/skills/okstra-user-response/SKILL.md

@@ -75,7 +75,7 @@ Returns `{reportPath, rows: [{id, kind, blocks, status, statement, expectedForm,
 
 Each entry of `options[]` is `{role, answer, rationale, scopeImpact, addedWork, directionChange, disposition}`. `role` is `recommended` for exactly one entry and `alternative` for the rest; `scopeImpact` is a token list drawn from `in-repo` / `cross-repo` / `new-schema` / `deferrable`; `addedWork` and `directionChange` are one sentence each. Activity-contract v1 approval options also carry the gate action in `disposition`. A legacy schema-v1 report has nowhere to record impact or a gate action, so those fields arrive empty — the CLI reconstructs only the answers from the report's `Expected form` cell.
 
-`resolvedRefs` is `[{ref, definition}]` — the CLI has already looked up what each internal token (`RB-002`, `FU-001`, `§4.7`, …) means in the report body; `definition` is `null` only when the report text alone could not resolve it (e.g. a `path:line` pointer).
+`resolvedRefs` is `[{ref, definition}]` — the CLI has already looked up what each record coordinate (`RB-002`, `FU-001`) means in the report record; `definition` is `null` when the record has no such row, when the citation is a section number (`§4.7`, leftover from an older report), or when the citation is a `path:line` pointer.
 
 This call is a **data fetch, not a presentation step**. Do not print `rows` at the user, and do not paste a raw `statement` as a question — a `statement` like `Rewrite RB-002 rollback (see §4.7)` is meaningless on its own, which is the whole reason this skill exists. Announce only the count and the plan:
 
@@ -100,7 +100,7 @@ Walk the open rows in report order. **One item per `AskUserQuestion` call** —
 Where the background comes from — in this order:
 
 - `resolvedRefs[].definition`, which is already resolved and needs no file read;
-- when a `definition` is `null`, or the three blocks would otherwise be empty, **Read** the report `§`/`path:line` that this item's `contextRefs[]` points at and take it from there;
+- when a `definition` is `null`, or the three blocks would otherwise be empty, **Read** the report record (the `.data.json` at `reportPath`) and take the cited row's `statement` / `summary` / `item` from there. Do not open the full reading copy to chase a `§` number — that number is not a record coordinate;
 - **never invent it.** If the report genuinely does not say why, write `The report states nothing beyond the statement itself.` and go straight to the question. Fabricated background corrupts the answer it collects.
 
 Close the background with the raw source on one line, so the mapping back to the report stays visible:
@@ -133,7 +133,7 @@ Record one entry — `{id, kind, value, rationale?, disposition}`, `kind` copied
 
 A reframe is not an answer, so it does not satisfy the approval gate.
 
-If the user replies with a question instead of an answer ("what does this mean?"), record nothing: **Read** the `§`/`path:line` from `contextRefs[]`, explain it in plain language, and re-ask the same item with the same options. Explain only — **do not resolve it for them**; the decision goes back to the user.
+If the user replies with a question instead of an answer ("what does this mean?"), record nothing: **Read** the report record for the cited row id from `contextRefs[]`, explain it in plain language, and re-ask the same item with the same options. Explain only — **do not resolve it for them**; the decision goes back to the user.
 
 Echo one line per finished item (`[2/5] C-014 → answer: 60s`), then ask the next one. Do not summarize the whole set until Step 4.
 

package/runtime/templates/project-docs/task-index.template.md

@@ -24,7 +24,7 @@ taskType: "{{FM_TASK_TYPE}}"
 - Worker Roster: `{{RECOMMENDED_ANALYSERS}}`
 - Lead Model: `{{LEAD_MODEL}}`
 - Latest Run: `{{LATEST_RUN_RELATIVE_PATH}}`
-- Latest Report: `{{LATEST_REPORT_RELATIVE_PATH}}`
+- Latest Report: `{{LATEST_REPORT_RECORD_RELATIVE_PATH}}`
 - Team State: `{{TEAM_STATE_RELATIVE_PATH}}`
 - Validation Status: `{{VALIDATION_STATUS}}`
 - Resume Command: `{{CLAUDE_RESUME_COMMAND_RELATIVE_PATH}}`

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

@@ -14,7 +14,7 @@ Write `- PROGRESS: <stage> <ISO-8601-UTC>` there before reading and at least eve
 
 - Author the data.json at `**Result Path:**` and the audit file at `**Audit sidecar path:**`.
 - Follow the task-type schema excerpt and Phase 6 report-writer contract. Do not perform independent analysis, edit source code, or load implementation coding-preflight resources.
-- Invoke `okstra render-final-report <Result Path>` after writing data.json and verify the markdown sibling exists before returning.
+- Do not invoke `okstra render-final-report`. The full reading copy is rendered on demand.
 - Preserve source item IDs, convergence classifications, round history, and unresolved dissent; do not recompute them from intuition.
 - Every `clarificationItems[]` row you leave `status: open` with `blocks: approval` carries `origin` and `userConfirmation`. `origin` is `worker-finding` only when an analyser or verifier reached it on its own evidence — when the lead's dispatch prompt told you to raise it, it is `lead-directed`, whatever the workers then agreed. `userConfirmation` is what the lead reports having done about it (`asked-and-answered` / `asked-awaiting` / `deferred-no-interactive-session`); if the dispatch does not say, write `asked-awaiting` and name the gap in your return message rather than guessing. An open approval blocker stops the whole task, so a row that misreports where it came from costs a re-run. **Enforced:** `validators/validate-run.py` `_validate_open_approval_blocker_provenance`.
 

package/runtime/validators/forbidden_actions.py

@@ -15,10 +15,12 @@ Bash tool_use 명령을 phase deny-list 와 대조해 위반을 기계적으로
 한계 1: claude-code 세션 jsonl 만 스캔한다. codex/antigravity lead·worker 는 동일 형식의
 tool_use transcript 를 ~/.claude/projects 에 남기지 않으므로 이 스캐너의 사정권 밖이며,
 해당 런타임의 금지 행위는 여전히 수동 감사에 의존한다.
-한계 2: deny-list 는 heredoc 본문을 걷어낸(strip_heredoc_bodies) 명령 문자열 전체를
-검색하므로, 금지 토큰이 인자/메시지에 등장하는 경우(예: `git commit -m "... npm
-publish ..."`)는 여전히 위반으로 잡힐 수 있다. `cd <path> && <cmd>` 형태 때문에 명령
-head 앵커링은 불가하므로 이 잔여 오탐은 감수한다.
+한계 2: deny-list 는 heredoc 본문과 검색 명령 절을 걷어낸(strip_heredoc_bodies,
+strip_search_clauses) 명령 문자열 전체를 검색하므로, 금지 토큰이 인자/메시지에
+등장하는 경우(예: `git commit -m "... npm publish ..."`)는 여전히 위반으로 잡힐 수
+있다. `cd <path> && <cmd>` 형태 때문에 명령 head 앵커링은 불가하므로 이 잔여 오탐은
+감수한다. 검색 절을 예외로 둔 것은 그 오탐이 우연이 아니라 계약이 시키는 감사에서
+반드시 발생하기 때문이다.
 """
 from __future__ import annotations
 
@@ -86,6 +88,75 @@ def strip_heredoc_bodies(command: str) -> str:
     return "\n".join(kept)
 
 
+_SEARCH_HEADS = frozenset({"grep", "egrep", "fgrep", "rg", "ag", "ack"})
+
+
+def _shell_clauses(command: str) -> list[str]:
+    """쉘 구분자로 자른 절 목록. 인용 안의 구분자는 자르지 않는다.
+
+    검색 패턴은 거의 언제나 `'git push|npm publish'` 처럼 인용된 교대(alternation)
+    이므로, 인용을 무시하고 자르면 패턴이 절 경계로 쪼개져 뒷조각이 그대로 명령처럼
+    남는다.
+    """
+    clauses: list[str] = []
+    buffer: list[str] = []
+    quote = ""
+    index = 0
+    while index < len(command):
+        char = command[index]
+        if quote:
+            buffer.append(char)
+            if char == quote:
+                quote = ""
+            index += 1
+            continue
+        if char in "'\"":
+            quote = char
+            buffer.append(char)
+            index += 1
+            continue
+        if command.startswith(("&&", "||"), index):
+            clauses.append("".join(buffer))
+            buffer = []
+            index += 2
+            continue
+        if char in ";|\n":
+            clauses.append("".join(buffer))
+            buffer = []
+            index += 1
+            continue
+        buffer.append(char)
+        index += 1
+    clauses.append("".join(buffer))
+    return clauses
+
+
+def strip_search_clauses(command: str) -> str:
+    """검색 명령 절을 걷어낸 명령 문자열.
+
+    `grep -E 'git push|npm publish' <logs>` 의 패턴은 실행되는 명령이 아니라
+    **찾는 대상**이다. 그리고 그 감사는 우연이 아니라 계약이 시킨다 —
+    `_implementation-deliverable.md` 의 자체 리뷰 항목이 리드에게 세션
+    트랜스크립트에서 배포 명령을 스캔하라고 요구한다. 걷어내지 않으면 계약을
+    이행한 런이 매번 그 이행 때문에 실패했다.
+
+    절 단위로 자르므로 `cd <path> && grep …` 에서도 grep 절만 빠지고, 같은 줄
+    뒤에 이어지는 실제 명령은 계속 스캔된다.
+    """
+    kept: list[str] = []
+    for clause in _shell_clauses(command):
+        tokens = clause.split()
+        if not tokens:
+            continue
+        head = tokens[0].rsplit("/", 1)[-1]
+        if head in _SEARCH_HEADS:
+            continue
+        if head == "git" and len(tokens) > 1 and tokens[1] == "grep":
+            continue
+        kept.append(clause)
+    return "\n".join(kept)
+
+
 def forbidden_patterns_for(task_type: str) -> list[tuple[str, re.Pattern]]:
     """task_type(=phase profile) 의 deny-list. 모든 phase 가 _UNIVERSAL 을 받고,
     release-handoff 를 제외한 모든 phase 는 bare `git push` 도 금지한다
@@ -142,7 +213,7 @@ def _scan_one(
                 if block.get("type") != "tool_use" or block.get("name") != "Bash":
                     continue
                 command = (block.get("input") or {}).get("command") or ""
-                executed = strip_heredoc_bodies(command)
+                executed = strip_search_clauses(strip_heredoc_bodies(command))
                 for label, pattern in patterns:
                     if pattern.search(executed):
                         hits.append((label, command))

package/runtime/validators/lib/fixtures.sh

@@ -197,7 +197,7 @@ run_manifest_path = project_root / latest_run["runManifestPath"]
 run_manifest = load_json(run_manifest_path)
 team_state_path = project_root / run_manifest["teamStatePath"]
 team_state = load_json(team_state_path)
-report_path = project_root / run_manifest["expectedReportPath"]
+report_path = project_root / run_manifest["expectedReportRecordPath"]
 final_status_path = project_root / run_manifest["expectedStatusPath"]
 
 status_by_worker_id = {
@@ -412,7 +412,17 @@ report_lines.extend(
     ]
 )
 report_path.parent.mkdir(parents=True, exist_ok=True)
-report_path.write_text("\n".join(report_lines) + "\n")
+_report_name = report_path.name
+if _report_name.endswith(".data.json"):
+    data_path = report_path
+    md_path = report_path.with_name(_report_name[: -len(".data.json")] + ".md")
+elif _report_name.endswith(".md"):
+    md_path = report_path
+    data_path = report_path.with_name(_report_name[: -len(".md")] + ".data.json")
+else:
+    md_path = report_path
+    data_path = report_path.with_suffix(".data.json")
+md_path.write_text("\n".join(report_lines) + "\n")
 
 # Phase 7 step 1.5 (BLOCKING) — render the html sibling artifact next
 # to the final-report so validate-run.py's report-views hook passes.
@@ -460,12 +470,6 @@ if WORKSPACE_ROOT:
                 {**_rows[min(i, len(_rows) - 1)], "role": role}
                 for i, role in enumerate(_required)
             ]
-        name = report_path.name
-        data_path = (
-            report_path.with_name(name[:-3] + ".data.json")
-            if name.endswith(".md")
-            else report_path.with_suffix(".data.json")
-        )
         data_path.write_text(
             json.dumps(sample, indent=2, ensure_ascii=False) + "\n",
             encoding="utf-8",
@@ -481,7 +485,7 @@ if WORKSPACE_ROOT:
         try:
             from okstra_ctl.render_final_report import render_to_file
 
-            render_to_file(data_path, report_path)
+            render_to_file(data_path, md_path)
         except Exception as exc:  # pragma: no cover — fixture path only
             raise SystemExit(f"failed to render final report in fixture: {exc}")
     # Go through the same CLI the run uses, so the fixture picks the schema's
@@ -491,7 +495,7 @@ if WORKSPACE_ROOT:
         [
             _sys.executable,
             str(Path(WORKSPACE_ROOT) / "scripts" / "okstra-render-report-views.py"),
-            str(report_path),
+            str(data_path),
             "--task-key", str(task_manifest.get("taskKey", "validation/fixture")),
             "--task-type", str(task_manifest.get("taskType", "validation")),
             "--seq", "001",

package/runtime/validators/lib/runners.sh

@@ -70,7 +70,7 @@ if latest_run is None:
 run_manifest_path = project_root / latest_run["runManifestPath"]
 run_manifest = json.loads(run_manifest_path.read_text())
 team_state_path = project_root / run_manifest["teamStatePath"]
-report_path = project_root / run_manifest["expectedReportPath"]
+report_path = project_root / run_manifest["expectedReportRecordPath"]
 final_status_path = project_root / run_manifest["expectedStatusPath"]
 
 process = subprocess.run(

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

@@ -523,6 +523,9 @@ def _check_data_step_counts(
             errs.append(ValidationError("S4", meta.stage_number,
                 f"stageMap stepCount {meta.step_count} != "
                 f"{actual} stepwiseExecution rows"))
+        if actual > HARD_STEP_CAP:
+            errs.append(ValidationError("S5", meta.stage_number,
+                f"effective step count {actual} exceeds {HARD_STEP_CAP}"))
     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"))

package/runtime/validators/validate-report-views.py

@@ -188,7 +188,7 @@ def validate(report_path: Path) -> list[str]:
     """Validate the html view of the report named by *report_path*.
 
     A schema-v2 report is checked against its data.json and the rendered html;
-    the AI-handoff markdown is a sibling rendering of the same record and is
+    the full reading copy markdown is a sibling rendering of the same record and is
     never read here, so it does not have to exist. Schema-v1 reports keep the
     markdown as their source and still require it.
     """