okstra 0.179.1 → 0.180.0

package/runtime/python/okstra_ctl/dispatch_state.py

@@ -47,6 +47,7 @@ from .execution_manifest import (
 )
 from .execution_mutation_audit import ExecutionMutationAudit, MutationSnapshot
 from .final_report_paths import final_report_data_path
+from .report_inputs import report_narrative_path, uses_report_contract_v3
 from .worker_prompt_body import REPORT_WRITER_WORKER_ID
 from .worker_prompt_contract import (
     PromptRecord,
@@ -152,7 +153,11 @@ class WorkerJob:
     completion_paths: tuple[Path, ...]
     worktree_path: str
     role: str
-    idle_timeout_seconds: int
+    # None 은 "이 디스패치가 예산을 정하지 않는다" 는 뜻이고, 그때 예산은
+    # 역할이 정한다(`domain/worker_role.role_spec`). 여기에 숫자 기본값을 두면
+    # 역할별 예산이 영영 도달 불가능해진다 — 엔트리포인트는 이 자리가 비었을
+    # 때만 역할을 보기 때문이다.
+    idle_timeout_seconds: int | None
     dispatch_kind: str
     invocation_id: str = ""
     audience: str = ""
@@ -188,7 +193,7 @@ class WorkerJob:
             str(self.prompt_path),
             self.worktree_path,
             self.wrapper_role,
-            str(self.idle_timeout_seconds),
+            self._idle_timeout_argument,
             "--presentation",
             self._presentation(),
         ]
@@ -201,6 +206,18 @@ class WorkerJob:
             argv += ["--session-id", self.session_id]
         return argv
 
+    @property
+    def _idle_timeout_argument(self) -> str:
+        """엔트리포인트가 읽는 유휴 예산 자리.
+
+        비워 두면 엔트리포인트가 역할의 예산을 쓴다. 이 자리를 항상 채우던
+        동안에는 `worker_request.idle_timeout` 의 역할 분기가 한 번도 실행되지
+        않았고, executor/verifier 의 1500s 도 함께 죽어 있었다.
+        """
+        if self.idle_timeout_seconds is None:
+            return ""
+        return str(self.idle_timeout_seconds)
+
     @property
     def wrapper_role(self) -> str:
         """The canonical role the entrypoint's role positional is read as.
@@ -707,6 +724,10 @@ def record_verified_agent_dispatch(
             snapshot = ExecutionMutationAudit().snapshot(
                 (write_policy,),
                 orchestrator_paths=(
+                    # run 산출물 트리 전체. 같은 run 의 다른 라운드가 감사 창
+                    # 안에 남기는 프롬프트·로그·사이드카를 파일 단위로 미리 셀
+                    # 수 없고, 그 아래는 정의상 소스가 아니다.
+                    Path(run_manifest_path).resolve().parents[1],
                     run_manifest_path,
                     team_state_path,
                     Path(f"{team_state_path}.lock"),
@@ -1468,6 +1489,8 @@ def dispatch_result_path(
     """
     if worker_id != REPORT_WRITER_WORKER_ID:
         return worker_result_path
+    if uses_report_contract_v3(manifest):
+        return report_narrative_path(project_root, manifest)
     return final_report_data_path(
         resolve_required_path(project_root, manifest, "expectedReportRecordPath")
     )
