mindforge-cc 11.9.2 → 11.9.4

package/bin/dashboard/server.js

@@ -5,7 +5,7 @@
  *
  * Usage:
  *   node bin/dashboard/server.js [--port 7339] [--open]
- *   /mindforge:dashboard [--port 7339] [--open] [--stop]
+ *   /mindforge:dashboard [--port 7339] [--open] [--stop] [--status]
  *
  * Security: binds to 127.0.0.1 only (ADR-017 policy).
  * Bearer token auth on all mutating endpoints (POST/PUT/DELETE).
@@ -22,6 +22,143 @@ const ARGS   = process.argv.slice(2);
 const PORT     = parseInt(ARGS.find((_, i, a) => a[i-1] === '--port') || '7339', 10);
 const OPEN_BROWSER = ARGS.includes('--open');
 const PID_FILE = path.join(process.cwd(), '.planning', 'dashboard-server.pid');
+
+// ── Lifecycle flags: --status and --stop ──────────────────────────────────────
+//
+// THE DEFECT. `--stop` and `--status` were documented in four places and implemented in none. The
+// shipped slash command `.claude/commands/mindforge/dashboard.md` listed both in its Usage line and
+// gave each a worked example; docs/user-guide.md documented a `--start` that never existed either.
+// Worst of all, THIS FILE told the operator to run one of them: on EADDRINUSE it printed
+// "[dashboard] Stop it: /mindforge:dashboard --stop". Only `--port` and `--open` were ever parsed,
+// so every one of those instructions did nothing but start a second server.
+//
+// They are implemented rather than deleted because the PID file below already exists to support
+// them — it is written on listen and removed on shutdown, so the information was there all along.
+//
+// This runs BEFORE express is required, deliberately. This module has no `require.main` guard and
+// starts a server as a side effect of loading, so a lifecycle flag has to be handled and exited
+// here or `--stop` would stop the old server and start a new one. It also means `--status` works
+// when express is not installed, which is exactly when an operator is most likely to ask.
+if (ARGS.includes('--status') || ARGS.includes('--stop')) {
+  const { execFileSync } = require('child_process');
+
+  /** Read the recorded pid, or null when there is no usable PID file. */
+  const readPid = () => {
+    try {
+      const pid = parseInt(fs.readFileSync(PID_FILE, 'utf8').trim(), 10);
+      return Number.isInteger(pid) && pid > 0 ? pid : null;
+    } catch { return null; }
+  };
+
+  /** Signal 0 tests for existence and permission without delivering anything. */
+  const isAlive = (pid) => {
+    try { process.kill(pid, 0); return true; } catch (e) { return e.code === 'EPERM'; }
+  };
+
+  /**
+   * Confirm the pid is THIS dashboard before signalling it.
+   *
+   * A PID file is not proof: the recorded process can exit without cleanup (a SIGKILL, a power
+   * loss) and the operating system will reuse the number. Sending SIGTERM on the strength of a
+   * stale file means killing an unrelated process the operator never asked about — so identity is
+   * verified from the process table and, when it cannot be verified, this REFUSES. That is the same
+   * choice the audit writer and the vector-hub conflict path make: declining loudly beats acting on
+   * a guess.
+   *
+   * Returns the command line on success, or null when identity could not be established.
+   */
+  const identify = (pid) => {
+    if (process.platform === 'win32') return null;      // no ps; --stop refuses below
+    try {
+      const cmd = execFileSync('ps', ['-o', 'command=', '-p', String(pid)], { encoding: 'utf8' }).trim();
+
+      // IDENTITY, not shape. Two earlier versions of this check were both too loose, and the second
+      // was the more dangerous:
+      //
+      //   /dashboard[/\\]server\.js/                       matched any process whose command line
+      //                                                    MENTIONED the path — a shell running a
+      //                                                    script that referenced it got a SIGTERM
+      //   /^\S*node...\S*dashboard[/\\]server\.js(\s|$)/   matched any `node <anything>/dashboard/
+      //                                                    server.js`. `dashboard/server.js` is an
+      //                                                    utterly ordinary path: this would have
+      //                                                    signalled an UNRELATED app's dashboard
+      //                                                    (verified against
+      //                                                    `node /var/www/unrelated_app/dashboard/server.js`)
+      //
+      // Anchoring made the first mistake unreachable and left a worse one, because both were asking
+      // "does this look like a dashboard server" when the only safe question is "is this THE one I am".
+      // So the script argument is resolved and compared against this file's own realpath.
+      //
+      // A relative script path cannot be resolved from here — it would need the target process's cwd,
+      // which ps does not give us — so that case REFUSES rather than guessing. Same choice as
+      // commitDb's conflict path: declining loudly beats acting on a guess, and the cost of being
+      // wrong here is someone else's process dying.
+      const m = /^\S*node(?:\.exe)?\s+(\S+)/.exec(cmd);
+      if (!m) return null;
+      const script = m[1];
+      if (!path.isAbsolute(script)) return null;        // unresolvable without the target's cwd
+      let resolved;
+      let self;
+      try {
+        resolved = fs.realpathSync(script);
+        self = fs.realpathSync(__filename);
+      } catch { return null; }                          // script gone, or unreadable — refuse
+      return resolved === self ? cmd : null;
+    } catch { return null; }
+  };
+
+  const pid = readPid();
+  const alive = pid !== null && isAlive(pid);
+
+  if (ARGS.includes('--status')) {
+    if (!alive) {
+      console.log(pid === null
+        ? '[dashboard] not running (no PID file)'
+        : `[dashboard] not running (stale PID file records ${pid})`);
+      process.exit(1);
+    }
+    const cmd = identify(pid);
+    // No port claimed. PORT here is whatever THIS invocation was told, not what the running
+    // process bound — measured, `--status` on a server started with --port 7466 printed "port 7339",
+    // the default this process happened to receive. The PID file records only the pid, so the port is
+    // not knowable from here, and stating a number we cannot know is the defect this file is full of
+    // fixes for.
+    console.log(`[dashboard] running — pid ${pid}`);
+    if (!cmd && process.platform !== 'win32') {
+      console.log(`[dashboard] warning: pid ${pid} is alive but does not look like this server, so `
+        + 'the PID file may be stale and the number reused');
+    }
+    process.exit(0);
+  }
+
+  // --stop
+  if (!alive) {
+    console.error(pid === null
+      ? '[dashboard] nothing to stop (no PID file)'
+      : `[dashboard] nothing to stop (stale PID file records ${pid})`);
+    if (pid !== null) { try { fs.rmSync(PID_FILE, { force: true }); } catch { /* best effort */ } }
+    process.exit(1);
+  }
+  if (process.platform === 'win32') {
+    console.error(`[dashboard] REFUSING to stop pid ${pid}: process identity cannot be verified on `
+      + 'this platform. Stop the server with CTRL+C in its own terminal.');
+    process.exit(1);
+  }
+  if (!identify(pid)) {
+    console.error(`[dashboard] REFUSING to stop pid ${pid}: it is running, but is not this `
+      + 'dashboard. The PID file is stale and the number has been reused — signalling it would kill '
+      + `an unrelated process. Delete ${PID_FILE} if you are sure it is obsolete.`);
+    process.exit(1);
+  }
+  try {
+    process.kill(pid, 'SIGTERM');
+    console.log(`[dashboard] SIGTERM sent to pid ${pid}`);
+    process.exit(0);
+  } catch (err) {
+    console.error(`[dashboard] could not stop pid ${pid}: ${err.message}`);
+    process.exit(1);
+  }
+}
 const FRONTEND = path.join(__dirname, 'frontend', 'index.html');
 
 // ── Load dependencies gracefully ──────────────────────────────────────────────
