okstra 0.159.0 → 0.161.0

package/runtime/validators/validate_session_conformance.py

@@ -6,7 +6,7 @@ Design: docs/superpowers/specs/2026-06-10-blocking-contract-posthoc-conformance-
 |-------|----------|----------|
 | 1. lead PROGRESS checkpoints | prompts/lead/okstra-lead-contract.md "Progress reporting (BLOCKING)" | selected adapter evidence source |
 | 2. worker-provider heartbeat | worker provider contract | audit sidecar `- PROGRESS: <stage> <ISO>` lines |
-| 3. implementation sidecar entry guard | prompts/lead/okstra-lead-contract.md "Entry guard (BLOCKING)" | selected adapter evidence source |
+| 3. implementation entry guard | prompts/lead/okstra-lead-contract.md "Entry guard (BLOCKING)" + prompts/launch.template.md "Host Orchestration Rules" (only when the run staged the rules file) | selected adapter evidence source |
 
 Evidence rules prevent false passes:
 - `claude-jsonl` accepts only assistant text and Read tool-use records, excluding
@@ -25,7 +25,7 @@ import sys
 from dataclasses import dataclass, field
 from datetime import datetime
 from pathlib import Path
-from typing import Any, Mapping
+from typing import Any, Mapping, NamedTuple
 
 # scripts/ (repo) and python/ (installed under ~/.okstra/lib) are not packages;
 # insert whichever exists so okstra_ctl is importable directly.
