mindforge-cc 10.7.0 → 11.2.0

package/bin/autonomous/state-manager.js

@@ -7,8 +7,59 @@
 
 const fs = require('fs');
 const path = require('path');
+const { atomicWriteJSON } = require('../utils/file-io');
 
 const VALID_PHASES = ['idle', 'planning', 'executing', 'verifying', 'complete', 'running', 'paused', 'completed'];
+const VALID_STATUSES = ['idle', 'running', 'paused', 'completed', 'escalated', 'timeout'];
+
+/**
+ * Validates HANDOFF.json structure without blocking on failure (fail-open).
+ * Warns on malformed fields but always returns the data for processing.
+ * @param {*} data — Parsed HANDOFF.json content
+ * @returns {{ valid: boolean, warnings: string[] }}
+ */
+function validateHandoff(data) {
+  const warnings = [];
+
+  if (!data || typeof data !== 'object') {
+    warnings.push('HANDOFF.json is not a valid object');
+    return { valid: false, warnings };
+  }
+
+  if (!data.schema_version) {
+    warnings.push('Missing schema_version field');
+  }
+
+  if (data.handoffs && !Array.isArray(data.handoffs)) {
+    warnings.push('handoffs field must be an array');
+  }
+
+  if (data.handoffs && Array.isArray(data.handoffs)) {
+    for (let i = 0; i < data.handoffs.length; i++) {
+      const task = data.handoffs[i];
+      if (!task.id) warnings.push(`handoffs[${i}] missing required field: id`);
+      if (!task.name) warnings.push(`handoffs[${i}] missing required field: name`);
+    }
+  }
+
+  if (data.status && !VALID_STATUSES.includes(data.status)) {
+    warnings.push(`Invalid status: "${data.status}". Expected one of: ${VALID_STATUSES.join(', ')}`);
+  }
+
+  if (data.wave_current !== undefined && typeof data.wave_current !== 'number') {
+    warnings.push('wave_current must be a number');
+  }
+
+  if (data.tasks_completed !== undefined && typeof data.tasks_completed !== 'number') {
+    warnings.push('tasks_completed must be a number');
+  }
+
+  if (data.timestamps && typeof data.timestamps !== 'object') {
+    warnings.push('timestamps must be an object');
+  }
+
+  return { valid: warnings.length === 0, warnings };
+}
 
 /**
  * Creates a state manager for the given planning directory.
@@ -45,7 +96,7 @@ function createStateManager(planningDir) {
   function updateState(patch) {
     const current = getState();
     const merged = Object.assign(Object.create(null), current, patch);
-    fs.writeFileSync(statePath, JSON.stringify(merged, null, 2));
+    atomicWriteJSON(statePath, merged);
     return merged;
   }
 
@@ -64,7 +115,8 @@ function createStateManager(planningDir) {
   }
 
   /**
-   * Reads and parses HANDOFF.json. Throws if missing or malformed.
+   * Reads and parses HANDOFF.json with schema validation (fail-open).
+   * Logs warnings for structural issues but always returns data if parseable.
    * @returns {object} Parsed handoff data (fresh object)
    */
   function readHandoff() {
@@ -79,8 +131,12 @@ function createStateManager(planningDir) {
       throw new Error(`HANDOFF.json is malformed: ${e.message}`);
     }
 
-    if (!handoff.handoffs || !Array.isArray(handoff.handoffs)) {
-      throw new Error('HANDOFF.json has no handoffs array');
+    // Fail-open schema validation — warn but never block
+    const { valid, warnings } = validateHandoff(handoff);
+    if (!valid) {
+      for (const warning of warnings) {
+        console.warn('[STATE] HANDOFF validation:', warning);
+      }
     }
 
     return handoff;
@@ -94,7 +150,7 @@ function createStateManager(planningDir) {
     const timestamped = Object.assign(Object.create(null), data, {
       last_updated: new Date().toISOString(),
     });
-    fs.writeFileSync(handoffPath, JSON.stringify(timestamped, null, 2) + '\n');
+    atomicWriteJSON(handoffPath, timestamped);
     return timestamped;
   }
 
@@ -113,4 +169,4 @@ function sanitizeState(parsed) {
   return clean;
 }
 
-module.exports = { createStateManager };
+module.exports = { createStateManager, validateHandoff };

package/bin/autonomous/stuck-monitor.js

@@ -96,12 +96,49 @@ class StuckMonitor {
     return identical.length >= 3;
   }
 
-  isContentSimilar(a, b) {
+  isContentSimilar(a, b, threshold = 10) {
     if (!a || !b) return false;
     if (a === b) return true;
-    // Simple similarity check (hardened from Roadmap requirement)
-    const dist = this.levenshtein(a.slice(0, 100), b.slice(0, 100));
-    return dist < 10;
+
+    const hashA = this._quickHash(a);
+    const hashB = this._quickHash(b);
+    if (hashA === hashB) return true;
+
+    const lenDiff = Math.abs(a.length - b.length);
+    if (lenDiff > Math.max(a.length, b.length) * 0.2) return false;
+
+    const cached = this._getCachedSimilarity(hashA, hashB);
+    if (cached !== undefined) return cached;
+
+    const truncA = a.substring(0, 100);
+    const truncB = b.substring(0, 100);
+    const result = this.levenshtein(truncA, truncB) <= threshold;
+
+    this._setCachedSimilarity(hashA, hashB, result);
+    return result;
+  }
+
+  _quickHash(str) {
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+      hash = ((hash << 5) - hash) + str.charCodeAt(i);
+      hash = hash & hash;
+    }
+    return hash;
+  }
+
+  _getCachedSimilarity(keyA, keyB) {
+    const key = keyA < keyB ? `${keyA}|${keyB}` : `${keyB}|${keyA}`;
+    return StuckMonitor._similarityCache.get(key);
+  }
+
+  _setCachedSimilarity(keyA, keyB, result) {
+    const key = keyA < keyB ? `${keyA}|${keyB}` : `${keyB}|${keyA}`;
+    if (StuckMonitor._similarityCache.size >= 200) {
+      const firstKey = StuckMonitor._similarityCache.keys().next().value;
+      StuckMonitor._similarityCache.delete(firstKey);
+    }
+    StuckMonitor._similarityCache.set(key, result);
   }
 
   levenshtein(a, b) {
@@ -109,12 +146,14 @@ class StuckMonitor {
     for (let i = 0; i <= a.length; i++) { tmp[i] = [i]; }
     for (let j = 0; j <= b.length; j++) { tmp[0][j] = j; }
     for (let i = 1; i <= a.length; i++) {
-        for (let j = 1; j <= b.length; j++) {
-            tmp[i][j] = Math.min(tmp[i - 1][j] + 1, tmp[i][j - 1] + 1, tmp[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
-        }
+      for (let j = 1; j <= b.length; j++) {
+        tmp[i][j] = Math.min(tmp[i - 1][j] + 1, tmp[i][j - 1] + 1, tmp[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+      }
     }
     return tmp[a.length][b.length];
   }
 }
 
+StuckMonitor._similarityCache = new Map();
+
 module.exports = StuckMonitor;

package/bin/autonomous/wave-executor.js

@@ -6,6 +6,36 @@
 'use strict';
 
 const crypto = require('crypto');
+const { buildGraph, groupIntoWaves } = require('./dependency-dag');
+
+/**
+ * Semaphore for bounding concurrency within a wave.
+ * Tasks within a wave are independent — this limits how many run simultaneously.
+ */
+class Semaphore {
+  constructor(max) {
+    this.max = max;
+    this.current = 0;
+    this.queue = [];
+  }
+
+  async acquire() {
+    if (this.current < this.max) {
+      this.current++;
+      return;
+    }
+    await new Promise(resolve => this.queue.push(resolve));
+    this.current++;
+  }
+
+  release() {
+    this.current--;
+    if (this.queue.length > 0) {
+      const next = this.queue.shift();
+      next();
+    }
+  }
+}
 
 /**
  * Creates a wave executor with the given configuration.
@@ -35,10 +65,19 @@ function createWaveExecutor(config = {}) {
   /**
    * Groups handoff tasks into sequential waves based on wave field or dependency topology.
    * Returns a new array of wave objects — does not mutate input.
+   *
+   * Resolution order (UC-03):
+   *   1. Explicit numeric `.wave` field ALWAYS wins (legacy behavior, unchanged).
+   *   2. Else if `options.useDag === true` (OPT-IN), order by `depends_on` via Kahn
+   *      topological sort. Halts loud (throws) on cycles or unknown dependencies.
+   *   3. Else (legacy default), all tasks in a single parallel wave (unchanged).
+   *
+   * DAG ordering is OPT-IN to avoid silently reordering existing PLAN files.
    * @param {Array} handoffs — Raw handoffs array from HANDOFF.json
+   * @param {object} [options] — { useDag?: boolean }
    * @returns {Array<{ wave: number, tasks: Array }>}
    */
-  function planWaves(handoffs) {
+  function planWaves(handoffs, options = {}) {
     if (!Array.isArray(handoffs) || handoffs.length === 0) {
       waves = [];
       return [];
@@ -57,6 +96,15 @@ function createWaveExecutor(config = {}) {
       waves = Array.from(byWave.entries())
         .sort((a, b) => a[0] - b[0])
         .map(([waveNum, tasks]) => Object.freeze({ wave: waveNum, tasks: Object.freeze(tasks) }));
+    } else if (options.useDag === true) {
+      const normalized = handoffs.map(normalizeTask);
+      const graph = buildGraph(normalized);
+      const waveIds = groupIntoWaves(graph);
+      const byId = new Map(normalized.map(t => [t.id, t]));
+      waves = waveIds.map((ids, i) => Object.freeze({
+        wave: i,
+        tasks: Object.freeze(ids.map(id => byId.get(id))),
+      }));
     } else {
       // Single wave with all tasks
       waves = [Object.freeze({
@@ -73,42 +121,54 @@ function createWaveExecutor(config = {}) {
   }
 
   /**
-   * Executes a single wave — runs tasks sequentially, skipping already-completed ones.
+   * Executes a single wave — runs tasks in parallel (bounded by maxConcurrency),
+   * skipping already-completed ones.
    * @param {object} wave — A wave object from planWaves
    * @param {object} context — Execution context passed to callbacks
-   * @param {object} context.executor — async function(task) => result (performs actual work)
+   * @param {function} context.executor — async function(task) => result (performs actual work)
+   * @param {number} [context.maxConcurrency=3] — Max parallel tasks within this wave
    * @returns {Promise<{ completed: string[], failed: string[], skipped: string[] }>}
    */
   async function executeWave(wave, context = {}) {
-    const { executor = async () => {} } = context;
+    const { executor = async () => {}, maxConcurrency = 3 } = context;
     status = 'running';
 
     const pending = wave.tasks.filter(t => !completedTasks.has(t.id));
     const result = { completed: [], failed: [], skipped: [] };
+    const semaphore = new Semaphore(maxConcurrency);
 
     onWaveStart({ wave: wave.wave, taskCount: pending.length });
 
-    for (const task of pending) {
-      const taskStart = Date.now();
-      onTaskStart({ task, wave: wave.wave });
-
-      try {
-        await executor(task);
-
-        const duration = Date.now() - taskStart;
-        completedTasks = new Set([...completedTasks, task.id]);
-        result.completed.push(task.id);
-
-        onTaskComplete({ task, wave: wave.wave, duration_ms: duration });
-      } catch (err) {
-        const duration = Date.now() - taskStart;
-        result.failed.push(task.id);
-
-        onTaskFail({ task, wave: wave.wave, error: err, duration_ms: duration });
-
-        // Re-throw to let caller decide on retry/escalation strategy
-        throw err;
-      }
+    const settled = await Promise.allSettled(
+      pending.map(async (task) => {
+        await semaphore.acquire();
+        const taskStart = Date.now();
+        try {
+          onTaskStart({ task, wave: wave.wave });
+          await executor(task);
+
+          const duration = Date.now() - taskStart;
+          completedTasks = new Set([...completedTasks, task.id]);
+          result.completed.push(task.id);
+
+          onTaskComplete({ task, wave: wave.wave, duration_ms: duration });
+          return { task, status: 'fulfilled' };
+        } catch (err) {
+          const duration = Date.now() - taskStart;
+          result.failed.push(task.id);
+
+          onTaskFail({ task, wave: wave.wave, error: err, duration_ms: duration });
+          throw err;
+        } finally {
+          semaphore.release();
+        }
+      })
+    );
+
+    const failures = settled.filter(r => r.status === 'rejected');
+    if (failures.length > 0) {
+      const failMsg = failures.map(f => f.reason?.message || 'unknown').join(', ');
+      throw new Error(`${failures.length} task(s) failed in wave: ${failMsg}`);
     }
 
     currentWaveIndex++;
@@ -166,4 +226,4 @@ function normalizeTask(h) {
   });
 }
 
-module.exports = { createWaveExecutor };
+module.exports = { createWaveExecutor, Semaphore };

package/bin/council-cli.js

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * MindForge — Council CLI (UC-22)
+ *
+ * Thin CLI wrapper around council-runtime.runCouncil. Provides the injectable
+ * model function via ModelClient and formats structured output for the
+ * /mindforge:council command.
+ *
+ * Usage:
+ *   node bin/council-cli.js "Should we adopt event sourcing for the payments domain?"
+ *   node bin/council-cli.js --id payment-es "Should we adopt event sourcing?"
+ *
+ * Exit codes:
+ *   0 — PROCEED
+ *   1 — REVISE
+ *   2 — NO_CONSENSUS
+ *   3 — Runtime error
+ */
+const { runCouncil } = require('./engine/council-runtime');
+const ModelClient = require('./models/model-client');
+
+const VOICE_SYSTEM_PROMPTS = {
+  architect: 'You are the Architect voice in a decision council. You focus on system design, scalability, maintainability, and long-term architectural integrity. Evaluate the decision from a structural perspective.',
+  skeptic: 'You are the Skeptic voice in a decision council. You challenge assumptions, identify risks, hidden costs, and failure modes. Your job is to stress-test the proposal.',
+  pragmatist: 'You are the Pragmatist voice in a decision council. You focus on delivery timelines, team capacity, incremental value, and practical trade-offs. Favor what ships reliably.',
+  critic: 'You are the Critic voice in a decision council. You evaluate quality, correctness, edge cases, and whether the solution meets its stated goals without over-engineering.',
+};
+
+const POSITION_INSTRUCTION = `
+Respond with ONLY a JSON object (no markdown fences, no prose) in this exact shape:
+{
+  "recommendation": "PROCEED" or "REVISE",
+  "confidence": <number between 0 and 1>,
+  "rationale": "<1-3 sentence explanation>"
+}
+Do NOT include any text outside the JSON object.`;
+
+/**
+ * Injectable model function for runCouncil — calls ModelClient.complete per voice.
+ */
+async function councilModel({ voice, question }) {
+  const systemPrompt = (VOICE_SYSTEM_PROMPTS[voice] || VOICE_SYSTEM_PROMPTS.architect) +
+    '\n' + POSITION_INSTRUCTION;
+
+  const result = await ModelClient.complete({
+    persona: 'council',
+    tier: 2,
+    systemPrompt,
+    userMessage: `Decision under review:\n${question}`,
+    maxTokens: 300,
+    temperature: 0.4,
+    taskName: `council-${voice}`,
+  });
+
+  // Parse the JSON response from the model
+  const content = (result.content || '').trim();
+  let parsed;
+  try {
+    // Strip markdown fences if model adds them despite instructions
+    const cleaned = content.replace(/^```(?:json)?\s*/i, '').replace(/\s*```$/i, '');
+    parsed = JSON.parse(cleaned);
+  } catch {
+    throw new Error(`Council voice "${voice}" returned unparseable response: ${content.slice(0, 200)}`);
+  }
+
+  return {
+    recommendation: parsed.recommendation,
+    confidence: parsed.confidence,
+    rationale: parsed.rationale,
+  };
+}
+
+// --- CLI argument parsing ---
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  const opts = { question: null, decisionId: null };
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--id' && args[i + 1]) {
+      opts.decisionId = args[++i];
+    } else if (!args[i].startsWith('-')) {
+      opts.question = opts.question ? `${opts.question} ${args[i]}` : args[i];
+    }
+  }
+  return opts;
+}
+
+// --- Formatted output ---
+function formatOutput(result) {
+  const lines = [];
+  lines.push('');
+  lines.push('=== COUNCIL VERDICT ===');
+  lines.push('');
+  lines.push(`Question: ${result.question}`);
+  lines.push('');
+  lines.push('--- Positions ---');
+  for (const pos of result.positions) {
+    const icon = pos.recommendation === 'PROCEED' ? '[+]' : '[-]';
+    lines.push(`  ${icon} ${pos.voice.toUpperCase()} (${pos.recommendation}, confidence: ${pos.confidence.toFixed(2)})`);
+    lines.push(`      ${pos.rationale}`);
+  }
+  lines.push('');
+  lines.push(`--- Consensus: ${(result.consensus * 100).toFixed(1)}% ---`);
+  lines.push('');
+  lines.push(`VERDICT: ${result.verdict}`);
+
+  if (result.verdict === 'NO_CONSENSUS' && result.dissent.length > 0) {
+    lines.push('');
+    lines.push('--- Dissent (full split) ---');
+    for (const d of result.dissent) {
+      lines.push(`  * ${d.voice.toUpperCase()} (${d.recommendation}): ${d.rationale}`);
+    }
+  } else if (result.dissent.length > 0) {
+    lines.push('');
+    lines.push('--- Dissent ---');
+    for (const d of result.dissent) {
+      lines.push(`  * ${d.voice.toUpperCase()}: ${d.rationale}`);
+    }
+  }
+
+  lines.push('');
+  lines.push('Council is advisory -- you have final say.');
+  lines.push('');
+  return lines.join('\n');
+}
+
+// --- Main ---
+async function main() {
+  const { question, decisionId } = parseArgs(process.argv);
+
+  if (!question) {
+    process.stderr.write('Usage: node bin/council-cli.js [--id <decision-id>] "<question>"\n');
+    process.exit(3);
+  }
+
+  try {
+    const result = await runCouncil(question, {
+      model: councilModel,
+      writeDecision: true,
+      decisionId: decisionId || undefined,
+    });
+
+    // Output structured JSON to stdout for programmatic consumption
+    console.log(JSON.stringify(result, null, 2));
+
+    // Output formatted human-readable summary to stderr
+    process.stderr.write(formatOutput(result));
+
+    // Exit code reflects verdict
+    const exitCode = result.verdict === 'PROCEED' ? 0
+      : result.verdict === 'REVISE' ? 1
+      : 2;
+    process.exit(exitCode);
+  } catch (err) {
+    process.stderr.write(`[council-cli] ERROR: ${err.message}\n`);
+    process.exit(3);
+  }
+}
+
+main();

package/bin/dashboard/api-router.js

@@ -192,6 +192,49 @@ function register(app) {
   app.get('/api/connections', (req, res) => {
     res.json({ clients: SSE.getClientCount() });
   });
+
+  // ── System observability ────────────────────────────────────────────────────
+  app.get('/api/v1/system', (req, res) => {
+    try {
+      const heapUsed = process.memoryUsage().heapUsed;
+      const heapTotal = process.memoryUsage().heapTotal;
+      const uptime = process.uptime();
+
+      let auditLines = 0;
+      try {
+        const auditPath = path.join(process.cwd(), '.planning', 'AUDIT.jsonl');
+        if (fs.existsSync(auditPath)) {
+          const content = fs.readFileSync(auditPath, 'utf8');
+          auditLines = content.split('\n').filter(l => l.trim()).length;
+        }
+      } catch { /* non-critical */ }
+
+      let snapshotCount = 0;
+      try {
+        const historyDir = path.join(process.cwd(), '.planning', 'history');
+        if (fs.existsSync(historyDir)) {
+          snapshotCount = fs.readdirSync(historyDir).length;
+        }
+      } catch { /* non-critical */ }
+
+      const heapHealth = Metrics.checkHeapHealth();
+
+      res.json({
+        heap_used_mb: Math.round(heapUsed / 1024 / 1024 * 100) / 100,
+        heap_total_mb: Math.round(heapTotal / 1024 / 1024 * 100) / 100,
+        heap_usage_pct: Math.round(heapUsed / heapTotal * 100),
+        heap_alert: heapHealth,
+        uptime_seconds: Math.round(uptime),
+        audit_lines: auditLines,
+        snapshot_count: snapshotCount,
+        sse_clients: SSE.getClientCount(),
+        node_version: process.version,
+        timestamp: new Date().toISOString()
+      });
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
 }
 
 module.exports = { register };

package/bin/dashboard/approval-handler.js

@@ -115,7 +115,9 @@ function writeAuditEntry(entry) {
   try {
     const paths = getPaths();
     if (!fs.existsSync(path.dirname(paths.audit))) return;
-    fs.appendFileSync(paths.audit, JSON.stringify(entry) + '\n');
+    // UC-04b: unified, hash-chained, durable append into the single verifiable chain.
+    const { appendAuditEntrySync } = require('../autonomous/audit-writer');
+    appendAuditEntrySync(paths.audit, entry);
   } catch { /* ignore AUDIT write failures */ }
 }
 

package/bin/dashboard/metrics-aggregator.js

@@ -326,6 +326,32 @@ function getCosts(windowDays = 7) {
   return stats;
 }
 
+// ── Heap Health ──────────────────────────────────────────────────────────────
+function checkHeapHealth() {
+  const heapUsed = process.memoryUsage().heapUsed;
+  const maxHeap = getMaxOldSpaceSize();
+  const usagePct = Math.round(heapUsed / maxHeap * 100);
+
+  let status = 'healthy';
+  if (usagePct > 85) {
+    status = 'critical';
+  } else if (usagePct > 70) {
+    status = 'warning';
+  }
+
+  return { status, usage_pct: usagePct };
+}
+
+function getMaxOldSpaceSize() {
+  // Parse --max-old-space-size from process args, default 1.4GB
+  const flag = process.execArgv.find(a => a.startsWith('--max-old-space-size'));
+  if (flag) {
+    const mb = parseInt(flag.split('=')[1], 10);
+    if (mb > 0) return mb * 1024 * 1024;
+  }
+  return 1.4 * 1024 * 1024 * 1024;
+}
+
 module.exports = {
   getStatus,
   getAuditEntries,
@@ -333,5 +359,6 @@ module.exports = {
   getApprovals,
   getTeamActivity,
   getMemory,
-  getCosts
+  getCosts,
+  checkHeapHealth
 };