@bongos/core 1.19.866 → 1.19.868

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.866",
-  "core_contract": "1.19.866",
-  "source_commit": "313d85e8328b2cf414e81eb6c971c3cd84724fb3",
+  "core_version": "1.19.868",
+  "core_contract": "1.19.868",
+  "source_commit": "6e35e3093dab9de214c45a87c227247fdc311bab",
   "source_ref": "HEAD",
-  "built_at": "2026-09-18T14:15:20.838Z",
+  "built_at": "2026-09-18T18:45:12.625Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 500,
     "agent_docs_stubbed": 26,
-    "functional_verbatim": 2284,
+    "functional_verbatim": 2286,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2810,
-  "tree_sha256": "beb2b02aa761274891c011957f1c0edf40e0b339d537014d78ce7b8c6231f11d",
+  "file_count": 2812,
+  "tree_sha256": "f61ec14f3d7f288cca2d20b1c27a0d0f4685e6e3474f344058c2bb7894cc3bef",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2602,7 +2602,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "f6cebe493fa035d5b336e1947d9d491ef051f266388108c55f6402572db6dd6e"
+      "sha256": "3a71551ddb488315c33aa0f3bd4850e96f91e79940e801eeaa9c5c9304cdc653"
     },
     {
       "path": "docs/modules-contract.md",
@@ -7927,12 +7927,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "5d3ee0b5b578882947d9ef96d04ba34877589d6f8f3cafa33ef73bdda178feb8"
+      "sha256": "89633564a9bfe53d895b487d7d0d06e8f23c3c1fcbabca119e7be607be5986b5"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "e491cf6aef48a2644a7c639bae0d7e2ec4f258e7d00aaedbd08a884d4c1c92d5"
+      "sha256": "266b5d6ca4a1c4342a451577885abc475091a30a1e9bceb3a1749e579e97121d"
     },
     {
       "path": "public-docs/index.html",
@@ -8242,7 +8242,7 @@
     {
       "path": "scripts/gds/claude-materialize.js",
       "mode": "0000644",
-      "sha256": "488a2a6c55c794625c47480def16c3b3fee81be4bd73d36a21f11a7feab741fc"
+      "sha256": "30fa12a96df4e9eda7e81f5abe3886caa0fb7dd277e37c5f6388c9acc429950e"
     },
     {
       "path": "scripts/gds/claude-md-template.js",
@@ -9264,10 +9264,15 @@
       "mode": "0000644",
       "sha256": "03095c6a2c57a9b1c91688d26320dcb5749dc59d5eb468db105dfad27dcd58e9"
     },
+    {
+      "path": "scripts/gds/ship-merge-gate.js",
+      "mode": "0000644",
+      "sha256": "34c28500eb2c4324f44c5b3604049c305d7b7921b57557ee325ece88b6293252"
+    },
     {
       "path": "scripts/gds/ship-merge.js",
       "mode": "0000644",
-      "sha256": "0a1a9be854950574c554ab4a38d92123eeb6b283f2e17a4a9c1ce07aa80beaee"
+      "sha256": "b85dd18d8214f1e732d4bd584fbad037c5505a16703e867e18e42bafef0bed33"
     },
     {
       "path": "scripts/gds/ship-preflight-steps.js",
@@ -9877,7 +9882,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "ee2e636d5a1daea33068efecea345e13095aec56718b589e08dda05ed1fc5791"
+      "sha256": "a1045f7acc428f16a6ebdfbcdc8ecf0eb0829c16fde30829b3c8541150372c05"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -10612,7 +10617,7 @@
     {
       "path": "tests/claude_materialize.mjs",
       "mode": "0000644",
-      "sha256": "ac4c44006a151190a5ead99c7a32241cf95e21b3eca397ea7c0d4bf26b0b7de9"
+      "sha256": "36c52641c98217d42c38853c5dd78d4d4eb51ee97005380318db5adb2aa71d28"
     },
     {
       "path": "tests/clawback_confirmed_backlog.mjs",
@@ -13444,6 +13449,11 @@
       "mode": "0000644",
       "sha256": "a3b7858c255f1c7ea692866dbadd7321f77bd88c8380c429b7cb5f6b1b65496b"
     },
+    {
+      "path": "tests/ship_merge_gate.mjs",
+      "mode": "0000644",
+      "sha256": "b498d2820f6e17948cb8a86637d16b248a3349ebd9933343dd4b335a239497b7"
+    },
     {
       "path": "tests/ship_post_land_verify.mjs",
       "mode": "0000644",

package/docs/module-api-changelog.md

@@ -2206,5 +2206,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.864 with no explicit bump. run 35295856053. (task 1002620)
   1.19.866 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.865 with no explicit bump. run 35355019469. (task 1002620)
+  1.19.867 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.866 with no explicit bump. run 35380895321. (task 1002620)
+  1.19.868 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.867 with no explicit bump. run 35381947323. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.866",
+  "version": "1.19.868",
   "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

@@ -389,10 +389,37 @@ function renderStarterSettings() {
   }, null, 2)}\n`;
 }
 
-function transformSettings(srcPath) {
+// readSettingsTransform — the transform, as a result rather than a string:
+// { text, parsed, reason }. transformSettings below is the string face of it,
+// kept because that is what the tests and the historical callers use.
+//
+// WHY A PARSE FAILURE IS COPIED THROUGH UNTOUCHED (task 1004023). The old
+// fallback was `bongosify(raw)` — a best-effort regex rewrite over the whole
+// file. The script-invocation regex ends in an optional quote so it can swallow the
+// closing quote of a QUOTED PATH inside a command; run over raw JSON text it
+// swallows the JSON string's own closing quote instead:
+//
+//     bongosify('{"command": "node scripts/gds/strand-watch.js", }')
+//     -> {"command": "bongos exec scripts/gds/strand-watch.js, }
+//
+// So a file that was one trailing comma from valid was written to the instance
+// MORE broken than it arrived, with its strings running into each other. A
+// rewrite of text we could not parse is not worth a worse file: the raw bytes
+// are copied through unchanged and the caller is handed a reason to report. The
+// operator fixes one comma instead of unpicking mangled strings.
+//
+// The parse failure is NOT made fatal: the core's own settings.json is valid
+// JSON (pinned by a test), so reaching this means the operator has edited
+// theirs, and refusing the whole materialize over one file would be a worse
+// trade than copying it and saying so.
+function readSettingsTransform(srcPath) {
   const raw = fs.readFileSync(srcPath, 'utf8');
   let json;
-  try { json = JSON.parse(raw); } catch { return bongosify(raw); } // malformed → best-effort text rewrite
+  try {
+    json = JSON.parse(raw);
+  } catch (err) {
+    return { text: raw, parsed: false, reason: (err && err.message) || 'not valid JSON' };
+  }
   const hooks = json && json.hooks;
   if (hooks && typeof hooks === 'object') {
     for (const event of Object.values(hooks)) {
@@ -416,7 +443,14 @@ function transformSettings(srcPath) {
       perms[key] = [...new Set(rules.flatMap((r) => (typeof r === 'string' ? spellings(r) : [r])))];
     }
   }
-  return JSON.stringify(json, null, 2) + '\n';
+  return { text: JSON.stringify(json, null, 2) + '\n', parsed: true, reason: null };
+}
+
+// transformSettings — the string face of readSettingsTransform. A caller that
+// only wants the bytes keeps working; one that needs to know the file could not
+// be parsed calls readSettingsTransform and reads `parsed`.
+function transformSettings(srcPath) {
+  return readSettingsTransform(srcPath).text;
 }
 
 // Materialize the .claude/ surface from `coreRoot` into `instanceDir`. Returns a summary.
@@ -426,7 +460,7 @@ function transformSettings(srcPath) {
 const HOOK_TEXT_EXT = new Set(['.js', '.mjs', '.cjs', '.json', '.sh', '.md', '.txt']); // hooks are .js — rebrand them too
 
 function materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite = true, log = () => {} }) {
-  const summary = { skipped: false, skills: 0, moduleSkills: 0, settings: false, hooks: 0, scheduledTasks: 0, skippedFiles: [], excludedSkills: [], withdrawnSkills: [], rebrandRules: 0, claudeMd: false, writtenPaths: [], notes: [] };
+  const summary = { skipped: false, skills: 0, moduleSkills: 0, settings: false, settingsUnparsed: false, hooks: 0, scheduledTasks: 0, skippedFiles: [], excludedSkills: [], withdrawnSkills: [], rebrandRules: 0, claudeMd: false, writtenPaths: [], notes: [] };
   // Every instance-relative path this run WROTE or REMOVED (task 1003957). `bongos upgrade`
   // hands these to persistPin as artifactPaths, exactly as task 1003926 already does for
   // regenerateApiArtifacts' output: committing only the pin left the materialized files dirty,
@@ -607,13 +641,22 @@ function materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite =
       summary.skippedFiles.push('settings.json');
       log('  • .claude/settings.json already present — left untouched (adopt merges nothing here yet).');
     } else {
+      // task 1004023: an unparseable settings.json is copied through BYTE FOR
+      // BYTE — no bongosify, no rebrand. Both are regex passes written for the
+      // strings inside a parsed file, and over raw JSON text they damage it.
+      // The instance gets what the core had, plus a note naming the parse error.
+      const settingsOut = readSettingsTransform(settingsSrc);
       if (!dryRun) {
         fs.mkdirSync(destClaude, { recursive: true });
-        fs.writeFileSync(settingsDest, rebrand(transformSettings(settingsSrc)));
+        fs.writeFileSync(settingsDest, settingsOut.parsed ? rebrand(settingsOut.text) : settingsOut.text);
       }
       addWritten('.claude/settings.json');
       summary.settings = true;
-      log(`  ${dryRun ? '[dry-run] would write' : '✓ wrote'} .claude/settings.json (hook commands + permission rules→bongos, identity rebranded)`);
+      if (!settingsOut.parsed) {
+        summary.settingsUnparsed = true;
+        summary.notes.push(`.claude/settings.json is not valid JSON (${settingsOut.reason}) — copied through UNCHANGED: no hook-command or permission-rule rewrite to bongos, and no identity rebrand. Fix the JSON at the core root and materialize again, or edit the instance copy by hand.`);
+      }
+      log(`  ${dryRun ? '[dry-run] would write' : '✓ wrote'} .claude/settings.json ${settingsOut.parsed ? '(hook commands + permission rules→bongos, identity rebranded)' : '(UNCHANGED — not valid JSON, nothing rewritten)'}`);
     }
   } else {
     // Package-only install: the core root carries no settings.json to copy, so
@@ -802,4 +845,4 @@ if (require.main === module) {
   process.exit(s.refused.length ? 1 : 0);
 }
 
-module.exports = { scriptToVerb, bongosify, transformSettings, renderStarterSettings, STARTER_ALLOW, copyTreeTransformed, materializeClaude, materializeModuleSkillsIntoCore, isCoreCheckoutRoot, readModuleSkillsManifest, MODULE_SKILLS_MANIFEST, readInstanceSkillsManifest, INSTANCE_SKILLS_MANIFEST, GDS_INVOCATION_RE, buildRebrandRules, rebrandText, disabledModuleSkills, moduleSkillRoster, moduleSkillSources, vendoredSkillGate, SKILL_NAME_RE, VENDOR_DEFAULT_POLICY };
+module.exports = { scriptToVerb, bongosify, transformSettings, readSettingsTransform, renderStarterSettings, STARTER_ALLOW, copyTreeTransformed, materializeClaude, materializeModuleSkillsIntoCore, isCoreCheckoutRoot, readModuleSkillsManifest, MODULE_SKILLS_MANIFEST, readInstanceSkillsManifest, INSTANCE_SKILLS_MANIFEST, GDS_INVOCATION_RE, buildRebrandRules, rebrandText, disabledModuleSkills, moduleSkillRoster, moduleSkillSources, vendoredSkillGate, SKILL_NAME_RE, VENDOR_DEFAULT_POLICY };

package/scripts/gds/ship-merge-gate.js

@@ -0,0 +1,187 @@
+// scripts/gds/ship-merge-gate.js — the fitness gate on the MERGE RESULT, run
+// between the local merge and the push that makes it main (task 1004032).
+//
+// WHY THIS EXISTS. Branch protection requires the `unit` check of a PULL
+// REQUEST. The local-merge land path is not a pull request: ship-merge.js
+// merges the task branch into main inside the main checkout and pushes the
+// result straight to origin/main, so no required check is consulted at any
+// point. Until this file, the only things standing between a builder's branch
+// and a red main were the grader (which reads a diff, not the gates) and
+// runSmoke (an HTTP liveness probe against the deployed instance). Neither runs
+// fitness.js, and ship-check.js — which does — is a command the builder may
+// choose to run, not a step of the ship.
+//
+// THE INCIDENT IT CLOSES (2026-09-17). Commit 89ac9620 (task 1000862) added two
+// legacy-acronym literals to .github/workflows/integration.yml. Measured after
+// the fact, on the commits themselves:
+//
+//   89ac9620  the BRANCH TIP  legacy_gds_literals 1137, committed baseline 1135
+//                             -> fitness.js exits non-zero. Already red.
+//   272b664d  the MERGE       the same 1137 against the same 1135, since the
+//                             merge changed nothing about those two literals.
+//   41ce52d4  the main before  fitness.js passes.
+//
+// So the guess in the original bug report — that a merge-ref-evaluated ratchet
+// let a clean branch produce a red main — is WRONG, and the truth is worse: the
+// branch was red on its own, and the ship pushed it to main regardless. This
+// was never the subtle "green branch, red merge" case; nothing measured
+// anything. main went red, and three tasks (1003456, 1004014, 1004021) sat at
+// 'confirmed' with nothing able to land until the baseline was raised by hand
+// to unblock the queue.
+//
+// WHAT IT DOES NOT DO. It does not punish a builder for damage that is already
+// on main. A gate that refused every ship while main is red would have turned
+// that same incident into a total deadlock instead of a bad afternoon — so when
+// the merge result fails, the pre-merge base is measured too, and a failure
+// already present there is reported and waved through. The rule is "do not make
+// main worse", not "main must be perfect before you may ship".
+
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+// mergeGateVerdict — PURE. The whole decision, over two measurements:
+//
+//   mergeClean  did fitness pass on the merge result (the tree about to be main)
+//   baseClean   did it pass on the pre-merge base — true, false, or null for
+//               "could not be measured"
+//
+// The null case blocks on purpose. A failing merge result IS a red main
+// whatever the base was doing; an unmeasurable base means the gate cannot show
+// the failure was inherited, and the honest report is "this push makes main
+// red and I cannot prove it was already red". The builder's own next step is
+// the same either way — run fitness.js and read the failing lines.
+function mergeGateVerdict({ mergeClean, baseClean }) {
+  if (mergeClean) return { block: false, reason: 'clean' };
+  if (baseClean === false) return { block: false, reason: 'pre-existing' };
+  if (baseClean === null || baseClean === undefined) return { block: true, reason: 'unmeasured-base' };
+  return { block: true, reason: 'regression' };
+}
+
+// gateMessage — PURE. The one line printed for each verdict, in the voice of
+// the sibling bails in ship-merge.js.
+function gateMessage(reason) {
+  switch (reason) {
+    case 'clean':
+      return '  fitness on the merge result: clean';
+    case 'pre-existing':
+      return '  fitness on the merge result: FAILS, but the pre-merge main fails too — inherited, not caused by this branch; proceeding';
+    case 'regression':
+      return '  auto-merge: fitness FAILS on the merge result and PASSES on the pre-merge main — this branch would turn main red; task stays at confirmed';
+    case 'unmeasured-base':
+      return '  auto-merge: fitness FAILS on the merge result and the pre-merge main could not be measured; task stays at confirmed';
+    default:
+      return `  auto-merge: fitness gate returned an unknown verdict (${reason})`;
+  }
+}
+
+// fitnessOutcome — one fitness.js run over the tree at `treeRoot`, as a
+// TRI-STATE: 'clean', 'failing', or 'unmeasurable'.
+//
+// The three are kept apart on purpose. An earlier cut returned a boolean, which
+// made a crashed run and a genuine finding the same answer — and since a
+// FAILING base waves the ship through, a probe that merely broke would have
+// certified any regression as inherited. A control that degrades to permissive
+// under infra flakiness is not a control. 'unmeasurable' blocks instead.
+//
+// IT MUST BE THAT TREE'S OWN fitness.js, not this file's sibling copy.
+// fitness.js resolves the repo it measures from its own __dirname and ignores
+// cwd, so invoking the shipping worktree's copy with `cwd` pointed elsewhere
+// measures the shipping worktree twice and reports "clean" for whatever it was
+// asked about. That is not a hypothetical: the first cut of this gate did
+// exactly that, and replaying the 2026-09-17 incident through it returned a
+// confident pass on a tree that fails fitness. Running each tree's own gate is
+// also the honest semantics — a base commit is measured by the rules that were
+// committed with it, which is what CI would have done on that commit.
+//
+// Output is inherited so the failing lines land in the ship log where the
+// builder reads them. A non-zero exit is a FINDING; anything else that goes
+// wrong (no fitness.js in that tree, a spawn that never ran, a checker that
+// crashed) is 'unmeasurable'.
+function fitnessOutcome(treeRoot) {
+  const script = path.join(treeRoot, 'scripts', 'gds', 'fitness.js');
+  if (!fs.existsSync(script)) return 'unmeasurable';
+  try {
+    execFileSync(process.execPath, [script], { cwd: treeRoot, stdio: 'inherit', shell: false });
+    return 'clean';
+  } catch (err) {
+    // A real gate verdict is a clean non-zero exit. A spawn that never produced
+    // an exit code (ENOENT on the interpreter, a signal, a permissions refusal)
+    // is the infra case, and must not be read as "this tree fails".
+    return typeof err?.status === 'number' ? 'failing' : 'unmeasurable';
+  }
+}
+
+// runFitnessAt — the boolean face of fitnessOutcome, kept for the merge-result
+// side where "not clean" is all the caller needs: a merge result that cannot be
+// measured is one this gate will not certify either way.
+function runFitnessAt(treeRoot) {
+  return fitnessOutcome(treeRoot) === 'clean';
+}
+
+// probeBaseClean — measure the PRE-MERGE base in a throwaway detached worktree,
+// so the merge already sitting in the main checkout does not have to be unwound
+// to ask the question. Returns true (base clean), false (base genuinely fails
+// its own gate) or null (could not be measured at all).
+//
+// No `npm ci` and no node_modules junction: fitness.js reads the tree and
+// shells out to git, and runs green in a bare worktree — verified on this repo.
+// If that ever stops being true the probe reports 'unmeasurable' rather than
+// inventing a verdict, and mergeGateVerdict blocks.
+function probeBaseClean(repoRoot, baseSha) {
+  if (!baseSha) return null;
+  let dir = null;
+  try {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'bongos-merge-gate-'));
+    execFileSync('git', ['worktree', 'add', '--detach', '--quiet', dir, baseSha], {
+      cwd: repoRoot, stdio: 'ignore', shell: false,
+    });
+  } catch (_) {
+    if (dir) removeProbe(repoRoot, dir);
+    return null;
+  }
+  try {
+    const outcome = fitnessOutcome(dir);
+    if (outcome === 'clean') return true;
+    if (outcome === 'failing') return false;
+    return null;
+  } finally {
+    removeProbe(repoRoot, dir);
+  }
+}
+
+// removeProbe — best-effort teardown. A husk left in the OS temp dir is
+// untidy; a ship that dies because its cleanup threw is worse.
+function removeProbe(repoRoot, dir) {
+  try {
+    execFileSync('git', ['worktree', 'remove', '--force', dir], { cwd: repoRoot, stdio: 'ignore', shell: false });
+  } catch (_) { /* fall through to the filesystem */ }
+  try {
+    fs.rmSync(dir, { recursive: true, force: true });
+  } catch (_) { /* nothing left to do */ }
+}
+
+// gateMergeResult — the I/O half: measure, decide, print. `baseSha` is the main
+// tip as it stood BEFORE the branch was merged in (in ship-merge.js that is
+// origin/main, since the ff-only step immediately above it guarantees the two
+// are the same commit).
+function gateMergeResult({ repoRoot, baseSha, log = console.log }) {
+  log('  fitness against post-merge state...');
+  const mergeClean = runFitnessAt(repoRoot);
+  const baseClean = mergeClean ? true : probeBaseClean(repoRoot, baseSha);
+  const verdict = mergeGateVerdict({ mergeClean, baseClean });
+  log(gateMessage(verdict.reason));
+  return verdict;
+}
+
+module.exports = {
+  fitnessOutcome,
+  gateMergeResult,
+  gateMessage,
+  mergeGateVerdict,
+  probeBaseClean,
+  runFitnessAt,
+};

package/scripts/gds/ship-merge.js

@@ -26,6 +26,7 @@ const {
   landed,
 } = require('./ship-land.js');
 const { runSmoke } = require('./ship-grade.js');
+const { gateMergeResult } = require('./ship-merge-gate.js');
 const { dbOnlyIgnoredNotice } = require('./ship-honesty.js');
 const { currentBranch, mainWorktreeBusy, regenerateApiClient, regenerateApiDocs, regenerateCopyInventory, regenerateDiagrams, regenerateFileMap, regenerateRepoMap, regenerateSessionIndex } = require('./ship-regen.js');
 const { REPO_ROOT } = require('./ship-state.js');
@@ -247,6 +248,12 @@ async function mergeLocally(taskId, valueSummary, { dbOnly = false } = {}) {
       return landBailed('the local main is ahead of origin/main', '/merge-mode');
     }
 
+    // The tree the merge result will be compared against (task 1004032). The
+    // ff-only step above has just proved local main IS origin/main, so this is
+    // main as the rest of the world currently sees it — read before the branch
+    // is merged in, because afterwards the commit is no longer reachable by name.
+    const baseSha = gitOk('git rev-parse HEAD', { cwd: REPO_ROOT });
+
     // #681: build the merge argv and run it WITHOUT a shell. valueSummary is
     // DB-sourced (untrusted) — passing it as a literal argv element means
     // `$(...)`/backticks in it can never be interpreted as a command.
@@ -261,6 +268,21 @@ async function mergeLocally(taskId, valueSummary, { dbOnly = false } = {}) {
       return landBailed('post-merge smoke tests failed', '/merge-mode');
     }
 
+    // task 1004032: the merge result is about to BECOME main by a direct push,
+    // which no required status check gates. Run the same fitness gate CI would
+    // have run on a PR, and refuse the push when this branch is what turns main
+    // red. A failure already present on the pre-merge base is reported and
+    // waved through — see scripts/gds/ship-merge-gate.js for why.
+    const fitnessVerdict = gateMergeResult({ repoRoot: REPO_ROOT, baseSha });
+    if (fitnessVerdict.block) {
+      return landBailed(
+        fitnessVerdict.reason === 'regression'
+          ? 'fitness fails on the merge result and passes on the pre-merge main — this branch would turn main red'
+          : 'fitness fails on the merge result and the pre-merge main could not be measured',
+        'node scripts/gds/fitness.js',
+      );
+    }
+
     console.log('  pushing merged main to origin...');
     // SEC #863: route through push-main.js, which carries the
     // OTB_ALLOW_MAIN_PUSH override so the pre-push permission gate lets THIS

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

@@ -832,5 +832,65 @@ t("an instance's OWN settings.json is never clobbered", () => {
   rmSync(inst, { recursive: true, force: true });
 });
 
+// ---- an unparseable settings.json is copied through, not mangled (task 1004023) ----
+// THE DEFECT. The fallback was `bongosify(raw)` — the command-string rewrite run over
+// the whole FILE. The script-invocation regex ends in an optional quote so it can swallow the
+// closing quote of a quoted PATH; over raw JSON text it swallows the JSON string's own
+// closing quote, and a file one trailing comma from valid was written to the instance
+// with its strings running into each other. The load-bearing assertion is therefore the
+// BYTE-EQUALITY one: the fix is not "rewrite it better", it is "do not rewrite what you
+// could not parse".
+const BROKEN_SETTINGS = '{"command": "node scripts/gds/strand-watch.js", }'; // one trailing comma from valid
+
+t('readSettingsTransform: malformed JSON is reported, not rewritten', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'w3-bad-'));
+  const p = join(dir, 'settings.json');
+  writeFileSync(p, BROKEN_SETTINGS);
+  const out = m.readSettingsTransform(p);
+  assert.equal(out.parsed, false, 'a trailing comma must be reported as unparseable');
+  assert.equal(out.text, BROKEN_SETTINGS, 'the bytes must come through untouched');
+  assert.ok(out.reason && out.reason.length > 0, 'the caller needs something to print');
+  // The specific corruption from the bug report must not be reachable any more.
+  assert.ok(!out.text.includes('bongos exec'), 'the command rewrite ran over text it could not parse');
+  assert.equal((out.text.match(/"/g) || []).length, (BROKEN_SETTINGS.match(/"/g) || []).length,
+    'a quote was eaten — this is the exact shape of the original defect');
+  rmSync(dir, { recursive: true, force: true });
+});
+
+t('readSettingsTransform: valid JSON still gets the full rewrite', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'w3-good-'));
+  const p = join(dir, 'settings.json');
+  writeFileSync(p, JSON.stringify({ permissions: { allow: ['Bash(node scripts/gds/ship.js:*)'] } }, null, 2));
+  const out = m.readSettingsTransform(p);
+  assert.equal(out.parsed, true);
+  assert.ok(out.text.includes('bongos'), 'the parseable path must still rewrite to the bongos bin');
+  assert.equal(out.reason, null);
+  rmSync(dir, { recursive: true, force: true });
+});
+
+t('transformSettings keeps its string contract for existing callers', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'w3-str-'));
+  const p = join(dir, 'settings.json');
+  writeFileSync(p, BROKEN_SETTINGS);
+  assert.equal(typeof m.transformSettings(p), 'string');
+  assert.equal(m.transformSettings(p), BROKEN_SETTINGS);
+  rmSync(dir, { recursive: true, force: true });
+});
+
+t('materializeClaude: a broken core settings.json reaches the instance unchanged, with a note', () => {
+  const core = mkdtempSync(join(tmpdir(), 'bad-core-'));
+  const inst = mkdtempSync(join(tmpdir(), 'bad-inst-'));
+  mkdirSync(join(core, '.claude'), { recursive: true });
+  writeFileSync(join(core, '.claude', 'settings.json'), BROKEN_SETTINGS);
+  const summary = m.materializeClaude({ coreRoot: core, instanceDir: inst, dryRun: false });
+  assert.equal(readFileSync(join(inst, '.claude', 'settings.json'), 'utf8'), BROKEN_SETTINGS,
+    'the instance must receive exactly what the core had, not a worse file');
+  assert.equal(summary.settingsUnparsed, true, 'the summary must record that nothing was rewritten');
+  assert.ok(summary.notes.some((n) => n.includes('not valid JSON')),
+    'a silent copy-through is how an operator never learns their hooks were not rewritten');
+  rmSync(core, { recursive: true, force: true });
+  rmSync(inst, { recursive: true, force: true });
+});
+
 console.log(`\nclaude_materialize: ${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);

package/tests/ship_merge_gate.mjs

@@ -0,0 +1,172 @@
+// tests/ship_merge_gate.mjs — the fitness gate on the merge result (task 1004032).
+//
+// WHY. The local-merge land path pushes straight to origin/main, where no
+// required status check can reach it. On 2026-09-17 a branch that ALREADY
+// failed fitness was merged and pushed by ship.js, main went red, and three
+// confirmed tasks could not land until the baseline was raised by hand.
+//
+// The load-bearing assertions are the two that were wrong before this gate
+// existed: a merge result that regresses a clean base must be REFUSED, and a
+// failure inherited from an already-red base must NOT be — a gate that blocked
+// on an inherited failure would have deadlocked that same incident instead of
+// merely spoiling an afternoon.
+//
+// The decision is exercised as the pure function it is; the wiring is pinned
+// separately by reading ship-merge.js, because a correct verdict that is never
+// consulted, or consulted after the push, is worth nothing.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const gate = require(path.join(ROOT, 'scripts', 'gds', 'ship-merge-gate.js'));
+
+test('a clean merge result is waved through, and the base is never consulted', () => {
+  assert.deepEqual(gate.mergeGateVerdict({ mergeClean: true, baseClean: null }), { block: false, reason: 'clean' });
+  assert.deepEqual(gate.mergeGateVerdict({ mergeClean: true, baseClean: false }), { block: false, reason: 'clean' });
+});
+
+test('THE INCIDENT: a failing merge result over a clean base is REFUSED', () => {
+  const verdict = gate.mergeGateVerdict({ mergeClean: false, baseClean: true });
+  assert.equal(verdict.block, true, 'a branch that turns main red must not be pushed');
+  assert.equal(verdict.reason, 'regression');
+});
+
+test('an INHERITED failure is not the shipper’s fault — it must not block', () => {
+  const verdict = gate.mergeGateVerdict({ mergeClean: false, baseClean: false });
+  assert.equal(verdict.block, false, 'blocking here deadlocks every ship while main is red');
+  assert.equal(verdict.reason, 'pre-existing');
+});
+
+test('an unmeasurable base blocks — the gate may not guess innocence', () => {
+  for (const baseClean of [null, undefined]) {
+    const verdict = gate.mergeGateVerdict({ mergeClean: false, baseClean });
+    assert.equal(verdict.block, true);
+    assert.equal(verdict.reason, 'unmeasured-base');
+  }
+});
+
+test('every verdict reason carries a message that names its own case', () => {
+  const seen = new Set();
+  for (const reason of ['clean', 'pre-existing', 'regression', 'unmeasured-base']) {
+    const msg = gate.gateMessage(reason);
+    assert.match(msg, /fitness/, `${reason} must say what was measured`);
+    assert.equal(seen.has(msg), false, `${reason} reuses another verdict’s wording`);
+    seen.add(msg);
+  }
+  // A blocked ship has to say the task is parked, or the builder reads a bare
+  // failure and re-runs the ship instead of fixing the tree.
+  assert.match(gate.gateMessage('regression'), /confirmed/);
+  assert.match(gate.gateMessage('unmeasured-base'), /confirmed/);
+});
+
+test('probeBaseClean cannot answer without a base commit', () => {
+  // The null-sha case must not reach `git worktree add` at all: an empty ref
+  // there resolves to HEAD, which after the merge is the merge itself — the
+  // gate would then compare the merge result against ITSELF and always pass.
+  assert.equal(gate.probeBaseClean(ROOT, null), null);
+  assert.equal(gate.probeBaseClean(ROOT, ''), null);
+});
+
+test('WIRING: ship-merge.js runs the gate BEFORE the push that makes it main', () => {
+  const src = fs.readFileSync(path.join(ROOT, 'scripts', 'gds', 'ship-merge.js'), 'utf8');
+  const gateAt = src.indexOf('gateMergeResult({');
+  const pushAt = src.indexOf('push-main.js');
+  assert.notEqual(gateAt, -1, 'ship-merge.js must call the gate');
+  assert.notEqual(pushAt, -1, 'ship-merge.js must still push through push-main.js');
+  assert.ok(gateAt < pushAt, 'the gate runs after the push — it would measure a main that is already red');
+  // …and it must actually act on the verdict. A call whose result is dropped
+  // reads as a gate in a diff and is a no-op at runtime.
+  assert.match(src, /fitnessVerdict\.block/, 'the verdict must be consulted');
+  assert.match(src.slice(gateAt, pushAt), /return landBailed\(/, 'a blocked merge must bail before the push');
+});
+
+test('the gate measures the PRE-MERGE base, captured before the branch lands', () => {
+  const src = fs.readFileSync(path.join(ROOT, 'scripts', 'gds', 'ship-merge.js'), 'utf8');
+  const baseAt = src.indexOf('const baseSha =');
+  const mergeAt = src.indexOf('buildMergeArgv(branch, valueSummary)');
+  assert.notEqual(baseAt, -1, 'the base sha must be captured');
+  assert.ok(baseAt < mergeAt, 'the base sha is read after the merge — it would name the merge commit itself');
+});
+
+// The bug that the first cut of this gate actually shipped with, and that only
+// a replay of the real incident caught: fitness.js resolves the repo it
+// measures from its OWN __dirname and ignores cwd, so running this worktree's
+// copy against another tree measures this worktree and calls the other one
+// clean. These fixtures are exit codes, not real gates — if runFitnessAt ever
+// goes back to invoking a fixed sibling script, the failing fixture returns
+// true and this reds.
+function fakeTree(exitCode) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'merge-gate-fixture-'));
+  fs.mkdirSync(path.join(dir, 'scripts', 'gds'), { recursive: true });
+  const body = exitCode === 0 ? 'process.exit(0);\n' : `process.exit(${exitCode});\n`;
+  fs.writeFileSync(path.join(dir, 'scripts', 'gds', 'fitness.js'), body);
+  return dir;
+}
+
+test('runFitnessAt runs the MEASURED TREE\u2019s own fitness.js, not this one\u2019s', () => {
+  const green = fakeTree(0);
+  const red = fakeTree(1);
+  try {
+    assert.equal(gate.runFitnessAt(green), true, 'a passing tree must certify');
+    assert.equal(gate.runFitnessAt(red), false, 'a failing tree reported clean means the wrong tree was measured');
+  } finally {
+    fs.rmSync(green, { recursive: true, force: true });
+    fs.rmSync(red, { recursive: true, force: true });
+  }
+});
+
+test('a tree with no fitness.js cannot be certified', () => {
+  const bare = fs.mkdtempSync(path.join(os.tmpdir(), 'merge-gate-bare-'));
+  try {
+    assert.equal(gate.runFitnessAt(bare), false, 'no gate present must read as "cannot certify", never as clean');
+  } finally {
+    fs.rmSync(bare, { recursive: true, force: true });
+  }
+});
+
+// The hacker finding on the first cut: a boolean outcome made "fitness crashed"
+// and "fitness found something" the same answer, and since a FAILING base waves
+// the ship through, a merely-broken probe would have certified a real
+// regression as inherited. A control that degrades to permissive under infra
+// flakiness is not a control.
+test('a crashed run is UNMEASURABLE, not a finding', () => {
+  const crashed = fs.mkdtempSync(path.join(os.tmpdir(), 'merge-gate-crash-'));
+  fs.mkdirSync(path.join(crashed, 'scripts', 'gds'), { recursive: true });
+  // A tree whose gate cannot even be parsed: node exits non-zero, so this one
+  // still reads as a finding — that is deliberate, it IS a broken committed
+  // gate. The infra case is the one below it: no gate in the tree at all.
+  try {
+    assert.equal(gate.fitnessOutcome(path.join(crashed, 'nope')), 'unmeasurable');
+    assert.equal(gate.fitnessOutcome(crashed), 'unmeasurable', 'a tree with no fitness.js cannot be judged');
+  } finally {
+    fs.rmSync(crashed, { recursive: true, force: true });
+  }
+});
+
+test('the tri-state keeps clean and failing apart', () => {
+  const green = fs.mkdtempSync(path.join(os.tmpdir(), 'merge-gate-green-'));
+  const red = fs.mkdtempSync(path.join(os.tmpdir(), 'merge-gate-red-'));
+  for (const [dir, code] of [[green, 0], [red, 1]]) {
+    fs.mkdirSync(path.join(dir, 'scripts', 'gds'), { recursive: true });
+    fs.writeFileSync(path.join(dir, 'scripts', 'gds', 'fitness.js'), `process.exit(${code});\n`);
+  }
+  try {
+    assert.equal(gate.fitnessOutcome(green), 'clean');
+    assert.equal(gate.fitnessOutcome(red), 'failing', 'a non-zero exit is a real verdict, not infra noise');
+  } finally {
+    fs.rmSync(green, { recursive: true, force: true });
+    fs.rmSync(red, { recursive: true, force: true });
+  }
+});
+
+test('an unmeasurable base blocks rather than waving the ship through', () => {
+  // The end-to-end shape of the finding: probeBaseClean returns null for a base
+  // it could not measure, and null blocks.
+  assert.equal(gate.mergeGateVerdict({ mergeClean: false, baseClean: null }).block, true);
+});