mindforge-cc 11.9.1 → 11.9.3

package/bin/models/usage-record.js

@@ -0,0 +1,71 @@
+/**
+ * MindForge — Token-usage ledger record shape.
+ *
+ * SINGLE SOURCE OF TRUTH for `.mindforge/metrics/token-usage.jsonl`.
+ * The writer (bin/models/cost-tracker.js, fed by every provider in
+ * bin/models/*-provider.js) and every reader (bin/models/cost-tracker.js,
+ * bin/dashboard/metrics-aggregator.js) MUST go through this module so the
+ * field names cannot drift apart again.
+ *
+ * Canonical row (all five providers emit exactly this cost field):
+ *   {
+ *     model, input_tokens, output_tokens,
+ *     cache_read_input_tokens?, cache_creation_input_tokens?,
+ *     cost_usd,                       // <- the ONLY cost field. Never total_cost_usd.
+ *     task_name?, session_id?, phase?,
+ *     date,                           // 'YYYY-MM-DD', added by buildRecord()
+ *     timestamp                       // full ISO 8601, added by buildRecord()
+ *   }
+ *
+ * `total_cost_usd` is a DIFFERENT concept that belongs to cross-review reports
+ * (bin/review/cross-review-engine.js:72) and must never appear in this ledger.
+ *
+ * NOTE ON PATHS: resolution stays on process.cwd() (not bin/utils/paths.js
+ * findProjectRoot) to preserve today's behaviour exactly; relocating user state
+ * is deliberately deferred to v12.
+ *
+ * KNOWN STALE SITE, deliberately NOT migrated here: bin/migrations/1.0.0-to-2.0.0.js:93
+ * resolves the ledger to .planning/token-usage.jsonl — a path that has never existed —
+ * so that migration silently no-ops. Repointing it is out of scope for COST-01 because
+ * it would start a migration that has never run against real data. Until then, this
+ * module is the single source of truth for every LIVE reader and writer, not literally
+ * every path-resolution site in the tree.
+ */
+'use strict';
+
+const path = require('path');
+
+// Project-root-relative location of the append-only usage ledger.
+const LEDGER_SEGMENTS = ['.mindforge', 'metrics', 'token-usage.jsonl'];
+
+/** Absolute path to the ledger. Resolved lazily so tests can chdir. */
+function ledgerPath(root = process.cwd()) {
+  return path.join(root, ...LEDGER_SEGMENTS);
+}
+
+/** Directory containing the ledger. */
+function ledgerDir(root = process.cwd()) {
+  return path.join(root, ...LEDGER_SEGMENTS.slice(0, -1));
+}
+
+/** Stamp a provider result into a canonical ledger row. */
+function buildRecord(entry, now = new Date()) {
+  const iso = now.toISOString();
+  return { ...entry, date: iso.slice(0, 10), timestamp: iso };
+}
+
+/** Cost of one row, in USD. Returns 0 for absent/non-finite values. */
+function entryCost(entry) {
+  const v = entry && entry.cost_usd;
+  return typeof v === 'number' && Number.isFinite(v) ? v : 0;
+}
+
+/** 'YYYY-MM-DD' day of one row: prefers `date`, falls back to `timestamp`. */
+function entryDay(entry) {
+  if (!entry) return '';
+  if (typeof entry.date === 'string' && entry.date.length >= 10) return entry.date.slice(0, 10);
+  if (typeof entry.timestamp === 'string' && entry.timestamp.length >= 10) return entry.timestamp.slice(0, 10);
+  return '';
+}
+
+module.exports = { LEDGER_SEGMENTS, ledgerPath, ledgerDir, buildRecord, entryCost, entryDay };

package/bin/revops/debt-monitor.js

@@ -4,27 +4,69 @@
  */
 'use strict';
 
-const fs = require('fs');
-const path = require('path');
+// A `require('fs')` and a `this.auditPath = path.join(...)` used to sit here. Both were dead —
+// `grep 'fs\.'` over this file returns nothing and no caller reads `auditPath` — and their presence
+// implied this module reads the audit log, which it does not. Its only input is the array handed to
+// monitor() by bin/dashboard/revops-api.js. Removed so the module's actual surface is legible.
 
-class DebtMonitor {
-  constructor() {
-    this.auditPath = path.join(process.cwd(), '.planning', 'AUDIT.jsonl');
-  }
+/**
+ * The score is computed from exactly these three event types. If an audit log contains none of them,
+ * this module measured NOTHING — which is a different state from measuring cleanly, and the whole
+ * point of the sentinel below.
+ */
+const TRACKED_EVENTS = ['security_finding', 'approval_granted', 'policy_bypass'];
+
+/**
+ * Reported in place of a score, a status and a debt level when nothing was measured.
+ *
+ * WHY A STRING and not null. Both dashboard frontends call `.toUpperCase()` on `governance_status`
+ * and `debt_level` (index.html:735,747 and, in PR #186's extracted copy, app.js:395,407 — verified
+ * byte-identical), so null or a number is a hard TypeError there, not a blank tile.
+ * `security_health_score` is assigned with a bare `textContent =` (index.html:732), so a string
+ * passes straight through and renders as the word. Confirmed by loading the real render function into
+ * a headless browser: the tile reads "Unmeasured", the badge "STATUS: UNMEASURED", and the `> 80`
+ * colour comparison is false, so the badge goes red rather than green. No frontend edit needed.
+ */
+const UNMEASURED = 'Unmeasured';
 
+class DebtMonitor {
   /**
    * Monitor governance debt and security health.
    * @param {Object} metrics - From MetricsAggregator
    */
   monitor(metrics) {
     const auditEntries = metrics.auditEntries || [];
-    
-    // 1. Identify high-risk events
-    const criticalFindings = auditEntries.filter(e => e.event === 'security_finding' && e.severity === 'critical');
-    const tier3Approvals  = auditEntries.filter(e => e.event === 'approval_granted' && e.tier === 3);
-    const policyBypasses   = auditEntries.filter(e => e.event === 'policy_bypass');
 
-    // 2. Calculate Health Score (starts at 100)
+    // 1. Identify high-risk events.
+    //    Severity is compared case-INSENSITIVELY. It used to require lowercase 'critical', while
+    //    .mindforge/audit/AUDIT-SCHEMA.md:269 declares severity uppercase ("HIGH"). Measured: three
+    //    schema-compliant `severity: 'CRITICAL'` findings scored 100/"Excellent"/"Minimal", while the
+    //    same three lowercase scored 70/"Warning"/"Moderate" — so a compliant writer was invisible.
+    const criticalFindings = auditEntries.filter((e) => e.event === 'security_finding'
+      && String(e.severity || '').toLowerCase() === 'critical');
+    const tier3Approvals = auditEntries.filter((e) => e.event === 'approval_granted' && e.tier === 3);
+    const policyBypasses = auditEntries.filter((e) => e.event === 'policy_bypass');
+
+    // 2. Refuse to report health that was never measured.
+    //    Previously an absent audit log, an empty one, and a clean one were indistinguishable: all
+    //    three returned 100 / "Excellent" / "Minimal". Measured, the absent and empty cases were
+    //    byte-identical but for the timestamp. Reporting a maximum for the absence of evidence is
+    //    the inverse of what a security score is for.
+    const measuredEvents = auditEntries.filter((e) => TRACKED_EVENTS.includes(e.event)).length;
+    if (measuredEvents === 0) {
+      return {
+        security_health_score: UNMEASURED,
+        governance_status: UNMEASURED,
+        critical_findings: 0,
+        tier3_approvals: 0,
+        policy_bypasses: 0,
+        debt_level: UNMEASURED,
+        measured: false,
+        timestamp: new Date().toISOString(),
+      };
+    }
+
+    // 3. Calculate Health Score (starts at 100)
     let score = 100;
     score -= (criticalFindings.length * 10);
     score -= (tier3Approvals.length * 5);
@@ -32,7 +74,7 @@ class DebtMonitor {
 
     const healthScore = Math.max(0, score);
 
-    // 3. Determine status
+    // 4. Determine status
     let status = 'Excellent';
     if (healthScore < 90) status = 'Good';
     if (healthScore < 75) status = 'Warning';
@@ -45,6 +87,7 @@ class DebtMonitor {
       tier3_approvals: tier3Approvals.length,
       policy_bypasses: policyBypasses.length,
       debt_level: this.getDebtLevel(healthScore),
+      measured: true,
       timestamp: new Date().toISOString()
     };
   }
@@ -58,3 +101,4 @@ class DebtMonitor {
 }
 
 module.exports = new DebtMonitor();
+module.exports.UNMEASURED = UNMEASURED;

package/bin/security/trust-gate-hook.js

@@ -3,6 +3,53 @@
 
 const { isHighImpact } = require('./trust-boundaries');
 
+/**
+ * WHY THERE IS NO TOOL-NAME CHECK HERE.
+ *
+ * THE DEFECT. This hook used to open with `if (event.tool_name !== 'Bash') process.exit(0)`, so a
+ * deny-class gate permitted every call whose tool was not spelled with that exact string. Measured
+ * against the real hook with one destructive command and only the tool name varied:
+ *
+ *     tool_name=Bash              -> DENY (exit 2)
+ *     tool_name=Shell             -> PERMIT (exit 0)
+ *     tool_name=shell             -> PERMIT (exit 0)
+ *     tool_name=PowerShell        -> PERMIT (exit 0)
+ *     tool_name=run_terminal_cmd  -> PERMIT (exit 0)
+ *     tool_name=Terminal          -> PERMIT (exit 0)
+ *
+ * That is reachable today, not hypothetical. Verified inside cursor-agent 2026.04.17's own bundle:
+ * it loads the exact file the installer writes —
+ *
+ *     claudeProjectConfigPath: join(e, ".claude", "settings.json")
+ *     claudeUserConfigPath:    join(homedir(), ".claude", "settings.json")
+ *
+ * — and translates Claude matcher names to its own tool names through
+ * `{Bash:"Shell", Read:"Read", Write:"Write", Edit:"Write", Grep:"Grep", ...}`, while its hook
+ * normaliser defaults to `{loop_limit:null, failClosed:!1}`. So opening a MindForge-installed project
+ * in Cursor silently drops this gate, and its shell payload carries the SAME
+ * `{command, workingDirectory, timeout}` shape — meaning nothing but the name check stood between a
+ * destructive command and execution, while the install receipt reported three deny-class hooks
+ * verified blocking.
+ *
+ * THE SCOPE IS `tool_input.command`, AND THAT IS SUFFICIENT. No name list replaces the check, because
+ * a list only ever covers the harnesses someone thought to enumerate and the next one that spells its
+ * tool differently reopens the hole in silence. Every shell tool observed — Claude Code's Bash and
+ * Cursor's Shell — passes the command as `tool_input.command`, so reading that field IS the scoping:
+ * a Write, Edit, Read or Grep payload has no `.command`, yields the empty string, and is permitted
+ * without a name ever being consulted. An unknown harness using the conventional shape now fails
+ * CLOSED instead of open.
+ *
+ * A FIRST ATTEMPT AT THIS FIX ADDED A `looksLikeShellCall()` GUARD, and falsification proved it did
+ * nothing. Deleting that guard outright left all 14 tests green, because the extraction below already
+ * scopes the gate. Its comment claimed removal would over-block Write payloads whose CONTENT mentions
+ * a destructive command — measurably false, since such payloads carry no `.command`. Keeping it would
+ * have shipped machinery that looks like enforcement and performs none, which is the exact defect
+ * class this gate was being repaired for. So it is gone, and this comment stands in its place.
+ *
+ * MCP calls are unaffected: Cursor passes `tool_input: JSON.stringify(d)` for those, so `.command` on
+ * a string is undefined and the gate declines rather than guessing.
+ */
+
 let input = '';
 process.stdin.setEncoding('utf8');
 process.stdin.on('data', (chunk) => { input += chunk; });
@@ -10,12 +57,9 @@ process.stdin.on('end', () => {
   try {
     const event = JSON.parse(input);
 
-    // Only gate Bash tool calls
-    if (event.tool_name !== 'Bash') {
-      process.exit(0); // allow
-    }
-
-    const fullCommand = event.tool_input?.command || '';
+    // Scoped by payload shape, NOT by tool name — see the header for the measured fail-open this
+    // replaces. A non-executing call has no `.command`, so it yields '' and is permitted below.
+    const fullCommand = (typeof event.tool_input?.command === 'string' ? event.tool_input.command : '');
 
     // Check the whole command AND every individual line, blocking if ANY
     // segment is high-impact. Per-line scanning means a benign first line

package/bin/skill-validator.js

@@ -22,7 +22,12 @@ const colors = {
 };
 
 function main() {
-  const target = ARGS[0];
+  // The first NON-FLAG argument. This was `ARGS[0]`, so any flag placed before the path was taken
+  // as the filename: `validate-skill --no-color skill/SKILL.md` reported
+  // "File not found: <cwd>/--no-color" and exited 1. Flags-before-operands is the ordering most
+  // people reach for, and the two flags this tool documents (--no-color, --enterprise) are both
+  // read from anywhere in ARGS, so only the target lookup was position-sensitive.
+  const target = ARGS.find((a) => !a.startsWith('-'));
   if (!target || ARGS.includes('--help') || ARGS.includes('-h')) {
     console.log('\nUsage: mindforge-cc validate-skill <path-to-SKILL.md>\n');
     process.exit(0);

package/bin/skills-builder/skill-scorer.js

@@ -44,17 +44,57 @@ const GENERIC_TRIGGERS = new Set([
   'response', 'handler', 'controller', 'repository', 'schema',
 ]);
 
+// ── Trigger frontmatter, in both grammars ─────────────────────────────────────
+//
+// THE DEFECT THIS FIXES. This parser required a YAML BLOCK list:
+//
+//     const triggersSection = frontmatter.match(/^triggers:\n((?: {2}- .+\n?)*)/m);
+//
+// The shipped corpus is written in the INLINE comma form. Measured by driving this module's real
+// parseSkill over the real .mindforge/skills tree: 232 skills, 232 with ZERO triggers, mean 0.00 —
+// 232 inline, 0 block. So every engine skill scored 0 of the 30 points `score()` awards for trigger
+// coverage (:95-99), and the suggestion at :233 told skills carrying 12 triggers to "add 25 more to
+// reach 25+ (currently 0)". Three callers — learn-cli.js, skill-registrar.js, skill-generator.js —
+// make registration decisions against that uniformly-zero scoreboard.
+//
+// bin/skill-validator.js:119 has always read the inline form (`fm.triggers.split(',')`). Two readers
+// of the same field, two incompatible grammars, and the corpus written in the one the scorer could
+// not read. The DIVERGENCE is the real defect; the regex is just where it surfaced.
+//
+// BOTH grammars are supported deliberately. The block form is not legacy cruft: all three fixtures
+// in tests/self-building-skills.test.js use it, and :209 asserts >= 24 triggers on one of them, so
+// dropping it would silently zero those fixtures and the test would still pass for the wrong reason.
+//
+// DELIBERATELY NOT DONE HERE: extracting one shared frontmatter reader so the scorer and the
+// validator cannot diverge again. That is the durable fix, but it edits bin/skill-validator.js,
+// which PR #185 is currently changing. Doing it here would collide. Follow-up once #185 lands.
+function parseTriggers(frontmatter) {
+  // Block form first. The ordering is defence in depth, not the load-bearing part — verified rather
+  // than assumed: the `\S` in the inline pattern below already makes it REJECT a block-form header,
+  // because after `triggers:` the next character is a newline and `.` does not match one. Loosen
+  // that `\S` to `.` and the inline branch starts matching block form with an EMPTY capture, so a
+  // list of triggers would silently parse as none. Two independent things prevent that; keep both.
+  // `[ \t]+` rather than the old `{2}` — two spaces is a convention, not a requirement.
+  const block = frontmatter.match(/^triggers:[ \t]*\n((?:[ \t]+-[ \t]+.+\n?)+)/m);
+  if (block) {
+    return block[1].split('\n').map((l) => l.replace(/^\s*-\s*/, '').trim()).filter(Boolean);
+  }
+
+  // Inline comma form, e.g. `triggers: a11y testing, axe-core, WCAG compliance test`.
+  const inline = frontmatter.match(/^triggers:[ \t]*(\S.*)$/m);
+  if (inline) {
+    return inline[1].split(',').map((t) => t.trim()).filter(Boolean);
+  }
+
+  return [];
+}
+
 // ── SKILL.md parser ───────────────────────────────────────────────────────────
 function parseSkill(content) {
   const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
   const frontmatter      = frontmatterMatch?.[1] || '';
 
-  // Extract triggers from frontmatter
-  const triggersSection = frontmatter.match(/^triggers:\n((?: {2}- .+\n?)*)/m);
-  const triggers        = (triggersSection?.[1] || '')
-    .split('\n')
-    .map(l => l.replace(/^\s*- /, '').trim())
-    .filter(Boolean);
+  const triggers = parseTriggers(frontmatter);
 
   // Count code blocks with ≥ 3 lines (meaningful examples, not one-liners)
   const codeBlockMatches = content.match(/```[\s\S]*?```/g) || [];

package/bin/updater/self-update.js

@@ -10,7 +10,12 @@ const { execSync }         = require('child_process');
 const { compareSemver, upgradeType, fetchLatestVersion } = require('./version-comparator');
 const { fetchChangelog }   = require('./changelog-fetcher');
 
-const CURRENT_VERSION = require('../../package.json').version;
+// MindForge's OWN version, not the host project's. `require('../../package.json')` resolved to
+// the CONSUMER's manifest once bin/updater/ was copied into a project — measured 1.0.0 for an
+// app installed alongside MindForge 11.9.2, which made every upgrade read as MAJOR and fed a
+// bogus "from" version into the migration path below.
+const { resolveMindforgeVersion } = require('../utils/mindforge-version');
+const CURRENT_VERSION = resolveMindforgeVersion({ fromDir: __dirname }).version;
 
 /**
  * Detect where MindForge was originally installed.

package/bin/updater/version-comparator.js

@@ -37,6 +37,26 @@ function upgradeType(current, latest) {
  * Returns null on any error — callers must handle gracefully.
  * Timeout: 5 seconds (respects enterprise proxies that may be slow).
  */
+/**
+ * MindForge's own version for the User-Agent, or 'unknown'.
+ *
+ * The header used to interpolate `require('../../package.json').version`, which in an INSTALL is
+ * the consumer's manifest — measured 1.0.0 for a host app sitting alongside MindForge 11.9.2, so
+ * the registry saw the wrong client version. Resolved by package NAME instead.
+ *
+ * Required inline, and failure degrades to 'unknown' rather than throwing: this file documents
+ * itself as pure with no external dependencies, and an unresolvable version is no reason to break
+ * an update check. self-update.js throws in the same situation, correctly — there a wrong version
+ * would misclassify the upgrade.
+ */
+function userAgentVersion() {
+  try {
+    return require('../utils/mindforge-version').resolveMindforgeVersion({ fromDir: __dirname }).version;
+  } catch {
+    return 'unknown';
+  }
+}
+
 async function fetchLatestVersion(packageName = 'mindforge-cc') {
   const https = require('https');
   return new Promise(resolve => {
@@ -44,7 +64,7 @@ async function fetchLatestVersion(packageName = 'mindforge-cc') {
       hostname: 'registry.npmjs.org',
       path:     `/${encodeURIComponent(packageName)}/latest`,
       method:   'GET',
-      headers:  { 'Accept': 'application/json', 'User-Agent': `mindforge-cc/${require('../../package.json').version}` },
+      headers:  { 'Accept': 'application/json', 'User-Agent': `mindforge-cc/${userAgentVersion()}` },
       timeout:  5000,
     };
 

package/bin/utils/file-lock.js

@@ -0,0 +1,106 @@
+'use strict';
+
+/**
+ * MindForge — Fail-closed advisory file lock (LOCK-01).
+ *
+ * Promoted from bin/learning/instinct-cli.js:78-100 (`withStoreLock`), preserving its
+ * semantics: an O_CREAT|O_EXCL lockfile beside the target, a bounded retry spin, a
+ * stale-reclaim by mtime for locks orphaned by a killed process, and unlink in finally.
+ *
+ * FAIL-CLOSED: when the lock cannot be taken this THROWS. It NEVER writes anyway.
+ * Deliberately NOT modelled on .agent/bin/lib/state.cjs:784-789, which unlinks the other
+ * holder's lock and writes regardless on its last retry — that converts a detectable
+ * contention error into silent data loss.
+ *
+ * `fn` MUST be SYNCHRONOUS. The re-entrancy depth counter below is only sound because
+ * nothing else in this process can interleave between acquire and release.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const MAX_TRIES = 50;      // 50 x 20-40ms => ~1-2s ceiling before failing closed
+const WAIT_MS = 20;
+const STALE_MS = 10000;    // reclaim a lockfile whose mtime is older than this
+
+// Re-entrancy depth per lockfile. Required: knowledge-graph applyDecay() holds this
+// lock and calls deprecateEdge(), which takes the SAME lock. Without re-entrancy that
+// self-deadlocks and then fails closed, so a decay pass could never prune an edge.
+const _held = new Map(); // lockPath -> depth
+
+const _sleepView = new Int32Array(new SharedArrayBuffer(4));
+
+/** Blocking sleep that does not burn a core; busy-waits if Atomics.wait is refused. */
+function sleepSync(ms) {
+  try {
+    Atomics.wait(_sleepView, 0, 0, ms);
+  } catch {
+    const until = Date.now() + ms;
+    while (Date.now() < until) { /* busy-wait fallback */ }
+  }
+}
+
+/**
+ * Rejects an async fn. The `finally` in withFileLock unlinks the lockfile the moment
+ * fn() returns, so a promise-returning fn would run its critical section UNLOCKED while
+ * looking guarded. Failing loudly here is far cheaper than debugging that corruption.
+ */
+function assertSync(out) {
+  if (out && typeof out.then === 'function') {
+    throw new TypeError('withFileLock requires a SYNCHRONOUS fn; got a thenable');
+  }
+  return out;
+}
+
+/**
+ * Runs fn() while holding an exclusive advisory lock on `${targetPath}.lock`.
+ * @param {string} targetPath  the file being protected (the lock is a sibling `.lock`)
+ * @param {Function} fn        SYNCHRONOUS critical section; its return value is returned
+ * @param {object} [opts]      { maxTries, waitMs, staleMs, label }
+ * @returns {*} whatever fn() returns
+ * @throws if the lock cannot be acquired within maxTries — the caller MUST NOT write
+ */
+function withFileLock(targetPath, fn, opts = {}) {
+  const lock = `${targetPath}.lock`;
+
+  const depth = _held.get(lock) || 0;
+  if (depth > 0) {                       // already ours — re-enter, do not re-acquire
+    _held.set(lock, depth + 1);
+    try { return assertSync(fn()); }
+    finally { _held.set(lock, _held.get(lock) - 1); }
+  }
+
+  const maxTries = opts.maxTries ?? MAX_TRIES;
+  const waitMs = opts.waitMs ?? WAIT_MS;
+  const staleMs = opts.staleMs ?? STALE_MS;
+  const label = opts.label || targetPath;
+
+  // The lock must be creatable before the target's own mkdir runs, so ensure the dir
+  // here. A bad path still throws ENOTDIR/ENOENT to the caller, unchanged.
+  fs.mkdirSync(path.dirname(lock), { recursive: true });
+
+  let acquired = false;
+  for (let i = 0; i < maxTries && !acquired; i++) {
+    try {
+      fs.closeSync(fs.openSync(lock, 'wx'));   // O_CREAT|O_EXCL|O_WRONLY
+      acquired = true;
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+      try {
+        const age = Date.now() - fs.statSync(lock).mtimeMs;
+        if (age > staleMs) { fs.unlinkSync(lock); continue; }   // orphaned by a kill
+      } catch { /* lock vanished between EEXIST and stat — retry */ }
+      sleepSync(waitMs + Math.floor(Math.random() * waitMs));   // jitter breaks the herd
+    }
+  }
+  if (!acquired) throw new Error(`could not acquire ${label} lock: ${lock}`);
+
+  _held.set(lock, 1);
+  try { return assertSync(fn()); }
+  finally {
+    _held.set(lock, 0);
+    try { fs.unlinkSync(lock); } catch { /* already gone */ }
+  }
+}
+
+module.exports = { withFileLock, MAX_TRIES, WAIT_MS, STALE_MS };

package/bin/utils/mindforge-params.js

@@ -0,0 +1,124 @@
+'use strict';
+/**
+ * MindForge — MINDFORGE.md parameter parser (single source of truth).
+ *
+ * TWO on-disk forms are supported, because both ship:
+ *
+ * 1. BRACKETED (current, MINDFORGE.md) — 43 keys in the shipped registry:
+ *        [PLANNER]  = claude-opus-4-7
+ *        [MODE]     = "Platform Sovereign"
+ *        [API_URL]  = <http://localhost:3000>
+ *        [PQAS_ENFORCED] = false  # trailing note
+ *        [FORBIDDEN] = """
+ *        ...multi-line block...
+ *        """
+ *
+ * 2. LEGACY PLAIN (shell-style) — 28 keys in examples/starter-project/MINDFORGE.md,
+ *    which ships (package.json files[] contains "examples/"), and the
+ *    tests/cli-router.test.js:110 fixture. A bracket-only parser silently
+ *    zeroes those out:
+ *        MAX_TASKS_PER_PHASE=999
+ *        DISABLED_SKILLS=            <- empty value is LEGAL, hence (.*) not (.+)
+ *
+ * Bracketed semantics are ported from sdk/src/client.ts:141-158 (the only
+ * previously correct bracket-aware reader) and extended with value
+ * normalisation so the runtime and the validator agree on one interpretation.
+ *
+ * NOT captured: prose bullets such as `- [MIN_SOUL_SCORE] — description`
+ * (section 7 of MINDFORGE.md). A bracketed key only counts when the bracket
+ * opens the line (leading whitespace allowed) and is followed by `=`.
+ *
+ * The legacy form deliberately allows NO leading whitespace, matching the two
+ * regexes it replaces (bin/validate-config.js:36, bin/models/model-router.js:48).
+ * That is a safety property, not an oversight: it stops indented `KEY=value`
+ * lines inside markdown code blocks from being read as configuration.
+ */
+
+const fs = require('fs');
+
+/** [KEY] = value — key must open the line; only spaces/tabs may precede it. */
+const ASSIGN_RE = /^[ \t]*\[([A-Z0-9_]+)\][ \t]*=[ \t]*(.*)$/;
+
+/** KEY=value — legacy plain form. Column 0 only. `(.*)`: empty values are legal. */
+const LEGACY_RE = /^([A-Z0-9_]+)=(.*)$/;
+
+const FENCE = '"""';
+
+/** Drop a trailing ` # comment`. Requires whitespace before `#` so that
+ *  values legitimately containing `#` (URL fragments, colours) survive. */
+function stripComment(raw) {
+  const i = raw.search(/\s#/);
+  return i === -1 ? raw : raw.slice(0, i);
+}
+
+/** Unwrap "quoted" values and <markdown-autolink> URLs. */
+function unwrap(v) {
+  if (v.length >= 2 && v.startsWith('"') && v.endsWith('"')) return v.slice(1, -1);
+  if (v.length >= 2 && v.startsWith('<') && v.endsWith('>')) return v.slice(1, -1);
+  return v;
+}
+
+function normalise(raw) {
+  return unwrap(stripComment(raw).trim());
+}
+
+/**
+ * @param {string} content raw MINDFORGE.md text
+ * @returns {Record<string,string>} key -> normalised string value
+ */
+function parseParams(content) {
+  const bracketed = {};
+  const legacy    = {};
+  const lines = String(content).split(/\r?\n/);
+
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(ASSIGN_RE);
+
+    if (!m) {
+      // Legacy plain form. Only reached when the line is not a bracketed
+      // assignment; the two patterns can never both match one line.
+      const g = lines[i].match(LEGACY_RE);
+      if (g) legacy[g[1]] = normalise(g[2]);
+      continue;
+    }
+
+    const key = m[1];
+    const rest = m[2].trim();
+
+    if (rest.startsWith(FENCE)) {
+      const inline = rest.slice(FENCE.length);
+      // Single-line fenced value: [K] = """text"""
+      if (inline.trimEnd().endsWith(FENCE) && inline.trim().length >= FENCE.length) {
+        bracketed[key] = inline.trimEnd().slice(0, -FENCE.length).trim();
+        continue;
+      }
+      const block = [];
+      let j = i + 1;
+      for (; j < lines.length; j++) {
+        if (lines[j].trim() === FENCE) break;
+        block.push(lines[j]);
+      }
+      bracketed[key] = block.join('\n').trim();
+      i = j; // resume after the closing fence (or at EOF)
+      continue;
+    }
+
+    bracketed[key] = normalise(rest);
+  }
+
+  // Bracketed is the canonical modern form and wins on collision, regardless
+  // of which appeared first in the file.
+  return { ...legacy, ...bracketed };
+}
+
+/**
+ * Read + parse a MINDFORGE.md. Returns {} when the file is absent so callers
+ * can fall back to their own defaults (fail-open on absence, not on garbage).
+ * @param {string} filePath
+ */
+function readParams(filePath) {
+  if (!fs.existsSync(filePath)) return {};
+  return parseParams(fs.readFileSync(filePath, 'utf8'));
+}
+
+module.exports = { parseParams, readParams, ASSIGN_RE, LEGACY_RE };