mindforge-cc 8.2.0 → 10.0.0

package/docs/security/threat-model.md

@@ -1,142 +0,0 @@
-# MindForge v1.0.0 — Threat Model
-
-## 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/skills-authoring-guide.md

@@ -1,176 +0,0 @@
-# MindForge Skills Authoring Guide
-
-## What is a skill?
-
-A skill is a self-contained folder containing a `SKILL.md` file that gives
-the MindForge agent domain-specific expertise for a specific type of task.
-
-Skills are loaded just-in-time: MindForge discovers them by matching trigger
-keywords against the task description. They inject the right knowledge at the
-right moment without cluttering the context with irrelevant information.
-
-## When to write a skill
-
-Write a new skill when:
-
-- A specific domain requires knowledge beyond the agent's defaults
-- The same guidance needs to be applied consistently across many tasks
-- Your team has standards that aren't captured in CONVENTIONS.md
-- An existing core skill doesn't match your organisation's approach
-
-## Automated Skill Generation (New in v2)
-
-MindForge can now generate skills automatically. Instead of writing `SKILL.md` from scratch, use the intelligent learning engine:
-
-### 1. Learn from Documentation
-
-```bash
-/mindforge:learn https://react.dev/learn "react-best-practices"
-```
-
-The agent will research the URL, extract high-value engineering patterns, and generate a high-quality `SKILL.md` with examples and triggers.
-
-### 2. Learn from Project History
-
-```bash
-/mindforge:learn ./src/modules/auth "auth-patterns"
-```
-
-This analyzes your codebase and session history to capture project-specific expertise.
-
-### 3. Community Marketplace
-
-```bash
-/mindforge:marketplace search "performance"
-/mindforge:marketplace install mindforge-skill-latency-optimizer
-```
-
-Discover and install verified skills from the MindForge community.
-
-## Skill file structure
-
-```text
-.mindforge/skills/[skill-name]/
-    SKILL.md          ← required
-    examples/         ← optional: sample inputs and outputs
-    resources/        ← optional: reference documents the skill uses
-    scripts/          ← optional: helper scripts the skill can run
-```
-
-## SKILL.md template
-
-```markdown
----
-name: [skill-name-in-kebab-case]
-version: 1.0.0
-min_mindforge_version: 0.1.0
-status: stable | beta | alpha
-triggers: [comma-separated list of trigger keywords]
-mutually_exclusive_with:   # optional: skill names that conflict with this one
-breaking_changes:
-  # Record breaking changes here when bumping MAJOR version
-changelog:
-  - "1.0.0: Initial release"
----
-
-# Skill — [Human-readable skill name]
-
-## When this skill activates
-
-[One paragraph: what task types trigger this skill, and why it helps]
-
-## Mandatory actions when this skill is active
-
-### Before writing any code / Before starting any task
-
-[Steps the agent MUST take before beginning — written as an ordered list]
-
-### During [implementation / review / analysis]
-
-[Standards and patterns the agent must follow — be specific]
-
-### After [implementation / review / analysis]
-
-[Verification steps, output requirements — be specific]
-
-## [Domain-specific section 1]
-
-[Detailed guidance, code examples, patterns]
-
-## [Domain-specific section 2]
-
-[Detailed guidance, code examples, patterns]
-
-## Self-check before task completion
-
-- [ ] [Checkable item 1]
-- [ ] [Checkable item 2]
-- [ ] [Checkable item 3]
-
-## Output
-
-[What files or artifacts this skill produces, with exact paths]
-```
-
-## Writing Good Trigger Keywords
-
-- Specific beats generic: `argon2` beats `hash`
-- Include common misspellings and abbreviations: `optimise, optimize`
-- Include acronyms and their expansions: `a11y, accessibility, WCAG, wcag`
-- Include library names: `Prisma, Drizzle, SQLAlchemy` for database-patterns
-- Aim for 10-30 triggers per skill
-- Avoid single-letter words and extremely common words (the, be, is, to)
-
-## Security Notice for Skill Authors
-
-MindForge skills are injected directly into AI agent contexts. A skill file
-with adversarial content could manipulate agent behaviour.
-
-MindForge includes an injection guard that blocks skills containing known
-manipulation patterns. However, all skill authors — especially for Tier 2
-and Tier 3 skills — should:
-
-1. Never include instructions that override or disable safety behaviours
-2. Keep skill files in version control with a clear audit trail
-3. Review skill changes in code review before merging
-4. Restrict who can write to `.mindforge/personas/overrides/` and
-   `.mindforge/org/skills/` directories
-
-## Registering Your Skill
-
-After creating SKILL.md:
-
-```bash
-/mindforge:skills add .mindforge/skills/[your-skill-name]
-# Choose tier: 2 (org) or 3 (project)
-# Commit the manifest update
-```
-
-### Quality Scoring
-
-All skills (automated or manual) are passed through the **7-Dimension Scorer**. To manually score a skill:
-
-```bash
-/mindforge:skills validate .mindforge/skills/[your-skill]
-```
-
-A minimum score of **60** is required for registration.
-
-## Tier Guidance
-
-| Tier | Scope | Local Path | Description |
-| :--- | :--- | :--- | :--- |
-| **1 (Core)** | Platform | `.mindforge/skills/` | Universal engineering best practices across all stacks. |
-| **2 (Org)** | Enterprise | `.mindforge/org/skills/` | Corporate standards, security policies, and internal libraries. |
-| **3 (Project)** | Repository | `.agent/skills/` | Local project conventions, module patterns, and specific logic. |
-
-> [!NOTE]
-> Lower tiers (Project) override higher tiers (Org/Core) when skill names or triggers conflict, allowing for project-level specialization of global rules.
-
-## Version Your Skill
-
-Every change to mandatory actions or trigger keywords = MINOR version bump.
-Every removal of triggers or outputs = MAJOR version bump.
-Typo fixes = PATCH version bump.
-
-Update both the SKILL.md frontmatter AND the MANIFEST.md entry.

package/docs/skills-publishing-guide.md

@@ -1,22 +0,0 @@
-# MindForge Skills Publishing Guide
-
-## Overview
-Skills are distributed as npm packages with the `mindforge-skill-` prefix.
-
-## Required files
-- `SKILL.md`
-- `package.json` with `mindforge` metadata
-- `README.md`
-- `CHANGELOG.md`
-
-## Publish checklist
-1. Run `/mindforge:skills validate ./SKILL.md --quality`
-2. Verify `package.json` metadata is complete
-3. Ensure `CHANGELOG.md` includes the current version
-4. Run `npm pack --dry-run` to inspect files
-5. Publish with `/mindforge:marketplace publish` (handles pre-flight scoring)
-   - Or manually via `npm publish --access public`
-
-## Private registries
-Set `MINDFORGE_SKILL_REGISTRY` in `.mindforge/org/integrations/INTEGRATIONS-CONFIG.md`
-for private registries (Verdaccio, Artifactory, GitHub Packages).

package/docs/team-setup-guide.md

@@ -1,21 +0,0 @@
-# MindForge Team Setup Guide
-
-## Step 1 — Configure approvers
-Set approvers in `.mindforge/org/integrations/INTEGRATIONS-CONFIG.md` and
-governance config.
-
-## Step 2 — Profile team
-Run:
-`/mindforge:profile-team --questionnaire`
-
-## Step 3 — Branch strategy
-Set branch strategy in `MINDFORGE.md`, for example:
-- `BRANCHING_STRATEGY=phase`
-- `PHASE_BRANCH_TEMPLATE=feat/phase-{N}-{slug}`
-
-## Step 4 — Coordinate ownership
-Use `HANDOFF.json` and plan files to avoid overlapping write scopes.
-
-## Ethics policy
-Per ADR-014 and TEAM-PROFILE policy, metrics are for process and system
-improvement only, not individual performance evaluation.

package/docs/testing-current-version.md

@@ -1,130 +0,0 @@
-# MindForge v2.0.0-alpha.10: In-Depth Testing Guide (Antigravity)
-
-This document provides a step-by-step rigorous testing flow to validate the entire MindForge framework from a blank project state. It is designed to be shared and logged for architectural review.
-
-## 🏁 Phase 0: Isolated Setup
-1. Create a new empty directory (e.g., `Mind-Forge-Test`): `mkdir Mind-Forge-Test && cd Mind-Forge-Test`
-2. **Linked Alpha Testing** (Simulated Live Publish):
-   - Use the **Absolute Binary Path** to bypass shell PATH configuration issues:
-     ```bash
-     /Users/sairamugge/.vite-plus/js_runtime/node/24.14.0/bin/mindforge-cc --antigravity --local
-     ```
-   - *Confirmation*: Run the command with `--version`. It must show `v2.0.0-alpha.10`.
-3. Verify the local binary exists: `ls agents/bin/install.js` (or `.agent/bin/install.js` if legacy)
-
-## 🏗 Phase 1: Registry & Integrity
-**Objective**: Verify that MindForge correctly registers the project and mirrors commands.
-
-**Command**:
-```bash
-./mindforge:init-project
-```
-
-**Post-Init Verification**:
-- Check `.claude/commands/mindforge/` and `.agent/commands/mindforge/`. They should be identical.
-- Verify the project is in the global registry (optional):
-  ```bash
-  cat ~/.mindforge/registry.json
-  ```
-**Prompt to Agent**:
-> "Initialize this project for me. I am building a simple 'Weather Proxy API' in Node.js. Please set up the `.planning/` directory and registry."
-
-**Success Criteria**:
-- `.planning/PROJECT.md` is created with the Weather Proxy brief.
-- `.mindforge/` metadata directory is populated.
-
-## 📝 Phase 2: Workflow & Planning
-**Objective**: Test the planning engine and dependency mapping.
-
-**Prompt to Agent**:
-> "I need a plan to implement the weather service. Phase 1 should handle the API structure, Phase 2 should handle the weather fetching logic, and Phase 3 should add caching. Generate a detailed plan for Phase 1."
-
-**Command**:
-```bash
-/mindforge:plan-phase 1
-```
-
-**Success Criteria**:
-- `.planning/phases/phase-1/PLAN.md` is generated.
-- Plan status is set to `[ ]` in `task.md`.
-
-## 🤖 Phase 3: Autonomous Execution (The "Walk-Away" Test)
-**Objective**: Test the `/mindforge:auto` engine and state management.
-
-**Command**:
-```bash
-/mindforge:auto --phase 1
-```
-
-**Success Criteria**:
-- MindForge iterates through tasks without human intervention.
-- Code is written to the project (e.g., `index.js`, `routes/`).
-- `.planning/AUDIT.jsonl` is logging every execution step.
-
-## 📊 Phase 4: Observability (Dashboard)
-**Objective**: Test the Real-time Dashboard and SSE Bridge.
-
-**Command**:
-```bash
-/mindforge:dashboard --start --open
-```
-
-**Testing Steps**:
-1. Keep the dashboard open at `http://localhost:7339`.
-2. Run another command (e.g., `/mindforge:health`).
-3. Verify that the "Activity Feed" in the browser updates instantly.
-4. Check the "Metrics" tab for token spend data.
-
-## 🧠 Phase 5: Persistent Memory
-**Objective**: Test the Knowledge Graph retrieval.
-
-**Command**:
-```bash
-/mindforge:remember --search "api structure"
-```
-
-**Success Criteria**:
-- MindForge returns findings from the earlier `/mindforge:init-project` or `/mindforge:plan-phase` steps.
-
-## ⚔️ Phase 6: Multi-Model Hardening
-**Objective**: Test the adversarial cross-review system.
-
-**Command**:
-```bash
-/mindforge:cross-review
-```
-
-**Success Criteria**:
-- MindForge invokes secondary models (GPT/Gemini) to critique the code generated in Phase 3.
-- Review results are logged in `review_results.md`.
-
-## 🚢 Phase 7: Verification & Shipping
-**Objective**: Test the quality gates and release automation.
-
-**Commands**:
-```bash
-/mindforge:verify-phase 1
-/mindforge:ship 1
-```
-
-**Success Criteria**:
-- `CHANGELOG.md` is updated.
-- A PR-ready diff is generated.
-
----
-
-## 🛡 Phase 8: Framework Conflict Check
-**Objective**: Ensure MindForge is isolated from other frameworks.
-
-1. **Port Check**: Verify the dashboard is on `7339` and not conflicting with common framework ports (e.g., 8000, 8080).
-2. **Directory Check**: Ensure no other framework is writing to `.planning/` or `.mindforge/`.
-3. **Process Check**: Run `ps aux | grep mindforge` to ensure only one instance of the SSE bridge is active.
-
-## 📂 Logging for Review
-All Antigravity sessions are logged. To share your results for review, zip and send:
-- `.planning/AUDIT.jsonl` (Full execution history)
-- `CHANGELOG.md` (Outcome summary)
-## 💡 Troubleshooting
-- **Command not found**: Ensure you are using `./mindforge:command` or `/mindforge:command` within the agent.
-- **Wrong Version**: Run `/mindforge:health` and check for "v2.0.0-alpha.10". If it shows "v1.0.5", your installation failed or you are using the global `npx` version.
-- **Registry Error**: Check `~/.mindforge/registry.json` exists; it is now automatically created by the v2 installer.

