okstra 0.76.0 → 0.78.0

package/src/cli-registry.mjs

@@ -0,0 +1,277 @@
+const SUMMARY_COLUMN = 25;
+
+export const COMMAND_REGISTRY = [
+  {
+    name: "install",
+    module: "./install.mjs",
+    export: "runInstall",
+    category: "admin",
+    summary: ["Install runtime; --runtime codex skips ~/.claude assets"],
+  },
+  {
+    name: "ensure-installed",
+    module: "./install.mjs",
+    export: "runEnsureInstalled",
+    category: "admin",
+    summary: ["Verify install is fresh; reinstall if stale (idempotent)"],
+  },
+  {
+    name: "uninstall",
+    module: "./uninstall.mjs",
+    export: "runUninstall",
+    category: "admin",
+    summary: ["Remove runtime + skills (user data preserved by default)"],
+  },
+  {
+    name: "setup",
+    module: "./setup.mjs",
+    export: "run",
+    category: "admin",
+    summary: ["Register the current project (.okstra/project.json)"],
+  },
+  {
+    name: "doctor",
+    module: "./doctor.mjs",
+    export: "run",
+    category: "admin",
+    summary: [
+      "Diagnostic check; --runtime selects assets, --phase checks readiness",
+    ],
+  },
+  {
+    name: "check-project",
+    module: "./check-project.mjs",
+    export: "run",
+    category: "admin",
+    summary: ["Verify the current project has been registered with setup"],
+  },
+  {
+    name: "config",
+    module: "./config.mjs",
+    export: "run",
+    category: "admin",
+    summary: ["Read / write okstra settings (e.g. PR template path)"],
+  },
+  {
+    name: "migrate",
+    module: "./migrate.mjs",
+    export: "run",
+    category: "admin",
+    summary: ["Move legacy .project-docs/okstra/ to .okstra/ (one-shot)"],
+  },
+  {
+    name: "git-reconcile",
+    module: "./git-reconcile.mjs",
+    export: "run",
+    category: "admin",
+    summary: ["Reconcile stale stage SHAs after external git history changes"],
+  },
+  {
+    name: "handoff",
+    module: "./handoff.mjs",
+    export: "run",
+    category: "admin",
+    summary: ["Stage-group release-handoff helpers (eligible/assemble/record)"],
+  },
+  {
+    name: "paths",
+    module: "./paths.mjs",
+    export: "run",
+    category: "admin",
+    summary: [
+      "Print runtime paths (workspace/agents/pythonpath/bin/home/version)",
+    ],
+  },
+  {
+    name: "task-list",
+    module: "./task-list.mjs",
+    export: "run",
+    category: "introspection",
+    summary: ["List tasks registered in the current project"],
+  },
+  {
+    name: "task-show",
+    module: "./task-show.mjs",
+    export: "run",
+    category: "introspection",
+    summary: ["Summarize a task's manifest + workflow phase state"],
+  },
+  {
+    name: "context-cost",
+    module: "./context-cost.mjs",
+    export: "run",
+    category: "introspection",
+    summary: ["Estimate file/read context cost for a task bundle"],
+  },
+  {
+    name: "worktree-lookup",
+    module: "./worktree-lookup.mjs",
+    export: "run",
+    category: "introspection",
+    summary: ["Look up registered worktree for a task-key"],
+  },
+  {
+    name: "plan-validate",
+    module: "./plan-validate.mjs",
+    export: "run",
+    category: "introspection",
+    summary: ["Check an approved-plan file for the approval marker"],
+  },
+  {
+    name: "render-bundle",
+    module: "./render-bundle.mjs",
+    export: "run",
+    category: "introspection",
+    summary: [
+      "Preview prepare_task_bundle() output (forwards to",
+      "python3 -m okstra_ctl.run --render-only)",
+    ],
+  },
+  {
+    name: "codex-run",
+    module: "./codex-run.mjs",
+    export: "run",
+    category: "introspection",
+    summary: [
+      "Prepare a render-only Codex lead task bundle",
+      "(--lead-runtime codex, no worker dispatch)",
+    ],
+  },
+  {
+    name: "codex-dispatch",
+    module: "./codex-dispatch.mjs",
+    export: "run",
+    category: "introspection",
+    summary: ["Dispatch CLI-backed workers for a prepared Codex run"],
+  },
+  {
+    name: "team",
+    module: "./team.mjs",
+    export: "run",
+    category: "introspection",
+    summary: ["Dispatch and await tmux-pane workers for external leads"],
+  },
+  {
+    name: "wizard",
+    module: "./wizard.mjs",
+    export: "run",
+    category: "introspection",
+    summary: [
+      "Drive the okstra-run interactive input state machine",
+      "(init / step / render-args / confirmation)",
+    ],
+  },
+  {
+    name: "token-usage",
+    module: "./token-usage.mjs",
+    export: "run",
+    category: "introspection",
+    summary: [
+      "Collect token usage for a run (wraps the installed",
+      "okstra-token-usage.py so skills avoid emitting",
+      'python3 "$HOME/..." invocations).',
+    ],
+  },
+  {
+    name: "render-views",
+    module: "./render-views.mjs",
+    export: "run",
+    category: "introspection",
+    summary: ["Render slim AI + self-contained HTML views of a final report"],
+  },
+  {
+    name: "render-final-report",
+    module: "./render-final-report.mjs",
+    export: "run",
+    category: "introspection",
+    summary: ["Render the markdown sibling of a final-report data.json"],
+  },
+  {
+    name: "inject-report-index",
+    module: "./inject-report-index.mjs",
+    export: "run",
+    category: "introspection",
+    summary: ["Add the top-of-report Index + scroll anchors to a report"],
+  },
+  {
+    name: "spawn-followups",
+    module: "./spawn-followups.mjs",
+    export: "run",
+    category: "introspection",
+    summary: ["Create follow-up task bundles from a final report"],
+  },
+  {
+    name: "error-log",
+    module: "./error-log.mjs",
+    export: "run",
+    category: "introspection",
+    summary: ["Append run error events to the run error log"],
+  },
+  {
+    name: "memory",
+    module: "./memory.mjs",
+    export: "run",
+    category: "introspection",
+    summary: [
+      "Store and find user-home conversation memory under",
+      "~/.okstra/memory-book.",
+    ],
+  },
+];
+
+export const COMMANDS = new Map(
+  COMMAND_REGISTRY.map((c) => [
+    c.name,
+    () => import(c.module).then((m) => m[c.export]),
+  ]),
+);
+
+const PREAMBLE = `okstra — multi-agent cross-verification orchestrator for Claude Code
+
+This CLI is the installer/admin tool. Day-to-day usage happens inside a
+Claude Code session via slash commands (/okstra-setup, /okstra-run, ...).
+
+Quick start (CLI):
+  1. npx -y okstra@latest install                       # one-time, this machine
+  2. cd <your project>
+  3. npx -y okstra@latest setup --project-id <id>       # one-time, this project
+  4. open a Claude Code session and run /okstra-run     # start a task
+
+Inside a Claude Code session you can replace step 3 with /okstra-setup —
+both write the same <PROJECT_ROOT>/.okstra/project.json.
+
+Usage:
+  okstra <command> [options]
+`;
+
+const GLOBAL_OPTIONS = `  --version              Print okstra version and exit
+  --help                 Print this help`;
+
+const FOOTER = `
+
+Run 'okstra <command> --help' for command-specific options.
+Docs: https://github.com/Devonshin/okstra#readme
+`;
+
+function renderRow(command) {
+  const [first, ...rest] = command.summary;
+  const head = "  " + command.name.padEnd(SUMMARY_COLUMN - 2) + first;
+  const continuations = rest.map((line) => " ".repeat(SUMMARY_COLUMN) + line);
+  return [head, ...continuations].join("\n");
+}
+
+function renderRows(category) {
+  return COMMAND_REGISTRY.filter((c) => c.category === category)
+    .map(renderRow)
+    .join("\n");
+}
+
+export const USAGE =
+  PREAMBLE +
+  "\nAdmin commands:\n" +
+  renderRows("admin") +
+  "\n\nIntrospection commands (JSON output, used by skills to avoid python heredocs):\n" +
+  renderRows("introspection") +
+  "\n\nGlobal options:\n" +
+  GLOBAL_OPTIONS +
+  FOOTER;

package/src/codex-dispatch.mjs

@@ -0,0 +1,70 @@
+import { runPythonModule } from "./_python-helper.mjs";
+import { resolvePaths } from "./paths.mjs";
+
+const USAGE = `okstra codex-dispatch — dispatch CLI-backed workers for a prepared Codex run
+
+Usage:
+  okstra codex-dispatch --project-root <dir> --run-manifest <path> \\
+    [--workers codex[,gemini[,report-writer]]] [--dry-run] \\
+    [--idle-timeout-seconds <n>] \\
+    [--enable-codex-report-writer --report-writer-codex-model <model>]
+
+This command reads an existing run manifest produced by 'okstra codex-run' and
+dispatches only Codex-side supported workers. When --workers is omitted, the
+command selects the supported subset of the run roster (codex/gemini, plus
+report-writer only when explicitly opted in). Codex and gemini use their
+existing wrappers. The report-writer role is available only through explicit
+Codex opt-in because the prepared manifest still records the Claude-side report
+writer model by default. Explicitly requesting unsupported workers such as
+claude fails.
+
+Missing worker prompt files are generated automatically from the run manifest
+and active-run-context. Existing prompt files are never overwritten.
+When the Codex report-writer path completes, this command also runs the
+idempotent post-report steps: token-usage substitution, render-views,
+spawn-followups, and validate-run.
+
+  --workspace-root and --okstra-bin are owned by this command.
+`;
+
+const OWNED_FLAGS = new Set(["--workspace-root", "--okstra-bin"]);
+
+function isOwnedFlag(arg) {
+  if (OWNED_FLAGS.has(arg)) return true;
+  return [...OWNED_FLAGS].some((flag) => arg.startsWith(`${flag}=`));
+}
+
+export function buildCodexDispatchArgs(args, paths) {
+  return [
+    "--workspace-root", paths.workspace,
+    "--okstra-bin", paths.bin,
+    ...args,
+  ];
+}
+
+export async function run(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  if (args.length === 0) {
+    process.stdout.write(USAGE);
+    return 2;
+  }
+
+  const forbidden = args.find(isOwnedFlag);
+  if (forbidden) {
+    process.stderr.write(
+      `error: ${forbidden} is set by 'okstra codex-dispatch' itself — remove it from your args\n`,
+    );
+    return 2;
+  }
+
+  const paths = await resolvePaths();
+  const result = await runPythonModule({
+    module: "okstra_ctl.codex_dispatch",
+    args: buildCodexDispatchArgs(args, paths),
+    stdio: "inherit-stdout",
+  });
+  return result.code ?? 0;
+}

package/src/codex-run.mjs

@@ -0,0 +1,68 @@
+import { runPythonModule } from "./_python-helper.mjs";
+import { resolvePaths } from "./paths.mjs";
+
+const USAGE = `okstra codex-run — prepare a render-only Codex lead task bundle
+
+This is the dry-run entry point for the Codex lead adapter. It forwards to
+\`python3 -m okstra_ctl.run --render-only --lead-runtime codex\`, materializes
+the normal okstra task bundle, and prints the rendered lead prompt without
+dispatching workers.
+
+Usage:
+  okstra codex-run --project-root <dir> --project-id <id> \\
+    --task-group <tg> --task-id <tid> --task-type <type> \\
+    --task-brief <path-or-rel> [--workers <list>] [--directive <text>] \\
+    [--lead-model <m>] [--claude-model <m>] [--codex-model <m>] \\
+    [--gemini-model <m>] [--report-writer-model <m>] \\
+    [--related-tasks <list>] [--base-ref <ref>] \\
+    [--clarification-response <path>] [--work-category <cat>] \\
+    [--stage <auto|N>] [--stages <csv>] [--pr-template-path <path>] \\
+    [--fix-cycle <yes|no>]
+
+  --render-only and --lead-runtime are owned by this command.
+  Worker dispatch is intentionally disabled here; use 'okstra codex-dispatch'
+  with the rendered run manifest for CLI-backed codex/gemini workers.
+`;
+
+const OWNED_FLAGS = new Set(["--workspace-root", "--render-only", "--lead-runtime"]);
+
+function isOwnedFlag(arg) {
+  if (OWNED_FLAGS.has(arg)) return true;
+  return [...OWNED_FLAGS].some((flag) => arg.startsWith(`${flag}=`));
+}
+
+export function buildCodexRunArgs(args, workspaceRoot) {
+  return [
+    "--workspace-root", workspaceRoot,
+    "--render-only",
+    "--lead-runtime", "codex",
+    ...args,
+  ];
+}
+
+export async function run(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  if (args.length === 0) {
+    process.stdout.write(USAGE);
+    return 2;
+  }
+
+  const forbidden = args.find(isOwnedFlag);
+  if (forbidden) {
+    process.stderr.write(
+      `error: ${forbidden} is set by 'okstra codex-run' itself — remove it from your args\n`,
+    );
+    return 2;
+  }
+
+  const paths = await resolvePaths();
+  const result = await runPythonModule({
+    module: "okstra_ctl.run",
+    args: buildCodexRunArgs(args, paths.workspace),
+    stdio: "inherit-stdout",
+  });
+  return result.code ?? 0;
+}

package/src/doctor.mjs

@@ -3,6 +3,8 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { resolvePaths } from "./paths.mjs";
 import { fileExists, runProcess } from "./_proc.mjs";
+import { runPythonSnippet } from "./_python-helper.mjs";
+import { runtimeIncludesClaudeAssets, validateInstallRuntime } from "./install.mjs";
 
 const CLAUDE_SKILLS_DIR = join(homedir(), ".claude", "skills");
 const REQUIRED_SKILLS = ["okstra-setup", "okstra-run"];
@@ -11,8 +13,9 @@ const USAGE = `okstra doctor — diagnose the installed runtime
 
 Usage:
   okstra doctor               Run all checks and print a summary
+  okstra doctor --runtime <claude-code|codex|external|all>
+  okstra doctor --phase <phase>
   okstra doctor --json        Machine-readable result
-
 Checks:
   - python3 binary and version (>= 3.10)
   - okstra_project module importable from $HOME/.okstra/lib/python
@@ -20,9 +23,70 @@ Checks:
   - bash entrypoints present and executable in $HOME/.okstra/bin
   - agents/ directory exists inside the okstra package
   - canonical skills present at $HOME/.claude/skills/<name>/SKILL.md
+    (skipped with --runtime codex)
   - version stamp matches package version
+  - optional phase readiness checks with --phase <phase>
+
+Supported phase readiness checks:
+  - implementation: git worktree support, approved-plan validator, worker agents
+  - final-verification: worktree registry, validators, final-report assets
+  - release-handoff: gh auth, clean git tree, remote, non-base branch
+  - improvement-discovery: required workers and lens whitelist
 `;
 
+export function parseDoctorArgs(args) {
+  const result = {
+    jsonMode: false,
+    phase: null,
+    runtime: "claude-code",
+  };
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--json") {
+      result.jsonMode = true;
+    } else if (arg === "--runtime" || arg.startsWith("--runtime=")) {
+      const value = arg.startsWith("--runtime=") ? arg.slice("--runtime=".length) : args[i + 1];
+      if (!value || value.startsWith("--")) {
+        throw new Error("--runtime requires one of: claude-code, codex, external, all");
+      }
+      result.runtime = validateInstallRuntime(value);
+      if (arg === "--runtime") i++;
+    } else if (arg === "--phase" || arg.startsWith("--phase=")) {
+      const value = arg.startsWith("--phase=") ? arg.slice("--phase=".length) : args[i + 1];
+      if (!value || value.startsWith("--")) {
+        throw new Error("--phase requires a phase name");
+      }
+      result.phase = value;
+      if (arg === "--phase") i++;
+    } else {
+      throw new Error(`unknown argument '${arg}'`);
+    }
+  }
+  return result;
+}
+
+export function requiredSkillNamesForRuntime(runtime) {
+  return runtimeIncludesClaudeAssets(runtime) ? REQUIRED_SKILLS : [];
+}
+
+export function phaseDiagnosticsToChecks(phase, phaseDiagnostics) {
+  const checks = Array.isArray(phaseDiagnostics.checks) ? phaseDiagnostics.checks : [];
+  if (checks.length === 0) {
+    return [
+      {
+        name: `phase ${phase}: diagnostics`,
+        ok: false,
+        detail: phaseDiagnostics.reason || "phase diagnostics returned no checks",
+      },
+    ];
+  }
+  return checks.map((item) => ({
+    name: `phase ${phase}: ${item.name}`,
+    ok: Boolean(item.ok),
+    detail: String(item.detail ?? ""),
+  }));
+}
+
 async function checkPython3() {
   const r = await runProcess("python3", ["--version"]);
   if (r.code !== 0) return { ok: false, detail: `python3 not found: ${r.stderr.trim() || "missing binary"}` };
@@ -69,12 +133,54 @@ async function check(name, fn) {
   }
 }
 
+async function loadPhaseDiagnostics(phase, paths) {
+  const script = [
+    "import json, sys",
+    "from okstra_ctl.doctor import phase_diagnostics",
+    "payload = phase_diagnostics(",
+    "    sys.argv[1],",
+    "    cwd=sys.argv[2],",
+    "    workspace_root=sys.argv[3],",
+    "    home=sys.argv[4],",
+    ")",
+    "print(json.dumps(payload, ensure_ascii=False))",
+  ].join("\n");
+  const result = await runPythonSnippet({
+    script,
+    args: [phase, process.cwd(), paths.workspace, paths.home],
+  });
+  if (result.code !== 0 && !result.stdout.trim()) {
+    return {
+      ok: false,
+      usageError: false,
+      reason: `python invocation failed: ${result.stderr.trim() || "no output"}`,
+      checks: [],
+    };
+  }
+  try {
+    return JSON.parse(result.stdout);
+  } catch (err) {
+    return {
+      ok: false,
+      usageError: false,
+      reason: `could not parse phase diagnostics output: ${err.message}`,
+      checks: [],
+    };
+  }
+}
+
 export async function run(args) {
   if (args.includes("--help") || args.includes("-h")) {
     process.stdout.write(USAGE);
     return 0;
   }
-  const jsonMode = args.includes("--json");
+  let opts;
+  try {
+    opts = parseDoctorArgs(args);
+  } catch (err) {
+    process.stderr.write(`error: ${err.message}\n`);
+    return 2;
+  }
   const paths = await resolvePaths();
 
   const results = [
@@ -91,7 +197,7 @@ export async function run(args) {
     await check("bin: okstra-gemini-exec.sh", () => checkBashEntry(paths.bin, "okstra-gemini-exec.sh")),
     await check("bin: okstra-central.sh", () => checkBashEntry(paths.bin, "okstra-central.sh")),
     ...(await Promise.all(
-      REQUIRED_SKILLS.map((name) =>
+      requiredSkillNamesForRuntime(opts.runtime).map((name) =>
         check(`skill: ${name}`, async () => {
           const p = join(CLAUDE_SKILLS_DIR, name, "SKILL.md");
           return (await fileExists(p))
@@ -107,10 +213,29 @@ export async function run(args) {
     ),
   ];
 
+  let phaseDiagnostics = null;
+  if (opts.phase) {
+    phaseDiagnostics = await loadPhaseDiagnostics(opts.phase, paths);
+    if (phaseDiagnostics.usageError) {
+      process.stderr.write(`error: ${phaseDiagnostics.reason}\n`);
+      return 2;
+    }
+    results.push(...phaseDiagnosticsToChecks(opts.phase, phaseDiagnostics));
+  }
+
   const allOk = results.every((r) => r.ok);
 
-  if (jsonMode) {
-    process.stdout.write(`${JSON.stringify({ ok: allOk, paths, checks: results }, null, 2)}\n`);
+  if (opts.jsonMode) {
+    process.stdout.write(
+      `${JSON.stringify({
+        ok: allOk,
+        runtime: opts.runtime,
+        phase: opts.phase,
+        paths,
+        phaseDiagnostics,
+        checks: results,
+      }, null, 2)}\n`,
+    );
     return allOk ? 0 : 1;
   }