@@ -179,6 +316,28 @@ app.get('/', (req, res) => {
   res.sendFile(FRONTEND);
 });
 
+// The application itself, as an EXTERNAL script. It used to be an inline <script> in index.html,
+// which this server's own CSP (`script-src 'self'`, set above) blocks — so the whole front end never
+// executed while the static shell displayed "● Connected". Measured in a headless browser:
+// "Executing inline script violates ... 'script-src 'self''. The action has been blocked.",
+// typeof window.showPage === undefined, and GET /api/connections === {"clients":0}.
+//
+// Serving it from the same origin satisfies the existing policy WITHOUT weakening it — no
+// 'unsafe-inline', no hash, no nonce. An explicit route rather than express.static: the frontend
+// directory is the only thing that should be reachable, and a static mount would expose whatever else
+// lands there later.
+const FRONTEND_ASSETS = new Set(['app.js']);
+app.get('/:asset', (req, res, next) => {
+  if (!FRONTEND_ASSETS.has(req.params.asset)) return next();
+  const file = path.join(path.dirname(FRONTEND), req.params.asset);
+  // Defence in depth: the allowlist already forbids traversal, but resolve and re-check anyway so a
+  // future edit to FRONTEND_ASSETS cannot turn this into a file-read primitive.
+  if (path.dirname(path.resolve(file)) !== path.dirname(path.resolve(FRONTEND))) return next();
+  if (!fs.existsSync(file)) return res.status(404).send('// asset not found');
+  res.type('application/javascript');
+  return res.sendFile(file);
+});
+
 // ── Token refresh endpoint (requires valid existing token) ───────────────────
 app.post('/api/v1/token/refresh', requireAuth, (req, res) => {
   const newToken = crypto.randomBytes(32).toString('hex');

package/bin/dashboard/sse-bridge.js

@@ -136,21 +136,24 @@ function pollApprovals() {
     if (mtime === _lastMtimes[APPROVAL_DIR]) return; // unchanged
     _lastMtimes[APPROVAL_DIR] = mtime;
 
+    // Reads `approval-*.json`, the name the only producer (bin/governance/approve.js) actually
+    // writes. The old filter was startsWith('APPROVAL-'), which matched nothing on any platform:
+    // String.prototype.startsWith is case-sensitive regardless of the filesystem, so macOS's
+    // case-insensitive lookup (which affects fs.open, not this comparison) did not save it.
     const files  = fs.readdirSync(APPROVAL_DIR)
-      .filter(f => f.startsWith('APPROVAL-') && f.endsWith('.json'))
+      .filter(f => f.endsWith('.json'))
       .sort();
     const key = files.join(',');
     if (key === _lastApprovals) return;
     _lastApprovals = key;
 
-    // Find new pending approvals
+    // Announce records as they appear. The previous condition was `data.status === 'pending'`, a
+    // field no producer has ever written, so this loop could never broadcast. There is no
+    // pending-request concept to restore either — approve.js records an already-made decision.
+    // Only the filename is sent; a listener that wants contents calls GET /api/approvals, which
+    // returns each record with its verified integrity state.
     for (const f of files) {
-      try {
-        const data = JSON.parse(fs.readFileSync(path.join(APPROVAL_DIR, f), 'utf8'));
-        if (data.status === 'pending') {
-          broadcast('approval:new', data);
-        }
-      } catch { /* skip */ }
+      broadcast('approval:new', { file: f });
     }
   } catch { /* ignore */ }
 }

package/bin/engine/sre-manager.js

@@ -69,7 +69,7 @@ class SREManager {
       return { status: 'PLAINTEXT', content: thoughtChain };
     }
 
-    // v5 Pillar VI: Merkle-style Cumulative Hash Chain
+    // v5 Pillar VI: cumulative SHA-256 hash chain (linear back-links, no hash tree)
     const enclaveData = this.activeEnclaves.get(enclaveId);
     const prevHash = enclaveData.cumulativeHash;
     const digest = crypto.createHash('sha256').update(thoughtChain).digest('hex');

package/bin/engine/temporal-cli.js

@@ -22,17 +22,67 @@ async function main() {
       break;
     }
 
-    case 'cleanup':
-      console.log('🧹 Cleaning up old temporal snapshots...');
-      // Logic for cleanup (e.g., keep last 100)
-      console.log('✅ Cleanup complete.');
+    // WAS TWO console.log CALLS AROUND A COMMENT. Verbatim:
+    //
+    //     console.log('🧹 Cleaning up old temporal snapshots...');
+    //     // Logic for cleanup (e.g., keep last 100)
+    //     console.log('✅ Cleanup complete.');
+    //
+    // It printed "✅ Cleanup complete." and deleted nothing, on every invocation, while
+    // `.planning/history/` grew without bound. The collector it should have called has existed all
+    // along — TemporalHub.gc, which auto-runner.js:702 and the 10.7.0 migration already use.
+    //
+    // DEFAULTS MATCH THE EXISTING CALLERS, not gc's own fallback. gc defaults maxAgeDays to 7; the
+    // migration passes 30. Seven days would make a first interactive run delete far more than an
+    // operator expects from a command that has never deleted anything, so 30 is used here.
+    //
+    // gc is bounded to `<cwd>/.planning/history/` and only ever removes DIRECTORIES directly inside
+    // it, returning early when that path does not exist. That matters now that the router runs
+    // children in the CALLER's directory: the blast radius is the caller's own snapshots, which is
+    // what a cleanup verb is for. It is still a recursive delete, so --dry-run reports the plan
+    // without touching anything.
+    case 'cleanup': {
+      const dryRun = ARGS.includes('--dry-run');
+      const before = TemporalHub.getHistory().length;
+
+      if (dryRun) {
+        // Recomputed here rather than by calling gc, because gc has no preview mode and adding one
+        // would mean a second code path that could drift from the one that deletes.
+        console.log('\n🧹  Temporal cleanup — DRY RUN, nothing will be deleted');
+        console.log(`    Snapshots now:   ${before}`);
+        console.log('    Policy:          keep newest 50, drop anything older than 30 days');
+        console.log('    Run without --dry-run to apply.\n');
+        break;
+      }
+
+      const result = await TemporalHub.gc({ maxSnapshots: 50, maxAgeDays: 30 });
+
+      // gc swallows failures into a returned `error` field rather than throwing, so a bare success
+      // message here would reproduce exactly the defect this replaces.
+      if (result.error) {
+        console.error(`❌  Cleanup FAILED: ${result.error}`);
+        console.error('    Nothing was deleted. .planning/history/ is unchanged.');
+        process.exitCode = 1;
+        break;
+      }
+
+      // The count is reported even when it is zero. "Cleanup complete" over 0 deletions is the
+      // sentence that made the old no-op invisible.
+      console.log('\n🧹  Temporal cleanup');
+      console.log(`    Deleted:    ${result.deleted} snapshot director${result.deleted === 1 ? 'y' : 'ies'}`);
+      console.log(`    Remaining:  ${result.remaining}`);
+      if (result.deleted === 0) {
+        console.log('    Nothing was old enough or over the limit — no change.');
+      }
+      console.log('');
       break;
+    }
 
     case 'inject': {
       const auditId = ARGS[1];
       const fix = ARGS.slice(2).join(' ');
       if (!auditId || !fix) {
-        console.error('Usage: /mindforge:temporal inject <auditId> <fix description>');
+        console.error('Usage: mindforge temporal inject <auditId> <fix description>');
         process.exit(1);
       }
       const result = await HindsightInjector.inject(auditId, fix);
@@ -46,7 +96,7 @@ async function main() {
     }
 
     default:
-      console.log('Usage: /mindforge:temporal <status|cleanup|inject>');
+      console.log('Usage: mindforge temporal <status|cleanup|inject>');
       break;
   }
 }

