@bongos/core 1.19.987 → 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.987",
-  "core_contract": "1.19.987",
-  "source_commit": "102ad9a7c1c780717451cc48241d577442dc44f1",
+  "core_version": "1.19.988",
+  "core_contract": "1.19.988",
+  "source_commit": "fe4b08f918073241c24208ac22bb4e2a505a00f4",
   "source_ref": "HEAD",
-  "built_at": "2026-09-23T19:04:45.567Z",
+  "built_at": "2026-09-23T19:26:45.671Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 518,
     "agent_docs_stubbed": 26,
-    "functional_verbatim": 2391,
+    "functional_verbatim": 2394,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2935,
-  "tree_sha256": "e0b9f64be067a45f8a343766f231127d7bb3708dc50656f188e122f06b15ac2a",
+  "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": "fcad58b07e48eb75f7dbfb280b1d2f167d07a753388aa063d292c7aee323accf"
+      "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",
@@ -8162,12 +8162,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "80f51079ed98cab29d9b48f5f20049f58104b76d68645ac01d03a7bdcde9f29e"
+      "sha256": "b852a0142a8be848b6e231b88b0c7b5e2f86baa0b88dcb44e42c1f1e65afb9ea"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "fe62f7efb8e83d82f66dd2277b8ae4da8d448a9286727ea88460ec358f339fc5"
+      "sha256": "46df90fa4ee1a722331e5bd7a6531f82e4245a545412e70ef73825bce85840e7"
     },
     {
       "path": "public-docs/index.html",
@@ -8502,7 +8502,7 @@
     {
       "path": "scripts/gds/claim.js",
       "mode": "0000644",
-      "sha256": "942581a081da9134cb7038c61b646ddba6e25f2de15411fe59378a477ac05637"
+      "sha256": "c9a7f39cf1f03e985466005a1857f570b4b3d449b0cbd8b3dfd0f7a7524a7c31"
     },
     {
       "path": "scripts/gds/classify-discipline.js",
@@ -9259,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",
@@ -9759,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",
@@ -10192,7 +10202,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "19be294e50fce302cf4663c7776dfd8472eaddfb33805baf32b681603271cb77"
+      "sha256": "2a9b6a4c34d0321b9684a3054d93a5224359fcdc89d81df9ec01bee4334c25c7"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -14614,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

@@ -2448,5 +2448,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         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/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.987",
+  "version": "1.19.988",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.987",
+      "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.987",
+  "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/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.987'; // 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/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();