mindforge-cc 11.0.0 → 11.2.0

package/bin/dashboard/server.js

@@ -161,7 +161,7 @@ app.use((req, res, next) => {
   res.setHeader('X-Content-Type-Options', 'nosniff');
   res.setHeader('X-Frame-Options', 'DENY');
   res.setHeader('Cache-Control', 'no-store'); // Never cache dashboard responses
-  res.setHeader('Content-Security-Policy', "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; connect-src 'self'");
+  res.setHeader('Content-Security-Policy', 'default-src \'self\'; script-src \'self\'; style-src \'self\' \'unsafe-inline\'; connect-src \'self\'');
   res.setHeader('X-XSS-Protection', '1; mode=block');
   res.setHeader('Referrer-Policy', 'strict-origin-when-cross-origin');
   next();

package/bin/dashboard/sse-bridge.js

@@ -21,7 +21,6 @@ const APPROVAL_DIR    = path.join(process.cwd(), '.planning', 'approvals');
 const clients = new Set(); // Connected SSE response objects
 
 let _lastAuditSize  = 0;
-let _auditInode     = 0; // Track file inode for rotation detection
 let _lastAutoState  = '';
 let _lastApprovals  = '';
 
@@ -78,14 +77,16 @@ function pollAuditLog() {
   try {
     const stat     = fs.statSync(AUDIT_PATH);
     const newSize  = stat.size;
-    const newIno   = stat.ino;
 
-    // File rotation detected: inode changed or file shrunk (truncated after archival)
-    if ((newIno !== _auditInode && _auditInode !== 0) || (newSize < _lastAuditSize)) {
-      process.stderr.write(`[sse-bridge] AUDIT.jsonl rotation detected (size: ${_lastAuditSize} -> ${newSize}, ino: ${_auditInode} -> ${newIno})\n`);
+    // Truncation / recreation recovery (NOT rotation — audit rotation was retired in
+    // UC-04b because it broke the hash chain; AUDIT.jsonl grows unbounded). If the
+    // file ever SHRINKS (manually truncated, .planning wiped, or replaced), reset the
+    // read offset to 0 so the live tail keeps working instead of stalling forever on
+    // the `newSize <= _lastAuditSize` early-return below or reading at a stale offset.
+    if (newSize < _lastAuditSize) {
+      process.stderr.write(`[sse-bridge] AUDIT.jsonl shrank (size: ${_lastAuditSize} -> ${newSize}) — re-tailing from start\n`);
       _lastAuditSize = 0;
     }
-    _auditInode = newIno;
 
     if (newSize <= _lastAuditSize) return;
 
@@ -169,9 +170,7 @@ function startPolling() {
 
   // Initialize AUDIT position on first start
   if (!_initialized && fs.existsSync(AUDIT_PATH)) {
-    const stat = fs.statSync(AUDIT_PATH);
-    _lastAuditSize = stat.size;
-    _auditInode    = stat.ino;
+    _lastAuditSize = fs.statSync(AUDIT_PATH).size;
     _initialized   = true;
   }
 
@@ -207,9 +206,7 @@ function stopPolling() {
 function start() {
   // Pre-initialize AUDIT position so first client gets instant data
   if (!_initialized && fs.existsSync(AUDIT_PATH)) {
-    const stat = fs.statSync(AUDIT_PATH);
-    _lastAuditSize = stat.size;
-    _auditInode    = stat.ino;
+    _lastAuditSize = fs.statSync(AUDIT_PATH).size;
     _initialized   = true;
   }
   // Polling starts lazily when addClient() is called

package/bin/engine/council-runtime.js

@@ -0,0 +1,124 @@
+'use strict';
+/**
+ * MindForge — Council Runtime (UC-10). Thin multi-voice decision harness (ADS).
+ *
+ * Activates the Adversarial Decision Loop (ADS) mandated by CLAUDE.md: instead of
+ * a multi-round debate simulator, this is a THIN runtime — parallel position
+ * collection (one per voice) + consensus scoring + dissent capture.
+ *
+ * The model is INJECTABLE (no hard LLM dependency) so callers/tests can supply a
+ * mock. The Semaphore from wave-executor is reused to bound concurrent voice calls.
+ *
+ * Design decision — NO challenge round (kept thin per adversarial review + YAGNI):
+ * A second model call per dissenter that folds a revised confidence back into the
+ * consensus adds ordering/weighting complexity and extra failure modes without
+ * changing the activation goal. Position-collection + consensus fully satisfies the
+ * ADS loop and the verdict contract. Add a challenge round only if a concrete need
+ * arises (an explicit `opts.challengeRound` flag would be the clean extension point).
+ *
+ * Filenames use opts.decisionId (NOT Date.now(), which is unavailable in some
+ * MindForge execution contexts); falls back to "council-latest.json".
+ */
+const fs = require('fs');
+const path = require('path');
+const { Semaphore } = require('../autonomous/wave-executor');
+
+const DEFAULT_VOICES = ['architect', 'skeptic', 'pragmatist', 'critic'];
+const VALID_RECOMMENDATIONS = ['PROCEED', 'REVISE'];
+
+/**
+ * Validates a single voice's position payload. Throws a clear, voice-named error
+ * on a malformed payload rather than letting it degrade into NaN consensus.
+ * @param {string} voice — The voice that produced the position (for the error message).
+ * @param {object} position — The raw position returned by the model.
+ */
+function validatePosition(voice, position) {
+  if (!position || typeof position !== 'object') {
+    throw new Error(`Council voice "${voice}" returned an invalid position: expected an object, got ${position === null ? 'null' : typeof position}`);
+  }
+  if (!VALID_RECOMMENDATIONS.includes(position.recommendation)) {
+    throw new Error(`Council voice "${voice}" returned an invalid position: recommendation must be one of ${VALID_RECOMMENDATIONS.join('/')}, got ${JSON.stringify(position.recommendation)}`);
+  }
+  if (typeof position.confidence !== 'number' || !Number.isFinite(position.confidence) || position.confidence < 0 || position.confidence > 1) {
+    throw new Error(`Council voice "${voice}" returned an invalid position: confidence must be a number in [0,1], got ${position.confidence}`);
+  }
+}
+
+/**
+ * Runs a thin adversarial council over a question.
+ * @param {string} question — The decision/question put to the council.
+ * @param {object} [opts]
+ * @param {string[]} [opts.voices] — Voice personas to consult (default: 4 ADS voices).
+ * @param {number} [opts.consensusThreshold=0.75] — Threshold for PROCEED/REVISE.
+ * @param {function} opts.model — REQUIRED. async ({voice, question}) =>
+ *   { recommendation: 'PROCEED'|'REVISE', confidence: number(0..1), rationale: string }
+ * @param {number} [opts.maxConcurrency] — Bound on parallel voice calls (default: #voices).
+ * @param {boolean} [opts.writeDecision=true] — Persist a decision record to disk.
+ * @param {string} [opts.outputPath] — Directory for the record (default: .planning/decisions).
+ * @param {string} [opts.decisionId] — Stable id used in the filename (no Date.now()).
+ * @returns {Promise<{question,positions,consensus,verdict,dissent}>}
+ */
+async function runCouncil(question, opts = {}) {
+  const voices = Array.isArray(opts.voices) && opts.voices.length > 0
+    ? opts.voices
+    : DEFAULT_VOICES;
+  const consensusThreshold = opts.consensusThreshold ?? 0.75;
+  const model = opts.model;
+  if (typeof model !== 'function') {
+    throw new Error('runCouncil requires an injectable model function (opts.model)');
+  }
+  const maxConcurrency = opts.maxConcurrency || voices.length;
+
+  // Parallel position collection — bounded by the reused Semaphore.
+  const sem = new Semaphore(maxConcurrency);
+  const positions = await Promise.all(voices.map(async (voice) => {
+    await sem.acquire();
+    try {
+      const position = await model({ voice, question });
+      // Validate the payload immediately — never silently swallow a malformed
+      // position into NaN consensus (which would collapse to NO_CONSENSUS and
+      // write NaN to the decision record).
+      validatePosition(voice, position);
+      return { voice, ...position };
+    } finally {
+      sem.release();
+    }
+  }));
+
+  // Consensus = mean approval signal across voices.
+  // A PROCEED contributes its confidence; a REVISE contributes its inverse
+  // (so a high-confidence REVISE pulls consensus down hard).
+  const consensus = positions.reduce((sum, p) => {
+    const approval = p.recommendation === 'PROCEED' ? p.confidence : (1 - p.confidence);
+    return sum + approval;
+  }, 0) / positions.length;
+
+  const verdict = consensus >= consensusThreshold ? 'PROCEED'
+    : consensus <= (1 - consensusThreshold) ? 'REVISE'
+    : 'NO_CONSENSUS';
+
+  // Dissent capture:
+  // - For a decisive verdict (PROCEED/REVISE): the voices opposing that direction.
+  // - For NO_CONSENSUS (the deadlock ADS most needs documented): the FULL split —
+  //   every voice's {voice, recommendation, rationale} — so the decision record
+  //   preserves both camps rather than recording an empty dissent list.
+  const dissent = verdict === 'NO_CONSENSUS'
+    ? positions.map((p) => ({ voice: p.voice, recommendation: p.recommendation, rationale: p.rationale }))
+    : positions.filter((p) =>
+        (verdict === 'PROCEED' && p.recommendation !== 'PROCEED') ||
+        (verdict === 'REVISE' && p.recommendation === 'PROCEED'))
+      .map((d) => ({ voice: d.voice, rationale: d.rationale }));
+
+  const result = { question, positions, consensus, verdict, dissent };
+
+  if (opts.writeDecision !== false) {
+    const dir = opts.outputPath || path.join(process.cwd(), '.planning', 'decisions');
+    fs.mkdirSync(dir, { recursive: true });
+    const name = opts.decisionId ? `council-${opts.decisionId}.json` : 'council-latest.json';
+    fs.writeFileSync(path.join(dir, name), JSON.stringify(result, null, 2));
+  }
+
+  return result;
+}
+
+module.exports = { runCouncil };

package/bin/engine/otel-exporter.js

@@ -0,0 +1,123 @@
+'use strict';
+/**
+ * MindForge — OTel GenAI Exporter (UC-18).
+ * Translates NexusTracer spans to OpenTelemetry GenAI semantic conventions.
+ * Active only when OTEL_EXPORTER_OTLP_ENDPOINT is set.
+ *
+ * NexusTracer span shape (from nexus-tracer.js startSpan/endSpan):
+ *   {
+ *     id: 'sp_<hex>',
+ *     trace_id: 'tr_<hex>',
+ *     parent_id: string|null,
+ *     name: string,
+ *     status: 'active'|'success'|'error',
+ *     start_time: ISO-8601,
+ *     end_time: ISO-8601,
+ *     attributes: {
+ *       service: string,
+ *       host: string,
+ *       pid: number,
+ *       model_id?: string,
+ *       skill?: string,
+ *       input_tokens?: number,
+ *       output_tokens?: number,
+ *       ...
+ *     }
+ *   }
+ *
+ * Mapping to OTel GenAI semantic conventions:
+ *   span.name → name
+ *   span.attributes.model_id → gen_ai.request.model, gen_ai.response.model
+ *   span.attributes.input_tokens → gen_ai.usage.input_tokens
+ *   span.attributes.output_tokens → gen_ai.usage.output_tokens
+ *   span.name → gen_ai.operation.name
+ *   'mindforge' → gen_ai.system (or span.attributes.provider if present)
+ */
+
+const crypto = require('crypto');
+
+/**
+ * Check if the OTel exporter is enabled (env var gate).
+ * @returns {boolean}
+ */
+function isEnabled() {
+  return !!process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
+}
+
+/**
+ * Translate a NexusTracer span to OTel GenAI-compatible format.
+ * Produces a valid 16-byte hex traceId and 8-byte hex spanId.
+ *
+ * @param {object} nexusSpan - A span object from NexusTracer
+ * @returns {object} OTel-compatible span object
+ */
+function toOtelSpan(nexusSpan) {
+  const attrs = nexusSpan.attributes || {};
+
+  return {
+    traceId: crypto.randomBytes(16).toString('hex'),
+    spanId: crypto.randomBytes(8).toString('hex'),
+    parentSpanId: nexusSpan.parent_id || '',
+    name: nexusSpan.name || 'unknown',
+    kind: 1, // SPAN_KIND_INTERNAL
+    startTimeUnixNano: nexusSpan.start_time
+      ? BigInt(new Date(nexusSpan.start_time).getTime()) * 1_000_000n
+      : 0n,
+    endTimeUnixNano: nexusSpan.end_time
+      ? BigInt(new Date(nexusSpan.end_time).getTime()) * 1_000_000n
+      : 0n,
+    status: nexusSpan.status === 'success' ? { code: 1 } : { code: 2 },
+    attributes: {
+      'gen_ai.system': attrs.provider || 'mindforge',
+      'gen_ai.request.model': attrs.model_id || '',
+      'gen_ai.response.model': attrs.model_id || '',
+      'gen_ai.usage.input_tokens': attrs.input_tokens || 0,
+      'gen_ai.usage.output_tokens': attrs.output_tokens || 0,
+      'gen_ai.operation.name': nexusSpan.name || '',
+      'service.name': attrs.service || 'mindforge-nexus',
+    },
+  };
+}
+
+/**
+ * Serialize BigInt values to strings for JSON compatibility.
+ * @param {object} otelSpan
+ * @returns {object}
+ */
+function toJsonSafe(otelSpan) {
+  return {
+    ...otelSpan,
+    startTimeUnixNano: String(otelSpan.startTimeUnixNano),
+    endTimeUnixNano: String(otelSpan.endTimeUnixNano),
+  };
+}
+
+/**
+ * Export a NexusTracer span to the OTel-compatible local file.
+ * In production, this would POST to OTEL_EXPORTER_OTLP_ENDPOINT/v1/traces.
+ * For now, appends to .mindforge/metrics/otel-spans.jsonl for verification.
+ *
+ * @param {object} nexusSpan - A span from NexusTracer
+ */
+async function exportSpan(nexusSpan) {
+  if (!isEnabled()) return;
+
+  const otelSpan = toOtelSpan(nexusSpan);
+  const jsonSafe = toJsonSafe(otelSpan);
+
+  const fs = require('fs');
+  const path = require('path');
+  const outPath = path.join(process.cwd(), '.mindforge', 'metrics', 'otel-spans.jsonl');
+
+  try {
+    const dir = path.dirname(outPath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.appendFileSync(outPath, JSON.stringify(jsonSafe) + '\n');
+  } catch {
+    // Non-fatal: observability export should never break the main flow
+  }
+}
+
+module.exports = { isEnabled, toOtelSpan, toJsonSafe, exportSpan };

package/bin/engine/remediation-engine.js

@@ -1,5 +1,5 @@
 /**
- * MindForge v11.0.0 — Neural Drift Remediation (NDR)
+ * MindForge v11.1.0 — Neural Drift Remediation (NDR)
  * Component: Remediation Engine (Pillar X)
  *
  * Triggers corrective actions when logic drift or reasoning

package/bin/engine/self-corrective-synthesizer.js

@@ -1,5 +1,5 @@
 /**
- * MindForge v11.0.0 — Self-Corrective Synthesis (SCS)
+ * MindForge v11.1.0 — Self-Corrective Synthesis (SCS)
  * Component: Self-Corrective Synthesizer (Pillar XII)
  *
  * Analyzes mission drift and logic stagnation to synthesize

package/bin/engine/temporal-cli.js

@@ -12,7 +12,7 @@ const SUBCOMMAND = ARGS[0];
 
 async function main() {
   switch (SUBCOMMAND) {
-    case 'status':
+    case 'status': {
       const history = TemporalHub.getHistory();
       console.log('\n⏳  MindForge Temporal Status');
       console.log(`    Snapshots:  ${history.length}`);
@@ -20,6 +20,7 @@ async function main() {
         console.log(`    Latest:     ${history[0].id} (${history[0].timestamp})`);
       }
       break;
+    }
 
     case 'cleanup':
       console.log('🧹 Cleaning up old temporal snapshots...');
@@ -27,7 +28,7 @@ async function main() {
       console.log('✅ Cleanup complete.');
       break;
 
-    case 'inject':
+    case 'inject': {
       const auditId = ARGS[1];
       const fix = ARGS.slice(2).join(' ');
       if (!auditId || !fix) {
@@ -42,6 +43,7 @@ async function main() {
         process.exit(1);
       }
       break;
+    }
 
     default:
       console.log('Usage: /mindforge:temporal <status|cleanup|inject>');

package/bin/engine/verification-runner.js

@@ -0,0 +1,131 @@
+'use strict';
+
+const { execSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const MAX_OUTPUT_LENGTH = 2000;
+
+/**
+ * Stage definitions — each maps a stage name to its command and optional skip condition.
+ * The tests stage guards against recursion: if NODE_ENV=test (set by run-all.js) or
+ * MINDFORGE_VERIFICATION_ACTIVE=1 (set by this runner), we skip to prevent infinite nesting.
+ */
+const STAGE_DEFS = {
+  tests: {
+    command: 'node tests/run-all.js',
+    skipIf: () =>
+      process.env.MINDFORGE_VERIFICATION_ACTIVE === '1' ||
+      process.env.NODE_ENV === 'test',
+  },
+  lint: {
+    command: 'npx eslint . --max-warnings=0',
+    skipIf: null,
+  },
+  audit: {
+    command: 'node bin/verify-audit.js',
+    skipIf: null,
+  },
+  typecheck: {
+    command: 'npx tsc --noEmit',
+    skipIf: (cwd) => !fs.existsSync(path.join(cwd, 'tsconfig.json')),
+  },
+};
+
+/**
+ * Run a single stage, returning a structured result object.
+ */
+function executeStage(name, cwd) {
+  const def = STAGE_DEFS[name];
+  if (!def) {
+    return { name, status: 'skip', durationMs: 0, output: `Unknown stage: ${name}` };
+  }
+
+  // Check skip condition
+  if (def.skipIf && def.skipIf(cwd)) {
+    return { name, status: 'skip', durationMs: 0, output: '' };
+  }
+
+  const start = Date.now();
+  let output = '';
+  let status = 'pass';
+
+  try {
+    const env = Object.assign({}, process.env, {
+      MINDFORGE_VERIFICATION_ACTIVE: '1',
+    });
+    const result = execSync(def.command, {
+      cwd,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: 120000,
+      env,
+    });
+    output = (result || '').slice(0, MAX_OUTPUT_LENGTH);
+  } catch (err) {
+    status = 'fail';
+    const stdout = err.stdout || '';
+    const stderr = err.stderr || '';
+    output = (stdout + '\n' + stderr).trim().slice(0, MAX_OUTPUT_LENGTH);
+  }
+
+  const durationMs = Date.now() - start;
+  return { name, status, durationMs, output };
+}
+
+/**
+ * Run verification across multiple stages.
+ * @param {{ cwd: string, stages: string[] }} opts
+ * @returns {Promise<object>} Structured verification result
+ */
+async function runVerification({ cwd, stages }) {
+  const resolvedCwd = path.resolve(cwd);
+  const results = [];
+
+  for (const stageName of stages) {
+    const result = executeStage(stageName, resolvedCwd);
+    results.push(result);
+  }
+
+  const passed = results.filter(s => s.status === 'pass').length;
+  const failed = results.filter(s => s.status === 'fail').length;
+  const skipped = results.filter(s => s.status === 'skip').length;
+  const totalDurationMs = results.reduce((sum, s) => sum + s.durationMs, 0);
+
+  return {
+    stages: results,
+    summary: { passed, failed, skipped, totalDurationMs },
+    timestamp: new Date().toISOString(),
+  };
+}
+
+/**
+ * Format a verification result as a markdown report.
+ * @param {object} result — output from runVerification
+ * @returns {string} Markdown report
+ */
+function formatReport(result) {
+  const statusEmoji = { pass: '✅', fail: '❌', skip: '⏭️' };
+  const lines = [];
+
+  lines.push('# Verification Report');
+  lines.push('');
+  lines.push(`**Timestamp:** ${result.timestamp}`);
+  lines.push('');
+  lines.push('| Stage | Status | Duration |');
+  lines.push('|-------|--------|----------|');
+
+  for (const stage of result.stages) {
+    const emoji = statusEmoji[stage.status] || '?';
+    const duration = stage.durationMs > 0 ? `${stage.durationMs}ms` : '-';
+    lines.push(`| ${stage.name} | ${emoji} ${stage.status} | ${duration} |`);
+  }
+
+  lines.push('');
+  lines.push(`**Summary:** ${result.summary.passed} passed, ${result.summary.failed} failed, ${result.summary.skipped} skipped (${result.summary.totalDurationMs}ms total)`);
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+module.exports = { runVerification, formatReport };

package/bin/engine/verify-cli.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * verify-cli.js — Entrypoint for the `verify` CLI command.
+ * Calls the unified verification runner across all stages and writes
+ * the formatted report to .planning/VERIFICATION.md.
+ */
+
+const path = require('path');
+const fs = require('fs');
+const { runVerification, formatReport } = require('./verification-runner');
+
+const STAGES = ['tests', 'lint', 'audit', 'typecheck'];
+const CWD = process.env.MINDFORGE_ROOT || path.resolve(__dirname, '../..');
+
+async function main() {
+  const planningDir = path.join(CWD, '.planning');
+  if (!fs.existsSync(planningDir)) {
+    fs.mkdirSync(planningDir, { recursive: true });
+  }
+
+  const result = await runVerification({ cwd: CWD, stages: STAGES });
+  const report = formatReport(result);
+
+  fs.writeFileSync(path.join(planningDir, 'VERIFICATION.md'), report);
+  process.stdout.write(report + '\n');
+  process.exit(result.summary.failed > 0 ? 1 : 0);
+}
+
+main().catch(err => {
+  console.error('Verification runner failed:', err.message);
+  process.exit(1);
+});

package/bin/eval/eval-harness.js

@@ -0,0 +1,82 @@
+'use strict';
+
+/**
+ * Recall@K — fraction of relevant items found in the top-k retrieved results.
+ * @param {string[]} retrieved - IDs in ranked order
+ * @param {string[]} relevant - ground-truth relevant IDs
+ * @param {number} k - cutoff
+ * @returns {number} recall in [0, 1]
+ */
+function recallAtK(retrieved, relevant, k) {
+  if (relevant.length === 0) return 0;
+  const topK = retrieved.slice(0, k);
+  const relevantSet = new Set(relevant);
+  const found = topK.filter(id => relevantSet.has(id)).length;
+  return found / relevant.length;
+}
+
+/**
+ * nDCG (Normalized Discounted Cumulative Gain) with graded relevance.
+ * @param {string[]} retrieved - IDs in ranked order
+ * @param {Object.<string, number>} relevanceMap - {id: grade} where grade is 0-3
+ * @param {number} k - cutoff
+ * @returns {number} nDCG in [0, 1]
+ */
+function ndcg(retrieved, relevanceMap, k) {
+  const topK = retrieved.slice(0, k);
+
+  // DCG = Σ (2^rel_i - 1) / log2(i + 2) for i = 0..k-1
+  const dcg = topK.reduce((sum, id, i) => {
+    const rel = relevanceMap[id] || 0;
+    return sum + (Math.pow(2, rel) - 1) / Math.log2(i + 2);
+  }, 0);
+
+  // IDCG — ideal ordering: sort all relevance grades descending, take top-k
+  const idealGrades = Object.values(relevanceMap)
+    .filter(g => g > 0)
+    .sort((a, b) => b - a)
+    .slice(0, k);
+
+  const idcg = idealGrades.reduce((sum, rel, i) => {
+    return sum + (Math.pow(2, rel) - 1) / Math.log2(i + 2);
+  }, 0);
+
+  if (idcg === 0) return 0;
+  return dcg / idcg;
+}
+
+/**
+ * Run a full evaluation over a golden set of queries.
+ * @param {Object} opts
+ * @param {Array<{query: string, relevant: string[]}>} opts.goldenSet
+ * @param {function(string): string[]} opts.retriever
+ * @param {number} opts.k
+ * @returns {Promise<{meanRecallAtK: number, meanNDCG: number, perQuery: Array}>}
+ */
+async function runEval({ goldenSet, retriever, k }) {
+  const perQuery = [];
+
+  for (const { query, relevant } of goldenSet) {
+    const retrieved = await Promise.resolve(retriever(query));
+
+    // Binary relevance map: relevant items get grade 1, others 0
+    const relevanceMap = {};
+    for (const id of relevant) {
+      relevanceMap[id] = 1;
+    }
+
+    const recall = recallAtK(retrieved, relevant, k);
+    const ndcgScore = ndcg(retrieved, relevanceMap, k);
+
+    perQuery.push({ query, recall, ndcg: ndcgScore, retrieved });
+  }
+
+  if (perQuery.length === 0) return { meanRecallAtK: 0, meanNDCG: 0, perQuery: [] };
+
+  const meanRecallAtK = perQuery.reduce((s, q) => s + q.recall, 0) / perQuery.length;
+  const meanNDCG = perQuery.reduce((s, q) => s + q.ndcg, 0) / perQuery.length;
+
+  return { meanRecallAtK, meanNDCG, perQuery };
+}
+
+module.exports = { recallAtK, ndcg, runEval };

package/bin/eval/golden-set-retrieval.json

@@ -0,0 +1,46 @@
+{
+  "description": "Golden set for retrieval quality evaluation. Each entry has a natural-language query and the IDs of documents that SHOULD be retrieved.",
+  "version": "1.0.0",
+  "queries": [
+    {
+      "query": "how does the audit hash chain work",
+      "relevant": ["audit-hash", "audit-verifier", "verify-audit"]
+    },
+    {
+      "query": "what model should I use for a security-sensitive task",
+      "relevant": ["difficulty-scorer", "model-router", "pricing-registry", "trust-boundaries"]
+    },
+    {
+      "query": "how does wave execution and parallel orchestration work",
+      "relevant": ["wave-executor", "swarm-controller", "auto-executor"]
+    },
+    {
+      "query": "how do I track token costs and budget enforcement",
+      "relevant": ["cost-tracker", "token-ledger", "budget-enforcer", "finops-hub"]
+    },
+    {
+      "query": "how does the knowledge store persist and retrieve entries",
+      "relevant": ["knowledge-store", "knowledge-graph-protocol", "shard-controller"]
+    },
+    {
+      "query": "what happens during council consensus and synthesis",
+      "relevant": ["council-protocol", "synthesis-engine", "council-templates"]
+    },
+    {
+      "query": "how do instincts get captured and promoted to skills",
+      "relevant": ["capture-engine", "promotion-engine", "instinct-schema", "skill-registry"]
+    },
+    {
+      "query": "what verification checks run before marking a task complete",
+      "relevant": ["verification-pipeline", "trust-verifier", "policy-engine"]
+    },
+    {
+      "query": "how does the autonomous stuck detector recover failed tasks",
+      "relevant": ["stuck-detector", "node-repair", "steering-manager", "progress-reporter"]
+    },
+    {
+      "query": "how are hooks triggered and what security gates exist pre-commit",
+      "relevant": ["trust-gate-hook", "instinct-capture-hook", "policy-gate-hardened", "impact-analyzer"]
+    }
+  ]
+}

package/bin/governance/audit-hash.js

@@ -0,0 +1,12 @@
+'use strict';
+const crypto = require('crypto');
+/**
+ * Canonical audit hash material. MUST be the single source of truth for both
+ * the writer (pre-_hash entry) and the verifier (entry with _hash stripped).
+ * Hashes {...entry, previous_hash} — entry must NOT contain _hash.
+ */
+function hashAuditEntry(entryWithoutHash, previousHash) {
+  const material = JSON.stringify({ ...entryWithoutHash, previous_hash: previousHash });
+  return crypto.createHash('sha256').update(material).digest('hex');
+}
+module.exports = { hashAuditEntry };