okstra 0.179.2 → 0.183.2

package/runtime/python/okstra_ctl/set_work_status.py

@@ -15,7 +15,9 @@ from datetime import datetime, timezone
 from pathlib import Path
 
 from okstra_ctl.ids import slugify_task_segment
+from okstra_ctl.fixed_text import line, scalar
 from okstra_ctl.paths import task_dir, task_manifest_file
+from okstra_ctl.json_boundary import load_owned_object, write_owned_object_atomic
 from okstra_project import (
     ResolverError,
     StateError,
@@ -26,8 +28,23 @@ from okstra_project import (
 ALLOWED_WORK_STATUSES = ("todo", "in-progress", "blocked", "done")
 
 
-def _emit(payload: dict) -> None:
-    print(json.dumps(payload, ensure_ascii=False, indent=2))
+def _emit(payload: dict, *, text: bool = False) -> None:
+    if not text:
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+        return
+    lines = ["# Okstra Work Status Result", ""]
+    for key, label in (
+        ("ok", "OK"), ("stage", "Stage"), ("reason", "Reason"),
+        ("taskKey", "Task key"), ("previousWorkStatus", "Previous work status"),
+        ("workStatus", "Work status"), ("workStatusUpdatedAt", "Updated at"),
+        ("workStatusNote", "Note"), ("taskManifestPath", "Task manifest"),
+    ):
+        if key in payload:
+            lines.append(line(label, payload.get(key)).rstrip("\n"))
+    for match in payload.get("matches", []) if isinstance(payload.get("matches"), list) else []:
+        if isinstance(match, dict):
+            lines.append(f"- Match: `{scalar(match.get('taskKey'))}`")
+    print("\n".join(lines))
 
 
 def _manifest_path(project_root: Path, entry: dict) -> Path:
@@ -44,7 +61,7 @@ def _manifest_path(project_root: Path, entry: dict) -> Path:
     return task_manifest_file(task_dir(project_root, group_seg, id_seg))
 
 
-def main(argv: list[str] | None = None) -> int:
+def _parse_args(argv: list[str] | None):
     parser = argparse.ArgumentParser(
         description="Set a task's user-managed workStatus in task-manifest.json."
     )
@@ -64,13 +81,16 @@ def main(argv: list[str] | None = None) -> int:
     parser.add_argument("--project-root", default="", help="project root for catalog lookup")
     parser.add_argument("--cwd", default=".", help="cwd for project root resolution")
     parser.add_argument("--json", action="store_true", help="emit JSON (always on)")
-    args = parser.parse_args(argv)
+    parser.add_argument("--text", action="store_true", help="emit fixed text fields")
+    return parser.parse_args(argv)
+
 
+def _resolve_entry(args):
     try:
         project_root = resolve_project_root(explicit_root=args.project_root, cwd=args.cwd)
     except ResolverError as exc:
-        _emit({"ok": False, "stage": "resolve", "reason": str(exc)})
-        return 2
+        _emit({"ok": False, "stage": "resolve", "reason": str(exc)}, text=args.text)
+        return None, None, 2
 
     token = args.token
     task_group = args.task_group
@@ -84,17 +104,42 @@ def main(argv: list[str] | None = None) -> int:
             project_root, token, task_group=task_group or None
         )
     except StateError as exc:
-        _emit({"ok": False, "stage": "catalog", "reason": str(exc)})
-        return 2
+        _emit({"ok": False, "stage": "catalog", "reason": str(exc)}, text=args.text)
+        return None, None, 2
 
     if not matches:
-        _emit({"ok": False, "stage": "not-found", "token": args.token})
-        return 1
+        _emit({"ok": False, "stage": "not-found", "token": args.token}, text=args.text)
+        return None, None, 1
     if len(matches) > 1:
-        _emit({"ok": False, "stage": "ambiguous", "matches": matches})
-        return 2
+        _emit({"ok": False, "stage": "ambiguous", "matches": matches}, text=args.text)
+        return None, None, 2
+    return project_root, matches[0], 0
+
+
+def _updated_payload(manifest_path: Path, manifest: dict, entry: dict, args) -> dict:
+    previous = manifest.get("workStatus", "")
+    manifest["workStatus"] = args.status
+    manifest["workStatusUpdatedAt"] = datetime.now(timezone.utc).strftime(
+        "%Y-%m-%dT%H:%M:%SZ"
+    )
+    if args.note is not None:
+        manifest["workStatusNote"] = args.note
+    write_owned_object_atomic(manifest_path, manifest, artifact="task manifest")
+    return {
+        "ok": True, "taskKey": entry.get("taskKey", ""),
+        "previousWorkStatus": previous, "workStatus": args.status,
+        "workStatusUpdatedAt": manifest["workStatusUpdatedAt"],
+        "workStatusNote": manifest.get("workStatusNote", ""),
+        "taskManifestPath": str(manifest_path),
+    }
 
-    entry = matches[0]
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parse_args(argv)
+    project_root, entry, resolution_exit = _resolve_entry(args)
+    if resolution_exit:
+        return resolution_exit
+    assert project_root is not None and entry is not None
     manifest_path = _manifest_path(project_root, entry)
     if not manifest_path.exists():
         _emit(
@@ -103,11 +148,12 @@ def main(argv: list[str] | None = None) -> int:
                 "stage": "manifest-missing",
                 "taskKey": entry.get("taskKey", ""),
                 "taskManifestPath": str(manifest_path),
-            }
+            },
+            text=args.text,
         )
         return 1
     try:
-        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+        manifest = load_owned_object(manifest_path, artifact="task manifest")
     except ValueError as exc:
         _emit(
             {
@@ -115,32 +161,12 @@ def main(argv: list[str] | None = None) -> int:
                 "stage": "manifest-invalid",
                 "taskManifestPath": str(manifest_path),
                 "reason": str(exc),
-            }
+            },
+            text=args.text,
         )
         return 1
 
-    previous = manifest.get("workStatus", "")
-    manifest["workStatus"] = args.status
-    manifest["workStatusUpdatedAt"] = datetime.now(timezone.utc).strftime(
-        "%Y-%m-%dT%H:%M:%SZ"
-    )
-    if args.note is not None:
-        manifest["workStatusNote"] = args.note
-    manifest_path.write_text(
-        json.dumps(manifest, indent=2, ensure_ascii=False) + "\n", encoding="utf-8"
-    )
-
-    _emit(
-        {
-            "ok": True,
-            "taskKey": entry.get("taskKey", ""),
-            "previousWorkStatus": previous,
-            "workStatus": args.status,
-            "workStatusUpdatedAt": manifest["workStatusUpdatedAt"],
-            "workStatusNote": manifest.get("workStatusNote", ""),
-            "taskManifestPath": str(manifest_path),
-        }
-    )
+    _emit(_updated_payload(manifest_path, manifest, entry, args), text=args.text)
     return 0
 
 

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.
 """
@@ -14,6 +14,8 @@ import subprocess
 from dataclasses import dataclass
 from pathlib import Path
 
+from .json_boundary import JsonBoundaryError, load_owned_object
+
 _REPORT_RE = re.compile(r"final-report-implementation-(\d+)\.data\.json$")
 
 
@@ -47,8 +49,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)
 
@@ -60,8 +62,8 @@ def derive_stage_fix_carry(
     if report is None:
         return None
     try:
-        data = json.loads(report.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError):
+        data = load_owned_object(report, artifact="implementation final report")
+    except (OSError, JsonBoundaryError):
         return None
     impl = data.get("implementation")
     if not isinstance(impl, dict):

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:
     """절대 경로를 프로젝트 상대로 낮춘다.
 

package/runtime/python/okstra_ctl/stage_map.py

@@ -7,6 +7,9 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Iterable
 
