mindforge-cc 10.7.0 → 11.2.0

package/bin/engine/temporal-hub.js

@@ -1,67 +1,99 @@
 /**
  * MindForge v3 — Temporal Hub (State Versioner)
  * Managed high-fidelity snapshots of the .planning directory.
- * 
+ *
  * Design:
  * - Each snapshot is identified by an audit_id.
  * - Snapshots are stored in .planning/history/[audit_id]/
  * - Atomic snapshots ensure time-travel debugging consistency.
+ * - HMAC integrity signatures on metadata for tamper detection.
  */
 'use strict';
 
 const fs = require('fs');
+const fsPromises = require('fs/promises');
 const path = require('path');
+const crypto = require('crypto');
 const { execSync } = require('child_process');
 
 const PLANNING_DIR = path.join(process.cwd(), '.planning');
 const HISTORY_DIR  = path.join(PLANNING_DIR, 'history');
 
+const HMAC_KEY = 'mindforge-temporal-v3';
+
 class TemporalHub {
+
+  static _signMetadata(metadata) {
+    const content = JSON.stringify(metadata);
+    const hmac = crypto.createHmac('sha256', HMAC_KEY)
+      .update(content)
+      .digest('hex');
+    return { ...metadata, integrity: hmac };
+  }
+
+  static _verifyMetadata(metadata) {
+    if (!metadata.integrity) return false;
+    const { integrity, ...rest } = metadata;
+    const expected = crypto.createHmac('sha256', HMAC_KEY)
+      .update(JSON.stringify(rest))
+      .digest('hex');
+    return crypto.timingSafeEqual(Buffer.from(integrity), Buffer.from(expected));
+  }
+
   /**
    * Capture the current state of the .planning directory.
    * @param {string} auditId - Unique identifier from AUDIT.jsonl
    * @param {object} metadata - Optional context (task_name, session_id)
+   * @returns {Promise<string|null>} Path to snapshot dir, or null on failure
    */
-  static captureState(auditId, metadata = {}) {
+  static async captureState(auditId, metadata = {}) {
     if (!/^[a-f0-9-]{8,40}$/.test(auditId)) {
       throw new Error('Invalid audit ID format');
     }
-    if (!fs.existsSync(PLANNING_DIR)) return null;
+
+    try {
+      await fsPromises.access(PLANNING_DIR);
+    } catch {
+      return null;
+    }
 
     const snapshotDir = path.join(HISTORY_DIR, auditId);
     if (!path.resolve(snapshotDir).startsWith(path.resolve(HISTORY_DIR))) {
       throw new Error('Path traversal detected in audit ID');
     }
-    if (!fs.existsSync(snapshotDir)) {
-      fs.mkdirSync(snapshotDir, { recursive: true });
-    }
+
+    await fsPromises.mkdir(snapshotDir, { recursive: true });
 
     try {
-      // 1. Identify files to snapshot (exclude history itself and archive)
-      const files = fs.readdirSync(PLANNING_DIR).filter(f => {
-        const stats = fs.statSync(path.join(PLANNING_DIR, f));
-        if (stats.isDirectory()) return false;
-        
-        const ext = path.extname(f).toLowerCase();
-        return ['.md', '.json', '.yml', '.yaml', '.log'].includes(ext);
-      });
-
-      // 2. Snapshot files
-      for (const file of files) {
-        fs.copyFileSync(
+      const allEntries = await fsPromises.readdir(PLANNING_DIR, { withFileTypes: true });
+      const files = [];
+
+      for (const entry of allEntries) {
+        if (entry.isDirectory()) continue;
+        const ext = path.extname(entry.name).toLowerCase();
+        if (['.md', '.json', '.yml', '.yaml', '.log'].includes(ext)) {
+          files.push(entry.name);
+        }
+      }
+
+      await Promise.all(files.map(file =>
+        fsPromises.copyFile(
           path.join(PLANNING_DIR, file),
           path.join(snapshotDir, file)
-        );
-      }
+        )
+      ));
 
-      // 3. Save snapshot metadata
       const meta = {
         id: auditId,
         timestamp: new Date().toISOString(),
         ...metadata,
         files: files
       };
-      fs.writeFileSync(path.join(snapshotDir, 'SNAPSHOT-META.json'), JSON.stringify(meta, null, 2));
+      const signedMeta = TemporalHub._signMetadata(meta);
+      await fsPromises.writeFile(
+        path.join(snapshotDir, 'SNAPSHOT-META.json'),
+        JSON.stringify(signedMeta, null, 2)
+      );
 
       return snapshotDir;
     } catch (err) {
@@ -72,9 +104,11 @@ class TemporalHub {
 
   /**
    * Restore the .planning directory to a specific snapshot.
-   * @param {string} auditId 
+   * Verifies HMAC integrity before restoring.
+   * @param {string} auditId
+   * @returns {Promise<boolean>}
    */
-  static rollbackTo(auditId) {
+  static async rollbackTo(auditId) {
     if (!/^[a-f0-9-]{8,40}$/.test(auditId)) {
       throw new Error('Invalid audit ID format');
     }
@@ -82,20 +116,39 @@ class TemporalHub {
     if (!path.resolve(snapshotDir).startsWith(path.resolve(HISTORY_DIR))) {
       throw new Error('Path traversal detected in audit ID');
     }
-    if (!fs.existsSync(snapshotDir)) {
+
+    try {
+      await fsPromises.access(snapshotDir);
+    } catch {
       throw new Error(`Snapshot ${auditId} not found in history.`);
     }
 
+    const metaPath = path.join(snapshotDir, 'SNAPSHOT-META.json');
     try {
-      const files = fs.readdirSync(snapshotDir).filter(f => f !== 'SNAPSHOT-META.json');
-      
-      for (const file of files) {
-        fs.copyFileSync(
+      const metaRaw = await fsPromises.readFile(metaPath, 'utf8');
+      const metaData = JSON.parse(metaRaw);
+      if (!TemporalHub._verifyMetadata(metaData)) {
+        throw new Error(`Snapshot ${auditId} failed integrity verification — metadata may be tampered.`);
+      }
+    } catch (err) {
+      if (err.message.includes('integrity verification') || err.message.includes('tampered')) {
+        throw err;
+      }
+      // Missing metadata file on legacy snapshots — allow rollback with warning
+      console.warn(`[temporal-hub] No verifiable metadata for ${auditId}, proceeding without integrity check.`);
+    }
+
+    try {
+      const allEntries = await fsPromises.readdir(snapshotDir);
+      const files = allEntries.filter(f => f !== 'SNAPSHOT-META.json');
+
+      await Promise.all(files.map(file =>
+        fsPromises.copyFile(
           path.join(snapshotDir, file),
           path.join(PLANNING_DIR, file)
-        );
-      }
-      
+        )
+      ));
+
       return true;
     } catch (err) {
       console.error(`[temporal-hub] Rollback failed for ${auditId}:`, err.message);
@@ -108,7 +161,7 @@ class TemporalHub {
    */
   static getHistory() {
     if (!fs.existsSync(HISTORY_DIR)) return [];
-    
+
     try {
       return fs.readdirSync(HISTORY_DIR)
         .map(id => {
@@ -141,6 +194,50 @@ class TemporalHub {
     return null;
   }
 
+  /**
+   * Garbage-collect old snapshots to prevent unbounded disk growth.
+   * Keeps the most recent `maxSnapshots` and deletes anything older than `maxAgeDays`.
+   */
+  static async gc(options = {}) {
+    try {
+      const maxSnapshots = options.maxSnapshots || 50;
+      const maxAgeDays = options.maxAgeDays || 7;
+      const historyDir = path.join(process.cwd(), '.planning', 'history');
+
+      if (!fs.existsSync(historyDir)) return { deleted: 0, remaining: 0 };
+
+      const entries = fs.readdirSync(historyDir)
+        .filter(name => {
+          const fullPath = path.join(historyDir, name);
+          try { return fs.statSync(fullPath).isDirectory(); } catch { return false; }
+        })
+        .map(name => {
+          const fullPath = path.join(historyDir, name);
+          return { name, path: fullPath, mtime: fs.statSync(fullPath).mtime };
+        })
+        .sort((a, b) => b.mtime - a.mtime);
+
+      const now = Date.now();
+      const maxAgeMs = maxAgeDays * 24 * 60 * 60 * 1000;
+      let deleted = 0;
+
+      for (let i = 0; i < entries.length; i++) {
+        const entry = entries[i];
+        const isOverLimit = i >= maxSnapshots;
+        const isExpired = (now - entry.mtime.getTime()) > maxAgeMs;
+
+        if (isOverLimit || isExpired) {
+          fs.rmSync(entry.path, { recursive: true, force: true });
+          deleted++;
+        }
+      }
+
+      return { deleted, remaining: entries.length - deleted };
+    } catch (err) {
+      return { deleted: 0, remaining: 0, error: err.message };
+    }
+  }
+
   /**
    * Capture terminal output for a command and associate with audit point.
    */
@@ -153,7 +250,7 @@ class TemporalHub {
       throw new Error('Path traversal detected in audit ID');
     }
     if (!fs.existsSync(logDir)) fs.mkdirSync(logDir, { recursive: true });
-    
+
     if (stdout) fs.writeFileSync(path.join(logDir, 'stdout.log'), stdout);
     if (stderr) fs.writeFileSync(path.join(logDir, 'stderr.log'), stderr);
   }

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/approve.js

@@ -10,6 +10,7 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const crypto = require('crypto');
+const { execFileSync } = require('child_process');
 
 const REASON = process.argv[2] || 'Manual approval for sensitive changes.';
 const ROOT = path.resolve(__dirname, '../../');
@@ -19,14 +20,47 @@ if (!fs.existsSync(APPROVALS_DIR)) {
   fs.mkdirSync(APPROVALS_DIR, { recursive: true });
 }
 
+/**
+ * Attempts to retrieve the GPG signing key configured in git.
+ * Returns null if no key is configured or git is unavailable.
+ */
+function getGPGSigningKey() {
+  try {
+    const key = execFileSync('git', ['config', 'user.signingkey'], { encoding: 'utf8' }).trim();
+    return key || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Verifies the identity of the approver using GPG if available.
+ * Falls back to git identity only (with warning) if no GPG key is configured.
+ * @param {string} approver - The approver identity string
+ */
+function verifyApproverIdentity(approver) {
+  const gpgKey = getGPGSigningKey();
+
+  if (!gpgKey) {
+    console.warn('[GOVERNANCE] No GPG signing key configured — approval accepted with git identity only');
+    return { verified: false, method: 'git_identity', identity: approver };
+  }
+
+  return { verified: true, method: 'gpg_key', identity: approver, keyId: gpgKey };
+}
+
 async function approve() {
   const pkgPath = path.join(ROOT, 'package.json');
   const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
 
   const id = `MF-AUTH-${Date.now().toString(36).toUpperCase()}`;
   const timestamp = new Date().toISOString();
-  
-  // Calculate a mock signature based on current state (can be hardened with real crypto sign later)
+  const approver = process.env.USER || 'MindForge User';
+
+  // Verify approver identity (GPG if available, git identity fallback)
+  const identityVerification = verifyApproverIdentity(approver);
+
+  // Calculate a signature based on current state
   const signature = crypto.createHash('sha256')
     .update(`${id}:${REASON}:${timestamp}:${os.hostname()}`)
     .digest('hex');
@@ -36,20 +70,22 @@ async function approve() {
     project: pkg.name,
     version: pkg.version,
     tier: 3,
-    approved_by: process.env.USER || 'MindForge User',
+    approved_by: approver,
     timestamp,
     reason: REASON,
-    signature: `sha256:${signature}`
+    signature: `sha256:${signature}`,
+    identity_verification: identityVerification
   };
 
   const filename = `approval-${id.toLowerCase()}.json`;
   const filePath = path.join(APPROVALS_DIR, filename);
 
   fs.writeFileSync(filePath, JSON.stringify(record, null, 2));
-  
+
   console.log('\n✅ Governance approval generated!\n');
   console.log(`ID:       ${id}`);
   console.log(`Reason:   ${REASON}`);
+  console.log(`Verified: ${identityVerification.verified ? 'GPG (' + identityVerification.keyId + ')' : 'git identity only (no GPG key)'}`);
   console.log(`File:     .planning/approvals/${filename}`);
   console.log('\nCommit this file to unblock Tier 3 gates in CI.\n');
 }

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 };