@bongos/core 1.18.0 → 1.18.18

package/docs/recipes/parallel-goal-waves.md

@@ -0,0 +1,174 @@
+# Running a goal as parallel worktree waves
+
+How to take a goal with ~20 tasks and ship it with several agents building at once, one worktree per claim.
+
+Written from the 2026-07-30 session that shipped 14 tasks off goal 1000030 (Governance — configurable roles & permissions). **This records what actually worked, which differed from the plan we started with.** The differences are the point.
+
+---
+
+## The one-paragraph version
+
+Dependencies tell you what must **ship** first. They tell you nothing about what can be **edited** at the same time. Work out the file-conflict graph yourself, run the disjoint set in parallel worktrees, and serialise anything that touches the same file. Claim the parallel set with `POST /claims/batch` (`claim.js` can only hold one claim per machine). Expect the plan's own dependency edges to be wrong somewhere, and expect one shared doc file to become the merge-conflict tax.
+
+---
+
+## 1. Read the DAG, then don't trust it
+
+Start by pulling the real graph — status, `dependencies[]`, `dependents[]`, and `requires_rank` for every task on the goal:
+
+```
+node scripts/gds/api.js GET "/api/gds/tasks?goal_id=<goal>&limit=100"
+node scripts/gds/api.js GET "/api/gds/tasks/<id>"     # includes dependencies + dependents
+```
+
+> **Gotcha (cost us ~40 minutes).** The generated API client wraps responses as `{status, ok, data:{...}}`. Reading `res.tasks` gives `undefined` and every dependency array silently looks empty — which reads as "this goal has no dependencies at all". Unwrap `.data` first. An empty dependency graph should make you suspicious, not relieved.
+
+Then **audit the edges for direction errors before scheduling anything**. Two of goal 1000030's edges were backwards, and each cost a full task cycle:
+
+- **The checker recorded as depending on the thing it checks.** R109 (teach the CI fitness gate to understand the new gate form) was recorded as depending on R104 (migrate the gates). But migrating gates without teaching the checker made every migrated route classify as `any-builder` — a silent downgrade that tripped exact-rank pins. R104 could not pass its grade until R109 shipped, and R109 could not be claimed until R104 shipped. **Deadlock.** Fix: `PUT /tasks/:id/dependencies` to reverse it. The heuristic — *if task B validates task A's output, B is usually A's prerequisite, not its dependent.*
+- **A migration racing ahead of a missing writer.** The plan migrated ~80 authority gates onto a new resolver, but nothing ever wrote the table the resolver reads outside a one-shot backfill. Any account created or re-ranked afterwards would have resolved to zero permissions — and a demoted account would have kept its old powers. Found only because one task's agent reported it instead of coding around it. Fix: file the missing work as a task, then `PUT /tasks/:id/dependencies` to gate the migration tasks behind it.
+
+**Do not let a wrong edge stand because fixing it feels like process work.** A backwards edge deadlocks a whole chain, and the deadlock presents as an unexplained grade failure several hours later.
+
+---
+
+## 2. Build the file-conflict graph — this is the real gate
+
+`dependencies[]` is a *ship* ordering. Parallel safety is a *file* question, and `touches[]` is advisory and frequently empty. So derive it yourself: read each task's description and predict the files it will edit.
+
+Then group:
+
+- **Parallel-safe** — no file overlap with anything else in the wave.
+- **Serialised** — two tasks edit the same file, so they run back-to-back regardless of what the DAG says.
+
+Worked example from goal 1000030:
+
+| Wave | Ran in parallel | Why the rest was held |
+|---|---|---|
+| 0 | resolver + kernel port ‖ config loader | disjoint: new module files vs `config/*.json` |
+| A | the gate primitive ‖ the protected-surface registry | both touched different core files; three others all edited `catalog.js`+`resolver.js` and were serialised behind them |
+| B | a proof test ‖ the core-route migration | test files collide with nothing |
+| C | module-route migration alone | it owns every `modules/*/routes/*.js`, so nothing else in that tree could move |
+
+**Heuristics that held up:**
+- A task whose whole output is a new test file is parallel-safe with everything. Schedule these freely.
+- A task that "migrates all X" owns its entire tree for the duration. Run the narrow, specific tasks in that tree **first**, then let the sweep absorb the remainder and rebase onto them. Running the sweep first forces every narrow task to conflict with it.
+- Two tasks extending the same registry/catalog file always serialise, even when their subject matter is unrelated.
+
+---
+
+## 3. Claiming a parallel set
+
+`claim.js` **cannot hold concurrent claims from one machine.** The app-layer guard permits one claim per *worktree*, but `uniq_active_claim_per_session` (`migrations/180`) is keyed on `creator_session_id` alone — worktree-blind — and the stricter of the two wins. Every worktree on a box shares one CLI session token, so the second `claim.js` fails.
+
+Worse, it fails with a **misleading** message: `claimTask` maps any Postgres `23505` to `ALREADY_CLAIMED`, so you are told *"Task #N was just claimed by another session"* when nothing is claimed and no retry will ever succeed. Two separate agents burned a full investigation each on this before the cause was found. (Filed as idea 1000617.)
+
+**Use the batch endpoint**, which was built for exactly this:
+
+```
+node scripts/gds/api.js POST /api/gds/claims/batch \
+  --body-file batch.json     # {"task_ids":[111,222,333],"bind_session":false}
+```
+
+`bind_session:false` stores each claim with a NULL session, which is the supported web-claim mode; many NULLs coexist. The safety property that matters — one task per worktree, one branch per ship, no commingled commits — is preserved, because you still give each task its own worktree.
+
+```bash
+git worktree add .claude/worktrees/task-<id> -b worktree-task-<id> origin/main
+```
+
+Always branch from a **freshly fetched `origin/main`**, not from local `main`.
+
+---
+
+## 4. Briefing an agent per worktree
+
+Each agent gets one task, one worktree, and an explicit **do-not-touch list** naming the files its siblings own. That list is what makes parallelism safe, so keep it accurate as the wave progresses.
+
+Include in every brief:
+
+- the absolute worktree path, and "never edit the main checkout, never `git push origin main`, never merge to main yourself"
+- the claim is **already held** — tell them not to run `claim.js` (it will fail, per §3)
+- the **known-red test baseline**, by name. If the suite is red on `main` for environmental reasons, an agent that doesn't know will either chase ghosts or quietly assume its own regressions are pre-existing. Give them the exact list and the technique: `git stash push -u`, re-run the suspect test on the clean tree, compare.
+- **report findings, don't fix them.** An agent that patches a defect in a sibling's file creates a conflict and hides a bug. Several of this session's most valuable findings came from agents that stopped and reported.
+- **mutation-test your own tests.** The highest-value defect class here is a test that passes while proving nothing — one agent shipped a first draft where both sides of the comparison read the same field, so mutating it moved both sides together and nothing went red. Require: break the thing deliberately, confirm red, revert, report that you did it.
+
+---
+
+## 5. The merge-conflict tax
+
+One file will become the contention point. Here it was the module's nested `CLAUDE.md`: four agents each appended to the same "build plan" line, and the resulting conflicts stalled two ships and needed manual recovery.
+
+**Mitigations, best first:**
+
+1. **Don't share the file.** The task that avoided the problem entirely needed a new kernel port, and registered it from a **new** file rather than editing the contended one. Prefer adding a file over editing a shared one.
+2. **Assign disjoint regions.** If several agents must edit one doc, give each a *specific* slot ("one bullet appended at the end of the Gotchas list", "one paragraph immediately after the R95 block") and forbid reflowing anything else. Different regions usually auto-merge.
+3. **Accept and recover.** A conflict is a bail, not a corruption — the task parks at `confirmed` and nothing is lost.
+
+**Generated files: always resolve by regenerating, never by picking a side.**
+
+```bash
+git checkout --theirs <file>
+node scripts/gds/gen-repo-map.js      # or gen-api-docs.js, gen-diagrams.js
+git add <file> && git commit --no-edit
+```
+
+Picking a side leaves the artefact inconsistent with source, and the freshness fitness check fails on the *next* task instead of yours. The generated symbol blocks and the OpenAPI spec both bit us this way.
+
+> If `ship.js` says *"auto-merge: bailed; task stays at confirmed"*, don't reach for `/merge-mode` first. Merge `origin/main` into the **task's own branch**, resolve there, re-run `fitness.js`, then re-run `ship.js <id>` — it resumes from `confirmed`. `/merge-mode` is an operator procedure that mutates the main worktree and assumes a bash/SSH environment.
+
+---
+
+## 6. Treat the ship grade as a noisy signal
+
+The subagent grader gates on **forwarded confidence**, not just scores. A worker that times out returns no vote, which collapses confidence and fails work that has **no defect finding against it**.
+
+Observed in one session: two tasks failed on a worker `SUBAGENT_TIMEOUT` and passed on retry **with zero code change**; another failed three times at 8.5–9.5/10 against a threshold of 6 with 4 of 5 workers passing every time.
+
+Practical rules:
+
+- **Capture the full grader output.** Do not pipe `ship.js` through `tail` — you will lose the finding and have to pay for another run. Redirect to a file.
+- **Read the per-worker table before reacting.** "4/5 PASS, verdict CONCERNS, confidence 0.3" is an infrastructure failure. "1 worker FAIL" is a real defect.
+- **A re-grade is the right first response** to a timeout-shaped failure. It is also not free — budget for it.
+- **A pass is not evidence either.** A gate this noisy can wave things through. Run a separate adversarial review over the finished work.
+- When the grader repeatedly flags a deliberate architecture decision, that is a signal to **record the decision** (an ADR or a triaged idea) rather than to keep re-litigating it per task — each re-grade costs real money.
+
+---
+
+## 7. Run an adversarial review at the end
+
+Fan reviewers out over surfaces, then have **every finding attacked by an independent skeptic prompted to refute by default**. On this goal that pass killed 6 of the top 8 findings — including three that were confidently written and wrong. Two survived, both reproduced end-to-end against the live module, and both were real.
+
+What made it work:
+
+- Tell reviewers explicitly **not to inherit the ship grades' verdicts**, and to re-derive security claims from the code.
+- Give the skeptics the failure modes to check: is the path actually reachable? is there a compensating control? is this a documented deliberate decision?
+- Name the highest-value defect class up front. Here it was tests whose expectation derives from the same code under test.
+- Findings that are never adversarially verified should be **recorded as unverified**, not reported as defects. With a 6-of-8 refutation rate, an unverified finding is more likely wrong than right.
+
+---
+
+## Checklist
+
+```
+[ ] Pull the real DAG; unwrap .data; be suspicious of an empty dependency graph
+[ ] Audit edge DIRECTION — does anything validate its own prerequisite?
+[ ] Predict files per task; build the conflict graph; group parallel vs serialised
+[ ] Narrow tasks in a tree BEFORE the sweep that owns that tree
+[ ] git worktree per task, branched from a fresh origin/main
+[ ] POST /claims/batch with bind_session:false (NOT claim.js)
+[ ] Brief each agent: worktree path, do-not-touch list, known-red baseline,
+    report-don't-fix, mutation-test your tests
+[ ] Assign disjoint regions in any shared doc; prefer a new file
+[ ] Regenerate generated files on conflict; never pick a side
+[ ] Capture full grader output to a file; read the per-worker table
+[ ] Adversarial review at the end; record unverified findings as unverified
+```
+
+---
+
+## Provenance
+
+Goal 1000030 (Governance — configurable roles & permissions), 2026-07-30. 14 tasks shipped; 5 defects found that were outside any task's scope, the most serious being that a demoted builder retained their previous powers because nothing kept role assignments in sync with rank.
+
+Related ideas: 1000617 (session-claim guard vs index), 1000618 (legacy ranks resolve to zero permissions), 1000624 (uncached per-request resolve — ADR 0016 tension), 1000625 (`guards` prose has no oracle), 1000626 (unverified review backlog).
+Related tasks: 1002550, 1002551, 1002552, 1002553, 1002554.

