@elalfner/relevo 0.7.0 → 0.8.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "relevo",
   "displayName": "Relevo",
-  "version": "0.7.0",
+  "version": "0.8.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.7.0",
+  "version": "0.8.0",
   "description": "Relevo: an automatic issue-to-merge workflow where an agent builds and people verify.",
   "type": "module",
   "license": "MIT",

package/scripts/init.mjs

@@ -11,7 +11,7 @@ import { execFileSync } from 'node:child_process';
 import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { homedir } from 'node:os';
-import { gatherFacts, readOnlyGh, WORKFLOW_FILES } from './lib/doctor.mjs';
+import { gatherFacts, readOnlyGh, vueWebFacts, WORKFLOW_FILES } from './lib/doctor.mjs';
 import { applyPlan, planInit, renderPlan, skipItems } from './lib/init.mjs';
 
 const arg = (name) => {
@@ -50,6 +50,8 @@ const facts = gatherFacts({
   repo,
 });
 
+facts.vueWeb = vueWebFacts(facts.config?.platforms ?? answers.platforms ?? {}, { tool, exists: existsSync });
+
 let admin = false;
 try {
   admin = JSON.parse(run('gh', ['api', `repos/${repo}`])).permissions?.admin === true;

package/scripts/lib/can-edit-issue.mjs

@@ -14,8 +14,11 @@ const REASON = {
   'qa-failed': 'a branch already exists and the text would no longer match what was built',
   'changes-requested': 'a branch already exists and the text would no longer match what was built',
   'needs-reviewer': 'it is built and waiting for a reviewer',
+  ship: 'its pull request is being merged',
+  // Not a state: it travels next to one, so the state decides whether the text may change.
+  urgent: 'the label asks for an early start and does not commit the issue to a build',
 };
-export const EDITABLE_LABELS = ['needs-spec'];
+export const EDITABLE_LABELS = ['needs-spec', 'urgent'];
 
 /**
  * @param {{state?: string, labels?: Array<string|{name: string}>}} issue  `gh issue view --json state,labels`

package/scripts/lib/config.mjs

@@ -20,6 +20,8 @@ export const SETTINGS = [
   { path: 'review.merger', type: 'enum', allowed: ['author', 'approver'], default: 'approver' },
   { path: 'review.autopilot', type: 'enum', allowed: ['off', 'precheck', 'verify'], default: 'off' },
   { path: 'review.allowed_origins', type: 'origin-list', default: [] },
+  // Whether the ship workflow may merge when no check ran on any commit; /relevo:ship asks the person instead.
+  { path: 'review.ship_without_ci', type: 'bool', default: false },
   { path: 'limits.built_unreviewed_per_person', type: 'int', min: 1, default: 2 },
   { path: 'limits.concurrent_agents', type: 'int', min: 1, default: 3 },
   { path: 'limits.review_sla_hours', type: 'int', min: 1, default: 8 },
@@ -29,6 +31,8 @@ export const SETTINGS = [
   { path: 'limits.run_max_cost', type: 'number', exclusiveMin: 0, required: true, default: null, requiredFor: 'claude', missing: 'unattended runs must always have a cost limit (amount in US dollars per run)', rejectedFor: 'antigravity', rejection: 'the agent has no cost limit; set limits.run_max_tokens instead, and note that the quota of the Google Cloud project that owns the key is the ceiling that really holds' },
   { path: 'limits.run_max_tokens', type: 'int', min: 1000, default: null, required: true, requiredFor: 'antigravity', missing: 'unattended runs must always have a limit, and for this agent it is a number of tokens per run', rejectedFor: 'claude', rejection: 'the run is limited by limits.run_max_cost' },
   { path: 'agent.build', type: 'enum', allowed: ['claude', 'antigravity'], default: 'claude' },
+  // The runner of every Relevo workflow: runs-on is read before any step, so init writes these labels into the files.
+  { path: 'runner.labels', type: 'label-list', default: ['ubuntu-latest'] },
   { path: 'qa.retries', type: 'int', min: 0, default: 1 },
   { path: 'qa.rules_from', type: 'path-list', default: [] },
   { path: 'skills.allow_scripts', type: 'string[]', default: [] },
@@ -79,6 +83,15 @@ function checkType(setting, value, errors) {
         errors.push({ path, message: `${path} must be a list of non-empty strings (got ${JSON.stringify(value)})` });
       }
       break;
+    case 'label-list':
+      if (!Array.isArray(value)) {
+        errors.push({ path, message: `${path} must be a list of runner labels, for example [self-hosted, Front] (got ${JSON.stringify(value)})` });
+      } else if (value.length === 0) {
+        errors.push({ path, message: `${path} needs at least one label; leave the setting out to use ubuntu-latest` });
+      } else if (value.some((v) => typeof v !== 'string' || v.trim() === '')) {
+        errors.push({ path, message: `${path} must be a list of non-empty strings (got ${JSON.stringify(value)})` });
+      }
+      break;
     case 'path-list':
       if (!Array.isArray(value) || value.length === 0 || value.some((v) => typeof v !== 'string' || v.trim() === '')) {
         errors.push({ path, message: `${path} must be a file name or a list of file names (got ${JSON.stringify(value)})` });
@@ -161,7 +174,12 @@ export function validateConfig(raw, { knownTargets = null, knownChecks = null }
     }
     const known = new Set(SETTINGS.filter((s) => s.path.startsWith(`${group}.`)).map((s) => s.path.split('.')[1]));
     Object.keys(value).forEach((k) => {
-      if (!known.has(k)) errors.push({ path: `${group}.${k}`, message: `unknown setting "${group}.${k}"` });
+      if (known.has(k)) return;
+      // Relevo cannot verify what a runner is, so it offers no such key: a runner is assumed to persist.
+      const message = `${group}.${k}` === 'runner.ephemeral'
+        ? 'unknown setting "runner.ephemeral": Relevo does not ask whether a runner is ephemeral, it assumes every runner persists between jobs'
+        : `unknown setting "${group}.${k}"`;
+      errors.push({ path: `${group}.${k}`, message });
     });
   });
 

package/scripts/lib/doctor.mjs

@@ -25,7 +25,10 @@ export const SKILL_INSTALL = {
   'supabase-postgres-best-practices': 'run `npx skills add supabase/agent-skills --skill supabase-postgres-best-practices`',
 };
 export const OPENSPEC_INSTALL = 'npm install --global @fission-ai/openspec (needs Node.js 20.19 or newer)';
-export const WORKFLOW_FILES = ['relevo-go.yml', 'relevo-queue.yml', 'relevo-review.yml', 'relevo-sla.yml', 'relevo-digest.yml'];
+export const WORKFLOW_FILES = ['relevo-go.yml', 'relevo-queue.yml', 'relevo-review.yml', 'relevo-sla.yml', 'relevo-digest.yml', 'relevo-ship.yml'];
+// The repository variable that pauses the ship workflow, and the secrets of the GitHub App it pushes with.
+export const SHIP_VARIABLE = 'RELEVO_CLOUD_SHIP';
+export const SHIP_APP_SECRETS = ['RELEVO_SHIP_APP_ID', 'RELEVO_SHIP_APP_KEY'];
 const REQUIRED_WORKFLOWS = new Set(['relevo-go.yml']);
 // How to ask a tool that it is there (most answer --version), and how to install the ones Relevo knows.
 const TOOL_PROBE = { adb: ['version'] };
@@ -70,10 +73,10 @@ export function refMatches(pattern, branch, defaultBranch) {
 
 /**
  * What the repository enforces on a branch, from its rulesets and its classic protection.
- * Returns { protected, pullRequestRequired, approvals, dismissStale, blocksDeletion, blocksForcePush }.
+ * Returns { protected, pullRequestRequired, approvals, dismissStale, lastPushApproval, requiredChecks, blocksDeletion, blocksForcePush }.
  */
 export function summarizeProtection({ rulesets = [], classic = null, branch, defaultBranch }) {
-  const out = { protected: false, pullRequestRequired: false, approvals: 0, dismissStale: false, blocksDeletion: false, blocksForcePush: false };
+  const out = { protected: false, pullRequestRequired: false, approvals: 0, dismissStale: false, lastPushApproval: false, requiredChecks: false, blocksDeletion: false, blocksForcePush: false };
   rulesets.filter((r) => r.target === 'branch' && r.enforcement === 'active').forEach((r) => {
     const include = r.conditions?.ref_name?.include ?? [];
     const exclude = r.conditions?.ref_name?.exclude ?? [];
@@ -84,7 +87,9 @@ export function summarizeProtection({ rulesets = [], classic = null, branch, def
         out.pullRequestRequired = true;
         out.approvals = Math.max(out.approvals, rule.parameters?.required_approving_review_count ?? 0);
         if (rule.parameters?.dismiss_stale_reviews_on_push) out.dismissStale = true;
+        if (rule.parameters?.require_last_push_approval) out.lastPushApproval = true;
       }
+      if (rule.type === 'required_status_checks') out.requiredChecks = true;
       if (rule.type === 'deletion') out.blocksDeletion = true;
       if (rule.type === 'non_fast_forward') out.blocksForcePush = true;
     });
@@ -96,13 +101,45 @@ export function summarizeProtection({ rulesets = [], classic = null, branch, def
       out.pullRequestRequired = true;
       out.approvals = Math.max(out.approvals, pr.required_approving_review_count ?? 0);
       if (pr.dismiss_stale_reviews) out.dismissStale = true;
+      if (pr.require_last_push_approval) out.lastPushApproval = true;
     }
+    if (classic.required_status_checks) out.requiredChecks = true;
     if (classic.allow_deletions?.enabled === false) out.blocksDeletion = true;
     if (classic.allow_force_pushes?.enabled === false) out.blocksForcePush = true;
   }
   return out;
 }
 
+// ---------- Playwright of a platform
+
+/** Is the platform a Vue platform reviewed in a browser? `web` is the only target of Vue, and its default. */
+export const isVueWeb = (platform) => platform?.stack === 'vue' && (!platform.targets?.length || platform.targets.includes('web'));
+
+/**
+ * Does Playwright resolve from the folder of a platform, and is its Chromium installed? Resolving from the folder, not
+ * from where the command runs, finds the node_modules of a platform in a subfolder. `tool(name, args)` throws when the
+ * command fails; `exists(path)`.
+ */
+export function playwrightFacts(dir, { tool, exists }) {
+  const where = "require.resolve('playwright', { paths: [require('node:path').resolve(process.argv[1])] })";
+  try {
+    tool('node', ['-e', where, dir || '.']);
+  } catch {
+    return { playwright: false, chromium: false };
+  }
+  try {
+    const path = String(tool('node', ['-e', `process.stdout.write(require(${where}).chromium.executablePath())`, dir || '.'])).trim();
+    return { playwright: true, chromium: path !== '' && Boolean(exists(path)) };
+  } catch {
+    return { playwright: true, chromium: false };
+  }
+}
+
+/** playwrightFacts of each Vue platform with a web target, by platform name. */
+export function vueWebFacts(platforms, deps) {
+  return Object.fromEntries(Object.entries(platforms ?? {}).filter(([, p]) => isVueWeb(p)).map(([name, p]) => [name, playwrightFacts(p.path, deps)]));
+}
+
 // ---------- gather
 
 /**
@@ -160,6 +197,8 @@ export function gatherFacts(p) {
   f.openspecRootTracked = tryRun(() => String(p.tool('git', ['ls-files', 'openspec'])).trim().length > 0, false);
   f.evidenceIgnored = p.exists('.gitignore') && /^\/?evidence\/?\s*$/m.test(p.read('.gitignore'));
   f.pluginDeclared = pluginDeclaration(p);
+  f.webHook = webHookDeclaration(p);
+  f.remoteSession = process.env.CLAUDE_CODE_REMOTE === 'true';
 
   // Workflows: what runs on GitHub is what is on the default branch, not what is in the working copy, so once the
   // repository is known they are read from there. `present` says whether the file is where it has to be; `local`
@@ -210,6 +249,7 @@ export function gatherFacts(p) {
     f.canApprove = tryRun(() => api(`repos/${f.repo}/actions/permissions/workflow`).can_approve_pull_request_reviews, null);
     f.secrets = tryRun(() => api(`repos/${f.repo}/actions/secrets`).secrets.map((s) => s.name));
     f.cloudVariable = tryRun(() => api(`repos/${f.repo}/actions/variables/${CLOUD_VARIABLE}`).value, null);
+    f.shipVariable = tryRun(() => api(`repos/${f.repo}/actions/variables/${SHIP_VARIABLE}`).value, null);
     // The repositories this one may depend on: can they be read, and are they private (then a token is needed)?
     f.links = (f.config?.links ?? []).map((link) => {
       const info = tryRun(() => api(`repos/${link}`), null);
@@ -286,6 +326,28 @@ export function pluginDeclaration(p) {
   }
 }
 
+// The one-line `SessionStart` hook that installs OpenSpec in a session of Claude Code on the web. It does nothing
+// outside a remote session, and nothing when `openspec` already runs; `|| true` keeps a failed install from failing the hook.
+export const WEB_HOOK_COMMAND = '[ "$CLAUDE_CODE_REMOTE" = "true" ] && ! command -v openspec >/dev/null 2>&1 && OPENSPEC_TELEMETRY=0 npm install --global @fission-ai/openspec || true';
+
+/** Does a `SessionStart` entry install OpenSpec? The package name is what is matched, so a hook written by hand counts. */
+const installsOpenspec = (entry) => (entry?.hooks ?? []).some((h) => typeof h?.command === 'string' && h.command.includes('@fission-ai/openspec'));
+
+/**
+ * Whether the committed settings file has a `SessionStart` hook that installs OpenSpec: { declared } or, when the file
+ * is not valid JSON, { unreadable: true }. A missing file is { declared: false }.
+ */
+export function webHookDeclaration(p) {
+  const path = '.claude/settings.json';
+  if (!p.exists(path)) return { declared: false };
+  try {
+    const settings = JSON.parse(p.read(path));
+    return { declared: Array.isArray(settings?.hooks?.SessionStart) && settings.hooks.SessionStart.some(installsOpenspec) };
+  } catch {
+    return { unreadable: true };
+  }
+}
+
 /** Reads a file: the plugin's own files from disk, the repository's through the probes. Null when absent. */
 function readerFor(p, tryRun) {
   const pluginRoot = p.pluginRoot ?? PLUGIN_ROOT;
@@ -363,7 +425,7 @@ function gatherPlatforms(f, p, tryRun) {
           const pubspec = p.exists(join(platform.path, 'pubspec.yaml')) ? tryRun(() => p.read(join(platform.path, 'pubspec.yaml')), '') : '';
           entry.driverDependency = /^\s*flutter_driver\s*:/m.test(pubspec ?? '');
         } else if (platform.stack === 'vue') {
-          entry.playwright = tryRun(() => Boolean(p.tool('node', ['-e', "require.resolve('playwright')"])), false);
+          entry.playwright = playwrightFacts(platform.path, { tool: p.tool, exists: p.exists }).playwright;
         }
         return entry;
       }),
@@ -532,7 +594,7 @@ function platformChecks(f) {
       if (!e.driverDependency) r.push(warn(`autopilot.${e.name}.dependency`, `platform ${e.name} does not depend on flutter_driver (dev_dependencies), which the driven review needs`, 'add flutter_driver: { sdk: flutter } under dev_dependencies in pubspec.yaml'));
       else r.push(pass(`autopilot.${e.name}.dependency`, `platform ${e.name} depends on flutter_driver`));
     } else if (e.stack === 'vue') {
-      if (!e.playwright) r.push(warn(`autopilot.${e.name}.playwright`, `review.autopilot is ${f.autopilot.mode} but Playwright cannot be resolved from this project (platform ${e.name})`, 'npm install -D playwright && npx playwright install chromium'));
+      if (!e.playwright) r.push(warn(`autopilot.${e.name}.playwright`, `review.autopilot is ${f.autopilot.mode} but Playwright cannot be resolved from this project (platform ${e.name})`, `run /relevo:init, which offers it, or \`${e.path && e.path !== '.' ? `cd ${e.path} && ` : ''}npm install -D playwright && npx playwright install chromium\` and commit package.json and the lock file`));
       else r.push(pass(`autopilot.${e.name}.playwright`, `Playwright is available for platform ${e.name}`));
     } else {
       r.push(warn(`autopilot.${e.name}.adapter`, `review.autopilot is ${f.autopilot.mode}, but a driven review of the stack ${e.stack} (platform ${e.name}) is not available`, 'set review.autopilot to off, or review that platform by hand'));
@@ -576,6 +638,7 @@ export function runChecks(f) {
   else r.push(fail('openspec.root', 'the OpenSpec root is missing or not tracked by git, so a clean checkout (and the runner) has no `openspec/`', 'run /relevo:init, then commit openspec/config.yaml and the .gitkeep files'));
   r.push(f.evidenceIgnored ? pass('evidence.ignored', 'evidence/ is ignored by git') : fail('evidence.ignored', 'evidence/ is not in .gitignore; `review` would put screenshots in git', 'add the line `evidence/` to .gitignore (or run /relevo:init)'));
   r.push(...pluginDeclaredChecks(f));
+  r.push(...webHookChecks(f));
 
   // GitHub side
   if (!f.repo || !f.ghAuth) {
@@ -602,6 +665,7 @@ export function runChecks(f) {
       else if (f.config?.review?.mode !== 'none' && p.approvals < 1) r.push(fail(`repo.protection.${key}`, `${name} requires a pull request but no approval`, `require at least 1 approving review on ${name}`));
       else r.push(pass(`repo.protection.${key}`, `${name} requires a pull request${p.approvals ? ` with ${p.approvals} approval(s)` : ''}`));
       if (p?.dismissStale) r.push(fail(`repo.dismiss-stale.${key}`, `${name} dismisses approvals when new commits are pushed; the spec archive commit pushed by \`ship\` would dismiss the approval`, `turn off "dismiss stale pull request approvals when new commits are pushed" on ${name}`));
+      if (p?.lastPushApproval) r.push(fail(`repo.last-push.${key}`, `${name} requires the most recent push to be approved by someone else; the spec archive commit pushed by \`ship\` would need a new approval`, `turn off "require approval of the most recent reviewable push" on ${name}`));
     });
   }
   if (!f.protectionUnavailable && !f.protectionError) {
@@ -637,11 +701,13 @@ export function runChecks(f) {
 
   r.push(...pluginInstallChecks(f));
   r.push(...toolchainChecks(f));
+  r.push(...runnerChecks(f));
   if (f.pluginMarketplace && f.pluginRepoPrivate === true && !f.pluginMarketplaceHasToken) {
     r.push(fail('automation.plugin-clone', `the plugin repository (${f.pluginMarketplace}) is private, so the runner cannot clone it without a credential`, 'store a read-only token as RELEVO_PLUGIN_TOKEN and use the private-repository line in relevo-go.yml'));
   }
   r.push(...linkChecks(f));
   r.push(...executionChecks(f));
+  r.push(...shipChecks(f));
   if (f.pluginRepoPrivate === true && Array.isArray(f.secrets)) {
     if (f.secrets.includes('RELEVO_PLUGIN_TOKEN')) r.push(pass('automation.plugin-secret', 'the RELEVO_PLUGIN_TOKEN secret exists for the private plugin repository'));
     else r.push(fail('automation.plugin-secret', 'the plugin repository is private and the repository has no RELEVO_PLUGIN_TOKEN secret, so the workflows fall back to the default token and fail at checkout', 'store a read-only fine-grained token that can read the plugin repository as the repository secret RELEVO_PLUGIN_TOKEN; a secret defined at organization level is not visible to this check'));
@@ -649,6 +715,27 @@ export function runChecks(f) {
   return r;
 }
 
+/**
+ * What the ship workflow needs, when it is on the default branch: the App secrets when the base branch requires checks
+ * (a push with the workflow token starts none, so the archive commit would never get them), and whether it is paused.
+ * Its label is checked with the other labels, and it needs no model credential.
+ */
+function shipChecks(f) {
+  const r = [];
+  if (!f.workflows?.['relevo-ship.yml']?.present) return r;
+  const base = f.config?.branches?.base ?? 'base';
+  if (f.protectionError || f.protectionUnavailable) return r;
+  if (f.protection?.base?.requiredChecks) {
+    if (f.secrets === null) r.push(warn('ship.app', `${base} requires status checks and the secrets could not be listed, so the ship App was not checked`, `check that ${SHIP_APP_SECRETS.join(' and ')} exist`));
+    else if (SHIP_APP_SECRETS.every((s) => f.secrets.includes(s))) r.push(pass('ship.app', `${base} requires status checks and the ship App secrets exist, so the relevo:ship label pushes with the App and the checks run on the archive commit`));
+    else r.push(fail('ship.app', `${base} requires status checks, so the relevo:ship label cannot ship here: the archive commit pushed with the workflow token would never get its checks`, `create a GitHub App for this repository and store its id and private key as ${SHIP_APP_SECRETS.join(' and ')} (docs/execution.md, "Shipping with a label"), or ship with /relevo:ship`));
+  } else {
+    r.push(pass('ship.app', `${base} requires no status checks, so the checks of the approved head carry over to the archive commit and the ship workflow needs no App`));
+  }
+  if (String(f.shipVariable ?? '').trim().toLowerCase() === 'off') r.push(warn('ship.paused', `the relevo:ship label is paused (${SHIP_VARIABLE} is off)`, `delete the repository variable ${SHIP_VARIABLE}, or set it to on, to ship with the label again`));
+  return r;
+}
+
 // The action that sets up the toolchain of a stack in the build job of the go workflow. Vue needs only Node, which the
 // job installs for Relevo itself, and a stack that is not listed here is not judged.
 const TOOLCHAIN_ACTIONS = { flutter: { action: 'subosito/flutter-action', step: 'the Flutter step' }, laravel: { action: 'shivammathur/setup-php', step: 'the Laravel step' } };
@@ -670,6 +757,38 @@ function toolchainChecks(f) {
   });
 }
 
+const HOSTED_RUNNER = ['ubuntu-latest'];
+
+/** The labels written in a `runs-on` line: `[self-hosted, Front]` or `ubuntu-latest`; null for an expression we cannot judge. */
+function parseRunsOn(value) {
+  if (value.includes('${{')) return null;
+  const inner = value.startsWith('[') && value.endsWith(']') ? value.slice(1, -1) : value;
+  return inner.split(',').map((l) => l.trim().replace(/^['"]|['"]$/g, '')).filter(Boolean);
+}
+
+/**
+ * Does every Relevo workflow run on the runner that relevo.yml names (`runner.labels`, else ubuntu-latest)? A workflow
+ * edited by hand to another runner is reported with the file, because the next copy of the template would undo it. A
+ * runner that is not GitHub's is only assumed to persist: Relevo cannot tell, and says so instead of claiming.
+ */
+function runnerChecks(f) {
+  const wanted = f.config?.runner?.labels ?? HOSTED_RUNNER;
+  const same = (a, b) => a.length === b.length && [...a].sort().every((l, i) => l === [...b].sort()[i]);
+  const r = [];
+  let judged = 0;
+  Object.entries(f.workflows ?? {}).forEach(([file, w]) => {
+    if (!w.present || typeof w.text !== 'string') return;
+    judged += 1;
+    const found = [...w.text.matchAll(/^[ \t]+runs-on:[ \t]*(.+?)[ \t]*(?:#.*)?$/gm)].map((m) => parseRunsOn(m[1])).filter((l) => l !== null);
+    const other = found.find((labels) => !same(labels, wanted));
+    if (other) r.push(fail(`automation.runner.${file}`, `${file} runs on [${other.join(', ')}] and relevo.yml says [${wanted.join(', ')}]`, same(wanted, HOSTED_RUNNER) ? `set runner.labels: [${other.join(', ')}] in relevo.yml if that is the runner you want, or restore runs-on: ubuntu-latest in ${file}` : `change runs-on in ${file} to [${wanted.join(', ')}], or change runner.labels in relevo.yml`));
+  });
+  if (r.length > 0) return r;
+  if (judged > 0) r.push(pass('automation.runner', `the Relevo workflows run on [${wanted.join(', ')}]`));
+  if (!same(wanted, HOSTED_RUNNER)) r.push(warn('automation.runner.persistence', `the runner [${wanted.join(', ')}] is not GitHub's: Relevo assumes it keeps its files between jobs, and the code the agent writes runs with the permissions of the runner's user`, 'an ephemeral runner (created for one job) or a container is the real barrier; Relevo installs its tools under the temporary folder of the job and removes what it adds, but cannot make the machine a sandbox (docs/security.md)'));
+  return r;
+}
+
 /** Does the committed settings file declare the plugin? It is a local fact, so it needs no GitHub sign-in. */
 function pluginDeclaredChecks(f) {
   const r = [];
@@ -679,6 +798,18 @@ function pluginDeclaredChecks(f) {
   return r;
 }
 
+/**
+ * Does the repository install OpenSpec in the sessions of Claude Code on the web? The hook has no use on a terminal,
+ * where OpenSpec stays installed, so it is judged only when doctor itself runs in a remote session. It warns: the
+ * project can run without it, but every new session starts without OpenSpec.
+ */
+function webHookChecks(f) {
+  if (!f.remoteSession || !f.webHook) return [];
+  if (f.webHook.unreadable) return [warn('web.openspec-hook', '.claude/settings.json is not valid JSON, so it cannot be checked whether it installs OpenSpec in web sessions', 'fix the file; /relevo:init then offers the hook')];
+  if (f.webHook.declared) return [pass('web.openspec-hook', 'the repository installs OpenSpec at the start of a web session (SessionStart hook in .claude/settings.json)')];
+  return [warn('web.openspec-hook', 'this is a web session and the repository has no SessionStart hook that installs OpenSpec, so every new session starts without it and go cannot run', `run /relevo:init to add the hook, commit .claude/settings.json, or install it now: ${OPENSPEC_INSTALL}`)];
+}
+
 /**
  * The installed plugin and what the workflows pin. A package that lost a folder cannot run; a workflow that clones
  * the plugin repository for its scripts (the layout before the package) or has no pin is told to be replaced; a pin

package/scripts/lib/github.mjs

@@ -45,16 +45,20 @@ function normalizeIssue(raw) {
     milestone: raw.milestone ? { number: raw.milestone.number, due_on: raw.milestone.due_on ?? null } : null,
     ready_at: null,
     ready_by: null,
+    urgent_by: null,
   };
 }
 
-/** When and by whom the ready label was last applied, from the issue timeline. */
-export function readyEvent(timeline, readyName) {
-  const events = timeline.filter((e) => e.event === 'labeled' && e.label?.name === readyName);
+/** When and by whom a label was last applied, from the issue timeline. */
+export function labelEvent(timeline, labelName) {
+  const events = timeline.filter((e) => e.event === 'labeled' && e.label?.name === labelName);
   const last = events[events.length - 1];
   return last ? { at: last.created_at, by: last.actor?.login ?? null } : { at: null, by: null };
 }
 
+/** When and by whom the ready label was last applied. */
+export const readyEvent = labelEvent;
+
 /**
  * Collect everything `planGo` needs. Returns { issues, completed, completedExternal, unreadable, running, permissions }.
  * `running` is supplied by the caller (workflow runs in progress). `ghLinks` reads issues of linked repositories
@@ -74,9 +78,11 @@ export function gather({ gh, ghLinks = gh, repo, config, running = [] }) {
   const candidates = issues.filter((i) => [names.ready, names.queued, names.blocked].some((n) => i.labels.includes(n)));
   candidates.forEach((issue) => {
     const timeline = apiJson(gh, `repos/${repo}/issues/${issue.number}/timeline?per_page=100`, { paginate: true });
-    const { at, by } = readyEvent(timeline, names.ready);
+    const { at, by } = labelEvent(timeline, names.ready);
     issue.ready_at = at;
     issue.ready_by = by;
+    // The same timeline answers for the urgent label: who asked for the early start.
+    if (issue.labels.includes(names.urgent)) issue.urgent_by = labelEvent(timeline, names.urgent).by;
   });
 
   const wanted = new Set();
@@ -109,7 +115,7 @@ export function gather({ gh, ghLinks = gh, repo, config, running = [] }) {
   });
 
   const permissions = {};
-  new Set(candidates.map((i) => i.ready_by).filter(Boolean)).forEach((login) => {
+  new Set(candidates.flatMap((i) => [i.ready_by, i.urgent_by]).filter(Boolean)).forEach((login) => {
     try {
       permissions[login] = apiJson(gh, `repos/${repo}/collaborators/${login}/permission`).permission ?? 'none';
     } catch {
@@ -132,6 +138,10 @@ export function commandsFor(decision, { repo, config }) {
     const body = renderMessage(decision.comment.kind, decision.comment.data, config.language);
     commands.push(['issue', 'comment', String(decision.issue), '--repo', repo, '--body', body]);
   }
+  if (decision.notice) {
+    const body = renderMessage(decision.notice.kind, decision.notice.data, config.language);
+    commands.push(['issue', 'comment', String(decision.issue), '--repo', repo, '--body', body]);
+  }
   return commands;
 }
 

package/scripts/lib/init.mjs

@@ -9,7 +9,7 @@ import { loadConfig } from './config.mjs';
 import { LEGACY_PLATFORMS } from './platforms.mjs';
 import { labelDefinitions } from './labels.mjs';
 import { agentWorkflow } from './agent-workflow.mjs';
-import { OPENSPEC_INSTALL, REQUIRED_SKILLS, SKILL_INSTALL, WORKFLOW_FILES } from './doctor.mjs';
+import { isVueWeb, OPENSPEC_INSTALL, REQUIRED_SKILLS, SKILL_INSTALL, WEB_HOOK_COMMAND, WORKFLOW_FILES } from './doctor.mjs';
 
 export const REVIEW_MODES = ['none', 'peer', 'roles'];
 
@@ -28,12 +28,42 @@ const TOKEN_LINE = '          # claude_code_oauth_token: ${{ secrets.CLAUDE_CODE
 export const PLUGIN_PROJECT_COMMAND = 'claude plugin marketplace add elalfner/relevo --scope project --sparse .claude-plugin && claude plugin install relevo@relevo --scope project';
 const PLUGIN_PROJECT_DETAIL = 'It writes the marketplace and the enabled plugin into .claude/settings.json of this repository. It works even if the plugin is already installed for your machine, and nothing is committed for you.';
 
+const WEB_HOOK_DETAIL = 'It adds a SessionStart hook to .claude/settings.json of this repository, keeping what the file already has. In a session of Claude Code on the web it installs OpenSpec when it is missing (npm install --global @fission-ai/openspec); on a terminal it does nothing. The file is left for you to commit.';
+
+/**
+ * `.claude/settings.json` with the hook that installs OpenSpec added to `SessionStart`, every other key and hook kept.
+ * Idempotent: text that already installs OpenSpec is returned as it is. Throws on text that is not a JSON object, so a
+ * broken file is never rewritten. `text` is null when the file does not exist.
+ */
+export function mergeWebHook(text) {
+  const settings = text === null ? {} : JSON.parse(text);
+  if (settings === null || typeof settings !== 'object' || Array.isArray(settings)) throw new Error('.claude/settings.json is not a JSON object');
+  const current = settings.hooks?.SessionStart;
+  if (current !== undefined && !Array.isArray(current)) throw new Error('hooks.SessionStart in .claude/settings.json is not a list');
+  if ((current ?? []).some((e) => (e?.hooks ?? []).some((h) => typeof h?.command === 'string' && h.command.includes('@fission-ai/openspec')))) return text;
+  const hooks = { ...(settings.hooks ?? {}), SessionStart: [...(current ?? []), { hooks: [{ type: 'command', command: WEB_HOOK_COMMAND }] }] };
+  return `${JSON.stringify({ ...settings, hooks }, null, 2)}\n`;
+}
+
 export function credentialLine(workflow, credential) {
   if (credential !== 'subscription') return workflow;
   if (!workflow.includes(API_KEY_LINE) || !workflow.includes(TOKEN_LINE)) throw new Error('the go workflow template has no credential lines to switch');
   return workflow.replace(API_KEY_LINE, API_KEY_LINE.replace('anthropic_api_key', '# anthropic_api_key')).replace(TOKEN_LINE, TOKEN_LINE.replace('# claude_code_oauth_token', 'claude_code_oauth_token'));
 }
 
+export const DEFAULT_RUNNER = ['ubuntu-latest'];
+
+/**
+ * The workflow with the runner of `runner.labels` in every `runs-on`. The templates run on `ubuntu-latest`, which is
+ * what an empty or default list leaves alone; a list of one label is written as that label.
+ */
+export function runnerLine(workflow, labels) {
+  const list = labels ?? DEFAULT_RUNNER;
+  if (list.length === 1 && list[0] === DEFAULT_RUNNER[0]) return workflow;
+  if (!workflow.includes('runs-on: ubuntu-latest')) throw new Error('the workflow template has no runs-on line to switch');
+  return workflow.replaceAll('runs-on: ubuntu-latest', `runs-on: ${list.length === 1 ? list[0] : `[${list.join(', ')}]`}`);
+}
+
 /** The text of a `platforms:` block for { name: { stack, path, targets } }. */
 export function platformsBlock(platforms) {
   const lines = ['platforms:'];
@@ -96,6 +126,15 @@ export function renderConfig(template, answers = {}) {
     if (answers.runMaxTokens !== undefined) out = set(out, 'run_max_tokens', answers.runMaxTokens);
   } else if (answers.runMaxCost !== undefined) out = set(out, 'run_max_cost', answers.runMaxCost);
   if (answers.language) out = set(out, 'language', answers.language);
+  // The commented example of the template becomes the setting; the default runner leaves the template as it is.
+  if (answers.runnerLabels && !(answers.runnerLabels.length === 1 && answers.runnerLabels[0] === DEFAULT_RUNNER[0])) {
+    const re = /^# runner:[^\n]*\n#   labels:[^\n]*\n/m;
+    if (!re.test(out)) throw new Error('the template has no "runner" example to switch on');
+    out = out.replace(re, `runner:                             # where the Relevo workflows run (docs/execution.md)\n  labels: [${answers.runnerLabels.join(', ')}]\n`);
+  }
+  // A browser review is always driven by the agent, so a Vue web platform cannot keep the autopilot off.
+  const autopilot = answers.autopilot ?? (Object.values(platforms ?? {}).some(isVueWeb) ? 'precheck' : null);
+  if (autopilot) out = set(out, 'autopilot', autopilot);
   const check = loadConfig(out);
   if (!check.ok) throw new Error(`the answers produce an invalid relevo.yml: ${check.errors.map((e) => e.message).join('; ')}`);
   return out;
@@ -167,7 +206,7 @@ const item = (id, status, description, extra = {}) => ({ id, status, description
 /**
  * Plan every change. `ctx`:
  *   facts      from gatherFacts (doctor)
- *   answers    the person's answers (members, specWriter, reviewMode, language, platforms, links, runs, credential, stackProfiles, base, release, merger)
+ *   answers    the person's answers (members, specWriter, reviewMode, language, platforms, links, runs, credential, runnerLabels, stackProfiles, base, release, merger)
  *   templates  { config: text, workflows: { file: text } }
  *   current    { workflows: { file: text|null }, gitignore: text|null, keepFiles: { path: boolean } }
  *   admin      true when the person has administrator permission on the repository
@@ -199,11 +238,30 @@ export function planInit({ facts, answers, templates, current, admin }) {
     });
   }
 
+  // What a browser review of each Vue platform needs: Playwright in its development dependencies, and its Chromium.
+  Object.entries(configuredPlatforms).filter(([, p]) => isVueWeb(p)).forEach(([name, p]) => {
+    const found = facts.vueWeb?.[name];
+    if (!found) return;
+    const cd = p.path && p.path !== '.' ? `cd ${p.path} && ` : '';
+    if (found.playwright) items.push(item(`install.playwright.${name}`, 'ok', `Playwright resolves from platform ${name}`));
+    else items.push(item(`install.playwright.${name}`, 'todo', `Add Playwright to the development dependencies of platform ${name}, which its browser review needs (package.json and the lock file are left for you to commit)`, { install: true, command: `${cd}npm install -D playwright`, detail: 'It changes package.json and the lock file of the platform: commit them on the base branch, so that every review finds Playwright. If you decline, a browser review of this platform stops until it is installed.' }));
+    if (found.playwright && found.chromium) items.push(item(`install.chromium.${name}`, 'ok', `The Chromium of Playwright is installed for platform ${name}`));
+    else items.push(item(`install.chromium.${name}`, 'todo', `Install the Chromium of Playwright for platform ${name}`, { install: true, command: `${cd}npx playwright install chromium`, detail: 'It downloads the browser to the cache of your user, outside the repository. If you decline, a browser review of this platform stops until it is installed.' }));
+  });
+  if (facts.config && (facts.config.review?.autopilot ?? 'off') === 'off' && Object.values(configuredPlatforms).some(isVueWeb)) {
+    items.push(item('review.autopilot', 'manual', 'A browser review of a Vue platform is driven by the agent: set review.autopilot to precheck (or verify) in relevo.yml'));
+  }
+
   // the plugin, declared in the project so that a teammate who clones the repository is offered it
   if (facts.pluginDeclared?.declared) items.push(item('install.plugin-project', 'ok', 'The repository declares the Relevo plugin (.claude/settings.json)'));
   else if (facts.pluginDeclared?.unreadable) items.push(item('install.plugin-project', 'manual', '.claude/settings.json is not valid JSON: fix it, then run init again to declare the Relevo plugin in the project'));
   else if (facts.pluginDeclared) items.push(item('install.plugin-project', 'todo', 'Declare the Relevo plugin in the project, so that a teammate who clones the repository is offered it (the new .claude/settings.json is left for you to commit)', { install: true, command: PLUGIN_PROJECT_COMMAND, detail: PLUGIN_PROJECT_DETAIL }));
 
+  // OpenSpec in the sessions of Claude Code on the web, where every new container starts without it
+  if (facts.webHook?.declared) items.push(item('install.web-hook', 'ok', 'The repository installs OpenSpec at the start of a web session (.claude/settings.json)'));
+  else if (facts.webHook?.unreadable) items.push(item('install.web-hook', 'manual', '.claude/settings.json is not valid JSON: fix it, then run init again to add the hook that installs OpenSpec in web sessions'));
+  else if (facts.webHook) items.push(item('install.web-hook', 'todo', 'Add a hook that installs OpenSpec at the start of a web session of Claude Code, where it is missing (the changed .claude/settings.json is left for you to commit)', { install: true, command: `node \${CLAUDE_PLUGIN_ROOT}/scripts/web-hook.mjs`, hook: WEB_HOOK_COMMAND, detail: WEB_HOOK_DETAIL }));
+
   // relevo.yml
   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 }) }));
@@ -248,11 +306,13 @@ export function planInit({ facts, answers, templates, current, admin }) {
   if (!CREDENTIALS.includes(credential)) throw new Error(`credential must be one of ${CREDENTIALS.join(', ')} (got "${credential}")`);
   const build = answers.agentBuild ?? 'claude';
   if (!AGENT_BUILDS.includes(build)) throw new Error(`agentBuild must be one of ${AGENT_BUILDS.join(', ')} (got "${build}")`);
+  // The runner of the workflows: the setting of the repository, else the person's answer, else GitHub's.
+  const runnerLabels = facts.config?.runner?.labels ?? answers.runnerLabels ?? DEFAULT_RUNNER;
   const cloudFiles = ['relevo-go.yml', 'relevo-queue.yml'];
   WORKFLOW_FILES.forEach((file) => {
     if (runs === 'local' && cloudFiles.includes(file)) return;
     const shared = file === 'relevo-go.yml' ? credentialLine(templates.workflows[file], credential) : templates.workflows[file];
-    const wanted = agentWorkflow(shared, build, templates.agentBlocks);
+    const wanted = runnerLine(agentWorkflow(shared, build, templates.agentBlocks), runnerLabels);
     const have = current.workflows[file] ?? null;
     if (have === null) items.push(item(`workflow.${file}`, 'todo', `Add .github/workflows/${file}`, { path: `.github/workflows/${file}`, content: wanted }));
     else if (have === wanted) items.push(item(`workflow.${file}`, 'ok', `.github/workflows/${file} is up to date`));

package/scripts/lib/labels.mjs

@@ -17,6 +17,10 @@ export const LABELS = [
   { key: 'qa-failed', name: 'relevo:qa-failed', color: 'e11d21', kind: 'exit', description: 'QA still rejected after the retries; branch is pushed' },
   { key: 'changes-requested', name: 'relevo:changes-requested', color: 'f9d0c4', kind: 'exit', description: 'The reviewer asked for changes' },
   { key: 'needs-reviewer', name: 'relevo:needs-reviewer', color: 'fef2c0', kind: 'overlay', description: 'No reviewer available or the review is overdue' },
+  // A request, not a state: the ship workflow merges the pull request and always removes it.
+  { key: 'ship', name: 'relevo:ship', color: '2ea44f', kind: 'overlay', description: 'Ship it: merge the approved pull request on GitHub' },
+  // A request, not a state: start it before the others and without waiting for the assignee's review capacity.
+  { key: 'urgent', name: 'relevo:urgent', color: 'ff7b00', kind: 'overlay', description: 'Start it first, even if the assignee has built issues waiting for review' },
 ];
 
 export const LABEL_KEYS = LABELS.map((l) => l.key);