okstra 0.179.2 → 0.183.2

package/runtime/python/okstra_ctl/report_finalize.py

@@ -1,10 +1,11 @@
 """Phase 7 report post-processing — the single reference point.
 
-Phase 7 turns a Phase 6 final-report data.json into shippable artifacts through
-six ordered steps: activity projection, English-SSOT verification, usage
-substitution, html view rendering, follow-up task spawning, and run validation.
-The order is load-bearing — rendering before substitution ships `--` token
-cells, and validating before rendering trips the report-views contract.
+Contract 3.0 collects usage into team state, assembles the role-owned inputs
+into final-report data.json once, then verifies and renders that published
+record. Contract 2.0 keeps its historical in-place projection sequence for
+read-only compatibility. The order is load-bearing: rendering before assembly
+or usage collection publishes stale derived views, and validating before
+rendering trips the report-views contract.
 
 `token-usage` is the one step whose failure does not stop the sequence, which
 deliberately accepts that first state: its input is the lead session log, so a
@@ -39,10 +40,12 @@ from typing import Any, Callable, Mapping, Sequence
 
 from .agent_activity import ActivityProjectionError, project_agent_activity
 from .report_contract import apply_execution_roles
+from .report_assembly import ReportAssemblyError, assemble_report
 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,
@@ -74,6 +77,16 @@ STEP_ORDER = (
     STEP_TEARDOWN_STAGES,
 )
 
+V3_STEP_ORDER = (
+    STEP_TOKEN_USAGE,
+    STEP_PROJECT_ACTIVITY,
+    STEP_CHECK_SOURCE,
+    STEP_RENDER_VIEWS,
+    STEP_SPAWN_FOLLOWUPS,
+    STEP_VALIDATE_RUN,
+    STEP_TEARDOWN_STAGES,
+)
+
 
 class FinalizeError(Exception):
     """Raised when the Phase 7 sequence cannot be assembled."""
@@ -226,6 +239,7 @@ class FinalizeContext:
     task_id: str
     seq: str
     final_status_path: Path | None
+    report_contract_version: str = "2.0"
 
     @property
     def markdown_path(self) -> Path:
@@ -257,13 +271,16 @@ class FinalizeContext:
             final_status_path=resolve_optional_path(
                 project_root, manifest.get("finalStatusPath")
             ),
+            report_contract_version=str(
+                manifest.get("reportContractVersion") or "2.0"
+            ),
         )
 
 
 def build_commands(ctx: FinalizeContext) -> list[tuple[str, list[str]]]:
     """Assemble the ordered Phase 7 argv list. Order is contractual."""
     markdown_path = ctx.markdown_path
-    return [
+    commands = [
         (
             STEP_PROJECT_ACTIVITY,
             [
@@ -344,6 +361,16 @@ def build_commands(ctx: FinalizeContext) -> list[tuple[str, list[str]]]:
             ["<in-process>", "teardown-stages", str(ctx.data_path)],
         ),
     ]
+    if ctx.report_contract_version != "3.0":
+        return commands
+    by_name = dict(commands)
+    usage = by_name[STEP_TOKEN_USAGE]
+    marker = usage.index("--substitute-data")
+    by_name[STEP_TOKEN_USAGE] = usage[:marker]
+    by_name[STEP_PROJECT_ACTIVITY] = [
+        "<in-process>", "report-assembly", str(ctx.manifest_path), str(ctx.data_path)
+    ]
+    return [(name, by_name[name]) for name in V3_STEP_ORDER]
 
 
 def _teardown_stage_worktrees(
@@ -363,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":
@@ -441,14 +468,16 @@ def run_finalize(
     steps: list[dict[str, Any]] = []
     deferred = ""
     try:
-        write_execution_roles(ctx)
+        if ctx.report_contract_version != "3.0":
+            write_execution_roles(ctx)
         commands = build_commands(ctx)
     except FinalizeError as exc:
         return {"ok": False, "reason": str(exc), "steps": steps}
 
     if only:
         selected = set(only)
-        unknown = sorted(selected - set(STEP_ORDER))
+        contract_order = V3_STEP_ORDER if ctx.report_contract_version == "3.0" else STEP_ORDER
+        unknown = sorted(selected - set(contract_order))
         if unknown:
             return {
                 "ok": False,
@@ -462,12 +491,17 @@ def run_finalize(
             before_step(name)
         if name == STEP_PROJECT_ACTIVITY:
             try:
-                rows = project_agent_activity(
-                    ctx.project_root,
-                    ctx.manifest_path,
-                    ctx.data_path,
-                )
-            except ActivityProjectionError as exc:
+                if ctx.report_contract_version == "3.0":
+                    assembled = assemble_report(ctx.project_root, ctx.manifest_path)
+                    count = len(assembled.get("agentActivity") or [])
+                else:
+                    rows = project_agent_activity(
+                        ctx.project_root,
+                        ctx.manifest_path,
+                        ctx.data_path,
+                    )
+                    count = len(rows)
+            except (ActivityProjectionError, ReportAssemblyError) as exc:
                 result = subprocess.CompletedProcess(
                     command,
                     1,
@@ -478,7 +512,7 @@ def run_finalize(
                 result = subprocess.CompletedProcess(
                     command,
                     0,
-                    json.dumps({"count": len(rows)}),
+                    json.dumps({"count": count}),
                     "",
                 )
         else:
@@ -530,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:
@@ -571,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
@@ -633,7 +663,9 @@ def _parser() -> argparse.ArgumentParser:
     return parser
 
 
-def _step_summary_lines(result: Mapping[str, Any]) -> list[str]:
+def _step_summary_lines(
+    result: Mapping[str, Any], order: Sequence[str] = STEP_ORDER,
+) -> list[str]:
     """One human-readable line per step, so the outcome is legible without
     parsing the JSON payload."""
     lines = []
@@ -641,13 +673,15 @@ def _step_summary_lines(result: Mapping[str, Any]) -> list[str]:
         code = step.get("exitCode")
         mark = "ok  " if code == 0 else "FAIL"
         lines.append(f"  [{mark}] {step.get('name')} (exit {code})")
-    for name in STEP_ORDER:
+    for name in order:
         if not any(s.get("name") == name for s in (result.get("steps") or [])):
             lines.append(f"  [skip] {name}")
     return lines
 
 
-def _recovery_step_names(result: Mapping[str, Any]) -> list[str]:
+def _recovery_step_names(
+    result: Mapping[str, Any], order: Sequence[str] = STEP_ORDER,
+) -> list[str]:
     """The steps a retry has to re-run: every step from the earliest failure on.
 
     Naming only the failed steps would prescribe half a recovery. `token-usage`
