@bongos/core 1.23.14 → 1.23.16

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

@@ -29,11 +29,12 @@ 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') {
+  // task 1004900: a submitted batch whose words wait for review is decided here too.
+  if (!round || (state !== 'waiting_for_artist' && state !== 'words_review')) {
     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.',
+      what_this_means: 'This page is not waiting for approval. Only submitted words, or a page that has been applied and checked, can be approved or sent back.',
     });
     return null;
   }
@@ -45,7 +46,34 @@ async function waitingRoundOrFail(res, lifecycle, pageId, body, openRoundOf) {
     });
     return null;
   }
-  return { round, rounds };
+  return { round, rounds, state };
+}
+
+// The WORDS decision (task 1004900): a submitted batch approved, so it joins
+// the /tweak queue, or sent back with a note, so the batch is withdrawn and the
+// round is a draft its artist can change and submit again. Answers the route
+// itself; nothing is applied, rendered or landed here.
+async function decideWords(res, lifecycle, { pageId, round, builderId, kind, note, invData }) {
+  if (typeof lifecycle.decideTweakWords !== 'function') {
+    return res.fail('lifecycle_unavailable', 503, { what_this_means: 'This instance cannot record a decision on submitted words. Nothing was decided.' });
+  }
+  const at = new Date().toISOString();
+  const by = String(builderId);
+  const compose = kind === 'approve'
+    ? (t) => pages.approveWords(t.description, { at, by })
+    : (t) => pages.sendBackWords(t.description, { at, by, note });
+  const r = await lifecycle.decideTweakWords({ taskId: round.id, builderId, compose });
+  if (r.outcome === 'round_moved') return refuseDecision(res, pageId, { outcome: 'not_waiting' });
+  if (r.outcome !== 'decided') return refuseDecision(res, pageId, r);
+  const crafts = typeof lifecycle.builderCrafts === 'function' ? await lifecycle.builderCrafts(builderId) : [];
+  return res.json({
+    ok: true,
+    outcome: kind === 'approve' ? 'words_approved' : 'words_sent_back',
+    page_id: pageId,
+    round: { task_id: String(r.task.id), state: kind === 'approve' ? 'submitted' : 'draft', status: r.task.status },
+    ...(kind === 'approve' ? {} : { sent_back: { at, by, note } }),
+    next: await nextWaiting(lifecycle, invData, builderId, crafts),
+  });
 }
 
 // The port's refusals, as the panel shows them.
@@ -80,4 +108,4 @@ async function nextWaiting(lifecycle, invData, builderId, crafts) {
   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 = { openRoundOf, waitingRoundOrFail, refuseDecision, nextWaiting };
+module.exports = { openRoundOf, waitingRoundOrFail, refuseDecision, nextWaiting, decideWords };

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

@@ -184,10 +184,12 @@ function roundState(round) {
       return round.holder_worktree ? 'applying' : 'writing';
     case 'ready':
       if (p.batch) {
-        // submitted = a batch, and no applied block newer than the latest
-        // send-back. A sent-back round reads submitted again (the mock's
-        // "it comes back to the queue once it is re-applied").
-        if (!p.applied) return 'submitted';
+        // submitted = a batch whose WORDS were approved (task 1004900), and no
+        // applied block newer than the latest send-back. A sent-back round reads
+        // submitted again (the mock's "it comes back to the queue once it is
+        // re-applied"). A batch nobody has approved yet is words_review: it is
+        // not in the /tweak queue until its words are approved.
+        if (!p.applied) return p.words_approved ? 'submitted' : 'words_review';
         if (p.last_sent_back_at && (!p.applied_at || p.applied_at <= p.last_sent_back_at)) return 'submitted';
         return 'unknown';
       }
@@ -313,14 +315,15 @@ const DAY_MS = 24 * 60 * 60 * 1000;
 const IN_FLIGHT = Object.freeze({
   draft: { word: 'Being written', stuck_after: null },
   writing: { word: 'Being written', stuck_after: null },
-  submitted: { word: 'Submitted, waiting to be applied', stuck_after: 3 * DAY_MS },
+  words_review: { word: 'Words waiting for review', stuck_after: 3 * DAY_MS },
+  submitted: { word: 'Approved, waiting to be applied', stuck_after: 3 * DAY_MS },
   applying: { word: 'Being applied', stuck_after: DAY_MS },
   // task 1004777: a review left 3 days is stuck too, so its artist is told on Home.
   waiting_for_artist: { word: 'Waiting for your review', stuck_after: 3 * DAY_MS },
   landing: { word: 'Approved, going live', stuck_after: DAY_MS },
   unknown: { word: 'Needs to be reviewed', stuck_after: 0 },
 });
-const IN_FLIGHT_ORDER = ['unknown', 'landing', 'applying', 'submitted', 'waiting_for_artist', 'writing', 'draft'];
+const IN_FLIGHT_ORDER = ['unknown', 'landing', 'applying', 'submitted', 'waiting_for_artist', 'words_review', 'writing', 'draft'];
 
 function inFlightFor(list, byPage, nowMs) {
   const out = [];
@@ -377,7 +380,8 @@ function stuckPageTweaks({ inventory, tasks, now = Date.now() }) {
       state_word: f.state_word,
       since: f.since,
       days: ms == null ? null : Math.max(0, Math.floor(ms / DAY_MS)),
-      waits_on: f.state === 'waiting_for_artist' ? 'artist' : 'appliers',
+      // Submitted words (task 1004900) wait on their artist's review, like an applied page.
+      waits_on: f.state === 'waiting_for_artist' || f.state === 'words_review' ? 'artist' : 'appliers',
       artist_id: f.artist_id,
     };
   });
@@ -814,6 +818,10 @@ function approvalFor({ page, pageId, rounds, round, builderId, isArtist }) {
     round: round.round,
     status: round.status,
     state: roundState(round),
+    // task 1004900: 'words' is a batch whose words are reviewed BEFORE it is
+    // applied (no render yet); 'applied' is the applied page held for its artist.
+    kind: roundState(round) === 'words_review' ? 'words' : 'applied',
+    submitted_at: batch.ok ? iso(batch.batch.submitted_at) : null,
     applied_at: appliedAtOf(round),
     line_count: lines.length,
     applied_count: lines.filter((l) => !l.refused).length,
@@ -873,14 +881,15 @@ function composeApprovals({ inventory, tasks, builderId, crafts, now = Date.now(
   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;
+    const st = round ? roundState(round) : null;
+    if (st !== 'waiting_for_artist' && st !== 'words_review') 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;
+    const at = (a.applied_at || a.submitted_at) ? Date.parse(a.applied_at || a.submitted_at) : Infinity;
+    const bt = (b.applied_at || b.submitted_at) ? Date.parse(b.applied_at || b.submitted_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; });

package/modules/copy-desk/pages.js

@@ -11,6 +11,9 @@
 //   ```page-tweak-applied    what the applying session landed (TW11); its
 //                            lines_after is the baseline drift is measured from
 //   ```page-tweak-sent-back  one per send-back, appended, never replaced (TW12)
+//   ```page-tweak-words-approved  the batch's words approved BEFORE it is
+//                            applied (task 1004900); only an approved batch is
+//                            in the /tweak queue
 //
 // TW05 (task 1004316) is the first reader, so it lands the format whole: the
 // status, changelog and drift reads parse all four, and the later links write
@@ -30,6 +33,7 @@ const FENCES = Object.freeze({
   batch: 'page-tweak',
   applied: 'page-tweak-applied',
   sentBack: 'page-tweak-sent-back',
+  wordsApproved: 'page-tweak-words-approved',
 });
 
 // The page id shape the inventory's generator enforces: <surface>:<page>, both
@@ -202,11 +206,30 @@ function parseSentBackBlocks(markdown) {
   return out;
 }
 
+// The words of a frozen batch approved before it is applied (task 1004900). It
+// APPENDS like a send-back; a send-back of the words withdraws the batch and
+// every approval with it, so an approval always speaks for the batch beside it.
+function composeWordsApprovedBlock(a) {
+  return fenceBlock(FENCES.wordsApproved, { at: a.at, by: a.by });
+}
+
+function parseWordsApprovedBlocks(markdown) {
+  const out = [];
+  for (const raw of findBlocks(markdown, FENCES.wordsApproved)) {
+    try {
+      const v = JSON.parse(raw);
+      if (v && typeof v.at === 'string') out.push({ at: v.at, by: v.by == null ? null : v.by });
+    } catch { /* an unreadable approval is skipped, never read as one */ }
+  }
+  return out;
+}
+
 // Which blocks a description carries, without failing on any one of them. The
 // round-state derivation (ADR 0341 D7) reads presence and times, not contents.
 function blockPresence(markdown) {
   const sent = parseSentBackBlocks(markdown);
   const applied = parseAppliedBlock(markdown);
+  const approved = parseWordsApprovedBlocks(markdown);
   return {
     draft: findBlocks(markdown, FENCES.draft).length > 0,
     batch: findBlocks(markdown, FENCES.batch).length > 0,
@@ -214,6 +237,8 @@ function blockPresence(markdown) {
     applied_at: applied.ok ? (applied.applied.applied_at || null) : null,
     sent_back_count: sent.length,
     last_sent_back_at: sent.length ? sent.map((s) => s.at).sort().pop() : null,
+    words_approved: approved.length > 0,
+    words_approved_at: approved.length ? approved.map((a) => a.at).sort().pop() : null,
   };
 }
 
@@ -494,6 +519,38 @@ function appendSentBack(description, { at, by, note }) {
   return { ok: true, description: src.trimEnd() + (src.trim() ? '\n\n' : '') + composeSentBackBlock({ at, by, note }) };
 }
 
+// ---------------------------------------------------------------------------
+// Reviewing the words before they are applied (task 1004900).
+//
+// A submitted batch waits for its words to be approved; only then does /tweak
+// (or the runner) apply it. Approving appends an approval block. Sending the
+// words back takes the batch (and any approval) out again and appends the
+// note, so the round reads as a draft its artist can change and submit again:
+// the draft block was never removed by the submit.
+// ---------------------------------------------------------------------------
+
+function stripBlocks(description, fence) {
+  const re = new RegExp('\\n*```' + fence.replace(/-/g, '\\-') + '[ \\t]*\\r?\\n[\\s\\S]*?\\r?\\n```', 'g');
+  return String(description || '').replace(re, '');
+}
+
+function approveWords(description, { at, by }) {
+  const p = blockPresence(description);
+  if (!p.batch) return fail('no_batch');
+  if (p.words_approved) return fail('already_approved');
+  const src = String(description || '');
+  return { ok: true, description: src.trimEnd() + '\n\n' + composeWordsApprovedBlock({ at, by }) };
+}
+
+function sendBackWords(description, { at, by, note }) {
+  const p = blockPresence(description);
+  if (!p.batch) return fail('no_batch');
+  if (p.words_approved) return fail('already_approved');
+  if (p.applied) return fail('already_applied');
+  const withdrawn = stripBlocks(stripBlocks(description, FENCES.batch), FENCES.wordsApproved);
+  return appendSentBack(withdrawn, { at, by, note });
+}
+
 module.exports = {
   SCHEMA,
   SOURCE,
@@ -516,6 +573,10 @@ module.exports = {
   MAX_NOTE_CHARS,
   normalizeSentBackNote,
   appendSentBack,
+  composeWordsApprovedBlock,
+  parseWordsApprovedBlocks,
+  approveWords,
+  sendBackWords,
   blockPresence,
   roundOpenForWriting,
   MAX_LINE_CHARS,

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

@@ -62,7 +62,7 @@ const pageStatus = require('../page-status');
 const pages = require('../pages');
 const guarded = require('../guarded-lines');
 const docx = require('../docx');
-const { openRoundOf, waitingRoundOrFail, refuseDecision, nextWaiting } = require('../page-decisions');
+const { openRoundOf, waitingRoundOrFail, refuseDecision, nextWaiting, decideWords } = require('../page-decisions');
 const { tallyCreditRows, readArtistStats } = require('../artist-stats');
 
 const { validateOrRespond } = api;
@@ -220,7 +220,7 @@ function alreadySubmitted(round, builderId, pageId) {
   if (!b.ok) return null;
   return {
     ok: true, outcome: 'already_submitted', page_id: pageId,
-    round: { task_id: String(round.id), state: 'submitted', status: 'ready' },
+    round: { task_id: String(round.id), state: pageStatus.roundState(round), status: 'ready' },
     batch: { line_count: b.batch.lines.length, submitted_at: b.batch.submitted_at, reading_hash: b.batch.reading_hash },
     unplaced_tasks: (b.batch.unplaced_tasks || []).map((id) => ({ task_id: String(id) })),
     warnings: b.batch.warnings || [],
@@ -1319,7 +1319,7 @@ module.exports = function buildCopyDeskRouter() {
         case 'submitted':
           return res.json({
             ok: true, outcome: 'submitted', page_id: pageId,
-            round: { task_id: String(r.task.id), state: 'submitted', status: r.task.status },
+            round: { task_id: String(r.task.id), state: 'words_review', status: r.task.status },
             batch: { line_count: frozen.batch.lines.length, submitted_at: submittedAt, reading_hash: frozen.batch.reading_hash },
             warnings: frozen.batch.warnings || [],
             unplaced_tasks: r.unplaced_tasks.map((u) => ({ task_id: u.id, key: u.key, created: u.created })),
@@ -1354,6 +1354,8 @@ module.exports = function buildCopyDeskRouter() {
   // 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.
+  // task 1004900: a submitted batch's WORDS are decided here first, before it
+  // is applied (approve: into the /tweak queue; send back: a draft again).
   // -------------------------------------------------------------------------
 
   // GET /copy-desk/approvals — every round waiting for its artist, oldest
@@ -1407,6 +1409,7 @@ module.exports = function buildCopyDeskRouter() {
       const waiting = await waitingRoundOrFail(res, lifecycle, pageId, req.body || {}, openRoundOf);
       if (!waiting) return;
       const { round } = waiting;
+      if (waiting.state === 'words_review') return decideWords(res, lifecycle, { pageId, round, builderId: req.builder.id, kind: 'approve', invData: inv.data });
       // 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;
@@ -1459,6 +1462,7 @@ module.exports = function buildCopyDeskRouter() {
       const waiting = await waitingRoundOrFail(res, lifecycle, pageId, req.body || {}, openRoundOf);
       if (!waiting) return;
       const { round } = waiting;
+      if (waiting.state === 'words_review') return decideWords(res, lifecycle, { pageId, round, builderId: req.builder.id, kind: 'send_back', note: note.note, invData: inv.data });
       const at = new Date().toISOString();
       const by = String(req.builder.id);
       const r = await lifecycle.sendBackHeldTweak({

package/modules/copy-desk/skills/tweak/SKILL.md

@@ -19,7 +19,7 @@ You are applying ONE page an artist rewrote in the studio (Tweak Mode, ADR 0341)
 node scripts/bongos/api.js GET /api/bongos/copy-desk/pages --quiet
 ```
 
-A round is in the queue when its page's `open_round.state` is `submitted`. Take the one with the lowest `open_round.task_id` (the oldest). None? Say "the tweak queue is empty" and stop.
+A round is in the queue when its page's `open_round.state` is `submitted`: its words have been approved in the studio (task 1004900). A round whose words still wait for review reads `words_review` and is not yours to apply. Take the one with the lowest `open_round.task_id` (the oldest). None? Say "the tweak queue is empty" and stop.
 
 Claim it in THIS worktree, on a fresh branch from `origin/main`:
 

package/modules/copy-desk/tests/copy_page_next.mjs

@@ -110,7 +110,7 @@ await test('held and in-flight pages are never recommended, and are named in ski
   assert.ok(!order(out).includes('landing:about'), 'submitted: in flight');
   assert.deepEqual(out.skipped.map((s) => [s.page_id, s.reason]), [['builders:studio', 'page_held'], ['landing:about', 'page_in_flight']]);
   assert.deepEqual(out.skipped[0].holder, { id: F.BOB.id, login: 'bob' });
-  assert.equal(out.skipped[1].state, 'submitted');
+  assert.equal(out.skipped[1].state, 'words_review');
   assert.equal(out.resume, null);
 });
 

package/modules/copy-desk/tests/copy_page_status.mjs

@@ -193,7 +193,10 @@ await test('every row of the D7 state table', () => {
     [{ status: 'active', holder_id: '7', holder_worktree: false }, 'writing'],
     [{ status: 'active', holder_id: '7', holder_worktree: true }, 'applying'],
     [{ status: 'ready', description: draft }, 'draft'],
-    [{ status: 'ready', description: batch }, 'submitted'],
+    [{ status: 'ready', description: batch }, 'words_review'],
+    [{ status: 'ready', description: `${batch}
+
+${pages.composeWordsApprovedBlock({ at: 't2', by: '7' })}` }, 'submitted'],
     [{ status: 'ready', description: sentBackAfterApply }, 'submitted'],
     [{ status: 'ready', description: applied }, 'unknown'],
     [{ status: 'completed', grade_passed: true }, 'waiting_for_artist'],
@@ -245,7 +248,9 @@ await test('in_flight: every open round, its plain state, how long, and stuck wh
   const pg = (id) => ({ id, surface: id.split(':')[0], title: id, path: '/', files: [] });
   const ids = ['landing:a', 'landing:b', 'landing:c', 'builders:d', 'builders:e', 'builders:f', 'builders:g', 'status:h'];
   const inventory = { surfaces: [{ id: 'landing' }, { id: 'builders' }, { id: 'status' }], pages: ids.map(pg) };
-  const batch = (id) => pages.composeBatchBlock({ page_id: id, reading_hash: 'h', submitted_at: ago(9), lines: [] });
+  const batch = (id) => `${pages.composeBatchBlock({ page_id: id, reading_hash: 'h', submitted_at: ago(9), lines: [] })}
+
+${pages.composeWordsApprovedBlock({ at: ago(9), by: '7' })}`;
   const round = (n, id, extra) => ({ id: String(n), source: 'page-tweak', source_ref: pages.roundSourceRef(id, 1), description: pages.roundTaskBody(pg(id), 1), ...extra });
   const tasks = [
     round(1, 'landing:a', { status: 'ready', description: `${pages.roundTaskBody(pg('landing:a'), 1)}\n\n${batch('landing:a')}`, updated_at: ago(9) }),
@@ -262,9 +267,9 @@ await test('in_flight: every open round, its plain state, how long, and stuck wh
     ['builders:f', 'unknown', 'Needs to be reviewed', true],
     ['landing:c', 'landing', 'Approved, going live', true],
     ['status:h', 'applying', 'Being applied', true],
-    ['landing:a', 'submitted', 'Submitted, waiting to be applied', true],
+    ['landing:a', 'submitted', 'Approved, waiting to be applied', true],
     ['builders:d', 'waiting_for_artist', 'Waiting for your review', true],
-    ['landing:b', 'submitted', 'Submitted, waiting to be applied', false],
+    ['landing:b', 'submitted', 'Approved, waiting to be applied', false],
     ['builders:e', 'writing', 'Being written', false],
   ], 'a shipped round is not in flight; writing is never stuck, and a review left 20 days is (task 1004777)');
   assert.equal(out.in_flight[1].since, ago(17));

package/modules/hall-ui/public/approval-queue-lib.js

@@ -83,6 +83,8 @@
   // there are any ("· 1 not applied").
   function subLine(item) {
     if (!item) return '';
+    // task 1004900: words reviewed before they are applied.
+    if (item.kind === 'words') return `· ${[item.surface_word || item.surface || '', `${plural(item.line_count, 'line', 'lines')} rewritten, not applied yet`].filter(Boolean).join(' · ')}`;
     const parts = [item.surface_word || item.surface || '', `${plural(item.applied_count, 'line', 'lines')} rewritten, applied`];
     if (item.refused_count > 0) parts.push(`${item.refused_count} not applied`);
     return `· ${parts.filter(Boolean).join(' · ')}`;
@@ -92,7 +94,7 @@
   function doorDetail(count) {
     if (count == null) return 'tweaks waiting for your sign-off';
     if (count === 0) return 'nothing waiting for you';
-    return `${plural(count, 'page', 'pages')} applied, waiting for you`;
+    return `${plural(count, 'page', 'pages')} waiting for you`;
   }
 
   // Why a line was not applied, in words (copy-apply.js's refusals).
@@ -140,7 +142,7 @@
       task_id: String(r.task_id),
       title: displayTitle(r),
       mark: 'not applied yet',
-      line: `${r.state_word}${waited ? ` · waiting ${waited}` : ''}. The words are waiting to be applied, so there is nothing to approve yet.`,
+      line: `${r.state_word}${waited ? ` · waiting ${waited}` : ''}. The words are approved and waiting to be put on the page.`,
     };
   }
 
@@ -156,6 +158,10 @@
   // server's re-read of the queue.
   function approvedLine(item, resp) {
     const name = displayTitle(item);
+    if (item && item.kind === 'words') {
+      const nxt = resp && resp.next && resp.next.page ? displayTitle(resp.next.page) : null;
+      return [`Words approved. ${name} will be updated on its own, and it ships once the update is checked.`, nxt ? `Next in the queue: ${nxt}.` : 'Nothing else is waiting.'].join(' ');
+    }
     const status = resp && resp.status_after ? resp.status_after.charAt(0).toLowerCase() + resp.status_after.slice(1) : null;
     const next = resp && resp.next && resp.next.page ? displayTitle(resp.next.page) : null;
     return [
@@ -164,7 +170,8 @@
     ].join(' ');
   }
 
-  function sentBackLine() {
+  function sentBackLine(item) {
+    if (item && item.kind === 'words') return 'Sent back with your note. The page is a draft again, so its writer can change the words and submit them.';
     return 'Sent back with your note. It comes back to the queue once it is re-applied.';
   }
 

package/modules/hall-ui/public/approval-queue.js

@@ -172,7 +172,7 @@
       if (!item.can_decide) {
         return '<div class="aq-foot"><p class="aq-sealed">Only the artist who wrote this page, or another artist, can approve it or send it back.</p><span class="aq-hint">highlighted: the words you changed</span></div>';
       }
-      const approve = `<button type="button" class="aq-accent" data-approve${state.busy ? ' disabled' : ''}>Approve and ship</button>`;
+      const approve = `<button type="button" class="aq-accent" data-approve${state.busy ? ' disabled' : ''}>${item.kind === 'words' ? 'Approve the words' : 'Approve and ship'}</button>`;
       const note = state.noteOpen
         ? `<div class="aq-note">
             <label for="aq-note" class="aq-sr">What needs changing</label>
@@ -187,6 +187,8 @@
     // The page as the artist would see it: closed until asked for, because a
     // picture that may not exist is no way to open a decision.
     function peekHtml(item) {
+      // task 1004900: submitted words have no page render yet.
+      if (item.kind === 'words') return '<p class="aq-frame__note">Not on the page yet. Once you approve the words, the page is updated and checked on its own.</p>';
       if (!state.peek) {
         return '<div class="aq-peek"><button type="button" class="aq-ghost aq-ghost--small" data-peek aria-expanded="false">See it on the page</button></div>';
       }
@@ -207,8 +209,8 @@
     function notAppliedHtml() {
       const rows = (state.notApplied || []).map((r) => L.notAppliedRow(r));
       if (!rows.length) return '';
-      return `<section class="aq-pending" aria-label="Submitted, not applied yet">
-          <h3 class="aq-pending__h">Submitted, not applied yet (${rows.length})</h3>
+      return `<section class="aq-pending" aria-label="Approved, not applied yet">
+          <h3 class="aq-pending__h">Approved, not applied yet (${rows.length})</h3>
           <ul class="aq-pending__list">${rows.map((r) => `
             <li class="aq-pending__row" data-task="${esc(r.task_id)}"><span class="aq-pending__title">${esc(r.title)}</span> <span class="aq-pending__mark">${esc(r.mark)}</span><span class="aq-pending__line">${esc(r.line)}</span></li>`).join('')}</ul>
         </section>`;
@@ -221,7 +223,7 @@
       const item = current();
       const close = '<button type="button" class="aq-close" data-close>close</button>';
       if (!item) {
-        const words = state.loadError || (state.loaded ? 'Nothing is waiting for you. A page shows up here once its tweaks have been applied and checked.' : 'Opening the Approval queue…');
+        const words = state.loadError || (state.loaded ? 'Nothing is waiting for you. A page shows up here when its words are submitted, and again once they have been applied and checked.' : 'Opening the Approval queue…');
         dialog.innerHTML = `
           <div class="aq-head"><span class="aq-eyebrow">approval queue</span><h2 class="aq-title" id="aq-title">${state.loaded ? 'Nothing waiting' : 'Approval queue'}</h2><span class="aq-head__gap"></span>${close}</div>
           <div class="aq-body aq-body--empty"><div class="aq-frame"><p class="aq-frame__note">${esc(words)}</p></div></div>
@@ -271,7 +273,7 @@
           state.error = errWords(res.data, 'That could not be recorded. Nothing changed.');
           return;
         }
-        state.outcome.set(item.task_id, { kind, line: kind === 'approved' ? L.approvedLine(item, res.data) : L.sentBackLine() });
+        state.outcome.set(item.task_id, { kind, line: kind === 'approved' ? L.approvedLine(item, res.data) : L.sentBackLine(item) });
         state.noteOpen = false;
         tellCount();
       } catch (_) {

package/modules/hall-ui/public/studio-lib.js

@@ -167,8 +167,9 @@
         state: p.state_word || 'Needs to be reviewed',
         age,
         stuck: !!p.stuck,
-        // A page waiting on a sign-off opens its approval card.
-        review: p.state === 'waiting_for_artist',
+        // A page waiting on a sign-off opens its approval card: its submitted
+        // words (task 1004900) or its applied page.
+        review: p.state === 'waiting_for_artist' || p.state === 'words_review',
         // A round the reads cannot name has no action of its own: the row offers
         // a release (task 1004837). task_id pins the round the viewer looked at.
         release: p.state === 'unknown',

package/modules/lifecycle/lifecycle.js

@@ -136,6 +136,8 @@ module.exports = {
   approveHeldTweak: (...a) => pageTweakApprove.approveHeldTweak(...a),
   sendBackHeldTweak: (...a) => pageTweakApprove.sendBackHeldTweak(...a),
   releaseStuckTweak: (...a) => pageTweakApprove.releaseStuckTweak(...a),
+  // task 1004900: approve or send back a submitted batch's WORDS before it is applied.
+  decideTweakWords: (...a) => pageTweakApprove.decideTweakWords(...a),
   // A builder's crafts (help-requests' reader, from builders.preferred_disciplines),
   // so the queue read can say whether the caller may decide before they try.
   builderCrafts: (...a) => helpRequests.craftsForBuilder(...a),

package/modules/lifecycle/page-tweak-approve.js

@@ -94,6 +94,14 @@ async function lockWaitingRound(client, { taskId, builderId }) {
   if (!hold.isHeldForArtist(task, grade ? grade.passed : null)) {
     return { outcome: 'not_waiting', task, grade_passed: grade ? grade.passed : null };
   }
+  const who = await deciderOf(client, { taskId, builderId, task });
+  if (who.outcome) return who;
+  return { task, grade, authorId: who.authorId };
+}
+
+// May this builder decide the round? Its author (latest web claim) or any
+// artist; an inactive builder never. Returns { authorId } or an outcome.
+async function deciderOf(client, { taskId, builderId, task }) {
   const { rows: b } = await client.query(
     'SELECT id, status, github_login, display_name FROM builders WHERE id = $1', [builderId]
   );
@@ -109,7 +117,7 @@ async function lockWaitingRound(client, { taskId, builderId }) {
     const crafts = await helpRequests.craftsForBuilder(builderId, { pool: client });
     if (!crafts.includes('artist')) return { outcome: 'not_an_artist', task, author_id: authorId };
   }
-  return { task, grade, authorId };
+  return { authorId };
 }
 
 async function inTx(deps, body) {
@@ -323,4 +331,44 @@ async function releaseStuckTweak({ taskId, builderId, expectedStatus, compose =
   return out;
 }
 
-module.exports = { approveHeldTweak, sendBackHeldTweak, releaseStuckTweak };
+// decideTweakWords({ taskId, builderId, compose }, deps)   (task 1004900)
+//
+// The review of a submitted batch's WORDS, before anything is applied. The
+// round must be a `ready` page tweak nobody holds (a held one is being
+// written or applied: round_moved); the same author-or-artist rule as the
+// other two decisions. copy-desk's compose says what the decision writes (an
+// approval block, or the batch withdrawn with a send-back note) and refuses a
+// round that is not under word review. Only the description changes: the task
+// stays `ready`, so an approved round is in the /tweak queue and a sent-back
+// one is a draft again. No PR exists yet, so none is touched.
+// Outcomes: decided | not_found | wrong_source | round_moved | not_an_artist |
+// builder_inactive | refused
+async function decideTweakWords({ taskId, builderId, compose }, deps = {}) {
+  const out = await inTx(deps, async (client) => {
+    const { rows } = await client.query(
+      `SELECT id, status, title, description, source, source_ref, version_id, goal_id, touches
+         FROM tasks WHERE id = $1 FOR UPDATE`,
+      [taskId]
+    );
+    const task = rows[0];
+    if (!task) return { outcome: 'not_found' };
+    if (!hold.isPageTweak(task)) return { outcome: 'wrong_source', task };
+    if (task.status !== 'ready') return { outcome: 'round_moved', task };
+    const { rows: open } = await client.query('SELECT id FROM claims WHERE task_id = $1 AND released_at IS NULL LIMIT 1', [taskId]);
+    if (open.length) return { outcome: 'round_moved', task };
+    const who = await deciderOf(client, { taskId, builderId, task });
+    if (who.outcome) return who;
+    const r = compose(task);
+    if (!r || !r.ok) return { outcome: 'refused', refusal: r, task };
+    const { rows: updated } = await client.query(
+      `UPDATE tasks SET description = $2, updated_at = now() WHERE id = $1
+       RETURNING id, status, description, source_ref, updated_at`,
+      [taskId, r.description]
+    );
+    return { commit: true, outcome: 'decided', task: updated[0], author_id: who.authorId };
+  });
+  delete out.commit;
+  return out;
+}
+
+module.exports = { approveHeldTweak, sendBackHeldTweak, releaseStuckTweak, decideTweakWords };