mindforge-cc 11.0.0 → 11.2.0

package/bin/governance/audit-verifier.js

@@ -0,0 +1,60 @@
+'use strict';
+/**
+ * MindForge — Audit chain verifier (UC-04). Fail-closed: any break => valid:false.
+ *
+ * Walks the JSONL audit log line-by-line and re-derives each entry's hash from its
+ * content plus the prior entry's hash. The chain is valid only if EVERY link holds:
+ *   1. entry.previous_hash matches the running previousHash (null for the first entry)
+ *   2. entry._hash equals sha256({...entry-without-_hash, previous_hash})
+ *
+ * CRITICAL INVARIANT: hashEntry() here MUST produce byte-identical material to the
+ * writer (bin/autonomous/audit-writer.js). The writer hashes {...e, previous_hash}
+ * where `e` has no `_hash`. The stored entry is {...e, previous_hash, _hash}; stripping
+ * `_hash` via destructuring yields {...e, previous_hash} with the SAME key insertion
+ * order, so {...rest, previous_hash} reproduces the writer's material exactly.
+ */
+const fs = require('fs');
+const { hashAuditEntry } = require('./audit-hash');
+
+/**
+ * Re-derives an entry's chained hash. Excludes `_hash` from the material by
+ * stripping it, then delegating to the canonical {@link hashAuditEntry} so the
+ * writer and verifier share ONE hasher (no material drift possible).
+ * @param {object} entry — stored entry (may include `_hash`, which is stripped)
+ * @param {string|null} previousHash — prior entry's `_hash` (null for the first link)
+ * @returns {string} hex-encoded SHA-256 digest
+ */
+function hashEntry(entry, previousHash) {
+  const { _hash, ...rest } = entry; // exclude _hash from material
+  return hashAuditEntry(rest, previousHash);
+}
+
+/**
+ * Verifies the integrity of a hash-chained audit log. Fail-closed.
+ * @param {string} auditPath — path to the AUDIT.jsonl file
+ * @returns {{ valid: boolean, count: number, brokenAt?: number, reason?: string }}
+ */
+function verifyAuditChain(auditPath) {
+  let lines;
+  try { lines = fs.readFileSync(auditPath, 'utf8').split('\n').filter(Boolean); }
+  catch (e) { return { valid: false, count: 0, brokenAt: 0, reason: `unreadable: ${e.message}` }; }
+
+  let previousHash = null;
+  for (let i = 0; i < lines.length; i++) {
+    let entry;
+    try { entry = JSON.parse(lines[i]); }
+    catch { return { valid: false, count: lines.length, brokenAt: i, reason: 'unparseable line' }; }
+
+    if (entry.previous_hash !== previousHash) {
+      return { valid: false, count: lines.length, brokenAt: i, reason: 'previous_hash mismatch' };
+    }
+    const expected = hashEntry(entry, previousHash);
+    if (entry._hash !== expected) {
+      return { valid: false, count: lines.length, brokenAt: i, reason: 'hash mismatch (entry mutated)' };
+    }
+    previousHash = entry._hash;
+  }
+  return { valid: true, count: lines.length };
+}
+
+module.exports = { verifyAuditChain };

package/bin/governance/quantum-crypto.js

@@ -10,20 +10,59 @@
 const crypto = require('node:crypto');
 const configManager = require('./config-manager');
 
