@bongos/core 1.19.592 → 1.19.594

package/modules/lifecycle/db-versions.js

@@ -13,6 +13,7 @@
 const api = require('../../src/module-api');
 const { pool, withTx } = api;
 const doneWhen = require('./done-when.js');
+const { nonTerminalSql } = require('./task-status');
 
 async function listVersions() {
   const { rows } = await pool.query(
@@ -34,7 +35,12 @@ async function getVersion(id) {
 }
 
 
-async function versionProgress() {
+// Accepts the #538 deps.pool test seam (honoured ONLY under NODE_ENV==='test'),
+// like its siblings in this family — added by BV1.R15 (task 1003602) so the
+// admissions join below is assertable without a live Postgres. Every caller
+// passes nothing and is unchanged.
+async function versionProgress(deps = {}) {
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
   // Joins the rolled-up progress view (any of completed/confirmed/shipped counts
   // as "done") with the per-state breakdown view from migration 012 so the
   // public dashboard can render a stacked three-segment progress bar.
@@ -46,14 +52,15 @@ async function versionProgress() {
   // uses criteria_count > 0 to tell a genuinely-active version from a freshly
   // stubbed "future placeholder" (e.g. a next-version row created by
   // version-close that has no criteria seeded yet) without needing a schema flag.
-  const { rows } = await pool.query(
+  const { rows } = await activePool.query(
     `SELECT vp.version_id, vp.name, vp.status,
             vp.shipped_count, vp.total_count, vp.shipped_weight, vp.total_weight,
             v.done_when,
             COALESCE(dwc.criteria_count, 0) AS criteria_count,
             COALESCE(vlb.completed_count, 0) AS lifecycle_completed_count,
             COALESCE(vlb.confirmed_count, 0) AS lifecycle_confirmed_count,
-            COALESCE(vlb.shipped_count,   0) AS lifecycle_shipped_count
+            COALESCE(vlb.shipped_count,   0) AS lifecycle_shipped_count,
+            COALESCE(adm.admission_count, 0) AS admission_count
        FROM version_progress vp
        LEFT JOIN version_lifecycle_breakdown vlb ON vlb.version_id = vp.version_id
        LEFT JOIN versions v ON v.id = vp.version_id
@@ -62,14 +69,34 @@ async function versionProgress() {
            FROM done_when_criteria
           GROUP BY version_id
        ) dwc ON dwc.version_id = vp.version_id
+       LEFT JOIN (
+         SELECT version_id, count(*) AS admission_count
+           FROM lifecycle_goal_version_admissions
+          GROUP BY version_id
+       ) adm ON adm.version_id = vp.version_id
        ORDER BY vp.version_id`
   );
+  // BV1.R15 (task 1003602, goal 1000086, ADR 0250 §3): "the overrides are
+  // counted and shown on the version." R07 put the count on
+  // `GET /versions/:id/progress` — a per-version route the roadmap never calls.
+  // The surface a person actually looks at reads THIS rollup, so the count rides
+  // here too, and an override becomes visible without anyone knowing to go
+  // looking for it. That is the whole mechanism: a counter nobody encounters is
+  // indistinguishable from no gate at all.
+  //
+  // Folded into the existing query as one more LEFT JOIN rather than a second
+  // round-trip or a require of db-goals.js: this file and that one are SIBLINGS
+  // in the module's require DAG (see modules/lifecycle/CLAUDE.md), and reaching
+  // sideways for one aggregate is how that DAG stops being one. COALESCE, not a
+  // JOIN that manufactures a zero row — a version nobody widened has no row here
+  // at all, which is the common case.
   return rows.map((r) => ({
     ...r,
     criteria_count: Number(r.criteria_count),
     lifecycle_completed_count: Number(r.lifecycle_completed_count),
     lifecycle_confirmed_count: Number(r.lifecycle_confirmed_count),
     lifecycle_shipped_count: Number(r.lifecycle_shipped_count),
+    admission_count: Number(r.admission_count),
     percent_complete:
       r.total_weight > 0 ? Math.round((Number(r.shipped_weight) / Number(r.total_weight)) * 100) : 0,
   }));
@@ -160,8 +187,173 @@ async function currentBuildingVersionId(deps = {}) {
   return rows[0] ? rows[0].id : null;
 }
 
+// maintenanceGoalExemptSql — "this goal is NOT the version's maintenance goal",
+// as one SQL predicate with ONE definition (BV1.R12, task 1003599; ADR 0263 §7).
+//
+// READ THIS BEFORE CHANGING IT. Today the maintenance goal is identified BY TITLE,
+// because no column says which goal it is — `ensureMaintenanceGoal` (db-goals.js)
+// matches `"<version> — maintenance"` and its own comment flags that as task
+// 1003605's (R18) debt. That is a provenance wrinkle for ROUTING, where the worst
+// case is a hand-titled goal receiving a bug. It is a much worse wrinkle HERE: this
+// predicate decides which goals hold a VERSION open, so a hand-titled goal would
+// silently exempt itself from the gate that decides when a version may close.
+//
+// So it is named, used in exactly one place, and R18 replaces its BODY with
+// `NOT g.is_maintenance` once the column exists — one edit, no call sites to find.
+// The parameter is the version id placeholder the caller has already bound.
+function maintenanceGoalExemptSql(titleParam) {
+  return `g.title <> (${titleParam} || ' — maintenance')`;
+}
+
+// openNonMaintenanceGoals — the goals that hold a version open, id + title +
+// how much unfinished work each still carries (BV1.R12).
+//
+// The task counts are here rather than fetched per goal because the caller's next
+// move is a per-goal decision — roll it forward or cut it — and "3 open tasks" vs
+// "0 open tasks" is most of that decision. Making the caller ask N more times is
+// how an agent ends up deciding without looking.
+async function openNonMaintenanceGoals(versionId, deps = {}) {
+  const exec = deps.client || ((deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool);
+  const { rows } = await exec.query(
+    `SELECT g.id::text, g.title,
+            (SELECT count(*)::int FROM tasks t
+              WHERE t.goal_id = g.id AND ${nonTerminalSql()}
+                AND t.title NOT LIKE '\\_\\_smoke\\_\\_%' ESCAPE '\\') AS open_tasks
+       FROM goals g
+      WHERE g.version_id = $1
+        AND g.status = 'open'
+        AND ${maintenanceGoalExemptSql('$1')}
+      ORDER BY g.sort_order, g.id`,
+    [versionId]
+  );
+  return rows;
+}
+
+// closeVersion — flip a building version to `shipped`, applying the caller's
+// per-goal disposition, in ONE transaction (BV1.R12, task 1003599, ADR 0263 §5).
+//
+// ATOMIC FOR THE SAME REASON R14's ARCHIVE IS. A partly-closed version — some
+// goals cut, some carried, the version still building — is a state no surface can
+// read and no caller can tell from the outside. One transaction makes the call
+// safe to retry verbatim after any error.
+//
+// The version row is locked FOR UPDATE first, so a goal cannot be created on it
+// (or achieved into it) between the plan validating and the flip landing.
+//
+// WHAT THIS DOES **NOT** DO, deliberately (ADR 0263 §§4, 8, 11):
+//   • It does not promote the planning version. That is task 1003607 (R20), which
+//     must run INSIDE this transaction and BEFORE any carry-over, because
+//     `ensureMaintenanceGoal` returns null for a non-`building` version. The seam
+//     is `deps.onClosed` below rather than a later edit to this function.
+//   • It does not create successor goals. `roll_forward` here only ABSTAINS from
+//     cutting the goal; task 1003604 (R17) does the lineage write. Until it ships,
+//     a rolled-forward goal simply stays open on the closed version — visible and
+//     recoverable, which is the right failure while half the feature exists.
+//   • It does not write `limitations/<version>-shipped.md`. That is a repo file; a
+//     route cannot write one, and file I/O has no business in this transaction.
+//
+// `plan` is planVersionClose's validated output: [{ goalId, verb }].
+async function closeVersion({ versionId, plan = [], reason }, deps = {}) {
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const client = await activePool.connect();
+  try {
+    await client.query('BEGIN');
+
+    const { rows: vRows } = await client.query(
+      `SELECT id, name, track, status, scope_doc_path, started_at, shipped_at, done_when
+         FROM versions WHERE id = $1 FOR UPDATE`,
+      [versionId]
+    );
+    if (!vRows[0]) throw Object.assign(new Error('version not found'), { code: 'VERSION_NOT_FOUND' });
+    if (vRows[0].status !== 'building') {
+      throw Object.assign(new Error('version is not building'), {
+        code: 'VERSION_NOT_BUILDING', versionStatus: vRows[0].status,
+      });
+    }
+
+    const applied = [];
+    for (const step of plan) {
+      const { rows: gRows } = await client.query(
+        `SELECT id, title, status FROM goals WHERE id = $1 AND version_id = $2 FOR UPDATE`,
+        [step.goalId, versionId]
+      );
+      // The goal moved or closed itself while the caller was deciding. Not an
+      // error — the final re-count is what guards the invariant — but recorded so
+      // the response says what this call actually did.
+      if (!gRows[0]) { applied.push({ goal_id: String(step.goalId), verb: step.verb, result: 'skipped_not_on_version' }); continue; }
+      if (gRows[0].status !== 'open') {
+        applied.push({ goal_id: String(step.goalId), verb: step.verb, result: 'skipped_already_closed', status: gRows[0].status });
+        continue;
+      }
+
+      if (step.verb === 'abandon') {
+        // A goal cut by a close takes its open tasks with it, stamped with the
+        // close's reason — the same stamp R14 writes, so the ledger reads
+        // identically whichever door retired the work.
+        const { rows: killed } = await client.query(
+          `UPDATE tasks SET status = 'abandoned',
+                            value_summary = COALESCE(NULLIF($2, ''), value_summary),
+                            updated_at = now()
+            WHERE goal_id = $1 AND ${nonTerminalSql()}
+              AND title NOT LIKE '\\_\\_smoke\\_\\_%' ESCAPE '\\'
+            RETURNING id`,
+          [step.goalId, `Abandoned: ${reason}`]
+        );
+        await client.query(`UPDATE goals SET status = 'archived', updated_at = now() WHERE id = $1`, [step.goalId]);
+        applied.push({ goal_id: String(step.goalId), verb: 'abandon', result: 'archived', tasks_abandoned: killed.length });
+      } else {
+        // roll_forward: left OPEN on purpose until R17 (task 1003604) writes the
+        // successor + `succeeded_by_goal_id` lineage. Reported so a reader is not
+        // left wondering why the goal is still there.
+        applied.push({ goal_id: String(step.goalId), verb: 'roll_forward', result: 'carried_pending_successor' });
+      }
+    }
+
+    // The invariant, asserted against committed-in-txn state rather than against
+    // the plan — the one check a bug in the planner cannot fool. `roll_forward`
+    // goals are expected to still be open, so they are excluded by id.
+    const carried = plan.filter((p) => p.verb === 'roll_forward').map((p) => Number(p.goalId));
+    const { rows: left } = await client.query(
+      `SELECT count(*)::int AS n FROM goals g
+        WHERE g.version_id = $1 AND g.status = 'open'
+          AND ${maintenanceGoalExemptSql('$1')}
+          AND NOT (g.id = ANY($2::bigint[]))`,
+      [versionId, carried]
+    );
+    if ((left[0]?.n ?? 0) > 0) {
+      throw Object.assign(new Error('version still holds open goals after dispositions'), {
+        code: 'CLOSE_INCOMPLETE_AFTER_APPLY', remaining: left[0].n,
+      });
+    }
+
+    const { rows: closed } = await client.query(
+      `UPDATE versions SET status = 'shipped', shipped_at = now()
+        WHERE id = $1
+        RETURNING id, name, track, status, scope_doc_path, started_at, shipped_at, done_when`,
+      [versionId]
+    );
+
+    // The seam R20 (task 1003607) hooks: promotion + bug carry-over must happen
+    // HERE, inside this transaction and after the flip, so the successor is
+    // already `building` when `ensureMaintenanceGoal` is asked for it.
+    let after = null;
+    if (typeof deps.onClosed === 'function') after = await deps.onClosed(client, { versionId, plan, reason });
+
+    await client.query('COMMIT');
+    return { version: closed[0], applied, after };
+  } catch (err) {
+    try { await client.query('ROLLBACK'); } catch { /* the original error is the one that matters */ }
+    throw err;
+  } finally {
+    client.release();
+  }
+}
+
 module.exports = {
+  closeVersion,
   createVersion,
+  maintenanceGoalExemptSql,
+  openNonMaintenanceGoals,
   currentBuildingVersionId,
   getVersion,
   listVersions,

package/modules/lifecycle/db.js

@@ -63,7 +63,7 @@ const {
   singleRungPromotionError,
   xenosClaimAllowed,
 } = require('./db-rank-authz.js');
-const { createVersion, currentBuildingVersionId, getVersion, listVersions, versionProgress, versionsWithStatus } = require('./db-versions.js');
+const { closeVersion, createVersion, currentBuildingVersionId, getVersion, listVersions, maintenanceGoalExemptSql, openNonMaintenanceGoals, versionProgress, versionsWithStatus } = require('./db-versions.js');
 const {
   acceptMembershipRequestAndAddMember,
   achieveGoalIfComplete,
@@ -217,7 +217,10 @@ module.exports = {
   listVersions,
   getVersion,
   versionProgress,
+  maintenanceGoalExemptSql,
+  openNonMaintenanceGoals,
   versionsWithStatus,
+  closeVersion,
   createVersion,
   currentBuildingVersionId,
   createGoal,

package/modules/lifecycle/routes/goals.js

@@ -293,7 +293,7 @@ module.exports = function buildGoalsRouter() {
     try {
       const goal = await db.getGoal(id);
       if (!goal) return res.fail('goal_not_found', 404);
-      const [members, criteria, dependencies, criterionless_task_count, admitted] = await Promise.all([
+      const [members, criteria, dependencies, criterionless_task_count, admitted, openTasks] = await Promise.all([
         db.listGoalMembers(id),
         db.listCriteriaForGoal(id),
         db.getGoalDependencies(id),  // task 1761 — prerequisite goals + satisfied state
@@ -306,11 +306,25 @@ module.exports = function buildGoalsRouter() {
         // override is worthless as an audit trail if reading the goal never
         // shows it.
         db.getGoalAdmission(id),
+        // BV1.R24 (task 1003611): WHAT IS ACTUALLY HOLDING THIS GOAL OPEN.
+        //
+        // Until R08/R09 (tasks 1003595, 1003596) a goal closed on its criteria
+        // alone, so "N of M criteria satisfied" was the whole answer and this page
+        // told the truth. It is not the whole answer any more: ADR 0250 D2 added
+        // "AND no task in it is non-terminal", and a task linked to NO criterion
+        // now holds the goal open while appearing nowhere in the rollup. A builder
+        // reading 5-of-5 and finding the goal still open has no way to see why.
+        //
+        // The SAME read the archive refusal returns (openTasksInGoal), so the page
+        // and the 409 cannot disagree about what is in the way — and it is what the
+        // archive flow previews before collecting a disposition.
+        db.openTasksInGoal(id),
       ]);
       const byId = await goalCategory.categoryIndex();
       return res.json({
         goal: goalCategory.decorateGoalCategory(decorateGoalScope(goal), byId),
         members, criteria, dependencies, criterionless_task_count, admitted,
+        open_tasks: openTasks,
       });
     } catch (err) {
       log.error('[gds] GET /goals/:id', err);

package/modules/lifecycle/routes/version-route-authz.js

@@ -93,4 +93,134 @@ function authorizeVersionBuild({ building = [] }) {
   };
 }
 
-module.exports = { authorizeVersionCreate, authorizeVersionBuild };
+// planVersionClose — the PURE decision behind POST /versions/:id/close
+// (BV1.R12, task 1003599, goal 1000086, ADR 0250 D5, ADR 0263 §5).
+//
+// THE ASYMMETRY THAT SHAPES THIS (ADR 0263 §3): auto-close fires when the last
+// non-maintenance goal achieves, so by construction NOTHING is left to
+// disposition on that path. Every rule below therefore belongs to EARLY close —
+// an Archon deliberately closing a version that still holds open goals — and the
+// auto path (task 1003603, R16) reaches the same writer with an empty plan.
+//
+// THE SHAPE IS R14'S ARCHIVE TWO-STEP, deliberately (planGoalArchiveDispositions
+// in goal-route-authz.js): refuse once, RETURNING the work; accept a total
+// disposition map on the second call. Two idioms for the same interaction is how
+// two surfaces drift, and agents already know this one.
+//
+// `openGoals` is the version's open, NON-MAINTENANCE goals — the maintenance goal
+// is exempt from the count (ADR 0263 §7) and always carries forward, so it is
+// never the caller's decision and must be filtered out BEFORE this is called.
+//
+// Returns { ok: true, plan: [{ goalId, verb }] } ordered to match `openGoals`, or
+// { ok: false, status, body } — the exact HTTP status and JSON the route sends.
+const VERSION_CLOSE_VERBS = new Set(['roll_forward', 'abandon']);
+
+function planVersionClose({ version, openGoals = [], dispositions = null, reason = '' }) {
+  if (!version) {
+    return { ok: false, status: 404, body: { error: 'version_not_found', message: 'No such version.' } };
+  }
+  // Only a BUILDING version closes. Closing a `planning` one is meaningless
+  // (nothing was built) and closing a `shipped`/`frozen` one is a double-close;
+  // saying which status refused beats asserting one the caller can see is wrong.
+  if (version.status !== 'building') {
+    return {
+      ok: false,
+      status: 409,
+      body: {
+        error: 'version_not_building',
+        status: version.status,
+        message: `Version '${version.id}' is '${version.status}' — only a building version can close.`,
+      },
+    };
+  }
+
+  const held = Array.isArray(openGoals) ? openGoals.filter(Boolean) : [];
+  if (held.length === 0) return { ok: true, plan: [] };
+
+  if (!dispositions || typeof dispositions !== 'object' || Array.isArray(dispositions)) {
+    return {
+      ok: false,
+      status: 409,
+      body: {
+        error: 'version_holds_open_goals',
+        message: `Version '${version.id}' still holds ${held.length} open goal(s). Re-submit with a \`dispositions\` map saying what happens to each — {"<goal id>":{"verb":"roll_forward"}} or {"<goal id>":{"verb":"abandon"}}.`,
+        details: { total: held.length, shown: held.length, goals: held },
+      },
+    };
+  }
+
+  // A goal abandoned by a close is stamped with the close's reason, the way R14
+  // stamps a task. A close that disposes of someone's goal without saying why is
+  // the silent discard D3 forbids, one tier up.
+  if (typeof reason !== 'string' || reason.trim().length === 0) {
+    return {
+      ok: false,
+      status: 400,
+      body: {
+        error: 'close_reason_required',
+        message: 'Closing a version that still holds open goals records why. Pass a non-empty `reason`; it is stamped onto everything this call abandons.',
+      },
+    };
+  }
+
+  const plan = [];
+  const missing = [];
+  for (const g of held) {
+    const d = dispositions[String(g.id)];
+    if (!d || typeof d !== 'object') { missing.push(g); continue; }
+    const verb = typeof d.verb === 'string' ? d.verb : null;
+    if (!VERSION_CLOSE_VERBS.has(verb)) {
+      return {
+        ok: false,
+        status: 400,
+        body: {
+          error: 'bad_disposition',
+          message: `Goal #${g.id}: verb must be "roll_forward" or "abandon".`,
+          details: { goal_id: String(g.id), verb: d.verb ?? null, valid: Array.from(VERSION_CLOSE_VERBS) },
+        },
+      };
+    }
+    plan.push({ goalId: Number(g.id), verb });
+  }
+
+  if (missing.length > 0) {
+    return {
+      ok: false,
+      status: 400,
+      body: {
+        error: 'disposition_incomplete',
+        message: `${missing.length} of ${held.length} open goal(s) have no disposition. Every one needs a decision — nothing is carried or cut by omission.`,
+        details: { total: held.length, undecided: missing.length, goals: missing },
+      },
+    };
+  }
+  return { ok: true, plan };
+}
+
+// rollForwardNeedsPlanningVersion — a `roll_forward` needs somewhere to roll TO.
+//
+// REFUSED RATHER THAN AUTO-CREATED, and that is the decision worth remembering
+// (ADR 0263 §5): cutting the successor version is a scope decision with its own
+// criteria, and doing it implicitly inside a close is exactly the "fake hotfix
+// version" that ADR 0250 §3 built the override counter to prevent.
+//
+// Returns null when the close may proceed, or the refusal's parts.
+function rollForwardNeedsPlanningVersion({ plan = [], planning = [] }) {
+  if (!plan.some((p) => p.verb === 'roll_forward')) return null;
+  if (Array.isArray(planning) && planning.length > 0) return null;
+  return {
+    status: 409,
+    body: {
+      error: 'no_planning_version',
+      message: 'A goal was dispositioned `roll_forward`, but no version is in planning to receive it. Scope the next version first (POST /versions with status "planning"), or abandon the goal instead.',
+    },
+  };
+}
+
+module.exports = {
+  authorizeVersionCreate,
+  authorizeVersionBuild,
+  planVersionClose,
+  rollForwardNeedsPlanningVersion,
+  VERSION_CLOSE_VERBS,
+};

package/modules/lifecycle/routes/versions.js

@@ -23,7 +23,7 @@ const auth = api;
 const db = require('../db');
 const versionClose = require('../version-close');
 const doneWhen = require('../done-when');
-const { authorizeVersionCreate, authorizeVersionBuild } = require('./version-route-authz.js');
+const { authorizeVersionCreate, authorizeVersionBuild, planVersionClose, rollForwardNeedsPlanningVersion } = require('./version-route-authz.js');
 const { asyncHandler, validateOrRespond } = api;
 
 // versions.status CHECK (migration 003). A new version starts 'planning' or
@@ -225,5 +225,83 @@ module.exports = function buildVersionsRouter() {
     res.status(201).json({ version, criteria: created });
   }, { errorCode: 'create_version_failed' }));
 
+
+  // POST /versions/:id/close — the move a version has never had (BV1.R12, task
+  // 1003599, goal 1000086, ADR 0250 D5, ADR 0263 §5).
+  //
+  // The hierarchy had a bottom and no top: tasks close, criteria close, goals
+  // close, and a version only ever moved by hand-run SQL on the droplet —
+  // `scripts/gds/version-close.js` still PRINTS that the API cannot do this (task
+  // 1003610, R23, points it here). A thing with no closing move does not close,
+  // which is how two versions ended up building at once.
+  //
+  // Archon-only, behind the `version.close` permission that has existed at that
+  // floor since BV1.R105 and that, until now, NOTHING referenced.
+  //
+  // THE TWO-STEP IS R14's ARCHIVE, in spirit and in shape: call it bare and a
+  // version holding open goals refuses with the GOALS ATTACHED; re-submit with a
+  // total `dispositions` map and it closes. Agents already know that interaction,
+  // and a second idiom for the same thing is how two surfaces drift apart.
+  //
+  // Auto-close (task 1003603, R16) reaches `db.closeVersion` with an EMPTY plan
+  // and never touches this route: by construction it fires only when the last
+  // non-maintenance goal achieved, so nothing is left to disposition (ADR 0263 §3).
+  // rank: archon — the disposition that finalises a version's scope-truth.
+  router.post('/versions/:id/close', auth.requireBuilder, auth.requirePermission('version.close'), asyncHandler('POST /versions/:id/close', async (req, res) => {
+    // ADR 0118 / R12: declare the body, so a typo'd `disposition` (singular) is
+    // REJECTED rather than read as "none given" — which would take the refusal
+    // branch and tell a caller who sent a complete map that the version holds open
+    // goals. Contents are validated by planVersionClose, which names every
+    // malformed entry.
+    if (validateOrRespond(req, res, {
+      reason: { type: 'string', maxLength: 2000 },
+      dispositions: { type: 'object' },
+    })) return;
+    const versionId = String(req.params.id || '').trim();
+    if (!versionId) return res.fail('version_id_required', 400);
+
+    const version = await db.getVersion(versionId);
+    const reason = typeof req.body?.reason === 'string' ? req.body.reason.slice(0, 2000) : '';
+    // The maintenance goal is filtered out by the READ (ADR 0263 §7): it is exempt
+    // from the close count and always carries forward, so it is never the caller's
+    // decision and must not appear in a refusal asking them to make one.
+    const openGoals = version ? await db.openNonMaintenanceGoals(versionId) : [];
+
+    const plan = planVersionClose({ version, openGoals, dispositions: req.body?.dispositions ?? null, reason });
+    if (!plan.ok) return res.status(plan.status).json(plan.body);
+
+    // A roll_forward needs a planning version to roll INTO, and its absence is a
+    // REFUSAL rather than an auto-create: cutting the successor is a scope
+    // decision with its own criteria, and doing it implicitly inside a close is
+    // the "fake hotfix version" ADR 0250 §3 built the override counter to prevent.
+    const needsPlanning = rollForwardNeedsPlanningVersion({
+      plan: plan.plan,
+      planning: plan.plan.some((p) => p.verb === 'roll_forward') ? await db.versionsWithStatus('planning') : [],
+    });
+    if (needsPlanning) return res.status(needsPlanning.status).json(needsPlanning.body);
+
+    try {
+      const out = await db.closeVersion({ versionId, plan: plan.plan, reason });
+      return res.json({ ok: true, version: out.version, applied: out.applied });
+    } catch (err) {
+      if (err && err.code === 'VERSION_NOT_FOUND') return res.fail('version_not_found', 404);
+      if (err && err.code === 'VERSION_NOT_BUILDING') {
+        return res.fail('version_not_building', {
+          status: 409,
+          message: `Version '${versionId}' changed to '${err.versionStatus}' while the close was running — nothing was applied.`,
+          details: { status: err.versionStatus },
+        });
+      }
+      if (err && err.code === 'CLOSE_INCOMPLETE_AFTER_APPLY') {
+        return res.fail('version_holds_open_goals', {
+          status: 409,
+          message: `Version '${versionId}' still held ${err.remaining} open goal(s) after the dispositions were applied — nothing was changed. Re-read and retry.`,
+          details: { remaining: err.remaining },
+        });
+      }
+      throw err;
+    }
+  }, { errorCode: 'close_version_failed' }));
+
   return router;
 };

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.592",
+  "version": "1.19.594",
   "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",