@elalfner/relevo 0.8.0 → 0.9.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "relevo",
   "displayName": "Relevo",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "description": "An automatic issue-to-merge workflow where an agent builds and people verify.",
   "author": {
     "name": "Elias Alfaro"

package/README.es.md

@@ -74,6 +74,7 @@ Además, `/relevo:status` (quién espera a quién) y `/relevo:doctor` (comprueba
 
 - [Primeros pasos](docs/get-started.es.md): de cero a tu primer pull request fusionado, paso a paso.
 - [Instalación](docs/install.es.md): qué necesitas y los primeros pasos.
+- [Actualizar](docs/upgrading.es.md): pasar un proyecto a una versión nueva, en el orden correcto.
 - [Cómo funciona](docs/how-it-works.es.md): la idea, y una corrida real de la idea al pull request mergeado.
 - [Comandos](docs/commands.es.md): los nueve comandos, y las skills que usa `think`.
 - [Configuración](docs/configuration.es.md): el archivo `relevo.yml`.

package/README.md

@@ -74,6 +74,7 @@ Plus `/relevo:status` (who is waiting on what) and `/relevo:doctor` (checks your
 
 - [Get started](docs/get-started.md): from nothing to your first merged pull request, step by step.
 - [Install](docs/install.md): what you need and the first steps.
+- [Upgrading](docs/upgrading.md): moving a project to a new version, in the right order.
 - [How it works](docs/how-it-works.md): the idea, and a real run from idea to merged pull request.
 - [Commands](docs/commands.md): the nine commands, and the skills that `think` uses.
 - [Configuration](docs/configuration.md): the `relevo.yml` file.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elalfner/relevo",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "description": "Relevo: an automatic issue-to-merge workflow where an agent builds and people verify.",
   "type": "module",
   "license": "MIT",

package/scripts/doctor.mjs

@@ -1,13 +1,14 @@
 #!/usr/bin/env node
 // Checks that the machine, the repository and GitHub are ready for Relevo. Read-only: it changes nothing.
-//   node scripts/doctor.mjs [--repo owner/name] [--json]
+//   node scripts/doctor.mjs [--repo owner/name] [--all] [--json]
+//   --all lists the checks that passed too; --json always lists every check
 // exit 0: no check failed (warnings allowed)   exit 1: at least one check failed
 
 import { execFileSync } from 'node:child_process';
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { adapterFacts } from './lib/adapters/install.mjs';
-import { gatherFacts, readOnlyGh, renderReport, runChecks } from './lib/doctor.mjs';
+import { exitCode, gatherFacts, readOnlyGh, renderReport, reportHeader, runChecks } from './lib/doctor.mjs';
 
 const arg = (name) => {
   const i = process.argv.indexOf(`--${name}`);
@@ -53,5 +54,5 @@ const facts = gatherFacts({
   repo,
 });
 const results = runChecks(facts);
-console.log(process.argv.includes('--json') ? JSON.stringify(results, null, 2) : renderReport(results));
-process.exit(results.some((x) => x.status === 'fail') ? 1 : 0);
+console.log(process.argv.includes('--json') ? JSON.stringify(results, null, 2) : renderReport(results, { header: reportHeader(facts), all: process.argv.includes('--all') }));
+process.exit(exitCode(results));

package/scripts/init.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 // Plans and applies the repository setup. Usage:
-//   node scripts/init.mjs plan  [--answers answers.json] [--repo owner/name] [--json]
-//   node scripts/init.mjs apply [--answers answers.json] [--repo owner/name] [--skip id,id] [--json]
+//   node scripts/init.mjs plan  [--answers answers.json] [--repo owner/name] [--from version] [--json]
+//   node scripts/init.mjs apply [--answers answers.json] [--repo owner/name] [--from version] [--skip id,id] [--json]
+//   --from names the published version a workflow that differs came from, when none is close enough to tell
 // `plan` changes nothing. `apply` carries out the planned changes except installs (the skill asks first).
 // answers.json: { "members": ["a","b"], "specWriter": "a", "reviewMode": "peer", "language": "en", "platforms": { "app": { "stack": "flutter", "path": ".", "targets": ["android"] } }, "stackProfiles": [] }
 // It never reads or writes the model API key.
@@ -13,6 +14,7 @@ import { dirname, resolve } from 'node:path';
 import { homedir } from 'node:os';
 import { gatherFacts, readOnlyGh, vueWebFacts, WORKFLOW_FILES } from './lib/doctor.mjs';
 import { applyPlan, planInit, renderPlan, skipItems } from './lib/init.mjs';
+import { planUpgrades, publishedTemplates, unifiedDiff } from './lib/workflow-upgrade.mjs';
 
 const arg = (name) => {
   const i = process.argv.indexOf(`--${name}`);
@@ -72,9 +74,26 @@ const current = {
   stackProfiles: Object.fromEntries((answers.stackProfiles ?? []).map((s) => [s, existsSync(`.relevo/stacks/${s}.md`)])),
 };
 
+// A workflow that exists and differs may be updated by a merge with the published templates (asked for lazily: it uses npm).
+const published = publishedTemplates({ exec: (cmd, args) => run(cmd, args) });
+process.on('exit', () => published.cleanup());
+let versions;
+const source = { versions: () => (versions ??= published.versions()), read: published.read };
+const upgrades = (file) => {
+  try {
+    const state = planUpgrades({
+      files: [file], ours: current.workflows, templates: templates.workflows, agentBlocks: templates.agentBlocks,
+      labels: facts.config?.runner?.labels ?? answers.runnerLabels, build: answers.agentBuild ?? 'claude', from: arg('from') ?? null, source,
+    })[file];
+    return state.status === 'update' ? { ...state, diff: unifiedDiff(current.workflows[file], state.text) } : state;
+  } catch (err) {
+    return { status: 'error', message: String(err.message ?? err).split('\n')[0] };
+  }
+};
+
 let items;
 try {
-  items = planInit({ facts, answers, templates, current, admin });
+  items = planInit({ facts, answers, templates, current, admin, upgrades });
 } catch (err) {
   fail(err.message);
 }

package/scripts/lib/cli.mjs

@@ -13,7 +13,7 @@ export const USAGE = [
   '            relevo init [--tools claude,antigravity] [--scope project|machine] [--yes] [--force]',
   '  install   add the marketplace and install the plugin; asks where in a terminal (project by default)',
   '  update    update the marketplace and the plugin (without --scope, the installation of this project), and render again the plugins that init made; --force overwrites files edited by hand',
-  '  doctor    check this repository (the same as /relevo:doctor)',
+  '  doctor    check this repository (the same as /relevo:doctor); --all lists the checks that passed too',
   '  version   print the version of this package',
   '',
   'user: every project of this machine. project: this repository, shared through .claude/settings.json. local: this repository, only you.'
@@ -26,14 +26,16 @@ export function parseArgs(argv) {
   if (!['install', 'update', 'doctor', 'version'].includes(command)) return { error: `unknown command "${command}"` };
   let scope = null;
   let force = false;
+  let all = false;
   for (let i = 0; i < rest.length; i += 1) {
     const arg = rest[i];
     if (arg === '--force' && command === 'update') force = true;
+    else if (arg === '--all' && command === 'doctor') all = true;
     else if (arg === '--scope') { scope = rest[i + 1]; i += 1; } else if (arg.startsWith('--scope=')) scope = arg.slice(8);
     else return { error: `unknown option "${arg}"` };
   }
   if (scope !== null && !SCOPES.includes(scope)) return { error: `the scope must be one of ${SCOPES.join(', ')}` };
-  return force ? { command, scope, force } : { command, scope };
+  return { command, scope, ...(force ? { force } : {}), ...(all ? { all } : {}) };
 }
 
 /** Whether the folder is inside a git work tree; `run` is the injected runner. A missing git counts as no. */
@@ -85,11 +87,11 @@ export function steps(command, scope) {
  * Runs a command. Returns { code, lines }: the lines to print and the exit code. Stops at the first failing step
  * and says which one, so the person knows what was already done.
  */
-export function execute({ command, scope }, { run, has, version, doctorScript, cwd = process.cwd() }) {
+export function execute({ command, scope, all = false }, { run, has, version, doctorScript, cwd = process.cwd() }) {
   const lines = [];
   if (command === 'version') return { code: 0, lines: [version] };
   if (command === 'doctor') {
-    const r = run(process.execPath, [doctorScript]);
+    const r = run(process.execPath, all ? [doctorScript, '--all'] : [doctorScript]);
     return { code: r.code, lines: [r.output.trimEnd()] };
   }
   if (!has('claude')) {

package/scripts/lib/config.mjs

@@ -85,7 +85,7 @@ function checkType(setting, value, errors) {
       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)})` });
+        errors.push({ path, message: `${path} must be a list of runner labels, for example [self-hosted, linux-build] (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() === '')) {

package/scripts/lib/doctor.mjs

@@ -48,6 +48,8 @@ const PLUGIN_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..')
 const pass = (id, message) => ({ id, status: 'pass', message });
 const fail = (id, message, fix) => ({ id, status: 'fail', message, fix });
 const warn = (id, message, fix) => ({ id, status: 'warn', message, fix });
+// Information that asks for nothing: neither a failure nor a warning, and it never changes the exit status.
+const note = (id, message) => ({ id, status: 'note', message });
 
 /** True when `version` (like "22.1.0") is at least `min` (like "20.19"). */
 export function versionAtLeast(version, min) {
@@ -183,6 +185,12 @@ export function gatherFacts(p) {
   const installedRoot = p.pluginRoot ?? PLUGIN_ROOT;
   f.pluginFolders = ['scripts', 'skills', 'agents', 'stacks', 'templates'].filter((d) => tryRun(() => readdirSync(resolve(installedRoot, d)).length > 0, false) !== true);
   f.pluginVersion = tryRun(() => JSON.parse(readFileSync(resolve(installedRoot, '.claude-plugin', 'plugin.json'), 'utf8')).version ?? null, null);
+  // The installations Claude Code knows of: the user scope, and the project or local scope of this repository. null when
+  // `claude` cannot list them. Only the command is read, never Claude Code's own files.
+  const repoTop = tryRun(() => String(p.tool('git', ['rev-parse', '--show-toplevel'])).trim() || null, null);
+  f.installedPlugins = tryRun(() => JSON.parse(String(p.tool('claude', ['plugin', 'list', '--json'])))
+    .filter((e) => String(e.id).startsWith('relevo@') && (e.scope === 'user' || e.projectPath === repoTop))
+    .map((e) => ({ scope: e.scope, version: e.version ?? null })), null);
 
   f.configText = p.exists('relevo.yml') ? p.read('relevo.yml') : null;
   const loaded = f.configText === null ? null : loadConfig(f.configText, profileLookups({ pluginRoot: p.pluginRoot ?? PLUGIN_ROOT, read: readerFor(p, tryRun) }));
@@ -306,6 +314,11 @@ export function gatherFacts(p) {
     WORKFLOW_FILES.forEach((file) => {
       if (typeof texts[file] === 'string') f.pluginPins[file] = (/^\s*RELEVO_VERSION:\s*['"]?([\w.+-]+)['"]?\s*$/m.exec(texts[file]) ?? [])[1] ?? null;
     });
+    // The version of the text each workflow was copied from (null when it has no stamp).
+    f.pluginStamps = {};
+    WORKFLOW_FILES.forEach((file) => {
+      if (typeof texts[file] === 'string') f.pluginStamps[file] = (/^# relevo-template: (\d+\.\d+\.\d+)\s*$/m.exec(texts[file]) ?? [])[1] ?? null;
+    });
     f.hasCi = names.some((n) => /\.ya?ml$/.test(n) && !n.startsWith('relevo-'));
   }
 }
@@ -478,11 +491,11 @@ function executionChecks(f) {
 
   if (mode === 'both') r.push(warn('execution.credential', `both ANTHROPIC_API_KEY and CLAUDE_CODE_OAUTH_TOKEN exist${used ? `; the workflow uses the ${used === 'api_key' ? 'API key' : 'subscription token'}` : ''}`, 'keep only the secret the workflow uses, so that it is clear which account pays'));
   else if (mode === 'api_key') r.push(pass('execution.credential', 'the cloud builds with an API key: run_max_cost is a real ceiling on spending'));
-  else if (mode === 'subscription') r.push(pass('execution.credential', 'the cloud builds with a subscription token: run_max_cost is only a notional ceiling, and the quota is shared with the use of the account that owns the token'));
+  else if (mode === 'subscription') r.push(note('execution.credential', 'the cloud builds with a subscription token: run_max_cost is only a notional ceiling, and the quota is shared with the use of the account that owns the token'));
   else r.push(pass('execution.credential', installed ? 'no model credential: the cloud cannot build (see the warning about the secret)' : 'no model credential and no go workflow: go builds on machines only'));
 
   if (mode === 'subscription' || (mode === 'both' && used === 'subscription')) {
-    r.push(pass('execution.policy', 'reminder: read the current Anthropic terms on automated use of a subscription token (and the README of claude-code-action) before relying on it for a team'));
+    r.push(note('execution.policy', 'reminder: read the current Anthropic terms on automated use of a subscription token (and the README of claude-code-action) before relying on it for a team'));
     if ((f.config?.limits?.concurrent_agents ?? 1) > 1) {
       r.push(warn('execution.concurrency', `limits.concurrent_agents is ${f.config.limits.concurrent_agents} with a subscription, whose quota is shared by every run and by the interactive use of the account`, 'set limits.concurrent_agents to 1'));
     }
@@ -564,7 +577,7 @@ function platformChecks(f) {
     e.targetTools.forEach(({ target, tool, ok }) => {
       const id = `tools.target.${e.name}.${target}`;
       if (tool === '') r.push(pass(id, `target ${target} of ${e.name} needs no extra tool`));
-      else if (tool === 'xcrun' && !f.macos) r.push(pass(id, `target ${target} of ${e.name}: iOS can only be built and reviewed on macOS (a notice, not a problem)`));
+      else if (tool === 'xcrun' && !f.macos) r.push(note(id, `target ${target} of ${e.name}: iOS can only be built and reviewed on macOS`));
       else if (ok) r.push(pass(id, `target ${target} of ${e.name}: ${tool} is installed`));
       else r.push(warn(id, `target ${target} of ${e.name}: ${tool} is not installed; \`review\` needs it for this target`, TOOL_INSTALL[tool] ?? `install ${tool}`));
     });
@@ -622,7 +635,7 @@ export function runChecks(f) {
   // skills that think invokes
   REQUIRED_SKILLS.forEach((name) => {
     const manual = (f.manualOnlySkills ?? []).includes(name);
-    r.push(f.skills[name] ? pass(`skills.${name}`, manual ? `skill ${name} is installed; it is reserved for you, so run /${name} by hand when \`think\` asks (a notice, not a problem)` : `skill ${name} is installed`) : fail(`skills.${name}`, `skill ${name} is not installed; \`think\` needs it`, SKILL_INSTALL[name]));
+    r.push(f.skills[name] ? (manual ? note(`skills.${name}`, `skill ${name} is installed; it is reserved for you, so run /${name} by hand when \`think\` asks`) : pass(`skills.${name}`, `skill ${name} is installed`)) : fail(`skills.${name}`, `skill ${name} is not installed; \`think\` needs it`, SKILL_INSTALL[name]));
   });
 
   // configuration
@@ -688,14 +701,27 @@ export function runChecks(f) {
   } else if (f.secrets.some((n) => ['ANTHROPIC_API_KEY', 'CLAUDE_CODE_OAUTH_TOKEN'].includes(n))) r.push(pass('automation.secret', 'a model credential secret exists'));
   else r.push(warn('automation.secret', 'no ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN secret, so the cloud cannot build: a ready label only leaves a comment that says to run /relevo:go on a machine', 'for the cloud, add one to the repository secrets (init never touches it; for a subscription token remove all whitespace before storing it); for local builds nothing is needed'));
 
+  // One result per cause: the workflows in the same state, with the same status and the same fix, are one result that names them.
+  const groups = new Map();
+  const put = (kind, status, file, what, fix) => {
+    const key = `${kind}|${status}`;
+    const g = groups.get(key) ?? { kind, status, files: [], what, fix };
+    g.files.push(file);
+    groups.set(key, g);
+  };
   Object.entries(f.workflows).forEach(([file, w]) => {
-    const required = REQUIRED_WORKFLOWS.has(file);
-    const bad = (m, fix) => r.push(required ? fail(`automation.workflow.${file}`, m, fix) : warn(`automation.workflow.${file}`, m, fix));
-    if (!w.present && w.local && w.remote === false) bad(`${file} is only in your working copy, not on the default branch, and a workflow only runs from there`, 'commit it and push it to the default branch (through a pull request if the branch is protected)');
-    else if (!w.present) bad(`${file} is not installed`, 'run /relevo:init to copy it into .github/workflows/');
-    else if (w.enabled === false) bad(`${file} is disabled`, 'enable it in the Actions tab');
-    else if (w.enabled === null) r.push(warn(`automation.workflow.${file}`, `${file} is on the default branch but GitHub does not list it yet`, 'check the Actions tab, or run doctor again in a minute'));
-    else r.push(pass(`automation.workflow.${file}`, `${file} is installed and enabled`));
+    const level = REQUIRED_WORKFLOWS.has(file) ? 'fail' : 'warn';
+    if (!w.present && w.local && w.remote === false) put('local-only', level, file, 'only in your working copy, not on the default branch, and a workflow only runs from there', 'commit it and push it to the default branch (through a pull request if the branch is protected)');
+    else if (!w.present) put('missing', level, file, 'not installed', 'run /relevo:init to copy it into .github/workflows/');
+    else if (w.enabled === false) put('disabled', level, file, 'disabled', 'enable it in the Actions tab');
+    else if (w.enabled === null) put('unlisted', 'warn', file, 'on the default branch but GitHub does not list it yet', 'check the Actions tab, or run doctor again in a minute');
+    else put('installed', 'pass', file, 'installed and enabled');
+  });
+  groups.forEach(({ kind, status, files, what, fix }) => {
+    // The same state can be a failure for a required workflow and a warning for an optional one: two results, two ids.
+    const id = files.length === 1 ? `automation.workflow.${files[0]}` : `automation.workflow.${kind}${status === 'warn' && kind !== 'unlisted' ? '-optional' : ''}`;
+    const message = files.length === 1 ? `${files[0]} is ${what}` : `${files.join(', ')} are ${what}`;
+    r.push({ id, status, message, ...(fix ? { fix } : {}) });
   });
   r.push(f.hasCi ? pass('automation.ci', 'an objective CI check exists') : fail('automation.ci', 'no CI workflow other than Relevo\'s was found; QA needs an objective check', 'add a workflow that runs the project\'s analysis and tests on pull requests'));
 
@@ -708,7 +734,10 @@ export function runChecks(f) {
   r.push(...linkChecks(f));
   r.push(...executionChecks(f));
   r.push(...shipChecks(f));
-  if (f.pluginRepoPrivate === true && Array.isArray(f.secrets)) {
+  // The token is for reading the plugin repository, which only a workflow that still loads the plugin through a marketplace
+  // (or clones it, the older layout) does; one that loads it from the pinned package needs none.
+  const readsPluginRepository = Boolean(f.pluginMarketplace) || (f.pluginCheckouts ?? []).length > 0;
+  if (readsPluginRepository && 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'));
   }
@@ -759,7 +788,7 @@ 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. */
+/** The labels written in a `runs-on` line: `[self-hosted, linux-build]` 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;
@@ -776,12 +805,21 @@ function runnerChecks(f) {
   const same = (a, b) => a.length === b.length && [...a].sort().every((l, i) => l === [...b].sort()[i]);
   const r = [];
   let judged = 0;
+  // One result per cause: the files that run on the same other runner are one failure that names all of them.
+  const differing = new Map();
   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 (!other) return;
+    const key = other.join(', ');
+    differing.set(key, [...(differing.get(key) ?? []), file]);
+  });
+  [...differing.entries()].forEach(([labels, files]) => {
+    const names = files.join(', ');
+    const id = differing.size === 1 ? 'automation.runner' : `automation.runner.${labels}`;
+    r.push(fail(id, `${names} ${files.length === 1 ? 'runs' : 'run'} on [${labels}] and relevo.yml says [${wanted.join(', ')}]`, same(wanted, HOSTED_RUNNER) ? `set runner.labels: [${labels}] in relevo.yml if that is the runner you want, or restore runs-on: ubuntu-latest in ${names}` : `change runs-on in ${names} 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(', ')}]`));
@@ -825,7 +863,50 @@ function pluginInstallChecks(f) {
   const unpinned = Object.entries(pins).filter(([file, v]) => v === null && !cloners.includes(file)).map(([file]) => file);
   if (unpinned.length > 0) r.push(fail('automation.plugin-pin', `${unpinned.join(', ')} do not pin the version of the Relevo package`, 'copy the current templates, which set RELEVO_VERSION'));
   const old = f.pluginVersion ? Object.entries(pins).filter(([, v]) => v !== null && v !== f.pluginVersion).map(([file, v]) => `${file} (${v})`) : [];
-  if (old.length > 0) r.push(warn('automation.plugin-version', `${old.join(', ')} pin a different version than the installed plugin (${f.pluginVersion})`, 'to move them, change RELEVO_VERSION to the installed version after reading the changelog'));
+  if (old.length > 0) r.push(warn('automation.plugin-version', `${old.join(', ')} pin a different version than the installed plugin (${f.pluginVersion})`, 'run /relevo:init: it updates a workflow by merging it with the new template and keeps your own changes; or change RELEVO_VERSION by hand after reading the changelog (that moves the scripts, not the text)'));
+  r.push(...versionChecks(f), ...workflowTextChecks(f));
+  return r;
+}
+
+const byVersion = (a, b) => a.split('.').map(Number).reduce((x, n, i) => x || n - Number(b.split('.')[i]), 0);
+
+/**
+ * Which version each part is on, from what can be read here: the plugin in use, each installation `claude` lists and the
+ * pins of the workflows. It is a note, always visible; a warning only when the user and the project scope disagree, with
+ * the command that moves the lagging one. It asks the npm registry nothing.
+ */
+function versionChecks(f) {
+  if (f.installedPlugins === undefined) return [];
+  if (f.installedPlugins === null) return [warn('plugin.versions', 'the installed versions of the plugin could not be read: `claude plugin list --json` failed', 'check that Claude Code is installed (claude --version) and run claude plugin list')];
+  const r = [];
+  const scopes = f.installedPlugins.filter((e) => e.version);
+  const pins = [...new Set(Object.values(f.pluginPins ?? {}).filter(Boolean))].sort(byVersion);
+  const parts = [
+    `plugin in use ${f.pluginVersion ?? 'unknown'}`,
+    scopes.length > 0 ? `installed ${scopes.map((e) => `${e.scope} ${e.version}`).join(', ')}` : 'not installed through Claude Code',
+    pins.length > 0 ? `workflows pin ${pins.join(', ')}` : null,
+  ].filter(Boolean);
+  r.push(note('plugin.versions', `versions: ${parts.join('; ')}`));
+  const distinct = [...new Set(scopes.map((e) => e.version))].sort(byVersion);
+  if (distinct.length > 1) {
+    const newest = distinct.at(-1);
+    const lagging = scopes.filter((e) => e.version !== newest).map((e) => e.scope);
+    r.push(warn('plugin.scopes', `the plugin is on different versions: ${scopes.map((e) => `${e.scope} ${e.version}`).join(', ')}`, `update the lagging scope: ${lagging.map((s) => `claude plugin update relevo@relevo --scope ${s}`).join('; ')}`));
+  }
+  return r;
+}
+
+/** Is the text of each workflow as current as the scripts it runs? The stamp is the version of the text; the pin is the scripts'. */
+function workflowTextChecks(f) {
+  const stamps = f.pluginStamps;
+  if (!stamps) return [];
+  const pins = f.pluginPins ?? {};
+  const unknown = Object.keys(stamps).filter((file) => stamps[file] === null && f.workflows?.[file]?.present);
+  const older = Object.keys(stamps).filter((file) => stamps[file] !== null && pins[file] && byVersion(stamps[file], pins[file]) < 0);
+  const r = [];
+  if (older.length > 0) r.push(warn('automation.workflow-text', `${older.map((file) => `${file} (text ${stamps[file]}, scripts ${pins[file]})`).join(', ')}: the text of the workflow is older than the scripts it runs`, 'run /relevo:init: it updates the workflow by merging it with the new template and keeps your own changes'));
+  if (unknown.length > 0) r.push(warn('automation.workflow-text-unknown', `${unknown.join(', ')} have no # relevo-template: line, so the age of their text is unknown`, 'run /relevo:init: it updates the workflow by merging it with the new template and keeps your own changes'));
+  if (older.length === 0 && unknown.length === 0 && Object.keys(stamps).length > 0) r.push(pass('automation.workflow-text', 'the text of the workflows is as current as the scripts they run'));
   return r;
 }
 
@@ -846,14 +927,41 @@ function adapterChecks(f) {
   });
 }
 
-/** Text report. */
-export function renderReport(results) {
-  const tag = { pass: 'pass', fail: 'FAIL', warn: 'warn' };
-  const lines = results.flatMap((x) => [`[${tag[x.status]}] ${x.message}`, ...(x.fix && x.status !== 'pass' ? [`       fix: ${x.fix}`] : [])]);
-  const failed = results.filter((x) => x.status === 'fail').length;
-  const warned = results.filter((x) => x.status === 'warn').length;
+/** The exit status of `doctor`: 1 when a check failed, 0 otherwise. Warnings and notes never fail it. */
+export function exitCode(results) {
+  return results.some((x) => x.status === 'fail') ? 1 : 0;
+}
+
+const TAG = { pass: 'pass', fail: 'FAIL', warn: 'warn', note: 'note' };
+const lineOf = (x) => [`[${TAG[x.status]}] ${x.message}`, ...(x.fix && (x.status === 'fail' || x.status === 'warn') ? [`       fix: ${x.fix}`] : [])];
+
+/** The first line of the report: what was judged, and where the workflows were read from. */
+export function reportHeader(facts) {
+  if (!facts?.repo || !facts.ghAuth) return 'Relevo doctor: only the local checks ran (no GitHub repository, or not signed in to GitHub)';
+  return `Relevo doctor: ${facts.repo}, workflows read from the ${facts.workflowSource ?? 'working copy'}`;
+}
+
+/**
+ * Text report. By default what needs action comes first (failures, warnings, notes, each with its count) and the checks
+ * that passed are only counted; `all` lists every check in the order it was evaluated. The closing line counts results.
+ */
+export function renderReport(results, { header = null, all = false } = {}) {
+  const by = (status) => results.filter((x) => x.status === status);
+  const failed = by('fail').length;
+  const warned = by('warn').length;
+  const passed = by('pass').length;
+  const lines = header ? [header, ''] : [];
+  if (all) lines.push(...results.flatMap(lineOf));
+  else {
+    [['FAILURES', 'fail'], ['WARNINGS', 'warn'], ['NOTES', 'note']].forEach(([title, status]) => {
+      const group = by(status);
+      if (group.length === 0) return;
+      lines.push(`${title} (${group.length})`, ...group.flatMap(lineOf), '');
+    });
+    if (passed > 0) lines.push(`${passed} check(s) passed; run with --all to list them.`);
+  }
   lines.push('', failed === 0 ? (warned === 0 ? 'All green.' : `No failures, ${warned} warning(s).`) : `${failed} check(s) failed${warned ? `, ${warned} warning(s)` : ''}.`);
-  return lines.join('\n');
+  return lines.join('\n').replace(/\n{3,}/g, '\n\n');
 }
 
 /** Wrap a `gh` client so that it can only read: `doctor` must never change anything. */

package/scripts/lib/init.mjs

@@ -210,10 +210,13 @@ const item = (id, status, description, extra = {}) => ({ id, status, description
  *   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';
@@ -314,9 +317,22 @@ export function planInit({ facts, answers, templates, current, admin }) {
     const shared = file === 'relevo-go.yml' ? credentialLine(templates.workflows[file], credential) : templates.workflows[file];
     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})`));
@@ -358,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');
 }
@@ -411,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/workflow-upgrade.mjs

@@ -0,0 +1,198 @@
+// Updates a workflow of a repository to the current template by a three-way merge. Implements the requirements "Init
+// updates a workflow by a three-way merge", "A merged workflow is written only when clean and confirmed" and "The pin and
+// the stamp are set, not merged" of openspec/specs/init-doctor/spec.md.
+//
+//   base    the published template closest to the file (the pin is no guide: a person can raise it by hand)
+//   ours    the file as it is
+//   theirs  the current template, rendered with the runner and the agent of the repository, so that a person's runner
+//           or agent block is the same on both sides and is not reported as a change
+//
+// The pin and the stamp are not merged: both are set to the base's value in the file before the merge (otherwise the
+// person's own pin conflicts with every release) and to the current value after it. Nothing here writes a workflow: the
+// caller decides, and a conflict gives back text that must not be written.
+
+import { execFileSync } from 'node:child_process';
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { agentWorkflow } from './agent-workflow.mjs';
+import { runnerLine } from './init.mjs';
+
+const PIN_RE = /^(\s*RELEVO_VERSION:\s*)(['"]?)([\w.+-]+)\2[ \t]*$/m;
+const STAMP_RE = /^# relevo-template: (\d+\.\d+\.\d+)[ \t]*$/m;
+const MARKERS = ['credential', 'agent-step'];
+
+export const pinOf = (text) => PIN_RE.exec(text)?.[3] ?? null;
+export const stampOf = (text) => STAMP_RE.exec(text)?.[1] ?? null;
+const setPin = (text, version) => text.replace(PIN_RE, (_, head, quote) => `${head}${quote}${version}${quote}`);
+const setStamp = (text, version) => text.replace(STAMP_RE, `# relevo-template: ${version}`);
+
+/** How many lines two workflows do not share (as multisets), with the pin and the stamp set aside. */
+export function distance(a, b) {
+  const lines = (t) => setStamp(setPin(t, 'X'), 'X').split('\n');
+  const count = new Map();
+  lines(a).forEach((l) => count.set(l, (count.get(l) ?? 0) + 1));
+  lines(b).forEach((l) => count.set(l, (count.get(l) ?? 0) - 1));
+  return [...count.values()].reduce((sum, n) => sum + Math.abs(n), 0);
+}
+
+/**
+ * The candidate whose text is closest to the file; the newest among equals. `from` names the base instead. null when no
+ * candidate is close enough: more than half of the lines of the file different is not a version of this template.
+ */
+export function chooseBase(file, candidates, { from = null } = {}) {
+  if (from !== null) {
+    const named = candidates.find((c) => c.version === from);
+    return named ? { ...named, distance: distance(file, named.rendered) } : null;
+  }
+  const ranked = candidates.map((c) => ({ ...c, distance: distance(file, c.rendered) }))
+    .sort((a, b) => a.distance - b.distance || compareVersions(b.version, a.version));
+  const limit = Math.max(20, Math.floor(file.split('\n').length / 2));
+  return ranked.length > 0 && ranked[0].distance <= limit ? ranked[0] : null;
+}
+
+const compareVersions = (a, b) => a.split('.').map(Number).reduce((r, n, i) => r || n - Number(b.split('.')[i]), 0);
+
+/** `git merge-file -p`: the exit status is the number of conflicts (1 to 127); anything else is an error. */
+export function gitMergeFile(ours, base, theirs) {
+  const dir = mkdtempSync(join(tmpdir(), 'relevo-merge-'));
+  try {
+    const paths = [['ours', ours], ['base', base], ['theirs', theirs]].map(([name, text]) => {
+      const path = join(dir, name);
+      writeFileSync(path, text);
+      return path;
+    });
+    try {
+      return { status: 0, stdout: execFileSync('git', ['merge-file', '-p', ...paths], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }) };
+    } catch (err) {
+      return { status: err.status ?? 255, stdout: String(err.stdout ?? '') };
+    }
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/** The blocks of conflict of a merged text: [{ yours, theirs }]. */
+export function conflictsOf(text) {
+  const out = [];
+  const re = /^<<<<<<<[^\n]*\n([\s\S]*?)^=======\n([\s\S]*?)^>>>>>>>[^\n]*\n/gm;
+  let m;
+  while ((m = re.exec(text)) !== null) out.push({ yours: m[1].trimEnd(), theirs: m[2].trimEnd() });
+  return out;
+}
+
+/** A merge that lost what other code depends on is not safe to write, whatever git says. */
+function structureProblem(merged, current) {
+  if ((merged.match(/^\s*RELEVO_VERSION:/gm) ?? []).length !== 1) return 'it does not have exactly one RELEVO_VERSION';
+  if (stampOf(current) !== null && (merged.match(/^# relevo-template:/gm) ?? []).length !== 1) return 'it does not have exactly one stamp';
+  for (const name of MARKERS) {
+    const count = (t, kind) => (t.match(new RegExp(`^\\s*# relevo:${name} ${kind}\\s*$`, 'gm')) ?? []).length;
+    for (const kind of ['begin', 'end']) {
+      if (count(merged, kind) !== count(current, kind)) return `the block "${name}" (${kind}) is not as in the template`;
+    }
+  }
+  return null;
+}
+
+/**
+ * The state of one workflow against the current template.
+ *   { status: 'current' }                        nothing to update
+ *   { status: 'update', from, to, text }         a clean merge; `text` is what to write
+ *   { status: 'conflict', from, conflicts }      lines both sides changed, or a merge that is not safe; write nothing
+ *   { status: 'nobase' }                         no published template is close to the file
+ *   { status: 'error', message }                 git failed
+ * `candidates` are [{ version, template, blocks }] (the raw template of a published version and its agent blocks, or
+ * null). `render` turns a raw template into what `init` would write for this repository.
+ */
+export function upgradeWorkflow({ ours, current, candidates, from = null, render, merge = gitMergeFile }) {
+  const theirs = render(current.template, current.blocks);
+  const rendered = candidates.map((c) => ({ ...c, rendered: render(c.template, c.blocks) }));
+  const base = chooseBase(ours, rendered, { from });
+  if (!base) return { status: 'nobase' };
+
+  let prepared = ours;
+  if (pinOf(prepared) !== null && pinOf(base.rendered) !== null) prepared = setPin(prepared, pinOf(base.rendered));
+  if (stampOf(prepared) !== null && stampOf(base.rendered) !== null) prepared = setStamp(prepared, stampOf(base.rendered));
+
+  const result = merge(prepared, base.rendered, theirs);
+  if (result.status === 0) {
+    let text = result.stdout;
+    if (pinOf(theirs) !== null) text = setPin(text, pinOf(theirs));
+    if (stampOf(theirs) !== null && stampOf(text) !== null) text = setStamp(text, stampOf(theirs));
+    const problem = structureProblem(text, theirs);
+    if (problem) return { status: 'conflict', from: base.version, conflicts: [], message: `the merge is not safe: ${problem}` };
+    if (text === ours) return { status: 'current' };
+    return { status: 'update', from: base.version, to: stampOf(theirs) ?? pinOf(theirs), text };
+  }
+  if (result.status >= 1 && result.status <= 127) return { status: 'conflict', from: base.version, conflicts: conflictsOf(result.stdout) };
+  return { status: 'error', message: 'git merge-file failed' };
+}
+
+/** The published versions of the package and their templates, fetched with `npm`; `exec(cmd, args)` returns stdout. */
+export function publishedTemplates({ exec, tmp = mkdtempSync(join(tmpdir(), 'relevo-published-')), pkg = '@elalfner/relevo' }) {
+  const unpacked = new Map();
+  const dirOf = (version) => {
+    if (!unpacked.has(version)) {
+      const dir = join(tmp, version);
+      mkdirSync(dir, { recursive: true });
+      try {
+        exec('npm', ['pack', `${pkg}@${version}`, '--silent', '--pack-destination', dir]);
+        const tarball = join(dir, `${pkg.replace(/^@/, '').replace('/', '-')}-${version}.tgz`);
+        exec('tar', ['-xzf', tarball, '-C', dir]);
+        unpacked.set(version, join(dir, 'package'));
+      } catch {
+        unpacked.set(version, null);
+      }
+    }
+    return unpacked.get(version);
+  };
+  return {
+    versions: () => JSON.parse(exec('npm', ['view', pkg, 'versions', '--json'])).filter((v) => /^\d+\.\d+\.\d+$/.test(v) && v !== '0.0.0'),
+    read: (version, path) => {
+      const dir = dirOf(version);
+      if (dir === null) return null;
+      try {
+        return readFileSync(join(dir, path), 'utf8');
+      } catch {
+        return null;
+      }
+    },
+    cleanup: () => rmSync(tmp, { recursive: true, force: true }),
+  };
+}
+
+/**
+ * The state of each workflow of the repository that exists and differs from what `init` would write. `ours` and
+ * `templates` map a file name to its text; `repo` brings `runnerLabels` and `build`; `source` is `publishedTemplates`.
+ */
+export function planUpgrades({ files, ours, templates, agentBlocks, labels, build, from = null, source, merge }) {
+  const render = (template, blocks) => runnerLine(agentWorkflow(template, build, blocks), labels);
+  const versions = files.some((f) => ours[f] != null) ? source.versions() : [];
+  const out = {};
+  files.filter((f) => ours[f] != null).forEach((file) => {
+    const candidates = versions.map((version) => {
+      const template = source.read(version, `templates/workflows/${file}`);
+      return template === null ? null : { version, template, blocks: build === 'claude' ? null : source.read(version, `templates/agents/${build}-step.yml`) };
+    }).filter(Boolean);
+    out[file] = upgradeWorkflow({ ours: ours[file], current: { template: templates[file], blocks: agentBlocks }, candidates, from, render, merge });
+  });
+  return out;
+}
+
+/** A readable unified difference between the file and its update, for the plan. */
+export function unifiedDiff(before, after) {
+  const dir = mkdtempSync(join(tmpdir(), 'relevo-diff-'));
+  try {
+    const a = join(dir, 'before');
+    const b = join(dir, 'after');
+    writeFileSync(a, before);
+    writeFileSync(b, after);
+    try {
+      return execFileSync('git', ['diff', '--no-index', '--no-color', '--unified=2', a, b], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+    } catch (err) {
+      return String(err.stdout ?? '').split('\n').slice(4).join('\n');
+    }
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}

package/skills/doctor/SKILL.md

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

package/skills/init/SKILL.md

@@ -15,7 +15,8 @@ Scripts live in `${CLAUDE_PLUGIN_ROOT}/scripts/`. Run them with `node`. They hol
 
 - Never read, write, print or ask for the model API key or any token. Tell the person to add it to the repository secrets themselves.
 - Never apply a change before the person says yes to the plan, and never install anything before they confirm that exact command.
-- Never overwrite a workflow or `relevo.yml` that already exists and differs; report it. A `relevo.yml` with the older `platform: flutter-android` line stays as it is.
+- Never overwrite `relevo.yml` that already exists and differs; report it. A `relevo.yml` with the older `platform: flutter-android` line stays as it is.
+- A workflow that already exists and differs is reported, unless the plan offers to update it: that line (`Update .github/workflows/<file> from A to B, keeping your own changes`) means a three-way merge with the published templates came out clean, and it is written only with the person's yes to the plan. A workflow whose merge conflicts or has no close published version is left as it is; never edit it to resolve the conflict yourself.
 - Never create files under `openspec/` by hand. If there is no OpenSpec root, tell the person to run `openspec init`.
 - Never commit or push. The new files are left for the person to commit.
 - Never put credentials in `relevo.yml` or in the answers file.
@@ -35,7 +36,7 @@ If `relevo.yml` already exists and is valid, skip this step. Otherwise ask, in s
 - the language of the hand-off messages (`en` or `es`);
 - the platforms: for each one a name, its stack (look at the project to propose one: the profiles in `${CLAUDE_PLUGIN_ROOT}/stacks/` are the stacks Relevo ships with: `flutter`, `vue`, `laravel` and `supabase`), the folder where it lives (`.` for a repository with one platform, `apps/web` in a monorepo) and, for a stack that has targets, which ones (for Flutter: `android`, `ios`, `web`; for Vue: `web`; Laravel and Supabase have none). Several platforms in one repository are written down, but `go` builds only a repository with one for now;
 - where `go` builds: in the cloud, on each person's machine, or both (the default), and, for the cloud, with an API key from the Anthropic Console (the default) or with a subscription token. A subscription's quota is shared by every run and by the interactive use of the account, so `init` sets `limits.concurrent_agents` to 1 for it. Nothing about this goes in `relevo.yml` apart from that number: the installed workflows, the secret that exists and the repository variable `RELEVO_CLOUD_GO` (`off` pauses the cloud at once, with no pull request) decide it. Whatever the answer, the ship workflow (`relevo-ship.yml`) is added: it ships an approved issue when a person applies the `relevo:ship` label, runs no model and needs no model credential, and the repository variable `RELEVO_CLOUD_SHIP` (`off`) pauses it;
-- whether the repository runs its GitHub Actions on a self-hosted runner. Ask nothing more when the answer is no: the workflows run on `ubuntu-latest` and `relevo.yml` gets no `runner` key. On a yes, ask for the runner's labels (for example `self-hosted` and `Front`): they become `runner.labels` in `relevo.yml` and the `runs-on` of every workflow `init` adds. Say that Relevo assumes a self-hosted runner keeps its files between jobs, whatever the person says about it, and that the agent's code runs with the permissions of the runner's user; do not ask whether the runner is ephemeral;
+- whether the repository runs its GitHub Actions on a self-hosted runner. Ask nothing more when the answer is no: the workflows run on `ubuntu-latest` and `relevo.yml` gets no `runner` key. On a yes, ask for the runner's labels (for example `self-hosted` and `linux-build`): they become `runner.labels` in `relevo.yml` and the `runs-on` of every workflow `init` adds. Say that Relevo assumes a self-hosted runner keeps its files between jobs, whatever the person says about it, and that the agent's code runs with the permissions of the runner's user; do not ask whether the runner is ephemeral;
 - the repositories this one depends on, if any (`owner/repo`, for example the back end of a front end): they are written to `links`, the closed list that `Depends-on: owner/repo#N` is checked against;
 - whether to create a commented `.relevo/stacks/<stack>.md` for each stack, where the project can add its own hygiene to the plugin's profile (optional; `init` creates it but does not commit it: it is left for the person to commit, because the cloud and teammates read it from git);
 - which agent builds in the cloud, only when the person says they use Antigravity: `claude` (the default) or `antigravity`. With `antigravity` the model key is `GEMINI_API_KEY`, a key made only for Relevo in its own Google Cloud project with a quota, and the limit asked below is a number of tokens (`limits.run_max_tokens`) because that agent has no cost limit; `docs/security.md` says what else it cannot enforce;
@@ -49,7 +50,7 @@ Write the answers as JSON to a temporary file **outside the repository**, with t
 node ${CLAUDE_PLUGIN_ROOT}/scripts/init.mjs plan --answers <answers file>
 ```
 
-Show it as it is. Each line says whether it is already `ok`, will be done, `differs` (exists, left alone) or must be done `by hand`. Then ask one direct yes/no question: apply the changes marked "will do"? Wait for the answer.
+Show it as it is. Each line says whether it is already `ok`, will be done, `differs` (exists, left alone) or must be done `by hand`. A workflow update shows its difference under the line, and a conflict shows both versions. When a line says that no published version is close to a workflow, ask which version of Relevo it was copied from and run the plan again with `--from <version>`. Then ask one direct yes/no question: apply the changes marked "will do"? Wait for the answer.
 
 ### 4. Offer the installs, one at a time
 

package/templates/relevo.yml

@@ -39,7 +39,7 @@ limits:
   run_max_cost: 5                  # REQUIRED: US dollars per unattended run; choose your own
 
 # runner:                            # where the Relevo workflows run; leave it out for GitHub-hosted (ubuntu-latest)
-#   labels: [self-hosted, Front]     # a self-hosted runner is assumed to persist between jobs (docs/execution.md)
+#   labels: [self-hosted, linux-build]     # a self-hosted runner is assumed to persist between jobs (docs/execution.md)
 
 qa:
   retries: 1                       # developer attempts after QA rejects

package/templates/workflows/relevo-digest.yml

@@ -1,3 +1,4 @@
+# relevo-template: 0.9.1
 # Relevo: posts one digest per working day, as a comment on the issue named by digest.issue in relevo.yml.
 # It lists who is waiting on what and the alerts, and posts nothing when nothing is waiting.
 # Subscribe your chat tool to that issue to receive it. Copy to .github/workflows/relevo-digest.yml.
@@ -13,7 +14,7 @@ name: relevo-digest
 # The version of @elalfner/relevo whose scripts this workflow runs. The plugin's templates carry the version they
 # were released with, and `/relevo:init` reports this file as different when it is older; change it by hand to update.
 env:
-  RELEVO_VERSION: '0.8.0'
+  RELEVO_VERSION: '0.9.1'
 
 on:
   schedule:

package/templates/workflows/relevo-go.yml

@@ -1,3 +1,4 @@
+# relevo-template: 0.9.1
 # Relevo: builds an issue when someone with write access labels it `relevo:ready`.
 # Copy to .github/workflows/relevo-go.yml. If you renamed the ready label in relevo.yml, change it below too.
 #
@@ -19,7 +20,7 @@ name: relevo-go
 # The version of @elalfner/relevo whose scripts this workflow runs. The plugin's templates carry the version they
 # were released with, and `/relevo:init` reports this file as different when it is older; change it by hand to update.
 env:
-  RELEVO_VERSION: '0.8.0'
+  RELEVO_VERSION: '0.9.1'
   # The version of OpenSpec that the job installs for itself.
   OPENSPEC_VERSION: '1.14.3'
 
@@ -183,7 +184,8 @@ jobs:
       # Stops before the agent, without spending a model turn, when the runner lacks a tool that the profile of the
       # platform lists (the Flutter SDK, PHP and Composer, ...): otherwise the developer writes the code and QA only
       # finds out at the end, after a full run. The package is unpacked outside the workspace on purpose: the agent needs
-      # a clean working tree. If you renamed the labels in relevo.yml, change the names below too.
+      # a clean working tree. The agent loads its plugin from this same folder (--plugin-dir), so a package without
+      # .claude-plugin/plugin.json stops the run here too. If you renamed the labels in relevo.yml, change the names below too.
       - name: Check the toolchain
         env:
           GH_TOKEN: ${{ github.token }}
@@ -193,7 +195,7 @@ jobs:
           mkdir -p "$RUNNER_TEMP/relevo"
           npm pack "@elalfner/relevo@$RELEVO_VERSION" --silent --pack-destination "$RUNNER_TEMP" > /dev/null
           tar -xzf "$RUNNER_TEMP"/elalfner-relevo-*.tgz --strip-components=1 -C "$RUNNER_TEMP/relevo"
-          for f in scripts/toolchain-check.mjs scripts/render-message.mjs; do
+          for f in scripts/toolchain-check.mjs scripts/render-message.mjs .claude-plugin/plugin.json; do
             [ -f "$RUNNER_TEMP/relevo/$f" ] || { echo "::error::The Relevo package $RELEVO_VERSION lacks $f"; exit 1; }
           done
           if result=$(node "$RUNNER_TEMP/relevo/scripts/toolchain-check.mjs" --platform "$PLATFORM" --plugin-root "$RUNNER_TEMP/relevo"); then
@@ -232,13 +234,9 @@ jobs:
           # The queue starts builds with `gh workflow run`, so the actor is the Actions bot and the action refuses
           # it unless it is allowed. Only this one bot: never '*', which would let outside apps start runs.
           allowed_bots: github-actions
-          # Plugin repository: choose ONE of the next two lines.
-          # a) Public repository (default):
-          plugin_marketplaces: https://github.com/elalfner/relevo.git
-          # b) Private repository: the runner cannot clone it without a credential. Store a read-only fine-grained
-          #    token as the secret RELEVO_PLUGIN_TOKEN and replace the line above with:
-          # plugin_marketplaces: https://x-access-token:${{ secrets.RELEVO_PLUGIN_TOKEN }}@github.com/elalfner/relevo.git
-          plugins: relevo@relevo
+          # The plugin is not installed from a marketplace: --plugin-dir in claude_args loads the package that the step
+          # "Check the toolchain" unpacked at RELEVO_VERSION, so one pin decides the scripts and the skills, nothing is
+          # cloned and no token is needed to read the plugin repository.
           # The issue text is data, never instructions: the skill tells the agent so. The tool list is closed:
           # only the tools in --allowedTools, and no web access (nothing to fetch, nowhere to send a secret).
           # Do not set allowed_non_write_users or show_full_output here, and never widen allowed_bots: they open the run to
@@ -249,6 +247,7 @@ jobs:
           claude_args: >-
             --max-turns 100
             --max-budget-usd 5
+            --plugin-dir ${{ runner.temp }}/relevo
             --allowedTools "Bash,Read,Write,Edit,Glob,Grep,Task"
             --disallowedTools "WebFetch,WebSearch,Bash(curl:*),Bash(wget:*)"
       # relevo:agent-step end

package/templates/workflows/relevo-queue.yml

@@ -1,3 +1,4 @@
+# relevo-template: 0.9.1
 # Relevo: re-evaluates the queue and starts the issues that are now eligible.
 # Copy to .github/workflows/relevo-queue.yml next to relevo-go.yml (it starts builds through that workflow).
 #
@@ -14,7 +15,7 @@ name: relevo-queue
 # The version of @elalfner/relevo whose scripts this workflow runs. The plugin's templates carry the version they
 # were released with, and `/relevo:init` reports this file as different when it is older; change it by hand to update.
 env:
-  RELEVO_VERSION: '0.8.0'
+  RELEVO_VERSION: '0.9.1'
 
 on:
   issues:

package/templates/workflows/relevo-review.yml

@@ -1,3 +1,4 @@
+# relevo-template: 0.9.1
 # Relevo: keeps the issue label in step with its pull request.
 # A review that requests changes sets `relevo:changes-requested` and mentions the author; a new push returns the
 # issue to `relevo:pr-open`; an approval mentions the person who will run /relevo:ship.
@@ -14,7 +15,7 @@ name: relevo-review
 # The version of @elalfner/relevo whose scripts this workflow runs. The plugin's templates carry the version they
 # were released with, and `/relevo:init` reports this file as different when it is older; change it by hand to update.
 env:
-  RELEVO_VERSION: '0.8.0'
+  RELEVO_VERSION: '0.9.1'
 
 on:
   pull_request_review:

package/templates/workflows/relevo-ship.yml

@@ -1,3 +1,4 @@
+# relevo-template: 0.9.1
 # Relevo: ships an issue when a person applies the `relevo:ship` label to it.
 # Copy to .github/workflows/relevo-ship.yml. If you renamed the ship label in relevo.yml, change it below too.
 #
@@ -26,7 +27,7 @@ name: relevo-ship
 # The version of @elalfner/relevo whose scripts this workflow runs. The plugin's templates carry the version they
 # were released with, and `/relevo:init` reports this file as different when it is older; change it by hand to update.
 env:
-  RELEVO_VERSION: '0.8.0'
+  RELEVO_VERSION: '0.9.1'
   # The version of OpenSpec that the job installs for itself.
   OPENSPEC_VERSION: '1.14.3'
 

package/templates/workflows/relevo-sla.yml

@@ -1,3 +1,4 @@
+# relevo-template: 0.9.1
 # Relevo: reminds the reviewer when a pull request waits longer than limits.review_sla_hours, and escalates
 # to the spec writer (adding the needs-reviewer label) after the same time again.
 # Copy to .github/workflows/relevo-sla.yml. Needs a relevo.yml at the repository root.
@@ -12,7 +13,7 @@ name: relevo-sla
 # The version of @elalfner/relevo whose scripts this workflow runs. The plugin's templates carry the version they
 # were released with, and `/relevo:init` reports this file as different when it is older; change it by hand to update.
 env:
-  RELEVO_VERSION: '0.8.0'
+  RELEVO_VERSION: '0.9.1'
 
 on:
   schedule: