@elalfner/relevo 0.0.0-stage → 0.3.0

package/scripts/branch-state.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+// Says what a feature branch on the remote holds. Usage:
+//   node scripts/branch-state.mjs <base> <branch> <change_id>
+// Prints one word: absent (no such branch), empty, spec-only or implementation.
+// spec-only means every changed path is under openspec/changes/<change_id>/. exit 0: printed   exit 2: bad arguments or git failed
+
+import { execFileSync } from 'node:child_process';
+import { classifyBranchChanges } from './lib/branch.mjs';
+
+const [base, branch, id] = process.argv.slice(2);
+if (!base || !branch || !id) {
+  console.error('usage: branch-state.mjs <base> <branch> <change_id>');
+  process.exit(2);
+}
+const git = (...args) => execFileSync('git', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+
+try {
+  // The branch may not exist: fetching it then fails, which is the answer.
+  try {
+    git('fetch', '--quiet', 'origin', base, branch);
+  } catch {
+    git('fetch', '--quiet', 'origin', base);
+    console.log('absent');
+    process.exit(0);
+  }
+  const paths = git('diff', '--name-only', `origin/${base}...origin/${branch}`).split('\n');
+  console.log(classifyBranchChanges(paths, id));
+} catch (err) {
+  console.error(`could not read the branch: ${(err.stderr || err.message).toString().trim()}`);
+  process.exit(2);
+}

package/scripts/branch-work.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+// Says whether the current branch holds implementation beyond the change's specification. Usage:
+//   node scripts/branch-work.mjs --base dev --change 31-summary
+// Prints {"implementation":true|false,"files":[...]}.   exit 0: there is code to correct   exit 1: only the specification   exit 2: bad arguments
+
+import { execFileSync } from 'node:child_process';
+import { hasImplementation } from './lib/branch-work.mjs';
+
+const arg = (name) => {
+  const i = process.argv.indexOf(`--${name}`);
+  return i === -1 ? undefined : process.argv[i + 1];
+};
+const base = arg('base');
+const change = arg('change');
+if (!base || !change) {
+  console.error('usage: branch-work.mjs --base <branch> --change <change folder name>');
+  process.exit(2);
+}
+const paths = execFileSync('git', ['diff', '--name-only', `origin/${base}...HEAD`], { encoding: 'utf8' }).split('\n').filter(Boolean);
+const result = hasImplementation(paths, `openspec/changes/${change}`);
+console.log(JSON.stringify(result));
+if (!result.implementation) {
+  console.error('the branch holds only the specification: delete the remote branch and apply relevo:ready again');
+  process.exit(1);
+}

package/scripts/can-edit-issue.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+// Tells whether an issue's description may be rewritten. Usage:
+//   gh issue view 42 --json number,title,body,state,labels | node scripts/can-edit-issue.mjs [--input issue.json] [--config relevo.yml]
+// Prints `editable`, or `refused: <label> - <reason>` (the label is left out when the issue is closed).
+// exit 0: editable   exit 1: refused   exit 2: bad arguments
+
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { loadConfig } from './lib/config.mjs';
+import { canEditIssue } from './lib/can-edit-issue.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);
+};
+
+let issue;
+try {
+  issue = JSON.parse(readFileSync(arg('input') ?? 0, 'utf8'));
+} catch (err) {
+  fail(`cannot read the issue JSON: ${err.message}`);
+}
+if (!issue || typeof issue !== 'object' || !Array.isArray(issue.labels) || typeof issue.state !== 'string') {
+  fail('the JSON must come from `gh issue view --json number,title,body,state,labels`');
+}
+
+let overrides = {};
+const configPath = resolve(arg('config') ?? 'relevo.yml');
+if (existsSync(configPath)) {
+  const loaded = loadConfig(readFileSync(configPath, 'utf8'));
+  if (!loaded.ok) fail(loaded.errors.map((e) => `error: ${e.message}`).join('\n'));
+  overrides = loaded.config.labels ?? {};
+}
+
+const r = canEditIssue(issue, overrides);
+if (r.editable) {
+  console.log('editable');
+  process.exit(0);
+}
+console.log(`refused: ${r.label ? `${r.label} - ` : ''}${r.reason}`);
+process.exit(1);

package/scripts/capture.mjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+// Takes a screenshot of the device and saves it as evidence/<name>.png. Never opens the image.
+//   node scripts/capture.mjs <name> [--dir evidence]
+// Names are plain file names (letters, digits, "_", "-", "."), never paths.
+
+import { capture, listDevices, pickDevice, safeCaptureName } from './lib/device.mjs';
+
+const name = process.argv[2];
+const di = process.argv.indexOf('--dir');
+const dir = di === -1 ? 'evidence' : process.argv[di + 1];
+if (!name || name.startsWith('--')) {
+  console.error('usage: capture.mjs <name> [--dir evidence]');
+  process.exit(2);
+}
+try {
+  safeCaptureName(name); // a bad name is refused before adb is run
+  const serial = pickDevice(listDevices(), process.env.ANDROID_SERIAL ?? null);
+  console.log(capture({ name, dir, serial }));
+} catch (err) {
+  console.error(err.code === 'ENOENT' ? 'adb is not installed: install the Android platform tools' : err.message);
+  process.exit(2);
+}

package/scripts/check-archive.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+// After `openspec archive`, checks that the archive changed nothing outside openspec/.
+//   node scripts/check-archive.mjs [--dir openspec]
+//   exit 0: only the specifications folder changed   exit 1: something else changed, or nothing changed
+
+import { execFileSync } from 'node:child_process';
+import { checkArchiveChanges, pathsFromPorcelain } from './lib/archive-check.mjs';
+
+const di = process.argv.indexOf('--dir');
+const dir = di === -1 ? 'openspec' : process.argv[di + 1];
+const paths = pathsFromPorcelain(execFileSync('git', ['status', '--porcelain', '--untracked-files=all'], { encoding: 'utf8' }));
+const result = checkArchiveChanges(paths, dir);
+if (result.ok) {
+  console.log(`the archive changed ${paths.length} path(s), all under ${dir}/`);
+  process.exit(0);
+}
+if (result.empty) console.log('the archive changed nothing: was the change already archived?');
+else console.log(`the archive changed files outside ${dir}/: ${result.outside.join(', ')}`);
+process.exit(1);

package/scripts/check-issue.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+// Checks a drafted issue. Usage:
+//   (--repo-root <folder>, default the current folder, is where the files of a Design reference must exist)
+//   node scripts/check-issue.mjs --title "Short plain title" --body-file issue.md [--rules-file CLAUDE.md] [--platforms web,api] [--links acme/api,acme/design]
+// --platforms lists the names of the platforms of relevo.yml: with more than one the draft needs a `Platform:` line.
+// --rules-file is the project rules file or files, comma separated (`qa.rules_from`), which an `Allow-paths:` line can never list.
+// Prints the counts and every problem. exit 0: ready to create   exit 1: problems   exit 2: bad arguments
+
+import { readFileSync } from 'node:fs';
+import { checkIssueDraft } from './lib/issue-check.mjs';
+
+const arg = (name) => {
+  const i = process.argv.indexOf(`--${name}`);
+  return i === -1 ? undefined : process.argv[i + 1];
+};
+const title = arg('title');
+const file = arg('body-file');
+if (title === undefined || !file) {
+  console.error('usage: check-issue.mjs --title "<title>" --body-file <file>');
+  process.exit(2);
+}
+let body;
+try {
+  body = readFileSync(file, 'utf8');
+} catch (err) {
+  console.error(`cannot read ${file}: ${err.message}`);
+  process.exit(2);
+}
+const platformNames = (arg('platforms') ?? '').split(',').map((f) => f.trim()).filter(Boolean);
+const platforms = platformNames.length ? Object.fromEntries(platformNames.map((n) => [n, {}])) : null;
+const links = (arg('links') ?? '').split(',').map((f) => f.trim()).filter(Boolean);
+const r = checkIssueDraft({ title, body, platforms, links, repoRoot: arg('repo-root') ?? process.cwd(), rulesFile: (arg('rules-file') ?? '').split(',').map((f) => f.trim()).filter(Boolean) });
+const allows = r.allowPaths.length ? `, allows changes to ${r.allowPaths.join(', ')}` : '';
+console.log(`${r.scenarios} scenario(s), ${r.edgeCases} edge case(s), depends on ${[...r.dependsOn.map((n) => `#${n}`), ...r.dependsOnExternal.map((d) => `${d.repo}#${d.number}`)].join(', ') || 'nothing'}${allows}`);
+r.warnings.forEach((w) => console.error(`warning: ${w}`));
+if (r.ok) {
+  console.log('ready to create');
+  process.exit(0);
+}
+r.problems.forEach((p) => console.error(`problem: ${p}`));
+process.exit(1);

package/scripts/checklist.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// Prints the review checklist of a change. Usage:
+//   node scripts/checklist.mjs openspec/changes/<id> [--json | --count]
+// Default output is a Markdown checklist, one line per scenario of the change's specs.
+// --state <file> ticks the lines the person confirmed in an on-device review (see review-state.mjs).
+
+import { existsSync, readFileSync } from 'node:fs';
+import { checklistFromChange, checklistMarkdown } from './lib/checklist.mjs';
+
+const dir = process.argv[2];
+if (!dir || dir.startsWith('--') || !existsSync(dir)) {
+  console.error('usage: checklist.mjs <change-directory> [--json | --count]');
+  process.exit(2);
+}
+const items = checklistFromChange(dir);
+if (process.argv.includes('--count')) console.log(items.length);
+else if (process.argv.includes('--json')) console.log(JSON.stringify(items, null, 2));
+else {
+  const si = process.argv.indexOf('--state');
+  const statuses = {};
+  const autos = {};
+  if (si !== -1 && existsSync(process.argv[si + 1])) {
+    JSON.parse(readFileSync(process.argv[si + 1], 'utf8')).items.forEach((i) => {
+      statuses[i.id] = i.status;
+      if (i.auto) autos[i.id] = i.auto;
+    });
+  }
+  console.log(checklistMarkdown(items, statuses, autos));
+}

package/scripts/cli.mjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+// relevo install | update | doctor | version. See scripts/lib/cli.mjs.
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { USAGE, execute, parseArgs } from './lib/cli.mjs';
+
+const here = (p) => fileURLToPath(new URL(p, import.meta.url));
+const parsed = parseArgs(process.argv.slice(2));
+if (parsed.error) {
+  process.stderr.write(`${parsed.error}\n${USAGE}\n`);
+  process.exit(2);
+}
+if (parsed.command === 'help') {
+  process.stdout.write(`${USAGE}\n`);
+  process.exit(0);
+}
+
+const run = (cmd, args) => {
+  const r = spawnSync(cmd, args, { encoding: 'utf8' });
+  return { code: r.status ?? 1, output: `${r.stdout ?? ''}${r.stderr ?? ''}` };
+};
+const has = (cmd) => spawnSync(cmd, ['--version'], { encoding: 'utf8' }).error === undefined;
+const version = JSON.parse(readFileSync(here('../package.json'), 'utf8')).version;
+
+const { code, lines } = execute(parsed, { run, has, version, doctorScript: here('./doctor.mjs') });
+process.stdout.write(`${lines.join('\n')}\n`);
+process.exit(code);

package/scripts/commit-change.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+// Commits named files, and nothing else, after checking them. Usage:
+//   node scripts/commit-change.mjs --message "feat: title (#42)" [--allow pubspec.yaml,pubspec.lock] [--rules-file CLAUDE.md,docs/rules.md]
+//     [--within apps/web --change 42-title] -- path [path ...]
+// --within is the folder of the platform of the issue: files outside it are refused, except the specification of --change, GLOSSARY.md and docs/adr/.
+// It stages the paths, refuses protected paths, scans the staged diff for temporary markers and credentials, and
+// commits only when nothing was found. With no --rules-file it reads qa.rules_from from relevo.yml, if there is one.
+//   exit 0: committed (prints the short hash)   exit 1: refused, nothing committed (prints what and where)
+//   exit 2: bad arguments, "." or "-A" as a path, or git failed
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { loadConfig } from './lib/config.mjs';
+import { commitChange, refusalText } from './lib/commit-change.mjs';
+
+const argv = process.argv.slice(2);
+const sep = argv.indexOf('--');
+const options = sep === -1 ? argv : argv.slice(0, sep);
+const paths = sep === -1 ? [] : argv.slice(sep + 1);
+const opt = (name) => {
+  const i = options.indexOf(`--${name}`);
+  return i === -1 ? undefined : options[i + 1];
+};
+const fail = (message) => {
+  console.error(message);
+  process.exit(2);
+};
+
+if (!opt('message') || paths.length === 0) fail('usage: commit-change.mjs --message "<message>" [--allow a,b] [--rules-file path] -- <path> [path ...]');
+
+let rulesFile = opt('rules-file') ? opt('rules-file').split(',').map((f) => f.trim()).filter(Boolean) : null;
+if (!rulesFile && existsSync('relevo.yml')) {
+  const loaded = loadConfig(readFileSync('relevo.yml', 'utf8'));
+  if (loaded.ok) rulesFile = loaded.config.qa.rules_from;
+}
+const allow = (opt('allow') ?? '').split(',').map((p) => p.trim()).filter(Boolean);
+const git = (args) => execFileSync('git', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+
+try {
+  const result = commitChange({ git, message: opt('message'), paths, allow, rulesFile, within: opt('within') ?? null, change: opt('change') ?? null });
+  if (result.ok) {
+    console.log(result.commit);
+    process.exit(0);
+  }
+  console.error('not committed:');
+  console.error(refusalText(result));
+  process.exit(1);
+} catch (err) {
+  fail(`${err.message}${err.stderr ? `\n${String(err.stderr).trim()}` : ''}`);
+}

package/scripts/conflict-scope.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+// Says whether every conflicted file is inside openspec/. Usage:
+//   node scripts/conflict-scope.mjs               reads `git diff --name-only --diff-filter=U`
+//   node scripts/conflict-scope.mjs --paths       reads the paths from stdin, one per line
+// exit 0: all inside (or none)   exit 1: prints the files outside   exit 2: bad arguments
+
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { conflictScope } from './lib/archive-check.mjs';
+
+const fromStdin = process.argv.includes('--paths');
+const raw = fromStdin ? readFileSync(0, 'utf8') : execFileSync('git', ['diff', '--name-only', '--diff-filter=U'], { encoding: 'utf8' });
+const result = conflictScope(raw.split('\n').filter(Boolean));
+if (result.ok) {
+  console.log(result.paths.length === 0 ? 'no conflicts' : `all ${result.paths.length} conflicted file(s) are under openspec/`);
+  process.exit(0);
+}
+console.log(`conflicts outside openspec/: ${result.outside.join(', ')}`);
+process.exit(1);

package/scripts/design-fetch.mjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+// Fetches the design references of an issue so the builder can read them. Usage:
+//   node scripts/design-fetch.mjs --issue 42 [--repo owner/name] [--out .relevo-design] [--config relevo.yml] [--repo-root .]
+//   node scripts/design-fetch.mjs --body-file issue.md ...      (the body from a file instead of GitHub, for tests)
+// The references come only from the issue. Pasted attachments are downloaded only when design.images is true; files of
+// linked repositories are read through `gh api`. Downloads go to <out> (default .relevo-design), which is added to
+// .git/info/exclude so it is never committed, with a manifest.json. The files of this repository are not copied.
+//   exit 0: every reference is available   exit 1: some reference was refused (the reasons are printed)   exit 2: bad arguments
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { loadConfig } from './lib/config.mjs';
+import { fetchReferences } from './lib/design-fetch.mjs';
+import { parseDesign } from './lib/issue-parse.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 issue = arg('issue');
+const bodyFile = arg('body-file');
+if (!issue && !bodyFile) fail('usage: design-fetch.mjs --issue <n> [--repo owner/name] [--out .relevo-design] [--config relevo.yml] [--repo-root .]', 2);
+
+const configPath = resolve(arg('config') ?? 'relevo.yml');
+let config = { design: { images: false }, links: [] };
+if (existsSync(configPath)) {
+  const loaded = loadConfig(readFileSync(configPath, 'utf8'));
+  if (!loaded.ok) fail(`relevo.yml is invalid:\n${loaded.errors.map((e) => `  ${e.message}`).join('\n')}`, 2);
+  config = loaded.config;
+}
+const repoRoot = resolve(arg('repo-root') ?? '.');
+const out = resolve(arg('out') ?? '.relevo-design');
+
+let body;
+if (bodyFile) {
+  body = readFileSync(bodyFile, 'utf8');
+} else {
+  const repo = arg('repo') ?? process.env.GITHUB_REPOSITORY;
+  const args = ['issue', 'view', String(issue), '--json', 'body', '-q', '.body', ...(repo ? ['--repo', repo] : [])];
+  try {
+    body = execFileSync('gh', args, { encoding: 'utf8' });
+  } catch (error) {
+    fail(`the issue could not be read: ${String(error.message).split('\n')[0]}`, 2);
+  }
+}
+
+const design = parseDesign(body);
+if (!design.present) {
+  console.log('the issue has no Design reference');
+  process.exit(0);
+}
+
+const linksToken = process.env.GH_LINKS_TOKEN;
+const gh = (args) => execFileSync('gh', args, { encoding: 'utf8', env: { ...process.env, ...(linksToken ? { GH_TOKEN: linksToken } : {}) } });
+const result = await fetchReferences({
+  references: design.references,
+  images: config.design.images === true,
+  links: config.links,
+  exists: (path) => existsSync(join(repoRoot, path)),
+  fetch: globalThis.fetch,
+  gh,
+  token: process.env.GH_TOKEN ?? process.env.GITHUB_TOKEN ?? null,
+});
+const refused = [...design.problems.map((p) => ({ reference: 'Design reference', reason: p })), ...result.refused];
+
+const EXT = { png: 'png', jpeg: 'jpg', gif: 'gif', webp: 'webp' };
+const manifest = { files: [], refused };
+mkdirSync(out, { recursive: true });
+result.files.forEach((f, i) => {
+  const entry = { reference: f.reference, kind: f.kind, type: f.type };
+  if (f.kind === 'path') {
+    entry.file = f.path;
+  } else {
+    const base = f.kind === 'repo-file' ? f.path.split('/').pop().replace(/[^A-Za-z0-9._-]/g, '_') : `attachment.${EXT[f.type]}`;
+    const name = `${String(i + 1).padStart(2, '0')}-${base}`;
+    writeFileSync(join(out, name), f.buf);
+    entry.file = join(out, name);
+    entry.bytes = f.buf.length;
+  }
+  manifest.files.push(entry);
+});
+writeFileSync(join(out, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`);
+
+// Keep the downloads out of git: a local exclusion, never committed.
+try {
+  const exclude = execFileSync('git', ['rev-parse', '--git-path', 'info/exclude'], { encoding: 'utf8', cwd: repoRoot }).trim();
+  const file = resolve(repoRoot, exclude);
+  const pattern = `/${out.startsWith(`${repoRoot}/`) ? out.slice(repoRoot.length + 1) : '.relevo-design'}/`;
+  mkdirSync(join(file, '..'), { recursive: true });
+  const current = existsSync(file) ? readFileSync(file, 'utf8') : '';
+  if (!current.split('\n').includes(pattern)) appendFileSync(file, `${current && !current.endsWith('\n') ? '\n' : ''}${pattern}\n`);
+} catch { /* not a git repository: nothing to exclude */ }
+
+manifest.files.forEach((f) => console.log(`available: ${f.reference} -> ${f.file}${f.bytes ? ` (${f.bytes} bytes)` : ''}`));
+refused.forEach((r) => console.error(`refused: ${r.reference}: ${r.reason}`));
+console.log(`${manifest.files.length} available, ${refused.length} refused; manifest in ${join(out, 'manifest.json')}`);
+process.exit(refused.length > 0 ? 1 : 0);

package/scripts/device.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+// Finds the Android device to review on. Prints its serial, or explains what is wrong.
+//   exit 0: a device was found   exit 2: none, unauthorised or several (ANDROID_SERIAL picks one)
+
+import { listDevices, pickDevice } from './lib/device.mjs';
+
+try {
+  console.log(pickDevice(listDevices(), process.env.ANDROID_SERIAL ?? null));
+} catch (err) {
+  console.error(err.code === 'ENOENT' ? 'adb is not installed: install the Android platform tools' : err.message);
+  process.exit(2);
+}

package/scripts/digest.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+// Posts the daily digest as a comment on the issue named by digest.issue (chat tools subscribe to GitHub events).
+// Posts nothing when nothing is waiting, and nothing on weekends.
+//   node scripts/digest.mjs --repo owner/name [--config relevo.yml] [--dry-run] [--now ISO]
+//   node scripts/digest.mjs --input state.json [--now ISO]     (never writes)
+// Prints the digest text, or nothing.   exit 0: done   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, renderDigest } 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 now = arg('now') ? new Date(arg('now')) : new Date();
+const day = now.getUTCDay();
+if (day === 0 || day === 6) process.exit(0);
+
+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 });
+}
+
+const text = renderDigest(buildStatus({ config, ...data, me: null, now }), config.language);
+if (!text) process.exit(0);
+const dry = process.argv.includes('--dry-run') || Boolean(arg('input'));
+if (!dry) {
+  if (!config.digest.issue) fail('digest.issue is not set in relevo.yml: name the issue where the digest is posted');
+  realGh(['issue', 'comment', String(config.digest.issue), '--repo', repo, '--body', text]);
+}
+console.log(text);

package/scripts/doctor.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+// Checks that the machine, the repository and GitHub are ready for Relevo. Read-only: it changes nothing.
+//   node scripts/doctor.mjs [--repo owner/name] [--json]
+// exit 0: no check failed (warnings allowed)   exit 1: at least one check failed
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { gatherFacts, readOnlyGh, renderReport, runChecks } from './lib/doctor.mjs';
+
+const arg = (name) => {
+  const i = process.argv.indexOf(`--${name}`);
+  return i === -1 ? undefined : process.argv[i + 1];
+};
+
+let repo = arg('repo') ?? process.env.GITHUB_REPOSITORY ?? null;
+const tool = (name, args) => execFileSync(name, args, { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'] });
+const gh = (args) => tool('gh', args);
+if (!repo) {
+  try {
+    repo = tool('gh', ['repo', 'view', '--json', 'nameWithOwner', '-q', '.nameWithOwner']).trim() || null;
+  } catch {
+    repo = null;
+  }
+}
+
+// Files of a skill folder, for the comparison with skills-lock.json.
+const readFolder = (dir) => readdirSync(dir, { withFileTypes: true }).flatMap((e) => {
+  const path = `${dir}/${e.name}`;
+  if (e.isDirectory()) return readFolder(path).map((f) => ({ ...f, path: `${e.name}/${f.path}` }));
+  return e.isFile() ? [{ path: e.name, content: readFileSync(path) }] : [];
+});
+
+const facts = gatherFacts({
+  tool,
+  gh: readOnlyGh(gh),
+  exists: existsSync,
+  read: (p) => readFileSync(p, 'utf8'),
+  listDir: (p) => readdirSync(p),
+  skillDirs: ['.claude/skills', '.agents/skills', `${homedir()}/.claude/skills`],
+  git: (args) => tool('git', args),
+  readFolder,
+  repo,
+});
+const results = runChecks(facts);
+console.log(process.argv.includes('--json') ? JSON.stringify(results, null, 2) : renderReport(results));
+process.exit(results.some((x) => x.status === 'fail') ? 1 : 0);

package/scripts/fix-guard.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+// Checks that the specification was updated before any code was written for a fix. Usage:
+//   node scripts/fix-guard.mjs openspec/changes/<id>
+//   exit 0: the developer may run   exit 1: the specification is not ready (reasons printed)
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { checkSpecFirst } from './lib/fix-guard.mjs';
+
+const changeDir = (process.argv[2] ?? '').replace(/\/+$/, '');
+if (!changeDir || !existsSync(changeDir)) {
+  console.error('usage: fix-guard.mjs <change-directory>');
+  process.exit(2);
+}
+const git = (...args) => execFileSync('git', args, { encoding: 'utf8' });
+const lines = (text) => text.split('\n').filter(Boolean);
+
+const changedFiles = [...new Set([...lines(git('diff', '--name-only', 'HEAD')), ...lines(git('ls-files', '--others', '--exclude-standard'))])];
+
+// Lines added to tracked files (diff against HEAD) plus every line of new, untracked files.
+const trackedAdded = (path) => lines(git('diff', '-U0', 'HEAD', '--', path)).filter((l) => l.startsWith('+') && !l.startsWith('+++'));
+const untrackedAdded = (prefix) => changedFiles
+  .filter((f) => (f === prefix || f.startsWith(prefix)) && git('ls-files', '--', f).trim() === '')
+  .flatMap((f) => lines(readFileSync(f, 'utf8')).map((l) => `+${l}`));
+const added = (path, prefix) => [...trackedAdded(path), ...untrackedAdded(prefix)];
+
+const { ok, reasons } = checkSpecFirst({
+  changedFiles,
+  changeDir,
+  specLinesAdded: added(`${changeDir}/specs`, `${changeDir}/specs/`),
+  taskLinesAdded: added(`${changeDir}/tasks.md`, `${changeDir}/tasks.md`),
+});
+if (ok) console.log('the specification is ready: the developer may run');
+else {
+  console.log('the specification is NOT ready; the developer must not run yet:');
+  reasons.forEach((r) => console.log(`  - ${r}`));
+}
+process.exit(ok ? 0 : 1);

package/scripts/fix-stash.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+// Keeps the work of a fix that QA rejected, and gives it back. Usage:
+//   node scripts/fix-stash.mjs save --issue 42 --iteration 2   save the working tree (untracked files included)
+//   node scripts/fix-stash.mjs find --issue 42                 print the newest stash of the issue as JSON
+//   node scripts/fix-stash.mjs pop  --issue 42                 restore it; on a conflict it stays listed
+//   node scripts/fix-stash.mjs drop --issue 42                 discard it (only after the person's written confirmation)
+// exit 0: done   exit 1: nothing to do, or a conflict   exit 2: bad arguments
+
+import { execFileSync } from 'node:child_process';
+import { findStash, stashMessage } from './lib/fix-stash.mjs';
+
+const [command] = process.argv.slice(2);
+const arg = (name) => {
+  const i = process.argv.indexOf(`--${name}`);
+  return i === -1 ? undefined : process.argv[i + 1];
+};
+const git = (...args) => execFileSync('git', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+const issue = arg('issue');
+if (!['save', 'find', 'pop', 'drop'].includes(command) || !/^\d+$/.test(issue ?? '') || (command === 'save' && !/^\d+$/.test(arg('iteration') ?? ''))) {
+  console.error('usage: fix-stash.mjs save --issue N --iteration K | find|pop|drop --issue N');
+  process.exit(2);
+}
+
+if (command === 'save') {
+  if (git('status', '--porcelain').trim() === '') {
+    console.error('the working tree is clean: there is nothing to save');
+    process.exit(1);
+  }
+  const message = stashMessage(issue, arg('iteration'));
+  git('stash', 'push', '--include-untracked', '-m', message);
+  console.log(`saved as "${message}". Resume with /relevo:fix ${issue}; the stash is local to this clone.`);
+  process.exit(0);
+}
+
+const found = findStash(git('stash', 'list'), issue);
+if (!found) {
+  if (command === 'find') console.log('null');
+  else console.error(`no saved fix for issue ${issue}`);
+  process.exit(1);
+}
+if (command === 'find') {
+  console.log(JSON.stringify(found));
+  process.exit(0);
+}
+if (command === 'drop') {
+  git('stash', 'drop', found.ref);
+  console.log(`dropped "${found.message}"`);
+  process.exit(0);
+}
+try {
+  git('stash', 'pop', found.ref);
+  console.log(`restored "${found.message}"`);
+} catch (error) {
+  const files = git('diff', '--name-only', '--diff-filter=U').split('\n').filter(Boolean);
+  console.error(`restoring "${found.message}" conflicts with the branch in: ${files.join(', ') || 'unknown files'}. The stash is kept.`);
+  process.exit(1);
+}