@elalfner/relevo 0.7.0 → 0.8.0

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

@@ -2,7 +2,14 @@
 // 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 };
+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'];
 
@@ -34,6 +41,38 @@ export function moduleScripts(html, pageUrl) {
     .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) => {
@@ -56,7 +95,8 @@ export async function checkUrl(url, { fetch, timeout = 5000 }) {
 }
 
 /**
- * Runs the checks in order and stops at the first failure. Returns { ok, check, detail, start, env, code }.
+ * 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.
@@ -66,9 +106,15 @@ export async function webPreflight({ cwd, url, timeout = 5000, wait = 0 }, 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] });
+  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', 'the project has no node_modules: run npm install first');
+  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;

package/scripts/review-event.mjs

@@ -52,7 +52,16 @@ if (eventName === 'pull_request_review') {
 
 const pr = { number: prData.number, url: prData.html_url, author: prData.user.login };
 const labels = JSON.parse(realGh(['api', `repos/${repo}/issues/${number}`])).labels.map((l) => (typeof l === 'string' ? l : l.name));
-const decision = planReviewEvent({ config, event, pr, issue: { number, labels } });
+// The approval names the ship label only where the ship workflow runs: it runs from the default branch.
+const shipWorkflow = event.kind === 'review' && event.state === 'approved' && (() => {
+  try {
+    realGh(['api', `repos/${repo}/contents/.github/workflows/relevo-ship.yml`, '--silent']);
+    return true;
+  } catch {
+    return false;
+  }
+})();
+const decision = planReviewEvent({ config, event, pr, issue: { number, labels }, shipWorkflow });
 if (!decision) {
   console.log(JSON.stringify({ action: 'none' }));
   process.exit(0);

package/scripts/ship-check.mjs

@@ -11,6 +11,7 @@ import { resolve } from 'node:path';
 import { loadConfig } from './lib/config.mjs';
 import { realGh } from './lib/github.mjs';
 import { shipDecision } from './lib/ship.mjs';
+import { baselineChecks, loadPr } from './lib/ship-github.mjs';
 
 const arg = (name) => {
   const i = process.argv.indexOf(`--${name}`);
@@ -26,9 +27,9 @@ if (!existsSync(configPath)) fail(`relevo.yml not found at ${configPath}. Run /r
 const loaded = loadConfig(readFileSync(configPath, 'utf8'));
 if (!loaded.ok) fail(loaded.errors.map((e) => `error: ${e.message}`).join('\n'));
 
-const FIELDS = 'number,state,isDraft,mergeable,title,author,reviews,statusCheckRollup,headRefName,headRefOid,baseRefName';
 let pr;
 let invoker = arg('invoker');
+let carried;
 
 if (arg('input')) {
   pr = JSON.parse(readFileSync(arg('input'), 'utf8'));
@@ -36,10 +37,10 @@ if (arg('input')) {
   const repo = arg('repo') ?? process.env.GITHUB_REPOSITORY;
   const branch = arg('branch');
   if (!repo || !branch) fail('usage: ship-check.mjs --repo owner/name --branch <branch> [--invoker login] [--config relevo.yml]');
-  const found = JSON.parse(realGh(['pr', 'list', '--repo', repo, '--head', branch, '--state', 'all', '--json', 'number,state', '--limit', '5']));
-  const open = found.find((p) => p.state === 'OPEN') ?? found[0];
-  pr = open ? JSON.parse(realGh(['pr', 'view', String(open.number), '--repo', repo, '--json', FIELDS])) : null;
+  pr = loadPr(realGh, repo, branch);
   invoker ??= realGh(['api', 'user', '--jq', '.login']).trim();
+  // The archive commit may have no checks of its own; the approved head's count when only openspec/ changed since.
+  if (pr && arg('baseline')) carried = baselineChecks(realGh, repo, arg('baseline'), pr.headRefOid);
 }
 
 const decision = shipDecision({
@@ -49,6 +50,7 @@ const decision = shipDecision({
   baseline: arg('baseline'),
   labels: arg('labels') === undefined ? undefined : arg('labels').split(',').map((l) => l.trim()).filter(Boolean),
   issue: arg('issue'),
+  baselineChecks: carried,
 });
 console.log(JSON.stringify(decision, null, 2));
 process.exit(decision.allowed ? 0 : 1);

package/scripts/ship-unattended.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+// Ships an issue on GitHub, without a model, when a person applied the `relevo:ship` label. Usage (in the workflow):
+//   node scripts/ship-unattended.mjs --repo owner/name --issue 31 --actor login --actor-type User --work <checkout>
+// Environment: GH_TOKEN (the workflow token), GH_PUSH_TOKEN (the App token, or the workflow token), HAS_APP (true|false).
+// Prints the outcome as JSON.   exit 0: merged, stopped with a comment, or ignored   exit 2: bad arguments
+// Any other failure exits non-zero, and the workflow's last step reports it on the issue.
+
+import { execFileSync, spawnSync } from 'node:child_process';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { runUnattendedShip } from './lib/ship-unattended.mjs';
+
+const arg = (name) => {
+  const i = process.argv.indexOf(`--${name}`);
+  return i === -1 ? undefined : process.argv[i + 1];
+};
+const [repo, issue, actor, actorType, work] = ['repo', 'issue', 'actor', 'actor-type', 'work'].map(arg);
+if (!repo || !/^\d+$/.test(issue ?? '') || !actor || !actorType || !work) {
+  console.error('usage: ship-unattended.mjs --repo owner/name --issue <n> --actor <login> --actor-type <User|Bot> --work <checkout>');
+  process.exit(2);
+}
+
+const ghWith = (token) => (args) => execFileSync('gh', args, {
+  encoding: 'utf8',
+  maxBuffer: 64 * 1024 * 1024,
+  env: { ...process.env, GH_TOKEN: token ?? process.env.GH_TOKEN },
+});
+const sh = (cmd, args, { cwd, input, env } = {}) => {
+  const r = spawnSync(cmd, args, { cwd, input, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, env: { ...process.env, ...env } });
+  return { status: r.status ?? 1, stdout: r.stdout ?? '', stderr: r.stderr ?? String(r.error ?? '') };
+};
+
+const outcome = await runUnattendedShip({
+  repo,
+  issue,
+  actor,
+  actorType,
+  hasApp: process.env.HAS_APP === 'true',
+  workDir: resolve(work),
+  pluginRoot: resolve(dirname(fileURLToPath(import.meta.url)), '..'),
+  sh,
+  gh: ghWith(process.env.GH_TOKEN),
+  pushGh: ghWith(process.env.GH_PUSH_TOKEN || process.env.GH_TOKEN),
+});
+console.log(JSON.stringify(outcome, null, 2));

package/scripts/toolchain-check.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // Checks that the tools which the profile of a platform lists are on the path of this machine. Usage:
 //   node scripts/toolchain-check.mjs --platform <name> [--config relevo.yml] [--plugin-root <dir>]
-// It prints { platform, stack, tools, missing } as JSON. A tool is there when `<tool> --version` starts. The cloud build
+// It prints { platform, stack, tools, missing } as JSON; `missing` also covers git, gh, jq and node, which every job needs. A tool is there when `<tool> --version` starts. The cloud build
 // runs it before the agent, so that a runner without the SDK stops in seconds and not after a full run.
 //   exit 0: every tool is there (or the profile lists none)   exit 1: a tool is missing, or the profile cannot be resolved
 //   exit 2: bad usage or an invalid relevo.yml
@@ -12,7 +12,7 @@ import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { loadConfig } from './lib/config.mjs';
 import { resolveProfile } from './lib/stack-profile.mjs';
-import { missingTools } from './lib/toolchain-check.mjs';
+import { missingTools, RUNNER_TOOLS } from './lib/toolchain-check.mjs';
 
 const arg = (name) => {
   const i = process.argv.indexOf(`--${name}`);
@@ -44,6 +44,6 @@ const resolved = resolveProfile({ platform, pluginRoot, read });
 if (!resolved.ok) fail(resolved.errors.join('\n'), 1);
 
 const probe = (tool) => spawnSync(tool, ['--version'], { stdio: 'ignore' }).error === undefined;
-const missing = missingTools(resolved.profile.tools, probe);
+const missing = missingTools([...RUNNER_TOOLS, ...(resolved.profile.tools ?? [])], probe);
 console.log(JSON.stringify({ platform: name, stack: resolved.profile.stack, tools: resolved.profile.tools, missing }));
 process.exit(missing.length > 0 ? 1 : 0);

package/scripts/web-hook.mjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+// Adds the SessionStart hook that installs OpenSpec in web sessions to .claude/settings.json. Usage:
+//   node scripts/web-hook.mjs [--settings .claude/settings.json]
+// Run by /relevo:init only after the person agreed to the hook. Every other key and hook of the file is kept, and a
+// file that is not a JSON object is left as it is.
+// exit 0: written, or already there   exit 2: the file could not be merged
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { mergeWebHook } from './lib/init.mjs';
+
+const i = process.argv.indexOf('--settings');
+const path = i === -1 ? '.claude/settings.json' : process.argv[i + 1];
+
+try {
+  const before = existsSync(path) ? readFileSync(path, 'utf8') : null;
+  const after = mergeWebHook(before);
+  if (after === before) {
+    console.log(`${path} already installs OpenSpec at the start of a web session; nothing changed`);
+  } else {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, after);
+    console.log(`${path} now installs OpenSpec at the start of a web session; the file is left for you to commit`);
+  }
+} catch (err) {
+  console.error(`could not add the hook to ${path}: ${err.message}`);
+  process.exit(2);
+}

package/scripts/web-preflight.mjs

@@ -3,11 +3,12 @@
 // 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
+// Prints { ok, check, detail, start, env, install } as JSON: `start` is the command that starts the app, `env` the
+// variable names of .env.example (the real environment files are never read), `install` the frozen install command of
+// the lock file (null without one).
+//   exit 0: ready   exit 3: no node_modules   exit 7: node_modules does not match package-lock.json
+//   exit 4: Playwright does not resolve from the project   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';

package/scripts/web-review.mjs

@@ -73,7 +73,7 @@ const secrets = Object.fromEntries(secretNames.filter((n) => process.env[n]).map
 const hide = (text) => redact(text, secrets);
 
 const playwright = loadPlaywright();
-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 (!playwright) stop(1, 'Playwright cannot be resolved from this project: it belongs in its development dependencies; run /relevo:init, or "npm install -D playwright" and "npx playwright install chromium" in the folder of the platform, and commit the change on the base branch');
 
 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>)`);

package/skills/doctor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: doctor
-description: Checks that this machine, the repository and GitHub are ready for Relevo and reports every check as pass, fail or warning, with the fix next to each failure. It covers the required tools (OpenSpec, git, the GitHub CLI, the toolchain and the targets of each platform's stack profile), the skills that /relevo:think invokes, the extra skills of each role, relevo.yml, labels and branches, branch protection and approvals, the automation secret and workflows, and a CI check. Read-only: it never changes anything. Use when asked to check, diagnose or verify the Relevo setup.
+description: Checks that this machine, the repository and GitHub are ready for Relevo and reports every check as pass, fail or warning, with the fix next to each failure. It covers the required tools (OpenSpec, git, the GitHub CLI, the toolchain and the targets of each platform's stack profile), the skills that /relevo:think invokes, the extra skills of each role, relevo.yml, labels and branches, branch protection and approvals, the automation secret and workflows, what the ship workflow needs, in a web session whether the repository installs OpenSpec at its start, and a CI check. Read-only: it never changes anything. Use when asked to check, diagnose or verify the Relevo setup.
 argument-hint: ""
 ---
 
@@ -21,7 +21,8 @@ Scripts live in `${CLAUDE_PLUGIN_ROOT}/scripts/`. Run them with `node`. They hol
 1. Run `node ${CLAUDE_PLUGIN_ROOT}/scripts/doctor.mjs` from the repository root. It finds the repository itself; pass `--repo owner/name` only when it cannot.
 2. Show its output as it is: each check is `pass`, `FAIL` or `warn`, and each failure and warning has its fix on the next line.
 3. If there are failures, say which command fixes most of them: `/relevo:init` for labels, branches, protection, workflows and the ignore line; the install commands shown for tools and skills; adding the model credential to the repository secrets by hand.
-4. If the output says branch protection is not available, say plainly that approving and merging are then enforced only by the written confirmation `ship` asks for, not by the platform.
+4. If a `ship.app` check fails, say that the `relevo:ship` label cannot ship in this repository until a GitHub App and its two secrets exist, because the base branch requires checks, and that `/relevo:ship` still works meanwhile.
+5. If the output says branch protection is not available, say plainly that approving and merging are then enforced only by the written confirmation `ship` asks for, not by the platform.
 
 ## Exit status