mindforge-cc 11.9.3 → 11.9.5

package/.mindforge/config.json

@@ -1,5 +1,5 @@
 {
-  "version": "11.9.3",
+  "version": "11.9.5",
   "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,285 @@
 # Changelog
 
+## [11.9.5] — 2026-08-22 — The release path can no longer strand itself, and the SDK ships
+
+Patch release, and the shortest one in a while. It exists because 11.9.4 published two
+packages and then failed on the third, and that failure took the release page and the
+`stable` dist-tag with it. Both causes are fixed here, and one of them is the reason this
+release is worth cutting rather than waiting: **`mindforge-sdk` publishes for the first
+time in seven versions, with provenance.**
+
+### Fixed
+
+**A publish that cannot finish the release it started**
+
+- **`sdk/package.json` had no `repository` field.** npm's provenance verification compares
+  that field against the attestation **server-side, at PUT** — so the publish was rejected
+  with `422 Unprocessable Entity … "repository.url" is ""` *after* `mindforge-cc` and
+  `mindforge-mcp-server` had already published irreversibly. `npm publish --dry-run` does
+  not perform that comparison, and nothing in this repository read `repository` at all: all
+  six preflight gates passed on a manifest the registry was guaranteed to reject. The field
+  is added, matching the spelling the other two packages use.
+
+- **`scripts/ci/verify-provenance-metadata.js` makes that failure reachable before the
+  point of no return.** It runs in the release **preflight** job, ahead of every publish,
+  and it does not carry a list of packages: it discovers them from the workflow — every
+  step whose `run` contains both `npm publish` and `--provenance`, resolved through its
+  `working-directory` — so a fourth package is covered without editing the gate.
+  Discovering zero targets is a hard failure rather than a pass, on the principle that a
+  check which examined nothing must not report success.
+
+  Verified the only way that means anything: run against a git worktree at tag `v11.9.4` —
+  the exact tree that the registry rejected — it exits 1 and names `sdk/package.json` and
+  the missing field. It would have stopped that release before anything reached npm.
+
+- **The release steps were ordered so that an optional package could strand the release.**
+  The SDK publish sat *before* `Create GitHub Release` and the `stable` dist-tag move.
+  A failing step fails the job, so both were skipped — which is precisely the harm the
+  placement comment claimed to prevent. The same mode had already fired on **v11.5.1** and
+  **v11.8.3** from the MCP publish; v11.9.4 was its third occurrence.
+
+  Reordered to: `Publish to npm` → `Create GitHub Release` → `stable` dist-tag →
+  `mcp-server` → `sdk`. The rule now encoded in `tests/action-pinning.test.js`: **no step
+  whose failure leaves no residue may be able to skip a step that finishes an irreversible
+  one.** That test previously asserted the opposite and had to be inverted in the same
+  commit — because `Run Full Test Suite` is the release job's first step, a reorder shipped
+  alone would have failed the release at its own gate.
+
+  The two finishers carry guards on their own inputs rather than a bare `!cancelled()`,
+  which would publish a release with a 0-byte body and an unmatched `.tgz` glob when
+  `Build Package` fails — the `bodyBytes=0` defect already seen on v11.9.0, .1 and .2. And
+  deliberately not `continue-on-error`: a tolerated failure makes the run conclude
+  **green**, which is the blindness that let the SDK sit seven versions behind, unattested,
+  with nothing noticing.
+
+**Prose surfaces that shipped stale twice running**
+
+- `bin/utils/readiness-gate.js` scored `RELEASENOTES.md` on `fileExists` while its
+  changelog sibling three lines away checked that the version appeared *in* the file. That
+  asymmetry is why the immutable 11.9.3 tarball's README said "Latest release v11.9.2" and
+  the immutable 11.9.4 tarball shipped with no 11.9.4 entry at all — while `README.md`
+  offers that file as the human-readable route to the BREAKING notes. Both are now checked,
+  anchored rather than by substring (`includes('11.9.4')` is also satisfied by
+  `## v11.9.40`).
+
+  **Policy change, stated plainly:** every release from here needs a `RELEASENOTES.md`
+  entry. Six published 11.x versions do not have one, so that file has been curated rather
+  than exhaustive; the gate only ever looks for the version being released, so those gaps
+  are unaffected.
+
+- README's `## Latest release` is deliberately gated by a **test** rather than written by
+  `sync-version.js`. Auto-bumping the version token onto the previous release's paragraph
+  produces the right number attached to the wrong description — a better-disguised
+  falsehood than a visibly stale one.
+
+- `docs/sdk-reference.md` offered `npx mindforge-cc@stable` as a way to get the SDK
+  "as part of the framework". Measured false: the published package declares exactly
+  `express` and `sql.js` and ships no `sdk/` directory. Removed.
+
+### Added
+
+- **`mindforge-sdk` is published, with provenance** — its first release since 11.8.0 and
+  its first ever attested one. This is not cosmetic. Everything fixed in the SDK across
+  11.8.1–11.9.4 reached nobody, including the one that matters most:
+  `WebSocketEventStream` scheduled a reconnect with `setTimeout(() => this.connect(), …)`
+  and nothing handled the returned promise, so a failed reconnect was an unhandled
+  rejection — fatal under Node's default mode, **terminating the caller's process**. Every
+  consumer on 11.8.0 still has that. (#191)
+
+- `npm run provenance:check` — the gate above, runnable offline.
+
+### Notes for operators
+
+- 11.9.4 is complete but was finished by hand: its GitHub Release was created at the
+  existing tag from the registry's own tarball (verified against `dist.integrity` and both
+  attestation bundles' subject digests), and the `v11.9.4` tag was deliberately **not**
+  moved, because two published packages' provenance attests to the commit it names.
+- The `stable` dist-tag lagged at 11.9.3 between the two releases. Because the dist-tag
+  step now runs *ahead* of both additive publishes, this release moves it forward even if a
+  package publish fails again.
+- Still outstanding, and requiring repository settings rather than code: there is no `v*`
+  **tag ruleset** restricting who may create the ref that triggers publishing, and
+  `NPM_TOKEN` remains a long-lived repository secret with no GitHub environment in front of
+  it. Create the environment *first* — adding `environment:` while none exists publishes
+  exactly as before while looking like a gate.
+
+## [11.9.4] — 2026-08-22 — Delivery: the gates register, the tarball matches its tag
+
+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` was NOT published in this release. It remains at 11.8.0.** This entry
+  originally claimed it shipped with provenance; that claim was false and is corrected here
+  rather than quietly deleted, because a release arguing for measured claims does not get to
+  misstate a supply-chain property.
+
+  What happened: the SDK 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**. A publish step was added for it, and the registry rejected it:
+
+  ```
+  npm error 422 Unprocessable Entity - PUT https://registry.npmjs.org/mindforge-sdk
+    Error verifying sigstore provenance bundle: Failed to validate repository information:
+    package.json: "repository.url" is "", expected to match
+    "https://github.com/sairam0424/MindForge" from provenance
+  ```
+
+  `sdk/package.json` carried no `repository` field. The other two packages both do, which is
+  exactly why they published and it did not. That field is validated **registry-side at PUT**,
+  after two irreversible publishes have already succeeded — `npm publish --dry-run` does not
+  check it and neither did any gate here. Both are fixed for 11.9.5: the field, and an offline
+  preflight gate that refuses to reach a publish without it.
+
+  The step was also badly placed. It ran **before** `Create GitHub Release` and the `stable`
+  dist-tag move, so its failure skipped both — which is the precise harm the placement comment
+  claimed to prevent. `mindforge-cc@11.9.4` and `mindforge-mcp-server@11.9.4` published
+  correctly with provenance attesting commit 353e8d41; the release page and the `stable` tag
+  were completed by hand afterwards. The finishing steps now run ahead of the additive
+  publishes, so no optional package can strand a release again.
+
+- **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 +292,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 +401,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 +430,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.5)
 
 ## 1. IDENTITY & VERSIONING
 
 [NAME]    = MindForge
-[VERSION] = 11.9.3
+[VERSION] = 11.9.5
 [STABLE]  = true
 [MODE]    = "Platform Sovereign"
 [REQUIRED_CORE_VERSION] = 11.9.1

package/README.md

@@ -6,11 +6,24 @@
 
 ## 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.5** (2026-08-22) — The release path can no longer strand itself, and the SDK ships.
+11.9.4 published two packages and then failed on the third; because that step sat *before* the
+release page and the `stable` dist-tag move, its failure skipped both. Fixed two ways: the steps
+that finish a release now run ahead of any additive package publish, and a new offline preflight
+gate refuses to reach a publish that the registry will reject. Verified against a worktree at tag
+`v11.9.4` — the exact tree npm rejected — the gate exits 1 and names the file.
+
+**`mindforge-sdk` publishes for the first time since 11.8.0, and for the first time with
+provenance.** Everything fixed in it across 11.8.1–11.9.4 had reached nobody, including a
+`WebSocketEventStream` reconnect whose unhandled rejection **terminates the caller's process**.
+
+The previous release, **v11.9.4**, is where the hook gates started actually registering: 11.9.3
+shipped the code and then declined to run it on essentially every project. Measured against the
+published tarballs — 11.9.3: **11 hook scripts installed, 0 registered**; 11.9.4: **8 registered,
+3 deny-class verified blocking**. That **behaviour change under a patch bump** still applies — the
+installer writes `.claude/settings.json` where it previously declined, merging append-only and
+backing up first. See the BREAKING section in [CHANGELOG.md](./CHANGELOG.md), or
+[RELEASENOTES.md](./RELEASENOTES.md) for human-readable notes.
 
 ---
 
@@ -19,7 +32,9 @@ 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.** 11.9.3 added the registration code
+but it declined to run on almost every project, so in practice nothing was enforced there either.
+**As of 11.9.4** both channels register and execute them **on Claude Code**, and nowhere else.
 
 | Capability | Plugin channel | `npx` channel |
 |---|---|---|
@@ -27,34 +42,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