@bongos/core 1.19.589 → 1.19.591

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.591",
+  "core_contract": "1.19.591",
+  "source_commit": "1a5d5f0eb546f0430b57a3ca5446be6ebd135fe9",
   "source_ref": "HEAD",
-  "built_at": "2026-09-08T02:16:53.692Z",
+  "built_at": "2026-09-08T02:46:21.428Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 457,
     "agent_docs_stubbed": 24,
-    "functional_verbatim": 2060,
+    "functional_verbatim": 2063,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2541,
-  "tree_sha256": "d96aab84f10a639efe4d035824854aed5cb9bf2fcc7723f62a69f4b1a8074591",
+  "file_count": 2544,
+  "tree_sha256": "8c944ccd379b18b96ad8d347ecc09ae1d5a3d163d40ca3c446e9bce07f86a002",
   "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": "32f8765fbbc0999a25b5abfc0f58a5dc5980db09c03ff4ee127b6774387c865a"
     },
     {
       "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": "b89e31e9693695643d5effcfe1386164ec4b8759e50fec6d86fe4edf19f09cb6"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "fc682e53b7902f41fb4a455c9f61d70a5b154159df150b6e7e6c696c596df4e4"
+      "sha256": "09428614577361d939096da4a4a91a0f742a0504d97168cdea6d169ccb8931be"
     },
     {
       "path": "public-docs/index.html",
@@ -8087,7 +8087,7 @@
     {
       "path": "scripts/gds/gds-literal-scan.js",
       "mode": "0000644",
-      "sha256": "fe622c9abf848a668fe2672d699fef22141156f41bb2396523461d1484341ec1"
+      "sha256": "3f873da74a012f73e30e659f070b3476eda81ac55f802913307494a645d8ee88"
     },
     {
       "path": "scripts/gds/gen-api-client.js",
@@ -8454,6 +8454,11 @@
       "mode": "0000644",
       "sha256": "4cbb7baf533e1aa2eced1c828f37bbd11f7183846a0f3862f9fb72b3f504be66"
     },
+    {
+      "path": "scripts/gds/rename-history-check.js",
+      "mode": "0000644",
+      "sha256": "06ad6a69304cfc66509f4ab283e7f76196ac7edcac97f8eba55ea3ab92c3eecb"
+    },
     {
       "path": "scripts/gds/render-ideas.js",
       "mode": "0000644",
@@ -9317,7 +9322,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "9264831ff874468719e9a6f73a3dfa39507f6ce033f25cdfc9d08e840d1a58fe"
+      "sha256": "5c9d16a923a0cb30e18960d8714e1e8454940d1c4d6cef4d22fa8096a98237ab"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -10437,7 +10442,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",
@@ -11954,6 +11964,11 @@
       "mode": "0000644",
       "sha256": "a7a0a61260a4ee78f5452b76ee6d8ef732104cf9c32a3c05bfa25517bf883aeb"
     },
+    {
+      "path": "tests/rename_history_restraint.mjs",
+      "mode": "0000644",
+      "sha256": "2cbc4981c0f33a6597445f268055d10107b6696be4de42e5790e7efefc087edd"
+    },
     {
       "path": "tests/render_prefs.mjs",
       "mode": "0000644",

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,9 @@ 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)
+  1.19.591 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.590 with no explicit bump. run 34181177013. (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,
 };