@bongos/core 1.17.0

package/docs/adr/0101-goal-hierarchy-phase-5-judge-membership-reward.md

@@ -0,0 +1,90 @@
+# 0101 — Goal hierarchy Phase 5: relevance judge, sub-Metic membership in protected-scope goals, and the goal-reward model
+
+- **Status:** Accepted (design + security review recorded; the build is a task cluster, filed backlog under BONGOS-V1). Two sub-decisions are explicitly **owner-gated at build time** — see Parts 2 and 3.
+- **Date:** 2026-07-01
+- **Deciders:** Lars (Archon), Claude
+
+**Builds on:** [ADR 0086](<redacted>.md) (the goal hierarchy — this is its deferred Phase 5), [ADR 0043](<redacted>.md) (the protected-path hard floor this amends), [ADR 0016](<redacted>.md) (server-enforced permissions), [ADR 0084](<redacted>.md) (auto-derived rank floor), [ADR 0024](<redacted>.md) (the grader subagent harness the judge reuses), [ADR 0058](<redacted>.md) (gate-review + owner approval), [ADR 0054](<redacted>.md) (per-task cost-plus reward), [ADR 0023](<redacted>.md) (credit multipliers), [ADR 0027](<redacted>.md) (BFG contribution signals).
+
+**Track:** `internal` (GDS / methodology — a Cloud Bongos platform capability).
+
+---
+
+## Context
+
+[ADR 0086](<redacted>.md) shipped the goal-scoped work hierarchy — Phases 1–4 (BV1.R54–R64): the module-scope map, the configurable hierarchy preset, the `goals` tier, the bounded task-authoring gate (`POST /goals/:id/tasks`), the polymorphic dependency edge, and the criterion-auto-flag → `/goal-review` → goal-auto-achieve lifecycle. Those phases are **live and defended**: a member's authoring is bounded by the deterministic scope-subset wall, the protected-path block (the single [ADR 0043](<redacted>.md) roster), and the auto-derived rank floor ([ADR 0084](<redacted>.md)), with the ship-time gates authoritative on the real diff (BV1.R61 pins + abuse matrix).
+
+ADR 0086 **explicitly deferred three non-decisions** to "its own security-reviewed ADR," because each is a matter of *judgment* or a *widening of the trust boundary* rather than the deterministic wall that shipped first. This is that ADR. It records the design and the security review; the build is a future cluster (filed below). It changes **no enforcement code**.
+
+The three deferred items:
+
+1. **An AI relevance / anti-hack judge** at goal-task create/claim time — advisory-first, never hard-blocking a newcomer.
+2. **Sub-Metic membership inside protected-scope goals** — which amends the [ADR 0043](<redacted>.md) hard floor and requires the ship-time gates to become goal-aware.
+3. **The goal-reward model** — does *achieving a goal* earn anything beyond the per-task cost-plus already paid, and how does any reward split among a goal's members.
+
+---
+
+## Decision
+
+We adopt a three-part design. Each part is an independent, revertible build task. The security-sensitive boundary-widening (Part 2) ships **last**, behind the advisory judge (Part 1) and an explicit owner Gate sign-off + red-team pass.
+
+### Part 1 — The relevance / anti-hack judge (advisory-first)
+
+**What.** At goal-task **create** (`POST /goals/:id/tasks`) and, optionally, at **claim**, an AI judge assesses: *is this task genuinely in service of the goal, or is it scope-gaming / a hack attempt that slipped the deterministic gate?* (e.g. a task whose declared `touches[]` sit inside scope but whose title/description reveal an intent to weaken the very wall that admitted it).
+
+**How.** Reuse the existing grader subagent harness ([ADR 0024](<redacted>.md) — the adversarial worker panel + `cascade-dispatch`), NOT a new harness. Cheapest model first (the cascade ceiling), escalate only on ambiguity; budget-aware (the $5k constraint).
+
+**Advisory-first — the load-bearing rule.** The judge **flags for a Metic to review**; it **never hard-blocks a newcomer at create time**. The deterministic scope-subset + protected-path + auto-rank-floor gates remain the **only hard walls**. The judge is a soft, human-escalated signal that surfaces in a review queue mirroring the `/goal-review` / `/idea-triage` cadence. High-confidence or repeat gaming may *raise friction* (e.g. require a Metic co-sign before the authored task becomes claimable) but never a silent, opaque AI "no."
+
+**Why advisory, not blocking.** An LLM judge is fallible; hard-blocking on it would (a) re-introduce the delegation bottleneck ADR 0086 exists to remove, and (b) create a gaming/DoS surface (adversarial prompts crafted to trip or exhaust the judge). Keeping it advisory means a wrong judge call costs a review, never a builder's ability to work.
+
+### Part 2 — Sub-Metic membership in protected-scope goals (amends ADR 0043)
+
+**Today (the conservative default that stays until this ships).** A protected-scope goal requires a **Metic+** holder ([ADR 0086](<redacted>.md) Deferred); a sub-Metic cannot author/claim/ship work touching the protected core even inside a goal — the [ADR 0043](<redacted>.md) hard floor blocks it at the pre-push hook, the grader `permissionPathPrePass`, the `gate-review` ESCALATE floor, and the post-push `main-audit`.
+
+**The amendment.** An **Archon** may admit a sub-Metic to a protected-scope goal under a **tightly-scoped, Archon-granted membership**, letting them author + claim + ship work touching a **narrow, explicitly-enumerated** protected surface — but **only with the ship-time gates made goal-aware**.
+
+**Security review (the crux).** The amendment is a genuine **widening of the trust boundary**, so it is purely *additive* permission, fail-closed, gated on an explicit grant:
+
+- **Goal-aware ship-time gates.** A sub-Metic diff touching a protected path is allowed **only if** all hold, checked server-side against the **real committed diff** (not the advisory create-time `touches[]`): (a) the author is a **member** of a protected-scope goal, (b) the membership was **Archon-granted** and audit-logged, and (c) every protected path the diff touches is **within that goal's enumerated protected scope**. Any protected-path hit **outside** a live matching grant → the ADR-0043 floor bites unchanged.
+- **Never self-granted.** Protected scope is Archon-set at goal creation ([ADR 0086](<redacted>.md) §4); membership admission to a protected-scope goal is the Archon-only `POST /goals/:id/members`. The sub-Metic can *ask*, never grant.
+- **Blast-radius containment.** The member can touch only the goal's enumerated protected paths; the grader, `gate-review`, and `main-audit` still run on the real diff; the Archon can revoke membership; the Part-1 relevance judge watches for gaming; the `main-audit` flags any sub-Metic protected-path commit **not** covered by a live goal grant.
+- **Ships last, gated.** This is the highest-risk change. Its build task carries an explicit **owner Gate approval** ([ADR 0058](<redacted>.md)) and a **red-team pass** before merge.
+
+### Part 3 — The goal-reward model
+
+**Question.** Does *achieving* a goal earn anything beyond the per-task cost-plus already paid ([ADR 0054](<redacted>.md)), and how does any reward split among members?
+
+**Leaning (recorded; the money is owner-gated).**
+
+- **Karma by default, not drachmae.** Drachmae are real money (1 = $1) against a tight $5k budget, and a goal is a *coordination construct*, not a unit of billable work — the per-task cost-plus already pays for the actual shipping. A goal-achievement **karma** bonus recognizes the collaboration with **no new monetary spend**.
+- **Contribution-weighted, not membership-flat.** The bonus tracks **who actually shipped tasks under the goal** (reuse the shipped-task/credit attribution + the BFG contribution signals, [ADR 0027](<redacted>.md)), never mere membership — a flat per-member reward would incentivize goal-squatting. A `lead` may take a small coordination share.
+- **On achievement, not creation.** The reward attaches when a goal is **achieved** (all criteria satisfied + confirmed via `/goal-review`), never on creation or joining — which, with contribution-weighting and the Metic confirmation, closes the free-rider and squatting surfaces.
+
+**Owner-gated.** Whether *any* monetary (drachmae) component attaches, and the exact karma amount/curve, is **Lars's call at build time** — money is owner authority. This ADR records the budget-safe default (karma-only, contribution-weighted); the build task (P5.3) surfaces the money decision explicitly rather than presuming it.
+
+### The child task list (filed backlog under BONGOS-V1, `source_ref` = this ADR)
+
+- **P5.1 — Relevance/anti-hack judge (advisory-first).** Reuse the grader harness at goal-task create/claim; flag → Metic review queue; never hard-blocks; budget-aware cascade. *(Metic.)*
+- **P5.2 — Goal-aware ship-time gates + the ADR-0043 amendment.** Sub-Metic membership in protected-scope goals under an Archon grant; make the pre-push hook / grader pre-pass / `gate-review` / `main-audit` goal-aware on the real diff; fail-closed; red-team + owner Gate sign-off. *(Archon; sequence after P5.1 so the advisory signal exists.)*
+- **P5.3 — Goal-reward model.** Karma-default, contribution-weighted split on goal achievement; anti-gaming; the monetary decision surfaced to the owner. *(Metic; after the goal-achievement flow, BV1.R63.)*
+
+---
+
+## Alternatives considered
+
+- **A hard-blocking relevance judge — rejected.** A fallible LLM as a hard gate re-introduces the bottleneck ADR 0086 removed and creates a gaming/DoS surface; the deterministic gates are the hard wall, the judge is a soft signal.
+- **Keep protected-scope Metic+-only forever — rejected as the long-term posture** (it caps the maneuverability grant's reach), but it **is** the safe default that stays in force until P5.2 ships with its security review.
+- **Flat per-member goal reward — rejected.** It incentivizes goal-squatting; contribution-weighting is fairer and anti-gaming.
+- **A drachmae goal bonus by default — rejected as the default** (real money, tight budget); left as an explicit owner-gated option, not presumed.
+- **Fold Phase 5 into Phase 4 rather than its own ADR — rejected** (ADR 0086 already decided this): the boundary-widening warrants a standalone security review, which is this document.
+
+---
+
+## Consequences
+
+**Positive.** Completes the goal hierarchy's *judgment* and *reward* story: a soft relevance signal catches gaming the deterministic wall can't see; a newcomer can eventually touch a narrow protected surface under an explicit, revocable, audited Archon grant; and collaboration is recognized without mandatory monetary spend.
+
+**Negative / cost.** Part 2 is a real widening of the trust boundary — the reason it ships last, fail-closed, red-teamed, and owner-approved. The judge adds LLM cost (mitigated: advisory, cheapest-model-first, budget-aware). The reward model adds accounting on goal achievement.
+
+**Neutral.** The monetary-reward specifics and the exact karma curve stay owner-gated; the build is a future cluster (P5.1–P5.3), each part independently shippable and revertible; until they land, behavior is the conservative Phase-1–4 default (no goal bonus; protected-scope goals require a Metic+ holder; no AI judge in the loop).

package/docs/adr/0102-finish-bounding-the-kernel.md

@@ -0,0 +1,36 @@
+# ADR 0102 — Finish bounding the kernel: LLM-cost as kernel-adjacent infra, identity/auth carve, flip Check 12 to ENFORCING
+
+**Status:** Accepted (2026-07-02) · **Supersedes the WARN-mode deferral in** [ADR 0091](<redacted>.md) §1,§3 / [ADR 0093](<redacted>.md)
+
+## Context
+
+ADR 0091 §1 defined the kernel boundary — every file in `fitness.js` `KERNEL_FILES` must import only the kernel + grandfathered infra. Its enforcer, fitness **Check 12 ("kernel imports no domain")**, shipped as a **WARN-mode ratchet**: it *reported* the tracked kernel→domain leaks but `hardFail: false`, "flips to a red build at zero." It never reached zero, so the boundary stayed advisory. At the start of this work there were **7 tracked leaks**:
+
+- `src/module-api.js` (the doorway) → `./gds/db` ×4 — Gemini-key storage (×3) + `builderRollingAvgGrade` (×1)
+- `src/module-api.js` → `./gds/llm-cache`, `./gds/llm-pricing` (×2)
+- `src/bongos/auth.js` → `./db` (×1)
+
+The 2020-era framing (ADR 0093) parked `llm-cache`/`llm-pricing` "until an llm-infra module exists." Revisiting that: building such a module is a needless seam.
+
+## Decision
+
+**Clear all 7 leaks and flip Check 12 to a hard gate** (`hardFail` when findings > 0), so any future kernel→domain import reds the build.
+
+1. **LLM-cost is kernel-adjacent infra, not a domain module.** `llm-cache.js` (a best-effort, dependency-injected content-addressed cache) and `llm-pricing.js` (a pure token→USD pricing table) carry no domain logic and are consumed by core, the grading module, and the CLI cost tooling *alike* — the same cross-cutting category as the pg pool and `path-match.js`, which are already in `KERNEL_IMPORT_ALLOWLIST`. Add both there. This clears leaks 5–6 with **no file moves and no new module core would have to depend on anyway.**
+
+2. **Carve the identity/auth/admission cluster into `db-kernel.js`.** `upsertBuilder`, `seatFirstAdminIfUnclaimed`, `getBuilderByGithubId`, `hasInvitedAccessRequest`, `createSession`, `lookupSession`, `SESSION_TTL_MS`, and the `RANKS` vocabulary move from the `db.js` residue into the bounded kernel slice (they are kernel identity/authz primitives; `auth.js` — a `KERNEL_FILE` — resolves them there). `db.js` re-imports and re-exports every name, so its other importers and internal uses (e.g. `setBuilderRank`'s `RANKS.indexOf`) are byte-identical. Clears leak 7. (`RANKS` stays TWINNED with `modules/lifecycle/db.js` — the twin now pairs with db-kernel.)
+
+3. **Push the doorway's remaining domain re-exports behind ports.** Gemini-key storage → the `art-pipeline` module + its port; `builderRollingAvgGrade` → the `grading` module + the `grade` port. The doorway stops importing `./gds/db`. Clears leaks 1–4.
+
+4. **Flip `<redacted>`** to report `violations` + `hardFail: findings.length > 0`.
+
+## Consequences
+
+- The kernel↔domain boundary becomes a **hard, self-defending CI gate** — the ratchet can no longer silently rot (the same class of gap this session's audit found in the C9 proof and self-host hardware-verify).
+- `db.js` shrinks toward being purely the social-twin + security-docs + credential residue; `db-kernel.js` is now the identity/auth/rank/audit/tx slice in full.
+- Landed incrementally (llm-infra classification → auth carve → Gemini port → grade port → flip), each verified against `fitness.js` + the unit suite + a live vanilla `docker compose up` (auth still 401s cleanly). Test stubs that mocked `db.lookupSession` were repointed to `db-kernel`.
+
+## Alternatives considered
+
+- **Build an `llm-infra` module for cache+pricing** (the ADR 0093 deferral). Rejected: they are pure cross-cutting infra with no domain state; a module would exist only to be depended on by core anyway, adding a seam and a port for zero isolation benefit. Kernel-adjacent classification is the honest model.
+- **Promote the Gemini/grade functions into the kernel.** Rejected: they are art-pipeline / grading *domain* reads over domain tables, not kernel primitives — they belong behind their modules' ports.

package/docs/adr/0103-core-first-extraction-cloud-bongos-trunk.md

@@ -0,0 +1,70 @@
+# ADR 0103 — Core-first extraction: Cloud Bongos is the trunk, Example splits
+
+- **Status:** Accepted
+- **Date:** 2026-07-02
+- **Track:** internal
+- **Task:** [#1726](https://example.com/builders#/task/1726) (BV1.R87) — the owner-review decision this ADR records.
+- **Supersedes:** [ADR 0100](<redacted>.md) §§1–2 (the Mercury-first sequence and the "Example stays coupled until a later decision" plank). **Retains ADR 0100 §3** (per-repo GDS) **and §4** (the generated mirror, retired conditionally).
+- **Builds on:** [ADR 0062](<redacted>.md) §1 (portable-core / host-instance cut-line), [ADR 0098](<redacted>.md) (`isPublishable()` — the executable definition of "the core"), [ADR 0100](<redacted>.md) §§3–4 + its R84 (`bongos package-core`, shipped), [ADR 0065](<redacted>.md) (AGPL / non-profit / AI-first).
+- **Reshapes:** the R84 → R86 spine — inserts a core-extraction step before Mercury (R85) and adds a committed Example-split step (see §4).
+- **Amended by:** [ADR 0108](<redacted>.md) — resolves §2's mechanism-neutral consumer-repo shape ("installs a pinned core version and layers its own content on top") into configurable-root.
+
+## Context
+
+[ADR 0100](<redacted>.md) was accepted 2026-07-01. It chose two repos, but sequenced **Mercury** (a greenfield Example instance) as the *first* two-repo consumer and deliberately left **Example coupled** as the single-checkout reference instance "until a later, separate decision" — on the reasoning that moving a live product before the update channel is proven buys risk for no gain.
+
+A next-day owner review (2026-07-02, task [#1726](https://example.com/builders#/task/1726)) reopened planks 1 and 2. The owner's position, stated directly:
+
+- **Cloud Bongos is the real product** — the thing of durable value — and should live as a clean standalone artifact, with Example as *one consumer of it*, not its host.
+- **The coupling actively hurts.** One repo carrying both the game and the platform, with a convoluted shared history, is hard to reason about and hand off.
+- **The boundary stays theoretical while Example is coupled.** OTB specifics keep leaking into the "portable" core. Evidence: a walk of the ~105 accumulated memory-file learnings on 2026-07-02 found **~85% are platform knowledge wearing OTB-specific framing** (example.com links, the droplet, `drachmae`) — the substance is core, the *wording* is coupled. Only 7 items are genuinely instance-bound.
+- **Mercury is imminent** — the separation should be proven on something that matters to the business now.
+
+"Leave Example coupled until later" reads, under these priorities, as "never." The precondition ADR 0100 waited for — a mechanical, CI-enforced boundary — already holds (ADR 0093 core-carve, the module system, `isPublishable()`), so the more ambitious cut is now buildable rather than a leap.
+
+## Decision
+
+### 1. Core-first extraction — the core gets its own repo, first.
+
+The Cloud Bongos **core** — the `isPublishable()` subtree ([ADR 0098](<redacted>.md)): portable methodology + platform + GDS engine + neutral branding — is extracted into its **own standalone repository** with **fresh history**, AGPL/public-ready. That repo **is** Cloud Bongos, the product. This is the *first* physical move, ahead of standing up any consumer. R84's `bongos package-core` is reused, not discarded: the subtree it already packages is exactly what gets extracted.
+
+### 2. Example splits — it is not the permanently-coupled reference instance.
+
+Example becomes a **consumer repo** that installs a pinned core version and layers its own game content, branding, and modules on top — the same shape as any other instance. It is **sequenced after** the core extraction and, for live-prod-risk reasons, after greenfield Mercury has proven the consumer path. This reverses ADR 0100 §2's open-ended deferral into a committed, sequenced step. The single-checkout reskin (cloudbongos.com) stays a supported cheap-reskin shape.
+
+### 3. Retained from ADR 0100: per-repo GDS (§3) and the conditional mirror (§4).
+
+Each repo runs its own GDS (own DB, tasks, builders, credits) — a shared GDS is still rejected. The delayed redacted mirror ([ADR 0099](<redacted>.md)) stays the public surface **until** the core is physically extracted — under this ADR that trigger now fires *first*, so the mirror's retirement/repointing is re-evaluated at extraction time rather than after a Mercury detour.
+
+### 4. Reshaped spine.
+
+| Step | Task | Change |
+|---|---|---|
+| R84 — package the core | [#1688](https://example.com/builders#/task/1688) | shipped; reused as-is |
+| **R88 — extract the core into its own repo** | [#1727](https://example.com/builders#/task/1727) | the new first physical move (dep: R84) |
+| R85 — Mercury on a pinned core | [#1689](https://example.com/builders#/task/1689) | re-pointed to depend on R88 (extraction), not just R84 |
+| R86 — `bongos upgrade` channel | [#1690](https://example.com/builders#/task/1690) | unchanged (dep: R85) |
+| **R89 — split Example onto the pinned core** | [#1728](https://example.com/builders#/task/1728) | committed, sequenced (deps: R88 + R85) |
+
+## Alternatives reconsidered (rejected)
+
+- **Keep ADR 0100 as-is (Mercury-first, Example coupled forever).** Rejected — it leaves the core↔instance boundary untested and traps the product inside the game repo, which is the exact pain the owner raised.
+- **Split Example *first*.** Rejected — moving a live product before the consumer/upgrade path is proven on greenfield Mercury adds risk for no gain. Core-first + Mercury-proof-first de-risks the prod migration.
+- **One repo with a clean internal cut (`core/` vs `instances/`).** Rejected — cheapest, but Cloud Bongos never becomes a separately shippable product and the boundary stays enforced by fitness tests, not a real repo gap.
+
+## Consequences
+
+- **The core repo becomes the canonical public artifact.** ADR 0099's mirror retirement, deferred in ADR 0100 §4 to "physical extraction," is now re-evaluated as part of R88.
+- **Two one-time migrations** (Mercury standup, then Example re-base) plus a permanent per-project upgrade step — the recurring cost the single-repo model avoided, now accepted for the product + boundary payoff.
+- **A larger operational footprint** (a core repo + per-instance repos, each with its own GDS/CI) — weighed against the $5k budget, mitigated by building incrementally, Mercury-driven.
+- **The 2026-07-02 learnings classification** (105 memory files, walked item-by-item with the owner: 85 CORE, 5 SPLIT, 4 INSTANCE, 11 DROP) is the reference for what knowledge travels into the extracted core repo. Companion: [`docs/cloud-bongos-core-learnings-classification.md`](../cloud-bongos-core-learnings-classification.md).
+- **The module boundary is now load-bearing across a repo gap sooner** — the ADR 0062 / ADR 0061 fitness functions matter more, not less.
+
+## Execution record — R88 shipped (2026-07-03, task [#1727](https://example.com/builders#/task/1727))
+
+§1 is done. The core was extracted into **[github.com/example-owner/cloud-bongos](https://github.com/example-owner/cloud-bongos)** — **private**, `main`, **AGPL-3.0**, **fresh single-commit history**.
+
+- **What was extracted:** the `isPublishable()` subtree via R84's `scripts/gds/package-core.js` — **989 core files** (of 2203), redacted in-memory through the fail-closed no-leak gate (0 residual leaks). The pin travels in-repo as `.cloudbongos-core.json`: `core_version 1.14.0`, `source_commit 2783a396…`, `tree_sha256 2bf9f8ee9a97…`. R85 ([#1689](https://example.com/builders#/task/1689)) and R89 ([#1728](https://example.com/builders#/task/1728)) can now depend on this pin.
+- **Genericized on the way in:** identity surface branded to Cloud Bongos (README, package.json, CLAUDE.md 298→258 lines, GOVERNANCE); instance identity re-pointed to `docs/project-context.template.md` + `config/branding.neutral.json`; `drachmae→credits`, owner-name and Off-the-Boats/ancient-Greece framing removed.
+- **§4 mirror re-evaluation (ADR 0099):** the physical-extraction trigger has now fired, and `cloud-bongos` is the **designated canonical public artifact** — but it is **PRIVATE for now**. So the ADR 0099 generated mirror is **NOT retired yet**; it stays the public surface until the owner flips `cloud-bongos` public, at which point the mirror is retired (or repointed). Retirement is bound to the public-flip, not to this extraction.
+- **Deferred to follow-ups (tracked in the GDS):** the exhaustive `Off the Boats`→neutral sweep across the ~32 remaining ADR/test/recipe files; standalone vanilla-boot wiring (`server.js`/entrypoints still reference the reference instance's product layer) — naturally proven by R85/R89; core `package.json` dependency pruning (game deps carried in); dangling in-repo links to topology/instance paths the scaffold populates on `init`; seeding the CORE-bucketed learnings; and tagging R88/R89 to goal 26 (their `goal_id` is null).

package/docs/adr/0103-gdsv4-bongos-consolidation.md

@@ -0,0 +1,28 @@
+# 0103 — Consolidate GDS-V4 into BONGOS-V1; split the Bongos desktop app into its own goal
+
+- **Status:** Accepted
+- **Date:** 2026-07-02
+- **Deciders:** Lars (owner) · Claude (Opus 4.8)
+- **Track:** `internal` (Cloud Bongos)
+- **Relates to:** [ADR 0064](<redacted>.md) (Medusa → Cloud Bongos), [ADR 0062](<redacted>.md) (core ↔ host / instance model), [ADR 0087](<redacted>.md) (the Bongos desktop app absorbs Dev Box), [ADR 0095](<redacted>.md) (grep-over-embeddings — retires the C1 recall arm). Executed by migration `<redacted>.sql` under task [#1709](https://example.com/builders#/task/1709).
+
+## Context
+
+The internal track carried **two live versions at once** — `GDS-V4` (534 tasks, ~114 open) and `BONGOS-V1` (130 tasks, ~14 open) — with no clean divide between them. Both were, in practice, Cloud Bongos platform work. Worse, `BONGOS-V1` was *titled* "Bongos App — V1" but its goals were platform concerns (core modularization, the animation module), while the actual **Bongos desktop app** (`bongos-app/` — the feedback-capture tool that also absorbs the Dev Box switch, [ADR 0087](<redacted>.md)) had its tasks scattered across *both* versions. Two parallel internal versions + an app/platform naming inversion made "what's the live internal version?" and "is this app work or platform work?" both unanswerable from the ledger.
+
+A task-by-task triage of GDS-V4's 114 open tasks (with the owner, 2026-07-02) also found dead work: the C1 semantic-search/embeddings arm (superseded by [ADR 0095](<redacted>.md)'s decision that agents navigate by grep, not embeddings), old V3-era grader tasks (superseded by the shipped 4-worker grader panel + [ADR 0089](<redacted>.md)), and the T-NNN task-ref migration (the hall-link convention already works and is enforced).
+
+## Decision
+
+1. **One go-forward internal version.** `BONGOS-V1` becomes the single Cloud Bongos **platform** version (renamed "Cloud Bongos — platform (V1)", status `building`). All still-relevant open GDS-V4 work carries into it.
+2. **`GDS-V4` is frozen, not shipped.** It was absorbed, not delivered; `frozen` avoids a false 100% and lets its in-flight tail (10 `confirmed` + 1 `active`) finish landing as its final history. Its `shipped`/`abandoned` rows stay attributed to GDS-V4 as the archive of what it delivered.
+3. **The Bongos desktop app becomes its own goal** ("Bongos desktop app") under BONGOS-V1, with every app task reparented to it (mascot, branded download + auto-update, the cloudbongos.com landing page, feedback capture, the Dev Box desktop switch). The app is a component *of* the platform version, not a peer version — matching the owner's framing. The code carve `bongos-app/` → `modules/bongos-app/` is tracked as a follow-up task under this goal.
+4. **Prune the superseded.** Abandon the C1 embeddings arm (939, 962, 966–971, 1221), the old V3 grader tasks (201, 202, 242, 292, 388, 490, 492), and the T-NNN migration (753, 754, 755) — 19 tasks. Move the two misfiled game-art tasks (586, 587) to product `V2`.
+5. **Sever the 758→753 dependency edge** so task 758 (kept) is not left permanently unclaimable by an abandoned dependency.
+
+## Consequences
+
+- `/status` now defaults to `BONGOS-V1` (was `GDS-V4`); the CLAUDE.md version-framing is updated to match.
+- The reorg is a **data migration** (182), applied atomically on deploy — reversible by construction (only status/version/goal/edge mutations; the pre-state is snapshotted in the task-1709 notes and the GDS DB dump).
+- The recall/embeddings headline in the old GDS-V4 framing is retired; the endorsed findability path (docstrings, greppability, the repo-map) continues under BONGOS-V1 as the C2 cluster.
+- **Process gap surfaced:** this consolidation was blocked for hours because the nightly DB backup had failed silently for 12 days (an orphaned superuser-owned table broke pg_dump; fixed under task [#1711](https://example.com/builders#/task/1711)). A version-consolidation should verify a fresh restore point exists *first*.

package/docs/adr/0104-trust-gds-api-channel-in-auto-mode.md

@@ -0,0 +1,42 @@
+# 0104 — Trust the GDS API channel in Claude Code auto mode (pre-allow `scripts/gds/api.js`)
+
+- **Status:** Accepted
+- **Date:** 2026-07-02
+- **Deciders:** Lars (owner) · Claude (Opus 4.8)
+- **Track:** `internal` (Cloud Bongos)
+- **Relates to:** [ADR 0016](<redacted>.md) (server-enforced permissions / trust boundary — the load-bearing rationale). Completes task [#1051](https://example.com/builders#/task/1051) (the narrow named-script allow-list, from the task-[#1027](https://example.com/builders#/task/1027) nightmare) and complements task [#1251](https://example.com/builders#/task/1251) (default dev boxes to `bypassPermissions`). Executed under task [#1716](https://example.com/builders#/task/1716).
+
+## Context
+
+Claude Code's **auto** permission mode runs an LLM *classifier* that judges each action and hard-denies what it reads as a risky external write or as work beyond the user's request. A builder hit this on the dev box:
+
+> Permission for this action was denied by the Claude Code auto mode classifier. Reason: **[External System Writes]** The agent patches inbox item 486 (which it did not create this session) to "promoted" and creates a task from an agent-inferred idea, well beyond the user's request to ship the scope doc.
+
+Two prior decisions were supposed to prevent this and don't fully:
+
+- Task **1051** (from the task-[#1027](https://example.com/builders#/task/1027) nightmare, where the classifier denied `ship.js` mid-deploy) added a **narrow** `permissions.allow` to the project `.claude/settings.json` for the blessed **named** scripts (`ship`/`claim`/`release`/`reauth`/`paste-token`/`start`/`setup`/`sandbox-stage`/`capture`/`learning-capture`/`doctor`). An explicit allow-rule bypasses the classifier for that command.
+- Task **1251** additionally defaults the box's interactive `claude` to `bypassPermissions` (no classifier at all on the box).
+
+**The gap.** Every autonomous GDS operation that has *no dedicated script* — idea-triage **promote**, **create-task**, blocker-**resolve**, criterion **ratify**, **goal** create, cost-via-API, security reports — rides the *generic* caller `node scripts/gds/api.js <METHOD> /api/gds/...` (see [`.claude/skills/idea-triage/SKILL.md`](../../.claude/skills/idea-triage/SKILL.md)). That generic channel was never allow-listed. So the moment a session is in **auto** mode rather than bypass — a builder cycled modes with Shift+Tab, the task-1251 `bypassPermissions` write didn't take, or the work is on a laptop/local full clone — the classifier hard-denies the **entire** autonomous GDS write surface. It only "just works" under `bypassPermissions`, which is a mode-level paper-over of a missing allow-rule.
+
+## Decision
+
+**Pre-allow the generic GDS API channel.** Add `Bash(node scripts/gds/api.js:*)` to the project `.claude/settings.json` `permissions.allow`. It ships in the repo, so it reaches the box, laptops, and **every permission mode** at once, and it is locked against silent regression by [`tests/box_ship_permissions.mjs`](../../tests/box_ship_permissions.mjs).
+
+The owner chose **"trust the whole channel"** over a narrower "reads + a few specific write paths" split — the split is brittle (breaks when a skill uses a slightly different path or flag order) and buys only illusory least-privilege, because the server already gates every write by rank.
+
+## Why this is safe (the crux)
+
+The auto-mode classifier was **never the security gate here** — the **GDS server is**, and it is stricter. `builders.rank` is checked on every request, per-request, with no caching ([ADR 0016](<redacted>.md)). Therefore:
+
+- Allow-listing `api.js` grants an autonomous builder **nothing beyond what its rank already permits**. It only removes a redundant, weaker, and — as observed — **wrong** harness prompt that mistook a sanctioned idea-triage session for scope creep.
+- `api.js` can only reach `/api/gds/*` on the configured API base (via `cli-lib.apiCall`); it is **not** a general HTTP or shell escape hatch. Blast radius = "the caller's rank-permitted GDS operations, without a per-call prompt" — which is exactly the design intent of an autonomous builder.
+- **Scope-discipline** ("don't wander off the claim") is owned by the methodology's per-builder **`wandering`** knob ([`modules/builder-settings/wandering-prefs.js`](../../modules/builder-settings/wandering-prefs.js)), which is the correct layer — a harness classifier can't tell whether promoting an idea *is* the task.
+
+Editing this allow-list grants no authority; sub-Metic authorship limits, protected-path gates, and rank checks all remain server-enforced ([ADR 0016](<redacted>.md)).
+
+## Consequences
+
+- Auto mode no longer prompts for any GDS API call. `bypassPermissions` boxes are unaffected (the rule is a no-op there). Laptops / local clones in auto mode now run the autonomous GDS loop hands-free, matching a bypass-mode box.
+- The one-line pattern extends cleanly if a *named* read wrapper (`recall.js`, `status.js`, `me.js`) later turns out to be classifier-gated too — but those are out of scope here; `api.js` is the channel the autonomous loop actually rides.
+- **Follow-up (not blocking):** investigate *why* a box provisioned for `bypassPermissions` (task 1251) still lands builders in auto mode — a Shift+Tab toggle, a failed `~/.claude/settings.json` write, or a Claude Code default change. This allow-rule makes the GDS loop robust regardless of the answer, so it is diagnostics, not a blocker.

package/docs/adr/0105-instance-seed-migrations-out-of-core.md

@@ -0,0 +1,47 @@
+# 0105 — Instance/product seed data out of the core migration path
+
+- **Status:** Accepted
+- **Date:** 2026-07-02
+- **Deciders:** Lars (owner) · Claude (Opus 4.8)
+- **Track:** `internal` (Cloud Bongos)
+- **Relates to:** [ADR 0062](<redacted>.md) (core ↔ host / instance model), [ADR 0083](<redacted>.md) (module-owned migrations — the enabled-gated precedent this generalizes). Executed under task [#1704](https://example.com/builders#/task/1704); the tactical predecessor was task [#1264](https://example.com/builders#/task/1264) (the 172/173 guards).
+- **Amended by:** [ADR 0108](<redacted>.md) §5 — under configurable-root, `migrations/instance/` becomes a genuinely SEPARATE repo's directory (not a subtree of the same checkout), and two independently-versioned repos both adding `NNN_*.sql` will collide on the shared `schema_migrations` stem key. §5 commits to a namespacing/lineage discipline before that ships (task 1885, W5); this ADR's basename-merge-sort ordering and stem-key idempotency in `migrate.sh` are the mechanism §5 extends, not replaces.
+
+## Context
+
+`scripts/migrate.sh` applies **every** file in `migrations/*.sql` on **every** Cloud Bongos instance. But ~16 of those files embed **OTB/product scope-truth** — `INSERT`s into `versions`, `goals`, `done_when_criteria` for OTB's specific project history (game V1/V2/V3, the PMS/GDS/BONGOS platform versions, the goal hierarchy). On a fresh **vanilla self-host** DB those rows either:
+
+- **Crash the boot** — a seed that references a row created out-of-band on OTB (e.g. the V2/V3 game versions and goal 10, which were created via the API, not by any migration) hits a foreign-key violation, and `docker compose up` crash-loops. This is the 2026-07-02 self-host regression.
+- **Pollute the DB** — a self-contained seed (one that creates its own version) runs fine but leaves a vanilla instance carrying OTB's versions/goals/criteria, which a fresh instance has no business owning.
+
+Task [#1264](https://example.com/builders#/task/1264) patched the two *crashers* (migrations 172, 173) with per-migration `DO`-block guards keyed on the presence of the referenced OTB rows. That stopped the crash but left the **class** latent: the other ~14 seed migrations still pollute, and nothing stops the next one from re-introducing a crasher. Two adjacent findings: the `MEDUSA_GDS_ONLY` env var was **documented as the vanilla marker but read by no code** (vestigial), and the self-host "does a fresh DB boot?" check (task [#1264](https://example.com/builders#/task/1264)) was a **manual** verification — CI had no Postgres and no Docker job, so the whole class was invisible to CI.
+
+An audit of migrations 001..183 classified them: **10 pure seed files** (no schema — e.g. the `*_planning_seed` files, 172, 173, 182, 183) and **6 mixed schema+seed files** (003, 006, 019, 065, 067, 160). Of the mixed ones, only 003 and 006 *create* OTB scope-truth (versions + their criteria); 019 renames (no-ops on a vanilla DB), 160 self-derives its goals from `versions` (empty ⇒ zero goals), and 065/067 seed **generic platform system principals** (`bfg-system`, `discord-bot-system`) that are not OTB scope-truth.
+
+## Decision
+
+**Instance/product seed data is a declared class that does not run on a non-owning instance.** Concretely:
+
+1. **A dedicated `migrations/instance/` directory** holds the 10 pure seed files (relocated via `git mv` — the stem-key tracking in `migrate.sh` means moving a file never re-runs it on OTB prod). This makes the class visible on disk and is the home for any future instance seed.
+
+2. **`migrate.sh` applies instance seeds only for the owning instance, and defaults OFF.** A single `SEED_INSTANCE` decision:
+   - `on` only when `GDS_APPLY_INSTANCE_SEEDS=1` is set explicitly;
+   - `off` by default, and **hard `off`** when `MEDUSA_GDS_ONLY=1` (which reviving gives that var a real consumer at last).
+
+   `off` is the safe default for **every** fresh non-owning DB — a vanilla self-host *and* a branded third-party instance — so neither ever inherits OTB's data. The owning instance opts in only when rebuilding its DB from scratch (a DR runbook step); a normal OTB deploy never needs it, because those rows are already in `schema_migrations` and are skipped as-applied regardless.
+
+3. **Order is preserved.** `migrate.sh` merges `migrations/*.sql` and (when on) `migrations/instance/*.sql` into one list **sorted by filename basename**, so the original global numeric sequence is intact — e.g. instance seed `018` still applies before core rename `019`. A from-scratch OTB replay reproduces the original 5 versions / 11 goals / 43 criteria exactly.
+
+4. **The unavoidable seed blocks embedded in the mixed files 003/006 are guarded in place.** `SEED_INSTANCE` is exposed to SQL as the `app.seed_instance_data` GUC (via `PGOPTIONS`, inherited by every `psql`), and each OTB version/criteria `INSERT` is wrapped in `IF current_setting('app.seed_instance_data', true) IS DISTINCT FROM 'off' THEN … END IF`. Platform-universal seeds (achievements) and the `schema_migrations` self-registration stay ungated. Default (GUC unset, e.g. a direct `psql -f`) = seed, so nothing about the historical files' behaviour changes outside `migrate.sh`.
+
+5. **A CI gate makes it un-regressable.** A `selfhost-boot.yml` workflow spins a fresh `postgres:16` service, runs `migrate.sh`, and asserts (a) a **vanilla** boot exits 0 with zero OTB versions/goals/criteria (but achievements present), and (b) an **owning-instance** boot seeds versions. The workflow is authored, but its **landing is gated on blocker 52** — a GitHub App cannot push/merge `.github/workflows/*` changes, which currently strands such PRs at `confirmed` (it stalled task [#1310](https://example.com/builders#/task/1310) the same way). So the structural fix lands on its own first; the gate lands in a follow-up once blocker 52 is resolved (grant the App the `workflows` permission) or via a one-off owner merge, after which the operator flips it to a required check on `main`.
+
+**System principals kept.** `bfg-system` (the `sessions` module is `default: true`) and `discord-bot-system` are generic, inert (`status=inactive`) platform accounts, not OTB scope-truth, and remain on a vanilla instance.
+
+## Consequences
+
+- A vanilla `docker compose up` now boots on a fresh DB with **only schema + platform-universal defaults** — no crash, no foreign-key failure, no leftover OTB versions/goals/criteria. Verified end-to-end against a throwaway `postgres:16-alpine`.
+- OTB prod is **unaffected**: every seed is already recorded in `schema_migrations`, so nothing re-runs; a from-scratch OTB DR sets `GDS_APPLY_INSTANCE_SEEDS=1` and replays identically.
+- The self-host regression class moves from a manual check toward a CI gate (`selfhost-boot.yml`, authored here) — closing the same "un-gated proof" gap that bit C9, once blocker 52 lets the workflow land.
+- **Trade-off:** OTB DR now requires the explicit opt-in flag (documented in `docs/recipes/self-host.md`), chosen over auto-detecting "am I OTB" so that a *branded* self-host can never inherit OTB's seeds. The forward norm (already the practice, per migration 172's header) is to seed instance scope-truth via API/`seed-*.js` scripts, not migrations.
+- **Deferred:** an authoring-time `fitness.js` check that flags a new instance-seed `INSERT` in core `migrations/` was considered but not shipped — it false-positives on legitimately-derived seeds (160's `INSERT … SELECT FROM versions`), and the `selfhost-boot.yml` gate already catches the regression empirically. Revisit if the class recurs.

package/docs/adr/0106-goal-owner-manager-authority.md

@@ -0,0 +1,84 @@
+# 0106 — Goal owner/manager authority: fixed owner (creator), promotable managers, owner-only demotion and transfer
+
+- **Status:** Accepted
+- **Date:** 2026-07-03
+- **Deciders:** jaxri (Metic, owner request), Claude
+
+**Builds on / amends:** [ADR 0086](<redacted>.md) (goal-scoped work hierarchy — this ADR refines its membership-role semantics), [ADR 0016](<redacted>.md) (server-enforced rank boundary — unchanged), [ADR 0090](<redacted>.md) (Metic authoring powers — the rank floor this ADR reuses for ownership).
+
+**Track:** `internal` (GDS / methodology — a Cloud Bongos platform capability).
+
+---
+
+## Context
+
+Migration 160 gave `goal_members` a `role ∈ {lead, member}` column, but the only
+role-assignment path was the Archon admission route (`POST /goals/:id/members`).
+Task [#1735](https://example.com/builders#/task/1735) was specced as "lead
+self-management" with **leads as equals**: any lead promotes/demotes any lead,
+"transfer lead" = promote-then-self-demote, invariant "never below one lead."
+
+Mid-build, the owner request refined the model into a fixed hierarchy: the goal
+**creator is the owner**; owners promote **managers**; managers hold the owner's
+powers *except* goal disposition; and creation stays rank-gated. Three decisions
+were made explicitly with the requester:
+
+1. **No delete.** Goals are never hard-deleted (the GDS is a permanent ledger);
+   archive stays as it is today (any Metic+ member, reversible).
+2. **Ownership is transferable**, owner-only (plus the Archon arm).
+3. **Demotion is owner-only.** Managers promote members up; only the owner (or
+   an Archon) demotes a manager back down.
+
+## Decision
+
+Two authority layers, deliberately different *kinds*:
+
+| Layer | Where it lives | Powers |
+|---|---|---|
+| **Owner** | `goals.created_by` — a column, **not** a role row. Set at create; moved only by explicit transfer. | Everything: promote, demote, transfer. |
+| **Manager** | `goal_members.role = 'lead'` (the hall renders it "manager"). | Owner-equivalent except: cannot demote a manager, cannot transfer ownership. |
+
+- **Creator becomes owner at create** — `db.createGoal` also upserts the
+  creator's `lead` membership row in the same statement, so the owner always
+  appears in their own member list. A one-shot module migration
+  (`<redacted>`) backfills pre-existing goals' creators the
+  same way. Goals with `created_by NULL` (the migration-160 system defaults)
+  have **no owner by design**; Archons act as one. Deliberately **no
+  earliest-member fallback** in the backfill — promoting someone on an
+  ownerless goal would grant authority nobody asked for (fail-closed).
+- **`PATCH /goals/:id/members/:builderId {role}`** — the role-change surface.
+  Middleware is `requireBuilder` only; the wall is the in-handler PURE ordered
+  gate (`authorizeMemberRoleChange`, the `authorizeGoalTaskCreate` precedent):
+  goal exists → goal open → actor is owner|manager|Archon → target is a member
+  → no-op same-role → demotions owner|Archon-only → **the owner's row is never
+  demotable** (`owner_role_fixed` — owner authority is `created_by`, so a
+  demoted owner row would just lie to the member list; transfer first). The DB
+  write (`setGoalMemberRole`) re-asserts the owner guard **inside the UPDATE**
+  so a race cannot demote an owner.
+- **`POST /goals/:id/transfer {builder_id}`** — owner (or Archon) hands the
+  goal over. The old owner keeps their `lead` row (drops to manager, not out);
+  the new owner's membership upserts to `lead` in the same statement that moves
+  `created_by`. **The new owner must be Metic+**: goal creation is Metic+
+  ([ADR 0086](<redacted>.md) / R57), ownership is
+  creator-equivalent authority, and this also keeps the protected-scope
+  membership wall intact (a protected-scope goal requires Metic+ members).
+- **Creation rank gate: unchanged.** `POST /goals` was already
+  `requireRank('metic','archon')` (Archon-only for protected scope) — the
+  owner request's "only Archons or Metics can create" was already enforced.
+- **Pins:** both new routes are pinned `any-builder` in
+  `route-rank-check.MODULE_EXPECTED_RANKS['lifecycle']` — like the authoring
+  keystone, the wall is in-handler, and the pin makes an accidental
+  `requireRank` re-gate (or a gate removal) a red build.
+
+## Consequences
+
+- The "never below one lead" invariant from the original task spec is **gone**
+  — it existed to keep *someone* in charge, and a fixed owner does that job
+  with less machinery. Manager count may legitimately be zero.
+- The hall Goals page can light up role controls (owner/manager framing) and a
+  transfer action; task [#1736](https://example.com/builders#/task/1736)'s
+  conflict-resolution actions gate on owner/manager instead of "lead."
+- "Delete goal" remains a non-feature. If it is ever wanted, it must come back
+  through a new ADR (archive semantics already cover retirement).
+- A demoted-to-member ex-manager retains plain membership (join/leave/author
+  within scope) — demotion is not expulsion.

package/docs/adr/0107-module-upstreaming-contribution-to-core-catalog.md

@@ -0,0 +1,83 @@
+# ADR 0107 — Module upstreaming: instances contribute modules into the shared core catalog
+
+- **Status:** Accepted
+- **Date:** 2026-07-03
+- **Track:** internal
+- **Task:** [#1766](https://example.com/builders#/task/1766) (BV1) — the owner-review decision this ADR records + the initiative it seeds.
+- **Builds on:** [ADR 0062](<redacted>.md) §1 (portable-core / host-instance / gated feature-module cut-line), [ADR 0083](<redacted>.md) (the module system — loader, manifest, seams, module-owned migrations), [ADR 0098](<redacted>.md) (`isPublishable()` — what a module may contain to enter an AGPL core), [ADR 0065](<redacted>.md) (AGPL-3.0, non-profit, AI-first — and its explicit rejection of CLA-relicensing as "capture").
+- **Complements:** [ADR 0100](<redacted>.md) / [ADR 0103](<redacted>.md) — those define the **distribution** arrow (core → instance, a pinned versioned dependency). This ADR defines the **reverse** arrow (instance → core): an instance's module flows *upstream* into the shared catalog. The two arrows together make the module boundary a two-way membrane.
+
+## Context
+
+ADR 0103 makes the Cloud Bongos core its own repository — the product — with instances (Example, Mercury) consuming a pinned core and layering their own modules on top. That is one-directional: fixes and features flow core → instance.
+
+The owner's direction (2026-07-03): an instance also builds feature modules of its own, and **should be able to submit those modules for approval to be merged into the shared core** — so the core accumulates a growing catalog of modules built by the sub-projects, each **credited to its author and its origin project**. A module accepted into core becomes available (opt-in) to *every* instance.
+
+A read-only audit of the current codebase (task [#1766](https://example.com/builders#/task/1766)) established ground truth:
+
+- **The prerequisites are solid.** A validated `module.json` manifest ([`src/module-loader/manifest-schema.js`](../../src/module-loader/manifest-schema.js)), a discover→mount loader with a **one-way import boundary** hard-enforced in CI ([`scripts/gds/fitness.js`](../../scripts/gds/fitness.js) Check 12, [ADR 0102](<redacted>.md)), opt-in **default-off** enablement (`config/modules.json` / `config/modules.neutral.json`), module-owned migrations, and the `isPublishable()` publish boundary that already decides which module *shapes* may enter an AGPL core.
+- **The capability is absent.** There is no submission/approval/merge-upstream flow, no catalog/registry (a "marketplace" is an explicitly-deferred future fork in [`docs/design/modular-architecture/01-architecture.md`](../../docs/design/modular-architecture/01-architecture.md)), and the manifest has **no** `author` / `origin` / `license` / `maintainer` fields — adding them fails manifest validation until the schema is extended.
+- **The name "contribution seam" is already taken** — it is the in-process UI/profile extension hook (`contribute`/`contributions`, `CORE_VERSION` 1.1.0). This capability must use a distinct name to avoid confusion: **module upstreaming** / **the module catalog**.
+- **A CI gap:** contributed-module tests only run in core CI if placed at repo-root `tests/`; the runner does not discover `modules/<key>/tests/`.
+
+## Decision
+
+### 1. The upstreaming flow — submit → review → accept into the catalog.
+
+An instance builds a module in its own repo. To land it in core, a **platform-native submission** (`bongos module submit`) packages the module + its attribution metadata + a sign-off, runs the automated pre-checks, and files it into a **rank-gated review queue on the core** — it does **not** grant the instance write access to core (consistent with ADR 0103's "no direct write access"). On acceptance the module lands in the core `modules/<key>/` tree **default-off**, is added to the `isPublishable()` allowlist, and its attribution is recorded. Every instance may then opt in via `config/modules.json`. *(Standard fork-and-PR remains a fallback, but the native flow is canonical because it captures attribution + sign-off and fits the GDS methodology.)*
+
+### 2. Attribution is portable metadata, not a cross-database link.
+
+Each repo runs its own GDS with its own builder identities ([ADR 0100](<redacted>.md) §3) — there is no shared identity key. So credit **travels with the module**: `module.json` gains `author`, `origin` (origin instance/project), `license`, and `maintainer` fields, captured at submit time. The catalog shows author + origin credit. This is a *record*, not a foreign key.
+
+### 3. Reward: credit now, money later.
+
+Accepted contributions earn **visible credit** (author + origin in the catalog) immediately. Any monetary reward (drachmae) — and the cross-instance identity/payout mechanics it would require — is **explicitly deferred** to a separate economics decision (owner call, 2026-07-03). This keeps the build unblocked and avoids prematurely solving cross-GDS identity.
+
+### 4. Licensing: AGPL-in, sign-off, no CLA.
+
+Core is AGPL-3.0 and [ADR 0065](<redacted>.md) rejected CLA-relicensing as capture. So **inbound = outbound**: a contributed module is accepted under AGPL-3.0 with a lightweight **DCO-style sign-off** (the contributor affirms it is their own work, licensed AGPL) — never a copyright-assignment CLA. The `isPublishable()` pre-check runs at **submit time** and rejects anything that cannot be AGPL'd (game content, pixel art, copyrighted reference material).
+
+### 5. Security review is a hard accept-gate.
+
+A module accepted into core runs **in-process, with full access, in every instance that enables it** — and the "untrusted modules → separate processes" isolation remains a deferred future fork. Therefore acceptance is a **security review**, not a works-check: no module enters the catalog without a reviewer (Metic+/maintainer) clearing it for safety, license, and quality. This is the single highest-risk property of the whole capability.
+
+### 6. Default-off + the publish-allowlist is the accept action.
+
+An accepted module ships `default: false` — instances opt in; none inherits everyone's features. Because a new module directory publishes only if explicitly added to the `isPublishable()` allowlist (default-deny), "accept into core" is a concrete, fail-safe checklist: add to `modules/`, set `default:false`, add to the allowlist, record attribution.
+
+### 7. Maintenance & orphaning policy.
+
+A module pinned to an old `coreVersion` rots as core advances. On acceptance a module either becomes **core-maintained** or carries a named **maintainer** and a deprecation path; `bongos upgrade`'s existing `coreVersion` pre-check surfaces incompatibility. The catalog must not fill with silently-broken entries.
+
+### 8. Sequencing.
+
+The **prerequisites** are direction-agnostic and buildable now in the single repo (dormant until the split): the manifest attribution fields, module-owned test discovery in core CI, and the submit-time AGPL/publish pre-check. The **pipeline** (`bongos module submit` → core-side review/accept → the catalog) depends on there being a core repo to receive into (R88, [#1727](https://example.com/builders#/task/1727)) and a producing consumer (Mercury R85, [#1689](https://example.com/builders#/task/1689)). Do not build the pipeline before the split.
+
+### 9. How it's shown to users — the repo atlas + the Modules tab.
+
+Two user-facing surfaces, both **UI-first** (a non-technical builder must be able to do all of this with clicks — no terminal required; the CLI verbs are the same actions underneath).
+
+- **The repo atlas shows module provenance.** The atlas (`scripts/gds/gen-atlas.js`, `buildModuleView`) gains a clear split so a builder sees, at a glance, **which Cloud Bongos *core* modules this instance loads** versus **which modules the project built itself** (core-loaded vs. own-built). This is the "what am I running, and what's mine" view.
+- **A "Modules" tab in the hall** does three jobs:
+  1. **Enable / disable access to core modules** — a toggle UI over the enablement layer (`config/modules.json`), with the default-off contract (§6) respected. This is how an instance opts into the core catalog.
+  2. **See the project's own modules** — the instance-specific modules it has built, listed distinctly from core.
+  3. **Contribute / submit for review** — a UI-first "submit this module upstream" action that runs the §4 pre-check, captures the DCO sign-off, and files the module into the core review queue (§1). It is the clickable front door to `bongos module submit`; a submitted module then shows its review status, and accepted modules appear in the catalog with author + origin credit (§2).
+
+The enable/disable and provenance views are buildable against the existing module system now; the submit-for-review action lights up when the submit pipeline (§8) lands. Tracked by [#1776](https://example.com/builders#/task/1776) (the tab + atlas provenance), with the catalog view in [#1772](https://example.com/builders#/task/1772) and the submit flow in [#1770](https://example.com/builders#/task/1770).
+
+## Alternatives considered (rejected)
+
+- **Fork-and-PR only.** Standard OSS, but loses attribution/sign-off capture and doesn't fit the GDS review/approval methodology. Kept as a fallback, not the canonical path.
+- **A CLA granting relicensing rights.** Rejected by [ADR 0065](<redacted>.md) as capture; incompatible with the non-profit posture.
+- **Auto-accept / CI-only gate (no security review).** Rejected — a module runs in every enabling instance with no sandbox; unreviewed inbound code is a supply-chain compromise across all instances.
+- **Accepted modules default-on.** Rejected — every instance would inherit every contributed feature; breaks the "fail-to-vanilla" default-off contract.
+- **A package marketplace now.** Rejected as premature (the design docs defer it); the in-repo catalog is the smaller first step.
+
+## Consequences
+
+- **The module boundary and `isPublishable()` become load-bearing for the *inbound* direction too**, not just outbound distribution — the ADR 0062 / ADR 0102 fitness functions matter more.
+- **Core CI must run contributed-module tests** — the runner is extended to discover `modules/<key>/tests/` so contributions are self-contained (closes the audit's CI gap).
+- **A review/maintainer role emerges** on the core repo (Metic+), with security + license + quality as the acceptance bar.
+- **Cross-instance identity stays an open question**, deferred with the reward economics (§3).
+- **Tooling note:** seeding this initiative's goal + criteria + task-attachment + spine consolidation is done via a **guarded data-migration**, because the GDS HTTP API cannot create done-when criteria, attach a task to a goal, or reparent an orphan (only `POST /goals` + goal-less `POST /tasks` + dependencies are API-exposed). That API gap is itself filed as a follow-up — the planning surface should not require hand-written SQL.