package/bin/engine/verification-runner.js

@@ -7,28 +7,114 @@ 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.
+ * Detect an ESLint configuration. Flat config (eslint 9+) and the legacy .eslintrc family both
+ * count, as does an `eslintConfig` key in package.json, because `npx eslint .` succeeds with any
+ * of them and fails with none.
+ */
+function hasEslintConfig(cwd) {
+  const named = [
+    'eslint.config.js', 'eslint.config.mjs', 'eslint.config.cjs',
+    'eslint.config.ts', 'eslint.config.mts', 'eslint.config.cts',
+    '.eslintrc', '.eslintrc.js', '.eslintrc.cjs', '.eslintrc.json',
+    '.eslintrc.yml', '.eslintrc.yaml',
+  ];
+  if (named.some((f) => fs.existsSync(path.join(cwd, f)))) return true;
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8'));
+    return Boolean(pkg.eslintConfig);
+  } catch { return false; }
+}
+
+/**
+ * Stage definitions — each maps a stage name to its command and an optional availability check.
+ *
+ * `skipIf(cwd)` returns a REASON STRING to skip, or false to run. A bare `true` still skips, for
+ * compatibility, but a reason is strongly preferred: an unexplained skip in the report is nearly as
+ * unhelpful as an unexplained failure.
+ *
+ * WHY EVERY STAGE NEEDS ONE. Only `typecheck` had an availability check, so `mindforge verify` on a
+ * freshly installed, entirely healthy consumer project reported:
+ *
+ *     | tests     | ❌ fail |
+ *     | lint      | ❌ fail |
+ *     | audit     | ❌ fail |
+ *     | typecheck | ⏭️ skip |
+ *     **Summary:** 0 passed, 3 failed, 1 skipped        exit 1
+ *
+ * Measured on `node bin/install.js --claude --local` into an empty project: 1,836 files installed,
+ * and no `tests/`, no ESLint config and no `bin/verify-audit.js` — because the installer ships none
+ * of them, which is correct. So all three stages were reporting the ABSENCE of a tool as the
+ * FAILURE of the thing it would have checked. The audit stage's "result" was a raw Node module
+ * loader stack trace.
+ *
+ * "I cannot check this here" and "this is broken" are opposite statements, and a verifier that
+ * conflates them is worse than one that runs nothing: it trains its user to ignore red.
+ *
+ * The recursion guard on `tests` is unchanged and separate — NODE_ENV=test is set by run-all.js and
+ * MINDFORGE_VERIFICATION_ACTIVE=1 by this runner, and skipping prevents infinite nesting.
  */
 const STAGE_DEFS = {
   tests: {
     command: 'node tests/run-all.js',
-    skipIf: () =>
-      process.env.MINDFORGE_VERIFICATION_ACTIVE === '1' ||
-      process.env.NODE_ENV === 'test',
+    skipIf: (cwd) => {
+      if (process.env.MINDFORGE_VERIFICATION_ACTIVE === '1' || process.env.NODE_ENV === 'test') {
+        return 'already inside a verification run (recursion guard)';
+      }
+      if (!fs.existsSync(path.join(cwd, 'tests', 'run-all.js'))) {
+        return 'no tests/run-all.js here — the package does not install a test suite';
+      }
+      return false;
+    },
   },
   lint: {
-    command: 'npx eslint . --max-warnings=0',
-    skipIf: null,
+    // `--max-warnings=0` used to be here, which made this stage IMPOSSIBLE to pass in the repo it
+    // ships from: measured, `npx eslint .` reports 199 problems / 0 errors / 199 warnings. So
+    // `mindforge verify` reported a lint FAILURE on a tree whose lint is green by the project's own
+    // definition — a confidently wrong answer, which is worse than no answer.
+    //
+    // Aligned with the project's own contract rather than a stricter threshold invented here:
+    //   package.json  "lint": "eslint ."                      (warnings tolerated)
+    //   CI            eslint . --max-warnings=9999            (warnings tolerated)
+    //   sdk CI        eslint src/ --max-warnings 0            (strict, but only over sdk/src)
+    // Two of the three tolerate warnings and the third is scoped to a different tree, so a
+    // repo-wide zero-warning gate was this file's opinion alone. Errors still fail the stage,
+    // because eslint exits non-zero on an error regardless of the warning threshold.
+    command: 'npx eslint .',
+    skipIf: (cwd) => (hasEslintConfig(cwd)
+      ? false
+      : 'no ESLint configuration here — nothing defines what lint means for this project'),
   },
   audit: {
     command: 'node bin/verify-audit.js',
-    skipIf: null,
+    // BOTH the verifier AND the log — and the comment that used to sit here asserted the opposite of
+    // measured behaviour, which is how the remaining gap survived review.
+    //
+    // It claimed "an absent AUDIT.jsonl is a legitimate empty chain that verify-audit.js reports on
+    // correctly". Measured in an empty project: `node bin/verify-audit.js` prints
+    // "❌ audit chain BROKEN at entry 0: unreadable: ENOENT: no such file or directory" and exits 1.
+    // It does not report an empty chain, it reports corruption. So wherever the script IS present and
+    // the log is not — a --with-utils install, a fresh checkout — this stage still produced a red for
+    // a project that has simply never written an audit entry. That is the same
+    // absence-reported-as-failure defect the rest of this change exists to remove.
+    //
+    // The script being missing is the state of every ordinary consumer install (the installer does not
+    // copy bin/verify-audit.js), and there the stage died in Node's module loader and printed the
+    // stack trace as its verification result.
+    skipIf: (cwd) => {
+      if (!fs.existsSync(path.join(cwd, 'bin', 'verify-audit.js'))) {
+        return 'bin/verify-audit.js is not installed here, so the audit chain cannot be verified';
+      }
+      if (!fs.existsSync(path.join(cwd, '.planning', 'AUDIT.jsonl'))) {
+        return 'no .planning/AUDIT.jsonl yet — nothing has been audited, which is not a broken chain';
+      }
+      return false;
+    },
   },
   typecheck: {
     command: 'npx tsc --noEmit',
-    skipIf: (cwd) => !fs.existsSync(path.join(cwd, 'tsconfig.json')),
+    skipIf: (cwd) => (fs.existsSync(path.join(cwd, 'tsconfig.json'))
+      ? false
+      : 'no tsconfig.json here — nothing to typecheck'),
   },
 };
 
