mindforge-cc 11.0.0 → 11.2.0

package/bin/autonomous/auto-runner.js

@@ -19,7 +19,7 @@ const progressStream = require('./progress-stream');
 const ContextRefactorer = require('./context-refactorer');
 
 // Extracted modules (lightweight, always needed)
-const { createAuditWriter } = require('./audit-writer');
+const { appendAuditEntrySync } = require('./audit-writer');
 const { createStateManager } = require('./state-manager');
 const { createWaveExecutor, Semaphore } = require('./wave-executor');
 
@@ -44,6 +44,68 @@ function lazyRequire(cached, modulePath) {
   return cached;
 }
 
+/**
+ * UC-14: Pure timeout predicate evaluated at wave boundaries.
+ *
+ * Three cases:
+ *   1. falsy `timeoutAt` (null / undefined / '') → NO timeout is configured →
+ *      false. Autonomous mode never times out in that case.
+ *   2. truthy but UNPARSEABLE deadline (`Date.parse` → NaN, e.g. 'garbage') → a
+ *      MALFORMED deadline. We FAIL CLOSED: warn to stderr AND return true (treat
+ *      as expired). For a stability/bounding feature, a broken deadline silently
+ *      never firing would let a run proceed UNBOUNDED — the wrong direction. A
+ *      malformed deadline must be VISIBLE and must HALT, not silently fail open.
+ *   3. valid date → `now > parsed` (timed out once `now` strictly exceeds it).
+ *
+ * `Date.now()` is the sane default for a RUNTIME comparison (unlike the council
+ * UC, which avoided `Date.now()` only for deterministic/resumable FILENAMES — a
+ * wall-clock read here is exactly what a timeout check wants). Callers inside the
+ * run-loop should still pass an explicit `now` for testability/consistency within
+ * a single iteration.
+ *
+ * NOTE: this is otherwise a PURE function (used directly in tests). The only
+ * side-effect is the diagnostic stderr write on the malformed branch — never on
+ * the falsy or valid-date paths — so existing pure assertions are unaffected.
+ *
+ * @param {string|null|undefined} timeoutAt — ISO-8601 deadline, or falsy for "no timeout"
+ * @param {number} [now=Date.now()] — Epoch ms to compare against
+ * @returns {boolean} true iff a deadline is set AND it has passed (or is malformed)
+ */
+function isTimedOut(timeoutAt, now = Date.now()) {
+  if (!timeoutAt) return false;
+  const parsed = Date.parse(timeoutAt);
+  if (Number.isNaN(parsed)) {
+    // Malformed deadline → fail CLOSED (visible + halt), never silently fail open.
+    process.stderr.write(`[auto-runner] malformed timeout_at "${timeoutAt}" — treating as expired to fail closed\n`);
+    return true;
+  }
+  return now > parsed;
+}
+
+/**
+ * UC-14: Pure decision for the opt-in terminal-ESCALATE rollback hook.
+ *
+ * SAFE BY DEFAULT: rollback-on-escalate is opt-in via
+ * `wave_execution.rollback_on_escalate` (default false). Even when enabled, an
+ * actual destructive `git reset` is gated on the runner tracking per-wave commit
+ * SHAs — which it does NOT today. So `gitReset` is always false until commit
+ * tracking exists; we only ever RECORD the rollback point.
+ *
+ * @param {object} config — Parsed .mindforge/config.json (or {})
+ * @param {boolean} [hasCommitTracking=false] — Whether per-wave commit SHAs are tracked
+ * @returns {{ record: boolean, gitReset: boolean, reason: string }}
+ */
+function decideRollback(config, hasCommitTracking = false) {
+  const enabled = config?.wave_execution?.rollback_on_escalate === true;
+  if (!enabled) {
+    return { record: true, gitReset: false, reason: 'rollback_on_escalate disabled (default) — recording intent only' };
+  }
+  if (!hasCommitTracking) {
+    return { record: true, gitReset: false, reason: 'rollback_on_escalate enabled but per-wave commit tracking unavailable — recording intent only, actual git reset deferred' };
+  }
+  return { record: true, gitReset: true, reason: 'rollback_on_escalate enabled and commit tracking available' };
+}
+
 class AutoRunner {
   constructor(options = {}) {
     if (options.phase != null && !/^[a-zA-Z0-9_-]+$/.test(String(options.phase))) {
@@ -61,7 +123,6 @@ class AutoRunner {
 
     // Extracted module instances
     this.stateManager = createStateManager(planningDir);
-    this.auditWriter = createAuditWriter(this.auditPath);
     this.waveExecutor = createWaveExecutor({
       onTaskStart: ({ task, wave }) => this.writeAudit({ event: 'task_started', phase: this.phase, wave: wave + 1, task_id: task.id, task_name: task.name }),
       onTaskComplete: ({ task, wave, duration_ms }) => this.writeAudit({ event: 'task_completed', phase: this.phase, wave: wave + 1, task_id: task.id, task_name: task.name, duration_ms }),
@@ -173,6 +234,10 @@ class AutoRunner {
 
     while (await this.hasNextWave()) {
       if (this.isPaused) break;
+      // UC-14: enforce the wave-boundary timeout BEFORE dispatching this wave.
+      // Re-read auto-state each iteration so an externally-updated timeout_at is
+      // honored; stop cleanly (status 'timeout' + resumable state) when passed.
+      if (this._enforceWaveTimeout()) return;
       const permit = await this.evaluateWavePolicy();
       if (!permit) { this.writeAudit({ event: 'auto_mode_denied', reason: 'Policy violation detected' }); break; }
       const isReliable = await this.checkArbitrage();
@@ -188,10 +253,77 @@ class AutoRunner {
     await this.complete();
   }
 
+  /**
+   * UC-14: Wave-boundary timeout enforcement.
+   *
+   * Re-reads the current `timeout_at` from auto-state.json (V9 design field) and,
+   * if the deadline has passed, stops the run CLEANLY:
+   *   1. persists resumable state (currentWaveIndex + completedTasks) so a later
+   *      `/mindforge:auto` resumes exactly where it left off,
+   *   2. sets status to 'timeout' (a VALID_STATUS), keeping the resumable fields,
+   *   3. writes an `auto_mode_timeout` audit event,
+   *   4. logs the resume command and returns true so the caller stops the loop.
+   *
+   * Returns false (no-op) when no timeout is set or the deadline hasn't passed.
+   * @returns {boolean} true iff the run timed out and the loop should stop
+   */
+  _enforceWaveTimeout() {
+    const autoState = this.stateManager.getState();
+    if (!isTimedOut(autoState.timeout_at)) return false;
+
+    const waveNum = this.currentWaveIndex + 1;
+
+    // 1 + 2: persist resumable progress AND flip status to 'timeout' in one write.
+    this.updateState({
+      status: 'timeout',
+      currentWaveIndex: this.currentWaveIndex,
+      completedTasks: Array.from(this.completedTasks),
+      timedOutAt: new Date().toISOString(),
+    });
+
+    // 3: audit the clean stop.
+    this.writeAudit({
+      event: 'auto_mode_timeout',
+      phase: this.phase,
+      wave: waveNum,
+      timeout_at: autoState.timeout_at,
+      completed_tasks: this.completedTasks.size,
+      timestamp: new Date().toISOString(),
+    });
+
+    // 4: clear operator-facing message including the resume command.
+    console.warn(
+      `\n⏲️  TIMEOUT at wave boundary ${waveNum}/${this.waves.length} ` +
+      `(deadline ${autoState.timeout_at}). Stopped cleanly with ${this.completedTasks.size} task(s) completed.\n` +
+      `   Resume with: /mindforge:auto --phase ${this.phase}`
+    );
+    return true;
+  }
+
   runPreFlight() {
     console.log('🔍 Running pre-flight checks...');
+
+    // UC-01: fail closed on version drift before any wave executes
+    try {
+      const { assertVersionConsistency } = require('../utils/version-check');
+      assertVersionConsistency(process.cwd());
+    } catch (e) {
+      throw new Error(`[pre-flight] ${e.message}`);
+    }
+
     const handoff = this.stateManager.readHandoff();
-    this.waves = this._buildWaves(handoff.handoffs);
+
+    // FIX 3.2: read config ONCE for the whole pre-flight path and thread the
+    // resolved useDag boolean into both _assertNoCycles and _buildWaves, instead
+    // of each method re-reading + re-parsing .mindforge/config.json.
+    const useDag = this._useDagMode();
+
+    // UC-03: when DAG ordering is enabled (opt-in via config), detect cycles
+    // BEFORE any wave executes and HALT LOUD. Default OFF — legacy behavior
+    // (single-wave / explicit .wave grouping) is untouched.
+    this._assertNoCycles(handoff.handoffs, useDag);
+
+    this.waves = this._buildWaves(handoff.handoffs, useDag);
     this.currentWaveIndex = 0;
 
     const savedState = this.stateManager.getState();
@@ -253,6 +385,9 @@ class AutoRunner {
         const strategy = repairOperator.determineRepairStrategy({ planId: task.plan || taskId, phase: this.phase, attemptNumber: 1, errorOutput: error.message, isTier3Change: false, isOnCriticalPath: (task.depends_on || []).length > 0 });
         if (strategy === 'ESCALATE') {
           this.writeAudit({ event: 'auto_mode_escalated', reason: `Task ${taskId} unrecoverable` });
+          // UC-14: opt-in rollback hook on terminal ESCALATE. SAFE DEFAULT —
+          // records the rollback point only; never mutates git (see decideRollback).
+          this._recordRollbackPoint(waveNum, taskId);
           this.isPaused = true;
           return;
         }
@@ -277,12 +412,158 @@ class AutoRunner {
     return 3;
   }
 
+  /**
+   * UC-14: Rollback-on-escalate is OPT-IN. Reads
+   * `wave_execution.rollback_on_escalate` from config; defaults to false so the
+   * SAFE behavior (record rollback intent only — NO git mutation) is the default.
+   * Even when true, an actual git reset is further gated on per-wave commit
+   * tracking, which the runner does not yet have (see decideRollback).
+   * @returns {boolean}
+   */
+  _rollbackOnEscalate() {
+    try {
+      const configPath = path.join(process.cwd(), '.mindforge', 'config.json');
+      if (fs.existsSync(configPath)) {
+        const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+        return config.wave_execution?.rollback_on_escalate === true;
+      }
+    } catch (e) { /* Fall through to default */ }
+    return false;
+  }
+
+  /**
+   * UC-14: Records the rollback point on terminal ESCALATE WITHOUT mutating git.
+   *
+   * The runner does NOT track per-wave commit SHAs, so even with
+   * `rollback_on_escalate` enabled the actual `git reset --hard` is deferred —
+   * we never run a destructive reset against untracked commit boundaries. We
+   * emit a `rollback_point_recorded` audit event (and a clear log) recording the
+   * intended rollback wave so a human can act on it.
+   *
+   * @param {number} waveNum — 1-based wave number that hit terminal escalation
+   * @param {string} taskId — The task id whose repair was exhausted
+   */
+  _recordRollbackPoint(waveNum, taskId) {
+    const config = (() => {
+      try {
+        const configPath = path.join(process.cwd(), '.mindforge', 'config.json');
+        if (fs.existsSync(configPath)) return JSON.parse(fs.readFileSync(configPath, 'utf8'));
+      } catch (e) { /* ignore — treat as no config */ }
+      return {};
+    })();
+
+    // hasCommitTracking is hard-false: no per-wave SHA tracking exists yet.
+    const decision = decideRollback(config, /* hasCommitTracking */ false);
+
+    // DRY: derive the flag from the `config` we ALREADY read above instead of
+    // calling _rollbackOnEscalate(), which would re-read + re-parse the SAME
+    // config.json a second time within this single escalation path.
+    const rollbackEnabled = config?.wave_execution?.rollback_on_escalate === true;
+
+    this.writeAudit({
+      event: 'rollback_point_recorded',
+      phase: this.phase,
+      wave: waveNum,
+      task_id: taskId,
+      commits: [], // none tracked yet — rollback target is the prior wave boundary
+      git_reset_performed: decision.gitReset,
+      reason: decision.reason,
+      timestamp: new Date().toISOString(),
+    });
+    console.warn(`↩️  ROLLBACK POINT recorded at wave ${waveNum} (task ${taskId}): ${decision.reason}`);
+    if (rollbackEnabled && !decision.gitReset) {
+      console.warn('   (rollback_on_escalate is ON, but actual git reset is deferred until per-wave commit tracking exists.)');
+    }
+    return decision;
+  }
+
+  /**
+   * UC-03: DAG wave ordering is OPT-IN. Reads `wave_execution.use_dag` from
+   * config; defaults to false so legacy single-wave / explicit-.wave behavior
+   * is untouched. Enabling this reorders tasks by `depends_on` topology.
+   * @returns {boolean}
+   */
+  _useDagMode() {
+    try {
+      const configPath = path.join(process.cwd(), '.mindforge', 'config.json');
+      if (fs.existsSync(configPath)) {
+        const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+        return config.wave_execution?.use_dag === true;
+      }
+    } catch (e) { /* Fall through to default */ }
+    return false;
+  }
+
+  /**
+   * UC-03: Pre-flight cycle detection. ONLY active when DAG mode is enabled
+   * (opt-in) AND no explicit numeric `.wave` field is present (DAG would be the
+   * active strategy). Throws `[pre-flight] Circular dependency...` to HALT LOUD
+   * before any wave executes — never warn-and-continue. No-op when DAG is off.
+   *
+   * FIX 1: the pre-flight graph must NOT differ from the graph planWaves
+   * actually executes. planWaves builds its graph from normalizeTask, which
+   * SYNTHESIZES a random id (`task_<rand>`) for any handoff lacking both id and
+   * task_id. A random id can't be matched between two separate calls, AND a task
+   * with no stable id can never be a `depends_on` TARGET (nothing can reference
+   * an id that doesn't exist until it's randomly minted). So we cycle-check the
+   * SUBSET of handoffs that carry a real, stable id (id || task_id) — a subset
+   * guaranteed consistent with execution — and log a warning for any id-less
+   * handoff excluded from the check.
+   *
+   * @param {Array} handoffs — Raw handoffs array from HANDOFF.json
+   * @param {boolean} [useDag] — Resolved DAG mode (threaded from runPreFlight to
+   *   avoid re-reading config). Falls back to _useDagMode() for direct callers.
+   */
+  _assertNoCycles(handoffs, useDag = this._useDagMode()) {
+    if (!Array.isArray(handoffs) || handoffs.length === 0) return;
+    if (!useDag) return;
+
+    // Explicit .wave field wins over DAG, so cycle check is irrelevant there.
+    const hasWaveField = handoffs.some(h => typeof h.wave === 'number');
+    if (hasWaveField) return;
+
+    // Only handoffs with a STABLE id participate in cycle-checking (see above).
+    const stable = handoffs.filter(h => h.id || h.task_id);
+    const idless = handoffs.length - stable.length;
+    if (idless > 0) {
+      console.warn(
+        `[pre-flight] ${idless} handoff(s) lack a stable id (id/task_id) and are ` +
+        'excluded from cycle-checking; an id-less task cannot be a dependency target.'
+      );
+    }
+    if (stable.length === 0) return;
+
+    const { buildGraph, groupIntoWaves } = require('./dependency-dag');
+    let graph;
+    try {
+      graph = buildGraph(stable.map(h => ({
+        id: h.id || h.task_id,
+        depends_on: Array.isArray(h.depends_on) ? h.depends_on : [],
+      })));
+    } catch (e) {
+      // Unknown-dependency reference — also a planning error; fail loud.
+      throw new Error(`[pre-flight] ${e.message}`);
+    }
+    // FIX 3.1: hasCircularDependency() is itself `try{groupIntoWaves}catch`, so
+    // running it then groupIntoWaves again ran Kahn 2-3 times and left an
+    // unreachable defensive throw. Run Kahn ONCE here; on throw, rethrow with the
+    // descriptive (circular OR unknown-dep) message prefixed for pre-flight.
+    try {
+      groupIntoWaves(graph);
+    } catch (e) {
+      throw new Error(`[pre-flight] ${e.message}`);
+    }
+  }
+
   /**
    * Build wave groups from HANDOFF handoffs array.
    * Kept as instance method for backward compatibility with tests.
+   * @param {Array} handoffs — Raw handoffs array from HANDOFF.json
+   * @param {boolean} [useDag] — Resolved DAG mode (threaded from runPreFlight).
+   *   Falls back to _useDagMode() for direct callers (e.g. tests).
    */
-  _buildWaves(handoffs) {
-    return this.waveExecutor.planWaves(handoffs);
+  _buildWaves(handoffs, useDag = this._useDagMode()) {
+    return this.waveExecutor.planWaves(handoffs, { useDag });
   }
 
   async checkIntelligenceDrift() {
@@ -359,27 +640,23 @@ class AutoRunner {
     } catch (e) { /* GC failure is non-critical */ }
 
     this.writeAudit({ event: 'auto_mode_completed', timestamp: new Date().toISOString() });
-    await this.auditWriter.close();
   }
 
   writeAudit(event) {
-    const crypto = require('crypto');
-    if (!event.id) event = Object.assign({}, event, { id: crypto.randomBytes(8).toString('hex') });
-    if (!event.timestamp) event = Object.assign({}, event, { timestamp: new Date().toISOString() });
-
-    // Synchronous write for backward compat (monitor needs immediate data)
-    fs.appendFileSync(this.auditPath, JSON.stringify(event) + '\n');
-
-    // Also buffer in async writer for future async consumers
-    this.auditWriter.write(event);
+    // UC-04b: single unified, hash-chained, synchronous-DURABLE append. The sync
+    // fsync'd write means in-process consumers (StuckMonitor reads the event
+    // object directly below; any file re-readers see it immediately) get durable
+    // data at once — replacing the old dual raw-appendFileSync + async-buffer write
+    // that left the live AUDIT.jsonl chain unverifiable.
+    const stamped = appendAuditEntrySync(this.auditPath, event);
 
     const STATE_CHANGING_EVENTS = ['auto_mode_started', 'phase_planned', 'phase_execution_started', 'task_completed', 'hindsight_injected', 'auto_mode_completed'];
-    if (STATE_CHANGING_EVENTS.includes(event.event)) {
+    if (STATE_CHANGING_EVENTS.includes(stamped.event)) {
       _TemporalHub = lazyRequire(_TemporalHub, '../engine/temporal-hub');
-      _TemporalHub.captureState(event.id, { agent: event.agent || 'auto-runner', event: event.event, phase: this.phase }).catch(() => {});
+      _TemporalHub.captureState(stamped.id, { agent: stamped.agent || 'auto-runner', event: stamped.event, phase: this.phase }).catch(() => {});
     }
 
-    const result = this.monitor.analyze(event);
+    const result = this.monitor.analyze(stamped);
     if (result) this.handleStuck(result);
   }
 
@@ -412,7 +689,7 @@ class AutoRunner {
 
   async evaluateWavePolicy() {
     _ZTAIManager = lazyRequire(_ZTAIManager, '../governance/ztai-manager');
-    const manager = new _ZTAIManager();
+    const manager = _ZTAIManager;
     const identity = await manager.getIdentity();
     const intent = { did: identity.did, action: 'process_phase_wave', resource: `projects/${process.env.MF_PROJECT_ID || 'MF-ALPHA'}/phases/${this.phase}/*`, tier: identity.tier || 1, metadata: { engine: 'Nimbus-S4', mode: 'autonomous', wave_timestamp: new Date().toISOString() } };
     const result = this.policyEngine.evaluate(intent);
@@ -504,4 +781,12 @@ class AutoRunner {
   }
 }
 
+// Primary export remains the AutoRunner class (back-compat with all callers/tests
+// that do `const AutoRunner = require('./auto-runner')`). UC-14 pure helpers are
+// attached as named properties so `require('./auto-runner').isTimedOut` works too.
+AutoRunner.isTimedOut = isTimedOut;
+AutoRunner.decideRollback = decideRollback;
+
 module.exports = AutoRunner;
+module.exports.isTimedOut = isTimedOut;
+module.exports.decideRollback = decideRollback;

package/bin/autonomous/dependency-dag.js

@@ -0,0 +1,59 @@
+'use strict';
+/**
+ * MindForge — Dependency DAG (UC-03).
+ * Kahn topological sort + cycle detection.
+ * Ported from the previously test-only implementation into the real engine.
+ *
+ * TODO(UC-xx): same-wave file-conflict detection once tasks carry file lists.
+ *   Handoff tasks (see normalizeTask in wave-executor.js and validateHandoff in
+ *   state-manager.js) currently expose only id/name/plan/depends_on — there is
+ *   no `files` field to compare. A `findFileConflicts(plans)` check (two tasks
+ *   in the SAME wave writing the same file -> warn) cannot be wired meaningfully
+ *   until the handoff schema captures per-task file lists, so it is intentionally
+ *   not implemented here rather than left as dead exported surface.
+ */
+function groupIntoWaves(graph) {
+  // Self-defense: every dependency target must be a known graph node. Throw a
+  // DISTINCT "unknown dependency" error (not the misleading "Circular" message)
+  // so callers that invoke groupIntoWaves standalone still fail descriptively.
+  for (const id of Object.keys(graph)) {
+    const deps = graph[id].dependsOn || [];
+    for (const d of deps) {
+      if (!(d in graph)) {
+        throw new Error(`Unknown dependency "${d}" referenced by "${id}"`);
+      }
+    }
+  }
+  const remaining = new Set(Object.keys(graph));
+  const completed = new Set();
+  const waves = [];
+  while (remaining.size > 0) {
+    const wave = [];
+    for (const id of remaining) {
+      const deps = graph[id].dependsOn || [];
+      if (deps.every(d => completed.has(d))) wave.push(id);
+    }
+    if (wave.length === 0 && remaining.size > 0) {
+      throw new Error(`Circular dependency detected among: ${[...remaining].join(', ')}`);
+    }
+    waves.push(wave.sort());
+    wave.forEach(id => { completed.add(id); remaining.delete(id); });
+  }
+  return waves;
+}
+function hasCircularDependency(graph) {
+  try { groupIntoWaves(graph); return false; } catch { return true; }
+}
+function buildGraph(tasks) {
+  const ids = new Set(tasks.map(t => t.id));
+  const graph = {};
+  for (const t of tasks) {
+    const deps = Array.isArray(t.depends_on) ? t.depends_on : [];
+    for (const d of deps) {
+      if (!ids.has(d)) throw new Error(`Task "${t.id}" depends on unknown task "${d}"`);
+    }
+    graph[t.id] = { dependsOn: deps };
+  }
+  return graph;
+}
+module.exports = { groupIntoWaves, hasCircularDependency, buildGraph };

package/bin/autonomous/wave-executor.js

@@ -6,6 +6,7 @@
 'use strict';
 
 const crypto = require('crypto');
+const { buildGraph, groupIntoWaves } = require('./dependency-dag');
 
 /**
  * Semaphore for bounding concurrency within a wave.
@@ -64,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 [];
@@ -86,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({

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/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 */ }
 }