role-os 2.9.0 → 2.9.1

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));
   }

package/src/role-dossiers.json

@@ -318,7 +318,7 @@
     "role": "Judge",
     "aptitudes": {
       "rigor": 5,
-      "pace": 2,
+      "pace": 1,
       "range": 1,
       "skepticism": 5,
       "autonomy": 3,

package/src/route.mjs

@@ -1,11 +1,11 @@
 import { existsSync } from "node:fs";
-import { resolve, dirname } from "node:path";
+import { resolve, dirname, join } from "node:path";
 import { readFileSafe } from "./fs-utils.mjs";
 import { detectConflicts } from "./conflicts.mjs";
 import { resolveConflict, resolveSplit, formatEscalation } from "./escalation.mjs";
 import { suggestPack, getPack, checkPackMismatch, getPackRoles } from "./packs.mjs";
 
-// ── Full 31-Role Catalog ─────────────────────────────────────────────────────
+// ── Full Role Catalog ────────────────────────────────────────────────────────
 // Every role in the OS is scoreable. Keywords from routing-rules.md + contracts.
 // Triggers are strong multi-word signals worth bonus points.
 
@@ -502,7 +502,7 @@ function scoreRole(role, content, packetType, deliverableType) {
 // ── Type detection ────────────────────────────────────────────────────────────
 
 function detectType(content) {
-  const typeMatch = content.match(/## Packet Type\n(\w+)/);
+  const typeMatch = content.match(/## Packet Type\r?\n(\w+)/);
   if (typeMatch && ["feature", "integration", "identity"].includes(typeMatch[1])) {
     return typeMatch[1];
   }
@@ -521,7 +521,7 @@ function detectType(content) {
 // ── Deliverable type extraction ───────────────────────────────────────────────
 
 function extractDeliverableType(content) {
-  const match = content.match(/## Deliverable Type\n(\w+)/);
+  const match = content.match(/## Deliverable Type\r?\n(\w+)/);
   if (match && DELIVERABLE_TYPES.includes(match[1])) return match[1];
   return null;
 }
@@ -553,17 +553,34 @@ function assessConfidence(scoredRoles) {
 
 // ── File reference extraction ─────────────────────────────────────────────────
 
-function extractFileRefs(content, packetDir) {
+/**
+ * Find the base directory file refs should resolve against: the nearest
+ * ancestor of the packet that contains .claude/ (the repo root), falling
+ * back to the current working directory for packets outside any repo.
+ */
+function repoBaseFor(packetFile) {
+  let dir = dirname(packetFile);
+  for (let i = 0; i < 20; i++) {
+    if (existsSync(join(dir, ".claude"))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return process.cwd();
+}
+
+function extractFileRefs(content, packetFile) {
   const refs = [];
-  const inputsMatch = content.match(/## Inputs\n([\s\S]*?)(?=\n## |\n---)/);
+  const inputsMatch = content.match(/## Inputs\r?\n([\s\S]*?)(?=\r?\n## |\r?\n---)/);
   if (!inputsMatch) return refs;
 
+  const base = repoBaseFor(packetFile);
   const inputsSection = inputsMatch[1];
   const pathPattern = /(?:^|\s|`)((?:\.\/|\.\.\/|[a-zA-Z][\w\-]*\/)[^\s`\n,)]+\.\w+)/gm;
   let match;
   while ((match = pathPattern.exec(inputsSection)) !== null) {
     const ref = match[1];
-    const resolved = resolve(dirname(packetDir), "..", "..", ref);
+    const resolved = resolve(base, ref);
     refs.push({ ref, resolved, exists: existsSync(resolved) });
   }
 
@@ -610,6 +627,22 @@ const HANDOFF_HINTS = {
 
 export async function routeCommand(args) {
   const verbose = args.includes("--verbose");
+
+  // A bare --pack would be silently swallowed as a flag and the pack name
+  // treated as the packet file — reject loudly instead of mis-routing.
+  if (args.includes("--pack")) {
+    const err = new Error("The --pack flag requires a value: use --pack=<name> (e.g. --pack=feature)");
+    err.exitCode = 1;
+    err.hint = "Run 'roleos packs list' for available pack names.";
+    throw err;
+  }
+
+  const knownFlag = a => a === "--verbose" || a === "--debug" || a.startsWith("--pack=");
+  const unknownFlags = args.filter(a => a.startsWith("--") && !knownFlag(a));
+  if (unknownFlags.length > 0) {
+    console.log(`! Ignoring unrecognized flag(s): ${unknownFlags.join(", ")}`);
+  }
+
   const packFlag = args.find(a => a.startsWith("--pack="));
   const requestedPack = packFlag ? packFlag.split("=")[1] : null;
   const packetFile = args.find(a => !a.startsWith("--"));
@@ -632,7 +665,7 @@ export async function routeCommand(args) {
   const type = detectType(content);
   const deliverableType = extractDeliverableType(content);
 
-  // Score all 32 roles
+  // Score every role in the catalog
   const allScored = ROLE_CATALOG.map(role => ({
     role,
     ...scoreRole(role, content, type, deliverableType),

package/src/run-cmd.mjs

@@ -94,7 +94,6 @@ export async function runCommand(args) {
   }
 
   // roleos run "<task>"
-  const task = args.join(" ");
   const opts = {};
 
   // Parse --mission= and --pack= flags

package/src/run.mjs

@@ -16,9 +16,11 @@ import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, rename
 import { join } from "node:path";
 import { decideEntry } from "./entry.mjs";
 import { getMission } from "./mission.mjs";
-import { TEAM_PACKS, getPack } from "./packs.mjs";
+import { TEAM_PACKS, getPack, getPackRoles } from "./packs.mjs";
 import { ROLE_CATALOG } from "./route.mjs";
 import { ROLE_ARTIFACT_CONTRACTS, validateArtifact, getHandoffContract } from "./artifacts.mjs";
+import { buildSwarmSteps, buildDynamicSteps } from "./mission-run.mjs";
+import { isValidStepTransition } from "./state-machine.mjs";
 import { retrieveForDispatch, isKnowledgeConfigured } from "./knowledge/index.mjs";
 
 // ── Run directory ────────────────────────────────────────────────────────────
@@ -87,6 +89,9 @@ let _counter = 0;
  * @param {object} [opts]
  * @param {string} [opts.forceMission] - force a specific mission key
  * @param {string} [opts.forcePack] - force a specific pack key
+ * @param {object} [opts.manifest] - dispatch manifest for dynamic missions
+ *   (swarm-manifest.json for dogfood-swarm, audit-manifest.json for deep-audit);
+ *   scales steps per domain/component instead of using the static artifactFlow
  * @returns {PersistentRun}
  */
 export async function createPersistentRun(taskDescription, cwd, opts = {}) {
@@ -106,7 +111,7 @@ export async function createPersistentRun(taskDescription, cwd, opts = {}) {
     if (!mission) throw new Error(`Mission "${opts.forceMission}" not found`);
     level = "mission";
     missionKey = opts.forceMission;
-    steps = buildMissionSteps(opts.forceMission);
+    steps = buildMissionSteps(opts.forceMission, opts.manifest);
   } else if (opts.forcePack) {
     const pack = getPack(opts.forcePack);
     if (!pack) throw new Error(`Pack "${opts.forcePack}" not found`);
@@ -172,9 +177,23 @@ export async function createPersistentRun(taskDescription, cwd, opts = {}) {
 
 // ── Step builders ────────────────────────────────────────────────────────────
 
-function buildMissionSteps(missionKey) {
+function buildMissionSteps(missionKey, manifest = null) {
   const mission = getMission(missionKey);
-  return mission.artifactFlow.map((step, i) => ({
+
+  // Dynamic dispatch — when a manifest is supplied, scale steps from it:
+  // dogfood-swarm builds per-domain steps with stage/gate metadata,
+  // deep-audit builds one auditor step per component/boundary.
+  let flow = mission.artifactFlow;
+  if (manifest && mission.dynamicDispatch) {
+    flow = missionKey === "dogfood-swarm"
+      ? buildSwarmSteps(mission, manifest)
+      : buildDynamicSteps(mission, manifest);
+  }
+
+  // Spread first so dispatch metadata (stage, domain, isGate, userApproval,
+  // parcel, consumedBy, …) carries through, then pin the run.mjs step shape.
+  return flow.map((step, i) => ({
+    ...step,
     index: i,
     role: step.role,
     produces: step.produces,
@@ -190,12 +209,26 @@ function buildMissionSteps(missionKey) {
 function buildPackSteps(packKey) {
   const pack = getPack(packKey);
   const handoff = getHandoffContract(packKey);
-  const roles = pack.chainOrder
-    ? pack.chainOrder.split(" → ")
-    : pack.roles;
+
+  // Derive steps from the pack's real roster (includes the final review gate
+  // and conditional Orchestrator) — never from chainOrder prose, which for
+  // brainstorm/deep-audit/swarm contains pseudo-role fragments.
+  const roles = getPackRoles(packKey) || pack.roles;
+
+  // Fail loudly on roles missing from the catalog — a run built around a
+  // nonexistent role breaks guidance, artifact contracts, and escalation.
+  const unknown = roles.filter(name => !ROLE_CATALOG.some(r => r.name === name));
+  if (unknown.length > 0) {
+    throw new Error(
+      `Pack "${packKey}" contains roles not in the role catalog: ${unknown.join(", ")}`
+    );
+  }
 
   return roles.map((roleName, i) => {
-    const artifact = handoff?.flow?.[i]?.produces || guessArtifact(roleName);
+    // Resolve produces by role lookup into the handoff flow — index alignment
+    // is wrong whenever the roster and flow are ordered differently.
+    const flowEntry = handoff?.flow?.find(f => f.role === roleName);
+    const artifact = flowEntry?.produces || guessArtifact(roleName);
     return {
       index: i,
       role: roleName,
@@ -279,6 +312,7 @@ function buildStepGuidance(roleName, produces, mission) {
 
 function guessArtifact(roleName) {
   const map = {
+    "Orchestrator": "decomposition-plan",
     "Product Strategist": "strategy-brief",
     "Spec Writer": "implementation-spec",
     "Backend Engineer": "change-plan",
@@ -512,6 +546,13 @@ export function escalate(run, from, to, trigger, action, cwd) {
         run.steps[i].note = `Unblocked: ${to} re-opened for escalation`;
       }
     }
+
+    // A completed run with a re-opened step is no longer complete —
+    // mirror reopenStep so formatNext doesn't report "All done."
+    if (run.status === "completed") {
+      run.status = "paused";
+      run.completedAt = null;
+    }
   } else {
     const inChain = run.steps.some(s => s.role === to);
     escalation.warning = inChain
@@ -540,13 +581,15 @@ export function escalate(run, from, to, trigger, action, cwd) {
 export function retry(run, stepIndex, cwd) {
   const step = run.steps[stepIndex];
   if (!step) throw new Error(`Invalid step index: ${stepIndex}`);
-  if (step.status !== "failed" && step.status !== "partial") {
-    throw new Error(`Step ${stepIndex} is "${step.status}", not failed/partial`);
+  // blocked is retryable so an operator block (or a mistaken one) has a recovery path
+  if (step.status !== "failed" && step.status !== "partial" && step.status !== "blocked") {
+    throw new Error(`Step ${stepIndex} is "${step.status}", not failed/partial/blocked`);
   }
 
+  const previousStatus = step.status;
   step.status = "pending";
   step.artifact = null;
-  step.note = `Retried (was ${step.status})`;
+  step.note = `Retried (was ${previousStatus})`;
   step.completedAt = null;
 
   // Unblock downstream
@@ -583,6 +626,14 @@ export function retry(run, stepIndex, cwd) {
 export function blockStep(run, stepIndex, reason, cwd) {
   const step = run.steps[stepIndex];
   if (!step) throw new Error(`Invalid step index: ${stepIndex}`);
+  // Enforce the canonical state machine — blocking a completed/failed step
+  // would strand the run with no CLI recovery path.
+  if (!isValidStepTransition(step.status, "blocked")) {
+    throw new Error(
+      `Cannot block step ${stepIndex} (${step.role}) — invalid transition "${step.status}" → "blocked". ` +
+      `Only pending or active steps can be blocked.`
+    );
+  }
 
   step.status = "blocked";
   step.note = reason;
@@ -609,8 +660,8 @@ export function blockStep(run, stepIndex, reason, cwd) {
 export function reopenStep(run, stepIndex, reason, cwd) {
   const step = run.steps[stepIndex];
   if (!step) throw new Error(`Invalid step index: ${stepIndex}`);
-  if (step.status !== "completed" && step.status !== "partial") {
-    throw new Error(`Step ${stepIndex} is "${step.status}", can only reopen completed/partial`);
+  if (step.status !== "completed" && step.status !== "partial" && step.status !== "blocked") {
+    throw new Error(`Step ${stepIndex} is "${step.status}", can only reopen completed/partial/blocked`);
   }
 
   step.status = "pending";
@@ -743,7 +794,7 @@ export function formatNext(run) {
 
   if (run.status === "failed" || run.status === "partial") {
     const failedStep = run.steps.find(s => s.status === "failed" || s.status === "partial");
-    return `Run ${run.status} at step ${failedStep?.index || "?"} (${failedStep?.role || "?"}). ` +
+    return `Run ${run.status} at step ${failedStep?.index ?? "?"} (${failedStep?.role || "?"}). ` +
            `Use \`roleos retry ${failedStep?.index}\` to retry or \`roleos escalate\` to reroute.`;
   }
 
@@ -920,7 +971,7 @@ export function loadRun(cwd, id) {
 /**
  * List all runs in the working directory.
  * @param {string} cwd
- * @returns {Array<{id: string, task: string, status: string, level: string, createdAt: string}>}
+ * @returns {Array<{id: string, task: string, status: string, level: string, missionKey: string|null, createdAt: string}>}
  */
 export function listRuns(cwd) {
   const dir = runsDir(cwd);
@@ -936,6 +987,7 @@ export function listRuns(cwd) {
           task: run.taskDescription,
           status: run.status,
           level: run.entryLevel,
+          missionKey: run.missionKey ?? null,
           createdAt: run.createdAt,
         };
       } catch { return null; }

package/src/session.mjs

@@ -15,6 +15,8 @@ import { existsSync, mkdirSync, writeFileSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { writeFileSafe } from "./fs-utils.mjs";
 import { scaffoldHooks, generateHooksConfig } from "./hooks.mjs";
+import { ROLE_CATALOG } from "./route.mjs";
+import { TEAM_PACKS } from "./packs.mjs";
 
 // ── roleos init claude ────────────────────────────────────────────────────────
 
@@ -302,7 +304,7 @@ Before starting non-trivial work in this repo, route the task through Role OS:
 3. Use structured handoffs between roles
 4. Review with evidence-based verdicts
 
-Role OS provides 31 specialized roles across 8 packs (engineering, design, product, research, growth, treatment, marketing, core). It detects broken chains, auto-routes recovery, and requires structured evidence in every verdict.
+Role OS provides ${ROLE_CATALOG.length} specialized roles across ${Object.keys(TEAM_PACKS).length} packs (${Object.keys(TEAM_PACKS).join(", ")}). It detects broken chains, auto-routes recovery, and requires structured evidence in every verdict.
 
 If the task is composite (feature + docs + launch), Role OS will recommend splitting into child packets with dependency ordering.
 

package/src/specialist/capability-gate.mjs

@@ -21,7 +21,9 @@
  *     not, so its asymmetry runs the other way.)
  *
  * The grant manifest (`.claude/role-os/capabilities.json`, director-authored) maps an action id to a
- * grant, e.g.: { "npm:publish": { "granted": true, "scope": "@mcptoolshop/roll", "expires": "2026-07-01" } }
+ * grant, e.g.: { "npm:publish": { "granted": true, "expires": "2026-07-01" } }. The gate enforces
+ * `granted` and `expires` ONLY — any other field (e.g. a "scope" annotation) is informational/audit
+ * metadata and does NOT narrow the grant: a granted action id authorizes ALL matching invocations.
  */
 
 import { existsSync, readFileSync } from "node:fs";
@@ -41,17 +43,21 @@ const _bash = (re) => (toolName, call) =>
 /**
  * The GATED SET — the irreversible / world-touching actions from the NAMED_COMPENSATORS standard.
  * Each entry: { id, label, test(toolName, call) -> boolean }. Detection is deterministic + pattern-
- * based and errs toward FLAGGING (a benign match just needs a one-line grant), never toward missing
- * an irreversible action.
+ * based and errs toward FLAGGING (a benign match just needs a one-line grant). The patterns allow
+ * flags between the command word and its verb — `git -C <dir> push`, `npm --workspace <pkg> publish`,
+ * `gh release -R <repo> create` all match — without crossing a shell separator (| ; & or newline).
+ * KNOWN LIMIT: script indirection (`npm run release` wrapping a publish, a shell script invoking
+ * git push) is NOT detected — the gate bounds direct invocations; it is opt-in defense-in-depth,
+ * not an evasion-proof sandbox.
  */
 export const GATED_ACTIONS = [
-  { id: "npm:publish", label: "npm/pnpm/yarn publish", test: _bash(/\b(?:npm|pnpm|yarn)\s+publish\b/) },
-  { id: "pypi:publish", label: "PyPI publish (twine/uv)", test: _bash(/\btwine\s+upload\b|\buv\s+publish\b/) },
-  { id: "gh:release", label: "gh release create", test: _bash(/\bgh\s+release\s+create\b/) },
-  { id: "gh:pr-create", label: "gh pr create", test: _bash(/\bgh\s+pr\s+create\b/) },
-  { id: "gh:repo-edit", label: "gh repo edit/delete", test: _bash(/\bgh\s+repo\s+(?:edit|delete)\b/) },
-  { id: "git:push", label: "git push", test: _bash(/\bgit\s+push\b/) },
-  { id: "pages:deploy", label: "GitHub Pages / gh-pages deploy", test: _bash(/\bgh-pages\b|\bpages\s+deploy\b/) },
+  { id: "npm:publish", label: "npm/pnpm/yarn publish", test: _bash(/\b(?:npm|pnpm|yarn)\b[^|;&\n]*\bpublish\b/) },
+  { id: "pypi:publish", label: "PyPI publish (twine/uv)", test: _bash(/\btwine\b[^|;&\n]*\bupload\b|\buv\b[^|;&\n]*\bpublish\b/) },
+  { id: "gh:release", label: "gh release create", test: _bash(/\bgh\b[^|;&\n]*\brelease\b[^|;&\n]*\bcreate\b/) },
+  { id: "gh:pr-create", label: "gh pr create", test: _bash(/\bgh\b[^|;&\n]*\bpr\b[^|;&\n]*\bcreate\b/) },
+  { id: "gh:repo-edit", label: "gh repo edit/delete", test: _bash(/\bgh\b[^|;&\n]*\brepo\b[^|;&\n]*\b(?:edit|delete)\b/) },
+  { id: "git:push", label: "git push", test: _bash(/\bgit\b[^|;&\n]*\bpush\b/) },
+  { id: "pages:deploy", label: "GitHub Pages / gh-pages deploy", test: _bash(/\bgh-pages\b|\bpages\b[^|;&\n]*\bdeploy\b/) },
 ];
 
 /** Read the director's capability manifest, or {} if absent/malformed (=> nothing granted). */
@@ -66,15 +72,24 @@ export function loadCapabilities(cwd) {
   }
 }
 
-/** Is `actionId` granted (granted:true and not expired) in the manifest? */
-function _granted(manifest, actionId, now) {
+/**
+ * Evaluate `actionId`'s grant. Returns null when granted and valid; otherwise a short problem
+ * string for the deny reason. An unparseable `expires` is treated as INVALID (deny) — a
+ * fail-closed gate must never turn a typo'd date into a permanent grant.
+ */
+function _grantProblem(manifest, actionId, now) {
   const g = manifest && manifest[actionId];
-  if (!g || typeof g !== "object" || g.granted !== true) return false;
+  if (!g || typeof g !== "object" || g.granted !== true) {
+    return `No capability "${actionId}" is granted in ${CAPABILITIES_FILE}`;
+  }
   if (typeof g.expires === "string") {
     const t = Date.parse(g.expires);
-    if (!Number.isNaN(t) && t < now) return false; // grant expired
+    if (Number.isNaN(t)) {
+      return `The grant for "${actionId}" has an unparseable "expires" value ("${g.expires}") — an invalid expiry DENIES (fail-closed), it never extends the grant; fix the date`;
+    }
+    if (t < now) return `The grant for "${actionId}" expired at ${g.expires}`;
   }
-  return true;
+  return null;
 }
 
 /**
@@ -100,14 +115,16 @@ export function capabilityGate(cwd, toolName, toolInput, opts = {}) {
     if (!action) return { denied: false }; // not an irreversible action -> allow
     const manifest = opts.capabilities || loadCapabilities(cwd);
     const now = typeof opts.now === "number" ? opts.now : Date.now();
-    if (_granted(manifest, action.id, now)) return { denied: false };
+    const problem = _grantProblem(manifest, action.id, now);
+    if (!problem) return { denied: false };
     return {
       denied: true,
       action: action.id,
       reason:
         `Capability gate: "${action.label}" is an irreversible action requiring an explicit grant. ` +
-        `No capability "${action.id}" is granted in ${CAPABILITIES_FILE}. To authorize it, the ` +
-        `director adds {"${action.id}": {"granted": true}} (optionally with "scope"/"expires").`,
+        `${problem}. To authorize it, the director adds {"${action.id}": {"granted": true}}, ` +
+        `optionally with an "expires" date. (Note: the gate enforces only "granted"/"expires" — ` +
+        `a grant authorizes ALL matching ${action.label} calls; a "scope" field is informational only.)`,
     };
   } catch {
     // A gate that errors must not silently allow an irreversible action: if a gated action matched

package/src/specialist/dispatch.mjs

@@ -145,7 +145,6 @@ export async function dispatchSpecialist({
     if (specialistCall.ok) {
       result = specialistCall.verdict;
       source = "specialist";
-      recordDispatch(state, role, windowSize, parseIsoMs(nowIso));
     } else {
       // Specialist call failed → fail open to Claude. The gate's "route" was specialist, but
       // the realized source is Claude. Both are recorded in the receipt.
@@ -157,6 +156,11 @@ export async function dispatchSpecialist({
     source = "claude";
   }
 
+  // Record EVERY dispatch (both routes) in the quota window, tagged with the REALIZED source.
+  // The window only rolls when Claude traffic is recorded too — recording only specialist
+  // successes froze the window and locked every role out permanently once the quota tripped.
+  recordDispatch(state, source, windowSize, parseIsoMs(nowIso));
+
   // ── Shadow probe ─────────────────────────────────────────────────────────────────────────
   // Probes only fire when the dispatch actually went to a specialist (source === "specialist").
   // A failed-open dispatch already ran Claude; there is nothing left to probe.
@@ -175,12 +179,13 @@ export async function dispatchSpecialist({
         claude_summary: summarize(claudeVerdict),
       });
       resetProbeCounter(state, role);
-      const { probes, rate, shouldHalt } = checkHalt(eventsPath, role, N, tau);
+      const { probes, rate, agreed: agreedCount, shouldHalt } = checkHalt(eventsPath, role, N, tau);
       shadow = { fired: true, agreed, probes, rate, halt_triggered: shouldHalt };
       if (shouldHalt && !getHalt(state, role).halted) {
         const reason = contrastiveHaltMessage({ role, probes, rate, tau });
         setHalt(state, role, { reason, since: nowIso });
-        appendHaltEvent(eventsPath, { role, ts: nowIso, reason, probes, agreed: probes - Math.round(probes * (1 - rate)), rate, tau });
+        // `agreed` is checkHalt's exact window count — never recompute it lossily from the rate.
+        appendHaltEvent(eventsPath, { role, ts: nowIso, reason, probes, agreed: agreedCount, rate, tau });
       }
     } else {
       shadow = { fired: false, counter: c };

package/src/specialist/registry.mjs

@@ -199,6 +199,12 @@ function validateVersion(v, tag) {
   if (v.exam_centroid !== undefined && !Array.isArray(v.exam_centroid)) {
     errors.push(`${tag}: exam_centroid, if present, must be an array of numbers`);
   }
+  // ood_floor feeds defaultOodFn directly (gate.mjs): a string silently falls back to the 0.4
+  // default and a value outside cosine range disables routing entirely — both must fail loudly
+  // at load time, mirroring the R5 gate_threshold check.
+  if (v.ood_floor !== undefined && (typeof v.ood_floor !== "number" || !(v.ood_floor >= -1 && v.ood_floor <= 1))) {
+    errors.push(`${tag}: R5 — ood_floor, if present, must be a number in [-1, 1] (cosine range; got ${JSON.stringify(v.ood_floor)})`);
+  }
   return errors;
 }