okstra 0.202.0 → 0.205.0

package/runtime/python/okstra_ctl/conformance.py

@@ -219,6 +219,49 @@ def exempt_stage_surface_conflicts(
     return conflicts
 
 
+def declared_stage_surface_gaps(
+    data: object, patterns: object = None,
+) -> list[dict[str, object]]:
+    """`Conformance tests:` 의 `requires` 가 계획된 경로의 표면을 다 덮지 못한 stage.
+
+    구현 게이트는 두 가지를 동시에 요구한다 — diff 가 건드린 표면을 `requires`
+    가 덮을 것(`_validate_conformance_surfaces`), 그리고 선언된 stage 의
+    `requires` 가 계획 선언과 같을 것(`_declared_conformance_errors`). 계획이
+    `requires` 를 좁게 적었는데 그 stage 가 계획한 경로가 다른 표면을 건드리면
+    구현은 둘 중 하나에 반드시 걸린다. 실측(2026-09-22, fontradar-v2-api dev-10860
+    Stage 1~3): `requires=[io]` 로 선언하고 `catalog.controller.ts`(http)를
+    계획해, 구현 run 이 "undeclared surface" 와 "requires mismatch" 를 번갈아 냈다.
+    면제 stage 와 같은 판별을 선언 stage 에도 승인 전에 한다.
+
+    반환 행: `{"stage": <int>, "surfaces": [빠진 표면..], "paths": [..],
+    "requires": [선언된 것..]}`.
+    """
+    planning = data.get("implementationPlanning") if isinstance(data, dict) else None
+    stages = planning.get("stages") if isinstance(planning, dict) else None
+    gaps: list[dict[str, object]] = []
+    for stage in stages if isinstance(stages, list) else []:
+        if not isinstance(stage, dict):
+            continue
+        parsed = parse_conformance_tests(stage.get("conformanceTests"))
+        number = stage.get("stage")
+        if parsed is None or not isinstance(number, int) or isinstance(number, bool):
+            continue
+        _script, requires = parsed
+        touching = sorted(
+            path for path in _stage_planned_paths(stage)
+            if detect_surfaces([path], patterns) - requires
+        )
+        missing = detect_surfaces(touching, patterns) - requires
+        if missing:
+            gaps.append({
+                "stage": number,
+                "surfaces": sorted(missing),
+                "paths": touching,
+                "requires": sorted(requires),
+            })
+    return gaps
+
+
 def _stage_planned_paths(stage: dict) -> list[str]:
     """stage 의 step 들이 계획한 경로 — 경로 모양인 문자열만.
 

package/runtime/python/okstra_ctl/consumers.py

@@ -218,9 +218,15 @@ def _append_row(plan_run_root: Path, record: Dict[str, Any]) -> None:
 
 def append_verified(plan_run_root: Path, *, impl_task_key: str, stage: int,
                     verdict: str, report_path: str, head_commit: str = "",
-                    final_verdict: dict | None = None) -> None:
-    """단독-stage final-verification 결과 기록. 같은 report_path 재기록은 멱등,
-    다른 report_path 는 재검증으로 append 한다 (읽기는 last-wins)."""
+                    final_verdict: dict | None = None,
+                    verification_scope: str = "",
+                    verified_head_commit: str = "") -> None:
+    """final-verification 결과를 stage 별로 기록. 같은 report_path 재기록은 멱등,
+    다른 report_path 는 재검증으로 append 한다 (읽기는 last-wins).
+
+    `head_commit` 은 언제나 이 stage 가 완료로 기록한 커밋이다. 전체 task 검증이
+    근거인 행은 검증된 head 가 그 커밋이 아니므로, 그 head 를
+    `verified_head_commit` 으로 함께 남긴다 — 자격 판정이 둘을 각각 대조한다."""
     with consumers_mutex(plan_run_root):
         rows = read_consumers(plan_run_root)
         done = latest_done_by_stage(rows).get(stage, {})
@@ -234,25 +240,34 @@ def append_verified(plan_run_root: Path, *, impl_task_key: str, stage: int,
                     and row.get("status") == "verified"
                     and row.get("report_path") == report_path):
                 return
-        _append_row(plan_run_root, {
+        row: Dict[str, Any] = {
             "impl_task_key": impl_task_key, "stage": stage,
             "status": "verified", "verdict": verdict,
             "report_path": report_path,
             "head_commit": head_commit,
             "final_verdict": final_verdict or {},
-        })
+        }
+        # 단독-stage 행에는 싣지 않는다 — 그 행의 검증된 head 는 `head_commit`
+        # 자신이고, 빈 필드를 더하면 옛 행과 새 행의 모양이 갈라진다.
+        if verification_scope:
+            row["verification_scope"] = verification_scope
+            row["verified_head_commit"] = verified_head_commit
+        _append_row(plan_run_root, row)
 
 
 def append_pr(plan_run_root: Path, *, impl_task_key: str, stages: List[int],
-              branch: str, url: str) -> None:
-    """handoff 의 PR 생성/재사용 기록. 같은 branch 의 pr 행이 이미 있으면 멱등."""
+              branch: str, url: str, base: str = "") -> None:
+    """handoff 의 PR 생성/재사용 기록. 같은 branch 의 pr 행이 이미 있으면 멱등.
+
+    `base` 는 그 PR 이 올라앉은 브랜치다. stage PR 은 스택이라 base 가 릴리스
+    브랜치가 아닐 수 있고, 어느 순서로 머지해야 하는지는 이 값에만 남는다."""
     with consumers_mutex(plan_run_root):
         for row in read_consumers(plan_run_root):
             if row.get("status") == "pr" and row.get("branch") == branch:
                 return
         _append_row(plan_run_root, {
             "impl_task_key": impl_task_key, "stages": sorted(stages),
-            "status": "pr", "branch": branch, "url": url,
+            "status": "pr", "branch": branch, "base": base, "url": url,
         })
 
 

package/runtime/python/okstra_ctl/container.py

@@ -213,8 +213,18 @@ def _compose_ps(project_name: str, cwd: str, include_stopped: bool = False) -> l
     return rows
 
 
-def _docker_run(argv: list[str], cwd: str | None = None) -> str:
+def _docker_run(argv: list[str], cwd: str | None = None, *, check: bool = False) -> str:
+    """docker 명령을 돌려 stdout 을 돌려준다.
+
+    `check=True` 면 0 이 아닌 종료를 PrepareError 로 올린다. status 가 빈 목록을,
+    down 이 성공을 보고하는데 실제로는 docker 가 실패한 경우를 막는다. config 계열
+    조회는 실패해도 진행하도록 설계돼 있어 기본값은 그대로 둔다."""
     result = subprocess.run(argv, capture_output=True, text=True, check=False, cwd=cwd)
+    if check and result.returncode != 0:
+        detail = (result.stderr or result.stdout or "").strip().splitlines()
+        raise PrepareError(
+            f"`{' '.join(argv[:4])}` 가 exit {result.returncode} 로 실패했습니다: "
+            f"{detail[-1] if detail else '출력 없음'}")
     return result.stdout or ""
 
 
@@ -222,7 +232,7 @@ def query_containers_by_label(project_name: str) -> list[dict]:
     """라벨 SSOT(spec §11): `okstra.project-name` 으로 컨테이너를 질의한다.
 
     registry 가 아니라 docker 라벨이 컨테이너 존재의 기준값이다."""
-    out = _docker_run([
+    out = _docker_run(check=True, argv=[
         "docker", "ps", "-a", "--filter",
         f"label=okstra.project-name={project_name}",
         "--format", (
@@ -431,7 +441,7 @@ def provision_container_group(
         raise PrepareError(
             f"container up: `up -d` 후 기동된 컨테이너가 없습니다(`docker compose -p "
             f"{project_name} ps -a` 로 확인). compose 정의·활성 profile 을 점검한 뒤 "
-            f"`okstra container down --task-key {task_key}` 로 정리하고 다시 시도하세요.")
+            f"`{_down_hint(project_root, task_key)}` 로 정리하고 다시 시도하세요.")
     failed = poll_healthcheck(
         project_name=project_name, cwd=str(worktree), services=started,
         healthcheck_timeout_seconds=healthcheck_timeout_seconds,
@@ -445,8 +455,8 @@ def provision_container_group(
         raise PrepareError(
             f"container up: 다음 서비스가 시간 내 기동하지 못했습니다: {', '.join(failed)} "
             f"(timeout={healthcheck_timeout_seconds}s). `docker compose -p "
-            f"{project_name} logs` 로 원인을 확인한 뒤 `okstra container down "
-            f"--task-key {task_key}` 로 정리하세요.")
+            f"{project_name} logs` 로 원인을 확인한 뒤 "
+            f"`{_down_hint(project_root, task_key)}` 로 정리하세요.")
     # deploy-state 는 실제 기동된 started 만 기록한다 — full services 를 쓰면
     # profiles 로 안 뜬 서비스가 `down --all` 스윕의 대상으로 남는다.
     _write_deploy_state(cp, project_name=project_name, task_key=task_key,
@@ -528,12 +538,18 @@ def status_container_group(*, project_root, task_key: str) -> dict:
             "containers": query_containers_by_label(project_name)}
 
 
+def _down_hint(project_root, task_key: str) -> str:
+    """실패 메시지가 안내하는 정리 명령. 파서가 요구하는 인자를 모두 싣는다."""
+    return f"okstra container down --project-root {project_root} --task-key {task_key}"
+
+
 def down_container_group(*, project_root, task_key: str = "", all_groups: bool = False) -> dict:
-    """라벨 쿼리로 컨테이너를 down 한다."""
+    """compose 프로젝트 이름으로 task 의 컨테이너 그룹을 down 한다."""
     from .ids import compose_project_name
 
     project_root = Path(project_root)
     results = []
+    failures: list[str] = []
     for project_id, group, task_id in _down_targets(project_root, task_key, all_groups):
         project_name = compose_project_name(project_id, group, task_id)
         # `docker rm -f` 는 컨테이너만 지우고 compose 가 만든 네트워크를 누수시킨다.
@@ -541,9 +557,16 @@ def down_container_group(*, project_root, task_key: str = "", all_groups: bool =
         # 단위 컨테이너+네트워크를 회수한다. `-v` 는 의도적으로 빼서 compose 에
         # 선언된 named volume(예: DB 데이터)을 보존한다 — down 한 번에 사용자
         # 영속 데이터를 파괴하지 않는다.
-        _docker_run(["docker", "compose", "-p", project_name, "down",
-                     "--remove-orphans"])
+        try:
+            _docker_run(["docker", "compose", "-p", project_name, "down",
+                         "--remove-orphans"], check=True)
+        except PrepareError as exc:
+            failures.append(f"{project_name}: {exc}")
+            continue
         results.append({"projectName": project_name})
+    if failures:
+        # 나머지 대상은 끝까지 내리고, 실패한 것만 모아 알린다.
+        raise PrepareError("container down 실패 — " + "; ".join(failures))
     return {"downed": results}
 
 

package/runtime/python/okstra_ctl/context_cost.py

@@ -2,7 +2,8 @@
 
 The estimator answers a narrow operational question: how much file/context
 surface does the current task bundle ask the lead, analysis workers, and
-report-writer to absorb? It does not mutate task artifacts.
+report-writer to absorb? It writes no report or run artifact; resolving the task
+may record a finished implementation outcome (see `find_task_root`).
 """
 from __future__ import annotations
 
@@ -38,11 +39,9 @@ HOT_PATH_LEAD_RESOURCES = (
     "convergence",
     "report-writer",
 )
-WORKER_AGENT_FILES = (
-    "claude-worker.md",
-    "report-writer-worker.md",
-    "translator-worker.md",
-)
+# 모든 디스패치 프롬프트 앞머리에 실리는 계약. 종전에는 `~/.claude/agents` 의
+# 에이전트 정의를 셌는데, 그 정의는 더 이상 설치되지 않는다(ADR-0017).
+HOT_PATH_AGENT_CONTRACTS = ("agents/common.json",)
 TIMESTAMPED_ARTIFACT_RE = re.compile(r"\d{4}-\d{2}-\d{2}[_T]\d{2}-\d{2}-\d{2}")
 
 
@@ -136,7 +135,7 @@ def _duty_contract_files(
     if not isinstance(duty_root_value, str) or not duty_root_value:
         return []
     duty_root = project_root / duty_root_value
-    files = [duty_root / "common.md", duty_root / f"{audience}.md"]
+    files = [duty_root / "common.json", duty_root / f"{audience}.json"]
     return [path for path in files if path.is_file()]
 
 
@@ -239,19 +238,15 @@ def _skill_assets_metric() -> dict:
     instruction footprint and are the prompt-diet ranking input."""
     entries = []
     okstra_home = _okstra_asset_home()
-    claude_home = Path.home() / ".claude"
     for name in HOT_PATH_LEAD_RESOURCES:
         path = _installed_or_dev(
             okstra_home / "prompts" / "lead" / f"{name}.md",
             f"prompts/lead/{name}.md",
         )
         entries.append((f"resource:{name}", path))
-    for fname in WORKER_AGENT_FILES:
-        path = _installed_or_dev(
-            claude_home / "agents" / fname,
-            f"runtime/agents/workers/{fname}",
-        )
-        entries.append((f"agent:{fname}", path))
+    for relative in HOT_PATH_AGENT_CONTRACTS:
+        path = _installed_or_dev(okstra_home / relative, relative)
+        entries.append((f"contract:{relative}", path))
 
     files = []
     for label, path in entries:
@@ -512,7 +507,8 @@ _CLI_EPILOG = r"""Usage:
 
 Output: JSON with task file counts, current-run counts, lead Phase 1 read
 surface, analysis-worker initial read surface, and report-writer synthesis
-surface. This is read-only; it never mutates task artifacts.
+surface. Resolving a task may record a finished implementation outcome in its task
+manifest, the task catalog, and consumers.jsonl; nothing else is written.
 """
 
 

package/runtime/python/okstra_ctl/contract_refreeze.py

@@ -0,0 +1,156 @@
+"""진행 중인 run 의 동결 계약을 현재 형식으로 다시 동결한다.
+
+run 은 시작할 때 직무·역할·공통 계약을 자기 폴더로 동결하고, 그 다이제스트를
+매니페스트에 적는다. 계약 형식이 바뀐 릴리스를 설치하면 그 run 의 다이제스트는
+새 규칙으로 계산한 값과 영영 다르고, 프롬프트를 하나도 더 만들 수 없다 — 실측
+2026-09-23(fontradar-v2-api dev-10860 implementation-planning-002): 같은 run 에서
+8회 성공한 뒤 설치가 한 번 일어나자 그다음 materialize 가
+`run duty snapshot catalog digest does not match` 로 멈췄다.
+
+이 모듈은 그 run 을 현재 형식으로 다시 동결하고 매니페스트의 다이제스트와 형식
+표식을 갱신한다. 계약 본문은 런타임이 소유하므로 새로 쓰는 것이 원래 값이고,
+run 의 증거(프롬프트·결과·원장)는 건드리지 않는다. 사용자가 명시적으로 부를 때만
+도는 복구 경로다.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Mapping
+
+from .agent.invocation import digest_duty_catalog
+from .json_boundary import (
+    JsonBoundaryError,
+    load_owned_object,
+    write_owned_object_atomic,
+)
+from .run import (
+    CONTRACT_FORMAT_VERSION,
+    PrepareError,
+    _common_contract_source,
+    _duty_catalog_source,
+)
+
+
+class ContractRefreezeError(RuntimeError):
+    """다시 동결할 수 없는 run. 메시지가 그 자리를 이름한다."""
+
+
+@dataclass(frozen=True)
+class RefreezeResult:
+    duty_root: str
+    previous_digest: str
+    digest: str
+    previous_format_version: int
+    format_version: int
+    changed: bool
+
+
+def frozen_format_version(contract: Mapping[str, Any]) -> int:
+    """이 run 이 동결한 계약 형식. 표식이 없는 run 은 1(Markdown 직무)이다."""
+    value = contract.get("contractFormatVersion")
+    return value if isinstance(value, int) and not isinstance(value, bool) else 1
+
+
+def refreeze_message(duty_root: str) -> str:
+    """형식이 어긋난 run 이 받아야 할 문장 — 원인과 다음 명령."""
+    return (
+        "run froze an older duty contract format and this install cannot read "
+        f"it: {duty_root}. Re-freeze this run's contracts with "
+        "`okstra agent-prompt refreeze-contracts --project-root <dir> "
+        "--run-manifest <path>`, then repeat the command that failed."
+    )
+
+
+def refreeze_run_contracts(
+    *, project_root: Path, run_manifest_path: Path, workspace_root: Path,
+) -> RefreezeResult:
+    """이 run 의 계약 폴더를 현재 런타임 카탈로그로 갈아 끼운다."""
+    root = project_root.resolve()
+    manifest_path = _resolve(root, run_manifest_path)
+    manifest = _load(manifest_path, "run manifest")
+    contract = manifest.get("agentContract")
+    if not isinstance(contract, dict):
+        raise ContractRefreezeError(f"run manifest has no agentContract: {manifest_path}")
+    duty_root_rel = str(contract.get("dutyRootPath") or "")
+    if not duty_root_rel:
+        raise ContractRefreezeError(f"agentContract has no dutyRootPath: {manifest_path}")
+    duty_root = _resolve(root, Path(duty_root_rel))
+    previous_digest = str(contract.get("catalogDigest") or "")
+    previous_format = frozen_format_version(contract)
+    try:
+        source = _duty_catalog_source(workspace_root)
+        common_source = _common_contract_source(workspace_root)
+    except PrepareError as exc:
+        raise ContractRefreezeError(str(exc)) from exc
+    digest = _replace_snapshot(duty_root, source, common_source)
+    changed = (
+        digest != previous_digest or previous_format != CONTRACT_FORMAT_VERSION
+    )
+    if changed:
+        contract["catalogDigest"] = digest
+        contract["contractFormatVersion"] = CONTRACT_FORMAT_VERSION
+        _write_manifest(manifest_path, manifest)
+    return RefreezeResult(
+        duty_root=str(duty_root),
+        previous_digest=previous_digest,
+        digest=digest,
+        previous_format_version=previous_format,
+        format_version=CONTRACT_FORMAT_VERSION,
+        changed=changed,
+    )
+
+
+def _replace_snapshot(duty_root: Path, source: Path, common_source: Path) -> str:
+    """계약 폴더를 통째로 새로 쓴다. 옛 형식 파일은 남기지 않는다.
+
+    옛 파일을 남기면 두 형식이 한 폴더에 섞이고, 다이제스트가 세는 대상과 로더가
+    읽는 대상이 다시 갈린다 — 이 결함이 처음 생긴 자리가 그 갈림이다.
+    """
+    duty_root.parent.mkdir(parents=True, exist_ok=True)
+    staged = Path(tempfile.mkdtemp(
+        dir=duty_root.parent, prefix=f".{duty_root.name}.", suffix=".refreeze",
+    ))
+    retired = duty_root.with_name(f".{duty_root.name}.retired")
+    try:
+        shutil.copytree(source, staged, dirs_exist_ok=True)
+        shutil.copyfile(common_source, staged / "common.json")
+        shutil.copytree(
+            common_source.parent / "roles", staged / "roles", dirs_exist_ok=True
+        )
+        digest = digest_duty_catalog(staged)
+        if duty_root.exists():
+            shutil.rmtree(retired, ignore_errors=True)
+            os.rename(duty_root, retired)
+        os.rename(staged, duty_root)
+    except OSError as exc:
+        raise ContractRefreezeError(f"cannot re-freeze duty contracts: {exc}") from exc
+    finally:
+        shutil.rmtree(staged, ignore_errors=True)
+        shutil.rmtree(retired, ignore_errors=True)
+    return digest
+
+
+def _resolve(project_root: Path, value: Path) -> Path:
+    path = Path(value).expanduser()
+    return path if path.is_absolute() else project_root / path
+
+
+def _load(path: Path, label: str) -> dict[str, Any]:
+    try:
+        payload = load_owned_object(path, artifact=label)
+    except (OSError, JsonBoundaryError) as exc:
+        raise ContractRefreezeError(f"cannot read {label} {path}: {exc}") from exc
+    if not isinstance(payload, dict):
+        raise ContractRefreezeError(f"{label} is not an object: {path}")
+    return payload
+
+
+def _write_manifest(path: Path, manifest: Mapping[str, Any]) -> None:
+    try:
+        write_owned_object_atomic(path, manifest, artifact="run manifest")
+    except JsonBoundaryError as exc:
+        raise ContractRefreezeError(f"cannot write run manifest {path}: {exc}") from exc

package/runtime/python/okstra_ctl/convergence_engine.py

@@ -849,6 +849,44 @@ def validate_working_state(state: Mapping[str, Any]) -> list[str]:
     return errors
 
 
+def lead_only_final_state(task_key: str) -> dict[str, Any]:
+    """워커를 띄우지 않는 phase 의 수렴 최종 상태.
+
+    리포트 계약 3.0 은 모든 리포트에 수렴 입력을 요구한다(ADR-0020: 사실마다
+    소유자가 하나). release-handoff 처럼 프로필이 "convergence 를 돌지 않는다"
+    고 선언한 phase 에는 그 파일을 만드는 주체가 없었고, report-finalize 가
+    `required input is missing` 으로 멈췄다. 리드는 매 run 마다 seed →
+    plan-round → finalize 를 손으로 돌려 빈 상태를 만들어 왔다(실측: dev-10860
+    release-handoff 001·002 둘 다).
+
+    "수렴이 돌지 않았다" 는 부재가 아니라 사실이므로 파일로 남긴다 — 분석자가
+    둘 미만이어서 자동 비활성이라는 뜻이고, 그게 이 어휘의 `auto-disabled` 다.
+    """
+    state = {
+        "schemaVersion": FINAL_SCHEMA_VERSION,
+        "taskKey": task_key,
+        "config": {
+            "enabled": False,
+            "adversarial": False,
+            "maxRounds": 1,
+            "effectiveMaxRounds": 1,
+            "verificationMode": "lightweight",
+            "autoDisabled": "fewer-than-two-analysers",
+        },
+        "findings": [],
+        "roundHistory": [],
+        "round2SkippedReason": "auto-disabled",
+        "finalState": "converged",
+        "totalRounds": 0,
+        "finalClassificationCounts": classification_counts_from_findings([]),
+    }
+    errors = validate_final_state(state)
+    if errors:
+        raise ConvergenceContractError(
+            "lead-only convergence state is invalid: " + "; ".join(errors))
+    return state
+
+
 def validate_final_state(state: Mapping[str, Any]) -> list[str]:
     """Validate historical v1.0-v1.2 and strict current v1.3 artifacts."""
     errors: list[str] = []

package/runtime/python/okstra_ctl/convergence_provenance.py

@@ -154,7 +154,13 @@ def worker_result_paths(
         if candidate.resolve().parent != results_dir.resolve():
             raise ValueError(f"accepted resultPath is outside worker-results: {candidate}")
         if not candidate.is_file():
-            raise ValueError(f"accepted resultPath is missing: {candidate}")
+            # 이 모듈의 계약은 "없는 워커 결과는 조용히 건너뛴다" 이고, 그 판정은
+            # 아래 `read_canonical_worker_result` 가 None 을 돌려주는 것으로
+            # 이루어진다. 여기서 던지면 판정이 아니라 run 이 죽는다 — 실측
+            # 2026-09-23(jobs dev-10860 stage 1): 옛 run 의 원장이 ok 로 적은
+            # 결과 파일이 디스크에 없어 `report-finalize --only validate-run` 이
+            # 예외로 멈췄다. 파일명 규칙 경로를 그대로 두고 넘어간다.
+            continue
         paths[row["workerId"]] = candidate
     return paths
 

package/runtime/python/okstra_ctl/design_prep.py

@@ -20,6 +20,7 @@ from fnmatch import fnmatchcase
 from pathlib import Path
 from typing import Any, Iterator
 
+from .consumers import read_stage_consumer_state
 from .final_report_schema import load_schema, validate as validate_schema
 from .json_boundary import JsonBoundaryError, load_owned_object
 from okstra_project import ResolverError, resolve_project_root
@@ -466,6 +467,7 @@ def materialize_design_prep_requests(plan_data_path: Path) -> list[Path]:
     # 충돌은 한 항목씩 알리지 않는다. 요청 12개가 모두 옛 리포트의 파일과 부딪히면
     # 첫 건에서 멈추는 구현은 사용자에게 12회 왕복을 시키고, 그때마다 이미 쓴
     # 앞쪽 파일이 남아 상태가 절반만 진행된다. 전부 렌더해 전부 검사한 뒤 쓴다.
+    done = _done_stages(data_path)
     rendered = [
         _render_request(
             data_path=data_path,
@@ -474,7 +476,7 @@ def materialize_design_prep_requests(plan_data_path: Path) -> list[Path]:
             item=item,
         )
         for item in items
-        if item.get("status") in _REQUEST_STATUSES
+        if item.get("status") in _REQUEST_STATUSES and not _is_implemented(item, done)
     ]
     conflicts = [
         reason
@@ -494,6 +496,37 @@ def materialize_design_prep_requests(plan_data_path: Path) -> list[Path]:
     return written
 
 
+def _done_stages(data_path: Path) -> frozenset[int]:
+    """이 태스크에서 이미 구현이 끝난 stage.
+
+    원장을 못 읽으면 빈 집합이다 — 그때의 동작은 이 판정이 없던 때와 같고,
+    "모르니까 건너뛴다" 는 반대 방향의 실패보다 안전하다.
+    """
+    try:
+        state = read_stage_consumer_state(data_path.parent.parent)
+    except (OSError, UnicodeError, ValueError):
+        return frozenset()
+    return frozenset(state.done_stages)
+
+
+def _is_implemented(item: Mapping[str, Any], done: frozenset[int]) -> bool:
+    """이 항목이 가리키는 stage 가 전부 구현 완료인가.
+
+    구현이 끝난 stage 의 계획은 역사이지 계획이 아니다. 그런데 탐지기는 매
+    계획 run 마다 이월된 stage 본문을 다시 훑고, 그 사이 선택 방향의
+    `fileStructure` 가 바뀌면 같은 PREP 항목이 다른 증거로 렌더된다. 요청
+    파일은 태스크 단위 이름이라 불변 파일과 충돌하고, report-finalize 는
+    빠져나갈 길 없이 멈춘다(2026-09-24, dev-10860: 9건). 이미 지어진 것에
+    설계 준비를 다시 요구하는 것이므로, 답도 쓸모가 없다.
+    """
+    stages = [
+        stage
+        for stage in item.get("stageRefs") or ()
+        if isinstance(stage, int) and not isinstance(stage, bool)
+    ]
+    return bool(stages) and all(stage in done for stage in stages)
+
+
 def load_design_prep_items(report_path: Path) -> tuple[dict[str, Any], ...]:
     """Return validated snapshot items without exposing mutable report data."""
     data_path = _canonical_data_path(report_path)