mindforge-cc 1.0.5 → 2.0.0-alpha.6

package/.agent/CLAUDE.md

@@ -3,6 +3,29 @@
 
 ---
 
+## MULTI-MODEL INTELLIGENCE LAYER (v2.0.0 — Day 10)
+
+### Model Routing
+
+- Resolve model using `bin/models/model-router.js` based on persona and tier.
+- Tier 3 (Security) always uses `SECURITY_MODEL`.
+
+### API Client
+- Always use `bin/models/model-client.js` for API interactions.
+- Fallback chain: unavailable model → next in tier.
+
+### Cost Awareness
+- Record every call using `bin/models/cost-tracker.js`.
+- Block calls if `MODEL_COST_HARD_LIMIT_USD` is reached.
+
+### New Commands
+
+- `/mindforge:cross-review` — Adversarial multi-model review.
+- `/mindforge:research` — Deep research via Gemini 1M.
+- `/mindforge:costs` — Cost tracking dashboard.
+
+---
+
 ## DISTRIBUTION & CI LAYER (Day 6)
 
 ### CI mode awareness
@@ -93,6 +116,66 @@ Non-breaking additions (new optional fields, new commands) require MINOR.
 
 ---
 
+## AUTONOMOUS LAYER (Day 8 — v2.0.0-alpha.1)
+
+### Autonomous mode protocol
+When the user requests `/mindforge:auto --phase [N]`:
+1. Execute the pre-flight check from `.mindforge/engine/autonomous/auto-executor.md`.
+2. Follow the auto-executor state machine precisely.
+3. Every task must be performed by a fresh subagent context (context-compaction logic).
+4. Monitor every action for S01-S05 stuck patterns (stuck-detector.md).
+5. On failure: apply RETRY → DECOMPOSE → PRUNE logic (node-repair.md).
+6. Compliance Gate 3 (secrets) runs PRE-COMMIT on staged diffs.
+7. Visual Verification: runs <verify-visual> AFTER successful <verify> (unit tests).
+8. Governance: ESCALATE immediately on Tier 3 changes (Auth/Payment/PII).
+
+### Steering awareness
+Check `.planning/steering-queue.jsonl` at every task boundary.
+If guidance is present: inject it into the next PLAN file as the highest priority
+instruction. Standard governance gates still apply to steered changes.
+
+### Headless execution
+If `--headless` is used:
+- Disable all TTY-rich progress UI.
+- Structure all stdout as line-delimited JSON.
+- Handle SIGTERM by pausing execution and snapshotting HANDOFF.json.
+
+### New commands (Day 8)
+- /mindforge:auto — start/resume autonomous execution engine
+- /mindforge:steer — inject mid-execution guidance
+- /mindforge:browse — persistent browser control and actions
+- /mindforge:qa — systematic post-phase visual QA
+
+---
+
+## REAL-TIME DASHBOARD (v2.0.0 — Day 12)
+
+### Dashboard server
+The MindForge dashboard runs at localhost:7339 when started.
+- Start: `node bin/dashboard/server.js [--port 7339] [--open]`
+- Stop:  `/mindforge:dashboard --stop`
+
+Localhost-only (127.0.0.1) — consistent with ADR-017.
+Never bind to 0.0.0.0, never port-forward externally.
+
+### When to recommend the dashboard
+Suggest starting the dashboard when:
+- User runs /mindforge:auto (live progress visibility)
+- Team standup approaching (screenshare mode)
+- Tier 2/3 approvals are pending (approver can approve from browser)
+- Debugging a quality issue (metrics page shows trends)
+
+### AUDIT events written by dashboard
+- dashboard_started: on server start
+- dashboard_stopped: on graceful shutdown
+- approval_granted / approval_rejected: when approved via browser UI
+- steering_queued: when steering instruction sent via browser UI
+
+### New command (Day 12)
+- /mindforge:dashboard — start/stop/status the real-time web dashboard
+
+---
+
 ## IDENTITY
 
 You are a senior AI engineering agent operating under the **MindForge framework**.

package/.agent/mindforge/auto.md

@@ -0,0 +1,22 @@
+# /mindforge:auto [Phase N]
+
+**Purpose**: Starts the MindForge Autonomous Execution Engine for the
+specified phase. The agent will execute all waves, handle repairs, and
+perform compliance gates without requiring human confirmation.
+
+## Usage
+- `/mindforge:auto --phase 3` (Standard unattended mode)
+- `/mindforge:auto --resume` (Resumes from last checkpoint)
+- `/mindforge:auto --headless` (CI/CD optimized output)
+- `/mindforge:auto --dry-run` (Show the wave DAG and plan without executing)
+
+## Behavior
+- **Zero-Interaction**: Auto-approves Tier 1/2 changes if gates pass.
+- **Self-Repair**: Tries RETRY/DECOMPOSE before asking for help.
+- **Checkpointing**: Constant state persistence in `HANDOFF.json`.
+- **Governance**: ESCALATES on Tier 3 changes (Auth/Payment/PII).
+
+## Environment Variables
+- `AUTO_MODE_TIMEOUT_MINUTES`: Default 120.
+- `AUTO_PUSH_ON_WAVE_COMPLETE`: Default false.
+- `SLACK_WEBHOOK_URL`: Required for notifications.

package/.agent/mindforge/browse.md

@@ -0,0 +1,26 @@
+# /mindforge:browse
+
+## Usage
+`@mindforge browse <url | action>`
+
+## Description
+Controls the persistent MindForge browser daemon. 
+Maintains session state (cookies/localStorage) for the AI.
+
+## Actions
+| Action | Description |
+|---|---|
+| `--start` | Initialize browser daemon |
+| `--stop` | Kill browser daemon |
+| `--status` | Show daemon health and active sessions |
+| `--session <name>` | Switch browser context |
+| `--import-session <name> --from <browser>` | Import cookies from host browser (chrome, arc, etc) |
+| `<url>` | Navigate the current page to URL |
+| `click <selector>` | Trigger click event |
+| `type <sel> <text>` | Fill input field |
+| `screenshot` | Capture current viewport |
+
+## Security
+- Daemon binds to `127.0.0.1` only.
+- Session files are gitignored.
+- Use only for debugging and visual verification.

package/.agent/mindforge/costs.md

@@ -0,0 +1,11 @@
+# MindForge v2 — Costs Command
+# Usage: /mindforge:costs [--phase N] [--session ID] [--window 7d]
+
+## Purpose
+Real-time cost tracking for all AI model usage.
+Enforce daily budgets and see per-model spend.
+
+## Metrics
+- Total spend: $X.XX
+- Daily limit usage: XX%
+- Per-model breakdown (Tokens/Cost)

package/.agent/mindforge/cross-review.md

@@ -0,0 +1,17 @@
+# MindForge v2 — Cross-Review Command
+# Usage: /mindforge:cross-review [--phase N] [--models list] [--focus area]
+
+## Purpose
+Get the same code diff reviewed by multiple AI models simultaneously.
+Claude finds what Claude finds. GPT-4o finds what GPT-4o finds.
+Consensus findings = high confidence issues.
+
+## Round 1: Primary (Claude)
+Senior architect review.
+
+## Round 2: Adversarial (GPT-4o)
+Critical security and edge case review.
+
+## Synthesis
+Consensus detector filters findings.
+Verdict is gating for `/mindforge:ship`.

package/.agent/mindforge/dashboard.md

@@ -0,0 +1,98 @@
+# MindForge v2 — Dashboard Command
+# Usage: /mindforge:dashboard [--port 7339] [--open] [--stop] [--status]
+# Version: v2.0.0-alpha.5
+
+## Purpose
+Start the MindForge real-time web dashboard — a live observability UI for the
+entire team. Shows execution progress, quality metrics, pending approvals,
+knowledge graph, and team activity without requiring CLI access.
+
+## Design
+The dashboard is a localhost-only web server:
+- No build step — single HTML file, no bundler, no npm packages on client
+- No authentication — binding to 127.0.0.1 is the security model
+- Live updates via Server-Sent Events — no WebSocket library needed
+- Designed for screensharing at standups, not external access
+
+## Usage
+
+### Start the dashboard
+```
+/mindforge:dashboard
+→ Dashboard running at: http://localhost:7339
+→ Press CTRL+C to stop (or /mindforge:dashboard --stop)
+```
+
+### Start and open in browser
+```
+/mindforge:dashboard --open
+→ Opens http://localhost:7339 in your default browser
+```
+
+### Custom port
+```
+/mindforge:dashboard --port 7340
+→ Useful if 7339 is already in use
+```
+
+### Stop the dashboard
+```
+/mindforge:dashboard --stop
+→ Finds the running dashboard process (from PID file) and sends SIGTERM
+```
+
+### Check dashboard status
+```
+/mindforge:dashboard --status
+→ Checks if dashboard is running, shows port and PID
+→ Also shows: http://localhost:7339/api/status
+```
+
+## Dashboard pages
+
+### Activity (default)
+- Phase name, auto mode status (RUNNING/PAUSED/ESCALATED/IDLE)
+- Wave progress bar (tasks completed / total)
+- Live AUDIT event feed with color-coded event types
+- Steering input: send guidance to auto mode without touching the CLI
+
+### Quality Metrics
+- Session quality score trend (last 20 sessions)
+- Verify pass rate over time
+- Security findings by severity (CRITICAL/HIGH/MEDIUM/LOW)
+- Cost per session trend
+
+### Approvals
+- All pending Tier 2/3 governance requests
+- [Approve] and [Reject] buttons — no CLI needed for approval
+- Tier, phase/plan, description, time since requested, expiry warning
+- Recent approval history
+
+### Knowledge
+- Search the knowledge graph from the browser
+- Entries filtered by confidence, type, tags
+- Color-coded by knowledge type
+
+### Team
+- Active developers (by git email, from AUDIT.jsonl)
+- What each person is working on (last task)
+- File conflict warnings (two developers recently touching the same file)
+
+## Security rules
+1. Never expose the dashboard on 0.0.0.0 — localhost only
+2. Never forward the port externally (no ngrok, no port forwarding)
+3. For remote team visibility: screenshare your browser instead
+4. The dashboard shows project details including code patterns and decisions
+
+## Integration with auto mode
+When `/mindforge:auto` is running and the dashboard is open:
+- Activity feed updates live as tasks complete
+- Wave progress bar advances in real-time
+- Any escalations appear immediately with red indicator
+- The Steering input is active — inject guidance without a second terminal
+
+## AUDIT entry
+```json
+{ "event": "dashboard_started", "port": 7339, "pid": 12345 }
+{ "event": "dashboard_stopped", "pid": 12345 }
+```

package/.agent/mindforge/execute-phase.md

@@ -76,9 +76,11 @@ Write to console:
 For each plan in the wave:
 1. Load context package (per `context-injector.md`)
 2. Execute the plan instructions
-3. Run `<verify>` — capture exact output
-4. If verify PASSES:
-   - Write SUMMARY-[N]-[M].md
+   - Run `<verify>` — capture exact output
+   - If verify PASSES:
+     - Run `<verify-visual>` via `visual-verify-executor.js`
+     - If visual verify FAILS: stop and report (treat as verify failure)
+     - Write SUMMARY-[N]-[M].md
    - Execute commit: `git add [files] && git commit -m "[type]([scope]): [task name]"`
    - Capture git SHA
    - Write AUDIT entry for task completion

package/.agent/mindforge/init-project.md

@@ -5,6 +5,18 @@ Read `.planning/PROJECT.md`. If it already exists and contains content,
 ask: "A project is already initialised. Do you want to reinitialise? (yes/no)"
 Stop if the user says no.
 
+## Pre-flight Environment Check
+Verify that `CLAUDE.md` exists at the root of the project and `.claude/commands/mindforge/` is populated. If not, silently run the following to enable zero-config IDE autocomplete (Cursor, Windsurf, Claude Code):
+```bash
+mkdir -p .claude/commands/mindforge
+cp -r .agent/mindforge/* .claude/commands/mindforge/ 2>/dev/null || true
+cp -r agents/mindforge/* .claude/commands/mindforge/ 2>/dev/null || true
+cp .agent/CLAUDE.md ./CLAUDE.md 2>/dev/null || true
+cp agents/CLAUDE.md ./CLAUDE.md 2>/dev/null || true
+cp ./CLAUDE.md ./.cursorrules 2>/dev/null || true
+cp ./CLAUDE.md ./.windsurfrules 2>/dev/null || true
+```
+
 ## Step 1 — Requirements interview
 Ask these questions one at a time. Wait for the full answer before asking the next.
 Do not batch them. Do not rush.

package/.agent/mindforge/qa.md

@@ -0,0 +1,16 @@
+# /mindforge:qa
+
+## Usage
+`@mindforge qa [--phase N] [--auto]`
+
+## Description
+Runs systematic visual QA on UI surfaces changed in the current phase.
+Analyzes git diff to find pages, navigates to them, and looks for errors.
+
+## Options
+- `--phase N`: Target specific phase for reporting (defaults to current).
+- `--auto`: Automatically run after successful wave execution if configured.
+
+## Output
+- `QA-REPORT-[N].md`: Found bugs with screenshots.
+- `tests/regression/*.test.ts`: Playwright tests to prevent bug recurrence.

package/.agent/mindforge/remember.md

@@ -0,0 +1,14 @@
+# /mindforge:remember
+
+Manage the MindForge long-term memory (knowledge graph).
+
+## Usage
+
+- `/mindforge:remember --add "Your knowledge content"`: Manually add an entry.
+- `/mindforge:remember --search "your query"`: Search the knowledge base.
+- `/mindforge:remember --stats`: View memory statistics.
+- `/mindforge:remember --promote "id"`: Promote a project entry to global memory.
+
+## Description
+
+MindForge capture, stores, and retrieves knowledge (architectural decisions, code patterns, team preferences) across all sessions and projects. This command allows for manual management and querying of this data.

package/.agent/mindforge/research.md

@@ -0,0 +1,11 @@
+# MindForge v2 — Research Command
+# Usage: /mindforge:research [topic] [--type general|library|codebase|compliance] [--url URL]
+
+## Purpose
+Deep research using Gemini 1.5 Pro's 1-million-token context window.
+Incorporate local code context and remote documentation simultaneously.
+
+## Capabilities
+- Ingest full library documentation.
+- Codebase-wide architectural analysis.
+- Regulatory compliance audits.

package/.agent/mindforge/steer.md

@@ -0,0 +1,13 @@
+# /mindforge:steer "[instruction]"
+
+**Purpose**: Injects mid-execution guidance into the running autonomous engine.
+Steering guidance is applied at the next task boundary to course-correct the agent.
+
+## Usage
+- `/mindforge:steer "Use the new logger in all created files"`
+- `/mindforge:steer --task 3-05 "This plan is too broad, focus on login only"`
+- `/mindforge:steer --cancel` (Clears the steering queue)
+
+## Precedence
+- Steering instructions take precedence over the original `PLAN-N-MM.md` actions.
+- Steering cannot override core security constraints or governance gates.

package/.agent/workflows/publish-release.md

@@ -0,0 +1,36 @@
+---
+description: Publish a new version of MindForge to npm
+---
+
+# MindForge Publishing Workflow
+
+This workflow automates the pre-verification and publishing of MindForge.
+
+## Pre-Flight Checks
+
+1. Verify structural integrity
+// turbo
+npm test
+
+2. Check package contents
+// turbo
+npm pack --dry-run
+
+## Publish Execution
+
+**Note**: If this is a prerelease (alpha, beta, rc), you must specify the tag.
+
+3. Publish to npm
+```bash
+# For stable:
+npm publish --access public
+
+# For alpha:
+npm publish --tag alpha --access public
+```
+
+4. Create Git Tag
+```bash
+git tag v$(node -p "require('./package.json').version")
+git push origin --tags
+```

package/.claude/CLAUDE.md

@@ -3,6 +3,29 @@
 
 ---
 
+## MULTI-MODEL INTELLIGENCE LAYER (v2.0.0 — Day 10)
+
+### Model Routing
+
+- Resolve model using `bin/models/model-router.js` based on persona and tier.
+- Tier 3 (Security) always uses `SECURITY_MODEL`.
+
+### API Client
+- Always use `bin/models/model-client.js` for API interactions.
+- Fallback chain: unavailable model → next in tier.
+
+### Cost Awareness
+- Record every call using `bin/models/cost-tracker.js`.
+- Block calls if `MODEL_COST_HARD_LIMIT_USD` is reached.
+
+### New Commands
+
+- `/mindforge:cross-review` — Adversarial multi-model review.
+- `/mindforge:research` — Deep research via Gemini 1M.
+- `/mindforge:costs` — Cost tracking dashboard.
+
+---
+
 ## DISTRIBUTION & CI LAYER (Day 6)
 
 ### CI mode awareness
@@ -93,6 +116,66 @@ Non-breaking additions (new optional fields, new commands) require MINOR.
 
 ---
 
+## AUTONOMOUS LAYER (Day 8 — v2.0.0-alpha.1)
+
+### Autonomous mode protocol
+When the user requests `/mindforge:auto --phase [N]`:
+1. Execute the pre-flight check from `.mindforge/engine/autonomous/auto-executor.md`.
+2. Follow the auto-executor state machine precisely.
+3. Every task must be performed by a fresh subagent context (context-compaction logic).
+4. Monitor every action for S01-S05 stuck patterns (stuck-detector.md).
+5. On failure: apply RETRY → DECOMPOSE → PRUNE logic (node-repair.md).
+6. Compliance Gate 3 (secrets) runs PRE-COMMIT on staged diffs.
+7. Visual Verification: runs <verify-visual> AFTER successful <verify> (unit tests).
+8. Governance: ESCALATE immediately on Tier 3 changes (Auth/Payment/PII).
+
+### Steering awareness
+Check `.planning/steering-queue.jsonl` at every task boundary.
+If guidance is present: inject it into the next PLAN file as the highest priority
+instruction. Standard governance gates still apply to steered changes.
+
+### Headless execution
+If `--headless` is used:
+- Disable all TTY-rich progress UI.
+- Structure all stdout as line-delimited JSON.
+- Handle SIGTERM by pausing execution and snapshotting HANDOFF.json.
+
+### New commands (Day 8)
+- /mindforge:auto — start/resume autonomous execution engine
+- /mindforge:steer — inject mid-execution guidance
+- /mindforge:browse — persistent browser control and actions
+- /mindforge:qa — systematic post-phase visual QA
+
+---
+
+## REAL-TIME DASHBOARD (v2.0.0 — Day 12)
+
+### Dashboard server
+The MindForge dashboard runs at localhost:7339 when started.
+- Start: `node bin/dashboard/server.js [--port 7339] [--open]`
+- Stop:  `/mindforge:dashboard --stop`
+
+Localhost-only (127.0.0.1) — consistent with ADR-017.
+Never bind to 0.0.0.0, never port-forward externally.
+
+### When to recommend the dashboard
+Suggest starting the dashboard when:
+- User runs /mindforge:auto (live progress visibility)
+- Team standup approaching (screenshare mode)
+- Tier 2/3 approvals are pending (approver can approve from browser)
+- Debugging a quality issue (metrics page shows trends)
+
+### AUDIT events written by dashboard
+- dashboard_started: on server start
+- dashboard_stopped: on graceful shutdown
+- approval_granted / approval_rejected: when approved via browser UI
+- steering_queued: when steering instruction sent via browser UI
+
+### New command (Day 12)
+- /mindforge:dashboard — start/stop/status the real-time web dashboard
+
+---
+
 ## IDENTITY
 
 You are a senior AI engineering agent operating under the **MindForge framework**.

