@bongos/core 1.19.318 → 1.19.320

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

@@ -0,0 +1,323 @@
+// scripts/gds/ship-preflight-steps.js — the preflight gate (tree, freshness, deletions) + pre-verify doc auto-linkify.
+//
+// Carved out of scripts/gds/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 } = require('../../modules/lifecycle/ship-preflight');
+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))];
+}
+
+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 TOOLING_PATHS = [
+    'scripts/gds/ship.js',
+    'scripts/gds/smoke-gds.js',
+    'scripts/gds/cli-lib.js',
+    'modules/grading/grader.js', // BV1.R73: grading carved to modules/grading/
+  ];
+  const staleToolingStr = gitOk(`git diff --name-only HEAD...origin/main -- ${TOOLING_PATHS.join(' ')}`);
+  const staleTooling = staleToolingStr ? staleToolingStr.trim().split('\n').filter(Boolean) : [];
+  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('');
+    }
+  }
+
+  console.log(`  preflight: working tree clean, branch ${behind} commits behind main, ship tooling current — OK`);
+  return { ok: true };
+}
+
+// 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 dev box
+  // (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 the box 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 box.
+  if (via === 'server') {
+    return {
+      action: 'skip',
+      reason: 'server-mediated publish reconciles with origin/main server-side (credential-less partial-clone box 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,
+};

package/scripts/gds/ship-regen.js

@@ -0,0 +1,286 @@
+// scripts/gds/ship-regen.js — regeneration of the generated artifacts a ship must keep fresh + the merge-worktree lock.
+//
+// Carved out of scripts/gds/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 fs = require('node:fs');
+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 diagram-drift routine will flag any miss.
+//
+// Returns a status string ('skipped-server' | 'regen-failed' | 'current' |
+// 'committed' | 'committed-nofatal') so the regression test (task 1046) can
+// prove the dev-box skip without git or a headless browser.
+function regenerateDiagrams() {
+  // task 1046: on the server-mediated-publish path (a dev box — 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). The box 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; the diagram-drift routine backstops any
+  // staleness in the meantime. 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 dev-box 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 dev-box 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 scripts/gds/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 scripts/gds/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 dev-box
+// 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 docs (docs/api/openapi.json + docs/api-reference.md +
+// docs/routes-permissions.md) from the shipped route tree (task 1918). Pure JS (reads
+// route files, no DB, no headless browser) — safe on EVERY ship path incl. the dev-box
+// server-publish path. Non-fatal: a hiccup must never block a ship; the fitness
+// `gen-api-docs --check` gate backstops staleness on main.
+function regenerateApiDocs() {
+  console.log('  regenerating OpenAPI spec + API reference 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 staleness');
+    return 'regen-failed';
+  }
+  const dirty = gitOk('git status --porcelain docs/api/openapi.json docs/api-reference.md docs/routes-permissions.md');
+  if (!dirty) {
+    console.log('  API docs already current — nothing to commit');
+    return 'current';
+  }
+  shellOk('git add docs/api/openapi.json docs/api-reference.md docs/routes-permissions.md');
+  if (shellOk('git commit -m "chore(api-docs): auto-regenerate OpenAPI spec + reference (task 1918)"')) {
+    console.log('  committed auto-regenerated API docs');
+    return 'committed';
+  }
+  return 'committed-nofatal';
+}
+
+// Refresh the generated typed client (clients/bongos-client) FROM the just-regenerated
+// spec, then keep the devbox vendored CJS copy in lockstep (task 2051). Runs right
+// after regenerateApiDocs so the client reflects the same route tree. Automatic here
+// (not fail-if-forgotten): before this, ship regenerated the spec but not the client,
+// so a route change left the client stale until the api_client test caught it in CI.
+// Non-fatal + safe on every ship path; the api_client freshness test backstops main.
+
+// Where the devbox Electron app vendors the CJS client (ADR 0045). It lives inside the
+// dev-box MODULE (ADR 0145) — an instance that ships without that module has no copy.
+const VENDORED_CLIENT_REL = 'modules/dev-box/app/src/vendor/bongos-client.cjs';
+
+// The git pathspec for the regenerated client. Pure + exported so the rule is unit-tested
+// with no git/fs (task 1002417). `git status` tolerates an unmatched pathspec (exit 0) but
+// `git add` aborts the ENTIRE staging step (exit 128), which leaves the regenerated client
+// unstaged and the worktree dirty — and a dirty worktree makes the ship's auto-merge bail,
+// stranding the task at `confirmed` with no PR. So the vendored copy is named ONLY when it
+// is actually on disk.
+function apiClientPathspec({ worktreeRoot, existsSync = fs.existsSync } = {}) {
+  const paths = ['clients/bongos-client'];
+  if (existsSync(path.join(worktreeRoot, VENDORED_CLIENT_REL))) paths.push(VENDORED_CLIENT_REL);
+  return paths;
+}
+
+function regenerateApiClient() {
+  console.log('  regenerating typed API client (clients/bongos-client) from the OpenAPI spec...');
+  if (!shellOk(`"${process.execPath}" ${JSON.stringify(path.join(__dirname, 'gen-api-client.js'))}`)) {
+    console.log('  api-client regen failed (non-fatal) — CI api_client freshness test backstops staleness');
+    return 'regen-failed';
+  }
+  // The devbox Electron app can't require() clients/ at runtime, so it vendors the CJS
+  // build (ADR 0045); keep the copy byte-identical (the api_client test asserts it).
+  // Present only where the dev-box module ships — an instance without it has no vendored
+  // copy, so both the vendor step and the git pathspec below drop out (task 1002417: the
+  // app moved from top-level devbox-app/ to modules/dev-box/app/ per ADR 0145, and these
+  // paths were not updated, so the guard below silently never fired).
+  // Resolve it WORKTREE-LOCALLY (like the generator above, __dirname=scripts/gds), NOT
+  // via REPO_ROOT: on a ship from a linked worktree REPO_ROOT is the MAIN checkout, so a
+  // REPO_ROOT path would vendor the main tree while gen-api-client just wrote THIS tree,
+  // leaving this worktree's vendored copy stale → the api_client byte-identity test reds
+  // the PR (task 2060 fix). __dirname keeps the generator, the vendored file, and the
+  // git add all on the same tree.
+  const worktreeRoot = path.join(__dirname, '..', '..');
+  const vendorScript = path.join(worktreeRoot, 'modules', 'dev-box', 'app', 'scripts', 'vendor-client.js');
+  if (fs.existsSync(vendorScript)) {
+    shellOk(`"${process.execPath}" ${JSON.stringify(vendorScript)}`);
+  }
+  const clientPathspec = apiClientPathspec({ worktreeRoot }).join(' ');
+  const dirty = gitOk(`git status --porcelain ${clientPathspec}`);
+  if (!dirty) {
+    console.log('  API client already current — nothing to commit');
+    return 'current';
+  }
+  shellOk(`git add ${clientPathspec}`);
+  if (shellOk('git commit -m "chore(api-client): auto-regenerate typed client + devbox vendor (task 2051)"')) {
+    console.log('  committed auto-regenerated API client');
+    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 dev-box 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';
+}
+
+// ---------- 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.
+
+// 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.
+function mainWorktreeBusy() {
+  if (gitOk('git rev-parse -q --verify MERGE_HEAD', { cwd: REPO_ROOT })) {
+    return 'a merge is already in progress';
+  }
+  const dirty = gitOk('git status --porcelain', { cwd: REPO_ROOT });
+  if (dirty && dirty.trim().length > 0) {
+    return 'the working tree is dirty or has unmerged files';
+  }
+  return null;
+}
+
+// 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 = {
+  VENDORED_CLIENT_REL,
+  apiClientPathspec,
+  currentBranch,
+  mainWorktreeBusy,
+  regenerateApiClient,
+  regenerateApiDocs,
+  regenerateDiagrams,
+  regenerateFileMap,
+  regenerateRepoMap,
+  regenerateSessionIndex,
+};