role-os 2.2.0 → 2.3.0

package/src/knowledge/render-knowledge-block.mjs

@@ -0,0 +1,215 @@
+/**
+ * Knowledge Block Renderer — transforms a retrieval bundle into a prompt fragment.
+ *
+ * This is a pure function: same input → same output. No retrieval logic.
+ * No raw JSON dump. No ad hoc search. Just governed prompt construction.
+ *
+ * The block has 4 sections:
+ *   1. Knowledge posture (one line)
+ *   2. Retrieved evidence (top N excerpts with citations)
+ *   3. Warnings / constraints
+ *   4. Usage law (status-specific behavioral rules)
+ */
+
+// ── Configuration ───────────────────────────────────────────────────
+
+const MAX_EVIDENCE_CHUNKS = 6;
+const MAX_EXCERPT_LENGTH = 200;
+
+// ── Status-Specific Usage Law ───────────────────────────────────────
+
+const USAGE_LAW = {
+  strong: [
+    "Prioritize retrieved evidence when making claims in your domain.",
+    "Cite retrieved references when making specific substantive claims.",
+    "Do not invent sources that were not retrieved.",
+  ],
+  weak: [
+    "Treat retrieved evidence as partial — it may not cover the full picture.",
+    "Avoid overclaiming based on limited evidence.",
+    "Escalate uncertainty where it affects your deliverable.",
+    "Do not invent sources that were not retrieved.",
+  ],
+  stale: [
+    "Retrieved evidence may be outdated — note possible staleness in your analysis.",
+    "Do not present stale evidence as current truth without qualification.",
+    "Flag any claims that depend on time-sensitive data.",
+    "Do not invent sources that were not retrieved.",
+  ],
+  conflicted: [
+    "Retrieved sources contain conflicting evidence.",
+    "Surface the conflict explicitly — do not flatten disagreement into fake consensus.",
+    "Acknowledge which claims are contested and by what sources.",
+    "Do not invent sources that were not retrieved.",
+  ],
+  none: null, // No knowledge block rendered
+};
+
+// ── Main Renderer ───────────────────────────────────────────────────
+
+/**
+ * Render a knowledge prompt block from packet.knowledge.
+ *
+ * @param {Object|null} packetKnowledge - packet.knowledge (with retrieval_bundle and status)
+ * @returns {string|null} Prompt block string, or null if no knowledge to render
+ */
+export function renderKnowledgeBlock(packetKnowledge) {
+  if (!packetKnowledge || packetKnowledge.status === "none") {
+    return null;
+  }
+
+  const { retrieval_bundle: bundle, status } = packetKnowledge;
+  if (!bundle || !bundle.selected?.length) {
+    return null;
+  }
+
+  const sections = [];
+
+  // 1. Posture line
+  sections.push(`## Retrieved Knowledge\n\nKnowledge status: **${status}**`);
+
+  // 2. Evidence excerpts
+  const evidenceBlock = renderEvidenceBlock(bundle.selected);
+  if (evidenceBlock) {
+    sections.push(evidenceBlock);
+  }
+
+  // 3. Warnings
+  const warningsBlock = renderWarningsBlock(bundle.warnings);
+  if (warningsBlock) {
+    sections.push(warningsBlock);
+  }
+
+  // 4. Usage law
+  const lawBlock = renderUsageLaw(status);
+  if (lawBlock) {
+    sections.push(lawBlock);
+  }
+
+  return sections.join("\n\n");
+}
+
+// ── Evidence Renderer ───────────────────────────────────────────────
+
+/**
+ * Render the top N evidence excerpts.
+ */
+function renderEvidenceBlock(selected) {
+  if (!selected?.length) return null;
+
+  const top = selected.slice(0, MAX_EVIDENCE_CHUNKS);
+  const lines = ["### Evidence"];
+
+  for (let i = 0; i < top.length; i++) {
+    const chunk = top[i];
+    const trustLabel = chunk.metadata?.trust_tier ?? "general";
+    const freshnessLabel = chunk.metadata?.freshness?.status ?? "undated";
+    const citation = chunk.citation?.reference ?? chunk.chunk_id;
+    const excerpt = truncateExcerpt(chunk.content);
+
+    lines.push(`${i + 1}. [${trustLabel} | ${freshnessLabel}] ${citation}`);
+    lines.push(`   "${excerpt}"`);
+  }
+
+  return lines.join("\n");
+}
+
+// ── Warnings Renderer ───────────────────────────────────────────────
+
+/**
+ * Render retrieval warnings as constraints.
+ */
+function renderWarningsBlock(warnings) {
+  if (!warnings?.length) return null;
+
+  const meaningful = warnings.filter(
+    (w) => w.code !== "FORBIDDEN_SOURCE_HIT" // governance working, not a user-facing warning
+  );
+
+  if (!meaningful.length) return null;
+
+  const lines = ["### Warnings"];
+  for (const warning of meaningful) {
+    lines.push(`- ${formatWarning(warning)}`);
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Format a warning into human-readable text.
+ */
+function formatWarning(warning) {
+  switch (warning.code) {
+    case "NO_HIGH_TRUST_MATCH":
+      return "No authoritative sources matched — evidence quality is limited.";
+    case "ONLY_SHARED_CORPUS":
+      return "No role-specific evidence found — results are from shared corpus only.";
+    case "STALE_DOMINANT":
+      return "Most retrieved evidence is outdated — treat with caution.";
+    case "LOW_DIVERSITY":
+      return "Evidence comes from a single source — limited perspective.";
+    case "CONFLICTING_EVIDENCE":
+      return `Conflicting evidence: ${warning.message}`;
+    default:
+      return warning.message;
+  }
+}
+
+// ── Usage Law Renderer ──────────────────────────────────────────────
+
+/**
+ * Render status-specific usage law.
+ */
+function renderUsageLaw(status) {
+  const laws = USAGE_LAW[status];
+  if (!laws) return null;
+
+  const lines = ["### Knowledge Use Rules"];
+  for (const law of laws) {
+    lines.push(`- ${law}`);
+  }
+
+  return lines.join("\n");
+}
+
+// ── Helpers ─────────────────────────────────────────────────────────
+
+/**
+ * Truncate content to MAX_EXCERPT_LENGTH, preserving word boundaries.
+ */
+function truncateExcerpt(content) {
+  if (!content) return "";
+  if (content.length <= MAX_EXCERPT_LENGTH) return content;
+
+  const truncated = content.slice(0, MAX_EXCERPT_LENGTH);
+  const lastSpace = truncated.lastIndexOf(" ");
+  return (lastSpace > MAX_EXCERPT_LENGTH * 0.7 ? truncated.slice(0, lastSpace) : truncated) + "...";
+}
+
+// ── Manifest Summary ────────────────────────────────────────────────
+
+/**
+ * Generate a compact knowledge summary for the dispatch manifest.
+ * Not full excerpts — just posture truth.
+ *
+ * @param {Object|null} packetKnowledge
+ * @returns {Object|null} Compact summary for manifest, or null
+ */
+export function knowledgeManifestSummary(packetKnowledge) {
+  if (!packetKnowledge || packetKnowledge.status === "none") {
+    return null;
+  }
+
+  const { retrieval_bundle: bundle, status } = packetKnowledge;
+  if (!bundle) return null;
+
+  return {
+    status,
+    selected_count: bundle.selected?.length ?? 0,
+    trust_posture: bundle.provenance?.trust_posture ?? "weak",
+    freshness_posture: bundle.provenance?.freshness_posture ?? "stale",
+    warning_codes: (bundle.warnings ?? []).map((w) => w.code),
+    rerank_strategy: bundle.summary?.rerank_strategy ?? "unknown",
+  };
+}

package/src/knowledge/resolve-overlay.mjs

@@ -0,0 +1,66 @@
+/**
+ * Resolve a role overlay from knowledge/roles/*.json.
+ *
+ * Returns the overlay config for a given role, or null if no overlay exists.
+ * Roles without overlays fall back to shared-corpus-only retrieval.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+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"),
+];
+
+/**
+ * Resolve the overlay for a role.
+ *
+ * @param {string} roleId - Role identifier (e.g. "security-reviewer")
+ * @param {Object} [options]
+ * @param {string[]} [options.searchPaths] - Override overlay search paths
+ * @returns {{ overlay: object, path: string } | null}
+ */
+export function resolveOverlay(roleId, options = {}) {
+  const paths = options.searchPaths || OVERLAY_PATHS;
+
+  for (const dir of paths) {
+    const filePath = join(dir, `${roleId}.json`);
+    if (existsSync(filePath)) {
+      try {
+        const data = JSON.parse(readFileSync(filePath, "utf-8"));
+        if (data.version !== "1.0") {
+          console.warn(`[knowledge] Overlay ${roleId}: unsupported version ${data.version}`);
+          return null;
+        }
+        if (data.role_id !== roleId) {
+          console.warn(`[knowledge] Overlay file ${roleId}.json has mismatched role_id: ${data.role_id}`);
+          return null;
+        }
+        return { overlay: data, path: filePath };
+      } catch (e) {
+        console.warn(`[knowledge] Failed to parse overlay for ${roleId}:`, e.message);
+        return null;
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Check if a role has an overlay available.
+ *
+ * @param {string} roleId
+ * @param {Object} [options]
+ * @returns {boolean}
+ */
+export function hasOverlay(roleId, options = {}) {
+  return resolveOverlay(roleId, options) !== null;
+}

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

@@ -0,0 +1,150 @@
+/**
+ * Retrieve knowledge for a dispatch step.
+ *
+ * This is the integration seam between Role OS dispatch and knowledge-core.
+ * Phase 2: wired to the real retrieval pipeline.
+ *
+ * When a corpus store is available, runs the full pipeline:
+ *   task + overlay + corpus → candidates → filter → rerank → bundle
+ *
+ * When no corpus is available, returns a governed stub (graceful degradation).
+ */
+
+import { resolveOverlay } from "./resolve-overlay.mjs";
+import { applyFallbackPolicy } from "./fallback-policy.mjs";
+
+// ── Corpus Store Singleton ──────────────────────────────────────────
+// Lazy-loaded. Role OS sets this via configureKnowledge().
+let _store = null;
+let _retrieveFn = null;
+
+/**
+ * Configure the knowledge subsystem with a live corpus store.
+ * Call once at startup (e.g., in session init or dispatch init).
+ *
+ * @param {Object} options
+ * @param {Object} options.store - CorpusStore instance from knowledge-core
+ * @param {Function} options.retrieve - retrieve() function from knowledge-core
+ */
+export function configureKnowledge({ store, retrieve }) {
+  _store = store;
+  _retrieveFn = retrieve;
+}
+
+/**
+ * Check if knowledge subsystem is configured with a live corpus.
+ */
+export function isKnowledgeConfigured() {
+  return _store !== null && _retrieveFn !== null;
+}
+
+/**
+ * @typedef {Object} RetrieveOptions
+ * @property {string} roleId - Role identifier
+ * @property {string} taskText - Task description from packet
+ * @property {string} [packetContextSummary] - Optional packet context
+ * @property {Object} [routeSignals] - Route scoring signals
+ */
+
+/**
+ * Retrieve knowledge for a role's dispatch step.
+ *
+ * @param {RetrieveOptions} options
+ * @returns {Promise<{ bundle: object, status: string, fallback: object }>}
+ */
+export async function retrieveForDispatch({ roleId, taskText, packetContextSummary, routeSignals }) {
+  const overlayResult = resolveOverlay(roleId);
+  const overlay = overlayResult?.overlay ?? null;
+
+  // ── Live retrieval (Phase 2) ────────────────────────────────────
+  if (_store && _retrieveFn) {
+    const bundle = await _retrieveFn({
+      store: _store,
+      roleId,
+      taskText,
+      overlay,
+      packetContextSummary,
+      lexicalOnly: true, // Phase 2: lexical-only until embeddings are populated
+    });
+
+    const fallback = applyFallbackPolicy(bundle, overlay);
+
+    return {
+      bundle,
+      status: deriveStatus(fallback),
+      fallback,
+    };
+  }
+
+  // ── Stub fallback (no corpus configured) ────────────────────────
+  const bundle = buildStubBundle(roleId, taskText, overlayResult);
+  const fallback = applyFallbackPolicy(bundle, overlay);
+
+  return {
+    bundle,
+    status: deriveStatus(fallback),
+    fallback,
+  };
+}
+
+/**
+ * Derive packet knowledge status from fallback state.
+ */
+function deriveStatus(fallback) {
+  switch (fallback.state) {
+    case "healthy": return "strong";
+    case "no_overlay": return "none";
+    case "no_strong_match": return "weak";
+    case "stale_dominant": return "stale";
+    case "conflicting": return "conflicted";
+    case "forbidden_hit": return "strong"; // forbidden sources removed = governance working
+    default: return "weak";
+  }
+}
+
+/**
+ * Build a stub retrieval bundle when no corpus is available.
+ */
+function buildStubBundle(roleId, taskText, overlayResult) {
+  const hasOverlayData = overlayResult !== null;
+
+  return {
+    version: "1.0",
+    role_id: roleId,
+    query: {
+      task_text: taskText,
+      lexical_query: [],
+      semantic_query: [],
+      applied_overlay_rules: hasOverlayData ? [`overlay:${roleId}`] : [],
+      applied_filters: [],
+      generated_at: new Date().toISOString(),
+    },
+    summary: {
+      total_candidates: 0,
+      selected_count: 0,
+      stale_count: 0,
+      forbidden_hits: 0,
+      trust_tier_breakdown: { authoritative: 0, preferred: 0, general: 0, untrusted: 0 },
+      source_breakdown: {},
+      rerank_strategy: "stub-no-corpus",
+    },
+    selected: [],
+    rejected: [],
+    provenance: {
+      source_ids: [],
+      document_ids: [],
+      trust_posture: "weak",
+      freshness_posture: "stale",
+    },
+    warnings: [
+      { code: "ONLY_SHARED_CORPUS", message: "No corpus configured — stub bundle returned" },
+    ],
+    diagnostics: {
+      latency_ms: 0,
+      candidate_pool_size: 0,
+      deduped_count: 0,
+      dropped_forbidden_count: 0,
+      dropped_stale_count: 0,
+    },
+  };
+}

package/src/mission-run.mjs

@@ -11,6 +11,7 @@
 
 import { MISSIONS, getMission, validateMission } from "./mission.mjs";
 import { validateArtifact } from "./artifacts.mjs";
+import { STEP_TRANSITIONS, isValidStepTransition } from "./state-machine.mjs";
 
 let _runCounter = 0;
 
@@ -74,7 +75,10 @@ export function createRun(missionKey, taskDescription, options = {}) {
   let steps;
   const dd = mission.dynamicDispatch;
 
-  if (dd && options.manifest) {
+  if (missionKey === "dogfood-swarm" && dd && options.manifest) {
+    // Swarm dispatch — build staged domain steps from swarm manifest
+    steps = buildSwarmSteps(mission, options.manifest);
+  } else if (dd && options.manifest) {
     // Dynamic dispatch — build steps from manifest
     steps = buildDynamicSteps(mission, options.manifest);
   } else {
@@ -104,6 +108,7 @@ export function createRun(missionKey, taskDescription, options = {}) {
     completionReport: null,
     dynamicDispatch: dd && options.manifest ? true : false,
     manifest: options.manifest || null,
+    knowledge: options.knowledge || null, // Phase 5: PacketKnowledge from retrieval
   };
 }
 
@@ -190,6 +195,93 @@ function buildDynamicSteps(mission, manifest) {
   return steps;
 }
 
+/**
+ * Build steps from swarm manifest for dogfood-swarm missions.
+ * Creates domain agent steps per stage with coordinator gates.
+ * @param {Object} mission
+ * @param {Object} manifest - The swarm-manifest.json content
+ * @returns {MissionStep[]}
+ */
+function buildSwarmSteps(mission, manifest) {
+  const steps = [];
+  const domains = manifest.domains || [];
+  const stages = manifest.stages || ["health-a", "health-b", "health-c", "feature"];
+  const waveLoops = mission.waveLoops || [];
+
+  // For each stage, create domain agent steps + coordinator gate
+  for (const stage of stages) {
+    const loopDef = waveLoops.find(w => w.stage === stage);
+
+    // One step per domain agent
+    for (const domain of domains) {
+      steps.push({
+        role: domain.role,
+        produces: "wave-report",
+        consumedBy: "Swarm Coordinator",
+        domain: domain.id,
+        stage,
+        waveIteration: 0,
+        patterns: domain.patterns,
+        status: "pending",
+        artifact: null,
+        artifactValidation: null,
+        note: null,
+        startedAt: null,
+        completedAt: null,
+      });
+    }
+
+    // Coordinator gate step after domain agents
+    steps.push({
+      role: "Swarm Coordinator",
+      produces: "swarm-gate",
+      consumedBy: stage === stages[stages.length - 1] ? "Swarm Synthesizer" : domains[0]?.role || null,
+      stage,
+      isGate: true,
+      exitCondition: loopDef?.exitCondition || null,
+      maxIterations: loopDef?.maxIterations || 1,
+      buildGate: loopDef?.buildGate ?? true,
+      userApproval: loopDef?.userApproval ?? false,
+      lens: loopDef?.lens || null,
+      status: "pending",
+      artifact: null,
+      artifactValidation: null,
+      note: null,
+      startedAt: null,
+      completedAt: null,
+    });
+  }
+
+  // Final stage: Synthesizer + Critic
+  steps.push({
+    role: "Swarm Synthesizer",
+    produces: "swarm-final-report",
+    consumedBy: "Critic Reviewer",
+    stage: "final",
+    status: "pending",
+    artifact: null,
+    artifactValidation: null,
+    note: null,
+    startedAt: null,
+    completedAt: null,
+  });
+
+  steps.push({
+    role: "Critic Reviewer",
+    produces: "review-verdict",
+    consumedBy: null,
+    stage: "final",
+    status: "pending",
+    artifact: null,
+    artifactValidation: null,
+    note: null,
+    startedAt: null,
+    completedAt: null,
+  });
+
+  return steps;
+}
+
 // ── Step through a run ──────────────────────────────────────────────────────
 
 /**
@@ -198,6 +290,10 @@ function buildDynamicSteps(mission, manifest) {
  * @returns {MissionStep|null} The started step, or null if no pending steps
  */
 export function startNextStep(run) {
+  // Guard: refuse to activate a new step if one is already active (prevents dual-active)
+  const alreadyActive = run.steps.find((s) => s.status === "active");
+  if (alreadyActive) return null;
+
   const next = run.steps.find((s) => s.status === "pending");
   if (!next) return null;
 
@@ -386,6 +482,7 @@ export function generateCompletionReport(run) {
     status: s.status,
     hasArtifact: !!s.artifact,
     note: s.note,
+    knowledge: s.knowledge || null, // Phase 5: per-step knowledge posture
   }));
 
   const isComplete = run.status === "completed";
@@ -408,6 +505,13 @@ export function generateCompletionReport(run) {
     artifactChain,
     escalationCount: run.escalations.length,
     escalations: run.escalations,
+    knowledge: run.knowledge ? {
+      status: run.knowledge.status,
+      selected_count: run.knowledge.retrieval_bundle?.selected?.length ?? 0,
+      trust_posture: run.knowledge.retrieval_bundle?.provenance?.trust_posture ?? "unknown",
+      freshness_posture: run.knowledge.retrieval_bundle?.provenance?.freshness_posture ?? "unknown",
+      warning_codes: (run.knowledge.retrieval_bundle?.warnings ?? []).map((w) => w.code),
+    } : null,
     honestPartial: isPartial || isFailed ? mission.honestPartial : null,
     verdict: isComplete
       ? "Mission completed — all artifacts produced, all steps passed."
@@ -453,7 +557,20 @@ export function formatCompletionReport(report) {
                  step.status === "blocked" ? "[-]" : "[ ]";
     const artifact = step.hasArtifact ? ` → ${step.produces}` : "";
     const note = step.note ? ` (${step.note})` : "";
-    lines.push(`  ${icon} ${step.role}${artifact}${note}`);
+    const kStatus = step.knowledge ? ` [knowledge: ${step.knowledge.status}]` : "";
+    lines.push(`  ${icon} ${step.role}${artifact}${kStatus}${note}`);
+  }
+
+  // Knowledge posture (Phase 5)
+  if (report.knowledge) {
+    lines.push("");
+    lines.push("## Knowledge");
+    lines.push(`  Status: ${report.knowledge.status}`);
+    lines.push(`  Evidence: ${report.knowledge.selected_count} chunks selected`);
+    lines.push(`  Trust: ${report.knowledge.trust_posture} | Freshness: ${report.knowledge.freshness_posture}`);
+    if (report.knowledge.warning_codes.length > 0) {
+      lines.push(`  Warnings: ${report.knowledge.warning_codes.join(", ")}`);
+    }
   }
 
   if (report.escalationCount > 0) {