@bongos/core 1.19.760 → 1.19.762

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.760",
-  "core_contract": "1.19.760",
-  "source_commit": "d95227cc76780c216d4662c4b5d1979114a2841f",
+  "core_version": "1.19.762",
+  "core_contract": "1.19.762",
+  "source_commit": "4235a1ef680b4e7b79d8e61dc88b68069bc48d5f",
   "source_ref": "HEAD",
-  "built_at": "2026-09-16T03:30:46.130Z",
+  "built_at": "2026-09-16T03:56:12.759Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 483,
     "agent_docs_stubbed": 25,
-    "functional_verbatim": 2115,
+    "functional_verbatim": 2116,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2623,
-  "tree_sha256": "0aa4534bb30ad7aebdab2abc87c30d522f473d9d154e17820e73fedaa79748f5",
+  "file_count": 2624,
+  "tree_sha256": "7561f06e166d4cb1fa763b4771e03e57bba45299206df6dc706609de095557a3",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2512,7 +2512,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "dac2227121e64e9f6516a5dfb80e9362b4b3c05da7abef17cd199b89bf861104"
+      "sha256": "6eafab6b4df93ff7ed5abfb7c2d7ed203d4a277cb9533fa262653e6ada53a4de"
     },
     {
       "path": "docs/modules-contract.md",
@@ -7567,12 +7567,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "578710b1ef47bdf6cdf4510cbe531c5ed92a8ae3758f820eeb75efe4c6bafa61"
+      "sha256": "b20ee554299dfd5a29d5877d1eb9df41f460d30f1db26526485b4588228ef2e3"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "34ee3354f9e18c01ed9b9f0b5cac46a1d4e64da68978e38519e37a540b2c8787"
+      "sha256": "222eb11d6d265b2235b1a7455707bc9bc9aa2210bcec0deb34dcbfdc12de784d"
     },
     {
       "path": "public-docs/index.html",
@@ -8062,7 +8062,7 @@
     {
       "path": "scripts/gds/fitness-ratchets.js",
       "mode": "0000644",
-      "sha256": "7a0828405f5069ef97dedfa0874c156507f3ec10651c0e45cfd62d31315275d7"
+      "sha256": "b3f4092fffd30e50cb145b524beeed5d483132f52e77e37a7ab9c18bbf300bc7"
     },
     {
       "path": "scripts/gds/fitness.js",
@@ -8242,7 +8242,7 @@
     {
       "path": "scripts/gds/linkify-refs.js",
       "mode": "0000644",
-      "sha256": "ad292a1bcfd4c9f3ef93260af1b1a34883b78185ba03d0677b51765165915ea1"
+      "sha256": "73be262f96571e9d35ed83f0c9d27e7652f1dad74016c302f8b24d1d9a724333"
     },
     {
       "path": "scripts/gds/lint-infra-exec.js",
@@ -9382,7 +9382,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "9080c03abc81fa68447459fcec10d19afb4c9f8a5816515a2af48adf4cce76dd"
+      "sha256": "9fca9034c480450daf57672bfecc9c7d09f8105fddd88d81ef8e46d025903cac"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -10532,7 +10532,7 @@
     {
       "path": "tests/fitness_ratchets.mjs",
       "mode": "0000644",
-      "sha256": "e33edfa4925694d824c042f1fd06a977f1ac14b5c1cb24b5326014ca9f86ece0"
+      "sha256": "949526efc49c317a7be7e33beea0643b29748f3fd4e914d3a3670ce9ce6aadeb"
     },
     {
       "path": "tests/fitness_two_root.mjs",
@@ -10589,6 +10589,11 @@
       "mode": "0000644",
       "sha256": "850113ed91babc9eb54dc22231f194d283fd3f94cee9deef1e6e0bf6f3a969c2"
     },
+    {
+      "path": "tests/github_push_stderr_truncation.mjs",
+      "mode": "0000644",
+      "sha256": "d400c1830c9255851682c1653841a616ab9088f6facb2a5893f0ec41a72626eb"
+    },
     {
       "path": "tests/github_repo_visibility.mjs",
       "mode": "0000644",
@@ -11457,7 +11462,7 @@
     {
       "path": "tests/linkify_refs.mjs",
       "mode": "0000644",
-      "sha256": "ba5164ec77b5541b22b50ed7611dfbbe61731f62b3dfbb678f7de4f77282e918"
+      "sha256": "f4e905823f8c3b7f540d3dbc6a9873198a26e022810b21194b2ae45ef9437954"
     },
     {
       "path": "tests/live_channel.mjs",

package/docs/module-api-changelog.md

@@ -1994,5 +1994,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.758 with no explicit bump. run 35050268139. (task 1002620)
   1.19.760 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         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)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.760",
+  "version": "1.19.762",
   "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/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/scripts/gds/linkify-refs.js

@@ -200,6 +200,72 @@ const LIST_GLUE_RE = /^[\s,–—-]*(?:and|&|\+|or|to|through)?[\s,–—-]*$/i;
 // last. Each site builds its own.
 const REF_DIGITS = '\\d{1,7}';
 
+// ---- the ordinal-prose guard (task 1002975) --------------------------------
+//
+// THE BUG. With no context word, a bare `#N` was linkified on ID EXISTENCE ALONE:
+// the prose "side door #1" became a link to task 1, while its sibling "side door
+// #2" survived only because no id 2 exists. That is luck, not grammar, and task
+// 1002974 had to repair a committed doc because of it.
+//
+// THE RULE, AND WHY IT IS A WIDTH RULE. The originating row proposed "a preceding
+// bare noun without task/idea/blocker context words → leave alone". Measured
+// against the actual corpus, that is far too broad: running linkifyText over every
+// committed .md with a maximally permissive id set rewrites 231 context-less refs,
+// 77 of them preceded by a bare word — and 49 of those are GENUINE ("the #506",
+// "by #435", "under #436"). Skipping on the preceding noun alone would leave ~49
+// real refs bare, which is exactly the GitHub-mis-autolink harm this script exists
+// to prevent. So the noun test alone would have traded one defect for a worse one.
+//
+// What DOES separate them in the corpus is WIDTH. All 28 word-preceded refs of 1–2
+// digits are ordinal prose — "§Decision #4" (an ADR section, 13 of them), "limiter
+// #4", "limiter #5", "idea fixture #1", "fixture #4", "ask #1", "and #7", "with
+// #5" — and every word-preceded ref of 3+ digits is a real task. Ordinals in
+// English prose are small; the ids these docs cite are not. Hence: no context
+// word, AND a bare word immediately before, AND at most two digits.
+//
+// Both conjuncts are load-bearing. Drop the width and 49 real refs go bare; drop
+// the preceding-word test and "(#1)" or a line-leading "#7" — which the corpus
+// shows are ordinarily genuine — stop linking too.
+//
+// Known cost, accepted: "PMS-V2 #37" and "the #54" are legacy two-digit refs that
+// now stay bare. Two ambiguous links lost against ~26 false ones fixed, and a bare
+// "#37" with no entity word is ambiguous to a human reader as well.
+//
+// This lands in linkifyText rather than beside it because `.claude/hooks/
+// stop-refcheck.js` classifies by CALLING linkifyText — so the same prose stops
+// being flagged in chat by the same change, with no second copy of the rule.
+// The one context word the guard must stand down for. There is deliberately NO
+// task entry in classifyKind — "task #170" is handled by the DEFAULT path (no
+// kind, id exists → link), because a task is the thing this resolver is for. That
+// leaves "task #3" looking exactly like "limiter #4" to a width rule, and the
+// first cut of this guard ate it. Caught by its own test, which is why the test
+// exists. Not folded into ENTITY_RE: that set means "shares the integer space
+// with tasks but is NOT one", and adding `task` there would neutralize every
+// "task #N" into a code span.
+const TASK_CTX_RE = /\b(tasks?)[`'")\s(:]*$/i;
+// Words that INTRODUCE a reference rather than being the noun it counts. The row
+// asked for "a preceding bare NOUN", and these are not nouns: "see #2" is a real
+// ref and the Stop hook is right to block it in chat, which is how this omission
+// was caught — tests/stop_refcheck.mjs went red on exactly that string.
+//
+// Kept deliberately short, and checked against the corpus rather than guessed: the
+// 1–2 digit word-preceded refs in committed docs are preceded by pms-v2 · task ·
+// the · ask · and · decision · limiter · fixture · sr · with · fixing. None of
+// these six appears there, so exempting them re-breaks nothing that was measured.
+// Words like "the", "and", "with" and "of" are NOT here on purpose — they precede
+// ordinal phrases at least as often as references ("ask #1 and #7" means the
+// questions, not two tasks).
+const ORDINAL_EXEMPT_RE = /\b(see|from|per|via|in|at)[`'")\s(:]*$/i;
+const ORDINAL_MAX_DIGITS = 2;
+// A bare word (letters, then letters/digits/'/-) immediately before the '#',
+// separated by spaces or tabs or nothing at all. Anchored at the end of the left
+// context. The whitespace is OPTIONAL because the corpus contains "SR#11" — a
+// security-review finding number, unspaced and just as much a false positive as
+// the spaced ones. Widening it is safe precisely because the width conjunct is
+// what protects real refs: every word-adjacent ref of 3+ digits is untouched
+// either way, so this only ever admits more of the same two-digit class.
+const ORDINAL_PROSE_LEFT_RE = /[A-Za-z][A-Za-z0-9'-]*[ \t]*$/;
+
 const RESOLVER_LINK_RE = new RegExp(`\\[#(${REF_DIGITS})\\]\\((?:https?:\\/\\/[^/)\\s]+)?\\/builders#\\/task\\/(${REF_DIGITS})\\)`, 'g');
 
 // Classify a ref by its left context (+ list-glue carry). Returns one of
@@ -313,6 +379,11 @@ function linkifySegment(segment, ids, leftContext, stats) {
     } else if (kind === 'github') {
       // "PR #475" — genuinely GitHub's number space; the bare autolink is CORRECT.
       skipReason = 'github-namespace';
+    } else if (!kind && !TASK_CTX_RE.test(left) && !ORDINAL_EXEMPT_RE.test(left)
+               && ORDINAL_PROSE_LEFT_RE.test(left) && num.length <= ORDINAL_MAX_DIGITS) {
+      // "side door #1", "limiter #4", "§Decision #4" — a noun followed by a small
+      // ordinal, not a ref. See ORDINAL_MAX_DIGITS for the corpus evidence.
+      skipReason = 'ordinal-prose';
     } else if (!kind && !ids.tasks.has(Number(num))) {
       // No context and not a known task id — too ambiguous to touch (a bare PR
       // ref, a future task, a numeric color). Left bare.

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.760'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.762'; // 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/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');
+});

package/tests/linkify_refs.mjs

@@ -311,5 +311,75 @@ t('discoverDocs finds CLAUDE.md, recurses docs/ subdirs (only .md), skips the ge
   }
 });
 
+// ---- the ordinal-prose guard (task 1002975) --------------------------------
+//
+// THE BUG task 1002974 had to repair a committed doc for: with no context word, a
+// bare `#N` was linkified on ID EXISTENCE ALONE. "side door #1" became a link to
+// task 1; its sibling "side door #2" survived only because no id 2 exists. Luck,
+// not grammar.
+//
+// The rule is NOT "a preceding noun means skip" — measured over every committed
+// .md, that would leave ~49 genuine refs bare ("the #506", "by #435"), which is
+// the GitHub-mis-autolink harm this script exists to prevent. It is a WIDTH rule:
+// no context word AND a bare word immediately before AND at most two digits.
+// In the corpus all 28 word-preceded 1–2 digit refs are ordinals; every
+// word-preceded 3+ digit ref is a real task.
+
+t('ordinal prose after a noun is left alone — the reported "side door #1"', () => {
+  const ids = new Set([1, 2]);
+  assert.equal(run('the side door #1 is open', ids), 'the side door #1 is open');
+  assert.equal(run('the side door #2 is open', ids), 'the side door #2 is open');
+});
+
+t('the ordinals found in our OWN docs are left alone', () => {
+  const ids = new Set([1, 4, 5, 11]);
+  for (const s of [
+    'joins rate-limit.js as limiter #4: 120 reads',
+    'ADR 0083 §Decision #4 forbids kernel machinery from naming one',
+    'live proof against a local origin (idea fixture #1)',
+    'the edge cookie-strip rule (ADR 0053 / SR#11)',   // unspaced — still ordinal prose
+  ]) assert.equal(run(s, ids), s, s);
+});
+
+t('a WORD-preceded ref of three or more digits still linkifies — the width is what separates them', () => {
+  const ids = new Set([506, 435]);
+  assert.equal(run('the #506 evaluator', ids), `the ${link(506)} evaluator`);
+  assert.equal(run('captured by #435 last night', ids), `captured by ${link(435)} last night`);
+});
+
+t('a SMALL ref with no preceding word still linkifies — the noun is half the rule', () => {
+  const ids = new Set([7]);
+  assert.equal(run('#7 is the row', ids), `${link(7)} is the row`);
+  assert.equal(run('see (#7) for detail', ids), `see (${link(7)}) for detail`);
+});
+
+t('an explicit entity word still wins over the ordinal guard', () => {
+  // "task #3" is a real ref even though it is one digit after a word: classifyKind
+  // runs first, so the guard never sees it.
+  const ids = new Set([3]);
+  assert.equal(run('task #3 sat in blocked for days', ids), `task ${link(3)} sat in blocked for days`);
+});
+
+t('a REFERRING word is not a noun — "see #2" still linkifies', () => {
+  // The Stop hook classifies by calling linkifyText, so this is also what stops it
+  // blocking a real bare ref in chat. tests/stop_refcheck.mjs went red on exactly
+  // this string when the first cut of the guard treated every preceding word as a
+  // noun — which is how the omission was found.
+  const ids = new Set([2]);
+  for (const [s, expect] of [
+    ['see #2 for details', `see ${link(2)} for details`],
+    ['from #2 onward', `from ${link(2)} onward`],
+    ['landed in #2 last week', `landed in ${link(2)} last week`],
+  ]) assert.equal(run(s, ids), expect, s);
+});
+
+t('the guard is reported as its own skip reason, not folded into not-a-task', () => {
+  const stats = { skipped: {}, linked: 0, rewritten: 0, unlinked: 0 };
+  linkifyText('the side door #1 is open', new Set([1]), stats);
+  assert.equal(stats.skipped['ordinal-prose'], 1);
+  assert.equal(stats.skipped['not-a-task'], undefined,
+    'an ordinal is skipped BECAUSE it reads as prose, not because the id is missing');
+});
+
 console.log(`\nlinkify_refs: ${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);