@bongos/core 1.19.1063 → 1.19.1065

package/docs/page-inventory.json

@@ -13,7 +13,7 @@
     "pages": 38,
     "surfaces": 3,
     "with_states": 31,
-    "states": 155
+    "states": 161
   },
   "surfaces": [
     {
@@ -842,11 +842,14 @@
         "modules/hall-ui/public/studio.html",
         "modules/hall-ui/public/style.css",
         "modules/hall-ui/public/studio.css",
+        "modules/hall-ui/public/approval-queue.css",
         "modules/hall-ui/public/shell.js",
         "modules/hall-ui/public/palette.js",
         "modules/hall-ui/public/dom-utils.js",
         "modules/hall-ui/public/hall-visual.js",
         "modules/hall-ui/public/hall-kit.js",
+        "modules/hall-ui/public/approval-queue-lib.js",
+        "modules/hall-ui/public/approval-queue.js",
         "modules/hall-ui/public/studio.js"
       ],
       "states_files": [
@@ -856,7 +859,13 @@
         "focus",
         "out",
         "full",
-        "full-back"
+        "full-back",
+        "approvals",
+        "approvals-before",
+        "approvals-phone",
+        "approvals-note",
+        "approved",
+        "sent-back"
       ]
     },
     {

package/docs/page-readings.json

@@ -5,7 +5,7 @@
   "adr": "0341 D3",
   "reread": "node scripts/gds/page-reader.js --stale",
   "how": ["Generated by node scripts/gds/page-reader.js (BV2.TW04, task 1004315; ADR 0341 D3). Do not hand-edit.","One entry per page of docs/page-inventory.json. Lines are in page order: the default state first, and a line only another state shows sits where that state shows it, with its state named.","placement: placed = a docs/copy-registry.json row renders it (file, line, string_id); shared = shell text every page of the surface carries (top bar, sidebar, footer), with its row when the registry has one; unplaced = the registry cannot place it (a rewrite becomes an engineer task, ADR 0341 D4).","text keeps {…} where the registry row has a hole, or where a value the page read from its API was filled in. A string that is only such data is counted under omitted.data, not listed.","reading_hash is over the non-shared lines (key, section, text); files_hash is over the page's inventory files. --check compares files_hash only and never opens a browser.","Rendered through the hall-preview harness (hall) and the ui-design kit stub (landing, status), at 1280x800 with the clock pinned, so a reading is the fixture world's page."],
-  "counts": {"pages":38,"lines":3636,"placed":1131,"shared":247,"unplaced":2258,"omitted_data":2010},
+  "counts": {"pages":38,"lines":3659,"placed":1139,"shared":247,"unplaced":2273,"omitted_data":2015},
   "pages": [
     {
       "id": "builders:atlas",
@@ -2650,35 +2650,58 @@
       "id": "builders:studio",
       "surface": "builders",
       "title": "Studio",
-      "states_read": ["focus","out","full","full-back"],
-      "files_hash": "2bac3a520cca3414",
-      "reading_hash": "8f0ed70c6bd4d60e",
-      "counts": {"lines":22,"placed":15,"shared":5,"unplaced":2},
-      "omitted": {"data":2},
+      "states_read": ["focus","out","full","full-back","approvals","approvals-before","approvals-phone","approvals-note","approved","sent-back"],
+      "files_hash": "e1041dfa74aca8dd",
+      "reading_hash": "e52bb7163191d85a",
+      "counts": {"lines":45,"placed":23,"shared":5,"unplaced":17},
+      "omitted": {"data":7},
       "notes": [],
       "lines": [
         {"key":"L0001","section":"skip link","text":"Skip to content","placement":"shared","file":"modules/hall-ui/public/shell.js","line":776,"string_id":"87cee78ca134"},
         {"key":"L0002","section":"top bar","text":"Studio","placement":"shared"},
         {"key":"L0003","section":"top bar","text":"Jump to…","placement":"shared","file":"modules/hall-ui/public/shell.js","line":496,"string_id":"eba610d25523"},
         {"key":"L0004","section":"top bar","text":"Ctrl K","placement":"shared"},
-        {"key":"L0005","section":"page top","text":"artist mode","placement":"placed","file":"modules/hall-ui/public/studio.html","line":42,"string_id":"520853131591"},
+        {"key":"L0005","section":"page top","text":"artist mode","placement":"placed","file":"modules/hall-ui/public/studio.html","line":43,"string_id":"520853131591"},
         {"key":"L0006","section":"Good morning, {…}","text":"Good morning, {…}","placement":"unplaced"},
         {"key":"L0007","section":"Good morning, {…}","text":"{…} of {…}","placement":"placed","file":"modules/hall-ui/public/sky-panel.js","line":120,"string_id":"73c1372b43d9"},
-        {"key":"L0008","section":"Good morning, {…}","text":"to tend now · {…}","placement":"placed","file":"modules/hall-ui/public/studio.js","line":204,"string_id":"1b88ce51fd84"},
-        {"key":"L0009","section":"The copy and visuals that {…} in task #1899","text":"The copy and visuals that {…} in task #1899","placement":"unplaced"},
-        {"key":"L0010","section":"The copy and visuals that {…} in task #1899","text":"It shipped and it is live. Say what you see — your review coaches the grader and never blocks what shipped.","placement":"placed","file":"modules/hall-ui/public/studio.js","line":202,"string_id":"a28aa368453f"},
-        {"key":"L0011","section":"The copy and visuals that {…} in task #1899","text":"What you saw","placement":"placed","file":"modules/hall-ui/public/studio.js","line":162,"string_id":"1d5bfd09068c"},
-        {"key":"L0012","section":"The copy and visuals that {…} in task #1899","text":"— your words, in your voice. Needed for a note or a follow-up.","placement":"placed","file":"modules/hall-ui/public/studio.js","line":162,"string_id":"d3afa6d6dd9e"},
-        {"key":"L0013","section":"The copy and visuals that {…} in task #1899","text":"The headline lands, but the sub-line reads like a brochure.","placement":"placed","file":"modules/hall-ui/public/studio.js","line":162,"string_id":"027e9420daa2","attr":"placeholder"},
-        {"key":"L0014","section":"The copy and visuals that {…} in task #1899","text":"Looks good","placement":"placed","file":"modules/hall-ui/public/studio.js","line":162,"string_id":"73677b6839d7"},
-        {"key":"L0015","section":"The copy and visuals that {…} in task #1899","text":"Note it","placement":"placed","file":"modules/hall-ui/public/studio.js","line":162,"string_id":"73c72974f4f9"},
-        {"key":"L0016","section":"The copy and visuals that {…} in task #1899","text":"Needs work","placement":"placed","file":"modules/hall-ui/public/studio.js","line":162,"string_id":"3970d299c95a"},
-        {"key":"L0017","section":"The copy and visuals that {…} in task #1899","text":"Open this review","placement":"placed","file":"modules/hall-ui/public/studio.js","line":204,"string_id":"1cb80282de09"},
-        {"key":"L0018","section":"The copy and visuals that {…} in task #1899","text":"Let it be for now","placement":"placed","file":"modules/hall-ui/public/studio.js","line":204,"string_id":"d6a78b9e5368"},
-        {"key":"L0019","section":"The copy and visuals that {…} in task #1899","text":"and {…} more waiting{…}","placement":"placed","file":"modules/hall-ui/public/studio.js","line":277,"string_id":"d86265f99668"},
-        {"key":"L0020","section":"The copy and visuals that {…} in task #1899","text":"The copy desk — every flagged string","placement":"placed","file":"modules/hall-ui/public/studio.html","line":63,"string_id":"2dc061096c48"},
-        {"key":"L0021","section":"The copy and visuals that {…} in task #1899","text":"The task board — all work","placement":"placed","file":"modules/hall-ui/public/studio.html","line":64,"string_id":"599fd0e82d1c"},
-        {"key":"L0022","section":"footer","text":"Sign out","placement":"shared","file":"modules/hall-ui/public/shell.js","line":473,"string_id":"1883ad7f07fc"}
+        {"key":"L0008","section":"Good morning, {…}","text":"Approval queue","placement":"placed","file":"modules/hall-ui/public/studio.html","line":55,"string_id":"20c98a4b630f"},
+        {"key":"L0009","section":"Good morning, {…}","text":"1 page applied, waiting for you","placement":"unplaced","state":"approved"},
+        {"key":"L0010","section":"Good morning, {…}","text":"2 pages applied, waiting for you","placement":"unplaced"},
+        {"key":"L0011","section":"Good morning, {…}","text":"to tend now · {…}","placement":"placed","file":"modules/hall-ui/public/studio.js","line":215,"string_id":"1b88ce51fd84"},
+        {"key":"L0012","section":"The copy and visuals that {…} in task #1899","text":"The copy and visuals that {…} in task #1899","placement":"unplaced"},
+        {"key":"L0013","section":"The copy and visuals that {…} in task #1899","text":"It shipped and it is live. Say what you see — your review coaches the grader and never blocks what shipped.","placement":"placed","file":"modules/hall-ui/public/studio.js","line":213,"string_id":"a28aa368453f"},
+        {"key":"L0014","section":"The copy and visuals that {…} in task #1899","text":"What you saw","placement":"placed","file":"modules/hall-ui/public/studio.js","line":173,"string_id":"1d5bfd09068c"},
+        {"key":"L0015","section":"The copy and visuals that {…} in task #1899","text":"— your words, in your voice. Needed for a note or a follow-up.","placement":"placed","file":"modules/hall-ui/public/studio.js","line":173,"string_id":"d3afa6d6dd9e"},
+        {"key":"L0016","section":"The copy and visuals that {…} in task #1899","text":"The headline lands, but the sub-line reads like a brochure.","placement":"placed","file":"modules/hall-ui/public/studio.js","line":173,"string_id":"027e9420daa2","attr":"placeholder"},
+        {"key":"L0017","section":"The copy and visuals that {…} in task #1899","text":"Looks good","placement":"placed","file":"modules/hall-ui/public/studio.js","line":173,"string_id":"73677b6839d7"},
+        {"key":"L0018","section":"The copy and visuals that {…} in task #1899","text":"Note it","placement":"placed","file":"modules/hall-ui/public/studio.js","line":173,"string_id":"73c72974f4f9"},
+        {"key":"L0019","section":"The copy and visuals that {…} in task #1899","text":"Needs work","placement":"placed","file":"modules/hall-ui/public/studio.js","line":173,"string_id":"3970d299c95a"},
+        {"key":"L0020","section":"The copy and visuals that {…} in task #1899","text":"Open this review","placement":"placed","file":"modules/hall-ui/public/studio.js","line":215,"string_id":"1cb80282de09"},
+        {"key":"L0021","section":"The copy and visuals that {…} in task #1899","text":"Let it be for now","placement":"placed","file":"modules/hall-ui/public/studio.js","line":215,"string_id":"d6a78b9e5368"},
+        {"key":"L0022","section":"The copy and visuals that {…} in task #1899","text":"and {…} more waiting{…}","placement":"placed","file":"modules/hall-ui/public/studio.js","line":288,"string_id":"d86265f99668"},
+        {"key":"L0023","section":"The copy and visuals that {…} in task #1899","text":"The copy desk — every flagged string","placement":"placed","file":"modules/hall-ui/public/studio.html","line":76,"string_id":"2dc061096c48"},
+        {"key":"L0024","section":"The copy and visuals that {…} in task #1899","text":"The task board — all work","placement":"placed","file":"modules/hall-ui/public/studio.html","line":77,"string_id":"599fd0e82d1c"},
+        {"key":"L0025","section":"footer","text":"Sign out","placement":"shared","file":"modules/hall-ui/public/shell.js","line":473,"string_id":"1883ad7f07fc"},
+        {"key":"L0026","section":"The copy and visuals that {…} in task #1899","text":"{…} of {…}","placement":"placed","file":"modules/hall-ui/public/sky-panel.js","line":120,"string_id":"73c1372b43d9","state":"approvals"},
+        {"key":"L0027","section":"Home · {…} · 3 lines rewritten, applied · 1 not applied","text":"Home","placement":"unplaced","state":"approvals"},
+        {"key":"L0028","section":"Home · {…} · 3 lines rewritten, applied · 1 not applied","text":"· {…} · 3 lines rewritten, applied · 1 not applied","placement":"unplaced","state":"approvals"},
+        {"key":"L0029","section":"Home · {…} · 3 lines rewritten, applied · 1 not applied","text":"before","placement":"unplaced","state":"approvals"},
+        {"key":"L0030","section":"Home · {…} · 3 lines rewritten, applied · 1 not applied","text":"after","placement":"unplaced","state":"approvals"},
+        {"key":"L0031","section":"Home · {…} · 3 lines rewritten, applied · 1 not applied","text":"close","placement":"unplaced","state":"approvals"},
+        {"key":"L0032","section":"Home · {…} · 3 lines rewritten, applied · 1 not applied","text":"desktop","placement":"unplaced","state":"approvals"},
+        {"key":"L0033","section":"Home · {…} · 3 lines rewritten, applied · 1 not applied","text":"phone","placement":"unplaced","state":"approvals"},
+        {"key":"L0034","section":"Home · {…} · 3 lines rewritten, applied · 1 not applied","text":"light","placement":"unplaced","state":"approvals"},
+        {"key":"L0035","section":"Home · {…} · 3 lines rewritten, applied · 1 not applied","text":"dark","placement":"unplaced","state":"approvals"},
+        {"key":"L0036","section":"Home · {…} · 3 lines rewritten, applied · 1 not applied","text":"{…} project{…}","placement":"placed","file":"modules/hall-ui/public/fleet.js","line":39,"string_id":"771bef3d31b5","state":"approvals-before","occurrences":12},
+        {"key":"L0037","section":"Home · {…} · 3 lines rewritten, applied · 1 not applied","text":"not applied: the page no longer shows it","placement":"unplaced","state":"approvals"},
+        {"key":"L0038","section":"Home · {…} · 3 lines rewritten, applied · 1 not applied","text":"Sent back with your note. It comes back to the queue once it is re-applied.","placement":"unplaced","state":"sent-back"},
+        {"key":"L0039","section":"Home · {…} · 3 lines rewritten, applied · 1 not applied","text":"Approved. It ships now, and Home reads text tweaked 3x. Next in the queue: Contact.","placement":"unplaced","state":"approved"},
+        {"key":"L0040","section":"Home · {…} · 3 lines rewritten, applied · 1 not applied","text":"open {…}","placement":"placed","file":"modules/hall-ui/public/approval-queue.js","line":156,"string_id":"9a803563c948","state":"approved"},
+        {"key":"L0041","section":"Home · {…} · 3 lines rewritten, applied · 1 not applied","text":"approve and ship","placement":"placed","file":"modules/hall-ui/public/approval-queue.js","line":165,"string_id":"ac37199ccdbb","state":"approvals"},
+        {"key":"L0042","section":"Home · {…} · 3 lines rewritten, applied · 1 not applied","text":"The hero line is too long on a phone.","placement":"placed","file":"modules/hall-ui/public/approval-queue.js","line":167,"string_id":"f08587a38a2a","attr":"placeholder","state":"approvals-note"},
+        {"key":"L0043","section":"Home · {…} · 3 lines rewritten, applied · 1 not applied","text":"send","placement":"unplaced","state":"approvals-note"},
+        {"key":"L0044","section":"Home · {…} · 3 lines rewritten, applied · 1 not applied","text":"send it back","placement":"placed","file":"modules/hall-ui/public/approval-queue.js","line":172,"string_id":"92775a3d8d0d","state":"approvals"},
+        {"key":"L0045","section":"Home · {…} · 3 lines rewritten, applied · 1 not applied","text":"highlighted: the words you changed","placement":"placed","file":"modules/hall-ui/public/approval-queue.js","line":161,"string_id":"c2267f78f931","state":"approvals"}
       ]
     },
     {

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

@@ -0,0 +1,71 @@
+// modules/copy-desk/page-decisions.js — the Approval queue's route helpers (task
+// 1004323 / BV2.TW12, ADR 0341 D7): which round a decision is about, the port's
+// refusals as the panel shows them, and the next page after a decision. The two
+// routes that use them are in routes/copy-desk.js (POST /copy-desk/pages/:pageId/
+// approve and /send-back); these sit apart only because that file is at the
+// 1,500-line ratchet. They answer through `res` and read through the lifecycle
+// port the route hands them; nothing here writes a row, a file or a string.
+
+'use strict';
+
+const pageStatus = require('./page-status');
+
+// The page's round that is waiting for its artist, or the named refusal.
+// `task_id` in the body, when sent, pins the round the artist looked at: a
+// round sent back and re-applied since is another set of renders.
+async function waitingRoundOrFail(res, lifecycle, pageId, body, openRoundOf) {
+  const rounds = await lifecycle.listPageTweakTasks({ pageId });
+  const round = openRoundOf(rounds, pageId);
+  const state = round ? pageStatus.roundState(round) : null;
+  if (!round || state !== 'waiting_for_artist') {
+    res.fail('not_waiting', 409, {
+      page_id: pageId,
+      round: round ? { task_id: String(round.id), status: round.status, state } : null,
+      what_this_means: 'This page is not waiting for approval. Only a page /tweak has applied, and whose grade passed, can be approved or sent back.',
+    });
+    return null;
+  }
+  if (body.task_id != null && String(body.task_id) !== String(round.id)) {
+    res.fail('round_moved', 409, {
+      page_id: pageId,
+      round: { task_id: String(round.id) },
+      what_this_means: 'The page waiting now is a different round from the one you looked at. Open the Approval queue again to see its renders; nothing was decided.',
+    });
+    return null;
+  }
+  return { round, rounds };
+}
+
+// The port's refusals, as the panel shows them.
+function refuseDecision(res, pageId, r) {
+  switch (r.outcome) {
+    case 'not_an_artist':
+      return res.fail('not_an_artist', 403, {
+        page_id: pageId,
+        what_this_means: 'Only the artist who wrote this page, or another artist, can approve it or send it back. The project owner can still land it through an override request on the task.',
+      });
+    case 'not_waiting':
+    case 'wrong_source':
+    case 'not_found':
+      return res.fail('not_waiting', 409, {
+        page_id: pageId,
+        what_this_means: 'This page is no longer waiting for approval (it was decided a moment ago, or it is being applied again). Nothing was changed.',
+      });
+    case 'builder_inactive':
+      return res.fail('builder_inactive', 403);
+    case 'refused':
+      return res.fail((r.refusal && r.refusal.code) || 'send_back_refused', 400, (r.refusal && r.refusal.detail) || {});
+    default:
+      throw new Error(`page decision: unexpected outcome ${r.outcome}`);
+  }
+}
+
+// What comes after a decision: the next page in the queue, re-read, so the
+// panel names it ("Next in the queue: Contact").
+async function nextWaiting(lifecycle, invData, builderId, crafts) {
+  const q = pageStatus.composeApprovals({ inventory: invData, tasks: await lifecycle.listPageTweakTasks(), builderId, crafts });
+  const n = q.queue[0] || null;
+  return { count: q.count, page: n ? { page_id: n.page_id, title: n.title, path: n.path, task_id: n.task_id } : null };
+}
+
+module.exports = { waitingRoundOrFail, refuseDecision, nextWaiting };

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

@@ -25,6 +25,8 @@
 //                 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).
+//   APPROVALS     the Approval queue (TW12, task 1004323): every round waiting
+//                 for its artist, "1 of 2" (composeApprovals, below).
 //
 // Pure: no fs, no DB, no clock (the caller passes `now`). The route owns the I/O.
 
@@ -573,7 +575,101 @@ function composeEditor({ page, readingPage, round, builderId }) {
   };
 }
 
+// ---------------------------------------------------------------------------
+// The Approval queue (task 1004323 / BV2.TW12, ADR 0341 D7): every round
+// WAITING FOR ITS ARTIST, oldest applied first, with what the panel shows for
+// each: the page, the lines the batch rewrote (before and after, and the ones
+// the applier refused, by name), what the page will read once approved, and
+// where its renders are. The renders themselves are the applied branch's
+// images, read from GET /tasks/:id/visuals; nothing here builds a page from the
+// batch (ADR 0341 builder pick 9).
+//
+// `crafts` is the caller's crafts (the lifecycle port's builderCrafts): an
+// artist may decide any round, and anyone may decide a round they authored.
+// The routes decide again; this only keeps the panel from offering a verb its
+// route would refuse.
+// ---------------------------------------------------------------------------
+
+function appliedAtOf(round) {
+  const a = pages.parseAppliedBlock(round.description);
+  return a.ok ? iso(a.applied.applied_at) : null;
+}
+
+function approvalFor({ page, pageId, rounds, round, builderId, isArtist }) {
+  const batch = pages.parseBatchBlock(round.description);
+  const applied = pages.parseAppliedBlock(round.description);
+  const refusedBy = new Map();
+  if (applied.ok) for (const r of applied.applied.refused || []) if (r && r.key) refusedBy.set(String(r.key), String(r.code || 'refused'));
+  const lines = batch.ok ? batch.batch.lines.map((l) => ({
+    key: l.key,
+    section: l.section == null ? null : l.section,
+    before: l.before,
+    after: l.after,
+    placement: l.placement || null,
+    refused: refusedBy.get(String(l.key)) || null,
+  })) : [];
+  const shipped = (rounds || []).filter((r) => r.status === 'shipped');
+  const now = countsFor(rounds);
+  const after = countsFor([...shipped, { ...round, status: 'shipped' }]);
+  const author = person(round.artist_id, round.artist_login);
+  return {
+    page_id: pageId,
+    surface: page ? page.surface : String(pageId).split(':')[0],
+    surface_word: surfaceWord(page ? page.surface : String(pageId).split(':')[0]),
+    title: page ? (page.title || page.id) : pageId,
+    path: page ? page.path || null : null,
+    task_id: String(round.id),
+    round: round.round,
+    status: round.status,
+    state: roundState(round),
+    applied_at: appliedAtOf(round),
+    line_count: lines.length,
+    applied_count: lines.filter((l) => !l.refused).length,
+    refused_count: lines.filter((l) => l.refused).length,
+    lines,
+    ...(batch.ok ? {} : { batch_unreadable: batch.code }),
+    author,
+    by_you: !!author && String(author.id) === String(builderId),
+    can_decide: isArtist || (!!author && String(author.id) === String(builderId)),
+    status_label: now.status_label,
+    status_after_approval: after.status_label,
+    sent_back_count: pages.blockPresence(round.description).sent_back_count,
+    visuals: { method: 'GET', path: `/tasks/${round.id}/visuals` },
+    approve: { method: 'POST', path: `/copy-desk/pages/${pageId}/approve` },
+    send_back: { method: 'POST', path: `/copy-desk/pages/${pageId}/send-back` },
+  };
+}
+
+// GET /copy-desk/approvals — the queue, "1 of 2".
+function composeApprovals({ inventory, tasks, builderId, crafts }) {
+  const byPage = indexRounds(tasks);
+  const invById = new Map(((inventory && inventory.pages) || []).filter((p) => p && p.id).map((p) => [p.id, p]));
+  const isArtist = (crafts || []).includes('artist');
+  const queue = [];
+  for (const [pageId, rounds] of byPage) {
+    const open = rounds.filter((r) => !TERMINAL.has(r.status));
+    const round = open.length ? open[open.length - 1] : null;
+    if (!round || roundState(round) !== 'waiting_for_artist') continue;
+    queue.push(approvalFor({ page: invById.get(pageId) || null, pageId, rounds, round, builderId, isArtist }));
+  }
+  // Oldest applied first, the order they reached the artist; a round with no
+  // readable applied block sorts by its task id after the dated ones.
+  queue.sort((a, b) => {
+    const at = a.applied_at ? Date.parse(a.applied_at) : Infinity;
+    const bt = b.applied_at ? Date.parse(b.applied_at) : Infinity;
+    return at - bt || Number(a.task_id) - Number(b.task_id);
+  });
+  queue.forEach((q, i) => { q.position = i + 1; q.of = queue.length; });
+  return {
+    builder_id: String(builderId),
+    is_artist: isArtist,
+    count: queue.length,
+    queue,
+  };
+}
+
 module.exports = {
+  composeApprovals,
   composeEditor,
   TALLY_REASON_PREFIX,
   NEXT_ALTERNATIVES,

package/modules/copy-desk/pages.js

@@ -420,6 +420,32 @@ function unplacedTaskBody(page, line, roundTaskId) {
   ].join('\n');
 }
 
+// ---------------------------------------------------------------------------
+// The send-back (task 1004323 / BV2.TW12, ADR 0341 D4, D7).
+//
+// The artist sends an applied page back with a one-line note of at least ten
+// characters (the flag's own reason floor). Each send-back APPENDS its block,
+// never replaces one, so a round sent back twice says so twice, and the
+// round-state derivation reads the latest `at` (blockPresence above).
+// ---------------------------------------------------------------------------
+
+const MIN_NOTE_CHARS = 10;
+const MAX_NOTE_CHARS = 500;
+
+// The note, tidied (one line) and measured, or a named refusal.
+function normalizeSentBackNote(raw) {
+  const note = tidy(raw);
+  if (note.length < MIN_NOTE_CHARS) return fail('note_too_short', { min: MIN_NOTE_CHARS, length: note.length });
+  if (note.length > MAX_NOTE_CHARS) return fail('note_too_long', { max: MAX_NOTE_CHARS, length: note.length });
+  return { ok: true, note };
+}
+
+// The description with one more sent-back block at its end.
+function appendSentBack(description, { at, by, note }) {
+  const src = String(description || '');
+  return { ok: true, description: src.trimEnd() + (src.trim() ? '\n\n' : '') + composeSentBackBlock({ at, by, note }) };
+}
+
 module.exports = {
   SCHEMA,
   SOURCE,
@@ -438,6 +464,10 @@ module.exports = {
   parseAppliedBlock,
   composeSentBackBlock,
   parseSentBackBlocks,
+  MIN_NOTE_CHARS,
+  MAX_NOTE_CHARS,
+  normalizeSentBackNote,
+  appendSentBack,
   blockPresence,
   roundOpenForWriting,
   MAX_LINE_CHARS,

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

@@ -18,6 +18,9 @@
 // 1004320) the Word round trip, GET and POST /copy-desk/pages/:pageId/draft.docx:
 // the upload lands in the round's DRAFT, through the autosave's own port call.
 // TW10 (task 1004321) added the editor's read, GET /copy-desk/pages/:pageId/draft.
+// TW12 (task 1004323) added the Approval queue: GET /copy-desk/approvals and the
+// two decisions, POST /copy-desk/pages/:pageId/approve and /send-back, which
+// move the round TASK through the lifecycle port and write nothing here.
 //
 // THE RANK SHAPE, AND WHY IT IS ASYMMETRIC:
 //
@@ -58,6 +61,7 @@ const pageData = require('../page-data');
 const pageStatus = require('../page-status');
 const pages = require('../pages');
 const docx = require('../docx');
+const { waitingRoundOrFail, refuseDecision, nextWaiting } = require('../page-decisions');
 
 const { validateOrRespond } = api;
 
@@ -118,6 +122,18 @@ const DRAFT_BODY_SCHEMA = Object.freeze({
 });
 // The submit takes nothing: it freezes the draft already on the task.
 const SUBMIT_BODY_SCHEMA = Object.freeze({});
+// The Approval queue's two decisions (task 1004323 / TW12). Who decides is the
+// session and which page is the path; `task_id` only pins the round the artist
+// looked at, and is checked against the page's waiting round, never trusted.
+// The note is the one piece of text a decision carries, and it is a judgement
+// for the next applier, never wording for the page.
+const APPROVE_BODY_SCHEMA = Object.freeze({
+  task_id: { type: 'string', maxLength: 20, minLength: 1 },
+});
+const SEND_BACK_BODY_SCHEMA = Object.freeze({
+  note:    { required: true, type: 'string', maxLength: pages.MAX_NOTE_CHARS * 2, minLength: 1 },
+  task_id: { type: 'string', maxLength: 20, minLength: 1 },
+});
 
 // The refusals of pages.resolveDraft / freezeBatch, as HTTP statuses.
 const PAGE_REFUSAL_STATUS = Object.freeze({
@@ -1338,6 +1354,143 @@ module.exports = function buildCopyDeskRouter() {
     }
   });
 
+  // -------------------------------------------------------------------------
+  // The Approval queue (task 1004323 / BV2.TW12, ADR 0341 D7 and D11).
+  //
+  // A passed page tweak WAITS at completed for its artist (page-tweak-hold.js).
+  // The artist approves it (it lands) or sends it back with a note (the /tweak
+  // queue), both through the lifecycle port. WHO DECIDES: the author or any
+  // artist, checked by the port; the owner's escape hatch is the override
+  // request. Anyone may READ the queue. Helpers: ../page-decisions.js.
+  // -------------------------------------------------------------------------
+
+  // GET /copy-desk/approvals — every round waiting for its artist, oldest
+  // applied first, with its position ("1 of 2"), the lines it rewrote (and the
+  // ones the applier refused), and where its renders are. Any signed-in
+  // builder; `can_decide` says whether the caller may approve or send back.
+  router.get('/copy-desk/approvals', api.requireBuilder, async (req, res) => {
+    try {
+      const inv = inventoryOrFail(res);
+      if (!inv) return;
+      const lifecycle = pageReadsOrFail(res);
+      if (!lifecycle) return;
+      const [tasks, crafts] = await Promise.all([
+        lifecycle.listPageTweakTasks(),
+        typeof lifecycle.builderCrafts === 'function' ? lifecycle.builderCrafts(req.builder.id) : Promise.resolve([]),
+      ]);
+      const out = pageStatus.composeApprovals({ inventory: inv.data, tasks, builderId: req.builder.id, crafts });
+      res.set('Cache-Control', 'no-store');
+      res.json({ ok: true, ...out });
+    } catch (err) {
+      log.error({ err }, 'GET /copy-desk/approvals failed');
+      if (!res.headersSent) res.fail('copy_approvals_failed', 500);
+    }
+  });
+
+  function decisionPortOrFail(res, name) {
+    const lifecycle = pageReadsOrFail(res);
+    if (!lifecycle) return null;
+    if (typeof lifecycle[name] !== 'function') {
+      res.fail('lifecycle_unavailable', 503, { what_this_means: 'This instance cannot move a page tweak on from the Approval queue. Nothing was decided.' });
+      return null;
+    }
+    return lifecycle;
+  }
+
+  // -------------------------------------------------------------------------
+  // POST /copy-desk/pages/:pageId/approve — the held pass goes on to land.
+  // Body: { task_id? } (the round the artist looked at). The port promotes
+  // completed -> confirmed with the rewards the hold skipped and nudges the
+  // merge; the reconciler lands it otherwise. The count goes up when it ships.
+  //   200 approved   · 409 not_waiting · 409 round_moved · 403 not_an_artist
+  // -------------------------------------------------------------------------
+  router.post('/copy-desk/pages/:pageId/approve', api.requireBuilder, async (req, res) => {
+    try {
+      if (validateOrRespond(req, res, APPROVE_BODY_SCHEMA)) return;
+      const found = pageOrFail(req, res);
+      if (!found) return;
+      const { pageId, inv } = found;
+      const lifecycle = decisionPortOrFail(res, 'approveHeldTweak');
+      if (!lifecycle) return;
+      const waiting = await waitingRoundOrFail(res, lifecycle, pageId, req.body || {}, openRoundOf);
+      if (!waiting) return;
+      const { round } = waiting;
+      // What the page will read once this round ships, from ALL its rounds, read
+      // before the approve moves this one on.
+      const before = pageStatus.composeApprovals({ inventory: inv.data, tasks: waiting.rounds, builderId: req.builder.id, crafts: [] }).queue[0] || null;
+      const r = await lifecycle.approveHeldTweak({ taskId: round.id, builderId: req.builder.id });
+      if (r.outcome !== 'approved') return refuseDecision(res, pageId, r);
+      const crafts = typeof lifecycle.builderCrafts === 'function' ? await lifecycle.builderCrafts(req.builder.id) : [];
+      return res.json({
+        ok: true,
+        outcome: 'approved',
+        page_id: pageId,
+        round: { task_id: String(r.task.id), state: 'landing', status: 'confirmed' },
+        status_after: before ? before.status_after_approval : null,
+        land: r.land || null,
+        next: await nextWaiting(lifecycle, inv.data, req.builder.id, crafts),
+      });
+    } catch (err) {
+      log.error({ err }, 'POST /copy-desk/pages/:pageId/approve failed');
+      if (!res.headersSent) res.fail('copy_page_approve_failed', 500);
+    }
+  });
+
+  // -------------------------------------------------------------------------
+  // POST /copy-desk/pages/:pageId/send-back — back to the /tweak queue with a
+  // note (ADR 0341 D7).
+  //
+  // Body: { note, task_id? }. The note is one line of at least 10 characters
+  // (pages.normalizeSentBackNote). The port appends a page-tweak-sent-back
+  // block { at, by, note }, releases any open claim, drops the round's grade
+  // row, returns the task to ready and closes the unmerged PR, so the round
+  // reads `submitted` again.
+  //
+  //   200 sent_back  · 400 note_too_short / note_too_long · 409 not_waiting ·
+  //   409 round_moved · 403 not_an_artist
+  // -------------------------------------------------------------------------
+  router.post('/copy-desk/pages/:pageId/send-back', api.requireBuilder, async (req, res) => {
+    try {
+      if (validateOrRespond(req, res, SEND_BACK_BODY_SCHEMA)) return;
+      const found = pageOrFail(req, res);
+      if (!found) return;
+      const { pageId, inv } = found;
+      const note = pages.normalizeSentBackNote(req.body.note);
+      if (!note.ok) {
+        return res.fail(note.code, 400, {
+          ...note.detail,
+          what_this_means: `Say in one line what needs changing, in at least ${pages.MIN_NOTE_CHARS} characters, so whoever applies it again knows what to do. Nothing was sent.`,
+        });
+      }
+      const lifecycle = decisionPortOrFail(res, 'sendBackHeldTweak');
+      if (!lifecycle) return;
+      const waiting = await waitingRoundOrFail(res, lifecycle, pageId, req.body || {}, openRoundOf);
+      if (!waiting) return;
+      const { round } = waiting;
+      const at = new Date().toISOString();
+      const by = String(req.builder.id);
+      const r = await lifecycle.sendBackHeldTweak({
+        taskId: round.id,
+        builderId: req.builder.id,
+        compose: (task) => pages.appendSentBack(task.description, { at, by, note: note.note }),
+      });
+      if (r.outcome !== 'sent_back') return refuseDecision(res, pageId, r);
+      const crafts = typeof lifecycle.builderCrafts === 'function' ? await lifecycle.builderCrafts(req.builder.id) : [];
+      return res.json({
+        ok: true,
+        outcome: 'sent_back',
+        page_id: pageId,
+        round: { task_id: String(r.task.id), state: 'submitted', status: r.task.status },
+        sent_back: { at, by, note: note.note },
+        pr: r.pr || null,
+        next: await nextWaiting(lifecycle, inv.data, req.builder.id, crafts),
+      });
+    } catch (err) {
+      log.error({ err }, 'POST /copy-desk/pages/:pageId/send-back failed');
+      if (!res.headersSent) res.fail('copy_page_send_back_failed', 500);
+    }
+  });
+
   return router;
 };