mindforge-cc 11.9.8 → 11.9.9

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 (v11.9.9)
 
 ## 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`
+v11.9.9 — 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 (v11.9.9)
 
 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 `11.9.9`)
 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: `11.9.9`
 
 ---
 
-## SDK Exports (v11.9.8)
+## SDK Exports (v11.9.9)
 
 ```javascript
 const {
@@ -28,7 +28,7 @@ const {
   commands,               // Command registry
   batch,                  // Batch execution
   MindForgeMemory,        // Memory interface
-  VERSION                 // '11.9.8'
+  VERSION                 // '11.9.9'
 } = 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.

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 (v11.9.9)
 
 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 (v11.9.9)
 
 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
+> **v11.9.9 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. 11.9.9) 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