@bongos/core 1.19.525 → 1.19.527

package/modules/lifecycle/routes/lifecycle.js

@@ -26,11 +26,36 @@
 const express = require('express');
 const api = require('../../../src/module-api');
 const lifecycle = require('../lifecycle');
+const db = require('../db');
+const cascade = require('../cascade');
+
+// task 1003549 — the cross-role cascade listener. `task.shipped` already exists
+// as a kernel event (emitted post-commit by the publish reconciler and the ship
+// routes, consumed today by discord's broadcast and sessions' deferred reward),
+// so a ship generating work in ANOTHER role needs no new bus: it is one more
+// listener on the event that already says a ship happened. Registered here for
+// the same reason the port is — `mountModuleRoutes` is the one boot hook that
+// runs in the live server AND whenever a test rebuilds the router.
+//
+// The handle is kept so a re-mount replaces the listener instead of stacking a
+// second one (the discord `_shipListenerOff` precedent); a doubled listener
+// would be harmless anyway, since filing is idempotent on (source, source_ref),
+// but "harmless because something downstream catches it" is not a reason to
+// leave it. Nothing here can affect the ship: the emitters fire post-commit and
+// already wrap the emit, and `runCascadesForShip` resolves rather than throws.
+let _cascadeListenerOff = null;
 
 function registerSeams() {
   if (!api.hasProvider('lifecycle')) {
     api.registerProvider('lifecycle', lifecycle);
   }
+  if (_cascadeListenerOff) _cascadeListenerOff();
+  _cascadeListenerOff = api.on('task.shipped', (shipped) => cascade.runCascadesForShip(shipped, {
+    getTask: (id) => db.getTask(id),
+    findTaskBySourceRef: (ref) => db.findTaskBySourceRef(ref),
+    createTask: (spec) => db.createTask(spec),
+    log: api.logger ? api.logger('lifecycle') : null,
+  }));
 }
 
 module.exports = function buildLifecycleRouter() {

package/modules/lifecycle/tests/cascade.mjs

@@ -0,0 +1,197 @@
+// modules/lifecycle/tests/cascade.mjs — the cross-role cascade (task 1003549 /
+// goal 1000074, the artist's loop).
+//
+// The mechanism's whole value is that a ship in one role can generate work in
+// another WITHOUT ever putting that generation in the ship's way. So the four
+// properties the header of cascade.js promises are what these pin, and three of
+// them are about what must NOT happen:
+//
+//   1. it never blocks the ship — every failure shape resolves to a report
+//   2. it is idempotent — the same ship twice files one task
+//   3. it says where it came from
+//   4. it files at backlog, never ready
+//
+// The production table ships EMPTY (R04 writes the first rule), so the rules
+// below are the test's OWN declarations — which is also the point: a mechanism
+// proved by a rule its consumer has not written yet is proved against the
+// contract rather than against one example.
+//
+// DB-free: the runner takes its three database calls as injected functions.
+
+import { strict as assert } from 'node:assert';
+import path from 'node:path';
+import url from 'node:url';
+import { createRequire } from 'node:module';
+
+const HERE = path.dirname(url.fileURLToPath(import.meta.url));
+const require_ = createRequire(import.meta.url);
+const cascade = require_(path.join(HERE, '..', 'cascade.js'));
+
+let passed = 0;
+let failed = 0;
+async function test(name, fn) {
+  try { await fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.log(`  FAIL ${name}`); console.log(`     ${err.stack || err.message}`); }
+}
+
+console.log('\nlifecycle: a ship in one role generates work in another');
+
+const shipped = (over = {}) => ({
+  id: '9001',
+  version_id: 'BONGOS-V1',
+  goal_id: '1000074',
+  title: 'R09 · Reword the hall empty states',
+  discipline: 'engineer',
+  kind: 'feature',
+  status: 'shipped',
+  ...over,
+});
+
+// A rule of the shape R04 will write: an engineer's ship becomes an artist's task.
+const REVIEW_RULE = {
+  key: 'test-artist-review',
+  discipline: 'artist',
+  when: (t) => t.discipline === 'engineer',
+  title: (t) => `Review the copy that shipped in task ${t.id}`,
+  body: (t) => `Look at what ${t.title} put in front of a person.`,
+};
+
+const stubs = (over = {}) => {
+  const created = [];
+  return {
+    created,
+    deps: {
+      rules: [REVIEW_RULE],
+      getTask: async () => shipped(),
+      findTaskBySourceRef: async () => null,
+      createTask: async (spec) => { created.push(spec); return { id: String(9100 + created.length) }; },
+      ...over,
+    },
+  };
+};
+
+await test('an engineer ship files a task FOR THE ARTIST — the push the queues never had', async () => {
+  const { created, deps } = stubs();
+  const report = await cascade.runCascadesForShip({ id: '9001' }, deps);
+
+  assert.equal(report.errors.length, 0, report.errors.join(' | '));
+  assert.equal(created.length, 1);
+  const spec = created[0];
+  assert.equal(spec.discipline, 'artist', 'the generated work is for a DIFFERENT role than the ship');
+  assert.equal(report.created[0].discipline, 'artist');
+  assert.match(spec.title, /9001/);
+});
+
+await test('the generated task files at backlog and inherits its goal and version', async () => {
+  const { created, deps } = stubs();
+  await cascade.runCascadesForShip({ id: '9001' }, deps);
+  const spec = created[0];
+  assert.equal(spec.status, 'backlog', 'generated work is a REQUEST — auto-filing claimable work mints claims nobody asked for');
+  assert.equal(spec.goalId, 1000074);
+  assert.equal(spec.versionId, 'BONGOS-V1');
+});
+
+await test('it says where it came from, in the ref and in the prose', async () => {
+  const { created, deps } = stubs();
+  await cascade.runCascadesForShip({ id: '9001' }, deps);
+  const spec = created[0];
+  assert.equal(spec.source, 'cascade');
+  assert.equal(spec.sourceRef, 'cascade-test-artist-review-9001');
+  assert.match(spec.description, /task 9001 shipped/);
+  assert.match(spec.description, /test-artist-review/);
+  assert.match(spec.description, /Look at what/, 'the rule\'s own body survives the preamble');
+  // NOT a subtask: cascaded work outlives its trigger and belongs to another role.
+  assert.equal(spec.parentTaskId, undefined);
+});
+
+await test('the same ship twice files ONE task — a reconciler re-sweep is a no-op', async () => {
+  const { created, deps } = stubs();
+  await cascade.runCascadesForShip({ id: '9001' }, deps);
+  assert.equal(created.length, 1);
+
+  // Second pass: the row now exists under the same (source, source_ref).
+  deps.findTaskBySourceRef = async ({ source, sourceRef }) => (
+    source === 'cascade' && sourceRef === 'cascade-test-artist-review-9001' ? { id: '9101' } : null
+  );
+  const again = await cascade.runCascadesForShip({ id: '9001' }, deps);
+  assert.equal(created.length, 1, 'no second row');
+  assert.equal(again.created.length, 0);
+  assert.deepEqual(again.skipped[0], { key: 'test-artist-review', taskId: '9101', reason: 'already filed' });
+});
+
+await test('a rule that does not match files nothing, quietly', async () => {
+  const { created, deps } = stubs({ getTask: async () => shipped({ discipline: 'artist' }) });
+  const report = await cascade.runCascadesForShip({ id: '9001' }, deps);
+  assert.equal(created.length, 0);
+  assert.equal(report.errors.length, 0, 'a non-match is not a problem');
+});
+
+// --- property 1: nothing here may reach the ship ----------------------------
+
+await test('NOTHING a cascade does can fail the ship — every failure shape resolves', async () => {
+  const shapes = {
+    'when() throws': stubs({ rules: [{ ...REVIEW_RULE, when: () => { throw new Error('boom'); } }] }),
+    'title() throws': stubs({ rules: [{ ...REVIEW_RULE, title: () => { throw new Error('boom'); } }] }),
+    'createTask rejects': stubs({ createTask: async () => { throw new Error('db down'); } }),
+    'findTaskBySourceRef rejects': stubs({ findTaskBySourceRef: async () => { throw new Error('db down'); } }),
+    'getTask rejects': stubs({ getTask: async () => { throw new Error('db down'); } }),
+    'getTask returns nothing': stubs({ getTask: async () => null }),
+    'a malformed rule': stubs({ rules: [{ key: 'broken' }] }),
+  };
+  for (const [name, { created, deps }] of Object.entries(shapes)) {
+    const report = await cascade.runCascadesForShip({ id: '9001' }, deps);
+    assert.ok(report && Array.isArray(report.errors), `${name}: returned a report`);
+    assert.ok(report.errors.length > 0, `${name}: and said what went wrong`);
+    assert.equal(created.length, 0, `${name}: filed nothing`);
+  }
+
+  // The payload itself being junk is the same story.
+  for (const junk of [null, undefined, {}, { id: null }]) {
+    const { deps } = stubs();
+    const report = await cascade.runCascadesForShip(junk, deps);
+    assert.ok(report.errors.length > 0, `${JSON.stringify(junk)}: reported rather than threw`);
+  }
+});
+
+await test('one broken rule costs only its own task', async () => {
+  const good = { ...REVIEW_RULE, key: 'good-one' };
+  const bad = { ...REVIEW_RULE, key: 'bad-one', when: () => { throw new Error('boom'); } };
+  const { created, deps } = stubs({ rules: [bad, good] });
+  const report = await cascade.runCascadesForShip({ id: '9001' }, deps);
+  assert.equal(created.length, 1, 'the healthy rule still filed');
+  assert.equal(created[0].sourceRef, 'cascade-good-one-9001');
+  assert.equal(report.errors.length, 1);
+  assert.match(report.errors[0], /bad-one/);
+});
+
+// --- the declaration itself --------------------------------------------------
+
+await test('the production table is valid, and a duplicate key is refused', () => {
+  assert.deepEqual(cascade.validateCascades(), [], 'the shipped CASCADES table must be well-formed');
+  assert.ok(Array.isArray(cascade.CASCADES));
+  assert.equal(Object.isFrozen(cascade.CASCADES), true);
+
+  // Two rules sharing a key would collide on source_ref and silently suppress
+  // one another — the failure that is invisible in production.
+  const errs = cascade.validateCascades([REVIEW_RULE, { ...REVIEW_RULE }]);
+  assert.equal(errs.length, 1);
+  assert.match(errs[0], /duplicate key/);
+
+  // A rule missing any required field is named, field by field.
+  const shape = cascade.assertRuleShape({ key: 'x' });
+  assert.ok(shape.some((p) => /discipline/.test(p)));
+  assert.ok(shape.some((p) => /when/.test(p)));
+  assert.ok(shape.some((p) => /title/.test(p)));
+  assert.ok(shape.some((p) => /body/.test(p)));
+});
+
+await test('the production table ships EMPTY, deliberately — R04 writes the first rule', () => {
+  // If this fails because a rule was added, that is fine: replace the assertion
+  // with one that pins the new rule's key and discipline. It exists so the
+  // emptiness is a DECISION on the record (see cascade.js's header) rather than
+  // something nobody noticed.
+  assert.equal(cascade.CASCADES.length, 0);
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.525",
+  "version": "1.19.527",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.525",
+      "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.525",
+  "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';