package/.claude/commands/mindforge/auto.md

@@ -0,0 +1,22 @@
+# /mindforge:auto [Phase N]
+
+**Purpose**: Starts the MindForge Autonomous Execution Engine for the
+specified phase. The agent will execute all waves, handle repairs, and
+perform compliance gates without requiring human confirmation.
+
+## Usage
+- `/mindforge:auto --phase 3` (Standard unattended mode)
+- `/mindforge:auto --resume` (Resumes from last checkpoint)
+- `/mindforge:auto --headless` (CI/CD optimized output)
+- `/mindforge:auto --dry-run` (Show the wave DAG and plan without executing)
+
+## Behavior
+- **Zero-Interaction**: Auto-approves Tier 1/2 changes if gates pass.
+- **Self-Repair**: Tries RETRY/DECOMPOSE before asking for help.
+- **Checkpointing**: Constant state persistence in `HANDOFF.json`.
+- **Governance**: ESCALATES on Tier 3 changes (Auth/Payment/PII).
+
+## Environment Variables
+- `AUTO_MODE_TIMEOUT_MINUTES`: Default 120.
+- `AUTO_PUSH_ON_WAVE_COMPLETE`: Default false.
+- `SLACK_WEBHOOK_URL`: Required for notifications.

package/.claude/commands/mindforge/browse.md

@@ -0,0 +1,26 @@
+# /mindforge:browse
+
+## Usage
+`@mindforge browse <url | action>`
+
+## Description
+Controls the persistent MindForge browser daemon. 
+Maintains session state (cookies/localStorage) for the AI.
+
+## Actions
+| Action | Description |
+|---|---|
+| `--start` | Initialize browser daemon |
+| `--stop` | Kill browser daemon |
+| `--status` | Show daemon health and active sessions |
+| `--session <name>` | Switch browser context |
+| `--import-session <name> --from <browser>` | Import cookies from host browser (chrome, arc, etc) |
+| `<url>` | Navigate the current page to URL |
+| `click <selector>` | Trigger click event |
+| `type <sel> <text>` | Fill input field |
+| `screenshot` | Capture current viewport |
+
+## Security
+- Daemon binds to `127.0.0.1` only.
+- Session files are gitignored.
+- Use only for debugging and visual verification.

package/.claude/commands/mindforge/costs.md

@@ -0,0 +1,11 @@
+# MindForge v2 — Costs Command
+# Usage: /mindforge:costs [--phase N] [--session ID] [--window 7d]
+
+## Purpose
+Real-time cost tracking for all AI model usage.
+Enforce daily budgets and see per-model spend.
+
+## Metrics
+- Total spend: $X.XX
+- Daily limit usage: XX%
+- Per-model breakdown (Tokens/Cost)

package/.claude/commands/mindforge/cross-review.md

@@ -0,0 +1,17 @@
+# MindForge v2 — Cross-Review Command
+# Usage: /mindforge:cross-review [--phase N] [--models list] [--focus area]
+
+## Purpose
+Get the same code diff reviewed by multiple AI models simultaneously.
+Claude finds what Claude finds. GPT-4o finds what GPT-4o finds.
+Consensus findings = high confidence issues.
+
+## Round 1: Primary (Claude)
+Senior architect review.
+
+## Round 2: Adversarial (GPT-4o)
+Critical security and edge case review.
+
+## Synthesis
+Consensus detector filters findings.
+Verdict is gating for `/mindforge:ship`.