okstra 0.121.1 → 0.123.0

package/runtime/validators/validate_session_conformance.py

@@ -1,22 +1,20 @@
-"""prompts/lead/okstra-lead-contract.md BLOCKING 계약 3종의 post-hoc conformance 검사.
-
-설계: docs/superpowers/specs/2026-06-10-blocking-contract-posthoc-conformance-design.md
-
-| 검사 | 선언 위치 | 증거 |
-|------|----------|------|
-| 1. lead PROGRESS 체크포인트 라인 | prompts/lead/okstra-lead-contract.md "Progress reporting (BLOCKING)" | lead 세션 jsonl 의 assistant text 블록 |
-| 2. claude-worker 5분 heartbeat | agents/workers/claude-worker.md "Heartbeat" | audit 사이드카의 `- PROGRESS: <stage> <ISO>` 라인 |
-| 3. implementation sidecar entry guard | prompts/lead/okstra-lead-contract.md "Entry guard (BLOCKING)" | lead 세션 jsonl 의 Read tool_use |
-
-스캔 규칙 (false-pass 방지가 핵심):
-- `type == "assistant"` 레코드만 본다 — Skill 호출 시 SKILL.md 본문(체크포인트
-  라인 예시 포함)이 tool_result(user 레코드)로 transcript 에 주입되므로,
-  assistant 외 레코드를 보면 즉시 false pass 가 난다. `isSidechain` 레코드도 제외.
-- run 윈도우(`resolve_run_window`)로 스코핑한다 — in-session lead 는 세션 전체
-  jsonl 에 기록되므로, 같은 세션의 직전 run 이 남긴 라인이 증거로 오인된다.
-  (실측: dev-9692 lead 세션 1개에 implementation run 001–003 이 모두 들어 있음.)
-- validator 실행 시점(Phase 7) **이후** 에 출력되는 체크포인트
-  (`phase-7-teardown`, `complete`)는 구조적으로 검사 불가 — 요구하지 않는다.
+"""Post-hoc checks for three BLOCKING neutral lead lifecycle contracts.
+
+Design: docs/superpowers/specs/2026-06-10-blocking-contract-posthoc-conformance-design.md
+
+| Check | Contract | Evidence |
+|-------|----------|----------|
+| 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 |
+
+Evidence rules prevent false passes:
+- `claude-jsonl` accepts only assistant text and Read tool-use records, excluding
+  injected skill text and sidechain records.
+- Session evidence is scoped to the current run window so a previous run cannot
+  satisfy the neutral lead lifecycle contract.
+- Checkpoints emitted after validation begins (`phase-7-teardown`, `complete`)
+  cannot be observed and are not required.
 """
 from __future__ import annotations
 
@@ -202,7 +200,8 @@ def _collect_lead_evidence(
     if not evidence.scanned_files:
         return None, (
             f"lead session jsonl not found under {proj_dir} "
-            f"(lead.sessionId={lead_sid or '<empty>'}) — PROGRESS checkpoint / "
+            f"(lead.sessionId={lead_sid or '<empty>'}) — selected adapter evidence "
+            "source `claude-jsonl` cannot verify the PROGRESS checkpoint / "
             "implementation entry-guard conformance cannot be verified, which "
             "fails the run (same principle as the token-usage accuracy contract)."
         )
@@ -223,15 +222,16 @@ def _resolve_lead_events_path(
     if not raw:
         return None, (
             "artifact lead event log path missing from team-state "
-            "(`leadEventsPath`) — artifact-only conformance cannot be verified."
+            "(`leadEventsPath`) — selected adapter evidence source `artifact-only` "
+            "cannot verify conformance."
         )
     path = Path(str(raw))
     if not path.is_absolute():
         path = project_root / path
     if not path.is_file():
         return None, (
-            f"artifact lead event log not found: {path} — artifact-only "
-            "conformance cannot be verified."
+            f"artifact lead event log not found: {path} — selected adapter evidence "
+            "source `artifact-only` cannot verify conformance."
         )
     return path, None
 
@@ -301,7 +301,10 @@ def _collect_artifact_lead_evidence(
     try:
         events = read_lead_events(events_path)
     except LeadEventParseError as exc:
-        return None, f"artifact lead event log is malformed — {exc}"
+        return None, (
+            "artifact lead event log is malformed — selected adapter evidence "
+            f"source `artifact-only` cannot verify conformance: {exc}"
+        )
 
     run_seq = suffix.rsplit("-", 1)[1]
     evidence = _LeadEvidence(scanned_files=[events_path])
@@ -324,6 +327,27 @@ def _collect_artifact_lead_evidence(
     return evidence, None
 
 
+def _conformance_evidence_source(
+    team_state: dict,
+) -> tuple[str | None, str | None]:
+    dispatch_mode = str(team_state.get("dispatchMode", "")).strip()
+    if dispatch_mode in _WORKER_DISPATCH_MODES:
+        return "artifact-only", None
+
+    adapter = team_state.get("leadAdapter")
+    if isinstance(adapter, dict):
+        accounting = str(adapter.get("sessionAccounting", "")).strip()
+        if accounting in {"claude-jsonl", "artifact-only"}:
+            return accounting, None
+        if accounting:
+            return None, f"unsupported sessionAccounting: `{accounting}`"
+
+    legacy_runtime = str(team_state.get("leadRuntime", "") or "claude-code")
+    if legacy_runtime in {"codex", "external"}:
+        return "artifact-only", None
+    return "claude-jsonl", None
+
+
 def _convergence_rounds_ran(run_dir: Path, suffix: str | None) -> bool:
     """이 run 의 convergence state artifact 가 실제 round 를 1회 이상 돌았는지.
     auto-disable(`totalRounds: 0`)·artifact 부재는 phase-5.5 라인을 요구하지 않는다."""
@@ -569,7 +593,8 @@ def _check_implementation_sidecar_reads(evidence: _LeadEvidence, errors: list[st
         if not ts_list:
             errors.append(
                 f"implementation entry guard: no `Read` of `{basename}` found in "
-                f"the lead session jsonl within this run's window — the sidecar "
+                "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)')."
             )
@@ -593,10 +618,10 @@ def validate_session_conformance(
     task_type: str,
     claude_projects_dir: Path | None = None,
 ) -> SessionConformanceResult:
-    """post-hoc conformance 검사 3종을 수행하고 실패 목록을 돌려준다.
+    """Run three post-hoc checks for the neutral lead lifecycle contract.
 
-    `claude_projects_dir` 는 테스트/진단용 주입 시드 (기본: 실제 ~/.claude/projects).
-    검사 2(heartbeat)는 디스크 사이드카만 보므로 lead jsonl 미발견 시에도 수행된다.
+    `claude_projects_dir` injects the Claude project root for tests and diagnostics.
+    Heartbeat validation runs before selecting the adapter evidence source.
     """
     result = SessionConformanceResult()
     _ensure_token_usage_importable()
@@ -610,11 +635,11 @@ def validate_session_conformance(
     suffix = run_artifact_suffix(team_state_path)
     _check_heartbeat_sidecars(run_dir, task_type, suffix, result.errors)
 
-    lead_runtime = team_state.get("leadRuntime", "") or "claude-code"
-    dispatch_mode = str(team_state.get("dispatchMode", "")).strip()
-    if lead_runtime in {"codex", "external"} or (
-        lead_runtime == "claude-code" and dispatch_mode in _WORKER_DISPATCH_MODES
-    ):
+    evidence_source, source_error = _conformance_evidence_source(team_state)
+    if source_error:
+        result.errors.append(source_error)
+        return result
+    if evidence_source == "artifact-only":
         evidence, error = _collect_artifact_lead_evidence(
             team_state, project_root, task_type, suffix
         )

package/src/cli-registry.mjs

@@ -110,6 +110,13 @@ export const COMMAND_REGISTRY = [
     category: "introspection",
     summary: ["Summarize a task's manifest + workflow phase state"],
   },
+  {
+    name: "stage-map",
+    module: "./commands/inspect/stage-map.mjs",
+    export: "run",
+    category: "introspection",
+    summary: ["Dump a task's implementation-planning Stage Map + done stages"],
+  },
   {
     name: "context-cost",
     module: "./commands/inspect/context-cost.mjs",
@@ -180,6 +187,13 @@ export const COMMAND_REGISTRY = [
     category: "introspection",
     summary: ["Answer a task's open clarification questions in-session and write the response sidecar"],
   },
+  {
+    name: "design-prep",
+    module: "./commands/inspect/design-prep.mjs",
+    export: "run",
+    category: "introspection",
+    summary: ["Review and record AI-prepared implementation design inputs"],
+  },
   {
     name: "rollup",
     module: "./commands/inspect/rollup.mjs",

package/src/commands/inspect/design-prep.mjs

@@ -0,0 +1,23 @@
+import { runPythonModule } from "../../lib/python-helper.mjs";
+
+const USAGE = `okstra design-prep — review AI-prepared implementation design inputs
+
+Usage:
+  okstra design-prep list [--project-root <path>] [--report <path>]
+  okstra design-prep show --report <path> [--item PREP-001]
+  okstra design-prep write --report <path> --item PREP-001 \\
+    --decision <accept-draft|modify-draft|reject-draft|defer> \\
+    [--overrides <json-object>] [--notes <text>] --confirmed
+`;
+
+export async function run(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  const { code } = await runPythonModule({
+    module: "okstra_ctl.design_prep",
+    args,
+  });
+  return code ?? 1;
+}

package/src/commands/inspect/stage-map.mjs

@@ -0,0 +1,100 @@
+import { runPythonSnippet, emitJsonError } from "../../lib/python-helper.mjs";
+
+const USAGE = `okstra stage-map — dump a task's implementation-planning Stage Map + done stages
+
+Usage:
+  okstra stage-map <task-key>                  task-key is project-id:task-group:task-id
+  okstra stage-map <task-key> --cwd <dir>      Resolve PROJECT_ROOT from <dir>
+  okstra stage-map <task-key> --project <dir>  Use <dir> directly as PROJECT_ROOT
+
+Output: JSON { ok, taskKey, taskRoot, stages:[{stage_number,title,depends_on,step_count}], doneStages:[int] }.
+stages is [] when no implementation-planning Stage Map exists.
+`;
+
+function parseArgs(args) {
+  const opts = { cwd: process.cwd(), projectRoot: "", taskKey: "" };
+  const positional = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--cwd") {
+      opts.cwd = args[++i];
+      if (!opts.cwd) throw new Error("--cwd requires a path");
+    } else if (a === "--project") {
+      opts.projectRoot = args[++i];
+      if (!opts.projectRoot) throw new Error("--project requires a path");
+    } else if (a === "--json") {
+      // JSON is always emitted; accept the flag for parity with sibling commands.
+    } else if (a.startsWith("--")) {
+      throw new Error(`unknown argument '${a}'`);
+    } else {
+      positional.push(a);
+    }
+  }
+  if (positional.length !== 1) {
+    throw new Error("expected exactly one positional argument: <task-key>");
+  }
+  opts.taskKey = positional[0];
+  return opts;
+}
+
+const SCRIPT = `
+import json, sys
+from pathlib import Path
+from okstra_project import resolve_project_root, find_task_root, read_task_manifest, ResolverError
+from okstra_ctl.implementation_outcome import _load_stage_map
+from okstra_ctl.consumers import read_stage_consumer_state
+
+explicit, cwd, task_key = sys.argv[1], sys.argv[2], sys.argv[3]
+
+try:
+    pr = resolve_project_root(explicit_root=explicit, cwd=cwd)
+except ResolverError as e:
+    print(json.dumps({"ok": False, "stage": "resolve", "reason": str(e)}))
+    sys.exit(2)
+
+task_root = find_task_root(Path(pr), task_key)
+if task_root is None:
+    print(json.dumps({"ok": False, "stage": "task_root", "reason": f"task root not found for {task_key}"}))
+    sys.exit(1)
+
+manifest = read_task_manifest(task_root) or {}
+stages = _load_stage_map(task_root, manifest)
+
+plan_run_root = task_root / "runs" / "implementation-planning"
+done = sorted(read_stage_consumer_state(plan_run_root, recover_from_carry=True).done_stages) if plan_run_root.is_dir() else []
+
+print(json.dumps({
+    "ok": True,
+    "taskKey": task_key,
+    "taskRoot": str(task_root),
+    "stages": stages,
+    "doneStages": done,
+}, ensure_ascii=False, indent=2))
+`;
+
+export async function run(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  let opts;
+  try {
+    opts = parseArgs(args);
+  } catch (err) {
+    process.stderr.write(`error: ${err.message}\n\n${USAGE}`);
+    return 2;
+  }
+  const result = await runPythonSnippet({
+    script: SCRIPT,
+    args: [opts.projectRoot, opts.cwd, opts.taskKey],
+  });
+  if (result.code !== 0 && !result.stdout.trim()) {
+    emitJsonError({
+      stage: "python",
+      reason: `python invocation failed: ${result.stderr.trim() || "no output"}`,
+    });
+    return 1;
+  }
+  process.stdout.write(result.stdout);
+  return result.code === 0 ? 0 : result.code;
+}

package/src/commands/lifecycle/install.mjs

@@ -45,6 +45,9 @@ const BIN_ENTRYPOINTS = [
 // depend on. Intentionally an exact allowlist, not a directory wildcard.
 const REQUIRED_PROMPT_RESOURCE_FILES = Object.freeze([
   ["prompts", "lead", "okstra-lead-contract.md"],
+  ["prompts", "lead", "adapters", "claude-code.md"],
+  ["prompts", "lead", "adapters", "codex.md"],
+  ["prompts", "lead", "adapters", "external.md"],
   ["prompts", "lead", "context-loader.md"],
   ["prompts", "lead", "team-contract.md"],
   ["prompts", "lead", "convergence.md"],

package/src/commands/lifecycle/uninstall.mjs

@@ -6,30 +6,15 @@ import {
   RUNTIMES_MANIFEST_REL,
   runtimeManifestIncludesClaudeAssets,
 } from "../../lib/runtime-manifest.mjs";
+import { OBSOLETE_SKILL_NAMES, USER_SKILL_NAMES } from "../../lib/skill-catalog.mjs";
 
-const FALLBACK_SKILL_NAMES = [
-  "okstra",
-  "okstra-setup",
-  "okstra-brief-gen",
-  "okstra-run",
-  "okstra-memory",
-  "okstra-inspect",
-  "okstra-schedule",
-  "okstra-container-build",
-  "okstra-container",
-  "okstra-brief",
-  "okstra-context-loader",
-  "okstra-team-contract",
-  "okstra-convergence",
-  "okstra-report-writer",
-  // Pre-merge names — kept so uninstall on an upgraded machine still cleans
-  // them out of ~/.claude/skills/ once the user runs `okstra uninstall`.
-  // Safe to drop after a few releases when nobody has them installed.
-  "okstra-status",
-  "okstra-history",
-  "okstra-logs",
-  "okstra-report-finder",
-  "okstra-time-summary",
+// Manifest-less uninstall must clean out every okstra skill directory — the
+// live names AND every former/renamed one. Both sets are the single source of
+// truth in skill-catalog.mjs (install prunes OBSOLETE_SKILL_NAMES from each
+// skill home), so deriving the fallback from their union keeps uninstall from
+// drifting behind skill additions or renames.
+export const FALLBACK_SKILL_NAMES = [
+  ...new Set([...USER_SKILL_NAMES, ...OBSOLETE_SKILL_NAMES]),
 ];
 
 const FALLBACK_AGENT_NAMES = [

package/src/lib/skill-catalog.mjs

@@ -13,7 +13,7 @@ export const USER_SKILL_NAMES = Object.freeze([
   "okstra-inspect",
   "okstra-rollup",
   "okstra-usage",
-  "okstra-schedule",
+  "okstra-schedule-gen",
   "okstra-container-build",
   "okstra-graphify",
   "okstra-pr-gen",
@@ -33,6 +33,15 @@ export const OBSOLETE_SKILL_NAMES = Object.freeze([
   "okstra-coding-preflight",
   "okstra-container",
   "okstra-brief",
+  "okstra-schedule",
+  // Pre-merge status/history/logs/report/time skills, since folded into
+  // okstra-inspect. Absent here, upgrades left them stranded in agent skill
+  // homes and their pre-.okstra-migration bodies kept triggering.
+  "okstra-status",
+  "okstra-history",
+  "okstra-logs",
+  "okstra-report-finder",
+  "okstra-time-summary",
 ]);
 
 export function userSkillNames() {