mindforge-cc 11.9.1 → 11.9.3

package/README.md

@@ -6,13 +6,55 @@
 
 ## Latest release
 
-**v11.9.0** (2026-07-27) — Bedrock provider + full dry-run audit. See [CHANGELOG.md](./CHANGELOG.md) for full history, or [RELEASENOTES.md](./RELEASENOTES.md) for human-readable notes.
+**v11.9.2** (2026-08-16) — Correctness: the config gate can now fail, the audit chain no longer
+forks under concurrent writers, trace retrieval works, and the cost ledger has one record shape.
+**Contains a breaking change to the dashboard HTTP surface** (loopback-only) — see the BREAKING
+section in [CHANGELOG.md](./CHANGELOG.md), or [RELEASENOTES.md](./RELEASENOTES.md) for
+human-readable notes.
+
+---
+
+## What is actually enforced
+
+Read this before the install instructions. MindForge ships a large corpus of agent
+instructions — commands, skills, personas, protocols — and those are advisory: they work by
+being in the model's context, and a model can decline them. The parts that would *block* an
+action are hooks, and **no install channel currently registers them.**
+
+| Capability | Plugin channel | `npx` channel |
+|---|---|---|
+| Slash commands | Yes | Yes |
+| Skills / personas / protocol docs | Yes | Yes |
+| Subagents | Yes | Yes |
+| Audit hash-chain (`bin/verify-audit.js`) | Yes | Yes |
+| **Hooks enforced (can block a tool call)** | **No** | **No** |
+
+Why, specifically:
+
+- **No hook configuration ships, and nothing generates one.** `package.json` `files[]` has 48
+  entries and none contains `settings`, so neither `.claude/settings.json` nor
+  `.agent/settings.json` is published. All references to those paths in `bin/` are reads or
+  metadata strings — there is no code that writes or merges one. `bin/harness-audit.js:335`
+  even offers "wire trust-gate + block-no-verify into both …" as a *fix suggestion*, auditing a
+  wiring nothing creates.
+- **The plugin channel's hooks additionally crash when fired.**
+  `plugins/mindforge/scripts/run-with-flags.js:24` requires `./lib/hook-flags`, and
+  `plugins/mindforge/scripts/lib/` does not exist in the published plugin. Running the
+  dispatcher gives `Error: Cannot find module './lib/hook-flags'` and exit 1. The module it
+  needs does exist at `.agent/hooks/lib/hook-flags.js`; it was never copied in.
+
+So treat MindForge as **governance-by-convention plus a tamper-evident audit log**, not as a
+policy enforcement point. Installing it also expands your repository's trust boundary by a large
+volume of agent instructions — review what you install. Making hook registration real per
+harness is the headline goal of v12; the audit chain is genuinely verifiable today
+(`node bin/verify-audit.js`).
 
 ---
 
 ## Install
 
-Fastest path — Claude Code plugin marketplace (no project files written):
+Claude Code plugin marketplace (no project files written). **Note:** the plugin's hooks do not
+fire — see *What is actually enforced* above. Slash commands, skills and subagents do work.
 
 ```bash
 /plugin marketplace add sairam0424/MindForge
@@ -27,6 +69,13 @@ npx mindforge-cc@latest --claude --local
 
 All install channels (global, local, Antigravity, Cursor, Copilot, Gemini CLI, MCP server, combined runtimes, `--minimal`): see [docs/getting-started.md](docs/getting-started.md).
 
+**Upgrading from 11.9.x?** The installer does not overwrite an existing
+`.mindforge/MINDFORGE-SCHEMA.json`, so 11.9.2's armed config validator keeps the older
+permissive schema on a plain upgrade. Run with `--force` if you want the stricter gate. The
+daily cost cap declared as `[COST_HARD_LIMIT_USD]` in `MINDFORGE.md` was **not enforced** in
+11.9.2; 11.9.3 arms it. An upgrade never rewrites an existing `MINDFORGE.md`, so if yours
+predates the key the cap stays off — add `[COST_HARD_LIMIT_USD] = 25.00` to turn it on.
+
 ---
 
 ## Verify

package/RELEASENOTES.md

@@ -1,5 +1,58 @@
 # Release Notes
 
+## v11.9.2 — 2026-08-16 — Correctness: config gate, audit chain, retrieval, cost ledger
+
+### What's New
+Nothing. This is a correctness release: four things that were reported as working were measured
+and found not to be, and a fifth — the plugin channel's hooks — is now documented as broken
+instead of advertised as the fastest path.
+
+### ⚠️ Breaking (under a patch bump)
+The dashboard's HTTP surface changed shape. `detail` is gone from 5 endpoints and raw errno
+strings from 10 more; `correlation_id` is added to 15; malformed bodies now return
+`application/json` instead of an HTML error page. Those fields were leaking absolute filesystem
+paths — and so the operator's username and home directory — into an unauthenticated response.
+The dashboard also now **exits** on an unhandled rejection or uncaught exception where 11.9.1
+logged and continued, so supervised deployments will see restarts instead of silent errors.
+The surface is loopback-only, so this affects you only if you script against it.
+
+### Fixes
+- **`security-scan` could not fail.** It reported `MINDFORGE.md valid — 0 settings configured`
+  and exited 0 on every input, because both config parsers used a plain `KEY=value` regex while
+  the registry declares bracketed `[KEY] = value`. All 43 parameters were invisible. One shared
+  parser now reads both forms, and the schema has real `required` keys. Three CI gates go from
+  unfailable to failable — on fresh installs and `--force` reinstalls; a plain upgrade keeps
+  your existing schema.
+- **The audit hash chain forked under concurrent writers.** No `.jsonl` append took a lock, and
+  the chain head was cached in-process and never invalidated — so a second process's append made
+  the first keep chaining from a superseded hash. Both halves are fixed: a fail-closed lock, and
+  a cached head that carries the file size witnessing it is still the tail. A lock alone was
+  measured insufficient. 8 concurrent appenders went from 199 broken links to 0.
+- **44.4% of trace content was unsearchable and every multi-word query returned nothing.** The
+  index was keyed on `trace_id` rather than the row's primary key, so each span evicted the
+  previous one; and whole queries were wrapped as a single FTS phrase, so one absent term zeroed
+  the result. 2,270 of 5,117 rows are recovered losslessly and queries are now tokenised and
+  ranked. The shipped retrieval eval had zero callers and now runs as `npm run eval:retrieval`.
+- **The cost ledger reported two different totals for one concept** ($13.73 vs $0.00) because
+  writer and reader used different field names — and the test wrote the reader's name, so the
+  mismatch passed. One record shape now, and the configured ledger path no longer points at a
+  file that never existed.
+- **The daily cost cap is declared but not enforced**, and is now labelled that way in
+  `MINDFORGE.md` and the schema rather than described as non-overridable. Wiring it is COST-02.
+
+### Honesty
+`README.md` now carries a per-channel capability table with an explicit **Hooks enforced: No**
+row for both install channels, because no hook configuration ships and nothing generates one.
+The plugin channel's dispatcher additionally fails with `Cannot find module './lib/hook-flags'`
+on every fire. Treat MindForge as governance-by-convention plus a verifiable audit log, not as a
+policy enforcement point. Making enforcement real per harness is the goal of v12.
+
+### Stats
+105 test files, 103 pass, 2 environment-dependent skips. Four suites that could not report
+failure now can. Audit chain verifies clean. Tarball 1,973 entries.
+
+---
+
 ## v11.9.0 — 2026-07-27 — Bedrock Provider + Full Dry-Run Audit
 
 ### What's New
@@ -569,7 +622,7 @@ You must address these before upgrading from v9.x:
 |--------|--------|-----------|
 | `better-sqlite3` removed, replaced by `sql.js` | If you imported or extended VectorHub internals, the constructor API has changed | Use `createVectorHub()` factory function instead of `new VectorHub()` |
 | VectorHub uses FTS4 (not FTS5) | FTS5-specific syntax (e.g., `BM25`) no longer available | Use standard FTS4 `MATCH` queries; ranking is handled internally |
-| SDK `memory.ts` rewritten | If you imported memory utilities from `../../bin/` paths, those imports no longer resolve | Import from `@mindforge/sdk` directly — all public APIs are re-exported |
+| SDK `memory.ts` rewritten | If you imported memory utilities from `../../bin/` paths, those imports no longer resolve | Import from `mindforge-sdk` directly — all public APIs are re-exported |
 | Dashboard endpoints require auth | Unauthenticated requests to `/api/steering`, `/api/approve`, and SSE mutators now return 401 | Set `MINDFORGE_DASHBOARD_TOKEN` env var; pass as `Authorization: Bearer <token>` |
 | `sync-jira` / `sync-confluence` CLI routes removed | These were stubs with no implementation | Remove any scripts that invoke these commands |
 | Prompt injection blocklist removed | The regex-based `BLOCKED_PATTERNS` array no longer exists | Use the structured action allowlist in `bin/governance/action-allowlist.js` |
@@ -661,7 +714,7 @@ The database file format is compatible. No data migration is required.
 import { MemoryStore } from '../../bin/memory/store';
 
 // After (v10) — public SDK exports
-import { MemoryStore } from '@mindforge/sdk';
+import { MemoryStore } from 'mindforge-sdk';
 ```
 
 ### Step 5: Remove references to deleted commands

package/SECURITY.md

@@ -1,6 +1,6 @@
 # Security Policy
 
-> **Current version:** 11.9.0 | **npm audit:** 0 vulnerabilities across root, sdk, mcp-server
+> **Current version:** 11.9.3 | **npm audit:** 0 vulnerabilities across root, sdk, mcp-server
 
 ## Supported Versions
 
@@ -66,7 +66,9 @@ We follow responsible disclosure practices. We will credit reporters in the rele
 
 ### Audit & Integrity
 
-- **Merkle-chain audit log** — Every entry in `AUDIT.jsonl` includes a SHA-256 hash of the previous entry. Tampering with any historical entry breaks the chain, making modifications detectable.
+- **Hash-chained audit log (SHA-256 back-links)** — Every entry in `AUDIT.jsonl` carries the SHA-256
+  hash of the previous entry. Not a Merkle tree: there is no hash tree and no inclusion proof, so
+  "Merkle" was the wrong word for it. What it detects, and does not, is measured below.
 - **AuditWriter with buffered writes** — Atomic append operations prevent partial writes from corrupting the log.
 - **Log rotation with archival** — AUDIT.jsonl auto-archives beyond 5000 lines with gzip compression, preventing unbounded disk growth.
 - **npm provenance** — Published packages include SLSA Build Level 2 attestation via `--provenance`, proving the package was built from the stated source commit in CI.
@@ -143,7 +145,24 @@ For security questions that are not vulnerability reports, open a GitHub Discuss
 Tier-3 trust in v11.x uses **in-process key simulation** (`bin/governance/ztai-manager.js` `SecureEnclaveProvider`). Key material resides in the Node.js heap — it is NOT hardware-isolated. A real TPM/HSM provider is planned for v12.x. **Do not use Tier-3 trust for production credential workflows in v11.x.**
 
 ## Audit Log Tamper Evidence
-The Merkle chain (`bin/governance/audit-hash.js`) provides tamper-evidence for content and ordering but does not prevent replay of identical entries. Restrict OS-level write access to `.planning/AUDIT.jsonl` to prevent replay attacks.
+The hash chain (`bin/governance/audit-hash.js`) is real and independently verifiable — `node
+bin/verify-audit.js` recomputes it and exits 1 on a break. Measured on a 200-entry chain taken from
+the head of a live log:
+
+| Attack | Detected? | Evidence |
+|---|---|---|
+| Mutate a middle entry | **YES** | `BROKEN at entry 79: hash mismatch (entry mutated)`, exit 1 |
+| Delete a middle entry | **YES** | `BROKEN at entry 79: previous_hash mismatch`, exit 1 |
+| **Truncate the tail** | **NO** | 40 entries removed from the end → `audit chain valid: 160 entries`, **exit 0** |
+| Replay identical entries | **NO** | the chain constrains content and ordering, not multiplicity |
+
+The truncation gap is inherent to a bare hash chain: each entry commits to its predecessor, so a
+prefix of a valid chain is itself a valid chain. Closing it needs a commitment to LENGTH — an external
+anchor, a signed length attestation, or a witnessed head — none of which ships today.
+
+So the accurate claim is **"detects mutation and mid-file deletion"**, not "immutable" or
+"non-repudiable". Restrict OS-level write access to `.planning/AUDIT.jsonl`; the chain does not
+substitute for filesystem permissions.
 
 ## Agent Dispatch (spawn mode)
 `bin/spawn-agent.js` spawn mode exits with an error in v11.x — real agent dispatch is not yet implemented at the shell level. Use Claude Code slash commands (`/mindforge:auto`, `/mindforge:next`) to dispatch agents.

package/bin/autonomous/audit-writer.js

@@ -20,6 +20,7 @@ const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
 const { hashAuditEntry } = require('../governance/audit-hash');
+const { withFileLock } = require('../utils/file-lock');
 
 /**
  * Computes the SHA-256 hash of an entry chained to its predecessor (UC-04).
@@ -57,19 +58,20 @@ function readLastHash(auditPath) {
 // sync write gives in-process consumers (e.g. StuckMonitor, which is fed the event
 // object directly but may also re-read the file) immediate, durable data.
 //
-// Chain head caching: re-reading the file's tail on every append is O(file) — bad
-// on hot paths. Instead we keep a per-path in-memory lastHash (Map keyed by the
-// RESOLVED absolute path), seeded ONCE from the file's last entry on the first
-// append, then advanced in-process for O(1) appends. If the cache is cold (new
-// process, or a path never written in this process) we seed from disk — so a
-// second process correctly continues the on-disk chain from its tail.
+// Chain head caching: re-reading the file's tail on every append is O(file) — bad on
+// hot paths. We keep a per-path in-memory head (Map keyed by the RESOLVED absolute
+// path) as { hash, size }, where `size` is the file size immediately after our own
+// write. The size is the WITNESS that the cache is still the true tail: if the file is
+// still exactly that long, nobody else appended and the cached hash is the tail (O(1));
+// if it differs, another process appended and we MUST re-seed from disk.
 //
-// Concurrency: within a process this is fully synchronous, so calls cannot
-// interleave and the cached lastHash is always current. ACROSS processes, each
-// process seeds from the file tail on its first append; this is correct only under
-// the single-operator model (no two processes appending CONCURRENTLY to the same
-// audit file). MindForge runs one autonomous operator at a time, so this holds.
-const _lastHashCache = new Map(); // resolvedPath -> last `_hash` written/seen
+// Concurrency (LOCK-01): the seed-through-write sequence below runs inside
+// withFileLock, so no other process can read the head, or append, while we hold it.
+// The size check is what makes the cache safe across processes — a lock alone is NOT
+// enough, because a warm cache would still hand back a hash that a lock-respecting
+// second writer has since superseded, forking the chain. Verified: lock-only leaves
+// 4-6 link breaks per 8-process run; lock + size-validated reseed leaves 0.
+const _lastHashCache = new Map(); // resolvedPath -> { hash, size }
 
 /**
  * Synchronously appends ONE hash-chained, durable entry to an audit JSONL file.
@@ -96,30 +98,43 @@ function appendAuditEntrySync(auditPath, event) {
     timestamp: event.timestamp || new Date().toISOString(),
   };
 
-  // 2. Seed previous_hash: prefer the warm in-process cache; fall back to the
-  //    file's last entry when cold (first append in this process for this path).
-  let previous_hash = _lastHashCache.has(resolved)
-    ? _lastHashCache.get(resolved)
-    : readLastHash(resolved);
+  // 2-5. LOCK-01: seed-through-write is ONE critical section. The lock opens BEFORE
+  //      the head is read and closes AFTER the fsync, so no other process can read the
+  //      same head, or interleave an append, while we hold it. maxTries is raised above
+  //      the module default because failing closed here DROPS an audit entry: at 16
+  //      concurrent writers the default ~1s ceiling loses ~35% of entries, 150 tries
+  //      loses none.
+  return withFileLock(resolved, () => {
+    // 2. Seed previous_hash from the warm cache ONLY if the file is still exactly as
+    //    long as we left it (proof nobody else appended); otherwise re-seed from disk.
+    const cached = _lastHashCache.get(resolved);
+    let onDiskSize = -1;
+    try { onDiskSize = fs.statSync(resolved).size; } catch { onDiskSize = -1; }
+    const previous_hash = (cached && cached.size === onDiskSize)
+      ? cached.hash
+      : readLastHash(resolved);
 
-  // 3. Compute _hash over {...stamped, previous_hash} WITHOUT _hash in the material.
-  const _hash = hashEntry(stamped, previous_hash);
+    // 3. Compute _hash over {...stamped, previous_hash} WITHOUT _hash in the material.
+    const _hash = hashEntry(stamped, previous_hash);
 
-  // 4. Write {...stamped, previous_hash, _hash} as one JSON line, durably+synchronously
-  //    (openSync('a') + writeSync + fsyncSync + closeSync — mirrors appendDurableSync).
-  const chained = { ...stamped, previous_hash, _hash };
-  fs.mkdirSync(path.dirname(resolved), { recursive: true });
-  const fd = fs.openSync(resolved, 'a');
-  try {
-    fs.writeSync(fd, JSON.stringify(chained) + '\n');
-    fs.fsyncSync(fd);
-  } finally {
-    fs.closeSync(fd);
-  }
+    // 4. Write {...stamped, previous_hash, _hash} as one JSON line, durably+synchronously
+    //    (openSync('a') + writeSync + fsyncSync + closeSync — mirrors appendDurableSync).
+    const chained = { ...stamped, previous_hash, _hash };
+    fs.mkdirSync(path.dirname(resolved), { recursive: true });
+    const fd = fs.openSync(resolved, 'a');
+    let sizeAfter = -1;
+    try {
+      fs.writeSync(fd, JSON.stringify(chained) + '\n');
+      fs.fsyncSync(fd);
+      sizeAfter = fs.fstatSync(fd).size;   // exact new length, one syscall, fd already open
+    } finally {
+      fs.closeSync(fd);
+    }
 
-  // 5. Advance the in-process chain head and return the written entry.
-  _lastHashCache.set(resolved, _hash);
-  return chained;
+    // 5. Advance the in-process chain head (hash + its witness) and return the entry.
+    _lastHashCache.set(resolved, { hash: _hash, size: sizeAfter });
+    return chained;
+  }, { maxTries: 150, label: 'audit' });
 }
 
 module.exports = { appendAuditEntrySync };

package/bin/autonomous/auto-runner.js

@@ -117,6 +117,12 @@ class AutoRunner {
     this.phase = String(options.phase);
     this.isHeadless = options.headless || false;
     this.isPaused = false;
+    // Optional async function(task) that performs the actual work for one task. When absent,
+    // executeWave() aborts the wave rather than writing task_completed entries for work that would
+    // not run — see the comment there. Deliberately NOT defaulted to a no-op: bin/autonomous/
+    // wave-executor.js:133 defaults its own `executor` to `async () => {}`, and a silent no-op
+    // default is exactly how a wave came to report every task fulfilled while dispatching nothing.
+    this.taskExecutor = typeof options.taskExecutor === 'function' ? options.taskExecutor : null;
 
     // Paths
     const planningDir = path.join(process.cwd(), '.planning');
@@ -306,10 +312,30 @@ class AutoRunner {
   runPreFlight() {
     console.log('🔍 Running pre-flight checks...');
 
-    // UC-01: fail closed on version drift before any wave executes
+    // UC-01: fail closed on version drift before any wave executes.
+    //
+    // The root MUST be MindForge's own install root, NOT process.cwd(). This check compares
+    // package.json against .mindforge/config.json, sdk/package.json and MINDFORGE.md — all
+    // MindForge's own manifests. Pointed at a consumer's cwd it takes THEIR application
+    // version as canonical and reports MindForge's own config as drift. Measured, with an app
+    // at 1.0.0 and MindForge at 11.9.2:
+    //   [".mindforge/config.json declares 11.9.2 but canonical (package.json) is 1.0.0"]
+    // and a consumer with no package.json at all fails closed on a missing canonical. Only a
+    // project whose app version coincidentally equalled MindForge's would have passed.
+    //
+    // This has never fired in a shipped build, because nothing constructs AutoRunner today
+    // (verified: no `new AutoRunner` anywhere in bin/; the only requirer is
+    // tests/wave-timeout-rollback.test.js, for the pure helpers). It is a landmine that arms
+    // the moment the runner is wired — which DEL-02 proposes doing — so it is disarmed here
+    // rather than left for whoever wires it to find in the field.
+    //
+    // __dirname/../.. is MindForge's root in both layouts: <repo> from a checkout, and
+    // <project>/node_modules/mindforge-cc when installed. In the installed shape
+    // .mindforge/config.json is absent (the installer writes that into the CONSUMER project),
+    // which reads as null and is SKIPPED rather than counted as drift — verified.
     try {
       const { assertVersionConsistency } = require('../utils/version-check');
-      assertVersionConsistency(process.cwd());
+      assertVersionConsistency(path.resolve(__dirname, '..', '..'));
     } catch (e) {
       throw new Error(`[pre-flight] ${e.message}`);
     }
@@ -357,6 +383,40 @@ class AutoRunner {
 
     console.log(`\n⚡ Wave ${waveNum}/${this.waves.length}: ${pending.length} tasks (concurrency: ${maxConcurrency})`);
     if (idcStatus.action === 'UPGRADE_MIR') console.log(`  [IDC-ACTIVE] MIR Override: ${idcStatus.new_mir}`);
+
+    // REFUSE TO FABRICATE. The task body below used to be, in full:
+    //
+    //     try {
+    //       this.writeAudit({ event: 'task_started',   ... });
+    //       this.writeAudit({ event: 'task_completed', ... duration_ms: Date.now() - taskStart });
+    //       this.completedTasks.add(task.id);
+    //
+    // Nothing between the two writes. No dispatch. So every task was recorded as completed with a
+    // duration of ~0ms, the catch block was unreachable because nothing could throw, and the
+    // hash-chained audit log — the one component of this project that is genuinely production-grade
+    // and independently verifiable — became a tamper-evident record of statements that were false.
+    // A verifiable false record is worse than no record: it survives verify-audit and carries the
+    // authority of the chain.
+    //
+    // Measured before this change: task_completed = 0 in the live 3056-entry chain, and no module
+    // under bin/ requires auto-runner (every repo-wide match is a comment, a test, or an
+    // "extracted from" note). So the defect was LATENT — the code would have lied the first time
+    // anything invoked it, and nothing had. That is why this is a refusal rather than a cleanup:
+    // there is no contamination to repair, only a trap to disarm.
+    //
+    // A wave with no executor now writes ONE honest entry and throws, instead of N false ones.
+    if (typeof this.taskExecutor !== 'function') {
+      this.writeAudit({
+        event: 'wave_aborted', phase: this.phase, wave: waveNum, task_count: pending.length,
+        reason: 'no task executor is wired, so no task can run. Refusing to write task_completed '
+          + 'entries for work that would not be performed — see auto-runner.executeWave.',
+      });
+      throw new Error(
+        `Wave ${waveNum} cannot execute: no task executor wired. Pass { taskExecutor } to the `
+        + 'AutoRunner constructor, or drive waves through bin/autonomous/wave-executor.js. '
+        + 'Refusing to record completions for work that would not run.');
+    }
+
     this.writeAudit({ event: 'wave_started', phase: this.phase, wave: waveNum, task_count: pending.length });
 
     const semaphore = new Semaphore(maxConcurrency);
@@ -368,6 +428,9 @@ class AutoRunner {
         console.log(`  → Task: ${task.name || task.id}`);
         try {
           this.writeAudit({ event: 'task_started', phase: this.phase, wave: waveNum, task_id: task.id, task_name: task.name || task.id });
+          // The dispatch that was missing. Its absence is what made the catch below unreachable and
+          // every duration_ms ~0; task_completed is now written only after real work returns.
+          await this.taskExecutor(task);
           this.writeAudit({ event: 'task_completed', phase: this.phase, wave: waveNum, task_id: task.id, task_name: task.name || task.id, duration_ms: Date.now() - taskStart });
           this.completedTasks.add(task.id);
           return { taskId: task.id, status: 'fulfilled' };

package/bin/change-classifier.js

@@ -9,16 +9,55 @@
 const { execSync, execFileSync } = require('child_process');
 const fs = require('fs');
 
+// Matched with String.prototype.startsWith against repo-relative diff paths.
+//
+// Two groups, because this file SHIPS (package.json files[] includes bin/) and therefore runs
+// against two different trees:
+//
+//   (a) CONSUMER paths — a project that installed MindForge. Measured against MindForge's own
+//       tree these match ZERO tracked files, which is correct: they describe the consumer's
+//       layout, not the framework's. Do not remove them.
+//   (b) FRAMEWORK paths — MindForge's OWN trust surface, which control-plane.yml classifies on
+//       every push and PR to this repo. These were absent, so the detector protected the five
+//       markdown files under .mindforge/governance/ while leaving the 15 executable modules
+//       under bin/governance/ — the audit hasher, the verifier, RBAC, the policy engine and
+//       approve.js itself — unclassified. Editing the prose ABOUT governance tripped Tier 3;
+//       editing the code that enforces it did not.
 const SENSITIVE_PATHS = [
+  // (a) consumer-project layout
   'auth/',
   'payment/',
   'security/',
+  // (b) MindForge's own trust surface
+  'bin/governance/',        // audit-hash, audit-verifier, rbac, policy-engine, approve
+  'bin/security/',          // trust-gate-hook and friends — NOT matched by 'security/'
+  'bin/hooks/',             // instinct-capture-hook, context-monitor
+  'bin/models/',
+  '.agent/hooks/',          // the hook dispatcher the installer copies
+  '.claude/settings.json',  // hook registration
+  '.agent/settings.json',
+  '.planning/approvals/',   // the approval records themselves
   '.github/workflows/',
-  '.mindforge/governance/',
-  'bin/models/'
+  '.mindforge/governance/'
 ];
 
+// Scanned against the DIFF CONTENT, so security-critical code in an innocuously-named file still
+// reaches Tier 3 — that is the stated purpose of "Signal B" in
+// .mindforge/governance/change-classifier.md.
+//
+// The doc lists 19 patterns; measured, only 6 of them were detected. The second group below was
+// specified and absent: argon2 (a password hasher), the jose signing pair, paypal.,
+// createCipheriv/createDecipheriv and crypto.subtle (cipher construction), encrypt(/decrypt(,
+// role.*permission and hasPermission (authorization), and SET ROLE / GRANT (SQL privilege
+// changes). tests/governance.test.js pins every documented pattern against the live set, so the
+// doc and this array cannot drift apart again.
+//
+// Adding them cost nothing measurable: over the last 40 commits they caught ZERO additional
+// changes, because anything they would flag was already Tier 3 by path or by one of the broad
+// substring patterns above. So this closes a documented gap without moving the Tier-3 rate, which
+// sat at 50% (path OR pattern) before and after.
 const SENSITIVE_PATTERNS = [
+  // broad substring signals
   /jwt/i,
   /bcrypt/i,
   /stripe/i,
@@ -26,18 +65,89 @@ const SENSITIVE_PATTERNS = [
   /password/i,
   /secret/i,
   /token/i,
-  /PII/
+  /PII/,
+  // the specified-but-missing set
+  /argon2/i,
+  /jose\.(sign|verify)/i,
+  /paypal\./i,
+  /createCipheriv/,
+  /createDecipheriv/,
+  /crypto\.subtle/,
+  /\bencrypt\(/,
+  /\bdecrypt\(/,
+  /role.*permission/i,
+  /hasPermission/,
+  /\bSET ROLE\b/i,
+  /\bGRANT\b/
 ];
 
+/** True if `rev` resolves to an object in this clone (false on a shallow/partial fetch). */
+function revExists(rev) {
+  try {
+    execFileSync('git', ['rev-parse', '--verify', '--quiet', `${rev}^{commit}`], { stdio: 'pipe' });
+    return true;
+  } catch { return false; }
+}
+
+/** The pre-push tip GitHub reports for a push event, or '' if unavailable. */
+function pushBefore() {
+  if (process.env.MINDFORGE_PUSH_BEFORE) return process.env.MINDFORGE_PUSH_BEFORE;
+  // Read the event payload rather than requiring the workflow to thread a variable through.
+  // A fix that depends on someone remembering `env: BEFORE: ${{ github.event.before }}` is a
+  // fix that silently reverts the first time a workflow is copied.
+  const p = process.env.GITHUB_EVENT_PATH;
+  if (!p || !fs.existsSync(p)) return '';
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')).before || ''; } catch { return ''; }
+}
+
+/**
+ * Resolve the commit range to classify.
+ *
+ * A push is a RANGE, not a commit. The old code used HEAD~1..HEAD whenever GITHUB_BASE_REF was
+ * unset, so on a push it inspected only the tip. Measured: two commits where the first adds
+ * auth/login.js with a hardcoded password and the second is docs-only classify as TIER=1 on a
+ * push and TIER=3 as a PR — the sensitive file rides in completely unclassified. control-plane.yml
+ * triggers on `push: [main, develop]`, and this repo has allow_rebase_merge enabled, so the
+ * multi-commit push is the normal case, not an edge case.
+ *
+ * @returns {{range:string, how:string}}
+ * @throws {Error} with .failClosed when a CI push range cannot be resolved.
+ */
+function resolveRange() {
+  // Pull request: three-dot diffs against the MERGE-BASE, so a branch that is merely behind
+  // its base does not pick up base-only changes. (Two-dot here caused Tier-3 false positives.)
+  if (process.env.GITHUB_BASE_REF) {
+    return { range: `origin/${process.env.GITHUB_BASE_REF}...HEAD`, how: 'pull_request' };
+  }
+
+  const inCiPush = process.env.GITHUB_EVENT_NAME === 'push';
+  if (inCiPush) {
+    const before = pushBefore();
+    const isBranchCreation = /^0{40}$/.test(before);
+    if (before && !isBranchCreation && revExists(before)) {
+      return { range: `${before}..HEAD`, how: 'push' };
+    }
+    // Fail CLOSED. Every remaining case genuinely cannot be scoped: a new branch has no prior
+    // tip, and a shallow clone cannot reach `before`. Falling back to HEAD~1 here is what let
+    // a sensitive commit ride in behind a benign tip.
+    const why = isBranchCreation ? 'branch creation (before is all-zeros)'
+      : !before ? 'no `before` in the push event payload'
+        : `\`before\` (${before.slice(0, 12)}) is not present in this clone — shallow fetch?`;
+    const err = new Error(`cannot scope the push range: ${why}`);
+    err.failClosed = true;
+    throw err;
+  }
+
+  // Local invocation (`mindforge classify`). HEAD~1..HEAD is a developer convenience, not a
+  // gate, and must never be reached in CI — the branch above owns every CI push.
+  return { range: 'HEAD~1..HEAD', how: 'local' };
+}
+
 function classify() {
   try {
-    // Get list of changed files compared to origin/<base> or HEAD~1.
-    // Three-dot (...) diffs against the MERGE-BASE, so on a PR branch that is behind its base
-    // we see ONLY this branch's own changes — not unrelated commits already on the base.
-    // (Two-dot here caused Tier-3 false positives by pulling in base-only changes.)
-    const base = process.env.GITHUB_BASE_REF ? `origin/${process.env.GITHUB_BASE_REF}` : 'HEAD~1';
-    const range = process.env.GITHUB_BASE_REF ? `${base}...HEAD` : `${base}..HEAD`;
+    const { range, how } = resolveRange();
     const diffFiles = execFileSync('git', ['diff', '--name-only', range], { encoding: 'utf8' }).split('\n').filter(Boolean);
+    if (process.env.MINDFORGE_CLASSIFY_DEBUG) console.error(`[classify] ${how}: ${range} (${diffFiles.length} file(s))`);
 
     // Test and documentation files are excluded from the sensitive-PATTERN scan below: a test
     // asserting on "password"/key patterns, or a doc mentioning secrets, is not a sensitive
@@ -50,10 +160,16 @@ function classify() {
     let reasons = [];
 
     // 1. Path-based detection (Tier 3)
-    const matchedPath = diffFiles.find(file => SENSITIVE_PATHS.some(p => file.startsWith(p)));
-    if (matchedPath) {
+    // Reports EVERY matched path, not just the first. `find` short-circuited, so a change
+    // touching both .github/workflows/ and bin/governance/ was attributed only to the workflow —
+    // which made the CI log unable to show that the newly-added framework paths were doing any
+    // work, and hid the more interesting of the two matches from the reviewer.
+    const matchedPaths = diffFiles.filter(file => SENSITIVE_PATHS.some(p => file.startsWith(p)));
+    if (matchedPaths.length) {
       tier = 3;
-      reasons.push(`Sensitive path modified: ${matchedPath}`);
+      const shown = matchedPaths.slice(0, 5).join(', ');
+      const more = matchedPaths.length > 5 ? ` (+${matchedPaths.length - 5} more)` : '';
+      reasons.push(`Sensitive path${matchedPaths.length > 1 ? 's' : ''} modified: ${shown}${more}`);
     }
 
     // 2. Pattern-based detection in diff (Tier 3) — non-test/doc files only
@@ -94,13 +210,32 @@ function classify() {
 
     return tier;
   } catch (err) {
-    console.error(`❌ Classification failed: ${err.message}`);
-    // Default to Tier 3 for safety if classification fails
+    // Fail closed: an unscopeable change is treated as maximum risk. Emit the SAME
+    // TIER=/REASONS= lines as the success path so every consumer — the workflow's stdout
+    // parsing, GITHUB_OUTPUT, and a human reading the log — sees tier 3 rather than nothing.
+    // Previously only GITHUB_OUTPUT was written, so anything reading stdout saw no tier at all.
+    const reason = err.failClosed
+      ? `Fail-closed: ${err.message}`
+      : `Fail-closed: classification error — ${err.message}`;
+    console.log('TIER=3');
+    console.log(`REASONS=${reason}`);
+    console.error(`❌ Classification could not be scoped — defaulting to Tier 3. ${err.message}`);
+    if (process.env.GITHUB_ACTIONS) {
+      console.error(`::error title=Change classification failed closed::${reason}`);
+    }
     if (process.env.GITHUB_OUTPUT) {
       fs.appendFileSync(process.env.GITHUB_OUTPUT, 'tier=3\n');
     }
-    process.exit(0); // Don't fail the pipeline yet, let the gate handle it
+    // Exit 0 deliberately: this step's contract is to REPORT a tier, and the downstream gate
+    // is what blocks. Exiting non-zero here would fail the job before the gate can annotate
+    // why. That contract is only honest while a gate actually consumes tier 3 — see
+    // tests/change-classifier.test.js, which pins that the tier-3 consumer exists.
+    return 3;
   }
 }
 
-classify();
+module.exports = { classify, resolveRange, revExists, pushBefore, SENSITIVE_PATHS, SENSITIVE_PATTERNS };
+
+// Behind a require.main guard so tests can import the pure pieces without triggering a run.
+// bin/mindforge-cli.js:51 spawns this file as a script, which still executes normally.
+if (require.main === module) classify();