okstra 0.201.3 → 0.204.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

@@ -244,15 +244,18 @@ def append_verified(plan_run_root: Path, *, impl_task_key: str, stage: int,
 
 
 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_critic_prompt.py

@@ -28,7 +28,7 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Mapping, Sequence
 
-from .convergence_provenance import worker_result_suffix
+from .convergence_provenance import worker_result_paths, worker_result_suffix
 from .fixed_text import line
 from .json_boundary import JsonBoundaryError, load_owned_object
 from .paths import RunRef
@@ -132,9 +132,7 @@ def analyser_results(
 ) -> list[AnalyserResult]:
     """분석 audience 워커마다 결과 파일 경로와 finding id 를 짝지어 돌려준다.
 
-    결과 파일명은 `convergence_provenance` 가 이미 소유한 규칙을 그대로 쓴다 —
-    `<worker>-worker-<task-type>-<workerResults seq>.md`. state 시퀀스와 다른
-    카운터라 그룹 파일명에서 접미사를 빌려 오면 빗나간다.
+    출처 검사와 같은 실행 원장을 사용해야 교정 전 결과를 재검증하지 않는다.
     """
     suffix = worker_result_suffix(Path(run_dir), groups)
     if suffix is None:
@@ -142,13 +140,13 @@ def analyser_results(
             "cannot resolve the worker-result suffix from the grouping's "
             "runManifestPath"
         )
-    results_dir = Path(run_dir) / "worker-results"
+    paths = worker_result_paths(Path(run_dir), groups, suffix)
     by_worker = _findings_by_worker(groups)
     return [
         AnalyserResult(
             worker_id=worker,
             result_path=_project_relative(
-                project_root, results_dir / f"{worker}-worker-{suffix}.md"
+                project_root, paths[worker]
             ),
             finding_ids=tuple(by_worker.get(worker, ())),
         )

package/runtime/python/okstra_ctl/convergence_provenance.py

@@ -21,6 +21,8 @@ from pathlib import Path
 from typing import Mapping
 
 from okstra_ctl.convergence_engine import grouped_input_digest
+from okstra_ctl.execution_identity import Attempt, ExecutionManifest
+from okstra_ctl.execution_manifest import read_execution_manifest_view
 from okstra_ctl.json_boundary import (
     load_owned_object,
 )
@@ -97,6 +99,72 @@ def groups_digest_ok(state_dir: Path, suffix: str, document: dict) -> bool:
     return grouped_input_digest(document) == recorded
 
 
+def discovery_attempts(manifest: ExecutionManifest) -> dict[str, list[Attempt]]:
+    """교정 실행은 발견 결과를 대체하지만 재검증 투표는 발견 출처가 아니다."""
+    latest: dict[str, Attempt] = {}
+    for attempt in manifest.attempts:
+        current = latest.get(attempt.invocation_ref)
+        if current is None or attempt.attempt > current.attempt:
+            latest[attempt.invocation_ref] = attempt
+    by_role: dict[str, list[Attempt]] = {}
+    for invocation in manifest.invocations:
+        if invocation.dispatch_kind not in {"initial", "correction"}:
+            continue
+        attempt = latest.get(invocation.invocation_ref)
+        if attempt is not None:
+            by_role.setdefault(invocation.role_execution_ref, []).append(attempt)
+    return by_role
+
+
+def worker_result_paths(
+    run_dir: Path, document: Mapping, suffix: str
+) -> dict[str, Path]:
+    """실행 원장의 채택된 발견 결과를 고른다. 구형 원장은 파일명 규칙을 쓴다."""
+    results_dir = run_dir / "worker-results"
+    workers = document.get("workers") or []
+    paths = {
+        row["workerId"]: results_dir / f"{row['workerId']}-worker-{suffix}.md"
+        for row in workers if isinstance(row, Mapping) and row.get("workerId")
+    }
+    if document.get("schemaVersion") != "2.0":
+        return paths
+    recorded = document.get("runManifestPath")
+    if not _nonempty_string(recorded):
+        return paths
+    manifest_path = run_dir / "manifests" / Path(recorded).name
+    manifest, authority = read_execution_manifest_view(manifest_path)
+    if manifest.legacy:
+        return paths
+    attempts = discovery_attempts(manifest)
+    for row in workers:
+        if not isinstance(row, Mapping) or not row.get("workerId"):
+            continue
+        accepted = [
+            attempt for attempt in attempts.get(row.get("sourceRoleExecutionRef"), [])
+            if attempt.status == "ok" and attempt.result_path
+        ]
+        if not accepted:
+            continue
+        candidate = Path(accepted[-1].result_path)
+        if not candidate.is_absolute():
+            project_root = authority.get("projectRoot")
+            if not _nonempty_string(project_root):
+                raise ValueError("relative accepted resultPath requires projectRoot")
+            candidate = Path(project_root) / candidate
+        if candidate.resolve().parent != results_dir.resolve():
+            raise ValueError(f"accepted resultPath is outside worker-results: {candidate}")
+        if not candidate.is_file():
+            # 이 모듈의 계약은 "없는 워커 결과는 조용히 건너뛴다" 이고, 그 판정은
+            # 아래 `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
+
+
 def read_canonical_worker_result(
     worker_results_dir: Path, worker: str, suffix: str
 ) -> str | None:
@@ -140,20 +208,25 @@ def provenance_errors(
     claims = group_claims(document)
     if claims is None:
         return []
+    paths = worker_result_paths(worker_results_dir.parent, document, suffix)
     contents: dict[str, str | None] = {}
     errors: list[str] = []
     for finding_id, worker, item_id in claims:
         if worker not in contents:
-            contents[worker] = read_canonical_worker_result(
-                worker_results_dir, worker, suffix
-            )
+            candidate = paths.get(worker)
+            if candidate is not None and candidate.name != f"{worker}-worker-{suffix}.md":
+                contents[worker] = candidate.read_text(encoding="utf-8")
+            else:
+                contents[worker] = read_canonical_worker_result(
+                    worker_results_dir, worker, suffix
+                )
         text = contents[worker]
         if text is None or id_occurs_wordbounded(text, item_id):
             continue
         errors.append(
             f"convergence groups `{groups_label}` group {finding_id} "
             f"cites source item `{worker}:{item_id}`, but that ID does not "
-            f"occur in the worker's result file `{worker}-worker-{suffix}.md` — a "
+            f"occur in the worker's result file `{paths.get(worker, Path(f'{worker}-worker-{suffix}.md')).name}` — a "
             "grouping may not invent a provenance link to an item the "
             "worker never reported."
         )
@@ -243,10 +316,10 @@ DISCARDED_ATTEMPT_STATUSES = frozenset(
 
 
 def discarded_workers(document: object, execution_manifest: object) -> dict[str, str]:
-    """``{workerId: "<invocationRef>#<attempt> <status>"}`` — 초기 attempt 가 전부
+    """``{workerId: "<invocationRef>#<attempt> <status>"}`` — 발견 attempt 가 전부
     폐기돼 채택할 결과가 없는 분석 워커.
 
-    한 워커의 초기 invocation 이 둘 이상이면(교정 디스패치는 새 invocation 이다)
+    한 워커의 발견 invocation 이 둘 이상이면(교정 디스패치는 새 invocation 이다)
     그중 하나라도 마지막 attempt 가 ``ok`` 면 채택 가능한 결과가 있는 것이므로
     폐기로 보지 않는다. legacy 매니페스트나 v1 roster 는 판정하지 않는다.
     """
@@ -254,17 +327,7 @@ def discarded_workers(document: object, execution_manifest: object) -> dict[str,
         return {}
     if execution_manifest is None or getattr(execution_manifest, "legacy", False):
         return {}
-    initial_refs: dict[str, set[str]] = {}
-    for invocation in getattr(execution_manifest, "invocations", ()):
-        if invocation.dispatch_kind == "initial":
-            initial_refs.setdefault(invocation.role_execution_ref, set()).add(
-                invocation.invocation_ref
-            )
-    latest: dict[str, object] = {}
-    for attempt in getattr(execution_manifest, "attempts", ()):
-        current = latest.get(attempt.invocation_ref)
-        if current is None or attempt.attempt > current.attempt:
-            latest[attempt.invocation_ref] = attempt
+    attempts = discovery_attempts(execution_manifest)
     result: dict[str, str] = {}
     for row in document["workers"]:
         if not isinstance(row, dict):
@@ -273,7 +336,7 @@ def discarded_workers(document: object, execution_manifest: object) -> dict[str,
         role_ref = row.get("sourceRoleExecutionRef")
         if not _nonempty_string(worker) or not _nonempty_string(role_ref):
             continue
-        rows = [latest[ref] for ref in sorted(initial_refs.get(role_ref, ())) if ref in latest]
+        rows = attempts.get(role_ref, [])
         if not rows or any(item.status == "ok" for item in rows):
             continue
         discarded = [item for item in rows if item.status in DISCARDED_ATTEMPT_STATUSES]

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)