package/docs/recipes/ship-and-regrade.md

@@ -11,8 +11,8 @@
 `/builder-ship` runs three transitions ([Phase 5](../session-logs/<redacted>.md)):
 
 1. **`completed`** — the claim resolves once local verification (smoke) passes. **The claim is consumed here.**
-2. **`confirmed`** — the v2 subagent quality grader (the 4-worker panel: Narc · Quality · Hacker · Efficiency Monger) passes. **Credits land here.**
-3. **`shipped`** — branch auto-merged to `main` + deployed; the Discord `#ship-news` broadcast fires.
+2. **`confirmed`** — the v2 subagent quality grader (the 4-worker panel: Narc · Quality · Hacker · Efficiency Monger) passes. **Verified, but not yet paid.**
+3. **`shipped`** — branch auto-merged to `main` + deployed; the Discord `#ship-news` broadcast fires. **Credits land here** ([ADR 0120](../adr/<redacted>.md) pays on land, not on confirm) — so a task stranded at `confirmed` is unpaid until it lands.
 
 The grader reads **committed history** (`merge-base origin/main HEAD`…`HEAD`), independent of touches[] — so the diff it judges is whatever you've committed on the branch, not your working tree.
 

package/docs/recipes/standalone-live-docs.md

@@ -0,0 +1,48 @@
+# Recipe — live-updating docs on a STANDALONE instance
+
+**Read before:** standing up / debugging a standalone instance whose `docs/` is empty or stale.
+**Decision of record:** [ADR 0147](../adr/<redacted>.md) (builds on [ADR 0110](../adr/<redacted>.md) / [ADR 0108](../adr/<redacted>.md)).
+
+## The mental model — which doc refreshes where
+
+A standalone instance (its own repo + `@bongos/core` vendored in `node_modules`) has several *generated* docs. They do **not** all refresh the same way:
+
+| Doc | Kind | Refreshes | Committed? |
+|---|---|---|---|
+| `docs/session-log-index.md` | whole-file, instance content | **deploy** (`regen-instance-docs.js`) + `bongos upgrade` + init seed | **gitignored** |
+| `docs/api/openapi.json`, `docs/api-reference.md`, `docs/routes-permissions.md` | generated from routes | `bongos init` + `bongos upgrade` | tracked/committed |
+| `docs/file-map.md` | hybrid (prose + generated sections) | ship-time | tracked/committed |
+| `docs/repo-map.md` | CORE symbol map | shipped with `@bongos/core` (core-scoped) | gitignored |
+| onboarding diagrams (`.svg`/`.png`) | rendered | package/CI time (headless browser) | gitignored renders, tracked `.mmd` |
+
+Only `session-log-index.md` is regenerated **on deploy** — it's the one whole-file doc whose content (the instance's own session logs) changes as work ships. Everything else is committed-at-ship, shipped-with-core, or rendered-at-package.
+
+## Wiring a standalone deploy to keep docs live
+
+The one-liner every standalone deploy script must run **after** `git reset --hard origin/main` + migrate:
+
+```bash
+node node_modules/@bongos/core/scripts/gds/regen-instance-docs.js
+```
+
+Run it with `cwd` = the instance repo root (or set `CLOUDBONGOS_INSTANCE_ROOT=<instance-dir>`). It resolves the instance root, regenerates `docs/session-log-index.md` there, is **best-effort** (always exits 0), and is **LOUD** on failure (`::ERROR::` → journald). A stale nav doc is tolerable; a failed deploy is not (ADR 0110 §2 "accepted staleness").
+
+`provision.js` already runs this on its standalone deploy path, and `bongos init` / `bongos upgrade` run it at standup / on a core bump. You only wire it by hand into a **bespoke** pull-deploy script (e.g. cloudbongos.com's `/home/lars/deploy.sh`).
+
+## `.gitignore` requirement
+
+The instance repo must gitignore the whole-file docs so `git reset --hard` never wipes the regenerated copy and no branch can diff it:
+
+```
+docs/session-log-index.md
+docs/repo-map.md
+```
+
+`provision.js`'s `INSTANCE_GITIGNORE` seeds these for new instances; an older instance (pre-ADR-0147) needs them added by hand.
+
+## Debugging "my instance's docs are empty / stale"
+
+1. **Empty `docs/` (only the 3 API files)?** The nav-doc seed never ran. Run `regen-instance-docs.js` once, and confirm the deploy script calls it (above).
+2. **`session-log-index.md` indexes the *core's* sessions, not the instance's?** You're on a core older than the ADR 0147 fix (`gen-session-index.js` hardcoded the core root). `bongos upgrade` to a fixed core.
+3. **The file keeps disappearing after deploy?** It isn't gitignored — `git reset --hard` wipes it. Add the `.gitignore` lines above.
+4. **`::ERROR:: regen-instance-docs` in journald?** A generator threw — the deploy still succeeded, but the doc is stale. Check the generator output; the instance must have `docs/session-logs/` and a resolvable instance root.

package/docs/recipes/upgrading-the-core.md

@@ -9,11 +9,12 @@
 1. **pre-flight** — module-compat vs the target core + a clean git tree (skip with `--force`).
 2. **bump the pin** — vendor the new `bongos-core-<version>.tgz` and rewrite the `"@bongos/core": "file:vendor/…"` dependency.
 3. **`npm install`** — `node_modules/@bongos/core` becomes the new version.
+3b. **verify the integrity pin** (task [#1002216](https://example.com/builders#/task/1002216)) — recompute `tree_sha256` over the installed core and check the vendored `.tgz` bytes against `tarball.sha256`, comparing to the trusted reference manifest (the committed `vendor/…manifest.json`; the installed inner manifest for `--registry`). Runs **before** migrate so a corrupted core never touches the DB. A **mismatch is fatal → rollback**; a missing reference warns (fatal with `--require-pin`); opt out with `--skip-pin-verify`.
 4. **`npm run migrate`** — the core's `migrate.sh` applies additive `core_*` migrations (merged three-root: core + instance + modules).
 5. **materialize `.claude/`** — refresh skills/settings/hooks from the new core (`materializeClaude`), rewriting invocations to the `bongos` bin.
 6. **restart** — `--service <unit>` or `--restart-cmd "<cmd>"`.
-7. **verify** — installed version == target (+ optional `--health-url`).
-8. **auto-rollback on failure** (task [#2149](https://example.com/builders#/task/2149), default ON) — if `npm install`/`migrate` fails or the step-7 health check fails, revert the pin → reinstall the previous core → restart → re-verify → write a `rolled_back:` ledger row. Opt out with `--no-rollback-on-failure`. See the section below.
+7. **verify** — installed version == target + the **mandatory post-restart health check** (task [#1002222](https://example.com/builders#/task/1002222)): a bump that restarts the service **requires `--health-url <url>`** (it can't report success without confirming the new core serves). Opt out explicitly with `--no-health-check`; a bump with no managed restart needs no URL (it reports the new core installed-but-unconfirmed). A still-failing health poll fails the bump (auto-rollback).
+8. **auto-rollback on failure** (task [#2149](https://example.com/builders#/task/2149), default ON) — if `npm install`/pin-verify/`migrate` fails or the step-7 health check fails, revert the pin → reinstall the previous core → restart → re-verify → write a `rolled_back:` ledger row. Opt out with `--no-rollback-on-failure`. See the section below.
 
 Run bare (`bongos upgrade`, no `--to`) it stays the module-compat **pre-check** only.
 
@@ -63,6 +64,8 @@ By default (`--rollback-on-failure`, ON unless `--no-rollback-on-failure`) the c
 
 **The DB is NOT rolled back — only the code pin.** Core migrations are additive + forward-safe (the core migration rule), so an already-applied migration is left in place; a *failed* migration is never recorded in `schema_migrations`, so a retry re-runs it cleanly. The reversal is recorded via the always-present `note` column (not a new `outcome` column) so it lands even in the failed-migrate path — where a newer column wouldn't yet exist on that instance.
 
+> **The forward-safe rule is now enforced, not just documented** (task [#1002223](https://example.com/builders#/task/1002223), audit H10). A core migration that DROPs/RENAMEs/retypes existing state (which would strand the rolled-back old code on the new schema) fails the [`tests/migrations_forward_safe.mjs`](../../tests/migrations_forward_safe.mjs) unit gate unless it carries an explicit `-- forward-unsafe: <reason>` acknowledgement pragma. `migrate.sh` also prints a non-fatal notice at apply time (via [`scripts/gds/lint-migrations.js`](../../scripts/gds/lint-migrations.js)). Additive migrations (the norm) need no annotation.
+
 **Proven live on demo.cloudbongos.com** (task [#2157](https://example.com/builders#/task/2157)): demo, on rollback-capable 1.17.3, was upgraded to a canary carrying a deliberately-failing migration. Migrate raised → the channel auto-reverted the pin to 1.17.3, reinstalled + restarted it, `/healthz` stayed 200 (**zero downtime** — the failure was at migrate, before the restart), and a `rolled_back` ledger row was written. This is the safety gate the unattended patch-only auto-upgrade subscription (task [#2150](https://example.com/builders#/task/2150)) depends on.
 
 ## Subscribing to updates — unattended patch-only auto-upgrade (task 2150 / ADR 0136)

package/docs/recipes/work-on-a-task-from-your-dev-box.md

@@ -0,0 +1,108 @@
+# Work on a task from your dev box
+
+> Your dev box is **task-scoped**: claim a task and the box pulls **only the code
+> that task needs** — the module(s) its work touches, on top of a small base
+> instance — never the whole repo. Your GitHub token never leaves the server; the
+> box fetches its slice through the control plane. See
+> [ADR 0148](../adr/<redacted>.md) (the scope model) and
+> [ADR 0150](../adr/<redacted>.md) (how the box
+> comes up).
+
+## TL;DR
+
+In your dev box's terminal:
+
+```bash
+/builder-start          # see what you can claim
+/builder-claim <N>      # claim task N (locks it to your session)
+/builder-sync           # pull task N's code onto the box now (re-scopes in place)
+# …work in /workspace…
+/builder-ship           # smoke + review, then land + deploy — awards credits
+```
+
+That's the whole loop. `/builder-sync` is the new step: it materializes the claimed
+task's code within seconds instead of waiting for the box's ~10-minute refresh.
+
+## The model — what's on your box
+
+A task-scoped box carries two layers:
+
+1. **The base instance** — always present, whatever you've claimed: the methodology
+   (`CLAUDE.md`, `.claude/`), the build tooling (`scripts/`, `src/bongos/`),
+   `docs/`, `infra/`, and the **test suite** (`tests/`). Enough for Claude to hold
+   context and run the `/builder-*` CLI, and to run your module's tests.
+2. **Your claimed task's code** — the module directories the task's goal scopes
+   (`goals.scope_modules` → globs, [ADR 0086](../adr/<redacted>.md)). Claim a `dev-box` task → you get
+   `modules/dev-box/`; claim a `game` task → you get the game world too. Nothing
+   else.
+
+What you do **not** get: other builders' modules, the product/game runtime (unless
+your task is game-scoped), and — the point — **no GitHub credential on the box**.
+The box asks the control plane (`GET /box/source-access`) for its slice on each
+fetch; the server holds the token and returns a scoped, cone-mode sparse-checkout
+spec. Lose the claim or a rank, and the next fetch is cut off at the server.
+
+## Step by step
+
+### 1. Connect to your box
+
+If you haven't yet, run **`/builder-connect`** (or follow the
+[dev-box lifecycle recipe](builder-box-lifecycle.md)) to raise and connect to your
+box, then **`/builder-setup`** once on the box to sign the GDS CLI in. The browser
+terminal drops you into `/workspace` — the one working folder.
+
+> **`bongos shell` / `bongos code` re-scope on connect (BV1.R101).** Connecting with
+> either verb runs the sync for you first, so you land in `/workspace` already scoped
+> to your active claim — no manual `/builder-sync` needed just to arrive. (The browser
+> terminal drops you straight into `/workspace`; run `/builder-sync` there if you
+> claimed or switched since your last sync.)
+
+### 2. See what you can claim — `/builder-start`
+
+Lists the tasks that are `ready` and parallel-safe against everyone else's active
+claims. Pick one.
+
+### 3. Claim it — `/builder-claim <N>`
+
+Locks task N to your session. **This is what drives your box's scope:** source
+access is computed from your **active claim** — its task → goal → `scope_modules`.
+
+### 4. Pull the code now — `/builder-sync`
+
+Re-runs the box's source-fetch immediately, so `/workspace` re-scopes to task N's
+modules within seconds. (A ~10-minute cron does this on its own as a backstop — you
+just don't want to wait for it.) Off a box there's nothing to sync — your source is
+your local checkout — and the command tells you so.
+
+### 5. Work — in `/workspace`
+
+`/workspace` now holds the base instance **plus** task N's module code. One folder:
+when you switch tasks it **re-scopes in place**, so there are no per-task folders to
+manage.
+
+### 6. Ship — `/builder-ship`
+
+Runs the smoke tests and the review gate, then lands + deploys and awards credits.
+
+## Switching tasks
+
+One box, one working folder, one active claim at a time (the server enforces
+one-claim-per-session). To move to a different task:
+
+1. `/builder-ship` (or `/builder-release`) the current claim.
+2. `/builder-claim <M>` the new one.
+3. `/builder-sync` — the box re-scopes to task M in place.
+
+## Notes + gotchas
+
+- **`tests/` is always in the base** — so a module's tests run on the box (they
+  live in the top-level `tests/`, not inside `modules/<key>/`).
+- **Idle boxes rest.** A box with no activity is reclaimed after ~10–15 min; the
+  next connect re-provisions a fresh one and re-fetches your scope. **Uncommitted
+  work on a reaped box is lost** — ship or commit before you step away.
+- **`/builder-sync` is idempotent** — safe to re-run; it just does, on demand, what
+  the cron does on its schedule.
+- **A fresh box comes up with the base already cloned.** If a box ever comes up
+  *bare* (no code, no terminal), that's the packaging bug
+  [ADR 0150](../adr/<redacted>.md) fixed on the
+  control plane — flag it rather than working around it.

package/migrations/003_pms.sql

@@ -223,17 +223,16 @@ CREATE INDEX IF NOT EXISTS idx_session_logs_builder ON session_logs (builder_id)
 CREATE INDEX IF NOT EXISTS idx_session_logs_ended ON session_logs (ended_at);
 
 -- =========================================================================
--- Seed: the two known versions
+-- Seed: the platform PMS-V1 version
 -- =========================================================================
--- Instance-seed guard (task 1704 / ADR 0105): these are OTB product versions —
--- scope-truth that must NOT seed onto a vanilla / non-owning DB. scripts/migrate.sh
--- sets app.seed_instance_data='off' on such a boot; unset (direct psql / OTB) = seed.
+-- Instance-seed guard (task 1704 / ADR 0105): OTB platform scope-truth that must
+-- NOT seed onto a vanilla / non-owning DB. scripts/migrate.sh sets
+-- app.seed_instance_data='off' on such a boot; unset (direct psql / OTB) = seed.
+-- (Game V1 was product/primea scope; relocated to the amazonprimea instance's
+--  migrations/instance/ per task 1002423 — the neutral core carries no game seed.)
 DO $seed$ BEGIN IF current_setting('app.seed_instance_data', true) IS DISTINCT FROM 'off' THEN
 INSERT INTO versions (id, name, track, status, scope_doc_path, started_at, done_when)
 VALUES
-  ('V1', 'Game V1 — first playable purchase loop', 'product', 'building',
-   'limitations/current-version.md', '2026-05-08'::timestamptz,
-   'A visitor can land in the world, walk to the vendor, buy a real item, and Hermeslines fulfills it.'),
   ('PMS-V1', 'PMS V1 — project management system, parallel internal track', 'internal', 'building',
    'limitations/pms-v1.md', '2026-05-09'::timestamptz,
    'Builders auth via GitHub. Slash commands claim/ship tasks atomically. Backlog migrated. Public status page live.')

package/migrations/006_pms_v2.sql

@@ -337,38 +337,10 @@ ON CONFLICT (version_id, criterion_id) DO UPDATE
 END IF; END $seed$;
 
 -- =========================================================================
--- 6. Seeds: V1 done-when criteria (mirrors limitations/current-version.md)
+-- (Game V1 done-when criteria removed — product/primea scope, not core.)
+-- Relocated to the amazonprimea instance's migrations/instance/ per task
+-- 1002423; the neutral core seeds no game scope-truth.
 -- =========================================================================
--- The V1 done-when (CLAUDE.md §9): "the experience supports the full
--- purchase loop: land in the world → walk to the vendor → buy a real
--- item → Hermeslines fulfills it." Decomposed into checkable criteria.
-
--- Instance-seed guard (task 1704 / ADR 0105): OTB V1 game scope-truth. FK-references
--- the V1 version guarded above, so this must skip on a vanilla DB too.
-DO $seed$ BEGIN IF current_setting('app.seed_instance_data', true) IS DISTINCT FROM 'off' THEN
-INSERT INTO done_when_criteria (version_id, criterion_id, criterion_md, sort_order) VALUES
-  ('V1', 'world-land',
-   'Visitor lands in the persistent world from amazonprimea.com',
-   10),
-  ('V1', 'walk-to-vendor',
-   'Visitor can walk to Hyperion at the shipping container with WASD',
-   20),
-  ('V1', 'auth-magic-link',
-   'Visitor authenticates via Stripe-tied magic link before purchase',
-   30),
-  ('V1', 'vendor-purchase',
-   'Vendor dialog supports real-product purchase via Stripe',
-   40),
-  ('V1', 'hermeslines-fulfill',
-   'Order intake reaches Hermeslines fulfillment system (whatever the format)',
-   50),
-  ('V1', 'order-confirmation',
-   'Visitor receives order confirmation in-world',
-   60)
-ON CONFLICT (version_id, criterion_id) DO UPDATE
-  SET criterion_md = EXCLUDED.criterion_md,
-      sort_order   = EXCLUDED.sort_order;
-END IF; END $seed$;
 
 -- =========================================================================
 -- 7. Migration record

package/migrations/039_newcomer_friendly_column.sql

@@ -1,6 +1,11 @@
 -- 039_newcomer_friendly_column.sql — V3.R15: tasks.newcomer_friendly column +
 -- view-level filter + Xenos claim-policy error code.
 --
+-- forward-unsafe: rename-column (RENAME tasks.xenos_claimable → newcomer_friendly). Historical
+--   (V3.R15, 2026), already applied on every instance long before `bongos upgrade`'s code-only
+--   rollback existed — no core version a current rollback could revert to reads the old column
+--   name. Acknowledged per audit H10 / task 1002223 (scripts/gds/lint-migrations.js).
+--
 -- Context: V3.R15 (#239) was planned as the row-level "newcomer-friendly task"
 -- gate for the Xenos rank. In parallel, #360 / ADR 0018 (migration 029) shipped
 -- the same idea under the name `xenos_claimable`. Now V3.R15 closes by:

package/migrations/102_remove_box_first_provision_approval.sql

@@ -1,6 +1,10 @@
 -- 102_remove_box_first_provision_approval.sql — ADR 0059 (task 1141): REMOVE the
 -- dev-box "first-box Archon approval" gate. Reverts migration 071.
 --
+-- forward-unsafe: drop-column (box_intents.approved_by / approved_at). Historical (ADR 0059, task
+--   1141); the code that read those columns was removed in the SAME change, and it predates
+--   `bongos upgrade`'s code-only rollback. Acknowledged per audit H10 / task 1002223.
+--
 -- Context
 -- -------
 -- Migration 071 (#717, ADR 0035 Decision 2) added a 'pending_approval' state to

package/migrations/core_192_github_oauth_tokens.sql

@@ -0,0 +1,33 @@
+-- core_192_github_oauth_tokens.sql — short-lived, encrypted GitHub repo tokens for
+-- the onboarding wizard (task 1002099, ADR 0143).
+--
+-- The wizard (public-landing/create.html) opts into `public_repo` at GitHub sign-in
+-- so it can LIST the signed-in user's repos (adopt) and CREATE an empty repo (fresh)
+-- — things `read:user` cannot do. That user-to-server GitHub token is held here
+-- BRIEFLY: one row per builder, the token encrypted with secret-box (master key in
+-- server env only — a DB dump alone decrypts nothing), with a short expires_at (one
+-- wizard sitting). It is read back by the repo picker/creator over the next few
+-- minutes and deleted on use; getGithubToken lazily sweeps an expired row so the
+-- table self-cleans without a cron. ON DELETE CASCADE ties a token to its builder.
+--
+-- This is the AUTH system's OWN handshake token (not a feature's third-party API
+-- key like the art module's Gemini key, ADR 0102), so it lives in core. When
+-- secret-box is unconfigured no row is ever written and the wizard falls back to
+-- manual repo entry (ADR 0143).
+--
+-- Idempotent: safe to re-run.
+
+CREATE TABLE IF NOT EXISTS github_oauth_tokens (
+  builder_id  bigint PRIMARY KEY REFERENCES builders(id) ON DELETE CASCADE,
+  token_enc   text NOT NULL,
+  scope       text,
+  created_at  timestamptz NOT NULL DEFAULT now(),
+  expires_at  timestamptz NOT NULL
+);
+
+-- The read/sweep hot path filters on expiry.
+CREATE INDEX IF NOT EXISTS idx_github_oauth_tokens_expires
+  ON github_oauth_tokens (expires_at);
+
+INSERT INTO schema_migrations (version) VALUES ('core_192_github_oauth_tokens')
+  ON CONFLICT (version) DO NOTHING;

package/migrations/core_193_task_needs_rebase.sql

@@ -0,0 +1,28 @@
+-- core_193_task_needs_rebase.sql — ADR 0120 part 2: the `needs_rebase` flag.
+--
+-- A confirmed task whose land the publish-reconciler cannot complete after the
+-- normal auto-land grace (its retries + the ADR 0082 generated-file self-heal)
+-- is flagged needs_rebase=true. It is a SIGNAL, not a status change: the task
+-- stays 'confirmed' (its work is done) — it is simply marked as awaiting *its
+-- builder's* rebase. Attribution to the builder who did the work is derived from
+-- tasks.shipped_by (confirmTask/applyGrade/decideOverrideRequest all COALESCE it
+-- to the claim holder), so no separate owner column is needed.
+--
+-- The claim gate (core claimTask, ADR 0120 part 3) refuses that builder's NEW
+-- claims while any of their tasks is needs_rebase; landing the task (shipTask)
+-- or releasing it clears the flag. This is a CORE migration (not a lifecycle
+-- module migration) because it ALTERs the core `tasks` table — the module
+-- migration namespacing rule forbids a module migration touching non-namespaced
+-- core objects (the discord precedent).
+--
+-- Safe DDL: ADD COLUMN ... NOT NULL DEFAULT <constant> does not rewrite the
+-- table on Postgres 11+ (the default is stored in the catalog).
+
+ALTER TABLE tasks ADD COLUMN IF NOT EXISTS needs_rebase boolean NOT NULL DEFAULT false;
+ALTER TABLE tasks ADD COLUMN IF NOT EXISTS needs_rebase_reason text;
+ALTER TABLE tasks ADD COLUMN IF NOT EXISTS needs_rebase_at timestamptz;
+
+-- The claim gate + hall/CLI ask "does builder B own any needs_rebase task?",
+-- keyed on shipped_by. Partial index keeps that lookup cheap (only the handful
+-- of flagged rows are indexed).
+CREATE INDEX IF NOT EXISTS idx_tasks_needs_rebase ON tasks (shipped_by) WHERE needs_rebase;

package/migrations/core_194_confirmed_backlog_clawback.sql

@@ -0,0 +1,63 @@
+-- core_194_confirmed_backlog_clawback.sql — ADR 0120 part 4: one-time clawback
+-- + re-gate of the confirmed backlog that accrued under the OLD pay-on-confirm
+-- rule (parts 1-3 moved BOTH the pay and the queue gate to the LAND).
+--
+-- For every task still at status='confirmed' (verified but NOT yet merged to
+-- main) this migration:
+--   1. Reverses its task.confirmed per-task credit — a compensating NEGATIVE
+--      credit_log row (reason='task.confirmed_reversal') per (task, builder), so
+--      the builders.total_credits trigger nets it back to 0. The reward is fully
+--      RE-EARNABLE: when the task finally lands, part 1a books a fresh
+--      'task.shipped' credit. Achievements already unlocked are LEFT INTACT
+--      (reversing gamification is punitive + messy — ADR 0120 §Consequences).
+--   2. Flags the task needs_rebase=true (reason 'clawback:confirmed_backlog') so
+--      the part-3 claim gate applies the new incentive to the work that stranded
+--      under the old rule, rather than grandfathering it.
+--
+-- Idempotent: a task already carrying a task.confirmed_reversal row is skipped,
+-- and needs_rebase is only set where still false — a re-run is a no-op. It runs
+-- ONCE per DB (schema_migrations), at the deploy that first carries it; that is
+-- WHERE the retroactive sting lands, so it hits real builders (the owner
+-- included) only when this version is actually deployed.
+--
+-- Deliberately NOT reversed: the idea-promotion bonus and the net-negative
+-- bonus. The ADR names only the 'task.confirmed' delta; the idea bonus stays
+-- with its capturer (it is not double-paid on re-land — maybeAwardIdeaPromotion
+-- Bonus guards on the existing 'idea_promotion_bonus' row), and the net-negative
+-- bonus derives from grade-time signals that never moved off confirm.
+--
+-- DML only (no schema change): safe to run inside one transaction.
+
+BEGIN;
+
+-- 1. Compensating reversal of the task.confirmed credit for still-confirmed tasks.
+INSERT INTO credit_log (builder_id, task_id, delta, reason, description)
+SELECT cl.builder_id,
+       cl.task_id,
+       -SUM(cl.delta),
+       'task.confirmed_reversal',
+       'ADR 0120 clawback: reverse premature task.confirmed credit for still-confirmed (unlanded) task ' || cl.task_id
+  FROM credit_log cl
+  JOIN tasks t ON t.id = cl.task_id
+ WHERE t.status = 'confirmed'
+   AND cl.reason = 'task.confirmed'
+   AND NOT EXISTS (
+     SELECT 1 FROM credit_log r
+      WHERE r.task_id = cl.task_id
+        AND r.builder_id = cl.builder_id
+        AND r.reason = 'task.confirmed_reversal'
+   )
+ GROUP BY cl.builder_id, cl.task_id
+HAVING SUM(cl.delta) <> 0;
+
+-- 2. Re-gate: flag every still-confirmed task needs_rebase for its builder
+--    (attribution via tasks.shipped_by), so the claim gate (part 3) bites.
+UPDATE tasks
+   SET needs_rebase = true,
+       needs_rebase_reason = 'clawback:confirmed_backlog',
+       needs_rebase_at = COALESCE(needs_rebase_at, now()),
+       updated_at = now()
+ WHERE status = 'confirmed'
+   AND needs_rebase = false;
+
+COMMIT;