mindforge-cc 11.9.7 → 11.9.9

package/README.md

@@ -1,50 +1,60 @@
 # 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)
 
-**An agentic intelligence framework for Claude Code** — orchestrates multi-agent workflows with governance, memory, and autonomous execution. Production-hardened with true parallelism, streaming SDK, and zero-trust security. Install once, get structured AI-driven development with built-in quality gates.
+![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).
 
-**At a glance:** 221 slash commands · 355 skills (232 auto-triggered + 123 explicit) · 216 personas · 164 installable subagents · 35 pre-built multi-agent dynamic workflows · a tamper-evident audit hash-chain · cost-aware routing across Anthropic/OpenAI/Gemini/Bedrock/Ollama · a local-first knowledge graph on zero-native-dependency SQLite (sql.js) · a live Express+SSE dashboard. Ships as an npm package, a Claude Code plugin, and an MCP server.
+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
+wave-based executor that fans work out to fresh-context subagents and commits per task, a
+tamper-evident audit chain, and cost-aware routing across providers. Install it once and get
+`/mindforge:plan-phase` → `/mindforge:execute-phase` → `/mindforge:verify-phase` → `/mindforge:ship`
+as your actual working loop, not a slogan.
 
-**Jump to:** [Latest release](#latest-release) · [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)
+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) · [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)
 
 ---
 
-## Latest release
+## What you get
 
-**v11.9.7** (2026-09-20) — The install banner stops contradicting itself. Found by
-actually running v11.9.6's own documented install command in a clean project instead of
-stopping at `--version`: the top banner claimed `SOVEREIGN INTELLIGENCE v8.1.1` while the
-install activation line two screens later said `v8.2.0` for the same subsystem, and claimed
-`PQAS ... Enabled` right before accurately disclosing it's simulated and off by default a
-few lines down. Both fixed, plus 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. No
-new features. See [RELEASENOTES.md](./RELEASENOTES.md) or [CHANGELOG.md](./CHANGELOG.md).
-
-The previous release, **v11.9.6**, was the release-readiness pass before pointing real,
-external users at the project for the first time: fixed a crash in `/mindforge:learn`, a
-token-leak in the browser daemon, three dashboard panels that silently rendered nothing, a
-stale Homebrew formula, and docs describing PQAS/ZTAI/"Pillar"-numbered subsystems as live
-guarantees when the code already self-labels them simulated. **v11.9.5** fixed a release
-pipeline that could strand itself mid-publish and shipped `mindforge-sdk` for the first
-time since 11.8.0, with provenance. **v11.9.4**, before that, 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).
+| | Capability | Detail |
+|---|---|---|
+| 🧩 | **221 slash commands** | `/mindforge:plan-phase`, `/mindforge:execute-phase`, `/mindforge:ship`, and 218 more — [full reference](docs/commands-reference.md) |
+| 🛠️ | **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); 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` |
+
+Ships three ways: an npm package (`npx mindforge-cc@latest`), a Claude Code plugin marketplace
+entry, and an MCP server.
 
 ---
 
 ## What is actually enforced
 
-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
+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.
@@ -60,7 +70,7 @@ but it declined to run on almost every project, so in practice nothing was enfor
 
 What that means, measured rather than asserted:
 
-- **The `npx` channel generates the config it never used to ship.** `files[]` has 49 entries and
+- **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
@@ -73,11 +83,12 @@ What that means, measured rather than asserted:
   `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`.
+> [!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
@@ -96,36 +107,108 @@ instructions — review what you install. The audit chain is verifiable today
 
 ## Install
 
-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.
+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:
+
+```bash
+npx mindforge-cc@latest --claude --local      # Claude Code, this project only
+npx mindforge-cc@latest --antigravity --local # Antigravity, this project only
+npx mindforge-cc@latest                       # interactive wizard, pre-selects a detected runtime
+```
+
+The bare form only detects anything inside an interactive TTY wizard session, where it pre-selects
+— you still confirm — whichever runtime it finds. Run it non-interactively (CI, piped, scripted,
+or anywhere `stdin` isn't a TTY) and it skips the wizard entirely and installs `--claude` by
+default, regardless of what's actually on the machine.
+
+**Global** (system-wide, for your primary AI coding runtime):
+
+```bash
+npx mindforge-cc@latest --claude --global
+```
+
+(`npm install -g mindforge-cc@latest` only puts the `mindforge-cc`/`mindforge` binaries on your
+PATH — it doesn't select a runtime or write anything. Run the command above, or the equivalent
+`mindforge-cc --claude --global` once installed, to actually scaffold a global setup.)
+
+**Other runtimes** — same flag pattern, swap `--global`/`--local`:
+
+| Runtime | Flag |
+|---|---|
+| Claude Code | `--claude` |
+| Antigravity | `--antigravity` |
+| Cursor | `--cursor` |
+| GitHub Copilot | `--copilot` |
+| Gemini CLI | `--gemini` |
+
+**Advanced:** `--runtime claude,cursor` (combined runtimes) · `--with-utils` (installs local `bin/` utilities) · `--minimal` (essential scaffolding only, no persona library) · `--force` (rewrite an existing `.mindforge/MINDFORGE-SCHEMA.json` with the current, stricter schema)
+
+### Claude Code plugin marketplace
+
+No project files written — the plugin's hooks fire, see [What is actually enforced](#what-is-actually-enforced) for what that does and does not cover.
 
 ```bash
 /plugin marketplace add sairam0424/MindForge
 /plugin install mindforge@mindforge
 ```
 
-Or the full framework engine via `npx` (writes `.mindforge/` governance, memory, and planning into your project):
+Prefer just a slice (e.g. Python agents)? `mindforge-lang@mindforge` and 9 other focused packs exist — see [docs/plugin-installation.md](docs/plugin-installation.md) for all 10, token-budget guidance, and team setup.
+
+### Standalone MCP server
+
+```bash
+claude mcp add mindforge -- npx -y mindforge-mcp-server
+```
+
+Exposes 8 tools over stdio (6 read-only, 1 guarded write, 1 guarded browse proxy). Also listed on
+the [MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.sairam0424/mindforge`
+— that entry is republished manually and can lag; check what it actually serves before relying on
+it, or install `mindforge-mcp-server` from npm directly to pin a version.
+
+### Homebrew
 
 ```bash
-npx mindforge-cc@latest --claude --local
+brew install sairam0424/tap/mindforge
 ```
 
