mindforge-cc 8.1.0 → 8.2.0

package/.mindforge/mirrors/mirror-sre-776a1cf9/bin/autonomous/repair-operator.js

@@ -0,0 +1,213 @@
+/**
+ * MindForge — Node Repair Operator
+ * Implements RETRY → DECOMPOSE → PRUNE → ESCALATE decision logic.
+ */
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+/**
+ * Determine the repair strategy for a failed task.
+ * @param {object} context - Task context
+ * @returns {'RETRY'|'DECOMPOSE'|'PRUNE'|'ESCALATE'}
+ */
+function determineRepairStrategy(context) {
+  const {
+    planId,
+    phase,
+    attemptNumber,     // 1 = first failure, 2 = retry also failed
+    errorOutput,
+    isTier3Change,
+    isOnCriticalPath,  // other plans have this plan as a dependency
+    planFilePath,
+    repairBudget = 2,
+  } = context;
+
+  // Tier 3 changes ALWAYS escalate — never auto-approve auth/payment/PII
+  if (isTier3Change) {
+    return 'ESCALATE';
+  }
+
+  // First failure — always try RETRY first
+  if (attemptNumber === 1) {
+    return 'RETRY';
+  }
+
+  // Retry also failed — try DECOMPOSE if the plan is decomposable
+  if (attemptNumber === 2 && isPlanDecomposable(planFilePath)) {
+    return 'DECOMPOSE';
+  }
+
+  // Cannot DECOMPOSE (or decompose also failed) — try PRUNE if not critical path
+  if (!isOnCriticalPath) {
+    return 'PRUNE';
+  }
+
+  // On critical path and all repair strategies exhausted — must ESCALATE
+  return 'ESCALATE';
+}
+
+/**
+ * Check if a plan can be split into independent sub-plans.
+ */
+function isPlanDecomposable(planFilePath) {
+  if (!fs.existsSync(planFilePath)) return false;
+  const content = fs.readFileSync(planFilePath, 'utf8');
+
+  // Count distinct file domains
+  const filesMatch = content.match(/<files>([\s\S]*?)<\/files>/);
+  if (!filesMatch) return false;
+  const files = filesMatch[1].trim().split('\n').filter(Boolean);
+
+  // Decomposable if:
+  // 1. More than 2 files (enough to split)
+  // 2. Files span different directories (different concerns)
+  if (files.length <= 1) return false;
+  const dirs = new Set(files.map(f => f.trim().split('/').slice(0, 2).join('/')));
+  return dirs.size > 1;
+}
+
+/**
+ * Generate RETRY context injection — adds error details for the retry subagent.
+ */
+function buildRetryContext(errorOutput, attemptNumber) {
+  const normalized = errorOutput
+    .split('\n')
+    .filter(l => /error|FAIL|error/i.test(l))
+    .slice(0, 5)
+    .join('\n');
+
+  return `
+[RETRY CONTEXT — attempt ${attemptNumber} of 2]
+Previous attempt failed with:
+${normalized}
+
+Instructions:
+- Do NOT repeat the same approach that caused this error
+- Fix the specific error above before implementing new functionality
+- If the error is an import/module error: verify the package is installed
+- If the error is a type error: check the exact type definitions
+- If the error is a test failure: read the test assertion carefully
+`.trim();
+}
+
+/**
+ * Build decomposed sub-plans from a failed plan.
+ * Returns two PLAN file contents as strings.
+ */
+function buildDecomposedPlans(planContent, originalPlanId, phase) {
+  const xmlMatch = planContent.match(/<task[^>]*>([\s\S]*?)<\/task>/);
+  if (!xmlMatch) return null;
+
+  const name       = (planContent.match(/<n>(.*?)<\/n>/) || [])[1] || 'Task';
+  const action     = (planContent.match(/<action>([\s\S]*?)<\/action>/) || [])[1] || '';
+  const filesMatch = planContent.match(/<files>([\s\S]*?)<\/files>/);
+  const files      = filesMatch ? filesMatch[1].trim().split('\n').filter(Boolean) : [];
+  const persona    = (planContent.match(/<persona>(.*?)<\/persona>/) || [])[1] || 'developer';
+
+  const mid      = Math.ceil(files.length / 2);
+  const filesA   = files.slice(0, mid);
+  const filesB   = files.slice(mid);
+  const idA      = `${originalPlanId}a`;
+  const idB      = `${originalPlanId}b`;
+
+  const planA = `<task type="auto">
+  <n>${name} — Part A (Foundation)</n>
+  <persona>${persona}</persona>
+  <phase>${phase}</phase>
+  <plan>${idA}</plan>
+  <decomposed_from>${originalPlanId}</decomposed_from>
+  <dependencies>${getPlanDependencies(planContent)}</dependencies>
+  <files>
+${filesA.map(f => `    ${f.trim()}`).join('\n')}
+  </files>
+  <action>
+${splitAction(action, 'first_half')}
+  </action>
+  <verify>Run the tests for the files modified in this sub-task only</verify>
+  <done>Part A files exist, compile cleanly, and their specific tests pass</done>
+</task>`;
+
+  const planB = `<task type="auto">
+  <n>${name} — Part B (Integration)</n>
+  <persona>${persona}</persona>
+  <phase>${phase}</phase>
+  <plan>${idB}</plan>
+  <decomposed_from>${originalPlanId}</decomposed_from>
+  <dependencies>${idA}</dependencies>
+  <files>
+${filesB.map(f => `    ${f.trim()}`).join('\n')}
+  </files>
+  <action>
+${splitAction(action, 'second_half')}
+  </action>
+  <verify>Run the full test suite for the entire ${name} feature</verify>
+  <done>All ${name} functionality working end-to-end</done>
+</task>`;
+
+  return { planA, planB, idA, idB };
+}
+
+/**
+ * Fix the dependency chain after decomposing a plan.
+ * Any plan that depended on the original plan now depends on the second sub-plan.
+ */
+function fixDependencyChain(phaseDir, originalPlanId, newDependentPlanId, phase) {
+  const planFiles = fs.readdirSync(phaseDir)
+    .filter(f => f.match(new RegExp(`^PLAN-${phase}-\\d`)) && f.endsWith('.md'));
+
+  let fixed = 0;
+  for (const planFile of planFiles) {
+    const filePath = path.join(phaseDir, planFile);
+    const content  = fs.readFileSync(filePath, 'utf8');
+
+    // Check if this plan depends on the original decomposed plan
+    const depPattern = new RegExp(`<dependencies>([^<]*\\b${originalPlanId}\\b[^<]*)</dependencies>`);
+    if (depPattern.test(content)) {
+      const updated = content.replace(depPattern, (match, deps) => {
+        const newDeps = deps.replace(new RegExp(`\\b${originalPlanId}\\b`, 'g'), newDependentPlanId);
+        return `<dependencies>${newDeps}</dependencies>`;
+      });
+      fs.writeFileSync(filePath, updated);
+      fixed++;
+    }
+  }
+  return fixed;
+}
+
+function getPlanDependencies(planContent) {
+  return (planContent.match(/<dependencies>(.*?)<\/dependencies>/) || [])[1] || 'none';
+}
+
+function splitAction(action, half) {
+  // Try period-delimited split first
+  const periodSplit = action.split(/\.\s+/);
+  if (periodSplit.length > 1) {
+    const mid = Math.ceil(periodSplit.length / 2);
+    return half === 'first_half'
+      ? periodSplit.slice(0, mid).join('. ').trim()
+      : periodSplit.slice(mid).join('. ').trim();
+  }
+
+  // Try newline-bullet split
+  const bulletSplit = action.split(/\n-\s+/);
+  if (bulletSplit.length > 1) {
+    const mid = Math.ceil(bulletSplit.length / 2);
+    return half === 'first_half'
+      ? bulletSplit.slice(0, mid).join('\n- ').trim()
+      : bulletSplit.slice(mid).join('\n- ').trim();
+  }
+
+  // Fallback: prefix the whole action with a half indicator
+  const prefix = half === 'first_half' ? 'First half of: ' : 'Second half of: ';
+  return prefix + action.trim().slice(0, Math.ceil(action.length / 2));
+}
+
+module.exports = {
+  determineRepairStrategy,
+  isPlanDecomposable,
+  buildRetryContext,
+  buildDecomposedPlans,
+  fixDependencyChain,
+};

