okstra 0.179.2 → 0.183.2

package/runtime/python/okstra_ctl/fixed_text.py

@@ -0,0 +1,39 @@
+"""모델용 고정 텍스트 투영의 scalar 줄 형식을 공유한다."""
+from __future__ import annotations
+
+import re
+
+
+def scalar(value: object) -> str:
+    """복합 값과 Markdown 줄 삽입을 노출하지 않는 scalar 문자열이다."""
+    if value is None or value == "" or not isinstance(value, (str, int, float, bool)):
+        return "-"
+    text = str(value).replace("`", "\\`").replace("\n", " ").replace("\r", " ")
+    return re.sub(
+        r"[\x00-\x09\x0b\x0c\x0e-\x1f\x7f-\x9f\u2028\u2029]",
+        lambda match: f"\\u{ord(match.group(0)):04X}",
+        text,
+    )
+
+
+def line(label: str, value: object) -> str:
+    """한 scalar를 Markdown 목록 한 줄로 렌더한다."""
+    if not re.fullmatch(r"[A-Za-z][A-Za-z0-9 ()/.-]*", label):
+        raise ValueError("fixed text label must be a static single-line label")
+    return f"- {label}: `{scalar(value)}`\n"
+
+
+def value_lines(label: str, value: object) -> list[str]:
+    """JSON 모양의 복합 값을 이름/순서/값 고정 줄로 손실 없이 펼친다."""
+    if isinstance(value, dict):
+        rows = [line(f"{label} field count", len(value))]
+        for index, (name, child) in enumerate(value.items(), 1):
+            rows.append(line(f"{label} field {index} name", name))
+            rows.extend(value_lines(f"{label} field {index} value", child))
+        return rows
+    if isinstance(value, list):
+        rows = [line(f"{label} item count", len(value))]
+        for index, child in enumerate(value, 1):
+            rows.extend(value_lines(f"{label} item {index}", child))
+        return rows
+    return [line(label, value)]

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

@@ -7,9 +7,16 @@ import json
 import re
 import sys
 from pathlib import Path
+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]*)-")
+STEP_VERDICT_RE = re.compile(r"^P-Step-([1-9][0-9]*)\.")
 
 
 class CarryError(Exception):
@@ -290,6 +297,78 @@ def merge_carried_forward(
     return cur
 
 
+def _plan_item_stage(item: Mapping[str, Any]) -> int | None:
+    item_id = str(item.get("id") or "")
+    for pattern in (PREP_VERDICT_RE, STEP_VERDICT_RE):
+        match = pattern.match(item_id)
+        if match:
+            return int(match.group(1))
+    return None
+
+
+def _writer_stage_rows(data: Mapping[str, Any], *, snapshot: str) -> dict[int, dict]:
+    planning = _planning(dict(writer_owned_data(data)))
+    return _stage_rows(planning, snapshot=snapshot)
+
+
+def merge_v3_plan_state(
+    prev: dict[str, Any],
+    narrative: dict[str, Any],
+    state: dict[str, Any],
+    *,
+    prev_seq: str,
+    carry_stages: set[int],
+    reverify_stages: set[int],
+) -> dict[str, Any]:
+    """이전 판정 중 이월 스테이지 소유분만 v3 수렴 상태에 복사한다."""
+    prev_stages = _writer_stage_rows(prev, snapshot="prior")
+    cur_stages = _stage_rows(_planning(narrative), snapshot="current")
+    _validate_stage_sets(prev_stages, cur_stages, carry_stages, reverify_stages)
+    for stage in sorted(carry_stages):
+        current = cur_stages.get(stage)
+        if current is None:
+            raise CarryError(f"carry stage {stage} is missing from current narrative")
+        if _canonical(prev_stages[stage]) != _canonical(current):
+            raise CarryError(f"carry stage {stage} changed in current narrative")
+
+    prev_items = _indexed_rows(
+        _planning(prev).get("planBodyVerification", {}).get("planItems", []),
+        key="id",
+        label="prior planItems",
+    )
+    state_items = _indexed_rows(
+        state.get("planBodyVerification", {}).get("planItems", []),
+        key="id",
+        label="current state planItems",
+    )
+    for item_id, current in state_items.items():
+        stage = _plan_item_stage(current)
+        if stage not in carry_stages:
+            continue
+        previous = prev_items.get(item_id)
+        if previous is None:
+            raise CarryError(f"carry-owned plan item {item_id} is missing from prior report")
+        for field in ("subject", "sourceSection"):
+            if current.get(field) != previous.get(field):
+                raise CarryError(f"carry-owned plan item {item_id} changed {field}")
+        carried = copy.deepcopy(previous)
+        carried["carriedForwardFromSeq"] = str(prev_seq)
+        state_items[item_id] = carried
+
+    prior_carried_ids = {
+        item_id
+        for item_id, item in prev_items.items()
+        if _plan_item_stage(item) in carry_stages
+    }
+    missing = sorted(prior_carried_ids - set(state_items))
+    if missing:
+        raise CarryError(f"current state omitted carry-owned plan items: {missing}")
+    state["planBodyVerification"]["planItems"] = [
+        state_items[item_id] for item_id in sorted(state_items)
+    ]
+    return state
+
+
 def _parse_stage_csv(value: str | None, *, option: str) -> set[int] | None:
     if value is None:
         return None
@@ -306,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):
@@ -317,33 +396,67 @@ def _load_data(path: str, *, option: str) -> dict:
 def main(argv: list[str]) -> int:
     ap = argparse.ArgumentParser(prog="okstra incremental-carry")
     ap.add_argument("--prev-data", required=True, help="prior run final-report data.json")
-    ap.add_argument("--cur-data", required=True, help="current incremental re-run data.json")
+    current = ap.add_mutually_exclusive_group(required=True)
+    current.add_argument("--cur-data", help="historical v2 current data.json")
+    current.add_argument("--cur-narrative", help="contract v3 current narrative Markdown")
+    ap.add_argument("--state", help="contract v3 convergence-owned plan state")
     ap.add_argument("--prev-seq", required=True, help="prior run seq, tagged onto carried items")
     ap.add_argument("--carry-stages", default=None, help="comma-separated carried stage numbers")
     ap.add_argument("--reverify-stages", default=None, help="comma-separated reverified stage numbers")
-    ap.add_argument("--out", required=True, help="path to write the merged data.json")
+    ap.add_argument("--out", help="historical v2 merged data.json path")
+    ap.add_argument("--out-state", help="contract v3 merged plan state path")
     args = ap.parse_args(argv)
 
     try:
         prev = _load_data(args.prev_data, option="--prev-data")
-        cur = _load_data(args.cur_data, option="--cur-data")
-        merged = merge_carried_forward(
-            prev,
-            cur,
-            prev_seq=args.prev_seq,
-            carry_stages=_parse_stage_csv(args.carry_stages, option="--carry-stages"),
-            reverify_stages=_parse_stage_csv(
-                args.reverify_stages, option="--reverify-stages",
-            ),
+        carry_stages = _parse_stage_csv(args.carry_stages, option="--carry-stages")
+        reverify_stages = _parse_stage_csv(
+            args.reverify_stages, option="--reverify-stages",
         )
-    except CarryError as exc:
+        if args.cur_narrative:
+            if not args.state or not args.out_state or args.out:
+                raise CarryError(
+                    "--cur-narrative requires --state and --out-state, and forbids --out"
+                )
+            if carry_stages is None or reverify_stages is None:
+                raise CarryError("contract v3 carry requires both stage sets")
+            try:
+                narrative = parse_narrative(
+                    Path(args.cur_narrative).read_text(encoding="utf-8"),
+                    load_schema_version("3.0"),
+                )
+            except (OSError, UnicodeError, ValueError) as exc:
+                raise CarryError(f"--cur-narrative could not be read: {exc}") from exc
+            state = _load_data(args.state, option="--state")
+            merged = merge_v3_plan_state(
+                prev,
+                narrative,
+                state,
+                prev_seq=args.prev_seq,
+                carry_stages=carry_stages,
+                reverify_stages=reverify_stages,
+            )
+            output = Path(args.out_state)
+        else:
+            if not args.out or args.out_state or args.state:
+                raise CarryError(
+                    "--cur-data requires --out, and forbids --state and --out-state"
+                )
+            cur = _load_data(args.cur_data, option="--cur-data")
+            merged = merge_carried_forward(
+                prev,
+                cur,
+                prev_seq=args.prev_seq,
+                carry_stages=carry_stages,
+                reverify_stages=reverify_stages,
+            )
+            output = Path(args.out)
+    except (CarryError, KeyError, TypeError) as exc:
         print(f"carry refused: {exc}", file=sys.stderr)
         return 1
 
     try:
-        Path(args.out).write_text(
-            json.dumps(merged, ensure_ascii=False, indent=2) + "\n", encoding="utf-8"
-        )
+        write_json_atomic(output, merged)
     except OSError as exc:
         print(f"carry refused: --out could not be written: {exc}", file=sys.stderr)
         return 1
@@ -354,7 +467,7 @@ def main(argv: list[str]) -> int:
         .get("planItems", [])
         if item.get("carriedForwardFromSeq") == str(args.prev_seq)
     )
-    print(f"merged {carried} carried-forward plan item(s) from seq {args.prev_seq} -> {args.out}")
+    print(f"merged {carried} carried-forward plan item(s) from seq {args.prev_seq} -> {output}")
     return 0
 
 

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
 
@@ -207,7 +208,10 @@ def stages_for_clarification(data: dict, clarification_id: str) -> set[int]:
     )
     stages = _stages_blocked_on(planning.get("requirementCoverage"), clarification_id)
     for item in plan_items if isinstance(plan_items, list) else []:
-        if isinstance(item, dict) and item.get("clarificationId") == clarification_id:
+        if isinstance(item, dict) and (
+            item.get("clarificationId") == clarification_id
+            or clarification_id in (item.get("clarificationRefs") or [])
+        ):
             stages |= _plan_item_stages(item)
     return stages
 
@@ -272,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,
@@ -329,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(",")
@@ -389,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")