@bongos/core 1.19.525 → 1.19.527

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/adr/0242-a-cascade-is-a-declaration-table-on-the-event-that-already-exists.md

@@ -0,0 +1,107 @@
+# 0242 — A cross-role cascade is a declaration table on the event that already exists
+
+- **Status:** Accepted
+- **Date:** 2026-09-04
+- **Tasks:** [#1003549](https://cloudbongos.com/builders#/task/1003549) (goal 1000074, the artist's loop) — the split [#1003115](https://cloudbongos.com/builders#/task/1003115) (R04) invited in its own brief: *"if that generalisation is bigger than this task, split it — a cascade mechanism is its own task and possibly its own goal."* Encoded as a real dependency edge by [#1003264](https://cloudbongos.com/builders#/task/1003264).
+- **Related:** 0241 (the artist gate — why a cascade may never fail a ship), 0083 (the module system's one-way rule and the kernel seams), 0233 (a proposal is a task carrying a patch — the same `(source, source_ref)` idempotency), 0086 (goals), 0120 (pay on land)
+
+## Context
+
+R04 needs "every ship with copy or visuals generates one [review task]" — automatic on ship, never
+hand-filed. Its brief said plainly that the infrastructure for that **did not exist**, and named the
+spark queue as the prototype to extend. Reading both surfaces closely shows the prototype is the
+wrong half of the problem:
+
+- The **spark queue** (goal 1000062 / [task 1002921](https://cloudbongos.com/builders#/task/1002921))
+  returns open Big Idea Sparks not yet developed.
+- The **copy-desk flag queue** (R02 / [task 1003113](https://cloudbongos.com/builders#/task/1003113))
+  returns surfaces anyone flagged as needing touch-up.
+
+Both are **PULL**: a filtered listing of rows another role had already created. They are how one role
+*finds* work another role left. Nothing anywhere **generated** work on a state transition, which is
+the **PUSH** R04 actually asks for. (`cascade-dispatch.js` is model-cost routing and unrelated —
+named here only because its name has sent more than one reader down the wrong path.)
+
+## Decision
+
+### 1. No new bus — `task.shipped` already exists
+
+The kernel seam registry's own header uses this exact scenario as its worked example: *"the lifecycle
+emits `task.shipped` and the discord module may want to react."* The event is emitted post-commit by
+both ship paths (the publish reconciler and the ship routes), and already has two consumers —
+discord's ship broadcast and sessions' deferred reward.
+
+So a cascade is **one more listener on the event that already says a ship happened**, registered in
+`routes/lifecycle.js` beside the kernel port, for the reason that file already documents: the route
+mount is the one boot hook that runs both in the live server and whenever a test rebuilds the router.
+Building a second notification path would have been a parallel spine to keep in sync with this one.
+
+### 2. A declaration table, not a rules engine
+
+A cascade is one frozen entry: `{ key, discipline, when(task), title(task), body(task) }`. There is
+no condition language, no stored rules, no per-project configuration, no UI, and no priority
+ordering. Adding a cascade means appending an entry; the runner does not change.
+
+This is the [ADR 0237](<redacted>.md)
+/ [ADR 0239](<redacted>.md) shape applied to a
+different problem, and for the same reason: the generalisations worth building are the ones two or
+three real entries have shown they share. With one consumer in existence, a rules engine would be
+inventing the requirements it then satisfied.
+
+### 3. `CASCADES` ships EMPTY, and R04 writes the first rule
+
+The mechanism lands with no production cascade. Its four properties are proved against the tests'
+own declarations rather than against one example — which is the stronger proof, because a mechanism
+pinned to its first consumer's shape tends to fit only that shape.
+
+This is deliberate and is asserted, so the emptiness is a decision on the record rather than
+something nobody noticed. The artist review cascade is R04's content: this task built the thing R04
+said was missing, and stopped there.
+
+### 4. Four properties, all of them load-bearing
+
+- **It can never fail the ship it reacts to.** The event fires post-commit, both emitters already
+  wrap it, listener errors are isolated by the seam, and `runCascadesForShip` catches everything and
+  returns a report. Every failure shape — a predicate that throws, a malformed rule, a database that
+  is down, a junk payload — is a logged report and nothing else. This is not defensive habit: ADR
+  0241 settled that an artist's review may hold a **deploy** and never a builder's **ship**, and a
+  generator that could fail a ship would smuggle that gate back in through the back door. Verified
+  against a real failure, not a stub: with no database reachable, emitting `task.shipped` logs one
+  error line and resolves.
+- **It is idempotent, on machinery that already exists.** Generated tasks carry `source: 'cascade'`
+  and `source_ref: cascade-<key>-<taskId>`, so `createTask`'s `(source, source_ref)` read — the same
+  one a copy proposal uses (ADR 0233) — makes a reconciler re-sweep, a re-ship, or both emitters
+  firing a no-op. The runner checks first, so the ordinary case is a read.
+- **It says where it came from.** Every generated task inherits the source task's `goal_id` and
+  `version_id`, carries the originating id in its ref, and opens with the source task and the rule
+  key. NOT `parent_task_id`: that column models a **subtask**, and cascaded work is not part of the
+  ship that triggered it — it is separate work, for a different role, that outlives its trigger.
+- **It files at `backlog`, never `ready`.** Generated work is a request and goes through ordinary
+  triage, like a copy proposal or a capture. Auto-filing claimable work would let a rule nobody
+  re-read mint claims.
+
+## Consequences
+
+- **R04 is unblocked**, and narrowed: it appends one entry to `CASCADES` and writes the review task's
+  content and the ADR 0241 gate. It does not build a generation mechanism.
+- **A rule key is permanent.** It is half the `source_ref`, so renaming one re-files every task that
+  rule ever generated. Stated in the file and pinned by the duplicate-key check.
+- **The mechanism is discipline-agnostic.** Nothing about it is artist-specific; an ideator or
+  engineer cascade is the same entry with a different `discipline`. That is the generalisation the
+  brief asked for, and the reason this is not simply part of R04.
+- **Accepted limit:** cascades are declared in code, not configured per project. A project that
+  wants a cascade the platform does not declare cannot have one. That is the right trade while the
+  count is zero, and the point at which it stops being right is when the second and third entries
+  disagree about what they need.
+
+## Rejected
+
+- **Extending the spark queue.** The brief's own suggestion, and the wrong half: the queue is a
+  read-side filter over rows that already exist. Nothing in it generates anything.
+- **A new event or a poller.** `task.shipped` exists, is post-commit, and has two consumers already.
+- **A rules engine, or per-project cascade configuration.** See §2 — both are generalisations ahead
+  of their evidence.
+- **Filing generated work at `ready`.** See §4.
+- **`parent_task_id` as the link.** See §4 — it would claim a subtask relationship that is not true.
+- **Running the cascade inside the ship transaction.** It would make a generation failure a ship
+  failure, which is exactly the coupling ADR 0241 rules out.

package/docs/adr/README.md

@@ -329,5 +329,6 @@ This keeps the decision history honest and traceable.
 | 0239 | [**A recommendation is a table that carries its own reason; governance is a preview and invites are a seam** ([task 1002336](https://cloudbongos.com/builders#/task/1002336) · goal 1000046, criteria `proj-module-select` / `proj-governance-reco` / `proj-invite-builders`). R19 ([ADR 0237](<redacted>.md)) declared the per-type starter bundle and said outright it is "a declaration and not a rule engine — R17/R22 own the layer that reasons"; this is that layer, and the goal pins it **rule-based**, with the AI/embeddings pass deferred ([task 1003500](https://cloudbongos.com/builders#/task/1003500), idea 1000552). **Two inputs, and the free-text description is not one of them:** the DECLARED `type` (a column) and `team_shape` (the one closed-answer key the R15 interview collects, [task 1002334](https://cloudbongos.com/builders#/task/1002334)) — inferring from prose is the deferred layer ADR 0237 §7 already rejected once. The engine is three frozen tables (`TEAM_SHAPE_RULES` add/remove ONE opt-in module; `GOVERNANCE_RULES` name a preset; `INVITE_RULES` emit a seek) and **every row carries its own `reason` sentence**, shipped with the effect rather than reconstructed by whichever surface renders it — a recommendation an owner cannot be told the reason for is one they cannot disagree with. `bundle.adjustments` is a **DELTA**: a rule whose condition matched but whose module the bundle already carried records NOTHING, because "we switched discord on because you said community" over a module a game would have had anyway is a claim the owner can check and find false. **Governance is a named preview, never a setting** — the governance module is planned and unbuilt (goal 1000030), so a preset is a name plus one sentence of what it feels like (`owner-only` / `trusted-team` / `open-contribution`) and every result carries `applied: false`, one flag instead of the same fact hardcoded in R25, R18, the wizard and the project page. **Invites are a SEAM**: `suggested` is always `[]` because ranking builders means querying the leaderboard in the sibling `economy` module, which the one-way rule ([ADR 0083](<redacted>.md)) forbids importing — the engine emits `seeking: { kind: 'top-builders', limit }` (or `null` = suggest nobody, a real answer) and R28 ([task 1002347](https://cloudbongos.com/builders#/task/1002347)) turns it into names. **Skipping is an answer:** every table states a default and each is the NARROWEST option (widening later costs one setting; a role granted to strangers is not recovered by setting it back), an off-vocabulary `team_shape` reads as no answer exactly as `normalizeProjectDetail` drops it, and the route answers 200-with-defaults rather than 400 — refusing would make the supported path ([ADR 0182](<redacted>.md) D4) an error. `tailored: boolean` is the machine-readable half of `proj-detail-interview`'s details-vs-skip split that R18 ([task 1002337](https://cloudbongos.com/builders#/task/1002337)) proves. Served at public `GET /provisioning/recommendations?type=&team_shape=` (same absent gate as `starter-bundles`; no database, pinned by a `pool`-throws stub), returning ADR 0237 §5's bundle shape plus `adjustments` so a recommendation and R20's preselect can never name different modules. Rejected: reading the description, filling `suggested` from `GET /public/leaderboard`, a weighted scoring function, a reason per matched condition, and a 400 on an unknown shape.](<redacted>.md) | provisioning / project creation |
 | 0240 | [**A skipped module picker stores nothing, and the bundle is resolved on read** ([task 1002339](https://cloudbongos.com/builders#/task/1002339) · goal 1000046, criterion `proj-module-select`). [ADR 0237](<redacted>.md) declared the starter bundles and closed with "where a chosen selection lands is R20's decision". It lands in a new **nullable** `modules jsonb` column on `provisioning_instances` (`provisioning_014`), read through `starter-bundles.effectiveModules(row)` and **three-valued**: `NULL` = nobody answered (the picker was skipped, or the caller does not ask) and the declared type's bundle is resolved AT READ TIME; `[]` = the owner switched them all off, a real answer; `["dev-box",…]` = what they picked. `NOT NULL DEFAULT '[]'` was rejected because it collapses the first two forever — the `PROJECT_DETAIL_VOCAB` rule ("absent stays absent, skipped stays skipped") applied to a list. **Skipping is safe because the preselect and the fallback are the same function**, `bundleForProjectType`, called twice — not two lists kept in agreement — so `bongos onboard` and any API caller inherit the bundle by omitting the field, and the canonical sequence in `onboard-plan.js` grows **no new step** (the picker refines `type`, an answer already in it). NOT `detail` (its vocabulary is closed + scalar by construction, and [ADR 0237](<redacted>.md) §2 ruled the interview must not ask this) and NOT `settings` (a setting is a policy the RUNNING instance obeys — web.env, a settings-apply intent, a restart). The picker's catalog copy (`OPTIONAL_MODULES`) is **declared beside the bundles**, because `module.json` descriptions are written for builders, `GET /modules` needs a session the signed-out wizard has not got, and `GET /public/modules` serves booleans — pinned the ADR 0237 way, so a new `default: false` module cannot ship without owner-facing copy. `GET /provisioning/starter-bundles` gains `optional` so the preselect and the catalog arrive in **one** read. The route **refuses** an unknown / always-on / hub-only key (`400 bad_modules`) rather than dropping it silently (`badProjectDetail`'s rule), and a re-request reports `modules_ignored`. The column is a DECLARATION, not yet an input to the control-plane runner. Rejected: storing the preselect on a skip (it writes down an answer nobody gave), a new `onboardPlan` step, and rendering the always-on core as sixteen disabled toggles (a disabled control reads as a choice the owner failed to make).](<redacted>.md) | provisioning / project creation |
 | 0241 | [**The artist gate holds the DEPLOY, not the ship, and it reads a state rather than a judgement** ([task 1003116](https://cloudbongos.com/builders#/task/1003116) · goal 1000074, criterion `artist-blocking-is-per-project` — R05, the DECISION task the goal placed before R04 so no code would be wired to an unsettled gate). Goal 1000074 carries two rules on a collision course: the owner's "blocking strictness is PER PROJECT, not global", and [ADR 0162](<redacted>.md), which retired review gates on `main` after a code-owner requirement stranded two graded-PASS ships in a day. **0162 is usually cited by a paraphrase — "a verdict is advisory, never self-executing" — and the paraphrase is wrong as a blanket claim:** 0162's own table of compensating controls marks three of four as *fails closed*, the subagent grader among them. What it actually retired was a gate GitHub could only express as ACCOUNTS — identity-pinned against [ADR 0016](<redacted>.md), and stranding with no escape hatch. So the surviving test is: **a gate is admissible when it is evaluated automatically from readable state, consistently for every builder, with a named escape hatch; inadmissible when a particular person must act and it stalls when they do not.** Decision: (1) the gate reads a **STATE** — "is there an unresolved artist review task?" — never an opinion, so the artist's judgement is what they write INTO the task and stays advisory in exactly 0162's sense, while what the system reads is ordinary GDS status; (2) strictness is a project setting `artist_gate ∈ off | advisory | strict` and at `strict` it holds the **DEPLOY, not the ship** (owner ruling) — the builder's work is graded, merged, credited and landed on CI alone exactly as today, so 0162's strand class cannot recur, and the gate attaches to the boundary the artist's ABI mandate is actually about (users see the deployed instance, not `main`; [ADR 0137](<redacted>.md) already splits land/release/deploy); (3) the escape hatch is the **project OWNER only** — not the builder, not any Metic+, not the artist — via the existing `POST /tasks/:id/override-request`, because a person can be both artist and builder and could pass their own work; a self-release is permitted but never quiet (required rationale, audit-logged as a self-override) so a solo instance cannot deadlock; (4) the default is **`strict`** (owner ruling, against the author's `advisory` recommendation), which is safe only because §2 holds the deploy — the worst case is a pin that waits, and this instance is included once R04 ships; a project with no artist must still be able to deploy, and the refusal must name what holds it and which control releases it; (5) tightening is **not retroactive** — re-gating history would strand the next deploy behind reviews for work nobody remembers and make the setting frightening to raise; R02's flag queue is the right tool for already-shipped copy. Rejected: blocking the ship (recreates 0162's incident exactly, with credits unpaid — [ADR 0120](<redacted>.md)); advisory at every level (configures nothing); any Metic+ as the hatch (makes `strict` indistinguishable from `advisory`); making the artist's VERDICT the gate (the one thing 0162 genuinely forbids); retroactive tightening; a global constant (ruled out by the owner's constraint by name).](<redacted>.md) | goal 1000074 / the artist's loop |
+| 0242 | [**A cross-role cascade is a declaration table on the event that already exists** ([task 1003549](https://cloudbongos.com/builders#/task/1003549) · goal 1000074, criterion `artist-review-task-on-ship` — the split R04 invited in its own brief and [ADR 0241](<redacted>.md)'s dependency). R04 needs "every ship with copy or visuals GENERATES one", and its brief said the infrastructure did not exist, naming the spark queue as the prototype. Reading both surfaces shows the prototype is the wrong half: the spark queue ([task 1002921](https://cloudbongos.com/builders#/task/1002921)) and the copy-desk flag queue ([task 1003113](https://cloudbongos.com/builders#/task/1003113)) are both **PULL** — filtered listings of rows another role already created — and nothing anywhere generated work on a state transition, which is the **PUSH** R04 asks for. (`cascade-dispatch.js` is model-cost routing; named only because its name has misled more than one reader.) **Decision: no new bus.** The kernel seam registry's own header uses this exact scenario as its worked example, `task.shipped` is already emitted post-commit by both ship paths and already has two consumers (discord's broadcast, sessions' deferred reward) — so a cascade is ONE MORE LISTENER on it, registered in `routes/lifecycle.js` beside the port because that mount is the one boot hook tests also run. A cascade is a frozen entry `{ key, discipline, when(task), title(task), body(task) }` — **a declaration table, not a rules engine**: no condition language, no stored rules, no per-project config, no priority ordering; adding one appends an entry and the runner does not change (the [ADR 0237](<redacted>.md)/[0239](<redacted>.md) shape, for their reason — the generalisations worth building are the ones two or three real entries have shown they share). **`CASCADES` ships EMPTY and R04 writes the first rule**, asserted so the emptiness is a decision on the record; the mechanism is proved against the tests' own declarations rather than against its first consumer's shape. Four load-bearing properties, all pinned: (1) **it can never fail the ship it reacts to** — post-commit event, isolated listeners, and a runner that catches everything and returns a report, because ADR 0241 settled that an artist may hold a DEPLOY and never a builder's SHIP and a generator that could fail a ship would smuggle that gate back in; verified against a real failure (no database reachable → one log line, resolves); (2) **idempotent on machinery that already exists** — `source: 'cascade'` + `source_ref: cascade-<key>-<taskId>` through `createTask`'s `(source, source_ref)` read, the same one a copy proposal uses ([ADR 0233](<redacted>.md)), so a reconciler re-sweep or a double emit is a no-op; (3) **it says where it came from** — inherits `goal_id`/`version_id`, carries the origin id in the ref and the prose, but NOT `parent_task_id`, which models a SUBTASK, and cascaded work is not part of the ship that triggered it; (4) **files at `backlog`, never `ready`** — generated work is a request, and auto-filing claimable work would let a rule nobody re-read mint claims. A rule key is PERMANENT (half the source_ref; renaming re-files everything it ever generated), pinned by a duplicate-key check. The mechanism is discipline-agnostic — an ideator or engineer cascade is the same entry with a different `discipline`, which is the generalisation that made this its own task. Accepted limit: cascades are declared in code, not configured per project. Rejected: extending the spark queue (a read-side filter that generates nothing), a new event or poller, a rules engine or per-project config, filing at `ready`, `parent_task_id` as the link, and running the cascade inside the ship transaction (which would make a generation failure a ship failure — the exact coupling ADR 0241 rules out).](<redacted>.md) | goal 1000074 / the artist's loop |
 
 > ⚠️ **Numbering collisions are now machine-enforced, not narrated.** Twenty numbers are shared by two ADRs each — assigned in parallel sessions before anything checked. The files keep their filenames (renumbering would break every existing citation, and a number once assigned is never reused), and this table disambiguates each pair as `NNNN-a` / `NNNN-b`. The authoritative list is `LEGACY_DUPLICATE_ADRS` in [`scripts/gds/adr-namespace.js`](../../scripts/gds/adr-namespace.js), frozen by exact filename: a **new** collision — or a third file joining a legacy number, or a rename of either half — hard-fails the `unit` CI gate, as does an index row that points at no file or an ADR with no row. The list may only shrink. This paragraph used to narrate the collisions one by one and had fallen eight behind reality; see [ADR 0195](<redacted>.md) for why the check exists and why the pairs are grandfathered rather than renumbered.

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

@@ -1487,5 +1487,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.523 with no explicit bump. run 33818285201. (task 1002620)
   1.19.525 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         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)
 ---------------------------------------------------------------------------
 ```

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/lifecycle/cascade.js

@@ -0,0 +1,238 @@
+'use strict';
+
+// modules/lifecycle/cascade.js — a ship in one role GENERATES work in another
+// (task 1003549, goal 1000074's the artist's loop; the split R04 asked for).
+//
+// WHAT WAS MISSING, precisely — the gap is PUSH vs PULL. Two surfaces already
+// let one role take work from another, and both are LISTINGS of rows somebody
+// had already created: the spark queue (goal 1000062 / task 1002921) returns
+// open sparks awaiting development, and the copy-desk flag queue (R02 / task
+// 1003113) returns surfaces anyone flagged. A role could READ what another
+// produced; nothing GENERATED work on a state transition. R04's requirement is
+// the other direction — "every ship with copy or visuals generates one [review
+// task]", automatic, never hand-filed — and there was no mechanism for it.
+//
+// WHAT THIS IS, AND WHAT IT DELIBERATELY IS NOT. It is a DECLARATION TABLE plus
+// a runner, not a rules engine. A cascade is one frozen entry saying: when a
+// shipped task looks like THIS, file THAT task, for THAT discipline. There is no
+// condition language, no stored rules, no per-project configuration and no UI —
+// every one of those is a thing to add when a second and third cascade exist and
+// have shown what they have in common. Today `CASCADES` ships EMPTY: the
+// mechanism, its idempotency and its non-blocking property are proved by the
+// tests' own declarations, and R04 (task 1003115) writes the first production
+// entry. A mechanism whose first real rule is written by the task that needs it
+// is honest; one that ships a rule nobody asked for is a guess.
+//
+// THE FOUR PROPERTIES THAT MAKE IT SAFE, each of which the tests pin:
+//
+//   1. IT NEVER BLOCKS THE SHIP IT REACTS TO. The runner is driven by the
+//      `task.shipped` kernel event, which fires POST-COMMIT and whose emitters
+//      already wrap it in try/catch; on top of that `runCascadesForShip` catches
+//      everything and returns a report. A cascade that throws, or a database
+//      that is down, changes nothing about the ship — the work is landed, graded
+//      and paid before this code runs at all. This is not a nicety: ADR 0241
+//      settled that an artist's review may hold a DEPLOY and never a builder's
+//      ship, and a generator that could fail a ship would smuggle that gate back
+//      in through the back door.
+//
+//   2. IT IS IDEMPOTENT, using machinery that already exists. Each generated
+//      task carries `source: 'cascade'` and `source_ref: cascade-<key>-<id>`,
+//      and `createTask`'s (source, source_ref) idempotency read returns the
+//      original row instead of minting a second one. So a reconciler re-sweep, a
+//      re-ship, or both emitters firing for the same task are no-ops. The
+//      runner ALSO checks first, so the common case is a read rather than a
+//      write that gets rejected.
+//
+//   3. IT SAYS WHERE IT CAME FROM. Every generated task inherits the source
+//      task's `goal_id` and `version_id`, carries the originating task's id
+//      inside its `source_ref`, and opens its description with that id and the
+//      rule key. A task that appears on the board with no author has to be able
+//      to explain itself, or the next person deletes it. NOT `parent_task_id`:
+//      that column models a SUBTASK, and cascaded work is not a part of the ship
+//      that triggered it — it is separate work, for a different role, that
+//      outlives its trigger. The attribution belongs in the ref and the prose.
+//
+//   4. IT FILES AT `backlog`, NEVER `ready`. Generated work is a REQUEST, and
+//      it goes through the board's ordinary triage like a copy proposal (ADR
+//      0233 §6) or any capture. Auto-filing claimable work would let a rule
+//      nobody re-read mint claims.
+//
+// PURE ABOVE `runCascadesForShip`: the declaration shape, the matching and the
+// task spec are all synchronous functions over plain objects, so a cascade can
+// be pinned without a database.
+
+// ---------------------------------------------------------------------------
+// The declaration
+// ---------------------------------------------------------------------------
+
+// A cascade rule:
+//   key         string, stable + unique. It is half the source_ref, so RENAMING
+//               a key re-files every task the rule ever generated. Treat it as
+//               permanent.
+//   discipline  the role the generated work is FOR ('artist', 'ideator',
+//               'engineer'). This is the whole point of the mechanism: the
+//               discipline of the generated task is not the discipline of the
+//               ship that caused it.
+//   when(task)  a predicate over the shipped task row. Must be pure and total —
+//               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'.
+//
+// Production rules live here. It is empty by design — see the header.
+const CASCADES = Object.freeze([]);
+
+// 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
+// it to one rule and one originating ship.
+const CASCADE_SOURCE = 'cascade';
+
+function cascadeSourceRef(ruleKey, sourceTaskId) {
+  return `cascade-${ruleKey}-${sourceTaskId}`;
+}
+
+// Validate a declaration at the moment it is used rather than trusting it. A
+// malformed rule is a wiring bug that should be loud in a test, not a silent
+// missing task in production six weeks later.
+function assertRuleShape(rule) {
+  const problems = [];
+  if (!rule || typeof rule !== 'object') return ['rule is not an object'];
+  if (typeof rule.key !== 'string' || !rule.key) problems.push('key must be a non-empty string');
+  if (typeof rule.discipline !== 'string' || !rule.discipline) problems.push('discipline must be a non-empty string');
+  if (typeof rule.when !== 'function') problems.push('when must be a function');
+  if (typeof rule.title !== 'function') problems.push('title must be a function');
+  if (typeof rule.body !== 'function') problems.push('body must be a function');
+  return problems;
+}
+
+// Every rule in a table, checked, with duplicate keys reported — two rules
+// sharing a key would collide on source_ref and silently suppress one another.
+function validateCascades(rules = CASCADES) {
+  const errors = [];
+  const seen = new Set();
+  rules.forEach((rule, i) => {
+    for (const p of assertRuleShape(rule)) errors.push(`cascade[${i}]: ${p}`);
+    const key = rule && rule.key;
+    if (typeof key === 'string' && key) {
+      if (seen.has(key)) errors.push(`cascade[${i}]: duplicate key "${key}" — keys are half the source_ref and must be unique`);
+      seen.add(key);
+    }
+  });
+  return errors;
+}
+
+// ---------------------------------------------------------------------------
+// Matching + the generated task spec
+// ---------------------------------------------------------------------------
+
+// The task rows a shipped task cascades into. Pure: no database, no clock, no
+// side effect — hand it a task-shaped object and a rule table and it returns
+// the specs that would be filed.
+//
+// A rule whose `when` THROWS is treated as no-match and reported in `errors`,
+// never propagated: one broken predicate must not cost the other rules their
+// tasks, and it certainly must not reach the ship.
+function cascadesFor(task, rules = CASCADES) {
+  const matched = [];
+  const errors = [];
+  if (!task || task.id == null) return { matched, errors: ['no task'] };
+  for (const rule of rules) {
+    const shape = assertRuleShape(rule);
+    if (shape.length) { errors.push(`cascade "${rule && rule.key}": ${shape.join('; ')}`); continue; }
+    let hit = false;
+    try {
+      hit = rule.when(task) === true;
+    } catch (e) {
+      errors.push(`cascade "${rule.key}": when() threw (${e && e.message}) — treated as no match`);
+      continue;
+    }
+    if (!hit) continue;
+    try {
+      matched.push({ rule, spec: cascadeTaskSpec(rule, task) });
+    } catch (e) {
+      errors.push(`cascade "${rule.key}": title/body threw (${e && e.message})`);
+    }
+  }
+  return { matched, errors };
+}
+
+// The createTask payload for one matched rule. The attribution preamble is
+// prepended here rather than left to each rule, so no rule can forget it.
+function cascadeTaskSpec(rule, task) {
+  const body = String(rule.body(task) || '').trim();
+  const preamble =
+    `Filed automatically when task ${task.id} shipped — the "${rule.key}" cascade `
+    + `(modules/lifecycle/cascade.js). Nobody typed this; it is a REQUEST, filed at backlog, `
+    + `and it goes through the board's ordinary triage. If the rule that made it is wrong, fix `
+    + `the rule rather than only this task.`;
+  return {
+    versionId: task.version_id,
+    goalId: task.goal_id != null ? Number(task.goal_id) : null,
+    title: String(rule.title(task) || '').trim(),
+    description: `${preamble}\n\n${body}`,
+    discipline: rule.discipline,
+    kind: rule.kind || 'chore',
+    status: 'backlog',
+    source: CASCADE_SOURCE,
+    sourceRef: cascadeSourceRef(rule.key, task.id),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// The runner — the only part that touches a database
+// ---------------------------------------------------------------------------
+
+// React to one shipped task. Returns a report, NEVER throws and never rejects:
+// property 1 in the header. `deps` is injected so the whole runner is testable
+// with two stubs and no database.
+//
+//   deps.getTask(id)                 -> the full task row (the event payload is
+//                                       the ship RETURNING row and carries no
+//                                       goal_id / version_id / discipline)
+//   deps.findTaskBySourceRef({...})  -> an existing row or null
+//   deps.createTask(spec)            -> the created row
+//   deps.log                         -> optional { info, error }
+async function runCascadesForShip(shipped, deps = {}) {
+  const report = { created: [], skipped: [], errors: [] };
+  const log = deps.log || null;
+  try {
+    const id = shipped && (shipped.id ?? shipped.task_id);
+    if (id == null) { report.errors.push('cascade: ship payload carried no task id'); return report; }
+
+    const task = deps.getTask ? await deps.getTask(id) : null;
+    if (!task) { report.errors.push(`cascade: task ${id} not readable after ship`); return report; }
+
+    const { matched, errors } = cascadesFor(task, deps.rules || CASCADES);
+    report.errors.push(...errors);
+
+    for (const { rule, spec } of matched) {
+      try {
+        const existing = deps.findTaskBySourceRef
+          ? await deps.findTaskBySourceRef({ source: CASCADE_SOURCE, sourceRef: spec.sourceRef })
+          : null;
+        if (existing) { report.skipped.push({ key: rule.key, taskId: existing.id, reason: 'already filed' }); continue; }
+        const created = await deps.createTask(spec);
+        report.created.push({ key: rule.key, taskId: created && created.id, discipline: rule.discipline });
+        log?.info?.(`[cascade] task ${id} shipped → filed ${created && created.id} for ${rule.discipline} ("${rule.key}")`);
+      } catch (e) {
+        // One rule failing costs that rule its task and nothing else.
+        report.errors.push(`cascade "${rule.key}": ${e && e.message}`);
+      }
+    }
+  } catch (e) {
+    report.errors.push(`cascade: ${e && e.message}`);
+  }
+  if (report.errors.length) log?.error?.(`[cascade] ${report.errors.length} problem(s): ${report.errors.join(' | ')}`);
+  return report;
+}
+
+module.exports = {
+  CASCADES,
+  CASCADE_SOURCE,
+  cascadeSourceRef,
+  assertRuleShape,
+  validateCascades,
+  cascadesFor,
+  cascadeTaskSpec,
+  runCascadesForShip,
+};