role-os 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # Changelog
 
+## 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
+
+#### Outcome Calibration (Phase M)
+- Run outcome ledger — append-only JSONL recording pack selection, confidence, overrides, escalations, corrections, completion status
+- `computeCalibration()` — pack usage rates, high-confidence accuracy, operator override rates, per-pack performance
+- `computePackBoosts()` — weight tuning from clean completed runs (+0.5/run, capped at 2.0)
+- `computeConfidenceAdjustment()` — raises threshold when high-confidence is often overridden, lowers when medium is often accepted
+- Auto-generated calibration suggestions when metrics drift
+- Safety constraint: calibration never overrides mismatch guards, conflict rules, escalation honesty, or evidence requirements
+
+#### Mixed-Task Decomposition (Phase N)
+- `detectComposite()` — 7 subtask categories (build, bugfix, security, docs, research, launch, treatment) with signal-based detection
+- Structural connector detection ("and then", "after that", "plus", "also")
+- Confidence levels: high (3+ categories or 2+ with connectors), medium, low
+- `decompose()` — generates linked child packets sorted by phase order
+- `createRunPlan()` — dependency-aware parent plan with child tracking
+- Honest fallback: medium/low confidence shows uncertainty warning with `--no-split` override
+
+#### Composite Execution (Phase O)
+- `initExecution()` / `advance()` — dependency-driven child execution with artifact passing
+- 7 artifact contracts defining what each category produces and expects
+- Artifact ledger tracking all cross-packet handoffs
+- `blockChild()` / `recoverChild()` / `failChild()` — branch recovery with transitive cascade
+- `invalidateDownstream()` — resets stale children when upstream changes, removes stale artifacts
+- `synthesize()` — truthful parent-level completion report
+- Independent branches continue unaffected when a sibling fails
+
+#### Adaptive Replanning (Phase P)
+- 6 structured change event types: scope-change, artifact-changed, new-requirement, review-finding, dependency-discovered, priority-change
+- `analyzeImpact()` — identifies valid/stale children, stale artifacts, whether new children or reorder needed
+- `replan()` — selective replanning: invalidates only affected branches, inserts new children, updates dependencies
+- Plan diff: shows what changed, what stayed valid, what reopened, what was inserted
+- Execution resumes from next valid child after replan — no restart required
+
+### Evidence
+- 317 tests, zero failures
+- Calibration, decomposition, composite execution, and replanning each have dedicated test suites
+
 ## 1.2.0
 
 ### Added

package/README.md

@@ -173,7 +173,12 @@ Role OS operates **locally only**. It copies markdown templates and writes packe
 | **Evidence** | Role-aware structured evidence in verdicts. Sufficiency checks. 12 evidence kinds. | ✓ Shipped |
 | **Dispatch** | Generates execution manifests for multi-claude. Per-role tool profiles, system prompts, budgets. | ✓ Shipped |
 | **Trials** | Full roster proven: 30/30 gold-task + 5/5 negative trials. 7 pack trials complete. | ✓ Complete |
-| **Team Packs** | 7 battle-tested packs for common task families. Pack suggestion engine. | ✓ Shipped |
+| **Team Packs** | 7 calibrated packs with auto-selection, mismatch guards, and free-routing fallback. | ✓ Shipped |
+| **Outcome calibration** | Records run outcomes, tunes pack/role weights from results, adjusts confidence thresholds. | ✓ Shipped |
+| **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 |
 
 ## Status
 
@@ -181,7 +186,9 @@ Role OS operates **locally only**. It copies markdown templates and writes packe
 - v1.0.0: 32 roles, full CLI, proven treatment, multi-repo portability
 - 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. 230 tests.
+- v1.2.0: Calibrated packs promoted to default entry. Auto-selection, mismatch detection, alternative suggestion, free-routing fallback. 246 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. Adoption certainty, not just routing cleverness. 335 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.2.0",
+  "version": "1.4.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/calibration.mjs

@@ -0,0 +1,292 @@
+/**
+ * Outcome Calibration — Phase M
+ *
+ * Records outcome signals from real runs and tunes routing/pack
+ * selection from results. The learning loop improves selection
+ * without overriding hard safety constraints.
+ *
+ * What it tunes:
+ * - Pack suggestion weights (which pack for which signals)
+ * - Confidence thresholds (when to suggest vs fall back)
+ * - Role scoring boosts (from successful chain patterns)
+ *
+ * What it NEVER overrides:
+ * - Hard mismatch guards
+ * - Conflict detection rules
+ * - Escalation honesty
+ * - Evidence requirements
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+// ── Outcome record shape ──────────────────────────────────────────────────────
+
+/**
+ * @typedef {Object} RunOutcome
+ * @property {string} runId - Unique run identifier
+ * @property {string} timestamp - ISO timestamp
+ * @property {string} packetFile - Path to the packet
+ * @property {string} detectedType - feature/integration/identity
+ * @property {string|null} suggestedPack - Pack auto-suggested (or null)
+ * @property {string} suggestedConfidence - high/medium/low
+ * @property {string|null} selectedPack - Pack actually used (or null for free routing)
+ * @property {boolean} operatorOverride - Did operator change the suggestion?
+ * @property {boolean} mismatchRedirect - Was a mismatch guard triggered?
+ * @property {string|null} mismatchFrom - Pack that was rejected
+ * @property {string|null} mismatchTo - Pack that was suggested instead
+ * @property {number} chainLength - Number of roles in the chain
+ * @property {number} escalations - Number of escalation events
+ * @property {number} rejectedVerdicts - Number of rejected verdicts
+ * @property {number} corrections - Number of operator corrections
+ * @property {string} completionStatus - completed/blocked/failed/abandoned
+ * @property {string[]} rolesUsed - Roles that participated
+ */
+
+// ── Ledger ────────────────────────────────────────────────────────────────────
+
+const LEDGER_DIR = ".claude/calibration";
+const LEDGER_FILE = "outcome-ledger.jsonl";
+
+/**
+ * Record a run outcome to the ledger (append-only JSONL).
+ *
+ * @param {RunOutcome} outcome
+ * @param {string} [cwd] - Working directory (default: process.cwd())
+ */
+export function recordOutcome(outcome, cwd = process.cwd()) {
+  const dir = join(cwd, LEDGER_DIR);
+  mkdirSync(dir, { recursive: true });
+  const path = join(dir, LEDGER_FILE);
+  const line = JSON.stringify({ ...outcome, recordedAt: new Date().toISOString() }) + "\n";
+  writeFileSync(path, line, { flag: "a" });
+}
+
+/**
+ * Read all outcomes from the ledger.
+ *
+ * @param {string} [cwd]
+ * @returns {RunOutcome[]}
+ */
+export function readOutcomes(cwd = process.cwd()) {
+  const path = join(cwd, LEDGER_DIR, LEDGER_FILE);
+  if (!existsSync(path)) return [];
+
+  return readFileSync(path, "utf-8")
+    .split("\n")
+    .filter(line => line.trim())
+    .map(line => {
+      try { return JSON.parse(line); }
+      catch { return null; }
+    })
+    .filter(Boolean);
+}
+
+// ── Calibration analysis ──────────────────────────────────────────────────────
+
+/**
+ * Compute calibration metrics from the outcome ledger.
+ *
+ * @param {RunOutcome[]} outcomes
+ * @returns {CalibrationReport}
+ */
+export function computeCalibration(outcomes) {
+  if (outcomes.length === 0) {
+    return {
+      totalRuns: 0,
+      packUsageRate: 0,
+      freeRoutingRate: 0,
+      highConfidenceAccuracy: 0,
+      operatorOverrideRate: 0,
+      mismatchRedirectRate: 0,
+      avgEscalations: 0,
+      avgCorrections: 0,
+      completionRate: 0,
+      packPerformance: {},
+      suggestions: [],
+    };
+  }
+
+  const total = outcomes.length;
+  const packUsed = outcomes.filter(o => o.selectedPack);
+  const freeRouted = outcomes.filter(o => !o.selectedPack);
+  const highConf = outcomes.filter(o => o.suggestedConfidence === "high");
+  const highConfCorrect = highConf.filter(o =>
+    o.selectedPack === o.suggestedPack && !o.operatorOverride
+  );
+  const overrides = outcomes.filter(o => o.operatorOverride);
+  const redirects = outcomes.filter(o => o.mismatchRedirect);
+  const completed = outcomes.filter(o => o.completionStatus === "completed");
+
+  // Per-pack performance
+  const packPerformance = {};
+  for (const o of outcomes) {
+    const key = o.selectedPack || "free-routing";
+    if (!packPerformance[key]) {
+      packPerformance[key] = {
+        runs: 0,
+        completed: 0,
+        escalations: 0,
+        corrections: 0,
+        avgChainLength: 0,
+        totalChainLength: 0,
+      };
+    }
+    const p = packPerformance[key];
+    p.runs++;
+    if (o.completionStatus === "completed") p.completed++;
+    p.escalations += o.escalations;
+    p.corrections += o.corrections;
+    p.totalChainLength += o.chainLength;
+  }
+  for (const p of Object.values(packPerformance)) {
+    p.avgChainLength = p.runs > 0 ? Math.round((p.totalChainLength / p.runs) * 10) / 10 : 0;
+    p.completionRate = p.runs > 0 ? Math.round((p.completed / p.runs) * 100) : 0;
+  }
+
+  // Generate suggestions
+  const suggestions = [];
+
+  // If high-confidence accuracy is below 80%, suggest tightening
+  const highConfAccuracy = highConf.length > 0
+    ? Math.round((highConfCorrect.length / highConf.length) * 100)
+    : 100;
+  if (highConfAccuracy < 80 && highConf.length >= 3) {
+    suggestions.push({
+      type: "tighten-confidence",
+      detail: `High-confidence accuracy is ${highConfAccuracy}% (${highConfCorrect.length}/${highConf.length}). Consider raising the confidence threshold.`,
+    });
+  }
+
+  // If operator override rate is above 20%, suggest review
+  const overrideRate = Math.round((overrides.length / total) * 100);
+  if (overrideRate > 20 && total >= 5) {
+    suggestions.push({
+      type: "review-suggestions",
+      detail: `Operator override rate is ${overrideRate}%. Pack suggestions may be misaligned with operator intent.`,
+    });
+  }
+
+  // If a specific pack has high escalation rate, flag it
+  for (const [key, p] of Object.entries(packPerformance)) {
+    if (p.runs >= 3 && p.escalations / p.runs > 1) {
+      suggestions.push({
+        type: "pack-escalation-concern",
+        detail: `Pack "${key}" averages ${(p.escalations / p.runs).toFixed(1)} escalations per run. May need retuning.`,
+      });
+    }
+  }
+
+  return {
+    totalRuns: total,
+    packUsageRate: Math.round((packUsed.length / total) * 100),
+    freeRoutingRate: Math.round((freeRouted.length / total) * 100),
+    highConfidenceAccuracy: highConfAccuracy,
+    operatorOverrideRate: overrideRate,
+    mismatchRedirectRate: Math.round((redirects.length / total) * 100),
+    avgEscalations: Math.round((outcomes.reduce((s, o) => s + o.escalations, 0) / total) * 10) / 10,
+    avgCorrections: Math.round((outcomes.reduce((s, o) => s + o.corrections, 0) / total) * 10) / 10,
+    completionRate: Math.round((completed.length / total) * 100),
+    packPerformance,
+    suggestions,
+  };
+}
+
+// ── Weight tuning ─────────────────────────────────────────────────────────────
+
+/**
+ * Compute pack score boosts from successful outcome patterns.
+ * Returns a map of pack → keyword → boost amount.
+ *
+ * Rules:
+ * - Only boost from completed runs with 0 corrections
+ * - Never boost above +2 per keyword
+ * - Never create new keywords — only boost existing ones
+ *
+ * @param {RunOutcome[]} outcomes
+ * @returns {Record<string, number>} packName → boost amount
+ */
+export function computePackBoosts(outcomes) {
+  const boosts = {};
+
+  const cleanRuns = outcomes.filter(
+    o => o.selectedPack && o.completionStatus === "completed" && o.corrections === 0
+  );
+
+  for (const o of cleanRuns) {
+    const pack = o.selectedPack;
+    boosts[pack] = Math.min((boosts[pack] || 0) + 0.5, 2.0);
+  }
+
+  return boosts;
+}
+
+/**
+ * Compute confidence threshold adjustment from outcomes.
+ * If high-confidence suggestions are often overridden, raise the threshold.
+ * If medium-confidence suggestions are often accepted, lower it.
+ *
+ * @param {RunOutcome[]} outcomes
+ * @returns {{ adjustment: number, reason: string }}
+ */
+export function computeConfidenceAdjustment(outcomes) {
+  const highConf = outcomes.filter(o => o.suggestedConfidence === "high");
+  const medConf = outcomes.filter(o => o.suggestedConfidence === "medium");
+
+  const highOverridden = highConf.filter(o => o.operatorOverride).length;
+  const medAccepted = medConf.filter(o => o.selectedPack === o.suggestedPack && !o.operatorOverride).length;
+
+  if (highConf.length >= 3 && highOverridden / highConf.length > 0.3) {
+    return {
+      adjustment: +1,
+      reason: `${Math.round(highOverridden / highConf.length * 100)}% of high-confidence suggestions were overridden. Recommend raising keyword threshold from 3 to 4 for "high."`,
+    };
+  }
+
+  if (medConf.length >= 3 && medAccepted / medConf.length > 0.7) {
+    return {
+      adjustment: -1,
+      reason: `${Math.round(medAccepted / medConf.length * 100)}% of medium-confidence suggestions were accepted. Recommend lowering keyword threshold from 3 to 2 for "high."`,
+    };
+  }
+
+  return { adjustment: 0, reason: "Confidence thresholds are well-calibrated." };
+}
+
+/**
+ * Format a calibration report for display.
+ *
+ * @param {object} report
+ * @returns {string}
+ */
+export function formatCalibrationReport(report) {
+  const lines = [
+    `\nOutcome Calibration Report`,
+    `─────────────────────────`,
+    `Total runs: ${report.totalRuns}`,
+    `Pack usage: ${report.packUsageRate}% | Free routing: ${report.freeRoutingRate}%`,
+    `High-confidence accuracy: ${report.highConfidenceAccuracy}%`,
+    `Operator override rate: ${report.operatorOverrideRate}%`,
+    `Mismatch redirect rate: ${report.mismatchRedirectRate}%`,
+    `Avg escalations: ${report.avgEscalations} | Avg corrections: ${report.avgCorrections}`,
+    `Completion rate: ${report.completionRate}%`,
+  ];
+
+  if (Object.keys(report.packPerformance).length > 0) {
+    lines.push(`\nPer-pack performance:`);
+    for (const [key, p] of Object.entries(report.packPerformance)) {
+      lines.push(`  ${key}: ${p.runs} runs, ${p.completionRate}% completion, ${p.avgChainLength} avg chain, ${p.escalations} escalations`);
+    }
+  }
+
+  if (report.suggestions.length > 0) {
+    lines.push(`\nCalibration suggestions:`);
+    for (const s of report.suggestions) {
+      lines.push(`  ! [${s.type}] ${s.detail}`);
+    }
+  } else {
+    lines.push(`\nNo calibration adjustments needed.`);
+  }
+
+  return lines.join("\n");
+}