@bongos/core 1.19.761 → 1.19.763

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.761",
-  "core_contract": "1.19.761",
-  "source_commit": "3412fa5f1d7bb5d383191d64806396f61b136ae5",
+  "core_version": "1.19.763",
+  "core_contract": "1.19.763",
+  "source_commit": "d56c0dce70d9d91b47d04673af4ed036f6456415",
   "source_ref": "HEAD",
-  "built_at": "2026-09-16T03:36:29.589Z",
+  "built_at": "2026-09-16T04:43:46.371Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 483,
     "agent_docs_stubbed": 25,
-    "functional_verbatim": 2115,
+    "functional_verbatim": 2117,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2623,
-  "tree_sha256": "e9ee270455be1db1f07c7c206e5f9ba6a408a2f231634a18330a70ac78a0ed59",
+  "file_count": 2625,
+  "tree_sha256": "d1d3bb6923feb8c9a3191045a69e641c553b0ac0d9ca4b973e8f0f63c48b67d9",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2512,7 +2512,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "94b5d8c1844e775937a9acec9a78b5c2a789ed6e8e194835c02cd0d2634a4d29"
+      "sha256": "ef6513a9bb60c6532ad6b981c24e7e867aaeb75a85d874b7d6e67842de9cda5a"
     },
     {
       "path": "docs/modules-contract.md",
@@ -7567,12 +7567,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "172d01adc5b82fa70d7079ec41e84a7a99b89b84c40c58d8d383b45c7a18f584"
+      "sha256": "3331982a91d6104fac63e458b3f10d7fb6e1388ba91a8ebf2245019e5d056720"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "7f3d59f7939972bb1a32c493f4203e0c22286a3296ae69d9a11a06ed2c5d62a9"
+      "sha256": "da63833600ca5e2e1d01eb5e6382bd53896d586f0f5b4e899b8616bd854f3009"
     },
     {
       "path": "public-docs/index.html",
@@ -7707,7 +7707,7 @@
     {
       "path": "scripts/gds/audit-ships.js",
       "mode": "0000644",
-      "sha256": "8dbba68d9b8c0635263f3dfb4a223edb14621fb715aa9ab603ea8220313f9dfa"
+      "sha256": "ffcb9068753855fcb0c1ea5c69fddbe97c4c5cb72f225ec38ca4c599d5aca24a"
     },
     {
       "path": "scripts/gds/autonomy-gate.js",
@@ -8062,7 +8062,7 @@
     {
       "path": "scripts/gds/fitness-ratchets.js",
       "mode": "0000644",
-      "sha256": "7a0828405f5069ef97dedfa0874c156507f3ec10651c0e45cfd62d31315275d7"
+      "sha256": "b3f4092fffd30e50cb145b524beeed5d483132f52e77e37a7ab9c18bbf300bc7"
     },
     {
       "path": "scripts/gds/fitness.js",
@@ -9382,7 +9382,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "3429cc6b1beee6916f92a274dd2e85be55cb7e10236d8d70c4a4a8cf7ac6387c"
+      "sha256": "d57ef047cc14ac346694d7a0507103b2b2b85583553786a3c21ba6aacac329c2"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -9654,6 +9654,11 @@
       "mode": "0000644",
       "sha256": "4973872431cb0e5e7aedb978f4d5b28f804fe33aa8288f16d2656a28c85befbe"
     },
+    {
+      "path": "tests/audit_ships_git_argv.mjs",
+      "mode": "0000644",
+      "sha256": "bb7f06a866ccea00a88d2f373c70f7e4bc0a3aa5e658c61346046b83637baa35"
+    },
     {
       "path": "tests/auth_admission_gate.mjs",
       "mode": "0000644",
@@ -10532,7 +10537,7 @@
     {
       "path": "tests/fitness_ratchets.mjs",
       "mode": "0000644",
-      "sha256": "e33edfa4925694d824c042f1fd06a977f1ac14b5c1cb24b5326014ca9f86ece0"
+      "sha256": "949526efc49c317a7be7e33beea0643b29748f3fd4e914d3a3670ce9ce6aadeb"
     },
     {
       "path": "tests/fitness_two_root.mjs",
@@ -10589,6 +10594,11 @@
       "mode": "0000644",
       "sha256": "850113ed91babc9eb54dc22231f194d283fd3f94cee9deef1e6e0bf6f3a969c2"
     },
+    {
+      "path": "tests/github_push_stderr_truncation.mjs",
+      "mode": "0000644",
+      "sha256": "d400c1830c9255851682c1653841a616ab9088f6facb2a5893f0ec41a72626eb"
+    },
     {
       "path": "tests/github_repo_visibility.mjs",
       "mode": "0000644",

package/docs/module-api-changelog.md

@@ -1996,5 +1996,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.759 with no explicit bump. run 35052040282. (task 1002620)
   1.19.761 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.760 with no explicit bump. run 35052410219. (task 1002620)
+  1.19.762 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.761 with no explicit bump. run 35053643269. (task 1002620)
+  1.19.763 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.762 with no explicit bump. run 35056690992. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.761",
+  "version": "1.19.763",
   "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/audit-ships.js

@@ -9,35 +9,92 @@
 // Audit-only — does NOT write to task_grades. Pre-grader ships keep clean
 // history.
 
-const { execSync } = require('node:child_process');
+const { execFileSync } = require('node:child_process');
 const grader = require('../../modules/grading/grader');
 const { cliClient } = require('./cli-lib');
 
+// EVERY git call here goes through argv, never a shell string (task 1003223 —
+// the class task 1002761 named and task 1002526 fixed in docs-entropy).
+//
+// WHAT WAS WRONG. Five call sites built shell strings. THREE of them interpolated
+// a quoted empty `--format=''`; a POSIX shell strips those quotes and git sees an
+// empty format, but the shell Node uses on Windows does not, so git receives
+// `--format=''` literally and dies with `fatal: invalid --pretty format: ''`.
+// Verified on win32 before fixing: the shell-string form throws, the argv form
+// returns " 1 file changed, 139 insertions(+)". The correct argv spelling is
+// `--format=` — empty value, no quotes, which no shell can mangle because no
+// shell is involved. The other two passed `--format='%H %s'`, which survives a
+// POSIX shell and arrives with literal quotes elsewhere; same class, same fix.
+//
+// WHY IT MATTERED MORE THAN A LOUD CRASH. The originating row asked whether the
+// try/catch around these calls "degrades to a silently empty audit — if so it is
+// the same dangerous shape after all". It did. Every catch returned null or [],
+// so on Windows the audit reported no diff stats and zero downstream impact for
+// EVERY ship, and looked like a clean run. `gitFails` below keeps the same return
+// values but says so on stderr, so an empty audit can never again be mistaken for
+// an uneventful one.
+//
+// One of the five also built a `grep | head | awk` pipeline and pinned
+// `shell: '/bin/bash'` to survive; that filtering is now done in JS, so the script
+// needs no shell at all.
+function gitLines(args, { cwd } = {}) {
+  return execFileSync('git', args, { cwd, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 })
+    .split('\n').map((s) => s.trim()).filter(Boolean);
+}
+
+// One place that reports a git failure instead of swallowing it. Returns the
+// caller's fallback so behaviour is unchanged; only the silence is.
+function gitFails(what, err, fallback) {
+  const msg = String((err && (err.stderr || err.message)) || err).trim().split('\n')[0];
+  console.error(`audit-ships: ${what} failed — ${msg}`);
+  return fallback;
+}
+
 const DAYS = Number(process.env.AUDIT_DAYS || 2);
 
+// `git log --all` once per RUN, not once per task.
+//
+// The shell pipeline this replaced ended in `head -1`, which let git stop as soon
+// as one subject matched. The argv rewrite has no such early exit — and
+// findCommitForTask is called once per shipped task, up to 500 in a run — so a
+// naive port turned one bounded call into 500 full history walks. The commit list
+// cannot change mid-run, so it is read once and reused. Caught by the grader on
+// the first round of this task, which is a fair catch: replacing a shell pipeline
+// means inheriting the work its operators were doing, not just its output.
+let commitSubjectsCache = null;
+function commitSubjects() {
+  if (commitSubjectsCache) return commitSubjectsCache;
+  commitSubjectsCache = gitLines(['log', '--all', '--format=%H %s']);
+  return commitSubjectsCache;
+}
+
 function findCommitForTask(taskId) {
-  let sha;
+  // Matches both subject conventions: the legacy ' #NNN:' prefix and the de-#-ed
+  // 'task NNN:' form ship.js writes since task 916 (a bare "#NNN" in commit
+  // subjects autolinked to dead GitHub issue numbers).
+  //
+  // The grep|head|awk pipeline this replaces needed `shell: '/bin/bash'` to run at
+  // all — a hard dependency on a POSIX shell at a fixed path, for filtering JS can
+  // do. Doing it here also makes the id match EXACT: the old regex was
+  // interpolated unescaped, so a task id was pasted straight into a regex.
+  const re = new RegExp(` (?:#|task )${String(taskId).replace(/[^0-9]/g, '')}:`);
+  let lines;
   try {
-    sha = execSync(
-      // Matches both subject conventions: the legacy ' #NNN:' prefix and the
-      // de-#-ed 'task NNN:' form ship.js writes since task 916 (a bare "#NNN"
-      // in commit subjects autolinked to dead GitHub issue numbers).
-      `git log --all --format='%H %s' | grep -E ' (#|task )${taskId}:' | head -1 | awk '{print $1}'`,
-      { encoding: 'utf8', shell: '/bin/bash' }
-    ).trim();
-  } catch (_) {
-    return null;
+    lines = commitSubjects();
+  } catch (e) {
+    return gitFails(`finding the commit for task ${taskId}`, e, null);
   }
-  return sha || null;
+  const hit = lines.find((l) => re.test(l));
+  return hit ? (hit.split(' ')[0] || null) : null;
 }
 
 function gitDiffStatsForCommit(sha) {
   if (!sha) return null;
   let raw;
   try {
-    raw = execSync(`git show --shortstat --format='' ${sha}`, { encoding: 'utf8' });
-  } catch (_) {
-    return null;
+    raw = execFileSync('git', ['show', '--shortstat', '--format=', sha], { encoding: 'utf8' });
+  } catch (e) {
+    return gitFails(`reading diff stats for ${String(sha).slice(0, 8)}`, e, null);
   }
   // Example shortstat line: " 15 files changed, 1171 insertions(+), 65 deletions(-)"
   const m = raw.match(/(\d+) files? changed(?:, (\d+) insertions?\(\+\))?(?:, (\d+) deletions?\(-\))?/);
@@ -53,10 +110,9 @@ function gitDiffStatsForCommit(sha) {
 function filesTouchedByCommit(sha) {
   if (!sha) return [];
   try {
-    const out = execSync(`git show --name-only --format='' ${sha}`, { encoding: 'utf8' });
-    return out.split('\n').map((s) => s.trim()).filter(Boolean);
-  } catch (_) {
-    return [];
+    return gitLines(['show', '--name-only', '--format=', sha]);
+  } catch (e) {
+    return gitFails(`listing files touched by ${String(sha).slice(0, 8)}`, e, []);
   }
 }
 
@@ -64,35 +120,30 @@ function filesTouchedByCommit(sha) {
 // from origin/main that landed AFTER `sha` and touched any of `files`. High
 // count = subsequent work has built on top of this change, so a "redo"
 // risks conflicts. Excludes `sha` itself.
+const NO_DOWNSTREAM = Object.freeze({
+  commits_after_touching_files: 0, distinct_files_touched: 0, sample_subjects: [],
+});
+
 function downstreamImpact(sha, files) {
-  if (!sha || files.length === 0) {
-    return { commits_after_touching_files: 0, distinct_files_touched: 0, sample_subjects: [] };
-  }
-  // -- shell-quote each file path so spaces/specials don't break the cmd.
-  const fileArgs = files.map((f) => `'${f.replace(/'/g, "'\\''")}'`).join(' ');
-  let out;
+  if (!sha || files.length === 0) return { ...NO_DOWNSTREAM };
+  // The hand-rolled POSIX shell-quoting this replaces ("'" + escape + "'") was
+  // both unnecessary and wrong on Windows, where that quoting style is not the
+  // shell's. In argv form a path with spaces, quotes or a `$` is just an element.
+  const range = `${sha}..origin/main`;
+  let lines;
   try {
-    out = execSync(
-      `git log ${sha}..origin/main --format='%H %s' -- ${fileArgs}`,
-      { encoding: 'utf8' }
-    );
-  } catch (_) {
-    return { commits_after_touching_files: 0, distinct_files_touched: 0, sample_subjects: [] };
+    lines = gitLines(['log', range, '--format=%H %s', '--', ...files]);
+  } catch (e) {
+    return gitFails(`reading downstream commits after ${String(sha).slice(0, 8)}`, e, { ...NO_DOWNSTREAM });
   }
-  const lines = out.split('\n').map((s) => s.trim()).filter(Boolean);
   // Distinct downstream files touched
   let distinct = 0;
   try {
-    const namesOut = execSync(
-      `git log ${sha}..origin/main --name-only --format='' -- ${fileArgs}`,
-      { encoding: 'utf8' }
-    );
-    const set = new Set(
-      namesOut.split('\n').map((s) => s.trim()).filter(Boolean)
-    );
-    distinct = set.size;
-  } catch (_) {
-    distinct = 0;
+    distinct = new Set(gitLines(['log', range, '--name-only', '--format=', '--', ...files])).size;
+  } catch (e) {
+    // Same shape as every other call site: the fallback comes FROM gitFails, so
+    // the value and the report can never drift apart.
+    distinct = gitFails(`reading downstream files after ${String(sha).slice(0, 8)}`, e, 0);
   }
   return {
     commits_after_touching_files: lines.length,
@@ -251,7 +302,18 @@ async function main() {
   for (const [k, v] of Object.entries(buckets)) console.log(`  ${k}: ${v}`);
 }
 
-main().catch((err) => {
-  console.error(err);
-  process.exit(1);
-});
+// Run only as a CLI. Without this guard the file executes main() — and hits the
+// API — the instant anything requires it, which is why its git helpers had never
+// been tested: there was no way to reach them without starting an audit
+// (task 1003223).
+if (require.main === module) {
+  main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+}
+
+// Exported for tests/audit_ships_git_argv.mjs — the argv-vs-shell-string fix is a
+// property of THESE functions, so the test drives them rather than re-typing an
+// equivalent git call and hoping it matches.
+module.exports = { findCommitForTask, gitDiffStatsForCommit, filesTouchedByCommit, downstreamImpact };

package/scripts/gds/fitness-ratchets.js

@@ -243,10 +243,20 @@ function knipIssueCount() {
 //
 // The file's own header says raising a baseline to pass CI is out of policy;
 // deleting the file must not be the loophole that raising it is not.
-function readBaselines() {
+//
+// `baselinePath` is injectable for TESTS ONLY (task 1003351) and defaults to the
+// real file, so every production caller is unchanged. The three task-1003227
+// cases used to prove the three unreadable shapes by renaming and overwriting the
+// repo's OWN config/fitness-baselines.json, restoring in a finally — and
+// run-unit-tests.js runs each file under a 90s execFileSync timeout, whose
+// SIGTERM skips the finally and leaves the last payload on disk. That is how a
+// real checkout ended up with {"_comment":"no metrics key"} committed-adjacent
+// and the sibling case dying on `Cannot read properties of undefined`. A test
+// must not have to survive being killed to leave the repo intact.
+function readBaselines(baselinePath = BASELINE_PATH) {
   let raw;
   try {
-    raw = fs.readFileSync(BASELINE_PATH, 'utf8');
+    raw = fs.readFileSync(baselinePath, 'utf8');
   } catch (e) {
     const missing = e && e.code === 'ENOENT';
     return {
@@ -355,9 +365,17 @@ function computeMetrics({ withDocs = true } = {}) {
 }
 
 // The fitness.js check (in-suite, hermetic — everything except knip).
-function checkQualityRatchets() {
-  const metrics = computeMetrics();
-  const { metrics: baselines, error: baselineError } = readBaselines();
+//
+// Both options are injectable for TESTS ONLY (task 1003351); fitness.js calls
+// this through `CHECKS.map((fn) => fn())`, with no arguments, so the defaults are
+// what production runs. `metrics` matters as much as `baselinePath` here: a test
+// that only wanted to prove an unreadable baseline file still paid for a full
+// computeMetrics() sweep — git ls-files plus every tracked .js plus the
+// docs-entropy scan, measured at 23.7s + 2.5s + 2.8s, i.e. ~29s of this file's
+// 29s runtime, which is what pushed it into the 90s timeout in the first place.
+function checkQualityRatchets({ baselinePath = BASELINE_PATH, metrics: injectedMetrics = null } = {}) {
+  const metrics = injectedMetrics === null ? computeMetrics() : injectedMetrics;
+  const { metrics: baselines, error: baselineError } = readBaselines(baselinePath);
   const { violations, warnings } = compareToBaselines(metrics, baselines);
   // task 1003227: an unreadable baseline file is a hard failure, not silence. Put it
   // FIRST so it is the headline rather than buried under per-metric noise.
@@ -434,6 +452,9 @@ if (require.main === module) main();
 
 module.exports = {
   checkQualityRatchets,
+  // Exported for tests/fitness_ratchets.mjs (task 1003351), which proves the
+  // injected baselinePath is honoured rather than silently falling back.
+  readBaselines,
   computeMetrics,
   compareToBaselines,
   duplicateWindowCount,

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.761'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.763'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/audit_ships_git_argv.mjs

@@ -0,0 +1,173 @@
+// tests/audit_ships_git_argv.mjs — audit-ships' git calls must be argv, not a
+// shell string (task 1003223; the class task 1002761 named).
+//
+// THE BUG. Five calls interpolated `--format=''` into a shell string. A POSIX
+// shell strips the quotes and git sees an empty format; the shell Node uses on
+// Windows does not, so git receives `--format=''` literally and dies with
+// `fatal: invalid --pretty format: ''`. A sixth built a `grep | head | awk`
+// pipeline and pinned `shell: '/bin/bash'` to survive at all.
+//
+// WHY THIS NEEDS A TEST AND NOT JUST A FIX. Every one of those calls sat inside a
+// try/catch that returned null or []. So the Windows failure did not crash the
+// audit — it produced an audit with no diff stats and zero downstream impact for
+// every ship, which is indistinguishable from a clean run. The originating row
+// asked exactly this ("check whether the catch degrades to a silently empty audit
+// — if so it is the same dangerous shape after all"). It did.
+//
+// The static half of this file is the real net: it is the half that stays true on
+// Linux CI, where the shell-string form would have passed happily forever.
+//
+// Run:  node --test tests/audit_ships_git_argv.mjs
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { execSync, execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const FILE = path.join(ROOT, 'scripts/gds/audit-ships.js');
+const audit = require('../scripts/gds/audit-ships.js');
+const raw = fs.readFileSync(FILE, 'utf8');
+
+// Scan CODE, not prose. The file's header explains the bug by quoting the exact
+// tokens that are banned ("--format=''", "grep -E", "shell: '/bin/bash'"), so a
+// naive scan of the whole file fails on its own documentation — which is exactly
+// what happened when this test was first written. Same comments-stripped posture
+// as scripts/gds/category-advisory-guard.js.
+const src = raw
+  .replace(/\/\*[\s\S]*?\*\//g, '')          // block comments
+  .split('\n').map((l) => l.replace(/(^|\s)\/\/.*$/, '$1')).join('\n');
+
+// ---- static: the shape that broke must not come back ----------------------
+
+test('no execSync anywhere — a shell string is what mangles the quoting', () => {
+  assert.doesNotMatch(src, /\bexecSync\b/,
+    'audit-ships must spawn git through execFileSync with an argv array');
+});
+
+test("no quoted --format='' — the argv spelling is --format= with no quotes", () => {
+  // Match the SHELL form precisely: two consecutive quotes after the '='. A naive
+  // /--format='/ also matches the correct argv literal '--format=', where that
+  // quote is JS string syntax, not a shell quote — it flagged the fix as the bug.
+  assert.doesNotMatch(src, /--format=''/,
+    "a quoted empty format is the exact token git rejects on Windows");
+  assert.match(src, /'--format='/, 'the argv spelling is present');
+});
+
+test('no shell pipeline and no pinned /bin/bash', () => {
+  assert.doesNotMatch(src, /\bshell:\s*['"]/, 'no shell is needed once calls are argv');
+  for (const tool of ['grep -E', '| head', '| awk']) {
+    assert.ok(!src.includes(tool), `${tool} is a POSIX-only dependency`);
+  }
+});
+
+test('git failures are reported, not swallowed into a clean-looking audit', () => {
+  // The silent `catch (_) { return null; }` is what made the Windows breakage
+  // invisible. Every catch around a git call must go through gitFails.
+  assert.match(raw, /function gitFails\(/, 'the reporting helper exists');
+  // Scoped to catches returning an empty RESULT SET — null or [] — which is the
+  // shape that turned a git failure into a clean-looking audit. A catch returning
+  // `{}` for an unreadable branding pack is a different, legitimate default and is
+  // deliberately not swept up here.
+  const silent = src.match(/catch \(_\)\s*\{\s*return (?:null|\[\])/g) || [];
+  assert.equal(silent.length, 0,
+    `silent catch(es) returning an empty result: ${silent.join(' | ')}`);
+});
+
+// ---- behavioural: the calls actually work on THIS platform ----------------
+//
+// These run real git against this repo, which is what makes them meaningful on
+// Windows: before the fix, two of them threw here and returned empty.
+
+const git = (args) => execFileSync('git', args, { cwd: ROOT, encoding: 'utf8' }).trim();
+// A NON-MERGE commit. `git show --name-only` prints nothing for a merge by
+// default, so anchoring on HEAD makes the file-listing assertions depend on
+// whatever happened to be checked out — they failed here for that reason, not
+// because the code was wrong. --no-merges picks a commit that really touched files.
+const HEAD = git(['rev-list', '--no-merges', '-n', '1', 'HEAD']);
+
+test('the exact argv git rejected as a shell string succeeds here', () => {
+  const out = execFileSync('git', ['show', '--shortstat', '--format=', HEAD], { cwd: ROOT, encoding: 'utf8' });
+  assert.match(out, /\d+ files? changed/, `shortstat should parse, got: ${JSON.stringify(out.slice(0, 80))}`);
+});
+
+test('the shell-string form is what actually fails on this platform', () => {
+  // Not a hypothetical: assert the OLD form's behaviour so the reason for the fix
+  // is recorded in a runnable way. On POSIX it succeeds (the quotes are stripped),
+  // on Windows it throws — either way, argv is the only spelling that is correct
+  // on both, which is the whole point.
+  let threw = false;
+  try { execSync(`git show --shortstat --format='' ${HEAD}`, { cwd: ROOT, encoding: 'utf8' }); }
+  catch { threw = true; }
+  if (process.platform === 'win32') {
+    assert.equal(threw, true, 'on win32 the quoted form must be the one that fails');
+  } else {
+    assert.equal(threw, false, 'on POSIX it happens to work — which is why this hid on CI');
+  }
+});
+
+test('--name-only --format= yields real paths', () => {
+  const out = execFileSync('git', ['show', '--name-only', '--format=', HEAD], { cwd: ROOT, encoding: 'utf8' });
+  const files = out.split('\n').map((s) => s.trim()).filter(Boolean);
+  assert.ok(files.length > 0, 'HEAD touched at least one file');
+  assert.ok(files.every((f) => !f.includes("'")), 'paths come back unquoted');
+});
+
+// ---- the real functions, not equivalents ---------------------------------
+//
+// These drive audit-ships' own helpers. Before this task the file executed main()
+// on require — it hit the API the moment anything imported it — so its git helpers
+// had never been reachable from a test at all. That is the deeper reason the
+// Windows breakage went unnoticed for months.
+
+test('gitDiffStatsForCommit returns real stats on this platform', () => {
+  const stats = audit.gitDiffStatsForCommit(HEAD);
+  assert.ok(stats, 'must not be the null the Windows failure returned');
+  assert.equal(stats.commit_sha, HEAD);
+  assert.ok(stats.files_changed > 0, `files_changed should be positive, got ${stats.files_changed}`);
+});
+
+test('filesTouchedByCommit returns real paths, not the empty array of a swallowed failure', () => {
+  const files = audit.filesTouchedByCommit(HEAD);
+  assert.ok(Array.isArray(files) && files.length > 0, `expected paths, got ${JSON.stringify(files)}`);
+  assert.ok(files.every((f) => typeof f === 'string' && f.length > 0));
+});
+
+test('the commit list is read once per run, not once per task', () => {
+  // The shell pipeline this replaced ended in `head -1`, so git stopped at the
+  // first match. The argv form has no early exit, and findCommitForTask runs once
+  // per shipped task — up to 500 a run — so a naive port turns one bounded call
+  // into 500 full history walks. Caught by the grader on this task's first round.
+  //
+  // Measured rather than asserted structurally: the second lookup must not spend
+  // anywhere near the first's time, because it must not touch git at all.
+  const t0 = process.hrtime.bigint();
+  audit.findCommitForTask(999999901);
+  const cold = process.hrtime.bigint() - t0;
+
+  const t1 = process.hrtime.bigint();
+  audit.findCommitForTask(999999902);
+  const warm = process.hrtime.bigint() - t1;
+
+  assert.ok(warm * 5n < cold || warm < 2_000_000n,
+    `second lookup should reuse the cached list (cold ${cold / 1000000n}ms, warm ${warm / 1000000n}ms)`);
+});
+
+test('the helpers still answer safely for a missing sha', () => {
+  assert.equal(audit.gitDiffStatsForCommit(null), null);
+  assert.deepEqual(audit.filesTouchedByCommit(null), []);
+  assert.deepEqual(audit.downstreamImpact(null, ['x']),
+    { commits_after_touching_files: 0, distinct_files_touched: 0, sample_subjects: [] });
+});
+
+test('a path containing a space survives argv — the hand-rolled quoting is gone', () => {
+  // git log -- <pathspec> with a space used to need shell quoting; in argv it is
+  // simply one element. An unmatched pathspec returns empty, never an error.
+  const out = execFileSync('git', ['log', '-1', '--format=%H', '--', 'no such file.md'], { cwd: ROOT, encoding: 'utf8' });
+  assert.equal(out.trim(), '', 'an unmatched pathspec is empty, not a crash');
+});
+

package/tests/fitness_ratchets.mjs

@@ -10,6 +10,71 @@ import { fileURLToPath } from 'node:url';
 
 const require = createRequire(import.meta.url);
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+// Task 1003351 — the tripwire, installed BEFORE fitness-ratchets.js is required.
+// Fixing today's three cases only fixes today's three cases; the hazard is the
+// SHAPE, and it is an easy one to reach for again ("just back it up and restore
+// in a finally"). A finally is not a guarantee — run-unit-tests.js kills this
+// file on a 90s timeout and SIGTERM skips it — so the rule is stronger than
+// "restore afterwards": a test in this file may not write under <ROOT>/config at
+// all. Failing at the write names the offending path, which is far easier to act
+// on than the delayed symptom it used to produce (a dirty tree, and a sibling
+// case dying on a mangled baseline one run later).
+//
+// WHICH ARGUMENT IS THE WRITE. This is the whole subtlety, and getting it wrong
+// makes the guard worse than none — it would read as comprehensive while missing
+// the exact call the original bug used. fs.copyFileSync(src, DEST) and
+// fs.renameSync(old, NEW) write to their SECOND argument, so a restore-direction
+// `fs.copyFileSync(backup, real)` — precisely what the old `finally` blocks ran —
+// passes a harmless temp path in position 0. Every method is therefore listed
+// with the argument indices that are WRITE positions, not assumed to be [0].
+// renameSync guards BOTH: position 1 writes into config/, and position 0 moves a
+// file OUT of it, which is how the ABSENT-baseline case used to work.
+const CONFIG_WRITE_ARGS = {
+  writeFileSync: [0],
+  appendFileSync: [0],
+  unlinkSync: [0],
+  rmSync: [0],
+  truncateSync: [0],
+  mkdirSync: [0],
+  renameSync: [0, 1],
+  copyFileSync: [1],
+  cpSync: [1],
+  linkSync: [1],
+  symlinkSync: [1],
+};
+
+{
+  const fs = require('node:fs');
+  const CONFIG_DIR = path.join(ROOT, 'config');
+  const underConfig = (value) => {
+    // Only string paths are resolvable; an fd or a URL is not a path here and
+    // passes through to the real call untouched.
+    if (typeof value !== 'string') return null;
+    const resolved = path.resolve(value);
+    const inside = resolved === CONFIG_DIR || resolved.startsWith(CONFIG_DIR + path.sep);
+    return inside ? resolved : null;
+  };
+  for (const [name, writeArgs] of Object.entries(CONFIG_WRITE_ARGS)) {
+    const original = fs[name];
+    if (typeof original !== 'function') continue;
+    fs[name] = function guarded(...args) {
+      for (const i of writeArgs) {
+        const hit = underConfig(args[i]);
+        if (hit) {
+          throw new Error(
+            `tests/fitness_ratchets.mjs may not fs.${name} under <ROOT>/config — got ${hit} `
+            + `(argument ${i}). Task 1003351: a timeout SIGTERM skips your finally and the repo `
+            + 'keeps the payload. Pass a temp path via checkQualityRatchets({ baselinePath }) / '
+            + 'readBaselines(path) instead.',
+          );
+        }
+      }
+      return original.apply(this, args);
+    };
+  }
+}
+
 const rat = require(path.join(ROOT, 'scripts', 'gds', 'fitness-ratchets.js'));
 
 test('ratchet compare: worse fails, equal passes, better nudges, unknown warns', () => {
@@ -103,53 +168,102 @@ test('the committed baseline file parses and covers every hermetic metric', () =
 // (pure) for the metric-level rules and exercise the file-level rule by pointing at a
 // baseline that does not exist.
 
-test('1003227 an ABSENT baseline file makes the gate hard-fail, not pass', async () => {
+// Task 1003351: these three used to prove their point by renaming/overwriting the
+// repo's own config/fitness-baselines.json and restoring in a `finally`. That is
+// only safe if the process is allowed to finish, and it is not: run-unit-tests.js
+// runs each test file under execFileSync with a 90s timeout, and the SIGTERM that
+// enforces it skips `finally` entirely. Since each case also called the real
+// checkQualityRatchets() — a ~29s full-repo sweep — this file sat right at the
+// timeout, so the kill was the normal outcome rather than the rare one. It left
+// {"_comment":"no metrics key"} as the committed file's contents, which then made
+// the sibling case die on `Cannot read properties of undefined (reading
+// 'oversized_file_count')` and the working tree dirty. Observed on Windows
+// 2026-08-29; standalone `node tests/fitness_ratchets.mjs` never reproduced it,
+// because nothing imposes the timeout there.
+//
+// Now each case owns a baseline file in its own temp dir and injects synthetic
+// metrics, so there is no sweep, no shared file, and nothing to restore. A
+// killed process leaves the repo exactly as it found it.
+const tmpBaseline = (contents) => {
   const fs = require('node:fs');
-  const real = rat.BASELINE_PATH;
-  const backup = `${real}.1003227-test-backup`;
-  const had = fs.existsSync(real);
-  if (had) fs.renameSync(real, backup);
-  try {
-    const r = rat.checkQualityRatchets();
-    assert.equal(r.hardFail, true, 'a gate that cannot read its floors must not report a pass');
-    assert.ok(r.violations.length > 0, 'and it must say so as a VIOLATION, not a warning');
-    assert.match(r.violations[0], /MISSING/, 'the first violation names the real cause');
-    assert.match(r.violations[0], /fails CLOSED/i, 'and states the posture explicitly');
-  } finally {
-    if (had) fs.renameSync(backup, real);
-  }
+  const os = require('node:os');
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ratchet-baseline-'));
+  const file = path.join(dir, 'fitness-baselines.json');
+  if (contents !== null) fs.writeFileSync(file, contents);
+  return file;
+};
+// Any non-empty metric map exercises compareToBaselines without a repo sweep. An
+// unknown metric is a WARNING, never a violation, so violations[0] is the
+// baseline error itself — which is the whole point of each assertion below.
+const SYNTHETIC_METRICS = { excess_lines_total: 1 };
+
+test('1003227 an ABSENT baseline file makes the gate hard-fail, not pass', async () => {
+  const r = rat.checkQualityRatchets({ baselinePath: tmpBaseline(null), metrics: SYNTHETIC_METRICS });
+  assert.equal(r.hardFail, true, 'a gate that cannot read its floors must not report a pass');
+  assert.ok(r.violations.length > 0, 'and it must say so as a VIOLATION, not a warning');
+  assert.match(r.violations[0], /MISSING/, 'the first violation names the real cause');
+  assert.match(r.violations[0], /fails CLOSED/i, 'and states the posture explicitly');
 });
 
 test('1003227 a MALFORMED baseline file also hard-fails', async () => {
-  const fs = require('node:fs');
-  const real = rat.BASELINE_PATH;
-  const backup = `${real}.1003227-test-backup2`;
-  const had = fs.existsSync(real);
-  if (had) fs.copyFileSync(real, backup);
-  try {
-    fs.writeFileSync(real, '{ this is not json');
-    const r = rat.checkQualityRatchets();
-    assert.equal(r.hardFail, true, 'unparseable is no more verifiable than absent');
-    assert.match(r.violations[0], /not valid JSON/);
-  } finally {
-    if (had) { fs.copyFileSync(backup, real); fs.unlinkSync(backup); }
-  }
+  const r = rat.checkQualityRatchets({
+    baselinePath: tmpBaseline('{ this is not json'), metrics: SYNTHETIC_METRICS,
+  });
+  assert.equal(r.hardFail, true, 'unparseable is no more verifiable than absent');
+  assert.match(r.violations[0], /not valid JSON/);
 });
 
 test('1003227 a baseline file with no "metrics" object hard-fails', async () => {
+  const r = rat.checkQualityRatchets({
+    baselinePath: tmpBaseline(JSON.stringify({ _comment: 'no metrics key' })),
+    metrics: SYNTHETIC_METRICS,
+  });
+  assert.equal(r.hardFail, true);
+  assert.match(r.violations[0], /no "metrics" object/);
+});
+
+test('1003351 the config/ write-guard actually fires — a tripwire nobody has tripped is not a tripwire', () => {
   const fs = require('node:fs');
-  const real = rat.BASELINE_PATH;
-  const backup = `${real}.1003227-test-backup3`;
-  const had = fs.existsSync(real);
-  if (had) fs.copyFileSync(real, backup);
-  try {
-    fs.writeFileSync(real, JSON.stringify({ _comment: 'no metrics key' }));
-    const r = rat.checkQualityRatchets();
-    assert.equal(r.hardFail, true);
-    assert.match(r.violations[0], /no "metrics" object/);
-  } finally {
-    if (had) { fs.copyFileSync(backup, real); fs.unlinkSync(backup); }
-  }
+  // Every probe is chosen so an UNGUARDED call cannot damage anything: each one
+  // names a source or a parent directory that does not exist, so without the
+  // guard it raises ENOENT instead of moving a real file into config/. That is
+  // what makes the MESSAGE match load-bearing rather than decorative — a bare
+  // assert.throws() would pass on the very failure it exists to catch.
+  const guarded = /may not fs\.\w+ under <ROOT>\/config/;
+  const real = path.join(ROOT, 'config', 'fitness-baselines.json');
+  const absent = path.join(ROOT, 'config', '.1003351-absent-dir', 'probe.json');
+  const noSuchSource = path.join(ROOT, 'config', '..', '.1003351-no-such-source');
+
+  assert.throws(() => fs.unlinkSync(real), guarded, 'unlinkSync on the real baseline');
+  assert.throws(() => fs.writeFileSync(absent, 'x'), guarded,
+    'a NESTED write under config/ — the guard is on the prefix, not one filename');
+
+  // The destination-argument cases. These are the ones that matter most: they are
+  // the restore direction the original buggy finally blocks used, and a guard that
+  // only inspected argument 0 would wave every one of them through.
+  assert.throws(() => fs.copyFileSync(noSuchSource, real), guarded,
+    'copyFileSync writes to argument 1 — the restore call the old tests ran');
+  assert.throws(() => fs.renameSync(noSuchSource, real), guarded,
+    'renameSync writes to argument 1');
+  assert.throws(() => fs.renameSync(real, noSuchSource), guarded,
+    'renameSync argument 0 moves the baseline OUT of config/ — the ABSENT case');
+
+  // And it is a guard, not a blanket ban on writing: temp paths still work, and a
+  // copy whose DESTINATION is outside config/ is legitimate even when it reads
+  // the real baseline.
+  const tmpDest = tmpBaseline('{"metrics":{}}');
+  assert.ok(fs.existsSync(tmpDest), 'writes outside config/ are untouched');
+  fs.copyFileSync(real, tmpDest);
+  assert.ok(fs.readFileSync(tmpDest, 'utf8').includes('metrics'), 'reading the real baseline is allowed');
+});
+
+test('1003351 the real baseline path still reads cleanly — the injected path is a test seam, not a bypass', () => {
+  const real = rat.readBaselines();
+  assert.equal(real.error, null, 'the committed baseline file parses');
+  assert.ok(real.metrics && typeof real.metrics === 'object', 'and yields a metrics map');
+  const injected = rat.readBaselines(tmpBaseline(JSON.stringify({ metrics: { only_me: 1 } })));
+  assert.deepEqual(injected.metrics, { only_me: 1 }, 'an injected path is actually honoured');
+  assert.notDeepEqual(injected.metrics, real.metrics, 'and does not fall back to the real file');
 });
 
 test('1003227 a missing KEY for a NEW metric stays a warning (adding a metric must not brick CI)', () => {

package/tests/github_push_stderr_truncation.mjs

@@ -0,0 +1,139 @@
+// tests/github_push_stderr_truncation.mjs — the builder-facing git stderr must
+// keep the line that names the CAUSE, even when the cap bites (task 1003199).
+//
+// THE INCIDENT. The server-mediated publish rejected three pushes with
+// `remote: fatal error in commit_refs`. The server log kept that line; the
+// builder's client did not. stderr was head-sliced at 500 chars (and again at 200
+// on the way out), so what reached the person who had to act was clipped mid-word
+// at `error: failed` — naming neither cause nor remedy. They correctly stopped and
+// filed blocker 1000117; diagnosing it took ten minutes in a separate session, the
+// round trip took a day, and two finished tasks sat outside main throughout.
+//
+// Task 1003222 fixed the truncation: the cap went 500 → 8000 and became head+tail
+// with a loud marker instead of a blind head-slice. It exported truncateLoudly
+// "so its behaviour is testable, not just its effect" — and then no test was
+// written. This is that test.
+//
+// WHY THE SHAPE OF THE FIXTURES MATTERS. git puts the useful line LAST: the
+// `remote:` lines follow the progress chatter, and a non-fast-forward failure pads
+// itself with a long `hint:` block. A head-only truncation therefore throws away
+// precisely the causal line, on precisely the errors that need it. Both fixtures
+// below are built to EXCEED the cap — the originating row's own warning was that a
+// synthetic string under 500 chars cannot fail this test, and under the 8000-char
+// cap that trap is even easier to fall into.
+//
+// Run:  node --test tests/github_push_stderr_truncation.mjs
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { truncateLoudly, STDERR_MAX, scrubCredential } = require('../modules/lifecycle/github-push.js');
+
+// Progress chatter git emits before it ever reaches the verdict. Padded past the
+// cap so the truncation genuinely bites.
+const chatter = (n) => Array.from({ length: n },
+  (_, i) => `Enumerating objects: ${i}, done.\nCounting objects: ${i}% (${i}/${n}), done.`).join('\n');
+
+// CLASS 1 — the blocker-1000117 shape: a server-side rejection whose cause is the
+// LAST line of the stream.
+const COMMIT_REFS = [
+  'Enumerating objects: 41, done.',
+  chatter(400),
+  'Writing objects: 100% (23/23), 4.21 KiB | 1.05 MiB/s, done.',
+  'Total 23 (delta 17), reused 0 (delta 0), pack-reused 0',
+  'remote: fatal error in commit_refs',
+  'To https://github.com/example/repo.git',
+  ' ! [remote rejected] task-1003199 -> task-1003199 (failure)',
+  "error: failed to push some refs to 'https://github.com/example/repo.git'",
+].join('\n');
+
+// CLASS 2 — non-fast-forward. Real shape: progress chatter, then the verdict, then
+// a long `hint:` block. The hints are the padding a head-slice would preserve at
+// the cause's expense, and they sit AFTER the verdict, which is why keeping a tail
+// is what saves it.
+const NON_FAST_FORWARD = [
+  chatter(600),
+  'To https://github.com/example/repo.git',
+  ' ! [rejected]        task-1003199 -> task-1003199 (fetch first)',
+  "error: failed to push some refs to 'https://github.com/example/repo.git'",
+  'hint: Updates were rejected because the remote contains work that you do not',
+  'hint: have locally. This is usually caused by another repository pushing to',
+  'hint: the same ref. If you want to integrate the remote changes, use',
+  "hint: 'git pull' before pushing again.",
+  'hint: See the "Note about fast-forwards" in "git push --help" for details.',
+].join('\n');
+
+test('precondition: both fixtures exceed the cap, or this whole file proves nothing', () => {
+  assert.ok(COMMIT_REFS.length > STDERR_MAX, `commit_refs fixture is ${COMMIT_REFS.length}, cap ${STDERR_MAX}`);
+  assert.ok(NON_FAST_FORWARD.length > STDERR_MAX, `nff fixture is ${NON_FAST_FORWARD.length}, cap ${STDERR_MAX}`);
+});
+
+test('a commit_refs failure keeps the line that names the cause', () => {
+  const out = truncateLoudly(COMMIT_REFS);
+  assert.ok(out.includes('remote: fatal error in commit_refs'),
+    'the causal line is the whole reason stderr is attached at all');
+  assert.ok(out.includes('! [remote rejected]'), 'and the rejection line beside it');
+});
+
+test('a non-fast-forward failure keeps ! [rejected] and the error line', () => {
+  const out = truncateLoudly(NON_FAST_FORWARD);
+  assert.ok(out.includes('! [rejected]'), 'the verdict line');
+  assert.ok(out.includes('error: failed to push some refs'), 'the error line');
+});
+
+test('the truncation SAYS it truncated — never a message that just stops', () => {
+  const out = truncateLoudly(COMMIT_REFS);
+  assert.match(out, /characters omitted/,
+    'a silently clipped message reads like the whole message; that is what cost the day');
+  assert.match(out, /full text in the server log/, 'and it names where the rest lives');
+});
+
+test('the output stays bounded — the cap is still a real payload guard', () => {
+  const out = truncateLoudly(COMMIT_REFS);
+  // cap + the marker itself; the marker is deliberately outside the budget so the
+  // kept head and tail are each a full share.
+  assert.ok(out.length < STDERR_MAX + 200, `bounded, got ${out.length}`);
+});
+
+test('text within the cap is returned untouched — no marker on a short error', () => {
+  const short = 'remote: fatal error in commit_refs\nerror: failed to push some refs';
+  assert.equal(truncateLoudly(short), short);
+});
+
+test('both ends survive: a head-only slice would drop the tail, a tail-only the head', () => {
+  const out = truncateLoudly(NON_FAST_FORWARD);
+  assert.ok(out.startsWith('Enumerating objects'), 'the head is kept — the run did start');
+  assert.ok(out.trimEnd().endsWith('"git push --help" for details.'),
+    'and the tail, which is where git puts the verdict and its remedy');
+});
+
+// The shape of the guarantee, stated rather than assumed. head+tail keeps the two
+// ENDS, so a verdict in the exact MIDDLE of a stream far larger than the cap is
+// lost. That is not a defect for the two classes this task is about — git puts the
+// verdict at the end of both — but it is the boundary of what the current
+// truncation promises, and a future reader should not have to rediscover it. If a
+// failure class ever turns up whose cause sits mid-stream, THIS is the test that
+// says the fix must become line-aware (prefer remote:/error:/fatal: over hint:)
+// rather than merely bigger.
+test('KNOWN LIMIT: a cause buried mid-stream is not preserved — head+tail keeps the ends', () => {
+  const buried = [chatter(400), 'remote: fatal error in commit_refs', chatter(400)].join('\n');
+  assert.ok(buried.length > STDERR_MAX * 2, 'the fixture must dwarf the cap for the middle to be dropped');
+  const out = truncateLoudly(buried);
+  assert.ok(!out.includes('remote: fatal error in commit_refs'),
+    'documenting the boundary: if this starts passing, the truncation became smarter and this test should be rewritten, not deleted');
+});
+
+test('empty and non-string input do not throw', () => {
+  for (const v of ['', null, undefined, 0]) assert.equal(truncateLoudly(v), '');
+});
+
+test('truncation never resurrects a scrubbed credential', () => {
+  // scrubCredential runs BEFORE truncateLoudly on both call sites. Pin the order's
+  // consequence: a token in the tail half must not reappear in the kept tail.
+  const withToken = [chatter(400), 'remote: https://x-access-token:ghp_AAAABBBBCCCCDDDDEEEEFFFFGGGGHHHH@github.com/e/r.git', 'error: failed'].join('\n');
+  const out = truncateLoudly(scrubCredential(withToken));
+  assert.ok(!out.includes('ghp_AAAABBBBCCCCDDDDEEEEFFFFGGGGHHHH'), 'the token must not survive');
+  assert.ok(out.includes('error: failed'), 'while the causal tail still does');
+});