@bongos/core 1.17.0

package/docs/adr/0056-prod-deploy-script-mirror-and-healthcheck-retry.md

@@ -0,0 +1,62 @@
+# ADR 0056 — Version-control the prod deploy script as a reviewable mirror, and retry the post-restart healthcheck
+
+**Date:** 2026-06-13
+**Context:** GDS, task [#1026](https://example.com/builders#/task/1026) (follow-up to [#1025](https://example.com/builders#/task/1025)). Builds on [ADR 0042](<redacted>.md) (ci deploy mode — `deploy-prod.yml` SSHes the droplet's `~/deploy.sh`) and [ADR 0043](<redacted>.md) (the forced-command lock on the deploy key).
+**Status:** Accepted.
+**Track:** `internal` (development system / deploy pipeline).
+
+## Problem
+
+On 2026-06-13, `deploy-prod` run 27468951859 (merge `447a58de`) reported **failure** — `Process completed with exit code 7`, immediately after `==> service: active`. The deploy had actually **succeeded** (live `/version` + external `/healthz` confirmed prod on the new commit). The cause: the in-script healthcheck in the droplet's `~/deploy.sh` was
+
+```sh
+sudo systemctl restart example
+sleep 1
+ACTIVE=$(systemctl is-active example)   # systemd "active" ≠ port bound
+...
+CODE=$(curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:3000/healthz)
+[ "$CODE" = "200" ] || exit 1
+```
+
+`systemctl restart` returns once systemd considers the unit *active*, but the Node process may not have bound `127.0.0.1:3000` yet. A fixed `sleep 1` + a **single** curl raced that bind. When curl couldn't connect it exited 7, and under `set -e` the **command substitution itself** aborted the script — *before* the `==> /healthz:` line even printed. Exit 7 (curl "failed to connect") propagated to the SSH caller, so the Actions step went red.
+
+Two compounding issues:
+
+1. **A false failure on a healthy deploy.** In `ci` mode ([ADR 0042](<redacted>.md)) `ship.js pollCiDeploy` / `publish-status` reads `conclusion=failure` and **cannot auto-advance `confirmed → shipped`** — every ci ship that hits the race needs a manual `POST /tasks/:id/ship` (had to for [#1025](https://example.com/builders#/task/1025)).
+2. **The authoritative deploy script lived only on the droplet.** Prod's `~/deploy.sh` was hand-maintained at `/home/lars/deploy.sh`, un-versioned and un-reviewed — which is exactly why this race went unnoticed. (Staging's analogue, `scripts/deploy/deploy-staging.sh`, *is* in the repo and installed by `deploy-staging.yml` — but it carried the **same** single-curl bug, just manifesting as a clean `fail` rather than exit 7 because its `if ! curl … | grep` form suppresses `set -e`.)
+
+## Decision
+
+### 1. Retry the post-restart healthcheck with short backoff
+
+Poll localhost `/healthz` up to **15× at 1s** before concluding failure (matching the cadence of `ship.js pollCiDeploy`). The load-bearing detail is `… ) || CODE=000`, which keeps a connection failure from tripping `set -e` so a slow bind **retries** instead of dying on the first miss; `--max-time 5` bounds a hang; a real failure still exits 1 with the last 30 journal lines. Applied to **both** the prod script and `scripts/deploy/deploy-staging.sh`.
+
+### 2. Mirror the prod deploy script in the repo (but do NOT auto-install it)
+
+`scripts/deploy/deploy-prod.sh` is now the **version-controlled source-of-truth mirror** of `/home/lars/deploy.sh` — byte-faithful, so `diff <(ssh droplet cat deploy.sh) scripts/deploy/deploy-prod.sh` is empty. This makes the authoritative deploy logic reviewable + diffable and stops the silent drift that hid this bug.
+
+It is **not** auto-scp'd onto the droplet the way `deploy-staging.yml` installs `deploy-staging.sh`, and that asymmetry is deliberate: the prod CI deploy key (`otb-ci-deploy-prod`) is **forced-command-locked** in the droplet's `~/.ssh/authorized_keys` —
+`command="/home/lars/deploy.sh",no-pty,no-agent-forwarding,no-port-forwarding,no-X11-forwarding` ([ADR 0042](<redacted>.md)/[0043](<redacted>.md)). That lock means the CI runner can **only** trigger a deploy, never run `scp` or any other command — a trust-boundary control we will **not** weaken just to auto-sync a script. So prod stays hand-installed by an operator (with a non-forced key) whenever the mirror changes:
+
+```sh
+scp scripts/deploy/deploy-prod.sh lars@REDACTED_IP:deploy.sh
+```
+
+The mirror's header documents this install contract.
+
+## Consequences
+
+- **A slow service bind no longer fails a successful prod deploy** — ci ships auto-advance `confirmed → shipped` without a manual `POST /tasks/:id/ship`.
+- **The prod deploy script is reviewable in the repo** for the first time; the forced-command control is preserved intact.
+- **One manual step remains:** the mirror is the source of truth but is not auto-installed; an operator must reinstall it on change (loud `diff` makes drift visible). Wiring a safe auto-install for prod (e.g. a tightly-scoped second key, or a server-mediated path) is left as a future improvement — out of scope for this bugfix.
+- `provision-staging.sh` has the same single-curl pattern but is a one-time, human-supervised step (not a per-deploy CI hot path); left unchanged, noted as a possible follow-up.
+
+## Verification
+
+Faithful copies of the new loop, exercised three ways:
+
+- **Dead port:** retries then exits **1** cleanly (no exit 7) — proves the `set -e` safety.
+- **Live prod port (on the droplet):** 200 on attempt 1, exit 0.
+- **Slow bind (port binds mid-loop):** retries through the connection failures, catches 200 on attempt 5, exit 0 — the exact incident class.
+
+The fixed script was installed to the droplet (atomic rename; prior version backed up to `~/deploy.sh.bak-task1026`), parses cleanly there, and is byte-identical to the repo mirror.

package/docs/adr/0057-container-cost-ledger.md

@@ -0,0 +1,28 @@
+# ADR 0057 — Per-builder container cost ledger (org-funded → self-fund tracking)
+
+**Date:** 2026-06-15
+**Status:** Accepted
+**Track:** `internal` (dev-system / cost oversight).
+**Context:** GDS-V3, task [#602](https://example.com/builders#/task/602), criterion C-cost. Implements the ledger half of ADR 0031 §5 (cost passthrough). Companion to [ADR 0031](<redacted>.md) (the dev box) and the early-stage billing policy ("tracked, not settled" — both drachmae earnings and container costs are recorded but not actually paid/charged yet).
+
+## Problem
+
+Builders run org-provisioned DigitalOcean dev boxes (ADR 0031). We want every box cost event recorded per builder — visible to the builder on their own profile and to the Archon for oversight — so the org can see what each box costs *before* any real self-fund/charge mechanism exists. No payment integration, no drachmae deduction yet.
+
+## Decisions
+
+1. **Reuse `cost_log`; no new table, no migration.** The existing `cost_log` table (migrations/003, builder-attributed since 046, idempotent on `(source, source_ref)`) already carries timestamp/amount/description/builder_id — the exact shape the task asks for. Container events are logged with `category='compute'` and distinguished by `source`: `box-lifecycle` (compute hours, already shipped via `recordComputeCost`), `box-spinup`, `box-storage`. Bucketing is by `source`, so a $0 spin-up line stays distinct from compute. This avoids a CHECK-constraint migration (the one real deploy risk) entirely.
+
+2. **Accrue at lifecycle transitions — no billing cron.** Compute hours settle at park/deprovision (existing). Spin-up logs at provision + wake. Storage (snapshot-only, charged only while *parked*) settles at wake and deprovision from `parked_at`. All accrual rides the `scripts/gds/box.js` lifecycle ops that already run — no new always-on infra.
+
+3. **Spin-up is a $0 event marker by default.** DigitalOcean charges no provision fee — billing starts at the first active hour (captured by compute). We still write a spin-up `cost_log` row (at `$0`, overridable via `BOX_SPINUP_COST_USD`) so the ledger records every create/resume as a timestamped line, per the task's "capture spin-up events" requirement. No fabricated cost.
+
+4. **Storage = snapshot rate while parked.** `SNAPSHOT_MONTHLY_USD` (~$0.30, overridable) × parked hours. A running box's disk is already in the droplet hourly rate, so storage is a separate line only for the rare manual-park window (the automated lifecycle deprovisions rather than parks — ADR 0031 / box.js).
+
+5. **Two views.** Builder-own: `GET /box/me` returns a `cost` block (`{spinup_usd, compute_usd, storage_usd, total_usd}`, own-scoped, **never** `allowBoxScope`), rendered on the box panel framed as "tracked, not charged." Archon: `GET /boxes/cost-ledger` returns the full ledger + per-builder totals (declared archon-first per the route-rank auditor), surfaced as a "Dev-Box Costs" section on the `/watch` page — cost oversight without a DB query.
+
+## Consequences
+
+- The "compute" category in the public cost summary now also includes near-$0 spin-up rows; negligible.
+- When a real self-fund/charge mechanism lands (drachmae deduction or DO-account handoff), it reads this ledger — the data is already accruing.
+- Pure cost math (`storageCostUsd`, `summarizeBoxCost`) is unit-tested (`tests/box_cost.mjs`); the DB writers ride the box-lifecycle integration smoke.

package/docs/adr/0057-discord-archon-approval-channels.md

@@ -0,0 +1,64 @@
+# ADR 0057 — Approve new members and first dev boxes from Discord (Archon 👍/👎)
+
+**Date:** 2026-06-15
+**Context:** GDS-V4, task [#1100](https://example.com/builders#/task/1100). Builds on [ADR 0033](<redacted>.md) (the in-process Discord bot as a service principal), [ADR 0037](<redacted>.md) (config-driven channel layout), [ADR 0016](<redacted>.md) (server-enforced permissions / trust boundary), [ADR 0035](<redacted>.md) §2 (the first-box Archon approval gate, [#717](https://example.com/builders#/task/717)), and [ADR 0050](<redacted>.md) (invite-gated admission).
+**Status:** Accepted.
+**Track:** `internal` (development system / onboarding + Discord surface).
+
+> **⚠️ Superseded in part by [ADR 0059](<redacted>.md) (task [#1141](https://example.com/builders#/task/1141)).** The **box half** — the `📦-box-approvals` channel and the box-intent 👍/👎 approve/deny wiring — is **removed**: there is no longer a first-box approval gate, so an admitted builder's first box provisions hands-off. The **member half** (`🚪-member-approvals` + the admit/dismiss reaction wiring) is unchanged — member-join admission is still the gate. Read the box-channel parts below as historical.
+
+## Problem
+
+Two recurring Archon decisions could only be made on the example builders hall ("the Watch", `/builders/watch`):
+
+1. **Admit a new builder.** A stranger submits their GitHub username → an `access_requests` row lands at `status='pending'` → an Archon flips it to `'invited'` (or `'dismissed'`) via `PATCH /api/gds/access-requests/:id` (ADR 0050).
+2. **Approve a first dev box.** A newcomer's first paid droplet is held at `box_intents.state='pending_approval'` (ADR 0035 §2) until an Archon flips it to `'pending'` via `POST /api/gds/box/intents/:id/approve`, at which point the control-plane runner provisions it.
+
+Both required opening the hall. The owner already lives in Discord (where ship news, ideas, and bugs already flow — ADR 0033). Neither request emitted any notification, so an Archon had to *remember to check* the Watch. The ask: do both approvals from Discord, with a 👍 reaction, in two **separate** channels.
+
+## Decision
+
+Add two Archon-only Discord channels and wire a reaction handler to the two existing approve actions. **No new authority** is created — Discord becomes a faster trigger for server actions that already exist and are already Archon-gated.
+
+- **Channels** (`docs/discord/channels.json`, reconciled per ADR 0037): `🚪-member-approvals` and `📦-box-approvals`, both `view: archon`. Kept separate as requested.
+- **Outbound (request → channel).** When an `access_request` is created (`POST /access-requests`) the GDS posts a one-line request to `#member-approvals`; when a `box_intent` enters `pending_approval` (`POST /box/ensure`) it posts to `#box-approvals`. Both go through the channel's **incoming webhook** (`scripts/discord/lib.postWebhook`) — the same outbound-only mechanism as ship-news — via `src/bongos/approval-broadcast.js`. Best-effort and fire-and-forget: a Discord hiccup never blocks or fails the request path, and the hall queue remains the source of truth.
+- **Inbound (👍/👎 → action).** The in-process bot's reaction handler (`src/bongos/discord-bot.js` → `src/bongos/discord-approvals.js`) reacts to 👍/👎 in those two channels:
+  - `#member-approvals` 👍 → `access_requests` `'invited'`; 👎 → `'dismissed'`.
+  - `#box-approvals` 👍 → `boxes.approveIntent` (held → `pending`, runner provisions); 👎 → `boxes.denyIntent`.
+
+### Marker contract
+
+Each request line **leads** with a `<kind> #<id>` token (`member-request #<id>` / `box-intent #<id>`), mirroring how ship-feed lines lead with `#<taskId>` (ADR 0033 §3). The handler anchors to the start of the message, so a body that happens to contain another `#5` cannot hijack the mapping. The producer (`approval-broadcast`) and parser (`discord-approvals.parseApprovalMarker`) are unit-tested to round-trip.
+
+### The deny path for boxes
+
+`box_intents.state` has no `denied` value, and adding one would need a migration to widen the CHECK. A 👎 instead resolves the held intent to terminal `state='error'` with `last_error='denied:archon:<login>'` (free-text `box_events.event='intent_denied'` records it). The runner only ever claims `state='pending'`, so a denied intent is never provisioned; `'error'` reads distinctly from a real provisioning failure via the `denied:` prefix. A terminal state frees the `ux_box_intents_open` index, so a declined newcomer can re-request later — symmetric with how a `'dismissed'` access request can be re-submitted. **No migration.**
+
+## Why this is safe — the trust boundary holds (ADR 0016 / 0033 §1)
+
+The one invariant: *every bot-triggered write re-checks the linked builder's LIVE rank.* The bot asserts only **who** reacted (Discord user → linked builder via the F1 link table, which reads `builders.rank` fresh); the GDS decides **what** they may do. Both actions are `requireRank('archon')` on the web, so `discord-approvals` re-derives the reactor's live rank and acts **only** when it is `archon`. A Metic, a player, or an unlinked reactor is a silent no-op. The bot cannot escalate; the worst a compromised bot could do is mis-report which Archon reacted — bounded by the `audit_log` (every write recorded with `surface='discord_bot'`).
+
+Defense in depth, all fail-closed:
+
+- **Webhook-only request lines.** The handler acts only on messages with a non-null `webhookId`. A member cannot post as a webhook (needs Manage Webhooks + the secret URL), so a hand-typed `member-request #5` can't trigger an approval — enforced in code, not just by channel permissions (the same guard ADR 0033 §3 uses for upvotes).
+- **Channel-pinned.** The handler is inert unless the channel ids are configured (`DISCORD_MEMBER_APPROVALS_CHANNEL_ID` / `DISCORD_BOX_APPROVALS_CHANNEL_ID`, or the creds file) — it never acts on reactions in arbitrary channels.
+- **Idempotent.** Both actions guard on the current DB state (`status='pending'` / `state='pending_approval'`), so a duplicate or late reaction matches nothing and is a no-op (`already_resolved`), never a double-write.
+- **Mention pings suppressed.** `postWebhook` already sends `allowed_mentions:{parse:[]}` ([#871](https://example.com/builders#/task/871)), so an attacker-influenceable display name / note in a request line can't `@everyone` the server.
+- **Never throws into the gateway.** Every handler path is caught; the bot can't be crashed by a malformed reaction, and the web/game process is never at risk (ADR 0033 fail-safe).
+
+## Operator setup (inert until configured)
+
+The feature ships dormant — the same posture as every other Discord surface. To turn it on:
+
+1. Create the `🚪-member-approvals` and `📦-box-approvals` channels (or let the channel reconciler create them from `channels.json`).
+2. Create an incoming webhook in each; store the URLs as `member_approvals` / `box_approvals` in `~/.config/otb/discord-webhooks.json` (or env `DISCORD_MEMBER_APPROVALS_WEBHOOK` / `DISCORD_BOX_APPROVALS_WEBHOOK`).
+3. Record the two channel ids as `member_approvals_channel_id` / `box_approvals_channel_id` in `~/.config/otb/discord-bot.json` (or the matching env vars).
+
+Until both halves are set, requests simply aren't posted and reactions aren't acted on; the hall Watch is unaffected.
+
+## Alternatives considered
+
+- **A new HTTP endpoint the bot calls.** Rejected — the bot is in-process (ADR 0033 F3), so it calls the function directly: no localhost self-HTTP, no minted bot session token to store/leak, strictly less attack surface. Same rationale as `discord-reaction`.
+- **Reading the reactor's Discord @Archon role to authorize.** Rejected — Discord roles are cosmetic badges synced one-way from `builders.rank` (ADR 0033 §4); trusting them back would invert the trust boundary. We re-derive rank from the GDS.
+- **Bot posts confirmations via the gateway client.** We post the short `✅ … invited/approved.` confirmation through the channel webhook instead, keeping the bot's write surface to Discord minimal (it adds no authority either way).
+- **A migration adding a `denied` box-intent state.** Rejected for now — terminal `error` + a `denied:` prefix is sufficient and avoids a schema change; revisit if the roster UI needs to distinguish denials visually.

package/docs/adr/0058-automatic-gate-surface-gatekeeper.md

@@ -0,0 +1,64 @@
+# ADR 0058 — Automatic gate-surface gatekeeper (rank-based auto-approval + deterministic hard floor)
+
+- **Status:** Accepted
+- **Date:** 2026-06-15
+- **Track:** internal
+- **Builds on:** [ADR 0042](<redacted>.md) (CI self-deploy), [ADR 0043](<redacted>.md) (protected paths + rank floor), [ADR 0016](<redacted>.md) (trust boundary), [ADR 0055](<redacted>.md) (server-mediated publish), [ADR 0057](<redacted>.md) (Archon approval channels)
+- **Task:** 1139
+
+## Context
+
+In deploy mode `ci` ([ADR 0042](<redacted>.md)) PRs auto-merge on green required checks and `main` auto-deploys to prod. `CODEOWNERS` (owner review on gate surfaces, enforced by `require_code_owner_reviews`) was the **only** human in that loop — it stops a builder from weakening the gate from inside their own auto-merging PR (disabling a check, muting a test, lowering a rank requirement, sneaking a malicious migration).
+
+That review made the owner a bottleneck: **every** PR touching a gate surface (the ~36 `PROTECTED_GLOBS` in [`src/bongos/permission-path-check.js`](../../src/bongos/permission-path-check.js)) blocked on a manual approval — and nothing surfaced those pending PRs, so server-mediated-publish PRs ([ADR 0055](<redacted>.md)) stranded silently (the 2026-06-15 retro: tasks 1068/1096/602/476 sat `confirmed` for days, blocked on an approval the owner never saw).
+
+A red-team design pass established one hard truth: a **deterministic** analyzer can only *safely* certify a tiny set of changes as benign (un-muting a test, narrowing the secret allowlist, and PRs touching no gate surface). New migrations, dependency bumps, and auth/route changes are **undecidable** by rules — and an LLM reviewer is rejected as authoritative because the project's own history (grader prompt-injection fencing, task 995) proves it is trickable.
+
+## Decision
+
+A **rank-based** gatekeeper (owner directive, 2026-06-15: "I don't want to review anything manually"), implemented as a deterministic CI check with three verdicts over the PR **diff-as-data**:
+
+- **PASS** — no gate surface, or only **AUTO** pure-removal surfaces (`run-unit-tests.js` removing a test-mute; `.husky/secrets-allowlist.txt` removing a line). Auto-merge. This already clears the *common* PR (game/art/docs/non-gate `src/`).
+- **NEEDS_TRUST** — a sensitive-but-routine gate surface (migrations, deps, routes, `server.js`, ship plumbing, boxes, doctrine docs, a `db.js` change outside the rank-tier region, a deleted/shrunk test). Auto-merges **iff the author is Metic+** (rank trust, server-resolved) **or the owner approved**; otherwise escalates.
+- **ESCALATE — the HARD FLOOR (rank-independent)** — the gate's own machinery + deploy switch: `gate-review.js` itself, `.github/`, `CODEOWNERS`, `config/deploy.json`, `infra/` (branch-protection-as-code), `auth.js`, `route-rank-check.js`, `permission-path-check.js`, the grader, `main-audit.js`, `run-unit-tests.js` (non-narrowing), the hooks, and `db.js`'s `REQUIRES_RANK_TIER` (content rule). **No rank bypasses this** — it always pings the owner. Pre-flight rejections (symlink, non-ASCII/whitespace path, oversize diff, analyzer error) also ESCALATE, fail-closed.
+
+The hard floor is the irreducible root of trust: a compromised or prompt-injected senior session **cannot** auto-merge a change that disables the gatekeeper, the deploy-time audit, branch protection, or the rank brain. The owner explicitly accepted the residual risk that a hijacked senior session could auto-merge a *non-floor* sensitive change — bounded by (a) this floor, (b) the existing autonomous-path protected-path exclusion (task 994), and (c) the deploy-time `main-audit.js --verify-head` backstop.
+
+### Why these specifics (red-team-closed)
+
+- **Gate-surface set = imported `PROTECTED_GLOBS`, never a hand-typed list** (red-team finding `#1`: a hand-typed shrink dropped `db.js`/`routes.js`/`server.js` and was *less* safe than today). A drift test asserts no protected glob is ever classified PASS.
+- **Two-layer enforcement**: the in-CI `gate-review` check is the fast cooperative gate; `main-audit.js --verify-head` on the droplet is the authoritative net (asserts the merged SHA carries a `success` gate-review conclusion — closes the workflow-self-neuter, raw-push, and cancelled-check races).
+- **Trusted-base overlay**: the workflow overlays the whole `scripts/` + `src/` from `origin/main` before running, so a PR cannot edit the analyzer to pass itself.
+- **`run-unit-tests.js`, `config/deploy.json`, `CODEOWNERS`, `scripts/deploy/`, `gate-review.js`, `grader-rubric.json` added to `PROTECTED_GLOBS`** — these gate-machinery paths were previously unprotected at the sub-Metic floor; adding them closes that pre-existing gap and makes the hard floor a subset of the protected set.
+- **Escalation reuses [ADR 0057](<redacted>.md)**: a `#gate-approvals` channel + `gate-pr #<n>` marker; the owner clears it by approving the (App-authored) PR. Inert until `DISCORD_GATE_APPROVALS_WEBHOOK` is set.
+
+## Rollout (the gate is never weaker mid-flight)
+
+1. **Report-only** (this task): ship `gate-review.js` + `gate-review.yml` with `GATE_REPORT_ONLY=1` (always exit 0 — verdict to the run summary only). `CODEOWNERS`/branch protection unchanged → gate identical to today.
+2. **Verify**: confirm the verdict against real PRs + the red-team matrix (`tests/gate_review.mjs`).
+3. **Enforce**: drop `GATE_REPORT_ONLY`, add `gate-review` to required checks, add the `--verify-head` conclusion assertion, and wire the server rank-attestation (`GATE_AUTHOR_TRUSTED`) + the `#gate-approvals` ping. Then shrink `CODEOWNERS` only for the two AUTO surfaces.
+
+## Consequences
+
+- The owner's manual-review surface shrinks from "every PR touching ~36 protected paths" to "only changes to the gate's own machinery + deploy switch" — pinged, never silently blocked.
+- A purely-deterministic gate could not deliver "review nothing" without the rank-trust layer (migrations/deps are undecidable); the rank layer is the deliberate trade the owner chose.
+- The hard floor + two-layer enforcement keep the safety system itself un-auto-disablable.
+
+## Update — enforcing, and the two server-attestation vectors (task 1142, task 1169)
+
+The gatekeeper went **ENFORCING** (task 1142): `gate-review.yml` no longer sets `GATE_REPORT_ONLY`, and `gate-review` is a required check. The `GATE_AUTHOR_TRUSTED` signal is the `gate-author-trust` **commit status** — set only by the server (which alone holds the authenticated builder's server-resolved rank + the App/PAT credential), so CI reads it but cannot forge it. The server posts it via `githubPush.setCommitStatus` from **two** ship paths, sharing one helper (`postGateAuthorTrust` in [`src/bongos/routes/tasks.js`](../../src/bongos/routes/tasks.js)):
+
+1. **Server-mediated publish** ([ADR 0055](<redacted>.md), dev box / `pushVia 'server'`): `POST /tasks/:id/publish-branch` attests the pushed tip after opening the PR.
+2. **Laptop `ci`-land** (`pushVia 'local'` — task 1169): `ship.js` pushes the branch + opens the PR with the laptop's own `gh` credential, which **cannot** forge the attestation. So `ciLandLocal` calls `POST /tasks/:id/attest-gate` (`requireBuilder` + ownership, deliberately **no** `allowBoxScope`) right **after the push and before opening the PR** — race-free for a fresh PR, since the PR-open is what fires `gate-review` and it runs only after the status is already present. Before task 1169 the laptop path posted *nothing*, so a Metic+ author's gate-surface PR from a laptop was BLOCKED and they could not self-approve their own PR (hit live on task 1162 / PR #131).
+
+A commit status posted on a SHA does **not** re-trigger a `pull_request`-triggered check, so a **reused** open PR that already ran `gate-review` red (on the same SHA, before the attestation existed) gets a best-effort `gh run rerun` nudge of that stale run. A freshly-opened PR needs no nudge.
+
+## Update — owner approval from the hall (task 1179)
+
+Clearing an ESCALATE (and a NEEDS_TRUST without a Metic+ author) required a GitHub `APPROVED` review by `example-owner` on the head SHA — i.e. the owner had to leave a GitHub/terminal review, which the non-technical owner should never have to (feedback: auth flows must be UI-first). This adds a **second owner-approval channel**, trust-equal to the GitHub review, drivable from the builders' hall:
+
+- **The Gate** (`/builders/gate`, Archon-only page, server-gated by `requireArchonPage`) lists every open PR whose `gate-review` check is red — the LIVE check conclusion is the authoritative "awaiting approval" signal — and renders **why** by reusing the **exact** pure `classifyChanges()` the CI runs (no duplicated policy). Each held PR shows its task, author, head SHA, the verdict + per-file reasons (hard-floor flagged), changed files, and a diff link.
+- **Approve** (`POST /api/gds/gate-approvals/:pr/approve`, `requireBuilder` + `requireRank('archon')`) sets a **`gate-owner-approved`** commit status on the head SHA via `githubPush.setGateOwnerApproved` — set **exactly like** `gate-author-trust`: only the server holds the credential, and it sets it only after re-checking the caller's Archon rank server-side ([ADR 0016](<redacted>.md)). A PR author cannot forge it. `gate-review.yml`'s trust step now resolves `OWNER_APPROVED=1` from **either** a `example-owner` GitHub review **or** this status. Both are read on the head SHA, so a later commit's head carries no approval (the same red-team `#2b` sha-pin protection).
+- **Re-trigger without a new App permission.** A commit status does not re-fire a `pull_request` check, and the publish App is not granted `actions:write`. So Approve **closes+reopens** the PR (`recheckPullRequest`, using the `pull_requests:write` the App already holds), which fires `pull_request: reopened` → `gate-review` re-runs with the real PR context, reads the new status on the correct head SHA, and goes green; auto-merge is re-armed and the publish reconciler `mergeIfGreen` sweep (task 1162) is the backstop.
+
+The approve route **clears the hard floor**, so `POST /gate-approvals/:pr/approve` is pinned `archon` in `route-rank-check.EXPECTED_RANKS` (a silent downgrade would let any builder clear an ESCALATE). Because `gate-review.yml` is itself a hard-floor surface, the PR that introduces this change ESCALATEs and must be owner-approved to land — the bootstrapping case, shipped via `OTB_PUSH_VIA_SERVER=1` so the App authors the PR and the owner can approve it. Coverage: `tests/gate_approvals.mjs`. Authority is unchanged in substance — only `rank='archon'` (server-checked) can clear the gate, as before; this just adds a browser surface to do it.

package/docs/adr/0059-single-approval-remove-devbox-approval-gate.md

@@ -0,0 +1,37 @@
+# ADR 0059 — Single approval: remove the dev-box (first-box) Archon approval gate
+
+- **Status:** Accepted
+- **Date:** 2026-06-16
+- **Track:** internal
+- **Supersedes:** [ADR 0035](<redacted>.md) §2 (the first-box Archon approval gate, [#717](https://example.com/builders#/task/717) / migration 071) and the **box half** of [ADR 0057](<redacted>.md) (the `#box-approvals` channel + the box-intent approve/deny wiring)
+- **Builds on:** [ADR 0050](<redacted>.md) (invite-gated admission), [ADR 0031](<redacted>.md) (cloud dev boxes + the box provisioning rank floor), [ADR 0016](<redacted>.md) (server-enforced permissions)
+- **Task:** 1141
+
+## Context
+
+A builder hit **two** human gates between "I heard about this" and "I'm shipping from a dev box":
+
+1. **Member-join admission** ([ADR 0050](<redacted>.md)). A stranger submits their GitHub username → an `access_requests` row lands `pending` → an Archon invites or dismisses it (the hall Watch, or the `#member-approvals` Discord 👍/👎 from [ADR 0057](<redacted>.md)). This is the **admission** gate: it decides who is allowed into the hall at all.
+2. **First-box Archon approval** ([ADR 0035](<redacted>.md) §2, [#717](https://example.com/builders#/task/717), migration 071). An already-admitted builder's *first* dev box was held at `box_intents.state='pending_approval'` until an Archon approved it (`POST /api/gds/box/intents/:id/approve`, or the `#box-approvals` Discord 👍/👎). Only then did the control-plane runner provision the paid (~$24/mo) droplet.
+
+The first-box gate existed when admission was **open** — back then anyone with a GitHub account could become a Xenos with zero human in the loop, so a second human gate on the first paid box was the only thing standing between a signup and a charge ([ADR 0035](<redacted>.md) §Problem-3). Since [ADR 0050](<redacted>.md) closed that hole — admission is now invite-gated by default — the two gates are **redundant**: an Archon already had to admit this person before they could request a box at all. The second approval is a now-pointless second click that an Archon must remember to action (or it strands silently — the same failure mode the 2026-06-15 gate-surface retro called out for stranded approvals).
+
+## Decision
+
+Collapse the two human gates to **one — member-join admission.** Once a member is admitted ([ADR 0050](<redacted>.md)), their first dev box provisions **hands-off** through the existing box-intent runner: `POST /api/gds/box/ensure` enqueues the intent at `state='pending'` straight away (the same state a wake or a subsequent re-provision already uses), and the control-plane runner drains it unchanged. There is no `pending_approval` hold and no first-box approve step.
+
+This **supersedes** [ADR 0035](<redacted>.md) §2 (Decision §2, "A newcomer's FIRST box requires Archon approval") and the **box half** of [ADR 0057](<redacted>.md) (the `#box-approvals` channel and its box-intent approve/deny reaction wiring). The rest of [ADR 0035](<redacted>.md) (§1 Metic+ local clone, §3 the single hosted guide) and the **member half** of [ADR 0057](<redacted>.md) (the `#member-approvals` channel) stand unchanged.
+
+## Consequences
+
+- **The member invite becomes the SOLE human gate before a paid (~$24/mo) box is created.** An admitted Xenos can provision their first box hands-off — the spend is bounded by the fact that a human already chose to admit them, not by a second per-box click.
+- **The box provisioning RANK FLOOR still bounds eligibility.** `BOX_PROVISION_MIN_RANK` ([`src/bongos/boxes.js`](../../src/bongos/boxes.js)) is unchanged: the floor is still the rank-side control on who may have a box at all, and the per-builder "one box at a time" invariant (`box_intents` partial unique index, one `builder_boxes` row) is untouched. Removing the *first-box* gate does not widen *who* qualifies; it only removes the second human click for someone already admitted and already above the floor.
+- **Migration 102 reverts the schema** introduced by migration 071 — the `pending_approval` box-intent state (and any approval-tracking column) is removed; in-flight first-box intents are migrated to `pending` so the runner drains them.
+- **The box-panel "awaiting approval" UI state is removed** — `/builder-box` and the hall box panel no longer surface "your box is awaiting approval," because no box waits.
+- **The `#box-approvals` Discord channel + its box-intent approve/deny wiring are removed** (the box half of [ADR 0057](<redacted>.md)). `#member-approvals` and the admission approve/dismiss wiring stay — admission is still the gate.
+- **The trust-boundary invariant from [ADR 0031](<redacted>.md) §6 is unchanged.** The web tier still only *records a provision intent*; it never holds `DO_API_TOKEN` and never provisions directly. This ADR removes a human approval step, not the control-plane separation.
+
+## Alternatives considered
+
+- **Keep both gates.** Rejected — with admission now invite-gated ([ADR 0050](<redacted>.md)), the first-box gate is a redundant second click on a person an Archon already vetted, and it strands silently when un-actioned. The cost concern it was built for ([ADR 0035](<redacted>.md) §Problem-3) is already covered by admission + the rank floor.
+- **Drop admission and keep first-box approval instead.** Rejected — admission is the stronger control (it gates *all* access, including reading and idea-filing, not just the box), and [ADR 0050](<redacted>.md) deliberately made it the default. Keeping the weaker, narrower gate while dropping the broader one inverts the design.

package/docs/adr/0060-gds-retrieval-layer.md

@@ -0,0 +1,97 @@
+# ADR 0060 — GDS retrieval layer: Postgres-resident, lexical-first, rank-scoped, fail-open
+
+- **Status:** Accepted
+- **Date:** 2026-06-16
+- **Track:** internal
+- **Builds on:** [ADR 0016](<redacted>.md) (server-enforced permissions — the read posture this index must never bypass), [ADR 0043](<redacted>.md) (sub-Metic stay out of the permission/methodology core), [ADR 0024](<redacted>.md) (the memory/learning corpus this indexes), [ADR 0010](0010-pms-architecture.md) (the GDS Postgres this lives in)
+- **Task:** 940 (V4.R02) — locks the architecture for the GDS-V4 "one-call recall" criterion. Implemented by V4.R06 (migration, [#944](https://example.com/builders#/task/944)), V4.R07 (chunker, [#945](https://example.com/builders#/task/945)), V4.R09/R10 (ingesters, [#947](https://example.com/builders#/task/947)/[#948](https://example.com/builders#/task/948)), V4.R11 (search route, [#949](https://example.com/builders#/task/949)), V4.R12 (scoping + isolation suite, [#950](https://example.com/builders#/task/950)); the embedding layer is gated behind the V4.R24 eval ([#962](https://example.com/builders#/task/962)).
+
+## Context
+
+A builder starting a session re-discovers the same project knowledge by hand every time: which ADR covers X, which session log hit this footgun, which task already shipped this. The 2026-06-12 friction analysis of the BFG session corpus put "rediscovery / wrong-path" at the top of the time sinks. The GDS-V4 headline is **one-call recall**: any session, from any machine, can ask "what do we know about X?" and get the relevant docs + DB prose back in one call — *without* the recall layer ever becoming a side-channel that leaks content a builder isn't allowed to read.
+
+Two hard constraints frame every choice below:
+
+1. **Budget + ops (CLAUDE.md §4).** $5k/year, one ~$14/mo droplet, one Node process, one Postgres. A retrieval stack that adds a managed vector DB, a separate search service, or a GPU box is off the table unless lexical-in-Postgres demonstrably can't do the job.
+2. **The trust boundary ([ADR 0016](<redacted>.md) / [ADR 0043](<redacted>.md)).** Some indexed content is rank-gated (permission-core docs are Metic+; a builder's own memory is theirs alone). A search index is a classic read-side bypass: if it returns a snippet of a doc the caller can't otherwise read, the index just defeated the boundary. Scoping is therefore a **first-class, server-enforced** property of the index, not a filter bolted on later.
+
+The 2026-06-12 research report ("GDS retrieval architecture") surveyed the options and recommended **lexical-first, in Postgres**: Postgres ships full-text search (`tsvector`/`tsquery`) and trigram fuzzy match (`pg_trgm`) in the box we already run; the corpus (a few thousand markdown chunks + DB prose rows) is tiny by search standards; and embeddings buy little until a *measured* lexical gap justifies their cost and operational weight. This ADR locks that in.
+
+## Decision
+
+### 1. Substrate — one table in the existing Postgres, no new service
+
+All searchable content is chunked into one table, `search_chunks`, in the GDS Postgres. No new process, no managed service, no network hop. Full-text and fuzzy match run as SQL against this table.
+
+### 2. Schema (`search_chunks`, migration 103 / [#944](https://example.com/builders#/task/944))
+
+```
+search_chunks
+  id            bigserial primary key
+  source_kind   text     not null         -- 'doc' | 'db'  (markdown file vs DB-prose row)
+  source_ref    text     not null         -- e.g. 'docs/adr/0016-....md' or 'task:431' / 'learning:53'
+  chunk_index   int      not null          -- ordinal within the source (0-based)
+  heading_path  text                       -- breadcrumb: 'CLAUDE.md > §8 Versioning > Working rules'
+  title         text                       -- the source's human title (for result display)
+  body          text     not null          -- the chunk text (what gets shown as a snippet)
+  min_rank      text     not null default 'xenos'  -- LOWEST rank that may see this chunk (scoping, §6)
+  owner_builder_id bigint references builders(id)  -- non-null ⟺ a per-builder private chunk (e.g. memory); else NULL = shared
+  content_hash  text     not null          -- sha256 of body; ingestion delta key (skip unchanged)
+  tsv           tsvector                    -- generated/maintained FTS vector over title+heading_path+body
+  created_at    timestamptz not null default now()
+  updated_at    timestamptz not null default now()
+  unique (source_kind, source_ref, chunk_index)
+```
+
+Indexes: a **GIN** index on `tsv` (FTS) and a **GIN `gin_trgm_ops`** index on `body` (trigram fuzzy). `pg_trgm` is enabled via `CREATE EXTENSION IF NOT EXISTS pg_trgm` in the same migration (ships with standard Postgres contrib; no new package). A btree on `(source_kind, source_ref)` supports idempotent re-ingest + delete-by-source.
+
+### 3. Chunking — heading-aware with breadcrumbs (V4.R07 / [#945](https://example.com/builders#/task/945))
+
+Markdown is split on heading boundaries (not fixed byte windows), so a chunk is a coherent section. Each chunk carries a `heading_path` breadcrumb (`File > H1 > H2 > H3`) so a result is self-locating and the snippet has context. Front-matter is parsed (not indexed as body). Over-long sections are sub-split on paragraph boundaries with the breadcrumb preserved. The chunker is a **pure module** (`src/bongos/search-chunker.js`) so both ingesters and the test suite drive it without I/O.
+
+### 4. Ingestion — deploy hook (repo) + nightly timer (DB prose)
+
+- **Repo markdown** (V4.R09 / [#947](https://example.com/builders#/task/947)): a deploy-hook step (`scripts/gds/search-ingest-md.js`) walks the repo's docs/markdown, chunks each file, and upserts. Delta by `content_hash` — unchanged chunks are skipped; vanished sources are deleted. Runs on every deploy so the index tracks `main`.
+- **DB prose** (V4.R10 / [#948](https://example.com/builders#/task/948)): a nightly timer (`scripts/gds/search-ingest-db.js`) ingests prose-bearing DB rows — task descriptions/value summaries, learnings, session-log summaries, recent shipped-task summaries — with a recency boost. Nightly is fresh enough for DB prose; the deploy hook keeps docs current intra-day.
+
+Each ingested chunk is stamped with the `min_rank` of its source (§6).
+
+### 5. Query — lexical hybrid fused with RRF (V4.R11 / [#949](https://example.com/builders#/task/949))
+
+`POST /api/gds/search { q, limit? }` runs **two** retrievers and fuses them:
+
+1. **FTS leg** — `websearch_to_tsquery` against `tsv`, ranked by `ts_rank_cd`.
+2. **Trigram leg** — `body % q` / `similarity(body, q)` via `pg_trgm`, which catches typos, partial tokens, and identifier fragments FTS stems away.
+
+Results are fused with **Reciprocal Rank Fusion** (RRF: `score = Σ 1/(k + rank_i)`, k=60) — rank-based, so the two legs' incomparable score scales don't need normalizing, and a chunk ranked well by *either* leg surfaces. RRF is computed in SQL (a CTE per leg + a fused aggregate) so there's one round-trip. The response returns `{ source_kind, source_ref, heading_path, title, snippet, score }[]`.
+
+### 6. Scoping — per-chunk `min_rank` + owner, server-enforced (V4.R12 / [#950](https://example.com/builders#/task/950))
+
+This is the load-bearing security property, mirroring [`src/bongos/routes/memory.js`](../../src/bongos/routes/memory.js)'s posture:
+
+- Every query is filtered **in the SQL WHERE clause** (not post-hoc in JS) by the caller's **live, server-resolved rank** (`req.builder.rank`, read fresh per request — never from input): `min_rank` must be ≤ the caller's rank in the ladder.
+- A chunk with a non-null `owner_builder_id` (a per-builder private chunk, e.g. memory) is returned **only** to that owner — `owner_builder_id IS NULL OR owner_builder_id = req.builder.id`. There is no parameter to name another builder; the owner is always the authenticated session.
+- Permission-core docs (the [ADR 0043](<redacted>.md) protected set: trust-boundary docs, rank/authz, the ship/grade/deploy pipeline) are ingested at `min_rank='metic'` so a Xenos/Thetes search can never return a snippet of them.
+- **No public/unauthenticated surface.** `POST /api/gds/search` is `requireBuilder`. The public read API ([`src/bongos/routes/public.js`](../../src/bongos/routes/public.js)) gains nothing here.
+- A dedicated isolation suite (`tests/search_isolation.mjs`, in the style of `tests/memory_isolation.mjs`) proves: a sub-Metic query never returns a `min_rank='metic'` chunk; a builder never returns another builder's owned chunk; the filter is in SQL, not a JS post-filter that a future refactor could drop.
+
+### 7. Fail-open to lexical-only
+
+The (future, V4.R24-gated) embedding/semantic leg is **additive and fail-open**: if embeddings are absent, disabled, or error, search degrades to the lexical legs above — it never hard-fails a query. Lexical-first means the system is fully useful with zero embedding infrastructure; embeddings are a later, measured upgrade, not a dependency.
+
+## Consequences
+
+- **Zero new infra / monthly cost.** Search is SQL against the existing Postgres. No vector DB, no search service, no GPU.
+- **The index can never be a read-side bypass.** Scoping is enforced server-side in SQL against the live rank + authenticated owner, identical in spirit to the memory router. The isolation suite is the regression guard.
+- **Lexical is the floor, embeddings are the option.** We ship a useful recall layer now; the embedding go/no-go is a *measured* decision (V4.R24 [#962](https://example.com/builders#/task/962)) against a golden eval set (V4.R01 [#939](https://example.com/builders#/task/939)), and even if adopted it fails open to this.
+- **Freshness is bounded + visible.** Docs track `main` on deploy; DB prose is nightly. Staleness monitoring + a `/watch` tile (V4.R36 [#972](https://example.com/builders#/task/972)) surface a stalled ingest rather than letting it rot silently.
+- **`search_chunks` fattens the nightly `pg_dump`.** Reviewed under V4.R37 ([#973](https://example.com/builders#/task/973)); chunks are derivable from `main` + DB, so the backup could exclude them if size warrants.
+
+## Alternatives considered (rejected)
+
+- **ParadeDB / `pg_search` (BM25 in Postgres).** A real BM25 index would beat `ts_rank`, but it's a non-core extension that must be compiled/installed on the droplet — operational weight and a deploy-time dependency for a corpus small enough that `ts_rank_cd` + trigram + RRF is plenty. Rejected on ops cost vs marginal quality. Revisit only if the golden-set eval shows lexical ranking is the bottleneck.
+- **Standalone vector DB (Qdrant / Weaviate / Pinecone).** A separate always-on service (or per-query SaaS spend) for a few-thousand-chunk corpus — squarely against the budget posture, and it splits the source of truth out of Postgres. Rejected.
+- **Embeddings now (pgvector from day one).** Embeddings cost API spend per ingest + per query and add a provider dependency, for unproven recall gain on a small, jargon-dense corpus where exact-term + trigram match is strong. Deferred behind a measured gate (V4.R24), and even then layered on (fail-open), not depended on.
+- **Local embedding model on the droplet.** A ~$14/mo shared CPU droplet has no headroom to host an embedding model without degrading the game server. Rejected; if embeddings are adopted they go through a serverless provider (the V4.R30 [#966](https://example.com/builders#/task/966) decision), consistent with the LLM-agnostic research ([#1069](https://example.com/builders#/task/1069)) "serverless, not local" finding.
+- **Cross-encoder reranker.** A reranker over the fused top-k would lift precision but adds a model call per query (latency + spend) for a marginal gain at this corpus size. Out of scope; RRF over two lexical legs is the v1 ranker.
+- **Filter scoping in application code (post-query).** Fetch top-k, then drop chunks the caller can't see in JS. Rejected outright: it's the exact read-side-bypass failure mode — a post-filter is one refactor away from leaking, and it can under-fill the result page. Scoping lives in the SQL WHERE clause so an unauthorized chunk is never selected in the first place.

package/docs/adr/0061-context-layer-decomposition.md

@@ -0,0 +1,61 @@
+# ADR 0061 — Context-layer decomposition: a CLAUDE.md content charter + nested per-module docs
+
+- **Status:** Accepted
+- **Date:** 2026-06-18
+- **Track:** internal
+- **Builds on:** [ADR 0016](<redacted>.md) (markdown only describes; the server/DB enforce — so trimming CLAUDE.md can never weaken authority), [ADR 0060](0060-gds-retrieval-layer.md) (the `/recall` retrieval half of "find what we know"; this ADR is the *instruction/navigation* half), [ADR 0024](<redacted>.md) (the Architect, which drives the deeper Path C module refactor)
+- **Task:** 1222 (GDS-V4) — Path A of the 2026-06-18 "context cliff" research.
+
+## Context
+
+This project is almost entirely AI-authored. The owner's worry is concrete: as agents keep adding code and docs, the repo gets harder to scan and an agent's ability to change it safely degrades — a **context cliff**. The literature backs this up:
+
+- **Length alone degrades reliability** — Chroma's *Context Rot* (2025, 18 models): accuracy falls as input grows, even on trivial tasks.
+- **Position matters** — *Lost in the Middle* (TACL 2024): a fact buried mid-context is recalled far worse than at the edges.
+- **Related-but-wrong content misleads** — a single near-miss distractor measurably lowers answers, and a large repo is a distractor factory.
+- **Effective ≪ advertised** — NVIDIA's RULER (2024): usable context is roughly half the advertised window.
+
+CLAUDE.md is the most-loaded artifact we have: Claude Code reads the root **in full, every session, regardless of length**. Anthropic's own guidance is **under ~200 lines**, with the rule *"a bloated CLAUDE.md causes Claude to ignore your actual instructions."* Ours was **351 lines** and mixed three kinds of content — durable framing, live state, and operational rules — so it over-spent the always-on budget *and* drifted (live-state prose goes stale between the DB and the file).
+
+Cursor addresses the same problem by splitting one rules file into many small, **scoped, lazily-loaded** `.cursor/rules` files (loaded only when a matching file is in context). Claude Code has the native equivalent — **nested `CLAUDE.md` files load on demand** when an agent reads a file in that directory — and we were not using it: one root file, zero nested ones.
+
+> On the owner's worry that "CLAUDE.md is deeply ingrained into making everything work": per [ADR 0016](<redacted>.md) it is **descriptive, not authoritative** — the server/DB enforce permissions and the ship pipeline, and editing the file grants no authority. So the risk is *not* that a wrong CLAUDE.md breaks enforcement. The risk is narrower and real: it over-spends the always-loaded context budget, and its live-state prose drifts. This ADR fixes that risk without touching enforcement.
+
+## Decision
+
+### 1. A content charter, stated at the top of CLAUDE.md
+
+A short "Working with this file" section codifies what belongs in the root, with three rules:
+
+- **The per-line test** (Anthropic's): *"Would removing this line cause an agent to make a mistake? If not, cut it."*
+- **The decoder — what goes where:** durable framing + pointers + invariants → this file; live state (tasks/versions/ranks/costs) → the GDS DB; *why* a non-obvious choice was made → an ADR; multi-page how-to → a recipe; specifics of one module → that dir's nested `CLAUDE.md`; short per-rule learnings → the `learnings` table.
+- **A size budget:** the root targets **≤ ~200 lines** (hard ceiling ~250). When it crosses, relocate detail *down the decoder* — don't append.
+
+This is the "best practices for what goes in CLAUDE.md" the owner asked for, kept short so it doesn't itself bloat the file; the full rationale is this ADR.
+
+### 2. Nested per-module `CLAUDE.md` (load on demand)
+
+Thin `CLAUDE.md` files in the highest-traffic directories, loaded by Claude Code only when an agent works there. First set: `src/bongos/`, `src/bongos/routes/`, `scripts/gds/` (the GDS core + CLI, where the monoliths live — `db.js` ~219 KB, `ship.js` ~151 KB, `tasks.js` ~79 KB). Each follows a fixed template:
+
+- **Purpose** — one paragraph: what this directory is for.
+- **Key files / public surface** — the handful of entry points and what each does (the "function block" view — read this, dive into the implementation only as needed).
+- **Gotchas / invariants** — the non-obvious rules that prevent mistakes here.
+- **See also** — the relevant ADRs / recipes.
+
+`CLAUDE.md` (not `README.md`) is deliberate: only `CLAUDE.md` is auto-loaded for the agent; READMEs serve humans. Where a dir already has a README (e.g. `art/`, `migrations/`), the nested `CLAUDE.md` stays a thin pointer + agent-only gotchas.
+
+### 3. Hard invariants live in code, not prose
+
+Anything that must never be skipped is a hook or CI check, not a CLAUDE.md sentence — prose is advisory, gates are deterministic. This is already largely true (`stop-refcheck.js`, `route-rank-check`, the grader pre-pass, `linkify-refs.js`). The charter makes the principle explicit so future rules land in the right layer.
+
+### 4. Freshness is the seam to Path B
+
+Hand-written nested docs will drift exactly like the owner fears. The **factual** half (the "public surface" list) is therefore a generation target for **Path B** — a tree-sitter symbol skeleton regenerated in CI the way `gen-diagrams.js` regenerates diagrams. Until then the *purpose / gotchas / see-also* halves are stable by design (matklad's ARCHITECTURE.md principle: record invariants, not line-level facts that rot).
+
+## Consequences
+
+- The root shrinks toward budget; per-module depth arrives only when relevant — less dilution, better instruction adherence (the documented failure mode).
+- An agent (or human) gets a high-level map of each busy directory without reading every file — the "read generally, then dive in" property the owner asked for.
+- **Risk:** nested docs drift until Path B generates their factual half — mitigated by keeping them thin + invariant-focused, plus a follow-up task for the generator.
+- **Risk:** over-aggressive trimming could drop a load-bearing line — mitigated by *relocating* rather than deleting, and by the per-line test being conservative ("if unsure, keep").
+- A future CI check can enforce the root size budget (filed as a follow-up).

package/docs/adr/0062-medusa-instance-model-decoupling.md

@@ -0,0 +1,107 @@
+# ADR 0062 — Medusa: decoupling the GDS into an instance-model build platform
+
+- **Status:** Accepted
+- **Date:** 2026-06-18
+- **Track:** internal
+- **Builds on:** [ADR 0010](0010-pms-architecture.md) (the GDS architecture being extracted), [ADR 0016](<redacted>.md) (the trust boundary — *core*, survives the split untouched), [ADR 0061](<redacted>.md) (the context-layer charter + nested docs — this ADR makes that the *portable methodology core*), [ADR 0004](0004-example-name-and-trademark-acceptance.md) (the civ-name "single config string" rule — generalized here into the branding contract), [ADR 0024](<redacted>.md) (the grader/architect/onboarding prompts that carry brand and must be parameterized)
+- **Task:** [#1189](https://example.com/builders#/task/1189) (V4.R50) — the spike that **locks the boundary before the R51–R74 structural epics build**. Satisfies the design half of criteria **C8** (decouple the GDS into an instance model — "the GDS builds itself") and frames **C9** (AGPL open-source track).
+- **Amended by:** [ADR 0108](<redacted>.md) — resolves §10's build-sequence assumption that instance content sits at the repo root into the configurable-root composition mechanism (a consumer installs the core as a dependency and injects an instance-root).
+
+> **⚠ Renamed (2026-06-19):** the platform this ADR calls **Medusa** was renamed **Cloud Bongos** by owner directive. This record is kept verbatim as history; the rename decision (and what it touches vs. leaves as history) is [ADR 0064](<redacted>.md). Forward-facing config + docs now read "Cloud Bongos."
+
+## Context
+
+The goal (GDS-V4 Medusa cluster, planning tasks [#1188](https://example.com/builders#/task/1188)/[#1215](https://example.com/builders#/task/1215)): extract the GDS — the build/methodology platform — into **Medusa**, a configurable, self-hostable, AGPL, AI-first build platform. A host project supplies a **branding pack** and selects **feature-modules** (game, art-pipeline, discord, dev-box) that are *off by default*. **Customer 0** = Medusa on a plain vanilla brand, no modules — it builds itself (the C8 proof, [#1206](https://example.com/builders#/task/1206)). **Customer 1** = Example (OTB).
+
+Today it is one fused codebase. A file-grounded coupling analysis (2026-06-18) found four seams:
+
+1. **Process/HTTP** — one Express app + one Colyseus server. The GDS (`/api/gds`, hall, status) mounts host-agnostic *first*; the **game is the fall-through default**, not a module. Good news: `src/rooms/register.js` + `src/preview-server.js` already factor the game-room set out — the cleanest existing seam and the template for the cut.
+2. **DB** — *one shared `pg` Pool*: `src/bongos/db.js` does `require('../db')` and reuses the game's pool. Game tables (`world_events`, `players`, migrations 001/002) and ~78 GDS tables share one pool and one flat migration sequence. `track` is a 2-value `CHECK (track IN ('product','internal'))` column on `versions`, woven into analytics + hall UI — an OTB-specific taxonomy.
+3. **Brand/identity** — leaked, not single-config. "Example" is hardcoded across ~50 hits / 28 files; `example.com` across ~90 (cookie domain `.example.com`, OAuth origin, `*.dev.` SSH allowlist); "drachmae" in 23 files; "Off the Boats"/"Example" baked into **grader/architect/onboarding LLM prompts**. Only `devbox-app/src/brand.js` honors the single-config ideal.
+4. **Methodology/skills** — already clean: `.claude/skills/builder-*` + idea/blocker/planning/status/recall are portable; the four `otb-*` art skills + `stop-sound.js` are host; `art/` is self-contained (no `src/` imports); Discord is already `DISCORD_BOT_ENABLED`-gated.
+
+Why a spike-ADR first: 24 structural tasks (R51–R74) depend on this. They need **one** locked boundary, branding-contract schema, and module mechanism to build against, or they will diverge.
+
+## Decision
+
+### 1. The boundary (the cut-line)
+
+**The engine is host-agnostic and mounts modules; a host is a branding pack + a set of enabled modules.** Invert today's "game is the default fall-through" → the game is a module the OTB instance enables.
+
+| Component | Portable core (Medusa) | Host instance (OTB) | Feature-module (gated) |
+|---|---|---|---|
+| `src/bongos/*` (routes, auth, grader, BFG, onboarding, recall) | ✅ core (prompts templatized) | — | — |
+| `src/bongos/db.js` Pool | ✅ owns its own Pool | — | — |
+| `src/db.js`, `players`/`world_events`, migrations 001/002 | — | ✅ | `game` |
+| `src/rooms/`, `register.js`, `preview-server.js`, `public/` | — | ✅ | `game` (already factored) |
+| `public-builders/` hall + `public-status/` | ✅ *engine* | copy/theme/lore | branding pack supplies strings |
+| `art/` + `otb-*` skills + tile scripts | — | ✅ | `art-pipeline` (self-contained) |
+| `discord-*.js`, `scripts/discord/`, `channels.json` | ✅ *engine* | channel layout + persona | `discord` (already flag-gated) |
+| `box*.js`, `cf-tunnel.js`, `devbox-app/`, box skills | ✅ *engine* | `*.dev.` domains | `dev-box` |
+| `.claude/skills/builder-*`, idea/blocker/planning, hooks | ✅ core | `stop-sound.js`, `otb-*` | — |
+| `versions.track` + by_track analytics/UI | — | the 2-value taxonomy | configurable track set |
+| domains/origins/cookie-domain | reads from config | hardcoded ×90 today | — |
+
+### 2. The instance model
+
+- **Engine entrypoint** (R51, [#1190](https://example.com/builders#/task/1190)): boots Express + `buildGdsRouter()` + hall + status, host-agnostic, **no Colyseus, no game/tile mounts** — sibling to `src/preview-server.js`. Today's `server.js` becomes the *OTB instance boot* (engine + game module).
+- **A host instance** = branding pack (§3) + feature-module flags (§4) + owner/repo/OAuth binding (R62, [#1201](https://example.com/builders#/task/1201)) + its own DB (R52).
+- Customer 0 = vanilla brand, no modules (the dogfood); customer 1 = OTB (game + art + discord + dev-box, drachmae, Greek pack).
+
+### 3. The branding contract (`config/branding.*` — R53 keystone, [#1192](https://example.com/builders#/task/1192))
+
+One per-instance config; **resolution precedence: env var → instance config → neutral starter** (fail to the plain default, never to OTB). A documented schema + neutral starter + an owner-LLM "fill-it-in" prompt. Fields the codebase proves are needed (each hardcoded today):
+
+- **Identity:** `productName`, `worldName` (the in-world / civilization name), `company` (+ site).
+- **Domains:** `publicOrigin`, `buildersOrigin`, `statusOrigin`, `cookieDomain`, box subdomain pattern (`*.dev.`/`sandbox-`/`term-`). *(Load-bearing security strings — a swap must not widen cookie/SSH scope.)*
+- **Currency label** (R56, [#1195](https://example.com/builders#/task/1195)): "drachmae" → configurable; the cost-plus reward **math is unchanged**.
+- **Tracks:** replace the 2-value `product|internal` CHECK with a configurable set (R52, [#1191](https://example.com/builders#/task/1191)).
+- **Theme/palette + copy pack:** hall lore/primer/404 copy, Discord persona, and — critically — the **grader/architect/onboarding prompt brand header** must read the project name from config, or a non-OTB instance grades against the wrong project identity.
+
+Customer 1 (OTB) pack = R57 ([#1196](https://example.com/builders#/task/1196)); vanilla = R74 ([#1216](https://example.com/builders#/task/1216)); the diagram generator reads it (R58, [#1197](https://example.com/builders#/task/1197)).
+
+### 4. Feature-module selection (R54, [#1193](https://example.com/builders#/task/1193))
+
+A **module registry**: each module declares what it contributes — route mounts, hall/status UI sections, skills, disciplines/achievements, DB migrations/tables, Colyseus rooms, pollers, hooks. An instance's config enables a set; resolution gates at mount time (`routes.js`/the entrypoint reads the enabled set). Modules: `game` + `art-pipeline` (R59, [#1198](https://example.com/builders#/task/1198)), `discord` + `dev-box` (R60, [#1199](https://example.com/builders#/task/1199)). The hall's only realtime feature (a Colyseus room) gets a non-Colyseus fallback over the pg-NOTIFY relay so a game-less instance keeps live updates (R55, [#1194](https://example.com/builders#/task/1194)).
+
+### 5. DB carve-out (R52, [#1191](https://example.com/builders#/task/1191))
+
+A GDS-owned Pool reading `DATABASE_URL`/`PG*` (not hard-defaulting to the `example` DB) — sever `src/bongos/db.js`'s `require('../db')`. A GDS-only migration sequence; game migrations 001/002 belong to the `game` module and are simply not applied on a non-game instance. Drop the hardcoded track taxonomy. **The trust boundary ([ADR 0016](<redacted>.md)) and per-request rank enforcement are core and unchanged.**
+
+### 6. Config namespace (R61, [#1200](https://example.com/builders#/task/1200))
+
+Consolidate `OTB_*`/`PMS_*` env prefixes + the `~/.config/otb/` path to a neutral product namespace driven by instance config, with back-compat shims (existing local sessions/boxes keep working). Owner bootstrap from instance config replaces migration 023's hardcoded `github_login='example-owner'` Archon literal (R62, [#1201](https://example.com/builders#/task/1201)).
+
+### 7. Portable methodology core ↔ host context split (folds in [ADR 0061](<redacted>.md) + R66 [#1205](https://example.com/builders#/task/1205))
+
+- **CLAUDE.md becomes the portable methodology core** Medusa ships: the working rules, session protocol, claim→ship lifecycle, the ADR 0061 **content charter**, and the **nested-`CLAUDE.md`** pattern. Instance-agnostic.
+- **The host authors its own project-context file.** The OTB identity (company, vision, world, visual style — today's CLAUDE.md §§3/5/6/7) moves OUT of the shipped core into an instance-owned context doc + the branding pack. This is the concrete meaning of "move the project identity": **it is the core/host split, not tidying.**
+- `medusa init` (R65, [#1204](https://example.com/builders#/task/1204)) scaffolds a new instance's context file from a neutral template + the owner-LLM fill prompt. The AI-first norm ("AI always writes the code") is documented in the core.
+
+### 8. Session logs in the portable core (new task, folds in the redesign)
+
+The §13 hand-maintained in-file index is an OTB-era artifact: it bloats the always-loaded file, drifts, and recurrently breaks (dangling-link bug recurs as idea 57, BFG F2, [#580](https://example.com/builders#/task/580)). Medusa's core ships a **generate-don't-narrate** model instead:
+
+- The **DB session corpus is canonical** (already true — the BFG corpus + ADR 0051 full-transcript capture, [#1004](https://example.com/builders#/task/1004)).
+- The context file carries at most an **auto-generated, bounded "recent sessions" snippet**, regenerated at deploy (the `gen-diagrams.js` pattern, branding-aware per R58); **full history renders in the hall + a generated index.** No instance hand-maintains a session-log index.
+
+**Implemented — task [#1226](https://example.com/builders#/task/1226), 2026-06-19.** `scripts/gds/gen-session-index.js` generates `docs/session-log-index.md` (full history) + a bounded 10-entry snippet injected between markers into CLAUDE.md §13; it runs + commits at **ship** (`ship.js` `regenerateSessionIndex` — the realized form of "the gen-diagrams pattern") and is gated by `gen-session-index --check` in `fitness.js` (Check 5). §12 + the handoff-template drop the hand-maintained-index / manual-compaction chores; CLAUDE.md fell 342→300 lines and `ROOT_HARD_MAX` ratcheted 360→310. Two honest deltas from the wording above: **(a)** the index is generated from the canonical session **prose files** (`docs/session-logs/*.md`), not the DB — "DB corpus is canonical" presumes ADR 0051 transcript capture ([#1004](https://example.com/builders#/task/1004)), still Proposed/unshipped; generating from the files needs no unshipped dependency and makes a link **structurally undanglable** (retires idea 57 / [#580](https://example.com/builders#/task/580)). **(b)** A dedicated **hall** rendering of full narrative history is deferred until [#1004](https://example.com/builders#/task/1004) lands (the existing Archon session-ledger renders the `session_records` digests today); the generated index is the browseable full-history surface meanwhile.
+
+### 9. A → B → C, folded into Medusa
+
+The 2026-06-18 context-cliff research recommended three paths; each becomes a Medusa **core** capability:
+
+- **A — context-layer decomposition** (ADR 0061, [#1222](https://example.com/builders#/task/1222)): the charter + nested per-module docs. This *is* the portable methodology core (§7). Done; carried into R66.
+- **B — generated code/altitude map:** a tree-sitter symbol skeleton, regenerated in CI, feeding the *factual* half of the nested docs so they don't drift — keeping **every** instance's codebase navigable, complementing the recall layer ([ADR 0060](0060-gds-retrieval-layer.md)). (New core task.)
+- **C — fitness functions in CI:** the **enforcement layer for this whole ADR.** A dependency-cruiser/ArchUnit-style gate that (i) prevents host/feature-module code from leaking into the portable core and vice versa — **mechanically enforcing the §1 cut-line and §4 module boundaries so the decoupling cannot silently rot back together** — and (ii) enforces the ADR 0061 CLAUDE.md budget + nested-doc presence, and (iii) asserts no module bypasses the §5 rank checks. Without C the boundary is a hope; with C it is a gate. (New core task — the single highest-leverage guarantee that Medusa *stays* decoupled.)
+
+### 10. Build sequence
+
+R50 (this ADR) → **R51 entrypoint + R52 DB pool** (independent foundations) → **R53 branding contract (keystone — most epics cross-ref it)** → **R54 module system** → parallelizable de-brand epics (R55–R62, R66 CLAUDE.md split, the new session-log + Path-B tasks) → **Path-C fitness functions** (wired as a dep of "decoupling done") → R63 docker / R64 upgrade / R65 init → **R67 C8 proof** (a second, non-game branded instance ships a task). C9 (R68–R73: AGPL ADR/LICENSE, governance, public mirror, delayed export, lineage proof) proceeds on its own track.
+
+## Consequences
+
+- A clear, file-grounded target the 24 epics build against — one boundary, one contract, one module mechanism.
+- The trust boundary + rank enforcement stay core and unchanged; a feature-module must never be able to bypass server-side rank checks (a Path-C assertion).
+- **Hardest knots (called out so the epics plan for them):** (1) shared Pool + flat migrations; (2) the brand-saturated, *not* data-driven hall UI (~50 brand hits, drachmae in 23 files) — the largest mechanical job; (3) inverting game-as-default into a mounted module; (4) domains woven into auth/security — config swaps must not widen cookie/SSH scope; (5) brand inside LLM prompts (grader/architect/onboarding).
+- **Risk: scope.** Mitigation: R53 keystone first; modules incremental; Path-C enforces no regression; customer-0 dogfood ([#1206](https://example.com/builders#/task/1206)) is the falsifiable proof the cut actually worked.