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

package/README.md

@@ -1,4 +1,4 @@
-# MindForge — Enterprise Agentic Framework (v2.0.0-alpha.4)
+# MindForge — Enterprise Agentic Framework (v2.0.0-alpha.7)
 
 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.7
+- **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.

package/RELEASENOTES.md

@@ -21,7 +21,7 @@ Quality gates, security posture, and release readiness are documented for enterp
 - Example starter project with MindForge structure ready for onboarding teams.
 
 ## Quality & Stability
-- Day 7 production, migration, and e2e test suites added.
+- production, migration, and e2e test suites added.
 - Full 12-suite regression loop validated across prior-day coverage.
 - Triple-run stability verification completed with all tests passing.
 - Threat model and penetration test results documented.

package/bin/change-classifier.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+/**
+ * MindForge Change Classifier
+ * Categorizes changes into Tiers based on risk and sensitivity.
+ */
+
+'use strict';
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+
+const SENSITIVE_PATHS = [
+  'auth/',
+  'payment/',
+  'security/',
+  '.github/workflows/',
+  '.mindforge/governance/',
+  'bin/models/'
+];
+
+const SENSITIVE_PATTERNS = [
+  /jwt/i,
+  /bcrypt/i,
+  /stripe/i,
+  /apiKey/i,
+  /password/i,
+  /secret/i,
+  /token/i,
+  /PII/
+];
+
+function classify() {
+  try {
+    // Get list of changed files compared to origin/main or HEAD~1
+    const base = process.env.GITHUB_BASE_REF ? `origin/${process.env.GITHUB_BASE_REF}` : 'HEAD~1';
+    const diffFiles = execSync(`git diff --name-only ${base}..HEAD`, { encoding: 'utf8' }).split('\n').filter(Boolean);
+    
+    let tier = 1;
+    let reasons = [];
+
+    // 1. Path-based detection (Tier 3)
+    const matchedPath = diffFiles.find(file => SENSITIVE_PATHS.some(p => file.startsWith(p)));
+    if (matchedPath) {
+      tier = 3;
+      reasons.push(`Sensitive path modified: ${matchedPath}`);
+    }
+
+    // 2. Pattern-based detection in diff (Tier 3)
+    if (tier < 3) {
+      const diffContent = execSync(`git diff ${base}..HEAD`, { encoding: 'utf8' });
+      for (const pattern of SENSITIVE_PATTERNS) {
+        if (pattern.test(diffContent)) {
+          tier = 3;
+          reasons.push(`Sensitive pattern detected: ${pattern}`);
+          break;
+        }
+      }
+    }
+
+    // 3. Simple change (Tier 1 vs 2)
+    if (tier < 3) {
+      if (diffFiles.length > 10 || diffFiles.some(f => f.endsWith('.js') || f.endsWith('.ts'))) {
+        tier = 2; // Significant logic change
+      }
+    }
+
+    console.log(`TIER=${tier}`);
+    console.log(`REASONS=${reasons.join('; ')}`);
+    
+    // Write to GITHUB_OUTPUT if available
+    if (process.env.GITHUB_OUTPUT) {
+      fs.appendFileSync(process.env.GITHUB_OUTPUT, `tier=${tier}\n`);
+    }
+
+    return tier;
+  } catch (err) {
+    console.error(`❌ Classification failed: ${err.message}`);
+    // Default to Tier 3 for safety if classification fails
+    if (process.env.GITHUB_OUTPUT) {
+      fs.appendFileSync(process.env.GITHUB_OUTPUT, `tier=3\n`);
+    }
+    process.exit(0); // Don't fail the pipeline yet, let the gate handle it
+  }
+}
+
+classify();

package/bin/dashboard/api-router.js

@@ -0,0 +1,198 @@
+/**
+ * MindForge v2 — Dashboard API Router
+ * All REST endpoints for the dashboard.
+ */
+'use strict';
+
+const path    = require('path');
+const fs      = require('fs');
+const Metrics = require('./metrics-aggregator');
+const Approval = require('./approval-handler');
+const SSE     = require('./sse-bridge');
+
+// Steering queue path (from Day 8 auto-executor)
+const STEERING_QUEUE = path.join(process.cwd(), '.planning', 'steering-queue.jsonl');
+const AUTO_STATE_PATH = path.join(process.cwd(), '.planning', 'auto-state.json');
+
+function register(app) {
+
+  // ── SSE stream ──────────────────────────────────────────────────────────────
+  app.get('/events', (req, res) => {
+    res.setHeader('Content-Type',  'text/event-stream');
+    res.setHeader('Cache-Control', 'no-cache');
+    res.setHeader('Connection',    'keep-alive');
+    res.setHeader('X-Accel-Buffering', 'no'); // Disable Nginx buffering
+    res.flushHeaders();
+
+    // Send current status immediately on connect
+    try {
+      const status = Metrics.getStatus();
+      res.write(`event: status:update\ndata: ${JSON.stringify(status)}\n\n`);
+    } catch { /* ignore */ }
+
+    SSE.addClient(res);
+  });
+
+  // ── Status ──────────────────────────────────────────────────────────────────
+  app.get('/api/status', (req, res) => {
+    try {
+      res.json(Metrics.getStatus());
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  // ── Audit entries ───────────────────────────────────────────────────────────
+  app.get('/api/audit', (req, res) => {
+    try {
+      const limit  = Math.min(parseInt(req.query.limit  || '50',  10), 200);
+      const offset = Math.max(parseInt(req.query.offset || '0',   10), 0);
+      const event  = typeof req.query.event === 'string' ? req.query.event : null;
+      res.json(Metrics.getAuditEntries(limit, offset, event));
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  // ── Quality metrics ─────────────────────────────────────────────────────────
+  app.get('/api/metrics', (req, res) => {
+    try {
+      res.json(Metrics.getMetrics());
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  // ── Approvals ───────────────────────────────────────────────────────────────
+  app.get('/api/approvals', (req, res) => {
+    try {
+      res.json(Metrics.getApprovals());
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  app.post('/api/approve/:id', (req, res) => {
+    try {
+      const { id }                  = req.params;
+      const { decision, comment, approver } = req.body || {};
+
+      if (!decision) {
+        return res.status(400).json({ error: 'Missing "decision" field (approve|reject)' });
+      }
+
+      const result = Approval.processDecision(id, decision, comment, approver);
+
+      if (!result.success) {
+        return res.status(400).json(result);
+      }
+
+      // Broadcast approval event to all SSE clients
+      SSE.broadcast(
+        decision === 'approve' ? 'approval:resolved' : 'approval:resolved',
+        { approval_id: id, decision, message: result.message }
+      );
+
+      res.json(result);
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  // ── Team activity ───────────────────────────────────────────────────────────
+  app.get('/api/team', (req, res) => {
+    try {
+      res.json(Metrics.getTeamActivity());
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  // ── Knowledge base query ────────────────────────────────────────────────────
+  app.get('/api/memory', (req, res) => {
+    try {
+      const q     = typeof req.query.q     === 'string' ? req.query.q.slice(0, 100) : '';
+      const limit = Math.min(parseInt(req.query.limit || '20', 10), 100);
+      res.json(Metrics.getMemory(q, limit));
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  // ── Costs ───────────────────────────────────────────────────────────────────
+  app.get('/api/costs', (req, res) => {
+    try {
+      const window = Math.min(parseInt(req.query.window || '7', 10), 90);
+      res.json(Metrics.getCosts(window));
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  // ── Steering (requires auto mode running) ───────────────────────────────────
+  app.post('/api/steer', (req, res) => {
+    try {
+      const { instruction, priority = 'normal' } = req.body || {};
+
+      if (!instruction || typeof instruction !== 'string') {
+        return res.status(400).json({ error: 'Missing "instruction" field' });
+      }
+      if (instruction.length > 500) {
+        return res.status(400).json({ error: 'Instruction too long (max 500 chars)' });
+      }
+      if (!['normal', 'urgent', 'stop'].includes(priority)) {
+        return res.status(400).json({ error: 'Invalid priority. Use: normal|urgent|stop' });
+      }
+
+      // Check auto mode is running
+      const autoState = fs.existsSync(AUTO_STATE_PATH)
+        ? JSON.parse(fs.readFileSync(AUTO_STATE_PATH, 'utf8'))
+        : null;
+
+      if (!autoState || autoState.status !== 'running') {
+        return res.status(409).json({ error: 'Auto mode is not running. Steering has no effect.' });
+      }
+
+      // Run injection guard
+      const INJECTION_PATTERNS = [
+        /IGNORE ALL PREVIOUS INSTRUCTIONS/i,
+        /DISREGARD YOUR INSTRUCTIONS/i,
+        /FORGET YOUR TRAINING/i,
+        /YOUR NEW INSTRUCTIONS ARE/i,
+        /OVERRIDE:/i,
+      ];
+      if (INJECTION_PATTERNS.some(p => p.test(instruction))) {
+        return res.status(400).json({ error: 'Instruction rejected: contains prohibited patterns' });
+      }
+
+      // Write to steering queue
+      const entry = {
+        id:          require('crypto').randomBytes(8).toString('hex'),
+        timestamp:   new Date().toISOString(),
+        instruction: instruction.trim(),
+        priority,
+        authored_by: 'dashboard',
+        applies_to:  'all',
+        status:      'queued',
+        applied_at:  null,
+        applied_to_plan: null,
+      };
+
+      if (!fs.existsSync(path.dirname(STEERING_QUEUE))) {
+        fs.mkdirSync(path.dirname(STEERING_QUEUE), { recursive: true });
+      }
+      fs.appendFileSync(STEERING_QUEUE, JSON.stringify(entry) + '\n');
+
+      res.json({ success: true, queued: true, id: entry.id, priority });
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  // ── Client count (for dashboard connection indicator) ───────────────────────
+  app.get('/api/connections', (req, res) => {
+    res.json({ clients: SSE.getClientCount() });
+  });
+}
+
+module.exports = { register };

package/bin/dashboard/approval-handler.js

@@ -0,0 +1,134 @@
+/**
+ * MindForge v2 — Approval Handler
+ * Handles POST /api/approve/:id — approve or reject governance requests.
+ * Reads/writes APPROVAL-*.json files in .planning/approvals/
+ */
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+// Paths resolved lazily for testing
+const getPaths = () => ({
+  approvals: path.join(process.cwd(), '.planning', 'approvals'),
+  audit:     path.join(process.cwd(), '.planning', 'AUDIT.jsonl'),
+});
+
+/**
+ * Process an approval decision from the dashboard.
+ * @param {string} approvalId - The APPROVAL UUID
+ * @param {string} decision   - 'approve' or 'reject'
+ * @param {string} comment    - Optional comment
+ * @param {string} approver   - Approver identifier (email or name)
+ * @returns {{ success, decision, message }}
+ */
+function processDecision(approvalId, decision, comment, approver, confirmationId = null) {
+  // Input validation
+  if (!approvalId || typeof approvalId !== 'string') {
+    return { success: false, error: 'Invalid approval ID' };
+  }
+
+  // Sanitize approvalId — only allow UUID characters
+  if (!/^[a-f0-9-]{36}$/.test(approvalId)) {
+    return { success: false, error: 'Malformed approval ID format' };
+  }
+
+  if (!['approve', 'reject'].includes(decision)) {
+    return { success: false, error: 'Decision must be "approve" or "reject"' };
+  }
+
+  // Find the approval file
+  const paths    = getPaths();
+  const filePath = path.join(paths.approvals, `APPROVAL-${approvalId}.json`);
+  if (!fs.existsSync(filePath)) {
+    return { success: false, error: `Approval not found: ${approvalId}` };
+  }
+
+  let approval;
+  try {
+    approval = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return { success: false, error: 'Cannot parse approval file' };
+  }
+
+  // Validate approval is still pending
+  if (approval.status !== 'pending') {
+    return { success: false, error: `Approval already ${approval.status}` };
+  }
+
+  // Check expiry
+  if (approval.expires_at && new Date(approval.expires_at) < new Date()) {
+    return { success: false, error: 'Approval has expired' };
+  }
+
+  // TIER 3 CONFIRMATION — require typing the plan ID
+  if (approval.tier === 3 && decision === 'approve') {
+    const expectedConfirmation = `${approval.phase}-${approval.plan}`;
+    if (!confirmationId || confirmationId.trim() !== expectedConfirmation) {
+      return {
+        success: false,
+        error: `Tier 3 approval requires typing the plan ID "${expectedConfirmation}" to confirm.`,
+        confirmation_required: true,
+        expected: expectedConfirmation,
+        tier3_warning: 'This is a Tier 3 change (auth/payment/PII). Review the code diff before approving.',
+      };
+    }
+  }
+
+  // Write AUDIT entry FIRST (before updating file)
+  writeAuditEntry({
+    id:          require('crypto').randomBytes(8).toString('hex'),
+    timestamp:   new Date().toISOString(),
+    event:       decision === 'approve' ? 'approval_granted' : 'approval_rejected',
+    approval_id: approvalId,
+    tier:        approval.tier,
+    phase:       approval.phase,
+    plan:        approval.plan,
+    resolved_by: approver || 'dashboard',
+    comment:     comment || null,
+    agent:       'mindforge-dashboard',
+    session_id:  'dashboard',
+  });
+
+  // Update approval file
+  const updated = {
+    ...approval,
+    status:       decision === 'approve' ? 'approved' : 'rejected',
+    resolved_at:  new Date().toISOString(),
+    resolved_by:  approver || 'dashboard',
+    comment:      comment || null,
+    resolution_channel: 'mindforge-dashboard',
+  };
+
+  fs.writeFileSync(filePath, JSON.stringify(updated, null, 2));
+
+  return {
+    success:     true,
+    decision,
+    approval_id: approvalId,
+    tier:        approval.tier,
+    message:     `${approval.tier === 3 ? 'Tier 3' : 'Tier 2'} approval ${decision}d for Plan ${approval.phase}-${approval.plan}`,
+  };
+}
+
+function writeAuditEntry(entry) {
+  try {
+    const paths = getPaths();
+    if (!fs.existsSync(path.dirname(paths.audit))) return;
+    fs.appendFileSync(paths.audit, JSON.stringify(entry) + '\n');
+  } catch { /* ignore AUDIT write failures */ }
+}
+
+function listApprovals() {
+  const paths = getPaths();
+  if (!fs.existsSync(paths.approvals)) return [];
+  return fs.readdirSync(paths.approvals)
+    .filter(f => f.startsWith('APPROVAL-') && f.endsWith('.json'))
+    .map(f => {
+      try { return JSON.parse(fs.readFileSync(path.join(paths.approvals, f), 'utf8')); }
+      catch { return null; }
+    })
+    .filter(Boolean);
+}
+
+module.exports = { processDecision, listApprovals };