-All install channels (global, local, Antigravity, Cursor, Copilot, Gemini CLI, MCP server, combined runtimes, `--minimal`): see [docs/getting-started.md](docs/getting-started.md).
+### 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` if you want 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. 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.
+Build on MindForge programmatically:
+
+```bash
+npm i mindforge-sdk
+```
+
+> [!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).
 
 ---
 
 ## Verify
 
+These `/mindforge:*` commands require the Claude Code plugin or an `npx`/Homebrew framework
+install — the standalone MCP server exposes MCP tools instead, and `mindforge-sdk` exposes a
+programmatic API; neither installs these slash commands.
+
 ```bash
 /mindforge:health              # framework + installation health check
-/mindforge:health --repair     # fix anything the health check flags
+/mindforge:health --repair     # documented in the command spec, but NOT wired into the CLI
+                                # backing path — silently ignored, output is byte-identical to plain health
 /mindforge:status              # project status snapshot
 /mindforge:next                # auto-discover your first task
 ```
@@ -154,31 +237,121 @@ Full verification walkthrough: [docs/quick-verify.md](docs/quick-verify.md).
 
 ---
 
+## Latest release
+
+**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
+project for the first time: fixed a crash in `/mindforge:learn`, a token-leak in the
+browser daemon, three dashboard panels that silently rendered nothing, a stale Homebrew
+formula, and docs describing PQAS/ZTAI/"Pillar"-numbered subsystems as live guarantees when
+the code already self-labels them simulated. **v11.9.5** fixed a release pipeline that
+could strand itself mid-publish and shipped `mindforge-sdk` for the first time since
+11.8.0, with provenance. **v11.9.4**, before that, 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).
+
+</details>
+
+---
+
+## How it fits together
+
+```
+                     /mindforge:plan-phase N
+                              |
+                              v
+   Skill Loader (trigger-match, tier: Project > Org > Core)
+                              |
+                              v
+        Context Injector (<=60K tokens)  --> Cost Router
+                              |             (Haiku / Sonnet / Opus / Gemini,
+                              v              by task difficulty)
+      Fresh-context Subagent (implement -> self-verify -> commit)
+                              |
+                              v
+   Verification (build / typecheck / lint / test / security / diff)
+                     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 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
+the only place with real enforcement, per *What is actually enforced* above.
+
+---
+
 ## Documentation
 
-- **User Guide:** [docs/user-guide.md](docs/user-guide.md)
-- **Getting started:** [docs/getting-started.md](docs/getting-started.md)
-- **Quick verify:** [docs/quick-verify.md](docs/quick-verify.md)
-- **Troubleshooting:** [docs/troubleshooting.md](docs/troubleshooting.md)
-- **FAQ:** [docs/faq.md](docs/faq.md)
-- **Full tutorial:** [docs/tutorial.md](docs/tutorial.md)
-- **Commands reference (full):** [docs/commands-reference.md](docs/commands-reference.md)
-- **Commands (quick):** [docs/References/commands.md](docs/References/commands.md)
-- **Config reference:** [docs/References/config-reference.md](docs/References/config-reference.md)
-- **SDK:** [docs/References/sdk-api.md](docs/References/sdk-api.md)
-- **Skills:** [docs/References/skills-api.md](docs/References/skills-api.md)
-- **Audit events:** [docs/References/audit-events.md](docs/References/audit-events.md)
-- **Upgrade guide:** [docs/upgrade.md](docs/upgrade.md)
-- **Workflow atlas:** [docs/workflow-atlas.md](docs/workflow-atlas.md)
-- **Security:** [SECURITY.md](SECURITY.md) (credentials are read from env vars and never committed to the repository)
-- **Threat model:** [docs/security/threat-model.md](docs/security/threat-model.md)
-- **Architecture:** [docs/architecture/README.md](docs/architecture/README.md)
-- **Contributing:** [docs/contributing/CONTRIBUTING.md](docs/contributing/CONTRIBUTING.md)
-- **Release notes:** [RELEASENOTES.md](RELEASENOTES.md)
-- **CI quickstart:** [docs/ci-quickstart.md](docs/ci-quickstart.md)
-- **Requirements:** [docs/requirements.md](docs/requirements.md)
-- **Release checklist guide:** [docs/release-checklist-guide.md](docs/release-checklist-guide.md)
-- **USPs and features:** [docs/usp-features.md](docs/usp-features.md)
+Six categories, read in this order the first time:
+
+| Category | Doc | Read this when |
+|---|---|---|
+| Start here | [Getting started](docs/getting-started.md) | Installing for the first time |
+| Start here | [Quick verify](docs/quick-verify.md) | Right after install — confirm it actually works |
+| Start here | [User guide](docs/user-guide.md) | Learning the day-to-day command loop |
+| Start here | [Full tutorial](docs/tutorial.md) | Want a guided walkthrough instead of reference docs |
+| Reference | [Commands (full)](docs/commands-reference.md) / [Commands (quick)](docs/References/commands.md) | Looking up a specific `/mindforge:*` command |
+| Reference | [Config reference](docs/References/config-reference.md) | Editing `MINDFORGE.md` — this doc doesn't cover `.mindforge/config.json` |
+| Reference | [SDK API](docs/References/sdk-api.md) / [Skills API](docs/References/skills-api.md) | Building on `mindforge-sdk` or authoring a new skill |
+| Reference | [Audit events](docs/References/audit-events.md) | Parsing `.planning/AUDIT.jsonl` |
+| Reference | [Workflow atlas](docs/workflow-atlas.md) | Choosing one of the 35 dynamic workflows |
+| Reference | [Requirements](docs/requirements.md) | Checking supported Node/OS versions before install |
+| When something's wrong | [Troubleshooting](docs/troubleshooting.md) | A command or hook isn't behaving as documented |
+| When something's wrong | [FAQ](docs/faq.md) | Common questions before filing an issue |
+| When something's wrong | [Upgrade guide](docs/upgrade.md) | Moving between major/minor versions |
+| 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](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 |
+| Release notes | [RELEASENOTES.md](RELEASENOTES.md) | What changed, in prose, per version |
 
 ---
 
@@ -187,7 +360,7 @@ Full verification walkthrough: [docs/quick-verify.md](docs/quick-verify.md).
 | Command | What it does |
 | :--- | :--- |
 | `/mindforge:init-project` | Requirements interview → creates `PROJECT.md`, `REQUIREMENTS.md`, `STATE.md` |
-| `/mindforge:plan-phase 1 [--ads]` | Discuss scope, research the domain in parallel, create atomic XML task plans |
+| `/mindforge:plan-phase 1` | Discuss scope, research the domain in parallel, create atomic XML task plans |
 | `/mindforge:execute-phase 1` | Wave-based parallel execution, one commit per task, automated verification |
 | `/mindforge:verify-phase 1` | Human acceptance testing, debug agent on failures, UAT sign-off |
 | `/mindforge:ship 1` | Changelog generation, final quality gates, PR creation |
@@ -207,13 +380,18 @@ Full, verified 35-workflow table by tier: [docs/workflow-atlas.md](docs/workflow
 
 ---
 
-## Execution Modes
+<details>
+<summary><strong>Execution modes</strong></summary>
 
 MindForge supports multiple interaction models to fit your engineering workflow:
 
 - **In-IDE Orchestration**: Use `/mindforge:agent <persona>` for real-time delegation.
 - **Enterprise Workflows**: Specialized commands like `/mindforge:wf-tdd-sprint` and `/mindforge:plan-phase`.
-- **CLI Automation**: Run `node bin/mindforge-cli.js spawn <persona>` for scripted tasks.
+- **CLI Automation**: `node bin/mindforge-cli.js spawn <persona>` exists but is a v1.0 stub — it
+  prints "NOT IMPLEMENTED in v1.0" and exits 1, redirecting you to `/mindforge:auto` or
+  `/mindforge:next` instead.
+
+</details>
 
 ---
 
@@ -223,27 +401,40 @@ Run `/mindforge:update` (add `--apply` to install) — see [docs/upgrade.md](doc
 
 ---
 
-## Plugin system (v1.0.0)
+<details>
+<summary><strong>Plugin system (v1.0.0)</strong></summary>
 
-Plugins extend MindForge via the `mindforge-plugin-*` namespace.
+Plugins extend MindForge via the `mindforge-plugin-*` namespace. No packages are currently
+published under it — this is the mechanism, not a catalog.
 
-```
+```bash
 /mindforge:plugins list
 /mindforge:plugins install mindforge-plugin-<name>
 /mindforge:plugins validate
 ```
 