@@ -664,9 +698,9 @@ def _recovery_step_names(result: Mapping[str, Any]) -> list[str]:
         for step in (result.get("steps") or [])
         if step.get("exitCode") != 0
     }
-    for index, name in enumerate(STEP_ORDER):
+    for index, name in enumerate(order):
         if name in failed:
-            return list(STEP_ORDER[index:])
+            return list(order[index:])
     return []
 
 
@@ -682,13 +716,14 @@ def main(argv: Sequence[str] | None = None) -> int:
     # sequence because the token-usage step below reads `leadSessionIds`.
     observe_lead_session(ctx.project_root, ctx.team_state_path)
     result = run_finalize(ctx, only=args.only or None)
+    order = V3_STEP_ORDER if ctx.report_contract_version == "3.0" else STEP_ORDER
     print(json.dumps(result, indent=2, ensure_ascii=False))
     print("finalize steps:", file=sys.stderr)
-    for line in _step_summary_lines(result):
+    for line in _step_summary_lines(result, order):
         print(line, file=sys.stderr)
     if not result["ok"]:
         print(f"error: {result['reason']}", file=sys.stderr)
-        recovery = _recovery_step_names(result)
+        recovery = _recovery_step_names(result, order)
         if recovery:
             flags = " ".join(f"--only {name}" for name in recovery)
             print(

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_inputs.py

@@ -0,0 +1,72 @@
+"""리포트 계약 3.0의 역할별 입력 경로와 단일 소유자 레지스트리."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Mapping
+
+
+REPORT_CONTRACT_V3 = "3.0"
+
+
+class ReportInputError(ValueError):
+    """3.0 입력 경로나 소유자가 매니페스트에서 해소되지 않았다."""
+
+
+@dataclass(frozen=True)
+class ReportInputPath:
+    key: str
+    owner: str
+    path: Path
+
+
+_INPUT_FIELDS = (
+    ("narrative", "report-writer", "reportNarrativePath"),
+    ("approval-decisions", "lead", "approvalDecisionsPath"),
+    ("agent-activity", "activity-ledger", "leadEventsPath"),
+    ("execution-status", "team-state", "teamStatePath"),
+    ("convergence", "convergence", "convergenceStatePath"),
+)
+
+_PLANNING_INPUT_FIELDS = (
+    ("design-preparation", "design-surface-detector", "designPreparationPath"),
+    ("plan-body-verification", "convergence", "planBodyVerificationPath"),
+)
+
+
+def uses_report_contract_v3(manifest: Mapping[str, Any]) -> bool:
+    return str(manifest.get("reportContractVersion") or "").strip() == REPORT_CONTRACT_V3
+
+
+def _project_path(project_root: Path, value: object, field: str) -> Path:
+    if not isinstance(value, str) or not value.strip():
+        raise ReportInputError(f"report contract 3.0 requires {field}")
+    path = Path(value)
+    return path if path.is_absolute() else project_root / path
+
+
+def report_narrative_path(
+    project_root: Path, manifest: Mapping[str, Any],
+) -> Path:
+    if not uses_report_contract_v3(manifest):
+        raise ReportInputError("report narrative path belongs to report contract 3.0")
+    return _project_path(project_root, manifest.get("reportNarrativePath"), "reportNarrativePath")
+
+
+def report_input_paths(
+    project_root: Path, manifest: Mapping[str, Any],
+) -> tuple[ReportInputPath, ...]:
+    if not uses_report_contract_v3(manifest):
+        raise ReportInputError("role-owned report inputs require report contract 3.0")
+    fields = _INPUT_FIELDS + (
+        _PLANNING_INPUT_FIELDS
+        if manifest.get("taskType") == "implementation-planning"
+        else ()
+    )
+    rows = tuple(
+        ReportInputPath(key, owner, _project_path(project_root, manifest.get(field), field))
+        for key, owner, field in fields
+    )
+    if len({row.key for row in rows}) != len(rows):
+        raise ReportInputError("report input keys must be unique")
+    return rows

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.
 
@@ -105,6 +116,7 @@ class SchemaIndex:
 
     def __init__(self, schema: Any) -> None:
         self._defs = schema.get("$defs", {}) if isinstance(schema, dict) else {}
+        self._schema = schema if isinstance(schema, dict) else {}
 
     def resolve(self, node: Any) -> dict:
         seen: set[str] = set()
@@ -118,10 +130,21 @@ class SchemaIndex:
 
     def _branches(self, node: Any) -> list[dict]:
         resolved = self.resolve(node)
-        branches = [resolved]
-        for keyword in ("allOf", "oneOf", "anyOf"):
-            for branch in resolved.get(keyword) or ():
-                branches.append(self.resolve(branch))
+        branches: list[dict] = []
+        pending = [resolved]
+        seen: set[int] = set()
+        while pending:
+            branch = pending.pop(0)
+            identity = id(branch)
+            if identity in seen:
+                continue
+            seen.add(identity)
+            branches.append(branch)
+            for keyword in ("allOf", "oneOf", "anyOf"):
+                pending.extend(
+                    self.resolve(candidate)
+                    for candidate in branch.get(keyword) or ()
+                )
         return branches
 
     def key_order(self, node: Any) -> list[str]:
@@ -133,17 +156,67 @@ class SchemaIndex:
         return order
 
     def child(self, node: Any, key: str) -> dict:
+        candidates: list[dict] = []
         for branch in self._branches(node):
             candidate = (branch.get("properties") or {}).get(key)
             if candidate is not None:
-                return self.resolve(candidate)
-        return {}
+                candidates.append(self.resolve(candidate))
+        return max(candidates, key=_schema_detail, default={})
 
     def item(self, node: Any) -> dict:
+        candidates: list[dict] = []
         for branch in self._branches(node):
             if "items" in branch:
-                return self.resolve(branch["items"])
-        return {}
+                candidates.append(self.resolve(branch["items"]))
+        return max(candidates, key=_schema_detail, default={})
+
+    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()
+        while pending:
+            node = pending.pop()
+            if isinstance(node, list):
+                pending.extend(node)
+                continue
+            if not isinstance(node, dict) or id(node) in seen:
+                continue
+            seen.add(id(node))
+            for key in (node.get("properties") or {}):
+                if label_key(humanise(key)) == wanted:
+                    found.add(key)
+            pending.extend(node.values())
+        return sorted(found)
+
+    def schema_for_key(self, key: str) -> dict:
+        """전체 스키마에서 이 키를 가장 구체적으로 설명하는 후보."""
+        found: list[dict] = []
+        pending: list[Any] = [self._schema]
+        seen: set[int] = set()
+        while pending:
+            node = pending.pop()
+            if isinstance(node, list):
+                pending.extend(node)
+                continue
+            if not isinstance(node, dict) or id(node) in seen:
+                continue
+            seen.add(id(node))
+            candidate = (node.get("properties") or {}).get(key)
+            if isinstance(candidate, dict):
+                found.append(self.resolve(candidate))
+            pending.extend(node.values())
+        return max(found, key=_schema_detail, default={})
+
+
+def _schema_detail(node: dict) -> tuple[int, int]:
+    """구체적인 분기 스키마가 빈 호환 스키마보다 먼저 선택되게 한다."""
+    structural = sum(
+        1 for key in ("properties", "items", "required", "enum", "const", "type")
+        if key in node
+    )
+    return structural, len(str(node))
 
 
 def _is_scalar(value: Any) -> bool: