@elalfner/relevo 0.7.0 → 0.9.0

package/scripts/lib/doctor.mjs

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

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