@@ -1487,6 +1510,8 @@ def dispatch_completion_paths(
     """
     if worker_id != REPORT_WRITER_WORKER_ID:
         return (worker_result_path,)
+    if uses_report_contract_v3(manifest):
+        return (report_narrative_path(project_root, manifest), worker_result_path)
     data_json = final_report_data_path(
         resolve_required_path(project_root, manifest, "expectedReportRecordPath")
     )
@@ -1765,7 +1790,7 @@ def worker_jobs_from_file(
     manifest: Mapping[str, Any],
     active_context: Mapping[str, Any] | None = None,
     backend: str,
-    idle_timeout_seconds: int,
+    idle_timeout_seconds: int | None,
     default_dispatch_kind: str,
     resolve_wrapper: Callable[[str], Path],
     default_provider: Callable[[str], str],
@@ -1804,7 +1829,7 @@ def _worker_job_from_file(
     manifest: Mapping[str, Any],
     active_context: Mapping[str, Any] | None = None,
     backend: str,
-    idle_timeout_seconds: int,
+    idle_timeout_seconds: int | None,
     dispatch_kind: str,
     resolve_wrapper: Callable[[str], Path],
     default_provider: Callable[[str], str],

package/runtime/python/okstra_ctl/execution_mutation_audit.py

@@ -32,6 +32,10 @@ class MutationSnapshot:
     scratch_digests: Mapping[str, str]
     git_projection: Mapping[str, Any]
     digest: str
+    # 오케스트레이터가 쓰는 경로. 파일 하나를 싣거나 디렉터리를 실어 그 트리
+    # 전체를 덮을 수 있다 — 한 배치가 무엇을 쓸지 파일 단위로 미리 셀 수 없기
+    # 때문이다(다른 라운드의 재시도 프롬프트, 로그, 상태 사이드카가 그 창에
+    # 들어온다).
     orchestrator_paths: tuple[str, ...] = ()
 
     def to_payload(self) -> dict[str, Any]:
@@ -445,7 +449,7 @@ def _source_changes(
             snapshot.artifact_root == snapshot.root
             and any(_is_within(path, item) for item in artifacts)
         )
-        and path not in orchestrator
+        and not any(_is_within(path, item) for item in orchestrator)
         and not _excluded(Path(path), generated)
     }
 
@@ -464,7 +468,7 @@ def _artifact_policy_failures(
     unauthorized = {
         path for path in changed
         if not any(_is_within(path, item) for item in allowed)
-        and path not in orchestrator
+        and not any(_is_within(path, item) for item in orchestrator)
     }
     if snapshot.artifact_root == snapshot.root:
         return []

package/runtime/python/okstra_ctl/final_report_schema.py

@@ -1,11 +1,11 @@
-"""Mini JSON Schema validator for the final-report data.json.
+"""Mini JSON Schema validator for versioned final-report data.json records.
 
 This is a deliberately narrow JSON Schema implementation that supports
 exactly the keywords used by ``schemas/final-report-v2.0.schema.json``:
 
   type, required, properties, additionalProperties, enum, const, pattern,
   minLength, minItems, maxItems, uniqueItems, items, minimum, maximum, $ref ($defs),
-  oneOf, allOf, if/then/else, contains, not
+  oneOf, allOf, if/then/else, contains, minContains, maxContains, not
 
 We do NOT depend on the ``jsonschema`` PyPI package because its
 dependency tree (``referencing``, ``rpds-py``) includes a Rust C
@@ -13,8 +13,8 @@ extension which we would have to vendor or ship pre-built per platform.
 The ~250 lines below cover everything the final-report schema needs;
 strict spec compliance is not a goal — strict validation of OUR schema is.
 
-Error messages include the JSON pointer of the failing field so the
-report-writer can fix the exact data.json cell.
+Error messages include the JSON pointer of the failing field so report
+assembly can return the defect to the input owner.
 """
 from __future__ import annotations
 
@@ -23,9 +23,6 @@ import re
 from pathlib import Path
 from typing import Any
 
-from okstra_ctl.report_contract import CURRENT_REPORT_SCHEMA_VERSION
-
-
 class SchemaError(ValueError):
     """Raised when a schema itself is malformed (e.g. a $ref points
     nowhere). Distinct from a data validation failure.
@@ -204,10 +201,20 @@ class _Validator:
             for i, value in enumerate(instance):
                 self.validate(value, items, path + (i,))
         contains = schema.get("contains")
-        if contains is not None and not any(
-            self._matches(value, contains) for value in instance
-        ):
-            self._err(path, f"array does not contain any item matching {self._summarise(contains)}")
+        if contains is not None:
+            matches = sum(self._matches(value, contains) for value in instance)
+            minimum = schema.get("minContains", 1)
+            maximum = schema.get("maxContains")
+            if matches < minimum:
+                self._err(
+                    path,
+                    f"array contains {matches} matching item(s), below minContains {minimum}",
+                )
+            if maximum is not None and matches > maximum:
+                self._err(
+                    path,
+                    f"array contains {matches} matching item(s), above maxContains {maximum}",
+                )
 
     def _validate_conditional(self, instance: Any, schema: dict, path: tuple[str | int, ...]) -> None:
         if_schema = schema.get("if")
@@ -263,6 +270,7 @@ def validate(data: Any, schema: dict) -> list[str]:
 
 SCHEMA_FILENAMES = {
     "2.0": "final-report-v2.0.schema.json",
+    "3.0": "final-report-v3.0.schema.json",
 }
 
 
@@ -295,10 +303,11 @@ def load_schema_for_data(data: dict, start: Path | None = None) -> dict:
 
 
 def load_schema(schema_path: Path | None = None) -> dict:
-    """Load the final-report schema. If ``schema_path`` is None, locate
-    ``schemas/final-report-v2.0.schema.json`` relative to this file's
-    repo root.
+    """Load the compatibility schema used by historical direct callers.
+
+    New write paths select contract 3.0 explicitly. Readers select from the
+    record's ``schemaVersion`` through :func:`load_schema_for_data`.
     """
     if schema_path is not None:
         return json.loads(Path(schema_path).read_text(encoding="utf-8"))
-    return load_schema_version(CURRENT_REPORT_SCHEMA_VERSION)
+    return load_schema_version("2.0")

package/runtime/python/okstra_ctl/incremental_carry.py

@@ -7,9 +7,15 @@ 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
 
 
 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 +296,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
@@ -317,33 +395,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 +466,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

@@ -207,7 +207,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
 

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

@@ -562,6 +562,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 +671,10 @@ 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),
+        "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),
@@ -737,6 +745,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),