mindforge-cc 11.9.3 → 11.9.4

package/.mindforge/config.json

@@ -1,5 +1,5 @@
 {
-  "version": "11.9.3",
+  "version": "11.9.4",
   "environment": "development",
   "governance": {
     "drift_threshold": 0.75,

package/.mindforge/engine/autonomous/headless-adapter.md

@@ -47,7 +47,14 @@ Typical GitHub Action setup:
 steps:
   - uses: actions/checkout@v4
   - name: Run MindForge headless
-    run: npx mindforge headless --phase 3
+    # `npx --package=mindforge-cc` PINS the package. Bare `npx mindforge` resolves to an UNRELATED
+    # third-party package on the public registry (mindforge@1.0.21, maintainer william@mindforge.ai) —
+    # not this project, whose npm name is mindforge-cc. In a fresh runner there is no local bin to
+    # shadow it, so npx fetches and unpacks that package, runs any install scripts it has, and then
+    # fails with "could not determine executable to run" because it exposes no `mindforge` bin.
+    # Measured both forms: the pinned one exits 0 with mindforge-cc in the npx cache; the bare one
+    # exits 1 after downloading someone else's package into a job holding MINDFORGE_TOKEN.
+    run: npx --yes --package=mindforge-cc mindforge headless --phase 3
     env:
       MINDFORGE_TOKEN: ${{ secrets.MINDFORGE_TOKEN }}
       AUTO_PUSH_ON_WAVE_COMPLETE: true

package/CHANGELOG.md

@@ -1,5 +1,159 @@
 # Changelog
 
+## [11.9.4] — 2026-08-22 — Delivery: the gates register, the tarball matches its tag, three packages attested
+
+Patch release. 11.9.3 argued that an instrument must not report success while doing
+nothing. 11.9.4 is what an adversarial audit of the **published** 11.9.3 artifact found
+when that standard was applied to the delivery itself: **enforcement that installed and
+then declined to register, a tarball that could not be reproduced from its own tag, and a
+README that understated what shipped.**
+
+Every finding here came from measuring the published package in a confined environment —
+not from reading the repository. That distinction is the whole content of this release.
+
+### BREAKING
+
+- **The installer now registers hooks on projects where it previously declined.** If you
+  install into a project that has an ancestor directory containing a `.claude`, MindForge
+  now writes `.claude/settings.json` (merging append-only into any existing file) instead
+  of skipping. On a machine that has ever run Claude Code, `~/.claude` makes that
+  essentially every project — so most installs go from **0 registered hooks to 8**. Three
+  of them can block a tool call. If you were relying on the installer being inert here,
+  it no longer is; `.mindforge/hook-registration.json` records exactly what was written,
+  and the previous settings file is backed up under `.mindforge/backups/`. (#224)
+
+### Fixed
+
+**Hook registration — the gates shipped installed but inert**
+
+- **`register()` skipped whenever any ancestor held a `.claude` directory.** Measured
+  against the published 11.9.3 tarball, confined HOME, `~/.claude` as the only ancestor:
+  **11 hook scripts installed, 0 registered, no settings file written.** The gates that
+  the shipped `CLAUDE.md` calls MANDATORY were copied in and left unreachable. Same
+  sandbox on 11.9.4: **8 registered, installer preflight executed 7 of 8 and verified all
+  3 deny-class hooks returning exit 2** before keeping the file. (#224)
+
+  The reason it printed — *"the harness will read `<ancestor>/.claude/settings.json`, not
+  this directory"* — was wrong three separate ways:
+
+  1. `~/.claude/settings.json` is the **user tier**, applied in addition to the project
+     tier. Its existence carries no information about whether a project file is read, so
+     the condition that suppressed the gates was satisfied by an ordinary laptop.
+  2. For a genuine project ancestor the claim is false too — that file is not read
+     either. Verified with a natural experiment: an ancestor two levels up carried a
+     `PreToolUse` Bash hook appending a marker to a log; across a dozen tool calls with
+     the inner directory as the project root, the log was never created. Skipping did not
+     deliver the gates elsewhere. It delivered them nowhere.
+  3. The git-boundary guard was **dead code**. `stop` was the git toplevel while the walk
+     began at `dirname(projectRoot)`, so when toplevel equalled projectRoot the stop
+     condition could never be true and the walk ran to the filesystem root every time.
+     The boundary meant to keep the check local is why it reached `$HOME`.
+
+  It now warns and registers anyway: a registration that turns out inert costs nothing and
+  becomes live when the harness is launched there, whereas a skip is guaranteed inert. The
+  check additionally requires a real `settings.json` **file** — the old one accepted any
+  directory named `.claude`, and the one it hit in practice held only markdown. (#224)
+
+- **The installer's only failure-path pointer led nowhere.** It told anyone whose hooks
+  were not registered to "see `docs/troubleshooting.md`", where the word *hook* appeared
+  **0** times. That file now carries the section the message names, separating "not
+  registered" from "registered but not live", and including a copy-paste payload that
+  drives a hook directly so a broken hook can be told apart from an unwired one. (#224)
+
+**Release artifacts**
+
+- **The published tarball could not be reproduced from its tag.**
+  `.mindforge/memory/sync-manifest.json` — gitignored, written at runtime by
+  `bin/memory/semantic-hub.js` — was **1 of 1979** shipped files not tracked at
+  `v11.9.3`, so provenance attested to a tree containing a file the repository does not
+  contain. With a `files[]` allowlist, a **directory** entry ships its contents regardless
+  of `.gitignore`; `files[]` already carried a negation for `pattern-library.jsonl` for
+  exactly this reason, and the manifest's entire content is the sync record *for that
+  already-excluded file*. (#225)
+
+- **`mindforge-sdk` is published again, with provenance.** It sat at **11.8.0** on npm
+  while `sync-version.js` kept `sdk/package.json` at canonical — seven releases of
+  disagreement (11.8.1 through 11.9.3, none published) that nothing detected, because
+  `version:check` verifies the tracked file and not what the registry serves. It was also
+  the only one of the three packages with **no attestation**. The release workflow now
+  publishes it with `--provenance`, after the two proven publishes and before the GitHub
+  Release, so the newest step cannot cost the others their artifacts.
+
+- **The Homebrew formula carries the real 11.9.3 digest.** Verified against an independent
+  measurement rather than the tool's own output, and explicitly confirmed not to be the
+  SHA-256 of npm's 21-byte `{"error":"Not found"}` body — the constant #203 used to write
+  for every unpublished version. (#223)
+
+**Honesty about what is enforced**
+
+- **The README understated the product.** "What is actually enforced" still declared that
+  **no install channel registers hooks**, with a `No / No` table, and stated that the
+  plugin channel's dispatcher crashes on every fire. Measured: the plugin's
+  `scripts/lib/` exists, all **14** path tokens in `plugins/mindforge/hooks/hooks.json`
+  resolve under the plugin root, and driving the dispatcher by hand returns **exit 2** for
+  `mindforge-block-no-verify` and `mindforge-config-protection`. A document that
+  under-claims a security capability is the same defect as one that over-claims it —
+  either way it describes a system that is not the one shipped. Now stated per channel,
+  with the four cases that remain deliberately unenforced and the three liveness
+  preconditions outside MindForge's control. (#225)
+
+**Defects the published-artifact audit found (#222)**
+
+- The **v11.9.3 release page shipped empty**: `changelog-fetcher.js --latest` exits 0
+  while writing zero bytes, so the `||` fallback never fired and a 195-line changelog
+  reached nobody. The step now prefers the in-tree changelog and fails on an empty body.
+- A **shipped CI snippet told users to `npx` a package we do not own**.
+  `npx mindforge …` resolves to an unrelated third-party package; in a fresh runner it is
+  fetched and unpacked, install scripts and all, inside a job holding `MINDFORGE_TOKEN`.
+  Now pinned with `--package=mindforge-cc`.
+- The **version-source gate missed a live defect twice**. `mindforge health` printed
+  `RELEASE v0.4.2` and `Current : v11.9.3` twenty-six lines apart in a project declaring
+  0.4.2, and produced `Unexpected end of JSON input` with no manifest at all — the verb
+  whose job is verifying installation integrity misreporting the installation. Widening
+  the gate surfaced two more of the same shape, one of which bound the **wrong** version
+  silently into approval records, which is worse than no binding because the check still
+  returns a verdict.
+- `mindforge approve` died with ENOENT on any non-Node project. Absent values are now
+  recorded as `null` rather than invented.
+
+**Test infrastructure**
+
+- `tests/production.test.js` carried the uncommitted diff into its clone with
+  `git diff HEAD` (which includes staged files) but committed it with `commit -a` (which
+  stages only modified and deleted **tracked** files). So any commit **adding** a file
+  under `bin/` or `tests/` left the clone dirty and failed the gate's own cleanliness
+  assertion — reintroducing precisely the `--no-verify` pressure that carry exists to
+  avoid, for the one case it did not cover.
+
+### Added
+
+New regression gates, each falsified by reinstating the exact defect and confirming RED,
+with every touched file restored byte-exact afterwards:
+
+- `tests/hook-registration-ancestor.test.js` — six properties, the first of which asserts
+  the ancestor detector fires at all, so the other five cannot pass by never triggering.
+- `every shipped file is tracked in git` — property-based, no name list. It cannot fail on
+  a clean clone, which is how the real leak survived CI, so it is paired with a second
+  test that plants the runtime state in a throwaway clone and then packs.
+- `all three published packages publish with provenance` — counts the `npm publish`
+  invocations rather than matching one, because a single-match regex was satisfied by
+  either of the two packages that already had an attestation while the SDK had none. Also
+  asserts the SDK step is idempotent and ordered after the proven publishes.
+
+### Notes for operators
+
+- **These fixes change installer behaviour on almost every project.** After upgrading,
+  check `.mindforge/hook-registration.json` to see what was registered, and restart the
+  harness — hooks are snapshotted at session start.
+- A registered hook is only *live* if the harness has been restarted, the project is
+  trusted in the harness, and `CLAUDE_PROJECT_DIR` is set with `node` on the hook PATH.
+  None of those three are in MindForge's control; the last is a deliberate trade against a
+  fail-closed shell tail that was measured denying benign commands on a fresh clone.
+- Two gaps remain that require repository settings rather than code, and are recorded
+  rather than claimed fixed: there is no `v*` **tag ruleset** restricting who may create
+  the ref that triggers publishing, and `NPM_TOKEN` is a long-lived repository secret with
+  no GitHub environment in front of it.
+
 ## [11.9.3] — 2026-08-21 — Honesty: gates that can fail, commands that run, a release path that is checked
 
 Patch release. No new features. Twenty-one fixes, and they all turned out to be the
@@ -12,6 +166,14 @@ Contains behaviour changes under a patch bump — several of the things being fi
 bugs that a consumer could have been relying on. Read BREAKING before upgrading if you
 script against the CLI or the installer.
 
+> **Corrected after release.** Three measured numbers in this entry were wrong and are fixed above:
+> the count of places `--status`/`--stop` were documented (removed rather than re-guessed — it reads 4,
+> 9 or 15 depending on how you count, which is the argument against stating it); the eslint total, which
+> was 199 on the author's machine and **190** on a clean clone, because 9 problems came from an
+> untracked local directory; and "four releases behind", which is **three** (11.8.3 → 11.9.0 → 11.9.1 →
+> 11.9.2). Found by an adversarial audit of this changelog against the published artifact. A release
+> arguing that measured numbers should be reproducible has to hold its own notes to that standard.
+
 ### BREAKING
 
 Each of these is a bug fix whose correct behaviour differs from the shipped behaviour.
@@ -113,15 +275,16 @@ Each of these is a bug fix whose correct behaviour differs from the shipped beha
   exactly one event — a `v*` tag push — and the repository's only ruleset targets
   branches, so its six required checks applied to nothing on the path that ships. GitHub
   cannot attach required status checks to a tag. A `preflight` job now gates it. (#216)
-- The `stable` npm dist-tag was moved by hand, or not at all — it sat four releases
-  behind `latest` (11.8.3 against 11.9.2), so `npm i mindforge-cc@stable` delivered a
+- The `stable` npm dist-tag was moved by hand, or not at all — it sat three releases
+  behind `latest` (11.8.3 against 11.9.2, via 11.9.0 and 11.9.1), so `npm i mindforge-cc@stable` delivered a
   build with none of the 11.9.x fixes. The release workflow now moves it as its final
   step: forward-only, prereleases skipped, and verified against npm's uncached dist-tags
   endpoint rather than the CDN-cached packument. (#216)
 
 **Dashboard**
 
-- `--status` and `--stop` were documented in nine places and implemented in none; both
+- `--status` and `--stop` were documented across the harness roots and the docs and implemented
+  nowhere; both
   printed nothing and exited 0. Now implemented, before `express` is required, so they
   work without the dependency installed. (#206)
 - `--stop` identified the target by the SHAPE of its command line, which matched any
@@ -141,8 +304,8 @@ Each of these is a bug fix whose correct behaviour differs from the shipped beha
 **Verification**
 
 - `mindforge verify`'s lint stage used `--max-warnings=0`, which made it impossible to
-  pass in the repository it ships from: `npx eslint .` reports 199 problems / 0 errors /
-  199 warnings, so `verify` reported a lint FAILURE on a tree that is green by the
+  pass in the repository it ships from: on a clean clone `npx eslint .` reports 190 problems /
+  0 errors / 190 warnings, so `verify` reported a lint FAILURE on a tree that is green by the
   project's own contract. Aligned with the project's definition; errors still fail. (#204)
 - `temporal cleanup` printed "🧹 Cleaning up old temporal snapshots..." and
   "✅ Cleanup complete." with no cleanup between them. Now wired to

package/MINDFORGE.md

@@ -1,9 +1,9 @@
-# MINDFORGE.md — Parameter Registry (v11.9.3)
+# MINDFORGE.md — Parameter Registry (v11.9.4)
 
 ## 1. IDENTITY & VERSIONING
 
 [NAME]    = MindForge
-[VERSION] = 11.9.3
+[VERSION] = 11.9.4
 [STABLE]  = true
 [MODE]    = "Platform Sovereign"
 [REQUIRED_CORE_VERSION] = 11.9.1

package/README.md

@@ -6,11 +6,14 @@
 
 ## Latest release
 
-**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.
+**v11.9.3** (2026-08-21) — Honesty: gates that can fail, commands that run, a release path that is
+checked. Twenty-one fixes sharing one defect — an instrument reporting success while doing nothing:
+a self-install that printed "skipping" and overwrote 149 tracked files, 11 of 27 routed CLI verbs
+dying on `MODULE_NOT_FOUND` in a real install, `--fetch-sha` hashing npm's 404 body into the Homebrew
+formula, no version channel covering any document a user receives, and a publish path no check ever
+touched. **Contains behaviour changes under a patch bump** — several fixed bugs whose correct
+behaviour differs from what shipped. See the BREAKING section in
+[CHANGELOG.md](./CHANGELOG.md), or [RELEASENOTES.md](./RELEASENOTES.md) for human-readable notes.
 
 ---
 
@@ -19,7 +22,8 @@ human-readable notes.
 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.**
+action are hooks. Through 11.9.2 **no channel registered them**; as of 11.9.3 both channels
+register and execute them **on Claude Code**, and nowhere else.
 
 | Capability | Plugin channel | `npx` channel |
 |---|---|---|
@@ -27,34 +31,48 @@ action are hooks, and **no install channel currently registers them.**
 | 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
+| **Hooks enforced (can block a tool call)** | **Claude Code only** | **Claude Code + `--local` only** |
+
+What that means, measured rather than asserted:
+
+- **The `npx` channel generates the config it never used to ship.** `files[]` has 49 entries and
+  none of them contains `settings`, so no settings file is *published* — instead
+  `bin/installer/hook-registration.js` writes one at install time, merging append-only into any
+  file you already have. Measured on a confined install: **8 hooks registered** into
+  `.claude/settings.json`, of which the installer's own preflight **executed 7 and verified all 3
+  deny-class hooks returning exit 2** before keeping the file. A preflight failure rolls the
+  registration back rather than leaving a config whose commands do not run.
+- **The plugin channel's dispatcher runs.** It previously crashed on every fire —
+  `run-with-flags.js` requires `./lib/hook-flags` and `plugins/mindforge/scripts/lib/` was not
+  copied in. That directory now exists, all **14 path tokens** in
+  `plugins/mindforge/hooks/hooks.json` resolve under the plugin root, and driving the dispatcher by
+  hand returns **exit 2** for `mindforge-block-no-verify` and `mindforge-config-protection`.
+
+Still **not** enforced, deliberately and with a printed reason for each: any runtime other than
+Claude Code (Cursor, Copilot, Gemini/Antigravity, OpenCode), `--global` scope, a self-install
+inside a MindForge checkout, and Windows. Writing a Claude-schema config into `.cursor/` without an
+execution-verified hook contract would be decorative. Every outcome, including "not registered", is
+printed by the installer and written to `.mindforge/hook-registration.json`.
+
+Three things gate whether a registered hook is *live*, none of them in MindForge's control: the
+harness must be **restarted** (hooks are snapshotted at session start), the project must be
+**trusted** in the harness, and `CLAUDE_PROJECT_DIR` must be set with `node` on the hook PATH —
+if it is not, the commands exit 1 and the gate is simply absent, which is a deliberate trade
+against a fail-closed tail that was measured denying benign commands on a fresh clone. See
+*Hooks are installed but nothing is blocked* in `docs/troubleshooting.md`.
+
+So: on Claude Code, treat MindForge as a policy enforcement point for the 8 registered hooks plus
+a tamper-evident audit log; on every other harness, as **governance-by-convention** plus that same
+audit log. Installing it also expands your repository's trust boundary by a large volume of agent
+instructions — review what you install. The audit chain is verifiable today
 (`node bin/verify-audit.js`).
 
 ---
 
 ## Install
 
-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.
+Claude Code plugin marketplace (no project files written). The plugin's hooks now fire — see
+*What is actually enforced* above for what that does and does not cover.
 
 ```bash
 /plugin marketplace add sairam0424/MindForge

package/RELEASENOTES.md

@@ -1,5 +1,68 @@
 # Release Notes
 
+## v11.9.3 — 2026-08-21 — Honesty: gates that can fail, commands that run, a release path that is checked
+
+### What's New
+Nothing. Twenty-one fixes sharing a single defect: **an instrument reported success while doing
+nothing.** Gates that could not fail, tests a comment satisfied, docs naming scripts that do not
+exist, commands printing success while performing no action, and a publish path no check ever
+touched.
+
+### ⚠️ Breaking (under a patch bump)
+Six behaviour changes, each a bug fix whose correct behaviour differs from what shipped. Read these
+if you script against the CLI or the installer.
+
+- **Routed CLI commands now act on YOUR project, not MindForge's checkout.** The router passed
+  `cwd: ROOT`, so `mindforge classify` diffed MindForge's repository instead of yours and
+  `mindforge health` inspected MindForge's `node_modules`. Of 27 routed commands, 7 changed
+  behaviour — all in the correct direction.
+- **`npx mindforge-cc install`, and any other positional argument, now exits 1.** The installer
+  takes flags only and used to ignore stray words silently, so that command appeared to work while
+  configuring nothing. Use `npx mindforge-cc --claude --local`.
+- **`mindforge verify` now SKIPS unavailable stages instead of failing them.** A project with no
+  ESLint config or no test script was reported as FAILING those stages rather than as not having
+  them. CI that relied on a non-zero exit there will now pass. A run where every stage skipped
+  prints a "NOTHING WAS VERIFIED" banner rather than a clean bill of health.
+- **`scripts/sync-version.js` now exits non-zero when the plugin build artifacts are stale.** A bump
+  used to report success and exit 0 while leaving `npm test` red.
+- **A self-install no longer writes over your tracked files.** Running the installer inside a
+  MindForge checkout printed that it was skipping and then overwrote 149 tracked files, including
+  `CLAUDE.md`, `.claude/**`, `.agent/**` and `.mindforge/**`.
+- **Releases must be tagged on a commit reachable from `main`.**
+
+### Fixes
+- **11 of 27 routed CLI verbs died on `MODULE_NOT_FOUND` in a real install.** The router shipped;
+  six of the scripts it dispatches to did not.
+- **Every `--global` install reported failure on a correct run.** Verification demanded six `bin/**`
+  paths regardless of scope, so a global install — which writes 389 files to `$HOME/.claude` and,
+  deliberately, zero to `bin/` — ended `6 of 12 required file(s) missing` and exit 1, with a
+  `--force` retry that could not help.
+- **`--fetch-sha` hashed npm's 404 error body into the Homebrew formula.** For an unpublished
+  version the registry answers `{"error":"Not found"}` and `curl -sL` exits 0, so the digest written
+  was the SHA-256 of that error text — the same constant for every unpublished version — and
+  `--check` then passed. It now fails closed on both status and gzip magic bytes.
+- **No version channel covered a document a user receives.** `SECURITY.md` — the security policy at
+  the root of the published package — said "Current version: 11.9.0", and five docs titled
+  themselves v11.9.0: three releases stale while every npm manifest was correct. A channel that does
+  not exist cannot drift, so `--check` was green the whole time.
+- **The tag push that publishes was exempt from every gate.** Publishing is triggered by exactly one
+  event — a `v*` tag push — and the repository's only ruleset targets branches, so its six required
+  checks applied to nothing on the path that ships. GitHub cannot attach required status checks to a
+  tag, so this had to be fixed in the workflow itself.
+- **The `stable` dist-tag sat three releases behind `latest`** (11.8.3 against 11.9.2), so
+  `npm i mindforge-cc@stable` delivered a build with none of the 11.9.x fixes. The release workflow
+  now moves it as its final step — forward-only, prereleases skipped.
+- **`mindforge dashboard --status` and `--stop` were documented and implemented nowhere.** Both
+  printed nothing useful. `--stop` also identified its target by the SHAPE of a command line, which
+  matched any `node <anything>/dashboard/server.js` — verified against an unrelated app's dashboard.
+- **`temporal cleanup` printed "Cleaning up…" and "Cleanup complete." with no cleanup between them.**
+- **The protocol files instructed the agent to run scripts that do not exist** (`soul-engine.js`,
+  `shard-controller.js`), and 15 phantom `/mindforge:` slash commands appeared in shipped docs. A
+  reader following the user guide typed `/mindforge:personas --list` and got nothing.
+- **Every abandoned exit left a full copy of the database on disk** — 1.8 GB of orphaned `.tmp` files.
+
+Full detail, including the measured evidence for each: [changelogs/v11.9.3.md](./changelogs/v11.9.3.md).
+
 ## v11.9.2 — 2026-08-16 — Correctness: config gate, audit chain, retrieval, cost ledger
 
 ### What's New

package/SECURITY.md

@@ -1,6 +1,6 @@
 # Security Policy
 
-> **Current version:** 11.9.3 | **npm audit:** 0 vulnerabilities across root, sdk, mcp-server
+> **Current version:** 11.9.4 | **npm audit:** 0 vulnerabilities across root, sdk, mcp-server
 
 ## Supported Versions
 

package/bin/dashboard/metrics-aggregator.js

@@ -210,7 +210,12 @@ function getApprovals() {
   const { verifyRecord } = require('../governance/approval-record');
   let currentVersion = null;
   try {
-    currentVersion = JSON.parse(fs.readFileSync(path.join(__dirname, '..', '..', 'package.json'), 'utf8')).version;
+    // MindForge's version, resolved by package NAME. `path.join(__dirname, '..', '..',
+    // 'package.json')` reached <project>/package.json in an install — the CONSUMER's manifest — so
+    // verifyRecord() below compared an approval record against the host app's version (0.4.2, say)
+    // instead of MindForge's. The try/catch stopped it crashing, which is why it went unnoticed:
+    // a wrong binding is quieter than a missing one.
+    currentVersion = require('../utils/mindforge-version').resolveMindforgeVersion(process.cwd()).version;
   } catch { /* version binding is skipped if the manifest is unreadable */ }
 
   const now = Date.now();

package/bin/governance/approve.js

@@ -80,7 +80,18 @@ function approve(opts = {}) {
   const root = opts.root || ROOT;
   const approvalsDir = opts.approvalsDir || APPROVALS_DIR;
 
-  const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+  // TOLERATES A PROJECT WITH NO package.json. This was an unguarded readFileSync, so `mindforge approve`
+  // died with `ENOENT: no such file or directory, open '<project>/package.json'` on any repo that is not
+  // Node — Python, Go, Rust, or any polyglot root. Measured on the published 11.9.3 tarball.
+  //
+  // The FIELDS stay the consumer's on purpose: this record documents a governance decision in the
+  // user's project, so `project` and `version` describing that project is correct. Only the crash was
+  // wrong. Absent values are recorded as null rather than invented — an approval record that guesses
+  // what it is approving is worse than one that admits it does not know.
+  const pkg = (() => {
+    try { return JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')); }
+    catch { return { name: path.basename(root) || null, version: null }; }
+  })();
 
   const id = `MF-AUTH-${Date.now().toString(36).toUpperCase()}`;
   const timestamp = new Date().toISOString();

package/bin/governance/verify-approvals.js

@@ -72,7 +72,19 @@ function summary(lines) {
 
 function main(argv = process.argv.slice(2)) {
   const args = parseArgs(argv);
-  const currentVersion = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8')).version;
+  // MindForge's version, by package NAME. This read `path.join(ROOT, 'package.json')`, which in an
+  // install is the CONSUMER's manifest — so every approval record was verified against the host
+  // app's version rather than MindForge's, and the command died with ENOENT on any project without
+  // a package.json at all. Version binding is the point of the record; binding it to the wrong
+  // version is worse than not binding it, because the check still reports a verdict.
+  //
+  // Degrades to null rather than throwing: an unresolvable version should make the binding
+  // unverifiable, not make the whole verification unrunnable. verifyRecord treats a null
+  // currentVersion as "do not check the binding".
+  let currentVersion = null;
+  try {
+    currentVersion = require('../utils/mindforge-version').resolveMindforgeVersion(process.cwd()).version;
+  } catch { /* binding unverifiable, reported as such rather than crashing the run */ }
 
   let files = [];
   try {

package/bin/installer/hook-registration.js

@@ -60,6 +60,7 @@
  */
 
 const fs = require('node:fs');
+const os = require('node:os');
 const path = require('node:path');
 const { spawnSync } = require('node:child_process');
 
@@ -366,14 +367,48 @@ function probeInner(projectRoot, failures) {
 
 // ── register ─────────────────────────────────────────────────────────────────
 
-/** Would the harness read a DIFFERENT .claude/settings.json than the one we are about to write? */
-function ancestorClaudeDir(projectRoot) {
-  const top = spawnSync('git', ['rev-parse', '--show-toplevel'], { cwd: projectRoot, encoding: 'utf8' });
-  const stop = top.status === 0 ? path.resolve(top.stdout.trim()) : path.parse(projectRoot).root;
+/**
+ * An ancestor project whose OWN .claude/settings.json a harness launched there would read instead of
+ * ours. Advisory only — see the three corrections below. Returns the directory, or null.
+ *
+ * THIS USED TO SKIP REGISTRATION ENTIRELY, and the reason it printed was wrong in three ways:
+ *
+ *   "the harness will read <ancestor>/.claude/settings.json, not this directory"
+ *
+ * 1. IT TRIPPED ON $HOME, so it tripped for essentially every project. ~/.claude/settings.json is the
+ *    USER TIER: Claude Code applies it to every session IN ADDITION TO the project tier, not instead
+ *    of it. Its existence says nothing about whether a project file is read. Measured on the author's
+ *    machine: the user-tier hooks fire on every Bash call while a project settings.json sits below
+ *    them. So the condition that suppressed the gates was satisfied by the normal state of a laptop.
+ *
+ * 2. FOR A REAL PROJECT ANCESTOR THE CLAIM IS ALSO FALSE — the ancestor's file is not read either.
+ *    Measured with a natural experiment: an ancestor two levels up carried a PreToolUse Bash hook
+ *    appending a marker to a log file. Across a dozen Bash calls with the inner directory as the
+ *    project root, that log was never even created. Claude Code reads the project tier from the
+ *    directory it treats as the project root; it does not walk up for settings. So skipping did not
+ *    deliver the gates "over there", it delivered them nowhere.
+ *
+ * 3. THE GIT-BOUNDARY GUARD WAS DEAD CODE. `stop` was the git toplevel, but the walk started at
+ *    path.dirname(projectRoot) — so when toplevel === projectRoot (the normal case) `dir === stop`
+ *    could never be true and the walk ran to the filesystem root every time. The boundary that was
+ *    supposed to keep this local is why it reached $HOME.
+ *
+ * So: WARN, NEVER SKIP. A registration that turns out to be inert costs nothing and becomes live the
+ * moment the harness is launched here; a skip is guaranteed inert. Two narrowings keep the warning
+ * meaningful rather than universal: $HOME is excluded because it is a tier and not a shadow, and an
+ * actual settings.json FILE must exist — the old check accepted any directory named .claude, of which
+ * a docs folder is a perfectly ordinary example.
+ *
+ * The git boundary is deliberately not repaired, just removed: a git toplevel ABOVE projectRoot means
+ * this project is nested inside another repo, which is exactly the case worth warning about, so
+ * stopping the walk there would suppress the one signal this function exists to produce.
+ */
+function shadowingProjectSettings(projectRoot) {
+  const home = os.homedir();
   let dir = path.dirname(path.resolve(projectRoot));
   for (let i = 0; i < 64; i++) {
-    if (fs.existsSync(path.join(dir, '.claude'))) return dir;
-    if (dir === stop || dir === path.dirname(dir)) break;
+    if (dir !== home && fs.existsSync(path.join(dir, SETTINGS_REL))) return dir;
+    if (dir === path.dirname(dir)) break;
     dir = path.dirname(dir);
   }
   return null;
@@ -391,10 +426,15 @@ function register(options = {}) {
   if (selfInstall) return skip('self-install: the repo maintains its own tracked .claude/settings.json');
   if (process.platform === 'win32') return skip('win32 is unverified for the emitted command shape');
 
-  const ancestor = ancestorClaudeDir(projectRoot);
-  if (ancestor) {
-    return skip(`the harness will read ${path.join(ancestor, '.claude', 'settings.json')}, not this directory — re-run the installer there`);
-  }
+  // Advisory, deliberately not a skip — see shadowingProjectSettings for the three measurements that
+  // demoted it from one. The operator is told what to do about it; the gates still get installed.
+  const shadow = shadowingProjectSettings(projectRoot);
+  const warnings = shadow
+    ? [`${path.join(shadow, SETTINGS_REL)} exists in an ancestor project. These hooks are registered `
+       + 'for THIS directory and are live when the harness runs with it as the project root. If you '
+       + `launch the harness in ${shadow} instead, run the installer there too — its project settings `
+       + 'are read from where it starts, not walked up from.']
+    : [];
 
   const copy = applyCopyManifest(projectRoot, repoRoot);
   if (!copy.ok) return skip(copy.reason);
@@ -424,7 +464,7 @@ function register(options = {}) {
 
   const text = `${JSON.stringify(merged.next, null, 2)}\n`;
   if (dryRun) {
-    return { status: 'dry-run', reason: `would write ${HOOK_SPEC.length} hooks to ${SETTINGS_REL}`, registered: false, preview: text };
+    return { status: 'dry-run', reason: `would write ${HOOK_SPEC.length} hooks to ${SETTINGS_REL}`, registered: false, preview: text, warnings };
   }
 
   const existedBefore = fs.existsSync(absSettings);
@@ -452,6 +492,7 @@ function register(options = {}) {
     preflight_skipped: verified.skipped,
     preflight_skip_reason: 'registered but not executed during preflight: spawns a background '
       + 'process and writes under $HOME. Advisory, so a failure there would not have blocked.',
+    warnings,
     residual_risk: 'CLAUDE_PROJECT_DIR unset, or node off the hook PATH, yields exit 1 and the gate is '
       + 'absent (identical to not installing). No fail-closed shell tail is used: measured, it denies '
       + 'benign commands on a fresh clone.',
@@ -466,6 +507,7 @@ function register(options = {}) {
     target: SETTINGS_REL,
     backup: receipt.backup,
     receipt: RECEIPT_REL,
+    warnings,
   };
 }
 
@@ -500,5 +542,6 @@ module.exports = {
   DENY_CLASS, OWNED_RE, KNOWN_IDS,
   commandFor, profilesFor, isOwned,
   applyCopyManifest, mergeSettings, assertNoLoss, probe,
+  shadowingProjectSettings,
   register, unregister,
 };

package/bin/installer-core.js

@@ -1152,7 +1152,15 @@ async function install(runtime, scope, options = {}) {
   } else {
     Theme.printStatus(c.yellow(`Hooks NOT registered (${hookRegistration.status}): ${hookRegistration.reason}`), 'warn');
     Theme.printStatus(c.dim('The hook scripts are installed but nothing invokes them, so no tool call '
-      + 'is gated. This is stated rather than implied — see docs/troubleshooting.md.'), 'info');
+      + 'is gated. This is stated rather than implied — see "Hooks are installed but nothing is '
+      + 'blocked" in docs/troubleshooting.md.'), 'info');
+  }
+
+  // Non-fatal advisories. Printed for BOTH outcomes, because the case that produces one today —
+  // an ancestor project with its own settings.json — used to CANCEL registration outright, and the
+  // whole point of demoting it to a warning is that the operator hears it without losing the gates.
+  for (const w of hookRegistration.warnings || []) {
+    Theme.printStatus(c.yellow(w), 'warn');
   }
 }
 
@@ -1297,11 +1305,31 @@ async function run(args) {
   const options     = { dryRun, force, verbose, withUtils, minimal };
 
   // Get package.json for version
-  const pJSON = JSON.parse(fsu.read(path.join(SOURCE_ROOT, 'package.json')));
+  // MINDFORGE'S VERSION, NOT THE HOST PROJECT'S — and it must not crash when there is no manifest.
+  //
+  // This read was `JSON.parse(fsu.read(path.join(SOURCE_ROOT, 'package.json')))`, and SOURCE_ROOT is
+  // path.resolve(__dirname, '..'). In an install that lands at <project>/bin/, so it read the CONSUMER's
+  // package.json. Measured on the published 11.9.3 tarball: in a project declaring version 0.4.2,
+  // `mindforge health` printed the banner `RELEASE v0.4.2` and then, 26 lines later, `Current : v11.9.3`
+  // — one command, two contradictory versions, exit 0. In a project with NO package.json the whole
+  // command was `Unexpected end of JSON input`, exit 1, no report at all: fsu.read returns empty for a
+  // missing file and JSON.parse throws.
+  //
+  // This is the same defect 11.9.3 fixed for `--version`, in the one verb whose advertised job is
+  // "verify project health and installation integrity". bin/utils/mindforge-version.js already resolves
+  // correctly — by package NAME, which is what distinguishes our manifest from a consumer's — and it
+  // shipped in the same release. It simply was not used here.
+  //
+  // It THROWS rather than guessing, which is right for a version check and wrong for a banner, so the
+  // banner degrades to 'unknown' instead of taking the whole health report down with it.
+  let bannerVersion = 'unknown';
+  try {
+    bannerVersion = require('./utils/mindforge-version').resolveMindforgeVersion(process.cwd()).version;
+  } catch { /* a banner must never be the reason health cannot run */ }
 
   // Print header and brand manifest
   // Print header and brand manifest
-  Theme.printHeader(pJSON.version);
+  Theme.printHeader(bannerVersion);
   Theme.printBrandManifest();
   // Check for updates only
   if (isCheck) {

package/changelogs/v11.9.3.md

@@ -12,6 +12,14 @@ Contains behaviour changes under a patch bump — several of the things being fi
 bugs that a consumer could have been relying on. Read BREAKING before upgrading if you
 script against the CLI or the installer.
 
+> **Corrected after release.** Three measured numbers in this entry were wrong and are fixed above:
+> the count of places `--status`/`--stop` were documented (removed rather than re-guessed — it reads 4,
+> 9 or 15 depending on how you count, which is the argument against stating it); the eslint total, which
+> was 199 on the author's machine and **190** on a clean clone, because 9 problems came from an
+> untracked local directory; and "four releases behind", which is **three** (11.8.3 → 11.9.0 → 11.9.1 →
+> 11.9.2). Found by an adversarial audit of this changelog against the published artifact. A release
+> arguing that measured numbers should be reproducible has to hold its own notes to that standard.
+
 ### BREAKING
 
 Each of these is a bug fix whose correct behaviour differs from the shipped behaviour.
@@ -113,15 +121,16 @@ Each of these is a bug fix whose correct behaviour differs from the shipped beha
   exactly one event — a `v*` tag push — and the repository's only ruleset targets
   branches, so its six required checks applied to nothing on the path that ships. GitHub
   cannot attach required status checks to a tag. A `preflight` job now gates it. (#216)
-- The `stable` npm dist-tag was moved by hand, or not at all — it sat four releases
-  behind `latest` (11.8.3 against 11.9.2), so `npm i mindforge-cc@stable` delivered a
+- The `stable` npm dist-tag was moved by hand, or not at all — it sat three releases
+  behind `latest` (11.8.3 against 11.9.2, via 11.9.0 and 11.9.1), so `npm i mindforge-cc@stable` delivered a
   build with none of the 11.9.x fixes. The release workflow now moves it as its final
   step: forward-only, prereleases skipped, and verified against npm's uncached dist-tags
   endpoint rather than the CDN-cached packument. (#216)
 
 **Dashboard**
 
-- `--status` and `--stop` were documented in nine places and implemented in none; both
+- `--status` and `--stop` were documented across the harness roots and the docs and implemented
+  nowhere; both
   printed nothing and exited 0. Now implemented, before `express` is required, so they
   work without the dependency installed. (#206)
 - `--stop` identified the target by the SHAPE of its command line, which matched any
@@ -141,8 +150,8 @@ Each of these is a bug fix whose correct behaviour differs from the shipped beha
 **Verification**
 
 - `mindforge verify`'s lint stage used `--max-warnings=0`, which made it impossible to
-  pass in the repository it ships from: `npx eslint .` reports 199 problems / 0 errors /
-  199 warnings, so `verify` reported a lint FAILURE on a tree that is green by the
+  pass in the repository it ships from: on a clean clone `npx eslint .` reports 190 problems /
+  0 errors / 190 warnings, so `verify` reported a lint FAILURE on a tree that is green by the
   project's own contract. Aligned with the project's definition; errors still fail. (#204)
 - `temporal cleanup` printed "🧹 Cleaning up old temporal snapshots..." and
   "✅ Cleanup complete." with no cleanup between them. Now wired to

package/changelogs/v11.9.4.md

@@ -0,0 +1,155 @@
+# Changelog
+
+## [11.9.4] — 2026-08-22 — Delivery: the gates register, the tarball matches its tag, three packages attested
+
+Patch release. 11.9.3 argued that an instrument must not report success while doing
+nothing. 11.9.4 is what an adversarial audit of the **published** 11.9.3 artifact found
+when that standard was applied to the delivery itself: **enforcement that installed and
+then declined to register, a tarball that could not be reproduced from its own tag, and a
+README that understated what shipped.**
+
+Every finding here came from measuring the published package in a confined environment —
+not from reading the repository. That distinction is the whole content of this release.
+
+### BREAKING
+
+- **The installer now registers hooks on projects where it previously declined.** If you
+  install into a project that has an ancestor directory containing a `.claude`, MindForge
+  now writes `.claude/settings.json` (merging append-only into any existing file) instead
+  of skipping. On a machine that has ever run Claude Code, `~/.claude` makes that
+  essentially every project — so most installs go from **0 registered hooks to 8**. Three
+  of them can block a tool call. If you were relying on the installer being inert here,
+  it no longer is; `.mindforge/hook-registration.json` records exactly what was written,
+  and the previous settings file is backed up under `.mindforge/backups/`. (#224)
+
+### Fixed
+
+**Hook registration — the gates shipped installed but inert**
+
+- **`register()` skipped whenever any ancestor held a `.claude` directory.** Measured
+  against the published 11.9.3 tarball, confined HOME, `~/.claude` as the only ancestor:
+  **11 hook scripts installed, 0 registered, no settings file written.** The gates that
+  the shipped `CLAUDE.md` calls MANDATORY were copied in and left unreachable. Same
+  sandbox on 11.9.4: **8 registered, installer preflight executed 7 of 8 and verified all
+  3 deny-class hooks returning exit 2** before keeping the file. (#224)
+
+  The reason it printed — *"the harness will read `<ancestor>/.claude/settings.json`, not
+  this directory"* — was wrong three separate ways:
+
+  1. `~/.claude/settings.json` is the **user tier**, applied in addition to the project
+     tier. Its existence carries no information about whether a project file is read, so
+     the condition that suppressed the gates was satisfied by an ordinary laptop.
+  2. For a genuine project ancestor the claim is false too — that file is not read
+     either. Verified with a natural experiment: an ancestor two levels up carried a
+     `PreToolUse` Bash hook appending a marker to a log; across a dozen tool calls with
+     the inner directory as the project root, the log was never created. Skipping did not
+     deliver the gates elsewhere. It delivered them nowhere.
+  3. The git-boundary guard was **dead code**. `stop` was the git toplevel while the walk
+     began at `dirname(projectRoot)`, so when toplevel equalled projectRoot the stop
+     condition could never be true and the walk ran to the filesystem root every time.
+     The boundary meant to keep the check local is why it reached `$HOME`.
+
+  It now warns and registers anyway: a registration that turns out inert costs nothing and
+  becomes live when the harness is launched there, whereas a skip is guaranteed inert. The
+  check additionally requires a real `settings.json` **file** — the old one accepted any
+  directory named `.claude`, and the one it hit in practice held only markdown. (#224)
+
+- **The installer's only failure-path pointer led nowhere.** It told anyone whose hooks
+  were not registered to "see `docs/troubleshooting.md`", where the word *hook* appeared
+  **0** times. That file now carries the section the message names, separating "not
+  registered" from "registered but not live", and including a copy-paste payload that
+  drives a hook directly so a broken hook can be told apart from an unwired one. (#224)
+
+**Release artifacts**
+
+- **The published tarball could not be reproduced from its tag.**
+  `.mindforge/memory/sync-manifest.json` — gitignored, written at runtime by
+  `bin/memory/semantic-hub.js` — was **1 of 1979** shipped files not tracked at
+  `v11.9.3`, so provenance attested to a tree containing a file the repository does not
+  contain. With a `files[]` allowlist, a **directory** entry ships its contents regardless
+  of `.gitignore`; `files[]` already carried a negation for `pattern-library.jsonl` for
+  exactly this reason, and the manifest's entire content is the sync record *for that
+  already-excluded file*. (#225)
+
+- **`mindforge-sdk` is published again, with provenance.** It sat at **11.8.0** on npm
+  while `sync-version.js` kept `sdk/package.json` at canonical — seven releases of
+  disagreement (11.8.1 through 11.9.3, none published) that nothing detected, because
+  `version:check` verifies the tracked file and not what the registry serves. It was also
+  the only one of the three packages with **no attestation**. The release workflow now
+  publishes it with `--provenance`, after the two proven publishes and before the GitHub
+  Release, so the newest step cannot cost the others their artifacts.
+
+- **The Homebrew formula carries the real 11.9.3 digest.** Verified against an independent
+  measurement rather than the tool's own output, and explicitly confirmed not to be the
+  SHA-256 of npm's 21-byte `{"error":"Not found"}` body — the constant #203 used to write
+  for every unpublished version. (#223)
+
+**Honesty about what is enforced**
+
+- **The README understated the product.** "What is actually enforced" still declared that
+  **no install channel registers hooks**, with a `No / No` table, and stated that the
+  plugin channel's dispatcher crashes on every fire. Measured: the plugin's
+  `scripts/lib/` exists, all **14** path tokens in `plugins/mindforge/hooks/hooks.json`
+  resolve under the plugin root, and driving the dispatcher by hand returns **exit 2** for
+  `mindforge-block-no-verify` and `mindforge-config-protection`. A document that
+  under-claims a security capability is the same defect as one that over-claims it —
+  either way it describes a system that is not the one shipped. Now stated per channel,
+  with the four cases that remain deliberately unenforced and the three liveness
+  preconditions outside MindForge's control. (#225)
+
+**Defects the published-artifact audit found (#222)**
+
+- The **v11.9.3 release page shipped empty**: `changelog-fetcher.js --latest` exits 0
+  while writing zero bytes, so the `||` fallback never fired and a 195-line changelog
+  reached nobody. The step now prefers the in-tree changelog and fails on an empty body.
+- A **shipped CI snippet told users to `npx` a package we do not own**.
+  `npx mindforge …` resolves to an unrelated third-party package; in a fresh runner it is
+  fetched and unpacked, install scripts and all, inside a job holding `MINDFORGE_TOKEN`.
+  Now pinned with `--package=mindforge-cc`.
+- The **version-source gate missed a live defect twice**. `mindforge health` printed
+  `RELEASE v0.4.2` and `Current : v11.9.3` twenty-six lines apart in a project declaring
+  0.4.2, and produced `Unexpected end of JSON input` with no manifest at all — the verb
+  whose job is verifying installation integrity misreporting the installation. Widening
+  the gate surfaced two more of the same shape, one of which bound the **wrong** version
+  silently into approval records, which is worse than no binding because the check still
+  returns a verdict.
+- `mindforge approve` died with ENOENT on any non-Node project. Absent values are now
+  recorded as `null` rather than invented.
+
+**Test infrastructure**
+
+- `tests/production.test.js` carried the uncommitted diff into its clone with
+  `git diff HEAD` (which includes staged files) but committed it with `commit -a` (which
+  stages only modified and deleted **tracked** files). So any commit **adding** a file
+  under `bin/` or `tests/` left the clone dirty and failed the gate's own cleanliness
+  assertion — reintroducing precisely the `--no-verify` pressure that carry exists to
+  avoid, for the one case it did not cover.
+
+### Added
+
+New regression gates, each falsified by reinstating the exact defect and confirming RED,
+with every touched file restored byte-exact afterwards:
+
+- `tests/hook-registration-ancestor.test.js` — six properties, the first of which asserts
+  the ancestor detector fires at all, so the other five cannot pass by never triggering.
+- `every shipped file is tracked in git` — property-based, no name list. It cannot fail on
+  a clean clone, which is how the real leak survived CI, so it is paired with a second
+  test that plants the runtime state in a throwaway clone and then packs.
+- `all three published packages publish with provenance` — counts the `npm publish`
+  invocations rather than matching one, because a single-match regex was satisfied by
+  either of the two packages that already had an attestation while the SDK had none. Also
+  asserts the SDK step is idempotent and ordered after the proven publishes.
+
+### Notes for operators
+
+- **These fixes change installer behaviour on almost every project.** After upgrading,
+  check `.mindforge/hook-registration.json` to see what was registered, and restart the
+  harness — hooks are snapshotted at session start.
+- A registered hook is only *live* if the harness has been restarted, the project is
+  trusted in the harness, and `CLAUDE_PROJECT_DIR` is set with `node` on the hook PATH.
+  None of those three are in MindForge's control; the last is a deliberate trade against a
+  fail-closed shell tail that was measured denying benign commands on a fresh clone.
+- Two gaps remain that require repository settings rather than code, and are recorded
+  rather than claimed fixed: there is no `v*` **tag ruleset** restricting who may create
+  the ref that triggers publishing, and `NPM_TOKEN` is a long-lived repository secret with
+  no GitHub environment in front of it.

package/docs/faq.md

@@ -1,4 +1,4 @@
-# MindForge FAQ (v11.9.3)
+# MindForge FAQ (v11.9.4)
 
 ## Is MindForge tied to Claude only?
 No. MindForge supports Claude Code and Antigravity. Install with `--claude`,
@@ -55,7 +55,7 @@ The `deep-research` workflow was removed before the v11.8.0 release (the superpo
 ## Version & Stability
 
 **Q: What version is current?**
-v11.9.3 — verify with `node bin/mindforge-cli.js --version`
+v11.9.4 — verify with `node bin/mindforge-cli.js --version`
 
 **Q: Is v11.9.0 production-stable?**
 Yes. The IQ200 deep-audit (258 discrete checks across 14 dimensions) shows 258/258 passing. 0 CVEs, 0 test failures, 0 ESLint errors, 0 TypeScript errors.
@@ -80,7 +80,7 @@ Spawn dispatch is not yet implemented in v11.9.0. Use `/mindforge:auto` or `/min
 Tier-3 trust uses in-process key simulation in v11.9.0 — this is intentional and safe. `SECURITY_TIER_3_SIMULATED = true` is the documented v11.x behavior. Hardware TPM/HSM is planned for v12.x.
 
 **Q: What is the test coverage?**
-133 test files: 131 pass, 0 failures, 2 env-dependent skips (`browser.test.js` needs a Chromium
+134 test files: 132 pass, 0 failures, 2 env-dependent skips (`browser.test.js` needs a Chromium
 daemon, `sre-integration.test.js` needs git worktree support and a clean tree).
 
 The enforced floor is **30% lines**, gated in CI by the `mindforge-quality` job

package/docs/getting-started.md

@@ -1,4 +1,4 @@
-# MindForge — Getting Started (v11.9.3)
+# MindForge — Getting Started (v11.9.4)
 
 This guide gets you from zero to a working MindForge project in under five minutes.
 
@@ -54,7 +54,13 @@ Run the MindForge MCP server (`mindforge-mcp-server`) over stdio — it exposes
 claude mcp add mindforge -- npx -y mindforge-mcp-server
 ```
 
-This server is also published to the [MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.sairam0424/mindforge` (currently `11.9.0`, marked latest).
+This server is also published to the [MCP Registry](https://registry.modelcontextprotocol.io) as
+`io.github.sairam0424/mindforge`. **The registry entry lags this package** — it is republished
+manually, so check what it actually serves before relying on it:
+`curl -s 'https://registry.modelcontextprotocol.io/v0/servers?search=io.github.sairam0424/mindforge'`.
+To pin a known version instead, install `mindforge-mcp-server` from npm directly. (The previous
+wording named a specific version and marked it latest; both were wrong in both directions, which
+is why this now describes how to check rather than asserting a number.)
 
 ### 4. Homebrew
 
@@ -108,7 +114,7 @@ Or use slash commands: `/mindforge:wf-code-audit`
 ## Your First 5 Minutes with MindForge
 
 1. **Verify install:** `node bin/mindforge-cli.js health`
-2. **Check version:** `node bin/mindforge-cli.js --version` (should print `11.9.3`)
+2. **Check version:** `node bin/mindforge-cli.js --version` (should print `11.9.4`)
 3. **List workflows:** `node bin/mindforge-cli.js workflow list`
 4. **Run first slash command:** Open Claude Code → `/mindforge:status`
 5. **Onboard your codebase:** Open Claude Code → `/mindforge:wf-onboard-codebase`

package/docs/sdk-reference.md

@@ -14,11 +14,11 @@ import {
 } from 'mindforge-sdk';
 ```
 
-Current SDK version: `11.9.3`
+Current SDK version: `11.9.4`
 
 ---
 
-## SDK Exports (v11.9.3)
+## SDK Exports (v11.9.4)
 
 ```javascript
 const {
@@ -28,7 +28,7 @@ const {
   commands,               // Command registry
   batch,                  // Batch execution
   MindForgeMemory,        // Memory interface
-  VERSION                 // '11.9.3'
+  VERSION                 // '11.9.4'
 } = require('mindforge-sdk');
 // or: import { MindForgeClient, VERSION } from 'mindforge-sdk';
 ```

package/docs/troubleshooting.md

@@ -1,4 +1,4 @@
-# MindForge Troubleshooting (v11.9.3)
+# MindForge Troubleshooting (v11.9.4)
 
 This page lists common issues and fast fixes. If you get stuck, start with
 `/mindforge:health`.
@@ -208,3 +208,58 @@ All tests must be run from the MindForge project root: `cd /path/to/MindForge &&
 **Symptom:** `--version` flag reports "Unknown command" on installs older than v11.9.0.
 
 **Fix:** Upgrade: `npx mindforge-cc@latest --claude --local`
+
+---
+
+## Hooks are installed but nothing is blocked
+
+**Symptom:** The hook scripts are present under `.claude/hooks/`, but a command that should be denied
+— say `git commit --no-verify` — runs normally.
+
+Hooks have two separate failure modes: **not registered** (no config names them) and **registered but
+not live** (the config exists, the harness has not applied it). Check them in that order.
+
+**1. Was registration attempted, and what did it decide?** The installer prints one line for every
+outcome, and writes a receipt:
+
+```
+cat .mindforge/hook-registration.json
+```
+
+`registered: false` there carries the reason. Registration is deliberately narrow: Claude Code only,
+`--local` only, non-Windows. A self-install inside a MindForge checkout also declines, because that
+repo maintains its own tracked config.
+
+**2. Restart the harness.** Claude Code snapshots hooks at session start, so a registration performed
+during an open session is not live in it. This is the single most common cause.
+
+**3. Confirm the project is trusted.** User-tier and project-tier settings are applied independently:
+`~/.claude/settings.json` is the user tier and applies to every session, while
+`<project>/.claude/settings.json` is the project tier and needs the project itself to be trusted.
+Measured on one machine: the user-tier hooks fired on every tool call while the project-tier hooks in
+the same session did not, and that project's entry in `~/.claude.json` had
+`hasTrustDialogAccepted: false`. Accept the trust prompt for the directory, then use `/hooks` to
+confirm the entries are listed.
+
+**4. Drive the hook directly** to separate "the hook is broken" from "the hook is not wired". This
+takes the harness out of the loop entirely — a deny-class hook must exit **2**:
+
+```bash
+echo '{"hook_event_name":"PreToolUse","tool_name":"Bash","cwd":"'"$PWD"'","tool_input":{"command":"git commit --no-verify -m x"}}' \
+  | node .claude/hooks/run-with-flags.js mindforge-block-no-verify .claude/hooks/mindforge-block-no-verify.js minimal,standard,strict
+echo "exit=$?"
+```
+
+Exit 2 with a `BLOCKED:` line on stderr means the hook works and the problem is registration or
+trust. Exit 0 with the payload echoed back means the dispatcher could not load the script — check
+that the second path exists under `.claude/hooks/`.
+
+**5. If you launch the harness somewhere else, install there too.** Project settings are read from the
+directory the harness starts in; they are **not** inherited from a parent directory. An ancestor
+project having its own `.claude/settings.json` does not make its hooks apply here, and does not stop
+these from applying — the installer warns when it sees one, and still registers.
+
+**Known residual:** if `CLAUDE_PROJECT_DIR` is unset, or `node` is not on the hook PATH, the
+registered commands exit 1 and the gate is simply absent — the same position as not installing. This
+is a deliberate trade: a fail-closed shell tail was measured denying benign commands on a fresh
+clone.

package/docs/user-guide.md

@@ -1,8 +1,8 @@
-# MindForge User Guide (v11.9.3)
+# MindForge User Guide (v11.9.4)
 
 This guide gets you from install to productive, with the minimum needed to run MindForge in a real project.
 
-> **v11.9.3 Stats:** 35 workflows · 221 slash commands · 232 engine skills · 216 personas · 0 CVEs · 258/258 IQ200 checks passing
+> **v11.9.4 Stats:** 35 workflows · 221 slash commands · 232 engine skills · 216 personas · 0 CVEs · 258/258 IQ200 checks passing
 
 ## Prerequisites
 
@@ -44,7 +44,7 @@ mindforge health          # Verify project integrity
 mindforge security-scan   # Run security checks
 mindforge headless        # Run agent in non-interactive mode
 mindforge --verbose ...   # Enable verbose output for debugging
-mindforge --version       # Print installed version (e.g. 11.9.3) and exit 0
+mindforge --version       # Print installed version (e.g. 11.9.4) and exit 0
 ```
 
 Use `--verbose` (or `-v`) on any command for detailed diagnostic output. Use `--version` (or `-V`) to print the installed version and exit.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindforge-cc",
-  "version": "11.9.3",
+  "version": "11.9.4",
   "description": "MindForge — Sovereign Agentic Intelligence Framework. Sovereign Stability: Production-Hardened Agentic Intelligence (v11)",
   "bin": {
     "mindforge-cc": "bin/install.js",
@@ -29,6 +29,7 @@
     ".mindforge/intelligence/",
     ".mindforge/memory/",
     "!.mindforge/memory/pattern-library.jsonl",
+    "!.mindforge/memory/sync-manifest.json",
     ".mindforge/metrics/",
     "!.mindforge/metrics/token-usage.jsonl",
     ".mindforge/models/",

package/.mindforge/memory/sync-manifest.json

@@ -1,6 +0,0 @@
-{
-  "pattern-library.jsonl": {
-    "lastSync": "2026-08-21T12:02:25.078Z",
-    "localCount": 1
-  }
-}