@bongos/core 1.21.175 → 1.21.177

package/scripts/bongos/ship-regen.js

@@ -0,0 +1,291 @@
+// scripts/bongos/ship-regen.js — regeneration of the generated artifacts a ship must keep fresh + the merge-worktree lock.
+//
+// Carved out of scripts/bongos/ship.js by task 1003205 (goal 1000079, the R03
+// de-monolith plan) — a STRUCTURAL move, not a rewrite: the code below is the
+// original ship.js lines 2050-2306 unchanged. ship.js remains the facade that
+// re-exports every name and owns the CLI entry point, so the ship contract and
+// every flag are untouched, and the other scripts that import from it are too.
+
+'use strict';
+
+const path = require('node:path');
+const { gitOk, shellOk } = require('./ship-git.js');
+const { pushVia } = require('./ship-deploy-target.js');
+const { REPO_ROOT } = require('./ship-state.js');
+
+// ---------- Step 3: merge + deploy chain ----------
+
+function currentBranch() {
+  return gitOk('git rev-parse --abbrev-ref HEAD');
+}
+
+// Task #357: keep the 3 mechanical onboarding diagrams current on every deploy.
+// Regenerate them from live facts; if any changed, commit the refresh on this
+// branch so it ships with the deploy. Non-fatal — a render/network hiccup must
+// never block a ship; the next render-capable ship refreshes any miss.
+//
+// Returns a status string ('skipped-server' | 'regen-failed' | 'current' |
+// 'committed' | 'committed-nofatal') so the regression test (task 1046) can
+// prove the server-publish skip without git or a headless browser.
+function regenerateDiagrams() {
+  // task 1046: on the server-mediated-publish path (pushVia 'server'),
+  // there is no headless browser, so render-diagrams.sh fails and gen-diagrams.js
+  // exits non-zero AFTER writing the regenerated .mmd + assertions.json — which
+  // shellOk() then treats as a failed regen and returns BEFORE the commit below,
+  // leaving those files UNCOMMITTED in the builder's tree (had to be reverted by
+  // hand). That path must not attempt the regen at all: skip here and let a
+  // render-capable ship (the laptop path, which CAN render the PNGs) refresh them
+  // as a matched .mmd+.png+assertions set. Skipping entirely (vs --no-render) avoids committing
+  // a .mmd/.png mismatch to main. Mirrors gen-diagrams.js's own non-fatal skip when
+  // bash itself is absent (ENOENT).
+  if (pushVia() === 'server') {
+    console.log('  diagram regen skipped on the server-publish ship path (no GDS session for the conceptual diagrams) — a full-clone ship refreshes the .mmd; drift checker backstops staleness');
+    return 'skipped-server';
+  }
+  // ADR 0110 pt.3 (task 2027): the .svg/.png RENDERS are now gitignored and
+  // regenerated at deploy (deploy-prod.sh) — no longer committed here — so ship
+  // only refreshes the TRACKED sources. Run gen-diagrams with --no-render: it
+  // rewrites the mechanical .mmd + assertions.json from live facts WITHOUT
+  // invoking the headless-Chromium render, which is why this no longer needs a
+  // render-capable machine. The gitignored .svg/.png never appear in the git add
+  // below (a directory add silently skips ignored paths).
+  console.log('  regenerating onboarding diagram SOURCES from live facts (--no-render; renders are a deploy artifact, ADR 0110 pt.3)...');
+  // process.execPath (quoted) instead of bare `node`: on Windows cmd.exe can't
+  // resolve a bare `node` without a full PATH, the same failure #660 fixed for
+  // the smoke-gds spawn. The quotes survive spaces in a Windows install path
+  // (e.g. C:\Program Files\nodejs\node.exe).
+  if (!shellOk(`"${process.execPath}" ${JSON.stringify(path.join(__dirname, 'gen-diagrams.js'))} --no-render`)) {
+    console.log('  diagram regen failed (non-fatal) — drift checker will flag any staleness');
+    return 'regen-failed';
+  }
+  const dirty = gitOk('git status --porcelain docs/onboarding/diagrams');
+  if (!dirty) {
+    console.log('  diagram sources already current — nothing to commit');
+    return 'current';
+  }
+  shellOk('git add docs/onboarding/diagrams');
+  if (shellOk('git commit -m "chore(diagrams): auto-regenerate diagram sources from live facts (task 357)"')) {
+    console.log('  committed auto-regenerated diagrams');
+    return 'committed';
+  }
+  return 'committed-nofatal';
+}
+
+// task 1224 (Path B / ADR 0063): refresh the generated symbol skeleton from the shipped tree so the
+// altitude map can't drift. Pure JS (no headless browser, no render) — unlike the diagrams it is safe
+// on EVERY ship path, including the server-publish path. Non-fatal: a hiccup must never block
+// a ship. ADR 0110 (task 1926): docs/repo-map.md is now GITIGNORED + regenerated at deploy — the
+// generator still WRITES it (untracked, harmless), but ship commits ONLY the tracked nested-doc
+// blocks. It is deliberately absent from the git add/status lists below: `git add <ignored path>`
+// ABORTS the whole command (exit 1), which would drop the nested-block commit. The block bucket is
+// backstopped on main by fitness.js (`gen-repo-map --check-block`).
+function regenerateRepoMap() {
+  console.log('  regenerating code symbol skeleton (repo map + nested-doc blocks) from the shipped tree...');
+  if (!shellOk(`"${process.execPath}" ${JSON.stringify(path.join(__dirname, 'gen-repo-map.js'))}`)) {
+    console.log('  repo-map regen failed (non-fatal) — CI --check-block backstops the tracked blocks');
+    return 'regen-failed';
+  }
+  const dirty = gitOk('git status --porcelain src/bongos/CLAUDE.md src/bongos/routes/CLAUDE.md');
+  if (!dirty) {
+    console.log('  nested-doc symbol blocks already current — nothing to commit (docs/repo-map.md is gitignored, ADR 0110)');
+    return 'current';
+  }
+  shellOk('git add src/bongos/CLAUDE.md src/bongos/routes/CLAUDE.md');
+  if (shellOk('git commit -m "chore(repo-map): auto-regenerate nested-doc symbol blocks (task 1224)"')) {
+    console.log('  committed auto-regenerated nested-doc symbol blocks');
+    return 'committed';
+  }
+  return 'committed-nofatal';
+}
+
+// Refresh the generated session-log index (docs/session-log-index.md) + the bounded CLAUDE.md §13
+// "recent sessions" snippet from the shipped tree's docs/session-logs/*.md (ADR 0062 §8, task 1226).
+// Pure JS (reads files, no DB, no headless browser) — safe on EVERY ship path including the
+// server-publish path. Non-fatal: a hiccup must never block a ship; the Path-C CI gate
+// (`gen-session-index --check`) backstops staleness on main.
+// Refresh the generated API pointer stub (docs/routes-permissions.md) from the shipped
+// route tree (task 1918). Pure JS — safe on EVERY ship path. Non-fatal; the fitness
+// `gen-api-docs --check` gate backstops it on main.
+//
+// task 1004866: gen-api-docs.js also writes docs/api/openapi.json + docs/api-reference.md,
+// and gen-api-client.js the typed client — all GITIGNORED now, rebuilt from the routes by
+// package-core / serve-internal / the unit suite. So ship no longer regenerates or commits
+// them (it used to, ~175 "auto-regenerate typed client" commits in four months), and the
+// ignored paths are deliberately absent from the git status/add lists below: an explicit
+// `git add <ignored path>` ABORTS the whole command, which would drop the stub's commit.
+const API_DOCS_COMMITTED = 'docs/routes-permissions.md';
+
+function regenerateApiDocs() {
+  console.log('  regenerating the API pointer stub from the shipped route tree...');
+  if (!shellOk(`"${process.execPath}" ${JSON.stringify(path.join(__dirname, 'gen-api-docs.js'))}`)) {
+    console.log('  api-docs regen failed (non-fatal) — CI --check backstops it');
+    return 'regen-failed';
+  }
+  const dirty = gitOk(`git status --porcelain ${API_DOCS_COMMITTED}`);
+  if (!dirty) {
+    console.log('  API pointer stub already current — nothing to commit (the spec, reference and client are gitignored, task 1004866)');
+    return 'current';
+  }
+  shellOk(`git add ${API_DOCS_COMMITTED}`);
+  if (shellOk('git commit -m "chore(api-docs): auto-regenerate the API pointer stub (task 1918)"')) {
+    console.log('  committed auto-regenerated API pointer stub');
+    return 'committed';
+  }
+  return 'committed-nofatal';
+}
+
+// ADR 0110 (task 1926): docs/session-log-index.md is GITIGNORED + deploy-regenerated — the generator
+// still writes it (untracked), but ship commits ONLY the tracked CLAUDE.md §13 snippet. The index is
+// omitted from the git add/status lists (an explicit `git add` of an ignored path aborts the commit);
+// the tracked snippet is backstopped on main by fitness.js (`gen-session-index --check-block`).
+function regenerateSessionIndex() {
+  console.log('  regenerating session-log index + CLAUDE.md snippet from the shipped tree...');
+  if (!shellOk(`"${process.execPath}" ${JSON.stringify(path.join(__dirname, 'gen-session-index.js'))}`)) {
+    console.log('  session-index regen failed (non-fatal) — CI --check-block backstops the tracked snippet');
+    return 'regen-failed';
+  }
+  const dirty = gitOk('git status --porcelain CLAUDE.md');
+  if (!dirty) {
+    console.log('  CLAUDE.md §13 snippet already current — nothing to commit (docs/session-log-index.md is gitignored, ADR 0110)');
+    return 'current';
+  }
+  shellOk('git add CLAUDE.md');
+  if (shellOk('git commit -m "chore(session-log): auto-regenerate CLAUDE.md §13 snippet (task 1226)"')) {
+    console.log('  committed auto-regenerated CLAUDE.md §13 snippet');
+    return 'committed';
+  }
+  return 'committed-nofatal';
+}
+
+// Refresh the generated file-map sections (.claude/skills/ + .claude/scheduled-tasks/ trees in
+// docs/file-map.md) from what is on disk (ADR 0066, task 1276). Pure JS (reads dirs + the
+// docs/file-map.notes.json sidecar, no DB, no headless browser) — safe on EVERY ship path including
+// the server-publish path. Non-fatal: a hiccup must never block a ship; the Path-C CI gate
+// (`gen-file-map --check`, in fitness.js) backstops staleness on main. NB gen-file-map exits 2 when
+// a skill/routine has no note, so shellOk may report "failed" on a legit note-gap ship — that is
+// fine, we still commit whatever it wrote and CI surfaces the missing note.
+function regenerateFileMap() {
+  console.log('  regenerating file-map sections (skills + scheduled-tasks) from the shipped tree...');
+  shellOk(`"${process.execPath}" ${JSON.stringify(path.join(__dirname, 'gen-file-map.js'))}`);
+  const dirty = gitOk('git status --porcelain docs/file-map.md');
+  if (!dirty) {
+    console.log('  file-map already current — nothing to commit');
+    return 'current';
+  }
+  shellOk('git add docs/file-map.md');
+  if (shellOk('git commit -m "chore(file-map): auto-regenerate skills + scheduled-tasks sections (task 1276)"')) {
+    console.log('  committed auto-regenerated file-map sections');
+    return 'committed';
+  }
+  return 'committed-nofatal';
+}
+
+// docs/copy-registry.json + docs/copy-inventory.md — the reader-facing copy the UI
+// actually renders (task 1003556).
+//
+// WHY IT HAS TO RUN HERE. Every row in the registry carries a `line`, so editing ANY
+// scanned UI file shifts line numbers and makes tests/copy_inventory.mjs red — on the
+// PR's MERGE ref, not on the branch, which is the worst place to find out. Nothing in
+// the ship path regenerated it (grep for copy-inventory across ship.js, ship-regen.js
+// and ship-preflight-steps.js used to return zero hits) and fitness did not cover the
+// pair either, so the builder got no local signal at all and learned from CI.
+//
+// Task 1003546 fixed the SERVER-side merge heals for the same artifact. Those repair a
+// strand after it happens; this is the prevention, so the PR is not born stale.
+function regenerateCopyInventory() {
+  console.log('  regenerating the copy registry + inventory from the shipped tree...');
+  shellOk(`"${process.execPath}" ${JSON.stringify(path.join(__dirname, 'copy-inventory.js'))}`);
+  const dirty = gitOk('git status --porcelain docs/copy-registry.json docs/copy-inventory.md');
+  if (!dirty) {
+    console.log('  copy registry already current — nothing to commit');
+    return 'current';
+  }
+  shellOk('git add docs/copy-registry.json docs/copy-inventory.md');
+  if (shellOk('git commit -m "chore(copy): auto-regenerate the copy registry + inventory (task 1003556)"')) {
+    console.log('  committed auto-regenerated copy registry');
+    return 'committed';
+  }
+  return 'committed-nofatal';
+}
+
+// ---------- merge serialization lock (#462 C4; extended in #269 C6) ----------
+//
+// autoMerge() mutates the SHARED main worktree (REPO_ROOT). Two concurrent
+// ships — or a ship racing a /merge-mode in another session — collide on that
+// single working tree. Observed 2026-05-30: a parallel session was mid-merge
+// in REPO_ROOT, so this ship's `git merge --ff-only` failed and it bailed with
+// the misleading "main is ahead of origin somehow".
+//
+// The lock primitives now live in src/bongos/merge-lock.js (V3.R50 / #269) so BOTH
+// ship.js AND the /merge-mode CLI take the SAME mutex — closing the
+// ship-vs-merge-mode and merge-mode-vs-merge-mode races that the in-ship.js
+// lock could not cover. See docs/recipes/multi-builder-merge.md.
+
+// describeMainWorktreeBusy — the PURE verdict. Given the three facts about
+// REPO_ROOT, is it safe to mutate, and if not, why? Returns a human reason string
+// or null.
+//
+// task 1002871: it used to answer only 'a merge is already in progress' or 'the
+// working tree is dirty…', and it runs BEFORE the named-branch diagnostic in
+// ship-merge.js. So the shape of the original incident — a shared main checkout
+// that is BOTH parked on a feature branch AND dirty (2026-07-28: parked on
+// `task-1002503-backfill-recovery` with 2 unpushed commits and 4 modified
+// generated files, blocking the auto-merge leg for 9 confirmed tasks) —
+// short-circuited here and the builder never learned WHICH branch was squatting.
+// The named-branch message was only reachable when the tree was clean, which is
+// the one case where nobody needs to be told twice.
+//
+// Pure + exported so the wording is unit-tested rather than eyeballed: this is the
+// ship hot path, and the whole value of the change is the exact string.
+function describeMainWorktreeBusy({ mergeInProgress, dirty, branch, defaultBranch = 'main' } = {}) {
+  // A branch name is only worth naming when it is NOT the expected one. Saying
+  // "on main" in every bail would be noise that trains the reader to skip the line.
+  const occupant = branch && branch !== defaultBranch && branch !== 'HEAD'
+    ? ` (on \`${branch}\`, not \`${defaultBranch}\`)`
+    : '';
+  if (mergeInProgress) return `a merge is already in progress${occupant}`;
+  if (dirty) return `the working tree is dirty or has unmerged files${occupant}`;
+  return null;
+}
+
+// REPO_ROOT must be on main, not mid-merge, and clean before we mutate it.
+// Returns a human reason string if busy, or null if safe to proceed. The I/O
+// shell over describeMainWorktreeBusy — gather the facts, let the pure half decide.
+function mainWorktreeBusy() {
+  const mergeInProgress = !!gitOk('git rev-parse -q --verify MERGE_HEAD', { cwd: REPO_ROOT });
+  // Short-circuit the moment the verdict is decided. `describeMainWorktreeBusy`
+  // prefers merge-in-progress over dirty, so once that is true the dirty probe's
+  // answer is discarded — spawning it anyway would be two subprocesses bought for
+  // nothing. The branch IS still needed on this arm: the reason names it either way.
+  const branch = gitOk('git rev-parse --abbrev-ref HEAD', { cwd: REPO_ROOT }) || null;
+  if (mergeInProgress) return describeMainWorktreeBusy({ mergeInProgress: true, branch });
+  const dirty = gitOk('git status --porcelain', { cwd: REPO_ROOT });
+  // Best-effort throughout: a probe failure yields null, which the pure half reads
+  // as "no occupant worth naming". A diagnostic must never be the thing that
+  // breaks the bail it is decorating.
+  return describeMainWorktreeBusy({ mergeInProgress: false, dirty: !!(dirty && dirty.length > 0), branch });
+}
+
+// task 391 (idea #37): the verdict for a ship whose branch has no commits ahead
+// of main. Pure, so the gate is unit-tested.
+//   'has-commits' → normal path: there is a real diff to merge + deploy. (Also
+//                   the value when `git rev-list` failed/returned null — same as
+//                   the original `=== '0'` check, which only short-circuited an
+//                   exact '0'.)
+//   'db-only'     → zero commits + explicit --db-only: a deliberate direct-SQL
+//                   ship (work already live in the prod DB); short-circuit to shipped.
+//   'refuse'      → zero commits + NO --db-only: almost always a mistake
+//                   (uncommitted work / wrong branch / empty touches[]); refuse.
+
+module.exports = {
+  currentBranch,
+  describeMainWorktreeBusy,
+  mainWorktreeBusy,
+  regenerateApiDocs,
+  API_DOCS_COMMITTED,
+  regenerateDiagrams,
+  regenerateCopyInventory,
+  regenerateFileMap,
+  regenerateRepoMap,
+  regenerateSessionIndex,
+};

