role-os 2.2.0 → 2.3.0

package/src/audit-cmd.mjs

@@ -0,0 +1,401 @@
+/**
+ * Audit CLI — Deep Audit entry point.
+ *
+ * roleos audit                       Run deep audit on current repo
+ * roleos audit manifest              Show or generate the audit manifest
+ * roleos audit status                Show audit run progress
+ * roleos audit verify                Re-verify findings against current code
+ *
+ * This is a first-class shortcut into the deep-audit mission.
+ * Under the hood it creates a mission run with dynamic dispatch.
+ */
+
+import { existsSync, readFileSync, writeFileSync, readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { getMission, suggestMission } from "./mission.mjs";
+import {
+  createRun,
+  startNextStep,
+  getRunPosition,
+  getArtifactChain,
+  generateCompletionReport,
+  formatCompletionReport,
+} from "./mission-run.mjs";
+import {
+  createPersistentRun, findActiveRun, listRuns, loadRun,
+  startNext, explainRun, getPosition, saveRun,
+} from "./run.mjs";
+
+// ── Constants ────────────────────────────────────────────────────────────────
+
+const MANIFEST_FILE = "audit-manifest.json";
+
+// ── Main dispatch ────────────────────────────────────────────────────────────
+
+/**
+ * @param {string[]} args
+ */
+export async function auditCommand(args) {
+  const sub = args[0] || "run";
+
+  switch (sub) {
+    case "run":
+    case "start":
+      return cmdRun(args.slice(1));
+    case "manifest":
+      return cmdManifest(args.slice(1));
+    case "status":
+      return cmdStatus();
+    case "verify":
+      return cmdVerify();
+    case "help":
+      return cmdHelp();
+    default:
+      // If the first arg isn't a subcommand, treat everything as a task description
+      if (!["run", "start", "manifest", "status", "verify", "help"].includes(sub)) {
+        return cmdRun(args);
+      }
+      cmdHelp();
+  }
+}
+
+// ── roleos audit [run] ───────────────────────────────────────────────────────
+
+function cmdRun(extraArgs) {
+  const cwd = process.cwd();
+  const manifestPath = join(cwd, MANIFEST_FILE);
+
+  // Check if manifest exists
+  if (!existsSync(manifestPath)) {
+    console.log("\nNo audit-manifest.json found in current directory.");
+    console.log("Generate one first with: roleos audit manifest --generate\n");
+    console.log("The manifest defines your repo's components and boundaries.");
+    console.log("Deep audit uses it to dispatch one auditor per component.\n");
+    process.exit(1);
+  }
+
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+
+  // Validate manifest shape
+  const issues = validateManifest(manifest);
+  if (issues.length > 0) {
+    console.log("\nAudit manifest has issues:\n");
+    for (const issue of issues) {
+      console.log(`  - ${issue}`);
+    }
+    console.log("\nFix the manifest and re-run.\n");
+    process.exit(1);
+  }
+
+  const taskDesc = extraArgs.length > 0
+    ? 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" });
+
+  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(`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(`  - Audit Synthesizer  ×1`);
+  console.log(`  - Critic Reviewer    ×1`);
+  console.log(`\nRun 'roleos next' to begin the first step.`);
+  console.log(`Run 'roleos audit status' to check progress.\n`);
+}
+
+// ── roleos audit manifest ────────────────────────────────────────────────────
+
+function cmdManifest(args) {
+  const cwd = process.cwd();
+  const manifestPath = join(cwd, MANIFEST_FILE);
+
+  if (args.includes("--generate") || args.includes("-g")) {
+    return generateManifest(cwd, manifestPath);
+  }
+
+  if (!existsSync(manifestPath)) {
+    console.log("\nNo audit-manifest.json found.");
+    console.log("Run 'roleos audit manifest --generate' to create one.\n");
+    return;
+  }
+
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+  const issues = validateManifest(manifest);
+
+  console.log(`\nAudit Manifest: ${manifest.repo || "unknown"}`);
+  console.log(`──────────────────────────────────────────`);
+  console.log(`Version:    ${manifest.version || "unknown"}`);
+  console.log(`Language:   ${manifest.language || "unknown"}`);
+  console.log(`Source:     ${manifest.total_source_lines || "?"} lines`);
+  console.log(`Tests:      ${manifest.total_test_lines || "?"} lines`);
+  console.log(`Components: ${manifest.components?.length || 0}`);
+  console.log(`Boundaries: ${manifest.boundaries?.length || 0}`);
+
+  if (manifest.components?.length > 0) {
+    console.log(`\nComponents:`);
+    for (const c of manifest.components) {
+      const paths = c.owned_paths?.length || 0;
+      console.log(`  - ${c.id}: ${c.description || ""} (${paths} paths)`);
+    }
+  }
+
+  if (manifest.boundaries?.length > 0) {
+    console.log(`\nBoundaries:`);
+    for (const b of manifest.boundaries) {
+      const label = b.id || `${b.from} → ${b.to}`;
+      console.log(`  - ${label}: ${b.contract || b.description || ""}`);
+    }
+  }
+
+  if (issues.length > 0) {
+    console.log(`\nIssues:`);
+    for (const issue of issues) {
+      console.log(`  ! ${issue}`);
+    }
+  } else {
+    console.log(`\nManifest is valid.`);
+  }
+
+  console.log("");
+}
+
+function generateManifest(cwd, manifestPath) {
+  if (existsSync(manifestPath)) {
+    console.log(`\nManifest already exists at ${MANIFEST_FILE}.`);
+    console.log("Edit it manually or delete it to regenerate.\n");
+    return;
+  }
+
+  // Build a skeleton manifest by scanning src/
+  const srcDir = join(cwd, "src");
+  const components = [];
+
+  if (existsSync(srcDir)) {
+    const files = readdirSync(srcDir).filter(f => f.endsWith(".mjs") || f.endsWith(".js") || f.endsWith(".ts"));
+    // Group by common prefix
+    const seen = new Set();
+    for (const f of files) {
+      const base = f.replace(/(-cmd)?\.m?[jt]s$/, "");
+      if (seen.has(base)) continue;
+      seen.add(base);
+
+      const paths = files.filter(ff => ff.startsWith(base)).map(ff => `src/${ff}`);
+      components.push({
+        id: base,
+        description: `TODO: describe ${base}`,
+        owned_paths: paths,
+        forbidden_paths: [],
+        upstream_deps: [],
+        downstream_consumers: [],
+        public_interfaces: [],
+      });
+    }
+  }
+
+  const manifest = {
+    repo: "TODO: org/repo-name",
+    version: "0.0.0",
+    timestamp: new Date().toISOString(),
+    language: "TODO",
+    runtime: "TODO",
+    total_source_lines: 0,
+    total_test_lines: 0,
+    external_dependencies: 0,
+    components,
+    boundaries: [],
+  };
+
+  writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+  console.log(`\nGenerated skeleton ${MANIFEST_FILE} with ${components.length} components.`);
+  console.log("Edit the manifest to:");
+  console.log("  1. Fill in repo, version, language, runtime");
+  console.log("  2. Write real descriptions for each component");
+  console.log("  3. Define boundaries between components");
+  console.log("  4. Set upstream_deps and downstream_consumers");
+  console.log(`\nThen run 'roleos audit' to start the audit.\n`);
+}
+
+// ── roleos audit status ──────────────────────────────────────────────────────
+
+function cmdStatus() {
+  const cwd = process.cwd();
+
+  // Find the most recent deep-audit run
+  const runs = listRuns(cwd);
+  const auditRuns = runs.filter(r =>
+    r.task.toLowerCase().includes("audit") ||
+    r.level === "mission"
+  );
+
+  if (auditRuns.length === 0) {
+    console.log("\nNo audit runs found. Start one with: roleos audit\n");
+    return;
+  }
+
+  // Show the most recent
+  const latest = auditRuns[0];
+  console.log(`\nLatest Audit Run`);
+  console.log(`────────────────`);
+  console.log(`ID:      ${latest.id}`);
+  console.log(`Task:    ${latest.task}`);
+  console.log(`Status:  ${latest.status.toUpperCase()}`);
+  console.log(`Created: ${latest.createdAt}`);
+
+  const full = loadRun(cwd, latest.id);
+  if (full) {
+    const pos = getPosition(full);
+    console.log(`Progress: ${pos.progress}`);
+
+    const byStatus = {};
+    for (const s of full.steps) {
+      byStatus[s.status] = (byStatus[s.status] || 0) + 1;
+    }
+    console.log(`\nSteps:`);
+    for (const [status, count] of Object.entries(byStatus)) {
+      const icon = status === "completed" ? "[x]" :
+                   status === "active"    ? "[>]" :
+                   status === "failed"    ? "[!]" :
+                   status === "blocked"   ? "[-]" : "[ ]";
+      console.log(`  ${icon} ${status}: ${count}`);
+    }
+  }
+
+  console.log(`\nRun 'roleos explain ${latest.id}' for full detail.\n`);
+}
+
+// ── roleos audit verify ──────────────────────────────────────────────────────
+
+function cmdVerify() {
+  const cwd = process.cwd();
+  const manifestPath = join(cwd, MANIFEST_FILE);
+
+  if (!existsSync(manifestPath)) {
+    console.log("\nNo audit-manifest.json found. Nothing to verify.\n");
+    process.exit(1);
+  }
+
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+  const issues = validateManifest(manifest);
+
+  console.log(`\nAudit Verification`);
+  console.log(`──────────────────`);
+
+  // 1. Manifest valid
+  if (issues.length === 0) {
+    console.log(`  [PASS] Manifest is valid`);
+  } else {
+    console.log(`  [FAIL] Manifest has ${issues.length} issue(s)`);
+    for (const i of issues) console.log(`         - ${i}`);
+  }
+
+  // 2. Owned paths exist
+  let pathsOk = 0;
+  let pathsMissing = 0;
+  for (const c of manifest.components || []) {
+    for (const p of c.owned_paths || []) {
+      if (existsSync(join(cwd, p))) {
+        pathsOk++;
+      } else {
+        pathsMissing++;
+        if (pathsMissing <= 5) {
+          console.log(`  [WARN] Missing path: ${p} (${c.id})`);
+        }
+      }
+    }
+  }
+  if (pathsMissing === 0) {
+    console.log(`  [PASS] All ${pathsOk} owned paths exist`);
+  } else {
+    console.log(`  [WARN] ${pathsMissing} owned path(s) missing (${pathsOk} ok)`);
+  }
+
+  // 3. Check for audit output files
+  const auditFiles = ["AUDIT-SUMMARY.md", "AUDIT-ACTION-PLAN.md", "AUDIT-CRITIC-VERDICT.md"];
+  const existing = auditFiles.filter(f => existsSync(join(cwd, f)));
+  if (existing.length === auditFiles.length) {
+    console.log(`  [PASS] All audit output files present (${existing.length}/${auditFiles.length})`);
+  } else if (existing.length > 0) {
+    console.log(`  [WARN] Partial audit outputs (${existing.length}/${auditFiles.length})`);
+    const missing = auditFiles.filter(f => !existsSync(join(cwd, f)));
+    for (const f of missing) console.log(`         missing: ${f}`);
+  } else {
+    console.log(`  [INFO] No audit outputs yet — run 'roleos audit' first`);
+  }
+
+  // 4. Check parcel reports
+  const parcelFiles = readdirSync(cwd).filter(f => f.startsWith("AUDIT-PARCEL-"));
+  if (parcelFiles.length > 0) {
+    console.log(`  [PASS] ${parcelFiles.length} parcel report(s) found`);
+  } else {
+    console.log(`  [INFO] No parcel reports yet`);
+  }
+
+  const healthy = issues.length === 0 && pathsMissing === 0;
+  console.log(`\n${healthy ? "Audit infrastructure verified." : "Some issues found — fix before re-auditing."}\n`);
+  if (!healthy) process.exit(1);
+}
+
+// ── Help ─────────────────────────────────────────────────────────────────────
+
+function cmdHelp() {
+  console.log(`
+roleos audit — Deep Audit CLI
+
+Usage:
+  roleos audit                        Start a deep audit on the current repo
+  roleos audit manifest               Show the audit manifest
+  roleos audit manifest --generate    Generate a skeleton manifest from src/
+  roleos audit status                 Show audit run progress
+  roleos audit verify                 Verify manifest and audit outputs
+  roleos audit help                   Show this help
+
+The deep audit decomposes a repo into bounded components, dispatches one
+auditor per component, inspects seams between components, checks test truth,
+then synthesizes into a ranked action plan.
+
+Workflow:
+  1. roleos audit manifest --generate    Create audit-manifest.json
+  2. Edit the manifest                   Define components and boundaries
+  3. roleos audit                        Start the audit run
+  4. roleos next                         Step through each auditor
+  5. roleos audit status                 Check progress
+  6. roleos audit verify                 Verify everything landed
+`);
+}
+
+// ── Manifest validation ──────────────────────────────────────────────────────
+
+function validateManifest(manifest) {
+  const issues = [];
+
+  if (!manifest.components || !Array.isArray(manifest.components)) {
+    issues.push("components must be an array");
+  } else {
+    if (manifest.components.length === 0) {
+      issues.push("components array is empty — add at least one component");
+    }
+    for (let i = 0; i < manifest.components.length; i++) {
+      const c = manifest.components[i];
+      if (!c.id) issues.push(`components[${i}] missing id`);
+      if (!c.owned_paths || c.owned_paths.length === 0) {
+        issues.push(`components[${i}] (${c.id || "?"}) has no owned_paths`);
+      }
+    }
+  }
+
+  if (!manifest.boundaries || !Array.isArray(manifest.boundaries)) {
+    issues.push("boundaries must be an array");
+  }
+
+  return issues;
+}
+
+export { validateManifest };

package/src/brainstorm-roles.mjs

@@ -139,7 +139,10 @@ export const INPUT_PARTITIONS = {
  */
 export function partitionBrief(request, roleName) {
   const partition = INPUT_PARTITIONS[roleName];
-  if (!partition) return request; // Unknown role gets full brief (fallback)
+  if (!partition) {
+    // Unknown roles receive only the topic — minimal brief, not full access
+    return request.topic !== undefined ? { topic: request.topic } : {};
+  }
 
   const filtered = {};
   for (const field of partition.permitted) {
@@ -702,6 +705,46 @@ export function translateToAtoms(roleName, roleOutput) {
   return atoms;
 }
 
+/**
+ * Map from specific claim_kind (atom layer) to broad statement kind (scout layer).
+ * This bridges the two naming conventions:
+ *   - Scout findings use `.kind` ∈ {"claim", "opportunity", "risk", "tension", "unknown"}
+ *   - Translated atoms use `.claim_kind` with specific types per role
+ */
+export const CLAIM_KIND_TO_STATEMENT_KIND = {
+  // Context Analyst → claim
+  definition: "claim", category: "claim", lineage: "claim", boundary: "claim",
+  // User Value Analyst → opportunity or claim
+  need: "opportunity", desire: "opportunity", friction: "risk", willingness: "claim",
+  // Mechanics Analyst → claim or risk
+  loop: "claim", dependency: "claim", failure_mode: "risk", mechanism: "claim",
+  // Positioning Analyst → opportunity
+  substitute: "tension", wedge: "opportunity", category_frame: "claim",
+  positioning: "claim", timing: "opportunity",
+  // Contrarian Analyst → tension
+  challenge: "tension", contradiction: "tension", overstatement: "tension", gap: "risk",
+  // Normalizer
+  adjacency: "claim", avoidance: "risk", constraint: "claim",
+};
+
+/**
+ * Normalize an atom to include both `.claim_kind` (specific) and `.kind` (broad).
+ * Ensures atoms are compatible with both the scout validation layer and
+ * the cross-examination layer.
+ *
+ * @param {object} atom - Atom with claim_kind
+ * @returns {object} Atom with both claim_kind and kind fields
+ */
+export function normalizeAtomKind(atom) {
+  if (atom.kind && !atom.claim_kind) {
+    return { ...atom, claim_kind: atom.kind };
+  }
+  if (atom.claim_kind && !atom.kind) {
+    return { ...atom, kind: CLAIM_KIND_TO_STATEMENT_KIND[atom.claim_kind] || "unknown" };
+  }
+  return atom;
+}
+
 /**
  * Validate that a translated atom preserves all required provenance fields.
  *

package/src/composite.mjs

@@ -308,14 +308,20 @@ export function failChild(exec, category, reason) {
 
 /**
  * Find all categories that transitively depend on a given category.
+ * Uses a visited set to guard against circular dependency graphs.
  */
 function findUnreachable(exec, failedCategory) {
   const unreachable = new Set();
+  const visited = new Set();
   let changed = true;
   while (changed) {
     changed = false;
     for (const child of exec.children) {
       if (unreachable.has(child.category)) continue;
+      if (visited.has(child.category) && !child.dependsOn.includes(failedCategory) && !child.dependsOn.some(d => unreachable.has(d))) {
+        continue; // already evaluated without being unreachable — skip
+      }
+      visited.add(child.category);
       if (child.dependsOn.includes(failedCategory) || child.dependsOn.some(d => unreachable.has(d))) {
         unreachable.add(child.category);
         changed = true;
@@ -325,6 +331,41 @@ function findUnreachable(exec, failedCategory) {
   return [...unreachable];
 }
 
+/**
+ * Check for circular dependencies in the execution plan.
+ * Returns an array of categories involved in cycles (empty if none).
+ *
+ * @param {CompositeExecution} exec
+ * @returns {string[]}
+ */
+export function detectCycles(exec) {
+  const resolved = new Set();
+  const visiting = new Set();
+  const cycles = [];
+
+  function visit(category) {
+    if (resolved.has(category)) return;
+    if (visiting.has(category)) {
+      cycles.push(category);
+      return;
+    }
+    visiting.add(category);
+    const child = exec.children.find(c => c.category === category);
+    if (child) {
+      for (const dep of child.dependsOn) {
+        visit(dep);
+      }
+    }
+    visiting.delete(category);
+    resolved.add(category);
+  }
+
+  for (const child of exec.children) {
+    visit(child.category);
+  }
+  return cycles;
+}
+
 // ── Invalidation ──────────────────────────────────────────────────────────────
 
 /**

package/src/dispatch.mjs

@@ -16,85 +16,8 @@
 import { existsSync, mkdirSync, writeFileSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { resolveBlocked, resolveRejected } from "./escalation.mjs";
-
-// ── Tool profiles per role ────────────────────────────────────────────────────
-// What tools each role is allowed to use. Sandboxing by contract.
-
-const TOOL_PROFILES = {
-  // Core
-  "Orchestrator":         ["Read", "Glob", "Grep", "Bash", "Write", "Edit"],
-  "Product Strategist":   ["Read", "Glob", "Grep", "Write"],
-  "Critic Reviewer":      ["Read", "Glob", "Grep", "Bash"],
-
-  // Design
-  "UI Designer":          ["Read", "Glob", "Grep", "Write", "Edit"],
-  "Brand Guardian":       ["Read", "Glob", "Grep"],
-
-  // Engineering
-  "Backend Engineer":     ["Read", "Glob", "Grep", "Bash", "Write", "Edit"],
-  "Frontend Developer":   ["Read", "Glob", "Grep", "Bash", "Write", "Edit"],
-  "Test Engineer":        ["Read", "Glob", "Grep", "Bash", "Write", "Edit"],
-  "Performance Engineer": ["Read", "Glob", "Grep", "Bash"],
-  "Refactor Engineer":    ["Read", "Glob", "Grep", "Bash", "Write", "Edit"],
-  "Security Reviewer":    ["Read", "Glob", "Grep", "Bash"],
-  "Dependency Auditor":   ["Read", "Glob", "Grep", "Bash"],
-
-  // Treatment
-  "Repo Researcher":      ["Read", "Glob", "Grep", "Bash"],
-  "Repo Translator":      ["Read", "Glob", "Grep", "Write", "Edit"],
-  "Docs Architect":       ["Read", "Glob", "Grep", "Write", "Edit"],
-  "Metadata Curator":     ["Read", "Glob", "Grep", "Write", "Edit"],
-  "Coverage Auditor":     ["Read", "Glob", "Grep", "Bash"],
-  "Deployment Verifier":  ["Read", "Glob", "Grep", "Bash"],
-  "Release Engineer":     ["Read", "Glob", "Grep", "Bash", "Write", "Edit"],
-
-  // Growth / Marketing
-  "Launch Strategist":    ["Read", "Glob", "Grep", "Write"],
-  "Content Strategist":   ["Read", "Glob", "Grep", "Write"],
-  "Community Manager":    ["Read", "Glob", "Grep", "Write"],
-  "Support Triage Lead":  ["Read", "Glob", "Grep", "Write"],
-  "Launch Copywriter":    ["Read", "Glob", "Grep", "Write", "Edit"],
-
-  // Product
-  "Feedback Synthesizer": ["Read", "Glob", "Grep"],
-  "Roadmap Prioritizer":  ["Read", "Glob", "Grep", "Write"],
-  "Spec Writer":          ["Read", "Glob", "Grep", "Write", "Edit"],
-
-  // Research
-  "UX Researcher":        ["Read", "Glob", "Grep"],
-  "Competitive Analyst":  ["Read", "Glob", "Grep"],
-  "Trend Researcher":     ["Read", "Glob", "Grep"],
-  "User Interview Synthesizer": ["Read", "Glob", "Grep"],
-
-  // Brainstorm
-  "Context Scout":        ["Read", "Glob", "Grep"],
-  "User Value Scout":     ["Read", "Glob", "Grep"],
-  "Creative Leap Scout":  ["Read", "Glob", "Grep"],
-  "Normalizer":           ["Read", "Glob", "Grep"],
-  "Synthesizer":          ["Read", "Glob", "Grep", "Write"],
-  "Product Expander":     ["Read", "Glob", "Grep", "Write"],
-  "Judge":                ["Read", "Glob", "Grep"],
-  "Mechanics Scout":      ["Read", "Glob", "Grep"],
-  "Market Scout":         ["Read", "Glob", "Grep"],
-  "Contrarian Scout":     ["Read", "Glob", "Grep"],
-  "Feasibility Scout":    ["Read", "Glob", "Grep"],
-  "Quality Bar Scout":    ["Read", "Glob", "Grep"],
-  "Scenario Expander":    ["Read", "Glob", "Grep", "Write"],
-  "Moat Expander":        ["Read", "Glob", "Grep", "Write"],
-
-  // Brainstorm v0.3 analysts
-  "Context Analyst":      ["Read", "Glob", "Grep"],
-  "User Value Analyst":   ["Read", "Glob", "Grep"],
-  "Mechanics Analyst":    ["Read", "Glob", "Grep"],
-  "Positioning Analyst":  ["Read", "Glob", "Grep"],
-  "Contrarian Analyst":   ["Read", "Glob", "Grep"],
-
-  // Deep Audit
-  "Component Auditor":    ["Read", "Glob", "Grep"],
-  "Seam Auditor":         ["Read", "Glob", "Grep"],
-  "Test Truth Auditor":   ["Read", "Glob", "Grep"],
-  "Audit Synthesizer":    ["Read", "Glob", "Grep", "Write"],
-};
+import { TOOL_PROFILES } from "./tool-profiles.mjs";
+import { renderKnowledgeBlock, knowledgeManifestSummary } from "./knowledge/render-knowledge-block.mjs";
 
 // ── Default role config ─────────────────────────────────────────────────────
 
@@ -120,7 +43,9 @@ export const EXEC_STATES = [
 
 // ── System prompt builder ─────────────────────────────────────────────────────
 
-function buildRolePrompt(roleName, packetContent, chainContext) {
+function buildRolePrompt(roleName, packetContent, chainContext, packetKnowledge) {
+  const knowledgeBlock = renderKnowledgeBlock(packetKnowledge);
+
   return `You are operating as ${roleName} in a Role-OS managed chain.
 
 ## Your Role Contract
@@ -133,7 +58,7 @@ ${packetContent}
 You are step ${chainContext.stepNumber} of ${chainContext.totalSteps} in this chain.
 ${chainContext.previousRole ? `Previous role: ${chainContext.previousRole} (${chainContext.previousStatus})` : "You are the first role in this chain."}
 ${chainContext.nextRole ? `Next role: ${chainContext.nextRole}` : "You are the last role before Critic review."}
-
+${knowledgeBlock ? `\n${knowledgeBlock}\n` : ""}
 ## Handoff Requirements
 When you finish, produce a structured handoff:
 1. Summary of what you did
@@ -162,7 +87,7 @@ When you finish, produce a structured handoff:
  * @param {Object} [options.overrides] - Per-role config overrides
  * @returns {DispatchManifest}
  */
-export function buildDispatchManifest({ packetFile, packetContent, chainRoles, cwd, overrides = {} }) {
+export function buildDispatchManifest({ packetFile, packetContent, chainRoles, cwd, overrides = {}, packetKnowledge = null }) {
   const runId = `run-${Date.now()}`;
   const steps = [];
 
@@ -184,7 +109,7 @@ export function buildDispatchManifest({ packetFile, packetContent, chainRoles, c
       role: role.name,
       pack: role.pack,
       tools: TOOL_PROFILES[role.name] || ["Read", "Glob", "Grep"],
-      systemPrompt: buildRolePrompt(role.name, packetContent, chainContext),
+      systemPrompt: buildRolePrompt(role.name, packetContent, chainContext, packetKnowledge),
       model: roleOverrides.model || DEFAULTS.model,
       maxTurns: roleOverrides.maxTurns || DEFAULTS.maxTurns,
       maxBudgetUsd: roleOverrides.maxBudgetUsd || DEFAULTS.maxBudgetUsd,
@@ -195,6 +120,7 @@ export function buildDispatchManifest({ packetFile, packetContent, chainRoles, c
         from: i > 0 ? chainRoles[i - 1].role.name : null,
         to: i < chainRoles.length - 1 ? chainRoles[i + 1].role.name : null,
       },
+      knowledge: knowledgeManifestSummary(packetKnowledge),
     });
   }