@bongos/core 1.19.601 → 1.19.603

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.601",
-  "core_contract": "1.19.601",
-  "source_commit": "16a19ddf0ad7e10177aea562deb878093568f308",
+  "core_version": "1.19.603",
+  "core_contract": "1.19.603",
+  "source_commit": "54df6f5e5080d70795a267d435e1c3595e597cd1",
   "source_ref": "HEAD",
-  "built_at": "2026-09-08T05:00:27.028Z",
+  "built_at": "2026-09-08T05:34:52.291Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 457,
     "agent_docs_stubbed": 24,
-    "functional_verbatim": 2076,
+    "functional_verbatim": 2077,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2557,
-  "tree_sha256": "eb65ec1fb208a9e7c09906234b5a43e7660816544a9b4ae44ecf94d7f64e6260",
+  "file_count": 2558,
+  "tree_sha256": "6ac267a518248236669ff017af4b9c35d3835cfa1c679b45ea8b6aa65c6690ef",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -2727,7 +2727,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "71f84a8b41b3efb16f49909dcf6b6542deecfa51378e24ad271267cf3de1d6a9"
+      "sha256": "998a472d5b9c5c3b54337d03979d07204d1f224a91d6251e6b578744b9ff0364"
     },
     {
       "path": "docs/modules-contract.md",
@@ -5567,7 +5567,7 @@
     {
       "path": "modules/lifecycle/db-versions.js",
       "mode": "0000644",
-      "sha256": "2c10a17f86506788ab2f9db25c23024120ec9fddb3c7c4894e65d8354cd46869"
+      "sha256": "51b170cdd34a90c49070ec79723b5250dffbc8c61d5ed114d6a560bcc93cadb7"
     },
     {
       "path": "modules/lifecycle/db.js",
@@ -7627,12 +7627,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "d9ab931e2e3779b181225611efe7019b45d037bea4249d643574104445931164"
+      "sha256": "34defd9d51ab981a40425d9faa27a0a3aa694580fd7624f307bd1bdaba3a13d4"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "9903e5cd3c9d790a76647c7fff7556c33d900dd119d5b5afd0ada6797508df1d"
+      "sha256": "aaa775cf4d3e84c22beae120aa96d84b1c40fdaf85c0159c1eb38d957a12e26f"
     },
     {
       "path": "public-docs/index.html",
@@ -8932,7 +8932,7 @@
     {
       "path": "scripts/gds/version-close.js",
       "mode": "0000644",
-      "sha256": "32e0c1f2a955d4cabeae00d3749b283abd70f05f34b5fcbd84be3f35e2e655c8"
+      "sha256": "2db9a69b8a64873eee7cd473ce2915df51ccfffb79f289ec01e0419d2861ba3e"
     },
     {
       "path": "scripts/gds/version-literal-guard.js",
@@ -9347,7 +9347,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "de0d452d14fef52118d0302145065609722f6fbdf333fcbf47ec5864cbd3d86a"
+      "sha256": "48518bea650f7714a9ff00aa6c5de38a1fced6c8c04cf050143254371c73f854"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -12704,6 +12704,11 @@
       "mode": "0000644",
       "sha256": "372c80d42e122a70a4fae8fcfbaaa47459575d3e0a2b80fff8876dfc512c5aeb"
     },
+    {
+      "path": "tests/version_close_cli.mjs",
+      "mode": "0000644",
+      "sha256": "7f7f4cc397bea0d319d5549b50aea178507dfeb2bdaf680fd42f4c80f56509ac"
+    },
     {
       "path": "tests/version_close_route.mjs",
       "mode": "0000644",
@@ -12722,12 +12727,12 @@
     {
       "path": "tests/version_promotion.mjs",
       "mode": "0000644",
-      "sha256": "43ba25381f3d02d7ecaaa8a2639bb8f1f72587d6966e6498db1c887b289148eb"
+      "sha256": "a2be1bb9ea506cac6f1d7e4c54fe4dbd07fbca5fbd64624c099c0faf8be528de"
     },
     {
       "path": "tests/version_roll_forward.mjs",
       "mode": "0000644",
-      "sha256": "fa0f079b8dff816806788bc34b6beb31e3366d5c7166e531108fe4ea40890373"
+      "sha256": "cb4b723c632f3ec5f3bdbf06057d252bfbe3052841548a8ac386984c52447fc9"
     },
     {
       "path": "tests/versions_route.mjs",

package/docs/module-api-changelog.md

@@ -1651,5 +1651,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.599 with no explicit bump. run 34187881031. (task 1002620)
   1.19.601 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.600 with no explicit bump. run 34188958832. (task 1002620)
+  1.19.602 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.601 with no explicit bump. run 34189930315. (task 1002620)
+  1.19.603 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.602 with no explicit bump. run 34191126290. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/lifecycle/db-versions.js

@@ -404,11 +404,27 @@ async function closeVersion({ versionId, plan = [], reason, planningVersionId =
         // Smoke fixtures are excluded on the same terms as the abandon branch, so
         // both doors agree about what "unfinished" means.
         const { rows: moved } = await client.query(
-          `UPDATE tasks SET goal_id = $2, updated_at = now()
+          // THE VERSION MOVES WITH THE GOAL (task 1003710). Setting only
+          // `goal_id` leaves the task in a goal on the SUCCESSOR while still
+          // stamped with the version that just closed, and that column is not
+          // decoration: `version_progress` joins `tasks t ON t.version_id = v.id`
+          // and `version-close.js` filters `WHERE version_id = $1` in three
+          // places. A half-moved task therefore counts against a SHIPPED version
+          // forever, never counts toward the successor, and leaves the closed
+          // version still reporting carry-over it no longer holds — surfacing as
+          // "V1 closed but still shows N carried", a long way from here.
+          //
+          // Identical to the fix task 1003709 made to `carryBugsForward`
+          // (db-goals.js). Both halves of the boundary move — the roll-forward
+          // here and the maintenance carry-over there — and I shipped both with
+          // the same defect while only one got fixed. tests/version_roll_forward.mjs
+          // now pins the two against each other so the next edit cannot drift one
+          // without the other.
+          `UPDATE tasks SET goal_id = $2, version_id = $3, updated_at = now()
             WHERE goal_id = $1 AND ${nonTerminalSql('status')}
               AND title NOT LIKE '\\_\\_smoke\\_\\_%' ESCAPE '\\'
             RETURNING id`,
-          [step.goalId, successorId]
+          [step.goalId, successorId, planningVersionId]
         );
 
         await client.query(

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.601",
+  "version": "1.19.603",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.601",
+      "version": "1.19.603",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.601",
+  "version": "1.19.603",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/version-close.js

@@ -11,12 +11,15 @@
 //   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. Prints the SQL needed to (a) flip the closing version to 'shipped',
-//      (b) insert the next-version row with status='building', and
-//      (c) rebind carry-over task version_id values. The GDS API does not
-//      yet expose endpoints for these operations; per task #43 spec this
-//      ships with explicit "MANUAL STEP REQUIRED" output rather than
-//      extending routes.js (out of touches[]).
+//   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.
@@ -38,7 +41,7 @@ const REPO_ROOT = path.resolve(__dirname, '..', '..');
 // -------------------------------------------------------------------------
 
 function parseArgs(argv) {
-  const out = { versionId: null, yes: false, nextId: null, noNextStub: false };
+  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') {
@@ -49,6 +52,16 @@ function parseArgs(argv) {
       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('-')) {
@@ -62,8 +75,15 @@ function usage() {
   return [
     'Usage: node scripts/gds/version-close.js <VERSION_ID> [--yes|-y] [--next <ID>] [--no-next-stub]',
     '',
-    'Drafts <scope>-shipped.md + next-version stub, prints SQL for the',
-    'destructive parts. Always interactive without --yes.',
+    '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',
@@ -74,6 +94,8 @@ function usage() {
     '  node scripts/gds/version-close.js PMS-V2 --next GDS-V3',
     '  node scripts/gds/version-close.js PMS-V2 --yes',
     '  node scripts/gds/version-close.js PMS-V2 --no-next-stub',
+    '  node scripts/gds/version-close.js PMS-V2 --disposition 44=roll_forward \\',
+    '         --disposition 51=abandon --reason "V2 is done; 51 is not coming back"',
   ].join('\n');
 }
 
@@ -277,74 +299,66 @@ function buildNextVersionStub({ nextVersionId, prevVersionId, carryOverTasks })
 }
 
 // -------------------------------------------------------------------------
-// SQL builders (no API endpoints exist for these — print as manual steps)
+// 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.
 
-function sqlEscape(s) {
-  return String(s).replace(/'/g, "''");
+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 };
 }
 
-function buildManualSql({ versionId, versionName, nextVersionId, nextScopeDocPath, carryOverTasks, nextVersionExists }) {
+// 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 = [
-    '-- MANUAL STEP REQUIRED -----------------------------------------------',
-    '-- The GDS API does not currently expose endpoints for: version status',
-    '-- transitions, version creation from CLI, or task version_id rebinding.',
-    '-- Run the SQL below on the production droplet (psql amazonprimea).',
-    '-- ---------------------------------------------------------------------',
-    'BEGIN;',
+    `[refused] ${versionId} still holds ${goals.length} open goal(s). Nothing was changed.`,
     '',
-    `-- 1. Close ${versionId}.`,
-    `UPDATE versions`,
-    `   SET status = 'shipped'`,
-    `     , shipped_at = now()`,
-    ` WHERE id = '${sqlEscape(versionId)}'`,
-    `   AND status = 'building';`,
+    'Decide what happens to each, then re-run with --disposition:',
     '',
   ];
-
-  if (nextVersionExists) {
-    lines.push(`-- 2. ${nextVersionId} already exists in the versions table — no INSERT needed.`);
-    lines.push('');
-  } else {
-    lines.push(`-- 2. Insert ${nextVersionId} stub with status='building'.`);
-    lines.push(`INSERT INTO versions (id, name, track, status, scope_doc_path, started_at)`);
-    lines.push(`VALUES ('${sqlEscape(nextVersionId)}',`);
-    lines.push(`        '${sqlEscape(nextVersionId)}',`);
-    lines.push(`        (SELECT track FROM versions WHERE id = '${sqlEscape(versionId)}'),`);
-    lines.push(`        'building',`);
-    lines.push(`        '${sqlEscape(nextScopeDocPath)}',`);
-    lines.push(`        now())`);
-    lines.push(`ON CONFLICT (id) DO NOTHING;`);
-    lines.push('');
+  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}`);
   }
-
-  if (carryOverTasks.length > 0) {
-    const ids = carryOverTasks.map((t) => t.id).join(', ');
-    lines.push(`-- 3. Rebind ${carryOverTasks.length} carry-over task(s) to ${nextVersionId}.`);
-    lines.push(`UPDATE tasks`);
-    lines.push(`   SET version_id = '${sqlEscape(nextVersionId)}'`);
-    lines.push(`     , updated_at = now()`);
-    lines.push(` WHERE id IN (${ids})`);
-    lines.push(`   AND version_id = '${sqlEscape(versionId)}'`);
-    lines.push(`   AND status IN ('backlog', 'ready');`);
-    lines.push('');
-  } else {
-    lines.push(`-- 3. No carry-over tasks — skip rebind step.`);
-    lines.push('');
-  }
-
-  lines.push('COMMIT;');
-  lines.push('-- ---------------------------------------------------------------------');
+  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/gds/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)'}.`,
-    '- Run the printed SQL on the droplet to flip version status + rebind tasks.',
+    '- 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`;
 }
@@ -500,34 +514,85 @@ async function main() {
     } 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: print manual SQL + commit message.
-  const sql = buildManualSql({
-    versionId,
-    versionName: target.name,
-    nextVersionId,
-    nextScopeDocPath: nextScopeDocRel,
-    carryOverTasks: carryOver,
-    nextVersionExists,
-  });
+  // 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('');
-  console.log(sql);
+  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 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 ---');
+  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} close drafted. Run the SQL above on the droplet to finalize.`);
+  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) {
@@ -539,11 +604,11 @@ if (require.main === module) {
 
 module.exports = {
   parseArgs,
+  usage,
   deriveNextVersionId,
   deriveNextScopePath,
   deriveShippedPath,
   buildShippedArchive,
   buildNextVersionStub,
-  buildManualSql,
   buildCommitMessage,
 };

package/src/module-api.js

@@ -55,7 +55,7 @@ const { buildInfo } = require('./build-info');
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.601'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.603'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/version_close_cli.mjs

@@ -0,0 +1,164 @@
+// tests/version_close_cli.mjs — version-close.js drives the ROUTE, and no longer
+// prints SQL for a human to paste into the production droplet
+// (BV1.R23, task 1003610, goal 1000086).
+//
+// WHAT THIS SCRIPT USED TO DO, AND WHY IT WAS RIGHT AT THE TIME. It ended with a
+// `-- MANUAL STEP REQUIRED` block: three UPDATEs to flip the version, insert the
+// successor and rebind carry-over tasks, with the instruction to run them on the
+// droplet. Its own header explained why — "the GDS API does not currently expose
+// endpoints for version status transitions" — and that was simply true.
+//
+// WHY IT IS NOW THE MOST DANGEROUS THING IN THE FILE. BV1.R12 (task 1003599)
+// built `POST /versions/:id/close`, so the claim became false. Worse, by then the
+// route had accumulated everything 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 every one of them — a goal
+// left open on a shipped version, a defect queue entombed where nothing routes,
+// no successor promoted. The bypass was printed by the tool meant to prevent it.
+//
+// Run:  node --test tests/version_close_cli.mjs
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+
+process.env.NODE_ENV = 'test';
+const require = createRequire(import.meta.url);
+const { parseArgs, usage } = require('../scripts/gds/version-close.js');
+
+const SRC = readFileSync(new URL('../scripts/gds/version-close.js', import.meta.url), 'utf8');
+// Comments explain the history on purpose, so the prohibitions below read CODE.
+const CODE = SRC.replace(/\/\/[^\n]*/g, '').replace(/\/\*[\s\S]*?\*\//g, '');
+
+// ---------------------------------------------------------------------------
+// The bypass is gone
+// ---------------------------------------------------------------------------
+
+test('the script no longer BUILDS any version-mutating SQL', () => {
+  assert.equal(/buildManualSql/.test(CODE), false, 'the SQL builder must be deleted, not merely unused');
+  for (const bad of [/UPDATE\s+versions/i, /INSERT INTO versions/i, /UPDATE\s+tasks/i]) {
+    assert.equal(bad.test(CODE), false, `the script must not emit ${bad} — that is the path around every rule this goal built`);
+  }
+});
+
+test('it does not tell the operator to run anything on the droplet', () => {
+  assert.equal(/MANUAL STEP REQUIRED/.test(CODE), false);
+  assert.equal(/psql/i.test(CODE), false);
+  assert.equal(/droplet/i.test(CODE), false);
+});
+
+test('the commit message no longer promises SQL that will not be run', () => {
+  // It said "Run the printed SQL on the droplet to flip version status" — a
+  // commit body describing a step that no longer exists is a instruction someone
+  // eventually follows.
+  assert.equal(/Run the printed SQL/.test(CODE), false);
+  assert.match(SRC, /this commit is the drafted docs only/);
+});
+
+// ---------------------------------------------------------------------------
+// It calls the route
+// ---------------------------------------------------------------------------
+
+test('the close goes through POST /versions/:id/close', () => {
+  assert.match(CODE, /postVersionsIdClose\(\{ path: \{ id: versionId \}, body \}\)/);
+});
+
+test('a disposition map is only sent when there is one', () => {
+  // The route treats an EMPTY map as "the caller dispositioned nothing", which is
+  // a different call from "the caller sent no map at all" — the first can satisfy
+  // a close of a version holding no open goals, the second is the two-step's
+  // first leg. Sending `{}` unconditionally would blur them.
+  assert.match(CODE, /if \(dispositions && Object\.keys\(dispositions\)\.length > 0\) body\.dispositions = dispositions;/);
+});
+
+test('the advisory half is kept — this is still the script that drafts the archive', () => {
+  // The brief is explicit that suggestClose stays. Only the destructive tail moved.
+  assert.match(CODE, /fetchCloseSuggestions/);
+  assert.match(CODE, /buildShippedArchive|shippedDocPath/);
+});
+
+// ---------------------------------------------------------------------------
+// The two-step, rendered for a human
+// ---------------------------------------------------------------------------
+
+test('an open-goals refusal lists the goals and the exact re-run', () => {
+  // R12 refuses and RETURNS the goals precisely so the caller can decide per
+  // goal. Dumping that JSON would make the operator translate it themselves.
+  assert.match(CODE, /renderOpenGoalsRefusal/);
+  assert.match(SRC, /--disposition <goalId>=roll_forward/);
+  assert.match(SRC, /--disposition <goalId>=abandon/);
+});
+
+test('both incomplete-disposition refusals are handled, not just one', () => {
+  // The route answers `version_holds_open_goals` when nothing was sent and
+  // `disposition_incomplete` when a partial map was. Handling only the first
+  // leaves the commoner second attempt printing a bare error code.
+  assert.match(CODE, /version_holds_open_goals/);
+  assert.match(CODE, /disposition_incomplete/);
+});
+
+test('any other refusal is RELAYED by name, not re-worded', () => {
+  // ADR 0250 §7: the codes are named so an agent can act on them. Re-phrasing one
+  // into prose makes it unsearchable.
+  assert.match(CODE, /\[refused\] \$\{err\}/);
+});
+
+test('a refusal exits non-zero', () => {
+  assert.match(CODE, /process\.exitCode = 1;/);
+});
+
+// ---------------------------------------------------------------------------
+// The flags
+// ---------------------------------------------------------------------------
+
+test('--disposition parses into the exact map shape the route expects', () => {
+  const a = parseArgs(['node', 'x', 'BONGOS-V1', '--disposition', '44=roll_forward', '--disposition=51=abandon']);
+  assert.deepEqual(a.dispositions, { 44: { verb: 'roll_forward' }, 51: { verb: 'abandon' } },
+    'so the operator never hand-writes JSON');
+  assert.equal(a.versionId, 'BONGOS-V1');
+});
+
+test('--reason survives both spellings', () => {
+  assert.equal(parseArgs(['n', 'x', 'V', '--reason', 'because']).reason, 'because');
+  assert.equal(parseArgs(['n', 'x', 'V', '--reason=because']).reason, 'because');
+});
+
+test('a malformed --disposition is dropped rather than sent as nonsense', () => {
+  // `--disposition 44` with no verb would otherwise reach the route as
+  // {44: {verb: undefined}} and come back a bad_disposition the operator has to
+  // decode. Dropping it means the close refuses with the goal still listed.
+  const a = parseArgs(['n', 'x', 'V', '--disposition', '44', '--disposition', '=abandon']);
+  assert.deepEqual(a.dispositions, {});
+});
+
+test('no flags means no dispositions — nothing is cut by omission', () => {
+  assert.deepEqual(parseArgs(['n', 'x', 'V']).dispositions, {});
+  assert.equal(parseArgs(['n', 'x', 'V']).reason, null);
+});
+
+test('usage documents both new flags', () => {
+  const u = usage();
+  assert.match(u, /--reason/);
+  assert.match(u, /--disposition/);
+  assert.match(u, /POST \/versions\/:id\/close/);
+  assert.equal(/SQL/.test(u), false, 'the usage must not still advertise printed SQL');
+});
+
+// ---------------------------------------------------------------------------
+// The close is still a confirmed, destructive act
+// ---------------------------------------------------------------------------
+
+test('without --yes the operator is asked before the version closes', () => {
+  // Closing cannot be undone through the API (ADR 0263 §2: nothing un-closes a
+  // version), so this is the one prompt that must not be dropped.
+  assert.match(CODE, /if \(!args\.yes\) \{[\s\S]{0,200}prompter\.ask\(`Close \$\{versionId\}/);
+});
+
+test('the prompter is closed on every exit, including the refusal returns', () => {
+  // Step 8 returns early on a refusal. A leaked readline keeps the process alive,
+  // which on a CLI reads as a hang rather than a failure — so the close step runs
+  // inside the same try whose finally closes it.
+  assert.match(CODE, /return await closeStep\(\);\s*\}\s*finally \{\s*prompter\.close\(\);/);
+});

