@elalfner/relevo 0.7.0 → 0.9.0

package/scripts/ship-check.mjs

@@ -11,6 +11,7 @@ import { resolve } from 'node:path';
 import { loadConfig } from './lib/config.mjs';
 import { realGh } from './lib/github.mjs';
 import { shipDecision } from './lib/ship.mjs';
+import { baselineChecks, loadPr } from './lib/ship-github.mjs';
 
 const arg = (name) => {
   const i = process.argv.indexOf(`--${name}`);
@@ -26,9 +27,9 @@ if (!existsSync(configPath)) fail(`relevo.yml not found at ${configPath}. Run /r
 const loaded = loadConfig(readFileSync(configPath, 'utf8'));
 if (!loaded.ok) fail(loaded.errors.map((e) => `error: ${e.message}`).join('\n'));
 
-const FIELDS = 'number,state,isDraft,mergeable,title,author,reviews,statusCheckRollup,headRefName,headRefOid,baseRefName';
 let pr;
 let invoker = arg('invoker');
+let carried;
 
 if (arg('input')) {
   pr = JSON.parse(readFileSync(arg('input'), 'utf8'));
@@ -36,10 +37,10 @@ if (arg('input')) {
   const repo = arg('repo') ?? process.env.GITHUB_REPOSITORY;
   const branch = arg('branch');
   if (!repo || !branch) fail('usage: ship-check.mjs --repo owner/name --branch <branch> [--invoker login] [--config relevo.yml]');
-  const found = JSON.parse(realGh(['pr', 'list', '--repo', repo, '--head', branch, '--state', 'all', '--json', 'number,state', '--limit', '5']));
-  const open = found.find((p) => p.state === 'OPEN') ?? found[0];
-  pr = open ? JSON.parse(realGh(['pr', 'view', String(open.number), '--repo', repo, '--json', FIELDS])) : null;
+  pr = loadPr(realGh, repo, branch);
   invoker ??= realGh(['api', 'user', '--jq', '.login']).trim();
+  // The archive commit may have no checks of its own; the approved head's count when only openspec/ changed since.
+  if (pr && arg('baseline')) carried = baselineChecks(realGh, repo, arg('baseline'), pr.headRefOid);
 }
 
 const decision = shipDecision({
@@ -49,6 +50,7 @@ const decision = shipDecision({
   baseline: arg('baseline'),
   labels: arg('labels') === undefined ? undefined : arg('labels').split(',').map((l) => l.trim()).filter(Boolean),
   issue: arg('issue'),
+  baselineChecks: carried,
 });
 console.log(JSON.stringify(decision, null, 2));
 process.exit(decision.allowed ? 0 : 1);

package/scripts/ship-unattended.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+// Ships an issue on GitHub, without a model, when a person applied the `relevo:ship` label. Usage (in the workflow):
+//   node scripts/ship-unattended.mjs --repo owner/name --issue 31 --actor login --actor-type User --work <checkout>
+// Environment: GH_TOKEN (the workflow token), GH_PUSH_TOKEN (the App token, or the workflow token), HAS_APP (true|false).
+// Prints the outcome as JSON.   exit 0: merged, stopped with a comment, or ignored   exit 2: bad arguments
+// Any other failure exits non-zero, and the workflow's last step reports it on the issue.
+
+import { execFileSync, spawnSync } from 'node:child_process';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { runUnattendedShip } from './lib/ship-unattended.mjs';
+
+const arg = (name) => {
+  const i = process.argv.indexOf(`--${name}`);
+  return i === -1 ? undefined : process.argv[i + 1];
+};
+const [repo, issue, actor, actorType, work] = ['repo', 'issue', 'actor', 'actor-type', 'work'].map(arg);
+if (!repo || !/^\d+$/.test(issue ?? '') || !actor || !actorType || !work) {
+  console.error('usage: ship-unattended.mjs --repo owner/name --issue <n> --actor <login> --actor-type <User|Bot> --work <checkout>');
+  process.exit(2);
+}
+
+const ghWith = (token) => (args) => execFileSync('gh', args, {
+  encoding: 'utf8',
+  maxBuffer: 64 * 1024 * 1024,
+  env: { ...process.env, GH_TOKEN: token ?? process.env.GH_TOKEN },
+});
+const sh = (cmd, args, { cwd, input, env } = {}) => {
+  const r = spawnSync(cmd, args, { cwd, input, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, env: { ...process.env, ...env } });
+  return { status: r.status ?? 1, stdout: r.stdout ?? '', stderr: r.stderr ?? String(r.error ?? '') };
+};
+
+const outcome = await runUnattendedShip({
+  repo,
+  issue,
+  actor,
+  actorType,
+  hasApp: process.env.HAS_APP === 'true',
+  workDir: resolve(work),
+  pluginRoot: resolve(dirname(fileURLToPath(import.meta.url)), '..'),
+  sh,
+  gh: ghWith(process.env.GH_TOKEN),
+  pushGh: ghWith(process.env.GH_PUSH_TOKEN || process.env.GH_TOKEN),
+});
+console.log(JSON.stringify(outcome, null, 2));

package/scripts/toolchain-check.mjs

@@ -1,7 +1,7 @@
 #!/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
+// It prints { platform, stack, tools, missing } as JSON; `missing` also covers git, gh, jq and node, which every job needs. 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
@@ -12,7 +12,7 @@ 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';
+import { missingTools, RUNNER_TOOLS } from './lib/toolchain-check.mjs';
 
 const arg = (name) => {
   const i = process.argv.indexOf(`--${name}`);
@@ -44,6 +44,6 @@ 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);
+const missing = missingTools([...RUNNER_TOOLS, ...(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/scripts/web-hook.mjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+// Adds the SessionStart hook that installs OpenSpec in web sessions to .claude/settings.json. Usage:
+//   node scripts/web-hook.mjs [--settings .claude/settings.json]
+// Run by /relevo:init only after the person agreed to the hook. Every other key and hook of the file is kept, and a
+// file that is not a JSON object is left as it is.
+// exit 0: written, or already there   exit 2: the file could not be merged
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { mergeWebHook } from './lib/init.mjs';
+
+const i = process.argv.indexOf('--settings');
+const path = i === -1 ? '.claude/settings.json' : process.argv[i + 1];
+
+try {
+  const before = existsSync(path) ? readFileSync(path, 'utf8') : null;
+  const after = mergeWebHook(before);
+  if (after === before) {
+    console.log(`${path} already installs OpenSpec at the start of a web session; nothing changed`);
+  } else {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, after);
+    console.log(`${path} now installs OpenSpec at the start of a web session; the file is left for you to commit`);
+  }
+} catch (err) {
+  console.error(`could not add the hook to ${path}: ${err.message}`);
+  process.exit(2);
+}

package/scripts/web-preflight.mjs

@@ -3,11 +3,12 @@
 // under review with the module scripts its page loads. Usage:
 //   node scripts/web-preflight.mjs --url http://localhost:5173 [--timeout 5000] [--wait 30000]
 // With --wait it is also the readiness probe of a server the agent started: the address is retried until it answers.
-// Prints { ok, check, detail, start, env } as JSON: `start` is the command that starts the app, `env` the variable
-// names of .env.example (the real environment files are never read).
-//   exit 0: ready   exit 3: no node_modules (run npm install)   exit 4: Playwright does not resolve
-//   exit 5: the Chromium of Playwright is missing   exit 6: the address or one of its modules does not answer below 400
-//   exit 2: bad arguments
+// Prints { ok, check, detail, start, env, install } as JSON: `start` is the command that starts the app, `env` the
+// variable names of .env.example (the real environment files are never read), `install` the frozen install command of
+// the lock file (null without one).
+//   exit 0: ready   exit 3: no node_modules   exit 7: node_modules does not match package-lock.json
+//   exit 4: Playwright does not resolve from the project   exit 5: the Chromium of Playwright is missing
+//   exit 6: the address or one of its modules does not answer below 400   exit 2: bad arguments
 
 import { existsSync, readFileSync } from 'node:fs';
 import { loadPlaywright } from './lib/web-review.mjs';

package/scripts/web-review.mjs

@@ -73,7 +73,7 @@ const secrets = Object.fromEntries(secretNames.filter((n) => process.env[n]).map
 const hide = (text) => redact(text, secrets);
 
 const playwright = loadPlaywright();
-if (!playwright) stop(1, 'Playwright cannot be resolved from this project: with the person\'s permission, install it with "npm install --no-save playwright" and "npx playwright install chromium", then restore package-lock.json if npm changed it');
+if (!playwright) stop(1, 'Playwright cannot be resolved from this project: it belongs in its development dependencies; run /relevo:init, or "npm install -D playwright" and "npx playwright install chromium" in the folder of the platform, and commit the change on the base branch');
 
 if (arg('out') === undefined && existsSync(join(out, 'web-log.txt'))) {
   tell(`warning: ${join(out, 'web-log.txt')} is replaced; a run against another server uses an --out of its own (evidence/run-<port>)`);

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, 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,10 +18,11 @@ 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 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.
+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.
 
 ## Exit status
 

package/skills/go/SKILL.md

@@ -88,6 +88,8 @@ node ${CLAUDE_PLUGIN_ROOT}/scripts/preflight.mjs
 
 It checks the configuration, that OpenSpec runs and finds a root for this repository, and that the working tree is clean. If it exits non-zero, stop with a clear message and change nothing: show its output, which names each failed check and its fix.
 
+When the failed check is `openspec` (the command line does not run), stop there. Show the install command it gives and do not go on from memory or from reading the code: never write anything under `openspec/changes/` by hand, and never imitate what `openspec` would have produced.
+
 Find the repository name: `$GITHUB_REPOSITORY`, or `gh repo view --json nameWithOwner -q .nameWithOwner`.
 
 ### 1. Plan and claim
@@ -110,7 +112,7 @@ This reads the queue from GitHub, applies the gates and limits, carries out labe
 
 Read the decision for the issue in the JSON it prints:
 
-- `start`: continue. It gives you `branch`, `change_id`, `base`, `assignee`, `title`, `qa_retries`, `run_max_turns`, `run_max_cost`, `issue_hash` (the text of the issue when it was claimed), `allow_paths` (dependency files and folders the issue lets the change touch), and the platform the issue is for: `platform` (its name), `stack`, `path` (its folder) and `targets`.
+- `start`: continue. It gives you `branch`, `change_id`, `base`, `assignee`, `title`, `qa_retries`, `run_max_turns`, `run_max_cost`, `issue_hash` (the text of the issue when it was claimed), `allow_paths` (dependency files and folders the issue lets the change touch), and the platform the issue is for: `platform` (its name), `stack`, `path` (its folder) and `targets`. When a valid urgent label let the issue start over the assignee's capacity it also has `urgent` (true) and `built_waiting` (how many built issues the assignee will have waiting).
 - anything else (`needs-spec`, `block`, `queue`, `denied`, `no-milestone`, `no-assignee`, `skip`): that is a normal outcome, already applied. Report the decision and its reason in one line, and stop. Do not build.
 
 ### 2. Branch
@@ -245,7 +247,7 @@ Do not add links to this session or attribution lines to the message.
 
 1. `git push -u origin <branch>` (a normal push, never forced).
 2. Move the issue to `built`: `label-change.mjs --to built --current "..."`, applied with `gh issue edit`.
-3. Post one comment with `render-message.mjs built`, mentioning the assignee. Fill: `assignee`, `issue`, `title`, `tasks_done` and `tasks_total` (`progress.complete` and `progress.total` of `openspec instructions apply --change "<change_id>" --json`), `branch`, `issue_hash`, `scenarios` (`node ${CLAUDE_PLUGIN_ROOT}/scripts/checklist.mjs openspec/changes/<change_id> --count`), `risk` if QA or the developer pointed at a riskiest area, and `checklist` (the output of `node ${CLAUDE_PLUGIN_ROOT}/scripts/checklist.mjs openspec/changes/<change_id>`).
+3. Post one comment with `render-message.mjs built`, mentioning the assignee. Fill: `assignee`, `issue`, `title`, `tasks_done` and `tasks_total` (`progress.complete` and `progress.total` of `openspec instructions apply --change "<change_id>" --json`), `branch`, `issue_hash`, `scenarios` (`node ${CLAUDE_PLUGIN_ROOT}/scripts/checklist.mjs openspec/changes/<change_id> --count`), `risk` if QA or the developer pointed at a riskiest area, `urgent` and `built_waiting` copied from the decision when it has them (they add the line that says the issue started ahead of the queue; leave both out otherwise), and `checklist` (the output of `node ${CLAUDE_PLUGIN_ROOT}/scripts/checklist.mjs openspec/changes/<change_id>`).
 
 The comment tells the assignee the next command (`/relevo:review <issue>`).
 

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.
@@ -34,13 +35,14 @@ If `relevo.yml` already exists and is valid, skip this step. Otherwise ask, in s
 - the review mode: `none` (a solo project), `peer` or `roles`;
 - 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;
+- 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 `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;
 - the cost limit per unattended run in US dollars: the template's 5 is a placeholder the person must accept or change (with `antigravity`, the token limit instead).
 
-Write the answers as JSON to a temporary file **outside the repository**, with the keys `members`, `specWriter`, `reviewMode`, `language`, `platforms` (a map of name to `{ stack, path, targets }`), `links` (a list of `owner/repo`, possibly none), `runs` (`cloud`, `local` or `both`), `credential` (`api_key` or `subscription`), `stackProfiles` (the stacks that get a profile file, possibly none) and, if given, `runMaxCost`. Never put a secret in it.
+Write the answers as JSON to a temporary file **outside the repository**, with the keys `members`, `specWriter`, `reviewMode`, `language`, `platforms` (a map of name to `{ stack, path, targets }`), `links` (a list of `owner/repo`, possibly none), `runs` (`cloud`, `local` or `both`), `credential` (`api_key` or `subscription`), `runnerLabels` (a list of runner labels, only for a self-hosted runner), `stackProfiles` (the stacks that get a profile file, possibly none) and, if given, `runMaxCost`. Never put a secret in it.
 
 ### 3. Show the plan
 
@@ -48,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
 
@@ -56,6 +58,10 @@ For each line in the plan that is an install, show its exact command and ask for
 
 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.
 
+`install.web-hook` adds a `SessionStart` hook to `.claude/settings.json` that installs OpenSpec at the start of a session of Claude Code on the web, where every new container lacks it. Show the hook the plan names (it runs nothing outside a remote session and nothing when `openspec` already runs) and ask for a yes to it alone. On a yes, run `node ${CLAUDE_PLUGIN_ROOT}/scripts/web-hook.mjs` from the repository root: it adds the hook next to the other settings and hooks of the file and changes nothing else, and it writes nothing when the file is not valid JSON. Say that `.claude/settings.json` is left for the person to commit. If the person declines, write nothing for it: `/relevo:doctor` keeps warning about it in a web session. When the plan says the file is not valid JSON, do not touch it.
+
+For a Vue platform reviewed in a browser, the plan has two installs, in this order: `install.playwright.<platform>` adds Playwright to the platform's development dependencies, and `install.chromium.<platform>` downloads its Chromium. Run each from the repository root exactly as shown (the command enters the platform folder itself). If Playwright was added, `package.json` and the lock file of that platform changed: say that they are left for the person to commit with the other new files, on the base branch, so that every review finds Playwright. If the person declines either one, continue and say that a browser review of that platform stops until it is installed, and that `/relevo:doctor` keeps warning about it. A `review.autopilot` line among the manual steps means the existing `relevo.yml` keeps the autopilot `off`: say that a browser review needs `precheck` or `verify`, and leave the file as it is.
+
 ### 5. Apply
 
 ```bash

package/skills/review/SKILL.md

@@ -79,7 +79,7 @@ If `evidence/review-state.json` exists for this issue, resume: show the confirme
 
 Otherwise: `node ${CLAUDE_PLUGIN_ROOT}/scripts/review-state.mjs init openspec/changes/<change folder> --autopilot <review.autopilot>`, then clear the log so the audit only sees this session: `adb -s <serial> logcat -c`. Then ask the person to start the app, or restart it if it was already open, so that the log names its process and the audit can ignore other apps on the device.
 
-For a `browser` adapter there is no `adb` and no device log: after `init`, run the preflight against the address under review (the one the person gives; for Vue, `http://localhost:5173` when they give none):
+For a `browser` adapter there is no `adb` and no device log: after `init`, run the preflight from the folder of the platform, against the address under review (the one the person gives; for Vue, `http://localhost:5173` when they give none):
 
 ```bash
 node ${CLAUDE_PLUGIN_ROOT}/scripts/web-preflight.mjs --url <address>
@@ -87,8 +87,9 @@ node ${CLAUDE_PLUGIN_ROOT}/scripts/web-preflight.mjs --url <address>
 
 It prints JSON and exits by what is missing. Tell the person in their language:
 
-- `3`: there is no `node_modules`; ask them to run `npm install` first, and stop until they say it is done.
-- `4` or `5`: Playwright or its Chromium is missing. Ask for permission to install them; only on a yes run `npm install --no-save playwright` and `npx playwright install chromium`, then `git diff --quiet -- package-lock.json || git restore -- package-lock.json` (npm can rewrite the lock file even with `--no-save`), and run the preflight again.
+- `3` (there is no `node_modules`) or `7` (the installed dependencies do not match `package-lock.json`, for example after the merge changed it): when `install` is `null` there is no lock file to install from; ask the person to install the dependencies themselves and stop until they say it is done. Otherwise show the `install` command exactly as printed and ask for a yes to that command alone; never compose another one. Only on a yes run it from the folder of the platform, then `git status --porcelain -- package.json <the lock file>`: if either changed, restore it with `git restore --` and say which. Then run the preflight again. If the install fails, show its error and stop: do not retry it with package scripts or another command, and do not drive. If the person says no, stop without driving; the issue stays as it is. After an install, if the person's dev server is already running, tell them to restart it before you check the address again; never restart it yourself.
+- `4`: Playwright does not resolve from the project. Install nothing: say that Playwright is missing from the development dependencies of the project, that `/relevo:init` adds it once for everyone (or `npm install -D playwright` in the folder of the platform, committed on the base branch), and stop without driving.
+- `5`: the Chromium of Playwright is missing. It lives outside the project: ask for permission, and only on a yes run `npx playwright install chromium` from the folder of the platform, then run the preflight again.
 - `6`: the app does not answer, or one of its modules answers 400 or more (`detail` names it). Keep its `start` and `env` for step 3: the person starts the app there. If the app was already running and a module fails, tell them to restart their server; never do it yourself.
 - `0`: ready.
 

package/skills/ship/SKILL.md

@@ -99,7 +99,7 @@ Do not add links to this session or attribution lines to the commit.
 
 ### 4. Check again
 
-The push may start new checks or dismiss an approval. Wait for any running checks (`gh pr checks <number> --repo <owner/name> --watch`), then run `ship-check.mjs` again, exactly as in step 1 and adding `--baseline <baseline>`, so an approval given on the head before the archive still counts. If it now says the pull request has conflicts, see below. If it says anything else to stop, show the reasons and stop. The most common one is an approval dismissed by the push: tell the person that the repository must not dismiss approvals on new commits (`/relevo:doctor` checks it).
+The push may start new checks or dismiss an approval. Wait for any running checks (`gh pr checks <number> --repo <owner/name> --watch`), then run `ship-check.mjs` again, exactly as in step 1 and adding `--baseline <baseline>`, so an approval given on the head before the archive still counts. When the archive commit has no checks of its own and changes only `openspec/`, `ship-check` judges the checks of `<baseline>` instead, and its summary says `checksFrom: baseline`; do not ask about `no-ci` then. If it now says the pull request has conflicts, see below. If it says anything else to stop, show the reasons and stop. The most common one is an approval dismissed by the push: tell the person that the repository must not dismiss approvals on new commits (`/relevo:doctor` checks it).
 
 **The archive left conflicts.** If the only reason is `CONFLICTING`, the base branch changed the specifications the archive wrote. Recover with normal pushes only, never a force-push:
 
@@ -126,3 +126,5 @@ The subject is the pull request title, which already ends with the issue number.
 Finish with one short block: the issue, the pull request, the merge commit, that the issue is closed and the labels removed.
 
 End with this reminder: promoting `<base>` to `<release>` is a separate pull request, with a version tag. `ship` does not do it.
+
+When the repository has the ship workflow (`.github/workflows/relevo-ship.yml`), add one line: next time, the person who ships can apply the `relevo:ship` label to the issue instead, and GitHub ships it with the same checks, without a local copy.

package/stacks/vue.md

@@ -20,7 +20,7 @@ targets:
 
 ## Verification
 
-Run the commands of this profile from the folder of the platform: `analyze` (type check, then linter), `test` and `format`. They use the versions pinned in the project (`npx --no-install`), so the dependencies must be installed; if they are not, say so instead of installing anything new.
+Run the commands of this profile from the folder of the platform: `analyze` (type check, then linter), `test` and `format`. They use the versions pinned in the project (`npx --no-install`), so the dependencies must be installed; if they are not, say so instead of installing anything new. Only the review may install them: it offers the frozen install of the project's lock file (`npm ci --ignore-scripts`) and runs it on a yes.
 
 Do not claim the code type-checks, lints or passes tests unless you ran the commands and saw the result. The commands written here are read-only on purpose: the `lint` script that `npm create vue` generates uses `--fix` and rewrites files, so do not run `npm run lint` as a check. Only `format` writes.
 
@@ -57,7 +57,7 @@ Do not spend time re-checking what `analyze` already enforces: read its output.
 
 ## Targets
 
-- `web`: needs a browser; no extra tool. The review of a web target is always driven by the agent (`review.autopilot` must be `precheck` or `verify`) with a Playwright script that `qa` reads first; Playwright is a dependency of the project, installed with `npm install -D playwright` and `npx playwright install chromium`.
+- `web`: needs a browser; no extra tool. The review of a web target is always driven by the agent (`review.autopilot` must be `precheck` or `verify`) with a Playwright script that `qa` reads first; Playwright is a development dependency of the project: `/relevo:init` offers to add it (`npm install -D playwright`) and its Chromium (`npx playwright install chromium`), and the review never installs Playwright itself.
 
 ## Questions for the issue writer
 

package/templates/agents/antigravity-step.yml

@@ -1,7 +1,7 @@
 # What `relevo-go.yml` and `relevo-queue.yml` run when `agent.build` in relevo.yml is `antigravity`. This file is not a
 # workflow: each block below replaces, in the shared workflow, the lines between the markers with the same name, and
 # nothing else of the workflow changes (a test checks it). Edit the shared workflow for anything that is not about the
-# agent. Written for ubuntu-latest (x86-64).
+# agent. Written for an x86-64 Linux runner (the binary below is linux-x64).
 #
 # What Antigravity CLI cannot do on its own, and what stands in for it (docs/security.md):
 #   turn and token limits  the run guard (scripts/agent-guard.mjs) reads the event stream and stops the agent; the numbers
@@ -32,10 +32,13 @@
           curl -fsSL -o "$RUNNER_TEMP/agy.tar.gz" "$AGY_URL"
           echo "$AGY_SHA512  $RUNNER_TEMP/agy.tar.gz" | sha512sum --check --strict -
           tar -xzf "$RUNNER_TEMP/agy.tar.gz" -C "$RUNNER_TEMP" antigravity
-          mkdir -p "$HOME/.local/bin"
-          install -m 0755 "$RUNNER_TEMP/antigravity" "$HOME/.local/bin/agy"
-          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
-          [ "$("$HOME/.local/bin/agy" --version)" = "$AGY_VERSION" ] || { echo "::error::agy is not version $AGY_VERSION"; exit 1; }
+          mkdir -p "$RUNNER_TEMP/bin" "$RUNNER_TEMP/home"
+          install -m 0755 "$RUNNER_TEMP/antigravity" "$RUNNER_TEMP/bin/agy"
+          echo "$RUNNER_TEMP/bin" >> "$GITHUB_PATH"
+          # The CLI, the plugin of the machine and the settings of the run live in a home folder of this job, so a runner
+          # that persists keeps none of them. Every later step of the job sees this HOME.
+          echo "HOME=$RUNNER_TEMP/home" >> "$GITHUB_ENV"
+          [ "$("$RUNNER_TEMP/bin/agy" --version)" = "$AGY_VERSION" ] || { echo "::error::agy is not version $AGY_VERSION"; exit 1; }
 
       # The Relevo plugin is rendered from the package unpacked in the step "Check the toolchain" and installed for the
       # machine, so nothing is added to the working tree (the agent needs it clean). The settings of the run go to the

package/templates/relevo.yml

@@ -28,6 +28,7 @@ review:
   merger: approver     # author | approver: who runs /relevo:ship
   autopilot: off       # off | precheck | verify: how much of the on-device review the agent may drive (the person always closes it)
   allowed_origins: []  # web origins a driven review may visit besides localhost, e.g. https://staging.example.com
+  ship_without_ci: false  # true: the relevo:ship label may merge when no check ran (/relevo:ship asks instead)
 
 limits:
   built_unreviewed_per_person: 2   # built issues one person may have waiting
@@ -37,6 +38,9 @@ limits:
   building_alert_hours: 3          # hours without activity before an issue on `building` is reported as stuck
   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, linux-build]     # a self-hosted runner is assumed to persist between jobs (docs/execution.md)
+
 qa:
   retries: 1                       # developer attempts after QA rejects
   rules_from: CLAUDE.md            # project rules QA reads at every run

package/templates/workflows/relevo-digest.yml

@@ -1,15 +1,20 @@
+# relevo-template: 0.9.0
 # 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.
 # Change the time below to suit your team (cron is in UTC).
 # The scripts come from the published package @elalfner/relevo, at the version pinned in RELEVO_VERSION.
 
+# Runner: `runs-on` comes from `runner.labels` in relevo.yml (`/relevo:init` writes it into this file, `/relevo:doctor` checks it).
+# The runner needs git, gh and jq; Node and the tools of the job are installed per job. A self-hosted runner is assumed to
+# persist between jobs, so the job puts its tools under $RUNNER_TEMP and removes what it adds to the workspace.
+
 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.7.0'
+  RELEVO_VERSION: '0.9.0'
 
 on:
   schedule:
@@ -52,3 +57,8 @@ jobs:
           GH_TOKEN: ${{ github.token }}
           GITHUB_REPOSITORY: ${{ github.repository }}
         run: node .relevo-plugin/scripts/digest.mjs --repo "$GITHUB_REPOSITORY"
+
+      # A runner may keep its workspace between jobs (a self-hosted one does): remove what this job added to it.
+      - name: Remove what this job added
+        if: always()
+        run: rm -rf .relevo-plugin

package/templates/workflows/relevo-go.yml

@@ -1,3 +1,4 @@
+# relevo-template: 0.9.0
 # 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.
 #
@@ -10,12 +11,18 @@
 # Keep the numbers in claude_args in line with limits.run_max_turns and limits.run_max_cost.
 # Where the numbers disagree the lower one wins, so this file can only make a run cheaper than relevo.yml says.
 
+# Runner: `runs-on` comes from `runner.labels` in relevo.yml (`/relevo:init` writes it into this file, `/relevo:doctor` checks it).
+# The runner needs git, gh and jq; Node and the tools of the job are installed per job. A self-hosted runner is assumed to
+# persist between jobs, so the job puts its tools under $RUNNER_TEMP and removes what it adds to the workspace.
+
 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.7.0'
+  RELEVO_VERSION: '0.9.0'
+  # The version of OpenSpec that the job installs for itself.
+  OPENSPEC_VERSION: '1.14.3'
 
 on:
   issues:
@@ -109,6 +116,11 @@ jobs:
           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 "${assignee:+@$assignee }The run failed before it could decide what to do (job status: $JOB_STATUS), so nothing was built. Read the log to see why: $RUN_URL. When the cause is fixed, remove \`relevo:qa-failed\` and apply \`relevo:ready\` again."
 
+      # A runner may keep its workspace between jobs (a self-hosted one does): remove what this job added to it.
+      - name: Remove what this job added
+        if: always()
+        run: rm -rf .relevo-plugin
+
   build:
     needs: decide
     if: needs.decide.outputs.action == 'start'
@@ -162,14 +174,18 @@ jobs:
       # the packages, so they need no such option.
 
       - name: Install OpenSpec
-        run: npm install --global @fission-ai/openspec
+        # Under the temporary folder of the job, at the pinned version: nothing global is left on a runner that persists.
+        run: |
+          npm install --prefix "$RUNNER_TEMP/openspec" "@fission-ai/openspec@$OPENSPEC_VERSION" --no-fund --no-audit
+          echo "$RUNNER_TEMP/openspec/node_modules/.bin" >> "$GITHUB_PATH"
         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.
+      # 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 }}
@@ -179,18 +195,19 @@ 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
             exit 0
           fi
-          missing=$(printf '%s' "$result" | jq -r '.missing | join(", ")')
+          # No jq here: the tool that is missing may be jq itself, and the comment must still be posted.
+          missing=$(printf '%s' "$result" | node -e 'console.log(JSON.parse(require("fs").readFileSync(0, "utf8")).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)
+          body=$(ASSIGNEE="$assignee" TITLE="$title" TOOLS="$missing" node -e 'const e = process.env; console.log(JSON.stringify({assignee: e.ASSIGNEE, issue: e.ISSUE, title: e.TITLE, tools: e.TOOLS, platform: e.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"
@@ -217,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
@@ -234,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
@@ -300,3 +314,8 @@ jobs:
           else
             gh issue comment "$ISSUE" --body "${assignee:+@$assignee }The run ended without a result (job status: $JOB_STATUS), so nothing was built or reported. Read the log to see why: $RUN_URL. When the cause is fixed, remove \`relevo:qa-failed\` and apply \`relevo:ready\` again."
           fi
+
+      # A runner may keep its workspace between jobs (a self-hosted one does): remove what this job added to it.
+      - name: Remove what this job added
+        if: always()
+        run: rm -rf .relevo-plugin

package/templates/workflows/relevo-queue.yml

@@ -1,3 +1,4 @@
+# relevo-template: 0.9.0
 # 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).
 #
@@ -5,12 +6,16 @@
 # schedule, so a lost event does not stall the queue. Needs a relevo.yml at the repository root.
 # The scripts come from the published package @elalfner/relevo, at the version pinned in RELEVO_VERSION.
 
+# Runner: `runs-on` comes from `runner.labels` in relevo.yml (`/relevo:init` writes it into this file, `/relevo:doctor` checks it).
+# The runner needs git, gh and jq; Node and the tools of the job are installed per job. A self-hosted runner is assumed to
+# persist between jobs, so the job puts its tools under $RUNNER_TEMP and removes what it adds to the workspace.
+
 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.7.0'
+  RELEVO_VERSION: '0.9.0'
 
 on:
   issues:
@@ -72,3 +77,8 @@ jobs:
           for issue in $(echo "$result" | node -e 'JSON.parse(require("fs").readFileSync(0,"utf8")).start.forEach(n=>console.log(n))'); do
             gh workflow run relevo-go.yml --repo "$GITHUB_REPOSITORY" -f issue="$issue"
           done
+
+      # A runner may keep its workspace between jobs (a self-hosted one does): remove what this job added to it.
+      - name: Remove what this job added
+        if: always()
+        run: rm -rf .relevo-plugin

package/templates/workflows/relevo-review.yml

@@ -1,3 +1,4 @@
+# relevo-template: 0.9.0
 # 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.
@@ -5,12 +6,16 @@
 # Pull requests from forks are skipped explicitly (and would only get a read-only token anyway).
 # The scripts come from the published package @elalfner/relevo, at the version pinned in RELEVO_VERSION.
 
+# Runner: `runs-on` comes from `runner.labels` in relevo.yml (`/relevo:init` writes it into this file, `/relevo:doctor` checks it).
+# The runner needs git, gh and jq; Node and the tools of the job are installed per job. A self-hosted runner is assumed to
+# persist between jobs, so the job puts its tools under $RUNNER_TEMP and removes what it adds to the workspace.
+
 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.7.0'
+  RELEVO_VERSION: '0.9.0'
 
 on:
   pull_request_review:
@@ -58,3 +63,8 @@ jobs:
           GH_TOKEN: ${{ github.token }}
           GITHUB_REPOSITORY: ${{ github.repository }}
         run: node .relevo-plugin/scripts/review-event.mjs --repo "$GITHUB_REPOSITORY"
+
+      # A runner may keep its workspace between jobs (a self-hosted one does): remove what this job added to it.
+      - name: Remove what this job added
+        if: always()
+        run: rm -rf .relevo-plugin