@bongos/core 1.18.0 → 1.18.18

package/.claude/skills/builder-box/SKILL.md

@@ -39,6 +39,12 @@ The per-builder box lifecycle (ADR 0031 §2) auto-suspends when idle (snapshot-a
 - **Own resource only.** `/box/me` and `/box/ssh-key` are scoped to the caller. The full roster (`GET /api/gds/boxes`) is Archon-only — don't try it for a regular builder.
 - **Don't print the SSH private key** — these endpoints only ever return public fingerprints, never private material. Keep it that way.
 
+## Quirks on the box (verified from ssh sessions)
+
+- **`sharp` resolves only from `/workspace`.** Run image-pipeline tooling (art gen, thumbnailing) from `/workspace` — invoking it from another cwd on the box fails to resolve the native binding.
+- **Playwright MCP writes screenshots to `.playwright-mcp/` relative to the server's cwd**, not the caller's — look there first when a screenshot path seems to have gone missing.
+- **The Bash tool's cwd persists between calls on the box.** A bare `cd x` silently shifts every later command in the session; prefer absolute paths over `cd`-then-relative sequences.
+
 ## Files this skill touches
 
 - Calls: `/api/gds/box/me`, `/api/gds/box/ssh-key` (read), `/api/gds/box/terminal` (read), optionally `POST /api/gds/box/ensure` (queue auto-provision/wake) or `DELETE /api/gds/box/ssh-key/:id`

package/.claude/skills/builder-sequence/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: builder-sequence
+description: Walk a whole dependency chain from one kickoff — claim, build, ship, then pick up whatever that unblocked, and repeat until the chain is done or something needs a human. Triggers when the user says "/builder-sequence N", "work the chain from task N", "do these tasks in order", "run goal N end to end", "keep going until the chain is done", or "work through the rest of this chain". One task is claimed at a time; a task is always fully shipped before the next is claimed.
+---
+
+You are running a **chain**: several dependency-linked tasks, one after another, from a single kickoff. Two-thirds of the open backlog sits behind a predecessor, and shipping a task auto-promotes its dependents `backlog`→`ready` — but nothing picks the newly-unblocked task up. That gap is what this skill closes.
+
+This skill owns the **loop and the halt discipline**. It does not re-derive how to claim, build, or ship — `/builder-claim`, `/dev`, and `/builder-ship` own those, and you defer to them each pass.
+
+## The one rule
+
+**One task at a time, fully shipped before the next is claimed.** The server enforces this anyway (one active claim per working tree, `shouldRefuseSessionClaim`), and it is what makes the chain safe: each task lands on a clean tree, and each ship is what unblocks the next task. Never batch-claim a chain — successors fail `DEPS_NOT_SHIPPED` by construction, because their predecessor has not shipped yet.
+
+## The loop
+
+1. **Plan the chain, and show it before starting.**
+
+   ```bash
+   node scripts/gds/sequence.js --from <task-id>
+   ```
+
+   Or `--goal <goal-id>` to scope to a goal's open tasks. This prints the chain in dependency order with total credits and total estimated time. Relay it, and confirm the scope looks right before doing any work — a 24-task chain is not a single sitting, and the user should see the size before you start.
+
+2. **Ask for the next task.**
+
+   ```bash
+   node scripts/gds/sequence.js --from <head-id> --next
+   ```
+
+   Exit 0 with a task means go. **Exit 1 means halt** — see below. Re-run this each pass rather than working from the step-1 plan: the plan is a snapshot, and shipping changes what is claimable.
+
+3. **Claim it** — `/builder-claim <id>`, or `node scripts/gds/claim.js <id>`.
+
+4. **Build it** — follow `/dev`. Stay strictly inside the task's `touches[]`. Everything the normal task loop requires still applies: read the acceptance criteria, work test-first, commit before shipping.
+
+5. **Ship it** — `/builder-ship`. The task must reach `shipped`, not stall at `completed` or `confirmed`. A ship that does not land has not unblocked anything, so the chain cannot advance; treat it as a halt (see `ship_failed` below).
+
+6. **Go back to step 2.** The ship you just landed is what promotes the next task to `ready`.
+
+Between passes, report progress in one line — which task landed, what is next, how much of the chain remains. The user is following a long run; they should never have to ask where it is.
+
+## Halting — the contract
+
+**The runner stops and reports. It never ships a half-finished task, and it never skips ahead to work around a blocked one.** A skipped predecessor strands everything behind it, so skipping is not the safer option it looks like.
+
+`sequence.js --next` exits 1 and names the reason when the next task:
+
+| Reason | Means |
+|---|---|
+| `needs_migration` | wants a schema change — needs a reserved migration number and human eyes |
+| `security_sensitive` | flagged security-sensitive |
+| `protected_path` | `touches[]` hits the permission/deploy core |
+| `rank_floor` | requires a rank above the running builder's |
+| `thin_spec` | no description, or too thin to verify "done" against |
+| `judgement_kind` | a `decision` or `spike` — the output is a recommendation or an ADR, not mechanical work |
+| `not_claimable` | `ready`, but the server will not hand it over (open blocker, or `touches[]` collide with a live claim) |
+| `deps_unmet` | still waiting on a predecessor |
+| `in_flight` | already mid-ship |
+| `cycle` | sits in a dependency cycle and cannot be ordered |
+
+Two more halts are yours to detect, not the script's:
+
+- **`ship_failed`** — the ship bounced, the grade failed, or the task did not reach `shipped`.
+- **`scope_surprise`** — the task turns out to need work outside its `touches[]`, or its premise is wrong (the thing it describes is already done, or no longer true). Do not quietly widen the scope; that is a new task.
+
+**On any halt:** leave the current task claimed, stop, and report — what you hit, which task, and what it needs from a human. Then say plainly what already landed. Everything shipped stays shipped; a halt costs the rest of the run, not the work done.
+
+To inspect one task without running anything:
+
+```bash
+node scripts/gds/sequence.js --check <task-id>
+```
+
+## What NOT to do
+
+- **Do not skip a halted task and continue down the chain.** The owner chose stop-and-report precisely so a blocked predecessor does not silently strand its dependents.
+- **Do not batch-claim.** See "The one rule".
+- **Do not widen a task's `touches[]`** to make the chain flow. File a new task instead (`node scripts/gds/capture.js`).
+- **Do not keep going past the user's stated scope.** `--from` and `--goal` bound the run; when the chain is exhausted, stop and report rather than reaching into the wider backlog.
+- **Do not treat a long chain as a mandate to run unattended forever.** If the remaining estimate is large, say so and let the user decide whether to continue.
+
+## Flags
+
+| Flag | Effect |
+|---|---|
+| `--from <id>` | scope to a task and everything transitively behind it |
+| `--goal <id>` | scope to a goal's open tasks |
+| `--next` | emit only the next claimable task, or exit 1 with a halt reason |
+| `--check <id>` | evaluate the halt matrix for one task; exit 1 if anything fires |
+| `--limit N` | cap the planned chain (default 50) |
+| `--json` | machine-readable output for all of the above |
+
+## Files this skill touches
+
+- Runs: `scripts/gds/sequence.js` (planning + next + check), then `scripts/gds/claim.js` and `scripts/gds/ship.js` per pass.
+- Reads: `GET /api/gds/tasks/:id` (for `dependencies[]`/`dependents[]`), `GET /api/gds/tasks/claimable`, `GET /api/gds/me`.
+- Writes nothing itself — every state change goes through the claim and ship paths that already own it.

package/.claude/skills/builder-ship/SKILL.md

@@ -12,8 +12,10 @@ Runs `node scripts/gds/ship.js <task-id> --notes "..." --summary "..."`.
 The CLI drives a **three-state lifecycle** with a subagent grader between states (Phase 5, 2026-05-10):
 
 1. **`completed`** — the builder declared the work done. Always reached. Sets the task's `value_summary` (used on `status.example.com`) and the handoff notes.
-2. **`confirmed`** — smoke green + the subagent grader passed. **Credits land here**: a `credit_log` row for `credits_reward` is inserted (a trigger updates `builders.total_credits`). If the grade fails, the task stays at `completed` for human follow-up.
-3. **`shipped`** — the branch is merged into `main` + deployed (visible in production). The claim is released and the task is stamped `shipped_at` + `shipped_by`. If this step fails (conflicts, smoke red), the task stays at `confirmed` for `/merge-mode` to land later.
+2. **`confirmed`** — smoke green + the subagent grader passed. **Verified, but not yet paid** — no credits land here ([ADR 0120](../../../docs/adr/<redacted>.md) pays on land, not on confirm). If the grade fails, the task stays at `completed` for human follow-up.
+3. **`shipped`** — the branch is merged into `main` + deployed (visible in production). The claim is released and the task is stamped `shipped_at` + `shipped_by`. **Credits land here**, as `credit_log.reason = 'task.shipped'` (a trigger updates `builders.total_credits`). If this step fails (conflicts, smoke red), the task stays at `confirmed` for `/merge-mode` to land later.
+
+   > **What actually pays depends on the instance's reward mode** ([ADR 0146](../../../docs/adr/<redacted><redacted>.md)). The default `cost-plus-and-estimate` books both the per-task estimate and the cost-plus session reward. **Cloud Bongos runs `cost-plus-only`**, so the per-task `credits_reward` estimate is *never* paid here — it is an advertised guide only, and the cost-plus session reward (`round(true_cost_usd × 1.20)`) is the sole equity stream. A `Credits +0` on the ship card is expected on this instance, not a bug.
 
 `/builder-ship` runs steps 1 + 2 inline; on auto-confirm it chains into step 3 (push, merge on main, smoke, deploy).
 
@@ -37,6 +39,8 @@ The CLI drives a **three-state lifecycle** with a subagent grader between states
    - Decisions made (linked to ADRs)
    If the user is in a hurry, ask them for one bullet per heading and fill gaps from session context.
 
+   **Confirm every new behavior is asserted by a checked-in `tests/*.mjs` case** — the grader treats throwaway verification scripts and Playwright probes as unverified and bounces the ship back to `completed`.
+
 3. **Compose the value summary (`--summary`)** — ONE LINE, written for non-engineers. This is what shows up on `status.example.com` for the team and the public. Examples:
    - "Players can now resume at their last position after a browser refresh."
    - "Cost dashboard backfilled with 377 art-pipeline API calls."
@@ -53,6 +57,8 @@ The CLI drives a **three-state lifecycle** with a subagent grader between states
      --summary "the one-liner"
    ```
 
+   **Never merge a task branch to main before running `ship.js`.** `ship.js` diffs the claim branch against `main`; an already-merged branch yields an empty diff, and the only exits are `--allow-empty` (dead-ends the task at `completed`, requiring an Archon-only confirm) or reverting the merge. Ship from the branch, then let `ship.js` land it. (This trap was hit on tasks 1002417 and 1002419, producing blockers 1000081/1000082 and an ~8.5-hour stall.)
+
 5. **Render the completion card — it IS the summary; do NOT write a prose recap (task 1270).**
    _As of task 1288 the lifecycle-card `PostToolUse` hook (`.claude/hooks/lifecycle-card.js`) reads this card and injects a one-step render directive right after `ship.js` runs — normally just follow that and render **once**; the detail below is the fallback if no directive appears._
    On every ship, `ship.js` prints ONE deterministic completion card — the same shape every time, only the data changes. It always prints a monospace card to stdout, and for a shipped / confirmed / grade-failed outcome it ALSO writes a branded HTML card to a temp file and prints two marker lines:

package/.claude/skills/builder-start/SKILL.md

@@ -27,6 +27,17 @@ Delivery is now deterministic (task 1288). The **card-delivery hook** (`.claude/
 - If `start.js` prints **"no GDS session"**, the builder isn't signed in — route them by scenario: a **first-timer** on the project runs `/builder-setup` (one-time GitHub sign-in that also registers them); a **returning builder whose session went stale** runs `/builder-reauth` (the fast UI re-issue). `start.js` now prints both options; relay the one that fits, then retry.
 - (`--full` adds the detailed status widgets + worktree/context block; `--json` is the machine interface; `--hook` is the envelope the hook consumes — don't run these for the user unless asked.)
 
+## When the environment isn't ready (fresh clone)
+
+`/builder-start` is frequently the **first** command run in a freshly-cloned instance, where the local environment isn't set up yet. In that state the script can't produce a card — so **route the builder to the one missing step instead of surfacing a raw error**. Match what you see and relay the single fix, plainly:
+
+- **`bongos: command not found`, a "cannot find module" from `node scripts/gds/start.js`, or you can otherwise tell this is a fresh checkout** (a scaffolded instance whose `node_modules` is absent). The `bongos` CLI ships *inside* the not-yet-installed `@bongos/core` package, so nothing runs until deps are installed — this is the #1 fresh-clone wall. Route: run `npm install`, then `bongos dev` (one-command local bring-up), then re-run `/builder-start`. Don't try to hand-run internal scripts; the package isn't unpacked yet.
+- **The card says the instance isn't reachable / running.** The local server was never brought up. Route: `bongos dev`, then re-run. (`start.js` now prints this guided card itself on a connection failure — relay it verbatim.)
+- **Exit code 3 / "Wrong instance — refusing to act".** This machine's signed-in session targets a *different* instance than this project's `config/branding.json`. This is correct-by-design (it prevents writing to the wrong place). Route: run the exact `bongos login <origin>` line the message prints (the origin is right there), then re-run. **Do not** set an env override to force the mismatched instance.
+- **"no GDS session"** — the auth case above (`/builder-setup` for a first-timer, `/builder-reauth` for a stale session).
+
+Emit one guided next step, not a wall of options. These are the same fixes `bongos doctor` and the environment preflight (`preflight.js`) describe — this just front-loads them onto the first command so a newcomer isn't diagnosing a crash.
+
 ## After rendering
 
 - The widget rows are **click-to-claim**: a click sends "Claim task N", which you handle by running `/builder-claim N` (the `builder-claim` skill). A typed number does the same.

package/.claude/skills/builder-sync/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: builder-sync
+description: "Sync now — re-fetch the dev box's source immediately so a freshly-claimed task's code materializes within seconds, instead of waiting for the ~10-min cron. Triggers on '/builder-sync', 'sync my box', 're-scope my box', 'pull my task's code now', or right after '/builder-claim N' when the builder wants the code on the box now. Runs ON the box."
+---
+
+**Script skill (authoritative).** The core action is `node scripts/gds/box-sync.js`. Run it and relay its output verbatim.
+
+You are re-running the dev box's source-fetch **on demand** (BV1.R96, goal 1000051 — task-scoped dev box). The box normally re-fetches on a ~10-min cron; this makes it instant.
+
+## Why this exists
+
+A builder's box holds only the code for their **active claim** (ADR 0148 task-scoping): `GET /box/source-access` returns the sparse-checkout set for the modules the claimed task's goal scopes. The box applies that via `infra/box-source-fetch.sh`, on a cron every ~10 min. So right after `/builder-claim N`, the *new* task's code isn't on the box yet — until the next cron tick.
+
+`box-sync.js` re-runs that fetch **now**. Because the fetch re-reads `/box/source-access`, it **re-scopes the box in place** to whatever the builder currently holds a claim on — seconds after claiming, not ~10 minutes later. The cron stays the backstop.
+
+## How to use
+
+1. **Run it** (on the box):
+   ```
+   node scripts/gds/box-sync.js
+   ```
+   Add `--dry-run` to print what it would run without fetching.
+
+2. **Relay the output.** On success it prints `sync: done — your box now holds the code for your active claim.` The sparse-checkout is now scoped to the active claim's modules (plus the base instance).
+
+3. **Typical flow:** `/builder-claim N` → `/builder-sync` → the box now has task N's module code; open the working folder and start.
+
+## Failure modes
+
+- **`no infra/box-source-fetch.sh found`** — you are **not on a dev box** (off a box your source *is* your local checkout, so there's nothing to sync). This is expected on a laptop; the skill exits non-zero and says so.
+- **The fetch itself errors** — the underlying `box-source-fetch.sh` output is passed through verbatim (e.g. a credential/rank issue surfaces there); relay it and, if it's a rank/claim problem, check the active claim with `/builder-start`.
+
+## Constraints
+
+- **Runs on the box only.** It re-runs the box-side fetch; it does not push, claim, or change scope by itself — scope follows the builder's active claim (change scope by claiming a different task, then sync).
+- **Idempotent + safe.** Re-running is harmless; the cron does the same thing on its own schedule.
+
+## Files this skill touches
+
+- Runs: `scripts/gds/box-sync.js` → `infra/box-source-fetch.sh` (on the box)
+- Reads (indirectly, via the fetch): `GET /box/source-access`

package/.claude/skills/fix-task/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: fix-task
+description: Claim, fix, verify, and ship a single GDS task by id — the standard cloud-bongos task loop. Use when asked to "claim/fix/ship task NNNN".
+---
+
+You are running the standard task loop for cloud-bongos: read a task, verify its premise, claim it, fix it test-first, then ship it. This skill chains the pieces `/builder-claim` and `/builder-ship` already own — it does not re-derive their mechanics.
+
+## What this skill does
+
+Runs the recurring "claim, fix, and ship task NNNN" macro end to end. Its own value is the parts nothing else covers: verifying the task's premise before claiming (step 1), the test-first discipline (step 4), and confirming the ship actually landed instead of bouncing (step 7). For claiming and shipping themselves, it defers to `/builder-claim` and `/builder-ship`.
+
+## How to use
+
+1. **Read the task and verify it BEFORE claiming.**
+   ```
+   node scripts/gds/api.js GET /api/gds/tasks/<id>
+   ```
+   If the task names a root cause, open the actual code it points at and confirm that root cause is real — don't take the task's own diagnosis on faith. If the description doesn't match what the code does, say so before writing anything; a task built on a wrong premise needs a corrected task, not a fix for the wrong bug.
+
+2. **If the task is in `backlog`, promote it to `ready` first** (Metic+ only — `POST /tasks/:id/promote` is rank-gated):
+   ```
+   node scripts/gds/api.js POST /api/gds/tasks/<id>/promote --body '{}'
+   ```
+   Skip this step if the task is already `ready`.
+
+3. **Claim it** — see `/builder-claim` for the full mechanics (dedicated worktree, one-claim-per-session, and its error codes). In short:
+   ```
+   node scripts/gds/claim.js <id> --worktree <worktree-name>
+   ```
+
+4. **Write a failing test FIRST, then fix.** Add the case to the relevant `tests/*.mjs` file (or create one if none covers the surface) that reproduces the bug/gap the task describes. Run it and confirm it fails for the reason you expect — THEN implement the fix — THEN confirm the same test passes.
+
+5. **Run the full verification the ship gate expects, not just the one new test:**
+   - the whole touched `tests/*.mjs` file (every case, not just the new one)
+   - `node scripts/gds/fitness.js` (the architecture fitness gate — core/host boundary, CLAUDE.md budget, rank-guard)
+   - any other suite CLAUDE.md/CONTRIBUTING.md calls out for the surface you touched (e.g. a module's own nested CLAUDE.md test pointer)
+
+   A throwaway verification script or a one-off Playwright probe does **not** satisfy this — the grader only trusts a checked-in `tests/*.mjs` case (see `/builder-ship`).
+
+6. **Ship from the claim branch** — see `/builder-ship` for handoff notes, the value summary, and the completion-card rendering contract. In short:
+   ```
+   node scripts/gds/ship.js <id> --notes "..." --summary "..."
+   ```
+   **Never merge the claim branch into `main` before running `ship.js`.** `ship.js` diffs the branch against `main`; a pre-merged branch yields an empty diff, and the only way out is `--allow-empty` (dead-ends the task at `completed`, needing an Archon-only confirm) or reverting the merge. Ship from the branch and let `ship.js` land it — the same trap `/builder-ship` calls out.
+
+7. **Confirm the outcome — don't assume the ship landed.**
+   ```
+   node scripts/gds/api.js GET /api/gds/tasks/<id>
+   ```
+   - `shipped` (or `confirmed`, awaiting `/merge-mode`) → done; relay the completion card per `/builder-ship`.
+   - Still `completed` → the grader bounced it. **Surface its feedback verbatim** — don't paraphrase or summarize away the specifics — then loop back to step 4 with that feedback in hand.
+
+## Constraints
+
+- **Don't skip step 1.** A task's own description can be wrong; verifying against the live code before claiming avoids burning a claim on a fix for a bug that doesn't exist as described.
+- **Don't claim a task still in `backlog`** — promote it first (step 2), or the claim is refused (`TASK_NOT_READY`; see `/builder-claim`).
+- **Don't substitute a manual/throwaway check for a committed test** — see step 5.
+- **Don't merge to `main` before shipping** — see step 6 and `/builder-ship`'s own callout on the same trap.
+
+## Files this skill touches
+
+- Calls: `GET /api/gds/tasks/:id`, `POST /api/gds/tasks/:id/promote`, plus whatever `/builder-claim` and `/builder-ship` call for claiming and shipping.
+- Reads: `~/.config/otb/gds-session.json`
+- Writes: the fix itself, plus a new or extended `tests/*.mjs` case.

package/.claude/skills/goal-create/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: goal-create
+description: Plan and create ONE GDS goal — the module-scoped workspace between a version and its criteria (ADR 0086) — in a single interactive session. Claude reads the goal board, decides reuse-vs-new, infers scope_modules from the LIVE module roster, drafts the goal's done-when criteria and a seed-task outline on its own, then asks only about genuine gray areas and for one sign-off before writing anything. Scoped smaller than /planning-session (one goal in one sitting, no spec file, no migration) and the opening end of /goal-review (which closes goals out). Triggers when the user says "/goal-create", "create a goal", "make a goal for this", "plan a goal", "we need a goal to hold this work", "what goal should this live in", or automatically when a task is created with no goal to live in — a POST /tasks response carrying a `goal_advisory`, or work about to land in a version's "<version> — general" catch-all. Metic+ rank only (Metic and Archon; not Xenos) — Archon for a protected-module scope.
+---
+
+You are running the **goal-create** session for this Cloud Bongos instance. You produce **one goal**: a title, a scope wall, two to four done-when criteria, and a handful of seed tasks — written to the GDS in one sitting.
+
+> **Not `/planning-session`, not `/goal-review`.** `/planning-session` scopes a whole **version**: 5–9 criteria, a written spec under `docs/specs/`, a multi-round interview, a seed script, a migration. This skill produces **one goal**, with no spec file and no migration. `/goal-review` is the other end of the same lifecycle — it *confirms* criteria and auto-achieves goals. If the ask is "plan the next version", stop and run `/planning-session` instead.
+
+## Rank gate — Metic+ only
+
+**Gated to Metic+ (Metic, Archon); not Xenos.** Creating a goal sets a **scope wall** — the module keys its members may author inside — and seeds the criteria a slice of the version will be judged against. That is a trusted-builder operation (ADR 0086 §3/§4). The server enforces it: `POST /api/gds/goals` is `requireRank('metic','archon')`, and `POST /api/gds/versions/:id/done-when` is `requireRank('metic','archon')` **plus a goal-ownership wall** (ADR 0154) — both pinned in `route-rank-check.MODULE_EXPECTED_RANKS.lifecycle`. This check just stops a Xenos early instead of after a wall of 403s. Markdown never grants authority ([`docs/canonical-permissions.md`](../../../docs/canonical-permissions.md), [ADR 0016](../../../docs/adr/<redacted>.md)).
+
+**Enforce the gate at the very top of the session, before reading anything else:**
+
+1. Call `node scripts/gds/api.js GET /api/gds/me` and read `builder.rank`. Compare case-insensitively (lowercase it before testing).
+2. **If `rank` lowercases to `xenos`** → stop immediately. Tell the builder: *"Creating a goal sets a scope wall and seeds a version's done-when criteria — a Metic+ operation. You're currently Xenos. You can still **file** the proposal as an idea (`node scripts/gds/capture.js "…"`) for an Archon to promote at triage; ask an Archon for promotion if you need to create goals directly."* Do not read the goal board, do not draft criteria.
+3. **If `rank` lowercases to `metic` or `archon`** → proceed with the phases below.
+4. **If `rank` is absent** (a deployment where the three-rank model hasn't shipped) → treat the session as available, exactly as `/idea-triage` does in its pre-rank passthrough mode, and note that in the session log.
+5. **The protected-scope branch is a SECOND gate, decided in Phase 3 — not here.** A goal whose `scope_modules` includes a **protected** key is Archon-only to create (`403 archon_required_for_protected_scope`) and Archon-mediated to join. You do not know the scope at gate time. Draft it in Phase 3, then take one of the off-ramps in Phase 5 if you are a Metic and the drafted scope is protected.
+
+## What this skill does
+
+1. Reads the live goal board for the target version, and the version's existing criteria.
+2. Decides **reuse vs. create** — an open goal whose outcome and scope already cover the work wins; a net-new goal only when nothing does.
+3. Drafts, on its own: title · description · `scope_modules` (verified against the **live** roster) · `succeeds_goal_id` lineage · 2–4 criteria · a seed-task outline.
+4. Asks — via AskUserQuestion — only the gray areas it genuinely cannot decide, then **one** approval round.
+5. Writes in the order **goal → criteria → tasks**, then verifies and reports.
+
+## Phase 1 — Read the board (autonomous; ask nothing)
+
+Determine without asking:
+
+- **The version.** `node scripts/gds/api.js GET /api/gds/public/versions`. If exactly one is `building` or `planning`, take it. Ask only when two or more are open *and* the work doesn't obviously belong to one.
+- **The existing goals.** `node scripts/gds/api.js GET "/api/gds/goals?version=<ver>&status=open"`, then `GET /api/gds/goals/<id>` on each plausible candidate — the detail response is `{goal, members, criteria, dependencies}`, which is what tells you whether a candidate already owns criteria in this space.
+- **The version's criteria.** `node scripts/gds/api.js GET "/api/gds/versions/<ver>/done-when"` → `{version_id, criteria, goals}`. Use it to avoid a `criterion_id` collision and to pick the next `sort_order` (max + 1).
+- **The module roster — LIVE, never from memory and never from this file:**
+
+  ```
+  node -e "const m=require('./src/bongos/module-scope-map');console.log(m.moduleKeys().map(k=>k+(m.isProtectedModule(k)?' [PROTECTED — Archon-only]':'')).join('\n'))"
+  ```
+
+  > **Run the line. Do not paste a roster anywhere, including into this file.** `protected` is *derived* from glob overlap with the trust core, so it changes when the globs change. The snapshot in `/planning-session`'s Phase 2.5 rotted within one release and now omits a key — that is the failure mode this rule exists to prevent.
+
+- **Lineage**, only when this goal continues a prior version's work: `node scripts/gds/api.js GET "/api/gds/goals?version=<prev>&status=achieved"` and pick the predecessor for `succeeds_goal_id`.
+
+## Phase 2 — Reuse or create (autonomous; one question only on a genuine tie)
+
+> **Reuse** when an open goal's outcome already contains this work *and* its `scope_modules` already cover the files it touches. **Create** when the work is a distinct outcome, or when reusing would force that goal's wall to widen into a new module — widening is `POST /goals/:id/scope`, a separate ask a trusted rank approves. Don't smuggle it in.
+
+If the answer is reuse, **stop creating.** Report the goal id, and if an orphan task triggered this session, move it:
+
+```
+node scripts/gds/api.js PATCH /api/gds/tasks/<task_id> --body '{"goal_id":<gid>}'   # ids only — safe inline
+```
+
+Only a real tie between two candidates earns an AskUserQuestion.
+
+## Phase 3 — Draft the goal (autonomous)
+
+Everything here is your call. It is presented in Phase 4 as a proposal, not as questions.
+
+- **Title** — the outcome the goal owns, not a task list. One line.
+- **`description`** — 2–4 sentences: what is true when this goal is achieved, and what it explicitly does not cover.
+- **`scope_modules`** — infer from the planned work's file paths, then **verify every key against `moduleKeys()`**. An unknown key is a hard `400 unknown_module` (the response helpfully returns the full valid roster). Keep it tight: the wall is set here and only here. **No covering key?** Do not invent one — file a `kind='refactor'` prep task scoped to `kernel` to extend `MODULE_GLOBS`, and make this goal's tasks depend on it.
+- **`succeeds_goal_id`** — set it when carrying an achieved goal forward. `POST /goals` validates the predecessor exists *before* creating, so a bad ref can't orphan a goal; it then stamps the predecessor's `succeeded_by_goal_id`. Archiving the predecessor is a **separate** call.
+- **Criteria — 2 to 4.** A goal's criteria are narrower than a version's: each should plausibly anchor 2–5 tasks. Draft `criterion_id` as a stable kebab slug (position-independent, and what `criterion_ids` on `POST /tasks` should reference); `criterion_md` is the outcome prose.
+- **Seed tasks — 3 to 8.** Per criterion, with `kind`, a one-line done-when, `criterion_ids: ["<slug>"]`, and dependency edges. Omit `touches[]` (advisory, ADR 0049 — backfilled from the real diff at ship). Never hand-set `requires_rank` (auto-derives, ADR 0084). Proof tasks use `kind='verify'`; exploration uses `kind='spike'` (and spikes are deliberately left in backlog).
+
+## Phase 4 — Ask, then get sign-off
+
+Two rounds at most, both via **AskUserQuestion**.
+
+1. **Gray-area round — at most one round, at most 4 questions, often zero.** A question earns its place only if the work is genuinely underspecified on it, reasonable people would disagree, **and** the answer changes the goal's shape. Put your recommendation first and leave room for "Other". Legitimate gray areas: where this goal's boundary falls against an adjacent one; whether a module belongs inside the wall or is a dependency; whether this succeeds a prior goal or replaces it; whether a criterion belongs to this goal or the version. **Do not ask** anything the goal board, the criteria list, or `moduleKeys()` already answers, and never ask a yes/no rubber-stamp.
+2. **The approval round — always exactly one, always last.** Present the goal (title · `scope_modules` · join policy · succeeds), the **numbered** criteria, and the seed-task table. Then one question: **Create it** / **Goal + criteria only** (skip the seed tasks) / **Edit first** / **Cancel**. Number the criteria so the user edits by number rather than by copy/paste.
+
+## Phase 5 — Land it (write order: goal → criteria → tasks)
+
+The order is forced: a criterion needs `goal_id`, a task needs both `goal_id` and the criterion slugs.
+
+> **Always `--body-file`, never inline `--body`, for anything carrying a title, description or criterion prose.** Those strings are authored in this session and routinely contain an apostrophe ("the builder's hall"), which terminates a single-quoted shell argument and corrupts the JSON — or, with a hostile string, runs whatever follows on the builder's machine. Write the body to a temp `.json` file and pass its path. On Windows also heed `scripts/gds/CLAUDE.md`: do **not** create that file with `Out-File`/`>` (the UTF-8 BOM breaks `JSON.parse`), and never pipe `api.js` through `2>&1` (its banner goes to stderr by design).
+
+```
+# 5a — the goal. STRICT validation: exactly these five fields are accepted
+#      (version_id*, title*, description, scope_modules[], succeeds_goal_id).
+#      ANY other key is a 400 unknown_field — do NOT pass criteria, tasks, lead or visibility.
+#   goal.json: {"version_id":"<ver>","title":"...","description":"...","scope_modules":["<key>"]}
+#   carry-forward: add "succeeds_goal_id":<prior_goal_id>
+node scripts/gds/api.js POST /api/gds/goals --body-file <path-to-goal.json>
+# → 201 {ok, goal, succeeds_goal_id}. CAPTURE goal.id.
+# You are now the goal's OWNER and its 'lead' member — the membership row is inserted
+# in the SAME statement, so there is NO join step. Don't POST /goals/<id>/join after.
+
+# 5b — the criteria, one call each, in presentation order.
+#   criterion.json: {"criterion_id":"<slug>","criterion_md":"...","goal_id":<gid>,"sort_order":<n>}
+node scripts/gds/api.js POST /api/gds/versions/<ver>/done-when --body-file <path-to-criterion.json>
+# You may write these because you OWN the goal (ADR 0154), not merely because you are
+# a Metic. Refusals: 409 criterion_exists (slug already on this version — reuse it,
+# don't rename around the collision) · 409 goal_not_open · 409 version_closed ·
+# 400 bad_goal_id (which ALSO masks "you don't own this goal" — see below).
+
+# 5c — the seed tasks, one call each. --body-file avoids shell-quoting description/arrays.
+node scripts/gds/api.js POST /api/gds/tasks --body-file <path-to-task.json>
+#   {"version_id":"<ver>","goal_id":<gid>,"title":"...","description":"...",
+#    "kind":"feature|refactor|infra|spike|verify|decision","priority":N,"est_minutes":N,
+#    "criterion_ids":["<slug>"],"source":"goal-create","source_ref":"goal-<gid>-R##"}
+# criterion_ids takes a SLUG (preferred), a "Cn" position, or a numeric id; an
+# unresolvable ref is 400 bad_criterion_ref and NOTHING is created. source_ref makes a
+# re-run idempotent (a repeat returns the original task with "idempotent": true).
+# Throttle between calls and honour 429 retry_after.
+
+# 5d — dependency edges, only where a real gate exists.
+node scripts/gds/api.js POST /api/gds/tasks/<id>/dependencies --body '{"depends_on_task_id":<id>}'  # ids only
+
+# 5e — promote the zero-dependency layer. Every new task lands status='backlog', and
+#      auto-promotion only fires when a DEPENDENCY ships — so a task with no deps would
+#      sit unclaimable forever. Leave spikes in backlog.
+node scripts/gds/api.js POST /api/gds/tasks/<id>/promote
+
+# 6 — verify + report.
+node scripts/gds/api.js GET /api/gds/goals/<gid>            # {goal, members, criteria, dependencies}
+node scripts/gds/api.js GET "/api/gds/tasks?goal_id=<gid>"
+```
+
+### Protected scope — the Archon off-ramps
+
+> **If the drafted `scope_modules` contains a protected key and you are a Metic, do not POST.** `POST /goals` returns `403 archon_required_for_protected_scope`, and a protected-scope goal is Archon-mediated to join in any case. Say so plainly and offer three routes:
+> 1. **Narrow the wall.** Usually only *part* of the work needs the protected module. Create the goal scoped to the unprotected keys, and file the protected-core piece as a task under an existing Archon-owned goal.
+> 2. **Hand an Archon the drafted body.** They create it, then admit you via `POST /goals/:id/members` (Archon-only for protected scope, and the target must be Metic+).
+> 3. **File it as an idea** — `node scripts/gds/capture.js "<the goal proposal>"` — for an Archon to promote at `/idea-triage`.
+>
+> **Do not** create the goal narrow intending to widen it later. Widening into a protected key is Archon-gated too. Scope is never self-granted (ADR 0086 §4).
+
+### A 400 on a criterion can mean "not your goal"
+
+`POST /versions/:id/done-when` deliberately returns the **same** `400 bad_goal_id` whether the goal doesn't exist or you simply don't own/manage it — so the route can't be used to probe which goals (including private ones) exist on a version (ADR 0154). If you get `bad_goal_id` for a goal you just created, you are almost certainly writing to the wrong version; if it's a goal someone else owns, ask them or an Archon to add the criterion.
+
+## Auto-invoked from a task create (the orphan hook)
+
+When `POST /tasks` came back with a non-null **`goal_advisory`**, you were invoked to give that task a home.
+
+- `reason: "no_goal"` — the task has no goal at all. Its version has no catch-all, which is normal for any version created after the goal tier shipped.
+- `reason: "catch_all"` — it landed in `"<version> — general"`: a bucket with no scope wall, no criteria and no owner.
+
+Run the phases above **with the orphan task as the seed** — its title, description and touches are your best evidence for the goal's title and `scope_modules`. Two shortcuts:
+
+- **Prefer reuse.** `goal_advisory.candidate_goals` already lists the version's open goals with the catch-all excluded. Check each with `GET "/api/gds/goals/<id>/suggest-criteria?title=<t>&description=<d>"` — a strong criterion match means the task belongs there and no new goal is needed. Move it with `PATCH /tasks/<id> {"goal_id":<gid>}`.
+- **If you do create a goal, re-home the orphan into it** (same PATCH) and link the criterion: `POST /api/gds/tasks/<task_id>/criteria --body '{"criterion_ids":["<slug>"]}'` (slugs are kebab-case, so inline is safe). Do **not** delete and recreate the task — you would lose its id, `source_ref` and any votes.
+
+**A goal-less task is not an error and was never blocked.** `goal_advisory` is advice on a request that already succeeded. Never fail a build, refuse work, or badger the builder over it — if they say "later", file the idea and move on.
+
+## Why we run this
+
+Nothing in the system creates a goal on its own, and nothing errors when a task has none. `db.createTask` falls back to the version's `"<version> — general"` catch-all, and those rows were created **only** by migration 160, for the versions that existed at that moment — `db.createVersion` makes no such goal and there is no trigger. So on any newer version, every task quietly gets `goal_id = NULL`: no scope wall, no criteria gating it, no workspace where anyone reviews it. This skill is how a real goal comes to exist before that happens.
+
+## Tone for the user
+
+Lars is the prompter (see CLAUDE.md §2). Frame the goal as an **outcome** — what is true when it's done — never as a `scope_modules` array or a rank discussion. Decide the mechanics yourself; ask only about the boundary: what this goal owns, and what it deliberately doesn't. Keep the approval round to one screen.

package/.claude/skills/goal-review/SKILL.md

@@ -5,11 +5,13 @@ description: Walk the GDS criterion review queue — for each criterion auto-fla
 
 You are running the **goal-review** session for this Cloud Bongos instance. It mirrors `/idea-triage`, but for the *closing* end of the work hierarchy (ADR 0086 §6): criteria that have **auto-flagged "met — pending review"** get walked one-at-a-time and dispositioned, so finished work actually closes out instead of sitting in limbo.
 
+> **The other end of this lifecycle is [`/goal-create`](../goal-create/SKILL.md)** — it opens a goal (scope wall, criteria, seed tasks); this one closes it out.
+
 **The auto-flag is derived, not stored.** When every task linked to a criterion has shipped — and the criterion has not yet been confirmed — the server flags it `pending_review` (deterministic from `task_criteria` + ship status; no manual propose step). This skill surfaces that queue and lets a trusted builder confirm or reject each one. Confirming sets the criterion `satisfied=true`; confirming a goal's **last** unsatisfied criterion auto-flips the goal `open → achieved`.
 
 ## Rank gate — Metic+ only
 
-**Gated to Metic+ (Metic, Archon); not Xenos.** Confirming a criterion sets `satisfied=true` and can auto-achieve a goal — a trusted-builder operation that closes out a slice of a version (the "who confirms" resolution in ADR 0086 §6: the planner, not only the Archon). The server enforces this — `POST /api/gds/done-when/:criterionId/satisfy` is `requireRank('metic','archon')` and pinned in `route-rank-check.EXPECTED_RANKS` — so this check just stops a Xenos early instead of after a wall of 403s. Markdown never grants authority ([`docs/canonical-permissions.md`](../../../docs/canonical-permissions.md), [ADR 0016](../../../docs/adr/<redacted>.md)).
+**Gated to Metic+ (Metic, Archon); not Xenos.** Confirming a criterion sets `satisfied=true` and can auto-achieve a goal — a trusted-builder operation that closes out a slice of a version (the "who confirms" resolution in ADR 0086 §6: the planner, not only the Archon). The server enforces this — `POST /api/gds/done-when/:criterionId/satisfy` is `requireRank('metic','archon')` and pinned in `route-rank-check.MODULE_EXPECTED_RANKS.lifecycle` — so this check just stops a Xenos early instead of after a wall of 403s. Markdown never grants authority ([`docs/canonical-permissions.md`](../../../docs/canonical-permissions.md), [ADR 0016](../../../docs/adr/<redacted>.md)).
 
 **Enforce the gate at the very top of the session, before reading anything else:**
 

package/.claude/skills/idea-triage/SKILL.md

@@ -5,6 +5,8 @@ description: Daily walk through the GDS idea_inbox — for each open idea, promp
 
 You are running the daily idea-triage session for Example. Open ideas in the GDS `idea_inbox` table get walked one-at-a-time and verdicted, so the inbox doesn't accumulate stale entries.
 
+> **This skill is no longer the only way to triage.** Since task 1002447 a Metic+ builder can promote, discard and merge from the **hall** — the Home "Needs your attention" card's idea rows each carry a *Triage* verb that opens the record overlay, where all three forms live. No Claude session involved. What this skill adds over the hall is the **parallel development pass** (Step 1.5) — an idea fleshed out into open questions/risks before the verdict — so reach for it when the queue needs judgment, and use the hall when it just needs clearing.
+
 ## Rank gate — Metic+ only
 
 **Gated to Metic+ (Metic, Archon); not Xenos.** Triage verdicts (promote, discard, merge) reshape the team's backlog — a trusted-builder operation (GDS-V3 criterion C2, `three-ranks-gate-everything`; [`docs/canonical-permissions.md`](../../../docs/canonical-permissions.md), [ADR 0018](../../../docs/adr/<redacted>.md)). A Xenos can still **file** an idea (`POST /api/gds/inbox`); they just can't verdict them.
@@ -42,7 +44,9 @@ If `open_count` is 0, print "inbox empty — nothing to triage today" and exit.
 
 **Step 1.5 — develop the open ideas in parallel (task 930).**
 
-Before walking the list, **flesh out each open idea with a subagent** so the verdict lands on a developed idea, not a one-liner. Spawn the subagents **in parallel** (multiple `Agent` tool calls in a single message) — they run while you prepare the walk, so there's no serial wait.
+**Before spawning any subagents, run a cheap staleness pass over the list first** — a quick skim of each idea's title/body against the current codebase/CLAUDE.md to catch ideas that are already implemented, already superseded, or otherwise obviously stale. A recent triage found 47 of 170 open ideas already stale; filtering those out first means the expensive multi-agent development pass below is only spent on ideas that still need it.
+
+Then, before walking the list, **flesh out each remaining open idea with a subagent** so the verdict lands on a developed idea, not a one-liner. Spawn the subagents **in parallel** (multiple `Agent` tool calls in a single message) — they run while you prepare the walk, so there's no serial wait.
 
 - **Model:** `opus` for every development subagent. This is research / design analysis against the live repo, which per CLAUDE.md §2's routing table is Opus work — never inherit silently, never downgrade to Haiku.
 - **Fan-out cap:** develop up to **12** ideas per session (oldest-first — `captured_at` ascending). If there are more than 12 open, note "developed the 12 oldest; the rest are walked undeveloped" so nothing is silently dropped.
@@ -71,7 +75,7 @@ node scripts/gds/triage.js --development "${TMPDIR:-/tmp}/otb-idea-development.j
 **Step 2 — walk the list, idea by idea.**
 
 Present each idea with:
-- id + kind (auto-classified by B2)
+- id + kind (auto-classified by B2 — one of `feature`, `bug`, `infra`, `refactor`, `spike`, `learning-capture`, `cleanup`, `decision`, `blocker-resolution`, `unclassified`, `criterion-proposal`; mirrors `tasks.kind` plus the triage-only `criterion-proposal` value, `modules/ideas/inbox.js`)
 - title
 - body_md (full)
 - captured_at + captured_by
@@ -85,7 +89,7 @@ Then ask the user (concise prompt — Lars is an EE, not a software engineer; fr
 
 **Promote → pick the tier (BV1.R64 / ADR 0086).** An idea no longer only becomes a *task* — it can promote into any tier of the work hierarchy: a **goal** (a whole module-scoped workspace), a **criterion** (a new done-when test), or a **task** (a single unit of work). Choose by the idea's size: a broad objective → goal; a "we should also require X to be done" → criterion; a concrete piece of work → task. Frame the choice to the user in those terms, then create the right record and mark the idea promoted.
 
-- **Promote → task** (the common case). Ask for version, title, est_minutes, priority, credits_reward (`touches[]` optional — [ADR 0049](../../../docs/adr/<redacted>.md)). (Filing a task *under a goal* — stamping `tasks.goal_id` — is the bounded-authoring route's job, R60; until it lands, promote to a task at the version level and link it to a goal's criteria via `criterion_ids`.)
+- **Promote → task** (the common case). Ask for version, title, est_minutes, priority, credits_reward (`touches[]` optional — [ADR 0049](../../../docs/adr/<redacted>.md)). `POST /api/gds/tasks` lands the new task in `backlog`, **not** `active` — it still needs `POST /tasks/:id/promote` (Metic+) before it's claimable. **Pass `goal_id` on the create** so the task lands in a real goal rather than the version's `"<version> — general"` catch-all — `POST /tasks` has accepted it since task 1763, and the 201 now returns a `goal_advisory` when the task ends up with no proper home. If no existing goal fits, run [`/goal-create`](../goal-create/SKILL.md) instead of filing it loose.
 
   ```
   # 1. Create the task (--body-file avoids shell-quoting the touches[]/description).
@@ -96,7 +100,7 @@ Then ask the user (concise prompt — Lars is an EE, not a software engineer; fr
   node scripts/gds/api.js PATCH /api/gds/inbox/<idea_id> --body '{"status":"promoted","promoted_to_task_id":<new_task_id>}'
   ```
 
-- **Promote → goal** (Metic+; Archon if the scope includes a `protected` module). Create the goal, then mark the idea promoted — `promoted_to_task_id` stays NULL (a goal isn't a task; note the new goal id in the session log, mirroring how criterion-promotion records its link).
+- **Promote → goal** (Metic+; Archon if the scope includes a `protected` module). For anything needing criteria and seed tasks, run [`/goal-create`](../goal-create/SKILL.md) — it does the reuse-vs-new check, the scope wall and the sign-off. The bare one-liner below is fine only for a goal you are deliberately leaving empty. Create the goal, then mark the idea promoted — `promoted_to_task_id` stays NULL (a goal isn't a task; note the new goal id in the session log, mirroring how criterion-promotion records its link).
 
   ```
   node scripts/gds/api.js POST /api/gds/goals --body '{"version_id":"<ver>","title":"...","description":"from idea #<idea_id>","scope_modules":["<module-key>", ...]}'
@@ -111,18 +115,20 @@ Then ask the user (concise prompt — Lars is an EE, not a software engineer; fr
 
   If the idea isn't already criterion-proposal-shaped, either re-file it in that shape or promote it to a task/goal instead — don't hand-write a `done_when_criteria` row.
 
-**Discard** → mark it closed:
+**Discard** → mark it closed, with the reason (`triage_note`, task 1002447 / migration core_195 — a discard with no reason is a verdict nobody can audit):
 
 ```
-node scripts/gds/api.js PATCH /api/gds/inbox/<idea_id> --body '{"status":"discarded"}'
+node scripts/gds/api.js PATCH /api/gds/inbox/<idea_id> --body '{"status":"discarded","triage_note":"superseded by the new gate"}'
 ```
 
-**Merge** → ask the user which other idea N is the canonical one, then mark this one merged:
+**Merge** → ask the user which other idea N is the canonical one, then fold this one into it:
 
 ```
-node scripts/gds/api.js PATCH /api/gds/inbox/<idea_id> --body '{"status":"merged","promoted_to_task_id":<canonical_idea_or_task_id>}'
+node scripts/gds/api.js PATCH /api/gds/inbox/<idea_id> --body '{"status":"merged","merged_into_idea_id":<canonical_idea_id>,"triage_note":"same ask as #N"}'
 ```
 
+> **`merged_into_idea_id`, NOT `promoted_to_task_id`.** This skill used to document the latter; that column is `REFERENCES tasks(id)`, so an idea id written there either trips the FK (a 500) or silently points at an unrelated task that happens to share the number. Task 1002447 added the real column. The server refuses a self-merge (`MERGE_SELF`), a target that doesn't exist (`MERGE_TARGET_NOT_FOUND`), and a target that is itself merged (`MERGE_TARGET_MERGED` — it names where the chain ends, so retarget there).
+
 **Defer** is implicit — leave the idea open by not patching it. Inbox count stays the same; the idea will surface again tomorrow.
 
 **Step 4 — surface a summary.**

package/.claude/skills/merge-mode/SKILL.md

@@ -5,7 +5,7 @@ description: Manual fallback for the auto-merge in /builder-ship. Walks every ta
 
 You are running the manual merge-mode session for Example. **`/merge-mode` is a rare last resort, not a routine sweep — and not something to push on other builders.** The server lands merges on its own: `/builder-ship` chains into auto-merge, green PRs auto-merge, a 5-min reconciler flips `confirmed → shipped`, and the [ADR 0082](../../../docs/adr/<redacted>.md) resolver self-heals generated-file conflicts. **Before running this skill, confirm the task is genuinely stuck** — still at `confirmed` more than ~5 minutes after its ship because of a conflict or regression the server couldn't auto-resolve. If you haven't waited for the sweep yet, stop and wait. This skill is for the strand that survives all of that — usually a cross-branch / non-generated-file conflict, a smoke regression, or a `--no-merge` ship.
 
-The queue this skill works against is **tasks at status='confirmed'**. Those are tasks where the builder declared done, verification passed, credits landed, and the only thing missing is the merge to main + deploy.
+The queue this skill works against is **tasks at status='confirmed'**. Those are tasks where the builder declared done, verification passed, and the only thing missing is the merge to main + deploy. **They are not yet paid** — [ADR 0120](../../../docs/adr/<redacted>.md) books the reward on land, so landing the queue is what releases those builders' credits.
 
 ## What this skill does
 
@@ -144,7 +144,7 @@ For each task that successfully merged + deployed:
 node scripts/gds/api.js POST /api/gds/tasks/<task-id>/ship
 ```
 
-The `POST /tasks/:id/ship` endpoint flips the task to `shipped`, stamps `shipped_at`. No credit implication — credits already landed at confirmed.
+The `POST /tasks/:id/ship` endpoint flips the task to `shipped`, stamps `shipped_at`. **This is the credit moment** — [ADR 0120](../../../docs/adr/<redacted>.md) books the reward on land, so this call is what pays the builder (on a `cost-plus-only` instance like Cloud Bongos that is the cost-plus session reward only — the per-task estimate is never paid; [ADR 0146](../../../docs/adr/<redacted><redacted>.md)).
 
 **Step 7 — surface a summary.**
 

package/.claude/skills/new-project/SKILL.md

@@ -108,4 +108,5 @@ A new owner has gone zero → live: their own standalone repo on a pinned core,
 - **This skill is the source of truth for the sequence.** If a step changes, change it here; `bongos onboard` (task 1982) and the hall wizard (task 1983) must render the same sequence.
 - **Standalone only** (ADR 0108) — do not fall back to editing this monorepo's checkout for a new project.
 - **Never weaken the trust boundary** — the web tier enqueues; only the control-plane runner (`provision.js`) touches cloud tokens (ADR 0016 / 0111 §2).
+- **Live docs are automatic** — a standalone instance's session-log index regenerates on deploy (`provision.js` runs `regen-instance-docs.js` after migrate; `bongos init`/`upgrade` seed+refresh it), and the whole-file nav docs are gitignored so `git reset --hard` never wipes them ([ADR 0147](../../../docs/adr/<redacted>.md)). If you wire a **bespoke** deploy script for an instance, it MUST call `node node_modules/@bongos/core/scripts/gds/regen-instance-docs.js` after `git reset` + migrate — see [`docs/recipes/standalone-live-docs.md`](../../../docs/recipes/standalone-live-docs.md).
 - **Adopting an EXISTING repo** (brownfield) is the other branch of the scaffold leg (step 3) — `bongos init --adopt` ([ADR 0121](../../../docs/adr/<redacted>.md)): detect → accept-gated conflict pre-flight → additive layering (never clobbers) → real version/goal + backlog import. Built; the `bongos onboard` CLI and the hall "start a project" wizard offer the same greenfield-vs-adopt choice.