role-os 2.9.0 → 2.9.1

package/README.zh.md

@@ -120,18 +120,21 @@ roleos reopen 0 "found issue in review"
 
 顺序：首先进行发布检查，然后进行完整的治疗。如果没有通过硬性闸，则不能发布 v1.0.0 版本。
 
-## 10 个包中的 61 个角色
+## 包含 61 个角色的目录
 
-| 包 | 角色 |
-|------|-------|
-| **Core** (3) | 协调员、产品战略家、审核者 |
+该目录将这 61 个角色分为 11 个类别。（Dispatch 使用一套独立的 10 个“团队包”——功能、bug 修复、安全、文档、发布、研究、处理、深度审计、头脑风暴、协作——这些团队包会从这些类别中选择相应的角色。）
+
+| 类别 | 角色 |
+|--------|-------|
+| **Core** (2) | 协调者，批评评审员 |
+| **Product** (4) | 产品策略师，反馈整合者，路线图优先级排序者，规范撰写者 |
 | **Engineering** (7) | 前端开发人员、后端工程师、测试工程师、重构工程师、性能工程师、依赖关系审计员、安全审查员 |
 | **Design** (2) | UI 设计师，品牌守护者 |
 | **Marketing** (1) | 发布文案撰写员 |
 | **Treatment** (7) | 仓库研究员、仓库翻译员、文档架构师、元数据管理员、覆盖审计员、部署验证员、发布工程师 |
-| **Product** (3) | 反馈综合分析员、路线图优先级排序者、规范编写者 |
 | **Research** (4) | 用户体验研究员、竞争对手分析师、趋势研究员、用户访谈结果综合分析员 |
 | **Growth** (4) | 发布策略制定者、内容策略制定者、社区经理、支持问题分流负责人 |
+| **Brainstorm** (19) | 背景调查员、用户价值调查员、创意突破调查员、机制调查员、市场调查员、逆向思维调查员、可行性调查员、质量标准调查员、背景分析师、用户价值分析师、机制分析师、定位分析师、逆向思维分析师、标准化者、整合者、产品拓展者、场景拓展者、护城河拓展者、评估者 |
 | **Deep Audit** (4) | 组件审计员、测试真实性审计员、接口审计员、审计综合分析员 |
 | **Swarm** (7) | 蜂群协调员、蜂群后端代理、蜂群桥接代理、蜂群测试代理、蜂群基础设施代理、蜂群前端代理、蜂群综合分析员 |
 
@@ -140,7 +143,13 @@ roleos reopen 0 "found issue in review"
 ## 快速入门
 
 ```bash
-npx role-os init
+# Install (puts `roleos` on your PATH):
+npm install -g role-os
+
+# Scaffold the role spine into your repo:
+roleos init
+# (one-off alternative without installing: `npx role-os init`,
+#  then prefix every command below with `npx role-os` instead of `roleos`)
 
 # Describe what you need — Role OS picks the right level:
 roleos run "fix the crash in save handler"
@@ -262,13 +271,21 @@ role-os/
     brainstorm.mjs             ← Evidence modes, request validation, finding/synthesis/judge schemas
     brainstorm-roles.mjs       ← Role-native schemas, input partitioning, blindspot enforcement, cross-exam
     brainstorm-render.mjs      ← Two-layer rendering: lexical bans, render schemas, debate transcript
-  test/                        ← 1150 tests across 37 test files
+  test/                        ← 1435 tests across 65 test files
   starter-pack/                ← Drop-in role contracts, policies, schemas, workflows
 ```
 
 ## 安全性
 