+from .final_report_paths import final_report_data_path, is_full_reading_copy_path
+from .json_boundary import JsonBoundaryError, load_owned_object
+from .fixed_text import line, value_lines
 from .md_table import is_separator_row, split_pipe_row
 from .paths import RunRef
 from .plan_run_root import list_implementation_planning_reports
@@ -47,6 +50,24 @@ class StageMapSnapshot:
     stages: list[dict[str, Any]]
 
 
+def render_stage_map_text(payload: dict[str, Any]) -> str:
+    """모델 소비용 Stage Map 스냅샷을 고정 텍스트로 투영한다."""
+    rows = ["Okstra stage map\n"]
+    rows.append(line("Status", "ready" if payload.get("ok") else "error"))
+    for label, key in (
+        ("Task key", "taskKey"), ("Task root", "taskRoot"),
+        ("State", "state"), ("Source plan path", "sourcePlanPath"),
+    ):
+        rows.append(line(label, payload.get(key)))
+    for label, key in (("Stages", "stages"), ("Done stages", "doneStages"),
+                       ("Planning", "planning")):
+        rows.extend(value_lines(label, payload.get(key)))
+    if not payload.get("ok"):
+        rows.append(line("Failure stage", payload.get("stage")))
+        rows.append(line("Failure reason", payload.get("reason")))
+    return "".join(rows)
+
+
 # `stepwiseExecution` is what the stage DOES; the other three are what becomes
 # true when it is finished. A schedule carrying only the latter reads as an
 # analysis of a plan rather than the plan itself.
@@ -353,8 +374,8 @@ def parse_stage_map_file(plan_path: Path) -> list[StageMapStage]:
     resolved = Path(plan_path).resolve()
     if is_report_record_path(resolved):
         try:
-            data = json.loads(resolved.read_text(encoding="utf-8"))
-        except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+            data = load_owned_object(resolved, artifact="planning final report")
+        except (OSError, UnicodeError, JsonBoundaryError) as exc:
             raise StageMapError("stage_map", str(exc), str(resolved)) from exc
         if not isinstance(data, dict):
             raise StageMapError(
@@ -364,8 +385,8 @@ def parse_stage_map_file(plan_path: Path) -> list[StageMapStage]:
     return _parse_stage_map_markdown(resolved)
 
 
-def schema_v2_report(plan_path: Path) -> dict[str, Any]:
-    """The schema-v2 report record as a whole, `{}` for a v1 markdown path.
+def structured_report(plan_path: Path) -> dict[str, Any]:
+    """계약 2.0·3.0 구조화 리포트를 반환하고 Markdown에는 빈 값을 반환한다.
 
     Public because every caller that must branch on report schema needs it —
     including `validators/validate-implementation-plan-stages.py`, which is a
@@ -378,17 +399,22 @@ def schema_v2_report(plan_path: Path) -> dict[str, Any]:
     if not is_report_record_path(resolved) or not resolved.exists():
         return {}
     try:
-        data = json.loads(resolved.read_text(encoding="utf-8"))
-    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        data = load_owned_object(resolved, artifact="planning final report")
+    except (OSError, UnicodeError, JsonBoundaryError) as exc:
         raise StageMapError("stage_map", str(exc), str(resolved)) from exc
-    if not isinstance(data, dict) or data.get("schemaVersion") != "2.0":
+    if not isinstance(data, dict) or data.get("schemaVersion") not in {"2.0", "3.0"}:
         return {}
     return data
 
 
+def schema_v2_report(plan_path: Path) -> dict[str, Any]:
+    """기존 호출자를 위한 구조화 리포트 판독 별칭."""
+    return structured_report(plan_path)
+
+
 def _planning_section(markdown_path: Path) -> dict[str, Any]:
     """The report's `implementationPlanning` block, `{}` for v1."""
-    planning = schema_v2_report(markdown_path).get("implementationPlanning")
+    planning = structured_report(markdown_path).get("implementationPlanning")
     return planning if isinstance(planning, dict) else {}
 
 
@@ -412,7 +438,7 @@ def _stage_narratives(value: Any) -> dict[int, dict[str, Any]]:
 
 def load_planning_detail(markdown_path: Path) -> PlanningDetail:
     """Read one report's narrative rows; empty for a schema-v1 report."""
-    report = schema_v2_report(markdown_path)
+    report = structured_report(markdown_path)
     planning = report.get("implementationPlanning")
     if not isinstance(planning, dict) or not planning:
         return PlanningDetail({}, {})
@@ -456,9 +482,34 @@ def stage_map_records(stages: Iterable[StageMapStage]) -> list[dict[str, Any]]:
     ]
 
 
