role-os 1.8.0 → 2.0.0

package/bin/roleos.mjs

@@ -1,140 +1,205 @@
-#!/usr/bin/env node
-
-import { readFileSync } from "node:fs";
-import { join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
-import { initCommand } from "../src/init.mjs";
-import { packetCommand } from "../src/packet.mjs";
-import { routeCommand } from "../src/route.mjs";
-import { reviewCommand } from "../src/review.mjs";
-import { statusCommand } from "../src/status.mjs";
-import { packsCommand } from "../src/packs-cmd.mjs";
-import { scaffoldClaude, doctor, formatDoctor } from "../src/session.mjs";
-import { artifactsCommand } from "../src/artifacts-cmd.mjs";
-import { missionCommand } from "../src/mission-cmd.mjs";
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const VERSION = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8")).version;
-
-function printHelp() {
-  console.log(`
-roleos v${VERSION} — Role OS bootstrap CLI
-
-Usage:
-  roleos init                        Scaffold Role OS into .claude/
-  roleos init --force                Update canonical files (protects context/)
-  roleos packet new <type>           Create a new packet (feature|integration|identity)
-  roleos route <packet-file> [--verbose]  Recommend the smallest valid chain
-  roleos review <packet-file> <verdict>  Record a review verdict
-  roleos status                      Show active work, verdicts, and health
-  roleos status --write              Write .claude/status/index.md
-  roleos status --json               Output as JSON
-  roleos packs list                  List all available team packs
-  roleos packs suggest <packet-file> Suggest a pack for a packet
-  roleos packs show <pack-key>       Show full detail for a named pack
-  roleos artifacts                   List all role artifact contracts
-  roleos artifacts show <role>       Show artifact contract for a role
-  roleos artifacts validate <role> <file>  Validate a file against a contract
-  roleos artifacts chain <pack>      Show pack handoff flow
-  roleos mission list                List all missions
-  roleos mission show <key>          Show full mission detail
-  roleos mission suggest <text>      Suggest a mission for a task
-  roleos mission validate [key]      Validate mission wiring
-  roleos doctor                      Verify repo is wired for Role OS sessions
-  roleos help                        Show this help
-
-Verdicts: accept | accept-with-notes | reject | blocked
-`);
-}
-
-/**
- * Structured error output. Matches shipcheck error shape:
- * code, message, hint, cause?, retryable?
- */
-function handleError(err) {
-  const isUserError = err.exitCode === 1;
-  const code = isUserError ? "USER_ERROR" : "RUNTIME_ERROR";
-  const exitCode = isUserError ? 1 : 2;
-
-  if (process.argv.includes("--debug")) {
-    console.error(err.stack || err);
-  } else {
-    console.error(JSON.stringify({
-      code,
-      message: err.message,
-      hint: err.hint || null,
-      retryable: false,
-    }));
-  }
-
-  process.exit(exitCode);
-}
-
-const command = process.argv[2] || "help";
-const args = process.argv.slice(3);
-
-try {
-  switch (command) {
-    case "init":
-      if (args[0] === "claude") {
-        const force = args.includes("--force");
-        const result = scaffoldClaude(process.cwd(), { force });
-        if (result.created.length > 0) {
-          console.log(`Created:`);
-          result.created.forEach(f => console.log(`  + ${f}`));
-        }
-        if (result.skipped.length > 0) {
-          console.log(`Skipped:`);
-          result.skipped.forEach(f => console.log(`  ~ ${f}`));
-        }
-        console.log(`\nDone. Claude Code will now use Role OS for routing.\nRun: roleos doctor  to verify.`);
-      } else {
-        await initCommand(args);
-      }
-      break;
-    case "doctor": {
-      const result = doctor(process.cwd());
-      console.log(formatDoctor(result));
-      if (!result.healthy) process.exit(1);
-      break;
-    }
-    case "packet":
-      await packetCommand(args);
-      break;
-    case "route":
-      await routeCommand(args);
-      break;
-    case "review":
-      await reviewCommand(args);
-      break;
-    case "status":
-      await statusCommand(args);
-      break;
-    case "packs":
-      await packsCommand(args);
-      break;
-    case "artifacts":
-      await artifactsCommand(args);
-      break;
-    case "mission":
-      await missionCommand(args);
-      break;
-    case "help":
-    case "--help":
-    case "-h":
-      printHelp();
-      break;
-    case "--version":
-    case "-v":
-      console.log(`roleos v${VERSION}`);
-      break;
-    default: {
-      const err = new Error(`Unknown command: ${command}`);
-      err.exitCode = 1;
-      err.hint = "Run 'roleos help' for usage.";
-      throw err;
-    }
-  }
-} catch (err) {
-  handleError(err);
-}
+#!/usr/bin/env node
+
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { initCommand } from "../src/init.mjs";
+import { packetCommand } from "../src/packet.mjs";
+import { routeCommand } from "../src/route.mjs";
+import { reviewCommand } from "../src/review.mjs";
+import { statusCommand } from "../src/status.mjs";
+import { packsCommand } from "../src/packs-cmd.mjs";
+import { scaffoldClaude, doctor, formatDoctor } from "../src/session.mjs";
+import { artifactsCommand } from "../src/artifacts-cmd.mjs";
+import { missionCommand } from "../src/mission-cmd.mjs";
+import { startCommand } from "../src/entry-cmd.mjs";
+import {
+  runCommand, resumeCommand, nextCommand, explainCommand,
+  completeCommand, failCommand, retryCommand, rerouteCommand,
+  escalateCommand, blockCommand, reopenCommand, reportCommand,
+  frictionCommand,
+} from "../src/run-cmd.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const VERSION = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8")).version;
+
+function printHelp() {
+  console.log(`
+roleos v${VERSION} — Role OS bootstrap CLI
+
+Usage:
+  roleos start <task>                 Decide entry path: mission, pack, or free routing
+  roleos run "<task>"                Create and start a persistent run
+  roleos run list                    List all runs
+  roleos run show <id>               Show run detail
+  roleos resume [id]                 Resume an interrupted run
+  roleos next                        Start the next step (or show what's next)
+  roleos explain [id]                Explain current run state
+  roleos complete <artifact> [note]  Complete the active step
+  roleos fail <partial|failed> <reason>  Fail the active step
+  roleos retry <step-index>          Retry a failed step
+  roleos reroute <step> <role> <reason>  Reroute a step to a different role
+  roleos escalate <from> <to> <trigger> <action>  Escalate between roles
+  roleos block <step-index> <reason> Block a step
+  roleos reopen <step-index> <reason> Reopen a completed step
+  roleos report [id]                 Generate completion report
+  roleos friction [id]               Measure operator friction
+  roleos init                        Scaffold Role OS into .claude/
+  roleos init --force                Update canonical files (protects context/)
+  roleos packet new <type>           Create a new packet (feature|integration|identity)
+  roleos route <packet-file> [--verbose]  Recommend the smallest valid chain
+  roleos review <packet-file> <verdict>  Record a review verdict
+  roleos status                      Show active work, verdicts, and health
+  roleos status --write              Write .claude/status/index.md
+  roleos status --json               Output as JSON
+  roleos packs list                  List all available team packs
+  roleos packs suggest <packet-file> Suggest a pack for a packet
+  roleos packs show <pack-key>       Show full detail for a named pack
+  roleos artifacts                   List all role artifact contracts
+  roleos artifacts show <role>       Show artifact contract for a role
+  roleos artifacts validate <role> <file>  Validate a file against a contract
+  roleos artifacts chain <pack>      Show pack handoff flow
+  roleos mission list                List all missions
+  roleos mission show <key>          Show full mission detail
+  roleos mission suggest <text>      Suggest a mission for a task
+  roleos mission validate [key]      Validate mission wiring
+  roleos doctor                      Verify repo is wired for Role OS sessions
+  roleos help                        Show this help
+
+Verdicts: accept | accept-with-notes | reject | blocked
+`);
+}
+
+/**
+ * Structured error output. Matches shipcheck error shape:
+ * code, message, hint, cause?, retryable?
+ */
+function handleError(err) {
+  const isUserError = err.exitCode === 1;
+  const code = isUserError ? "USER_ERROR" : "RUNTIME_ERROR";
+  const exitCode = isUserError ? 1 : 2;
+
+  if (process.argv.includes("--debug")) {
+    console.error(err.stack || err);
+  } else {
+    console.error(JSON.stringify({
+      code,
+      message: err.message,
+      hint: err.hint || null,
+      retryable: false,
+    }));
+  }
+
+  process.exit(exitCode);
+}
+
+const command = process.argv[2] || "help";
+const args = process.argv.slice(3);
+
+try {
+  switch (command) {
+    case "start":
+      await startCommand(args);
+      break;
+    case "init":
+      if (args[0] === "claude") {
+        const force = args.includes("--force");
+        const result = scaffoldClaude(process.cwd(), { force });
+        if (result.created.length > 0) {
+          console.log(`Created:`);
+          result.created.forEach(f => console.log(`  + ${f}`));
+        }
+        if (result.skipped.length > 0) {
+          console.log(`Skipped:`);
+          result.skipped.forEach(f => console.log(`  ~ ${f}`));
+        }
+        console.log(`\nDone. Claude Code will now use Role OS for routing.\nRun: roleos doctor  to verify.`);
+      } else {
+        await initCommand(args);
+      }
+      break;
+    case "doctor": {
+      const result = doctor(process.cwd());
+      console.log(formatDoctor(result));
+      if (!result.healthy) process.exit(1);
+      break;
+    }
+    case "packet":
+      await packetCommand(args);
+      break;
+    case "route":
+      await routeCommand(args);
+      break;
+    case "review":
+      await reviewCommand(args);
+      break;
+    case "status":
+      await statusCommand(args);
+      break;
+    case "packs":
+      await packsCommand(args);
+      break;
+    case "artifacts":
+      await artifactsCommand(args);
+      break;
+    case "run":
+      await runCommand(args);
+      break;
+    case "resume":
+      await resumeCommand(args);
+      break;
+    case "next":
+      await nextCommand(args);
+      break;
+    case "explain":
+      await explainCommand(args);
+      break;
+    case "complete":
+      await completeCommand(args);
+      break;
+    case "fail":
+      await failCommand(args);
+      break;
+    case "retry":
+      await retryCommand(args);
+      break;
+    case "reroute":
+      await rerouteCommand(args);
+      break;
+    case "escalate":
+      await escalateCommand(args);
+      break;
+    case "block":
+      await blockCommand(args);
+      break;
+    case "reopen":
+      await reopenCommand(args);
+      break;
+    case "report":
+      await reportCommand(args);
+      break;
+    case "friction":
+      await frictionCommand(args);
+      break;
+    case "mission":
+      await missionCommand(args);
+      break;
+    case "help":
+    case "--help":
+    case "-h":
+      printHelp();
+      break;
+    case "--version":
+    case "-v":
+      console.log(`roleos v${VERSION}`);
+      break;
+    default: {
+      const err = new Error(`Unknown command: ${command}`);
+      err.exitCode = 1;
+      err.hint = "Run 'roleos help' for usage.";
+      throw err;
+    }
+  }
+} catch (err) {
+  handleError(err);
+}

