@bongos/core 1.19.986 → 1.19.987

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.986",
-  "core_contract": "1.19.986",
-  "source_commit": "df54cfbda9edb7e3e5b7f953174e31e6a5b65bc4",
+  "core_version": "1.19.987",
+  "core_contract": "1.19.987",
+  "source_commit": "102ad9a7c1c780717451cc48241d577442dc44f1",
   "source_ref": "HEAD",
-  "built_at": "2026-09-23T18:36:30.871Z",
+  "built_at": "2026-09-23T19:04:45.567Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 518,
     "agent_docs_stubbed": 26,
-    "functional_verbatim": 2390,
+    "functional_verbatim": 2391,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2934,
-  "tree_sha256": "8b898c04436c76259878da047c512541c0d0a03e9de13419b31e0a0d41ffa182",
+  "file_count": 2935,
+  "tree_sha256": "e0b9f64be067a45f8a343766f231127d7bb3708dc50656f188e122f06b15ac2a",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2712,7 +2712,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "e779420483a2e19ea834a5995d1960296dad434fa158c1e46db3ee4e12b6569e"
+      "sha256": "fcad58b07e48eb75f7dbfb280b1d2f167d07a753388aa063d292c7aee323accf"
     },
     {
       "path": "docs/modules-contract.md",
@@ -5707,7 +5707,7 @@
     {
       "path": "modules/lifecycle/cascade.js",
       "mode": "0000644",
-      "sha256": "176f7463d6f3c7bf2297760d0934f88528ee180dfb0c9e49a4347a449af2820d"
+      "sha256": "714bbacc99433c307b949c7f882a081e3dfb77b86c8e472c82a7729b513f7d74"
     },
     {
       "path": "modules/lifecycle/check-rollup.js",
@@ -6092,7 +6092,7 @@
     {
       "path": "modules/lifecycle/routes/lifecycle.js",
       "mode": "0000644",
-      "sha256": "330e42fad79812a05a90256fe31931df2156093b80a648d7c838ecac136c91e4"
+      "sha256": "9f311cf078774875e53c4a07ad65501b09d37a3dbfdbe52d38d394ed555100d1"
     },
     {
       "path": "modules/lifecycle/routes/mingle.js",
@@ -6159,6 +6159,11 @@
       "mode": "0000644",
       "sha256": "bc95dfe95261ddcfdda7f578ba2f4e0e9c1f20d7da955ac5d64800476538bed5"
     },
+    {
+      "path": "modules/lifecycle/ship-files.js",
+      "mode": "0000644",
+      "sha256": "7e0797b26e870d33f054708f2ba717589231c8ccada444ebb03c6234452c8d90"
+    },
     {
       "path": "modules/lifecycle/ship-preflight.js",
       "mode": "0000644",
@@ -6197,7 +6202,7 @@
     {
       "path": "modules/lifecycle/tests/cascade.mjs",
       "mode": "0000644",
-      "sha256": "fc8c5cf14265515faf8dc63b17b80de1acbb7558a08d26808960244aec6e4377"
+      "sha256": "cd0360521e8f89e86fabdf75f41dc213fd2ae5a0ae5a51548441164a915df292"
     },
     {
       "path": "modules/lifecycle/version-autoclose.js",
@@ -8157,12 +8162,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "2fcebda4add1d874aee7ce5f756b37bb55485b6c001aaccde5b0f9624d4c0192"
+      "sha256": "80f51079ed98cab29d9b48f5f20049f58104b76d68645ac01d03a7bdcde9f29e"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "80d5c9a1504e44bfccb0e3bfb0fd38e99eed359118d9d48f12bf9cab895f0533"
+      "sha256": "fe62f7efb8e83d82f66dd2277b8ae4da8d448a9286727ea88460ec358f339fc5"
     },
     {
       "path": "public-docs/index.html",
@@ -9532,7 +9537,7 @@
     {
       "path": "scripts/gds/ship-grade.js",
       "mode": "0000644",
-      "sha256": "40c6a9f6aa6a75cdf8a5e41bfa8318766636cba64e47aee870c26a719676713d"
+      "sha256": "eb0740f3cdc3dc91038320dd9044dc81c05e31212059d772d5c8bf6e9f44b474"
     },
     {
       "path": "scripts/gds/ship-honesty.js",
@@ -10187,7 +10192,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "17399ab568a9343c5c5cead3e1e467af941ec891ee117b424ad0e2ed10151731"
+      "sha256": "19be294e50fce302cf4663c7776dfd8472eaddfb33805baf32b681603271cb77"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -12037,7 +12042,7 @@
     {
       "path": "tests/grader_reader_lens.mjs",
       "mode": "0000644",
-      "sha256": "93e24012252c08798e3017ce9a7130ce9ece4e5e07456892b3632ab12f44ad47"
+      "sha256": "cacfafb2e8408bfcc2137ab1bf11bed21cf95c720aa0a7bc5cdbf0386f4833c8"
     },
     {
       "path": "tests/grader_regrade_delta.mjs",

package/docs/module-api-changelog.md

@@ -2446,5 +2446,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.984 with no explicit bump. run 35902000024. (task 1002620)
   1.19.986 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.985 with no explicit bump. run 35903379073. (task 1002620)
+  1.19.987 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.986 with no explicit bump. run 35906802480. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/lifecycle/cascade.js

@@ -126,15 +126,30 @@ const COPY_VISUAL_MODULES = Object.freeze([
   'art-pipeline', // generated visual assets
   'status-ui',    // the public status dashboard
   'ui-design',    // the design-system surfaces (ADR 0081)
+  'public-landing', // the apex and the project hub (projects.html) — the owner-facing pages
 ]);
 
+// A path that IS a rendered surface: a page, sheet, script or image under a
+// module's public/ dir. Explicit for the same reason as the list above — a
+// backend file in a UI module (routes/, db.js, module.json) is not visual work,
+// and neither is a kit states file (.json).
+const UI_SURFACE_PATH = /^modules\/[^/]+\/public\/.+\.(html?|css|m?js|svg|png|jpe?g|webp|gif|avif|ico|woff2?|ttf|otf|mp4|webm)$/i;
+function isUiSurfacePath(p) { return typeof p === 'string' && UI_SURFACE_PATH.test(p); }
+
 // Does this shipped task's work put copy or visuals in front of a person? Pure
 // and total — the runner treats a throw as "no match", but this must not throw.
-function hasCopyOrVisualWork(task) {
+//
+// `changedFiles` is what the work actually CHANGED (task 1004201). The label
+// alone missed most UI work: of 19 recent ships that changed page files, 14 had
+// module_key null — the goal forest (task 1003480) shipped its overflowing
+// titles with no visual lens and no review. Owner decision 2026-09-23: every UI
+// change gets a visual review, and this is the predicate that files it.
+function hasCopyOrVisualWork(task, changedFiles) {
   if (!task) return false;
   if (task.source === 'copy-proposal') return true;        // a copy change that landed via the copy desk (ADR 0233)
   if (task.discipline === 'artist') return true;           // work an artist did is, by definition, on their surface
   if (task.module_key && COPY_VISUAL_MODULES.includes(task.module_key)) return true;
+  if (Array.isArray(changedFiles) && changedFiles.some(isUiSurfacePath)) return true;
   return false;
 }
 
@@ -235,8 +250,12 @@ const CASCADES = Object.freeze([
     // is read from ctx, never from branding, so the predicate stays pure; an
     // absent ctx (a caller that resolved no policy) files, because the gate's
     // default is 'strict' and silence must not be read as an opt-out.
+    //
+    // A changed-files list that hit GitHub's read cap FILES (task 1004201): a UI
+    // file may sit past the cap, and a padded PR must not skip its review.
     when: (t, ctx) => (ctx || {}).artistGate !== 'off'
-      && t.source !== CASCADE_SOURCE && hasCopyOrVisualWork(t),
+      && t.source !== CASCADE_SOURCE
+      && (hasCopyOrVisualWork(t, (ctx || {}).changedFiles) || (ctx || {}).changedFilesTruncated === true),
     title: (t) => `Artist review: the copy and visuals that shipped in task ${t.id}`,
     body: artistReviewBody,
   }),
@@ -539,6 +558,17 @@ async function runCascadesForShip(shipped, deps = {}) {
       try { ctx.artistGate = deps.artistGateMode(); }
       catch (e) { report.errors.push(`cascade: artistGateMode() threw (${e && e.message}) — policy unread`); }
     }
+    // WHAT THIS SHIP CHANGED (task 1004201), from the server's own view of the
+    // merged pull request, so the artist review keys on the work rather than a
+    // module_key label. A resolver that throws is reported and leaves the key
+    // unset: the label-based match still stands and the ship costs nothing.
+    if (typeof deps.changedFiles === 'function') {
+      try {
+        const changed = await deps.changedFiles(task);
+        ctx.changedFiles = (changed && changed.paths) || [];
+        ctx.changedFilesTruncated = Boolean(changed && changed.truncated);
+      } catch (e) { report.errors.push(`cascade: changedFiles() threw (${e && e.message}) — matched on labels only`); }
+    }
     // WHAT THIS SHIP DELETED (task 1004090 / BV2.R15, ADR 0313). Resolved here
     // rather than in the rule for the reason the rule's own comment gives: a
     // `when` is pure and synchronous, and this is a network read.

package/modules/lifecycle/routes/lifecycle.js

@@ -30,6 +30,7 @@ const db = require('../db');
 const cascade = require('../cascade');
 const removalDerivation = require('../removal-derivation');
 const removalTargets = require('../removal-targets');
+const shipFiles = require('../ship-files');
 
 // task 1003549 — the cross-role cascade listener. `task.shipped` already exists
 // as a kernel event (emitted post-commit by the publish reconciler and the ship
@@ -70,49 +71,60 @@ function registerSeams() {
     log: api.logger ? api.logger('lifecycle') : null,
   }));
 
-  _cascadeListenerOff = api.on('task.shipped', (shipped) => cascade.runCascadesForShip(shipped, {
-    getTask: (id) => db.getTask(id),
-    findTaskBySourceRef: (ref) => db.findTaskBySourceRef(ref),
-    createTask: (spec) => db.createTask(spec),
-    // The project's artist gate (ADR 0241, task 1003575). Resolved through the
-    // doorway's one reader rather than from branding().project, so the level that
-    // decides whether a review is FILED and the level that decides whether one
-    // HOLDS a deploy can never be read differently. At 'off' the artist-review
-    // rule files nothing.
-    artistGateMode: () => api.artistGate.artistGateMode(),
-    // WHAT THIS SHIP DELETED (task 1004090 / BV2.R15, ADR 0313). The derivation
-    // asks GitHub what the pull request actually changed and blames the deleted
-    // paths back through `claims.published_head_sha` — the SERVER's own view of
-    // the merge, never the client-supplied `diff_stats` the net-negative bonus
-    // reads, which is target-less and already known-forgeable.
-    //
-    // Resolving the PR number here rather than inside the derivation keeps that
-    // file free of the task->PR question, which github-push already answers.
-    // A task with no findable PR derives nothing, which files nothing.
-    //
-    // Every failure is swallowed into an empty result: this runs on the ship
-    // path, and ADR 0313 is explicit that landing work matters more than dimming
-    // a star on time.
-    //
-    // The resolver itself is `removalCandidatesForTask`, NOT a closure here. It
-    // was a closure, and it read the wrong field off findTaskPullRequest
-    // (`number` for `pr_number`), which made the whole rule dead in production
-    // while every test passed — because every test injected this dep. A closure
-    // inside a listener registration is not reachable from a test; a named
-    // function is, and this line is now too small to hide a bug of its own.
-    removalCandidates: (task) => removalDerivation.removalCandidatesForTask(task, {
-      shippedTasksByPublishedSha: (shas) => db.shippedTasksByPublishedSha(shas),
-    }),
-    // WHOSE WORK IT WAS, stored (task 1004099 / BV2.R16 brightness). The
-    // derivation above already computed the attribution and the proposal body
-    // renders it as prose; this persists the same objects so brightness can
-    // read them structured. Passed as the NAMED function rather than wrapped in
-    // a closure, for the reason the note above gives: a closure here is not
-    // reachable from a test, and that is how the `number`/`pr_number` bug lived
-    // in production with a green suite.
-    recordRemovalTargets: removalTargets.recordRemovalTargets,
-    log: api.logger ? api.logger('lifecycle') : null,
-  }));
+  _cascadeListenerOff = api.on('task.shipped', (shipped) => {
+    // ONE pair of GitHub reads (find the PR, list its files) per ship, shared by
+    // the two resolvers below that both need them (task 1004201).
+    const pr = shipFiles.sharedPrReads();
+    return cascade.runCascadesForShip(shipped, {
+      getTask: (id) => db.getTask(id),
+      findTaskBySourceRef: (ref) => db.findTaskBySourceRef(ref),
+      createTask: (spec) => db.createTask(spec),
+      // The project's artist gate (ADR 0241, task 1003575). Resolved through the
+      // doorway's one reader rather than from branding().project, so the level that
+      // decides whether a review is FILED and the level that decides whether one
+      // HOLDS a deploy can never be read differently. At 'off' the artist-review
+      // rule files nothing.
+      artistGateMode: () => api.artistGate.artistGateMode(),
+      // WHAT THIS SHIP CHANGED (task 1004201): the merged PR's paths, so a UI
+      // change files its artist review whatever its module_key label says. The
+      // NAMED function, not a closure, for the reason removalCandidates gives below;
+      // the arrow only hands it this ship's shared reads.
+      changedFiles: (task) => shipFiles.changedFilesForTask(task, pr),
+      // WHAT THIS SHIP DELETED (task 1004090 / BV2.R15, ADR 0313). The derivation
+      // asks GitHub what the pull request actually changed and blames the deleted
+      // paths back through `claims.published_head_sha` — the SERVER's own view of
+      // the merge, never the client-supplied `diff_stats` the net-negative bonus
+      // reads, which is target-less and already known-forgeable.
+      //
+      // Resolving the PR number here rather than inside the derivation keeps that
+      // file free of the task->PR question, which github-push already answers.
+      // A task with no findable PR derives nothing, which files nothing.
+      //
+      // Every failure is swallowed into an empty result: this runs on the ship
+      // path, and ADR 0313 is explicit that landing work matters more than dimming
+      // a star on time.
+      //
+      // The resolver itself is `removalCandidatesForTask`, NOT a closure here. It
+      // was a closure, and it read the wrong field off findTaskPullRequest
+      // (`number` for `pr_number`), which made the whole rule dead in production
+      // while every test passed — because every test injected this dep. A closure
+      // inside a listener registration is not reachable from a test; a named
+      // function is, and this line is now too small to hide a bug of its own.
+      removalCandidates: (task) => removalDerivation.removalCandidatesForTask(task, {
+        ...pr,
+        shippedTasksByPublishedSha: (shas) => db.shippedTasksByPublishedSha(shas),
+      }),
+      // WHOSE WORK IT WAS, stored (task 1004099 / BV2.R16 brightness). The
+      // derivation above already computed the attribution and the proposal body
+      // renders it as prose; this persists the same objects so brightness can
+      // read them structured. Passed as the NAMED function rather than wrapped in
+      // a closure, for the reason the note above gives: a closure here is not
+      // reachable from a test, and that is how the `number`/`pr_number` bug lived
+      // in production with a green suite.
+      recordRemovalTargets: removalTargets.recordRemovalTargets,
+      log: api.logger ? api.logger('lifecycle') : null,
+    });
+  });
 }
 
 module.exports = function buildLifecycleRouter() {

package/modules/lifecycle/ship-files.js

@@ -0,0 +1,57 @@
+'use strict';
+
+// modules/lifecycle/ship-files.js — the paths a shipped task's pull request
+// changed, from the SERVER's own view of the merge (task 1004201).
+//
+// The artist-review cascade asks "did this ship change a rendered surface?" by
+// the files, because the module_key label it used to key on is usually null.
+// The answer comes from GitHub — the same two reads removal-derivation.js makes,
+// SHARED with it per ship through sharedPrReads — never from a list the building
+// box supplied. A task with no findable pull request changed nothing this can
+// see, and answers no paths.
+
+const githubPush = require('./github-push');
+
+// github-push.getPullRequestFiles reads at most 3 pages of 100 and says nothing
+// when it stops there, so a list this long may have been cut off. Pinned against
+// that file by test.
+const PR_FILES_CAP = 300;
+
+// sharedPrReads — the two GitHub reads behind a ship's pull request, memoised for
+// ONE ship event, so this file and removal-derivation.js ask GitHub once between
+// them. Create one per event; never share it across ships.
+function sharedPrReads(deps = {}) {
+  const find = deps.findTaskPullRequest || ((args) => githubPush.findTaskPullRequest(args));
+  const list = deps.getPullRequestFiles || ((args) => githubPush.getPullRequestFiles(args));
+  const memo = new Map();
+  const once = (key, read) => {
+    if (!memo.has(key)) memo.set(key, read());
+    return memo.get(key);
+  };
+  return {
+    findTaskPullRequest: (args) => once(`pr:${args && args.taskId}`, () => find(args)),
+    getPullRequestFiles: (args) => once(`files:${args && args.number}`, () => list(args)),
+  };
+}
+
+// changedFilesForTask — { paths, truncated } for the task's pull request.
+// `truncated` means the list hit the read cap, so a UI file may sit past it: the
+// review rule files anyway rather than let a padded PR skip it. Throws on a failed
+// read; the cascade runner reports that and falls back to the label match.
+async function changedFilesForTask(task, deps = {}) {
+  const findPr = deps.findTaskPullRequest || ((args) => githubPush.findTaskPullRequest(args));
+  const getFiles = deps.getPullRequestFiles || ((args) => githubPush.getPullRequestFiles(args));
+  const pr = await findPr({ taskId: task && task.id });
+  // `pr_number`, NOT `pr.number` — findTaskPullRequest returns { branch, pr_number,
+  // pr_state, merged }, and reading the wrong field is silent (removal-derivation.js
+  // shipped dead in production over exactly this).
+  if (!pr || pr.pr_number == null) return { paths: [], truncated: false };
+  const files = await getFiles({ number: Number(pr.pr_number) });
+  const rows = Array.isArray(files) ? files : [];
+  return {
+    paths: rows.map((f) => f && f.path).filter((p) => typeof p === 'string' && p),
+    truncated: rows.length >= PR_FILES_CAP,
+  };
+}
+
+module.exports = { PR_FILES_CAP, sharedPrReads, changedFilesForTask };

package/modules/lifecycle/tests/cascade.mjs

@@ -329,5 +329,152 @@ await test("runCascadesForShip honours 'off' end to end — nothing is created,
   assert.deepEqual(report.errors, [], 'a project that switched the gate off has no problem to report');
 });
 
+// --- the review keys on the FILES a ship changed, not its label (task 1004201) --
+
+await test('a page file changed under modules/*/public/ is visual work whatever the label says', () => {
+  const H = cascade.hasCopyOrVisualWork;
+  const unlabelled = shippedCopy({ module_key: null, discipline: 'engineer' });
+  assert.equal(H(unlabelled), false, 'the label alone says no — the gap task 1003480 fell through');
+  for (const p of [
+    'modules/hall-ui/public/goal-forest-lib.js',
+    'modules/public-landing/public/projects.html',
+    'modules/status-ui/public/status.css',
+    'modules/public-landing/public/assets/world/planet.webp',
+  ]) assert.equal(H(unlabelled, ['README.md', p]), true, p);
+  assert.equal(H(shippedCopy({ module_key: 'public-landing' })), true, 'public-landing joined the label list');
+});
+
+await test('a backend file in a UI module is NOT visual work — page files only', () => {
+  const H = cascade.hasCopyOrVisualWork;
+  const unlabelled = shippedCopy({ module_key: null, discipline: 'engineer' });
+  assert.equal(H(unlabelled, [
+    'modules/hall-ui/module.json',
+    'modules/public-landing/routes/hub.js',
+    'modules/hall-ui/public/goals.states.json',
+    'modules/lifecycle/cascade.js',
+    'public-docs/index.html',
+  ]), false);
+  assert.equal(H(unlabelled, []), false);
+  assert.equal(H(unlabelled, null), false);
+});
+
+await test('the ship runner resolves the changed files ONCE and the artist review files on them', async () => {
+  const created = [];
+  let asked = 0;
+  const deps = {
+    getTask: async () => shippedCopy({ module_key: null, discipline: 'engineer' }),
+    findTaskBySourceRef: async () => null,
+    createTask: async (spec) => { created.push(spec); return { id: String(9300 + created.length) }; },
+    changedFiles: async () => { asked++; return { paths: ['modules/hall-ui/public/goal-forest-render.js'], truncated: false }; },
+  };
+  const report = await cascade.runCascadesForShip({ id: '7001' }, deps);
+  assert.equal(asked, 1);
+  assert.equal(created.filter((s) => s.discipline === 'artist').length, 1, 'the unlabelled UI ship gets its review');
+  assert.deepEqual(report.errors, []);
+});
+
+await test('a changed-files list cut off at the read cap FILES the review — a padded PR cannot skip it', async () => {
+  const run = async (changed) => {
+    const created = [];
+    await cascade.runCascadesForShip({ id: '7001' }, {
+      getTask: async () => shippedCopy({ module_key: null, discipline: 'engineer' }),
+      findTaskBySourceRef: async () => null,
+      createTask: async (spec) => { created.push(spec); return { id: '9500' }; },
+      changedFiles: async () => changed,
+    });
+    return created.filter((s) => s.discipline === 'artist').length;
+  };
+  const padding = Array.from({ length: 300 }, (_, i) => `docs/pad-${i}.md`);
+  assert.equal(await run({ paths: padding, truncated: true }), 1);
+  assert.equal(await run({ paths: padding, truncated: false }), 0, 'the same list, complete, is not UI work');
+});
+
+await test('a filed review is one the deploy gate HOLDS on — the rule and the gate agree on its identity', async () => {
+  const gate = require_(path.join(HERE, '..', '..', '..', 'src', 'bongos', 'artist-gate.js'));
+  const created = [];
+  await cascade.runCascadesForShip({ id: '7001' }, {
+    getTask: async () => shippedCopy({ module_key: null, discipline: 'engineer' }),
+    findTaskBySourceRef: async () => null,
+    createTask: async (spec) => { created.push(spec); return { id: '9600' }; },
+    changedFiles: async () => ({ paths: ['modules/public-landing/public/projects.html'], truncated: false }),
+  });
+  const review = created.find((s) => s.discipline === 'artist');
+  assert.ok(review, 'the review was filed');
+  assert.equal(gate.isArtistReview({ source: review.source, source_ref: review.sourceRef }), true);
+});
+
+await test('a changed-files read that fails is REPORTED, never thrown — the label match still stands', async () => {
+  const run = async (task) => {
+    const created = [];
+    const report = await cascade.runCascadesForShip({ id: '7001' }, {
+      getTask: async () => task,
+      findTaskBySourceRef: async () => null,
+      createTask: async (spec) => { created.push(spec); return { id: '9400' }; },
+      changedFiles: async () => { throw new Error('github down'); },
+    });
+    return { created, report };
+  };
+  const unlabelled = await run(shippedCopy({ module_key: null, discipline: 'engineer' }));
+  assert.equal(unlabelled.created.length, 0);
+  assert.match(unlabelled.report.errors.join('\n'), /changedFiles\(\) threw \(github down\)/);
+  const labelled = await run(shippedCopy({ module_key: 'hall-ui' }));
+  assert.equal(labelled.created.filter((s) => s.discipline === 'artist').length, 1, 'an outage never costs a labelled review');
+});
+
+const shipFiles = require_(path.join(HERE, '..', 'ship-files.js'));
+
+await test('ship-files: reads the merged PR by pr_number and returns its paths', async () => {
+  const asked = [];
+  const changed = await shipFiles.changedFilesForTask({ id: '7001' }, {
+    findTaskPullRequest: async (a) => { asked.push(a); return { branch: 'task-7001', pr_number: 42, merged: true }; },
+    getPullRequestFiles: async ({ number }) => (number === 42
+      ? [{ path: 'modules/hall-ui/public/a.css', status: 'modified' }, { path: 'modules/hall-ui/public/b.js', status: 'removed', deleted: true }, null]
+      : []),
+  });
+  assert.deepEqual(asked, [{ taskId: '7001' }]);
+  assert.deepEqual(changed, { paths: ['modules/hall-ui/public/a.css', 'modules/hall-ui/public/b.js'], truncated: false });
+  const noPr = await shipFiles.changedFilesForTask({ id: '7001' }, {
+    findTaskPullRequest: async () => ({ number: 42 }), // the WRONG field — must not be read as a PR
+    getPullRequestFiles: async () => { throw new Error('must not be called'); },
+  });
+  assert.deepEqual(noPr, { paths: [], truncated: false });
+});
+
+await test('ship-files: a list at the read cap says it may be cut off, and the cap is github-push\'s own', async () => {
+  const full = await shipFiles.changedFilesForTask({ id: '1' }, {
+    findTaskPullRequest: async () => ({ pr_number: 7 }),
+    getPullRequestFiles: async () => Array.from({ length: shipFiles.PR_FILES_CAP }, (_, i) => ({ path: `docs/${i}.md` })),
+  });
+  assert.equal(full.truncated, true);
+  const src = require_('fs').readFileSync(path.join(HERE, '..', 'github-push.js'), 'utf8');
+  const body = src.slice(src.indexOf('async function getPullRequestFiles'));
+  const pages = Number((body.match(/page <= (\d+)/) || [])[1]);
+  const perPage = Number((body.match(/per_page=(\d+)/) || [])[1]);
+  assert.equal(pages * perPage, shipFiles.PR_FILES_CAP, 'if getPullRequestFiles reads more, the cap must follow');
+});
+
+await test('ship-files: one ship asks GitHub ONCE between the two resolvers that need the PR', async () => {
+  let finds = 0;
+  let lists = 0;
+  const pr = shipFiles.sharedPrReads({
+    findTaskPullRequest: async () => { finds++; return { pr_number: 9 }; },
+    getPullRequestFiles: async () => { lists++; return [{ path: 'modules/hall-ui/public/x.css' }]; },
+  });
+  await shipFiles.changedFilesForTask({ id: '5' }, pr);
+  await pr.findTaskPullRequest({ taskId: '5' });
+  await pr.getPullRequestFiles({ number: 9 });
+  assert.equal(finds, 1);
+  assert.equal(lists, 1);
+});
+
+await test('the ship listener wires the shared reads into BOTH resolvers', () => {
+  const fs = require_('fs');
+  const src = fs.readFileSync(path.join(HERE, '..', 'routes', 'lifecycle.js'), 'utf8');
+  assert.match(src, /require\('\.\.\/ship-files'\)/);
+  assert.match(src, /const pr = shipFiles\.sharedPrReads\(\);/, 'made per ship event, inside the listener');
+  assert.match(src, /changedFiles:\s*\(task\)\s*=>\s*shipFiles\.changedFilesForTask\(task, pr\)/);
+  assert.match(src, /removalDerivation\.removalCandidatesForTask\(task, \{\s*\.\.\.pr,/);
+});
+
 console.log(`\n${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.986",
+  "version": "1.19.987",
   "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/ship-grade.js

@@ -296,13 +296,13 @@ async function runSubagentGrader({ task, valueSummary, baseline, changedFiles: p
     // task 1003977: the advisory Reader rides along on copy-bearing diffs only.
     // Where the predicate says no, `panel` is byte-identical to DEFAULT_PANEL
     // and the ship costs exactly what it costs today.
-    const copyBearing = hasCopyOrVisualWork(task);
+    const copyBearing = hasCopyOrVisualWork(task, changedFiles);
     const panel = grader.WORKERS.panelFor({ copyBearing });
     console.log(`  subagent grader ${grader.VERSION}: panel of ${panel.length} workers (${panel.join(', ')}), model=${grader.selectGraderModel({ builderModel })} (builder ${builderModel || `${grader.ASSUMED_BUILDER_MODEL} assumed`}), changed_files=${changedFiles.length}, diff_chars=${diff.length}, per-worker timeout=${GRADER_TIMEOUT_MS}ms`);
     console.log(`  gate: every GATING worker must return verdict='pass'; 'concerns' → manual-confirm fall-through; 'fail' blocks`);
     console.log(copyBearing
       ? `  copy lens: ON — this task is copy-bearing, so the advisory 'reader' reads the changed strings against docs/voice.md. It is NON-GATING: nothing it reports, and no error or timeout it hits, can stop this ship.`
-      : `  copy lens: off — not a copy-bearing task (no copy-proposal source, not artist-discipline, module not in COPY_VISUAL_MODULES), so the panel is the usual four.`);
+      : `  copy lens: off — not a copy-bearing task (no copy-proposal source, not artist-discipline, module not in COPY_VISUAL_MODULES, no page file under modules/*/public/ changed), so the panel is the usual four.`);
     if (priorRound) {
       console.log(`  delta re-grade (task 1002662): prior round's findings + builder response ride along, fenced; answered findings can only re-veto with NEW evidence`);
     }

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

@@ -242,6 +242,13 @@ test('the cascade and the copy lens cover the SAME set by construction', () => {
   const shipSrc = fs.readFileSync(path.join(ROOT, 'scripts', 'gds', 'ship-grade.js'), 'utf8');
   assert.match(cascadeSrc, /hasCopyOrVisualWork/);
   assert.match(shipSrc, /hasCopyOrVisualWork/);
+  // Task 1004201: BOTH consumers hand the predicate the files the work changed,
+  // so an unlabelled UI ship gets the lens at grade time AND the review on ship.
+  assert.match(shipSrc, /hasCopyOrVisualWork\(task, changedFiles\)/, 'the grader passes its own diff');
+  assert.match(cascadeSrc, /hasCopyOrVisualWork\(t, \(ctx \|\| \{\}\)\.changedFiles\)/, 'the cascade passes the merged PR');
+  const unlabelled = { module_key: null, discipline: 'engineer' };
+  assert.equal(hasCopyOrVisualWork(unlabelled, ['modules/hall-ui/public/goal-forest-lib.js']), true);
+  assert.equal(hasCopyOrVisualWork(unlabelled, ['modules/hall-ui/module.json', 'scripts/gds/claim.js']), false);
 });
 
 // ---- 8. COST ---------------------------------------------------------------