mindforge-cc 11.9.2 → 11.9.4

package/.agent/CLAUDE.md

@@ -25,25 +25,37 @@ You are a **Dynamic Multi-Agent Swarm (Agentic Mesh)**. Your mission is to execu
 
 ## 🛠️ CORE PROTOCOLS (The "How")
 
+> **These are protocols you follow, not modules you call.** `SwarmController`, `PersonaFactory`
+> and `WaveExecutor` are role names in the specs under `.mindforge/engine/`, not importable code —
+> there is no file by any of those names. Every step below is something you do by reasoning and by
+> using your own tools. Where a real executable exists, it is named with its path.
+
 ### 1. Swarm Dynamic Orchestration (V4)
 **IF** task complexity/impact is high **OR** cross-disciplinary logic is required:
-1.  Invoke `SwarmController` and activate `mindforge-swarm-execution`.
+1.  Adopt the swarm-orchestration protocol described in `.mindforge/engine/`.
 2.  Spawn task-specific ephemeral specialist cluster (AIEngineering, Security, etc.).
-3.  Inject knowledge patches via `PersonaFactory` (Context7).
-4.  Execute parallel mesh waves via `WaveExecutor` guided by `mindforge-parallel-mesh_extended`.
+3.  Load the relevant persona brief from `.mindforge/personas/` before each specialist acts.
+4.  Execute parallel mesh waves, consolidating dependent work before independent work.
 5.  Consolidate mesh findings into a single `SWARM-SUMMARY`.
 
 ### 2. The Sharded Memory Loop (SRD)
 **IF** context ≥ 70% **OR** starting a new task:
-1. Initialize `shard-controller.js`.
-2. Rotate context per the Tri-Tier strategy (Hot/Warm/Cold).
-3. Inject only sharded relevant data into the active buffer.
+1. Rotate context per the Tri-Tier strategy (Hot/Warm/Cold) yourself — this is an advisory
+   discipline, not an automated step.
+2. Inject only sharded relevant data into the active buffer.
+3. Re-read the current phase's plan rather than carrying stale detail forward.
 
 ### 3. The Adversarial Decision Loop (ADS)
 **BEFORE** committing any architectural change:
-1. Spawn Red-Team/Blue-Team debate contexts.
-2. Run `soul-engine.js` on the proposed diff.
-3. **STOP** if SOUL Score < `[MIN_SOUL_SCORE]` from MINDFORGE.md.
+1. Spawn Red-Team/Blue-Team debate contexts and argue the change against itself.
+2. Score the proposal on impact, leverage, reversibility, effort, risk and cost.
+3. **STOP** if the resulting SOUL Score < `[MIN_SOUL_SCORE]` from MINDFORGE.md.
+
+ADS is a reasoning protocol you run, not a command. Do not look for a script: measured, the two
+scripts this section used to name (soul-engine.js and shard-controller.js) do not exist
+anywhere in the package. The nearest real implementation, `runADSSynthesis()` in
+`bin/review/ads-engine.js`, is a library with a single internal caller, exposes no CLI, and takes
+`{phaseNum, goal, context, sessionId}` rather than a diff, so it cannot be invoked here either.
 
 ### 4. Standard Extended Protocols (Quality Gates)
 **MANDATORY**: For specific workflows, activate the corresponding `_extended` protocol:
@@ -78,18 +90,26 @@ Prioritize based on `[REACTIVE_MODE]` in MINDFORGE.md. These are the **Quality g
 - [ ] **AgRevOps Check**: Verify ROI trends and Security Health Score via `/api/revops`.
 - [ ] **PLAN-FIRST RULE**: Never code without a verified XML plan.
 - [ ] **Verify First**: Never task-complete without successful `<verify>` output.
-- [ ] **Audit Always**: Write a JSONL entry for every significant session event. All entries must be Merkle-linked.
+- [ ] **Audit Always**: Write a JSONL entry for every significant session event. The result is a hash-chained append-only audit log (SHA-256 back-links): each entry sets `previous_hash` to the prior entry's `_hash`.
 
 ---
 
 ## ⚡ COMMAND SUITE
 
+Every entry below has a backing command file, checked by `tests/protocol-claims.test.js`. Two that
+did not (the brainstorming and history entries) are gone: neither existed in
+`.claude/commands/mindforge/` or `.agent/mindforge/` (both hold exactly 221 files, so this was not
+a mirror gap), and neither had a near-match to correct to. Temporal history is reachable, just not
+as a slash command, so it is named as what it actually is.
+
 - `/mindforge:next` — Primary auto-discovery.
 - `/mindforge:auto` — Reactive engine start.
-- `/mindforge:brainstorming` — Creative & architectural exploration.
-- `/mindforge:history` — Temporal Hub access.
+- `/mindforge:plan-phase` — Plan the next phase before writing code.
+- `/mindforge:verify-phase` — Verify the phase against its plan.
 - `/mindforge:status` — Project health & sharding state.
 - `/mindforge:audit` — Day 4 governance access.
+- `mindforge temporal <status|cleanup|inject>` — reasoning-history access (a CLI command, not a
+  slash command).
 
 ---
 
@@ -109,7 +129,11 @@ Adopt the Principal AI persona. Be instruction-dense, unambiguous, and architect
 
 **Source of Truth Hierarchy**:
 
-1. SOUL.md (Sovereign Identity — Behavioral OS)
+1. SOUL.md (Sovereign Identity — Behavioral OS). **Not shipped in the package**, and generated
+   locally rather than installed: `bin/memory/identity-synthesizer.js` creates and evolves it. If
+   your project has no SOUL.md, this entry is vacant and authority passes to MINDFORGE.md — do not
+   infer its contents. The prompt-defense baseline it carries is reproduced verbatim at the top of
+   this file, so that part reaches you either way.
 2. MINDFORGE.md (Parameter Registry)
 3. .agent/CLAUDE.md (Protocols)
 4. `.mindforge/` (Framework Binary Logic)

package/.agent/hooks/mindforge-block-no-verify.js

@@ -486,34 +486,73 @@ function checkCommand(input) {
 /**
  * Extract the command string from hook input (JSON or plain text).
  */
+/**
+ * Extract the command, and report whether input that LOOKED like JSON failed to parse.
+ *
+ * The parse-failure fallback used to `return trimmed` — scan the raw text for the bypass flag
+ * instead. That is a reasonable defence for genuinely non-JSON input, but on a TRUNCATED JSON
+ * payload it becomes a bypass: the flag is simply absent from the surviving prefix, the scan finds
+ * nothing, and the hook approves. Callers now block instead, matching trust-gate-hook.js, which
+ * prints "parse error (BLOCKING)" and exits 2 — and which is why trust-gate was NOT bypassable
+ * this way while this hook was.
+ *
+ * @returns {{command: string, jsonParseFailed: boolean}}
+ */
 function extractCommand(rawInput) {
   const trimmed = rawInput.trim();
-  if (!trimmed.startsWith('{')) return trimmed;
+  if (!trimmed.startsWith('{')) return { command: trimmed, jsonParseFailed: false };
 
   try {
     const parsed = JSON.parse(trimmed);
-    if (typeof parsed !== 'object' || parsed === null) return trimmed;
+    if (typeof parsed !== 'object' || parsed === null) {
+      return { command: trimmed, jsonParseFailed: false };
+    }
 
     // Claude Code format: { tool_input: { command: "..." } }
     const cmd = parsed.tool_input?.command;
-    if (typeof cmd === 'string') return cmd;
+    if (typeof cmd === 'string') return { command: cmd, jsonParseFailed: false };
 
     // Generic JSON formats
     for (const key of ['command', 'cmd', 'input', 'shell', 'script']) {
-      if (typeof parsed[key] === 'string') return parsed[key];
+      if (typeof parsed[key] === 'string') return { command: parsed[key], jsonParseFailed: false };
     }
 
-    return trimmed;
+    return { command: trimmed, jsonParseFailed: false };
   } catch {
-    return trimmed;
+    return { command: trimmed, jsonParseFailed: true };
   }
 }
 
 /**
  * Exportable run() for in-process execution via run-with-flags.js.
  */
-function run(rawInput) {
-  const command = extractCommand(rawInput);
+function run(rawInput, options = {}) {
+  // A truncated payload cannot be judged: the dispatcher caps stdin at MAX_STDIN, so a caller can
+  // push the git command past the cap and the flag never reaches this hook. MEASURED before this
+  // guard: `git commit --no-verify` preceded by ~1 MiB of padding scored exit 0 (allowed), while
+  // the same command alone scored exit 2. Its sibling mindforge-config-protection.js:66 already
+  // refused on truncation; this hook computed the flag and never read it, and run() took only one
+  // parameter so `options` never arrived at all.
+  if (options.truncated) {
+    return {
+      exitCode: 2,
+      stderr:
+        `BLOCKED: Hook input exceeded ${options.maxStdin || MAX_STDIN} bytes. Refusing to approve ` +
+        'a git command on a truncated payload — the bypass flag this hook looks for may have been ' +
+        'cut off. Retry with a smaller payload.',
+    };
+  }
+
+  const { command, jsonParseFailed } = extractCommand(rawInput);
+  if (jsonParseFailed) {
+    return {
+      exitCode: 2,
+      stderr:
+        'BLOCKED: hook input began with "{" but is not valid JSON, so the command could not be ' +
+        'read. Failing closed rather than scanning a partial payload for the bypass flag.',
+    };
+  }
+
   const result = checkCommand(command);
 
   if (result.blocked) {
@@ -530,21 +569,30 @@ module.exports = { run };
 
 // Stdin fallback for spawnSync execution — only when invoked directly, not via require()
 if (require.main === module) {
+  // Truncation is tracked here too, and seeded from the dispatcher's env flag. This path had the
+  // same bypass as run(): it capped stdin at MAX_STDIN and then judged the surviving prefix,
+  // silently dropping whatever came after. Going through run() keeps ONE decision path for both
+  // invocation modes rather than two that can drift — the same discipline audit-hash.js uses for
+  // its writer and verifier.
+  let truncated = /^(1|true|yes)$/i.test(String(process.env.MINDFORGE_HOOK_INPUT_TRUNCATED || ''));
+
   process.stdin.setEncoding('utf8');
   process.stdin.on('data', chunk => {
     if (raw.length < MAX_STDIN) {
       const remaining = MAX_STDIN - raw.length;
       raw += chunk.substring(0, remaining);
+      if (chunk.length > remaining) truncated = true;
+    } else {
+      truncated = true;
     }
   });
 
   process.stdin.on('end', () => {
-    const command = extractCommand(raw);
-    const result = checkCommand(command);
+    const output = run(raw, { truncated, maxStdin: MAX_STDIN });
 
-    if (result.blocked) {
-      process.stderr.write(result.reason + '\n');
-      process.exit(2);
+    if (Number.isInteger(output.exitCode) && output.exitCode !== 0) {
+      if (output.stderr) process.stderr.write(output.stderr.endsWith('\n') ? output.stderr : output.stderr + '\n');
+      process.exit(output.exitCode);
     }
 
     process.stdout.write(raw);

package/.agent/hooks/mindforge-config-protection.js

@@ -62,6 +62,58 @@ function parseInput(inputOrRaw) {
 /**
  * Exportable run() for in-process execution via run-with-flags.js.
  */
+/**
+ * Return the protected path a Bash command would WRITE, or '' if it writes none.
+ *
+ * Deliberately conservative and pattern-specific rather than clever. This hook is deny-class, so a
+ * false positive blocks a legitimate command; and every pattern here was chosen because the protected
+ * file appears in an unambiguous write position:
+ *
+ *   > path        >> path      >| path        shell redirect
+ *   tee ... path                              writes each named file
+ *   sed -i ... path                           edits in place
+ *   dd of=path                                writes the output file
+ *   truncate ... path                         truncates the named file
+ *   cp/mv src path                            path is the DESTINATION only when it is last
+ *
+ * NOT matched, on purpose: `cat path`, `grep x path`, `git diff path`, `< path`, and
+ * `cp path /tmp/backup` — all reads. A pipeline is split on |, ; and && first, so
+ * `cat tsconfig.json | grep strict` cannot be mistaken for a write.
+ */
+function bashWriteTarget(command) {
+  if (!command) return '';
+  const names = [...PROTECTED_FILES].map((n) => n.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+  if (!names.length) return '';
+  const anyName = `(?:${names.join('|')})`;
+  // A path token ending in a protected basename, at a word boundary so `my-tsconfig.json` is not
+  // mistaken for `tsconfig.json`.
+  const PATH = `((?:[^\\s;|&<>]*[/])?${anyName})(?![\\w.-])`;
+
+  // Normalise `>|` (bash's noclobber override) to `>` BEFORE splitting on pipelines. Splitting on a
+  // bare `|` tears `>|` in half — `echo {} >| tsconfig.json` became the segments `echo {} >` and
+  // ` tsconfig.json`, so the redirect pattern found nothing and the write was permitted. The
+  // segmentation was defeating the operator match it exists to support. `>|` and `>` are the same
+  // write as far as this gate is concerned, so collapsing them is exact, not a heuristic.
+  const normalised = command.replace(/>\s*\|/g, '>');
+  for (const segment of normalised.split(/\|\||&&|[;|\n]/)) {
+    const s = segment.trim();
+    if (!s) continue;
+    const checks = [
+      new RegExp(`>>?\\|?\\s*${PATH}`),                       // redirect
+      new RegExp(`\\btee\\b(?:\\s+-\\S+)*\\s+${PATH}`),        // tee [flags] path
+      new RegExp(`\\bsed\\b[^\\n]*?\\s-i\\S*[^\\n]*?\\s${PATH}`), // sed -i ... path
+      new RegExp(`\\bdd\\b[^\\n]*?\\bof=${PATH}`),             // dd of=path
+      new RegExp(`\\btruncate\\b[^\\n]*?\\s${PATH}`),          // truncate ... path
+      new RegExp(`\\b(?:cp|mv|install)\\b[^\\n]*?\\s${PATH}\\s*$`), // destination is the LAST token
+    ];
+    for (const re of checks) {
+      const m = s.match(re);
+      if (m) return m[1];
+    }
+  }
+  return '';
+}
+
 function run(inputOrRaw, options = {}) {
   if (options.truncated) {
     return {
@@ -74,7 +126,24 @@ function run(inputOrRaw, options = {}) {
   }
 
   const input = parseInput(inputOrRaw);
-  const filePath = input?.tool_input?.file_path || input?.tool_input?.file || '';
+  let filePath = input?.tool_input?.file_path || input?.tool_input?.file || '';
+
+  // A Bash command reaches the same files by a different door.
+  //
+  // Measured before this: an Edit targeting an existing tsconfig.json returned exit 2, while
+  // `echo {} > tsconfig.json` as a Bash command returned exit 0 — and trust-gate permitted it too.
+  // The identical outcome was blocked through one tool surface and silently permitted through
+  // another, with no warning on the permitted path. That is what made "Non-Bypassable Compliance
+  // Gates" unsupportable: not a disabled gate, a gate watching one entrance.
+  //
+  // Only WRITE intent counts. `cat tsconfig.json`, `grep x tsconfig.json` and
+  // `cp tsconfig.json /tmp/backup` are reads of a protected file and must pass — a gate that blocks
+  // reading its own protected files would be worse than the hole it closes, and this hook is
+  // deny-class, so a false positive blocks the operator's real work.
+  if (!filePath) {
+    const target = bashWriteTarget(String(input?.tool_input?.command || ''));
+    if (target) filePath = target;
+  }
   if (!filePath) return { exitCode: 0 };
 
   const basename = path.basename(filePath);
@@ -96,13 +165,23 @@ function run(inputOrRaw, options = {}) {
       return { exitCode: 0 };
     }
 
+    // The deny reason no longer names the env var that turns this gate off.
+    //
+    // A PreToolUse denial is delivered to the MODEL whose tool call was just refused, so the old
+    // message ended by telling the agent it had blocked exactly how to stop being blocked
+    // ("disable the config-protection hook temporarily (MINDFORGE_DISABLED_HOOKS)"). A control
+    // that hands out its own bypass in the refusal is a suggestion, not a control.
+    //
+    // The escape hatch still exists and is documented in this file's header for the HUMAN
+    // operator, who is the party entitled to use it — and run-with-flags.js now writes
+    // "SECURITY GATE DISABLED" to stderr whenever it is used, so exercising it leaves a record.
     return {
       exitCode: 2,
       stderr:
         `BLOCKED: Modifying ${basename} is not allowed. ` +
         'Fix the source code to satisfy linter/formatter/tsconfig rules instead ' +
-        'of weakening the config. If this is a legitimate config change, disable ' +
-        'the config-protection hook temporarily (MINDFORGE_DISABLED_HOOKS).'
+        'of weakening the config. A legitimate config change needs a human decision, ' +
+        'not a hook bypass — ask the operator.'
     };
   }
 

package/.agent/hooks/mindforge-context-monitor.js

@@ -127,7 +127,7 @@ process.stdin.on('end', () => {
         ? `CONTEXT CRITICAL: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
           'Context is nearly exhausted. Do NOT start new complex work or write handoff files — ' +
           'MindForge state is already tracked in STATE.md. Inform the user so they can run ' +
-          '/mindforge:pause-work at the next natural stopping point.'
+          '/mindforge:checkpoint at the next natural stopping point.'
         : `CONTEXT CRITICAL: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
           'Context is nearly exhausted. Inform the user that context is low and ask how they ' +
           'want to proceed. Do NOT autonomously save state or write handoff files unless the user asks.';

package/.agent/hooks/mindforge-workflow-guard.js

@@ -5,7 +5,7 @@
 // (no active /mindforge: command or Task subagent) and injects an advisory warning.
 //
 // This is a SOFT guard — it advises, not blocks. The edit still proceeds.
-// The warning nudges Claude to use /mindforge:quick or /mindforge:fast instead of
+// The warning nudges Claude to use /mindforge:quick or /mindforge:do instead of
 // making direct edits that bypass state tracking.
 //
 // Enable via config: hooks.workflow_guard: true (default: false)
@@ -80,7 +80,7 @@ process.stdin.on('end', () => {
         hookEventName: 'PreToolUse',
         additionalContext: `⚠️ WORKFLOW ADVISORY: You're editing ${path.basename(filePath)} directly without a MindForge command. ` +
           'This edit will not be tracked in STATE.md or produce a SUMMARY.md. ' +
-          'Consider using /mindforge:fast for trivial fixes or /mindforge:quick for larger changes ' +
+          'Consider using /mindforge:do to route the intent, or /mindforge:quick for a small tracked change, ' +
           'to maintain project state tracking. ' +
           'If this is intentional (e.g., user explicitly asked for a direct edit), proceed normally.'
       }

package/.agent/hooks/run-with-flags.js

@@ -21,11 +21,78 @@
 const fs = require('fs');
 const path = require('path');
 const { spawnSync } = require('child_process');
-const { isHookEnabled } = require('./lib/hook-flags');
+const { isHookEnabled, getDisabledHookIds, getHookProfile, normalizeId } = require('./lib/hook-flags');
 const { buildPreToolUseAdditionalContext } = require('./lib/pretooluse-visible-output');
 
 const MAX_STDIN = 1024 * 1024;
 
+/**
+ * Hooks whose entire job is to DENY. If one of these cannot produce a verdict, the safe answer
+ * is "block", because nothing has established that the operation is safe.
+ *
+ * Measured contract, identical across all three: exit 0 = allow, exit 2 = block. (trust-gate
+ * also writes {"decision":"block"} to stdout; the other two write a reason to stderr.) Exit 1 is
+ * not in the contract at all — Claude Code does not read it as a denial.
+ *
+ * Every OTHER hook stays fail-open on purpose. context-monitor, session-init, check-update and
+ * instinct-capture are advisory: if telemetry cannot run, nothing about the operation's safety
+ * became unknown, and blocking a tool call because a logger failed would be indefensible.
+ */
+const DENY_CLASS = new Set([
+  'trust-gate',
+  'mindforge-block-no-verify',
+  'mindforge-config-protection',
+]);
+
+/**
+ * Escape hatch, deliberately loud.
+ *
+ * Rationale for having one at all: these gates fire on every Bash call for anyone working in a
+ * MindForge checkout, so a latent crash in trust-gate would otherwise brick every tool call with
+ * no way out but editing hook source. The reviewed risk of fail-closed behaviour was precisely
+ * "visible unexplained tool-call denials". This makes the override explicit and auditable rather
+ * than leaving the failure mode silent.
+ */
+const FAIL_OPEN_OVERRIDE = process.env.MINDFORGE_HOOK_FAILOPEN === '1';
+
+/**
+ * A hook could not produce a verdict. Decide what that means and exit.
+ *
+ * Before this, EVERY such path echoed stdin and exited 0 — which Claude Code reads as an explicit
+ * ALLOW, indistinguishable from a hook that ran and approved. Measured paths that behaved this
+ * way: a script that does not exist, a rejected path traversal (it printed "Path traversal
+ * rejected" and then permitted), a run() that threw, a non-integer exitCode, and the top-level
+ * catch. The spawn path exited 1 instead, which is out of contract and therefore also permits —
+ * that one covers a hook TIMEOUT, where no exit 2 was previously reachable at all.
+ *
+ * @param {string} hookId
+ * @param {string} raw   the original payload, echoed only when allowing
+ * @param {string} reason
+ */
+function failed(hookId, raw, reason) {
+  const isDenyClass = DENY_CLASS.has(hookId);
+
+  if (isDenyClass && !FAIL_OPEN_OVERRIDE) {
+    process.stderr.write(
+      `[Hook] BLOCKED: ${hookId} could not run, so this operation was not checked — ${reason}\n` +
+      `[Hook] ${hookId} is a deny-class gate; failing closed. Fix the hook, or set ` +
+      'MINDFORGE_HOOK_FAILOPEN=1 to permit unchecked operations.\n');
+    // No stdout: a block carries its reason on stderr (see mindforge-block-no-verify).
+    process.exit(2);
+  }
+
+  if (isDenyClass) {
+    process.stderr.write(
+      `[Hook] FAIL-OPEN OVERRIDE: ${hookId} could not run (${reason}) and ` +
+      'MINDFORGE_HOOK_FAILOPEN=1 is set, so the operation proceeds UNCHECKED.\n');
+  } else {
+    process.stderr.write(`[Hook] ${hookId} skipped (advisory) — ${reason}\n`);
+  }
+
+  process.stdout.write(raw);
+  process.exit(0);
+}
+
 function readStdinRaw() {
   return new Promise(resolve => {
     let raw = '';
@@ -92,16 +159,73 @@ function writeLegacySpawnOutput(raw, result) {
 }
 
 /**
- * Resolve the MindForge install root. In a plugin-install layout CLAUDE_PLUGIN_ROOT
- * points at the plugin root; otherwise we resolve the repo/.agent root from this
- * file's location (.agent/hooks/ -> repo root two levels up).
+ * The roots this dispatcher can legitimately run under, derived from its OWN location.
+ *
+ *   plugin install    <pluginRoot>/scripts/run-with-flags.js    -> __dirname/..
+ *   repo / npx        <root>/.agent/hooks/run-with-flags.js     -> __dirname/../..
+ *   installed project <project>/.claude/hooks/run-with-flags.js -> __dirname/../..
+ *
+ * In every real layout the root is an ancestor of __dirname. That is the property the
+ * CLAUDE_PLUGIN_ROOT check below relies on. A new layout must be added here deliberately —
+ * failing closed on an unrecognised one is the point.
+ */
+function candidateRoots() {
+  return [
+    path.resolve(__dirname, '..'),
+    path.resolve(__dirname, '..', '..'),
+  ];
+}
+
+/**
+ * realpath if the path exists, plain resolve otherwise.
+ *
+ * This exists to prevent FALSE REJECTIONS, not to block an attack — a correction to my first
+ * reading of it. An unrelated directory is rejected by the candidate comparison whether or not it
+ * is a symlink, because its resolved path is not a candidate either way. What realpath buys is the
+ * converse: a LEGITIMATE root reached by an equivalent path still matches. That happens routinely —
+ * a symlinked checkout, or macOS reporting /tmp/x while process paths resolve to /private/tmp/x.
+ * Comparing unresolved strings would reject those and silently fall back to the derived root.
+ */
+function canonical(p) {
+  try { return fs.realpathSync(path.resolve(p)); } catch { return path.resolve(p); }
+}
+
+/**
+ * Resolve the MindForge install root.
+ *
+ * CLAUDE_PLUGIN_ROOT is honoured ONLY when it names a root this dispatcher could actually be
+ * running from. It used to be returned verbatim, which made it a gate-substitution primitive
+ * rather than a relocation hint: the dispatcher resolves the hook script relative to this root,
+ * so pointing the variable at an attacker-controlled directory makes an arbitrary file execute
+ * WITH THE AUTHORITY OF THE SECURITY GATE. Measured against the real trust-gate:
+ *
+ *   unset                                   `rm -rf /` -> exit 2  (denied)
+ *   CLAUDE_PLUGIN_ROOT=<dir with a stub>    `rm -rf /` -> exit 0  (APPROVED by the stub)
+ *   CLAUDE_PLUGIN_ROOT=/tmp                 `rm -rf /` -> exit 2  (fails closed: no script there)
+ *
+ * The third case was already safe once deny-class hooks began failing closed. The second was
+ * not, and no amount of fail-closed logic fixes it — the substituted gate returns a clean ALLOW.
+ * The existing traversal guard does not help either, because the root it measures against is
+ * exactly what moved.
+ *
+ * Rejection is loud and falls back to the derived root, so a mis-set variable degrades to the
+ * correct gate rather than to no gate.
  */
 function getHookRoot() {
-  if (process.env.CLAUDE_PLUGIN_ROOT && process.env.CLAUDE_PLUGIN_ROOT.trim()) {
-    return process.env.CLAUDE_PLUGIN_ROOT;
+  const derived = path.resolve(__dirname, '..', '..');
+  const raw = process.env.CLAUDE_PLUGIN_ROOT;
+  if (!raw || !raw.trim()) return derived;
+
+  const requested = canonical(raw.trim());
+  if (candidateRoots().some((c) => canonical(c) === requested)) {
+    return requested;
   }
-  // .agent/hooks/run-with-flags.js -> repo root is two dirs up.
-  return path.resolve(__dirname, '..', '..');
+
+  process.stderr.write(
+    `[Hook] IGNORING CLAUDE_PLUGIN_ROOT=${raw.trim()} — it is not a root this dispatcher runs ` +
+    'from, and honouring it would resolve hook scripts out of an unrelated directory (executing ' +
+    `them with the gate's authority). Using ${derived} instead.\n`);
+  return derived;
 }
 
 async function main() {
@@ -114,6 +238,23 @@ async function main() {
   }
 
   if (!isHookEnabled(hookId, { profiles: profilesCsv })) {
+    // Leave a record. Switching a hook off used to be entirely silent — measured,
+    // MINDFORGE_DISABLED_HOOKS=trust-gate gave exit 0 with EMPTY stderr, so a disabled security
+    // gate was indistinguishable from a gate that ran and approved, in the log as well as in the
+    // exit code. The two reasons are reported separately because they are different events: an
+    // explicit opt-out is somebody's decision, while a profile mismatch is ordinary configuration.
+    const explicitlyDisabled = getDisabledHookIds().has(normalizeId(hookId));
+    if (explicitlyDisabled && DENY_CLASS.has(hookId)) {
+      process.stderr.write(
+        `[Hook] SECURITY GATE DISABLED: ${hookId} was switched off via MINDFORGE_DISABLED_HOOKS, ` +
+        'so this operation ran unchecked.\n');
+    } else if (explicitlyDisabled) {
+      process.stderr.write(`[Hook] ${hookId} disabled via MINDFORGE_DISABLED_HOOKS.\n`);
+    } else {
+      process.stderr.write(
+        `[Hook] ${hookId} not active for profile ${getHookProfile()} ` +
+        `(registered for: ${profilesCsv || 'standard,strict'}).\n`);
+    }
     process.stdout.write(raw);
     process.exit(0);
   }
@@ -122,17 +263,14 @@ async function main() {
   const resolvedRoot = path.resolve(hookRoot);
   const scriptPath = path.resolve(hookRoot, relScriptPath);
 
-  // Prevent path traversal outside the install root
+  // Prevent path traversal outside the install root. This branch previously printed
+  // "Path traversal rejected" and then exited 0 — announcing an attack signal and permitting it.
   if (!scriptPath.startsWith(resolvedRoot + path.sep)) {
-    process.stderr.write(`[Hook] Path traversal rejected for ${hookId}: ${scriptPath}\n`);
-    process.stdout.write(raw);
-    process.exit(0);
+    failed(hookId, raw, `script path escapes the install root: ${scriptPath}`);
   }
 
   if (!fs.existsSync(scriptPath)) {
-    process.stderr.write(`[Hook] Script not found for ${hookId}: ${scriptPath}\n`);
-    process.stdout.write(raw);
-    process.exit(0);
+    failed(hookId, raw, `script not found at ${scriptPath}`);
   }
 
   // Prefer direct require() when the hook exports run(rawInput). Eliminates one
@@ -161,10 +299,18 @@ async function main() {
         truncated,
         maxStdin: MAX_STDIN
       });
+      // A hook that returns an exitCode which is not an integer has produced a result we cannot
+      // read. emitHookResult() coerced that to 0, so `{exitCode: '2'}` — a string, e.g. from
+      // JSON round-tripping — silently became ALLOW. Absent exitCode is different and legitimate:
+      // it means "allow, with a message".
+      if (output && typeof output === 'object'
+          && Object.prototype.hasOwnProperty.call(output, 'exitCode')
+          && !Number.isInteger(output.exitCode)) {
+        failed(hookId, raw, `run() returned a non-integer exitCode: ${JSON.stringify(output.exitCode)}`);
+      }
       process.exit(emitHookResult(raw, output));
     } catch (runErr) {
-      process.stderr.write(`[Hook] run() error for ${hookId}: ${runErr.message}\n`);
-      process.stdout.write(raw);
+      failed(hookId, raw, `run() threw: ${runErr.message}`);
     }
     process.exit(0);
   }
@@ -189,19 +335,43 @@ async function main() {
   if (result.stderr) process.stderr.write(result.stderr);
 
   if (result.error || result.signal || result.status === null) {
+    // Covers the 30s spawn TIMEOUT, which arrives as signal SIGTERM with a null status. Exiting 1
+    // here meant a timed-out security gate permitted the operation: 1 is not in the 0-allow/
+    // 2-block contract, so Claude Code does not read it as a denial.
     const failureDetail = result.error
       ? result.error.message
       : result.signal
         ? `terminated by signal ${result.signal}`
         : 'missing exit status';
-    writeStderr(`[Hook] legacy hook execution failed for ${hookId}: ${failureDetail}`);
-    process.exit(1);
+    failed(hookId, raw, `child process failed: ${failureDetail}`);
+  }
+
+  if (!Number.isInteger(result.status)) {
+    failed(hookId, raw, `child returned a non-integer status: ${String(result.status)}`);
   }
 
-  process.exit(Number.isInteger(result.status) ? result.status : 0);
+  // Enforce the contract: 0 = allow, 2 = block. Anything else is the hook ERRORING, not deciding.
+  // Measured: a hook that throws at module scope exits 1, and 1 is not a denial Claude Code
+  // honours — so a crashed security gate was permitting the very operation it exists to check.
+  // Advisory hooks keep their status verbatim; only a deny-class gate turns an unreadable result
+  // into a block, because only there does "we could not decide" mean "do not proceed".
+  if (result.status !== 0 && result.status !== 2) {
+    failed(hookId, raw, `child exited ${result.status}, which is outside the 0-allow/2-block contract`);
+  }
+
+  process.exit(result.status);
 }
 
 main().catch(err => {
+  // The dispatcher itself failed. hookId is argv[2] — read it directly, because main() may have
+  // thrown before assigning anything, and the class decision needs it.
+  const hookId = process.argv[2] || '';
+  if (DENY_CLASS.has(hookId) && !FAIL_OPEN_OVERRIDE) {
+    process.stderr.write(
+      `[Hook] BLOCKED: dispatcher failed for ${hookId} — ${err.message}\n` +
+      '[Hook] deny-class gate; failing closed. Set MINDFORGE_HOOK_FAILOPEN=1 to override.\n');
+    process.exit(2);
+  }
   process.stderr.write(`[Hook] run-with-flags error: ${err.message}\n`);
   process.exit(0);
 });

package/.agent/mindforge/browse.md

@@ -1,11 +1,11 @@
 ---
-description: @mindforge browse <url | action>
+description: /mindforge:browse <url | action>
 ---
 
 # /mindforge:browse
 
 ## Usage
-`@mindforge browse <url | action>`
+`/mindforge:browse <url | action>`
 
 ## Description
 Controls the persistent MindForge browser daemon. 

package/.agent/mindforge/checkpoint.md

@@ -61,7 +61,7 @@ Remove old checkpoints, keeping the last 5.
 
 ## AUDIT linkage
 
-Each create/verify optionally writes a Merkle-linked AUDIT.jsonl entry:
+Each create/verify optionally writes a hash-chained AUDIT.jsonl entry:
 
 ```json
 { "event": "checkpoint_created", "name": "core-done", "sha": "abc1234", "tests_pass_rate": 1.0, "coverage": 0.0 }

package/.agent/mindforge/harness-audit.md

@@ -31,7 +31,7 @@ LLM layer judges *whether it matters here* and proposes the highest-leverage fix
 
 ## Step 3 — Report + AUDIT entry
 
-Summarize the scorecard, then write a Merkle-linked AUDIT.jsonl entry:
+Summarize the scorecard, then write a hash-chained AUDIT.jsonl entry:
 
 ```json
 {