okstra 0.179.2 → 0.183.2

package/runtime/python/okstra_ctl/mutation_probe.py

@@ -85,6 +85,7 @@ from .self_mock_signals import (
     partition_waived_entries,
     selfmock_path_key,
 )
+from .json_boundary import JsonBoundaryError, external_tool_json_source, load_external_json
 
 # `survived` is read by a human in the sidecar, so it is trimmed. The verdict and
 # the logged total are taken before the trim — the cap shortens the report, never
@@ -414,8 +415,12 @@ class StrykerAdapter:
         if not path.is_file():
             return None
         try:
-            return json.loads(path.read_text(encoding="utf-8"))
-        except (OSError, json.JSONDecodeError):
+            # 외부 입력: mutation testing 도구가 생성한 실행 보고서다.
+            return load_external_json(
+                external_tool_json_source(path, Path(worktree) if worktree else Path.cwd()),
+                artifact="mutation test report",
+            )
+        except JsonBoundaryError:
             return None
 
 
@@ -1004,8 +1009,12 @@ class CargoMutantsAdapter:
         if not path.is_file():
             return None
         try:
-            data = json.loads(path.read_text(encoding="utf-8"))
-        except (OSError, json.JSONDecodeError):
+            # 외부 입력: mutation testing 도구가 생성한 실행 보고서다.
+            data = load_external_json(
+                external_tool_json_source(path, Path(worktree) if worktree else Path.cwd()),
+                artifact="mutation test report",
+            )
+        except JsonBoundaryError:
             return None
         return data if isinstance(data, dict) else None
 

package/runtime/python/okstra_ctl/pane_reclaim.py

@@ -18,6 +18,7 @@ import sys
 from pathlib import Path
 
 from .dispatch_state import NON_TERMINAL_WORKER_STATUSES
+from .json_boundary import JsonBoundaryError, load_owned_object
 
 
 def _newest_team_state(state_dir: Path) -> Path | None:
@@ -33,8 +34,8 @@ def _newest_team_state(state_dir: Path) -> Path | None:
 
 def _has_live_dispatch(team_state_path: Path) -> bool:
     try:
-        payload = json.loads(team_state_path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError):
+        payload = load_owned_object(team_state_path, artifact="team state")
+    except JsonBoundaryError:
         return False
     if not isinstance(payload, dict):
         return False

package/runtime/python/okstra_ctl/path_hints.py

