@bongos/core 1.17.0

package/docs/adr/0012-ground-object-cell-split.md

@@ -0,0 +1,208 @@
+# 0012 — Ground-object cell split: terrain becomes ground + sparse object layer
+
+- **Status:** Accepted
+- **Date:** 2026-05-09
+- **Deciders:** Lars
+- **Supersedes (in part):** [ADR 0011](./0011-terrain-id-rendering-model.md) — extends its data model; the dispatched render-strategies architecture stays valid.
+
+## Context
+
+[ADR 0011](./0011-terrain-id-rendering-model.md) established that each
+map cell stores a TERRAIN id and the renderer dispatches per terrain to
+a render strategy (`single` / `blob47` / `path16`). It worked, but the
+first browser session uncovered a structural bug: the V1 top band has
+GRASS, SAND, and ROCK randomly intermixed (1/11 rock, 3/11 sand,
+7/11 grass), and the autotile picker — which checks `n === my` for
+each neighbor — treated rocks and sand as "different from grass" the
+same way. Every grass cell with a rock neighbor rendered a boundary
+tile, even though a rock isn't a kind of land — it's a thing sitting
+on land. The result was a marble-flagstone appearance instead of the
+intended meadow.
+
+A scoped fix (per-terrain `interiorEquivalents` to mark "rocks count
+as same-as-grass for the picker," option B in the scoping note) would
+have removed the artifact in ~12 LOC. We chose to pay down the deeper
+debt instead, because:
+
+1. The wider problem is conflation: a single terrain id at every cell
+   tries to mean both "what's the visual surface here" AND "what's
+   blocking movement here." That conflation breaks at any cell whose
+   surface differs from its overlay (rocks on grass, containers on
+   sand, future trees / fences / signs / item drops on whatever).
+2. The world is about to grow. Doing the architectural split now,
+   while the map is small and entirely procedural, costs ~2 hours.
+   Doing it later, after we've baked the assumption into level data,
+   gameplay events, and persistence, costs much more.
+3. Industry-standard tile renderers (Tiled, RPG Maker, FireRed itself)
+   separate ground tiles from object overlays. Aligning with that
+   convention makes future contributions cheaper.
+
+## Decision
+
+Each cell carries TWO independent pieces of data:
+
+- **Ground terrain** — always defined. Drives the autotile renderer.
+  Walkable unless declared in `BLOCKING_TERRAINS`. The set is small
+  and stable: `GRASS`, `SAND`, `SEA`, `MARBLE_PATH`. Future additions
+  are alternative ground types.
+- **Object** — optional (zero or one per cell in V1; lists in V2 if
+  needed). Painted in a second draw pass at depth 1. May block
+  movement (`BLOCKING_OBJECTS`). Currently: `ROCK` plus the 8
+  `CONTAINER_PANEL_*` ids that compose the shipping container.
+
+`INITIAL_MAP` exports `{ ground, objects }` — two parallel 2D arrays.
+Both client (`public/game/world/map.js`) and server (`src/world/map.js`)
+build them with identical logic. The shape is JSON-serializable for
+the eventual move to a Postgres-backed map.
+
+The autotile picker (`pickAutotileIndex` in
+[`public/game/world/terrain.js`](../../public/game/world/terrain.js))
+takes the ground grid only. Objects never enter its view. That is the
+core invariant that fixes the marble-flagstone artifact: a grass cell
+with a rock object on top is, to the picker, just a grass cell — its
+neighbors are ground terrains too, and only sand neighbors at the
+y=6 transition trigger the autotile boundary tile.
+
+### Render pipeline
+
+`WorldScene.drawMap(map)` runs two passes:
+
+1. **Ground pass.** For every cell, paint
+   `pickGroundTextureKey(scene, map.ground, x, y)` at depth 0. Uses the
+   autotile dispatch from ADR 0011.
+2. **Object pass.** For every cell where `map.objects[y][x]`, paint
+   `pickObjectTextureKey(scene, map.objects, x, y)` at depth 1. Single-
+   tile per object id; no autotile dispatch on the object layer.
+
+Vendor and player sprites continue to live at higher depths (8 and 10
+respectively) above objects. The vendor at (13, 9) sits visually atop
+the door panel object, exactly as before.
+
+### Walkability
+
+`isBlocked(x, y)`:
+```
+out-of-bounds              → blocked
+ground in BLOCKING_TERRAINS  → blocked   (SEA only, in V1)
+object in BLOCKING_OBJECTS   → blocked   (ROCK + 8 container panels, in V1)
+otherwise                    → walkable
+```
+
+Server (`src/world/map.js`) is the source of truth for movement
+validation. Client honors the same rule for prediction. Both read from
+the same shared `terrain.js` enums + sets. Tests in
+[`tests/walkability.mjs`](../../tests/walkability.mjs) exercise the
+server module directly to guard against drift.
+
+### Asset implications
+
+- `rock_small.png` (AI-generated, currently RGB no-alpha): renders
+  opaquely on top of the ground autotile. Acceptable for V1 — the rock
+  visually fills its cell, identical to the pre-split look. The win
+  is in the surrounding GRASS cells, which now render smooth meadow
+  instead of marble-flagstone borders. Future polish: regenerate with
+  magenta-key transparent BG so the autotiled grass shows through at
+  the rock's corners (~$0.04). Not blocking V1.
+- The procedural rock fallback in [`tilePalette.js`](../../public/game/world/tilePalette.js)
+  was updated to drop its grass-green BG fillRect — the canvas is
+  transparent by default, so the procedural rock now correctly shows
+  the underlying ground at corners.
+- Container panels: stay opaque. The container is a solid building
+  covering its 8 cells of sand. Opaque is correct.
+
+### Cross-verify safety
+
+The Python↔JS autotile lookup table cross-verifier
+([`tests/autotile_xverify.mjs`](../../tests/autotile_xverify.mjs))
+tests `selectBlob47` / `selectPath16` directly — unchanged by this
+ADR. Picker behavior change is captured in the new
+[`tests/terrain_picker.mjs`](../../tests/terrain_picker.mjs), which
+asserts the ground-only invariant.
+
+## Consequences
+
+### Positive
+
+- **The marble-flagstone bug is gone by construction.** The picker
+  cannot see objects, so rocks (and any future overlays) cannot
+  pollute boundary tile selection.
+- **Clean walkability.** Movement rules read like the intent: "is the
+  ground impassable, OR is the object impassable?" No more entanglement
+  between visual identity and blocking.
+- **Future objects are nearly free.** Trees, signs, fences, item
+  drops, multi-tile structures all slot in as new `OBJECT` enum
+  entries + manifest tile + (if blocking) `BLOCKING_OBJECTS` entry.
+  No renderer changes per addition.
+- **Container scales.** Adding a second container, a market stall, a
+  multi-cell tent — all just place more object-cell sets. The picker
+  paints clean ground around each.
+- **Persistence-ready data shape.** `objects[y][x]` maps directly to
+  a `(x, y, object_id)` table when player-placed objects need to
+  persist. `ground[y][x]` maps to a separate ground table that
+  rarely changes.
+- **Aligned with industry convention.** Tiled, RPG Maker, FireRed all
+  use ground + object layers. Future contributors recognize the model.
+
+### Negative / costs
+
+- **Two-file mirror tax doubles** — now `terrain.js` AND `map.js` each
+  exist as CJS server + ESM client twins (4 files). Same fix as before:
+  consolidate when the world becomes data-driven from Postgres.
+- **Container is 8 distinct object ids** rather than an anchor + 2×4
+  footprint. Per-cell is simpler for V1; anchor-based becomes
+  attractive when we have many multi-tile structures (V2+).
+- **Z-order between objects is V1-flat** — every object renders at
+  depth 1. A future "tall object in front of player" effect needs
+  per-object depth-sort by `(y + footprint_height)`. Not urgent.
+- **Per-cell object limit is one** in V1. A flower next to a sign in
+  the same cell would need `objects[y][x]: string[]`. Trivial to lift
+  when needed.
+
+### What this does not change
+
+- ADR 0011's dispatched render strategies (`single` / `blob47` /
+  `path16`) are unchanged. They now operate on the GROUND grid only.
+- The autotile pipeline (ADR 0009) and the family pipeline (ADR 0008)
+  are unchanged. Container panels are still generated by the family
+  pipeline; their PNGs are interpreted as object overlays now.
+- Vendor placement, dialog, interact semantics: unchanged. The vendor
+  at (13, 9) still occupies the door cell. The cell is still blocked
+  (now via object-blocking, was previously via terrain-blocking).
+- The hardcoded V1 map geometry: unchanged. The container is still 4
+  wide × 2 tall at anchor (13, 8); rocks scatter on the same noise
+  function.
+- Cost ledger and budget rules: unchanged.
+
+## Migration path
+
+Single commit, atomic switch. Server and client move together. The
+`players` table has no terrain references (only x/y/facing); the
+`world_events` table has no terrain references in payloads; nothing
+external needs migrating. The Colyseus smoke tests in `/tmp/colyseus-*`
+still validate movement against the same `isBlocked()` API surface.
+
+## Testing
+
+- [`tests/terrain_picker.mjs`](../../tests/terrain_picker.mjs) (10
+  cases) — picker dispatch shape, neighbor lookup, ground-only
+  invariant, path16 sanity (lone node = 0; cross junction = 15).
+- [`tests/walkability.mjs`](../../tests/walkability.mjs) (13 cases) —
+  enum sanity, isBlocking{Terrain,Object}, isBlocked over the actual
+  INITIAL_MAP for sea / sand / grass / rock-on-grass / all 8 container
+  cells / vendor cell / cell south of vendor / out-of-bounds.
+- Both wired into `art/pipeline/smoke_test.sh` step 3b. The smoke test
+  fails the build if either test fails.
+
+## Future work this enables
+
+- **Trees** (decorative, blocking): one OBJECT entry + tile.
+- **Signs** (interactive, blocking, dialog payload): OBJECT entry +
+  tile + a small `INTERACTIONS` map keyed by `(x, y)` consumed by
+  `WorldScene.handleInteract`.
+- **Item drops** (non-blocking, pickable): OBJECT entry + tile,
+  exclude from `BLOCKING_OBJECTS`. Pickup is a server event that
+  mutates `objects[y][x] = null` and broadcasts.
+- **Multiple buildings / placed objects**: just place more
+  object-cell sets. Ground autotile renders cleanly around them.
+- **Persistent player-placed objects**: `objects` grid is the natural
+  persistence shape (`(x, y, object_id)`).

