@bongos/core 1.18.3 → 1.18.19

package/docs/onboarding/slash-commands.md

@@ -0,0 +1,124 @@
+# Slash commands: which are Claude's, which are this project's
+
+*A reference page. Skim it once, come back when a command surprises you.*
+
+When you type `/` in Claude Code you get one list, but the commands in it come from **two different places** and are maintained by two different people. Claude Code ships some of them; this project ships the rest. They look identical in the menu, which is why a few of them trip people up — see [Easy mix-ups](#easy-mix-ups) at the bottom.
+
+## The 10-second rule
+
+| | **Claude Code's own** | **This project's** |
+|---|---|---|
+| Who ships it | Anthropic, inside the Claude Code app | This repository |
+| Where it lives | Inside the app — nothing in this repo | [`.claude/skills/<name>/`](../../.claude/skills/) |
+| What it acts on | Your *session* — context, model, config, account | The *build system* — tasks, claims, ships, ideas |
+| Works in any repo? | Yes, everywhere | No — only in a folder that holds this code |
+| Authoritative list | Type `/help` | The folder listing linked above |
+
+**The short version:** if it changes your Claude session, it's Claude's. If it changes project state — a task, a claim, a ship — it's ours. If you can run it in an unrelated repo, it's Claude's.
+
+> This is also why the commands "appear by magic" when you clone: they aren't a plugin or a download, they're files in `.claude/skills/` that Claude Code reads when a session **starts** on the folder. Clone mid-session and they won't show up until you start a fresh session — the wrinkle the [primer](primer.md) calls out in step 3.
+
+## This project's commands
+
+Every one of these talks to the build system. They're grouped by when you'd reach for them, not alphabetically.
+
+### The work loop — the ones you'll use every session
+
+| Command | What it does |
+|---|---|
+| `/builder-start` | List the tasks you can claim right now, filtered for parallel-safety |
+| `/builder-claim N` | Lock task N to your session |
+| `/builder-ship` | Grade, merge, and deploy your claimed task (credits land here) |
+| `/builder-release` | Cancel a claim — the task returns to `ready`, no credits |
+| `/builder-stage` | Preview your work-in-progress on your own sandbox before shipping |
+| `/builder-end` | Close out the session safely — resolve the claim, seal the log |
+| `/status` | Version / criterion progress — "what's left for C8?" |
+| `/recall` | Search the docs + project knowledge before re-solving something |
+
+### Your account and your machine
+
+| Command | What it does |
+|---|---|
+| `/builder-setup` | One-time enrolment — signs you in and registers you |
+| `/builder-reauth` | Refresh an expired session |
+| `/builder-key` | Check / set your own API key status |
+| `/builder-box` | Your dev box control panel — wake, create, check cost |
+| `/builder-connect` · `/builder-sync` · `/close-box` | Connect to, re-sync, and tear down that box |
+| `/builder-cost` | Log a cost entry against your claim |
+| `/builder-backup` | Check or trigger a database backup before risky work |
+| `/builder-exit` | Offboard or reactivate a builder *(Archon only)* |
+
+### Triage and planning *(Metic and above)*
+
+| Command | What it does |
+|---|---|
+| `/idea-triage` | Walk the idea inbox — promote, discard, or merge each |
+| `/blocker-review` · `/blocker-solve` | Walk open blockers, or drive one to done |
+| `/goal-create` | Plan and create one goal — scope wall, criteria, seed tasks |
+| `/goal-review` | Confirm criteria that are flagged met-pending-review |
+| `/planning-session` | Scope an upcoming version and seed its task list |
+| `/priority-session` | Reweight the inbox from a few plain-speech answers |
+| `/merge-mode` | Manual fallback when a confirmed task didn't land |
+
+### Discipline modes
+
+`/dev` (engineering — the default loop), `/paint` (art), `/ideate` (ideation). A claimed task's discipline routes you to one of these.
+
+### Design and art pipeline
+
+`/design-sync` and `/figma-design-sync` round-trip the UI design system. The `/otb-*` family — `otb-tile-generate`, `otb-design-review`, `otb-character-review`, `otb-feedback-capture`, `otb-figma-sync` — is the reference instance's pixel-art pipeline; it's only meaningful on an instance that runs that pipeline.
+
+### Session and meta
+
+| Command | What it does |
+|---|---|
+| `/session-handoff` | Emit a paste-ready prompt to start a fresh session with |
+| `/read-session-export` | Read a past session's `/export` zip |
+| `/feedback` | Pull in the latest recorded walkthrough bundle |
+| `/new-project` | Zero-to-live runbook for a brand-new instance |
+| `/builder-redteam` | File a security / vulnerability report |
+
+## Claude Code's own commands
+
+These work in **any** repository — they have nothing to do with this project. `/help` prints the live, authoritative list for your version; the ones below are simply the ones you'll actually meet.
+
+| Command | What it does |
+|---|---|
+| `/help` | List every command available right now — **the authoritative list** |
+| `/clear` · `/compact` | Wipe or condense the conversation context |
+| `/model` · `/config` | Switch model; change app settings |
+| `/login` · `/logout` | Sign in to your **Anthropic** account |
+| `/init` | Write a `CLAUDE.md` for the current codebase |
+| `/cost` · `/usage` · `/context` | Token spend, plan usage, context window |
+| `/doctor` | Diagnose the **Claude Code install** |
+| `/memory` | Edit Claude's memory files |
+| `/mcp` · `/agents` · `/hooks` · `/permissions` | Configure MCP servers, subagents, hooks, tool permissions |
+| `/export` · `/resume` · `/rewind` | Save the transcript; resume or roll back a session |
+| `/review` | Review a GitHub pull request |
+| `/status` | **Claude Code's** session/auth status — see the warning below |
+
+## Easy mix-ups
+
+These are the ones that actually cause confusion.
+
+**`/status` — the genuine collision.** Both sides define it. Claude Code's `/status` shows your session and auth state; this project's shows version and criterion progress. Which one wins depends on your Claude Code version and how it resolves the name. If you get the wrong one, say *"what's left for C8"* in plain English, or run `node scripts/gds/status.js` directly.
+
+**`/login` is Anthropic, not us.** It signs you into your Claude account. To sign into a Cloud Bongos instance, use `bongos login <instance-url>`, or `/builder-setup` for a first-time enrolment.
+
+**`/init` writes a `CLAUDE.md`.** It does *not* scaffold a new instance — that's `bongos init`, wrapped by `/new-project`. Running `/init` in this repo would overwrite the project's own `CLAUDE.md`.
+
+**`/doctor` checks Claude Code.** For the build system's health — your session, toolchain, git plumbing, environment — run `node scripts/gds/doctor.js`.
+
+**`/cost` is Claude's token spend.** To record a project cost against your claim, that's `/builder-cost`.
+
+**`/export` vs `/read-session-export`.** Claude's `/export` *writes* a transcript zip; our `/read-session-export` *reads* one back.
+
+**`/review` reviews a GitHub PR.** The project's review commands are `/goal-review`, `/blocker-review`, and `/idea-triage` — different jobs entirely.
+
+## Two more things worth knowing
+
+**Every command has a plain-English twin.** Each skill lists trigger phrases, so *"what can I work on"* reaches `/builder-start` and *"ship it"* reaches `/builder-ship`. You never have to memorise the slash form.
+
+**Same commands, outside Claude.** The work-loop commands are also a terminal CLI: `bongos start`, `bongos claim N`, `bongos ship`. Same actions, same API — usable from any terminal, a Chromebook, or CI. Run `bongos help` for the verb list.
+
+**Rank gates are real.** Some commands above refuse below a certain rank — that's enforced by the server on every request, not by the presence of the file on your disk. See [`canonical-permissions.md`](../canonical-permissions.md).

package/docs/recipes/builder-box-lifecycle.md

@@ -138,6 +138,29 @@ These spend money and are intentionally manual.
    > **`box-drift-reconcile.timer` (task [#1289](https://example.com/builders#/task/1289)/[ADR 0071](../adr/<redacted>.md)) is the zombie backstop.** It runs `box.js reconcile-drift --apply` hourly, reading the live DO droplet list and repairing DO⇄DB drift both ways — force-deleting **zombie** droplets (running but no live box row claims them) and marking **ghost** rows destroyed (droplet gone from DO). Reads the SAME `/etc/example/box.env` (needs `DO_API_TOKEN` to enumerate droplets). Without it, the confirm-before-destroyed teardown still prevents *new* zombies, but a pre-existing one (or an out-of-band DO change) only heals on the next manual `reconcile-drift`. Confirm with `journalctl -u box-drift-reconcile.service`.
    > **Chromebook / browser terminal ([#760](https://example.com/builders#/task/760)/[ADR 0038](../adr/<redacted>.md), superseding the old `claude rc` pairing).** Research proved `claude rc` cannot run headless, so the box instead serves its OWN browser terminal — **ttyd** (127.0.0.1:7681, per-box basic-auth, drops into `/workspace`) exposed over an outbound-only **Cloudflare Tunnel** — where the builder runs normal interactive `claude`. A browser/Chromebook builder gets the URL + credential from `GET /api/gds/box/terminal` after their box is active — no SSH needed. The terminal/cloudflared units are inlined in cloud-init and start at first boot ([#774](https://example.com/builders#/task/774)). The deleted RC bits (`claude-rc.service`, `box-report-pairing.sh`, `/box/pairing(-link)`) are gone.
 
+## Cloudflare token: the edge cookie-strip rule (ADR 0053 / SR#11)
+
+`provision` applies two zone **rulesets** best-effort: the **cookie-strip Transform Rule** (removes the `Cookie` request header on `term-*`/`sandbox-*`, so the apex session cookie never rides the tunnel onto a box — a host outside the trust boundary) and the **sandbox cache-bypass Cache Rule**. Both need scopes beyond Tunnel + DNS, and a token that lacks them fails **silently** — the box provisions fine and the security control simply isn't there.
+
+Since task 1002511, `box.js provision` **read-probes** the ruleset phase before spending a cent (dry-run included) and prints a `⚠⚠ SECURITY` block naming the fix. Read the probe honestly: it is a `GET`, so it can only prove the scope is **missing** (401/403). A readable phase means *readable* — edit scope is not proven until the rule PUT actually runs, which is why the summary line after `✓ named tunnel ready` is the authoritative signal.
+
+**Fix — widen the token** (account owner only):
+
+> CF dashboard → **My Profile → API Tokens** → edit the token used as `CLOUDFLARE_API_TOKEN` → **Permissions** → add **Zone → Transform Rules → Edit** and **Zone → Cache Rules → Edit** → **Zone Resources → Include → Specific zone → `<your apex zone>`** → Continue → Save. Then re-run `node scripts/gds/box.js provision <login> --apply`.
+
+**Fallback — apply the rule by hand** (no token change; do it once per zone):
+
+> CF dashboard → the zone → **Rules → Transform Rules → Modify Request Header** → Create rule. Custom filter expression: `starts_with(http.host, "term-") or starts_with(http.host, "sandbox-")` (the exported `COOKIE_STRIP_EXPRESSION`). Action: **Remove** header `Cookie` (phase `http_request_late_transform`). Deploy. Give it the same description the code uses (`COOKIE_STRIP_RULE_DESC`) so a later widened-token run recognises and replaces it instead of adding a duplicate.
+
+**Verify:**
+
+```bash
+node scripts/gds/box.js provision <login>          # dry-run — prints the probe verdict, spends nothing
+curl -sI https://term-<login>.<apex>/ -H 'Cookie: x=1'   # from a box-facing check, confirm the origin sees no Cookie
+```
+
+> `/user/tokens/verify` is **not** a valid check here — an IP-locked token answers "Invalid API Token" there even when it is valid (see the [#725](https://example.com/builders#/task/725) note above). Always probe the real operation.
+
 ## Boundaries (other ADR-0031 tasks)
 
 - **[#596](https://example.com/builders#/task/596)** (done) — the devcontainer (box-as-code) this provisions.

package/docs/recipes/devbox-app-release.md

@@ -10,7 +10,10 @@ releases repo → a one-line config bump re-points the branded
 - **Source:** `devbox-app/` in the main (private) repo.
 - **CI:** `.github/workflows/build-devbox-app.yml` — builds on every push
   touching `devbox-app/**` (mac dmg arm64+x64 on macos-14, NSIS exe x64+arm64 on
-  windows-latest) and uploads workflow artifacts. No publishing from CI.
+  windows-latest). **Only `main` keeps the artifacts** (3-day retention); a
+  `claude/**` run builds both platforms as a CI signal and uploads nothing —
+  ~500MB per run had filled the shared Actions storage cap and blocked uploads
+  repo-wide. No publishing from CI either way.
 - **Public releases repo:** named in `config/devbox-app.json`
   (`releases_repo`). Assets live on GitHub releases there; GitHub's CDN
   serves the downloads, $0.
@@ -43,13 +46,20 @@ releases repo → a one-line config bump re-points the branded
 
 1. Bump `devbox-app/package.json` version (e.g. `1.1.0`) and regenerate
    icons only if they changed (`npm run icons`).
-2. Push the branch; wait for `build-devbox-app` to go green.
-3. Download the artifacts:
+2. Land the bump on `main` through the normal GDS flow, then wait for
+   `build-devbox-app` to go green **on the `main` run** — that is the run that
+   carries the installers.
+3. Download the artifacts (they expire after 3 days — re-run the workflow on
+   `main` via `gh workflow run build-devbox-app.yml --ref main` if they aged out):
    ```
    gh run download -R example-owner/example -n devbox-app-mac -D /tmp/devbox-rel
    gh run download -R example-owner/example -n devbox-app-win -D /tmp/devbox-rel
    ```
-   (or build the mac side locally: `cd devbox-app && npm run dist:mac`).
+   **These commands only work against a `main` run.** Pointing them at a
+   `claude/**` run fails with nothing to download — the upload steps are gated to
+   `refs/heads/main` (see §0). To get an installer out of an unmerged branch,
+   build it locally instead: `cd modules/dev-box/app && npm run dist:mac` (or
+   `npm run dist:win` on Windows).
 4. Publish to the public releases repo (tag = `v<version>`, must match what
    `src/devbox-downloads.js` composes):
    ```

package/docs/recipes/instance-first-run.md

@@ -35,6 +35,22 @@ npx bongos start
 
 That's it — `bongos claim <id>` / `bongos ship` now work, scoped to this instance.
 
+## If the instance isn't hosted yet — a freshly-created, LOCALHOST project
+
+The steps above assume the instance is already **running** at a reachable origin. A project
+straight out of the creation flow is different: its `config/branding.json` `publicOrigin`
+is `http://localhost:<port>`, and **nothing is serving it yet** — so step 2's
+`bongos login http://localhost:<port>` fails with `fetch failed`. That repo is configured
+to run on *your own machine*; stand it up with one command instead:
+
+```bash
+npm install
+npx bongos dev        # Postgres → createdb → migrate → server → sign-in, in one step
+```
+
+Full guide: [`docs/recipes/local-dev.md`](local-dev.md) (ADR 0149). Prefer a cloud dev box
+over running locally? Use `bongos box` + `bongos code`.
+
 ## Notes
 
 - **Sign in to the RIGHT instance.** `bongos login <url>` writes a per-instance session

package/docs/recipes/local-dev.md

@@ -0,0 +1,81 @@
+# Run a project on your own machine — `bongos dev`
+
+> The one-command path from a freshly-cloned **standalone instance repo** (one whose
+> `config/branding.json` points at `http://localhost:<port>`) to a running, signed-in
+> instance on your Mac. This is the local counterpart of `bongos onboard` (which
+> stands an instance up in the **cloud**) — see [ADR 0149](../adr/<redacted>.md).
+
+## TL;DR
+
+```bash
+gh repo clone <owner>/<project>
+cd <project>
+npm install
+npx bongos dev
+```
+
+`bongos dev` starts the database, creates this project's database, builds its tables,
+launches the server on the port in `config/branding.json`, and signs you in. Re-running
+it is safe (idempotent). Stop it with `bongos dev stop`.
+
+## Prerequisites (one-time, per machine)
+
+- **Node.js ≥ 22** — `node --version`
+- **PostgreSQL 16** — `psql --version`. Install on a Mac with Homebrew:
+  ```bash
+  brew install postgresql@16
+  brew services start postgresql@16   # bongos dev will also try to start it for you
+  ```
+- macOS or Linux (migrations use `bash`). On **Windows**, use WSL, or the Docker path in
+  [`self-host.md`](self-host.md).
+
+## What `bongos dev` does (and why it's needed)
+
+A cloned project ships the code but nothing *running*. The server reads its port from an
+env var and **not** from branding, the migrator and the server default to **different**
+database names, and node-pg defaults to a Linux socket that doesn't exist on a Mac — so a
+by-hand standup is a six-step assembly with three silent mismatches. `bongos dev` does all
+of it from one source of truth (your `config/branding.json`):
+
+1. Ensures Postgres is running (starts it if it isn't).
+2. Creates the project's database if it doesn't exist.
+3. Runs migrations to build/refresh the tables.
+4. Starts the server on the branding port (e.g. `http://localhost:3006`).
+5. Signs you in to this instance (`--no-login` to skip).
+
+## Commands
+
+```bash
+npx bongos dev                 # stand it up (idempotent) + sign in
+npx bongos dev status          # is it running? what URL? is sign-in configured?
+npx bongos dev stop            # stop the background server this launched
+npx bongos dev --foreground    # run attached instead (Ctrl-C stops it)
+npx bongos dev --no-login      # stand it up but don't sign in
+npx bongos dev --skip-migrate  # skip the migration step (already migrated)
+npx bongos dev --port 3011 --db my_scratch   # override the port / database name
+```
+
+The server runs in the **background but managed** — `bongos dev status`/`stop` always find
+it, and a second `bongos dev` is a no-op if it's already up. (This is deliberate: an
+*unmanaged* leftover server is how you end up accidentally signing a new project into an
+old one's server.)
+
+## The one step that can need you: a GitHub OAuth App
+
+Sign-in uses a GitHub OAuth App. If your machine already ran another Cloud Bongos instance,
+the credentials are usually already present and `bongos dev` just works. If not, it prints
+exact steps: create an OAuth App (Homepage `http://localhost:<port>`, callback
+`http://localhost:<port>/api/gds/auth/web/callback`, tick **Enable Device Flow**), then save
+the Client ID + secret to `~/.config/<configDir>/gds-github.json` as
+`{ "client_id": "…", "client_secret": "…" }` and re-run `bongos dev`.
+
+## Notes
+
+- **Sign in as the owner.** `config/branding.json`'s `firstAdmin` is the GitHub account
+  auto-seated as owner on first sign-in — `bongos dev` tells you which one.
+- **Switching instances.** Signing in to a local project points your CLI session at it; to
+  go back to a hosted instance later, `bongos login https://<that-instance>`.
+- **Multiple projects at once** each get their own database + port, so their `bongos dev`
+  servers don't collide.
+- **Prefer the cloud?** `bongos box` + `bongos code` give you a remote dev box instead — no
+  local database or server to run.

package/docs/recipes/ops-gotchas.md

@@ -147,11 +147,29 @@ Organized by topic, not chronology. New entries go in the matching section; crea
 
 ---
 
+## Windows / local dev (PowerShell)
+
+### PowerShell 5.1 turns a clean `node scripts/gds/*.js` exit into a false failure
+
+- **Symptom:** Running `node scripts/gds/api.js GET /api/gds/me 2>&1` (or the same on `claim.js`/`ship.js`) inside a PowerShell 5.1 session reports failure — `$?` is `$false` and the stderr line surfaces as a `NativeCommandError` — even though node exited 0 and the JSON on stdout is exactly right.
+- **Root cause:** `api.js` prints its status banner to stderr unconditionally, by design (stdout stays clean JSON for piping); `claim.js`/`ship.js` also write diagnostics to stderr during a normal run. PS 5.1 wraps any stderr output from a native command into an `ErrorRecord` once the two streams are merged with `2>&1`, and sets `$?` false regardless of the actual exit code.
+- **Fix:** Never merge streams on these calls. Prefer `scripts/gds/api.ps1` (a thin wrapper that discards stderr and writes clean JSON to stdout, safe to pipe into `ConvertFrom-Json`), or call `node scripts/gds/api.js ...` plain, with no `2>&1`.
+- **Why it bites:** The exit code and JSON body are both fine — only the redirection is wrong — so the failure looks like a real API error and wastes time chasing a phantom bug in the call itself.
+
+### `Out-File`/`>` writes a UTF-8 BOM that breaks `JSON.parse` on re-read
+
+- **Symptom:** A JSON body file written from PowerShell (`... | Out-File body.json` or `... > body.json`) and then read back with `--body-file` fails to parse, or parses with an invisible extra character before the first key.
+- **Root cause:** PowerShell's `Out-File`/`>` redirection default to UTF-8 **with a byte-order-mark**. `JSON.parse` does not strip a leading BOM, so the file's first byte is invisible garbage as far as the parser is concerned.
+- **Fix:** Don't write CLI JSON body files with `Out-File`/`>`. Use the Write tool, or `[IO.File]::WriteAllText($path, $json, (New-Object Text.UTF8Encoding($false)))` (explicit no-BOM encoding). `scripts/gds/api.js`'s `--body-file` reader now also strips a leading BOM defensively, but the safest fix is to never write one.
+- **Why it bites:** The file looks completely normal in an editor — the BOM is invisible — so the parse failure looks like a JSON syntax problem, not an encoding one.
+
+---
+
 ## GDS build pipeline
 
 ### Two deterministic routines run as in-process server timers, not external cron
 
-- **What:** `peer-vote-tally` (weekly) runs inside the always-on Node process via the autonomy module's poller `modules/autonomy/pollers/routine-timers.js` (ADR 0078 amendment, task 1382; carved into `modules/autonomy/` at BV1.R83) — no `claude -p`, no external cron, no token. The loader's `startModulePollers` starts it (on the game/droplet boot only); it reaches `tallyPeerVotes` through the doorway. It's a no-op anywhere the DB is unreachable (builder machines), so it only does work on the prod droplet.
+- **What:** `peer-vote-tally` (weekly) runs inside the always-on Node process via the autonomy module's poller `modules/autonomy/pollers/routine-timers.js` (ADR 0078 amendment, task 1382; carved into `modules/autonomy/` at BV1.R83) — no `claude -p`, no external cron, no token. The loader's `startModulePollers` starts it from `src/platform-server.js` at boot (task 1002419 — before that fix the call site had been lost with the retired `server.js` and no module poller started at all); it reaches `tallyPeerVotes` through the doorway. It's a no-op anywhere the DB is unreachable (builder machines), so it only does work on the prod droplet.
 - **Disable / move it out-of-process:** set `ROUTINE_TIMERS_DISABLED=1` in `/etc/example/web-source.env` and restart. Also set it on any **second** always-on instance that shares the `example` DB so the tally can't double-fold (the `FOR UPDATE OF pv` row lock is the hard guard if you forget).
 - **Run it manually now:** `node scripts/gds/run-routine.js peer-vote-tally` (the dispatcher front door still works). The cadence is boot-anchored ("~90s after boot, then weekly"), not a wall-clock Monday job — frequent deploys re-anchor it, which is harmless (the tally is idempotent).
 

package/docs/recipes/overnight-builder.md

@@ -33,7 +33,7 @@ curl -sS -X PATCH -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: applicat
   -d '{"parallel_safe": true}' https://example.com/api/gds/tasks/<id>
 ```
 
-In parallel mode each worker stops at `confirmed` (credits land) and the runner lands the merges **one at a time** — concurrent merges to `main` are never allowed.
+In parallel mode each worker stops at `confirmed` (verified, not yet paid — [ADR 0120](../adr/<redacted>.md) books credits at land) and the runner lands the merges **one at a time** — concurrent merges to `main` are never allowed. Credits land as each merge completes.
 
 ## Reading the morning report
 

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.