@elalfner/relevo 0.6.0 → 0.8.0

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

package/scripts/lib/messages.mjs

@@ -29,10 +29,18 @@ const REQUIRED = {
   no_assignee: ['actor', 'issue'],
   ready_denied: ['issue'],
   ready_denied_maintainer: ['issue'],
+  urgent_denied: ['issue'],
+  urgent_denied_maintainer: ['issue'],
   blocked_notice: ['issue', 'title', 'blockers'],
   queued_capacity: ['issue', 'title', 'assignee', 'built', 'limit'],
   queued_agents: ['issue', 'title'],
   fix_done: ['issue', 'title', 'summary', 'qa', 'commit', 'iteration'],
+  ship_stopped: ['actor', 'issue', 'reasons'],
+  ship_not_approver: ['actor', 'issue'],
+  ship_no_ci: ['actor', 'issue'],
+  ship_needs_app: ['actor', 'issue', 'base'],
+  ship_done: ['issue', 'pr', 'base'],
+  ship_failed: ['issue', 'run'],
 };
 
 // The lifecycle state whose next step each message shows (see next-step.mjs, the only place that knows the commands).
@@ -52,6 +60,7 @@ const CATALOG = {
       '',
       'What happened: {{tasks_done}} of {{tasks_total}} tasks done, QA passed.',
       'Branch: {{branch}}',
+      'Started ahead of the queue (urgent): you now have {{built_waiting}} built issues waiting for your review.',
       'Built from the issue text: {{issue_hash_short}}',
       'What to test: {{scenarios}} scenarios (checklist below)',
       'Riskiest area, check it first: {{risk}}',
@@ -93,6 +102,7 @@ const CATALOG = {
       '',
       'Pull request: {{pr}}',
       'Your next step: {{command}}',
+      'Or apply the label {{ship_label}} to this issue: it ships on GitHub, with no local copy.',
     ],
     needs_reviewer: [
       '@{{spec_writer}} #{{issue}} "{{title}}" has no available reviewer',
@@ -134,10 +144,19 @@ const CATALOG = {
       '#{{issue}} was not started: this repository is public, so only maintainers can mark an issue ready, and the label was removed',
       'Applied by: @{{actor}}',
     ],
+    urgent_denied: [
+      '#{{issue}}: the urgent label was removed because only people with write access can ask for an early start. The issue keeps its place in the queue.',
+      'Applied by: @{{actor}}',
+    ],
+    urgent_denied_maintainer: [
+      '#{{issue}}: the urgent label was removed because this repository is public, so only maintainers can ask for an early start. The issue keeps its place in the queue.',
+      'Applied by: @{{actor}}',
+    ],
     blocked_notice: [
       '#{{issue}} "{{title}}" is blocked',
       '',
       'Waiting for {{blockers}} to be merged. It starts automatically when they are.',
+      '{{urgent_note}}',
     ],
     queued_capacity: [
       '#{{issue}} "{{title}}" is queued',
@@ -157,6 +176,41 @@ const CATALOG = {
       'Commit: {{commit}}',
       '@{{recipient}} {{ask}}',
     ],
+    ship_stopped: [
+      '@{{actor}} #{{issue}} was not shipped',
+      '',
+      'Why: {{reasons}}',
+      'Nothing was merged and the issue keeps its state; the relevo:ship label was removed. Apply it again once this is solved, or run `/relevo:ship {{issue}}`.',
+    ],
+    ship_not_approver: [
+      '@{{actor}} #{{issue}} was not shipped: you did not approve this pull request',
+      '',
+      'An eligible person who did not approve has to say so in writing, and a label cannot. Run `/relevo:ship {{issue}}`, which asks you to confirm it, or ask {{approvers}} to apply the label. The label was removed.',
+    ],
+    ship_no_ci: [
+      '@{{actor}} #{{issue}} was not shipped: no check ran on this pull request',
+      '',
+      'Nothing but the review vouches for this code, and the label cannot confirm that. Run `/relevo:ship {{issue}}`, which asks you, or set `review.ship_without_ci: true` in relevo.yml to let the label merge without checks. The label was removed.',
+    ],
+    ship_needs_app: [
+      '@{{actor}} #{{issue}} was not shipped: {{base}} requires status checks',
+      '',
+      'The archive commit needs its own checks, and a push with the workflow token starts none. Create a GitHub App for this repository and store its id and private key as the secrets RELEVO_SHIP_APP_ID and RELEVO_SHIP_APP_KEY (see docs/execution.md), or run `/relevo:ship {{issue}}`. Nothing was archived; the label was removed.',
+    ],
+    ship_done: [
+      '#{{issue}} shipped ✅',
+      '',
+      'Pull request {{pr}} was squash-merged into {{base}} as {{commit}}.',
+      'Applied by: @{{actor}}',
+      '{{checks_note}}',
+      'The issue is closed and its labels removed. Promoting {{base}} to the release branch is a separate pull request.',
+    ],
+    ship_failed: [
+      '#{{issue}} was not shipped: the run ended without an outcome',
+      '',
+      '{{log_line}}',
+      'When the cause is fixed, apply relevo:ship again: a specification already archived is not archived twice.',
+    ],
   },
   es: {
     built: [
@@ -164,6 +218,7 @@ const CATALOG = {
       '',
       'Qué pasó: {{tasks_done}} de {{tasks_total}} tareas hechas, QA aprobado.',
       'Rama: {{branch}}',
+      'Empezó antes que la cola (urgente): ahora tienes {{built_waiting}} issues construidos esperando tu revisión.',
       'Construida con el texto del issue: {{issue_hash_short}}',
       'Qué probar: {{scenarios}} escenarios (checklist abajo)',
       'Zona más riesgosa, revísala primero: {{risk}}',
@@ -205,6 +260,7 @@ const CATALOG = {
       '',
       'Pull request: {{pr}}',
       'Tu siguiente paso: {{command}}',
+      'O pon la etiqueta {{ship_label}} a este issue: se fusiona en GitHub, sin copia local.',
     ],
     needs_reviewer: [
       '@{{spec_writer}} #{{issue}} "{{title}}" no tiene revisor disponible',
@@ -246,10 +302,19 @@ const CATALOG = {
       '#{{issue}} no se inició: este repositorio es público, así que solo quienes mantienen el proyecto pueden marcar un issue como ready, y se quitó la etiqueta',
       'Aplicada por: @{{actor}}',
     ],
+    urgent_denied: [
+      '#{{issue}}: se quitó la etiqueta de urgente porque solo quienes tienen acceso de escritura pueden pedir un inicio anticipado. El issue conserva su lugar en la cola.',
+      'Aplicada por: @{{actor}}',
+    ],
+    urgent_denied_maintainer: [
+      '#{{issue}}: se quitó la etiqueta de urgente porque este repositorio es público, así que solo quienes mantienen el proyecto pueden pedir un inicio anticipado. El issue conserva su lugar en la cola.',
+      'Aplicada por: @{{actor}}',
+    ],
     blocked_notice: [
       '#{{issue}} "{{title}}" está bloqueado',
       '',
       'Espera a que se fusionen {{blockers}}. Empieza solo cuando lo estén.',
+      '{{urgent_note}}',
     ],
     queued_capacity: [
       '#{{issue}} "{{title}}" está en cola',
@@ -269,6 +334,41 @@ const CATALOG = {
       'Commit: {{commit}}',
       '@{{recipient}} {{ask}}',
     ],
+    ship_stopped: [
+      '@{{actor}} #{{issue}} no se fusionó',
+      '',
+      'Por qué: {{reasons}}',
+      'No se fusionó nada y el issue conserva su estado; se quitó la etiqueta relevo:ship. Vuelve a ponerla cuando esté resuelto, o ejecuta `/relevo:ship {{issue}}`.',
+    ],
+    ship_not_approver: [
+      '@{{actor}} #{{issue}} no se fusionó: tú no aprobaste este pull request',
+      '',
+      'Quien es elegible pero no aprobó tiene que decirlo por escrito, y una etiqueta no puede. Ejecuta `/relevo:ship {{issue}}`, que te pide confirmarlo, o pide a {{approvers}} que ponga la etiqueta. Se quitó la etiqueta.',
+    ],
+    ship_no_ci: [
+      '@{{actor}} #{{issue}} no se fusionó: no corrió ningún check en este pull request',
+      '',
+      'Solo la revisión respalda este código, y la etiqueta no puede confirmarlo. Ejecuta `/relevo:ship {{issue}}`, que te lo pregunta, o pon `review.ship_without_ci: true` en relevo.yml para que la etiqueta fusione sin checks. Se quitó la etiqueta.',
+    ],
+    ship_needs_app: [
+      '@{{actor}} #{{issue}} no se fusionó: {{base}} exige status checks',
+      '',
+      'El commit del archivo necesita sus propios checks, y un push con el token del workflow no lanza ninguno. Crea una GitHub App para este repositorio y guarda su id y su clave privada como los secrets RELEVO_SHIP_APP_ID y RELEVO_SHIP_APP_KEY (ver docs/execution.es.md), o ejecuta `/relevo:ship {{issue}}`. No se archivó nada; se quitó la etiqueta.',
+    ],
+    ship_done: [
+      '#{{issue}} fusionada ✅',
+      '',
+      'El pull request {{pr}} se fusionó con squash en {{base}} como {{commit}}.',
+      'La pidió: @{{actor}}',
+      '{{checks_note}}',
+      'El issue está cerrado y sin etiquetas. Promover {{base}} a la rama de release es un pull request aparte.',
+    ],
+    ship_failed: [
+      '#{{issue}} no se fusionó: la ejecución terminó sin resultado',
+      '',
+      '{{log_line}}',
+      'Cuando la causa esté resuelta, vuelve a poner relevo:ship: una especificación ya archivada no se archiva dos veces.',
+    ],
   },
 };
 
@@ -297,7 +397,16 @@ export function renderMessage(kind, data = {}, language = 'en') {
   });
   const language_ = pickLanguage(language);
   const es = language_ === 'es';
+  // The person who applied the label is mentioned when the run knows who it was.
+  if (kind === 'ship_failed') {
+    const who = present(values.actor) ? `@${values.actor} ` : '';
+    values.log_line = es ? `${who}${who ? 'lee' : 'Lee'} el log para ver por qué: ${values.run}` : `${who}${who ? 'read' : 'Read'} the log to see why: ${values.run}`;
+  }
   if (kind === 'built' && present(values.issue_hash)) values.issue_hash_short = shortHash(values.issue_hash);
+  // Urgent does not skip dependencies: an urgent issue that is blocked says so.
+  if (kind === 'blocked_notice' && values.urgent === true) {
+    values.urgent_note = es ? 'La etiqueta de urgente no salta las dependencias: empieza primero en la cola cuando se fusionen.' : 'The urgent label does not skip dependencies: it goes first in the queue once they are merged.';
+  }
 
   // The next step comes from one table. needs-spec depends on why the issue came back, qa-failed on what the branch holds.
   if (STATE_OF[kind]) {

package/scripts/lib/next-step.mjs

@@ -104,6 +104,18 @@ const TABLE = {
     who: 'spec_writer',
     hint: { en: 'assign a reviewer or ask someone to take it', es: 'asigna a alguien que revise o pide que alguien lo tome' },
   },
+  // The ship workflow is merging it; when it stops, its comment says why and the issue is back on pr-open.
+  ship: {
+    command: null,
+    who: 'nobody',
+    hint: { en: 'the ship workflow is merging it', es: 'el workflow de ship lo está fusionando' },
+  },
+  // A request next to the state, not a state: the state it travels with decides the next step.
+  urgent: {
+    command: null,
+    who: 'nobody',
+    hint: { en: 'it starts before the others; the state it is in decides the next step', es: 'empieza antes que las demás; el estado en que está decide el siguiente paso' },
+  },
 };
 
 const WHO = {

package/scripts/lib/plan.mjs

@@ -6,7 +6,8 @@
 //   issues     [{ number, title, body, state, labels: [names], assignees: [logins],
 //                 milestone: { number, due_on } | null,
 //                 ready_at: ISO | null,   // when the ready label was last applied
-//                 ready_by: login | null  // who applied it }]
+//                 ready_by: login | null, // who applied it
+//                 urgent_by: login | null // who applied the urgent label, when the issue carries it }]
 //   completed  issue numbers closed as completed (their pull request merged)
 //   running    issue numbers with an agent run in progress
 //   permissions  { login: 'admin' | 'maintain' | 'write' | 'triage' | 'read' | 'none' }
@@ -61,6 +62,12 @@ export function planGo({ config, issues, completed = [], completedExternal = [],
   const linked = (config.links ?? []);
   const own = repo ? repo.toLowerCase() : null;
 
+  // The urgent label is a request that only the people who may start work can make. A label from anyone else is not
+  // valid: it is removed (with a notice) and the issue is evaluated as a normal one.
+  const mayTrigger = config.trust === 'public' ? MAY_TRIGGER_PUBLIC : MAY_TRIGGER;
+  const hasUrgentLabel = (issue) => has(issue, 'urgent');
+  const isUrgent = (issue) => hasUrgentLabel(issue) && Boolean(issue.urgent_by) && mayTrigger.has(permissions[issue.urgent_by]);
+
   const runningSet = new Set(running);
   open.filter((i) => has(i, 'building')).forEach((i) => runningSet.add(i.number));
   let freeSlots = Math.max(0, config.limits.concurrent_agents - runningSet.size);
@@ -71,14 +78,16 @@ export function planGo({ config, issues, completed = [], completedExternal = [],
     if (owner) builtBy.set(owner, (builtBy.get(owner) ?? 0) + 1);
   });
 
+  // Valid urgent issues are considered first, so they take the free agent slots before the others; inside each group
+  // the order is the time `ready` was applied.
   const candidates = open
     .filter((i) => has(i, 'ready') || has(i, 'queued') || has(i, 'blocked'))
-    .sort(byReadyAt);
+    .sort((a, b) => Number(isUrgent(b)) - Number(isUrgent(a)) || byReadyAt(a, b));
 
   const decisions = [];
 
   function decision(issue, action, reason, extra = {}) {
-    const labels = extra.labels ?? { add: [], remove: [] };
+    let labels = extra.labels ?? { add: [], remove: [] };
     const out = {
       issue: issue.number,
       action,
@@ -87,6 +96,16 @@ export function planGo({ config, issues, completed = [], completedExternal = [],
       comment: extra.comment ?? null,
       assign: extra.assign ?? null,
     };
+    // An urgent label that is not valid is removed in the decision of the issue, with its own notice. An issue whose
+    // run is in progress is left alone.
+    if (action !== 'skip' && hasUrgentLabel(issue) && !isUrgent(issue)) {
+      labels = { add: labels.add, remove: [...labels.remove, names.urgent] };
+      out.labels = labels;
+      out.notice = {
+        kind: config.trust === 'public' ? 'urgent_denied_maintainer' : 'urgent_denied',
+        data: { issue: issue.number, ...(issue.urgent_by ? { actor: issue.urgent_by } : {}) },
+      };
+    }
     if (action === 'start') Object.assign(out, extra.start);
     decisions.push(out);
   }
@@ -189,15 +208,17 @@ export function planGo({ config, issues, completed = [], completedExternal = [],
       decision(issue, 'block', `waiting for ${blockers.join(', ')}`, {
         labels: moveTo(issue, 'blocked'),
         comment: entering
-          ? { kind: 'blocked_notice', data: { issue: issue.number, title: issue.title, blockers: blockers.join(', ') } }
+          ? { kind: 'blocked_notice', data: { issue: issue.number, title: issue.title, blockers: blockers.join(', '), ...(isUrgent(issue) ? { urgent: true } : {}) } }
           : null,
       });
       return;
     }
 
-    // Gate 3: capacity of the assignee.
+    // Gate 3: capacity of the assignee. A valid urgent label skips this gate and no other.
     const built = assignee ? builtBy.get(assignee) ?? 0 : 0;
-    if (assignee && built >= config.limits.built_unreviewed_per_person) {
+    const overCapacity = Boolean(assignee) && built >= config.limits.built_unreviewed_per_person;
+    const urgent = isUrgent(issue);
+    if (overCapacity && !urgent) {
       decision(issue, 'queue', `${assignee} already has ${built} built issues waiting for review`, {
         labels: moveTo(issue, 'queued'),
         comment: has(issue, 'queued')
@@ -244,6 +265,8 @@ export function planGo({ config, issues, completed = [], completedExternal = [],
         stack: platform.entry.stack,
         path: platform.entry.path,
         targets: platform.entry.targets,
+        // Only when the urgent label let the issue start over the assignee's capacity: the hand-off message says so.
+        ...(overCapacity && urgent ? { urgent: true, built_waiting: built + 1 } : {}),
       },
     });
   });

package/scripts/lib/preflight.mjs

@@ -27,7 +27,7 @@ function checkConfig({ readConfig }) {
 
 function checkOpenspec({ run }) {
   const r = run('openspec', ['--version']);
-  return r.status === 0 ? pass('openspec') : fail('openspec', 'the OpenSpec command line does not run', 'run /relevo:doctor');
+  return r.status === 0 ? pass('openspec') : fail('openspec', 'the OpenSpec command line does not run. Stop here: do not go on from memory and do not write anything under openspec/changes/ by hand', 'install it with `npm install --global @fission-ai/openspec` (Node.js 20.19 or newer), or run /relevo:doctor');
 }
 
 function checkOpenspecRoot({ run }) {

package/scripts/lib/review-adapters.mjs

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

package/scripts/lib/review-brief.mjs

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

package/scripts/lib/review-events.mjs

@@ -16,8 +16,11 @@ function summarise(body, es) {
   return text.length > SUMMARY_LENGTH ? `${text.slice(0, SUMMARY_LENGTH)}…` : text;
 }
 
-/** Returns { action, labels: { add, remove }, comment } or null when the event changes nothing. */
-export function planReviewEvent({ config, event, pr, issue }) {
+/**
+ * Returns { action, labels: { add, remove }, comment } or null when the event changes nothing.
+ * shipWorkflow: the ship workflow is installed on the default branch, so the approval also names its label.
+ */
+export function planReviewEvent({ config, event, pr, issue, shipWorkflow = false }) {
   if (config.review.mode === 'none') return null;
   const names = resolveLabelNames(config.labels);
   const has = (key) => issue.labels.includes(names[key]);
@@ -49,7 +52,7 @@ export function planReviewEvent({ config, event, pr, issue }) {
     return {
       action: 'approved',
       labels: { add: [], remove: [] },
-      comment: { kind: 'approved', data: { recipient, issue: issue.number, reviewer: event.reviewer, pr: pr.url } },
+      comment: { kind: 'approved', data: { recipient, issue: issue.number, reviewer: event.reviewer, pr: pr.url, ...(shipWorkflow ? { ship_label: names.ship } : {}) } },
     };
   }
   return null;