@elalfner/relevo 0.7.0 → 0.9.0

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,14 +206,17 @@ 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
+ *   upgrades   { file: state } or a function file -> state (asked only for a workflow that exists and differs), from
+ *              `planUpgrades`: a clean merge becomes an
+ *              update to confirm, a conflict or a missing base stays `differs` and says why
  * Items have status: ok (nothing to do), todo (init will do it), differs (exists but differs: reported, never
  * overwritten), manual (the person must do it).
  */
-export function planInit({ facts, answers, templates, current, admin }) {
+export function planInit({ facts, answers, templates, current, admin, upgrades = {} }) {
   const items = [];
   const base = facts.config?.branches?.base ?? answers.base ?? 'dev';
   const release = facts.config?.branches?.release ?? answers.release ?? 'main';
@@ -199,11 +241,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,15 +309,30 @@ 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;
+    // The state of the update is asked for only when the file exists and differs: it may need the network.
+    const upgrade = () => (typeof upgrades === 'function' ? upgrades(file) : upgrades[file]);
+    const up = have !== null && have !== wanted ? upgrade() : undefined;
     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`));
-    else {
+    else if (up?.status === 'update') {
+      items.push(item(`workflow.${file}`, 'todo', `Update .github/workflows/${file} from ${up.from} to ${up.to}, keeping your own changes`, { path: `.github/workflows/${file}`, content: up.text, diff: up.diff }));
+    } else if (up?.status === 'current') items.push(item(`workflow.${file}`, 'ok', `.github/workflows/${file} is up to date (with your own changes)`));
+    else if (up?.status === 'conflict') {
+      const where = up.conflicts.length > 0 ? `${up.conflicts.length} place(s) changed by you and by the new template` : up.message;
+      items.push(item(`workflow.${file}`, 'differs', `.github/workflows/${file} differs from the template and cannot be updated without a conflict (${where}); it is left as it is`, { conflicts: up.conflicts }));
+    } else if (up?.status === 'nobase') {
+      items.push(item(`workflow.${file}`, 'differs', `.github/workflows/${file} differs from the template and no published version is close to it; it is left as it is (name the version it came from with --from <version>)`));
+    } else if (up?.status === 'error') {
+      items.push(item(`workflow.${file}`, 'differs', `.github/workflows/${file} differs from the template and could not be checked for an update (${up.message}); it is left as it is`));
+    } else {
       // The cloud build only passes QA when the build job installs the toolchain of the stack, which the template does.
       const toolchain = file === 'relevo-go.yml' ? '; check that its build job installs the toolchain of your stacks, as the template does for Flutter and Laravel' : '';
       items.push(item(`workflow.${file}`, 'differs', `.github/workflows/${file} exists and differs from the template; it is left as it is (compare it by hand${toolchain})`));
@@ -298,7 +374,12 @@ export function planInit({ facts, answers, templates, current, admin }) {
 export function renderPlan(items) {
   const tag = { ok: 'ok     ', todo: 'will do', differs: 'differs', manual: 'by hand' };
   const todo = items.filter((i) => i.status === 'todo').length;
-  const lines = items.map((i) => `[${tag[i.status]}] ${i.description}${i.install ? ` (${i.command})` : ''}`);
+  const indent = (text) => text.split('\n').map((l) => `          ${l}`);
+  const lines = items.flatMap((i) => [
+    `[${tag[i.status]}] ${i.description}${i.install ? ` (${i.command})` : ''}`,
+    ...(i.diff ? indent(i.diff.trimEnd()) : []),
+    ...(i.conflicts ?? []).flatMap((c) => [indent('yours:'), indent(c.yours), indent('the new template:'), indent(c.theirs)].flat()),
+  ]);
   lines.push('', todo === 0 ? 'Nothing to do.' : `${todo} change(s) to make.`);
   return lines.join('\n');
 }
@@ -351,6 +432,8 @@ export function applyPlan(items, { repo, io }) {
           it.paths.forEach((p) => io.write(p, ''));
           break;
         default:
+          // A workflow is written only under .github/workflows/, whatever the item says.
+          if (it.id.startsWith('workflow.') && !/^\.github\/workflows\/[\w.-]+\.yml$/.test(it.path)) throw new Error(`refusing to write ${it.path}: a workflow goes under .github/workflows/`);
           if (it.id.startsWith('workflow.') || it.id.startsWith('stack-profile.')) io.write(it.path, it.content);
           else throw new Error(`no way to apply "${it.id}"`);
       }

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

package/scripts/lib/ship-github.mjs

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