package/.mindforge/mirrors/mirror-sre-776a1cf9/bin/autonomous/steer.js

@@ -0,0 +1,89 @@
+/**
+ * MindForge — Steering Manager
+ * Manages mid-execution guidance via steering-queue.jsonl.
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const QUEUE_PATH = path.join(process.cwd(), '.planning/steering-queue.jsonl');
+
+/**
+ * Add guidance to the queue.
+ */
+function pushGuidance(instruction, scope = 'global', taskId = null) {
+  const item = {
+    id: `steer-${Date.now()}`,
+    timestamp: new Date().toISOString(),
+    instruction,
+    scope,
+    taskId
+  };
+  fs.appendFileSync(QUEUE_PATH, JSON.stringify(item) + '\n');
+  return item.id;
+}
+
+/**
+ * Get and remove all pending guidance for the current context.
+ */
+function popGuidance(taskId = null) {
+  if (!fs.existsSync(QUEUE_PATH)) return [];
+
+  const lines = fs.readFileSync(QUEUE_PATH, 'utf8').split('\n').filter(Boolean);
+  const relevant = [];
+  const remaining = [];
+
+  for (const line of lines) {
+    const item = JSON.parse(line);
+    if (item.scope === 'global' || item.taskId === taskId) {
+      relevant.push(item);
+    } else {
+      remaining.push(item);
+    }
+  }
+
+  // Rewrite remaining
+  fs.writeFileSync(QUEUE_PATH, remaining.map(JSON.stringify).join('\n') + (remaining.length ? '\n' : ''));
+  return relevant;
+}
+
+/**
+ * Inject steering guidance into a PLAN file content.
+ */
+function injectSteering(planContent, guidanceItems) {
+  if (!guidanceItems || guidanceItems.length === 0) return planContent;
+
+  const guidanceText = guidanceItems
+    .map(g => `[STEERING GUIDANCE — DO NOT IGNORE] ${g.instruction}`)
+    .join('\n');
+
+  // Hardened injection: inject at beginning of <action> to ensure visibility
+  return planContent.replace(/<action>([\s\S]*?)<\/action>/, (match, action) => {
+    return `<action>\n${guidanceText}\n\nOriginal plan instructions:\n${action}\n</action>`;
+  });
+}
+
+/**
+ * Add human steering to the unified queue (v5 Pillar VII).
+ */
+function pushHumanSteering(instruction, bundleId = 'none') {
+  const STEER_PATH = path.join(process.cwd(), '.planning', 'STEER.json');
+  const item = {
+    id: `human-${Date.now()}`,
+    timestamp: new Date().toISOString(),
+    bundle_id: bundleId,
+    type: 'HUMAN_OVERRIDE',
+    instruction,
+    priority: 'CRITICAL'
+  };
+  fs.appendFileSync(STEER_PATH, JSON.stringify(item) + '\n');
+  return item.id;
+}
+
+module.exports = {
+  pushGuidance,
+  popGuidance,
+  injectSteering,
+  pushHumanSteering
+};

package/.mindforge/mirrors/mirror-sre-776a1cf9/bin/autonomous/stuck-monitor.js

@@ -0,0 +1,120 @@
+/**
+ * MindForge — Stuck Detection Engine
+ * Monitors AUDIT.jsonl for S01-S04 patterns.
+ */
+'use strict';
+
+const fs = require('fs');
+
+class StuckMonitor {
+  constructor(auditPath) {
+    this.auditPath = auditPath;
+    this.history = [];
+    this.patterns = {
+      S01_LINT_LOOP: 0,
+      S02_COMMAND_LOOP: 0,
+    };
+  }
+
+  analyze(event) {
+    this.history.push(event);
+    if (this.history.length > 50) this.history.shift();
+
+    // Check S01: Lint Loop (Identical multi_replace calls)
+    if (this.detectS01(event)) return { pattern: 'S01', message: 'Stuck in lint loop: identical edits detected.' };
+
+    // Check S02: Command Loop (Identical failing commands)
+    if (this.detectS02(event)) return { pattern: 'S02', message: 'Stuck in command loop: identical failing commands.' };
+
+    // Check S03: Semantic Mirroring (Reasoning Loop)
+    if (this.detectS03(event)) return { pattern: 'S03', message: 'Stuck in reasoning loop: semantic mirroring detected.' };
+
+    // Check S04: Infinite Decomposition (Planning Paradox)
+    if (this.detectS04(event)) return { pattern: 'S04', message: 'Stuck in planning paradox: infinite decomposition detected.' };
+
+    return null;
+  }
+
+  detectS03(event) {
+    if (event.event !== 'reasoning_trace') return false;
+
+    // Compare with the last 5 thoughts in history
+    const reflections = this.history.filter(h => h.event === 'reasoning_trace');
+    if (reflections.length < 3) return false;
+
+    const currentThought = event.thought;
+    const previousThoughts = reflections.slice(-4, -1);
+
+    const isMirroring = previousThoughts.some(p => 
+      this.isContentSimilar(p.thought, currentThought)
+    );
+
+    return isMirroring;
+  }
+
+  detectS04(event) {
+    if (event.event !== 'reasoning_trace') return false;
+
+    const decompositions = this.history.filter(h => 
+      h.event === 'reasoning_trace' && 
+      (h.thought?.toLowerCase().includes('break down') || h.thought?.toLowerCase().includes('sub-task'))
+    );
+
+    // If more than 4 consecutive decompositions without a command or edit
+    const lastActionIndex = this.history.findLastIndex(h => 
+      h.tool === 'run_command' || h.tool === 'replace_file_content' || h.tool === 'multi_replace_file_content'
+    );
+
+    const recentDecomps = decompositions.filter(d => 
+      this.history.indexOf(d) > lastActionIndex
+    );
+
+    return recentDecomps.length >= 4;
+  }
+
+  detectS01(event) {
+    if (event.tool !== 'multi_replace_file_content') return false;
+
+    const similar = this.history.filter(h =>
+      h.tool === 'multi_replace_file_content' &&
+      h.args?.TargetFile === event.args?.TargetFile &&
+      this.isContentSimilar(h.args?.ReplacementChunks?.[0]?.ReplacementContent, event.args?.ReplacementChunks?.[0]?.ReplacementContent)
+    );
+
+    return similar.length >= 3;
+  }
+
+  detectS02(event) {
+    if (event.tool !== 'run_command' || event.status !== 'failed') return false;
+
+    const identical = this.history.filter(h =>
+      h.tool === 'run_command' &&
+      h.status === 'failed' &&
+      h.args?.CommandLine === event.args?.CommandLine
+    );
+
+    return identical.length >= 3;
+  }
+
+  isContentSimilar(a, b) {
+    if (!a || !b) return false;
+    if (a === b) return true;
+    // Simple similarity check (hardened from Roadmap requirement)
+    const dist = this.levenshtein(a.slice(0, 100), b.slice(0, 100));
+    return dist < 10;
+  }
+
+  levenshtein(a, b) {
+    const tmp = [];
+    for (let i = 0; i <= a.length; i++) { tmp[i] = [i]; }
+    for (let j = 0; j <= b.length; j++) { tmp[0][j] = j; }
+    for (let i = 1; i <= a.length; i++) {
+        for (let j = 1; j <= b.length; j++) {
+            tmp[i][j] = Math.min(tmp[i - 1][j] + 1, tmp[i][j - 1] + 1, tmp[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+    }
+    return tmp[a.length][b.length];
+  }
+}
+
+module.exports = StuckMonitor;

package/.mindforge/mirrors/mirror-sre-776a1cf9/bin/browser/browser-daemon.js

@@ -0,0 +1,139 @@
+/**
+ * MindForge v2 — Browser Daemon
+ * Lightweight HTTP server controlling Chromium.
+ * Consistent with ADR-017 / ADR-024 (Localhost only).
+ */
+'use strict';
+
+const http      = require('http');
+const playwright = require('playwright-core');
+const fs        = require('fs');
+const path      = require('path');
+
+const PORT      = process.env.BROWSER_PORT || 7338;
+const HEADLESS  = process.env.BROWSER_HEADLESS !== 'false';
+const TIMEOUT   = (parseInt(process.env.BROWSER_IDLE_TIMEOUT_MINUTES) || 30) * 60 * 1000;
+
+let browser, lastActionAt = Date.now(), isLaunching = false;
+const sessions = new Map(); // name -> { context, page }
+
+async function init() {
+  if (isLaunching) return;
+  isLaunching = true;
+  try {
+    browser = await playwright.chromium.launch({
+      headless: HEADLESS,
+      args: ['--no-sandbox', '--disable-setuid-sandbox', '--no-first-run']
+    });
+    setInterval(checkIdle, 60000);
+  } finally {
+    isLaunching = false;
+  }
+}
+
+function checkIdle() {
+  if (Date.now() - lastActionAt > TIMEOUT) {
+    console.log('[daemon] Idle timeout reached. Shutting down.');
+    process.exit(0);
+  }
+}
+
+async function getOrCreateSession(name = 'default') {
+  if (sessions.has(name)) return sessions.get(name);
+  const context = await browser.newContext();
+  const page    = await context.newPage();
+  const s = { context, page };
+  sessions.set(name, s);
+  return s;
+}
+
+const server = http.createServer(async (req, res) => {
+  lastActionAt = Date.now();
+  const send = (data, code = 200) => {
+    res.writeHead(code, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(data));
+  };
+
+  // Only allow localhost
+  const remote = req.socket.remoteAddress;
+  if (remote !== '127.0.0.1' && remote !== '::1' && remote !== '::ffff:127.0.0.1') {
+    return send({ error: 'Forbidden: Localhost only' }, 403);
+  }
+
+  let body = '';
+  req.on('data', chunk => body += chunk);
+  req.on('end', async () => {
+    try {
+      const { url, session: sessionName, selector, text, script, type, expected_text, name } = body ? JSON.parse(body) : {};
+      const { page, context } = await getOrCreateSession(sessionName);
+
+      if (req.url === '/status' && req.method === 'GET') {
+        return send({ alive: true, sessions: Array.from(sessions.keys()), uptime: process.uptime() });
+      }
+
+      if (req.url === '/navigate' && req.method === 'POST') {
+        const start = Date.now();
+        const r = await page.goto(url, { waitUntil: 'load', timeout: 30000 });
+        return send({ 
+          success: true, 
+          status_code: r ? r.status() : 200, 
+          load_time_ms: Date.now() - start 
+        });
+      }
+
+      if (req.url === '/click' && req.method === 'POST') {
+        const target = selector ? page.locator(selector) : page.getByText(text, { exact: false });
+        await target.first().click({ timeout: 5000 });
+        return send({ success: true, element_found: true });
+      }
+
+      if (req.url === '/type' && req.method === 'POST') {
+        await page.locator(selector).fill(text, { timeout: 5000 });
+        return send({ success: true });
+      }
+
+      if (req.url === '/screenshot' && req.method === 'POST') {
+        const buf = await page.screenshot({ type: 'png' });
+        return send({ success: true, screenshot_b64: buf.toString('base64') });
+      }
+
+      if (req.url === '/evaluate' && req.method === 'POST') {
+        const result = await page.evaluate(script);
+        return send({ success: true, result });
+      }
+
+      if (req.url === '/assert' && req.method === 'POST') {
+        if (type === 'visible') {
+          const loc = page.locator(selector).first();
+          const visible = await loc.isVisible();
+          const actual = visible ? await loc.innerText() : '';
+          const passed = visible && (!expected_text || actual.includes(expected_text));
+          return send({ passed, actual_text: actual });
+        }
+        if (type === 'url') return send({ passed: page.url().includes(expected_text), actual_url: page.url() });
+        if (type === 'title') return send({ passed: (await page.title()).includes(expected_text), actual_title: await page.title() });
+        if (type === 'no_console_errors') return send({ passed: true }); // simplified
+      }
+
+      send({ error: 'Not Found' }, 404);
+    } catch (err) {
+      send({ success: false, error: err.message }, 500);
+    }
+  });
+});
+
+init().then(() => {
+  server.listen(PORT, '127.0.0.1', () => console.log(`[daemon] Browser daemon listening on port ${PORT}`));
+}).catch(err => {
+  console.error('[daemon] Initialization failed:', err);
+  process.exit(1);
+});
+
+async function shutdown() {
+  console.log('[daemon] Shutting down gracefully...');
+  if (browser) await browser.close();
+  process.exit(0);
+}
+
+process.on('SIGTERM', shutdown);
+process.on('SIGINT', shutdown);

package/.mindforge/mirrors/mirror-sre-776a1cf9/bin/browser/daemon-manager.js

@@ -0,0 +1,91 @@
+/**
+ * MindForge v2 — Browser Daemon Manager
+ * Starts and stops the browser-daemon.js process.
+ */
+'use strict';
+
+const { spawn, execSync } = require('child_process');
+const path = require('path');
+const fs   = require('fs');
+const http = require('http');
+
+const PORT = process.env.BROWSER_PORT || 7338;
+const DAEMON_SCRIPT = path.join(__dirname, 'browser-daemon.js');
+
+async function isRunning() {
+  return new Promise(resolve => {
+    const req = http.get(`http://127.0.0.1:${PORT}/status`, res => {
+      resolve(res.statusCode === 200);
+    });
+    req.on('error', () => resolve(false));
+    req.end();
+  });
+}
+
+async function start() {
+  if (await isRunning()) return;
+
+  const out = fs.openSync(path.join(process.cwd(), '.planning/browser-daemon.log'), 'a');
+  const err = fs.openSync(path.join(process.cwd(), '.planning/browser-daemon.log'), 'a');
+
+  const child = spawn(process.execPath, [DAEMON_SCRIPT], {
+    detached: true,
+    stdio: ['ignore', out, err],
+    env: { ...process.env, BROWSER_HEADLESS: 'true' }
+  });
+
+  child.unref();
+  console.log('[manager] Starting browser daemon...');
+
+  // Wait for it to wake up
+  for (let i = 0; i < 10; i++) {
+    await new Promise(r => setTimeout(r, 500));
+    if (await isRunning()) {
+      console.log('[manager] Browser daemon ready.');
+      return;
+    }
+  }
+  throw new Error('Timeout waiting for browser daemon to start');
+}
+
+async function stop() {
+  if (!(await isRunning())) return;
+  // Simple way to kill on localhost
+  try {
+    if (process.platform === 'win32') {
+      execSync(`for /f "tokens=5" %a in ('netstat -aon ^| find ":${PORT}" ^| find "LISTENING"') do taskkill /f /pid %a`);
+    } else {
+      execSync(`lsof -t -i:${PORT} | xargs kill -9`);
+    }
+    console.log('[manager] Browser daemon stopped.');
+  } catch (err) {
+    console.error('[manager] Failed to stop daemon:', err.message);
+  }
+}
+
+async function ensureRunning(opts = {}) {
+  if (!(await isRunning())) await start();
+}
+
+async function request(method, endpoint, body = null) {
+  return new Promise((resolve, reject) => {
+    const req = http.request({
+      hostname: '127.0.0.1',
+      port: PORT,
+      path: endpoint,
+      method: method,
+      headers: { 'Content-Type': 'application/json' }
+    }, res => {
+      let data = '';
+      res.on('data', chunk => data += chunk);
+      res.on('end', () => {
+        try { resolve(JSON.parse(data)); } catch { resolve({ success: false, error: 'Invalid JSON response' }); }
+      });
+    });
+    req.on('error', err => reject(err));
+    if (body) req.write(JSON.stringify(body));
+    req.end();
+  });
+}
+
+module.exports = { start, stop, isRunning, ensureRunning, request };

package/.mindforge/mirrors/mirror-sre-776a1cf9/bin/browser/qa-engine.js

@@ -0,0 +1,47 @@
+/**
+ * MindForge v2 — QA Engine
+ * Diff-aware systematic UI testing.
+ */
+'use strict';
+
+const { execSync } = require('child_process');
+const DaemonMgr    = require('./daemon-manager');
+const ScreenStore  = require('./screenshot-store');
+
+const DEV_SERVER = process.env.DEV_SERVER_URL || 'http://localhost:3000';
+
+function extractSurfaces() {
+  const files = execSync('git diff --name-only HEAD~1', { encoding: 'utf8' }).split('\n').filter(Boolean);
+  const surfaces = [];
+  for (const file of files) {
+    if (file.includes('pages/') || file.includes('app/')) {
+      const route = file.replace(/.*(pages|app)/, '').replace(/\.(tsx|jsx|ts|js)$/, '').replace(/\/page$/, '').replace(/\/index$/, '') || '/';
+      surfaces.push({ file, route });
+    }
+  }
+  return surfaces;
+}
+
+async function runQA(phaseNum) {
+  await DaemonMgr.ensureRunning();
+  const surfaces = extractSurfaces();
+  const results = [];
+  const bugs = [];
+
+  for (const surface of surfaces) {
+    const route = surface.route;
+    const r = await DaemonMgr.request('POST', '/navigate', { url: `${DEV_SERVER}${route}`, session: 'default' });
+    const passed = r.success && r.status_code < 400;
+    
+    if (!passed) {
+      const snap = await DaemonMgr.request('POST', '/screenshot', { session: 'default' });
+      const shot = snap.success ? ScreenStore.save(snap.screenshot_b64, phaseNum, 'qa', `fail-${route.replace(/\//g, '-')}.png`) : null;
+      bugs.push({ surface: route, error: r.error || `Status ${r.status_code}`, screenshot: shot });
+    }
+    results.push({ surface: route, passed });
+  }
+
+  return { surfaces: surfaces.length, passed: results.filter(r => r.passed).length, failed: bugs.length, results, bugs };
+}
+
+module.exports = { runQA };