okstra 0.206.0 → 0.207.0

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}

@@ -12,7 +12,7 @@
 1. Read the frozen technical input linked in the analysis packet. Preserve the source hash, candidate IDs and fact identities. `resolve_technical_verification_input` enforces same-task source ownership, schema validity, eligible technical facts and unresolved user-decision gates.
 2. Before executing a probe, write its plan under `experiments/<seq>/<worker-id>/`: hypothesis, procedure, commands, confirming and rejecting signals, environment, and inconclusive criteria. Retain the plan with the evidence.
 3. Create a separate source copy in that directory. Record the source commit and any uncommitted input differences. Read the project and task worktree as inputs; perform source edits, installations and builds only in your own copy. Do not share writable dependency directories or use real credentials. Use synthetic local accounts for request-boundary experiments.
-4. Preserve the baseline lockfile. When the hypothesis needs a deliberate dependency change, retain the resulting lockfile and diff, then use a frozen install against that experimental lockfile. Record command, working directory, stdout/stderr and exit code in run-local logs. Distinguish infrastructure failure from a falsified compatibility claim.
+4. Phase 7 removes every `node_modules` and `.next` directory under the run directory, so evidence must not live inside them. Preserve the baseline lockfile. When the hypothesis needs a deliberate dependency change, retain the resulting lockfile and diff, then use a frozen install against that experimental lockfile. Record command, working directory, stdout/stderr and exit code in run-local logs. Distinguish infrastructure failure from a falsified compatibility claim.
 5. Classify each fact as `supported`, `refuted`, `inconclusive` or `not-run` using the declared signals. A zero exit code alone does not establish compatibility. Record limitations and all failed or unavailable probes.
 6. During convergence, inspect plans and logs; rerun disputed probes in a separate copy when feasible. An independent report is not a substitute for command evidence.
 
@@ -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