okstra 0.180.0 → 0.183.2

package/runtime/python/okstra_ctl/report_finalize.py

@@ -45,6 +45,7 @@ from .dispatch_state import DispatchError, link_agent_dispatch_result
 from .final_report_paths import final_report_data_path, final_report_markdown_path
 from .paths import task_dir, task_manifest_file
 from .release_gate import release_handoff_allowed
+from .json_boundary import JsonBoundaryError, load_owned_object, write_owned_object_atomic
 from .stage_integrate import IntegrateError
 from .stage_targets import (
     StageTargetError,
@@ -389,8 +390,8 @@ def _teardown_stage_worktrees(
     if ctx.task_type != "final-verification":
         return _done({"skipped": "not a final-verification run"})
     try:
-        data = json.loads(Path(ctx.data_path).read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError) as exc:
+        data = load_owned_object(Path(ctx.data_path), artifact="final report record")
+    except JsonBoundaryError as exc:
         return subprocess.CompletedProcess(
             command, 1, "", f"cannot read final-report data.json: {exc}")
     if data.get("verificationScope") != "whole-task":
@@ -563,9 +564,7 @@ def write_execution_roles(ctx: FinalizeContext) -> None:
     updated = apply_execution_roles(dict(data), dict(manifest))
     if updated == data:
         return
-    tmp = ctx.data_path.with_suffix(ctx.data_path.suffix + ".tmp")
-    tmp.write_text(json.dumps(updated, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
-    tmp.replace(ctx.data_path)
+    write_owned_object_atomic(ctx.data_path, updated, artifact="final report record")
 
 
 def _link_lead_result_for_validation(ctx: FinalizeContext) -> None:
@@ -604,11 +603,9 @@ def _link_lead_result_for_validation(ctx: FinalizeContext) -> None:
 
 def _load_manifest(path: Path) -> Mapping[str, Any]:
     try:
-        payload = json.loads(path.read_text(encoding="utf-8"))
-    except FileNotFoundError as exc:
-        raise FinalizeError(f"run manifest not found: {path}") from exc
-    except json.JSONDecodeError as exc:
-        raise FinalizeError(f"run manifest is not valid JSON: {path} ({exc})") from exc
+        payload = load_owned_object(path, artifact="run manifest")
+    except JsonBoundaryError as exc:
+        raise FinalizeError(f"run manifest is not valid: {path} ({exc})") from exc
     if not isinstance(payload, Mapping):
         raise FinalizeError(f"run manifest is not a JSON object: {path}")
     return payload

package/runtime/python/okstra_ctl/report_html/render.py

@@ -15,6 +15,7 @@ from ..i18n import HTML_DICTIONARY_REL, load_dictionary, make_jinja_global
 from ..report_translation import overlay
 from ..report_view_artifacts import user_responses_dir_for_report
 from ..usage_cells import format_duration_ms
+from ..json_boundary import load_owned_object
 from .common import anchor_index
 from .filters import (
     code_evidence,
@@ -87,7 +88,7 @@ def _localize(data: dict, data_path: Path) -> tuple[dict, str]:
             "rendering the English source\n"
         )
         return data, lang
-    payload = json.loads(sidecar_file.read_text(encoding="utf-8"))
+    payload = load_owned_object(sidecar_file, artifact="translation sidecar")
     strings = payload.get("strings")
     if not isinstance(strings, dict):
         raise HtmlRenderError(f"translation sidecar has no 'strings' object: {sidecar_file}")
@@ -120,7 +121,7 @@ def render_v2_html_view(
     no reader ever compared, which made a derived artifact a precondition for
     another derived artifact.
     """
-    data = json.loads(data_path.read_text(encoding="utf-8"))
+    data = load_owned_object(data_path, artifact="final report record")
     errors = validate(data, load_schema_for_data(data))
     if errors:
         raise HtmlRenderError("invalid v2 final-report data: " + "; ".join(errors[:5]))

package/runtime/python/okstra_ctl/report_language.py

@@ -12,6 +12,7 @@ from pathlib import Path
 from typing import Any, Mapping
 
 from .worker_prompt_body import instruction_path
+from .json_boundary import JsonBoundaryError, load_owned_object
 
 REPORT_LANGUAGE_VALUES = {"en", "ko", "auto"}
 
@@ -50,8 +51,8 @@ def _read_report_language(path: Path, label: str) -> str:
     if not path.is_file():
         return ""
     try:
-        payload = json.loads(path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError) as exc:
+        payload = load_owned_object(path, artifact=f"{label} configuration")
+    except JsonBoundaryError as exc:
         raise ReportLanguageError(f"{label} config is unreadable: {path}") from exc
     if not isinstance(payload, Mapping):
         raise ReportLanguageError(f"{label} config must be a JSON object: {path}")

package/runtime/python/okstra_ctl/report_markdown.py

@@ -95,6 +95,17 @@ def humanise(key: str) -> str:
     )
 
 
+def label_key(label: str) -> str:
+    """라벨 대조용 정규화 표기.
+
+    `humanise` 는 `_ACRONYMS` 표에 있는 낱말만 대문자로 올린다(`ticketId` ->
+    `Ticket ID`). 그 표는 저작자에게 전달되지 않으므로 `Ticket Id` 라고 쓰면
+    글자 하나 때문에 리포트 전체가 되돌아온다. 대소문자와 낱말 구분 문자를
+    지운 표기로 맞춰, 약어 표를 모르고도 쓸 수 있게 한다.
+    """
+    return re.sub(r"[^a-z0-9]", "", str(label).lower())
+
+
 class SchemaIndex:
     """Property-order lookup over the final-report schema.
 
@@ -161,6 +172,7 @@ class SchemaIndex:
 
     def keys_for_label(self, label: str) -> list[str]:
         """전체 스키마에서 사람이 읽는 표기가 일치하는 고유 키 후보."""
+        wanted = label_key(label)
         found: set[str] = set()
         pending: list[Any] = [self._schema]
         seen: set[int] = set()
@@ -173,7 +185,7 @@ class SchemaIndex:
                 continue
             seen.add(id(node))
             for key in (node.get("properties") or {}):
-                if humanise(key) == label:
+                if label_key(humanise(key)) == wanted:
                     found.add(key)
             pending.extend(node.values())
         return sorted(found)

package/runtime/python/okstra_ctl/report_narrative.py

@@ -8,7 +8,8 @@ from pathlib import Path
 from typing import Any, Mapping
 
 from .final_report_schema import validate
-from .report_markdown import SchemaIndex, humanise
+from .report_markdown import SchemaIndex, humanise, label_key
+from .json_boundary import load_owned_object
 
 
 TITLE = "# OKSTRA Report Narrative"
@@ -42,7 +43,7 @@ def _narrative_schema_path() -> Path:
 
 
 def _narrative_schema() -> dict[str, Any]:
-    return json.loads(_narrative_schema_path().read_text(encoding="utf-8"))
+    return load_owned_object(_narrative_schema_path(), artifact="report narrative schema")
 
 
 def _allowed_top_level() -> frozenset[str]:
@@ -191,7 +192,13 @@ def _parse_tree(markdown: str) -> _Node:
             level = _line_level(value.group("indent"), number)
             _append_value(stack, value.group("value"), level, number)
         else:
-            raise NarrativeContractError(f"line {number}: unsupported Markdown syntax")
+            raise NarrativeContractError(
+                f"line {number}: unsupported Markdown syntax `{line.strip()}` — "
+                "a narrative line is only `- **Field Name**`, `- Item <N>`, or "
+                "`> value`. Headings, tables at column 0, code fences, bare "
+                "paragraphs, JSON and YAML are rejected; put such text inside a "
+                "`> ` value line instead"
+            )
     return root
 
 
@@ -217,17 +224,38 @@ def _append_value(stack: list[_Node], value: str, level: int, number: int) -> No
     stack[-1].values.append(value)
 
 
+def _allowed_labels(node: Any, index: SchemaIndex, path: str) -> list[str]:
+    """이 위치에서 저작자가 쓸 수 있는 사람이 읽는 필드 표기."""
+    keys = index.key_order(node)
+    if not path:
+        keys = [key for key in keys if key in _allowed_top_level()]
+    # 파서가 뒤에서 거부할 필드를 여기서 권하면 안내가 다음 거부를 만든다.
+    keys = [key for key in keys if f"{path}.{key}".lstrip(".") not in _NESTED_FORBIDDEN]
+    return sorted(humanise(key) for key in keys)
+
+
 def _field_key(label: str, node: Any, index: SchemaIndex, path: str) -> str:
     candidates: dict[str, list[str]] = {}
     for key in index.key_order(node):
-        candidates.setdefault(humanise(key), []).append(key)
-    matches = candidates.get(label, [])
+        candidates.setdefault(label_key(humanise(key)), []).append(key)
+    matches = candidates.get(label_key(label), [])
     if not matches:
         matches = index.keys_for_label(label)
     display_path = f"{path}.{label}" if path else label
-    if len(matches) != 1:
+    # 거부만 알리면 다음 시도도 추측이 된다. 이 위치에서 허용되는 표기를
+    # 함께 실어, 재작성이 목록 대조로 끝나게 한다.
+    if not matches:
+        allowed = _allowed_labels(node, index, path)
+        listing = ", ".join(f"`{item}`" for item in allowed) or "(none)"
+        raise NarrativeContractError(
+            f"owner=report-writer field `{display_path}` is not an allowed unique "
+            f"field; allowed at this position: {listing}"
+        )
+    if len(matches) > 1:
+        collisions = ", ".join(f"`{key}`" for key in matches)
         raise NarrativeContractError(
-            f"owner=report-writer field `{display_path}` is not an allowed unique field"
+            f"owner=report-writer field `{display_path}` is not an allowed unique "
+            f"field; the label matches more than one schema key: {collisions}"
         )
     return matches[0]
 
@@ -310,8 +338,12 @@ def parse_narrative(markdown: str, schema: Mapping[str, Any]) -> dict[str, Any]:
     unknown = sorted(set(result) - _allowed_top_level())
     if unknown:
         labels = [humanise(key) for key in unknown]
+        owned = ", ".join(
+            f"`{humanise(key)}`" for key in sorted(_allowed_top_level())
+        )
         raise NarrativeContractError(
-            f"owner=report-writer cannot author fields: {labels}"
+            f"owner=report-writer cannot author fields: {labels}; "
+            f"writer-owned top-level fields: {owned}"
         )
     errors = validate(result, _narrative_schema())
     if errors: