role-os 1.6.0 → 1.8.0

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## 1.8.0
+
+### Added
+
+#### Mission Library (Phase S — Mission Hardening)
+- 6 named, repeatable mission types: feature-ship, bugfix, treatment, docs-release, security-hardening, research-launch
+- Each mission declares: pack, role chain, artifact flow, escalation branches, honest-partial definition, stop conditions, dispatch defaults, trial evidence
+- Mission runner: create → step through → complete/fail → generate completion report
+- Completion proof reporter with honest-partial and formatted text output
+- `roleos mission list` — list all missions
+- `roleos mission show <key>` — full mission detail
+- `roleos mission suggest <text>` — signal-based mission suggestion
+- `roleos mission validate [key]` — validate mission wiring against packs/roles
+
+#### Mission Runner Engine
+- `createRun()` — instantiate a mission with tracked steps
+- `startNextStep()` / `completeStep()` / `failStep()` — step lifecycle
+- `recordEscalation()` — re-opens completed steps on escalation loops
+- `getRunPosition()` / `getArtifactChain()` — run introspection
+- `generateCompletionReport()` / `formatCompletionReport()` — honest outcome reporting
+
+### Evidence
+- 465 tests, zero failures (67 new)
+- All 6 missions validate against live pack/role catalog
+- Full lifecycle tests: end-to-end runs, escalation loops, partial completions, failure reporting
+
+## 1.7.0
+
+### Added
+
+#### Completion Proof (Phase R)
+- `roleos artifacts` CLI command: list, show, validate, chain subcommands
+- 13 new CLI integration tests for artifact inspection
+- Real task completion missions through the full stack
+
+#### Completion Proof Evidence
+- R1-1 Feature mission: `roleos artifacts` command shipped through feature pack
+  - Pack: feature (high confidence, correct)
+  - Chain: 5 roles, 0 escalations, 1 minor correction
+  - Artifact contracts: all 4 used and valid
+- R1-2 Bugfix mission: README.zh.md npm anomaly
+  - Diagnosed correctly: npm auto-includes README* regardless of files field
+  - Escalated honestly: fix requires structural decision (translation file organization)
+  - Not force-closed: deferred to treatment pass
+
+### Evidence
+- 398 tests, zero failures
+- 3 missions run through the full stack
+- Completion metrics recorded per mission
+
 ## 1.6.0
 
 ### Added

package/README.md

@@ -192,7 +192,8 @@ Role OS operates **locally only**. It copies markdown templates and writes packe
 - 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. 358 tests.
-- **v1.6.0**: Artifact spine — 20 per-role artifact contracts, 7 pack handoff contracts, structural validation, chain completeness checks. 385 tests.
+- v1.6.0: Artifact spine — 20 per-role artifact contracts, 7 pack handoff contracts, structural validation. 385 tests.
+- **v1.7.0**: Completion proof — real tasks run through the full stack. `roleos artifacts` CLI. Honest escalation on structural fixes. 398 tests.
 
 ## License
 

package/bin/roleos.mjs

@@ -10,6 +10,8 @@ import { reviewCommand } from "../src/review.mjs";
 import { statusCommand } from "../src/status.mjs";
 import { packsCommand } from "../src/packs-cmd.mjs";
 import { scaffoldClaude, doctor, formatDoctor } from "../src/session.mjs";
+import { artifactsCommand } from "../src/artifacts-cmd.mjs";
+import { missionCommand } from "../src/mission-cmd.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const VERSION = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8")).version;
@@ -30,6 +32,14 @@ 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 artifacts                   List all role artifact contracts
+  roleos artifacts show <role>       Show artifact contract for a role
+  roleos artifacts validate <role> <file>  Validate a file against a contract
+  roleos artifacts chain <pack>      Show pack handoff flow
+  roleos mission list                List all missions
+  roleos mission show <key>          Show full mission detail
+  roleos mission suggest <text>      Suggest a mission for a task
+  roleos mission validate [key]      Validate mission wiring
   roleos doctor                      Verify repo is wired for Role OS sessions
   roleos help                        Show this help
 
@@ -103,6 +113,12 @@ try {
     case "packs":
       await packsCommand(args);
       break;
+    case "artifacts":
+      await artifactsCommand(args);
+      break;
+    case "mission":
+      await missionCommand(args);
+      break;
     case "help":
     case "--help":
     case "-h":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "role-os",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "Role OS — a multi-Claude operating system where 31 specialized roles execute work through contracts, conflict detection, escalation, and structured evidence. 7 proven team packs for common task families.",
   "homepage": "https://mcp-tool-shop-org.github.io/role-os/",
   "bugs": {

package/src/artifacts-cmd.mjs

@@ -0,0 +1,180 @@
+/**
+ * CLI surface for artifact contracts — roleos artifacts
+ *
+ * Subcommands:
+ * - artifacts (bare) — list all roles with contracts
+ * - artifacts show <role> — display artifact contract
+ * - artifacts validate <role> <file> — validate file against contract
+ * - artifacts chain <pack> — show pack handoff flow
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import {
+  ROLE_ARTIFACT_CONTRACTS,
+  PACK_HANDOFF_CONTRACTS,
+  validateArtifact,
+  getArtifactContract,
+  getHandoffContract,
+  formatArtifactValidation,
+  formatPackChain,
+  validatePackChain,
+} from "./artifacts.mjs";
+
+/**
+ * Main command handler.
+ * @param {string[]} args
+ */
+export async function artifactsCommand(args) {
+  const sub = args[0];
+
+  if (!sub || sub === "list") {
+    runList();
+  } else if (sub === "show") {
+    runShow(args.slice(1));
+  } else if (sub === "validate") {
+    runValidate(args.slice(1));
+  } else if (sub === "chain") {
+    runChain(args.slice(1));
+  } else {
+    const err = new Error(`Unknown artifacts subcommand: "${sub}"`);
+    err.exitCode = 1;
+    err.hint = "Valid subcommands: list, show <role>, validate <role> <file>, chain <pack>";
+    throw err;
+  }
+}
+
+function runList() {
+  const roles = Object.entries(ROLE_ARTIFACT_CONTRACTS);
+  console.log(`\nRole artifact contracts (${roles.length} roles)\n`);
+  console.log(`${"Role".padEnd(25)} ${"Artifact Type".padEnd(22)} ${"Required".padEnd(8)} Consumed By`);
+  console.log(`${"─".repeat(25)} ${"─".repeat(22)} ${"─".repeat(8)} ${"─".repeat(30)}`);
+
+  for (const [role, contract] of roles) {
+    const consumers = contract.consumedBy.length > 0 ? contract.consumedBy.join(", ") : "terminal";
+    console.log(
+      `${role.padEnd(25)} ${contract.artifactType.padEnd(22)} ${String(contract.requiredSections.length).padEnd(8)} ${consumers}`
+    );
+  }
+}
+
+function runShow(args) {
+  if (args.length === 0) {
+    const err = new Error("Missing role name.");
+    err.exitCode = 1;
+    err.hint = "Usage: roleos artifacts show <role-name>";
+    throw err;
+  }
+
+  const input = args.join(" ");
+  const roleName = resolveRoleName(input);
+  if (!roleName) {
+    const err = new Error(`No artifact contract for role "${input}".`);
+    err.exitCode = 1;
+    err.hint = `Available roles: ${Object.keys(ROLE_ARTIFACT_CONTRACTS).join(", ")}`;
+    throw err;
+  }
+
+  const contract = getArtifactContract(roleName);
+
+  console.log(`\nArtifact Contract — ${roleName}\n`);
+  console.log(`Type: ${contract.artifactType}`);
+  console.log(`Required sections: ${contract.requiredSections.join(", ")}`);
+  if (contract.optionalSections.length > 0) {
+    console.log(`Optional sections: ${contract.optionalSections.join(", ")}`);
+  }
+  if (contract.requiredEvidence.length > 0) {
+    console.log(`Required evidence: ${contract.requiredEvidence.join(", ")}`);
+  }
+  console.log(`Consumed by: ${contract.consumedBy.length > 0 ? contract.consumedBy.join(", ") : "terminal (no downstream consumer)"}`);
+  console.log(`Completion rule: ${contract.completionRule}`);
+}
+
+function runValidate(args) {
+  if (args.length < 2) {
+    const err = new Error("Missing arguments.");
+    err.exitCode = 1;
+    err.hint = "Usage: roleos artifacts validate <role-name> <file-path>";
+    throw err;
+  }
+
+  // Last arg is the file, everything before is the role name
+  const filePath = args[args.length - 1];
+  const roleArgs = args.slice(0, -1);
+  const roleName = resolveRoleName(roleArgs.join(" "));
+
+  if (!roleName) {
+    const err = new Error(`Unknown role: "${roleArgs.join(" ")}".`);
+    err.exitCode = 1;
+    err.hint = `Available roles: ${Object.keys(ROLE_ARTIFACT_CONTRACTS).join(", ")}`;
+    throw err;
+  }
+
+  if (!existsSync(filePath)) {
+    const err = new Error(`File not found: "${filePath}".`);
+    err.exitCode = 1;
+    err.hint = "Provide a path to the artifact file to validate.";
+    throw err;
+  }
+
+  const content = readFileSync(filePath, "utf-8");
+  const validation = validateArtifact(roleName, content);
+  console.log(formatArtifactValidation(roleName, validation));
+
+  if (!validation.valid) {
+    process.exitCode = 1;
+  }
+}
+
+function runChain(args) {
+  const packName = args[0];
+  if (!packName) {
+    const err = new Error("Missing pack name.");
+    err.exitCode = 1;
+    err.hint = `Usage: roleos artifacts chain <pack-name>. Available: ${Object.keys(PACK_HANDOFF_CONTRACTS).join(", ")}`;
+    throw err;
+  }
+
+  const contract = getHandoffContract(packName);
+  if (!contract) {
+    const err = new Error(`No handoff contract for pack "${packName}".`);
+    err.exitCode = 1;
+    err.hint = `Available packs: ${Object.keys(PACK_HANDOFF_CONTRACTS).join(", ")}`;
+    throw err;
+  }
+
+  console.log(`\nHandoff Contract — ${packName} pack\n`);
+  console.log(`${"Step".padEnd(5)} ${"Role".padEnd(25)} ${"Produces".padEnd(22)} Consumed By`);
+  console.log(`${"─".repeat(5)} ${"─".repeat(25)} ${"─".repeat(22)} ${"─".repeat(25)}`);
+
+  contract.flow.forEach((step, i) => {
+    const consumer = step.consumedBy || "terminal";
+    console.log(
+      `${String(i + 1).padEnd(5)} ${step.role.padEnd(25)} ${step.produces.padEnd(22)} ${consumer}`
+    );
+  });
+}
+
+/**
+ * Resolve a role name from user input.
+ * Handles both exact names ("Product Strategist") and slug forms ("product-strategist").
+ */
+function resolveRoleName(input) {
+  if (!input || !input.trim()) return null;
+  const trimmed = input.trim();
+
+  // Exact match
+  if (ROLE_ARTIFACT_CONTRACTS[trimmed]) return trimmed;
+
+  // Case-insensitive match
+  for (const role of Object.keys(ROLE_ARTIFACT_CONTRACTS)) {
+    if (role.toLowerCase() === trimmed.toLowerCase()) return role;
+  }
+
+  // Slug match (product-strategist → Product Strategist)
+  const slugToName = trimmed.replace(/-/g, " ");
+  for (const role of Object.keys(ROLE_ARTIFACT_CONTRACTS)) {
+    if (role.toLowerCase() === slugToName.toLowerCase()) return role;
+  }
+
+  return null;
+}

package/src/mission-cmd.mjs

@@ -0,0 +1,179 @@
+/**
+ * Mission CLI — Phase S (v1.8.0)
+ *
+ * roleos mission list              List all missions
+ * roleos mission show <key>        Show full mission detail
+ * roleos mission suggest <text>    Suggest a mission for a task
+ * roleos mission validate          Validate all missions are properly wired
+ * roleos mission validate <key>    Validate a specific mission
+ */
+
+import {
+  listMissions,
+  getMission,
+  suggestMission,
+  validateMission,
+  validateAllMissions,
+  MISSIONS,
+} from "./mission.mjs";
+
+/**
+ * @param {string[]} args
+ */
+export async function missionCommand(args) {
+  const sub = args[0];
+
+  switch (sub) {
+    case "list":
+      return cmdList();
+    case "show":
+      return cmdShow(args[1]);
+    case "suggest":
+      return cmdSuggest(args.slice(1).join(" "));
+    case "validate":
+      return cmdValidate(args[1]);
+    default: {
+      const err = new Error(
+        `Usage: roleos mission <list|show|suggest|validate>\n` +
+        `  list              List all missions\n` +
+        `  show <key>        Show full mission detail\n` +
+        `  suggest <text>    Suggest a mission for a task description\n` +
+        `  validate [key]    Validate mission wiring`
+      );
+      err.exitCode = 1;
+      err.hint = "Run 'roleos mission list' to see available missions.";
+      throw err;
+    }
+  }
+}
+
+function cmdList() {
+  const missions = listMissions();
+  console.log("\nMission Library\n");
+  console.log("  Key                  Pack        Roles  Description");
+  console.log("  " + "-".repeat(78));
+  for (const m of missions) {
+    const key = m.key.padEnd(20);
+    const pack = m.pack.padEnd(10);
+    const roles = String(m.roleCount).padEnd(6);
+    console.log(`  ${key} ${pack} ${roles} ${m.description}`);
+  }
+  console.log(`\n  ${missions.length} missions. Run 'roleos mission show <key>' for details.\n`);
+}
+
+function cmdShow(key) {
+  if (!key) {
+    const err = new Error("Usage: roleos mission show <key>");
+    err.exitCode = 1;
+    err.hint = `Available: ${Object.keys(MISSIONS).join(", ")}`;
+    throw err;
+  }
+
+  const mission = getMission(key);
+  if (!mission) {
+    const err = new Error(`Mission "${key}" not found`);
+    err.exitCode = 1;
+    err.hint = `Available: ${Object.keys(MISSIONS).join(", ")}`;
+    throw err;
+  }
+
+  console.log(`\n# ${mission.name}`);
+  console.log(`\n${mission.description}`);
+  console.log(`\nPack: ${mission.pack}`);
+  console.log(`Entry: ${mission.entryPath}`);
+
+  console.log("\n## Role Chain");
+  for (let i = 0; i < mission.roleChain.length; i++) {
+    const arrow = i < mission.roleChain.length - 1 ? " →" : "";
+    console.log(`  ${i + 1}. ${mission.roleChain[i]}${arrow}`);
+  }
+
+  console.log("\n## Artifact Flow");
+  for (const step of mission.artifactFlow) {
+    const to = step.consumedBy ? ` → ${step.consumedBy}` : " (terminal)";
+    console.log(`  ${step.role} produces "${step.produces}"${to}`);
+  }
+
+  console.log("\n## Escalation Branches");
+  for (const branch of mission.escalationBranches) {
+    console.log(`  [${branch.trigger}] ${branch.from} → ${branch.to}: ${branch.action}`);
+  }
+
+  console.log("\n## Honest Partial");
+  console.log(`  ${mission.honestPartial}`);
+
+  console.log("\n## Stop Conditions");
+  for (const cond of mission.stopConditions) {
+    console.log(`  - ${cond}`);
+  }
+
+  console.log(`\n## Dispatch Defaults`);
+  const d = mission.dispatchDefaults;
+  console.log(`  Model: ${d.model} | Max turns: ${d.maxTurns} | Budget: $${d.maxBudgetUsd}`);
+
+  if (mission.trialEvidence) {
+    console.log(`\n## Trial Evidence`);
+    console.log(`  ${mission.trialEvidence}`);
+  }
+
+  console.log("");
+}
+
+function cmdSuggest(text) {
+  if (!text) {
+    const err = new Error("Usage: roleos mission suggest <task description>");
+    err.exitCode = 1;
+    err.hint = "Describe what you want to do and I'll suggest a mission.";
+    throw err;
+  }
+
+  const suggestion = suggestMission(text);
+  if (!suggestion) {
+    console.log("\nNo mission matched. Task may need manual routing.\n");
+    console.log("Available missions:");
+    for (const key of Object.keys(MISSIONS)) {
+      console.log(`  - ${key}: ${MISSIONS[key].description}`);
+    }
+    console.log("");
+    return;
+  }
+
+  const mission = getMission(suggestion.mission);
+  console.log(`\nSuggested mission: ${suggestion.mission}`);
+  console.log(`Name: ${mission.name}`);
+  console.log(`Confidence: ${suggestion.confidence}`);
+  console.log(`Reason: ${suggestion.reason}`);
+  console.log(`Pack: ${mission.pack}`);
+  console.log(`Chain: ${mission.roleChain.join(" → ")}`);
+  console.log(`\nRun 'roleos mission show ${suggestion.mission}' for full details.\n`);
+}
+
+function cmdValidate(key) {
+  if (key) {
+    const result = validateMission(key);
+    if (result.valid) {
+      console.log(`\n[PASS] Mission "${key}" is properly wired.\n`);
+    } else {
+      console.log(`\n[FAIL] Mission "${key}" has issues:`);
+      for (const issue of result.issues) {
+        console.log(`  - ${issue}`);
+      }
+      console.log("");
+      process.exit(1);
+    }
+  } else {
+    const { allValid, results } = validateAllMissions();
+    console.log("\nMission Validation\n");
+    for (const [k, r] of Object.entries(results)) {
+      const icon = r.valid ? "[PASS]" : "[FAIL]";
+      console.log(`  ${icon} ${k}`);
+      if (!r.valid) {
+        for (const issue of r.issues) {
+          console.log(`         - ${issue}`);
+        }
+      }
+    }
+    console.log(`\n  ${Object.keys(results).length} missions checked. ${allValid ? "All valid." : "Some issues found."}\n`);
+    if (!allValid) process.exit(1);
+  }
+}

package/src/mission-run.mjs

@@ -0,0 +1,380 @@
+/**
+ * Mission Runner — Phase S (v1.8.0)
+ *
+ * Executes a mission through the full Role OS stack:
+ *   mission → packet → route → pack → artifacts → review → completion report
+ *
+ * The runner does NOT execute code — it orchestrates the contract chain
+ * and tracks state so that operators (human or agent) know exactly
+ * where they are, what's been produced, and what's next.
+ */
+
+import { MISSIONS, getMission, validateMission } from "./mission.mjs";
+import { TEAM_PACKS } from "./packs.mjs";
+import { validateArtifact, ROLE_ARTIFACT_CONTRACTS } from "./artifacts.mjs";
+
+let _runCounter = 0;
+
+// ── Run states ──────────────────────────────────────────────────────────────
+
+/**
+ * @typedef {"pending"|"active"|"completed"|"partial"|"failed"|"escalated"} StepStatus
+ */
+
+/**
+ * @typedef {Object} MissionStep
+ * @property {string} role
+ * @property {string} produces - artifact type
+ * @property {string|null} consumedBy - next role or null
+ * @property {StepStatus} status
+ * @property {string|null} artifact - produced artifact content/reference
+ * @property {string|null} note - operator note
+ * @property {string|null} startedAt
+ * @property {string|null} completedAt
+ */
+
+/**
+ * @typedef {"planning"|"running"|"completed"|"partial"|"failed"} RunStatus
+ */
+
+/**
+ * @typedef {Object} MissionRun
+ * @property {string} id
+ * @property {string} missionKey
+ * @property {string} taskDescription
+ * @property {RunStatus} status
+ * @property {MissionStep[]} steps
+ * @property {Array<{from: string, to: string, trigger: string, action: string, timestamp: string}>} escalations
+ * @property {string} startedAt
+ * @property {string|null} completedAt
+ * @property {object|null} completionReport
+ */
+
+// ── Create a run ────────────────────────────────────────────────────────────
+
+/**
+ * Create a new mission run from a mission key and task description.
+ *
+ * @param {string} missionKey
+ * @param {string} taskDescription
+ * @returns {MissionRun}
+ */
+export function createRun(missionKey, taskDescription) {
+  const mission = getMission(missionKey);
+  if (!mission) {
+    throw new Error(`Mission "${missionKey}" not found. Available: ${Object.keys(MISSIONS).join(", ")}`);
+  }
+
+  const validation = validateMission(missionKey);
+  if (!validation.valid) {
+    throw new Error(`Mission "${missionKey}" has issues: ${validation.issues.join("; ")}`);
+  }
+
+  const id = `${missionKey}-${Date.now()}-${++_runCounter}`;
+
+  const steps = mission.artifactFlow.map((step) => ({
+    role: step.role,
+    produces: step.produces,
+    consumedBy: step.consumedBy,
+    status: "pending",
+    artifact: null,
+    note: null,
+    startedAt: null,
+    completedAt: null,
+  }));
+
+  return {
+    id,
+    missionKey,
+    taskDescription,
+    status: "planning",
+    steps,
+    escalations: [],
+    startedAt: new Date().toISOString(),
+    completedAt: null,
+    completionReport: null,
+  };
+}
+
+// ── Step through a run ──────────────────────────────────────────────────────
+
+/**
+ * Start the next pending step.
+ * @param {MissionRun} run
+ * @returns {MissionStep|null} The started step, or null if no pending steps
+ */
+export function startNextStep(run) {
+  const next = run.steps.find((s) => s.status === "pending");
+  if (!next) return null;
+
+  next.status = "active";
+  next.startedAt = new Date().toISOString();
+  run.status = "running";
+
+  return next;
+}
+
+/**
+ * Complete the current active step with an artifact.
+ * @param {MissionRun} run
+ * @param {string} artifact - The produced artifact (content or reference)
+ * @param {string} [note] - Optional operator note
+ * @returns {MissionStep}
+ */
+export function completeStep(run, artifact, note) {
+  const active = run.steps.find((s) => s.status === "active");
+  if (!active) {
+    throw new Error("No active step to complete");
+  }
+
+  active.status = "completed";
+  active.artifact = artifact;
+  active.note = note || null;
+  active.completedAt = new Date().toISOString();
+
+  // Check if all steps are done
+  const allDone = run.steps.every((s) => s.status === "completed");
+  if (allDone) {
+    run.status = "completed";
+    run.completedAt = new Date().toISOString();
+  }
+
+  return active;
+}
+
+/**
+ * Mark the current active step as failed/partial.
+ * @param {MissionRun} run
+ * @param {"partial"|"failed"} status
+ * @param {string} reason
+ * @returns {MissionStep}
+ */
+export function failStep(run, status, reason) {
+  if (status !== "partial" && status !== "failed") {
+    throw new Error(`Invalid fail status: "${status}". Use "partial" or "failed"`);
+  }
+
+  const active = run.steps.find((s) => s.status === "active");
+  if (!active) {
+    throw new Error("No active step to fail");
+  }
+
+  active.status = status;
+  active.note = reason;
+  active.completedAt = new Date().toISOString();
+
+  // Block all downstream pending steps (S2-F2)
+  let foundActive = false;
+  for (const step of run.steps) {
+    if (step === active) { foundActive = true; continue; }
+    if (foundActive && step.status === "pending") {
+      step.status = "blocked";
+      step.note = `Blocked: upstream ${active.role} ${status}`;
+    }
+  }
+
+  // Mission status follows the worst step
+  run.status = status;
+  run.completedAt = new Date().toISOString();
+
+  return active;
+}
+
+/**
+ * Record an escalation during a run.
+ * @param {MissionRun} run
+ * @param {string} from - Role escalating
+ * @param {string} to - Role receiving
+ * @param {string} trigger - What triggered it
+ * @param {string} action - What needs to happen
+ * @returns {{from: string, to: string, trigger: string, action: string, timestamp: string, reopened: boolean, warning: string|null}}
+ */
+export function recordEscalation(run, from, to, trigger, action) {
+  const escalation = {
+    from,
+    to,
+    trigger,
+    action,
+    timestamp: new Date().toISOString(),
+    reopened: false,
+    warning: null,
+  };
+  run.escalations.push(escalation);
+
+  // S5-F1: Find the LAST matching step for the target role, not the first.
+  // Security-hardening has Security Reviewer twice — escalation should target
+  // the latest occurrence (re-audit), not the initial audit.
+  let targetStep = null;
+  for (let i = run.steps.length - 1; i >= 0; i--) {
+    if (run.steps[i].role === to && run.steps[i].status === "completed") {
+      targetStep = run.steps[i];
+      break;
+    }
+  }
+
+  if (targetStep) {
+    targetStep.status = "pending";
+    targetStep.artifact = null;
+    targetStep.note = `Re-opened by escalation: ${trigger}`;
+    targetStep.completedAt = null;
+    escalation.reopened = true;
+  } else {
+    // S4-F2: Target role not found in chain (or no completed step to re-open).
+    // Warn the operator instead of silently doing nothing.
+    const inChain = run.steps.some((s) => s.role === to);
+    if (!inChain) {
+      escalation.warning = `Role "${to}" is not in this mission's step chain. Escalation recorded but no step re-opened.`;
+    } else {
+      escalation.warning = `Role "${to}" has no completed step to re-open. Escalation recorded.`;
+    }
+  }
+
+  return escalation;
+}
+
+// ── Run introspection ───────────────────────────────────────────────────────
+
+/**
+ * Get the current position in a run.
+ * @param {MissionRun} run
+ * @returns {{currentStep: MissionStep|null, completedCount: number, totalSteps: number, progress: string}}
+ */
+export function getRunPosition(run) {
+  const active = run.steps.find((s) => s.status === "active");
+  const completedCount = run.steps.filter((s) => s.status === "completed").length;
+  const totalSteps = run.steps.length;
+
+  return {
+    currentStep: active || null,
+    completedCount,
+    totalSteps,
+    progress: `${completedCount}/${totalSteps}`,
+  };
+}
+
+/**
+ * Get the artifact chain produced so far.
+ * @param {MissionRun} run
+ * @returns {Array<{role: string, type: string, artifact: string}>}
+ */
+export function getArtifactChain(run) {
+  return run.steps
+    .filter((s) => s.status === "completed" && s.artifact)
+    .map((s) => ({
+      role: s.role,
+      type: s.produces,
+      artifact: s.artifact,
+    }));
+}
+
+// ── Completion report ───────────────────────────────────────────────────────
+
+/**
+ * Generate a completion report for a finished (or partially finished) run.
+ * This is the "honest partial" — it tells you exactly what happened,
+ * not what you hoped would happen.
+ *
+ * @param {MissionRun} run
+ * @returns {object} Completion report
+ */
+export function generateCompletionReport(run) {
+  const mission = getMission(run.missionKey);
+  const position = getRunPosition(run);
+  const artifactChain = getArtifactChain(run);
+
+  const stepSummaries = run.steps.map((s) => ({
+    role: s.role,
+    produces: s.produces,
+    status: s.status,
+    hasArtifact: !!s.artifact,
+    note: s.note,
+  }));
+
+  const isComplete = run.status === "completed";
+  const isPartial = run.status === "partial";
+  const isFailed = run.status === "failed";
+
+  const report = {
+    missionKey: run.missionKey,
+    missionName: mission.name,
+    taskDescription: run.taskDescription,
+    outcome: run.status,
+    progress: position.progress,
+    startedAt: run.startedAt,
+    completedAt: run.completedAt,
+    durationMs: run.completedAt
+      ? new Date(run.completedAt) - new Date(run.startedAt)
+      : null,
+    steps: stepSummaries,
+    artifactsProduced: artifactChain.length,
+    artifactChain,
+    escalationCount: run.escalations.length,
+    escalations: run.escalations,
+    honestPartial: isPartial || isFailed ? mission.honestPartial : null,
+    verdict: isComplete
+      ? "Mission completed — all artifacts produced, all steps passed."
+      : isPartial
+        ? `Mission partially completed (${position.progress}). ${mission.honestPartial}`
+        : isFailed
+          ? `Mission failed at step ${position.completedCount + 1}/${position.totalSteps} (${run.steps.find((s) => s.status === "failed")?.role || "unknown"}).`
+          : `Mission still running (${position.progress}).`,
+  };
+
+  // Attach to run
+  run.completionReport = report;
+
+  return report;
+}
+
+/**
+ * Format a completion report as human-readable text.
+ * @param {object} report
+ * @returns {string}
+ */
+export function formatCompletionReport(report) {
+  const lines = [];
+
+  lines.push(`# Mission Report: ${report.missionName}`);
+  lines.push("");
+  lines.push(`**Task:** ${report.taskDescription}`);
+  lines.push(`**Outcome:** ${report.outcome.toUpperCase()}`);
+  lines.push(`**Progress:** ${report.progress}`);
+
+  if (report.durationMs) {
+    const seconds = Math.round(report.durationMs / 1000);
+    lines.push(`**Duration:** ${seconds}s`);
+  }
+
+  lines.push("");
+  lines.push("## Steps");
+  for (const step of report.steps) {
+    const icon = step.status === "completed" ? "[x]" :
+                 step.status === "active" ? "[>]" :
+                 step.status === "partial" ? "[~]" :
+                 step.status === "failed" ? "[!]" :
+                 step.status === "blocked" ? "[-]" : "[ ]";
+    const artifact = step.hasArtifact ? ` → ${step.produces}` : "";
+    const note = step.note ? ` (${step.note})` : "";
+    lines.push(`  ${icon} ${step.role}${artifact}${note}`);
+  }
+
+  if (report.escalationCount > 0) {
+    lines.push("");
+    lines.push("## Escalations");
+    for (const esc of report.escalations) {
+      lines.push(`  - ${esc.from} → ${esc.to}: ${esc.trigger} → ${esc.action}`);
+    }
+  }
+
+  if (report.honestPartial) {
+    lines.push("");
+    lines.push("## Honest Partial");
+    lines.push(report.honestPartial);
+  }
+
+  lines.push("");
+  lines.push("## Verdict");
+  lines.push(report.verdict);
+
+  return lines.join("\n");
+}

package/src/mission.mjs

@@ -0,0 +1,388 @@
+/**
+ * Mission Library — Phase S (v1.8.0)
+ *
+ * Named, repeatable job types that make recurring work boringly reliable.
+ * Each mission declares:
+ * - Default pack and role chain
+ * - Expected artifact flow
+ * - Common escalation branches
+ * - What "honest partial" looks like
+ * - Entry conditions and stop conditions
+ *
+ * Missions are NOT new abstractions — they are proven patterns
+ * extracted from real execution (trials G1–G10, pack comparisons,
+ * completion proof arc).
+ */
+
+import { TEAM_PACKS } from "./packs.mjs";
+import { ROLE_ARTIFACT_CONTRACTS } from "./artifacts.mjs";
+import { ROLE_CATALOG } from "./route.mjs";
+
+// ── Mission definitions ─────────────────────────────────────────────────────
+
+export const MISSIONS = {
+  // ── Feature Shipment ────────────────────────────────────────────────────
+  "feature-ship": {
+    name: "Feature Shipment",
+    description: "Scope, spec, implement, test, and review a new feature end-to-end.",
+    pack: "feature",
+    entryPath: "Product Strategist frames scope → Spec Writer writes spec → implementation → test → review",
+    roleChain: [
+      "Product Strategist",
+      "Spec Writer",
+      "Backend Engineer",
+      "Test Engineer",
+      "Critic Reviewer",
+    ],
+    artifactFlow: [
+      { role: "Product Strategist", produces: "strategy-brief", consumedBy: "Spec Writer" },
+      { role: "Spec Writer", produces: "implementation-spec", consumedBy: "Backend Engineer" },
+      { role: "Backend Engineer", produces: "change-plan", consumedBy: "Test Engineer" },
+      { role: "Test Engineer", produces: "test-report", consumedBy: "Critic Reviewer" },
+      { role: "Critic Reviewer", produces: "review-verdict", consumedBy: null },
+    ],
+    escalationBranches: [
+      { trigger: "scope ambiguity", from: "Spec Writer", to: "Product Strategist", action: "clarify scope before proceeding" },
+      { trigger: "untestable spec", from: "Test Engineer", to: "Spec Writer", action: "revise interface spec for testability" },
+      { trigger: "review rejection", from: "Critic Reviewer", to: "Backend Engineer", action: "address findings, re-test, re-review" },
+    ],
+    honestPartial: "Scope + spec complete but implementation blocked. Artifact chain intact up to the blocking point. Handoff includes what was tried and why it stalled.",
+    stopConditions: [
+      "Critic Reviewer accepts",
+      "Escalation exhausts retry budget (3 loops max)",
+      "Scope change invalidates the mission — replan required",
+    ],
+    dispatchDefaults: { model: "sonnet", maxTurns: 30, maxBudgetUsd: 5.0 },
+    trialEvidence: "G1, G2 — 6/6 gold passes. Pack comparison: wins vs free routing.",
+  },
+
+  // ── Bugfix / Diagnosis ──────────────────────────────────────────────────
+  "bugfix": {
+    name: "Bugfix & Diagnosis",
+    description: "Diagnose root cause, fix, test, and verify a bug or regression.",
+    pack: "bugfix",
+    entryPath: "Repo Researcher diagnoses root cause → Backend Engineer fixes → Test Engineer verifies → Critic reviews",
+    roleChain: [
+      "Repo Researcher",
+      "Backend Engineer",
+      "Test Engineer",
+      "Critic Reviewer",
+    ],
+    artifactFlow: [
+      { role: "Repo Researcher", produces: "diagnosis-report", consumedBy: "Backend Engineer" },
+      { role: "Backend Engineer", produces: "change-plan", consumedBy: "Test Engineer" },
+      { role: "Test Engineer", produces: "test-report", consumedBy: "Critic Reviewer" },
+      { role: "Critic Reviewer", produces: "review-verdict", consumedBy: null },
+    ],
+    escalationBranches: [
+      { trigger: "root cause unclear", from: "Repo Researcher", to: "Repo Researcher", action: "gather more evidence, add reproduction steps" },
+      { trigger: "fix introduces regression", from: "Test Engineer", to: "Backend Engineer", action: "revise fix approach" },
+      { trigger: "diagnosis was wrong", from: "Backend Engineer", to: "Repo Researcher", action: "re-diagnose with new evidence from attempted fix" },
+    ],
+    honestPartial: "Root cause identified and documented but fix is non-trivial. Diagnosis report artifact is complete. Handoff includes attempted approaches and why they failed.",
+    stopConditions: [
+      "Critic Reviewer accepts fix",
+      "Root cause confirmed but fix requires scope expansion — replan as feature-ship",
+      "Bug is not reproducible — document findings and close",
+    ],
+    dispatchDefaults: { model: "sonnet", maxTurns: 20, maxBudgetUsd: 3.0 },
+    trialEvidence: "G3, G4 — 4/4 gold passes. Honest partial validated in R1-2 (README anomaly).",
+  },
+
+  // ── Treatment (Repo Polish) ─────────────────────────────────────────────
+  "treatment": {
+    name: "Treatment (Repo Polish)",
+    description: "Full treatment: shipcheck gates, polish, docs, translations, version bump, publish.",
+    pack: "treatment",
+    entryPath: "Shipcheck gates first → Security Reviewer audits → Docs Architect updates → Deployment Verifier verifies CI → Critic reviews",
+    roleChain: [
+      "Security Reviewer",
+      "Docs Architect",
+      "Deployment Verifier",
+      "Critic Reviewer",
+    ],
+    artifactFlow: [
+      { role: "Security Reviewer", produces: "security-audit", consumedBy: "Docs Architect" },
+      { role: "Docs Architect", produces: "docs-update", consumedBy: "Deployment Verifier" },
+      { role: "Deployment Verifier", produces: "ci-verification", consumedBy: "Critic Reviewer" },
+      { role: "Critic Reviewer", produces: "review-verdict", consumedBy: null },
+    ],
+    escalationBranches: [
+      { trigger: "security gate fails", from: "Security Reviewer", to: "Backend Engineer", action: "fix security issue before treatment continues" },
+      { trigger: "CI fails after changes", from: "Deployment Verifier", to: "Backend Engineer", action: "fix CI, re-verify" },
+      { trigger: "shipcheck hard gate blocks", from: "Critic Reviewer", to: "Security Reviewer", action: "address blocking gate, restart treatment" },
+    ],
+    honestPartial: "Shipcheck passed but polish incomplete. Security and docs artifacts exist. Remaining items documented in handoff.",
+    stopConditions: [
+      "All shipcheck hard gates pass + Critic accepts",
+      "Security gate A blocks — must fix before continuing",
+      "Scope expands to feature work — decompose into treatment + feature-ship",
+    ],
+    dispatchDefaults: { model: "sonnet", maxTurns: 25, maxBudgetUsd: 4.0 },
+    trialEvidence: "G5, G6 — treatment pack proven. Completion proof arc validated honest partial.",
+  },
+
+  // ── Docs / Release ──────────────────────────────────────────────────────
+  "docs-release": {
+    name: "Docs & Release",
+    description: "Write or update documentation, prepare release notes, publish.",
+    pack: "docs",
+    entryPath: "Docs Architect synthesizes upstream → writes docs → Critic reviews completeness",
+    roleChain: [
+      "Docs Architect",
+      "Critic Reviewer",
+    ],
+    artifactFlow: [
+      { role: "Docs Architect", produces: "docs-update", consumedBy: "Critic Reviewer" },
+      { role: "Critic Reviewer", produces: "review-verdict", consumedBy: null },
+    ],
+    escalationBranches: [
+      { trigger: "upstream source missing", from: "Docs Architect", to: "Product Strategist", action: "clarify what changed and why" },
+      { trigger: "docs conflict with code", from: "Critic Reviewer", to: "Docs Architect", action: "reconcile docs with actual implementation" },
+    ],
+    honestPartial: "Core docs updated but supplementary pages (handbook, translations) pending. Main artifact complete.",
+    stopConditions: [
+      "Critic accepts docs as accurate and complete",
+      "Upstream changes still in flight — park docs until code stabilizes",
+    ],
+    dispatchDefaults: { model: "sonnet", maxTurns: 15, maxBudgetUsd: 2.0 },
+    trialEvidence: "G7, G8 — docs pack proven. Upstream-synthesis gate prevents stale docs.",
+  },
+
+  // ── Security Hardening ──────────────────────────────────────────────────
+  "security-hardening": {
+    name: "Security Hardening",
+    description: "Threat model, audit, fix vulnerabilities, verify gates.",
+    pack: "security",
+    entryPath: "Security Reviewer threat-models → identifies issues → Backend Engineer fixes → re-audit",
+    roleChain: [
+      "Security Reviewer",
+      "Backend Engineer",
+      "Test Engineer",
+      "Critic Reviewer",
+    ],
+    artifactFlow: [
+      { role: "Security Reviewer", produces: "security-audit", consumedBy: "Backend Engineer" },
+      { role: "Backend Engineer", produces: "change-plan", consumedBy: "Test Engineer" },
+      { role: "Test Engineer", produces: "test-report", consumedBy: "Security Reviewer" },
+      { role: "Security Reviewer", produces: "security-audit", consumedBy: "Critic Reviewer" },
+      { role: "Critic Reviewer", produces: "review-verdict", consumedBy: null },
+    ],
+    escalationBranches: [
+      { trigger: "critical vulnerability found", from: "Security Reviewer", to: "Backend Engineer", action: "immediate fix, skip non-critical work" },
+      { trigger: "fix breaks functionality", from: "Test Engineer", to: "Backend Engineer", action: "find fix that preserves both security and function" },
+      { trigger: "threat model scope expands", from: "Security Reviewer", to: "Product Strategist", action: "reframe scope — is this a feature-ship or security mission?" },
+    ],
+    honestPartial: "Threat model complete, critical issues fixed, non-critical items documented as backlog. Audit artifact reflects actual state.",
+    stopConditions: [
+      "All critical findings fixed + Critic accepts",
+      "No critical findings — document clean audit",
+      "Scope expands beyond security — decompose into security + feature-ship",
+    ],
+    dispatchDefaults: { model: "sonnet", maxTurns: 25, maxBudgetUsd: 4.0 },
+    trialEvidence: "G9, G10 — security pack proven. Treatment includes Security Reviewer by default.",
+  },
+
+  // ── Research → Framing → Launch ─────────────────────────────────────────
+  "research-launch": {
+    name: "Research → Framing → Launch",
+    description: "Investigate a question, frame findings into a decision, prepare launch artifacts.",
+    pack: "research",
+    entryPath: "Product Strategist frames question → Competitive Analyst investigates → findings → launch decision",
+    roleChain: [
+      "Product Strategist",
+      "Competitive Analyst",
+      "Docs Architect",
+      "Critic Reviewer",
+    ],
+    artifactFlow: [
+      { role: "Product Strategist", produces: "strategy-brief", consumedBy: "Competitive Analyst" },
+      { role: "Competitive Analyst", produces: "research-findings", consumedBy: "Product Strategist" },
+      { role: "Docs Architect", produces: "docs-update", consumedBy: "Critic Reviewer" },
+      { role: "Critic Reviewer", produces: "review-verdict", consumedBy: null },
+    ],
+    escalationBranches: [
+      { trigger: "research inconclusive", from: "Competitive Analyst", to: "Product Strategist", action: "narrow the question or accept uncertainty" },
+      { trigger: "findings contradict assumption", from: "Competitive Analyst", to: "Product Strategist", action: "reframe strategy based on evidence" },
+      { trigger: "launch blocked by findings", from: "Critic Reviewer", to: "Product Strategist", action: "decide: proceed with caveats or pivot" },
+    ],
+    honestPartial: "Research complete with findings documented. Launch decision pending stakeholder input. Research artifact is self-contained.",
+    stopConditions: [
+      "Critic accepts research findings and launch plan",
+      "Research reveals the question is wrong — reframe mission",
+      "Findings are clear but launch is premature — park with documented rationale",
+    ],
+    dispatchDefaults: { model: "sonnet", maxTurns: 20, maxBudgetUsd: 3.0 },
+    trialEvidence: "Research pack opens with Product Strategist (framing before research). Validated in pack comparison.",
+  },
+};
+
+// ── Mission catalog ─────────────────────────────────────────────────────────
+
+/**
+ * List all missions with summary info.
+ * @returns {Array<{key: string, name: string, description: string, pack: string, roleCount: number}>}
+ */
+export function listMissions() {
+  return Object.entries(MISSIONS).map(([key, m]) => ({
+    key,
+    name: m.name,
+    description: m.description,
+    pack: m.pack,
+    roleCount: m.roleChain.length,
+  }));
+}
+
+/**
+ * Get a mission by key.
+ * @param {string} key
+ * @returns {object|null}
+ */
+export function getMission(key) {
+  return MISSIONS[key] || null;
+}
+
+/**
+ * Suggest a mission for a task description (signal matching).
+ * @param {string} taskDescription
+ * @returns {{mission: string, confidence: "high"|"medium"|"low", reason: string}|null}
+ */
+export function suggestMission(taskDescription) {
+  const text = taskDescription.toLowerCase();
+
+  const MISSION_SIGNALS = {
+    "feature-ship": {
+      signals: ["add feature", "implement", "build", "create", "new command", "ship feature", "develop", "add command", "new feature", "add support"],
+      weight: 1,
+    },
+    "bugfix": {
+      signals: ["fix", "bug", "crash", "broken", "regression", "repair", "diagnose", "not working"],
+      weight: 1,
+    },
+    "treatment": {
+      signals: ["treatment", "polish", "shipcheck", "pre-release", "ship-ready", "cleanup", "housekeeping"],
+      weight: 1.2, // slightly prefer treatment when signals match (common task)
+    },
+    "docs-release": {
+      signals: ["documentation", "docs", "readme", "release notes", "changelog", "handbook", "write docs"],
+      weight: 1,
+    },
+    "security-hardening": {
+      signals: ["security", "vulnerability", "threat model", "audit", "CVE", "injection", "hardening"],
+      weight: 1.1,
+    },
+    "research-launch": {
+      signals: ["research", "investigate", "should we", "evaluate", "competitive", "launch plan", "strategy"],
+      weight: 1,
+    },
+  };
+
+  let bestKey = null;
+  let bestScore = 0;
+
+  for (const [key, def] of Object.entries(MISSION_SIGNALS)) {
+    let hits = 0;
+    for (const signal of def.signals) {
+      if (text.includes(signal)) hits++;
+    }
+    const score = hits * def.weight;
+    if (score > bestScore) {
+      bestScore = score;
+      bestKey = key;
+    }
+  }
+
+  if (!bestKey || bestScore === 0) return null;
+
+  const confidence = bestScore >= 3 ? "high" : bestScore >= 1.5 ? "medium" : "low";
+  const mission = MISSIONS[bestKey];
+
+  return {
+    mission: bestKey,
+    confidence,
+    reason: `Matched ${Math.floor(bestScore)} signal(s) for "${mission.name}"`,
+  };
+}
+
+// ── Mission validation ──────────────────────────────────────────────────────
+
+/**
+ * Validate that a mission's pack and roles are properly wired.
+ * @param {string} key
+ * @returns {{valid: boolean, issues: string[]}}
+ */
+export function validateMission(key) {
+  const mission = MISSIONS[key];
+  if (!mission) return { valid: false, issues: [`Mission "${key}" not found`] };
+
+  const issues = [];
+
+  // Check pack exists
+  if (!TEAM_PACKS[mission.pack]) {
+    issues.push(`Pack "${mission.pack}" not found in TEAM_PACKS`);
+  }
+
+  // S6-F1: Check all role names exist in ROLE_CATALOG
+  const catalogNames = new Set(ROLE_CATALOG.map((r) => r.name));
+  for (const roleName of mission.roleChain) {
+    if (!catalogNames.has(roleName)) {
+      issues.push(`Role "${roleName}" in roleChain not found in ROLE_CATALOG`);
+    }
+  }
+  for (const step of mission.artifactFlow) {
+    if (!catalogNames.has(step.role)) {
+      issues.push(`Role "${step.role}" in artifactFlow not found in ROLE_CATALOG`);
+    }
+  }
+
+  // Check artifact contracts exist for producing roles
+  for (const step of mission.artifactFlow) {
+    if (ROLE_ARTIFACT_CONTRACTS[step.role]) {
+      // Contract exists — good
+    }
+    // Not all roles need contracts (only chain-critical ones), so missing is a warning not error
+  }
+
+  // Check artifact flow continuity (each consumed artifact should be produced upstream)
+  const produced = new Set();
+  for (const step of mission.artifactFlow) {
+    produced.add(step.produces);
+  }
+
+  // Check escalation branches reference roles in the chain or known roles
+  for (const branch of mission.escalationBranches) {
+    if (!mission.roleChain.includes(branch.from) && branch.from !== branch.to) {
+      // from role should be in chain or self-referencing
+      issues.push(`Escalation "from" role "${branch.from}" not in role chain`);
+    }
+  }
+
+  // Check stop conditions exist
+  if (!mission.stopConditions || mission.stopConditions.length === 0) {
+    issues.push("Mission has no stop conditions");
+  }
+
+  // Check honest partial exists
+  if (!mission.honestPartial) {
+    issues.push("Mission has no honest-partial definition");
+  }
+
+  return { valid: issues.length === 0, issues };
+}
+
+/**
+ * Validate ALL missions.
+ * @returns {{allValid: boolean, results: Record<string, {valid: boolean, issues: string[]}>}}
+ */
+export function validateAllMissions() {
+  const results = {};
+  let allValid = true;
+
+  for (const key of Object.keys(MISSIONS)) {
+    const result = validateMission(key);
+    results[key] = result;
+    if (!result.valid) allValid = false;
+  }
+
+  return { allValid, results };
+}