@bongos/core 1.19.1062 → 1.19.1064

package/scripts/gds/copy-apply.js

@@ -30,7 +30,9 @@
 // arithmetic does not hold, or the file is outside a registry surface. None of
 // them means the wording was wrong — they mean a person should look.
 //
-// Run:  node scripts/gds/copy-apply.js                    (the task you are HOLDING — the normal call)
+// Run:  node scripts/gds/copy-apply.js --batch            (a PAGE TWEAK round you hold: every line, task 1004322)
+//       node scripts/gds/copy-apply.js --batch --batch-file round.md --dry-run   (a local round; writes nothing)
+//       node scripts/gds/copy-apply.js                    (the task you are HOLDING — the normal call)
 //       node scripts/gds/copy-apply.js --dry-run          (say what would change, write nothing)
 //       node scripts/gds/copy-apply.js --task 1234        (a claim you hold, when you hold more than one)
 //       node scripts/gds/copy-apply.js --patch-file p.json  (a local patch — used by the tests)
@@ -53,9 +55,12 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
+const { spawnSync } = require('node:child_process');
 
 const ci = require('./copy-inventory.js');
 const proposals = require('../../modules/copy-desk/proposals.js');
+// The page tweak format's one reader and writer (ADR 0341 D4), for --batch.
+const pages = require('../../modules/copy-desk/pages.js');
 const { apiCall, arg, hasFlag, cliExit } = require('./cli-lib.js');
 
 const REPO_ROOT = path.resolve(__dirname, '..', '..');
@@ -305,11 +310,275 @@ async function loadPatch({ taskId, patchFile }) {
   return { ok: true, patch: parsed.patch, task };
 }
 
