mindforge-cc 11.9.8 → 11.9.9

package/README.md

@@ -1,12 +1,22 @@
 # MindForge
 
-[![npm version](https://img.shields.io/npm/v/mindforge-cc.svg)](https://www.npmjs.com/package/mindforge-cc)
+[![npm version](https://img.shields.io/npm/v/mindforge-cc.svg?style=for-the-badge)](https://www.npmjs.com/package/mindforge-cc)
+[![CI](https://img.shields.io/github/actions/workflow/status/sairam0424/MindForge/mindforge-ci.yml?style=for-the-badge&label=CI)](https://github.com/sairam0424/MindForge/actions/workflows/mindforge-ci.yml)
+[![audit chain: verified](https://img.shields.io/badge/audit%20chain-verified-brightgreen?style=for-the-badge)](#what-is-actually-enforced)
+
 [![npm downloads](https://img.shields.io/npm/dm/mindforge-cc.svg)](https://www.npmjs.com/package/mindforge-cc)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Node >=18](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](package.json)
-[![CI](https://github.com/sairam0424/MindForge/actions/workflows/mindforge-ci.yml/badge.svg)](https://github.com/sairam0424/MindForge/actions/workflows/mindforge-ci.yml)
 
-**A governance and orchestration layer for Claude Code.**
+![Claude Code](https://img.shields.io/badge/Claude_Code-supported-blueviolet)
+![Antigravity](https://img.shields.io/badge/Antigravity-supported-blueviolet)
+![Cursor](https://img.shields.io/badge/Cursor-supported-blueviolet)
+![Copilot](https://img.shields.io/badge/Copilot-supported-blueviolet)
+![Gemini CLI](https://img.shields.io/badge/Gemini_CLI-supported-blueviolet)
+![OpenCode](https://img.shields.io/badge/OpenCode-supported-blueviolet)
+
+**A governance and orchestration layer for Claude Code** (and Antigravity, Cursor, Copilot,
+Gemini, OpenCode).
 
 Claude Code alone runs one agent in one context. MindForge adds the parts that don't fit in a
 single context window: skills that auto-load by trigger, personas you can call by name, a
@@ -15,11 +25,9 @@ tamper-evident audit chain, and cost-aware routing across providers. Install it
 `/mindforge:plan-phase` → `/mindforge:execute-phase` → `/mindforge:verify-phase` → `/mindforge:ship`
 as your actual working loop, not a slogan.
 
-<!-- TODO: record a ~30s terminal cast of one real /mindforge:plan-phase -> /mindforge:execute-phase
-     run (asciinema or GIF) and embed it here. Every comparable README in this space leads with a
-     visual in the first 15 lines; this is currently the single biggest gap. -->
+221 commands · 354 skills · 216 personas · 164 subagents · 35 workflows
 
-**Jump to:** [Latest release](#latest-release) · [What you get](#what-you-get) · [What is actually enforced](#what-is-actually-enforced) · [Install](#install) · [Quick start](#quick-start-new-project) · [Documentation](#documentation) · [Core workflow](#core-workflow) · [Dynamic workflows](#dynamic-workflow-library)
+**Jump to:** [Latest release](#latest-release) · [What you get](#what-you-get) · [What is actually enforced](#what-is-actually-enforced) · [Install](#install) · [Verify](#verify) · [Quick start (new)](#quick-start-new-project) · [Quick start (existing)](#quick-start-existing-codebase) · [How it fits together](#how-it-fits-together) · [Documentation](#documentation) · [Core workflow](#core-workflow) · [Dynamic workflows](#dynamic-workflow-library) · [Updates](#updates-and-migrations) · [Token usage](#token-usage-profiling) · [License](#license)
 
 ---
 
@@ -28,11 +36,12 @@ as your actual working loop, not a slogan.
 | | Capability | Detail |
 |---|---|---|
 | 🧩 | **221 slash commands** | `/mindforge:plan-phase`, `/mindforge:execute-phase`, `/mindforge:ship`, and 218 more — [full reference](docs/commands-reference.md) |
-| 🛠️ | **355 skills** | 232 auto-triggered by keyword match (engine tier) + 123 explicit, invoked by name (extended tier) |
+| 🛠️ | **354 skills** | 232 auto-triggered by keyword match (engine tier) + 122 explicit, invoked by name (extended tier) |
 | 🎭 | **216 personas** | In-session role overlays via `/mindforge:agent <name>` — same context, different behavioral spec |
-| 🤖 | **164 subagents** | Genuine isolated-context Claude-Code-native subagent definitions — a separate mechanism from personas, see [docs/PERSONAS.md](docs/PERSONAS.md) |
+| 🤖 | **164 subagents** | Genuine isolated-context Claude-Code-native subagent definitions — a separate mechanism from personas, see [docs/PERSONAS.md](docs/PERSONAS.md); 152 adapted from [VoltAgent's `awesome-claude-code-subagents`](https://github.com/VoltAgent/awesome-claude-code-subagents) (MIT), attribution in [subagents/README.md](subagents/README.md) |
 | 🔀 | **35 dynamic workflows** | Multi-agent fan-out scripts across 5 tiers (Research, Dev, Ops, Intelligence, Beast) — [workflow atlas](docs/workflow-atlas.md) |
 | 🔒 | **Tamper-evident audit chain** | SHA-256 hash-linked `.planning/AUDIT.jsonl`; verify independently with `node bin/verify-audit.js` |
+| 🔍 | **Multi-model cross-review + decision council** | Two-model adversarial PR review (`/mindforge:pr-review`) and a 4-voice consensus council (`/mindforge:council`) — `bin/review/`, `bin/engine/council-runtime.js` |
 | 💸 | **Cost-aware model routing** | Anthropic / OpenAI / Gemini / Bedrock / Ollama, routed by task difficulty tier |
 | 🧠 | **Local-first knowledge graph** | Zero-native-dependency SQLite (`sql.js` / WASM) — no native build step |
 | 📊 | **Live dashboard** | Express + SSE at `localhost:7339` |
@@ -42,10 +51,69 @@ entry, and an MCP server.
 
 ---
 
+## What is actually enforced
+
+Read this before you rely on anything below blocking a bad command. 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. 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 |
+|---|---|---|
+| Slash commands | Yes | Yes |
+| Skills / personas / protocol docs | Yes | Yes |
+| Subagents | Yes | Yes |
+| Audit hash-chain (`bin/verify-audit.js`) | Yes | Yes |
+| **Hooks enforced (can block a tool call)** | **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 52 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`.
+
+> [!WARNING]
+> 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
 
 Pick whichever matches how you work — all of these are real, live channels.
 
+On a typical connection, `npx mindforge-cc@latest --claude --local` finishes in well under 10
+seconds (measured: ~5.4s locally) — reproduce with `time npx mindforge-cc@latest --claude --local`
+in an empty directory. Install makes zero model calls; you don't spend a token or a dollar until
+you run a command that dispatches to a subagent.
+
 ### `npx` (recommended)
 
 Writes `.mindforge/` governance, memory, and planning into your project:
@@ -119,12 +187,13 @@ Build on MindForge programmatically:
 npm i mindforge-sdk
 ```
 
-**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` for the stricter gate. The daily cost
-cap declared as `[COST_HARD_LIMIT_USD]` in `MINDFORGE.md` was **not enforced** in 11.9.2 (11.9.3
-arms it), and an upgrade never rewrites an existing `MINDFORGE.md` — add
-`[COST_HARD_LIMIT_USD] = 25.00` yourself if yours predates the key.
+> [!NOTE]
+> **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` for the stricter gate. The daily cost
+> cap declared as `[COST_HARD_LIMIT_USD]` in `MINDFORGE.md` was **not enforced** in 11.9.2 (11.9.3
+> arms it), and an upgrade never rewrites an existing `MINDFORGE.md` — add
+> `[COST_HARD_LIMIT_USD] = 25.00` yourself if yours predates the key.
 
 Full install matrix, plugin packs, and team-setup guidance: [docs/getting-started.md](docs/getting-started.md).
 
@@ -170,20 +239,33 @@ Full verification walkthrough: [docs/quick-verify.md](docs/quick-verify.md).
 
 ## Latest release
 
-**v11.9.8** (2026-09-21) — What the README claims, verified line by line. v11.9.7's README
-rewrite got a literal, end-to-end audit: every command it documents actually run — real
-`npx` installs, a real Homebrew install/uninstall cycle, a real `npm i mindforge-sdk`, live
-registry checks — instead of re-read for plausibility. 113 claims checked, 98 held up, 14
-didn't, 1 couldn't be verified either way. Two of the 14 were real bugs:
-`--runtime claude,cursor` crashed the installer outright, and `--minimal` claimed "no
-persona library" but shipped all 216 anyway. Both fixed. The other twelve were
-documentation catching up to what the code actually does — a removed `[--ads]` hint that
-was never real, the auto-detect claim, `--repair`, `--profile`, the CLI `spawn` stub, the
-License holder, the skill-tier split, the `bin/` line count, three Documentation-table rows
-that overstated their linked docs, and the `mindforge-plugin-*` namespace's empty catalog.
-See [RELEASENOTES.md](./RELEASENOTES.md) or [CHANGELOG.md](./CHANGELOG.md).
-
-The previous release, **v11.9.7**, fixed a version self-contradiction and a false "Enabled"
+**v11.9.9** (2026-09-23) — Release-readiness audit: 5 CRITICAL + 9 HIGH findings fixed. An
+8-agent audit workflow tested every surface (commands, skills, personas, subagents,
+dynamic workflows, CLI/MCP, live install/verify/health) as a release gate before pointing
+real external users at the project. Every finding was independently re-verified against
+live code before fixing, not trusted from the audit report alone. Five were ship-blocking:
+a real LLM jailbreak toolkit (`godmode`) shipping unconditionally in the package is gone;
+`help.md`/`status.md`/`health.md`/`security-scan.md` stop claiming PQAS/biometric/
+lattice-crypto verification is "active by default" when the code says the opposite;
+`--minimal` now actually skips the persona set instead of shipping all 218 files anyway; a
+"Sovereign Integrity Check" that called a CLI flag on a script with no CLI entrypoint (and
+so could never fail) is replaced with a real check; and a dead 4-line stub standing in for
+"232 auto-triggered skills" is now disclosed as what it is. Nine more: corrected CLI
+invocation docs, disclosed the marketplace's zero published packages, crash-guards on 8
+dynamic workflows, 32 unregistered skills added to the manifest, 3 personas granting
+tools that don't exist fixed, 11 dangling swarm-template references reconciled, `health`
+wired to a real integrity check, and a brand-new install's audit log no longer reporting a
+false "BROKEN" status. See [RELEASENOTES.md](./RELEASENOTES.md) or
+[CHANGELOG.md](./CHANGELOG.md).
+
+<details>
+<summary><strong>Earlier releases</strong></summary>
+
+**v11.9.8** fixed two real bugs found by a literal, end-to-end README audit (113 claims
+checked, 98 held up): `--runtime claude,cursor` crashed the installer outright, and
+`--minimal` claimed "no persona library" but shipped all 216 anyway. The other twelve
+findings were documentation catching up to what the code actually does. The previous
+release, **v11.9.7**, fixed a version self-contradiction and a false "Enabled"
 claim in the install banner, a dead `docs.mindforge.cc` link, and a persona-count doc
 regression (218 → back to the correct 216) introduced by v11.9.6's own honesty pass.
 **v11.9.6** was the release-readiness pass before pointing real, external users at the
@@ -200,58 +282,7 @@ change under a patch bump** still applies — the installer writes `.claude/sett
 where it previously declined, merging append-only and backing up first. See the BREAKING
 section in [CHANGELOG.md](./CHANGELOG.md).
 
----
-
-## What is actually enforced
-
-Read this before you rely on anything below blocking a bad command. 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. 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 |
-|---|---|---|
-| Slash commands | Yes | Yes |
-| Skills / personas / protocol docs | Yes | Yes |
-| Subagents | Yes | Yes |
-| Audit hash-chain (`bin/verify-audit.js`) | Yes | Yes |
-| **Hooks enforced (can block a tool call)** | **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`).
+</details>
 
 ---
 
@@ -271,14 +302,22 @@ instructions — review what you install. The audit chain is verifiable today
                               |
                               v
    Verification (build / typecheck / lint / test / security / diff)
-                              |
-                              v
-        Handoff (.planning/HANDOFF.json + AUDIT.jsonl)
+                     pass    |    fail
+              +--------------+--------------+
+              v                             v
+   Handoff (.planning/HANDOFF.json    Temporal rollback -> sets status
+              + AUDIT.jsonl)              "awaiting_regeneration"
 ```
 
+The fail path is real but partial: `bin/hindsight-injector.js` rolls back `.planning/` state and sets
+`auto-state.json.status = "awaiting_regeneration"` — verified, and hash-chained into the audit log
+like everything else. What is **not** currently true: nothing in `bin/` reads that status back out
+to automatically re-trigger the wave (`awaiting_regeneration` has one writer, zero readers today) —
+regeneration after a rollback is a manual step, not a closed loop.
+
 Four layers underlie this, top to bottom: **Interface** (`.claude/`, `.agent/` — the 221 slash
-commands and hooks), **Engine specs** (`.mindforge/` — 232 of the 355 skills plus 216 personas and
-`config.json` runtime knobs; the other 123 skills are extended-tier, under `.agent/skills/`),
+commands and hooks), **Engine specs** (`.mindforge/` — 232 of the 354 skills plus 216 personas and
+`config.json` runtime knobs; the other 122 skills are extended-tier, under `.agent/skills/`),
 **Execution** (`bin/`, ~32K raw / ~25K stripped-of-comments LOC — the wave executor, governance,
 memory, and dashboard code that actually runs), and **Persistence** (`.planning/` — `STATE.md`,
 the audit chain, resumable `HANDOFF.json`). Edit behavior in layer 2 where possible; layer 3 is
@@ -308,7 +347,7 @@ Six categories, read in this order the first time:
 | Security | [SECURITY.md](SECURITY.md) | Reporting a vulnerability; credentials are read from env vars and never committed |
 | Security | [Threat model](docs/security/threat-model.md) | Historical only — scoped to the v1.0.0 predecessor, not re-reviewed against v11.x; see [SECURITY.md](SECURITY.md) for what's actually enforced today |
 | Contributing | [Architecture](docs/architecture/README.md) | Understanding the codebase before sending a PR |
-| Contributing | [Contributing guide](docs/contributing/CONTRIBUTING.md) | Sending a PR |
+| Contributing | [Contributing guide](CONTRIBUTING.md) | Sending a PR |
 | Contributing | [CI quickstart](docs/ci-quickstart.md) | Understanding what CI checks before you push |
 | Contributing | [Release checklist](docs/release-checklist-guide.md) | Cutting a release |
 | Reference | [USPs and features](docs/usp-features.md) | The same "measured, not asserted" honesty pass applied to what's actually shipped — no competitor comparison |
@@ -386,6 +425,14 @@ published under it — this is the mechanism, not a catalog.
 (`--profile` doesn't exist; real flags are `--phase N`, `--session ID`, `--window short|medium|long`,
 and `--optimise`.) See `.mindforge/production/token-optimiser.md`.
 
+Installing and running `/mindforge:plan-phase`/`/mindforge:execute-phase` costs real model calls
+once a subagent starts working — install itself does not (`npx mindforge-cc@latest` never calls
+a model). Spend is capped by `[COST_HARD_LIMIT_USD]` in `MINDFORGE.md` (default `25.00`),
+enforced in code by `bin/models/cost-tracker.js`'s `preflight()` before each call goes out — not a
+policy statement. The per-project token/cost *reports* from `/mindforge:tokens` and
+`.mindforge/production/token-optimiser.md` are heuristic estimates (`file size / 4`), explicitly
+logged with `measured: false`.
+
 ---
 
 ## License

package/RELEASENOTES.md

@@ -1,5 +1,33 @@
 # Release Notes
 
+## v11.9.9 — 2026-09-23 — Release-readiness audit: 5 CRITICAL + 9 HIGH findings fixed
+
+### Why this release exists
+
+An 8-agent audit workflow tested every MindForge surface — slash commands, skills,
+personas, subagents, dynamic workflows, CLI/MCP, and a live install/verify/health cycle —
+as a release gate before shipping to real external users. Every finding was independently
+re-verified against live code and commands before being fixed, not trusted from the audit
+report alone.
+
+### The user-visible part
+
+**Five CRITICAL findings, all ship-blocking:** a real, complete LLM jailbreak toolkit
+(`godmode`) that was shipping unconditionally in the published package is gone; `help.md`,
+`status.md`, `health.md`, and `security-scan.md` stop claiming PQAS/biometric/lattice-crypto
+verification is "active by default" when the code itself says it's simulated and off;
+`--minimal` now actually skips the persona set instead of shipping all 218 files anyway; a
+"Sovereign Integrity Check" that called a CLI flag on a script with no CLI entrypoint (and
+so could never fail) is replaced with a real check; and a dead 4-line stub standing in for
+"232 auto-triggered skills" is now disclosed as what it is.
+
+**Nine HIGH-severity findings:** corrected CLI invocation docs, disclosed the marketplace
+has zero published packages today, added crash-guards to 8 dynamic workflows, registered 32
+skills that existed on disk but were never in the manifest, fixed three personas granting
+tools that don't exist, reconciled 11 dangling swarm-template references, wired the `health`
+command to an actual integrity check, and stopped a brand-new install's audit log from
+reporting a false "BROKEN" status.
+
 ## v11.9.8 — 2026-09-21 — What the README claims, verified line by line
 
 ### Why this release exists

package/SECURITY.md

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

package/bin/governance/audit-verifier.js

@@ -1,6 +1,10 @@
 'use strict';
 /**
- * MindForge — Audit chain verifier (UC-04). Fail-closed: any break => valid:false.
+ * MindForge — Audit chain verifier (UC-04). Fail-closed: any break => valid:false. An ABSENT log
+ * (ENOENT) is reported separately via `missing: true` rather than folded into the generic
+ * `unreadable:` reason below — a project that has never written an audit entry is not evidence of
+ * tampering, and callers (bin/verify-audit.js) use the distinction to avoid crying "BROKEN" at a
+ * brand-new user who has done nothing wrong.
  *
  * Walks the JSONL audit log line-by-line and re-derives each entry's hash from its
  * content plus the prior entry's hash. The chain is valid only if EVERY link holds:
@@ -32,12 +36,17 @@ function hashEntry(entry, previousHash) {
 /**
  * Verifies the integrity of a hash-chained audit log. Fail-closed.
  * @param {string} auditPath — path to the AUDIT.jsonl file
- * @returns {{ valid: boolean, count: number, brokenAt?: number, reason?: string }}
+ * @returns {{ valid: boolean, count: number, brokenAt?: number, reason?: string, missing?: boolean }}
  */
 function verifyAuditChain(auditPath) {
   let lines;
   try { lines = fs.readFileSync(auditPath, 'utf8').split('\n').filter(Boolean); }
-  catch (e) { return { valid: false, count: 0, brokenAt: 0, reason: `unreadable: ${e.message}` }; }
+  catch (e) {
+    if (e.code === 'ENOENT') {
+      return { valid: false, count: 0, missing: true, reason: 'no audit log yet — nothing has been audited' };
+    }
+    return { valid: false, count: 0, brokenAt: 0, reason: `unreadable: ${e.message}` };
+  }
 
   let previousHash = null;
   for (let i = 0; i < lines.length; i++) {

package/bin/installer/harness-adapter-compliance.js

@@ -84,7 +84,7 @@ function freezeRecord(record) {
  */
 function sharedAssetTrees(base, { hooks = 11 } = {}) {
   return [
-    { asset: 'skills', dir: `${base}/skills`, min_files: 282, verbatim_subset_of: '.agent/skills' },
+    { asset: 'skills', dir: `${base}/skills`, min_files: 279, verbatim_subset_of: '.agent/skills' },
     { asset: 'hooks', dir: `${base}/hooks`, min_files: hooks, verbatim_subset_of: '.agent/hooks' },
     { asset: 'personas', dir: `${base}/personas`, min_files: 218, verbatim_subset_of: '.mindforge/personas' },
     { asset: 'docs references', dir: `${base}/docs/references`, min_files: 20, verbatim_subset_of: 'docs/References' },

package/bin/installer-core.js

@@ -636,13 +636,16 @@ async function install(runtime, scope, options = {}) {
     const assetMappings = [
       { key: 'skillsSubdir',   src: src('.agent', 'skills'),      label: 'skills' },
       { key: 'hooksSubdir',    src: src('.agent', 'hooks'),       label: 'hooks' },
-      { key: 'personasSubdir', src: src('.mindforge', 'personas'), label: 'personas' },
       // NB: on-disk dirs are capitalized (docs/References, docs/Templates). macOS is
       // case-insensitive so lowercase used to "work" locally, but npm/Linux is
       // case-sensitive — the lookup silently missed in production (UC: REFERENCES 0).
       { key: 'docsSubdir',     src: src('docs', 'References'),    label: 'references' },
       { key: 'docsSubdir',     src: src('docs', 'Templates'),     label: 'templates' }
     ];
+    // Mirrors the real copy logic in Section 2.1: personas are skipped under --minimal.
+    if (!minimal) {
+      assetMappings.push({ key: 'personasSubdir', src: src('.mindforge', 'personas'), label: 'personas' });
+    }
 
     assetMappings.forEach(asset => {
       const subDir = cfg[asset.key];
@@ -813,17 +816,25 @@ async function install(runtime, scope, options = {}) {
     }
   }
 
-  // ── 2.1 Install Enterprise Assets (Skills, Hooks, Personas) ─────────────────
+  // ── 2.1 Install Enterprise Assets (Skills, Hooks, Personas, Docs, Memory, Plugins) ──
   if (scope === 'local' && !selfInstall) {
     const assetTypes = [
       { key: 'skillsSubdir',   src: src('.agent', 'skills'),      label: 'skills' },
       { key: 'hooksSubdir',    src: src('.agent', 'hooks'),       label: 'hooks' },
-      { key: 'personasSubdir', src: src('.mindforge', 'personas'), label: 'personas' },
       { key: 'docsSubdir',     src: src('docs', 'References'),    label: 'references' },
       { key: 'docsSubdir',     src: src('docs', 'Templates'),     label: 'templates' },
       { key: 'memorySubdir',   src: src('.mindforge', 'memory'),   label: 'memory' },
       { key: 'pluginsSubdir',  src: src('.mindforge', 'plugins'),  label: 'plugins' }
     ];
+    // 'personas' is gated on !minimal, not removed: this copy into <runtime>/personas/ (e.g.
+    // .claude/personas/) is a real, tested, documented per-harness asset delivery contract
+    // (bin/installer/harness-adapter-compliance.js's ADAPTER_RECORDS asserts a >=218-file floor
+    // here for every harness except copilot), not dead/unused. The bug was that it ran
+    // unconditionally regardless of --minimal, undermining --minimal's "no persona library"
+    // promise (README.md, docs/getting-started.md) by shipping the full persona set anyway.
+    if (!minimal) {
+      assetTypes.push({ key: 'personasSubdir', src: src('.mindforge', 'personas'), label: 'personas' });
+    }
 
     assetTypes.forEach(asset => {
       const subDir = cfg[asset.key];
@@ -1082,6 +1093,13 @@ async function install(runtime, scope, options = {}) {
       // install-manifests/install-state pair, which are build- and CI-side and have no business in a
       // consumer project.
       'bin/installer/hook-registration.js',
+      // A thin (12-line) entry point whose only require is bin/governance/audit-verifier.js, which
+      // already ships unconditionally via sovereignEngines above -- so this adds zero new surface,
+      // just the one file consumers need to actually run "node bin/verify-audit.js" themselves.
+      // Previously gated behind --with-utils for no functional reason: CLAUDE.md documents
+      // "node bin/verify-audit.js" as a top-level command, not a --with-utils-only one, and a
+      // fresh default install had the doc but not the script.
+      'bin/verify-audit.js',
     ];
     coreFiles.forEach(rel => {
       const srcFile = src(...rel.split('/'));
@@ -1330,17 +1348,6 @@ async function run(args) {
     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(bannerVersion);
-  Theme.printBrandManifest();
-  // Check for updates only
-  if (isCheck) {
-    const { checkAndUpdate } = require('./updater/self-update');
-    await checkAndUpdate({ apply: false });
-    return;
-  }
-
   const runtimes = runtime === 'all'
     ? Object.keys(RUNTIMES)
     : runtime.split(',').map((r) => r.trim()).filter(Boolean);
@@ -1353,6 +1360,43 @@ async function run(args) {
     process.exit(1);
   }
 
+  // Print header and brand manifest
+  Theme.printHeader(bannerVersion);
+  Theme.printBrandManifest();
+  // `health` (routed here via --check — bin/mindforge-cli.js:33-37) advertises itself as "Verify
+  // project health and installation integrity". Until now it only did the first half — this
+  // npm-registry lookup — and returned before touching a single file on disk. Measured: in a fresh
+  // --claude --local install with bin/governance/policy-engine.js deleted by hand, `mindforge health`
+  // printed only "vX.Y.Z is the latest version" and exited 0 — the missing file was invisible to the
+  // one command whose job is to say so.
+  //
+  // verifyInstall() already exists as the real per-runtime file check (used by install() at :1144,
+  // see its own comment for why it was dead code before that). Reusing it here for a project's
+  // EXISTING install — rather than inventing a second checker — means both callers agree on what
+  // "installed" means.
+  if (isCheck) {
+    const { checkAndUpdate } = require('./updater/self-update');
+    await checkAndUpdate({ apply: false });
+
+    let anyMissing = false;
+    for (const rt of runtimes) {
+      const cfg = RUNTIMES[rt];
+      const rtBaseDir = resolveBaseDir(rt, scope);
+      const rtCmdsDir = norm(path.join(rtBaseDir, cfg.commandsSubdir));
+      const verification = verifyInstall(rtBaseDir, rtCmdsDir, rt, scope);
+      if (verification.ok) {
+        Theme.printResolved(c.bold(`${rt} (${scope}): install verified (${verification.checked} required files present)`));
+      } else {
+        anyMissing = true;
+        console.error(`\n  ❌  ${rt} (${scope}): install verification failed — ${verification.missing.length} of ` +
+          `${verification.checked} required file(s) missing:`);
+        verification.missing.forEach(f => console.error(`      ${f}`));
+      }
+    }
+    if (anyMissing) process.exit(1);
+    return;
+  }
+
   for (const rt of runtimes) {
     if (isUninstall)  await uninstall(rt, scope, options);
     else if (isUpdate) await install(rt, scope, { ...options, isUpdate: true });

package/bin/mindforge-cli.js

@@ -41,11 +41,11 @@ const COMMANDS = {
   },
   'pr-review': {
     script: 'bin/review/cross-review-engine.js',
-    description: 'Run standard PR review logic'
+    description: 'Alias for cross-review -- runs the same 2-model adversarial review engine'
   },
   'cross-review': {
     script: 'bin/review/cross-review-engine.js',
-    description: 'Run advanced cross-model review'
+    description: 'Run the 2-model adversarial cross-review engine (architect + security auditor)'
   },
   'classify': {
     script: 'bin/change-classifier.js',

package/bin/verify-audit.js

@@ -3,7 +3,13 @@
 const { verifyAuditChain } = require('./governance/audit-verifier');
 const auditPath = process.argv[2] || '.planning/AUDIT.jsonl';
 const result = verifyAuditChain(auditPath);
-if (result.valid) {
+if (result.missing) {
+  // Not a break: a project that has never written an audit entry has no chain to break. Measured
+  // before this branch existed: an absent log printed "❌ audit chain BROKEN at entry 0: unreadable:
+  // ENOENT..." and exited 1 — indistinguishable from real tamper detection to a brand-new user.
+  process.stdout.write(`ℹ️  no audit log yet at ${auditPath} — one will be created on first audited action\n`);
+  process.exit(0);
+} else if (result.valid) {
   process.stdout.write(`✅ audit chain valid: ${result.count} entries\n`);
   process.exit(0);
 } else {

package/changelogs/v11.9.9.md

@@ -0,0 +1,59 @@
+# Changelog
+
+## [11.9.9] — 2026-09-23 — Release-readiness audit: 5 CRITICAL + 9 HIGH findings fixed
+
+Patch release. An 8-agent audit workflow tested every MindForge surface (slash commands,
+skills, personas, subagents, dynamic workflows, CLI/MCP, live install/verify/health) as a
+release gate before shipping to real external users. Every finding was independently
+re-verified against live code/commands before fixing, not trusted from the audit report
+alone.
+
+### Fixed
+
+**CRITICAL**
+
+- Removed the `godmode` skill entirely — a real, complete LLM jailbreak toolkit that was
+  shipping unconditionally in the published npm tarball, undisclosed anywhere in the docs.
+- Rewrote `help.md`/`status.md`/`health.md`/`security-scan.md`: they claimed
+  PQAS/biometric-bypass/lattice-crypto signature verification was "active by default,"
+  directly contradicted by `quantum-crypto.js`'s own comments (simulated, off by default).
+- Fixed `--minimal`: a second, unguarded persona-copy path in `installer-core.js` shipped
+  the full 218-file persona set regardless of `--minimal`. Gated on `!minimal` rather than
+  removed outright — the copy is a real, tested per-harness delivery contract, confirmed
+  against `harness-adapter-compliance.js`'s `ADAPTER_RECORDS`.
+- Fixed `security-scan.md`'s "Sovereign Integrity Check," which called a CLI flag on a
+  module with no CLI entrypoint (always exits 0) — a CRITICAL gate that could never fail.
+  Replaced with the one real check (policy-engine tamper detection).
+- Disclosed `bin/engine/skill-loader.js` as dead code (4 lines, zero callers). The real
+  trigger-matching mechanism is an LLM-followed protocol spec
+  (`.mindforge/engine/skills/loader.md`), not deterministic code.
+
+**HIGH**
+
+- `install-skill.md`: documented the literal action token (`install`/`register`/`audit`)
+  `bin/skill-registry.js` deliberately requires with no default.
+- `marketplace.md`: disclosed that zero published packages exist today; labeled sample
+  output as illustrative, not reproducible.
+- `status.md`: fixed a nonexistent-file reference (`AutoRunner.js` -> the real
+  `bin/autonomous/auto-runner.js`).
+- `pr-review`/`cross-review`: was an unqualified alias with descriptions implying different
+  behavior — now honestly documented as the same 2-model adversarial review engine.
+- 8 dynamic-workflow scripts (`feature-planner`, `tdd-sprint`, `onboard-codebase`,
+  `incident-response`, `release-prep`, `perf-optimize`, `refactor-plan`,
+  `verification-loop`): added null-guards after every dependent `agent()` call, matching
+  the pattern ~27 other scripts already use.
+- `MANIFEST.md`: registered 32 engine-tier skills that existed on disk but were never
+  listed in the registration source of truth (`systematic-debugging`,
+  `test-driven-development`, and 30 others).
+- 3 MF-series personas (`mf-tool`, `mf-memory`, `mf-executor`): replaced fictional tool
+  grants (`Database`, `API`, `task_boundary`, `commit_memory`,
+  `multi_replace_file_content`) with the real Claude Code tool vocabulary.
+- `swarm-templates.json`: reconciled 11 dangling persona references (2 fixed by name
+  correction, 9 removed with no real equivalent); updated `docs/PERSONAS.md`'s
+  `data-privacy-engineer` writeup to match the real `privacy-engineer.md` persona it now
+  points to.
+- `health` command: wired to `verifyInstall()` so it actually checks installation
+  integrity instead of only an npm-version lookup.
+- `AUDIT.jsonl`: distinguished "no audit log yet" from "chain broken" so a brand-new
+  install doesn't report a false BROKEN status; shipped `verify-audit.js` by default (its
+  only dependencies already shipped unconditionally).

package/docs/References/commands.md

@@ -36,7 +36,7 @@ the complete, verified list.
 | `/mindforge:note` | `note <text> [list|promote N]` | Zero-friction idea capture and todo promotion | v2.0.0 |
 | `/mindforge:quick` | `quick` | Run a small, single-task plan without a full phase | |
 | `/mindforge:status` | `status` | Show current phase, plan status, and next action | |
-| `/mindforge:health` | `health [--repair]` | Validate installation and repair drift | |
+| `/mindforge:health` | `health` | Validate installation. `--repair` is documented but not wired into the CLI backing path — it's silently ignored, byte-identical to plain `health`. | |
 | `/mindforge:review` | `review [N]` | Run a structured review pass for a phase | |
 | `/mindforge:debug` | `debug [plan-id]` | Debug a failed plan with root-cause workflow | |
 | `/mindforge:add-backlog` | `add-backlog <desc>` | Park ideas in 999.x "parking lot" | v2.0.0 |
@@ -70,7 +70,7 @@ the complete, verified list.
 | `/mindforge:metrics` | `metrics [--phase N]` | Compute quality and throughput metrics | |
 | `/mindforge:profile-team` | `profile-team` | Generate team skill and ownership profile | |
 | `/mindforge:benchmark` | `benchmark [--skill X]` | Measure skill effectiveness | |
-| `/mindforge:tokens` | `tokens [--profile] [--summary]` | Token usage profiling and optimisation | |
+| `/mindforge:tokens` | `tokens [--phase N] [--session ID] [--window short\|medium\|long] [--optimise]` | Token usage profiling and optimisation (`--profile`/`--summary` don't exist) | |
 
 ### Integrations & distribution