@bongos/core 1.19.526 → 1.19.528

package/.claude/skills/otb-character-review/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: otb-character-review
-description: Review a painterly character ANIMATION (a character_anim family — many frames of one character in different poses) against the ADR 0088 animation criteria. Triggers when the user says "review this animation", "score the bongo idle", "check the character animation", "is this animation consistent", "rate these frames", or asks how a generated character/mascot animation holds up. Sibling to otb-design-review (which scores a single pixel-art tile). Returns a plain-language verdict per frame and for the sequence: same character throughout, correct anatomy, each frame on its intended pose, clean edges, and smooth in-order motion. Wraps family_orchestrator.run_family + family_review for the painterly path.
+description: >-
+  Review a painterly character ANIMATION (many frames of one character) against the ADR 0088 criteria — same character throughout, correct anatomy, each frame on its pose, clean edges, smooth in-order motion — with a plain-language verdict per frame and for the sequence. Triggers: "review this animation", "is this animation consistent", "rate these frames". Sibling of otb-design-review (one tile).
 ---
 
 You are reviewing a painterly **character animation** — a `character_anim` family: many frames of the *same* character in *different* poses (e.g. the Bongo Buddha idle-breathing cycle). This is the animation sibling of `otb-design-review` (which scores one pixel-art tile). Do NOT judge it as pixel art — there is no palette to match, no FireRed reference, no 32×32 grid.

package/.claude/skills/paint/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: paint
-description: The art session — the operating playbook for artist-discipline work. Triggers when the user says "/paint", "let's make art", "I want to work on a tile/sprite", "start an art session", or when a claimed task's discipline routes here (claim.js prints a directive to invoke /paint for artist tasks). Show-first, low-text: Claude communicates in pictures, not prose, and drives the existing pixel-art pipeline underneath.
+description: >-
+  The art session — the operating playbook for artist-discipline work. Triggers when the user says "/paint", "let's make art", "I want to work on a tile/sprite", "start an art session", or when a claimed task's discipline routes here (claim.js prints a directive to invoke /paint for artist tasks). Show-first, low-text: Claude communicates in pictures, not prose, and drives the existing pixel-art pipeline underneath.
 ---
 
 You are running an **art session** for Example. This is not the engineer's text-heavy build loop. Read this whole file before acting — it changes how you *communicate* for the rest of the session.

package/.claude/skills/scan-before-install/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: scan-before-install
-description: Scan a third-party GitHub repo or git-hosted Claude plugin/marketplace entry BEFORE anything from it is installed — hardened quarantine fetch, deterministic zero-LLM floor, tiered subagent panel over a scrubbed mirror, arithmetic verdict, honest-limits report, and three evidence-gated landings (print install command / sanitized copy / rebuild spec). The scanner itself NEVER installs anything. Triggers when the user says "/scan-before-install", "scan this repo before I install it", "is this plugin safe to install", "check this tool before I add it", "vet this GitHub repo", "scan this marketplace plugin", or pastes a repo/plugin URL and asks whether it's safe.
+description: >-
+  Scan a third-party GitHub repo or git-hosted Claude plugin BEFORE installing anything: quarantined fetch, deterministic floor, tiered subagent panel over a scrubbed mirror, arithmetic verdict, honest-limits report, three evidence-gated landings. The scanner never installs. Triggers: "/scan-before-install", "is this plugin safe to install", "vet this GitHub repo".
 ---
 
 You are scanning a third-party artifact someone wants to install. The engine lives in `modules/security/artifact-scan/` — this skill is the orchestration wrapper: it runs the pipeline, spawns the panel, and lands one of three offers. Every load-bearing decision below is an owner decision; do not soften any of them.

package/.claude/skills/ship-check/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: ship-check
+description: >-
+  Run every freshness and fitness check ship.js will run, in one command, before shipping — and get the healing command for each stale generated file. Triggers: "/ship-check", "am I ready to ship", "what will ship trip on", "check before I ship", "is anything stale".
+---
+
+# /ship-check — the pre-ship table
+
+**Script skill (authoritative).** The whole action is one command, run from the worktree you will ship from:
+
+```bash
+node scripts/gds/ship-check.js
+```
+
+Add `--tests` to also run the DB-free unit lane (slow; minutes). Add `--json` for machine output.
+
+## Why this exists
+
+Builders were running the same eight generators and checks by hand, one Bash call at a time — 223
+invocations across 140 sessions in three days — because a ship that fails preflight costs a grader
+run, and the last 30 days of session logs name a stale generated file (`docs/copy-registry.json`,
+a nested `CLAUDE.md` symbol block, `docs/file-map.md`, `docs/api/openapi.json`, the §13 session
+snippet) in roughly a quarter of all sessions. This is that sequence as one call with one table.
+It changes nothing: every step is a `--check`; the **fix →** column is what to run.
+
+## What to do with the output
+
+1. Every `✗` row names the generator to run. Run it, look at the diff it produced, commit it on your
+   branch. Then re-run `/ship-check` until every row is `✓`.
+2. `fitness.js` failures name their own fix inline; warnings are advisory (budgets, ratchets).
+3. With `--tests`: a failing test is only "environmental" if the SAME test fails on an untouched
+   checkout of `origin/main`. Compare by test name, never by count — a Windows baseline of ~25
+   environment failures has masked real regressions before (see `docs/recipes/windows-builders.md`).
+4. When the table is all `✓`, ship: `/builder-ship`. The grader and CI are the remaining gates;
+   this skill removes the preflight trip, not the review.
+
+## Relationship to other tools
+
+- `ship.js` runs these checks itself at ship time and refuses on a stale one; `/ship-check` is the
+  same gate run early, when fixing is cheap.
+- The PostToolUse hook `.claude/hooks/edit-hints.js` tells you the moment an edit makes a generated
+  file stale; `/ship-check` is the sweep that catches whatever the hints did not.
+- `node scripts/gds/preflight.js` checks the MACHINE (node version, node_modules, `claude` auth);
+  this checks the TREE.

package/.claude/skills/strand-fix/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: strand-fix
-description: Walk ONE stranded ship to landed — a task parked at `confirmed` that the server reconciler has already probed and given up on (`needs_rebase_reason` = `strand:no_branch_no_tip` or `strand:land_not_proven`), the shape the SessionStart line calls "will never self-heal". Finds where the work actually is (a main commit, an unpushed local branch, a conflicting PR, or nowhere), does the one sanctioned move for that case, and verifies the flip to `shipped`. Also the fix for a claim refused `409 REBASE_REQUIRED` — that gate is one of YOUR strands. Triggers when the user says "/strand-fix N", "fix strand N", "task N is stranded", "land the strand", "my claim says REBASE_REQUIRED", or after the SessionStart "Stranded ships:" line names a task. For a `completed` (ungraded) task use `/grade-recover`; for a `confirmed` task with no strand reason use `/merge-mode`.
+description: >-
+  Walk ONE stranded ship to landed — a task parked at confirmed that the reconciler gave up on (strand:no_branch_no_tip, strand:land_not_proven). Finds where the work is, makes the one sanctioned move, verifies the flip to shipped. Also the fix for a claim refused 409 REBASE_REQUIRED. Triggers: "/strand-fix N", "task N is stranded", "land the strand", "my claim says REBASE_REQUIRED".
 requires: [gh]
 ---
 

package/.claude/skills/worktree-clean/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: worktree-clean
-description: Remove the per-claim worktrees whose work already landed — every shipped task leaves a `.claude/worktrees/task-N` behind, and nothing else prunes them. Lists what is stale (branch merged into origin/main, or branch already deleted by the ship), shows the list, then removes each through the junction-safe `worktree.js remove` — never raw `git worktree remove`, which follows the node_modules junction into the shared node_modules (task 1002809). Triggers when the user says "/worktree-clean", "clean up worktrees", "prune stale worktrees", "remove old worktrees", or when the SessionStart line reports "Stale worktrees: N".
+description: >-
+  Remove the per-claim worktrees whose work already landed (branch merged into origin/main, or deleted by the ship): lists them, then removes each through the junction-safe worktree.js remove — never raw git worktree remove, which follows the node_modules junction (task 1002809). Triggers: "/worktree-clean", "prune stale worktrees", or the SessionStart line "Stale worktrees: N".
 ---
 
 **Script skill (authoritative).** Two scripts do the work; this skill only sequences them and shows the list before anything is removed.

package/.gitattributes

@@ -58,7 +58,12 @@
 # that conflicts only on these files lands without a human (GitHub's own auto-merge
 # can't run a custom driver, hence the server does the merge locally then pushes).
 # NB: the TOP-LEVEL CLAUDE.md is hand-written and deliberately NOT listed here —
-# only the three nested CLAUDE.md docs carry a generated block. docs/file-map.md
+# only the nested CLAUDE.md docs that carry a generated block are. scripts/gds/CLAUDE.md
+# LEFT that set in task 1003548 (its ~40k-char block was 76% of a file loaded on every
+# visit to that directory; docs/repo-map.md still carries the full index), so its entry
+# came out with it — a path listed here whose generator no longer owns it would route a
+# merge through a driver that cannot regenerate it, which tests/git_merge_regen.mjs
+# asserts against. docs/file-map.md
 # carries two generated section blocks (.claude/skills/ + .claude/scheduled-tasks/,
 # ADR 0066, gen-file-map.js), so it joins the set; docs/session-log-index.md is
 # whole-file generated (gen-session-index.js), so it joins too.
@@ -72,7 +77,6 @@ docs/file-map.md           merge=otb-regen
 docs/session-log-index.md  merge=otb-regen
 src/bongos/CLAUDE.md          merge=otb-regen
 src/bongos/routes/CLAUDE.md   merge=otb-regen
-scripts/gds/CLAUDE.md      merge=otb-regen
 
 # docs/copy-registry.json + docs/copy-inventory.md (task 1003543): the copy
 # registry's committed pair (scripts/gds/copy-inventory.js) — fully generated from

package/docs/file-map.md

@@ -419,6 +419,7 @@ tests/
 ├── recall/SKILL.md                ← /recall — one-call project-knowledge search across repo docs + DB prose (tasks, learnings, session logs)
 ├── scan-before-install/SKILL.md   ← /scan-before-install — quarantine-fetch a third-party repo/plugin, deterministic floor + tiered subagent panel over the scrubbed mirror, arithmetic verdict + honest-limits report to the builder's own config dir; prints install commands (pinned SHA only), never installs (goal 1000055)
 ├── session-handoff/SKILL.md       ← /session-handoff — compose a clean, paste-ready next-steps prompt to START a fresh session with (keeps context light by curating what carries forward); read-only, distinct from /builder-ship's ledger notes and /builder-end's close-out
+├── ship-check/SKILL.md            ← /ship-check — run every freshness + fitness check ship.js will run (repo-map/session-index/file-map/api-docs/copy-registry --check, linkify, skill-lint, fitness; --tests adds the DB-free lane) in ONE command before shipping, with the healing command per stale artifact (task 1003548; script scripts/gds/ship-check.js)
 ├── status/SKILL.md                ← /status — what's the status of X / what's left for criterion Cn (read-only rollup)
 ├── strand-fix/SKILL.md            ← /strand-fix N — walk ONE stranded confirmed task (strand:no_branch_no_tip / land_not_proven — the shape the reconciler gave up on) to shipped: find the work (main commit / unpushed branch / conflicting PR / nowhere), do the one sanctioned move, verify the flip; also clears a 409 REBASE_REQUIRED claim gate (task 1003365)
 └── worktree-clean/SKILL.md        ← /worktree-clean — list the per-claim worktrees whose branch already landed on main (scripts/gds/stale-worktrees.js) and remove each through the junction-safe worktree.js remove; never raw git worktree remove (task 1003365)
@@ -454,11 +455,13 @@ tests/
 
 To install on a new machine, symlink each routine's directory under `~/.claude/scheduled-tasks/`, e.g. `ln -s "<repo>/.claude/scheduled-tasks/overnight-code-review" ~/.claude/scheduled-tasks/overnight-code-review`.
 
-**Claude Code hooks** at `.claude/hooks/` (wired in `.claude/settings.json`; all invoked via `node` so they run on Windows/macOS/Linux alike — [#671](https://example.com/builders#/task/671)):
+**Claude Code hooks** at `.claude/hooks/` (wired in `.claude/settings.json`; all invoked through `run-node.sh`, which finds node even when the hook shell's PATH lacks it, so they run on Windows/macOS/Linux alike (task 1003548) — [#671](https://example.com/builders#/task/671)):
 
 ```
 .claude/hooks/
 ├── secret-gate.js            ← PreToolUse (Edit|Write|MultiEdit|NotebookEdit|Bash): cooperative, fail-OPEN block of secret-shaped content before it reaches the tree or a shell (task 1003125, ADR 0022)
+├── run-node.sh               ← the node resolver every hook command runs through (task 1003548): $OTB_NODE_BIN → PATH → known install dirs → nvm; one actionable line + exit 1 when none is found. 1,055 hook runs had died silently with `node: command not found`
+├── edit-hints.js             ← PostToolUse (Edit|Write|MultiEdit): lints a saved SKILL.md's frontmatter (scripts/gds/skill-lint.js) and names the generator an edited path makes stale (copy-registry, repo-map blocks, file-map, openapi, §13 snippet) with its command (task 1003548)
 ├── git-guard.js              ← PreToolUse (Bash): same contract as secret-gate — blocks `git stash` (repo-global stack, learning 1000215), raw `git worktree remove` (follows the node_modules junction, task 1002809), `git push origin main` (PR-only) and `git branch -D`, each with its remedy; kill-switch BONGOS_GIT_GUARD_OFF=1 (task 1003365)
 ├── _core-resolve.js          ← shared helper, not a hook: locates a core module/script across the monolith vs `node_modules/@cloudbongos/core` layouts; required by most hooks here and by four routine scripts under `.claude/scheduled-tasks/`
 ├── cascade-route.js          ← PreToolUse (Task|Agent): cheapest-sufficient start-model advisory for a subagent spawn (ADR 0024); inert unless OTB_AUTONOMY_ENABLED=1

package/docs/module-api-changelog.md

@@ -1489,5 +1489,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.524 with no explicit bump. run 33823218193. (task 1002620)
   1.19.526 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.525 with no explicit bump. run 33824700579. (task 1002620)
+  1.19.527 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.526 with no explicit bump. run 33827382028. (task 1002620)
+  1.19.528 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.527 with no explicit bump. run 33829339717. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/docs/recipes/windows-builders.md

@@ -101,3 +101,49 @@ because the server already landed the task first (reconcile-on-read or the ~5-mi
 `ship.js` now normalizes both API error shapes and **verifies the live task status with a GET
 before reporting failure** (task 1002809) — a verified `shipped` prints as the success it is. If
 you see a ship-call failure from older tooling, check `GET /tasks/<id>` before reacting.
+
+## The hook shell can start without node — hooks were silently off (task 1003548)
+
+- **Symptom:** every hook run reports `Failed with non-blocking status code: /usr/bin/bash: line 1: node: command not found`. A transcript scan of 2026-09-01..03 counted **1,055** such runs, which meant `secret-gate`, `git-guard`, `worktree-guard`, `lifecycle-card` and `conductor` were off for whole sessions while Claude Code showed only a muted warning.
+- **Root cause:** Claude Code runs hook commands through Git Bash, and on this machine that shell intermittently starts with a PATH that predates the Node install. The Bash tool inherits the same PATH, which is why sessions also prepended `export PATH="/c/Program Files/nodejs:…"` to 1,404 commands.
+- **What the tooling does now:** every hook command in `.claude/settings.json` goes through `.claude/hooks/run-node.sh`, which finds node on PATH or in the known install dirs (`C:\Program Files\nodejs`, `%LOCALAPPDATA%\Programs\nodejs`, nvm, Homebrew, `/usr/local/bin`) and, when it truly cannot, prints one line naming the fix instead of failing quietly. Override with `OTB_NODE_BIN` in the `env` block of `.claude/settings.local.json` if your node lives somewhere exotic.
+- **For the Bash tool itself:** check once with `command -v node`; prepend PATH only if it is missing. Do not put the prepend on every command — see the next section for why that also collides with worktree isolation.
+
+## Compound `export PATH=…; cd …; …` commands collide with worktree isolation
+
+- **Symptom:** `This session is isolated in the worktree … but this command is too complex to verify that it stays inside` (25×), `… changes directory to the shared checkout` (7×), `… runs export PATH= with a value every later program …` (6×), `… runs a command whose name is computed at runtime` (3×). 1,931 of 2,370 Bash calls in the scan were compound.
+- **Root cause:** a session that entered a worktree (EnterWorktree) has Claude Code checking that each Bash command stays inside it. A chain of `export … ; cd … && …` defeats the checker, so it refuses the whole command.
+- **Fix:** one purpose per command; use paths relative to the worktree (the Bash tool's cwd is the worktree); no `export PATH=` prefix once node is on PATH; never `cd` into the main checkout from a worktree session (learning 2026-08-29: `../../../` checks and dirties the MAIN checkout — run the worktree's own `scripts/gds/` copy).
+
+## `git fetch` / `git push` / `ls-remote` fail here BY DESIGN
+
+- This machine holds no GitHub push credential (ADR 0031 §6 / ADR 0055). The scan found 22 `git fetch` attempts in three days, all wasted. Landing is server-mediated: `/builder-ship` uploads a bundle and the server pushes, opens the PR and lands it. To see whether work reached GitHub use `GET /api/gds/tasks/:id/publish-status`, never a raw git probe. To base a new worktree on fresh main, `node scripts/gds/worktree.js add <task-id> --base origin/main` (worktree.js fetches through the sanctioned path).
+
+## A worktree without `node_modules` fails 300+ tests — and the count is not the signal
+
+- **Symptom:** `Cannot find module 'pg'` / `'express'`; `npm test` reports ~300 FAILED; 9 `npm install`s and 2 dead junctions in three days of transcripts.
+- **What the tooling does now:** SessionStart prints one `[otb] node_modules is missing …` line (from `scripts/gds/preflight.js`'s check) when neither the worktree nor the main checkout has it. Install ONCE in the main checkout (`npm ci`); inside-repo worktrees resolve from it.
+- **Rule:** when comparing a local run against CI, compare failing test NAMES against an untouched checkout of `origin/main`, never counts — a ~25-failure Windows baseline has masked real regressions (session logs 2026-08-14, 2026-08-19). `node scripts/gds/ship-check.js --tests` prints the names.
+
+## `tests/git_merge_regen.mjs` — when it reds, suspect `.gitattributes` first, not Windows
+
+This test is the consistency gate between **two** sources that must agree, and it is the one that
+caught a real bug during task 1003548, so read its assertion before blaming the platform:
+
+- **Every path declared `merge=otb-regen` in `.gitattributes` must be in `REGENERABLE`**
+  (`scripts/gds/git-merge-regen.js`, derived from `gen-repo-map.NESTED_DIRS` + the whole-file set).
+  Drop a doc from the generators and its `.gitattributes` line has to come out in the same commit —
+  otherwise a merge on that path routes through a driver that cannot regenerate it. The failure reads
+  `.gitattributes declares merge=otb-regen for <path> but REGENERABLE … does not know it`.
+- **A `real git merge must auto-resolve via the driver; got 1` failure** with a mangled driver path
+  (`Cannot find module 'C:\…\Temp\otb-gitmerge-*\<redacted>…'`) has been seen on this
+  machine and then stopped reproducing in all three trees (worktree, baseline worktree, main
+  checkout) — so treat it as intermittent, not as a standing Windows defect. Do NOT record it as a
+  known baseline failure: doing so is what let a genuine regression hide behind it for a whole
+  session. Re-run it, and follow the naming rule above — if it fails on your branch and passes on an
+  untouched `origin/main` worktree, it is yours.
+
+## CRLF: a multi-line find silently misses, and a whole-file diff is usually line endings
+
+- Several hall files (`people.css`, `people.html`, `style.css`, the privacy spec) and every `.claude/skills/*/SKILL.md` are CRLF; `scripts/gds/*.js` and the tests are LF. An exact-string patch must detect the file's EOL before joining lines (`text.includes('\r\n') ? '\r\n' : '\n'`), or the find matches nothing and the edit is a silent no-op (session log 2026-08-24).
+- A `git diff --stat` that touches every line of a file you barely edited is an EOL flip — check with `git diff --stat --ignore-cr-at-eol`, and restore the original EOL before committing.

package/modules/grading/generated-provenance.js

@@ -58,7 +58,7 @@ const GENERATORS = [
     owns: [
       { file: 'src/bongos/CLAUDE.md', scope: 'fence', marker: 'BEGIN GENERATED REPO-MAP' },
       { file: 'src/bongos/routes/CLAUDE.md', scope: 'fence', marker: 'BEGIN GENERATED REPO-MAP' },
-      { file: 'scripts/gds/CLAUDE.md', scope: 'fence', marker: 'BEGIN GENERATED REPO-MAP' },
+      // scripts/gds/CLAUDE.md left NESTED_DIRS in task 1003548 — it carries no fence any more.
     ],
   },
   {

package/modules/grading/grader-subagent.js

@@ -23,6 +23,25 @@ function runSubagent({ prompt, opts = {} }) {
     // isn't named `claude` on PATH — covers any OS, not just Windows.
     const bin = opts.claudeBin ?? process.env.OTB_CLAUDE_BIN ?? process.env.CLAUDE_BIN ?? 'claude';
 
+    // THE PERMISSION MODE IS ROOT-DEPENDENT (task 1003574). `bypassPermissions` maps
+    // to --dangerously-skip-permissions, and the CLI REFUSES that when euid is 0:
+    //   "--dangerously-skip-permissions cannot be used with root/sudo privileges"
+    // It exits non-zero before doing any work, so under root EVERY worker returns
+    // SUBAGENT_NONZERO_EXIT and the whole panel dies. A root container is an ordinary
+    // CI/sandbox shape, not an exotic one — this was hit on a real ship (task 1003280).
+    //
+    // `acceptEdits` is the fallback because it is the closest mode the CLI accepts as
+    // root, and it grants this worker NOTHING extra: the tool list is `Read` alone, so
+    // there are no edits to accept. Verified as root that a worker under acceptEdits
+    // still reads files inside its cwd (which is all a grader worker ever does) while
+    // a path outside the project is refused without hanging — in -p there is no prompt
+    // to answer, so a denial returns rather than blocking.
+    //
+    // Non-root keeps bypassPermissions exactly as before: this narrows the mode only
+    // where the wider one cannot run at all.
+    const isRoot = typeof process.getuid === 'function' && process.getuid() === 0;
+    const permissionMode = isRoot ? 'acceptEdits' : 'bypassPermissions';
+
     const args = [
       '-p',
       '--print',
@@ -30,7 +49,7 @@ function runSubagent({ prompt, opts = {} }) {
       '--output-format', 'json',
       '--tools', 'Read',
       '--disable-slash-commands',
-      '--permission-mode', 'bypassPermissions',
+      '--permission-mode', permissionMode,
     ];
 
     const startedAt = Date.now();

package/modules/grading/grader.js

@@ -183,6 +183,11 @@ function aggregatePanel(workerResults, meta = {}) {
   // If the panel were somehow advisory-only, fall back to gating on everyone so
   // a lone Narc still counts (defensive — the default panel always has 3+
   // gating workers).
+  // A pseudo-worker produced by a deterministic check rather than an LLM subagent
+  // (route-rank, permission-path — both stamp model:'deterministic'). It cannot be
+  // taken out by a grader outage, so it is not evidence either way about whether the
+  // panel ran. Task 1003574.
+  const isDeterministic = (w) => w && w.model === 'deterministic';
   const nonAdvisory = workerResults.filter((w) => !isAdvisory(w));
   const gating = nonAdvisory.length ? nonAdvisory : workerResults;
   const gatingFail = gating.filter((w) => w.verdict === 'fail' && !isMissingSignal(w)).length;
@@ -202,7 +207,25 @@ function aggregatePanel(workerResults, meta = {}) {
   // is an infra/outage condition, NOT a 0/10 quality rejection. Distinguished
   // from the partial-error case (some gating workers errored, others reported)
   // so callers (ship.js) can present "grader unavailable" instead of a FAIL.
-  const gatingErrorAll = gating.length > 0 && gating.every((w) => isMissingSignal(w));
+  //
+  // TASK 1003574 — WHY THIS COUNTS ONLY THE SUBAGENT WORKERS. When #943 was written
+  // every gating worker was an LLM subagent, so "all of them are missing signal" and
+  // "the grader could not run" were the same sentence. They stopped being the same
+  // the moment the DETERMINISTIC pseudo-workers (route-rank, permission-path) were
+  // appended to workerResults: those never spawn a subprocess, so an outage cannot
+  // touch them, and a passing route-rank made `gating.every(isMissingSignal)`
+  // permanently false. The effect was that a TOTAL subagent outage could no longer
+  // reach this branch at all — it fell through to securityLensErrored and was
+  // reported as `FAIL · 0/10` with zero issues and every rubric axis null, which is
+  // indistinguishable from a real rejection and routes the builder to a re-grade
+  // that cannot clear it. Observed end-to-end on task 1003280.
+  //
+  // Excluding the deterministic checks here does NOT weaken the gate: a
+  // deterministic worker that FAILS is a real finding and is caught by `gatingFail`,
+  // which is the first branch and takes precedence over this one. All this says is
+  // that a deterministic check PASSING is not evidence the grader ran.
+  const subagentGating = gating.filter((w) => !isDeterministic(w));
+  const gatingErrorAll = subagentGating.length > 0 && subagentGating.every((w) => isMissingSignal(w));
   // Advisory-worker outcomes — never a hard block. Uses isAdvisory so a Narc
   // that DID raise a blocker is treated as gating (in `nonAdvisory`), not here.
   const advisoryFail = workerResults.some((w) => isAdvisory(w) && w.verdict === 'fail' && !isMissingSignal(w));

package/modules/lifecycle/cascade.js

@@ -77,10 +77,85 @@
 //               a throw is caught and treated as "no match", because a broken
 //               predicate must not stop the other rules.
 //   title(task) / body(task)  the generated task's title and description.
-//   kind        optional task kind; defaults to 'chore'.
+//   kind        optional task kind; must be one the classifier knows
+//               (task-classifier.VALID_KINDS). Defaults to 'unclassified' —
+//               which is right for generated work anyway, because a request the
+//               board has not triaged has, precisely, no classification yet.
 //
-// Production rules live here. It is empty by design — see the header.
-const CASCADES = Object.freeze([]);
+// ---------------------------------------------------------------------------
+// The first production rule (R04 of goal 1000074, task 1003115).
+// ---------------------------------------------------------------------------
+//
+// THE ARTIST REVIEW. "Every shipped work with copy or visuals becomes a Review
+// task for an artist, in two steps" (the criterion artist-review-task-on-ship).
+// This is the rule that makes that true, and it is the whole of R04's build: the
+// mechanism (ADR 0242) and its four safety properties already exist and are
+// tested; R04 writes the one declaration.
+//
+// TWO GUARDS THAT KEEP IT FROM MISFIRING, both pinned in the tests:
+//   • It excludes `source === CASCADE_SOURCE`. Without that, the artist review
+//     task it generates — discipline 'artist', so it matches its own predicate —
+//     would on ship generate a review OF the review, and so on. The exclusion
+//     makes the generation a single hop, never a chain.
+//   • "Copy or visuals" is a NARROW, explicit predicate (hasCopyOrVisualWork),
+//     not "every ship". A cascade that fired on everything would bury the artist,
+//     and the criterion's "dismissable rather than nagging" would be a lie.
+//
+// It does NOT block anything (ADR 0241 draws the line: an artist may hold a
+// DEPLOY, decided per project, never a builder's ship; that gate is a separate
+// build). The generated task is a `backlog` request that triage may dismiss.
+
+// The modules whose shipped work puts user-facing copy or visuals in front of a
+// person. Kept as an explicit set rather than inferred, because "is this
+// copy/visual work" is a judgement the rule should state out loud and a test
+// should be able to pin — an inferred predicate is the kind that quietly widens.
+const COPY_VISUAL_MODULES = Object.freeze([
+  'copy-desk',    // the copy registry + proposals (goal 1000074's own spine)
+  'hall-ui',      // the builders' hall — the most-seen surface
+  'art-pipeline', // generated visual assets
+  'status-ui',    // the public status dashboard
+  'ui-design',    // the design-system surfaces (ADR 0081)
+]);
+
+// 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) {
+  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;
+  return false;
+}
+
+// The two-step artist review body. STEP 1 coaches the grader (the artist trains
+// the grading system, not only the artefact); STEP 2 remakes the copy/visuals
+// with both routes explicitly offered — R04's brief, verbatim in intent.
+function artistReviewBody(task) {
+  return [
+    `This is an ARTIST REVIEW, generated automatically because task ${task.id} put copy or visuals in front of a person. It is a REQUEST, not a gate — it blocks nothing that shipped, and triage may dismiss it.`,
+    '',
+    `STEP 1 — REVIEW THE GRADER, not only the work. Read how the grader judged task ${task.id}'s copy and visuals, and coach it: where was it right, and where did it miss what an artist would catch — slop, an off-voice line, a claim that does not land, a visual that reads as generated? The artist trains the grading system, not just the artefact, so this step is the one that compounds.`,
+    '',
+    'STEP 2 — REMAKE OR TWEAK the copy/visuals if they need it. Your choice of route, both offered on purpose: OUTSIDE the AI chat (edit the surface directly and land it through the copy desk or the normal pipeline), or WITH it (draft in chat, then land). Either way it lands as a claimed, graded, shipped task like everything else — there is no live CMS (goal 1000074\'s hard rule).',
+    '',
+    'If the copy and visuals are fine and the grader judged them well, DISMISS this in triage. That is a real, expected outcome — not a failure.',
+  ].join('\n');
+}
+
+// Production rules. The artist review is the first (R04); add another by
+// appending an entry, never by touching the runner (ADR 0242).
+const CASCADES = Object.freeze([
+  Object.freeze({
+    key: 'artist-review-on-ship',
+    discipline: 'artist',
+    kind: 'unclassified',
+    // The anti-recursion guard (source !== CASCADE_SOURCE) is FIRST so a
+    // cascade-generated task is rejected before any other test runs.
+    when: (t) => t.source !== CASCADE_SOURCE && hasCopyOrVisualWork(t),
+    title: (t) => `Artist review: the copy and visuals that shipped in task ${t.id}`,
+    body: artistReviewBody,
+  }),
+]);
 
 // The (source, source_ref) pair the generated task is keyed on. `source` is a
 // constant so every cascade-generated row is findable as a class; the ref pins
@@ -171,7 +246,11 @@ function cascadeTaskSpec(rule, task) {
     title: String(rule.title(task) || '').trim(),
     description: `${preamble}\n\n${body}`,
     discipline: rule.discipline,
-    kind: rule.kind || 'chore',
+    // 'unclassified', not 'chore' (task 1003115): the cascade calls db.createTask
+    // directly, bypassing the route's kind validation, and 'chore' is not in
+    // task-classifier.VALID_KINDS — it would have written an invalid kind. A
+    // generated request the board has not triaged is genuinely unclassified.
+    kind: rule.kind || 'unclassified',
     status: 'backlog',
     source: CASCADE_SOURCE,
     sourceRef: cascadeSourceRef(rule.key, task.id),
@@ -229,6 +308,9 @@ async function runCascadesForShip(shipped, deps = {}) {
 module.exports = {
   CASCADES,
   CASCADE_SOURCE,
+  COPY_VISUAL_MODULES,
+  hasCopyOrVisualWork,
+  artistReviewBody,
   cascadeSourceRef,
   assertRuleShape,
   validateCascades,

package/modules/lifecycle/tests/cascade.mjs

@@ -185,12 +185,69 @@ await test('the production table is valid, and a duplicate key is refused', () =
   assert.ok(shape.some((p) => /body/.test(p)));
 });
 
-await test('the production table ships EMPTY, deliberately — R04 writes the first rule', () => {
-  // If this fails because a rule was added, that is fine: replace the assertion
-  // with one that pins the new rule's key and discipline. It exists so the
-  // emptiness is a DECISION on the record (see cascade.js's header) rather than
-  // something nobody noticed.
-  assert.equal(cascade.CASCADES.length, 0);
+// --- the first production rule: the artist review (R04, task 1003115) --------
+
+const shippedCopy = (over = {}) => ({
+  id: '7001', version_id: 'BONGOS-V1', goal_id: '1000074',
+  title: 'Reword the hall empty states', discipline: 'engineer',
+  kind: 'feature', status: 'shipped', module_key: 'hall-ui', source: 'manual',
+  ...over,
+});
+
+await test('the artist review is the one production rule, keyed and disciplined', () => {
+  assert.equal(cascade.CASCADES.length, 1);
+  const r = cascade.CASCADES[0];
+  assert.equal(r.key, 'artist-review-on-ship');
+  assert.equal(r.discipline, 'artist', 'the review is FOR the artist, whatever role shipped the work');
+  assert.equal(r.kind, 'unclassified', 'a valid kind — not the invalid "chore" the spec used to default to');
+  assert.deepEqual(cascade.validateCascades(), [], 'and the shipped table is well-formed');
+});
+
+await test('a copy/visual ship generates the two-step artist review', () => {
+  const { matched } = cascade.cascadesFor(shippedCopy());
+  assert.equal(matched.length, 1);
+  const spec = matched[0].spec;
+  assert.equal(spec.discipline, 'artist');
+  assert.equal(spec.kind, 'unclassified');
+  assert.equal(spec.status, 'backlog', 'a request that triage may dismiss — not claimable, not nagging');
+  assert.match(spec.title, /7001/);
+  // Both steps, and both routes of step 2, are in the body.
+  assert.match(spec.description, /STEP 1 — REVIEW THE GRADER/);
+  assert.match(spec.description, /STEP 2 — REMAKE OR TWEAK/);
+  assert.match(spec.description, /OUTSIDE the AI chat/);
+  assert.match(spec.description, /WITH it/);
+  assert.match(spec.description, /DISMISS this in triage/);
+  assert.match(spec.description, /blocks nothing that shipped/, 'it says out loud that it is not a gate');
+});
+
+await test('"copy or visuals" is a NARROW predicate — three ways in, and a default of no', () => {
+  const H = cascade.hasCopyOrVisualWork;
+  assert.equal(H(shippedCopy({ module_key: 'copy-desk' })), true);
+  assert.equal(H(shippedCopy({ module_key: 'art-pipeline' })), true);
+  assert.equal(H(shippedCopy({ module_key: null, source: 'copy-proposal' })), true, 'a landed copy proposal');
+  assert.equal(H(shippedCopy({ module_key: null, source: 'manual', discipline: 'artist' })), true, 'work an artist did');
+  // The default is NO — a backend/infra ship is not an artist review.
+  assert.equal(H(shippedCopy({ module_key: 'lifecycle', discipline: 'engineer', source: 'manual' })), false);
+  assert.equal(H(shippedCopy({ module_key: null, discipline: 'engineer', source: 'manual' })), false);
+  assert.equal(H(null), false);
+});
+
+await test('THE ANTI-RECURSION GUARD: an artist review shipping does NOT generate a review of itself', () => {
+  // The generated review is discipline:'artist' + source:'cascade'. Its own
+  // predicate (discipline artist) would match — so without the source guard it
+  // would cascade forever. This is the test that proves it is a single hop.
+  const reviewTaskThatShipped = shippedCopy({
+    discipline: 'artist', source: cascade.CASCADE_SOURCE, module_key: null, id: '7100',
+  });
+  const { matched } = cascade.cascadesFor(reviewTaskThatShipped);
+  assert.equal(matched.length, 0, 'a cascade-generated task never triggers another cascade');
+});
+
+await test('the review inherits the shipped task goal and version, not goal 1000074 by fiat', () => {
+  // A copy ship in some other goal gets its review filed next to that work.
+  const { matched } = cascade.cascadesFor(shippedCopy({ goal_id: '1000046', version_id: 'BONGOS-V1' }));
+  assert.equal(matched[0].spec.goalId, 1000046);
+  assert.equal(matched[0].spec.versionId, 'BONGOS-V1');
 });
 
 console.log(`\n${passed} passed, ${failed} failed`);

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.526",
+  "version": "1.19.528",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/claude-materialize.js

@@ -48,9 +48,14 @@ function scriptToVerb(verbs = VERBS) {
 // skills + settings.json hooks use. The optional $CLAUDE_PROJECT_DIR/ or ./ prefix and surrounding
 // quote are consumed so the whole thing collapses to the bongos form. `.claude/hooks/<x>.js` refs are
 // deliberately NOT matched (this targets scripts/gds/) — those stay instance-local after materialize.
-const GDS_INVOCATION_RE = /node\s+"?(?:\$CLAUDE_PROJECT_DIR\/|\.\/)?scripts\/gds\/([a-zA-Z0-9_-]+)\.js"?/g;
+// The launcher is bare `node`, OR the hook resolver `sh "$CLAUDE_PROJECT_DIR/.claude/hooks/run-node.sh"`
+// that every settings.json hook command goes through since task 1003548 (it finds node when the hook
+// shell's PATH lacks it). Both collapse to the same bongos form; a resolver call whose target is a
+// .claude/hooks/*.js stays untouched exactly like the bare-node form did.
+const LAUNCHER = String.raw`(?:node|sh\s+"?(?:\$CLAUDE_PROJECT_DIR\/|\.\/)?\.claude\/hooks\/run-node\.sh"?)`;
+const GDS_INVOCATION_RE = new RegExp(LAUNCHER + String.raw`\s+"?(?:\$CLAUDE_PROJECT_DIR\/|\.\/)?scripts\/gds\/([a-zA-Z0-9_-]+)\.js"?`, 'g');
 // A non-gds core script under scripts/ (rare in skills, but keep the transform total).
-const OTHER_SCRIPT_RE = /node\s+"?(?:\$CLAUDE_PROJECT_DIR\/|\.\/)?scripts\/((?!gds\/)[a-zA-Z0-9_./-]+\.js)"?/g;
+const OTHER_SCRIPT_RE = new RegExp(LAUNCHER + String.raw`\s+"?(?:\$CLAUDE_PROJECT_DIR\/|\.\/)?scripts\/((?!gds\/)[a-zA-Z0-9_./-]+\.js)"?`, 'g');
 
 // Pure: rewrite core-script invocations in a skill/settings command string to the bongos bin.
 // Idempotent (a string with no matching invocation is returned unchanged).

package/scripts/gds/fitness.js

@@ -182,7 +182,7 @@ function checkGeneratedArtifactsFresh() {
   try {
     execFileSync(process.execPath, [path.join(__dirname, 'gen-repo-map.js'), '--check-block'], { cwd: REPO_ROOT, stdio: 'pipe' });
   } catch {
-    violations.push('The tracked nested-doc symbol blocks (src/bongos/CLAUDE.md, src/bongos/routes/CLAUDE.md, scripts/gds/CLAUDE.md) are STALE — run `node scripts/gds/gen-repo-map.js` and commit (ADR 0063 / ADR 0110). NB docs/repo-map.md itself is gitignored + deploy-regenerated, not gated here.');
+    violations.push('The tracked nested-doc symbol blocks (src/bongos/CLAUDE.md, src/bongos/routes/CLAUDE.md) are STALE — run `node scripts/gds/gen-repo-map.js` and commit (ADR 0063 / ADR 0110). NB docs/repo-map.md itself is gitignored + deploy-regenerated, not gated here.');
   }
   try {
     execFileSync(process.execPath, [path.join(__dirname, 'gen-session-index.js'), '--check-block'], { cwd: REPO_ROOT, stdio: 'pipe' });
@@ -1295,9 +1295,48 @@ function checkErrorEnvelope() {
   };
 }
 
+// ============================================================================
+// Check 2c — every SKILL.md frontmatter parses the way Claude Code's YAML reader reads it (task 1003548)
+// ============================================================================
+// Ten of fifty skills shipped with an unquoted description holding ": " or " #": YAML dropped or
+// truncated EVERY field, the skill matched on its body text, and nothing in CI noticed. A parse
+// error is a hard fail; description length and the listing budget are advisory (the listing is
+// resident in every session, ~1% of context, and gets truncated past ~8k chars). The check reads
+// the instance's .claude/skills/ and is a quiet pass when a checkout carries none (published core).
+function checkSkillFrontmatter() {
+  const violations = [];
+  const warnings = [];
+  let lint;
+  try { lint = require('./skill-lint'); } catch (e) {
+    return { name: 'skill frontmatter parses (task 1003548)', ok: true, hardFail: false, violations, warnings: [`skill-lint unavailable: ${e.message}`], note: 'linter missing — check skipped.' };
+  }
+  const files = lint.listSkillFiles(INSTANCE_ROOT);
+  const report = lint.lintSkills(files);
+  const rel = (f) => path.relative(INSTANCE_ROOT, f).replace(/\\/g, '/');
+  const long = [];
+  for (const r of report.results) {
+    for (const e of r.errors) violations.push(`${rel(r.file)}: ${e}`);
+    if (r.description.length > lint.DESC_WARN_CHARS) long.push({ file: rel(r.file), n: r.description.length });
+  }
+  if (long.length) {
+    long.sort((a, b) => b.n - a.n);
+    warnings.push(`${long.length} description(s) over ${lint.DESC_WARN_CHARS} chars (longest: ${long.slice(0, 4).map((l) => `${l.file.split('/')[2]} ${l.n}`).join(', ')}) — every char is resident in every session; run node scripts/gds/skill-lint.js.`);
+  }
+  if (report.overBudget) warnings.push(`the skill listing is ${report.listingChars} chars (~${estTokens(report.listingChars)} tokens) against a ~${report.budgetChars}-char budget — Claude Code truncates entries past it and routing degrades.`);
+  return {
+    name: 'skill frontmatter parses (task 1003548)',
+    ok: violations.length === 0,
+    hardFail: violations.length > 0,
+    violations,
+    warnings,
+    note: `${report.results.length} SKILL.md file(s) under .claude/skills/ parse as YAML (name + description present, no ": " / " #" in a plain scalar); length + listing budget advisory.`,
+  };
+}
+
 const CHECKS = [
   checkCoreHostBoundary,
   checkClaudeMdBudget,
+  checkSkillFrontmatter,
   checkNestedDocsPresent,
   checkRankGuards,
   checkGeneratedArtifactsFresh,

package/scripts/gds/gen-repo-map.js

@@ -61,7 +61,9 @@ const SCAN_ROOTS = [...CORE_SCAN_ROOTS, ...INSTANCE_SCAN_ROOTS, MODULE_SCAN_ROOT
 
 // Directories whose nested CLAUDE.md gets a generated symbol-skeleton block (must already exist —
 // they are authored in Path A / ADR 0061; this only refreshes the factual half). All CORE dirs.
-const NESTED_DIRS = ['src/bongos', 'src/bongos/routes', 'scripts/gds'];
+// scripts/gds dropped (task 1003548): its block had grown to ~40k chars — 76% of a file every builder
+// session loads when it touches claim/ship. docs/repo-map.md still carries the full index.
+const NESTED_DIRS = ['src/bongos', 'src/bongos/routes'];
 
 const EXCLUDE_DIR = new Set(['node_modules', '.git', 'tests', 'test', 'vendor']);
 const TOP_GLOBAL = 50;      // global "most-referenced" table cap