package/docs/adr/0013-paths-as-object-overlays-with-autotile-dispatch.md

@@ -0,0 +1,158 @@
+# 0013 — Paths as object overlays with autotile dispatch
+
+- **Status:** Accepted
+- **Date:** 2026-05-10
+- **Deciders:** Lars
+- **Extends:** [ADR 0012](./<redacted>.md) (cell model), [ADR 0011](./0011-terrain-id-rendering-model.md) (render dispatch), [ADR 0009](./0009-autotile-architecture.md) (autotile families)
+
+## Context
+
+The V1 world places a marble flagstone path running 4 cells north-to-south
+through the sand band (cells `(13, 10..13)`). Up until now the path was
+declared as a **ground terrain** (`TERRAIN.MARBLE_PATH`) with a `path16`
+render strategy. The `marble_path` autotile family was generated with
+three primitives: `path_terrain` (the surrounding ground texture), `path_node`
+(centered marble cluster), and `path_arm_N` (vertical strip of marble).
+Each composed tile was an opaque RGB image — the path arms and node
+pasted onto a `path_terrain` background that filled the whole 32×32.
+
+That model has two structural problems:
+
+1. **Terrain mismatch.** The composed path tiles include their own
+   `path_terrain` margins. The V1 world places the path over `SAND`, but
+   the family was designed for paths through grass (per the prompt). The
+   path tiles' margins read as grass, the surrounding world ground reads
+   as sand → visible color discontinuity at every path cell's edge,
+   which Lars correctly described as "visible gaps showing through."
+2. **Combinatorial family explosion.** If V2 adds paths that run through
+   grass *and* paths through marble plazas *and* paths through cobble,
+   each pairing needs its own family — `marble_path_on_sand`,
+   `marble_path_on_grass`, etc. The number of families is `paths × grounds`,
+   which doesn't scale.
+
+ADR 0012's whole point was that **objects are overlays on top of ground**,
+free from polluting ground rendering. That model fits paths perfectly —
+a path is a thing you walk on top of the ground, not a kind of ground.
+But ADR 0012 limited objects to single-tile rendering, which doesn't
+support the autotile dispatch a path needs to pick the right
+straight/junction/end-cap tile based on its neighbors.
+
+## Decision
+
+**Paths become objects with autotile dispatch.** Specifically:
+
+- A new object id `OBJECT.PATH_MARBLE` (declared on the OBJECT enum,
+  added to neither `BLOCKING_OBJECTS` nor `BLOCKING_TERRAINS` — a path is
+  walkable). The world places the path on the **objects** layer; the
+  ground at those cells is `SAND` (just like the surrounding cells).
+- `OBJECT_RENDER` extends from `{ tile }` only to the same dispatch
+  shape that `TERRAIN_RENDER` already supports:
+  `{ strategy: 'single' | 'path16' | 'blob47', family, fallbackTile }`.
+  Single-tile is preserved for back-compat (legacy short-form `{ tile }`
+  still accepted, normalized internally).
+- A new `pickObjectAutotileIndex(object, neighbors)` mirrors the existing
+  `pickAutotileIndex(terrain, neighbors)` — same dispatch logic, looks up
+  in `OBJECT_RENDER` instead of `TERRAIN_RENDER`. The picker queries the
+  **objects** grid for neighbors of the same object id. (`neighborsAt`
+  itself is unchanged — already generic over any 2D grid.)
+- The `marble_path` autotile family drops the `path_terrain` primitive
+  entirely. Its tiles are now produced as **RGBA with alpha-keyed
+  backgrounds**: the marble flagstones are opaque, everything else is
+  transparent. The world's ground tile is painted first (depth 0); the
+  path tile renders on top (depth 1). The surrounding sand-or-grass-or-
+  whatever shows through wherever the marble doesn't cover.
+- A new `kind='alpha_tile'` in `post_process.process()` does explicit
+  magenta-key transparency removal *before* palette quantization (the
+  locked palette doesn't contain pure `#FF00FF`, so magenta would
+  otherwise palette-snap to a near-purple and dodge the threshold). The
+  autotile orchestrator routes primitives with `transparent_bg: true`
+  to this kind.
+- `compose_path16` in `autotile_compositor.py` defaults to a transparent
+  RGBA canvas when no `terrain` primitive is present. Legacy families
+  that still ship a terrain primitive get the old opaque behavior.
+- `family_checks.color_profile_check` masks alpha=0 pixels out of the
+  in-range fraction so transparent regions don't skew the score.
+
+The runtime renderer is unchanged in shape: `WorldScene.drawMap` still
+does ground pass + object pass. Phaser's `add.image` blits RGBA natively;
+the alpha pixels just don't paint over the ground that's already there.
+
+## Consequences
+
+**Paths are now terrain-agnostic.** The same `marble_path` family works
+over sand, grass, marble plazas, and any future ground. The V1 world's
+path strip renders correctly — sand shows through where the marble
+doesn't cover, no gaps, no color mismatch.
+
+**Object-layer autotile dispatch is now a first-class pattern.** Future
+linear or regional overlays (fences, low walls, rivers, trails, footpaths
+in dirt, bridges, vine borders) reuse this without further architectural
+work. Pick `path16` for line connections, `blob47` for region overlays.
+
+**The cell model stays at two layers.** This is *not* a layer-count
+expansion. Ground is the always-defined surface; object is the optional
+overlay. Both layers can autotile-dispatch — the dispatch generalizes,
+not the cell shape.
+
+**`MARBLE_PATH` ground terrain is now vestigial.** It's declared and its
+`TERRAIN_RENDER` entry remains for back-compat, but `INITIAL_MAP` no
+longer places it. A future cleanup task can remove the enum entry once
+no other code references it; not urgent.
+
+**The walkability test grew by 1 case** (the path strip is walkable
+across all 4 cells) and the existing `(13, 10) is sand` assertion
+loosened to require `ground = SAND, object = PATH_MARBLE` instead of
+`ground = MARBLE_PATH, object = null`. `terrain_picker.mjs` gained 4
+cases covering object-layer autotile dispatch — including the
+**OBJECT-LAYER AUTOTILE INVARIANT** mirror of ADR 0012's ground invariant
+(object autotile sees only the object grid; ground never affects it).
+
+**Alpha rendering has a known generation cost.** Each new alpha-keyed
+family needs primitives generated with magenta-key backdrops. The model
+needs explicit instruction to use `#FF00FF` solid backgrounds; in
+practice the family pipeline's color profile gate caught the path_node
+at 39% in-range (1pt below the 40% threshold) on retry, but accepted
+best-effort because the gate is WARN-not-block in V1. Future iteration
+can hard-block on color once the pipeline reliably hits ≥80%.
+
+## Alternatives considered
+
+**Option A — Pragmatic regen of `marble_path.path_terrain` to be sand.**
+~$0.08 of generation work. Visible problem disappears for V1. But binds
+the family to one underlying terrain forever — the moment a path needs
+to run through grass, this model breaks again. We chose the architectural
+fix because the explicit goal of this stress-test session is improving
+the building architecture, not patching surface symptoms.
+
+**Option B — Multi-layer ground cells.** Instead of two layers (ground
++ object), let ground itself be a stack: `[sand, marble_path]` for path
+cells. Cleaner conceptually for "path on top of ground" framing, but a
+much larger schema change — affects every consumer of `INITIAL_MAP.ground`,
+breaks the "ground is always one terrain" invariant ADR 0011 leans on,
+and doesn't generalize beyond paths.
+
+**Option C — Composite at preload.** Generate the full opaque path tile
+at runtime by stitching `world_ground_tile + path_alpha_overlay` once
+per cell when the world loads. Equivalent visual outcome to the chosen
+approach, but does the compositing in JS (slow), per-cell (lots of
+texture cache pressure), and at preload (delays first render). The
+chosen approach offloads the compositing to the GPU at draw time, which
+is what Phaser is already optimized for.
+
+## Verification
+
+- `tests/walkability.mjs` — 14/14 passing. New: PATH_MARBLE non-blocking;
+  4-cell strip walkable; ground=SAND object=PATH_MARBLE at the path cells.
+- `tests/terrain_picker.mjs` — 14/14 passing. New: OBJECT_RENDER strategy
+  enumeration; `pickObjectAutotileIndex` dispatch correctness on
+  isolated, vertical-strip, top/bottom end-cap configurations; the
+  object-layer autotile invariant.
+- `tests/autotile_xverify.mjs` — unchanged, still green (the JS↔Python
+  lookup tables didn't change; only the dispatch wrapper shifted).
+- Visual: `/tmp/path-on-sand-preview.png` (rendered at session time)
+  shows a 4-tile vertical strip with marble flagstones running down the
+  center column and sand visible on left/right margins — no magenta, no
+  terrain mismatch, no gaps. The browser will reproduce this at runtime.
+- The `_magenta_mask` detector runs before palette quantization, on raw
+  model output, with threshold `R>180 ∧ G<80 ∧ B>140` (caught 61% of
+  pixels in `path_node`, 33% in `path_arm_N`).

package/docs/adr/0014-families-canonical-over-vocabulary.md

@@ -0,0 +1,103 @@
+# 0014 — `families.json` is canonical over `vocabulary.json` for any shared id
+
+- **Status:** Accepted
+- **Date:** 2026-05-11
+- **Deciders:** Lars
+- **Track:** `internal` (art pipeline)
+- **Extends:** [ADR 0008-a](./<redacted>.md) (family-based tile generation), [ADR 0009](./0009-autotile-architecture.md) (autotile architecture)
+
+## Context
+
+The pixel-art pipeline grew in two phases:
+
+1. **Phase 0** seeded `art/template/vocabulary.json`. Each entry is one
+   atomic tile or sprite, generated one-at-a-time, scored against the
+   per-tile rubric.
+2. **Phase 1+** introduced `art/template/families.json`. A family is a
+   *group* of related members (a player spritesheet, the 8 container
+   panels, an autotile family). Families carry richer metadata: edge
+   contracts, color profiles, member kinds, anchor refinement,
+   deterministic checks, layout cell coordinates, sliceable strategies.
+
+Both files coexisted while families were being migrated from per-tile
+generation. That migration is now far enough along that several ids
+appear in *both* files:
+
+- `player_down_idle`, `player_up_idle`, `player_left_idle`,
+  `player_right_idle` — vocab + `player_character` family members
+- `rock_small` — vocab + `rock` family member
+- `vendor_hyperion` — vocab id + `vendor_hyperion` family id (whose
+  members are `vendor_hyperion_idle` / `..._talk`)
+- `marble_path` — vocab id + autotile family id
+
+Duplication has two failure modes:
+1. **Drift.** A descriptor or `game_key` updated in one file but not
+   the other. Whichever file the running pipeline reads from "wins"
+   silently; the other becomes stale.
+2. **Double-publish.** `build_tilesheet.py` writes every vocab entry
+   then every family member. Same id from both sources overwrites the
+   manifest entry twice — order-dependent, fragile.
+
+We need one canonical source for any id that has both representations.
+
+## Decision
+
+**We will treat `families.json` as the canonical source for any id that
+appears in both files.** `vocabulary.json` is reserved for legacy
+per-tile entries that are *not* covered by any family — atomic singletons
+from Phase 0 (e.g. `amphora`, `column_base`, `olive_tree`) that have not
+yet been migrated to a family and may never need to be.
+
+Concretely:
+
+1. Vocabulary entries whose `id` matches any of (a) a family id,
+   (b) a family member id, or (c) an autotile family id are **removed**
+   from `vocabulary.json`. As of GDS [#139](https://example.com/builders#/task/139) that's 7 entries:
+   `marble_path`, `player_{down,up,left,right}_idle`, `rock_small`,
+   `vendor_hyperion`.
+2. `build_tilesheet.py` builds the set of "family-owned" ids at the top
+   of `main()` and silently skips any vocab entry whose id is in that
+   set. This is defense in depth — even if a future edit re-introduces
+   an overlapping vocab entry, families.json wins by construction.
+3. Future migrations (e.g. `amphora` → an amphora family) follow the
+   same pattern: add the family entry to `families.json`, then remove
+   the now-redundant entry from `vocabulary.json` in the same change.
+4. `vocabulary.json`'s `_comment` field documents this canon rule and
+   points back at this ADR.
+
+## Alternatives considered
+
+- **Merge both files into one `assets.json`.** Cleaner long-term but
+  the rubric / schema / orchestrator code-paths are different enough
+  (per-tile review vs. family review with deterministic gates) that
+  merging now would invite churn. Defer until Phase 0 is fully drained.
+- **Keep both files, prefer vocabulary.json when both define an id.**
+  Backwards but symmetrical. Rejected because families.json carries
+  strictly more metadata — the deterministic checks, color profiles,
+  and edge contracts are not expressible in the vocabulary schema, so
+  preferring vocabulary would be a regression in fidelity.
+- **Auto-generate vocabulary.json from families.json at build time.**
+  Possible but introduces a generated-file invariant we'd have to
+  guard in CI. The remaining 16 vocab-only entries don't justify the
+  tooling cost yet.
+
+## Consequences
+
+- **One file owns each id.** No more drift between two
+  descriptors for the same sprite.
+- **Per-tile pipeline still works** for legacy entries — Phase 0
+  outputs continue to land at `art/generated/tiles/<id>.png` and get
+  published by the vocabulary loop. Nothing about the orchestrator
+  changes.
+- **build_tilesheet.py is monotone:** for any given manifest id, exactly
+  one publishing pass writes it. The order of (vocab pass → family pass
+  → autotile pass) is no longer load-bearing, because the vocab pass
+  skips family-owned ids up front.
+- **Migration motion is mechanical.** Promoting a vocab entry to a
+  family: add the family, remove the vocab entry, regenerate. The
+  scanner / smoke tests catch any regression at the manifest level.
+- **No game-side change.** Both `key` (vocab) and `game_key` (family)
+  resolve to the same texture-key conventions used by Player.js /
+  vendorSprite.js / tilePalette.js. The texture keys the game asks
+  for (`player_down`, `vendor_idle`, `tex_rock_small`, etc.) are all
+  still defined in the manifest after the dedup.

package/docs/adr/0015-task-dependencies-and-auto-promotion.md

@@ -0,0 +1,125 @@
+# ADR 0015 — Task dependencies + auto-promotion
+
+**Date:** 2026-05-17
+**Context:** GDS-V3, task [#309](https://example.com/builders#/task/309) (V3.R02 — Task dependencies + auto-promotion system).
+**Status:** Accepted.
+
+## Problem
+
+The GDS has a `tasks` table with a `status` column and a `priority` column, plus a `V<ver>.R##` rank prefix encoded in the title. Planning Session `#1` (2026-05-12) used the rank prefix as the "order to ship things in." But the system had no machinery to enforce that order:
+
+- Every new task lands in `status='backlog'`.
+- A task can only be claimed when `status='ready'`.
+- `backlog → ready` only flips via manual `POST /tasks/:id/promote`. There is no auto-promotion rule.
+- So the rank prefix was decorative — execution order was whatever happened to be promoted, which in practice meant "whatever was already `ready` from a previous version."
+
+Lars hit this on 2026-05-17: he wanted to claim the top-rank GDS-V3 task and the API offered him one option (V3.R18) — the only `ready` task — when the ranking implied he should be working on V3.R02.
+
+We needed three things:
+
+1. **A way to declare "task A must wait for task B."**
+2. **A rule that promotes tasks automatically as their dependencies ship**, so the queue self-feeds.
+3. **A claim-time guard** so a task can't be worked while its deps are still open, even if it ended up `ready` manually.
+
+## Decision
+
+Add a `task_dependencies` join table, a `tasks` UPDATE trigger that auto-promotes dependents on ship, a claim-time check that refuses `DEPS_NOT_SHIPPED`, and an API surface for managing deps.
+
+### Schema
+
+```sql
+CREATE TABLE task_dependencies (
+  task_id            bigint NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+  depends_on_task_id bigint NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+  created_at         timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (task_id, depends_on_task_id),
+  CONSTRAINT no_self_dep CHECK (task_id <> depends_on_task_id)
+);
+CREATE INDEX idx_task_deps_task         ON task_dependencies (task_id);
+CREATE INDEX idx_task_deps_depends_on   ON task_dependencies (depends_on_task_id);
+```
+
+Many-to-many. Cascade on delete because a task being removed orphans its edges. Self-deps are constrained out at the DB layer; cycles are checked at the application layer (recursive CTE in `addTaskDependency` / `setTaskDependencies`).
+
+### Trigger
+
+```sql
+CREATE TRIGGER trg_promote_dependents_on_ship
+  AFTER UPDATE OF status ON tasks
+  FOR EACH ROW
+  EXECUTE FUNCTION promote_dependents_on_ship();
+```
+
+The function fires when `NEW.status='shipped' AND OLD.status<>'shipped'`. It scans rows in `task_dependencies` where `depends_on_task_id = NEW.id`, and for each dependent task that is `backlog`, is NOT `kind='spike'`, and has zero remaining unshipped deps, flips it to `ready` and stamps `promoted_at`.
+
+### Claim-time guard
+
+`claimTask` in [src/bongos/db.js](../../src/bongos/db.js) checks `unshippedDependencies(taskId, client)` before inserting the claim row. If any dep is unshipped, throws `{ code: 'DEPS_NOT_SHIPPED', deps: [...] }`. The route handler maps that to HTTP 409, the CLI prints a clean error listing the blockers.
+
+`claimTasksBatch` does the same check per-task but treats batch-internal deps as "OK" (the batch is worked serially).
+
+### API surface
+
+| Verb     | Path                                          | Body / returns                                           |
+|----------|-----------------------------------------------|----------------------------------------------------------|
+| `GET`    | `/api/gds/tasks/:id`                          | `task` now includes `dependencies[]` + `dependents[]` arrays |
+| `GET`    | `/api/gds/tasks/:id/dependencies`             | `{ dependencies, dependents }`                            |
+| `POST`   | `/api/gds/tasks/:id/dependencies`             | `{ depends_on_task_id }` or `{ depends_on_task_ids: [N,...] }` |
+| `PUT`    | `/api/gds/tasks/:id/dependencies`             | `{ depends_on_task_ids: [N,...] }` — replaces full set    |
+| `DELETE` | `/api/gds/tasks/:id/dependencies/:depId`      | removes one edge                                         |
+
+Error codes: `self_dep` (400), `task_not_found` (404), `cycle` (409 — returns the path).
+
+### Spike convention
+
+Spikes (`kind='spike'`) NEVER auto-promote. They sit in backlog until a power-user manually calls `POST /tasks/:id/promote`. This is the "ambiguity gate" — spikes produce new task definitions or ADRs whose outputs reshape downstream work; auto-flowing them would skip the human review that justifies the spike's existence.
+
+Non-spike tasks (`feature`, `bug`, `infra`, `cleanup`, `refactor`, `learning-capture`, `decision`, `blocker-resolution`, `unclassified`) auto-promote.
+
+### Rank renumbering
+
+The `V<ver>.R##` rank prefix is now a topological renumbering of the dep graph. For any A → deps → B, B's R## < A's R##. Tiebreaker: lower current R## (preserves planning intent), then alphabetical. The rank is decorative — `dependencies[]` is load-bearing — but a topologically-sorted rank makes the queue display read true.
+
+Migration 021 did the initial pass for GDS-V3: 86 dep edges inserted, 72 of 87 non-shipped tasks renumbered.
+
+## Alternatives considered
+
+### One: `tasks.depends_on int[]` array column
+
+Single column, no join table. Rejected because:
+- Indexing both directions (forward + reverse) is harder with arrays.
+- The cycle-detection CTE is uglier without a normalized edge list.
+- The 1-row-per-edge model lets us add per-edge metadata later (e.g. `reason`) without schema churn.
+
+### Two: `parent_task_id` for ordering
+
+We already have a parent/child hierarchy column (PMS-V2 [#210](https://example.com/builders#/task/210)). Reuse it for ordering. Rejected because hierarchy is a *containment* relationship ("R17 is a sub-task of R15") and dependency is a *precedence* relationship ("R17 cannot start until R08 ships"). Two different things. Conflating them would make both unusable.
+
+### Three: Cron-based promotion
+
+A scheduled task walks the backlog every N minutes and promotes anything whose deps are clear. Rejected because:
+- Latency: tasks could sit unpromoted for up to N minutes after a ship.
+- More moving parts (one more scheduled task to monitor).
+- The trigger is exactly correct here — it fires synchronously with the state change that matters.
+
+### Four: No auto-promotion — keep manual `/promote`
+
+Rejected because that's the system that was failing Lars in the first place. Manual promotion doesn't scale beyond one builder.
+
+## Consequences
+
+**Good:**
+- A high-rank task that's stuck in backlog is now self-explanatory: look at its `dependencies[]`.
+- A planning session's rank actually means something now — execution order can't drift from the spec.
+- Parallel-safe: deps are evaluated per-claim, so two builders can independently claim tasks whose dep graphs don't overlap.
+- The auto-promotion trigger is one place to read; it's the only thing that flips status from backlog → ready (other than `POST /promote` and the existing blocker-resolution trigger).
+
+**Costs:**
+- Migration 021 was hand-built for the GDS-V3 task set; future planning sessions will need their seed scripts to write the `task_dependencies` rows as part of the same atomic seed. The [planning-session SKILL](../../.claude/skills/planning-session/SKILL.md) Phase 4 now captures this.
+- Cycle detection on every `addTaskDependency` is a recursive CTE walk. Cheap for V3-sized graphs (<100 nodes, <100 edges); will need an index review at 1000+ nodes if we ever get there.
+- A planner who forgets to declare a dep will get the wrong execution order — but they'll see it immediately when the wrong task auto-promotes, and editing deps after the fact is cheap (`PUT /tasks/:id/dependencies` replaces the full set). The auto-promotion trigger doesn't retro-flip; if you add a dep to a task that's already `ready`, the task stays ready. That's intentional — auto-promotion is a forward-only signal.
+
+**Operationally:**
+- `/builder-start` filters by `status='ready'`, so a builder never sees a dep-blocked task in their menu. Good UX.
+- `/builder-claim` returns `DEPS_NOT_SHIPPED` if a manually-promoted task is claimed before its deps land. CLI prints the blockers. Good UX.
+- The `[ADR 0014](../adr/<redacted>.md)` ADR number was taken by the families work; this one is **0015**.