@bongos/core 1.17.0

package/docs/adr/README.md

@@ -0,0 +1,208 @@
+# `docs/adr/` — Architecture Decision Records
+
+This folder holds short markdown files, one per significant decision, recording **why we chose what we chose**. Originally proposed by Michael Nygard (2011), now standard practice in well-run codebases.
+
+The point: when a future session asks *"why are we using a Cloudflare Origin Cert instead of Let's Encrypt?"* the answer is in one place, not scattered across session-log prose.
+
+## When to write a new ADR
+
+Write an ADR when:
+
+- A choice between meaningful alternatives was made (Stack A vs B, vendor X vs Y, pattern P vs Q)
+- The decision is **non-obvious** — meaning a reasonable person could have chosen differently
+- The decision will outlive the current session — anyone reading code in 6 months might wonder why
+
+Do **not** write an ADR for:
+
+- Routine implementation details (what to name a function, how to structure a small file)
+- Decisions that are forced by an external constraint (we use Postgres because the migration script requires it — that's a chain reaction, not a decision)
+- Anything reversible in <10 minutes
+
+## File naming
+
+`NNNN-kebab-case-title.md`. Numbers are zero-padded to 4 digits, monotonically increasing. Once a number is assigned, it is never reused, even if the ADR is later superseded.
+
+## ADR template
+
+```markdown
+# NNNN — {Title}
+
+- **Status:** Accepted | Superseded by NNNN | Deprecated
+- **Date:** YYYY-MM-DD
+- **Deciders:** {names}
+
+## Context
+
+What problem are we trying to solve? What constraints apply? What did we know at decision time? Keep this short — one or two paragraphs.
+
+## Decision
+
+The decision itself, in plain language. Start with "We will…".
+
+## Alternatives considered
+
+Bullet list of the options we evaluated and why we did not pick them. This is the most valuable part for future readers — it shows the shape of the trade-off.
+
+## Consequences
+
+What follows from this decision? What does it cost us? What does it commit us to? What becomes harder, and what becomes easier?
+
+If this decision creates a known limitation, link to the relevant `limitations/` entry.
+```
+
+## Superseding an ADR
+
+When a later decision overrides an earlier one, **do not edit the old ADR**. Instead:
+
+1. Write a new ADR documenting the new decision and why the old one no longer holds
+2. Edit the old ADR's `Status:` line to read `Superseded by NNNN — {short reason}`
+
+This keeps the decision history honest and traceable.
+
+## Index
+
+| # | Title | Topic |
+|---|---|---|
+| 0001 | [Stack choice — single VPS](<redacted>.md) | infra (game-stack choice) |
+| 0002 | [DigitalOcean over Hetzner](<redacted>.md) | infra (game hosting) |
+| 0003 | [Cloudflare Origin Cert over Let's Encrypt](<redacted>.md) | infra / TLS (game domain) |
+| 0004 | [Example name + trademark acceptance](0004-example-name-and-trademark-acceptance.md) | brand |
+| 0005 | [Invisible other players in V1](<redacted>.md) | gameplay |
+| 0006 | [Singleton WorldRoom + QueueRoom](<redacted>.md) | game architecture |
+| 0007 | [Persistent identity via localStorage UUID](<redacted>.md) | game identity |
+| 0008-a | [Family-based tile generation](<redacted>.md) | art pipeline |
+| 0008-b | [Google Chat OAuth user auth](0008-google-chat-oauth-user-auth.md) | chat broadcast |
+| 0009 | [Autotile architecture](0009-autotile-architecture.md) | art pipeline |
+| 0010 | [GDS architecture](0010-pms-architecture.md) | GDS |
+| 0011 | [Terrain-id rendering model](0011-terrain-id-rendering-model.md) | game rendering |
+| 0012 | [Ground-object cell split](<redacted>.md) | game world data |
+| 0013 | [Paths as object overlays with autotile dispatch](<redacted>.md) | game world data |
+| 0014 | [Families canonical over vocabulary](<redacted>.md) | art pipeline |
+| 0015 | [Task dependencies + auto-promotion](<redacted>.md) | GDS |
+| 0016 | [Trust boundary — server-enforced permissions](<redacted>.md) | GDS / security |
+| 0017 | [Code simplification & repo cleanliness as a maintained property](<redacted>.md) | GDS / methodology |
+| 0018 | [Three-rank model goes live (Xenos → Metic → Archon)](<redacted>.md) | GDS / security |
+| 0019 | [Red-team bounty payout table by severity](<redacted>.md) | GDS / security |
+| 0020 | [Security model — public stub (full ADR is server-side)](<redacted>.md) | GDS / security |
+| 0021 | [Per-builder skill model preferences + audit](<redacted>.md) | GDS / cost discipline |
+| 0022 | [Secrets policy — what counts, where it lives, how rotation works](0022-secrets-policy.md) | infra / security |
+| 0023 | [Kind multipliers + staged idea bonus](<redacted>.md) | GDS / drachmae economy |
+| 0024-a | [Cloneable repo + local-first memory with server-canonical sync](<redacted>.md) | GDS / per-builder memory |
+| 0024-b | [Multi-Agent System (MAS) architecture](<redacted>.md) | GDS / MAS |
+| 0025-a | [Offsite backup vendor: DigitalOcean Spaces](<redacted>.md) | infra / backup |
+| 0025-b | [Structured criterion↔task link (`task_criteria`)](<redacted>.md) | GDS / criterion tracking |
+| 0026 | [The BFG: documentation/memory hygiene + cross-builder learning + transparent correction](<redacted>.md) | GDS / MAS Phase 6 |
+| 0027 | [The BFG session-inefficiency evaluator (auto-post-mortem of builder sessions)](<redacted>.md) | GDS / MAS Phase 6 (6D) |
+| 0028 | [Honest LLM-spend accounting (grader envelope cost + session transcript pricing)](<redacted>.md) | GDS / cost ledger |
+| 0029 | [Status-page outage resilience (measure from outside, host off-box, prevent at source)](<redacted>.md) | infra / status dashboard |
+| 0030 | [Builders-hall live updates via Postgres NOTIFY → WebSocket](<redacted>.md) | GDS / builders hall |
+| 0031 | [Cloud dev environments for builders (Claude Desktop → SSH → containerized DO box)](<redacted>.md) | infra / dev environments |
+| 0032 | [Discord as a one-way mirror of the GDS (outbound broadcast moves off Google Chat)](0032-discord-mirror-of-gds.md) | GDS / team communication |
+| 0033 | [Discord bot as a service principal (account-linking, both-mode upvoting, role-sync, inbound retirement)](<redacted>.md) | GDS / team communication |
+| 0034 | [`thetes`: a 4th live rank for graduated newcomers, with auto-graduation after 3 ships](<redacted>.md) | GDS / builder onboarding |
+| 0035 | [Builder onboarding: three setup paths (Local / DO Box / Remote Control)](<redacted>.md) _(§2 first-box approval superseded by ADR 0059)_ | GDS / builder onboarding |
+| 0036 | [Builders subdomain + builder-UI reorganization (hall / watch / settings / status)](<redacted>.md) | GDS / builder UI |
+| 0037 | [Bot-managed Discord channels from a config file, Archon-gated commands](<redacted>.md) | Discord bot / channel layout |
+| 0038 | [Chromebook/browser on-ramp via a box-hosted ttyd web terminal over a Cloudflare Tunnel (replaces `claude rc`)](<redacted>.md) | GDS / builder onboarding |
+| 0039 | [Setup-first onboarding UX: two-config selector + action-only Path checklist](<redacted>.md) | GDS / builder onboarding |
+| 0040 | [Remote Control is the default browser-only on-ramp (reverses 0038's "RC is dead" verdict)](<redacted>.md) | GDS / builder onboarding |
+| 0041 | [Temporary global grader-bypass kill-switch (`GRADER_BYPASS_ENABLED`)](<redacted>.md) | GDS / shipping pipeline |
+| 0042 | [Builder self-deploy: CI auto-deploy on main + PR auto-merge (no builder box holds the prod key)](<redacted>.md) | GDS / shipping pipeline |
+| 0043 | [Git/SSH trust-boundary gap + a rank floor on permission-sensitive paths](<redacted>.md) | GDS / trust boundary |
+| 0044-a | [Full Mediterranean palette replacement (not a split)](0044-mediterranean-palette-replacement.md) | Art pipeline / palette |
+| 0044-b | [Per-box live game preview (the builder sandbox)](<redacted>.md) | GDS / builder experience |
+| 0045 | [Dev Box desktop app (menu-bar / tray switch for the builder box)](<redacted>.md) | GDS / builder experience |
+| 0046 | [Sandbox-first review in the dev-box ship flow (stage → review → ship)](<redacted>.md) | GDS / shipping pipeline |
+| 0047 | [Discord #bugs intake → GDS tasks, straight-through with a layered anti-abuse guard](<redacted>.md) | GDS / Discord bot |
+| 0048 | ["Works in Progress" IA split: work board owns it, status mirrors a thin slice](<redacted>.md) | GDS / builder UI |
+| 0049 | [The split parallel-safety contract (detect-at-merge for humans, gate for the autonomous runner)](<redacted>.md) | GDS / methodology |
+| 0050 | [Device-Flow admission posture: invite-gated by default (with an `OTB_OPEN_XENOS_ENROLLMENT` escape-hatch)](<redacted>.md) | GDS / builder onboarding |
+| 0051 | [Full session transcripts in the BFG corpus (with transcript-grade scrubbing)](<redacted>.md) | GDS / BFG |
+| 0052 | [Sandbox for everyone: a game-only preview entrypoint + the game in the starter clone](<redacted>.md) | GDS / dev boxes |
+| 0053 | [Scoped, short-lived dev-box session + apex-cookie strip at the tunnel (SR#2/#11)](0053-scoped-dev-box-session.md) | GDS / dev boxes + security |
+| 0054 | [Flat cost-plus session token reward (drachmae as equity): reward = round(true_cost_usd × 1.20 × 100), server-priced from per-model tokens, idempotent per session_id](<redacted>.md) | GDS / economy |
+| 0055 | [Server-mediated branch publish (the dev box holds no GitHub credential): box uploads a thin bundle, the GDS pushes + opens the PR + auto-merges with a server-side PAT](<redacted>.md) | GDS / dev boxes + ship pipeline |
+| 0056 | [Version-control the prod deploy script as a reviewable mirror (`scripts/deploy/deploy-prod.sh`), and retry the post-restart `/healthz` so a slow service bind no longer false-fails a successful deploy](<redacted>.md) | GDS / deploy pipeline |
+| 0057 | [Approve new members and first dev boxes from Discord: two Archon-only channels where a 👍/👎 fires the existing admit (`access_requests`) / first-box (`box_intents`) approve action, re-checked against the reactor's live rank](<redacted>.md) _(box half superseded by ADR 0059)_ | GDS / Discord + onboarding |
+| 0058 | [Automatic gate-surface gatekeeper (rank-based auto-approval + deterministic hard floor)](<redacted>.md) | GDS / shipping pipeline |
+| 0059 | [Single approval: remove the dev-box (first-box) Archon approval gate — collapse to one human gate (member-join admission); an admitted builder's first box provisions hands-off](<redacted>.md) | GDS / builder onboarding |
+| 0060 | [GDS retrieval layer: Postgres-resident, lexical-first (FTS + pg_trgm fused with RRF), rank-scoped, fail-open — the "one-call recall" architecture (no new infra; embeddings deferred behind a measured gate)](0060-gds-retrieval-layer.md) | GDS / recall + search |
+| 0061 | [Context-layer decomposition: a CLAUDE.md content charter + nested per-module `CLAUDE.md` (load on demand) to fight the AI-authored "context cliff" — keep the always-loaded root lean, push module depth to where it's used](<redacted>.md) | GDS / methodology + context |
+| 0062 | [Medusa: decouple the GDS into an instance-model build platform — the cut-line (portable core / host instance / gated feature-modules), the branding-contract schema, the feature-module selection mechanism; folds in the CLAUDE.md core/host split + the A→B→C context plan](<redacted>.md) | GDS / Medusa decoupling |
+| 0063 | [Generated code symbol skeleton (the repo map): a deterministic, zero-dependency, CI-regenerated altitude map — top exported symbols by reference frequency + per-dir signatures — that feeds the factual half of the nested `CLAUDE.md` docs so they can't drift (Path B; complements the prose recall layer with code)](<redacted>.md) | GDS / context + repo map |
+| 0064 | [Rename the platform **Medusa → Cloud Bongos** (owner directive): whole-platform rename, history preserved — canonical config identity + forward docs renamed, historical records (ADR 0062 body, logs, migrations, the R50–R74 task descriptions) kept as-is; amends ADR 0062](<redacted>.md) | Cloud Bongos / branding |
+| 0065 | [Cloud Bongos is **AGPL-3.0, non-profit, and AI-first**: AGPL closes the hosted-closed-fork (SaaS) loophole — the only license consistent with the anti-monopoly goal; non-profit + capture-resistant governance (never monetized from contributors); AI-first as a documented norm, not a technical gate; defines the public-mirror boundary (portable core + platform published; host identity/secrets/content + a ~6-month redaction window never). Rejects MIT/Apache (capture), GPL (SaaS loophole), BSL/open-core (not OSS), CLA-relicensing (capture). The C9 keystone — gates R69–R73](<redacted>.md) | Cloud Bongos / open-source governance |
+| 0066 | [Generated file-map sections: generate the `.claude/skills/` + `.claude/scheduled-tasks/` trees of `docs/file-map.md` from disk, with per-entry notes in a sidecar (`docs/file-map.notes.json`); `--check` fails CI on drift or an undescribed skill/routine (Path C), so a new skill can't land un-mapped and the doc-hygiene follow-up task is retired. Leaves the curated `scripts/gds/` highlight list hand-written.](<redacted>.md) | GDS / context + file map |
+| 0067 | [Fast-forward the checkout to origin/main at session start when safe (clean `main` full clone, strictly behind) — the warn-only→pull-when-safe reversal of the SessionStart freshness step; still warns in every unsafe case (feature-branch worktree, dirty, diverged, partial clone); event-driven freshness, not a faster cron](<redacted>.md) | GDS / dev boxes + methodology |
+| 0068 | [Shared Gemini art key delivered from the GDS to newcomers](<redacted>.md) | GDS / art pipeline |
+| 0069 | [Builders-hall live updates move from a Colyseus WebSocket room to an SSE endpoint (`GET /api/gds/live`) so the hall refreshes live on a game-less Cloud Bongos boot (R55, C8). Supersedes ADR 0030's §2 transport only — the `NOTIFY` + `live-channel.js` signal layer is unchanged; same opaque zero-leak `nudge`, `requireBuilder` gate, per-IP cap kept inline (no `src/rooms/` import). Deletes the room + join-guard; the hall stops loading `/vendor/colyseus.js`. EventSource auto-reconnect replaces the manual rejoin backoff.](<redacted>.md) | GDS / builders hall |
+| 0070 | [Deterministic delivery of in-session cards (hook-delivered, read-only vs mutating)](<redacted>.md) | GDS / context |
+| 0071 | [Dev-box teardown confirms the DigitalOcean droplet is actually deleted BEFORE marking the GDS row 'destroyed' (idempotent + retried; a failed delete parks at 'error' with droplet_id preserved, never a silent zombie); adds a bidirectional `reconcile-drift` sweep (force-delete zombie droplets no live row claims, mark ghost rows whose droplet vanished) on an hourly timer, with an in-flight young-droplet guard. Fixes the running-but-'destroyed' zombie that froze a box on old code.](<redacted>.md) | GDS / dev boxes |
+| 0072 | [Bongos app ships Mac-signed + notarized first; Windows code signing deferred (BV1.R01, C1). Reuses the Dev Box app's signing identity verbatim — the same Apple Developer ID + the inert-until-armed, `main`-ref-gated (SR-13/SR-14) Mac block — rather than minting a new cert; declines a Windows cert for now, riding the existing Windows-only blocker [#20](https://example.com/builders#/blocker/20) (Azure Trusted Signing vs EV). One cert decision serves both apps once they merge into the umbrella. $0 new recurring cost; Windows users keep the "Run anyway" first-run friction until blocker [#20](https://example.com/builders#/blocker/20) resolves.](<redacted>.md) | Bongos app / packaging |
+| 0073 | [The secrets scan excludes TruffleHog's generic URI detector. It flagged a `scheme://userinfo@host` SSRF-guard rejection-test fixture (and, fatally, a URL quoted in a fix commit's message — TruffleHog scans commit messages, which `--exclude-paths` cannot reach), reddening every PR off main once a dev-box tunnel host stopped resolving (ADR 0071). Excluding the URI detector on both scan surfaces loses no real coverage — connection-string secrets (postgres://, mysql://, …) keep their dedicated detectors. Lesson: exclude noisy detectors at the detector level, and keep commit messages free of credential-shaped URLs.](<redacted>.md) | GDS / CI gates |
+| 0074 | [The memory map stays light (budget guard + auto-tidy + drawer)](<redacted>.md) | GDS / memory |
+| 0075 | [Per-system cost attribution + the savings counterfactual ledger (System 1 of the LLM-reduction redesign). Corrects LLM pricing to flat Opus 4.8 rates (no 1M premium); splits the single `session` `cost_log` row into call-site-tagged rows (`session:<redacted>, `cron:<routine>:*` via `OTB_COST_CRON_ROUTINE`) each carrying a per-tier USD split (migration 123); adds a `cost_baseline` table (migration 124) where every later system records a `priceUsage()`-computed counterfactual (never client-supplied) so savings are `SUM(baseline−actual)` by system; surfaces `by_source`/`by_tier` (cache_read share) / `savings` as additive blocks on the unchanged `/public/cost-summary`, with the audit folding them in plus a `savings_without_baseline` tripwire. Turns the 82%-cache_read finding from an inference into a queryable column.](<redacted>.md) | GDS / cost ledger |
+| 0076 | [In-session deterministic compaction (System 2 — the only lever on the 82% marathon-cache_read pool, est 20-40%). A pure classifier (`.claude/hooks/eviction-policy.js`) finds provably-stale `tool_result` blocks (superseded reads, duplicate reads, old uncited bulk dumps) and replaces each with a one-line recovery stub; never touches user/assistant/reasoning turns, the context-pack, worktree guidance, the last N turns, or the newest read of a file; a backward-reference liveness scan keeps anything a later turn cites. Batched ONLY at the PreCompact boundary (per-turn would invalidate the prompt cache); recovery is retrieval-first via the stub → `/recall` (search.js) / re-Read / tool-rerun loop, with a one-time directive that prevents re-fetch loops. Wired behind `OTB_INSESSION_COMPACT`, OFF by default (wire, don't arm). Spike 1347 measured ~24% realized headroom on real transcripts.](<redacted>.md) | GDS / context + cost |
+| 0077 | [Content-addressed LLM cache (System 5 — the residual safety net, est 2-5%). Memoizes idempotent model runs at the single shared spawn primitive (`grader.runSubagent`): an identical (normalized-prompt, model, task_type, git-tree-SHA) invocation over UNCHANGED inputs replays a stored result at ZERO new tokens. Validity is bound to the git SHA of the embedded inputs (self-invalidating — a real change always re-runs); the per-task-type normalizer registry strips only provably-volatile lines and is the correctness surface. Stores only on exit_code===0 (never a timeout); the wrap (`runSubagentCached`) is opt-in and behavior-preserving; a hit returns cost_usd:0 and records the saving into `cost_baseline` (ADR 0075). First plug-ins: architect-audit (tree-scoped) + onboarding-analyze (immutable session id). v1 is exact-match; semantic match deferred.](<redacted>.md) | GDS / cost |
+| 0078 | [Deterministic-first cron harness (System 4 — stop wrapping a committed script in an Opus session, est 3-6%). A routine declares `mode: deterministic\|hybrid\|judgment` + `steps:` in SKILL.md frontmatter; `run-routine.js` runs deterministic routines as plain node with NO model launched (hybrid escalates to `claude -p` only on a `needs_judgment` payload). peer-vote-tally + diagram-drift converted (their scripts already self-file); main-audit (trust-boundary core, ADR 0043) + dep-audit-nightly parked (their security scripts don't self-file — converting would drop alerting). A fitness check (`checkDeterministicRoutines`) fails CI if a deterministic body carries judgment/mutation instructions (git push/commit, deploy.sh, Edit/Write, synthesis — negated boundary mentions allowed) or its prose commands diverge from its steps, so the boundary can't rot back into a wrapped session. Cron-line repoint is an operator action.](<redacted>.md) | GDS / cron + cost |
+| 0079 | [Value-gated autonomous engagement (System 3 — the autonomous-spend lever, est 8-14%; **SHIPPED INERT**). Merges three spawn decisions behind one off-by-default flag (`OTB_AUTONOMY_ENABLED`): a $0 deterministic precheck (`autonomy-gate.js`) that NO-GOs a nightly routine on no-signal nights or a spend-brake (audited in `autonomy_runs`, migration 126); a cascade router (`cascade-dispatch.js`) that drafts a spawn on the cheapest sufficient model and escalates only on an objective signal, never above the builder's ceiling; and a safe_autofix lane that collapses review→triage→rebuild into one fix-and-ship run — permitted ONLY when high-confidence + single-file + not a protected path + the grader is LIVE (never while GRADER_BYPASS is on). BUILT DISABLED per owner directive: decide() returns GO and autofixAllowed() returns false by default, so wiring changes nothing until armed alongside the grader rework. Does NOT touch marathon spend (that's System 2 / ADR 0076).](<redacted>.md) | GDS / autonomy + cost |
+| 0080 | [LLM-cache API transport + trust model (System 5 — the transport that finally lets the content-addressed cache of ADR 0077 hit). Its two consumers (`architect-audit.js`, `onboarding-analyze.js`) run as CLI/cron on builder machines where the `pg` pool is unreachable (peer-socket only), so every cache op silently degraded to miss/no-store and the cache never hit organically (eval task 1372: 0 rows, 0 hits despite correct logic). Fix: expose the cache over the GDS API — `POST /api/gds/llm-cache/lookup` + `/store` in `src/bongos/routes/llm-cache.js`, each mapping 1:1 onto the existing `llm-cache.js` DB helper (the route never reimplements SQL; `/store` mounts its own 512 KB body parser since a full subagent stdout exceeds the global 64 KB cap). `llm-cache.js` self-routes: pool first (memoized `poolReachable()` — a `false` is never memoized so a boot blip can't permanently disable the server cache), else an injected `apiCall` fallback (`setApiFallback`), so the always-on server core never statically requires the CLI layer (preserving the core↔host boundary the fitness gate guards). Best-effort end-to-end: any pool/network/auth error degrades to miss/no-store and never throws. Trust model (load-bearing): a store writes a `result_stdout` a later run replays at $0 and trusts, so an open store endpoint is a content-injection vector into the planning pipeline and a metrics-integrity vector into the public savings number — hence rank-gated, reusing the ADR 0016 server-enforced trust boundary.](<redacted>.md) | GDS / LLM cache + cost |
+| 0081 | [Tool-agnostic design layer — the repo (design tokens + component code + exported assets) is the single source of truth; Claude Design, Figma, and any future design tool are SWAPPABLE ADAPTERS against that neutral contract, not hardwired integrations (the ADR 0062 core↔host pattern applied to design — vendor-lock-in insurance the owner asked for). Splits a `ui` discipline out of `artist`/graphics (UI = design-as-code, graded by diff + screenshot; graphics = pixel art, graded by vision). Code-canonical round-trip: structured UI round-trips as code, freeform canvas art is a committed asset; a talented human can still edit directly in Figma and the change round-trips into the repo via a normal GDS task (the escape hatch). One ship pipeline + ONE multimodal grader with a single regen loop, parameterized by type (rubric + evidence chosen by task type) — retires the standalone Gemini vision path and the two-grader-set maintenance trap. Claude Design adapter = code-native /design-sync + Claude Code handoff; Figma adapter = human-edit→code + code→Figma sync. Grader/ship changes ride the gate-review hard floor (ADR 0043). Implementation cluster tasks 1376–1380.](<redacted>.md) | GDS / design pipeline |
+| 0082 | [Server-side auto-resolution of generated-file & append-index merge conflicts: the publish-reconciler runs a temp-clone `git merge origin/main` with the `otb-regen` driver + a `docs/adr/README.md merge=union` attribute active, then pushes the resolution so a PR that conflicts ONLY on generated indexes or the ADR append-index self-heals server-side (GitHub's own merge can't run the custom driver) — the PR #300/[#167](https://example.com/builders#/task/167) stall. Pushes a commit (all required checks re-run), aborts to a human on any genuine hand-conflict, best-effort + kill-switchable; zero trust-boundary change (rejects the alternative of lowering deploy access to `thetes`).](<redacted>.md) | GDS / CI + merge |
+| 0083 | [Practical build plan for the modular architecture (strangler migration) — the decision record that turns the scoped design research (`docs/design/modular-architecture/`, 5 docs) into a concrete, CI-guarded, one-module-at-a-time build. Builds the whole product into `core + modules`: a ~3.5k-LOC kernel + ~16 modules, each a vertical slice reached through ONE published, semver'd doorway (`src/module-api.js` — the only core file a module may import); a loader that discovers/validates/mounts `modules/*/module.json` behind kernel-composed auth and replaces the closed `KNOWN_MODULES` registry in `src/modules.js`; modules talk only through kernel-mediated seams (ports + events), never by importing each other. Boundaries are held by fitness functions (a violation is a red build), not discipline — five new `fitness.js` checks (core-never-imports-a-module, <redacted>, module-route-rank-gate via parameterizing `route-rank-check.js`, core-carries-no-module-code, module-migrations-additive+namespaced). Module-owned migrations generalize the working `migrations/game/` enabled-gated precedent to `modules/<key>/migrations/`. Reorganize, NOT rewrite (the foundation is sound, the filing is wrong); stay single-package/single-process/no-bundler (modularity is a separate axis). Moves ordered by MEASURED isolation: dev-box (the template) → game → discord → art-pipeline; the recurring seam is `routes/me.js` + `settings.js`, cut by a module→core contribution hook. task→module affinity (retire `touches[]`) is the final-tier follow-on. Reconciles the numbering collision: the design docs + epic [#1388](https://example.com/builders#/task/1388) + task [#1389](https://example.com/builders#/task/1389) call this "ADR 0080", but 0080 is the LLM-cache — the module-system record is THIS file. Seeds BONGOS-V1 criterion C5 + the BV1.R## children.](<redacted>.md) | GDS / architecture |
+| 0084 | [Auto-derived per-task rank floor — every task is rank-scoped and the claim gate finally BITES. `tasks.requires_rank` (V3.R82) + the claim-time gate (`db.claimTask` → `INSUFFICIENT_RANK`) + the `/builder-start` hide were all sound but INERT: no create/edit path ever set `requires_rank`, so every task took the `NOT NULL DEFAULT 'xenos'` and anyone at thetes+ could claim anything. Fix: `deriveRequiredRank(touches, security_sensitive)` derives a floor by reusing the SAME protected-path matcher as the trust boundary (`permission-path-check.matchProtected`, ADR 0043) — the rank/authz/ship-grade/deploy/migration core (the paths a sub-Metic builder already can't push) floors at `metic`, game/art/docs stay `xenos`; never auto-assigns `archon`. `highestRank(floor, requested)` composes it with an Archon override that can only RAISE (a request below the floor is clamped up; `POST`/`PATCH /tasks` accept `requires_rank`, Archon-only; flipping `security_sensitive` ratchets up). Migration 145 backfills every non-terminal task (raise-only, idempotent, SQL generated faithfully from `PROTECTED_GLOBS`). Hall shows a rank pill. One sensitivity source of truth shared with the git-push floor, so claim-floor and push-floor can't drift.](<redacted>.md) | GDS / authz |
+| 0085 | [Builders are uncapped by default — removes the default $50/mo per-builder spend cap. `classifyCostStatus` no longer falls back to a project default: a `NULL`/`<=0` `monthly_budget_usd` now means UNCAPPED (`level:'ok'`, `budget_mtd_usd:null`, nothing blocks), and the `DEFAULT_MONTHLY_BUDGET_USD=50` constant is deleted. Reverses the default-cap half of GDS-V3 C3 (task 302): the default blocked the very work it was meant to enable — a new builder's own `session:<redacted> API cost crossed $50 within a day and froze /builder-ship + the art pipeline (builder 95 hit $69.32 MTD on day two). KEEPS the Archon override (`PATCH /builders/:id/budget`) as a manual emergency brake — a positive value still enforces warn(≥80%)/over(≥100%). Cost recording + the /public/cost-summary dashboard are unchanged (removes blocking, not observability). No schema change; project-wide guards (autonomy-gate, art HARD_STOP) unaffected.](<redacted>.md) | GDS / cost ledger |
+| 0086 | [Goal-scoped work hierarchy — assign goals, not tasks. Introduces a `goal` tier and a six-level hierarchy (Project → Version → Goal → Criteria → Task → Sub-task) whose structure is a per-instance config preset (`config/hierarchy.json`, owner-set at onboarding — the ADR 0062 pattern) and whose enforcement is core. A goal is a SHARED, joinable, module-scoped workspace: joining grants bounded authority to author tasks within the goal's `scope_modules` (the wall, set by a trusted rank at planning, never self-granted; widened only by an approved request — Archon for protected modules). Reuses almost everything: criteria re-parent under goals (`done_when_criteria.goal_id`; `/status` rolls up Version→Goals→Criteria→Tasks), sub-tasks stay `parent_task_id`, the per-task rank floor is the auto-derived one (ADR 0084), dependencies become a polymorphic blocked-until-done edge resolved at the claim gate (ADR 0015 — cross-goal allowed, reference-not-grant). Achievement auto-flags when a criterion's tasks ship, then a planner (Metic+) confirms via a new `/goal-review` skill (idea-triage-style), auto-flipping the goal achieved. Deterministic scope + protected-path gate at create; the ship-time grader/gate-review/main-audit stay authoritative on the real diff. Deferred to follow-ons: the reward model, sub-Metic membership in protected-scope goals (amends ADR 0043), and an AI relevance judge. Fills ADR 0083 Rule 5 ("a task is scoped to a module").](<redacted>.md) | GDS / work hierarchy |
+| 0087 | [Bongos app architecture + the model-agnostic feedback handoff contract (BONGOS-V1 / C4). Records the umbrella desktop app that absorbs the Dev Box app as a module, the capture→synthesize→handoff pipeline (R04–R14), and the Rung-3 *visual* capture floor (pixels + voice + freeze-frame markup over any app) with element-level reads deferred to V2 (Accessibility requested lazily, never up front). The contract: a bundle is a self-contained `~/CloudBongos/feedback/<id>/` dir where every screenshot is referenced by ABSOLUTE FILE PATH, never base64 — so the text prompt stays ~5–11k tokens and any agent opens the frames with its own file read. One shared `latest` pointer (atomic `latest.json` + best-effort symlink, self-healing) feeds three readers that can't drift: Claude Desktop (clipboard + open folder, R12), Claude Code (`/feedback` slash command cats prompt.md + Reads the frame paths, R13), and an optional zero-dependency stdio MCP server (`get_latest_feedback` returns text + file paths, never base64, R14). Hand-rolled MCP (newline-delimited JSON-RPC, no SDK dep) keeps the install surface flat. Bongos succeeds the GDS as the primary builder surface after GDS-V4; a fourth agent is an adapter, not a redesign. $0 new recurring cost.](<redacted>.md) | Bongos app / feedback loop |
+| 0088 | [Consistent-character generative animation — a generate→grade→audit→regenerate loop built by EXTENDING the existing family pipeline (ADR 0008: `run_family` + cross-frame coherence + the `character_identity` Gemini review + `t5_anchor_refine`), not a new grader/loop (the owner's "don't reinvent the loop"). Decision (with the owner, 2026-06-26): option A — Gemini + grade/audit with a PLUGGABLE generator backend (the ADR 0062/0081 adapter pattern) — over a per-character LoRA, which is deferred as "level-2" (needs GPU training + an open model). The family pipeline is already a consistent-character multi-frame loop (walk/peck cycles ship through it) but tuned for 32×32 pixel-art; this adds a painterly `character_anim` family kind (drops palette-snap/32×32), the two genuinely-new criteria `pose_match` + order-aware transition-coherence (existing checks are order-agnostic — they'd pass a shuffled animation), a recursive Gemini inbetween layer for high frame counts (≈12–24 "on twos"/"on ones"), a painterly cutout/register post-process, and packaging as a Cloud Bongos module (ADR 0083). First consumer = the Bongo Buddha's 8 actions → widget (task 1523). Implementation epic: tasks 1549–1559.](<redacted>.md) | GDS / art pipeline |
+| 0089 | [Modular, multi-model adversarial grader (open-weight ensemble) — refactor the ship-gate into a central, work-type-parameterized engine (gather evidence → deterministic pre-passes → judge ensemble → normalize+aggregate → gate → persist) where each MODULE contributes only its rubric + evidence-gatherer + specialist critics through the ADR 0083 seam (`grader.workType.<key>`), answering the owner's "per-module or general?" as central-engine + module-plugged. Adds open-weight LLM judges from a DIFFERENT model family than the author (Claude stays as the quality floor, never the sole judge) to kill same-family self-preference inflation (10–25%); judges run via a `ModelProvider` adapter (`openai-compatible` → DeepInfra/OpenRouter/vLLM/Ollama, the ADR 0062 neutral-contract pattern) on a hosted pay-per-call API (~$1–5/mo, owner spend-gated). Small (2–3) audited panel — z-score/rank-normalize then median + hard-veto aggregation; an error-correlation audit routine (Cohen's κ vs owner decisions) keeps the jury failing DIFFERENTLY (the "Nine Judges, Two Effective Votes" finding) rather than assuming vendor-diversity. Deterministic route-rank + permission-path pre-passes stay ZERO-LLM and authoritative (no LLM verdict, Claude or open, can upgrade a fail over a protected path; ADR 0016/0043/0080); VLM judges advisory on art, deterministic palette/grid checks authoritative. Owner decisions 2026-06-26: central-engine + module-plugged; ensemble vote; hosted API. Reuses the worker-contract + task_grades schema + LLM cache (ADR 0077); rolls out advisory-first behind a flag. Build cluster task-pending (task 1561).](<redacted>.md) | GDS / grader + quality gate |
+| 0090 | [Metic gains task authoring — re-ranks `POST /tasks`, `PATCH /tasks/:id`, `POST /tasks/:id/promote`, and the `tasks/:id/{dependencies,criteria}` CRUD from Archon-only to `requireRank('metic','archon')` (owner decision 2026-06-26: a rank trusted to triage ideas is trusted to seed + shape the tasks they become). Moves the two `EXPECTED_RANKS` pins in lockstep and updates the `// rank:` annotations so the route-rank audit stays green. Keeps Archon-only: rank-setting, version-close, abandon, grader-bypass confirm, and the ADR 0086 cross-tier `POST /dependencies` + goal-scope edges. Amends ADR 0018's table row 7; sits beside ADR 0086, which remains the module-fenced authoring path for sub-Metic ranks. "Tighten later" debt explicitly accepted — no per-version/module/goal fence on a Metic's authoring.](<redacted>.md) | GDS / permissions |
+| 0091 | [Bounding the kernel and carving `db.js` per-domain (Config-B core decomposition) — amends ADR 0083 to extend the strangler from the four FEATURE modules into the CORE itself (BONGOS-V1 C7). Answers the three questions the audit opened: (1) WHAT IS THE KERNEL — replaces the 6-file machinery-only `fitness.js` `KERNEL_FILES` with an enumerated ~3.5k-LOC trust roster (auth · route-rank-check · permission-path-check · secret-box · pool · the new `db-kernel.js` identity/audit/rank/`withTx` slice · instance-config/branding/build-info · routes/_helpers · the module-system machinery + module-scope-map); everything else in `src/bongos/` is a domain destined to become a module or to stay inside the un-split lifecycle state machine. (2) HOW A DOMAIN OWNS ITS SQL — ratifies the proven `modules/discord/db.js` + `modules/game/db.js` pattern (own queries lifted verbatim + deleted from core, reached through the doorway `pool`/`withTx`; kernel helpers re-exported behind the same `db.*` namespace; boundary-forced twins allowed + documented) as THE per-domain carve mechanism; `db.js` shrinks toward a kernel slice + the lifecycle residue. (3) WHAT THE DOORWAY EXPOSES — classifies `module-api.js` re-exports into kernel (stays: identity/audit/rank/auth/seams/config + `withTx`), domain-leak-with-a-home (relocate now: `setBuilderBoxBlocked`→dev-box, gemini-key trio→art-pipeline), and domain-leak-pending-carve (`createTask`/`captureIdea`/`VOTABLE_TASK_STATUSES` stay as MARKED temporary re-exports until lifecycle/ideas are carved in tranche 2 — named, owned, tracked debt, not pretend-kernel). A lifecycle-invoked capability resolves through a kernel PORT, never a direct import (R73 replaces `routes/tasks.js`→`grader.js` with `resolve('grade')`). Deliverable = this decision + the seeded, dependency-wired R68–R74 sub-task shape; OTB byte-identical at every step. Tranche 2 (the other ~8 core domains) deferred per owner.](<redacted>.md) | GDS / architecture |
+| 0092 | [Hosting module + on-prem (warehouse) hosting target — scopes a portable Cloud Bongos `hosting` module (default-OFF, fail-to-vanilla) that brokers compute + storage workloads (inference / imagegen / embeddings / training / storage) to configured hosting *targets* through kernel seams, resolving each via `resolveOptional(port, cloudDefaultFn)` so a box-less / module-off instance degrades to cloud automatically. The warehouse GPU box is OTB's first ON-PREM target — one adapter backend declared in HOST-instance config (the ADR 0062 / 0081 core↔host + swappable-adapter pattern), shared across all Example instances, reached over an outbound tunnel the box initiates (no open ports / no static IP), sitting OUTSIDE the trust boundary like Discord (ADR 0033): it computes, it never grants rank or lands code (ADR 0016 / 0043). Inference REUSES the ADR 0089 `ModelProvider` openai-compatible adapter (the on-prem box = one more vLLM / Ollama endpoint) and adopts 0089's decisive finding that low-volume work is cheaper on pay-per-call APIs — so the GPU's honest justification narrows to GPU-bound batch generation, open-model fine-tuning / LoRA (the ADR 0088 deferred level-2), and always-busy bulk, plus the non-GPU wins of backups / storage + an unmetered sandbox; code that ships stays on Claude. Owner decisions 2026-06-27: serve all instances, conservative posture, proceed. Phased: scope use ✅ → build (task 1619) → hardware (task 1620) → software; the cost read-out (task 1621) is an independent input.](<redacted>.md) | Cloud Bongos / hosting |
+| 0093 | [Tranche-2 core-carve sequence (Config-B, completing C7) — amends ADR 0091, which deferred tranche 2 "per owner"; owner greenlit 2026-06-27. Tranche 1 proved the carve pattern (memory R72, grading R73) AND shipped the reusable infra (bounded kernel + `KERNEL_FILES` ratchet, doorway/`withTx`, per-domain `db.js` slice + `db-kernel.js`, the `grade` kernel port, `coreB-carve-proof.sh`), so each remaining core domain is now a PURE carve. Fixes (1) the ORDER — clean-slicing-first per the 02-module-map import-graph: economy → ideas → security → builder-settings → onboarding → sessions/BFG → autonomy/MAS → status-UI → hall-UI → lifecycle LAST; (2) economy registers the `reward` kernel PORT (twin of `grade`) so the lifecycle resolves grade+reward via seams and imports only the kernel — which is WHY economy is first and the lifecycle state machine is carved last + whole (never split, 02 §4); (3) every carve is proof-gated byte-identical and C7 is satisfied only by the final all-domains proof (R87) — tranche 1 proved the pattern, tranche 2 completes the decomposition the done-when demands; (4) the ADR-0091 §3 temporary doorway leaks retire as their domains carve (`captureIdea`→ideas R78, `createTask`/`VOTABLE_TASK_STATUSES`→lifecycle R86). Deliverable = this decision + the seeded, dependency-wired R76–R87 sub-task shape.](<redacted>.md) | GDS / architecture |
+| 0094 | [Repo Atlas — a self-drawing map of the codebase (idea [#457](https://example.com/builders#/idea/457)): a Builders' Hall page rendering an isometric, hover-connective, click-for-detail map in two views — CONTEXT LAYER (the always-loaded root `CLAUDE.md` + its budget gauge vs the on-demand nested guides, the docs library, the DB as live state, broken-link drift) and MODULE TRUTH (the real modules carved into `modules/<key>/` with clean boundaries vs the ~26k-line `src/bongos` core blob + the `db.js` monolith vs the planned-but-still-fused ghosts). Data = one generated `public-builders/atlas.json` from `scripts/gds/gen-atlas.js`, PURE file-reads, reusing the existing truth sources (`module-scope-map` MOVED-vs-FUSED, `fitness.js` boundary scan for clean-vs-violation + kernel leaks, `docs-entropy` stale links, the `CLAUDE.md` budget). Regenerated SERVER-SIDE on every deploy (a `deploy-prod.sh` step, the world-snapshot precedent) — never on the shipping builder's machine; gitignored build artifact; page degrades gracefully pre-generation; styled in the Cloud Bongos brand, gated to any signed-in builder, built to port to Cloud Bongos. Owner decision 2026-06-27. Follow-up task [#1641](https://example.com/builders#/task/1641) migrates the repo-map/session-index/file-map generators onto the same server-side trigger (diagrams excepted: headless browser + auth).](<redacted>.md) | Cloud Bongos / docs |
+| 0095-a | [Borrowed memory, retrieval & collision concepts from claude-mem (Apache-2.0) and graphify (MIT) — after evaluating both Claude-Code tools and rejecting either wholesale (Python stack / local-daemon+Chroma architecture / no rank-scoping / open-core+memecoin governance), adopt eight stack-agnostic CONCEPTS, reimplemented in-stack with no new dependency or service ("borrow concepts, not tools"): from graphify — symbol-level collision detection (path-prefix→symbol/dependency overlap in `path-match.js`, the forecast-accuracy lever ADR 0049 left open), an AST/tree-sitter repo-map upgrade via the ADR 0063 `extractFile()` seam (polyglot + symbol resolution + a dependency graph that also feeds the ADR 0094 atlas truer edges), and forward-facing "why" extraction (`# WHY:`/ADR rationale into recall + auto-injected on file open); from claude-mem (1–5) — progressive-disclosure recall with token-cost visibility (~10× fewer tokens/query, mechanism-agnostic), a hook graceful-degradation policy (infra-fail→exit 0, code-bug→exit 2), a memory-usefulness feedback loop, a `<private>` content-exclusion marker, and windowed content-hash dedup. Deliberately does NOT decide grep vs. a semantic/embedding layer — a companion owner-authored ADR owns that, and every item here composes with whichever it picks. Declines lifting either codebase, the Chroma/uv dependency, and automatic-capture-as-default (folded into the BFG as suggestion-only).](<redacted>.md) | GDS / memory + retrieval |
+| 0095-b | [Cross-agent context management — adopt docstrings now (meaning written into version-controlled source is the zero-cost, zero-drift core of BOTH grep and semantic findability — no separate index to pay for or keep fresh); record as DEFERRED future-decision content the `AGENTS.md` cross-tool adapter layer (one canonical instructions file + thin per-tool pointers), the greppability / Grep-Test naming conventions, the `AIDEV-NOTE` anchor-comment convention (guarded by a fitness check so it can't rot), a semantic / embeddings layer (local model + embedded store + incremental git-hook reindex, run alongside grep — never instead), and a per-project "retrieval & agent profile" chosen at init that provisions the adapter set. Preserves the cross-agent research (agents navigate by grep not embeddings; Anthropic + Sourcegraph dropped embedding indexes, Cursor only augments grep with them). The portability frame is the ADR 0062 / 0081 core↔host swappable-adapter pattern applied to the agent surface; corroborates ADR 0060's deferred-embeddings gate. One accepted decision; everything else is framing for a future GDS-V4 / Cloud Bongos planning session. Follow-on task 1654 tracks the docstring rollout.](<redacted>.md) | Cloud Bongos / context + retrieval |
+| 0096 | [Require a `credits_reward` (drachmae) value before a task is workable — closes the hole where `credits_reward NOT NULL DEFAULT 0` (migration 003) let a task be promoted→claimed→shipped while paying 0 drachmae. Enforces a present, positive reward at THREE points: the promote route (`POST /tasks/:id/promote` refuses an unrewarded flip to `ready` with an actionable `REWARD_REQUIRED` 409 that SUGGESTS a value from kind/est), the auto-promote predicate (`task_is_fully_unblocked`, migration 177 — adds `(reward_gate_exempt OR credits_reward>0)` so a deps-shipped task with no reward stays `backlog`), and a claim backstop (`db.claimTask` mirrors the `DEPS_NOT_SHIPPED` second-line-of-defence). GRANDFATHERS the ~57 already-`ready` zero-reward tasks via a `tasks.reward_gate_exempt` flag set true for every task at/past `ready` at migration time — no currently-claimable task becomes unclaimable, no `ready` task is retro-demoted (the predicate change is forward-only: triggers never re-evaluate a `ready` row). Keeps `credits_reward` AUTHOR-SET (ADR 0023 anti-gaming): suggests, never auto-applies; setting it stays `PATCH /tasks/:id`. Coordinates with the backfill task (<redacted>, task 1672) to value the grandfathered rows.](<redacted>.md) | GDS / economy + lifecycle |
+| 0097 | [One active claim per session + a claim binds to a dedicated worktree (task 1642) — closes the commingled-ship hole: a single Claude Code session works one git worktree which owns one branch, so claiming a 2nd task from the same worktree lands both tasks' commits on one branch and `/builder-ship` (which publishes the whole branch) drags the unfinished task's work out under the first's ship. The only prior guard (`gateNewcomerClaim`) was Xenos-only, builder-scoped, and fail-OPEN. Adds a SESSION-scoped (keyed on `creator_session_id`, not builder — preserves the many-sessions-per-builder norm), ALL-rank, FAIL-CLOSED block at `POST /claims` (`409 session_already_has_active_claim` naming the in-flight task). NULL-session web claims (`bind_session=false`) are skipped so claim-in-browser/ship-from-any-terminal still works. The decision is a pure exported fn (`shouldRefuseSessionClaim`, DB-free unit-tested); the route middleware is thin. DB defence-in-depth: partial unique index `uniq_active_claim_per_session ON claims(creator_session_id) WHERE released_at IS NULL AND creator_session_id IS NOT NULL` (migration 180 — the real `released_at` convention, NOT the spec's nonexistent `status` column; heals any current violation before CREATE so deploy can't break). Part B: the builder-claim skill default flow now claims into a dedicated worktree (`EnterWorktree task-N`). AMENDS ADR 0049 — adds the within-session invariant 0049 left implicit; the cross-claim split contract is untouched.](<redacted>.md) | GDS / lifecycle |
+| 0098 | [The Cloud Bongos public-mirror publish boundary as an executable manifest (`scripts/gds/publish-manifest.js`, `isPublishable()`) — makes ADR 0065 §4's prose boundary something R72 (the delayed redacted export) consumes and R73 (the no-leak proof) asserts against. Default-deny: an allowlist (portable core + platform + neutral branding + sanitized methodology docs) gated by a hard denylist that IMPORTS and partitions the three trust inventories — `PROTECTED_GLOBS` is NOT a denylist, only its topology subset (infra/deploy/CI/local-gate-hooks) is excluded; the rank/permission/ship machinery publishes AS the open-source methodology. Excludes the game + all art (the art subtree carries the ripped Pokémon FireRed reference corpus — an independent copyright reason) + instance identity/config/history + secrets. A unit test cross-checks the partition against the live `PROTECTED_GLOBS` so the carve-out can't silently drift (the gate-review "no allow-by-omission" doctrine applied to publishing). Defers the customer-0 brand pack + desktop-client source to R72/owner (excluded by default until then). No migration — a file-glob boundary has no DB state.](<redacted>.md) | Cloud Bongos / open-source governance |
+| 0099 | [The time-delayed, redacted public-mirror export pipeline (R72, task 1211) — the file-level work ADR 0098 deferred: `scripts/public-mirror-export.js` picks the newest commit ≥180 days old (a lagged SNAPSHOT, not a history replay), partitions its tree through `isPublishable()` (ADR 0098 — the ONLY allow-list), redacts every published file (`scripts/gds/mirror-redact.js`: domain/subdomains → example.com, repo/db/world/company token → example, owner login+aliases → example-owner, public IPv4 **and** IPv6 → REDACTED_IP with localhost/RFC-1918/RFC-5737/link-local/ULA kept) THEN the ADR-0022 secret scrubber (extracted to `modules/security/secret-scrub.js` so it's CI-safe to require without ship.js's heavy deps; ship.js re-exports it). FAIL-CLOSED + atomic: all redaction in memory, a no-leak gate over every blob, and only a fully-clean set touches the mirror FS. Two invariants carry it: (1) SELF-LEAK — the redactor is itself published so it holds NO instance literal, deriving them at runtime from the excluded `config/branding.json`; (2) the no-leak DETECTOR is STRICTER THAN + DECOUPLED FROM redaction — `findLeaks` scans raw literal SUBSTRINGS + IPv4/v6 floors, not the bounded redaction regexes, because a shared word-bounded rule silently missed `example-owner` inside a regex-literal string AND blinded the gate to its own miss. Droplet IP + owner-name aliases are sourced from env in the EXCLUDED workflow yaml. Transport reuses the ADR-0029/[#741](https://example.com/builders#/task/741) scoped-deploy-key push; scheduled weekly; DORMANT no-op until history is 180d old (~2026-11), keeping the mirror empty until R73 lands + the owner flips it public. `.mirror-provenance.json` is the lineage anchor R73 ([#1212](https://example.com/builders#/task/1212)) reuses.](<redacted>.md) | Cloud Bongos / open-source governance |
+| 0100 | [Two-repo instance model — a project consumes Cloud Bongos as a versioned platform dependency (resolves the R77 decision gate, task [#1607](https://example.com/builders#/task/1607)). Chooses the PHYSICAL repo topology [ADR 0062](<redacted>.md) §10 left open: an instance may be its OWN repo installing a pinned core (the `isPublishable()` subtree, [ADR 0098](<redacted>.md)) + layering its own content/branding/modules — not only a second process on one checkout (cloudbongos.com stays a supported, cheaper reskin shape). SEQUENCED + Mercury-driven: build the smallest slice to stand Mercury up as customer 2 on a PINNED core, then let its first core bump define the update channel (`bongos upgrade` is a stub today, [#1203](https://example.com/builders#/task/1203)) — don't design the channel up front; Example is NOT split (stays the single-checkout reference instance, free core updates) until a separate later call. GDS topology = PER-REPO (each project its own DB/tasks/builders/versions; a shared GDS is rejected — it re-couples what the split exists to separate). The generated mirror ([ADR 0065](<redacted>.md) §4 / [ADR 0099](<redacted>.md)) is RETAINED now, retired CONDITIONALLY once the core is physically extracted (then the core repo becomes the canonical public artifact); AGPL + governance + 6-month delay unaffected by topology. Trades free instant updates for a permanent per-project upgrade step + a bigger op footprint, weighed against the $5k budget. Seeds GDS-V4 R84→R85→R86.](<redacted>.md) | Cloud Bongos / architecture |
+| 0101 | [Goal hierarchy Phase 5 — the deferred ADR 0086 non-decisions, recorded with a security review (BV1.R65, task 1519): (1) an ADVISORY-FIRST relevance / anti-hack judge at goal-task create/claim that reuses the ADR 0024 grader subagent harness, flags for a Metic to review, and NEVER hard-blocks a newcomer (the deterministic scope + protected-path + auto-rank-floor gates stay the only hard walls; a fallible LLM as a hard gate would re-introduce the bottleneck ADR 0086 removed + open a gaming/DoS surface); (2) sub-Metic membership inside PROTECTED-scope goals — a genuine widening of the ADR 0043 hard floor, made purely-additive + fail-closed: an Archon grants a tightly-scoped, audit-logged membership and the ship-time gates (pre-push / grader pre-pass / gate-review / main-audit) become GOAL-AWARE on the REAL diff (allow a sub-Metic protected-path hit only if a live Archon-granted goal membership enumerates exactly that path, else the 0043 floor bites unchanged); ships LAST behind Part 1 + an owner Gate sign-off (ADR 0058) + a red-team pass; (3) the goal-reward model — leaning KARMA (not drachmae: real money, tight budget) + CONTRIBUTION-WEIGHTED (not membership-flat: anti-squatting; reuse the shipped-task attribution + BFG signals, ADR 0027) on goal ACHIEVEMENT, with any monetary component + the exact curve owner-gated at build time. Design + security review only; NO enforcement code. Child cluster P5.1 (judge) / P5.2 (goal-aware gates + 0043 amendment) / P5.3 (reward) filed backlog.](<redacted>.md) | GDS / permissions + economy |
+| 0102 | [Finish bounding the kernel — flip fitness Check 12 ("kernel imports no domain") from a WARN-mode ratchet to a HARD gate by clearing all 7 tracked kernel→domain leaks (task [#1707](https://example.com/builders#/task/1707)). (1) `llm-cache.js` + `llm-pricing.js` reclassified as kernel-adjacent infra (pure/injected cost primitives, same category as the pg pool + `path-match.js` — added to `KERNEL_IMPORT_ALLOWLIST`, NOT a new module core would depend on anyway); (2) the identity/auth/admission cluster (`upsertBuilder`/`seatFirstAdminIfUnclaimed`/`getBuilderByGithubId`/`hasInvitedAccessRequest`/`createSession`/`lookupSession`/`SESSION_TTL_MS`/`RANKS`) carved from the `db.js` residue into `db-kernel.js` — `auth.js` (a KERNEL_FILE) resolves them there, `db.js` re-exports for its other callers, the `RANKS` twin now pairs with lifecycle; (3) the doorway's remaining domain re-exports pushed behind ports — Gemini-key storage → art-pipeline, `builderRollingAvgGrade` → the `grade` port; (4) `<redacted>` flipped to `violations` + `hardFail` at zero. Lands incrementally, each verified vs `fitness.js` + the unit suite + a live vanilla `docker compose up` (auth still 401s clean). Supersedes the ADR 0091 §1/§3 + 0093 WARN-mode deferral of the llm-infra carve.](<redacted>.md) | GDS / architecture |
+| 0103 | [Consolidate the two parallel internal versions — GDS-V4 (frozen) folds into BONGOS-V1, now the single go-forward Cloud Bongos PLATFORM version (renamed "Cloud Bongos — platform (V1)", status `building`); its still-relevant open work carries forward. The Bongos DESKTOP APP becomes its own GOAL under BONGOS-V1 (mascot, branded download + auto-update, the cloudbongos.com landing page, feedback capture, the absorbed Dev Box switch — [ADR 0087](<redacted>.md)); the code carve `bongos-app/` → `modules/bongos-app/` is tracked under it. Prunes 19 superseded tasks (the C1 semantic-search/embeddings arm — retired by [ADR 0095](<redacted>.md)'s grep-over-embeddings decision; old V3-era grader tasks superseded by [ADR 0089](<redacted>.md); the T-NNN task-ref migration), moves 2 misfiled game-art tasks to product V2, and severs the 758→753 dependency edge so 758 stays claimable. Executed as reversible data migration `182` (only status/version/goal/edge mutations; in-flight `confirmed`/`active` tasks stay in GDS-V4 to land). `/status` now defaults to BONGOS-V1. Surfaced + fixed a 12-day silent DB-backup outage first (task [#1711](https://example.com/builders#/task/1711)).](<redacted>.md) | Cloud Bongos / methodology |
+| 0104 | [Trust the GDS API channel in Claude Code AUTO mode — pre-allow `Bash(node scripts/gds/api.js:*)` in the project `.claude/settings.json`. Completes task [#1051](https://example.com/builders#/task/1051)'s narrow named-script allow-list (from the task-[#1027](https://example.com/builders#/task/1027) nightmare): every autonomous GDS op without a dedicated script — idea-triage promote, create-task, blocker-resolve, criterion ratify, goal create, cost, security reports — rides the GENERIC `api.js` caller, which was never allow-listed, so auto mode's classifier hard-denied the whole autonomous GDS write surface as "[External System Writes] … beyond the user's request" (it only worked under the box's task-[#1251](https://example.com/builders#/task/1251) `bypassPermissions`). Safe because the GDS SERVER enforces `builders.rank` per-request ([ADR 0016](<redacted>.md)) — the classifier was never the gate; the rule grants nothing beyond the caller's rank, and `api.js` can only reach `/api/gds/*`. Scope-discipline stays in the per-builder `wandering` knob. Locked by `tests/box_ship_permissions.mjs`.](<redacted>.md) | harness permissions / dev box |
+| 0105 | [Instance/product seed data out of the core migration path — OTB scope-truth (`versions`/`goals`/`done_when_criteria`) embedded in ~16 core migrations crash-looped a vanilla self-host on a fresh DB (FK violations) or polluted it with OTB's versions/goals; task [#1264](https://example.com/builders#/task/1264) patched only the two crashers (172/173 `DO`-block guards). Structural fix (task [#1704](https://example.com/builders#/task/1704)): the 10 PURE seed files move to a declared `migrations/instance/` dir; `scripts/migrate.sh` applies instance seeds only for the OWNING instance and DEFAULTS OFF (opt-in `GDS_APPLY_INSTANCE_SEEDS=1`; hard-off under the now-revived `MEDUSA_GDS_ONLY`), so a vanilla OR branded self-host never inherits them. Both dirs merge-sort by basename so the global numeric order is preserved (018 before 019) and an OTB from-scratch replay is byte-identical (5 versions / 11 goals / 43 criteria). The unavoidable seed blocks in the mixed files 003/006 guard in place on the `app.seed_instance_data` GUC (achievements + the generic `bfg`/`discord_bot` system principals kept). A `selfhost-boot.yml` CI gate (authored; landing gated on blocker 52 — the App can't merge `.github/workflows/*`) boots a fresh `postgres:16` and asserts a clean vanilla boot with zero OTB rows, closing the C9-style un-gated-proof gap. Verified against a throwaway DB both ways.](<redacted>.md) | Cloud Bongos / architecture |
+| 0106 | [Goal owner/manager authority — refines ADR 0086's membership roles into a fixed hierarchy (task [#1735](https://example.com/builders#/task/1735)): the goal OWNER is `goals.created_by` (a column, not a role row — set at create, moved only by the new owner-only `POST /goals/:id/transfer`; the new owner must be Metic+); MANAGER is the `goal_members.role='lead'` value (rendered "manager" in the hall), owner-equivalent EXCEPT demotion (owner-only) and transfer; the owner's row is never demotable (`owner_role_fixed`), enforced in the pure ordered gate (`authorizeMemberRoleChange`, the authorizeGoalTaskCreate precedent) AND atomically inside the UPDATE (`setGoalMemberRole`). Creators backfill as leads via module migration `<redacted>` — deliberately NO earliest-member fallback (fail-closed; ownerless migration-160 system goals stay Archon-run). No goal delete — archive unchanged. Replaces the task's original leads-as-equals "never below one lead" invariant with the simpler fixed-owner model.](<redacted>.md) | GDS / goal hierarchy |
+| 0107 | [Module upstreaming — instances contribute modules into the shared core catalog (task [#1766](https://example.com/builders#/task/1766)). The REVERSE of the ADR 0100/0103 distribution arrow: an instance (Example, Mercury) builds a feature module and submits it for approval to be merged INTO the shared Cloud Bongos core, credited to author + origin project; accepted modules land in core `modules/<key>/` **default-off**, added to the `isPublishable()` allowlist, and every instance may opt in. Decisions: (1) platform-native `bongos module submit` → a rank-gated core review queue (NOT instance write-access to core; fork-and-PR is a fallback); (2) attribution is PORTABLE METADATA — `module.json` gains `author`/`origin`/`license`/`maintainer` (a record, not a cross-GDS foreign key, since each repo has its own identities per [ADR 0100](<redacted>.md) §3); (3) reward = CREDIT NOW, money later (drachmae/cross-instance payout deferred to a separate economics call); (4) AGPL-IN with a DCO-style sign-off, NO CLA ([ADR 0065](<redacted>.md)), `isPublishable()` pre-check at submit rejects un-AGPL-able content (game/art/copyright); (5) SECURITY REVIEW is a hard accept-gate — a contributed module runs in-process in every enabling instance, no sandbox yet; (6) default-off + the publish-allowlist add IS the accept action; (7) maintenance/deprecation policy for orphaned modules (coreVersion compat). Sequenced: manifest fields + module-owned test discovery in core CI + submit-time pre-check buildable NOW; the submit→review→accept→catalog pipeline depends on R88 (extract core, [#1727](https://example.com/builders#/task/1727)) + R85 (Mercury, [#1689](https://example.com/builders#/task/1689)). Renames away from the taken "contribution seam" term (that is the in-process UI hook).](<redacted>.md) | Cloud Bongos / architecture |
+| 0108 | [Instance composition topology — CONFIGURABLE-ROOT: the core is consumed as a versioned npm dependency (task [#1870](https://example.com/builders#/task/1870), BV1.R115). Resolves the composition MECHANISM that [ADR 0062](<redacted>.md) §10 / [ADR 0100](<redacted>.md) §1 / [ADR 0103](<redacted>.md) §2 each left open (they are mechanism-neutral — "installs a pinned core + layers on top"; 0103's R88 record deferred "the topology/instance paths the scaffold populates on `init`"). A 2026-07-03 owner review chose configurable-root over the earlier clone-and-layer draft, weighting SCALABILITY over least-resistance: upgrades = O(1)-per-instance version bump (not O(instances×drift) merges); the boundary is enforced by the PACKAGE (can't rot under many agents) not convention+CI; a dependency forces a real core API; instance repos stay small; "root is a parameter" is the precondition for multi-instance/hosted. Decisions: (1) core installed as `@cloudbongos/core`, host content resolved via an injected instance-root — two resolvers `resolveInstanceRoot()`/`resolveCoreRoot()` in the existing `src/instance-config.js`, defaulting to repo-root TODAY (byte-identical) and flipping `resolveCoreRoot()` to `node_modules` when packaged, no further per-site edits; the two directions are OPPOSITE (config→instance-root; the `infra/` installers `serve-internal` serves→core-root); (2) `package-core` emits a real `package/`-rooted npm package (`main`→platform-server, `bin`→bongos, deps pruned to express/pg/undici), `isPublishable()` stays the single core definition; (3) `.claude/` is MATERIALIZED into the instance by `bongos init`/`upgrade` (Claude Code reads it from the project root, never node_modules) + the ~30 skills/hooks rewritten `node scripts/gds/…`→`bongos …` (skills already ship in-core; hooks+settings are already "topology"); (4) `bongos upgrade` (R86) is an npm version bump, deploy flips `git reset --hard`→`npm ci` (Docker/`platform-server`/`selfhost-boot` already model it); (5) cross-repo migration numbering gets a namespacing + lineage discipline (two repos both adding `NNN_*.sql` collide on the shared `schema_migrations` stem key); (6) land Mercury-first — step-1 resolvers now (zero-change), package+`.claude` prove on greenfield R85, Example splits last (R89) with the trust-boundary path sites + the two-root guardrail fix (fitness.js/gen-repo-map/gen-file-map all hardcode REPO_ROOT) behind a security review. Runtime-library half is SMALL/de-risked (~8–11 readers; entrypoint seam `mountInternalSurfaces`/`buildPlatformApp`, two-roots loader, single-sourced partition already exist); the real work is delivery+ops (§3/§4/§5) — the accepted "more pain now". Clone-and-layer/submodule/monorepo rejected. Informs R85 ([#1689](https://example.com/builders#/task/1689)), R86 ([#1690](https://example.com/builders#/task/1690)), R89 ([#1728](https://example.com/builders#/task/1728)). Docs amended (not superseded): file-map, architecture, packaging-the-core + self-host recipes, ADR 0105, modules-contract; cross-refs in 0062/0100/0103/0098/branding-contract/CLAUDE.md. No migration, no new criterion; goal 26.](<redacted>.md) | Cloud Bongos / architecture |
+| 0109 | [The GDS API is self-describing — a standards-compliant **OpenAPI 3.1** spec generated from the live route files + a hosted `/docs` site (task [#1918](https://example.com/builders#/task/1918), BONGOS-V1, Part A of the API-docs + `/api/gds`→`/api/bongos` rename). Replaces the hand-maintained, drifted `docs/routes-permissions.md` with `scripts/gds/gen-api-docs.js`, which reuses the SAME `route-rank-check.js` introspection the ship-time rank gate ([ADR 0016](<redacted>.md)) uses — so the docs enumerate exactly the routes the server mounts and cannot drift (the [ADR 0063](<redacted>.md) generate-and-`--check` pattern). Emits `docs/api/openapi.json` (each op carries its rank in `x-rank` + a `security` ref, path params, and best-effort request-body fields from the `validateOrRespond` schema; undocumented bodies are counted) + a generated `docs/api-reference.md`. A vendored Redoc bundle renders it at `/docs` on every instance's apex (`cloudbongos.com/docs` canonical), served from the SHARED `mountInternalSurfaces` so a self-hosted instance is self-documenting for free; `GET /api/gds` returns a machine-discovery index and the 404 hint names `/docs`. Introduces the single `src/bongos/api-prefix.js` prefix constant that Part B flips to `/api/bongos`. Freshness enforced by `gen-api-docs --check` in `fitness.js` + ship-time regen; full standard lint via `npm run docs:api:lint` (`@redocly/cli`, off the critical path). Rejected: annotation-based/hand-written specs (drift), CDN renderer (self-host convention/air-gap), redocly as a hard CI dep (lean project).](<redacted>.md) | GDS / API docs |
+| 0110 | [Move whole-file generated navigation docs off the git graph (task [#1926](https://example.com/builders#/task/1926), BONGOS-V1, goal 24 build-pipeline-integrity). `docs/repo-map.md` (ADR 0063) + `docs/session-log-index.md` (ADR 0062 §8) were regenerated + **committed on every ship**, so parallel builder branches collided on them constantly (the [ADR 0082](<redacted>.md) reactive heal only cleans up after the fact). Applies the blessed `gen-atlas.js`/`atlas.json` precedent ([ADR 0094](<redacted>.md)): **gitignore** both whole files + regenerate them SERVER-SIDE at deploy (`deploy-prod.sh`, LOUD on failure → goal-24 `gcarry-pipe-loud`) and at `box-source-fetch` — a file not in git can never appear in a branch diff, so the conflict class is gone AT THE SOURCE. Both generators are DUAL-DUTY (each also refreshes a tracked block — the nested `CLAUDE.md` symbol blocks / the `CLAUDE.md` §13 snippet), so the CI freshness gate is SPLIT: `gen-*.js --check-block` (tracked block, still HARD) vs `--check-whole` (the gitignored file, no longer gated) — the adversarial-review fatal flaw was that the old single `--check` bundled both, so a naive relax would silently drop the block gate. `ship.js` drops the gitignored paths from its `git add` (an explicit `git add <ignored>` aborts the commit). Reactive heal (`git-merge-regen`, `.gitattributes`, ADR 0082 resolver) KEPT unchanged as a transition backstop; trust boundary untouched (no bot commits to main; no `.github/workflows/` change). Deferred to follow-ups: the OpenAPI spec (external consumers → bounded regen bot) + diagram renders (headless Chromium). Accepts: whole files fresh only post-deploy, not at merge.](<redacted>.md) | Build pipeline / generated artifacts |
+| 0111 | [Instance hosting + domains as a Cloud Bongos module — spec of the new **`provisioning`** module boundary + the **self-host vs managed** split (task [#1485](https://example.com/builders#/task/1485), BONGOS-V1 goal 26; consolidates owner ideas [#345](https://example.com/builders#/idea/345) + [#303](https://example.com/builders#/idea/303)). Standing up a Cloud Bongos instance still leaves an irreducibly-manual infra checklist (`bongos init` files it as kickoff tasks); this ADR specs the module that automates it. **Distinct from [ADR 0092](<redacted>.md)'s `hosting`** (that brokers compute/storage *workloads*; this provisions an *instance's own* server/DB/domain/DNS/TLS) — takes the free key `provisioning` to avoid the collision. Decisions: (1) a portable `default:false` `provisioning` module owns only the web-tier request/state surface (`provisioning_instances`/`_intents`/`_events`, own+Archon rank-gated routes, a `provisioning.instanceState` port) — it holds **no** cloud tokens; (2) the web tier only **enqueues intents**, a new control-plane CLI `scripts/gds/provision.js` (sibling of `box.js`, sole token-holder, systemd-timer-drained, idempotent/dry-run-default) executes them — the [ADR 0031](<redacted>.md)/[ADR 0016](<redacted>.md) box precedent, with the DO+Cloudflare clients extracted to a shared control-plane location so `box.js`+`provision.js` reuse them without a module→module import; (3) provisioning composes the [`cloudbongos-standup.md`](../recipes/cloudbongos-standup.md) runbook (server co-tenant-or-droplet → DB → migrate → env → service → DNS → TLS → Caddy), with GitHub-OAuth-app + first-sign-in demarcated as guided/manual; (4) **bring-your-own-domain first** (registrar-API purchase deferred) + **Caddy on-demand ACME TLS** for new hosts (removes the manual Cloudflare Origin-Cert leg; existing apexes keep theirs); (5) **self-host and managed run the identical `@cloudbongos/core` artifact** ([ADR 0108](<redacted>.md)) — the only differences are *whose* credentials the control plane holds and *who* operates it; managed = self-host + <redacted> infra + a central fleet control plane driving the same `bongos upgrade` channel, AGPL unchanged ([ADR 0065](<redacted>.md) §2, no open-core); (6) cheapest-first cost DNA (co-tenant $0 → dedicated droplet only when justified; snapshot-park idle; billing deferred); (7) self-host arm buildable now on the shipped configurable-root substrate, managed arm gated on R85 Mercury ([#1689](https://example.com/builders#/task/1689)) + R86 upgrade channel ([#1690](https://example.com/builders#/task/1690)). Seeds 8 follow-up tasks via `scripts/gds/seed-provisioning-tasks.js`.](<redacted>.md) | Cloud Bongos / architecture |
+| 0112 | [Private goals — a `visibility` flag (`public` default \| `private`) + a two-sided `goal_membership_requests` queue (task [#1951](https://example.com/builders#/task/1951), BONGOS-V1). A goal manager can make a goal **private**; on a private goal non-members can't self-join — they are **invited** (a consented, pending row the invitee accepts from their inbox — distinct from the immediate `POST /goals/:id/members` add, kept byte-identical) or they **request** to join, approved by the goal's owner/manager/Archon (the [ADR 0106](<redacted>.md) `authorizeGoalManagement` wall reused wholesale). Both directions are one `goal_membership_requests` table keyed by `kind ∈ {invite, request}`, `status ∈ {pending, accepted, rejected, cancelled}`, with a **partial-unique `(goal_id, builder_id) WHERE status='pending'`** (the `access_requests` precedent — one open ask per person+goal). `GET /goals/inbox` returns each builder's actionable slice — invitations to them + join-requests on goals they own/manage + their own outstanding requests — powering a **home-page inbox**. **Private = join-gated, not hidden** (owner decision): a private goal still shows its title + progress; true concealment would need its own ADR. Purely additive (default `public` = today's open-join, unchanged) + revertible; ships in four phases (schema/db → routes → goals-page UI → home inbox). Rejected: fully-hidden goals (large filter surface for the stated intent), invite-as-force-add (owner asked for accept-from-inbox), two separate tables (shared lifecycle + mutual-exclusion index), requests on public goals (redundant — just join).](<redacted>.md) | GDS / goal hierarchy |
+| 0113 | [Per-builder art sandbox (task [#885](https://example.com/builders#/task/885)): descope to the sprite/animation Studio only. Task 885's 8-part breakdown (walkable offline preview, static sandbox server + systemd unit, `cf-tunnel.js` multi-ingress, box-provisioning wiring, reset-to-main script, retire staging) went stale on two axes: (1) Parts A1/B were already shipped, one day after 885 was filed, under [ADR 0044](<redacted>.md) (real degraded-DB game server at `sandbox-<login>.example.com` over the existing box tunnel) + [ADR 0052](<redacted>.md) (game-only entry, every rank) — a better design than the static-file/offline-mode one 885 proposed; (2) the touches\[\] paths point at pre-carve locations (`public/game/...`, `src/bongos/cf-tunnel.js`, `src/bongos/routes/box.js`) that moved to `modules/game/...`/`scripts/gds/cf-tunnel.js`/`modules/dev-box/...` under the ADR 0083/0093 module carve. Part C (retire staging) also contradicts the standing 2026-05-29 defer-not-delete decision in `docs/recipes/staging-environment.md`. Keeps only the Studio — a sprite/animation reviewer at `/studio`, layered onto the *existing* sandbox as a static page under `modules/game/public/` (the `/art` gallery precedent in `src/preview-server.js`; no new server/tunnel/unit) that auto-discovers sprites from `manifest.json` and extracts the right-facing mirror logic from `Player.js` into a shared `spriteFacing.js` — filed as one new child task instead of re-minting the stale 8.](<redacted>.md) | Builder experience / dev box |
+| 0114 | [Instance docs-discovery contract — pins how an agent locates its doc surfaces from config alone, with no hard-coded host. Three layers: (1) `config/branding.json` `domains.{publicOrigin,buildersOrigin,statusOrigin}` is the source of truth — the hall is the canonical doc-reading surface, `/docs` on `publicOrigin` renders the API reference, the status page is the off-box outage fallback; (2) `GET <publicOrigin>/api/bongos` (the machine-discovery index, + permanent `/api/gds` alias) is the zero-config entry point and now re-advertises `hall`/`status`/`public` from `branding().domains` so a second instance bootstraps its surfaces from a single unauthenticated call; (3) a resolution order for agents. Formalizes existing keys (no new required field); CLAUDE.md's preamble references it instead of hand-waving one config key.](<redacted>.md) | Portability / docs-discovery |
+| 0115 | [Scheduled-routines portability (self-host + multi-builder) — pins the model for the ~17 cron routines under `.claude/scheduled-tasks/`. Contract: every routine is INSTANCE-WIDE (one scheduled run per instance, never one cron per builder — a routine's per-builder effect comes from iterating the builder set in its body). A manifest `config/scheduled-routines.json` declares each routine's scope / default-enabled / cadence / requiresAutonomy: read-only ops default ON, autonomous build routines (overnight-builder, overnight-code-review, idea-triage-nightly) default OFF behind the autonomy flag, BFG Part C stays separately gated. A fresh instance inherits the set + manifest and the operator opts in/out there without editing a routine; builders don't schedule their own (governed by per-builder settings). Spike deliverable; flags the prose `example`/`~/.config/otb` hardcoding as a follow-up sweep. No behavior change today.](<redacted>.md) | Portability / autonomy |
+| 0116 | [API error envelope + code taxonomy — the contract (R01) for goal 36's `api-error-envelope` criterion (task [#1988](https://example.com/builders#/task/1988), BONGOS-V1). An audit found **352 distinct `error:'…'` string literals** returned across 400/401/403/404/409/413/422/429/500/502/503 in ~4 different response shapes — a caller cannot write one error-handling path. Decision: **one envelope everywhere** — `{error:{code,message,details?}}` — where the specific `code` slug is **preserved** (a caller keying on `task_not_found` keeps working) and the 352 codes **collapse by category, not by discard**. A kernel registry `src/bongos/api-errors.js` defines ~12 canonical categories (each with a default HTTP status + `retriable` flag) and a pure/total `classify(code)` — an `OVERRIDES` table for the ~90 exceptions (auth codes, preconditions-as-conflicts, `*_too_large`) plus a suffix/prefix heuristic for the long tail (`*_failed`→internal, `*_not_found`→404, `bad_*`/`*_required`→400, `already_*`/`*_taken`→409, `*_unconfigured`→503); an unknown/future code falls back to `internal` (500). Ships the `ApiError` carrier + `envelope()` formatter + `statusForCode(code,override)` (a site keeps its current status; the sweep changes shape, not status). **Contract-only — nothing imports it yet, zero behaviour change.** R02 ([#1989](https://example.com/builders#/task/1989)) wires the middleware + `res.fail()`; R03 ([#1990](https://example.com/builders#/task/1990)) fails the build on a new hand-rolled flat error; R04 ([#1991](https://example.com/builders#/task/1991)) sweeps the ~219 handlers behind that gate. Rejected: flat `{error,message}` (today's mess, no room to grow), numeric codes (opaque), collapsing to 12 codes only (loses signal, breaks callers), per-module registries (defeats "one shape").](<redacted>.md) | API contract / goal 36 |
+| 0117 | [API versioning + deprecation policy — the policy (R05) for goal 36's `api-versioning` criterion (task [#1992](https://example.com/builders#/task/1992), BONGOS-V1). The API (212 endpoints at `/api/bongos` + permanent `/api/gds` alias) had no version marker, no breaking-change definition, no deprecation window — any change could silently break a self-hoster/shipped Dev Box binary/status dashboard. Decision: (1) an explicit path segment `/api/bongos/v1/…` is the **contract** version, distinct from `info.version` (the package semver); (2) today's unversioned paths become **permanent aliases pinned to v1** — the load-bearing rule is *an unversioned path never silently jumps major versions*, so when v2 mounts at `/v2/` the alias stays on v1 and breaking changes reach only opted-in callers; (3) breaking = remove/rename/retype a field/endpoint/error-code, new required field, tightened validation, narrowed auth, changed default — non-breaking = additive fields/endpoints/optional-params + new error codes *within an existing ADR-0116 category*; (4) a superseded version lives **≥180 days** with RFC 8594 `Deprecation`/`Sunset` headers, the unversioned alias exempt (permanent); (5) the version is discoverable via OpenAPI `servers` + `x-api-version` + the machine-discovery index + `/docs`. **Policy only** — R06 ([#1993](https://example.com/builders#/task/1993)) mounts `/v1` + aliases the unversioned paths (day-one no-op). Rejected: header-based versioning (invisible in URL, un-curl-able), semver-in-path (too fine), reusing the package semver (conflates build with contract), sunsetting the unversioned alias (breaks un-updatable binaries).](<redacted>.md) | API contract / goal 36 |
+| 0118 | [API contract source-of-truth: code-first, schema-as-data — the spike (R07) for goal 36 (task [#1994](https://example.com/builders#/task/1994), BONGOS-V1). Decision: STAY code-first; the per-route `validate()` schema object (already structured data: type/required/enum/length caps in `_helpers.js`) is the SINGLE source — the OpenAPI spec, runtime validation, and the typed client are all DERIVED from it, none hand-authored. `gen-api-docs.js` already generates the spec from route source (ADR 0109) but shallowly (212 endpoints; 76 write ops with a requestBody, 24 without; `components.schemas` empty); enrich `extractBody()` to emit full typed schemas from the validate() rules. One schema, three consumers (spec + validation + client) = single-source WITHIN code-first, no drift. Refines R08 (enrich generator → generate+publish client), R09 (migrate callers — also repairs the R04 flat-error reads), R10 (external on-ramp), R11 (reject unknown fields + query params, same schema), R12 (build check: write route ⇒ spec-bound schema). Rejected: schema-first (rewrite the whole 212-endpoint route layer), hand-maintained spec (drift, per ADR 0109), framework swap to Fastify/tRPC (too invasive).](<redacted>.md) | API contract / goal 36 |
+| 0119 | [API pagination contract — the contract (R13) for goal 36's `api-pagination` criterion (task [#2000](https://example.com/builders#/task/2000), BONGOS-V1). Three styles coexisted (limit-only, limit+offset, none) and some public lists (leaderboard, blockers, versions) returned everything (unbounded = cost/DoS surface). Decision: ONE convention — `?limit=&offset=` through a shared `parsePagination(req,{defaultLimit,maxLimit})` helper in `_helpers.js`: limit default 50 / hard-cap 200 (so no list is unbounded), offset default 0, bad/oversized values CLAMPED not rejected (list reads stay forgiving — the strict counterpart is write-validation R11). Response convention `{ items, page:{ limit, offset, total? } }` via `pageMeta()`. Chose limit/offset over cursor (already the in-use style, no opaque-token/stable-sort infra, trivial to curl; cursor left as a per-endpoint escape hatch for churning lists). Opt-in/non-breaking today; R14 ([#2001](https://example.com/builders#/task/2001)) adopts it across every list + caps the unbounded public lists. Rejected: cursor-as-default (disproportionate), page-number (awkward), leaving lists unbounded (the problem), 400-on-bad-limit (a read should be forgiving).](0119-api-pagination-contract.md) | API contract / goal 36 |
+| 0120 | [Pay drachmae on land (not on confirm) + a builder-owned rebase gate (task [#2035](https://example.com/builders#/task/2035), BONGOS-V1). Credits were awarded at the `confirmed` transition — before the code is on `main` — so stranded/never-pushed work paid out with no consequence, and the builder (the only one who can rebase it) had no reason to. Decision: (1) move BOTH the per-task credit AND the cost-plus session reward to the `shipped` (merged-to-`main`) transition; (2) the publish-reconciler flags a confirmed task `needs_rebase` (attributed to the claim holder) once auto-land is exhausted — merge conflict, failing required check vs current `main`, or no pushed branch; (3) a `needs_rebase` task blocks that builder's NEW claims (`REBASE_REQUIRED`) but not their existing/in-flight ones; (4) a one-time migration claws back the `task.confirmed` credits on the current confirmed backlog and re-gates it. Happy path unaffected (a clean PR auto-lands in minutes and pays then); the teeth bite only on stranding. Rejected: gate-only (stranded work still paid), soft-warn (ignorable), grandfather the backlog (leaves today's stranded-and-paid state), per-task-credit-only (owner chose fullest alignment).](<redacted>.md) | economy + lifecycle |
+| 0117 | [API versioning + deprecation policy — the policy (R05) for goal 36's `api-versioning` criterion (task [#1992](https://example.com/builders#/task/1992), BONGOS-V1). The API (212 endpoints at `/api/bongos` + permanent `/api/gds` alias) had no version marker, no breaking-change definition, no deprecation window — any change could silently break a self-hoster/shipped Dev Box binary/status dashboard. Decision: (1) an explicit path segment `/api/bongos/v1/…` is the **contract** version, distinct from `info.version` (the package semver); (2) today's unversioned paths become **permanent aliases pinned to v1** — the load-bearing rule is *an unversioned path never silently jumps major versions*, so when v2 mounts at `/v2/` the alias stays on v1 and breaking changes reach only opted-in callers; (3) breaking = remove/rename/retype a field/endpoint/error-code, new required field, tightened validation, narrowed auth, changed default — non-breaking = additive fields/endpoints/optional-params + new error codes *within an existing ADR-0116 category*; (4) a superseded version lives **≥180 days** with RFC 8594 `Deprecation`/`Sunset` headers, the unversioned alias exempt (permanent); (5) the version is discoverable via OpenAPI `servers` + `x-api-version` + the machine-discovery index + `/docs`. **Policy only** — R06 ([#1993](https://example.com/builders#/task/1993)) mounts `/v1` + aliases the unversioned paths (day-one no-op). Rejected: header-based versioning (invisible in URL, un-curl-able), semver-in-path (too fine), reusing the package semver (conflates build with contract), sunsetting the unversioned alias (breaks un-updatable binaries).](<redacted>.md) | API contract / goal 36 |
+| 0116 | [API error envelope + code taxonomy — the contract (R01) for goal 36's `api-error-envelope` criterion (task [#1988](https://example.com/builders#/task/1988), BONGOS-V1). An audit found **352 distinct `error:'…'` string literals** returned across 400/401/403/404/409/413/422/429/500/502/503 in ~4 different response shapes — a caller cannot write one error-handling path. Decision: **one envelope everywhere** — `{error:{code,message,details?}}` — where the specific `code` slug is **preserved** (a caller keying on `task_not_found` keeps working) and the 352 codes **collapse by category, not by discard**. A kernel registry `src/bongos/api-errors.js` defines ~12 canonical categories (each with a default HTTP status + `retriable` flag) and a pure/total `classify(code)` — an `OVERRIDES` table for the ~90 exceptions (auth codes, preconditions-as-conflicts, `*_too_large`) plus a suffix/prefix heuristic for the long tail (`*_failed`→internal, `*_not_found`→404, `bad_*`/`*_required`→400, `already_*`/`*_taken`→409, `*_unconfigured`→503); an unknown/future code falls back to `internal` (500). Ships the `ApiError` carrier + `envelope()` formatter + `statusForCode(code,override)` (a site keeps its current status; the sweep changes shape, not status). **Contract-only — nothing imports it yet, zero behaviour change.** R02 ([#1989](https://example.com/builders#/task/1989)) wires the middleware + `res.fail()`; R03 ([#1990](https://example.com/builders#/task/1990)) fails the build on a new hand-rolled flat error; R04 ([#1991](https://example.com/builders#/task/1991)) sweeps the ~219 handlers behind that gate. Rejected: flat `{error,message}` (today's mess, no room to grow), numeric codes (opaque), collapsing to 12 codes only (loses signal, breaks callers), per-module registries (defeats "one shape").](<redacted>.md) | API contract / goal 36 |
+| 0122 | [Onboarding diagram renders: untracked + rendered at deploy from a host-provisioned Chrome (task [#2027](https://example.com/builders#/task/2027), BONGOS-V1) — completes the diagram half [ADR 0110](<redacted>.md) deferred. The `.svg`/`.png` renders were committed on every render-capable ship and kept colliding on parallel branches; ADR 0110 deferred them because `mermaid-cli`/puppeteer downloads its own Chromium on first run (a multi-minute fetch that stalls the 2 GB droplet). Decision: provision Google Chrome once on the host; `render-diagrams.sh` auto-detects an installed browser (or honors `PUPPETEER_EXECUTABLE_PATH`) and sets `PUPPETEER_SKIP_DOWNLOAD` so it never fetches (falls back to the download only on a dev laptop), passing a committed `puppeteer-config.json` with `--no-sandbox` (Ubuntu 24.04 restricts unprivileged user namespaces) and pinning `mermaid-cli@11`; deploy-prod.sh + box-source-fetch render from the tracked `.mmd` (LOUD `::ERROR::`, best-effort); `git rm --cached` + gitignore the `*.svg`/`*.png` (the `.mmd` + `assertions.json` stay tracked, so the nightly diagram-drift cron is unaffected); ship runs `gen-diagrams --no-render`. Verified rendering all 5 diagrams on the prod droplet before landing. Rejected: on-deploy Chromium download (the droplet stall), snap chromium (flaky headless), keep-tracked + strengthen the ADR 0082 resolver (hides the collision).](<redacted>.md) | internal / ADR 0110 |
+| 0121 | [Greenfield vs. brownfield onboarding — scope `bongos init --adopt` (task [#1986](https://example.com/builders#/task/1986), BONGOS-V1, goal 35's `adopt-existing-repo` criterion). Today the creation flow is greenfield-only: `scripts/gds/init.js` opens *"stand up a NEW instance"*, refuses to run where `config/branding.json` exists (`--force` overwrites), and seeds a synthetic `"V1 — Prove the loop"`; it inspects nothing about an existing tree. Decision: TWO explicit modes over goal 35's one canonical step sequence (task 1981), branching at exactly the SCAFFOLD leg — greenfield (`bongos init`, today) vs brownfield (`bongos init --adopt`); every other leg (provision, OAuth, verify, brand) identical, so the CLI (1982) + hall wizard (1983) forms inherit adopt for free. `--adopt` must: (1) LAYER not clobber — add the pinned `@cloudbongos/core` dep + lean `config/` + `.claude/` additively, merge-or-report on pre-existing files, never reuse the `--force`-overwrites path; (2) reflect REAL state — capture the repo's actual version/goal instead of the synthetic V1, import the existing backlog (GitHub issues / TODO / roadmap) into GDS tasks; (3) DETECT the existing stack + layout so modules / repo-map / fitness-boundary fit; (4) a CONFLICT PRE-FLIGHT report (migration namespace, fitness boundary, protected-path / rank gates, existing CI), `--dry-run` default, gated behind an accept step. Scope-only — no adopt code ships; seeds a 5-task dependency-wired breakdown. Rejected: overloading `--force` to merge (footgun), a separate `bongos adopt` command (leg duplication / drift), auto-import with no pre-flight, building adopt-mode now (1986 is scope-only).](<redacted>.md) | Cloud Bongos / onboarding |
+| 0123 | [Idle-swept dev boxes lose uncommitted work: an on-box autosave-push, not a VM snapshot (task [#837](https://example.com/builders#/task/837) SPIKE). `box.js`'s idle sweep hard-deletes the droplet once a box reads idle — nothing on that path checks git status, and park's snapshot was deliberately removed from the automated path for cost. Decision: a new on-box cron (sibling to `box-heartbeat.sh`) that, when `/workspace` is dirty, commits + pushes to the box's own `claude/<name>` claim branch using the same one-shot-credentialed-then-scrubbed pattern `box-source-fetch.sh` already uses for fetch — bounding loss to the autosave interval (~5 min) instead of unbounded. Open dependency: confirm/mint a push-scoped box credential (today's `BOX_SOURCE_FULL_TOKEN` is fetch-only by convention). Rejected: reintroducing snapshot-before-destroy (the exact cost the team removed), a control-plane git-status check before sweep (needs new box-exec capability, would pin dirty boxes active forever), relying on `/builder-end`'s manual dirty-check alone (doesn't fire on the automatic sweep path at all). Scope-only — no autosave code ships; seeds a follow-up implementation task.](<redacted>.md) | internal / dev-box |
+| 0124 | [Typed API response bodies — follow-up to ADR 0118 for goal 36's `api-client-sdk` (task [#2061](https://example.com/builders#/task/2061), from idea 519, BONGOS-V1). Task 2050 typed every request body but success RESPONSES stayed the `ApiResponse` (`= any`) alias — routes declare no response schema. Decision: infer the success shape STATICALLY from each route's inline `res.json({ … })` object literal (reusing the request extractor's `captureBalanced`/`splitTopLevel` machinery; never executes a route) → a `<OperationId>Response` component on the `200` `content`, and the client returns `Promise<ThatShape>`. Only KEYS are provable (values type `unknown` unless trivially safe — a boolean literal, or the ADR-0119 `pageMeta()` `page` block → a shared `PageInfo`). Degrade-gracefully: a bare value (`res.json(row)`), a top-level spread, an empty `{}`, or a computed key keeps `ApiResponse` — we only ever narrow `any`, never mistype. 162/221 endpoints now typed; runtime JS unchanged (only `openapi.json` + `index.d.ts`). Rejected: a per-route `responseSchema` export (duplicates the `res.json` truth + 200-file churn, anti-code-first), executing routes to observe responses (breaks the zero-execution contract), tracing variables to type values (brittle data-flow analysis), `additionalProperties:false` on responses (a false compile error if an unparsed branch adds a key).](<redacted>.md) | API contract / goal 36 |
+| 0125 | [The control plane scaffolds + pushes a standalone instance's repo (task [#2055](https://example.com/builders#/task/2055), BONGOS-V1, goal 35's `project-creation-flow`). `provision.js` used to THROW if a standalone instance's repo wasn't already hand-cloned at `/srv/cloudbongos/<slug>` — a manual dead-end between `bongos init` and provision. Decision: the provisioning runner SCAFFOLDS the repo itself (`scaffoldStandaloneRepo`) before the existing code-sync/db/service steps: clone the empty `target_ref` (forcing branch `main` on the unborn HEAD) → build the core tarball (`package-core.js`) → materialize `config/` + `.claude/` + a `file:`-pinned `package.json` + lockfile via `bongos init --vendor-core` (task 2053, `--no-seed`) → commit + push (with a `node_modules`-excluding `.gitignore`; vendored tarball + lockfile stay tracked). Idempotent (skips once `package.json` exists) + dry-run-safe (injected `exec`/`writeFile`). Git transport reuses the existing `github-deploy` SSH alias (no secret in any command) — the one operational grant is that the control plane's deploy key gets WRITE on each instance repo (per-repo, like the platform repo). `deploy-instance.sh` already existed at `scripts/deploy/` (ADR 0108 §4 / task 1884; the task description predated it) — it's the ongoing consumer deploy, not the first-time scaffold; no `infra/` duplicate created. Rejected: a control-plane PAT/App-token over HTTPS (token-leak risk in the URL + a new broad secret class — a GitHub App is the scalable follow-up), keeping the "clone it yourself first" throw (the dead-end itself), scaffolding from a template fork (a template repo to maintain vs `--vendor-core`'s single-source tree).](<redacted>.md) | Cloud Bongos / onboarding |
+| 0126 | [Dedicated cloudbongos.com control-plane droplet (task [#2063](https://example.com/builders#/task/2063), BONGOS-V1, goal 26). cloudbongos.com ran as a co-tenant on the OTB game droplet with the account-wide DO+Cloudflare tokens co-located on that same shared box — the powerful tokens sat next to the game and third-party co-hosted instances. Owner pulled the infra separation forward (accepting a 2nd droplet): a new dedicated droplet `REDACTED_IP` (nyc3, 2GB, tag `cloudbongos-control`, own `cloudbongos_ed25519` SSH) runs cloudbongos.com + `builders.`/`status.` AND is the sole token-holding control plane (`/etc/cloudbongos/box.env` holds the new account-wide CF token IP-locked to it + the DO token — where `provision.js` provisions subdomains). Co-hosting box keeps the game + `emersonian-circles.`/`staging.`; the co-tenant unit was decommissioned at cutover. Lift-and-shift (same repo clone, not the ADR 0108 pinned-core standalone). De-risks R89. Follow-ups: new-box deploy automation ([#2064](https://example.com/builders#/task/2064)) + strip all cloud tokens off the co-hosting box ([#2065](https://example.com/builders#/task/2065)). IPv6 egress disabled so the IPv4-locked CF token isn't spuriously rejected.](<redacted>.md) | infra / Cloud Bongos |
+| 0127 | [Cross-box fleet observability on the control-plane droplet (task [#2059](https://example.com/builders#/task/2059), BONGOS-V1). The Grafana/Prometheus stack (task 2020) exports Bongos-API metrics = *platform* observability, so it was re-homed off `metrics.example.com` onto the control-plane box at `metrics.cloudbongos.com`, watching the whole fleet. After ADR 0126 split the fleet across two droplets, Prometheus (on the control-plane box) scrapes `cloudbongos` locally and the co-hosting box's `example`+`emersonian` over the private VPC via `socat` TCP forwarders (`10.108.0.2:9101/9102`), ufw-locked to the control-plane IP. socat (raw relay) preserves the exporter's loopback-no-token semantics → no token, no game restart; the VPC+ufw is the boundary; the `METRICS_TOKEN` Bearer path is reserved for future off-VPC instances. Dashboards gained a `project` template var. Trade-off: socat exposes the whole app port (not just `/metrics`) to the trusted control-plane box over the VPC — accepted (that box already holds the account-wide tokens). Follow-up: token/DNS-SD discovery for provisioned instances.](<redacted>.md) | infra / Cloud Bongos |
+| 0128 | [Provisioning runner privilege + DB-auth model (task [#2066](https://example.com/builders#/task/2066), BONGOS-V1, goal 35's `project-creation-flow`). [ADR 0111](<redacted>.md)'s `provision.js` was built + unit-tested but NEVER run end-to-end (existing instances were hand-wired); the first real greenfield standup ([#2053](https://example.com/builders#/task/2053)–[#2056](https://example.com/builders#/task/2056)) exposed that the runner (`User=lars`, non-root) can't do its own mutating steps: `/etc` writes (`EACCES`), `systemctl` reloads, and `createdb`/`migrate` (peer-auth-as-lars, but lars isn't a usable PG role — the app uses `DATABASE_URL`). Decision: a `PROVISION_SUDO=1` knob (alias `PROVISION_PRIVILEGED`), **default OFF** (bare commands + direct `fs` writes — tests/root/co-tenant-legacy byte-unchanged); ON escalates exactly those steps — `/etc` writes via temp-file + `sudo install -D -m <mode>`, `sudo systemctl`/`sudo rm`, and `createdb`/`migrate` as `sudo -u postgres` (migrate passes env via `env …`+`bash …` to survive sudo's env reset). Dry-run always logs the exact command. The runner unit gains `Environment=PROVISION_SUDO=1` and **must** flip `NoNewPrivileges` false (a `true` value sets `PR_SET_NO_NEW_PRIVS`, silently blocking the setuid `sudo`). Preconditions: passwordless sudo for the runner user + a postgres-readable checkout. Rejected: granting `lars` a PG role + writable `/etc` (non-portable, weakens the trust boundary), running the whole runner as root (over-privileged vs per-step sudo), createdb/migrate via the app `DATABASE_URL` (valid alt, but the runner holds no app DB creds today). The dedicated-droplet cloud-init path is left unchanged (root context, out of scope).](<redacted>.md) | infra / Cloud Bongos |
+| 0129 | [cloudbongos.com control-plane box deploys by a pull timer, not the CI push (task [#2064](https://example.com/builders#/task/2064), BONGOS-V1, follows ADR 0126). After the dedicated-droplet migration, the co-hosting box's CI deploy only touched example.com — nothing pulled `main` onto the new box, so cloudbongos.com drifted. Chosen: a pull-based `systemd` timer (`infra/cloudbongos-deploy.{service,timer}` → `scripts/deploy/deploy-cloudbongos.sh`: fetch+reset → npm ci if lockfile changed → `MEDUSA_GDS_ONLY` GDS-only migrate of the `cloudbongos` DB → restart `cloudbongos` → 3002 healthz), every ~2 min with a fast no-op path. Rejected extending the CI push: that would store THIS box's prod SSH key as a GitHub Actions secret — more sprawl, against ADR 0126's blast-radius reduction; the pull uses the box's existing `github-deploy` key and touches no shared secret. Two divergences from `deploy-prod.sh`: the executed script is a stable copy at `/home/lars/deploy.sh` (so `git reset` can't corrupt the running script), and the SEC [#863](https://example.com/builders#/task/863) audit gate is non-fatal here (the cloudbongos DB can't resolve OTB author ranks; the authoritative gate runs on the co-hosting box + CI against the same main). One-time operator bootstrap; self-heals after.](<redacted>.md) | infra / Cloud Bongos |
+| 0130 | [provision.js remote-exec over SSH — the control plane orchestrates co-tenant workloads on the co-hosting box (task [#2065](https://example.com/builders#/task/2065), BONGOS-V1, follows ADR 0126). To reach ZERO cloud tokens on the co-hosting box, the provisioning runner must move to the token-holding control plane yet still drive co-tenants that RUN on the co-hosting box. Decision: thread a target through `provision.js`'s injected executors — box-target `exec`/`writeFile` run box-mutating steps (createdb, migrate, /etc, systemctl, Caddy, healthz) on `PROVISION_REMOTE_HOST` over `ssh <host> bash -s` (stdin-fed, no quoting; files base64→`sudo tee`); `controlExec`/`controlWriteFile` keep the token step (Cloudflare DNS hook) + the standalone repo scaffold LOCAL where the token/toolchain live. Default OFF (unset ⇒ byte-identical local, today's behavior). `box.js` needs no change (pure DO/CF API — runs from the control plane with the tokens). `PROVISION_PUBLIC_IP` = the co-hosting box IP (co-tenant A records point where they run). Ships a control-plane runner unit (`infra/provision-intent-runner-cloudbongos.{service,timer}`, later superseded by `cohost-provision-intent-runner.*` — ADR 0132). Creates a control-plane→co-hosting SSH trust edge (token-holder commands token-free box, never reverse). Activation (SSH trust · runner move · token removal+rotation · rollback-DB drop) is a sequenced OWNER op — blocker attached to 2065.](<redacted>.md) | infra / Cloud Bongos |
+| 0131 | [Rank-scoped skill visibility — feasibility spike (task [#1650](https://example.com/builders#/task/1650)). Wanted: a session lists only the skills the builder's rank can use, via a SessionStart hook filtering the skill menu — pure UX declutter (the server rank gate + each skill's early self-check still enforce). Finding: Claude Code hooks CANNOT filter/hide/rewrite the skill listing — SessionStart offers only `additionalContext` (inject text) + `reloadSkills` (add-only), no hook subtracts a skill, and hooks can't mutate settings at runtime. A HARD menu hide needs a pre-launch step (the launcher that already fetches rank) writing per-builder `skillOverrides:"off"` into `.claude/settings.local.json` before `claude` starts (misses plugin skills; workspace-trust-gated). Recommendation: don't build the heavy launcher change for a cosmetic gain; if some declutter is wanted now, use the existing hook's `additionalContext` as a soft nudge; keep the server gate + self-checks. Owner to decide.](<redacted>.md) | dx / skills |
+| 0132 | [Migrate the co-hosting fleet to the control plane over an SSH DB tunnel (task [#2071](https://example.com/builders#/task/2071), BONGOS-V1, goal 26; extends ADR 0130, completes 2065 / blocker 64). Stripping the co-hosting box's tokens proved NOT a switch-flip: it runs FIVE token-consuming timers (the 4 `box.js` dev-box lifecycle sweeps + `provision-intent-runner`), each reading its queue from the box's LOCAL `example` Postgres (firewalled to localhost) — so a control-plane runner can't reach the queues, and ADR 0130 moved only box-step execution, not queue reading. Also `box.js` was never migrated. Decision: a persistent SSH tunnel (control-plane `127.0.0.1:5433` → co-hosting `127.0.0.1:5432`, `infra/cohost-db-tunnel.service`) + all five runners re-homed as `cohost-*` control-plane variants reading the example queues via `DATABASE_URL` through the tunnel (no public Postgres exposure), calling DO/CF with the control-plane tokens; provisioning remote-execs box steps per ADR 0130. DB auth: a scram password on the EXISTING `lars` role (identical privileges the runners already use; reachable only via `127.0.0.1`), stored only in chmod-600 `/etc/cloudbongos/cohost-fleet.env`. `box.js` unchanged (pure DO/CF API + Discord/DNS-hook execs, all on the control plane). `cohost-provision-intent-runner.*` supersedes 2065's `provision-intent-runner-cloudbongos.*`. Rejected: exposing Postgres over the VPC (opens a TCP surface + `pg_hba`/cred work; droplets not guaranteed same-VPC); a token-signing broker on the co-hosting box (leaves tokens' blast radius there — opposite of the goal); moving the queue tables to the cloudbongos DB (the OTB web tier can't reach it either — firewall symmetry). Units ship additive + not-enabled, self-healed install-only. Activation (SSH trust · DB password · tunnel · enable `cohost-*` + disable co-hosting timers same window · verify via drift-reconcile · bake · owner token rotate+strip · drop rollback DB) is a sequenced operator-op.](<redacted>.md) | infra / Cloud Bongos |
+| 0133 | [One-click GitHub sign-in for onboarding via the GitHub App Manifest flow (task [#2080](https://example.com/builders#/task/2080), BONGOS-V1, goal 35 / criterion 165). The last onboarding friction was wiring GitHub sign-in — the owner had to hand-create an OAuth App + paste a client secret, unscriptable because GitHub has NO create-OAuth-App API. Decision: use GitHub's App **Manifest** flow. The signed-in owner clicks one pre-filled link; GitHub creates the App and returns a temporary `code`; the control-plane runner (`provision.js`, sole token-holder) exchanges it for `client_id`/`client_secret`, writes them to `/etc/<slug>/web.env` (the `oauth-secret.js` path), restarts, and verifies `/healthz` auth_configured — the secret never touches the browser, chat, or web tier. Spans the trust boundary: web tier mints a one-time `state` + stores a `provisioning_oauth_manifests` row + a PUBLIC callback stores GitHub's code (`state` is the auth); the control-plane runner drains `code_received` rows on its existing timer tick (gated on instance=active). Sign-in code unchanged — a GitHub App's user token hits the same `GET /user`; GitHub ignores the extra `scope` for Apps. Back-compat: existing OAuth-app instances untouched; manifest is the new default, manual path kept as fallback. All three onboarding surfaces (hall wizard one-click button, `bongos onboard`, `/new-project`) updated in lockstep.](<redacted>.md) | onboarding / auth |
+| 0134 | [Private-first npm distribution for the core + client (task [#2089](https://example.com/builders#/task/2089), BONGOS-V1, goal 35 / criterion 165; refines [#2025](https://example.com/builders#/task/2025), builds on ADR 0108). Owner wants the npm/CLI onboarding commands ready but private pre-launch, choosing paid private npm over free GitHub Packages. npm rule forces the shape: unscoped names are always public, only SCOPED packages can be private (paid plan) — so the private form stays scoped `@cloudbongos/core` + `@cloudbongos/client` (zero rename; org already owned). Decision: publish both as scoped PRIVATE packages now via `publishConfig:{access:"restricted"}` baked into the synthesized core `package.json` (`package-core.js buildPackageJson`) + the generated client `package.json` (`gen-api-client.js`); `package-core.js --publish` dry-runs by default, real publish needs `--publish --live` + owner `npm login` (tooling holds no token). Consumers auth via env-fed `.npmrc` `_authToken=<redacted> Vendored-tarball install (task 2053) stays the working default; provision/init registry auto-pull is a follow-up. Going public at launch is one flag (`npm access public`) or task 2025's unscoped vanity `cloudbongos` — 2025 becomes the go-public step, not superseded. The daily `bongos` command is name-independent throughout. Runbook: docs/recipes/private-npm-distribution.md.](<redacted>.md) | distribution / npm |
+
+> ⚠️ **Numbering collision (known):** two ADRs share `0008`. The numbers were assigned in parallel sessions before the lock could be enforced. The files are kept under their existing filenames to preserve git history, but the table disambiguates them as `0008-a` / `0008-b`. New ADRs should resume at `0040` to avoid further collisions. (`0024` is also a real on-disk duplicate: the cloneable-repo/local-first-memory ADR and the multi-agent-system-architecture ADR were both numbered `0024` in parallel; both keep their filenames, disambiguated as `0024-a` / `0024-b` like `0008`. Likewise `0025` ended up with two on-disk files — the offsite-backup ADR and the structured-criterion↔task-link ADR — both kept under their existing filenames and disambiguated as `0025-a` / `0025-b`; separately, the BFG ADR had also claimed `0025` on 2026-05-30 and yielded to `0026`. A third happened 2026-06-06: `0036` was claimed in parallel by the builders-subdomain ADR ([#726](https://example.com/builders#/task/726)) and this Discord-channels ADR ([#727](https://example.com/builders#/task/727)); the Discord-channels ADR yielded to `0037`. A fourth landed 2026-06-10: `0044` was claimed in parallel by the palette-replacement ADR and the per-box game-preview ADR ([#897](https://example.com/builders#/task/897)); both keep their filenames, disambiguated as `0044-a` / `0044-b` like `0008`. A fifth was caught pre-land 2026-06-13: `0050` was claimed in parallel by the device-flow-admission ADR ([#1000](https://example.com/builders#/task/1000)) and the sandbox-for-everyone ADR ([#1001](https://example.com/builders#/task/1001)); the latter yielded to `0052` before merging, so there is no `0050` duplicate. A sixth was caught pre-land 2026-06-21: the tool-agnostic-design-layer ADR ([#1375](https://example.com/builders#/task/1375)) first collided at `0079` with the value-gated-autonomous-engagement ADR, then at `0080` with the llm-cache-api-transport ADR (both part of the 0075–0080 LLM-cost-reduction series, landed on `main` in parallel); it yielded to `0081` before merging, so there is no `0079`/`0080` design-layer duplicate. A seventh landed 2026-06-23: `0084` was claimed in parallel by the auto-derived-per-task-rank-floor ADR and the remove-default-spend-cap ADR (task 1499); the rank-floor ADR landed on `main` first, so the spend-cap ADR yielded to `0085`, leaving no `0084` duplicate. An eighth landed 2026-06-27: `0095` was claimed in parallel by the borrowed-memory-and-retrieval-concepts ADR (PR #459, landed first) and the cross-agent-context-management ADR ([#1651](https://example.com/builders#/task/1651), PR #460); both keep their filenames, disambiguated as `0095-a` / `0095-b` like `0008`. These two are companions — `0095-a` adopts the memory/retrieval concepts and explicitly defers the grep-vs-semantic question to `0095-b`.)