@elalfner/relevo 0.3.1 → 0.4.0

package/.claude-plugin/plugin.json

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

package/README.es.md

@@ -26,7 +26,7 @@ claude plugin install relevo@relevo
 
 Eso lo instala para todos los proyectos de la máquina. Para instalarlo solo en un repositorio, añade `--scope project` al segundo comando (compartido con el equipo en `.claude/settings.json`) o `--scope local` (solo para ti). Solo se instala el plugin (scripts, skills, agents, perfiles de stack y plantillas); la documentación está en línea.
 
-Un atajo, si prefieres un solo comando: `npm install -g @elalfner/relevo` te da `relevo install` (o `relevo install --scope project`), `relevo update` y `relevo doctor`.
+Un atajo, si prefieres un solo comando: `npm install -g @elalfner/relevo` te da `relevo install`, que pregunta dónde instalarlo (el proyecto viene preseleccionado; `relevo install --scope project` se salta la pregunta), `relevo update` y `relevo doctor`.
 
 ```bash
 npm install -g @elalfner/relevo

package/README.md

@@ -26,7 +26,7 @@ claude plugin install relevo@relevo
 
 That installs it for every project of the machine. To install it for one repository only, add `--scope project` to the second command (shared with the team through `.claude/settings.json`) or `--scope local` (only you). Only the plugin is installed (scripts, skills, agents, stack profiles and templates); the documentation is online.
 
-A shortcut, if you prefer one command: `npm install -g @elalfner/relevo` gives you `relevo install` (or `relevo install --scope project`), `relevo update` and `relevo doctor`.
+A shortcut, if you prefer one command: `npm install -g @elalfner/relevo` gives you `relevo install`, which asks where to install it (the project is preselected; `relevo install --scope project` skips the question), `relevo update` and `relevo doctor`.
 
 ```bash
 npm install -g @elalfner/relevo

package/package.json

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

package/scripts/cli.mjs

@@ -1,9 +1,11 @@
 #!/usr/bin/env node
