role-os 2.2.0 → 2.2.1

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 2.2.1
+
+### Added
+- **`roleos audit` CLI** — first-class entry point for deep audit with subcommands: `audit`, `audit manifest`, `audit manifest --generate`, `audit status`, `audit verify`
+- **Shared state machine** (`src/state-machine.mjs`) — canonical step/run transitions shared by both runners
+- **Shared tool profiles** (`src/tool-profiles.mjs`) — extracted from dispatch.mjs to break trial→dispatch coupling
+
+### Fixed
+- **P3-1:** Cycle detection in composite execution (`detectCycles` + visited-set guard in `findUnreachable`)
+- **P3-2:** Dual-active guard in `startNext`/`startNextStep` prevents two steps active simultaneously
+- **P3-3:** Atomic persistence — `saveRun` writes to temp file then renames
+- **P4-1:** Dependency Auditor has own artifact contract (`dependency-audit`), pack handoff corrected
+- **P4-2:** `partitionBrief` returns topic-only for unknown roles instead of full brief
+- **P4-3:** Atom kind normalization layer bridges scout `.kind` and atom `.claim_kind`
+- **P4-4:** `/dev/stdin` → `readFileSync(0)` for Windows compatibility in all 5 hooks
+- **P4-5:** TOOL_PROFILES extracted to shared module, eliminating trial→dispatch coupling
+- Node 18 compatibility fix for `import.meta.dirname` in deep-audit-proof test
+
+### Tests
+- 18 new tests (audit-cmd, audit-p5, deep-audit-proof) — total: 954
+
 ## 2.2.0
 
 ### Added

package/README.md

@@ -134,6 +134,12 @@ roleos complete artifact.md    # Complete with artifact
 roleos explain                 # Show full state
 roleos report                  # Completion report
 
+# Deep audit:
+roleos audit manifest --generate   # Create audit-manifest.json
+roleos audit                       # Start component-level deep audit
+roleos audit status                # Check audit progress
+roleos audit verify                # Verify manifest and outputs
+
 # Or go manual:
 roleos start "fix the crash"   # Entry decision only (no run)
 roleos packet new feature
@@ -207,18 +213,21 @@ role-os/
     entry-cmd.mjs              ← `roleos start` CLI command
     run.mjs                    ← Persistent run engine: create → step → pause → resume → report
     run-cmd.mjs                ← `roleos run/resume/next/explain/complete/fail` + interventions
-    mission.mjs                ← 7 named mission types (feature, bugfix, treatment, docs, security, research, brainstorm)
+    mission.mjs                ← 8 named mission types (feature, bugfix, treatment, docs, security, research, brainstorm, deep-audit)
     mission-run.mjs            ← Mission runner: create → step → complete → report
     mission-cmd.mjs            ← `roleos mission` CLI commands
+    audit-cmd.mjs              ← `roleos audit` — deep audit entry point with manifest generation
     route.mjs                  ← 54-role routing + dynamic chain builder
     packs.mjs                  ← 9 calibrated team packs + auto-selection
     conflicts.mjs              ← 4-pass conflict detection
     escalation.mjs             ← Auto-routing for blocked/rejected/split
     evidence.mjs               ← Structured evidence + role-aware requirements
     dispatch.mjs               ← Runtime dispatch manifests for multi-claude
+    tool-profiles.mjs          ← Per-role tool sandboxing (shared by dispatch + trial)
+    state-machine.mjs          ← Canonical step/run transition maps
     artifacts.mjs              ← Per-role artifact contracts + pack handoffs
     decompose.mjs              ← Composite task detection + splitting
-    composite.mjs              ← Dependency-ordered execution + recovery
+    composite.mjs              ← Dependency-ordered execution + recovery + cycle detection
     replan.mjs                 ← Mid-run adaptive replanning
     calibration.mjs            ← Outcome recording + weight tuning
     hooks.mjs                  ← 5 lifecycle hooks for runtime enforcement
@@ -226,7 +235,7 @@ role-os/
     brainstorm.mjs             ← Evidence modes, request validation, finding/synthesis/judge schemas
     brainstorm-roles.mjs       ← Role-native schemas, input partitioning, blindspot enforcement, cross-exam
     brainstorm-render.mjs      ← Two-layer rendering: lexical bans, render schemas, debate transcript
