@elalfner/relevo 0.6.0 → 0.7.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "relevo",
   "displayName": "Relevo",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "An automatic issue-to-merge workflow where an agent builds and people verify.",
   "author": {
     "name": "Elias Alfaro"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elalfner/relevo",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Relevo: an automatic issue-to-merge workflow where an agent builds and people verify.",
   "type": "module",
   "license": "MIT",

package/scripts/dev-server-guard.mjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+// Says whether the working tree may switch branches: a dev server of the address under review that runs from it
+// would lose its files. Usage:
+//   node scripts/dev-server-guard.mjs --url http://localhost:5173
+// Prints { code, servers, reason } as JSON.
+//   exit 0: no server of that address runs from the working tree   exit 1: one does (stop it before switching)
+//   exit 3: it cannot tell (no lsof, or the folder cannot be read): do not switch   exit 2: bad arguments
+
+import { realpathSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { guard } from './lib/dev-server-guard.mjs';
+
+const i = process.argv.indexOf('--url');
+const url = i === -1 ? undefined : process.argv[i + 1];
+try {
+  if (!url || !/^https?:$/.test(new URL(url).protocol)) throw new Error();
+} catch {
+  console.error('usage: dev-server-guard.mjs --url <http address>');
+  process.exit(2);
+}
+const top = spawnSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' });
+if (top.status !== 0) {
+  console.error('not inside a git repository');
+  process.exit(2);
+}
+const lsof = (args) => {
+  const r = spawnSync('lsof', args, { encoding: 'utf8' });
+  return { status: r.error ? 127 : r.status ?? 1, stdout: r.stdout ?? '' };
+};
+const result = guard({ url, repoRoot: top.stdout.trim() }, { lsof, realpath: realpathSync });
+console.log(JSON.stringify(result));
+process.exit(result.code);

package/scripts/extra-server.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+// Starts, checks and stops the dev servers the agent needs for lines that require another configuration. Usage:
+//   node scripts/extra-server.mjs start --port 5174 [--set NAME=value ...] [--unset NAME ...] -- npx vite --port 5174 --strictPort
+//   node scripts/extra-server.mjs check --port 5174     after web-preflight.mjs --wait: the port is served by that server
+//   node scripts/extra-server.mjs stop --port 5174 | --all
+// Each server runs in a process group of its own, logs to evidence/servers/<port>.log and is recorded in
+// evidence/servers.json (override the folder with --dir). Only recorded servers are ever stopped, so the person's own
+// server is never touched. The environment files are never read; their names only decide whether --unset can work.
+//   exit 0: done   exit 1: not recorded, or the port is not served by the recorded server (it was stopped)
+//   exit 2: bad arguments   exit 3: the port is busy   exit 4: --unset with environment files present   exit 5: no lsof
+
+import { existsSync, mkdirSync, openSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { spawn, spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+import { checkServer, parseSet, startServer, stopServers } from './lib/extra-server.mjs';
+
+const dash = process.argv.indexOf('--');
+const argv = dash === -1 ? process.argv.slice(2) : process.argv.slice(2, dash);
+const command = dash === -1 ? [] : process.argv.slice(dash + 1);
+const [action] = argv;
+const values = (name) => argv.flatMap((a, i) => (a === `--${name}` ? [argv[i + 1]] : []));
+const usage = (message) => {
+  if (message) console.error(message);
+  console.error('usage: extra-server.mjs start --port <p> [--set NAME=value] [--unset NAME] -- <command>\n       extra-server.mjs check --port <p>\n       extra-server.mjs stop --port <p> | --all');
+  process.exit(2);
+};
+
+const dir = values('dir')[0] ?? 'evidence';
+const file = join(dir, 'servers.json');
+const port = values('port')[0] === undefined ? null : Number(values('port')[0]);
+const lsof = (args) => {
+  const r = spawnSync('lsof', args, { encoding: 'utf8' });
+  return { status: r.error ? 127 : r.status ?? 1, stdout: r.stdout ?? '' };
+};
+const deps = {
+  lsof,
+  dir,
+  baseEnv: process.env,
+  listDir: () => readdirSync(process.cwd()),
+  load: () => (existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : []),
+  save: (records) => {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(file, `${JSON.stringify(records, null, 2)}\n`);
+  },
+  spawn: (cmd, env, log) => {
+    mkdirSync(join(dir, 'servers'), { recursive: true });
+    const fd = openSync(log, 'a');
+    const child = spawn(cmd[0], cmd.slice(1), { detached: true, stdio: ['ignore', fd, fd], env });
+    child.unref();
+    return child.pid;
+  },
+  pgidOf: (pid) => Number(spawnSync('ps', ['-o', 'pgid=', '-p', String(pid)], { encoding: 'utf8' }).stdout.trim()),
+  kill: (pgid) => {
+    try {
+      process.kill(-pgid, 'SIGTERM');
+    } catch (error) {
+      if (error.code !== 'ESRCH') throw error;
+    }
+  },
+};
+
+let result;
+try {
+  if (action === 'start') {
+    if (port === null) usage('start needs --port');
+    result = startServer({ port, set: parseSet(values('set')), unset: values('unset'), command }, deps);
+  } else if (action === 'check') {
+    if (port === null) usage('check needs --port');
+    result = checkServer({ port }, deps);
+  } else if (action === 'stop') {
+    if (port === null && !argv.includes('--all')) usage('stop needs --port or --all');
+    result = stopServers({ port, all: argv.includes('--all') }, deps);
+  } else usage();
+} catch (error) {
+  usage(error.message);
+}
+(result.code === 0 ? console.log : console.error)(result.message);
+process.exit(result.code);

package/scripts/lib/dev-server-guard.mjs

@@ -0,0 +1,49 @@
+// Which processes listen on a port and where they run from, through lsof. A review does not switch branches under a
+// dev server that runs from the working tree, because the server would lose its files.
+// Implements "Review restores the base branch upon completion" of openspec/specs/review/spec.md.
+
+import { sep } from 'node:path';
+
+/** The pids listening on a TCP port; null when lsof cannot be run. `lsof(args)` returns { status, stdout }. */
+export function listeners(port, lsof) {
+  const r = lsof(['-nP', `-tiTCP:${port}`, '-sTCP:LISTEN']);
+  if (r.status === 127) return null;
+  // lsof exits 1 with nothing printed when no process matches.
+  return String(r.stdout ?? '').split('\n').map((s) => Number(s.trim())).filter((n) => Number.isInteger(n) && n > 0);
+}
+
+/** The current folder of a process; null when lsof cannot tell. */
+export function cwdOf(pid, lsof) {
+  const r = lsof(['-a', '-p', String(pid), '-d', 'cwd', '-Fn']);
+  if (r.status !== 0) return null;
+  const line = String(r.stdout ?? '').split('\n').find((l) => l.startsWith('n'));
+  return line ? line.slice(1) : null;
+}
+
+/** The port of an http address, with the default of its scheme. */
+export function portOf(url) {
+  const u = new URL(url);
+  return Number(u.port || (u.protocol === 'https:' ? 443 : 80));
+}
+
+/**
+ * May the working tree switch branches? Looks at the processes listening on the port of `url`.
+ * Returns { code, servers }: 0 none runs from the repository, 1 one does, 3 it cannot tell.
+ * deps: lsof(args) -> { status, stdout }, realpath(path) -> path.
+ */
+export function guard({ url, repoRoot }, { lsof, realpath }) {
+  const pids = listeners(portOf(url), lsof);
+  if (pids === null) return { code: 3, servers: [], reason: 'lsof is not available, so the folder of the server cannot be known' };
+  const root = realpath(repoRoot);
+  const servers = pids.map((pid) => {
+    const cwd = cwdOf(pid, lsof);
+    let real = null;
+    try {
+      real = cwd ? realpath(cwd) : null;
+    } catch { /* a folder that no longer exists is outside the repository */ }
+    return { pid, cwd, inside: real !== null && (real === root || real.startsWith(`${root}${sep}`)) };
+  });
+  if (servers.some((s) => s.inside)) return { code: 1, servers, reason: 'a server of the address under review runs from the working tree' };
+  if (servers.some((s) => s.cwd === null)) return { code: 3, servers, reason: 'the folder of a server on that port cannot be read' };
+  return { code: 0, servers, reason: null };
+}

package/scripts/lib/extra-server.mjs

@@ -0,0 +1,84 @@
+// Dev servers the agent starts for a line that needs the app with another configuration. Each one runs in a process
+// group of its own on a port that was free, is recorded, and is the only kind of server the agent may stop.
+// Implements "Servers started by the agent are its own" and "Environment files of a reviewed app are never read" of
+// openspec/specs/review/spec.md.
+
+import { join } from 'node:path';
+import { listeners } from './dev-server-guard.mjs';
+
+export const EXIT = { refused: 1, busy: 3, envFiles: 4, noLsof: 5 };
+
+// Example files hold no values the app loads.
+const EXAMPLES = new Set(['.env.example', '.env.sample', '.env.template']);
+const NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/** The environment files a dev server loads by itself, by name only: `.env` and `.env.*`, without the examples. */
+export function envFiles(names) {
+  return names.filter((n) => /^\.env(\..+)?$/.test(n) && !EXAMPLES.has(n)).sort();
+}
+
+/** The environment of the server: the current one with `set` applied and `unset` removed. */
+export function serverEnv(base, { set = {}, unset = [] }) {
+  const env = { ...base, ...set };
+  unset.forEach((n) => { delete env[n]; });
+  return env;
+}
+
+/** Parse `NAME=value` pairs of --set; throws on a bad name. */
+export function parseSet(pairs) {
+  return Object.fromEntries(pairs.map((p) => {
+    const i = p.indexOf('=');
+    const name = i === -1 ? p : p.slice(0, i);
+    if (i === -1 || !NAME_RE.test(name)) throw new Error(`--set needs NAME=value (got ${p})`);
+    return [name, p.slice(i + 1)];
+  }));
+}
+
+const fail = (code, message) => ({ code, message });
+
+/**
+ * Start a server. deps: lsof(args), listDir() -> names in the project folder, spawn(command, env, logFile) -> pgid,
+ * load() -> records, save(records), baseEnv, dir (the evidence folder, for the log).
+ */
+export function startServer({ port, set = {}, unset = [], command }, deps) {
+  if (!Number.isInteger(port) || port < 1024 || port > 65535) return fail(2, 'the port must be a number between 1024 and 65535');
+  if (!command || command.length === 0) return fail(2, 'give the command that starts the server after --');
+  const busy = listeners(port, deps.lsof);
+  if (busy === null) return fail(EXIT.noLsof, 'lsof is not available, so a free port cannot be told apart: leave this line for the person');
+  if (busy.length > 0) return fail(EXIT.busy, `port ${port} is busy (pid ${busy.join(', ')}): choose another; the server already there is not touched`);
+  const files = envFiles(deps.listDir());
+  if (unset.length > 0 && files.length > 0) {
+    return fail(EXIT.envFiles, `a variable cannot be removed while ${files.join(', ')} exist${files.length === 1 ? 's' : ''}: the dev server loads them by itself. Pre-check this line by reading the code, or leave it for the person`);
+  }
+  const records = deps.load();
+  const log = join(deps.dir ?? 'evidence', 'servers', `${port}.log`);
+  const pgid = deps.spawn(command, serverEnv(deps.baseEnv, { set, unset }), log);
+  records.push({ port, pgid, command: command.join(' '), set: Object.keys(set), unset });
+  deps.save(records);
+  return { code: 0, message: `started on port ${port} (process group ${pgid}); log in ${log}`, pgid };
+}
+
+/**
+ * Confirm that the process listening on the port belongs to the recorded server; when it does not (the server moved
+ * to another port, or failed), stop the recorded group and forget it.
+ */
+export function checkServer({ port }, deps) {
+  const records = deps.load();
+  const record = records.find((r) => r.port === port);
+  if (!record) return fail(EXIT.refused, `no server started by this script is recorded on port ${port}`);
+  const pids = listeners(port, deps.lsof) ?? [];
+  if (pids.some((pid) => deps.pgidOf(pid) === record.pgid)) return { code: 0, message: `port ${port} is served by the recorded server` };
+  deps.kill(record.pgid);
+  deps.save(records.filter((r) => r !== record));
+  return fail(EXIT.refused, `port ${port} is not served by the server that was started (it may have moved to another port): it was stopped`);
+}
+
+/** Stop recorded servers only: one port, or all of them. A port with no record stops nothing. */
+export function stopServers({ port = null, all = false }, deps) {
+  const records = deps.load();
+  const chosen = all ? records : records.filter((r) => r.port === port);
+  if (!all && chosen.length === 0) return fail(EXIT.refused, `no server started by this script is recorded on port ${port}: nothing was stopped`);
+  chosen.forEach((r) => deps.kill(r.pgid));
+  deps.save(records.filter((r) => !chosen.includes(r)));
+  return { code: 0, message: chosen.length === 0 ? 'no server to stop' : `stopped ${chosen.map((r) => `port ${r.port}`).join(', ')}` };
+}

package/scripts/lib/review-adapters.mjs

@@ -1,12 +1,14 @@
 // How `review` gets a log and captures for a platform and a target, and whether the agent may drive it.
 // Implements "The review picks its adapter from the platform and the target" of openspec/specs/review/spec.md.
 
+import { pickLanguage } from './language.mjs';
+
 const DEFAULT_TARGET = { flutter: 'android', vue: 'web' };
 
 const ADAPTERS = {
   'flutter/android': { kind: 'device', log: 'adb logcat', capture: 'adb screencap', driver: 'flutter_driver', needs: ['adb'] },
-  'flutter/web': { kind: 'browser', log: 'the browser runner', capture: 'the browser runner', driver: 'flutter_driver', needs: ['a browser'] },
-  'vue/web': { kind: 'browser', log: 'the browser runner', capture: 'the browser runner', driver: 'playwright', needs: ['playwright'] },
+  'flutter/web': { kind: 'browser', log: 'the browser runner', capture: 'capture(name, check) of the browser runner', driver: 'flutter_driver', needs: ['a browser'] },
+  'vue/web': { kind: 'browser', log: 'the browser runner', capture: 'capture(name, check) of the browser runner', driver: 'playwright', needs: ['playwright'] },
 };
 
 const NOT_AVAILABLE = {
@@ -35,3 +37,14 @@ export function adapterFor({ stack, target }) {
 export function needsAutopilot(adapter) {
   return adapter.supported && adapter.kind === 'browser';
 }
+
+const ADVICE = {
+  en: 'A browser has no manual review. Set review.autopilot to verify in relevo.yml (precheck is the cautious option) and commit it to the base branch. You still confirm every line, and lines about appearance are never marked automatically.',
+  es: 'Un navegador no tiene revisión manual. Pon review.autopilot en verify en relevo.yml (precheck es la opción prudente) y haz commit en la rama base. Tú sigues confirmando cada línea, y las líneas sobre apariencia nunca se marcan automáticamente.',
+};
+
+/** What to tell the person when a browser review cannot start because review.autopilot is off; null otherwise. */
+export function autopilotAdvice(adapter, { autopilot = 'off', language = 'en' } = {}) {
+  if (!needsAutopilot(adapter) || autopilot !== 'off') return null;
+  return ADVICE[pickLanguage(language)];
+}

package/scripts/lib/review-brief.mjs

@@ -8,8 +8,14 @@ export const MAX_SENTENCES = 2;
 export const MAX_LINE = 160;
 
 const LABELS = {
-  en: { asked: 'Asked', outcome: 'Outcome', first: 'Check first', count: (s, e) => `To check: ${s} scenario(s), ${e} edge case(s)` },
-  es: { asked: 'Se pidió', outcome: 'Resultado', first: 'Revisa primero', count: (s, e) => `Por revisar: ${s} escenario(s), ${e} caso(s) borde` },
+  en: {
+    asked: 'Asked', outcome: 'Outcome', first: 'Check first', count: (s, e) => `To check: ${s} scenario(s), ${e} edge case(s)`,
+    autopilot: 'The agent walks the lines below first; you confirm every line, and lines about appearance are never marked automatically.',
+  },
+  es: {
+    asked: 'Se pidió', outcome: 'Resultado', first: 'Revisa primero', count: (s, e) => `Por revisar: ${s} escenario(s), ${e} caso(s) borde`,
+    autopilot: 'El agente recorre primero las líneas de abajo; tú confirmas cada línea, y las líneas sobre apariencia nunca se marcan automáticamente.',
+  },
 };
 const RISK_RE = /(?:Riskiest area, check it first|Zona más riesgosa, revísala primero):\s*(.+)/;
 
@@ -26,9 +32,10 @@ export function firstSentences(text, max = MAX_SENTENCES) {
 /**
  * issue  { number, title, body }
  * built  the text of the `built` comment, when there is one (the risk line is taken from it)
+ * autopilot  review.autopilot; with precheck or verify a fixed note says the person still confirms every line
  * Returns the brief as a string of about five lines.
  */
-export function reviewBrief({ issue, built = '', language = 'en' }) {
+export function reviewBrief({ issue, built = '', language = 'en', autopilot = 'off' }) {
   const L = LABELS[language === 'es' ? 'es' : 'en'];
   const parsed = parseIssueBody(issue.body);
   const lines = [`#${issue.number} ${clean(issue.title)}`];
@@ -39,5 +46,6 @@ export function reviewBrief({ issue, built = '', language = 'en' }) {
   const risk = String(built).match(RISK_RE)?.[1];
   if (risk) lines.push(`${L.first}: ${clean(risk)}`);
   lines.push(L.count(parsed.scenarios, parsed.edgeCases));
-  return lines.map(cap).join('\n');
+  const note = ['precheck', 'verify'].includes(autopilot) ? `\n${L.autopilot}` : '';
+  return `${lines.map(cap).join('\n')}${note}`;
 }

package/scripts/lib/review-state.mjs

@@ -1,6 +1,8 @@
 // State of one on-device review, and the rule that decides whether a pull request may be opened.
 // Implements "Pull request only after verification" of openspec/specs/review/spec.md.
 
+import { createHash } from 'node:crypto';
+
 export const STATUSES = ['pending', 'ok', 'fail'];
 
 const same = (a, b) => a.class === b.class && a.excerpt === b.excerpt;
@@ -78,6 +80,8 @@ export function syncState(state, items) {
   state.audit = null;
   state.waivers = [];
   state.agreed = false;
+  // The code changed, so the review script must be read by QA again.
+  state.qaScript = null;
   return state;
 }
 
@@ -93,12 +97,34 @@ export function setItem(state, id, status, note = null) {
   return state;
 }
 
-const driving = (state) => {
+/**
+ * Throws unless the agent may drive the review: autopilot is not off and the person confirmed the data.
+ * With `open`, the review must also not be agreed yet (the browser runner asks for it).
+ */
+export function assertDriving(state, { open = false } = {}) {
   const mode = state.autopilot ?? 'off';
   if (mode === 'off') throw new Error('the agent does not drive the review: review.autopilot is "off"');
   if (!state.envConfirmed) throw new Error('the person has not confirmed in writing that the app points to non-production data: run "confirm-env" after they do');
+  if (open && state.agreed) throw new Error('the review is closed: the person already agreed to open the pull request');
   return mode;
-};
+}
+
+/** The sha256 of a review script, as `qa-pass` records it and the runner compares it. */
+export const scriptHash = (text) => createHash('sha256').update(String(text)).digest('hex');
+
+/** QA passed this exact script; any later change to it needs a new pass. */
+export function qaPass(state, path, text) {
+  state.qaScript = { path, sha256: scriptHash(text) };
+  return state;
+}
+
+/** Record a screenshot that was taken. Captures belong to the open review, so one after the agreement is refused. */
+export function recordCapture(state, path) {
+  if (state.agreed) throw new Error('the review is closed: captures are taken while the person tests, before the agreement');
+  state.captures ??= [];
+  if (!state.captures.includes(path)) state.captures.push(path);
+  return state;
+}
 
 /** The person confirmed that the app under review does not point to production data. */
 export function confirmEnv(state) {
@@ -108,7 +134,7 @@ export function confirmEnv(state) {
 
 /** The agent's own result for a line, apart from the person's confirmation. Modes precheck and verify only. */
 export function precheckItem(state, id, result, note = null) {
-  driving(state);
+  assertDriving(state);
   if (!['ok', 'fail'].includes(result)) throw new Error('a pre-check result is ok or fail');
   const item = state.items.find((i) => i.id === id);
   if (!item) throw new Error(`there is no checklist item ${id}`);
@@ -119,7 +145,7 @@ export function precheckItem(state, id, result, note = null) {
 
 /** The agent marks a line as verified automatically, saying how. Mode verify only; the line becomes ok but stays labelled. */
 export function autoItem(state, id, how) {
-  const mode = driving(state);
+  const mode = assertDriving(state);
   if (mode !== 'verify') throw new Error(`a line can be verified automatically only when review.autopilot is "verify" (it is "${mode}")`);
   const why = String(how ?? '').trim();
   if (!why) throw new Error('say how the line was verified: auto <number> <the assertion, finder or log that proved it>');

package/scripts/lib/web-preflight.mjs

@@ -0,0 +1,87 @@
+// What a browser review checks before it drives: the project's dependencies, Playwright and its browser, and the
+// address under review with the module scripts its page loads. Everything that touches the machine is injected.
+// Implements "A browser review checks its tools and the app before driving" of openspec/specs/review/spec.md.
+
+export const EXIT = { node_modules: 3, playwright: 4, browser: 5, url: 6 };
+
+const START_SCRIPTS = ['dev', 'serve', 'start'];
+
+/** The command that starts the app, from the scripts of package.json; null when there is none. */
+export function startCommand(pkgText) {
+  let scripts = {};
+  try {
+    scripts = JSON.parse(pkgText ?? '{}').scripts ?? {};
+  } catch { /* an unreadable package.json names no command */ }
+  const name = START_SCRIPTS.find((s) => typeof scripts[s] === 'string');
+  return name ? `npm run ${name}` : null;
+}
+
+/** The variable names of an example environment file (`NAME=value` lines); values are ignored. */
+export function envNames(text) {
+  return [...String(text ?? '').matchAll(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/gm)].map((m) => m[1]);
+}
+
+/** The same-origin module scripts that an HTML page loads, as absolute URLs. */
+export function moduleScripts(html, pageUrl) {
+  const origin = new URL(pageUrl).origin;
+  return [...String(html ?? '').matchAll(/<script\b[^>]*>/gi)]
+    .map((m) => m[0])
+    .filter((tag) => /\btype\s*=\s*["']?module\b/i.test(tag))
+    .map((tag) => tag.match(/\bsrc\s*=\s*["']([^"']+)["']/i)?.[1])
+    .filter(Boolean)
+    .map((src) => new URL(src, pageUrl))
+    .filter((u) => u.origin === origin)
+    .map((u) => u.href);
+}
+
+/** Does the page answer below 400 after redirects, and so do its module scripts? Returns { ok, detail }. */
+export async function checkUrl(url, { fetch, timeout = 5000 }) {
+  const get = async (address) => {
+    try {
+      const response = await fetch(address, { redirect: 'follow', signal: AbortSignal.timeout(timeout) });
+      return { status: response.status, text: response.status < 400 ? await response.text() : '' };
+    } catch (error) {
+      return { status: null, error: String(error?.cause?.code ?? error?.name ?? error?.message ?? error) };
+    }
+  };
+  const page = await get(url);
+  if (page.status === null) return { ok: false, detail: `${url} does not answer (${page.error})` };
+  if (page.status >= 400) return { ok: false, detail: `${url} answered ${page.status}` };
+  for (const script of moduleScripts(page.text, url)) {
+    const r = await get(script);
+    if (r.status === null) return { ok: false, detail: `${script} does not answer (${r.error})` };
+    if (r.status >= 400) return { ok: false, detail: `${script} answered ${r.status}` };
+  }
+  return { ok: true, detail: null };
+}
+
+/**
+ * Runs the checks in order and stops at the first failure. Returns { ok, check, detail, start, env, code }.
+ * deps: exists(path), readFile(path) (null when missing), loadPlaywright(), fetch, sleep(ms), now().
+ * Only `.env.example` is read for variable names; the real environment files never are.
+ * With `wait`, the address is retried every 500 ms until it answers or the time is over.
+ */
+export async function webPreflight({ cwd, url, timeout = 5000, wait = 0 }, deps) {
+  const { exists, readFile, loadPlaywright, fetch, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), now = Date.now } = deps;
+  const at = (name) => `${cwd}/${name}`;
+  const start = startCommand(readFile(at('package.json')));
+  const env = envNames(readFile(at('.env.example')));
+  const result = (check, detail) => ({ ok: check === null, check, detail, start, env, code: check === null ? 0 : EXIT[check] });
+
+  if (!exists(at('node_modules'))) return result('node_modules', 'the project has no node_modules: run npm install first');
+  const playwright = loadPlaywright();
+  if (!playwright) return result('playwright', 'Playwright does not resolve from the project');
+  let executable = null;
+  try {
+    executable = playwright.chromium.executablePath();
+  } catch { /* an unknown browser build has no path */ }
+  if (!executable || !exists(executable)) return result('browser', 'the Chromium of Playwright is not installed');
+
+  const deadline = now() + wait;
+  for (;;) {
+    const answer = await checkUrl(url, { fetch, timeout });
+    if (answer.ok) return result(null, null);
+    if (now() >= deadline) return result('url', answer.detail);
+    await sleep(500);
+  }
+}

package/scripts/lib/web-review.mjs

@@ -1,10 +1,25 @@
 // The rules of a driven web review that must not vary: which origins a page may reach, what a review script may
 // contain, how a secret is kept out of the output, and the log the audit reads.
 // Implements "The agent operates the app only within fixed limits", "A web review script is reviewed before it runs",
-// "Credentials of a driven review are names, not values" and "The audit understands a browser" of openspec/specs/review/spec.md.
+// "Credentials of a driven review are names, not values", "The audit understands a browser",
+// "A browser review takes captures through the runner" and "A failing page is reported as such" of openspec/specs/review/spec.md.
+
+import { createRequire } from 'node:module';
+import { isAbsolute, join, relative } from 'node:path';
+import { safeCaptureName } from './device.mjs';
 
 export const WEB_PACKAGE = 'web';
 
+/** Playwright as the project resolves it, else as the plugin does; null when neither has it. */
+export function loadPlaywright(cwd = process.cwd()) {
+  for (const base of [join(cwd, 'package.json'), import.meta.url]) {
+    try {
+      return createRequire(base)('playwright');
+    } catch { /* try the next place */ }
+  }
+  return null;
+}
+
 const LOCAL_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]']);
 // URLs that do not reach the network.
 const OFFLINE_PROTOCOLS = new Set(['data:', 'blob:', 'about:']);
@@ -41,6 +56,15 @@ const FORBIDDEN = [
   [/\bglobalThis\s*\.\s*process\b/, 'it reaches the process'],
   [/\bfetch\s*\(/, 'it makes a request outside the browser with fetch'],
   [/\brequire\.resolve\b|\bimport\.meta\b/, 'it inspects the module system'],
+  [/\bscreenshot\s*\(|\[\s*['"`]screenshot['"`]\s*\]/, 'it takes a screenshot itself; take it with capture(name, check), which saves it in the output folder'],
+  [/\.\s*pdf\s*\(/, 'it saves a PDF of the page'],
+  [/\btracing\b/, 'it records a trace'],
+  [/\brecord(?:Video|Har)\b/, 'it records a video or a HAR'],
+  [/\brouteFromHAR\b/, 'it reads a HAR file'],
+  [/\.\s*saveAs\s*\(/, 'it saves a download'],
+  [/\.\s*storageState\s*\(/, 'it saves the storage state'],
+  [/\.\s*setInputFiles\s*\(/, 'it uploads a local file to the page'],
+  [/(?:^|[{,\s])['"]?path['"]?\s*:/m, 'it passes a file path to a browser call (a "path:" option)'],
 ];
 
 /**
@@ -63,6 +87,63 @@ export function scanReviewScript(text) {
   return problems;
 }
 
+/**
+ * The capture(name, check, { fullPage }) helper given to a review script. `check` asserts the state the shot shows and
+ * runs first: when it fails no screenshot is taken and the capture is recorded as failed, without throwing into the
+ * script. A good capture is saved as <out>/<name>.png. Nothing is returned, so the image never reaches the script.
+ * `captures` collects { name, ok, path | error }, the path relative to `cwd` when the file is under it; a repeated
+ * name replaces the earlier entry, as its file does.
+ */
+export function makeCapture({ page, out, captures, cwd = process.cwd() }) {
+  const keep = (entry) => {
+    const i = captures.findIndex((c) => c.name === entry.name);
+    if (i === -1) captures.push(entry);
+    else captures[i] = entry;
+  };
+  return async (name, check, options = {}) => {
+    const safe = safeCaptureName(name);
+    if (typeof check !== 'function') throw new Error(`capture("${safe}", check): check is the assertion of the state the shot shows, and it is required`);
+    const unknown = Object.keys(options ?? {}).filter((k) => k !== 'fullPage');
+    if (unknown.length > 0) throw new Error(`capture("${safe}"): the only option is fullPage (got ${unknown.join(', ')})`);
+    try {
+      await check();
+    } catch (error) {
+      keep({ name: safe, ok: false, error: String(error?.message ?? error).split('\n')[0] });
+      return undefined;
+    }
+    const file = join(out, `${safe}.png`);
+    await page.screenshot({ path: file, fullPage: options?.fullPage === true });
+    const near = relative(cwd, file);
+    keep({ name: safe, ok: true, path: near && !near.startsWith('..') && !isAbsolute(near) ? near : file });
+    return undefined;
+  };
+}
+
+/**
+ * The page's own failure during a run, to name before a script error: the first uncaught error of the page or the
+ * first response of 400 or more from the origin under review. `events` are those of formatBrowserLog. Returns a
+ * string or null.
+ */
+export function probableCause(events, baseUrl) {
+  let origin;
+  try {
+    origin = new URL(baseUrl).origin;
+  } catch {
+    return null;
+  }
+  const hit = events.find((e) => {
+    if (e.type === 'pageerror') return true;
+    if (e.type !== 'response') return false;
+    try {
+      return new URL(String(e.text).split(' ').pop()).origin === origin;
+    } catch {
+      return false;
+    }
+  });
+  if (!hit) return null;
+  return hit.type === 'pageerror' ? `uncaught ${hit.text}` : `response ${hit.text}`;
+}
+
 /** Replace the value of every secret by [redacted:NAME]. `secrets` maps a variable name to its value. */
 export function redact(text, secrets = {}) {
   let out = String(text ?? '');

package/scripts/review-adapter.mjs

@@ -1,13 +1,14 @@
 #!/usr/bin/env node
 // Prints how `review` works for a platform of relevo.yml, as JSON. Usage:
 //   node scripts/review-adapter.mjs --platform web [--target web] [--config relevo.yml]
-// Output: { supported, stack, target, kind, log, capture, driver, needs, reason, platform, needs_autopilot }
+// Output: { supported, stack, target, kind, log, capture, driver, needs, reason, platform, needs_autopilot, advice }
+// `advice` is what to tell the person, in the language of relevo.yml, when a browser review cannot start with review.autopilot off.
 //   exit 0: supported   exit 1: no adapter for this platform and target (the reason is in the output)   exit 2: bad usage or invalid relevo.yml
 
 import { existsSync, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { loadConfig } from './lib/config.mjs';
-import { adapterFor, needsAutopilot, targetOf } from './lib/review-adapters.mjs';
+import { adapterFor, autopilotAdvice, needsAutopilot, targetOf } from './lib/review-adapters.mjs';
 
 const arg = (name) => {
   const i = process.argv.indexOf(`--${name}`);
@@ -28,5 +29,6 @@ if (!platform) fail(`there is no platform "${name}" in relevo.yml (platforms: ${
 
 const target = arg('target') ?? targetOf(platform);
 const adapter = adapterFor({ stack: platform.stack, target });
-console.log(JSON.stringify({ ...adapter, platform: name, needs_autopilot: needsAutopilot(adapter) }));
+const advice = autopilotAdvice(adapter, { autopilot: loaded.config.review?.autopilot, language: loaded.config.language });
+console.log(JSON.stringify({ ...adapter, platform: name, needs_autopilot: needsAutopilot(adapter), advice }));
 process.exit(adapter.supported ? 0 : 1);

package/scripts/review-brief.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 // Prints a short brief of an issue for the person who reviews it. Usage:
 //   node scripts/review-brief.mjs --issue 42 --title "Birthday list" --body-file issue.md [--built-file comment.md] [--language en|es]
+//        [--autopilot off|precheck|verify]
 // exit 0: printed   exit 2: bad arguments
 
 import { readFileSync } from 'node:fs';
@@ -14,7 +15,7 @@ const number = arg('issue');
 const title = arg('title');
 const bodyFile = arg('body-file');
 if (!number || title === undefined || !bodyFile) {
-  console.error('usage: review-brief.mjs --issue <n> --title "<title>" --body-file <file> [--built-file <file>] [--language en|es]');
+  console.error('usage: review-brief.mjs --issue <n> --title "<title>" --body-file <file> [--built-file <file>] [--language en|es] [--autopilot off|precheck|verify]');
   process.exit(2);
 }
 const read = (f) => {
@@ -26,4 +27,4 @@ const read = (f) => {
   }
 };
 const built = arg('built-file') ? read(arg('built-file')) : '';
-console.log(reviewBrief({ issue: { number, title, body: read(bodyFile) }, built, language: arg('language') ?? 'en' }));
+console.log(reviewBrief({ issue: { number, title, body: read(bodyFile) }, built, language: arg('language') ?? 'en', autopilot: arg('autopilot') ?? 'off' }));

package/scripts/review-state.mjs

@@ -3,7 +3,8 @@
 //   review-state.mjs init <change-dir> [--autopilot off|precheck|verify]   build the checklist from the change's scenarios
 //   review-state.mjs set <id> <ok|fail|pending> [note ...]
 //   review-state.mjs sync <change-dir>            after a fix: keep confirmed lines, retest failed ones, add new scenarios
-//   review-state.mjs capture <path>               record a screenshot that was taken
+//   review-state.mjs capture <path>               record a screenshot that was taken (refused after "agree")
+//   review-state.mjs qa-pass <script>             QA passed this browser review script; the runner runs only this exact content
 //   review-state.mjs audit [<log-file>|-] [--package <id>] [--pid <n>]
 //                                                 audit the device log (stdin by default), write the report;
 //                                                 with --package only that app's lines are audited
@@ -24,7 +25,7 @@ import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } fr
 import { dirname, join } from 'node:path';
 import { checklistFromChange } from './lib/checklist.mjs';
 import { auditLog, auditReport, filterByApp } from './lib/logaudit.mjs';
-import { applyWaivers, autoItem, autoSection, confirmEnv, decidePr, newState, precheckItem, setItem, syncState, waivedSection, waiveFinding } from './lib/review-state.mjs';
+import { applyWaivers, autoItem, autoSection, confirmEnv, decidePr, newState, precheckItem, qaPass, recordCapture, setItem, syncState, waivedSection, waiveFinding } from './lib/review-state.mjs';
 
 const argv = process.argv.slice(2);
 const si = argv.indexOf('--state');
@@ -72,12 +73,18 @@ try {
     }
     case 'capture': {
       if (!rest[0]) fail('usage: review-state.mjs capture <path>');
-      const state = load();
-      state.captures.push(rest[0]);
+      const state = recordCapture(load(), rest[0]);
       save(state);
       console.log(`recorded ${rest[0]}`);
       break;
     }
+    case 'qa-pass': {
+      if (!rest[0] || !existsSync(rest[0])) fail('usage: review-state.mjs qa-pass <script>');
+      const state = qaPass(load(), rest[0], readFileSync(rest[0], 'utf8'));
+      save(state);
+      console.log(`QA passed ${rest[0]} (sha256 ${state.qaScript.sha256.slice(0, 12)}); any change to it needs a new pass`);
+      break;
+    }
     case 'drain': {
       const file = join(dirname(statePath), 'device.log');
       const text = readFileSync(0, 'utf8');
@@ -164,7 +171,7 @@ try {
       break;
     }
     default:
-      fail('usage: review-state.mjs <init|set|sync|capture|drain|audit|waive|waived|confirm-env|precheck|auto|auto-list|agree|show|decide> [...]');
+      fail('usage: review-state.mjs <init|set|sync|capture|qa-pass|drain|audit|waive|waived|confirm-env|precheck|auto|auto-list|agree|show|decide> [...]');
   }
 } catch (err) {
   fail(err.message);

package/scripts/web-preflight.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+// Checks that a browser review can drive: the project's dependencies, Playwright and its Chromium, and the address
+// under review with the module scripts its page loads. Usage:
+//   node scripts/web-preflight.mjs --url http://localhost:5173 [--timeout 5000] [--wait 30000]
+// With --wait it is also the readiness probe of a server the agent started: the address is retried until it answers.
+// Prints { ok, check, detail, start, env } as JSON: `start` is the command that starts the app, `env` the variable
+// names of .env.example (the real environment files are never read).
+//   exit 0: ready   exit 3: no node_modules (run npm install)   exit 4: Playwright does not resolve
+//   exit 5: the Chromium of Playwright is missing   exit 6: the address or one of its modules does not answer below 400
+//   exit 2: bad arguments
+
+import { existsSync, readFileSync } from 'node:fs';
+import { loadPlaywright } from './lib/web-review.mjs';
+import { webPreflight } from './lib/web-preflight.mjs';
+
+const arg = (name) => {
+  const i = process.argv.indexOf(`--${name}`);
+  return i === -1 ? undefined : process.argv[i + 1];
+};
+const number = (name, fallback) => {
+  const v = arg(name);
+  if (v === undefined) return fallback;
+  const n = Number(v);
+  if (!Number.isInteger(n) || n < 0) {
+    console.error(`--${name} must be a number of milliseconds`);
+    process.exit(2);
+  }
+  return n;
+};
+
+const url = arg('url');
+try {
+  if (!url || !/^https?:$/.test(new URL(url).protocol)) throw new Error();
+} catch {
+  console.error('usage: web-preflight.mjs --url <http address> [--timeout 5000] [--wait 30000]');
+  process.exit(2);
+}
+const cwd = process.cwd();
+const result = await webPreflight({ cwd, url, timeout: number('timeout', 5000), wait: number('wait', 0) }, {
+  exists: existsSync,
+  readFile: (path) => (existsSync(path) ? readFileSync(path, 'utf8') : null),
+  loadPlaywright: () => loadPlaywright(cwd),
+  fetch: globalThis.fetch,
+});
+const { code, ...shown } = result;
+console.log(JSON.stringify(shown));
+process.exit(code);

package/scripts/web-review.mjs

@@ -1,23 +1,34 @@
 #!/usr/bin/env node
 // Runs a review script in a browser of its own and reports what it checked. Usage:
 //   node scripts/web-review.mjs --script evidence/review-web.mjs --url http://localhost:5173 \
-//        [--allow-origins https://staging.example.com] [--secret-env TEST_USER,TEST_PASS] [--out evidence] [--headed]
+//        [--allow-origins https://staging.example.com] [--secret-env TEST_USER,TEST_PASS] [--out evidence]
+//        [--state evidence/review-state.json] [--headed]
 // The script is the agent's, written from the scenarios and reviewed by QA. Its default export receives
-// { page, context, baseUrl, line, credentials }: line(n, how, fn) runs fn and records the checklist line n as
+// { page, context, baseUrl, line, credentials, capture }: line(n, how, fn) runs fn and records the checklist line n as
 // auto-ok or auto-fail; credentials(name) gives a test credential taken from the environment variable `name`,
-// which must be in --secret-env. The browser has a clean profile and can reach only localhost, the page under
-// review and the allowed origins; every secret value is redacted from what is written.
-// Writes <out>/web-log.txt (the log the audit reads, with --package web) and <out>/web-result.json.
-//   exit 0: the script ran (lines can still have failed)   exit 1: the script was refused, Playwright is missing,
-//   the browser could not start, or the script failed outside a line   exit 2: bad arguments
-
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { createRequire } from 'node:module';
+// which must be in --secret-env; capture(name, check, { fullPage }) runs the assertion `check` and, when it holds,
+// saves <out>/<name>.png and records it in the review state (nothing of the image is given back or printed).
+// Before anything runs, the review state must say the autopilot is on, the data was confirmed, the review is not
+// agreed yet, and QA passed this exact script (review-state.mjs qa-pass). The browser has a clean profile and can
+// reach only localhost, the page under review and the allowed origins; every secret value is redacted from what is
+// written, and the script's own console goes to <out>/script-console.txt, never to this output.
+// Writes <out>/web-log.txt (the log the audit reads, with --package web) and <out>/web-result.json. Each run against
+// another server uses an --out of its own; only the log of the normal run is audited.
+//   exit 0: the script ran (lines and captures can still have failed)   exit 1: the review state refused the run,
+//   the script was refused, Playwright is missing, the browser could not start, or the script failed outside a line
+//   exit 2: bad arguments
+
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { formatBrowserLog, isAllowedOrigin, redact, scanReviewScript } from './lib/web-review.mjs';
+import { format } from 'node:util';
+import { assertDriving, recordCapture, scriptHash } from './lib/review-state.mjs';
+import { formatBrowserLog, isAllowedOrigin, loadPlaywright, makeCapture, probableCause, redact, scanReviewScript } from './lib/web-review.mjs';
 
 const RUN_LIMIT_MS = 120000;
+// The runner's own output. The script's console is taken over while it runs, so these are kept apart.
+const say = console.log.bind(console);
+const tell = console.error.bind(console);
 
 const arg = (name) => {
   const i = process.argv.indexOf(`--${name}`);
@@ -25,13 +36,13 @@ const arg = (name) => {
 };
 const list = (name) => (arg(name) ?? '').split(',').map((s) => s.trim()).filter(Boolean);
 const stop = (code, message) => {
-  console.error(message);
+  tell(message);
   process.exit(code);
 };
 
 const scriptPath = arg('script');
 const baseUrl = arg('url');
-if (!scriptPath || !baseUrl || !existsSync(scriptPath)) stop(2, 'usage: web-review.mjs --script <file> --url <url> [--allow-origins a,b] [--secret-env A,B] [--out evidence] [--headed]');
+if (!scriptPath || !baseUrl || !existsSync(scriptPath)) stop(2, 'usage: web-review.mjs --script <file> --url <url> [--allow-origins a,b] [--secret-env A,B] [--out evidence] [--state evidence/review-state.json] [--headed]');
 let origin;
 try {
   origin = new URL(baseUrl);
@@ -41,26 +52,38 @@ try {
 const allowed = list('allow-origins');
 const secretNames = list('secret-env');
 const out = resolve(arg('out') ?? 'evidence');
+const statePath = resolve(arg('state') ?? 'evidence/review-state.json');
+
+const readState = () => JSON.parse(readFileSync(statePath, 'utf8'));
+if (!existsSync(statePath)) stop(1, `no review in progress (${statePath} not found): the runner drives only a review started with review-state.mjs init`);
+try {
+  assertDriving(readState(), { open: true });
+} catch (error) {
+  stop(1, `the review state refused the run before any browser started: ${error.message}`);
+}
 
-const problems = scanReviewScript(readFileSync(scriptPath, 'utf8'));
+const source = readFileSync(scriptPath, 'utf8');
+const problems = scanReviewScript(source);
 if (problems.length > 0) stop(1, `the review script was refused before any browser started:\n${problems.map((p) => `  - ${p}`).join('\n')}`);
+if (readState().qaScript?.sha256 !== scriptHash(source)) {
+  stop(1, `the review script is not the one QA passed: launch relevo:qa on it, and after QA PASSED run review-state.mjs qa-pass ${scriptPath}`);
+}
 
 const secrets = Object.fromEntries(secretNames.filter((n) => process.env[n]).map((n) => [n, process.env[n]]));
 const hide = (text) => redact(text, secrets);
 
-function loadPlaywright() {
-  for (const base of [join(process.cwd(), 'package.json'), import.meta.url]) {
-    try {
-      return createRequire(base)('playwright');
-    } catch { /* try the next place */ }
-  }
-  return null;
-}
 const playwright = loadPlaywright();
-if (!playwright) stop(1, 'Playwright cannot be resolved from this project: install it with "npm install -D playwright" and "npx playwright install chromium"');
+if (!playwright) stop(1, 'Playwright cannot be resolved from this project: with the person\'s permission, install it with "npm install --no-save playwright" and "npx playwright install chromium", then restore package-lock.json if npm changed it');
+
+if (arg('out') === undefined && existsSync(join(out, 'web-log.txt'))) {
+  tell(`warning: ${join(out, 'web-log.txt')} is replaced; a run against another server uses an --out of its own (evidence/run-<port>)`);
+}
+mkdirSync(out, { recursive: true });
 
 const events = [];
 const results = [];
+const captures = [];
+const scriptConsole = [];
 let scriptError = null;
 let pagesLoaded = 0;
 let browser;
@@ -80,6 +103,13 @@ const credentials = (name) => {
   return secrets[name];
 };
 
+// From here on the script's console goes to a file, also after a timeout: the runner prints with say and tell.
+function takeOverConsole() {
+  ['log', 'info', 'warn', 'error', 'debug', 'trace', 'dir', 'table'].forEach((level) => {
+    console[level] = (...args) => { scriptConsole.push(`${level} ${format(...args)}`); };
+  });
+}
+
 async function run() {
   try {
     browser = await playwright.chromium.launch({ headless: !process.argv.includes('--headed') });
@@ -105,11 +135,14 @@ async function run() {
     if (r.request().isNavigationRequest() && r.request().frame() === page.mainFrame() && r.status() < 400) pagesLoaded += 1;
   });
   page.on('response', (r) => { if (r.status() >= 400) events.push({ type: 'response', text: `${r.status()} ${r.request().method()} ${r.url()}` }); });
+  // The real path, so a capture is recorded relative to the working directory even through a symbolic link.
+  const capture = makeCapture({ page, out: realpathSync(out), captures });
 
   try {
+    takeOverConsole();
     const mod = await import(pathToFileURL(resolve(scriptPath)).href);
     if (typeof mod.default !== 'function') throw new Error('the script must export a default async function');
-    await mod.default({ page, context, baseUrl, line, credentials });
+    await mod.default({ page, context, baseUrl, line, credentials, capture });
   } catch (error) {
     scriptError = String(error?.message ?? error).split('\n')[0];
   }
@@ -124,11 +157,29 @@ clearTimeout(timer);
 clearTimeout(backstop);
 if (browser) await browser.close().catch(() => {});
 
-mkdirSync(out, { recursive: true });
 // A browser that never loaded a page proves nothing: the log is left empty so the audit is inconclusive.
 writeFileSync(join(out, 'web-log.txt'), pagesLoaded === 0 ? '' : hide(formatBrowserLog(events, { origin: origin.host })));
-writeFileSync(join(out, 'web-result.json'), hide(`${JSON.stringify({ url: baseUrl, lines: results, blocked: events.filter((e) => e.type === 'blocked').length, pagesLoaded, scriptError }, null, 2)}\n`));
-results.sort((a, b) => a.n - b.n).forEach((r) => console.log(hide(`line ${r.n}: ${r.status} - ${r.how}${r.error ? ` (${r.error})` : ''}`)));
-console.log(`${events.length} event(s) written to ${join(out, 'web-log.txt')}; audit it with: review-state.mjs audit --package web`);
-if (scriptError) stop(1, hide(`the script failed outside a line: ${scriptError}`));
+writeFileSync(join(out, 'web-result.json'), hide(`${JSON.stringify({ url: baseUrl, lines: results, captures, blocked: events.filter((e) => e.type === 'blocked').length, pagesLoaded, scriptError }, null, 2)}\n`));
+writeFileSync(join(out, 'script-console.txt'), hide(scriptConsole.map((l) => `${l}\n`).join('')));
+
+// The state is read again, so a line set while the browser ran is not lost.
+const saved = captures.filter((c) => c.ok);
+if (saved.length > 0) {
+  try {
+    const state = readState();
+    saved.forEach((c) => recordCapture(state, c.path));
+    writeFileSync(statePath, `${JSON.stringify(state, null, 2)}\n`);
+  } catch (error) {
+    tell(`the captures could not be recorded in ${statePath}: ${error.message}`);
+  }
+}
+
+results.sort((a, b) => a.n - b.n).forEach((r) => say(hide(`line ${r.n}: ${r.status} - ${r.how}${r.error ? ` (${r.error})` : ''}`)));
+captures.forEach((c) => say(hide(c.ok ? `captured ${c.path}` : `capture ${c.name}: failed (${c.error})`)));
+say(`${events.length} event(s) written to ${join(out, 'web-log.txt')}; audit it with: review-state.mjs audit --package web`);
+if (scriptError) {
+  const cause = probableCause(events, baseUrl);
+  if (cause) tell(hide(`the page itself failed: ${cause}`));
+  stop(1, hide(`the script failed outside a line: ${scriptError}`));
+}
 process.exit(0);

package/skills/review/SKILL.md

@@ -19,6 +19,7 @@ Scripts live in `${CLAUDE_PLUGIN_ROOT}/scripts/`. Run them with `node`. They hol
 - Never patch code during the review. A defect found here goes through `/relevo:fix`.
 - Never waive a finding, and never suggest or hint that one could be waived: a waiver is the person's decision, written by them as `waive <number> <reason>`.
 - Never commit the `evidence/` folder, and never force-push.
+- Never read the project's environment files (`.env`, `.env.local` and the like); only `.env.example` and the specification give variable names. Never stop, restart or signal a server you did not start with `extra-server.mjs`, above all the one the person started.
 
 The only `adb` commands you may run are: list devices, clear or read the log (`logcat`), and the screenshot taken by `capture.mjs`.
 
@@ -31,7 +32,8 @@ Stop with a clear message, changing nothing, if any of these fails:
 - `node ${CLAUDE_PLUGIN_ROOT}/scripts/validate-config.mjs relevo.yml` exits non-zero. Show its output.
 - `git check-ignore -q evidence/` fails: the evidence folder is not ignored by git. Tell the person to add `evidence/` to `.gitignore`.
 - The issue is not `built` (or `in-review`, to resume). Say which state it is in and what to do (`/relevo:go`, `/relevo:fix`).
-- `node ${CLAUDE_PLUGIN_ROOT}/scripts/review-adapter.mjs --platform <platform>` (the platform of the issue, from `platform-of.mjs`) exits 1: no review is possible for that platform and target; show the `reason` and stop, changing nothing. If it prints `needs_autopilot: true` and `review.autopilot` is `off`, stop and tell the person to set `review.autopilot` to `precheck` or `verify` in `relevo.yml`: a browser has no manual review.
+- `node ${CLAUDE_PLUGIN_ROOT}/scripts/review-adapter.mjs --platform <platform>` (the platform of the issue, from `platform-of.mjs`) exits 1: no review is possible for that platform and target; show the `reason` and stop, changing nothing. If it prints `needs_autopilot: true` and `review.autopilot` is `off`, stop and show its `advice` as it is: it recommends `verify`, names `precheck` as the cautious option, and is already in the language of `relevo.yml`.
+- Not a stop, a warning: if `git status --porcelain -- relevo.yml` prints anything, tell the person that `relevo.yml` has uncommitted changes, that this review uses them as they are, and that they belong on the base branch through a commit of their own. Never stage or commit `relevo.yml` in this review.
 - For an adapter whose kind is `device`: `node ${CLAUDE_PLUGIN_ROOT}/scripts/device.mjs` exits non-zero. Show its message: it says what to connect or authorise. Keep the serial it prints as `<serial>`. A `browser` adapter needs no device.
 
 Find the repository (`$GITHUB_REPOSITORY`, or `gh repo view --json nameWithOwner -q .nameWithOwner`), the issue's branch (`git branch -r --list "origin/feature/$ARGUMENTS-*"`) and its change folder: the one `openspec list --json` names that starts with `$ARGUMENTS-` (`openspec/changes/<name>`).
@@ -77,14 +79,28 @@ If `evidence/review-state.json` exists for this issue, resume: show the confirme
 
 Otherwise: `node ${CLAUDE_PLUGIN_ROOT}/scripts/review-state.mjs init openspec/changes/<change folder> --autopilot <review.autopilot>`, then clear the log so the audit only sees this session: `adb -s <serial> logcat -c`. Then ask the person to start the app, or restart it if it was already open, so that the log names its process and the audit can ignore other apps on the device.
 
+For a `browser` adapter there is no `adb` and no device log: after `init`, run the preflight against the address under review (the one the person gives; for Vue, `http://localhost:5173` when they give none):
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/web-preflight.mjs --url <address>
+```
+
+It prints JSON and exits by what is missing. Tell the person in their language:
+
+- `3`: there is no `node_modules`; ask them to run `npm install` first, and stop until they say it is done.
+- `4` or `5`: Playwright or its Chromium is missing. Ask for permission to install them; only on a yes run `npm install --no-save playwright` and `npx playwright install chromium`, then `git diff --quiet -- package-lock.json || git restore -- package-lock.json` (npm can rewrite the lock file even with `--no-save`), and run the preflight again.
+- `6`: the app does not answer, or one of its modules answers 400 or more (`detail` names it). Keep its `start` and `env` for step 3: the person starts the app there. If the app was already running and a module fails, tell them to restart their server; never do it yourself.
+- `0`: ready.
+
 ### 3. Brief the person, then stop
 
-Tell the person to start the app on the device themselves (for example `flutter run -d <serial>` in another terminal). Then show:
+Tell the person to start the app on the device themselves (for example `flutter run -d <serial>` in another terminal). For a `browser` adapter, tell them the exact command to start it in their own terminal: the `start` of the preflight, with the variable names of its `env` and the address under review. Then show:
 
-0. The **brief**, computed and not written by you: save the issue body and the `built` comment outside the working tree (`gh issue view $ARGUMENTS --json title,body,comments`), then `node ${CLAUDE_PLUGIN_ROOT}/scripts/review-brief.mjs --issue $ARGUMENTS --title "<title>" --body-file <body> --built-file <the built comment> --language <language>`. It prints about five lines: what was asked, the outcome, what to check first and how many lines there are to check. Show them as they are.
-1. A **shot list**: two or three screenshots worth taking, named like `01_initial`, `02_action`, `03_result`, taken from the scenarios. For a change with nothing visible, say there are no screenshots to take and the log will be audited anyway.
+0. The **brief**, computed and not written by you: save the issue body and the `built` comment outside the working tree (`gh issue view $ARGUMENTS --json title,body,comments`), then `node ${CLAUDE_PLUGIN_ROOT}/scripts/review-brief.mjs --issue $ARGUMENTS --title "<title>" --body-file <body> --built-file <the built comment> --language <language> --autopilot <review.autopilot>`. It prints about five lines: what was asked, the outcome, what to check first and how many lines there are to check, and, with `precheck` or `verify`, a fixed note that the person confirms every line. Show them as they are.
+1. A **shot list**: two or three screenshots worth taking, named like `01_initial`, `02_action`, `03_result`, taken from the scenarios. For a change with nothing visible, say there are no screenshots to take and the log will be audited anyway. In a browser review, each shot also names what proves the page shows that state and no other shot's (the text of the alert, the heading, the URL): it becomes the check of its capture.
 2. The **checklist**: `node ${CLAUDE_PLUGIN_ROOT}/scripts/checklist.mjs openspec/changes/<change folder>`, one numbered line per scenario, edge cases included. Point out any step the person must do outside the app, because you will not do it.
-3. What they can write: `capture <name>`, `ok <numbers>` (or `ok all`), `fail <number> <what went wrong>`, `retest <numbers>`, `done`. They may write in any language; understand the intent.
+3. With `review.autopilot` `precheck` or `verify`, the **plan of the walk**, so the person does not have to ask: one line per checklist line you walk yourself, `<n>. <method>: <how>`, where the method is `browser` (a Playwright assertion), `command` (an npm script of `package.json`, such as typecheck, lint, test or build), `read` (code, CI or docs) or `server <port>` (a run against a server you start with another configuration: say which variables are set or removed). Then the lines left to the person. Every configuration you will start is listed here, before the person confirms the data (Autopilot, step 1), so that confirmation covers them too.
+4. What they can write: `capture <name>`, `ok <numbers>` (or `ok all`), `fail <number> <what went wrong>`, `retest <numbers>`, `done`. They may write in any language; understand the intent.
 
 **Then end your turn.** Make no further tool calls until the person writes. Do not advance on your own and do not run the log audit early.
 
@@ -92,7 +108,7 @@ Tell the person to start the app on the device themselves (for example `flutter
 
 Handle each message as it comes:
 
-- `capture <name>`: `node ${CLAUDE_PLUGIN_ROOT}/scripts/capture.mjs <name>`, then record it with `review-state.mjs capture <path>`. Reply with the saved path only. If the script rejects the name, show its message and ask for another.
+- `capture <name>`: `node ${CLAUDE_PLUGIN_ROOT}/scripts/capture.mjs <name>`, then record it with `review-state.mjs capture <path>`. Reply with the saved path only. If the script rejects the name, show its message and ask for another. In a browser review there is no device to capture: add the shot, with its check, to the shot list and to the review script, which then needs QA again (Autopilot, step 4).
 - `ok <numbers>`: `review-state.mjs set <n> ok` for each. `fail <n> <note>`: `review-state.mjs set <n> fail <note>`. `retest <numbers>`: `review-state.mjs set <n> pending` for each, so the line must be confirmed again (useful after a fix).
 - A bug or something that looks wrong: do not edit anything. Record it as a `fail` and say the fix goes through `/relevo:fix $ARGUMENTS`; the review can resume afterwards.
 - `waive <number> <reason>`: the person's decision, available once the audit has findings; run `review-state.mjs waive <number> <reason>`. It refuses an empty reason and an inconclusive audit; show its message.
@@ -102,14 +118,21 @@ After **each** message of the person, keep the device log from being lost to its
 
 Never go to step 5 without an explicit `done` (or the equivalent in the person's language).
 
+Captures belong to this step: the shot list is taken while the person tests, before the agreement, and `review-state.mjs capture` refuses after `agree`. If the person asks for screenshots after agreeing, point to the files already in `evidence/` and do not drive again.
+
 ### Autopilot (only when `review.autopilot` is `precheck` or `verify`)
 
 When it is `off` skip this section: the person does everything. The person always confirms the lines and gives the agreement; nothing here replaces that.
 
 1. **Confirm the data.** Before any driven step, ask the person to confirm in writing that the app points to data that is not production. Record it only after they say so: `node ${CLAUDE_PLUGIN_ROOT}/scripts/review-state.mjs confirm-env`. Without it `precheck` and `auto` are refused.
-2. **Walk the lines.** `precheck`: after you walk a line, record your own result with `review-state.mjs precheck <n> ok|fail <note>`; the line stays pending until the person writes `ok`. `verify`: in addition, when the `THEN` of a line was proved by an assertion, a semantic finder or the log, record `review-state.mjs auto <n> <what proved it>`; the person confirms the other lines. A line about appearance, animation or fidelity to an image is never marked automatically.
+2. **Walk the lines.** `precheck`: after you walk a line, record your own result with `review-state.mjs precheck <n> ok|fail <note>`; the line stays pending until the person writes `ok`. `verify`: in addition, when the `THEN` of a line was proved by an assertion, a semantic finder or the log, or by the exit code of a project command, record `review-state.mjs auto <n> <what proved it>`; the person confirms the other lines. A line about appearance, animation or fidelity to an image is never marked automatically. A line checked only by reading code, CI or docs is recorded with `precheck` and what you found, never with `auto`.
+   - **Project commands.** Run the npm script of `package.json` that the line names (typecheck, lint, test, build), never a script that fixes or formats files. Run `git status --porcelain` before and after: if a tracked file changed, restore it with `git restore -- <file>` and tell the person which file changed. Record the command and its exit code as what proved the line.
 3. **Flutter on a device.** Drive through the Dart and Flutter MCP tools: `launch_app`, `connect_dart_tooling_daemon`, then `flutter_driver` (`get_health`, `waitFor`, `tap`, `enter_text`, `scroll`, `screenshot`), `get_runtime_errors`, `get_app_logs`, and `hot_reload` after a micro-fix. It needs `lib/main_driver.dart` with `enableFlutterDriverExtension()`. Rules: never pass `timeout` to `flutter_driver` (it breaks the MCP server); find widgets only by semantic finders (text, key, tooltip, type), never by coordinates; if a finder fails twice, stop driving and go back to manual for that line; the log of the MCP server is the source of the audit, and if it does not answer or is empty the audit is inconclusive.
-4. **A browser (Vue, or Flutter on the web).** Write a Playwright script from the scenarios to `evidence/review-web.mjs`: it exports a default async function that receives `{ page, baseUrl, line, credentials }`, uses `node:assert/strict`, and calls `line(<checklist number>, "<what is asserted>", async () => { ... })` once per line it can check. Every `THEN` it covers must have an assertion that would fail if the feature did not exist (text, URL, response, absence of errors), not a screenshot. A test login is read with `credentials("NAME")` where `NAME` is an environment variable the person names; you never read, print or store its value. Then launch `relevo:qa` on the script, read-only. Only if it answers `QA PASSED`, run `node ${CLAUDE_PLUGIN_ROOT}/scripts/web-review.mjs --script evidence/review-web.mjs --url <the address of the app> --allow-origins <review.allowed_origins> --secret-env <the names>`. The browser is its own, with a clean profile, and can reach only `localhost`, the address under review and `review.allowed_origins`; a refused script is not run in any other way. Its `auto-ok` lines are recorded as in step 2, its `auto-fail` lines as `precheck <n> fail` with the message, and `evidence/web-log.txt` is the log of step 5 (audit with `--package web`). The script checks are a tripwire, not a sandbox: if it touches anything sensitive, show it to the person before it runs.
+4. **A browser (Vue, or Flutter on the web).** Write a Playwright script from the scenarios to `evidence/review-web.mjs`: it exports a default async function that receives `{ page, baseUrl, line, credentials, capture }`, uses `node:assert/strict`, and calls `line(<checklist number>, "<what is asserted>", async () => { ... })` once per line it can check. Every `THEN` it covers must have an assertion that would fail if the feature did not exist (text, URL, response, absence of errors), not a screenshot. A test login is read with `credentials("NAME")` where `NAME` is an environment variable the person names; you never read, print or store its value.
+   - **Screenshots.** Turn the shot list into `capture("<name>", async () => { <the check of that shot> }, { fullPage: true })` calls. The check runs first, and when it fails no screenshot is taken and the capture is reported as failed. `capture` is the only way to take one: the runner refuses `page.screenshot`, any file path, and anything the script prints goes to `script-console.txt`, never to you. You never open the PNG files; their paths are all you see.
+   - **QA.** Then launch `relevo:qa` on the script, read-only, with the shot list: it rejects a `capture` name that is not on the shot list, and a check that would also hold for another shot (for example only `[role="alert"]` for two different errors). Only if it answers `QA PASSED`, record that exact script with `node ${CLAUDE_PLUGIN_ROOT}/scripts/review-state.mjs qa-pass evidence/review-web.mjs`. Any change to the script afterwards, even one port, needs `relevo:qa` and `qa-pass` again: the runner refuses a script whose content QA did not pass.
+   - **The normal run.** Run `node ${CLAUDE_PLUGIN_ROOT}/scripts/web-preflight.mjs --url <the address of the app>` again: it must exit 0. Then run `node ${CLAUDE_PLUGIN_ROOT}/scripts/web-review.mjs --script evidence/review-web.mjs --url <the address of the app> --allow-origins <review.allowed_origins> --secret-env <the names> --out evidence`. The runner itself refuses before any browser starts when the state has no confirmation of the data, the autopilot is `off` or the review is already agreed. The browser is its own, with a clean profile, and can reach only `localhost`, the address under review and `review.allowed_origins`; a refused script is not run in any other way. Its `auto-ok` lines are recorded as in step 2, its `auto-fail` lines as `precheck <n> fail` with the message, its captures are already recorded in the review state, and `evidence/web-log.txt` is the log of step 5 (audit with `--package web`). When it says `the page itself failed`, that is the cause to tell the person, not the selector timeout after it. The script checks are a tripwire, not a sandbox: if it touches anything sensitive, show it to the person before it runs.
+   - **Runs with another configuration** (the `server <port>` lines of the plan). Start each server yourself on a free localhost port with `node ${CLAUDE_PLUGIN_ROOT}/scripts/extra-server.mjs start --port <port> [--set NAME=value] [--unset NAME] -- npx vite --port <port> --strictPort`. It refuses a busy port and refuses `--unset` while an environment file exists (the dev server loads it by itself): then that line is pre-checked by reading the code or left for the person. Wait until it answers with `web-preflight.mjs --url http://localhost:<port> --wait 30000`, confirm it with `extra-server.mjs check --port <port>`, and run the same script with `--url http://localhost:<port> --out evidence/run-<port>`: each run has an output folder of its own, and these logs are never audited, because they show errors on purpose. Stop each one afterwards with `extra-server.mjs stop --port <port>`. The server the person started is never stopped or restarted.
 5. **Never** drive in the person's own browser, on an origin that is not allowed, with coordinates, with `adb shell input`, Appium or Maestro, or send a message or make a call in another app.
 
 ### 5. Audit the log
@@ -119,6 +142,12 @@ package=$(node ${CLAUDE_PLUGIN_ROOT}/scripts/app-id.mjs)
 adb -s <serial> logcat -d -v threadtime | node ${CLAUDE_PLUGIN_ROOT}/scripts/review-state.mjs audit --accumulated --package "$package"
 ```
 
+For a `browser` adapter there is no device: audit only the log of the normal run, never one of `evidence/run-<port>/`:
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/review-state.mjs audit evidence/web-log.txt --package web
+```
+
 `app-id.mjs` prints the application id of the project. The audit then looks only at the lines written by that app's processes, so other apps on the device are neither audited nor quoted. If `app-id.mjs` finds no id, run the audit without `--package`.
 
 It prints `REVIEW PASSED`, `REVIEW REJECTED` with the numbered findings, or `REVIEW INCONCLUSIVE`, and writes `evidence/review-report.md`. **Inconclusive** means the log was empty or had no line of the app: it proves nothing, it is not a pass and it cannot be waived. Ask the person to start the app again, repeat the steps, and audit once more.
@@ -150,11 +179,20 @@ Only when `decide` exited 0.
 ### 8. Evidence
 
 - `evidence.policy: local_only`: delete the `evidence/` folder now. Nothing is attached anywhere.
-- `evidence.policy: attach_to_pr`: GitHub has no API for attaching images, so you cannot upload them. List the files in `evidence/` and ask the person to drag them into the pull request description. Keep the folder until they say they did, then delete it.
+- `evidence.policy: attach_to_pr`: GitHub has no API for attaching images, so you cannot upload them. List only the images, in every run folder (`find evidence -name '*.png'`), and ask the person to drag them into the pull request description; the logs, results and scripts repeat what the body already says. Keep the folder until they say they did, then delete it. When there is no image, delete the folder without asking and say there was nothing to attach.
 
 ### 9. Return to base branch
 
-Restore the working tree to the base branch so the workspace remains clean on the base branch for other tasks or subsequent reviews, but only where that is possible: in the main checkout, and when no other worktree holds the base branch.
+Restore the working tree to the base branch so the workspace remains clean on the base branch for other tasks or subsequent reviews, but only where that is possible: in the main checkout, when no other worktree holds the base branch, and when no dev server of the address under review runs from the working tree (switching would remove its files under it and break it until it is restarted).
+
+For a `browser` adapter, first stop the servers you started, then ask the guard:
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/extra-server.mjs stop --all
+node ${CLAUDE_PLUGIN_ROOT}/scripts/dev-server-guard.mjs --url <the address of the app>
+```
+
+Switch only when the guard exits 0. On 1 a server runs from the working tree; on 3 the guard cannot tell. In both cases do not switch: say why, and that the person can stop their server and run `git switch <base>` themselves.
 
 ```bash
 [ "$(git rev-parse --git-dir)" = "$(git rev-parse --git-common-dir)" ] && ! git worktree list --porcelain | grep -qx "branch refs/heads/<base>" && git switch <base>

package/templates/workflows/relevo-digest.yml

@@ -9,7 +9,7 @@ name: relevo-digest
 # The version of @elalfner/relevo whose scripts this workflow runs. The plugin's templates carry the version they
 # were released with, and `/relevo:init` reports this file as different when it is older; change it by hand to update.
 env:
-  RELEVO_VERSION: '0.6.0'
+  RELEVO_VERSION: '0.7.0'
 
 on:
   schedule:

package/templates/workflows/relevo-go.yml

@@ -15,7 +15,7 @@ name: relevo-go
 # The version of @elalfner/relevo whose scripts this workflow runs. The plugin's templates carry the version they
 # were released with, and `/relevo:init` reports this file as different when it is older; change it by hand to update.
 env:
-  RELEVO_VERSION: '0.6.0'
+  RELEVO_VERSION: '0.7.0'
 
 on:
   issues:

package/templates/workflows/relevo-queue.yml

@@ -10,7 +10,7 @@ name: relevo-queue
 # The version of @elalfner/relevo whose scripts this workflow runs. The plugin's templates carry the version they
 # were released with, and `/relevo:init` reports this file as different when it is older; change it by hand to update.
 env:
-  RELEVO_VERSION: '0.6.0'
+  RELEVO_VERSION: '0.7.0'
 
 on:
   issues:

package/templates/workflows/relevo-review.yml

@@ -10,7 +10,7 @@ name: relevo-review
 # The version of @elalfner/relevo whose scripts this workflow runs. The plugin's templates carry the version they
 # were released with, and `/relevo:init` reports this file as different when it is older; change it by hand to update.
 env:
-  RELEVO_VERSION: '0.6.0'
+  RELEVO_VERSION: '0.7.0'
 
 on:
   pull_request_review:

package/templates/workflows/relevo-sla.yml

@@ -8,7 +8,7 @@ name: relevo-sla
 # The version of @elalfner/relevo whose scripts this workflow runs. The plugin's templates carry the version they
 # were released with, and `/relevo:init` reports this file as different when it is older; change it by hand to update.
 env:
-  RELEVO_VERSION: '0.6.0'
+  RELEVO_VERSION: '0.7.0'
 
 on:
   schedule: