role-os 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # Changelog
 
+## 1.5.0
+
+### Added
+
+#### Hook Spine / Runtime Enforcement (Phase R)
+- 5 lifecycle hooks: SessionStart, UserPromptSubmit, PreToolUse, SubagentStart, Stop
+- `scaffoldHooks()` generates all 5 hook scripts in .claude/hooks/
+- `roleos init claude` now scaffolds hooks + settings.local.json with hook config
+- `roleos doctor` now checks for hook scripts (check 7) and settings hooks (check 8)
+
+#### SessionStart hook
+- Establishes session contract on every new session
+- Records session ID, timestamp, initializes state tracking
+- Adds context reminding Claude to use /roleos-route for non-trivial tasks
+
+#### UserPromptSubmit hook
+- Classifies prompts as substantial (>50 chars + action verbs)
+- After 2+ substantial prompts without a route card, adds context reminder
+- Does not block — advisory enforcement
+
+#### PreToolUse hook
+- Records all tool usage in session state
+- Flags write tools (Bash, Write, Edit) used without route card after substantial work
+- Advisory, not blocking — preserves operator control
+
+#### SubagentStart hook
+- Injects active role contract into delegated agents
+- Ensures subagents inherit the Role OS session context
+
+#### Stop hook
+- Warns when substantial sessions end without route card or outcome artifact
+- Advisory — does not block session exit
+- Trivial sessions (< 2 substantial prompts) are exempt
+
+### Evidence
+- 358 tests, zero failures
+- 23 new hook tests covering all 5 lifecycle hooks
+
+## 1.4.0
+
+### Added
+
+#### Session Spine (Phase Q)
+- `roleos init claude` — scaffolds Claude Code integration: CLAUDE.md instructions, /roleos-route + /roleos-review + /roleos-status slash commands
+- `roleos doctor` — verifies repo is correctly wired for Role OS sessions (6 checks: .claude/ dir, CLAUDE.md section, /roleos-route command, context files, role contracts, packets)
+- Route card generation — session header artifact proving Role OS was engaged (task type, pack, confidence, composite status, success artifact)
+- CLAUDE.md template instructs Claude to route through Role OS before non-trivial work
+- /roleos-route command produces structured route cards
+- /roleos-review command guides structured verdict production
+- /roleos-status command shows active work and context health
+- Appends to existing CLAUDE.md without overwriting (detects Role OS section)
+- --force flag overwrites existing command files
+
+### Evidence
+- 335 tests, zero failures
+
 ## 1.3.0
 
 ### Added

package/README.md

@@ -178,6 +178,8 @@ Role OS operates **locally only**. It copies markdown templates and writes packe
 | **Mixed-task decomposition** | Detects composite work, splits into child packets, assigns packs, preserves dependencies. | ✓ Shipped |
 | **Composite execution** | Runs child packets in dependency order with artifact passing, branch recovery, and synthesis. | ✓ Shipped |
 | **Adaptive replanning** | Mid-run scope changes, findings, or new requirements update the plan without restarting. | ✓ Shipped |
+| **Session spine** | `roleos init claude` scaffolds CLAUDE.md, /roleos-route, /roleos-review, /roleos-status. `roleos doctor` verifies wiring. Route cards prove engagement. | ✓ Shipped |
+| **Hook spine** | 5 lifecycle hooks (SessionStart, PromptSubmit, PreToolUse, SubagentStart, Stop). Advisory enforcement: route card reminders, write-tool gating, subagent role injection, completion audit. | ✓ Shipped |
 
 ## Status
 
@@ -186,7 +188,9 @@ Role OS operates **locally only**. It copies markdown templates and writes packe
 - v1.0.2: Role OS lockdown (bootstrap truth fixes, init --force)
 - v1.1.0: 31 roles, full routing spine, conflict detection, escalation, evidence, dispatch, 7 proven team packs. 35 execution trials. 212 tests.
 - v1.2.0: Calibrated packs promoted to default entry. Auto-selection, mismatch detection, alternative suggestion, free-routing fallback. 246 tests.
-- **Current**: Outcome calibration, mixed-task decomposition, composite execution, adaptive replanning. 317 tests.
+- v1.3.0: Outcome calibration, mixed-task decomposition, composite execution, adaptive replanning. 317 tests.
+- v1.4.0: Session spine — `roleos init claude`, `roleos doctor`, route cards, /roleos-route + /roleos-review + /roleos-status commands. 335 tests.
+- **v1.5.0**: Hook spine — 5 lifecycle hooks for runtime enforcement. Advisory route card reminders, write-tool gating, subagent role injection, completion audit. 358 tests.
 
 ## License
 

package/bin/roleos.mjs

@@ -9,6 +9,7 @@ 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";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const VERSION = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8")).version;
@@ -29,6 +30,7 @@ Usage:
   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 doctor                      Verify repo is wired for Role OS sessions
   roleos help                        Show this help
 
 Verdicts: accept | accept-with-notes | reject | blocked
@@ -64,8 +66,28 @@ const args = process.argv.slice(3);
 try {
   switch (command) {
     case "init":
-      await initCommand(args);
+      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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "role-os",
-  "version": "1.3.0",
+  "version": "1.5.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": {

package/src/hooks.mjs

@@ -0,0 +1,469 @@
+/**
+ * Hook Spine — v1.5.0 Runtime Enforcement
+ *
+ * Hooks verify, gate, and record. The actual routing intelligence
+ * stays in explicit artifacts (route cards, pack selection).
+ * Hooks are the proof layer, not the decision layer.
+ *
+ * Four guarantees:
+ * 1. No substantial task begins without a route artifact
+ * 2. No tool execution drifts outside the selected role envelope
+ * 3. No subagent runs without inheriting the role contract
+ * 4. No session ends without an outcome artifact
+ *
+ * Hook lifecycle events used:
+ * - SessionStart: establish session contract
+ * - UserPromptSubmit: classify before improvising
+ * - PreToolUse: enforce role-specific tool law
+ * - SubagentStart: inject role contract into delegation
+ * - Stop: prevent false completion
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+// ── Hook script generators ────────────────────────────────────────────────────
+
+/**
+ * Generate the settings.json hooks configuration.
+ * Each hook is a shell command that runs a Node script from .claude/hooks/.
+ *
+ * @returns {object} The hooks configuration object for settings.json
+ */
+export function generateHooksConfig() {
+  return {
+    hooks: {
+      SessionStart: [
+        {
+          matcher: "",
+          hooks: [{
+            type: "command",
+            command: "node .claude/hooks/session-start.mjs",
+          }],
+        },
+      ],
+      UserPromptSubmit: [
+        {
+          matcher: "",
+          hooks: [{
+            type: "command",
+            command: "node .claude/hooks/prompt-submit.mjs",
+          }],
+        },
+      ],
+      PreToolUse: [
+        {
+          matcher: "",
+          hooks: [{
+            type: "command",
+            command: "node .claude/hooks/pre-tool-use.mjs",
+          }],
+        },
+      ],
+      SubagentStart: [
+        {
+          matcher: "",
+          hooks: [{
+            type: "command",
+            command: "node .claude/hooks/subagent-start.mjs",
+          }],
+        },
+      ],
+      Stop: [
+        {
+          matcher: "",
+          hooks: [{
+            type: "command",
+            command: "node .claude/hooks/stop.mjs",
+          }],
+        },
+      ],
+    },
+  };
+}
+
+// ── Session state ─────────────────────────────────────────────────────────────
+
+const SESSION_STATE_FILE = ".claude/hooks/session-state.json";
+
+/**
+ * Read or create session state.
+ * @param {string} cwd
+ * @returns {object}
+ */
+export function getSessionState(cwd) {
+  const path = join(cwd, SESSION_STATE_FILE);
+  if (existsSync(path)) {
+    try { return JSON.parse(readFileSync(path, "utf-8")); }
+    catch { /* fall through */ }
+  }
+  return {
+    sessionId: null,
+    routeCardPresent: false,
+    activeRole: null,
+    activePack: null,
+    toolsUsed: [],
+    promptCount: 0,
+    substantivePrompts: 0,
+    outcomeRecorded: false,
+    startedAt: null,
+  };
+}
+
+/**
+ * Save session state.
+ * @param {string} cwd
+ * @param {object} state
+ */
+export function saveSessionState(cwd, state) {
+  const dir = join(cwd, ".claude", "hooks");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(cwd, SESSION_STATE_FILE), JSON.stringify(state, null, 2));
+}
+
+// ── Hook logic ────────────────────────────────────────────────────────────────
+
+/**
+ * SessionStart hook logic.
+ * Establishes session contract, checks for existing route artifacts.
+ *
+ * @param {object} input - Hook input (session_id, cwd, etc.)
+ * @returns {{ addContext?: string }}
+ */
+export function onSessionStart(input) {
+  const cwd = input.cwd || process.cwd();
+  const state = getSessionState(cwd);
+
+  state.sessionId = input.session_id || `session-${Date.now()}`;
+  state.startedAt = new Date().toISOString();
+  state.routeCardPresent = false;
+  state.promptCount = 0;
+  state.substantivePrompts = 0;
+  state.outcomeRecorded = false;
+
+  saveSessionState(cwd, state);
+
+  // Check if Role OS is initialized
+  const hasRoleOs = existsSync(join(cwd, ".claude", "agents"));
+
+  if (hasRoleOs) {
+    return {
+      addContext: "Role OS is active in this repo. For non-trivial tasks, run /roleos-route to produce a route card before beginning work. The route card proves the task was classified and the right team was chosen.",
+    };
+  }
+
+  return {};
+}
+
+/**
+ * UserPromptSubmit hook logic.
+ * Detects substantial prompts and warns if no route artifact exists.
+ *
+ * @param {object} input - { prompt, session_id, cwd }
+ * @returns {{ addContext?: string, block?: { reason: string } }}
+ */
+export function onPromptSubmit(input) {
+  const cwd = input.cwd || process.cwd();
+  const state = getSessionState(cwd);
+  const prompt = input.prompt || "";
+
+  state.promptCount++;
+
+  // Classify as substantial if > 50 chars and contains action words
+  const isSubstantial = prompt.length > 50 && /\b(implement|add|fix|build|create|refactor|review|ship|deploy|test|write|update|change|remove|migrate)\b/i.test(prompt);
+
+  if (isSubstantial) {
+    state.substantivePrompts++;
+  }
+
+  saveSessionState(cwd, state);
+
+  // If this is the 2nd+ substantial prompt without a route card, remind
+  if (isSubstantial && state.substantivePrompts >= 2 && !state.routeCardPresent) {
+    return {
+      addContext: "Note: This is a substantial task and no Role OS route card has been produced yet. Consider running /roleos-route to classify the task and choose the right team. A route card ensures the work is staffed correctly.",
+    };
+  }
+
+  return {};
+}
+
+/**
+ * PreToolUse hook logic.
+ * Checks tool usage against active role envelope.
+ *
+ * @param {object} input - { tool_name, tool_input, session_id, cwd }
+ * @returns {{ allow?: boolean, deny?: { reason: string }, addContext?: string }}
+ */
+export function onPreToolUse(input) {
+  const cwd = input.cwd || process.cwd();
+  const state = getSessionState(cwd);
+  const toolName = input.tool_name || "";
+
+  // Record tool usage
+  if (!state.toolsUsed.includes(toolName)) {
+    state.toolsUsed.push(toolName);
+    saveSessionState(cwd, state);
+  }
+
+  // Advisory: flag write tools without route card after substantial prompts
+  const writeTools = ["Bash", "Write", "Edit", "NotebookEdit"];
+  if (writeTools.includes(toolName) && !state.routeCardPresent && (state.substantivePrompts || 0) >= 2) {
+    return {
+      addContext: `Write tool "${toolName}" used without a route card. If this is substantial work, consider routing first.`,
+    };
+  }
+
+  // If a role is active, read-only tools are always fine
+  if (state.activeRole && state.activePack) {
+    const readOnlyTools = ["Read", "Glob", "Grep", "WebSearch", "WebFetch"];
+    if (readOnlyTools.includes(toolName)) {
+      return { allow: true };
+    }
+  }
+
+  return {};
+}
+
+/**
+ * SubagentStart hook logic.
+ * Injects role contract context into delegated agents.
+ *
+ * @param {object} input - { agent_id, agent_type, session_id, cwd }
+ * @returns {{ addContext?: string }}
+ */
+export function onSubagentStart(input) {
+  const cwd = input.cwd || process.cwd();
+  const state = getSessionState(cwd);
+
+  if (state.activeRole) {
+    return {
+      addContext: `This subagent is operating under Role OS. Active role: ${state.activeRole}. Pack: ${state.activePack || "free routing"}. Follow the role contract and produce structured handoffs.`,
+    };
+  }
+
+  return {};
+}
+
+/**
+ * Stop hook logic.
+ * Prevents false completion — warns if no route card or outcome exists.
+ *
+ * @param {object} input - { session_id, cwd, stop_reason }
+ * @returns {{ block?: { reason: string }, addContext?: string }}
+ */
+export function onStop(input) {
+  const cwd = input.cwd || process.cwd();
+  const state = getSessionState(cwd);
+
+  // Only enforce on sessions that had substantial work
+  if (state.substantivePrompts < 2) {
+    return {}; // Trivial session, let it end
+  }
+
+  const warnings = [];
+
+  if (!state.routeCardPresent) {
+    warnings.push("No route card was produced during this session.");
+  }
+
+  if (!state.outcomeRecorded) {
+    warnings.push("No outcome artifact was recorded.");
+  }
+
+  if (warnings.length > 0) {
+    return {
+      addContext: `Role OS session audit: ${warnings.join(" ")} Consider documenting the outcome before ending.`,
+    };
+  }
+
+  return {};
+}
+
+// ── Hook script file generators ───────────────────────────────────────────────
+
+/**
+ * Generate hook script files for .claude/hooks/.
+ * These are the actual scripts that settings.json points to.
+ *
+ * @param {string} cwd
+ * @returns {{ created: string[], skipped: string[] }}
+ */
+export function scaffoldHooks(cwd) {
+  const created = [];
+  const skipped = [];
+  const hooksDir = join(cwd, ".claude", "hooks");
+  mkdirSync(hooksDir, { recursive: true });
+
+  const scripts = {
+    "session-start.mjs": generateSessionStartScript(),
+    "prompt-submit.mjs": generatePromptSubmitScript(),
+    "pre-tool-use.mjs": generatePreToolUseScript(),
+    "subagent-start.mjs": generateSubagentStartScript(),
+    "stop.mjs": generateStopScript(),
+  };
+
+  for (const [name, content] of Object.entries(scripts)) {
+    const path = join(hooksDir, name);
+    if (!existsSync(path)) {
+      writeFileSync(path, content);
+      created.push(`.claude/hooks/${name}`);
+    } else {
+      skipped.push(`.claude/hooks/${name}`);
+    }
+  }
+
+  return { created, skipped };
+}
+
+function generateSessionStartScript() {
+  return `#!/usr/bin/env node
+// Role OS SessionStart hook — establishes session contract
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+const input = JSON.parse(readFileSync("/dev/stdin", "utf-8").toString() || "{}");
+const cwd = input.cwd || process.cwd();
+const stateDir = join(cwd, ".claude", "hooks");
+mkdirSync(stateDir, { recursive: true });
+
+const state = {
+  sessionId: input.session_id || \`session-\${Date.now()}\`,
+  startedAt: new Date().toISOString(),
+  routeCardPresent: false,
+  activeRole: null,
+  activePack: null,
+  toolsUsed: [],
+  promptCount: 0,
+  substantivePrompts: 0,
+  outcomeRecorded: false,
+};
+
+writeFileSync(join(stateDir, "session-state.json"), JSON.stringify(state, null, 2));
+
+const hasRoleOs = existsSync(join(cwd, ".claude", "agents"));
+if (hasRoleOs) {
+  console.log(JSON.stringify({
+    addContext: "Role OS is active. For non-trivial tasks, run /roleos-route first.",
+  }));
+}
+`;
+}
+
+function generatePromptSubmitScript() {
+  return `#!/usr/bin/env node
+// Role OS UserPromptSubmit hook — classify before improvising
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+const input = JSON.parse(readFileSync("/dev/stdin", "utf-8").toString() || "{}");
+const cwd = input.cwd || process.cwd();
+const statePath = join(cwd, ".claude", "hooks", "session-state.json");
+
+let state = {};
+if (existsSync(statePath)) {
+  try { state = JSON.parse(readFileSync(statePath, "utf-8")); } catch {}
+}
+
+const prompt = input.prompt || "";
+state.promptCount = (state.promptCount || 0) + 1;
+
+const isSubstantial = prompt.length > 50 &&
+  /\\b(implement|add|fix|build|create|refactor|review|ship|deploy|test|write|update|change|remove|migrate)\\b/i.test(prompt);
+
+if (isSubstantial) state.substantivePrompts = (state.substantivePrompts || 0) + 1;
+
+writeFileSync(statePath, JSON.stringify(state, null, 2));
+
+if (isSubstantial && (state.substantivePrompts || 0) >= 2 && !state.routeCardPresent) {
+  console.log(JSON.stringify({
+    addContext: "No Role OS route card yet. Consider /roleos-route to classify this task.",
+  }));
+}
+`;
+}
+
+function generatePreToolUseScript() {
+  return `#!/usr/bin/env node
+// Role OS PreToolUse hook — enforce role-specific tool law
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+const input = JSON.parse(readFileSync("/dev/stdin", "utf-8").toString() || "{}");
+const cwd = input.cwd || process.cwd();
+const statePath = join(cwd, ".claude", "hooks", "session-state.json");
+
+let state = {};
+if (existsSync(statePath)) {
+  try { state = JSON.parse(readFileSync(statePath, "utf-8")); } catch {}
+}
+
+const toolName = input.tool_name || "";
+if (!state.toolsUsed) state.toolsUsed = [];
+if (!state.toolsUsed.includes(toolName)) {
+  state.toolsUsed.push(toolName);
+  writeFileSync(statePath, JSON.stringify(state, null, 2));
+}
+
+// Advisory: flag write tools without route card
+const writeTools = ["Bash", "Write", "Edit", "NotebookEdit"];
+if (writeTools.includes(toolName) && !state.routeCardPresent && (state.substantivePrompts || 0) >= 2) {
+  console.log(JSON.stringify({
+    addContext: \`Write tool "\${toolName}" used without route card. Consider /roleos-route.\`,
+  }));
+}
+`;
+}
+
+function generateSubagentStartScript() {
+  return `#!/usr/bin/env node
+// Role OS SubagentStart hook — inject role contract
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+const input = JSON.parse(readFileSync("/dev/stdin", "utf-8").toString() || "{}");
+const cwd = input.cwd || process.cwd();
+const statePath = join(cwd, ".claude", "hooks", "session-state.json");
+
+let state = {};
+if (existsSync(statePath)) {
+  try { state = JSON.parse(readFileSync(statePath, "utf-8")); } catch {}
+}
+
+if (state.activeRole) {
+  console.log(JSON.stringify({
+    addContext: \`Role OS active. Role: \${state.activeRole}. Pack: \${state.activePack || "free routing"}. Follow role contract.\`,
+  }));
+}
+`;
+}
+
+function generateStopScript() {
+  return `#!/usr/bin/env node
+// Role OS Stop hook — prevent false completion
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+const input = JSON.parse(readFileSync("/dev/stdin", "utf-8").toString() || "{}");
+const cwd = input.cwd || process.cwd();
+const statePath = join(cwd, ".claude", "hooks", "session-state.json");
+
+let state = {};
+if (existsSync(statePath)) {
+  try { state = JSON.parse(readFileSync(statePath, "utf-8")); } catch {}
+}
+
+// Only enforce on sessions with substantial work
+if ((state.substantivePrompts || 0) < 2) process.exit(0);
+
+const warnings = [];
+if (!state.routeCardPresent) warnings.push("No route card produced.");
+if (!state.outcomeRecorded) warnings.push("No outcome artifact recorded.");
+
+if (warnings.length > 0) {
+  console.log(JSON.stringify({
+    addContext: \`Role OS audit: \${warnings.join(" ")} Consider documenting the outcome.\`,
+  }));
+}
+`;
+}

package/src/session.mjs

@@ -0,0 +1,395 @@
+/**
+ * Session Spine — Phase Q (v1.4.0)
+ *
+ * Makes Role-OS the session substrate, not just a package.
+ * Scaffolds CLAUDE.md instructions, skills, and hooks so that
+ * Claude Code enters every session through role-os routing.
+ *
+ * Extension points used:
+ * - CLAUDE.md: project instructions loaded at session start
+ * - .claude/commands/: slash commands (skills) invokable by user or auto-matched
+ * - Hooks: lifecycle events configured in settings
+ */
+
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { writeFileSafe } from "./fs-utils.mjs";
+import { scaffoldHooks, generateHooksConfig } from "./hooks.mjs";
+
+// ── roleos init claude ────────────────────────────────────────────────────────
+
+/**
+ * Scaffold Claude Code integration files into a repo.
+ * Creates: CLAUDE.md addition, /roleos-route command, and session guidance.
+ *
+ * @param {string} cwd - Working directory
+ * @param {object} [options]
+ * @param {boolean} [options.force] - Overwrite existing files
+ * @returns {{ created: string[], skipped: string[] }}
+ */
+export function scaffoldClaude(cwd, options = {}) {
+  const created = [];
+  const skipped = [];
+
+  // 1. CLAUDE.md — session entry instructions
+  const claudeMd = join(cwd, "CLAUDE.md");
+  const claudeContent = generateClaudeMd();
+  if (!existsSync(claudeMd) || options.force) {
+    writeFileSync(claudeMd, claudeContent);
+    created.push("CLAUDE.md");
+  } else {
+    // Append role-os section if not already present
+    const existing = readFileSync(claudeMd, "utf-8");
+    if (!existing.includes("## Role OS")) {
+      writeFileSync(claudeMd, existing + "\n\n" + claudeContent);
+      created.push("CLAUDE.md (appended)");
+    } else {
+      skipped.push("CLAUDE.md (Role OS section already present)");
+    }
+  }
+
+  // 2. Slash command: /roleos-route
+  const cmdDir = join(cwd, ".claude", "commands");
+  mkdirSync(cmdDir, { recursive: true });
+  const routeCmd = join(cmdDir, "roleos-route.md");
+  if (!existsSync(routeCmd) || options.force) {
+    writeFileSync(routeCmd, generateRouteCommand());
+    created.push(".claude/commands/roleos-route.md");
+  } else {
+    skipped.push(".claude/commands/roleos-route.md");
+  }
+
+  // 3. Slash command: /roleos-review
+  const reviewCmd = join(cmdDir, "roleos-review.md");
+  if (!existsSync(reviewCmd) || options.force) {
+    writeFileSync(reviewCmd, generateReviewCommand());
+    created.push(".claude/commands/roleos-review.md");
+  } else {
+    skipped.push(".claude/commands/roleos-review.md");
+  }
+
+  // 4. Slash command: /roleos-status
+  const statusCmd = join(cmdDir, "roleos-status.md");
+  if (!existsSync(statusCmd) || options.force) {
+    writeFileSync(statusCmd, generateStatusCommand());
+    created.push(".claude/commands/roleos-status.md");
+  } else {
+    skipped.push(".claude/commands/roleos-status.md");
+  }
+
+  // 5. Hook scripts
+  const hookResult = scaffoldHooks(cwd);
+  created.push(...hookResult.created);
+  skipped.push(...hookResult.skipped);
+
+  // 6. Settings.json with hooks config
+  const settingsPath = join(cwd, ".claude", "settings.local.json");
+  if (!existsSync(settingsPath) || options.force) {
+    const hooksConfig = generateHooksConfig();
+    writeFileSync(settingsPath, JSON.stringify(hooksConfig, null, 2));
+    created.push(".claude/settings.local.json");
+  } else {
+    // Check if hooks are already configured
+    try {
+      const existing = JSON.parse(readFileSync(settingsPath, "utf-8"));
+      if (!existing.hooks) {
+        const hooksConfig = generateHooksConfig();
+        existing.hooks = hooksConfig.hooks;
+        writeFileSync(settingsPath, JSON.stringify(existing, null, 2));
+        created.push(".claude/settings.local.json (hooks added)");
+      } else {
+        skipped.push(".claude/settings.local.json (hooks already configured)");
+      }
+    } catch {
+      skipped.push(".claude/settings.local.json (could not parse existing)");
+    }
+  }
+
+  return { created, skipped };
+}
+
+// ── roleos doctor ─────────────────────────────────────────────────────────────
+
+/**
+ * @typedef {Object} DoctorCheck
+ * @property {string} name
+ * @property {"pass"|"fail"|"warn"} status
+ * @property {string} detail
+ */
+
+/**
+ * Verify that a repo is correctly wired for Role-OS session integration.
+ *
+ * @param {string} cwd
+ * @returns {{ checks: DoctorCheck[], healthy: boolean }}
+ */
+export function doctor(cwd) {
+  const checks = [];
+
+  // Check 1: .claude/ directory exists
+  const claudeDir = join(cwd, ".claude");
+  checks.push({
+    name: ".claude/ directory",
+    status: existsSync(claudeDir) ? "pass" : "fail",
+    detail: existsSync(claudeDir) ? "exists" : "missing — run roleos init first",
+  });
+
+  // Check 2: CLAUDE.md exists and has Role OS section
+  const claudeMd = join(cwd, "CLAUDE.md");
+  if (existsSync(claudeMd)) {
+    const content = readFileSync(claudeMd, "utf-8");
+    if (content.includes("## Role OS")) {
+      checks.push({ name: "CLAUDE.md Role OS section", status: "pass", detail: "present" });
+    } else {
+      checks.push({ name: "CLAUDE.md Role OS section", status: "warn", detail: "CLAUDE.md exists but has no Role OS section — run roleos init claude" });
+    }
+  } else {
+    checks.push({ name: "CLAUDE.md", status: "fail", detail: "missing — run roleos init claude" });
+  }
+
+  // Check 3: /roleos-route command exists
+  const routeCmd = join(cwd, ".claude", "commands", "roleos-route.md");
+  checks.push({
+    name: "/roleos-route command",
+    status: existsSync(routeCmd) ? "pass" : "fail",
+    detail: existsSync(routeCmd) ? "exists" : "missing — run roleos init claude",
+  });
+
+  // Check 4: Context files exist
+  const contextDir = join(cwd, ".claude", "context");
+  const contextFiles = ["product-brief.md", "repo-map.md", "brand-rules.md", "current-priorities.md"];
+  const filledContext = contextFiles.filter(f => {
+    const path = join(contextDir, f);
+    if (!existsSync(path)) return false;
+    const content = readFileSync(path, "utf-8");
+    // Check if it's still a template (all comments, no real content)
+    const lines = content.split("\n").filter(l => l.trim() && !l.trim().startsWith("#") && !l.trim().startsWith("<!--") && !l.trim().startsWith("//"));
+    return lines.length > 2;
+  });
+
+  if (filledContext.length === 4) {
+    checks.push({ name: "context files", status: "pass", detail: "all 4 filled" });
+  } else if (filledContext.length > 0) {
+    checks.push({ name: "context files", status: "warn", detail: `${filledContext.length}/4 filled — empty context reduces routing quality` });
+  } else {
+    checks.push({ name: "context files", status: "fail", detail: "no context files filled — routing will be low-confidence" });
+  }
+
+  // Check 5: Role contracts exist
+  const agentsDir = join(cwd, ".claude", "agents");
+  if (existsSync(agentsDir)) {
+    checks.push({ name: "role contracts", status: "pass", detail: "agents/ directory exists" });
+  } else {
+    checks.push({ name: "role contracts", status: "fail", detail: "no agents/ directory — run roleos init first" });
+  }
+
+  // Check 6: Packets directory exists
+  const packetsDir = join(cwd, ".claude", "packets");
+  checks.push({
+    name: "packets directory",
+    status: existsSync(packetsDir) ? "pass" : "warn",
+    detail: existsSync(packetsDir) ? "exists" : "no packets yet — run roleos packet new",
+  });
+
+  // Check 7: Hook scripts exist
+  const hooksDir = join(cwd, ".claude", "hooks");
+  const hookFiles = ["session-start.mjs", "prompt-submit.mjs", "pre-tool-use.mjs", "subagent-start.mjs", "stop.mjs"];
+  const existingHooks = hookFiles.filter(f => existsSync(join(hooksDir, f)));
+  if (existingHooks.length === hookFiles.length) {
+    checks.push({ name: "hook scripts", status: "pass", detail: `all ${hookFiles.length} hooks present` });
+  } else if (existingHooks.length > 0) {
+    checks.push({ name: "hook scripts", status: "warn", detail: `${existingHooks.length}/${hookFiles.length} hooks present` });
+  } else {
+    checks.push({ name: "hook scripts", status: "warn", detail: "no hooks — run roleos init claude for runtime enforcement" });
+  }
+
+  // Check 8: Settings has hooks configured
+  const settingsPath = join(cwd, ".claude", "settings.local.json");
+  if (existsSync(settingsPath)) {
+    try {
+      const settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
+      if (settings.hooks) {
+        checks.push({ name: "hooks in settings", status: "pass", detail: "configured" });
+      } else {
+        checks.push({ name: "hooks in settings", status: "warn", detail: "settings.local.json exists but no hooks section" });
+      }
+    } catch {
+      checks.push({ name: "hooks in settings", status: "warn", detail: "settings.local.json exists but could not parse" });
+    }
+  } else {
+    checks.push({ name: "hooks in settings", status: "warn", detail: "no settings.local.json — hooks not active" });
+  }
+
+  const healthy = checks.every(c => c.status !== "fail");
+
+  return { checks, healthy };
+}
+
+// ── Route card ────────────────────────────────────────────────────────────────
+
+/**
+ * Generate a route card — the session header artifact that proves
+ * role-os was engaged.
+ *
+ * @param {object} routeResult
+ * @returns {string} Markdown route card
+ */
+export function generateRouteCard(routeResult) {
+  const lines = [
+    `## Route Card`,
+    ``,
+    `| Field | Value |`,
+    `|-------|-------|`,
+    `| Task type | ${routeResult.type || "unknown"} |`,
+    `| Pack | ${routeResult.pack || "free routing"} |`,
+    `| Pack confidence | ${routeResult.packConfidence || "n/a"} |`,
+    `| Composite | ${routeResult.isComposite ? "yes — " + routeResult.compositeReason : "no"} |`,
+    `| Chain | ${routeResult.chain || "pending"} |`,
+    `| Confidence | ${routeResult.confidence || "unknown"} |`,
+    `| Routed at | ${new Date().toISOString()} |`,
+  ];
+
+  if (routeResult.mismatch) {
+    lines.push(`| Mismatch | ${routeResult.mismatch} |`);
+  }
+
+  lines.push(``);
+  lines.push(`**Why:** ${routeResult.reason || "Scored against packet content."}`);
+
+  if (routeResult.successArtifact) {
+    lines.push(``);
+    lines.push(`**Success artifact:** ${routeResult.successArtifact}`);
+  }
+
+  return lines.join("\n");
+}
+
+// ── Format doctor output ──────────────────────────────────────────────────────
+
+/**
+ * @param {{ checks: DoctorCheck[], healthy: boolean }} result
+ * @returns {string}
+ */
+export function formatDoctor(result) {
+  const lines = [
+    `\nRole OS Doctor`,
+    `──────────────`,
+  ];
+
+  for (const check of result.checks) {
+    const icon = check.status === "pass" ? "✓" : check.status === "warn" ? "!" : "✗";
+    lines.push(`  ${icon} ${check.name}: ${check.detail}`);
+  }
+
+  lines.push(``);
+  lines.push(result.healthy
+    ? `Healthy — Role OS is wired correctly.`
+    : `Unhealthy — run roleos init claude to fix.`
+  );
+
+  return lines.join("\n");
+}
+
+// ── Generators ────────────────────────────────────────────────────────────────
+
+function generateClaudeMd() {
+  return `## Role OS
+
+Before starting non-trivial work in this repo, route the task through Role OS:
+
+1. Run \`/roleos-route\` or \`roleos route <packet-file>\` to classify the task
+2. Follow the recommended pack or role chain
+3. Use structured handoffs between roles
+4. Review with evidence-based verdicts
+
+Role OS provides 31 specialized roles across 8 packs (engineering, design, product, research, growth, treatment, marketing, core). It detects broken chains, auto-routes recovery, and requires structured evidence in every verdict.
+
+If the task is composite (feature + docs + launch), Role OS will recommend splitting into child packets with dependency ordering.
+
+**Route card required:** Every substantial task should produce a route card at the start showing task type, chosen pack/role, confidence, and expected success artifact. If no route card exists, Role OS was not engaged.
+`;
+}
+
+function generateRouteCommand() {
+  return `# Route Task Through Role OS
+
+Classify the current task and recommend the right team.
+
+## Steps
+
+1. Read the task description or packet file
+2. Run \`roleos route\` against it (or reason through the routing logic)
+3. Emit a **route card** with:
+   - Task type (feature / bugfix / docs / research / security / launch / treatment)
+   - Recommended pack or free-routing chain
+   - Why this pack/chain was chosen
+   - Whether the task is composite (needs splitting)
+   - Expected success artifact
+   - Confidence level
+
+## Route card format
+
+\`\`\`
+## Route Card
+
+| Field | Value |
+|-------|-------|
+| Task type | feature |
+| Pack | feature (high confidence) |
+| Composite | no |
+| Chain | Product Strategist → Spec Writer → Backend Engineer → Test Engineer → Critic Reviewer |
+| Confidence | high |
+
+**Why:** Packet contains implementation scope with clear deliverable type.
+**Success artifact:** Working implementation with tests and Critic verdict.
+\`\`\`
+
+## Rules
+- If confidence is low, say so — do not force a pack
+- If composite, recommend splitting before execution
+- If the task is trivial (< 3 steps), skip routing and just do it
+- The route card is the proof Role OS was engaged
+`;
+}
+
+function generateReviewCommand() {
+  return `# Review Work Through Role OS
+
+Review the completed work using Role OS structured verdict.
+
+## Steps
+
+1. Identify which role should review (usually Critic Reviewer)
+2. Check the work against the original packet's done definition
+3. Produce a structured verdict:
+   - **Verdict:** accept / accept-with-notes / reject / blocked
+   - **Evidence:** specific items supporting the verdict
+   - **Gaps:** what's missing, if anything
+   - **Next owner:** who receives this next
+
+## Rules
+- Tie every verdict to specific evidence, not impressions
+- If evidence is insufficient to judge, say so
+- Reject honestly — do not approve weak work to be nice
+- For reject/blocked: state what must change and who should do it
+`;
+}
+
+function generateStatusCommand() {
+  return `# Role OS Status
+
+Check the current state of Role OS work in this repo.
+
+## Steps
+
+1. Run \`roleos status\` to see active packets, verdicts, and context health
+2. Report:
+   - Active/blocked/completed packets
+   - Recent verdicts
+   - Context file health
+   - Any conflicts or escalations
+
+## If no packets exist
+Role OS has not been engaged in this session. Consider running \`/roleos-route\` first.
+`;
+}