role-os 2.8.0 → 2.9.1

package/src/hooks.mjs

@@ -95,11 +95,7 @@ const SESSION_STATE_FILE = ".claude/hooks/session-state.json";
  */
 export function getSessionState(cwd) {
   const path = join(cwd, SESSION_STATE_FILE);
-  if (existsSync(path)) {
-    try { return JSON.parse(readFileSync(path, "utf-8")); }
-    catch { /* fall through */ }
-  }
-  return {
+  const defaults = {
     sessionId: null,
     routeCardPresent: false,
     activeRole: null,
@@ -110,6 +106,18 @@ export function getSessionState(cwd) {
     outcomeRecorded: false,
     startedAt: null,
   };
+  if (existsSync(path)) {
+    try {
+      const parsed = JSON.parse(readFileSync(path, "utf-8"));
+      // Merge over the default shape: a PARTIAL state file (e.g. created from {} by the generated
+      // prompt-submit script when SessionStart never ran) must not crash the library hook functions
+      // — the generated scripts guard field-by-field; the library tolerates the same files.
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        return { ...defaults, ...parsed };
+      }
+    } catch { /* fall through */ }
+  }
+  return defaults;
 }
 
 /**
@@ -450,20 +458,93 @@ process.exit(0);
 
 function generatePreToolUseScript() {
   return `#!/usr/bin/env node
-// Role OS PreToolUse hook — enforce role-specific tool law + Tool-Call Conformance floor (advisory)
+// Role OS PreToolUse hook — role tool law + capability gate (fail-closed) + conformance floor (advisory).
+// SELF-CONTAINED: stdlib-only. A bare role-os import specifier resolves in NO npx/global-install
+// consumer repo (the package has no "exports" self-reference), so the fail-closed gate logic is
+// INLINED below — a security control must never depend on a best-effort import. Internal failures
+// warn on stderr (once per repo, marker-file throttled); they are never a silent catch.
 import { readFileSync, writeFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
+import { pathToFileURL } from "node:url";
 
 const input = JSON.parse(readFileSync(0, "utf-8").toString() || "{}");
 const cwd = input.cwd || process.cwd();
 const statePath = join(cwd, ".claude", "hooks", "session-state.json");
+const toolName = input.tool_name || "";
+
+// One-time stderr warning: degraded hook behavior must be VISIBLE, but must not spam every call.
+function warnOnce(key, message) {
+  let line = "[role-os hook] " + message;
+  try {
+    const marker = join(cwd, ".claude", "hooks", "." + key + ".warned");
+    if (existsSync(marker)) return; // already surfaced in this repo
+    writeFileSync(marker, new Date().toISOString() + " " + message + "\\n");
+  } catch (err) {
+    line += " (warn-marker write failed: " + err.message + ")";
+  }
+  process.stderr.write(line + "\\n");
+}
+
+// ── Capability gate (opt-in via ROLEOS_CAPABILITY_GATE, FAIL-CLOSED) ─────────────────────────────
+// Inlined gated set + grant law — keep in sync with src/specialist/capability-gate.mjs in the
+// role-os repo. A gated irreversible action (NAMED_COMPENSATORS list) with no matching grant in
+// .claude/role-os/capabilities.json is DENIED (exit 2 blocks). Default OFF => pure no-op. The
+// patterns allow flags between command word and verb without crossing a shell separator; an
+// unparseable "expires" DENIES (a typo'd date must never become a permanent grant).
+const gateEnabled = process.env.ROLEOS_CAPABILITY_GATE === "1" || process.env.ROLEOS_CAPABILITY_GATE === "true";
+if (gateEnabled && toolName === "Bash") {
+  const command = (input.tool_input && typeof input.tool_input.command === "string") ? input.tool_input.command : "";
+  const GATED = [
+    { id: "npm:publish", label: "npm/pnpm/yarn publish", re: /\\b(?:npm|pnpm|yarn)\\b[^|;&\\n]*\\bpublish\\b/ },
+    { id: "pypi:publish", label: "PyPI publish (twine/uv)", re: /\\btwine\\b[^|;&\\n]*\\bupload\\b|\\buv\\b[^|;&\\n]*\\bpublish\\b/ },
+    { id: "gh:release", label: "gh release create", re: /\\bgh\\b[^|;&\\n]*\\brelease\\b[^|;&\\n]*\\bcreate\\b/ },
+    { id: "gh:pr-create", label: "gh pr create", re: /\\bgh\\b[^|;&\\n]*\\bpr\\b[^|;&\\n]*\\bcreate\\b/ },
+    { id: "gh:repo-edit", label: "gh repo edit/delete", re: /\\bgh\\b[^|;&\\n]*\\brepo\\b[^|;&\\n]*\\b(?:edit|delete)\\b/ },
+    { id: "git:push", label: "git push", re: /\\bgit\\b[^|;&\\n]*\\bpush\\b/ },
+    { id: "pages:deploy", label: "GitHub Pages / gh-pages deploy", re: /\\bgh-pages\\b|\\bpages\\b[^|;&\\n]*\\bdeploy\\b/ },
+  ];
+  const action = command ? GATED.find((a) => a.re.test(command)) : undefined;
+  if (action) {
+    let problem = null;
+    try {
+      const capPath = join(cwd, ".claude", "role-os", "capabilities.json");
+      const manifest = existsSync(capPath) ? JSON.parse(readFileSync(capPath, "utf-8")) : {};
+      const g = manifest && typeof manifest === "object" ? manifest[action.id] : undefined;
+      if (!g || typeof g !== "object" || g.granted !== true) {
+        problem = 'No capability "' + action.id + '" is granted in .claude/role-os/capabilities.json';
+      } else if (typeof g.expires === "string") {
+        const t = Date.parse(g.expires);
+        if (Number.isNaN(t)) {
+          problem = 'the grant for "' + action.id + '" has an unparseable "expires" ("' + g.expires + '") — an invalid expiry DENIES (fail-closed), it never extends the grant; fix the date';
+        } else if (t < Date.now()) {
+          problem = 'the grant for "' + action.id + '" expired at ' + g.expires;
+        }
+      }
+    } catch (err) {
+      // FAIL CLOSED: a gated action whose grant cannot be evaluated is denied, with the cause named.
+      problem = "the grant could not be evaluated (" + err.message + ") — failing closed on an irreversible action";
+    }
+    if (problem) {
+      process.stderr.write(
+        'Capability gate: "' + action.label + '" is an irreversible action requiring an explicit grant. ' +
+        problem + '. To authorize it, the director adds {"' + action.id + '": {"granted": true}} to ' +
+        '.claude/role-os/capabilities.json, optionally with an "expires" date. (The gate enforces only ' +
+        '"granted"/"expires" — a grant authorizes ALL matching ' + action.label + ' calls; a "scope" field is informational only.)\\n'
+      );
+      process.exit(2);
+    }
+  }
+}
 
 let state = {};
 if (existsSync(statePath)) {
-  try { state = JSON.parse(readFileSync(statePath, "utf-8")); } catch {}
+  try { state = JSON.parse(readFileSync(statePath, "utf-8")); }
+  catch (err) {
+    warnOnce("session-state-unreadable", "session-state.json was unreadable (" + err.message + ") — continuing with fresh session state.");
+    state = {};
+  }
 }
 
-const toolName = input.tool_name || "";
 if (!state.toolsUsed) state.toolsUsed = [];
 if (!state.toolsUsed.includes(toolName)) {
   state.toolsUsed.push(toolName);
@@ -476,33 +557,32 @@ if (writeTools.includes(toolName) && !state.routeCardPresent && (state.substanti
   notes.push(\`Write tool "\${toolName}" used without route card. Consider /roleos-route.\`);
 }
 
-// Tool-Call Conformance floor (advisory, deterministic). Best-effort: runs only when this tool has a
-// .claude/role-os/tool-contracts.json catalog entry AND the role-os library is resolvable. ANY failure
-// is a silent no-op — a hook must never break a tool call; the watcher is advisory + fail-open.
+// Tool-Call Conformance floor (advisory, deterministic, fail-open). Runs only when this tool has a
+// .claude/role-os/tool-contracts.json catalog entry AND the role-os library is installed where this
+// repo can resolve it (local node_modules). Unlike the inlined capability gate above (fail-closed),
+// the advisory floor may degrade — but it must SAY so once on stderr, never silently no-op.
 try {
   const catPath = join(cwd, ".claude", "role-os", "tool-contracts.json");
   if (existsSync(catPath)) {
     const catalog = JSON.parse(readFileSync(catPath, "utf-8"));
     const entry = catalog && catalog[toolName];
     if (entry) {
-      const { schemaFloor, contractFloor } = await import("role-os/src/specialist/conformance-consult.mjs");
-      const tool = { name: toolName, contract: entry.contract, params: entry.params || [], constraints: entry.constraints || [] };
-      const call = (input.tool_input && typeof input.tool_input === "object") ? input.tool_input : {};
-      const v = [...schemaFloor(tool, call).violations, ...contractFloor(tool, call, entry.state_struct || null).violations];
-      if (v.length) notes.push(\`Tool-Call Conformance (advisory): "\${toolName}" appears NONCONFORMANT — \${v.join("; ")}.\`);
+      const libPath = join(cwd, "node_modules", "role-os", "src", "specialist", "conformance-consult.mjs");
+      if (!existsSync(libPath)) {
+        warnOnce("conformance-lib-unresolvable", "tool-contracts.json catalogs this tool but the role-os library is not installed locally (" + libPath + " not found) — the advisory conformance floor is OFF. Run: npm i -D role-os");
+      } else {
+        const { schemaFloor, contractFloor } = await import(pathToFileURL(libPath).href);
+        const tool = { name: toolName, contract: entry.contract, params: entry.params || [], constraints: entry.constraints || [] };
+        const call = (input.tool_input && typeof input.tool_input === "object") ? input.tool_input : {};
+        const v = [...schemaFloor(tool, call).violations, ...contractFloor(tool, call, entry.state_struct || null).violations];
+        if (v.length) notes.push(\`Tool-Call Conformance (advisory): "\${toolName}" appears NONCONFORMANT — \${v.join("; ")}.\`);
+      }
     }
   }
-} catch { /* role-os not resolvable here, or internal error -> no-op (never block a tool call) */ }
-
-// Capability gate (opt-in via ROLEOS_CAPABILITY_GATE, FAIL-CLOSED): an irreversible action without a
-// granted capability is DENIED (exit 2 blocks). Default OFF => no-op. Bounds what a wrong verdict can
-// DO (POLA / CaMeL). Best-effort: if role-os is not resolvable here a hook-resolution failure must not
-// itself block a call; the in-process onPreToolUse path still enforces it where role-os is resolvable.
-try {
-  const { capabilityGate } = await import("role-os/src/specialist/capability-gate.mjs");
-  const cap = capabilityGate(cwd, toolName, input.tool_input || {});
-  if (cap.denied) { process.stderr.write(cap.reason + "\\n"); process.exit(2); }
-} catch { /* role-os not resolvable / internal error -> no-op (in-process path enforces) */ }
+} catch (err) {
+  // Advisory stays fail-open (never blocks a call) but never SILENT: surface the failure once.
+  warnOnce("conformance-floor-error", "Tool-Call Conformance advisory errored (" + err.message + ") — the advisory floor was skipped.");
+}
 
 // PreToolUse wire protocol (current Claude Code): inject advisory context via
 // hookSpecificOutput.additionalContext + exit 0. A bare { addContext } is IGNORED; exit 2 would BLOCK.

package/src/knowledge/analyze-artifact-evidence.mjs

@@ -206,11 +206,12 @@ export function analyzeArtifactEvidence({
         locations.push("title-match");
       }
       // Check for source ID reference
-      if (artifactLower.includes(chunk.source_id.toLowerCase())) {
+      const sourceId = (chunk.source_id ?? "").toLowerCase();
+      if (sourceId && artifactLower.includes(sourceId)) {
         locations.push("source-id");
       }
       // Check for key content phrases (first 50 chars of content)
-      const contentSnippet = chunk.content.slice(0, 50).toLowerCase();
+      const contentSnippet = (chunk.content ?? "").slice(0, 50).toLowerCase();
       if (contentSnippet.length > 20 && artifactLower.includes(contentSnippet)) {
         locations.push("content-echo");
       }
@@ -236,7 +237,7 @@ export function analyzeArtifactEvidence({
   const knownRefs = new Set([
     ...(bundle?.selected?.map((c) => (c.citation?.reference ?? c.chunk_id).toLowerCase()) ?? []),
     ...(bundle?.selected?.map((c) => c.title?.toLowerCase()).filter(Boolean) ?? []),
-    ...(bundle?.selected?.map((c) => c.source_id.toLowerCase()) ?? []),
+    ...(bundle?.selected?.map((c) => (c.source_id ?? "").toLowerCase()).filter(Boolean) ?? []),
     ...known_external_refs.map((r) => r.toLowerCase()),
   ]);
 
@@ -268,7 +269,14 @@ export function analyzeArtifactEvidence({
 
   if (!postureCompliance.compliant) {
     verdict = verdict === "fail" ? "fail" : "warn";
-    reasons.push(`Posture compliance failed: missing ${postureCompliance.missing_signals.join(", ")}`);
+    const parts = [];
+    if (postureCompliance.missing_signals.length > 0) {
+      parts.push(`missing ${postureCompliance.missing_signals.join(", ")}`);
+    }
+    if ((postureCompliance.banned_violations ?? []).length > 0) {
+      parts.push(`banned phrase(s): ${postureCompliance.banned_violations.join(", ")}`);
+    }
+    reasons.push(`Posture compliance failed: ${parts.join("; ") || "expected posture signals absent"}`);
   }
 
   if (driftViolations.length > 0) {
@@ -390,16 +398,18 @@ function checkDrift(artifactLower, roleId) {
 function extractCitationPatterns(text) {
   const patterns = [];
 
-  // Bracketed references: [Something]
-  const bracketMatches = text.match(/\[([^\]]{5,80})\]/g) ?? [];
+  // Bracketed references: [Something] — but not markdown links [text](url)
+  // (checkbox brackets like [x] fall below the 5-char minimum already)
+  const bracketMatches = text.match(/\[([^\]]{5,80})\](?!\()/g) ?? [];
   for (const m of bracketMatches) {
     patterns.push(m.slice(1, -1));
   }
 
-  // "Source: X" or "Reference: X"
-  const sourceMatches = text.match(/(?:source|reference|per|according to):?\s+([^\n.]{5,80})/gi) ?? [];
+  // "Source: X" or "Reference: X" — word boundaries so "per" can't match
+  // inside words like "Super" or "paper"
+  const sourceMatches = text.match(/\b(?:source|reference|per|according to)\b:?\s+([^\n.]{5,80})/gi) ?? [];
   for (const m of sourceMatches) {
-    const cleaned = m.replace(/^(?:source|reference|per|according to):?\s+/i, "").trim();
+    const cleaned = m.replace(/^(?:source|reference|per|according to)\b:?\s+/i, "").trim();
     if (cleaned) patterns.push(cleaned);
   }
 

package/src/knowledge/fallback-policy.mjs

@@ -13,12 +13,24 @@
  * @returns {{ state: string, action: string, message: string }}
  */
 export function applyFallbackPolicy(bundle, overlay) {
+  // Malformed bundle from a buggy/version-skewed retrieve() → named degraded
+  // state instead of a TypeError that callers would swallow silently.
+  if (!bundle || typeof bundle !== "object" || !Array.isArray(bundle.selected)) {
+    return {
+      state: "malformed_bundle",
+      action: "warn",
+      message: "Retrieval bundle is malformed (missing or invalid selected[]) — knowledge degraded",
+    };
+  }
+
+  const summary = bundle.summary ?? {};
+
   // No overlay → shared corpus only
   if (!overlay) {
     return {
       state: "no_overlay",
       action: "continue",
-      message: `No overlay for role ${bundle.role_id} — using shared corpus only`,
+      message: `No overlay for role ${bundle.role_id ?? "unknown"} — using shared corpus only`,
     };
   }
 
@@ -32,22 +44,22 @@ export function applyFallbackPolicy(bundle, overlay) {
   }
 
   // Check for forbidden source hits
-  if (bundle.summary.forbidden_hits > 0) {
+  if ((summary.forbidden_hits ?? 0) > 0) {
     // Forbidden sources were removed, but log the diagnostic
     return {
       state: "forbidden_hit",
       action: "continue",
-      message: `${bundle.summary.forbidden_hits} forbidden source(s) removed from results`,
+      message: `${summary.forbidden_hits} forbidden source(s) removed from results`,
     };
   }
 
   // Check for stale-dominant results
-  const totalRelevant = bundle.summary.selected_count + bundle.summary.stale_count;
-  if (totalRelevant > 0 && bundle.summary.stale_count / totalRelevant > 0.5) {
+  const totalRelevant = (summary.selected_count ?? 0) + (summary.stale_count ?? 0);
+  if (totalRelevant > 0 && (summary.stale_count ?? 0) / totalRelevant > 0.5) {
     return {
       state: "stale_dominant",
       action: "warn",
-      message: `${bundle.summary.stale_count} of ${totalRelevant} relevant candidates are stale`,
+      message: `${summary.stale_count} of ${totalRelevant} relevant candidates are stale`,
     };
   }
 
@@ -62,7 +74,7 @@ export function applyFallbackPolicy(bundle, overlay) {
   }
 
   // Check for weak trust posture
-  if (bundle.provenance.trust_posture === "weak") {
+  if ((bundle.provenance?.trust_posture ?? "weak") === "weak") {
     return {
       state: "no_strong_match",
       action: "warn",

package/src/knowledge/resolve-overlay.mjs

@@ -11,13 +11,26 @@ import { fileURLToPath } from "node:url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-// Default overlay search paths (relative to knowledge-core root)
-const OVERLAY_PATHS = [
-  // Local knowledge-core checkout (development)
-  join(resolve(__dirname, "..", ".."), "knowledge-core", "knowledge", "roles"),
-  // Fallback: role-os local knowledge dir
-  join(resolve(__dirname, ".."), "knowledge", "roles"),
-];
+// Default overlay search paths. ROLEOS_KNOWLEDGE_ROLES overrides everything;
+// otherwise we look for a knowledge-core checkout SIBLING to the role-os repo
+// (e.g. <workspace>/knowledge-core next to <workspace>/role-os), then a nested
+// checkout, then role-os's own local knowledge dir.
+function defaultOverlayPaths() {
+  const paths = [];
+  if (process.env.ROLEOS_KNOWLEDGE_ROLES) {
+    paths.push(resolve(process.env.ROLEOS_KNOWLEDGE_ROLES));
+  }
+  paths.push(
+    // Sibling knowledge-core checkout (development) — __dirname is <role-os>/src/knowledge,
+    // so three levels up is the workspace that contains both repos.
+    join(resolve(__dirname, "..", "..", ".."), "knowledge-core", "knowledge", "roles"),
+    // Nested knowledge-core checkout inside role-os
+    join(resolve(__dirname, "..", ".."), "knowledge-core", "knowledge", "roles"),
+    // Fallback: role-os local knowledge dir
+    join(resolve(__dirname, ".."), "knowledge", "roles"),
+  );
+  return paths;
+}
 
 /**
  * Resolve the overlay for a role.
@@ -28,7 +41,7 @@ const OVERLAY_PATHS = [
  * @returns {{ overlay: object, path: string } | null}
  */
 export function resolveOverlay(roleId, options = {}) {
-  const paths = options.searchPaths || OVERLAY_PATHS;
+  const paths = options.searchPaths || defaultOverlayPaths();
 
   for (const dir of paths) {
     const filePath = join(dir, `${roleId}.json`);

package/src/knowledge/retrieve-for-dispatch.mjs

@@ -71,7 +71,7 @@ export async function retrieveForDispatch({ roleId, taskText, packetContextSumma
 
     return {
       bundle,
-      status: deriveStatus(fallback),
+      status: deriveStatus(fallback, bundle),
       fallback,
     };
   }
@@ -82,18 +82,23 @@ export async function retrieveForDispatch({ roleId, taskText, packetContextSumma
 
   return {
     bundle,
-    status: deriveStatus(fallback),
+    status: deriveStatus(fallback, bundle),
     fallback,
   };
 }
 
 /**
  * Derive packet knowledge status from fallback state.
+ *
+ * no_overlay with selected chunks maps to "weak" (shared-corpus-only evidence),
+ * matching fallback-policy's "continue — using shared corpus only" action.
+ * "none" is reserved for genuinely empty retrievals, since renderKnowledgeBlock()
+ * drops the knowledge block entirely for status "none".
  */
-function deriveStatus(fallback) {
+function deriveStatus(fallback, bundle) {
   switch (fallback.state) {
     case "healthy": return "strong";
-    case "no_overlay": return "none";
+    case "no_overlay": return (bundle?.selected?.length ?? 0) > 0 ? "weak" : "none";
     case "no_strong_match": return "weak";
     case "stale_dominant": return "stale";
     case "conflicting": return "conflicted";

package/src/mission-run.mjs

@@ -114,11 +114,12 @@ export function createRun(missionKey, taskDescription, options = {}) {
 
 /**
  * Build steps from manifest for dynamic dispatch missions.
+ * Exported so the persistent runner (run.mjs) can scale steps from a manifest.
  * @param {Object} mission
  * @param {Object} manifest - The audit-manifest.json content
  * @returns {MissionStep[]}
  */
-function buildDynamicSteps(mission, manifest) {
+export function buildDynamicSteps(mission, manifest) {
   const dd = mission.dynamicDispatch;
   const steps = [];
 
@@ -198,11 +199,12 @@ function buildDynamicSteps(mission, manifest) {
 /**
  * Build steps from swarm manifest for dogfood-swarm missions.
  * Creates domain agent steps per stage with coordinator gates.
+ * Exported so the persistent runner (run.mjs) can scale steps from a manifest.
  * @param {Object} mission
  * @param {Object} manifest - The swarm-manifest.json content
  * @returns {MissionStep[]}
  */
-function buildSwarmSteps(mission, manifest) {
+export function buildSwarmSteps(mission, manifest) {
   const steps = [];
   const domains = manifest.domains || [];
   const stages = manifest.stages || ["health-a", "health-b", "health-c", "feature", "treatment"];
@@ -412,6 +414,13 @@ export function recordEscalation(run, from, to, trigger, action) {
     targetStep.note = `Re-opened by escalation: ${trigger}`;
     targetStep.completedAt = null;
     escalation.reopened = true;
+
+    // A completed run with a re-opened step is no longer complete —
+    // reset run status so the pending step is actionable again.
+    if (run.status === "completed") {
+      run.status = "running";
+      run.completedAt = null;
+    }
   } else {
     // S4-F2: Target role not found in chain (or no completed step to re-open).
     // Warn the operator instead of silently doing nothing.

package/src/packs-cmd.mjs

@@ -57,7 +57,7 @@ function runSuggest(packetFile) {
     }
   }
 
-  console.log(`\nNext: roleos route ${packetFile} --pack ${result.pack}\n`);
+  console.log(`\nNext: roleos route ${packetFile} --pack=${result.pack}\n`);
 }
 
 // ── Show ──────────────────────────────────────────────────────────────────────

package/src/review.mjs

@@ -32,9 +32,18 @@ export async function reviewCommand(args) {
   }
 
   // Extract task ID from the packet
-  const taskIdMatch = content.match(/## Task ID\n(.+)/);
+  const taskIdMatch = content.match(/## Task ID\r?\n(.+)/);
   const taskId = taskIdMatch ? taskIdMatch[1].trim() : basename(packetFile, ".md");
 
+  // Extract the producing role from the packet — reject escalations route the
+  // retry back to the role that PRODUCED the output, never the reviewer.
+  // Falls back to Orchestrator when the section is absent or unassigned.
+  const assignedRoleMatch = content.match(/## Assigned Role\r?\n(.+)/);
+  const assignedRole = assignedRoleMatch ? assignedRoleMatch[1].trim() : null;
+  const producingRole = assignedRole && !assignedRole.startsWith("<!--")
+    ? assignedRole
+    : "Orchestrator";
+
   console.log(`\nroleos review — ${verdict}\n`);
   console.log(`Packet: ${packetFile}`);
   console.log(`Task ID: ${taskId}\n`);
@@ -99,7 +108,7 @@ ${nextOwner}
     console.log(`\nEscalation (auto-routed):`);
     console.log(formatEscalation(escalation));
   } else if (verdict === "reject") {
-    const escalation = resolveRejected(reason, reviewer);
+    const escalation = resolveRejected(reason, producingRole);
     console.log(`\nEscalation (auto-routed):`);
     console.log(formatEscalation(escalation));
   }