@bongos/core 1.19.266 → 1.19.267

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.266",
-  "core_contract": "1.19.266",
-  "source_commit": "d91db4e58ad64674e65d64d611241e88e02188ac",
+  "core_version": "1.19.267",
+  "core_contract": "1.19.267",
+  "source_commit": "438a7182b523f2e5d9bd4181397642f51b75c77d",
   "source_ref": "HEAD",
-  "built_at": "2026-08-20T17:59:23.193Z",
+  "built_at": "2026-08-20T18:45:39.708Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 318,
     "agent_docs_stubbed": 22,
-    "functional_verbatim": 1365,
+    "functional_verbatim": 1367,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1705,
-  "tree_sha256": "22cc9e757ec02b637af6ec28f6d00b5daa91a92f742361641d8921f5ecd27996",
+  "file_count": 1707,
+  "tree_sha256": "c333d9a98c37d10dd8a8e60d7c3f1a279fab0365ab4462a4a64517d5e681e77f",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -3169,6 +3169,11 @@
       "mode": "0000644",
       "sha256": "b651b73c65b0da33284430b430638dbc39b34db43846a05ab431deaabcc44b3b"
     },
+    {
+      "path": "modules/grading/generated-provenance.js",
+      "mode": "0000644",
+      "sha256": "43e94be02fe20891633f7fbe7abe0caf774d86743cbce4c5ec34b8499e22e125"
+    },
     {
       "path": "modules/grading/grader-rubric.json",
       "mode": "0000644",
@@ -3217,7 +3222,7 @@
     {
       "path": "modules/grading/grader-workers/worker-prompt.js",
       "mode": "0000644",
-      "sha256": "986c7b039f392704613160c7ee10738030ef47972150d867e0972f6dfb761ae4"
+      "sha256": "4fc9198ba4df9ee8aacb8c48f2a1b1fcc9f076ccb4b751ec45fd91af26edad91"
     },
     {
       "path": "modules/grading/grader-workers/worker-verdict.js",
@@ -3227,7 +3232,7 @@
     {
       "path": "modules/grading/grader.js",
       "mode": "0000644",
-      "sha256": "49ae9286fea73fbf67a89e42bf10a14f9fb04d7857582accaab402ad966fafd6"
+      "sha256": "a37f5327f986f34bb67496052a9892228b432fdfcca61d52970b22c10ac74fa8"
     },
     {
       "path": "modules/grading/module.json",
@@ -4467,12 +4472,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "6f22594e4af013cef5cb741be874306be308300163055bd00a6c929d48b6de93"
+      "sha256": "593aec1826ec6611b0b879e4d71faeaac1fb32934aae45ac5abbf726f44c029e"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "0d77282b3bbfdbff7f582d9a7765a174a8881b18ef150dcbf6d2b640a104069a"
+      "sha256": "b1c9f3acb84a8ed67474e02d525666855953406b4393eb0b4fbbece6cd92b0e8"
     },
     {
       "path": "public-docs/index.html",
@@ -5117,7 +5122,7 @@
     {
       "path": "scripts/gds/fitness.js",
       "mode": "0000644",
-      "sha256": "a5fa6432b70c9b18d39d08837edd17987982a12595c1a55bb44585f9af71628d"
+      "sha256": "e4399cd9d5283ff23b8c5baf9e7b22a4663cab3f6e0e477b138f279cda50bd72"
     },
     {
       "path": "scripts/gds/gate-review.js",
@@ -6117,7 +6122,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "c1a2c62a325a9d5516729a15e8bc8939aa05d2c1e25db859a8ec519e04605186"
+      "sha256": "c52908a516ff2f5cc2147e0a1d0a3c2564713b3dfeada50c5ba142b1e5b5bf32"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -6937,7 +6942,7 @@
     {
       "path": "tests/fitness.mjs",
       "mode": "0000644",
-      "sha256": "fb9f8fe63f0f9447ab82ba171b718855e4157846ae4a292e907ff895faa892a3"
+      "sha256": "de84ceb6c73818975d5da77949c8ff4823f6e9d4613d9c95ea21c96a92b66760"
     },
     {
       "path": "tests/fitness_ratchets.mjs",
@@ -7274,6 +7279,11 @@
       "mode": "0000644",
       "sha256": "5f01a094ba58b6c39c8d386162399a1ed81fee400c12d0feb932485af3875234"
     },
+    {
+      "path": "tests/grader_generated_provenance.mjs",
+      "mode": "0000644",
+      "sha256": "6e1288f285bfce6cecc080d597455b9051754efa0d2f885cf03a9ee4cea4c6a8"
+    },
     {
       "path": "tests/grader_panel.mjs",
       "mode": "0000644",

package/modules/grading/generated-provenance.js

@@ -0,0 +1,260 @@
+// modules/grading/generated-provenance.js — task 1002795.
+//
+// THE FALSE POSITIVE THIS EXISTS TO KILL. Several tracked files carry regions
+// written by a generator, fenced with a "do not hand-edit" banner. Adding a
+// docs/session-logs/ file makes the fitness "generated artifacts fresh" check go
+// RED until you run gen-session-index.js and COMMIT its rewrite of the CLAUDE.md
+// §13 block. So the ship's own diff necessarily contains changed lines inside a
+// fence that says "do not hand-edit" — and the grader panel, which reads only
+// the diff, gates the ship as a hand-edit. It is unresolvable by re-grading:
+// generator output is textually IDENTICAL to typing the same characters, so no
+// amount of re-reading the diff can tell them apart. On task 1002794 it went
+// 7/10, then 4/10 as the finding was re-flagged "unresolved" under the delta
+// re-grade policy, and adding a rebuttal to the ship notes made it WORSE.
+//
+// THE FIX is to give the panel the provenance it lacks, from the one authority
+// that HAS it: each generator's own --check/--check-block flag REGENERATES from
+// source and compares, rather than reading the diff. If that check passes, the
+// committed region is provably the generator's output. That is a fact about the
+// tree, not an opinion about a diff, and it is exactly what fitness.js gates on.
+//
+// Deliberately NOT the broader options in the task: this does not exclude the
+// regions from the diff (a worker that cannot see them cannot notice a real
+// hand-edit smuggled in beside them), and it does not mark regions and trust the
+// marking (the marking is what the builder controls). It verifies, then reports.
+//
+// The generator roster MUST stay in lockstep with fitness.js
+// checkGeneratedArtifactsFresh() — that is the check whose red/green this
+// mirrors. tests/grader_generated_provenance.mjs pins both sides.
+
+const path = require('node:path');
+const { execFile, execFileSync } = require('node:child_process');
+
+// A generator script lives in the very tree being graded, so an in-diff edit
+// could make it hang — and an unbounded spawn on the grade path would hang the
+// grade with it. fitness.js's equivalent spawns are likewise untimed; this is
+// the bounded version. gen-repo-map walks the whole .js tree, so the budget is
+// generous rather than tight: it exists to stop a hang, not to race a slow disk.
+const VERIFY_TIMEOUT_MS = 120000;
+
+// A minimal environment for the spawn. A generator regenerates a doc from source
+// files; it has no business reading the session's credentials, tokens, or API
+// keys, and nothing here needs LD_PRELOAD-style injection either. Allowlist, so
+// a variable added to the session later is excluded by default.
+const SPAWN_ENV = Object.freeze(Object.fromEntries(
+  ['PATH', 'HOME', 'NODE_PATH', 'LANG', 'LC_ALL', 'TZ', 'TMPDIR', 'SystemRoot', 'ComSpec']
+    .filter((k) => process.env[k] !== undefined)
+    .map((k) => [k, process.env[k]])
+));
+
+// One entry per generator fitness gates, with the tracked files it owns and how
+// much of each it owns. `fence` = only the region between the markers is
+// generated (the rest of the file is hand-authored and must be graded normally).
+// `whole` = the entire file is generator output.
+const GENERATORS = [
+  {
+    script: 'gen-repo-map.js',
+    verify: '--check-block',
+    owns: [
+      { file: 'src/bongos/CLAUDE.md', scope: 'fence', marker: 'BEGIN GENERATED REPO-MAP' },
+      { file: 'src/bongos/routes/CLAUDE.md', scope: 'fence', marker: 'BEGIN GENERATED REPO-MAP' },
+      { file: 'scripts/gds/CLAUDE.md', scope: 'fence', marker: 'BEGIN GENERATED REPO-MAP' },
+    ],
+  },
+  {
+    script: 'gen-session-index.js',
+    verify: '--check-block',
+    owns: [{ file: 'CLAUDE.md', scope: 'fence', marker: 'BEGIN GENERATED SESSION-LOG SNIPPET' }],
+  },
+  {
+    script: 'gen-file-map.js',
+    verify: '--check',
+    owns: [{ file: 'docs/file-map.md', scope: 'fence', marker: 'BEGIN GENERATED FILE-MAP' }],
+  },
+  {
+    script: 'gen-api-docs.js',
+    verify: '--check',
+    owns: [
+      { file: 'docs/api/openapi.json', scope: 'whole' },
+      { file: 'docs/api-reference.md', scope: 'whole' },
+      { file: 'docs/routes-permissions.md', scope: 'whole' },
+    ],
+  },
+];
+
+// THE CIRCULARITY GUARD (panel blocker, task 1002795). Verification works by
+// RUNNING a generator out of the tree under review. Round 2 guarded only the
+// generator scripts themselves, which the panel correctly called PARTIAL: a
+// generator also `require`s other repo modules, so a diff touching anything in
+// that require-chain still got its code executed on the grade path — and could
+// still bend the verdict that vouches for it.
+//
+// So the line is drawn where it can be drawn soundly: verification runs ONLY for
+// a diff that introduces no executable file at all. If nothing in the diff can
+// run, then running a generator cannot execute anything the diff added — not the
+// generator, not its imports, not a transitive dependency. No require-chain to
+// reason about, and nothing to keep in sync as the generators grow dependencies.
+//
+// This keeps the case the task exists for: a session-log ship is docs-only, and
+// so is every "regenerate the committed doc" ship — exactly the diffs that hit
+// the false positive. A ship that changes code AND regenerates a doc gets no
+// provenance claim and is graded as it was before this feature: full suspicion,
+// no regression, just no help.
+const EXECUTABLE_RE = /\.(js|mjs|cjs|ts|mts|cts|sh|bash|zsh|py|rb|pl|php|ps1|bat|cmd|node|wasm)$/i;
+
+// A diff is verification-eligible only if EVERY changed path is inert. Unknown
+// extensions are treated as executable (fail closed) — a dotfile-less binary or
+// a `Dockerfile` is not something to run a generator next to on faith.
+function diffCarriesExecutable(changedFiles) {
+  return (Array.isArray(changedFiles) ? changedFiles : []).some((f) => {
+    const p = String(f || '');
+    if (!p) return false;
+    const base = p.split('/').pop() || '';
+    if (EXECUTABLE_RE.test(base)) return true;
+    // No extension at all, or an unrecognised one on a non-doc/data path.
+    return !/\.(md|markdown|json|ya?ml|txt|csv|tsv|sql|html|css|svg|png|jpe?g|gif|webp|ico|lock|toml|ini|cfg|env|gitignore|npmrc|patch|diff|mmd|xml)$/i.test(base);
+  });
+}
+
+// PURE. Which of the changed files are generator-owned, grouped by generator.
+// Returns [] when the diff touches none — the common case, and the reason this
+// costs nothing on a normal ship.
+function generatorsInDiff(changedFiles) {
+  if (diffCarriesExecutable(changedFiles)) return []; // circularity guard — see above
+  const changed = new Set((Array.isArray(changedFiles) ? changedFiles : []).filter(Boolean));
+  const out = [];
+  for (const g of GENERATORS) {
+    const owned = g.owns.filter((o) => changed.has(o.file));
+    if (owned.length) out.push({ script: g.script, verify: g.verify, owned });
+  }
+  return out;
+}
+
+// Runs each implicated generator's OWN freshness check. `run` is injectable so
+// the unit test never spawns a process. A check that throws means the region does
+// NOT match what the generator would produce right now — which is the case where
+// the panel's suspicion is CORRECT, so that file is reported as unverified and
+// gets no provenance claim at all.
+function verifyGeneratedProvenance({ changedFiles, cwd, scriptDir, run } = {}) {
+  try {
+    return _verify({ changedFiles, cwd, scriptDir, run });
+  } catch (_) {
+    // ENRICHMENT ONLY. A failure here must never block or alter a grade, so it
+    // degrades to "no provenance claim" — which is the pre-task-1002795
+    // behaviour, i.e. the panel keeps full suspicion.
+    return { verified: [], unverified: [], checked: [] };
+  }
+}
+
+function _verify({ changedFiles, cwd, scriptDir, run } = {}) {
+  const implicated = generatorsInDiff(changedFiles);
+  const verified = [];
+  const unverified = [];
+  if (implicated.length === 0) return { verified, unverified, checked: [] };
+  const dir = scriptDir || path.join(__dirname, '..', '..', 'scripts', 'gds');
+  const exec = run || ((script, flag) => {
+    execFileSync(process.execPath, [path.join(dir, script), flag], {
+      cwd: cwd || process.cwd(), stdio: 'pipe', timeout: VERIFY_TIMEOUT_MS, env: SPAWN_ENV,
+    });
+  });
+  const checked = [];
+  for (const g of implicated) {
+    let ok = true;
+    let reason = null;
+    try {
+      exec(g.script, g.verify);
+    } catch (err) {
+      ok = false;
+      reason = `${g.script} ${g.verify} did not pass`;
+    }
+    checked.push({ script: g.script, verify: g.verify, ok });
+    for (const o of g.owned) {
+      (ok ? verified : unverified).push({ ...o, script: g.script, verify: g.verify, ...(ok ? {} : { reason }) });
+    }
+  }
+  return { verified, unverified, checked };
+}
+
+// PURE. The prompt section. Empty string when the diff touches no generated
+// file, so a normal ship's prompt is byte-identical to before.
+function provenanceSection(manifest) {
+  const verified = (manifest && manifest.verified) || [];
+  const unverified = (manifest && manifest.unverified) || [];
+  if (verified.length === 0 && unverified.length === 0) return '';
+  const lines = [];
+  lines.push('---');
+  lines.push('## Generated content in this diff (provenance — VERIFIED, not asserted)');
+  lines.push('');
+  if (verified.length) {
+    lines.push('Each region below was checked by RE-RUNNING its generator against this committed tree and comparing the output. The check passed, so the committed content is provably what the generator produces — it is machine output, not an authored edit:');
+    lines.push('');
+    for (const v of verified) {
+      lines.push(v.scope === 'whole'
+        ? `- \`${v.file}\` — ENTIRE FILE is output of \`${v.script}\` (verified: \`${v.script} ${v.verify}\` passed)`
+        : `- \`${v.file}\` — only the region inside the \`${v.marker}\` fence is output of \`${v.script}\` (verified: \`${v.script} ${v.verify}\` passed)`);
+    }
+    lines.push('');
+    lines.push('**Do not report changes in these regions as hand-edits, as violations of their own "do not hand-edit" banner, or as unexplained/unrelated churn.** Committing them is REQUIRED: the fitness gate fails until the regenerated output is committed, so a ship that touches a session log or a route signature cannot avoid this diff. Generator output is textually identical to typing the same characters, so the diff alone cannot distinguish them — that is precisely why the verification above was run for you, and why re-reading the diff cannot overturn it.');
+    lines.push('');
+    lines.push('Grade these regions on ONE question only: was regenerating correct here — i.e. does the diff carry the generated change the authored change implies? For a fenced file, everything OUTSIDE the named fence is hand-authored and must be graded normally.');
+    lines.push('');
+  }
+  if (unverified.length) {
+    lines.push('These generated files changed but their generator\'s own check did NOT pass, so their content is NOT verified as machine output — treat changes here with full suspicion, including as possible hand-edits:');
+    lines.push('');
+    for (const u of unverified) lines.push(`- \`${u.file}\` — ${u.reason}`);
+    lines.push('');
+  }
+  return lines.join('\n');
+}
+
+// ASYNC verification — the form the grade path uses. The sync variant blocks the
+// event loop while a generator fully regenerates and compares (gen-repo-map
+// walks the whole .js tree), which would stall any other concurrent grading in
+// the same process. gradeSubagent is already async and verifies ONCE per grade
+// before the panel spawns, so nothing needs to block: prompt construction only
+// READS the finished manifest.
+async function verifyGeneratedProvenanceAsync({ changedFiles, cwd, scriptDir, run } = {}) {
+  const implicated = generatorsInDiff(changedFiles);
+  const empty = { verified: [], unverified: [], checked: [] };
+  if (implicated.length === 0) return empty;
+  const dir = scriptDir || path.join(__dirname, '..', '..', 'scripts', 'gds');
+  const runOne = run || ((script, flag) => new Promise((resolve, reject) => {
+    execFile(process.execPath, [path.join(dir, script), flag],
+      { cwd: cwd || process.cwd(), timeout: VERIFY_TIMEOUT_MS, env: SPAWN_ENV },
+      (err) => (err ? reject(err) : resolve()));
+  }));
+  try {
+    const verified = [];
+    const unverified = [];
+    // Concurrently: each check is an independent whole-repo regeneration, and at
+    // most a handful are ever implicated, so serializing them just added latency
+    // to the grade path for no benefit.
+    const checked = await Promise.all(implicated.map(async (g) => {
+      let ok = true;
+      try { await runOne(g.script, g.verify); } catch (_) { ok = false; }
+      return { script: g.script, verify: g.verify, ok };
+    }));
+    implicated.forEach((g, i) => {
+      const ok = checked[i].ok;
+      for (const o of g.owned) {
+        (ok ? verified : unverified).push({
+          ...o, script: g.script, verify: g.verify,
+          ...(ok ? {} : { reason: `${g.script} ${g.verify} did not pass` }),
+        });
+      }
+    });
+    return { verified, unverified, checked };
+  } catch (_) {
+    // ENRICHMENT ONLY — degrade to no claim (the pre-task behaviour: the panel
+    // keeps full suspicion), never fail a grade on a verification problem.
+    return empty;
+  }
+}
+
+module.exports = {
+  GENERATORS, generatorsInDiff, provenanceSection, diffCarriesExecutable,
+  verifyGeneratedProvenance,       // sync — kept for DB-free unit tests + non-async callers
+  verifyGeneratedProvenanceAsync,  // the grade path: non-blocking, once per grade
+  VERIFY_TIMEOUT_MS,
+};

package/modules/grading/grader-workers/worker-prompt.js

@@ -14,6 +14,14 @@
 // Unified diff). Behavior-neutral: produces the identical string the inlined
 // builders produced for the same inputs.
 const { fenceBlock, scrubUntrusted, NOFOLLOW_PREAMBLE } = require('./fence');
+// task 1002795: VERIFIED provenance for generator-owned regions of the diff.
+// Trusted text — the verification re-ran each generator's own --check against
+// the committed tree, so it is the one thing here the builder cannot influence
+// by writing content, and it sits OUTSIDE every fence. Already computed by the
+// caller (once per grade, off this path), so building a prompt does no work and
+// spawns nothing. Empty when the diff touches no generated file, leaving a
+// normal ship's prompt byte-identical to before.
+const { provenanceSection } = require('../generated-provenance');
 
 // The instance's project name for the worker identity lines, so a non-OTB Cloud
 // Bongos instance is graded against ITS OWN project instead of a hardcoded "Off
@@ -138,6 +146,10 @@ function buildWorkerPrompt({
       lines.push('');
     }
   }
+  if (contextBundle && contextBundle.generatedProvenance) {
+    const provSection = provenanceSection(contextBundle.generatedProvenance);
+    if (provSection) lines.push(provSection);
+  }
   // task 1002662: prior panel round context for a delta-aware re-grade. The
   // findings/response/interim summary are builder-adjacent data → fenced; the
   // policy that governs them is trusted text outside the fences.

package/modules/grading/grader.js

@@ -108,6 +108,7 @@ const FALLTHROUGH_CONFIDENCE = V4.fallthrough_confidence ?? 0.3;
 // values are model ids. workerModelFor guards the cross-model invariant.
 const WORKER_MODEL_TIERS = V4.worker_model_tiers || {};
 const workers = require('./grader-workers');
+const generatedProvenance = require('./generated-provenance'); // task 1002795
 // Carved into modules/grading/ (BV1.R73 / ADR 0091 §1+§4): the two deterministic
 // trust classifiers are KERNEL (KERNEL_FILES, R70) — reached through the doorway,
 // never a deep core require. The worker panel + extract-json are intra-module.
@@ -312,7 +313,7 @@ Return ONLY JSON matching this schema — no prose before or after, no markdown
 
 You have a Read tool. Spend reads checking that removed code is unreferenced elsewhere, that new helpers match surrounding style, that the diff's value_summary matches what the diff actually does, and that acceptance criteria you can't verify from the diff alone are actually satisfied in the post-merge file. Do not run tests, do not edit files, do not call the network.`;
 
-function buildPrompt({ task, valueSummary, diff, changedFiles, diffStats }) {
+function buildPrompt({ task, valueSummary, diff, changedFiles, diffStats, generatedProvenance: prov = null }) {
   const t = task || {};
   const desc = (t.description || '(no description)').trim();
   const title = (t.title || '(no title)').trim();
@@ -371,7 +372,7 @@ function buildPrompt({ task, valueSummary, diff, changedFiles, diffStats }) {
   lines.push('```diff');
   lines.push(diffText);
   lines.push('```');
-  lines.push('');
+  lines.push('', ...(prov ? [generatedProvenance.provenanceSection(prov)].filter(Boolean) : [])); // task 1002795 — the trivial path is where a docs-only ship lands
   lines.push('Now grade. Default-fail unless your read of the diff and post-merge files turns up no material problems. Output ONLY the JSON object — nothing before or after it.');
   return lines.join('\n');
 }
@@ -1771,7 +1772,7 @@ async function gradeSubagent({ task, valueSummary, diff, changedFiles, diffStats
   // kills the per-worker re-exploration that dominated panel cost.
   // diff (task 1002905): lets the bundle prove a truncated prefix actually shows
   // the change instead of handing a worker a head fragment as "post-change".
-  const contextBundle = buildContextBundle({ changedFiles, cwd: runOpts.cwd, diff });
+  const contextBundle = Object.assign(...await Promise.all([buildContextBundle({ changedFiles, cwd: runOpts.cwd, diff }), generatedProvenance.verifyGeneratedProvenanceAsync({ changedFiles, cwd: runOpts.cwd }).then((generatedProvenance) => ({ generatedProvenance }))])); // task 1002795 — verified once, concurrently with the bundle read, off the prompt path
   // task 1002660: cache-wrapped spawns. Same prompt + model replays at $0
   // (llm-cache, System 5) — the prompt embeds the diff + bundle, so the key
   // needs no separate scope sha. Absent llm-cache → plain runSubagent.
@@ -1831,7 +1832,7 @@ async function gradeSubagent({ task, valueSummary, diff, changedFiles, diffStats
 // (gradeSubagent) points at the v4 panel. Useful for re-running a single
 // generalist prompt N times for diagnostic comparison against the panel.
 async function gradeSubagentV3MultiShot({ task, valueSummary, diff, changedFiles, diffStats, shots = DEFAULT_SHOTS, builderModel, runOpts = {} }) {
-  const prompt = buildPrompt({ task, valueSummary, diff, changedFiles, diffStats });
+  const prompt = buildPrompt({ task, valueSummary, diff, changedFiles, diffStats, generatedProvenance: await generatedProvenance.verifyGeneratedProvenanceAsync({ changedFiles, cwd: runOpts.cwd }) }); // task 1002795
   const graderModel = selectGraderModel({ builderModel });
   const N = Math.max(1, Math.trunc(shots));
 

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.266",
+  "version": "1.19.267",
   "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.js

@@ -1982,7 +1982,6 @@ module.exports = {
   HOST_GAME,
   GRANDFATHERED,
   LEGACY_NAMESPACED,
-  KERNEL_FILES,
   ROOT_HARD_MAX,
   ROOT_TARGET,
   ROOT_CHAR_HARD_MAX,

package/src/module-api.js

@@ -959,8 +959,10 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.264 with no explicit bump. run 32396925426. (task 1002620)
 //   1.19.266 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.265 with no explicit bump. run 32400609982. (task 1002620)
+//   1.19.267 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.266 with no explicit bump. run 32404853216. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.266'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.267'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // 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.mjs

@@ -596,3 +596,16 @@ test('identity gate strips comments on CRLF checkouts too (task 1002428)', () =>
     'a CRLF code literal must still be caught'
   );
 });
+
+test('KERNEL_FILES is exported exactly ONCE and still resolves (task 1002795)', () => {
+  // fitness.js listed KERNEL_FILES TWICE in the same export literal, so the
+  // second key silently shadowed the first — harmless today, a latent bug the
+  // moment the two diverge. Task 1002795 removed the duplicate. Two grader
+  // rounds read that `-  KERNEL_FILES,` line as "the export was removed", so pin
+  // the actual behaviour here rather than arguing it in a ship note.
+  const src = fs.readFileSync(path.join(ROOT, 'scripts/gds/fitness.js'), 'utf8');
+  const decls = src.split('\n').filter((l) => l.trim() === 'KERNEL_FILES,');
+  assert.equal(decls.length, 1, 'exactly one export entry — no duplicate key');
+  assert.ok(Array.isArray(fitness.KERNEL_FILES), 'and it still resolves to an array');
+  assert.ok(fitness.KERNEL_FILES.length > 0, 'with the real kernel roster in it');
+});

package/tests/grader_generated_provenance.mjs

@@ -0,0 +1,363 @@
+// tests/grader_generated_provenance.mjs — task 1002795.
+//
+// THE FALSE POSITIVE: adding a docs/session-logs/ file makes the fitness
+// "generated artifacts fresh" check go RED until gen-session-index.js is run and
+// its rewrite of the CLAUDE.md §13 block is COMMITTED. So the ship's diff
+// necessarily contains changed lines inside a fence reading "do not hand-edit",
+// and the grader panel — which reads only the diff — gated the ship as a
+// hand-edit. It was unresolvable by re-grading (generator output is textually
+// identical to typing the same characters), went 7/10 then 4/10 under the delta
+// re-grade policy as the finding was re-flagged unresolved, and each round cost
+// ~1 USD. It will fire on EVERY session-log ship.
+//
+// What we prove here (all pure or injected — no subprocess, no network):
+//   1. The generator roster stays in LOCKSTEP with fitness.js
+//      checkGeneratedArtifactsFresh(). That check's red/green is the authority
+//      this feature mirrors; if a generator is added there and not here, the
+//      false positive comes back for that file, silently.
+//   2. generatorsInDiff is exact: only generator-owned changed files implicate a
+//      generator, and an ordinary diff implicates none (so a normal ship pays
+//      nothing and its prompt is unchanged).
+//   3. A PASSING generator check marks the region verified; a FAILING one marks
+//      it unverified — the panel must keep its suspicion exactly where the
+//      evidence is absent.
+//   4. The prompt section says the load-bearing things: that the check was
+//      re-run rather than asserted, that these are not hand-edits, that
+//      committing them is required, and — for a fenced file — that content
+//      OUTSIDE the fence is still graded normally.
+//   5. It is empty for a clean diff, and an unverified file NEVER gets the
+//      do-not-report-this language.
+//
+// Run:  node tests/grader_generated_provenance.mjs
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+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 prov = require(path.join(ROOT, 'modules/grading/generated-provenance.js'));
+
+// ---- 1. lockstep with the fitness gate ----
+
+test('the generator roster matches fitness.js checkGeneratedArtifactsFresh exactly', () => {
+  const src = fs.readFileSync(path.join(ROOT, 'scripts/gds/fitness.js'), 'utf8');
+  const fn = src.slice(src.indexOf('function checkGeneratedArtifactsFresh'));
+  const body = fn.slice(0, fn.indexOf('\nfunction ', 1));
+
+  // Every generator fitness runs must be in our roster, with the SAME flag —
+  // a --check-block gate mirrored as --check would compare the wrong thing.
+  const fitnessPairs = [...body.matchAll(/'(gen-[a-z-]+\.js)'\], \{|\bgen-[a-z-]+\.js/g)];
+  const fitnessScripts = new Set(
+    [...body.matchAll(/(gen-[a-z-]+\.js)'\)?,\s*'(--check(?:-block)?)'/g)].map((m) => `${m[1]} ${m[2]}`)
+  );
+  assert.ok(fitnessPairs.length > 0, 'sanity: found generator references in the fitness check');
+  assert.ok(fitnessScripts.size >= 4, `expected >=4 (script, flag) pairs in the fitness check, found ${fitnessScripts.size}: ${[...fitnessScripts].join(' | ')}`);
+
+  const ours = new Set(prov.GENERATORS.map((g) => `${g.script} ${g.verify}`));
+  for (const pair of fitnessScripts) {
+    assert.ok(ours.has(pair), `fitness gates "${pair}" but generated-provenance.js does not — the false positive is live for its files`);
+  }
+  for (const pair of ours) {
+    assert.ok(fitnessScripts.has(pair), `generated-provenance.js claims "${pair}" but fitness does not gate it — provenance would assert freshness nothing enforces`);
+  }
+});
+
+test('every file the roster claims actually exists and carries its fence marker', () => {
+  for (const g of prov.GENERATORS) {
+    for (const o of g.owns) {
+      const abs = path.join(ROOT, o.file);
+      assert.ok(fs.existsSync(abs), `${o.file} (claimed by ${g.script}) does not exist`);
+      if (o.scope === 'fence') {
+        const text = fs.readFileSync(abs, 'utf8');
+        assert.ok(text.includes(o.marker), `${o.file} does not contain its claimed fence marker "${o.marker}"`);
+      }
+    }
+  }
+});
+
+// ---- 2. generatorsInDiff is exact ----
+
+test('an ordinary diff implicates no generator (a normal ship pays nothing)', () => {
+  assert.deepEqual(prov.generatorsInDiff(['src/bongos/serve-internal.js', 'tests/foo.mjs']), []);
+  assert.deepEqual(prov.generatorsInDiff([]), []);
+  assert.deepEqual(prov.generatorsInDiff(null), []);
+});
+
+test('the session-log ship shape implicates exactly gen-session-index.js', () => {
+  // This IS the reproducing diff: a new session log + the regenerated §13 block.
+  const g = prov.generatorsInDiff(['docs/session-logs/2026-08-20-x.md', 'CLAUDE.md']);
+  assert.equal(g.length, 1);
+  assert.equal(g[0].script, 'gen-session-index.js');
+  assert.equal(g[0].verify, '--check-block');
+  assert.deepEqual(g[0].owned.map((o) => o.file), ['CLAUDE.md']);
+});
+
+test('a docs-only regeneration implicates gen-api-docs.js for each doc it owns that changed', () => {
+  const g = prov.generatorsInDiff(['docs/api/openapi.json', 'docs/api-reference.md']);
+  assert.equal(g.length, 1);
+  assert.equal(g[0].script, 'gen-api-docs.js');
+  assert.deepEqual(g[0].owned.map((o) => o.file).sort(), ['docs/api-reference.md', 'docs/api/openapi.json']);
+  // routes-permissions.md did NOT change, so it is not claimed.
+  assert.ok(!g[0].owned.some((o) => o.file === 'docs/routes-permissions.md'));
+});
+
+test('THE DELIBERATE TRADE: a route change + its regenerated docs gets NO claim', () => {
+  // Adding a .js to the diff makes it ineligible, by design — see the guard.
+  // Such a ship is graded exactly as it was before this feature (full
+  // suspicion): no help, but no regression either. The alternative was reasoning
+  // about a generator's whole require-chain, which the panel rightly rejected as
+  // unsound. The case this feature exists for — the session-log ship — is
+  // docs-only and stays covered.
+  assert.deepEqual(prov.generatorsInDiff(['modules/lifecycle/routes/tasks.js', 'docs/api/openapi.json']), []);
+});
+
+// ---- 3. verify: pass ⇒ verified, fail ⇒ unverified ----
+
+test('a PASSING generator check marks its regions verified', () => {
+  const calls = [];
+  const m = prov.verifyGeneratedProvenance({
+    changedFiles: ['CLAUDE.md', 'docs/session-logs/x.md'],
+    run: (script, flag) => { calls.push(`${script} ${flag}`); },
+  });
+  assert.deepEqual(calls, ['gen-session-index.js --check-block'], 'runs the generator ONE time, with its own flag');
+  assert.deepEqual(m.verified.map((v) => v.file), ['CLAUDE.md']);
+  assert.deepEqual(m.unverified, []);
+  assert.deepEqual(m.checked, [{ script: 'gen-session-index.js', verify: '--check-block', ok: true }]);
+});
+
+test('a FAILING generator check marks its regions UNVERIFIED — suspicion stays where evidence is absent', () => {
+  const m = prov.verifyGeneratedProvenance({
+    changedFiles: ['CLAUDE.md'],
+    run: () => { throw new Error('exit 2'); },
+  });
+  assert.deepEqual(m.verified, []);
+  assert.equal(m.unverified.length, 1);
+  assert.equal(m.unverified[0].file, 'CLAUDE.md');
+  assert.match(m.unverified[0].reason, /did not pass/);
+});
+
+test('a clean diff runs NO generator at all', () => {
+  let ran = 0;
+  const m = prov.verifyGeneratedProvenance({ changedFiles: ['README.md'], run: () => { ran++; } });
+  assert.equal(ran, 0, 'no subprocess on a diff that touches no generated file');
+  assert.deepEqual(m, { verified: [], unverified: [], checked: [] });
+});
+
+test('one generator failing does not taint another that passed', () => {
+  const m = prov.verifyGeneratedProvenance({
+    changedFiles: ['CLAUDE.md', 'docs/api/openapi.json'],
+    run: (script) => { if (script === 'gen-api-docs.js') throw new Error('stale'); },
+  });
+  assert.deepEqual(m.verified.map((v) => v.file), ['CLAUDE.md']);
+  assert.deepEqual(m.unverified.map((v) => v.file), ['docs/api/openapi.json']);
+});
+
+// ---- 4/5. the prompt section ----
+
+test('the section is EMPTY for a diff with no generated files (prompt unchanged)', () => {
+  assert.equal(prov.provenanceSection({ verified: [], unverified: [], checked: [] }), '');
+  assert.equal(prov.provenanceSection(null), '');
+});
+
+test('the verified section states the load-bearing facts', () => {
+  const m = prov.verifyGeneratedProvenance({ changedFiles: ['CLAUDE.md'], run: () => {} });
+  const s = prov.provenanceSection(m);
+  assert.match(s, /RE-RUNNING its generator/, 'says the check was re-run, not asserted');
+  assert.match(s, /Do not report changes in these regions as hand-edits/, 'gives the instruction that kills the false positive');
+  assert.match(s, /do not hand-edit/, 'names the banner the worker will see in the diff');
+  assert.match(s, /Committing them is REQUIRED/, 'explains why the diff cannot avoid this');
+  assert.match(s, /gen-session-index\.js/, 'names the generator');
+  assert.match(s, /BEGIN GENERATED SESSION-LOG SNIPPET/, 'names the fence, so the scope is unambiguous');
+  assert.match(s, /OUTSIDE the named fence is hand-authored and must be graded normally/,
+    'a fenced file must NOT become a blanket exemption for the whole file');
+});
+
+test('a whole-file generator is described as whole-file, not as a fence', () => {
+  const m = prov.verifyGeneratedProvenance({ changedFiles: ['docs/api/openapi.json'], run: () => {} });
+  const s = prov.provenanceSection(m);
+  assert.match(s, /ENTIRE FILE is output of `gen-api-docs\.js`/);
+  assert.doesNotMatch(s, /region inside the/, 'no fence language for a whole-file artifact');
+});
+
+test('an UNVERIFIED file never receives the do-not-report language', () => {
+  const m = prov.verifyGeneratedProvenance({ changedFiles: ['CLAUDE.md'], run: () => { throw new Error('stale'); } });
+  const s = prov.provenanceSection(m);
+  assert.match(s, /NOT verified as machine output/);
+  assert.match(s, /full suspicion/);
+  assert.doesNotMatch(s, /Do not report changes in these regions as hand-edits/,
+    'the exemption must never leak onto a file whose generator check failed');
+});
+
+// ---- wiring: the section actually reaches a worker prompt ----
+
+// ---- the async form the grade path uses (grader finding: no blocking spawn
+// during prompt construction, and no unbounded spawn at all) ----
+
+test('the async verifier is what the grade path uses, and it does not block', async () => {
+  // The sync variant blocks the event loop while a generator regenerates the
+  // whole repo; gradeSubagent is async and verifies ONCE before the panel
+  // spawns, so prompt construction only READS the finished manifest.
+  const calls = [];
+  const m = await prov.verifyGeneratedProvenanceAsync({
+    changedFiles: ['CLAUDE.md', 'docs/api/openapi.json'],
+    run: async (script, flag) => { calls.push(`${script} ${flag}`); },
+  });
+  assert.deepEqual(calls, ['gen-session-index.js --check-block', 'gen-api-docs.js --check']);
+  assert.deepEqual(m.verified.map((v) => v.file).sort(), ['CLAUDE.md', 'docs/api/openapi.json']);
+});
+
+test('the async verifier runs NOTHING for a diff with no generated file', async () => {
+  let ran = 0;
+  const m = await prov.verifyGeneratedProvenanceAsync({ changedFiles: ['README.md'], run: async () => { ran++; } });
+  assert.equal(ran, 0);
+  assert.deepEqual(m, { verified: [], unverified: [], checked: [] });
+});
+
+test('the async verifier marks a rejecting check unverified, and never rejects itself', async () => {
+  const m = await prov.verifyGeneratedProvenanceAsync({
+    changedFiles: ['CLAUDE.md'],
+    run: async () => { throw new Error('exit 2'); },
+  });
+  assert.deepEqual(m.verified, []);
+  assert.equal(m.unverified.length, 1);
+  assert.match(m.unverified[0].reason, /did not pass/);
+});
+
+test('both spawns are TIMEOUT-bounded — a generator lives in the tree being graded', () => {
+  // A hanging generator (including one made to hang by an edit in the very diff
+  // under review) must not hang the grade with it.
+  assert.ok(Number.isInteger(prov.VERIFY_TIMEOUT_MS) && prov.VERIFY_TIMEOUT_MS > 0);
+  const src = fs.readFileSync(path.join(ROOT, 'modules/grading/generated-provenance.js'), 'utf8');
+  const spawns = [...src.matchAll(/execFile(?:Sync)?\(/g)];
+  assert.equal(spawns.length, 2, 'exactly the two spawn sites (sync + async)');
+  for (const m of spawns) {
+    const window = src.slice(m.index, m.index + 320);
+    assert.match(window, /timeout: VERIFY_TIMEOUT_MS/, 'every spawn site must be timeout-bounded');
+  }
+});
+
+test('verifyGeneratedProvenance never throws — it degrades to no claim', () => {
+  // A broken runner must not take the grade down with it; the pre-task
+  // behaviour (full suspicion, no provenance) is the safe degradation.
+  const m = prov.verifyGeneratedProvenance({
+    changedFiles: ['CLAUDE.md'],
+    run: () => { throw Object.assign(new Error('boom'), { code: 'EACCES' }); },
+  });
+  assert.ok(m, 'returns a manifest rather than throwing');
+  // A throwing check is a FAILED check, so the region is unverified, not exempt.
+  assert.deepEqual(m.verified, []);
+  assert.equal(m.unverified.length, 1);
+});
+
+test('the shared worker prompt renders a manifest carried on the bundle, and spawns nothing', () => {
+  const { buildWorkerPrompt } = require(path.join(ROOT, 'modules/grading/grader-workers/worker-prompt.js'));
+  const manifest = prov.verifyGeneratedProvenance({ changedFiles: ['CLAUDE.md'], run: () => {} });
+  const base = {
+    header: 'H', task: { id: 1, title: 't', description: 'd' }, valueSummary: 'v',
+    diff: 'diff --git a/CLAUDE.md b/CLAUDE.md', changedFiles: ['CLAUDE.md'],
+    taskHeader: '## Task', descLabel: '**D:**', emptyFilesText: '(none)',
+    readFilesHint: 'hint', finalInstruction: 'go',
+  };
+  const withProv = buildWorkerPrompt({ ...base, contextBundle: { files: [], skipped: [], generatedProvenance: manifest } });
+  assert.match(withProv, /Generated content in this diff/);
+  assert.match(withProv, /Do not report changes in these regions as hand-edits/);
+
+  // No manifest on the bundle → prompt byte-identical to before this task.
+  const without = buildWorkerPrompt({ ...base, contextBundle: { files: [], skipped: [] } });
+  assert.doesNotMatch(without, /Generated content in this diff/);
+});
+
+test('the generalist (trivial-path) prompt renders it too — that is where a docs-only ship lands', () => {
+  const grader = require(path.join(ROOT, 'modules/grading/grader.js'));
+  const manifest = prov.verifyGeneratedProvenance({ changedFiles: ['CLAUDE.md'], run: () => {} });
+  const base = {
+    task: { id: 1, title: 't', description: 'd' }, valueSummary: 'v', diff: 'd',
+    diffStats: { files_changed: 1, lines_added: 3, lines_removed: 3 },
+  };
+  const p = grader.buildPrompt({ ...base, changedFiles: ['CLAUDE.md'], generatedProvenance: manifest });
+  assert.match(p, /Do not report changes in these regions as hand-edits/);
+  const plain = grader.buildPrompt({ ...base, changedFiles: ['src/x.js'] });
+  assert.doesNotMatch(plain, /Generated content in this diff/);
+});
+
+test('grader.js verifies once per grade, OFF the prompt-construction path', () => {
+  // The finding this answers: a blocking spawn during prompt construction would
+  // stall other concurrent grading. Both grade paths must await the ASYNC
+  // verifier and hand the finished manifest to the prompt builders.
+  const src = fs.readFileSync(path.join(ROOT, 'modules/grading/grader.js'), 'utf8');
+  const sites = [...src.matchAll(/generatedProvenance\.verifyGeneratedProvenanceAsync\(/g)];
+  assert.equal(sites.length, 2, 'the panel path and the trivial path each verify once, via the ASYNC verifier');
+  assert.doesNotMatch(src, /verifyGeneratedProvenance\(\{/, 'grader.js must not call the BLOCKING sync verifier');
+  // And the prompt builders must not spawn: worker-prompt only reads the bundle.
+  const wp = fs.readFileSync(path.join(ROOT, 'modules/grading/grader-workers/worker-prompt.js'), 'utf8');
+  assert.doesNotMatch(wp, /verifyGeneratedProvenance/, 'the prompt scaffold must only RENDER, never verify');
+});
+
+// ---- the circularity guard (panel blocker) ----
+
+test('verification runs ONLY for a diff that introduces no executable file', () => {
+  // Round 2 guarded only the generator scripts; the panel correctly called that
+  // partial, because a generator also requires other repo modules. The sound
+  // line: if nothing in the diff can RUN, running a generator cannot execute
+  // anything the diff added — no require-chain to reason about.
+  assert.ok(!prov.diffCarriesExecutable(['CLAUDE.md', 'docs/session-logs/x.md']), 'the motivating case stays eligible');
+  assert.ok(!prov.diffCarriesExecutable(['docs/api/openapi.json', 'docs/api-reference.md']));
+  assert.ok(prov.diffCarriesExecutable(['scripts/gds/gen-repo-map.js']), 'the generator itself');
+  assert.ok(prov.diffCarriesExecutable(['CLAUDE.md', 'modules/lifecycle/db.js']), 'anything a generator might require');
+  assert.ok(prov.diffCarriesExecutable(['CLAUDE.md', 'deploy.sh']), 'shell too');
+  assert.ok(prov.diffCarriesExecutable(['CLAUDE.md', 'tests/x.mjs']));
+  assert.ok(prov.diffCarriesExecutable(['Dockerfile']), 'unknown/extension-less paths fail CLOSED');
+});
+
+test('an ineligible diff SPAWNS NOTHING and claims nothing', async () => {
+  let ran = 0;
+  const files = ['CLAUDE.md', 'modules/lifecycle/db.js'];
+  const sync = prov.verifyGeneratedProvenance({ changedFiles: files, run: () => { ran++; } });
+  const asyncM = await prov.verifyGeneratedProvenanceAsync({ changedFiles: files, run: async () => { ran++; } });
+  assert.equal(ran, 0, 'no generator is executed beside code the diff introduced');
+  for (const m of [sync, asyncM]) {
+    assert.deepEqual(m.verified, [], 'no verified claim');
+    assert.deepEqual(m.unverified, [], 'and no unverified entry either — silence, not a verdict');
+    assert.equal(prov.provenanceSection(m), '', 'the panel keeps full suspicion, exactly as before this feature');
+  }
+});
+
+test('both spawn sites pass a minimal env allowlist — a generator needs no credentials', () => {
+  const src = fs.readFileSync(path.join(ROOT, 'modules/grading/generated-provenance.js'), 'utf8');
+  const spawns = [...src.matchAll(/execFile(?:Sync)?\(/g)];
+  assert.equal(spawns.length, 2);
+  for (const m of spawns) {
+    const window = src.slice(m.index, m.index + 340);
+    assert.match(window, /env: SPAWN_ENV/, 'every spawn site must pass the allowlisted env');
+    assert.match(window, /timeout: VERIFY_TIMEOUT_MS/, 'and stay timeout-bounded');
+  }
+  // The allowlist must not carry anything credential-shaped.
+  const list = src.slice(src.indexOf('const SPAWN_ENV'), src.indexOf('const SPAWN_ENV') + 400);
+  assert.doesNotMatch(list, /TOKEN|KEY|SECRET|PASSWORD|DATABASE_URL|LD_PRELOAD/i);
+});
+
+test('the implicated checks run concurrently, not in series', async () => {
+  let inFlight = 0;
+  let maxInFlight = 0;
+  await prov.verifyGeneratedProvenanceAsync({
+    changedFiles: ['CLAUDE.md', 'docs/api/openapi.json', 'docs/file-map.md'],
+    run: async () => {
+      inFlight += 1;
+      maxInFlight = Math.max(maxInFlight, inFlight);
+      await new Promise((r) => setImmediate(r));
+      inFlight -= 1;
+    },
+  });
+  assert.ok(maxInFlight > 1, `expected overlapping checks, saw max ${maxInFlight} in flight`);
+});
+
+test('the bundle read and the verification run CONCURRENTLY, not in series', () => {
+  const src = fs.readFileSync(path.join(ROOT, 'modules/grading/grader.js'), 'utf8');
+  const line = src.split('\n').find((l) => l.includes('verifyGeneratedProvenanceAsync') && l.includes('buildContextBundle'));
+  assert.ok(line, 'the panel path builds the bundle and verifies on one statement');
+  assert.match(line, /Promise\.all/, 'two independent reads must not be serialized on the grade path');
+});