@bongos/core 1.19.986 → 1.19.988

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.988",
+  "core_contract": "1.19.988",
+  "source_commit": "fe4b08f918073241c24208ac22bb4e2a505a00f4",
   "source_ref": "HEAD",
-  "built_at": "2026-09-23T18:36:30.871Z",
+  "built_at": "2026-09-23T19:26:45.671Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 518,
     "agent_docs_stubbed": 26,
-    "functional_verbatim": 2390,
+    "functional_verbatim": 2394,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2934,
-  "tree_sha256": "8b898c04436c76259878da047c512541c0d0a03e9de13419b31e0a0d41ffa182",
+  "file_count": 2938,
+  "tree_sha256": "bc9a86c3157f1080179c3d82293d7cfad4a40cc7b5895538465816e8f1238416",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -127,7 +127,7 @@
     {
       "path": ".claude/skills/design/SKILL.md",
       "mode": "0000644",
-      "sha256": "1ead0250cf028382a55dfd110faa2f787ea8fe14a7927b2272f6891bde30fc2e"
+      "sha256": "2ffaa5f9c6b6ff5b9a3a4730b4d172cdb905f1ed5efa879d3b14dca5ae60aeeb"
     },
     {
       "path": ".claude/skills/feedback/SKILL.md",
@@ -2712,7 +2712,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "e779420483a2e19ea834a5995d1960296dad434fa158c1e46db3ee4e12b6569e"
+      "sha256": "22b37ede3331f4be0569380c58ab10e90d79aaaf3dd52191d6fc49bab095b2b2"
     },
     {
       "path": "docs/modules-contract.md",
@@ -2787,12 +2787,12 @@
     {
       "path": "docs/packs/artist.md",
       "mode": "0000644",
-      "sha256": "f5754df3bd633f317b9b221640b519ecdc1fdbb68d9ca322329cc92b365c9524"
+      "sha256": "ef94247b390fe32676c910545c35a7cfd39bb2ed87680174d7bd590eb1fbe2af"
     },
     {
       "path": "docs/packs/engineer.md",
       "mode": "0000644",
-      "sha256": "b7cb50de31efaa49ce41a475a916abc652454a2eacca5aaaaf8ee8cba46067c6"
+      "sha256": "76c058f9fa63846caf132e2b4703ae7913572d59dbcb47f3e8b565f21262fea8"
     },
     {
       "path": "docs/packs/ideator.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": "b852a0142a8be848b6e231b88b0c7b5e2f86baa0b88dcb44e42c1f1e65afb9ea"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "80d5c9a1504e44bfccb0e3bfb0fd38e99eed359118d9d48f12bf9cab895f0533"
+      "sha256": "46df90fa4ee1a722331e5bd7a6531f82e4245a545412e70ef73825bce85840e7"
     },
     {
       "path": "public-docs/index.html",
@@ -8497,7 +8502,7 @@
     {
       "path": "scripts/gds/claim.js",
       "mode": "0000644",
-      "sha256": "942581a081da9134cb7038c61b646ddba6e25f2de15411fe59378a477ac05637"
+      "sha256": "c9a7f39cf1f03e985466005a1857f570b4b3d449b0cbd8b3dfd0f7a7524a7c31"
     },
     {
       "path": "scripts/gds/classify-discipline.js",
@@ -9254,6 +9259,11 @@
       "mode": "0000644",
       "sha256": "084fa5c4da1e755fa0edde5ec770e5151a9f66a247bca222bc7a2366ccf61748"
     },
+    {
+      "path": "scripts/gds/review-sheet.js",
+      "mode": "0000644",
+      "sha256": "a0234b79890f9eae0fdc9d1910b723d61d21ca6b2888092b45084fb13c0c63c6"
+    },
     {
       "path": "scripts/gds/role-pack-guard.js",
       "mode": "0000644",
@@ -9532,7 +9542,7 @@
     {
       "path": "scripts/gds/ship-grade.js",
       "mode": "0000644",
-      "sha256": "40c6a9f6aa6a75cdf8a5e41bfa8318766636cba64e47aee870c26a719676713d"
+      "sha256": "eb0740f3cdc3dc91038320dd9044dc81c05e31212059d772d5c8bf6e9f44b474"
     },
     {
       "path": "scripts/gds/ship-honesty.js",
@@ -9754,6 +9764,11 @@
       "mode": "0000644",
       "sha256": "be4fec619d5a0c76ba05bcc75042c1497f70da21b54a3d646884e2228f90b2ba"
     },
+    {
+      "path": "scripts/gds/visual-review-nudge.js",
+      "mode": "0000644",
+      "sha256": "a86b2cd427c9b52090d906b0b5febb9d8098fae1589e01828e4d7698d38db599"
+    },
     {
       "path": "scripts/gds/worktree-claim-guard.js",
       "mode": "0000644",
@@ -10187,7 +10202,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "17399ab568a9343c5c5cead3e1e467af941ec891ee117b424ad0e2ed10151731"
+      "sha256": "2a9b6a4c34d0321b9684a3054d93a5224359fcdc89d81df9ec01bee4334c25c7"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -12037,7 +12052,7 @@
     {
       "path": "tests/grader_reader_lens.mjs",
       "mode": "0000644",
-      "sha256": "93e24012252c08798e3017ce9a7130ce9ece4e5e07456892b3632ab12f44ad47"
+      "sha256": "cacfafb2e8408bfcc2137ab1bf11bed21cf95c720aa0a7bc5cdbf0386f4833c8"
     },
     {
       "path": "tests/grader_regrade_delta.mjs",
@@ -14609,6 +14624,11 @@
       "mode": "0000644",
       "sha256": "8a8df7e2a025029ffe7e18b7c7b18c6bd92a256822609931f0cd88628e446041"
     },
+    {
+      "path": "tests/visual_review.mjs",
+      "mode": "0000644",
+      "sha256": "6c583bd0cb3c2611044e5adad4c17a57d5aed89ba5daf921c355903df239a2ab"
+    },
     {
       "path": "tests/wandering_prefs.mjs",
       "mode": "0000644",

package/.claude/skills/design/SKILL.md

@@ -49,7 +49,8 @@ Generated code uses the `--dt-*` variables; adapters write only `src/ui/<surface
 - `node scripts/gds/validate-design.js --strict` after touching adapters, tokens or `design-sources.json` (fitness runs it on every PR).
 - **New interactive code gets a pin in the page's own test file in the same diff** — the grader's Quality worker fails a chrome change that arrives with no test. Contrast pairs are measured in CI, not eyeballed.
 - The task's DONE WHEN is read literally — "both pages" means both pages. Deliberate deviations from a mock stay minor if the ship notes say why.
-- `/builder-ship` with real `--notes` (what changed, which screens you looked at, in which modes) and a plain-language `--summary`.
+- **The person you're working with OKs it before it ships** — the project default for every builder (owner, 2026-09-23). Open the before/after shots in their browser with `node scripts/gds/review-sheet.js --title … --shot "<caption>=<png>"` (a terminal shows no images, so a screenshot you only read yourself never reached them), and wait. Autonomous: no one to ask, so list the shots in the notes and ship; the change files a visual review that holds the deploy (ADR 0241), never the ship.
+- `/builder-ship` with real `--notes` (what changed, which screens you looked at, in which modes, and who OKed them) and a plain-language `--summary`.
 
 ## Round-tripping with a design tool
 

package/docs/module-api-changelog.md

@@ -2446,5 +2446,9 @@ 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)
+  1.19.988 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.987 with no explicit bump. run 35909292753. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/docs/packs/artist.md

@@ -15,6 +15,7 @@ In every other craft Claude narrates — diffs, logs, paragraphs about what it i
 - **End every step with something visual.** After a generation, display the image. After a copy change, show the rendered text in place, not a diff. After a check, show the scorecard, not a prose summary. They should see the result before they read a word.
 - **Collapse the plumbing to one-liners.** Budget checks, config edits, retry tiers, atlas rebuilds — do them, report them as a single line or a number. "Generated, scored 0.91, on-palette, staged ✓" beats three paragraphs.
 - **Verification is looking, not reading.** Surface the rendered surface and the sandbox preview, not console logs. Logs are for when something breaks, not for routine success.
+- **Nothing that changes a page ships until they have seen it** (the project default, owner 2026-09-23). Show the before and after in both modes at desktop and phone width, opened in their browser with `node scripts/gds/review-sheet.js` (a terminal shows no images), and ship on their OK.
 
 ## The second rule: as little interpretation as possible
 

package/docs/packs/engineer.md

@@ -20,7 +20,8 @@ Engineering is the project's **default loop**, so this pack introduces no new dy
 
 4. **Verify it — never report done on faith.** The step engineers most often skip.
    - Run the smoke tests yourself while iterating (`/builder-ship` runs them too, but later is not the same as sooner).
-   - If the change is observable in the running app, use the preview/verification workflow (preview → reload → console + page check → screenshot proof) rather than asking a human to look. Verify, then share the proof.
+   - If the change is observable in the running app, use the preview/verification workflow (preview → reload → console + page check → screenshot proof) yourself first. Verify, then share the proof.
+   - **A change to a page people see is reviewed by your human before it ships — the project default for every builder (owner, 2026-09-23).** Render it before and after, in both modes, at desktop and phone width; open the shots for them with `node scripts/gds/review-sheet.js` (a terminal shows no images — this opens one page in their browser); wait for their OK, then ship. With nobody to ask, list the shots in the ship notes and ship: the change also files a visual review on the board that holds the deploy (ADR 0241), never the ship.
    - If it is not browser-observable (a different runtime, types, tooling), say so and verify the way that *does* exercise it.
    - `/ship-check` runs every freshness and fitness gate `ship.js` will run, and prints the healing command for each stale generated file.
 

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.988",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.986",
+      "version": "1.19.988",
       "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.988",
   "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/claim.js

@@ -36,6 +36,7 @@ const { plainCardLines } = require('./plain-cards');
 // and the detector. A lifecycle CLI may require the lifecycle module directly
 // (the documented exception in modules/lifecycle/CLAUDE.md).
 const { splitDeadDeps, deadDepHint } = require('../../modules/lifecycle/dead-deps.js');
+const { visualReviewNudge } = require('./visual-review-nudge');
 
 // Fetch up to 3 learnings relevant to the task being claimed. touches[] cleanup
 // [3/8] (task 878): key off the task's discipline + title (always present) rather
@@ -728,6 +729,12 @@ async function main() {
     // playbook) into its skill. Printed right after the description so it's the
     // last thing the builder reads before deciding how to work — task 1267.
     printDisciplineMode(task);
+    // task 1004202: a task that changes a page is told to use /design and get its
+    // human's OK on the before/after. A nudge, never a gate (ADR 0162).
+    try {
+      const nudge = visualReviewNudge(task);
+      if (nudge) console.log(`\n${nudge.join('\n')}`);
+    } catch (_) { /* never let a hint break a successful claim */ }
     if (worktree) console.log(`\nWorktree: ${worktree}`);
     // Claim-time knowledge (#956 / V4.R18, criterion sessions-start-knowing):
     // learnings first (curated, short), then the top recall sources for this task

package/scripts/gds/review-sheet.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+'use strict';
+
+// scripts/gds/review-sheet.js — open before/after screenshots for a person to
+// review, as ONE page in their own browser (task 1004202).
+//
+// WHY. Every change to a rendered surface is reviewed by the session's human
+// before it ships — the project default since the owner's 2026-09-23 decision.
+// A terminal shows no images: a screenshot an agent "sends" or reads into its
+// own context never reaches a CLI user's eyes. So the review is a local HTML page
+// of captioned shots, opened with the OS's own opener. Nothing is uploaded.
+//
+// Usage:
+//   node scripts/gds/review-sheet.js --title "Task 1004200 — graph titles" \
+//     --shot "Before — 1280, light=C:/shots/before.png" \
+//     --shot "After — 1280, light=C:/shots/after.png" \
+//     [--note "One line on what changed."] [--out <dir>] [--no-open]
+//
+// Prints the page's path. Each --shot is "<caption>=<image path>", in order.
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { pathToFileURL } = require('node:url');
+const { spawn } = require('node:child_process');
+
+function escapeHtml(s) {
+  return String(s == null ? '' : s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+}
+
+// parseArgs — the flags above; `shots` keep their order. A --shot with no "="
+// is an error, not a guess: the caption and the path cannot be told apart.
+function parseArgs(argv) {
+  const out = { title: 'Visual review', note: '', shots: [], outDir: null, open: true, errors: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--no-open') { out.open = false; continue; }
+    const v = argv[i + 1];
+    if (a === '--title') { out.title = v; i++; }
+    else if (a === '--note') { out.note = v; i++; }
+    else if (a === '--out') { out.outDir = v; i++; }
+    else if (a === '--shot') {
+      i++;
+      const at = String(v || '').lastIndexOf('=');
+      if (at < 1) out.errors.push(`--shot needs "<caption>=<image path>", got: ${v}`);
+      else out.shots.push({ caption: v.slice(0, at).trim(), file: v.slice(at + 1).trim() });
+    } else out.errors.push(`unknown argument: ${a}`);
+  }
+  if (!out.shots.length) out.errors.push('at least one --shot is required');
+  return out;
+}
+
+// buildReviewPage — the page itself. Images are absolute file:// URLs, so the
+// page works wherever it is written and nothing is copied.
+function buildReviewPage({ title, note, shots }) {
+  const figures = shots.map((s) => `<figure><figcaption>${escapeHtml(s.caption)}</figcaption>`
+    + `<img src="${escapeHtml(pathToFileURL(path.resolve(s.file)).href)}" alt="${escapeHtml(s.caption)}"></figure>`).join('\n');
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>${escapeHtml(title)}</title>
+<style>
+  body { margin: 0; padding: 24px; font: 15px/1.5 system-ui, sans-serif; background: #f4f4f5; color: #17181a; }
+  h1 { font-size: 20px; margin: 0 0 6px; }
+  p { margin: 0 0 20px; max-width: 70ch; }
+  figure { margin: 0 0 28px; }
+  figcaption { font-weight: 600; margin-bottom: 6px; }
+  img { display: block; max-width: 100%; border: 1px solid #d4d4d8; border-radius: 8px; }
+</style>
+</head>
+<body>
+<h1>${escapeHtml(title)}</h1>
+${note ? `<p>${escapeHtml(note)}</p>\n` : ''}${figures}
+</body>
+</html>
+`;
+}
+
+function openInBrowser(file) {
+  // `start`'s first quoted argument is a window title, hence the empty "".
+  const [cmd, args] = process.platform === 'win32' ? ['cmd', ['/c', 'start', '""', `"${file}"`]]
+    : process.platform === 'darwin' ? ['open', [file]] : ['xdg-open', [file]];
+  const child = spawn(cmd, args, { detached: true, stdio: 'ignore', windowsVerbatimArguments: process.platform === 'win32' });
+  child.on('error', () => console.error(`Could not open a browser — open this file yourself: ${file}`));
+  child.unref();
+}
+
+function main(argv) {
+  const opts = parseArgs(argv);
+  const missing = opts.shots.filter((s) => !fs.existsSync(s.file)).map((s) => `no such image: ${s.file}`);
+  const errors = [...opts.errors, ...missing];
+  if (errors.length) {
+    console.error(errors.join('\n'));
+    return 1;
+  }
+  const dir = opts.outDir || fs.mkdtempSync(path.join(os.tmpdir(), 'bongos-review-'));
+  fs.mkdirSync(dir, { recursive: true });
+  const file = path.join(dir, 'index.html');
+  fs.writeFileSync(file, buildReviewPage(opts));
+  console.log(file);
+  if (opts.open) openInBrowser(file);
+  return 0;
+}
+
+if (require.main === module) process.exitCode = main(process.argv.slice(2));
+
+module.exports = { parseArgs, buildReviewPage };

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/scripts/gds/visual-review-nudge.js

@@ -0,0 +1,37 @@
+'use strict';
+
+// scripts/gds/visual-review-nudge.js — the claim-time lines that tell a session
+// its task changes a page people see (task 1004202): use /design, check it in a
+// real browser, and get the human's OK on the before/after before shipping — the
+// project default for every builder since the owner's 2026-09-23 decision.
+//
+// A NUDGE, never a gate (ADR 0162). "Is this UI work" is the ONE predicate the
+// artist review and the grader's copy lens already use (lifecycle/cascade.js), so
+// the three cannot disagree. Nothing has changed yet at claim time, so it is fed
+// the paths the task NAMES: its touches[] and any modules/*/public/ path written
+// in its description.
+
+const { hasCopyOrVisualWork } = require('../../modules/lifecycle/cascade.js');
+
+const PUBLIC_PATH_IN_TEXT = /modules\/[\w.-]+\/public\/[^\s`'"()<>[\]{}|,;]+/g;
+
+// pathsNamedIn — touches[] plus every public/ path the description mentions,
+// with sentence punctuation stripped off the end ("…/goal-forest-lib.js." → .js).
+function pathsNamedIn(task) {
+  const touches = Array.isArray(task && task.touches) ? task.touches.filter((t) => typeof t === 'string') : [];
+  const named = (String((task && task.description) || '').match(PUBLIC_PATH_IN_TEXT) || [])
+    .map((p) => p.replace(/[.:]+$/, ''));
+  return [...touches, ...named];
+}
+
+// visualReviewNudge — the lines to print, or null when the task is not UI work.
+function visualReviewNudge(task) {
+  if (!hasCopyOrVisualWork(task, pathsNamedIn(task))) return null;
+  return [
+    '🎨 This task changes a page people see.',
+    '  Build it with /design, and check it in a real browser at desktop and phone width, light and dark.',
+    '  Before you ship: open the before/after for your human (node scripts/gds/review-sheet.js) and wait for their OK.',
+  ];
+}
+
+module.exports = { pathsNamedIn, visualReviewNudge };

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.988'; // 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 ---------------------------------------------------------------

package/tests/visual_review.mjs

@@ -0,0 +1,110 @@
+// tests/visual_review.mjs — the visual review as the project default for every
+// builder (task 1004202; owner decision 2026-09-23).
+//
+// Three parts, pinned together because each is useless without the others: the
+// review page a CLI user can actually SEE (review-sheet.js), the claim-time nudge
+// that tells a UI task to use it (visual-review-nudge.js + claim.js), and the
+// three playbooks every builder's session reads, which carry the rule itself.
+//
+// Run:  node tests/visual_review.mjs
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { makeRunner } from './helpers.mjs';
+import { parseArgs, buildReviewPage } from '../scripts/gds/review-sheet.js';
+import { pathsNamedIn, visualReviewNudge } from '../scripts/gds/visual-review-nudge.js';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const read = (rel) => fs.readFileSync(path.join(ROOT, rel), 'utf8');
+const { test, summary } = makeRunner();
+
+// ---- the review page ---------------------------------------------------------
+
+await test('parseArgs keeps the shots in order and splits caption from path at the LAST "="', () => {
+  const o = parseArgs(['--title', 'T', '--shot', 'Before — a=b=C:/x/one.png', '--shot', 'After=C:/x/two.png', '--no-open']);
+  assert.deepEqual(o.shots, [{ caption: 'Before — a=b', file: 'C:/x/one.png' }, { caption: 'After', file: 'C:/x/two.png' }]);
+  assert.equal(o.open, false);
+  assert.deepEqual(o.errors, []);
+});
+
+await test('parseArgs refuses a shot it cannot split, and a page with no shots', () => {
+  assert.match(parseArgs(['--shot', 'nocaption']).errors.join('\n'), /needs "<caption>=<image path>"/);
+  assert.match(parseArgs([]).errors.join('\n'), /at least one --shot/);
+});
+
+await test('the page shows every shot as a captioned image, and no caption becomes markup', () => {
+  const html = buildReviewPage({
+    title: 'Task <b>1</b>',
+    note: 'A & B',
+    shots: [{ caption: 'Before <img onerror=x>', file: 'C:/shots/before.png' }, { caption: 'After', file: 'C:/shots/after.png' }],
+  });
+  assert.ok(!html.includes('<b>1</b>') && !html.includes('<img onerror'), 'captions and title are escaped');
+  assert.ok(html.includes('A &amp; B'));
+  const srcs = [...html.matchAll(/<img src="([^"]+)"/g)].map((m) => m[1]);
+  assert.deepEqual(srcs, [pathToFileURL(path.resolve('C:/shots/before.png')).href, pathToFileURL(path.resolve('C:/shots/after.png')).href]);
+  assert.ok(html.indexOf('Before') < html.indexOf('After'), 'in the order given');
+});
+
+await test('the CLI writes the page and prints its path; a missing image is an error, not a blank page', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'visual-review-test-'));
+  const png = path.join(dir, 'shot.png');
+  fs.writeFileSync(png, 'not really a png');
+  const cli = path.join(ROOT, 'scripts', 'gds', 'review-sheet.js');
+  const ok = spawnSync(process.execPath, [cli, '--shot', `Before=${png}`, '--out', dir, '--no-open'], { encoding: 'utf8' });
+  assert.equal(ok.status, 0, ok.stderr);
+  assert.equal(ok.stdout.trim(), path.join(dir, 'index.html'));
+  assert.match(fs.readFileSync(path.join(dir, 'index.html'), 'utf8'), /<figcaption>Before<\/figcaption>/);
+  const bad = spawnSync(process.execPath, [cli, '--shot', `After=${path.join(dir, 'nope.png')}`, '--no-open'], { encoding: 'utf8' });
+  assert.equal(bad.status, 1);
+  assert.match(bad.stderr, /no such image/);
+});
+
+// ---- the claim-time nudge ----------------------------------------------------
+
+const task = (over = {}) => ({ id: '1', discipline: 'engineer', module_key: null, source: 'manual', touches: [], description: '', ...over });
+
+await test('a task that names a page file in its description is told to use /design and get an OK', () => {
+  const t = task({ description: 'Where: modules/hall-ui/public/goal-forest-lib.js — NODE_W = 168. Drawing is modules/hall-ui/public/goal-forest-render.js.' });
+  assert.deepEqual(pathsNamedIn(t), ['modules/hall-ui/public/goal-forest-lib.js', 'modules/hall-ui/public/goal-forest-render.js'],
+    'sentence punctuation is not part of a path');
+  const lines = visualReviewNudge(t);
+  assert.ok(lines, 'nudged');
+  assert.match(lines.join('\n'), /\/design/);
+  assert.match(lines.join('\n'), /review-sheet\.js/);
+  assert.match(lines.join('\n'), /OK/);
+});
+
+await test('touches[], a UI module label, and the artist craft nudge too — the same predicate the review uses', () => {
+  assert.ok(visualReviewNudge(task({ touches: ['modules/public-landing/public/projects.html'] })));
+  assert.ok(visualReviewNudge(task({ module_key: 'hall-ui' })));
+  assert.ok(visualReviewNudge(task({ discipline: 'artist' })));
+});
+
+await test('a backend task is not nudged — no noise on work that renders nothing', () => {
+  assert.equal(visualReviewNudge(task({ description: 'Fix modules/lifecycle/cascade.js and modules/hall-ui/module.json.' })), null);
+  assert.equal(visualReviewNudge(task({ touches: ['scripts/gds/claim.js'] })), null);
+  assert.equal(visualReviewNudge(task()), null);
+});
+
+await test('claim.js prints the nudge after the craft directive, and cannot fail a claim with it', () => {
+  const src = read('scripts/gds/claim.js');
+  const at = src.indexOf('visualReviewNudge(task)');
+  assert.ok(at > src.indexOf('printDisciplineMode(task);'), 'right after the craft directive');
+  assert.match(src.slice(at - 200, at + 300), /catch \(_\)/, 'wrapped, so a hint can never break a successful claim');
+});
+
+// ---- the rule, where every builder's session reads it ------------------------
+
+await test('all three playbooks carry the rule and the way to show a CLI user the shots', () => {
+  for (const rel of ['docs/packs/engineer.md', 'docs/packs/artist.md', '.claude/skills/design/SKILL.md']) {
+    const doc = read(rel);
+    assert.match(doc, /review-sheet\.js/, `${rel} names the helper`);
+    assert.match(doc, /2026-09-23/, `${rel} dates the owner decision`);
+  }
+  assert.doesNotMatch(read('docs/packs/engineer.md'), /rather than asking a human to look/, 'the old contrary instruction is gone');
+});
+
+summary();