+
+// ---------------------------------------------------------------------------
+// --batch: a whole PAGE at once (task 1004322 / BV2.TW11; ADR 0341 D4).
+//
+// A page tweak's round carries a ```page-tweak``` block: every line the artist
+// rewrote, frozen at submit, each with its reading key, its section, the text the
+// page showed (`before`), the artist's wording (`after`) and where the registry
+// placed it (`file`, `line`, `string_id`). --batch lands every line through the
+// SAME rules one proposal lands by (ADR 0233): the span is re-derived from the
+// tree as it stands, the `${expr}` holes go back in, and every doubt is a named
+// refusal. What is new is only that there are many lines, and so:
+//
+//   * A REFUSED LINE IS NAMED, NEVER SKIPPED. It goes in the applied block's
+//     `refused` list with its code, and the artist sees it at approval. The rest
+//     of the batch still lands (D4: "the batch lands with the lines that applied").
+//   * ORDER IS BY SOURCE POSITION, BOTTOM UP, per file. A rewrite can change how
+//     many lines a span covers, which would move every later line number; the
+//     line number is only ever a tie-breaker between duplicates, but applying from
+//     the bottom keeps even the tie-breaker true for every line still to come.
+//   * A READING LINE MAY BE PART OF A REGISTRY STRING. The page reader places a
+//     visible fragment on the registry row that contains it (a word inside a
+//     sentence built around a hole), so `before` is either the row's whole text
+//     or appears in it exactly once; the rewrite replaces that one occurrence.
+//     Anything else is `no_exact_span` (absent) or `ambiguous_target` (twice).
+//   * TWO LINES ON ONE STRING compose: the second is resolved against the text the
+//     first one left, never against the stale registry row.
+//
+// Then the command regenerates the registry, re-reads the changed pages
+// (page-reader.js --stale, which opens a browser) and writes the
+// ```page-tweak-applied``` block from the NEW reading: reading_hash_after and
+// lines_after (the page's non-shared lines, the baseline drift is measured from,
+// D8) plus the refused list.
+// ---------------------------------------------------------------------------
+
+const REFUSAL_CODES = Object.freeze(['target_gone', 'ambiguous_target', 'no_exact_span', 'placeholder_mismatch', 'path_outside_surface', 'unknown_surface', 'file_unreadable']);
+
+function countOccurrences(haystack, needle) {
+  if (!needle) return 0;
+  let n = 0;
+  for (let at = haystack.indexOf(needle); at !== -1; at = haystack.indexOf(needle, at + needle.length)) n += 1;
+  return n;
+}
+
+// Which registry row a batch line means. A string id is a hash of (surface,
+// text), so the same sentence in two files shares one id: the row in the line's
+// own file wins, the nearest to its line if that file has it twice. Pure.
+function registryRowFor(line, registryById) {
+  const rows = (line && line.string_id && registryById.get(line.string_id)) || [];
+  if (rows.length <= 1) return rows[0] || null;
+  const inFile = rows.filter((e) => e.file === line.file);
+  const pool = inFile.length ? inFile : rows;
+  if (pool.length === 1) return pool[0];
+  const near = (e) => Math.abs((e.line || 0) - (line.line || 0));
+  return pool.slice().sort((a, b) => near(a) - near(b))[0];
+}
+
+const rowKey = (e) => `${e.id}|${e.file}|${e.line}`;
+
+// One batch line -> the single-proposal patch shape (proposals.js), resolved
+// against the registry row its string_id names. `texts` carries a row's text as
+// earlier lines of this batch left it. Pure.
+function patchForBatchLine(line, registryById, texts = new Map()) {
+  const entry = registryRowFor(line, registryById);
+  if (!entry) {
+    return { ok: false, code: 'target_gone', detail: { string_id: line && line.string_id, what_this_means: 'The copy registry no longer has the string this line was placed on: the page changed after the artist submitted.' } };
+  }
+  const want = proposals.placeholderCount(line.before);
+  const got = proposals.placeholderCount(line.after);
+  if (want !== got) {
+    return { ok: false, code: 'placeholder_mismatch', detail: { expected: want, got, what_this_means: 'The rewrite does not keep the values the page drops into this line.' } };
+  }
+  const current = texts.has(rowKey(entry)) ? texts.get(rowKey(entry)) : entry.text;
+  let proposed;
+  if (current === line.before) proposed = line.after;
+  else {
+    const n = countOccurrences(current, line.before);
+    if (n === 0) return { ok: false, code: 'no_exact_span', detail: { file: entry.file, looked_for: line.before, in: current, what_this_means: 'The line the page shows cannot be found inside the string the registry placed it on, so no exact span exists.' } };
+    if (n > 1) return { ok: false, code: 'ambiguous_target', detail: { file: entry.file, occurrences: n, what_this_means: 'The line appears more than once inside its string, and the batch cannot say which one it meant.' } };
+    proposed = current.replace(line.before, () => line.after);
+  }
+  return {
+    ok: true,
+    patch: { row: rowKey(entry), surface: entry.surface, file: entry.file, line: entry.line, origin: entry.origin, current, proposed },
+  };
+}
+
+// applyBatchToSources({ batch, registry, readSource }) -> { applied, refused, sources }
+//
+// The whole batch, as a pure function of the registry and the files' current
+// contents (readSource(rel) returns a file's text or throws). Writes nothing.
+// `applied` and `refused` come back in PAGE order (the batch's own order);
+// `sources` maps each changed file to its new contents.
+function applyBatchToSources({ batch, registry, readSource }) {
+  const registryById = new Map();
+  for (const e of (registry && registry.entries) || []) {
+    if (!registryById.has(e.id)) registryById.set(e.id, []);
+    registryById.get(e.id).push(e);
+  }
+  const lines = ((batch && batch.lines) || []).map((l, i) => ({ ...l, order: i }));
+  const byId = (l) => registryRowFor(l, registryById);
+  // Bottom up per file, by the registry's line (the tree's truth, not the batch's).
+  const work = lines.slice().sort((a, b) => {
+    const ea = byId(a), eb = byId(b);
+    const fa = ea ? ea.file : '', fb = eb ? eb.file : '';
+    if (fa !== fb) return fa < fb ? -1 : 1;
+    return ((eb && eb.line) || 0) - ((ea && ea.line) || 0) || a.order - b.order;
+  });
+  const sources = new Map();
+  const texts = new Map();
+  const applied = [];
+  const refused = [];
+  const refuse = (l, r) => refused.push({ key: l.key, section: l.section == null ? null : l.section, before: l.before, code: r.code, detail: r.detail || {} });
+  for (const l of work) {
+    const p = patchForBatchLine(l, registryById, texts);
+    if (!p.ok) { refuse(l, p); continue; }
+    const guard = checkPatchPath(p.patch);
+    if (!guard.ok) { refuse(l, guard); continue; }
+    let source = sources.get(guard.rel);
+    if (source === undefined) {
+      try { source = readSource(guard.rel); } catch (err) { refuse(l, { code: 'file_unreadable', detail: { file: guard.rel, reason: err.message } }); continue; }
+    }
+    const out = applyPatchToSource(source, guard.rel, p.patch);
+    if (!out.ok) { refuse(l, out); continue; }
+    sources.set(guard.rel, out.source);
+    texts.set(p.patch.row, p.patch.proposed);
+    applied.push({ key: l.key, section: l.section == null ? null : l.section, file: guard.rel, line: out.line, before: out.before, after: out.after, proposed: p.patch.proposed, order: l.order });
+  }
+  const byOrder = (x, y) => x.order - y.order;
+  const orderOf = new Map(lines.map((l) => [l.key, l.order]));
+  refused.sort((x, y) => orderOf.get(x.key) - orderOf.get(y.key));
+  return { applied: applied.sort(byOrder).map(({ order, ...rest }) => rest), refused, sources };
+}
+
+// The ```page-tweak-applied``` block's content, from the page's NEW reading.
+// lines_after is the non-shared lines' texts: shared shell lines are left out of
+// drift on both sides (D8, builder pick 7), so they must be left out here too or
+// every one of them would read as "removed" on the next drift check.
+function appliedBlockFor({ pageId, readingPage, refused, appliedAt }) {
+  return {
+    page_id: pageId,
+    applied_at: appliedAt,
+    reading_hash_after: readingPage ? readingPage.reading_hash : null,
+    lines_after: readingPage ? (readingPage.lines || []).filter((l) => l && l.placement !== 'shared').map((l) => String(l.text)) : [],
+    refused: (refused || []).map((x) => ({ key: x.key, code: x.code })),
+  };
+}
+
+// Load the round's batch: the task you hold, or a local file (the tests' and the
+// dry run's entry point). A file may hold a whole round description or a bare
+// batch object; either way it goes through pages.parseBatchBlock, the one reader.
+async function loadBatch({ taskId, batchFile, readFile = (p) => fs.readFileSync(p, 'utf8'), api = apiCall }) {
+  let description;
+  if (batchFile) {
+    let raw;
+    try { raw = readFile(path.resolve(process.cwd(), batchFile)); } catch (err) { return { ok: false, code: 'batch_file_unreadable', detail: { reason: err.message } }; }
+    description = raw.trim().startsWith('{') ? ['```' + pages.FENCES.batch, raw.trim(), '```'].join('\n') : raw;
+  } else {
+    const res = await api('GET', `/api/bongos/tasks/${taskId}`);
+    if (!res.ok) return { ok: false, code: 'task_unreadable', detail: { task: taskId, status: res.status } };
+    const task = (res.data && res.data.task) || {};
+    if (task.source !== pages.SOURCE) return { ok: false, code: 'not_a_page_tweak', detail: { task: taskId, source: task.source || null, what_this_means: '--batch applies a page tweak round. For a single copy proposal, run this without --batch.' } };
+    description = task.description || '';
+  }
+  const parsed = pages.parseBatchBlock(description);
+  if (!parsed.ok) return parsed;
+  return { ok: true, batch: parsed.batch, description };
+}
+
+// Re-read the pages whose files the batch changed (page-reader.js --stale: this
+// page, and any other page sharing a changed file). Opens a browser.
+function rereadStalePages({ spawn = spawnSync } = {}) {
+  const r = spawn(process.execPath, [path.join(__dirname, 'page-reader.js'), '--stale'], { cwd: REPO_ROOT, stdio: 'inherit' });
+  return r.status === 0 ? { ok: true } : { ok: false, code: r.status === 3 ? 'no_browser' : 'reread_failed', detail: { exit: r.status } };
+}
+
+function readingFor(pageId, { readFile = (p) => fs.readFileSync(p, 'utf8') } = {}) {
+  try {
+    const doc = JSON.parse(readFile(path.join(REPO_ROOT, 'docs', 'page-readings.json')));
+    return (doc.pages || []).find((p) => p.id === pageId) || null;
+  } catch { return null; }
+}
+
+// Write the applied block into the round's description (replacing an earlier one:
+// a re-apply after a send-back supersedes it), through PATCH /tasks/:id.
+async function writeAppliedBlock({ taskId, description, block, api = apiCall }) {
+  const next = pages.replaceBlock(description, pages.FENCES.applied, pages.composeAppliedBlock(block));
+  if (!next.ok) return next;
+  const res = await api('PATCH', `/api/bongos/tasks/${taskId}`, { description: next.description });
+  if (!res.ok) return { ok: false, code: 'task_write_failed', detail: { task: taskId, status: res.status, what_this_means: 'The files are applied, but the round does not yet record it. PATCH /tasks/:id needs the task.edit permission (Metic+).' } };
+  return { ok: true };
+}
+
+// The --batch command. `deps` is the test seam: every read, write, re-read and API
+// call can be replaced, so the whole path runs against a fixture round.
+async function batchMain({ taskId, batchFile, dryRun, now = () => new Date().toISOString() }, deps = {}) {
+  const readFile = deps.readFile || ((p) => fs.readFileSync(p, 'utf8'));
+  const writeFile = deps.writeFile || ((p, s) => fs.writeFileSync(p, s));
+  const api = deps.api || apiCall;
+  const log = deps.log || console.log;
+  const loaded = await loadBatch({ taskId, batchFile, readFile, api });
+  if (!loaded.ok) return refuse(loaded);
+  const { batch } = loaded;
+  const registry = deps.registry || JSON.parse(readFile(path.join(REPO_ROOT, 'docs', 'copy-registry.json')));
+  const result = applyBatchToSources({ batch, registry, readSource: (rel) => readFile(path.join(REPO_ROOT, rel)) });
+
+  log(`copy-apply --batch: ${batch.page_id}, ${batch.lines.length} line(s): ${result.applied.length} applied, ${result.refused.length} refused.`);
+  for (const a of result.applied) {
+    log(`  ${a.key} ${a.file}:${a.line}`);
+    log(`    -  ${a.before}`);
+    log(`    +  ${a.after}`);
+  }
+  for (const x of result.refused) {
+    log(`  ${x.key} REFUSED (${x.code})${x.detail && x.detail.what_this_means ? `: ${x.detail.what_this_means}` : ''}`);
+    log(`    line: ${JSON.stringify(x.before)}`);
+  }
+  if (dryRun) { log('copy-apply --batch: --dry-run, nothing written.'); return 0; }
+
+  for (const [rel, source] of result.sources) writeFile(path.join(REPO_ROOT, rel), source);
+  const { reg } = (deps.regenerateRegistry || (() => ci.write()))();
+  const missing = result.applied.filter((a) => !reg.entries.some((e) => e.file === a.file && e.text === a.proposed));
+  if (missing.length) {
+    console.error(`copy-apply --batch: WROTE THE FILES, but the regenerated registry does not contain the new wording for ${missing.map((m) => m.key).join(', ')}.`);
+    console.error('  An edit landed somewhere the inventory does not read as copy. Review `git diff` before doing anything else.');
+    return 3;
+  }
+  log(`copy-apply --batch: files written, registry regenerated (${reg.counts ? reg.counts.strings : reg.entries.length} strings).`);
+
+  const reread = (deps.reread || rereadStalePages)();
+  if (!reread.ok) {
+    console.error(`copy-apply --batch: the page could not be re-read (${reread.code}). The files are applied; run node scripts/gds/page-reader.js --stale, then this command again to write the applied block.`);
+    return 4;
+  }
+  const readingPage = (deps.readingFor || ((id) => readingFor(id, { readFile })))(batch.page_id);
+  const block = appliedBlockFor({ pageId: batch.page_id, readingPage, refused: result.refused, appliedAt: now() });
+  if (batchFile) {
+    log('copy-apply --batch: the page-tweak-applied block (a --batch-file run writes no task):');
+    log(pages.composeAppliedBlock(block));
+  } else {
+    const wrote = await writeAppliedBlock({ taskId, description: loaded.description, block, api });
+    if (!wrote.ok) return refuse(wrote);
+    log(`copy-apply --batch: recorded the page-tweak-applied block on task ${taskId} (reading ${block.reading_hash_after}, ${block.lines_after.length} lines, ${block.refused.length} refused).`);
+  }
+  if (!result.applied.length) {
+    console.error('copy-apply --batch: NO line applied. Every refusal is recorded; there is nothing to ship until they are resolved.');
+    return 2;
+  }
+  log('  Review with `git diff`, render the page, then ship this task the normal way (it waits for the artist).');
+  return 0;
+}
+
 async function main() {
   let taskId = arg('--task');
   const patchFile = arg('--patch-file');
   const dryRun = hasFlag('--dry-run');
 
+  // --batch (task 1004322): a page tweak round. The claim gate is the same one the
+  // single proposal uses; --batch-file is the local, claim-free entry point, and
+  // like --patch-file it lands nothing a task authorised.
+  if (hasFlag('--batch')) {
+    const batchFile = arg('--batch-file');
+    if (!batchFile) {
+      const held = taskId ? await claimOnTask(taskId) : await claimedTaskId();
+      if (!held.ok) return cliExit(refuse(held));
+      taskId = held.taskId;
+      console.log(`copy-apply --batch: the round you are holding — task ${taskId}`);
+    }
+    return cliExit(await batchMain({ taskId, batchFile, dryRun }));
+  }
+
   if (!taskId && !patchFile) {
     const held = await claimedTaskId();
     if (!held.ok) return cliExit(refuse(held));
@@ -379,6 +648,13 @@ if (require.main === module) {
 }
 
 module.exports = {
+  // task 1004322: --batch, a page tweak round.
+  REFUSAL_CODES,
+  registryRowFor,
+  patchForBatchLine,
+  applyBatchToSources,
+  appliedBlockFor,
+  batchMain,
   surfaceRootFor,
   checkPatchPath,
   locateOccurrence,

package/scripts/gds/page-reader.js

@@ -671,4 +671,6 @@ module.exports = {
   filesHash, readingHash, buildMatcher, placeText, collectStrings, holeData,
   mergeStates, assembleReading, serialize, buildDoc, checkReadings, planRenders,
   captureInPage, mergeReadings,
+  // task 1004322: /tweak renders the page the reader reads, through the same harness.
+  startHarness, SURFACE_MODULE, PINNED_CLOCK,
 };

package/scripts/gds/ship-finish.js

@@ -17,7 +17,8 @@ const { uploadSessionOnShip } = require('./ship-session-upload.js');
 const { gitOk, shellOk } = require('./ship-git.js');
 const { fetchDeployedVersion } = require('./ship-deploy-target.js');
 const { landBailed, reconciledCardStatus } = require('./ship-land.js');
-const { autoMerge } = require('./ship-merge.js');
+const { autoMerge, publishHeld } = require('./ship-merge.js');
+const tweakHold = require('../../modules/lifecycle/page-tweak-hold.js');
 const { normalizeApiError, playShipBell, postLandShipOutcome } = require('./ship-io.js');
 const { getServerReward, noteServerReward } = require('./ship-state.js');
 
@@ -176,7 +177,10 @@ function postShipCloseout(taskId) {
   }
 }
 
-async function finishShip({ taskId, summary, advanceToMerge, skipMerge, postGradeStatus, doneLine, card, dbOnly = false }) {
+async function finishShip({ taskId, summary, advanceToMerge, skipMerge, postGradeStatus, doneLine, card, dbOnly = false, held = false }) {
+  // task 1004322 (ADR 0341 D7): a page tweak whose grade passed is HELD for its
+  // artist. It publishes its branch and PR and stops; nothing merges.
+  if (held) return finishHeld({ taskId, summary, postGradeStatus, card });
   // task 1002541: the land outcome carries WHY a land didn't happen. Without it
   // the card had only the status to go on and printed 'landing automatically'
   // over a merge that had already bailed.
@@ -226,6 +230,26 @@ async function finishShip({ taskId, summary, advanceToMerge, skipMerge, postGrad
   }
 }
 
+// finishHeld — the tail of a held pass (task 1004322). The session is finished
+// work, so it syncs exactly as a confirmed ship does (the applier's session
+// reward is computed from the upload, and pays on land). No bell and no tree
+// close-out: nothing landed, and a send-back brings the round back to be
+// re-applied. `deps` is a test seam only.
+async function finishHeld({ taskId, summary, postGradeStatus, card }, deps = {}) {
+  console.log('');
+  console.log('Publishing the applied branch for the artist (ADR 0341 D7):');
+  const land = await (deps.publishHeld || publishHeld)(taskId, summary);
+  if (land && land.held) {
+    for (const line of tweakHold.heldLines(taskId, { prUrl: land.prUrl })) console.log(line);
+  } else {
+    console.error(`  The branch did not publish${land && land.reason ? `: ${land.reason}` : ''}. The task stays at completed with its passed grade.`);
+    console.error(`  Re-run to publish it again (the grade is not re-run): node scripts/gds/ship.js ${taskId}`);
+  }
+  const usage = await (deps.postShipSync || postShipSync)(taskId, 'confirmed');
+  await (deps.printCompletionCard || printCompletionCard)({ taskId, postGradeStatus, card, usage, land });
+  return land;
+}
+
 // task 1275: sum the committed diffstat (added/removed lines) over baseline...HEAD.
 // Shared by the completion card and the in-review card. Best-effort: returns
 // nulls when there's no baseline or git is unavailable.
@@ -377,6 +401,7 @@ async function printCompletionCard({ taskId, postGradeStatus, card, usage, land
 module.exports = {
   diffstatFor,
   finishShip,
+  finishHeld,
   mergeAndDeploy,
   onboardingNudgeBestEffort,
   postShipSync,

package/scripts/gds/ship-flow.js

@@ -27,6 +27,7 @@ const { apiErrorLine, normalizeApiError, isUnknownFieldRejection } = require('./
 const { pushVia } = require('./ship-deploy-target.js');
 
 const { diffstatFor, finishShip } = require('./ship-finish.js');
+const tweakHold = require('../../modules/lifecycle/page-tweak-hold.js');
 const { evaluateRegradeEligibility, evaluateResumeAction, resumeMerge, shouldConfirmWithoutGrade } = require('./ship-resume.js');
 const { fileNoArtifactEscalation, noArtifactRefusalLines } = require('./ship-escalation.js');
 const { noteServerReward } = require('./ship-state.js');
@@ -583,6 +584,7 @@ async function shipMain() {
   let postGradeJustUnlocked = r.data.just_unlocked || [];
   let gradePassed = false;
   let advanceToMerge = false;
+  let held = false; // task 1004322: a page tweak's pass, held for its artist (ADR 0341 D7)
   let gradeObj = null; // task 1270: the grade result, hoisted for the completion card
   // V3.R27 (#247): credit breakdown surfaced from the grade or confirm
   // response. Kept separate from `credits` so we only print the multiplier
@@ -696,6 +698,7 @@ async function shipMain() {
     gradeObj = g;
     gradePassed = g.passed;
     advanceToMerge = gradePost.data.advanceToMerge;
+    held = gradePost.data.held === true;
     postGradeStatus = gradePost.data.taskStatus;
     credits = gradePost.data.creditsAwarded;
     postGradeJustUnlocked = gradePost.data.just_unlocked || [];
@@ -726,7 +729,7 @@ async function shipMain() {
     markShipProgress(postGradeStatus === 'shipped' ? 'landed' : 'graded', taskId);
   }
   await finishShip({
-    taskId, summary, advanceToMerge, skipMerge, postGradeStatus, doneLine: 'Done.', dbOnly,
+    taskId, summary, advanceToMerge, skipMerge, postGradeStatus, doneLine: 'Done.', dbOnly, held,
     // task 1270: data for the deterministic completion card.
     card: {
       title: ac.title,
@@ -895,6 +898,18 @@ async function regradeMain() {
     console.error(`  node scripts/gds/ship.js ${taskId} --verified`);
     process.exit(1);
   }
+  // task 1004322 (ADR 0341 D7): a page tweak already HELD for its artist has a
+  // passed grade. A plain re-run lands here (completed -> resume-grade), and
+  // re-grading would spend the panel again for the verdict it already has, so it
+  // only re-publishes the branch (the recovery for a publish that failed).
+  if (tweakHold.isHeldForArtist(task, tRes.data.grade ? tRes.data.grade.passed : null)) {
+    console.log(`Task #${taskId} already passed its grade and is waiting for the artist: re-publishing its branch, not re-grading.`);
+    await finishShip({
+      taskId, summary: summaryArg || task.value_summary || '', held: true, postGradeStatus: 'completed', doneLine: 'Done.',
+      card: { title: task.title, valueSummary: summaryArg || task.value_summary || '', notes: '' },
+    });
+    return;
+  }
   console.log(`Re-grading task #${taskId}: ${task.title}`);
   console.log(`  eligibility: ${elig.reason} (${elig.via})`);
 
@@ -1101,6 +1116,7 @@ async function regradeMain() {
   // normal ship (finishShip, #1093/C9) so a re-grade lands identically.
   await finishShip({
     taskId, summary, advanceToMerge: gradePost.data.advanceToMerge, skipMerge, dbOnly,
+    held: gradePost.data.held === true, // task 1004322: a page tweak's pass waits for its artist
     postGradeStatus,
     doneLine: g.passed ? 'Done — re-grade passed.' : 'Done — re-grade still failing; fix and try again.',
     // task 1270: completion card for the re-grade path too.

package/scripts/gds/ship-land.js

@@ -46,6 +46,12 @@ const { readCheckRollup, UNIT_REPORT_CONTEXT } = require('../../modules/lifecycl
 function landed(o = {}) { return { ok: true, pending: false, reason: null, nextStep: null, noArtifact: o.noArtifact === true, noArtifactReason: o.noArtifactReason || null }; }
 function landPending() { return { ok: false, pending: true, reason: null, nextStep: null }; }
 function landBailed(reason, nextStep = null, bailId = null) { return { ok: false, pending: false, reason, nextStep, bailId }; }
+// task 1004322 (ADR 0341 D7): the FOURTH outcome, and only a page tweak reaches it.
+// Its grade passed and its branch and PR are published, but nothing is landing and
+// nothing should: the artist approves the applied page first. Not a bail (nothing
+// failed, and the card must not say "Land it") and not pending (no auto-merge is
+// armed, so it does not land on its own).
+function landHeld({ prUrl = null } = {}) { return { ok: false, pending: false, held: true, reason: null, nextStep: null, prUrl }; }
 
 // ---------- which bails a PR can still land (task 1002572, part 2) ----------
 //
@@ -79,12 +85,17 @@ function strandCommand(taskId, via) {
 
 // ciLand — dispatch the 'ci' confirmed->shipped land to the local or the
 // server-mediated path. Async because the server path awaits GDS API calls.
-async function ciLand(taskId, branch, valueSummary) {
-  console.log('  deploy mode: ci — landing via PR auto-merge (no droplet key needed)');
+// opts.hold (task 1004322): PUBLISH ONLY — push the branch and open the PR, never
+// arm auto-merge and never poll for a land. A page tweak held for its artist takes
+// it; every other caller passes nothing and gets the unchanged path.
+async function ciLand(taskId, branch, valueSummary, opts = {}) {
+  console.log(opts.hold
+    ? '  held for the artist — publishing the branch and its PR only (no auto-merge, no land)'
+    : '  deploy mode: ci — landing via PR auto-merge (no droplet key needed)');
   if (pushVia() === 'server') {
-    return ciLandServer(taskId, branch, valueSummary);
+    return ciLandServer(taskId, branch, valueSummary, opts);
   }
-  return await ciLandLocal(taskId, branch, valueSummary);
+  return await ciLandLocal(taskId, branch, valueSummary, opts);
 }
 
 // task 1001916: render a FAILED POST /tasks/:id/publish-branch for the builder.
@@ -165,7 +176,7 @@ function formatPublishFailure(data, status, branch, opts = {}) {
 // hand the branch to the GDS, which pushes it + opens the PR + auto-merges with
 // the server-side credential. Requires a RE-AUTHED (non-box) cli session — a
 // box-scoped session is 403'd by the endpoint (it must `/builder-reauth` first).
-async function ciLandServer(taskId, branch, valueSummary) {
+async function ciLandServer(taskId, branch, valueSummary, { hold = false } = {}) {
   console.log('  ci-land: server-mediated publish (this machine has no GitHub push credential)');
   const headSha = gitOk('git rev-parse HEAD');
   // Make sure origin/main is current so the THIN bundle's `origin/main..HEAD`
@@ -195,9 +206,14 @@ async function ciLandServer(taskId, branch, valueSummary) {
       console.log(`  ci-land: server publish failed — ${e}. Task stays at confirmed. ${strandNextStep(taskId, 'server')}`);
       return landBailed(`server publish failed — ${e}`, strandCommand(taskId, 'server'));
     }
-    console.log(`  ci-land: server pushed ${branch} + PR ${r.data.pr_url} (auto-merge ${r.data.auto_merge ? 'enabled' : 'NOT enabled — merge it on GitHub'}).`);
+    // task 1004322: the server does not arm a held page tweak (it reads the hold
+    // itself), so do not tell the builder to merge it on GitHub.
+    console.log(hold
+      ? `  ci-land: server pushed ${branch} + PR ${r.data.pr_url} (auto-merge NOT armed: waiting for the artist).`
+      : `  ci-land: server pushed ${branch} + PR ${r.data.pr_url} (auto-merge ${r.data.auto_merge ? 'enabled' : 'NOT enabled — merge it on GitHub'}).`);
     const assigneeLine = prAssigneeLine(r.data.pr_assignee);
     if (assigneeLine) console.log(assigneeLine);
+    if (hold) return landHeld({ prUrl: r.data.pr_url || null });
     return pollServerPublish(taskId, branch);
   } finally {
     try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch (_) { /* best-effort */ }
@@ -858,7 +874,7 @@ function pushCapturing(branch, deps = {}) {
 // ciLandLocal — today's local path: this machine pushes the branch + opens the PR
 // + enables auto-merge via git + gh. async since task 1169 — it asks the server to
 // post the gate-author-trust attestation between the push and the PR open.
-async function ciLandLocal(taskId, branch, valueSummary) {
+async function ciLandLocal(taskId, branch, valueSummary, { hold = false } = {}) {
   const headSha = gitOk('git rev-parse HEAD');
 
   console.log(`  pushing ${branch} to origin...`);
@@ -924,6 +940,12 @@ async function ciLandLocal(taskId, branch, valueSummary) {
     console.log(`  ci-land: reusing open PR ${existing.url}`);
   }
 
+  // task 1004322: a held page tweak stops here — published, never armed.
+  if (hold) {
+    const pr = ghJson(['pr', 'view', branch, '--json', 'number,url,state']);
+    console.log(`  ci-land: PR ${(pr && pr.url) || 'opened'} — auto-merge NOT armed: waiting for the artist.`);
+    return landHeld({ prUrl: (pr && pr.url) || null });
+  }
   console.log('  ci-land: enabling auto-merge (lands when required checks pass)...');
   // task 1718: an enable-failure is NOT a dead-end — the PR is open and the server
   // still lands green PRs. Don't return false (which stranded the builder at
@@ -1075,6 +1097,7 @@ module.exports = {
   LAND_BAIL_NO_TASK_BRANCH,
   landBailRecoverableByPr,
   landBailed,
+  landHeld,
   landPending,
   landPendingLines,
   landPollAfterAutoMerge,

package/scripts/gds/ship-merge.js

@@ -86,6 +86,46 @@ async function autoMerge(taskId, valueSummary, opts = {}, deps = {}) {
   return await land(taskId, branch, valueSummary);
 }
 
+// regenerateShipArtifacts — every generated artifact a branch must carry fresh,
+// in the order the land has always refreshed them. Moved out of mergeLocally
+// unchanged (task 1004322) so the held publish below carries the same set.
+function regenerateShipArtifacts() {
+  regenerateDiagrams();
+  // Refresh the generated code symbol skeleton (Path B / task 1224) on the same beat.
+  regenerateRepoMap();
+  // Refresh the generated session-log index + the bounded CLAUDE.md §13 snippet (ADR 0062 §8 / task 1226).
+  regenerateSessionIndex();
+  // Refresh the generated file-map sections (skills + scheduled-tasks) on the same beat (ADR 0066 / task 1276).
+  regenerateFileMap();
+  // Refresh the copy registry + inventory on the same beat (task 1003556). Its rows
+  // carry line numbers, so ANY edit to a scanned UI file staled it — and nothing in
+  // the ship path regenerated it, so the PR was born stale and CI said so.
+  regenerateCopyInventory();
+  // Refresh the generated OpenAPI spec + API reference from the shipped route tree (task 1918).
+  regenerateApiDocs();
+  // ...then the typed client FROM that spec (+ the devbox vendored copy) on the same beat (task 2051).
+  regenerateApiClient();
+}
+
+// publishHeld — the held pass's whole "land" (task 1004322, ADR 0341 D7). A page
+// tweak whose grade passed waits at completed for its artist, and the Approval
+// queue shows the APPLIED BRANCH, so the branch and its PR must exist now: a
+// grade-parked ship otherwise never publishes, and the later approve would strand
+// at no_branch_no_tip. This publishes, in every deploy mode, through the PR path
+// (never a local merge to main) and stops: no auto-merge, no poll, no land.
+// `deps` is a test seam only.
+async function publishHeld(taskId, valueSummary, deps = {}) {
+  const branch = (deps.currentBranch || currentBranch)();
+  if (!branch || branch === 'main' || branch === 'HEAD') {
+    return landBailed(
+      `nothing to publish — this checkout is on ${branch}, not the task branch`,
+      onMainNextStep(taskId, (deps.localTaskBranchExists || localTaskBranchExists)(taskId)),
+    ); // untagged on purpose: only autoMerge routes by bail id
+  }
+  (deps.regenerate || regenerateShipArtifacts)();
+  return await (deps.ciLand || ciLand)(taskId, branch, valueSummary, { hold: true });
+}
+
 async function mergeLocally(taskId, valueSummary, { dbOnly = false } = {}) {
   const branch = currentBranch();
   if (!branch || branch === 'main' || branch === 'HEAD') {
@@ -116,21 +156,7 @@ async function mergeLocally(taskId, valueSummary, { dbOnly = false } = {}) {
 
   // Refresh the data-driven diagrams before computing commits-ahead, so a
   // diagram-only refresh still counts as something to deploy.
-  regenerateDiagrams();
-  // Refresh the generated code symbol skeleton (Path B / task 1224) on the same beat.
-  regenerateRepoMap();
-  // Refresh the generated session-log index + the bounded CLAUDE.md §13 snippet (ADR 0062 §8 / task 1226).
-  regenerateSessionIndex();
-  // Refresh the generated file-map sections (skills + scheduled-tasks) on the same beat (ADR 0066 / task 1276).
-  regenerateFileMap();
-  // Refresh the copy registry + inventory on the same beat (task 1003556). Its rows
-  // carry line numbers, so ANY edit to a scanned UI file staled it — and nothing in
-  // the ship path regenerated it, so the PR was born stale and CI said so.
-  regenerateCopyInventory();
-  // Refresh the generated OpenAPI spec + API reference from the shipped route tree (task 1918).
-  regenerateApiDocs();
-  // ...then the typed client FROM that spec (+ the devbox vendored copy) on the same beat (task 2051).
-  regenerateApiClient();
+  regenerateShipArtifacts();
 
   // Resolve the deploy mode ONCE (task 1093 / C9) — it reads config/deploy.json;
   // reused at the fetch-bail check + the ci-land branch below.
@@ -422,6 +448,8 @@ async function mergeLocally(taskId, valueSummary, { dbOnly = false } = {}) {
 
 module.exports = {
   autoMerge,
+  // task 1004322: the held page tweak's publish-only path.
+  publishHeld,
   // task 1002572 (PART 2): the pure recovery command for a ship run from main —
   // exported so the "don't point back at the dead end" wording is pinned.
   onMainNextStep,