-Role OS **仅在本地运行**。它会复制 Markdown 模板并将数据包/结果文件写入到您的仓库的 `.claude/` 目录中。它不会访问网络、处理密钥或收集遥测数据。没有危险的操作——所有文件写入默认使用“如果存在则跳过”的方式。有关完整策略，请参阅 [SECURITY.md](SECURITY.md)。
+默认情况下，Role OS 仅在**本地文件系统上运行**。它会复制 Markdown 模板，并将数据包/结果/运行文件写入到您的仓库的 `.claude/` 目录中。默认操作不会进行任何网络请求，也不会处理任何敏感信息，也不会收集任何遥测数据。不执行任何危险的操作——所有文件写入操作默认使用“如果存在则跳过”的方式。
+
+有三个**可选**功能会在您明确启用时连接到网络：
+
+- **`roleos verify-citations`** — 调用外部 `prism` CLI，该工具会根据公共 arXiv/Crossref API 解析引用标识符（发送正在验证的引用 ID/URL）。
+- **专家级别** (`roleos specialist`，已注册的角色）— 将 Dispatch 提示发布到您在 `.role-os/specialists.json` 中配置的 `backend_url`（通常是本地模型端点）。
+- **预算/合规性咨询** (`ROLEOS_BUDGET_CONSULT` / `ROLEOS_CONFORMANCE_CONSULT`) — 通过 HTTP 将步骤/工具调用上下文发送到本地模型，以获取建议结果。
+
+这三个功能默认情况下都是关闭的，并且会回退到本地确定性行为。有关完整策略，请参阅 [SECURITY.md](SECURITY.md)。
 
 ## 操作系统
 

package/bin/roleos.mjs

@@ -50,6 +50,7 @@ Usage:
   roleos friction [id]               Measure operator friction
   roleos init                        Scaffold Role OS into .claude/
   roleos init --force                Update canonical files (protects context/)
+  roleos init claude [--force]       Scaffold Claude Code session integration (CLAUDE.md, commands, hooks)
   roleos packet new <type>           Create a new packet (feature|integration|identity)
   roleos route <packet-file> [--verbose]  Recommend the smallest valid chain
   roleos review <packet-file> <verdict>  Record a review verdict
@@ -72,8 +73,8 @@ Usage:
   roleos swarm manifest               Show the swarm manifest
   roleos swarm manifest --generate    Auto-detect domains and generate manifest
   roleos swarm status                 Show swarm run progress
-  roleos swarm findings               List findings by severity
-  roleos swarm approve                Approve the current feature gate
+  roleos swarm findings               List findings captured from wave reports
+  roleos swarm approve                Approve the current user gate
   roleos swarm verify                 Verify manifest and run state
   roleos verify-citations <dispatch>  Verify a research dispatch's citations via prism (gate)
   roleos specialist list              List all specialists in the registry (active version + cert)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "role-os",
-  "version": "2.9.0",
+  "version": "2.9.1",
   "description": "Role OS — a multi-Claude operating system where 61 specialized roles execute work through contracts, conflict detection, escalation, and structured evidence. 10 team packs, 9 missions including dogfood swarm (multi-pass convergence), deep audit with manifest-scaled dynamic dispatch, and brainstorm with traceable disagreement.",
   "homepage": "https://mcp-tool-shop-org.github.io/role-os/",
   "bugs": {

package/src/artifacts.mjs

@@ -521,15 +521,22 @@ export const PACK_HANDOFF_CONTRACTS = {
       { role: "Critic Reviewer", produces: "verdict", consumedBy: null },
     ],
   },
+  // v0.4 pipeline — mirrors the brainstorm mission's artifactFlow:
+  // Analysts (parallel) → Normalizer → Contrarian → Normalizer (rebut) →
+  // Synthesizer → Product Expander → Judge.
   brainstorm: {
     flow: [
-      { role: "Context Scout",       produces: "scout-finding",          consumedBy: "Normalizer" },
-      { role: "User Value Scout",    produces: "scout-finding",          consumedBy: "Normalizer" },
-      { role: "Creative Leap Scout", produces: "scout-finding",          consumedBy: "Normalizer" },
-      { role: "Normalizer",          produces: "normalized-finding-set", consumedBy: "Synthesizer" },
-      { role: "Synthesizer",         produces: "synthesis-report",       consumedBy: "Product Expander" },
-      { role: "Product Expander",    produces: "expanded-concept",       consumedBy: "Judge" },
-      { role: "Judge",               produces: "judge-report",           consumedBy: null },
+      { role: "Context Analyst",     produces: "context-map",      consumedBy: "Normalizer" },
+      { role: "User Value Analyst",  produces: "user-value-map",   consumedBy: "Normalizer" },
+      { role: "Mechanics Analyst",   produces: "mechanics-map",    consumedBy: "Normalizer" },
+      { role: "Positioning Analyst", produces: "positioning-map",  consumedBy: "Normalizer" },
+      { role: "Normalizer",          produces: "provenance-atoms", consumedBy: "Contrarian Analyst" },
+      { role: "Contrarian Analyst",  produces: "challenge-set",    consumedBy: "Normalizer" },
+      // Rebut pass: Normalizer routes analyst responses (defend/narrow/retract)
+      { role: "Normalizer",          produces: "rebuttal-set",     consumedBy: "Synthesizer" },
+      { role: "Synthesizer",         produces: "synthesis-report", consumedBy: "Product Expander" },
+      { role: "Product Expander",    produces: "expanded-concept", consumedBy: "Judge" },
+      { role: "Judge",               produces: "judge-report",     consumedBy: null },
     ],
   },
   treatment: {

package/src/audit-cmd.mjs

@@ -11,19 +11,9 @@
  */
 
 import { existsSync, readFileSync, writeFileSync, readdirSync } from "node:fs";
-import { join, resolve } from "node:path";
-import { getMission, suggestMission } from "./mission.mjs";
+import { join } from "node:path";
 import {
-  createRun,
-  startNextStep,
-  getRunPosition,
-  getArtifactChain,
-  generateCompletionReport,
-  formatCompletionReport,
-} from "./mission-run.mjs";
-import {
-  createPersistentRun, findActiveRun, listRuns, loadRun,
-  startNext, explainRun, getPosition, saveRun,
+  createPersistentRun, listRuns, loadRun, getPosition,
 } from "./run.mjs";
 
 // ── Constants ────────────────────────────────────────────────────────────────
@@ -61,7 +51,7 @@ export async function auditCommand(args) {
 
 // ── roleos audit [run] ───────────────────────────────────────────────────────
 
-function cmdRun(extraArgs) {
+async function cmdRun(extraArgs) {
   const cwd = process.cwd();
   const manifestPath = join(cwd, MANIFEST_FILE);
 
@@ -91,20 +81,28 @@ function cmdRun(extraArgs) {
     ? extraArgs.join(" ")
     : `Deep audit of ${manifest.repo || "current repo"}`;
 
-  // Create a persistent run via the deep-audit mission
-  const run = createPersistentRun(taskDesc, cwd, { forceMission: "deep-audit" });
+  // Create a persistent run via the deep-audit mission.
+  // Forwarding the manifest routes step construction through buildDynamicSteps,
+  // so auditor steps scale with components/boundaries instead of the static flow.
+  const run = await createPersistentRun(taskDesc, cwd, {
+    forceMission: "deep-audit",
+    manifest,
+  });
+
+  const componentCount = manifest.components?.length || 0;
+  const boundaryCount = manifest.boundary_clusters?.length ?? manifest.boundaries?.length ?? 0;
 
   console.log(`\nDeep Audit Started`);
   console.log(`──────────────────`);
   console.log(`Run:        ${run.id}`);
   console.log(`Repo:       ${manifest.repo || "unknown"}`);
-  console.log(`Components: ${manifest.components?.length || 0}`);
-  console.log(`Boundaries: ${manifest.boundaries?.length || 0}`);
+  console.log(`Components: ${componentCount}`);
+  console.log(`Boundaries: ${boundaryCount}`);
   console.log(`Steps:      ${run.steps.length}`);
   console.log(`\nThe audit will dispatch:`);
-  console.log(`  - Component Auditor  ×${manifest.components?.length || 0}`);
-  console.log(`  - Test Truth Auditor ×${manifest.components?.length || 0}`);
-  console.log(`  - Seam Auditor       ×${manifest.boundaries?.length || 0}`);
+  console.log(`  - Component Auditor  ×${componentCount}`);
+  console.log(`  - Test Truth Auditor ×${componentCount}`);
+  console.log(`  - Seam Auditor       ×${boundaryCount}`);
   console.log(`  - Audit Synthesizer  ×1`);
   console.log(`  - Critic Reviewer    ×1`);
   console.log(`\nRun 'roleos next' to begin the first step.`);
@@ -228,11 +226,13 @@ function generateManifest(cwd, manifestPath) {
 function cmdStatus() {
   const cwd = process.cwd();
 
-  // Find the most recent deep-audit run
+  // Find the most recent deep-audit run.
+  // missionKey is authoritative; task keywords cover legacy runs created
+  // before missionKey was exposed by listRuns.
   const runs = listRuns(cwd);
   const auditRuns = runs.filter(r =>
-    r.task.toLowerCase().includes("audit") ||
-    r.level === "mission"
+    r.missionKey === "deep-audit" ||
+    r.task.toLowerCase().includes("audit")
   );
 
   if (auditRuns.length === 0) {

package/src/brainstorm-roles.mjs

@@ -308,6 +308,12 @@ export function validateRoleNativeOutput(roleName, output) {
       // Validate item shape for object items
       if (typeof spec.items === "object" && !Array.isArray(spec.items)) {
         for (let i = 0; i < value.length; i++) {
+          // Guard malformed (null / non-object) items — the validator must
+          // report bad LLM output, not crash on it.
+          if (value[i] === null || typeof value[i] !== "object" || Array.isArray(value[i])) {
+            issues.push(`${fieldName}[${i}] must be an object`);
+            continue;
+          }
           for (const [itemField, itemType] of Object.entries(spec.items)) {
             if (value[i][itemField] === undefined) {
               issues.push(`${fieldName}[${i}].${itemField} is required`);

package/src/citation-panel.mjs

@@ -182,7 +182,10 @@ export function runOffloadPanel(supported, options = {}) {
     }
   }
 
-  const checked = perCitation.filter((p) => p.panel_verdict === "supported" || disagreements.some((d) => d.id === p.id)).length;
+  // `checked` = citations the panel actually ADJUDICATED (a real verdict came back). "error" and
+  // "no_evidence" entries were never re-judged — counting them (or join-by-nullable-id tricks)
+  // would overstate the second seat's coverage in the receipt.
+  const checked = perCitation.filter((p) => p.panel_verdict !== "error" && p.panel_verdict !== "no_evidence").length;
   return {
     requested: true,
     reachable,
@@ -217,6 +220,9 @@ function contrastiveDetail(disagreements) {
  *   - gate passing + panel DISAGREES on ≥1 supported citation -> escalate (local_panel_disagreement)
  *   - gate passing + panel UNREACHABLE (and it was requested) -> escalate (local_panel_unreachable)
  *     ("an unreachable gate is a closed gate" — same invariant prism uses)
+ *   - gate passing + panel ERRORED on ≥1 citation it was asked to re-check -> escalate
+ *     (local_panel_incomplete — per-citation errors are per-citation unreachability; a citation
+ *     the second seat never adjudicated cannot be stamped fully verified)
  *   - gate already blocking/advisory                          -> unchanged (panel adds notes only)
  *
  * @param {object} gate    GateResult from gateCitations / runCitationGate
@@ -247,5 +253,24 @@ export function applyLocalPanel(gate, panel) {
       detail: contrastiveDetail(panel.disagreements),
     };
   }
+  // A flaky session that adjudicates 1 of 10 citations must not let the other 9 pass as
+  // "fully verified": every per-citation error closes the gate for the whole accept.
+  // ("no_evidence" entries stay notes — prism surfaced nothing to re-judge, and absence of
+  // evidence is not a contradiction; they are visible in perCitation and excluded from `checked`.)
+  const unadjudicated = (panel.perCitation || []).filter((p) => p.panel_verdict === "error");
+  if (unadjudicated.length > 0) {
+    const names = unadjudicated.slice(0, 5).map((p) => p.identifier || p.id || "(unidentified)").join(", ");
+    return {
+      ...annotated,
+      verdict: "escalate",
+      pass: false,
+      advisory: true,
+      reason: "local_panel_incomplete",
+      detail:
+        `the local panel errored on ${unadjudicated.length} citation(s) it was asked to re-check (${names}) — ` +
+        `these were never adjudicated by the second seat, so the accept cannot stand` +
+        (panel.detail ? `; ${panel.detail}` : ""),
+    };
+  }
   return annotated; // panel agrees (or had nothing to challenge) -> pass stands
 }

package/src/composite.mjs

@@ -124,6 +124,10 @@ export function initExecution(runPlan) {
 export function advance(exec) {
   if (exec.status === "completed" || exec.status === "failed") return null;
 
+  // Preserve the blocked status — blockChild's contract is that the parent
+  // stays blocked until recoverChild; advancing must not mask the block.
+  if (exec.status === "blocked") return null;
+
   if (!exec.startedAt) exec.startedAt = new Date().toISOString();
   exec.status = "running";
 

package/src/entry.mjs

@@ -274,7 +274,7 @@ function applyLadder(text, missionSug, missionScore, packSug, packScore, agreeme
       confidence: packScore,
     } : null,
     isComposite,
-    warnings: [...warnings, "Free routing selected — task will be scored against all 31 roles"],
+    warnings: [...warnings, `Free routing selected — task will be scored against all ${ROLE_CATALOG.length} roles`],
   };
 }
 
@@ -284,7 +284,7 @@ function buildFreeRoutingHints(text, missionSug, packSug, isComposite, composite
     reason = `Task looks composite (${composite.detectedCategories.map(c => c.category).join(" + ")}). ` +
              `No single mission or pack covers all parts — use free routing with decomposition.`;
   } else if (!missionSug && !packSug) {
-    reason = "No mission or pack matched. Task is novel — free routing will score all 31 roles.";
+    reason = `No mission or pack matched. Task is novel — free routing will score all ${ROLE_CATALOG.length} roles.`;
   } else {
     reason = "Mission and pack matches were too weak to commit. Free routing will let role scoring decide.";
   }

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",