@bongos/core 1.21.174 → 1.21.176

package/scripts/bongos/ship-mode-manual.js

@@ -0,0 +1,54 @@
+// scripts/bongos/ship-mode-manual.js — Manual ship mode: the AI asks before it ships (task 1004631, ADR 0369).
+//
+// WHY. Ship mode says who starts a ship. In Auto the AI ships on its own; in Manual a person
+// approves each ship. The instance CLAUDE.md and the /builder-ship skill tell the AI to ask in
+// Manual, but words alone are what failed the owner in Auto (the AI refused to ship), so the ship
+// itself also stops: when an AI session runs it on a Manual project without the person's yes, it
+// exits before anything resolves and prints the question. The re-run with `--person-approved`
+// carries on.
+//
+// WHO IT STOPS. Only an AI session: Claude Code sets CLAUDECODE=1 in the shell it runs commands
+// in, and a person typing `npx bongos ship` in their own terminal has already decided. An
+// Autobongos worker (OTB_SUBAGENT=1) is not stopped: the runner is the owner's own opt-in to
+// unattended shipping, and stopping it would only park every task it takes.
+//
+// WHAT IT IS NOT. A security wall. The flag is one word an agent could add, the same posture as
+// `--approved` on the sandbox review: the rule is behavioural, and the skill says never to pass it
+// without a real yes. Rank and every server gate are unchanged (ADR 0016). A mode that cannot be
+// read never stops a ship (the resolver's own posture: Auto).
+//
+// The decision is pure (manualShipVerdict) so tests prove it with no network.
+
+'use strict';
+
+// Same code as the first-ship question (ship-mode-ask.js, task 1004630): "a question for the
+// person is waiting", distinct from failure (1), usage (2) and the grade cap (6).
+const MANUAL_ASK_EXIT = 5;
+const MANUAL_ASK_MARKER = '[otb-ask-ship-approval]';
+const APPROVED_FLAG = '--person-approved';
+
+// manualShipVerdict({ shipMode, args, env }) → { stop: boolean, why }
+function manualShipVerdict({ shipMode, args = [], env = process.env }) {
+  if (!shipMode || shipMode.mode !== 'manual') return { stop: false, why: 'not_manual' };
+  if (args.includes(APPROVED_FLAG)) return { stop: false, why: 'approved' };
+  if (env.OTB_SUBAGENT === '1') return { stop: false, why: 'unattended_runner' };
+  if (env.CLAUDECODE !== '1') return { stop: false, why: 'person_at_terminal' };
+  return { stop: true, why: 'needs_approval' };
+}
+
+// manualAskLines(args, taskId) — the question the AI puts to the person, and the re-run.
+function manualAskLines(args, taskId) {
+  const rerun = ['node', 'scripts/bongos/ship.js', ...args]
+    .map((a) => (/\s/.test(a) ? JSON.stringify(a) : a)).join(' ');
+  return [
+    `${MANUAL_ASK_MARKER} This project's ship mode is Manual: a person approves each ship.`,
+    `Ask the person whether to ship task ${taskId} now, with two options: Ship it, or Not yet.`,
+    'Only after they say yes, re-run:',
+    '',
+    `  ${rerun} ${APPROVED_FLAG}`,
+    '',
+    'Nothing was resolved: the claim is still active. Never add the flag without their yes.',
+  ];
+}
+
+module.exports = { MANUAL_ASK_EXIT, MANUAL_ASK_MARKER, APPROVED_FLAG, manualShipVerdict, manualAskLines };

package/scripts/bongos/ship-preflight-steps.js

@@ -0,0 +1,399 @@
+// scripts/bongos/ship-preflight-steps.js — the preflight gate (tree, freshness, deletions) + pre-verify doc auto-linkify.
+//
+// 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 1469-1762 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 { execFileSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+const { trackedDirty, cleanupMacFinderDupRefs, untrackedLeftBehind, untrackedWarningLines } = require('../../modules/lifecycle/ship-preflight');
+const { arg } = require('./cli-lib');
+const mergeRegen = require('./git-merge-regen');
+const { argvOut, gitArgvOk, gitOk } = require('./ship-git.js');
+const { pushVia } = require('./ship-deploy-target.js');
+const { computeChangedFiles, computeGraderBaseline } = require('./ship-grade.js');
+const { currentBranch } = require('./ship-regen.js');
+const { BEHIND_MAIN_LIMIT, REPO_ROOT } = require('./ship-state.js');
+
+// ---------- Step 0: preflight (working tree + branch freshness) ----------
+//
+// Catches the 2026-05-10 "phantom ship" bug: builder forgot to stage/commit
+// their actual work. The committed-diff scanner reported clean (because nothing
+// was committed), smoke passed, and the task auto-shipped with zero code
+// change. The fix is to inspect the working tree BEFORE the claim resolves and
+// refuse to proceed when any tracked file has uncommitted/staged changes.
+//
+// Also refuses when the branch is far behind origin/main — merging a stale
+// branch is a known regression vector.
+
+// parseDeletedUpstreamPaths — pure: turn `git log --diff-filter=D --name-only
+// --pretty=format:` output (one deleted path per line, blank lines between
+// commits) into a deduped, order-preserving list. Exported so preflight's
+// upstream-deletion warning (step (d)) is unit-tested without a live git repo.
+// Null/empty input (no matches, or the git call failed closed) → [].
+function parseDeletedUpstreamPaths(rawLogOutput) {
+  if (!rawLogOutput) return [];
+  return [...new Set(rawLogOutput.split('\n').map((s) => s.trim()).filter(Boolean))];
+}
+
+// shipInputPaths — the repo-relative paths of the files a ship was HANDED as input
+// (task 1001436), so preflight's untracked-file warning never lists them. The
+// builder-ship skill writes notes.md + summary.txt into the worktree and passes them
+// here; left in, they would put the warning on nearly every ship and teach everyone
+// to skip it. `-` (stdin), a missing value and a path outside the checkout add
+// nothing — a file outside the tree cannot be an untracked file in it. Both sides go
+// through realpath, so a /var vs /private/var spelling of one file still matches.
+// `cwd`, `repoRoot` and `realpath` are injectable for the unit test.
+const SHIP_INPUT_FLAGS = ['--notes-file', '--summary-file', '--response-file', '--visual'];
+
+function safeRealpath(p) {
+  try { return fs.realpathSync.native(p); } catch (_) { return path.resolve(p); }
+}
+
+function shipInputPaths(args, { cwd = process.cwd(), repoRoot = null, realpath = safeRealpath } = {}) {
+  const root = realpath(repoRoot || gitOk('git rev-parse --show-toplevel') || cwd);
+  const out = [];
+  for (const flag of SHIP_INPUT_FLAGS) {
+    const value = arg(flag, args || []);
+    if (typeof value !== 'string' || value === '' || value === '-' || value.startsWith('--')) continue;
+    const rel = path.relative(root, realpath(path.resolve(cwd, value)));
+    if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) continue;
+    out.push(rel.split(path.sep).join('/'));
+  }
+  return out;
+}
+
+// The code that RUNS the ship and the grade on this machine — what step (c) of
+// preflight() refuses to run from a stale copy. PATHSPECS, not a file list (task
+// 1004273): the list used to name ship.js and grader.js alone, and two carves moved
+// the logic out from under it (task 1003205 split ship.js into ~20 ship-*.js files;
+// grader.js now delegates to grader-*.js, grader-workers/ and grade-engine.js), so a
+// branch behind main on ship-land.js or grader-score.js sailed through. A prefix
+// covers the next carve too. They reach git as argv, never through a shell, so a
+// file that exists ONLY on origin/main (a new carve file) still matches — a shell
+// would have expanded the glob against this checkout and missed exactly that one.
+// tests/ship_preflight.mjs fails if a ship*.js / grader* / grade-engine file is not covered.
+const TOOLING_PATHSPECS = Object.freeze([
+  'scripts/bongos/ship*.js',           // ship.js + every ship-*.js carved out of it
+  'scripts/bongos/smoke-gds.js',
+  'scripts/bongos/cli-lib.js',
+  'scripts/bongos/autobongos-grade-cap.js', // ship.js's entry refuses a capped run with it (task 1004536)
+  'modules/grading/grader*',       // grader.js, grader-*.js, grader-rubric.json, grader-workers/
+  'modules/grading/grade-engine.js', // grader.js requires it (task 1002839)
+]);
+
+// staleToolingFiles — the tooling files origin/main has changed since this branch's
+// merge-base. Three-dot (HEAD...origin/main) scopes to the origin/main side, so the
+// builder's OWN edits to these files (shipping a ship fix) do not count. A failed git
+// call reads as nothing stale, as it always has. `cwd` is injectable for the test.
+function staleToolingFiles({ cwd } = {}) {
+  const out = argvOut('git', ['diff', '--name-only', 'HEAD...origin/main', '--', ...TOOLING_PATHSPECS], cwd ? { cwd } : {});
+  return out ? out.split('\n').map((s) => s.trim()).filter(Boolean) : [];
+}
+
+// opts: { force, inputFiles } — inputFiles is shipInputPaths(args) from the caller;
+// omitted (the resume path has no prose flags), nothing is excluded from the
+// untracked-file warning.
+function preflight(claim, opts = {}) {
+  // (a) Working-tree check — refuse if any TRACKED file carries an uncommitted
+  // modification or staged change. This fires post-commit, so a clean tree
+  // proves the builder's work is actually committed. touches[] cleanup [2/8]
+  // (task 877): this replaced the old touches[]-scoped match, which was skipped
+  // entirely for empty-touches tasks (leaving them unprotected). The plain
+  // clean-tree check is strictly stronger and needs no touches[]. Untracked /
+  // .gitignored files are ignored so autonomous scratch files don't false-refuse.
+  const porcelain = gitOk('git status --porcelain');
+  const dirty = trackedDirty(porcelain);
+  if (dirty.length > 0) {
+    console.log('  preflight: working tree has uncommitted tracked changes:');
+    for (const file of dirty) console.log(`    - ${file}`);
+    console.log('');
+    console.log('  Stage + commit these (or revert them) before shipping.');
+    console.log('  This guard exists because uncommitted work has shipped as "complete" before.');
+    return { ok: false, reason: 'working-tree-dirty' };
+  }
+
+  // (b) Branch-freshness check — refuse if behind origin/main by too much.
+  // Fetch quietly so the comparison is against current remote state. Clean
+  // macOS Finder/iCloud `* 2` duplicate refs first or fetch will fail with
+  // "bad object refs/heads/<name> 2".
+  const cleaned = cleanupMacFinderDupRefs(REPO_ROOT);
+  if (cleaned.length > 0) {
+    console.log(`  preflight: removed ${cleaned.length} stray refs (macOS Finder duplicates)`);
+  }
+  gitOk('git fetch origin main');
+  const behindStr = gitOk('git rev-list --count HEAD..origin/main');
+  const behind = behindStr ? Number(behindStr) : 0;
+  if (Number.isFinite(behind) && behind > 0) {
+    // (b) Branch-freshness is REPORT-ONLY now (#1068). Being behind origin/main
+    // is no longer a refusal: shipMain() merges origin/main INTO the branch up
+    // front (mergeMainIntoBranch), BEFORE the sandbox review gate, so the tree
+    // the human reviews == the tree we ship — killing the post-approval re-stage
+    // loop the #1057 retro hit. We still fetch (above) so that merge + the
+    // stale-tooling guard below see current remote state.
+    const note = behind > BEHIND_MAIN_LIMIT ? ` (well past the ${BEHIND_MAIN_LIMIT}-commit mark)` : '';
+    console.log(`  preflight: branch is ${behind} commit(s) behind origin/main${note} — shipMain merges it in before staging.`);
+  }
+
+  // (c) Stale ship-tooling guard. The behind-limit above is deliberately lenient
+  // so an unrelated commit to main doesn't block every parallel builder — but
+  // that means a branch a FEW commits behind sails through, and if those commits
+  // touched the ship/grade tooling, the builder runs a STALE ship.js / grader.js
+  // / smoke runner and the ship silently fails the same way every time. That was
+  // the #662 root cause (a grader.js predating the Windows spawn fix ran twice).
+  // So: regardless of commit count, refuse if origin/main carries changes to the
+  // tooling that runs the ship locally and this branch lacks them. Three-dot diff
+  // (HEAD...origin/main) scopes to changes on the origin/main side since the
+  // merge-base, so the builder's OWN edits to these files (e.g. shipping a
+  // ship.js fix) do not trip it.
+  const staleTooling = staleToolingFiles();
+  if (staleTooling.length > 0) {
+    if (opts.force) {
+      console.log(`  preflight: ship tooling is behind origin/main (${staleTooling.join(', ')}) — proceeding due to --force`);
+    } else {
+      console.log('  preflight: your ship/grade tooling is behind origin/main:');
+      for (const f of staleTooling) console.log(`    - ${f}`);
+      console.log('  These files RUN the ship + grader locally — shipping with a stale copy silently fails (root cause of #662).');
+      console.log('  Run `git merge origin/main` (or `git pull --rebase origin main`) on this branch, then re-ship. Or --force to override.');
+      return { ok: false, reason: 'stale-tooling' };
+    }
+  }
+
+  // (d) Upstream-deletion warning (WARN-ONLY — never blocks, never changes the
+  // exit code). main can delete or relocate a surface between when a task was
+  // claimed and when it ships (a cutover, a carve, a rename — the R89 hall-ui
+  // cutover class); the branch's own diff still touches the OLD path, and an
+  // oblivious ship can silently revert the upstream deletion or leave this
+  // branch's work orphaned. Scoped to the paths THIS branch's diff actually
+  // touches — the same baseline/diff computeGraderBaseline/computeChangedFiles
+  // compute for the grader — so an unrelated upstream deletion elsewhere in the
+  // repo never fires it. Silent no-op if origin/main isn't resolvable (offline /
+  // never fetched) or this branch's diff is empty — the check itself must never
+  // be why a ship breaks. parseDeletedUpstreamPaths is the pure parsing seam,
+  // exported + unit-tested (tests/ship_upstream_deletion.mjs) without a live git
+  // repo; this block is just the git I/O + presentation around it.
+  const upstreamDelBaseline = computeGraderBaseline(claim);
+  const upstreamDelTouched = upstreamDelBaseline ? computeChangedFiles(upstreamDelBaseline) : [];
+  if (upstreamDelTouched.length > 0) {
+    const deletedUpstreamStr = argvOut('git', [
+      'log', 'HEAD..origin/main', '--diff-filter=D', '--name-only', '--pretty=format:',
+      '--', ...upstreamDelTouched,
+    ]);
+    const deletedUpstream = parseDeletedUpstreamPaths(deletedUpstreamStr);
+    if (deletedUpstream.length > 0) {
+      console.error('');
+      console.error(`⚠ Upstream deletion warning: main has removed ${deletedUpstream.length} path(s) this branch still touches, since this task was claimed:`);
+      for (const f of deletedUpstream) console.error(`    - ${f}`);
+      console.error('  This looks like the R89 hall-ui cutover class: a surface removed or relocated upstream while the claim was in flight.');
+      console.error('  Verify these paths still exist on main (or that the removal/rename is intentional) before shipping —');
+      console.error("  shipping anyway may silently revert the upstream deletion or leave this branch's work orphaned.");
+      console.error('  Warning only — not blocking; the ship proceeds.');
+      console.error('');
+    }
+  }
+
+  // (e) Untracked-file warning (task 1001436) — WARN-ONLY, never blocks, never
+  // changes the exit code. Step (a) ignores untracked files so scratch cannot
+  // false-refuse a ship, which also meant a NEW deliverable left un-added beside
+  // committed work shipped without it, in silence (the residual of the task-1363
+  // phantom ship). This names those files while stopping is still free. It needs
+  // committed work to warn about — upstreamDelTouched is this branch's committed
+  // diff from step (d); with none, the empty-diff guard already refuses and lists
+  // them. Its own `git status`, on purpose: --untracked-files=all names each file
+  // rather than a collapsed `dir/`, so the ship's input files can be excluded
+  // exactly; and a failed or oversized read here stays a skipped warning, never a
+  // blank porcelain for the refusal in step (a).
+  const untrackedPorcelain = gitOk('git status --porcelain --untracked-files=all', { maxBuffer: 64 * 1024 * 1024 });
+  const leftBehind = untrackedLeftBehind(untrackedPorcelain, {
+    committedFileCount: upstreamDelTouched.length,
+    inputs: opts.inputFiles || [],
+  });
+  for (const line of untrackedWarningLines(leftBehind, { taskId: claim && claim.task_id })) console.error(line);
+
+  const treeState = leftBehind.length > 0
+    ? `tracked files clean (${leftBehind.length} untracked file(s) will not ship — see the warning)`
+    : 'working tree clean';
+  console.log(`  preflight: ${treeState}, branch ${behind} commits behind main, ship tooling current — OK`);
+  return { ok: true, untrackedLeftBehind: leftBehind };
+}
+
+// mergeMainIntoBranch — pull origin/main INTO the current feature branch BEFORE
+// the sandbox review gate (#1068, gap 2), so the tree the human reviews == the
+// tree we ship and an --approved lands in ONE shot. This subsumes the old
+// behind-main hard refusal: instead of telling the builder to merge by hand
+// (which then invalidated their just-given sandbox approval — the #1057 retro),
+// we do it up front. Aborts ONLY on a genuine merge conflict (the human must
+// resolve those); a no-op when already current or not on a feature branch. Runs
+// in the session's worktree (currentBranch()/gitOk operate on process.cwd()).
+// Returns { ok, merged, conflict?, reason? }.
+// decidePreMerge — the PURE policy for the pre-stage merge: skip on main/detached
+// HEAD, on the server-publish path, or when already current; otherwise merge.
+// Exported so the truth table is unit-tested with no git. `via` is pushVia()'s
+// verdict ('server' | 'local' | undefined). Returns { action:'skip'|'merge', reason }.
+function decidePreMerge({ branch, behind, via }) {
+  if (!branch || branch === 'main' || branch === 'HEAD') {
+    return { action: 'skip', reason: `not on a feature branch (${branch})` };
+  }
+  // Server-mediated publish (ADR 0055): a credential-less partial-clone checkout
+  // (blob:none, HTTPS origin, no gh/credential-helper — ADR 0053) CANNOT run a
+  // local `git merge origin/main` — the ort merge lazily fetches main's blobs
+  // from the promisor remote and there are no credentials to authenticate that
+  // fetch, so such a checkout strands here and can never ship while behind main, i.e.
+  // ≈always (idea #364). It also does not NEED to: ciLandServer bundles
+  // `origin/main..HEAD` and the SERVER reconciles the branch with the real main
+  // when it pushes + opens + auto-merges the PR; a genuine conflict surfaces
+  // server-side as merge_conflict (publish-reconciler / conflict-resolve,
+  // ADR 0082). The local pre-merge (#1068) is a LAPTOP-path optimization (so the
+  // sandbox-reviewed tree == the shipped tree); it stays exactly as-is there
+  // (via 'local'/undefined) and is simply skipped on the server path.
+  if (via === 'server') {
+    return {
+      action: 'skip',
+      reason: 'server-mediated publish reconciles with origin/main server-side (credential-less partial-clone checkout cannot fetch main blobs locally — idea #364)',
+    };
+  }
+  if (!Number.isFinite(behind) || behind === 0) {
+    return { action: 'skip', reason: 'already up to date with origin/main' };
+  }
+  return { action: 'merge', reason: `${behind} commit(s) behind origin/main` };
+}
+
+function mergeMainIntoBranch() {
+  const branch = currentBranch();
+  // preflight already fetched origin/main + cleaned stray refs; reuse that state.
+  const behindStr = gitOk('git rev-list --count HEAD..origin/main');
+  const behind = behindStr ? Number(behindStr) : 0;
+  const decision = decidePreMerge({ branch, behind, via: pushVia() });
+  if (decision.action === 'skip') {
+    return { ok: true, merged: false, reason: decision.reason };
+  }
+  console.log(`  pre-stage: merging origin/main into ${branch} (${behind} commit(s) behind) so the reviewed tree == the shipped tree...`);
+  const msg = `Merge origin/main into ${branch} (pre-stage freshness, task 1068)`;
+  if (gitArgvOk(['merge', '--no-edit', '-m', msg, 'origin/main'])) {
+    console.log('  pre-stage: merged origin/main cleanly.');
+    return { ok: true, merged: true };
+  }
+  // Conflict (or other merge failure). Before giving up, AUTO-HEAL conflicts that
+  // are confined to GENERATED files (task 1243): docs/repo-map.md + the nested
+  // CLAUDE.md blocks reliably collide between parallel branches (they're rebuilt
+  // from code, so two branches render them differently), and re-resolving them by
+  // hand — three times — was the PR #167 churn. Regenerate them from the merged
+  // tree, stage, and complete the merge. This is the guaranteed-to-run safety net
+  // that backstops the `otb-regen` git merge driver (install-git-hooks.js), which
+  // only fires where it's been registered per-clone.
+  const conflicted = (gitOk('git diff --name-only --diff-filter=U') || '').trim();
+  const files = conflicted ? conflicted.split('\n').map((s) => s.trim()).filter(Boolean) : [];
+  if (files.length && files.every((f) => mergeRegen.REGENERABLE.has(f))) {
+    const healed = files.every((f) => mergeRegen.resolveInWorktree(f));
+    if (healed && gitArgvOk(['add', ...files]) && gitArgvOk(['commit', '--no-edit'])) {
+      console.log(`  pre-stage: auto-healed generated-file conflict(s) by regenerating ${files.join(', ')} from the merged tree.`);
+      return { ok: true, merged: true, healed: files };
+    }
+    // A hand-written conflict remained (resolveInWorktree returned false) or the
+    // commit failed — fall through to the clean abort below; no half-merged tree.
+  }
+  // Abort so the tree is left clean, and surface it — we must NOT ship a
+  // half-merged tree.
+  gitArgvOk(['merge', '--abort']);
+  return {
+    ok: false,
+    merged: false,
+    conflict: true,
+    reason: conflicted
+      ? `merge conflict with origin/main in: ${files.join(', ')}. Resolve on this branch (git merge origin/main), commit, then re-ship`
+      : 'could not merge origin/main into this branch (see git output). Resolve manually, then re-ship',
+  };
+}
+
+// ---------- Pre-verify: auto-linkify the ship's own changed docs ----------
+//
+// The doc-ref-linkify CI gate (tests/linkify_check.mjs, in the required `unit`
+// check — task 1002639; a standalone doc-ref-linkify.yml workflow never
+// actually existed) red-Xes a PR carrying a bare "#NNN" task ref in a doc. A
+// red-X after the builder walked away still strands the land (#747).
+//
+// The structural cure is to fix the ship's OWN changed docs here, before the
+// merge, and commit the rewrite. The gate then stays as the backstop for refs
+// that arrive by other paths (generated docs, direct pushes) but stops firing
+// in the normal /builder-ship path.
+//
+// Scope is deliberately the docs already in THIS commit's diff: rewriting only
+// files the builder already changed means it can NEVER rewrite a doc they
+// didn't touch, and a pre-existing bare ref elsewhere is left for
+// the periodic backlog sweep (`linkify-refs.js --apply`) + the CI gate.
+
+// Pure: which changed paths are in the linkifier's domain (the hand-authored
+// markdown a reader sees on github.com — root CLAUDE.md/README.md + docs/**).
+// Mirrors linkify-refs.js discoverDocs() roots. Exported for unit tests.
+function isLinkifiableDocPath(rel) {
+  return (
+    typeof rel === 'string' &&
+    rel.endsWith('.md') &&
+    (rel === 'CLAUDE.md' || rel === 'README.md' || rel.startsWith('docs/'))
+  );
+}
+
+function autoLinkifyChangedDocs(ac) {
+  const baseline = computeGraderBaseline(ac);
+  let docs = computeChangedFiles(baseline).filter(isLinkifiableDocPath);
+  // Mirror discoverDocs()'s GENERATED-FILE skip — an explicit file set bypasses
+  // it, and rewriting a generated doc just churns until its next regen.
+  docs = docs.filter((rel) => {
+    try {
+      const head = fs.readFileSync(path.resolve(process.cwd(), rel), 'utf8').slice(0, 200);
+      return !/GENERATED FILE/i.test(head);
+    } catch (_) {
+      return false;
+    }
+  });
+  if (docs.length === 0) return;
+
+  console.log(`Auto-linkify: scanning ${docs.length} changed doc(s) for bare "#NNN" task refs...`);
+  const linkifyScript = path.resolve(__dirname, 'linkify-refs.js');
+  try {
+    // --apply (no --check) throws on an unreachable id allow-list; treat any
+    // failure as best-effort and continue — the CI gate is the backstop, a
+    // network blip must never block a ship.
+    execFileSync(process.execPath, [linkifyScript, '--apply', ...docs], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      cwd: process.cwd(),
+    });
+  } catch (err) {
+    const line = (err.message || 'unknown error').split('\n')[0];
+    console.log(`  auto-linkify: skipped (linkifier unavailable: ${line}). CI gate remains the backstop.`);
+    return;
+  }
+
+  // Commit only if the rewrite actually changed something. status --porcelain
+  // over the explicit doc set, via argv (paths can't be spliced into a shell).
+  const dirty = gitOk(`git status --porcelain -- ${docs.map((d) => JSON.stringify(d)).join(' ')}`);
+  if (!dirty) {
+    console.log('  auto-linkify: changed docs already clean — nothing to commit.');
+    return;
+  }
+  gitArgvOk(['add', '--', ...docs]);
+  const committed = gitArgvOk(['commit', '-m', 'chore(docs): auto-linkify task refs before ship (task 747)']);
+  if (committed) {
+    const n = dirty.split('\n').filter(Boolean).length;
+    console.log(`  auto-linkify: rewrote bare task refs in ${n} doc(s) and committed before merge.`);
+  } else {
+    console.log('  auto-linkify: commit failed; continuing (CI gate is the backstop).');
+  }
+}
+
+module.exports = {
+  autoLinkifyChangedDocs,
+  decidePreMerge,
+  isLinkifiableDocPath,
+  mergeMainIntoBranch,
+  parseDeletedUpstreamPaths,
+  preflight,
+  shipInputPaths,
+  staleToolingFiles,
+  TOOLING_PATHSPECS,
+};