okstra 0.186.7 → 0.187.0

package/runtime/python/okstra_ctl/incremental_scope.py

@@ -16,9 +16,10 @@ from dataclasses import asdict, dataclass
 from pathlib import Path
 
 from okstra_ctl.final_report_paths import final_report_data_path
+from okstra_ctl.paths import infer_project_root
 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
+from okstra_ctl.json_boundary import load_owned_object, write_owned_object_atomic
 
 CUTOFF_RATIO = 0.5
 
@@ -27,6 +28,7 @@ CUTOFF_RATIO = 0.5
 # which is what made a re-run's "no impacted stages resolved" unreadable as
 # either a structural judgement or a mapping the lead never made.
 DECLARED_FULL_PREFIX = "declared structural change:"
+DECLARED_CARRY_ALL_PREFIX = "declared additive change:"
 
 # CLI-to-lead signal only: an answered id traced to no stage and the user has
 # not named `--impacted` stages. Never recorded as incrementalDecision (schema
@@ -54,7 +56,7 @@ class UserReverifyScope:
     The lead still runs `okstra incremental-scope`; this only says which of the
     CLI's inputs the user pinned. `auto` pins nothing.
     """
-    mode: str  # "auto" | "full" | "stages"
+    mode: str  # "auto" | "full" | "carry-all" | "stages"
     stages: list[int]
 
 
@@ -62,10 +64,18 @@ class ReverifyScopeError(ValueError):
     """The `--reverify-scope` value is not one of the three accepted forms."""
 
 
+# 위저드가 "이월만 하고 재검증은 없음" 을 고를 때 쓰는 핀. 직전 stage 가 전부
+# `done` 이고 이번 재실행이 stage 를 **추가만** 하는 형태에서는 지정할 stage 번호가
+# 없다 — 그래서 `stages` 핀으로 표현할 수 없고, `full` 을 고르면 이월해도 되는
+# stage 를 전부 다시 교차검증하는 비용을 사용자가 치른다.
+CARRY_ALL_SCOPE = "carry-all"
+
+
 def parse_user_reverify_scope(raw: str) -> UserReverifyScope:
     """`--reverify-scope` → the user's pinned scope.
 
-    Accepts exactly `""` / `auto`, `full`, or a comma-separated stage list.
+    Accepts exactly `""` / `auto`, `full`, `carry-all`, or a comma-separated
+    stage list.
     Anything else raises rather than degrading to `auto`: a typo silently read
     as "let the lead decide" would drop a full-re-verification request the user
     made on purpose, and the run would look like it honoured it.
@@ -73,13 +83,13 @@ def parse_user_reverify_scope(raw: str) -> UserReverifyScope:
     value = (raw or "").strip()
     if not value or value == "auto":
         return UserReverifyScope("auto", [])
-    if value == "full":
-        return UserReverifyScope("full", [])
+    if value in ("full", CARRY_ALL_SCOPE):
+        return UserReverifyScope(value, [])
     tokens = [token.strip() for token in value.split(",") if token.strip()]
     if not tokens or not all(token.isdigit() for token in tokens):
         raise ReverifyScopeError(
-            f"--reverify-scope must be 'auto', 'full', or a stage-number list "
-            f"(e.g. '2,3'); got {raw!r}"
+            f"--reverify-scope must be 'auto', 'full', {CARRY_ALL_SCOPE!r}, or a "
+            f"stage-number list (e.g. '2,3'); got {raw!r}"
         )
     return UserReverifyScope("stages", sorted({int(token) for token in tokens}))
 
@@ -369,6 +379,57 @@ def decide_scope(
     )
 
 
