@bongos/core 1.17.0

package/docs/adr/0016-trust-boundary-server-enforced-permissions.md

@@ -0,0 +1,132 @@
+# ADR 0016 — Trust boundary: server-enforced permissions
+
+**Date:** 2026-05-26
+**Context:** GDS-V3, spike [#229](https://example.com/builders#/task/229) (V3.R03 — Architecture spike: server-enforced trust boundary). Satisfies done-when criterion C7 (`three-ranks-gate-everything` / `permissions-enforced-server-side`).
+**Status:** Accepted.
+
+> Numbering note: the spike's done-when named this ADR `0015`, but `0015` was taken by the task-dependencies work before this spike was opened. This ADR is **0016**.
+
+## Problem
+
+GDS-V3 opens the system to more than one builder. Today there is exactly one builder (`example-owner`) and every API route trusts any authenticated session equally. Before a second person holds a session token, we need an explicit answer to: **where does authority live, how is it checked, and what is the exact failure mode when a builder edits their own local files to try to grant themselves more authority?**
+
+The threat is not a malicious outsider breaching the network — that's a different ADR (security basics, C8). The threat here is the *trusted-but-bounded* builder: someone given a real session who should be able to claim and ship tasks but should NOT be able to create tasks, rewrite methodology, close versions, or touch another builder's claim. A Claude Code builder runs with full write access to their own checkout: they can edit `CLAUDE.md`, edit `.claude/skills/*`, edit `.claude/settings.json`, add hooks, and edit any `src/` file locally. None of that local editing power can be allowed to translate into elevated authority over shared state.
+
+So the trust boundary must sit at a place the builder's local machine cannot move: **the server, checking a value the builder cannot write.**
+
+## Decision
+
+Authority lives in **one column in the production database** — `builders.rank` — and is checked **server-side, per request, against the database, with no caching**. Everything a builder controls locally (files, skills, hooks, settings) is *outside* the trust boundary and can only ever *call into* server endpoints that re-check rank themselves.
+
+### Where rank lives
+
+`builders.rank` (Postgres `text` + `CHECK` enum), on the production DB. It is set only by the Archon-only rank endpoint (`PATCH /api/gds/builders/:id/rank`, task [#232](https://example.com/builders#/task/232) / V3.R07). It is never read from a token, a cookie, a file, an env var, or request body. The session token (`builder_sessions.token`) identifies *who* the builder is; it carries no authority claim of its own. Rank is looked up fresh from `builders` on every privileged request.
+
+### How it's checked
+
+`requireRank(...allowed)` middleware (task [#106](https://example.com/builders#/task/106) / V3.R05 defines it; task [#231](https://example.com/builders#/task/231) / V3.R06 applies it to every privileged route) runs *after* `requireBuilder`. `requireBuilder` resolves the session token → `builder_sessions` row → `builders` row, and now also selects `rank`. `requireRank` compares `req.builder.rank` against the allowed set and returns `403 { error: 'rank_forbidden', required: [...], actual }` on mismatch.
+
+**No token-side caching of rank.** The rank is read as part of the same `lookupSession` join that authenticates the request, so it is always the live DB value. Consequence: a demotion takes effect on the demoted builder's *very next request* — there is no stale-token window. This is the single most important property of the design, and it is why rank must not be embedded in the token at issuance time.
+
+### What enforces vs. what merely describes
+
+| Surface | Role | Inside trust boundary? |
+|---|---|---|
+| `builders.rank` (prod DB) | **the** source of authority | ✅ yes — the boundary itself |
+| `requireRank()` middleware on each route | enforcement point | ✅ yes |
+| `PATCH /builders/:id/rank` (Archon-only) | the *only* writer of rank | ✅ yes |
+| `CLAUDE.md`, `docs/`, ADRs | **describe** the permission model for humans/agents | ❌ no — documentation only |
+| `.claude/skills/*` | call server endpoints; cannot grant authority | ❌ no |
+| `.claude/settings.json`, hooks | local automation; cannot grant authority | ❌ no |
+| session token / cookie | identity, not authority | ❌ no (carries no rank) |
+
+The rule that makes this legible: **markdown describes, the database enforces.** If `CLAUDE.md` says "only Archon can create tasks" and the `POST /tasks` route is missing its `requireRank('archon')` check, the *route* is the bug — the markdown is not load-bearing and must never be treated as such. A periodic auditor (below) exists precisely to catch that class of drift.
+
+### Failure mode when a builder edits local files
+
+A builder who edits their checkout to try to elevate themselves hits the boundary and fails, every time, in a defined way:
+
+- **Edits `CLAUDE.md` to say "Thetes can create tasks":** no effect. `POST /tasks` checks `builders.rank` in the prod DB. The doc is descriptive; the route is enforcing. Result: `403 rank_forbidden`.
+- **Edits a skill (e.g. `.claude/skills/builder-claim`) to call a privileged endpoint:** the endpoint still runs `requireRank` against the DB. The skill is just an HTTP client. Result: `403 rank_forbidden`.
+- **Adds a hook / edits `.claude/settings.json`:** hooks run locally and can only invoke the same API surface. No endpoint trusts local state. Result: no elevation.
+- **Forges or replays a token:** the token maps to a `builders` row whose `rank` is whatever the DB says. A Thetes token is a Thetes token no matter how it's presented. Result: bounded to Thetes.
+- **Writes directly to the DB:** only possible with prod Postgres credentials, which are not in the repo and not held by a Thetes builder. That is the C8 (security-basics / secrets-hygiene) boundary, not this one.
+
+In every local-edit case the failure is the same shape — a `403 rank_forbidden` from the server — because the server never consults anything the builder's machine can write.
+
+## Trust-model diagram
+
+```
+                    builder's local machine (UNTRUSTED for authority)
+   ┌───────────────────────────────────────────────────────────────────┐
+   │  CLAUDE.md   .claude/skills/*   settings.json   hooks   src/ edits  │
+   │      │             │                  │           │                 │
+   │      │ describe    │ call             │ automate  │                 │
+   │      ▼             ▼                  ▼           ▼                 │
+   │   (no authority — these can only emit HTTP requests + a token)      │
+   └───────────────────────────────┬───────────────────────────────────┘
+                                    │  HTTPS + Bearer/cookie token
+                                    │  (token = <redacted>, NOT authority)
+================================ TRUST BOUNDARY ============================
+                                    │
+                                    ▼
+   ┌───────────────────────────────────────────────────────────────────┐
+   │  GDS server  (TRUSTED)                                              │
+   │                                                                     │
+   │   requireBuilder  ── token → builder_sessions → builders (+ rank)   │
+   │         │                                                           │
+   │         ▼                                                           │
+   │   requireRank(...allowed)  ── compares live builders.rank           │
+   │         │           │                                               │
+   │      allowed      denied → 403 { rank_forbidden, required, actual } │
+   │         ▼                                                           │
+   │   privileged handler runs                                           │
+   │                                                                     │
+   │   ┌─────────────────────────────────────────────────────────────┐  │
+   │   │  Postgres  builders.rank  ◄── only PATCH /builders/:id/rank   │  │
+   │   │  (the source of authority)     (Archon-only) writes this      │  │
+   │   └─────────────────────────────────────────────────────────────┘  │
+   └───────────────────────────────────────────────────────────────────┘
+```
+
+## Implementation sub-tasks (C7)
+
+These already exist in the GDS as seeded GDS-V3 tasks; this spike sets their `parent_task_id` to [#229](https://example.com/builders#/task/229) so the lineage is explicit. The spike does **not** reshape their scope — it confirms it.
+
+| Task | Rank work |
+|---|---|
+| [#106](https://example.com/builders#/task/106) (V3.R05) | `builders.rank` enum column + `requireRank()` middleware + gate write routes + `/me`/CLI surfacing. Live ranks for V3: **Archon** + **Thetes**. |
+| [#231](https://example.com/builders#/task/231) (V3.R06) | Apply `requireRank()` to **every** privileged route; no privileged route left ungated. |
+| [#232](https://example.com/builders#/task/232) (V3.R07) | `PATCH /api/gds/builders/:id/rank` — the single Archon-only writer of rank. |
+| [#266](https://example.com/builders#/task/266) (V3.R44) / [#267](https://example.com/builders#/task/267) (V3.R45) | periodic auditor that asserts no privileged route is missing a rank check; CLAUDE.md trust-boundary disclaimer. (Confirm exact ids at claim time.) |
+
+### Token-issuance design (resolved here so [#106](https://example.com/builders#/task/106)/[#231](https://example.com/builders#/task/231) don't re-litigate it)
+
+Tokens stay authority-free. `builder_sessions` issuance is unchanged by the rank work: a token is minted at auth time and identifies a builder. Rank is *not* stamped into the token and *not* cached alongside it. The cost of this choice is one extra column read on the existing `lookupSession` join (already a single query) — negligible — bought in exchange for instant demotion and zero stale-authority windows. This is the deliberate trade and it is not to be "optimized" into a cached/token-embedded rank later without a superseding ADR.
+
+## Alternatives considered
+
+**Rank embedded in the session token (JWT-style claim).** Rejected: a stolen/old token would carry stale authority, and demotion couldn't take effect until token expiry. The whole point of putting rank in the DB and reading it per-request is that demotion is instant. The per-request read is one cheap join we already do.
+
+**Rank cached in-process keyed by builder id, with TTL.** Rejected for V3: adds a stale window (= the TTL) for demotion, and a cache-invalidation surface, to save a column on a join that is already happening. Premature optimization for a <10-builder system. Revisit only if `lookupSession` ever becomes a measured hotspot.
+
+**Enforce permissions in skills / CLAUDE.md (client-side).** Rejected — this is the anti-pattern the whole ADR exists to forbid. Anything the builder's machine can edit cannot be the source of authority.
+
+**Filesystem/OS permissions on methodology files.** Partially relevant but orthogonal: methodology files (`CLAUDE.md` etc.) are protected by *who can push to `main` + who can run the deploy*, not by the API. The API trust boundary covers GDS *state* (tasks, claims, ranks, versions). Methodology-file edits are gated by git/deploy access, documented but not API-enforced in V3.
+
+## Consequences
+
+**Good:**
+- One column, one middleware, one writer — a small, auditable trust boundary.
+- Demotion is instant (next request) because rank is never cached.
+- Local-file edits are provably inert against shared authority; the failure mode is uniform (`403 rank_forbidden`).
+- A periodic auditor can mechanically assert the boundary is intact (every privileged route has a `requireRank`).
+
+**Costs:**
+- Every privileged route must remember to call `requireRank`. A forgotten check is a silent hole — mitigated by the auditor task ([#266](https://example.com/builders#/task/266)/V3.R44) which fails loudly when a privileged route lacks a rank gate.
+- Rank read on every privileged request (one extra column on an existing join). Accepted.
+- The two-rank V3 scope (Archon + Thetes) is deliberately minimal; the full ladder in [#106](https://example.com/builders#/task/106)'s enum is reserved but unimplemented, so promoting anyone to a middle rank is a no-op until those ranks gain route grants. Documented, not a bug. **(Superseded by [ADR 0018](<redacted>.md), task [#360](https://example.com/builders#/task/360): the three-rank `xenos`/`metic`/`archon` model went live — `xenos` is now the default entry rank and `metic` the approved working rank, both wired with route grants. The trust-boundary mechanism in this ADR is unchanged; only the set of live ranks widened.)**
+
+**Operationally:**
+- When adding any new write/privileged route, the default is `requireRank('archon')` until a lower rank is explicitly granted — fail closed, not open.
+- `CLAUDE.md` will carry a short disclaimer (task [#267](https://example.com/builders#/task/267)/V3.R45) stating that it *describes* permissions and the DB *enforces* them, so no future reader mistakes the doc for the source of truth.

package/docs/adr/0017-code-simplification-and-repo-cleanliness.md

@@ -0,0 +1,74 @@
+# 0017 — Code simplification & repo cleanliness as a maintained property
+
+- **Status:** Accepted
+- **Date:** 2026-05-27
+- **Deciders:** Lars Kristensen (Archon), Claude
+- **Track:** `internal` (GDS)
+- **Context task:** GDS-V3 [#351](https://example.com/builders#/task/351) (V3.R90). Parent of [#352](https://example.com/builders#/task/352) (V3.R91, substrate), [#353](https://example.com/builders#/task/353) (V3.R92, grader economy lens), [#354](https://example.com/builders#/task/354) (V3.R93, reward), [#355](https://example.com/builders#/task/355) (V3.R94, janitor). Plan: `~/.claude/plans/i-believe-that-a-valiant-giraffe.md`.
+
+## Context
+
+AI-written code accrues bulk. It over-writes, reaches for abstraction it doesn't need, and leaves dead code behind — and then the same agent struggles to read and edit its own output later. The cheaper it is to keep the codebase small and legible, the more reliably an autonomous builder can keep shipping into it. Simplicity is therefore not a stylistic preference here; it is a precondition for the GDS scaling to multiple builders without the repo collapsing under its own weight.
+
+Three gaps make simplicity hard to sustain today:
+
+1. **Simplicity is invisible to the reward system.** The ship-time grader (`src/bongos/grader.js`) scores exactly two axes — `functional_fidelity` and `code_quality` (threshold 6.0, both must pass). Neither measures economy, diff size, or complexity. Diff stats are *already computed* at ship time (`scripts/gds/ship.js` `computeDiffShortstat` → stored in `task_grades.signals.diff_stats`) but never scored.
+2. **The incentive is backwards.** `src/bongos/streak.js` *excludes* `kind='cleanup'` from streak credit — the system mildly penalizes the exact work we want to encourage.
+3. **Cleanliness is reactive and weak.** `/merge-mode` only merges already-built branches. The `overnight-code-review` routine flags dead code as a low-priority, high-confidence afterthought. There is no complexity / dead-code / lint tooling anywhere — `package.json` carried only `"start"` and zero devDependencies before this ADR.
+
+## Decision
+
+We will treat simplicity the way the GDS already treats correctness: **prevent it inline, reward it, and maintain it autonomously.** Three layers, sharing one cheap measurement substrate:
+
+- **PREVENT** ([#353](https://example.com/builders#/task/353)/V3.R92) — the grader gains an *economy* lens at ship time: it judges whether the change is the simplest one that achieves the task, penalizing unnecessary abstraction, premature generalization, duplicated/dead code, and diffs larger than the task warrants. Caught at the cheapest moment, while the author still has full context.
+- **REWARD** ([#354](https://example.com/builders#/task/354)/V3.R93) — stop excluding `cleanup` from streaks; credit net-negative ships (more lines removed than added); add a "Subtractor" achievement. Simplification becomes a rewarded act, not an unpaid chore.
+- **MAINTAIN** ([#355](https://example.com/builders#/task/355)/V3.R94) — a weekly autonomous `repo-simplify-sweep` routine measures the repo, files findings to `idea_inbox`, and auto-fixes a *narrow, safe class* (confirmed dead files) end-to-end so builders never have to think about it.
+
+All three read one substrate ([#352](https://example.com/builders#/task/352)/V3.R91, `scripts/gds/repo-metrics.js` + a `repo_health_snapshots` table + a `/public/repo-health` surface): per-file size, LOC growth by directory, dead-code counts, and branch hygiene.
+
+### Advisory first, then a gate (the economy score)
+
+The economy score ships **advisory first**: recorded on every grade (as a sub-score in `task_grades.rubric_scores`, jsonb — no migration) and feeding `code_quality`, but **not** independently hard-blocking. A legitimately large-but-necessary feature must not be blocked on day one by an uncalibrated threshold. After a few weeks of real scores, a follow-up task promotes economy to a third both-must-pass axis at the existing `grader.js` gate. This mirrors how every gate in this system earned its teeth — measure, calibrate, then enforce.
+
+### Adopt knip as the dead-code detector
+
+We will adopt **knip** (dev-only) as the one tool the substrate and janitor lean on. Rationale:
+
+- **It targets the exact failure mode.** Unused exports and unreferenced files are the residue of AI over-writing — code written, then orphaned. Reliable dead-file/dead-export detection is genuinely hard to hand-roll (it requires building and walking the import graph); knip does it.
+- **Zero production cost.** knip is in `devDependencies`. The droplet deploy runs `npm ci --omit=dev`, so knip and its dependency tree never reach production. No runtime, no monthly cost — consistent with the $5K budget posture. (Its transitive dev-tree does carry npm-audit advisories; these are dev-only and are the concern of the dependency-scan task V3.R38, not prod.)
+- **Config lives in `package.json`, not a new file.** knip reads a `"knip"` key in `package.json`. Embedding it there — rather than adding a root `knip.json` — keeps the footprint minimal, which is the very ethos this ADR encodes. (The task description floated `knip.json`; the package.json key is the simpler in-scope choice and is what shipped.)
+
+The committed config declares entry points (CLI scripts, tests, the browser `public/game/main.js`, the status/builders pages) and the project globs, and lists `phaser` + `colyseus.js` under `ignoreDependencies` because those are loaded as vendored browser globals via `<script>` tags (`public/index.html`), not statically imported — so knip would otherwise report them as unused. The config was trimmed to remove every pattern knip flagged as redundant; it now emits no configuration hints.
+
+### Baseline knip run (the "first janitor backlog") — and a precision rule it taught us
+
+Running knip against the current repo produced:
+
+- **Unused files (2, high precision):** `src/bongos/active-claims.js` (referenced only in seed-script *prose*, never `require`d) and `src/bongos/pulse.js` (referenced only by the separate CLI `scripts/gds/pulse.js` via an HTTP route, never imported). Both are genuine orphan candidates. They are **not** removed under this task — V3.R90's scope (`touches: docs/adr/, package.json, package-lock.json`) excludes editing `src/`. They are recorded here as the first janitor backlog for V3.R94 to triage/remove.
+- **"Unused exports" (143, low precision in this repo):** dominated by **false positives**. This codebase is largely CommonJS consumed via namespace member-access (`const db = require('./db'); db.createTask(...)`), which knip cannot statically trace, so it reports the individual exports as unused even though they are called. Spot-verified: `createTask` is invoked from `src/bongos/routes/tasks.js`.
+- **"Unlisted binaries (1): knip":** an artifact of running via `npx` with no local `node_modules`; it resolves once `npm ci` installs knip into `node_modules/.bin`. Not a real finding.
+
+**The precision rule this establishes (load-bearing for V3.R94):** the janitor's **autonomous auto-fix class is restricted to unused *files* (and, later, confirmed unused *dependencies*)** — high-precision, reversible deletions. Unused-*export* findings are **advisory only**: filed for human/triage review, never auto-removed, because under CommonJS namespace access they are unreliable. This is exactly why the janitor auto-fixes a deliberately narrow class and files everything judgment-heavy.
+
+## Alternatives considered
+
+- **ESLint / a full linter instead of knip.** Rejected as the first tool. ESLint enforces style and catches per-file lint issues but does not build a project-wide reachability graph, so it does not find orphaned files or cross-module dead exports — the actual AI-residue problem. A linter may still be adopted later for a different purpose; it is not a substitute here.
+- **Hand-rolled dead-code detection (git/grep heuristics only).** Rejected for the dead-code signal. Reliable unused-export/unreferenced-file detection means parsing and walking the import graph; a grep heuristic is crude and misses re-exports, dynamic paths, and the CJS cases knip at least surfaces. We *do* keep git/`wc` shell-outs for the cheap size/growth/branch-hygiene metrics in the substrate — those don't need a tool.
+- **Make the economy score a hard gate immediately.** Rejected. An uncalibrated simplicity threshold would block legitimately large features on day one and erode trust in the grader. Advisory-first, then harden, is the safer path and matches precedent.
+- **Keep cleanliness purely reactive (extend `/merge-mode` or `overnight-code-review`).** Rejected as insufficient. The user's explicit goal is that builders should *not* have to think about cleanliness; a reactive merge tool and a correctness-first review routine do not actively reduce bulk. A dedicated, scheduled, partly-autonomous janitor is the mechanism that removes the human from the loop.
+
+## Consequences
+
+**Good:**
+- Simplicity becomes measured (substrate), rewarded (incentive flip), prevented (grader), and maintained (janitor) — four reinforcing pressures instead of zero.
+- The first tool in a zero-tooling repo is a deliberately scoped, dev-only one with no production or monthly cost.
+- The baseline run already produced a concrete, verified backlog and a precision rule that de-risks the janitor's autonomy.
+
+**Costs / commitments:**
+- knip's dev dependency tree adds npm-audit surface (dev-only; owned by V3.R38, not prod).
+- The economy gate must actually be hardened after calibration, or it stays a toothless number — a follow-up task tracks this (filed under V3.R92).
+- The janitor's auto-fix autonomy is bounded by the precision rule above; broadening it beyond unused files/dependencies would need its own decision, because export-level and refactor-level "simplifications" are not safe to apply unattended in a CJS codebase.
+
+**Operationally:**
+- Run dead-code detection with `npm run knip`. For the trustworthy signal, scope to files/dependencies (`knip --include files,dependencies`); treat the exports report as advisory.
+- The ADR index that records permissions/architecture decisions is `docs/adr/README.md`; this ADR is indexed there. (CLAUDE.md references ADRs in prose but is not edited here — it is outside this task's declared `touches`.)

package/docs/adr/0018-three-rank-model-goes-live.md

@@ -0,0 +1,97 @@
+# ADR 0018 — The three-rank model goes live (Xenos → Metic → Archon)
+
+**Date:** 2026-05-27
+**Context:** Task [#360](https://example.com/builders#/task/360), follow-up to the V3.R86 ([#305](https://example.com/builders#/task/305)) CLAUDE.md audit. Advances GDS-V3 criterion
+C2 (`three-ranks-gate-everything`). Builds on (and partially supersedes) [ADR 0016](<redacted>.md).
+**Status:** Accepted.
+
+## Problem
+
+The V3.R86 audit surfaced that the project carried **two conflicting rank models**:
+
+- **Enforced** (migration 023 / task [#106](https://example.com/builders#/task/106)): a deliberately-minimal **two-rank** model — `archon`
+  plus `thetes` as the default for any new builder, with `xenos` used only as the
+  deactivation/offboarding tier (migration 025). `metic` was reserved but unwired.
+- **Planned** (the V3 planning seed's criterion C2 + the skills): a **three-rank** model — **Xenos**
+  (default, sandboxed: read-only + ship only explicitly-open tasks), **Metic** (Archon-approved
+  working rank: full claim/ship + idea triage + blocker review + planning/priority sessions),
+  **Archon** (rank promotion, ratification, version close, infra).
+
+The two models *disagreed on fundamentals*: the default rank (`thetes` vs `xenos`), the name of the
+approved working rank (`thetes` vs `metic`), and the role of `xenos` (exit tier vs entry tier).
+Several skills (`priority-session`, `planning-session`) gate on a `Metic+` rank that wasn't live, and
+`priority-session`'s gate (`xenos`→block, `metic|archon`→proceed) didn't even handle a live `thetes`.
+This is exactly the doc↔DB drift ADR 0016 warns about, except here the *plan of record* (criterion
+C2) was the three-rank model while the *implementation* shipped two.
+
+Lars chose to resolve it by **wiring the three-rank model for real** rather than ratifying the
+two-rank reality.
+
+## Decision
+
+Three ranks are now LIVE: **`archon`** (top), **`metic`** (approved working rank), **`xenos`**
+(sandboxed entry default). `thetes` becomes reserved. The 16-value CHECK enum (migration 023) is
+unchanged — `metic` and `xenos` were already reserved values, so going live is a code + default
+change, not an enum migration.
+
+### What each live rank can do
+
+| Operation | Xenos | Metic | Archon |
+|---|:--:|:--:|:--:|
+| Read public surfaces, `/me` | ✅ | ✅ | ✅ |
+| File an idea / blocker, capture a learning, log cost | ✅ | ✅ | ✅ |
+| Claim + ship **own** work | only `xenos_claimable` tasks | any ready task | any ready task |
+| Idea triage (`PATCH /inbox/:id`) | ❌ | ✅ | ✅ |
+| Blocker review (`POST /blockers/:id/{resolve,link}`) | ❌ | ✅ | ✅ |
+| Planning / priority sessions | ❌ | ✅ | ✅ |
+| Create / promote / edit tasks, deps, confirm, done-when scope | ❌ | ❌ | ✅ |
+| Grant/revoke rank, offboard, version close, infra | ❌ | ❌ | ✅ |
+
+> **Update (2026-06-26, [ADR 0090](<redacted>.md)):** the *"Create / promote / edit tasks, deps"* part of row 7 moved to **✅ for Metic** — a Metic may now author + shape tasks (`POST /tasks`, `PATCH /tasks/:id`, `POST /tasks/:id/promote`, and the `tasks/:id/{dependencies,criteria}` CRUD). `confirm` (grader-bypass), `done-when` *scope*-setting, abandon, rank, and version-close stay Archon-only (row 8 is unchanged). The table above is preserved as the 2026 record; ADR 0090 is the current authority.
+
+### Mechanisms
+
+- **Default flip (migration 029):** `builders.rank` DEFAULT `'thetes'` → `'xenos'`. Not retroactive;
+  affects only builders created from now on. Blast radius today is zero (only `example-owner`/archon exists).
+- **Xenos sandbox (migration 029 + `db.claimTask`/`claimTasksBatch`):** new column
+  `tasks.xenos_claimable boolean NOT NULL DEFAULT false`. A `xenos` may claim a task only if it's
+  `true`; otherwise the claim path throws `XENOS_RESTRICTED` (→ 403). An Archon opens a task to Xenos
+  via `PATCH /api/gds/tasks/:id { xenos_claimable: true }`. This is a **row-level** rule, not a route
+  gate — it can't live in `requireRank` because it depends on the specific task being claimed.
+- **Metic route grants:** the triage/review routes criterion C2 assigns to Metic widened from
+  `requireRank('archon')` to `requireRank('metic','archon')`: `PATCH /inbox/:id`,
+  `POST /blockers/:id/{resolve,link}`. Everything that mutates *plan/scope* (task create/promote/edit,
+  dependencies, confirm, done-when, rank, version close) stays Archon-only — the fail-closed default.
+
+### Why this didn't need skill changes
+
+Adopting the three-rank model makes the skills' *existing* rank checks correct without edits:
+`priority-session`'s gate (`xenos`→stop, `metic|archon`→proceed) is now exactly right because `metic`
+is a real promotable rank and `xenos` is the real default. The per-skill *enforcement flips* that are
+still advisory (e.g. `planning-session` → V3.R88) remain their own tasks; this ADR makes the ranks
+they reference real.
+
+## Consequences
+
+**Good:**
+- Target (criterion C2) and shipped now agree; the doc↔DB divergence the audit found is closed.
+- A new teammate starts sandboxed and is *deliberately* promoted to Metic before they can ship freely
+  — the "vet before they can ship" property C2 wanted.
+- The trust boundary is unchanged in shape: authority still lives in `builders.rank`, checked
+  server-side per request with no caching (ADR 0016). This ADR only widens *which* ranks are granted.
+
+**Costs / follow-ups:**
+- New surface to keep gated: any future Metic-eligible review route must remember `requireRank('metic','archon')`;
+  any plan-mutating route stays `archon`. The periodic auditor ([#266](https://example.com/builders#/task/266)/[#267](https://example.com/builders#/task/267)) covers the "no ungated
+  privileged route" half but does **not** assert the *correct* rank — that stays a review concern.
+- **Not** in scope here (tracked separately): per-skill enforcement flips (`planning-session` V3.R88),
+  marking criterion C2 fully satisfied (Archon does that after verifying the `/builders` hall shows
+  rank + the auditor is green), and updating the onboarding rank-ladder diagram
+  (`docs/onboarding/diagrams/02-rank-ladder.mmd`, which lives on a newer `main` than this branch).
+
+## Supersedes
+
+The "two-rank V3 scope (Archon + Thetes) is deliberately minimal" bullet in
+[ADR 0016 §Consequences](<redacted>.md#consequences) is
+superseded: the middle/entry ranks are no longer all reserved-and-unwired — `metic` and `xenos` are
+live as of this ADR.

package/docs/adr/0019-red-team-bounty-payout-table.md

@@ -0,0 +1,52 @@
+# ADR 0019 — Red-team bounty payout table by severity
+
+- **Status:** Accepted
+- **Date:** 2026-05-27
+- **Deciders:** Lars, autonomous builder (V3.R65 / [#284](https://example.com/builders#/task/284))
+
+## Context
+
+GDS-V3's incentive structure (criterion C9) adds a **red-team bounty**: a builder who finds and reports a security vulnerability against the system earns drachmae for it. The mechanism that *files* a report (`vulnerability_reports`, R63 / [#282](https://example.com/builders#/task/282)) and the mechanism that *auto-confirms and pays* one (R68) both need to agree on a single thing — **how many drachmae a report is worth, given its severity.**
+
+Without one authoritative table, each consumer would invent its own constants and they would drift. We also need the numbers to be **tunable** by an Archon (the only rank that controls economy levers): if the bounty proves too generous or too stingy in practice, adjusting it should be an environment change, not a code edit and redeploy.
+
+Drachmae are the project's in-world currency, stored as integer `delta` in `credit_log` (migrations/003_pms.sql). A bounty payout is therefore a plain integer count of drachmae in the same unit as a task's `credits_reward`. The "10c / 50c" shorthand in the task spec maps to 10 / 50 drachmae; there is no sub-drachma denomination.
+
+## Decision
+
+We will define the bounty payout table in `src/bongos/security.js` as four **default** integer amounts, each overridable by an environment variable:
+
+| Severity | Default drachmae | Env override |
+|---|---|---|
+| low | 10 | `GDS_BOUNTY_LOW` |
+| medium | 50 | `GDS_BOUNTY_MEDIUM` |
+| high | 200 | `GDS_BOUNTY_HIGH` |
+| critical | 1000 | `GDS_BOUNTY_CRITICAL` |
+
+`security.js` exports `bountyTable()` (the flat `{low,medium,high,critical}` map, env applied) and `bountyTableDetailed()` (ordered rows carrying the default, the live value, and whether it was overridden) so that R68's award logic and the /builders hall both read the same source. The env merge happens once at module load, validated as a non-negative integer with fallback to the default — a typo in the env can never silently zero or negative-pay a bounty.
+
+The table is surfaced read-only on the `/builders` hall under a **"Red-team rewards"** heading, served by a public read endpoint (`GET /api/gds/public/bounty-table`), mirroring how `/public/grades` exposes the grader rubric as a single source of truth.
+
+### Why these tier amounts
+
+The four tiers span two orders of magnitude (10 → 1000), which is the right shape for a bounty: it must be cheap to reward a flood of low-severity nitpicks without draining the treasury, yet pay a genuinely motivating sum for the rare catastrophic find.
+
+- **low = 10** — roughly the floor of a trivial task reward. Enough to acknowledge a real but cosmetic finding (info leak with no exploit path, minor misconfig) without inviting noise-farming.
+- **medium = 50** — ~5× low. A real flaw that needs specific conditions; comparable to a small bug-fix task.
+- **high = 200** — ~4× medium. Privilege escalation, broad data exposure, auth bypass — work that would have cost us materially if shipped.
+- **critical = 1000** — 5× high, 100× low. RCE, full account/rank takeover, treasury drain. Deliberately the single largest payout in the economy so a builder who finds one is unambiguously rewarded above any normal task.
+
+The geometric spacing (≈4–5× per step) matches industry bug-bounty convention (e.g. CVSS-banded payouts) and keeps the ranking legible: each tier is visibly "a different league," not a smooth gradient a reporter would argue over.
+
+## Alternatives considered
+
+- **Hardcoded constants, no env override.** Simplest, but fails the done-when tunability requirement — and the right number is genuinely uncertain until we see real reports, so we want to retune without a deploy.
+- **A `bounty_payouts` DB table editable via an API.** More flexible (Archon edits via UI, audit trail). Rejected as over-engineered for V3: there are exactly four numbers and they change rarely; an env var is the cheapest lever that still satisfies "Archon can tune without code." A DB-backed table can supersede this later if retune frequency justifies it.
+- **Linear amounts (e.g. 10/20/30/40).** Rejected — the whole point of a severity bounty is to make a critical find pay dramatically more than a cosmetic one; linear spacing under-rewards the finds we most want.
+
+## Consequences
+
+- One module (`src/bongos/security.js`) is the source of truth for bounty amounts. R68's award logic imports `bountyTable()` rather than re-deriving constants — no drift.
+- An Archon retunes any tier by setting the env var on the droplet and restarting the process (consistent with every other GDS env knob; takes effect next restart, not live).
+- The /builders hall shows the live table — builders always see the current bounty, and an overridden tier is visibly marked so the displayed number is never stale relative to prod config.
+- The amounts are a starting point, not gospel. If reports cluster at one tier or the treasury feels the cost, retune via env first; promote to a DB-backed editable table only if env churn becomes a chore.

package/docs/adr/0020-security-model-public-stub.md

@@ -0,0 +1,70 @@
+# ADR 0020 — Security model — public stub (full ADR is server-side)
+
+**Date:** 2026-05-28
+**Context:** Task [#287](https://example.com/builders#/task/287) (V3.R68), GDS-V3 criterion C9. Companion to [ADR 0019](<redacted>.md) (bounty table), [ADR 0018](<redacted>.md) (rank model), [ADR 0016](<redacted>.md) (server-enforced trust boundary).
+**Status:** Accepted.
+
+## Problem
+
+A security ADR worth writing is a security ADR worth attacking. The threat model — every authenticated surface, every privileged write, every assumption the server-enforced trust boundary leans on, and the specific defenses each leg relies on — is the most attacker-useful document in the project. Committing the full version to the public repo would hand a roadmap to anyone clipping the project.
+
+But we *also* need this document to exist and be readable by trusted builders (Archon, Metic) — otherwise the system has no shared model of how it defends itself, and every new privileged route ends up reinventing the threat-list ad hoc. The red-team bounty (criterion C9) only makes sense if Metics know roughly where the surface is.
+
+We've already adopted [ADR 0016](<redacted>.md): authority lives on the server, not in the repo. The same logic applies to the security ADR itself — its content should live where its enforcement does.
+
+## Decision
+
+The **full security ADR is server-side**, served by a Metic+-gated endpoint and stored *outside this repo*. This file is the **public stub**: enough framing that a reader (or future builder) understands the structure and knows where to look, but with no specifics an attacker could weaponize.
+
+### What lives where
+
+| Surface | Where | Who reads it |
+|---|---|---|
+| Public stub (this file) | `docs/adr/<redacted>.md`, in the repo | anyone with the repo |
+| Full security ADR | A markdown file on the droplet at the path named by `GDS_SECURITY_ADR_PATH` (recommended: `/etc/example/security-adr.md`, owned by the deploy user, `chmod 600`) | the server process, on read; Metic+ via API |
+| Public read endpoint | none | — |
+| Authenticated read endpoint | `GET /api/gds/security/adr` — `requireBuilder` + `requireRank('metic','archon')` — returns the markdown body verbatim under `{ adr_md, source: <path>, fetched_at }` | Metic, Archon |
+| Missing-file handling | If `GDS_SECURITY_ADR_PATH` is unset or the file is unreadable, the endpoint returns `404 { error: 'security_adr_not_provisioned', hint: '…' }` with the same rank gate in front (so existence-or-not isn't leaked to a Xenos) | — |
+
+### What's in the full ADR (categories, not contents)
+
+The full ADR is structured as:
+
+1. **Trust boundary mechanics** — the actual implementation of [ADR 0016](<redacted>.md) per route: which routes are gated, by what rank, where the rank read lives in the request lifecycle, and what fails closed.
+2. **Threat model** — the set of attackers we model (sandboxed builder, malicious Metic, leaked GitHub OAuth, supply-chain compromise, lost laptop) and what each can and cannot do under the current design.
+3. **Defense-in-depth inventory** — per privileged surface, the specific layers in front of it (rank check + audit log + rate limit + input validation + content TTL + …) and why each layer was chosen. This is the section that would most directly aid an attacker.
+4. **Known weaknesses** — the specific places where a defense is thinner than we'd like, with the reasons we haven't fixed them yet (deferred to a later version, cost/benefit, etc.). Highest sensitivity.
+5. **Red-team bounty alignment** — how a confirmed vulnerability_report maps onto the table in [ADR 0019](<redacted>.md), where the auto-confirmation path lives (R67/R68), and which surfaces are explicit invitations vs. out-of-scope (e.g. droplet-host vulns vs. application vulns).
+
+Each section is updated when the underlying mechanism changes. The full ADR is the *living* document; this stub is the *pointer*.
+
+### Why not just chmod the repo file?
+
+The Example repo is on GitHub. Marking a single file private is awkward (git history exposes it; collaborators see everything). The cleanest available primitive is "the file is on the droplet, the server reads it, the API gates access." That collapses to the same trust boundary [ADR 0016](<redacted>.md) already enforces for everything else.
+
+### This is not security-through-obscurity
+
+The defense doesn't depend on the ADR's secrecy. Every protection mentioned in the full ADR is independently enforced in code (rank middleware, audit log, input validation, etc.). Withholding the document raises the cost of an attacker's reconnaissance — it doesn't *create* the defense. The bounty table ([ADR 0019](<redacted>.md)) names the gain for the attacker who reverse-engineers it anyway: a high-severity finding pays out 1000 drachmae. The system *wants* serious red-teamers; what it doesn't want is to hand them the map for free.
+
+## Alternatives considered
+
+- **Commit the full ADR to the repo.** Simplest. Rejected for the reason above: highest-leverage document for an attacker.
+- **Encrypted file in the repo (e.g. age-encrypted blob).** Possible, but key-management overhead for every Metic + the encrypted blob is still public. The trust boundary already gives us "authenticated reads," so reusing it is cheaper.
+- **Private companion repo.** Considered. Adds a second-repo coordination problem (every Metic needs access; secrets-in-repo policy needs to cover two repos; CI doesn't see it). The droplet-file approach concentrates surface area without sacrificing access.
+- **Notion/Google Doc.** Rejected for the same reason all project state lives in the GDS + git: third-party SaaS dependencies for canonical authority drift over time. The droplet is already the source of truth for everything else server-side.
+
+## Consequences
+
+- The full security ADR exists at `GDS_SECURITY_ADR_PATH` on the droplet, not in the repo. Provisioning is a one-time Archon action; the file persists across deploys (it lives outside the repo working tree).
+- New builders see the public stub (this file) when reading the ADR index. The stub tells them how to read the full ADR once promoted to Metic+.
+- Any change to the *real* defenses (new gated route, new redaction rule, new rate-limit knob) updates the full ADR on the droplet. Significant structural changes (new threat-model attacker, new defense category) also update this public stub.
+- The `GET /api/gds/security/adr` endpoint exists *now* (V3.R68 / [#287](https://example.com/builders#/task/287)) but returns the not-provisioned placeholder until an Archon writes the file. That's intentional — the endpoint is the contract, the file is the content.
+- A Xenos hitting the endpoint sees `403 rank_forbidden` whether or not the file is provisioned — the rank gate runs before the file-existence check, so existence of the document isn't leaked downward.
+
+## Cross-references
+
+- [ADR 0016](<redacted>.md) — the server-enforced trust boundary the security model rests on.
+- [ADR 0018](<redacted>.md) — the three-rank model whose gates the security ADR documents.
+- [ADR 0019](<redacted>.md) — the payout table a confirmed vulnerability_report maps onto.
+- Migration [<redacted>.sql](../../migrations/<redacted>.sql) — the report intake table (R63).
+- Migration [033_audit_log.sql](../../migrations/033_audit_log.sql) — the audit ledger every privileged write lands in (R35).

package/docs/adr/0021-per-builder-skill-model-preferences.md

@@ -0,0 +1,99 @@
+# ADR 0021 — Per-builder skill model preferences + skill-efficiency audit
+
+**Date:** 2026-05-28
+**Context:** Task [#304](https://example.com/builders#/task/304) (V3.R85), GDS-V3 cost-discipline cross-cutting. Promotes idea_inbox [#21](https://example.com/builders#/idea/21); pulls forward a minimal slice of PMS-V4 idea [#30](https://example.com/builders#/idea/30).
+**Status:** Accepted (mechanism only; per-skill refactor + execution-time hook deferred to follow-up tasks).
+
+## Problem
+
+Today every slash-command skill runs on whichever model the user launched. Two things are wrong with that:
+
+1. **Mechanism vs judgment is conflated.** A skill like `/builder-claim` is structurally a shell around `scripts/gds/claim.js` — there is no LLM judgment in claiming a task. Yet it runs on whatever model the user's session is on (typically Opus 4.7), which burns budget on parsing + formatting that a `node` invocation does for free. Conversely, `/planning-session` IS the judgment — it sets a whole version's scope-truth — and demoting it for cost saving would be exactly the wrong move.
+2. **There's no per-builder lever.** CLAUDE.md §2 documents a project-wide policy ("default to Opus, Haiku for plumbing") that doesn't survive contact with multi-builder reality. A builder who wants Sonnet for everything except priority-session has no way to express that without editing skill files.
+
+The cross-cutting ask in [#304](https://example.com/builders#/task/304) is to make the trade-off explicit per skill AND tunable per builder.
+
+## Decision
+
+We will ship the **mechanism**: a per-builder storage + UI + API surface for picking a model per skill, plus an audit-classified set of system defaults. The **per-skill refactor** (extracting mechanism into pure scripts) and the **execution-time hook** (skills actually reading the preference at invocation) are filed as follow-up tasks and tracked separately.
+
+The split is deliberate. The storage + UI + audit is load-bearing infrastructure — once it exists, the per-skill refactors can land independently (different skill, different week, different builder). The reverse order doesn't work: refactoring a skill without somewhere to encode the preference produces an orphaned commit.
+
+### What ships now
+
+1. **Migration 037 — `builders.skill_model_prefs jsonb`** (single column, default `'{}'`). A jsonb map from skill name → model token. Per-builder, sparse — missing keys fall back to the system default.
+2. **`src/bongos/skill-prefs.js`** — pure module. Exports `ALLOWED_MODELS`, `KNOWN_SKILLS`, `SKILL_DEFAULTS`, `getDefault()`, `getForBuilder()`, `listEffective()`, `validatePatch()`, `applyPatch()`. The single source of truth that the API, the UI, and any future skill hook read from.
+3. **`GET /api/gds/me/skill-prefs`** — returns `{ prefs, effective, defaults, known_skills, allowed_models }`. The UI consumes `effective` (which already merges override > default) plus `allowed_models` (drives the dropdown options).
+4. **`PATCH /api/gds/me/skill-prefs`** — body is `{ <skill>: <model> | null }`. `null` clears the override; missing skills are untouched (partial updates are first-class). Unknown skill names or unknown models → 422 with a structured errors array.
+5. **`/builders` profile UI** — new section "The Voice Behind Each Skill" rendering one row per skill with the system default + a dropdown for the builder's override.
+6. **This ADR** — captures the audit + the design + the deferred items.
+
+### What's deferred (follow-up tasks)
+
+- **Per-skill refactor.** Each skill listed below as `default: 'script'` should actually be a script wrapper — today most of them already are (the `builder-*` slash commands shell out to `scripts/gds/*.js`), but the SKILL.md files still invite the LLM to parse the JSON output. Refactor per-skill is one-task-per-skill.
+- **Execution-time hook.** Skills currently don't read `skill_model_prefs` when they run. The intended hook: each SKILL.md gets a top-line `Subagent model:` line resolved against `getForBuilder()` at invocation time, and any `Agent` tool call inside the skill passes the resolved model explicitly. That requires touching each SKILL.md plus a small helper script.
+- **Cost measurement before/after.** Today we have `cost_log` rows by `category` but not by `(category, skill)`. Adding a skill-attribution column + a measurement window post-rollout is its own task.
+
+These three are filed as new tasks at idea_inbox (kind=cleanup or refactor) so the deferred work is visible.
+
+### Audit — what each skill is structurally
+
+The audit pass walked every `.claude/skills/*/SKILL.md`, classified each step as **mechanism** (deterministic; no model judgment needed) or **judgment** (the model is the load-bearing thing), and picked a system default:
+
+| Skill | Default | Why |
+|---|---|---|
+| `builder-start` | script | wraps `start.js` — format-output only |
+| `builder-claim` | script | wraps `claim.js` — atomic DB write |
+| `builder-release` | script | wraps `release.js` |
+| `builder-exit` | script | wraps `onboarding-ship.js` (offboarding flow) |
+| `builder-cost` | script | wraps `cost.js` — direct row insert |
+| `otb-figma-sync` | script | direct Figma API push |
+| `builder-ship` | sonnet | mostly mechanism, but drafts handoff notes + value summary (light judgment) |
+| `idea-triage` | opus | walks the inbox and proposes promote/discard/merge verdicts — heavy judgment |
+| `blocker-review` | opus | similar — walks blockers, drafts resolutions |
+| `merge-mode` | opus | resolves merge conflicts, decides which branches go first |
+| `planning-session` | opus | sets a version's scope — the highest-judgment skill in the project |
+| `priority-session` | opus | reweights the inbox via plain-speech survey |
+| `otb-builder-setup` | sonnet | long-form env walk-through; once-per-builder |
+| `otb-tile-generate` | sonnet | orchestrates Gemini image gen + review; light judgment |
+| `otb-design-review` | sonnet | orchestrates Gemini vision; light judgment |
+| `otb-feedback-capture` | sonnet | converts speech to style-guide rule; medium judgment |
+
+Six skills sit at `script` — the cleanest cost wins, and the simplest to hook (just don't invoke the LLM at all). Five sit at `opus` — the project-default and the right call. Five sit at `sonnet` — middle tier, where the budget lever is most useful.
+
+### Why jsonb on `builders` and not a separate table
+
+- The natural read shape is "what does THIS builder prefer for skill X" — keyed on builder primary key. A separate table forces a join.
+- Sparse + irregular (most builders won't override most skills). jsonb's natural shape.
+- Adding a new skill = one line in `KNOWN_SKILLS` + one line in `SKILL_DEFAULTS`. No backfill, no migration. A table would force coordinated schema + code change every time.
+- Analytics queries ("how many builders override planning-session?") are rare enough to do via jsonb operators when needed.
+
+If V4 retires per-skill defaults in favor of per-skill-*kind* defaults (the broader idea [#30](https://example.com/builders#/idea/30) reshape), the jsonb stays — only the helper changes.
+
+### Why these four model tokens
+
+`opus`, `sonnet`, `haiku`, `script`. The first three match the project-wide subagent routing vocabulary (CLAUDE.md §2). `script` is the deliberate "no LLM" sentinel — important because a skill marked `script` doesn't just save tokens, it commits to running deterministically. Without it, the only way to express "this skill has no judgment moment" would be to remove it from the matrix, which loses the audit signal.
+
+## Alternatives considered
+
+- **Per-skill defaults only, no per-builder override.** Simpler. Rejected — the ask in [#304](https://example.com/builders#/task/304) is explicitly "builder-toggleable." A project-wide policy + the ability to deviate is what aligns multi-builder reality with cost discipline.
+- **Separate `builder_skill_prefs` table.** More flexible for analytics, easier to migrate one preference type without touching jsonb shape. Rejected for V3 — see above. Can supersede this later if analytics frequency justifies it.
+- **Resolve overrides only at skill-execution time, no GET endpoint.** Possible, but then the /builders UI has no source of truth — it'd have to mirror `SKILL_DEFAULTS` in JS, which is exactly the kind of drift the helper module exists to prevent.
+- **Validate model tokens via Postgres CHECK constraint on the jsonb.** Rejected — jsonb CHECK is awkward to express, and the API-level validation catches the same class of errors with a structured error message. The DB layer is defensive (uses jsonb's type system to reject non-string values), not authoritative.
+- **Ship the full refactor + hookup atomically.** Tempting (one PR, complete done-when). Rejected because (a) [#304](https://example.com/builders#/task/304) is genuinely a multi-task project (1 mechanism PR + ~6 per-skill refactor PRs + 1 hook PR + 1 measurement PR), (b) the mechanism is independently useful (the audit alone tells builders what the system thinks each skill is for), and (c) shipping the mechanism gives every subsequent skill task a stable consumer.
+
+## Consequences
+
+- A builder can deviate from CLAUDE.md §2's default-Opus posture per skill, via the /builders UI. Power-users tune; new builders inherit sensible defaults.
+- The audit (the table above) is now in code, not just CLAUDE.md prose — visible at `src/bongos/skill-prefs.js` and rendered in the UI. Stays honest as new skills land (the `KNOWN_SKILLS` sanity check at module load catches drift).
+- Today, the storage exists but nothing reads `effective` at skill-execution time. The per-builder choice has no effect until the hookup task lands. The UI surfaces this honestly — the dropdown says "Set X → Sonnet" but the runtime still uses whatever model the user launched. Acceptable as the bootstrapping step.
+- The `script` default for six skills is a *commitment* — those skills should not invoke the LLM for judgment. The next time one of them is edited, the editor sees `default: 'script'` in this ADR and adjusts the SKILL.md to delegate to the wrapper script.
+- Adding a new skill in V4: one line in `KNOWN_SKILLS`, one line in `SKILL_DEFAULTS`, ship. No migration.
+
+## Cross-references
+
+- [Migration 037](../../migrations/<redacted>.sql) — the schema change.
+- [`src/bongos/skill-prefs.js`](../../src/bongos/skill-prefs.js) — the helper module and source of truth for defaults.
+- [`tests/skill_prefs.mjs`](../../tests/skill_prefs.mjs) — unit coverage for the pure helpers.
+- [ADR 0017](<redacted>.md) — same spirit: keep judgment work intentional, mechanism work cheap.
+- CLAUDE.md §2 — the project-wide subagent routing policy this ADR sits beside (not replaces — the policy is the default the matrix opens with).