@bongos/core 1.17.0

package/docs/adr/0082-server-side-merge-conflict-auto-resolution.md

@@ -0,0 +1,55 @@
+# ADR 0082 — Server-side auto-resolution of generated-file & append-index merge conflicts
+
+- **Status:** Accepted
+- **Date:** 2026-06-21
+- **Track:** internal
+- **Builds on:** [ADR 0055](<redacted>.md) (server-mediated publish — the box holds no push credential; the server pushes), [ADR 0063](<redacted>.md) / [ADR 0066](<redacted>.md) / [ADR 0062](<redacted>.md) §8 (the generated artifacts + the `otb-regen` merge driver, task 1243), [ADR 0016](<redacted>.md) (trust boundary — this does NOT touch it)
+- **Task:** [#1385](https://example.com/builders#/task/1385) (idea [#349](https://example.com/builders#/idea/349))
+
+## Context
+
+The active merge driver (task 1162, `github-push.mergeIfGreen`) lands a green PR the moment it is mergeable AND `CLEAN`, but bails on **any** conflict (`reason:'merge_conflict'`) and the publish-reconciler just moves on. Two conflict classes recur constantly in a multi-builder repo and are *not* genuine disagreements — they are mechanical collisions:
+
+1. **Generated artifacts** — `docs/repo-map.md`, `docs/file-map.md`, `docs/session-log-index.md`, and the nested `CLAUDE.md` symbol blocks. Two parallel branches each regenerate them, so they conflict on nearly every merge. Task 1243 already solved this *locally* with the `otb-regen` git merge driver (`scripts/gds/git-merge-regen.js`), which regenerates them from the merged tree.
+2. **The `docs/adr/README.md` append-index** — a hand-maintained table whose only recurring conflict is two branches each appending a new ADR row. There is no generator to rebuild it from, so `otb-regen` can't help it at all.
+
+The gap: task 1243's machinery only runs in a **local** `git merge` (a builder's box, `/merge-mode`, ship's pre-stage). But the default ship path is **server-mediated** (ADR 0055) and lands via GitHub's own merge — and **GitHub's merge cannot run a custom merge driver** (`otb-regen`). So a confirmed PR that later conflicts only on these files sits open forever until a human with a credentialed checkout runs a local merge. This is the exact stall behind PR #300 and PR #167 (both on `docs/adr/README.md`).
+
+The owner framed the goal as "kill the merge bottleneck" — and **explicitly rejected** the tempting alternative of lowering deploy/merge access down to the `thetes` rank. That would reopen the Builder 25 hole ([ADR 0043](<redacted>.md)): a lightly-trusted agent landing changes on a live prod payment system. The right fix changes *who does the mechanical work*, not *who is trusted to land code*.
+
+## Decision
+
+Two pieces, both reusing the task-1243 machinery rather than reinventing it:
+
+**1. `.gitattributes` coverage.**
+- `docs/adr/README.md merge=union` — the built-in `union` driver keeps both sides' appended rows, the correct resolution for an append list. `union` is core git (no per-clone registration) and is honored by every *local* merge.
+- `docs/session-log-index.md merge=otb-regen` + adding it to `REGENERABLE` in `git-merge-regen.js` (a whole-file `renderIndex(collectEntries())`, like `docs/repo-map.md`) — so the generated session index self-heals everywhere the rest do.
+
+**2. `src/bongos/conflict-resolve.js` — a server-side resolver** wired into the publish-reconciler. When a confirmed task's PR reports `merge_conflict`, it:
+1. Clones the server's checkout into a throwaway temp dir (never the deploy worktree — mirrors `github-push.pushBundle`).
+2. Registers the `otb-regen` driver in that clone (`install-git-hooks.registerMergeDriver`); `union` needs none.
+3. Fetches fresh `origin/main` + the feature branch over the server's credentialed URL and checks out the branch.
+4. Runs `git merge origin/main`. The driver resolves the generated files; `union` resolves the ADR index; **any genuine hand-written conflict leaves the merge non-zero**, and we `git merge --abort` and leave the PR untouched for a human.
+5. On a fully-clean merge (asserted: no unmerged paths, no surviving `<<<<<<<`/`>>>>>>>` markers), pushes the resolved branch.
+
+The PR's required checks (unit / trufflehog / audit / gate-review) re-run on the new head, and the next `mergeIfGreen` sweep lands it.
+
+## Why this is safe — and never worse than today
+
+- **It bypasses no gate.** It pushes a *commit*; it does not merge to `main`. Every required check re-runs before anything lands. It cannot bypass the grader, gate-review, or rank checks — and **zero change to the trust boundary** (the rejected `thetes` alternative).
+- **It resolves only what the driver/union resolve.** A real hand-conflict aborts to a human; the resolver invents nothing (`git-merge-regen` already exits non-zero if any marker survives a regeneration).
+- **Isolated + best-effort + kill-switchable.** It works in a temp clone (can't race `~/deploy.sh`), is wrapped best-effort in the reconciler (a failure is logged, never thrown), and is killable via `CONFLICT_RESOLVE_DISABLED=1`. If anything goes wrong the strand is simply left exactly as it is today.
+- **No `--force`, ever.** A non-fast-forward push (someone moved the branch) fails safely; the next sweep retries against the new tip.
+
+## Consequences
+
+- Generated/index-only conflicts on the server path now self-heal within a reconciler sweep (~5 min) with no human and no credentialed checkout — the PR #300/[#167](https://example.com/builders#/task/167) class is closed going forward.
+- The resolution push changes the PR head, so an SHA-pinned `gate-owner-approved` (ADR 0058) on a *gate-surface* PR would need re-approval. In practice these conflicts are on docs/index files (rarely gate-surface), so this is uncommon; when it happens, the behavior is the same one-click re-approval as any post-push change.
+- `docs/adr/README.md` itself now carries `merge=union`, so this ADR's own index row — and every future one — stops conflicting.
+- The generated-artifact set is defined once (`REGENERABLE` in `git-merge-regen.js`, mirrored by `.gitattributes` and the `fitness.js` freshness gate); adding a future generated file means adding it in those places together.
+
+## Alternatives considered
+
+- **Lower deploy/merge access to `thetes`** (the owner's first instinct) — rejected: reopens the Builder 25 hole for zero benefit here (the stranded session was already Archon; rank was never the blocker).
+- **Rely on GitHub honoring `union`/custom drivers server-side** — GitHub does not run custom merge drivers, and `union` honoring is unreliable across GitHub's merge surface; doing the merge locally on the server makes the outcome deterministic regardless.
+- **A `gen-adr-index.js` generator** so `otb-regen` could rebuild `docs/adr/README.md` — rejected for now: the index's `Track`/`Topic` columns are human-authored and not derivable from the ADR files, so `union` is the correct, cheap resolution for an append list.

package/docs/adr/0083-modular-architecture-strangler-build-plan.md

@@ -0,0 +1,143 @@
+# ADR 0083 — Practical build plan for the modular architecture (strangler migration)
+
+**Status:** Accepted (2026-06-21) · task [#1405](https://example.com/builders#/task/1405) (BV1.R36) · epic [#1388](https://example.com/builders#/task/1388) (BV1.R34) · spike that produced the design: [#1383](https://example.com/builders#/task/1383) → design research in [`docs/design/modular-architecture/`](../design/modular-architecture/) (5 docs, task [#1401](https://example.com/builders#/task/1401))
+
+**Amended by:** [ADR 0091](<redacted>.md) (2026-06-26, BONGOS-V1 C7) — extends this strangler from the four *feature* modules into the **core itself**: bounds the kernel as an enumerated file roster (the "~3.5k-LOC kernel" this ADR kept referencing), defines the per-domain `db.js` carve mechanism, and classifies what the `src/module-api.js` doorway may expose. Nothing here is reversed; 0091 makes "the kernel" and "carve `db.js` per-domain" concrete.
+
+**Builds on:** [ADR 0062](<redacted>.md) (instance/model decoupling — the core↔host split, §4 module registry, §5 module-owned migrations, §9 fitness functions), [ADR 0061](<redacted>.md) (context layers / nested CLAUDE.md), [ADR 0016](<redacted>.md) (server-enforced rank boundary), [ADR 0043](<redacted>.md) (protected paths), [ADR 0049](<redacted>.md) (`touches[]` advisory).
+
+> **Numbering reconciliation (read this first).** The design docs, the epic [#1388](https://example.com/builders#/task/1388), and task [#1389](https://example.com/builders#/task/1389) all refer to the project-extensible module system as **"ADR 0080"**. That number was taken by the LLM-cache transport ADR ([ADR 0080](<redacted>.md)) before the module-system ADR was written — the same `0079→0081` collision class recorded in project memory. **The module-system decision record is THIS file, ADR 0083.** Where the design docs or those tasks say "ADR 0080 (module system / plugin API)", read "ADR 0083". ADR 0080 is unrelated (it is the LLM cache).
+
+---
+
+## Context
+
+The modular architecture has been **scoped** — five research/design documents under [`docs/design/modular-architecture/`](../design/modular-architecture/) settle *what* to build and *why*. This ADR settles **how we practically build it**: the concrete, sequenced, CI-guarded migration, mapped 1:1 onto claimable GDS tasks.
+
+The design's load-bearing conclusions (not re-argued here — see the design docs):
+
+1. **Reorganize, don't rewrite.** The foundation (trust boundary, GDS ship/grade/deploy pipeline, grader, ~143 migrations) is *sound*; the filing (fused game/core, a ~5.3k-LOC shared `db.js`, flat routes, inline `if (isModuleEnabled())` gates, hardcoded brand strings) is *wrong*. Rewrite when the foundation is wrong; reorganize when the filing is wrong ([01 §5](../design/modular-architecture/01-architecture.md)).
+2. **Modularity is one axis of four.** Move *only* modularity (how code is organized). **Stay** single-package, single-process, no-bundler ([01 §1](../design/modular-architecture/01-architecture.md)). Each "stay" has a clean future fork (marketplace → packages; untrusted modules → processes; a UI needing a build → that module owns its build) that this plan does not foreclose.
+3. **Boundaries are held by CI fitness functions, not discipline.** In an AI-built system this is decisive: an agent on a module-scoped task *cannot* silently erode the architecture, because a violation is a red build ([04 §3](../design/modular-architecture/04-module-lifecycle.md)).
+4. **The roster is ~16 modules + a ~3.5k-LOC kernel**, drawn from a `require()`-graph scan, not intuition ([02](../design/modular-architecture/02-module-map.md)). Sequence **coarse → medium**, stop before fine; **never cut through the lifecycle state machine**.
+5. **Modules talk through kernel-mediated seams** (ports + events), never by importing each other ([04 §1](../design/modular-architecture/04-module-lifecycle.md)).
+
+### What already exists (grounded at `cc8a5e0` / `494d1d77`)
+
+The migration is **moving files into `modules/<key>/` and replacing inline gates with a loader** — not inventing the flag layer. The seeds are already in place:
+
+| Seed | Where | Status |
+|---|---|---|
+| A module registry with a `contributes` map | `src/modules.js` (~240 LOC): `isModuleEnabled`, `enabledDisciplines`, `clientModules`, `loadModules` | **closed** — a hardcoded `KNOWN_MODULES` set of four; the loader opens it |
+| Per-instance enablement config | `config/modules.json` (OTB: all four on) over `config/modules.neutral.json` (vanilla: all off) | works; loader keeps reading it |
+| Inline mount gates (the lines a loader DELETES) | `server.js:139-143,176-178,186-191` (game rooms, world precreate, discord bot); `src/bongos/routes.js:122-123` (dev-box + discord routers); `src/bongos/routes/instance.js:119` (`devBoxEnabled`) | replace with loader-driven mount |
+| Client UI gates | `window.__MODULES__` → `public-builders/dom-utils.js:103` `moduleOn()`; consumed in `builders.js`, `settings.js` | keep; loader keeps injecting `__MODULES__` |
+| Fitness gate (6 checks) | `scripts/gds/fitness.js` → `tests/fitness.mjs` → the `unit` CI job (`pr-unit-tests.yml`) | **extend** with the boundary checks |
+| One thin route mounter | `src/bongos/routes.js` (`buildGdsRouter()`), single mount at `src/bongos/serve-internal.js:155` | loader composes module routers behind auth here |
+| Per-module migrations precedent | `migrations/game/` applied enabled-gated in `scripts/migrate.sh:62-67` (`MEDUSA_GDS_ONLY` gate); `schema_migrations` is **stem-keyed** so moving a file between dirs does **not** re-run it (`migrate.sh:25-26`) | **generalize** to `modules/<key>/migrations/` |
+| A GDS-only schema verifier | `scripts/verify-gds-only-schema.sh` (the R52 carve-out test) | generalize per-module |
+| The core↔host import-boundary check | `fitness.js` `checkCoreHostBoundary` (`HOST_GAME` regex, empty `GRANDFATHERED` set) | the template for the module-boundary checks |
+
+**There is no `modules/` directory yet.** The kernel (`src/bongos/auth.js`, `pool.js`, `db.js`, `route-rank-check.js`, `permission-path-check.js`, the loader-to-be) stays where it is; modules move *out* around it.
+
+---
+
+## Decision
+
+**Build the whole product into `core + modules` via an incremental strangler migration, one module at a time (most-isolated first), with each step shipping independently and guarded by CI fitness functions. Stay single-package, single-process, no-bundler. Enforce the one-way boundary by composition (the loader owns the mount) and by fitness (a violation is a red build), not by trust.**
+
+The unit of work is a **module** = a vertical slice (its routes, DB tables, UI, skills, agent-context) reachable through **one published doorway** (`src/module-api.js`). The five rules ([01 §3](../design/modular-architecture/01-architecture.md)): (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.
+
+### The doorway and the loader
+
+- **`src/module-api.js`** — the stable, **semver'd** import surface, and the *only* core file a module may `require`. It re-exports the kernel capabilities a module legitimately needs: `requireBuilder` / `requireRank` (auth, from `src/bongos/auth.js`), a DB pool accessor (`src/bongos/pool.js`), the **seam registry** (`registerProvider`/`resolve` for ports; `emit`/`on` for events), config/branding/identity (`src/instance-config.js`, `config/branding.json`), and a logger. It carries a `CORE_VERSION` constant. Adding to it is a **minor** semver bump (safe); changing/removing is **major** ([04 §2](../design/modular-architecture/04-module-lifecycle.md)). *(The design docs call this `core/module-api.js`; we site it at `src/module-api.js` to match the existing `src/modules.js` sibling and epic [#1388](https://example.com/builders#/task/1388) step 1. "core/" is the conceptual kernel, not a directory move.)*
+- **The loader** — replaces the closed `KNOWN_MODULES` registry in `src/modules.js`. It (a) **discovers** `modules/*/module.json` across roots, (b) **validates** each manifest against a schema, (c) checks `coreVersion` compatibility (fail-closed), (d) **resolves → loads → mounts** each enabled module's route factory **behind kernel-composed auth** (the module ships a route *recipe* + a required rank; the loader wraps audit → `requireBuilder` → `requireRank` around it — [01 §3a](../design/modular-architecture/01-architecture.md)), (e) starts/stops its pollers, (f) applies its migrations (enabled-gated). The existing `isModuleEnabled`/`enabledDisciplines`/`clientModules` exports stay as a **back-compat facade** over the loader so nothing downstream breaks during the move.
+- **The seam registry** — the kernel switchboard ([04 §1](../design/modular-architecture/04-module-lifecycle.md)). **Ports** (required capability): the economy module registers a `reward` provider; at ship the lifecycle asks the kernel to resolve `reward` and calls it. **Events** (optional reaction): the lifecycle emits `task.shipped`; discord reacts if it cares. No module ever holds a reference to another.
+
+### How the boundary is enforced (trust = composition + fitness, never trust)
+
+Two layers, composing with the existing rank boundary ([03 §8](../design/modular-architecture/03-builder-flows.md)): **rank** = *what* you may do (server-enforced, live, ADR 0016); **module** = *where* this task's code lands (worktree scope + a ship-time diff⊆module check).
+
+New fitness checks, each a pure `checkXxx()` added to the `CHECKS` array in `fitness.js:285` (riding the `unit` job with **zero workflow changes** — they're picked up by `tests/fitness.mjs`):
+
+1. **core never imports a module** — mirror `checkCoreHostBoundary`: flag any `require()` under the kernel that resolves into `modules/`. Fresh `GRANDFATHERED` set, ratcheted to empty as moves land.
+2. **modules import only the published API** — walk each `modules/<key>/`, flag any `require()` resolving into core internals *other than* `src/module-api.js` (reject deep `src/bongos/db`, `src/bongos/auth`, …) and any resolving into a *sibling* module.
+3. **every module write-route is rank-gated** — **do not re-implement.** Parameterize `route-rank-check.js`'s `ROUTES_DIR` (`route-rank-check.js:26,151-159`) to *also* walk `modules/**/routes/`; module write-routes then inherit the exact "unknown write = blocker" rule Check 4 already enforces.
+4. **core carries no module-specific code** — assert no module key/domain term leaks into kernel files.
+5. **module migrations are additive + namespaced** — read `modules/<key>/migrations/`, regex-reject destructive DDL (`DROP TABLE`/`DROP COLUMN`/destructive `ALTER`) and assert a `<key>_`-prefixed object namespace.
+
+Each new check returns `warnings` until the tree is clean, then flips to `violations` (the ratchet). Every check ships with a **negative test** (proves it actually catches a violation) alongside the clean-pass test, mirroring `tests/fitness.mjs`.
+
+### Module-owned migrations
+
+Generalize the working `migrations/game/` precedent ([02 §1 grounded](../design/modular-architecture/02-module-map.md)):
+
+- Teach `scripts/migrate.sh` to discover `modules/*/migrations/*.sql` and apply each **only if its module is enabled** (the `MEDUSA_GDS_ONLY` gate generalized to per-module enablement). `schema_migrations` stays **stem-keyed**, so relocating a migration from `migrations/game/` to `modules/game/migrations/` does **not** re-run it on prod — the existing safety guarantee carries the move for free.
+- **Disable preserves data** — the entire mechanism is "don't apply," never "drop." There is no down-migration path and we keep it that way; a disabled module's tables simply are never created (or are left untouched).
+- Generalize `scripts/verify-gds-only-schema.sh` into a per-module schema-presence/absence verifier.
+- `scripts/migrate.sh` is a **gate HARD-FLOOR** (`gate-review.js`) and `migrations/` is **NEEDS_TRUST + a protected path** (`permission-path-check.js:78-80`): the runner change needs owner sign-off; new `modules/<key>/migrations/` subtrees inherit the protected-path treatment. The loader/migrate change is owner-gated by construction.
+
+### The four module moves — ordered by *measured* isolation
+
+From the `require()`-graph + reference scan (not intuition — [02 §2](../design/modular-architecture/02-module-map.md), confirmed in this ADR's grounding pass):
+
+| Order | Module | Coupling into core | Why this slot |
+|---|---|---|---|
+| **1** | **dev-box** | **0** refs in `server.js`/`routes.js` bodies; self-contained `box*.js` cluster; box-prefixed tables; routes already flag-gated at `routes.js:122` | **The template move.** Cleanest seam; every later move copies it. Only seam: ~16 read-only box-status lines in `routes/me.js`. |
+| **2** | **game** | **0** refs in any `src/bongos/` core file; lives entirely outside `src/bongos/` (`src/rooms/`, `src/world/`, `public/game/`); **already** has `migrations/game/` + a game-less `platform-server.js` | Most pre-separated. Slot 2 only because its server/client render twins must move together and `server.js` carries its static-serve tail + the Colyseus "realtime capability" seam. |
+| **3** | **discord** | bot + broadcast cleanly isolatable, but the link/role **UI is woven into core** — `routes/me.js` (63 refs) + `settings.js` (19) | Needs the profile/settings contribution seam first. |
+| **4** | **art-pipeline** | **no own router** — its API lives *inside* core `routes/me.js` (art-key, ~32 refs); the `artist` discipline threads through `src/modules.js` `enabledDisciplines()`; ~18k LOC `art/` tree | Hardest clean cut; largest body; last. |
+
+**The recurring seam** across dev-box/discord/art is **`src/bongos/routes/me.js`** (the builder-profile route embeds all three) and **`public-builders/settings.js`** (embeds all three UI panels). A **module→core contribution hook** (a registration callback for profile fields + settings panels) is the prerequisite that lets dev-box/discord/art leave core. Game has *zero* such coupling and needs no profile seam.
+
+### task→module affinity (the follow-on)
+
+The research centerpiece ([00 §6](../design/modular-architecture/00-research-report.md)) — move the unit of work-affinity *up* from file paths to modules. Once the roster exists: a task declares **module affinity**; the agent loads only that module + the published API (smaller context, higher quality); parallel-safety becomes **module-disjointness** (cleaner than path overlap); drift detection becomes semantic ("you said dev-box, you touched game"); and the file-path `touches[]` (ADR 0049, already advisory) **retires** in favor of the module label + a ship-time diff⊆module check. This depends on the full move being done, so it is the **final tier** of this plan, not a precondition.
+
+---
+
+## The build plan → seeded tasks
+
+Each phase maps to a claimable BONGOS-V1 task under criterion **C5 (`module-system-live`)**, dependency-ordered. (Seeded by `scripts/gds/seed-bongos-module-system-tasks.js`, companion migration `144`. R## numbers are assigned sequentially after the current max; the dependency edges below are authoritative.)
+
+| Phase | Task (by role) | Delivers | Depends on |
+|---|---|---|---|
+| 0 · Doorway | `module-api.js` | the published, semver'd import surface + `CORE_VERSION` + nested CLAUDE.md | — |
+| 0 · Doorway | fitness one-way checks | "core never imports a module" + "modules import only the API" (warn-mode; green on empty `modules/`) | module-api.js |
+| 1 · Loader | manifest schema + validator | `module.json` schema (key, coreVersion, `contributes`, `provides`/`consumes`, `prerequisites`) + validator | — |
+| 1 · Loader | the loader | discover → validate → coreVersion-check → mount-behind-auth → pollers → teardown; back-compat facade over `src/modules.js` | module-api.js, manifest schema |
+| 1 · Loader | seam registry | kernel ports (`registerProvider`/`resolve`) + event bus (`emit`/`on`) | module-api.js |
+| 2 · First move | profile/settings contribution seam | module→core hook for `routes/me.js` profile fields + `settings.js` panels | seam registry |
+| 2 · First move | **move dev-box** → `modules/dev-box/` | move files; delete `routes.js:122` gate; loader mounts; OTB byte-identical | loader, profile seam |
+| 3 · Trust | fitness module-route rank gate | parameterize `route-rank-check.js` to walk `modules/**/routes/` | loader |
+| 3 · Trust | fitness core-clean + migration checks | "core carries no module code" + "module migrations additive/namespaced" (flip warn→violation) | loader, move dev-box |
+| 4 · Migrations | module-owned migrations | generalize `migrate.sh` + `verify-gds-only-schema.sh` to `modules/<key>/migrations/` | loader |
+| 5 · More moves | **move discord** → `modules/discord/` | bot/broadcast/routes + link UI via the profile seam | move dev-box, profile seam, module migrations |
+| 5 · More moves | **move art-pipeline** → `modules/art-pipeline/` | carve art-key API out of `me.js`; `art/` tree; artist-discipline contribution | move dev-box, profile seam |
+| 6 · Game | **move game** → `modules/game/` | rooms/world/`public/game`/`migrations/game`; Colyseus "realtime capability" seam | loader, module migrations |
+| 7 · DX | `bongos module new <key>` + `bongos upgrade` | scaffolder (manifest + dirs + nested CLAUDE.md) + coreVersion pre-check | manifest schema, loader |
+| 8 · Docs | rewrite `docs/modules-contract.md` + index sweep | plugin-API contract + module-author recipe; CLAUDE.md / file-map / architecture / ADR README | scaffolder, all moves |
+| 8 · Proof | live demonstration | scaffold a throwaway module via `bongos module new`, mount it, ship it, OTB byte-identical; fitness catches a deliberate cross-module import | all moves, scaffolder |
+| 9 · Follow-on | task→module affinity | `task.module`; module-disjoint parallel-safety; retire `touches[]`; module-scoped agent context | full roster moved |
+
+**Proof of equivalence at every step** (as in ADR 0062's core/host split): after moving a module, OTB behaves **byte-for-byte the same**. That is the per-phase done-when.
+
+---
+
+## Consequences
+
+**Positive.** The architecture becomes self-maintaining (fitness ratchet); AI agents get module-scoped context (higher quality, lower token cost — the research's biggest lever); a host can add/configure modules without forking core (the defining Cloud Bongos capability); parallel-safety gets cleaner (module-disjointness); the trust boundary is *extended* to module routes, never weakened. Each phase ships independently and is individually revertible — merging two modules back is cheap, the ratchet makes splitting safe, so the first cut is never a lock-in.
+
+**Negative / cost.** ~16 boundaries to enforce (mitigated: fitness does it, not reviewers; start coarse). More ceremony per module (a manifest, a nested CLAUDE.md, maybe a seam). The lifecycle state machine must **not** be force-split (the one warning — [02 §4](../design/modular-architecture/02-module-map.md)). Several phases touch gate-protected surfaces (`migrate.sh` HARD-FLOOR, `routes.js`/`server.js`/`fitness.js`/`module-api.js` core trust surfaces) → owner Gate approval + admin-merge are expected on those PRs; this is the boundary working as designed, not friction to remove.
+
+**Neutral.** Single-package / single-process / no-bundler are explicitly preserved; `start` stays `node server.js`. The future forks (packages, process isolation, per-module build) remain open and are deliberately *not* taken now.
+
+---
+
+## Alternatives considered
+
+- **Ground-up rewrite — rejected.** Re-derives the sound parts (auth, ranks, tasks/claims/credits, grader, ship pipeline, ~143 migrations) for no modularity win, with an upside-down risk profile (long no-ship window → big-bang cutover) for a bootstrapped, ship-small, AI-first project ([01 §5](../design/modular-architecture/01-architecture.md)).
+- **Coarse config A (~5 units, ADR 0080-as-written) — partially adopted as the *first* step, not the destination.** Proves the loader cheaply, but leaves ~70% of code a blob so AI-scoping barely improves. We ship A then peel medium ([02 §3](../design/modular-architecture/02-module-map.md)).
+- **Fine config C (~22+ units, a module per route-group) — rejected.** Fights cohesion (tasks/claims/credits belong together), manifest sprawl, over-engineered for a small team. "As modular as the evidence supports, no finer."
+- **Nx / Turborepo / Bazel / workspaces — rejected (for now).** Adds a build/link step for dependency-tree + caching benefits a single-process no-bundler app doesn't need ([00 §8](../design/modular-architecture/00-research-report.md)). In-repo `modules/<key>/` + a manifest + the existing `fitness.js` is the right lightweight choice; `eslint-plugin-boundaries` is the documented escape hatch if import-graph checks outgrow `fitness.js`.
+- **In-process plugin sandboxing — deferred (the standard call).** First-party modules are trusted for *process safety*; the boundary that matters (**authz**) is enforced by composition (the loader owns the mount + wraps every entry behind auth the module can't remove) and fitness — *stronger* than Backstage/VS Code treat first-party plugins. True process isolation is the future fork for untrusted modules ([00 §4b](../design/modular-architecture/00-research-report.md)).

package/docs/adr/0084-auto-derived-per-task-rank-floor.md

@@ -0,0 +1,86 @@
+# 0084 — Auto-derived per-task rank floor (every task is rank-scoped; the claim gate bites)
+
+- **Status:** Accepted
+- **Date:** 2026-06-23
+- **Deciders:** Lars (Archon), Claude
+
+## Context
+
+Builders must not be able to claim tasks above their rank, and every task should
+carry a deliberate rank criterion (Lars's directive, 2026-06-23). The *mechanism*
+for the gate already existed and was sound: `tasks.requires_rank` (V3.R82, migration
+044; widened to include `thetes` in 068) plus a claim-time check in `db.claimTask` /
+`claimTasksBatch` (`rankAllowsTask` → `INSUFFICIENT_RANK` 403) and a belt-and-braces
+filter in `listClaimableTasks` that hides over-rank tasks from `/builder-start`.
+
+But the gate never bit. Nothing ever *set* `requires_rank`: `POST /tasks` didn't
+accept it, `createTask` didn't write it (so the column took its `NOT NULL DEFAULT
+'xenos'`), `PATCH /tasks/:id` couldn't edit it, and the planning-session skill never
+emitted it. Net effect: essentially every task sat at `requires_rank='xenos'` — the
+floor — so any builder at `thetes` or above could claim anything. The column was
+inert; the gate guarded nothing. The hall didn't even display a task's required rank.
+
+## Decision
+
+We will make a task's rank floor **auto-derived, always-set, overridable upward, and
+visible**, and backfill the existing board.
+
+- **Derive** the floor from what a task touches plus its sensitivity, reusing the
+  *same* protected-path matcher the trust boundary uses
+  (`permission-path-check.matchProtected`, ADR 0043).
+  `deriveRequiredRank(touches, securitySensitive)`: `security_sensitive` OR any touch
+  hitting a `PROTECTED_GLOB` ⇒ `metic`; everything else ⇒ `xenos`. One source of truth
+  for "this is sensitive" — the rank/authz/ship-grade/deploy/migration core (exactly
+  the paths a sub-Metic builder already cannot push to) floors at Metic; game / art /
+  docs / UI work stays open. The rule **never auto-assigns `archon`** — "only the
+  Archon may claim this" is a deliberate human statement, not something to infer.
+- **Compose with an override** via `highestRank(floor, requested)`: the stored
+  `requires_rank` is always `max(floor, requested)`. An explicit value (on create, or
+  via `PATCH /tasks/:id`, Archon-only) can only **raise** the bar; a request below the
+  derived floor is clamped up (fail-closed). Flipping `security_sensitive` on ratchets
+  the floor up in the same atomic UPDATE; it never lowers a floor (an Archon can PATCH
+  down to the derived floor explicitly if a task was over-gated).
+- **Backfill** (migration 145): every non-terminal task whose `requires_rank` is still
+  the `xenos` default rises to `metic` when it is `security_sensitive` or its `touches`
+  overlap the protected set. The SQL conditions are generated faithfully from
+  `PROTECTED_GLOBS` (all exact-file or dir-prefix, no wildcards), idempotent, raise-only.
+- **Surface** the floor as a pill on the builders-hall task card when it is above
+  `xenos`.
+
+## Alternatives considered
+
+- **Manual rank at scoping** (the planner picks per task; create requires it). Rejected
+  as the *primary* mechanism: it is exactly what silently failed — an optional field
+  nobody filled, so the whole board drifted to the floor. Discipline does not scale;
+  structure does. (Manual override *upward* is kept, on top of the derived floor.)
+- **Just raise the column default** (unset ⇒ gated higher). Rejected: crude — it would
+  gate trivial game/art work behind Metic and empty the newcomer/general queue,
+  inverting the intent. The sensitivity signal must come from the task, not a blanket
+  default.
+- **A second sensitivity list for ranks** (independent of the trust boundary). Rejected:
+  two lists drift — the SEC [#863](https://example.com/builders#/task/863) failure mode. Reusing `matchProtected` means the claim
+  floor and the git-push floor can never disagree.
+- **Auto-assign `archon` to the most sensitive paths.** Rejected: an `archon` floor
+  means only the owner can ever claim that task, which would starve the board; Metic is
+  the right "trusted working rank" floor, and `archon` stays a deliberate manual override.
+
+## Consequences
+
+- Every task now carries a deliberate, enforced rank floor; the existing claim gate
+  (`INSUFFICIENT_RANK`) and the `/builder-start` hide finally bite. The change is purely
+  in *setting* `requires_rank` — the enforcement code is untouched, and its tests
+  (`tests/rank_gate.mjs`) still pass, now extended with `deriveRequiredRank` /
+  `highestRank` cases.
+- The claim floor and the ADR 0043 git-push floor share one matcher, so a task a
+  sub-Metic builder could not push is also one they cannot claim — coherent by
+  construction.
+- The migration-145 SQL is a *snapshot* of `PROTECTED_GLOBS`; if a wildcard glob is ever
+  added, the historical snapshot will not change (new/edited tasks re-derive through the
+  JS helper, which is authoritative). The generator asserts no-wildcard to keep the
+  snapshot exact.
+- An Archon can still gate a task to `archon` by hand (`PATCH requires_rank=archon`) when
+  a task genuinely should be owner-only.
+- This is a trust-boundary-adjacent change (it sets the per-task claim floor); it rides
+  the gate-review hard floor (ADR 0043) and is Archon-authored. See
+  [`docs/canonical-permissions.md`](../canonical-permissions.md) (the per-task floor
+  section) for the mirror.

package/docs/adr/0085-remove-default-per-builder-spend-cap.md

@@ -0,0 +1,39 @@
+# ADR 0085 — Builders are uncapped by default (remove the default per-builder monthly spend cap)
+
+- **Status:** Accepted
+- **Date:** 2026-06-23
+- **Track:** internal
+- **Builds on:** [ADR 0016](<redacted>.md) (the Archon override stays server-enforced), [ADR 0054](<redacted>.md) (session token cost — the spend this cap measured)
+- **Reverses:** the default-cap half of GDS-V3 criterion **C3** (V3.R84, task [#302](https://example.com/builders#/task/302) — "per-builder monthly budget, Archon-configurable")
+- **Task:** [#1499](https://example.com/builders#/task/1499)
+
+## Context
+
+GDS-V3 criterion C3 (task 302) gave every builder a **month-to-date spend cap**: `cost_log` API/compute spend attributed to the builder since `date_trunc('month', now())`, compared against `builders.monthly_budget_usd`. When that column is `NULL` (the normal case), `classifyCostStatus()` fell back to a project-wide default of **$50/month**. At 100% the builder's `/me` `cost.level` flips to `'over'`, which **hard-blocks `/builder-ship` (before the grader runs) and the art pipeline**. An Archon could raise a specific builder's ceiling via `PATCH /builders/:id/budget`.
+
+The default was framed in-code as "catch a runaway, not ration normal work." In practice it did the opposite. The dominant entry in a builder's `cost_log` is `session:<redacted> — **the API cost of running the assistant to do the work itself** (auto-captured per [ADR 0028](<redacted>.md)). On Opus, a handful of real sessions costs more than $50:
+
+- Builder 95 (Jackson Rini), created 2026-06-22, hit `over` on day two: **$69.32 MTD across 5 interactive sessions** (largest single session $24.86) vs the $50 default. He was blocked from shipping anything — and every further session he ran to *try* to work pushed him deeper over, since the cost of working is itself the metered quantity.
+
+So the default cap blocked the exact activity it was meant to enable, and would stall **every** productive new builder within a day or two — a structural newcomer trap, not a runaway guard. The owner's directive: *"Builders should have no budget limitations. Remove the default spend cap entirely."*
+
+We considered fuller removal (delete the column, the override endpoint, and all blocking) but the owner chose to **keep a manual brake**: removing the *default* satisfies "no budget limitations" (no builder is capped unless someone deliberately caps them), while retaining the Archon override as a rarely-needed emergency stop on a genuine runaway — consistent with the project's $5K annual budget.
+
+## Decision
+
+**A builder with no explicit budget is uncapped.** `classifyCostStatus(spend, budget)` no longer falls back to a default:
+
+- `budget` is `NULL` / non-finite / `<= 0` → **uncapped**: returns `level: 'ok'`, `budget_mtd_usd: null`, `pct_used: 0`. Nothing blocks. The `DEFAULT_MONTHLY_BUDGET_USD = 50` constant is **removed**.
+- `budget` is a **positive number** (an explicit Archon override via `PATCH /builders/:id/budget`) → unchanged: `warn` at ≥80%, `over` at ≥100%, which still blocks ship + art. This is the manual brake.
+
+Spend is **still recorded and surfaced** — the per-builder `cost_log` rows, the `/public/cost-summary` dashboard, and the `/me` `cost` object are all unchanged. This ADR removes *blocking*, not *observability*; the $5K pool is still fully visible.
+
+No schema change (`monthly_budget_usd` stays; `NULL` now means "uncapped" instead of "use the $50 default"). The only behavioral surface is the pure `classifyCostStatus`; every consumer (ship.js, art `cost_ledger.py`, the CLI session ping, the hall banner) already keys off `level`/`budget_mtd_usd`, so they need no logic change — an uncapped builder simply never trips them.
+
+## Consequences
+
+- **Builders are unblocked by default.** No new builder stalls on their own session cost. Existing over-budget builders (e.g. Jackson Rini) are immediately unblocked with no operator action.
+- **The brake survives.** An Archon can still cap a specific runaway builder by setting a positive `monthly_budget_usd`; clearing it (`null`) returns them to uncapped.
+- **Cost stays honest.** Spend attribution, the savings ledger, and the public dashboard are untouched — we still see exactly where the $5K goes; we just don't gate work on it.
+- **Project-wide guards are unaffected.** The separate autonomous-fleet spend brake (`autonomy-gate.js`, `OTB_AUTONOMY_CEILING_USD`) and the art-pipeline `HARD_STOP_USD` ledger cap are independent mechanisms and remain in force.
+- **C3's intent narrows** from "every builder has a default ceiling" to "a ceiling is an opt-in, per-builder Archon tool." The onboarding drachmae/karma diagram note is updated to match.

package/docs/adr/0086-goal-scoped-work-hierarchy.md

@@ -0,0 +1,123 @@
+# 0086 — Goal-scoped work hierarchy: assign goals, not tasks
+
+- **Status:** Accepted (design recorded; build is task-pending via a planning session)
+- **Date:** 2026-06-23
+- **Deciders:** Lars (Archon), Claude
+
+**Builds on:** [ADR 0016](<redacted>.md) (server-enforced rank boundary), [ADR 0025](<redacted>.md) (structured criterion↔task link), [ADR 0043](<redacted>.md) (protected paths + rank floor), [ADR 0049](<redacted>.md) (`touches[]` advisory), [ADR 0062](<redacted>.md) (instance/host decoupling — the config-preset pattern), [ADR 0083](<redacted>.md) (modular architecture — "a task is scoped to a module"), [ADR 0084](<redacted>.md) (auto-derived per-task rank floor), [ADR 0015](<redacted>.md) (task dependencies + auto-promotion), [ADR 0054](<redacted>.md) (cost-plus reward).
+
+**Track:** `internal` (GDS / methodology — a Cloud Bongos platform capability).
+
+---
+
+## Context
+
+Today only the Archon can create or edit tasks — `POST /tasks` and `PATCH /tasks/:id` are both `requireRank('archon')` ([`src/bongos/routes/tasks.js`](../../src/bongos/routes/tasks.js)). Lower-ranking builders (`xenos`, `thetes`) can only **file ideas** into `idea_inbox`; they have no ability to shape their own work toward an objective.
+
+> **Update (2026-06-26, [ADR 0090](<redacted>.md)):** `POST /tasks` / `PATCH /tasks/:id` are now `requireRank('metic','archon')` — a *Metic* may author tasks directly. This ADR's goal-scoped, module-fenced authoring path (`POST /goals/:id/tasks`) is now the mechanism for **sub-Metic** ranks (`xenos`/`thetes`) specifically; everything below about the scope-subset wall and protected-path block is unchanged and still governs that path. Every task must be hand-authored by the owner first — a delegation bottleneck that wastes capable builders' judgment, and the opposite of the AI-first norm where agents do the building.
+
+Lars's directive (2026-06-23): **stop assigning individual *tasks*; assign *goals*.** A builder working toward a goal should be able to **author and organize their own tasks** beneath it — but only within a **module scope** they cannot exceed, and never in a way that lets someone "pick a goal and then create tasks that hack stuff."
+
+This slots directly into the modular architecture: [ADR 0083](<redacted>.md) Rule 5 already states *"a task is scoped to a module."* Goals are the mechanism that turns that rule into a **live, enforced permission** rather than a convention.
+
+The structure decided over a design session is a six-tier hierarchy — most of which **already exists** in the GDS. Only **Goal** is a genuinely new tier:
+
+| Tier | What it is | In the system today |
+|---|---|---|
+| **Project** | the instance itself (Example) | implicit (one project per install) — becomes a config preset |
+| **Version** | a scope phase that sets goals | ✅ `versions` |
+| **Goal** | a shared, module-scoped workspace | 🆕 **the one new tier** |
+| **Criteria** | the tests for "goal met" | ✅ `done_when_criteria` — re-parented version → goal |
+| **Task** | work fulfilling a criterion | ✅ `tasks` (link to criteria via `task_criteria`) |
+| **Sub-task** | a task broken down | ✅ `tasks.parent_task_id` (one level) |
+
+---
+
+## Decision
+
+**We will introduce a `goal` tier and reorganize work tracking into a six-level hierarchy — Project → Version → Goal → Criteria → Task → Sub-task — whose *structure* is a per-instance config preset (owner-set at onboarding) and whose *enforcement* is core. A goal is a shared, joinable, module-scoped workspace: joining it grants bounded authority to author tasks within the goal's modules, with scope set by a trusted rank and never self-granted.**
+
+### 1. The hierarchy is a configurable preset (onboarding)
+
+The tier set is host-configured, not hardcoded — the [ADR 0062](<redacted>.md) core/host pattern applied to the work model.
+
+- A new **`config/hierarchy.json`** (joins `branding.json` / `modules.json` as host config; loaded by a `hierarchy-config.js` mirroring `src/modules.js`) declares the tiers — names, order, and which tier carries **scope**, **membership**, and **criteria**. Example ships the six-tier preset above; the project owner fills/edits it **during onboarding**.
+- **v1 scope of "editable":** the standard tier set with owner-set labels, enable/disable, and which tier owns scope/criteria/membership. Fully *arbitrary* custom tier graphs are a later extension — explicitly not built now.
+
+### 2. The Goal tier (shared, module-scoped) + criteria re-parenting
+
+- **New `goals` table** — sits between `versions` and `done_when_criteria`. New (not `parent_task_id`: one-level, task lifecycle; not `done_when_criteria`: that *is* the criteria tier). Carries: `version_id`, `title`/`description`, **`scope_modules text[]`** (the wall), `status` (`open|achieved|archived`), `created_by`, `succeeded_by_goal_id` (rescope carry-forward).
+- **Goals are shared, not owned** — a new **`goal_members`** table (many builders ↔ one goal; `lead`/`member` roles). **Membership**, not a single assignee, is what grants bounded task authoring.
+- **Criteria re-parent under goals** — `done_when_criteria` gains a `goal_id` (backfill existing version criteria under a per-version default goal). A version is "done" when all its goals are achieved; the `/status` rollup becomes **Version → Goals → Criteria → Tasks** (extends [ADR 0025](<redacted>.md)).
+- **Tasks** gain `goal_id`; sub-tasks remain `parent_task_id`; a task fulfils a criterion via the existing `task_criteria` link.
+
+### 3. Bounded task authoring (membership grants it; the create-time gate)
+
+- **`POST /goals`** — `requireRank('metic','archon')`; **Archon-only when `scope_modules` includes a `protected` module.**
+- **`POST /goals/:id/join` / `leave`** — open join for normal goals; **joining a sensitive-scope goal needs Archon approval** (reuse the access-request pattern, [`access-requests.js`](../../src/bongos/routes/access-requests.js)).
+- **`POST /goals/:id/tasks`** — `requireBuilder` + an in-handler gate (the maneuverability grant), ordered + fail-closed: goal `open` and **caller is a member** (or Archon); version guards reused from `POST /tasks`; **scope subset** — every `touches[]` element covered by the goal's `scope_modules` globs (`touchesOverlap`, [`path-match.js`](../../src/bongos/path-match.js)); **protected-path block** — `checkPermissionPaths` ([`permission-path-check.js`](../../src/bongos/permission-path-check.js)) so a sub-Metic member cannot author a task touching the protected core; then `db.createTask` stamping `goal_id`. `POST /tasks` / `PATCH /tasks/:id` stay byte-identical (Archon-only) for ungoverned creation.
+- **Rank floor is auto-derived, not a bespoke cap.** Per [ADR 0084](<redacted>.md), a created task's `requires_rank` is auto-derived from its touches + sensitivity (`deriveRequiredRank` → `metic` for protected/sensitive, else `xenos`) and can only be raised. So a goal member need not (and cannot) self-set a rank that escapes their own gate — and a sensitive task auto-floors to `metic`, which a sub-Metic author could not claim. No new cap mechanism; this composes with the one that already exists.
+
+### 4. The scope wall (set by the planner, never self-granted; "ask to widen")
+
+- **New `src/bongos/module-scope-map.js`** — each module key → its path globs + a `protected` flag, for the full ~16-module roster from the [modular-architecture design](../design/modular-architecture/02-module-map.md). `protected: true` where globs intersect `PROTECTED_GLOBS` ([ADR 0043](<redacted>.md)) — the lifecycle/ship-pipeline, migrations, security, authz core. It **auto-tightens** as [ADR 0083](<redacted>.md) moves code into `modules/<key>/`, converging on that ADR's task→module affinity (where `touches[]` retires in favour of the module label + a ship-time diff⊆module check). The carve precedes the feature (Lars: "carve more modules first").
+- A goal's `scope_modules` is set by the assigner at planning time — the **one moment scope is defined**, which is precisely why it is **never self-granted**. Widening goes through a request a trusted rank approves (Archon for a protected module).
+
+### 5. Dependencies
+
+- **One polymorphic "blocked-until-done" edge** — a new `dependencies(from_kind, from_id, to_kind, to_id)` over `{task, goal, criterion}`; the existing `tasks.dependencies[]` (task→task) migrates in. "Done" = task/sub-task `shipped`, criterion `satisfied`, goal `achieved`.
+- **One enforcement point** — it resolves down to the existing **claim gate** ([ADR 0015](<redacted>.md)): claiming a task checks its own deps plus deps inherited from its goal/criterion; achieving/shipping a node auto-promotes its dependents.
+- **Cross-goal and cross-version is allowed** (Lars, 2026-06-23). A dependency is a **reference, not a grant** — it never widens module scope, so cross-module deps are safe; cross-goal deps become the visible coordination contract between two shared workspaces. Containment (the tree) is never a dependency; the graph is acyclic.
+
+### 6. Achievement (auto-flag → planner review → auto-achieve) + lifecycle
+
+- **Auto-flag.** When every task linked to a criterion has shipped, the server **auto-flags that criterion "met — pending review"** — deterministic, from the `task_criteria` links + ship status, no manual propose step (a `pending_review` flag; the existing `satisfied` bool is set on confirm).
+- **Planner reviews, obviously and triage-style.** Flagged criteria surface as a clear review queue, walked one-at-a-time via a new **`/goal-review` skill** that mirrors `/idea-triage` (confirm / reject / note). The **planner (Metic+)** confirms — resolving "who confirms" so the Archon is not in every goal's closing loop. (This re-ranks the existing criterion-satisfy route from Archon-only to Metic+.) Confirming a goal's last criterion **auto-flips the goal `open → achieved`**.
+- **Lifecycle / rescope.** `open → achieved → archived` (archived is re-openable). The same `/goal-review` cadence dispositions achieved goals (archive vs carry forward). At version rescope (next `/planning-session`), achieved goals are carried forward (`succeeded_by_goal_id`) or replaced — "previous or new" at each tier.
+- **`/planning-session` becomes the scope phase, levelled up:** it defines a version's **goals**, each with its **criteria** and **module scope** (and optional seed tasks/join policy), uploaded atomically as today; sensitive-scope goals get Archon sign-off there.
+
+### 7. How the boundary holds (reuse + defense-in-depth)
+
+The create-time gate sees only *declared* touches (advisory — git merge is the real collision detector, [ADR 0049](<redacted>.md)), so it is the first filter, **not** the enforcement boundary. The existing **ship-time gates remain authoritative on the real diff**: the grader's `permissionPathPrePass`/`routeRankPrePass` + `serverSideGuards` ([`grader.js`](../../src/bongos/grader.js)), the `gate-review` ESCALATE floor, and the post-push `main-audit`. A mis-declared task still cannot *merge* if its real diff hits protected paths. Two CI fitness checks ([`fitness.js`](../../scripts/gds/fitness.js)) guard drift: goal routes are pinned in `route-rank-check.EXPECTED_RANKS`, and the scope code must *import* `PROTECTED_GLOBS`, never re-declare it.
+
+### Deferred (explicit non-decisions)
+
+- **Rewards** — whether *achieving a goal* earns anything beyond the per-task cost-plus already paid ([ADR 0054](<redacted>.md)), and how any reward splits among a goal's members. The leaning is karma by default (budget-safe, since drachmae are real money) with contribution-weighted splits, but this is **not yet decided** and rides a follow-on.
+- **A sub-Metic builder joining a protected-scope goal** — letting a newcomer work *inside* the dangerous core under a tightly-scoped, Archon-granted goal amends the [ADR 0043](<redacted>.md) hard floor (and needs the ship-time gates to become goal-aware). Deliberately **last**, behind its own security-reviewed ADR. Until then, protected-scope goals require a Metic+ holder.
+- **An AI relevance / anti-hack judge** at create/claim time (reusing the grader subagent harness; advisory-first, flag-for-Metic, never hard-blocking a newcomer) — a later phase; the deterministic scope + protected-path gates ship first.
+
+---
+
+## The build plan (phases → planning-session tasks)
+
+Each phase ships independently; implementing tasks are created via `/planning-session` under the live internal version (a criterion cluster alongside the [ADR 0083](<redacted>.md) BV1 module work).
+
+| Phase | Delivers | Depends on |
+|---|---|---|
+| 1 · Carve + config | `module-scope-map.js` (roster + `protected` flags); `config/hierarchy.json` + `hierarchy-config.js` (preset, onboarding-edited) | — |
+| 2 · Goal entity | migration (`goals`, `goal_members`, `done_when_criteria.goal_id` + backfill, `tasks.goal_id`); `db.js` helpers; `/status` rollup through goals; join/leave + goal view + `?goal_id=` filter | 1 |
+| 3 · Bounded authoring | `goal-scope-check.js` (pure); `routes/goals.js` create gate; sub-tasks; fitness checks; abuse-matrix tests | 1, 2 |
+| 4 · Deps + achievement | polymorphic `dependencies` + claim-gate resolution; criterion auto-flag → `/goal-review` (confirm/reject) → goal auto-achieve; archive/reopen + rescope carry-forward; "ask to widen"; ideas-promote-to-any-tier | 2, 3 |
+| 5 · (own ADR) | AI relevance judge; sub-Metic membership in protected-scope goals | 3, 4 |
+
+---
+
+## Alternatives considered
+
+- **Reuse `parent_task_id` for goals (a goal = a parent task) — rejected.** One-level cap ([`hierarchy.js`](../../src/bongos/hierarchy.js)), wrong lifecycle (a goal is a standing grant, not shippable work that earns credit on ship), and a task has no place for scope or membership.
+- **Reuse `done_when_criteria` as goals — rejected.** That table *is* the criteria tier; overloading it with membership + a creation grant conflates "definition of done" with "who may do work." A goal *links to* criteria; it is not one.
+- **Single-owner goals — rejected** (Lars). Goals are shared workspaces; a single assignee would force mega-claims and block collaboration. Membership grants the authority; contribution (not membership alone) is what any future reward weights on.
+- **A bespoke per-task rank cap at goal-create — rejected in favour of [ADR 0084](<redacted>.md).** The auto-derived floor already prevents a member minting a task that escapes their gate; a second mechanism would be a second list that drifts (the SEC [#863](https://example.com/builders#/task/863) failure mode).
+- **Restrict dependencies to within a single goal — rejected** (Lars). Real dependencies cross goals; self-containment forces mega-goals or fakery. A dependency is only a reference, so cross-goal is safe and surfaces coordination.
+- **Hard-code the hierarchy / build a full tier-editor UI now — both rejected.** A config preset edited at onboarding (the [ADR 0062](<redacted>.md) pattern) is the right middle: configurable per instance without a heavy runtime editor.
+- **Open task creation to all ranks generally (no goal) — rejected.** That removes the scope wall entirely; the whole safety model is that authority is *bounded by an assigned goal's modules*, not granted by rank alone.
+
+---
+
+## Consequences
+
+**Positive.** Lower-rank builders gain real maneuverability (author + organize their own work) without weakening the trust boundary — authority is bounded by an assigned, module-scoped goal and enforced server-side. It fills [ADR 0083](<redacted>.md) Rule 5 and reuses almost everything (versions, criteria, tasks, sub-tasks, the protected-path matcher, the auto-derived rank floor, the dependency/auto-promotion engine, the access-request pattern, the idea-triage cadence shape). The "carve more modules first" map is also an ADR-0083 deliverable. Each phase ships independently and is individually revertible.
+
+**Negative / cost.** Schema changes to two core tables (`done_when_criteria` re-parenting under goals; `tasks.goal_id`) plus new `goals`/`goal_members`/`dependencies` tables and a criteria backfill — touches the lifecycle/`migrations` core, so those PRs ride the gate hard-floor and need owner sign-off (the boundary working as designed). The `/status` rollup, `/planning-session`, and the criterion-satisfy route all change. It is a deliberate **widening of the trust boundary** (sub-Metic builders can now create tasks), justified by the layered scope + protected-path + auto-rank-floor + ship-gate defenses; that widening is exactly why this is its own ADR.
+
+**Neutral.** The reward model and sub-Metic-in-protected-scope membership are deferred to follow-ons; until they land, behavior is conservative (no goal bonus; protected-scope goals need a Metic+ holder). The configurable hierarchy ships as a preset; arbitrary tier graphs remain a future fork, not foreclosed.

package/docs/adr/0087-bongos-app-architecture-and-handoff-contract.md

@@ -0,0 +1,49 @@
+# ADR 0087 — Bongos app architecture + the model-agnostic feedback handoff contract
+
+**Date:** 2026-06-26
+**Context:** Bongos App `BONGOS-V1` / criterion C4 (the feedback loop closes — capture lands in a coding agent), task [#1312](https://example.com/builders#/task/1312) (`BV1.R33`). Records the architecture the R01–R14 rungs built and pins the contract the three handoff paths (R12 [#1307](https://example.com/builders#/task/1307), R13 [#1308](https://example.com/builders#/task/1308), R14 [#1309](https://example.com/builders#/task/1309)) share. Builds on [ADR 0045](<redacted>.md) (the Dev Box desktop app, now absorbed), [ADR 0072](<redacted>.md) (signing posture), [ADR 0083](<redacted>.md) (the modular core), and the [ADR 0062](<redacted>.md) core↔host split.
+**Status:** Accepted.
+**Track:** `internal` (development system → the Cloud Bongos desktop app line; bongos succeeds the GDS as the primary builder surface after GDS-V4).
+
+## Problem — feedback has nowhere to land
+
+The whole point of the Bongos app is to shrink the distance between "I see something wrong on screen" and "a coding agent is fixing it." A builder records a short spoken walkthrough — *"this header is wrong, see the spacing, fix this"* — drawing on the screen as they talk. The app already turns that into a tight, model-agnostic `prompt.md` + a handful of screenshots (R06–R11). But a bundle sitting in `~/CloudBongos/feedback/` is inert. The missing half is the **handoff**: getting that bundle *into* a Claude session, reliably, across the two surfaces a builder actually uses (Claude Desktop and Claude Code) — without fighting the CLI's unreliable clipboard-image paste.
+
+This ADR records (a) the app's overall shape, and (b) the one contract all the handoff paths agree on, so a fourth path (Cursor, Codex, a future agent) can be added without redesign.
+
+## The architecture (what R01–R14 built)
+
+**One umbrella desktop app that absorbs the Dev Box app.** `bongos-app/` is the single signed Cloud Bongos desktop app ([#1298](https://example.com/builders#/task/1298)). The existing Dev Box app ([ADR 0045](<redacted>.md)) becomes a *module* of it rather than a sibling install — one Electron shell, one app-pairing auth (`~/.config/otb/gds-session.json`), one branded `/downloads` distribution, one in-app updater, one Apple Developer ID ([ADR 0072](<redacted>.md)). The result offers both the Dev Box switch and the new feedback toolbar.
+
+**A three-stage pipeline: capture → synthesize → handoff.**
+
+1. **Capture** (R04–R09) — a Zoom-style floating, click-through overlay toolbar over any target. Screen/window + mic capture (R06), a snapshot grabber (R07), freeze-frame markup (R08), and on-device Whisper transcription (R09). The three raw streams (word-timestamped transcript, timestamped frames, markup moments) are collected in the renderer.
+2. **Synthesize** (R10–R11) — `timeline.js` aligns the three streams onto one millisecond clock and runs a salience pass that escalates only the frames the speech points at (deictic words) or the user marked up; `bundle.js` assembles the aligned timeline into one deterministic, model-agnostic `prompt.md` + the escalated frame images, written to `~/CloudBongos/feedback/<id>/`.
+3. **Handoff** (R12–R14) — the three documented ways that bundle reaches a coding agent (below).
+
+**The Rung-3 capture floor; element-select deferred to V2.** V1 captures at the **visual** rung — pixels (screen region + frames + freeze-frame markup) plus voice. This is the robust floor: it works over *any* app on screen with no per-app integration, and needs only Screen-Recording + Microphone grants. Higher-fidelity **element-level reads** (resolving the actual UI element under the cursor via macOS Accessibility / a DOM bridge — the "rung-2" reads) are **deferred to V2**: the permission wizard (R05) requests Accessibility *lazily*, only when those reads land, never up front. Capturing pixels-not-elements is a deliberate V1 scope cut, not an accident — it keeps V1 universal and the permission ask minimal.
+
+**Bongos as the GDS successor.** The longer arc ([ADR 0072](<redacted>.md) track line): the Bongos app is where building moves *after* GDS-V4 — the feedback loop (see → say → ship) becomes the primary way an owner directs AI builders, with the GDS's task/claim/ship machinery underneath. This ADR is the first architectural record of that intent.
+
+## Decision — the model-agnostic handoff contract
+
+**A bundle is a self-contained directory; every image is referenced by absolute file path, never inlined.** That single rule is the contract. `~/CloudBongos/feedback/<id>/` holds `prompt.md` (a timestamped transcript walkthrough + the ask, with each screenshot referenced as `![caption](/abs/path.png)`) and the escalated frame images. Because the images are *paths*, the text prompt stays tiny (~5–11k tokens for a typical 1–3 min session) and **any** agent can open them with its own file-read — Claude Code's Read tool, Claude Desktop's drag-in, a future Cursor/Codex adapter. No base64, no decoding, no per-agent payload format. The full format is documented in [`bongos-app/README.md`](../../bongos-app/README.md).
+
+**One shared `latest` pointer; three readers.** Every write of a bundle (`bundle.js writeBundle`) records it as `latest` — an atomic `latest.json` pointer plus a best-effort `latest/` symlink — in `bongos-app/src/handoff.js`. All three handoff paths resolve "the newest bundle" through that one `resolveLatest()`, so they can never drift:
+
+1. **Claude Desktop — file-bundle + clipboard (R12).** A toolbar button copies `prompt.md` to the clipboard and opens the bundle folder; the user pastes the prompt and drags the images into the composer (Desktop accepts mixed text + images). A one-liner spells out exactly what to do. (`handoff.js` + the `feedback:produce` / `feedback:handoff-desktop` IPC in `main.js`.)
+2. **Claude Code — the `/feedback` slash command (R13).** Running `/feedback` shells `node scripts/gds/feedback-latest.js`, which prints the `prompt.md` body + the absolute path of every frame; Claude then `Read`s each path so the screenshots enter context. This sidesteps the CLI's unreliable clipboard-image paste — Claude reads the frames from disk, not from a pasted blob.
+3. **MCP — `get_latest_feedback` (R14, optional "direct" path).** A local, zero-dependency stdio MCP server (`bongos-app/src/mcp-server.js`, launched by `scripts/bongos-mcp.js`) exposes one tool that returns the prompt text + the screenshots' **file paths** (never base64 — inlining would blow the MCP tool-result size cap). Both Desktop and Code can pull the latest bundle hands-free once the server is registered. Optional/stretch for V1 — the file-bundle + `/feedback` paths already close the loop.
+
+### Why hand-rolled MCP (no SDK dependency)
+
+MCP's stdio transport is newline-delimited JSON-RPC 2.0. The four methods a single read-only tool needs (`initialize`, `tools/list`, `tools/call`, `ping`) are ~100 lines, so we implement them directly rather than bundle the MCP SDK into the Electron app. This keeps the app's install size + dependency surface flat ([CLAUDE.md §4](../../CLAUDE.md) cost discipline) and makes the server testable with no network and no extra install. v1 speaks protocol version `2024-11-05` (echoing the client's if it sends a known one) and advertises exactly the one tool.
+
+## Consequences
+
+- **Adding a fourth agent is an adapter, not a redesign.** A new target (Cursor, Codex) consumes the *same* bundle via the *same* `resolveLatest()` — the contract already says "prompt text + absolute image paths." The handoff layer is the seam ([ADR 0081](<redacted>.md)'s swappable-adapter pattern, applied to feedback).
+- **The `latest` pointer is the single source of truth for "newest bundle."** A reader never scans for itself unless the pointer is missing (then `resolveLatest()` self-heals by scanning for the newest dir with a `prompt.md`). `latest.json` is authoritative cross-platform; the `latest/` symlink is a convenience that may be absent on Windows without symlink privilege — readers never depend on it.
+- **`writeBundle` now has a side effect beyond writing the bundle** (it records `latest`). This is intentional and best-effort: a pointer failure is swallowed and never loses the bundle already on disk.
+- **Frames are paths everywhere, base64 nowhere.** Enforced by the bundle format (R11) and re-asserted by the R14 tool result + the test suite. The day an agent needs bytes, it reads the path — the cap-safe choice.
+- **Element-select is the headline V2 lift.** When rung-2 element reads land, the bundle gains structured element context *alongside* the pixels; the handoff contract (paths, not payloads) does not change.
+- **Budget: $0 new recurring cost.** Zero-dependency MCP, on-device transcription, local file bundles. The app rides the already-paid Apple Developer ID ([ADR 0072](<redacted>.md)).