@@ -439,6 +439,10 @@ def _run_files(
         "codex_worker_result": worker_results / f"codex-worker{suffixes['worker_results']}.md",
         "antigravity_worker_result": worker_results / f"antigravity-worker{suffixes['worker_results']}.md",
         "report_writer_worker_result": worker_results / f"report-writer-worker{suffixes['worker_results']}.md",
+        "report_writer_narrative": worker_results / f"report-writer-narrative{suffixes['worker_results']}.md",
+        "approval_decisions": run_state / f"approval-decisions-{task_type_segment}-{sequences['state']}.json",
+        "design_preparation": run_state / f"design-preparation-{task_type_segment}-{sequences['state']}.json",
+        "plan_body_verification": run_state / f"plan-body-verification-{task_type_segment}-{sequences['state']}.json",
         "run_errors_log": run_logs / f"errors-{task_type_segment}-{sequences['state']}.jsonl",
         "claude_worker_errors_sidecar": worker_results / f"claude-worker-errors{suffixes['worker_results']}.json",
         "codex_worker_errors_sidecar": worker_results / f"codex-worker-errors{suffixes['worker_results']}.json",
@@ -570,6 +574,10 @@ def _absolute_worker_fields(paths: Mapping[str, Any]) -> dict[str, str]:
         "CODEX_WORKER_RESULT_FILE": str(paths["codex_worker_result"]),
         "ANTIGRAVITY_WORKER_RESULT_FILE": str(paths["antigravity_worker_result"]),
         "REPORT_WRITER_WORKER_RESULT_FILE": str(paths["report_writer_worker_result"]),
+        "REPORT_WRITER_NARRATIVE_FILE": str(paths["report_writer_narrative"]),
+        "APPROVAL_DECISIONS_PATH": str(paths["approval_decisions"]),
+        "DESIGN_PREPARATION_PATH": str(paths["design_preparation"]),
+        "PLAN_BODY_VERIFICATION_STATE_PATH": str(paths["plan_body_verification"]),
         "CLAUDE_WORKER_ERRORS_SIDECAR_PATH": str(paths["claude_worker_errors_sidecar"]),
         "CODEX_WORKER_ERRORS_SIDECAR_PATH": str(paths["codex_worker_errors_sidecar"]),
         "ANTIGRAVITY_WORKER_ERRORS_SIDECAR_PATH": str(paths["antigravity_worker_errors_sidecar"]),
@@ -670,6 +678,10 @@ def _relative_file_fields(project_root: Path, paths: Mapping[str, Any]) -> dict[
         "CODEX_WORKER_RESULT_RELATIVE_PATH": _rel(project_root, paths["codex_worker_result"]),
         "ANTIGRAVITY_WORKER_RESULT_RELATIVE_PATH": _rel(project_root, paths["antigravity_worker_result"]),
         "REPORT_WRITER_WORKER_RESULT_RELATIVE_PATH": _rel(project_root, paths["report_writer_worker_result"]),
+        "REPORT_WRITER_NARRATIVE_RELATIVE_PATH": _rel(project_root, paths["report_writer_narrative"]),
+        "APPROVAL_DECISIONS_RELATIVE_PATH": _rel(project_root, paths["approval_decisions"]),
+        "DESIGN_PREPARATION_RELATIVE_PATH": _rel(project_root, paths["design_preparation"]),
+        "PLAN_BODY_VERIFICATION_STATE_RELATIVE_PATH": _rel(project_root, paths["plan_body_verification"]),
         "RUN_ERRORS_LOG_RELATIVE_PATH": _rel(project_root, paths["run_errors_log"]),
         "CLAUDE_WORKER_ERRORS_SIDECAR_RELATIVE_PATH": _rel(project_root, paths["claude_worker_errors_sidecar"]),
         "CODEX_WORKER_ERRORS_SIDECAR_RELATIVE_PATH": _rel(project_root, paths["codex_worker_errors_sidecar"]),

package/runtime/python/okstra_ctl/paths.py

@@ -552,6 +552,9 @@ def compute_run_paths(
     team_state = run_state / f"team-state{suffixes['state']}.json"
     active_run_context = run_state / f"active-run-context{suffixes['state']}.json"
     lead_events = run_state / f"lead-events-{task_type_segment}-{seqs['state']}.jsonl"
+    convergence_state = (
+        run_state / f"convergence-{task_type_segment}-{seqs['state']}.json"
+    )
     final_report_template = instruction_set / "final-report-template.md"
     final_report_schema = instruction_set / "final-report-schema.json"
     reference_expectations = instruction_set / "reference-expectations.md"
@@ -562,6 +565,10 @@ def compute_run_paths(
     codex_worker_result = worker_results / f"codex-worker{suffixes['worker_results']}.md"
     antigravity_worker_result = worker_results / f"antigravity-worker{suffixes['worker_results']}.md"
     report_writer_worker_result = worker_results / f"report-writer-worker{suffixes['worker_results']}.md"
+    report_writer_narrative = worker_results / f"report-writer-narrative{suffixes['worker_results']}.md"
+    approval_decisions = run_state / f"approval-decisions-{task_type_segment}-{seqs['state']}.json"
+    design_preparation = run_state / f"design-preparation-{task_type_segment}-{seqs['state']}.json"
+    plan_body_verification = run_state / f"plan-body-verification-{task_type_segment}-{seqs['state']}.json"
 
     run_errors_log = run_logs / f"errors-{task_type_segment}-{seqs['state']}.jsonl"
     runtime_home = okstra_home()
@@ -667,6 +674,11 @@ def compute_run_paths(
         "CODEX_WORKER_RESULT_FILE": str(codex_worker_result),
         "ANTIGRAVITY_WORKER_RESULT_FILE": str(antigravity_worker_result),
         "REPORT_WRITER_WORKER_RESULT_FILE": str(report_writer_worker_result),
+        "REPORT_WRITER_NARRATIVE_FILE": str(report_writer_narrative),
+        "APPROVAL_DECISIONS_PATH": str(approval_decisions),
+        "DESIGN_PREPARATION_PATH": str(design_preparation),
+        "CONVERGENCE_STATE_PATH": str(convergence_state),
+        "PLAN_BODY_VERIFICATION_STATE_PATH": str(plan_body_verification),
         "RUN_ERRORS_LOG_PATH": str(run_errors_log),
         "CLAUDE_WORKER_ERRORS_SIDECAR_PATH": str(claude_worker_errors_sidecar),
         "CODEX_WORKER_ERRORS_SIDECAR_PATH": str(codex_worker_errors_sidecar),
@@ -724,6 +736,11 @@ def compute_run_paths(
         ("FINAL_REPORT_RECORD_RELATIVE_PATH", final_report),
         ("FINAL_STATUS_RELATIVE_PATH", final_status),
         ("TEAM_STATE_RELATIVE_PATH", team_state),
+        # `render.py` 가 이 키로 매니페스트의 `convergenceStatePath` 를 채운다.
+        # `path_hints` 만 내보내던 동안 그 필드가 빈 문자열로 렌더돼,
+        # `report-finalize` 가 "report contract 3.0 requires convergenceStatePath"
+        # 로 죽었다 — 수렴 상태 파일 자체는 정상 생성돼 있었다.
+        ("CONVERGENCE_STATE_RELATIVE_PATH", convergence_state),
         ("ACTIVE_RUN_CONTEXT_RELATIVE_PATH", active_run_context),
         ("LEAD_EVENTS_RELATIVE_PATH", lead_events),
         ("WORKER_RESULTS_RELATIVE_PATH", worker_results),
@@ -737,6 +754,10 @@ def compute_run_paths(
         ("CODEX_WORKER_RESULT_RELATIVE_PATH", codex_worker_result),
         ("ANTIGRAVITY_WORKER_RESULT_RELATIVE_PATH", antigravity_worker_result),
         ("REPORT_WRITER_WORKER_RESULT_RELATIVE_PATH", report_writer_worker_result),
+        ("REPORT_WRITER_NARRATIVE_RELATIVE_PATH", report_writer_narrative),
+        ("APPROVAL_DECISIONS_RELATIVE_PATH", approval_decisions),
+        ("DESIGN_PREPARATION_RELATIVE_PATH", design_preparation),
+        ("PLAN_BODY_VERIFICATION_STATE_RELATIVE_PATH", plan_body_verification),
         ("RUN_ERRORS_LOG_RELATIVE_PATH", run_errors_log),
         ("CLAUDE_WORKER_ERRORS_SIDECAR_RELATIVE_PATH", claude_worker_errors_sidecar),
         ("CODEX_WORKER_ERRORS_SIDECAR_RELATIVE_PATH", codex_worker_errors_sidecar),

package/runtime/python/okstra_ctl/plan_items.py

@@ -1,6 +1,7 @@
 """Deterministic extraction of implementation-planning verification items."""
 from __future__ import annotations
 
+import re
 from collections.abc import Mapping
 from copy import deepcopy
 from typing import Any
@@ -50,6 +51,87 @@ def _non_empty_string(value: object) -> str | None:
     return None
 
 
+# 자연키가 있는 소스. 이 필드는 요소의 *정체*이지 내용이 아니다 — 명령이나 문구를 고쳐도
+# 같은 요소로 남고, 앞의 형제가 지워져도 값이 변하지 않는다.
+_NATURAL_KEY_FIELDS: dict[str, tuple[str, ...]] = {
+    "optionCandidates": ("name",),
+    "dependencyMigrationRisk": ("id",),
+    "validationChecklist": ("id",),
+    "rollbackStrategy": ("id",),
+    "requirementCoverage": ("id", "originalRequirementId"),
+}
+
+
+def _element_key(value: str) -> str:
+    return re.sub(r"[^a-z0-9]+", "-", value.strip().lower()).strip("-")
+
+
+def _element_id(kind: str, key: str, fallback: str) -> str:
+    """이 요소의 안정 식별자. 자연키가 없으면 위치 id 로 떨어진다.
+
+    `P-Opt-N` / `P-Val-N` / `P-Req-N` 같은 위치 id 는 서수라, 자기수정이 요소
+    하나를 지우면 뒤가 전부 밀린다 — 재작성 전의 `P-Req-16` 과 후의 `P-Req-16` 이
+    같은 요소라는 보장이 없다(`prompts/lead/plan-body-verification.md` §7). 그래서
+    라운드나 run 을 가로질러 판정을 이월할 수 없고, 검증 표면이 매번 전체로
+    돌아간다.
+
+    `elementId` 는 그 대조를 가능하게 한다. 위치가 아니라 요소가 스스로 지닌
+    이름(`R-001`, `VC-011`, 스테이지·스텝 좌표)에서 만들어지므로 형제의 삭제에
+    영향받지 않는다. 표시와 인용은 계속 `id` 를 쓴다 — 이 값은 대조용이다.
+
+    자연키가 없는 소스는 위치 id 로 떨어지고, 그 항목은 삭제를 가로질러 안정하지
+    않다. 소비자는 `elementId == id` 인 항목을 그렇게 다뤄야 한다.
+    """
+    normalized = _element_key(key)
+    return f"{kind}:{normalized}" if normalized else fallback
+
+
+# 자기 기록 블록. 계획은 실행 지시와 그 실행의 감사 기록을 한 산출물에 담는데,
+# 게이트가 둘을 구분하지 않으면 기록의 부정확이 구현 착수를 막는다 — 실측 run 에서
+# 남은 차단 4건이 전부 "사용자가 내린 결정을 계획이 정확히 반영했는가" 였다.
+#
+# 커버리지 행이 유일한 기록 항목이다. 승인 처분과 decision 참조는 그 행의 필드이고,
+# 나머지 소스는 전부 무엇을 어떻게 만드는지를 말한다.
+_RECORD_SOURCES = frozenset({"requirementCoverage"})
+
+
+def _item_block(source: str) -> str:
+    return "record" if source in _RECORD_SOURCES else "execution"
+
+
+def _stage_scope(row: Mapping[str, Any] | None, *coordinates: int) -> list[int] | None:
+    """이 항목이 걸리는 스테이지. 어디에도 안 걸리면 ``None``.
+
+    게이트 범위를 다음 실행 스테이지로 좁히려면 항목마다 이 값이 있어야 한다.
+    스텝과 design-prep 은 id 자체가 좌표를 지니지만, 커버리지 행과 검증 행은
+    `stageRefs` 를 실어야 알 수 있다 — 그 전에는 `coveredBy` 산문을 정규식으로
+    읽는 수밖에 없었고, 그것은 게이트 판정의 근거가 되지 못한다.
+
+    ``None`` 은 "스테이지에 걸리지 않는다" 이고, 소비처는 이를 **모든 스테이지에
+    적용** 으로 읽는다. 그게 안전한 쪽이고 지금 동작과 같다. `P-Opt-*` 처럼 계획
+    전체의 성격을 판정하는 항목이 여기 해당하고, `stageRefs` 를 아직 안 쓰는 계획도
+    같은 자리로 떨어진다.
+    """
+    if coordinates:
+        return [int(value) for value in coordinates]
+    refs = (row or {}).get("stageRefs")
+    if not isinstance(refs, list):
+        return None
+    stages = [
+        value for value in refs
+        if isinstance(value, int) and not isinstance(value, bool) and value >= 1
+    ]
+    return stages or None
+
+
+def _natural_element_id(source: str, prefix: str, row: Mapping[str, Any], item_id: str) -> str:
+    for field in _NATURAL_KEY_FIELDS.get(source, ()):
+        value = _non_empty_string(row.get(field))
+        if value is not None:
+            return _element_id(prefix.removeprefix("P-").lower(), value, item_id)
+    return item_id
+
+
 def _subject(row: Mapping[str, Any], source: str) -> str:
     for field in _SUBJECT_FIELDS[source]:
         value = _non_empty_string(row.get(field))
@@ -77,6 +159,11 @@ def _row_payload(row: Mapping[str, Any], **coordinates: int) -> dict[str, Any]:
 def _add_item(items: list[dict[str, Any]], item: dict[str, Any]) -> None:
     if any(existing["id"] == item["id"] for existing in items):
         raise PlanItemContractError(f"duplicate plan item ID: {item['id']}")
+    element_id = item.get("elementId")
+    if element_id and any(existing.get("elementId") == element_id for existing in items):
+        # 두 요소가 같은 자연키를 쓰면 이월이 엉뚱한 항목에 붙는다. 위치 id 가
+        # 갈라져 있어도 대조는 elementId 로 하므로 여기서 막는다.
+        raise PlanItemContractError(f"duplicate plan element ID: {element_id}")
     items.append(item)
 
 
@@ -115,6 +202,9 @@ def _extract_standard_items(planning: Mapping[str, Any]) -> list[dict[str, Any]]
             items,
             {
                 "id": "P-Dir-1",
+                "elementId": "dir:selected-direction",
+                "stageScope": None,
+                "block": "execution",
                 "subject": _non_empty_string(realization.get("goal"))
                 or "Selected direction realization",
                 "sourceSection": "Selected Direction",
@@ -127,10 +217,14 @@ def _extract_standard_items(planning: Mapping[str, Any]) -> list[dict[str, Any]]
             _extract_step_items(planning, items, prefix, section)
             continue
         for index, row in enumerate(_rows(planning, source), start=1):
+            item_id = f"{prefix}-{index}"
             _add_item(
                 items,
                 {
-                    "id": f"{prefix}-{index}",
+                    "id": item_id,
+                    "elementId": _natural_element_id(source, prefix, row, item_id),
+                    "stageScope": _stage_scope(row),
+                    "block": _item_block(source),
                     "subject": _subject(row, source),
                     "sourceSection": section,
                     "ticketId": _ticket_id(row),
@@ -151,8 +245,11 @@ def _extract_step_items(
             _add_item(
                 items,
                 {
+                    # 평면 배열에는 좌표가 없어 위치 id 로 떨어진다.
                     "id": f"{prefix}-{index}",
-                    "subject": _subject(row, "stepwiseExecution"),
+                    "elementId": f"{prefix}-{index}",
+                    "stageScope": _stage_scope(row),
+                    "block": "execution",                    "subject": _subject(row, "stepwiseExecution"),
                     "sourceSection": section,
                     "ticketId": _ticket_id(row),
                     "payload": _row_payload(row),
@@ -172,6 +269,9 @@ def _extract_step_items(
                 items,
                 {
                     "id": f"{prefix}-{stage_number}.{step_number}",
+                    "elementId": f"step:{stage_number}.{step_number}",
+                    "stageScope": _stage_scope(None, stage_number),
+                    "block": "execution",
                     "subject": _subject(row, "stepwiseExecution"),
                     "sourceSection": section,
                     "ticketId": _ticket_id(row),
@@ -212,6 +312,9 @@ def _extract_prep_items(
             items,
             {
                 "id": item_id,
+                "elementId": f"prep:{trigger.stage}:{_element_key(trigger.kind)}",
+                "stageScope": _stage_scope(None, trigger.stage),
+                "block": "execution",
                 "subject": f"Stage {trigger.stage} {trigger.kind} design preparation",
                 "sourceSection": "5.5.10",
                 "ticketId": "",
@@ -243,7 +346,9 @@ def _extract_variation_point_items(
             items,
             {
                 "id": "P-Var-0",
-                "subject": "No variation point declared",
+                "elementId": "var:none",
+                "stageScope": None,
+                "block": "execution",                "subject": "No variation point declared",
                 "sourceSection": "5.5.11",
                 "ticketId": "",
                 "payload": _row_payload(dict(analysis)),
@@ -259,7 +364,13 @@ def _extract_variation_point_items(
             items,
             {
                 "id": f"P-Var-{index}",
-                "subject": _non_empty_string(point.get("behavior"))
+                "elementId": _element_id(
+                    "var",
+                    _non_empty_string(point.get("behavior")) or "",
+                    f"P-Var-{index}",
+                ),
+                "stageScope": None,
+                "block": "execution",                "subject": _non_empty_string(point.get("behavior"))
                 or f"variation point {index}",
                 "sourceSection": "5.5.11",
                 "ticketId": "",