okstra 0.180.0 → 0.183.2

package/runtime/python/okstra_ctl/git_reconcile.py

@@ -14,6 +14,7 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Dict, List, Optional, Tuple
 
+from .fixed_text import line
 from .worktree import _resolve_commit_sha
 
 
@@ -202,7 +203,7 @@ def guidance(*, plan_run_root: Path, project_id: str, task_group: str,
             f"--task-id {task_id} --work-category {work_category}")
     return ("Recorded stage SHAs no longer match the git history "
             "(external rebase/squash/amend?). Inspect and reconcile:\n"
-            f"  {base} --check --json\n"
+            f"  {base} --check --text\n"
             f"  {base} --apply --stage <N> --use-ref <branch|sha>")
 
 
@@ -272,9 +273,8 @@ def _items_as_json(items: List[StaleItem]) -> list:
              "suggested_commit": i.suggested_commit} for i in items]
 
 
-def main(argv: Optional[list] = None) -> int:
+def _parse_args(argv: Optional[list]):
     import argparse
-    import json as _json
 
     p = argparse.ArgumentParser(
         prog="okstra git-reconcile",
@@ -294,11 +294,44 @@ def main(argv: Optional[list] = None) -> int:
     p.add_argument("--use-ref", default="")
     p.add_argument("--reset-anchor", default="")
     p.add_argument("--json", action="store_true")
+    p.add_argument("--text", action="store_true")
     a = p.parse_args(argv)
     if a.check and a.apply:
         p.error("--check and --apply are mutually exclusive")
     if a.apply and a.stage is not None and not a.use_ref:
         p.error("--stage requires --use-ref (confirm 항목은 명시 ref 로만 보정된다)")
+    return a
+
+
+def _emit_result(payload: dict, *, as_json: bool, as_text: bool) -> None:
+    import json as _json
+
+    print(
+        render_git_reconcile_text(payload)
+        if as_text
+        else _json.dumps(payload, ensure_ascii=False, indent=None if as_json else 2)
+    )
+
+
+def render_git_reconcile_text(payload: dict) -> str:
+    """reconcile 결과의 승인된 분류만 고정 순서로 투영한다."""
+    rows = ["Okstra git reconcile\n"]
+    rows.append(line("Status", "ready" if payload.get("ok", True) else "error"))
+    items = payload.get("items") if isinstance(payload.get("items"), list) else []
+    rows.append(line("Item count", len(items)))
+    for index, item in enumerate(items, 1):
+        if not isinstance(item, dict):
+            continue
+        rows.append(line(f"Item {index} kind", item.get("kind")))
+        rows.append(line(f"Item {index} classification", item.get("classification")))
+        rows.append(line(f"Item {index} reason", item.get("reason")))
+    if "error" in payload:
+        rows.append(line("Failure reason", payload.get("error")))
+    return "".join(rows)
+
+
+def main(argv: Optional[list] = None) -> int:
+    a = _parse_args(argv)
 
     kw = dict(project_root=Path(a.project_root).resolve(),
               plan_run_root=Path(a.plan_run_root).resolve(),
@@ -310,17 +343,16 @@ def main(argv: Optional[list] = None) -> int:
                                      reset_anchor=a.reset_anchor)
             out = {"applied": result["applied"],
                    "remaining_confirm": _items_as_json(result["remaining_confirm"])}
-            print(_json.dumps(out, ensure_ascii=False,
-                              indent=None if a.json else 2))
+            _emit_result(out, as_json=a.json, as_text=a.text)
             return 2 if result["remaining_confirm"] else 0
         items = classify_task(**kw)
         stale = [i for i in items if i.classification != "ok"]
-        print(_json.dumps({"items": _items_as_json(stale)}, ensure_ascii=False,
-                          indent=None if a.json else 2))
+        out = {"items": _items_as_json(stale)}
+        _emit_result(out, as_json=a.json, as_text=a.text)
         return 2 if any(i.classification == "confirm" for i in stale) else 0
     except ReconcileError as exc:
-        print(_json.dumps({"ok": False, "error": str(exc)}, ensure_ascii=False,
-                          indent=None if a.json else 2))
+        out = {"ok": False, "error": str(exc)}
+        _emit_result(out, as_json=a.json, as_text=a.text)
         return 1
 
 

package/runtime/python/okstra_ctl/handoff.py

@@ -15,6 +15,7 @@ from typing import Any, Callable, Dict, List, Optional, Tuple
 from . import consumers, stage_targets, worktree_registry
 from .final_report_paths import final_report_markdown_path
 from .paths import RunRef
+from .json_boundary import JsonBoundaryError, load_owned_object
 from .release_gate import (
     blocking_condition_ids,
     release_handoff_allowed,
@@ -75,8 +76,8 @@ def latest_whole_task_fv_release_ready(project_root, project_id: str,
     for dj in sorted(reports_dir.glob("final-report-*.data.json"),
                      reverse=True):
         try:
-            data = json.loads(dj.read_text(encoding="utf-8"))
-        except (OSError, json.JSONDecodeError):
+            data = load_owned_object(dj, artifact="final verification report")
+        except JsonBoundaryError:
             continue
         if ((data.get("header") or {}).get("taskType") == "final-verification"
                 and data.get("verificationScope") == "whole-task"
@@ -372,8 +373,8 @@ def record_verified(*, plan_run_root, stage: int, report_path: str,
     막는다. 통과 조건은 whole-task 와 같고(`release_gate`), 기록되는 verdict 는
     보고서가 실제로 실은 토큰이다."""
     try:
-        data = json.loads(Path(data_json).read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError) as exc:
+        data = load_owned_object(Path(data_json), artifact="final verification report")
+    except JsonBoundaryError as exc:
         raise HandoffError(f"cannot read final-report data.json: {exc}")
     if (data.get("header") or {}).get("taskType") != "final-verification":
         raise HandoffError("data.json is not a final-verification report")

package/runtime/python/okstra_ctl/i18n.py

@@ -11,6 +11,8 @@ import os
 from pathlib import Path
 from typing import Any, Callable
 
+from .json_boundary import JsonBoundaryError, load_owned_object
+
 SUPPORTED_LANGS = ("en", "ko")
 DICTIONARY_REL = ("templates", "reports", "i18n")
 # The human HTML has its own fixed strings — table headings, empty states,
@@ -48,8 +50,8 @@ def load_dictionary(lang: str, rel: tuple[str, ...] = DICTIONARY_REL) -> dict[st
         )
     path = _i18n_dir(rel) / f"{lang}.json"
     try:
-        return json.loads(path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError) as exc:
+        return load_owned_object(path, artifact="i18n dictionary")
+    except JsonBoundaryError as exc:
         raise I18nError(f"failed to load {path}: {exc}") from exc
 
 

package/runtime/python/okstra_ctl/implementation_direction.py

@@ -20,6 +20,11 @@ from .final_report_schema import (
     load_schema_for_data,
     validate as validate_schema,
 )
+from .json_boundary import (
+    JsonBoundaryError,
+    load_owned_object_snapshot,
+    write_owned_object_atomic,
+)
 from .report_views import normalize_direction_selection_identity
 from .scope_provenance import brief_end_state_id_sequence
 from .user_response import UserResponseError, parse_direction_selection
@@ -139,14 +144,14 @@ def _sibling_data_path(report: Path) -> Path:
     return data_path
 
 
-def _parse_data(data_path: Path, data_bytes: bytes) -> dict[str, Any]:
+def _parse_data(data_path: Path) -> tuple[dict[str, Any], bytes]:
     try:
-        data = json.loads(data_bytes)
-    except (UnicodeError, json.JSONDecodeError) as exc:
+        snapshot = load_owned_object_snapshot(
+            data_path, artifact="implementation option data"
+        )
+    except JsonBoundaryError as exc:
         raise DirectionSelectionError(f"data JSON is invalid: {data_path}") from exc
-    if not isinstance(data, dict):
-        raise DirectionSelectionError("data JSON must contain an object")
-    return data
+    return snapshot.value, snapshot.raw_bytes
 
 
 def _validate_report_identity(data: Mapping[str, Any], expected_task_key: str) -> None:
@@ -342,8 +347,7 @@ def resolve_selected_direction(
     task_root, seq = _selection_layout(report)
     report = validate_task_artifact_path(report, task_root, "report")
     data_path = validate_task_artifact_path(data_path, task_root, "data")
-    data_bytes = data_path.read_bytes()
-    data = _parse_data(data_path, data_bytes)
+    data, data_bytes = _parse_data(data_path)
     _validate_report_identity(data, expected_task_key)
     _validate_schema(data)
     selection = data.get("implementationOptionSelection")
@@ -406,9 +410,10 @@ def write_selected_direction_snapshot(
         "requirementCoverage": list(direction.requirement_coverage),
         "planningInvariants": list(direction.planning_invariants),
     }
-    destination.write_text(
-        json.dumps(payload, ensure_ascii=False, indent=2) + "\n",
-        encoding="utf-8",
+    write_owned_object_atomic(
+        destination,
+        payload,
+        artifact="selected implementation direction",
     )
     return destination
 
@@ -447,13 +452,16 @@ def _load_selected_direction_snapshot(
     task_root = path.parent.parent
     try:
         path = validate_task_artifact_path(path, task_root, "selected direction snapshot")
-        content = path.read_bytes()
-        data = json.loads(content)
+        loaded = load_owned_object_snapshot(
+            path, artifact="selected direction snapshot"
+        )
+        content = loaded.raw_bytes
+        data = loaded.value
     except DirectionSelectionError as exc:
         return None, [str(exc)]
     except OSError as exc:
         return None, [f"selected direction snapshot is unreadable: {exc}"]
-    except (UnicodeError, json.JSONDecodeError) as exc:
+    except (UnicodeError, json.JSONDecodeError, JsonBoundaryError) as exc:
         return None, [f"selected direction snapshot JSON is invalid: {exc}"]
     if not isinstance(data, Mapping):
         return None, ["selected direction snapshot JSON must contain an object"]

package/runtime/python/okstra_ctl/implementation_outcome.py

@@ -15,6 +15,7 @@ from . import next_phase
 from .paths import RunRef, task_manifest_file
 from .stage_map import StageMapError, load_task_stage_map
 from .workflow import PHASE_SEQUENCE
+from .json_boundary import JsonBoundaryError, load_owned_object, write_owned_object_atomic
 
 
 @dataclass(frozen=True)
@@ -114,8 +115,8 @@ def _load_json(path: Path) -> dict[str, Any]:
     if not path.is_file():
         return {}
     try:
-        data = json.loads(path.read_text(encoding="utf-8"))
-    except json.JSONDecodeError:
+        data = load_owned_object(path, artifact="implementation outcome")
+    except JsonBoundaryError:
         return {}
     return data if isinstance(data, dict) else {}
 
@@ -224,8 +225,4 @@ def _update_task_catalog(project_root: Path, manifest: dict[str, Any]) -> bool:
 
 
 def _write_json(path: Path, payload: dict[str, Any]) -> None:
-    path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(
-        json.dumps(payload, ensure_ascii=False, indent=2) + "\n",
-        encoding="utf-8",
-    )
+    write_owned_object_atomic(path, payload, artifact="implementation outcome")

package/runtime/python/okstra_ctl/incremental_carry.py

@@ -12,6 +12,7 @@ from typing import Any, Mapping
 from .convergence_store import write_json_atomic
 from .final_report_schema import load_schema_version
 from .report_narrative import parse_narrative, writer_owned_data
+from .json_boundary import load_owned_object
 
 
 PREP_VERDICT_RE = re.compile(r"^P-Prep-S([1-9][0-9]*)-")
@@ -384,7 +385,7 @@ def _load_data(path: str, *, option: str) -> dict:
     the documented `carry refused:` refusal it knows how to fall back from.
     """
     try:
-        data = json.loads(Path(path).read_text(encoding="utf-8"))
+        data = load_owned_object(Path(path), artifact="incremental carry report")
     except (OSError, ValueError) as exc:
         raise CarryError(f"{option} could not be read: {exc}") from exc
     if not isinstance(data, dict):

package/runtime/python/okstra_ctl/incremental_scope.py

@@ -18,6 +18,7 @@ from pathlib import Path
 from okstra_ctl.final_report_paths import final_report_data_path
 from okstra_ctl.stage_citations import cited_stage_numbers
 from okstra_ctl.stage_targets import downstream_stage_closure
+from okstra_ctl.json_boundary import load_owned_object
 
 CUTOFF_RATIO = 0.5
 
@@ -275,7 +276,7 @@ def preview_link_availability_for_report(
             "reason": f"prior report has no data sibling at {data_path.name}",
         }
     try:
-        data = json.loads(data_path.read_text(encoding="utf-8"))
+        data = load_owned_object(data_path, artifact="incremental scope report")
     except (OSError, ValueError) as exc:
         return {
             "wouldForceFull": True,
@@ -332,7 +333,9 @@ def _preview_result(args) -> dict:
     answer when the input cannot be read.
     """
     try:
-        data = json.loads(Path(args.prev_data).read_text(encoding="utf-8"))
+        data = load_owned_object(
+            Path(args.prev_data), artifact="incremental scope report"
+        )
         answered = {
             token.strip()
             for token in args.answered_clarifications.split(",")
@@ -392,7 +395,9 @@ def main(argv: list[str]) -> int:
         return 0
 
     try:
-        data = json.loads(Path(args.prev_data).read_text(encoding="utf-8"))
+        data = load_owned_object(
+            Path(args.prev_data), artifact="incremental scope report"
+        )
         stages = parse_stage_graph(data)
         impacted = {int(t.strip()) for t in args.impacted.split(",") if t.strip()}
         prep_ids = {t.strip() for t in args.prep_items.split(",") if t.strip()}

package/runtime/python/okstra_ctl/index.py

@@ -1,14 +1,17 @@
 """active/projects 인덱스 행 치환·기록."""
 from __future__ import annotations
 
-import json
 import os
 from pathlib import Path
 
 from .ids import build_run_id
 from .invocation import save_invocation
-from .jsonl import append_jsonl, read_jsonl, remove_jsonl_row, rotate_recent_if_needed
+from .jsonl import (
+    append_jsonl, read_jsonl, remove_jsonl_row, rewrite_jsonl,
+    rotate_recent_if_needed,
+)
 from .project_meta import upsert_project_meta
+from .json_boundary import load_owned_object, write_owned_object_atomic
 from .run_index_row import build_run_index_row, slim_run_row
 
 
@@ -21,11 +24,7 @@ def _replace_or_append_row(path: Path, run_id: str, row: dict) -> None:
         if r.get("runId") == run_id:
             rows[i] = slim
             path.parent.mkdir(parents=True, exist_ok=True)
-            tmp = path.with_suffix(path.suffix + ".tmp")
-            with tmp.open("w") as f:
-                for rr in rows:
-                    f.write(json.dumps(rr, separators=(",", ":")) + "\n")
-            os.replace(tmp, path)
+            rewrite_jsonl(path, rows)
             return
     append_jsonl(path, slim)
 
@@ -156,9 +155,7 @@ def remove_reservation(home: Path, *, project_id: str, task_group: str,
     target = home / "projects" / project_id / "meta.json"
     if not target.is_file():
         return
-    meta = json.loads(target.read_text())
+    meta = load_owned_object(target, artifact="project metadata")
     meta["runCount"] = max(0, int(meta.get("runCount", 0)) - 1)
     meta["activeCount"] = max(0, int(meta.get("activeCount", 0)) - 1)
-    tmp = target.with_suffix(".json.tmp")
-    tmp.write_text(json.dumps(meta, indent=2) + "\n")
-    os.replace(tmp, target)
+    write_owned_object_atomic(target, meta, artifact="project metadata")

package/runtime/python/okstra_ctl/initial_prompt_materialization.py

@@ -24,6 +24,13 @@ from .agent_invocation import (
 )
 from .path_hints import hydrate_active_run_context
 from .report_language import resolve_report_language
+from .report_inputs import report_narrative_path, uses_report_contract_v3
+from .report_synthesis_packet import (
+    ReportSynthesisPacketError,
+    materialize_report_synthesis_packet,
+    report_synthesis_packet_paths,
+)
+from .json_boundary import JsonBoundaryError, load_owned_object
 from .worker_prompt_body import (
     REPORT_WRITER_WORKER_ID,
     analysis_prompt_body,
@@ -444,7 +451,17 @@ def _render_prompt_parts(
             f"**Prompt Delivery Mode:** {context.request.delivery_mode.value}"
         )
         anchors.extend(_implementation_anchor_lines(context, item.plan))
-        body = _prompt_body(context, state, worker, item.plan)
+        synthesis_packet_path = _materialize_report_writer_packet(
+            context,
+            item.plan,
+        )
+        body = _prompt_body(
+            context,
+            state,
+            worker,
+            item.plan,
+            synthesis_packet_path,
+        )
         body.extend(_resource_lines(context, item))
     except InitialPromptMaterializationError:
         raise
@@ -503,7 +520,7 @@ def _agent_invocation_request(
             f"requested model does not match {assignment_ref}",
         )
     anchors, body = _render_prompt_parts(context, item)
-    source_paths = (
+    source_paths = [
         AgentInstructionSource(
             "project",
             _project_relative(context.project_root, context.request.run_manifest_path),
@@ -514,7 +531,10 @@ def _agent_invocation_request(
         AgentInstructionSource(
             "project", _required_string(context.manifest, "teamStatePath")
         ),
-    )
+    ]
+    packet_source = _report_writer_packet_source(context, item.plan)
+    if packet_source is not None:
+        source_paths.append(packet_source)
     invocation_id = _worker_invocation_id(context.manifest, item.worker.worker_id)
     return AgentInvocationRequest(
         invocation_id=invocation_id,
@@ -526,7 +546,7 @@ def _agent_invocation_request(
         instruction=AgentInstruction(
             anchor_lines=tuple(anchors),
             body="\n".join(body).rstrip() + "\n",
-            source_paths=source_paths,
+            source_paths=tuple(source_paths),
         ),
         project_root=context.project_root,
         run_manifest_path=context.request.run_manifest_path,
@@ -549,6 +569,7 @@ def _prompt_body(
     state: Mapping[str, Any],
     worker: InitialPromptWorkerRequest,
     plan: PromptPlan,
+    synthesis_packet_path: str = "",
 ) -> list[str]:
     if plan.audience == "report-writer":
         return report_writer_prompt_body(
@@ -561,6 +582,7 @@ def _prompt_body(
                 context.manifest,
                 context.active_context,
             ),
+            synthesis_packet_path,
         )
     return analysis_prompt_body(
         context.manifest,
@@ -571,6 +593,56 @@ def _prompt_body(
     )
 
 
+def _report_writer_narrative_path(context: _MaterializationContext) -> Path:
+    return report_narrative_path(context.project_root, context.manifest)
+
+
+def _report_writer_packet_source(
+    context: _MaterializationContext,
+    plan: PromptPlan,
+) -> AgentInstructionSource | None:
+    if (
+        plan.audience != "report-writer"
+        or not uses_report_contract_v3(context.manifest)
+    ):
+        return None
+    _, markdown_path = report_synthesis_packet_paths(
+        _report_writer_narrative_path(context)
+    )
+    return AgentInstructionSource(
+        "project",
+        _project_relative(context.project_root, markdown_path),
+    )
+
+
+def _materialize_report_writer_packet(
+    context: _MaterializationContext,
+    plan: PromptPlan,
+) -> str:
+    packet_source = _report_writer_packet_source(context, plan)
+    if packet_source is None:
+        return ""
+    try:
+        _, markdown_path = materialize_report_synthesis_packet(
+            project_root=context.project_root,
+            manifest=context.manifest,
+            active_context=context.active_context,
+            team_state=context.team_state,
+            narrative_path=_report_writer_narrative_path(context),
+        )
+    except ReportSynthesisPacketError as exc:
+        defects = "; ".join(
+            f"owner={issue.owner} source={issue.label} path={issue.path} "
+            f"reason={issue.reason}"
+            for issue in exc.issues
+        )
+        raise InitialPromptMaterializationError(
+            "required_input_missing",
+            f"report synthesis packet contract defects: {defects}",
+        ) from exc
+    return _project_relative(context.project_root, markdown_path)
+
+
 def _resource_lines(
     context: _MaterializationContext,
     item: _PromptItem,
@@ -1325,12 +1397,12 @@ def _load_referenced_json(
 
 def _load_json_object(path: Path, label: str) -> Mapping[str, Any]:
     try:
-        payload = json.loads(path.read_text(encoding="utf-8"))
-    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        payload = load_owned_object(path, artifact=label)
+    except JsonBoundaryError as exc:
         raise InitialPromptMaterializationError(
             "required_input_missing",
             f"cannot load {label}: {path}: {exc}",
-        ) from exc
+        ) from (exc.__cause__ or exc)
     if not isinstance(payload, dict):
         raise InitialPromptMaterializationError(
             "required_input_missing",

package/runtime/python/okstra_ctl/invocation.py

@@ -7,6 +7,7 @@ from pathlib import Path
 from typing import Optional
 
 from .ids import _safe_fs_segment
+from .json_boundary import load_owned_object, write_owned_object_atomic
 
 
 def invocation_path(home: Path, project_id: str,
@@ -32,11 +33,7 @@ def save_invocation(home: Path, project_id: str,
                     run_seq: int, payload: dict) -> None:
     """invocation 을 원자적으로 저장(임시파일 + os.replace)."""
     target = invocation_path(home, project_id, task_group, task_id, task_type, run_seq)
-    target.parent.mkdir(parents=True, exist_ok=True)
-    tmp = target.with_suffix(".json.tmp")
-    tmp.write_text(json.dumps(payload, indent=2) + "\n")
-    os.chmod(tmp, 0o600)
-    os.replace(tmp, target)
+    write_owned_object_atomic(target, payload, artifact="invocation metadata")
 
 
 def load_invocation(home: Path, project_id: str,
@@ -46,4 +43,4 @@ def load_invocation(home: Path, project_id: str,
     target = invocation_path(home, project_id, task_group, task_id, task_type, run_seq)
     if not target.is_file():
         return None
-    return json.loads(target.read_text())
+    return load_owned_object(target, artifact="invocation metadata")