+/**
+ * Honest-disclosure guard message. The signatures produced by this module are
+ * SIMULATED Dilithium-5 (base64(SHA3 + random) — NOT real ML-DSA/FIPS-204
+ * lattice crypto). They must NEVER sit on the live trust path silently. The
+ * simulated implementation is preserved for demonstration only and is gated
+ * behind an explicit, opt-in flag.
+ */
+const PQC_DEMO_DISABLED_MSG =
+  'PQC demo disabled — set experimental.pqc_demo=true to use simulated lattice crypto (NOT for production trust)';
+
 class QuantumCrypto {
   constructor() {
     this.providerId = configManager.get('security.provider', 'simulated-lattice');
-    this.pqasEnabled = configManager.get('security.pqas_enabled', true);
+    // UC-24: simulated PQC is OFF the live trust path by default. Real PQC has
+    // not shipped. The simulated path is gated SOLELY behind the explicit
+    // experimental.pqc_demo opt-in (read fresh via isPqcDemoEnabled), so there
+    // is exactly one switch controlling the simulated minter. The legacy
+    // security.pqas_enabled flag is retained for provider metadata only and
+    // MUST NOT independently gate minting (see getProvider).
+    this.pqasEnabled = configManager.get('security.pqas_enabled', false);
+  }
+
+  /**
+   * Returns true only when the operator has explicitly opted into the SIMULATED
+   * post-quantum demo. Read fresh from config so a runtime toggle is honored.
+   * @returns {boolean}
+   */
+  isPqcDemoEnabled() {
+    return configManager.get('experimental.pqc_demo', false) === true;
+  }
+
+  /**
+   * Hard gate: throws unless the operator has explicitly enabled the simulated
+   * PQC demo. Prevents simulated (false-assurance) signatures from silently
+   * landing on the live trust path.
+   */
+  _assertPqcDemoEnabled() {
+    if (!this.isPqcDemoEnabled()) {
+      throw new Error(PQC_DEMO_DISABLED_MSG);
+    }
   }
 
   /**
    * Returns the current active crypto provider.
    */
   getProvider() {
-    // In v7, this would resolve to a real provider like 'oqs-provider.js'
+    // In v7, this would resolve to a real provider like 'oqs-provider.js'.
+    // Read pqas_enabled FRESH from config (not the constructor cache) for
+    // symmetry with the demo gate. This is metadata only — it does NOT gate
+    // minting; experimental.pqc_demo is the single source of truth for that.
     return {
       id: this.providerId,
-      pqas_enabled: this.pqasEnabled,
+      pqas_enabled: configManager.get('security.pqas_enabled', false),
       algorithm: 'Dilithium-5'
     };
   }
@@ -32,7 +71,10 @@ class QuantumCrypto {
    * Generates a key pair using the configured PQ provider.
    */
   async generateLatticeKeyPair() {
-    if (!this.pqasEnabled) throw new Error('PQAS is disabled in configuration.');
+    // UC-24: simulated keys are demo-only. The SINGLE gate is the fresh-read
+    // experimental.pqc_demo flag — enabling it is sufficient to mint, and
+    // disabling it fails closed. security.pqas_enabled does NOT gate this.
+    this._assertPqcDemoEnabled();
 
     // Simulate high-entropy lattice seeds
     const seed = crypto.randomBytes(64).toString('hex');
@@ -53,7 +95,11 @@ class QuantumCrypto {
    * @returns {{ signature: string, simulated: true, algorithm: string }}
    */
   async signPQ(data, privateKey) {
-    if (!this.pqasEnabled) throw new Error('PQAS is disabled.');
+    // UC-24: never produce a simulated (false-assurance) signature on the live
+    // trust path. The SINGLE gate is the fresh-read experimental.pqc_demo flag
+    // (same flag _selectProvider routes on) — security.pqas_enabled does NOT
+    // independently block signing.
+    this._assertPqcDemoEnabled();
     if (!privateKey.startsWith('mfq7_dilithium5_priv_')) {
       throw new Error('Invalid Post-Quantum private key format.');
     }
@@ -92,19 +138,27 @@ class QuantumCrypto {
   }
 
   /**
-   * Generates a simulated ZK-Proof of policy adherence.
-   * This mimics a SNARK where the agent proves it ran the PolicyEngine rules.
+   * Generates a SIMULATED ZK-Proof of policy adherence.
+   * This mimics a SNARK where the agent proves it ran the PolicyEngine rules,
+   * but it is NOT a real zero-knowledge proof. The returned token is explicitly
+   * stamped with a `sim` marker (zkp_v1_sim_...) so downstream code and audit
+   * logs can never mistake it for a real SNARK. It remains inert by default —
+   * verifyZKProof DENYs unless an external verifier module is configured.
+   * @returns {string} A simulated ZK-proof token prefixed `zkp_v1_sim_`.
    */
   generateZKProof(intent, result) {
     const proofPayload = JSON.stringify({
       intent: intent.id,
       verdict: result.verdict,
       timestamp: Date.now(),
-      entropy: crypto.randomBytes(16).toString('hex')
+      entropy: crypto.randomBytes(16).toString('hex'),
+      simulated: true
     });
 
     const hash = crypto.createHash('sha256').update(proofPayload).digest('hex');
-    return `zkp_v1_${hash}_${crypto.randomBytes(32).toString('base64')}`;
+    // `sim` marker is embedded AFTER the `zkp_v1_` prefix so the existing
+    // format check (startsWith 'zkp_v1_') and any external verifier still work.
+    return `zkp_v1_sim_${hash}_${crypto.randomBytes(32).toString('base64')}`;
   }
 
   verifyZKProof(proof, intentId) {

package/bin/governance/ztai-manager.js

@@ -5,6 +5,7 @@
 
 const crypto = require('node:crypto');
 const { promisify } = require('node:util');
+const configManager = require('./config-manager');
 
 const generateKeyPair = promisify(crypto.generateKeyPair);
 
@@ -147,6 +148,34 @@ class ZTAIManager {
     };
   }
 
+  /**
+   * Selects a key provider for a given trust tier.
+   *
+   * UC-24: All tiers route to REAL crypto by default — Tier 1-2 use the
+   * in-memory Ed25519 provider, Tier 3+ use the (simulated-HSM) enclave
+   * provider which also signs with REAL Ed25519. The SIMULATED post-quantum
+   * lattice provider ('quantum') is NEVER selected on the live trust path
+   * unless the operator has explicitly opted into the demo via
+   * experimental.pqc_demo. This keeps false-assurance signatures off the
+   * default trust path while preserving the demo for explicit exploration.
+   *
+   * @param {number} tier - Trust tier (1-4)
+   * @returns {'local'|'enclave'|'quantum'}
+   */
+  _selectProvider(tier) {
+    const pqcDemo = configManager.get('experimental.pqc_demo', false) === true;
+
+    // Tier 4+ MAY use the simulated lattice provider, but only when the
+    // operator has explicitly enabled the PQC demo. Otherwise it falls back to
+    // the real-Ed25519 enclave provider so the trust path stays verifiable.
+    if (tier >= 4) {
+      return pqcDemo ? 'quantum' : 'enclave';
+    }
+
+    // Tier 3 agents use the SecureEnclaveProvider (real Ed25519).
+    return tier >= 3 ? 'enclave' : 'local';
+  }
+
   /**
    * Registers a new agent and assigns a provider based on Trust Tier.
    * @param {string} persona - Agent persona identifier
@@ -157,8 +186,7 @@ class ZTAIManager {
     const uuid = crypto.randomUUID();
     const did = `did:mindforge:${uuid}`;
 
-    // Tier 3 agents use the SecureEnclaveProvider
-    const providerType = tier >= 3 ? 'enclave' : 'local';
+    const providerType = this._selectProvider(tier);
     const provider = this.providers[providerType];
 
     const publicKeyPEM = await provider.generate(did);

package/bin/hindsight-injector.js

@@ -21,17 +21,16 @@ class HindsightInjector {
       // 1. Rollback .planning directory
       TemporalHub.rollbackTo(auditId);
 
-      // 2. Append the "Hindsight" event to AUDIT.jsonl
+      // 2. Append the "Hindsight" event to AUDIT.jsonl via the unified, hash-chained,
+      //    durable append (UC-04b) so this entry links into the single verifiable chain.
+      const { appendAuditEntrySync } = require('./autonomous/audit-writer');
       const auditPath = path.join(process.cwd(), '.planning', 'AUDIT.jsonl');
-      const hindsightEvent = {
-        id:          require('crypto').randomBytes(8).toString('hex'),
-        timestamp:   new Date().toISOString(),
+      const hindsightEvent = appendAuditEntrySync(auditPath, {
         event:       'hindsight_injected',
         target_id:   auditId,
         description: fixDescription,
         agent:       'temporal-hub'
-      };
-      fs.appendFileSync(auditPath, JSON.stringify(hindsightEvent) + '\n');
+      });
 
       // 3. Mark the state as "ready_for_regeneration"
       const statePath = path.join(process.cwd(), '.planning', 'auto-state.json');

package/bin/hooks/instinct-capture-hook.js

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * MindForge — Instinct Auto-Capture Hook (UC-11)
+ * Invoked as a PostToolUse hook. Reads hook event JSON from stdin,
+ * detects successful task completions, and appends lightweight instinct
+ * entries to the configured store path.
+ *
+ * Session capture limit is enforced via a temp counter file to avoid
+ * flooding the store with low-signal entries.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const os = require('os');
+
+// ── Configuration ────────────────────────────────────────────────────────────
+
+const CONFIG_PATH = path.join(process.cwd(), '.mindforge', 'config.json');
+const SESSION_ID = process.env.MINDFORGE_SESSION_ID || process.ppid || 'default';
+const SESSION_COUNTER_PATH = path.join(
+  os.tmpdir(),
+  `mindforge-instinct-session-${SESSION_ID}.count`
+);
+
+function loadConfig() {
+  try {
+    const raw = fs.readFileSync(CONFIG_PATH, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function getSessionCount() {
+  try {
+    const raw = fs.readFileSync(SESSION_COUNTER_PATH, 'utf8');
+    return parseInt(raw, 10) || 0;
+  } catch {
+    return 0;
+  }
+}
+
+function incrementSessionCount() {
+  const current = getSessionCount();
+  fs.writeFileSync(SESSION_COUNTER_PATH, String(current + 1));
+}
+
+// ── Success Detection ────────────────────────────────────────────────────────
+
+function isSuccessfulCompletion(payload) {
+  const tool = (payload.tool_name || payload.tool || '').toLowerCase();
+
+  // Bash tool with exit code 0
+  if (tool === 'bash') {
+    const exitCode = payload.exit_code ?? payload.result?.exit_code ?? null;
+    if (exitCode === 0) return true;
+    // If no explicit exit code but has output and no error marker
+    if (exitCode === null && payload.output && !payload.error) return true;
+    return false;
+  }
+
+  // Task tool with completed status
+  if (tool === 'task') {
+    const status = (payload.status || payload.result?.status || '').toLowerCase();
+    return status === 'completed' || status === 'done';
+  }
+
+  return false;
+}
+
+// ── Pattern Extraction ───────────────────────────────────────────────────────
+
+function extractPattern(payload) {
+  const tool = (payload.tool_name || payload.tool || '').toLowerCase();
+
+  if (tool === 'bash') {
+    const command = payload.command || payload.input?.command || payload.tool_input?.command || '';
+    if (!command || command.length < 5) return null;
+    // Skip trivial commands
+    if (/^(ls|pwd|echo|cat|cd)\b/.test(command.trim())) return null;
+    return {
+      observation: `Bash command succeeded: ${command.slice(0, 200)}`,
+      behavior: `Use pattern: ${command.slice(0, 200)}`,
+    };
+  }
+
+  if (tool === 'task') {
+    const description = payload.description || payload.task_description || payload.name || '';
+    if (!description) return null;
+    return {
+      observation: `Task completed successfully: ${description.slice(0, 200)}`,
+      behavior: `Reuse approach for similar tasks: ${description.slice(0, 200)}`,
+    };
+  }
+
+  return null;
+}
+
+// ── Main ─────────────────────────────────────────────────────────────────────
+
+function main() {
+  const config = loadConfig();
+  if (!config || !config.instincts) {
+    process.exit(0);
+  }
+
+  const { mode, max_capture_per_session, store_path } = config.instincts;
+  if (mode !== 'auto-capture') {
+    process.exit(0);
+  }
+
+  // Check session limit
+  const sessionCount = getSessionCount();
+  if (sessionCount >= (max_capture_per_session || 5)) {
+    process.exit(0);
+  }
+
+  // Read stdin (hook payload)
+  let input = '';
+  try {
+    input = fs.readFileSync(0, 'utf8');
+  } catch {
+    process.exit(0);
+  }
+
+  if (!input.trim()) {
+    process.exit(0);
+  }
+
+  let payload;
+  try {
+    payload = JSON.parse(input);
+  } catch {
+    process.exit(0);
+  }
+
+  // Check if this is a successful completion
+  if (!isSuccessfulCompletion(payload)) {
+    process.exit(0);
+  }
+
+  // Extract pattern
+  const pattern = extractPattern(payload);
+  if (!pattern) {
+    process.exit(0);
+  }
+
+  // Build instinct entry
+  const entry = {
+    id: `inst-${crypto.randomUUID()}`,
+    created_at: new Date().toISOString(),
+    updated_at: new Date().toISOString(),
+    observation: pattern.observation,
+    behavior: pattern.behavior,
+    confidence: 0.3,
+    times_applied: 0,
+    times_succeeded: 0,
+    times_failed: 0,
+    project: 'mindforge',
+    tags: [],
+    status: 'active',
+    promoted_to_skill: null,
+    last_applied_at: null,
+    source: 'auto-capture',
+  };
+
+  // Write to store
+  const storePath = path.resolve(process.cwd(), store_path);
+  const storeDir = path.dirname(storePath);
+
+  try {
+    if (!fs.existsSync(storeDir)) {
+      fs.mkdirSync(storeDir, { recursive: true });
+    }
+    fs.appendFileSync(storePath, JSON.stringify(entry) + '\n');
+    incrementSessionCount();
+  } catch {
+    // Non-fatal — hooks must not block
+  }
+
+  process.exit(0);
+}
+
+main();

package/bin/memory/auto-shadow.js

@@ -18,6 +18,8 @@ const path     = require('path');
 const Store    = require('./knowledge-store');
 const Graph    = require('./knowledge-graph');
 const Embedder = require('./embedding-engine');
+const Indexer  = require('./knowledge-indexer');
+const { fuseResults } = require('./retrieval-fusion');
 
 // ── Configuration ─────────────────────────────────────────────────────────────
 const MAX_SHADOW_CHARS  = 8000;    // ~2KB tokens
@@ -63,13 +65,40 @@ function generateShadowContext(opts = {}) {
 
   const { vectors, df, N } = Embedder.buildEmbeddings(activeEntries);
 
-  // 2. Hybrid query: embedding similarity + graph traversal
+  // 2. Multi-path retrieval with RRF fusion (UC-20)
+  //    Path 1: Knowledge Graph (embedding + graph traversal)
+  //    Path 2: Knowledge Indexer (BM25 + confidence)
+  //    Results are fused via Reciprocal Rank Fusion for scale-free merging.
   const queryText = `${taskDescription} ${techStack.join(' ')}`;
-  const related = Graph.findRelated(queryText, vectors, df, N, {
+  const fetchK = maxItems * 3; // Over-fetch for filtering headroom
+
+  const graphResults = Graph.findRelated(queryText, vectors, df, N, {
     maxHops: 2,
-    topK: maxItems * 2, // Over-fetch for filtering
+    topK: fetchK,
   });
 
+  let indexerResults = [];
+  try {
+    const rawIndexer = Indexer.search(queryText, { includeGlobal: true }, fetchK);
+    indexerResults = rawIndexer.map((entry, rank) => ({
+      id: entry.id,
+      score: entry.confidence || 0,
+      source: 'indexer',
+    }));
+  } catch {
+    // Indexer may fail on empty store — non-fatal
+  }
+
+  // RRF fusion: merge both ranked lists by ordinal position
+  const fusedResults = fuseResults([graphResults, indexerResults]);
+
+  // Map fused results back to the legacy shape expected downstream
+  const related = fusedResults.map(item => ({
+    id: item.id,
+    score: item.rrfScore, // RRF score replaces incomparable linear blends
+    source: item.source || 'fused',
+  }));
+
   // 3. Filter and enrich results
   const excludeSet = new Set(excludeIds);
   const enriched = [];

package/bin/memory/identity-synthesizer.js

@@ -25,7 +25,7 @@ class IdentitySynthesizer {
       .replace(/{PROJECT_OBJECTIVE}/g, answers.goal || 'Maximizing engineering leverage');
 
     await fs.writeFile(this.soulPath, soulContent);
-    console.log(`[IDENTITY] SOUL.md bootstrapped successfully from the Grand Blueprint.`);
+    console.log('[IDENTITY] SOUL.md bootstrapped successfully from the Grand Blueprint.');
   }
 
   /**
@@ -41,7 +41,7 @@ class IdentitySynthesizer {
     );
 
     if (traces.length === 0) {
-      console.log(`[IDENTITY] No execution traces found in celestial.db. Evolution skipped.`);
+      console.log('[IDENTITY] No execution traces found in celestial.db. Evolution skipped.');
       return;
     }
 

package/bin/memory/knowledge-store.js

@@ -15,6 +15,30 @@ const path = require('path');
 const os   = require('os');
 const crypto = require('crypto');
 
+// ── Durable append (UC-09) ──────────────────────────────────────────────────
+// The knowledge-store public API (add/deprecate/reinforce) is SYNCHRONOUS and
+// callers read-after-write synchronously (e.g. `const id = Store.add(...)`
+// immediately followed by `Store.readAll()`). Routing through the async
+// append-queue would make those reads observe stale data and would require an
+// API change across 9+ consumers — out of scope for UC-09.
+//
+// Instead we centralize every append through one durable, fsync'd, synchronous
+// writer. This delivers UC-09's durability guarantee (acknowledged writes are on
+// disk before the call returns) and a single serialized append path per file,
+// while preserving the synchronous read-after-write contract. appendFileSync's
+// per-call append is atomic on POSIX, so concurrent in-process appends do not
+// interleave at the byte level.
+function appendDurableSync(filePath, line) {
+  const record = line.endsWith('\n') ? line : line + '\n';
+  const fd = fs.openSync(filePath, 'a');
+  try {
+    fs.writeSync(fd, record);
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
 // ── ID Index for fast lookups (built lazily, invalidated on writes) ───────────
 let _idIndex = null;       // Map<id, entry> — latest version per ID
 let _indexDirty = true;    // Invalidated whenever entries are appended
@@ -201,12 +225,12 @@ function add(entry) {
 
   const filePath = getFilePath(entry.type);
   verifyFileIntegrity(filePath);
-  fs.appendFileSync(filePath, JSON.stringify(full) + '\n');
+  appendDurableSync(filePath, JSON.stringify(full));
 
   // Also append to unified knowledge-base.jsonl for cross-type queries
   if (filePath !== paths.KB_PATH) {
     verifyFileIntegrity(paths.KB_PATH);
-    fs.appendFileSync(paths.KB_PATH, JSON.stringify(full) + '\n');
+    appendDurableSync(paths.KB_PATH, JSON.stringify(full));
   }
 
   _invalidateIndex();
@@ -236,10 +260,10 @@ function deprecate(id, reason, supersededBy = null) {
   };
 
   verifyFileIntegrity(filePath);
-  fs.appendFileSync(filePath, JSON.stringify(deprecated) + '\n');
+  appendDurableSync(filePath, JSON.stringify(deprecated));
   if (filePath !== paths.KB_PATH) {
     verifyFileIntegrity(paths.KB_PATH);
-    fs.appendFileSync(paths.KB_PATH, JSON.stringify(deprecated) + '\n');
+    appendDurableSync(paths.KB_PATH, JSON.stringify(deprecated));
   }
 
   _invalidateIndex();
@@ -267,10 +291,10 @@ function reinforce(id) {
 
   const filePath = getFilePath(entry.type);
   verifyFileIntegrity(filePath);
-  fs.appendFileSync(filePath, JSON.stringify(reinforced) + '\n');
+  appendDurableSync(filePath, JSON.stringify(reinforced));
   if (filePath !== paths.KB_PATH) {
     verifyFileIntegrity(paths.KB_PATH);
-    fs.appendFileSync(paths.KB_PATH, JSON.stringify(reinforced) + '\n');
+    appendDurableSync(paths.KB_PATH, JSON.stringify(reinforced));
   }
 
   _invalidateIndex();

package/bin/memory/retrieval-fusion.js

@@ -0,0 +1,58 @@
+'use strict';
+/**
+ * MindForge — Reciprocal Rank Fusion (UC-20).
+ * Merges multiple ranked lists using scale-free RRF scoring.
+ *
+ * RRF eliminates the need for score normalization across retrieval paths
+ * with incomparable scoring functions (embedding similarity, BM25, graph
+ * traversal, FTS rank). Only ordinal rank matters, not score magnitude.
+ *
+ * Formula:
+ *   rrfScore(item) = SUM( 1 / (K + rank_i) ) for all lists containing the item
+ *
+ * Where K=60 is the standard constant from the original RRF paper
+ * (Cormack, Clarke, Butt — 2009).
+ */
+
+const K = 60; // Standard RRF constant — dampens the influence of high ranks
+
+/**
+ * Fuse multiple ranked result lists using Reciprocal Rank Fusion.
+ *
+ * Each list is an array of objects with at least an `id` field.
+ * Items appearing in multiple lists accumulate RRF score and rank higher.
+ *
+ * @param {Array<Array<{id: string, [key: string]: any}>>} rankedLists
+ *   Array of ranked lists. Each list is ordered by relevance (index 0 = most relevant).
+ * @returns {Array<{id: string, rrfScore: number, [key: string]: any}>}
+ *   Fused results sorted by RRF score descending. Each item retains its
+ *   original properties from the first list it appeared in.
+ */
+function fuseResults(rankedLists) {
+  if (!rankedLists || rankedLists.length === 0) return [];
+
+  const scores = new Map(); // id -> merged item with rrfScore
+
+  for (const list of rankedLists) {
+    if (!Array.isArray(list)) continue;
+
+    for (let rank = 0; rank < list.length; rank++) {
+      const item = list[rank];
+      if (!item || !item.id) continue;
+
+      const id = item.id;
+      const rrfContribution = 1 / (K + rank + 1); // rank is 0-based, +1 makes it 1-based
+
+      if (scores.has(id)) {
+        const existing = scores.get(id);
+        existing.rrfScore += rrfContribution;
+      } else {
+        scores.set(id, { ...item, rrfScore: rrfContribution });
+      }
+    }
+  }
+
+  return [...scores.values()].sort((a, b) => b.rrfScore - a.rrfScore);
+}
+
+module.exports = { fuseResults, K };

package/bin/memory/semantic-hub.js

@@ -83,7 +83,7 @@ class SemanticHub {
     try {
       const data = await fs.readFile(this.syncManifest, 'utf8');
       manifest = JSON.parse(data);
-    } catch (e) {}
+    } catch (e) { /* intentionally empty */ }
 
     manifest[libraryName] = {
       lastSync: new Date().toISOString(),
@@ -106,7 +106,7 @@ class SemanticHub {
         sqliteTraces = await vectorHub.searchTraces(skillFilter);
       } else {
         sqliteTraces = vectorHub.query(
-          "SELECT * FROM traces WHERE event = ? LIMIT 20",
+          'SELECT * FROM traces WHERE event = ? LIMIT 20',
           ['reasoning_trace']
         );
       }