okstra 0.179.2 → 0.180.0

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),

package/runtime/python/okstra_ctl/plan_items_cli.py

@@ -16,6 +16,8 @@ from typing import Any
 from .convergence_store import write_json_atomic
 from .plan_derivations import extract_tokens, find_derivations
 from .plan_items import PlanItemContractError, extract_plan_items
+from .final_report_schema import load_schema_version
+from .report_narrative import parse_narrative
 from .user_response import parse_user_response_entries
 from .verdict_blocks import (
     PLAN_ITEM_VERDICTS,
@@ -57,10 +59,10 @@ def _parser() -> argparse.ArgumentParser:
     )
     commands = parser.add_subparsers(dest="command", required=True)
     extract = commands.add_parser("extract")
-    extract.add_argument("--data", type=Path, required=True)
+    _add_plan_source(extract)
     extract.add_argument("--output", type=Path, required=True)
     validate = commands.add_parser("validate")
-    validate.add_argument("--data", type=Path, required=True)
+    _add_plan_source(validate)
     validate.add_argument("--items", type=Path, required=True)
     collect = commands.add_parser(
         "collect-verdicts",
@@ -84,12 +86,15 @@ def _parser() -> argparse.ArgumentParser:
         "seed",
         help="create the planBodyVerification.planItems[] rows a round lands in",
     )
-    seed.add_argument("--data", type=Path, required=True)
+    _add_plan_source(seed)
+    seed.add_argument("--state", type=Path)
     apply_verdicts = commands.add_parser(
         "apply-verdicts",
-        help="overwrite planBodyVerification.planItems[].verdicts in data.json",
+        help="overwrite planBodyVerification.planItems[].verdicts in owned state",
     )