package/package.json

@@ -1,51 +1,51 @@
-{
-  "name": "role-os",
-  "version": "1.8.0",
-  "description": "Role OS — a multi-Claude operating system where 31 specialized roles execute work through contracts, conflict detection, escalation, and structured evidence. 7 proven team packs for common task families.",
-  "homepage": "https://mcp-tool-shop-org.github.io/role-os/",
-  "bugs": {
-    "url": "https://github.com/mcp-tool-shop-org/role-os/issues"
-  },
-  "type": "module",
-  "bin": {
-    "roleos": "bin/roleos.mjs"
-  },
-  "files": [
-    "bin",
-    "src",
-    "starter-pack",
-    "README.md",
-    "CHANGELOG.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "test": "node --test test/*.test.mjs",
-    "verify": "node --test test/*.test.mjs && node bin/roleos.mjs help && echo '✓ verify passed'"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "author": "mcp-tool-shop <64996768+mcp-tool-shop@users.noreply.github.com>",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/mcp-tool-shop-org/role-os.git"
-  },
-  "keywords": [
-    "role-os",
-    "agents",
-    "contracts",
-    "handoffs",
-    "review",
-    "workflow",
-    "multi-agent",
-    "ai-workflow",
-    "developer-tools",
-    "role-contracts",
-    "claude",
-    "multi-claude"
-  ],
-  "publishConfig": {
-    "registry": "https://registry.npmjs.org"
-  }
-}
+{
+  "name": "role-os",
+  "version": "2.0.0",
+  "description": "Role OS — a multi-Claude operating system where 31 specialized roles execute work through contracts, conflict detection, escalation, and structured evidence. 7 proven team packs for common task families.",
+  "homepage": "https://mcp-tool-shop-org.github.io/role-os/",
+  "bugs": {
+    "url": "https://github.com/mcp-tool-shop-org/role-os/issues"
+  },
+  "type": "module",
+  "bin": {
+    "roleos": "bin/roleos.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "starter-pack",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "verify": "node --test test/*.test.mjs && node bin/roleos.mjs help && echo '✓ verify passed'"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "author": "mcp-tool-shop <64996768+mcp-tool-shop@users.noreply.github.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mcp-tool-shop-org/role-os.git"
+  },
+  "keywords": [
+    "role-os",
+    "agents",
+    "contracts",
+    "handoffs",
+    "review",
+    "workflow",
+    "multi-agent",
+    "ai-workflow",
+    "developer-tools",
+    "role-contracts",
+    "claude",
+    "multi-claude"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org"
+  }
+}

package/src/entry-cmd.mjs

@@ -0,0 +1,59 @@
+/**
+ * Entry CLI — Phase T (v1.9.0)
+ *
+ * roleos start <task description>     Decide best entry path automatically
+ * roleos start --json <text>          Output as JSON
+ */
+
+import { decideEntry, formatEntryDecision } from "./entry.mjs";
+
+/**
+ * @param {string[]} args
+ */
+export async function startCommand(args) {
+  const isJson = args.includes("--json");
+  const textArgs = args.filter(a => a !== "--json");
+  const text = textArgs.join(" ").trim();
+
+  if (!text) {
+    const err = new Error(
+      "Usage: roleos start <task description>\n" +
+      "  Decides whether to route through a mission, pack, or free routing.\n\n" +
+      "Examples:\n" +
+      '  roleos start "fix the crash in save handler"\n' +
+      '  roleos start "add a new export command"\n' +
+      '  roleos start "run the full treatment before publishing"'
+    );
+    err.exitCode = 1;
+    err.hint = "Describe the task you want to accomplish.";
+    throw err;
+  }
+
+  const decision = decideEntry(text);
+
+  if (isJson) {
+    console.log(JSON.stringify(decision, null, 2));
+  } else {
+    console.log("");
+    console.log(formatEntryDecision(decision));
+    console.log("");
+
+    // Action guidance
+    if (decision.level === "mission") {
+      console.log("Next steps:");
+      console.log(`  1. roleos mission show ${decision.mission.key}     # review the mission`);
+      console.log(`  2. Create a packet and start working through the mission steps`);
+      console.log(`  3. Use the mission runner to track progress and artifacts`);
+    } else if (decision.level === "pack") {
+      console.log("Next steps:");
+      console.log(`  1. roleos packs show ${decision.pack.key}          # review the pack`);
+      console.log(`  2. roleos packet new feature                       # create a packet`);
+      console.log(`  3. roleos route <packet> --pack=${decision.pack.key}   # route with pack`);
+    } else {
+      console.log("Next steps:");
+      console.log("  1. roleos packet new feature                       # create a packet");
+      console.log("  2. roleos route <packet>                           # free routing");
+    }
+    console.log("");
+  }
+}