package/docs/tutorial.md

@@ -1,162 +0,0 @@
-# MindForge v2.1.1 — Full Tutorial (Install → Advanced Usage)
-
-This tutorial walks a new user from installation to advanced usage. It is written for engineers who want to adopt MindForge in a real codebase.
-
----
-
-## 1. Install MindForge
-
-### Claude Code (local, per repo)
-
-```bash
-npx mindforge-cc@latest --claude --local
-```
-
-### Antigravity
-
-```bash
-npx mindforge-cc@latest --antigravity --local
-```
-
-### Specific Runtime (Universal)
-
-```bash
-npx mindforge-cc@latest --runtime <name>
-```
-
----
-
-## 2. Verify Installation
-
-Open your agentic runtime (Claude Code, Antigravity, etc.) in your repo and run:
-
-```bash
-/mindforge:health
-```
-
-If anything is wrong, run the repair command:
-
-```bash
-/mindforge:health --repair
-```
-
----
-
-## 3. Create a New Project
-
-```bash
-/mindforge:init-project
-```
-
-This command scaffolds the framework in `.agent/` and initializes project planning:
-
-- `.planning/PROJECT.md`: High-level vision and roadmap.
-- `.planning/REQUIREMENTS.md`: Functional and technical specs.
-- `.planning/STATE.md`: Real-time project health and milestone status.
-
----
-
-## 4. Onboarding an Existing Codebase
-
-```bash
-/mindforge:map-codebase
-```
-
-This command generates architectural insights:
-
-- `.planning/ARCHITECTURE.md`: Module relationships and data flow.
-- `.planning/CONVENTIONS.md`: Inferred coding styles and patterns.
-
----
-
-## 5. Unified Workflow (Phase 1)
-
-MindForge uses a 4-pillar iterative cycle:
-
-```bash
-/mindforge:plan-phase 1     # discuss → research → plan
-/mindforge:execute-phase 1  # parallel execution of task plans
-/mindforge:verify-phase 1   # UAT + automated validation
-/mindforge:ship 1           # generate release output + PR
-```
-
----
-
-## 6. High-Performance Personas
-
-MindForge v2.1.1 provides 32+ specialized personas. Each is a "digital twin" of a senior role.
-
-- To list all personas: `/mindforge:personas --list`
-- To switch persona: `/mindforge:personas --set executor`
-
----
-
-## 7. Real-time Dashboard
-
-Observable engineering is core to MindForge. Start the dashboard to see live agent activity:
-
-```bash
-/mindforge:dashboard --start --open
-```
-
-Visit `http://localhost:7339` for the premium web interface.
-
----
-
-## 8. Knowledge & Memory Management
-
-MindForge records architectural decisions to prevent regression.
-
-- Capture a note: `/mindforge:note "Preference: Use absolute imports for shared libs"`
-- Search memory: `/mindforge:remember --search "api patterns"`
-
----
-
-## 9. Self-Building Skills
-
-Learn new capabilities from documentation URL or local files:
-
-```bash
-/mindforge:learn https://docs.nextjs.org "nextjs-best-practices"
-```
-
----
-
-## 10. Security & Governance
-
-MindForge enforces strict compliance gates.
-
-```bash
-/mindforge:security-scan --deep
-```
-
-This checks for secrets, dependency vulnerabilities, and architectural drift.
-
----
-
-## 11. CI/CD Integration
-
-MindForge is designed for non-interactive execution in CI environments.
-
-- Set `CI=true` in your environment.
-- Use `/mindforge:ship --auto-pr` for automated delivery.
-
-See `docs/ci-cd-integration.md` for full pipeline examples.
-
----
-
-## 12. Troubleshooting
-
-If you hit issues, consult these specialized guides:
-
-- `docs/troubleshooting.md`: Common technical fixes.
-- `docs/faq.md`: Frequent questions and architectural patterns.
-- `docs/upgrade.md`: Migration guides between versions.
-
----
-
-## 13. Next Steps
-
-1. Configure your team preferences in `docs/Templates/Profile/user-profile.md`.
-2. Start your first Phase 1 planning.
-3. Join our community: `/mindforge:join-discord`.