-// relevo install | update | doctor | version. See scripts/lib/cli.mjs.
+// relevo install | update | doctor | version. See scripts/lib/cli.mjs. `install` without --scope asks where, in a
+// terminal, with the project preselected.
 import { spawnSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
-import { USAGE, execute, parseArgs } from './lib/cli.mjs';
+import { USAGE, execute, isInsideGitRepo, parseArgs, resolveScope, scopeChoices } from './lib/cli.mjs';
+import { select } from './lib/select.mjs';
 
 const here = (p) => fileURLToPath(new URL(p, import.meta.url));
 const parsed = parseArgs(process.argv.slice(2));
@@ -23,6 +25,29 @@ const run = (cmd, args) => {
 const has = (cmd) => spawnSync(cmd, ['--version'], { encoding: 'utf8' }).error === undefined;
 const version = JSON.parse(readFileSync(here('../package.json'), 'utf8')).version;
 
-const { code, lines } = execute(parsed, { run, has, version, doctorScript: here('./doctor.mjs') });
+let { scope } = parsed;
+if (parsed.command === 'install' && has('claude')) {
+  const inRepo = isInsideGitRepo(run);
+  const resolved = resolveScope({ given: scope, interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY), inRepo });
+  if (resolved.ask) {
+    const choices = scopeChoices({ cwd: process.cwd(), inRepo });
+    scope = await select({
+      title: 'Where should Relevo be installed?',
+      choices,
+      defaultIndex: Math.max(0, choices.findIndex((c) => c.value === resolved.preferred)),
+      input: process.stdin,
+      output: process.stdout
+    });
+    if (scope === null) {
+      process.stdout.write('Cancelled: nothing was installed.\n');
+      process.exit(130);
+    }
+  } else {
+    scope = resolved.scope;
+    if (resolved.reason) process.stdout.write(`relevo: ${resolved.reason}.\n`);
+  }
+}
+
+const { code, lines } = execute({ command: parsed.command, scope }, { run, has, version, doctorScript: here('./doctor.mjs'), cwd: process.cwd() });
 process.stdout.write(`${lines.join('\n')}\n`);
 process.exit(code);

package/scripts/lib/cli.mjs

@@ -9,8 +9,8 @@ export const SCOPES = ['user', 'project', 'local'];
 export const USAGE = [
   'usage: relevo <command> [--scope user|project|local]',
   '',
-  '  install   add the marketplace and install the plugin (default scope: user)',
-  '  update    update the marketplace and the plugin',
+  '  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)',
   '  doctor    check this repository (the same as /relevo:doctor)',
   '  version   print the version of this package',
   '',
@@ -22,16 +22,44 @@ export function parseArgs(argv) {
   const [command, ...rest] = argv;
   if (!command || command === '--help' || command === '-h' || command === 'help') return { command: 'help' };
   if (!['install', 'update', 'doctor', 'version'].includes(command)) return { error: `unknown command "${command}"` };
-  let scope = 'user';
+  let scope = null;
   for (let i = 0; i < rest.length; i += 1) {
     const arg = rest[i];
     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 (!SCOPES.includes(scope)) return { error: `the scope must be one of ${SCOPES.join(', ')}` };
+  if (scope !== null && !SCOPES.includes(scope)) return { error: `the scope must be one of ${SCOPES.join(', ')}` };
   return { command, scope };
 }
 
+/** Whether the folder is inside a git work tree; `run` is the injected runner. A missing git counts as no. */
+export function isInsideGitRepo(run) {
+  const r = run('git', ['rev-parse', '--is-inside-work-tree']);
+  return r.code === 0 && r.output.trim() === 'true';
+}
+
+/**
+ * Which scope an install uses. A given scope wins. In a terminal the person is asked, with the project preselected
+ * inside a git repository and the machine outside one; without a terminal nothing waits: the same default is used and
+ * `reason` says why, to be printed.
+ */
+export function resolveScope({ given = null, interactive = false, inRepo = false }) {
+  if (given) return { scope: given };
+  const preferred = inRepo ? 'project' : 'user';
+  if (interactive) return { ask: true, preferred };
+  const why = inRepo ? 'this folder is inside a git repository, so the project scope is used' : 'this folder is not inside a git repository, so the machine scope is used';
+  return { scope: preferred, reason: `no --scope given and no terminal: ${why}` };
+}
+
+/** The choices of the list; the project says which folder gets the settings file. */
+export function scopeChoices({ cwd, inRepo }) {
+  return [
+    { value: 'project', label: `Project (${cwd})${inRepo ? '' : ' [not a git repository]'}: declared in .claude/settings.json, shared with your team` },
+    { value: 'user', label: 'Machine: every project of this machine' },
+    { value: 'local', label: 'Only me, in this project: not shared' }
+  ];
+}
+
 /** The `claude` invocations of a command, in order. */
 export function steps(command, scope) {
   if (command === 'install') {
@@ -43,7 +71,7 @@ export function steps(command, scope) {
   if (command === 'update') {
     return [
       { label: 'update the marketplace', args: ['plugin', 'marketplace', 'update', MARKETPLACE_NAME] },
-      { label: 'update the plugin', args: ['plugin', 'update', PLUGIN_ID, '--scope', scope] }
+      { label: 'update the plugin', args: ['plugin', 'update', PLUGIN_ID, ...(scope ? ['--scope', scope] : [])] }
     ];
   }
   return [];
@@ -53,7 +81,7 @@ 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 }) {
+export function execute({ command, scope }, { run, has, version, doctorScript, cwd = process.cwd() }) {
   const lines = [];
   if (command === 'version') return { code: 0, lines: [version] };
   if (command === 'doctor') {
@@ -74,9 +102,9 @@ export function execute({ command, scope }, { run, has, version, doctorScript })
       return { code: r.code || 1, lines };
     }
   }
-  const where = { user: 'for this machine', project: 'for this repository (declared in .claude/settings.json, so commit it to share it)', local: 'for this repository, only for you' }[scope];
-  lines.push(command === 'install'
-    ? `Relevo is installed ${where}. Restart Claude Code and run /relevo:doctor.`
-    : 'Relevo is up to date. Restart Claude Code to apply it.');
+  const where = { user: 'for this machine', project: 'for this repository', local: 'for this repository, only for you' }[scope];
+  const wrote = { user: 'your user settings', project: `.claude/settings.json of ${cwd}, so commit it to share it`, local: `.claude/settings.local.json of ${cwd}` }[scope];
+  if (command === 'install') lines.push(`Scope: ${scope} (${wrote}).`, `Relevo is installed ${where}. Restart Claude Code and run /relevo:doctor.`);
+  else lines.push('Relevo is up to date. Restart Claude Code to apply it.');
   return { code: 0, lines };
 }

package/scripts/lib/doctor.mjs

@@ -153,6 +153,7 @@ export function gatherFacts(p) {
   f.openspecRoot = p.exists('openspec/config.yaml') || p.exists('openspec/config.yml');
   f.openspecRootTracked = tryRun(() => String(p.tool('git', ['ls-files', 'openspec'])).trim().length > 0, false);
   f.evidenceIgnored = p.exists('.gitignore') && /^\/?evidence\/?\s*$/m.test(p.read('.gitignore'));
+  f.pluginDeclared = pluginDeclaration(p);
 
   // Workflows: what runs on GitHub is what is on the default branch, not what is in the working copy, so once the
   // repository is known they are read from there. `present` says whether the file is where it has to be; `local`
@@ -263,6 +264,22 @@ export function gatherFacts(p) {
   }
 }
 
+/**
+ * Whether the repository declares the Relevo plugin in the settings file that is committed, so that a teammate who
+ * clones it is offered the plugin: { declared } or, when the file is not valid JSON, { unreadable: true }. Only the
+ * shared file counts; the user's and the local settings do not reach anyone else.
+ */
+export function pluginDeclaration(p) {
+  const path = '.claude/settings.json';
+  if (!p.exists(path)) return { declared: false };
+  try {
+    const settings = JSON.parse(p.read(path));
+    return { declared: Boolean(settings?.extraKnownMarketplaces?.relevo) && settings?.enabledPlugins?.['relevo@relevo'] === true };
+  } catch {
+    return { unreadable: true };
+  }
+}
+
 /** Reads a file: the plugin's own files from disk, the repository's through the probes. Null when absent. */
 function readerFor(p, tryRun) {
   const pluginRoot = p.pluginRoot ?? PLUGIN_ROOT;
@@ -504,6 +521,7 @@ export function runChecks(f) {
   if (f.openspecRoot && f.openspecRootTracked) r.push(pass('openspec.root', 'the OpenSpec root is tracked by git'));
   else r.push(fail('openspec.root', 'the OpenSpec root is missing or not tracked by git, so a clean checkout (and the runner) has no `openspec/`', 'run /relevo:init, then commit openspec/config.yaml and the .gitkeep files'));
   r.push(f.evidenceIgnored ? pass('evidence.ignored', 'evidence/ is ignored by git') : fail('evidence.ignored', 'evidence/ is not in .gitignore; `review` would put screenshots in git', 'add the line `evidence/` to .gitignore (or run /relevo:init)'));
+  r.push(...pluginDeclaredChecks(f));
 
   // GitHub side
   if (!f.repo || !f.ghAuth) {
@@ -595,6 +613,15 @@ function toolchainChecks(f) {
   });
 }
 
+/** Does the committed settings file declare the plugin? It is a local fact, so it needs no GitHub sign-in. */
+function pluginDeclaredChecks(f) {
+  const r = [];
+  if (f.pluginDeclared?.unreadable) r.push(warn('plugin.declared', '.claude/settings.json is not valid JSON, so it cannot be checked whether the repository declares the Relevo plugin', 'fix the file; /relevo:init then offers to declare the plugin'));
+  else if (f.pluginDeclared?.declared) r.push(pass('plugin.declared', 'the repository declares the Relevo plugin in .claude/settings.json, so a teammate who opens it is offered it'));
+  else if (f.pluginDeclared) r.push(warn('plugin.declared', 'the repository does not declare the Relevo plugin in .claude/settings.json: a teammate who clones it is not offered the plugin and finds no /relevo: commands', 'run /relevo:init, or claude plugin marketplace add elalfner/relevo --scope project --sparse .claude-plugin and claude plugin install relevo@relevo --scope project, and commit .claude/settings.json'));
+  return r;
+}
+
 /**
  * The installed plugin and what the workflows pin. A package that lost a folder cannot run; a workflow that clones
  * the plugin repository for its scripts (the layout before the package) or has no pin is told to be replaced; a pin

package/scripts/lib/init.mjs

@@ -22,6 +22,10 @@ const TOKEN_LINE = '          # claude_code_oauth_token: ${{ secrets.CLAUDE_CODE
  * subscription token that line is commented out and the token line is switched on. Throws when the template no
  * longer has the lines (a test runs this on the real template).
  */
+// The two official commands that install the plugin at the project scope; the person confirms this exact line.
+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.';
+
 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');
@@ -174,6 +178,11 @@ export function planInit({ facts, answers, templates, current, admin }) {
   if (!facts.openspec) items.push(item('install.openspec', 'todo', 'Install the OpenSpec command-line tool', { install: true, command: 'npm install --global @fission-ai/openspec', detail: OPENSPEC_INSTALL }));
   REQUIRED_SKILLS.filter((n) => !facts.skills[n]).forEach((n) => items.push(item(`install.skill.${n}`, 'todo', `Install the ${n} skill`, { install: true, command: n === 'openspec-explore' ? 'openspec init' : 'npx skills add mattpocock/skills', detail: SKILL_INSTALL[n] })));
 
+  // 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 }));
+
   // 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 }) }));

package/scripts/lib/messages.mjs

@@ -17,6 +17,7 @@ const MAX_VALUE_LENGTH = 400;
 const REQUIRED = {
   built: ['assignee', 'issue', 'title', 'tasks_done', 'tasks_total', 'branch', 'scenarios'],
   qa_failed: ['assignee', 'issue', 'title', 'finding', 'branch'],
+  toolchain_missing: ['assignee', 'issue', 'title', 'tools', 'platform'],
   needs_spec: ['spec_writer', 'issue', 'title', 'missing'],
   changes_requested: ['author', 'issue', 'reviewer', 'summary'],
   needs_reviewer: ['spec_writer', 'issue', 'title', 'pr'],
@@ -38,6 +39,7 @@ const REQUIRED = {
 const STATE_OF = {
   built: 'built',
   qa_failed: 'qa-failed',
+  toolchain_missing: 'qa-failed',
   needs_spec: 'needs-spec',
   changes_requested: 'changes-requested',
   approved: 'pr-open',
@@ -67,6 +69,12 @@ const CATALOG = {
       'Full QA report: {{log_url}}',
       '{{next_line}}',
     ],
+    toolchain_missing: [
+      '@{{assignee}} #{{issue}} "{{title}}" was not built: the runner has no {{tools}} ❌',
+      '',
+      'What happened: the build job checked the toolchain of platform {{platform}} before the agent started, and {{tools}} is not on the path of the runner. Nothing was built and no model turns were spent.',
+      '{{next_line}}',
+    ],
     needs_spec: [
       '@{{spec_writer}} #{{issue}} "{{title}}" is back with you: the spec needs work',
       '',
@@ -173,6 +181,12 @@ const CATALOG = {
       'Reporte completo de QA: {{log_url}}',
       '{{next_line}}',
     ],
+    toolchain_missing: [
+      '@{{assignee}} #{{issue}} "{{title}}" no se construyó: el runner no tiene {{tools}} ❌',
+      '',
+      'Qué pasó: el job de build comprobó el toolchain de la plataforma {{platform}} antes de que empezara el agente, y {{tools}} no está en el path del runner. No se construyó nada y no se gastó ningún turno del modelo.',
+      '{{next_line}}',
+    ],
     needs_spec: [
       '@{{spec_writer}} #{{issue}} "{{title}}" regresa contigo: la spec necesita trabajo',
       '',
@@ -287,9 +301,10 @@ export function renderMessage(kind, data = {}, language = 'en') {
 
   // 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]) {
-    const reason = kind === 'needs_spec' ? values.reason ?? 'missing' : kind === 'qa_failed' ? values.recovery ?? (values.branch_state === 'kept' ? 'kept' : 'fix') : null;
+    const reason = kind === 'needs_spec' ? values.reason ?? 'missing' : kind === 'qa_failed' ? values.recovery ?? (values.branch_state === 'kept' ? 'kept' : 'fix') : kind === 'toolchain_missing' ? 'toolchain' : null;
     const step = nextStep({ state: STATE_OF[kind], reason, issue: values.issue, language: language_ });
     if (!present(values.command) && step.command) values.command = step.command;
+    if (kind === 'toolchain_missing') values.next_line = `${nextStepPrefix(language_)}: ${step.hint}.`;
     if (kind === 'needs_spec') values.next_line = `${nextStepPrefix(language_)}: ${step.command}: ${step.hint}.`;
     if (kind === 'qa_failed') {
       // For kept work the next step says what the command does and the other way forward; the others are the bare command.

package/scripts/lib/next-step.mjs

@@ -76,6 +76,15 @@ const TABLE = {
         es: 'verifica y corrige el trabajo que se guardó; para repensar el issue, usa /relevo:think y luego /relevo:issue {n}',
       },
     },
+    // Nothing was built: the runner lacks a tool of the profile, and the fix is in the workflow, not a command.
+    toolchain: {
+      command: null,
+      who: 'assignee',
+      hint: {
+        en: 'install the toolchain in the build job of relevo-go.yml (the template has the step for Flutter and Laravel, and /relevo:doctor checks it), then remove relevo:qa-failed and label the issue relevo:ready again',
+        es: 'instala el toolchain en el job de build de relevo-go.yml (la plantilla trae el paso para Flutter y Laravel, y /relevo:doctor lo comprueba), luego quita relevo:qa-failed y vuelve a poner relevo:ready al issue',
+      },
+    },
     'delete-branch': {
       command: null,
       who: 'assignee',
@@ -113,7 +122,7 @@ export const NEXT_STEP_STATES = Object.keys(TABLE);
 /** Reasons for the states whose next step depends on one. */
 export const NEXT_STEP_REASONS = {
   'needs-spec': ['missing', 'ambiguous'],
-  'qa-failed': ['fix', 'kept', 'delete-branch'],
+  'qa-failed': ['fix', 'kept', 'toolchain', 'delete-branch'],
 };
 
 const fill = (text, issue) => String(text).replaceAll('{n}', String(issue ?? ''));

package/scripts/lib/select.mjs

@@ -0,0 +1,60 @@
+// A list in the terminal that is chosen with the arrows, and nothing else: no dependency, so that the package stays
+// small. The input and the output are injected, so a test drives it with a simulated keyboard. The terminal is put
+// back (raw mode off, cursor shown) on every way out, including a cancel and an error.
+import { emitKeypressEvents } from 'node:readline';
+
+const HIDE = '\u001b[?25l';
+const SHOW = '\u001b[?25h';
+const UP = (n) => `\u001b[${n}A`;
+const CLEAR = '\u001b[0J';
+
+/**
+ * choices: [{ value, label }]; defaultIndex: the one selected at the start.
+ * Resolves the chosen value, or null when the person cancels (Esc, Ctrl-C, Ctrl-D, q).
+ * Keys: up/down (or k/j), Enter, the digits 1 to 9 as a shortcut that chooses at once.
+ */
+export function select({ title, choices, defaultIndex = 0, input, output, hint = 'Arrows and Enter to choose, a number to pick one, Esc to cancel' }) {
+  if (!input?.isTTY || typeof input.setRawMode !== 'function') return Promise.reject(new Error('the list needs a terminal'));
+  if (!Array.isArray(choices) || choices.length === 0) return Promise.reject(new Error('the list has no choices'));
+  return new Promise((resolve) => {
+    let index = Math.min(Math.max(defaultIndex, 0), choices.length - 1);
+    let drawn = 0;
+    const draw = () => {
+      const lines = [title, ...choices.map((c, i) => `${i === index ? '>' : ' '} ${i + 1}. ${c.label}`), hint];
+      output.write(`${drawn ? UP(drawn) : ''}\r${CLEAR}${lines.join('\n')}\n`);
+      drawn = lines.length;
+    };
+    const finish = (value) => {
+      input.removeListener('keypress', onKey);
+      try {
+        input.setRawMode(false);
+      } finally {
+        input.pause?.();
+        output.write(SHOW);
+      }
+      resolve(value);
+    };
+    function onKey(str, key = {}) {
+      try {
+        if (key.ctrl && (key.name === 'c' || key.name === 'd')) return finish(null);
+        if (key.name === 'escape' || str === 'q') return finish(null);
+        if (key.name === 'return' || key.name === 'enter') return finish(choices[index].value);
+        if (key.name === 'up' || str === 'k') index = (index + choices.length - 1) % choices.length;
+        else if (key.name === 'down' || str === 'j') index = (index + 1) % choices.length;
+        else if (/^[1-9]$/.test(str ?? '') && Number(str) <= choices.length) return finish(choices[Number(str) - 1].value);
+        else return undefined;
+        draw();
+      } catch (err) {
+        finish(null);
+        throw err;
+      }
+      return undefined;
+    }
+    emitKeypressEvents(input);
+    input.setRawMode(true);
+    input.resume?.();
+    input.on('keypress', onKey);
+    output.write(HIDE);
+    draw();
+  });
+}

package/scripts/lib/status-data.mjs

@@ -8,7 +8,13 @@ import { cloudBuilds, CLOUD_VARIABLE } from './execution-mode.mjs';
 
 const paged = (gh, path) => JSON.parse(gh(['api', '--paginate', '--slurp', path])).flat();
 
+// The first line of an error, which is the reason a read failed.
+const reasonOf = (err) => String(err?.stderr ?? err?.message ?? err).trim().split('\n')[0];
+const notFound = (err) => /404|Not Found/i.test(String(err?.stderr ?? err?.message ?? err));
+
 export function gatherStatus({ gh, ghLinks = gh, repo, config }) {
+  // The reads that fail and are not an answer; the report lists them so that a partial report is not taken for a complete one.
+  const unread = [];
   const names = resolveLabelNames(config.labels);
   const byNumber = new Map();
   LABELS.forEach((l) => {
@@ -44,8 +50,9 @@ export function gatherStatus({ gh, ghLinks = gh, repo, config }) {
     let behind = 0;
     try {
       behind = JSON.parse(gh(['api', `repos/${repo}/compare/${pr.head.sha}...${pr.base.ref}`])).ahead_by ?? 0;
-    } catch {
+    } catch (err) {
       behind = 0;
+      unread.push({ what: 'compare', pr: pr.number, reason: reasonOf(err) });
     }
     prs.push({
       number: pr.number, issue, url: pr.html_url, author: pr.user.login,
@@ -54,7 +61,7 @@ export function gatherStatus({ gh, ghLinks = gh, repo, config }) {
       approved: approvedBy.length > 0, behind_by: behind,
     });
   });
-  return { issues: issues.map(({ body, ...rest }) => rest), prs, milestones, externalBlocks: readExternalBlocks({ ghLinks, issues, repo, config, names }), cloudBuilds: readCloudBuilds({ gh, repo }) };
+  return { issues: issues.map(({ body, ...rest }) => rest), prs, milestones, externalBlocks: readExternalBlocks({ ghLinks, issues, repo, config, names }), cloudBuilds: readCloudBuilds({ gh, repo, unread }), unread };
 }
 
 /**
@@ -90,20 +97,24 @@ function readExternalBlocks({ ghLinks, issues, repo, config, names }) {
  * is not `off`. When the workflow cannot be read the answer is `true` (the cautious one: no extra rows, no claim
  * that a person must build by hand).
  */
-function readCloudBuilds({ gh, repo }) {
+function readCloudBuilds({ gh, repo, unread = [] }) {
   let workflowPresent;
   try {
     gh(['api', `repos/${repo}/contents/.github/workflows/relevo-go.yml`]);
     workflowPresent = true;
   } catch (err) {
-    if (!/404|Not Found/i.test(String(err.stderr ?? err.message ?? err))) return true;
+    if (!notFound(err)) {
+      unread.push({ what: 'workflow', reason: reasonOf(err) });
+      return true;
+    }
     workflowPresent = false;
   }
   let variable = null;
   try {
     variable = JSON.parse(gh(['api', `repos/${repo}/actions/variables/${CLOUD_VARIABLE}`])).value ?? null;
-  } catch {
+  } catch (err) {
     variable = null;
+    if (!notFound(err)) unread.push({ what: 'variable', reason: reasonOf(err) });
   }
   return cloudBuilds({ workflowPresent, variable });
 }

package/scripts/lib/status.mjs

@@ -28,7 +28,7 @@ function stateOf(issue, names) {
   return order.find((k) => issue.labels.includes(names[k])) ?? null;
 }
 
-export function buildStatus({ config, issues, prs = [], milestones = [], externalBlocks = {}, cloudBuilds = true, me = null, now = new Date() }) {
+export function buildStatus({ config, issues, prs = [], milestones = [], externalBlocks = {}, cloudBuilds = true, unread = [], me = null, now = new Date() }) {
   const names = resolveLabelNames(config.labels);
   const entries = issues.map((i) => ({
     number: i.number, title: i.title, state: stateOf(i, names), assignee: i.assignees[0] ?? null, milestone: i.milestone ?? null,
@@ -116,14 +116,19 @@ export function buildStatus({ config, issues, prs = [], milestones = [], externa
   return {
     me, view: isSpecWriter ? 'spec-writer' : 'person',
     onMe, toReview, toShip, readyForMe, waitingOnOthers, specWriter: specWriterView,
-    milestones: summaries, alerts, waiting,
+    milestones: summaries, alerts, waiting, unread,
     readOnly: true,
   };
 }
 
 const T = {
   en: {
-    nothing: 'Nothing is waiting on you.', onMe: 'Waiting on you', review: 'Pull requests to review', ship: 'Approved, ready to ship',
+    nothing: 'Nothing is waiting on you.', fromRead: '(from what could be read)', unreadTitle: 'Could not read, so this report may be incomplete',
+    unread: {
+      variable: (u) => `the variable RELEVO_CLOUD_GO (${u.reason}): the issues you could build by hand may be missing`,
+      workflow: (u) => `the workflow relevo-go.yml (${u.reason}): the cloud is assumed to build, so the issues you could build by hand may be missing`,
+      compare: (u) => `the comparison of the branch of pull request #${u.pr} with the base (${u.reason}): a branch that is behind may not be reported`,
+    }, onMe: 'Waiting on you', review: 'Pull requests to review', ship: 'Approved, ready to ship',
     others: 'Waiting on others', spec: 'Back with the spec writer', blocked: 'Blocked', needsReviewer: 'Need a reviewer', milestone: 'Milestone',
     noDue: 'has no due date, so no capacity warning is computed', merged: 'merged', inReview: 'in review', queued: 'queued', warn: 'capacity warning: more work than the team can review before the due date',
     alerts: 'Alerts', staleReview: 'review waiting', staleBranch: 'branch behind the base by',
@@ -131,7 +136,12 @@ const T = {
     readyForMe: 'Ready, for you to build (the cloud is not building)', stuck: 'build with no activity for', restart: 'remove relevo:building and apply relevo:ready again, or run',
   },
   es: {
-    nothing: 'Nada espera por ti.', onMe: 'Esperando por ti', review: 'Pull requests por revisar', ship: 'Aprobadas, listas para entregar',
+    nothing: 'Nada espera por ti.', fromRead: '(con lo que se pudo leer)', unreadTitle: 'No se pudo leer, así que este informe puede estar incompleto',
+    unread: {
+      variable: (u) => `la variable RELEVO_CLOUD_GO (${u.reason}): pueden faltar los issues que podrías construir a mano`,
+      workflow: (u) => `el workflow relevo-go.yml (${u.reason}): se supone que la nube construye, así que pueden faltar los issues que podrías construir a mano`,
+      compare: (u) => `la comparación de la rama del pull request #${u.pr} con la base (${u.reason}): puede que no se avise de una rama atrasada`,
+    }, onMe: 'Esperando por ti', review: 'Pull requests por revisar', ship: 'Aprobadas, listas para entregar',
     others: 'Esperando a otros', spec: 'De vuelta con quien escribe las specs', blocked: 'Bloqueadas', needsReviewer: 'Sin revisor', milestone: 'Milestone',
     noDue: 'no tiene fecha límite, así que no se calcula la advertencia de capacidad', merged: 'fusionadas', inReview: 'en revisión', queued: 'en cola', warn: 'advertencia de capacidad: hay más trabajo del que el equipo puede revisar antes de la fecha límite',
     alerts: 'Alertas', staleReview: 'revisión esperando', staleBranch: 'rama atrasada respecto a la base por',
@@ -160,7 +170,8 @@ export function renderStatus(report, language = 'en') {
   section(t.review, report.toReview.map((r) => `#${r.number} ${r.pr}`));
   section(t.ship, report.toShip.map((r) => `#${r.number} → ${r.command}`));
   section(t.others, report.waitingOnOthers.map((e) => withWaits(e, `#${e.number} ${e.title} (${e.state})`)));
-  if (!sw && !report.onMe.length && !report.toReview.length && !report.toShip.length) out.unshift(t.nothing, '');
+  const unread = report.unread ?? [];
+  if (!sw && !report.onMe.length && !report.toReview.length && !report.toShip.length) out.unshift(unread.length ? `${t.nothing} ${t.fromRead}` : t.nothing, '');
   report.milestones.forEach((m) => {
     out.push(`${t.milestone} "${m.title}": ${m.merged} ${t.merged}, ${m.inReview} ${t.inReview}, ${m.queued} ${t.queued}`);
     if (!m.dueOn) out.push(`  ${t.milestone} ${t.noDue}`);
@@ -173,6 +184,10 @@ export function renderStatus(report, language = 'en') {
       ? `#${a.issue} ${t.staleReview} ${a.hours}h (@${a.reviewer}) ${a.pr}`
       : `#${a.issue} ${t.staleBranch} ${a.behind} ${a.pr}`;
   }));
+  if (unread.length) {
+    if (out.length && out[out.length - 1] !== '') out.push('');
+    section(t.unreadTitle, unread.map((u) => t.unread[u.what](u)));
+  }
   while (out.length && out[out.length - 1] === '') out.pop();
   return out.join('\n');
 }

package/scripts/lib/toolchain-check.mjs

@@ -0,0 +1,12 @@
+// Which of the tools that a profile lists are not on the path. `probe(tool)` says whether one answers; it is injected
+// so that a test does not need the tools. An empty list checks nothing.
+
+/** The tools that are missing, in the order of the profile and without repeats. */
+export function missingTools(tools, probe) {
+  const seen = new Set();
+  return (tools ?? []).filter((tool) => {
+    if (seen.has(tool)) return false;
+    seen.add(tool);
+    return !probe(tool);
+  });
+}

package/scripts/toolchain-check.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+// Checks that the tools which the profile of a platform lists are on the path of this machine. Usage:
+//   node scripts/toolchain-check.mjs --platform <name> [--config relevo.yml] [--plugin-root <dir>]
+// It prints { platform, stack, tools, missing } as JSON. A tool is there when `<tool> --version` starts. The cloud build
+// runs it before the agent, so that a runner without the SDK stops in seconds and not after a full run.
+//   exit 0: every tool is there (or the profile lists none)   exit 1: a tool is missing, or the profile cannot be resolved
+//   exit 2: bad usage or an invalid relevo.yml
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadConfig } from './lib/config.mjs';
+import { resolveProfile } from './lib/stack-profile.mjs';
+import { missingTools } from './lib/toolchain-check.mjs';
+
+const arg = (name) => {
+  const i = process.argv.indexOf(`--${name}`);
+  return i === -1 ? undefined : process.argv[i + 1];
+};
+const fail = (message, code) => {
+  console.error(message);
+  process.exit(code);
+};
+
+const pluginRoot = resolve(arg('plugin-root') ?? resolve(dirname(fileURLToPath(import.meta.url)), '..'));
+const configPath = resolve(arg('config') ?? 'relevo.yml');
+if (!existsSync(configPath)) fail(`relevo.yml not found at ${configPath}. Run /relevo:init to create it.`, 2);
+const loaded = loadConfig(readFileSync(configPath, 'utf8'));
+if (!loaded.ok) fail(`relevo.yml is invalid:\n${loaded.errors.map((e) => `  ${e.message}`).join('\n')}`, 2);
+
+const names = Object.keys(loaded.config.platforms);
+const name = arg('platform') ?? (names.length === 1 ? names[0] : undefined);
+if (!name) fail(`usage: toolchain-check.mjs --platform <${names.join('|')}> [--config relevo.yml] [--plugin-root dir]`, 2);
+const platform = loaded.config.platforms[name];
+if (!platform) fail(`unknown platform "${name}"; the platforms of relevo.yml are: ${names.join(', ')}`, 2);
+
+const base = dirname(configPath);
+const read = (path) => {
+  const file = path.startsWith('/') ? path : resolve(base, path);
+  return existsSync(file) ? readFileSync(file, 'utf8') : null;
+};
+const resolved = resolveProfile({ platform, pluginRoot, read });
+if (!resolved.ok) fail(resolved.errors.join('\n'), 1);
+
+const probe = (tool) => spawnSync(tool, ['--version'], { stdio: 'ignore' }).error === undefined;
+const missing = missingTools(resolved.profile.tools, probe);
+console.log(JSON.stringify({ platform: name, stack: resolved.profile.stack, tools: resolved.profile.tools, missing }));
+process.exit(missing.length > 0 ? 1 : 0);

package/skills/init/SKILL.md

@@ -53,6 +53,8 @@ Show it as it is. Each line says whether it is already `ok`, will be done, `diff
 
 For each line in the plan that is an install, show its exact command and ask for a yes to that command alone. Run it only on a yes. If the person declines, continue, say that dependency is still missing, and that `go` and `ship` will not run until the OpenSpec tool is installed.
 
+One install is not a dependency: `install.plugin-project` declares the Relevo plugin in the project, so that a teammate who clones the repository is offered it, even when the plugin is already installed for the machine. Show its exact command (the two `claude plugin` commands at the project scope) and run it only on a yes. If it ran, `.claude/settings.json` is new or changed: say that it is left for the person to commit. If the person declines, nothing else changes, and `/relevo:doctor` keeps warning about it. When the plan says that file is not valid JSON, do not touch it: tell the person to fix it.
+
 ### 5. Apply
 
 ```bash

package/templates/workflows/relevo-digest.yml

@@ -9,7 +9,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.3.1'
+  RELEVO_VERSION: '0.4.0'
 
 on:
   schedule:

package/templates/workflows/relevo-go.yml

@@ -15,7 +15,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.3.1'
+  RELEVO_VERSION: '0.4.0'
 
 on:
   issues:
@@ -164,6 +164,36 @@ jobs:
         env:
           OPENSPEC_TELEMETRY: '0'
 
+      # 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.
+      - name: Check the toolchain
+        env:
+          GH_TOKEN: ${{ github.token }}
+          ISSUE: ${{ github.event.issue.number || inputs.issue }}
+          PLATFORM: ${{ needs.decide.outputs.platform }}
+        run: |
+          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
+            [ -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
+            exit 0
+          fi
+          missing=$(printf '%s' "$result" | jq -r '.missing | join(", ")')
+          [ -n "$missing" ] || { echo "::error::The toolchain check failed: $result"; exit 1; }
+          title=$(gh issue view "$ISSUE" --json title --jq .title)
+          assignee=$(gh issue view "$ISSUE" --json assignees --jq '.assignees[0].login // empty')
+          body=$(jq -n --arg assignee "$assignee" --arg issue "$ISSUE" --arg title "$title" --arg tools "$missing" --arg platform "$PLATFORM" \
+            '{assignee: $assignee, issue: $issue, title: $title, tools: $tools, platform: $platform}' | node "$RUNNER_TEMP/relevo/scripts/render-message.mjs" toolchain_missing --config relevo.yml)
+          gh issue edit "$ISSUE" --remove-label relevo:ready --remove-label relevo:queued --remove-label relevo:building --add-label relevo:qa-failed
+          gh issue comment "$ISSUE" --body "$body"
+          echo "::error::The runner has no $missing, so nothing was built"
+          exit 1
+
       - id: agent
         uses: anthropics/claude-code-action@v1
         env:

package/templates/workflows/relevo-queue.yml

@@ -10,7 +10,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.3.1'
+  RELEVO_VERSION: '0.4.0'
 
 on:
   issues:

package/templates/workflows/relevo-review.yml

@@ -10,7 +10,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.3.1'
+  RELEVO_VERSION: '0.4.0'
 
 on:
   pull_request_review:

package/templates/workflows/relevo-sla.yml

@@ -8,7 +8,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.3.1'
+  RELEVO_VERSION: '0.4.0'
 
 on:
   schedule: