@elalfner/relevo 0.6.0 → 0.8.0

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/ship-github.mjs

@@ -0,0 +1,87 @@
+// What ship reads from GitHub besides the pull request: the commits since the approved head, the checks of that
+// head, and whether the base branch requires checks. The client is injected (`gh(args) -> stdout`) for the tests.
+// Implements "Checks of the approved head count for the archive commit" and "Repositories that require checks ship
+// with an App" of openspec/specs/ship/spec.md.
+
+const SPECS_DIR = 'openspec/';
+// The compare API lists at most 300 files; a longer list cannot be proven to stay inside the specifications.
+const COMPARE_FILE_LIMIT = 300;
+
+const ROLLUP_QUERY = `query($owner: String!, $name: String!, $oid: GitObjectID!) {
+  repository(owner: $owner, name: $name) {
+    object(oid: $oid) {
+      ... on Commit {
+        statusCheckRollup {
+          contexts(first: 100) {
+            nodes {
+              __typename
+              ... on CheckRun { name status conclusion }
+              ... on StatusContext { context state }
+            }
+          }
+        }
+      }
+    }
+  }
+}`;
+
+// The fields shipDecision reads.
+export const PR_FIELDS = 'number,state,isDraft,mergeable,title,author,reviews,statusCheckRollup,headRefName,headRefOid,baseRefName';
+
+/** The open pull request of `branch` (or its latest one), as `gh pr view --json` gives it, or null when none exists. */
+export function loadPr(gh, repo, branch) {
+  const found = JSON.parse(gh(['pr', 'list', '--repo', repo, '--head', branch, '--state', 'all', '--json', 'number,state', '--limit', '5']));
+  const open = found.find((p) => p.state === 'OPEN') ?? found[0];
+  return open ? JSON.parse(gh(['pr', 'view', String(open.number), '--repo', repo, '--json', PR_FIELDS])) : null;
+}
+
+const notFound = (err) => /404|Not Found/i.test(String(err?.stderr ?? err?.message ?? err));
+
+/** True when every file that changed from `baseline` to `head` is under `openspec/`, and something changed. */
+export function changedOnlySpecs(gh, repo, baseline, head) {
+  if (!baseline || !head || baseline === head) return false;
+  const data = JSON.parse(gh(['api', `repos/${repo}/compare/${baseline}...${head}`]));
+  const files = data.files ?? [];
+  if (files.length === 0 || files.length >= COMPARE_FILE_LIMIT) return false;
+  return files.every((f) => f.filename.startsWith(SPECS_DIR) && (!f.previous_filename || f.previous_filename.startsWith(SPECS_DIR)));
+}
+
+/** The status check rollup of one commit, in the shape `gh pr view --json statusCheckRollup` gives. */
+export function commitRollup(gh, repo, oid) {
+  const [owner, name] = repo.split('/');
+  const data = JSON.parse(gh(['api', 'graphql', '-f', `query=${ROLLUP_QUERY}`, '-f', `owner=${owner}`, '-f', `name=${name}`, '-f', `oid=${oid}`]));
+  return data.data?.repository?.object?.statusCheckRollup?.contexts?.nodes ?? [];
+}
+
+/** The input of shipDecision's `baselineChecks`, or undefined when there is no baseline to compare. */
+export function baselineChecks(gh, repo, baseline, head) {
+  if (!baseline || !head || baseline === head) return undefined;
+  const archiveOnly = changedOnlySpecs(gh, repo, baseline, head);
+  return { archiveOnly, rollup: archiveOnly ? commitRollup(gh, repo, baseline) : [] };
+}
+
+/**
+ * Whether merging into `branch` requires status checks, by a ruleset or by classic branch protection.
+ * Returns { required: boolean, contexts: [names] }. A branch without protection requires none.
+ */
+export function requiredChecks(gh, repo, branch) {
+  const contexts = new Set();
+  let required = false;
+  const rules = JSON.parse(gh(['api', `repos/${repo}/rules/branches/${encodeURIComponent(branch)}`]));
+  (Array.isArray(rules) ? rules : []).filter((r) => r.type === 'required_status_checks').forEach((r) => {
+    required = true;
+    (r.parameters?.required_status_checks ?? []).forEach((c) => contexts.add(c.context));
+  });
+  try {
+    const protection = JSON.parse(gh(['api', `repos/${repo}/branches/${encodeURIComponent(branch)}/protection`]));
+    const classic = protection.required_status_checks;
+    if (classic) {
+      required = true;
+      (classic.contexts ?? []).forEach((c) => contexts.add(c));
+      (classic.checks ?? []).forEach((c) => contexts.add(c.context));
+    }
+  } catch (err) {
+    if (!notFound(err)) throw err;
+  }
+  return { required, contexts: [...contexts] };
+}

