okstra 0.129.0 → 0.130.0

package/runtime/python/okstra_ctl/scope_provenance.py

@@ -0,0 +1,129 @@
+"""Single source of truth for scope-provenance grammar.
+
+Every requirement a phase emits must declare where it came from. Shared by
+validators/validate-run.py and validators/validate_fanout.py so the grammar
+cannot drift between the planning report and the fan-out packets.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+# Items okstra's own phase contracts mandate — they have no brief line to cite.
+# Keep this narrow: a wide allowlist turns into a bypass for invented scope.
+CONTRACT_RULES = frozenset(
+    {
+        "decision-record-step",  # implementation-planning.md: decisionDrafts materialization
+        "glossary-step",         # implementation-planning.md: glossary proposals
+    }
+)
+
+# Mirrors the report schema's requirement id pattern
+# (schemas/final-report-v1.0.schema.json: `^R-\d{3,}$`).
+_REQ_ID_RE = re.compile(r"^R-\d{3,}$")
+_BRIEF_RE = re.compile(r"^brief:\s*(?P<heading>.+?)\s*$")
+_DERIVED_RE = re.compile(r"^derived:\s*(?P<parent>\S+)\s*[—-]\s*(?P<reason>.+?)\s*$")
+_CONTRACT_RE = re.compile(r"^contract:\s*(?P<rule>.+?)\s*$")
+_BRIEF_HEADING_RE = re.compile(r"^(#{1,6}\s+.+?)\s*$")
+_FENCE_RE = re.compile(r"^\s*(`{3,}|~{3,})")
+
+
+def normalize_heading(text: str) -> str:
+    """Heading text stripped of its `#` markers and surrounding whitespace.
+
+    Applied to both sides of the citation comparison so `brief:Acceptance
+    Criteria` and `brief:## Acceptance Criteria` both name the same heading.
+    The comparison stays exact after this — a heading the brief lacks must
+    still fail.
+    """
+    return " ".join(text.lstrip("#").split())
+
+
+def brief_headings(brief_path: Path) -> set[str]:
+    """Markdown headings present in the brief, normalized for comparison.
+
+    An unreadable brief yields an empty set so callers degrade to skipping
+    heading verification instead of failing every brief-sourced citation.
+
+    Fenced regions are skipped: a shell comment inside a ```bash block starts
+    with `#` too, and admitting it would let a requirement cite a "heading" the
+    reporter never wrote.
+    """
+    try:
+        text = Path(brief_path).read_text(encoding="utf-8")
+    except OSError:
+        return set()
+
+    headings: set[str] = set()
+    fence: str | None = None
+    for line in text.splitlines():
+        if m := _FENCE_RE.match(line):
+            marker = m.group(1)
+            if fence is None:
+                fence = marker[0]
+            elif marker[0] == fence:
+                fence = None
+            continue
+        if fence is not None:
+            continue
+        if m := _BRIEF_HEADING_RE.match(line):
+            headings.add(normalize_heading(m.group(1)))
+    return headings
+
+
+@dataclass(frozen=True)
+class SourceRef:
+    kind: Literal["brief", "derived", "contract", "invalid"]
+    value: str = ""
+    reason: str = ""
+
+
+def parse_source(raw: str) -> SourceRef:
+    text = (raw or "").strip()
+    if m := _DERIVED_RE.match(text):
+        parent = m.group("parent")
+        if not _REQ_ID_RE.match(parent):
+            return SourceRef("invalid")
+        return SourceRef("derived", parent, m.group("reason"))
+    if m := _BRIEF_RE.match(text):
+        return SourceRef("brief", m.group("heading"))
+    if m := _CONTRACT_RE.match(text):
+        rule = m.group("rule")
+        if rule not in CONTRACT_RULES:
+            return SourceRef("invalid")
+        return SourceRef("contract", rule)
+    return SourceRef("invalid")
+
+
+def resolve_chain(rows: dict[str, SourceRef]) -> dict[str, str]:
+    """Walk each row's derivation chain to its terminator.
+
+    Returns id -> "ok" or a one-line reason the chain is not admissible.
+    """
+    result: dict[str, str] = {}
+    for rid in rows:
+        seen: list[str] = []
+        cursor = rid
+        while True:
+            if cursor in seen:
+                result[rid] = f"derivation cycle: {' -> '.join(seen + [cursor])}"
+                break
+            seen.append(cursor)
+            ref = rows.get(cursor)
+            if ref is None:
+                result[rid] = f"derives from `{cursor}` which is not a row in this table"
+                break
+            if ref.kind in ("brief", "contract"):
+                result[rid] = "ok"
+                break
+            if ref.kind == "derived":
+                cursor = ref.value
+                continue
+            result[rid] = (
+                f"unrecognized source on `{cursor}` — must be one of "
+                "`brief:<heading>`, `derived:R-NNN — <reason>`, `contract:<rule>`"
+            )
+            break
+    return result

package/runtime/python/okstra_ctl/worker_liveness.py

@@ -110,9 +110,13 @@ def main(argv: list[str] | None = None) -> int:
         description="Report whether pending workers are still alive (read-only).",
     )
     parser.add_argument("--audit", action="append", default=[],
-                        help="claude-worker audit sidecar path (repeatable)")
+                        help="in-process claude-worker audit sidecar path (repeatable)")
     parser.add_argument("--prompt", action="append", default=[],
-                        help="CLI-wrapper prompt-history path (repeatable)")
+                        help="CLI-wrapper (codex/antigravity) prompt-history path "
+                             "(repeatable). Only the wrappers write the artifacts "
+                             "this probe looks for, so passing an in-process "
+                             "claude-worker path here always reports "
+                             "did-not-launch — probe those with --audit")
     parser.add_argument("--max-idle", type=float, default=HEARTBEAT_MAX_GAP_SECONDS,
                         help="heartbeat staleness budget in seconds")
     parser.add_argument("--launch-grace", type=float, default=DEFAULT_LAUNCH_GRACE_SECONDS,

package/runtime/python/okstra_ctl/worker_prompt_headers.py

@@ -6,6 +6,7 @@ from typing import Any, Mapping
 
 from .paths import okstra_home
 from .worker_prompt_policy import (
+    GRILLING_LOG_HEADER,
     PromptPlan,
     WORKER_ERROR_CONTRACT_FILENAME,
     WORKER_PREAMBLE_FILENAME_BY_AUDIENCE,
@@ -75,7 +76,7 @@ def worker_prompt_headers(
     ])
     if _string_value(manifest.get("taskType")) == "improvement-discovery":
         headers.append(
-            f"**Phase 1.5 Grilling Log:** "
+            f"{GRILLING_LOG_HEADER} "
             f"{_improvement_grilling_log_path(project_root, manifest)}"
         )
     if _string_value(manifest.get("taskType")) == "final-verification":

package/runtime/python/okstra_ctl/worker_prompt_policy.py

@@ -14,6 +14,9 @@ PromptAudience = Literal[
     "lead-only",
 ]
 
+# The prompt emitter, the run validator, and the worker-facing docs all bind to
+# this literal; restating it anywhere else silently forks the dispatch contract.
+GRILLING_LOG_HEADER = "**Phase 1.5 Grilling Log:**"
 FINAL_VERIFICATION_HEADERS = (
     "**Worktree:**",
     "**Verification scope:**",
@@ -98,7 +101,7 @@ def resolve_prompt_plan(
             "analysis",
             equality_group="analysis-core",
             packet_only=True,
-            required_headers=("**Phase 1.5 Grilling Log:**",),
+            required_headers=(GRILLING_LOG_HEADER,),
         )
     return _plan("analysis", equality_group="analysis-core", packet_only=True)
 

package/runtime/templates/reports/fan-out-unit.template.md

@@ -16,6 +16,17 @@ recommended-next-phase: {{NEXT_PHASE}}
 
 <!-- Self-contained description of the single work item this unit covers. Do not mix it with other units. -->
 
+## Requirement Provenance
+
+<!-- Where this unit's scope came from. One bullet per source. Every bullet must be
+     `brief:<heading>` (a heading that literally exists in the task brief) or
+     `contract:<rule>` (an okstra-mandated artifact). A unit you cannot source this
+     way is not a work item — raise it as a clarification instead of inventing it.
+     Unlike a planning report, `derived:<parent> — <reason>` is NOT accepted here: a
+     packet is validated on its own, so the parent it names cannot be resolved. -->
+
+- brief:
+
 ## Evidence
 
 <!-- path:line evidence. Locations that requirements-discovery confirmed via file inspection. -->

package/runtime/templates/worker-error-contract.md

@@ -27,14 +27,24 @@ If the sidecar does not exist when a real failure occurs, create `{"schemaVersio
   "durationMs": null,
   "message": "<one-line human summary>",
   "stderrExcerpt": null,
-  "context": null
+  "context": {
+    "cause": "sandbox-denied | service-unavailable | auth-failed | unknown",
+    "causeEvidence": {
+      "targetProbe": "<command + raw output proving the target's state>",
+      "controlProbe": "<command + raw output proving another target is reachable>"
+    }
+  }
 }
 ```
 
+`context` and both `cause` fields are optional; omit `context` entirely (`null`) when there is nothing to add.
+
 ### Rules
 
 - Do not add `source`, `recordedAt`, `agent`, `agentRole`, `model`, or `taskKey`; the lead supplies them when merging the sidecar.
 - The sidecar accepts only `errorType: "tool-failure"`. CLI wrappers write `cli-failure` directly to the run log; the lead records `contract-violation`.
+- To record a block (sandbox/permission) as the cause, submit `context.cause = "sandbox-denied"` together with both probes in `context.causeEvidence`. Without the probes, leave `cause` as `unknown` — and then keep `message` to what you observed (`connection refused`, `1045 access denied`), not what you infer. A block asserted in `message` prose is rejected exactly like one asserted in `cause`, so "sandbox blocked it" with `cause: unknown` fails the write too. Failing to reach a target and the target being down are not the same fact — never assert the former without checking. Only `sandbox-denied` requires evidence; `service-unavailable` and `auth-failed` do not. Each probe is stored truncated to 256 bytes, so lead with the decisive command and its output.
+- [Guideline] Put raw output in `stderrExcerpt` verbatim. Never merge several commands' output into one line, summarize it, or elide it with `...`. Once the host, port, and errno are gone, the cause cannot be recovered later.
 - Continue after recording unless the failure makes the task impossible.
 
 ### Path extraction (BLOCKING)

package/runtime/validators/lib/common.sh

@@ -33,12 +33,3 @@ assert_contains() {
     fail "Expected to find [$expected_text] in $target_path"
   fi
 }
-
-assert_not_contains() {
-  local target_path="$1"
-  local unexpected_text="$2"
-
-  if grep -F -- "$unexpected_text" "$target_path" >/dev/null 2>&1; then
-    fail "Did not expect to find [$unexpected_text] in $target_path"
-  fi
-}

package/runtime/validators/validate-run.py

@@ -49,6 +49,13 @@ from okstra_ctl.final_report_paths import final_report_data_path as _data_path_f
 from okstra_ctl.improvement_assignment import (  # noqa: E402
     validate_primary_lens_assignments,
 )
+from okstra_ctl.worker_prompt_policy import GRILLING_LOG_HEADER  # noqa: E402
+from okstra_ctl.scope_provenance import (  # noqa: E402
+    brief_headings,
+    normalize_heading,
+    parse_source,
+    resolve_chain,
+)
 from okstra_ctl.design_prep import (  # noqa: E402
     DesignPrepError,
     _planning_seq as _design_prep_planning_seq,
@@ -472,7 +479,7 @@ def _grilling_log_path_from_prompts(
     worker_ids: list[str],
     records: list[PromptRecord],
 ) -> tuple[Path | None, list[str]]:
-    header = "**Phase 1.5 Grilling Log:**"
+    header = GRILLING_LOG_HEADER
     values: set[str] = set()
     errors: list[str] = []
     for record in records:
@@ -2869,6 +2876,134 @@ def _validate_requirement_coverage_covered_by(data: dict, failures: list[str]) -
             )
 
 
+def _validate_requirement_provenance(
+    data: dict, brief_path: Path, failures: list[str]
+) -> None:
+    """Every requirement must declare where it came from.
+
+    The planning input template already states that any change beyond what
+    `Requirement Summary` demands is out of scope by default; without this
+    check that sentence has no enforcement point and a phase can invent
+    requirements freely.
+    """
+    ip = data.get("implementationPlanning")
+    if not isinstance(ip, dict):
+        return
+    rows = [r for r in (ip.get("requirementCoverage") or []) if isinstance(r, dict)]
+    if not rows:
+        return
+
+    refs = {
+        str(r.get("id") or "").strip(): parse_source(str(r.get("source") or ""))
+        for r in rows
+    }
+    headings = brief_headings(brief_path)
+
+    for rid, ref in refs.items():
+        if ref.kind == "brief" and headings:
+            if normalize_heading(ref.value) not in headings:
+                failures.append(
+                    f"final-report data.json: requirementCoverage `{rid}` cites brief "
+                    f"heading `{ref.value}` which does not exist in the brief. A "
+                    "requirement must trace to a line the reporter actually wrote."
+                )
+
+    for rid, verdict in resolve_chain(refs).items():
+        if verdict != "ok":
+            failures.append(
+                f"final-report data.json: requirementCoverage `{rid}` provenance "
+                f"failed — {verdict}. An item with no admissible source is not a "
+                "requirement: raise it as a `Blocks=approval` clarification instead."
+            )
+
+
+_CITED_STAGE_RANGE = r"(?:[-–]|\bto\b|\bthrough\b)"
+_CITED_STAGE_ITEM = rf"\d+(?:\s*{_CITED_STAGE_RANGE}\s*\d+)?"
+# `, and` / `, &` is one separator, not a separator followed by a stray word:
+# `Stages 1, 2, and 3` is the idiomatic plural and must not orphan stage 3.
+_CITED_STAGE_SEP = r"(?:,\s*(?:and|&)?|and|&)"
+_CITED_STAGE_LIST_RE = re.compile(
+    rf"\bstages?[ \t]*({_CITED_STAGE_ITEM}(?:\s*{_CITED_STAGE_SEP}\s*{_CITED_STAGE_ITEM})*)",
+    re.IGNORECASE,
+)
+_CITED_STAGE_ITEM_RE = re.compile(
+    rf"(\d+)(?:\s*{_CITED_STAGE_RANGE}\s*(\d+))?", re.IGNORECASE
+)
+_CITED_STAGE_RANGE_MAX_SPAN = 64
+
+
+def _cited_stage_numbers(covered_by: str) -> set[int]:
+    """Stage numbers a `coveredBy` cell cites, in every prose form a planner writes.
+
+    Deliberately not `_COVERED_BY_STAGE_REF_RE`: the two directions disagree on
+    what "no match" means — forward treats it as nothing to verify and passes,
+    reverse treats it as nothing cited and orphans every stage — so the reverse
+    reader must cover `Stages 1, 2`, `Stages 1-3` and `Stage 1 and 2` too.
+    Numbers stay anchored to a word-initial `stage`/`stages` token on the same
+    line; harvesting bare numbers — or letting the anchor reach across a line
+    break, or match the tail of `Substage`/`Backstage` — would let any prose,
+    including a row disclaiming every stage, justify any stage.
+    """
+    cited: set[int] = set()
+    for span in _CITED_STAGE_LIST_RE.finditer(covered_by):
+        for item in _CITED_STAGE_ITEM_RE.finditer(span.group(1)):
+            start = int(item.group(1))
+            cited.add(start)
+            if item.group(2) is None:
+                continue
+            end = int(item.group(2))
+            cited.add(end)
+            # A reversed or absurdly wide range is a typo, not a citation of
+            # everything between its endpoints.
+            if 0 <= end - start <= _CITED_STAGE_RANGE_MAX_SPAN:
+                cited.update(range(start, end))
+    return cited
+
+
+# Statuses under which a row asserts the plan does work for the requirement.
+# `gap` is excluded: it states the plan does NOT cover the requirement, so it
+# can justify no stage. `blocked C-NNN` is included — the requirement is real
+# and the stage serving it is not invented scope, only pending a user answer,
+# and such a row already forces a non-passing gate and `approved: false`, so
+# orphaning its stage here would only push planners to delete legitimate work.
+_COVERAGE_CLAIMING_STATUS_RE = re.compile(r"^(covered|blocked C-\d{3,})$")
+
+
+def _validate_stage_has_requirement(data: dict, failures: list[str]) -> None:
+    """Reverse of `_validate_requirement_coverage_covered_by`.
+
+    That check proves every requirement reaches a stage; this one proves every
+    stage traces back to a requirement. Without it a plan can carry stages no
+    one asked for and still pass every gate.
+    """
+    ip = data.get("implementationPlanning")
+    if not isinstance(ip, dict):
+        return
+    stage_numbers = {
+        s.get("stage")
+        for s in (ip.get("stages") or [])
+        if isinstance(s, dict) and isinstance(s.get("stage"), int)
+    }
+    if not stage_numbers:
+        return
+
+    cited: set[int] = set()
+    for row in (ip.get("requirementCoverage") or []):
+        if not isinstance(row, dict):
+            continue
+        if not _COVERAGE_CLAIMING_STATUS_RE.match(str(row.get("status") or "").strip()):
+            continue
+        cited |= _cited_stage_numbers(str(row.get("coveredBy") or ""))
+
+    for orphan in sorted(stage_numbers - cited):
+        failures.append(
+            f"final-report data.json: Stage {orphan} is cited by no requirementCoverage "
+            "row — it traces back to nothing the brief asked for. Either cite the "
+            "requirement it serves, or drop it and raise it as a `Blocks=approval` "
+            "clarification (profile: scope provenance)."
+        )
+
+
 def _validate_final_verification_consistency(data: dict, failures: list[str]) -> None:
     """Enforce verdict ↔ blocker/condition/routing consistency on the
     final-verification data.json (SSOT). The schema guarantees field SHAPE;
@@ -3323,7 +3458,7 @@ def _validate_convergence_states(run_dir, failures) -> None:
         )
 
 
-def _validate_requirements_discovery_fanout(run_dir, failures) -> None:
+def _validate_requirements_discovery_fanout(run_dir, failures, brief_path=None) -> None:
     """requirements-discovery run 에 fan-out/ 이 있으면 packet+index 를 검증해
     실패를 ``requirements-discovery: `` 접두로 folding 한다. fan-out 이 없으면 no-op.
     """
@@ -3340,7 +3475,7 @@ def _validate_requirements_discovery_fanout(run_dir, failures) -> None:
             f"requirements-discovery: validate_fanout import failed — {exc}"
         )
         return
-    result = validate_fanout(_Path(run_dir))
+    result = validate_fanout(_Path(run_dir), brief_path)
     if not result.ok:
         for err in result.errors:
             failures.append(f"requirements-discovery: {err}")
@@ -3757,6 +3892,15 @@ def main() -> int:
         _validate_conformance(report_path, failures, surface_patterns=_sp)
     if task_type == "implementation-planning":
         _validate_planning_conformance_declared(report_path, failures)
+        brief_relative = str(task_manifest.get("taskBriefPath") or "").strip()
+        planning_brief = (
+            (project_root / brief_relative).resolve()
+            if brief_relative
+            else project_root / "__no-brief__"  # absent path → brief_headings returns set()
+        )
+        planning_data = _load_final_report_data(report_path)
+        _validate_requirement_provenance(planning_data, planning_brief, failures)
+        _validate_stage_has_requirement(planning_data, failures)
     if task_type == "improvement-discovery":
         brief_relative = str(task_manifest.get("taskBriefPath") or "").strip()
         brief_path = (
@@ -3767,8 +3911,14 @@ def main() -> int:
         run_dir = report_path.parent.parent
         _validate_improvement_discovery(report_path, run_dir, brief_path, failures)
     if task_type == "requirements-discovery":
+        brief_relative = str(task_manifest.get("taskBriefPath") or "").strip()
+        brief_path = (
+            (project_root / brief_relative).resolve()
+            if brief_relative
+            else project_root / "__no-brief__"  # absent path → brief_headings returns set()
+        )
         run_dir = report_path.parent.parent
-        _validate_requirements_discovery_fanout(run_dir, failures)
+        _validate_requirements_discovery_fanout(run_dir, failures, brief_path)
     # Phase-agnostic: convergence runs in every finding-producing phase.
     _validate_convergence_states(report_path.parent.parent, failures)
     validate_report_views(report_path, failures)

package/runtime/validators/validate_fanout.py

@@ -17,11 +17,67 @@ for _ssot_dir in (_VALIDATORS_DIR.parent / "scripts", _VALIDATORS_DIR.parent / "
 
 from okstra_ctl.work_categories import WORK_CATEGORIES  # noqa: E402
 from okstra_ctl.fanout import topological_order, CycleError  # noqa: E402
+from okstra_ctl.scope_provenance import (  # noqa: E402
+    brief_headings,
+    normalize_heading,
+    parse_source,
+)
 
 _NEXT_PHASES = ("error-analysis", "implementation-planning")
 _UNIT_RE = re.compile(r"unit-\d{3}")
 # index.md 번호목록 항목에서만 unit-NNN 을 추출 — 내러티브 문장 중복 방지
 _INDEX_ENTRY_RE = re.compile(r"^\s*\d+\.\s+(unit-\d{3})\b", re.MULTILINE)
+# A `###` subsection inside the section still ends it: its prose is commentary,
+# not provenance, and parsing it as bullets rejects legitimate packets.
+_PROVENANCE_SECTION_RE = re.compile(
+    r"^##\s+Requirement Provenance\s*$(?P<body>.*?)(?=^#{2,}\s|\Z)",
+    re.MULTILINE | re.DOTALL,
+)
+_PROVENANCE_BULLET_RE = re.compile(r"^\s*[-*]\s+(?P<src>.+?)\s*$", re.MULTILINE)
+
+
+def _check_provenance(
+    pkt_name: str, text: str, errors: list[str], headings: set[str]
+) -> None:
+    """A fan-out unit must cite the brief line that demanded it.
+
+    `derived:` is not admissible here: cross-packet derivation cannot be
+    resolved from a single packet, so each unit anchors directly on the brief
+    or on an okstra contract rule.
+
+    `headings` empty means the brief was unavailable — the grammar still
+    applies, only the heading-existence half degrades to unverifiable.
+    """
+    section = _PROVENANCE_SECTION_RE.search(text)
+    if not section:
+        errors.append(
+            f"{pkt_name}: missing `## Requirement Provenance` section — a unit must "
+            "cite the brief line that demanded it"
+        )
+        return
+    bullets = [
+        b for b in _PROVENANCE_BULLET_RE.findall(section.group("body")) if b.strip()
+    ]
+    if not bullets:
+        errors.append(
+            f"{pkt_name}: `## Requirement Provenance` is empty — cite at least one "
+            "`brief:<heading>` or `contract:<rule>`"
+        )
+        return
+    for raw in bullets:
+        ref = parse_source(raw)
+        if ref.kind not in ("brief", "contract"):
+            errors.append(
+                f"{pkt_name}: unrecognized provenance `{raw}` — a fan-out unit's "
+                "source must be `brief:<heading>` or `contract:<rule>`"
+            )
+        elif ref.kind == "brief" and headings:
+            if normalize_heading(ref.value) not in headings:
+                errors.append(
+                    f"{pkt_name}: cites brief heading `{ref.value}` which does not "
+                    "exist in the brief. A fan-out unit becomes the brief for a whole "
+                    "downstream task — it must trace to a line the reporter wrote."
+                )
 
 
 @dataclass
@@ -54,16 +110,20 @@ def _parse_deps(raw: str) -> list[str]:
     return _UNIT_RE.findall(raw or "")
 
 
-def validate_fanout(run_dir: Path) -> ValidationResult:
+def validate_fanout(run_dir: Path, brief_path: Path | None = None) -> ValidationResult:
     run_dir = Path(run_dir)
     fo = run_dir / "fan-out"
     if not fo.is_dir():
         return ValidationResult(ok=True)
 
+    headings = brief_headings(brief_path) if brief_path is not None else set()
+
     errors: list[str] = []
     units: dict[str, list[str]] = {}
     for pkt in sorted(fo.glob("unit-*.md")):
-        fm = _frontmatter(pkt.read_text(encoding="utf-8"))
+        text = pkt.read_text(encoding="utf-8")
+        fm = _frontmatter(text)
+        _check_provenance(pkt.name, text, errors, headings)
         uid = fm.get("unit-id", "")
         if uid != pkt.stem:
             errors.append(f"{pkt.name}: unit-id {uid!r} != filename stem {pkt.stem!r}")

package/src/cli-registry.mjs

@@ -319,6 +319,17 @@ export const COMMAND_REGISTRY = [
     category: "introspection",
     summary: ["Render slim AI + self-contained HTML views of a final report"],
   },
+  {
+    name: "report-finalize",
+    module: "./commands/report/finalize.mjs",
+    export: "run",
+    category: "introspection",
+    summary: [
+      "Run the Phase 7 post-report sequence (token-usage,",
+      "render-views, spawn-followups, validate-run) in its",
+      "contractual order against one final report.",
+    ],
+  },
   {
     name: "render-final-report",
     module: "./commands/report/render-final-report.mjs",

package/src/commands/report/finalize.mjs

@@ -0,0 +1,65 @@
+import { runPythonModule } from "../../lib/python-helper.mjs";
+import { resolvePaths } from "../../lib/paths.mjs";
+
+const USAGE = `okstra report-finalize — run the Phase 7 post-report sequence
+
+Usage:
+  okstra report-finalize --project-root <dir> --run-manifest <path> \\
+    --report <final-report-<task-type>-<seq>.md> [--team-state <path>]
+
+Runs the four Phase 7 steps in their contractual order against one final-report:
+
+  1. token-usage       substitute real token/cost numbers into the data.json
+  2. render-views      write the self-contained *.html sibling (skipped when the
+                       report has no C-* clarification rows and is not a plan
+                       approval target)
+  3. spawn-followups   turn section 4 rows into task stubs
+  4. validate-run      validate the finished run artifacts
+
+Every step is idempotent, so re-running after a fixed failure is safe. The
+sequence stops at the first non-zero exit and reports which step failed.
+
+This is the same code path the Codex lead adapter runs automatically after its
+report-writer completes, so a Claude-led and a Codex-led run finalize
+identically.
+
+  --workspace-root is owned by this command.
+`;
+
+const OWNED_FLAGS = new Set(["--workspace-root"]);
+
+function isOwnedFlag(arg) {
+  if (OWNED_FLAGS.has(arg)) return true;
+  return [...OWNED_FLAGS].some((flag) => arg.startsWith(`${flag}=`));
+}
+
+export function buildReportFinalizeArgs(args, paths) {
+  return ["--workspace-root", paths.workspace, ...args];
+}
+
+export async function run(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  if (args.length === 0) {
+    process.stdout.write(USAGE);
+    return 2;
+  }
+
+  const forbidden = args.find(isOwnedFlag);
+  if (forbidden) {
+    process.stderr.write(
+      `error: ${forbidden} is set by 'okstra report-finalize' itself — remove it from your args\n`,
+    );
+    return 2;
+  }
+
+  const paths = await resolvePaths();
+  const result = await runPythonModule({
+    module: "okstra_ctl.report_finalize",
+    args: buildReportFinalizeArgs(args, paths),
+    stdio: "inherit-stdout",
+  });
+  return result.code;
+}