okstra 0.179.2 → 0.180.0

package/runtime/python/okstra_ctl/report_projections.py

@@ -0,0 +1,265 @@
+"""역할별 실행 입력을 최종 리포트 조각으로 바꾸는 순수 투영."""
+from __future__ import annotations
+
+import json
+from copy import deepcopy
+from typing import Any, Mapping, Sequence
+
+from .design_surfaces import DesignSurfaceTrigger, detect_design_surfaces
+from .report_contract import execution_roles_from_manifest
+
+
+class ReportProjectionError(ValueError):
+    """소유자 입력을 정본 조각으로 투영할 수 없다."""
+
+
+_AGENT_LABELS = {
+    "claude": "Claude Code",
+    "claude-code": "Claude Code",
+    "codex": "Codex",
+    "antigravity": "Antigravity",
+    "grok": "Grok",
+    "kimi": "Kimi",
+}
+_STATUS = {
+    "done": "completed",
+    "passed": "completed",
+    "failed": "error",
+    "blocked": "error",
+    "pending": "not-run",
+    "prepared": "not-run",
+}
+
+
+def _text(value: object, fallback: str) -> str:
+    text = str(value or "").strip()
+    return text or fallback
+
+
+def _status(value: object) -> str:
+    text = str(value or "not-run").strip().lower()
+    return _STATUS.get(text, text if text in {
+        "completed", "error", "timeout", "not-run", "synthesis-only"
+    } else "not-run")
+
+
+def _agent_label(row: Mapping[str, Any]) -> str:
+    value = _text(row.get("agent") or row.get("provider"), "codex")
+    return _AGENT_LABELS.get(value.lower(), value)
+
+
+def _execution_row(row: Mapping[str, Any], *, lead: bool = False) -> dict[str, Any]:
+    role = _text(row.get("role"), "Okstra lead" if lead else "Worker")
+    result = {
+        "agent": _agent_label(row),
+        "role": role,
+        "model": _text(row.get("model") or row.get("modelExecutionValue"), "unknown"),
+        "status": _status(row.get("status")),
+        "summary": _text(
+            row.get("summary") or row.get("reason"),
+            "Run coordination recorded by team state." if lead
+            else "Worker execution recorded by team state.",
+        ),
+    }
+    _populate_usage(result, row.get("usage") or {})
+    return result
+
+
+def _populate_usage(row: dict[str, Any], usage: object) -> None:
+    source = usage if isinstance(usage, Mapping) else {}
+    mapping = {
+        "totalTokens": "totalTokens",
+        "cacheReadTokens": "cacheReadTokens",
+        "billableEquivalentTokens": "billableTokens",
+        "estimatedCostUsd": "costUsd",
+        "cliTotalTokens": "cliTotalTokens",
+        "cliEstimatedCostUsd": "cliCostUsd",
+        "durationMs": "durationMs",
+    }
+    for source_key, target_key in mapping.items():
+        if source_key in source and source.get("source") != "unavailable":
+            row[target_key] = source[source_key]
+
+
+def project_execution(
+    manifest: Mapping[str, Any], team_state: Mapping[str, Any],
+) -> dict[str, Any]:
+    """실행 역할과 상태를 매니페스트·팀 상태에서만 만든다."""
+    lead = team_state.get("lead")
+    lead_row = lead if isinstance(lead, Mapping) else {
+        "agent": manifest.get("leadRuntime") or manifest.get("leadProvider"),
+        "model": manifest.get("leadModel") or "unknown",
+        "status": "completed",
+        "role": "Okstra lead",
+    }
+    workers = team_state.get("workers")
+    worker_rows = workers if isinstance(workers, list) else []
+    result: dict[str, Any] = {
+        "executionStatus": [
+            _execution_row(lead_row, lead=True),
+            *[
+                _execution_row(row)
+                for row in worker_rows
+                if isinstance(row, Mapping)
+            ],
+        ]
+    }
+    roles = execution_roles_from_manifest(dict(manifest))
+    if roles:
+        result.update(executionIdentityVersion=2, executionRoles=roles)
+    return result
+
+
+def _usage_row(summary: Mapping[str, Any], prefix: str, cost: object) -> dict[str, Any]:
+    return {
+        "totalTokens": summary.get(f"{prefix}TotalTokens"),
+        "cacheReadTokens": summary.get(f"{prefix}CacheReadTokens"),
+        "billableTokens": summary.get(f"{prefix}BillableEquivalentTokens"),
+        "costUsd": cost,
+    }
+
+
+def _worker_details(team_state: Mapping[str, Any]) -> list[dict[str, Any]]:
+    result = []
+    for worker in team_state.get("workers") or []:
+        if not isinstance(worker, Mapping):
+            continue
+        usage = worker.get("usage") if isinstance(worker.get("usage"), Mapping) else {}
+        row = {"label": _text(worker.get("role") or worker.get("workerId"), "Worker")}
+        _populate_usage(row, usage)
+        for key in ("totalTokens", "cacheReadTokens", "billableTokens", "costUsd", "cliTotalTokens", "cliCostUsd"):
+            row.setdefault(key, None)
+        result.append(row)
+    return result
+
+
+def project_token_usage(team_state: Mapping[str, Any]) -> dict[str, Any]:
+    """팀 상태의 사용량 합계를 리포트 표 구조로 반환한다."""
+    summary = team_state.get("usageSummary")
+    summary = summary if isinstance(summary, Mapping) else {}
+    costs = summary.get("estimatedCostUsd")
+    costs = costs if isinstance(costs, Mapping) else {}
+    lead_cost = costs.get("lead")
+    worker_cost = costs.get("claudeWorkers")
+    return {
+        "lead": _usage_row(summary, "lead", lead_cost),
+        "worker": _usage_row(summary, "worker", worker_cost),
+        "grand": _usage_row(
+            summary,
+            "grand",
+            None if lead_cost is None or worker_cost is None else lead_cost + worker_cost,
+        ),
+        "workerDetails": _worker_details(team_state),
+        "cli": {"costUsd": costs.get("cliWorkers")},
+    }
+
+
+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}
+    rows = []
+    for row in state.get("roundHistory") or []:
+        if not isinstance(row, Mapping):
+            continue
+        rows.append({
+            "round": row.get("round", 0),
+            "inputQueueSize": row.get("inputQueueSize", 0),
+            "resolvedCount": row.get("resolvedCount", 0),
+            "carriedForwardCount": row.get("carriedForwardCount", 0),
+            "dispatches": json.dumps(row.get("dispatches") or [], ensure_ascii=False),
+            "skippedWorkers": json.dumps(row.get("skippedWorkers") or [], ensure_ascii=False),
+        })
+    return {"rounds": rows, "round2SkippedReason": state.get("round2SkippedReason", "not-skipped")}
+
+
+def _source_items(finding: Mapping[str, Any]) -> list[str]:
+    finding_id = _text(finding.get("findingId"), "unknown")
+    workers = finding.get("consensusWorkers") or [finding.get("originWorker")]
+    return [f"{_text(worker, 'worker').removesuffix('-worker')}:{finding_id}" for worker in workers]
+
+
+def project_convergence(state: Mapping[str, Any]) -> dict[str, Any]:
+    """수렴 상태에서 독자용 합의·이견과 공개 근거만 승격한다."""
+    consensus = []
+    differences = []
+    promoted = []
+    for finding in state.get("findings") or []:
+        if not isinstance(finding, Mapping):
+            continue
+        evidence = _text(finding.get("originEvidence"), "")
+        ticket_ids = finding.get("ticketIds") or ["unknown"]
+        ticket_id = _text(ticket_ids[0] if ticket_ids else "unknown", "unknown")
+        if finding.get("classification") in {"full-consensus", "partial-consensus"}:
+            row = {
+                "id": f"C-{len(consensus) + 1:03d}",
+                "ticketId": ticket_id,
+                "statement": _text(finding.get("summary"), "Converged finding"),
+                "sourceItems": _source_items(finding),
+                "evidence": evidence or "convergence state",
+            }
+            consensus.append(row)
+            if evidence and ("/" in evidence or ":" in evidence):
+                promoted.append({
+                    "findingId": finding.get("findingId"),
+                    "ticketId": ticket_id,
+                    "evidence": evidence,
+                    "sourceItems": row["sourceItems"],
+                })
+        else:
+            positions = []
+            for worker in [finding.get("originWorker"), *(finding.get("dissentingWorkers") or [])]:
+                if worker:
+                    positions.append({
+                        "worker": str(worker),
+                        "itemId": _text(finding.get("findingId"), ""),
+                        "position": "origin" if worker == finding.get("originWorker") else "dissent",
+                    })
+            differences.append({
+                "id": f"D-{len(differences) + 1:03d}",
+                "ticketId": ticket_id,
+                "disagreement": _text(finding.get("summary"), "Unresolved difference"),
+                "workersPosition": positions or [{"worker": "unknown", "itemId": "", "position": "unresolved"}],
+                "evidence": evidence or "convergence state",
+            })
+    result = {
+        "crossVerification": {
+            "roundHistory": _round_history(state),
+            "consensus": consensus,
+            "differences": differences,
+        },
+        "promotedEvidence": promoted,
+    }
+    return result

package/runtime/python/okstra_ctl/run.py

@@ -32,7 +32,11 @@ from okstra_project import project_json_path, upsert_project_json
 from okstra_project.state import slugify
 from . import fix_cycles
 from .analysis_packet import build_analysis_packet
-from .stage_ledger import build_stage_ledger, render_stage_ledger
+from .stage_ledger import (
+    build_stage_ledger,
+    render_stage_ledger,
+    stage_ledger_notice,
+)
 from .analysis_inputs import (
     ANALYSIS_TASK_TYPES,
     AnalysisInputError,
@@ -109,7 +113,10 @@ from .legacy_model_selection import (
     serialize_host_session_context,
 )
 from .model_defaults import ModelDefaultScopes
-from .worker_prompt_policy import ANALYSIS_DUTY_BY_TASK_TYPE
+from .worker_prompt_policy import (
+    ANALYSIS_DUTY_BY_TASK_TYPE,
+    critic_assignment_ref,
+)
 from .models import (
     UnknownProviderError,
     default_model,
@@ -2504,6 +2511,7 @@ def _resolve_model_bindings(
         worker_assignments,
         critic_assignment,
         translator_assignment,
+        inp.task_type,
     )
     worker_by_provider = {
         row.provider: row for row in worker_assignments
@@ -2653,6 +2661,7 @@ def _project_model_bindings(
         workers,
         critic_assignment,
         _role_assignment(resolved=translator, role="translator"),
+        inp.task_type,
     )
     worker_by_provider = {row.provider: row for row in workers}
     return _ModelBindings(
@@ -2892,6 +2901,7 @@ def _build_invocation_assignments(
     workers: tuple[RoleAssignment, ...],
     critic: RoleAssignment | None,
     translator: RoleAssignment,
+    task_type: str,
 ) -> dict[str, dict[str, object]]:
     assignments = {"lead": lead.to_model_payload()}
     for assignment in workers:
@@ -2902,8 +2912,11 @@ def _build_invocation_assignments(
             assignment.to_model_payload()
         )
     if critic is not None:
-        assignments["critic/scope"] = critic.to_model_payload()
-        assignments["critic/acceptance"] = critic.to_model_payload()
+        # 한 run 이 도달할 수 있는 critic 은 한 종류다. 둘 다 등록하면 실행될
+        # 수 없는 로스터 행이 남고, `_optional_worker_roles` 가 provider 로만
+        # role 라벨을 만들기 때문에 두 행의 이름이 겹쳐 validate-run 이
+        # `duplicate worker role detected` 로 런을 실패시킨다.
+        assignments[critic_assignment_ref(task_type)] = critic.to_model_payload()
     assignments["translator"] = translator.to_model_payload()
     return assignments
 
@@ -3218,6 +3231,12 @@ def _write_instruction_set_sources(
     render_reference_expectations(
         str(inp.brief_path), str(instruction_set / "reference-expectations.md"), ctx,
     )
+    # 계획 phase 만 원장을 받는다. 원장은 "무엇이 이미 지어졌나" 를 계획 저작
+    # 쪽에 알려 주는 것이므로, 계획을 쓰지 않는 phase 에는 실을 자리가 없다.
+    stage_ledger = (
+        build_stage_ledger(Path(ctx["TASK_MANIFEST_PATH"]).parent)
+        if inp.task_type == "implementation-planning" else None
+    )
     packet = build_analysis_packet(
         task_key=ctx["TASK_KEY"],
         task_type=ctx["TASK_TYPE"],
@@ -3232,11 +3251,8 @@ def _write_instruction_set_sources(
         instruction_set_relative_path=ctx["INSTRUCTION_SET_RELATIVE_PATH"],
         fix_history_text=fix_cycles.packet_summary(
             fix_cycles.read_rows(Path(ctx["TASK_MANIFEST_PATH"]).parent)),
-        stage_ledger_json=(
-            render_stage_ledger(
-                build_stage_ledger(Path(ctx["TASK_MANIFEST_PATH"]).parent))
-            if inp.task_type == "implementation-planning" else ""
-        ),
+        stage_ledger_json=render_stage_ledger(stage_ledger),
+        stage_ledger_notice=stage_ledger_notice(stage_ledger),
     )
     if inp.task_type in ANALYSIS_TASK_TYPES:
         packet += (

package/runtime/python/okstra_ctl/schema_excerpt.py

@@ -1,11 +1,11 @@
-"""Build a task-type-scoped excerpt of the final-report schema.
+"""Build a task-type-scoped excerpt of a versioned final-report schema.
 
-The full schema (``schemas/final-report-v2.0.schema.json``) carries the
+The full schema carries the
 deliverable property blocks for ALL task-types (``errorAnalysis``, the three
 read-only analysis blocks, ``implementationPlanning``, ``releaseHandoff``,
 ``implementation``, and ``finalVerification``) plus a
 ``$defs`` library (~38% of the file) shared across them. A single run only
-authors ONE task-type's data.json, so the report-writer worker only needs
+authors ONE task-type's narrative, so the report-writer worker only needs
 the common structure + its own task-type's block + the ``$defs`` those
 reach.
 
@@ -16,7 +16,7 @@ repo/installed schema (whose `schemas/...` path is not even resolvable
 from inside a consumer project's task bundle).
 
 The excerpt is ADVISORY — a reading aid for the author. Validation always
-runs against the FULL schema via ``final_report_schema.load_schema()``, so
+runs against the matching FULL schema, so
 the excerpt never gates correctness; it only trims what the worker reads.
 """
 from __future__ import annotations
@@ -28,7 +28,7 @@ from dataclasses import dataclass
 from pathlib import Path
 
 from .final_report_schema import load_schema_version
-from .report_contract import CURRENT_REPORT_SCHEMA_VERSION, TASK_TYPE_DATA_PROPERTY
+from .report_contract import TASK_TYPE_DATA_PROPERTY
 
 
 _ALL_PER_TYPE_PROPERTIES = frozenset(TASK_TYPE_DATA_PROPERTY.values())
@@ -168,9 +168,14 @@ def excerpt_contract_skew(
     cut_from = excerpt_cut_from_version(excerpt)
     if not cut_from or cut_from == installed:
         return None
+    schema_version = (
+        excerpt.get("properties", {})
+        .get("schemaVersion", {})
+        .get("const", "2.0")
+    )
     try:
         fresh = build_schema_excerpt(
-            load_schema_version(CURRENT_REPORT_SCHEMA_VERSION), task_type, installed
+            load_schema_version(str(schema_version)), task_type, installed
         )
     except Exception:  # noqa: BLE001 — an unloadable schema proves no drift
         return None

package/runtime/python/okstra_ctl/stage_fix_carry.py

@@ -1,8 +1,8 @@
 """Derive the fix-run carry for an implementation stage whose previous run
 ended with one or more verifier FAIL verdicts.
 
-Pure read-side: scans the stage run directory's final-report data.json files
-(the JSON SSOT written by the report writer) and the stage worktree HEAD.
+Pure read-side: scans the stage run directory's assembled final-report data.json
+files and the stage worktree HEAD.
 Returns None when the upcoming run is not a fix run, so callers can treat
 "no carry" and "first run on this stage" identically.
 """
@@ -47,8 +47,8 @@ class StageFixCarry:
             "`report-writer.md` § Fix-run incremental authoring).",
             "This block is inlined into the executor and verifier prompts by "
             "`initial_prompt_materialization`; do not transcribe it by hand. "
-            "Lead duties: pass the previous data.json path above to the "
-            "report-writer dispatch so it authors incrementally.",
+            "Lead duties: pass the previous data.json path above as read context "
+            "to the report-writer dispatch so it updates only changed narrative blocks.",
         ])
         return "\n".join(lines)
 

package/runtime/python/okstra_ctl/stage_ledger.py

@@ -4,8 +4,17 @@
 이 모듈은 그 사실만 모아 준다 — 무엇을 계획해야 하는지는 말하지 않는다.
 
 판정은 소유하지 않는다. 상태 어휘와 lifecycle 판정은 stage_targets 가, stage
-map 의 출처 판정은 stage_map.load_task_stage_map 이 소유한다. 여기서는 둘을
-잇고 직렬화만 한다.
+map 의 출처 판정은 stage_map 이 소유한다. 여기서는 둘을 잇고 직렬화만 한다.
+
+원장은 두 질문에 답하고, 답의 출처가 서로 다르다.
+
+- "무엇이 이미 지어졌나" — carry 사이드카가 가리키는 계획이 답한다. 실행이
+  실제로 따른 문서이기 때문이다.
+- "어떤 stage 번호가 이미 쓰였나" — 최신 계획이 답한다. ADR-0015 의
+  append-only 는 최신 계획의 `max` 로만 판정할 수 있다.
+
+한 소스가 둘 다 답하면, 완료 이후 stage 를 덧붙인 계획이 있을 때 그 번호가
+비어 있는 것처럼 보이고 새 stage 가 그 번호를 다시 받는다.
 """
 from __future__ import annotations
 
@@ -15,25 +24,31 @@ from typing import Any
 
 from .consumers import read_stage_consumer_state
 from .paths import RunRef
-from .stage_map import StageMapError, load_task_stage_map
+from .stage_map import (
+    StageMapError,
+    load_latest_plan_stage_map,
+    load_task_stage_map,
+)
 from .stage_targets import stage_lifecycle_snapshot_from_state
 from .task_target import infer_project_root
 
 
 def build_stage_ledger(task_root: Path) -> dict[str, Any] | None:
-    """이 task 의 Stage 원장. 계획 리포트가 아직 없으면 ``None``.
+    """이 task 의 Stage 원장.
+
+    세 결과를 구분한다. 셋이 하나로 접히면 소비처가 "계획이 아직 없다" 와
+    "계획을 못 읽었다" 를 같은 것으로 읽는다.
 
-    ``None`` 과 빈 리스트를 구분한다 — 계획이 없는 첫 run 과 stage 가 하나도
-    없는 계획은 저작 쪽에 다른 뜻이다.
+    - ``None`` — 계획 리포트가 아직 없다. 이 task 의 첫 계획 run 이다.
+    - ``{"unreadable": <사유>}`` — 계획은 있는데 Stage Map 을 못 읽었다.
+    - 그 외 — 사실 기록.
     """
     task_root = Path(task_root)
     try:
-        snapshot = load_task_stage_map(task_root, {})
-    except StageMapError:
-        # 계획 출처가 충돌하거나 읽히지 않는 경우. 원장을 추측해 싣느니 싣지
-        # 않는다 — 틀린 원장은 없는 원장보다 나쁘다.
-        return None
-    if snapshot.state != "ready" or not snapshot.stages:
+        latest = load_latest_plan_stage_map(task_root)
+    except StageMapError as exc:
+        return {"unreadable": _failure_reason(task_root, exc)}
+    if latest.state != "ready" or not latest.stages:
         return None
 
     plan_run_root = RunRef.from_task_root(
@@ -43,20 +58,119 @@ def build_stage_ledger(task_root: Path) -> dict[str, Any] | None:
     # 같은 멱등 복구이며, 이걸 건너뛰면 크래시 창에 걸린 완료 stage 가 원장에
     # 미완으로 실려 저작 쪽이 이미 구현된 stage 를 다시 계획한다.
     state = read_stage_consumer_state(plan_run_root, recover_from_carry=True)
-    lifecycle = stage_lifecycle_snapshot_from_state(snapshot.stages, state)
-    return {
-        "sourcePlan": _project_relative(task_root, snapshot.source_plan_path),
-        "stages": lifecycle.ledger_records(),
+    lifecycle = stage_lifecycle_snapshot_from_state(latest.stages, state)
+    records = lifecycle.ledger_records()
+
+    built_from, divergence = _built_from(task_root, latest)
+    divergence += _renumbering_divergence(
+        latest, built_from, state.done_stages
+    )
+    ledger: dict[str, Any] = {
+        "sourcePlan": _project_relative(
+            task_root, built_from.source_plan_path if built_from else ""
+        ),
+        "latestPlan": _project_relative(task_root, latest.source_plan_path),
+        "stages": records,
     }
+    if divergence:
+        ledger["planDivergence"] = divergence
+    return ledger
 
 
 def render_stage_ledger(ledger: dict[str, Any] | None) -> str:
-    """packet 에 실릴 JSON 본문. 원장이 없으면 빈 문자열."""
-    if not ledger:
+    """packet 에 실릴 JSON 본문. 사실 기록이 없으면 빈 문자열."""
+    if not ledger or ledger.get("unreadable"):
         return ""
     return json.dumps(ledger, ensure_ascii=False, indent=2)
 
 
+def stage_ledger_notice(ledger: dict[str, Any] | None) -> str:
+    """원장을 실을 수 없는 사유. 실을 수 있으면 빈 문자열.
+
+    평문이다. 실패 통지는 저작 쪽이 파싱할 데이터가 아니라 읽을 판정이고,
+    JSON 표면을 하나 더 만들면 그만큼 오독할 키가 늘어난다.
+    """
+    if not ledger:
+        return ""
+    return str(ledger.get("unreadable") or "")
+
+
+def _built_from(task_root: Path, latest: Any):
+    """완료된 stage 가 따른 계획. 못 읽으면 ``(None, [사유])``.
+
+    이걸 못 읽어도 원장 자체는 낼 수 있다 — 상태는 consumers 원장에서 오고,
+    stage 목록은 최신 계획에서 온다. 잃는 것은 번호 재배치 검사뿐이므로,
+    실패를 원장 부재로 승격하지 않고 그 사실만 함께 싣는다.
+    """
+    try:
+        return load_task_stage_map(task_root, {}), []
+    except StageMapError as exc:
+        return None, [
+            "could not read the plan the completed stages were built against, "
+            "so stage renumbering could not be checked: "
+            + _failure_reason(task_root, exc)
+        ]
+
+
+def _renumbering_divergence(
+    latest: Any,
+    built_from: Any,
+    done_stages: set[int],
+) -> list[str]:
+    """완료된 stage 가 두 계획에서 같은 작업을 가리키는지.
+
+    ADR-0015 는 stage 번호의 재사용과 재배치를 금지하므로, 규칙이 지켜졌다면
+    최신 계획 위에 실행 상태를 겹쳐 쓰는 것이 안전하다. 지켜졌는지는 검사할
+    사실이지 가정할 사실이 아니다 — 과거 replan 이 번호를 다시 매겼다면 완료
+    커밋이 엉뚱한 stage 에 귀속되고, 그 오류는 통합 시점까지 조용하다.
+    """
+    if built_from is None or built_from.state != "ready":
+        return []
+    if built_from.source_plan_path == latest.source_plan_path:
+        # 완료된 stage 를 지은 계획이 곧 최신 계획이다. 비교할 두 번째 계획이
+        # 없으므로 재배치가 일어날 자리 자체가 없다.
+        return []
+    latest_titles = {
+        int(row["stage_number"]): str(row.get("title") or "")
+        for row in latest.stages
+    }
+    built_titles = {
+        int(row["stage_number"]): str(row.get("title") or "")
+        for row in built_from.stages
+    }
+    notes: list[str] = []
+    for stage in sorted(done_stages):
+        if stage not in built_titles:
+            continue
+        if stage not in latest_titles:
+            notes.append(
+                f"stage {stage} is recorded done but the latest plan does not "
+                "declare it; a completed stage was dropped rather than cancelled"
+            )
+            continue
+        if built_titles[stage] != latest_titles[stage]:
+            notes.append(
+                f"stage {stage} names different work in the two plans "
+                f"(built: {built_titles[stage]!r}; latest: "
+                f"{latest_titles[stage]!r}); its completion may be attributed "
+                "to the wrong stage"
+            )
+    return notes
+
+
+def _failure_reason(task_root: Path, exc: StageMapError) -> str:
+    """StageMapError 를 프로젝트 상대 경로로 낮춘 한 줄."""
+    parts = [exc.reason]
+    if exc.source_plan_path:
+        parts.append(f"source={_project_relative(task_root, exc.source_plan_path)}")
+    if exc.conflicting_paths:
+        conflicts = ", ".join(
+            _project_relative(task_root, path) for path in exc.conflicting_paths
+        )
+        parts.append(f"conflicts={conflicts}")
+    return "; ".join(parts)
+
+
 def _project_relative(task_root: Path, source_plan_path: str) -> str:
     """절대 경로를 프로젝트 상대로 낮춘다.