+def decision_record(
+    decision: IncrementalDecision,
+    *,
+    prev_data: str,
+) -> dict:
+    """디스크에 남길 판정. narrative 의 `incrementalDecision` 과 같은 camelCase.
+
+    작성자가 리포트에 적을 필드명과 다르게 두면 옮겨 적는 사람이 매핑을 한 번
+    더 해야 하고, 그 매핑이 이 판정을 전달하는 유일한 경로였다.
+    """
+    return {
+        "schemaVersion": "1.0",
+        "mode": decision.mode,
+        "reverifyStages": list(decision.reverify_stages),
+        "carryStages": list(decision.carry_stages),
+        "reason": decision.reason,
+        "prevDataPath": prev_data,
+    }
+
+
+def _record_path(run_manifest: Path) -> Path:
+    """매니페스트가 이 run 의 판정 레코드로 지목한 경로.
+
+    경로를 CLI 인자로 받지 않는 이유가 이 함수다 — 판정을 쓰는 쪽과 읽는 쪽이
+    각자 경로를 조립하면 그 조립이 어긋날 자리가 생기고, 어긋나면 읽는 쪽은
+    "판정이 없다"(= full)로 읽는다. 매니페스트 한 곳이 답한다.
+    """
+    manifest = load_owned_object(run_manifest, artifact="run manifest")
+    value = manifest.get("incrementalDecisionPath")
+    if not isinstance(value, str) or not value:
+        raise ValueError(
+            "run manifest has no incrementalDecisionPath; re-render the run "
+            "bundle with a runtime that ships it"
+        )
+    candidate = Path(value)
+    if candidate.is_absolute():
+        return candidate
+    # 매니페스트의 경로 필드는 프로젝트 상대다. 부모를 고정 횟수로 세지 않는다
+    # — 매니페스트는 `.okstra/tasks/<group>/<id>/runs/<type>/manifests/` 아래에
+    # 있고 그 깊이를 손으로 세면 계층이 하나 바뀔 때 조용히 어긋난다.
+    return infer_project_root(run_manifest.resolve()) / candidate
+
+
+def _persist(decision: IncrementalDecision, args) -> None:
+    write_owned_object_atomic(
+        _record_path(Path(args.run_manifest)),
+        decision_record(decision, prev_data=args.prev_data),
+        artifact="incremental scope decision",
+    )
+
+
 def _preview_result(args) -> dict:
     """`preview_link_availability` over CLI args, degrading to full on bad input.
 
@@ -394,6 +455,42 @@ def _preview_result(args) -> dict:
         }
 
 
+def _carry_all_decision(args, declared: str) -> IncrementalDecision:
+    """이전 stage 전부를 그대로 이월하고 아무것도 재검증하지 않는 판정.
+
+    base ref 는 여전히 본다 — 브랜치가 움직였으면 이전 stage 본문이 "그대로"
+    가 아니고, 그때 이월은 사실이 아닌 주장이 된다.
+    """
+    if not args.prev_base_sha or args.prev_base_sha != args.cur_base_sha:
+        return IncrementalDecision(
+            "full", [], [],
+            "the branch this plan was written against has moved on "
+            f"({args.prev_base_sha or 'unrecorded'} -> "
+            f"{args.cur_base_sha or 'unrecorded'}), so the prior stages cannot "
+            "be carried as written even though this run only adds to them",
+        )
+    try:
+        data = load_owned_object(
+            Path(args.prev_data), artifact="incremental scope report"
+        )
+        stages = parse_stage_graph(data)
+    except (OSError, ValueError, KeyError, TypeError) as exc:
+        return IncrementalDecision(
+            "full", [], [], f"invalid incremental-scope input: {exc}",
+        )
+    carry = sorted({stage for stage, _ in stages})
+    if not carry:
+        return IncrementalDecision(
+            UNRESOLVED_MODE, [], [],
+            "--carry-all-reason was given but the prior report has no Stage Map "
+            "row to carry; check --prev-data",
+        )
+    return IncrementalDecision(
+        "incremental", [], carry,
+        f"{DECLARED_CARRY_ALL_PREFIX} {declared}",
+    )
+
+
 def _decision_for_run(args) -> IncrementalDecision:
     """SHA·폐포·컷오프 판정. unlinked 는 full 로 강등하지 않는다."""
     data = load_owned_object(
@@ -419,8 +516,10 @@ def _decision_for_run(args) -> IncrementalDecision:
             [],
             [],
             f"{', '.join(unlinked)} trace(s) to no stage in the prior report — "
-            "pass --impacted with the stage numbers those answers affect, or "
-            "--full-reason for a structural change",
+            "pass --impacted with the stage numbers those answers affect, "
+            "--full-reason for a structural change, or --carry-all-reason when "
+            "this run only adds stages and every prior stage carries forward "
+            "as written",
         )
     impacted.update(linked)
     unknown_stages = impacted - {stage for stage, _ in stages}
@@ -435,9 +534,39 @@ def _decision_for_run(args) -> IncrementalDecision:
     )
 
 
+_CLI_EPILOG = r"""Usage:
+  okstra incremental-scope --prev-data <path> --cur-base-sha <sha> \
+    --prev-base-sha <sha> [--impacted <csv>] [--option <name>]
+  okstra incremental-scope --preview --prev-data <path> \
+    --answered-clarifications <csv>
+
+Prints a JSON decision {mode, reverify_stages, carry_stages, reason} to stdout.
+
+`--preview` prints {wouldForceFull, unlinkedIds, reason} instead and needs no
+base SHA. It answers only the link half — whether the answered ids trace to a
+stage in the prior report — so it can run before `render-bundle` fixes a
+worktree base commit, while the decision to start is still reversible.
+`wouldForceFull: false` is not a promise of `incremental`: the base-ref check
+still runs at decision time.
+"""
+_CLI_DESCRIPTION = "Decide the re-verify vs carry-forward scope for a clarification re-run."
+
+
 def main(argv: list[str]) -> int:
-    ap = argparse.ArgumentParser(prog="okstra incremental-scope")
+    ap = argparse.ArgumentParser(
+        description=_CLI_DESCRIPTION,
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        prog="okstra incremental-scope")
     ap.add_argument("--prev-data", required=True, help="prior run final-report data.json")
+    ap.add_argument(
+        "--run-manifest",
+        default="",
+        help="this run's manifest. Required unless --preview: the decision is "
+             "written to the record it names (incrementalDecisionPath) so the "
+             "report writer's authoring contract and `incremental-carry` read "
+             "the same values instead of re-typed CSVs",
+    )
     # Not required: `--preview` answers the link half before a worktree base
     # commit exists, which is the whole reason that mode is there.
     ap.add_argument("--cur-base-sha", default="")
@@ -464,21 +593,49 @@ def main(argv: list[str]) -> int:
              "recommended approach. Forces full and records the judgement, so it "
              "is distinguishable from a re-run that simply resolved no stage",
     )
+    ap.add_argument(
+        "--carry-all-reason",
+        default="",
+        help="declare that this run only ADDS to the prior plan — every prior "
+             "stage carries forward as written and nothing is re-verified. The "
+             "mirror of --full-reason: without it a run that appends a stage has "
+             "no answer to give, because pinning any prior stage as impacted "
+             "makes `incremental-carry` demand it from a snapshot that no longer "
+             "holds it",
+    )
     args = ap.parse_args(argv)
 
     if args.preview:
         print(json.dumps(_preview_result(args), ensure_ascii=False))
         return 0
 
+    if not args.run_manifest.strip():
+        ap.error("--run-manifest is required unless --preview")
+
     declared = args.full_reason.strip()
     if declared:
         # The lead's structural judgement is exactly what the back-trace cannot
         # make, so a successful trace must not override it.
-        print(json.dumps(asdict(IncrementalDecision(
+        decision = IncrementalDecision(
             "full", [], [], f"{DECLARED_FULL_PREFIX} {declared}",
-        )), ensure_ascii=False))
+        )
+        _persist(decision, args)
+        print(json.dumps(asdict(decision), ensure_ascii=False))
         return 0
 
+    additive = args.carry_all_reason.strip()
+    if additive:
+        # 추가만 하는 run 은 되짚기로 표현할 수 없다. 이전 stage 중 어느 것도
+        # 영향받지 않았다는 것은 `--impacted` 로 못 쓰고(빈 값은 "좁힐 수
+        # 없음" 으로 읽힌다), 아무 stage 나 찍으면 `incremental-carry` 가 그
+        # stage 를 현재 스냅샷에서 찾다가 거절한다 — done 이라 이번 서술문에
+        # 없기 때문이다. 그래서 판단을 선언으로 받는다.
+        decision = _carry_all_decision(args, additive)
+        if decision.mode != UNRESOLVED_MODE:
+            _persist(decision, args)
+        print(json.dumps(asdict(decision), ensure_ascii=False))
+        return 0 if decision.mode != UNRESOLVED_MODE else 1
+
     try:
         decision = _decision_for_run(args)
     # Every bad input degrades to a full re-verification rather than raising:
@@ -491,6 +648,10 @@ def main(argv: list[str]) -> int:
         decision = IncrementalDecision(
             "full", [], [], f"invalid incremental-scope input: {exc}",
         )
+    # `unresolved` 는 판정이 아니라 리드에게 되묻는 신호이고 리포트 스키마의
+    # enum 에도 없다. 레코드로 남기면 소비자가 그것을 판정으로 읽는다.
+    if decision.mode != UNRESOLVED_MODE:
+        _persist(decision, args)
     print(json.dumps(asdict(decision), ensure_ascii=False))
     return 0
 

package/runtime/python/okstra_ctl/index.py

@@ -58,7 +58,7 @@ def record_start(home: Path, *, project_id: str, project_root: str,
         final_status_rel=final_status_rel,
         execution_manifest_path=execution_manifest_path,
         role_execution_refs=role_execution_refs)
-    # okstra-ctl 가 미리 'reserving' 예약 row 를 작성했을 수 있다(P1-2). 같은
+    # 앞선 prepare 가 미리 'reserving' 예약 row 를 작성했을 수 있다(P1-2). 같은
     # runId 의 예약 row 가 있으면 update; 없으면 append.
     existing_rows = read_jsonl(home / "active.jsonl")
     had_reservation = any(r.get("runId") == run_id for r in existing_rows)
@@ -68,7 +68,7 @@ def record_start(home: Path, *, project_id: str, project_root: str,
             remove_jsonl_row(home / "active.jsonl",
                              lambda r: r.get("runId") == run_id)
         # 동일 runId 가 이미 recent.jsonl 에 있으면(예: 매니페스트 직후 사용자가
-        # 처음 okstra-ctl 을 실행해 자동 backfill 이 같은 terminal run 을 미리
+        # 자동 backfill 이 같은 terminal run 을 미리
         # ingest 한 경우) 중복 append 를 방지하기 위해 기존 row 를 제거하고 새로
         # 쓴다(replace). 그렇지 않으면 동일 runId 가 두 줄로 남아 prefix 해석이
         # 모호해지고 runCount 도 재증가한다.

package/runtime/python/okstra_ctl/initial_prompt_materialization.py

@@ -11,7 +11,7 @@ from pathlib import Path
 from typing import Any, Callable, Literal, Mapping, Sequence
 
 from .final_report_paths import final_report_data_path
-from .agent_invocation import (
+from .agent.invocation import (
     AgentInstruction,
     AgentInstructionSource,
     AgentInvocationError,
@@ -377,14 +377,18 @@ def _prepare_prompt_item(
     except InitialPromptMaterializationError:
         raise
     except Exception as exc:
+        leaked = ""
         if temp_path is not None:
             try:
                 temp_path.unlink(missing_ok=True)
-            except OSError:
-                pass
+            except OSError as cleanup_exc:
+                # 정리 실패를 버리면 남은 .tmp 파일이 원인 없이 쌓인다. 원 오류를
+                # 가리지 않도록 던지지 않고 메시지에 실어 보낸다.
+                leaked = (f"; the staging file {temp_path} could not be removed "
+                          f"({cleanup_exc})")
         raise InitialPromptMaterializationError(
             "render_failed",
-            f"cannot render initial prompt for {item.worker.worker_id}: {exc}",
+            f"cannot render initial prompt for {item.worker.worker_id}: {exc}{leaked}",
         ) from exc
     if temp_path is None:
         raise InitialPromptMaterializationError(
@@ -590,6 +594,7 @@ def _prompt_body(
         worker.worker_id,
         worker.model,
         plan,
+        _optional_approved_plan_path(context) if plan.include_approved_plan else "",
     )
 
 
@@ -601,10 +606,7 @@ def _report_writer_packet_source(
     context: _MaterializationContext,
     plan: PromptPlan,
 ) -> AgentInstructionSource | None:
-    if (
-        plan.audience != "report-writer"
-        or not uses_report_contract_v3(context.manifest)
-    ):
+    if not _report_writer_reads_a_packet(context, plan):
         return None
     _, markdown_path = report_synthesis_packet_paths(
         _report_writer_narrative_path(context)
@@ -615,6 +617,25 @@ def _report_writer_packet_source(
     )
 
 
+def _report_writer_reads_a_packet(
+    context: "_MaterializationContext",
+    plan: PromptPlan,
+) -> bool:
+    """report-writer 의 `## Inputs` 가 합성 묶음 한 줄로 접히는가.
+
+    ADR-0023 이후 report-writer 는 합성 묶음 하나만 받는다 — clarification
+    응답을 포함한 개별 경로는 열거되지 않는다. contract v3 가 아닌 매니페스트는
+    아직 옛 목록(`report_writer_input_lines`)을 쓰고 그 목록에는 clarification
+    줄이 있다. 즉 이 답은 정적 plan 플래그가 아니라 이 run 의 계약 버전에
+    달려 있고, 본문을 조립한 쪽과 그 본문을 검사하는 쪽이 같은 술어를 써야
+    한다 — 갈리면 clarification 을 받은 planning 재실행이 Phase 6 에서
+    `existing_prompt_invalid` 로 막힌다.
+    """
+    return plan.audience == "report-writer" and uses_report_contract_v3(
+        context.manifest
+    )
+
+
 def _materialize_report_writer_packet(
     context: _MaterializationContext,
     plan: PromptPlan,
@@ -993,6 +1014,7 @@ def _validate_existing_clarification_metadata(
     enumerated = (
         item.plan.audience in _MATERIALIZABLE_AUDIENCES
         and not item.plan.packet_only
+        and not _report_writer_reads_a_packet(context, item.plan)
     )
     input_values = _backticked_line_values(
         _markdown_section(text, "## Inputs"),
@@ -1253,6 +1275,9 @@ def _result_paths(
     worker_result = _required_string(state, "resultPath")
     if worker_id != REPORT_WRITER_WORKER_ID:
         return worker_result, None
+    if uses_report_contract_v3(context.manifest):
+        narrative = report_narrative_path(context.project_root, context.manifest)
+        return _project_relative(context.project_root, narrative), worker_result
     expected_report = _required_string(context.manifest, "expectedReportRecordPath")
     return str(final_report_data_path(Path(expected_report))), worker_result
 
@@ -1336,6 +1361,21 @@ def _required_approved_plan_path(context: _MaterializationContext) -> str:
     return str(_resolve_input_path(context.project_root, Path(value)))
 
 
+def _optional_approved_plan_path(context: _MaterializationContext) -> str:
+    """The approved plan path when this run recorded one, otherwise empty.
+
+    `_required_approved_plan_path` speaks for implementation, where a missing
+    plan is a contract violation. An acceptance verifier enumerates the same
+    file as an input, and a run prepared without one still has to produce a
+    prompt — so the absence is reported by the empty line being dropped, not by
+    refusing to materialize.
+    """
+    try:
+        return _required_approved_plan_path(context)
+    except InitialPromptMaterializationError:
+        return ""
+
+
 def _required_stage_number(context: _MaterializationContext) -> str:
     value = _string_value(_active_run_field(context, "stage"))
     if not value:

package/runtime/python/okstra_ctl/interactive_cli.py

@@ -0,0 +1,223 @@
+"""`okstra.sh` 대화형 입력 경로가 쓰는 조회 헬퍼들.
+
+이 여섯 갈래는 원래 `scripts/lib/okstra/interactive.sh` 의 파이썬 heredoc 안에
+있었다(docs/coding-rules.md R1 위반). 셸 문자열 안에 있는 동안에는 import 도
+테스트도 할 수 없었다. 로직과 출력 형식은 그대로 옮겼다 — 호출부의 파서를
+건드리지 않기 위해서다.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+from . import next_phase
+from .ids import slugify_task_segment
+from .implementation_outcome import reconcile_implementation_outcome
+from .json_boundary import JsonBoundaryError, load_owned_object
+from .paths import RunRef, task_dir
+from .run_context import latest_run_inputs
+
+
+def _resolve_task_root(args: argparse.Namespace) -> int:
+    """`OK\\t<abs>` 또는 `MISSING` + 진단 줄들.
+
+    task root 의 slug 경로 구성은 `paths.task_dir` 이 단일 기준점이다. 예전에
+    이 코드는 slugify 와 `.okstra/tasks/<slug>/<slug>` 구조를 자체 재구현해
+    규칙이 바뀌면 조용히 어긋날 수 있었다.
+    """
+    project_root = Path(args.project_root)
+    requested_key = f"{args.project_id}:{args.task_group}:{args.task_id}"
+    requested_key_ci = requested_key.lower()
+
+    candidates: list[str] = []
+    catalog_keys: list[str] = []
+
+    catalog_path = project_root / ".okstra" / "discovery" / "task-catalog.json"
+    if catalog_path.is_file():
+        try:
+            catalog = load_owned_object(catalog_path, artifact="task catalog")
+        except JsonBoundaryError as exc:
+            sys.stderr.write(f"resolve_task_root: failed to parse {catalog_path}: {exc}\n")
+            catalog = None
+        if isinstance(catalog, dict):
+            catalog_project_id = catalog.get("projectId")
+            for entry in catalog.get("tasks") or []:
+                if not isinstance(entry, dict):
+                    continue
+                entry_key = entry.get("taskKey") or ""
+                if not isinstance(entry_key, str) or not entry_key:
+                    continue
+                belongs = (
+                    catalog_project_id == args.project_id
+                    or entry.get("projectId") == args.project_id
+                    or entry_key.startswith(f"{args.project_id}:")
+                )
+                if belongs:
+                    catalog_keys.append(entry_key)
+                if entry_key.lower() != requested_key_ci:
+                    continue
+                rel = entry.get("taskRootPath") or entry.get("taskRoot")
+                if isinstance(rel, str) and rel:
+                    abs_path = (
+                        Path(rel) if os.path.isabs(rel)
+                        else (project_root / rel).resolve()
+                    )
+                    if abs_path.is_dir():
+                        print(f"OK\t{abs_path}")
+                        return 0
+                    candidates.append(str(abs_path))
+
+    slug_path = task_dir(project_root, args.task_group, args.task_id)
+    if slug_path.is_dir():
+        print(f"OK\t{slug_path}")
+        return 0
+    candidates.append(str(slug_path))
+
+    print("MISSING")
+    print(f"REQUESTED\t{requested_key}")
+    for candidate in candidates:
+        print(f"TRIED\t{candidate}")
+    for key in sorted(set(catalog_keys)):
+        print(f"AVAILABLE\t{key}")
+    return 0
+
+
+def _reconcile_outcome(args: argparse.Namespace) -> int:
+    """구현 결과 화해. 편의 기능이라 실패해도 run 을 끊지 않는다."""
+    try:
+        reconcile_implementation_outcome(Path(args.project_root), Path(args.task_root))
+    except Exception as exc:  # noqa: BLE001 - 아래에서 신호를 남긴다
+        # expected-miss: 화해는 편의 기능이고 호출부(okstra.sh)는 `set -e` 아래
+        # 있다. 여기서 던지면 평범한 run 이 통째로 중단된다. 대신 stderr 로
+        # 남겨 삼킨 사실이 보이게 한다.
+        sys.stderr.write(f"reconcile-outcome: skipped ({exc})\n")
+    return 0
+
+
+def _autofill(args: argparse.Namespace) -> int:
+    """`BRIEF=<v>` / `TYPE=<v>` 두 줄. 매니페스트를 못 읽으면 빈 값."""
+    try:
+        data = load_owned_object(Path(args.manifest), artifact="task manifest")
+    except JsonBoundaryError as exc:
+        sys.stderr.write(f"autofill_from_manifest: failed to parse {args.manifest}: {exc}\n")
+        return 0
+
+    brief = ""
+    task_type = ""
+    if args.need_brief:
+        brief = (data.get("taskBriefPath") or "").strip()
+    if args.need_type:
+        # 포인터 판정은 파이썬이 갖는다 — `ready` 가 아니면 빈 문자열이라
+        # 셸이 센티널 목록을 따로 들고 있을 이유가 없다.
+        task_type = next_phase.autofill_task_type(data)
+    print(f"BRIEF={brief}")
+    print(f"TYPE={task_type}")
+    return 0
+
+
+def _latest_report(args: argparse.Namespace) -> int:
+    """`<report>\\t<task_type>` 한 줄. 없으면 아무것도 내지 않는다."""
+    types = (
+        (args.task_type,) if args.task_type
+        else ("error-analysis", "requirements-discovery")
+    )
+    ref = RunRef.latest_under(args.task_root, types)
+    if ref is not None:
+        sys.stdout.write(f"{ref.report}\t{ref.task_type}")
+    return 0
+
+
+def _manifest_brief(args: argparse.Namespace) -> int:
+    """매니페스트의 `taskBriefPath` 한 줄."""
+    try:
+        data = load_owned_object(Path(args.manifest), artifact="task manifest")
+    except JsonBoundaryError as exc:
+        sys.stderr.write(f"manifest-brief: failed to parse {args.manifest}: {exc}\n")
+        return 1
+    print((data.get("taskBriefPath") or "").strip())
+    return 0
+
+
+def _resume_args(args: argparse.Namespace) -> int:
+    """직전 run 의 인자들을 NUL 로 구분해 흘린다(셸의 `read -d ''` 용).
+
+    `default` 와 빈 값은 phase 기본값을 뜻하므로 넘기지 않는다 — 명시 플래그로
+    고정하면 다음 run 이 기본값 변경을 못 받는다.
+    """
+    inputs = latest_run_inputs(
+        args.project_root, args.task_group, args.task_id,
+        phase_segment=slugify_task_segment(args.task_type),
+    )
+
+    def emit(flag: str, value: str) -> None:
+        if value:
+            sys.stdout.write(flag + "\0" + value + "\0")
+
+    def model(value: object) -> str:
+        return value if isinstance(value, str) and value not in ("", "default") else ""
+
+    workers = inputs.get("workers")
+    if isinstance(workers, list):
+        workers = ",".join(w for w in workers if isinstance(w, str))
+    elif not isinstance(workers, str):
+        workers = ""
+    emit("--workers", workers)
+    emit("--lead-model", model(inputs.get("leadModel")))
+    emit("--claude-model", model(inputs.get("claudeModel")))
+    emit("--codex-model", model(inputs.get("codexModel")))
+    emit("--antigravity-model", model(inputs.get("antigravityModel")))
+    emit("--report-writer-model", model(inputs.get("reportWriterModel")))
+    directive = inputs.get("directive")
+    emit("--directive", directive if isinstance(directive, str) else "")
+    related = inputs.get("relatedTasks")
+    emit("--related-tasks", related if isinstance(related, str) else "")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="okstra interactive")
+    sub = parser.add_subparsers(dest="op", required=True)
+
+    resolve = sub.add_parser("resolve-task-root")
+    resolve.add_argument("--project-root", required=True)
+    resolve.add_argument("--project-id", required=True)
+    resolve.add_argument("--task-group", required=True)
+    resolve.add_argument("--task-id", required=True)
+    resolve.set_defaults(handler=_resolve_task_root)
+
+    reconcile = sub.add_parser("reconcile-outcome")
+    reconcile.add_argument("--project-root", required=True)
+    reconcile.add_argument("--task-root", required=True)
+    reconcile.set_defaults(handler=_reconcile_outcome)
+
+    autofill = sub.add_parser("autofill")
+    autofill.add_argument("--manifest", required=True)
+    autofill.add_argument("--need-brief", action="store_true")
+    autofill.add_argument("--need-type", action="store_true")
+    autofill.set_defaults(handler=_autofill)
+
+    latest = sub.add_parser("latest-report")
+    latest.add_argument("--task-root", required=True)
+    latest.add_argument("--task-type", default="")
+    latest.set_defaults(handler=_latest_report)
+
+    brief = sub.add_parser("manifest-brief")
+    brief.add_argument("--manifest", required=True)
+    brief.set_defaults(handler=_manifest_brief)
+
+    resume = sub.add_parser("resume-args")
+    resume.add_argument("--project-root", required=True)
+    resume.add_argument("--task-group", required=True)
+    resume.add_argument("--task-id", required=True)
+    resume.add_argument("--task-type", required=True)
+    resume.set_defaults(handler=_resume_args)
+
+    args = parser.parse_args(argv)
+    return args.handler(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/python/okstra_ctl/json_boundary.py

@@ -163,6 +163,16 @@ def external_claude_team_json_source(path: Path) -> ExternalJsonSource:
     return _issue_external_source(path, "Claude Code")
 
 
+def external_codex_catalog_json_source(
+    path: Path, codex_home: Path
+) -> ExternalJsonSource:
+    """호출자가 지정한 codex home의 모델 카탈로그 캐시만 승인한다."""
+    expected = codex_home / "models_cache.json"
+    if Path(os.path.abspath(path)) != Path(os.path.abspath(expected)) or path.is_symlink():
+        raise JsonBoundaryError(path, "codex model catalog", "outside codex home")
+    return _issue_external_source(path, "codex CLI")
+
+
 def external_tool_json_source(path: Path, workspace_root: Path) -> ExternalJsonSource:
     """외부 도구가 workspace의 비-Okstra 경로에 쓴 보고서만 승인한다."""
     try: