@bongos/core 1.19.714 → 1.19.724

package/docs/recipes/memory-sync-conflicts.md

@@ -1,6 +1,6 @@
 # Recipe — Memory sync conflicts: policy + clobber recovery
 
-> **Filed by:** task [#277](https://example.com/builders#/task/277) (V3.R58), GDS-V3 criterion C8. Documents the conflict policy chosen by the R04 spike ([ADR 0024](../adr/<redacted>.md) §3) and implemented across [#274](https://example.com/builders#/task/274) (push), [#275](https://example.com/builders#/task/275) (pull), [#276](https://example.com/builders#/task/276) (isolation). Recovery leans on the backup pipeline from [#281](https://example.com/builders#/task/281) ([`memory-backup.md`](memory-backup.md)).
+> **Filed by:** task [#277](https://example.com/builders#/task/277) (V3.R58), GDS-V3 criterion C8. Documents the conflict policy chosen by the R04 spike ([ADR 0024](../adr/0024-cloneable-repo-local-first-memory.md) §3) and implemented across [#274](https://example.com/builders#/task/274) (push), [#275](https://example.com/builders#/task/275) (pull), [#276](https://example.com/builders#/task/276) (isolation). Recovery leans on the backup pipeline from [#281](https://example.com/builders#/task/281) ([`memory-backup.md`](memory-backup.md)).
 
 ## The policy in one line
 
@@ -93,6 +93,6 @@ sudo -u postgres dropdb example_recover && rm -f /tmp/recovered.txt
 
 ## See also
 
-- [ADR 0024](../adr/<redacted>.md) §3 — the decision + rejected alternatives.
+- [ADR 0024](../adr/0024-cloneable-repo-local-first-memory.md) §3 — the decision + rejected alternatives.
 - [`memory-backup.md`](memory-backup.md) — backup cadence + the restore drill the recovery above relies on.
 - [`gds-db-backup.md`](gds-db-backup.md) — the underlying dump/offsite pipeline.

package/docs/recipes/multi-builder-merge.md

@@ -1,6 +1,6 @@
 # Multi-builder merge safety — audit + serialization model
 
-> **Deploy-mode note (current state).** This recipe documents the **`laptop`** merge path (operator merges `main` + SSHes the droplet). Since the 2026-06-13 cutover `config/deploy.json` is **`mode: ci`** — the merge + deploy run **server-side** (PR auto-merge + `.github/workflows/deploy-prod.yml`), and credential-less dev boxes ship via server-mediated publish ([ADR 0055](../adr/<redacted>.md)). The local-`main`-worktree + merge-lock model below applies only if `deploy.json` is reverted to `mode: laptop`.
+> **Deploy-mode note (current state).** This recipe documents the **`laptop`** merge path (operator merges `main` + SSHes the droplet). Since the 2026-06-13 cutover `config/deploy.json` is **`mode: ci`** — the merge + deploy run **server-side** (PR auto-merge + `.github/workflows/deploy-prod.yml`), and credential-less dev boxes ship via server-mediated publish ([ADR 0055](../adr/0055-server-mediated-branch-publish.md)). The local-`main`-worktree + merge-lock model below applies only if `deploy.json` is reverted to `mode: laptop`.
 
 > **Task:** V3.R50 / [#269](https://example.com/builders#/task/269) (criterion **C6 — parallel-safe-under-load**).
 > **Question it answers:** when N>1 builders ship and merge concurrently, where do `ship.js` and `/merge-mode` assume "I am the only builder," and what serializes the shared state so they don't collide?
@@ -72,7 +72,7 @@ Behavior is pinned by [`tests/merge_lock.mjs`](../../tests/merge_lock.mjs) (auto
 
 ## Related
 
-- [ADR 0024](../adr/<redacted>.md) — multi-agent system (the reason N>1 builders exist).
+- [ADR 0024](../adr/0024-multi-agent-system-architecture.md) — multi-agent system (the reason N>1 builders exist).
 - [#462](https://example.com/builders#/task/462) — the C4 auto-merge lock this task generalizes.
 - [#270](https://example.com/builders#/task/270) (V3.R51) — server-side worktree-name uniqueness (a sibling parallel-safety fix).
 - [#272](https://example.com/builders#/task/272) — the parallel-load smoke test that *exercises* this serialization under 5 simulated builders (the other open C6 task). Its **DB rank is R53** (the DB is king); the original planning-seed cross-ref text called it "R54", but the live rank renumbering settled it at R53/[#272](https://example.com/builders#/task/272).

package/docs/recipes/ops-gotchas.md

@@ -28,7 +28,7 @@ Organized by topic, not chronology. New entries go in the matching section; crea
 ### Re-provisioning an EXISTING instance moves its `HOME`, orphaning any stored builder secrets
 
 - **Symptom:** after a re-provision, an instance that had builder API keys stored can no longer decrypt them. Nothing errors at startup — the instance comes up healthy and simply behaves as though no key was ever saved.
-- **Root cause:** task [1003369](https://cloudbongos.com/builders#/task/1003369) ([ADR 0281](../adr/<redacted>.md)) gives each instance its own unix account with `HOME=/var/lib/bongos-<slug>`. [`src/bongos/secret-box.js`](../../src/bongos/secret-box.js) keeps its master key at `~/.config/<configDir>/builder-secret.key`, so the key an instance wrote under the OLD shared home (`/home/lars/.config/…`) is no longer on its `HOME` path. `provisionMasterKey()` finds nothing, mints a fresh key, and every previously encrypted secret is now undecryptable ciphertext.
+- **Root cause:** task [1003369](https://cloudbongos.com/builders#/task/1003369) ([ADR 0281](../adr/0281-an-instance-identity-is-its-own-unix-account-and-pg-role.md)) gives each instance its own unix account with `HOME=/var/lib/bongos-<slug>`. [`src/bongos/secret-box.js`](../../src/bongos/secret-box.js) keeps its master key at `~/.config/<configDir>/builder-secret.key`, so the key an instance wrote under the OLD shared home (`/home/lars/.config/…`) is no longer on its `HOME` path. `provisionMasterKey()` finds nothing, mints a fresh key, and every previously encrypted secret is now undecryptable ciphertext.
 - **Who this hits:** only a **re-provision of an instance that has already stored secrets**. A fresh standup has nothing to lose, and an instance whose `web.env` sets `BUILDER_SECRET_KEY` is unaffected — that env wins over the file.
 - **Fix (before the re-provision, one command as root):**
   ```bash
@@ -70,7 +70,7 @@ Organized by topic, not chronology. New entries go in the matching section; crea
 
 - **Symptom:** Caddy obtained the initial cert fine, then failed to renew at the 90-day mark — site went down.
 - **Root cause:** With Cloudflare proxy ON (orange cloud), CF intercepts port 80 at the edge and Caddy never sees the HTTP-01 challenge from Let's Encrypt. Renewal silently fails.
-- **Fix (already in place):** Replaced Let's Encrypt with a Cloudflare Origin Certificate (15-year cert at `/etc/caddy/origin.crt` + `.key`, explicit `tls` directive in Caddyfile). Eliminates the auto-renewal dependency for the CF↔origin leg. See [ADR 0003](../adr/<redacted>.md).
+- **Fix (already in place):** Replaced Let's Encrypt with a Cloudflare Origin Certificate (15-year cert at `/etc/caddy/origin.crt` + `.key`, explicit `tls` directive in Caddyfile). Eliminates the auto-renewal dependency for the CF↔origin leg. See [ADR 0003](../adr/0003-cloudflare-origin-cert-over-letsencrypt.md).
 - **Why it bites:** The failure mode is silent for ~89 days, then catastrophic. Easy to think the site is "set and forget" when it is actually approaching a cliff.
 
 ### Deploying configs to `/etc/caddy/` requires staging through `~/`
@@ -249,7 +249,7 @@ Organized by topic, not chronology. New entries go in the matching section; crea
 
 - **Symptom:** the site is down for hours, but The Watch still shows 100% / "standing".
 - **Root cause:** `status.example.com` is served by the same Node process on the same droplet as the game, and the in-process poller (`src/bongos/uptime-poller.js`) probes `127.0.0.1`. When the droplet dies, the page dies with it and the poller writes **zero rows** — the gap renders as green. A monitor that lives inside the monitored thing cannot witness its own death.
-- **Fix:** measure availability from **outside** (the external GitHub-Actions prober — `.github/workflows/status-probe.yml`, task [#565](https://example.com/builders#/task/565)) and host the status page **off-box** (follow-up [#566](https://example.com/builders#/task/566)). See [ADR 0029](../adr/<redacted>.md) + Bongos learning `#35`.
+- **Fix:** measure availability from **outside** (the external GitHub-Actions prober — `.github/workflows/status-probe.yml`, task [#565](https://example.com/builders#/task/565)) and host the status page **off-box** (follow-up [#566](https://example.com/builders#/task/566)). See [ADR 0029](../adr/0029-status-page-outage-resilience.md) + Bongos learning `#35`.
 - **Why it bites:** a status page that lies is worse than none — it actively reassures you while the product is on fire.
 
 ### The live status page is NOT served by the droplet — editing the status surface + deploying does nothing
@@ -268,7 +268,7 @@ Organized by topic, not chronology. New entries go in the matching section; crea
 ### `bypassPermissions` "still not available" even though the box was provisioned for it (task 2022)
 
 - **Symptom:** you reconnect to the browser terminal (or SSH) on a dev box and `claude` still stops for permission prompts, even though tasks [#1251](https://example.com/builders#/task/1251) and [#1314](https://example.com/builders#/task/1314) default every box to `bypassPermissions`.
-- **Root cause:** `otb-box-launch.sh` (behind `box-terminal.service`) only ever runs `claude` once — the first time it creates the tmux `otb` session. Every later connect just reattaches to that **same running process**. The `defaultMode=bypassPermissions` setting is written into `~/.claude/settings.json` by `box-source-fetch.sh`'s cron, on its own `*/10` schedule (and, on an already-provisioned box, only after that box's baked copy of the script has self-updated to even contain the fix). If the `otb` tmux session got created before that write landed — an older box, or a fresh box whose very first connect raced the first cron tick — `claude` started once in normal `auto` mode and is stuck there for the life of the box; reconnecting never re-launches it, so the fix never takes effect even once the setting is correct on disk. (Flagged as an open follow-up in [ADR 0104](../adr/<redacted>.md).)
+- **Root cause:** `otb-box-launch.sh` (behind `box-terminal.service`) only ever runs `claude` once — the first time it creates the tmux `otb` session. Every later connect just reattaches to that **same running process**. The `defaultMode=bypassPermissions` setting is written into `~/.claude/settings.json` by `box-source-fetch.sh`'s cron, on its own `*/10` schedule (and, on an already-provisioned box, only after that box's baked copy of the script has self-updated to even contain the fix). If the `otb` tmux session got created before that write landed — an older box, or a fresh box whose very first connect raced the first cron tick — `claude` started once in normal `auto` mode and is stuck there for the life of the box; reconnecting never re-launches it, so the fix never takes effect even once the setting is correct on disk. (Flagged as an open follow-up in [ADR 0104](../adr/0104-trust-gds-api-channel-in-auto-mode.md).)
 - **Fix:** `otb-box-launch.sh` now asserts `defaultMode=bypassPermissions` itself, synchronously, right before it creates a **new** `otb` tmux session — so a fresh session never depends on cron timing. This prevents the race going forward but does **not** repair a box whose `otb` session is already running in the wrong mode: for that, from an SSH/browser-terminal shell run `tmux kill-session -t otb` then reconnect (the launcher creates a fresh session and picks up the corrected setting immediately). Killing the session only drops the terminal pane — it does not touch `/workspace` or in-flight git state.
 - **Why it bites:** every layer *looks* fixed — `~/.claude/settings.json` has the right value, `IS_SANDBOX=1` is set — because you're inspecting the box's filesystem, not the already-running process that never re-read it.
 

package/docs/recipes/overnight-builder.md

@@ -33,7 +33,7 @@ curl -sS -X PATCH -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: applicat
   -d '{"parallel_safe": true}' https://example.com/api/gds/tasks/<id>
 ```
 
-In parallel mode each worker stops at `confirmed` (verified, not yet paid — [ADR 0120](../adr/<redacted>.md) books credits at land) and the runner lands the merges **one at a time** — concurrent merges to `main` are never allowed. Credits land as each merge completes.
+In parallel mode each worker stops at `confirmed` (verified, not yet paid — [ADR 0120](../adr/0120-pay-on-land-and-builder-owned-rebase-gate.md) books credits at land) and the runner lands the merges **one at a time** — concurrent merges to `main` are never allowed. Credits land as each merge completes.
 
 ## Reading the morning report
 

package/docs/recipes/packaging-the-core.md

@@ -2,13 +2,13 @@
 
 > **This is one leg of three.** For how a change to Cloud Bongos actually reaches a live instance — and why merging to `main` ships nothing on its own — start at [the core release pipeline](core-release-pipeline.md).
 >
-> Implements [ADR 0100 §1](../adr/<redacted>.md) (the two-repo instance model). This is **R84**, the first step of the `R84 → R85 → R86` spine: package the core → stand a downstream instance up on a pinned core → make `bongos upgrade` a real update channel. Tooling: [`scripts/gds/package-core.js`](../../scripts/gds/package-core.js) (`bongos package-core`).
+> Implements [ADR 0100 §1](../adr/0100-two-repo-instance-model.md) (the two-repo instance model). This is **R84**, the first step of the `R84 → R85 → R86` spine: package the core → stand a downstream instance up on a pinned core → make `bongos upgrade` a real update channel. Tooling: [`scripts/gds/package-core.js`](../../scripts/gds/package-core.js) (`bongos package-core`).
 >
-> **Real installable npm package ([ADR 0108](../adr/<redacted>.md) §2, task 1882/W2, shipped):** the artifact is `package/`-rooted (the npm convention `npm install ./x.tgz` requires) and carries a synthesized `package.json` — `name: "@bongos/core"`, `version` = `CORE_VERSION`, `main: "src/platform-server.js"`, `exports` for the default entry (`buildPlatformApp`) plus `./serve-internal` (`mountInternalSurfaces`) and `./module-api`, `bin: "bongos"` — and a **pruned** `package-lock.json` (express + pg's own transitive closure only, resolved offline from the source lockfile — no colyseus/phaser/sharp/discord.js). Both files are synthesized fresh, never copied verbatim from the source repo's game-heavy `package.json`. `resolveCoreRoot()`/`resolveInstanceRoot()` ([`src/instance-config.js`](../../src/instance-config.js), W1/task 1881) are what a consumer's own code routes through once installed.
+> **Real installable npm package ([ADR 0108](../adr/0108-instance-composition-configurable-root.md) §2, task 1882/W2, shipped):** the artifact is `package/`-rooted (the npm convention `npm install ./x.tgz` requires) and carries a synthesized `package.json` — `name: "@bongos/core"`, `version` = `CORE_VERSION`, `main: "src/platform-server.js"`, `exports` for the default entry (`buildPlatformApp`) plus `./serve-internal` (`mountInternalSurfaces`) and `./module-api`, `bin: "bongos"` — and a **pruned** `package-lock.json` (express + pg's own transitive closure only, resolved offline from the source lockfile — no colyseus/phaser/sharp/discord.js). Both files are synthesized fresh, never copied verbatim from the source repo's game-heavy `package.json`. `resolveCoreRoot()`/`resolveInstanceRoot()` ([`src/instance-config.js`](../../src/instance-config.js), W1/task 1881) are what a consumer's own code routes through once installed.
 
 ## What the artifact is
 
-A Cloud Bongos *instance* can be its **own repository** that installs a **pinned version** of the Cloud Bongos **core** — the portable methodology + platform + neutral branding — and layers its own content, branding, and modules on top. "The core" is not re-defined here: it is exactly the subtree [`isPublishable()`](../../scripts/gds/publish-manifest.js) already defines ([ADR 0098](../adr/<redacted>.md)).
+A Cloud Bongos *instance* can be its **own repository** that installs a **pinned version** of the Cloud Bongos **core** — the portable methodology + platform + neutral branding — and layers its own content, branding, and modules on top. "The core" is not re-defined here: it is exactly the subtree [`isPublishable()`](../../scripts/gds/publish-manifest.js) already defines ([ADR 0098](../adr/0098-public-mirror-publish-manifest.md)).
 
 `bongos package-core` produces three things in `dist/` (git-ignored — the artifact is a build product, not committed):
 
@@ -20,7 +20,7 @@ A Cloud Bongos *instance* can be its **own repository** that installs a **pinned
 
 The version is the **platform version** — `CORE_VERSION` from [`src/module-api.js`](../../src/module-api.js), the same coordinate the module loader and `bongos upgrade` compare against ([#1203](https://example.com/builders#/task/1203)). That shared coordinate is what keeps the spine coherent: a module pinned to `^core_contract` is guaranteed to load against the packaged core.
 
-Every file is **redacted** through the same fail-closed pipeline the public mirror uses ([ADR 0099](../adr/<redacted>.md)): instance literals + public IPs are stripped, a secret backstop runs, and if *any* residual leak survives the packager **produces nothing** (`dist/` is never touched). So a downstream repo never inherits the source instance's identity or secrets — it gets a neutral core.
+Every file is **redacted** through the same fail-closed pipeline the public mirror uses ([ADR 0099](../adr/0099-delayed-redacted-mirror-export.md)): instance literals + public IPs are stripped, a secret backstop runs, and if *any* residual leak survives the packager **produces nothing** (`dist/` is never touched). So a downstream repo never inherits the source instance's identity or secrets — it gets a neutral core.
 
 ## Produce it
 
@@ -59,6 +59,6 @@ The manifest's `files[]` carries the same `{ path, mode, sha256 }` triples, so t
 
 ## Boundaries + relation to the mirror
 
-- **Not the public mirror.** The delayed, redacted, ~6-month-lagged public mirror ([ADR 0099](../adr/<redacted>.md)) is the open-source surface. This artifact is a *current*, versioned unit for **dependency consumption** by a sister repo — no lag. Both reuse the same `isPublishable()` selection and the same redaction; `package-core.js` imports the mirror's `redactBlob` so the redaction logic is defined once.
-- **Per-repo Bongos.** Each instance runs its own database, tasks, builders, and credits ([ADR 0100 §3](../adr/<redacted>.md)). Packaging the core moves *code*, never work-tracking state.
+- **Not the public mirror.** The delayed, redacted, ~6-month-lagged public mirror ([ADR 0099](../adr/0099-delayed-redacted-mirror-export.md)) is the open-source surface. This artifact is a *current*, versioned unit for **dependency consumption** by a sister repo — no lag. Both reuse the same `isPublishable()` selection and the same redaction; `package-core.js` imports the mirror's `redactBlob` so the redaction logic is defined once.
+- **Per-repo Bongos.** Each instance runs its own database, tasks, builders, and credits ([ADR 0100 §3](../adr/0100-two-repo-instance-model.md)). Packaging the core moves *code*, never work-tracking state.
 - **The single-checkout instance model is not deprecated** — it stays the cheaper shape for a quick reskin (cloudbongos.com). Two-repo is the destination for a project that wants to be its own thing and pull core updates on its own schedule.

package/docs/recipes/private-npm-distribution.md

@@ -2,7 +2,7 @@
 
 > **This is one leg of three.** For the whole path from a change on core `main` to a live instance — and for when publishing to npm is *not* what moves an instance — start at [the core release pipeline](core-release-pipeline.md).
 >
-> Implements [ADR 0134](../adr/<redacted>.md), **core half only**. Pre-launch, `@bongos/core` publishes as a **private, scoped** npm package on the owner's paid `bongos` npm org (the canonical brand); at launch it flips to public. The daily command is `bongos` regardless of package name.
+> Implements [ADR 0134](../adr/0134-private-first-npm-distribution.md), **core half only**. Pre-launch, `@bongos/core` publishes as a **private, scoped** npm package on the owner's paid `bongos` npm org (the canonical brand); at launch it flips to public. The daily command is `bongos` regardless of package name.
 >
 > **`@bongos/client` is no longer part of this.** It was published once (2026-07-07, 0.0.2), never updated while the API moved 500+ core versions, and had **zero** consumers the whole time — every consumer vendors a copy instead. The owner removed it from npm on 2026-09-09; ADR 0134's client half is superseded ([task 1003742](https://cloudbongos.com/builders#/task/1003742)). The generated client still exists and still regenerates — it is simply not a package.
 >
@@ -52,13 +52,13 @@ npm pack ./clients/bongos-client --dry-run        # token-free content preview
 npm publish ./clients/bongos-client               # real (publishConfig makes it restricted; needs npm login)
 ```
 
-## Cutting a core release (the policy — [ADR 0161](../adr/<redacted>.md), superseding ADR 0137)
+## Cutting a core release (the policy — [ADR 0161](../adr/0161-publish-on-merge.md), superseding ADR 0137)
 
-**Publishing is automatic on merge** as of 2026-08-08: the `publish` workflow rides behind the required `unit` check, auto-bumps a patch when nobody bumped, builds through the fail-closed no-leak gate, publishes, and tags — see the workflow header (`.github/workflows/publish.yml`) and ADR 0161. It ships inert until the owner arms it (repo variable `PUBLISH_ON_MERGE=1` + secrets `NPM_TOKEN`, `RELEASE_PUSH_TOKEN`). A **minor/major bump stays a human in-task edit**. The update subscription ([ADR 0136](../adr/<redacted>.md)) consumes whatever is published, on its next sweep.
+**Publishing is automatic on merge** as of 2026-08-08: the `publish` workflow rides behind the required `unit` check, auto-bumps a patch when nobody bumped, builds through the fail-closed no-leak gate, publishes, and tags — see the workflow header (`.github/workflows/publish.yml`) and ADR 0161. It ships inert until the owner arms it (repo variable `PUBLISH_ON_MERGE=1` + secrets `NPM_TOKEN`, `RELEASE_PUSH_TOKEN`). A **minor/major bump stays a human in-task edit**. The update subscription ([ADR 0136](../adr/0136-update-channel-subscription-policy.md)) consumes whatever is published, on its next sweep.
 
 The steps below remain as the **manual fallback** (lane disarmed, npm outage, or a deliberate out-of-band release):
 
-1. **Bump `CORE_VERSION`** in [`src/module-api.js`](../../src/module-api.js) (semver; a **patch** for a fix, **minor** for additive surface — a **major** is a deliberate, human-only event) and append an entry to the release ledger [`docs/module-api-changelog.md`](../module-api-changelog.md) in the same commit ([ADR 0203](../adr/<redacted>.md) moved that ledger out of `module-api.js`). This bump is a normal claimed task, not a release-tool side effect — the version's provenance stays in the git history + ledger.
+1. **Bump `CORE_VERSION`** in [`src/module-api.js`](../../src/module-api.js) (semver; a **patch** for a fix, **minor** for additive surface — a **major** is a deliberate, human-only event) and append an entry to the release ledger [`docs/module-api-changelog.md`](../module-api-changelog.md) in the same commit ([ADR 0203](../adr/0203-doorway-changelog-out-of-module-api.md) moved that ledger out of `module-api.js`). This bump is a normal claimed task, not a release-tool side effect — the version's provenance stays in the git history + ledger.
 2. **Publish** (owner, from a clean checkout of the released commit):
    ```sh
    node scripts/gds/package-core.js --publish        # DRY-RUN: runs the fail-closed no-leak gate, previews @bongos/core@<version>
@@ -69,7 +69,7 @@ The steps below remain as the **manual fallback** (lane disarmed, npm outage, or
 3. **Tag the release** (optional but recommended — the deliberate, auditable marker): `git tag core-v<version> && git push origin core-v<version>`. The tag documents intent; it triggers no CI.
 4. **Done.** Subscribed instances on the `patch`/`minor` channel take it automatically on their next routine sweep; `pinned` instances wait for a manual `bongos upgrade`. A stale (un-bumped) version is rejected by npm as a duplicate — a natural guard.
 
-> **Automating this** (a tag-triggered CI publish) is deferred to the managed-fleet epic ([#1948](https://example.com/builders#/task/1948)); revisit when the manual step becomes a real bottleneck. See [ADR 0137](../adr/<redacted>.md) "When to revisit".
+> **Automating this** (a tag-triggered CI publish) is deferred to the managed-fleet epic ([#1948](https://example.com/builders#/task/1948)); revisit when the manual step becomes a real bottleneck. See [ADR 0137](../adr/0137-upstream-publish-policy-manual-owner-gated.md) "When to revisit".
 
 ## Install a private package (any consumer machine or instance)
 

package/docs/recipes/search-index-ingestion.md

@@ -10,13 +10,13 @@ How the `search_chunks` index (the recall layer, [ADR 0060](../adr/0060-gds-retr
 
 - **Delta-driven.** Each chunk's `content_hash` (sha256 of its body) is the change key. The upsert's `ON CONFLICT … DO UPDATE … WHERE content_hash IS DISTINCT FROM EXCLUDED.content_hash` makes an unchanged chunk a **no-op** (no row rewrite). A re-run over an unchanged tree writes nothing.
 - **Prunes shrinkage.** If a file loses sections, chunks beyond the new count are deleted; if a file is removed from the tree entirely, all its chunks are deleted (`source_kind='doc' AND source_ref NOT IN (present)`).
-- **Scopes by rank.** Most docs are `min_rank='xenos'` (shared). Read-sensitive documentation surfaces are tagged `min_rank='metic'` so a sub-Metic search can never surface them ([ADR 0060](../adr/0060-gds-retrieval-layer.md) §6 / [ADR 0043](../adr/<redacted>.md)). The metic set is curated in `SENSITIVE_DOC_GLOBS`: `docs/canonical-permissions.md`, `docs/security/`, `docs/audits/`, and the two trust-boundary ADRs (0016, 0043). **`CLAUDE.md` is deliberately `xenos`** — it's write-protected but the universal read-public onboarding index. Docs are never owner-scoped (`owner_builder_id` stays NULL); per-builder private content is the DB-prose ingester's job (memory rows).
+- **Scopes by rank.** Most docs are `min_rank='xenos'` (shared). Read-sensitive documentation surfaces are tagged `min_rank='metic'` so a sub-Metic search can never surface them ([ADR 0060](../adr/0060-gds-retrieval-layer.md) §6 / [ADR 0043](../adr/0043-git-ssh-trust-boundary-and-rank-floor-on-permission-paths.md)). The metic set is curated in `SENSITIVE_DOC_GLOBS`: `docs/canonical-permissions.md`, `docs/security/`, `docs/audits/`, and the two trust-boundary ADRs (0016, 0043). **`CLAUDE.md` is deliberately `xenos`** — it's write-protected but the universal read-public onboarding index. Docs are never owner-scoped (`owner_builder_id` stays NULL); per-builder private content is the DB-prose ingester's job (memory rows).
 
 ## When it runs
 
 A **non-blocking step in the prod deploy** ([`scripts/deploy/deploy-prod.sh`](../../scripts/deploy/deploy-prod.sh), mirrored in the droplet's hand-maintained `~/deploy.sh`), after the code update + migrations + healthz, where the new markdown and the DB are both on disk. It's wrapped `timeout 60 … || echo "…deploy unaffected"` — **an ingest failure never fails a deploy**; the next deploy (or a manual run) catches up.
 
-> ⚠️ `scripts/deploy/deploy-prod.sh` is a **byte-faithful mirror** of the droplet's `~/deploy.sh`, which is **hand-maintained and NOT auto-installed** (the ci deploy key is forced-command-locked — [ADR 0042](../adr/<redacted>.md)/[0043](../adr/<redacted>.md)). When you change the mirror, **re-apply the same edit to `~/deploy.sh` on the droplet by hand** (`ssh lars@REDACTED_IP`), or the deploy hook won't actually run there. (Same caveat as the [prod deploy-script mirror](../../docs/recipes/ops-gotchas.md) note.)
+> ⚠️ `scripts/deploy/deploy-prod.sh` is a **byte-faithful mirror** of the droplet's `~/deploy.sh`, which is **hand-maintained and NOT auto-installed** (the ci deploy key is forced-command-locked — [ADR 0042](../adr/0042-builder-self-deploy-ci-auto-merge.md)/[0043](../adr/0043-git-ssh-trust-boundary-and-rank-floor-on-permission-paths.md)). When you change the mirror, **re-apply the same edit to `~/deploy.sh` on the droplet by hand** (`ssh lars@REDACTED_IP`), or the deploy hook won't actually run there. (Same caveat as the [prod deploy-script mirror](../../docs/recipes/ops-gotchas.md) note.)
 
 ## Operating it
 
@@ -39,7 +39,7 @@ Output reports `inserted / updated / unchanged / pruned / deleted_sources_chunks
 
 `node scripts/gds/search-ingest-db.js` indexes the prose that lives in the DB, not in git, as `source_kind='db'`: task descriptions + value summaries (`task:<id>`), learnings (`learning:<id>`), idea inbox (`idea:<id>`), done-when criteria (`criterion:<id>`), blockers (`blocker:<id>`), session-log notes (`session_log:<id>`), grade notes (`grade:<id>`), per-builder memory (`memory:<builder>:<path>`), and recent git commit subjects (`commit:<sha>`). Same delta-by-content_hash + prune-vanished behavior as the repo-md ingester.
 
-Security ([ADR 0060](../adr/0060-gds-retrieval-layer.md) §6 / [ADR 0016](../adr/<redacted>.md) / [ADR 0022](../adr/0022-secrets-policy.md)):
+Security ([ADR 0060](../adr/0060-gds-retrieval-layer.md) §6 / [ADR 0016](../adr/0016-trust-boundary-server-enforced-permissions.md) / [ADR 0022](../adr/0022-secrets-policy.md)):
 
 - **`builder_memory` is owner-scoped** — each chunk carries `owner_builder_id`, so a builder's private memory only ever surfaces to that builder (the search route's owner filter, [#950](https://example.com/builders#/task/950)).
 - **`security_sensitive` tasks are tagged `min_rank='metic'`**.

package/docs/recipes/self-host.md

@@ -1,8 +1,8 @@
 # Self-hosting Cloud Bongos (Docker)
 
-Bring up a vanilla Cloud Bongos instance — the build platform + builders' hall + status dashboard, with no game — on any machine with Docker. Shipped by V4.R63 ([task #1202](https://example.com/builders#/task/1202), [ADR 0062](../adr/<redacted>.md)).
+Bring up a vanilla Cloud Bongos instance — the build platform + builders' hall + status dashboard, with no game — on any machine with Docker. Shipped by V4.R63 ([task #1202](https://example.com/builders#/task/1202), [ADR 0062](../adr/0062-medusa-instance-model-decoupling.md)).
 
-> **Relation to configurable-root ([ADR 0108](../adr/<redacted>.md)):** this is the **single-checkout** self-host shape — the whole repo (core + config) is baked into one image, so `resolveCoreRoot()` and `resolveInstanceRoot()` ([`src/instance-config.js`](../../src/instance-config.js)) both resolve to `/app` inside the container. ADR 0108 does not deprecate this path — it stays the cheap, supported shape for a quick reskin (this is how `cloudbongos.com` runs). The *installed-as-a-dependency* shape (a consumer repo running `npm install @bongos/core`) is the separate, heavier path ADR 0108 targets for a project that wants its own repo and its own upgrade cadence — see [`docs/recipes/packaging-the-core.md`](packaging-the-core.md).
+> **Relation to configurable-root ([ADR 0108](../adr/0108-instance-composition-configurable-root.md)):** this is the **single-checkout** self-host shape — the whole repo (core + config) is baked into one image, so `resolveCoreRoot()` and `resolveInstanceRoot()` ([`src/instance-config.js`](../../src/instance-config.js)) both resolve to `/app` inside the container. ADR 0108 does not deprecate this path — it stays the cheap, supported shape for a quick reskin (this is how `cloudbongos.com` runs). The *installed-as-a-dependency* shape (a consumer repo running `npm install @bongos/core`) is the separate, heavier path ADR 0108 targets for a project that wants its own repo and its own upgrade cadence — see [`docs/recipes/packaging-the-core.md`](packaging-the-core.md).
 
 ## One command
 
@@ -13,7 +13,7 @@ docker compose up
 That builds the image, starts Postgres, applies the build-system migrations (game-module migrations are skipped — this is a Bongos-only instance), and serves the builders' hall at **http://localhost:3000**.
 
 - The instance is **vanilla** by default: the neutral Cloud Bongos brand, every feature module (game, art pipeline, Discord, dev boxes) **off**. `.dockerignore` keeps the host's `config/branding.json` and `config/modules.json` out of the image, so it resolves to `config/branding.neutral.json` + `config/modules.neutral.json`.
-- **No OTB scope-truth is seeded.** OTB/product data (game versions, goals, done-when criteria) lives in opt-in seed migrations under `migrations/instance/` (plus a few guarded blocks in the mixed files 003/006). `scripts/migrate.sh` skips them unless `GDS_APPLY_INSTANCE_SEEDS=1`, so a fresh DB comes up with only the schema and platform-universal defaults (ranks, achievements) — no crash, no foreign-key failures, no leftover versions. Platform system principals (`bfg-system`, `discord-bot-system`) are generic and remain. See task 1704 / [ADR 0105](../adr/<redacted>.md).
+- **No OTB scope-truth is seeded.** OTB/product data (game versions, goals, done-when criteria) lives in opt-in seed migrations under `migrations/instance/` (plus a few guarded blocks in the mixed files 003/006). `scripts/migrate.sh` skips them unless `GDS_APPLY_INSTANCE_SEEDS=1`, so a fresh DB comes up with only the schema and platform-universal defaults (ranks, achievements) — no crash, no foreign-key failures, no leftover versions. Platform system principals (`bfg-system`, `discord-bot-system`) are generic and remain. See task 1704 / [ADR 0105](../adr/0105-instance-seed-migrations-out-of-core.md).
 - **No prod topology** is referenced: the database is a local container, the credentials are local demo values, and the app reaches Postgres over TCP via `PG*` env (see `docker-compose.yml`).
 
 To stop and wipe: `docker compose down -v` (the `-v` drops the `cloudbongos-db` volume).
@@ -35,7 +35,7 @@ Author `config/branding.json` from the neutral starter — see [the branding con
 
 **Or scaffold it with `bongos init`** ([task #1204](https://example.com/builders#/task/1204)): a short interview (or `bongos init --from spec.json` for a hands-free / CI run) that writes both config files, **seeds your first version + its done-when goal**, and **files the human-only kickoff steps** (register a GitHub OAuth app, first owner sign-in, repo binding, admission) as real tracked tasks — so a fresh instance has a claimable queue on day one instead of an empty hall. It never invents your branding (it points you at the fill prompt for that). Preview the whole plan with `bongos init --dry-run`.
 
-**Production hosting, optional (the `provisioning` module — [ADR 0111](../adr/<redacted>.md) §3).** If you enable the `provisioning` module and answer the interview's hosting questions (shape — co-tenant `$0` or a dedicated droplet — bring-your-own domain, credential ref, tier), init turns those answers into a real **provisioning request** (a queued `provision` intent the control-plane runner drains) instead of only filing a manual "production topology" task. The two irreducibly-human legs — the GitHub OAuth app and the first owner sign-in — stay guided/manual. If the module isn't enabled on the target instance, init falls back to the manual production-topology task, so nothing is silently skipped.
+**Production hosting, optional (the `provisioning` module — [ADR 0111](../adr/0111-instance-hosting-provisioning-module.md) §3).** If you enable the `provisioning` module and answer the interview's hosting questions (shape — co-tenant `$0` or a dedicated droplet — bring-your-own domain, credential ref, tier), init turns those answers into a real **provisioning request** (a queued `provision` intent the control-plane runner drains) instead of only filing a manual "production topology" task. The two irreducibly-human legs — the GitHub OAuth app and the first owner sign-in — stay guided/manual. If the module isn't enabled on the target instance, init falls back to the manual production-topology task, so nothing is silently skipped.
 
 ## Configuration surface
 
@@ -43,7 +43,7 @@ Author `config/branding.json` from the neutral starter — see [the branding con
 |---|---|---|
 | `PGHOST` / `PGPORT` / `PGUSER` / `PGPASSWORD` / `PGDATABASE` | Postgres connection (read by both the app pool and the migration runner) | the local `db` service |
 | `HOST` / `PORT` | bind address inside the container | `0.0.0.0` / `3000` |
-| `MEDUSA_GDS_ONLY` | `1` = hard force-skip the OTB **instance-seed** migrations (`migrations/instance/`) — belt-and-suspenders over the default. A vanilla instance never wants OTB's versions/goals/criteria (task 1704 / [ADR 0105](../adr/<redacted>.md)). | `1` |
+| `MEDUSA_GDS_ONLY` | `1` = hard force-skip the OTB **instance-seed** migrations (`migrations/instance/`) — belt-and-suspenders over the default. A vanilla instance never wants OTB's versions/goals/criteria (task 1704 / [ADR 0105](../adr/0105-instance-seed-migrations-out-of-core.md)). | `1` |
 | `GDS_APPLY_INSTANCE_SEEDS` | `1` = opt IN to applying the bundled OTB instance-seed migrations. Default (unset) = **skip** — so a self-host never inherits OTB scope-truth. Only the owning instance sets this, and only when rebuilding its DB from scratch (DR). | unset |
 | `BONGOS_PUBLIC_ORIGIN` | public origin for OAuth callbacks etc. | `http://localhost:3000` |
 

package/docs/recipes/server-bring-up.md

@@ -1,6 +1,6 @@
 # Recipe — putting your instance on a real host (`bongos serve`)
 
-> [ADR 0169](../adr/<redacted>.md), task [#1002398](https://cloudbongos.com/builders#/task/1002398). The server half of [`local-dev.md`](local-dev.md) / [ADR 0149](../adr/<redacted>.md): the **same** boot path `bongos dev` runs on your laptop, on a VPS.
+> [ADR 0169](../adr/0169-bongos-serve-server-bring-up.md), task [#1002398](https://cloudbongos.com/builders#/task/1002398). The server half of [`local-dev.md`](local-dev.md) / [ADR 0149](../adr/0149-bongos-dev-local-launcher.md): the **same** boot path `bongos dev` runs on your laptop, on a VPS.
 
 ## The short version
 

package/docs/recipes/ship-and-regrade.md

@@ -12,7 +12,7 @@
 
 1. **`completed`** — the claim resolves once local verification (smoke) passes. **The claim is consumed here.**
 2. **`confirmed`** — the v2 subagent quality grader (the 4-worker panel: Narc · Quality · Hacker · Efficiency Monger) passes. **Verified, but not yet paid.**
-3. **`shipped`** — branch auto-merged to `main` + deployed; the Discord `#ship-news` broadcast fires. **Credits land here** ([ADR 0120](../adr/<redacted>.md) pays on land, not on confirm) — so a task stranded at `confirmed` is unpaid until it lands.
+3. **`shipped`** — branch auto-merged to `main` + deployed; the Discord `#ship-news` broadcast fires. **Credits land here** ([ADR 0120](../adr/0120-pay-on-land-and-builder-owned-rebase-gate.md) pays on land, not on confirm) — so a task stranded at `confirmed` is unpaid until it lands.
 
 The grader reads **committed history** (`merge-base origin/main HEAD`…`HEAD`), independent of touches[] — so the diff it judges is whatever you've committed on the branch, not your working tree.
 
@@ -69,4 +69,4 @@ This writes a `task_grades` row with `grader_kind='lars'` so the audit trail sho
 
 - Learning `#43` — "Recover a task stuck at 'completed': re-grade standalone, then /merge-mode" (the manual procedure this recipe automates).
 - [`/merge-mode`](../../.claude/skills/merge-mode/SKILL.md) — lands `confirmed → shipped` when auto-merge bailed.
-- [ADR 0024](../adr/<redacted>.md) — the MAS grader panel.
+- [ADR 0024](../adr/0024-multi-agent-system-architecture.md) — the MAS grader panel.

package/docs/recipes/standalone-live-docs.md

@@ -1,7 +1,7 @@
 # Recipe — live-updating docs on a STANDALONE instance
 
 **Read before:** standing up / debugging a standalone instance whose `docs/` is empty or stale.
-**Decision of record:** [ADR 0147](../adr/<redacted>.md) (builds on [ADR 0110](../adr/<redacted>.md) / [ADR 0108](../adr/<redacted>.md)).
+**Decision of record:** [ADR 0147](../adr/0147-standalone-live-docs-regen.md) (builds on [ADR 0110](../adr/0110-untrack-whole-file-generated-nav-docs.md) / [ADR 0108](../adr/0108-instance-composition-configurable-root.md)).
 
 ## The mental model — which doc refreshes where
 

package/docs/recipes/ui-look-before-you-ship.md

@@ -1,6 +1,6 @@
 # Look before you ship — the ui-design kit
 
-> The `ui-design` module's kit (`modules/ui-design/kit/`, [task 1003320](https://cloudbongos.com/builders#/task/1003320), [ADR 0197](../adr/<redacted>.md)): a stub, a renderer/auditor, the interaction probes, the mock checker and the contrast probe any builder points at any surface of any instance. Plain Node; the browser is the system Edge or Chrome (nothing is downloaded). The `/design` playbook sends you here.
+> The `ui-design` module's kit (`modules/ui-design/kit/`, [task 1003320](https://cloudbongos.com/builders#/task/1003320), [ADR 0197](../adr/0197-the-ui-design-module.md)): a stub, a renderer/auditor, the interaction probes, the mock checker and the contrast probe any builder points at any surface of any instance. Plain Node; the browser is the system Edge or Chrome (nothing is downloaded). The `/design` playbook sends you here.
 
 The loop is five commands and one habit: **stub → render → probe → read the shots → fix in one batch → re-run once.** A surface describes itself in two small JSON files beside it; the kit never hardcodes a page.
 

package/docs/recipes/upgrading-the-core.md

@@ -2,7 +2,7 @@
 
 > **This is one leg of three.** For the whole path from a change on core `main` to a live instance — including how to tell whether *this* instance takes a vendored tarball or a registry version — start at [the core release pipeline](core-release-pipeline.md).
 >
-> The R86 update-consumption channel ([ADR 0100](../adr/<redacted>.md) §2, [ADR 0103](../adr/<redacted>.md) §4, task [#1690](https://example.com/builders#/task/1690)). How a **two-repo consumer instance** — one that installs `@bongos/core` as a vendored-tarball dependency — pulls the core from version N → N+1. Tooling: [`scripts/gds/upgrade.js`](../../scripts/gds/upgrade.js) (`bongos upgrade`). First proven live on emersonian-circles 1.15.0 → 1.16.0 (task [#1976](https://example.com/builders#/task/1976)).
+> The R86 update-consumption channel ([ADR 0100](../adr/0100-two-repo-instance-model.md) §2, [ADR 0103](../adr/0103-core-first-extraction-cloud-bongos-trunk.md) §4, task [#1690](https://example.com/builders#/task/1690)). How a **two-repo consumer instance** — one that installs `@bongos/core` as a vendored-tarball dependency — pulls the core from version N → N+1. Tooling: [`scripts/gds/upgrade.js`](../../scripts/gds/upgrade.js) (`bongos upgrade`). First proven live on emersonian-circles 1.15.0 → 1.16.0 (task [#1976](https://example.com/builders#/task/1976)).
 
 ## What the channel does
 
@@ -76,7 +76,7 @@ By default (`--rollback-on-failure`, ON unless `--no-rollback-on-failure`) the c
 
 ## Subscribing to updates — unattended patch-only auto-upgrade (task 2150 / ADR 0136)
 
-The sections above are the *manual* `bongos upgrade`. The **subscription** runs it for you, on a cadence, safely — the "subscribe to regular updates" experience. Policy: **patch-only by default, health-gated with auto-rollback, opt-in, autonomy-gated** (full rationale in [ADR 0136](../adr/<redacted>.md)).
+The sections above are the *manual* `bongos upgrade`. The **subscription** runs it for you, on a cadence, safely — the "subscribe to regular updates" experience. Policy: **patch-only by default, health-gated with auto-rollback, opt-in, autonomy-gated** (full rationale in [ADR 0136](../adr/0136-update-channel-subscription-policy.md)).
 
 **Per-instance channel** bounds how far an unattended upgrade may jump:
 

package/docs/recipes/work-on-a-task-from-your-dev-box.md

@@ -2,11 +2,11 @@
 
 > Your dev box serves your **rank scope**: Metic+ boxes carry the **whole repo**;
 > newcomer (starter) boxes carry the safe starter surface. Task-scoped slices are
-> **paused** per [ADR 0193](../adr/<redacted>.md) (the
-> machinery from [ADR 0148](../adr/<redacted>.md) remains;
+> **paused** per [ADR 0193](../adr/0193-pause-task-scoped-box-slices.md) (the
+> machinery from [ADR 0148](../adr/0148-task-scoped-box-source-access.md) remains;
 > `BOX_TASK_SCOPE=on` re-enables it). Your GitHub token never leaves the server —
 > see "How git works on a box" below, and
-> [ADR 0150](../adr/<redacted>.md) for how the
+> [ADR 0150](../adr/0150-box-first-boot-bringup-vendored-instances.md) for how the
 > box comes up.
 
 ## TL;DR
@@ -27,7 +27,7 @@ waiting for the box's ~10-minute refresh.
 ## How git works on a box — read this BEFORE diagnosing "stuck"
 
 The box holds **no stored git credential, ever** — and that is the design, not a
-fault ([ADR 0055](../adr/<redacted>.md)):
+fault ([ADR 0055](../adr/0055-server-mediated-branch-publish.md)):
 
 - **Reads are server-mediated, per request.** Every remote git operation goes
   through `/usr/local/bin/otb-git-credential`, which asks the control plane
@@ -57,7 +57,7 @@ box-written — don't edit it).
   `.claude/`), build tooling (`scripts/`, `src/bongos/`), `docs/`, `infra/`,
   `tests/`, and the sandbox-runnable product code. Rank, checked live by the
   server, is what bounds a box — not the task you claimed
-  ([ADR 0193](../adr/<redacted>.md)).
+  ([ADR 0193](../adr/0193-pause-task-scoped-box-slices.md)).
 
 ## Step by step
 
@@ -118,5 +118,5 @@ one-claim-per-session). To move to a different task:
   the cron does on its schedule.
 - **A fresh box comes up with the code already cloned.** If a box ever comes up
   *bare* (no code, no terminal), that's the packaging bug
-  [ADR 0150](../adr/<redacted>.md) fixed on the
+  [ADR 0150](../adr/0150-box-first-boot-bringup-vendored-instances.md) fixed on the
   control plane — flag it rather than working around it.

package/docs/research/cursor-competitive-analysis.md

@@ -175,8 +175,8 @@ And the reframe that matters most: **Cloud Bongos is free and non-profit, so it
 
 | Cloud Bongos's defensible axis | Why Cursor structurally can't match it |
 |---|---|
-| **Open / AGPL-3.0, no lock-in** ([ADR 0065](../adr/<redacted>.md)) | A $29B+ venture co. *sells* lock-in; AGPL §13 anti-capture is antithetical to its model |
-| **Self-host + full data control** ([ADR 0062](../adr/<redacted>.md) instance model) | SaaS multi-tenant is how it gets margin + telemetry; self-host canonical is the opposite |
+| **Open / AGPL-3.0, no lock-in** ([ADR 0065](../adr/0065-agpl-nonprofit-ai-first-governance.md)) | A $29B+ venture co. *sells* lock-in; AGPL §13 anti-capture is antithetical to its model |
+| **Self-host + full data control** ([ADR 0062](../adr/0062-medusa-instance-model-decoupling.md) instance model) | SaaS multi-tenant is how it gets margin + telemetry; self-host canonical is the opposite |
 | **Model-agnostic / BYO-key, zero markup** | Its economics *depend* on the inference relationship; BYO-key removes the revenue and the supplier risk |
 | **Governance / methodology layer** (claim→ship→grade, multi-builder, trust boundary) | Cursor 3 is *starting* on team governance — but for closed, per-seat, supervised use, not agent-authored multi-builder accountability |
 | **Non-profit** | Investors require the opposite; it can't credibly be "not monetizing you" |
@@ -248,7 +248,7 @@ For an AI-first **orchestration** platform, rank threats by *"does it manage aut
 - "$60B valuation / SpaceX-xAI acquisition (2026)" — **excluded as not credible** (low-quality sources). The credible April-2026 datapoint is the TechCrunch "$2B at ~$50B, in talks" line.
 - "$200/mo plan ≈ $5,000 in real compute" — abstained; directionally consistent with negative-margin reporting, specific figure unverified.
 
-**Internal (our positioning, read 2026-06-22):** [ADR 0065](../adr/<redacted>.md) (AGPL / non-profit / AI-first), [ADR 0062](../adr/<redacted>.md) (instance model, core↔host split), [`GOVERNANCE.md`](../../GOVERNANCE.md) (anti-capture principles); companion deep-research doc `component-based-dev-research.md` (uncommitted, module-system research, 2026-06-21).
+**Internal (our positioning, read 2026-06-22):** [ADR 0065](../adr/0065-agpl-nonprofit-ai-first-governance.md) (AGPL / non-profit / AI-first), [ADR 0062](../adr/0062-medusa-instance-model-decoupling.md) (instance model, core↔host split), [`GOVERNANCE.md`](../../GOVERNANCE.md) (anti-capture principles); companion deep-research doc `component-based-dev-research.md` (uncommitted, module-system research, 2026-06-21).
 
 ---
 

package/docs/research/llm-model-agnostic-and-cheaper-grader.md

@@ -12,7 +12,7 @@ This is a **doc-only research spike** — no code, migration, or config changed
 - **Phase 1 — Tools/coupling audit.** A concrete inventory of *where* the platform is hard-wired to Anthropic/Claude today, file by file, so a build cluster knows exactly what to touch.
 - **Phase 2 — Architecture path.** A recommended sequence to (a) a `ModelProvider` abstraction layer and (b) a cheaper grader, with trade-offs.
 
-**Relationship to [ADR 0089](../adr/<redacted>.md).** The *direction* for both goals was already decided with the owner on 2026-06-26 and recorded in ADR 0089 (Accepted; build task-pending): a central work-type-parameterized grading engine, a cross-family ensemble (Claude + hosted open-weight judges), a `ModelProvider` adapter, and a hosted pay-per-call API for the open leg. **This spike does not re-decide any of that** — it supplies the missing input ADR 0089's "Implementation (task-pending)" section presumes: the *grounded coupling map* of the current codebase. Where this doc and ADR 0089 touch the same ground, ADR 0089 is the decision and this doc is the implementation reconnaissance feeding it.
+**Relationship to [ADR 0089](../adr/0089-modular-multi-model-adversarial-grader.md).** The *direction* for both goals was already decided with the owner on 2026-06-26 and recorded in ADR 0089 (Accepted; build task-pending): a central work-type-parameterized grading engine, a cross-family ensemble (Claude + hosted open-weight judges), a `ModelProvider` adapter, and a hosted pay-per-call API for the open leg. **This spike does not re-decide any of that** — it supplies the missing input ADR 0089's "Implementation (task-pending)" section presumes: the *grounded coupling map* of the current codebase. Where this doc and ADR 0089 touch the same ground, ADR 0089 is the decision and this doc is the implementation reconnaissance feeding it.
 
 > **Confidence marks:** ✅ verified against the live file this session · 🔧 my synthesis / recommendation · ⚠️ caveat or open question for the owner/build cluster.
 
@@ -27,9 +27,9 @@ This is a **doc-only research spike** — no code, migration, or config changed
 
 The good news for the build: **there is one chokepoint.** Almost every platform LLM call funnels through `grader.runSubagent({prompt, opts})` (and its cached sibling `runSubagentCached`). Architect-audit and the routine runner reuse it; the only spawns that *don't* go through it are a couple of CLI scripts that call `spawn('claude', …)` directly. So a `ModelProvider` port introduced **at `runSubagent`** captures the overwhelming majority of the surface in one place. ✅
 
-**The cheaper grader is the same lever pulled differently.** Grading is purely *additive* spend (we pay Claude to write the code, then pay Claude again — Opus/Sonnet — to grade it). The grader prompt is mostly a **fixed rubric sent every call**, which makes it the ideal candidate for (a) a cheaper open-weight judge via the same `openai-compatible` adapter and (b) prompt-cache amortization (already partly handled by the content-addressed LLM cache, [ADR 0077](../adr/<redacted>.md)). 🔧
+**The cheaper grader is the same lever pulled differently.** Grading is purely *additive* spend (we pay Claude to write the code, then pay Claude again — Opus/Sonnet — to grade it). The grader prompt is mostly a **fixed rubric sent every call**, which makes it the ideal candidate for (a) a cheaper open-weight judge via the same `openai-compatible` adapter and (b) prompt-cache amortization (already partly handled by the content-addressed LLM cache, [ADR 0077](../adr/0077-content-addressed-llm-cache.md)). 🔧
 
-**Recommended sequence (detail in §6):** introduce the `ModelProvider` port at `runSubagent` with the existing Claude path as the only registered provider (zero behavior change) → add an `openai-compatible` adapter (DeepInfra/OpenRouter, BYOK, owner spend approval) → generalize `selectGraderModel` into a provider+model registry → run one open judge **advisory-only** (logs, does not gate) → promote to voting once the error-correlation audit ([ADR 0089](../adr/<redacted>.md) §5) shows agreement. This is exactly ADR 0089's staging; this doc just pins each stage to the real files.
+**Recommended sequence (detail in §6):** introduce the `ModelProvider` port at `runSubagent` with the existing Claude path as the only registered provider (zero behavior change) → add an `openai-compatible` adapter (DeepInfra/OpenRouter, BYOK, owner spend approval) → generalize `selectGraderModel` into a provider+model registry → run one open judge **advisory-only** (logs, does not gate) → promote to voting once the error-correlation audit ([ADR 0089](../adr/0089-modular-multi-model-adversarial-grader.md) §5) shows agreement. This is exactly ADR 0089's staging; this doc just pins each stage to the real files.
 
 ---
 
@@ -82,7 +82,7 @@ The main builder session runs inside the **Claude Code CLI harness** itself, whi
 
 ### 2.5 What is NOT coupled (already abstracted, leave alone)
 
-- **The content-addressed LLM cache** ([ADR 0077](../adr/<redacted>.md), `api.llmCache`) — provider-agnostic by shape; memoizes any `{prompt, model}` call. No change needed; it's a free win for the open leg. ✅
+- **The content-addressed LLM cache** ([ADR 0077](../adr/0077-content-addressed-llm-cache.md), `api.llmCache`) — provider-agnostic by shape; memoizes any `{prompt, model}` call. No change needed; it's a free win for the open leg. ✅
 - **The worker contract** (`buildPrompt`/`extractJson`/`computeVerdict` in `modules/grading/grader-workers/`) — model-independent; it builds a prompt and parses JSON. A different model that returns the same JSON schema slots in with no worker change. ✅
 - **The deterministic pre-passes** (route-rank, permission-path — `routeRankCheck`/`permissionPathCheck`) — zero-LLM, no model coupling, and per ADR 0089 §6 they **must stay** the authoritative security gate regardless of which model grades quality. ✅
 - **The art/vision pipeline** (`modules/art-pipeline/`, Gemini) — a *separate* provider coupling (Google, not Anthropic). ADR 0089 §7 folds it into the same work-type seam later; out of scope for *this* spike's Anthropic-focused audit but flagged so the build cluster knows the second provider exists. ⚠️
@@ -153,7 +153,7 @@ This matches ADR 0089 §3's `ModelProvider` decision exactly. The cost field abs
 
 ### 4.4 Trust boundary (non-negotiable, from ADR 0089 §6)
 
-An open-model verdict that gates a ship is a **content-injection surface** ([ADR 0080](../adr/<redacted>.md)). The abstraction must preserve:
+An open-model verdict that gates a ship is a **content-injection surface** ([ADR 0080](../adr/0080-llm-cache-api-transport-and-trust-model.md)). The abstraction must preserve:
 
 - **Deterministic pre-passes stay authoritative + zero-LLM.** No LLM verdict (Claude or open) can upgrade a route-rank / permission-path fail to pass. The provider port grades *quality* only. ✅
 - **Server-side guards (`serverSideGuards`) stay downgrade-only.** The existing envelope (re-run deterministic checks server-side, implausible-pass plausibility bound) is provider-independent and must wrap an open judge's verdict identically. ✅
@@ -223,5 +223,5 @@ Per the task's instruction, this doc lists recommended follow-ups rather than cr
 ## 9. Sources
 
 - The live repo, read 2026-06-28: `modules/grading/grader.js`, `modules/grading/grader-workers/index.js`, `modules/grading/CLAUDE.md`, `src/bongos/llm-pricing.js`, `src/bongos/cascade-dispatch.js`, `modules/builder-settings/skill-prefs.js`, `scripts/gds/ci-grade.js`, `scripts/gds/architect-audit.js`, `scripts/gds/session-cost.js`, `scripts/gds/run-routine.js`.
-- [ADR 0089 — Modular, multi-model adversarial grader](../adr/<redacted>.md) (the accepted direction this spike grounds; includes the external literature + market sweep — self-preference, PoLL, *Nine Judges*, open-weight model licenses, hosting math).
-- [ADR 0028 — Honest LLM spend accounting](../adr/<redacted>.md), [ADR 0077 — Content-addressed LLM cache](../adr/<redacted>.md), [ADR 0080 — LLM cache API transport & trust model](../adr/<redacted>.md), [ADR 0062 — Instance-model decoupling](../adr/<redacted>.md), [ADR 0021 — Per-builder skill model preferences](../adr/<redacted>.md).
+- [ADR 0089 — Modular, multi-model adversarial grader](../adr/0089-modular-multi-model-adversarial-grader.md) (the accepted direction this spike grounds; includes the external literature + market sweep — self-preference, PoLL, *Nine Judges*, open-weight model licenses, hosting math).
+- [ADR 0028 — Honest LLM spend accounting](../adr/0028-honest-llm-spend-accounting.md), [ADR 0077 — Content-addressed LLM cache](../adr/0077-content-addressed-llm-cache.md), [ADR 0080 — LLM cache API transport & trust model](../adr/0080-llm-cache-api-transport-and-trust-model.md), [ADR 0062 — Instance-model decoupling](../adr/0062-medusa-instance-model-decoupling.md), [ADR 0021 — Per-builder skill model preferences](../adr/0021-per-builder-skill-model-preferences.md).

package/migrations/core_240_artist_gate_indexes.sql

@@ -0,0 +1,48 @@
+-- core_240 — index the two reads the artist gate rides on (task 1003575, ADR 0241).
+--
+-- A CORE migration, not a lifecycle one: both `tasks` and `task_override_requests`
+-- are core tables, and ADR 0083 §5 lets a module migration touch only its own
+-- `lifecycle_`-namespaced tables. (fitness.js enforces that, and caught this.)
+--
+-- WHY NOW. Two reads key on this pair and neither had an index behind it:
+--
+--   findTaskBySourceRef  the create-vector idempotency read (task 386) — every
+--                        POST /tasks, every capture re-run, every cascade filing.
+--   listOpenArtistReviews  the artist gate's state read (task 1003575) — a route
+--                        any builder can call AND one every go-live calls, on a
+--                        table that only grows.
+--
+-- Without it both are sequential scans of `tasks`. The gate one is the sharper
+-- edge: a deploy should not get slower because the board got bigger.
+--
+-- NOT UNIQUE, deliberately, and this is the same reasoning findTaskBySourceRef's
+-- own comment records: `tasks` already carries historical (source, source_ref)
+-- duplicates, so a UNIQUE index would fail to BUILD on deploy and take the
+-- migration with it. Application-level idempotency stays the mechanism; this is
+-- only about how the row is found.
+--
+-- PARTIAL on `source IS NOT NULL`: the overwhelming majority of tasks are
+-- hand-filed with no source at all, and indexing those rows buys nothing — both
+-- queries always bind a source.
+--
+-- IF NOT EXISTS so a re-run is a no-op (the migration runner's contract). No
+-- CONCURRENTLY: the runner wraps each migration in a transaction, and this index
+-- is small enough that the brief lock is not worth leaving the transaction for.
+
+-- PLAIN BTREE, not text_pattern_ops, and that is a decision rather than an
+-- oversight. Under a non-C collation Postgres cannot turn `source_ref LIKE
+-- 'prefix%'` into a range bound on that column by itself — but both queries bind
+-- `source` by EQUALITY first, so the scan is already bounded to one source's rows
+-- and the LIKE is a cheap filter within it. A text_pattern_ops index would help
+-- only a caller that matched a prefix WITHOUT naming a source, which neither
+-- query does and which would be the wrong query anyway. Revisit if one appears.
+CREATE INDEX IF NOT EXISTS idx_tasks_source_ref
+  ON tasks (source, source_ref)
+  WHERE source IS NOT NULL;
+
+-- The gate's other leg: "does this task have an approved override request?",
+-- asked as a NOT EXISTS for every candidate review. The open-request uniqueness
+-- index is keyed on (task_id) WHERE status='open', so it cannot serve a lookup
+-- for 'approved' rows.
+CREATE INDEX IF NOT EXISTS idx_task_override_requests_task_status
+  ON task_override_requests (task_id, status);

package/migrations/core_240_goal_members_drop_legacy_role.sql

@@ -0,0 +1,79 @@
+-- core_240_goal_members_drop_legacy_role.sql — THE CONTRACT PHASE of the fourth
+-- "role" rename (task 1003089). core_220 was the expand phase; ADR 0177 records
+-- the two-step, ADR 0174 reserves the word `role` for the three crafts.
+--
+-- forward-unsafe: drop-column + set-not-null on goal_members — safe because core 1.19.238 (task 1003013) stopped reading the dropped column and live serves 1.19.689.
+--
+--   The pragma's first line is the whole claim on purpose: the acknowledgement
+--   regex in scripts/gds/lint-migrations.js captures ONE line, so a reason spread
+--   over a paragraph records nothing a reader of the lint output can check.
+--   Both operations are INTENTIONAL and gated, and this is the step core_220
+--   wrote down in advance. `bongos upgrade` auto-rollback
+--   reverts the CODE PIN but NOT the DB, so the question a pragma has to answer
+--   is "what is the oldest release a rollback could restore, and does it read
+--   the dropped column?". The release that stopped reading `goal_members.role`
+--   is core 1.19.238 (task 1003013, merged as 4738e3dd); cloudbongos.com serves
+--   1.19.689 — ~450 releases past it — verified at claim time with
+--   `curl -s https://cloudbongos.com/version` and
+--   `node scripts/gds/deploy-divergence.js`. There is no live reader of `role`
+--   left to strand. Ships with a fresh backup (`node scripts/gds/backup.js
+--   trigger`) and its own deploy window, same risk class as government_001.
+--
+-- THE FRESH-INSTALL HALF, which is not obvious from the column alone: the last
+-- writer of `role` was not application code at all but a MODULE migration —
+-- modules/lifecycle/migrations/lifecycle_001_goal_first_leads.sql, which runs
+-- AFTER the core migrations on every fresh install and named the old column in
+-- both its INSERT list and its ON CONFLICT arm. A DROP here without that edit
+-- would not have shown up on this instance (the module migration is already in
+-- `schema_migrations`, so it never re-runs) and would have broken `cloudbongos
+-- init` for every NEW instance instead. It is renamed in the same change, and
+-- tests/membership_kind_lockstep.mjs pins that no writer of the old name is left.
+--
+-- Idempotent: safe to re-run, including after the column is already gone.
+
+BEGIN;
+
+-- 1. The lockstep goes FIRST. The function body names NEW.role, and Postgres does
+--    not dependency-track plpgsql bodies — a trigger left behind would not block
+--    the DROP, it would fail at the next write to the table instead.
+DROP TRIGGER IF EXISTS goal_members_membership_kind_lockstep ON goal_members;
+DROP FUNCTION IF EXISTS goal_members_membership_kind_lockstep();
+
+-- 2. The last backfill, guarded on the column still being there so a re-run after
+--    the DROP is a no-op rather than an error. core_220 backfilled at expand time
+--    and the trigger has held the pair in step since, so this is expected to touch
+--    zero rows; it runs because "expected zero" is not "provably zero" on an
+--    instance that spent a release accepting writes from two code paths.
+DO $$
+BEGIN
+  IF EXISTS (
+    SELECT 1 FROM pg_attribute
+     WHERE attrelid = 'goal_members'::regclass
+       AND attname = 'role'
+       AND NOT attisdropped
+  ) THEN
+    EXECUTE 'UPDATE goal_members SET membership_kind = role WHERE membership_kind IS NULL';
+  END IF;
+END $$;
+
+-- 3. Any row the trigger never saw (there should be none) resolves to the same
+--    default the old column carried since migration 160, so step 5 cannot fail
+--    the whole migration on a single stray NULL.
+UPDATE goal_members SET membership_kind = 'member' WHERE membership_kind IS NULL;
+
+-- 4. The old noun leaves the schema. Its CHECK constraint and column default go
+--    with it; core_220's goal_members_membership_kind_check already carries the
+--    same ('lead','member') rule on the new column.
+ALTER TABLE goal_members DROP COLUMN IF EXISTS role;
+
+-- 5. The two guarantees core_220 deliberately deferred to this step. They were
+--    unsafe to state while an older release could still write only `role`; now
+--    that nothing does, the column can carry them itself instead of resting on a
+--    trigger surviving.
+ALTER TABLE goal_members ALTER COLUMN membership_kind SET NOT NULL;
+ALTER TABLE goal_members ALTER COLUMN membership_kind SET DEFAULT 'member';
+
+INSERT INTO schema_migrations (version) VALUES ('core_240_goal_members_drop_legacy_role')
+  ON CONFLICT DO NOTHING;
+
+COMMIT;

package/modules/dev-box/app/src/vendor/bongos-client.cjs

@@ -125,6 +125,10 @@ function createClient(opts = {}) {
       // GET /analytics/builder/{id} — rank: any-builder — GET /analytics/builder/:id
       getAnalyticsBuilderId: (args) => request("GET", "/analytics/builder/{id}", { hasBody: false }, args),
     },
+    "artistGate": {
+      // GET /artist-gate — rank: any-builder — GET /artist-gate
+      getArtistGate: (args) => request("GET", "/artist-gate", { hasBody: false }, args),
+    },
     "auditLog": {
       // GET /audit-log — rank: metic+archon — GET /audit-log
       getAuditLog: (args) => request("GET", "/audit-log", { hasBody: false }, args),