@elalfner/relevo 0.0.0-stage → 0.3.0

package/scripts/ship-check.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+// Decides whether a pull request may be merged. Usage:
+//   node scripts/ship-check.mjs --repo owner/name --branch feature/31-x [--invoker login] [--config relevo.yml] [--labels a,b] [--baseline <head sha>] [--issue 31]
+//     --labels    the issue's labels; with them the issue must be pr-open
+//     --baseline  the head recorded when ship started: an approval given on it still counts after the archive commit
+//   node scripts/ship-check.mjs --input pr.json --invoker login      (a saved `gh pr view --json ...`; null for no PR)
+// Prints the decision as JSON.   exit 0: may be merged   exit 1: must stop   exit 2: bad arguments or configuration
+
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { loadConfig } from './lib/config.mjs';
+import { realGh } from './lib/github.mjs';
+import { shipDecision } from './lib/ship.mjs';
+
+const arg = (name) => {
+  const i = process.argv.indexOf(`--${name}`);
+  return i === -1 ? undefined : process.argv[i + 1];
+};
+const fail = (m) => {
+  console.error(m);
+  process.exit(2);
+};
+
+const configPath = resolve(arg('config') ?? 'relevo.yml');
+if (!existsSync(configPath)) fail(`relevo.yml not found at ${configPath}. Run /relevo:init to create it.`);
+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');
+
+if (arg('input')) {
+  pr = JSON.parse(readFileSync(arg('input'), 'utf8'));
+} else {
+  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;
+  invoker ??= realGh(['api', 'user', '--jq', '.login']).trim();
+}
+
+const decision = shipDecision({
+  config: loaded.config,
+  pr,
+  invoker,
+  baseline: arg('baseline'),
+  labels: arg('labels') === undefined ? undefined : arg('labels').split(',').map((l) => l.trim()).filter(Boolean),
+  issue: arg('issue'),
+});
+console.log(JSON.stringify(decision, null, 2));
+process.exit(decision.allowed ? 0 : 1);

package/scripts/spec-ready.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+// Says whether OpenSpec considers the specification of a change complete. Usage:
+//   node scripts/spec-ready.mjs --change <change_id>
+//   node scripts/spec-ready.mjs --input status.json        (a saved `openspec status --change <id> --json`)
+// Complete means every artifact is done (or skipped, for a change that declares skip_specs).
+//   exit 0: complete   exit 1: artifacts missing (named on stdout)   exit 2: bad arguments or OpenSpec failed
+
+import { readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { pendingArtifacts, planningComplete } from './lib/openspec-status.mjs';
+
+const arg = (name) => {
+  const i = process.argv.indexOf(`--${name}`);
+  return i === -1 ? undefined : process.argv[i + 1];
+};
+const fail = (message) => {
+  console.error(message);
+  process.exit(2);
+};
+
+let status;
+try {
+  if (arg('input')) status = JSON.parse(readFileSync(arg('input'), 'utf8'));
+  else {
+    if (!arg('change')) fail('usage: spec-ready.mjs --change <change_id>  (or --input status.json)');
+    const r = spawnSync('openspec', ['status', '--change', arg('change'), '--json'], { encoding: 'utf8' });
+    if (r.error || r.status !== 0) fail(`openspec status failed${r.stderr ? `: ${r.stderr.trim()}` : ''}`);
+    status = JSON.parse(r.stdout);
+  }
+} catch (err) {
+  fail(`could not read the status: ${err.message}`);
+}
+
+if (planningComplete(status)) {
+  console.log('the specification is complete');
+} else {
+  const pending = pendingArtifacts(status);
+  console.log(pending.length ? `artifacts not done: ${pending.join(', ')}` : 'OpenSpec reported no artifacts');
+  process.exit(1);
+}

package/scripts/stack-profile.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+// Prints the resolved profile of a platform, as JSON. Usage:
+//   node scripts/stack-profile.mjs --platform <name> [--config relevo.yml] [--plugin-root <dir>] [--role issue]
+// With `--role issue` it prints only the questions the stack has for the issue writer ({ platform, stack, questions });
+// without it the questions are not part of the output, so dev and qa never receive them.
+// The profile is the plugin's stacks/<stack>.md plus the repository's .relevo/stacks/<stack>.md, with the
+// `platforms.<name>.checks` of relevo.yml applied. The agents receive this output; they do not look for profiles.
+//   exit 0: printed   exit 1: the stack has no profile (or a profile is invalid)   exit 2: bad usage or invalid relevo.yml
+
+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';
+
+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: stack-profile.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 result = resolveProfile({ platform, pluginRoot, read });
+if (!result.ok) fail(result.errors.join('\n'), 1);
+
+const { profile } = result;
+if (arg('role') === 'issue') {
+  console.log(JSON.stringify({ platform: name, stack: profile.stack, questions: profile.questions }, null, 2));
+  process.exit(0);
+}
+if (arg('role') !== undefined) fail('--role can only be "issue"', 2);
+console.log(JSON.stringify({
+  platform: name,
+  stack: profile.stack,
+  path: platform.path,
+  targets: platform.targets,
+  target_tools: Object.fromEntries(platform.targets.map((t) => [t, profile.targets[t] ?? ''])),
+  commands: profile.commands,
+  generated: profile.generated,
+  tools: profile.tools,
+  requires_skills: profile.requires_skills,
+  skills: profile.skills,
+  layers: profile.layers,
+  ignored: profile.ignored,
+  overridden: profile.overridden,
+  body: profile.body,
+}, null, 2));

package/scripts/stage.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+// Stages the named files, and nothing else. Usage: node scripts/stage.mjs path [path ...]
+// Refuses ".", "-A" and similar: every commit must name the files it includes.
+
+import { execFileSync } from 'node:child_process';
+import { explicitStageArgs } from './lib/staging.mjs';
+
+try {
+  const args = explicitStageArgs(process.argv.slice(2));
+  execFileSync('git', args, { stdio: 'inherit' });
+} catch (err) {
+  console.error(err.message);
+  process.exit(2);
+}

package/scripts/status.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+// Who is waiting on what. Read-only: it never changes an issue, label or branch.
+//   node scripts/status.mjs --repo owner/name [--me login] [--json] [--config relevo.yml]
+//   node scripts/status.mjs --input state.json [--me login] [--now ISO] [--json]
+// exit 0: reported   exit 2: invalid configuration or bad arguments
+
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { loadConfig } from './lib/config.mjs';
+import { realGh, realGhLinks } from './lib/github.mjs';
+import { buildStatus, renderStatus } from './lib/status.mjs';
+import { gatherStatus } from './lib/status-data.mjs';
+
+const arg = (name) => {
+  const i = process.argv.indexOf(`--${name}`);
+  return i === -1 ? undefined : process.argv[i + 1];
+};
+const fail = (m) => {
+  console.error(m);
+  process.exit(2);
+};
+
+const configPath = resolve(arg('config') ?? 'relevo.yml');
+if (!existsSync(configPath)) fail(`relevo.yml not found at ${configPath}. Run /relevo:init to create it.`);
+const loaded = loadConfig(readFileSync(configPath, 'utf8'));
+if (!loaded.ok) fail(loaded.errors.map((e) => `error: ${e.message}`).join('\n'));
+const { config } = loaded;
+
+const repo = arg('repo') ?? process.env.GITHUB_REPOSITORY;
+let data;
+if (arg('input')) {
+  data = JSON.parse(readFileSync(arg('input') === '-' ? 0 : arg('input'), 'utf8'));
+} else {
+  if (!repo) fail('give --repo owner/name (or set GITHUB_REPOSITORY), or --input state.json');
+  data = gatherStatus({ gh: realGh, ghLinks: realGhLinks(), repo, config });
+}
+let me = arg('me') ?? null;
+if (!me && !arg('input')) {
+  try {
+    me = JSON.parse(realGh(['api', 'user'])).login;
+  } catch {
+    me = null;
+  }
+}
+
+const report = buildStatus({ config, ...data, me, now: arg('now') ? new Date(arg('now')) : new Date() });
+console.log(process.argv.includes('--json') ? JSON.stringify(report, null, 2) : renderStatus(report, config.language));

package/scripts/usage-limit.mjs

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+// Did a cloud run end because a usage limit, a quota or the credit was reached? Usage:
+//   node scripts/usage-limit.mjs --file <execution_file>
+//   exit 0: the log shows it   exit 1: it does not, or the file is missing or unreadable
+// The final step of the build job uses it to say "label the issue ready again later" instead of the generic text.
+
+import { readFileSync } from 'node:fs';
+import { reachedUsageLimit } from './lib/run-usage.mjs';
+
+const i = process.argv.indexOf('--file');
+let text = '';
+try {
+  if (i !== -1) text = readFileSync(process.argv[i + 1], 'utf8');
+} catch {
+  text = '';
+}
+process.exit(reachedUsageLimit(text) ? 0 : 1);

package/scripts/validate-config.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+// Validates relevo.yml. Usage: node scripts/validate-config.mjs [path] [--json] [--effective]
+//   exit 0: valid   exit 1: invalid   exit 2: file not found
+
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadConfig } from './lib/config.mjs';
+import { profileLookups } from './lib/stack-profile.mjs';
+
+const args = process.argv.slice(2);
+const flags = new Set(args.filter((a) => a.startsWith('--')));
+const target = resolve(args.find((a) => !a.startsWith('--')) ?? 'relevo.yml');
+
+if (!existsSync(target)) {
+  console.error(`relevo.yml not found at ${target}. Run /relevo:init to create it.`);
+  process.exit(2);
+}
+
+// Targets and `checks` are checked against the profile of each stack, when a profile can be read.
+const read = (path) => {
+  const file = path.startsWith('/') ? path : resolve(dirname(target), path);
+  return existsSync(file) ? readFileSync(file, 'utf8') : null;
+};
+const pluginRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const result = loadConfig(readFileSync(target, 'utf8'), profileLookups({ pluginRoot, read }));
+
+if (result.ok) {
+  result.config.qa.rules_from.forEach((file) => {
+    if (!existsSync(resolve(dirname(target), file))) {
+      result.warnings.push({ path: 'qa.rules_from', message: `qa.rules_from points to "${file}", which does not exist` });
+    }
+  });
+}
+
+if (flags.has('--json')) {
+  console.log(JSON.stringify({ ok: result.ok, errors: result.errors, warnings: result.warnings }, null, 2));
+} else {
+  result.errors.forEach((e) => console.error(`error: ${e.message}`));
+  result.warnings.forEach((w) => console.error(`warning: ${w.message}`));
+  if (result.ok) console.log(`${target} is valid`);
+}
+if (result.ok && flags.has('--effective')) console.log(JSON.stringify(result.config, null, 2));
+process.exit(result.ok ? 0 : 1);

package/scripts/web-review.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+// Runs a review script in a browser of its own and reports what it checked. Usage:
+//   node scripts/web-review.mjs --script evidence/review-web.mjs --url http://localhost:5173 \
+//        [--allow-origins https://staging.example.com] [--secret-env TEST_USER,TEST_PASS] [--out evidence] [--headed]
+// The script is the agent's, written from the scenarios and reviewed by QA. Its default export receives
+// { page, context, baseUrl, line, credentials }: line(n, how, fn) runs fn and records the checklist line n as
+// auto-ok or auto-fail; credentials(name) gives a test credential taken from the environment variable `name`,
+// which must be in --secret-env. The browser has a clean profile and can reach only localhost, the page under
+// review and the allowed origins; every secret value is redacted from what is written.
+// Writes <out>/web-log.txt (the log the audit reads, with --package web) and <out>/web-result.json.
+//   exit 0: the script ran (lines can still have failed)   exit 1: the script was refused, Playwright is missing,
+//   the browser could not start, or the script failed outside a line   exit 2: bad arguments
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { formatBrowserLog, isAllowedOrigin, redact, scanReviewScript } from './lib/web-review.mjs';
+
+const RUN_LIMIT_MS = 120000;
+
+const arg = (name) => {
+  const i = process.argv.indexOf(`--${name}`);
+  return i === -1 ? undefined : process.argv[i + 1];
+};
+const list = (name) => (arg(name) ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+const stop = (code, message) => {
+  console.error(message);
+  process.exit(code);
+};
+
+const scriptPath = arg('script');
+const baseUrl = arg('url');
+if (!scriptPath || !baseUrl || !existsSync(scriptPath)) stop(2, 'usage: web-review.mjs --script <file> --url <url> [--allow-origins a,b] [--secret-env A,B] [--out evidence] [--headed]');
+let origin;
+try {
+  origin = new URL(baseUrl);
+} catch {
+  stop(2, `--url is not a URL: ${baseUrl}`);
+}
+const allowed = list('allow-origins');
+const secretNames = list('secret-env');
+const out = resolve(arg('out') ?? 'evidence');
+
+const problems = scanReviewScript(readFileSync(scriptPath, 'utf8'));
+if (problems.length > 0) stop(1, `the review script was refused before any browser started:\n${problems.map((p) => `  - ${p}`).join('\n')}`);
+
+const secrets = Object.fromEntries(secretNames.filter((n) => process.env[n]).map((n) => [n, process.env[n]]));
+const hide = (text) => redact(text, secrets);
+
+function loadPlaywright() {
+  for (const base of [join(process.cwd(), 'package.json'), import.meta.url]) {
+    try {
+      return createRequire(base)('playwright');
+    } catch { /* try the next place */ }
+  }
+  return null;
+}
+const playwright = loadPlaywright();
+if (!playwright) stop(1, 'Playwright cannot be resolved from this project: install it with "npm install -D playwright" and "npx playwright install chromium"');
+
+const events = [];
+const results = [];
+let scriptError = null;
+let pagesLoaded = 0;
+let browser;
+
+const line = async (n, how, fn) => {
+  if (!Number.isInteger(n) || n < 1) throw new Error('line(n, how, fn) needs the number of a checklist line');
+  try {
+    await fn();
+    results.push({ n, status: 'auto-ok', how: String(how) });
+  } catch (error) {
+    results.push({ n, status: 'auto-fail', how: String(how), error: String(error?.message ?? error).split('\n')[0] });
+  }
+};
+const credentials = (name) => {
+  if (!secretNames.includes(name)) throw new Error(`credentials("${name}"): the name is not in --secret-env`);
+  if (!(name in secrets)) throw new Error(`credentials("${name}"): the environment variable is not set`);
+  return secrets[name];
+};
+
+async function run() {
+  try {
+    browser = await playwright.chromium.launch({ headless: !process.argv.includes('--headed') });
+  } catch (error) {
+    stop(1, `the browser could not start: ${String(error.message).split('\n')[0]}`);
+  }
+  const context = await browser.newContext({ acceptDownloads: false, serviceWorkers: 'block' });
+  await context.route('**/*', (route) => {
+    const request = route.request();
+    if (isAllowedOrigin(request.url(), { baseUrl, allowed })) return route.continue();
+    events.push({ type: 'blocked', text: `${request.method()} ${request.url()}` });
+    return route.abort('blockedbyclient');
+  });
+  const page = await context.newPage();
+  // "Failed to load resource" repeats what the request and response events already say (and the blocked ones).
+  page.on('console', (m) => { if (m.type() === 'error' && !m.text().startsWith('Failed to load resource')) events.push({ type: 'console', text: m.text() }); });
+  page.on('pageerror', (e) => events.push({ type: 'pageerror', text: `${e.name}: ${e.message}` }));
+  page.on('requestfailed', (r) => {
+    const reason = r.failure()?.errorText ?? 'failed';
+    if (!reason.includes('BLOCKED_BY_CLIENT')) events.push({ type: 'requestfailed', text: `${r.method()} ${r.url()} ${reason}` });
+  });
+  page.on('response', (r) => {
+    if (r.request().isNavigationRequest() && r.request().frame() === page.mainFrame() && r.status() < 400) pagesLoaded += 1;
+  });
+  page.on('response', (r) => { if (r.status() >= 400) events.push({ type: 'response', text: `${r.status()} ${r.request().method()} ${r.url()}` }); });
+
+  try {
+    const mod = await import(pathToFileURL(resolve(scriptPath)).href);
+    if (typeof mod.default !== 'function') throw new Error('the script must export a default async function');
+    await mod.default({ page, context, baseUrl, line, credentials });
+  } catch (error) {
+    scriptError = String(error?.message ?? error).split('\n')[0];
+  }
+}
+
+const timer = setTimeout(() => {
+  scriptError = `the run took more than ${RUN_LIMIT_MS / 1000} seconds and was stopped`;
+}, RUN_LIMIT_MS);
+let backstop;
+await Promise.race([run(), new Promise((r) => { backstop = setTimeout(r, RUN_LIMIT_MS + 500); })]);
+clearTimeout(timer);
+clearTimeout(backstop);
+if (browser) await browser.close().catch(() => {});
+
+mkdirSync(out, { recursive: true });
+// A browser that never loaded a page proves nothing: the log is left empty so the audit is inconclusive.
+writeFileSync(join(out, 'web-log.txt'), pagesLoaded === 0 ? '' : hide(formatBrowserLog(events, { origin: origin.host })));
+writeFileSync(join(out, 'web-result.json'), hide(`${JSON.stringify({ url: baseUrl, lines: results, blocked: events.filter((e) => e.type === 'blocked').length, pagesLoaded, scriptError }, null, 2)}\n`));
+results.sort((a, b) => a.n - b.n).forEach((r) => console.log(hide(`line ${r.n}: ${r.status} - ${r.how}${r.error ? ` (${r.error})` : ''}`)));
+console.log(`${events.length} event(s) written to ${join(out, 'web-log.txt')}; audit it with: review-state.mjs audit --package web`);
+if (scriptError) stop(1, hide(`the script failed outside a line: ${scriptError}`));
+process.exit(0);

package/skills/doctor/SKILL.md

@@ -0,0 +1,28 @@
+---
+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: ""
+---
+
+# Relevo doctor
+
+Report whether Relevo can run here. This command only reads; it never changes anything.
+
+Scripts live in `${CLAUDE_PLUGIN_ROOT}/scripts/`. Run them with `node`. They hold the checks; use them instead of judging the setup yourself.
+
+## What you must never do
+
+- Never run a command that writes: no `gh` call except the reads inside the script, no `git add`, no install, no file edit. If something is wrong, tell the person the fix; do not apply it. `/relevo:init` is what applies fixes.
+- Never read, print or ask for the value of a secret. The script lists secret names only.
+- Never hide a failure or turn it into a pass.
+
+## 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.
+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.
+
+## Exit status
+
+`doctor.mjs` exits 0 when no check failed (warnings allowed) and 1 when at least one failed. Report the result in one line after the output.

package/skills/fix/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: fix
+description: Corrects a defect found in a built issue, specification first. It writes the corrected behaviour into the change's specification and task list, then runs the dev and qa agents, and only then commits and pushes. The issue keeps its place in the workflow. Use only when asked to fix a specific issue, with a description of what is wrong. It pushes code, so it never starts on its own.
+argument-hint: "[issue-number] [what is wrong]"
+disable-model-invocation: true
+---
+
+# Relevo fix
+
+Correct a defect in the issue named at the start of `$ARGUMENTS`. The first word is the issue number; everything after it is the description of what is wrong. If there is no description, ask the person what is wrong before doing anything else.
+
+The order matters and is checked by a script: **the specification is updated first, the code second.** In this session you never write application code yourself; the `relevo:dev` agent does.
+
+Scripts live in `${CLAUDE_PLUGIN_ROOT}/scripts/`. Run them with `node`. They hold the rules that must not vary (which state an issue returns to, the specification-first check, the tasks file edit, scanning, messages); use them instead of deciding those things yourself.
+
+## What you must never do
+
+- Never edit application code in this session, and never edit anything outside the change folder before the developer has run.
+- Never change the project rules file (`qa.rules_from`) to make a defect fit. If the defect is a breach of a rule, the rule stays and the code is fixed.
+- Never commit or push if QA still rejects after the retries: save the changes in a stash with `fix-stash.mjs` and tell the person.
+- Never approve, merge or open a pull request, never use `git add .` or `-A`, never force-push, and never push to a branch other than the issue's own.
+
+## Steps
+
+### 0. Preflight
+
+Stop with a clear message, changing nothing, if any of these fails:
+
+- `node ${CLAUDE_PLUGIN_ROOT}/scripts/validate-config.mjs relevo.yml` exits non-zero. Show its output.
+- `openspec --version` does not run. Tell the person to run `/relevo:doctor`.
+- The working tree has uncommitted changes.
+- `node ${CLAUDE_PLUGIN_ROOT}/scripts/fix-state.mjs --current "<the issue's labels, comma separated>"` exits 1. It prints why a fix cannot run in the issue's state. Keep its output: it tells you the state the issue returns to (`to`) and whom to notify.
+
+Find the repository (`$GITHUB_REPOSITORY`, or `gh repo view --json nameWithOwner -q .nameWithOwner`), the issue's branch (`git branch -r --list "origin/feature/<issue>-*"`) and its change folder (`openspec/changes/<issue>-*`). If the branch is not on the remote, stop and say so: there is nothing to correct yet.
+
+Switch to the branch: `git fetch origin <branch>`, `git switch <branch>`, `git pull --ff-only origin <branch>`.
+
+Then check two things before reading the defect:
+
+- **Is there code to correct?** `node ${CLAUDE_PLUGIN_ROOT}/scripts/branch-work.mjs --base <base> --change <change>`. If it exits 1 the branch holds only the specification: change nothing, tell the person to delete the remote branch and apply the label relevo:ready again, and stop.
+- **Is there saved work?** `node ${CLAUDE_PLUGIN_ROOT}/scripts/fix-stash.mjs find --issue <issue>`. If it prints a stash, a previous fix was rejected by QA and its work was saved (in this clone only). Tell the person which iteration it was and offer to restore it. If they agree, run `fix-stash.mjs pop --issue <issue>`; when it exits 1 it names the conflicting files and keeps the stash: show them and stop. After a restore, read the specification and the corrections already written, and go on from step 3 (Develop). To start from scratch instead, the person must confirm in writing before you run `fix-stash.mjs drop --issue <issue>`.
+
+### 1. Understand the defect
+
+Read the description, the change's specification (`openspec/changes/<change>/specs/`) and the project rules file (`qa.rules_from` in `relevo.yml`). Decide which of these it is:
+
+- the specification was wrong or missing a case: the specification needs correcting;
+- the code does not do what the specification says: the specification still gets a scenario for the exact case that failed, because that scenario is what QA will verify;
+- the defect breaks a project rule: say so to the person, and write a scenario that restores compliance. Do not touch the rules file.
+
+If you cannot tell what the correct behaviour should be, ask the person. They are here.
+
+### 2. Specification first
+
+Update the change, writing no application code:
+
+1. In the right capability under `openspec/changes/<change>/specs/`, add a `#### Scenario:` with `WHEN`/`THEN` lines that describe the corrected behaviour (or rewrite the scenario that was wrong, and say why in `design.md`).
+2. In `design.md`, record a decision only if one changed. In `proposal.md`, change the scope only if it changed.
+3. Add the correction tasks, one per distinct correction and each verifiable:
+   ```bash
+   node ${CLAUDE_PLUGIN_ROOT}/scripts/add-corrections.mjs openspec/changes/<change>/tasks.md "<task>" ["<task>" ...]
+   ```
+   It appends `## N. Review corrections [Iteration K]` with unchecked tasks and prints the iteration number `K`.
+4. `openspec validate "<change>"`. If it fails, fix the artifacts and validate again, at most twice; then stop and tell the person.
+5. Run the guard:
+   ```bash
+   node ${CLAUDE_PLUGIN_ROOT}/scripts/fix-guard.mjs openspec/changes/<change>
+   ```
+   If it exits 1 it prints what is missing. Correct the specification and run it again. **Do not launch the developer until it exits 0.**
+6. Check the task list: `node ${CLAUDE_PLUGIN_ROOT}/scripts/fix-tasks.mjs --file openspec/changes/<change>/tasks.md --stage before`. The only unchecked tasks may be the corrections just added, and one of them must start with `Test:` (a regression test that fails without the fix), unless every correction ends with `(device only)` because it shows only on a device. If it exits 1, fix the task list and run it again.
+
+Do not commit yet: the whole fix is committed together once QA passes.
+
+### 3. Develop
+
+Find the platform of the issue again from its text, then resolve the profile and the extra skills for it:
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/platform-of.mjs --issue <issue>
+node ${CLAUDE_PLUGIN_ROOT}/scripts/stack-profile.mjs --platform <platform>
+node ${CLAUDE_PLUGIN_ROOT}/scripts/role-skills.mjs --role fix --platform <platform>
+```
+
+If `platform-of.mjs` exits 1, change nothing more and tell the person what it printed (the issue no longer names a valid platform: they correct the `Platform:` line and run `/relevo:fix` again). If `stack-profile.mjs` fails, show its message and stop.
+
+Launch the `relevo:dev` agent in **build** mode. Give it the change folder, the project rules files, the resolved profile, the folder of the platform (`path`), the skill paths and the base branch. The original tasks are all done, so the only pending ones are the corrections, and those are all it should touch.
+
+Read its report. If its open questions are not "none", they mean the specification is still unclear: ask the person, update the specification and run the guard again.
+
+### 4. QA, with retries
+
+Launch the `relevo:qa` agent on the result, with the same change folder, rules files, profile, folder of the platform, skill paths (for `fix`, those of `dev` and `qa` are in the output of `role-skills.mjs --role fix`) and base branch. Its first line is `QA PASSED` or `QA REJECTED`.
+
+On `QA REJECTED` you may retry up to `qa.retries` times. Each retry launches `relevo:dev` in **fix** mode with the complete QA report, then `relevo:qa` again with the previous report, so it checks each earlier finding.
+
+If QA still rejects after the retries: **make no commit and no push.** Save the work with `node ${CLAUDE_PLUGIN_ROOT}/scripts/fix-stash.mjs save --issue <issue> --iteration <K>` (the tree is left clean, so the next `fix` can start), show the person the findings, say that `/relevo:fix <issue>` offers the saved work back, leave the issue's labels untouched, and stop.
+
+### 5. Commit
+
+Before committing, check that every task is done: `node ${CLAUDE_PLUGIN_ROOT}/scripts/fix-tasks.mjs --file openspec/changes/<change>/tasks.md --stage after`. If it exits 1, a correction was left open: do not commit, and go back to step 3 for it.
+
+Commit exactly the files the developer reported plus the files changed under `openspec/changes/<change>/`, naming each one, through the script. Never use `git add .` or `-A`; the script refuses them.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/commit-change.mjs --message "fix: <short summary> (#<issue>)" --within "<path>" --change "<change>" -- <paths>
+```
+
+The script stages the paths, refuses protected paths and files outside the folder of the platform, scans what is staged for temporary markers and credentials, and commits only when it finds nothing. If it exits 1 it has unstaged the paths and printed the file and line: show them to the person and stop without pushing. The changes stay in the working tree. Do not add links to this session or attribution lines to the message.
+
+### 6. Push
+
+`git push origin <branch>` (a normal push, never forced).
+
+### 7. The issue
+
+Use what `fix-state.mjs` printed in step 0.
+
+1. If `labels` is not empty, apply it with `gh issue edit` (it returns a `qa-failed` issue to `built`, and a `changes-requested` one to `pr-open`). In every other state the labels do not change.
+2. Decide who is told:
+   - `notify` is `assignee`: the issue's assignee, with the ask `Your next step: /relevo:review <issue>`.
+   - `notify` is `reviewer`: find the pull request (`gh pr list --head <branch> --json number,reviews`), take the people who requested changes, re-request each one with `gh pr edit <number> --add-reviewer <login>`, and mention them with the ask `please re-review`.
+   - otherwise: mention nobody.
+3. Post one comment built by `node ${CLAUDE_PLUGIN_ROOT}/scripts/render-message.mjs fix_done` with: `issue`, `title`, `iteration` (the number from step 2), `summary` (one line of what changed), `qa` (`QA PASSED`), `commit` (the short hash), and `recipient` and `ask` when someone is told.
+4. If `evidence/review-state.json` exists (a review is in progress), reconcile it with the new specification: `node ${CLAUDE_PLUGIN_ROOT}/scripts/review-state.mjs sync openspec/changes/<change>`. Lines already confirmed stay confirmed, lines that failed are tested again, new scenarios are added, and the log audit and the agreement are repeated. Tell the person to restart the app and resume with `/relevo:review <issue>`, and that they can write `retest <numbers>` for any confirmed line the fix may have affected, because QA only audited this correction.
+
+## Report
+
+Finish with one short block: the issue, the iteration, what changed, the QA verdict, the commit, and the issue's state before and after.