package/scripts/lib/ship-unattended.mjs

@@ -0,0 +1,271 @@
+// The ship that the `relevo:ship` label starts on GitHub: the steps of /relevo:ship, run by a workflow with no model.
+// Implements "A label starts an unattended ship" and the requirements after it in openspec/specs/ship/spec.md.
+//
+// Everything that touches the outside is injected, so the whole sequence is testable without a network:
+//   sh(cmd, args, { cwd, input }) -> { status, stdout, stderr }   git, openspec and the plugin's scripts
+//   gh(args) -> stdout                                            reads, comments and labels (workflow token)
+//   pushGh(args) -> stdout                                        merge and close (App token, or the workflow token)
+//   sleep(ms), now()                                              waiting for the checks of the archive commit
+// Nothing from the feature branch is executed: git runs without hooks, and the scripts come from `pluginRoot`.
+
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { loadConfig } from './config.mjs';
+import { clearAll, resolveLabelNames } from './labels.mjs';
+import { renderMessage } from './messages.mjs';
+import { shipDecision } from './ship.mjs';
+import { baselineChecks, loadPr, requiredChecks } from './ship-github.mjs';
+
+const ARCHIVE_SUBJECT = 'chore(openspec): archive ';
+const CONFLICT_REASON = /has conflicts/;
+
+const NOTES = {
+  baseline: {
+    en: (sha) => `The archive commit changes only openspec/ and had no checks of its own, so the checks of the approved head ${sha} were used.`,
+    es: (sha) => `El commit del archivo solo cambia openspec/ y no tuvo checks propios, así que se usaron los checks del head aprobado ${sha}.`,
+  },
+  none: {
+    en: () => 'No check ran on this code: only the review vouched for it (review.ship_without_ci is true).',
+    es: () => 'No corrió ningún check sobre este código: solo la revisión lo respalda (review.ship_without_ci es true).',
+  },
+};
+
+/**
+ * What a label cannot do that a person in a session can. Returns null when the label may ship, or the message to post.
+ * - a decision that stops, stops;
+ * - an eligible person who did not approve must say so in writing, which a label cannot;
+ * - no checks at all need the person's word, unless review.ship_without_ci says the label is enough.
+ */
+export function labelRules({ decision, config }) {
+  if (!decision.allowed) return { kind: 'ship_stopped', data: { reasons: decision.reasons.join('; ') } };
+  if (decision.confirm.includes('not-approver')) {
+    return { kind: 'ship_not_approver', data: { approvers: decision.summary.approvedBy.map((l) => `@${l}`).join(', ') } };
+  }
+  if (decision.confirm.includes('no-ci') && !config.review.ship_without_ci) return { kind: 'ship_no_ci', data: {} };
+  return null;
+}
+
+class Stop {
+  constructor(kind, data = {}) {
+    this.kind = kind;
+    this.data = data;
+  }
+}
+const stopWith = (kind, data) => {
+  throw new Stop(kind, data);
+};
+const stopReasons = (...reasons) => stopWith('ship_stopped', { reasons: reasons.join('; ') });
+const firstLines = (text, n = 6) => String(text ?? '').trim().split('\n').slice(0, n).join(' / ');
+
+/** The change folder of the issue on the branch, and whether it is still to be archived. */
+export function findChange(workDir, issue) {
+  const changes = join(workDir, 'openspec', 'changes');
+  const prefix = `${issue}-`;
+  const active = existsSync(changes) ? readdirSync(changes).filter((n) => n.startsWith(prefix) && n !== 'archive') : [];
+  if (active.length === 1) return { name: active[0], state: 'active' };
+  if (active.length > 1) return { name: null, state: 'ambiguous', found: active };
+  const archiveDir = join(changes, 'archive');
+  const dated = new RegExp(`^\\d{4}-\\d{2}-\\d{2}-(${issue}-.+)$`);
+  const archived = existsSync(archiveDir) ? readdirSync(archiveDir).map((n) => n.match(dated)?.[1]).filter(Boolean) : [];
+  if (archived.length === 1) return { name: archived[0], state: 'archived' };
+  return { name: null, state: archived.length > 1 ? 'ambiguous' : 'missing', found: archived };
+}
+
+export async function runUnattendedShip(ctx) {
+  const { repo, issue, actor, actorType, hasApp, workDir, pluginRoot, sh, gh, pushGh } = ctx;
+  const sleep = ctx.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const now = ctx.now ?? (() => Date.now());
+  const waitLimitMs = ctx.waitLimitMs ?? 30 * 60 * 1000;
+  const settleMs = ctx.settleMs ?? 3 * 60 * 1000;
+  const pollMs = ctx.pollMs ?? 20 * 1000;
+  const headPollMs = ctx.headPollMs ?? 10 * 1000;
+  const n = String(issue);
+
+  const run = (cmd, args, opts = {}) => sh(cmd, args, { cwd: workDir, ...opts });
+  const git = (args, opts = {}) => {
+    const r = run('git', ['-c', 'core.hooksPath=/dev/null', ...args], opts);
+    if (r.status !== 0 && !opts.allowFail) stopReasons(`git ${args[0]} failed: ${firstLines(r.stderr || r.stdout)}`);
+    return r;
+  };
+  const script = (name, args, opts = {}) => run(process.execPath, [join(pluginRoot, 'scripts', name), ...args], opts);
+  const openspec = (args) => run('openspec', args, { env: { OPENSPEC_TELEMETRY: '0' } });
+
+  // The configuration of the default branch only names the base branch; the one that applies is the base branch's.
+  const readConfig = (text, where) => {
+    const loaded = loadConfig(text);
+    if (!loaded.ok) stopReasons(`relevo.yml on ${where} is not valid: ${loaded.errors.map((e) => e.message).join('; ')}`);
+    return loaded.config;
+  };
+
+  let config = loadConfig('limits:\n  run_max_cost: 1\n').config;
+  let names = resolveLabelNames({});
+  const removeShipLabel = () => {
+    try {
+      gh(['issue', 'edit', n, '--repo', repo, '--remove-label', names.ship]);
+    } catch {
+      // The label may already be gone; the comment still says what happened.
+    }
+  };
+
+  if (actorType !== 'User') {
+    removeShipLabel();
+    return { outcome: 'ignored', reason: 'the label was not applied by a person' };
+  }
+
+  try {
+    const fromDefault = run('git', ['show', 'HEAD:relevo.yml']);
+    if (fromDefault.status !== 0) stopReasons('relevo.yml not found on the default branch: run /relevo:init');
+    const base = readConfig(fromDefault.stdout, 'the default branch').branches.base;
+    git(['fetch', '--no-tags', 'origin', base]);
+    const fromBase = run('git', ['show', `origin/${base}:relevo.yml`]);
+    if (fromBase.status !== 0) stopReasons(`relevo.yml not found on ${base}`);
+    config = readConfig(fromBase.stdout, base);
+    names = resolveLabelNames(config.labels);
+    const language = config.language;
+
+    const issueData = JSON.parse(gh(['issue', 'view', n, '--repo', repo, '--json', 'state,labels']));
+    const labels = issueData.labels.map((l) => l.name);
+    if (issueData.state !== 'OPEN') stopReasons('the issue is closed');
+
+    // The issue's branch, looked up on the remote: never a branch named by the event.
+    const heads = git(['ls-remote', '--heads', 'origin']).stdout.split('\n')
+      .map((l) => l.split('\t')[1]?.replace('refs/heads/', ''))
+      .filter((b) => b && b.startsWith(`feature/${n}-`));
+    if (heads.length === 0) stopReasons(`there is no branch feature/${n}-* on the remote`);
+    if (heads.length > 1) stopReasons(`more than one branch matches feature/${n}-*: ${heads.join(', ')}`);
+    const branch = heads[0];
+    git(['fetch', '--no-tags', 'origin', branch]);
+    git(['switch', '--force-create', branch, `origin/${branch}`]);
+    const head = () => git(['rev-parse', 'HEAD']).stdout.trim();
+
+    const change = findChange(workDir, n);
+    if (change.state === 'missing') stopReasons(`no change folder openspec/changes/${n}-* on ${branch}`);
+    if (change.state === 'ambiguous') stopReasons(`more than one change folder for #${n}: ${change.found.join(', ')}`);
+
+    // The head the approval was given on: the current one, or the one before the archive when a previous run archived.
+    const subject = (ref) => git(['log', '-1', '--format=%s', ref]).stdout.trim();
+    let baseline = head();
+    if (change.state === 'archived') baseline = subject('HEAD').startsWith(ARCHIVE_SUBJECT) ? git(['rev-parse', 'HEAD^']).stdout.trim() : undefined;
+
+    const decide = (pr, withBaseline) => shipDecision({
+      config, pr, invoker: actor, labels, issue: n,
+      baseline: withBaseline,
+      baselineChecks: withBaseline ? baselineChecks(gh, repo, withBaseline, pr?.headRefOid) : undefined,
+    });
+    // GitHub takes a moment to see a push on the pull request; a head that never matches means someone else pushed.
+    const check = async (withBaseline) => {
+      const local = head();
+      let pr = loadPr(gh, repo, branch);
+      for (let tries = 0; pr && pr.headRefOid !== local && tries < 6; tries += 1) {
+        await sleep(headPollMs);
+        pr = loadPr(gh, repo, branch);
+      }
+      if (pr && pr.headRefOid !== local) stopReasons('the branch moved while shipping: apply the label again');
+      return { pr, decision: decide(pr, withBaseline) };
+    };
+
+    let { pr, decision } = await check(baseline);
+    const rule = labelRules({ decision, config });
+    if (rule) stopWith(rule.kind, rule.data);
+
+    const required = requiredChecks(gh, repo, base);
+    if (required.required && !hasApp) stopWith('ship_needs_app', { base });
+
+    const diff = git(['diff', `origin/${base}...HEAD`]).stdout;
+    const scan = script('scan-diff.mjs', [], { input: diff });
+    if (scan.status !== 0) stopReasons(`the diff has findings: ${firstLines(scan.stdout || scan.stderr)}`);
+
+    const archive = () => {
+      const steps = [
+        () => openspec(['validate', change.name]),
+        () => script('fix-tasks.mjs', ['--file', `openspec/changes/${change.name}/tasks.md`, '--stage', 'after']),
+        () => openspec(['archive', change.name, '-y']),
+        () => script('check-archive.mjs', []),
+        () => script('stage.mjs', ['openspec/changes', 'openspec/specs']),
+      ];
+      steps.forEach((step) => {
+        const r = step();
+        if (r.status !== 0) stopReasons(`the archive stopped: ${firstLines(r.stdout || r.stderr)}`);
+      });
+      git(['commit', '-m', `${ARCHIVE_SUBJECT}${change.name} (#${n})`]);
+      git(['push', 'origin', `HEAD:refs/heads/${branch}`]);
+    };
+
+    let pushed = false;
+    if (change.state === 'active') {
+      archive();
+      pushed = true;
+    }
+
+    // With the App, the push started the project's checks: wait for them, for a bounded time.
+    if (pushed && hasApp) {
+      const started = now();
+      for (;;) {
+        const current = loadPr(gh, repo, branch);
+        const rollup = current?.statusCheckRollup ?? [];
+        const running = rollup.some((c) => (c.__typename === 'StatusContext' ? !['SUCCESS', 'FAILURE', 'ERROR'].includes(c.state) : c.status !== 'COMPLETED'));
+        if (rollup.length > 0 && !running) break;
+        if (rollup.length === 0 && now() - started >= settleMs) break;
+        if (now() - started >= waitLimitMs) {
+          stopReasons(`the checks of the archive commit did not finish within ${Math.round(waitLimitMs / 60000)} minutes; apply the label again: the specification is already archived, so it resumes from the merge`);
+        }
+        await sleep(pollMs);
+      }
+    }
+
+    ({ pr, decision } = await check(baseline));
+    if (!decision.allowed && decision.reasons.length === 1 && CONFLICT_REASON.test(decision.reasons[0]) && subject('HEAD').startsWith(ARCHIVE_SUBJECT)) {
+      // The base branch changed the specifications the archive wrote: undo the archive, bring in the base, archive again.
+      git(['revert', '--no-edit', 'HEAD']);
+      const merge = git(['merge', '--no-edit', `origin/${base}`], { allowFail: true });
+      if (merge.status !== 0) {
+        const scope = script('conflict-scope.mjs', []);
+        git(['merge', '--abort'], { allowFail: true });
+        if (scope.status !== 0) stopReasons(`bringing in ${base} conflicts in code, which is for the author: ${firstLines(scope.stdout)}`);
+        stopReasons(`bringing in ${base} conflicts inside openspec/: run /relevo:ship ${n} to resolve it in a session`);
+      }
+      archive();
+      // The head now holds more than the archive, so the approval must be on it.
+      ({ pr, decision } = await check(undefined));
+    }
+    const again = labelRules({ decision, config });
+    if (again) stopWith(again.kind, again.data);
+
+    const merged = head();
+    try {
+      pushGh(['pr', 'merge', String(pr.number), '--repo', repo, '--squash', '--delete-branch', '--subject', pr.title, '--body', `Issue #${n}`, '--match-head-commit', merged]);
+    } catch (err) {
+      stopReasons(`GitHub refused the merge: ${firstLines(err.stderr || err.message)}`);
+    }
+
+    const after = JSON.parse(gh(['issue', 'view', n, '--repo', repo, '--json', 'state,labels']));
+    if (after.state === 'OPEN') pushGh(['issue', 'close', n, '--repo', repo, '--reason', 'completed']);
+    const { remove } = clearAll(after.labels.map((l) => l.name), config.labels);
+    if (remove.length > 0) pushGh(['issue', 'edit', n, '--repo', repo, ...remove.flatMap((l) => ['--remove-label', l])]);
+
+    let commit = merged.slice(0, 7);
+    try {
+      commit = (gh(['pr', 'view', String(pr.number), '--repo', repo, '--json', 'mergeCommit', '--jq', '.mergeCommit.oid']).trim() || merged).slice(0, 7);
+    } catch {
+      // The short head is close enough for the report.
+    }
+    const lang = language === 'es' ? 'es' : 'en';
+    const note = decision.summary.checksFrom === 'baseline' ? NOTES.baseline[lang](String(baseline).slice(0, 7)) : decision.summary.checks === 'none' ? NOTES.none[lang]() : '';
+    gh(['issue', 'comment', n, '--repo', repo, '--body', renderMessage('ship_done', { issue: n, pr: `#${pr.number}`, base, commit, actor, checks_note: note }, language)]);
+
+    // A close made with the workflow token starts no workflow: tell the queue, so dependent issues are unblocked now.
+    if (!hasApp) {
+      try {
+        gh(['workflow', 'run', 'relevo-queue.yml', '--repo', repo]);
+      } catch {
+        // No queue workflow: nothing waits on it.
+      }
+    }
+    return { outcome: 'merged', pr: pr.number, commit };
+  } catch (err) {
+    if (!(err instanceof Stop)) throw err;
+    removeShipLabel();
+    gh(['issue', 'comment', n, '--repo', repo, '--body', renderMessage(err.kind, { actor, issue: n, ...err.data }, config.language)]);
+    return { outcome: 'stopped', kind: err.kind, ...err.data };
+  }
+}

package/scripts/lib/ship.mjs

@@ -67,11 +67,13 @@ export function checkRollup(rollup = []) {
  * baseline optional: the head commit recorded when ship started; an approval given on it still counts
  * labels   optional: the names of the issue's labels; when given, the issue must be pr-open
  * issue    optional: the issue number, used in the messages about the state
+ * baselineChecks optional: { archiveOnly, rollup } of the baseline. When the head differs from it only under
+ *          `openspec/` (archiveOnly) and the head has no checks of its own, the baseline's checks are judged.
  * Returns { allowed, reasons, confirm, summary }.
  *   reasons  why it must stop (empty when allowed)
  *   confirm  what the person must still confirm in writing, always including "merge"
  */
-export function shipDecision({ config, pr, invoker, baseline, labels, issue }) {
+export function shipDecision({ config, pr, invoker, baseline, labels, issue, baselineChecks }) {
   const reasons = [];
   const warnings = [];
   const confirm = ['merge'];
@@ -95,7 +97,17 @@ export function shipDecision({ config, pr, invoker, baseline, labels, issue }) {
   if (pr.mergeable === 'CONFLICTING') reasons.push('the pull request has conflicts: the author must synchronise the branch with the base branch');
   else if (pr.mergeable !== 'MERGEABLE') reasons.push('GitHub has not finished checking whether the pull request can be merged: try again in a minute');
 
-  const checks = checkRollup(pr.statusCheckRollup);
+  // A push with the workflow token starts no workflows, so the archive commit may have no checks: the checks of the
+  // approved head still vouch for the code when only the specifications changed since.
+  let checks = checkRollup(pr.statusCheckRollup);
+  let checksFrom = 'head';
+  if (checks.state === 'none' && baselineChecks?.archiveOnly) {
+    const carried = checkRollup(baselineChecks.rollup);
+    if (carried.state !== 'none') {
+      checks = carried;
+      checksFrom = 'baseline';
+    }
+  }
   if (checks.state === 'failing') reasons.push(`checks are failing: ${checks.failing.join(', ')}`);
   else if (checks.state === 'pending') reasons.push(`checks are still running: ${checks.pending.join(', ')}`);
   else if (checks.state === 'none') confirm.push('no-ci');
@@ -156,6 +168,6 @@ export function shipDecision({ config, pr, invoker, baseline, labels, issue }) {
     allowed: reasons.length === 0,
     reasons,
     confirm,
-    summary: { pr: pr.number, title: pr.title, author, branch: pr.headRefName, base: pr.baseRefName, mode, approvedBy, checks: checks.state, ...(warnings.length > 0 ? { warnings } : {}) },
+    summary: { pr: pr.number, title: pr.title, author, branch: pr.headRefName, base: pr.baseRefName, head: pr.headRefOid ?? null, mode, approvedBy, checks: checks.state, checksFrom, ...(warnings.length > 0 ? { warnings } : {}) },
   };
 }

package/scripts/lib/toolchain-check.mjs

@@ -1,6 +1,12 @@
 // Which of the tools that a profile lists are not on the path. `probe(tool)` says whether one answers; it is injected
 // so that a test does not need the tools. An empty list checks nothing.
 
+/**
+ * What every Relevo job needs on the runner whatever the stack: a GitHub-hosted runner has them, a self-hosted one may not.
+ * They are checked with the tools of the profile, so a runner without one stops before the agent, like one without Flutter.
+ */
+export const RUNNER_TOOLS = ['git', 'gh', 'jq', 'node'];
+
 /** The tools that are missing, in the order of the profile and without repeats. */
 export function missingTools(tools, probe) {
   const seen = new Set();

package/scripts/lib/web-preflight.mjs

@@ -0,0 +1,133 @@
+// 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, deps_stale: 7 };
+
+// The frozen install of each lock file, first match wins. None runs package scripts where the tool can skip them.
+const LOCKS = [
+  { file: 'package-lock.json', install: 'npm ci --ignore-scripts' },
+  { file: 'pnpm-lock.yaml', install: 'pnpm install --frozen-lockfile --ignore-scripts' },
+  { file: 'yarn.lock', install: 'yarn install --immutable' },
+];
+
+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);
+}
+
+/** The lock file of the folder and its frozen install command; null when the folder has none. */
+export function lockOf(cwd, exists) {
+  return LOCKS.find((l) => exists(`${cwd}/${l.file}`)) ?? null;
+}
+
+const parse = (text) => {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Do the installed dependencies differ from package-lock.json? Compares each package of the lock file with the one
+ * npm recorded in node_modules/.package-lock.json. An optional package that is not installed (a binary for another
+ * platform) is not a difference. Returns true, false, or null when it cannot tell (never treated as stale).
+ */
+export function npmStale(lockText, hiddenText) {
+  const lock = parse(lockText)?.packages;
+  if (!lock || typeof lock !== 'object') return null;
+  if (hiddenText === null) return true;
+  const hidden = parse(hiddenText)?.packages;
+  if (!hidden || typeof hidden !== 'object') return null;
+  return Object.entries(lock).some(([key, wanted]) => {
+    if (key === '') return false;
+    const installed = hidden[key];
+    if (!installed) return !(wanted?.optional || wanted?.devOptional);
+    return wanted?.version !== undefined && installed.version !== wanted.version;
+  });
+}
+
+/** 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, install, code }:
+ * `install` is the frozen install command of the folder's lock file, or null without one.
+ * 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 lock = lockOf(cwd, exists);
+  const install = lock?.install ?? null;
+  const result = (check, detail) => ({ ok: check === null, check, detail, start, env, install, code: check === null ? 0 : EXIT[check] });
+
+  if (!exists(at('node_modules'))) return result('node_modules', lock ? 'the project has no node_modules' : 'the project has no node_modules and no lock file to install from');
+  // Only npm records what it installed in a form comparable with its lock file; pnpm and yarn are checked for presence.
+  if (lock?.file === 'package-lock.json' && npmStale(readFile(at('package-lock.json')), readFile(at('node_modules/.package-lock.json'))) === true) {
+    return result('deps_stale', 'the installed dependencies do not match package-lock.json');
+  }
+  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);
+  }
+}