@elalfner/relevo 0.0.0-stage → 0.3.0

package/scripts/platform-of.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+// Prints the platform an issue belongs to, as JSON. Usage:
+//   node scripts/platform-of.mjs --issue <n> [--repo owner/name] [--config relevo.yml]
+//   node scripts/platform-of.mjs --input issue.json [--config relevo.yml]     (issue.json: { "body": "..." }, for tests)
+// Output: { platform, stack, path, targets }. `fix` and `review` use it to find the stack again from the issue text.
+//   exit 0: printed   exit 1: the platform cannot be resolved (the reason is on stderr)   exit 2: bad usage or invalid relevo.yml
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { loadConfig } from './lib/config.mjs';
+import { resolvePlatform } from './lib/platform-of.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 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);
+
+let body;
+if (arg('input')) {
+  try {
+    body = JSON.parse(readFileSync(arg('input'), 'utf8')).body ?? '';
+  } catch (err) {
+    fail(`cannot read ${arg('input')}: ${err.message}`, 2);
+  }
+} else if (arg('issue')) {
+  const repo = arg('repo') ?? process.env.GITHUB_REPOSITORY;
+  const args = ['issue', 'view', arg('issue'), '--json', 'body', '--jq', '.body', ...(repo ? ['--repo', repo] : [])];
+  try {
+    body = execFileSync('gh', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+  } catch (err) {
+    fail(`cannot read issue ${arg('issue')}: ${String(err.stderr ?? err.message).trim()}`, 2);
+  }
+} else {
+  fail('usage: platform-of.mjs --issue <n> [--repo owner/name] [--config relevo.yml]', 2);
+}
+
+const r = resolvePlatform({ platforms: loaded.config.platforms, body });
+if (!r.ok) fail(r.reason === 'missing' ? `the issue has no ${r.message}` : r.message, 1);
+console.log(JSON.stringify({ platform: r.name, stack: r.entry.stack, path: r.entry.path, targets: r.entry.targets }, null, 2));

package/scripts/preflight.mjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+// The checks to make before building or fixing anything. Usage:
+//   node scripts/preflight.mjs [--checks config,openspec,openspec-root,clean-tree,gh] [--config relevo.yml]
+// Default checks: config, openspec, openspec-root, clean-tree. `gh` (signed in to GitHub) is asked for by the
+// commands that need it. Prints one block per failure with its fix.
+//   exit 0: all passed   exit 1: something failed   exit 2: unknown check
+
+import { readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { resolve } from 'node:path';
+import { DEFAULT_CHECKS, formatPreflight, runPreflight } from './lib/preflight.mjs';
+
+const arg = (name) => {
+  const i = process.argv.indexOf(`--${name}`);
+  return i === -1 ? undefined : process.argv[i + 1];
+};
+const checks = arg('checks') ? arg('checks').split(',').map((c) => c.trim()).filter(Boolean) : DEFAULT_CHECKS;
+const run = (command, args) => {
+  const r = spawnSync(command, args, { encoding: 'utf8' });
+  return { status: r.error ? 127 : r.status ?? 1, stdout: r.stdout ?? '', stderr: r.stderr ?? '' };
+};
+
+try {
+  const result = runPreflight({ checks, readConfig: () => readFileSync(resolve(arg('config') ?? 'relevo.yml'), 'utf8'), run });
+  const text = formatPreflight(result);
+  if (result.ok) console.log(text);
+  else console.error(text);
+  process.exit(result.ok ? 0 : 1);
+} catch (err) {
+  console.error(err.message);
+  process.exit(2);
+}

package/scripts/render-message.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+// Renders a hand-off message. Usage:
+//   echo '{"assignee":"ana","issue":31,...}' | node scripts/render-message.mjs built [--config relevo.yml] [--language es]
+// The language comes from --language, else from relevo.yml (if found), else English.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { loadConfig } from './lib/config.mjs';
+import { MESSAGE_KINDS, renderMessage } from './lib/messages.mjs';
+
+const kind = process.argv[2];
+if (!kind || !MESSAGE_KINDS.includes(kind)) {
+  console.error(`usage: render-message.mjs <${MESSAGE_KINDS.join('|')}> [--config path] [--language xx]  (JSON data on stdin)`);
+  process.exit(2);
+}
+const arg = (name) => {
+  const i = process.argv.indexOf(`--${name}`);
+  return i === -1 ? undefined : process.argv[i + 1];
+};
+
+let language = arg('language');
+if (!language) {
+  const path = resolve(arg('config') ?? 'relevo.yml');
+  if (existsSync(path)) {
+    const loaded = loadConfig(readFileSync(path, 'utf8'));
+    if (loaded.ok) language = loaded.config.language;
+  }
+}
+
+try {
+  console.log(renderMessage(kind, JSON.parse(readFileSync(0, 'utf8') || '{}'), language ?? 'en'));
+} catch (err) {
+  console.error(err.message);
+  process.exit(2);
+}

package/scripts/requeue.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+// Re-evaluates the queue. Carries out every decision except `start` (labels, comments) and prints
+// which issues may start now, so a workflow can dispatch one build run for each.
+//
+//   node scripts/requeue.mjs --repo owner/name [--config relevo.yml] [--dry-run] [--credential false]
+//   node scripts/requeue.mjs --input state.json [--config relevo.yml]
+//   prints {"start":[12,15],"summary":{...}}
+//   exit 0: evaluated   exit 2: invalid or missing configuration, or bad arguments
+
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { loadConfig } from './lib/config.mjs';
+import { applyDecisions, gather, realGh, realGhLinks } from './lib/github.mjs';
+import { planGo } from './lib/plan.mjs';
+import { resolveLabelNames } from './lib/labels.mjs';
+import { ownedByQueue, startable } from './lib/requeue.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 state;
+if (arg('input')) {
+  state = 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');
+  state = gather({ gh: realGh, ghLinks: realGhLinks(), repo, config });
+}
+
+// The whole queue is planned so that the limits stay right, but the queue only acts on the issues that are
+// already waiting: a freshly ready issue is handled by the `go` run its label started.
+const { decisions: planned } = planGo({ config, repo, ...state });
+const decisions = ownedByQueue(planned, state.issues, resolveLabelNames(config.labels));
+const summary = {};
+decisions.forEach((d) => {
+  summary[d.action] = (summary[d.action] ?? 0) + 1;
+});
+const dry = process.argv.includes('--dry-run') || Boolean(arg('input'));
+if (!dry) applyDecisions(decisions, { gh: realGh, repo, config });
+// Without a model credential the cloud cannot build, so nothing is dispatched (and nothing would be commented again every run).
+console.log(JSON.stringify({ start: arg('credential') === 'false' ? [] : startable(decisions), summary }));

package/scripts/review-adapter.mjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+// Prints how `review` works for a platform of relevo.yml, as JSON. Usage:
+//   node scripts/review-adapter.mjs --platform web [--target web] [--config relevo.yml]
+// Output: { supported, stack, target, kind, log, capture, driver, needs, reason, platform, needs_autopilot }
+//   exit 0: supported   exit 1: no adapter for this platform and target (the reason is in the output)   exit 2: bad usage or invalid relevo.yml
+
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { loadConfig } from './lib/config.mjs';
+import { adapterFor, needsAutopilot, targetOf } from './lib/review-adapters.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);
+};
+const name = arg('platform');
+if (!name) fail('usage: review-adapter.mjs --platform <name> [--target <target>] [--config relevo.yml]');
+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(`relevo.yml is invalid:\n${loaded.errors.map((e) => `  ${e.message}`).join('\n')}`);
+const platform = loaded.config.platforms[name];
+if (!platform) fail(`there is no platform "${name}" in relevo.yml (platforms: ${Object.keys(loaded.config.platforms).join(', ') || 'none'})`);
+
+const target = arg('target') ?? targetOf(platform);
+const adapter = adapterFor({ stack: platform.stack, target });
+console.log(JSON.stringify({ ...adapter, platform: name, needs_autopilot: needsAutopilot(adapter) }));
+process.exit(adapter.supported ? 0 : 1);

package/scripts/review-brief.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// Prints a short brief of an issue for the person who reviews it. Usage:
+//   node scripts/review-brief.mjs --issue 42 --title "Birthday list" --body-file issue.md [--built-file comment.md] [--language en|es]
+// exit 0: printed   exit 2: bad arguments
+
+import { readFileSync } from 'node:fs';
+import { reviewBrief } from './lib/review-brief.mjs';
+
+const arg = (name) => {
+  const i = process.argv.indexOf(`--${name}`);
+  return i === -1 ? undefined : process.argv[i + 1];
+};
+const number = arg('issue');
+const title = arg('title');
+const bodyFile = arg('body-file');
+if (!number || title === undefined || !bodyFile) {
+  console.error('usage: review-brief.mjs --issue <n> --title "<title>" --body-file <file> [--built-file <file>] [--language en|es]');
+  process.exit(2);
+}
+const read = (f) => {
+  try {
+    return readFileSync(f, 'utf8');
+  } catch (err) {
+    console.error(`cannot read ${f}: ${err.message}`);
+    process.exit(2);
+  }
+};
+const built = arg('built-file') ? read(arg('built-file')) : '';
+console.log(reviewBrief({ issue: { number, title, body: read(bodyFile) }, built, language: arg('language') ?? 'en' }));

package/scripts/review-event.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+// Reacts to a pull request review or push. Reads the GitHub Actions event (GITHUB_EVENT_NAME and
+// GITHUB_EVENT_PATH), updates the issue label and posts the hand-off.
+//   node scripts/review-event.mjs --repo owner/name [--config relevo.yml] [--event-name n] [--event-path file] [--dry-run]
+//   exit 0: handled or nothing to do   exit 2: invalid configuration or bad arguments
+
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { issueFromBranch } from './lib/branch.mjs';
+import { loadConfig } from './lib/config.mjs';
+import { realGh } from './lib/github.mjs';
+import { renderMessage } from './lib/messages.mjs';
+import { planReviewEvent } from './lib/review-events.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;
+const eventName = arg('event-name') ?? process.env.GITHUB_EVENT_NAME;
+const eventPath = arg('event-path') ?? process.env.GITHUB_EVENT_PATH;
+if (!repo || !eventName || !eventPath) fail('give --repo, and the event through GITHUB_EVENT_NAME and GITHUB_EVENT_PATH (or --event-name and --event-path)');
+const payload = JSON.parse(readFileSync(eventPath, 'utf8'));
+
+const prData = payload.pull_request;
+const number = issueFromBranch(prData?.head?.ref);
+if (!number) {
+  console.log(JSON.stringify({ action: 'ignored', reason: 'not a Relevo feature branch' }));
+  process.exit(0);
+}
+
+let event;
+if (eventName === 'pull_request_review') {
+  event = { kind: 'review', state: String(payload.review.state).toLowerCase(), reviewer: payload.review.user.login, body: payload.review.body, url: payload.review.html_url };
+} else if (eventName === 'pull_request' && payload.action === 'synchronize') {
+  event = { kind: 'push' };
+} else {
+  console.log(JSON.stringify({ action: 'ignored', reason: `event ${eventName} is not handled` }));
+  process.exit(0);
+}
+
+const pr = { number: prData.number, url: prData.html_url, author: prData.user.login };
+const labels = JSON.parse(realGh(['api', `repos/${repo}/issues/${number}`])).labels.map((l) => (typeof l === 'string' ? l : l.name));
+const decision = planReviewEvent({ config, event, pr, issue: { number, labels } });
+if (!decision) {
+  console.log(JSON.stringify({ action: 'none' }));
+  process.exit(0);
+}
+
+if (!process.argv.includes('--dry-run')) {
+  const edit = ['issue', 'edit', String(number), '--repo', repo];
+  decision.labels.add.forEach((l) => edit.push('--add-label', l));
+  decision.labels.remove.forEach((l) => edit.push('--remove-label', l));
+  if (edit.length > 5) realGh(edit);
+  if (decision.comment) {
+    realGh(['issue', 'comment', String(number), '--repo', repo, '--body', renderMessage(decision.comment.kind, decision.comment.data, config.language)]);
+  }
+}
+console.log(JSON.stringify(decision));

package/scripts/review-sla.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+// Sends the review reminder, then the escalation. Usage:
+//   node scripts/review-sla.mjs --repo owner/name [--config relevo.yml] [--dry-run]
+//   node scripts/review-sla.mjs --input prs.json [--now ISO] [--config relevo.yml]   (never writes)
+// Prints the decisions as JSON.   exit 0: evaluated   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 } from './lib/github.mjs';
+import { gatherPrs, planSla, slaCommands } from './lib/sla.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;
+const now = arg('now') ? new Date(arg('now')) : new Date();
+let prs;
+if (arg('input')) {
+  prs = JSON.parse(readFileSync(arg('input') === '-' ? 0 : arg('input'), 'utf8'));
+} else {
+  if (!repo) fail('give --repo owner/name (or set GITHUB_REPOSITORY), or --input prs.json');
+  prs = gatherPrs({ gh: realGh, repo, config });
+}
+
+const decisions = planSla({ config, prs, now });
+const dry = process.argv.includes('--dry-run') || Boolean(arg('input'));
+if (!dry) decisions.forEach((d) => slaCommands(d, { repo, config }).forEach((cmd) => realGh(cmd)));
+console.log(JSON.stringify({ decisions }, null, 2));

package/scripts/review-state.mjs

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+// Keeps the state of an on-device review and decides whether a pull request may be opened.
+//   review-state.mjs init <change-dir> [--autopilot off|precheck|verify]   build the checklist from the change's scenarios
+//   review-state.mjs set <id> <ok|fail|pending> [note ...]
+//   review-state.mjs sync <change-dir>            after a fix: keep confirmed lines, retest failed ones, add new scenarios
+//   review-state.mjs capture <path>               record a screenshot that was taken
+//   review-state.mjs audit [<log-file>|-] [--package <id>] [--pid <n>]
+//                                                 audit the device log (stdin by default), write the report;
+//                                                 with --package only that app's lines are audited
+//   review-state.mjs drain                        append the device log (stdin) to evidence/device.log; the skill clears the device's log after it
+//   review-state.mjs audit --accumulated          audit evidence/device.log plus whatever is on stdin
+//   review-state.mjs confirm-env                  the person confirmed in writing that the app does not point to production data
+//   review-state.mjs precheck <n> ok|fail [note]  the agent's own result for a line (autopilot precheck or verify)
+//   review-state.mjs auto <n> <how ...>           the agent verified a line automatically (autopilot verify only)
+//   review-state.mjs auto-list                    print the "Verified automatically" section for the pull request body
+//   review-state.mjs waive <n> <reason ...>       the person waives finding n of the audit, with a written reason
+//   review-state.mjs waived                       print the "Waived findings" section for the pull request body
+//   review-state.mjs agree                        the person agrees to open the pull request
+//   review-state.mjs show                         print the state as JSON
+//   review-state.mjs decide                       exit 0 when the pull request may be opened, 1 when not
+// The state lives in evidence/review-state.json (override with --state). That folder is never committed.
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { checklistFromChange } from './lib/checklist.mjs';
+import { auditLog, auditReport, filterByApp } from './lib/logaudit.mjs';
+import { applyWaivers, autoItem, autoSection, confirmEnv, decidePr, newState, precheckItem, setItem, syncState, waivedSection, waiveFinding } from './lib/review-state.mjs';
+
+const argv = process.argv.slice(2);
+const si = argv.indexOf('--state');
+const statePath = si === -1 ? 'evidence/review-state.json' : argv[si + 1];
+const args = si === -1 ? argv : argv.filter((_, i) => i !== si && i !== si + 1);
+const [command, ...rest] = args;
+
+const fail = (m) => {
+  console.error(m);
+  process.exit(2);
+};
+const load = () => {
+  if (!existsSync(statePath)) fail(`no review in progress (${statePath} not found): run "init" first`);
+  return JSON.parse(readFileSync(statePath, 'utf8'));
+};
+const save = (state) => {
+  mkdirSync(dirname(statePath), { recursive: true });
+  writeFileSync(statePath, `${JSON.stringify(state, null, 2)}\n`);
+};
+
+try {
+  switch (command) {
+    case 'init': {
+      if (!rest[0] || !existsSync(rest[0])) fail('usage: review-state.mjs init <change-directory>');
+      const ai = rest.indexOf('--autopilot');
+      const state = newState(checklistFromChange(rest[0]), { autopilot: ai === -1 ? 'off' : rest[ai + 1] });
+      save(state);
+      console.log(`${state.items.length} checklist item(s) in ${statePath} (autopilot: ${state.autopilot})`);
+      break;
+    }
+    case 'sync': {
+      if (!rest[0] || !existsSync(rest[0])) fail('usage: review-state.mjs sync <change-directory>');
+      const state = syncState(load(), checklistFromChange(rest[0]));
+      save(state);
+      const pending = state.items.filter((i) => i.status === 'pending').length;
+      console.log(`${state.items.length} checklist item(s), ${pending} to test again; the log audit and the agreement must be repeated`);
+      break;
+    }
+    case 'set': {
+      const [id, status, ...note] = rest;
+      const state = setItem(load(), Number(id), status, note.join(' ') || null);
+      save(state);
+      console.log(`item ${id}: ${status}`);
+      break;
+    }
+    case 'capture': {
+      if (!rest[0]) fail('usage: review-state.mjs capture <path>');
+      const state = load();
+      state.captures.push(rest[0]);
+      save(state);
+      console.log(`recorded ${rest[0]}`);
+      break;
+    }
+    case 'drain': {
+      const file = join(dirname(statePath), 'device.log');
+      const text = readFileSync(0, 'utf8');
+      mkdirSync(dirname(file), { recursive: true });
+      appendFileSync(file, text.endsWith('\n') || text === '' ? text : `${text}\n`);
+      console.log(`${text.split('\n').filter(Boolean).length} line(s) added to ${file}`);
+      break;
+    }
+    case 'audit': {
+      const state = load();
+      const pi = rest.indexOf('--package');
+      const pkg = pi === -1 ? null : rest[pi + 1];
+      const pids = rest.flatMap((a, i) => (a === '--pid' ? [rest[i + 1]] : []));
+      const positional = rest.filter((a, i) => !a.startsWith('--') && rest[i - 1] !== '--package' && rest[i - 1] !== '--pid');
+      const accumulated = rest.includes('--accumulated');
+      const kept = accumulated && existsSync(join(dirname(statePath), 'device.log')) ? readFileSync(join(dirname(statePath), 'device.log'), 'utf8') : '';
+      const fresh = positional[0] && positional[0] !== '-' ? readFileSync(positional[0], 'utf8') : readFileSync(0, 'utf8');
+      const raw = accumulated ? `${kept}${kept && !kept.endsWith('\n') ? '\n' : ''}${fresh}` : fresh;
+      if (pi !== -1 && !pkg) fail('--package needs an application id');
+      const { text: source, scope } = pkg ? filterByApp(raw, { package: pkg, pids }) : { text: raw, scope: null };
+      const audit = auditLog(source, { scope });
+      state.audit = { verdict: audit.verdict, counts: audit.counts, findings: audit.findings, scope, ...(audit.reason ? { reason: audit.reason } : {}) };
+      applyWaivers(state);
+      audit.verdict = state.audit.verdict;
+      save(state);
+      writeFileSync(join(dirname(statePath), 'review-report.md'), auditReport(audit, { scope }));
+      console.log(audit.verdict);
+      if (audit.reason) console.log(`  ${audit.reason}`);
+      audit.findings.slice(0, 10).forEach((f, i) => console.log(`  ${i + 1}. ${f.class}: ${f.excerpt}${f.waived ? ` (waived: ${f.reason})` : ''}`));
+      break;
+    }
+    case 'confirm-env': {
+      const state = confirmEnv(load());
+      save(state);
+      console.log('recorded: the person confirmed that the app does not point to production data');
+      break;
+    }
+    case 'precheck': {
+      const [id, result, ...note] = rest;
+      const state = precheckItem(load(), Number(id), result, note.join(' ') || null);
+      save(state);
+      console.log(`item ${id}: pre-check ${result} (the person still confirms it)`);
+      break;
+    }
+    case 'auto': {
+      const [id, ...how] = rest;
+      const state = autoItem(load(), Number(id), how.join(' '));
+      save(state);
+      console.log(`item ${id}: verified automatically`);
+      break;
+    }
+    case 'auto-list':
+      process.stdout.write(autoSection(load()));
+      break;
+    case 'waive': {
+      const [number, ...reason] = rest;
+      const state = waiveFinding(load(), number, reason.join(' '));
+      save(state);
+      writeFileSync(join(dirname(statePath), 'review-report.md'), auditReport(state.audit, { scope: state.audit.scope }));
+      console.log(`finding ${number} waived; the verdict is ${state.audit.verdict}`);
+      break;
+    }
+    case 'waived':
+      process.stdout.write(waivedSection(load()));
+      break;
+    case 'agree': {
+      const state = load();
+      state.agreed = true;
+      save(state);
+      console.log('the person agreed to open the pull request');
+      break;
+    }
+    case 'show':
+      console.log(JSON.stringify(load(), null, 2));
+      break;
+    case 'decide': {
+      const { open, reasons } = decidePr(load());
+      if (open) console.log('the pull request may be opened');
+      else {
+        console.log('the pull request must NOT be opened yet:');
+        reasons.forEach((r) => console.log(`  - ${r}`));
+      }
+      process.exit(open ? 0 : 1);
+      break;
+    }
+    default:
+      fail('usage: review-state.mjs <init|set|sync|capture|drain|audit|waive|waived|confirm-env|precheck|auto|auto-list|agree|show|decide> [...]');
+  }
+} catch (err) {
+  fail(err.message);
+}

package/scripts/review-who.mjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+// Says whether the person running the review is the assignee of the issue. Usage:
+//   node scripts/review-who.mjs --assignee <login> --login <login>
+// exit 0: the same person (case does not matter)   exit 1: different people, prints both   exit 2: bad arguments
+
+const arg = (name) => {
+  const i = process.argv.indexOf(`--${name}`);
+  return i === -1 ? undefined : process.argv[i + 1];
+};
+const assignee = arg('assignee');
+const login = arg('login');
+if (!assignee || !login) {
+  console.error('usage: review-who.mjs --assignee <login> --login <login>');
+  process.exit(2);
+}
+if (assignee.toLowerCase() === login.toLowerCase()) {
+  console.log(`${login} is the assignee`);
+  process.exit(0);
+}
+console.log(`the issue is assigned to ${assignee}, but ${login} is running the review`);
+process.exit(1);

package/scripts/role-skills.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+// Resolves the extra skills of a role to the files an agent may read. Usage:
+//   node scripts/role-skills.mjs --role <dev|qa|issue|review|fix> [--platform <name>] [--base origin/dev] [--config relevo.yml]
+// Prints JSON: { role, platform, base, skills: [ { name, path, scripts } | { name, left_out, reason } ] }.
+// Only skills present on the base branch are used, so a skill added by the branch is never trusted.
+//   exit 0: printed (skills may be left out)   exit 1: the profile cannot be resolved   exit 2: bad usage or invalid relevo.yml
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadConfig } from './lib/config.mjs';
+import { resolveRoleSkills } from './lib/role-skills.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 role = arg('role');
+if (!role) fail('usage: role-skills.mjs --role <dev|qa|issue|review|fix> [--platform name] [--base origin/dev] [--config relevo.yml]', 2);
+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);
+const platform = name ? loaded.config.platforms[name] : undefined;
+if (!platform) fail(`give --platform <${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 pluginRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const resolved = resolveProfile({ platform, pluginRoot, read });
+if (!resolved.ok) fail(resolved.errors.join('\n'), 1);
+
+const baseRef = arg('base') ?? `origin/${loaded.config.branches.base}`;
+const git = (args) => execFileSync('git', args, { cwd: base, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+try {
+  const skills = resolveRoleSkills({ role, profile: resolved.profile, git, baseRef, allowScripts: loaded.config.skills.allow_scripts });
+  console.log(JSON.stringify({ role, platform: name, base: baseRef, skills }, null, 2));
+} catch (err) {
+  fail(err.message, 2);
+}

package/scripts/run-usage.mjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+// Prints one line with what a cloud run used, read from the execution log of the agent runner. Usage:
+//   node scripts/run-usage.mjs --file <execution_file> [--subscription]
+// --subscription says that the cost is notional. Prints nothing when the log is missing or has no usage.
+// It never fails: exit 0 always, so a step that posts the line cannot fail a run.
+
+import { readFileSync } from 'node:fs';
+import { readUsage, usageLine } from './lib/run-usage.mjs';
+
+const arg = (name) => {
+  const i = process.argv.indexOf(`--${name}`);
+  return i === -1 ? undefined : process.argv[i + 1];
+};
+
+let text = '';
+try {
+  if (arg('file')) text = readFileSync(arg('file'), 'utf8');
+} catch {
+  text = '';
+}
+const line = usageLine(readUsage(text), { subscription: process.argv.includes('--subscription') });
+if (line) console.log(line);

package/scripts/scan-diff.mjs

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+// Scans a unified diff on stdin for temporary markers and credentials.
+// Usage: git diff --cached | node scripts/scan-diff.mjs
+//   exit 0: clean   exit 1: findings (nothing should be committed or pushed)
+
+import { readFileSync } from 'node:fs';
+import { formatFindings, scanDiff } from './lib/scan.mjs';
+
+const findings = scanDiff(readFileSync(0, 'utf8'));
+if (findings.length === 0) {
+  console.log('no temporary markers or credentials found');
+  process.exit(0);
+}
+console.error(formatFindings(findings));
+console.error(`\n${findings.length} finding(s): do not commit or push until they are removed`);
+process.exit(1);