+def _latest_plan_report(task_root: Path) -> Path | None:
+    reports_dir = RunRef.from_task_root(
+        task_root, "implementation-planning"
+    ).reports_dir
+    reports = list_implementation_planning_reports(reports_dir)
+    return reports[0] if reports else None
+
+
+def _snapshot_for(source: Path | None) -> StageMapSnapshot:
+    if source is None:
+        return StageMapSnapshot("missing", "", [])
+    resolved = source.resolve()
+    return StageMapSnapshot(
+        "ready",
+        str(resolved),
+        stage_map_records(parse_stage_map_file(resolved)),
+    )
+
+
 def load_task_stage_map(
     task_root: Path, manifest: dict[str, Any],
 ) -> StageMapSnapshot:
+    """완료된 stage 를 무엇으로 지었는지 답하는 Stage Map.
+
+    carry 사이드카가 가리키는 계획을 우선한다 — 그게 실행이 실제로 따른
+    문서이기 때문이다. "어떤 stage 번호가 이미 쓰였나" 는 다른 질문이며
+    `load_latest_plan_stage_map` 이 답한다.
+    """
     carried = _unique_carry_source_paths(task_root)
     if len(carried) > 1:
         paths = tuple(str(path) for path in carried)
@@ -467,22 +518,19 @@ def load_task_stage_map(
             "implementation carries reference different source plans",
             conflicting_paths=paths,
         )
-    if carried:
-        source = carried[0]
-    else:
-        reports_dir = RunRef.from_task_root(
-            task_root, "implementation-planning"
-        ).reports_dir
-        reports = list_implementation_planning_reports(reports_dir)
-        source = reports[0] if reports else None
-    if source is None:
-        return StageMapSnapshot("missing", "", [])
-    resolved = source.resolve()
-    return StageMapSnapshot(
-        "ready",
-        str(resolved),
-        stage_map_records(parse_stage_map_file(resolved)),
-    )
+    source = carried[0] if carried else _latest_plan_report(task_root)
+    return _snapshot_for(source)
+
+
+def load_latest_plan_stage_map(task_root: Path) -> StageMapSnapshot:
+    """이 task 의 최신 계획 리포트가 선언한 Stage Map.
+
+    번호 점유의 판정 기준이다. ADR-0015 는 stage 번호를 append-only 로 두고
+    새 stage 를 `max+1` 로 붙이라고 정하는데, 그 `max` 는 최신 계획에서만
+    나온다 — 완료된 stage 를 지을 때 쓴 계획 뒤에 stage 를 덧붙인 계획이
+    있으면 그 번호들도 이미 점유된 상태다.
+    """
+    return _snapshot_for(_latest_plan_report(task_root))
 
 
 def _unique_carry_source_paths(task_root: Path) -> list[Path]:
@@ -490,15 +538,35 @@ def _unique_carry_source_paths(task_root: Path) -> list[Path]:
     paths: set[Path] = set()
     for carry_path in sorted(carry_dir.glob("stage-*.json")):
         try:
-            carry = json.loads(carry_path.read_text(encoding="utf-8"))
-        except (OSError, UnicodeError, json.JSONDecodeError):
+            carry = load_owned_object(carry_path, artifact="implementation stage carry")
+        except (OSError, UnicodeError, JsonBoundaryError):
             continue
         value = carry.get("sourcePlanPath") if isinstance(carry, dict) else None
         if isinstance(value, str) and value:
-            paths.add(_resolve_plan_path(task_root, value).resolve())
+            # carry 의 이 값은 executor 워커가 손으로 적는 자유 문자열이고,
+            # `--approved-plan` 이 레코드 전용으로 조여지기 전에 준비된 run 은
+            # 읽기본(`.md`) 경로를 남겼다. v2 리포트의 `.md` 에는 Stage Map
+            # 섹션이 없으므로 그대로 읽으면 원장이 통째로 사라진다. 같은 legacy
+            # 포인터 정규화를 run-index·타임라인 소비자는 이미 하고 있다.
+            # 읽는 쪽에서만 낮춘다 — 동결된 carry 사이드카는 고치지 않는다.
+            paths.add(_carry_source_path(task_root, value))
     return sorted(paths, key=str)
 
 
+def _carry_source_path(task_root: Path, value: str) -> Path:
+    """carry 가 가리키는 계획의 읽을 경로.
+
+    레코드 형제가 실재할 때만 읽기본(`.md`)을 레코드로 낮춘다. schema-v1 계획은
+    레코드가 아예 없고 마크다운이 유일한 정본이므로, 무조건 낮추면 v1 태스크의
+    Stage Map 을 없는 파일에서 찾게 된다.
+    """
+    resolved = _resolve_plan_path(task_root, value).resolve()
+    if not is_full_reading_copy_path(resolved):
+        return resolved
+    record = final_report_data_path(resolved)
+    return record if record.is_file() else resolved
+
+
 def _resolve_plan_path(task_root: Path, value: str) -> Path:
     path = Path(value)
     if path.is_absolute():

package/runtime/python/okstra_ctl/stage_targets.py

@@ -853,18 +853,17 @@ def integrate_and_teardown_whole_task(
     stage_map 은 done 행에서 만든다. 정리 대상은 완료된 stage 뿐이고, 계획에만 있고
     완료되지 않은 stage 는 Phase A 가 어차피 건너뛰기 때문이다.
     """
-    from json import loads as _loads
-
     from okstra_project.dirs import okstra_home, project_json_path
 
     from . import consumers, worktree_registry
+    from .json_boundary import load_owned_object
     from .locks import worktree_provision_mutex
     from .paths import task_runs_dir
     from .stage_integrate import integrate_stages
 
     try:
-        project_id = _loads(
-            project_json_path(project_root).read_text(encoding="utf-8")
+        project_id = load_owned_object(
+            project_json_path(project_root), artifact="project config"
         ).get("projectId", "")
     except (OSError, ValueError):
         project_id = ""

package/runtime/python/okstra_ctl/team.py

@@ -39,6 +39,7 @@ from .ports.worker_dispatch import WorkerDispatchRequest
 from .registry.host_registry import default_host_registry
 from .registry.provider_registry import default_provider_registry
 from .session import observe_lead_session
+from .json_boundary import load_owned_object
 
 
 _SUPPORTED_WRAPPERS = provider_worker_wrappers(default_provider_registry())
@@ -81,7 +82,7 @@ def _add_dispatch_parser(sub) -> None:
     parser.add_argument("--workers", default="")
     parser.add_argument("--jobs-file", default="")
     parser.add_argument("--dry-run", action="store_true")
-    parser.add_argument("--idle-timeout-seconds", type=int, default=600)
+    parser.add_argument("--idle-timeout-seconds", type=int, default=None)
     parser.add_argument("--dispatch-kind", default="initial")
 
 
@@ -417,7 +418,7 @@ def _load_manifest(project_root: str, run_manifest: str) -> dict[str, Any]:
 def _load_json(path: Path, label: str) -> dict[str, Any]:
     if not path.is_file():
         raise DispatchError(f"{label} not found: {path}")
-    payload = json.loads(path.read_text(encoding="utf-8"))
+    payload = load_owned_object(path, artifact=label)
     if not isinstance(payload, dict):
         raise DispatchError(f"{label} must be a JSON object: {path}")
     return payload