mindforge-cc 11.9.2 → 11.9.4

package/CHANGELOG.md

@@ -1,5 +1,362 @@
 # 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
+same defect: **an instrument reported success while doing nothing.** Gates that could
+not fail, tests satisfied by a comment, docs describing capabilities with no code
+behind them, commands printing success while performing no action, and a publish path
+that no check ever touched.
+
+Contains behaviour changes under a patch bump — several of the things being fixed were
+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.
+
+- **Routed CLI commands now act on YOUR project, not MindForge's own checkout.**
+  `bin/mindforge-cli.js` passed `cwd: ROOT` to every routed command, so `mindforge
+  classify` diffed MindForge's repository instead of yours, and `mindforge health`
+  inspected MindForge's `node_modules`. Measured across all 27 routed commands: 7
+  changed behaviour, all in the correct direction, none regressed. If you parsed output
+  that happened to describe MindForge itself, it now describes your project. (#201)
+
+- **`npx mindforge-cc install` — and any other positional argument — now exits 1.**
+  The installer takes flags only and silently ignored stray words, so
+  `npx mindforge-cc install` appeared to work while installing nothing configured.
+  It now refuses with the correct form. `--runtime`'s value token is still accepted.
+  Use `npx mindforge-cc --claude --local`. (#202)
+
+- **`mindforge verify` now SKIPS unavailable stages instead of failing them.** A project
+  with no ESLint config, no test script or no `bin/verify-audit.js` was reported as
+  FAILING those stages rather than as not having them. If your CI relied on a non-zero
+  exit in those cases, it will now pass. A run in which every stage skipped prints a
+  "NOTHING WAS VERIFIED" banner rather than a clean bill of health. (#204)
+
+- **`scripts/sync-version.js` now exits non-zero when the plugin build artifacts are
+  stale.** A bump used to report `✅ every derivable channel is at <version>` and exit 0
+  while leaving `npm test` red. If you script this, handle the new exit code — it means
+  "run the build chain it just printed". (#211)
+
+- **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/**`.
+  The skip is now honoured for local scope. (#200)
+
+- **Releases must be tagged on a commit reachable from `main`.** The release workflow
+  now refuses a tag that is not an ancestor of `origin/main`. The documented flow is
+  develop → release → main; tagging elsewhere previously published, with provenance
+  attesting to that tree. (#216)
+
+### Fixed
+
+**Installer**
+
+- A self-install claimed to skip and then overwrote 149 tracked files. The gate is now
+  scope-aware (`isSelfInstall() && scope === 'local'`). (#200)
+- Every `--global` install reported failure on a correct run: `verifyInstall` demanded
+  six `bin/**` paths regardless of scope, so a global install ended
+  `❌ 6 of 12 required file(s) missing` and exit 1, with a `--force` retry that could
+  not help. A global install writes 389 files to `$HOME/.claude` and, deliberately,
+  zero to `bin/`. (#210)
+- 11 of 27 routed CLI verbs died on `MODULE_NOT_FOUND` in a real install: the router
+  shipped but 6 of the scripts it dispatches to did not. `coreFiles` grew from 2 entries
+  to 8. (#210)
+- Two leaks: `/tmp` staging files left behind on abandoned runs, and developer runtime
+  state (`celestial.db`, `.browser-daemon-token`) copied into consumer projects.
+  `SENSITIVE_EXCLUDE` now covers both. (#210)
+- The forge commands overwrote three `mindforge` commands of the same name. (#197)
+- The documented default install did not deliver the CLI it documents. (#196)
+
+**Versioning and release**
+
+- `sync-version.js --fetch-sha` hashed npm's 404 error body. For an unpublished version
+  the registry answers `{"error":"Not found"}` and `curl -sL` exits 0, so the digest
+  written into the Homebrew formula was the SHA-256 of that error text — the same
+  constant for every unpublished version — and `--check` then passed. Now `curl -fsSL`
+  plus a gzip magic-byte check, and it refuses rather than writing a digest no artifact
+  can match. (#203)
+- The Homebrew formula may now LAG canonical but never LEAD it. Requiring equality
+  before publishing required something impossible: the digest is the hash of a tarball
+  that does not exist yet, and `npm test` blocked the publish that would have made it
+  satisfiable. (#208)
+- Semver comparison is numeric per component. Lexicographically, `11.10.0` reads as
+  *behind* `11.9.2` — wrong on exactly the first release past a `.9` minor. (#208)
+- Three version channels had no writer at all, so `npm test` failed on every bump and
+  the documented remedy could not fix it: `mcp-server/server.json` (both keys, matched
+  by identifier), `AGENTS.md`, and `sdk/README.md`'s second shape. (#207, #211)
+- **No 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
+  getting-started, faq, troubleshooting, user-guide and sdk-reference all titled
+  themselves v11.9.0: three releases stale, while every npm manifest was correct.
+  `--check` was green throughout, because a channel that does not exist cannot drift.
+  Structural markers now track canonical; narrative measurements deliberately do not.
+  (#211)
+- A bump is not finished when `sync-version.js` exits. Two tracked artifacts are gated
+  against `package.json` and only a build can write them —
+  `plugins/mindforge/.claude-plugin/plugin.json` and
+  `plugins/mindforge/mcp/dist/index.js`. They are now reported under
+  `🔨 REQUIRE A BUILD` with the exact three-command chain, which nothing had documented.
+  (#211)
+- `sync-version.js` reported "a channel is AHEAD of canonical" whenever its exit code
+  was non-zero for any reason, so the `--fetch-sha` refusal for an unpublished tarball
+  claimed the formula LEADS canonical in the same run that printed "DEFERRED until after
+  publish (behind, not ahead)". (#211)
+- `changelogs/index.json`, which `bin/updater/changelog-fetcher.js` reads as the
+  authoritative version list, was missing 11.9.2. (#218)
+
+**Publishing**
+
+- **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. A `preflight` job now gates it. (#216)
+- 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 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
+  `node <anything>/dashboard/server.js` — verified against
+  `node /var/www/unrelated_app/dashboard/server.js`. It now resolves the script's
+  realpath and compares it to its own. (#206)
+- `--status` printed a port it could not know: the PID file records only the pid, so it
+  reported whatever port that invocation happened to receive. Measured, `--status` on a
+  server started with `--port 7466` printed "port 7339". (#206)
+
+**Memory**
+
+- Every abandoned exit left a full copy of the database on disk — 1.8 GB of orphaned
+  `.tmp` files. (#199)
+- The SDK's WebSocket client took the caller's process down on a failed reconnect. (#191)
+
+**Verification**
+
+- `mindforge verify`'s lint stage used `--max-warnings=0`, which made it impossible to
+  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
+  `TemporalHub.gc({maxSnapshots: 50, maxAgeDays: 30})` with `--dry-run` and honest
+  counts, including zero. (#209)
+
+**Documentation that named things that do not exist**
+
+- The protocol files instructed the agent to run `soul-engine.js` and
+  `shard-controller.js`, neither of which exists anywhere in the package. Those steps
+  are reasoning protocols and now say so. (#205)
+- Fifteen phantom `/mindforge:` slash commands in shipped docs. A reader following
+  `docs/user-guide.md` typed `/mindforge:personas --list` and got nothing. They were not
+  typos: `.agent/workflows/` holds 130 tracked files using those exact names — an old
+  target layout, committed and orphaned, shipping zero files. (#209)
+- Four documented CLI invocations could not be run, each verified by running it:
+  `npx mindforge-cc@latest install` (exit 1), `mindforge-cli.js dashboard` (exit 1),
+  `npx mindforge auto` in a shipped engine doc (`auto` is a slash command, never a CLI
+  verb), and `@mindforge <verb>`, a syntax that exists nowhere. (#213)
+- `workflow` is the most-documented CLI verb in the project and works, but appeared in
+  neither `--help` nor the "Available commands" list, so a user who mistyped it was told
+  it does not exist. (#213)
+- Root `CLAUDE.md` named `bin/hooks/mindforge-context-monitor.js`; the file is under
+  `.agent/hooks/`. (#214)
+
+### Added
+
+- **`preflight` job on the release workflow.** Asserts the tagged commit is an ancestor
+  of `origin/main`, then runs the six gates a tag push never saw, with the publish job
+  behind `needs:`. (#216)
+- **Automatic `stable` dist-tag movement**, forward-only and verified. (#216)
+- **`node bin/dashboard/server.js --status` / `--stop`.** Not CLI verbs —
+  `mindforge-cli.js dashboard` does not route. (#206)
+- **`mindforge temporal cleanup --dry-run`.** (#209)
+- New regression gates, each falsified by mutation before being trusted:
+  `tests/protocol-claims.test.js` (no exemption list, deliberately — a name-keyed
+  allowlist was shown to excuse the exact defect it was written for), the shipped-doc
+  phantom-command gate, the CLI-verb gate, the authority-doc `.js` gate, the
+  version-channel round trips, and assertions that the release preflight itself cannot
+  be silently removed.
+
+### Notes for operators
+
+- `npm run version:check` is the offline drift check. A bump is finished only when
+  `sync-version.js` exits 0 — if it prints `🔨 REQUIRE A BUILD`, run the three commands
+  it names and commit both regenerated files.
+- Releases are now gated on being tagged from `main`. One residual, inherent to
+  tag-triggered workflows: a tag push resolves the workflow from the TAGGED ref, so a
+  tag placed on a commit predating this release runs that commit's workflow and is
+  ungated.
+
 ## [11.9.2] — 2026-08-16 — Correctness: audit-chain integrity, dashboard crash policy, secret scanning
 
 Patch release. No new features. Correctness work closing defects found by a

package/MINDFORGE.md

@@ -1,9 +1,9 @@
-# MINDFORGE.md — Parameter Registry (v11.9.2)
+# MINDFORGE.md — Parameter Registry (v11.9.4)
 
 ## 1. IDENTITY & VERSIONING
 
 [NAME]    = MindForge
-[VERSION] = 11.9.2
+[VERSION] = 11.9.4
 [STABLE]  = true
 [MODE]    = "Platform Sovereign"
 [REQUIRED_CORE_VERSION] = 11.9.1
@@ -98,8 +98,15 @@
 The following parameters cannot be overridden by plugins, agents, or session-level configuration:
 
 - [MIN_SOUL_SCORE] — Minimum SOUL score required for architectural changes
-- [BLOCK_ON_SECURITY] — Security gate enforcement cannot be disabled
-- [COST_HARD_LIMIT_USD] — declared here, but **NOT enforced as of 11.9.2**; do not rely on it as a spend control. `bin/models/cost-tracker.js` reads `MODEL_COST_HARD_LIMIT_USD`, a key this registry does not declare, so `preflight()` returns early and no cap is ever applied. Wiring it is tracked as COST-02 for 11.9.3
+- [BLOCK_ON_SECURITY] — DECLARED, UNREAD. `git grep -l BLOCK_ON_SECURITY -- bin/` returns nothing:
+  no code reads this key, so it changes no behaviour and deleting it fails no validation (the schema
+  lists it as `recommended`, not `required`). What actually blocks a config-weakening edit is the
+  `mindforge-config-protection` hook, which is deny-class and fails closed — see SECURITY.md.
+- [COST_HARD_LIMIT_USD] — **enforced as of 11.9.3** (COST-02). `bin/models/cost-tracker.js` `preflight()` reads this key, adds the call estimate to today's ledger spend, and throws `COST_LIMIT_REACHED`; `bin/models/model-client.js` re-throws it, so the model call is refused. Non-overridable means a plugin or session cannot raise the number — it does not mean a cap always exists: `0`, or the key being absent, legally disables the cap, because an upgrade never rewrites an existing MINDFORGE.md (`bin/installer-core.js:706`) and the schema lists this key as `recommended`, not `required`. A present-but-unreadable value (e.g. `= none`) is a hard config fault — `preflight()` throws `COST_LIMIT_MISCONFIGURED` instead of running uncapped
 - [BLOCK_ON_SECURITY] is non-overridable; PQAS itself is simulated/experimental (inactive by default) and is NOT a non-overridable guarantee — do not rely on it as an enforced control
-- [SOVEREIGN_IDENTITY] — Identity verification is always required
-- [ENABLE_ZTAI] — Zero-trust identity cannot be bypassed
+- [SOVEREIGN_IDENTITY] — DECLARED, UNREAD. No reader in `bin/`. No identity is verified as a result
+  of this key being set.
+- [ENABLE_ZTAI] — DECLARED, UNREAD, and the feature it gates is inactive. No reader in `bin/`;
+  measured on a live 3116-entry AUDIT.jsonl, 0 entries carry a `signature` or `did`. "Cannot be
+  bypassed" overstates a switch that is not wired to anything — see docs/security/ZTAI-OVERVIEW.md,
+  which now leads with a status banner.

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 47
-  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
@@ -72,8 +90,9 @@ All install channels (global, local, Antigravity, Cursor, Copilot, Gemini CLI, M
 **Upgrading from 11.9.x?** The installer does not overwrite an existing
 `.mindforge/MINDFORGE-SCHEMA.json`, so 11.9.2's armed config validator keeps the older
 permissive schema on a plain upgrade. Run with `--force` if you want the stricter gate. The
-daily cost cap declared as `[COST_HARD_LIMIT_USD]` in `MINDFORGE.md` is **not enforced** in
-11.9.2 — see the CHANGELOG.
+daily cost cap declared as `[COST_HARD_LIMIT_USD]` in `MINDFORGE.md` was **not enforced** in
+11.9.2; 11.9.3 arms it. An upgrade never rewrites an existing `MINDFORGE.md`, so if yours
+predates the key the cap stays off — add `[COST_HARD_LIMIT_USD] = 25.00` to turn it on.
 
 ---
 

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
@@ -622,7 +685,7 @@ You must address these before upgrading from v9.x:
 |--------|--------|-----------|
 | `better-sqlite3` removed, replaced by `sql.js` | If you imported or extended VectorHub internals, the constructor API has changed | Use `createVectorHub()` factory function instead of `new VectorHub()` |
 | VectorHub uses FTS4 (not FTS5) | FTS5-specific syntax (e.g., `BM25`) no longer available | Use standard FTS4 `MATCH` queries; ranking is handled internally |
-| SDK `memory.ts` rewritten | If you imported memory utilities from `../../bin/` paths, those imports no longer resolve | Import from `@mindforge/sdk` directly — all public APIs are re-exported |
+| SDK `memory.ts` rewritten | If you imported memory utilities from `../../bin/` paths, those imports no longer resolve | Import from `mindforge-sdk` directly — all public APIs are re-exported |
 | Dashboard endpoints require auth | Unauthenticated requests to `/api/steering`, `/api/approve`, and SSE mutators now return 401 | Set `MINDFORGE_DASHBOARD_TOKEN` env var; pass as `Authorization: Bearer <token>` |
 | `sync-jira` / `sync-confluence` CLI routes removed | These were stubs with no implementation | Remove any scripts that invoke these commands |
 | Prompt injection blocklist removed | The regex-based `BLOCKED_PATTERNS` array no longer exists | Use the structured action allowlist in `bin/governance/action-allowlist.js` |
@@ -714,7 +777,7 @@ The database file format is compatible. No data migration is required.
 import { MemoryStore } from '../../bin/memory/store';
 
 // After (v10) — public SDK exports
-import { MemoryStore } from '@mindforge/sdk';
+import { MemoryStore } from 'mindforge-sdk';
 ```
 
 ### Step 5: Remove references to deleted commands