@bongos/core 1.19.589 → 1.19.590

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.589",
-  "core_contract": "1.19.589",
-  "source_commit": "29fe6277ac47bc629f56c68e20dca829ed9370f2",
+  "core_version": "1.19.590",
+  "core_contract": "1.19.590",
+  "source_commit": "250f70f068d2406d49d2b57306a8f3f1ebf0f1ab",
   "source_ref": "HEAD",
-  "built_at": "2026-09-08T02:16:53.692Z",
+  "built_at": "2026-09-08T02:32:23.112Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 457,
     "agent_docs_stubbed": 24,
-    "functional_verbatim": 2060,
+    "functional_verbatim": 2061,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2541,
-  "tree_sha256": "d96aab84f10a639efe4d035824854aed5cb9bf2fcc7723f62a69f4b1a8074591",
+  "file_count": 2542,
+  "tree_sha256": "ff91f93bb16afd98f8d2130615c602425ac4d133c4b01c83fbe94e6d8015f2cc",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -392,7 +392,7 @@
     {
       "path": "clients/bongos-client/index.d.ts",
       "mode": "0000644",
-      "sha256": "e5cfa78c545e60771166ae4118e18f5c7bcf911db649c115c2831a028de3562b"
+      "sha256": "3865a914bd9e50df23960dbad5783bd1584157ff2b2bfcd2b8e597a620e81c01"
     },
     {
       "path": "clients/bongos-client/index.mjs",
@@ -1847,12 +1847,12 @@
     {
       "path": "docs/api-reference.md",
       "mode": "0000644",
-      "sha256": "450613589b6b480ba2d6789731003794749c0dd972fcd8636380fa5814d68807"
+      "sha256": "5e2031bf695567cb4318ef792395150b7032604e0e4cd7cafee99f05e1d3cb01"
     },
     {
       "path": "docs/api/openapi.json",
       "mode": "0000644",
-      "sha256": "75ba055326939ec1c827d01cdf088f564e94f372d9906759483fd1bad2328375"
+      "sha256": "597f489b67a88154ee771baa8b378bf681594534cf7690c2ffd9c109cb26092d"
     },
     {
       "path": "docs/architecture.md",
@@ -2727,7 +2727,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "0ca6c49c46b3bc4621613099885595eb387c784e86f9fb83d5600912c1ea4c38"
+      "sha256": "c2736a86c941e12d08b38f798ab18eddf8a365ef709ed952778629d13ebf4e1d"
     },
     {
       "path": "docs/modules-contract.md",
@@ -5512,7 +5512,7 @@
     {
       "path": "modules/lifecycle/db-goals.js",
       "mode": "0000644",
-      "sha256": "f50a54a0e0f0cdeac5a2321b14757e52d9d9507417b1d1962aa09cdc6a222832"
+      "sha256": "392970a48349421c000de9581cfcc63969152179feb3406f1057571d9b68c0ee"
     },
     {
       "path": "modules/lifecycle/db-grade.js",
@@ -5552,7 +5552,7 @@
     {
       "path": "modules/lifecycle/db.js",
       "mode": "0000644",
-      "sha256": "6d69634ad12510f81727eeed0a8fdde4eac618fedc23e43e2c1aa5835aaf0388"
+      "sha256": "c3318a8473ccc9b41bff5eb94fe4096032c2d5c5a7819d0777c4d41db0e4d695"
     },
     {
       "path": "modules/lifecycle/dead-deps.js",
@@ -5732,12 +5732,12 @@
     {
       "path": "modules/lifecycle/routes/goal-route-authz.js",
       "mode": "0000644",
-      "sha256": "5022ec9cdd2ba5087bc0b4607691c21d361f4a4edbf029ff3dea37ade373e890"
+      "sha256": "3b4fb0168b29fb0df1260c23c5b14d96576f00f587dd5c188fe17a712e3dffaa"
     },
     {
       "path": "modules/lifecycle/routes/goals.js",
       "mode": "0000644",
-      "sha256": "d408d89cf736a7d4cdf45ccff44c2038bbc64b13be42dd1b460198dfc8112535"
+      "sha256": "28874a1b4d3e748866fa59d510c3c62656ad48039dae8ca7ce5b0ca5d47b357d"
     },
     {
       "path": "modules/lifecycle/routes/help-requests.js",
@@ -7602,12 +7602,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "57bf21d2c0b7e235c4628f7f1d7e52c8b65b30375d96adcce8558a5e1cce1b5a"
+      "sha256": "035ec486f26d0a18ffcc578a861b2758f79ea279371c4f88dfe5fdfa1b04fefe"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "fc682e53b7902f41fb4a455c9f61d70a5b154159df150b6e7e6c696c596df4e4"
+      "sha256": "05c57c598f80ce768e83bc0040feb275732545150cbcb3cd01341ff3633ea96f"
     },
     {
       "path": "public-docs/index.html",
@@ -9317,7 +9317,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "9264831ff874468719e9a6f73a3dfa39507f6ce033f25cdfc9d08e840d1a58fe"
+      "sha256": "b2b2d8c9ccf065e7bbc7b984ff9acda5f4400c9db4e9063678e6d996616f7d1c"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -10437,7 +10437,12 @@
     {
       "path": "tests/goal_archive_disposition.mjs",
       "mode": "0000644",
-      "sha256": "d2056a3ae84b79d64409e6e43c477f6b160f202903be61710b40bc4fd06c00c9"
+      "sha256": "bf0baad459ee2e103079a53570ca4998bb3ba66451ad0257478dd236118c8ce6"
+    },
+    {
+      "path": "tests/goal_archive_route_e2e.mjs",
+      "mode": "0000644",
+      "sha256": "ffefb97db455e2b6656f5c26933312572102e3a8aa37605545ae9b425d616be0"
     },
     {
       "path": "tests/goal_category.mjs",

package/clients/bongos-client/index.d.ts

@@ -252,7 +252,8 @@ export interface PostGithubRepoVisibilityRequest { repo: string; visibility: "pu
 export interface PostGithubRepoVisibilityResponse { ok: boolean; repo: unknown; private_deployable: boolean }
 export interface PostGithubReposRequest { name: string }
 export interface PostGithubReposResponse { repo: unknown }
-export interface PostGoalsIdArchiveResponse { ok: boolean; goal: unknown }
+export interface PostGoalsIdArchiveRequest { reason?: string; dispositions?: Record<string, unknown> }
+export interface PostGoalsIdArchiveResponse { ok: boolean; goal: unknown; applied: unknown }
 export interface PostGoalsIdConflictsResolveRequest { action: string; note?: string; touches?: string[]; first_task_id?: StringifiableId; then_task_id?: StringifiableId; task_id?: StringifiableId }
 export interface PostGoalsIdConflictsResolveResponse { ok: boolean; action: unknown; first_task_id?: unknown; then_task_id?: unknown; dependencies?: unknown; claim?: unknown; task_id?: unknown; touches?: unknown; requires_rank?: unknown }
 export interface PostGoalsIdInvitationsReqIdRescindResponse { ok: boolean; request: unknown }
@@ -676,7 +677,7 @@ export interface BongosClient {
     /** PATCH /goals/{id}/accepting-requests — rank: any-builder */
     patchGoalsIdAcceptingRequests(args?: RequestArgs): Promise<ApiResponse>;
     /** POST /goals/{id}/archive — rank: metic+archon */
-    postGoalsIdArchive(args?: RequestArgs): Promise<PostGoalsIdArchiveResponse>;
+    postGoalsIdArchive(args?: RequestArgs & { body?: PostGoalsIdArchiveRequest }): Promise<PostGoalsIdArchiveResponse>;
     /** PATCH /goals/{id}/category — rank: any-builder */
     patchGoalsIdCategory(args?: RequestArgs): Promise<ApiResponse>;
     /** GET /goals/{id}/conflicts — rank: any-builder */

package/docs/api/openapi.json

@@ -5139,6 +5139,17 @@
             "description": "Path parameter `id`."
           }
         ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostGoalsIdArchiveRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
         "responses": {
           "200": {
             "description": "Success.",
@@ -5151,7 +5162,7 @@
             }
           },
           "400": {
-            "$ref": "#/components/responses/BadRequest"
+            "$ref": "#/components/responses/ValidationFailed"
           },
           "401": {
             "$ref": "#/components/responses/Unauthorized"
@@ -19912,17 +19923,32 @@
           "repo"
         ]
       },
+      "PostGoalsIdArchiveRequest": {
+        "type": "object",
+        "properties": {
+          "reason": {
+            "type": "string",
+            "maxLength": 2000
+          },
+          "dispositions": {
+            "type": "object"
+          }
+        },
+        "additionalProperties": false
+      },
       "PostGoalsIdArchiveResponse": {
         "type": "object",
         "properties": {
           "ok": {
             "type": "boolean"
           },
-          "goal": {}
+          "goal": {},
+          "applied": {}
         },
         "required": [
           "ok",
-          "goal"
+          "goal",
+          "applied"
         ]
       },
       "PostGoalsIdConflictsResolveRequest": {
@@ -22676,7 +22702,7 @@
     }
   },
   "x-endpoint-count": 359,
-  "x-schema-count": 395,
+  "x-schema-count": 396,
   "x-undocumented-bodies": 9,
   "x-response-schemas": 267,
   "x-generated-by": "scripts/gds/gen-api-docs.js"

package/docs/api-reference.md

@@ -230,7 +230,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | GET | `/api/bongos/goals/:id` | `any-builder` | — | GET /goals/:id — one goal with its members + linked criteria (read). |
 | PATCH | `/api/bongos/goals/:id` | `any-builder` | — | PATCH /goals/:id — correct a goal's own title/subtitle/description (tasks 1003102, 1003224). |
 | PATCH | `/api/bongos/goals/:id/accepting-requests` | `any-builder` | — | PATCH /goals/:id/accepting-requests { accepting_requests } — a private goal's lead closes or re-opens it to join-requests (task 1002971, … |
-| POST | `/api/bongos/goals/:id/archive` | `metic+archon` | — | POST /goals/:id/archive — retire a goal (open\|achieved → archived). |
+| POST | `/api/bongos/goals/:id/archive` | `metic+archon` | `reason`, `dispositions` | POST /goals/:id/archive — retire a goal (open\|achieved → archived). |
 | PATCH | `/api/bongos/goals/:id/category` | `any-builder` | — | PATCH /goals/:id/category — body { category_id } (null clears it). |
 | GET | `/api/bongos/goals/:id/conflicts` | `any-builder` | — | GET /goals/:id/conflicts — the server-side task-conflict view (task 1736). |
 | POST | `/api/bongos/goals/:id/conflicts/resolve` | `any-builder` | `action`, `note`, `touches`, `first_task_id`, `then_task_id`, `task_id` | POST /goals/:id/conflicts/resolve — the owner/manager resolution actions for a detected conflict (task 1736; authority model ADR 0106): s… |

package/docs/module-api-changelog.md

@@ -1627,5 +1627,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.587 with no explicit bump. run 34178696372. (task 1002620)
   1.19.589 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.588 with no explicit bump. run 34179479729. (task 1002620)
+  1.19.590 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.589 with no explicit bump. run 34180363432. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/lifecycle/db-goals.js

@@ -14,7 +14,7 @@ const api = require('../../src/module-api');
 const { pool } = api;
 const doneWhen = require('./done-when.js');
 const { deriveRequiredRank, highestRank } = require('./db-rank-authz.js');
-const { nonTerminalSql } = require('./task-status');
+const { nonTerminalSql, isTerminalStatus } = require('./task-status');
 const { maintenanceGoalTitle } = require('./goal-advisory.js');
 const { SMOKE_NOT_LIKE } = require('./db-shared.js');
 
@@ -487,6 +487,130 @@ async function openTasksInGoal(goalId, { cap = 50 } = {}, deps = {}) {
   );
   return { total: rows[0]?.total ?? 0, tasks: rows.map(({ total, ...t }) => t) };
 }
+// archiveGoalWithDispositions — apply the caller's decision about each unfinished
+// task, then archive the goal, in ONE transaction (BV1.R14, task 1003601, goal
+// 1000086, ADR 0250 D3). The write half of the archive two-step whose refusal
+// R10 (task 1003597) built and whose plan `planGoalArchiveDispositions` validates.
+//
+// ATOMIC IS THE WHOLE POINT, not a nicety. The failure this replaces is a goal
+// reported closed while its work is still open; a partially-applied disposition
+// produces the mirror of it — some tasks abandoned, some moved, the goal still
+// open — and leaves the caller unable to tell from outside which half ran. One
+// transaction means the call is safe to retry verbatim after any error.
+//
+// The goal row is locked FOR UPDATE first, so a concurrent create-task-in-goal
+// cannot slip a new task in between the plan being validated and the archive
+// landing. The final re-count inside the same transaction is the belt to that
+// braces: it asserts the invariant the whole goal exists to protect (an archived
+// goal holds no non-terminal work) against the committed state rather than
+// against the plan, and rolls back if it does not hold. Cheap, and it is the one
+// check that cannot be fooled by a bug in the planner.
+//
+// `plan` is the validated output of planGoalArchiveDispositions: [{ taskId, verb,
+// toGoalId }]. Move targets are resolved and checked open BY THE ROUTE via
+// goalNotOpenRefusal — the ONE definition of "this goal takes no new work"
+// (BV1.R05) — and are re-read here under lock only to guard the interval between
+// that check and this write.
+//
+// ABANDON MIRRORS abandonTask (db-ship.js) rather than calling it: that function
+// opens its own connection and commits, which cannot join this transaction. The
+// two behaviours kept identical on purpose are the `value_summary` stamp
+// (`Abandoned: <reason>`) and the refusal on an active claim — a task someone is
+// actively working must not be abandoned out from under them by a goal archive.
+async function archiveGoalWithDispositions({ goalId, 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: goalRows } = await client.query(
+      `SELECT ${GOAL_COLS} FROM goals WHERE id = $1 FOR UPDATE`, [goalId]
+    );
+    if (!goalRows[0]) throw Object.assign(new Error('goal not found'), { code: 'GOAL_NOT_FOUND' });
+    if (goalRows[0].status === 'archived') {
+      await client.query('ROLLBACK');
+      return { goal: goalRows[0], applied: [], alreadyArchived: true };
+    }
+
+    const applied = [];
+    for (const step of plan) {
+      const { rows: tRows } = await client.query(
+        `SELECT id, title, status FROM tasks WHERE id = $1 AND goal_id = $2 FOR UPDATE`,
+        [step.taskId, goalId]
+      );
+      // The task left this goal (or shipped) while the caller was deciding. Not an
+      // error: the disposition is moot, and the final re-count is what actually
+      // guards the invariant. Recorded as 'skipped' so the response tells the
+      // truth about what this call did rather than claiming a write it never made.
+      if (!tRows[0]) { applied.push({ task_id: String(step.taskId), verb: step.verb, result: 'skipped_not_in_goal' }); continue; }
+      if (isTerminalStatus(tRows[0].status)) {
+        applied.push({ task_id: String(step.taskId), verb: step.verb, result: 'skipped_already_terminal', status: tRows[0].status });
+        continue;
+      }
+
+      const { rows: claimed } = await client.query(
+        `SELECT id FROM claims WHERE task_id = $1 AND released_at IS NULL LIMIT 1`, [step.taskId]
+      );
+      if (claimed[0]) {
+        throw Object.assign(new Error('task has an active claim'), {
+          code: 'TASK_HAS_ACTIVE_CLAIM', taskId: String(step.taskId), taskTitle: tRows[0].title,
+        });
+      }
+
+      if (step.verb === 'abandon') {
+        await client.query(
+          `UPDATE tasks SET status = 'abandoned',
+                            value_summary = COALESCE(NULLIF($2, ''), value_summary),
+                            updated_at = now()
+            WHERE id = $1`,
+          [step.taskId, `Abandoned: ${reason}`]
+        );
+        applied.push({ task_id: String(step.taskId), verb: 'abandon', result: 'abandoned' });
+      } else {
+        const { rows: dest } = await client.query(
+          `SELECT id, status FROM goals WHERE id = $1 FOR SHARE`, [step.toGoalId]
+        );
+        if (!dest[0]) {
+          throw Object.assign(new Error('move target not found'), { code: 'MOVE_TARGET_NOT_FOUND', toGoalId: String(step.toGoalId) });
+        }
+        if (dest[0].status !== 'open') {
+          throw Object.assign(new Error('move target is not open'), {
+            code: 'MOVE_TARGET_NOT_OPEN', toGoalId: String(step.toGoalId), targetStatus: dest[0].status,
+          });
+        }
+        await client.query(`UPDATE tasks SET goal_id = $2, updated_at = now() WHERE id = $1`, [step.taskId, step.toGoalId]);
+        applied.push({ task_id: String(step.taskId), verb: 'move', result: 'moved', to_goal_id: String(step.toGoalId) });
+      }
+    }
+
+    // The invariant, asserted against committed-in-this-txn state rather than
+    // against the plan. If anything is still non-terminal here, the archive would
+    // recreate exactly the condition goal 1000086 exists to make impossible.
+    const { rows: left } = await client.query(
+      `SELECT count(*)::int AS n FROM tasks t
+        WHERE t.goal_id = $1 AND ${nonTerminalSql()} AND ${SMOKE_NOT_LIKE.replace(/title/, 't.title')}`,
+      [goalId]
+    );
+    if ((left[0]?.n ?? 0) > 0) {
+      throw Object.assign(new Error('goal still holds unfinished tasks after dispositions'), {
+        code: 'DISPOSITION_INCOMPLETE_AFTER_APPLY', remaining: left[0].n,
+      });
+    }
+
+    const { rows: archived } = await client.query(
+      `UPDATE goals SET status = 'archived', updated_at = now() WHERE id = $1 RETURNING ${GOAL_COLS}`,
+      [goalId]
+    );
+    await client.query('COMMIT');
+    return { goal: archived[0], applied, alreadyArchived: false };
+  } catch (err) {
+    try { await client.query('ROLLBACK'); } catch { /* the original error is the one that matters */ }
+    throw err;
+  } finally {
+    client.release();
+  }
+}
+
 async function listCriteriaForGoal(goalId, deps = {}) {
   const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
   // task 1002164: carry the linked-task counts so the caller can derive the
@@ -937,6 +1061,7 @@ module.exports = {
   acceptMembershipRequestAndAddMember,
   ensureMaintenanceGoal,
   achieveGoalIfComplete,
+  archiveGoalWithDispositions,
   addGoalMember,
   addGoalScopeModules,
   createGoal,

package/modules/lifecycle/db.js

@@ -81,6 +81,7 @@ const {
   isGoalMember,
   listActiveClaimsForTasks,
   listCriteriaForGoal,
+  archiveGoalWithDispositions,
   openTasksInGoal,
   listGoalMembers,
   listGoals,
@@ -252,6 +253,7 @@ module.exports = {
   listInboxFor,
   listPendingRequestsForGoal,
   listCriteriaForGoal,
+  archiveGoalWithDispositions,
   openTasksInGoal,
   createTask,
   generalGoalIdForVersion,

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

@@ -519,7 +519,140 @@ function decorateGoalScope(goal) {
 }
 
 
+// planGoalArchiveDispositions — the PURE decision behind the second half of the
+// archive two-step (BV1.R14, task 1003601, goal 1000086, ADR 0250 D3).
+//
+// R10 (task 1003597) made `POST /goals/:id/archive` REFUSE a goal that still
+// holds unfinished tasks and hand the caller the list. This is the other half:
+// the caller comes back saying what happens to each, and this decides whether
+// what they said is a complete, well-formed answer.
+//
+// THE CONSTRAINT IS "NOTHING IS DISCARDED WITHOUT A DECISION", so the map must be
+// TOTAL. A partial map is refused rather than applied-as-far-as-it-goes, because
+// a half-applied disposition leaves the goal un-archivable AND some of its work
+// already abandoned — the caller then cannot tell, from the outside, which half
+// happened. Total-or-nothing is what makes the call safe to retry.
+//
+// PURE + exported for the reason its siblings are: a decision expressed as a pure
+// function has its whole truth table exercised by a DB-free unit test, including
+// the shapes a live-Postgres test would never bother to set up (a verb of the
+// wrong case, a move naming the goal being archived, a map with an extra id for a
+// task that already shipped while the caller was deciding).
+//
+// Inputs: `openTasks` is R10's own `openTasksInGoal(...).tasks` — [{ id, title,
+// status }] — and `dispositions` is the caller's map, keyed by task id. `goalId`
+// is the goal being archived, `reason` the archive's reason.
+//
+// Returns { ok: true, plan: [{ taskId, verb, toGoalId }] } — the plan ORDERED to
+// match `openTasks`, so the writer's audit trail reads in a stable order — or
+// { ok: false, status, body } (the exact HTTP status + JSON the route sends).
+//
+// It deliberately does NOT check that a `move` target exists or is open: that is
+// a database fact, and this function has no database. The route resolves the
+// named goals and applies `goalNotOpenRefusal` to each, which is the ONE
+// definition of "this goal takes no new work" (BV1.R05) and must not be
+// re-implemented here in a second, drifting form.
+const ARCHIVE_DISPOSITION_VERBS = new Set(['abandon', 'move']);
+
+function planGoalArchiveDispositions({ goalId, openTasks = [], dispositions = null, reason = '' }) {
+  const held = Array.isArray(openTasks) ? openTasks.filter(Boolean) : [];
+  if (held.length === 0) return { ok: true, plan: [] };
+
+  // A goal holding open work may not be archived on a bare call. This is R10's
+  // refusal, reproduced here so the two steps cannot drift: same code, same
+  // shape, and it RETURNS the work rather than naming a count.
+  if (!dispositions || typeof dispositions !== 'object' || Array.isArray(dispositions)) {
+    return {
+      ok: false,
+      status: 409,
+      body: {
+        error: 'goal_holds_open_tasks',
+        message: `Goal #${goalId} still holds ${held.length} unfinished task(s). Re-submit with a \`dispositions\` map saying what happens to each — {"<task id>":{"verb":"abandon"}} or {"<task id>":{"verb":"move","goal_id":<id>}}.`,
+        details: { total: held.length, shown: held.length, tasks: held },
+      },
+    };
+  }
+
+  // An abandon stamps its reason onto the task, and an abandon with no reason is
+  // exactly the silent discard D3 exists to prevent — so the reason is required
+  // as soon as anything is being dispositioned, not merely encouraged.
+  if (typeof reason !== 'string' || reason.trim().length === 0) {
+    return {
+      ok: false,
+      status: 400,
+      body: {
+        error: 'archive_reason_required',
+        message: 'Archiving a goal that holds open work records why. Pass a non-empty `reason`; it is stamped onto every task abandoned by this call.',
+      },
+    };
+  }
+
+  const plan = [];
+  const missing = [];
+  for (const t of held) {
+    const key = String(t.id);
+    const d = dispositions[key];
+    if (!d || typeof d !== 'object') { missing.push(t); continue; }
+    const verb = typeof d.verb === 'string' ? d.verb : null;
+    if (!ARCHIVE_DISPOSITION_VERBS.has(verb)) {
+      return {
+        ok: false,
+        status: 400,
+        body: {
+          error: 'bad_disposition',
+          message: `Task #${key}: verb must be "abandon" or "move".`,
+          details: { task_id: key, verb: d.verb ?? null, valid: Array.from(ARCHIVE_DISPOSITION_VERBS) },
+        },
+      };
+    }
+    if (verb === 'abandon') { plan.push({ taskId: Number(t.id), verb, toGoalId: null }); continue; }
+
+    const toGoalId = Number(d.goal_id);
+    if (!Number.isInteger(toGoalId) || toGoalId <= 0) {
+      return {
+        ok: false,
+        status: 400,
+        body: {
+          error: 'bad_disposition',
+          message: `Task #${key}: a "move" names the surviving goal it moves to — pass \`goal_id\`.`,
+          details: { task_id: key, goal_id: d.goal_id ?? null },
+        },
+      };
+    }
+    // Moving a task INTO the goal being archived is the disposition that looks
+    // like a decision and is not: the task would be archived-with-the-goal a
+    // moment later, which is the silent discard by another name.
+    if (toGoalId === Number(goalId)) {
+      return {
+        ok: false,
+        status: 400,
+        body: {
+          error: 'bad_disposition',
+          message: `Task #${key}: cannot move a task into the goal being archived. Abandon it, or name a surviving goal.`,
+          details: { task_id: key, goal_id: toGoalId },
+        },
+      };
+    }
+    plan.push({ taskId: Number(t.id), verb, toGoalId });
+  }
+
+  if (missing.length > 0) {
+    return {
+      ok: false,
+      status: 400,
+      body: {
+        error: 'disposition_incomplete',
+        message: `${missing.length} of ${held.length} unfinished task(s) have no disposition. Every one needs a decision — nothing is discarded by omission.`,
+        details: { total: held.length, undecided: missing.length, tasks: missing },
+      },
+    };
+  }
+  return { ok: true, plan };
+}
+
+
 module.exports = {
+  ARCHIVE_DISPOSITION_VERBS,
   authorizeCreateJoinRequest,
   authorizeGoalCreate,
   authorizeGoalTaskCreate,
@@ -533,5 +666,6 @@ module.exports = {
   decorateGoalScope,
   goalNotOpenRefusal,
   isMemberOrArchon,
+  planGoalArchiveDispositions,
   protectedScopeAdmissionBlock,
 };

package/modules/lifecycle/routes/goals.js

@@ -49,6 +49,14 @@ const goalConflicts = require('../goal-conflicts');
 const { isGoalOwner, authorizeGoalManagement } = require('../goal-authz');
 
 const VALID_GOAL_STATUSES = ['open', 'achieved', 'archived'];
+
+// ARCHIVE_DISPOSITION_MAX — how many unfinished tasks one archive call will
+// disposition (BV1.R14). A ceiling rather than an unbounded read because the
+// whole plan is validated in memory and applied in ONE transaction, and a goal
+// holding thousands of open tasks is a data problem to fix before archiving, not
+// a payload to stream. Sized well above anything real: the largest bucket on the
+// live instance is a per-version catch-all at ~53 (ADR 0250 §7).
+const ARCHIVE_DISPOSITION_MAX = 500;
 const VALID_MEMBERSHIP_KINDS = ['lead', 'member'];
 const METIC_PLUS = ['metic', 'archon'];
 const RESOLVE_ACTIONS = ['sequence', 'flag_release', 'rescope'];
@@ -63,7 +71,7 @@ const JOIN_REQUEST_RESPONSE_ACTIONS = ['approve', 'deny']; // an owner/manager/A
 // proceed; a false result means "not a member" → the route should 403. This is the
 // membership half of the wall; the protected-module rank check is enforced per-route
 // (scope is never self-granted).
-const { authorizeCreateJoinRequest, authorizeGoalCreate, authorizeGoalTaskCreate, authorizeInvitationAccept, authorizeInvitationResponse, authorizeJoinRequestResponse, authorizeMembershipKindChange, authorizeOwnershipTransfer, authorizeRescindInvitation, authorizeWithdrawJoinRequest, decorateGoalScope, isMemberOrArchon, protectedScopeAdmissionBlock } = require('./goal-route-authz.js');
+const { authorizeCreateJoinRequest, authorizeGoalCreate, authorizeGoalTaskCreate, authorizeInvitationAccept, authorizeInvitationResponse, authorizeJoinRequestResponse, authorizeMembershipKindChange, authorizeOwnershipTransfer, authorizeRescindInvitation, authorizeWithdrawJoinRequest, decorateGoalScope, goalNotOpenRefusal, isMemberOrArchon, planGoalArchiveDispositions, protectedScopeAdmissionBlock } = require('./goal-route-authz.js');
 // task 1003208: structured logging (pino via the doorway) — was console.*.
 const log = api.logger('lifecycle');
 module.exports = function buildGoalsRouter() {
@@ -1075,6 +1083,17 @@ module.exports = function buildGoalsRouter() {
   // skill reaches for once a goal is achieved (ADR 0086 §6 / BV1.R64).
   // rank: metic+archon — a goal member (Metic+) or an Archon dispositions the goal.
   router.post('/goals/:id/archive', auth.requireBuilder, auth.requirePermission('goal.archive'), async (req, res) => {
+    // ADR 0118 / R12: every write route that reads a body declares it, so an
+    // unknown field is REJECTED rather than silently ignored — a typo'd
+    // `disposition` (singular) must not read as "no disposition given" and take
+    // the refusal branch, which is exactly the shape that trains a caller to
+    // believe the map was applied. `dispositions` is a dynamic-key map (task id →
+    // verb) so the schema bounds its TYPE here and its CONTENTS are validated by
+    // planGoalArchiveDispositions, which refuses every malformed entry by name.
+    if (validateOrRespond(req, res, {
+      reason: { type: 'string', maxLength: 2000 },
+      dispositions: { type: 'object' },
+    })) return;
     const id = parseId(req, res, { code: 'bad_goal_id' });
     if (id === null) return;
     try {
@@ -1100,17 +1119,96 @@ module.exports = function buildGoalsRouter() {
       // "not without saying what happens to these", not a silent discard.
       //
       // A goal holding nothing open stays a single call, unchanged.
-      const held = await db.openTasksInGoal(id);
-      if (held.total > 0) {
-        return res.fail('goal_holds_open_tasks', {
+      //
+      // BV1.R14 (task 1003601) is the second half: the caller comes back with a
+      // `dispositions` map saying what happens to each open task, and the archive
+      // APPLIES it. R10 shipped the refusal one task ahead of its own remedy, so
+      // between the two every archive of a goal holding work was impossible —
+      // which is also why the ADR 0264 goal cut could not start until this landed.
+      //
+      // The decision is the pure planGoalArchiveDispositions (the sibling of
+      // authorizeGoalCreate / authorizeVersionCreate): the route gathers the
+      // facts, that decides, the route renders the verdict verbatim.
+      //
+      // THE CAP MATTERS HERE AND NOT IN R10. `openTasksInGoal` defaults to 50 rows
+      // (with the true count in `.total`), which is right for a refusal that only
+      // has to show the caller what is in the way. This call must plan over EVERY
+      // open task — a plan built from a truncated list would validate as complete,
+      // and the transaction's final re-count would then roll the whole archive back
+      // with a confusing "still holds N" on a caller who dispositioned everything
+      // they were shown. So: read wide when a disposition is being applied, and
+      // refuse above the ceiling with a code that says what to do.
+      const wantsDisposition = req.body?.dispositions != null;
+      const held = await db.openTasksInGoal(id, wantsDisposition ? { cap: ARCHIVE_DISPOSITION_MAX } : undefined);
+      if (wantsDisposition && held.total > ARCHIVE_DISPOSITION_MAX) {
+        return res.fail('too_many_open_tasks', {
           status: 409,
-          message: `Goal #${id} still holds ${held.total} unfinished task(s). Ship or abandon them, or move them to another goal, before archiving it.`,
-          details: { total: held.total, shown: held.tasks.length, tasks: held.tasks },
+          message: `Goal #${id} holds ${held.total} unfinished tasks — more than the ${ARCHIVE_DISPOSITION_MAX} this call dispositions at once. Move or abandon some first, then archive.`,
+          details: { total: held.total, max: ARCHIVE_DISPOSITION_MAX },
         });
       }
-      const updated = await db.setGoalStatus({ goalId: id, status: 'archived' });
-      return res.json({ ok: true, goal: updated });
+      const reason = typeof req.body?.reason === 'string' ? req.body.reason.slice(0, 2000) : '';
+      const plan = planGoalArchiveDispositions({
+        goalId: id, openTasks: held.tasks, dispositions: req.body?.dispositions ?? null, reason,
+      });
+      if (!plan.ok) return res.status(plan.status).json(plan.body);
+
+      // A goal holding nothing open never had a plan to apply — keep it the one
+      // untouched call it has always been, rather than routing it through a
+      // transaction that would do nothing.
+      if (plan.plan.length === 0) {
+        const updated = await db.setGoalStatus({ goalId: id, status: 'archived' });
+        return res.json({ ok: true, goal: updated, applied: [] });
+      }
+
+      // Move targets are resolved HERE, before the write, so a bad target is a
+      // 400 about the caller's request rather than a rollback mid-archive. The
+      // open test is goalNotOpenRefusal — the ONE definition of "this goal takes
+      // no new work" (BV1.R05) — never a second spelling of the status list.
+      const targets = [...new Set(plan.plan.filter((p) => p.verb === 'move').map((p) => p.toGoalId))];
+      for (const t of targets) {
+        const dest = await db.getGoal(t);
+        if (!dest) {
+          return res.fail('bad_disposition', { status: 400, message: `Move target goal #${t} does not exist.`, details: { goal_id: String(t) } });
+        }
+        const notOpen = goalNotOpenRefusal(dest);
+        if (notOpen) {
+          return res.fail('bad_disposition', {
+            status: 409,
+            message: `Move target goal #${t} is '${dest.status}' — a task cannot be moved into a closed goal.`,
+            details: { goal_id: String(t), goal_status: dest.status },
+          });
+        }
+      }
+
+      const result = await db.archiveGoalWithDispositions({ goalId: id, plan: plan.plan, reason });
+      return res.json({ ok: true, goal: result.goal, applied: result.applied });
     } catch (err) {
+      // An actively-claimed task must not be abandoned out from under whoever is
+      // working it — the same refusal POST /tasks/:id/abandon makes, surfaced with
+      // the task named so the caller knows which claim to chase.
+      if (err && err.code === 'TASK_HAS_ACTIVE_CLAIM') {
+        return res.fail('task_has_active_claim', {
+          status: 409,
+          message: `Task #${err.taskId} has an active claim — release it before archiving this goal.`,
+          details: { task_id: err.taskId, task_title: err.taskTitle },
+        });
+      }
+      if (err && (err.code === 'MOVE_TARGET_NOT_FOUND' || err.code === 'MOVE_TARGET_NOT_OPEN')) {
+        return res.fail('bad_disposition', {
+          status: 409,
+          message: `Move target goal #${err.toGoalId} changed while the archive was running — nothing was applied. Re-read and retry.`,
+          details: { goal_id: err.toGoalId, goal_status: err.targetStatus ?? null },
+        });
+      }
+      if (err && err.code === 'DISPOSITION_INCOMPLETE_AFTER_APPLY') {
+        return res.fail('goal_holds_open_tasks', {
+          status: 409,
+          message: `Goal #${id} still held ${err.remaining} unfinished task(s) after the dispositions were applied — nothing was changed. Re-read the goal and retry.`,
+          details: { remaining: err.remaining },
+        });
+      }
+      if (err && err.code === 'GOAL_NOT_FOUND') return res.fail('goal_not_found', 404);
       log.error('[gds] POST /goals/:id/archive', err);
       return res.fail('archive_failed', { status: 500, message: 'internal error' });
     }

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.589",
+  "version": "1.19.590",
   "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/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.589'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.590'; // 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/goal_archive_disposition.mjs

@@ -24,6 +24,8 @@ process.env.NODE_ENV = 'test';
 const require = createRequire(import.meta.url);
 const { openTasksInGoal } = require('../modules/lifecycle/db.js');
 const { TERMINAL_STATUSES } = require('../modules/lifecycle/task-status.js');
+const { planGoalArchiveDispositions } = require('../modules/lifecycle/routes/goal-route-authz.js');
+const { archiveGoalWithDispositions } = require('../modules/lifecycle/db.js');
 
 const src = (rel) => readFileSync(new URL('../' + rel, import.meta.url), 'utf8');
 
@@ -86,15 +88,24 @@ test('an empty goal reports nothing held — the single-call path stays open', a
 // ---- the route --------------------------------------------------------------
 
 test('archive refuses with a NAMED 409 when the goal holds open work', () => {
-  assert.match(ARCHIVE, /const held = await db\.openTasksInGoal\(id\);/,
+  // R14 (task 1003601) moved this refusal OUT of the route and into the pure
+  // planner, so it is asserted on behaviour now rather than on route source —
+  // a strictly better pin, and the reason these two tests changed shape.
+  assert.match(ARCHIVE, /const held = await db\.openTasksInGoal\(id/,
     'the archive route must consult the work before discarding it');
-  assert.match(ARCHIVE, /res\.fail\('goal_holds_open_tasks', \{[\s\S]*?status: 409/,
-    'a named code an agent can branch on, not a bare 409');
+  const r = planGoalArchiveDispositions({
+    goalId: 7, openTasks: [{ id: '1', title: 't', status: 'ready' }], dispositions: null, reason: 'x',
+  });
+  assert.equal(r.ok, false);
+  assert.equal(r.status, 409);
+  assert.equal(r.body.error, 'goal_holds_open_tasks', 'a named code an agent can branch on, not a bare 409');
 });
 
 test('the refusal RETURNS the tasks, so the caller can decide without a second fetch', () => {
-  assert.match(ARCHIVE, /details: \{ total: held\.total, shown: held\.tasks\.length, tasks: held\.tasks \}/,
-    'an agent that has to go fetch the list will guess instead');
+  const held = [{ id: '1', title: 'one', status: 'ready' }, { id: '2', title: 'two', status: 'active' }];
+  const r = planGoalArchiveDispositions({ goalId: 7, openTasks: held, dispositions: null, reason: 'x' });
+  assert.deepEqual(r.body.details.tasks, held, 'an agent that has to go fetch the list will guess instead');
+  assert.equal(r.body.details.total, 2);
 });
 
 test('the check runs AFTER identity/authorization and BEFORE the status write', () => {
@@ -111,9 +122,14 @@ test('the check runs AFTER identity/authorization and BEFORE the status write',
 test('archiving a goal that holds nothing is still ONE call', () => {
   // The guard must not turn the ordinary case into a two-step. There is exactly
   // one setGoalStatus in this handler and no second round trip in front of it.
-  assert.equal((ARCHIVE.match(/db\.setGoalStatus/g) || []).length, 1);
+  assert.equal((ARCHIVE.match(/db\.setGoalStatus/g) || []).length, 1,
+    'the empty-goal path still writes through the plain setter, not the transaction');
   assert.equal(/disposition_required|preview=/.test(ARCHIVE), false,
     'no extra confirm parameter on the empty-goal path');
+  // And the planner agrees: nothing held means an empty plan, never a refusal.
+  const r = planGoalArchiveDispositions({ goalId: 7, openTasks: [], dispositions: null, reason: '' });
+  assert.equal(r.ok, true);
+  assert.deepEqual(r.plan, []);
 });
 
 // ---- the two doors agree ----------------------------------------------------
@@ -142,3 +158,188 @@ test('every non-terminal status is one the archive gate would catch', () => {
   assert.deepEqual([...TERMINAL_STATUSES].sort(), ['abandoned', 'shipped'],
     'and the terminal set is exactly the two deliberate endings');
 });
+
+// ---- R14: the disposition is APPLIED (task 1003601) --------------------------
+//
+// The second half of the two-step. R10 built the refusal; this is the answer to
+// it. The property under test throughout is TOTALITY: a map that does not cover
+// every open task is refused outright rather than applied as far as it goes,
+// because a half-applied disposition leaves the goal un-archivable AND some of
+// its work already abandoned, with no way for the caller to tell which happened.
+
+const TASKS = (...st) => st.map((s, i) => ({ id: String(i + 1), title: `t${i + 1}`, status: s }));
+const plan = (over = {}) => planGoalArchiveDispositions({
+  goalId: 7, openTasks: TASKS('ready', 'active'), reason: 'cut in the ten-areas review', ...over,
+});
+
+test('a partial map is refused — nothing is discarded by omission', () => {
+  const r = plan({ dispositions: { 1: { verb: 'abandon' } } });   // task 2 undecided
+  assert.equal(r.ok, false);
+  assert.equal(r.status, 400);
+  assert.equal(r.body.error, 'disposition_incomplete');
+  assert.equal(r.body.details.undecided, 1);
+  assert.deepEqual(r.body.details.tasks.map((t) => t.id), ['2'],
+    'the refusal names WHICH task is undecided, not merely how many');
+});
+
+test('a complete map plans one step per task, in the order the tasks came in', () => {
+  const r = plan({ dispositions: { 1: { verb: 'abandon' }, 2: { verb: 'move', goal_id: 42 } } });
+  assert.equal(r.ok, true);
+  assert.deepEqual(r.plan, [
+    { taskId: 1, verb: 'abandon', toGoalId: null },
+    { taskId: 2, verb: 'move', toGoalId: 42 },
+  ]);
+});
+
+test('an abandon with no reason is refused — that is the silent discard D3 forbids', () => {
+  for (const reason of ['', '   ', null, undefined]) {
+    const r = plan({ dispositions: { 1: { verb: 'abandon' }, 2: { verb: 'abandon' } }, reason });
+    assert.equal(r.ok, false, `reason ${JSON.stringify(reason)} must not pass`);
+    assert.equal(r.body.error, 'archive_reason_required');
+  }
+});
+
+test('only abandon and move are verbs; anything else is a named 400', () => {
+  for (const verb of ['delete', 'ABANDON', 'skip', '', null, 42]) {
+    const r = plan({ dispositions: { 1: { verb }, 2: { verb: 'abandon' } } });
+    assert.equal(r.ok, false, `verb ${JSON.stringify(verb)} must not pass`);
+    assert.equal(r.body.error, 'bad_disposition');
+  }
+});
+
+test('a move must name where it moves to', () => {
+  for (const goal_id of [undefined, null, 0, -1, 'forty-two', 1.5]) {
+    const r = plan({ dispositions: { 1: { verb: 'move', goal_id }, 2: { verb: 'abandon' } } });
+    assert.equal(r.ok, false, `goal_id ${JSON.stringify(goal_id)} must not pass`);
+    assert.equal(r.body.error, 'bad_disposition');
+  }
+});
+
+test('a task cannot be moved INTO the goal being archived', () => {
+  // The disposition that looks like a decision and is not: the task would be
+  // archived along with the goal a moment later — the silent discard renamed.
+  const r = plan({ dispositions: { 1: { verb: 'move', goal_id: 7 }, 2: { verb: 'abandon' } } });
+  assert.equal(r.ok, false);
+  assert.equal(r.body.error, 'bad_disposition');
+  assert.match(r.body.message, /into the goal being archived/);
+});
+
+test('a disposition for a task that is not open is simply unused, never an error', () => {
+  // The caller may hold a stale list; extra keys are harmless because the plan is
+  // built from the OPEN TASKS, not from the map.
+  const r = plan({ dispositions: { 1: { verb: 'abandon' }, 2: { verb: 'abandon' }, 999: { verb: 'move' } } });
+  assert.equal(r.ok, true);
+  assert.deepEqual(r.plan.map((p) => p.taskId), [1, 2]);
+});
+
+// ---- R14: the write is one transaction --------------------------------------
+
+function txPool(handler) {
+  const c = makeSqlAwareClient(handler);
+  return { connect: c.connect, query: (sql, params) => c._client.query(sql, params), queries: c._client.queries };
+}
+const flat = (q) => String(q.sql).replace(/\s+/g, ' ').trim();
+
+test('the whole disposition + archive runs inside ONE transaction', async () => {
+  const pool = txPool((sql) => {
+    const q = String(sql).replace(/\s+/g, ' ');
+    if (/^SELECT .* FROM goals WHERE id = \$1 FOR UPDATE/.test(q.trim())) return { rows: [{ id: 7, status: 'open' }] };
+    if (/FROM tasks WHERE id = \$1 AND goal_id = \$2 FOR UPDATE/.test(q)) return { rows: [{ id: 1, title: 't1', status: 'ready' }] };
+    if (/FROM claims WHERE task_id/.test(q)) return { rows: [] };
+    if (/count\(\*\)::int AS n FROM tasks/.test(q)) return { rows: [{ n: 0 }] };
+    if (/UPDATE goals SET status = 'archived'/.test(q)) return { rows: [{ id: 7, status: 'archived' }] };
+    return { rows: [] };
+  });
+  const out = await archiveGoalWithDispositions(
+    { goalId: 7, plan: [{ taskId: 1, verb: 'abandon', toGoalId: null }], reason: 'cut' },
+    { pool }
+  );
+  assert.equal(out.goal.status, 'archived');
+  const sqls = pool.queries.map(flat);
+  assert.equal(sqls.filter((q) => q === 'BEGIN').length, 1, 'exactly one BEGIN');
+  assert.equal(sqls.filter((q) => q === 'COMMIT').length, 1, 'exactly one COMMIT');
+  assert.ok(sqls.indexOf('BEGIN') < sqls.findIndex((q) => /UPDATE tasks SET status = 'abandoned'/.test(q)),
+    'the task writes are inside the transaction');
+  assert.ok(sqls.findIndex((q) => /UPDATE goals SET status = 'archived'/.test(q)) < sqls.indexOf('COMMIT'),
+    'so is the archive');
+});
+
+test('the goal row is locked BEFORE the plan is applied', async () => {
+  // Without FOR UPDATE on the goal, a concurrent POST /goals/:id/tasks can slip a
+  // new task in between the plan validating and the archive landing.
+  const pool = txPool((sql) => {
+    const q = String(sql).replace(/\s+/g, ' ');
+    if (/FROM goals WHERE id = \$1 FOR UPDATE/.test(q)) return { rows: [{ id: 7, status: 'open' }] };
+    if (/FROM tasks WHERE id = \$1 AND goal_id = \$2 FOR UPDATE/.test(q)) return { rows: [{ id: 1, title: 't', status: 'ready' }] };
+    if (/FROM claims/.test(q)) return { rows: [] };
+    if (/count\(\*\)::int AS n/.test(q)) return { rows: [{ n: 0 }] };
+    if (/UPDATE goals/.test(q)) return { rows: [{ id: 7, status: 'archived' }] };
+    return { rows: [] };
+  });
+  await archiveGoalWithDispositions({ goalId: 7, plan: [{ taskId: 1, verb: 'abandon', toGoalId: null }], reason: 'r' }, { pool });
+  const sqls = pool.queries.map(flat);
+  const lock = sqls.findIndex((q) => /FROM goals WHERE id = \$1 FOR UPDATE/.test(q));
+  const firstWrite = sqls.findIndex((q) => /^UPDATE tasks/.test(q));
+  assert.ok(lock !== -1 && firstWrite !== -1 && lock < firstWrite, 'lock the goal, then apply');
+});
+
+test('an actively-claimed task stops the archive and rolls it back', async () => {
+  const pool = txPool((sql) => {
+    const q = String(sql).replace(/\s+/g, ' ');
+    if (/FROM goals WHERE id = \$1 FOR UPDATE/.test(q)) return { rows: [{ id: 7, status: 'open' }] };
+    if (/FROM tasks WHERE id = \$1 AND goal_id = \$2 FOR UPDATE/.test(q)) return { rows: [{ id: 1, title: 'busy', status: 'active' }] };
+    if (/FROM claims WHERE task_id/.test(q)) return { rows: [{ id: 99 }] };   // someone is on it
+    return { rows: [] };
+  });
+  await assert.rejects(
+    archiveGoalWithDispositions({ goalId: 7, plan: [{ taskId: 1, verb: 'abandon', toGoalId: null }], reason: 'r' }, { pool }),
+    (e) => e.code === 'TASK_HAS_ACTIVE_CLAIM'
+  );
+  const sqls = pool.queries.map(flat);
+  assert.ok(sqls.includes('ROLLBACK'), 'nothing is left applied');
+  assert.equal(sqls.some((q) => /UPDATE goals SET status = 'archived'/.test(q)), false, 'and the goal is not archived');
+});
+
+test('the invariant is re-checked against committed state, not against the plan', async () => {
+  // The one check a bug in the planner cannot fool: if anything is still
+  // non-terminal after the writes, the archive rolls back rather than recreating
+  // exactly the condition goal 1000086 exists to make impossible.
+  const pool = txPool((sql) => {
+    const q = String(sql).replace(/\s+/g, ' ');
+    if (/FROM goals WHERE id = \$1 FOR UPDATE/.test(q)) return { rows: [{ id: 7, status: 'open' }] };
+    if (/FROM tasks WHERE id = \$1 AND goal_id = \$2 FOR UPDATE/.test(q)) return { rows: [{ id: 1, title: 't', status: 'ready' }] };
+    if (/FROM claims/.test(q)) return { rows: [] };
+    if (/count\(\*\)::int AS n FROM tasks/.test(q)) return { rows: [{ n: 3 }] };   // three snuck in
+    return { rows: [] };
+  });
+  await assert.rejects(
+    archiveGoalWithDispositions({ goalId: 7, plan: [{ taskId: 1, verb: 'abandon', toGoalId: null }], reason: 'r' }, { pool }),
+    (e) => e.code === 'DISPOSITION_INCOMPLETE_AFTER_APPLY' && e.remaining === 3
+  );
+  assert.ok(pool.queries.map(flat).includes('ROLLBACK'));
+});
+
+test('the re-check asks the SAME question the refusal asked', () => {
+  // Same terminal set, same smoke exclusion — or the transaction rolls back work
+  // the gate in front of it had already accepted.
+  const dbGoals = src('modules/lifecycle/db-goals.js');
+  const body = dbGoals.slice(dbGoals.indexOf('async function archiveGoalWithDispositions'));
+  assert.match(body, /\$\{nonTerminalSql\(\)\}/);
+  assert.match(body, /SMOKE_NOT_LIKE\.replace/);
+});
+
+test('an abandon stamps the archive reason, the way POST /tasks/:id/abandon does', () => {
+  const dbGoals = src('modules/lifecycle/db-goals.js');
+  const body = dbGoals.slice(dbGoals.indexOf('async function archiveGoalWithDispositions'));
+  assert.match(body, /`Abandoned: \$\{reason\}`/,
+    'the same stamp abandonTask writes, so the ledger reads identically whichever door was used');
+});
+
+test('a move into a closed goal is refused, via the ONE definition of "not open"', () => {
+  // The route resolves move targets and applies goalNotOpenRefusal (BV1.R05)
+  // rather than re-typing the status list — two spellings of "open" is how the
+  // three task-create vectors drifted apart in the first place.
+  assert.match(ARCHIVE, /goalNotOpenRefusal\(dest\)/);
+  assert.equal(/dest\.status === 'open'|dest\.status !== 'open'/.test(ARCHIVE), false,
+    'the route must not re-implement the open test');
+});

package/tests/goal_archive_route_e2e.mjs

@@ -0,0 +1,135 @@
+// tests/goal_archive_route_e2e.mjs — the archive two-step over real HTTP
+// (BV1.R14, task 1003601, goal 1000086, ADR 0250 D3).
+//
+// WHY A SECOND FILE. goal_archive_disposition.mjs pins the two halves in
+// isolation — the pure planner's truth table, and the writer's transaction shape
+// against a fake pool. Neither exercises the WIRING: that the route reads the
+// body it declares, calls the planner with the right arguments, renders its
+// verdict verbatim, resolves move targets BEFORE writing, and hands the writer a
+// plan. Every one of those is a place a correct planner and a correct writer can
+// still add up to a broken endpoint, and each was a real risk on this change
+// (the route previously read no body at all).
+//
+// So this drives the REAL router over a real socket, with the db layer stubbed at
+// the module boundary the way task_visual_route_gate.mjs does — the router under
+// test is the shipped one, not a re-assembly of it.
+//
+// THE CASE WORTH THE FILE ON ITS OWN is #6: a typo'd `disposition` (singular).
+// Without the ADR 0118 schema the handler reads `req.body.dispositions` as
+// undefined and takes the REFUSAL branch — so a caller who wrote a complete map
+// under a misspelled key is told the goal holds open work, which is true,
+// unhelpful, and indistinguishable from having sent nothing. That is the failure
+// shape that teaches an agent to retry with a different map instead of fixing the
+// key.
+//
+// Run:  node tests/goal_archive_route_e2e.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+process.env.NODE_ENV = 'test';
+
+const express = require('express');
+const api = require('../src/module-api.js');
+const db = require('../modules/lifecycle/db.js');
+
+api.requireBuilder = (req, _res, next) => { req.builder = { id: '3', rank: 'archon' }; next(); };
+api.requirePermission = () => (req, _res, next) => next();
+
+let GOALS = {
+  7:  { id: 7, status: 'open', title: 'cut me', version_id: 'BONGOS-V1' },
+  42: { id: 42, status: 'open', title: 'survivor', version_id: 'BONGOS-V1' },
+  99: { id: 99, status: 'archived', title: 'closed', version_id: 'BONGOS-V1' },
+};
+let OPEN = [{ id: '1', title: 'one', status: 'ready' }, { id: '2', title: 'two', status: 'active' }];
+let applied = null;
+db.getGoal = async (id) => GOALS[Number(id)] ?? null;
+db.isGoalMember = async () => true;
+db.openTasksInGoal = async () => ({ total: OPEN.length, tasks: OPEN });
+db.setGoalStatus = async ({ goalId }) => ({ ...GOALS[goalId], status: 'archived' });
+db.archiveGoalWithDispositions = async ({ goalId, plan, reason }) => {
+  applied = { goalId, plan, reason };
+  return { goal: { ...GOALS[goalId], status: 'archived' }, applied: plan.map(p => ({ task_id: String(p.taskId), verb: p.verb, result: p.verb === 'abandon' ? 'abandoned' : 'moved' })) };
+};
+
+const app = express();
+app.use(express.json());
+app.use((req, res, next) => {
+  res.fail = (code, statusOrOpts, details) => {
+    const o = typeof statusOrOpts === 'number' ? { status: statusOrOpts } : (statusOrOpts || {});
+    return res.status(o.status || 400).json({ error: code, message: o.message, details: o.details ?? details });
+  };
+  next();
+});
+app.use('/api/gds', require('../modules/lifecycle/routes/goals.js')());
+const server = app.listen(0);
+await new Promise(r => server.once('listening', r));
+const base = `http://127.0.0.1:${server.address().port}/api/gds`;
+const post = async (p, body) => {
+  const r = await fetch(base + p, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body ?? {}) });
+  return { status: r.status, body: await r.json().catch(() => null) };
+};
+
+let n = 0; const ok = (m) => { n++; console.log('  ✓', m); };
+
+// 1. bare archive of a goal holding work → the R10 refusal, WITH the tasks
+let r = await post('/goals/7/archive');
+assert.equal(r.status, 409); assert.equal(r.body.error, 'goal_holds_open_tasks');
+assert.equal(r.body.details.tasks.length, 2);
+ok('bare archive refuses 409 goal_holds_open_tasks and returns both tasks');
+
+// 2. a partial map → refused, names the undecided task
+r = await post('/goals/7/archive', { reason: 'cut', dispositions: { 1: { verb: 'abandon' } } });
+assert.equal(r.status, 400); assert.equal(r.body.error, 'disposition_incomplete');
+assert.deepEqual(r.body.details.tasks.map(t => t.id), ['2']);
+ok('partial map refuses 400 disposition_incomplete, naming task 2');
+
+// 3. complete map with no reason → refused
+r = await post('/goals/7/archive', { dispositions: { 1: { verb: 'abandon' }, 2: { verb: 'abandon' } } });
+assert.equal(r.status, 400); assert.equal(r.body.error, 'archive_reason_required');
+ok('an abandon with no reason refuses 400 archive_reason_required');
+
+// 4. move into a CLOSED goal → refused before any write
+applied = null;
+r = await post('/goals/7/archive', { reason: 'cut', dispositions: { 1: { verb: 'move', goal_id: 99 }, 2: { verb: 'abandon' } } });
+assert.equal(r.status, 409); assert.equal(r.body.error, 'bad_disposition');
+assert.equal(applied, null, 'nothing was written');
+ok('move into an archived goal refuses 409 bad_disposition, writing nothing');
+
+// 5. move into the goal being archived → refused
+r = await post('/goals/7/archive', { reason: 'cut', dispositions: { 1: { verb: 'move', goal_id: 7 }, 2: { verb: 'abandon' } } });
+assert.equal(r.status, 400); assert.equal(r.body.error, 'bad_disposition');
+ok('move into the goal being archived refuses 400 bad_disposition');
+
+// 6. unknown body field → rejected by the ADR 0118 schema
+r = await post('/goals/7/archive', { reason: 'cut', disposition: { 1: { verb: 'abandon' } } });
+assert.equal(r.status, 400);
+assert.equal(r.body.error?.code ?? r.body.error, 'validation_failed');
+ok('a typo\'d `disposition` (singular) is rejected as validation_failed, not read as "none given"');
+
+// 7. THE HAPPY PATH — complete map, one abandon + one move
+applied = null;
+r = await post('/goals/7/archive', { reason: 'cut in the ten-areas review', dispositions: { 1: { verb: 'abandon' }, 2: { verb: 'move', goal_id: 42 } } });
+assert.equal(r.status, 200, JSON.stringify(r.body));
+assert.equal(r.body.goal.status, 'archived');
+assert.deepEqual(r.body.applied, [
+  { task_id: '1', verb: 'abandon', result: 'abandoned' },
+  { task_id: '2', verb: 'move', result: 'moved' },
+]);
+assert.deepEqual(applied.plan, [
+  { taskId: 1, verb: 'abandon', toGoalId: null },
+  { taskId: 2, verb: 'move', toGoalId: 42 },
+]);
+assert.equal(applied.reason, 'cut in the ten-areas review');
+ok('a complete map archives the goal and reports what happened to each task');
+
+// 8. a goal holding nothing is still ONE call, no reason needed
+OPEN = [];
+r = await post('/goals/7/archive');
+assert.equal(r.status, 200); assert.equal(r.body.goal.status, 'archived');
+assert.deepEqual(r.body.applied, []);
+ok('a goal holding nothing archives in one call with no reason');
+
+assert.equal(n, 8, 'every check must run — an early return would pass silently');
+console.log(`\n${n}/8 end-to-end checks passed against the real router.`);
+server.close();