okstra 0.206.0 → 0.207.0

package/runtime/python/okstra_ctl/process_group.py

@@ -0,0 +1,118 @@
+"""CLI 워커 프로세스 그룹의 메모리 상한과 종료 뒤 잔여 프로세스 정리.
+
+워커가 실행한 빌드는 워커와 같은 프로세스 그룹에 들어간다(`worker_runner` 가
+`start_new_session=True` 로 띄운다). fontsninja-v3-site 에서 Turbopack PostCSS 워커가
+57GB, `next build` 가 78GB 까지 커져 커널 패닉(watchdog timeout)이 났고, 본 프로세스가
+죽은 뒤에도 PostCSS 워커가 남아 계속 커졌다(2026-09-27).
+"""
+from __future__ import annotations
+
+import os
+import signal
+import subprocess
+from pathlib import Path
+
+from okstra_project.dirs import okstra_home, project_json_path
+
+from .json_boundary import JsonBoundaryError, load_owned_object
+
+CONFIG_KEY = "workerMemoryCapMb"
+# 이 프로젝트의 정상 `next build` 는 5.4–5.6GB 였다. 상한은 그보다 넉넉하되, 물리
+# 메모리가 작은 기기에서는 절반을 넘지 않게 한다.
+_DEFAULT_CEILING_BYTES = 8 * 1024 ** 3
+
+
+class MemoryCapConfigError(ValueError):
+    pass
+
+
+def physical_memory_bytes() -> int:
+    return os.sysconf("SC_PAGE_SIZE") * os.sysconf("SC_PHYS_PAGES")
+
+
+def memory_cap_bytes(project_root: Path, global_config_path: Path | None = None) -> int:
+    """워커 그룹 RSS 합계 상한. 0 은 감시하지 않음.
+
+    프로젝트 `.okstra/project.json` → `~/.okstra/config.json` → 기본값 순서다.
+    """
+    for label, path in (
+        ("project", project_json_path(project_root)),
+        ("global", global_config_path or okstra_home() / "config.json"),
+    ):
+        value = _configured_cap_mb(label, path)
+        if value is not None:
+            return value * 1024 ** 2
+    return min(_DEFAULT_CEILING_BYTES, physical_memory_bytes() // 2)
+
+
+def _configured_cap_mb(label: str, path: Path) -> int | None:
+    if not path.is_file():
+        return None
+    try:
+        payload = load_owned_object(path, artifact=f"{label} configuration")
+    except JsonBoundaryError as exc:
+        raise MemoryCapConfigError(f"{label} config is unreadable: {path}") from exc
+    value = payload.get(CONFIG_KEY) if isinstance(payload, dict) else None
+    if value is None:
+        return None
+    if isinstance(value, bool) or not isinstance(value, int) or value < 0:
+        raise MemoryCapConfigError(
+            f"{CONFIG_KEY} must be a non-negative integer (MB), got {value!r}: {path}")
+    return value
+
+
+def group_rss_bytes(pgid: int) -> int:
+    """프로세스 그룹 `pgid` 에 속한 프로세스들의 RSS 합계."""
+    try:
+        output = subprocess.run(
+            ["ps", "-A", "-o", "pgid=,rss="],
+            capture_output=True, text=True, check=True,
+        ).stdout
+    except (OSError, subprocess.CalledProcessError):
+        return 0
+    total_kb = 0
+    for row in output.splitlines():
+        fields = row.split()
+        if len(fields) == 2 and fields[0] == str(pgid) and fields[1].isdigit():
+            total_kb += int(fields[1])
+    return total_kb * 1024
+
+
+def kill_group(pgid: int) -> bool:
+    """그룹에 남은 프로세스를 SIGKILL 한다. 보낼 대상이 있었으면 True."""
+    try:
+        os.killpg(pgid, signal.SIGKILL)
+    except ProcessLookupError:
+        return False
+    return True
+
+
+class MemoryWatch:
+    """주기적으로 그룹 RSS 를 재고, 상한을 넘으면 그룹을 죽인다."""
+
+    interval_seconds = 2.0
+
+    def __init__(self, cap_bytes: int) -> None:
+        self.cap_bytes = cap_bytes
+        self.exceeded_bytes = 0
+        self._next_sample = 0.0
+
+    def check(self, pgid: int, now: float) -> bool:
+        """상한을 넘어 그룹을 죽였으면 True."""
+        if not self.cap_bytes or self.exceeded_bytes or now < self._next_sample:
+            return False
+        self._next_sample = now + self.interval_seconds
+        rss = group_rss_bytes(pgid)
+        if rss <= self.cap_bytes:
+            return False
+        self.exceeded_bytes = rss
+        kill_group(pgid)
+        return True
+
+    def failure(self) -> str:
+        mb = 1024 ** 2
+        return (
+            f"memory-cap exceeded: worker process group used {self.exceeded_bytes // mb} MB, "
+            f"cap {self.cap_bytes // mb} MB ({CONFIG_KEY} in .okstra/project.json "
+            "or ~/.okstra/config.json)"
+        )

package/runtime/python/okstra_ctl/profile_show.py

@@ -19,7 +19,7 @@ import sys
 from pathlib import Path
 
 from .paths import find_asset_root
-from .phases.catalog import PhaseAssetError, UnknownTaskType, profile_markdown
+from .phases.catalog import PhaseAssetError, UnknownTaskType, profile_markdown, profile_sidecar
 from .role_requirements import RoleProfileError, load_role_profile
 from .run import PrepareError, _expand_profile_includes
 
@@ -29,7 +29,7 @@ _PROFILES_REL = ("prompts", "profiles")
 # `prompts/profiles/_implementation-executor.md`. Reading the list from the
 # profile body rather than hard-coding it here is deliberate: a list in code
 # goes stale the moment a profile adds a sidecar, and does so silently.
-_SIDECAR_RE = re.compile(r"`(prompts/profiles/_[\w-]+\.md)`")
+_SIDECAR_RE = re.compile(r"`((?:prompts/profiles|scripts/okstra_ctl/phases/implementation/instructions)/_[\w-]+\.md)`")
 
 
 def workspace_root(start: Path | None = None) -> Path:
@@ -77,7 +77,7 @@ def sidecar_bodies(root: Path, profile_text: str) -> list[str]:
         if relative in seen:
             continue
         seen.add(relative)
-        path = root / relative
+        path = profile_sidecar(root, relative)
         if not path.is_file():
             continue
         body = _expand_profile_includes(path)

package/runtime/python/okstra_ctl/render.py

@@ -17,6 +17,8 @@ session id 등) 를 덧붙여 전달한다.
 
 from __future__ import annotations
 
+from .phases.catalog import profile_sidecar
+
 import hashlib
 import json
 import re
@@ -2632,7 +2634,7 @@ def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
         home_prompts / "lead" / "convergence.md"
     )
     plan_body_verification_path = ctx.get("OKSTRA_PLAN_BODY_VERIFICATION_PATH") or str(
-        home_prompts / "lead" / "plan-body-verification.md"
+        profile_sidecar(home_prompts.parent, "prompts/lead/plan-body-verification.md")
     )
     report_writer_path = ctx.get("OKSTRA_REPORT_WRITER_PATH") or str(
         home_prompts / "lead" / "report-writer.md"
@@ -2785,8 +2787,12 @@ def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
             "`shutdown_workers`, `record_lead_event`, and `collect_usage` only "
             "through its mapping.\n"
             "- Do not call a primitive documented by an unselected adapter.\n"
-            "- Record the adapter-required Phase 3 state and emit the canonical "
-            "`PROGRESS: phase-3-team-create ...` checkpoint before dispatch.\n"
+            "- Record the adapter-required Phase 3 state. When team-state has "
+            "no `teamCreate` yet, do not append `phase-3-team-create`: the "
+            "first `team dispatch` (cmux-pane run) or `worker-dispatch` writes "
+            "the implicit-team marker, records the checkpoint and prints the "
+            "line to emit. Otherwise append `PROGRESS: phase-3-team-create ...` "
+            "before dispatch.\n"
             f"{adapter_setup_block}\n"
             "- The run manifest is authoritative for concurrent-run metadata, "
             "dispatch backend, and artifact paths."
@@ -2971,7 +2977,12 @@ def render_template_with_ctx(template_path: str, output_path: str, ctx: dict) ->
     Optional defaults (VALIDATION_STATUS etc.) should be filled by calling
     `apply_lead_prompt_defaults(ctx)` in the same setup step.
     """
-    template = Path(template_path).read_text(encoding="utf-8")
+    from .phases.catalog import migrated_report_template
+
+    source = Path(template_path)
+    if source.parent.name == "reports" and source.parent.parent.name == "templates":
+        source = migrated_report_template(source.parent.parent.parent, source.name) or source
+    template = source.read_text(encoding="utf-8")
 
     fm_ctx = dict(ctx)
     fm_ctx.setdefault("DOC_TYPE", _doc_type_from_template_path(template_path))

package/runtime/python/okstra_ctl/report_assembly.py

@@ -2,9 +2,10 @@
 from __future__ import annotations
 
 import copy
-import json
 import os
 import tempfile
+from okstra_ctl.phases.implementation_planning.validation import validate_selected_direction_plan
+
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Callable, Mapping, Sequence
@@ -25,22 +26,24 @@ from .report_synthesis_packet import (
 )
 from .conformance import strip_stage_declaration_label
 from .design_prep import DesignPrepError, materialize_design_prep_requests
-from .implementation_options import validate_blocked_answer_channel
-from .technical_verification import validate_technical_verification_report
+from .phases.implementation_option_selection.validation import validate_blocked_answer_channel
+from .phases.technical_verification.validation import validate_technical_verification_report
+from .report_routing import technical_verification_routing_errors
 from .implementation_direction import (
     load_selected_direction_snapshot,
-    validate_selected_direction_plan,
 )
 from .paths import task_dir
 from .phases.final_verification.report import verification_scope
 from .report_projections import (
     ReportProjectionError,
     project_convergence,
-    project_design,
     project_execution,
     project_token_usage,
 )
-from .scope_provenance import parse_source
+from .phases.implementation_planning.report import (
+    attach_design_snapshot, _sync_human_summary_with_plan_body_gate,
+    _fill_end_state_coverage,
+)
 
 from .write_policy import planned_path_declaration_errors
 
@@ -160,12 +163,21 @@ def _clarifications(
         _clarification_row(row, activity_by_id, path)
         for row in active
     ]
-    rows.extend(_carried_clarification_rows(ledger, {row.get("id") for row in rows}, path))
+    superseded = {
+        cid
+        for row in active
+        if isinstance(row.get("resolutionInput"), Mapping)
+        for cid in row.get("supersedes") or []
+    }
+    rows.extend(_carried_clarification_rows(
+        ledger, {row.get("id") for row in rows}, path, superseded,
+    ))
     return rows
 
 
 def _carried_clarification_rows(
     ledger: Mapping[str, Any], seen_ids: set[object], path: Path,
+    superseded: set[str],
 ) -> list[dict[str, Any]]:
     """이월 결정은 active 질문이 아니다. 이번 런 활동 원장을 요구하지 않는다."""
     carried = ledger.get("carriedDecisions")
@@ -185,7 +197,13 @@ def _carried_clarification_rows(
         cid = decision.get("id")
         if cid in seen:
             continue
-        rows.append(_carried_clarification_row(decision))
+        row = _carried_clarification_row(decision)
+        if cid in superseded:
+            # 다음 run 의 seed 는 `obsolete` 행을 이월하지 않는다. `answered` 로
+            # 남기면 대체된 답과 대체한 답이 함께 이월된다.
+            row["status"] = "obsolete"
+            row.pop("resolution", None)
+        rows.append(row)
         seen.add(cid)
     return rows
 
@@ -689,15 +707,9 @@ def _attach_machine_planning(
     if design_row is None:
         return
     try:
-        design = project_design(planning, _read_json(design_row))
+        attach_design_snapshot(planning, _read_json(design_row))
     except ReportProjectionError as exc:
         _fail(design_row.owner, design_row.path, "$", exc)
-    planning["designPreparation"] = design["designPreparation"]
-    stages = {row.get("stage"): row for row in planning.get("stages") or [] if isinstance(row, dict)}
-    for coverage in design["stageCoverage"]:
-        stage = stages.get(coverage.get("stage"))
-        if stage is not None:
-            stage["designSurfaceCoverage"] = coverage.get("rows") or []
     verification_row = inputs.get("plan-body-verification")
     if verification_row is None:
         return
@@ -717,83 +729,6 @@ def _attach_machine_planning(
     _sync_human_summary_with_plan_body_gate(data, projection)
 
 
-def _sync_human_summary_with_plan_body_gate(
-    data: dict[str, Any], projection: Mapping[str, Any],
-) -> None:
-    """게이트가 통과했는데 내러티브가 unseeded 로 남으면 사람용 칸을 맞춘다.
-
-    report-writer 는 PBV 전에 쓰고, 조립이 게이트를 덮어씌운다. blockers 와
-    nextStep 이 그때의 문장을 그대로 두면 통과한 계획이 아직 검증 전으로 보인다.
-    """
-    gate = str(projection.get("gateResult") or "")
-    if gate not in {"passed", "passed-with-dissent"}:
-        return
-    summary = data.get("humanSummary")
-    if isinstance(summary, dict) and isinstance(summary.get("blockers"), list):
-        summary["blockers"] = [
-            row for row in summary["blockers"]
-            if "unseeded" not in str(row).lower()
-        ]
-    card = data.get("verdictCard")
-    if not isinstance(card, dict):
-        return
-    next_step = str(card.get("nextStep") or "")
-    lowered = next_step.lower()
-    if "unseeded" not in lowered and "seed" not in lowered:
-        return
-    next_step = (
-        "Plan-body verification passed. Do not start implementation "
-        "until `frontmatter.approved` is true."
-    )
-    card["nextStep"] = next_step
-    final = data.get("finalVerdict")
-    if isinstance(final, dict):
-        final["nextStep"] = next_step
-
-
-def _fill_end_state_coverage(data: dict[str, Any]) -> None:
-    """writer 가 못 쓴 endStateCoverage 를 requirementCoverage brief:EB-001 에서 채운다.
-
-    내러티브 스키마가 이 칸을 열어 주면 writer 가 쓸 수 있다. 비어 있으면
-    validate-run 이 brief id 마다 한 행을 요구하므로 조립이 채운다.
-    """
-    existing = data.get("endStateCoverage")
-    if isinstance(existing, list) and existing:
-        return
-    planning = data.get("implementationPlanning")
-    if not isinstance(planning, dict):
-        return
-    derived = _end_state_rows_from_requirement_coverage(planning)
-    if derived:
-        data["endStateCoverage"] = derived
-
-
-def _end_state_rows_from_requirement_coverage(
-    planning: Mapping[str, Any],
-) -> list[dict[str, Any]]:
-    rows: list[dict[str, Any]] = []
-    seen: set[str] = set()
-    for item in planning.get("requirementCoverage") or []:
-        if not isinstance(item, Mapping):
-            continue
-        ref = parse_source(str(item.get("source") or ""))
-        if not ref.is_end_state_id or ref.value in seen:
-            continue
-        seen.add(ref.value)
-        status = str(item.get("status") or "")
-        row: dict[str, Any] = {
-            "id": ref.value,
-            "disposition": "addressed" if status == "covered" else "deferred",
-            "coveredBy": str(item.get("id") or item.get("coveredBy") or ""),
-        }
-        if row["disposition"] != "addressed":
-            row["rationale"] = (
-                f"requirementCoverage `{item.get('id')}` status is `{status or 'empty'}`."
-            )
-        rows.append(row)
-    return rows
-
-
 def _schema_owner(error: str) -> str:
     field = error.split(" ", 1)[0]
     owners = {
@@ -897,6 +832,7 @@ def assemble_report(
     target = Path(value)
     target = target if target.is_absolute() else project_root / target
     verification_errors = validate_technical_verification_report(data, target, project_root)
+    verification_errors.extend(technical_verification_routing_errors(data))
     if verification_errors:
         raise ReportAssemblyError(tuple(
             AssemblyIssue("report-writer", str(target), "technicalVerification", error)

package/runtime/python/okstra_ctl/report_finalize.py

@@ -62,7 +62,10 @@ from .final_report_paths import (
     final_report_markdown_path,
     sidecar_source_rel,
 )
-from .paths import task_dir, task_manifest_file
+from .run_artifact_prune import prune_run_artifacts
+from .handoff import record_verified
+from .handoff_error import HandoffError
+from .paths import RunRef, task_dir, task_manifest_file
 from .report_view_artifacts import html_view_path
 from .release_gate import release_handoff_allowed
 from .report_translation_dispatch import TranslateOutcome, translate_report
@@ -73,6 +76,7 @@ from .stage_targets import (
     integrate_and_teardown_whole_task,
 )
 from .session import observe_lead_session
+from .lead_progress import record_checkpoint
 from .error_log_write import record_runtime_failure
 
 # 포인터 값 타입만 쓴다. `okstra_project.phase_pointer` 는 okstra 안의
@@ -91,10 +95,12 @@ STEP_TRANSLATE = "translate"
 STEP_TOKEN_USAGE = "token-usage"
 STEP_RENDER_VIEWS = "render-views"
 STEP_SPAWN_FOLLOWUPS = "spawn-followups"
+STEP_RECORD_VERIFIED = "record-verified"
 STEP_VALIDATE_RUN = "validate-run"
 STEP_RECORD_GROUP_MEMORY = "record-group-memory"
 STEP_TEARDOWN_STAGES = "teardown-stages"
 STEP_PREFLIGHT = "preflight"
+STEP_PRUNE_RUN_ARTIFACTS = "prune-run-artifacts"
 
 STEP_ORDER = (
     STEP_PROJECT_ACTIVITY,
@@ -102,13 +108,15 @@ STEP_ORDER = (
     STEP_TOKEN_USAGE,
     STEP_RENDER_VIEWS,
     STEP_SPAWN_FOLLOWUPS,
+    STEP_RECORD_VERIFIED,
     STEP_VALIDATE_RUN,
     # After validation: the group's sibling tasks read this run's conclusion
     # from `group-context.md`, and only a validated record is worth handing on.
     STEP_RECORD_GROUP_MEMORY,
-    # Last, and only after the run validated: it removes the stage worktrees a
+    # Only after the run validated: it removes the stage worktrees a
     # blocked verdict would send the user straight back to.
     STEP_TEARDOWN_STAGES,
+    STEP_PRUNE_RUN_ARTIFACTS,
 )
 
 V3_STEP_ORDER = (
@@ -119,9 +127,12 @@ V3_STEP_ORDER = (
     STEP_TRANSLATE,
     STEP_RENDER_VIEWS,
     STEP_SPAWN_FOLLOWUPS,
+    # Needs the assembled record; `validate-run` requires the row it writes.
+    STEP_RECORD_VERIFIED,
     STEP_VALIDATE_RUN,
     STEP_RECORD_GROUP_MEMORY,
     STEP_TEARDOWN_STAGES,
+    STEP_PRUNE_RUN_ARTIFACTS,
 )
 
 # 앞 단계가 실패하면 건너뛰는 단계. 하나는 worktree 를 거두고, 하나는 검증 안 된
@@ -391,6 +402,10 @@ def build_commands(ctx: FinalizeContext) -> list[tuple[str, list[str]]]:
                 ctx.task_key,
             ],
         ),
+        (
+            STEP_RECORD_VERIFIED,
+            ["<in-process>", "record-verified", str(ctx.data_path)],
+        ),
         (STEP_VALIDATE_RUN, _validate_run_command(ctx, ctx.data_path)),
         (
             STEP_RECORD_GROUP_MEMORY,
@@ -400,6 +415,10 @@ def build_commands(ctx: FinalizeContext) -> list[tuple[str, list[str]]]:
             STEP_TEARDOWN_STAGES,
             ["<in-process>", "teardown-stages", str(ctx.data_path)],
         ),
+        (
+            STEP_PRUNE_RUN_ARTIFACTS,
+            ["<in-process>", "prune-run-artifacts", str(ctx.data_path)],
+        ),
     ]
     if ctx.report_contract_version != "3.0":
         return commands
@@ -502,6 +521,51 @@ def _next_in_group(steps: Sequence[Mapping[str, Any]]) -> dict[str, str] | None:
     return None
 
 
+def _record_verified_stages(
+    ctx: FinalizeContext,
+    command: list[str],
+) -> subprocess.CompletedProcess:
+    """Write a `verified` row for every stage a release-ready verdict clears.
+
+    `handoff record-verified` needs the assembled `data.json` and `validate-run`
+    requires its rows, and both happen inside this one call, so the lead had no
+    point at which to run it (observed 2026-09-26, dev-11054). Re-recording the
+    same report is a no-op, so a resumed finalize may run this again.
+    """
+    def _done(payload: Mapping[str, Any]) -> subprocess.CompletedProcess:
+        return subprocess.CompletedProcess(command, 0, json.dumps(payload), "")
+
+    if ctx.task_type != "final-verification":
+        return _done({"skipped": "not a final-verification run"})
+    try:
+        data = load_owned_object(Path(ctx.data_path), artifact="final report record")
+    except JsonBoundaryError as exc:
+        return subprocess.CompletedProcess(
+            command, 1, "", f"cannot read final-report data.json: {exc}")
+    if data.get("verificationScope") not in ("single-stage", "whole-task"):
+        return _done({"skipped": "report names no verification scope"})
+    if not release_handoff_allowed(data):
+        return _done({"skipped": "verdict does not clear the work for release"})
+    stages = sorted({
+        row["stage"]
+        for row in (data.get("finalVerification") or {}).get("stageReports") or ()
+        if isinstance(row, Mapping) and isinstance(row.get("stage"), int)
+    })
+    try:
+        plan_run_root = (
+            RunRef.from_report_path(Path(ctx.data_path).resolve())
+            .sibling("implementation-planning").run_dir
+        )
+        for stage in stages:
+            record_verified(
+                plan_run_root=plan_run_root, stage=stage,
+                report_path=str(ctx.data_path), data_json=str(ctx.data_path),
+            )
+    except (HandoffError, ValueError, OSError) as exc:
+        return subprocess.CompletedProcess(command, 1, "", str(exc))
+    return _done({"recorded": stages})
+
+
 def _teardown_stage_worktrees(
     ctx: FinalizeContext,
     command: list[str],
@@ -538,6 +602,27 @@ def _teardown_stage_worktrees(
     return _done(result)
 
 
+def _prune_run_artifacts(
+    ctx: FinalizeContext,
+    command: list[str],
+) -> subprocess.CompletedProcess:
+    """이 run 디렉터리에서 run 종료 뒤 읽는 곳이 없는 산출물을 지운다.
+
+    실패한 run 에서도 돈다. 빌드 디렉터리는 남은 lockfile 로 다시 만들고, dispatch
+    스냅샷은 검증을 통과한 run 의 것만 지운다(`run_artifact_prune`).
+    """
+    reports_dir = Path(ctx.data_path).resolve().parent
+    if reports_dir.name != "reports":
+        return subprocess.CompletedProcess(
+            command, 1, "", f"report record is not under a run's reports/: {ctx.data_path}")
+    run_dir = reports_dir.parent
+    try:
+        result = prune_run_artifacts(ctx.project_root, run_dir, apply=True)
+    except OSError as exc:
+        return subprocess.CompletedProcess(command, 1, "", str(exc))
+    return subprocess.CompletedProcess(command, 0, json.dumps(result), "")
+
+
 def _validate_run_command(ctx: FinalizeContext, report_record_path: Path) -> list[str]:
     command = [
         sys.executable,
@@ -875,8 +960,12 @@ def _run_finalize_step(
         return _run_translate(ctx, command)
     if name == STEP_TEARDOWN_STAGES:
         return _teardown_stage_worktrees(ctx, command)
+    if name == STEP_PRUNE_RUN_ARTIFACTS:
+        return _prune_run_artifacts(ctx, command)
     if name == STEP_RECORD_GROUP_MEMORY:
         return _record_group_memory(ctx, command)
+    if name == STEP_RECORD_VERIFIED:
+        return _record_verified_stages(ctx, command)
     if name == STEP_VALIDATE_RUN:
         try:
             _link_lead_result_for_validation(ctx)
@@ -1066,6 +1155,9 @@ Runs the Phase 7 steps in their contractual order against one final-report:
   5. spawn-followups   turn section 4 rows into task stubs
   6. validate-run      validate the finished run artifacts
   7. record-group-memory / 8. teardown-stages  after a clean validation
+  9. prune-run-artifacts  remove node_modules and .next under this run
+                       directory, and the dispatch snapshots and publication
+                       locks of a validated run; runs after a failure too
 
 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, except
@@ -1075,6 +1167,10 @@ exits non-zero the command prints the --only flags that resume the sequence
 from the earliest failing step — follow those rather than rerunning the failing
 step alone, which would leave the html rendered before the tokens landed.
 
+A full run (no --only) first records the lead's `phase-7-persist` checkpoint
+and returns it as `progressLines`; the lead emits that line instead of calling
+`okstra lead-progress append` for it.
+
 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.
@@ -1264,7 +1360,15 @@ def main(argv: Sequence[str] | None = None) -> int:
     # the generations resume and compaction split it into. It runs ahead of the
     # sequence because the token-usage step below reads `leadSessionIds`.
     observe_lead_session(ctx.project_root, ctx.team_state_path)
+    # 재개(`--only`)는 Phase 7 을 새로 시작하지 않고 다시 들어가는 것이다. 이 행은
+    # 그것을 요구하는 `validate-run` 보다 먼저 있어야 한다.
+    progress_line = None if args.only else record_checkpoint(
+        ctx.project_root, ctx.manifest_path, "phase-7-persist",
+        source="okstra report-finalize",
+    )
     result = run_finalize(ctx, only=args.only or None)
+    if progress_line:
+        result["progressLines"] = [progress_line]
     order = V3_STEP_ORDER if ctx.report_contract_version == "3.0" else STEP_ORDER
     print(json.dumps(result, indent=2, ensure_ascii=False))
     print("finalize steps:", file=sys.stderr)

package/runtime/python/okstra_ctl/report_html/context_links.py

@@ -247,7 +247,7 @@ def approved_plan_links(
     except JsonBoundaryError:
         return {}
     from .common import anchor_index
-    from .view_models.implementation_planning import ANCHORED_FIELDS
+    from okstra_ctl.phases.implementation_planning.report import ANCHORED_FIELDS
 
     page = html_view_path(record)
     href = Path(os.path.relpath(page, data_path.resolve().parent)).as_posix()

package/runtime/python/okstra_ctl/report_projections.py

@@ -4,10 +4,8 @@ from __future__ import annotations
 from okstra_token_usage.blocks import accounting_workers
 
 import json
-from copy import deepcopy
-from typing import Any, Mapping, Sequence
+from typing import Any, Mapping
 
-from .design_surfaces import DesignSurfaceTrigger, detect_design_surfaces
 from .report_contract import execution_roles_from_manifest
 from .usage_cells import duration_ms_from_bounds
 
@@ -220,39 +218,6 @@ def project_token_usage(team_state: Mapping[str, Any]) -> dict[str, Any]:
     }
 
 
-def _trigger_rows(trigger: DesignSurfaceTrigger) -> list[dict[str, Any]]:
-    return [
-        {"step": item.step, "field": item.field, "match": item.match}
-        for item in trigger.evidence
-    ]
-
-
-def project_design(
-    planning: Mapping[str, Any], detector_snapshot: Mapping[str, Any],
-) -> dict[str, Any]:
-    """탐지 결과가 실제 계획 표면과 일치할 때만 설계 블록을 반환한다."""
-    triggers = detect_design_surfaces(planning)
-    expected = {(row.stage, row.kind): _trigger_rows(row) for row in triggers}
-    coverage = detector_snapshot.get("stageCoverage")
-    coverage = coverage if isinstance(coverage, list) else []
-    actual: dict[tuple[int, str], list[dict[str, Any]]] = {}
-    for stage in coverage:
-        if not isinstance(stage, Mapping):
-            raise ReportProjectionError("owner=design-surface-detector invalid stageCoverage row")
-        for row in stage.get("rows") or []:
-            if isinstance(row, Mapping):
-                actual[(int(stage.get("stage") or 0), str(row.get("kind") or ""))] = list(row.get("triggerEvidence") or [])
-    if expected != actual:
-        raise ReportProjectionError("owner=design-surface-detector trigger coverage mismatch")
-    preparation = detector_snapshot.get("designPreparation")
-    if not isinstance(preparation, Mapping):
-        raise ReportProjectionError("owner=design-surface-detector missing designPreparation")
-    return {
-        "designPreparation": deepcopy(dict(preparation)),
-        "stageCoverage": deepcopy(coverage),
-    }
-
-
 def _round_history(state: Mapping[str, Any]) -> dict[str, Any]:
     if not (state.get("config") or {}).get("enabled", True):
         return {"disabled": True}

package/runtime/python/okstra_ctl/report_routing.py

@@ -0,0 +1,23 @@
+"""보고서 생산 단계와 분리된 공통 이동 적합성 검사."""
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+
+def technical_verification_routing_errors(data: Mapping[str, Any]) -> list[str]:
+    """기술 검증의 후속 목적지가 후보 비교인지 검사하며 목적지를 추론하지 않는다."""
+    if (data.get("header") or {}).get("taskType") != "technical-verification":
+        return []
+    block = data.get("technicalVerification") or {}
+    if (block.get("routing") or {}).get("nextTaskType") != "implementation-option-selection":
+        return ["technical verification returns only to implementation-option-selection"]
+    return []
+
+
+def fanout_routing_errors(packet_name: str, target: str | None) -> list[str]:
+    """작업 분해 패킷의 후속 단계가 허용된 값인지 검사한다."""
+    allowed = ("error-analysis", "implementation-option-selection")
+    if target not in allowed:
+        return [f"{packet_name}: recommended-next-phase not in {allowed}"]
+    return []