mindforge-cc 11.9.8 → 12.0.0

package/docs/security/threat-model.md

@@ -0,0 +1,148 @@
+# MindForge v1.0.0 — Threat Model
+
+> **STATUS: HISTORICAL — scoped to the v1.0.0-era predecessor system (March 2026), not the
+> current v11.x architecture.** File/asset paths, the plugin model, and the enumerated threat
+> actors below describe that earlier, materially smaller system. It is retained for historical
+> reference only and has not been re-reviewed against the live `bin/` runtime. For what is
+> actually enforced today, see the root [`SECURITY.md`](../../SECURITY.md).
+
+## Scope
+All attack surfaces introduced by MindForge across 7 days of development.
+Last reviewed: v1.0.0 release (March 2026).
+
+## Assets being protected
+
+| Asset | Classification | Location |
+|---|---|---|
+| API credentials | CRITICAL | Environment variables only (never in files) |
+| HANDOFF.json | HIGH — project state, agent notes, decisions | `.planning/HANDOFF.json` |
+| AUDIT.jsonl | HIGH — complete governance audit trail | `.planning/AUDIT.jsonl` |
+| Approval files | HIGH — governance records | `.planning/approvals/*.json` |
+| SECURITY.md | MEDIUM — security policy documentation | `.mindforge/org/SECURITY.md` |
+| CLAUDE.md | MEDIUM — agent instructions that shape behaviour | `.claude/CLAUDE.md` |
+| CONVENTIONS.md | LOW — coding standards | `.mindforge/org/CONVENTIONS.md` |
+
+## Threat Actor 1 — Malicious skill package author
+
+**Goal:** Inject adversarial instructions via a published `mindforge-skill-*` npm package.
+**Attack:** SKILL.md contains "IGNORE ALL PREVIOUS INSTRUCTIONS" or similar.
+**Controls:**
+- Injection guard in `loader.md` blocks known patterns at both install and load time
+- Level 1/2/3 skill validation at install time
+- TOCTOU-safe download (chmod 700 temp dir, tarball size check)
+- User must explicitly run `/mindforge:install-skill` — no auto-install
+
+**Residual risk:** MEDIUM — sophisticated injections that avoid simple string matching.
+**Mitigation:** Community review of public registry skills; organisation vetting of org-tier skills.
+
+---
+
+## Threat Actor 2 — MINDFORGE.md governance bypass
+
+**Goal:** Disable governance primitives via MINDFORGE.md settings.
+**Attack:** Set `SECRET_DETECTION=false`, `SECURITY_AUTOTRIGGER=false`.
+**Controls:**
+- Non-overridable rules enforced in CLAUDE.md session start protocol
+- MINDFORGE-SCHEMA.json marks these fields as `nonOverridable: true`
+- `bin/validate-config.js` warns on attempts to override these fields
+
+**Residual risk:** LOW — enforced at the agent instruction layer, not OS level.
+**Note:** An agent that ignores its CLAUDE.md is an agent that ignores everything.
+
+---
+
+## Threat Actor 3 — Accidental credential exposure in project files
+
+**Goal:** Not adversarial — developer accidentally commits a credential.
+**Attack vectors:**
+- Token pasted into HANDOFF.json
+- API key in MINDFORGE.md ADDITIONAL_AGENT_INSTRUCTIONS
+- Secret in AUDIT.jsonl via an error message
+
+**Controls:**
+- Gate 3 (secret detection) blocks ANY commit with credential patterns
+- `_warning` field in every HANDOFF.json schema reminding devs not to store secrets
+- Health engine (Category 7) scans .planning/ and root files for credential patterns
+- installer-core.js skips .env and *.key files during copyDir
+
+**Residual risk:** LOW — multiple detection layers with complementary coverage.
+
+---
+
+## Threat Actor 4 — TOCTOU attack on skill installation
+
+**Goal:** Replace a valid SKILL.md with malicious content in the window between download and validation.
+**Attack:** Race condition in temp directory.
+**Controls:**
+- `chmod 700` on temp directory (user-only access, blocks other OS users)
+- Tarball size check (detects empty/corrupted downloads)
+- Download → validate → install is a single-process, single-threaded operation
+
+**Residual risk:** VERY LOW — requires local machine compromise and precise timing.
+
+---
+
+## Threat Actor 5 — Compromised CI environment
+
+**Goal:** Bypass governance gates in CI to ship malicious code.
+**Attack:** Modify GitHub Actions workflow or CI runner environment to skip MindForge checks.
+**Controls:**
+- Gates run as separate CI jobs with explicit dependencies
+- Tier 3 changes always fail CI (cannot be configured away)
+- AUDIT.jsonl writes all gate results — tampering would require audit log manipulation
+- Branch protection rules on the repository (outside MindForge scope)
+
+**Residual risk:** HIGH — an attacker with write access to the workflow file or CI secrets
+can bypass. This is a threat to all CI systems, not MindForge specifically.
+**Mitigation:** Protect the `main` branch with required status checks.
+
+---
+
+## Threat Actor 6 — SSE event stream eavesdropping
+
+**Goal:** Read sensitive project state from the real-time event stream.
+**Attack:** Connect to port 7337 from another local process.
+**Controls:**
+- localhost-only binding (127.0.0.1) — not accessible from network
+- IP address check on every connection — non-localhost rejected with 403
+- CORS exact-origin matching (not wildcard)
+- Port only opens when the SDK's `MindForgeEventStream.start()` is explicitly called
+
+**Residual risk:** LOW — any process running as the same OS user can connect to localhost.
+**Mitigation:** The SSE stream exposes AUDIT entries, not credentials. Risk is information disclosure, not code execution.
+
+---
+
+## Threat Actor 7 — Plugin with elevated or undeclared permissions
+
+**Goal:** Use a MindForge plugin to exfiltrate project state or modify governance.
+**Attack:** Install a plugin that reads HANDOFF.json and sends it to an external server.
+**Controls:**
+- Permission model displayed to user at install time (requires explicit approval)
+- Injection guard run against all plugin .md files
+- All plugin-triggered actions logged with plugin name as agent in AUDIT.jsonl
+- `ELEVATED_PLUGINS` allowlist required for `write_state: true` permission
+
+**Residual risk:** MEDIUM — a user who installs a malicious plugin and approves its permissions.
+**Mitigation:** Only install plugins from sources you trust. Review plugin commands before installing.
+Treat MindForge plugins like VSCode extensions — they have significant project access.
+
+---
+
+## Controls summary matrix
+
+| Control | Threat Actors Mitigated |
+|---|---|
+| Injection guard (loader.md) | TA1, TA7 |
+| TOCTOU-safe download (chmod 700) | TA1, TA4 |
+| Non-overridable governance primitives | TA2 |
+| Gate 3 secret detection | TA3 |
+| Health engine credential scan | TA3 |
+| CI Tier 3 block | TA5 |
+| SSE localhost-only binding | TA6 |
+| Plugin permission model + AUDIT logging | TA7 |
+
+## Penetration test results
+
+See `docs/security/penetration-test-results.md` for the adversarial review
+conducted as part of the v1.0.0 production readiness process.

package/docs/troubleshooting.md

@@ -1,4 +1,4 @@
-# MindForge Troubleshooting (v11.9.8)
+# MindForge Troubleshooting (v12.0.0)
 
 This page lists common issues and fast fixes. If you get stuck, start with
 `/mindforge:health`.
@@ -23,18 +23,20 @@ Look for `CLAUDE.md.backup-<timestamp>` and merge your content.
 **Fix:** Verify the install location:
 - Claude Code: `~/.claude/commands/mindforge/`
 - Antigravity: `~/.gemini/antigravity/mindforge/`
-Run `/mindforge:health --repair`.
+`--repair` doesn't run an automated fix — it's a documented flag that isn't wired into the CLI
+backing path, silently ignored (byte-identical output to plain `health`). Re-run the install
+command with `--force` instead, or restore the missing directory from git/backup.
 
 ---
 
 ## 2. Health check failures
 
 ### CLAUDE.md drift detected
-**Fix:**
-```
-/mindforge:health --repair
-```
-This restores the canonical MindForge CLAUDE.md.
+**Fix:** `/mindforge:health --repair` is documented in the command spec but not wired into the
+CLI backing path — it's silently ignored, byte-identical output to plain `health`. No automated
+repair exists today. Restore the canonical file yourself: look for a
+`CLAUDE.md.backup-<timestamp>` the installer wrote on your last run, or re-run
+`npx mindforge-cc@latest --claude --local --force`.
 
 ### Missing .planning files
 **Fix:**
@@ -101,7 +103,8 @@ rerun migration. See `.mindforge/audit/AUDIT-SCHEMA.md` for expected format.
 - Reduce file reads or limit to ranges
 - Keep PLAN `<action>` lean (150–400 words)
 - Limit full skill injections to 3
-- Use `/mindforge:tokens --profile`
+- Use `/mindforge:tokens --optimise` (`--profile` doesn't exist; real flags are `--phase N`,
+  `--session ID`, `--window short|medium|long`, `--optimise`)
 
 ---
 
@@ -128,8 +131,9 @@ follow, not a command.
 
 ### Workspace isolation failure
 **Symptom:** Conflicts between feature branches or dirty worktree.
-**Fix:** Run `/mindforge:workspace` to inspect worktree state. Use `/mindforge:health --repair` if
-`.git/worktrees/` is corrupt.
+**Fix:** Run `/mindforge:workspace` to inspect worktree state. `/mindforge:health --repair` does
+not actually run an automated fix (the flag is silently ignored) — if `.git/worktrees/` is
+corrupt, run `git worktree prune` and remove the affected worktree directory manually.
 
 ---
 

package/docs/user-guide.md

@@ -1,8 +1,8 @@
-# MindForge User Guide (v11.9.8)
+# MindForge User Guide (v12.0.0)
 
 This guide gets you from install to productive, with the minimum needed to run MindForge in a real project.
 
-> **v11.9.8 Stats:** 35 workflows · 221 slash commands · 232 engine skills · 216 personas · 0 CVEs · 258/258 IQ200 checks passing
+> **v12.0.0 Stats:** 35 workflows · 221 slash commands · 232 engine skills · 216 personas · 0 CVEs · 258/258 IQ200 checks passing
 
 ## Prerequisites
 
@@ -35,6 +35,11 @@ npx mindforge-cc --antigravity --local
 npx mindforge-cc --runtime <name>
 ```
 
+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.
+
 ### Post-Install: The `mindforge` CLI
 
 After installation, the `mindforge` binary is available for runtime commands:
@@ -44,7 +49,7 @@ mindforge health          # Verify project integrity
 mindforge security-scan   # Run security checks
 mindforge headless        # Run agent in non-interactive mode
 mindforge --verbose ...   # Enable verbose output for debugging
-mindforge --version       # Print installed version (e.g. 11.9.8) and exit 0
+mindforge --version       # Print installed version (e.g. 12.0.0) and exit 0
 ```
 
 Use `--verbose` (or `-v`) on any command for detailed diagnostic output. Use `--version` (or `-V`) to print the installed version and exit.
@@ -59,11 +64,10 @@ Open your agentic runtime (Claude Code, Antigravity, etc.) in your project direc
 /mindforge:health
 ```
 
-If health reports issues, run:
-
-```bash
-/mindforge:health --repair
-```
+If health reports issues: `--repair` is documented in the command spec but not wired into the
+CLI backing path — it's silently ignored, byte-identical output to plain `health`. No automated
+repair exists today; address what the health report flags manually, or re-run the install with
+`--force`.
 
 ## 3. Initialize a New Project
 

package/docs/usp-features.md

@@ -0,0 +1,60 @@
+# MindForge — Key Features
+
+This page used to describe MindForge as a "Sovereign Agentic OS" with 16 "Pillars of Celestial
+Intelligence," CADIA, PQAS, and hardware-attested biometric gates. None of that is real —
+`SwarmController`, `PersonaFactory`, and `WaveExecutor` are role names in markdown specs, not
+importable code; the "Post-Quantum Agentic Security" and "Sovereign Reason Enclave" modules are
+explicitly self-labeled SIMULATED in their own source (`bin/governance/quantum-crypto.js`,
+`bin/governance/ztai-manager.js`), gated off the live trust path by default; and no biometric or
+HSM-backed gate exists anywhere in `bin/`. See *What is actually enforced* in the root
+[README](../README.md) for the same honesty pass applied to the whole project.
+
+What follows is what's actually shipped, in the same "measured, not asserted" spirit.
+
+## Governance you can verify
+
+- **File-driven behavior.** Commands, skills, and personas are markdown the model reads and acts
+  on — advisory by design, auditable like any other file in the repo.
+- **A real, tamper-evident audit log.** `.planning/AUDIT.jsonl` is a SHA-256 hash chain -- not a Merkle tree (no hash tree, no inclusion proof; that terminology has been retired),
+  verifiable with `node bin/verify-audit.js`.
+  It detects mutation and mid-file deletion; it does not detect tail truncation, and it is not
+  rotated (an earlier rotation mechanism broke the chain and was removed — the file grows
+  unbounded by design).
+- **Hooks that can actually block a tool call, on Claude Code.** See *What is actually enforced*
+  in the README for the exact current state per install channel.
+- **Real Ed25519 signing** for the parts of the trust chain that are live (`ztai-manager.js`).
+  Post-quantum signing is an explicitly-simulated, opt-in demo, not a production security
+  boundary.
+
+## Execution
+
+- **Slash-command lifecycle**: `/mindforge:init-project` → `/mindforge:plan-phase` →
+  `/mindforge:execute-phase` → `/mindforge:verify-phase` → `/mindforge:ship`. Each step is a
+  markdown prompt the assistant follows using its own tools against `.planning/` state files.
+- **35 dynamic multi-agent workflows** (`.mindforge/dynamic-workflows/`), invoked via the
+  `wf-*` slash commands or `node bin/mindforge-cli.js workflow run <name>` — these are real,
+  executable Node scripts, not prose.
+- **A council command** (`/mindforge:council`) that runs a real 4-voice (architect/skeptic/
+  pragmatist/critic) model debate via `bin/engine/council-runtime.js`.
+
+## Memory
+
+- **A local-first knowledge store and graph** (`bin/memory/`) with TF-IDF/BM25 retrieval and a
+  unified SQLite store (`sql.js`, zero native deps) for traces, skills, and remediations.
+- **`mindforge-sdk`** exposes a standalone, dependency-free client for reading project state and
+  the knowledge graph (`MindForgeClient`, `MindForgeMemory`) — see
+  [docs/References/sdk-api.md](References/sdk-api.md).
+
+## Observability
+
+- **A local dashboard** (`node bin/dashboard/server.js`, `127.0.0.1:7339`) — bearer-token
+  auth, rate-limited, CSP-hardened — showing audit stream, cost/token usage, and project health.
+
+## What's experimental or not wired up yet
+
+Being direct about this rather than silent: the autonomous wave-execution engine
+(`bin/autonomous/`), the FinOps/multi-cloud arbitrage layer, RBAC/ZTAI-archiver, and a few other
+subsystems are fully built and unit-tested but not yet constructed from any live command path —
+`/mindforge:auto` today is an LLM-interpreted markdown spec, not a call into that engine. If you
+need one of these to be load-bearing, check `bin/` and the test suite before relying on it, or
+open an issue.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindforge-cc",
-  "version": "11.9.8",
+  "version": "12.0.0",
   "description": "Agentic intelligence framework for Claude Code and Antigravity: slash commands, subagents, skills, hooks, governance, memory, and cost-aware model routing for AI-driven development.",
   "bin": {
     "mindforge-cc": "bin/install.js",
@@ -19,6 +19,7 @@
     ".mindforge/config.json",
     ".mindforge/imported-agents.jsonl",
     ".mindforge/engine/",
+    "!.mindforge/engine/instincts/instinct-store.jsonl",
     ".mindforge/manifests/",
     ".mindforge/schemas/",
     ".mindforge/personas/",
@@ -47,10 +48,13 @@
     "docs/faq.md",
     "docs/References/",
     "docs/Templates/",
+    "docs/usp-features.md",
+    "docs/security/",
     "examples/",
     "CHANGELOG.md",
     "changelogs/",
     "LICENSE",
+    "MINDFORGE-AGENTIC-SECURITY.md",
     "MINDFORGE.md",
     "README.md",
     "RELEASENOTES.md",

package/subagents/README.md

@@ -0,0 +1,38 @@
+# Subagents
+
+164 Claude-Code-native subagent definitions across 10 categories under `categories/`,
+installable individually via the marketplace packs in `.claude-plugin/marketplace.json` or
+by name via `bin/spawn-agent.js subagent <name>`.
+
+## Attribution
+
+152 of these 164 definitions are adapted from
+[VoltAgent's `awesome-claude-code-subagents`](https://github.com/VoltAgent/awesome-claude-code-subagents),
+used here under its MIT license:
+
+> MIT License
+>
+> Copyright (c) 2025 VoltAgent
+>
+> Permission is hereby granted, free of charge, to any person obtaining a copy
+> of this software and associated documentation files (the "Software"), to deal
+> in the Software without restriction, including without limitation the rights
+> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+> copies of the Software, and to permit persons to whom the Software is
+> furnished to do so, subject to the following conditions:
+>
+> The above copyright notice and this permission notice shall be included in all
+> copies or substantial portions of the Software.
+>
+> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+> SOFTWARE.
+
+16 filenames were suffixed `-cc` on import to avoid colliding with MindForge's own
+hand-authored personas of the same name (e.g. `api-designer-cc.md` alongside VoltAgent's
+`api-designer.md`) — see `scripts/build-subagent-plugins.js`. The remaining 12 subagents
+under `categories/` have no VoltAgent counterpart and are original MindForge content.