package/tests/version_promotion.mjs

@@ -128,7 +128,11 @@ test('the hook is composed in the ROUTE, not inside closeVersion', () => {
   // the module's require DAG — and the route is the one place already holding the
   // whole facade. Reaching sideways between the units is how that DAG stops being
   // one.
-  assert.equal(/carryBugsForward/.test(DBV), false,
+  // Comments stripped: db-versions.js NAMES carryBugsForward in prose (task
+  // 1003710's fix note points at the identical fix made there), and a check that
+  // read the explanation would fail on the cross-reference rather than on a call.
+  const dbvCode = DBV.replace(/\/\/[^\n]*/g, '');
+  assert.equal(/carryBugsForward/.test(dbvCode), false,
     'db-versions.js must not reach into db-goals.js');
   assert.match(ROUTES, /db\.promotePlanningVersion\(client\)/);
   assert.match(ROUTES, /db\.carryBugsForward\(/);

package/tests/version_roll_forward.mjs

@@ -36,7 +36,16 @@ const ROUTES = src('modules/lifecycle/routes/versions.js');
 
 // The roll_forward branch, sliced so assertions land on the right code.
 const CLOSE = DBV.slice(DBV.indexOf('async function closeVersion'));
-const ROLL = CLOSE.slice(CLOSE.indexOf("verb: 'roll_forward'") - 4000, CLOSE.indexOf('// The invariant'));
+// The roll_forward branch, bounded by its own `else {` and the invariant check
+// that follows the disposition loop. Anchored on real markers rather than a
+// character offset: a `- 4000` window silently stopped reaching the branch's own
+// guard the moment the branch grew (task 1003710 added a comment and broke it).
+const ROLL = (() => {
+  const start = CLOSE.lastIndexOf('} else {', CLOSE.indexOf("verb: 'roll_forward', result: 'succeeded'"));
+  const end = CLOSE.indexOf('// The invariant');
+  if (start === -1 || end === -1) throw new Error('roll_forward branch markers moved — fix this slice, do not widen it');
+  return CLOSE.slice(start, end);
+})();
 
 // ---------------------------------------------------------------------------
 // The lineage
@@ -95,6 +104,33 @@ test('only UNFINISHED tasks are re-pointed; shipped work stays with the version
   assert.match(move, /smoke/, 'smoke fixtures are excluded on the same terms as the abandon branch');
 });
 
+test('the VERSION moves with the goal, not just the goal_id (task 1003710)', () => {
+  // THE BUG THIS PINS, and it shipped. Setting only `goal_id` leaves the task in
+  // a goal on the successor while still stamped with the version that closed.
+  // `version_progress` joins `tasks t ON t.version_id = v.id` and
+  // `version-close.js` filters `WHERE version_id = $1`, so the task counts
+  // against a SHIPPED version forever, never counts toward the successor, and
+  // leaves the closed version reporting carry-over it no longer holds.
+  const move = ROLL.slice(ROLL.indexOf('UPDATE tasks SET goal_id'), ROLL.indexOf('RETURNING id`,', ROLL.indexOf('UPDATE tasks SET goal_id')));
+  assert.match(move, /version_id = \$3/, 'the successor version must be written too');
+  assert.match(ROLL, /\[step\.goalId, successorId, planningVersionId\]/, 'and bound, not interpolated');
+});
+
+test('BOTH boundary moves write both columns — they cannot drift apart', () => {
+  // The roll-forward here and `carryBugsForward` in db-goals.js are the two ways
+  // a task crosses a version boundary. They shipped with the same defect and only
+  // one was fixed (task 1003709 fixed the carry-over, 1003710 this one). Pinning
+  // them against each other is what stops the next edit repeating it.
+  const dbg = src('modules/lifecycle/db-goals.js');
+  const carry = dbg.slice(dbg.indexOf('async function carryBugsForward'));
+  const carryMove = carry.slice(carry.indexOf('UPDATE tasks SET goal_id'));
+  for (const [name, sql] of [['roll_forward (db-versions.js)', ROLL.slice(ROLL.indexOf('UPDATE tasks SET goal_id'))],
+                             ['carryBugsForward (db-goals.js)', carryMove]]) {
+    assert.match(sql.slice(0, 200), /goal_id = \$2/, `${name}: must move goal_id`);
+    assert.match(sql.slice(0, 200), /version_id = \$3/, `${name}: must move version_id`);
+  }
+});
+
 test('the predecessor is archived LAST, after its work has left', () => {
   // The brief's explicit ask: it archives holding zero unfinished tasks, so it
   // passes R10's own closure check on the way out rather than being