@bongos/core 1.17.0

package/docs/design/modular-architecture/01-architecture.md

@@ -0,0 +1,125 @@
+# A Concrete Modular Architecture — and the safest way to get there
+
+Built on the research ([00](00-research-report.md)). Plain language, decision-oriented.
+
+## 1. The reframe: one decision treated as four
+
+"How modular is the code" is a **separate question** from "how many packages" and "how many processes." They feel like one decision; they are four independent axes. Becoming modular means moving **only the first**.
+
+| Axis | Today | Move? | Why |
+|---|---|---|---|
+| **Modularity** (how code is organized inside) | one fused blob | **→ go fully modular** | this is the goal |
+| **Packaging** (npm package boundaries) | one `package.json` | **stay** | many packages buy dep-trees + caching, *not* modularity; cost a build/link step |
+| **Runtime** (deployment) | one Node process | **stay** | a process-per-module is a scaling/sandbox choice; ADR 0080 defers sandboxing |
+| **Build** (bundler) | none (raw files) | **stay** | pure cost for a $5k project; `start` is just `node server.js` |
+
+> **The one-sentence version:** modularity is delivered by **boundaries + a loader + a contract** — not by multiplying packages or processes. VS Code, Backstage, and Fastify are deeply modular and run as a single process. Each "stay" has a clean future fork (marketplace → packages; untrusted modules → processes; a UI needing a build → that module owns its build), all of which ADR 0080 already defers — so you change nothing you'd later regret.
+
+## 2. The confusing parts, in plain terms (shipping containers)
+
+"Manifest" is literally a shipping term — the cargo list a ship carries.
+
+| Jargon | Plain meaning | Shipping picture |
+|---|---|---|
+| Module / package | a self-contained folder with everything one feature needs | a labeled shipping container |
+| Manifest (`module.json`) | a label file saying what's inside + what it needs | the cargo manifest on the door |
+| The kernel | the always-on platform every module relies on (login, ranks, tasks) | the port — cranes, docks, customs |
+| Loader | the part of the kernel that finds containers, checks labels, plugs the enabled ones in | the crane |
+| Boundary / one-way arrow | a module may use the kernel; the kernel never reaches into a module; modules never reach into each other | containers connect only to the dock — never weld two together |
+| Fitness function | an automatic build check that **fails the merge** if a boundary rule is broken | customs at the gate, auto-rejecting a wrongly-loaded truck |
+
+Organizing once is easy; *staying* organized is the hard part — the fitness function is what makes the structure self-enforcing instead of relying on discipline.
+
+## 3. The target architecture
+
+The whole product becomes **core + modules**. A module is a **vertical slice** (its routes, DB tables, screens, agent-context) that reaches the rest of the system through **one published doorway**.
+
+```mermaid
+graph TD
+    subgraph Modules["Modules (each a vertical slice: routes · db · ui · skills · manifest)"]
+        G[game]
+        D[dev-box]
+        DC[discord]
+        Y["your module<br/>(no fork!)"]
+    end
+    API["core/module-api.js<br/>THE published, versioned doorway<br/>(the only thing a module may import)"]
+    subgraph Core["CORE — always on, carries ZERO module-specific code"]
+        L[loader]
+        A[auth + rank ladder]
+        T[tasks · claims · grading · memory]
+        DB[(core db pool + core tables)]
+    end
+    G --> API
+    D --> API
+    DC --> API
+    Y --> API
+    API --> Core
+    Core -.->|"FORBIDDEN: core never imports a module<br/>(fitness check blocks it)"| Modules
+```
+
+**The five rules:** (1) one doorway, one direction — modules import `module-api.js` only; core never imports a module; modules never import each other. (2) The host owns the mount. (3) A module owns a vertical slice. (4) Shared state is namespaced (`<key>_*` tables, additive migrations). (5) A task is scoped to a module.
+
+### 3a. How a module plugs in without picking the lock
+
+The module ships a *recipe* for its routes; the **loader** wraps them behind auth the module can't remove:
+
+```mermaid
+graph LR
+    M["module ships:<br/>route factory<br/>+ 'needs Metic'<br/>(never calls app.use)"] --> Loader
+    subgraph Loader["the loader builds around it"]
+        direction TB
+        A1["① audit log"] --> A2["② requireBuilder"]
+        A2 --> A3["③ requireRank(Metic) — live from DB"]
+        A3 --> A4["④ the module's handler runs here"]
+    end
+```
+
+The module's code only ever runs *inside* gates the core wraps around it; it can't register anything before the auth/rank checks because it never touches the front door. A separate fitness check fails the build if a module route forgets its rank gate. This is **stronger** than how Backstage/VS Code treat first-party plugins (they isolate for stability; Backstage doesn't sandbox at all). Full process-isolation is the deferred future fork.
+
+## 4. What this does to `touches[]` — it retires
+
+In a real modular world, two tasks on **different modules can't collide** — so the file-path `touches[]` array has nothing left to detect.
+
+- Cross-module work → **parallel-safe by construction** (no check needed).
+- Same-module or shared-core → the one zone that needs a check.
+- So the safety question shrinks from "do these file lists overlap?" to "same module? touches core?" — answered by the task's **module label**, not a file array.
+
+"Not passed the code" is about what the agent *sees*; the hard guarantee it can't write elsewhere comes from a **ship-time check that the diff stayed inside the declared module**. Seeing-only + verify-on-ship = real isolation. `touches[]` survives only as a transitional crutch while the code isn't in modules yet.
+
+## 5. Why NOT a ground-up rewrite
+
+```mermaid
+graph LR
+    subgraph RW["Ground-up rewrite"]
+        R1["long dark window — nothing ships —<br/>re-deriving the SAME core (auth, tasks, grading, ~111 migrations)"] --> R2["risky big-bang cutover ⚠"]
+    end
+    subgraph ST["Strangler migration (recommended)"]
+        S1[loader] --> S2[dev-box→module] --> S3["discord · art"] --> S4[game] --> S5["carve core + task→module"] --> S6[theming]
+    end
+```
+
+- A rewrite **re-derives the parts you'd keep anyway** (auth, rank ladder, tasks/claims/credits, grader, ship pipeline, ~111 migrations) — no modularity win in retyping it; the win is *where code lives + enforced boundaries*, which a reorg delivers.
+- The risk profile is upside-down for a bootstrapped, ship-small, AI-first project: a rewrite is a long no-ship window ending in a big-bang cutover.
+- **Rule of thumb: rewrite when the foundation is wrong; reorganize when the foundation is sound but the filing is wrong.** Your foundation (trust boundary, GDS pipeline, grader) is sound; the filing (fused game/core, a 236 KB `db.js`, flat routes, hardcoded brand strings) is wrong. That's a reorg.
+
+## 6. The migration path
+
+Each phase ships independently, guarded by the fitness functions; easiest/most-isolated first, riskiest (game) last.
+
+| # | Phase | What happens in the code |
+|---|---|---|
+| 0 | Draw the doorway | define `core/module-api.js` + teach `fitness.js` the one-way rule (mostly exists) |
+| 1 | Build the loader | discover `modules/*/module.json`, validate, compose routes behind auth, apply module migrations, start/stop pollers |
+| 2 | Move dev-box first | most self-contained + half flag-gated; the template every other move copies; prove OTB behaves identically |
+| 3 | Move discord, then art-pipeline | same recipe |
+| 4 | Move game (the hard one) | Colyseus rooms + world tables + `public/`; "realtime capability" seam |
+| 5 | Carve the core + rewire the task model | split `db.js` per-module; add `task.module`; **retire `touches[]`**; extend fitness to verify diff-in-module |
+| 6 | Finish theming | pull ~90 hardcoded brand strings into `branding.json`; unify the stylesheets; per-module UI sections |
+
+The proof at every step (as in ADR 0062's core/host split): after moving a module, OTB behaves **byte-for-byte the same**.
+
+## 7. What changes, what stays
+
+**Changes (reorganize):** code moves into `modules/<key>/` slices · a real loader replaces hand-wired `if (isModuleEnabled())` lines · `module.json` becomes load-bearing · the 236 KB `db.js` is carved per-module · a task gains a module label; `touches[]` retires · brand strings + stylesheets consolidate.
+
+**Stays (unchanged):** one `package.json` · one Node process (`node server.js`) · no bundler · Postgres, raw ESM client + CJS server · the trust boundary + rank ladder (extended to module routes) · the GDS ship/grade/deploy pipeline.

package/docs/design/modular-architecture/02-module-map.md

@@ -0,0 +1,116 @@
+# Module Map & Slicing
+
+Measured from the tree at `cc8a5e0` (~95k LOC). LOC are approximate — classified by file purpose, some files straddle domains.
+
+## 1. Where the lines of code live
+
+| Area | ≈ LOC | Home |
+|---|---:|---|
+| **KERNEL** — auth · rank · db-pool · loader · audit · trust primitives | ~3,500 | kernel |
+| Hall UI (`modules/hall-ui/public`, was `public-builders`) | ~13,100 | module (hall-UI) — carved BV1.R85 |
+| Ship / publish pipeline | ~5,500 | → lifecycle |
+| Shared data layer (`db.js`) | ~5,300 | carved per-domain |
+| Work lifecycle (tasks·claims·versions) | ~3,800 | → lifecycle |
+| Grading (grader + worker panel) | ~3,100 | module (grading) |
+| Status UI (`public-status`) | ~3,000 | module (status-UI) |
+| Memory · recall · search · learnings | ~2,200 | module (memory) |
+| Onboarding · admission · newcomer | ~1,900 | module (onboarding) |
+| Builder profile · prefs | ~1,600 | module (builder-settings) |
+| Economy (credits·cost·streak·achievements) | ~1,000 | module (economy) |
+| Security · red-team | ~1,000 | module (security) |
+| Inbox · ideas · blockers | ~900 | module (ideas) |
+| Builder CLI (`/builder-*`) | ~12,000 | follows each domain (a command travels with its module as a `skill`) |
+| Seed / generator / ops scripts | ~7,000 | seeds = disposable · generators = kernel/build or per-module |
+| Art pipeline | ~13,000 | feature module |
+| Dev-box (+2,900 Electron, separate) | ~5,400 | feature module |
+| Game | ~3,900 | feature module |
+| Discord | ~2,300 | feature module |
+
+**The reframe:** the four feature modules are only ~26% of the code. The other ~70% is "core" — which is *not one thing*: ~8–10 cohesive domains on a small (~3.5k) trust kernel. The real decision is **how finely to cut the core.**
+
+## 2. Validated against the import graph (not intuition)
+
+Built the `require()` graph across all 111 files in `src/bongos`:
+
+| What the graph shows | Reading |
+|---|---|
+| **In-degree cliff** — auth (35), db (28), pool (24), _helpers (23), then single digits | ✅ kernel is real + small |
+| **Tight, outward-silent clusters** — discord→all `discord-*`; box→box-access/credential; grader→grader-workers | ✅ discord, dev-box, grading, memory, economy, security-feature slice cleanly |
+| **`tasks → grader`, `tasks → github-push`, `tasks → ship-broadcast`** | ❌ work reaches into ship + grading → **one coupled cluster** (see §3) |
+| **`permission-path-check` / `route-rank-check`** imported by grader, tasks, instance | cross-cutting → **kernel**, not a "security module" |
+| **`me → boxes, streak, prefs, onboarding`**; **`public → grader, security`** | ⚠️ two cross-domain read-aggregators → thin **facades** |
+
+```mermaid
+graph LR
+    subgraph guess["My first cut (by purpose)"]
+        W[work]
+        S[ship]
+        Gr[grading]
+    end
+    subgraph real["What require() shows: ONE module"]
+        T["tasks (work)"] --> GG[grade]
+        T --> SH[ship]
+        T --> CV["+ claims · versions · credits"]
+    end
+    guess ==>|scan| real
+```
+
+> **Important correction:** the import graph turned my three by-purpose modules (work / ship / grading) into **one coupled cluster** — because the seam mechanism (see [04](04-module-lifecycle.md)) later *un*-fuses grading & economy back out via the kernel, the **lifecycle module** ends up = the build *state machine*; grading & economy are modules it *orchestrates*.
+
+## 3. How finely to cut the core — three configs
+
+| Config | Boundaries | Pros | Cons |
+|---|---|---|---|
+| **A · Coarse** (~5 units) | kernel + one core block + game/art/discord/dev-box (= ADR 0080 as-written) | smallest, lowest-risk migration | 70% of code stays a blob — AI-scoping barely improves |
+| **B · Medium** (~10–16 units) **[recommended]** | kernel + core cut into cohesive domains + feature modules; `db.js` carved per-domain | AI-scoping works for core work; lines from the measured graph; UIs first-class | more boundaries to enforce; carve the lifecycle carefully |
+| **C · Fine** (~22+ units) | a module per route-group | smallest blast-radius; max parallelism | fights cohesion (tasks/claims/credits belong together); manifest sprawl; over-engineered |
+
+**Recommendation: sequence A → B, stop before C.** Ship A (proves the loader), then peel the clean, scan-confirmed modules off one at a time (most self-contained first), carving `db.js` per-domain as you go. **Don't split the lifecycle state machine.**
+
+## 4. The one warning: don't cut through the lifecycle
+
+The GDS lifecycle — **claim → work → ship → grade → credit** — is the most coupled part, and the graph proves it (`tasks` imports `grader`, `github-push`, `ship-broadcast`). Keep the **state machine** (tasks/claims/versions) as one module; extract the *capabilities it invokes* (grade, reward) as separate modules behind kernel seams ([04](04-module-lifecycle.md)). Forcing the state machine apart with a strict "import the kernel only" rule would break the rule constantly or bloat the kernel.
+
+## 5. Cross-cutting code (e.g. "security")
+
+Two different things: **security-the-property** (authz, audit, rank ladder — `permission-path-check`/`route-rank-check`, imported everywhere) is **kernel**, enforced by composition + fitness functions, never "called"; **security-the-feature** (red-team reports, bounty, `/builder-redteam` — self-contained) is a **module**, optional + rank-gated, reached through its routes/skill/UI. Every cross-cutting concern (audit, logging, rate-limit) splits the same way.
+
+## 6. The decided roster (~16 modules + kernel)
+
+```mermaid
+graph TD
+    K["KERNEL: auth · rank · db-pool · loader · seam registry ·<br/>audit · live-channel · config/identity · analytics · trusted publish path"]
+    LC[lifecycle] --> K
+    EC[economy] --> K
+    GR[grading] --> K
+    ME[memory] --> K
+    ON[onboarding] --> K
+    ID[ideas] --> K
+    BS[builder-settings] --> K
+    SE[sessions/BFG] --> K
+    AU[autonomy/MAS] --> K
+    SC[security] --> K
+    HU[hall-UI] --> K
+    SU[status-UI] --> K
+    GA[game] --> K
+    AR[art-pipeline] --> K
+    DC[discord] --> K
+    DB[dev-box] --> K
+```
+
+| Module | Owns |
+|---|---|
+| lifecycle | the build state machine — tasks, claims, versions, done-when, ship orchestration |
+| economy | the credit-allocation **model** + ledger + pricing + gamification (streak/achievements/leaderboard) |
+| grading | grade-a-diff (adversarial panel), invoked via the seam |
+| memory | memory · recall · search · learnings |
+| onboarding | admission · setup · newcomer floor |
+| ideas | inbox · capture · triage · blockers |
+| builder-settings | prefs (wandering/skill/sound/render) · builder-needs (`me`/`public` = facades) |
+| sessions/BFG | session records · cost/eval/digest · transcript corpus · BFG |
+| autonomy/MAS | conductor dispatch · architect audits · autonomy-gate · scheduled routines |
+| security | red-team reports · bounty (rank-gated Metic+) |
+| hall-UI · status-UI | the two web surfaces |
+| game · art-pipeline · discord · dev-box | feature modules |
+
+> **~16 is the target ceiling, not a day-one requirement.** Start coarser; split as the coupling scan + fitness demand. Every one is a real cohesive cluster (the scan proved it), but a small team should be "as modular as the evidence supports, no finer." Merging two modules is cheap; the fitness ratchet makes splitting them safe — you're never locked into the first cut.

package/docs/design/modular-architecture/03-builder-flows.md

@@ -0,0 +1,104 @@
+# Builder Flows — what's blocked, what isn't
+
+How a person works once the code is in modules. **Nothing you do is blocked — only where a task's code lands is bounded.**
+
+## The one idea: two kinds of "access"
+
+- **Platform capabilities** — claim, start, ship, file an idea, recall, see your box. These are **kernel endpoints over HTTP, gated only by your rank.** The module structure never touches them. Available everywhere, always.
+- **Code-write scope** — which files a *single claimed task* may change. The **only** thing the structure bounds; it lives at the **worktree** level (not you, not your box); escaped by seeding a new task (itself a kernel capability).
+
+**The wall is around each task's worktree — not around you, and not around your dev box.**
+
+## 1. What the dev box has access to
+
+The dev box is your machine — a persistent environment, **not** module-scoped. Scoping happens one level down, per claim.
+
+| Layer | Scope | Governed by |
+|---|---|---|
+| Dev box (your environment) | full repo, all modules readable, whole CLI, the API, the preview | nothing — it's yours |
+| Kernel capabilities (claim/ship/capture/…) | everything the platform can do | **your rank** (server-enforced) — never a module |
+| A claim's worktree | write = its one module; read = that module + the kernel doorway | the task's **module label** + the ship-time diff check |
+
+## 2. Flow: open a dev box → ship a task
+
+```mermaid
+graph LR
+    A["Open dev box<br/>(box)"] --> B["/builder-start<br/>lists ALL modules<br/>(kernel)"]
+    B --> C["/builder-claim N<br/>a game task<br/>(kernel)"]
+    C --> D["worktree spun:<br/>modules/game + RO kernel<br/>(module-scoped)"]
+    D --> E["agent edits game only<br/>(module-scoped)"]
+    E --> F["/builder-ship<br/>smoke · diff⊆module · grade · merge · deploy<br/>(kernel)"]
+    F --> G["live ✓<br/>worktree reaped"]
+```
+
+Five of seven steps are kernel/box capabilities; only the worktree + the edits are module-scoped. The only *new* thing is a silent check inside `/builder-ship` (diff ⊆ declared module) that in-scope work never notices.
+
+## 3. Flow: claim a task in a different module
+
+You're never "in" a module — each *claim* is. A second claim just makes a second scoped worktree; because the two tasks are in different modules they're **parallel-safe by construction** (no overlap check needed).
+
+## 4. Flow: see an idea — and seed a cross-module task
+
+Browsing ideas, filing an idea, and **seeding a task for another module** are all kernel operations — they need no access to the other module's code, so they work from anywhere. An agent in a game worktree can't *write* dev-box code, but it can always *file the task* for it (one command), then continue or hand off; a dependency link orders them if needed.
+
+## 5. "Could this block me?" — every worry
+
+| Worry | Why it isn't a block |
+|---|---|
+| Claim a task in a module I'm not "in"? | You're never "in" a module. Claiming is kernel; each claim makes its own scoped worktree. |
+| Does my box only have one module's code? | No — the box has the full repo. Only each per-claim worktree is scoped. |
+| Agent needs another module mid-task — stuck? | No — it seeds a task for it (kernel op, needs no access to that code); a dep orders them. |
+| Filing an idea about module X needs X access? | No — capture/inbox is kernel; file from anywhere. |
+| Is shipping gated by my module? | No — ship is kernel; the only module check is "diff ⊆ module," which passes for normal work. |
+| Need to change the kernel/doorway? | Seed a kernel/core task (rank-gated as today); ship it first; the module task depends on it. |
+
+## 6. Long autonomous sessions stay mobile
+
+A Claude Code session is **not** welded to one worktree. The session is a **conductor**; each claimed task runs in its own module-scoped worktree:
+
+```mermaid
+graph TD
+    S["long autonomous SESSION = <redacted> repo · full mobility · no module binding"]
+    S --> A["task A (game) → worktree A → its own PR → ship"]
+    S --> B["task B (dev-box) → worktree B → its own PR → ship"]
+    S --> C["task C (memory) → worktree C → its own PR → ship"]
+```
+
+- **Parallel** (`--parallel N`): the conductor fans out worker subagents, each `isolation: "worktree"`, each on a different module → they can't collide (different modules).
+- **Sequential**: the conductor `EnterWorktree`s a fresh worktree per task, ships, `ExitWorktree`s, moves on.
+
+The session has full mobility across modules; only each *task's worker* is module-isolated. This is the orchestrator-worker pattern (ADR 0024), and the GDS already assigns a per-claim worktree.
+
+## 7. Limiting what the box holds — the jailbreak blast radius
+
+The split lets the box hold **far less**: only the claimed module (read/write) + the kernel's **safe contract** (signatures, read-only) + client plumbing + a scoped token. The kernel **implementation** (auth, rank, ship, grade) never leaves the server.
+
+```mermaid
+graph LR
+    subgraph Box["DEV BOX · one claim (= jailbreak blast radius)"]
+        M["modules/&lt;key&gt;/ — read/write"]
+        KC["kernel CONTRACT — signatures + docs only (RO)"]
+        CLI["CLI plumbing (cli-lib)"]
+        TOK["scoped, claim-scoped token (not full-repo)"]
+    end
+    subgraph Server["SERVER · the trusted side"]
+        KI["KERNEL IMPL — auth · rank · ship · grade<br/>(never on the box)"]
+        OM[every other module's source]
+        FR[full repo + history]
+        EN["ENFORCES the rank ladder, live per request (ADR 0016)"]
+    end
+    Box -->|"privileged ops = HTTP call<br/>(box can't push main)"| Server
+```
+
+**The trap to avoid:** reducing what's *on disk* is not reducing *access* — a box holding a full-repo credential re-fetches. The real lever is **scoping the box's credential + fetch to the claimed module** (and module access can be **rank-gated** too, since the server mediates every fetch). The primary boundary always remains the **server-enforced rank ladder**; on-disk minimization is defense-in-depth on top.
+
+| Approach | Efficiency | Real confidentiality boundary? |
+|---|---|---|
+| Sparse-checkout only | ✓ smaller tree | ✗ — `.git` still has everything |
+| Partial clone + sparse | ✓✓ | ~ — box can lazily re-fetch with its token |
+| **Server-mediated, claim-scoped fetch** | ✓✓ | **✓ — box never holds a full-repo remote or kernel source** |
+| Per-module repos | ✓✓ | ✓✓ strongest — but contradicts single-repo (ADR 0080 rejected package-modules for v1) |
+
+## 8. Two boundaries that compose (no new friction)
+
+Modules sit **beside** the rank trust boundary, not replacing it: **rank** = *what* you may do (server-enforced, live); **module** = *where* this task's code lands (ship-time diff check + worktree scope). Neither adds a step to the builder's day — you still run `/builder-start`, `/builder-claim`, `/builder-ship` exactly as now. The structure is invisible in the happy path; the wall only shows itself when a task tries to wander, and then the answer isn't "blocked," it's "that's a second task."

package/docs/design/modular-architecture/04-module-lifecycle.md

@@ -0,0 +1,62 @@
+# Module Lifecycle & Maintenance
+
+How modules talk to each other, grow, and stay healthy as the codebase expands.
+
+## 1. How modules talk without importing each other
+
+The one-way rule forbids a module importing another. But the **lifecycle** (which ships a task) needs a reward figure the **economy** module calculates. The resolution is a **kernel-mediated seam** — the kernel is a switchboard:
+
+- **Ports** (a *required, single-provider* capability): the economy module registers a `reward` provider; at ship, the lifecycle asks the kernel to resolve `reward` and calls it. **Economy owns the formula *and* the ledger**; the lifecycle only supplies the session and delivers the result.
+- **Events** (an *optional* reaction): the lifecycle emits `task.shipped`; the discord module reacts if it cares.
+- **Contributions** (an *accumulating extension point*): zero-or-more modules each add a piece to a named point and the kernel hands the whole set to a core consumer — how a module adds its own slice to a shared core surface without core hardcoding it. The `profile.fields` point lets dev-box/discord/art add their slice to the `GET /me` payload (and its browser twin, `window.OTB.contributeSettingsPanel`, adds a Settings panel) instead of those being baked into `routes/me.js` + `settings.js` (BV1.R42 / task 1411 — the strangler prerequisite for those three moves; game has no such coupling). Add-only: a contribution may introduce keys, never overwrite a core one.
+
+```mermaid
+graph LR
+    LC["LIFECYCLE<br/>build state machine<br/>▸ ship step"]
+    subgraph K["KERNEL — the switchboard (seam registry)"]
+        PR["port: reward"]
+        PG["port: grade"]
+        EV["event: task.shipped"]
+    end
+    EC["ECONOMY<br/>reward model + ledger"]
+    GR["GRADING<br/>grade-a-diff"]
+    DC["DISCORD<br/>notify"]
+    LC -->|"① at ship: resolve reward + grade, emit shipped"| K
+    EC -->|"② provides"| PR
+    GR -->|"② provides"| PG
+    EV -.->|reacts| DC
+```
+
+No module holds a reference to another; the kernel resolves ports and fans out events. The one-way arrow holds.
+
+> **This revises the earlier fusion — for the better.** The scan showed `tasks → grader`/`tasks → ship` as *direct imports*, so they looked like one module. But the seam economy needs *un*-fuses them: those imports become **seam calls**. So **grading and economy become their own modules the lifecycle *orchestrates*, not imports.** The lifecycle shrinks to the build **state machine** (claim→active→…→shipped) that, at defined points, asks the kernel for `grade` and `reward`. That's ports-and-adapters, and it's cleaner than the blob.
+
+The decided roster (~16 modules + kernel) lives in [02 §6](02-module-map.md#6-the-decided-roster-16-modules--kernel).
+
+## 2. The four maintenance flows
+
+| Flow | What happens | What keeps it safe |
+|---|---|---|
+| **Add a module** | `bongos module new <key>` scaffolds the manifest + dirs → write routes/db/ui/skills → declare in `module.json` → flip the flag in `config/modules.json`. Loader discovers + mounts. **No core edit.** | fitness: manifest valid, write routes rank-gated, migrations additive + namespaced, no kernel-internal imports |
+| **Grow a feature inside a module** | claim a module-scoped task → edit only `modules/<key>/` → additive namespaced migration → ship | blast radius = that module; ship-time diff⊆module |
+| **One module needs another's capability** | declare it (consumed port / `prerequisites.modules`) → call it **through the kernel seam**, never by import | loader verifies the provider is enabled; one-way arrow preserved; fitness fails any direct cross-module import |
+| **Evolve the kernel contract** | adding to `module-api.js` = a **minor** semver bump (safe); changing/removing = **major**. Each module declares the `coreVersion` it supports. | `bongos upgrade` pre-checks every enabled module's `coreVersion` and refuses/warns on mismatch (fail-closed) |
+| **A feature spanning modules** | decompose into an **epic of per-module child tasks + dependencies**. If two modules keep needing each other, add a kernel **port**. | each child stays isolated + parallel-safe; the coupling scan flags chronic cross-talk |
+
+## 3. Fitness functions are the immune system
+
+The reason this stays healthy as the codebase triples is **not reviewer vigilance — it's CI.** Every PR runs the fitness checks (core carries no module code · core never imports a module · modules import only the published API · every module write route is rank-gated · module migrations are additive + namespaced). A violation is a **red build**. In an **AI-built** system this is decisive: an agent working a module-scoped task **cannot** silently erode the architecture, because the boundary is enforced on the way in. The "ratchet" rule makes it monotonic — grandfathered violations may only shrink; new ones are rejected. The architecture maintains itself.
+
+## 4. The manifest is the living contract
+
+As a module grows, the one thing you keep honest is its `module.json` — the single declared source of what it contributes (routes, skills, UI, migrations, the ports it provides and consumes). Loader + fitness both act on it, so "maintaining a module" largely means "keeping its manifest true," and CI proves you did. Each module also carries its own nested `CLAUDE.md`, so an agent scoped to it stays oriented no matter how big the rest of the platform gets.
+
+**Detecting drift:** re-run the `require()`-graph / coupling scan periodically (cheap, deterministic). If two modules that shouldn't talk keep accumulating seam calls, the boundary is drifting — formalize a port or merge them. That scan is how you catch a wrong line early (it's how the work/ship/grade over-split was caught in [02](02-module-map.md)).
+
+## 5. The honest tradeoff
+
+More modules buy isolation, AI-scoping, and parallelism — but each is ceremony (a manifest, a boundary to enforce, maybe a seam to wire). For a bootstrapped team the sweet spot is **"as modular as the evidence supports, no finer."** Promote a cluster to a module when (a) the scan shows it's genuinely self-contained, (b) you want to scope agents/access to it, or (c) it's optional per-instance. Until then, leave it coarse. The migration is incremental and reversible-ish — merging two modules is cheap, and the fitness ratchet makes splitting them safe — so you are never locked into the first cut.
+
+---
+
+*The seam mechanism is ADR 0080 §6's declared extension points (`extends: { hooks: [...] }`) generalized to required ports + events; the upgrade/compat flow is ADR 0080 §7; fitness functions are ADR 0062 §9 / ADR 0080 §5.*

package/docs/design/modular-architecture/README.md

@@ -0,0 +1,27 @@
+# Cloud Bongos — Modular Architecture (design research)
+
+Five reports from the **2026-06-21 modular-architecture design session**, filed as durable markdown so they live in version control rather than as ephemeral Claude artifacts.
+
+> **Status: pre-red-team draft.** These are research/design reports, not a decision record. A formal numbered ADR follows once they've been red-teamed. Filed under `docs/design/` (not `docs/adr/`) on purpose — the ADR numbering is in flux (0079→0081 collisions), so the number is assigned later on an up-to-date worktree.
+
+| # | Doc | What it answers |
+|---|-----|-----------------|
+| 00 | [Research report](00-research-report.md) | Industry best practice on packaging, plugins, theming, and AI-agent scoping (cited) |
+| 01 | [Architecture](01-architecture.md) | The concrete core+modules design; why not a rewrite; the migration path |
+| 02 | [Module map](02-module-map.md) | Where the ~95k LOC live; how finely to cut the core; the decided roster |
+| 03 | [Builder flows](03-builder-flows.md) | What the dev box can access; why the structure never blocks a builder |
+| 04 | [Module lifecycle & maintenance](04-module-lifecycle.md) | How modules interact (seams) and stay healthy as code grows |
+
+## The decided model (one paragraph)
+
+A small **kernel** (auth, rank, db-pool, the loader, the seam registry, trust primitives, config/identity, analytics, the trusted publish path) plus **~16 modules** (lifecycle, economy, grading, memory, onboarding, ideas, builder-settings, sessions/BFG, autonomy/MAS, security, hall-UI, status-UI + game/art-pipeline/discord/dev-box). Modules **never import each other** — they interact through **kernel-mediated seams** (ports + events). Boundaries are held by **CI fitness functions** so the structure can't rot as it grows. It stays **single-package, single-process, no-bundler** — modularity is a separate axis from packaging/runtime/build. It is built via an incremental **strangler migration**, not a ground-up rewrite.
+
+## How the boundaries were drawn
+
+Not by intuition. The module lines come from a **`require()`-graph scan of all 111 files in `src/bongos`** (see [02](02-module-map.md)) — the kernel is confirmed by in-degree (auth 35, db 28, pool 24, _helpers 23, then a cliff), and the lifecycle cluster is confirmed by direct edges (`tasks → grader`, `tasks → github-push`, `tasks → ship-broadcast`).
+
+## Provenance & confidence
+
+- The research report (00) is **partial** — its synthesis step was cut by an org Claude spend limit; 12 claims passed full adversarial verification, the rest are sourced-but-not-triple-verified. It's a cited starting point, not an exhaustive survey.
+- The architecture, map, flows, and lifecycle docs are **synthesis + codebase-grounded** (read at commit `cc8a5e0`).
+- Related: memory `project-modular-architecture-scoping`. Builds on **ADR 0080** (project-extensible module system), **0062** (instance decoupling), **0061** (context layers), **0016** (trust boundary), **0049** (parallel-safety contract).