okstra 0.110.0 → 0.112.0

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

@@ -40,8 +40,8 @@ const SCRIPT = `
 import json, sys
 from pathlib import Path
 from okstra_project import (
-    resolve_project_root, find_task_root, read_task_manifest,
-    ResolverError,
+    resolve_project_root, task_read_side_snapshot,
+    ResolverError, StateError,
 )
 
 explicit = sys.argv[1]
@@ -55,37 +55,17 @@ except ResolverError as e:
     sys.exit(2)
 
 pr_path = Path(pr)
-task_root = find_task_root(pr_path, task_key)
-if task_root is None:
-    print(json.dumps({"ok": False, "stage": "task_root_missing", "reason": f"no task root for {task_key}"}))
-    sys.exit(1)
-
-manifest = read_task_manifest(task_root)
-if manifest is None:
-    print(json.dumps({"ok": False, "stage": "manifest_missing", "reason": f"task-manifest.json missing in {task_root}"}))
+try:
+    snapshot = task_read_side_snapshot(pr_path, task_key)
+except StateError as e:
+    print(json.dumps({
+        "ok": False,
+        "stage": getattr(e, "stage", None) or "task_snapshot",
+        "reason": str(e),
+    }))
     sys.exit(1)
 
-wf = manifest.get("workflow", {}) or {}
-out = {
-    "ok": True,
-    "projectRoot": str(pr_path),
-    "taskKey": manifest.get("taskKey"),
-    "taskType": manifest.get("taskType"),
-    "taskRoot": str(task_root),
-    "taskBriefPath": manifest.get("taskBriefPath"),
-    "workflow": {
-        "currentPhase": wf.get("currentPhase"),
-        "currentPhaseState": wf.get("currentPhaseState"),
-        "lastCompletedPhase": wf.get("lastCompletedPhase"),
-        "nextRecommendedPhase": wf.get("nextRecommendedPhase"),
-        "routingStatus": wf.get("routingStatus"),
-        "phaseStates": wf.get("phaseStates"),
-    },
-    "resultContract": manifest.get("resultContract"),
-    "artifacts": manifest.get("artifacts"),
-    "modelAssignments": manifest.get("modelAssignments"),
-    "latestRunPath": manifest.get("latestRunPath"),
-}
+out = {"ok": True, **snapshot}
 print(json.dumps(out, ensure_ascii=False, default=str, indent=2))
 `;
 

package/src/commands/lifecycle/check-project.mjs

@@ -63,6 +63,14 @@ export async function run(args) {
     process.stderr.write(`error: ${err.message}\n\n${USAGE}`);
     return 2;
   }
+  const { code, payload } = await checkProject({ cwd: opts.cwd });
+  emit(opts, payload);
+  return code;
+}
+
+// Core check shared with 'okstra preflight' — resolves PROJECT_ROOT from cwd
+// and validates .okstra/project.json without writing to stdout.
+export async function checkProject({ cwd = process.cwd() } = {}) {
   const paths = await resolvePaths();
 
   const probe = await runProcess(
@@ -79,23 +87,25 @@ export async function run(args) {
         "except ResolverError as e:",
         "    print('RESOLVER_ERROR', e)",
       ].join("\n"),
-      opts.cwd,
+      cwd,
     ],
     { PYTHONPATH: buildPythonpath(paths) },
   );
 
   if (probe.code !== 0) {
     const raw = probe.stderr.trim() || probe.stdout.trim();
-    emit(opts, {
-      ok: false,
-      stage: "python",
-      reason:
-        `python invocation failed: ${raw}. ` +
-        "This usually means the okstra runtime is stale or missing — " +
-        "run 'okstra doctor' to diagnose, then 'okstra ensure-installed' " +
-        "to repair.",
-    });
-    return 1;
+    return {
+      code: 1,
+      payload: {
+        ok: false,
+        stage: "python",
+        reason:
+          `python invocation failed: ${raw}. ` +
+          "This usually means the okstra runtime is stale or missing — " +
+          "run 'okstra doctor' to diagnose, then 'okstra ensure-installed' " +
+          "to repair.",
+      },
+    };
   }
 
   const lines = probe.stdout.trim().split("\n");
@@ -107,36 +117,37 @@ export async function run(args) {
 
   const resolverError = tagOf("RESOLVER_ERROR");
   if (resolverError) {
-    emit(opts, {
-      ok: false,
-      stage: "resolve",
-      reason: resolverError,
-      cwd: opts.cwd,
-    });
-    return 2;
+    return {
+      code: 2,
+      payload: { ok: false, stage: "resolve", reason: resolverError, cwd },
+    };
   }
 
   const projectRoot = tagOf("PROJECT_ROOT");
   const projectJsonPath = tagOf("PROJECT_JSON");
   if (!projectRoot || !projectJsonPath) {
-    emit(opts, {
-      ok: false,
-      stage: "parse",
-      reason: "could not parse python output",
-      raw: probe.stdout,
-    });
-    return 1;
+    return {
+      code: 1,
+      payload: {
+        ok: false,
+        stage: "parse",
+        reason: "could not parse python output",
+        raw: probe.stdout,
+      },
+    };
   }
 
   if (!(await fileExists(projectJsonPath))) {
-    emit(opts, {
-      ok: false,
-      stage: "project_json_missing",
-      reason: `${projectJsonPath} not found — run /okstra-setup in this project first`,
-      projectRoot,
-      projectJsonPath,
-    });
-    return 1;
+    return {
+      code: 1,
+      payload: {
+        ok: false,
+        stage: "project_json_missing",
+        reason: `${projectJsonPath} not found — run /okstra-setup in this project first`,
+        projectRoot,
+        projectJsonPath,
+      },
+    };
   }
 
   let projectId = null;
@@ -144,32 +155,33 @@ export async function run(args) {
     const data = JSON.parse(await fs.readFile(projectJsonPath, "utf8"));
     projectId = typeof data?.projectId === "string" ? data.projectId : null;
   } catch (err) {
-    emit(opts, {
-      ok: false,
-      stage: "project_json_invalid",
-      reason: `failed to parse ${projectJsonPath}: ${err.message}`,
-      projectRoot,
-      projectJsonPath,
-    });
-    return 1;
+    return {
+      code: 1,
+      payload: {
+        ok: false,
+        stage: "project_json_invalid",
+        reason: `failed to parse ${projectJsonPath}: ${err.message}`,
+        projectRoot,
+        projectJsonPath,
+      },
+    };
   }
 
   if (!projectId) {
-    emit(opts, {
-      ok: false,
-      stage: "project_json_invalid",
-      reason: `${projectJsonPath} missing projectId field`,
-      projectRoot,
-      projectJsonPath,
-    });
-    return 1;
+    return {
+      code: 1,
+      payload: {
+        ok: false,
+        stage: "project_json_invalid",
+        reason: `${projectJsonPath} missing projectId field`,
+        projectRoot,
+        projectJsonPath,
+      },
+    };
   }
 
-  emit(opts, {
-    ok: true,
-    projectRoot,
-    projectJsonPath,
-    projectId,
-  });
-  return 0;
+  return {
+    code: 0,
+    payload: { ok: true, projectRoot, projectJsonPath, projectId },
+  };
 }

package/src/commands/lifecycle/install.mjs

@@ -48,6 +48,7 @@ const REQUIRED_PROMPT_RESOURCE_FILES = Object.freeze([
   ["prompts", "lead", "context-loader.md"],
   ["prompts", "lead", "team-contract.md"],
   ["prompts", "lead", "convergence.md"],
+  ["prompts", "lead", "plan-body-verification.md"],
   ["prompts", "lead", "report-writer.md"],
   ["prompts", "coding-preflight", "overview.md"],
   ["prompts", "coding-preflight", "clean-code.md"],

package/src/commands/lifecycle/preflight.mjs

@@ -0,0 +1,82 @@
+import { checkProject } from "./check-project.mjs";
+import { runEnsureInstalled } from "./install.mjs";
+
+const USAGE = `okstra preflight — one-call skill preflight (ensure-installed + check-project)
+
+Usage:
+  okstra preflight [--runtime <name>] [--cwd <dir>] [--json]
+
+Runs the runtime freshness check (quietly reinstalling when stale), then
+verifies the target project has .okstra/project.json. Prints one JSON object:
+
+  ok: true   {ok, projectRoot, projectJsonPath, projectId}
+  ok: false  {ok, stage, reason, ...}
+             stage: install | resolve | project_json_missing |
+                    project_json_invalid | python | parse
+
+Options:
+  --runtime <name>   Runtime whose assets must be present (e.g. claude-code);
+                     forwarded to ensure-installed.
+  --cwd <dir>        Resolve PROJECT_ROOT from <dir> instead of process cwd.
+  --json             Default output format (kept for symmetry).
+
+Exit codes:
+  0   runtime fresh and project registered
+  1   runtime install failed, or project setup missing/invalid
+  2   PROJECT_ROOT could not be resolved from cwd (pass --cwd), or bad flags
+`;
+
+function parseArgs(args) {
+  const opts = { cwd: process.cwd(), runtime: null };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--json") continue;
+    if (a === "--cwd" || a === "--runtime") {
+      const next = args[i + 1];
+      if (!next || next.startsWith("--")) throw new Error(`${a} requires a value`);
+      if (a === "--cwd") opts.cwd = next;
+      else opts.runtime = next;
+      i++;
+    } else {
+      throw new Error(`unknown argument '${a}'`);
+    }
+  }
+  return opts;
+}
+
+function emit(payload) {
+  process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
+}
+
+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 ensureArgs = ["--quiet"];
+  if (opts.runtime) ensureArgs.push("--runtime", opts.runtime);
+  const installCode = await runEnsureInstalled(ensureArgs);
+  if (installCode !== 0) {
+    emit({
+      ok: false,
+      stage: "install",
+      reason:
+        "okstra runtime install failed — run 'okstra doctor' to diagnose, " +
+        "then 'okstra install' to repair.",
+    });
+    return installCode === 2 ? 2 : 1;
+  }
+
+  const { code, payload } = await checkProject({ cwd: opts.cwd });
+  emit(payload);
+  return code;
+}