okstra 0.111.0 → 0.113.0

package/src/cli-registry.mjs

@@ -45,6 +45,13 @@ export const COMMAND_REGISTRY = [
     category: "admin",
     summary: ["Verify the current project has been registered with setup"],
   },
+  {
+    name: "preflight",
+    module: "./commands/lifecycle/preflight.mjs",
+    export: "run",
+    category: "admin",
+    summary: ["One-call skill preflight: ensure-installed + check-project (JSON)"],
+  },
   {
     name: "config",
     module: "./commands/lifecycle/config.mjs",
@@ -117,6 +124,13 @@ export const COMMAND_REGISTRY = [
     category: "introspection",
     summary: ["Resolve a bare task-id to candidate task-keys from the catalog"],
   },
+  {
+    name: "set-work-status",
+    module: "./commands/inspect/set-work-status.mjs",
+    export: "run",
+    category: "introspection",
+    summary: ["Set a task's user-managed workStatus in task-manifest.json"],
+  },
   {
     name: "time-report",
     module: "./commands/inspect/time-report.mjs",

package/src/commands/inspect/set-work-status.mjs

@@ -0,0 +1,31 @@
+import { runPythonModule } from "../../lib/python-helper.mjs";
+
+const USAGE = `okstra set-work-status — set a task's user-managed workStatus
+
+Usage:
+  okstra set-work-status <token> <status> [--note <text>] [--task-group <g>]
+                         [--project-root <dir>] [--cwd <dir>] [--json]
+
+<token> is a full task-key (<project-id>:<task-group>:<task-id>) or a bare
+task-id. <status> is one of: todo | in-progress | blocked | done.
+
+Updates workStatus + workStatusUpdatedAt in task-manifest.json (workStatusNote
+only when --note is passed) using the same JSON serialization as the manifest
+renderer. Output: JSON { ok, taskKey, previousWorkStatus, workStatus, ... };
+ok:false stages: resolve | catalog | not-found | ambiguous (pick from
+matches[]) | manifest-missing | manifest-invalid.
+`;
+
+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.set_work_status",
+    args,
+    stdio: "inherit-stdout",
+  });
+  return result.code;
+}

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;
+}