@bongos/core 1.21.175 → 1.21.176

package/scripts/bongos/validate-design.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+'use strict';
+// validate-design.js — thin shim: the design-contract validator lives in the
+// ui-design module at modules/ui-design/scripts/validate-design.js (task 1003324,
+// ADR 0197). fitness.js (checkDesignContract in fitness-checks-identity.js) spawns
+// the module file directly; this path is the documented CLI entry point, kept
+// because it is the form claude-materialize rewrites to `bongos exec` for a
+// packaged core. Flags pass straight through:
+//   node scripts/bongos/validate-design.js           # exits 0 on pass, 1 on failure
+//   node scripts/bongos/validate-design.js --json    # machine-readable { ok, errors, warnings }
+//   node scripts/bongos/validate-design.js --strict  # treat warnings as errors
+require('../../modules/ui-design/scripts/validate-design.js');

package/scripts/bongos/version-close.js

@@ -0,0 +1,621 @@
+#!/usr/bin/env node
+// GDS version-close CLI (PMS-V2 task #43, bucket E3).
+//
+// Usage: node scripts/bongos/version-close.js <VERSION_ID> [--yes|-y] [--next <ID>]
+//
+// What it does:
+//   1. Verifies the version is ready to close (calls
+//      GET /api/bongos/versions/close-suggestions and checks the gate).
+//   2. Lists shipped tasks for the version (GET /api/bongos/tasks) and drafts a
+//      <scope>-shipped.md archive grouped by kind/bucket from value_summary.
+//   3. Identifies carry-over candidates (backlog + ready) and drafts a
+//      next-version scope stub (e.g. limitations/pms-v3.md) with a
+//      "## Carried Over from <VID>" section.
+//   4. CLOSES the version through POST /versions/:id/close (BV1.R23, task
+//      1003610). This step used to print a "MANUAL STEP REQUIRED" block of SQL
+//      to paste into psql on the droplet, because at the time the API genuinely
+//      exposed no version status transition. BV1.R12 (task 1003599) built the
+//      route, so that text became false — and by then the SQL was actively
+//      harmful, since it bypasses the disposition two-step, the closure
+//      invariant, the successor lineage, the promotion and the bug carry-forward.
+//      Closing a version by hand now silently strands everything the route
+//      carries.
+//   5. Prints a suggested git commit message.
+//
+// Every destructive write (file create, INSERT, UPDATE) prompts y/N first.
+// Pass --yes to auto-confirm all prompts (still prints what would happen).
+//
+// Re-runnable: refuses if the version is already at status 'shipped'.
+
+const fs = require('node:fs');
+const fsp = require('node:fs/promises');
+const path = require('node:path');
+const readline = require('node:readline');
+
+const { cliClient, requireSession, API_BASE } = require('./cli-lib');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+
+// -------------------------------------------------------------------------
+// Argv parsing
+// -------------------------------------------------------------------------
+
+function parseArgs(argv) {
+  const out = { versionId: null, yes: false, nextId: null, noNextStub: false, reason: null, dispositions: {} };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--yes' || a === '-y') {
+      out.yes = true;
+    } else if (a === '--no-next-stub') {
+      out.noNextStub = true;
+    } else if (a === '--next') {
+      out.nextId = argv[++i];
+    } else if (a.startsWith('--next=')) {
+      out.nextId = a.slice('--next='.length);
+    } else if (a === '--reason') {
+      out.reason = argv[++i];
+    } else if (a.startsWith('--reason=')) {
+      out.reason = a.slice('--reason='.length);
+    } else if (a === '--disposition' || a.startsWith('--disposition=')) {
+      // `<goalId>=<verb>`, repeatable. Parsed into the exact map shape
+      // POST /versions/:id/close expects, so the operator never hand-writes JSON.
+      const raw = a.startsWith('--disposition=') ? a.slice('--disposition='.length) : argv[++i];
+      const eq = String(raw || '').indexOf('=');
+      if (eq > 0) out.dispositions[raw.slice(0, eq)] = { verb: raw.slice(eq + 1) };
+    } else if (a === '-h' || a === '--help') {
+      out.help = true;
+    } else if (!out.versionId && !a.startsWith('-')) {
+      out.versionId = a;
+    }
+  }
+  return out;
+}
+
+function usage() {
+  return [
+    'Usage: node scripts/bongos/version-close.js <VERSION_ID> [--yes|-y] [--next <ID>] [--no-next-stub]',
+    '',
+    'Drafts <scope>-shipped.md + next-version stub, then CLOSES the version',
+    'through POST /versions/:id/close. Always interactive without --yes.',
+    '',
+    '  --reason <text>            recorded on the close; stamped on any task a',
+    '                             disposition abandons. Required by the route',
+    '                             whenever a goal is dispositioned.',
+    '  --disposition <id>=<verb>  roll_forward | abandon, repeatable — one per',
+    '                             open goal. Without them the close REFUSES and',
+    '                             lists the goals, so nothing is cut by omission.',
+    '',
+    '  --no-next-stub  Skip drafting the next-version scope stub entirely',
+    '                  (enforces the guided-review-pass memory rule). The',
+    '                  shipped archive + carry-over rebind still run.',
+    '',
+    'Examples:',
+    '  node scripts/bongos/version-close.js PMS-V2',
+    '  node scripts/bongos/version-close.js PMS-V2 --next GDS-V3',
+    '  node scripts/bongos/version-close.js PMS-V2 --yes',
+    '  node scripts/bongos/version-close.js PMS-V2 --no-next-stub',
+    '  node scripts/bongos/version-close.js PMS-V2 --disposition 44=roll_forward \\',
+    '         --disposition 51=abandon --reason "V2 is done; 51 is not coming back"',
+  ].join('\n');
+}
+
+// -------------------------------------------------------------------------
+// readline confirm
+// -------------------------------------------------------------------------
+
+function makePrompter(autoYes) {
+  if (autoYes) {
+    return {
+      async ask(msg) {
+        process.stdout.write(`${msg} [y/N] y (auto)\n`);
+        return true;
+      },
+      close() {},
+    };
+  }
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return {
+    ask(msg) {
+      return new Promise((resolve) => {
+        rl.question(`${msg} [y/N] `, (answer) => {
+          const s = (answer || '').trim().toLowerCase();
+          resolve(s === 'y' || s === 'yes');
+        });
+      });
+    },
+    close() {
+      rl.close();
+    },
+  };
+}
+
+// -------------------------------------------------------------------------
+// Version-id helpers
+// -------------------------------------------------------------------------
+
+// Derive the next version id from "PMS-V2" → "GDS-V3", "V1" → "V2".
+function deriveNextVersionId(currentId) {
+  const m = currentId.match(/^(.*?V)(\d+)$/);
+  if (!m) return null;
+  return `${m[1]}${Number(m[2]) + 1}`;
+}
+
+// Both derivations below build a REPO-RELATIVE doc path — it is stored on the
+// version row and read as a repo path on every platform — so they use path.posix,
+// never path.join (task 1003529). path.join emits '\' on win32, which produced
+// `limitations\pms-v2-shipped.md`: not a path this repo can resolve, and not what
+// either function's own `!currentPath` fallback returns. Only the separator is
+// platform-dependent here; the input is already a POSIX repo path.
+
+// Derive the next scope-doc path from the current one.
+//   limitations/pms-v2.md      → limitations/pms-v3.md
+//   limitations/current-version.md → limitations/v2.md   (best-effort guess)
+function deriveNextScopePath(currentPath, nextVersionId) {
+  if (!currentPath) return `limitations/${nextVersionId.toLowerCase()}.md`;
+  const dir = path.posix.dirname(currentPath);
+  const base = path.posix.basename(currentPath);
+  // e.g. pms-v2.md  → swap number
+  const numbered = base.match(/^(.*v)(\d+)(\.md)$/i);
+  if (numbered) {
+    return path.posix.join(dir, `${numbered[1]}${Number(numbered[2]) + 1}${numbered[3]}`);
+  }
+  // Fallback: lower-case the version id.
+  return path.posix.join(dir, `${nextVersionId.toLowerCase()}.md`);
+}
+
+// Derive the shipped-archive path. For "limitations/pms-v2.md" → "limitations/pms-v2-shipped.md".
+function deriveShippedPath(currentPath, versionId) {
+  if (!currentPath) return `limitations/${versionId.toLowerCase()}-shipped.md`;
+  const dir = path.posix.dirname(currentPath);
+  const base = path.posix.basename(currentPath);
+  const m = base.match(/^(.*)\.md$/i);
+  const stem = m ? m[1] : base;
+  return path.posix.join(dir, `${stem}-shipped.md`);
+}
+
+// -------------------------------------------------------------------------
+// API helpers
+// -------------------------------------------------------------------------
+
+async function fetchVersions() {
+  const api = await cliClient();
+  const { ok, status, data } = await api.versions.getVersions();
+  if (!ok) throw new Error(`GET /versions failed (${status}): ${JSON.stringify(data)}`);
+  return data.versions || [];
+}
+
+async function fetchCloseSuggestions() {
+  const api = await cliClient();
+  const { ok, status, data } = await api.versions.getVersionsCloseSuggestions();
+  if (!ok) throw new Error(`GET /versions/close-suggestions failed (${status}): ${JSON.stringify(data)}`);
+  return data.suggestions || [];
+}
+
+async function fetchTasks(versionId, status) {
+  const q = new URLSearchParams({ version: versionId, status });
+  const api = await cliClient();
+  const { ok, status: code, data } = await api.tasks.getTasks({ query: Object.fromEntries(q) });
+  if (!ok) throw new Error(`GET /tasks?${q} failed (${code}): ${JSON.stringify(data)}`);
+  return data.tasks || [];
+}
+
+// -------------------------------------------------------------------------
+// Markdown builders
+// -------------------------------------------------------------------------
+
+function groupTasksBy(tasks, fn) {
+  const out = new Map();
+  for (const t of tasks) {
+    const k = fn(t) || 'unclassified';
+    if (!out.has(k)) out.set(k, []);
+    out.get(k).push(t);
+  }
+  return out;
+}
+
+function escapeMd(s) {
+  return (s || '').replace(/\r/g, '');
+}
+
+function buildShippedArchive({ versionId, versionName, scopeDocPath, shippedTasks, originalScopeBody, shippedAt }) {
+  const heading = `# ${versionId} — ${versionName || versionId}  *(SHIPPED ${shippedAt})*`;
+  const intro = [
+    '',
+    `> ✅ **Shipped ${shippedAt}.** This file is the preserved archive of ${versionId}.`,
+    `> The original scope document (\`${scopeDocPath || 'unknown'}\`) is reproduced below the value summary.`,
+    '',
+    '---',
+    '',
+    '## Value summary — what shipped',
+    '',
+  ];
+
+  const byKind = groupTasksBy(shippedTasks, (t) => t.kind || 'unclassified');
+  const kindOrder = ['feature', 'bug', 'infra', 'refactor', 'spike', 'learning-capture', 'cleanup', 'decision', 'blocker-resolution', 'unclassified'];
+  const orderedKinds = [
+    ...kindOrder.filter((k) => byKind.has(k)),
+    ...[...byKind.keys()].filter((k) => !kindOrder.includes(k)),
+  ];
+
+  const valueLines = [];
+  if (shippedTasks.length === 0) {
+    valueLines.push('_No shipped tasks were recorded for this version._');
+    valueLines.push('');
+  } else {
+    for (const kind of orderedKinds) {
+      const rows = byKind.get(kind);
+      valueLines.push(`### ${kind} (${rows.length})`);
+      valueLines.push('');
+      for (const t of rows) {
+        const summary = (t.value_summary || t.title || '').trim();
+        valueLines.push(`- **#${t.id}** — ${escapeMd(summary)}`);
+      }
+      valueLines.push('');
+    }
+  }
+
+  const archive = [
+    '---',
+    '',
+    `## Original scope document (\`${scopeDocPath || 'unknown'}\`)`,
+    '',
+    originalScopeBody ? originalScopeBody.trimEnd() : '_(scope document not found on disk)_',
+    '',
+  ];
+
+  return [heading, ...intro, ...valueLines, ...archive].join('\n');
+}
+
+function buildNextVersionStub({ nextVersionId, prevVersionId, carryOverTasks }) {
+  const heading = `# ${nextVersionId} — scope (stub)`;
+  const intro = [
+    '',
+    `> Stub generated by \`scripts/bongos/version-close.js\` when ${prevVersionId} closed.`,
+    `> Fill in scope, done-when criteria, and open questions before promoting tasks.`,
+    '',
+    '---',
+    '',
+    '## What this version ships',
+    '',
+    '_(to be filled in)_',
+    '',
+    '## Done-when criteria',
+    '',
+    '_(to be seeded — see migration template for done_when_criteria rows)_',
+    '',
+  ];
+
+  const carry = [
+    `## Carried Over from ${prevVersionId}`,
+    '',
+  ];
+  if (carryOverTasks.length === 0) {
+    carry.push(`_None — ${prevVersionId} closed cleanly with no remaining backlog or ready tasks._`);
+    carry.push('');
+  } else {
+    carry.push(`These ${carryOverTasks.length} task(s) were not shipped in ${prevVersionId} and have been rebound to ${nextVersionId}:`);
+    carry.push('');
+    for (const t of carryOverTasks) {
+      const status = t.status || 'unknown';
+      carry.push(`- **#${t.id}** (${status}, P${t.priority ?? '?'}) — ${escapeMd(t.title || '')}`);
+    }
+    carry.push('');
+  }
+
+  return [heading, ...intro, ...carry].join('\n');
+}
+
+// -------------------------------------------------------------------------
+// The close itself — a ROUTE call, not printed SQL (BV1.R23, task 1003610)
+// -------------------------------------------------------------------------
+//
+// THIS FILE USED TO PRINT A `-- MANUAL STEP REQUIRED` BLOCK and tell the operator
+// to run three UPDATEs on the production droplet, on the entirely true grounds
+// that "the GDS API does not currently expose endpoints for version status
+// transitions". BV1.R12 (task 1003599) built `POST /versions/:id/close`, so that
+// sentence became false — and a script that keeps printing it is worse than one
+// that never offered anything, because the SQL path BYPASSES every rule this goal
+// exists to enforce: the disposition two-step (R12/R14), the closure invariant
+// (R08/R09), the successor lineage (R17), the promotion (R20) and the bug
+// carry-forward (R18). An operator pasting that SQL would close a version and
+// silently strand everything the route would have carried.
+//
+// The advisory half of this script — `suggestClose`, the shipped archive, the
+// next-version scope stub — is unchanged and still the reason to run it.
+
+async function closeVersionViaApi({ versionId, reason, dispositions }) {
+  const api = await cliClient();
+  const body = { reason };
+  if (dispositions && Object.keys(dispositions).length > 0) body.dispositions = dispositions;
+  const { ok, status, data } = await api.versions.postVersionsIdClose({ path: { id: versionId }, body });
+  return { ok, status, data };
+}
+
+// The route answers the R12 two-step: called with open goals and no disposition
+// it REFUSES and returns them, so the operator can decide per goal rather than
+// being told only that something is in the way. Rendered here rather than dumped
+// as JSON because the next thing the operator types is the re-run.
+function renderOpenGoalsRefusal(versionId, details) {
+  const goals = (details && details.goals) || [];
+  const lines = [
+    `[refused] ${versionId} still holds ${goals.length} open goal(s). Nothing was changed.`,
+    '',
+    'Decide what happens to each, then re-run with --disposition:',
+    '',
+  ];
+  for (const g of goals) {
+    const open = g.open_tasks ? ` (${g.open_tasks} unfinished task${g.open_tasks === 1 ? '' : 's'})` : '';
+    lines.push(`  #${g.id}  ${g.title || ''}${open}`);
+  }
+  lines.push('');
+  lines.push('  --disposition <goalId>=roll_forward   carry it into the planning version');
+  lines.push('  --disposition <goalId>=abandon        cut it, stamping the close reason on its tasks');
+  lines.push('');
+  lines.push(`  e.g. node scripts/bongos/version-close.js ${versionId} \\`);
+  const example = goals.slice(0, 2).map((g) => `--disposition ${g.id}=roll_forward`).join(' ');
+  lines.push(`         ${example || '--disposition <goalId>=roll_forward'} --reason "…"`);
+  return lines.join('\n');
+}
+
+
+function buildCommitMessage({ versionId, nextVersionId, shippedCount, carryCount }) {
+  const subject = `pms: close ${versionId}, open ${nextVersionId}`;
+  const body = [
+    '',
+    `- Archive ${versionId} scope to <scope>-shipped.md (${shippedCount} shipped task(s)).`,
+    `- Open ${nextVersionId} scope stub${carryCount ? ` with ${carryCount} carry-over task(s)` : ' (clean close)'}.`,
+    '- Version status, task rebinding and the successor promotion were done by',
+    '  POST /versions/:id/close (BV1.R23) — this commit is the drafted docs only.',
+  ].join('\n');
+  return `${subject}\n${body}\n`;
+}
+
+// -------------------------------------------------------------------------
+// Main
+// -------------------------------------------------------------------------
+
+async function writeFileWithConfirm(prompter, absPath, contents, label) {
+  const rel = path.relative(REPO_ROOT, absPath);
+  const exists = fs.existsSync(absPath);
+  const action = exists ? 'OVERWRITE' : 'create';
+  console.log('');
+  console.log(`--- ${label} ---`);
+  console.log(`Path: ${rel} (${exists ? 'EXISTS' : 'new'})`);
+  console.log(`Bytes: ${Buffer.byteLength(contents, 'utf8')}`);
+  console.log('--- preview (first 30 lines) ---');
+  const preview = contents.split('\n').slice(0, 30).join('\n');
+  console.log(preview);
+  console.log('--- end preview ---');
+  const ok = await prompter.ask(`${action} ${rel}?`);
+  if (!ok) {
+    console.log(`skipped: ${rel}`);
+    return false;
+  }
+  await fsp.mkdir(path.dirname(absPath), { recursive: true });
+  await fsp.writeFile(absPath, contents, 'utf8');
+  console.log(`wrote: ${rel}`);
+  return true;
+}
+
+async function main() {
+  const args = parseArgs(process.argv);
+
+  if (args.help || !args.versionId) {
+    console.log(usage());
+    process.exit(args.help ? 0 : 2);
+  }
+
+  await requireSession();
+
+  const versionId = args.versionId;
+  console.log(`[version-close] API: ${API_BASE}`);
+  console.log(`[version-close] Target version: ${versionId}`);
+
+  // Step 1: fetch versions, validate target exists and is in 'building'.
+  const versions = await fetchVersions();
+  const target = versions.find((v) => v.id === versionId);
+  if (!target) {
+    console.error(`error: version '${versionId}' not found.`);
+    process.exit(1);
+  }
+  if (target.status === 'shipped') {
+    console.error(`error: version '${versionId}' is already status='shipped'. Refusing (re-runnable guard).`);
+    process.exit(1);
+  }
+  if (target.status !== 'building') {
+    console.error(`error: version '${versionId}' is status='${target.status}', expected 'building'.`);
+    process.exit(1);
+  }
+
+  // Step 2: gate — check close-suggestions for readiness.
+  const suggestions = await fetchCloseSuggestions();
+  const suggestion = suggestions.find((s) => s.versionId === versionId);
+  if (!suggestion) {
+    console.error(`error: no close-suggestion entry for '${versionId}' (is it in 'building' status?).`);
+    process.exit(1);
+  }
+  if (!suggestion.ready) {
+    console.error(`error: ${versionId} is NOT ready to close.`);
+    console.error(`  percent_complete: ${suggestion.percentComplete}% (gate: >=80%)`);
+    console.error(`  criteria satisfied: ${suggestion.criteriaSatisfied}/${suggestion.criteriaTotal}`);
+    console.error(`  shipped tasks:    ${suggestion.tasksShipped}`);
+    console.error(`  carry-over tasks: ${suggestion.tasksCarryOver}`);
+    console.error('');
+    console.error('Both gates must pass: (a) >=80% complete AND (b) every done_when_criteria row satisfied.');
+    process.exit(1);
+  }
+  console.log(`[gate] ${versionId} is ready to close.`);
+  console.log(`       ${suggestion.percentComplete}% complete · ${suggestion.criteriaSatisfied}/${suggestion.criteriaTotal} criteria · ${suggestion.tasksShipped} shipped · ${suggestion.tasksCarryOver} carry-over`);
+
+  // Step 3: resolve next-version id + paths.
+  const nextVersionId = args.nextId || deriveNextVersionId(versionId);
+  if (!nextVersionId) {
+    console.error(`error: could not derive next version id from '${versionId}'. Pass --next <ID>.`);
+    process.exit(1);
+  }
+  // If the next-version row already exists (e.g. pre-created in planning), that
+  // is NOT a conflict — scoping ahead of close is normal. We simply must not
+  // emit a fresh INSERT for it below (the ON CONFLICT DO NOTHING path would no-op
+  // anyway, but suppressing the branch keeps the manual SQL honest).
+  const nextVersionExists = Boolean(versions.find((v) => v.id === nextVersionId));
+  if (nextVersionExists) {
+    console.log(`[note] next version '${nextVersionId}' already exists in DB; will not re-INSERT it.`);
+  }
+  const shippedDocPath = path.join(REPO_ROOT, deriveShippedPath(target.scope_doc_path, versionId));
+  const nextScopeDocRel = deriveNextScopePath(target.scope_doc_path, nextVersionId);
+  const nextScopeDocPath = path.join(REPO_ROOT, nextScopeDocRel);
+
+  console.log(`[plan] next version id:   ${nextVersionId}`);
+  console.log(`[plan] shipped archive:   ${path.relative(REPO_ROOT, shippedDocPath)}`);
+  console.log(`[plan] next scope stub:   ${nextScopeDocRel}`);
+
+  // Step 4: pull shipped + carry-over tasks.
+  const [shipped, backlog, ready] = await Promise.all([
+    fetchTasks(versionId, 'shipped'),
+    fetchTasks(versionId, 'backlog'),
+    fetchTasks(versionId, 'ready'),
+  ]);
+  const carryOver = [...backlog, ...ready].sort((a, b) => (a.priority ?? 99) - (b.priority ?? 99) || a.id - b.id);
+  console.log(`[plan] shipped tasks:     ${shipped.length}`);
+  console.log(`[plan] carry-over tasks:  ${carryOver.length} (${backlog.length} backlog + ${ready.length} ready)`);
+
+  // Step 5: load current scope-doc body (best-effort) for archive copy.
+  let originalScopeBody = '';
+  if (target.scope_doc_path) {
+    const abs = path.join(REPO_ROOT, target.scope_doc_path);
+    try {
+      originalScopeBody = await fsp.readFile(abs, 'utf8');
+    } catch (err) {
+      console.log(`[warn] could not read scope doc ${target.scope_doc_path}: ${err.code || err.message}`);
+    }
+  }
+
+  const shippedAt = new Date().toISOString().slice(0, 10);
+
+  // Step 6: build markdown bodies.
+  const archiveMd = buildShippedArchive({
+    versionId,
+    versionName: target.name,
+    scopeDocPath: target.scope_doc_path,
+    shippedTasks: shipped,
+    originalScopeBody,
+    shippedAt,
+  });
+  const nextStubMd = args.noNextStub
+    ? null
+    : buildNextVersionStub({
+        nextVersionId,
+        prevVersionId: versionId,
+        carryOverTasks: carryOver,
+      });
+
+  // Step 7: interactive writes.
+  const prompter = makePrompter(args.yes);
+  try {
+    await writeFileWithConfirm(prompter, shippedDocPath, archiveMd, `${versionId} shipped archive`);
+
+    if (args.noNextStub) {
+      console.log(`[note] --no-next-stub: skipping next-version scope stub draft for ${nextVersionId}.`);
+    } else if (fs.existsSync(nextScopeDocPath)) {
+      console.log(`[note] next-version stub already exists at ${nextScopeDocRel}; skipping write.`);
+    } else {
+      await writeFileWithConfirm(prompter, nextScopeDocPath, nextStubMd, `${nextVersionId} scope stub`);
+    }
+
+    // Step 8 runs INSIDE this try so the prompter is still open for its confirm
+    // and is closed on every exit — including the refusal paths, which return
+    // early. A leaked readline keeps the process alive forever, which on a CLI
+    // reads as a hang rather than a failure.
+    return await closeStep();
+  } finally {
+    prompter.close();
+  }
+
+  // Step 8: CLOSE THE VERSION THROUGH THE ROUTE (BV1.R23, task 1003610).
+  //
+  // Everything above this point is advisory — it drafts documents and reports the
+  // gate. This is the one destructive act, and it now goes through
+  // `POST /versions/:id/close` so it obeys the disposition two-step, the closure
+  // invariant, the successor lineage, the promotion and the bug carry-forward.
+  // The `--yes` flag the drafting steps honour gates it too: without it the
+  // operator is asked, because closing a version cannot be undone through the API.
+  async function closeStep() {
+  console.log('');
+  if (!args.yes) {
+    const go = await prompter.ask(`Close ${versionId} now via POST /versions/${versionId}/close?`);
+    if (!go) {
+      console.log(`[skip] ${versionId} left building. Re-run with --yes, or close it from the hall.`);
+      printCommit();
+      return;
+    }
+  }
+
+  const closeReason = args.reason || `Closing ${versionId} (${shipped.length} shipped, ${carryOver.length} carry-over).`;
+  const res = await closeVersionViaApi({ versionId, reason: closeReason, dispositions: args.dispositions });
+
+  if (!res.ok) {
+    const err = (res.data && res.data.error) || `http_${res.status}`;
+    if (err === 'version_holds_open_goals' || err === 'disposition_incomplete') {
+      console.log(renderOpenGoalsRefusal(versionId, res.data && res.data.details));
+      process.exitCode = 1;
+      return;
+    }
+    // Every other refusal is already NAMED by the route (ADR 0250 §7), so the
+    // honest thing is to relay it rather than re-word it into something the
+    // operator cannot search for.
+    console.log(`[refused] ${err}: ${(res.data && res.data.message) || ''}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log(`[closed] ${versionId} → ${res.data.version.status}`);
+  for (const a of (res.data.applied || [])) {
+    const extra = a.successor_goal_id ? ` → successor goal #${a.successor_goal_id} (${a.tasks_moved} task(s) moved)`
+      : (a.tasks_abandoned != null ? ` (${a.tasks_abandoned} task(s) abandoned)` : '');
+    console.log(`         goal #${a.goal_id}: ${a.verb} — ${a.result}${extra}`);
+  }
+  if (res.data.promoted) {
+    console.log(`[promoted] ${res.data.promoted.id} is now building.`);
+    if (res.data.carried && res.data.carried.moved) {
+      console.log(`[carried]  ${res.data.carried.moved} open defect(s) moved to its maintenance goal.`);
+    }
+  } else {
+    console.log('[note] no version was in planning — the project has no live train until one is cut.');
+  }
+
+  printCommit();
+  console.log('');
+  console.log(`[done] ${versionId} closed. Commit the drafted docs with the message above.`);
+  }
+
+  function printCommit() {
+    const commit = buildCommitMessage({
+      versionId,
+      nextVersionId,
+      shippedCount: shipped.length,
+      carryCount: carryOver.length,
+    });
+    console.log('');
+    console.log('--- suggested git commit message ---');
+    console.log(commit);
+    console.log('--- end commit message ---');
+  }
+}
+
+if (require.main === module) {
+  main().catch((err) => {
+    console.error(err && err.stack ? err.stack : String(err));
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  parseArgs,
+  usage,
+  deriveNextVersionId,
+  deriveNextScopePath,
+  deriveShippedPath,
+  buildShippedArchive,
+  buildNextVersionStub,
+  buildCommitMessage,
+};