mindforge-cc 11.9.2 → 11.9.3

package/bin/models/cost-tracker.js

@@ -49,21 +49,119 @@ function getTodaySpendCached() {
   return _dailyCache.value;
 }
 
+// COST-02 — the $25/day cap declared at MINDFORGE.md:54 was inert from the day it
+// was written. v11.9.2 read `settings.MODEL_COST_HARD_LIMIT_USD`; the registry
+// declares `[COST_HARD_LIMIT_USD]`. The MODEL_-prefixed name appears in exactly one
+// shipped file (.mindforge/MINDFORGE-V2-SCHEMA.json:58) and that file has no code
+// reader, so the lookup was always undefined -> parseFloat('0.0') -> 0 -> the
+// `hardLimit <= 0` guard returned before any spend was compared. Canonical registry
+// key first; the MODEL_-prefixed name is still read second so anyone who copied it
+// out of the V2 schema keeps the working cap they have instead of silently losing it.
+const HARD_LIMIT_KEYS = ['COST_HARD_LIMIT_USD', 'MODEL_COST_HARD_LIMIT_USD'];
+const WARN_LIMIT_KEYS = ['COST_WARN_USD', 'MODEL_COST_WARN_USD'];
+
+/** First non-empty key from `keys`, canonical-first. Returns null when none is set. */
+function findThreshold(settings, keys) {
+  for (const key of keys) {
+    const raw = settings[key];
+    if (raw !== undefined && raw !== null && String(raw).trim() !== '') {
+      return { key, raw: String(raw) };
+    }
+  }
+  return null;
+}
+
+/**
+ * Classify a registry cost threshold. Returns a new object, never mutates input:
+ *   { state: 'unset' }                  key absent/empty        -> caller fails OPEN
+ *   { state: 'disabled', key, value:0 } explicit 0              -> caller fails OPEN
+ *   { state: 'armed', key, value }      finite positive USD     -> caller enforces
+ *   { state: 'invalid', key, raw }      unreadable or negative  -> caller fails CLOSED
+ *
+ * parseFloat after stripping a leading `$` and thousands separators — not Number() —
+ * because `= $25.00` and `= 25.00 USD` are shapes a human types into MINDFORGE.md and
+ * both plainly mean 25; Number() would call them invalid and refuse every model call.
+ * Only a value with no leading number at all is invalid. Non-finite is invalid on
+ * purpose: `Infinity` compares false against every projection, i.e. it is not a cap.
+ */
+function classifyThreshold(found) {
+  if (!found) return { state: 'unset' };
+  const value = parseFloat(found.raw.trim());
+  if (!Number.isFinite(value) || value < 0) return { state: 'invalid', key: found.key, raw: found.raw };
+  if (value === 0) return { state: 'disabled', key: found.key, value: 0 };
+  return { state: 'armed', key: found.key, value };
+}
+
+// [COST_WARN_USD] had no reader anywhere in bin/ before COST-02. At most one line per
+// UTC day per threshold, so an armed warning does not append to stderr on every call.
+// Replaced as a whole object rather than mutated in place.
+let _warnState = { day: '', threshold: 0 };
+
+/** Soft threshold. Must never throw — a warning that blocks is a second hard cap. */
+function warnIfCrossed(settings, projected, hardLimit) {
+  const warn = classifyThreshold(findThreshold(settings, WARN_LIMIT_KEYS));
+  if (warn.state !== 'armed') return;
+  // Suppress only when an ARMED hard cap sits at or below the warn value — there the
+  // throw preempts this line anyway. With no hard cap, nothing preempts it, and an
+  // upgraded install without [COST_HARD_LIMIT_USD] is the common case
+  // (installer-core.js:706 never rewrites an existing MINDFORGE.md) — precisely the
+  // install that most needs a spend warning.
+  if (hardLimit !== null && warn.value >= hardLimit) return;
+  if (projected < warn.value) return;
+
+  const today = new Date().toISOString().slice(0, 10);
+  if (_warnState.day === today && _warnState.threshold === warn.value) return;
+  _warnState = { day: today, threshold: warn.value };
+  const cap = hardLimit === null ? 'no hard cap set' : `hard cap ${hardLimit}`;
+  process.stderr.write(
+    `[cost-tracker] Projected daily spend ${projected.toFixed(4)} crossed [${warn.key}] = ${warn.value} (${cap})\n`
+  );
+}
+
 async function preflight(estimatedCost = 0) {
   const settings = require('./model-router').getAllSettings();
-  const hardLimit = parseFloat(settings.MODEL_COST_HARD_LIMIT_USD || '0.0');
-  
-  if (hardLimit <= 0) return;
+  const limit = classifyThreshold(findThreshold(settings, HARD_LIMIT_KEYS));
+
+  // Fail CLOSED on a limit that is present but unreadable: a cap nobody can parse is
+  // not a cap. Not a new surprise either — bin/validate-config.js already rejects this
+  // exact config with exit 1, because COST_HARD_LIMIT_USD is typed "number" at
+  // .mindforge/MINDFORGE-SCHEMA.json:87. The code is distinct from COST_LIMIT_REACHED
+  // so a caller can tell a spend stop from a config fault; bin/models/model-client.js
+  // re-throws both, which is the only reason this throw is not swallowed.
+  if (limit.state === 'invalid') {
+    throw Object.assign(
+      new Error(`[${limit.key}] = "${limit.raw}" is not a USD amount — the daily cost cap cannot be evaluated. Set a number in MINDFORGE.md (0 disables the cap).`),
+      { code: 'COST_LIMIT_MISCONFIGURED', key: limit.key, raw: limit.raw }
+    );
+  }
+
+  // Fail OPEN when the key is absent or explicitly 0. DELIBERATE — do not invert it.
+  // docs/research/2026-08-v12-upgrade-report.md:85 recommends making an unset limit a
+  // config error, but bin/installer-core.js:706 writes MINDFORGE.md only when it does
+  // not already exist, so every install upgraded from a registry predating this key
+  // would start refusing every model call. The shipped schema agrees the key is
+  // optional: it sits in `recommended`, not `required` (.mindforge/MINDFORGE-SCHEMA.json
+  // :13-17), and bin/validate-config.js:48-49 only warns and exits 0 when it is absent.
+  if (limit.state !== 'armed') {
+    // The soft threshold must NOT depend on the hard cap. Guarded on the warn key so
+    // the no-cost-config fast path stays a pure early return and never reads the ledger.
+    if (classifyThreshold(findThreshold(settings, WARN_LIMIT_KEYS)).state === 'armed') {
+      warnIfCrossed(settings, getTodaySpendCached() + estimatedCost, null);
+    }
+    return;
+  }
 
   const todaySpend = getTodaySpendCached();
   const projected = todaySpend + estimatedCost;
 
-  if (projected >= hardLimit) {
+  if (projected >= limit.value) {
     throw Object.assign(
-      new Error(`Daily cost limit $${hardLimit} reached (Today: $${todaySpend.toFixed(4)})`),
-      { code: 'COST_LIMIT_REACHED', spend: todaySpend, limit: hardLimit }
+      new Error(`Daily cost limit $${limit.value} reached (Today: $${todaySpend.toFixed(4)})`),
+      { code: 'COST_LIMIT_REACHED', spend: todaySpend, limit: limit.value }
     );
   }
+
+  warnIfCrossed(settings, projected, limit.value);
 }
 
 async function record(entry) {

package/bin/models/model-client.js

@@ -41,10 +41,15 @@ class ModelClient {
     let modelId = routing.model;
 
     // 2. Pre-flight cost check
+    // Both COST_ codes must propagate. This catch re-threw only COST_LIMIT_REACHED,
+    // so COST-02's fail-closed config fault would have been discarded here and the
+    // call would have proceeded uncapped — an interlock reporting success while doing
+    // nothing. Anything else still falls through on purpose: an unreadable ledger is
+    // a broken meter, and a broken meter must not block work.
     try {
       await CostTracker.preflight(0.05); // Conservative estimate
     } catch (e) {
-      if (e.code === 'COST_LIMIT_REACHED') throw e;
+      if (e.code === 'COST_LIMIT_REACHED' || e.code === 'COST_LIMIT_MISCONFIGURED') throw e;
     }
 
     // 3. Execute with fallbacks

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/mindforge-version.js

@@ -0,0 +1,99 @@
+'use strict';
+/**
+ * Resolve MINDFORGE's own version, from any context it might be running in.
+ *
+ * THE DEFECT THIS REPLACES. Three modules read `require('../../package.json').version`:
+ *
+ *     bin/updater/self-update.js:13         const CURRENT_VERSION = ...
+ *     bin/updater/version-comparator.js:47  User-Agent: `mindforge-cc/${...}`
+ *     bin/wizard/setup-wizard.js:9          const VERSION = ...
+ *
+ * In the repo that path IS MindForge's manifest, so it looks correct. In an INSTALL it is not: the
+ * installer copies bin/updater/ into the consumer's project, where `../../package.json` is the
+ * CONSUMER's manifest. Measured on a clean `--claude --local` into an app at 1.0.0:
+ *
+ *     ../../package.json from bin/updater/ -> <project>/package.json
+ *     its version: 1.0.0          (the consumer app)
+ *     MindForge actual: 11.9.2
+ *
+ * That is not cosmetic. self-update.js:89 classifies the upgrade with
+ * `upgradeType(CURRENT_VERSION, latestVersion)`, so 1.0.0 -> 11.9.x reads as a MAJOR upgrade, and
+ * :133 uses `readHandoffSchemaVersion() || CURRENT_VERSION` as the "from" version driving
+ * migrations. A bogus origin version steers migration behaviour.
+ *
+ * Same family as the auto-runner defect fixed in ed977e9, which passed process.cwd() to a version
+ * check that compares MindForge's own manifests: both mistake "the directory I am running in" for
+ * "the package I am part of".
+ *
+ * HOW IT RESOLVES, in order, with the discriminator that makes it work:
+ *
+ *   1. The nearest ancestor package.json whose `name` is 'mindforge-cc'. The NAME is the whole
+ *      trick — it is what distinguishes MindForge's manifest from a consumer's, which a relative
+ *      path cannot do. Covers the repo, a global npm install, and node_modules layouts.
+ *   2. <cwd>/.mindforge/config.json `.version`. In an install this is written BY the installer and
+ *      carries MindForge's version (measured: 11.9.2 in a project whose app is 1.0.0).
+ *      tests/version-consistency.test.js asserts it equals package.json in the repo, so the two
+ *      sources cannot silently disagree.
+ *   3. <cwd>/node_modules/mindforge-cc/package.json, for a consumer that has the package but no
+ *      .mindforge/ yet.
+ *
+ * It THROWS rather than guessing. A wrong version is worse than an absent one here: it produces a
+ * confident, incorrect upgrade classification instead of an error somebody can act on.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const PACKAGE_NAME = 'mindforge-cc';
+
+function readJson(file) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; }
+}
+
+/** Walk up from `dir` looking for a package.json that belongs to MindForge itself. */
+function findOwnManifest(dir) {
+  let current = path.resolve(dir);
+  // Bounded by the filesystem root; path.dirname('/') === '/' terminates the loop.
+  for (let depth = 0; depth < 40; depth++) {
+    const candidate = path.join(current, 'package.json');
+    const pkg = readJson(candidate);
+    if (pkg && pkg.name === PACKAGE_NAME && pkg.version) {
+      return { version: pkg.version, source: candidate };
+    }
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return null;
+}
+
+/**
+ * @param {{fromDir?: string, cwd?: string}} [opts]
+ *   fromDir - where to start walking for MindForge's own manifest (defaults to this file).
+ *   cwd     - the project root to consult for installed-context sources.
+ * @returns {{version: string, source: string}}
+ * @throws {Error} when no source can establish MindForge's version.
+ */
+function resolveMindforgeVersion(opts = {}) {
+  const fromDir = opts.fromDir || __dirname;
+  const cwd = opts.cwd || process.cwd();
+
+  const own = findOwnManifest(fromDir);
+  if (own) return own;
+
+  const cfgPath = path.join(cwd, '.mindforge', 'config.json');
+  const cfg = readJson(cfgPath);
+  if (cfg && cfg.version) return { version: cfg.version, source: cfgPath };
+
+  const depPath = path.join(cwd, 'node_modules', PACKAGE_NAME, 'package.json');
+  const dep = readJson(depPath);
+  if (dep && dep.version) return { version: dep.version, source: depPath };
+
+  throw new Error(
+    'Cannot determine the MindForge version. Looked for a package.json named ' +
+    `"${PACKAGE_NAME}" above ${fromDir}, then ${path.join(cwd, '.mindforge/config.json')}, then ` +
+    `${depPath}. Refusing to guess: a wrong version produces a confident but incorrect upgrade ` +
+    'classification.');
+}
+
+module.exports = { resolveMindforgeVersion, findOwnManifest, PACKAGE_NAME };

package/bin/utils/redact-secrets.js

@@ -0,0 +1,106 @@
+'use strict';
+/**
+ * Redact credential-shaped substrings from text that is about to be persisted.
+ *
+ * WHY THIS EXISTS. `bin/hooks/instinct-capture-hook.js` writes the first 200 characters of a raw
+ * Bash command — and of a raw Task description — into BOTH an `observation` and a `behavior` field
+ * of `.mindforge/engine/instincts/instinct-store.jsonl`. Measured on real store files left by
+ * probes: an entry whose `observation` begins `Bash command succeeded: AWS_SE...`, i.e. an
+ * `AWS_SECRET_ACCESS_KEY=<value>` assignment captured verbatim. The store path is not gitignored,
+ * `.mindforge/engine/` is inside `package.json` files[] with no negation for instincts, and the
+ * promotion path (`.mindforge/engine/instincts/promotion-engine.md:33,41,46`) copies these fields
+ * into a generated, tracked, PUBLISHED `SKILL.md`. So a captured secret is amplified from a
+ * data file into committed source.
+ *
+ * WHY REDACT RATHER THAN HASH. Measured, not assumed: three consumers read this text and all three
+ * need it readable.
+ *
+ *   bin/learning/instinct-cli.js:114  `list` prints observation AND behavior verbatim to a human
+ *   bin/learning/instinct-cli.js:241  `promote` prints behavior verbatim as the suggestion
+ *   .mindforge/skills/instinct-clustering/SKILL.md:57-63  word-overlap Jaccard on observation
+ *
+ * And nothing in code dedups on the text — `cmdImport` keys on `e.id` and the hook stamps a fresh
+ * randomUUID per event — so a hash would preserve no collision that anything relies on. Hashing
+ * would break three consumers to buy nothing.
+ *
+ * WHY NOT "KEEP argv[0], REDACT THE REST". Because of the env-assignment form: in
+ * `SECRET=value cmd ...` the secret precedes the program, so the first retained token IS the
+ * secret. That is not hypothetical — it is the shape of the measured on-disk entry above.
+ *
+ * FAIL CLOSED. If redaction throws, this returns a placeholder rather than the input. A redactor
+ * that fails open is not a redactor. Note this does NOT make the calling hook fail closed: the hook
+ * stays advisory and still exits 0. "Do not block the tool call" and "do not write the secret
+ * anyway" are different promises, and both are kept.
+ */
+
+const PLACEHOLDER = (kind) => `<redacted:${kind}>`;
+
+/**
+ * Ordered most-specific first. Each entry replaces only the SECRET portion where a prefix carries
+ * meaning worth keeping (a scheme, a key name), so the redacted text still reads as the same shape
+ * of command — which is what the human-facing and Jaccard consumers need.
+ */
+const RULES = [
+  // PEM private key blocks, header through footer.
+  { kind: 'pem', re: /-----BEGIN[^-]{0,40}(?:PRIVATE )?KEY-----[\s\S]*?-----END[^-]{0,40}KEY-----/g,
+    replace: () => PLACEHOLDER('pem') },
+
+  // Vendor tokens with recognisable prefixes. Keep the prefix: it says WHICH credential leaked,
+  // which is exactly what an operator needs in order to rotate the right one.
+  { kind: 'vendor-token',
+    re: /\b(sk-(?:proj-|ant-)?|ghp_|gho_|ghu_|ghs_|ghr_|github_pat_|glpat-|npm_|xox[baprse]-|AKIA|ASIA|AIza|hf_|dop_v1_)[A-Za-z0-9_-]{16,}/g,
+    replace: (m, prefix) => `${prefix}${PLACEHOLDER('token')}` },
+
+  // Authorization headers. Keep the scheme, drop the credential.
+  { kind: 'auth-header', re: /\b(Bearer|Basic|Token)\s+[A-Za-z0-9+/=._~-]{8,}/gi,
+    replace: (m, scheme) => `${scheme} ${PLACEHOLDER('auth')}` },
+
+  // Credentials embedded in a URL: scheme://user:pass@host
+  { kind: 'url-credential', re: /\b([a-z][a-z0-9+.-]*:\/\/[^\s:/@]+):[^\s@/]+@/gi,
+    replace: (m, upToUser) => `${upToUser}:${PLACEHOLDER('url-password')}@` },
+
+  // Environment-assignment form, keyed on the NAME looking secret-bearing. This is the case that
+  // defeats prefix-preserving designs, because the assignment can precede the program name.
+  { kind: 'assignment',
+    re: /\b([A-Za-z_][A-Za-z0-9_]*(?:SECRET|TOKEN|PASSWORD|PASSWD|APIKEY|API_KEY|ACCESS_KEY|PRIVATE_KEY|CREDENTIAL|AUTH)[A-Za-z0-9_]*)\s*=\s*("[^"]*"|'[^']*'|[^\s;|&]+)/gi,
+    replace: (m, name) => `${name}=${PLACEHOLDER('assignment')}` },
+
+  // Flag form: --password X, --token=X, -p X. Keep the flag so the command still parses visually.
+  { kind: 'flag',
+    re: /(--?(?:password|passwd|token|secret|api[-_]?key|access[-_]?key|auth|credential)(?:[=\s]))(?:"[^"]*"|'[^']*'|[^\s;|&]+)/gi,
+    replace: (m, flag) => `${flag}${PLACEHOLDER('flag-value')}` },
+
+  // Generic high-entropy run, last resort for credentials with no recognisable prefix. Requires
+  // BOTH a letter and a digit and >= 28 characters, so English words, long flag names and ordinary
+  // identifiers are left alone. `/` is excluded so a long path is examined segment by segment.
+  { kind: 'opaque', re: /\b(?=[A-Za-z0-9+=_-]{28,}\b)(?=[^\s]*[A-Za-z])(?=[^\s]*\d)[A-Za-z0-9+=_-]{28,}\b/g,
+    replace: () => PLACEHOLDER('opaque') },
+];
+
+/**
+ * @param {string} text
+ * @returns {string} the text with credential-shaped substrings replaced
+ */
+function redactSecrets(text) {
+  if (typeof text !== 'string' || text === '') return text;
+  try {
+    let out = text;
+    for (const rule of RULES) out = out.replace(rule.re, rule.replace);
+    return out;
+  } catch {
+    // Fail closed. Withholding telemetry is always cheaper than persisting a credential.
+    return PLACEHOLDER('redaction-failed');
+  }
+}
+
+/**
+ * True when redactSecrets would change the text. Useful for asserting a fixture is actually
+ * secret-shaped before relying on it, so a test cannot pass because its fixture was inert.
+ * @param {string} text
+ * @returns {boolean}
+ */
+function containsSecretShape(text) {
+  return typeof text === 'string' && text !== '' && redactSecrets(text) !== text;
+}
+
+module.exports = { redactSecrets, containsSecretShape, RULES };