@@ -36,6 +36,7 @@ for _ssot_dir in (_VALIDATORS_DIR.parent / "scripts", _VALIDATORS_DIR.parent / "
 
 from okstra_ctl.worker_heartbeat import (  # noqa: E402
     HEARTBEAT_LINE_RE,
+    IN_STAGE_PREFIX,
     max_gap_seconds_after,
 )
 from okstra_ctl.lead_runtime import ARTIFACT_ONLY_LEAD_RUNTIMES  # noqa: E402
@@ -67,16 +68,62 @@ _PROGRESS_LINE_RE = re.compile(
 # heartbeat 라인 shape 과 cadence 예산은 okstra_ctl.worker_heartbeat 정본을 쓴다 —
 # `okstra worker-liveness` 가 run 도중 같은 판정을 내리므로 정의가 갈리면 안 된다.
 _HEARTBEAT_LINE_RE = HEARTBEAT_LINE_RE
+_IN_STAGE_PREFIX = IN_STAGE_PREFIX
+
+_LEAD_CONTRACT_CITE = "prompts/lead/okstra-lead-contract.md 'Entry guard (BLOCKING)'"
+_HOST_RULES_CITE = "prompts/launch.template.md 'Host Orchestration Rules'"
+
+
+class _EntryGuardRead(NamedTuple):
+    """implementation entry guard 가 Read 를 요구하는 파일 한 건."""
+
+    basename: str
+    # (이 Read 가 앞서야 할 PROGRESS 체크포인트, 실패 메시지에 쓸 시점 표현).
+    # None 이면 순서 제약이 없고 run 윈도우 안의 존재만 검사한다.
+    anchor: tuple[str, str] | None
+    cite: str
+    # True 면 run 이 이 파일을 instruction-set 에 스테이징했을 때만 요구한다.
+    staged_per_run: bool = False
+
+
+_ENTRY_GUARD_READS = (
+    _EntryGuardRead(
+        "_implementation-executor.md", ("phase-6-synthesis", "at Phase 5"), _LEAD_CONTRACT_CITE
+    ),
+    _EntryGuardRead(
+        "_implementation-verifier.md", ("phase-6-synthesis", "at Phase 5"), _LEAD_CONTRACT_CITE
+    ),
+    _EntryGuardRead(
+        "_implementation-deliverable.md", ("phase-7-persist", "at Phase 6"), _LEAD_CONTRACT_CITE
+    ),
+    # lead 프로파일 sidecar 가 아니라, run 이 instruction-set 에 스테이징한 host
+    # orchestration 규칙이다. 세 가지가 sidecar 와 다르다.
+    #
+    # anchor 없음: 이 파일은 `render-bundle` 이 만든다(run.py `_write_instruction_set_sources`).
+    #   그 앞에서 발화하는 gate(Step 5.1 waiver 제안)에는 아직 파일이 없고, 뒤에
+    #   오는 gate 는 run 의 PROGRESS 체크포인트와 시간 관계가 고정돼 있지 않다.
+    #   증거가 뒷받침하는 주장은 "run 윈도우 안에 Read 가 최소 한 번" 뿐이다.
+    # staged_per_run: 파일이 없는 번들 — 이 변경 전에 렌더된 run, 또는 payload 에
+    #   prompts/host-orchestration/<task-type>.md 가 없는 설치본 — 은 읽을 수 없는
+    #   파일 때문에 막히면 안 된다. 규칙이 없는 task-type 에 conformance 가 규칙을
+    #   요구하지 않는다는 원칙과 같은 판단이다.
+    _EntryGuardRead(
+        "host-orchestration-rules.md", None, _HOST_RULES_CITE, staged_per_run=True
+    ),
+)
 
-# 장기 단계 중 append 되는 진행 라인 (claude-worker.md "Heartbeat").
-_IN_STAGE_PREFIX = "in-stage:"
-
-# Phase 5/6 진입 전 lead 가 Read 해야 하는 implementation 프로파일 sidecar.
-# 절대 경로는 레이어(repo / runtime / 설치본)마다 다르지만 basename 은 동일하다.
-_SIDECAR_BASENAMES = (
-    "_implementation-executor.md",
-    "_implementation-verifier.md",
-    "_implementation-deliverable.md",
+# 환경으로 선택되는 어댑터라 lead 의 런타임이 이 파일을 가르쳐 주지 않는다.
+# 읽지 않은 lead 는 자기 런타임이 아는 방식 — cmux 경로에서는 okstra 가 소유한
+# 디스패치를 host 네이티브로 가로채는 방식 — 으로 되돌아간다.
+CMUX_ADAPTER_BASENAME = "cmux.md"
+CMUX_ADAPTER_NAME = "cmux"
+_CMUX_ADAPTER_CITE = "prompts/lead/adapters/cmux.md"
+
+# Read 증거는 basename 으로 거른다 — 절대 경로는 레이어(repo / runtime / 설치본)
+# 마다 다르지만 basename 은 동일하다. 목록이 갈리지 않도록 기대치에서 파생한다.
+_TRACKED_READ_BASENAMES = (
+    *(row.basename for row in _ENTRY_GUARD_READS),
+    CMUX_ADAPTER_BASENAME,
 )
 
 
@@ -171,7 +218,7 @@ def _scan_one_jsonl(
                         progress.append((ts, m.group("phase"), line))
                 elif block.get("type") == "tool_use" and block.get("name") == "Read":
                     base = Path(str((block.get("input") or {}).get("file_path") or "")).name
-                    if base in _SIDECAR_BASENAMES:
+                    if base in _TRACKED_READ_BASENAMES:
                         reads.setdefault(base, []).append(ts)
     return progress, reads, agent_name
 
@@ -297,7 +344,7 @@ def _sidecar_read_from_event(event) -> tuple[str, str] | None:
     if not isinstance(basename, str) or not basename:
         raw_path = details.get("path") or details.get("filePath")
         basename = Path(str(raw_path or "")).name
-    if basename not in _SIDECAR_BASENAMES:
+    if basename not in _TRACKED_READ_BASENAMES:
         return None
     return (basename, event.timestamp)
 
@@ -696,36 +743,88 @@ def _check_worker_liveness(
                 errors.append(f"registered wrapper status sidecar unreadable: {path}")
 
 
-def _check_implementation_sidecar_reads(evidence: _LeadEvidence, errors: list[str]) -> None:
+def _instruction_set_dir(run_dir: Path, suffix: str | None, project_root: Path) -> Path | None:
+    """이 run 의 instruction-set 디렉터리. 해소 불가면 None (경로를 모르면 스테이징
+    여부도 판정할 수 없고, 모르는 것을 근거로 run 을 떨어뜨리지 않는다)."""
+    if not suffix:
+        return None
+    manifest = run_dir / "manifests" / f"run-manifest-{suffix}.json"
+    try:
+        data = json.loads(manifest.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError, UnicodeDecodeError):
+        return None
+    raw = data.get("instructionSetPath") if isinstance(data, dict) else None
+    if not isinstance(raw, str) or not raw:
+        return None
+    path = Path(raw)
+    if not path.is_absolute():
+        path = project_root / path
+    return path if path.is_dir() else None
+
+
+def _check_cmux_adapter_read(
+    evidence: _LeadEvidence, team_state: dict, errors: list[str]
+) -> None:
+    """검사 4 — cmux 어댑터 읽음. 모든 task-type 에 적용된다.
+
+    다른 어댑터는 lead 의 런타임이 고르지만 이것은 환경이 고른다. 그래서 읽지
+    않은 lead 에게는 이 경로가 존재한다는 사실 자체가 닿지 않고, 자기 런타임이
+    아는 host 네이티브 디스패치로 되돌아간다 — cmux 경로에서 okstra 가 소유한
+    바로 그 일이다."""
+    adapter = team_state.get("leadAdapter")
+    name = str(adapter.get("name", "")).strip() if isinstance(adapter, dict) else ""
+    if name != CMUX_ADAPTER_NAME:
+        return
+    if evidence.sidecar_reads.get(CMUX_ADAPTER_BASENAME):
+        return
+    errors.append(
+        f"cmux adapter: no `Read` of `{CMUX_ADAPTER_BASENAME}` found in the "
+        "selected adapter evidence source within this run's window — the cmux "
+        "adapter is selected by environment, not by lead runtime, so it MUST be "
+        f"read before dispatch ({_CMUX_ADAPTER_CITE})."
+    )
+
+
+def _check_implementation_entry_guard(
+    evidence: _LeadEvidence, errors: list[str], instruction_set: Path | None
+) -> None:
     """검사 3 — entry guard. fresh-read 규칙(이전 run 기억으로 갈음 불가)은 run
-    윈도우 스코핑이 보장한다: 이번 윈도우 안의 Read 만 증거로 인정된다."""
+    윈도우 스코핑이 보장한다: 이번 윈도우 안의 Read 만 증거로 인정된다.
+
+    anchor 가 있는 행은 존재 + 순서를, anchor 가 `None` 인 행은 존재만 본다.
+    `staged_per_run` 행은 이 run 의 instruction-set 에 실제로 있을 때만 요구한다."""
     anchors: dict[str, str] = {}
     for ts, phase, _line in evidence.progress:  # progress 는 ts 정렬 — 첫 항목이 최초 발생
         if phase in ("phase-6-synthesis", "phase-7-persist") and ts:
             anchors.setdefault(phase, ts)
-    expectations = (
-        ("_implementation-executor.md", "phase-6-synthesis", "Phase 5"),
-        ("_implementation-verifier.md", "phase-6-synthesis", "Phase 5"),
-        ("_implementation-deliverable.md", "phase-7-persist", "Phase 6"),
-    )
-    for basename, anchor_phase, read_at in expectations:
-        ts_list = evidence.sidecar_reads.get(basename) or []
+    for row in _ENTRY_GUARD_READS:
+        if row.staged_per_run and not (
+            instruction_set and (instruction_set / row.basename).is_file()
+        ):
+            continue
+        ts_list = evidence.sidecar_reads.get(row.basename) or []
         if not ts_list:
+            demand = (
+                f"it MUST be read fresh {row.anchor[1]} of every implementation run"
+                if row.anchor
+                else "the staged copy MUST be read at least once inside that window"
+            )
             errors.append(
-                f"implementation entry guard: no `Read` of `{basename}` found in "
-                "the selected adapter evidence source within this run's window — "
-                "the sidecar "
-                f"MUST be read fresh at {read_at} every implementation run "
-                "(prompts/lead/okstra-lead-contract.md 'Entry guard (BLOCKING)')."
+                f"implementation entry guard: no `Read` of `{row.basename}` found in "
+                f"the selected adapter evidence source within this run's window — "
+                f"{demand} ({row.cite})."
             )
             continue
+        if not row.anchor:
+            continue
+        anchor_phase, when = row.anchor
         anchor_ts = anchors.get(anchor_phase)
         if anchor_ts and min(ts_list) >= anchor_ts:
             errors.append(
-                f"implementation entry guard: `{basename}` was first Read at "
+                f"implementation entry guard: `{row.basename}` was first Read at "
                 f"{min(ts_list)}, not before the first `PROGRESS: {anchor_phase}` "
-                f"line ({anchor_ts}) — it must be loaded at {read_at}, before "
-                "that checkpoint (prompts/lead/okstra-lead-contract.md 'Entry guard (BLOCKING)')."
+                f"line ({anchor_ts}) — it must be loaded {when}, before "
+                f"that checkpoint ({row.cite})."
             )
 
 
@@ -771,6 +870,11 @@ def validate_session_conformance(
         result.errors.append(error)
         return result
     _check_progress_checkpoints(evidence, team_state, run_dir, suffix, result.errors)
+    _check_cmux_adapter_read(evidence, team_state, result.errors)
     if task_type == "implementation":
-        _check_implementation_sidecar_reads(evidence, result.errors)
+        _check_implementation_entry_guard(
+            evidence,
+            result.errors,
+            _instruction_set_dir(run_dir, suffix, project_root),
+        )
     return result

package/src/cli-registry.mjs

@@ -87,6 +87,16 @@ export const COMMAND_REGISTRY = [
     category: "admin",
     summary: ["Score the §5.5.9 plan-body gate for one self-fix round"],
   },
+  {
+    name: "worker-audit-check",
+    module: "./commands/execute/worker-audit-check.mjs",
+    export: "run",
+    category: "admin",
+    summary: [
+      "Check a run's worker audit sidecars while the workers",
+      "are still alive (the Phase 7 rules, run early)",
+    ],
+  },
   {
     name: "git-reconcile",
     module: "./commands/execute/git-reconcile.mjs",
@@ -208,6 +218,20 @@ export const COMMAND_REGISTRY = [
     category: "introspection",
     summary: ["Bundle cross-project okstra error logs into a zip"],
   },
+  {
+    name: "error-issue",
+    module: "./commands/inspect/error-issue.mjs",
+    export: "run",
+    category: "introspection",
+    summary: ["Turn okstra run anomalies into GitHub issue candidates"],
+  },
+  {
+    name: "run-audit",
+    module: "./commands/inspect/run-audit.mjs",
+    export: "run",
+    category: "introspection",
+    summary: ["Check okstra run artifacts against progress invariants"],
+  },
   {
     name: "recap",
     module: "./commands/inspect/recap.mjs",
@@ -274,6 +298,16 @@ export const COMMAND_REGISTRY = [
       "python3 -m okstra_ctl.run --render-only)",
     ],
   },
+  {
+    name: "profile",
+    module: "./commands/inspect/profile-show.mjs",
+    export: "run",
+    category: "introspection",
+    summary: [
+      "Print a phase profile with {{INCLUDE:}} expanded and its",
+      "lazy-read sidecars appended (read-only)",
+    ],
+  },
   {
     name: "run",
     module: "./commands/execute/run.mjs",

package/src/commands/execute/incremental-scope.mjs

@@ -10,8 +10,18 @@ instead of emitting a \`python3 "$HOME/..."\` invocation (which breaks
 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.
+
 All arguments are forwarded verbatim to the python helper.
 `;
 

package/src/commands/execute/worker-audit-check.mjs

@@ -0,0 +1,35 @@
+import { runPythonModule } from "../../lib/python-helper.mjs";
+
+const USAGE = `okstra worker-audit-check — check one run's worker audit sidecars
+
+Usage:
+  okstra worker-audit-check --run-dir <runs/<task-type>/> --task-type <type> \\
+    --seq <nnn> [--worker <id>]
+
+  --run-dir    the run directory; worker-results/ and prompts/ hang off it
+  --worker     check only this worker (default: every worker in the run)
+
+Emits one JSON object — \`{ok, failures[]}\` — and exits 2 when failures[] is
+non-empty, 0 otherwise.
+
+Runs the Phase 7 audit-sidecar rules now, while the worker session is still
+alive: that every result file carries no \`## 0. Reading Confirmation\` heading,
+that its audit sidecar exists, and that every backticked \`path:line\` citation
+has a matching Evidence read row in that sidecar.
+
+Call it right after collecting a worker result. The same failure at Phase 7
+leaves only a retroactive edit — which breaks the audit chain — or a failed run.
+`;
+
+export async function run(args) {
+  if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return args.length === 0 ? 2 : 0;
+  }
+  const result = await runPythonModule({
+    module: "okstra_ctl.worker_audit_check",
+    args,
+    stdio: "inherit-stdout",
+  });
+  return result.code;
+}

package/src/commands/inspect/error-issue.mjs

@@ -0,0 +1,27 @@
+import { runPythonModule } from "../../lib/python-helper.mjs";
+
+const USAGE = `okstra error-issue — turn okstra run anomalies into GitHub issue candidates
+
+Usage:
+  okstra error-issue plan --out <path>
+  okstra error-issue submit --plan <path>
+
+'plan' walks the global run-index, gates clusters by occurrence and recency,
+computes classification signals from the raw records, checks GitHub for an
+existing issue carrying the same fingerprint, and writes plan.json.
+'submit' reads that file only, re-validates every candidate, and files or
+comments via gh. A candidate that fails validation is never sent.
+`;
+
+export async function run(args) {
+  if (args.includes("--help") || args.includes("-h") || args.length === 0) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  const result = await runPythonModule({
+    module: "okstra_ctl.error_issue",
+    args,
+    stdio: "inherit-stdout",
+  });
+  return result.code;
+}

package/src/commands/inspect/profile-show.mjs

@@ -0,0 +1,29 @@
+import { runPythonModule } from "../../lib/python-helper.mjs";
+
+const USAGE = `okstra profile show — print a phase profile, fully resolved
+
+Usage:
+  okstra profile show <task-type> [--resolved]
+
+  --resolved   expand {{INCLUDE:}} targets and append the lazy-read sidecars
+
+A profile is assembled from the top-level body, its {{INCLUDE:}} targets, and
+the sidecars its own table names — so grepping the top-level file and finding
+nothing does not mean the rule is absent. This prints all of it, so one grep
+answers "does this task-type cover X".
+
+Read-only: writes no manifest and registers no run. That is what separates it
+from 'okstra render-bundle', which answers the same question with side effects.
+`;
+
+export async function run(args) {
+  if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return args.length === 0 ? 2 : 0;
+  }
+  const { code } = await runPythonModule({
+    module: "okstra_ctl.profile_show",
+    args,
+  });
+  return code ?? 1;
+}

package/src/commands/inspect/run-audit.mjs

@@ -0,0 +1,26 @@
+import { runPythonModule } from "../../lib/python-helper.mjs";
+
+const USAGE = `okstra run-audit — check okstra run artifacts against progress invariants
+
+Usage:
+  okstra run-audit
+
+Walks the global run-index and checks each run's artifacts (run-manifest,
+final-report data, worker results) against invariants that no error log
+would catch: verification rounds that never ran, reports that never
+appeared, rosters that came up short, approvals waiting past the window.
+Read-only. Prints a JSON summary to stdout.
+`;
+
+export async function run(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  const result = await runPythonModule({
+    module: "okstra_ctl.run_audit",
+    args,
+    stdio: "inherit-stdout",
+  });
+  return result.code;
+}