role-os 1.0.2 → 1.2.0

package/src/dispatch.mjs

@@ -0,0 +1,310 @@
+/**
+ * Runtime dispatch engine.
+ *
+ * Turns a staffed, validated chain into an executable dispatch manifest
+ * that multi-claude can consume. Role-OS owns staffing/routing/evidence;
+ * multi-claude owns execution.
+ *
+ * This module:
+ * 1. Maps roles → role configs (tool profiles, system prompts, budgets)
+ * 2. Tracks execution state (queued → running → completed/failed/blocked)
+ * 3. Collects outputs back into the packet system
+ * 4. Generates escalation packets for blocked/rejected work
+ * 5. Closes chains to final completion
+ */
+
+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"],
+};
+
+// ── Default role config ─────────────────────────────────────────────────────
+
+const DEFAULTS = {
+  model: "sonnet",
+  maxTurns: 30,
+  maxBudgetUsd: 5.0,
+  timeoutMs: 10 * 60 * 1000, // 10 minutes
+};
+
+// ── Execution states ──────────────────────────────────────────────────────────
+
+export const EXEC_STATES = [
+  "queued",         // in chain, not yet launched
+  "running",        // role session active
+  "waiting",        // waiting for upstream handoff
+  "blocked",        // hit a block condition
+  "needs-review",   // completed work, awaiting verdict
+  "completed",      // approved and done
+  "failed",         // session error or timeout
+  "interrupted",    // manually stopped
+];
+
+// ── System prompt builder ─────────────────────────────────────────────────────
+
+function buildRolePrompt(roleName, packetContent, chainContext) {
+  return `You are operating as ${roleName} in a Role-OS managed chain.
+
+## Your Role Contract
+Follow the ${roleName} contract exactly. Your quality bar, inputs, outputs, and escalation rules are defined in .claude/agents/.
+
+## Current Packet
+${packetContent}
+
+## Chain Context
+You are step ${chainContext.stepNumber} of ${chainContext.totalSteps} in this chain.
+${chainContext.previousRole ? `Previous role: ${chainContext.previousRole} (${chainContext.previousStatus})` : "You are the first role in this chain."}
+${chainContext.nextRole ? `Next role: ${chainContext.nextRole}` : "You are the last role before Critic review."}
+
+## Handoff Requirements
+When you finish, produce a structured handoff:
+1. Summary of what you did
+2. Artifacts produced (files, changes, docs)
+3. Open questions or risks for the next role
+4. Evidence items for your verdict (kind, reference, claim, status)
+
+## Stop Conditions
+- If you cannot proceed: output a BLOCKED status with a clear reason
+- If the upstream handoff is insufficient: output a BLOCKED status explaining what's missing
+- Do not silently skip work — surface every gap explicitly
+`;
+}
+
+// ── Dispatch manifest builder ─────────────────────────────────────────────────
+
+/**
+ * Build a dispatch manifest from a routed chain.
+ * This is the contract between Role-OS (planning) and multi-claude (execution).
+ *
+ * @param {Object} options
+ * @param {string} options.packetFile - Path to the packet markdown
+ * @param {string} options.packetContent - Packet markdown content
+ * @param {Array<{role: {name: string, pack: string}}>} options.chainRoles - Assembled chain
+ * @param {string} options.cwd - Working directory for execution
+ * @param {Object} [options.overrides] - Per-role config overrides
+ * @returns {DispatchManifest}
+ */
+export function buildDispatchManifest({ packetFile, packetContent, chainRoles, cwd, overrides = {} }) {
+  const runId = `run-${Date.now()}`;
+  const steps = [];
+
+  for (let i = 0; i < chainRoles.length; i++) {
+    const { role } = chainRoles[i];
+    const roleOverrides = overrides[role.name] || {};
+
+    const chainContext = {
+      stepNumber: i + 1,
+      totalSteps: chainRoles.length,
+      previousRole: i > 0 ? chainRoles[i - 1].role.name : null,
+      previousStatus: i > 0 ? "pending" : null,
+      nextRole: i < chainRoles.length - 1 ? chainRoles[i + 1].role.name : null,
+    };
+
+    steps.push({
+      stepIndex: i,
+      packetId: `${runId}-step-${i}`,
+      role: role.name,
+      pack: role.pack,
+      tools: TOOL_PROFILES[role.name] || ["Read", "Glob", "Grep"],
+      systemPrompt: buildRolePrompt(role.name, packetContent, chainContext),
+      model: roleOverrides.model || DEFAULTS.model,
+      maxTurns: roleOverrides.maxTurns || DEFAULTS.maxTurns,
+      maxBudgetUsd: roleOverrides.maxBudgetUsd || DEFAULTS.maxBudgetUsd,
+      timeoutMs: roleOverrides.timeoutMs || DEFAULTS.timeoutMs,
+      state: "queued",
+      dependsOn: i > 0 ? [`${runId}-step-${i - 1}`] : [],
+      handoff: {
+        from: i > 0 ? chainRoles[i - 1].role.name : null,
+        to: i < chainRoles.length - 1 ? chainRoles[i + 1].role.name : null,
+      },
+    });
+  }
+
+  return {
+    version: 1,
+    runId,
+    createdAt: new Date().toISOString(),
+    packetFile: resolve(packetFile),
+    cwd: resolve(cwd),
+    totalSteps: steps.length,
+    steps,
+  };
+}
+
+// ── Execution state tracker ───────────────────────────────────────────────────
+
+/**
+ * Update a step's execution state in the manifest.
+ *
+ * @param {DispatchManifest} manifest
+ * @param {number} stepIndex
+ * @param {string} newState - One of EXEC_STATES
+ * @param {Object} [result] - Execution result data
+ * @returns {DispatchManifest} Updated manifest (mutated in place)
+ */
+export function updateStepState(manifest, stepIndex, newState, result = {}) {
+  const step = manifest.steps[stepIndex];
+  if (!step) throw new Error(`Invalid step index: ${stepIndex}`);
+  if (!EXEC_STATES.includes(newState)) throw new Error(`Invalid state: ${newState}`);
+
+  step.state = newState;
+  step.result = {
+    ...step.result,
+    ...result,
+    updatedAt: new Date().toISOString(),
+  };
+
+  // Auto-advance: if this step completed, mark next step as ready
+  if (newState === "completed" && stepIndex < manifest.steps.length - 1) {
+    const nextStep = manifest.steps[stepIndex + 1];
+    if (nextStep.state === "queued") {
+      nextStep.state = "waiting"; // ready to launch
+    }
+  }
+
+  return manifest;
+}
+
+/**
+ * Get the chain's overall status from individual step states.
+ *
+ * @param {DispatchManifest} manifest
+ * @returns {{status: string, completedSteps: number, totalSteps: number, currentStep: Object|null, blockedSteps: Object[]}}
+ */
+export function getChainStatus(manifest) {
+  const completed = manifest.steps.filter(s => s.state === "completed").length;
+  const blocked = manifest.steps.filter(s => s.state === "blocked");
+  const failed = manifest.steps.filter(s => s.state === "failed");
+  const running = manifest.steps.find(s => s.state === "running");
+  const waiting = manifest.steps.find(s => s.state === "waiting");
+
+  let status;
+  if (failed.length > 0) status = "failed";
+  else if (blocked.length > 0) status = "blocked";
+  else if (completed === manifest.steps.length) status = "completed";
+  else if (running) status = "running";
+  else if (waiting) status = "ready";
+  else status = "queued";
+
+  return {
+    status,
+    completedSteps: completed,
+    totalSteps: manifest.steps.length,
+    currentStep: running || waiting || null,
+    blockedSteps: blocked,
+    failedSteps: failed,
+  };
+}
+
+// ── Escalation packet generator ───────────────────────────────────────────────
+
+/**
+ * Generate an escalation packet when a step is blocked or rejected.
+ *
+ * @param {Object} step - The blocked/rejected step
+ * @param {string} reason - Block/rejection reason
+ * @param {string} verdict - "blocked" or "reject"
+ * @returns {Object} Escalation packet ready for routing
+ */
+export function generateEscalationPacket(step, reason, verdict) {
+  const escalation = verdict === "blocked"
+    ? resolveBlocked(reason)
+    : resolveRejected(reason, step.role);
+
+  return {
+    type: "escalation",
+    sourceStep: step.packetId,
+    sourceRole: step.role,
+    verdict,
+    reason,
+    escalation,
+    packet: {
+      title: `Escalation: ${step.role} ${verdict} — ${reason.slice(0, 80)}`,
+      assignedRole: escalation.targetRole,
+      recovery: escalation.recovery,
+      requiredArtifact: escalation.requiredArtifact,
+      context: escalation.handoffContext || escalation.reason,
+      sourcePacketFile: step.packetId,
+    },
+    generatedAt: new Date().toISOString(),
+  };
+}
+
+// ── Manifest persistence ──────────────────────────────────────────────────────
+
+/**
+ * Save a dispatch manifest to disk.
+ *
+ * @param {DispatchManifest} manifest
+ * @param {string} outputDir - Directory to write to
+ * @returns {string} Path to the saved manifest
+ */
+export function saveManifest(manifest, outputDir) {
+  mkdirSync(outputDir, { recursive: true });
+  const path = join(outputDir, `${manifest.runId}.dispatch.json`);
+  writeFileSync(path, JSON.stringify(manifest, null, 2));
+  return path;
+}
+
+/**
+ * Load a dispatch manifest from disk.
+ *
+ * @param {string} path
+ * @returns {DispatchManifest}
+ */
+export function loadManifest(path) {
+  return JSON.parse(readFileSync(path, "utf-8"));
+}
+
+// ── Exports for integration ───────────────────────────────────────────────────
+
+export { TOOL_PROFILES, DEFAULTS };

package/src/escalation.mjs

@@ -0,0 +1,288 @@
+/**
+ * Escalation auto-routing.
+ *
+ * When a packet hits a stop condition (blocked, rejected, conflict, split-needed),
+ * this module routes it to the right resolver with a reason, required artifact,
+ * and recovery type.
+ *
+ * Every escalation produces a clean next-step — not just a destination.
+ */
+
+// ── Recovery types ────────────────────────────────────────────────────────────
+
+/**
+ * @typedef {'retry' | 'revise' | 'review' | 'split' | 'reroute' | 'add-role'} RecoveryType
+ */
+
+/**
+ * @typedef {Object} EscalationResult
+ * @property {string} targetRole - Who owns the recovery
+ * @property {RecoveryType} recovery - What kind of recovery this is
+ * @property {string} reason - Why this role was chosen
+ * @property {string} requiredArtifact - What they must produce to unblock
+ * @property {string} handoffContext - What the target needs to know
+ */
+
+// ── Blocked work routing ──────────────────────────────────────────────────────
+// Each blocked reason maps to a resolver role + recovery path.
+
+const BLOCKED_ROUTES = {
+  // Missing information / unclear requirements
+  "missing info": {
+    targetRole: "Product Strategist",
+    recovery: "revise",
+    reason: "Blocked on missing information — Product Strategist owns requirement clarification",
+    requiredArtifact: "Updated scope doc or clarified requirements",
+    handoffContext: "Identify exactly what information is missing and whether it requires user input or can be derived from existing context",
+  },
+  "unclear requirements": {
+    targetRole: "Product Strategist",
+    recovery: "revise",
+    reason: "Requirements are ambiguous — Product Strategist owns scope clarification",
+    requiredArtifact: "Clarified requirements with acceptance criteria",
+    handoffContext: "Flag which requirements are ambiguous and what interpretations exist",
+  },
+  "scope contradiction": {
+    targetRole: "Product Strategist",
+    recovery: "revise",
+    reason: "Scope contains contradictions — Product Strategist must resolve",
+    requiredArtifact: "Revised scope with contradictions resolved and tradeoffs documented",
+    handoffContext: "List the specific contradictions and what each interpretation implies for delivery",
+  },
+
+  // Dependency unavailable
+  "dependency unavailable": {
+    targetRole: "Orchestrator",
+    recovery: "reroute",
+    reason: "Upstream dependency is unavailable — Orchestrator must re-sequence or find alternative",
+    requiredArtifact: "Revised execution plan with dependency resolved or worked around",
+    handoffContext: "Identify which dependency is blocked, what it provides, and whether alternatives exist",
+  },
+  "blocked upstream": {
+    targetRole: "Orchestrator",
+    recovery: "reroute",
+    reason: "Upstream work is incomplete — Orchestrator must re-sequence",
+    requiredArtifact: "Updated chain with dependency ordering corrected",
+    handoffContext: "Identify which upstream deliverable is missing and which role was supposed to produce it",
+  },
+
+  // Technical infeasibility
+  "technical infeasibility": {
+    targetRole: "Backend Engineer",
+    recovery: "revise",
+    reason: "Proposed approach is technically infeasible — needs engineering assessment",
+    requiredArtifact: "Feasibility analysis with alternative approaches",
+    handoffContext: "Document what was attempted, why it failed, and what constraints make the original approach infeasible",
+  },
+  "architecture mismatch": {
+    targetRole: "Orchestrator",
+    recovery: "split",
+    reason: "Work doesn't fit the current architecture — may need decomposition",
+    requiredArtifact: "Architectural assessment and revised packet(s)",
+    handoffContext: "Explain the mismatch between the work and the architecture, and what would need to change",
+  },
+
+  // Owner ambiguity
+  "owner ambiguity": {
+    targetRole: "Orchestrator",
+    recovery: "reroute",
+    reason: "Unclear which role owns this work — Orchestrator must assign",
+    requiredArtifact: "Clear role assignment with justification",
+    handoffContext: "Describe what the work is and which roles could plausibly own it",
+  },
+};
+
+// ── Rejected work routing ─────────────────────────────────────────────────────
+// Rejected work routes backward with intent.
+
+const REJECTED_ROUTES = {
+  "quality bar miss": {
+    recovery: "retry",
+    reason: "Output did not meet the role's quality bar — send back to the producing role",
+    requiredArtifact: "Revised output addressing quality bar gaps",
+    handoffContext: "Cite the specific quality bar items that were not met",
+    targetRoleRule: "previous", // route to the role that produced the rejected output
+  },
+  "wrong artifact type": {
+    recovery: "revise",
+    reason: "Wrong deliverable type — role may have misunderstood the packet",
+    requiredArtifact: "Correct artifact type as specified in the packet",
+    handoffContext: "Clarify what artifact was expected vs what was produced",
+    targetRoleRule: "previous",
+  },
+  "incomplete evidence": {
+    recovery: "retry",
+    reason: "Evidence is incomplete — role must provide missing proof",
+    requiredArtifact: "Complete evidence set as required by the review contract",
+    handoffContext: "List exactly which evidence items are missing or insufficient",
+    targetRoleRule: "previous",
+  },
+  "role mismatch": {
+    recovery: "reroute",
+    reason: "This work was assigned to the wrong role — needs re-routing",
+    requiredArtifact: "Re-routed packet with correct role assignment",
+    handoffContext: "Explain why the current role is wrong and which role should own this",
+    targetRoleRule: "orchestrator",
+  },
+  "chain problem": {
+    recovery: "reroute",
+    reason: "The chain/ordering is wrong — Orchestrator must restructure",
+    requiredArtifact: "Revised chain with corrected ordering or role selection",
+    handoffContext: "Describe the chain problem and what the correct structure should be",
+    targetRoleRule: "orchestrator",
+  },
+};
+
+// ── Conflict escalation routing ───────────────────────────────────────────────
+
+const CONFLICT_ROUTES = {
+  blocking: {
+    targetRole: "Orchestrator",
+    recovery: "reroute",
+    reason: "Hard conflict in chain — cannot execute without restructuring",
+    requiredArtifact: "Revised chain with conflict resolved",
+  },
+  sequence: {
+    targetRole: "Orchestrator",
+    recovery: "reroute",
+    reason: "Sequence conflict — roles are in the wrong order",
+    requiredArtifact: "Reordered chain with correct role sequencing",
+  },
+  redundancy: {
+    targetRole: "Orchestrator",
+    recovery: "revise",
+    reason: "Redundant roles in chain — consider trimming or splitting",
+    requiredArtifact: "Trimmed chain or split into sub-packets",
+  },
+  coverage: {
+    targetRole: "Orchestrator",
+    recovery: "add-role",
+    reason: "Coverage gap — chain is missing a critical role",
+    requiredArtifact: "Updated chain with missing role added",
+  },
+};
+
+// ── Split routing ─────────────────────────────────────────────────────────────
+
+const SPLIT_ROUTE = {
+  targetRole: "Orchestrator",
+  recovery: "split",
+  reason: "Chain is too large (>7 roles) — needs decomposition into sub-packets",
+  requiredArtifact: "Decomposed packets, each with its own chain and scope",
+  handoffContext: "Identify natural seams in the work where splitting reduces complexity without creating integration debt",
+};
+
+// ── Resolution engine ─────────────────────────────────────────────────────────
+
+/**
+ * Resolve a blocked verdict to an escalation target.
+ *
+ * @param {string} blockedReason - Why the work is blocked (free text, matched against known patterns)
+ * @returns {EscalationResult}
+ */
+export function resolveBlocked(blockedReason) {
+  const lower = (blockedReason || "").toLowerCase();
+
+  // Try exact-ish matches first
+  for (const [pattern, route] of Object.entries(BLOCKED_ROUTES)) {
+    if (lower.includes(pattern)) {
+      return { ...route };
+    }
+  }
+
+  // Default: Orchestrator owns unknown blocks
+  return {
+    targetRole: "Orchestrator",
+    recovery: "reroute",
+    reason: "Blocked for unrecognized reason — Orchestrator must assess and route",
+    requiredArtifact: "Assessment of block cause and recovery plan",
+    handoffContext: `Original block reason: "${blockedReason}"`,
+  };
+}
+
+/**
+ * Resolve a rejected verdict to an escalation target.
+ *
+ * @param {string} rejectedReason - Why the work was rejected
+ * @param {string} previousRole - The role that produced the rejected output
+ * @returns {EscalationResult}
+ */
+export function resolveRejected(rejectedReason, previousRole) {
+  const lower = (rejectedReason || "").toLowerCase();
+
+  for (const [pattern, route] of Object.entries(REJECTED_ROUTES)) {
+    if (lower.includes(pattern)) {
+      const target = route.targetRoleRule === "previous"
+        ? (previousRole || "Orchestrator")
+        : route.targetRoleRule === "orchestrator"
+          ? "Orchestrator"
+          : route.targetRoleRule;
+
+      return {
+        targetRole: target,
+        recovery: route.recovery,
+        reason: route.reason,
+        requiredArtifact: route.requiredArtifact,
+        handoffContext: route.handoffContext,
+      };
+    }
+  }
+
+  // Default: route back to previous role for retry
+  return {
+    targetRole: previousRole || "Orchestrator",
+    recovery: "retry",
+    reason: "Rejected — route back to producing role for revision",
+    requiredArtifact: "Revised output addressing rejection reason",
+    handoffContext: `Original rejection reason: "${rejectedReason}"`,
+  };
+}
+
+/**
+ * Resolve a conflict finding to an escalation target.
+ *
+ * @param {{type: string, severity: string, roles: string[], message: string, repair: string}} conflict
+ * @returns {EscalationResult}
+ */
+export function resolveConflict(conflict) {
+  const route = CONFLICT_ROUTES[conflict.type] || CONFLICT_ROUTES.blocking;
+
+  return {
+    targetRole: route.targetRole,
+    recovery: route.recovery,
+    reason: `${route.reason}: ${conflict.message}`,
+    requiredArtifact: route.requiredArtifact,
+    handoffContext: `Repair suggestion: ${conflict.repair}`,
+  };
+}
+
+/**
+ * Resolve a split-needed chain to a decomposition owner.
+ *
+ * @param {number} chainSize
+ * @returns {EscalationResult}
+ */
+export function resolveSplit(chainSize) {
+  return {
+    ...SPLIT_ROUTE,
+    handoffContext: `Current chain has ${chainSize} roles. ${SPLIT_ROUTE.handoffContext}`,
+  };
+}
+
+/**
+ * Format an escalation result for operator display.
+ *
+ * @param {EscalationResult} result
+ * @returns {string}
+ */
+export function formatEscalation(result) {
+  const lines = [
+    `  → ${result.targetRole} (${result.recovery})`,
+    `    why: ${result.reason}`,
+    `    must produce: ${result.requiredArtifact}`,
+  ];
+  if (result.handoffContext) {
+    lines.push(`    context: ${result.handoffContext}`);
+  }
+  return lines.join("\n");
+}