mindforge-cc 1.0.5 → 2.0.0-alpha.6

package/.claude/commands/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/.claude/commands/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/.claude/commands/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/.claude/commands/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/.claude/commands/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/.claude/commands/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/.mindforge/MINDFORGE-V2-SCHEMA.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "MindForge v2 Autonomous Engine Schema",
+  "description": "Schema for HANDOFF.json and auto-state.json in v2.0.0-alpha.1",
+  "type": "object",
+  "properties": {
+    "schema_version": { "type": "string", "const": "2.0.0" },
+    "auto_mode_active": { "type": "boolean" },
+    "phase": { "type": "integer" },
+    "wave_current": { "type": "integer" },
+    "tasks_completed": { "type": "integer" },
+    "PLANNER_MODEL": { "type": "string" },
+    "EXECUTOR_MODEL": { "type": "string" },
+    "REVIEWER_MODEL": { "type": "string" },
+    "SECURITY_MODEL": { "type": "string" },
+    "RESEARCH_MODEL": { "type": "string" },
+    "QA_MODEL": { "type": "string" },
+    "DEBUG_MODEL": { "type": "string" },
+    "QUICK_MODEL": { "type": "string" },
+    "MODEL_COST_WARN_USD": { "type": "number" },
+    "MODEL_COST_HARD_LIMIT_USD": { "type": "number" },
+    "MODEL_PREFER_CHEAP_BELOW_DIFFICULTY": { "type": "number" },
+    "REQUIRE_CROSS_REVIEW": { "type": "boolean" },
+    "status": {
+      "type": "string",
+      "enum": ["idle", "running", "paused", "completed", "escalated", "timeout"]
+    },
+    "governance": {
+      "type": "object",
+      "properties": {
+        "tier1_auto_approve": { "type": "boolean" },
+        "tier2_auto_approve": { "type": "boolean" },
+        "tier3_require_human": { "type": "boolean", "const": true }
+      }
+    },
+    "browser": {
+      "type": "object",
+      "properties": {
+        "port": { "type": "integer", "default": 7338 },
+        "headless": { "type": "boolean", "default": true },
+        "dev_server_url": { "type": "string" },
+        "auto_qa": { "type": "boolean", "default": true }
+      }
+    }
+  },
+  "required": ["schema_version", "auto_mode_active", "status"]
+}

package/.mindforge/browser/daemon-protocol.md

@@ -0,0 +1,24 @@
+# MindForge v2 — Browser Daemon Protocol
+
+## Overview
+Small, long-lived Node.js process that manages a Chromium instance via Playwright.
+
+## HTTP API (localhost:7338)
+
+| Method | Path | Body | Response |
+|---|---|---|---|
+| GET | /status | - | { alive: bool, sessions: string[], uptime: sec } |
+| POST | /navigate | { url, session, wait_for } | { success: bool, status_code: int, load_time_ms: int } |
+| POST | /click | { selector, text, session } | { success: bool, element_found: bool } |
+| POST | /type | { selector, text, session } | { success: bool } |
+| POST | /screenshot | { session } | { success: bool, screenshot_b64: string } |
+| POST | /evaluate | { script, session } | { success: bool, result: any } |
+| POST | /assert | { type, selector, expected_text, session } | { passed: bool, actual_text: string, error: string } |
+| POST | /session/save | { name } | { success: bool, path: string } |
+| POST | /session/load | { name } | { success: bool, cookies: int } |
+| DELETE | /session/:name | - | { success: bool } |
+
+## State Management
+- Sessions are stored in `.mindforge/browser/sessions/` as JSON.
+- Multiple named sessions can be active (different BrowserContexts).
+- SIGTERM saves all active sessions if --save-on-exit is passed.

package/.mindforge/browser/qa-engine.md

@@ -0,0 +1,16 @@
+# MindForge v2 — QA Engine
+
+## Purpose
+Systematic post-phase visual QA.
+Analyzes git diff, extracts UI surfaces (pages, routes), and runs tests.
+
+## Test Strategy
+For each page found:
+1. Load page -> check for JS errors.
+2. Verify main content visibility.
+3. Test authentication redirects.
+4. Document any rendering or logic bugs.
+
+## Outputs
+- `QA-REPORT-[N].md`: Detailed phase report.
+- `tests/regression/*.test.ts`: Playwright tests for every bug found.

package/.mindforge/browser/session-manager.md

@@ -0,0 +1,18 @@
+# MindForge v2 — Browser Session Manager
+
+## Principles
+1. **Persistence**: Cookies and localStorage must survive between MindForge waves.
+2. **Isolation**: Named sessions (admin, user, guest) prevent state leaking.
+3. **Security**: Session files are GITIGNORED. Never commit auth tokens.
+
+## Methods
+
+### 1. Sequential Manual Logins
+Agent navigates to /login, types credentials, and calls `/session/save name`.
+
+### 2. External Import
+Import cookies from your real browser (Chrome, Arc, Brave, Edge).
+`/mindforge:browse --import-session admin --from chrome`
+
+### 3. Programmatic (CI)
+Sessions can be pre-seeded by writing `.mindforge/browser/sessions/name.json` directly from CI secrets.

package/.mindforge/browser/visual-verify-spec.md

@@ -0,0 +1,31 @@
+# MindForge v2 — <verify-visual> Specification
+
+## Overview
+`<verify-visual>` is an optional field in PLAN task XML.
+It runs AFTER `<verify>` (unit/integration tests) passes.
+It confirms the UI looks and behaves correctly via browser automation.
+
+## Syntax
+```xml
+<verify-visual session="user">
+  navigate: /dashboard
+  wait: networkidle
+  assert-visible: h1 "My Projects"
+  screenshot: dashboard.png
+  click: "#create-btn"
+  assert-visible: .modal
+</verify-visual>
+```
+
+## Directives
+| Directive | Description |
+|---|---|
+| `navigate: /path` | Navigate to URL (relative to DEV_SERVER_URL) |
+| `wait: N` | Wait N ms or 'networkidle' |
+| `assert-visible: sel ["text"]` | Assert element is visible |
+| `assert-url: /path` | Assert current URL |
+| `screenshot: name.png` | Capture screenshot |
+| `click: selector` | Click element |
+| `type: sel "text"` | Type into field |
+| `evaluate: js` | Evaluate JS expression |
+| `press: Key` | Press keyboard key |

package/.mindforge/dashboard/api-reference.md

@@ -0,0 +1,122 @@
+# MindForge Dashboard API Reference
+
+## Base URL: http://localhost:7339
+
+## GET /api/status
+Current execution state.
+```json
+{
+  "project_name": "saas-app",
+  "phase": 3,
+  "phase_description": "Authentication System",
+  "auto_mode": true,
+  "auto_status": "running|paused|escalated|idle",
+  "current_task": "Plan 3-05 — JWT middleware",
+  "wave_current": 2,
+  "wave_total": 3,
+  "tasks_completed": 5,
+  "tasks_total": 8,
+  "elapsed_ms": 1083000,
+  "node_repairs": 1,
+  "escalations": 0,
+  "last_commit": "abc1234",
+  "last_event_at": "ISO-8601"
+}
+```
+
+## GET /api/audit?limit=50&offset=0&event=task_completed
+Recent AUDIT.jsonl entries (newest first).
+Query params: limit (default 50, max 200), offset, event (filter by event type)
+
+## GET /api/metrics
+Session quality and cost summary.
+```json
+{
+  "sessions": [{ "id": "...", "quality_score": 0.87, "cost_usd": 0.42, "verify_pass_rate": 0.95 }],
+  "avg_quality": 0.85,
+  "avg_cost_usd": 0.38,
+  "security_findings": { "CRITICAL": 0, "HIGH": 2, "MEDIUM": 5, "LOW": 8 },
+  "node_repair_rate": 0.08
+}
+```
+
+## GET /api/approvals
+Pending governance approvals.
+```json
+{
+  "pending": [
+    {
+      "id": "uuid",
+      "tier": 2,
+      "phase": 3,
+      "plan": "04",
+      "description": "Add user RBAC model",
+      "requested_at": "ISO-8601",
+      "expires_at": "ISO-8601",
+      "hours_remaining": 21.3,
+      "diff_preview": "src/models/user.ts +48 lines..."
+    }
+  ],
+  "approved": [...],
+  "rejected": [...],
+  "expired": [...]
+}
+```
+
+## POST /api/approve/:id
+```json
+Request:  { "decision": "approve|reject", "comment": "optional", "approver": "email" }
+Response: { "success": true, "decision": "approve", "approval_id": "uuid" }
+```
+
+## GET /api/team
+Active developer activity.
+```json
+{
+  "active": [
+    { "email": "john@company.com", "current_task": "Plan 3-05", "last_seen_mins": 0 }
+  ],
+  "conflicts": [
+    { "file": "src/auth/session.ts", "developers": ["john@...", "jane@..."] }
+  ]
+}
+```
+
+## GET /api/memory?q=jwt&limit=10
+Knowledge base query.
+```json
+{
+  "entries": [
+    { "id": "kb-uuid", "type": "architectural_decision", "topic": "JWT tokens", "confidence": 0.90 }
+  ],
+  "total": 47
+}
+```
+
+## GET /api/costs?window=7d
+Cost summary from token-usage.jsonl.
+```json
+{
+  "total_usd": 3.84,
+  "today_usd": 1.21,
+  "by_model": { "claude-sonnet-4-6": 1.92, "gpt-4o": 0.98 },
+  "daily_limit_usd": 10.00,
+  "limit_used_pct": 12.1
+}
+```
+
+## POST /api/steer
+Inject steering guidance (requires auto mode running).
+```json
+Request:  { "instruction": "Use Redis for session storage", "priority": "normal" }
+Response: { "success": true, "queued": true }
+```
+
+## GET /events
+SSE stream. Events emitted:
+- `audit:new` — new AUDIT.jsonl entry
+- `status:update` — auto-state.json changed
+- `approval:new` — new approval request
+- `approval:resolved` — approval approved or rejected
+- `conflict:detected` — two developers touching same file
+- `ping` — keepalive every 15 seconds

package/.mindforge/dashboard/dashboard-spec.md

@@ -0,0 +1,96 @@
+# MindForge v2 — Dashboard Specification
+
+## Overview
+
+The MindForge dashboard is a real-time web UI that reflects the live state of
+the MindForge agent and all project artifacts. It serves as the team's window
+into what the agent is doing — designed for standup visibility, not agent control
+(though it does support approval actions for Tier 2/3 governance).
+
+## Architecture
+
+```
+Browser clients
+     ↑ SSE (push)     ↑ REST (pull on load)
+     │                │
+  bin/dashboard/server.js  (Express.js, localhost:7339)
+     │                │
+  sse-bridge.js       api-router.js
+     │ (tails files)  │ (reads files)
+     │                │
+  AUDIT.jsonl         HANDOFF.json
+  auto-state.json     session-quality.jsonl
+  APPROVAL-*.json     token-usage.jsonl
+  HANDOFF.json        knowledge-base.jsonl
+  TEAM-STATE.jsonl    .planning/phases/
+```
+
+## Port and binding
+
+- **Port:** 7339 (Dashboard = 7337+2, after SSE at 7337 and Browser Daemon at 7338)
+- **Binding:** 127.0.0.1 ONLY — never 0.0.0.0 (ADR-017 policy)
+- **Protocol:** HTTP/1.1 with SSE for live events
+- **Process lifecycle:**
+  - Started by: `/mindforge:dashboard` command or `bin/dashboard/server.js`
+  - Stopped by: `CTRL+C`, `/mindforge:dashboard --stop`, or SIGTERM
+  - Auto-stop: when MindForge session ends (watches for HANDOFF.json inactivity)
+
+## Dashboard pages (5 tabs)
+
+### Page 1 — Live Activity (default view)
+Shows real-time execution state:
+- Project name and current phase description
+- Auto mode status indicator (RUNNING/PAUSED/ESCALATED/IDLE)
+- Wave progress bar (current wave / total waves)
+- Current task name and elapsed time
+- Live AUDIT event feed (last 50 events, newest at top)
+- Steering input box (sends to steering queue if auto mode active)
+
+### Page 2 — Quality Metrics
+Charts powered by session-quality.jsonl and token-usage.jsonl:
+- Session quality score trend (last 20 sessions, sparkline)
+- Verify pass rate over time (last 20 sessions)
+- Security findings by severity (bar chart: CRITICAL/HIGH/MEDIUM/LOW)
+- Token cost per session trend
+- Node repair frequency (auto mode health signal)
+
+### Page 3 — Pending Approvals
+Governance queue visible to the whole team:
+- Shows all APPROVAL-*.json files with status: pending
+- For each: tier, phase/plan, change description, time since requested, expiry
+- [Approve] and [Reject] buttons that call POST /api/approve/:id
+- Expired approvals shown separately with red indicator
+
+### Page 4 — Knowledge Graph
+Visual representation of the knowledge base:
+- Force-directed graph: nodes = knowledge entries, edges = ADR links
+- Color by type: blue=decision, green=preference, red=bug_pattern, yellow=domain
+- Node size = confidence × 30px radius
+- Click node → side panel with full content
+- Filter by type, tags, or confidence threshold
+
+### Page 5 — Team Activity
+Multi-developer visibility:
+- Active developers (git email → last AUDIT event timestamp)
+- What each developer is working on (last task from AUDIT.jsonl)
+- File conflict detection (two developers recently touching the same file)
+- Session history (list of sessions, quality scores, costs)
+
+## Security model
+
+1. Localhost-only binding (127.0.0.1) — consistent with all MindForge servers
+2. No authentication — local dev tool, not exposed to network
+3. CORS policy: only allow requests from localhost
+4. Approval actions (POST /api/approve/:id) require the approval file to exist
+   in `.planning/approvals/` — cannot fabricate approvals from browser
+5. Steering (POST /api/steer) only works when auto-state.json shows `status: running`
+6. All file reads are restricted to `.planning/` and `.mindforge/` directories —
+   no arbitrary filesystem access from the API
+
+## SCREENSHARE MODE (recommended team use)
+The dashboard is designed to be screenshared during standups:
+- Product managers see live progress without CLI access
+- Designers see when their UI implementation tasks are running
+- Stakeholders see real estimates of completion time
+- On-call engineers see security findings as they're detected
+Never expose the dashboard URL externally — it contains project details.