mindforge-cc 9.0.0 → 10.0.1

package/bin/migrations/v8-sqlite-migration.js

@@ -8,7 +8,7 @@ const vectorHub = require('../memory/vector-hub');
  */
 async function runMigration() {
   console.log('[MIGRATION] Starting MindForge v8 (Celestial) SQLite migration...');
-  
+
   await vectorHub.init();
 
   // 1. Migrate Remediation Queue
@@ -18,17 +18,18 @@ async function runMigration() {
       const data = JSON.parse(fs.readFileSync(remPath, 'utf8'));
       console.log(`[MIGRATION] Migrating ${data.length} remediations...`);
       for (const rem of data) {
-        await vectorHub.db.insertInto('remediations')
-          .values({
-            id: rem.remediation_id,
-            trace_id: rem.span_id, // Mapping span_id to trace_id for legacy compatibility
-            strategy: rem.strategy,
-            status: rem.status,
-            timestamp: rem.timestamp || new Date().toISOString(),
-            outcome: rem.status === 'SUCCESS' ? 'Legacy Success' : null
-          })
-          .onConflict(oc => oc.column('id').doNothing())
-          .execute();
+        vectorHub.run(
+          `INSERT OR IGNORE INTO remediations (id, trace_id, strategy, status, timestamp, outcome)
+           VALUES (?, ?, ?, ?, ?, ?)`,
+          [
+            rem.remediation_id,
+            rem.span_id,
+            rem.strategy,
+            rem.status,
+            rem.timestamp || new Date().toISOString(),
+            rem.status === 'SUCCESS' ? 'Legacy Success' : null
+          ]
+        );
       }
     } catch (err) {
       console.warn(`[MIGRATION] Failed to migrate remediations: ${err.message}`);
@@ -41,7 +42,7 @@ async function runMigration() {
     try {
       const lines = fs.readFileSync(auditPath, 'utf8').split('\n').filter(Boolean);
       console.log(`[MIGRATION] Migrating ${lines.length} audit trace lines...`);
-      
+
       for (const line of lines) {
         const entry = JSON.parse(line);
         if (entry.event === 'reasoning_trace' || entry.event === 'drift_remediation_event') {
@@ -64,15 +65,15 @@ async function runMigration() {
   }
 
   // 3. Set Mesh Node Identity
-  await vectorHub.db.insertInto('mesh_config')
-    .values({ key: 'mesh_node_id', value: `mindforge-node-${Math.random().toString(36).substr(2, 6)}` })
-    .onConflict(oc => oc.column('key').doNothing())
-    .execute();
+  vectorHub.run(
+    'INSERT OR IGNORE INTO mesh_config (key, value) VALUES (?, ?)',
+    ['mesh_node_id', `mindforge-node-${Math.random().toString(36).substr(2, 6)}`]
+  );
 
-  await vectorHub.db.insertInto('mesh_config')
-    .values({ key: 'v8_migration_complete', value: new Date().toISOString() })
-    .onConflict(oc => oc.column('key').doNothing())
-    .execute();
+  vectorHub.run(
+    'INSERT OR IGNORE INTO mesh_config (key, value) VALUES (?, ?)',
+    ['v8_migration_complete', new Date().toISOString()]
+  );
 
   console.log('[MIGRATION] MindForge v8 Migration Successful.');
   await vectorHub.close();

package/bin/migrations/v9-unified-memory.js

@@ -25,7 +25,7 @@ async function run() {
   let edgesMigrated = 0;
   let skippedLines = 0;
 
-  await vectorHub.db.transaction().execute(async (trx) => {
+  await vectorHub.transaction(async ({ run: txRun }) => {
     // 1. Migrate knowledge-base.jsonl → knowledge table
     const kbPaths = [
       path.join(process.cwd(), '.mindforge', 'memory', 'knowledge-base.jsonl'),

package/bin/mindforge-cli.js

@@ -9,7 +9,14 @@
 const { spawnSync } = require('child_process');
 const path = require('path');
 
-const ARGS = process.argv.slice(2);
+const RAW_ARGS = process.argv.slice(2);
+
+// ── Parse global flags ────────────────────────────────────────────────────────
+if (RAW_ARGS.includes('--verbose') || RAW_ARGS.includes('-v')) {
+  process.env.MINDFORGE_VERBOSE = '1';
+}
+
+const ARGS = RAW_ARGS.filter(a => a !== '--verbose' && a !== '-v');
 const COMMAND = ARGS[0];
 const COMMAND_ARGS = ARGS.slice(1);
 
@@ -113,14 +120,7 @@ const COMMANDS = {
     description: 'Verify framework integrity using post-quantum signatures',
     defaultArgs: ['--verify', '.mindforge/engine/']
   },
-  'sync-jira': {
-    script: 'bin/integrations/jira-sync.js',
-    description: 'Synchronize project state with Jira issues and milestones'
-  },
-  'sync-confluence': {
-    script: 'bin/integrations/confluence-sync.js',
-    description: 'Export architecture and roadmap to Confluence pages'
-  },
+  // Planned: jira-sync, confluence-sync (not yet implemented)
   'metrics': {
     script: 'bin/dashboard/metrics-aggregator.js',
     description: 'Display real-time velocity and quality metrics'
@@ -148,8 +148,20 @@ if (!COMMAND || ARGS.includes('--help') || ARGS.includes('-h')) {
 
 const target = COMMANDS[COMMAND];
 if (!target) {
-  console.error(`❌ Unknown command: ${COMMAND}`);
-  console.error('Available commands: ' + Object.keys(COMMANDS).join(', '));
+  console.error(`Unknown command: ${COMMAND}`);
+
+  // Suggest similar commands using Levenshtein distance
+  const suggestions = Object.keys(COMMANDS)
+    .map(cmd => ({ cmd, dist: levenshtein(COMMAND, cmd) }))
+    .filter(s => s.dist <= 3)
+    .sort((a, b) => a.dist - b.dist)
+    .slice(0, 3);
+
+  if (suggestions.length > 0) {
+    console.error(`\nDid you mean: ${suggestions.map(s => s.cmd).join(', ')}?`);
+  } else {
+    console.error('Available commands: ' + Object.keys(COMMANDS).join(', '));
+  }
   process.exit(1);
 }
 
@@ -166,6 +178,30 @@ const result = spawnSync('node', [scriptPath, ...finalArgs], {
 
 process.exit(result.status || 0);
 
+/**
+ * Levenshtein distance — dynamic programming edit distance between two strings.
+ */
+function levenshtein(a, b) {
+  const m = a.length;
+  const n = b.length;
+  const dp = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
+
+  for (let i = 0; i <= m; i++) dp[i][0] = i;
+  for (let j = 0; j <= n; j++) dp[0][j] = j;
+
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      dp[i][j] = Math.min(
+        dp[i - 1][j] + 1,
+        dp[i][j - 1] + 1,
+        dp[i - 1][j - 1] + cost
+      );
+    }
+  }
+  return dp[m][n];
+}
+
 function printUsage() {
   console.log('\n⚡ MindForge Enterprise CLI\n');
   console.log('Usage: node bin/mindforge-cli.js <command> [options]\n');

package/bin/models/model-broker.js

@@ -1,3 +1,5 @@
+const fs = require('fs');
+const path = require('path');
 const CloudBroker = require('./cloud-broker');
 
 class ModelBroker {

package/bin/revops/remediation-queue.js

@@ -1,14 +1,11 @@
 /**
  * MindForge v7 — Neural Drift Remediation (NDR)
  * Component: Remediation Queue
- * 
+ *
  * Manages the persistence and lifecycle of remediation tasks.
  */
 'use strict';
 
-const fs = require('node:fs');
-const path = require('node:path');
-
 const vectorHub = require('../memory/vector-hub');
 
 class RemediationQueue {
@@ -23,21 +20,6 @@ class RemediationQueue {
     }
   }
 
-  /**
-   * Loads the existing queue from disk.
-   */
-  _loadQueue() {
-    try {
-      if (fs.existsSync(this.queuePath)) {
-        const raw = fs.readFileSync(this.queuePath, 'utf8');
-        return JSON.parse(raw);
-      }
-    } catch (err) {
-      console.error(`[RemediationQueue] Failed to load queue: ${err.message}`);
-    }
-    return [];
-  }
-
   /**
    * Adds a new task to the remediation queue.
    */
@@ -48,16 +30,12 @@ class RemediationQueue {
       enqueued_at: new Date().toISOString(),
       status: 'PENDING'
     };
-    
-    await vectorHub.db.insertInto('remediations')
-      .values({
-        id: entry.remediation_id,
-        trace_id: entry.span_id || 'unknown',
-        strategy: entry.strategy,
-        status: entry.status,
-        timestamp: entry.enqueued_at
-      })
-      .execute();
+
+    vectorHub.run(
+      `INSERT INTO remediations (id, trace_id, strategy, status, timestamp)
+       VALUES (?, ?, ?, ?, ?)`,
+      [entry.remediation_id, entry.span_id || 'unknown', entry.strategy, entry.status, entry.enqueued_at]
+    );
 
     return entry;
   }
@@ -67,40 +45,23 @@ class RemediationQueue {
    */
   async updateStatus(remediationId, status) {
     await this.ensureInit();
-    await vectorHub.db.updateTable('remediations')
-      .set({ 
-        status, 
-        outcome: `Updated at ${new Date().toISOString()}` 
-      })
-      .where('id', '=', remediationId)
-      .execute();
-  }
-
-  /**
-   * Legacy persistence removed in v8 (SQLite transition).
-   */
-  _persist() {
-     // No-op for v8
-  }
-
-  _loadQueue() {
-     // No-op for v8
-     return [];
+    vectorHub.run(
+      'UPDATE remediations SET status = ?, outcome = ? WHERE id = ?',
+      [status, `Updated at ${new Date().toISOString()}`, remediationId]
+    );
   }
 
   async getPending() {
     await this.ensureInit();
-    return await vectorHub.db.selectFrom('remediations')
-      .selectAll()
-      .where('status', '=', 'PENDING')
-      .execute();
+    return vectorHub.query(
+      'SELECT * FROM remediations WHERE status = ?',
+      ['PENDING']
+    );
   }
 
   async getAll() {
     await this.ensureInit();
-    return await vectorHub.db.selectFrom('remediations')
-      .selectAll()
-      .execute();
+    return vectorHub.query('SELECT * FROM remediations');
   }
 }
 

package/bin/utils/errors.js

@@ -0,0 +1,40 @@
+'use strict';
+
+class MindForgeError extends Error {
+  constructor(message, code, context = {}) {
+    super(message);
+    this.name = 'MindForgeError';
+    this.code = code;
+    this.context = context;
+  }
+}
+
+class ConfigError extends MindForgeError {
+  constructor(message, context) {
+    super(message, 'CONFIG_ERROR', context);
+    this.name = 'ConfigError';
+  }
+}
+
+class GovernanceError extends MindForgeError {
+  constructor(message, context) {
+    super(message, 'GOVERNANCE_ERROR', context);
+    this.name = 'GovernanceError';
+  }
+}
+
+class SecurityError extends MindForgeError {
+  constructor(message, context) {
+    super(message, 'SECURITY_ERROR', context);
+    this.name = 'SecurityError';
+  }
+}
+
+class ValidationError extends MindForgeError {
+  constructor(message, fields = []) {
+    super(message, 'VALIDATION_ERROR', { fields });
+    this.name = 'ValidationError';
+  }
+}
+
+module.exports = { MindForgeError, ConfigError, GovernanceError, SecurityError, ValidationError };

package/bin/utils/file-io.js

@@ -0,0 +1,102 @@
+'use strict';
+
+const fs = require('fs');
+const fsp = require('fs/promises');
+const path = require('path');
+const crypto = require('crypto');
+
+class AuditWriter {
+  constructor(filePath) {
+    this._path = filePath;
+    this._buffer = [];
+    this._flushTimer = null;
+    this._lastHash = null;
+  }
+
+  write(entry) {
+    // Add Merkle chain link
+    const entryWithHash = {
+      ...entry,
+      timestamp: entry.timestamp || new Date().toISOString(),
+      previous_hash: this._lastHash
+    };
+    const serialized = JSON.stringify(entryWithHash);
+    this._lastHash = crypto.createHash('sha256').update(serialized).digest('hex');
+    entryWithHash._hash = this._lastHash;
+
+    this._buffer.push(JSON.stringify(entryWithHash));
+
+    if (this._buffer.length >= 10) {
+      return this.flush();
+    }
+    if (!this._flushTimer) {
+      this._flushTimer = setTimeout(() => this.flush(), 100);
+    }
+    return Promise.resolve();
+  }
+
+  async flush() {
+    if (this._buffer.length === 0) return;
+    clearTimeout(this._flushTimer);
+    this._flushTimer = null;
+
+    const lines = this._buffer.splice(0);
+    const content = lines.join('\n') + '\n';
+
+    await fsp.mkdir(path.dirname(this._path), { recursive: true });
+    await fsp.appendFile(this._path, content);
+  }
+
+  async close() {
+    await this.flush();
+  }
+
+  async initLastHash() {
+    try {
+      const content = await fsp.readFile(this._path, 'utf8');
+      const lines = content.trim().split('\n').filter(Boolean);
+      if (lines.length > 0) {
+        const lastEntry = JSON.parse(lines[lines.length - 1]);
+        this._lastHash = lastEntry._hash || null;
+      }
+    } catch { /* file doesn't exist yet */ }
+  }
+}
+
+async function readJSON(filePath) {
+  try {
+    const content = await fsp.readFile(filePath, 'utf8');
+    return JSON.parse(content);
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+async function writeJSON(filePath, data) {
+  await fsp.mkdir(path.dirname(filePath), { recursive: true });
+  await fsp.writeFile(filePath, JSON.stringify(data, null, 2) + '\n');
+}
+
+async function readJSONL(filePath, { limit = Infinity, reverse = false } = {}) {
+  try {
+    const content = await fsp.readFile(filePath, 'utf8');
+    let lines = content.trim().split('\n').filter(Boolean);
+    if (reverse) lines = lines.reverse();
+    return lines.slice(0, limit).map(line => JSON.parse(line));
+  } catch (err) {
+    if (err.code === 'ENOENT') return [];
+    throw err;
+  }
+}
+
+function readJSONSync(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+module.exports = { AuditWriter, readJSON, writeJSON, readJSONL, readJSONSync };

package/bin/utils/index.js

@@ -0,0 +1,6 @@
+'use strict';
+module.exports = {
+  ...require('./paths'),
+  ...require('./file-io'),
+  ...require('./errors')
+};

package/bin/utils/paths.js

@@ -0,0 +1,33 @@
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+
+function findProjectRoot(startDir = process.cwd()) {
+  let dir = startDir;
+  while (dir !== path.dirname(dir)) {
+    if (fs.existsSync(path.join(dir, 'MINDFORGE.md')) ||
+        fs.existsSync(path.join(dir, '.mindforge'))) {
+      return dir;
+    }
+    dir = path.dirname(dir);
+  }
+  return process.cwd();
+}
+
+const PROJECT_ROOT = findProjectRoot();
+
+module.exports = {
+  PROJECT_ROOT,
+  PLANNING_DIR: path.join(PROJECT_ROOT, '.planning'),
+  MINDFORGE_DIR: path.join(PROJECT_ROOT, '.mindforge'),
+  AUDIT_LOG: path.join(PROJECT_ROOT, '.planning', 'AUDIT.jsonl'),
+  STATE_FILE: path.join(PROJECT_ROOT, '.planning', 'STATE.md'),
+  HANDOFF_FILE: path.join(PROJECT_ROOT, '.planning', 'HANDOFF.json'),
+  AUTO_STATE_FILE: path.join(PROJECT_ROOT, '.planning', 'auto-state.json'),
+  CONFIG_FILE: path.join(PROJECT_ROOT, '.mindforge', 'config.json'),
+  DB_PATH: path.join(PROJECT_ROOT, '.mindforge', 'celestial.db'),
+  HISTORY_DIR: path.join(PROJECT_ROOT, '.mindforge', 'history'),
+  METRICS_DIR: path.join(PROJECT_ROOT, '.mindforge', 'metrics'),
+  resolve(...segments) { return path.join(PROJECT_ROOT, ...segments); }
+};

package/docs/commands-reference.md

@@ -117,8 +117,6 @@ Connecting MindForge to enterprise systems and keeping the framework hardened.
 
 | Command | Description |
 | :--- | :--- |
-| `/mindforge:sync-jira` | Synchronizes MindForge milestones and tasks with Jira tickets and status transitions. |
-| `/mindforge:sync-confluence` | Exports architectural decisions and project documentation to Confluence spaces. |
 | `/mindforge:approve [event]` | Issues a manual Tier 3 cryptographic signature for a sensitive or high-risk operation. |
 | `/mindforge:health` | Runs comprehensive framework diagnostics across 7 categories with auto-repair loops. |
 | `/mindforge:update` | Checks for, diffs, and applies MindForge framework updates in a safe, scope-preserving way. |
@@ -142,3 +140,41 @@ High-fidelity behaviors ported from the Superpowers library and hardened for pro
 | `/mindforge:verify-work` | Multi-level truth verification protocol (substance, existence, wiring). |
 | `/mindforge:retrospective` | Facilitates structured team retrospectives with objective telemetry and metrics. |
 
+---
+
+## 11. CLI Commands (`mindforge` binary)
+
+After installation, the `mindforge` binary provides direct access to runtime operations. Use `--verbose` (`-v`) on any command for detailed output.
+
+```bash
+mindforge <command> [options]
+```
+
+| Command | Description |
+| :--- | :--- |
+| `security-scan` | Validate configuration and run security checks |
+| `health` | Verify project health and installation integrity |
+| `headless` | Run MindForge agent in headless (non-interactive) mode |
+| `pr-review` | Run standard PR review logic |
+| `cross-review` | Run advanced cross-model architecture review |
+| `classify` | Classify changes into governance tiers |
+| `approve` | Generate a governance approval signature to unblock Tier 3 gates |
+| `validate-skill` | Run Level 1 & 2 validation on a SKILL.md file |
+| `install-skill` | Install a skill to the correct tier folder |
+| `register-skill` | Register a skill in MANIFEST.md |
+| `audit-skill` | Record skill life cycle events in audit log |
+| `remember` | Manage the long-term memory (knowledge graph) |
+| `learn-skill` | Ingest source and generate a validated SKILL.md |
+| `marketplace` | Search and install community skills |
+| `spawn` | Spawn a persona essence (e.g., mf-planner) |
+| `identity` | Invoke a specialized identity from /agents/ |
+| `temporal` | Manage time-travel debugging and state history |
+| `hindsight` | Inject a fix into a past point and regenerate state |
+| `harvest` | Proactively harvest semantic intent from the intelligence mesh |
+| `self-heal` | Auto-detect and repair reasoning drifts in the active swarm |
+| `quantum-verify` | Verify framework integrity using post-quantum signatures |
+| `metrics` | Display real-time velocity and quality metrics |
+| `tokens` | Analyze token consumption and cost efficiency |
+| `learning` | Consult or initialize the project agentic learning memory |
+| `record-learning` | Append a new Learning Entry to the Evolution Log |
+

package/docs/getting-started.md

@@ -1,19 +1,29 @@
-# MindForge — Getting Started
+# MindForge — Getting Started (v10.0.0)
 
 This guide gets you from zero to a working MindForge project in under five minutes.
 
+## Prerequisites
+
+- **Node.js 18+** (LTS recommended)
+- No native build tools required — MindForge uses sql.js (pure WASM) for all database operations
+
 ## Install
 
-MindForge is typically installed as a project-local dependency to ensure environment isolation.
+MindForge is installed via `npx` for zero-config setup:
 
 ```bash
-# Antigravity (recommended for local development)
-npx mindforge-cc@latest --antigravity --local
+# Recommended (auto-detects your runtime)
+npx mindforge-cc
 
-# Claude Code (alternative)
-npx mindforge-cc@latest --claude --local
+# Antigravity (local development)
+npx mindforge-cc --antigravity --local
+
+# Claude Code (local, per project)
+npx mindforge-cc --claude --local
 ```
 
+After installation, the `mindforge` CLI command is available for runtime operations (health checks, security scans, headless execution, etc.).
+
 ## Initialise Your Project
 
 Open your agentic runtime (Antigravity or Claude Code) in your repository and run: