okstra 0.225.1 → 0.226.0

package/runtime/python/okstra_ctl/approved_plan_stage_extract.py

@@ -0,0 +1,206 @@
+"""Project an approved implementation-planning report onto one stage.
+
+An implementation executor owns exactly one stage, but its prompt pointed it at
+the whole plan record. Measured 2026-10-30 (fontradar-v2-api dev-11562 stage 1):
+that record was 7,465 lines / 385 KB, 94 KB of it the planning phase's own
+verification ledger, and a codex executor reported `contract-violated` because
+its reads overran the CLI's tool-output limit before it made an edit.
+
+The extract keeps everything the stage can act on and drops only what is named
+in `OMITTED`, each with the reason, so a reader can tell an omission from a gap.
+Rows of a row family keep the stage's rows plus every row that names no stage
+(`plan_items._stage_scope` reads that as "applies to every stage"), and every
+row carries the `P-*` id the plan-body verification and lead directives cite it
+by. The full record stays the source of record behind `sourcePlanPath`.
+"""
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any, Mapping
+
+from .json_boundary import load_owned_object, write_owned_object_atomic
+from .plan_items import PLAN_ITEM_SOURCES
+
+EXTRACT_KIND = "approved-plan-stage-extract"
+EXTRACT_SCHEMA_VERSION = 1
+
+# implementationPlanning row families filtered to the stage. Every other
+# implementationPlanning key is carried whole unless OMITTED names it.
+_STAGE_ROW_FAMILIES = (
+    "requirementCoverage",
+    "validationChecklist",
+    "rollbackStrategy",
+    "dependencyMigrationRisk",
+    "crossProjectDependencies",
+)
+# plan_items numbers a row family by position (`P-Val-4` is the fourth
+# validation row); a filtered list loses the position, so the id travels on the row.
+_PLAN_ITEM_PREFIX = {
+    family: prefix for family, prefix, _ in PLAN_ITEM_SOURCES
+    if family in _STAGE_ROW_FAMILIES
+}
+# Top-level report keys an executor acts on. Everything else at the top level is
+# report presentation, audit, or accounting and is listed in OMITTED.
+_CARRIED_REPORT_KEYS = (
+    "clarificationItems",
+    "clarificationCarryIn",
+    "endStateCoverage",
+    "missingInformation",
+    "followUpTasks",
+)
+OMITTED = {
+    "implementationPlanning.planBodyVerification": (
+        "the planning phase's verification ledger (verdicts and dissent per plan "
+        "item); the plan body above is its settled result"
+    ),
+    "implementationPlanning.designPreparation": (
+        "the stage-scoped effective decision is inlined in the executor prompt "
+        "under Effective design preparation"
+    ),
+    "implementationPlanning.userNarrative": "plain-language explanation for the human reader",
+    "implementationPlanning.stages[other]": "stages this run does not own; their Stage Map rows stay",
+    "implementationPlanning.directionRealization.fileStructure[other]": (
+        "file rows whose path this stage's entry never names"
+    ),
+    "<rows of another stage>": (
+        "requirementCoverage / validationChecklist / rollbackStrategy / "
+        "dependencyMigrationRisk / crossProjectDependencies rows whose stageRefs "
+        "exclude this stage and whose id this stage's entry never cites"
+    ),
+    "humanSummary, verdictCard, rationale, summary, finalVerdict, recommendedNextSteps": (
+        "report presentation for the approver"
+    ),
+    "crossVerification, agentActivity, evidence, executionStatus, executionRoles, tokenUsage": (
+        "planning-run audit and accounting"
+    ),
+    "meta, frontmatter, header": "report identity",
+}
+
+
+class StageExtractError(ValueError):
+    """The approved plan cannot be projected onto the requested stage."""
+
+
+def stage_extract_payload(
+    report: Mapping[str, Any],
+    stage_number: int,
+    source_plan_path: str,
+) -> dict[str, Any]:
+    planning = report.get("implementationPlanning")
+    if not isinstance(planning, Mapping):
+        raise StageExtractError("approved plan has no implementationPlanning object")
+    stage_entry = _stage_entry(planning, stage_number)
+    cited_text = json.dumps(stage_entry, ensure_ascii=False)
+    carried_planning: dict[str, Any] = {}
+    for key, value in planning.items():
+        if f"implementationPlanning.{key}" in OMITTED:
+            continue
+        if key == "stages":
+            carried_planning[key] = [stage_entry]
+        elif key in _STAGE_ROW_FAMILIES:
+            carried_planning[key] = _stage_rows(value, key, stage_number, cited_text)
+        elif key == "directionRealization" and isinstance(value, Mapping):
+            carried_planning[key] = _direction_realization(value, cited_text)
+        else:
+            carried_planning[key] = value
+    payload: dict[str, Any] = {
+        "kind": EXTRACT_KIND,
+        "schemaVersion": EXTRACT_SCHEMA_VERSION,
+        "sourcePlanPath": source_plan_path,
+        "stage": stage_number,
+        "planItemIds": (
+            "Rows carry their plan item id as `planItemId`. `P-Step-<stage>.<step>` "
+            "names step <step> of that stage's `stepwiseExecution`."
+        ),
+        "omitted": dict(OMITTED),
+        "implementationPlanning": carried_planning,
+    }
+    for key in _CARRIED_REPORT_KEYS:
+        if key in report:
+            payload[key] = report[key]
+    return payload
+
+
+def materialize_stage_extract(
+    plan_path: Path,
+    stage_number: int,
+    output_path: Path,
+) -> bool:
+    """Write the extract for a `.data.json` plan; False when the plan is not one.
+
+    A Markdown plan predates the report record and has no structure to project,
+    and a missing file is reported by the prompt's own plan anchor, so neither
+    is an error here — the executor reads the plan as it did before.
+    """
+    if not plan_path.name.endswith(".data.json") or not plan_path.is_file():
+        return False
+    report = load_owned_object(plan_path, artifact="approved implementation plan")
+    payload = stage_extract_payload(report, stage_number, str(plan_path))
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    write_owned_object_atomic(output_path, payload, artifact="approved plan stage extract")
+    return True
+
+
+def _stage_entry(planning: Mapping[str, Any], stage_number: int) -> Mapping[str, Any]:
+    stages = planning.get("stages")
+    if not isinstance(stages, list):
+        raise StageExtractError("approved plan has no stages array")
+    for entry in stages:
+        if isinstance(entry, Mapping) and entry.get("stage") == stage_number:
+            return entry
+    raise StageExtractError(f"approved plan has no stage {stage_number}")
+
+
+def _stage_rows(
+    rows: Any,
+    family: str,
+    stage_number: int,
+    cited_text: str,
+) -> list[Any]:
+    if not isinstance(rows, list):
+        return rows
+    kept = []
+    for position, row in enumerate(rows, start=1):
+        if not isinstance(row, Mapping):
+            kept.append(row)
+            continue
+        if not _row_applies(row, stage_number, cited_text):
+            continue
+        prefix = _PLAN_ITEM_PREFIX.get(family)
+        kept.append(
+            {"planItemId": f"{prefix}-{position}", **row} if prefix else dict(row)
+        )
+    return kept
+
+
+def _row_applies(row: Mapping[str, Any], stage_number: int, cited_text: str) -> bool:
+    refs = row.get("stageRefs")
+    stages = (
+        [value for value in refs if isinstance(value, int) and not isinstance(value, bool)]
+        if isinstance(refs, list) else []
+    )
+    if not stages or stage_number in stages:
+        return True
+    row_id = row.get("id")
+    return isinstance(row_id, str) and bool(row_id) and _cites(cited_text, row_id)
+
+
+def _direction_realization(
+    realization: Mapping[str, Any], cited_text: str
+) -> dict[str, Any]:
+    carried = dict(realization)
+    rows = realization.get("fileStructure")
+    if isinstance(rows, list):
+        carried["fileStructure"] = [
+            row for row in rows
+            if not isinstance(row, Mapping)
+            or not isinstance(row.get("path"), str)
+            or row["path"] in cited_text
+        ]
+    return carried
+
+
+def _cites(text: str, identifier: str) -> bool:
+    return re.search(rf"(?<![\w-]){re.escape(identifier)}(?![\w-])", text) is not None

