okstra 0.205.1 → 0.206.1

package/runtime/{prompts/profiles/requirements-discovery.md → python/okstra_ctl/phases/requirements_discovery/profile.md}

@@ -24,7 +24,6 @@
   - state the reporter's rejection criteria, missing routing inputs, and the evidence boundary behind each recommendation
 - Primary focus areas:
   - classify the work as bugfix, feature, improvement, refactor, or ops
-  - determine whether `error-analysis` or `implementation-option-selection` is the next safe step. Direct `implementation-planning` or `implementation` handoff is never a valid routing target — implementation requires direction selection followed by an approved `implementation-planning` report
   - capture the reporter's **rejection criteria** — the delivered outcome that would make this work wrong or unacceptable — as a routing input. Consume it from the brief's `Desired Outcome` / `Out of Scope` / `Source Material` when present; when it is absent AND it would change the classification (e.g. bugfix vs feature) or the next-phase choice, raise it as one `decision` clarification row with `Evidence checked: none — reporter intent`. Never infer it — this is a reporter-intent signal, the mirror of improvement-discovery's `Anti-goals`
   - record the rejection criteria in `requirementsDiscovery.rejectionCriteria` with the
     `source` that produced it. When it was absent and would not have changed the
@@ -41,11 +40,11 @@
   - A single-item / single-domain request is not fanned out (preserving the current single-routing behaviour).
   - When a request spans two or more domains, or has two or more independently-startable work items,
     publish each item as a `runs/requirements-discovery/fan-out/unit-<NNN>.md` packet.
-    The packet follows the `templates/reports/fan-out-unit.template.md` format, and its frontmatter
+    The packet follows the `scripts/okstra_ctl/phases/requirements_discovery/report_assets/fan-out-unit.template.md` format, and its frontmatter
     `domain`(work-category 5-enum: bugfix / feature / refactor / ops / improvement),
     `depends-on`(an inline list of unit-ids within the same fan-out `[unit-001]`, or `[]` if none),
     `recommended-next-phase`(error-analysis | implementation-option-selection) are filled in.
-    Each packet MUST carry a non-empty `## Requirement Provenance` section whose every bullet is `brief:EB-001` / `brief:PB-001` / `brief:EO-001` — an end-state id the brief declares — or `contract:<rule>`. When the brief pins ids, citing a heading is rejected: every brief carries the same generic headings, so a heading cannot say WHICH reporter line demanded this unit, and a fan-out unit becomes the brief for a whole downstream task. Only a brief authored before the end-state sections existed still takes the older `brief:<heading>` form, and there the heading must literally exist in it. `derived:` is not admissible in a packet — cross-packet derivation cannot be resolved from a single packet, so each unit anchors directly on the brief. A unit you cannot source that way is not a work item: raise it as a clarification row instead of publishing a packet for it. **Enforced:** `validators/validate_fanout.py` `_check_provenance`.
+    Each packet MUST carry a non-empty `## Requirement Provenance` section whose every bullet is `brief:EB-001` / `brief:PB-001` / `brief:EO-001` — an end-state id the brief declares — or `contract:<rule>`. When the brief pins ids, citing a heading is rejected: every brief carries the same generic headings, so a heading cannot say WHICH reporter line demanded this unit, and a fan-out unit becomes the brief for a whole downstream task. Only a brief authored before the end-state sections existed still takes the older `brief:<heading>` form, and there the heading must literally exist in it. `derived:` is not admissible in a packet — cross-packet derivation cannot be resolved from a single packet, so each unit anchors directly on the brief. A unit you cannot source that way is not a work item: raise it as a clarification row instead of publishing a packet for it. **Enforced:** `scripts/okstra_ctl/phases/requirements_discovery/validation.py` `_check_provenance`.
   - in `runs/requirements-discovery/fan-out/index.md`, list the packets in depends-on topological order
     as a numbered list (`1. unit-001`) (a generated view; explicitly do not hand-edit). The depends-on graph
     must be a DAG — `validate_fanout` rejects a cycle as a validation failure, so if a cycle appears,

package/runtime/python/okstra_ctl/{report_html/view_models/requirements_discovery.py → phases/requirements_discovery/report.py}

@@ -1,9 +1,9 @@
 """Human-first requirements-discovery view model."""
 from __future__ import annotations
 
-from ..common import evidence_index
-from ..models import HumanReportView, VisualEdge, VisualNode
-from ..visualizations import decision_flow_figure
+from okstra_ctl.report_html.common import evidence_index
+from okstra_ctl.report_html.models import HumanReportView, VisualEdge, VisualNode
+from okstra_ctl.report_html.visualizations import decision_flow_figure
 
 # Record fields this template anchors as `id-<row id>` (see
 # `HumanReportView.anchored_fields`); ids elsewhere land in the ledger.

package/{docs/task-process/requirements-discovery.md → runtime/python/okstra_ctl/phases/requirements_discovery/spec.md}

@@ -1,5 +1,16 @@
 # requirements-discovery process
 
+## Guarantees
+
+| ID | Guarantee | Enforcement |
+|---|---|---|
+| RD-1 | Optional fan-out absence is accepted | `scripts/okstra_ctl/phases/requirements_discovery/validation.py::validate_fanout` |
+| RD-2 | Each packet cites an admissible brief or contract source | `scripts/okstra_ctl/phases/requirements_discovery/validation.py::_check_provenance` |
+| RD-3 | Dependency cycles and unknown units are rejected | `scripts/okstra_ctl/phases/requirements_discovery/fanout.py::topological_order` |
+| RD-4 | The index lists every packet in dependency order | `scripts/okstra_ctl/phases/requirements_discovery/validation.py::validate_fanout` |
+| RD-5 | Packet destinations use the common routing contract | `scripts/okstra_ctl/report_routing.py::fanout_routing_errors` |
+| RD-6 | Human intent and terminology are resolved from inspected evidence | unenforced — worker instructions and lead review; no generic validator proves intent semantics |
+
 ## Index
 
 - [1. Purpose](#1-purpose)
@@ -105,9 +116,17 @@ Non-goals are source edit, plan authoring, build, and deployment.
 
 ## 6. Code reviewed
 
-- [`skills/okstra-run/SKILL.md`](../../skills/okstra-run/SKILL.md)
-- [`scripts/okstra_ctl/wizard/`](../../scripts/okstra_ctl/wizard/)
-- [`scripts/okstra_ctl/run.py`](../../scripts/okstra_ctl/run.py)
-- [`scripts/okstra_ctl/workflow.py`](../../scripts/okstra_ctl/workflow.py)
-- [`prompts/profiles/requirements-discovery.md`](../../prompts/profiles/requirements-discovery.md)
-- [`prompts/lead/okstra-lead-contract.md`](../../prompts/lead/okstra-lead-contract.md)
+- [`skills/okstra-run/SKILL.md`](../../../../skills/okstra-run/SKILL.md)
+- [`scripts/okstra_ctl/wizard/`](../../wizard)
+- [`scripts/okstra_ctl/run.py`](../../run.py)
+- [`scripts/okstra_ctl/workflow.py`](../../workflow.py)
+- [`scripts/okstra_ctl/phases/requirements_discovery/profile.md`](profile.md)
+- [`prompts/lead/okstra-lead-contract.md`](../../../../prompts/lead/okstra-lead-contract.md)
+
+## Phase ownership and validation
+
+`profile.md` owns request discovery and decomposition instructions; `profile.json` owns roles. `validation.py` owns fan-out packet identity, work category, requirement provenance, dependency and index checks. `fanout.py` orders dependencies and rejects cycles and unknown units. `report.py` and `report_assets/` own the report body and fan-out packet template.
+
+Common scope-provenance helpers continue to define brief end-state identifiers and citation grammar. Shared schemas remain in `schemas/final-report-v2.0.schema.json` and `schemas/final-report-v3.0.schema.json` under `requirementsDiscovery`. The common lead's `prompts/lead/phase-routing.md` owns destination selection; `report_routing.py` checks packet destinations.
+
+`tests/test_fanout.py` checks real packet files, missing and invalid provenance, dependency cycles, missing dependencies and index order. The common validator calls `validate_requirements_discovery_fanout` only for this task type, preserving the optional fan-out behavior and the `requirements-discovery:` error prefix. Source inspection and human-intent decisions remain worker instructions rather than machine-enforced semantic claims.

package/runtime/{validators/validate_fanout.py → python/okstra_ctl/phases/requirements_discovery/validation.py}

@@ -6,25 +6,19 @@ and a `fan-out/` directory exists under the run dir.
 from __future__ import annotations
 
 import re
-import sys
 from dataclasses import dataclass, field
 from pathlib import Path
 
-_VALIDATORS_DIR = Path(__file__).resolve().parent
-for _ssot_dir in (_VALIDATORS_DIR.parent / "scripts", _VALIDATORS_DIR.parent / "python"):
-    if _ssot_dir.is_dir() and str(_ssot_dir) not in sys.path:
-        sys.path.insert(0, str(_ssot_dir))
-
-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
+from okstra_ctl.report_routing import fanout_routing_errors
+from okstra_ctl.work_categories import WORK_CATEGORIES
+from .fanout import topological_order, CycleError
+from okstra_ctl.scope_provenance import (
     brief_citation_problem,
     brief_end_state_ids,
     brief_headings,
     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)
@@ -138,8 +132,7 @@ def validate_fanout(run_dir: Path, brief_path: Path | None = None) -> Validation
             errors.append(f"{pkt.name}: unit-id {uid!r} != filename stem {pkt.stem!r}")
         if fm.get("domain") not in WORK_CATEGORIES:
             errors.append(f"{pkt.name}: domain {fm.get('domain')!r} not in {WORK_CATEGORIES}")
-        if fm.get("recommended-next-phase") not in _NEXT_PHASES:
-            errors.append(f"{pkt.name}: recommended-next-phase not in {_NEXT_PHASES}")
+        errors.extend(fanout_routing_errors(pkt.name, fm.get("recommended-next-phase")))
         units[pkt.stem] = _parse_deps(fm.get("depends-on", ""))
 
     if not units:
@@ -167,3 +160,9 @@ def validate_fanout(run_dir: Path, brief_path: Path | None = None) -> Validation
             errors.append(f"index.md order {listed} is not the topological order {order}")
 
     return ValidationResult(ok=not errors, errors=errors)
+
+
+def validate_requirements_discovery_fanout(run_dir, failures, brief_path=None) -> None:
+    """단계 산출물 오류를 공통 실행 검증의 오류 목록에 같은 접두로 전달한다."""
+    result = validate_fanout(Path(run_dir), brief_path)
+    failures.extend(f"requirements-discovery: {error}" for error in result.errors)

package/runtime/python/okstra_ctl/phases/technical_verification/__init__.py

@@ -0,0 +1 @@
+"""기술 검증 단계의 입력과 관측 증거 정책."""

package/runtime/python/okstra_ctl/phases/technical_verification/boundary.json

@@ -0,0 +1,9 @@
+{
+  "allowed": "  - falsifiable experiment plans for the frozen unresolved facts\n  - dependency installation, source experiments, tests and builds only in this run's experiment copies\n  - command logs, observed signals and per-fact supported/refuted/inconclusive/not-run results\n  - return to implementation-option-selection with evidence, without adoption or plan approval",
+  "forbidden": [
+    "source edits or installs in the project checkout, task worktree, or another worker's experiment copy",
+    "production credentials, remote writes, deployments, migrations, publishing, commits or merging experiments into product branches",
+    "marking candidates feasible, selecting a direction, approving a plan, or declaring task acceptance",
+    "starting another lifecycle phase inside this run; return the evidence to implementation-option-selection"
+  ]
+}

package/runtime/python/okstra_ctl/phases/technical_verification/entry.py

@@ -0,0 +1,100 @@
+"""미확정 사실의 시험 입력과 관측 결과를 연결하며 도입 승인은 만들지 않는다."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from pathlib import Path
+from typing import TypedDict
+
+from okstra_ctl.final_report_schema import load_schema_for_data, validate
+from okstra_ctl.implementation_direction import validate_task_artifact_path
+from okstra_ctl.json_boundary import load_owned_object_snapshot, serialize_owned_object
+from okstra_ctl.technical_verification_facts import (
+    TechnicalVerificationError,
+    VerificationFact,
+    technical_verification_facts,
+)
+
+
+class VerificationInput(TypedDict):
+    sourceReport: str
+    sourceDataSha256: str
+    scope: str
+    facts: list[VerificationFact]
+
+
+def resolve_technical_verification_input(
+    report: Path, project_root: Path, task_root: Path, task_key: str
+) -> VerificationInput:
+    """같은 작업의 후보 비교 기록을 시험 입력으로 고정한다."""
+    report = report if report.is_absolute() else project_root / report
+    validate_task_artifact_path(report, task_root, "technical verification source")
+    expected_parent = task_root / "runs/implementation-option-selection/reports"
+    if report.parent != expected_parent or not re.fullmatch(
+        r"final-report-implementation-option-selection-\d{3,}\.data\.json", report.name
+    ):
+        raise TechnicalVerificationError(
+            "source must be this task's option-selection record"
+        )
+    snapshot = load_owned_object_snapshot(
+        report, artifact="technical verification source"
+    )
+    data = snapshot.value
+    errors = validate(data, load_schema_for_data(data))
+    if errors:
+        raise TechnicalVerificationError("invalid source report: " + "; ".join(errors))
+    if data["header"]["taskKey"] != task_key:
+        raise TechnicalVerificationError(
+            "source taskKey does not match verification task"
+        )
+    return {
+        "sourceReport": report.relative_to(project_root).as_posix(),
+        "sourceDataSha256": hashlib.sha256(snapshot.raw_bytes).hexdigest(),
+        "scope": "technical-evidence-only",
+        "facts": technical_verification_facts(data),
+    }
+
+
+def write_technical_verification_input(
+    payload: VerificationInput, run_root: Path, seq: str
+) -> Path:
+    """실행 순번별 입력을 저장해 후속 실행이 이전 시험 범위를 덮지 않게 한다."""
+    path = run_root / "state" / f"technical-verification-input-{seq}.json"
+    serialized = serialize_owned_object(path, payload, artifact="technical verification input")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("x", encoding="utf-8") as output:
+        output.write(serialized)
+    return path
+
+
+def prepare_technical_verification_input(
+    source_path: str, project_root: Path, task_root: Path, task_key: str
+) -> VerificationInput:
+    """공통 준비가 부수효과를 시작하기 전에 필수 입력과 오류 형식을 고정한다."""
+    from okstra_ctl.prepare_error import PrepareError
+
+    if not source_path:
+        raise PrepareError("technical-verification requires --clarification-response pointing to this task's option-selection record")
+    try:
+        return resolve_technical_verification_input(
+            Path(source_path), project_root, task_root, task_key,
+        )
+    except ValueError as exc:
+        raise PrepareError(str(exc)) from exc
+
+
+def materialize_technical_input_packet(payload_json: str, run_root: Path, seq: str) -> str:
+    """입력 저장과 패킷 안내를 함께 구성해 실행 순번별 증거 위치를 보존한다."""
+    import json
+
+    verification_path = write_technical_verification_input(
+        json.loads(payload_json), run_root, seq,
+    )
+    return (
+        "\n## Technical Verification Input\n\n"
+        f"- Frozen input: `{verification_path}`\n"
+        f"- Experiment copies only: `{run_root}/experiments/{seq}/<worker-id>/`\n"
+        "- Read the input before planning experiments; copy each fact identity verbatim into results.\n"
+        + "\n```json\n" + payload_json + "\n```\n"
+    )

package/runtime/{prompts/profiles/technical-verification.md → python/okstra_ctl/phases/technical_verification/profile.md}

@@ -22,7 +22,7 @@ Copy boundaries and pre-execution plans are worker instructions reviewed during
 
 Copy `sourceReport`, `sourceDataSha256` and `scope` from the frozen input into `technicalVerification`. Emit exactly one check per fact, preserving its `id`, `candidateId`, `factIndex` and `fact`. Each check records its hypothesis, procedure, signals, command evidence, observation, status and limitations. Use project-relative evidence paths. Mark contested results inconclusive.
 
-Route only to `implementation-option-selection`, with one matching phase-continuation follow-up. The next comparison consumes this report through `--clarification-response` and authors fresh feasibility votes. Do not edit the source comparison, clear unrelated uncertainties, rank candidates, approve implementation, merge code or expand the user's pilot scope.
+Do not edit the source comparison, clear unrelated uncertainties, rank candidates, approve implementation, merge code or expand the user's pilot scope.
 
 `validate_technical_verification_report` checks frozen-input identity and evidence before publication and during run validation. The report schema restricts the routing target and requires `frontmatter.approved=false`.
 {{INCLUDE:_coverage-critic.md}}

package/runtime/python/okstra_ctl/{report_html/view_models/technical_verification.py → phases/technical_verification/report.py}

@@ -2,8 +2,8 @@
 
 from __future__ import annotations
 
-from ..common import evidence_index
-from ..models import HumanReportView
+from okstra_ctl.report_html.common import evidence_index
+from okstra_ctl.report_html.models import HumanReportView
 
 
 def build_technical_verification_view(data: dict) -> HumanReportView:

package/runtime/python/okstra_ctl/phases/technical_verification/spec.md

@@ -0,0 +1,37 @@
+# Technical verification phase
+
+## Purpose and boundaries
+
+This phase collects experimental evidence for unresolved technical facts. It does not rank candidates, select a direction, approve implementation or modify the source comparison. The lead chooses the continuation using `prompts/lead/phase-routing.md`.
+
+## Input and preparation
+
+The existing `--clarification-response` argument identifies this task's option-selection data record. `entry.prepare_technical_verification_input` checks the required argument before run creation. `entry.resolve_technical_verification_input` checks ownership, the canonical record name, schema and task key, then freezes the source-byte SHA-256 and eligible fact identities. Shared `technical_verification_facts.py` retains candidate safety and unresolved user-decision rules for both producer and consumer phases.
+
+`entry.materialize_technical_input_packet` writes `state/technical-verification-input-<seq>.json` without replacing an existing snapshot and appends the input and experiment directory to the existing analysis packet. Artifact names, CLI inputs and preparation order are unchanged.
+
+## Execution and output
+
+`profile.md` owns experiment preparation, isolated source copies, command evidence, convergence and fact classification. `profile.json` owns role requirements. Worker write boundaries remain in the common invocation write contract.
+
+The report's `technicalVerification` block preserves `sourceReport`, `sourceDataSha256`, `scope` and each fact's identity. Checks record hypothesis, procedure, confirming and rejecting signals, observations, limitations and commands. Status values are `supported`, `refuted`, `inconclusive` and `not-run`.
+
+Report schemas remain common: `schemas/final-report-v2.0.schema.json` and `schemas/final-report-v3.0.schema.json`, including the `technicalVerification` definition and approval/continuation constraints. `report.py` and `report_assets/` own the phase body; the common report engine owns publication and page layout.
+
+## Validation and failure behavior
+
+`validation.validate_technical_verification_report` checks frozen-input metadata, exactly one check per input fact, unchanged fact identity and execution evidence. Observed checks need commands; supported checks cannot cite a nonzero exit code. Log and working-directory evidence stays inside the matching run's experiment sequence and rejects symlink escapes. `not-run` may omit commands.
+
+Both `report_assembly.py` and `validators/validate-run.py` call this validation and the common `report_routing.technical_verification_routing_errors` check. Publication rejects invalid evidence before replacing the report. These checks do not prove that a declared command produced a log or sandbox arbitrary shell commands. Copy isolation and pre-execution plan quality remain worker instructions reviewed during convergence.
+
+## Tests
+
+`tests/test_technical_verification.py` covers input ownership, unsafe/unclassified sources, source preservation, exclusive snapshot creation, fact completeness, failed or missing commands, logs, sequence and symlink boundaries, full preparation and schema-v2/v3 report rendering. `tests/report/test_report_assembly.py::test_technical_assembly_requires_evidence_before_replacing_record` checks publication preserves an existing record when evidence fails.
+
+## Guarantees
+
+| ID | Guarantee | Enforcement |
+|---|---|---|
+| TV-1 | Report checks preserve the frozen input metadata and cover every input fact exactly once. | `scripts/okstra_ctl/phases/technical_verification/validation.py::validate_technical_verification_report` |
+| TV-2 | Observed results require execution evidence within the matching experiment sequence. | `scripts/okstra_ctl/phases/technical_verification/validation.py::_check_execution_evidence` |
+| TV-3 | The continuation targets implementation option selection. | `scripts/okstra_ctl/report_routing.py::technical_verification_routing_errors` |

package/runtime/python/okstra_ctl/phases/technical_verification/validation.py

@@ -0,0 +1,90 @@
+"""관측 판정과 실행별 시험 증거의 일치 검사."""
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from okstra_ctl.implementation_direction import validate_task_artifact_path
+from okstra_ctl.json_boundary import load_owned_object_snapshot
+from okstra_ctl.technical_verification_facts import TechnicalVerificationError
+
+
+def _check_execution_evidence(
+    check: Mapping[str, Any], project_root: Path, run_root: Path, seq: str
+) -> list[str]:
+    """관측 판정은 실행 기록과 실행별 시험 디렉터리를 요구한다."""
+    errors = []
+    commands = check.get("commands") or []
+    if check.get("status") != "not-run" and not commands:
+        errors.append(f"{check['id']}: an observed result requires command evidence")
+    for command in commands:
+        try:
+            log = project_root / command["logPath"]
+            experiment_root = run_root / "experiments" / seq
+            validate_task_artifact_path(log, experiment_root, "verification log")
+            if not log.read_text(encoding="utf-8").strip():
+                errors.append(f"{check['id']}: verification log is empty")
+            cwd = project_root / command["cwd"]
+            cwd.resolve(strict=True).relative_to(experiment_root.resolve(strict=True))
+            relative = cwd.relative_to(experiment_root)
+            current = run_root
+            for part in ("experiments", seq, *relative.parts):
+                current = current / part
+                if current.is_symlink():
+                    raise TechnicalVerificationError(
+                        "experiment cwd contains a symlink"
+                    )
+            if not cwd.is_dir() or cwd.is_symlink():
+                errors.append(f"{check['id']}: experiment cwd must be a directory")
+        except (OSError, ValueError) as exc:
+            errors.append(f"{check['id']}: invalid execution evidence: {exc}")
+        if check.get("status") == "supported" and command.get("exitCode") != 0:
+            errors.append(f"{check['id']}: a supported result has a failed command")
+    return errors
+
+
+def validate_technical_verification_report(
+    data: Mapping[str, Any], report_path: Path, project_root: Path
+) -> list[str]:
+    """발행·최종 검증에서 같은 사실 집합과 실제 시험 산출물을 대조한다."""
+    if (data.get("header") or {}).get("taskType") != "technical-verification":
+        return []
+    match = re.fullmatch(
+        r"final-report-technical-verification-(\d{3,})\.data\.json", report_path.name
+    )
+    if match is None:
+        return ["technical verification report must use its canonical record path"]
+    run_root = report_path.parent.parent
+    path = run_root / "state" / f"technical-verification-input-{match[1]}.json"
+    try:
+        validate_task_artifact_path(path, run_root, "technical verification input")
+        source = load_owned_object_snapshot(
+            path, artifact="technical verification input"
+        ).value
+    except (OSError, ValueError) as exc:
+        return [str(exc)]
+    block = data.get("technicalVerification") or {}
+    errors = []
+    for key in ("sourceReport", "sourceDataSha256", "scope"):
+        if block.get(key) != source.get(key):
+            errors.append(f"technicalVerification.{key} must match the run input")
+    expected = {fact["id"]: fact for fact in source["facts"]}
+    checks = block.get("checks") or []
+    ids = [check.get("id") for check in checks]
+    if len(ids) != len(set(ids)) or set(ids) != set(expected):
+        errors.append(
+            "technicalVerification.checks must cover each input fact exactly once"
+        )
+    for check in checks:
+        fact = expected.get(check.get("id"))
+        if fact is None:
+            continue
+        for key in ("candidateId", "factIndex", "fact"):
+            if check.get(key) != fact[key]:
+                errors.append(f"{check['id']}: {key} must preserve the input fact")
+        errors.extend(
+            _check_execution_evidence(check, project_root, run_root, match[1])
+        )
+    return errors

package/runtime/python/okstra_ctl/plan_approval.py

@@ -0,0 +1,70 @@
+"""계획 승인 상태를 보고서와 사용자 응답에 동일하게 제공한다."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Mapping, Any
+
+
+@dataclass(frozen=True)
+class PlanApprovalState:
+    option_names: tuple[str, ...]
+    recommended_option: str
+    disabled_reason: str
+    blocker_ids: tuple[str, ...]
+    show_option_selector: bool = True
+    reentry_command: str = ""
+
+
+def resolve_recommended_option(rec_name: str, names: tuple[str, ...]) -> str:
+    if rec_name in names:
+        return rec_name
+    matches = [
+        name
+        for name in names
+        if rec_name and (name.startswith(rec_name) or rec_name.startswith(name))
+    ]
+    return matches[0] if len(matches) == 1 else names[0]
+
+
+def plan_approval_state(data: dict) -> PlanApprovalState | None:
+    planning = data.get("implementationPlanning")
+    if not isinstance(planning, dict):
+        return None
+    blockers = tuple(
+        row["id"]
+        for row in data.get("clarificationItems", [])
+        if row.get("blocks") == "approval" and row.get("status") in {"open", "answered"}
+    )
+    reason = f"{len(blockers)} approval blocker(s) unresolved" if blockers else ""
+    if planning.get("planningContract") == "selected-direction":
+        if planning.get("outcome") == "direction-invalidated" and not reason:
+            reason = "selected direction invalidated"
+        task_key = (data.get("header") or {}).get("taskKey", "")
+        reentry_command = (
+            f"/okstra-run task-key={task_key} task-type=implementation-option-selection"
+            if planning.get("outcome") == "direction-invalidated" and task_key
+            else ""
+        )
+        return PlanApprovalState((), "", reason, blockers, False, reentry_command)
+    names = tuple(
+        row["name"]
+        for row in planning.get("optionCandidates", [])
+        if isinstance(row, dict) and row.get("name")
+    )
+    if not names:
+        return None
+    recommended = planning.get("recommendedOption", {}).get("name", "")
+    return PlanApprovalState(
+        names,
+        resolve_recommended_option(recommended, names),
+        reason,
+        blockers,
+    )
+
+
+def plan_is_approved(report_data: Mapping[str, Any] | None) -> bool:
+    if not isinstance(report_data, Mapping):
+        return False
+    frontmatter = report_data.get("frontmatter")
+    return isinstance(frontmatter, Mapping) and frontmatter.get("approved") is True