@bongos/core 1.19.591 → 1.19.593

package/modules/lifecycle/db-goals.js

@@ -178,12 +178,22 @@ async function ensureMaintenanceGoal(versionId, deps = {}) {
 // version" — a visible counter is what keeps the exception honest, because an
 // override nobody can see is just a slower version of having no rule. Returns []
 // for the overwhelmingly common case of a version whose scope nobody widened.
+// BV1.R15 (task 1003602) carries the ADMITTER'S NAME, not just their id. R07
+// returned a bare `admitted_by`, which is enough to count an override and not
+// enough to answer the question ADR 0250 §3 actually asks — "by whom" — without
+// the caller issuing a second lookup per row. The whole point of the counter is
+// that abuse is legible at a glance; a column of numeric ids is not legible.
+// LEFT JOIN, not JOIN: an admission whose admitter was later offboarded must
+// still appear in the count. Losing the row would be the one failure mode that
+// matters, since it hides exactly the history someone would want to erase.
 async function listVersionAdmissions(versionId, deps = {}) {
   const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
   const { rows } = await activePool.query(
-    `SELECT a.goal_id, a.version_id, a.admitted_by, a.reason, a.created_at, g.title AS goal_title
+    `SELECT a.goal_id, a.version_id, a.admitted_by, a.reason, a.created_at, g.title AS goal_title,
+            b.github_login AS admitted_by_login, b.display_name AS admitted_by_name
        FROM lifecycle_goal_version_admissions a
        JOIN goals g ON g.id = a.goal_id
+       LEFT JOIN builders b ON b.id = a.admitted_by
       WHERE a.version_id = $1
       ORDER BY a.created_at DESC`,
     [versionId]
@@ -191,6 +201,7 @@ async function listVersionAdmissions(versionId, deps = {}) {
   return rows;
 }
 
+
 // getGoalAdmission (BV1.R07, task 1003594) — the override record for ONE goal, or
 // null when the goal was created normally. Null is the overwhelmingly common
 // answer and is not an absence of data: it is the positive fact "this goal did
@@ -244,10 +255,31 @@ async function getGoalDependencies(goalId, deps = {}) {
 // A caller that only needs the first N (the orphan advisory wants 5 candidates)
 // passes it so Postgres does the truncating instead of shipping the whole version's
 // goals to be discarded in JS (task 1002539).
+// BV1.R15 (task 1003602, goal 1000086, ADR 0250 §3) adds `admitted` — did this
+// goal enter its version through the Archon override rather than the scope gate?
+//
+// A BOOLEAN, not the admission row. The board renders one chip; the who and the
+// why belong on the goal's own page, where there is room to read them, and
+// shipping the reason on every row of a list would put an Archon's free text
+// through a surface that only needs a yes/no. `getGoalAdmission` is still the
+// read for the detail.
+//
+// EXISTS rather than a LEFT JOIN: one row per goal is guaranteed either way, and
+// a join that later gained a second admission row per goal would silently
+// duplicate goals in the board's list.
+//
+// The correlation names `goals.id` in full rather than aliasing the table, so
+// every other line of this query is UNCHANGED — the column list, the two filters
+// and the ORDER BY all still read unqualified. That is deliberate: aliasing the
+// table to `g` would have been tidier and would have rewritten four lines whose
+// literal text tests/goal_tier.mjs pins ("priority-first, then stable
+// ordering"). An additive change should read as additive in the diff.
 async function listGoals({ versionId = null, status = null, limit = null } = {}, deps = {}) {
   const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
   const { rows } = await activePool.query(
-    `SELECT ${GOAL_COLS}
+    `SELECT ${GOAL_COLS},
+            EXISTS (SELECT 1 FROM lifecycle_goal_version_admissions a
+                     WHERE a.goal_id = goals.id) AS admitted
        FROM goals
       WHERE ($1::text IS NULL OR version_id = $1)
         AND ($2::text IS NULL OR status = $2)

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

@@ -53,4 +53,174 @@ function authorizeVersionCreate({ status, planning = [] }) {
   };
 }
 
-module.exports = { authorizeVersionCreate };
+// authorizeVersionBuild — may a version ENTER `building` in this state?
+// (BV1.R19, task 1003606, goal 1000086, ADR 0250 D5, ADR 0263 §9.)
+//
+// THE RULE: exactly one version builds at a time. This is the invariant every
+// other rule in this goal stands on, and the one the live instance breaks today:
+// BONGOS-V1 and CB-V1 are both `building`, which is why "the current version" has
+// no meaning here. `currentBuildingVersionId` resolves that ambiguity with an
+// `ORDER BY started_at DESC ... LIMIT 1` — it picks one and says nothing — so
+// R03's gate ("is this version still in planning?") silently has two answers
+// depending on which row won. Task 1003614 (R27) resolves the existing violation;
+// this stops a third from ever being created.
+//
+// THE TWIN OF authorizeVersionCreate, and deliberately a SEPARATE function rather
+// than a second branch inside it. The two guard different slots, and this one has
+// a second caller coming: the close flow promotes the planning version to
+// `building` in its own transaction (task 1003607, R20), where there is no
+// caller-supplied `status` to branch on. One function taking a status would force
+// that path to pass a value it is not setting.
+//
+// `building` is the versions already in that state (id + name), read by the
+// caller. Passing the rows rather than a boolean lets the refusal NAME the
+// version holding the slot — the caller's next move is to close it or scope onto
+// it, and neither is answerable from a bare "no".
+//
+// Returns { ok: true } or { ok: false, status, body } — the exact HTTP status and
+// JSON the route sends.
+function authorizeVersionBuild({ building = [] }) {
+  const existing = Array.isArray(building) ? building.filter(Boolean) : [];
+  if (existing.length === 0) return { ok: true };
+  return {
+    ok: false,
+    status: 409,
+    body: {
+      error: 'building_version_exists',
+      message: `Version '${existing[0].id}' is already building — close it first, or scope this work onto it. One version builds at a time.`,
+      building: existing,
+    },
+  };
+}
+
+// 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,
+};