-    apply_verdicts.add_argument("--data", type=Path, required=True)
+    target = apply_verdicts.add_mutually_exclusive_group(required=True)
+    target.add_argument("--data", type=Path)
+    target.add_argument("--state", type=Path)
     apply_verdicts.add_argument("--verdicts", type=Path, required=True)
     apply_verdicts.add_argument(
         "--round", type=int, required=True, dest="round_number",
@@ -99,14 +104,35 @@ def _parser() -> argparse.ArgumentParser:
     return parser
 
 
+def _add_plan_source(parser: argparse.ArgumentParser) -> None:
+    source = parser.add_mutually_exclusive_group(required=True)
+    source.add_argument("--data", type=Path)
+    source.add_argument("--narrative", type=Path)
+
+
+def _plan_source(args: argparse.Namespace) -> dict[str, Any]:
+    if args.data is not None:
+        return _load_json_object(args.data)
+    try:
+        markdown = args.narrative.read_text(encoding="utf-8")
+    except (OSError, UnicodeError) as exc:
+        raise PlanItemContractError(
+            f"cannot read report narrative {args.narrative}: {exc}"
+        ) from exc
+    try:
+        return parse_narrative(markdown, load_schema_version("3.0"))
+    except ValueError as exc:
+        raise PlanItemContractError(f"invalid report narrative: {exc}") from exc
+
+
 def _extract(args: argparse.Namespace) -> dict[str, Any]:
-    envelope = _envelope(_load_json_object(args.data))
+    envelope = _envelope(_plan_source(args))
     write_json_atomic(args.output, envelope)
     return {"ok": True, "operation": "extract", "path": str(args.output)}
 
 
 def _validate(args: argparse.Namespace) -> dict[str, Any]:
-    expected = _envelope(_load_json_object(args.data))
+    expected = _envelope(_plan_source(args))
     actual = _load_json_object(args.items)
     if actual != expected:
         raise PlanItemContractError("plan items envelope does not match deterministic extraction")
@@ -229,6 +255,45 @@ def _plan_body_items(data: dict[str, Any], data_path: Path) -> list[dict[str, An
     return items
 
 
+def _state_plan_body_items(
+    state: dict[str, Any], state_path: Path,
+) -> list[dict[str, Any]]:
+    if state.get("owner") != "convergence":
+        raise PlanItemContractError(
+            f"plan-body state owner must be convergence: {state_path}"
+        )
+    verification = state.get("planBodyVerification")
+    if not isinstance(verification, Mapping):
+        raise PlanItemContractError(
+            f"planBodyVerification must be an object: {state_path}"
+        )
+    items = verification.get("planItems")
+    if not isinstance(items, list):
+        raise PlanItemContractError(
+            f"planBodyVerification.planItems must be an array: {state_path}"
+        )
+    return items
+
+
+def _new_v3_state() -> dict[str, Any]:
+    return {
+        "schemaVersion": "1.1",
+        "owner": "convergence",
+        "planItems": [],
+        "roundHistory": [],
+        "selfFixRoundsApplied": 0,
+        "planBodyVerification": {
+            "roundCount": 0,
+            "gateResult": "passed",
+            "gateBlockedBy": [],
+            "selfFixRoundsApplied": 0,
+            "selfFixStopReason": "not-attempted",
+            "planItems": [],
+            "dissentLog": [],
+        },
+    }
+
+
 def _derivations(args: argparse.Namespace) -> dict[str, Any]:
     """Candidate statements each answered clarification may have falsified.
 
@@ -283,9 +348,17 @@ def _seed(args: argparse.Namespace) -> dict[str, Any]:
     already applied, `carriedForwardFromSeq`, `selfFixNote` — because a re-seed
     between rounds must not erase the round before it.
     """
-    extracted = _envelope(_load_json_object(args.data))["items"]
-    data = _load_json_object(args.data)
-    recorded = _plan_body_items(data, args.data)
+    extracted = _envelope(_plan_source(args))["items"]
+    if args.state is not None:
+        data = _load_json_object(args.state) if args.state.is_file() else _new_v3_state()
+        recorded = _state_plan_body_items(data, args.state)
+        target = args.state
+    else:
+        if args.data is None:
+            raise PlanItemContractError("--narrative requires --state")
+        data = _load_json_object(args.data)
+        recorded = _plan_body_items(data, args.data)
+        target = args.data
     known = {
         item.get("id")
         for item in recorded
@@ -306,18 +379,38 @@ def _seed(args: argparse.Namespace) -> dict[str, Any]:
         if item["id"] not in known
     ]
     recorded.extend(added)
-    write_json_atomic(args.data, data)
+    if args.state is not None:
+        audit_rows = data.get("planItems")
+        if not isinstance(audit_rows, list):
+            raise PlanItemContractError("state planItems must be an array")
+        audited = {
+            item.get("id") for item in audit_rows if isinstance(item, Mapping)
+        }
+        audit_rows.extend(
+            {
+                "id": item["id"],
+                "subject": item["subject"],
+                "sourceSection": item["sourceSection"],
+                "ticketId": item.get("ticketId") or "unknown",
+                "rounds": [],
+                "clarificationId": None,
+            }
+            for item in extracted
+            if item["id"] not in audited
+        )
+    write_json_atomic(target, data)
     return {
         "ok": True,
         "operation": "seed",
-        "path": str(args.data),
+        "path": str(target),
         "seeded": len(added),
         "existing": len(known),
     }
 
 
 def _apply_verdicts(args: argparse.Namespace) -> dict[str, Any]:
-    data = _load_json_object(args.data)
+    target = args.state or args.data
+    data = _load_json_object(target)
     incoming = _load_json_object(args.verdicts).get("planItems")
     if not isinstance(incoming, list):
         raise PlanItemContractError("verdicts envelope has no `planItems` array")
@@ -326,7 +419,11 @@ def _apply_verdicts(args: argparse.Namespace) -> dict[str, Any]:
         for item in incoming
         if isinstance(item, Mapping) and isinstance(item.get("id"), str)
     }
-    recorded = _plan_body_items(data, args.data)
+    recorded = (
+        _state_plan_body_items(data, target)
+        if args.state is not None
+        else _plan_body_items(data, target)
+    )
     known = {item.get("id") for item in recorded if isinstance(item, Mapping)}
     missing = sorted(item_id for item_id in rows if item_id not in known)
     if missing:
@@ -351,8 +448,8 @@ def _apply_verdicts(args: argparse.Namespace) -> dict[str, Any]:
             item["verdicts"] = [
                 {**row, "round": args.round_number} for row in rows[item["id"]]
             ]
-    write_json_atomic(args.data, data)
-    return {"ok": True, "operation": "apply-verdicts", "path": str(args.data)}
+    write_json_atomic(target, data)
+    return {"ok": True, "operation": "apply-verdicts", "path": str(target)}
 
 
 _HANDLERS = {

package/runtime/python/okstra_ctl/ports/worker_dispatch.py

@@ -15,7 +15,8 @@ class WorkerDispatchRequest:
     workspace_root: Path | None = None
     okstra_bin: Path | None = None
     requested_workers: tuple[str, ...] = ()
-    idle_timeout_seconds: int = 600
+    # 기본은 "정하지 않음" 이다. 그래야 엔트리포인트가 역할의 예산을 쓴다.
+    idle_timeout_seconds: int | None = None
     dispatch_kind: str = "initial"
     jobs_file: Path | None = None