@@ -41,9 +127,18 @@ function executeStage(name, cwd) {
     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: '' };
+  // Check availability / skip condition. A reason string is carried through to the report, because
+  // an unexplained skip leaves the reader unable to tell "not applicable here" from "silently
+  // broken" — the same ambiguity that conflating absence with failure created.
+  const skip = def.skipIf && def.skipIf(cwd);
+  if (skip) {
+    return {
+      name,
+      status: 'skip',
+      durationMs: 0,
+      output: typeof skip === 'string' ? skip : '',
+      reason: typeof skip === 'string' ? skip : undefined,
+    };
   }
 
   const start = Date.now();
@@ -112,20 +207,42 @@ function formatReport(result) {
   lines.push('');
   lines.push(`**Timestamp:** ${result.timestamp}`);
   lines.push('');
-  lines.push('| Stage | Status | Duration |');
-  lines.push('|-------|--------|----------|');
+  lines.push('| Stage | Status | Duration | Note |');
+  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} |`);
+    // A skip without its reason is unreadable: this table used to show a bare `⏭️ skip` and left the
+    // reader to guess whether the stage was inapplicable or quietly broken. Pipes are escaped so a
+    // reason can never break the markdown table.
+    const note = stage.status === 'skip' && stage.reason
+      ? String(stage.reason).replace(/\|/g, '\\|')
+      : '';
+    lines.push(`| ${stage.name} | ${emoji} ${stage.status} | ${duration} | ${note} |`);
   }
 
   lines.push('');
   lines.push(`**Summary:** ${result.summary.passed} passed, ${result.summary.failed} failed, ${result.summary.skipped} skipped (${result.summary.totalDurationMs}ms total)`);
+
+  // Say it outright when NOTHING ran. Adding availability checks fixed the false failures, but it
+  // moved a consumer install from "3 failed, exit 1" to "0 failed, exit 0" — and bin/engine/
+  // verify-cli.js exits on `failed > 0`, so a script reading $? now sees success for a run that
+  // verified nothing. Whether an all-skipped run should exit non-zero is an open maintainer
+  // decision and is deliberately NOT pre-empted here; what is not optional is that the report
+  // refuses to look like a pass.
+  if (result.summary.passed === 0 && result.summary.failed === 0 && result.summary.skipped > 0) {
+    lines.push('');
+    lines.push('> **NOTHING WAS VERIFIED.** Every stage was skipped, so this report is not '
+      + 'evidence that anything works — see the Note column for what was unavailable. A verifier '
+      + 'that ran no checks must not be read as a passing verifier.');
+  }
   lines.push('');
 
   return lines.join('\n');
 }
 
-module.exports = { runVerification, formatReport };
+// STAGE_DEFS is exported so a test can compare the lint stage's threshold against the project's own
+// lint script rather than hardcoding what it expects to find. Read-only by contract: mutating it
+// would change every subsequent run in the same process.
+module.exports = { runVerification, formatReport, STAGE_DEFS };

package/bin/engine/verify-cli.js

@@ -3,8 +3,19 @@
 
 /**
  * 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.
+ * Calls the unified verification runner across all stages, prints the formatted report, and writes it
+ * to .planning/VERIFICATION.md only when asked with --write.
+ *
+ * WHY --write RATHER THAN ALWAYS. `.planning/VERIFICATION.md` is TRACKED (`git ls-files` returns it),
+ * and this file used to overwrite it on every run — so a contributor who ran the project's own
+ * verification dirtied a tracked file and had to remember to discard it. Nothing reads the root
+ * report: the only other reference is tests/e2e.test.js:399, and that reads
+ * `.planning/phases/1/VERIFICATION-1.md`, a per-phase fixture in a generated project, not this file.
+ * The report was already printed to stdout, so gating the file loses no information.
+ *
+ * Untracking the file is the other half and belongs to the operator (`git rm --cached` plus a
+ * .gitignore entry). This change is correct either way: with the file untracked, --write becomes a
+ * convenience; while it stays tracked, --write is what stops the dirtying.
  */
 
 const path = require('path');
@@ -13,17 +24,24 @@ const { runVerification, formatReport } = require('./verification-runner');
 
 const STAGES = ['tests', 'lint', 'audit', 'typecheck'];
 const CWD = process.env.MINDFORGE_ROOT || path.resolve(__dirname, '../..');
+const REPORT_NAME = 'VERIFICATION.md';
 
 async function main() {
-  const planningDir = path.join(CWD, '.planning');
-  if (!fs.existsSync(planningDir)) {
-    fs.mkdirSync(planningDir, { recursive: true });
-  }
+  const shouldWrite = process.argv.slice(2).includes('--write');
 
   const result = await runVerification({ cwd: CWD, stages: STAGES });
   const report = formatReport(result);
 
-  fs.writeFileSync(path.join(planningDir, 'VERIFICATION.md'), report);
+  if (shouldWrite) {
+    const planningDir = path.join(CWD, '.planning');
+    if (!fs.existsSync(planningDir)) {
+      fs.mkdirSync(planningDir, { recursive: true });
+    }
+    const reportPath = path.join(planningDir, REPORT_NAME);
+    fs.writeFileSync(reportPath, report);
+    process.stdout.write(`Report written to ${reportPath}\n`);
+  }
+
   process.stdout.write(report + '\n');
   process.exit(result.summary.failed > 0 ? 1 : 0);
 }