okstra 0.225.0 → 0.226.0

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}")
@@ -539,7 +547,7 @@ def spawn_worker_surface(
         # 호출이 반환되기 전에는 명부에 창 식별자가 없다. 여기서 정리하지
         # 않으면 대체 실행으로 전환된 뒤에도 회수할 수 없는 창이 남는다.
         try:
-            closed = run_cmux(["close-surface", "--surface", surface_uuid])
+            closed = run_cmux(["close-surface", "--surface", surface_uuid, "--force"])
             if closed.returncode != 0:
                 raise RuntimeError(closed.stderr.strip() or "cmux close failed")
         except (RuntimeError, OSError, subprocess.SubprocessError) as cleanup_error:
@@ -610,8 +618,10 @@ def rename_lead_surface(title: str) -> str:
 
 def close_surface(surface_uuid: str) -> None:
     """Close an okstra-created surface, killing whatever still runs inside it."""
+    # cmux 는 살아 있는 프로세스가 있는 창을 `--force` 없이 닫지 않는다
+    # (`confirmation_required`). 막 분할된 창의 로그인 셸도 그 프로세스로 센다.
     try:
-        run_cmux(["close-surface", "--surface", surface_uuid])
+        run_cmux(["close-surface", "--surface", surface_uuid, "--force"])
     except (OSError, subprocess.SubprocessError):
         return
 
@@ -849,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/code_review_coverage.py

@@ -87,7 +87,7 @@ def _keyed_values(text: str) -> dict[str, str]:
 
 
 def _source_evidence(project_root: Path, cell: ReviewCell, evidence: str) -> str:
-    match = re.fullmatch(r"(.+):([1-9][0-9]*)", evidence.strip("`"))
+    match = re.fullmatch(r"(.+?):([1-9][0-9]*)`?(?: — .+)?", evidence.strip("`"))
     target = cell.target.partition(":")[0]
     if match is None or match[1] != target:
         raise ValueError("evidence must cite the target source path:line")
@@ -103,6 +103,30 @@ def _source_evidence(project_root: Path, cell: ReviewCell, evidence: str) -> str
     return evidence
 
 
+def _checked_rule_evidence(
+    project_root: Path, cell: ReviewCell, checked: Sequence[str], text: str,
+) -> str:
+    anchor, _, raw = text.partition(" :: ")
+    _source_evidence(project_root, cell, anchor)
+    observations = _keyed_values(raw.strip() or "-")
+    required = set(checked) & {"G2", "G3", "G5"} if cell.group == "general" else set()
+    missing = required - observations.keys()
+    if missing:
+        raise ValueError("missing clean check evidence: " + ", ".join(sorted(missing)))
+    if observations.keys() - set(checked):
+        raise ValueError("clean check evidence names an unchecked rule")
+    for observation in observations.values():
+        match = re.fullmatch(r"(`?.+?:[1-9][0-9]*`?) (.+)", observation)
+        if match is None:
+            raise ValueError("clean check evidence needs source path:line and an observation")
+        if re.fullmatch(r"(?:checked|clean|no issues?|none|n/?a)", match[2], re.I):
+            raise ValueError("clean check evidence needs an observation, not a verdict label")
+        citation = match[1].strip("`")
+        source_cell = ReviewCell(citation.partition(":")[0], cell.group)
+        _source_evidence(project_root, source_cell, citation)
+    return text
+
+
 def _group_verdict(
     fields: Sequence[str], expected: Sequence[str], cell: ReviewCell,
     project_root: Path, references: Sequence[str],
@@ -131,7 +155,7 @@ def _group_verdict(
                 raise ValueError("invalid finding ID")
             if not any(id_occurs_wordbounded(body, item) for body in references):
                 raise ValueError(f"finding {item} has no finding body")
-    evidence = _source_evidence(project_root, cell, fields[4])
+    evidence = _checked_rule_evidence(project_root, cell, checked, fields[4])
     if findings:
         return "finding", "; ".join(findings.values())
     if checked:

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,

package/runtime/python/okstra_ctl/initial_prompt_materialization.py

@@ -40,8 +40,10 @@ from .worker_prompt_body import (
 )
 from .worker_prompt_contract import PromptRecord, validate_initial_prompt_records
 from .worker_prompt_headers import source_worktree_headers, worker_prompt_headers
+from .approved_plan_stage_extract import StageExtractError, materialize_stage_extract
 from .worker_prompt_policy import (
     APPROVED_PLAN_HEADER,
+    APPROVED_PLAN_STAGE_EXTRACT_HEADER,
     IMPLEMENTATION_STAGE_HEADER,
     STAGE_QA_OWNER_HEADER,
     PromptPlan,
@@ -720,6 +722,11 @@ def _prompt_body(
         plan,
         _optional_approved_plan_path(context) if plan.include_approved_plan else "",
         _selected_direction_path(context) if plan.include_selected_direction else "",
+        (
+            _approved_plan_stage_extract(context)
+            if plan.audience == "implementation-executor"
+            else ""
+        ),
     )
 
 
@@ -1466,6 +1473,10 @@ def _implementation_anchor_lines(
     lines.append(
         f"{APPROVED_PLAN_HEADER} {_required_approved_plan_path(context)}"
     )
+    if plan.audience == "implementation-executor":
+        extract = _approved_plan_stage_extract(context)
+        if extract:
+            lines.append(f"{APPROVED_PLAN_STAGE_EXTRACT_HEADER} {extract}")
     lines.append(
         f"{IMPLEMENTATION_STAGE_HEADER} {_required_stage_number(context)}"
     )
@@ -1526,6 +1537,36 @@ def _required_approved_plan_path(context: _MaterializationContext) -> str:
     return str(_resolve_input_path(context.project_root, Path(value)))
 
 
+def _approved_plan_stage_extract(context: _MaterializationContext) -> str:
+    """Write this run's stage extract of the approved plan; its project path.
+
+    Empty when the plan is not a report record (see `materialize_stage_extract`),
+    and the executor then reads the plan itself.
+    """
+    stage = _required_stage_number(context)
+    if not stage.isdigit():
+        raise InitialPromptMaterializationError(
+            "required_input_missing",
+            f"implementation stage is not a stage number: {stage}",
+        )
+    active_context_path = _resolve_input_path(
+        context.project_root,
+        Path(_required_string(context.manifest, "activeRunContextPath")),
+    )
+    suffix = active_context_path.name.removeprefix("active-run-context-")
+    output = active_context_path.with_name(f"approved-plan-stage-{stage}-{suffix}")
+    try:
+        written = materialize_stage_extract(
+            Path(_required_approved_plan_path(context)), int(stage), output
+        )
+    except (StageExtractError, JsonBoundaryError) as exc:
+        raise InitialPromptMaterializationError(
+            "required_input_missing",
+            f"cannot project the approved plan onto stage {stage}: {exc}",
+        ) from exc
+    return _project_relative(context.project_root, output) if written else ""
+
+
 def _optional_approved_plan_path(context: _MaterializationContext) -> str:
     """The approved plan path when this run recorded one, otherwise empty.