@bongos/core 1.17.0

package/docs/adr/0091-bounding-the-kernel-and-db-carve.md

@@ -0,0 +1,106 @@
+# ADR 0091 — Bounding the kernel and carving `db.js` per-domain (Config-B core decomposition)
+
+**Status:** Accepted (2026-06-26) · task [#1570](https://example.com/builders#/task/1570) (BV1.R67) · criterion **C7 `gds-core-modularized`** (BONGOS-V1) · planning [session 2026-06-26](../session-logs/<redacted>.md)
+
+**Amends:** [ADR 0083](<redacted>.md) — the strangler build plan. ADR 0083 §"The four module moves" cut the four *feature* modules (dev-box, game, discord, art-pipeline) around an undifferentiated core. This ADR extends the same strangler to the **core itself**: it bounds the kernel as a real artifact and defines how a *core domain* becomes a module. It changes nothing about 0083's five rules, the loader, or the fitness ratchet — it gives the "kernel" 0083 kept referring to a concrete file roster, and the "carve `db.js` per-domain" 0083 mentioned ([02 §3](../design/modular-architecture/02-module-map.md)) a mechanism.
+
+**Builds on:** [ADR 0016](<redacted>.md) (server-enforced rank boundary — the kernel *is* the trust boundary), [ADR 0043](<redacted>.md) (protected paths), [ADR 0086](<redacted>.md) (module-scope-map), [ADR 0062](<redacted>.md) (core↔host split — same "neutral contract, swappable behind it" shape).
+
+**Relates to:** [ADR 0095](<redacted>.md) — the *findability* complement to this ADR's *structural* scoping (authored alongside it): 0091 bounds how much an agent loads (kernel + per-domain modules); 0095 helps the agent find the right place within it (docstrings, greppability, retrieval). The module-header doc-comment convention 0095 adopts is authored per module the carve here defines.
+
+---
+
+## Context
+
+ADR 0083's Config A moved the four feature modules — the *least*-coupled ~26% of the tree — into `modules/<key>/`. The audit that opened C7 ([planning 2026-06-26](../session-logs/<redacted>.md)) found the remaining ~70% ("core") is **not one thing**: it is ~8–10 cohesive domains sitting on a small (~3.5k-LOC) trust kernel ([02 §1](../design/modular-architecture/02-module-map.md)), but nothing in the code marks where the kernel ends and a domain begins. Three concrete symptoms:
+
+1. **The "kernel" is unbounded.** `fitness.js` `KERNEL_FILES` (`fitness.js:449-456`) is only the **6 module-system-machinery files** (`module-api`, `modules`, `module-seams`, the three `module-loader/*`). The real trust kernel — `auth.js`, `route-rank-check.js`, `permission-path-check.js`, `pool.js`, `secret-box.js`, config/identity — is nowhere named, so no fitness check guards it and no one can say "is this file kernel?" with a yes/no answer.
+2. **`db.js` is a 6063-LOC monolith** (383 exports, `require`d by 23 files) spanning every domain — builder identity, audit, tasks/claims/versions, memory search, grade-attempt logs, security docs, merge leases. It is the single biggest blocker to per-module AI-scoping: a "work on memory" task drags the whole file into context.
+3. **The doorway leaks domain queries.** `src/module-api.js` re-exports `getBuilderById`/`createTask`/`insertAuditLog`/`getBuilderGeminiKeyRow`/`setBuilderBoxBlocked`/`captureIdea` (`module-api.js:86-103`). Some of those (identity, audit, rank) are genuinely kernel; others (`createTask`, gemini keys, box-blocked, `captureIdea`) are **domain** capabilities the kernel should not own. There is also **no `withTx`** on the doorway, so a carved domain that needs a transaction (memory does — `memory.js:107,198,441` run raw `client.query('BEGIN')`) has no kernel-blessed way to get one.
+
+This ADR settles the three questions C7's tranche-1 tasks (R68–R74) each execute: **what is the kernel**, **how does a carved domain own its SQL**, and **what does the doorway expose**.
+
+---
+
+## Decision
+
+### 1. The kernel is a bounded, enumerated file roster
+
+The **kernel** is the trust boundary + identity + the module-system machinery — the *only* code a core-domain module may reach, and only through `src/module-api.js`. It is exactly this roster (this list replaces the 6-file `KERNEL_FILES` in `fitness.js`, the R70 ratchet):
+
+| Concern | Files | Why kernel |
+|---|---|---|
+| **Authz gates** | `src/bongos/auth.js` | `requireBuilder`/`requireRank`/`rankMeetsThreshold`/`allowBoxScope`/`requireBfgPrincipal` — the ADR 0016 boundary every route composes |
+| **Trust classification** | `src/bongos/route-rank-check.js`, `src/bongos/permission-path-check.js` | deterministic route→rank + protected-path matching (the "unknown write = blocker" rule + `PROTECTED_GLOBS`, ADR 0043) — cross-cutting, enforced by composition, never "called" by a domain ([02 §5](../design/modular-architecture/02-module-map.md)) |
+| **Secret primitive** | `src/bongos/secret-box.js` | AES-256-GCM box for per-builder secrets at rest |
+| **Data substrate** | `src/bongos/pool.js`, **`src/bongos/db-kernel.js`** *(new, R69)* | the singleton pool + `withTx` + the genuinely-kernel `builders`-identity / `audit_log` / rank-ladder slice carved out of `db.js` |
+| **Config / identity** | `src/instance-config.js`, `src/branding.js`, `src/build-info.js` | host context a module reads, never hardcodes (ADR 0062) |
+| **Shared route helpers** | `src/bongos/routes/_helpers.js` | `validateOrRespond`/`LIMITS` — the request validators the doorway re-exports so a module's routes don't vendor their own |
+| **Module-system machinery** | `src/module-api.js`, `src/modules.js`, `src/module-seams.js`, `src/module-loader/{loader,manifest-schema,semver}.js`, `src/bongos/module-scope-map.js` | the doorway, registry, seam switchboard, disk loader, and the module→path scope map (ADR 0086) |
+
+**Everything else in `src/bongos/` is a domain**, destined to become a module (memory, grading, economy, onboarding, ideas, builder-settings, sessions/BFG, security, …) or to stay inside the **lifecycle** state machine (tasks/claims/versions/ship — explicitly **not** split, [02 §4](../design/modular-architecture/02-module-map.md)). The roster is a **ratchet, not a wish**: R70 adds `KERNEL_FILES` = this list **and** a check that no kernel file `require`s a soon-to-be-module domain, so a regression is a red build. `db-kernel.js` joins the roster when R69 creates it; until then the roster is the trust files above (all confirmed present at this commit).
+
+### 2. `db.js` is carved per-domain — the module owns its SQL, the kernel owns identity/audit/tx
+
+The carve pattern is **already proven** by the discord move (`modules/discord/db.js`, BV1.R47) and the game move (`modules/game/db.js`). C7 ratifies it as *the* mechanism every core-domain carve copies:
+
+- A carved domain module ships its own `modules/<key>/db.js` that **requires only `../../src/module-api.js`** and reaches Postgres through the doorway's `pool` (and `withTx` — see Decision §3). Its domain queries are **lifted verbatim** out of `src/bongos/db.js` and **deleted from core** (`db.js` shrinks by that slice). The module re-exports any kernel helpers it consumes (e.g. `insertAuditLog`) off the doorway behind the *same* `db.*` namespace, so the module's own files keep `const db = require('./db')` unchanged.
+- **`db.js` shrinks toward two residues:** (a) the **kernel slice** — builder identity (`getBuilderById`), audit (`insertAuditLog`), the rank ladder (`LIVE_RANK_LADDER`), and `withTx` — extracted to `src/bongos/db-kernel.js` (R69) which the doorway re-exports; and (b) the **lifecycle** state-machine queries (tasks/claims/versions/ship), which stay in core because the lifecycle is not a module.
+- **Boundary-forced duplication is allowed and documented.** Where core *and* a module both need a query against a shared table, the module vendors its own copy (the discord `getDiscordLink`/`recordApplause` precedent) rather than importing core — a module can never `require` core internals. Each such twin carries a "keep in sync" note in the module's `CLAUDE.md`.
+- **Migrations stay additive + namespaced** (ADR 0083 §Module-owned migrations, unchanged). Carving *code* does not move *tables*; a domain's tables are reached through the pool and only ever extended by `modules/<key>/migrations/` going forward. No data moves, no down-path.
+
+R69 proves the pattern on **one reference slice**; R72 (memory) and R73 (grading) are the first two real carves.
+
+### 3. The doorway exposes kernel capabilities permanently and domain capabilities only as marked, temporary re-exports
+
+`src/module-api.js` is classified into three buckets. R68 executes the move and bumps `CORE_VERSION` minor (additive: `withTx`).
+
+- **Kernel — stays, permanently** (these legitimately belong to the kernel): all auth gates; `pool`/`getPool`/`instanceDbName`; **`withTx`** *(new)*; `secretBox`; `getBuilderById` (identity), `insertAuditLog` (audit), `LIVE_RANK_LADDER` (rank); all config/identity (`branding`/`resolveEnv`/`config*`); all seams; `buildInfo`/`validateOrRespond`/`LIMITS`; `logger`. After R69 these resolve through `db-kernel.js`, not the monolith.
+- **Domain leak — relocate to the owning module's `db.js` slice** (the module exists today; it just lacks a slice): `setBuilderBoxBlocked` → `modules/dev-box/db.js`; `getBuilderGeminiKeyRow`/`setBuilderGeminiKey`/`clearBuilderGeminiKey` → `modules/art-pipeline/db.js`. R68 deletes these doorway re-exports and the module owns the query (R69 pattern). This severs the last `dev-box`/`art-pipeline` → core-`db.js` dependency.
+- **Domain leak — temporary, behind a `pending-seam` note** (the owning domain is *not* carved in tranche 1, so a clean home does not exist yet): `createTask` (lifecycle), `captureIdea` (ideas), `VOTABLE_TASK_STATUSES` (lifecycle/task-classifier). These **stay on the doorway** for now, each tagged in `module-api.js` as "DOMAIN capability, not kernel — relocates behind a `lifecycle.*` / `ideas.*` port when that domain is carved (tranche 2)." Pretending they're kernel is the thing to avoid; deleting them now would break the discord module (its `db.js` consumes all three). The honest state — *known leak, named owner, tracked* — is what the ADR records.
+
+**Why `createTask` is not just made a port now:** the consumer (discord-bugs filing a task) is real, but the *provider* (a lifecycle module) does not exist until tranche 2. Registering a `lifecycle.createTask` port with core itself as the provider would be ceremony with no boundary benefit while lifecycle is still core. The port lands when lifecycle is carved; until then the doorway re-export *is* the seam, explicitly marked.
+
+### 4. A capability the lifecycle invokes resolves through a kernel PORT, never a direct import
+
+The lifecycle (tasks/claims/versions/ship) stays whole, but the capabilities it *calls* are extracted. `routes/tasks.js` (the ship path) currently `require`s `grader.js` directly — a core→domain edge once grading is a module. R73 replaces it with the seam: grading `registerProvider('grade', …)` at boot; the lifecycle does `resolve('grade')(…)` at ship. This proves the design's load-bearing pattern — *keep the state machine, extract the capability behind a seam* ([04 §1](../design/modular-architecture/04-module-lifecycle.md), [02 §4](../design/modular-architecture/02-module-map.md)) — and closes the audit's "ports were illustrative-only" gap.
+
+---
+
+## The sub-task shape (C7 tranche 1 — seeded, dependency-wired)
+
+This ADR's deliverable is the decision above **plus** the carve broken into claimable steps. Already seeded under C7 ([planning 2026-06-26](../session-logs/<redacted>.md)); dependency edges authoritative:
+
+| Task | Delivers | Depends on |
+|---|---|---|
+| **R67** ([#1570](https://example.com/builders#/task/1570)) | *this ADR* — kernel roster + carve strategy + doorway classification | — |
+| **R68** ([#1571](https://example.com/builders#/task/1571)) | doorway: add `withTx`; relocate the dev-box/art domain leaks; mark the lifecycle/ideas leaks; `CORE_VERSION` minor bump | R67 |
+| **R69** ([#1572](https://example.com/builders#/task/1572)) | the per-domain db-slice pattern + extract `db-kernel.js` (identity/audit/rank/tx) as the reference slice | R67, R68 |
+| **R70** ([#1573](https://example.com/builders#/task/1573)) | fitness: `KERNEL_FILES` = the real roster (§1) + "kernel imports no domain" check | R67 |
+| **R71** ([#1574](https://example.com/builders#/task/1574)) | register `memory` + `grading` keys in `module-scope-map.js`; widen goal 10 scope | R67 |
+| **R72** ([#1575](https://example.com/builders#/task/1575)) | carve `memory` → `modules/memory/` (memory·search·search-chunker·learnings + db slice) | R69, R71 |
+| **R73** ([#1576](https://example.com/builders#/task/1576)) | carve `grading` → `modules/grading/`; lifecycle resolves `grade` via a kernel PORT | R68, R69, R71 |
+| **R74** ([#1578](https://example.com/builders#/task/1578)) | proof: memory + grading live as modules, `db.js` shrank, kernel bounded + fitness green, OTB byte-identical | R72, R73 |
+
+**Proof of equivalence at every step** (ADR 0083 / 0062 discipline): after each carve, OTB behaves **byte-for-byte the same**. That is the per-task done-when.
+
+**Tranche-1 status: PROVEN** (R74, [#1578](https://example.com/builders#/task/1578)). The five claims above are demonstrated, in one re-runnable command, by [`scripts/gds/coreB-carve-proof.sh`](../../scripts/gds/coreB-carve-proof.sh): memory + grading are loader-discovered modules; `db-kernel.js` + the memory query slice left the `db.js` monolith; `KERNEL_FILES` is the bounded 17-file roster with zero fitness hard-failures (incl. the three ENFORCING C7 boundary checks); grading resolves through the `grade` kernel port (`seams.resolveOptional('grade')`) with no core→grader import; and the 27 DB-free tests exercising the carved surfaces pass unchanged (byte-identical). The ongoing guard is CI — `fitness.js` (the kernel-imports-no-domain ratchet flips red at zero leaks) + `run-unit-tests.js` on every PR; the script is the consolidated demonstration, not a new gate. Tranche 2 (the remaining ~8 core domains) stays deferred per owner until greenlit.
+
+---
+
+## Consequences
+
+**Positive.** The kernel becomes a yes/no artifact a fitness check guards (R70) — the trust boundary stops being "wherever the trust code happens to sit." `db.js` shrinks toward the lifecycle + a small kernel slice, so a core-domain task loads its module + the doorway, not a 6k-LOC monolith (the AI-scoping payoff Config A could not deliver). The doorway stops lying about what is kernel. The `grade`-via-port move makes the seam mechanism real instead of illustrative.
+
+**Negative / cost.** More boundaries to enforce (mitigated: fitness, not reviewers). `db.js` carving is delicate — a missed call site is a runtime break, so each carve verifies byte-identical behavior + runs the smoke suite. The honest "temporary doorway leak" bucket (Decision §3, third group) is real debt — but *named, owned, and tracked* debt, retired when tranche 2 carves lifecycle/ideas. Touching `module-api.js`, `fitness.js`, `db.js`, and `route-rank-check.js`/`permission-path-check.js` (kernel trust surfaces) means owner Gate approval is expected on those PRs — the boundary working as designed.
+
+**Neutral.** Single-package / single-process / no-bundler preserved (ADR 0083 unchanged). Tranche 2 (the other ~8 core domains: economy, onboarding, ideas, builder-settings, sessions/BFG, security, the UIs, lifecycle-as-its-own-module) is deferred per owner — this ADR proves the pattern on the two cleanest-slicing domains first.
+
+---
+
+## Alternatives considered
+
+- **Leave the kernel implicit (status quo) — rejected.** "The kernel is whatever the trust code happens to be" cannot be fitness-enforced and gives an AI agent no answer to "is this file kernel?" Bounding it is the precondition for every later check.
+- **Carve `db.js` by splitting the file in place (sections, not modules) — rejected.** Section comments already exist and did nothing for coupling or scoping; only moving a slice *out* to `modules/<key>/db.js` (behind the doorway) severs the dependency and shrinks the context an agent loads.
+- **Make every doorway leak a port immediately — rejected for tranche 1.** A port with core as its own provider is ceremony with no boundary benefit until the providing domain is actually a module. Mark the leak, carve the domain, *then* add the port (R73 does exactly this for `grade`, where the provider genuinely becomes a module).
+- **Split the lifecycle state machine into per-route modules (Config C) — rejected** (ADR 0083 already; restated because the `db.js` carve makes it tempting). tasks/claims/versions/ship are one coupled cluster; forcing them apart fights cohesion. Extract the *capabilities* (grade, reward), keep the *machine*.

package/docs/adr/0092-hosting-module-and-on-prem-target.md

@@ -0,0 +1,117 @@
+# 0092 — Hosting module + on-prem (warehouse) hosting target
+
+- **Status:** Accepted (direction decided with the owner 2026-06-27; build is task-pending — see Implementation)
+- **Date:** 2026-06-27
+- **Deciders:** Lars (Archon), Claude
+
+**Builds on:** [ADR 0083](<redacted>.md) (modular architecture — the module this capability ships as), [ADR 0089](<redacted>.md) (the `ModelProvider` `openai-compatible` adapter the on-prem inference target reuses, and its decisive hosting-cost finding), [ADR 0062](<redacted>.md) (core↔host decoupling — the warehouse box is host-instance config, not portable core), [ADR 0081](<redacted>.md) (swappable adapters against a neutral contract), [ADR 0031](<redacted>.md) (cloud dev boxes — a workload a later phase may partly displace), [ADR 0060](0060-gds-retrieval-layer.md) (recall/embeddings — a consumer), [ADR 0088](<redacted>.md) (the per-character LoRA deferred as "needs GPU training + an open model" — a workload this enables), [ADR 0016](<redacted>.md) / [ADR 0043](<redacted>.md) (server-enforced trust boundary the box must never weaken), [ADR 0033](<redacted>.md) (the precedent for a useful service that sits *outside* the trust boundary).
+
+**Track:** `internal` (a portable Cloud Bongos platform capability).
+
+---
+
+## Context
+
+Example wants to stand up a physical server inside the warehouse to (a) cut software-hosting cost, (b) get cheaper access to open-weight LLMs and code, and (c) capture other on-prem advantages. OTB runs on a <$5K/yr budget ([CLAUDE.md §4](../../CLAUDE.md)): a ~$14/mo DigitalOcean droplet for prod, cloud LLM APIs (Claude for code, Gemini for art), and per-builder cloud dev boxes ([ADR 0031](<redacted>.md)). The largest *variable* cost is LLM spend.
+
+This ADR records the **scope-of-use** decision — the first of the four phases the owner set: *scope use → scope build → hardware setup → software use* — and the shape the capability ships in. The build, hardware, and software phases are task-pending.
+
+### The reframe: a portable module + a host-specific target
+
+A warehouse server is *hardware*; a Cloud Bongos module is *software that mounts into a running instance* ([ADR 0083](<redacted>.md)). So "the hosting module" is **not** "the server in a folder." Following the core↔host split already used for branding ([ADR 0062](<redacted>.md)) and design tools ([ADR 0081](<redacted>.md)):
+
+- **The `hosting` module (portable core):** a broker, default-**OFF**, that exposes labeled compute/storage **seams** and resolves each to a configured **target**. The default target is today's cloud/APIs, so a vanilla instance behaves exactly as it does now (fail-to-vanilla, like the loader with no `modules/`).
+- **The warehouse box (host-instance config):** one **on-prem target** an adapter points at, declared in OTB's instance config — not in portable code. Another Cloud Bongos instance declares none and stays all-cloud.
+
+Two properties fall straight out, and they answer the two standing objections to on-prem:
+
+1. **Nothing depends on the box.** Each seam resolves through `resolveOptional(port, cloudDefaultFn)` ([ADR 0083](<redacted>.md)); a target marked unreachable falls back to cloud per-call. The box is an opportunistic cost-saver, never a single point of failure. (This is also why public, real-time prod — the game's Colyseus rooms — stays in the cloud: you can't fail a live socket over mid-session.)
+2. **Every Example instance shares it.** The owner chose to size and abstract the box as a shared backend across all Example Cloud Bongos instances — one GPU amortized across projects is what raises utilization enough to matter.
+
+### Honest economics — what the GPU is and isn't good for
+
+[ADR 0089](<redacted>.md)'s market sweep is decisive and we adopt it rather than relitigate: **at low volume, pay-per-call open-model APIs (DeepInfra / OpenRouter) beat self-hosting** — a few-thousand-calls/month workload is ~$1–5/mo on API, and a fixed, cached prompt crushes the bill. A self-hosted GPU only wins when it is *kept busy* or when per-call cloud pricing is high.
+
+So the warehouse GPU earns its keep on a **narrower** set than "all inference":
+
+- **GPU-bound batch generation** — art image-gen at volume across instances (priced per-image in the cloud).
+- **Model fine-tuning / training** — the per-character LoRA [ADR 0088](<redacted>.md) deferred as "level-2 (needs GPU training + an open model)"; cloud charges steep per-GPU-hour, an owned card amortizes.
+- **Always-busy bulk jobs** — overnight eval/analysis at a scale that saturates the card.
+
+The **non-GPU wins** stand on their own:
+
+- **Backups + bulk storage** — today our secrets live only on the droplet, *unbacked-up*; a NAS role closes a real gap.
+- **An unmetered experimentation sandbox** — run pipelines and model evals without metering every token.
+- **An always-on cron host** for the ~17 scheduled routines.
+
+Conversely — correcting an earlier hand-wave in this session — **embeddings and low-volume grading are cheaper on pay-per-call APIs** and are *not* a GPU justification by themselves; they move on-prem only opportunistically once the box exists, or for data-locality. **Code that ships stays on Claude regardless** (the quality-first rule, [CLAUDE.md §2](../../CLAUDE.md)).
+
+### Owner decisions (2026-06-27)
+
+1. **Who it serves:** all Example Cloud Bongos instances (shared backend; build the cross-instance abstraction now).
+2. **Quality posture:** **conservative** — local open-weight models do NON-SHIPPING work only (batch gen, training, eval, opportunistic embeddings, storage); shipping code stays on Claude. Expanding posture later is a config change, not a rebuild.
+3. **Proceed:** the capability is worth building — justified by the cross-instance multiplier + the owned-asset/training optionality + the storage/sandbox wins, **not** by near-term API savings alone.
+
+---
+
+## Decision
+
+**Ship a portable `hosting` module (default-OFF, fail-to-vanilla) that brokers compute and storage workloads to configured hosting targets through kernel seams, reusing the [ADR 0089](<redacted>.md) `ModelProvider` adapter contract for inference. A GPU box in the Example warehouse is OTB's first on-prem target — one adapter backend declared in host-instance config, shared across Example instances, with automatic cloud fallback so nothing ever depends on the box.**
+
+### 1. The module shape
+
+```
+modules/hosting/
+  module.json                       # key "hosting"; default false; coreVersion ^1.x
+  routes/hosting.js                  # Archon-gated admin: register/inspect targets, health, routing policy
+  pollers/target-health.js          # heartbeat each target; flip healthy/unreachable (drives fallback)
+  adapters/                         # cloud (default) + on-prem (openai-compatible, per ADR 0089) backends
+  migrations/001_hosting_targets.sql # hosting_targets, hosting_jobs (namespaced hosting_*)
+  CLAUDE.md                          # per-module reference
+```
+
+### 2. Seams it provides (ports)
+
+The module registers providers; consumers resolve via `resolveOptional(port, cloudDefaultFn)`, so a box-less or module-off instance degrades to cloud automatically.
+
+| Seam | Consumer(s) | Conservative-posture target |
+|---|---|---|
+| `inference.run` | grader ([ADR 0089](<redacted>.md)), eval cron | API by default; on-prem only when saturated / data-local |
+| `imagegen.run` | art-pipeline | **on-prem GPU** (batch) when up, else Gemini |
+| `embeddings.embed` | recall ([ADR 0060](0060-gds-retrieval-layer.md)) | API (cheap) by default; on-prem opportunistic |
+| `training.run` | art-pipeline (LoRA, [ADR 0088](<redacted>.md) L2) | **on-prem GPU** |
+| `storage.put/get` | backups, art assets | **on-prem NAS** + offsite copy |
+
+Inference does **not** reinvent [ADR 0089](<redacted>.md): the on-prem target is just one more `openai-compatible` `ModelProvider` endpoint (vLLM / Ollama) alongside the hosted ones. The hosting module adds the *target selection + health/fallback + sharing config* around it.
+
+### 3. Network + trust boundary
+
+- **Ingress:** the cloud instance reaches the warehouse box over an **outbound tunnel the box initiates** (e.g. Cloudflare Tunnel or WireGuard) — no open inbound ports, no static-IP requirement, no DDoS exposure at the warehouse. This sidesteps the whole residential/commercial-internet problem.
+- **Trust boundary ([ADR 0016](<redacted>.md) / [ADR 0043](<redacted>.md)):** the box runs jobs and holds model weights, but authority stays server-enforced in the cloud GDS. The box sits **outside** the trust boundary — like Discord ([ADR 0033](<redacted>.md)): it can compute, it can never grant rank or land code. A compromised box can degrade or poison *non-shipping* outputs (hence the conservative posture, and the grader staying authoritative), never escalate permissions.
+
+### 4. How this subproject is filed (the durable home)
+
+- **This ADR** — the decision + shape + phased plan; the pickup point a future session reads.
+- **GDS DB (live state)** — the scoping task [#1618](https://example.com/builders#/task/1618) (shipped with this ADR), and the follow-ons [#1619](https://example.com/builders#/task/1619) (build-scope), [#1620](https://example.com/builders#/task/1620) (hardware), [#1621](https://example.com/builders#/task/1621) (cost read-out).
+- **`modules/hosting/` + its nested `CLAUDE.md`** — created in Phase 2 via `bongos module new hosting`.
+- **Session log** — this session's record under `docs/session-logs/`.
+
+---
+
+## Consequences
+
+- A vanilla Cloud Bongos instance stays **byte-identical to today** (module off → every seam resolves to cloud).
+- OTB gains an owned compute/storage asset and an unmetered sandbox, and closes the secrets-backup gap.
+- **New surface to maintain:** the module, the tunnel, the box. Mitigated by fail-to-vanilla + conservative posture — no shipping path depends on it.
+- Near-term dollar savings are **modest**; the bet is on utilization (training + batch gen, pooled across instances) and optionality. Revisit at the build phase against real spend (task [#1621](https://example.com/builders#/task/1621)).
+
+## Implementation
+
+Owner-set phased arc — scope use ✅ (this ADR, task [#1618](https://example.com/builders#/task/1618)) → scope build (task [#1619](https://example.com/builders#/task/1619)) → hardware (task [#1620](https://example.com/builders#/task/1620)) → software use. The cost read-out (task [#1621](https://example.com/builders#/task/1621)) is an independent prerequisite input. A full done-when criterion + build task tree gets seeded at the build phase (likely via `/planning-session`).
+
+### Open questions (deferred to the build phase)
+
+- **Warehouse realities** (internet class, static IP, upload bandwidth, ISP terms on servers, power/cooling/space, on-site hands) — Lars to confirm; they gate the hardware spec (task [#1620](https://example.com/builders#/task/1620)).
+- GPU / VRAM class, and whether one card serves both inference and training.
+- Tunnel technology + secret handling for the box (it must never hold a credential that can land code).
+- Final module key (`hosting` vs `compute`) and whether storage is a separate module.

package/docs/adr/0093-tranche-2-core-carve-sequence.md

@@ -0,0 +1,72 @@
+# ADR 0093 — Tranche-2 core-carve sequence (Config-B, completing C7)
+
+**Status:** Accepted (2026-06-27) · task [#1627](https://example.com/builders#/task/1627) (BV1.R76) · criterion **C7 `gds-core-modularized`** (BONGOS-V1) · owner-greenlit
+
+**Amends:** [ADR 0091](<redacted>.md) — which carved the first two core domains (memory R72, grading R73) and **explicitly deferred tranche 2 "per owner."** The owner greenlit tranche 2 on 2026-06-27. This ADR fixes the order, the remaining kernel ports, and the lifecycle endgame; it changes nothing about 0091's kernel roster, the carve mechanism, or the fitness ratchet — those ship as reusable infrastructure.
+
+**Builds on:** [ADR 0083](<redacted>.md) (the strangler plan + 5 module rules), [02 module-map](../design/modular-architecture/02-module-map.md) (the import-graph evidence + the decided ~16-module roster), [04 module-lifecycle](../design/modular-architecture/04-module-lifecycle.md) (the seam/port mechanism).
+
+---
+
+## Context
+
+Tranche 1 ([ADR 0091](<redacted>.md)) did two things: it **proved the core-carve pattern** on the two cleanest-slicing domains (memory, grading — demonstrated by [`scripts/gds/coreB-carve-proof.sh`](../../scripts/gds/coreB-carve-proof.sh), R74), and it **shipped the infrastructure** every later carve reuses — the bounded kernel roster + `KERNEL_FILES` fitness ratchet (R70), the doorway with `withTx` (R68), the per-domain `db.js` slice pattern + `db-kernel.js` (R69), and the `grade` kernel **port** (R73). That infrastructure is generic: each remaining core domain is now a *pure carve* copying R72/R73, with **no new scaffolding**.
+
+What remains is the bulk of the core: ~8 cohesive domains + the two web UIs + the lifecycle state machine ([02 §6](../design/modular-architecture/02-module-map.md) roster). The import-graph scan ([02 §2](../design/modular-architecture/02-module-map.md)) already told us which slice cleanly (economy, ideas, security alongside the proven memory/grading) and which is the coupled cluster (the lifecycle — `tasks → grader/github-push/ship-broadcast`). This ADR turns that evidence into a sequence.
+
+---
+
+## Decision
+
+### 1. Carve order — clean-slicing-first, lifecycle last
+
+Per [02 §2](../design/modular-architecture/02-module-map.md) (import-graph, not intuition) and §68 ("peel the clean, scan-confirmed modules off one at a time, most self-contained first"):
+
+| Task | Carve | ≈LOC | Why this slot |
+|---|---|---:|---|
+| **R77** | economy (credits·cost·streak·achievements·leaderboard) | ~1.0k | clean slice; **also registers the `reward` port** — the lifecycle's last extractable capability (see §2), so it must precede lifecycle |
+| **R78** | ideas (inbox·capture·triage·blockers) | ~0.9k | clean, self-contained |
+| **R79** | security (red-team·bounty, rank-gated) | ~1.0k | clean feature slice ([02 §5](../design/modular-architecture/02-module-map.md): security-the-*feature*, not security-the-property) |
+| **R80** | builder-settings (prefs·builder-needs) | ~1.6k | `me`/`public` stay as thin read facades |
+| **R81** | onboarding (admission·setup·newcomer) | ~1.9k | |
+| **R82** | sessions/BFG (records·cost/eval/digest·corpus) | ~2k | |
+| **R83** | autonomy/MAS (conductor·architect·autonomy-gate·routines) | ~1.5k | cross-cutting — carve seams carefully |
+| **R84** | status-UI (`public-status`) | ~3k | web surface; big but mechanical |
+| **R85** | hall-UI (`public-builders`) | ~13k | largest; mechanical |
+| **R86** | lifecycle (tasks·claims·versions·ship) | ~9k | **last + delicate** — the coupled state machine |
+| **R87** | proof: extend `coreB-carve-proof.sh` to all domains → **C7 satisfied** | — | the criterion's final hinge |
+
+### 2. economy registers the `reward` kernel port — the twin of `grade`
+
+The lifecycle invokes two domain capabilities at ship: **grade** (already a port, R73) and **reward** (credit allocation — `applyGrade`/credit-log). [02 §3/§4](../design/modular-architecture/02-module-map.md) and the [04 lifecycle](../design/modular-architecture/04-module-lifecycle.md) seam design both name `reward` as the second illustrative port. R77 makes it real: economy `registerProvider('reward', …)` at boot; the lifecycle resolves `seams.resolveOptional('reward')` instead of importing economy. This is why **economy is first and lifecycle is last** — by the time the state machine is carved, every capability it calls is already a kernel port, so the lifecycle module imports only the kernel + resolves ports (the [ADR 0091 §4](<redacted>.md) rule, applied to the whole cluster).
+
+### 3. The lifecycle stays ONE module, carved last
+
+Do **not** split tasks/claims/versions/ship apart ([02 §4](../design/modular-architecture/02-module-map.md), restated in [ADR 0091](<redacted>.md) alternatives). Keep the state machine whole; the only edges it keeps are kernel + the grade/reward ports. Carving it last means the `db.js` residue at the end is exactly the lifecycle slice + `db-kernel.js` — the shape ADR 0091 §2 predicted.
+
+### 4. Every carve is proof-gated; C7 is satisfied by R87
+
+Each carve ships only when behavior is byte-identical — `coreB-carve-proof.sh` extended to assert the new module + its slice + its tests. Risk stays **per-domain**, never a big-bang. C7 (`gds-core-modularized`) is satisfied when R87 proves the whole core is decomposed — not before. Tranche 1 proved the *pattern*; tranche 2 completes the *decomposition* the criterion's done-when actually demands.
+
+### 5. The "temporary doorway leaks" retire as their domains carve
+
+ADR 0091 §3 parked three honest leaks on the doorway (`createTask`, `captureIdea`, `VOTABLE_TASK_STATUSES`) because their owning domains weren't carved. They retire here: `captureIdea` → behind an `ideas.*` seam at R78; `createTask`/`VOTABLE_TASK_STATUSES` → behind a `lifecycle.*` seam at R86. Each carve deletes its leak.
+
+---
+
+## Consequences
+
+**Positive.** The core becomes the ~16-module + kernel roster ([02 §6](../design/modular-architecture/02-module-map.md)); `db.js` shrinks to the lifecycle slice + `db-kernel.js`. A "work on X" task loads module X + the doorway, not a 6k-LOC monolith — the AI-scoping payoff, now realized for the whole core, not just two domains. All doorway leaks retire.
+
+**Negative / cost.** ~10 carves, each a focused session (low-hundreds of dollars total, negligible vs the budget). The lifecycle carve (R86) is delicate — it's the most coupled file cluster; it's last precisely so the ground under it (ports for grade + reward) is solid first. Kernel-trust-surface touches (`module-api.js`, `fitness.js`) on the economy/lifecycle carves mean owner Gate approval on those PRs — the boundary working as designed.
+
+**Neutral.** Single-package / single-process / no-bundler preserved. The ~16 roster is a ceiling, not a floor ([02 §6](../design/modular-architecture/02-module-map.md)) — merging two modules is cheap and the fitness ratchet makes a later split safe, so the first cut is not a lock-in.
+
+---
+
+## Alternatives considered
+
+- **A new criterion for tranche 2 — rejected.** C7's done-when already demands "the GDS core is *itself* decomposed … not just the four feature modules." Tranche 2 *is* C7; a second criterion would split one decision across two rows.
+- **Carve the lifecycle earlier — rejected.** Its capabilities (`reward`) aren't ports until economy is a module; carving the state machine while it still `require`s economy would either break the kernel-only rule or bloat the kernel. Sequence the ports first.
+- **Config C (a module per route-group) — rejected** ([02 §3](../design/modular-architecture/02-module-map.md)). tasks/claims/versions/credits are one cohesive cluster; forcing them apart fights cohesion and sprawls manifests. Extract capabilities behind seams; keep the machine.
+- **Carve all domains in one session — rejected (owner).** Per-domain proof gates keep the blast radius bounded; back-to-back unreviewed carves of a 6k-LOC monolith is exactly the big-bang the strangler avoids.

package/docs/adr/0094-repo-atlas-self-drawing-codebase-map.md

@@ -0,0 +1,49 @@
+# ADR 0094 — Repo Atlas: a self-drawing map of the codebase
+
+**Status:** Accepted (2026-06-27)
+**Track:** internal
+**Builds on:** [ADR 0061](<redacted>.md) (context layers), [ADR 0063](<redacted>.md) (generate-don't-narrate), [ADR 0062 §8](<redacted>.md) (generated artifacts), [ADR 0083](<redacted>.md) / [ADR 0091](<redacted>.md) (module system), [ADR 0056](<redacted>.md) (hand-installed deploy script), the world-snapshot precedent (`scripts/snapshots/maybe-render-on-deploy.sh`).
+**Promotes:** [idea #457](https://example.com/builders#/idea/457). **Tasks:** [#1640](https://example.com/builders#/task/1640) (this), [#1641](https://example.com/builders#/task/1641) (doc-generator migration).
+
+## Context
+
+[Idea #457](https://example.com/builders#/idea/457) (owner, from Discord): *"A visual and navigable map which allows a non-technical and technical user to understand the codebase of their project and the modules that make it up. Starting with Cloud Bongos, this map should be generated directly off of the code so it also clearly shows what is spaghetti and what is well structured."*
+
+The owner's framing in session: the single most important thing to make legible is **how `.md` files are positioned and how context is managed** in the repo; and, for the module system, to see **the TRUTH — exactly how modules are separated as files and function calls**, not the aspirational doc version. Visual reference: Langfuse's hover-connective boxes, in an isometric (but less-slanted, more-readable) layout, in the Cloud Bongos art style.
+
+Two pre-existing facts shape the design:
+- The repo already runs a **"generate self-knowledge on deploy"** pipeline (`gen-repo-map`, `gen-diagrams`, `gen-session-index`, `gen-file-map`) — but those run on the **shipping builder's machine** during `/builder-ship` and are committed into the PR. The owner explicitly wants the **server** to do this regeneration, not the local instance.
+- The world-snapshot renderer already regenerates an artifact **server-side on the droplet at deploy**, writes it to a served directory, and never commits it. That is the exact shape this needs.
+
+## Decision
+
+Build the **Repo Atlas**: a Builders' Hall page rendering an isometric, hover-connective, click-for-detail map of the repository, in **two views over one engine**:
+
+1. **Context Layer** — the always-loaded root `CLAUDE.md` (with its live line/char budget gauge) vs the on-demand nested guides, the docs library (ADRs / recipes / audits / session logs, real counts), the database as live-state (never a file), the self-generating artifacts, and broken-link **drift**.
+2. **Module Truth** — the real modules carved into `modules/<key>/` (clean boundary, green) vs the `src/bongos` **core blob** (with `db.js` the monolith, red) vs the planned-but-still-fused **ghosts** (the `module-scope-map` roster with no `modules/<key>/` dir yet). Edges are real dependency + boundary facts; a module flips to a violation colour if a require reaches a sibling or deep core.
+
+**Data pipeline (the load-bearing decision):**
+- A single generator, `scripts/gds/gen-atlas.js`, emits `public-builders/atlas.json`. It is **pure file-reads — no network, no GDS session** — so it runs headless on the droplet.
+- It **reuses the existing truth sources** rather than re-deriving them: `src/bongos/module-scope-map.js` (the MOVED-vs-FUSED roster), `scripts/gds/fitness.js --json` (the kernel-leak count + the boundary rule it applies), `scripts/gds/docs-entropy.js --json` (the stale-link count), the `CLAUDE.md` budget constants, and real `readdir`/LOC counts. The map can't disagree with the gates because it reads the same facts they do.
+- **Regeneration is SERVER-SIDE on every deploy**: a non-blocking step in `scripts/deploy/deploy-prod.sh` runs the generator and writes `atlas.json` into the served dir — copying the world-snapshot precedent exactly. Because prod auto-deploys on every merge to `main`, **every ship → fresh map**, regardless of who shipped or from what machine.
+- `atlas.json` is a **gitignored build artifact** — never committed, never hand-edited (so it can't drift), and not subject to a CI freshness gate. The page degrades gracefully (a "being drawn" notice) when it is absent.
+
+**Page:** a vanilla `public-builders/atlas.html` + `atlas.js` (no framework, the hall convention), **self-contained Cloud Bongos styling** (its own `--ab-*` tokens so the instance's injected theme never recolours it), auto-laid-out (ring-by-group seed + a relaxation pass so **no two islands touch**, the owner's requirement), hover lights an island's links, **click opens a popup** with that file/module's detail. Gated to **any signed-in builder** (`serve-internal.js`). Built to port to Cloud Bongos.
+
+## Consequences
+
+- **The existing doc generators should migrate to the same server-side trigger** (the owner's "do the same for documentation" ask) — task [#1641](https://example.com/builders#/task/1641). `gen-repo-map` / `gen-session-index` / `gen-file-map` are pure file-reads and move cleanly **once their `fitness.js` `--check` freshness gate is retired and the outputs are gitignored** (otherwise every PR fails the staleness check). **`gen-diagrams` is the exception** — it needs a headless browser (the droplet has none) and an authenticated GDS session for its conceptual slices, so it does NOT migrate cleanly; documented, left as-is.
+- **One-time operator step:** `scripts/deploy/deploy-prod.sh` is the hand-installed mirror of the droplet's `~/deploy.sh` (ADR 0056) — the new step goes live only when an operator `scp`s the updated script to the droplet. Until then prod shows the "being drawn" notice.
+- `atlas.json` is **public static** (non-sensitive repo-structure facts; the repo gains a public mirror per V4.R71 anyway). It can move behind an authenticated route later if a future instance needs it.
+- The map **surfaces drift and spaghetti honestly** — the live stale-link count, the kernel leaks, the 26k-line blob, the `db.js` monolith, the ghosts — which is the point of [#457](https://example.com/builders#/task/457), not a blemish to hide.
+
+## Amendment (2026-07-03 — task 1737)
+
+The "self-contained Cloud Bongos styling" clause is narrowed after the hall redesign (task 1723): the page **chrome** (card, view toggle, caption, legend, popup, badges) now rides the hall's design-token system, so it follows the instance pack and dark mode like every other hall page. What remains isolated — the actual invariant — is the **semantic node/edge palette**: it stays a fixed set (never pack-driven) so an instance's colors can never scramble the map's color-coded meaning. Non-semantic scene values (label ink/halo, ambient wash, hub glow, badge fills) are scoped `--ab-*` vars with dark variants that the renderer reads at draw time and re-reads on `html[data-theme]` flips.
+
+## Alternatives considered
+
+- **A live `/api/gds/*` endpoint** computing the graph per request — rejected: the file structure only changes at deploy, so a live route would repeatedly query disk/DB to serve data that never changes between deploys. Build-time static JSON is the right tool (the same reasoning that keeps the world snapshots static).
+- **A committed generated file** (like today's repo-map) — rejected: it reintroduces the builder-machine dependency the owner is explicitly removing, and a committed-but-server-regenerated file goes stale between the commit and the next deploy.
+- **Extending the Mermaid diagram pipeline** (`gen-diagrams`) — rejected: those diagrams are conceptual (lifecycle, ranks), not structural, and rendering them needs a headless browser the droplet lacks.
+- **A flat force-directed node-graph or a treemap** — rejected for the audience: a force graph tends to a hairball, a treemap hides connections. The isometric "islands + flight-paths" reads for a non-technical builder and matches the owner's Langfuse reference and the Cloud Bongos (sky-whale) brand.

package/docs/adr/0095-borrowed-memory-and-retrieval-concepts.md

@@ -0,0 +1,65 @@
+# ADR 0095 — Borrowed memory, retrieval & collision concepts from claude-mem and graphify
+
+**Status:** Proposed (owner-directed 2026-06-27; pending claim + companion ADR)
+**Track:** internal
+**Builds on:** [ADR 0060](0060-gds-retrieval-layer.md) (recall / retrieval layer), [ADR 0063](<redacted>.md) (generated repo-map symbol skeleton), [ADR 0094](<redacted>.md) (repo atlas), [ADR 0049](<redacted>.md) (touches[] advisory), [ADR 0082](<redacted>.md) (server-side conflict resolver), [ADR 0091](<redacted>.md) (memory module carve), [ADR 0026](<redacted>.md) / [ADR 0027](<redacted>.md) (BFG memory).
+**Pairs with:** a companion owner-authored ADR on **grep vs. a semantic/embedding retrieval layer**. This ADR deliberately does **not** decide that question — every item below is independent of which retrieval mechanism we run.
+**Sources evaluated:** [graphify](https://github.com/safishamsi/graphify) (MIT, Python) and [claude-mem](https://github.com/thedotmack/claude-mem) (Apache-2.0, JavaScript), in the 2026-06-27 research session.
+
+## Context
+
+We evaluated two mature, widely-starred Claude-Code tools that overlap our internal stack:
+
+- **graphify** — turns a codebase + docs into a queryable knowledge graph (tree-sitter AST + LLM-inferred edges + Leiden clustering), shipped as a `/graphify` skill + MCP server.
+- **claude-mem** — automatic persistent session memory (lifecycle hooks capture every tool use → AI-compressed summaries → reinjected next session), backed by SQLite + a Chroma vector DB.
+
+Both overlap things we already run — recall ([ADR 0060](0060-gds-retrieval-layer.md)), the generated repo-map ([ADR 0063](<redacted>.md)) and the repo atlas ([ADR 0094](<redacted>.md)), the carved memory module ([ADR 0091](<redacted>.md)), the `learnings` table, and `touches[]`/merge-collision handling ([ADR 0049](<redacted>.md), [ADR 0082](<redacted>.md)).
+
+**Neither fits wholesale**, for reasons specific to us:
+- graphify is **Python** — a foreign runtime bolted beside a Node/Postgres codebase; it could only ever sit *next to* the GDS, never inside it.
+- claude-mem's architecture is **local-first, single-developer** (a per-machine daemon + local SQLite + a Chroma vector service pulling in a Python/`uv` dependency). We are **centralized and multi-builder** (memory syncs to one Postgres on the droplet, rank-scoped, with the BFG doing cross-builder work). The shape is wrong.
+- graphify's graph has **no rank-scoping**; committing a full-repo graph would expose permission-core structure to low-rank builders, against [ADR 0016](<redacted>.md).
+- Both run an **open-core commercial play** (graphify → Penpax; claude-mem → a server/team beta), and claude-mem additionally endorses an associated **memecoin** — governance signals that argue against *depending* on either, though not against reading them.
+- Claude Code itself deliberately favours **live agentic search over a prebuilt index** (freshness, simplicity) — the philosophy we already follow with lexical recall + a generated map.
+
+But several *concepts* in these tools are stack-agnostic, cheap, and land on real gaps. This ADR records **which concepts we adopt and why**, and **what we decline**. The unifying principle: **borrow concepts, not tools** — reimplement in our own Node/Postgres stack, import no third-party code, add no new service, and stay inside the budget and the trust boundary.
+
+## Decision
+
+Adopt the following eight concepts. Each is reimplemented in-stack; none requires a new dependency or service (the one exception — a parser for the AST work — is called out in G2).
+
+### From graphify (the "Tier-2" borrows)
+
+- **G1 — Symbol-level collision detection.** Move `touches[]` overlap from *path-prefix* to *symbol/dependency* awareness (`src/bongos/path-match.js` `touchesOverlap`/`matchOne`, consumed by `claims.js`). **Why:** path-prefix over-flags — two tasks editing different functions in one big file (e.g. `db.js`) are falsely serialized, costing parallelism — and under-detects, missing cross-file collisions where one task changes a symbol another file depends on. [ADR 0049](<redacted>.md) already cut the *cost of being wrong* (touches is advisory, backfilled from the real diff); this attacks the *accuracy of the forecast*, the remaining lever. `git merge` stays the ground-truth backstop.
+- **G2 — AST-based repo-map upgrade.** Replace the regex symbol extractor with a real parser via the `extractFile()` seam [ADR 0063](<redacted>.md) explicitly left for this (`scripts/gds/gen-repo-map.js`). **Why:** the regex extractor is server-JS-only, conflates two symbols that share a name, and builds no call graph. A parser (tree-sitter, **WASM build** — which sidesteps the `node-gyp` native-compile cost that [ADR 0063](<redacted>.md) rejected) gives polyglot coverage (the Python `art/` pipeline, client `public/game/` JS, SQL), real symbol resolution, and a dependency graph. That graph is the **substrate G1 needs**, and it feeds [ADR 0094](<redacted>.md)'s atlas **truer edges** than today's `fitness.js` regex-on-`require` facts. This is the one item with a (vendored, no-native-build) dependency cost; accepted for the payoff.
+- **G3 — Surface the "why," forward-facing.** Extract design rationale (`# WHY:`/`# HACK:`/docstrings + ADR rationale) and attach it to the code it explains, surfaced *at the moment of work* rather than left in an archive. **Why:** we already *pay* to capture "why" (the ADR culture, the `# WHY:` convention) — but capture ≠ surfacing, and our builders are memoryless AI agents with a strong instinct to "tidy" load-bearing code, re-breaking solved problems (the fences in our own learnings/memory log). Cheap first cut: feed `# WHY:` + ADR rationale into the recall index; later, auto-inject the governing ADR when an agent opens a file it covers.
+
+### From claude-mem (concepts 1–5)
+
+- **C1 — Progressive-disclosure retrieval with token-cost visibility.** Layer recall into *cheap index → batch detail*: return a compact index first (IDs + titles, ~tens of tokens each), then fetch full bodies only for the few the agent selects (`modules/memory/routes/search.js`, `scripts/gds/recall.js`, the recall skill). **Why:** recall returns a flat list of snippets today; layering it yields ~10× fewer tokens per query (claude-mem's documented figure), which compounds across every session and serves the $5K / token-frugal posture directly. **Independent of grep-vs-semantic** — it's a presentation/cost pattern over whatever retrieval leg(s) the companion ADR chooses.
+- **C2 — Hook graceful-degradation policy.** Codify one rule across the hook fleet (`.claude/hooks/*`, memory-sync in `ship.js`, the Conductor): an **infrastructure** failure (ECONNREFUSED / timeout / 5xx) → **exit 0, never block** the builder; a **code bug** (4xx / TypeError) → **exit 2, block** so it's fixed. **Why:** we run many hooks; a droplet hiccup must never freeze a session mid-work. (The unreachable-API condition encountered while authoring this very ADR is the canonical example.)
+- **C3 — Memory-usefulness feedback loop.** Record whether a recalled chunk / learning was actually used, and let that signal drive ranking and decay (`modules/memory`, `learnings`). **Why:** nothing today tracks whether recalled knowledge helped; a usefulness signal lets high-value memory rise and dead weight fade, keeping the corpus high-signal as it grows. Pairs naturally with graphify's `save-result` (useful / dead_end / corrected).
+- **C4 — `<private>` content-exclusion marker.** A tag an agent can wrap around sensitive content so it never enters the memory store (`modules/memory` ingest; complements the BFG transcript scrub). **Why:** a simple, explicit opt-out that reinforces the trust boundary ([ADR 0016](<redacted>.md)) — secrets, permission-core internals, sub-Metic-sensitive material fenced out at the source.
+- **C5 — Windowed content-hash dedup.** On write, hash `(session + title + body)` and, if the same hash reappears within a short window, reuse the existing row instead of inserting (`modules/memory`, `learnings.js`). **Why:** stops near-duplicate memory/learning entries; complements the existing `source_ref` soft-idempotency.
+
+## What we decline (and why)
+
+- **Adopting either tool wholesale** — stack/architecture/trust mismatch (see Context).
+- **Lifting graphify's Python code** — foreign runtime; borrow patterns, not source.
+- **claude-mem's local-daemon + SQLite + Chroma architecture** — wrong shape for a centralized, multi-builder, Postgres server.
+- **The Chroma / `uv` vector dependency** — exactly the dependency weight we deferred embeddings to avoid. *If* we ever add semantic retrieval, it is `pgvector` inside the existing Postgres — but **that decision belongs to the companion grep-vs-semantic ADR**, not here.
+- **Automatic capture of every session** (claude-mem's default) — continuous token cost + noise risk; our deliberate capture is cheaper and higher-signal. Folded in only as auto-*suggestion*: the BFG may *propose* memory/learning entries for confirmation, never auto-commit.
+- **Headline star counts as evidence** — treated as marketing signal; these choices weigh maturity, license, and fit, not stars.
+
+## Consequences
+
+- **Positive.** Sharper parallelism + fewer surprise merge conflicts (G1); a polyglot, symbol-accurate map that also strengthens the atlas (G2); load-bearing rationale that stops agents re-breaking fences (G3); cheaper recall per query (C1); hooks that never freeze a session (C2); a self-cleaning, higher-signal memory corpus (C3–C5). All in-stack, no new service.
+- **Cost.** Eight follow-on tasks of varied size; G2 is the heaviest (a vendored WASM parser + reworking `gen-repo-map.js`). All modest against the budget. Each ships under its own claim and gate.
+- **Neutral / boundary.** Nothing here changes the retrieval *mechanism* (grep vs. semantic) — that is the companion ADR's call, and C1/G3 are written to compose with whatever it decides. Single-process / single-package / no-new-daemon preserved.
+
+## Alternatives considered
+
+- **Adopt graphify and/or claude-mem wholesale** — rejected: stack mismatch, dependency weight, no rank-scoping (graphify), local-first single-dev architecture (claude-mem), and open-core/memecoin governance risk. Reading them is valuable; depending on them is not.
+- **Do nothing (status quo)** — rejected: the gaps (false-serializing collisions, JS-only map, archived-not-surfaced "why," flat full-cost recall) are real and recurring; these borrows are cheap relative to the pain.
+- **Bundle the semantic-retrieval decision into this ADR** — rejected: the owner is authoring it separately; keeping the retrieval-mechanism choice in one place avoids splitting it across two records, and every item here is deliberately mechanism-agnostic.
+- **One ADR per concept** — rejected: these eight share one rationale (borrow-concepts-not-tools, from one evaluation); a single record keeps that reasoning together. Each still gets its own implementing task.

package/docs/adr/0095-cross-agent-context-management.md

@@ -0,0 +1,58 @@
+# 0095 — Cross-agent context management: adopt docstrings now, defer the portability layer
+
+- **Status:** Accepted
+- **Date:** 2026-06-27
+- **Deciders:** Lars (owner) · Claude (Opus 4.8)
+- **Track:** `internal` (Cloud Bongos / context + retrieval)
+- **Relates to:** [ADR 0083](<redacted>.md) / [ADR 0091](<redacted>.md) — the modular decomposition is the *structural* half of low-context AI navigation; this ADR is the *findability* half (see Context). Also [ADR 0094](<redacted>.md) (the codebase map), [ADR 0061](<redacted>.md) / [ADR 0063](<redacted>.md) (the context layers it feeds). Companion: [ADR 0095-a](<redacted>.md) — adopts the memory/retrieval *concepts* and explicitly defers the grep-vs-semantic decision to this ADR (the two collided on `0095` in parallel; see the index note).
+
+## Context
+
+Cloud Bongos is an AI-first build platform, and today its agent-facing surface is shaped almost entirely for one tool — Claude Code: the always-loaded root `CLAUDE.md` ([ADR 0061](<redacted>.md)), the `.claude/` skills + hooks, a lexical-first retrieval layer ([ADR 0060](0060-gds-retrieval-layer.md)), and a generated repo-map ([ADR 0063](<redacted>.md)). The owner wants Cloud Bongos instances to be editable across many agentic coding tools (Claude Code, OpenAI Codex, Cursor, …). That raises two questions a future version must answer:
+
+1. **Retrieval** — how do we make a repo navigable by tools that find code by literal text search ("grep"), and is a meaning-based ("semantic") retrieval layer worth its recurring cost and index-drift?
+2. **Portability** — how should the agent-facing contract (instructions, commands, enforcement, capabilities) be structured so it isn't hardwired to one tool?
+
+We did extensive research (two parallel passes, ~50 sources) to inform both. This ADR records the findings as durable framing, but the owner has deliberately scoped the *committed* decision narrow: **adopt docstrings now; everything else is captured as deferred future-decision content, not a commitment.**
+
+The durable findings:
+
+- **Agents navigate by grep, not embeddings.** Claude Code, Codex, and Cursor all default to literal search (generate query → grep → read → iterate). Anthropic and Sourcegraph both *removed* embedding indexes from their code tools (precision on exact identifiers, freshness/anti-staleness, privacy, cost); Cursor keeps embeddings but only *alongside* grep and fights staleness with incremental Merkle-tree re-indexing. So a literal-search-friendly repo is the high-leverage, low-cost target.
+- **Greppability is mostly free, write-time discipline that doesn't rot:** distinctive (not generic) names, "the Grep Test" (never construct or dispatch identifiers dynamically), one concept = one name (don't re-case across boundaries), unique whole log/error strings, flat namespaces. Generic identifiers are the single biggest documented retrieval-killer for agents.
+- **The best "semantic layer" is meaning written into the source.** Docstrings, module headers, READMEs, and ADRs co-locate concept words with the symbol — which helps grep, agentic search, *and* any future embedding, at zero recurring cost and zero index-drift (the "index" is the version-controlled text). OTB already has the structural half (the generated repo-map with a CI freshness gate) and the ADR/README half; the missing piece is per-symbol/per-module docstrings + consistent concept vocabulary.
+- **Cross-tool portability is an adapter problem** — one canonical source per concern + thin per-tool adapters: instructions → an `AGENTS.md`-style canonical file with thin per-tool pointers; commands → plain CLI (already true — slash-commands wrap `scripts/gds/*.js`); enforcement → server/git/CI, never tool hooks (already true — the trust boundary, [ADR 0016](<redacted>.md)); capabilities → MCP (already cross-tool). This is the [ADR 0062](<redacted>.md) / [0081](<redacted>.md) core↔host / swappable-adapter pattern applied to the agent surface.
+- **The Cloud Bongos shape:** *how a repo is managed for agents* becomes a project-init **profile** that provisions the right adapter set (which context files, which command wrappers, which retrieval posture, which enforcement). It is a start-of-project decision because naming conventions and whether to stand up an embedding pipeline are expensive to retrofit.
+
+**Relationship to the modular decomposition ([ADR 0083](<redacted>.md) / [ADR 0091](<redacted>.md)).** These were authored alongside this ADR and are the *other half* of the same goal — an AI agent that navigates the codebase at low context cost. The decomposition bounds *how much* an agent must load: a domain becomes a module reached through one doorway, not a 6k-LOC monolith (0091's explicit "AI-scoping payoff"). This ADR is the complementary *findability* layer — meaning written into the source so the agent locates the right module/symbol by search. They compose directly: **the module-header doc-comments decided here are authored per module precisely because 0091 makes the module the unit of scoping**, and each sits beside that module's nested `CLAUDE.md` and the generated repo-map ([ADR 0063](<redacted>.md)). The deferred `AGENTS.md` adapter + per-project agent profile are likewise the agent-surface counterpart to 0091's core↔module boundaries.
+
+## Decision
+
+**We will adopt docstrings and module-header doc-comments as a project convention.** This is the one change ratified here.
+
+- Every public function/class and each module gets a short natural-language doc-comment describing *what it does and why it exists* (not how), using the concept words a human would search for and naming key collaborating symbols.
+- Rationale: this is the zero-recurring-cost, zero-index-drift core of semantic findability. Meaning lives in the version-controlled source, so it helps literal/grep search, agentic search, and any future embedding alike — with no separate index to pay for or keep fresh.
+- It is a *convention*, rolled out incrementally (new + touched code adopts it by default; high-traffic modules backfilled opportunistically), not a big-bang backfill. Follow-on task [#1654](https://example.com/builders#/task/1654) tracks wiring it into the conventions guidance and an initial backfill; whether to add a non-blocking lint/fitness nudge is left to that task (not ship-blocking without owner sign-off).
+
+Everything else from the research is recorded below as **deferred** — explicitly *not* decided here.
+
+## Alternatives considered
+
+*Per the owner's scope, these are live options for a future planning session, not rejected ones. Captured so the research isn't re-done.*
+
+- **Stand up a semantic / embedding retrieval layer now.** Deferred. Embeddings earn their keep mainly on large codebases / pure concept-queries and carry recurring cost + index-drift; the leading tools dropped them or only augment grep with them. If ever pursued: local embedding model + embedded store (e.g. sqlite-vec) + incremental, content-hash, git-hook re-indexing, run *alongside* grep (hybrid), never instead. ([ADR 0060](0060-gds-retrieval-layer.md) already deferred embeddings behind a measured gate — this corroborates it.)
+- **Adopt an `AGENTS.md` cross-tool adapter layer** (one canonical instructions file + thin `CLAUDE.md` / `.cursor/rules` / `copilot-instructions` pointers, generated from a single source). Deferred — likely the highest-value *next* step, but a design decision in its own right (canonical-vs-adapter split; import vs symlink vs generator).
+- **Adopt explicit greppability conventions** (distinctive names, the Grep Test, flat namespaces, unique log strings) as a written, possibly lint-enforced standard. Deferred — strong candidate; pairs naturally with the AGENTS.md work.
+- **Adopt an `AIDEV-NOTE:` anchor-comment convention** (greppable inline notes for landmines and the "why"), guarded by a density / overdue fitness check so it can't rot. Deferred — high agent payoff, but it is *planted maintenance debt* and is only safe with the CI guard, so it needs deliberate design.
+- **Make a "retrieval & agent profile" a Cloud Bongos init setting** that deploys a different set of agents / skills / context-files / enforcement per project. Deferred — the owner flagged this as a serious, start-of-project-level platform decision; needs its own scoping.
+
+## Consequences
+
+- **Now:** a low-cost convention that improves human readability, grep/agentic retrieval, and any future semantic layer simultaneously — no infra, no drift. The cost is authoring discipline; a stale doc-comment can mislead, mitigated by the same "update the comment when you change the code" rule we already apply to anchors.
+- **Preserved:** the research and the five deferred options are recorded here so a future GDS-V4 / Cloud Bongos planning session starts from them instead of re-researching. This ADR is framing + one decision; it deliberately does **not** commit the platform to the adapter layer, embeddings, or the per-project profile.
+- **Follow-on:** task [#1654](https://example.com/builders#/task/1654) (docstring rollout). The deferred items remain unticketed by design until the owner chooses to scope them.
+
+## C4 — `<private>` content-exclusion marker (shipped, task [#1661](https://example.com/builders#/task/1661))
+
+An agent can wrap sensitive content in a `<private>…</private>` fence so it **never** enters the memory/learning store nor the recall index — the explicit, write-time opt-out that reinforces the trust boundary ([ADR 0016](<redacted>.md)) and complements the BFG transcript scrub: secrets, permission-core internals, and sub-Metic-sensitive material fenced out *at the source*.
+
+Implementation (all in `modules/memory`): a pure `stripPrivate()` in `search-chunker.js` removes every `<private>…</private>` region and is applied at **every** ingest/persist entry point — `storeMemoryFile`, `storeMemoryFilesBatch`, and the BFG cross-builder `bfgWriteMemoryFile` in `memory.js`; `createLearning` in `learnings.js` (title + body); and `chunkMarkdown` (the recall index) itself. The match is **case-insensitive and whitespace-tolerant** (`<private>`, `<PRIVATE>`, `< private >`) and **fail-closed**: an unbalanced `<private>` with no matching close strips to end-of-content, so a half-typed marker can't leak the secret it was meant to hide. A learning whose entire body is fenced strips to empty and is rejected like any other empty body.