@bongos/core 1.17.0

package/docs/adr/0022-secrets-policy.md

@@ -0,0 +1,124 @@
+# ADR 0022 — Secrets policy
+
+**Date:** 2026-05-28
+**Context:** Task [#279](https://example.com/builders#/task/279) (V3.R60), GDS-V3 criterion C8. Builds on the pre-commit hook + CI scan shipped by [#257](https://example.com/builders#/task/257) (V3.R36) and pairs with [ADR 0020](<redacted>.md) (security model — public stub) and [ADR 0016](<redacted>.md) (trust boundary). Companion to [`docs/security-baseline.md`](../security-baseline.md) item 6.
+**Status:** Accepted.
+
+## Problem
+
+A secret committed to a public repo is a credential someone else can use within minutes — even after a force-push to remove it, the value survives in forks, GitHub's commit cache, and any clone made between the commit and the removal. The right model is **defense in depth**: each layer assumes the next one will fail.
+
+We already have parts of this:
+
+- Pre-commit hook in `.husky/pre-commit` blocks the obvious shapes locally.
+- `.github/workflows/secrets-scan.yml` re-scans full history in CI on every PR.
+- `.gitignore` lists `.env.local`.
+- Live credentials resolve from `/etc/example/` on the droplet or `~/.config/otb/env` on builder laptops — neither path is tracked.
+
+What's missing — and what this ADR adds — is a written **policy** that defines:
+
+1. What counts as a secret (so the scan can be tuned).
+2. Where secrets are allowed to live (so a builder spinning up a fresh worktree knows the recipe).
+3. How rotation works (so a leak is recoverable, not catastrophic).
+4. What to do when a hit is found (so the response is mechanical, not improvised).
+
+Without this document, every new builder reinvents the answers. Some answers will be wrong.
+
+## Decision
+
+This ADR is **the policy**. The pre-commit hook + the CI workflow are the **enforcement**. The `docs/security-baseline.md` check is the **assertion that both still exist**. Each layer is independently maintained but consistent with this document.
+
+## What counts as a secret
+
+A "secret" for the purposes of this policy is any string that, if disclosed, would let an attacker act on behalf of the project or a builder.
+
+**In scope** (the scan looks for these shapes; treat any leak as a credential compromise):
+
+- GitHub Personal Access Tokens (`ghp_`, `gho_`, `ghu_`, `ghs_`, `ghr_`)
+- GitHub OAuth client secrets (40-char hex)
+- AWS access key IDs (`AKIA…` + the matching secret on the same line or nearby)
+- Google API keys (`AIza…` + 35 chars), Google service-account JSON bodies (look for `"private_key": "<redacted> PRIVATE KEY"`)
+- Slack tokens (`xoxa-`, `xoxb-`, `xoxp-`, `xoxr-`, `xoxs-`)
+- Stripe live + test secret keys (`sk_live_`, `sk_test_`)
+- Any RSA / EC / DSA / Ed25519 private key (`-----BEGIN … PRIVATE KEY-----`)
+- TLS private keys (`-----BEGIN PRIVATE KEY-----`)
+- Cloudflare Origin Certificate private halves (lives on droplet only — see [ADR 0003](<redacted>.md))
+- Postgres passwords (if peer-auth ever gets replaced with password auth — see [`docs/recipes/ops-gotchas.md`](../recipes/ops-gotchas.md) for the current peer-auth setup)
+- GDS session bearer tokens (any value of `gds_session` / `pms_session`)
+
+**Out of scope** (these are *config*, not secrets — they may live in the repo):
+
+- Public URLs, droplet IP `REDACTED_IP` (it's the A record's target — already published)
+- Cloudflare zone IDs, GitHub OAuth Client *IDs* (the matching *secret* is in scope)
+- Postgres database / user names (`example`, the deploy user), CORS-allowed origins
+- Public Stripe publishable keys (`pk_live_…`, `pk_test_…`) — these are *meant* to ship in client code
+
+## Where secrets are allowed to live
+
+Three lanes, each with explicit access controls. **Nothing else** is sanctioned; if a fourth lane appears, this ADR is the bug.
+
+| Lane | Path | Tracked? | Permissions | Used by |
+|---|---|---|---|---|
+| Droplet long-lived | `/etc/example/secrets.env` (chmod 600, owned by `lars`) | no — outside the repo | only the `lars` user + root | systemd service file sources it before exec |
+| Droplet rotating | `/etc/example/secrets/<name>` (chmod 600, per-secret file) | no | only the `lars` user + root | individual services that read one file at startup |
+| Builder laptop | `~/.config/otb/env` AND `.env.local` (gitignored, lives at the repo root in the main checkout and copies into worktrees on session start) | no — explicitly gitignored | the builder's macOS user account | `art/pipeline/gen_api.py` reads `~/.config/otb/env`; everything else reads `.env.local` |
+
+> **Multi-line secrets (e.g. a GitHub App private key, PEM).** Store in the droplet long-lived lane as a single line with literal `\n` escapes — `GITHUB_APP_PRIVATE_KEY="<redacted>"` — and the reader restores the newlines (`src/bongos/github-push.js normalizePem`). The GitHub App credential for server-mediated publish (`GITHUB_APP_ID` + `GITHUB_APP_INSTALLATION_ID` + `GITHUB_APP_PRIVATE_KEY`, [ADR 0055](<redacted>.md) / task 1028) lives here alongside the `GITHUB_PUSH_TOKEN` PAT it replaces.
+
+Notably **not allowed**:
+
+- Anywhere under the repo root that is not gitignored.
+- A "convenience" copy on the droplet outside `/etc/example/`.
+- An environment variable exported in a builder's `.zshrc` (it ends up in shell history; it isn't auditable).
+- Cloud "secrets managers" (AWS Secrets Manager, GCP Secret Manager, 1Password Connect, etc.) — out of budget for a $5K/year project and adds a single point of failure that's not worth it at this scale.
+
+## How rotation works
+
+When a credential is rotated — either because we found a leak or because the credential is reaching its TTL — the operation is:
+
+1. **Generate the new credential** at the issuing service (GitHub, Google, Stripe, Cloudflare, etc.).
+2. **Update the droplet** — `ssh lars@REDACTED_IP`, edit `/etc/example/secrets.env` (or the per-secret file), restart the affected service. Time gap: ≤ 5 minutes.
+3. **Update each builder laptop's local copy** — Lars notifies the team (chat broadcast or in-person); builders update `~/.config/otb/env` or `.env.local`. Builders who don't update can't run pipelines that need the rotated credential; they'll discover this when their next `art/` run fails.
+4. **Revoke the old credential** at the issuing service. Do this AFTER step 2; the brief overlap is intentional so a slow-rolling service catches both keys.
+5. **Log the rotation** — a one-line entry to [`docs/recipes/ops-gotchas.md`](../recipes/ops-gotchas.md) (date + which credential + why), so the next builder spinning up knows what changed when.
+
+GDS session tokens rotate automatically — they're 30-day-TTL, refresh-on-use, revocable per session or per builder (migration `<redacted>.sql`, ADR-aligned with [ADR 0016](<redacted>.md)). No manual rotation needed for those except in a leak scenario, which falls under "What to do on a hit" below.
+
+## What to do when the scan finds a hit
+
+If `.husky/pre-commit` blocks a commit, OR `.github/workflows/secrets-scan.yml` fails on a PR, OR a one-off TruffleHog run finds a hit in history, OR `scripts/gds/security-baseline-check.sh` item 6 flips to FAIL:
+
+1. **Stop**. Do not push, do not merge, do not delete the offending file from the working tree (yet).
+2. **Identify the credential** — what service, what scope, was it ever active in production.
+3. **Rotate the credential first** (steps 1-4 above). Treat the leaked value as compromised even if the scan was a pre-commit catch — the same value may have been pasted into a chat or a sibling file.
+4. **Then** rewrite the offending file (remove the credential) and commit. If the credential was already in pushed history, run `git filter-repo --replace-text <pattern>` to scrub it from every commit. This rewrites SHAs; force-push is required; CI scan re-validates afterward.
+5. **Document** — add an entry to [`docs/recipes/ops-gotchas.md`](../recipes/ops-gotchas.md) with the date, what happened, and what changed in the response so the next time it goes faster.
+6. **Forks + clones** — the rewrite doesn't reach existing clones. Anyone with an outdated clone gets a `git fetch` warning about non-fast-forward; they re-clone. Forks that mirror via GitHub's mirror feature need a manual `git push --force` from the upstream-aware operator.
+
+The cost of skipping step 3 is "the leaked credential keeps being a leaked credential, just out of sight." The cost of skipping step 5 is "next time, this is a 20-minute incident again."
+
+## Historical sweep
+
+A one-time scan of the full git history happened as part of this ADR (V3.R60, 2026-05-28). The repo was scanned for all in-scope secret shapes; **no hits were found**. The scan was performed with built-in tooling (`git rev-list --all --objects` piped through pattern grep) rather than TruffleHog because trufflehog was not yet installed on the builder's laptop at scan time and the CI scan covers the trufflehog-shape case continuously. The all-clear is documented here so a future operator doesn't repeat the sweep without cause.
+
+If a future audit *does* find a hit, follow "What to do when the scan finds a hit" above. The all-clear is point-in-time; a credential that lands tomorrow needs the same response.
+
+## Scrubbing secrets OUT of session uploads (the BFG corpus)
+
+The enforcement above keeps secrets out of the **repo**. A second egress exists: the BFG session-inefficiency evaluator ([ADR 0027](<redacted>.md)) uploads a digest of each Claude Code session to the GDS `sessions` corpus. A transcript contains every file read, command output, and pasted value — so the upload path is scrubbed by **the same policy, applied client-side at upload time**, in `scrubSecrets()` (`scripts/gds/ship.js`, used by both `ship.js` and `session-digest.js`).
+
+This scrubber is **transcript-grade** and **recall-first** (task 1003, which also completed the open token-redaction of task 723): a missed secret is a credential compromise, while over-redacting a non-secret in a BFG digest is merely cosmetic, so when in doubt it redacts. Five layers: (1) literal dynamic values — this run's GDS session token + every secret-shaped **env value** (`collectEnvSecrets()`, e.g. the `MAC_*`/`APPLE_*` signing creds, a baked GDS/DO token); (2) multi-line PEM private-key blocks; (3) the in-scope known shapes from this ADR (provider key prefixes, Stripe `sk_`/`rk_`/`whsec_`, our `gds_`/`pms_` tokens, `Authorization`/`Bearer` headers, JWTs, credentialed DSNs, Apple app-specific passwords); (4) recognised-key `key=value` / JSON-field assignments; (5) a **high-entropy catch-all** (`looksHighEntropySecret()`) over base64url/hex runs ≥20 chars — the net for an *unknown* secret shape. The accepted cost of layer 5 is that high-entropy non-secrets (git SHAs, UUIDs, a 40-hex value shape-identical to a GitHub OAuth client secret) are redacted too; the structured BFG metrics that matter (token/turn counts, tool names, error flags) are separate fields and untouched. The planted-secret corpus in `tests/scrubber_corpus.mjs` is the regression gate — every planted secret must be fully redacted, every benign line must survive — and **gates the full-transcript capture task**: capture must not ship until this passes.
+
+This scrubber is now a load-bearing enforcement surface alongside the pre-commit hook + CI scan; a change to the in-scope secret shapes above should update it (and its corpus) too, or the policy and the enforcement will drift.
+
+## Alternatives considered
+
+- **Use a cloud secrets manager.** Rejected: cost (~$0.40/secret-month at AWS), latency (an extra network hop on cold start), single point of failure (the manager being down blocks deploys). At ~10 secrets and one operator, the filesystem-permissions model is cheaper and not meaningfully less secure.
+- **Encrypt secrets in the repo (SOPS, git-crypt).** Rejected: shifts the problem from "don't commit the secret" to "don't lose the decryption key." The decryption key has to live somewhere; if it lives in the same repo, we've solved nothing; if it lives outside, we've reinvented the current `/etc/example/` model with extra steps.
+- **Skip the pre-commit hook; rely on CI alone.** Rejected: CI catches the leak after the secret has already been pushed to GitHub (where it's now in their cache, even if the PR closes). The pre-commit hook is the fast feedback that prevents the leak from leaving the laptop.
+
+## Consequences
+
+- New builders go through a one-line orientation: "creds live in /etc/example on the droplet, in ~/.config/otb/env or .env.local on your laptop, nowhere else." If they ask "but what if I want to commit one?" — the hook blocks them; if they push past the hook, CI blocks the merge.
+- The pre-commit hook + CI workflow + security-baseline-check item 6 are now load-bearing. A change to any of them needs to update this ADR too, or the policy and the enforcement will drift.
+- Rotation is the operator's responsibility (Lars). The team is informed via the chat broadcast; there is no automatic distribution of new secrets to builder laptops. This is a deliberate accept-the-friction choice — automatic distribution requires a secrets manager.

package/docs/adr/0023-kind-multipliers-and-idea-bonus.md

@@ -0,0 +1,118 @@
+# ADR 0023 — Kind multipliers + staged idea-promotion bonus
+
+**Date:** 2026-05-28
+**Context:** GDS-V3, task [#247](https://example.com/builders#/task/247) (V3.R27 — Kind multipliers + staged idea-bonus).
+**Status:** Accepted.
+
+## Problem
+
+Every task in the GDS carries a `credits_reward` value (the in-world "drachmae" payout when the task ships). Before this ADR, that value was paid 1:1 regardless of task kind. A 40-credit `cleanup` ship and a 40-credit `bug` ship both landed exactly 40c. That's a problem for two reasons:
+
+1. **It silently disincentivises the work we want more of.** Capturing a learning that prevents a future bug, resolving a blocker that was costing the builder days, or landing a decision/ADR are all *higher leverage* per builder-hour than the average feature. Paying them the same says "we don't care which you do." In practice we care a lot.
+2. **The idea_inbox economy was unfunded.** Anyone could capture an idea, get it triaged into a task, and the task's eventual shipper got 100% of the reward. The capturer earned 0 — even though the idea was the unblocker. Capturing felt like volunteer work.
+
+The fix has to be **small, transparent, and hard to game.** It can't be a sliding rubric the builder can argue with; it can't let a builder reclassify a task to chase 3× payouts; it has to leave a clear audit trail.
+
+## Decision
+
+Two coordinated changes, both at credit-grant time inside the existing `applyGrade` / `confirmTask` / `decideOverrideRequest` transactions:
+
+### 1. Per-kind multiplier table (frozen constant in src/bongos/db.js)
+
+```js
+const KIND_MULTIPLIERS = Object.freeze({
+  feature:             1.0,
+  bug:                 1.2,
+  'learning-capture':  1.5,
+  'blocker-resolution':1.5,
+  decision:            1.3,
+  infra:               1.0,
+  refactor:            0.9,
+  cleanup:             0.8,
+  spike:               1.1,
+  unclassified:        1.0,
+});
+```
+
+Applied at the moment a `task.confirmed` credit_log row is written. The `description` column (added in migration 031 for the net-negative bonus) records the math inline:
+
+```
+40c × 1.5 = 60c (learning-capture)
+```
+
+So an auditor reading credit_log later can reconstruct the payout without re-deriving the multiplier from the task's kind at read time.
+
+### 2. Staged idea-promotion bonus
+
+When a task ships and the task was promoted from `idea_inbox` (i.e. there exists a row with `idea_inbox.promoted_to_task_id = task.id`), the original capturer (`idea_inbox.captured_by`) receives **25% of the multiplier-adjusted reward**, rounded to the nearest integer drachma. Paid as a separate `credit_log` row with `reason='idea_promotion_bonus'` and an explanatory description.
+
+Guards:
+- **Idempotent** on `(task_id, reason='idea_promotion_bonus')` — a re-grade can't double-pay.
+- **No self-bonus**: if the same builder captured the idea AND shipped the task, no bonus is paid (they already got the full task reward).
+- **Only when capturer is set**: idea_inbox rows where `captured_by IS NULL` (legacy imports) skip the bonus.
+
+## Multiplier values + rationale
+
+The values fan out from `feature = 1.0` (the baseline kind) by no more than ±0.5×. Tight clamp on purpose: too narrow to make reclassification a meaningful exploit, wide enough to send a real signal.
+
+| Kind                | Mult  | Why                                                                                                    |
+| ------------------- | ----- | ------------------------------------------------------------------------------------------------------ |
+| `feature`           | 1.0×  | Baseline — every other value is "relative to a feature."                                               |
+| `bug`               | 1.2×  | Bug fixes prevent compounding failure. Slight bump to surface bug-finding as worthwhile-on-its-own.   |
+| `learning-capture`  | 1.5×  | High leverage: one captured learning saves N future debugging sessions. The most under-incentivised work in V2. |
+| `blocker-resolution`| 1.5×  | A resolved blocker unblocks every linked task. Same leverage argument as learnings.                   |
+| `decision`          | 1.3×  | ADRs / planning artifacts are durable. Worth more than a single feature; not as compounding as a learning. |
+| `infra`             | 1.0×  | Infra ships are large and valuable but already typically carry larger `credits_reward` values. No extra mult needed. |
+| `refactor`          | 0.9×  | Refactors are mostly neutral — useful when they're a precursor to a feature, dead weight when they aren't. Light penalty. |
+| `cleanup`           | 0.8×  | Cleanup is housekeeping. Necessary but not the work we want more of right now. Bigger penalty than refactor. |
+| `spike`             | 1.1×  | Spikes produce knowledge (ADRs, follow-up tasks). Small premium to encourage them when uncertainty is real. |
+| `unclassified`      | 1.0×  | Neutral — auto-classifier fallback. If a task lands here it should be re-kinded, not penalised.       |
+
+These are policy values. **They will be re-tuned at version close-out** (PMS retros) based on what mix of work we actually want for the next version. The fact that they live in a frozen constant in `db.js` (not a `kind_multipliers` table) is deliberate: changing them should require a code review and commit, not a `psql` UPDATE.
+
+## Idea-bonus rationale: why 25% and why a slice (not a flat fee)
+
+**Why a slice (not flat):** The bonus has to scale with the task's value. A 5c throwaway-idea task and a 200c platform-shift task can both come out of the inbox; flat-fee would over-reward trivial captures and under-reward important ones. Slice scales naturally.
+
+**Why 25%:** Big enough to be motivating (an idea that becomes a 100c bug-fix earns the capturer 25c — a meaningful chunk), small enough that the shipper still gets the majority share (their work is *executing* the idea, which is harder than capturing it). The shipper is paid 100% of the kind-adjusted reward; the capturer's bonus is *on top*, not deducted. (This is intentional. The marginal credit cost is real but small — most ideas come from the same handful of builders who would otherwise have shipped the work themselves.)
+
+**Why "no self-bonus":** Self-paying would degenerate to "every capture is a free 25%." That's not what the bonus is for — it's compensation for the social good of capturing an idea *that someone else then runs with*.
+
+## Consequences
+
+### Direct
+- All future ships pay out multiplier-adjusted credits. Old ships are untouched; their credit_log rows keep their NULL `description`.
+- Learning-capture / blocker-resolution / decision ships become more attractive. Cleanup / refactor become slightly less so. The discipline mix should shift accordingly over the next two weeks of shipping.
+- `idea_inbox.captured_by` becomes economically meaningful. Builders who triage and capture ideas now have a payoff curve. Capturing without expecting anything still works the same; capturing *deliberately* — knowing a bonus may follow — is rewarded.
+- The `Credits awarded:` line in `/builder-ship` output gains two new lines when relevant (kind multiplier breakdown and idea-promotion bonus). Audit trail is also visible by reading `credit_log.description` directly.
+
+### Indirect
+- **Game-the-system risk:** A builder could theoretically reclassify their `feature` task as `learning-capture` to chase 1.5×. Two safeguards:
+  - The auto-classifier (V2 [#122](https://example.com/builders#/task/122)) produces an opinion on `kind` at task creation; manual override is logged in `audit_log`.
+  - Subagent grader sees the kind in the prompt and can flag misclassifications in `issues[]`.
+  Worst case the swing is 0.5× — small enough that the friction of arguing the misclassification isn't worth the gain on most tasks.
+- **Bonus drainage risk:** If a power-user captures hundreds of ideas in idea_inbox and they all eventually get shipped by others, that user accumulates large bonus payouts without doing the work. This is a *feature*, not a bug — capturing high-quality ideas IS valuable work. If the pattern becomes pathological we can cap per-capturer bonuses per version in a follow-up.
+- **Re-grade idempotency:** Both the primary credit and the idea-bonus are guarded on the same `task_id` + `reason` key. A re-grade for the same task is a true no-op for both ledger rows.
+
+### Reversal posture
+
+This is reversible at policy level by editing `KIND_MULTIPLIERS` (uniform 1.0s + `IDEA_BONUS_FRACTION = 0` would restore the V2 behaviour). Already-paid bonuses stay paid (the ledger is append-only).
+
+### What changes vs. what stays the same
+
+| Before                                                          | After                                                                                                |
+| --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| 40c feature ships → 40c                                         | 40c feature ships → 40c (no change for the baseline)                                                 |
+| 40c cleanup ships → 40c                                         | 40c cleanup ships → 32c                                                                              |
+| 40c learning-capture ships → 40c                                | 40c learning-capture ships → 60c                                                                     |
+| credit_log row has NULL description                             | credit_log row has `40c × 1.5 = 60c (learning-capture)`                                              |
+| idea_inbox capturer earns 0 when their idea ships               | idea_inbox capturer earns 25% of the multiplied amount (rounded), if different from the shipper     |
+| One credit_log row per ship                                     | Up to two rows: `task.confirmed` (shipper) + optional `idea_promotion_bonus` (capturer)              |
+| `confirm` / `applyGrade` / `decideOverrideRequest` write 1× raw | All three paths route through `insertMultipliedConfirmCredit` + `maybeAwardIdeaPromotionBonus`        |
+
+## Cross-refs
+
+- Pairs with R32 (criterion-proposal workflow) — proposers will earn similar staged credit when their criteria land. Same shape, different source table.
+- Builds on migration 031 (V3.R93 [#354](https://example.com/builders#/task/354)) which added `credit_log.description` for the net-negative ship bonus.
+- Migration 041 (this task) reserves the migration number; the actual policy lives in code.
+- Cross-references the kind enum from migration 006 (V2): `feature, bug, infra, refactor, spike, learning-capture, cleanup, decision, blocker-resolution, unclassified`.

package/docs/adr/0024-cloneable-repo-local-first-memory.md

@@ -0,0 +1,277 @@
+# ADR 0024 — Cloneable repo + local-first memory with server-canonical sync
+
+**Date:** 2026-05-29
+**Context:** GDS-V3, spike [#230](https://example.com/builders#/task/230) (V3.R04 — Architecture spike: cloneability + local-first memory with server sync). Satisfies done-when criterion C8 (`cloneable-local-memory-server-sync`). Companion to [ADR 0016](<redacted>.md) (trust boundary — same enforcement boundary applies here) and [ADR 0022](0022-secrets-policy.md) (no secrets in repo — a precondition for "cloneable").
+**Status:** Accepted.
+
+> Numbering note: the spike's done-when named this ADR `<redacted>.md`, but `0016` was already taken by the trust-boundary ADR before this spike was opened. This ADR is **0024**. Same correction the R03 spike (ADR 0016) made for itself.
+
+## Problem
+
+GDS-V3 opens the system to more than one builder. Today there is exactly one builder (`example-owner`) on exactly one machine, so "memory" is whatever lives in `~/.claude/projects/<redacted>/memory/` on that one laptop. If that laptop dies, the memory is gone. If a Metic onboards from `git clone`, their memory starts empty and stays empty — there is no path for them to pick up where a previous session left off, even their *own* previous session on a different machine.
+
+We need an explicit answer to:
+
+1. **What is "memory" in this project, and why does it need to survive the laptop?** Distinct from the *code* (which `git` already handles) and distinct from the *system state* (which the GDS DB already handles).
+2. **Where does memory live canonically?** Local file, server DB, object store?
+3. **When does it sync, in which direction, on whose authority?**
+4. **What happens when two builders (or one builder on two machines) edit the same memory file?**
+5. **Can builder A read builder B's memory?** Under what conditions?
+6. **What happens when the server's memory store is wiped?**
+
+These cluster into five design choices: **schema**, **sync trigger**, **conflict policy**, **isolation**, **backup cadence**. The rest of this ADR is the choice made for each, with the rejected alternatives recorded so the trade-off survives the decision.
+
+## What "memory" means here
+
+Three distinct artifact classes live on a builder's laptop. Only one of them is in scope:
+
+| Artifact | Where canonical | Already solved? |
+|---|---|---|
+| Source code, ADRs, skills, migrations, CLAUDE.md | `git` (origin = `github.com/example-owner/example`) | ✅ yes — git is the answer |
+| Work state (tasks, claims, credits, learnings, idea_inbox) | GDS Postgres on droplet | ✅ yes — `/api/gds/*` is the answer |
+| **Claude Code's per-session memory dir** (`~/.claude/projects/<project>/memory/*.md`) | **Local laptop only** | ❌ no — this is what R04 designs |
+
+The third row is what this ADR addresses. It's the auto-memory Claude Code itself writes (e.g. `MEMORY.md`, `feedback_*.md`) plus any builder-authored persistent context that isn't code and isn't a GDS row. Today there's no path off the laptop; that is the gap C8 is trying to close.
+
+**Out of scope:** the GDS `learnings` table (already server-canonical, written via `node scripts/gds/learning-capture.js`), the `~/.config/otb/` directory (per-builder *secrets* — covered by ADR 0022, never synced), and the art pipeline's iteration ledger (already in-repo at `art/iterations/`). If a thing is already on the server or already in git, it is not "memory" in this ADR's sense.
+
+## Decision
+
+Five choices, each forced into the simplest viable shape unless the simple version actively breaks. Default posture per CLAUDE.md §4: choose cheap and small; pay complexity only when the simple version visibly fails.
+
+### 1. Schema — Postgres TEXT in one new table
+
+A new table `builder_memory(builder_id, path, content TEXT, mtime, sha256, byte_len, PRIMARY KEY (builder_id, path))` on the existing GDS Postgres. Per-file rows; `path` is the relative path under the builder's memory dir (e.g. `MEMORY.md`, `feedback_auth_flows_ui_first.md`). Content stored as `TEXT` (not `BYTEA`) because memory files are markdown — readable in `psql` for forensics is a meaningful Archon convenience.
+
+**Limits** (enforced at the helper layer in [#273](https://example.com/builders#/task/273) R54):
+
+- Per-file cap: **1 MB**. Memory files measured today are kilobytes; 1 MB is 1000× headroom and stops a runaway loop from filling the row.
+- Per-builder cap: **50 MB total**. 50,000× current observed size. A sync that would exceed the cap returns `413 memory_quota_exceeded` and is logged; the builder is told what to prune.
+- Per-builder file count cap: **2000 files**. Defensive.
+
+**Rejected: object storage (DO Spaces / S3).** Adds $5/mo minimum + an SDK dependency + a second auth-token surface + a second backup story. For files measured in kilobytes, with backup already free from `pg_dump`, this is buying complexity to solve a problem we don't have. Revisit only when (a) we see per-file sizes routinely above 100 KB or (b) total table size exceeds ~1 GB and `pg_dump` time becomes painful.
+
+**Rejected: git-backed memory** (push to a per-builder branch in the repo). Tempting because git is already there, but it conflates *code-king* artifacts with *per-builder mutable scratch* — and worse, it would expose one builder's memory diffs in the public repo, contradicting the isolation requirement (§4 below).
+
+### 2. Sync trigger — lifecycle-event push + pull, no daemon
+
+Two trigger points, both transactional boundaries that already exist in the methodology:
+
+- **Push on `/builder-ship`.** After the ship completes successfully (drachmae landed, branch merged or queued), `scripts/gds/ship.js` walks `~/.claude/projects/<project>/memory/*` and calls `POST /api/gds/memory/sync` with each file. If the push fails, ship still succeeds — work is preserved in the GDS row, memory can be resynced next time. Progress visible to the builder ("syncing 3 memory files…"). This is what [#274](https://example.com/builders#/task/274) R55 implements.
+- **Pull on `SessionStart` hook + `/builder-start`.** A new hook (or extension of the existing `.claude/hooks/sync-env-local.sh` pattern) calls `GET /api/gds/memory/since?mtime=<local-newest>` and writes any files the server has that are newer than the local copy. This is what [#275](https://example.com/builders#/task/275) R56 implements.
+
+No background polling. No Claude-Code-side daemon. No mid-session sync. The two trigger points are predictable, debuggable, and align with the natural commit/restart boundaries builders already think in.
+
+**Rejected: every-N-minutes background sync.** A daemon means a process to start, a process to stop, a place for it to log, a place for it to fail silently. The marginal benefit (memory survives a `kill -9` mid-session) is small — the same session is probably about to re-write the file anyway.
+
+**Rejected: sync on every Claude Code tool call.** Per-tool-call HTTP is a perceptible latency tax on every `/builder-*` interaction. Not worth it.
+
+### 3. Conflict policy — last-write-wins per file, server clock authoritative
+
+When the push handler receives a file, it compares the incoming `mtime` against the stored row. **Newer wins.** No merge, no rejection, no warning. The server's clock decides which `mtime` is "newer" (clients are not trusted to set the future-mtime trick).
+
+The expected collision shape is **one builder, two machines** — e.g. Lars edits memory on the desktop, then later on the laptop. Push from laptop overwrites the desktop's version. Pull-on-start brings the laptop's version back to the desktop next session. The lost-write window is "the time between push-A and pull-B," which in practice is one session boundary — recoverable from backup (§5) if a real loss occurs.
+
+Two-builders-same-builder-id is impossible by construction: `builder_id` is the unique GitHub user, not a session.
+
+Two-builders-different-builder-id on the same file is impossible by construction: paths are namespaced by `builder_id` (§4).
+
+**Operator escape hatch:** the conflict-resolution recipe (`docs/recipes/memory-sync-conflicts.md`, shipped by [#277](https://example.com/builders#/task/277) R58) documents how to restore an older version of a file from `pg_dump` if a builder confirms a clobber.
+
+**Rejected: three-way merge for markdown files.** Tempting (markdown diffs reasonably well), but the failure mode — a half-merged `MEMORY.md` that looks plausible but is structurally broken — is worse than the simple lose-one. Defer to V4 and only if we observe real collisions in V3.
+
+**Rejected: optimistic concurrency (reject pushes whose base-mtime is stale, force a pull-first).** Adds a step builders will work around by `--force`-ing. Push-then-overwrite is simpler and the recovery path (backup) handles the rare bad case.
+
+### 4. Isolation — server enforces `req.builder.id === path_owner.builder_id`
+
+All memory endpoints (`POST /memory/sync`, `GET /memory/since`, `GET /memory/files`, `GET /memory/files/:path`) check that the requester's `req.builder.id` matches the row's `builder_id` before reading or writing. Mismatch returns `403 memory_forbidden`. The check happens in the route handler, after `requireBuilder`, before any DB work. Same trust-boundary posture as [ADR 0016](<redacted>.md): the server enforces; nothing the builder can edit locally can grant cross-builder access.
+
+**Archon forensic exception — read-only.** An Archon-only endpoint `GET /memory/builders/:id/files` exists for restore + forensics use cases (e.g. a builder offboards, Archon needs to inspect their memory; a corrupt file needs restoration). Every Archon read is logged to `audit_log` with `actor_builder_id`, `target_builder_id`, `path`, `reason`. **There is no Archon write endpoint.** Restores happen via `pg_restore` into a sandbox schema, never live. Read-only is the V3 posture; cross-builder *reads* are likely to be relaxed in a later version (e.g. Metics seeing each other's memory for collaboration), but cross-builder *writes* through the API are not on the roadmap. Any future relaxation requires a superseding ADR.
+
+In V3: no other rank gets cross-builder access. Not Metic, not Thetes. Not for any reason short of an ADR-supersede.
+
+### 5. Backup cadence — ride the existing `pg_dump`
+
+`builder_memory` is a Postgres table. It rides whatever backup cadence the GDS DB has.
+
+> **Precondition (confirmed during this spike):** the GDS DB does **not** currently have a nightly `pg_dump` cron. R62 ([#281](https://example.com/builders#/task/281)) therefore has two parts: (a) stand up nightly `pg_dump` for the whole GDS DB (which `builder_memory` then inherits for free), and (b) the restore drill + recipe doc. Part (a) is the gating dependency for flipping C8 — until backups are real, the "server-canonical" half of C8 is unverified. A follow-up task is filed for part (a) so it's not buried inside R62's scope.
+
+**Target cadence:** nightly `pg_dump` to a separate volume on the droplet + weekly off-droplet archive (Backblaze B2 or DO Spaces — the cheapest target). **Retention:** 30 days rolling daily + 12 weekly archives. **Drill:** quarterly. Pick a random builder, restore their `builder_memory` rows from yesterday's dump into a sandbox schema, diff against live, confirm match. Documented in `docs/recipes/memory-backup.md`, shipped by [#281](https://example.com/builders#/task/281) R62.
+
+**Cost ceiling:** $1–2/month for off-droplet storage at expected memory sizes (GDS DB is currently <100 MB total; 12 weekly archives = ~1.2 GB; B2 cold tier is ~$0.005/GB/mo). Inside the $5K/year envelope without trouble.
+
+## Trust-model + sync diagram
+
+```
+                  Builder's local machine (cloneable from git)
+   ┌────────────────────────────────────────────────────────────────────┐
+   │   git clone repo  +  /builder-setup (Gemini key, Anthropic link)   │
+   │                                                                    │
+   │   ~/.claude/projects/<project>/memory/                             │
+   │   ├── MEMORY.md          (Claude Code auto-memory)                 │
+   │   ├── feedback_*.md      (rules captured from feedback)            │
+   │   └── …                                                            │
+   │                                                                    │
+   │   ▲                                  │                             │
+   │   │ pull (on SessionStart            │ push (on /builder-ship)     │
+   │   │  + /builder-start)               │                             │
+   └───┼──────────────────────────────────┼─────────────────────────────┘
+       │                                  │
+       │   HTTPS + Bearer/Cookie session token  (identity, not authority)
+       │                                  │
+============================== TRUST BOUNDARY ==============================
+       │                                  │
+       ▼                                  ▼
+   ┌────────────────────────────────────────────────────────────────────┐
+   │  GDS server  (single droplet, Node + Postgres)                     │
+   │                                                                    │
+   │   POST /memory/sync          GET /memory/since?mtime=...           │
+   │       │                          │                                 │
+   │       ▼ requireBuilder           ▼ requireBuilder                  │
+   │       ▼ isolation check          ▼ isolation check                 │
+   │       ▼  (req.builder.id ==      ▼                                 │
+   │           path_owner_id)                                           │
+   │       │                          │                                 │
+   │       ▼                          ▼                                 │
+   │   ┌────────────────────────────────────────────────────────────┐   │
+   │   │  builder_memory (builder_id, path, content TEXT,           │   │
+   │   │                   mtime, sha256, byte_len)                  │   │
+   │   │                                                              │   │
+   │   │  ► last-write-wins on push (server clock)                    │   │
+   │   │  ► quota: 1 MB/file · 50 MB/builder · 2000 files/builder    │   │
+   │   │  ► forensic read: Archon only, audit-logged                  │   │
+   │   └────────────────────────────────────────────────────────────┘   │
+   │                                                                    │
+   │   ┌────────────────────────────────────────────────────────────┐   │
+   │   │  Nightly pg_dump → droplet volume; weekly archive offsite  │   │
+   │   │  30 daily + 12 weekly retention; quarterly restore drill   │   │
+   │   └────────────────────────────────────────────────────────────┘   │
+   └────────────────────────────────────────────────────────────────────┘
+```
+
+## Implementation sub-tasks (C8)
+
+These already exist as seeded GDS-V3 tasks; this spike sets `parent_task_id = 230` on each so the lineage is explicit. The spike **does not reshape their scope** — the design decisions above match the assumptions the seeds were drafted under. If any seed description references an assumption this ADR overrode, the task description gets a follow-up edit in the same ship.
+
+| Task | What it builds | Encodes which decision |
+|---|---|---|
+| [#273](https://example.com/builders#/task/273) (V3.R54) | `builder_memory` schema + `storeMemoryFile / fetchMemoryFile / listMemoryFiles` helpers, per-builder isolation at helper layer | §1 (schema), §4 (isolation) |
+| [#274](https://example.com/builders#/task/274) (V3.R55) | `/builder-ship` reads local memory dir, calls `POST /memory/sync`, progress UX | §2 (push trigger) |
+| [#275](https://example.com/builders#/task/275) (V3.R56) | SessionStart / `/builder-start` reads `/memory/since`, writes newer files locally, last-write-wins | §2 (pull trigger), §3 (conflict policy applied client-side too) |
+| [#276](https://example.com/builders#/task/276) (V3.R57) | Every memory endpoint asserts `req.builder.id === path_owner_id`; Archon forensic-read endpoint with audit log | §4 (isolation enforcement) |
+| [#277](https://example.com/builders#/task/277) (V3.R58) | `docs/recipes/memory-sync-conflicts.md` — operator playbook for clobber recovery, parallel-session warning | §3 (conflict policy doc) |
+| [#280](https://example.com/builders#/task/280) (V3.R61) | `portability-smoke-memory.sh` + `portability-smoke-art.sh` — fresh-clone → ship → re-clone → memory restored | validates the whole stack end-to-end |
+| [#281](https://example.com/builders#/task/281) (V3.R62) | Nightly `pg_dump` + weekly offsite archive + restore drill + `docs/recipes/memory-backup.md` | §5 (backup cadence) |
+
+Already shipped under C8 (kept here for reference): [#278](https://example.com/builders#/task/278) R59 (.env.local propagation), [#279](https://example.com/builders#/task/279) R60 (secrets-in-repo scan, + ADR 0022).
+
+## Portability test plan
+
+The validation gate C8 ultimately answers: **"a Metic with no prior project state can clone, set up, ship, and have their memory follow them to a second machine."** Decomposes into a scripted smoke test ([#280](https://example.com/builders#/task/280) R61) and a manual rehearsal that runs before C8 is flipped to satisfied.
+
+### Scripted smoke (`scripts/gds/portability-smoke-memory.sh`)
+
+Runs on staging, ideally nightly in CI. Uses a synthetic Metic account.
+
+> **Path-encoding gotcha (important for the implementer of [#280](https://example.com/builders#/task/280) R61):** Claude Code does NOT store memory at `~/.claude/projects/$PWD/...`. It hyphen-encodes the absolute project path — every `/` becomes a `-`. So a project at `/Users/lars/foo/bar` lives at `~/.claude/projects/-Users-lars-foo-bar/`. The smoke script must resolve the real encoded path; do not use `$PWD` directly. The exact encoding rule may shift across Claude Code versions, so prefer querying it via `claude` CLI or inspecting `~/.claude/projects/` after a session start over hard-coding the substitution.
+
+```
+# Phase 0 — helper to resolve the encoded Claude Code memory dir for this checkout.
+# Strategy: derive it from the absolute project path, with a verification step that
+# fails loudly if the encoded dir doesn't appear after a SessionStart trigger.
+encode_project_dir() {
+  # Hyphen-encode the absolute path. If Claude Code's rule changes, replace this
+  # with a CLI query and bump the smoke script — do NOT silently let the path drift.
+  printf '%s' "$1" | sed 's|/|-|g'
+}
+
+# Phase 1 — bootstrap from cold
+WORK=$(mktemp -d)
+cd "$WORK"
+git clone https://github.com/example-owner/example.git
+cd example
+PROJECT_DIR="$PWD"
+MEM_DIR=~/.claude/projects/"$(encode_project_dir "$PROJECT_DIR")"/memory
+./scripts/setup-builder.sh                       # Node, Python, npm ci, …
+TEST_GDS_TOKEN=<redacted> ./scripts/gds/auth-from-env.sh
+
+# Phase 2 — capture a memory file pre-ship
+mkdir -p "$MEM_DIR"
+echo "smoke marker $(uuidgen)" > "$MEM_DIR/portability-smoke.md"
+MARKER=$(cat "$MEM_DIR/portability-smoke.md")
+
+# Phase 3 — claim + ship a known no-op task
+node scripts/gds/claim.js <staging-portability-task>
+# (the no-op task has zero-touch scope: it just exists for this drill)
+node scripts/gds/ship.js <id> --notes "portability smoke" --summary "portability smoke"
+
+# Phase 4 — wipe local memory + repo, re-clone, verify pull
+rm -rf "$MEM_DIR"
+WORK2=$(mktemp -d)
+cd "$WORK2"
+git clone https://github.com/example-owner/example.git
+cd example
+PROJECT_DIR_2="$PWD"
+MEM_DIR_2=~/.claude/projects/"$(encode_project_dir "$PROJECT_DIR_2")"/memory
+TEST_GDS_TOKEN=<redacted> ./scripts/gds/auth-from-env.sh
+node scripts/gds/start.js                        # triggers pull
+# The pull writes to MEM_DIR_2 (encoded for the *new* checkout path); the GDS
+# sync logic must key memory by builder_id, not by local path, so files restore
+# regardless of where on disk this checkout lives.
+test "$(cat "$MEM_DIR_2/portability-smoke.md")" = "$MARKER"
+echo "OK — memory survived clean reclone"
+```
+
+Failures file an idea_inbox row tagged `portability-regression` for follow-up.
+
+### Manual rehearsal (one-time, gates C8-satisfied flip)
+
+Lars (or a stand-in) runs the full flow with a stopwatch, on a fresh laptop / VM:
+
+1. Fresh macOS or Linux box — no prior project artifacts, no `~/.claude`, no `~/.config/otb`.
+2. Stopwatch starts.
+3. `git clone` → `./scripts/setup-builder.sh` → `/builder-setup` (real browser auth).
+4. `/builder-start` → claim a `newcomer_friendly` task.
+5. Do the task, `/builder-ship`. (This pushes memory.)
+6. Wipe `~/.claude` entirely.
+7. On the same box: `git clone` to a fresh dir → `/builder-setup` (re-auth) → `/builder-start`.
+8. Confirm `~/.claude/projects/.../memory/` contains the files from step 5.
+9. Stopwatch stops. Note total elapsed time for the C1 onboarding-2h reference.
+
+## Alternatives considered
+
+**Sync via git** — push memory to a per-builder branch in the repo, e.g. `memory/<github-login>`. Rejected for three reasons: (a) leaks each builder's memory diffs to anyone with read on the repo, contradicting §4 isolation; (b) couples memory size to repo size (clones get heavier over time); (c) requires `git push` to be a viable operation from inside `/builder-ship`, which it already isn't on the no-`git` paths (mobile, sandboxed).
+
+**Sync via DO Spaces (S3-compatible object storage)** — see §1 rejection. Right answer if file sizes were megabytes or if Postgres backup became painful; wrong answer for our actual data shape.
+
+**Server-canonical, no local copy** (every memory read fetches from server) — rejected because Claude Code reads `~/.claude/projects/<...>/memory/*.md` directly from disk and rewriting that is out of scope. Local-first is mandatory for the way Claude Code already works.
+
+**Local-only, never sync** — rejected because it fails C8: a builder's memory does not follow them across machines, and a dead laptop loses memory forever. Today's de-facto state, not the V3 target.
+
+**Encrypted-at-rest (client-side encryption with per-builder key)** — rejected for V3. The server is single-tenant on a single droplet that already holds the GDS DB; encrypting memory at rest doesn't change the threat model (anyone with droplet root sees everything anyway). Revisit if (a) the server becomes multi-tenant, (b) we move to a managed Postgres where the operator can read rows, or (c) a builder requests it explicitly.
+
+**Per-session memory snapshotting (every Claude tool call writes a delta)** — rejected as over-engineered. The information content of "memory after a session" is approximately the same as "memory at ship time"; per-tool-call deltas are noise.
+
+## Consequences
+
+**Good:**
+- One table, two endpoints, two triggers — the smallest possible surface that satisfies C8.
+- No new infra cost. Rides Postgres + existing `pg_dump`.
+- Memory follows the builder across machines and across worktrees on the same machine.
+- A wiped laptop is recoverable in two commands (`git clone` + `/builder-start`).
+- Trust boundary is the same one [ADR 0016](<redacted>.md) already established — no new authority concept to reason about.
+- Forensic access exists (for Archon) but is audit-logged, so misuse is visible.
+
+**Costs:**
+- A new sync step in `/builder-ship` slows ship by however long `POST /memory/sync` takes. Expected p50: <500 ms for typical memory dirs (kilobytes, ~3 files). Cap the wall time; if the push hangs, log + continue rather than block ship.
+- Last-write-wins means the rare two-machine collision *will* lose one side's edit. Acceptable because (a) the same builder typically intends to overwrite, (b) `pg_dump` makes it recoverable, (c) the alternative (true merge) is much more complex for less than 1× the rare-event benefit.
+- The 1 MB per-file cap and 50 MB per-builder cap are *guesses*. If real-world memory grows past them we either raise the cap or prune. Both are cheap; the guess being wrong is not load-bearing.
+
+**Operationally:**
+- Backup cadence has to be real before the first non-Lars builder pushes memory. Precondition check on R62: confirm GDS DB is in a `pg_dump` cron before C8 is flipped. If not, that's the first task to ship under R62.
+- `docs/recipes/memory-sync-conflicts.md` (R58) needs to land before the manual rehearsal, so the playbook exists when a collision is observed.
+- The onboarding diagram of the memory layer originally labelled the server-side store "PLANNED: R54–R62, mostly backlog." After this spike + R54–R62 shipped, that label was dropped. (That diagram, `04-server-repo-memory`, was later merged with the dev-box diagram into the single `04-architecture` map under [#1059](https://example.com/builders#/task/1059); it is now auto-generated and reads LIVE.)
+
+**Implementation notes that reach into other criteria:**
+- The isolation check in §4 IS a privileged-route addition. The periodic rank-check auditor ([#265](https://example.com/builders#/task/265) / V3.R45) needs to learn about the new memory endpoints so it asserts they're gated. Captured as a follow-up note on R57 ([#276](https://example.com/builders#/task/276)).
+- The audit-log entry on Archon forensic reads is a security surface; the security review ([#288](https://example.com/builders#/task/288) V3.R69) should include it once the endpoint exists.