mindforge-cc 2.0.0-alpha.4 → 2.0.0-alpha.6

package/.agent/CLAUDE.md

@@ -6,6 +6,7 @@
 ## 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`.
 
@@ -18,6 +19,7 @@
 - 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.
@@ -146,6 +148,34 @@ If `--headless` is used:
 
 ---
 
+## 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/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/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/.claude/CLAUDE.md

@@ -6,6 +6,7 @@
 ## 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`.
 
@@ -18,6 +19,7 @@
 - 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.
@@ -146,6 +148,34 @@ If `--headless` is used:
 
 ---
 
+## 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/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/.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.

package/.planning/approvals/v2-architecture-approval.json

@@ -0,0 +1,15 @@
+{
+  "id": "MF-AUTH-V2-001",
+  "project": "MindForge",
+  "version": "2.0.0-alpha.2",
+  "tier": 3,
+  "approved_by": "Antigravity (Agentic AI)",
+  "timestamp": "2026-03-22T20:28:00Z",
+  "scope": [
+    ".github/workflows/*",
+    "bin/mindforge-cli.js",
+    "bin/change-classifier.js"
+  ],
+  "reason": "Implementation of 5-Layer Plane Architecture and standardized CLI routing.",
+  "signature": "sha256:d8e8fca2dc0f896fd7cb4cb0031ba249"
+}

package/CHANGELOG.md

@@ -3,6 +3,19 @@
 All notable changes to MindForge are documented here.
 Format follows [Keep a Changelog](https://keepachangelog.com).
 
+## [2.0.0-alpha.6] — Day 12: Real-time Observability Dashboard — 2026-03-22
+
+- [v2.0.0-alpha.6 (2026-03-22)]
+  - [NEW] Real-time Dashboard Server (Express + SSE Bridge).
+  - [NEW] Premium 5-tab UI: Activity, Metrics, Approvals, Memory, Team.
+  - [NEW] Live Data Streaming for Audit Logs, Quality, Costs, and Team Activity.
+  - [NEW] Hardened Tier 3 Governance: Mandatory Plan ID typing for sensitive approvals.
+  - [NEW] Metrics Aggregator: Multi-source JSONL processing for observability.
+  - [NEW] CLI Command: `/mindforge:dashboard` for server lifecycle management.
+  - [NEW] ADR-033: Real-time Observability Architecture.
+  - [HARDENED] SSE Rotation Detection (Inode-based).
+  - [HARDENED] Localhost-only Security Model (Strict CORS/Binding).
+
 ## [2.0.0-alpha.4] — Day 11: Persistent Knowledge Graph (Long-Term Memory) — 2026-03-22
 
 - [v2.0.0-alpha.4 (2026-03-22)]

package/README.md

@@ -1,4 +1,4 @@
-# MindForge — Enterprise Agentic Framework (v2.0.0-alpha.4)
+# MindForge — Enterprise Agentic Framework (v2.0.0-alpha.6)
 
 MindForge turns Claude Code and Antigravity into production-grade engineering
 partners with governance, observability, and a disciplined workflow engine.
@@ -19,6 +19,7 @@ Decisions get forgotten. MindForge fixes that with:
 - **Skills** — just-in-time domain knowledge loaded on demand
 - **Wave execution** — parallelism with dependency safety
 - **Autonomous Engine** — walk-away execution with steerability (v2)
+- **Real-time Dashboard** — web-based observability and governance (v2)
 - **Browser Runtime** — headful/headless visual QA and sessions (v2)
 - **Multi-Model Intelligence** — dynamic routing, adversarial reviews, and deep research (v2)
 - **Persistent Knowledge Graph** — long-term memory across all engineering sessions (v2)
@@ -39,6 +40,16 @@ npx mindforge-cc@latest --claude --global
 npx mindforge-cc@latest --claude --local
 ```
 
+### Quick Start
+
+```bash
+# Install the latest stable version
+npm install -g mindforge-cc
+
+# Or try the v2.0.0-alpha (latest features)
+npm install -g mindforge-cc@alpha
+```
+
 ### Antigravity
 ```bash
 npx mindforge-cc@latest --antigravity --global
@@ -144,6 +155,10 @@ If issues are found, run:
 / mindforge:remember
     → Manual knowledge management and search (v2)
     → Persistent knowledge graph retrieval and promotion
+
+/ mindforge:dashboard
+    → Real-time web observability and governance at localhost:7339 (v2)
+    → Live audit logs, metrics, activity, and team feed
 ```
 
 ---
@@ -200,7 +215,8 @@ See `.mindforge/production/token-optimiser.md`.
 
 ---
 
-## What ships in v2.0.0-alpha.4
+## What ships in v2.0.0-alpha.6
+- **Real-time Dashboard**: `/mindforge:dashboard` and web-based observability.
 - **Persistent Knowledge Graph**: `/mindforge:remember` and long-term memory engine.
 - **Multi-Model Intelligence Layer**: `/mindforge:cross-review`, `/mindforge:research`, and `/mindforge:costs`.
 - **Visual QA Engine**: `/mindforge:qa` and automated regression tests.