@bongos/core 1.19.1058 → 1.19.1060

package/modules/copy-desk/flags.js

@@ -28,7 +28,12 @@ const { pool } = require('../../src/module-api');
 // Mirrors of the DB CHECK constraints — enforced here first so a bad payload
 // gets a clean, named 400 instead of a raw constraint violation surfacing as a
 // 500. The DB stays the backstop; this is the error message.
-const SCOPES = Object.freeze(['string', 'surface']);
+// SCOPES mirrors the DB CHECK (widened by copy_desk_002_page_asks.sql). A
+// 'page' row is a PAGE ASK (ADR 0341 D6) and is filed only through
+// POST /copy-desk/pages/:pageId/asks, so the flag route takes FLAG_SCOPES.
+const SCOPES = Object.freeze(['string', 'surface', 'page']);
+const FLAG_SCOPES = Object.freeze(['string', 'surface']);
+const PAGE_SCOPE = 'page';
 const STATUSES = Object.freeze(['open', 'resolved', 'dismissed']);
 const KINDS = Object.freeze(['slop', 'off-voice', 'stale', 'unclear', 'duplicate', 'typo', 'other']);
 // The closing verdicts a person can apply to an open flag. 'open' is not among
@@ -65,7 +70,11 @@ function normalizeFlagPayload(body, registryIndex, registryHelpers) {
   const b = body || {};
 
   const scope = String(b.scope || 'string');
-  if (!SCOPES.includes(scope)) return fail('bad_scope', { allowed: SCOPES });
+  if (!FLAG_SCOPES.includes(scope)) {
+    return fail('bad_scope', scope === PAGE_SCOPE
+      ? { allowed: FLAG_SCOPES, why: 'A page is asked for at POST /copy-desk/pages/:pageId/asks.' }
+      : { allowed: FLAG_SCOPES });
+  }
 
   const surface = String(b.surface || '');
   if (!surface) return fail('surface_required');
@@ -155,6 +164,31 @@ function normalizeResolution(body) {
   return { ok: true, value: { status, resolution_note: note, resolved_task_id: taskId } };
 }
 
+// Validate a PAGE ASK (task 1004317 / TW06, ADR 0341 D6). PURE. The page id is
+// the route's, already checked against the inventory; the body carries only the
+// reason, held to the flag's own floor. `surface` carries the page id too: that
+// is what makes 001's one-open-flag-per-target index mean one open ask per
+// (builder, page) — see copy_desk_002_page_asks.sql.
+function normalizePageAsk(body, pageId) {
+  const b = body || {};
+  const reason = tidy(b.reason);
+  if (reason.length < MIN_REASON_CHARS) {
+    return fail('reason_too_thin', {
+      min_chars: MIN_REASON_CHARS,
+      got: reason.length,
+      why: 'An ask tells an artist why this page, before the others. One line is enough; a word is not.',
+    });
+  }
+  if (reason.length > MAX_REASON_CHARS) return fail('reason_too_long', { max_chars: MAX_REASON_CHARS });
+  return {
+    ok: true,
+    value: {
+      scope: PAGE_SCOPE, surface: pageId, page_id: pageId, string_id: null, reason, kind: 'other',
+      text_at_flag: null, file_at_flag: null, line_at_flag: null, registry_schema: null,
+    },
+  };
+}
+
 // ---------------------------------------------------------------------------
 // SQL. Thin by design — the rules live above and in the migration's constraints.
 // ---------------------------------------------------------------------------
@@ -165,7 +199,7 @@ function normalizeResolution(body) {
 // shape, which is what lets the hall render an insert response and a queue row
 // with one function.
 const FLAG_COL_NAMES = Object.freeze([
-  'id', 'scope', 'surface', 'string_id', 'reason', 'kind',
+  'id', 'scope', 'surface', 'string_id', 'page_id', 'reason', 'kind',
   'text_at_flag', 'file_at_flag', 'line_at_flag', 'registry_schema',
   'flagged_by', 'flagged_at', 'status', 'resolution_note',
   'resolved_task_id', 'resolved_by', 'resolved_at',
@@ -176,11 +210,11 @@ const FLAG_COLS_BARE = FLAG_COL_NAMES.join(', ');
 async function insertFlag(value, builderId) {
   const { rows } = await pool.query(
     `INSERT INTO copy_desk_flags
-       (scope, surface, string_id, reason, kind, text_at_flag, file_at_flag, line_at_flag, registry_schema, flagged_by)
-     VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10)
+       (scope, surface, string_id, reason, kind, text_at_flag, file_at_flag, line_at_flag, registry_schema, flagged_by, page_id)
+     VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11)
      RETURNING ${FLAG_COLS_BARE}`,
     [value.scope, value.surface, value.string_id, value.reason, value.kind,
-      value.text_at_flag, value.file_at_flag, value.line_at_flag, value.registry_schema, builderId]
+      value.text_at_flag, value.file_at_flag, value.line_at_flag, value.registry_schema, builderId, value.page_id ?? null]
   );
   return rows[0];
 }
@@ -191,9 +225,12 @@ async function insertFlag(value, builderId) {
 //
 // Joined to builders for the display name: a flag is a judgement by a PERSON,
 // and an artist deciding how much weight to give it needs to know whose it is.
-async function listFlags({ status = 'open', surface = null, stringId = null, limit = 200 } = {}) {
+// `scopes` narrows by scope. The copy queue passes FLAG_SCOPES: page asks are
+// the recommendation's signal (TW07), not rows in the string queue.
+async function listFlags({ status = 'open', surface = null, stringId = null, scopes = null, limit = 200 } = {}) {
   const where = [];
   const args = [];
+  if (Array.isArray(scopes) && scopes.length) { args.push([...scopes]); where.push(`f.scope = ANY($${args.length}::text[])`); }
   if (status && status !== 'all') { args.push(status); where.push(`f.status = $${args.length}`); }
   if (surface) { args.push(surface); where.push(`f.surface = $${args.length}`); }
   if (stringId) { args.push(stringId); where.push(`f.string_id = $${args.length}`); }
@@ -238,8 +275,59 @@ async function closeFlag(id, value, builderId) {
   return rows[0] || null;
 }
 
+// The caller's OPEN ask on a page, if any: a second ask returns the first
+// (ADR 0341 D6), rather than a 409 the person has to read.
+async function findOpenPageAsk(pageId, builderId) {
+  const { rows } = await pool.query(
+    `SELECT ${FLAG_COLS} FROM copy_desk_flags f
+      WHERE f.scope = 'page' AND f.page_id = $1 AND f.flagged_by = $2 AND f.status = 'open'
+      ORDER BY f.id ASC LIMIT 1`,
+    [pageId, builderId]
+  );
+  return rows[0] || null;
+}
+
+// "N people asked for it": distinct askers among a page's OPEN asks.
+async function countPageAskers(pageId) {
+  const { rows } = await pool.query(
+    `SELECT COUNT(DISTINCT flagged_by)::int AS askers FROM copy_desk_flags
+      WHERE scope = 'page' AND page_id = $1 AND status = 'open'`,
+    [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.
+async function resolvePageAsks({ pageId, taskId, resolvedBy, shippedAt }) {
+  const { rows } = await pool.query(
+    `UPDATE copy_desk_flags
+        SET status = 'resolved', resolved_task_id = $2, resolved_by = $3, resolved_at = now(),
+            resolution_note = $5
+      WHERE scope = 'page' AND page_id = $1 AND status = 'open' AND flagged_at <= $4::timestamptz
+      RETURNING id`,
+    [pageId, taskId, resolvedBy, shippedAt, `Resolved by the page's tweak shipping (task ${taskId}).`]
+  );
+  return rows.map((r) => r.id);
+}
+
 module.exports = {
-  SCOPES, STATUSES, KINDS, CLOSING_STATUSES, MIN_REASON_CHARS, MAX_REASON_CHARS, MAX_NOTE_CHARS,
-  tidy, normalizeFlagPayload, normalizeResolution,
+  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, pageAskSummary, resolvePageAsks,
 };

package/modules/copy-desk/migrations/copy_desk_002_page_asks.sql

@@ -0,0 +1,62 @@
+-- copy_desk_002_page_asks.sql — the PAGE ASK: anyone asks for a whole page to be
+-- tweaked, with a one-line reason (task 1004317 / BV2.TW06, ADR 0341 D6).
+--
+-- WHAT CHANGES. copy_desk_flags gains a third scope, 'page', and a nullable
+-- `page_id` naming a page of the page inventory (docs/page-inventory.json,
+-- `<surface>:<page>`). A page ask IS a flag: it keeps the flag's reason floor
+-- (copy_desk_flags_reason_chk, untouched), its open / resolved / dismissed
+-- lifecycle and its closed-stamp rule. It is resolved when the page's next tweak
+-- ships (resolved_task_id = that tweak task), never auto-dismissed.
+--
+-- THE TARGET RULE. `string_id` is present exactly for scope 'string' and
+-- `page_id` exactly for scope 'page'. Both halves of each, as in 001: a page ask
+-- with no page points nowhere, and a string flag carrying a page would be a
+-- second target nobody reads.
+--
+-- WHY `surface` HOLDS THE PAGE ID ON A PAGE ASK. The one-open-flag-per-target
+-- index from 001 keys on (flagged_by, surface, COALESCE(string_id, '')). A page
+-- ask has no string_id, so if its surface were the page's surface ('builders')
+-- one builder could ask for only ONE page per surface: the second ask would
+-- collide with the first. Storing the page id there too makes the existing index
+-- mean "one open ask per (builder, page)", which is the rule ADR 0341 D6 wants,
+-- with no index dropped (a module migration stays additive). A page id always
+-- contains a ':' and a registry surface id never does, so a page ask can never
+-- collide with a surface flag. copy_desk_flags_page_surface_chk pins the pair.
+--
+-- NO LIVE CMS still holds (ADR 0178 §3): the one new column is a POINTER, a page
+-- id. Nothing here can hold replacement text; copy_no_cms.mjs lists page_id as
+-- the only text column this migration adds.
+--
+-- ADDITIVE, per ADR 0083 §Decision #5: the two CHECKs are dropped and re-added
+-- under the SAME names in this file (the widening shape the fitness gate
+-- allows), and existing rows all satisfy the new forms (they are 'string' or
+-- 'surface' rows with page_id NULL). Idempotent: safe to re-run.
+
+BEGIN;
+
+ALTER TABLE copy_desk_flags ADD COLUMN IF NOT EXISTS page_id text;
+
+ALTER TABLE copy_desk_flags DROP CONSTRAINT IF EXISTS copy_desk_flags_scope_chk;
+ALTER TABLE copy_desk_flags
+  ADD CONSTRAINT copy_desk_flags_scope_chk CHECK (scope IN ('string', 'surface', 'page'));
+
+ALTER TABLE copy_desk_flags DROP CONSTRAINT IF EXISTS copy_desk_flags_target_chk;
+ALTER TABLE copy_desk_flags
+  ADD CONSTRAINT copy_desk_flags_target_chk CHECK (
+    ((scope = 'string') = (string_id IS NOT NULL))
+    AND ((scope = 'page') = (page_id IS NOT NULL))
+  );
+
+ALTER TABLE copy_desk_flags DROP CONSTRAINT IF EXISTS copy_desk_flags_page_surface_chk;
+ALTER TABLE copy_desk_flags
+  ADD CONSTRAINT copy_desk_flags_page_surface_chk CHECK (scope <> 'page' OR surface = page_id);
+
+-- The recommendation's read (TW07): open asks per page, counted by distinct
+-- asker, oldest first.
+CREATE INDEX IF NOT EXISTS copy_desk_flags_page_open_idx
+  ON copy_desk_flags (page_id, flagged_at) WHERE scope = 'page' AND status = 'open';
+
+INSERT INTO schema_migrations (version) VALUES ('copy_desk_002_page_asks')
+  ON CONFLICT (version) DO NOTHING;
+
+COMMIT;

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/pages.js

@@ -52,6 +52,27 @@ function parseRoundRef(sourceRef) {
   return m ? { page_id: m[1], round: Number(m[2]) } : null;
 }
 
+// The round's task, as the claim route creates it (ADR 0341 D2; task 1004317 /
+// TW06). The title is `Tweak: <inventory title> (<page_id>)`. The body says what
+// the round is and where its words will rest; it carries NO wording and no block
+// yet, since the draft block is written by the autosave (TW08), never here.
+const ROUND_CREDITS = 30;
+
+function roundTaskTitle(page) {
+  const title = String((page && page.title) || (page && page.id) || '').trim();
+  return `Tweak: ${title} (${page.id})`;
+}
+
+function roundTaskBody(page, round) {
+  return [
+    `Page tweak round ${round} for **${String(page.title || page.id)}** (\`${page.id}\`${page.path ? `, ${page.path}` : ''}).`,
+    '',
+    'An artist rewrites every line of this page as one document in the studio. The draft rests in this description as a fenced `page-tweak-draft` block while they write, and is frozen into a `page-tweak` block when they submit. A session running `/tweak` then applies the batch, and the artist approves the rendered page before it ships (ADR 0341).',
+    '',
+    'This task was opened by the page claim (`POST /copy-desk/pages/:pageId/claim`). It is web-claimed by the artist while they write: there is no worktree until an applier claims it.',
+  ].join('\n');
+}
+
 // ---------------------------------------------------------------------------
 // Fences. A block is ```<fence>\n<json>\n```, and the fence name must be followed
 // by the end of its line: 'page-tweak' is a prefix of 'page-tweak-draft', so a
@@ -185,11 +206,23 @@ function blockPresence(markdown) {
   };
 }
 
+// May an artist's claim take over an UNHELD open round (ADR 0341 D5)? Only one
+// still being written: `ready`, with no frozen batch. That is the `draft` state
+// (released without submitting; the draft stays) and a round released before
+// any draft was saved. A round with a batch is `submitted`: it belongs to the
+// /tweak queue, and a writing claim would pull it back out of it.
+function roundOpenForWriting(task) {
+  return !!task && task.status === 'ready' && !blockPresence(task.description).batch;
+}
+
 module.exports = {
   SCHEMA,
   SOURCE,
   FENCES,
   PAGE_ID_RE,
+  ROUND_CREDITS,
+  roundTaskTitle,
+  roundTaskBody,
   roundSourceRef,
   parseRoundRef,
   composeDraftBlock,
@@ -201,4 +234,5 @@ module.exports = {
   composeSentBackBlock,
   parseSentBackBlocks,
   blockPresence,
+  roundOpenForWriting,
 };