@elalfner/relevo 0.5.0 → 0.7.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "relevo",
   "displayName": "Relevo",
-  "version": "0.5.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.5.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/go-worktree.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+// The worktree of an interactive `go` in Claude Code. Usage:
+//   node scripts/go-worktree.mjs create <issue> [--config relevo.yml]   prints {"worktree","base"} as JSON
+//   node scripts/go-worktree.mjs remove <issue>
+//   exit 0: done   1: git failed   2: bad usage   3: the worktree of the issue already exists   4: already in a linked worktree
+// The skill reads exit 3 as "stop" and exit 4 as "build where you are".
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { loadConfig } from './lib/config.mjs';
+import { createWorktree, EXIT, removeWorktree } from './lib/go-worktree.mjs';
+
+const args = process.argv.slice(2);
+const [command, issue] = args;
+const configAt = args.indexOf('--config');
+const fail = (message, code = EXIT.usage) => {
+  console.error(message);
+  process.exit(code);
+};
+
+const runner = {
+  capture: (cmd, cmdArgs, options) => execFileSync(cmd, cmdArgs, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], cwd: options.cwd }),
+};
+
+let result;
+if (command === 'create') {
+  const configPath = resolve(configAt === -1 ? 'relevo.yml' : args[configAt + 1]);
+  if (!existsSync(configPath)) fail(`relevo.yml not found at ${configPath}. Run /relevo:init to create it.`);
+  const loaded = loadConfig(readFileSync(configPath, 'utf8'));
+  if (!loaded.ok) fail(loaded.errors.map((e) => `error: ${e.message}`).join('\n'));
+  result = createWorktree({ issue, config: loaded.config, runner, exists: existsSync });
+  if (result.status === EXIT.ok) console.log(JSON.stringify({ worktree: result.worktree, base: result.base }));
+} else if (command === 'remove') {
+  result = removeWorktree({ issue, runner, exists: existsSync });
+} else {
+  fail('usage: go-worktree.mjs create|remove <issue>');
+}
+result.messages.forEach((m) => console.error(m));
+process.exit(result.status);

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/doctor.mjs

@@ -13,7 +13,7 @@ import { loadConfig } from './config.mjs';
 import { labelDefinitions } from './labels.mjs';
 import { credentialMode, cloudBuilds, CLOUD_VARIABLE } from './execution-mode.mjs';
 import { SKILL_DIRS, SIZE_BUDGET_BYTES, folderHash, lockDifferences, resolveRoleSkills, skillBudget } from './role-skills.mjs';
-import { ROLES, profileLocations, profileLookups, resolveProfile } from './stack-profile.mjs';
+import { ROLES, profileLocations, profileLookups, repositoryProfilePath, resolveProfile } from './stack-profile.mjs';
 
 export const REQUIRED_SKILLS = ['openspec-explore', 'grill-with-docs', 'grilling', 'domain-modeling'];
 export const SKILL_INSTALL = {
@@ -338,6 +338,14 @@ function gatherPlatforms(f, p, tryRun) {
         const tool = resolved.profile.targets[target] ?? '';
         return { target, tool, ok: tool === '' ? true : available(tool) };
       });
+      // The cloud and a fresh clone read the repository's layer from git, not from this working copy. `null` means
+      // git could not say (no git, or not a repository).
+      if (resolved.profile.layers.includes('repository')) {
+        const path = repositoryProfilePath(platform.stack);
+        if (!f.git) entry.repositoryLayerTracked = null;
+        else if (tryRun(() => { p.tool('git', ['ls-files', '--error-unmatch', path]); return true; }, false)) entry.repositoryLayerTracked = true;
+        else entry.repositoryLayerTracked = tryRun(() => { p.tool('git', ['rev-parse', '--is-inside-work-tree']); return true; }, false) ? false : null;
+      }
     }
     f.platformFacts.push(entry);
   });
@@ -474,6 +482,11 @@ function platformChecks(f) {
     }
     const layers = e.profile.layers.map((l) => (l === 'plugin' ? 'default of the plugin' : `.relevo/stacks/${e.stack}.md`)).join(' + ');
     r.push(pass(`platform.${e.name}.profile`, `platform ${e.name} (${e.stack}, ${e.path}): profile = ${layers}`));
+    if (e.repositoryLayerTracked === false) {
+      const path = `.relevo/stacks/${e.stack}.md`;
+      const effect = e.profile.layers.includes('plugin') ? `use only the plugin's profile for ${e.stack}, without your rules` : `have no profile for ${e.stack}`;
+      r.push(warn(`platform.${e.name}.profile.tracked`, `platform ${e.name}: ${path} is not tracked by git, so the cloud run and a fresh clone ${effect}`, `commit ${path} and push it with the rest of the repository's Relevo files`));
+    }
     (e.profile.ignored ?? []).forEach((x) => {
       r.push(warn(`platform.${e.name}.ignored.${x.key}`, `platform ${e.name}: the repository profile sets ${x.key} = "${x.value}", which is ignored (the plugin keeps "${x.kept}")`, `a command is replaced with platforms.${e.name}.checks in relevo.yml, not in the profile`));
     });

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/go-local.mjs

@@ -6,12 +6,13 @@
 //   stream(cmd, args, { cwd, env }) -> exit status (the output goes to the terminal); throws with code ENOENT when missing
 
 import { tmpdir } from 'node:os';
-import { basename, dirname, join } from 'node:path';
+import { basename, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { cloudBuilds } from './execution-mode.mjs';
 import { runFlags } from './run-flags.mjs';
+import { WORKTREES_FOLDER, worktreePath } from './worktree-path.mjs';
 
-export const WORKTREES_FOLDER = '.relevo-worktrees';
+export { WORKTREES_FOLDER };
 // The guard is part of the plugin, not of the project that is built, so it is found next to this file.
 const GUARD = fileURLToPath(new URL('../agent-guard.mjs', import.meta.url));
 // The same time limit as the cloud step of the Antigravity agent.
@@ -20,7 +21,7 @@ export const GUARD_TIMEOUT_MINUTES = 50;
 /** What a local run will do, without doing it: the worktree and the `claude` or `agy` command. Pure. */
 export function planLocalRun({ issue, repoRoot, config }) {
   const base = config.branches.base;
-  const worktree = join(dirname(repoRoot), WORKTREES_FOLDER, `${basename(repoRoot)}-${issue}`);
+  const worktree = worktreePath(repoRoot, issue);
   const isAntigravity = config.agent?.build === 'antigravity';
   const command = isAntigravity
     ? ['node', [

package/scripts/lib/go-worktree.mjs

@@ -0,0 +1,85 @@
+// The worktree of an interactive `go` in Claude Code. Implements "An interactive Claude Code run builds in its own
+// worktree" of the execution-modes specification: the skill makes the worktree here, enters it with EnterWorktree, and
+// asks for its removal here when the run ends cleanly.
+//
+// Every process goes through an injected runner so the logic is tested without git or a network:
+//   capture(cmd, args, { cwd }) -> stdout (throws when the command fails)
+
+import { worktreePath } from './worktree-path.mjs';
+
+/** Exit codes of `go-worktree.mjs`. `exists` and `linked` are answers, not failures: the skill reads them. */
+export const EXIT = { ok: 0, failed: 1, usage: 2, exists: 3, linked: 4 };
+
+const fail = (status, message) => ({ status, worktree: null, messages: [message] });
+// git prints progress ("Preparing worktree ...") before the reason, so the reason is the `fatal:` or `error:` line, or the last one.
+function firstLine(err) {
+  const lines = String(err.stderr ?? err.message).trim().split('\n').map((l) => l.trim()).filter(Boolean);
+  return lines.find((l) => /^(fatal|error):/.test(l)) ?? lines.at(-1) ?? 'git failed';
+}
+
+function context(issue, runner) {
+  if (!/^\d+$/.test(String(issue))) return { early: fail(EXIT.usage, 'give the issue number: go-worktree.mjs create|remove <issue>') };
+  try {
+    const repoRoot = runner.capture('git', ['rev-parse', '--show-toplevel'], {}).trim();
+    const [gitDir, commonDir] = runner
+      .capture('git', ['rev-parse', '--path-format=absolute', '--git-dir', '--git-common-dir'], { cwd: repoRoot })
+      .trim()
+      .split('\n');
+    return { repoRoot, linked: gitDir !== commonDir };
+  } catch {
+    return { early: fail(EXIT.usage, 'not inside a git repository (or git is older than 2.31)') };
+  }
+}
+
+/**
+ * Make the worktree of an issue from `origin/<base>`. `linked` when the session is already in a linked worktree (the
+ * build runs where it is), `exists` when the worktree of the issue is already there (the same issue twice).
+ */
+export function createWorktree({ issue, config, runner, exists = () => false }) {
+  const ctx = context(issue, runner);
+  if (ctx.early) return ctx.early;
+  if (ctx.linked) {
+    return fail(EXIT.linked, 'this session is already in a linked worktree: build here, no worktree is made');
+  }
+  const base = config.branches.base;
+  const worktree = worktreePath(ctx.repoRoot, issue);
+  if (exists(worktree)) {
+    return {
+      status: EXIT.exists,
+      worktree,
+      messages: [`${worktree} already exists: another run is building #${issue}, or a failed one left it. Finish it or remove it first (git worktree remove --force "${worktree}")`],
+    };
+  }
+  try {
+    // A folder deleted by hand leaves a registration that makes `worktree add` fail; prune only drops those.
+    runner.capture('git', ['worktree', 'prune'], { cwd: ctx.repoRoot });
+    runner.capture('git', ['fetch', 'origin', base], { cwd: ctx.repoRoot });
+    runner.capture('git', ['worktree', 'add', '--detach', worktree, `origin/${base}`], { cwd: ctx.repoRoot });
+  } catch (err) {
+    return fail(EXIT.failed, `could not prepare the worktree: ${firstLine(err)}`);
+  }
+  return { status: EXIT.ok, worktree, base, messages: [] };
+}
+
+/** Remove the worktree of an issue, after a clean end. Run it from the main working tree, not from inside. */
+export function removeWorktree({ issue, runner, exists = () => true }) {
+  const ctx = context(issue, runner);
+  if (ctx.early) return ctx.early;
+  if (ctx.linked) return fail(EXIT.linked, 'leave the worktree first (ExitWorktree with keep), then remove it from the main working tree');
+  const worktree = worktreePath(ctx.repoRoot, issue);
+  if (!exists(worktree)) {
+    // The folder may be gone while git still lists it: drop that registration so the issue can be built again.
+    try {
+      runner.capture('git', ['worktree', 'prune'], { cwd: ctx.repoRoot });
+    } catch (err) {
+      return { status: EXIT.failed, worktree, messages: [`could not prune the worktrees: ${firstLine(err)}; run git worktree prune`] };
+    }
+    return { status: EXIT.ok, worktree, messages: [`${worktree} is not there: nothing to remove`] };
+  }
+  try {
+    runner.capture('git', ['worktree', 'remove', '--force', worktree], { cwd: ctx.repoRoot });
+  } catch (err) {
+    return { status: EXIT.failed, worktree, messages: [`could not remove ${worktree}: ${firstLine(err)}; run git worktree remove --force "${worktree}"`] };
+  }
+  return { status: EXIT.ok, worktree, messages: [] };
+}

package/scripts/lib/init.mjs

@@ -208,11 +208,11 @@ export function planInit({ facts, answers, templates, current, admin }) {
   if (facts.configText !== null) items.push(item('config', facts.config ? 'ok' : 'differs', facts.config ? 'relevo.yml exists and is valid' : `relevo.yml exists but is invalid: ${facts.configErrors.join('; ')}`));
   else items.push(item('config', 'todo', 'Create relevo.yml from the answers', { content: renderConfig(templates.config, { base, release, ...answers }) }));
 
-  // optional stack profiles of the repository (created only when asked for, and never committed by init)
+  // optional stack profiles of the repository (created only when asked for; init never commits them, the person does)
   (answers.stackProfiles ?? []).forEach((stack) => {
     const path = `.relevo/stacks/${stack}.md`;
     if ((current.stackProfiles ?? {})[stack]) items.push(item(`stack-profile.${stack}`, 'ok', `${path} exists`));
-    else items.push(item(`stack-profile.${stack}`, 'todo', `Create ${path}, a commented profile that adds to the plugin's (not committed)`, { path, content: stackProfileTemplate(stack) }));
+    else items.push(item(`stack-profile.${stack}`, 'todo', `Create ${path}, a commented profile that adds to the plugin's (left for you to commit)`, { path, content: stackProfileTemplate(stack) }));
   });
 
   // labels

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>');