@elalfner/relevo 0.0.0-stage → 0.3.0

package/scripts/fix-state.mjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+// Prints what a fix does to an issue's labels. Usage:
+//   node scripts/fix-state.mjs --current "relevo:qa-failed,bug" [--config relevo.yml]
+// Output: {"allowed":true,"from":"qa-failed","to":"built","notify":"assignee","labels":{"add":[...],"remove":[...]}}
+//   exit 0: a fix may run   exit 1: not allowed in this state   exit 2: bad arguments
+
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { loadConfig } from './lib/config.mjs';
+import { fixOutcome } from './lib/fix.mjs';
+
+const arg = (name) => {
+  const i = process.argv.indexOf(`--${name}`);
+  return i === -1 ? undefined : process.argv[i + 1];
+};
+if (arg('current') === undefined) {
+  console.error('usage: fix-state.mjs --current "label,label" [--config relevo.yml]');
+  process.exit(2);
+}
+let overrides = {};
+const path = resolve(arg('config') ?? 'relevo.yml');
+if (existsSync(path)) {
+  const loaded = loadConfig(readFileSync(path, 'utf8'));
+  if (loaded.ok) overrides = loaded.config.labels;
+}
+const result = fixOutcome(arg('current').split(',').map((s) => s.trim()).filter(Boolean), overrides);
+console.log(JSON.stringify(result));
+process.exit(result.allowed ? 0 : 1);

package/scripts/fix-tasks.mjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+// Checks the task list of a change around a fix. Usage:
+//   node scripts/fix-tasks.mjs --file openspec/changes/31-x/tasks.md --stage before|after
+//   before: run before the developer; after: run after QA passes.
+// exit 0: ok   exit 1: prints why not   exit 2: bad arguments
+
+import { existsSync, readFileSync } from 'node:fs';
+import { checkFixTasks } from './lib/tasks-file.mjs';
+
+const arg = (name) => {
+  const i = process.argv.indexOf(`--${name}`);
+  return i === -1 ? undefined : process.argv[i + 1];
+};
+const file = arg('file');
+const stage = arg('stage');
+if (!file || !['before', 'after'].includes(stage) || !existsSync(file)) {
+  console.error('usage: fix-tasks.mjs --file <tasks.md> --stage before|after');
+  process.exit(2);
+}
+const result = checkFixTasks(readFileSync(file, 'utf8'), stage);
+if (!result.ok) result.reasons.forEach((r) => console.log(r));
+process.exit(result.ok ? 0 : 1);

package/scripts/go-local.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+// Builds an issue on this machine, with your own Claude session, as the cloud would. Usage:
+//   node scripts/go-local.mjs <issue> [--config relevo.yml] [--dry-run]
+// It runs `claude -p "/relevo:go <issue>"` in a separate git worktree (so your uncommitted changes do not matter),
+// with the turn and cost limits of relevo.yml and the closed tool lists of the workflow. The worktree is removed when
+// the run ends cleanly and kept otherwise.
+//   exit 0: done   exit 2: bad usage or something missing   other: the exit status of the run
+
+import { execFileSync, spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { loadConfig } from './lib/config.mjs';
+import { runLocal } from './lib/go-local.mjs';
+
+const args = process.argv.slice(2);
+const flag = (name) => args.includes(`--${name}`);
+const opt = (name) => {
+  const i = args.indexOf(`--${name}`);
+  return i === -1 ? undefined : args[i + 1];
+};
+const issue = args.find((a, i) => !a.startsWith('--') && args[i - 1] !== '--config');
+const fail = (message, code = 2) => {
+  console.error(message);
+  process.exit(code);
+};
+
+const configPath = resolve(opt('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 runner = {
+  capture: (cmd, cmdArgs, options) => execFileSync(cmd, cmdArgs, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], cwd: options.cwd }),
+  stream: (cmd, cmdArgs, options) => {
+    const r = spawnSync(cmd, cmdArgs, { stdio: 'inherit', cwd: options.cwd, env: { ...process.env, ...options.env } });
+    if (r.error) throw r.error;
+    return r.status ?? 1;
+  },
+};
+const result = runLocal({
+  issue,
+  config: loaded.config,
+  runner,
+  dryRun: flag('dry-run'),
+  workflowPresent: existsSync('.github/workflows/relevo-go.yml'),
+  exists: existsSync,
+});
+result.messages.forEach((m) => console.log(m));
+process.exit(result.status);

package/scripts/go-plan.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+// Plans what `go` should do. Reads GitHub (or a JSON file), prints the decisions as JSON.
+//
+//   node scripts/go-plan.mjs --repo owner/name [--config relevo.yml] [--credential false] [--running 12,13] [--only 31] [--apply] [--claim] [--github-output file]
+//   node scripts/go-plan.mjs --input state.json  [--config relevo.yml]
+//
+// --only N  keeps only the decision for issue N (the whole queue is still planned, so limits stay correct).
+// --apply   carries out every decision except `start` (labels, assignees, comments).
+// --claim   also carries out the `start` decision of the issue given by --only (marks it as building).
+// --github-output FILE  appends `action=<decision action, or none>`, `decision_b64=<the decision as base64 JSON>` and, for a start,
+//                       `platform=`, `stack=` and `path=` (empty otherwise)
+//           to FILE (the GITHUB_OUTPUT file of a workflow step), so a later job can build without planning again.
+//           Needs --only: it describes the decision of one issue.
+// The `start` decisions are returned for the skill to build.
+//   exit 0: planned   exit 2: invalid or missing configuration, or bad arguments
+
+import { appendFileSync, 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, withoutCredential } from './lib/plan.mjs';
+
+function arg(name) {
+  const i = process.argv.indexOf(`--${name}`);
+  return i === -1 ? undefined : process.argv[i + 1];
+}
+const flag = (name) => process.argv.includes(`--${name}`);
+const fail = (message) => {
+  console.error(message);
+  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 running = (arg('running') ?? '').split(',').filter(Boolean).map(Number);
+let state;
+let repo = arg('repo') ?? process.env.GITHUB_REPOSITORY;
+
+if (arg('input')) {
+  state = JSON.parse(readFileSync(arg('input') === '-' ? 0 : arg('input'), 'utf8'));
+  state.running = [...(state.running ?? []), ...running];
+} else {
+  if (!repo) fail('give --repo owner/name (or set GITHUB_REPOSITORY), or --input state.json');
+  state = gather({ gh: realGh, ghLinks: realGhLinks(), repo, config, running });
+}
+
+const result = planGo({ config, repo, ...state });
+// `--credential false`: the workflow found no model credential, so nothing may be claimed for a cloud build.
+if (arg('credential') === 'false') {
+  result.decisions = withoutCredential(result.decisions, state.issues);
+  result.summary = {};
+  result.decisions.forEach((d) => { result.summary[d.action] = (result.summary[d.action] ?? 0) + 1; });
+}
+
+const only = arg('only') ? Number(arg('only')) : null;
+if (only !== null) {
+  if (!Number.isInteger(only)) fail('--only needs an issue number');
+  result.decisions = result.decisions.filter((d) => d.issue === only);
+  result.summary = {};
+  result.decisions.forEach((d) => {
+    result.summary[d.action] = (result.summary[d.action] ?? 0) + 1;
+  });
+}
+if (flag('claim') && only === null) fail('--claim needs --only <issue>: it marks one issue as building');
+
+if (flag('apply') || flag('claim')) {
+  if (!repo) fail('--apply and --claim need --repo owner/name');
+  result.applied = applyDecisions(result.decisions, { gh: realGh, repo, config, includeStart: flag('claim') }).length;
+}
+if (arg('github-output')) {
+  if (only === null) fail('--github-output needs --only <issue>: it describes the decision of one issue');
+  const decision = result.decisions[0] ?? null;
+  const encoded = decision ? Buffer.from(JSON.stringify(decision), 'utf8').toString('base64') : '';
+  // The build job installs the toolchain of the stack of the platform; the values are empty unless the decision is `start`.
+  const start = decision?.action === 'start' ? decision : {};
+  appendFileSync(arg('github-output'), `action=${decision ? decision.action : 'none'}\ndecision_b64=${encoded}\nplatform=${start.platform ?? ''}\nstack=${start.stack ?? ''}\npath=${start.path ?? ''}\n`);
+}
+console.log(JSON.stringify(result, null, 2));

package/scripts/init.mjs

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+// Plans and applies the repository setup. Usage:
+//   node scripts/init.mjs plan  [--answers answers.json] [--repo owner/name] [--json]
+//   node scripts/init.mjs apply [--answers answers.json] [--repo owner/name] [--skip id,id] [--json]
+// `plan` changes nothing. `apply` carries out the planned changes except installs (the skill asks first).
+// answers.json: { "members": ["a","b"], "specWriter": "a", "reviewMode": "peer", "language": "en", "platforms": { "app": { "stack": "flutter", "path": ".", "targets": ["android"] } }, "stackProfiles": [] }
+// It never reads or writes the model API key.
+// exit 0: done   exit 2: bad arguments or a failed change
+
+import { execFileSync } from 'node:child_process';
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { gatherFacts, readOnlyGh, WORKFLOW_FILES } from './lib/doctor.mjs';
+import { applyPlan, planInit, renderPlan, skipItems } from './lib/init.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 mode = process.argv[2];
+if (!['plan', 'apply'].includes(mode)) fail('usage: init.mjs <plan|apply> [--answers file] [--repo owner/name] [--json]');
+
+const root = resolve(dirname(new URL(import.meta.url).pathname), '..');
+const run = (name, args, input) => execFileSync(name, args, { encoding: 'utf8', input, maxBuffer: 64 * 1024 * 1024, stdio: ['pipe', 'pipe', 'pipe'] });
+const tool = (name, args) => run(name, args);
+
+let repo = arg('repo') ?? process.env.GITHUB_REPOSITORY ?? null;
+if (!repo) {
+  try {
+    repo = run('gh', ['repo', 'view', '--json', 'nameWithOwner', '-q', '.nameWithOwner']).trim();
+  } catch {
+    fail('could not find the GitHub repository: run inside one, or pass --repo owner/name (and sign in with `gh auth login`)');
+  }
+}
+
+const answers = arg('answers') ? JSON.parse(readFileSync(arg('answers'), 'utf8')) : {};
+const facts = gatherFacts({
+  tool,
+  gh: readOnlyGh((args) => run('gh', args)),
+  exists: existsSync,
+  read: (p) => readFileSync(p, 'utf8'),
+  listDir: (p) => readdirSync(p),
+  skillDirs: ['.claude/skills', '.agents/skills', `${homedir()}/.claude/skills`],
+  repo,
+});
+
+let admin = false;
+try {
+  admin = JSON.parse(run('gh', ['api', `repos/${repo}`])).permissions?.admin === true;
+} catch {
+  admin = false;
+}
+
+const templates = {
+  config: readFileSync(`${root}/templates/relevo.yml`, 'utf8'),
+  workflows: Object.fromEntries(WORKFLOW_FILES.map((f) => [f, readFileSync(`${root}/templates/workflows/${f}`, 'utf8')])),
+};
+const keepPaths = ['openspec/specs/.gitkeep', 'openspec/changes/archive/.gitkeep'];
+const current = {
+  workflows: Object.fromEntries(WORKFLOW_FILES.map((f) => [f, existsSync(`.github/workflows/${f}`) ? readFileSync(`.github/workflows/${f}`, 'utf8') : null])),
+  gitignore: existsSync('.gitignore') ? readFileSync('.gitignore', 'utf8') : null,
+  keepFiles: Object.fromEntries(keepPaths.map((p) => [p, existsSync(p)])),
+  stackProfiles: Object.fromEntries((answers.stackProfiles ?? []).map((s) => [s, existsSync(`.relevo/stacks/${s}.md`)])),
+};
+
+let items;
+try {
+  items = planInit({ facts, answers, templates, current, admin });
+} catch (err) {
+  fail(err.message);
+}
+
+if (mode === 'plan') {
+  console.log(process.argv.includes('--json') ? JSON.stringify(items, null, 2) : renderPlan(items));
+  process.exit(0);
+}
+
+const io = {
+  gh: (args, input) => run('gh', args, input),
+  write: (p, text) => {
+    mkdirSync(dirname(resolve(p)), { recursive: true });
+    writeFileSync(p, text);
+  },
+  append: (p, line) => {
+    const have = existsSync(p) ? readFileSync(p, 'utf8') : '';
+    appendFileSync(p, `${have === '' || have.endsWith('\n') ? '' : '\n'}${line}\n`);
+  },
+};
+const skipped = (arg('skip') ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+const results = applyPlan(skipItems(items, skipped), { repo, io });
+skipped.forEach((id) => console.error(`skipped ${id}: run init again to apply it`));
+if (process.argv.includes('--json')) console.log(JSON.stringify(results, null, 2));
+else {
+  results.forEach((r) => {
+    console.log(`${r.ok ? 'done  ' : 'FAILED'} ${r.id}: ${r.message}`);
+    (r.checklist ?? []).forEach((c) => console.log(`         by hand: ${c}`));
+  });
+  items.filter((i) => i.status === 'manual').forEach((i) => {
+    console.log(`by hand ${i.id}: ${i.description}`);
+    (i.checklist ?? []).forEach((c) => console.log(`         ${c}`));
+  });
+}
+process.exit(results.some((r) => !r.ok && !r.checklist) ? 2 : 0);

package/scripts/intent-to-add.mjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+// Makes new files show up in `git diff <base>` without staging their content. Usage:
+//   node scripts/intent-to-add.mjs path [path ...]
+// `go` runs it on the files the developer reported, before QA reviews the work. Files that git ignores and files that
+// do not exist are skipped. Refuses "." and "-A": name the files.
+//   exit 0: done (prints what was marked and skipped)   exit 2: bad arguments or git failed
+
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { intentToAdd } from './lib/intent-to-add.mjs';
+
+const git = (args) => execFileSync('git', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+
+try {
+  const { marked, ignored, missing } = intentToAdd({ git, exists: existsSync, paths: process.argv.slice(2) });
+  console.log(`marked ${marked.length} file(s) for the diff${ignored.length ? `, skipped ${ignored.length} ignored by git` : ''}${missing.length ? `, skipped ${missing.length} that do not exist` : ''}`);
+} catch (err) {
+  console.error(err.message);
+  process.exit(2);
+}

package/scripts/issue-coverage.mjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+// Checks that every id of the agreement went into one of the drafts. Usage:
+//   node scripts/issue-coverage.mjs --agreement agreement.md --issue 1.md [--issue 2.md ...] [--discarded D3,Q1]
+// Prints a table (id, issue, section), the discarded ids and the ids without a destination.
+// exit 0: every id has a destination or was discarded   exit 1: some id has none   exit 2: bad arguments
+
+import { readFileSync } from 'node:fs';
+import { coverage } from './lib/issue-coverage.mjs';
+
+const values = (name) => process.argv.flatMap((a, i, all) => (a === `--${name}` ? [all[i + 1]] : []));
+const [agreementFile] = values('agreement');
+const issueFiles = values('issue');
+if (!agreementFile || issueFiles.length === 0) {
+  console.error('usage: issue-coverage.mjs --agreement <file> --issue <file> [--issue <file> ...] [--discarded D3,Q1]');
+  process.exit(2);
+}
+const read = (f) => {
+  try {
+    return readFileSync(f, 'utf8');
+  } catch (err) {
+    console.error(`cannot read ${f}: ${err.message}`);
+    process.exit(2);
+  }
+};
+const discarded = (values('discarded')[0] ?? '').split(',');
+const r = coverage({ agreement: read(agreementFile), issues: issueFiles.map((f) => ({ name: f, body: read(f) })), discarded });
+r.found.forEach((f) => console.log(`${f.id}\t${f.issue}\t${f.section}`));
+r.discarded.forEach((id) => console.log(`${id}\t(discarded)`));
+r.missing.forEach((id) => console.log(`${id}\tWITHOUT DESTINATION`));
+process.exit(r.ok ? 0 : 1);

package/scripts/issue-hash.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+// Checks that an issue still has the text it was claimed with. Usage:
+//   node scripts/issue-hash.mjs --repo owner/name --issue 42 --expect <hash>   exit 0 same, 1 different
+//   node scripts/issue-hash.mjs --input issue.json --expect <hash>             (a saved `gh issue view --json title,body`)
+//   node scripts/issue-hash.mjs --repo owner/name --issue 42                   prints the hash
+// exit 2: bad arguments or the issue could not be read.
+
+import { readFileSync } from 'node:fs';
+import { realGh } from './lib/github.mjs';
+import { checkIssueHash, issueHash, shortHash } from './lib/issue-hash.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 issue;
+try {
+  if (arg('input')) {
+    issue = JSON.parse(readFileSync(arg('input'), 'utf8'));
+  } else {
+    const repo = arg('repo') ?? process.env.GITHUB_REPOSITORY;
+    const number = arg('issue');
+    if (!repo || !/^\d+$/.test(number ?? '')) fail('usage: issue-hash.mjs --repo owner/name --issue <number> [--expect <hash>]  (or --input issue.json)');
+    issue = JSON.parse(realGh(['issue', 'view', number, '--repo', repo, '--json', 'title,body']));
+  }
+} catch (err) {
+  fail(`could not read the issue: ${err.message}`);
+}
+
+if (!arg('expect')) {
+  console.log(issueHash(issue));
+} else {
+  const { ok, actual } = checkIssueHash({ expected: arg('expect'), ...issue });
+  if (ok) console.log(`the issue text is unchanged (${shortHash(actual)})`);
+  else {
+    console.log(`the issue text changed after it was claimed (expected ${shortHash(arg('expect'))}, found ${shortHash(actual)})`);
+    process.exit(1);
+  }
+}

package/scripts/issue-sections.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+// Reads the sections of an issue body. Usage:
+//   node scripts/issue-sections.mjs --body-file issue.md --list                       names of the sections that have text
+//   node scripts/issue-sections.mjs --body-file issue.md --section Decisions          the text of one section
+//   node scripts/issue-sections.mjs --body-file issue.md --copy "Decisions,Constraints"   the block go appends to design.md
+// exit 0: done (a --copy with nothing to copy prints nothing)   exit 1: --section names a section that is not there   exit 2: bad arguments
+
+import { readFileSync } from 'node:fs';
+import { copyBlock, section, sections } from './lib/issue-sections.mjs';
+
+const arg = (name) => {
+  const i = process.argv.indexOf(`--${name}`);
+  return i === -1 ? undefined : process.argv[i + 1];
+};
+const file = arg('body-file');
+const modes = ['list', 'section', 'copy'].filter((m) => process.argv.includes(`--${m}`));
+if (!file || modes.length !== 1) {
+  console.error('usage: issue-sections.mjs --body-file <file> (--list | --section <Name> | --copy "<Name>,<Name>")');
+  process.exit(2);
+}
+let body;
+try {
+  body = readFileSync(file, 'utf8');
+} catch (err) {
+  console.error(`cannot read ${file}: ${err.message}`);
+  process.exit(2);
+}
+if (modes[0] === 'list') {
+  sections(body).filter((s) => s.text !== '').forEach((s) => console.log(s.name));
+} else if (modes[0] === 'section') {
+  const s = section(body, arg('section') ?? '');
+  if (!s) process.exit(1);
+  console.log(s.text);
+} else {
+  const names = (arg('copy') ?? '').split(',').map((n) => n.trim()).filter(Boolean);
+  if (names.length === 0) {
+    console.error('--copy needs at least one section name');
+    process.exit(2);
+  }
+  const block = copyBlock(body, names);
+  if (block) process.stdout.write(block);
+}

package/scripts/label-change.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+// Prints the label changes needed to move an issue to a state. Usage:
+//   node scripts/label-change.mjs --to built --current "relevo:building,bug" [--config relevo.yml]
+//   node scripts/label-change.mjs --clear --current "relevo:pr-open,bug"   (removes every Relevo label)
+// Output: {"add":[...],"remove":[...]} using the label names from relevo.yml.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { loadConfig } from './lib/config.mjs';
+import { clearAll, transition } from './lib/labels.mjs';
+
+const arg = (name) => {
+  const i = process.argv.indexOf(`--${name}`);
+  return i === -1 ? undefined : process.argv[i + 1];
+};
+
+const to = arg('to');
+const clear = process.argv.includes('--clear');
+if (!to && !clear) {
+  console.error('usage: label-change.mjs (--to <label-key> | --clear) --current "a,b" [--config path]');
+  process.exit(2);
+}
+let overrides = {};
+const path = resolve(arg('config') ?? 'relevo.yml');
+if (existsSync(path)) {
+  const loaded = loadConfig(readFileSync(path, 'utf8'));
+  if (loaded.ok) overrides = loaded.config.labels;
+}
+try {
+  const current = (arg('current') ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+  console.log(JSON.stringify(clear ? clearAll(current, overrides) : transition(current, to, overrides)));
+} catch (err) {
+  console.error(err.message);
+  process.exit(2);
+}

package/scripts/lib/appid.mjs

@@ -0,0 +1,12 @@
+// Finds the Android application id of the project under review, so the log audit can ignore other apps.
+
+const GRADLE = [/applicationId\s*=\s*["']([\w.]+)["']/, /applicationId\s+["']([\w.]+)["']/];
+
+/** Application id from the text of android/app/build.gradle or build.gradle.kts, or null. */
+export function applicationId(gradleText) {
+  for (const re of GRADLE) {
+    const m = re.exec(String(gradleText));
+    if (m) return m[1];
+  }
+  return null;
+}

package/scripts/lib/archive-check.mjs

@@ -0,0 +1,29 @@
+// The spec archive is committed after approval, so it may touch nothing but the specifications folder.
+// Implements "Archive the specification just before merging" of openspec/specs/ship/spec.md.
+
+/**
+ * paths   every path changed in the working tree by the archive (from `git status --porcelain`)
+ * Returns { ok, outside }.
+ */
+export function checkArchiveChanges(paths, specsDir = 'openspec') {
+  const prefix = `${specsDir.replace(/\/+$/, '')}/`;
+  const outside = paths.filter((p) => !p.startsWith(prefix));
+  if (paths.length === 0) return { ok: false, outside: [], empty: true };
+  return { ok: outside.length === 0, outside };
+}
+
+/** Paths from `git status --porcelain` output, including both sides of a rename. */
+export function pathsFromPorcelain(output) {
+  return String(output)
+    .split('\n')
+    .filter(Boolean)
+    .flatMap((line) => line.slice(3).split(' -> '))
+    .map((p) => p.replace(/^"|"$/g, ''));
+}
+
+/** Whether every conflicted path is inside the specifications folder. Returns { ok, paths, outside }. */
+export function conflictScope(paths, specsDir = 'openspec') {
+  const prefix = `${specsDir.replace(/\/+$/, '')}/`;
+  const outside = paths.filter((p) => !p.startsWith(prefix));
+  return { ok: outside.length === 0, paths, outside };
+}

package/scripts/lib/archive-state.mjs

@@ -0,0 +1,15 @@
+// Tells whether a change is still to be archived, already archived, or unknown.
+// Implements "Ship can be run again after a failed merge" of openspec/specs/ship/spec.md.
+
+/**
+ * active    names of the changes in `openspec list --json`
+ * archived  names of the folders of openspec/changes/archive/ (YYYY-MM-DD-<change>)
+ * change    the change folder name, e.g. "31-summary"
+ * Returns "active", "archived" or "missing".
+ */
+export function archiveState({ active, archived, change }) {
+  if (active.includes(change)) return 'active';
+  const dated = new RegExp(`^\\d{4}-\\d{2}-\\d{2}-${change.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}$`);
+  if (archived.some((name) => dated.test(name))) return 'archived';
+  return 'missing';
+}

package/scripts/lib/branch-work.mjs

@@ -0,0 +1,13 @@
+// Tells a branch that holds implementation from one that holds only the specification.
+// Implements "A branch without implementation is not corrected" of openspec/specs/fix/spec.md.
+
+/**
+ * paths      every path that differs from the base branch
+ * changeDir  e.g. "openspec/changes/31-summary"
+ * Returns { implementation, files }: files are the paths outside the change folder.
+ */
+export function hasImplementation(paths, changeDir) {
+  const prefix = `${changeDir.replace(/\/+$/, '')}/`;
+  const files = paths.filter((p) => !p.startsWith(prefix));
+  return { implementation: files.length > 0, files };
+}

package/scripts/lib/branch.mjs

@@ -0,0 +1,43 @@
+// Branch and change names derived from an issue.
+
+const MAX_SLUG = 40;
+
+/** kebab-case slug of a title: ASCII only, at most 40 characters, cut at a word boundary. */
+export function slugify(title, max = MAX_SLUG) {
+  let slug = String(title ?? '')
+    .normalize('NFD')
+    .replace(/[̀-ͯ]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  if (slug.length > max) {
+    const midWord = slug[max] !== '-';
+    slug = slug.slice(0, max);
+    if (midWord && slug.includes('-')) slug = slug.replace(/-[^-]*$/, '');
+    slug = slug.replace(/-+$/g, '');
+  }
+  return slug || 'task';
+}
+
+export const changeId = (number, title) => `${number}-${slugify(title)}`;
+export const branchName = (number, title) => `feature/${changeId(number, title)}`;
+
+/** The issue number a feature branch was made for (`feature/12-add-total` -> 12), or null. */
+export function issueFromBranch(branch) {
+  const m = /^feature\/(\d+)-/.exec(String(branch ?? ''));
+  return m ? Number(m[1]) : null;
+}
+
+/**
+ * What an existing feature branch holds, from the paths it changes against the base branch:
+ * `empty` (nothing), `spec-only` (only the change specification, under openspec/changes/<change_id>/) or `implementation`.
+ */
+export function classifyBranchChanges(paths, id) {
+  const changed = (paths ?? []).map((p) => String(p).trim()).filter(Boolean);
+  if (changed.length === 0) return 'empty';
+  const prefix = `openspec/changes/${id}/`;
+  return changed.every((p) => p.startsWith(prefix)) ? 'spec-only' : 'implementation';
+}
+
+/** What to tell the person about a failed run on a branch that already exists: fix it, or start again. */
+export const recoveryForBranch = (kind) => (kind === 'implementation' ? 'fix' : 'delete-branch');

package/scripts/lib/can-edit-issue.mjs

@@ -0,0 +1,34 @@
+// Decides whether the description of an issue may be rewritten.
+// Implements "Only an issue Relevo has not committed to a build may be edited" of openspec/specs/issue/spec.md.
+import { LABELS, resolveLabelNames } from './labels.mjs';
+
+// Why each lifecycle label closes the issue to editing. `needs-spec` is the only one that leaves it open.
+const REASON = {
+  ready: 'go starts it by itself, so the new text would be built without anyone rereading it',
+  queued: 'go starts it by itself when there is capacity',
+  blocked: 'go starts it by itself when its dependency merges',
+  building: 'the agent is building from the current text; wait for it to finish or fail',
+  built: 'a branch already exists and the text would no longer match what was built',
+  'in-review': 'it is being reviewed against the current text',
+  'pr-open': 'a pull request already exists for the current text',
+  'qa-failed': 'a branch already exists and the text would no longer match what was built',
+  'changes-requested': 'a branch already exists and the text would no longer match what was built',
+  'needs-reviewer': 'it is built and waiting for a reviewer',
+};
+export const EDITABLE_LABELS = ['needs-spec'];
+
+/**
+ * @param {{state?: string, labels?: Array<string|{name: string}>}} issue  `gh issue view --json state,labels`
+ * @param {Record<string,string>} [overrides]  the `labels` setting of relevo.yml
+ * @returns {{editable: true} | {editable: false, label?: string, reason: string}}
+ */
+export function canEditIssue(issue, overrides = {}) {
+  if (String(issue.state ?? '').toUpperCase() !== 'OPEN') return { editable: false, reason: 'the issue is closed' };
+  const names = resolveLabelNames(overrides);
+  const have = new Set((issue.labels ?? []).map((l) => (typeof l === 'string' ? l : l.name)));
+  for (const { key } of LABELS) {
+    if (EDITABLE_LABELS.includes(key) || !have.has(names[key])) continue;
+    return { editable: false, label: names[key], reason: REASON[key] };
+  }
+  return { editable: true };
+}