@bongos/core 1.17.0

package/docs/adr/0024-multi-agent-system-architecture.md

@@ -0,0 +1,125 @@
+# 0024 — Multi-Agent System (MAS) architecture
+
+- **Status:** Accepted — all phases shipped (Phase 4.5, autonomous background dispatch, shipped [#458](https://example.com/builders#/task/458); INERT until `OTB_AUTONOMY_ENABLED=1`). See *Phase plan & implementation history* below.
+- **Date:** 2026-05-29 (Phases 1–3); 2026-05-30 (Phases 4–5); Phase 6 + C7 followed.
+- **Deciders:** Lars Kristensen (Archon), Claude
+- **Track:** `internal` (GDS)
+- **Supersedes:** none. Extends [ADR 0010](0010-pms-architecture.md) (GDS architecture), [ADR 0016](<redacted>.md) (trust boundary), [ADR 0017](<redacted>.md) (economy lens — the first piece of the Grader's worker decomposition).
+
+## Context
+
+As the GDS opens to multiple builders, three structural risks scale faster than headcount:
+
+1. **The ship-time grader is lenient by construction.** [`src/bongos/grader.js`](../../src/bongos/grader.js) v2 (V3.R18 / [#209](https://example.com/builders#/task/209)) runs a *single* Opus subagent against the diff. Opus wrote the code; Opus grades it. Academic LLM-as-judge work (Zheng et al. 2023, Chiang & Lee 2023) consistently documents ~10–15% same-family inflation. The prompt asks "what score?" rather than "find what's wrong, then decide if it passes" — the default-to-pass framing is the bias. The recorded 14-day passing rate (65/75 = 87%) is suspiciously high for un-calibrated work.
+
+2. **Methodology hygiene is reactive.** Documentation drift, dead code, and architectural sprawl are caught (if at all) by `overnight-code-review` and `repo-simplify-sweep` — both downstream of merge, both advisory, both already overfilling. No upstream gate looks at the *system* the way the grader looks at the diff.
+
+3. **No standing entity watches the symphony.** Cron routines fire on a clock; skills fire when a builder remembers to invoke them. Nothing watches a builder's session in flight and dispatches the right specialist at the right moment.
+
+The user-proposed agent hierarchy (Conductor → Delegators → Workers) is a 3-tier orchestrator that names these gaps. The research literature (Anthropic's multi-agent research system, "Building Effective Agents" patterns, MetaGPT post-mortems) consistently shows 2-tier orchestration beats 3-tier in practice: deeper hierarchies amplify intent-loss between layers. The decision below collapses the proposal to 2 tiers while keeping the user's specialization intent.
+
+## Decision
+
+Adopt a **2-tier multi-agent architecture** with one persistent agent and three on-demand roles, building incrementally over six phases.
+
+### The cast
+
+```
+                       ┌──────────────────┐
+                       │    CONDUCTOR     │  persistent · Opus
+                       │  (UserPromptSubmit hook)
+                       │  watches triggers, suggests / dispatches
+                       └────────┬─────────┘
+                                │  proposes — never disposes (no new permissions; inherits builder rank)
+        ┌───────────────────────┼───────────────────────┐
+        ▼                       ▼                       ▼
+   ╔══════════╗            ╔══════════╗            ╔══════════╗
+   ║  GRADER  ║            ║ ARCHITECT║            ║   BFG    ║
+   ║ on /ship ║            ║quarterly ║            ║post-ship │
+   ╚════╤═════╝            ╚════╤═════╝            ╚════╤═════╝
+        │                       │                       │
+   ┌────┴────┬─────────────┐  audits → idea_inbox  CLAUDE.md ↔ reality
+   ▼         ▼             ▼                       memory graph hygiene
+HACKER    NARC      EFFICIENCY                     (no workers yet)
+red-team  completion MONGER
+                    cost/perf
+```
+
+**One persistent agent: the Conductor.** Implemented as a `UserPromptSubmit` hook in `.claude/settings.json`. Runs per builder turn. Inherits the builder's rank — no new authority. Output is advisory: it suggests `/builder-redteam` on security-sensitive edits, suggests Grader pre-flight before `/builder-ship`, dispatches BFG after doc edits, and so on. **Conductor proposes; the builder confirms.** Anything that touches a rank-gated route still goes through the existing DB-enforced check ([ADR 0016](<redacted>.md)) — the Conductor cannot grant or bypass authority.
+
+**Three invoked roles, summoned by trigger, not persistent:**
+
+- **Grader** (on `/builder-ship`). The ship-time gate. Phase 1 makes it strict (default-fail framing + cross-family Sonnet grading Opus's work + 3-shot unanimous-PASS); Phase 2 decomposes it into a worker panel: *Narc* (semantic completion — task description vs diff), *Quality* (code quality + advisory economy), *Hacker* (security red-team — wraps `/builder-redteam` as a CI gate), *Efficiency Monger* (runtime cost / hot-path performance). Unanimous-PASS gate; non-unanimous falls through to the manual-confirm release valve. Plus a deterministic route-rank pre-pass (C7).
+- **Architect** (quarterly cadence + Conductor nudge). Bounded-scope audits feed `docs/audits/<scope>-<date>.md` + `idea_inbox` seeds. Each quarterly audit becomes the foundational input for the next version's planning session. *No workers yet* — the Architect does its own work flexibly per the user's "delegators without workers do the work themselves" rule.
+- **BFG** (post-ship + pre-cron). Memory + index hygiene at its root — audits CLAUDE.md claims against DB reality, prunes stale references, verifies `[[links]]` resolve. **Widened in [ADR 0026](<redacted>.md) and now shipped (Phase 6 complete):** it also adds DB counter-vs-ledger drift checks (6A.2), scores builders + propagates transferable practice (6B), and operates the audited cross-builder memory WRITE path for dreams + transparent corrections (6C). *No grader-style workers — it does its own work (the "delegators without workers do the work themselves" rule).* Vector-store retrieval still deferred — the MEMORY.md graph + frontmatter suffices.
+
+### Why 2 tiers, not 3
+
+The user's original proposal had Conductor → Delegator → Worker. Three reasons to collapse:
+
+1. **Empirical.** Anthropic's multi-agent research system is deliberately 2-tier; their published numbers (90% improvement on breadth-first research, 15× tokens) are for that shape. No published multi-agent system the team has read about achieves better-than-2-tier coordination at scale.
+2. **Information loss.** Every hand-off between agents is a lossy translation of intent. Three hops compound. The Conductor → Worker direct path keeps intent intact.
+3. **The middle tier was a category error.** A "Delegator that has no workers does the work itself" is just a *Specialist* with a fancier name. Reifying the middle creates a permissions question (can a Delegator grant Workers powers it doesn't have?) and an attribution question (who gets the credit / blame?) that 2-tier sidesteps.
+
+The user's specialization intent is preserved: the Grader runs a worker panel; the Architect and the BFG do their own work (no grader-style workers) and can grow them if the "do it repeatedly → codify as worker" rule ever fires.
+
+### The Musk algorithm applied to the proposal
+
+Musk's 5-step engineering algorithm: (1) make requirements less dumb, (2) delete, (3) simplify, (4) accelerate, (5) automate — "if you're not adding 10% back, you didn't delete enough." Applied to the original proposal:
+
+- **Project Manager (deleted):** what the Conductor does. Reprioritization *is* conducting. Splitting it doubles the surface for no specialization.
+- **Janitor (deleted as standalone, merged into Architect):** cleanup is downstream of an architecture decision ("delete X"). The existing `repo-simplify-sweep` + `overnight-code-review` crons already cover the autonomous cleanup loop; the Architect's audit work *feeds* them.
+- **BFG vs Architect (kept separate):** boundary sharpened. BFG owns *current truth* (memory hygiene, live state). Architect owns *future structure* (forward-looking design, version-foundation audits). Distinct enough they won't fight over files.
+
+Reduced cast: **4 agents, not 6** (1 persistent + 3 invoked).
+
+**Grader strictness — strict-first, loosen-later.** The grader is the load-bearing first change (its output is consumed by every shipped task). It does not relax during calibration; if it stalls genuine work we tune the prompt, not the gate, with the manual-confirm endpoint (`POST /tasks/:id/confirm`) as the emergency release valve. New grader signals (`shots[]`, `grader_model`, per-worker scores) land in the jsonb `task_grades.signals` column with no migration; top-level `rubric_scores` get the median across shots. This mirrors how the economy lens earned its teeth ([ADR 0017](<redacted>.md)): advisory → calibrate → gate.
+
+## Phase plan & implementation history
+
+Built incrementally over six phases, each independently shippable and required to earn its keep before the next ("is this earning its tokens?" — delete the phase if not). **All shipped:**
+
+- **1** — strict grader: default-fail framing + cross-family Sonnet + 3-shot unanimous.
+- **2** — the grader's 4-worker panel (Narc · Quality · Hacker · Efficiency Monger) replacing the 3-shot generalist, unanimous-PASS gate; + server audit-trail forwarding of `security_score`/`efficiency_score`.
+- **3** — Conductor as a deterministic (zero-LLM) `UserPromptSubmit` hook, advisory only.
+- **4** — Conductor **session-mediated** dispatch (`scripts/gds/conductor-dispatch.js` runs any specialist on the working diff, reusing the grader-workers machinery).
+- **4.5** — Conductor **autonomous background** dispatch (`conductor-dispatch.js auto-dispatch`): selects the next claimable autonomous task *without a human prompt* and emits its `/builder-claim` directive for a runner to execute. It **proposes, never disposes** in the autonomous path too — the selector emits the directive; the runner + ship pipeline (where ADR 0016's DB gates and the grader still bite) is what claims, builds, and lands. Gated by the same `scripts/gds/autonomy-gate.js` precheck the nightly routines use (master kill-switch + MTD spend brake + no-signal skip), so it is **INERT until `OTB_AUTONOMY_ENABLED=1`**. The candidate feed is the protected-path-filtered `fit:'autonomous'` view (SR-12) — the permission/methodology/deploy core can never be auto-selected.
+- **5** — Architect role + first audit (`scripts/gds/architect-audit.js --scope` → `docs/audits/` + idea_inbox seeds; on-demand, not cron'd).
+- **6** — BFG built out well past bootstrap (doc/index + per-builder memory hygiene, DB counter-vs-ledger drift, cross-builder read + interaction-quality scoring, and the first audited cross-builder memory WRITE path — identity-gated, kill-switched, builder-reversible). Charter: [ADR 0026](<redacted>.md); session-inefficiency evaluator (cluster 6D): [ADR 0027](<redacted>.md).
+- **C7** — the grader's deterministic **route-rank pre-pass** (`src/bongos/route-rank-check.js`, shared via `grader.routeRankPrePass()` by the ship-time panel and `conductor-dispatch.js`): every route must classify to a known rank; write-route `unknown` → hard fail. The deterministic-first → LLM-on-demand pattern; C7's periodic auditor, in-context at ship time.
+
+Per-phase scope, rationale, "out of scope", and ship detail (incl. the Phase-1 first-ship calibration data + the `Number(null)=0` self-ship learning) live in the shipping tasks + the session logs — this ADR is the decision record, not the changelog. Phase tasks: [#395](https://example.com/builders#/task/395) (1) · [#410](https://example.com/builders#/task/410)/[#413](https://example.com/builders#/task/413)/[#416](https://example.com/builders#/task/416)/[#421](https://example.com/builders#/task/421)/[#423](https://example.com/builders#/task/423) (2) · [#427](https://example.com/builders#/task/427) (3) · [#439](https://example.com/builders#/task/439) (4) · [#459](https://example.com/builders#/task/459) (5) · [#442](https://example.com/builders#/task/442)–[#448](https://example.com/builders#/task/448) (6) · [#475](https://example.com/builders#/task/475) (C7) · [#458](https://example.com/builders#/task/458) (4.5).
+
+## Consequences
+
+**Good:**
+
+- The trust gate at `/builder-ship` actually bites. Calibration data — not vibes — drives future tightening.
+- Cost is ~neutral: 3× Sonnet ≈ 1× Opus (prior). Grader cost-per-shipped-task does not balloon.
+- Architecture-ready for per-builder model preferences ([ADR 0021](<redacted>.md)): when GDS-V4 ships builder-configurable model allocation, the `selectGraderModel(builderModel)` function becomes the obvious extension point.
+- Trust boundary preserved: nothing here grants new permissions; the Conductor (Phase 3+) inherits builder rank and proposes, never disposes ([ADR 0016](<redacted>.md) stays load-bearing).
+- The original Delegators (Project Manager, Janitor) are *deleted* rather than built — the Musk rule applied to ourselves.
+
+**Bad / accepted:**
+
+- <redacted> will likely stall at `completed`. Builders need to know this; the deploy banner should warn.
+- Sonnet may grade Sonnet builders same-family (when those exist). The cross-family premise assumes Opus builders. Phase 2's per-builder model-selection logic fixes this; Phase 1 accepts the assumption.
+- Three concurrent Sonnet subprocess invocations slow ship by ~1.5× the longest single shot (parallel, not serial — but the slowest shot still gates). Acceptable trade vs the leniency cost.
+- If 3 Sonnets agree too much (insufficient disagreement signal), the unanimous gate is theatrical. Calibration window will reveal this; Phase 1.5 mixes Opus into the panel if needed.
+
+**Reversibility:**
+
+- Phase 1 can be reverted by setting the rubric's `v3` entry's `shots: 1` and `default_model: claude-opus-4-7` (the field is `default_model`, not `model` — the latter is the v2 field name). The shot-aggregation code stays; the policy reverts. No migration needed.
+- The MAS hierarchy as a whole is reversible up through Phase 6. The persistent Conductor hook is the only piece that, once wired, will create dependency on its trigger taxonomy; deleting the hook restores prior behavior.
+
+## References
+
+- [ADR 0010](0010-pms-architecture.md) — GDS (then PMS) architecture
+- [ADR 0016](<redacted>.md) — trust boundary (Conductor must not bypass)
+- [ADR 0017](<redacted>.md) — economy lens (first Grader worker, retroactively)
+- [ADR 0021](<redacted>.md) — per-builder model preferences (Phase 1's hardcoded Sonnet generalizes here)
+- Anthropic, "Building Effective Agents" (Schluntz & Zhang, Dec 2024) — orchestrator-workers and evaluator-optimizer patterns
+- Anthropic, "How we built our multi-agent research system" (Engineering blog, 2025) — empirical 2-tier orchestration, ~15× token cost
+- Zheng et al., "Judging LLM-as-a-Judge with MT-Bench and Chatbot Arena" (NeurIPS 2023) — same-family judge inflation
+- Chiang & Lee, "Can Large Language Models Be an Alternative to Human Evaluations?" (ACL 2023) — LLM-judge sycophancy
+- Musk's 5-step engineering algorithm — applied to the proposal itself, not just to its outputs

package/docs/adr/0025-offsite-backup-vendor-digitalocean-spaces.md

@@ -0,0 +1,59 @@
+# ADR 0025 — Offsite backup vendor: DigitalOcean Spaces
+
+**Date:** 2026-05-30
+**Context:** Task [#415](https://example.com/builders#/task/415) (V3.R62-offsite), claim `#338`, GDS-V3 criterion C8 ("memory is local-first, server-canonical on ship" — which depends on the GDS DB surviving whole-droplet loss). Companion to the local nightly backup filed by [#412](https://example.com/builders#/task/412) (V3.R62-precondition, [`docs/recipes/gds-db-backup.md`](../recipes/gds-db-backup.md)) and the secrets policy in [ADR 0022](0022-secrets-policy.md). Sits under [ADR 0024 §5](<redacted>.md) (backup cadence).
+**Status:** Accepted.
+
+## Problem
+
+The local nightly `pg_dump` ([#412](https://example.com/builders#/task/412)) writes gzipped dumps to `/var/backups/gds/` — on the **same physical disk** (`/dev/vda1`) as the live database. That protects against the likely failures (bad migration, accidental `DROP`, schema corruption, an LLM writing a row it shouldn't) but **not** whole-droplet loss: provider failure, accidental droplet termination, or disk destruction takes the dumps with the database.
+
+C8 makes builder memory server-canonical on ship — so the GDS DB is now the single home for every builder's synced memory, not just work-tracking state. Losing it loses that too. We need a copy that lives somewhere the droplet's disk dying cannot reach.
+
+We must pick an off-droplet storage target. The budget posture (CLAUDE.md §4) is "cheapest viable; document the trade-off in an ADR when the more expensive option is chosen." We chose the more expensive option, so this ADR records why.
+
+## Options considered
+
+| Option | Cost | Notes |
+|---|---|---|
+| **Backblaze B2** | ~$0/mo at our volume (10 GB free; dumps are sub-1 MB) | Cheapest. Separate vendor, separate account, separate billing, separate credential lifecycle. S3-compatible API. |
+| **DigitalOcean Spaces** ✅ | $5/mo flat (250 GB + 1 TB transfer included) | Same vendor as the droplet — one console, one bill, one support relationship, one place to reason about region/latency. S3-compatible API. |
+| AWS S3 | ~$0 at our size but per-request + egress pricing | Third vendor, IAM complexity, surprise-bill risk. Rejected. |
+
+## Decision
+
+**Use DigitalOcean Spaces, in the NYC3 region** (same region as the droplet).
+
+Rationale for accepting the $5/mo over B2's ~$0:
+
+1. **One vendor.** The droplet, DNS-adjacent infra, and now backups all live in one DigitalOcean account. A non-software-engineer operator (the prompter — CLAUDE.md §2) manages one console and one bill, not two. The operational simplicity is worth $60/year on a $5,000 project budget.
+2. **Same region as the droplet (NYC3).** Lowest-latency upload path; no cross-provider egress to reason about.
+3. **Flat, predictable price.** $5/mo with generous included transfer — no per-request or surprise-egress billing to monitor. Predictability matters more than absolute floor at this scale.
+4. **The scaffolding already pointed here.** The retired task-[#7](https://example.com/builders#/task/7) backup (see below) was already written against the `SPACES_*` env shape, so DO Spaces is the lowest-friction path to a *working* offsite copy.
+
+B2 remains the obvious fallback if the $5/mo ever needs trimming — the uploader is plain S3 (`boto3` + `endpoint_url`), so re-pointing it at B2 is a credentials + endpoint change, nothing structural.
+
+## What this replaces — the retired [#7](https://example.com/builders#/task/7) backup
+
+A previous task ([#7](https://example.com/builders#/task/7), V1 era) shipped `scripts/backup.sh` + `/etc/cron.d/otb-backup`: a daily `pg_dump → DO Spaces` cron. By the time [#412](https://example.com/builders#/task/412)/[#415](https://example.com/builders#/task/415) were planned it had been **forgotten** — which is why [#415](https://example.com/builders#/task/415) was filed "vendor TBD." On inspection (2026-05-30) it was **deployed but dead**: `~/.config/otb/spaces.env` held all-empty credentials, no Space was ever created, and `/var/log/otb-backup.log` did not exist (it had never successfully run).
+
+Rather than leave two competing, half-broken backup systems, [#415](https://example.com/builders#/task/415) **retires** the [#7](https://example.com/builders#/task/7) setup and replaces it with one clean story:
+
+- **Local daily** — `gds-db-backup.timer` ([#412](https://example.com/builders#/task/412)), `pg_dump` → `/var/backups/gds/`, 30-day retention.
+- **Offsite weekly** — `gds-db-offsite.timer` ([#415](https://example.com/builders#/task/415)), copies the *latest existing* local dump → DO Spaces, 4-week retention. It does **not** take its own `pg_dump`; it archives what [#412](https://example.com/builders#/task/412) already produced.
+
+Removed by [#415](https://example.com/builders#/task/415): `scripts/backup.sh`, `infra/backup/otb-backup.cron`, the droplet's `/etc/cron.d/otb-backup`, and the empty `~/.config/otb/spaces.env` stub.
+
+## Mechanics
+
+- **Credentials** live at `/etc/example/spaces.env` (chmod 600, owned by `lars`), never in the repo — per [ADR 0022](0022-secrets-policy.md). Vars: `SPACES_KEY`, `SPACES_SECRET`, `SPACES_BUCKET`, `SPACES_REGION`, `SPACES_ENDPOINT`. systemd injects them via `EnvironmentFile`; manual runs source the same file.
+- **Cadence:** Sunday 05:00 UTC, one hour after the 04:00 UTC local dump, so the offsite copy is always same-day-fresh.
+- **Retention:** 4 weekly copies in the Space (`GDS_OFFSITE_KEEP=4`), pruned oldest-first under the `gds-offsite/` key prefix. ~1 month of offsite snapshots. Sub-1 MB each, so storage is a rounding error against the 250 GB tier.
+- **Restore drill:** quarterly download-and-restore from the Space, documented in [`docs/recipes/gds-db-backup.md`](../recipes/gds-db-backup.md).
+
+## Consequences
+
+- **+$5/mo** recurring (~$60/yr) against the project budget. Acceptable and documented.
+- Whole-droplet loss now costs at most ~1 week of writes (last weekly offsite copy), down from "everything." Combined with the daily local dump, the day-to-day exposure is still ≤24h.
+- One credential to rotate (the Spaces key) per [ADR 0022](0022-secrets-policy.md) rotation procedure.
+- A second vendor relationship is avoided; if cost pressure appears later, re-pointing the uploader at Backblaze B2 is a config change, not a rewrite.

package/docs/adr/0025-structured-criterion-task-link.md

@@ -0,0 +1,44 @@
+# ADR 0025 — Structured criterion↔task link (`task_criteria`)
+
+**Date:** 2026-05-30
+**Context:** GDS-V3, task [#435](https://example.com/builders#/task/435) (Project status queryability — structured criterion↔task link + /status skill + Conductor nudge).
+**Status:** Accepted.
+
+## Problem
+
+Answering a routine question — "what's left to satisfy criterion C8?" — took ~10 sequential GDS calls. The reason: the relationship between a done-when criterion and the tasks that satisfy it existed **only as prose** inside each task's `description`:
+
+```
+**Criterion:** C8 — cloneable repo, local-first memory, server-canonical on ship.
+…
+**Cross-refs:** Gates V3.R55–V3.R63 (the C8 implementation tasks).
+```
+
+To answer the question a session had to: read `done_when_criteria` to find C8, grep `scripts/gds/seed-v3-tasks.js` to discover which tasks claim that criterion, eyeball a "Gates R55–R63" sentence, then re-query each task's live status. That is archaeology, not a query — slow, error-prone, and impossible to surface on the public status dashboard.
+
+There was already a link, but the wrong one: `done_when_criteria.satisfied_by_task_id` is a **single, reverse** pointer — the one ship-task that *closed* a criterion. We needed the **forward, many** relation: the many tasks that *gate* a criterion, before it's closed.
+
+## Decision
+
+Add a dedicated **many-to-many join table** `task_criteria(task_id, criterion_id)` (migration 055), referencing `tasks(id)` and `done_when_criteria(id)`. A new read helper `criterionProgress(versionId)` joins it to roll up, per criterion: the gating tasks, their live statuses, and what remains. Surfaced as the public `GET /api/gds/versions/:id/progress`, consumed by `scripts/gds/status.js` + the `/status` skill, and routed to by a Conductor nudge.
+
+### Why many-to-many (rejected alternatives)
+
+- **A `criterion_id` column on `tasks`** — rejected: tasks routinely contribute to *multiple* criteria (prose like "C2, C7"). A single FK column can't represent that without a delimiter hack.
+- **Reusing `satisfied_by_task_id`** — rejected: it's singular and semantically the *closing* task, not the *gating* set. Overloading it would conflate "this task finished the criterion" with "this task is one of several that build toward it."
+- **Keep parsing prose at read time** — rejected: that's the status quo whose cost we're removing. Every consumer (CLI, dashboard, future agents) would re-implement a fragile parser.
+
+### The backfill is positional — and that fragility is the point
+
+Migration 055 backfills the table from the existing prose. The catch: the prose says "C8" but a criterion's `criterion_id` is a semantic slug (`cloneable-local-memory-server-sync`). **"Cn" is the 1-based position** by `(sort_order, criterion_id)` within the version. So the backfill ranks each version's criteria with `ROW_NUMBER()` and joins prose "Cn" → the n-th criterion of the *same* version.
+
+This positional decode is brittle — reorder the criteria and old prose references drift. That brittleness is exactly why the structured link must exist: **after this backfill, `task_criteria` is canonical**, and prose `Cn` references are legacy. New tasks should populate the join table directly rather than relying on the decode being re-run (it is not — it's a one-time historical migration).
+
+`cnum` is recomputed live (same `ROW_NUMBER()` ordering) in `criterionProgress`, so the "C8" label the user sees stays correct even if criteria are added or reordered later. Tasks whose Criterion line carries no "Cn" token (e.g. "cross-cutting (identity)") are left unlinked and counted as `unattributed_tasks` — the rollup reports coverage honestly rather than guessing.
+
+## Consequences
+
+- **One-call status.** `/status C8` answers in a single request what previously took ~10. The public dashboard can adopt the same endpoint.
+- **The Conductor stays advisory + zero-cost.** It gains one regex trigger that *routes* status-intent prompts to `/status` (proposes, never disposes; no LLM call) — it does not answer questions itself. Consistent with [ADR 0024 (MAS)](<redacted>.md) Phase 3.
+- **Follow-up needed:** task creation does not yet populate `task_criteria`, so tasks created after the backfill are unlinked until a manage endpoint / planning-flow wire-up lands. Filed as a follow-up task at ship time. Until then `/status` under-counts new work, which `unattributed_tasks` makes visible.
+- **No authority change.** The endpoint is public read-only (same posture as `/versions/:id/done-when`); the join table carries no permission semantics. ADR 0016 trust boundary is untouched.

package/docs/adr/0026-bfg-memory-hygiene-and-cross-builder-learning.md

@@ -0,0 +1,117 @@
+# 0026 — The BFG: documentation/memory hygiene + cross-builder learning + transparent correction
+
+- **Status:** Accepted + Shipped. Phase 6 of the MAS is **built** — implemented in [`modules/sessions/bfg.js`](../../modules/sessions/bfg.js) (`scoreMemoryQuality`, `extractTransferablePatterns`, `buildCorrection`, …; carved into the `sessions` module at BV1.R82 / ADR 0093 §1).
+- **Date:** 2026-05-30
+- **Deciders:** Lars Kristensen (Archon), Claude
+- **Track:** `internal` (GDS)
+- **Context task:** GDS-V3 [#441](https://example.com/builders#/task/441) (this design task — ADR + task breakdown only; no implementation).
+
+> **Numbering note:** this ADR was authored as `0025` but renumbered to **0026** on the same day, after a merge from `main` surfaced an already-shipped [`0025` — Offsite backup vendor](<redacted>.md) (task [#415](https://example.com/builders#/task/415)). The shipped ADR keeps `0025`; this one moves. The backlog implementation tasks **[#442](https://example.com/builders#/task/442)–[#448](https://example.com/builders#/task/448)** were filed *before* the renumber and so reference this ADR as "ADR 0025" in their descriptions (the GDS has no description-edit endpoint and there was no DB access to correct them in-session). The sub-phase labels (**6A.1 … 6C.3**) are stable and unambiguous — when a task says "ADR 0025 section 6A.1", read **this** ADR (0026), section 6A.1.
+- **Extends:** [ADR 0024 — Multi-Agent System architecture](<redacted>.md) (the BFG is its Phase 6); [ADR 0024 — Cloneable repo + local-first memory](<redacted>.md) (the `builder_memory` store this operates on); [ADR 0016 — Trust boundary](<redacted>.md) (this ADR deliberately and narrowly *punctures* the no-cross-builder-write rule — recorded here as a conscious exception). Touches the karma model ([migration 040](../../migrations/040_builder_karma.sql)) and the memory schema ([migration 054](../../migrations/054_builder_memory.sql)).
+
+## Context
+
+The **BFG** is the post-ship / pre-cron role in the MAS ([ADR 0024-mas](<redacted>.md)). Its Phase-6 charter there was deliberately narrow: *"memory hygiene — audit CLAUDE.md claims against DB reality, prune stale references, verify `[[links]]` resolve."* No code has been written yet.
+
+On 2026-05-30 Lars expanded the BFG's remit to **two standing objectives**:
+
+1. **Cleanliness of all documentation** — `*.md`, memory files, and anything doc-shaped that lives in the DB. The index must not drift from reality.
+2. **The best, most "creative/intelligent" building experience for builders.** The mechanism Lars named: read every builder's memory, evaluate *how* they interact with the system, and when a builder is performing well, study their memory and propose to other builders what they should adopt. The BFG may also **plant "dreams"** — write a memory directly into another builder's store when it's an obvious improvement — and apply **corrections** to misbehaving builders.
+
+This ADR records the architecture and, critically, the **boundaries** that turn that intent into something safe to build.
+
+### What the substrate already gives us
+
+- **Builder memory is server-canonical and per-builder isolated** — [`builder_memory`](../../src/bongos/routes/memory.js), `PRIMARY KEY (builder_id, path)`. The *only* cross-builder access that exists today is an **Archon-only, audit-logged, read-only** forensic path. **There is no cross-builder *write* path at all** — that was a conscious decision ([ADR 0016](<redacted>.md), [ADR 0024-memory](<redacted>.md) §4).
+- **Karma** ([`karma_log`](../../migrations/040_builder_karma.sql)) is the existing good-citizenship reputation ledger (append-only, `granted_by` records who drove a delta, `NULL` = system).
+- **Cron roles** live as `SKILL.md` files under [`.claude/scheduled-tasks/`](../../.claude/scheduled-tasks/); the read-only `overnight-code-review` routine is the closest existing pattern.
+
+## Decision
+
+The BFG gains three capability clusters (6A / 6B / 6C), built as independently-shippable sub-phases. Two cross-cutting rules govern all of them:
+
+- **The BFG is a privileged *system* agent, not a rank bypass.** Its cross-builder powers are the existing Archon-forensic-read posture, extended to a narrow audited write. They are bound to a dedicated **BFG service principal** (a `builders` row flagged as system: cannot claim work, cannot earn drachmae) and are reachable *only* by that principal — never exposed on a self-serve route. No human or agent builder can ask the system to "read/write another builder's memory." **This is an enforcement requirement, not prose intent:** 6C.1's write endpoint must gate on the *exact principal identity*, not on rank — an Archon token (or any rank-escalated / stolen token) must be rejected at the write endpoint, and that refusal must be covered by a test. "Never exposed on a self-serve route" is a property the implementation has to encode, not a promise the ADR can keep on its own.
+- **Every cross-builder operation — read *and* write — writes an `audit_log` row.** Writes are additionally **namespaced and attributed** so a builder can always see, and delete, exactly what the BFG put there. Nothing the BFG writes ever masquerades as the builder's own note.
+
+### 6A — Hygiene (the original charter, widened)
+
+Read-only auditor. Findings land as `idea_inbox` rows (one per finding, like `overnight-code-review`) plus a `docs/audits/bfg-<date>.md` report. The BFG **never** auto-mutates code or DB state — it reports.
+
+- **Doc ↔ reality:** CLAUDE.md claims vs DB (`shipped` task IDs cited, version statuses, the rank enum, drachmae/karma model), `[[link]]` resolution, ADR cross-reference integrity + numbering gaps, `docs/file-map.md` vs the actual tree, onboarding-diagram `assertions.json` vs live facts.
+- **Memory hygiene:** within each builder's *own* memory dir — dangling `[[links]]`, stale frontmatter, internal contradictions, duplicate facts (the same discipline the `consolidate-memory` skill applies, but agent-driven rather than human-invoked).
+- **DB cleanliness:** cached-counter vs ledger drift (`builders.karma` vs `karma_log`, `total_credits` vs `credit_log`), orphaned rows, long-stale `idea_inbox` / `blockers`. Reported, never silently "fixed."
+
+### 6B — Cross-builder learning ("read the room")
+
+- **Read all builders' memory** through a BFG-principal-only, per-read audit-logged endpoint (same shape as the Archon forensic read).
+- **Score interaction quality** by blending objective GDS signals (ships, grader pass rate, rework/abandon rate, karma, drachmae, methodology adherence visible in `audit_log` + conductor traces) with memory-quality heuristics.
+- **Extract *transferable* patterns** from top performers — working habits and durable lessons, **not** builder-specific secrets, PII, or anything that only makes sense in that builder's context.
+- **Propagate** as adoption suggestions to other builders (delivered via the 6C write path as clearly-marked BFG entries, or surfaced in the audit report).
+
+### 6C — Dreams & correction (the write path — the load-bearing part)
+
+This sub-phase creates the **first cross-builder memory write capability** in the system. It is the deliberate, bounded exception to [ADR 0016](<redacted>.md).
+
+**Dreams (beneficial writes).** Lars chose **direct write** (audited + visible) over propose-only, for immediacy. The BFG writes the entry directly into the target builder's memory, constrained by:
+- a dedicated, clearly-marked location — e.g. `bfg/dream-<slug>.md` (or a fenced `## BFG dreams` block) — never overwriting a builder's own files;
+- frontmatter `type: bfg-dream`, `author: BFG`, `source_builder`, `date`, `rationale`;
+- an `audit_log` row per write (`action: 'bfg_dream_write'`, target builder, path, rationale);
+- self-announcing content — the builder always sees it is BFG-authored and can delete it.
+
+**Correction (misbehaving builders).** Lars's explicit call: **transparent, attributed correction — NOT covert sabotage.** A correction is:
+- a **visible BFG-authored corrective note** (`type: bfg-correction`) stating the observed behavior, the rule it broke, and the expected change; plus
+- a **negative `karma_log` delta** with `reason: 'bfg_correction'`, `granted_by` = the BFG principal.
+
+> **Explicit non-goal — "nightmares" are rejected.** The original framing imagined the BFG planting *false or harmful* memories to covertly *worsen* a builder's experience. The system will **never** write deceptive or deliberately-degrading content into anyone's memory. A tool whose purpose is to sabotage a builder through deception is out of scope by design; "documenting it" does not make covert sabotage acceptable. Correction is honest, visible, and reversible — same steering effect, no deception. This clause is the durable record of *why* the capability stops here.
+
+### Identity & invocation
+
+The BFG runs as a `SKILL.md` scheduled routine (post-ship / pre-cron cadence) and can be nudged by the Phase-4 Conductor on index-doc edits. The cross-builder endpoints (6B read, 6C write) are gated to the BFG service principal server-side. The Phase-4 dispatch path treats the BFG as a read-mostly agent; only the 6C routine, running as the principal, may write.
+
+### Phase plan (created as backlog tasks by [#441](https://example.com/builders#/task/441))
+
+| Sub-phase | Scope | Earns it |
+|---|---|---|
+| **6A.1** | Read-only hygiene auditor: doc↔reality + `[[link]]`/ADR/file-map checks → `idea_inbox` + `docs/audits/bfg-<date>.md`. As a `SKILL.md` routine. | The index stops drifting; zero new write surface. Ship this first. |
+| **6A.2** | Extend the auditor with memory-hygiene + DB cached-vs-ledger drift checks (still report-only). | Hygiene covers all three artifact classes. |
+| **6B.1** | BFG-principal-only, audit-logged cross-builder memory **read** endpoint + interaction-quality scorer. | "Read the room" exists; reuses the forensic-read audit pattern. |
+| **6B.2** | Transferable-pattern extraction from top performers + adoption-suggestion generation. | Good practice propagates; the "most creative experience" objective gets teeth. |
+| **6C.1** | Migration: BFG service principal (system builder, no-claim/no-drachmae) + cross-builder memory **write** endpoint (audited, namespaced, attributed) + `karma_log` reason `bfg_correction`. | The write substrate + trust-boundary exception land in one reviewable unit. |
+| **6C.2** | Wire dream-writes + transparent corrections into the BFG routine; kill-switch; builder-visible attribution; delete affordance. | Dreams + correction work end-to-end, safely. |
+| **6C.3** | Update [ADR 0024-mas](<redacted>.md) Phase-6 row + CLAUDE.md MAS index line. (Deferred out of [#441](https://example.com/builders#/task/441) — `CLAUDE.md` / `0024` are held by the active Phase-4 claim `#439`.) | The index reflects the shipped BFG. |
+
+Each sub-phase must answer "is this earning its tokens?" before the next is built — the Musk gate, same as [ADR 0024-mas](<redacted>.md).
+
+> **Sibling capability cluster — 6D (session-inefficiency evaluator), recorded in [ADR 0027](<redacted>.md).** The 6A/6B/6C clusters above cover the BFG's *hygiene* and *cross-builder memory learning* objectives. A later, separately-chartered cluster — **6D** — serves the same "best building experience" objective from a different angle: it ingests uploaded session transcripts and auto-runs the #506-style post-mortem across all sessions to surface systemic build-process waste (and mine top performers for good practice). It reuses this charter's §6C transparent-note path to deliver per-builder findings. See [ADR 0027](<redacted>.md); build tasks GDS-V4 [#540](https://example.com/builders#/task/540)–[#545](https://example.com/builders#/task/545).
+
+## Alternatives considered
+
+- **Covert "nightmares" (rejected).** The original ask imagined planting *false or harmful* memories to covertly worsen a misbehaving builder. Rejected outright: it is deception that causes real harm (wasted work, decisions seeded by lies), it has no consent, and an audit trail does not redeem it. Transparent correction (a visible, attributed note + a karma dock) achieves the same steering with none of that. This is the load-bearing rejection of this ADR.
+- **Propose-only writes vs direct writes.** Propose-only (the BFG drops a clearly-marked *suggestion* the builder must accept) best preserves the isolation/consent spirit. Lars chose **direct write** for immediacy on "obvious improvements." We keep the consent spirit alive through visible attribution + namespaced files + delete-ability + per-write audit, and accept the residual risk (memory changing between sessions) in §Consequences.
+- **Karma-only correction (no memory write).** Considered: never touch a misbehaving builder's memory, only dock karma + flag for Archon. Rejected as the *default* because a karma delta alone doesn't tell the builder *what* to change; the visible corrective note carries the actionable feedback. (Karma-only remains the right move when there's nothing constructive to write.)
+- **Amend ADR 0024 vs a standalone ADR.** The BFG is Phase 6 of [ADR 0024-mas](<redacted>.md), so amending it was the obvious option. Chosen instead to write a standalone ADR because the new **cross-builder write path is a trust-boundary decision** that extends [ADR 0016](<redacted>.md) — significant enough to deserve its own record rather than a table-row footnote.
+- **Vector store / semantic memory for hygiene + 6B scoring.** Deferred, consistent with [ADR 0024-mas](<redacted>.md)'s own "vector-store implementation deferred" call. The current markdown `MEMORY.md` graph + frontmatter is sufficient for 6A/6B; revisit only if manual + heuristic analysis proves insufficient.
+
+## Consequences
+
+**Good:**
+- The index, memory, and DB stop drifting — a standing agent watches *current truth*, complementing the Architect's *future structure* (the boundary ADR 0024-mas drew).
+- Good practice propagates across builders instead of dying in one builder's memory.
+- The trust boundary stays *legible*: there is exactly one new cross-builder write path, bound to one system principal, fully audited and builder-visible.
+
+**Bad / accepted:**
+- **The isolation invariant is no longer absolute.** A builder's memory can change between sessions without their action. Mitigation: visible attribution + namespaced files + delete-ability + per-write audit. This residual risk is accepted in exchange for the immediacy Lars chose; revisit if it bites.
+- A BFG service principal is a new privileged identity — a new thing to secure. It must never be claimable or loginable as a normal builder.
+- Cross-builder reads touch every builder's memory; the audit trail is the only thing making that legible. The auditor must not leak one builder's private memory into another's via 6B extraction (the "transferable, not specific" rule is load-bearing, not advisory).
+
+**Reversibility:**
+- 6A is pure addition (a read-only routine) — delete the skill to revert.
+- 6C is reversible by disabling the write endpoint (kill-switch) and deleting BFG-namespaced memory files; the `audit_log` makes every write enumerable for cleanup.
+
+## References
+
+- [ADR 0024 — Multi-Agent System architecture](<redacted>.md) — the BFG is Phase 6
+- [ADR 0024 — Cloneable repo + local-first memory](<redacted>.md) — the `builder_memory` store + §4 isolation
+- [ADR 0016 — Trust boundary](<redacted>.md) — the rule this ADR narrowly excepts
+- [migration 040](../../migrations/040_builder_karma.sql) — karma ledger (correction deltas)
+- [migration 054](../../migrations/054_builder_memory.sql) — memory schema (read + write target)

package/docs/adr/0027-bfg-session-inefficiency-evaluator.md

@@ -0,0 +1,170 @@
+# 0027 — The BFG session-inefficiency evaluator (auto-post-mortem of builder sessions)
+
+- **Status:** Accepted + Shipped. The build (tasks **6D.1–6D.6**) was completed end-to-end — see the [2026-06-02 session log](../session-logs/<redacted>.md); this ADR is the charter it followed.
+- **Date:** 2026-06-02
+- **Deciders:** Lars Kristensen (Archon), Claude
+- **Track:** `internal` (GDS)
+- **Context tasks:** GDS-V4 **[#515](https://example.com/builders#/task/515)** (the capability umbrella) · **[#539](https://example.com/builders#/task/539)** (this design task — ADR + task breakdown only, no implementation; mirrors the design-only shape of [#441](<redacted>.md)).
+- **Extends:** [ADR 0024 — Multi-Agent System architecture](<redacted>.md) (the BFG is its Phase 6) · [ADR 0026 — The BFG charter](<redacted>.md) (this adds a **new capability cluster, 6D**, to the BFG's "best building experience" objective) · [ADR 0016 — Trust boundary](<redacted>.md) (narrowly extended — session detail now lives server-side and is BFG-readable across builders) · [ADR 0022 — Secrets policy](0022-secrets-policy.md) (scrubbing on upload). Touches `credit_log` (drachmae), `karma_log`, `builders` (rank + tenure), `task_grades` (the upsert-unique gap), `session_logs`.
+
+## Context
+
+On **2026-06-01** Lars asked for a manual evaluation of the **[#506](https://example.com/builders#/task/506)** session — a one-line welcome-copy fix that burned ~90% of its tokens on process ceremony + footgun recovery rather than the actual change. The post-mortem ([session log](../session-logs/<redacted>.md)) produced three concrete systemic fixes — **[#513](https://example.com/builders#/task/513)** (trivial-diff fast-path for the grader), **[#514](https://example.com/builders#/task/514)** (self-explaining API error hints), **[#468](https://example.com/builders#/task/468)** (a stale smoke assertion) — plus a security finding (`#526`).
+
+Lars wants that analysis **automated and run across every session**, to surface systemic build-process waste — and, as the inverse, to mine *top performers'* sessions for transferable good practice (the [ADR 0026](<redacted>.md) §6B objective). This ADR is the design; [#506](https://example.com/builders#/task/506) is the **hand-labeled seed/validation corpus**.
+
+### The substrate problem (and the decision that resolves it)
+
+The two candidate data sources don't overlap:
+
+- **Claude Code transcripts** (`~/.claude/projects/.../*.jsonl`) carry the rich signal — per-turn token usage, tool calls, `is_error` flags, timings — exactly what the manual [#506](https://example.com/builders#/task/506) read. But they live **local, per-builder**, never on the server.
+- **The GDS DB trail** (`session_logs`, `claims`, `task_grades`, `cost_log`) is **cross-builder** but coarse: wall-clock, outcomes, final grade — **no token-level detail**.
+
+Two earlier framings were put to Lars and rejected (see Alternatives): a local-only `/session-review` slash command, and a server-side analyzer. **Lars's decision** resolves the substrate problem directly:
+
+> **At ship time, upload the session's details to the server.** The BFG then runs as a **local Claude Code instance** (as it already does for hygiene, [ADR 0026](<redacted>.md) §6A.1) that **calls the server** to search across *all* sessions and deep-dive the interesting ones. The builder never runs anything — findings come to them.
+
+This is the load-bearing choice: the rich data stops being local, so one cross-builder corpus serves both the waste-hunt and the good-practice mine, and the analysis stays where the BFG already lives (a Claude Code routine), not on the always-on $14/mo droplet.
+
+## Decision
+
+A **new BFG capability cluster — 6D** — built as independently-shippable sub-phases. Four parts to the flow; the builder only ever sees part 4.
+
+### 1. Upload on ship (the keystone — 6D.1)
+
+When `/builder-ship` lands a task, `ship.js` locates the active Claude Code session transcript, **scrubs secrets** ([ADR 0022](0022-secrets-policy.md)), and uploads it to a new server-side `session_records` table. Each record carries the fields Lars named, denormalized for query:
+
+| Field | Source |
+|---|---|
+| `session_id` | the Claude Code `sessionId` |
+| `builder_id` | the shipping builder |
+| `task_ids[]` | task(s) shipped from this session |
+| `drachmae_earned` | the session's `credit_log` delta |
+| `total_tokens` | summed transcript `usage` (input + output + cache) |
+| `duration_seconds` | transcript first→last timestamp (or `session_logs`) |
+| `started_at` / `ended_at` / `uploaded_at` | timestamps |
+| `detail` | the **scrubbed** transcript payload (for deep-dive) |
+| `metrics` (jsonb) | derived signals (overhead ratio, tool-error count, footgun flags) — computed at upload or lazily |
+
+**Deduped per `session_id`** (a session that ships multiple tasks uploads once; `task_ids` accumulates). The upload is **fail-safe and non-blocking** — a failed or absent upload must *never* block a ship.
+
+### 2. Store + serve — the query surface (6D.2)
+
+The server stores and serves; it does **no analysis**. Two endpoints over `session_records`:
+
+- **Search/filter** by *session* fields (`drachmae_earned`, `total_tokens`, `duration`, the derived metrics) **and joined `builders` fields** — **tenure** (`now − created_at`), **rank**, **karma**, **drachmae** (`total_credits`). So queries like *"rank = Xenos AND tenure < 7d AND overhead > 0.7"* (onboarding friction) or *"karma top-decile"* (good-practice mining) are expressible against one corpus.
+- **Fetch one session's** full scrubbed detail for deep-dive.
+
+Cross-builder reads are gated to the **BFG service principal** ([ADR 0026](<redacted>.md) §6B posture — the *exact principal identity*, not rank) and write an **`audit_log` row per read**. A builder may always read their *own* sessions self-serve. Filtering is plain SQL/keyword **for now** (semantic/vector deferred, consistent with [ADR 0024](<redacted>.md)/[0026](<redacted>.md)).
+
+### 3. The BFG routine — local Claude Code, search → deep-dive → reason (6D.3)
+
+A new BFG sub-routine, running as a **local Claude Code instance** (the [`architect-audit.js`](../../scripts/gds/architect-audit.js) / §6A.1 pattern — read-only subagent + deterministic side-effects). It:
+
+1. calls the 6D.2 search to rank **interesting** sessions — high ceremony-vs-work ratio, dense tool-errors, ran-over-estimate, failed-grade, re-claim thrash (and the inverse: high-karma top performers worth learning from);
+2. fetches + deep-dives them, computing the two analyses below;
+3. writes a `docs/audits/bfg-session-eval-<date>.md` report. **Read-only — it proposes, never mutates.**
+
+**The ceremony-vs-work ratio.** Each assistant turn / tool-call classifies into:
+- **work** — edits to files that ended up in the shipped diff; problem-solving toward that diff;
+- **ceremony** — GDS claim/ship/release/status/grade plumbing; reading methodology; session-log writing;
+- **recovery** — tool errors + the turns spent recovering; retries; re-grades; guess-and-retry.
+
+Ratio = work tokens ÷ total (with a parallel turn-based ratio). [#506](https://example.com/builders#/task/506) ≈ **10 / 90**.
+
+**The footgun taxonomy** (the detector set):
+1. repeated tool failures (same tool + error class, ≥2×);
+2. empty/trivial-diff grade (panel spawned on no/near-no diff);
+3. claim-consumed-on-fail (claim released/abandoned after a failed grade);
+4. stale-test red herring (a test/smoke failure whose *fix edits the test*, not the feature);
+5. **guess-and-retry on API enums/routes** (GDS API 4xx → retry with changed params) → produced **[#514](https://example.com/builders#/task/514)**;
+6. **heavyweight-pipeline-on-trivial-change** (full grader panel on a sub-N-line / copy-only diff) → produced **[#513](https://example.com/builders#/task/513)**.
+
+### 4. Findings to the builder (6D.4)
+
+- **Systemic** build-process fixes → `idea_inbox` rows / backlog tasks (conservative grouping, like §6A.1 and the manual [#506](https://example.com/builders#/task/506) → [#513](https://example.com/builders#/task/513)/[#514](https://example.com/builders#/task/514)/[#468](https://example.com/builders#/task/468)).
+- **Per-builder** process findings → delivered to *that* builder via the [ADR 0026](<redacted>.md) **§6C transparent, BFG-authored, attributed note** path (builder-visible, deletable, audit-logged) — for the builder to **evaluate and act on**. The §6C write path is built by 0026's 6C.1/6C.2; 6D.4 wires session findings *into* it and degrades to inbox-only until 6C exists.
+
+The builder-field querying does double duty: it powers the **waste hunt** *and* the charter's **6B good-practice mining** — one corpus, both objectives.
+
+### Trust & privacy (load-bearing)
+
+Uploading session detail means transcripts **now live server-side and are BFG-readable across builders** — today they are local-only. This is a deliberate, narrow extension of [ADR 0016](<redacted>.md), in the same family as [ADR 0026](<redacted>.md)'s cross-builder paths. The safeguards are **enforcement requirements, not prose**:
+
+- **Secrets scrubbed on upload** ([ADR 0022](0022-secrets-policy.md)) — known secret patterns + the builder's own env values redacted *before* the transcript leaves the machine; covered by a test.
+- **BFG-principal-only** cross-builder reads (a builder reads only their own self-serve); **`audit_log` row per cross-builder read**.
+- **Retention window** — sessions are pruned after a bounded period; the corpus is not hoarded forever.
+- **Builder-visible** — a builder can see, and request deletion of, their uploaded sessions.
+
+> **Non-goal — not covert surveillance.** This is not a tool for secretly ranking or punishing builders. Findings are transparent and attributed (the §6C posture). This mirrors [ADR 0026](<redacted>.md)'s explicit rejection of covert "nightmares": the steering is honest, visible, and reversible.
+
+### Validation — the [#506](https://example.com/builders#/task/506) regression gate (6D.5)
+
+The design must reproduce the hand-labeled [#506](https://example.com/builders#/task/506) findings. A scrubbed excerpt of the 2026-06-01 transcript is checked in as a seed fixture; the evaluator must surface:
+
+| [#506](https://example.com/builders#/task/506) manual finding | Detector |
+|---|---|
+| heavyweight pipeline on a trivial change | footgun [#6](https://example.com/builders#/task/6) → **[#513](https://example.com/builders#/task/513)** |
+| guessing at API errors + retrying | footgun [#5](https://example.com/builders#/task/5) → **[#514](https://example.com/builders#/task/514)** |
+| stale test sent diagnosis down a rabbit hole | footgun `#4` → **[#468](https://example.com/builders#/task/468)** |
+| ~90% of tokens on ceremony | the ceremony-vs-work ratio |
+
+This is the regression gate: classifier/detector changes must keep finding the known issues.
+
+### Phase plan (created as backlog tasks by [#539](https://example.com/builders#/task/539), children of [#515](https://example.com/builders#/task/515))
+
+| Sub-phase | GDS task | Scope | Earns it |
+|---|---|---|---|
+| **6D.1** | [#540](https://example.com/builders#/task/540) | Upload-on-ship: `session_records` table + POST route + secret-scrub + `ship.js` wiring | The corpus exists; everything depends on it. Ship first. |
+| **6D.2** | [#541](https://example.com/builders#/task/541) | Search/query API (session + joined builder fields) + fetch-detail; principal-gated + audited | The corpus is queryable along both waste and good-practice axes. |
+| **6D.3** | [#542](https://example.com/builders#/task/542) | BFG local routine: search → deep-dive → ceremony-vs-work + footguns → report | The [#506](https://example.com/builders#/task/506) post-mortem becomes a standing, automatic capability. |
+| **6D.4** | [#543](https://example.com/builders#/task/543) | Findings delivery: `idea_inbox` (systemic) + §6C note (per-builder) | Findings reach the builder transparently; loop closes. |
+| **6D.5** | [#544](https://example.com/builders#/task/544) | [#506](https://example.com/builders#/task/506) validation/regression harness (seed fixture) | The evaluator provably reproduces the hand-labeled case. |
+| **6D.6** | [#545](https://example.com/builders#/task/545) | *(optional)* append-only grade-attempt logging | Re-grade thrash becomes countable — *only if the signal earns its keep.* |
+
+Each sub-phase answers "is this earning its tokens?" before the next — the Musk gate, same as [ADR 0024](<redacted>.md)/[0026](<redacted>.md).
+
+## Alternatives considered
+
+- **Local-only `/session-review` slash command (rejected by Lars).** The first proposal kept the rich data local and had the builder run the review on demand. Rejected: *"I want the average builder to not think about this"* — and a local tool can never see cross-builder sessions. Upload-on-ship + a server corpus replaces it.
+- **Server-side analyzer (rejected by Lars).** The second proposal ran the analysis on the server. Rejected: the BFG **runs as a local Claude Code instance**; the server only *stores and serves*. This keeps expensive LLM reasoning off the always-on droplet and matches the BFG's existing identity (a `SKILL.md` routine).
+- **Digest-only upload (deferred).** Store just the computed metrics, not the transcript. Rejected for now because the BFG must be able to deep-dive with *new* criteria later — a digest freezes the analysis. Full (scrubbed) transcript chosen, bounded by a retention window. Revisit if storage cost bites.
+- **Vector / semantic search over the corpus (deferred).** Consistent with [ADR 0024](<redacted>.md)/[0026](<redacted>.md)'s "vector store deferred." Plain SQL + keyword "for now" (Lars's word).
+- **Counting re-grade thrash from `task_grades` (not possible).** `task_grades.task_id` is `UNIQUE` — only the *final* grade survives, so the number of grade attempts isn't persisted. 6D.6 optionally adds append-only grade-attempt logging if that signal proves wanted.
+
+## Consequences
+
+**Good:**
+- The [#506](https://example.com/builders#/task/506) post-mortem becomes a **standing, automatic** capability; systemic waste surfaces as `idea_inbox`/tasks without anyone asking.
+- **One queryable corpus** serves both the waste hunt and [ADR 0026](<redacted>.md) §6B good-practice propagation.
+- Analysis stays a local Claude Code routine — **no new always-on cost** on the droplet.
+
+**Bad / accepted:**
+- **Session transcripts now live server-side** — a new sensitive store to secure, scrub, and retain. Mitigated by upload-time scrubbing + principal-gating + audit + retention + builder visibility.
+- **The BFG can read across builders' sessions** — the audit trail is what keeps that legible (same residual risk [ADR 0026](<redacted>.md) accepted for memory).
+- **`ship.js` gains an upload step** — it must be fast, non-blocking, and fail-safe; a broken upload can never block a ship.
+
+**Reversibility:**
+- 6D.1 is additive — stop uploading and drop `session_records` to revert.
+- The BFG routine is a deletable `SKILL.md`.
+- The retention window auto-prunes the corpus.
+
+## Lineage — GDS-V4 measurement-honesty amendments
+
+The 2026-06-12 friction analysis (1,349 session records, V4.R00) showed the
+evaluator's numbers did not reflect real friction. Three GDS-V4 fixes correct it
+(criterion `bfg-measures-what-hurts`):
+
+- **Harness-retry split ([#959](https://example.com/builders#/task/959)).** Harness guardrail rejections — an Edit/Write before the file was Read (`File has not been read yet`) or a foreground `Blocked: sleep` — were counted in `tool_error_count`, inflating it and letting benign retries top the `order=tool_errors` ranking. `buildSessionDigest` now classifies them into a separate `harness_retry_count`, leaving `tool_error_count` NET. Because `sessions/search` orders on `metrics->>'tool_error_count'`, the ranking uses the net figure with no route change.
+- **Wrong-path / worktree footgun ([#960](https://example.com/builders#/task/960)).** `detectFootguns` gained `wrong_path_worktree` (the corpus's [#1](https://example.com/builders#/task/1) error class, 84 hits) + a `FINDING_TEMPLATES` entry, so the worktree↔main-checkout split surfaces as an actionable idea_inbox finding.
+- **Turn-weighted overhead ([#961](https://example.com/builders#/task/961)).** Token weighting scored 150M-token cache-heavy marathons as 97–99% "work" while the turn sequence was hours of ceremony. `computeOverhead` now also reports a turn-weighted ratio, and the verdict is driven off it.
+
+## References
+
+- [ADR 0024 — Multi-Agent System architecture](<redacted>.md) — the BFG is Phase 6
+- [ADR 0026 — The BFG charter](<redacted>.md) — 6D extends the "best building experience" objective; §6C is the findings-delivery path
+- [ADR 0016 — Trust boundary](<redacted>.md) — the rule this narrowly extends
+- [ADR 0022 — Secrets policy](0022-secrets-policy.md) — upload-time scrubbing
+- [2026-06-01 #506 post-mortem session log](../session-logs/<redacted>.md) — the hand-labeled seed corpus
+- `migrations/003_pms.sql` (`credit_log`, `session_logs`, `claims`), `migrations/016_pms_task_grades.sql` (the upsert-unique grade), `migrations/040_builder_karma.sql` (karma)
+- GDS tasks: **[#515](https://example.com/builders#/task/515)** (umbrella) · **[#539](https://example.com/builders#/task/539)** (this design) · **[#540](https://example.com/builders#/task/540)–[#545](https://example.com/builders#/task/545)** (6D.1–6D.6)