@bongos/core 1.19.1059 → 1.19.1060

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.1059",
-  "core_contract": "1.19.1059",
-  "source_commit": "77525594aafb82e0be5f53d111e1d751ed6945cc",
+  "core_version": "1.19.1060",
+  "core_contract": "1.19.1060",
+  "source_commit": "053ab05047f2cede246dd8c6cca763a032ee8495",
   "source_ref": "HEAD",
-  "built_at": "2026-09-28T11:26:07.315Z",
+  "built_at": "2026-09-28T11:58:43.905Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 543,
     "agent_docs_stubbed": 26,
-    "functional_verbatim": 2525,
+    "functional_verbatim": 2528,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 3095,
-  "tree_sha256": "27e342154726c2063d49121ee1ef6a47f3125fc8673ba3a3ed328c8a15fc25db",
+  "file_count": 3098,
+  "tree_sha256": "80aa074ee45fe0f2b5b60a190786cd4833e3aad1153828d157d5fe2b865b7db0",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -317,12 +317,12 @@
     {
       "path": "clients/bongos-client/README.md",
       "mode": "0000644",
-      "sha256": "18f34899047600dc6f4301d3ee6728e7bf01216bb0aad0d3779c90c24878c417"
+      "sha256": "3e5980fb95bfaf6029cdddc9c9921053d9897cbcbf15be30e58e9b494177d4af"
     },
     {
       "path": "clients/bongos-client/bongos-client.global.js",
       "mode": "0000644",
-      "sha256": "cb4119d5434eb11476fb56ab5f3ad7cba19a04636669def7a9642abdfb379410"
+      "sha256": "c587bec39fefe04695a0c1673882e3af552fe72486909e9e90759a3b46e20916"
     },
     {
       "path": "clients/bongos-client/examples/hello-world.mjs",
@@ -332,17 +332,17 @@
     {
       "path": "clients/bongos-client/index.cjs",
       "mode": "0000644",
-      "sha256": "3d0b0cee2b777554c3289c54a1986bd65ee3a51b83d26535384b505866f56d5c"
+      "sha256": "ee6df391f3c319e77b9601fb47bf5deddc56adb95af62e8086a3d6dbeac4993b"
     },
     {
       "path": "clients/bongos-client/index.d.ts",
       "mode": "0000644",
-      "sha256": "df7d595c5ed10a4472cc3fc7bf3254e8b90eca5651394177b26dcbe3327fcf1e"
+      "sha256": "ed5f287b10278823cf322091feff1e784125d21a7856ad021a98e6e3e2269f71"
     },
     {
       "path": "clients/bongos-client/index.mjs",
       "mode": "0000644",
-      "sha256": "b211a8a2072874c86fa7d1c948a8e0313b76191c69fd4d044e2704aada198113"
+      "sha256": "a43b2952238b2f19e76fe8767ec6b8a313fdfb0173cfa10946b6dee63e97af69"
     },
     {
       "path": "clients/bongos-client/package.json",
@@ -2177,12 +2177,12 @@
     {
       "path": "docs/api-reference.md",
       "mode": "0000644",
-      "sha256": "e79005662b3fc53fed213d29c07885df5563a1319e978387d84fb30295a609c3"
+      "sha256": "d642de14db69137bb04bf79bf4a67b8ec01818ac2ff6b85f04fca4944f2bdd15"
     },
     {
       "path": "docs/api/openapi.json",
       "mode": "0000644",
-      "sha256": "fd26c908294adf589bfe05b6f1432b74bbb07f4cd5c0dce4d89e9b052e3dbdfa"
+      "sha256": "f47a697a636c8b50dafd4d8e58986676af0b8fcacaf89f6a418b230ebcb28cdc"
     },
     {
       "path": "docs/architecture.md",
@@ -2742,7 +2742,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "e503dd3babb557fcc2cdd366604e50c845d3264f29a6fbffd8c31b9a40cf6ae9"
+      "sha256": "72f72960133805df016e92eb786b37d8fb7cb67bf3f09e9fcade295cce4773cb"
     },
     {
       "path": "docs/modules-contract.md",
@@ -4112,7 +4112,7 @@
     {
       "path": "modules/copy-desk/flags.js",
       "mode": "0000644",
-      "sha256": "292f0d3461855552efc25cc5207dd4d58db38ef4c1b6eadcbb55521f89e6fa5e"
+      "sha256": "ca617aef2c209f89c57acf2db7772b27f0bb7e790afb48dc940822422ec8ad81"
     },
     {
       "path": "modules/copy-desk/migrations/copy_desk_001_flags.sql",
@@ -4137,7 +4137,7 @@
     {
       "path": "modules/copy-desk/page-status.js",
       "mode": "0000644",
-      "sha256": "63af13ad05f0b2479eb9488f542f3f0dade74273de41e422583eebe070359271"
+      "sha256": "fe85e899abb8524b36ef7187a8a2b5b127ea87342c378a32b95a644d18a83021"
     },
     {
       "path": "modules/copy-desk/pages.js",
@@ -4157,7 +4157,7 @@
     {
       "path": "modules/copy-desk/routes/copy-desk.js",
       "mode": "0000644",
-      "sha256": "4c7bab355d8410ec755f9677914b97132edc5be7c61b0aeebbf5b14abd2a3b42"
+      "sha256": "6d313d730906c5f240504695b792401fc0dc9ffde993efd2f330a9e71df276c0"
     },
     {
       "path": "modules/copy-desk/tests/copy_flags.mjs",
@@ -4169,6 +4169,11 @@
       "mode": "0000644",
       "sha256": "17ad6640e97dde18273ccd5c533b6910d490bfad970da16fd0712c20a8b5f7f3"
     },
+    {
+      "path": "modules/copy-desk/tests/copy_page_next.mjs",
+      "mode": "0000644",
+      "sha256": "d82db6db97b22a88a83b4cf9bac7724a411dc7831b08cacd5548c0ac367ad3b9"
+    },
     {
       "path": "modules/copy-desk/tests/copy_page_status.mjs",
       "mode": "0000644",
@@ -8517,12 +8522,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "cd48c5b838a56b6fb70ccedf866a234037b46a049f027facc60d0a925eabe5f9"
+      "sha256": "1dd792c5514fb93f90ca899378a3fe7fb0ba2759d11ae763a593eaa4de211a37"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "c2e9d52b540b2adbe2e9e7b8ae333d2b621add895a6280e1cc6d7c961f26b833"
+      "sha256": "8e2cc56778737033b8c49aabdb41869132a0343fae6419e90aa23adedf474daa"
     },
     {
       "path": "public-docs/index.html",
@@ -8542,7 +8547,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "77adcb2aa4e1aeed40c59698b77423095609e35589148c112b0a7196a5fc4542"
+      "sha256": "971eebaefe45a5e3bd6eac7a217d7a1abc571d02240dac97799f9167643a227b"
     },
     {
       "path": "scripts/bongos-mcp.js",
@@ -10627,7 +10632,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "d599f052a4dddddb6bc9ca72b7b97c99ba2c2e20e1d577cc8afdbfb2391289a5"
+      "sha256": "5be8c8ecfa92788bfeef57fd9e4235d24ac3e4257d10e9936f38ace6b627d2cb"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -11577,12 +11582,17 @@
     {
       "path": "tests/copy_desk_flags_db.mjs",
       "mode": "0000644",
-      "sha256": "b016c0017adfa95de453d418e81e1c22a2a7193418f05f05845a3212941bd074"
+      "sha256": "739bbd623955742864ac712a5f119968ebac671c005054a07a8521c7770a929b"
     },
     {
       "path": "tests/copy_desk_page_claim.mjs",
       "mode": "0000644",
-      "sha256": "18b0e3cd3384226fe2278a7094e45b849e0f43dc41269b40fa5487fd315e0f20"
+      "sha256": "af6cdac77b90aad511a603757e12d7ffefaa7fdbcdd14aefd70ad49e3cd193fe"
+    },
+    {
+      "path": "tests/copy_desk_page_next.mjs",
+      "mode": "0000644",
+      "sha256": "d9827f75b542ce1a3fe9bfe9e3d5cd8ecaaed4691d611dc73617d280ec6cf292"
     },
     {
       "path": "tests/copy_desk_page_reads.mjs",
@@ -12069,6 +12079,11 @@
       "mode": "0000644",
       "sha256": "2f532cacb06f0f074c15101c16578f3183104042644d6c8aa0d2e80fdb425b2f"
     },
+    {
+      "path": "tests/fixtures/page-ledger.mjs",
+      "mode": "0000644",
+      "sha256": "7e6cee001284e873e06a3037f6916abcfbfa53e243daafd652c6f629d4f73012"
+    },
     {
       "path": "tests/fixtures/session-506-digest.json",
       "mode": "0000644",

package/clients/bongos-client/README.md

@@ -5,7 +5,7 @@ A **generated**, zero-dependency typed client for the Bongos API — produced fr
 by hand; it regenerates when the spec changes, so it can never drift from the routes.
 
 - API version: **v1** (served at `/api/bongos/v1`)
-- 448 operations across 68 resource groups
+- 449 operations across 68 resource groups
 
 ## Use it from your project
 

package/clients/bongos-client/bongos-client.global.js

@@ -343,6 +343,8 @@ function createClient(opts = {}) {
       postCopyDeskFlags: (args) => request("POST", "/copy-desk/flags", { hasBody: true }, args),
       // POST /copy-desk/flags/{id}/close — rank: any-builder — POST /copy-desk/flags/:id/close
       postCopyDeskFlagsIdClose: (args) => request("POST", "/copy-desk/flags/{id}/close", { hasBody: true }, args),
+      // GET /copy-desk/next — rank: any-builder — GET /copy-desk/next
+      getCopyDeskNext: (args) => request("GET", "/copy-desk/next", { hasBody: false }, args),
       // GET /copy-desk/pages — rank: any-builder — GET /copy-desk/pages
       getCopyDeskPages: (args) => request("GET", "/copy-desk/pages", { hasBody: false }, args),
       // GET /copy-desk/pages/{pageId} — rank: any-builder — GET /copy-desk/pages/:pageId

package/clients/bongos-client/index.cjs

@@ -342,6 +342,8 @@ function createClient(opts = {}) {
       postCopyDeskFlags: (args) => request("POST", "/copy-desk/flags", { hasBody: true }, args),
       // POST /copy-desk/flags/{id}/close — rank: any-builder — POST /copy-desk/flags/:id/close
       postCopyDeskFlagsIdClose: (args) => request("POST", "/copy-desk/flags/{id}/close", { hasBody: true }, args),
+      // GET /copy-desk/next — rank: any-builder — GET /copy-desk/next
+      getCopyDeskNext: (args) => request("GET", "/copy-desk/next", { hasBody: false }, args),
       // GET /copy-desk/pages — rank: any-builder — GET /copy-desk/pages
       getCopyDeskPages: (args) => request("GET", "/copy-desk/pages", { hasBody: false }, args),
       // GET /copy-desk/pages/{pageId} — rank: any-builder — GET /copy-desk/pages/:pageId

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

@@ -760,6 +760,8 @@ export interface BongosClient {
     postCopyDeskFlags(args: RequestArgs & { body: PostCopyDeskFlagsRequest }): Promise<PostCopyDeskFlagsResponse>;
     /** POST /copy-desk/flags/{id}/close — rank: any-builder */
     postCopyDeskFlagsIdClose(args: RequestArgs & { body: PostCopyDeskFlagsIdCloseRequest }): Promise<PostCopyDeskFlagsIdCloseResponse>;
+    /** GET /copy-desk/next — rank: any-builder */
+    getCopyDeskNext(args?: RequestArgs): Promise<ApiResponse>;
     /** GET /copy-desk/pages — rank: any-builder */
     getCopyDeskPages(args?: RequestArgs): Promise<ApiResponse>;
     /** GET /copy-desk/pages/{pageId} — rank: any-builder */

package/clients/bongos-client/index.mjs

@@ -339,6 +339,8 @@ export function createClient(opts = {}) {
       postCopyDeskFlags: (args) => request("POST", "/copy-desk/flags", { hasBody: true }, args),
       // POST /copy-desk/flags/{id}/close — rank: any-builder — POST /copy-desk/flags/:id/close
       postCopyDeskFlagsIdClose: (args) => request("POST", "/copy-desk/flags/{id}/close", { hasBody: true }, args),
+      // GET /copy-desk/next — rank: any-builder — GET /copy-desk/next
+      getCopyDeskNext: (args) => request("GET", "/copy-desk/next", { hasBody: false }, args),
       // GET /copy-desk/pages — rank: any-builder — GET /copy-desk/pages
       getCopyDeskPages: (args) => request("GET", "/copy-desk/pages", { hasBody: false }, args),
       // GET /copy-desk/pages/{pageId} — rank: any-builder — GET /copy-desk/pages/:pageId

package/docs/api/openapi.json

@@ -5091,6 +5091,37 @@
         ]
       }
     },
+    "/copy-desk/next": {
+      "get": {
+        "operationId": "get_copy_desk_next",
+        "tags": [
+          "copy-desk"
+        ],
+        "summary": "GET /copy-desk/next",
+        "description": "------------------------------------------------------------------------- GET /copy-desk/next — the Tweak/CopyWrite Flow's recommendation (task 1004318 / BV2.TW07, ADR 0341 D8): the page the caller should tweak next and why (\"2 people asked for it\"), plus the next few for \"pick another\". Order: asked for (most distinct askers, then the oldest ask), then changed since the last tweak (most changed lines), then untweaked (landing, builders, status, then inventory order); tweaked pages with no drift last. A page another builder holds, or whose round is in flight, is never recommended (it is listed in `skipped`). The caller's own held page is `resume`, not a recommendation. \"Take next\" is POST /copy-desk/pages/:pageId/claim on `recommended.page_id` (each candidate carries its `take`), one call. The availability rule here is the claim's own, so that call is not refused for a reason this read knew. rank: any signed-in builder. The read is the caller's own and needs no craft; the claim it points at is where the artist gate lives. -------------------------------------------------------------------------\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/copy-desk/routes/copy-desk.js",
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/copy-desk/pages": {
       "get": {
         "operationId": "get_copy_desk_pages",
@@ -28354,7 +28385,7 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 448,
+  "x-endpoint-count": 449,
   "x-schema-count": 484,
   "x-undocumented-bodies": 9,
   "x-response-schemas": 331,

package/docs/api-reference.md

@@ -2,7 +2,7 @@
 
 # Bongos API reference
 
-> **Generated from the live route files** — the route file is authoritative. 448 endpoints across 76 route files.
+> **Generated from the live route files** — the route file is authoritative. 449 endpoints across 76 route files.
 > Machine-readable spec: [`docs/api/openapi.json`](api/openapi.json) (OpenAPI 3.1). Rendered docs site: **`/docs`** (e.g. `cloudbongos.com/docs`).
 
 Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust-boundary-server-enforced-permissions.md)): `public` < `any-builder` < `metic+archon` < `archon`.
@@ -210,12 +210,13 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | GET | `/api/bongos/connections/requests` | `any-builder` | — | MY pending requests, both directions (own data). |
 | GET | `/api/bongos/connections/suggestions` | `any-builder` | — | "builders you may know" (R21, task 1002297; ADR 0202 D5). |
 
-## `copy-desk` (10)
+## `copy-desk` (11)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
 | POST | `/api/bongos/copy-desk/flags` | `any-builder` | `scope`, `surface`, `string_id`, `reason`, `kind` | ------------------------------------------------------------------------- POST /copy-desk/flags — file a flag. |
 | POST | `/api/bongos/copy-desk/flags/:id/close` | `any-builder` | `status`, `resolution_note`, `resolved_task_id` | ------------------------------------------------------------------------- POST /copy-desk/flags/:id/close — resolve or dismiss. |
+| GET | `/api/bongos/copy-desk/next` | `any-builder` | — | ------------------------------------------------------------------------- GET /copy-desk/next — the Tweak/CopyWrite Flow's recommendation… |
 | GET | `/api/bongos/copy-desk/pages` | `any-builder` | — | ------------------------------------------------------------------------- GET /copy-desk/pages — every page's status, count and drift, pl… |
 | GET | `/api/bongos/copy-desk/pages/:pageId` | `any-builder` | — | ------------------------------------------------------------------------- GET /copy-desk/pages/:pageId — one page: status, changelog, the… |
 | POST | `/api/bongos/copy-desk/pages/:pageId/asks` | `any-builder` | `reason` | ------------------------------------------------------------------------- POST /copy-desk/pages/:pageId/asks — ask for a page (task 10043… |

package/docs/module-api-changelog.md

@@ -2605,5 +2605,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.1057 with no explicit bump. run 36390971623. (task 1002620)
   1.19.1059 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.1058 with no explicit bump. run 36415558760. (task 1002620)
+  1.19.1060 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.1059 with no explicit bump. run 36418832327. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/copy-desk/flags.js

@@ -297,6 +297,19 @@ async function countPageAskers(pageId) {
   return rows[0] ? Number(rows[0].askers) : 0;
 }
 
+// The recommendation's signal (TW07, ADR 0341 D8): every page with an open
+// ask, its distinct askers and its OLDEST open ask (the tie-break). One grouped
+// read over copy_desk_flags_page_open_idx, never a count per page.
+async function pageAskSummary() {
+  const { rows } = await pool.query(
+    `SELECT page_id, COUNT(DISTINCT flagged_by)::int AS askers, MIN(flagged_at) AS oldest_ask_at
+       FROM copy_desk_flags
+      WHERE scope = 'page' AND status = 'open'
+      GROUP BY page_id`
+  );
+  return rows.map((r) => ({ page_id: r.page_id, askers: Number(r.askers) || 0, oldest_ask_at: r.oldest_ask_at }));
+}
+
 // An open ask is RESOLVED when the page's next tweak ships (ADR 0341 D6): every
 // ask on the page filed before that ship, stamped with the tweak task. Guarded on
 // status = 'open', so a re-run changes nothing and a dismissed ask stays dismissed.
@@ -316,5 +329,5 @@ module.exports = {
   SCOPES, FLAG_SCOPES, PAGE_SCOPE, STATUSES, KINDS, CLOSING_STATUSES, MIN_REASON_CHARS, MAX_REASON_CHARS, MAX_NOTE_CHARS,
   tidy, normalizeFlagPayload, normalizeResolution, normalizePageAsk,
   insertFlag, listFlags, getFlag, closeFlag,
-  findOpenPageAsk, countPageAskers, resolvePageAsks,
+  findOpenPageAsk, countPageAskers, pageAskSummary, resolvePageAsks,
 };

package/modules/copy-desk/page-status.js

@@ -1,5 +1,6 @@
-// modules/copy-desk/page-status.js — the three Tweak Mode READS, derived
-// (task 1004316 / BV2.TW05, ADR 0341 D7 and D8).
+// modules/copy-desk/page-status.js — the Tweak Mode READS, derived
+// (task 1004316 / BV2.TW05, and the recommendation, task 1004318 / BV2.TW07;
+// ADR 0341 D7 and D8).
 //
 // There is NO status table, by the planning session's ruling: a table would be a
 // second record of what the task ledger already says. Everything here is a pure
@@ -13,7 +14,7 @@
 //   * docs/page-readings.json (what each page says now), for drift only;
 //   * the caller's `tweak.page_approved:` credit rows, for the tally.
 //
-// The three reads:
+// The four reads:
 //
 //   PER PAGE      status (Untweaked / Text tweaked / UI tweaked / Both) with its
 //                 count ("Text tweaked 2x"), the changelog, and the lines changed
@@ -22,6 +23,8 @@
 //                 shipped round, and drift does not lower it.
 //   PER ARTIST    the studio corner's tally: credits from approved pages, pages
 //                 tweaked, and this week's gain.
+//   NEXT          the recommendation (TW07): the page to tweak next, its why,
+//                 and the next few for "pick another" (composeNext, below).
 //
 // Pure: no fs, no DB, no clock (the caller passes `now`). The route owns the I/O.
 
@@ -340,8 +343,179 @@ function composeTally({ builderId, tasks, creditRows, now }) {
   };
 }
 
+// ---------------------------------------------------------------------------
+// The recommendation, "what should I tweak next" (task 1004318 / BV2.TW07,
+// ADR 0341 D8). The fourth read, over the same ledger rows as the other three
+// plus one more signal: the open page asks (flags.pageAskSummary()).
+//
+// WHO MAY BE RECOMMENDED A PAGE. Exactly the pages the claim route would hand
+// the caller, decided by the claim's own rule (modules/lifecycle/
+// page-tweak-claim.js) over the same fields, so "take next" on the answer can
+// never be refused for a reason this read already knew:
+//
+//   no open round                      free: the claim creates round n+1
+//   open, held by someone else         SKIPPED (page_held)
+//   open, the caller's own web claim   RESUME, reported apart, never a
+//                                      recommendation (the caller is already
+//                                      writing it)
+//   open, the caller's own CLI claim   SKIPPED: they are applying it (in flight)
+//   open, unheld, roundOpenForWriting  free: an unheld draft, taken over
+//   open, unheld, anything else        SKIPPED (page_in_flight)
+//
+// THE ORDER (D8). Four tiers, and within each its own ties, then the base
+// order (surface landing, builders, status, then inventory order):
+//
+//   asked      open asks: most distinct askers first, then the OLDEST ask
+//   changed    tweaked and drifted: most changed lines first
+//   untweaked  count 0
+//   tweaked    tweaked with no drift, or drift unknown: last
+//
+// The mock's sample list puts an untweaked page before a changed one; the
+// spec's order wins and the mock's list is sample data (ADR 0341 pick 8).
+// ---------------------------------------------------------------------------
+
+const NEXT_ALTERNATIVES = 4; // the mock's "pick another" row holds four
+const NEXT_TIERS = Object.freeze(['asked', 'changed', 'untweaked', 'tweaked']);
+
+function plural(n, one, many) { return `${n} ${n === 1 ? one : many}`; }
+
+// Where the caller stands with one page, by the claim route's own rule.
+function availability(rounds, builderId) {
+  const open = [...(rounds || [])].reverse().find((r) => !TERMINAL.has(r.status)) || null;
+  if (!open) return { kind: 'free', open: null };
+  if (open.holder_id != null) {
+    if (String(open.holder_id) !== String(builderId)) {
+      return { kind: 'held', open, holder: person(open.holder_id, open.holder_login) };
+    }
+    return open.holder_worktree ? { kind: 'in_flight', open } : { kind: 'resume', open };
+  }
+  return pages.roundOpenForWriting(open) ? { kind: 'free', open } : { kind: 'in_flight', open };
+}
+
+function surfaceWord(id) {
+  return (SURFACE_LABELS[id] || id).toLowerCase();
+}
+
+function candidateFor({ page, rounds, readingPage, readingsOk, ask, builderId, avail }) {
+  const counts = countsFor(rounds);
+  const drift = driftFor(readingPage, rounds, readingsOk);
+  const askers = ask ? ask.askers : 0;
+  // "Lines changed": a reworded line is one line that differs on each side of
+  // the multiset, so it counts once; a line only added, or only removed, still
+  // counts. The larger side is that number.
+  const changedLines = drift.known && drift.changed ? Math.max(drift.changed_count, drift.removed_count) : 0;
+  const last = latestShipped(rounds);
+  const yours = !!last && last.artist_id != null && String(last.artist_id) === String(builderId);
+
+  const parts = [];
+  if (askers > 0) parts.push(`${plural(askers, 'person', 'people')} asked for it`);
+  if (counts.count === 0) parts.push('untweaked');
+  else if (changedLines > 0) parts.push(`${plural(changedLines, 'line', 'lines')} changed since ${yours ? 'your' : 'the'} last pass`);
+  else parts.push(drift.known ? `${counts.status_label.toLowerCase()}, nothing changed since` : counts.status_label.toLowerCase());
+
+  let tier = 'tweaked';
+  if (askers > 0) tier = 'asked';
+  else if (changedLines > 0) tier = 'changed';
+  else if (counts.count === 0) tier = 'untweaked';
+
+  return {
+    page_id: page.id,
+    surface: page.surface,
+    title: page.title || page.id,
+    path: page.path || null,
+    tier,
+    why: parts[0],
+    why_line: [surfaceWord(page.surface), ...parts].join(' · '),
+    askers,
+    oldest_ask_at: ask ? iso(ask.oldest_ask_at) : null,
+    changed_lines: changedLines,
+    drift_known: drift.known,
+    count: counts.count,
+    status_label: counts.status_label,
+    // An unheld draft the claim takes over, so the take is honest about it.
+    draft_round: avail.open ? { task_id: String(avail.open.id), round: avail.open.round } : null,
+    take: { method: 'POST', path: `/copy-desk/pages/${page.id}/claim` },
+  };
+}
+
+function compareCandidates(a, b) {
+  const t = NEXT_TIERS.indexOf(a.tier) - NEXT_TIERS.indexOf(b.tier);
+  if (t) return t;
+  if (a.tier === 'asked') {
+    if (a.askers !== b.askers) return b.askers - a.askers;
+    const at = a.oldest_ask_at ? Date.parse(a.oldest_ask_at) : Infinity;
+    const bt = b.oldest_ask_at ? Date.parse(b.oldest_ask_at) : Infinity;
+    if (at !== bt) return at - bt;
+  }
+  if (a.tier === 'changed' && a.changed_lines !== b.changed_lines) return b.changed_lines - a.changed_lines;
+  return a._base - b._base;
+}
+
+// GET /copy-desk/next — the recommended page for `builderId`, its why, and
+// the next few for "pick another". `asks` is flags.pageAskSummary()'s rows.
+function composeNext({ inventory, readings, tasks, asks, builderId, alternatives = NEXT_ALTERNATIVES }) {
+  const byPage = indexRounds(tasks);
+  const readingsOk = !!readings;
+  const rIdx = readingIndex(readings);
+  const askIdx = new Map();
+  for (const a of asks || []) if (a && a.page_id && Number(a.askers) > 0) askIdx.set(a.page_id, { askers: Number(a.askers), oldest_ask_at: a.oldest_ask_at });
+
+  const surfaceRank = new Map(orderedSurfaces(inventory).map((id, i) => [id, i]));
+  const invPages = ((inventory && inventory.pages) || []).filter((p) => p && p.id);
+  const base = new Map(invPages
+    .map((p, i) => ({ id: p.id, s: surfaceRank.has(p.surface) ? surfaceRank.get(p.surface) : surfaceRank.size, i }))
+    .sort((a, b) => a.s - b.s || a.i - b.i)
+    .map((x, k) => [x.id, k]));
+
+  let resume = null;
+  const skipped = [];
+  const candidates = [];
+  for (const page of invPages) {
+    const rounds = byPage.get(page.id) || [];
+    const avail = availability(rounds, builderId);
+    if (avail.kind === 'resume') {
+      resume = {
+        page_id: page.id, surface: page.surface, title: page.title || page.id, path: page.path || null,
+        task_id: String(avail.open.id), round: avail.open.round,
+        take: { method: 'POST', path: `/copy-desk/pages/${page.id}/claim` },
+      };
+      continue;
+    }
+    if (avail.kind === 'held' || avail.kind === 'in_flight') {
+      skipped.push({
+        page_id: page.id,
+        reason: avail.kind === 'held' ? 'page_held' : 'page_in_flight',
+        state: roundState(avail.open),
+        ...(avail.holder ? { holder: avail.holder } : {}),
+      });
+      continue;
+    }
+    const c = candidateFor({ page, rounds, readingPage: rIdx.get(page.id), readingsOk, ask: askIdx.get(page.id), builderId, avail });
+    c._base = base.get(page.id);
+    candidates.push(c);
+  }
+  candidates.sort(compareCandidates);
+  for (const c of candidates) delete c._base;
+
+  const n = Math.max(0, Math.floor(Number(alternatives) || 0));
+  return {
+    builder_id: String(builderId),
+    resume,
+    recommended: candidates[0] || null,
+    alternatives: candidates.slice(1, 1 + n),
+    candidates: candidates.length,
+    // "4 pages have been asked for" (the mock's Artist Review Status line):
+    // every inventory page with an open ask, held or not.
+    asked_pages: invPages.filter((p) => askIdx.has(p.id)).length,
+    skipped,
+  };
+}
+
 module.exports = {
   TALLY_REASON_PREFIX,
+  NEXT_ALTERNATIVES,
+  NEXT_TIERS,
+  composeNext,
   SURFACE_ORDER,
   SURFACE_LABELS,
   STATUS,

package/modules/copy-desk/routes/copy-desk.js

@@ -663,6 +663,47 @@ module.exports = function buildCopyDeskRouter() {
     }
   });
 
+  // -------------------------------------------------------------------------
+  // GET /copy-desk/next — the Tweak/CopyWrite Flow's recommendation (task
+  // 1004318 / BV2.TW07, ADR 0341 D8): the page the caller should tweak next
+  // and why ("2 people asked for it"), plus the next few for "pick another".
+  //
+  // Order: asked for (most distinct askers, then the oldest ask), then changed
+  // since the last tweak (most changed lines), then untweaked (landing,
+  // builders, status, then inventory order); tweaked pages with no drift last.
+  // A page another builder holds, or whose round is in flight, is never
+  // recommended (it is listed in `skipped`). The caller's own held page is
+  // `resume`, not a recommendation.
+  //
+  // "Take next" is POST /copy-desk/pages/:pageId/claim on `recommended.page_id`
+  // (each candidate carries its `take`), one call. The availability rule here
+  // is the claim's own, so that call is not refused for a reason this read knew.
+  //
+  // rank: any signed-in builder. The read is the caller's own and needs no
+  // craft; the claim it points at is where the artist gate lives.
+  // -------------------------------------------------------------------------
+  router.get('/copy-desk/next', api.requireBuilder, async (req, res) => {
+    try {
+      const inv = inventoryOrFail(res);
+      if (!inv) return;
+      const lifecycle = pageReadsOrFail(res);
+      if (!lifecycle) return;
+      const readings = readingsState();
+      const [tasks, asks] = await Promise.all([
+        lifecycle.listPageTweakTasks(),
+        flags.pageAskSummary(),
+      ]);
+      const out = pageStatus.composeNext({ inventory: inv.data, readings: readings.data, tasks, asks, builderId: req.builder.id });
+      out.inventory = { at: inv.at };
+      out.readings = readings.info;
+      res.set('Cache-Control', 'no-store');
+      res.json(out);
+    } catch (err) {
+      log.error({ err }, 'GET /copy-desk/next failed');
+      if (!res.headersSent) res.fail('copy_next_failed', 500);
+    }
+  });
+
   // -------------------------------------------------------------------------
   // POST /copy-desk/pages/:pageId/claim — claim a page's tweak (task 1004317 /
   // BV2.TW06, ADR 0341 D2 and D5). Also Resume and "Take next".