@progen-labs/spectra 0.2.0 → 0.4.0

package/server/fix/cli.js

@@ -0,0 +1,237 @@
+/**
+ * spectra fix — the AI fix harness. It runs in the user's project: profiles a
+ * copy of the last commit, hands the costliest findings in the project's own
+ * code to a coding agent one at a time, and keeps a change only when the
+ * project's checks pass and Spectra measures it faster beyond run-to-run
+ * noise. Kept changes are commits on a new branch; nothing else is touched.
+ */
+import { spawn, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { intOption, parseArgs } from '../args.js';
+import { bootDevServer } from '../explore/boot.js';
+import { SPECTRA_VERSION } from '../output.js';
+import { claudeAgent, commandAgent } from './agent.js';
+import { detectChecks, runChecks } from './checks.js';
+import { runFix } from './harness.js';
+import { reportMarkdown } from './report.js';
+import { changesIn, commitChange, commitsOn, createWorkspace, diffOf, ignoreSpectra, removeWorkspace, repoOf, uncommitted, undoChanges } from './workspace.js';
+
+const BIN = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../bin/spectra.js');
+const argv = process.argv.slice(3);
+const { opt, flag } = parseArgs(argv, { values: ['runs', 'max-fixes', 'agent', 'model', 'max-budget-usd', 'check', 'command', 'boot-timeout', 'branch', 'out', 'max-lines'] });
+const log = line => console.error(`spectra: ${line}`);
+const json = flag('json');
+
+const HELP = `usage: spectra fix [options]
+
+The AI fix harness. In an isolated copy of your last commit, it hands the
+costliest findings in your own code to a coding agent one at a time, then
+keeps a change only if your checks pass and Spectra measures it faster
+beyond run-to-run noise. Kept changes are commits on a new branch.
+
+  --max-fixes <n>         Findings to attempt (default 3)
+  --runs <n>              Page loads per measurement (default 3)
+  --check "<cmd>"         A check that must pass after every change (repeat it
+                          for several). Default: your test, typecheck and
+                          build scripts. Checks can test the running app at
+                          $SPECTRA_FIX_URL.
+  --no-checks             Rely on measurements alone (not recommended)
+  --agent "<cmd>"         Your own agent: gets the instructions on stdin and in
+                          $SPECTRA_FIX_PROMPT_FILE, runs in the copy
+  --model <name>          Model for Claude Code, the default agent
+  --max-budget-usd <n>    Claude Code's spending cap per finding (default 2)
+  --command "<cmd>"       The dev-server command (default: your npm dev script)
+  --boot-timeout <s>      How long to wait for the dev server (default 60)
+  --install               Install dependencies in the copy instead of linking yours
+  --branch <name>         Branch for the fixes (default spectra/fix-<time>)
+  --max-lines <n>         Largest change accepted (default 150 lines)
+  --retry                 Try findings that failed in an earlier session
+  --keep-worktree         Keep the copy in .spectra/fix/ for inspection
+  --json, --out <file>    Machine-readable session report`;
+
+if (flag('help') || flag('h')) {
+  console.log(HELP);
+  process.exit(0);
+}
+
+const fail = (message, code = 1) => {
+  console.error(`spectra: ${message}`);
+  process.exit(code);
+};
+
+const checksFrom = () => {
+  const list = [];
+  for (let i = 0; i < argv.length; i++) if (argv[i] === '--check' && argv[i + 1]) list.push({ name: argv[i + 1], cmd: argv[++i] });
+  return list;
+};
+
+let runs;
+let maxFixes;
+let maxLines;
+try {
+  runs = intOption(opt('runs'), 'runs', { min: 1, max: 10, fallback: 3 });
+  maxFixes = intOption(opt('max-fixes'), 'max-fixes', { min: 1, max: 20, fallback: 3 });
+  maxLines = intOption(opt('max-lines'), 'max-lines', { min: 1, max: 5000, fallback: 150 });
+} catch (err) {
+  fail(err.message);
+}
+if (opt('url')) fail('spectra fix starts its own dev server in a copy of your project, so it does not take --url. Use --command if the dev server needs a special command.');
+
+const projectDir = process.cwd();
+let repo;
+try {
+  repo = repoOf(projectDir);
+} catch (err) {
+  fail(err.message);
+}
+const dirty = uncommitted(repo.root);
+if (dirty.length)
+  fail(`commit or stash your changes first: spectra fix works on a copy of your last commit, and these would not be in it:\n  ${dirty.slice(0, 6).join('\n  ')}${dirty.length > 6 ? '\n  …' : ''}`);
+
+let checks = checksFrom();
+if (!checks.length && !flag('no-checks')) checks = detectChecks(projectDir);
+if (!checks.length && !flag('no-checks'))
+  fail('no checks to run. A faster page must not be a broken one, so spectra fix needs at least one check that proves the app still works: add a test script, pass --check "<cmd>" (it can test the running app at $SPECTRA_FIX_URL), or pass --no-checks to rely on measurements alone.');
+if (flag('no-checks')) checks = [];
+
+const agent = opt('agent')
+  ? commandAgent(String(opt('agent')))
+  : claudeAgent({ model: opt('model') === true ? undefined : opt('model'), budgetUsd: Number(opt('max-budget-usd') ?? 2) });
+
+const stamp = new Date().toISOString().replace(/[-:]/g, '').replace(/\..+/, '').replace('T', '-');
+const sessionRoot = path.join(projectDir, '.spectra', 'fix');
+const sessionDir = path.join(sessionRoot, stamp);
+const historyFile = path.join(sessionRoot, 'history.json');
+let branch = typeof opt('branch') === 'string' ? opt('branch') : `spectra/fix-${stamp}`;
+fs.mkdirSync(path.join(sessionDir, 'results'), { recursive: true });
+ignoreSpectra(repo.root);
+
+const controller = new AbortController();
+let ws = null;
+let server = null;
+let child = null;
+let session = null;
+
+async function cleanup() {
+  await server?.stop().catch(() => {});
+  if (ws && !flag('keep-worktree')) removeWorkspace(repo.root, ws, { keepBranch: commitsOn(repo.root, ws.branch) > 0 });
+}
+for (const signal of ['SIGINT', 'SIGTERM']) {
+  process.on(signal, () => {
+    controller.abort();
+    child?.kill('SIGTERM');
+    log('stopping …');
+    cleanup().finally(() => process.exit(signal === 'SIGINT' ? 130 : 143));
+  });
+}
+
+/** `spectra <args> --json` in the copy; resolves with the parsed result. */
+function spectra(args) {
+  return new Promise((resolve, reject) => {
+    child = spawn(process.execPath, [BIN, ...args, '--json'], {
+      cwd: ws.projectDir,
+      env: { ...process.env, PERF_FRONTEND_DIR: ws.projectDir, PERF_REPORTS_DIR: path.join(sessionDir, 'reports') },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let out = '';
+    let err = '';
+    child.stdout.on('data', d => (out += d));
+    child.stderr.on('data', d => {
+      err += d;
+      for (const line of String(d).split('\n')) if (/^spectra: run \d+\/\d+/.test(line)) console.error(`           ${line.replace(/^spectra:\s*/, '')}`);
+    });
+    child.on('error', reject);
+    child.on('close', code => {
+      if (code === 1) return reject(new Error(err.trim().split('\n').filter(l => l.startsWith('spectra:')).pop()?.replace(/^spectra:\s*/, '') || `spectra ${args[0]} failed`));
+      try {
+        resolve(JSON.parse(out));
+      } catch {
+        reject(new Error(`spectra ${args[0]} printed no result`));
+      }
+    });
+  });
+}
+
+const slug = s => s.replace(/[^a-z0-9]+/gi, '-').replace(/^-|-$/g, '').toLowerCase();
+
+try {
+  if (branchExists(branch)) throw new Error(`branch ${branch} already exists; pass --branch <name>.`);
+  log(`working in a copy of ${shortHead()} on branch ${branch} …`);
+  ws = createWorkspace({ root: repo.root, sub: repo.sub, dir: path.join(sessionDir, 'worktree'), branch, install: flag('install'), log });
+  ws.exists = file => fs.existsSync(path.join(ws.projectDir, file));
+  ws.changes = () => changesIn(ws);
+  ws.diff = () => diffOf(ws);
+  ws.commit = (files, message) => commitChange(ws, files, message);
+  ws.undo = () => undoChanges(ws);
+
+  const command = typeof opt('command') === 'string' ? opt('command') : undefined;
+  log(`starting the dev server in the copy${command ? ` (${command})` : ''} …`);
+  server = await bootDevServer({ root: ws.projectDir, command, timeoutMs: (Number(opt('boot-timeout')) || 60) * 1000 });
+  log(`dev server ready at ${server.url}`);
+
+  let history = {};
+  try {
+    history = JSON.parse(fs.readFileSync(historyFile, 'utf8'));
+  } catch {
+    /* first session */
+  }
+
+  session = await runFix({
+    agent,
+    workspace: ws,
+    checks,
+    history,
+    retry: flag('retry'),
+    maxFixes,
+    maxLines,
+    url: server.url,
+    signal: controller.signal,
+    log,
+    runChecks: () => runChecks(checks, { cwd: ws.projectDir, env: { SPECTRA_FIX_URL: server.url }, signal: controller.signal }),
+    profile: async label => {
+      const file = path.join(sessionDir, 'results', `${slug(label)}.json`);
+      const result = await spectra(['performance', '--quick', '--runs', String(runs), '--url', server.url, '--out', file]);
+      return { file, result };
+    },
+    compare: async (before, after) => (await spectra(['compare', before.join(','), after.join(',')])).comparison,
+  });
+  Object.assign(session, { kind: 'fix', spectraVersion: SPECTRA_VERSION, project: projectDir, branch, runs, startedAt: stamp, sessionDir });
+
+  for (const a of session.attempts) history[a.finding.key] = { title: a.finding.title, outcome: a.outcome, at: new Date().toISOString() };
+  fs.writeFileSync(historyFile, `${JSON.stringify(history, null, 2)}\n`);
+} catch (err) {
+  console.error(`spectra: ${err.message}`);
+  if (err.tail) console.error(err.tail.replace(/^/gm, '  | '));
+  if (/cannot work/.test(err.message) && !opt('agent'))
+    console.error('spectra: sign in to Claude Code first (run `claude` once), set SPECTRA_CLAUDE to its path, or pass --agent "<command>".');
+  await cleanup();
+  process.exit(1);
+}
+
+await cleanup();
+const md = reportMarkdown(session);
+fs.writeFileSync(path.join(sessionDir, 'report.md'), md);
+fs.writeFileSync(path.join(sessionDir, 'report.json'), `${JSON.stringify(session, null, 2)}\n`);
+if (opt('out') && typeof opt('out') === 'string') fs.writeFileSync(path.resolve(opt('out')), `${JSON.stringify(session, null, 2)}\n`);
+
+const rel = p => path.relative(projectDir, p) || '.';
+console.error('');
+console.error(`Spectra fix — ${session.kept} of ${session.attempts.length} finding${session.attempts.length === 1 ? '' : 's'} fixed`);
+for (const a of session.attempts) console.error(`  ${a.outcome === 'kept' ? '✓ kept    ' : '✗ undone  '} ${a.finding.title} (${a.finding.file}${a.finding.line ? `:${a.finding.line}` : ''})${a.outcome === 'kept' ? '' : ` — ${a.reason}`}`);
+if (session.final) {
+  console.error(`\nOverall: ${session.final.verdict.toUpperCase()} (confidence: ${session.final.confidence})`);
+  for (const h of session.final.headlines) console.error(`  ${h.kind === 'improved' ? '✓' : '✗'} ${h.text}`);
+}
+if (session.kept) console.error(`\nThe fixes are on branch ${branch}. Review them with:\n  git log -p HEAD..${branch}\nthen merge the branch or open a pull request.`);
+console.error(`\nReport: ${rel(path.join(sessionDir, 'report.md'))}`);
+if (json) process.stdout.write(`${JSON.stringify(session)}\n`);
+process.exit(0);
+
+function branchExists(name) {
+  return spawnSync('git', ['rev-parse', '--verify', '--quiet', `refs/heads/${name}`], { cwd: repo.root }).status === 0;
+}
+function shortHead() {
+  return spawnSync('git', ['rev-parse', '--short', 'HEAD'], { cwd: repo.root, encoding: 'utf8' }).stdout.trim();
+}

package/server/fix/harness.js

@@ -0,0 +1,138 @@
+/**
+ * The loop of `spectra fix`: measure, hand one finding to an agent, check its
+ * change, measure again, and keep the change only if it measurably helped.
+ * Everything it touches is passed in (profile, compare, agent, workspace,
+ * checks), so the loop itself is tested without a browser or a model.
+ */
+import { fixPrompt, judge, rankFindings, scopeProblem } from './policy.js';
+
+// agent errors no other finding would get past: stop instead of trying them all
+const FATAL = /not logged in|\/login|authenticat|api key|credit balance|was not found|could not start/i;
+
+/**
+ * @param {object} o
+ * @param {(label: string) => Promise<{file: string, result: object}>} o.profile
+ * @param {(before: string[], after: string[]) => Promise<object>} o.compare   spectra compare's comparison
+ * @param {{name: string, run: Function}} o.agent
+ * @param {object} o.workspace   { projectDir, exists(file), changes(), diff(), commit(files, message), undo() }
+ * @param {() => Promise<{name: string, ok: boolean}[]>} o.runChecks
+ * @param {{name: string}[]} o.checks
+ * @returns {Promise<object>} the session: baseline, attempts, overall comparison
+ */
+export async function runFix(o) {
+  const { profile, compare, agent, workspace: ws, runChecks, checks = [], log = () => {}, maxFixes = 3, maxLines = 150, history = {}, retry = false, url, signal } = o;
+  const session = { agent: agent.name, checks: checks.map(c => c.name), attempts: [], skipped: [], baseline: null, final: null, kept: 0 };
+
+  if (checks.length) {
+    log(`running the checks before any change (${checks.map(c => c.name).join(', ')}) …`);
+    const before = await runChecks();
+    const failed = before.find(r => !r.ok);
+    if (failed) throw Object.assign(new Error(`"${failed.name}" fails before any change, so it cannot tell a good fix from a bad one. Fix it first, or choose checks with --check.`), { tail: failed.tail });
+  }
+
+  log('measuring the baseline …');
+  const baseline = await profile('baseline');
+  session.baseline = { file: baseline.file, summary: baseline.result.summary, url: baseline.result.url };
+  let current = [baseline.file];
+
+  const { candidates, skipped } = rankFindings(baseline.result.findings, { exists: ws.exists, history, retry, max: maxFixes });
+  session.skipped = skipped.map(s => ({ title: s.finding.title, reason: s.reason }));
+  if (!candidates.length) {
+    log('no findings in your own code to fix.');
+    return session;
+  }
+  log(`${candidates.length} finding${candidates.length === 1 ? '' : 's'} to attempt, most costly first.`);
+
+  for (const [i, f] of candidates.entries()) {
+    if (signal?.aborted) break;
+    const n = `${i + 1}/${candidates.length}`;
+    const attempt = { finding: { title: f.title, file: f.file, line: f.line, severity: f.severity, impactMs: f.impactMs, key: f.key }, outcome: null, reason: '', changes: [] };
+    session.attempts.push(attempt);
+    const discard = (outcome, reason) => {
+      ws.undo();
+      Object.assign(attempt, { outcome, reason });
+      log(`[${n}] ✗ ${reason} — change undone.`);
+    };
+
+    log(`[${n}] ${f.title} — ${f.file}${f.line ? `:${f.line}` : ''}`);
+    log(`[${n}] asking ${agent.name} for one focused change …`);
+    const t0 = Date.now();
+    try {
+      const res = await agent.run(fixPrompt(f, { url }), { cwd: ws.projectDir, signal, finding: attempt.finding });
+      Object.assign(attempt, { summary: res.summary, costUsd: res.costUsd, agentMs: Date.now() - t0 });
+      if (res.error) throw new Error(res.error);
+    } catch (err) {
+      discard('agent-error', `the agent failed: ${err.message}`);
+      if (FATAL.test(err.message)) throw Object.assign(new Error(`${agent.name} cannot work: ${err.message}`), { session });
+      continue;
+    }
+
+    const changes = ws.changes();
+    attempt.changes = changes;
+    if (!changes.length) {
+      Object.assign(attempt, { outcome: 'no-change', reason: 'the agent made no change' });
+      log(`[${n}] – the agent made no change.`);
+      continue;
+    }
+    attempt.diff = ws.diff();
+    log(`[${n}] changed ${changes.map(c => `${c.path} (+${c.added} −${c.removed})`).join(', ')}${attempt.summary ? `: ${attempt.summary}` : ''}`);
+    const problem = scopeProblem(changes, { maxLines });
+    if (problem) {
+      discard('out-of-scope', problem);
+      continue;
+    }
+
+    if (checks.length) {
+      log(`[${n}] running the checks …`);
+      const results = await runChecks();
+      attempt.checks = results.map(r => ({ name: r.name, ok: r.ok }));
+      const failed = results.find(r => !r.ok);
+      if (failed) {
+        attempt.checkTail = failed.tail;
+        discard('checks-failed', `"${failed.name}" failed`);
+        continue;
+      }
+    }
+
+    log(`[${n}] measuring the change …`);
+    const after = [await profile(`after ${i + 1}`)];
+    let comparison = await compare(current, after.map(a => a.file));
+    let verdict = judge(comparison);
+    if (verdict.decision === 'measure-again') {
+      log(`[${n}] improved with low confidence; measuring again …`);
+      after.push(await profile(`after ${i + 1}, more runs`));
+      comparison = await compare(current, after.map(a => a.file));
+      verdict = judge(comparison);
+      if (verdict.decision === 'measure-again') verdict = { decision: 'discard', outcome: 'unproven', reason: 'not proven: still low confidence after more runs' };
+    }
+    attempt.comparison = { verdict: comparison.verdict, confidence: comparison.confidence, headlines: comparison.headlines, resolved: comparison.findings.resolved.map(x => x.title), added: comparison.findings.added.map(x => x.title) };
+    if (verdict.decision !== 'keep') {
+      discard(verdict.outcome, verdict.reason);
+      continue;
+    }
+
+    const message = [
+      `perf: ${f.title.replace(/\s+/g, ' ').slice(0, 72)}`,
+      '',
+      ...(attempt.summary ? [attempt.summary, ''] : []),
+      `Verified by spectra fix: ${comparison.verdict} (confidence: ${comparison.confidence}).`,
+      ...verdict.headlines.map(h => `- ${h}`),
+      ...(attempt.checks?.length ? [`Checks passed: ${attempt.checks.map(c => c.name).join(', ')}.`] : []),
+      `Finding: ${f.file}${f.line ? `:${f.line}` : ''}`,
+    ].join('\n');
+    attempt.commit = ws.commit(
+      changes.map(c => c.path),
+      message,
+    );
+    Object.assign(attempt, { outcome: 'kept', reason: verdict.reason });
+    session.kept++;
+    current = after.map(a => a.file);
+    log(`[${n}] ✓ kept (${attempt.commit}): ${verdict.reason}`);
+  }
+
+  if (session.kept) {
+    const overall = await compare([baseline.file], current);
+    session.final = { verdict: overall.verdict, confidence: overall.confidence, headlines: overall.headlines, resolved: overall.findings.resolved.map(x => x.title) };
+  }
+  return session;
+}

package/server/fix/policy.js

@@ -0,0 +1,126 @@
+/**
+ * The rules of `spectra fix`: which findings to attempt, what an agent may
+ * change, and when a change has earned its place. Pure functions, so the
+ * rules are tested on their own (test-fix.js).
+ */
+import { findingKey } from '../../shared/compare.js';
+
+const SEVERITY = { critical: 0, warning: 1 };
+
+/** A finding's source file, when it points into the project (not a dependency or a URL). */
+export function ownFile(f) {
+  const file = f.file || f.culprits?.find(c => c.file)?.file || null;
+  if (!file || /^[a-z]+:\/\//i.test(file) || /(^|\/)node_modules\//.test(file) || file.startsWith('/@') || file.startsWith('..')) return null;
+  return file.replace(/^\.\//, '');
+}
+
+/**
+ * The findings worth an attempt, most costly first: critical or warning,
+ * pointing at a file in the project, one per place in the code, and not one
+ * that failed in an earlier session (unless retry).
+ *
+ * @param {object[]} findings   brief findings from a profile result
+ * @param {object} o
+ * @param {(file: string) => boolean} o.exists
+ * @param {Record<string, {outcome: string}>} [o.history]
+ * @returns {{ candidates: object[], skipped: {finding: object, reason: string}[] }}
+ */
+export function rankFindings(findings, { exists, history = {}, retry = false, max = 3 }) {
+  const candidates = [];
+  const skipped = [];
+  const taken = new Set();
+  const ordered = [...(findings || [])].sort(
+    (a, b) => (SEVERITY[a.severity] ?? 9) - (SEVERITY[b.severity] ?? 9) || (b.impactMs || 0) - (a.impactMs || 0),
+  );
+  for (const f of ordered) {
+    if (!(f.severity in SEVERITY)) continue;
+    const file = ownFile(f);
+    if (!file || !exists(file)) continue;
+    const key = findingKey(f);
+    const spot = `${file}:${f.line ?? ''}`;
+    if (taken.has(spot) || taken.has(key)) continue;
+    const past = history[key];
+    if (past && past.outcome !== 'kept' && !retry) {
+      skipped.push({ finding: f, reason: `an earlier attempt was ${past.outcome.replace(/-/g, ' ')} (use --retry to try again)` });
+      continue;
+    }
+    taken.add(spot);
+    taken.add(key);
+    candidates.push({ ...f, file, key });
+    if (candidates.length >= max) break;
+  }
+  return { candidates, skipped };
+}
+
+// files an agent must not touch: dependencies, tooling, tests and CI
+const OFF_LIMITS = [
+  /(^|\/)package\.json$/,
+  /(^|\/)(package-lock\.json|npm-shrinkwrap\.json|yarn\.lock|pnpm-lock\.yaml|bun\.lockb?)$/,
+  /(^|\/)[^/]*\.config\.[cm]?[jt]s$/,
+  /(^|\/)tsconfig[^/]*\.json$/,
+  /(^|\/)\.(eslintrc|prettierrc|babelrc)[^/]*$/,
+  /(^|\/)spectra\.config\.json$/,
+  /(^|\/)(__tests__|__snapshots__|tests?|e2e|cypress|playwright)\//,
+  /\.(test|spec)\.[cm]?[jt]sx?$/,
+  /(^|\/)\.github\//,
+  /(^|\/)\.spectra\//,
+];
+
+/**
+ * What is wrong with a proposed change, if anything.
+ * @param {{path: string, status: string, added: number, removed: number}[]} changes
+ */
+export function scopeProblem(changes, { maxLines = 150 } = {}) {
+  if (!changes.length) return null;
+  const deleted = changes.find(c => c.status === 'D');
+  if (deleted) return `deleted ${deleted.path}`;
+  const forbidden = changes.find(c => OFF_LIMITS.some(re => re.test(c.path)));
+  if (forbidden) return `changed ${forbidden.path}, which a fix may not touch (dependencies, configuration, tests and CI are off limits)`;
+  const lines = changes.reduce((n, c) => n + c.added + c.removed, 0);
+  if (lines > maxLines) return `${lines} changed lines, more than the ${maxLines} allowed for one focused fix`;
+  return null;
+}
+
+/**
+ * Keep, discard or measure again, from spectra compare's comparison of the
+ * code before the change with the code after it.
+ */
+export function judge(c) {
+  if (!c) return { decision: 'discard', outcome: 'not-measured', reason: 'nothing to compare' };
+  const worse = c.headlines.filter(h => h.kind === 'degraded').map(h => h.text);
+  const better = c.headlines.filter(h => h.kind === 'improved').map(h => h.text);
+  if (c.verdict === 'regressed') return { decision: 'discard', outcome: 'slower', reason: `slower: ${worse[0] || 'a key metric got worse'}` };
+  if (c.verdict === 'mixed') return { decision: 'discard', outcome: 'mixed', reason: `mixed: ${worse[0] || 'something got worse'}` };
+  if (c.verdict !== 'improved') return { decision: 'discard', outcome: 'no-gain', reason: 'no measurable improvement: every change was within run-to-run noise' };
+  const critical = c.findings.added.find(f => f.severity === 'critical');
+  if (critical) return { decision: 'discard', outcome: 'new-problem', reason: `introduced a critical finding: ${critical.title}` };
+  if (c.confidence === 'low') return { decision: 'measure-again', outcome: 'unproven', reason: 'improved, but with low confidence' };
+  return { decision: 'keep', outcome: 'kept', reason: better[0] || 'improved', headlines: better };
+}
+
+/** The instructions an agent gets for one finding. */
+export function fixPrompt(f, { url } = {}) {
+  const culprits = (f.culprits || [])
+    .slice(0, 5)
+    .map(c => `  - ${c.fn || '(anonymous)'}${c.file ? ` in ${c.file}${c.line ? `:${c.line}` : ''}` : ''}${c.ms ? `: ${c.ms} ms` : ''}${c.note ? ` (${c.note})` : ''}`);
+  return [
+    'Fix one frontend performance problem that Spectra, a profiler, measured in this project.',
+    '',
+    `Finding: ${f.title}`,
+    `Where: ${f.file}${f.line ? `:${f.line}` : ''}`,
+    `Cost: about ${f.impactMs} ms${f.seenIn ? `, seen in ${f.seenIn} runs` : ''}`,
+    ...(f.detail ? [`Detail: ${f.detail}`] : []),
+    ...(culprits.length ? ['Where the time went:', ...culprits] : []),
+    ...(f.fix ? [`Suggested fix: ${f.fix}`] : []),
+    '',
+    'Make ONE focused change that removes or reduces this cost.',
+    'Rules:',
+    '- Keep the behaviour exactly the same: the same output, UI and data. Never delete features, skip work the page needs, or hide content to look faster.',
+    '- Edit only the source files involved. Do not edit package.json, lockfiles, configuration, tests or CI files, and do not delete files.',
+    '- Keep the change small: a few lines to a few dozen.',
+    "- Do not run commands. Spectra runs the project's checks and measures the change after you finish.",
+    ...(url ? [`- The app is served at ${url} while you work, if you want to read it.`] : []),
+    '',
+    'When you are done, reply with one sentence that describes the change.',
+  ].join('\n');
+}

package/server/fix/report.js

@@ -0,0 +1,38 @@
+/**
+ * The session report: a Markdown summary for people (and pull requests) and
+ * the JSON behind it.
+ */
+const OUTCOME = {
+  kept: '✅ kept',
+  'no-change': '➖ no change',
+  'out-of-scope': '⛔ out of scope',
+  'checks-failed': '❌ checks failed',
+  'no-gain': '➖ no measurable gain',
+  slower: '❌ slower',
+  mixed: '⚠️ mixed',
+  'new-problem': '❌ new problem',
+  unproven: '➖ not proven',
+  'agent-error': '⚠️ agent error',
+};
+
+export function reportMarkdown(s) {
+  const lines = [
+    `## ⚡ Spectra fix: ${s.kept} of ${s.attempts.length} finding${s.attempts.length === 1 ? '' : 's'} fixed`,
+    '',
+    `Agent: ${s.agent} · checks: ${s.checks.length ? s.checks.join(', ') : 'none'} · ${s.runs} page-load runs per measurement${s.branch && s.kept ? ` · branch \`${s.branch}\`` : ''}`,
+    '',
+  ];
+  if (s.final) {
+    lines.push(`**Overall, before → after all kept fixes:** ${s.final.verdict} (confidence: ${s.final.confidence})`, '', ...s.final.headlines.map(h => `- ${h.kind === 'improved' ? '✅' : '❌'} ${h.text}`), '');
+  }
+  if (s.attempts.length) {
+    lines.push('| Finding | Where | Outcome | Why |', '| --- | --- | --- | --- |');
+    for (const a of s.attempts)
+      lines.push(`| ${a.finding.title.replace(/\|/g, '\\|')} | \`${a.finding.file}${a.finding.line ? `:${a.finding.line}` : ''}\` | ${OUTCOME[a.outcome] || a.outcome}${a.commit ? ` (${a.commit})` : ''} | ${(a.reason || '').replace(/\|/g, '\\|')} |`);
+    lines.push('');
+  }
+  for (const a of s.attempts.filter(x => x.summary)) lines.push(`- **${a.finding.title}**: ${a.summary}`);
+  if (s.skipped.length) lines.push('', 'Skipped:', ...s.skipped.map(x => `- ${x.title}: ${x.reason}`));
+  lines.push('', '<sub>Every kept change passed the checks and measured faster beyond run-to-run noise. Review it like any other change.</sub>');
+  return `${lines.join('\n')}\n`;
+}