package/runtime/python/okstra_ctl/brief_sources.py

@@ -0,0 +1,200 @@
+"""브리프 본문이 인용한 로컬 문서와 Source Material 항목을 맞춘다.
+
+task worktree 는 체크아웃이라 프로젝트 루트의 git 미추적 파일(`.project-docs/` 스펙)이
+없다. prepare 는 Source Material 의 `### Source N — file` 항목만 읽어 패킷에 싣으므로
+(`analysis_packet.cited_documents_block`), 본문에만 이름이 나온 미추적 문서는 워커에게
+닿지 않는다(fontradar dev-11562). `uncited_local_documents` 는 그런 경로를 찾고,
+`validators/validate-brief.py` 가 이를 거절한다. `attach_missing_sources` 는 기존
+브리프에 빠진 항목을 `format: by-reference` 로 덧붙인다. 다른 줄은 바꾸지 않는다.
+"""
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+from .analysis_packet import BY_REFERENCE_FORMAT, _fence_mask, _section_map, file_source_entries
+
+SOURCE_MATERIAL = "Source Material"
+ATTACH_FETCHED_VIA = "okstra brief-sources attach"
+_HTML_COMMENT_RE = re.compile(r"<!--.*?-->", re.DOTALL)
+_FRONTMATTER_RE = re.compile(r"\A---\n.*?\n---\n", re.DOTALL)
+_TOKEN_RE = re.compile(r"[^\s`'\"()\[\]<>{},;|*]+")
+_LINE_SUFFIX_RE = re.compile(r"(?::\d+(?:-\d+)?|#L\d+(?:-L?\d+)?)\Z")
+_SOURCE_NUMBER_RE = re.compile(r"\A### Source (\d+)\b")
+# okstra 자신의 산출물(브리프, 그룹 맥락, 보고서)은 okstra 가 직접 운반한다.
+_OKSTRA_HOME = ".okstra"
+# 문서만 본다. 미추적 코드 경로(`node_modules/` 타입 선언 등)는 설치로 다시 생기는 근거라
+# 브리프의 출처 문서가 아니다.
+DOCUMENT_SUFFIXES = frozenset({".md", ".markdown", ".txt", ".rst", ".adoc"})
+
+
+def _body_lines(text: str) -> list[str]:
+    return _FRONTMATTER_RE.sub("", _HTML_COMMENT_RE.sub("", text), count=1).splitlines()
+
+
+def _project_file(token: str, root: Path) -> str | None:
+    """토큰이 프로젝트 루트 아래 파일을 가리키면 루트 기준 posix 경로를 돌려준다."""
+    if "/" not in token or "://" in token:
+        return None
+    token = _LINE_SUFFIX_RE.sub("", token.rstrip(".:"))
+    candidate = Path(token).expanduser()
+    path = (candidate if candidate.is_absolute() else root / candidate).resolve()
+    try:
+        relative = path.relative_to(root)
+    except ValueError:
+        return None
+    if (not relative.parts or relative.parts[0] == _OKSTRA_HOME
+            or path.suffix.lower() not in DOCUMENT_SUFFIXES or not path.is_file()):
+        return None
+    return relative.as_posix()
+
+
+def _cited_in_body(text: str, root: Path) -> list[str]:
+    paths: dict[str, None] = {}
+    lines = _body_lines(text)
+    section = ""
+    for line, fenced in zip(lines, _fence_mask(lines)):
+        if fenced:
+            continue
+        if line.startswith("## "):
+            section = line[3:].strip()
+            continue
+        if section == SOURCE_MATERIAL:
+            continue
+        for token in _TOKEN_RE.findall(line):
+            if (relative := _project_file(token, root)) is not None:
+                paths.setdefault(relative)
+    return list(paths)
+
+
+def _sourced(text: str, root: Path) -> set[str]:
+    source_material = _section_map(_HTML_COMMENT_RE.sub("", text)).get(SOURCE_MATERIAL, "")
+    return {
+        relative
+        for ref, _ in file_source_entries(source_material)
+        for token in _TOKEN_RE.findall(ref)
+        if (relative := _project_file(token, root)) is not None
+    }
+
+
+def _git_tracked(root: Path, paths: list[str]) -> set[str] | None:
+    """`paths` 중 git 이 추적하는 것. git 저장소가 아니면 None — worktree 가 없으니 검사할 것도 없다."""
+    proc = subprocess.run(
+        ["git", "-C", str(root), "ls-files", "-z", "--", *paths],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if proc.returncode != 0:
+        return None
+    return {name for name in proc.stdout.split("\0") if name}
+
+
+def uncited_local_documents(text: str, project_root: Path) -> list[str]:
+    """본문이 이름을 댄 git 미추적 프로젝트 파일 중 Source Material 의 file 항목이 없는 것."""
+    root = project_root.resolve()
+    cited = [path for path in _cited_in_body(text, root) if path not in _sourced(text, root)]
+    if not cited:
+        return []
+    tracked = _git_tracked(root, cited)
+    if tracked is None:
+        return []
+    return [path for path in cited if path not in tracked]
+
+
+def _source_entry(index: int, ref: str, fetched_at: str) -> list[str]:
+    return [
+        f"### Source {index} — file",
+        "",
+        f"- ref: {ref}",
+        f"- fetched-via: {ATTACH_FETCHED_VIA}",
+        f"- fetched-at: {fetched_at}",
+        f"- format: {BY_REFERENCE_FORMAT}",
+        "",
+        "```",
+        "```",
+        "",
+    ]
+
+
+def attach_missing_sources(brief_path: Path, project_root: Path, *, now: dt.datetime) -> list[str]:
+    """빠진 file 항목을 Source Material 끝에 덧붙이고 덧붙인 경로를 돌려준다."""
+    text = brief_path.read_text(encoding="utf-8")
+    missing = uncited_local_documents(text, project_root)
+    if not missing:
+        return []
+    lines = text.split("\n")
+    mask = _fence_mask(lines)
+    start = next(
+        (i for i, (line, fenced) in enumerate(zip(lines, mask))
+         if not fenced and line.strip() == f"## {SOURCE_MATERIAL}"),
+        None,
+    )
+    if start is None:
+        raise ValueError(f"{brief_path}: no `## {SOURCE_MATERIAL}` section to attach to")
+    end = next(
+        (i for i in range(start + 1, len(lines)) if not mask[i] and lines[i].startswith("## ")),
+        len(lines),
+    )
+    numbers = [int(m.group(1)) for i in range(start + 1, end) if not mask[i]
+               if (m := _SOURCE_NUMBER_RE.match(lines[i]))]
+    while end > start + 1 and not lines[end - 1].strip():
+        end -= 1
+    stamp = now.strftime("%Y-%m-%d %H:%M")
+    entries: list[str] = [""]
+    for offset, ref in enumerate(missing, max(numbers, default=0) + 1):
+        entries.extend(_source_entry(offset, ref, stamp))
+    tail = lines[end:]
+    while tail and not tail[0].strip():
+        tail.pop(0)
+    brief_path.write_text("\n".join([*lines[:end], *entries, *tail]), encoding="utf-8")
+    return missing
+
+
+def _attach_command(args: argparse.Namespace) -> int:
+    brief = Path(args.brief).resolve()
+    try:
+        added = attach_missing_sources(brief, Path(args.project_root), now=dt.datetime.now())
+    except ValueError as exc:
+        print(f"brief-sources: {exc}", file=sys.stderr)
+        return 2
+    if not added:
+        print(f"brief-sources: nothing to attach in {brief}")
+        return 0
+    print(f"brief-sources: attached {len(added)} Source Material entr{'y' if len(added) == 1 else 'ies'} to {brief}")
+    for path in added:
+        print(f"  - {path} (format: {BY_REFERENCE_FORMAT})")
+    print("Every later prepare copies these files read-only into the analysis packet's `## Cited Local Documents`.")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="okstra brief-sources",
+        description=(
+            "Give every untracked project file a brief's body cites its own "
+            "Source Material entry, so runs copy it into the analysis packet."
+        ),
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+    attach = sub.add_parser(
+        "attach",
+        help="append a by-reference `### Source N — file` entry for each cited untracked file; edits nothing else",
+    )
+    attach.add_argument("--project-root", required=True, help="project root that holds `.okstra/`")
+    attach.add_argument("--brief", required=True, help="brief markdown file to upgrade in place")
+    attach.set_defaults(func=_attach_command)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/runtime/python/okstra_ctl/business_flow/store.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import re
+from collections import Counter
 from pathlib import Path
 from typing import Any, cast
 
@@ -27,6 +28,7 @@ from .contracts import (
 from .source import candidate_projects, capture_project
 
 CONFIRMED_LEVELS = frozenset({"static", "execution-verified"})
+PACKET_CLAIM_LIMIT = 40
 
 
 def task_link_path(project_root: Path, task_key: str) -> Path:
@@ -355,17 +357,22 @@ def knowledge_packet(
         result = query_knowledge(project_root, question, source_root)
     except (OSError, BusinessFlowError, JsonBoundaryError) as exc:
         return f"## Shared Business Knowledge\n\nKnowledge unavailable: {exc}\n"
+    # 질문이 task-brief 전체라 토큰 매칭이 거의 모든 claim 을 고르므로, 선택 결과는
+    # 관련도 순위가 아니다. 이 프로젝트가 기록한 claim 을 앞세우고 나머지는 조회로 넘긴다.
+    own = str(project_root.resolve())
+    claims = sorted(result["claims"], key=lambda row: row["ownerRoot"] != own)
+    shown, omitted = claims[:PACKET_CLAIM_LIMIT], claims[PACKET_CLAIM_LIMIT:]
     lines = [
         "## Shared Business Knowledge",
         "",
         "Preserve level, freshness, conflict and provenance. Recheck historical facts before relying on them.",
         "",
     ]
-    if not result["claims"]:
+    if not claims:
         lines.append(
             "No related stored claims were selected. Inspect source and use additional lookup when new business terms emerge."
         )
-    for row in result["claims"]:
+    for row in shown:
         lines.extend(
             [
                 f"- `{row['id']}`: {row['value']}",
@@ -377,6 +384,12 @@ def knowledge_packet(
             f"  - Evidence: `{item['projectId']}:{item['path']}:{item['line']}`"
             for item in row["evidence"]
         )
+    if omitted:
+        counts = Counter(row["business"] for row in omitted)
+        lines.append(
+            f"- {len(omitted)} more selected claims are omitted; look them up by business: "
+            + ", ".join(f"`{name}` ({count})" for name, count in counts.most_common())
+        )
     lines.extend(f"- Knowledge read error: {error}" for error in result["errors"])
     lines.extend(
         [

package/runtime/python/okstra_ctl/cmux.py

@@ -12,6 +12,7 @@ import shlex
 import shutil
 import socket
 import subprocess
+import time
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Collection, Mapping, Sequence
@@ -73,6 +74,13 @@ SOCKET_UNREACHABLE = "unreachable"
 
 SOCKET_PROBE_TIMEOUT_SECONDS = 2
 
+# 막 분할한 창에 보낸 `respawn-pane` 이 답 없이 소켓이 닫히는 경우가 있다. 실측
+# 2026-10-29, dev-11562 두 run: 탭 이름은 붙었는데 창에는 첫 로그인 셸만 남았다.
+# 그 창은 워커를 시작하지 않았으므로 같은 명령을 다시 보내도 워커가 둘이 되지 않는다.
+TRANSIENT_SOCKET_ERROR = "Socket closed before reply"
+RESPAWN_ATTEMPTS = 3
+RESPAWN_RETRY_DELAY_SECONDS = 0.5
+
 # cmux 가 돌려주는 식별자가 UUID 인지 ref 인지 가리는 자리. ref 는 번호가 다시
 # 매겨지므로 원장에 남길 수 없다.
 _UUID_PATTERN = re.compile(r"[0-9A-Fa-f]{8}(?:-[0-9A-Fa-f]{4}){3}-[0-9A-Fa-f]{12}")
@@ -851,9 +859,16 @@ def _exec_worker(surface_uuid: str, *, cwd: Path, command: Sequence[str]) -> Non
     line = worker_command_line(
         cwd=cwd, argv=command, path_value=shim_free_worker_path()
     )
-    started = run_cmux(["respawn-pane", "--surface", surface_uuid, "--command", line])
-    if started.returncode != 0:
-        raise RuntimeError(started.stderr.strip() or "cmux could not start the worker")
+    for attempt in range(1, RESPAWN_ATTEMPTS + 1):
+        started = run_cmux(["respawn-pane", "--surface", surface_uuid, "--command", line])
+        if started.returncode == 0:
+            return
+        error = started.stderr.strip()
+        if TRANSIENT_SOCKET_ERROR not in error or attempt == RESPAWN_ATTEMPTS:
+            raise RuntimeError(
+                f"respawn-pane: {error or 'cmux could not start the worker'}"
+            )
+        time.sleep(RESPAWN_RETRY_DELAY_SECONDS)
 
 
 def _size_lead_pane(

package/runtime/python/okstra_ctl/convergence_critic_prompt.py

@@ -296,7 +296,10 @@ verifiers may have missed:
 - requirements / acceptance points with no covering evidence,
 - DB / IO / SQL changes lacking real-execution evidence,
 - regressions or broken error paths,
-- scope / contract violations.
+- scope / contract violations,
+- other locations or cases of a mechanism the analysers already raised (for
+  example the same stale-copy defect in a sibling editor, or after the version
+  changed) — a cell of that class they did not judge is a new candidate.
 A finding that would not stop the release is not a blocker — say so, and it is
 recorded as a conditional-acceptance condition instead. Do NOT restate an existing
 Acceptance Blocker. If you find none, write `No candidate blockers.`

package/runtime/python/okstra_ctl/design_surfaces.py

@@ -242,12 +242,24 @@ def _split_declared_paths(raw: str) -> list[str]:
     return parts
 
 
-def _step_files_cells(step: Mapping[str, Any]) -> list[str]:
+def _step_path_cells(step: Mapping[str, Any]) -> list[str]:
+    """step 이 건드리는 경로를 담은 칸들 — 독자용 `files` 와 쓰기 원장 `plannedPaths`.
+
+    `files` 는 문장이어도 되는 칸이라(profile §Stepwise Execution Order), 경로를
+    `plannedPaths` 에만 적은 계획도 스테이지에 매핑돼야 한다.
+    """
     raw = step.get("files")
     if isinstance(raw, list):
-        return [_normalise(item) for item in raw if item]
-    text = _normalise(raw)
-    return [text] if text else []
+        cells = [_normalise(item) for item in raw if item]
+    else:
+        text = _normalise(raw)
+        cells = [text] if text else []
+    planned = step.get("plannedPaths")
+    for item in planned if isinstance(planned, list) else ():
+        path = _normalise(item).strip().strip("`") if isinstance(item, str) else ""
+        if path:
+            cells.append(path)
+    return cells
 
 
 def _files_cell_tokens(cell: str) -> list[str]:
@@ -282,7 +294,7 @@ def _stages_touching_path(
             cell
             for step in stage.get("stepwiseExecution") or []
             if isinstance(step, Mapping)
-            for cell in _step_files_cells(step)
+            for cell in _step_path_cells(step)
         ]
         if any(_cell_covers_path(cell, path) for cell in cells):
             hits.append(stage_number)
@@ -293,7 +305,7 @@ def _stages_for_selected_path(
     path: str,
     stages: Mapping[int, Mapping[str, Any]],
 ) -> list[int]:
-    """Every stage whose stepwise ``files`` cells touch *path*.
+    """Every stage whose stepwise ``files`` or ``plannedPaths`` cells touch *path*.
 
     A file legitimately edited by more than one stage — the task-level
     ``qa/conformance-manifest.json`` is the standard case, since each
@@ -321,7 +333,7 @@ def _stages_for_selected_path(
         hits = _stages_touching_path(part, stages)
         if not hits and "qa/scripts/" in part:
             # 적합성 스크립트는 executor 가 역할 권한으로 쓴다(write_policy
-            # `_role_qa_artifact_paths`). 계획 step 의 files 칸에는 원래 없다.
+            # `_role_qa_artifact_paths`). 계획 step 의 files·plannedPaths 칸에는 원래 없다.
             continue
         if not hits:
             raise DesignSurfaceError(

package/runtime/python/okstra_ctl/execution_mutation_audit.py

@@ -667,26 +667,34 @@ def _generated_paths(policies: Sequence[WritePolicy]) -> frozenset[str]:
 
 
 def _git_projection(root: Path) -> dict[str, Any]:
+    # 스냅샷은 워커 실행마다 두 번 찍힌다. rev-parse 는 여러 질의를 한 프로세스에서
+    # 줄 단위로 답하므로 질의마다 git 을 띄우지 않는다.
     probe = subprocess.run(
-        ["git", "-C", str(root), "rev-parse", "--is-inside-work-tree"],
+        ["git", "-C", str(root), "rev-parse", "--is-inside-work-tree",
+         "--path-format=absolute", "--git-dir", "--git-common-dir",
+         "--git-path", "index"],
         capture_output=True,
         text=True,
         check=False,
     )
     if probe.returncode != 0:
         return {"available": False}
-    git_dir = Path(_git_output(root, "rev-parse", "--path-format=absolute", "--git-dir"))
-    common_dir = Path(
-        _git_output(root, "rev-parse", "--path-format=absolute", "--git-common-dir")
-    )
+    lines = probe.stdout.splitlines()
+    if len(lines) == 4:
+        _inside, git_dir, common_dir, index_path = (Path(line) for line in lines)
+    else:
+        # 경로 속 줄바꿈은 질의 사이의 줄 경계와 구별되지 않는다. 그때만 경로를 하나씩 묻는다.
+        git_dir, common_dir, index_path = (
+            Path(_git_output(root, "rev-parse", "--path-format=absolute", *query))
+            for query in (("--git-dir",), ("--git-common-dir",), ("--git-path", "index"))
+        )
     branch_ref = _git_output(root, "symbolic-ref", "-q", "HEAD")
-    head = _git_output(root, "rev-parse", "HEAD")
-    index_path = Path(_git_output(root, "rev-parse", "--path-format=absolute", "--git-path", "index"))
+    head, branch_commit = _git_output(root, "rev-parse", "HEAD", branch_ref).splitlines()
     return {
         "available": True,
         "head": head,
         "allowedBranchRef": branch_ref,
-        "branchCommit": _git_output(root, "rev-parse", branch_ref),
+        "branchCommit": branch_commit,
         "gitDir": str(git_dir.resolve()),
         "gitCommonDir": str(common_dir.resolve()),
         "indexDigest": _optional_file_digest(index_path),
@@ -879,21 +887,15 @@ def _branch_switch_paths(
 
 
 def _git_head(root: Path) -> str | None:
-    probe = subprocess.run(
-        ["git", "-C", str(root), "rev-parse", "--is-inside-work-tree"],
-        capture_output=True,
-        text=True,
-        check=False,
-    )
-    if probe.returncode != 0:
-        return None
     head = subprocess.run(
-        ["git", "-C", str(root), "rev-parse", "HEAD"],
+        ["git", "-C", str(root), "rev-parse", "--is-inside-work-tree", "HEAD"],
         capture_output=True,
         text=True,
         check=False,
     )
-    return head.stdout.strip() or None if head.returncode == 0 else None
+    if head.returncode != 0:
+        return None
+    return head.stdout.splitlines()[-1].strip() or None
 
 
 def _allowed_artifact_paths(policies: Sequence[WritePolicy]) -> set[str]:

package/runtime/python/okstra_ctl/implementation_direction.py

@@ -67,6 +67,8 @@ class SelectedDirection:
     direction: dict[str, Any]
     requirement_coverage: tuple[dict[str, Any], ...]
     planning_invariants: tuple[dict[str, Any], ...]
+    deferred_feasibility_facts: tuple[dict[str, Any], ...] = ()
+    split_acceptance: dict[str, Any] | None = None
 
 
 @dataclass(frozen=True)
@@ -400,6 +402,8 @@ def resolve_selected_direction(
         direction=_direction_payload(option),
         requirement_coverage=tuple(_copy_json(option.get("requirementCoverage") or ())),
         planning_invariants=tuple(_copy_json(option.get("planningInvariants") or ())),
+        deferred_feasibility_facts=tuple(_copy_json(option.get("unresolvedFeasibilityFacts") or ())),
+        split_acceptance=_copy_json(option["splitAcceptance"]) if "splitAcceptance" in option else None,
     )
 
 
@@ -424,6 +428,12 @@ def write_selected_direction_snapshot(
         "requirementCoverage": list(direction.requirement_coverage),
         "planningInvariants": list(direction.planning_invariants),
     }
+    # 방향이 유효한 채로 남긴 사실(이후 게이트에서 닫힐 사실, 사용자가 감수한
+    # 위험)은 계획이 일정에 올려야 하므로 스냅샷에 실어 보낸다.
+    if direction.deferred_feasibility_facts:
+        payload["deferredFeasibilityFacts"] = list(direction.deferred_feasibility_facts)
+    if direction.split_acceptance is not None:
+        payload["splitAcceptance"] = direction.split_acceptance
     write_owned_object_atomic(
         destination,
         payload,