+</details>
+
 ---
 
 ## Token usage profiling
 
 ```
-/mindforge:tokens --profile
+/mindforge:tokens --optimise
 ```
-See `.mindforge/production/token-optimiser.md`.
+(`--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
 
-MIT © 2026 MindForge Team
+MIT © 2026 Sairam Ugge (GitHub: Sairam0000)

package/RELEASENOTES.md

@@ -1,5 +1,62 @@
 # 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
+
+v11.9.7 shipped a full README rewrite. This release is what happened when that rewrite got
+a literal, end-to-end audit — every command it documents actually run in a real environment
+(real `npx` installs, a real Homebrew install/uninstall cycle, a real `npm i mindforge-sdk`,
+live registry checks) rather than re-read for plausibility. Of 113 claims checked, 98 held
+up, 14 didn't, and 1 couldn't be verified either way.
+
+### The user-visible part
+
+**Two of the 14 were real bugs, not just wording.** `--runtime claude,cursor` — or any
+comma-separated runtime list — crashed the installer outright; it's fixed, and an unknown
+runtime name now exits cleanly with a clear message instead of a raw crash. `--minimal`
+claimed "no persona library" but silently installed all 216 personas anyway; it now
+installs none, as documented.
+
+**The other twelve are documentation catching up to what the code actually does:** the
+bare `npx mindforge-cc@latest` "auto-detects your runtime" claim (real detection only
+happens inside the interactive wizard, and even there you still confirm it — every
+non-interactive run defaults to `--claude`), an `--ads` flag on `/mindforge:plan-phase`
+that was never real, `/mindforge:health --repair` silently doing nothing, a `--profile`
+flag on `/mindforge:tokens` that doesn't exist, a CLI `spawn` command that's a v1.0 stub,
+the License section's copyright holder, the skill-tier split in the architecture diagram,
+the `bin/` line-count figure, three Documentation-table rows that overstated what their
+linked docs actually cover, and the `mindforge-plugin-*` namespace, which has zero
+packages published under it today.
+
 ## v11.9.7 — 2026-09-20 — The install banner stops contradicting itself
 
 ### Why this release exists

package/SECURITY.md

@@ -1,6 +1,6 @@
 # Security Policy
 
-> **Current version:** 11.9.7 | **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
 
@@ -90,7 +90,8 @@ We follow responsible disclosure practices. We will credit reporters in the rele
 ### Supply Chain
 
 - **Zero native dependencies** — The removal of `better-sqlite3` eliminates the entire native compilation toolchain (node-gyp, Python, C++ compiler) from the install process, reducing the attack surface.
-- **Dependabot enabled** — Automated weekly scans for vulnerable npm dependencies and monthly GitHub Actions version updates.
+- **Dependabot enabled** — Automated weekly scans for vulnerable npm dependencies (root, `sdk/`, and `mcp-server/` each tracked independently) and monthly GitHub Actions version updates.
+- **SBOM available** — GitHub generates a full SPDX software bill of materials from the dependency graph; export it from the repo's Insights tab, or via the API: `gh api repos/sairam0424/MindForge/dependency-graph/sbom/generate-report` returns an `sbom_url`, poll it until it 302s to a download. (The older single-call `.../dependency-graph/sbom` endpoint still works today but GitHub is retiring it on 2026-11-13 — use the generate/fetch flow above for anything meant to keep working past that date.)
 - **CODEOWNERS enforcement** — Changes to `bin/governance/`, `bin/engine/`, and the SDK require review from designated security owners.
 - **.npmignore** — Prevents accidental publication of secrets, test fixtures, planning state, and intelligence logs.
 

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' },