-  test/                        ← 936 tests across 31 test files
+  test/                        ← 954 tests across 33 test files
   starter-pack/                ← Drop-in role contracts, policies, schemas, workflows
 ```
 

package/bin/roleos.mjs

@@ -12,6 +12,7 @@ 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 { auditCommand } from "../src/audit-cmd.mjs";
 import { startCommand } from "../src/entry-cmd.mjs";
 import {
   runCommand, resumeCommand, nextCommand, explainCommand,
@@ -59,6 +60,11 @@ Usage:
   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 audit                        Start a deep audit on the current repo
+  roleos audit manifest               Show the audit manifest
+  roleos audit manifest --generate    Generate a skeleton manifest from src/
+  roleos audit status                 Show audit run progress
+  roleos audit verify                 Verify manifest and audit outputs
   roleos mission list                List all missions
   roleos mission show <key>          Show full mission detail
   roleos mission suggest <text>      Suggest a mission for a task
@@ -181,6 +187,9 @@ try {
     case "friction":
       await frictionCommand(args);
       break;
+    case "audit":
+      await auditCommand(args);
+      break;
     case "mission":
       await missionCommand(args);
       break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "role-os",
-  "version": "2.2.0",
+  "version": "2.2.1",
   "description": "Role OS — a multi-Claude operating system where 54 specialized roles execute work through contracts, conflict detection, escalation, and structured evidence. 9 team packs, 8 missions including deep audit with manifest-scaled dynamic dispatch and brainstorm with traceable disagreement.",
   "homepage": "https://mcp-tool-shop-org.github.io/role-os/",
   "bugs": {

package/src/artifacts.mjs

@@ -106,6 +106,14 @@ export const ROLE_ARTIFACT_CONTRACTS = {
     consumedBy: ["Backend Engineer", "Coverage Auditor", "Security Reviewer"],
     completionRule: "Entrypoints listed. Module responsibilities described. Commands documented.",
   },
+  "Dependency Auditor": {
+    artifactType: "dependency-audit",
+    requiredSections: ["vulnerability-summary", "outdated-inventory"],
+    optionalSections: ["supply-chain-risks", "update-recommendations", "license-audit"],
+    requiredEvidence: [],
+    consumedBy: ["Critic Reviewer", "Security Reviewer"],
+    completionRule: "Vulnerabilities triaged. Outdated deps inventoried with severity.",
+  },
   "Metadata Curator": {
     artifactType: "metadata-audit",
     requiredSections: ["manifest-audit", "registry-alignment"],
@@ -380,7 +388,7 @@ export const PACK_HANDOFF_CONTRACTS = {
   security: {
     flow: [
       { role: "Security Reviewer", produces: "security-findings", consumedBy: "Critic Reviewer" },
-      { role: "Dependency Auditor", produces: "metadata-audit", consumedBy: "Critic Reviewer" },
+      { role: "Dependency Auditor", produces: "dependency-audit", consumedBy: "Critic Reviewer" },
       { role: "Critic Reviewer", produces: "verdict", consumedBy: null },
     ],
   },

package/src/audit-cmd.mjs

@@ -0,0 +1,401 @@
+/**
+ * Audit CLI — Deep Audit entry point.
+ *
+ * roleos audit                       Run deep audit on current repo
+ * roleos audit manifest              Show or generate the audit manifest
+ * roleos audit status                Show audit run progress
+ * roleos audit verify                Re-verify findings against current code
+ *
+ * This is a first-class shortcut into the deep-audit mission.
+ * Under the hood it creates a mission run with dynamic dispatch.
+ */
+
+import { existsSync, readFileSync, writeFileSync, readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { getMission, suggestMission } from "./mission.mjs";
+import {
+  createRun,
+  startNextStep,
+  getRunPosition,
+  getArtifactChain,
+  generateCompletionReport,
+  formatCompletionReport,
+} from "./mission-run.mjs";
+import {
+  createPersistentRun, findActiveRun, listRuns, loadRun,
+  startNext, explainRun, getPosition, saveRun,
+} from "./run.mjs";
+
+// ── Constants ────────────────────────────────────────────────────────────────
+
+const MANIFEST_FILE = "audit-manifest.json";
+
+// ── Main dispatch ────────────────────────────────────────────────────────────
+
+/**
+ * @param {string[]} args
+ */
+export async function auditCommand(args) {
+  const sub = args[0] || "run";
+
+  switch (sub) {
+    case "run":
+    case "start":
+      return cmdRun(args.slice(1));
+    case "manifest":
+      return cmdManifest(args.slice(1));
+    case "status":
+      return cmdStatus();
+    case "verify":
+      return cmdVerify();
+    case "help":
+      return cmdHelp();
+    default:
+      // If the first arg isn't a subcommand, treat everything as a task description
+      if (!["run", "start", "manifest", "status", "verify", "help"].includes(sub)) {
+        return cmdRun(args);
+      }
+      cmdHelp();
+  }
+}
+
+// ── roleos audit [run] ───────────────────────────────────────────────────────
+
+function cmdRun(extraArgs) {
+  const cwd = process.cwd();
+  const manifestPath = join(cwd, MANIFEST_FILE);
+
+  // Check if manifest exists
+  if (!existsSync(manifestPath)) {
+    console.log("\nNo audit-manifest.json found in current directory.");
+    console.log("Generate one first with: roleos audit manifest --generate\n");
+    console.log("The manifest defines your repo's components and boundaries.");
+    console.log("Deep audit uses it to dispatch one auditor per component.\n");
+    process.exit(1);
+  }
+
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+
+  // Validate manifest shape
+  const issues = validateManifest(manifest);
+  if (issues.length > 0) {
+    console.log("\nAudit manifest has issues:\n");
+    for (const issue of issues) {
+      console.log(`  - ${issue}`);
+    }
+    console.log("\nFix the manifest and re-run.\n");
+    process.exit(1);
+  }
+
+  const taskDesc = extraArgs.length > 0
+    ? extraArgs.join(" ")
+    : `Deep audit of ${manifest.repo || "current repo"}`;
+
+  // Create a persistent run via the deep-audit mission
+  const run = createPersistentRun(taskDesc, cwd, { forceMission: "deep-audit" });
+
+  console.log(`\nDeep Audit Started`);
+  console.log(`──────────────────`);
+  console.log(`Run:        ${run.id}`);
+  console.log(`Repo:       ${manifest.repo || "unknown"}`);
+  console.log(`Components: ${manifest.components?.length || 0}`);
+  console.log(`Boundaries: ${manifest.boundaries?.length || 0}`);
+  console.log(`Steps:      ${run.steps.length}`);
+  console.log(`\nThe audit will dispatch:`);
+  console.log(`  - Component Auditor  ×${manifest.components?.length || 0}`);
+  console.log(`  - Test Truth Auditor ×${manifest.components?.length || 0}`);
+  console.log(`  - Seam Auditor       ×${manifest.boundaries?.length || 0}`);
+  console.log(`  - Audit Synthesizer  ×1`);
+  console.log(`  - Critic Reviewer    ×1`);
+  console.log(`\nRun 'roleos next' to begin the first step.`);
+  console.log(`Run 'roleos audit status' to check progress.\n`);
+}
+
+// ── roleos audit manifest ────────────────────────────────────────────────────
+
+function cmdManifest(args) {
+  const cwd = process.cwd();
+  const manifestPath = join(cwd, MANIFEST_FILE);
+
+  if (args.includes("--generate") || args.includes("-g")) {
+    return generateManifest(cwd, manifestPath);
+  }
+
+  if (!existsSync(manifestPath)) {
+    console.log("\nNo audit-manifest.json found.");
+    console.log("Run 'roleos audit manifest --generate' to create one.\n");
+    return;
+  }
+
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+  const issues = validateManifest(manifest);
+
+  console.log(`\nAudit Manifest: ${manifest.repo || "unknown"}`);
+  console.log(`──────────────────────────────────────────`);
+  console.log(`Version:    ${manifest.version || "unknown"}`);
+  console.log(`Language:   ${manifest.language || "unknown"}`);
+  console.log(`Source:     ${manifest.total_source_lines || "?"} lines`);
+  console.log(`Tests:      ${manifest.total_test_lines || "?"} lines`);
+  console.log(`Components: ${manifest.components?.length || 0}`);
+  console.log(`Boundaries: ${manifest.boundaries?.length || 0}`);
+
+  if (manifest.components?.length > 0) {
+    console.log(`\nComponents:`);
+    for (const c of manifest.components) {
+      const paths = c.owned_paths?.length || 0;
+      console.log(`  - ${c.id}: ${c.description || ""} (${paths} paths)`);
+    }
+  }
+
+  if (manifest.boundaries?.length > 0) {
+    console.log(`\nBoundaries:`);
+    for (const b of manifest.boundaries) {
+      const label = b.id || `${b.from} → ${b.to}`;
+      console.log(`  - ${label}: ${b.contract || b.description || ""}`);
+    }
+  }
+
+  if (issues.length > 0) {
+    console.log(`\nIssues:`);
+    for (const issue of issues) {
+      console.log(`  ! ${issue}`);
+    }
+  } else {
+    console.log(`\nManifest is valid.`);
+  }
+
+  console.log("");
+}
+
+function generateManifest(cwd, manifestPath) {
+  if (existsSync(manifestPath)) {
+    console.log(`\nManifest already exists at ${MANIFEST_FILE}.`);
+    console.log("Edit it manually or delete it to regenerate.\n");
+    return;
+  }
+
+  // Build a skeleton manifest by scanning src/
+  const srcDir = join(cwd, "src");
+  const components = [];
+
+  if (existsSync(srcDir)) {
+    const files = readdirSync(srcDir).filter(f => f.endsWith(".mjs") || f.endsWith(".js") || f.endsWith(".ts"));
+    // Group by common prefix
+    const seen = new Set();
+    for (const f of files) {
+      const base = f.replace(/(-cmd)?\.m?[jt]s$/, "");
+      if (seen.has(base)) continue;
+      seen.add(base);
+
+      const paths = files.filter(ff => ff.startsWith(base)).map(ff => `src/${ff}`);
+      components.push({
+        id: base,
+        description: `TODO: describe ${base}`,
+        owned_paths: paths,
+        forbidden_paths: [],
+        upstream_deps: [],
+        downstream_consumers: [],
+        public_interfaces: [],
+      });
+    }
+  }
+
+  const manifest = {
+    repo: "TODO: org/repo-name",
+    version: "0.0.0",
+    timestamp: new Date().toISOString(),
+    language: "TODO",
+    runtime: "TODO",
+    total_source_lines: 0,
+    total_test_lines: 0,
+    external_dependencies: 0,
+    components,
+    boundaries: [],
+  };
+
+  writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+  console.log(`\nGenerated skeleton ${MANIFEST_FILE} with ${components.length} components.`);
+  console.log("Edit the manifest to:");
+  console.log("  1. Fill in repo, version, language, runtime");
+  console.log("  2. Write real descriptions for each component");
+  console.log("  3. Define boundaries between components");
+  console.log("  4. Set upstream_deps and downstream_consumers");
+  console.log(`\nThen run 'roleos audit' to start the audit.\n`);
+}
+
+// ── roleos audit status ──────────────────────────────────────────────────────
+
+function cmdStatus() {
+  const cwd = process.cwd();
+
+  // Find the most recent deep-audit run
+  const runs = listRuns(cwd);
+  const auditRuns = runs.filter(r =>
+    r.task.toLowerCase().includes("audit") ||
+    r.level === "mission"
+  );
+
+  if (auditRuns.length === 0) {
+    console.log("\nNo audit runs found. Start one with: roleos audit\n");
+    return;
+  }
+
+  // Show the most recent
+  const latest = auditRuns[0];
+  console.log(`\nLatest Audit Run`);
+  console.log(`────────────────`);
+  console.log(`ID:      ${latest.id}`);
+  console.log(`Task:    ${latest.task}`);
+  console.log(`Status:  ${latest.status.toUpperCase()}`);
+  console.log(`Created: ${latest.createdAt}`);
+
+  const full = loadRun(cwd, latest.id);
+  if (full) {
+    const pos = getPosition(full);
+    console.log(`Progress: ${pos.progress}`);
+
+    const byStatus = {};
+    for (const s of full.steps) {
+      byStatus[s.status] = (byStatus[s.status] || 0) + 1;
+    }
+    console.log(`\nSteps:`);
+    for (const [status, count] of Object.entries(byStatus)) {
+      const icon = status === "completed" ? "[x]" :
+                   status === "active"    ? "[>]" :
+                   status === "failed"    ? "[!]" :
+                   status === "blocked"   ? "[-]" : "[ ]";
+      console.log(`  ${icon} ${status}: ${count}`);
+    }
+  }
+
+  console.log(`\nRun 'roleos explain ${latest.id}' for full detail.\n`);
+}
+
+// ── roleos audit verify ──────────────────────────────────────────────────────
+
+function cmdVerify() {
+  const cwd = process.cwd();
+  const manifestPath = join(cwd, MANIFEST_FILE);
+
+  if (!existsSync(manifestPath)) {
+    console.log("\nNo audit-manifest.json found. Nothing to verify.\n");
+    process.exit(1);
+  }
+
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+  const issues = validateManifest(manifest);
+
+  console.log(`\nAudit Verification`);
+  console.log(`──────────────────`);
+
+  // 1. Manifest valid
+  if (issues.length === 0) {
+    console.log(`  [PASS] Manifest is valid`);
+  } else {
+    console.log(`  [FAIL] Manifest has ${issues.length} issue(s)`);
+    for (const i of issues) console.log(`         - ${i}`);
+  }
+
+  // 2. Owned paths exist
+  let pathsOk = 0;
+  let pathsMissing = 0;
+  for (const c of manifest.components || []) {
+    for (const p of c.owned_paths || []) {
+      if (existsSync(join(cwd, p))) {
+        pathsOk++;
+      } else {
+        pathsMissing++;
+        if (pathsMissing <= 5) {
+          console.log(`  [WARN] Missing path: ${p} (${c.id})`);
+        }
+      }
+    }
+  }
+  if (pathsMissing === 0) {
+    console.log(`  [PASS] All ${pathsOk} owned paths exist`);
+  } else {
+    console.log(`  [WARN] ${pathsMissing} owned path(s) missing (${pathsOk} ok)`);
+  }
+
+  // 3. Check for audit output files
+  const auditFiles = ["AUDIT-SUMMARY.md", "AUDIT-ACTION-PLAN.md", "AUDIT-CRITIC-VERDICT.md"];
+  const existing = auditFiles.filter(f => existsSync(join(cwd, f)));
+  if (existing.length === auditFiles.length) {
+    console.log(`  [PASS] All audit output files present (${existing.length}/${auditFiles.length})`);
+  } else if (existing.length > 0) {
+    console.log(`  [WARN] Partial audit outputs (${existing.length}/${auditFiles.length})`);
+    const missing = auditFiles.filter(f => !existsSync(join(cwd, f)));
+    for (const f of missing) console.log(`         missing: ${f}`);
+  } else {
+    console.log(`  [INFO] No audit outputs yet — run 'roleos audit' first`);
+  }
+
+  // 4. Check parcel reports
+  const parcelFiles = readdirSync(cwd).filter(f => f.startsWith("AUDIT-PARCEL-"));
+  if (parcelFiles.length > 0) {
+    console.log(`  [PASS] ${parcelFiles.length} parcel report(s) found`);
+  } else {
+    console.log(`  [INFO] No parcel reports yet`);
+  }
+
+  const healthy = issues.length === 0 && pathsMissing === 0;
+  console.log(`\n${healthy ? "Audit infrastructure verified." : "Some issues found — fix before re-auditing."}\n`);
+  if (!healthy) process.exit(1);
+}
+
+// ── Help ─────────────────────────────────────────────────────────────────────
+
+function cmdHelp() {
+  console.log(`
+roleos audit — Deep Audit CLI
+
+Usage:
+  roleos audit                        Start a deep audit on the current repo
+  roleos audit manifest               Show the audit manifest
+  roleos audit manifest --generate    Generate a skeleton manifest from src/
+  roleos audit status                 Show audit run progress
+  roleos audit verify                 Verify manifest and audit outputs
+  roleos audit help                   Show this help
+
+The deep audit decomposes a repo into bounded components, dispatches one
+auditor per component, inspects seams between components, checks test truth,
+then synthesizes into a ranked action plan.
+
+Workflow:
+  1. roleos audit manifest --generate    Create audit-manifest.json
+  2. Edit the manifest                   Define components and boundaries
+  3. roleos audit                        Start the audit run
+  4. roleos next                         Step through each auditor
+  5. roleos audit status                 Check progress
+  6. roleos audit verify                 Verify everything landed
+`);
+}
+
+// ── Manifest validation ──────────────────────────────────────────────────────
+
+function validateManifest(manifest) {
+  const issues = [];
+
+  if (!manifest.components || !Array.isArray(manifest.components)) {
+    issues.push("components must be an array");
+  } else {
+    if (manifest.components.length === 0) {
+      issues.push("components array is empty — add at least one component");
+    }
+    for (let i = 0; i < manifest.components.length; i++) {
+      const c = manifest.components[i];
+      if (!c.id) issues.push(`components[${i}] missing id`);
+      if (!c.owned_paths || c.owned_paths.length === 0) {
+        issues.push(`components[${i}] (${c.id || "?"}) has no owned_paths`);
+      }
+    }
+  }
+
+  if (!manifest.boundaries || !Array.isArray(manifest.boundaries)) {
+    issues.push("boundaries must be an array");
+  }
+
+  return issues;
+}
+
+export { validateManifest };

package/src/brainstorm-roles.mjs

@@ -139,7 +139,10 @@ export const INPUT_PARTITIONS = {
  */
 export function partitionBrief(request, roleName) {
   const partition = INPUT_PARTITIONS[roleName];
-  if (!partition) return request; // Unknown role gets full brief (fallback)
+  if (!partition) {
+    // Unknown roles receive only the topic — minimal brief, not full access
+    return request.topic !== undefined ? { topic: request.topic } : {};
+  }
 
   const filtered = {};
   for (const field of partition.permitted) {
@@ -702,6 +705,46 @@ export function translateToAtoms(roleName, roleOutput) {
   return atoms;
 }
 
+/**
+ * Map from specific claim_kind (atom layer) to broad statement kind (scout layer).
+ * This bridges the two naming conventions:
+ *   - Scout findings use `.kind` ∈ {"claim", "opportunity", "risk", "tension", "unknown"}
+ *   - Translated atoms use `.claim_kind` with specific types per role
+ */
+export const CLAIM_KIND_TO_STATEMENT_KIND = {
+  // Context Analyst → claim
+  definition: "claim", category: "claim", lineage: "claim", boundary: "claim",
+  // User Value Analyst → opportunity or claim
+  need: "opportunity", desire: "opportunity", friction: "risk", willingness: "claim",
+  // Mechanics Analyst → claim or risk
+  loop: "claim", dependency: "claim", failure_mode: "risk", mechanism: "claim",
+  // Positioning Analyst → opportunity
+  substitute: "tension", wedge: "opportunity", category_frame: "claim",
+  positioning: "claim", timing: "opportunity",
+  // Contrarian Analyst → tension
+  challenge: "tension", contradiction: "tension", overstatement: "tension", gap: "risk",
+  // Normalizer
+  adjacency: "claim", avoidance: "risk", constraint: "claim",
+};
+
+/**
+ * Normalize an atom to include both `.claim_kind` (specific) and `.kind` (broad).
+ * Ensures atoms are compatible with both the scout validation layer and
+ * the cross-examination layer.
+ *
+ * @param {object} atom - Atom with claim_kind
+ * @returns {object} Atom with both claim_kind and kind fields
+ */
+export function normalizeAtomKind(atom) {
+  if (atom.kind && !atom.claim_kind) {
+    return { ...atom, claim_kind: atom.kind };
+  }
+  if (atom.claim_kind && !atom.kind) {
+    return { ...atom, kind: CLAIM_KIND_TO_STATEMENT_KIND[atom.claim_kind] || "unknown" };
+  }
+  return atom;
+}
+
 /**
  * Validate that a translated atom preserves all required provenance fields.
  *

package/src/composite.mjs

@@ -308,14 +308,20 @@ export function failChild(exec, category, reason) {
 
 /**
  * Find all categories that transitively depend on a given category.
+ * Uses a visited set to guard against circular dependency graphs.
  */
 function findUnreachable(exec, failedCategory) {
   const unreachable = new Set();
+  const visited = new Set();
   let changed = true;
   while (changed) {
     changed = false;
     for (const child of exec.children) {
       if (unreachable.has(child.category)) continue;
+      if (visited.has(child.category) && !child.dependsOn.includes(failedCategory) && !child.dependsOn.some(d => unreachable.has(d))) {
+        continue; // already evaluated without being unreachable — skip
+      }
+      visited.add(child.category);
       if (child.dependsOn.includes(failedCategory) || child.dependsOn.some(d => unreachable.has(d))) {
         unreachable.add(child.category);
         changed = true;
@@ -325,6 +331,41 @@ function findUnreachable(exec, failedCategory) {
   return [...unreachable];
 }
 
+/**
+ * Check for circular dependencies in the execution plan.
+ * Returns an array of categories involved in cycles (empty if none).
+ *
+ * @param {CompositeExecution} exec
+ * @returns {string[]}
+ */
+export function detectCycles(exec) {
+  const resolved = new Set();
+  const visiting = new Set();
+  const cycles = [];
+
+  function visit(category) {
+    if (resolved.has(category)) return;
+    if (visiting.has(category)) {
+      cycles.push(category);
+      return;
+    }
+    visiting.add(category);
+    const child = exec.children.find(c => c.category === category);
+    if (child) {
+      for (const dep of child.dependsOn) {
+        visit(dep);
+      }
+    }
+    visiting.delete(category);
+    resolved.add(category);
+  }
+
+  for (const child of exec.children) {
+    visit(child.category);
+  }
+  return cycles;
+}
+
 // ── Invalidation ──────────────────────────────────────────────────────────────
 
 /**

package/src/dispatch.mjs

@@ -16,85 +16,7 @@
 import { existsSync, mkdirSync, writeFileSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { resolveBlocked, resolveRejected } from "./escalation.mjs";
-
-// ── Tool profiles per role ────────────────────────────────────────────────────
-// What tools each role is allowed to use. Sandboxing by contract.
-
-const TOOL_PROFILES = {
-  // Core
-  "Orchestrator":         ["Read", "Glob", "Grep", "Bash", "Write", "Edit"],
-  "Product Strategist":   ["Read", "Glob", "Grep", "Write"],
-  "Critic Reviewer":      ["Read", "Glob", "Grep", "Bash"],
-
-  // Design
-  "UI Designer":          ["Read", "Glob", "Grep", "Write", "Edit"],
-  "Brand Guardian":       ["Read", "Glob", "Grep"],
-
-  // Engineering
-  "Backend Engineer":     ["Read", "Glob", "Grep", "Bash", "Write", "Edit"],
-  "Frontend Developer":   ["Read", "Glob", "Grep", "Bash", "Write", "Edit"],
-  "Test Engineer":        ["Read", "Glob", "Grep", "Bash", "Write", "Edit"],
-  "Performance Engineer": ["Read", "Glob", "Grep", "Bash"],
-  "Refactor Engineer":    ["Read", "Glob", "Grep", "Bash", "Write", "Edit"],
-  "Security Reviewer":    ["Read", "Glob", "Grep", "Bash"],
-  "Dependency Auditor":   ["Read", "Glob", "Grep", "Bash"],
-
-  // Treatment
-  "Repo Researcher":      ["Read", "Glob", "Grep", "Bash"],
-  "Repo Translator":      ["Read", "Glob", "Grep", "Write", "Edit"],
-  "Docs Architect":       ["Read", "Glob", "Grep", "Write", "Edit"],
-  "Metadata Curator":     ["Read", "Glob", "Grep", "Write", "Edit"],
-  "Coverage Auditor":     ["Read", "Glob", "Grep", "Bash"],
-  "Deployment Verifier":  ["Read", "Glob", "Grep", "Bash"],
-  "Release Engineer":     ["Read", "Glob", "Grep", "Bash", "Write", "Edit"],
-
-  // Growth / Marketing
-  "Launch Strategist":    ["Read", "Glob", "Grep", "Write"],
-  "Content Strategist":   ["Read", "Glob", "Grep", "Write"],
-  "Community Manager":    ["Read", "Glob", "Grep", "Write"],
-  "Support Triage Lead":  ["Read", "Glob", "Grep", "Write"],
-  "Launch Copywriter":    ["Read", "Glob", "Grep", "Write", "Edit"],
-
-  // Product
-  "Feedback Synthesizer": ["Read", "Glob", "Grep"],
-  "Roadmap Prioritizer":  ["Read", "Glob", "Grep", "Write"],
-  "Spec Writer":          ["Read", "Glob", "Grep", "Write", "Edit"],
-
-  // Research
-  "UX Researcher":        ["Read", "Glob", "Grep"],
-  "Competitive Analyst":  ["Read", "Glob", "Grep"],
-  "Trend Researcher":     ["Read", "Glob", "Grep"],
-  "User Interview Synthesizer": ["Read", "Glob", "Grep"],
-
-  // Brainstorm
-  "Context Scout":        ["Read", "Glob", "Grep"],
-  "User Value Scout":     ["Read", "Glob", "Grep"],
-  "Creative Leap Scout":  ["Read", "Glob", "Grep"],
-  "Normalizer":           ["Read", "Glob", "Grep"],
-  "Synthesizer":          ["Read", "Glob", "Grep", "Write"],
-  "Product Expander":     ["Read", "Glob", "Grep", "Write"],
-  "Judge":                ["Read", "Glob", "Grep"],
-  "Mechanics Scout":      ["Read", "Glob", "Grep"],
-  "Market Scout":         ["Read", "Glob", "Grep"],
-  "Contrarian Scout":     ["Read", "Glob", "Grep"],
-  "Feasibility Scout":    ["Read", "Glob", "Grep"],
-  "Quality Bar Scout":    ["Read", "Glob", "Grep"],
-  "Scenario Expander":    ["Read", "Glob", "Grep", "Write"],
-  "Moat Expander":        ["Read", "Glob", "Grep", "Write"],
-
-  // Brainstorm v0.3 analysts
-  "Context Analyst":      ["Read", "Glob", "Grep"],
-  "User Value Analyst":   ["Read", "Glob", "Grep"],
-  "Mechanics Analyst":    ["Read", "Glob", "Grep"],
-  "Positioning Analyst":  ["Read", "Glob", "Grep"],
-  "Contrarian Analyst":   ["Read", "Glob", "Grep"],
-
-  // Deep Audit
-  "Component Auditor":    ["Read", "Glob", "Grep"],
-  "Seam Auditor":         ["Read", "Glob", "Grep"],
-  "Test Truth Auditor":   ["Read", "Glob", "Grep"],
-  "Audit Synthesizer":    ["Read", "Glob", "Grep", "Write"],
-};
+import { TOOL_PROFILES } from "./tool-profiles.mjs";
 
 // ── Default role config ─────────────────────────────────────────────────────
 

package/src/hooks.mjs

@@ -322,7 +322,7 @@ function generateSessionStartScript() {
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
 import { join } from "node:path";
 
-const input = JSON.parse(readFileSync("/dev/stdin", "utf-8").toString() || "{}");
+const input = JSON.parse(readFileSync(0, "utf-8").toString() || "{}");
 const cwd = input.cwd || process.cwd();
 const stateDir = join(cwd, ".claude", "hooks");
 mkdirSync(stateDir, { recursive: true });
@@ -356,7 +356,7 @@ function generatePromptSubmitScript() {
 import { readFileSync, writeFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 
-const input = JSON.parse(readFileSync("/dev/stdin", "utf-8").toString() || "{}");
+const input = JSON.parse(readFileSync(0, "utf-8").toString() || "{}");
 const cwd = input.cwd || process.cwd();
 const statePath = join(cwd, ".claude", "hooks", "session-state.json");
 
@@ -389,7 +389,7 @@ function generatePreToolUseScript() {
 import { readFileSync, writeFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 
-const input = JSON.parse(readFileSync("/dev/stdin", "utf-8").toString() || "{}");
+const input = JSON.parse(readFileSync(0, "utf-8").toString() || "{}");
 const cwd = input.cwd || process.cwd();
 const statePath = join(cwd, ".claude", "hooks", "session-state.json");
 
@@ -421,7 +421,7 @@ function generateSubagentStartScript() {
 import { readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 
-const input = JSON.parse(readFileSync("/dev/stdin", "utf-8").toString() || "{}");
+const input = JSON.parse(readFileSync(0, "utf-8").toString() || "{}");
 const cwd = input.cwd || process.cwd();
 const statePath = join(cwd, ".claude", "hooks", "session-state.json");
 
@@ -444,7 +444,7 @@ function generateStopScript() {
 import { readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 
-const input = JSON.parse(readFileSync("/dev/stdin", "utf-8").toString() || "{}");
+const input = JSON.parse(readFileSync(0, "utf-8").toString() || "{}");
 const cwd = input.cwd || process.cwd();
 const statePath = join(cwd, ".claude", "hooks", "session-state.json");
 

package/src/mission-run.mjs

@@ -11,6 +11,7 @@
 
 import { MISSIONS, getMission, validateMission } from "./mission.mjs";
 import { validateArtifact } from "./artifacts.mjs";
+import { STEP_TRANSITIONS, isValidStepTransition } from "./state-machine.mjs";
 
 let _runCounter = 0;
 
@@ -198,6 +199,10 @@ function buildDynamicSteps(mission, manifest) {
  * @returns {MissionStep|null} The started step, or null if no pending steps
  */
 export function startNextStep(run) {
+  // Guard: refuse to activate a new step if one is already active (prevents dual-active)
+  const alreadyActive = run.steps.find((s) => s.status === "active");
+  if (alreadyActive) return null;
+
   const next = run.steps.find((s) => s.status === "pending");
   if (!next) return null;
 

package/src/run.mjs

@@ -12,7 +12,7 @@
  * Interventions: reroute, split, escalate, retry, block, reopen
  */
 
-import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync } from "node:fs";
+import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, renameSync } from "node:fs";
 import { join } from "node:path";
 import { decideEntry } from "./entry.mjs";
 import { getMission } from "./mission.mjs";
@@ -285,6 +285,10 @@ function guessArtifact(roleName) {
  * @returns {RunStep|null}
  */
 export function startNext(run, cwd) {
+  // Guard: refuse to activate a new step if one is already active (prevents dual-active)
+  const alreadyActive = run.steps.find(s => s.status === "active");
+  if (alreadyActive) return null;
+
   const next = run.steps.find(s => s.status === "pending");
   if (!next) return null;
 
@@ -854,7 +858,10 @@ export function formatReport(report) {
 export function saveRun(cwd, run) {
   const dir = runsDir(cwd);
   mkdirSync(dir, { recursive: true });
-  writeFileSync(runPath(cwd, run.id), JSON.stringify(run, null, 2));
+  const target = runPath(cwd, run.id);
+  const tmp = target + ".tmp";
+  writeFileSync(tmp, JSON.stringify(run, null, 2));
+  renameSync(tmp, target);
 }
 
 /**

package/src/state-machine.mjs

@@ -0,0 +1,70 @@
+/**
+ * Shared State Machine — valid transitions for run steps.
+ *
+ * Both run.mjs (persistent runner) and mission-run.mjs (mission runner)
+ * use the same step lifecycle. This module defines the canonical transitions
+ * so they cannot diverge.
+ */
+
+/**
+ * Valid step status transitions.
+ * Key: current status. Value: array of allowed next statuses.
+ */
+export const STEP_TRANSITIONS = {
+  pending:   ["active"],
+  active:    ["completed", "partial", "failed", "blocked"],
+  completed: ["pending"],          // re-opened by escalation
+  partial:   ["pending"],          // retried
+  failed:    ["pending"],          // retried
+  blocked:   ["pending"],          // unblocked
+  skipped:   [],                   // terminal
+};
+
+/**
+ * Valid run status transitions.
+ */
+export const RUN_TRANSITIONS = {
+  planning:  ["running"],
+  running:   ["paused", "completed", "partial", "failed"],
+  paused:    ["running"],
+  completed: ["paused"],           // re-opened by escalation/reopen
+  partial:   ["paused"],           // retried
+  failed:    ["paused"],           // retried
+};
+
+/**
+ * Check if a step transition is valid.
+ * @param {string} from - Current status
+ * @param {string} to - Desired status
+ * @returns {boolean}
+ */
+export function isValidStepTransition(from, to) {
+  const allowed = STEP_TRANSITIONS[from];
+  if (!allowed) return false;
+  return allowed.includes(to);
+}
+
+/**
+ * Check if a run transition is valid.
+ * @param {string} from - Current status
+ * @param {string} to - Desired status
+ * @returns {boolean}
+ */
+export function isValidRunTransition(from, to) {
+  const allowed = RUN_TRANSITIONS[from];
+  if (!allowed) return false;
+  return allowed.includes(to);
+}
+
+/**
+ * Assert a step transition is valid, or throw.
+ * @param {string} from
+ * @param {string} to
+ * @param {string} [context] - Description for error message
+ */
+export function assertStepTransition(from, to, context = "") {
+  if (!isValidStepTransition(from, to)) {
+    const prefix = context ? `${context}: ` : "";
+    throw new Error(`${prefix}Invalid step transition "${from}" → "${to}"`);
+  }
+}

package/src/tool-profiles.mjs

@@ -0,0 +1,82 @@
+/**
+ * Tool Profiles — per-role tool sandboxing.
+ *
+ * Extracted to a shared module so that both dispatch.mjs and trial.mjs
+ * can import it without creating a circular dependency.
+ */
+
+export const TOOL_PROFILES = {
+  // Core
+  "Orchestrator":         ["Read", "Glob", "Grep", "Bash", "Write", "Edit"],
+  "Product Strategist":   ["Read", "Glob", "Grep", "Write"],
+  "Critic Reviewer":      ["Read", "Glob", "Grep", "Bash"],
+
+  // Design
+  "UI Designer":          ["Read", "Glob", "Grep", "Write", "Edit"],
+  "Brand Guardian":       ["Read", "Glob", "Grep"],
+
+  // Engineering
+  "Backend Engineer":     ["Read", "Glob", "Grep", "Bash", "Write", "Edit"],
+  "Frontend Developer":   ["Read", "Glob", "Grep", "Bash", "Write", "Edit"],
+  "Test Engineer":        ["Read", "Glob", "Grep", "Bash", "Write", "Edit"],
+  "Performance Engineer": ["Read", "Glob", "Grep", "Bash"],
+  "Refactor Engineer":    ["Read", "Glob", "Grep", "Bash", "Write", "Edit"],
+  "Security Reviewer":    ["Read", "Glob", "Grep", "Bash"],
+  "Dependency Auditor":   ["Read", "Glob", "Grep", "Bash"],
+
+  // Treatment
+  "Repo Researcher":      ["Read", "Glob", "Grep", "Bash"],
+  "Repo Translator":      ["Read", "Glob", "Grep", "Write", "Edit"],
+  "Docs Architect":       ["Read", "Glob", "Grep", "Write", "Edit"],
+  "Metadata Curator":     ["Read", "Glob", "Grep", "Write", "Edit"],
+  "Coverage Auditor":     ["Read", "Glob", "Grep", "Bash"],
+  "Deployment Verifier":  ["Read", "Glob", "Grep", "Bash"],
+  "Release Engineer":     ["Read", "Glob", "Grep", "Bash", "Write", "Edit"],
+
+  // Growth / Marketing
+  "Launch Strategist":    ["Read", "Glob", "Grep", "Write"],
+  "Content Strategist":   ["Read", "Glob", "Grep", "Write"],
+  "Community Manager":    ["Read", "Glob", "Grep", "Write"],
+  "Support Triage Lead":  ["Read", "Glob", "Grep", "Write"],
+  "Launch Copywriter":    ["Read", "Glob", "Grep", "Write", "Edit"],
+
+  // Product
+  "Feedback Synthesizer": ["Read", "Glob", "Grep"],
+  "Roadmap Prioritizer":  ["Read", "Glob", "Grep", "Write"],
+  "Spec Writer":          ["Read", "Glob", "Grep", "Write", "Edit"],
+
+  // Research
+  "UX Researcher":        ["Read", "Glob", "Grep"],
+  "Competitive Analyst":  ["Read", "Glob", "Grep"],
+  "Trend Researcher":     ["Read", "Glob", "Grep"],
+  "User Interview Synthesizer": ["Read", "Glob", "Grep"],
+
+  // Brainstorm
+  "Context Scout":        ["Read", "Glob", "Grep"],
+  "User Value Scout":     ["Read", "Glob", "Grep"],
+  "Creative Leap Scout":  ["Read", "Glob", "Grep"],
+  "Normalizer":           ["Read", "Glob", "Grep"],
+  "Synthesizer":          ["Read", "Glob", "Grep", "Write"],
+  "Product Expander":     ["Read", "Glob", "Grep", "Write"],
+  "Judge":                ["Read", "Glob", "Grep"],
+  "Mechanics Scout":      ["Read", "Glob", "Grep"],
+  "Market Scout":         ["Read", "Glob", "Grep"],
+  "Contrarian Scout":     ["Read", "Glob", "Grep"],
+  "Feasibility Scout":    ["Read", "Glob", "Grep"],
+  "Quality Bar Scout":    ["Read", "Glob", "Grep"],
+  "Scenario Expander":    ["Read", "Glob", "Grep", "Write"],
+  "Moat Expander":        ["Read", "Glob", "Grep", "Write"],
+
+  // Brainstorm v0.3 analysts
+  "Context Analyst":      ["Read", "Glob", "Grep"],
+  "User Value Analyst":   ["Read", "Glob", "Grep"],
+  "Mechanics Analyst":    ["Read", "Glob", "Grep"],
+  "Positioning Analyst":  ["Read", "Glob", "Grep"],
+  "Contrarian Analyst":   ["Read", "Glob", "Grep"],
+
+  // Deep Audit
+  "Component Auditor":    ["Read", "Glob", "Grep"],
+  "Seam Auditor":         ["Read", "Glob", "Grep"],
+  "Test Truth Auditor":   ["Read", "Glob", "Grep"],
+  "Audit Synthesizer":    ["Read", "Glob", "Grep", "Write"],
+};

package/src/trial.mjs

@@ -10,7 +10,7 @@
  */
 
 import { ROLE_CATALOG, scoreRole, MIN_SCORE_THRESHOLD } from "./route.mjs";
-import { TOOL_PROFILES } from "./dispatch.mjs";
+import { TOOL_PROFILES } from "./tool-profiles.mjs";
 import { getRequirements } from "./evidence.mjs";
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
 import { join, resolve } from "node:path";