mindforge-cc 11.9.8 → 12.0.0

package/bin/security/trust-boundaries.js

@@ -199,6 +199,18 @@ function isHighImpact(command) {
 
     // ── #14 Power-state commands ────────────────────────────────────────────
     /\b(shutdown|reboot|halt|poweroff)\b/i,
+
+    // ── #16 Download -> chmod +x -> direct execution (dropper chain) ───────
+    // curl/wget fetches a payload, chmod +x makes it executable, then the
+    // SAME command line invokes it directly by path with no interpreter
+    // keyword in that final step — so neither #4 (pipe-to-shell) nor #5
+    // (interpreter + untrusted path) above ever see it. Requires all three
+    // in order: a curl/wget call, a chmod ... +x on that call's command
+    // segment, and a later bare invocation of an absolute, /tmp, /var/tmp,
+    // /dev/shm, or ~/-rooted path as its own command (introduced by a
+    // separator or the start of the line) — i.e. the path being run, not
+    // merely referenced as an argument (audit finding, pre-release review).
+    /\b(curl|wget)\b[\s\S]*?\bchmod\b[^;&|\n]*\+x\b[\s\S]*?(^|[;&|\n]\s*)(~\/|\/tmp\/|\/var\/tmp\/|\/dev\/shm\/|\/)\S+/i,
   ];
   return patterns.some(pattern => pattern.test(sanitized));
 }

package/bin/utils/readiness-gate.js

@@ -119,7 +119,7 @@ function releaseReadinessChecks(root) {
       label: 'RELEASENOTES.md present and has an entry for the current version',
       points: 2,
       pass: fileExists(root, 'RELEASENOTES.md') && Boolean(pkgVersion)
-        && new RegExp(`^## v${pkgVersion.replace(/\./g, '\\.')}(?![\\d.\\w-])`, 'm')
+        && new RegExp(`^## v${pkgVersion.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?![\\d.\\w-])`, 'm')
           .test(safeRead(root, 'RELEASENOTES.md')),
       fix: `Add a "## v${pkgVersion || '?'}" section to RELEASENOTES.md. README.md links here as the human-readable route to the BREAKING notes, so releasing without one points readers at a file whose newest entry describes a different version.`,
     },

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/bin/wizard/theme.js

@@ -41,7 +41,7 @@ const Theme = {
     '╚═╝     ╚═╝╚═╝╚═╝  ╚═══╝╚═════╝ ╚═╝      ╚═════╝ ╚═╝  ╚═╝ ╚═════╝ ╚══════╝'
   ].join('\n'),
 
-  tagline: 'THE AUTONOMOUS ENTERPRISE AGENTIC ECOSYSTEM',
+  tagline: 'AI-NATIVE AGENTIC FRAMEWORK FOR CLAUDE CODE',
 
   /**
    * Print a styled header with BMad-style border flare
@@ -66,9 +66,8 @@ const Theme = {
     console.log(`  ${this.colors.dim('│')}  ${this.colors.bold('THE PLATFORM VISION:')}`);
     console.log(`  ${this.colors.dim('│')}    - Unified Enterprise Agentic Ecosystem`);
     console.log(`  ${this.colors.dim('│')}    - Modular Skills & Persona Architecture`);
-    // Added Sovereign Intelligence as a core pillar
-    console.log(`  ${this.colors.dim('│')}    - ${this.colors.magenta('Sovereign Intelligence')}: PQ-Safe & Proactive Swarms`);
-    console.log(`  ${this.colors.dim('│')}    - Autonomous Governance & Self-Healing`);
+    console.log(`  ${this.colors.dim('│')}    - ${this.colors.magenta('Post-Quantum Security')} (simulated) & Proactive Task Homing`);
+    console.log(`  ${this.colors.dim('│')}    - Governance, Audit, and Verification Gates`);
     console.log(`  ${this.colors.dim('│')}`);
     console.log(`  ${this.colors.dim('│')}  ${this.colors.yellow('🌟 100% FREE & OPEN SOURCE')}`);
     console.log(`  ${this.colors.dim('│')}    - No paywalls. No gated content.`);

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/changelogs/v12.0.0.md

@@ -0,0 +1,89 @@
+# Changelog
+
+## [12.0.0] — 2026-09-24 — First release aimed at real external users
+
+MindForge's first release deliberately cut for real external users, not
+just internal iteration. The major-version bump is a milestone marker for
+that shift, not a signal of a breaking API/behavior change — there is none
+in this release; every item below is a fix. It follows a second, independent
+8-agent audit (security/STRIDE, staff-engineer code review, deps+license,
+live production dry-run across all 6 supported runtimes, docs accuracy,
+re-verification of the prior release's deferred backlog, test-coverage gaps,
+and a full trace of the CI/CD release pipeline) run specifically to check
+whether v11.9.9 was actually ready for that shift. It wasn't yet: this
+release closes the 1 CRITICAL and 4 HIGH findings that audit surfaced, plus
+8 MEDIUM/LOW findings judged worth fixing before this exact cutover, all
+independently adversarially re-verified (10/10 confirmed, 0 refuted) before
+being fixed.
+
+### Fixed
+
+**CRITICAL**
+
+- `--global` install printed a fabricated "PAYLOAD MANIFEST" (216 personas,
+  122 skills, etc. "active") while writing none of them — the install
+  success banner counted the source package tree instead of what a global
+  install actually writes (entry file, commands, subagents only, by
+  design). Now prints an honest message describing exactly that.
+
+**HIGH**
+
+- `help.md`/`status.md`/`health.md`/`security-scan.md`'s honesty fixes from
+  11.9.9 didn't reach the install banner itself: it printed "Proactive
+  Semantic Intent Harvesting active" — unhedged — for a feature confirmed
+  to be a genuine no-op, one line below a properly-hedged PQAS claim.
+  Reworded to match. The banner's surrounding "Autonomous Enterprise
+  Agentic Ecosystem" / "Sovereign Intelligence" / "Autonomous Governance &
+  Self-Healing" marketing language, unbacked by anything the rest of the
+  project stands behind, is gone too.
+- `verification-loop.js` (one of the 8 dynamic-workflow scripts null-guarded
+  in 11.9.9) could still crash with an unhandled `TypeError` if its round
+  loop completed zero rounds before any guard ran. Fixed with the same
+  graceful-return shape its siblings already use.
+- Two real test-coverage gaps: nothing asserted the removed `godmode` skill
+  stays absent, or that `--minimal` actually ships 0 persona files. Both
+  covered now, each verified by deliberately breaking the real fix and
+  confirming the new test catches it.
+
+**MEDIUM**
+
+- `bin/security/trust-boundaries.js`'s deny-class gate missed the classic
+  "curl/wget a payload, chmod +x it, run it by path" dropper chain (no
+  interpreter keyword in the final step, so neither existing pattern
+  fired). Added a pattern for it.
+- `bin/governance/config-manager.js`'s `ConfigManager.set()` was vulnerable
+  to prototype pollution via a `__proto__`-shaped key — not reachable from
+  any shipped call site today, but a live, shared, mutable singleton.
+  Guarded, matching a pattern this codebase already uses elsewhere.
+- CodeQL flagged (high severity) an incomplete regex-escape in
+  `bin/utils/readiness-gate.js` once this release's own plugin-bundling fix
+  (below) exposed it to scanning for the first time — only literal dots
+  were escaped before building a `RegExp` from the package version string.
+  Fixed to escape every regex metacharacter.
+- Dependabot's unconstrained docker config silently shipped the Docker MCP
+  Catalog image on `node:25-bookworm-slim`, a non-LTS release. Reverted to
+  `node:22-bookworm-slim` (the CI test matrix's highest tested version) and
+  added an ignore rule blocking future Node major-version bumps of the base
+  image.
+- `docs/PERSONAS.md`'s "Enterprise Swarm Templates" table cited 16 of 25
+  persona names that don't exist — a doc artifact never regenerated after
+  `swarm-templates.json`'s own dangling-reference cleanup in 11.9.9.
+  Regenerated wholesale from the real file: all 49 templates, exact
+  leader/members/focus values.
+- The release workflow's "stable dist-tag" step has failed on 4 consecutive
+  real releases (11.9.6 through 11.9.9) for an identical, root-caused
+  reason: its retry budget (3 attempts × 5s) was an order of magnitude
+  short of npm's own stated multi-minute propagation window, even though
+  the underlying write always succeeded. Widened to 10 attempts × 15s.
+- `.agent/settings.json` was missing the `instinct-capture` hook
+  `.claude/settings.json` has had since before 11.9.0 — a tracked,
+  documented parity gap. Mirrored the registration and, for the first
+  time, bundled its dependency closure into the plugin distribution.
+- Three GitHub Actions hygiene items: an `${{ }}`-into-shell interpolation
+  inconsistency in `control-plane.yml`, an unused `contents: write` grant
+  in `auto-pr.yml`, and an unverified `gitleaks` binary download in
+  `secret-scan.yml` (now checksum-verified against the project's own
+  published `checksums.txt`).
+- Stale doc drift: `agent.md`'s "13+ personas" claim (two mirrors)
+  corrected to 216; `docs/registry/PERSONAS.md`'s 3-release-stale version
+  header and unhedged PQAS citation corrected.

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
 

package/docs/References/config-reference.md

@@ -24,7 +24,7 @@ and be followed by `=`. Prose bullets that merely mention `[KEY]` are not parsed
 
 | Key | Example |
 | :--- | :--- |
-| `[VERSION]` | `11.9.2` — must match `^\d+\.\d+\.\d+$` |
+| `[VERSION]` | `11.9.8` — must match `^\d+\.\d+\.\d+$` |
 | `[REACTIVE_MODE]` | `true` |
 | `[PLANNER]` | `claude-opus-4-7` |
 | `[EXECUTOR]` | `claude-sonnet-4-6` |
@@ -56,6 +56,9 @@ for older configs.
 | `[VERIFIER]` | `VERIFIER_MODEL` | Testing and UAT verification. | `claude-sonnet-4-6` |
 | `[SECURITY]` | `SECURITY_MODEL` | Sensitive security scanning. | `claude-opus-4-7` |
 | `[DEBUG]` | — | Debugging and root-cause analysis. | `claude-opus-4-7` |
+| `[RESEARCH]` | `RESEARCH_MODEL` | Domain research during planning. | `gemini-2.5-pro` |
+| `[QA]` | `QA_MODEL` | Quality-assurance / test-writing tasks. | `claude-sonnet-4-6` |
+| `[QUICK]` | `QUICK_MODEL` | Tier-1 budget-biased tasks. | — |
 
 **Values are free-form strings** — the schema does not constrain them to a list, so a new model
 id works without a framework upgrade. The ids shipped in `MINDFORGE.md` today are
@@ -91,13 +94,15 @@ than editing your registry to satisfy it.
 
 These settings control the `/mindforge:auto` engine's behavior and performance.
 
+> [!WARNING]
+> `AUTONOMOUS_MODE_ENABLED`, `STUCK_DETECTION_TIMEOUT_MS`, `STEERING_CHECK_INTERVAL_MS`, and
+> `NODE_REPAIR_ENABLED` do not appear anywhere in `.mindforge/MINDFORGE-SCHEMA.json`, and nothing
+> in `bin/autonomous/` reads them — they are not currently configurable keys. Only the two rows
+> below are real.
+
 | Key | Description | Default |
 | :--- | :--- | :--- |
-| `AUTONOMOUS_MODE_ENABLED` | Global toggle for autonomous task execution. | `true` |
 | `MAX_TASKS_PER_PHASE` | Limit on task expansion during planning. | `15` |
-| `STUCK_DETECTION_TIMEOUT_MS` | Time before an agent is considered "looping" or stuck. | `300000` |
-| `STEERING_CHECK_INTERVAL_MS` | How often the engine checks for user guidance. | `5000` |
-| `NODE_REPAIR_ENABLED` | If true, the engine attempts to self-heal on failures. | `true` |
 | `COMPACTION_THRESHOLD_PCT` | The context usage percentage at which to trigger compaction. | `70` |
 
 ---
@@ -111,8 +116,7 @@ Define the rules that code must follow to pass the `VERIFY` phase.
 | `MIN_TEST_COVERAGE_PCT` | Required test coverage for any new module. | `80` |
 | `MAX_FUNCTION_LINES` | Maximum lines allowed for a single function. | `40` |
 | `MAX_CYCLOMATIC_COMPLEXITY` | Maximum complexity score (McCune) allowed. | `10` |
-| `BLOCK_ON_MEDIUM_SECURITY` | Fail the gate if any medium security findings exist. | `true` |
-| `ANTIPATTERN_SENSITIVITY` | Frequency at which suspicious patterns are flagged. | `0.7` |
+| `BLOCK_ON_MEDIUM_SECURITY_FINDINGS` | Fail the gate if any medium security findings exist. | `true` |
 
 ---
 
@@ -136,37 +140,18 @@ Control reasoning snapshot retention for the Temporal Steering system.
 | Key | Description | Default |
 | :--- | :--- | :--- |
 | `temporal.max_snapshots` | Maximum number of reasoning snapshots retained per session. | `50` |
-| `temporal.max_age_days` | Snapshots older than this value (in days) are auto-pruned. | `30` |
-
----
-
-## 6. Rate Limiting (v11.0.0+)
-
-Configure request rate limits for the dashboard and API endpoints.
-
-| Key | Description | Default |
-| :--- | :--- | :--- |
-| `rate_limiting.dashboard_rpm` | Maximum requests per minute to dashboard endpoints. | `120` |
-
----
-
-## 7. Session Configuration (v11.0.0+)
-
-Control session token behaviour for dashboard authentication.
-
-| Key | Description | Default |
-| :--- | :--- | :--- |
-| `session.token_expiry_hours` | Hours before a dashboard bearer token expires. | `24` |
+| `temporal.max_age_days` | Snapshots older than this value (in days) are auto-pruned. | `7` |
 
 ---
 
-## 8. Wave Execution (v11.0.0+)
-
-Tune parallel wave execution behaviour.
+## 6. Rate Limiting, Session Configuration, Wave Execution
 
-| Key | Description | Default |
-| :--- | :--- | :--- |
-| `wave_execution.max_concurrency` | Maximum number of tasks executed in parallel within a wave. | `6` |
+> [!WARNING]
+> `rate_limiting.dashboard_rpm`, `session.token_expiry_hours`, and
+> `wave_execution.max_concurrency` are not present in the current `.mindforge/config.json` and
+> nothing in the live `bin/` runtime reads them. The first two only ever existed as one-time
+> values written by a historical migration (`bin/migrations/10.7.0-to-11.0.0.js`); the third
+> doesn't appear anywhere in the codebase. Do not rely on setting any of these three today.
 
 ---
 
@@ -181,4 +166,4 @@ To ensure enterprise safety, several rules **cannot** be disabled via `MINDFORGE
 5. **Critical Security Blocks:** High/Critical findings *will* block the `SHIP` command.
 
 > [!WARNING]
-> Attempting to disable these rules in your configuration will result in a silent enforcement of the defaults. See [ADR-013](../adr/ADR-013-immutable-governance.md) for architectural details.
+> Attempting to disable these rules in your configuration will result in a silent enforcement of the defaults.

package/docs/References/sdk-api.md

@@ -1,4 +1,4 @@
-# MindForge SDK API — Reference (v2.0.0-alpha.4)
+# MindForge SDK API — Reference (v11.9.8)
 
 ## Package
 
@@ -9,11 +9,17 @@
 From `sdk/src/index.ts`:
 
 - `MindForgeClient`
-- `MindForgeEventStream`
-- `commands`
+- `MindForgeEventStream` — SSE-based event stream (see below)
+- `WebSocketEventStream` — WebSocket-based alternative; requires a global `WebSocket` (Node 22+,
+  a browser, or the optional `ws` package assigned to `globalThis.WebSocket` — the SDK declares
+  no runtime dependencies, so nothing is installed for you)
+- `commands` — slash-command string builders
+- `batch(commands: string[])` — joins an array of command strings with `&&`
 - `MindForgeMemory`
 - Types: `MindForgeConfig`, `PhaseResult`, `TaskResult`, `SecurityFinding`,
-  `GateResult`, `HealthReport`, `HealthIssue`, `MindForgeEvent`, `CommandOptions`
+  `GateResult`, `HealthReport`, `HealthIssue`, `MindForgeEvent`, `CommandOptions`,
+  `AuditLogEntry`, `WaveExecutionResult`, `MigrationResult`, `StreamChunk`,
+  `StreamingExecutionResult`, `BatchExecutionRequest`, `BatchExecutionResult`
 - `VERSION`
 
 ## MindForgeClient

package/docs/References/skills-api.md

@@ -13,12 +13,13 @@ Skills are domain knowledge packs loaded on demand. They are stored as
 ```
 
 ## SKILL.md schema (frontmatter)
-Required fields:
+Required fields, enforced by `scripts/ci/validate-assets.js` and `tests/skills-platform.test.js`:
 - `name`: string (stable in 1.x.x)
-- `description`: string
-- `triggers`: array of keywords
 - `version`: semver string
-- `owner`: string (team or org)
+- `status`: string (e.g. `stable`)
+- `triggers`: comma-separated keyword string, minimum 10 terms, unique across all engine skills
+
+`description` and `owner` are commonly present but are **not** enforced as required fields.
 
 Optional fields:
 - `scope`: `core | org | project`
@@ -30,8 +31,9 @@ Example:
 ---
 name: security-review
 version: 1.0.0
+status: stable
 description: Secure coding review checklist and threat modeling prompts
-triggers: ["auth", "payment", "pii", "encryption"]
+triggers: auth, payment, pii, encryption, secrets, credential, oauth, token, session, permission
 owner: mindforge-core
 scope: core
 ---
@@ -53,5 +55,5 @@ Skills can be published to the npm registry under `mindforge-skill-*`.
 See `docs/skills-publishing-guide.md` for full workflow.
 
 ## Stability contract
-As of v1.0.0, the `name` values of the 10 core skills are stable. New optional
-fields may be added in minor versions; removals require a major version bump.
+As of v1.0.0, the `name` values of the 232 engine-tier skills (`.mindforge/skills/`) are stable.
+New optional fields may be added in minor versions; removals require a major version bump.

package/docs/commands-reference.md

@@ -171,8 +171,8 @@ mindforge <command> [options]
 | `security-scan` | Validate configuration and run security checks |
 | `health` | Verify project health and installation integrity |
 | `headless` | Run MindForge agent in headless (non-interactive) mode |
-| `pr-review` | Run standard PR review logic |
-| `cross-review` | Run advanced cross-model architecture review |
+| `pr-review` | Alias for `cross-review` — same 2-model adversarial review engine |
+| `cross-review` | Run the 2-model adversarial cross-review engine (architect + security auditor) |
 | `classify` | Classify changes into governance tiers |
 | `approve` | Generate a governance approval signature to unblock Tier 3 gates |
 | `validate-skill` | Run Level 1 & 2 validation on a SKILL.md file |

package/docs/faq.md

@@ -1,4 +1,4 @@
-# MindForge FAQ (v11.9.8)
+# MindForge FAQ (v12.0.0)
 
 ## Is MindForge tied to Claude only?
 No. MindForge supports Claude Code and Antigravity. Install with `--claude`,
@@ -55,7 +55,7 @@ The `deep-research` workflow was removed before the v11.8.0 release (the superpo
 ## Version & Stability
 
 **Q: What version is current?**
-v11.9.8 — verify with `node bin/mindforge-cli.js --version`
+v12.0.0 — verify with `node bin/mindforge-cli.js --version`
 
 **Q: Was v11.9.0 production-stable?**
 At that release: yes, by the IQ200 deep-audit (258 discrete checks across 14 dimensions),

package/docs/getting-started.md

@@ -1,4 +1,4 @@
-# MindForge — Getting Started (v11.9.8)
+# MindForge — Getting Started (v12.0.0)
 
 This guide gets you from zero to a working MindForge project in under five minutes.
 
@@ -17,7 +17,8 @@ MindForge ships across several channels. Pick the one that matches how you work
 Zero-config setup that scaffolds the full framework:
 
 ```bash
-# Recommended (auto-detects your runtime)
+# Interactive wizard (TTY only) -- pre-selects a detected runtime, you confirm it.
+# Non-interactive/CI/piped invocations skip the wizard and default to --claude.
 npx mindforge-cc@latest
 
 # Antigravity (local development)
@@ -29,6 +30,11 @@ npx mindforge-cc@latest --claude --local
 
 After installation, the `mindforge` CLI command is available for runtime operations (health checks, security scans, headless execution, etc.).
 
+If a `CLAUDE.md` already exists in the target directory, the installer backs it up
+(`CLAUDE.md.backup-<timestamp>`) before writing its own — check that backup if you had custom
+content there. Hooks are snapshotted by Claude Code at session start, so if the harness was
+already open during install, restart it before expecting a newly-registered hook to fire.
+
 **Global install** (system-wide `/mindforge` commands for your primary AI coding runtime):
 
 ```bash
@@ -114,7 +120,7 @@ Or use slash commands: `/mindforge:wf-code-audit`
 ## Your First 5 Minutes with MindForge
 
 1. **Verify install:** `node bin/mindforge-cli.js health`
-2. **Check version:** `node bin/mindforge-cli.js --version` (should print `11.9.8`)
+2. **Check version:** `node bin/mindforge-cli.js --version` (should print `12.0.0`)
 3. **List workflows:** `node bin/mindforge-cli.js workflow list`
 4. **Run first slash command:** Open Claude Code → `/mindforge:status`
 5. **Onboard your codebase:** Open Claude Code → `/mindforge:wf-onboard-codebase`

package/docs/sdk-reference.md

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

package/docs/security/SECURITY.md

@@ -0,0 +1,14 @@
+# MindForge — Security Policy
+
+> This file used to duplicate the repo's security policy and had drifted out of sync (it was
+> still listing a `5.x.x`/`4.x.x`/`< 4.0.0` support table years behind the real `11.x` line). The
+> canonical, kept-current security policy — supported versions, vulnerability reporting process,
+> and the full "Security Features" / "Known Mitigations & Limitations" breakdown — lives at the
+> repo root: **[`/SECURITY.md`](../../SECURITY.md)**. Read that file, not this one.
+
+For the outward agentic-harness threat model (prompt injection, poisoned config/hooks/MCP,
+supply-chain risk in skills/agents, sandboxing) see
+**[`/MINDFORGE-AGENTIC-SECURITY.md`](../../MINDFORGE-AGENTIC-SECURITY.md)**.
+
+For the current, honestly-labeled status of Zero-Trust Agentic Identity specifically, see
+**[ZTAI Overview](./ZTAI-OVERVIEW.md)** — read its status banner first.

package/docs/security/ZTAI-OVERVIEW.md

@@ -0,0 +1,53 @@
+# Zero-Trust Agentic Identity (ZTAI) Overview
+
+> **STATUS: DESIGN DOCUMENT — NOT SHIPPED BEHAVIOUR.**
+>
+> Everything below describes an intended architecture. Measured against a live install:
+>
+> | Claim in this document | Reality |
+> |---|---|
+> | every agent action is cryptographically signed | **0 of 3116** audit entries carry a `signature` or `did` field |
+> | per-persona Ed25519 keypairs at spawn | `ztai-manager.js` can generate them; nothing calls it in a normal run |
+> | `.mindforge/identity` vault | not created by any install |
+> | every 50 entries triggers a Merkle-root | not a Merkle root — a linear cumulative fold — and nothing triggers it: `.planning/audit-archive/` contains only `.gitkeep`, the archiver has no caller outside tests |
+> | Merkle-root chain | `ztai-archiver.js:57` sets `merkleRoot: cumulativeHash` — a linear chain hash, not a hash tree |
+>
+> `ENABLE_ZTAI` has no readers in `bin/`. What IS real and independently verifiable is the SHA-256
+> hash chain in `.planning/AUDIT.jsonl` — see `SECURITY.md` for its actual guarantees and its one
+> documented gap. Treat this file as a roadmap, and `bin/` plus `tests/` as ground truth.
+
+MindForge v4.2 introduces **ZTAI Enterprise Mode**, an enterprise-grade identity layer that ensures every agent action is cryptographically signed and non-repudiable.
+
+## 1. Asymmetric Identity Model
+Every MindForge persona in the 32+ agent library is assigned a unique asymmetric key pair (Ed25519) upon project initialization or agent spawning.
+
+- **Private Key**: Stored securely in the local `.mindforge/identity` vault (never exposed).
+- **Public Key / DID**: Represented as a **Decentralized Identifier (DID)** in the format `did:mf:<key-fingerprint>`.
+
+## 2. Trust Tiers & Signing Requirements
+MindForge enforces tiered signing based on the risk level of the persona's actions.
+
+| Tier | Persona Examples | Signing Tech | Integrity Proof |
+| :--- | :--- | :--- | :--- |
+| **T0** | `mf-researcher`, `mf-query` | None | Audit log entry only. |
+| **T1** | `mf-executor`, `mf-coder` | Ed25519 (Software) | Signed JSON payload. |
+| **T2** | `security-auditor`, `ui-specialist` | Ed25519 (Software) | Signed Block + Peer Review. |
+| **T3** | `mf-planner`, `system-architect` | **Secure Enclave (HSM)** | Enclave-attested signature. |
+
+*Note: T3 agents utilize a simulated hardware-secured enclave (HSM) to ensure principal-level accountability.*
+
+## 3. Non-Repudiable Audit Manifests
+The `ZTAIArchiver` generates high-fidelity integrity proofs for the session history.
+
+- **Cumulative Chain Root**: Every 50 audit entries would trigger a cumulative SHA-256 chain hash over the block. It is a linear fold, not a Merkle tree — no hash tree, no inclusion proof — though `ztai-archiver.js:57` still names the field `merkleRoot`.
+- **Manifest Finalization**: The cumulative root of all audit entries is signed by the **Principal Agent (T3)**.
+- **Tamper Detection**: Inside a block a manifest covers, `verifyIntegrity()` fails closed. Mutating or reordering an entry changes the recomputed root (`ztai-archiver.js:156`), and adding, deleting, or truncating *into* the block trips the `entryCount` check (`ztai-archiver.js:148`) — measured: dropping 3 of 10 covered entries throws `block entry count mismatch`. What it does **not** cover is anything outside the block: the manifest selects entries by the `[blockStart, blockEnd]` timestamp window (`ztai-archiver.js:141`), so entries appended after the last finalized `blockEnd` are never selected, and truncating that uncovered tail is invisible — measured: dropping all 4 uncovered entries still returns valid. This is a **separate mechanism** from the `previous_hash` back-link chain in `.planning/AUDIT.jsonl`; the archiver contains zero references to `previous_hash`. `bin/verify-audit.js` has its own, different tail-truncation gap, for the unrelated reason that any prefix of a back-linked chain is itself a valid chain. Nothing raises an alert for either today — the archiver has no caller outside tests.
+
+## 4. Key Provider Abstraction
+The `ZTAIManager` uses a pluggable `KeyProvider` architecture:
+- `FileSystemProvider`: Standard key storage for T1/T2 agents.
+- `SecureEnclaveProvider`: Simulates hardware-backed signing for T3 agents.
+- `KMSProvider` (Future): Integration with AWS/GCP/Azure Key Management Services.
+
+## 5. Governance Integration
+ZTAI identities are verified during the `/mindforge:verify-phase` and `/mindforge:ship` processes. High-tier changes will be BLOCKED if the cryptographic signatures are missing or invalid.

package/docs/security/penetration-test-results.md

@@ -0,0 +1,36 @@
+# MindForge v1.0.0 — Penetration Test Results
+
+> **STATUS: HISTORICAL — scoped to the v1.0.0-era predecessor system, not the current v11.x
+> architecture.** These findings have not been re-run against the live `bin/` runtime. Retained
+> for historical reference only. For current security status, see the root
+> [`SECURITY.md`](../../SECURITY.md).
+
+**Date:** 2026-03-22
+**Scope:** MindForge v1.0.0 threat model (7 threat actors)
+**Method:** Manual adversarial review + targeted negative tests
+
+## Summary
+- Critical findings: 0
+- High findings: 0
+- Medium findings: 2
+- Low findings: 3
+
+All findings were addressed or documented with explicit mitigations.
+
+## Findings
+| ID | Severity | Area | Description | Status |
+|---|---|---|---|---|
+| PT-01 | MEDIUM | Plugin system | Malicious plugin can request `write_state` permission | Mitigated: allowlist (`ELEVATED_PLUGINS`) + user approval |
+| PT-02 | MEDIUM | Skill registry | Injection patterns could bypass simple string match | Mitigated: injection guard + manual review guidance |
+| PT-03 | LOW | SSE stream | Local process can subscribe to localhost stream | Accepted: localhost-only + no secrets in stream |
+| PT-04 | LOW | Config | User-controlled git email for approvals | Accepted: governance assumption, documented |
+| PT-05 | LOW | CI | Workflow modification could bypass gates | Accepted: branch protection required |
+
+## Retest notes
+- Re-validated installer excludes `.env`, `.key`, `.pem` files
+- Verified migration restores from backup on failure
+- Confirmed plugin loader skips incompatible plugins and logs audit entry
+
+## Conclusion
+MindForge v1.0.0 is fit for public release with known, documented trade-offs.
+See `docs/security/threat-model.md` for full controls and residual risk.