@bongos/core 1.19.526 → 1.19.527

package/.claude/skills/ship-check/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: ship-check
+description: >-
+  Run every freshness and fitness check ship.js will run, in one command, before shipping — and get the healing command for each stale generated file. Triggers: "/ship-check", "am I ready to ship", "what will ship trip on", "check before I ship", "is anything stale".
+---
+
+# /ship-check — the pre-ship table
+
+**Script skill (authoritative).** The whole action is one command, run from the worktree you will ship from:
+
+```bash
+node scripts/gds/ship-check.js
+```
+
+Add `--tests` to also run the DB-free unit lane (slow; minutes). Add `--json` for machine output.
+
+## Why this exists
+
+Builders were running the same eight generators and checks by hand, one Bash call at a time — 223
+invocations across 140 sessions in three days — because a ship that fails preflight costs a grader
+run, and the last 30 days of session logs name a stale generated file (`docs/copy-registry.json`,
+a nested `CLAUDE.md` symbol block, `docs/file-map.md`, `docs/api/openapi.json`, the §13 session
+snippet) in roughly a quarter of all sessions. This is that sequence as one call with one table.
+It changes nothing: every step is a `--check`; the **fix →** column is what to run.
+
+## What to do with the output
+
+1. Every `✗` row names the generator to run. Run it, look at the diff it produced, commit it on your
+   branch. Then re-run `/ship-check` until every row is `✓`.
+2. `fitness.js` failures name their own fix inline; warnings are advisory (budgets, ratchets).
+3. With `--tests`: a failing test is only "environmental" if the SAME test fails on an untouched
+   checkout of `origin/main`. Compare by test name, never by count — a Windows baseline of ~25
+   environment failures has masked real regressions before (see `docs/recipes/windows-builders.md`).
+4. When the table is all `✓`, ship: `/builder-ship`. The grader and CI are the remaining gates;
+   this skill removes the preflight trip, not the review.
+
+## Relationship to other tools
+
+- `ship.js` runs these checks itself at ship time and refuses on a stale one; `/ship-check` is the
+  same gate run early, when fixing is cheap.
+- The PostToolUse hook `.claude/hooks/edit-hints.js` tells you the moment an edit makes a generated
+  file stale; `/ship-check` is the sweep that catches whatever the hints did not.
+- `node scripts/gds/preflight.js` checks the MACHINE (node version, node_modules, `claude` auth);
+  this checks the TREE.

package/.claude/skills/strand-fix/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: strand-fix
-description: Walk ONE stranded ship to landed — a task parked at `confirmed` that the server reconciler has already probed and given up on (`needs_rebase_reason` = `strand:no_branch_no_tip` or `strand:land_not_proven`), the shape the SessionStart line calls "will never self-heal". Finds where the work actually is (a main commit, an unpushed local branch, a conflicting PR, or nowhere), does the one sanctioned move for that case, and verifies the flip to `shipped`. Also the fix for a claim refused `409 REBASE_REQUIRED` — that gate is one of YOUR strands. Triggers when the user says "/strand-fix N", "fix strand N", "task N is stranded", "land the strand", "my claim says REBASE_REQUIRED", or after the SessionStart "Stranded ships:" line names a task. For a `completed` (ungraded) task use `/grade-recover`; for a `confirmed` task with no strand reason use `/merge-mode`.
+description: >-
+  Walk ONE stranded ship to landed — a task parked at confirmed that the reconciler gave up on (strand:no_branch_no_tip, strand:land_not_proven). Finds where the work is, makes the one sanctioned move, verifies the flip to shipped. Also the fix for a claim refused 409 REBASE_REQUIRED. Triggers: "/strand-fix N", "task N is stranded", "land the strand", "my claim says REBASE_REQUIRED".
 requires: [gh]
 ---
 

package/.claude/skills/worktree-clean/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: worktree-clean
-description: Remove the per-claim worktrees whose work already landed — every shipped task leaves a `.claude/worktrees/task-N` behind, and nothing else prunes them. Lists what is stale (branch merged into origin/main, or branch already deleted by the ship), shows the list, then removes each through the junction-safe `worktree.js remove` — never raw `git worktree remove`, which follows the node_modules junction into the shared node_modules (task 1002809). Triggers when the user says "/worktree-clean", "clean up worktrees", "prune stale worktrees", "remove old worktrees", or when the SessionStart line reports "Stale worktrees: N".
+description: >-
+  Remove the per-claim worktrees whose work already landed (branch merged into origin/main, or deleted by the ship): lists them, then removes each through the junction-safe worktree.js remove — never raw git worktree remove, which follows the node_modules junction (task 1002809). Triggers: "/worktree-clean", "prune stale worktrees", or the SessionStart line "Stale worktrees: N".
 ---
 
 **Script skill (authoritative).** Two scripts do the work; this skill only sequences them and shows the list before anything is removed.

package/.gitattributes

@@ -58,7 +58,12 @@
 # that conflicts only on these files lands without a human (GitHub's own auto-merge
 # can't run a custom driver, hence the server does the merge locally then pushes).
 # NB: the TOP-LEVEL CLAUDE.md is hand-written and deliberately NOT listed here —
-# only the three nested CLAUDE.md docs carry a generated block. docs/file-map.md
+# only the nested CLAUDE.md docs that carry a generated block are. scripts/gds/CLAUDE.md
+# LEFT that set in task 1003548 (its ~40k-char block was 76% of a file loaded on every
+# visit to that directory; docs/repo-map.md still carries the full index), so its entry
+# came out with it — a path listed here whose generator no longer owns it would route a
+# merge through a driver that cannot regenerate it, which tests/git_merge_regen.mjs
+# asserts against. docs/file-map.md
 # carries two generated section blocks (.claude/skills/ + .claude/scheduled-tasks/,
 # ADR 0066, gen-file-map.js), so it joins the set; docs/session-log-index.md is
 # whole-file generated (gen-session-index.js), so it joins too.
@@ -72,7 +77,6 @@ docs/file-map.md           merge=otb-regen
 docs/session-log-index.md  merge=otb-regen
 src/bongos/CLAUDE.md          merge=otb-regen
 src/bongos/routes/CLAUDE.md   merge=otb-regen
-scripts/gds/CLAUDE.md      merge=otb-regen
 
 # docs/copy-registry.json + docs/copy-inventory.md (task 1003543): the copy
 # registry's committed pair (scripts/gds/copy-inventory.js) — fully generated from

package/docs/file-map.md

@@ -419,6 +419,7 @@ tests/
 ├── recall/SKILL.md                ← /recall — one-call project-knowledge search across repo docs + DB prose (tasks, learnings, session logs)
 ├── scan-before-install/SKILL.md   ← /scan-before-install — quarantine-fetch a third-party repo/plugin, deterministic floor + tiered subagent panel over the scrubbed mirror, arithmetic verdict + honest-limits report to the builder's own config dir; prints install commands (pinned SHA only), never installs (goal 1000055)
 ├── session-handoff/SKILL.md       ← /session-handoff — compose a clean, paste-ready next-steps prompt to START a fresh session with (keeps context light by curating what carries forward); read-only, distinct from /builder-ship's ledger notes and /builder-end's close-out
+├── ship-check/SKILL.md            ← /ship-check — run every freshness + fitness check ship.js will run (repo-map/session-index/file-map/api-docs/copy-registry --check, linkify, skill-lint, fitness; --tests adds the DB-free lane) in ONE command before shipping, with the healing command per stale artifact (task 1003548; script scripts/gds/ship-check.js)
 ├── status/SKILL.md                ← /status — what's the status of X / what's left for criterion Cn (read-only rollup)
 ├── strand-fix/SKILL.md            ← /strand-fix N — walk ONE stranded confirmed task (strand:no_branch_no_tip / land_not_proven — the shape the reconciler gave up on) to shipped: find the work (main commit / unpushed branch / conflicting PR / nowhere), do the one sanctioned move, verify the flip; also clears a 409 REBASE_REQUIRED claim gate (task 1003365)
 └── worktree-clean/SKILL.md        ← /worktree-clean — list the per-claim worktrees whose branch already landed on main (scripts/gds/stale-worktrees.js) and remove each through the junction-safe worktree.js remove; never raw git worktree remove (task 1003365)
@@ -454,11 +455,13 @@ tests/
 
 To install on a new machine, symlink each routine's directory under `~/.claude/scheduled-tasks/`, e.g. `ln -s "<repo>/.claude/scheduled-tasks/overnight-code-review" ~/.claude/scheduled-tasks/overnight-code-review`.
 
-**Claude Code hooks** at `.claude/hooks/` (wired in `.claude/settings.json`; all invoked via `node` so they run on Windows/macOS/Linux alike — [#671](https://example.com/builders#/task/671)):
+**Claude Code hooks** at `.claude/hooks/` (wired in `.claude/settings.json`; all invoked through `run-node.sh`, which finds node even when the hook shell's PATH lacks it, so they run on Windows/macOS/Linux alike (task 1003548) — [#671](https://example.com/builders#/task/671)):
 
 ```
 .claude/hooks/
 ├── secret-gate.js            ← PreToolUse (Edit|Write|MultiEdit|NotebookEdit|Bash): cooperative, fail-OPEN block of secret-shaped content before it reaches the tree or a shell (task 1003125, ADR 0022)
+├── run-node.sh               ← the node resolver every hook command runs through (task 1003548): $OTB_NODE_BIN → PATH → known install dirs → nvm; one actionable line + exit 1 when none is found. 1,055 hook runs had died silently with `node: command not found`
+├── edit-hints.js             ← PostToolUse (Edit|Write|MultiEdit): lints a saved SKILL.md's frontmatter (scripts/gds/skill-lint.js) and names the generator an edited path makes stale (copy-registry, repo-map blocks, file-map, openapi, §13 snippet) with its command (task 1003548)
 ├── git-guard.js              ← PreToolUse (Bash): same contract as secret-gate — blocks `git stash` (repo-global stack, learning 1000215), raw `git worktree remove` (follows the node_modules junction, task 1002809), `git push origin main` (PR-only) and `git branch -D`, each with its remedy; kill-switch BONGOS_GIT_GUARD_OFF=1 (task 1003365)
 ├── _core-resolve.js          ← shared helper, not a hook: locates a core module/script across the monolith vs `node_modules/@cloudbongos/core` layouts; required by most hooks here and by four routine scripts under `.claude/scheduled-tasks/`
 ├── cascade-route.js          ← PreToolUse (Task|Agent): cheapest-sufficient start-model advisory for a subagent spawn (ADR 0024); inert unless OTB_AUTONOMY_ENABLED=1

package/docs/module-api-changelog.md

@@ -1489,5 +1489,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.524 with no explicit bump. run 33823218193. (task 1002620)
   1.19.526 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.525 with no explicit bump. run 33824700579. (task 1002620)
+  1.19.527 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.526 with no explicit bump. run 33827382028. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/docs/recipes/windows-builders.md

@@ -101,3 +101,49 @@ because the server already landed the task first (reconcile-on-read or the ~5-mi
 `ship.js` now normalizes both API error shapes and **verifies the live task status with a GET
 before reporting failure** (task 1002809) — a verified `shipped` prints as the success it is. If
 you see a ship-call failure from older tooling, check `GET /tasks/<id>` before reacting.
+
+## The hook shell can start without node — hooks were silently off (task 1003548)
+
+- **Symptom:** every hook run reports `Failed with non-blocking status code: /usr/bin/bash: line 1: node: command not found`. A transcript scan of 2026-09-01..03 counted **1,055** such runs, which meant `secret-gate`, `git-guard`, `worktree-guard`, `lifecycle-card` and `conductor` were off for whole sessions while Claude Code showed only a muted warning.
+- **Root cause:** Claude Code runs hook commands through Git Bash, and on this machine that shell intermittently starts with a PATH that predates the Node install. The Bash tool inherits the same PATH, which is why sessions also prepended `export PATH="/c/Program Files/nodejs:…"` to 1,404 commands.
+- **What the tooling does now:** every hook command in `.claude/settings.json` goes through `.claude/hooks/run-node.sh`, which finds node on PATH or in the known install dirs (`C:\Program Files\nodejs`, `%LOCALAPPDATA%\Programs\nodejs`, nvm, Homebrew, `/usr/local/bin`) and, when it truly cannot, prints one line naming the fix instead of failing quietly. Override with `OTB_NODE_BIN` in the `env` block of `.claude/settings.local.json` if your node lives somewhere exotic.
+- **For the Bash tool itself:** check once with `command -v node`; prepend PATH only if it is missing. Do not put the prepend on every command — see the next section for why that also collides with worktree isolation.
+
+## Compound `export PATH=…; cd …; …` commands collide with worktree isolation
+
+- **Symptom:** `This session is isolated in the worktree … but this command is too complex to verify that it stays inside` (25×), `… changes directory to the shared checkout` (7×), `… runs export PATH= with a value every later program …` (6×), `… runs a command whose name is computed at runtime` (3×). 1,931 of 2,370 Bash calls in the scan were compound.
+- **Root cause:** a session that entered a worktree (EnterWorktree) has Claude Code checking that each Bash command stays inside it. A chain of `export … ; cd … && …` defeats the checker, so it refuses the whole command.
+- **Fix:** one purpose per command; use paths relative to the worktree (the Bash tool's cwd is the worktree); no `export PATH=` prefix once node is on PATH; never `cd` into the main checkout from a worktree session (learning 2026-08-29: `../../../` checks and dirties the MAIN checkout — run the worktree's own `scripts/gds/` copy).
+
+## `git fetch` / `git push` / `ls-remote` fail here BY DESIGN
+
+- This machine holds no GitHub push credential (ADR 0031 §6 / ADR 0055). The scan found 22 `git fetch` attempts in three days, all wasted. Landing is server-mediated: `/builder-ship` uploads a bundle and the server pushes, opens the PR and lands it. To see whether work reached GitHub use `GET /api/gds/tasks/:id/publish-status`, never a raw git probe. To base a new worktree on fresh main, `node scripts/gds/worktree.js add <task-id> --base origin/main` (worktree.js fetches through the sanctioned path).
+
+## A worktree without `node_modules` fails 300+ tests — and the count is not the signal
+
+- **Symptom:** `Cannot find module 'pg'` / `'express'`; `npm test` reports ~300 FAILED; 9 `npm install`s and 2 dead junctions in three days of transcripts.
+- **What the tooling does now:** SessionStart prints one `[otb] node_modules is missing …` line (from `scripts/gds/preflight.js`'s check) when neither the worktree nor the main checkout has it. Install ONCE in the main checkout (`npm ci`); inside-repo worktrees resolve from it.
+- **Rule:** when comparing a local run against CI, compare failing test NAMES against an untouched checkout of `origin/main`, never counts — a ~25-failure Windows baseline has masked real regressions (session logs 2026-08-14, 2026-08-19). `node scripts/gds/ship-check.js --tests` prints the names.
+
+## `tests/git_merge_regen.mjs` — when it reds, suspect `.gitattributes` first, not Windows
+
+This test is the consistency gate between **two** sources that must agree, and it is the one that
+caught a real bug during task 1003548, so read its assertion before blaming the platform:
+
+- **Every path declared `merge=otb-regen` in `.gitattributes` must be in `REGENERABLE`**
+  (`scripts/gds/git-merge-regen.js`, derived from `gen-repo-map.NESTED_DIRS` + the whole-file set).
+  Drop a doc from the generators and its `.gitattributes` line has to come out in the same commit —
+  otherwise a merge on that path routes through a driver that cannot regenerate it. The failure reads
+  `.gitattributes declares merge=otb-regen for <path> but REGENERABLE … does not know it`.
+- **A `real git merge must auto-resolve via the driver; got 1` failure** with a mangled driver path
+  (`Cannot find module 'C:\…\Temp\otb-gitmerge-*\<redacted>…'`) has been seen on this
+  machine and then stopped reproducing in all three trees (worktree, baseline worktree, main
+  checkout) — so treat it as intermittent, not as a standing Windows defect. Do NOT record it as a
+  known baseline failure: doing so is what let a genuine regression hide behind it for a whole
+  session. Re-run it, and follow the naming rule above — if it fails on your branch and passes on an
+  untouched `origin/main` worktree, it is yours.
+
+## CRLF: a multi-line find silently misses, and a whole-file diff is usually line endings
+
+- Several hall files (`people.css`, `people.html`, `style.css`, the privacy spec) and every `.claude/skills/*/SKILL.md` are CRLF; `scripts/gds/*.js` and the tests are LF. An exact-string patch must detect the file's EOL before joining lines (`text.includes('\r\n') ? '\r\n' : '\n'`), or the find matches nothing and the edit is a silent no-op (session log 2026-08-24).
+- A `git diff --stat` that touches every line of a file you barely edited is an EOL flip — check with `git diff --stat --ignore-cr-at-eol`, and restore the original EOL before committing.

package/modules/grading/generated-provenance.js

@@ -58,7 +58,7 @@ const GENERATORS = [
     owns: [
       { file: 'src/bongos/CLAUDE.md', scope: 'fence', marker: 'BEGIN GENERATED REPO-MAP' },
       { file: 'src/bongos/routes/CLAUDE.md', scope: 'fence', marker: 'BEGIN GENERATED REPO-MAP' },
-      { file: 'scripts/gds/CLAUDE.md', scope: 'fence', marker: 'BEGIN GENERATED REPO-MAP' },
+      // scripts/gds/CLAUDE.md left NESTED_DIRS in task 1003548 — it carries no fence any more.
     ],
   },
   {

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.526",
+  "version": "1.19.527",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.526",
+      "version": "1.19.527",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.526",
+  "version": "1.19.527",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/claude-materialize.js

@@ -48,9 +48,14 @@ function scriptToVerb(verbs = VERBS) {
 // skills + settings.json hooks use. The optional $CLAUDE_PROJECT_DIR/ or ./ prefix and surrounding
 // quote are consumed so the whole thing collapses to the bongos form. `.claude/hooks/<x>.js` refs are
 // deliberately NOT matched (this targets scripts/gds/) — those stay instance-local after materialize.
-const GDS_INVOCATION_RE = /node\s+"?(?:\$CLAUDE_PROJECT_DIR\/|\.\/)?scripts\/gds\/([a-zA-Z0-9_-]+)\.js"?/g;
+// The launcher is bare `node`, OR the hook resolver `sh "$CLAUDE_PROJECT_DIR/.claude/hooks/run-node.sh"`
+// that every settings.json hook command goes through since task 1003548 (it finds node when the hook
+// shell's PATH lacks it). Both collapse to the same bongos form; a resolver call whose target is a
+// .claude/hooks/*.js stays untouched exactly like the bare-node form did.
+const LAUNCHER = String.raw`(?:node|sh\s+"?(?:\$CLAUDE_PROJECT_DIR\/|\.\/)?\.claude\/hooks\/run-node\.sh"?)`;
+const GDS_INVOCATION_RE = new RegExp(LAUNCHER + String.raw`\s+"?(?:\$CLAUDE_PROJECT_DIR\/|\.\/)?scripts\/gds\/([a-zA-Z0-9_-]+)\.js"?`, 'g');
 // A non-gds core script under scripts/ (rare in skills, but keep the transform total).
-const OTHER_SCRIPT_RE = /node\s+"?(?:\$CLAUDE_PROJECT_DIR\/|\.\/)?scripts\/((?!gds\/)[a-zA-Z0-9_./-]+\.js)"?/g;
+const OTHER_SCRIPT_RE = new RegExp(LAUNCHER + String.raw`\s+"?(?:\$CLAUDE_PROJECT_DIR\/|\.\/)?scripts\/((?!gds\/)[a-zA-Z0-9_./-]+\.js)"?`, 'g');
 
 // Pure: rewrite core-script invocations in a skill/settings command string to the bongos bin.
 // Idempotent (a string with no matching invocation is returned unchanged).

package/scripts/gds/fitness.js

@@ -182,7 +182,7 @@ function checkGeneratedArtifactsFresh() {
   try {
     execFileSync(process.execPath, [path.join(__dirname, 'gen-repo-map.js'), '--check-block'], { cwd: REPO_ROOT, stdio: 'pipe' });
   } catch {
-    violations.push('The tracked nested-doc symbol blocks (src/bongos/CLAUDE.md, src/bongos/routes/CLAUDE.md, scripts/gds/CLAUDE.md) are STALE — run `node scripts/gds/gen-repo-map.js` and commit (ADR 0063 / ADR 0110). NB docs/repo-map.md itself is gitignored + deploy-regenerated, not gated here.');
+    violations.push('The tracked nested-doc symbol blocks (src/bongos/CLAUDE.md, src/bongos/routes/CLAUDE.md) are STALE — run `node scripts/gds/gen-repo-map.js` and commit (ADR 0063 / ADR 0110). NB docs/repo-map.md itself is gitignored + deploy-regenerated, not gated here.');
   }
   try {
     execFileSync(process.execPath, [path.join(__dirname, 'gen-session-index.js'), '--check-block'], { cwd: REPO_ROOT, stdio: 'pipe' });
@@ -1295,9 +1295,48 @@ function checkErrorEnvelope() {
   };
 }
 
+// ============================================================================
+// Check 2c — every SKILL.md frontmatter parses the way Claude Code's YAML reader reads it (task 1003548)
+// ============================================================================
+// Ten of fifty skills shipped with an unquoted description holding ": " or " #": YAML dropped or
+// truncated EVERY field, the skill matched on its body text, and nothing in CI noticed. A parse
+// error is a hard fail; description length and the listing budget are advisory (the listing is
+// resident in every session, ~1% of context, and gets truncated past ~8k chars). The check reads
+// the instance's .claude/skills/ and is a quiet pass when a checkout carries none (published core).
+function checkSkillFrontmatter() {
+  const violations = [];
+  const warnings = [];
+  let lint;
+  try { lint = require('./skill-lint'); } catch (e) {
+    return { name: 'skill frontmatter parses (task 1003548)', ok: true, hardFail: false, violations, warnings: [`skill-lint unavailable: ${e.message}`], note: 'linter missing — check skipped.' };
+  }
+  const files = lint.listSkillFiles(INSTANCE_ROOT);
+  const report = lint.lintSkills(files);
+  const rel = (f) => path.relative(INSTANCE_ROOT, f).replace(/\\/g, '/');
+  const long = [];
+  for (const r of report.results) {
+    for (const e of r.errors) violations.push(`${rel(r.file)}: ${e}`);
+    if (r.description.length > lint.DESC_WARN_CHARS) long.push({ file: rel(r.file), n: r.description.length });
+  }
+  if (long.length) {
+    long.sort((a, b) => b.n - a.n);
+    warnings.push(`${long.length} description(s) over ${lint.DESC_WARN_CHARS} chars (longest: ${long.slice(0, 4).map((l) => `${l.file.split('/')[2]} ${l.n}`).join(', ')}) — every char is resident in every session; run node scripts/gds/skill-lint.js.`);
+  }
+  if (report.overBudget) warnings.push(`the skill listing is ${report.listingChars} chars (~${estTokens(report.listingChars)} tokens) against a ~${report.budgetChars}-char budget — Claude Code truncates entries past it and routing degrades.`);
+  return {
+    name: 'skill frontmatter parses (task 1003548)',
+    ok: violations.length === 0,
+    hardFail: violations.length > 0,
+    violations,
+    warnings,
+    note: `${report.results.length} SKILL.md file(s) under .claude/skills/ parse as YAML (name + description present, no ": " / " #" in a plain scalar); length + listing budget advisory.`,
+  };
+}
+
 const CHECKS = [
   checkCoreHostBoundary,
   checkClaudeMdBudget,
+  checkSkillFrontmatter,
   checkNestedDocsPresent,
   checkRankGuards,
   checkGeneratedArtifactsFresh,

package/scripts/gds/gen-repo-map.js

@@ -61,7 +61,9 @@ const SCAN_ROOTS = [...CORE_SCAN_ROOTS, ...INSTANCE_SCAN_ROOTS, MODULE_SCAN_ROOT
 
 // Directories whose nested CLAUDE.md gets a generated symbol-skeleton block (must already exist —
 // they are authored in Path A / ADR 0061; this only refreshes the factual half). All CORE dirs.
-const NESTED_DIRS = ['src/bongos', 'src/bongos/routes', 'scripts/gds'];
+// scripts/gds dropped (task 1003548): its block had grown to ~40k chars — 76% of a file every builder
+// session loads when it touches claim/ship. docs/repo-map.md still carries the full index.
+const NESTED_DIRS = ['src/bongos', 'src/bongos/routes'];
 
 const EXCLUDE_DIR = new Set(['node_modules', '.git', 'tests', 'test', 'vendor']);
 const TOP_GLOBAL = 50;      // global "most-referenced" table cap

package/scripts/gds/session-cost.js

@@ -331,13 +331,13 @@ async function main() {
     if (!transcriptPath) transcriptPath = newestTranscriptFor(cwd);
     if (!transcriptPath || !fs.existsSync(transcriptPath)) {
       // nothing to price — quiet skip
-      process.exit(0);
+      return;
     }
     if (!sessionId) sessionId = path.basename(transcriptPath, '.jsonl');
 
     // No GDS session → nothing to attribute spend to; skip quietly.
     const session = await loadSession();
-    if (!session || !session.token) process.exit(0);
+    if (!session || !session.token) return;
 
     const inter = priceTranscript(transcriptPath);
 
@@ -347,7 +347,7 @@ async function main() {
     const sub = priceSubagents(sessionDir);
 
     const total = inter.total + sub.subagentTotal;
-    if (!(total > 0)) process.exit(0);
+    if (!(total > 0)) return;
 
     // task 1344: split into call-site-tagged, tier-carrying rows; cron sessions
     // are tagged via OTB_COST_CRON_ROUTINE.
@@ -362,7 +362,7 @@ async function main() {
         console.log(`  ${r.source} (${r.source_ref}) $${r.amount_usd.toFixed(4)}  tiers: fresh $${r.tiers.fresh_input_usd} / cache_read $${r.tiers.cache_read_usd} / cache_write $${r.tiers.cache_write_usd} / output $${r.tiers.output_usd}`);
       }
       console.log(`  reconcile: prior-single $${built.priorSingle.toFixed(4)} vs rows-sum $${built.rowsTotal.toFixed(4)} (Δ $${Math.abs(built.priorSingle - built.rowsTotal).toFixed(4)})`);
-      process.exit(0);
+      return;
     }
 
     const api = await cliClient({ allowUnauthenticated: true });
@@ -389,18 +389,21 @@ async function main() {
         console.error(`session-cost: skipped (non-fatal): HTTP ${res.status} for ${r.source}`);
       }
     }
-    process.exit(0);
+    return;
   } catch (err) {
     // Best-effort: never break session exit.
     console.error('session-cost: skipped (non-fatal):', err && err.message ? err.message : err);
-    process.exit(0);
+    return;
   }
 }
 
 // Run only when invoked directly (the SessionEnd hook / CLI). When required by a
 // test, expose the pure-ish helpers without firing the IIFE / network / exit.
 if (require.main === module) {
-  main();
+  // Drain instead of process.exit(): an exit while a socket/child handle is still closing aborts node on
+  // Windows (UV_HANDLE_CLOSING, src\win\async.c) — 59 SessionStart/UserPromptSubmit runs died that way
+  // (task 1003548). The unref'd backstop only fires if a hung request keeps the loop alive.
+  main().catch(() => {}).finally(() => { process.exitCode = 0; setTimeout(() => process.exit(0), 1500).unref(); });
 }
 
 module.exports = {

package/scripts/gds/session-digest.js

@@ -127,12 +127,12 @@ async function main() {
     });
 
     if (!transcriptPath) transcriptPath = newestTranscriptFor(cwd || process.cwd());
-    if (!transcriptPath || !fs.existsSync(transcriptPath)) process.exit(0); // nothing to capture
+    if (!transcriptPath || !fs.existsSync(transcriptPath)) return; // nothing to capture
     if (!sessionId) sessionId = path.basename(transcriptPath, '.jsonl');
 
     // No GDS session → nothing to attribute the digest to; skip quietly.
     const session = await loadSession();
-    if (!session || !session.token) process.exit(0);
+    if (!session || !session.token) return;
 
     // Secret hygiene: buildSessionDigest (ship.js) is the PRIMARY scrubber — it
     // redacts known secret PATTERNS + a high-entropy catch-all (task 1003).
@@ -180,10 +180,13 @@ async function main() {
   } catch (e) {
     console.error('session-digest: skipped —', e && e.message ? e.message : e);
   } finally {
-    process.exit(0);
+    return;
   }
 }
 
-if (require.main === module) main();
+// Drain instead of process.exit(): an exit while a socket/child handle is still closing aborts node on
+// Windows (UV_HANDLE_CLOSING, src\win\async.c) — 59 SessionStart/UserPromptSubmit runs died that way
+// (task 1003548). The unref'd backstop only fires if a hung request keeps the loop alive.
+if (require.main === module) main().catch(() => {}).finally(() => { process.exitCode = 0; setTimeout(() => process.exit(0), 1500).unref(); });
 
 module.exports = { parseHookInput };

package/scripts/gds/ship-check.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+// scripts/gds/ship-check.js — run every freshness/fitness check ship.js will run, in one command,
+// BEFORE you ship, and print the healing command for each stale thing.
+//
+// Why (task 1003548): a scan of 140 sessions found builders running these generators and checks by
+// hand 223 times in three days (fitness.js ×84, gen-repo-map ×41, copy-inventory ×42, gen-api-docs
+// ×16, linkify-refs ×13, docs-entropy ×12, gen-file-map ×9, gen-session-index ×6), one Bash call at
+// a time, because a ship that fails preflight costs a grader run. The last 30 days of session logs
+// name a stale generated file in roughly a quarter of all sessions. This is that sequence as one
+// call with one table. It CHANGES NOTHING: every step is a --check; the "fix" column is what to run.
+//
+// Usage:
+//   node scripts/gds/ship-check.js            checks only (fast; no tests)
+//   node scripts/gds/ship-check.js --tests    also run the DB-free unit lane (npm test) and list failures
+//   node scripts/gds/ship-check.js --json
+// Exit 1 when any check is stale/failing, 0 when everything is fresh.
+'use strict';
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+
+// Each step: a label, the argv to run (node scripts run with THIS node), the command that heals it,
+// and how to read a non-zero exit. `optional` steps are skipped when their script is absent.
+const STEPS = [
+  { key: 'fitness', label: 'fitness.js (architecture + budgets + freshness gate)', argv: ['scripts/gds/fitness.js'], fix: 'read the ✗ lines above; each names its fix' },
+  { key: 'repo-map', label: 'nested CLAUDE.md symbol blocks fresh', argv: ['scripts/gds/gen-repo-map.js', '--check-block'], fix: 'node scripts/gds/gen-repo-map.js' },
+  { key: 'session-index', label: 'CLAUDE.md §13 session snippet fresh', argv: ['scripts/gds/gen-session-index.js', '--check-block'], fix: 'node scripts/gds/gen-session-index.js' },
+  { key: 'file-map', label: 'docs/file-map.md skills/routines sections fresh', argv: ['scripts/gds/gen-file-map.js', '--check'], fix: 'node scripts/gds/gen-file-map.js (+ a note in docs/file-map.notes.json for a new skill)' },
+  { key: 'api-docs', label: 'docs/api/openapi.json + api-reference fresh', argv: ['scripts/gds/gen-api-docs.js', '--check'], fix: 'node scripts/gds/gen-api-docs.js' },
+  { key: 'copy-registry', label: 'docs/copy-registry.json fresh', argv: ['scripts/gds/copy-inventory.js', '--check'], fix: 'node scripts/gds/copy-inventory.js', optional: true },
+  { key: 'linkify', label: 'no bare #NNN task refs in committed markdown', argv: ['scripts/gds/linkify-refs.js', '--check'], fix: 'node scripts/gds/linkify-refs.js', optional: true },
+  { key: 'skill-lint', label: 'SKILL.md frontmatter parses', argv: ['scripts/gds/skill-lint.js'], fix: 'fix the ✗ lines (description: >- block scalars)' },
+  { key: 'tests', label: 'DB-free unit lane (npm test)', argv: ['scripts/gds/run-unit-tests.js'], fix: 'read the FAIL lines; compare against origin/main before calling any of them environmental', onlyWith: '--tests', slow: true },
+];
+
+function runStep(step, { cwd = REPO_ROOT } = {}) {
+  const script = path.join(cwd, step.argv[0]);
+  if (!fs.existsSync(script)) return { ...step, status: step.optional ? 'skipped' : 'missing', ms: 0, tail: `${step.argv[0]} not present` };
+  const t0 = Date.now();
+  const r = spawnSync(process.execPath, [script, ...step.argv.slice(1)], { cwd, encoding: 'utf8', timeout: step.slow ? 15 * 60 * 1000 : 5 * 60 * 1000, env: { ...process.env, GDS_QUIET: '1' } });
+  const out = ((r.stdout || '') + (r.stderr || '')).trim().split(/\r?\n/);
+  const failing = out.filter((l) => /^\s*(✗|FAIL|not ok|STALE|✘)/.test(l) || /STALE|is stale|would update|failed/i.test(l));
+  return { ...step, status: r.status === 0 ? 'ok' : 'fail', code: r.status, signal: r.signal, ms: Date.now() - t0, tail: (failing.length ? failing : out.slice(-4)).slice(0, 12).join('\n') };
+}
+
+function summarize(results) {
+  const stale = results.filter((r) => r.status === 'fail' || r.status === 'missing');
+  return { ok: stale.length === 0, stale: stale.map((r) => r.key), results };
+}
+
+function format(summary) {
+  const lines = ['ship-check — what ship.js will trip on', ''];
+  for (const r of summary.results) {
+    const mark = r.status === 'ok' ? '✓' : r.status === 'skipped' ? '·' : '✗';
+    lines.push(`${mark} ${r.label}  (${r.ms} ms)`);
+    if (r.status !== 'ok' && r.status !== 'skipped') {
+      for (const t of String(r.tail).split('\n')) lines.push(`    ${t}`);
+      lines.push(`    fix → ${r.fix}`);
+    }
+  }
+  lines.push('');
+  lines.push(summary.ok ? 'all fresh — ship.js preflight should pass; the grader and CI are the remaining gates.' : `${summary.stale.length} stale: ${summary.stale.join(', ')} — heal, commit, re-run.`);
+  return lines.join('\n');
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const steps = STEPS.filter((s) => !s.onlyWith || argv.includes(s.onlyWith));
+  const results = steps.map((s) => runStep(s));
+  const summary = summarize(results);
+  console.log(argv.includes('--json') ? JSON.stringify(summary, null, 1) : format(summary));
+  process.exitCode = summary.ok ? 0 : 1;
+}
+
+module.exports = { STEPS, runStep, summarize, format };
+if (require.main === module) main();

package/scripts/gds/ship-regen.js

@@ -87,12 +87,12 @@ function regenerateRepoMap() {
     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');
+  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 scripts/gds/CLAUDE.md');
+  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';