package/scripts/bongos/ship-resume.js

@@ -0,0 +1,201 @@
+// scripts/bongos/ship-resume.js — the claim-less resume + re-grade eligibility decisions and resumeMerge.
+//
+// Carved out of scripts/bongos/ship.js by task 1003205 (goal 1000079, the R03
+// de-monolith plan) — a STRUCTURAL move, not a rewrite: the code below is the
+// original ship.js lines 3353-3477 unchanged. ship.js remains the facade that
+// re-exports every name and owns the CLI entry point, so the ship contract and
+// every flag are untouched, and the other scripts that import from it are too.
+
+'use strict';
+
+const { cliClient } = require('./cli-lib');
+const { classifyEmptyShip } = require('../../modules/lifecycle/ship-preflight');
+const { preflight } = require('./ship-preflight-steps.js');
+const { playShipBell } = require('./ship-io.js');
+const { strandNextStep } = require('./ship-land.js');
+const { mergeAndDeploy, onboardingNudgeBestEffort, postShipSync, printCompletionCard } = require('./ship-finish.js');
+
+// task 1003221 — `pushMode` ('server'|'local') so the 'confirmed' answer names a
+// command the caller can ACTUALLY run: it hardcoded `/merge-mode`, which needs gh +
+// a main checkout (SEC #863) no server-mediated builder has. Defers to
+// strandNextStep; defaults to 'local' so an old caller is unchanged.
+function evaluateRegradeEligibility({ task, lastClaim, builder, pushMode = 'local' }) {
+  if (!task) {
+    return { ok: false, code: 'task_not_found', reason: 'Task not found.' };
+  }
+  const status = task.status;
+  if (status !== 'completed') {
+    let reason;
+    if (status === 'confirmed') {
+      reason = `Task #${task.id} is already 'confirmed' — its grade passed. Nothing to re-grade. `
+        + `If it hasn't shipped: ${strandNextStep(task.id, pushMode)}`;
+    } else if (status === 'shipped') {
+      reason = `Task #${task.id} is already 'shipped'. Done.`;
+    } else if (status === 'active' || status === 'ready') {
+      reason = `Task #${task.id} is '${status}', not 'completed'. Claim it and run a normal /builder-ship — --regrade only re-grades a ship that landed at 'completed'.`;
+    } else {
+      reason = `Task #${task.id} is '${status}'. --regrade only applies to a task stuck at 'completed' after a failed grade.`;
+    }
+    return { ok: false, code: 'not_completed', reason, status };
+  }
+  const isArchon = !!builder && builder.rank === 'archon';
+  const owns = !!lastClaim && !!builder && Number(lastClaim.builder_id) === Number(builder.id);
+  if (!isArchon && !owns) {
+    const holder = lastClaim?.github_login ? `@${lastClaim.github_login}` : 'another builder';
+    return {
+      ok: false,
+      code: 'not_owner',
+      reason: `Task #${task.id} was last claimed by ${holder}. Only that builder or an Archon can re-grade it.`,
+    };
+  }
+  return {
+    ok: true,
+    code: 'eligible',
+    via: owns ? 'owner' : 'archon',
+    reason: owns ? 'you last held this claim' : 'archon re-grade',
+  };
+}
+
+// task 941 (V4.R03 — idempotent ship re-drive): decide what a CLAIM-LESS
+// `ship.js <id>` re-run should do. The claim is consumed at the resolve step, so
+// a ship that fails AFTER it (grade fail → stuck `completed`; merge/deploy fail →
+// stuck `confirmed`, the task-1027 nightmare) left a re-run dead-ending at "you
+// don't have an active claim" — the builder had to know the `--regrade` flag (and
+// for `confirmed` there was NO path at all). This makes a PLAIN re-run resume
+// from the stalled leg: `completed` → re-grade, `confirmed` → re-merge/deploy.
+// Pure + exported so the truth table is unit-tested with no git/network. Returns
+// { action, via?, reason? } where action ∈
+//   resume-grade | resume-merge | done | claim-first | error
+function holderLabel(lastClaim) {
+  return lastClaim?.github_login ? `@${lastClaim.github_login}` : 'another builder';
+}
+function evaluateResumeAction({ task, lastClaim, builder }) {
+  if (!task) return { action: 'error', reason: 'Task not found.' };
+  const status = task.status;
+  if (status === 'shipped') {
+    return { action: 'done', reason: `Task #${task.id} is already 'shipped'. Nothing to do.` };
+  }
+  const isArchon = !!builder && builder.rank === 'archon';
+  const owns = !!lastClaim && !!builder && Number(lastClaim.builder_id) === Number(builder.id);
+  if (status === 'completed' || status === 'confirmed') {
+    const leg = status === 'completed' ? 'grade' : 'merge';
+    if (!isArchon && !owns) {
+      return {
+        action: 'error',
+        reason: `Task #${task.id} is at '${status}' but was last claimed by ${holderLabel(lastClaim)}. ` +
+          `Only that builder or an Archon can resume the ${leg}.`,
+      };
+    }
+    return {
+      action: status === 'completed' ? 'resume-grade' : 'resume-merge',
+      via: owns ? 'owner' : 'archon',
+    };
+  }
+  if (status === 'active') {
+    return {
+      action: 'claim-first',
+      reason: `Task #${task.id} is 'active' (claimed) but not in THIS session. Ship from the session that ` +
+        `claimed it, or \`node scripts/bongos/release.js ${task.id} --force\` here, then re-claim.`,
+    };
+  }
+  if (status === 'ready' || status === 'backlog' || status === 'blocked') {
+    return {
+      action: 'claim-first',
+      reason: `Task #${task.id} is '${status}' — claim it first: \`node scripts/bongos/claim.js ${task.id}\`.`,
+    };
+  }
+  return { action: 'error', reason: `Task #${task.id} is '${status}'. Nothing to resume.` };
+}
+
+// task 1003147: may a re-grade that has NOTHING to grade manual-confirm instead of
+// dead-ending? Pure + exported so the truth table is unit-tested with no git or
+// network, the same contract evaluateResumeAction above carries.
+//
+// Both halves are required, and they are different KINDS of evidence. The empty
+// diff is MEASURED (the caller passes what `git diff --name-only` actually
+// returned); the flag is the builder's DECLARATION that artifact-free is intended.
+// A declaration alone must never be enough — a task with a real diff whose grade
+// failed would otherwise bypass the grader by passing --allow-empty, turning a
+// deadlock fix into a quality hole. When the diff is genuinely empty the grader has
+// nothing to read, so there is no verdict being dodged.
+//
+// A bare re-run (neither flag) keeps dead-ending, deliberately: the overwhelmingly
+// common cause of an empty diff is uncommitted work, and silently confirming that
+// would ship nothing while reporting success.
+//
+// task 1003944 — THE FIRST CUT ASKED THE WRONG TWO QUESTIONS, and both answers let
+// the task-1363 phantom ship back in on this path:
+//
+//   (a) It never looked at the WORKING TREE. The only tree check a re-grade runs is
+//       preflight(), which uses trackedDirty and — by its own comment — deliberately
+//       ignores UNTRACKED files. So a deliverable that was never `git add`ed is
+//       invisible to both, and `--allow-empty` confirmed it, awarded credits, and
+//       (via finishShip's hardcoded dbOnly) landed the row at SHIPPED with HEAD
+//       never moved. That is task 1363 exactly: the ledger lying, CLAUDE.md §8.
+//       classifyEmptyShip already states the rule this violated — a dirty tree
+//       refuses EVEN UNDER --allow-empty, because the flag asserts there is no
+//       artifact and the tree proves there is one.
+//
+//   (b) It accepted `--skip-grade` as the declaration. That flag declares nothing
+//       about artifacts — ship.js's usage block documents it as a grader-outage
+//       override, "NOT a routine flag" — and task 1365 had already REMOVED it from
+//       the first-ship empty-diff decision for precisely that reason. Task 1003146's
+//       recovery is unaffected: `--allow-empty` is the flag both refusal messages
+//       prescribe, and it still works.
+//
+// So this no longer carries a second, weaker copy of the rule: it hands the
+// measured tree to classifyEmptyShip — the SAME function the first ship calls — and
+// returns its verdict, so the two paths cannot drift apart again. `porcelain` is
+// `git status --porcelain` output, passed in by the caller to keep this pure.
+// `reason` is classifyEmptyShip's ('uncommitted-work' | 'nothing-to-ship' |
+// 'allow-empty'), plus 'has-diff' when there is real committed work to grade.
+function shouldConfirmWithoutGrade({ committedFileCount, porcelain = '', args = [] }) {
+  if (Number(committedFileCount) !== 0) return { confirm: false, reason: 'has-diff', uncommitted: [] };
+  const verdict = classifyEmptyShip(porcelain, { allowEmpty: args.includes('--allow-empty') });
+  return { confirm: !verdict.refuse, reason: verdict.reason, uncommitted: verdict.uncommitted || [] };
+}
+
+// task 941: resume a `confirmed`-but-unshipped task — the merge/deploy leg only
+// (it already passed the grade + earned credits; this is the leg that stalls when
+// a box can't reach the server publish, a poll window expires, etc.). Mirrors the
+// tail of a normal ship: preflight → mergeAndDeploy → post-ship sync.
+async function resumeMerge(taskId, { summary, skipMerge, force, task, dbOnly = false }) {
+  console.log(`Resuming merge + deploy for task #${taskId}: ${task?.title || ''}`);
+  // Same working-tree-clean / branch-freshness guard a first ship runs before
+  // the land. head_sha is unused on this leg; touches is only for preflight.
+  const claimLike = { touches: task?.touches || [], head_sha: null, task_id: taskId, title: task?.title };
+  console.log('Preflight (working tree + branch freshness)...');
+  const pre = preflight(claimLike, { force });
+  if (!pre.ok) {
+    console.error('');
+    console.error(`Resume aborted: ${pre.reason}. Task stays at confirmed.`);
+    process.exit(1);
+  }
+  // The first ship stored value_summary; reuse it so the merge commit + broadcast
+  // carry meaningful text even when --summary is omitted on the re-run.
+  const effSummary = summary || task?.value_summary || '';
+  const land = await mergeAndDeploy({ taskId, summary: effSummary, advanceToMerge: true, skipMerge, dbOnly });
+  const usage = await postShipSync(taskId, 'confirmed');
+  console.log('');
+  console.log('Done — merge/deploy resume complete.');
+  playShipBell(); // task 1442: ring the bell when a stalled ship finally lands.
+  await onboardingNudgeBestEffort();
+  // task 1275: the resume path lands a stalled ship — show the completion card
+  // too (the gap surfaced on task 1270's own ship). Re-fetch the status so the
+  // card reflects whether it actually reached shipped. Best-effort.
+  try {
+    const t = await (await cliClient()).tasks.getTasksId({ id: taskId });
+    const status = (t.ok && t.data && t.data.task) ? t.data.task.status : 'shipped';
+    await printCompletionCard({
+      taskId, postGradeStatus: status, usage, land,
+      card: { title: task?.title, valueSummary: effSummary, notes: '', creditsAwarded: null },
+    });
+  } catch (_) { /* the resume already succeeded; the card is a bonus */ }
+}
+
+module.exports = {
+  evaluateRegradeEligibility,
+  evaluateResumeAction,
+  resumeMerge,
+  shouldConfirmWithoutGrade,
+};