@bongos/core 1.17.0

package/.claude/skills/planning-session/SKILL.md

@@ -0,0 +1,299 @@
+---
+name: planning-session
+description: Run a structured planning session for an upcoming GDS version — set scope criteria, brainstorm tasks, rank them, and upload everything to the GDS in one atomic shot. Triggers when the user says "/planning-session", "open a planning session", "let's plan V[N]", "plan the next version", or "scope a new version". Metic+ rank only (Metic and Archon; not Xenos).
+---
+
+You are running a planning session for the Game Development System (GDS). The goal is to leave the session with: (a) a clear set of done-when criteria for a version, (b) a ranked task list that lives in the GDS database, and (c) a durable record of the session for the audit trail.
+
+The first planning session — V3 Planning Session #1, 2026-05-12 — is the template this skill encodes. See `docs/session-logs/<redacted>.md` for the precedent and `tasks/227` (V3.R00) for the meta-task pattern.
+
+## When to invoke
+
+- The user says "let's plan V4" / "plan the next version" / "open a planning session"
+- A version is in `status='planning'` and needs scope locked before tasks start landing in earnest
+- A previous planning session left proposals in `idea_inbox` tagged `kind='criterion-proposal'` that need ratification
+
+## When NOT to invoke
+
+- Mid-version: planning sessions set scope, they don't refine it. For mid-version adjustments, use `/idea-triage`.
+- Without a clear target version: ask the user which version is being planned before doing anything else.
+- For a task-level scope question: that's a normal task description, not a planning session.
+
+## Rank gate — Metic+ only
+
+This skill is **gated to Metic and above** (Metic, Archon). It is **not** available to Xenos, the lowest rank. A planning session sets the scope-truth of a version: the criteria all subsequent tasks anchor to, the dependency graph other builders inherit, the rank ordering the queue surfaces. That's a trusted-builder operation, not something a sandboxed Xenos should reshape on their own.
+
+This mirrors GDS-V3 criterion C2 (`three-ranks-gate-everything`) and matches the gate the sibling skills already enforce (see [`docs/canonical-permissions.md`](../../../docs/canonical-permissions.md), [ADR 0018](../../../docs/adr/<redacted>.md), and the existing rank-gate frontmatter in [`/idea-triage`](../idea-triage/SKILL.md) and [`/blocker-review`](../blocker-review/SKILL.md)).
+
+**Enforce the gate at the very top of the session, before reading anything else:**
+
+1. Call `GET /api/gds/me` and read `builder.rank`. Compare case-insensitively (lowercase it before testing).
+2. **If `rank` is present and lowercases to `xenos`** → stop immediately. Tell the builder: *"Planning sessions set the scope-truth of a version — they're a Metic+ operation. You're currently Xenos. You can still **file** a criterion proposal or task idea via `POST /api/gds/inbox` (which lands in idea_inbox for an Archon to ratify at the next planning session); ask an Archon for promotion if you need to run sessions directly."* Do not pull state, do not present criteria, do not propose tasks.
+3. **If `rank` lowercases to `metic`** → proceed in **Metic-mode**: run the five-phase structure below conversationally, but in Phase 5 write proposals to `idea_inbox` (kind=`criterion-proposal` for criteria, kind=`feature` for tasks) tagged with the target version. Archon ratifies at the next Archon-mode planning session. Do NOT write `done_when_criteria` rows or POST to `/tasks` directly — those are Archon writes.
+
+   **For each criterion proposal**, write `body_md` as a JSON object with this exact shape so the `POST /api/gds/inbox/:id/ratify` endpoint (V3.R31 / #252) can parse it cleanly:
+
+   ```json
+   {
+     "target_version": "<ver>",
+     "criterion_md": "Full markdown of the criterion as it should appear in done_when_criteria.criterion_md.",
+     "sort_order_hint": 200
+   }
+   ```
+
+   `target_version` is required and must match an existing `versions.id`. `criterion_md` is required and is the user-visible criterion text. `sort_order_hint` is optional — omit or pass `null` to let the ratify endpoint default it to `max(existing sort_order) + 1` on the target version. On ratify, the proposer earns +5 karma (`reason='proposal_ratified'`) and the audit row in `criterion_proposal_audit` captures the full provenance.
+
+   **Net-new version a Metic can't create yet (idea 425).** The Metic-mode path above assumes the target version *already exists* — its criterion proposals carry `suggested_version` (an FK to a `versions` row) and a `target_version` that must match `versions.id`. But version creation is **Archon-gated**: a Metic planning a *brand-new* version (one with no `versions` row yet) has no valid FK to point at, so the normal proposal can't land. When that's the case, run the session in Metic-mode as usual through Phases 1–4, then in Phase 5 file the proposals like this instead:
+
+   1. **OMIT `suggested_version` on every proposal row.** It is an FK to a version row that doesn't exist yet; leaving it set would fail the constraint (or worse, attach the proposal to the wrong existing version). Leave it `null`/absent.
+   2. **Keep `target_version` INSIDE the criterion-proposal `body_md` JSON as plain text** (the version's intended id/slug, e.g. `"V4"`). It is *not* validated as an FK there — it's a label the Archon reads at ratify time. Once the Archon creates the real version row, the proposal is ratifiable as-is: `POST /api/gds/inbox/:id/ratify` resolves `target_version` against the now-existing `versions.id`.
+   3. **File ONE umbrella feature idea** (`kind='feature'`) that captures the whole net-new version in a single inbox row: the proposed version (id/slug + one-line theme), its goals, and a seed spec (the agreed criteria + the brainstormed task list). This is the thing an Archon picks up to actually create the version, then ratify the criterion proposals against it. One umbrella idea — not one idea per task — keeps the net-new version reviewable as a single unit.
+
+   Tell the Metic plainly: *"This version doesn't exist yet, and creating a version is an Archon step. I've filed your criteria as proposals (with the version name kept as text inside each) plus one umbrella idea describing the whole version. An Archon creates the version row, then ratifies these against it — your karma and attribution carry through."*
+4. **If `rank` lowercases to `archon`** → proceed in **Archon-mode**: full session, Phase 5 writes the migration + tasks + dependencies + done_when_criteria atomically. This is the flow described below.
+5. **If `rank` is absent** (the `/me` response has no `rank` field — only possible against a deployment where the three-rank model hasn't shipped yet): treat the session as Archon-mode, exactly as `/idea-triage` does in its pre-rank passthrough mode. Note in the session log that the gate ran in pre-rank passthrough mode.
+
+> The gate is **belt-and-braces**: the server already rejects `POST /api/gds/tasks`, `POST /tasks/:id/dependencies`, and `POST /done-when/:id/satisfy` with `403 rank_forbidden` for non-Archon callers, and `POST /api/gds/inbox` with `kind='criterion-proposal'` is gated to Metic+ (so a Xenos can't slip a criterion proposal in via raw curl). This frontmatter + check is the *intent surfaced to the operator*; the server is the *enforcement*. The skill stops early so a Xenos doesn't walk through a whole session only to hit 403s on every write in Phase 5.
+
+## The session — five phases
+
+### Phase 1 — Set the table
+
+1. **Confirm the target version.** Pull `GET /api/gds/public/versions`. If the user didn't name one, list versions in `status='planning'` and ask which.
+2. **Pull what's already queued for that version:**
+   - `GET /api/gds/tasks?version=<id>` — every task already bound to the version
+   - `GET /api/gds/inbox` (filter `suggested_version=<id>` or `status=open` if no suggested-version filter is supported by the route)
+   - `GET /api/gds/versions/<id>/done-when` — any criteria already seeded
+3. **Surface the signal back to the user** as a compact summary:
+   - N tasks already queued, grouped by kind
+   - M open ideas tagged for this version
+   - Existing `done_when` text (often a placeholder)
+   - The carry-forward limits from the previous version's `limitations/<prev>-shipped.md`
+
+This is where the user sees what they're shaping. Do not skip this — criteria written without it are guesswork.
+
+4. **Rescope — carry achieved goals forward (ADR 0086 §6 / BV1.R64).** If this version succeeds a prior one, pull the prior version's **achieved** goals and decide, per goal, "previous or new":
+
+   ```
+   node scripts/gds/api.js GET "/api/gds/goals?version=<prev>&status=achieved"
+   ```
+
+   - **Carry forward** — the goal's objective continues into this version. Create the successor goal in Phase 5 with `succeeds_goal_id` pointing at the prior goal (`POST /goals` stamps the predecessor's `succeeded_by_goal_id`), then **archive the prior goal** (`POST /goals/:id/archive`). The lineage stays queryable.
+   - **Replace / retire** — the objective is done or superseded. Leave the prior goal achieved (or archive it) and define fresh goals in Phase 2.5.
+
+   Surface the list to the user and get a per-goal carry/replace decision before writing criteria — the carry-forward goals shape this version's goal set.
+
+### Phase 2 — Criteria
+
+Criteria are the version's done-when. Strong criteria are **outcomes** (broad enough to anchor many tasks), not **task lists** (so narrow they only anchor a few). Five to nine criteria is the typical band; ours have been 7-9.
+
+For each criterion:
+
+- One bold lead sentence stating the outcome
+- A short "why" — what changes when this is true
+- 4-7 sub-outcomes that make the criterion testable
+
+**Apply the strength test BEFORE presenting each criterion.** A criterion passes the test if it plausibly anchors at least 5 tasks across multiple `kind` values (feature + bug + infra, not just feature). If it only anchors 1-3 specific tasks, or reads like an implementation step, rewrite it as the resulting outcome before showing it to the user.
+
+**Number every criterion** (`1.`, `2.`, …) in the presented list. The user will reference them by number when editing — e.g. "edit 4, remove 5, add a new one about X" — so they don't have to copy/paste the criterion titles.
+
+**Ask "what's missing?" before finalizing.** Once you've presented N criteria and worked through edits, explicitly prompt: "What concerns you that I haven't named? What's missing from this list?"
+
+Once criteria are agreed:
+
+- Number them in final order
+- Confirm each one with the user
+- Get explicit sign-off before moving to brainstorming.
+
+### Phase 2.5 — Goals (the module-scoped workspaces) — ADR 0086
+
+A **goal** is the tier between version and criteria: a shared, joinable, **module-scoped** workspace that several builders work inside (ADR 0086). A version is "done" when all its goals are achieved. Defining goals is now part of planning — it's how the version's criteria get grouped into workspaces with a **scope wall** that bounds what each goal's members may author.
+
+For the version being planned, **group the agreed criteria into goals**. For each goal decide, with the user:
+
+- **Title** — the outcome the goal owns (often 1–3 criteria's worth).
+- **`scope_modules`** — the module **keys** (NOT file paths) whose files this goal's members may touch. **This is the wall, and it is set here and only here — never self-granted.** Keep it tight: the modules the goal's work actually needs. Widening later goes through an explicit request a trusted rank approves (`POST /goals/:id/scope`; Archon for a `protected` module) — BV1.R64.
+  > **The valid key list is the source of truth in [`src/bongos/module-scope-map.js`](../../../src/bongos/module-scope-map.js) — read it, don't trust this list.** It exports `moduleKeys()` (all keys), `protectedModules()` / `isProtectedModule(key)` (which are PROTECTED), and `scopeForModule(key)` (a key's globs + `protected` flag). Each key maps to path-globs; `protected` is **derived** (the key's globs overlap the trust/ship-pipeline/migration/authz core), and a goal scoped to any protected key is **Archon-only** to create. The current roster (run `node -e "const m=require('./src/bongos/module-scope-map');console.log(m.moduleKeys().map(k=>k+(m.isProtectedModule(k)?' 🔒':'')).join('\n'))"` to print it live):
+  >   - `kernel` 🔒 · `lifecycle` 🔒 · `economy` · `grading` 🔒 · `memory` · `onboarding` 🔒 · `ideas` · `builder-settings` 🔒 · `sessions` · `autonomy` 🔒 · `security` · `hall-ui` · `status-ui` · `game` · `art-pipeline` · `discord` · `dev-box` 🔒
+  >   - 🔒 = **protected** (Archon-only goal creation + Archon-mediated join). The list above is a convenience snapshot of a *derived* result — if it disagrees with `module-scope-map.js`, the file wins; re-run the one-liner.
+- **No covering key? → file a module-map prep task FIRST.** Every `scope_modules` entry must be a real key from `moduleKeys()`. If a goal's planned work touches file paths that **no existing key covers** (e.g. a brand-new module dir, or code still fused under `src/bongos/` that isn't yet broken out as its own key), the scope wall cannot place that work. Do **not** invent a key. Instead, **add a prep task to this version** — `kind='refactor'`, scoped to `kernel` (the module that owns `module-scope-map.js`) — to extend `MODULE_GLOBS` so a key covers those paths, and make the dependent goal's tasks depend on it. Adding/editing a key is itself a `kernel`-scoped (Archon-gated) change, so flag it for Archon sign-off in this session.
+- **Join policy** — a normal-scope goal is **open-join** (any builder); a goal whose scope includes a **`protected`** module is **Archon-mediated** (a non-Archon can't self-join; an Archon admits Metic+ members). Creating a protected-scope goal is itself **Archon-only** — so flag those for Archon sign-off in this session.
+- **Optional seed tasks / lead** — any obvious first tasks, and who leads.
+
+Present the goals as a short table (title · scope_modules · join policy · the criteria under it). Confirm the grouping and the scope of each before Phase 3 — the brainstorm then runs **per goal → per criterion**, and each net-new task is scoped to one goal.
+
+> **Rescope is "previous or new" at the goal tier too.** If this version succeeds a prior one, you already decided in Phase 1 which prior goals carry forward — those become this version's goals (linked via `succeeded_by_goal_id`); the rest are net-new here.
+
+### Phase 3 — Brainstorm
+
+For each criterion, list every task that could serve it. Be thorough — the user will narrow. Include:
+
+- Existing tasks already queued for the version (you have them from Phase 1)
+- Open ideas tagged for the version that should be pulled in
+- Net-new tasks the criterion implies but nobody has filed yet
+
+Don't tunnel-vision. Surface lateral options the user might not have thought of:
+
+- Cross-cutting tasks (renames, audits, sweeps)
+- **Needs-exploration tasks** for criteria where the design isn't obvious yet (these become `kind='spike'` in the DB, but use the phrase "needs exploration" in conversation — clearer than "spike" for the user)
+- Smoke tests / "this proves the criterion is met" tasks
+- End-of-version lockdown tasks (e.g., rank-gating skills that were available to all during the version)
+
+**Proactively propose needs-exploration tasks** for any criterion where the implementation path isn't clear. Don't wait for the user to flag it. Frame them as "this one needs an architecture pass first — output an ADR + sub-task list before we build."
+
+**For each criterion, explicitly propose a proof-task** — the single live demonstration that proves the criterion is met. Examples: "Builder #2 onboards in ≤2h" for an onboarding criterion, "five concurrent builders shipping without collisions on staging" for a parallel-safety criterion. Without a proof-task, the criterion may technically ship without anyone knowing it works.
+
+**Encourage short task descriptions with cross-refs.** Each task's description should focus on done-when + touches; reference dependency tasks by their R## rather than restating context. Long standalone descriptions are content-debt at scale (80 tasks × 200 words = a lot of redundant context).
+
+> **`touches[]` is an advisory hint, not a hard fence ([ADR 0049](../../../docs/adr/<redacted>.md)).** Parallel-safety is a *split contract*: for interactive single-human work, `git merge` is the authoritative collision detector and the claim-time overlap signal only warns; only the autonomous `--parallel` runner treats footprint overlap as a hard gate. So don't agonize over predicting every file at planning time — a rough blast-radius is enough, and a wrong prediction is no longer ship-blocking. (Step 7/8 — task [#882](https://example.com/builders#/task/882) — makes the per-task `touches` field optional and backfills it from the committed diff at ship.)
+
+Present the brainstorm **grouped by criterion, with every task numbered** (R## prefix or local numbering). Tags: `[E]` existing, `[I]` idea to pull, `[N]` net-new. Note totals per criterion and flag scope-tension points.
+
+Ask the user to **edit (e), remove (r), or add (a) tasks BY NUMBER** per criterion. Format the prompt to make this explicit: "Reply per criterion with e/r/a + the task number — e.g. 'C1: e R03, r R07, a [task description]'".
+
+### Phase 4 — Rank + dependencies
+
+Once the task list is approved, rank everything AND wire dependencies.
+
+**The system has two ordering signals — use both:**
+
+1. **`dependencies[]`** (hard) — task A depends on task B if A cannot start until B has shipped. The auto-promotion trigger and claim-time check enforce this: a backlog task with all deps shipped (and `kind != 'spike'`) auto-promotes to `ready`; a claim attempt is refused if any dep is unshipped. Deps are the *meaning* of execution order.
+2. **`V##.R##` rank prefix** (soft) — fine-grained ordering *within* the dependency-allowed set. Used as the tiebreaker for queue display. Topologically renumber so that for any A → deps → B, B's R## < A's R##.
+
+**Spike tasks live in backlog by default.** The auto-promotion trigger skips `kind='spike'` — humans open spikes manually because spikes produce new tasks downstream and need a power-user decision before claim. Non-spike tasks auto-flow.
+
+**Sanity-check schema constraints before designing the encoding.** This runs
+against the Postgres on the Linux droplet over SSH — it's an Archon ops step, not
+a builder-local one (so the bash/`ssh`/`psql` here is server-side by design, not
+a Windows concern):
+
+```bash
+ssh lars@REDACTED_IP "psql -d example -c '\\d tasks' | grep -i check"
+```
+
+Confirm what the `priority` column actually allows.
+
+**Encoding (V3 convention):** priority is `1-5` (CHECK constraint). Use priority by tier:
+
+- T1 (must ship first) = P5
+- T2 (immediate follow-on) = P5
+- T3 / T4 (parallel infra) = P4
+- T5 (advanced features) = P3
+- T6 (polish) = P2
+- T7 (end-of-version lockdown) = P1
+
+The fine-grained N-deep rank lives in the title prefix: `V<ver>.R##` zero-padded so alphabetical sort returns ranking order within a priority bucket.
+
+Initial ranking: produce it yourself based on dependencies and what the user has stated as priority (e.g., "onboard builder #2 early"). Present in tiers. Ask the user to reorder, defer, or pull forward.
+
+**Critical-path sequencing notes** to surface: which tasks gate which (architecture spikes gate the rest of their criterion; rename should be first; smoke tests should be last in their tier).
+
+**Capture dependencies during the brainstorm, not after.** For each new task, ask yourself "which already-listed tasks must ship before this one is even claimable?" and write the answer next to the task. By the end of Phase 3 every task should have a `dependencies: [Rxx, Ryy]` field (possibly empty). Then in Phase 4:
+
+1. Build the dep graph from the captured edges.
+2. Run cycle detection — if a cycle exists, surface it and ask the user to break it (usually one side of the cycle is a "pair-with" relationship, not a true dep).
+3. Topologically sort. Tiebreaker: lower current R## first (preserves planning intent), then alphabetical ref.
+4. Re-number `V<ver>.R##` in topo order. The output is your final rank.
+
+This is what the V3.R02 (task 309) dependency system encodes; Phase 5 writes both the title prefix and the `task_dependencies` rows.
+
+### Phase 5 — Land it
+
+Once ranking is agreed, do the writes in this exact order:
+
+1. **Create a meta planning-session task** (`source_ref='<ver>-planning-N'`) that backs all the writes — version='<ver>', kind='decision', status='ready', priority=5, the full session described in its body. Claim it.
+
+2. **Create the version's goals, then write the criteria migration.** Goals come first (ADR 0086) so the criteria can be parented under them:
+   - **Goals** (via API — `POST /goals`; Archon-only when the scope includes a `protected` module). One per goal from Phase 2.5; **capture each returned goal id**.
+     ```
+     node scripts/gds/api.js POST /api/gds/goals --body '{"version_id":"<ver>","title":"...","scope_modules":["<key>", ...]}'
+     # carry-forward goal: add "succeeds_goal_id":<prior_goal_id>
+     ```
+   - **Criteria — the vector depends on whether the instance is LIVE ([ADR 0105](../../../docs/adr/<redacted>.md)):**
+     - **On a RUNNING instance (the normal case — planning a new goal/version on prod):** create each criterion via the **`POST /api/gds/versions/:id/done-when`** API (Archon), passing `criterion_id` (a stable slug), `criterion_md`, `goal_id` (the goal from above), and optional `sort_order`. This is the ONLY vector that actually lands a NEW criterion on a live DB — a `done_when_criteria` INSERT in a CORE migration **fails the `selfhost-boot` gate** (scope-truth pollution), and one in `migrations/instance/` **silently no-ops on a normal deploy** (ADR 0105 applies instance seeds only under the owner opt-in `GDS_APPLY_INSTANCE_SEEDS=1`, a DR step). A duplicate `criterion_id` returns 409 — treat as "already seeded."
+       ```
+       node scripts/gds/api.js POST /api/gds/versions/<ver>/done-when --body '{"criterion_id":"<slug>","criterion_md":"...","goal_id":<gid>}'
+       ```
+     - **For a brand-new version scaffolded from scratch (DR / a fresh instance):** put the `INSERT INTO done_when_criteria` (with `goal_id`, `ON CONFLICT ... DO UPDATE`) in **`migrations/instance/<NN>_<ver_slug>_planning_seed.sql`** — and recreate the goal idempotently in the same file (the goal is a runtime row a replay won't have). Applies only under `GDS_APPLY_INSTANCE_SEEDS=1`.
+   - **Migration** at `migrations/<NN>_<ver_slug>_planning_seed.sql` (CORE — platform-universal, non-scope-truth changes only): `UPDATE versions SET done_when = ...` and `UPDATE tasks` for existing-task priority + V##.R## title prefix (guarded by `WHERE title NOT LIKE 'V<ver>.R%'`). **Do NOT put versions/goals/`done_when_criteria` INSERTs here** — that's scope-truth and fails the `selfhost-boot` gate (ADR 0105).
+
+3. **Write a seed script** at `scripts/gds/seed-<ver_slug>-tasks.js` modeled on `scripts/gds/seed-v3-tasks.js` containing:
+   - The TASKS array — one entry per net-new task with full description, kind, discipline, priority, est_minutes, manual_degree, credits_reward, **optional** `touches` (see below), optional `promoted_idea_id`, `depends_on_refs: ['R##', ...]` (the dep edges captured during brainstorm), AND **`criterion_ids: ['Cn', ...]`** — the done-when criterion(s) this task gates. The brainstorm in Phase 3 is already grouped by criterion, so this is just transcribing that grouping. Use the positional `"Cn"` token (C1 = the version's first criterion); the server resolves it against the task's version at create (ADR 0025 / task 438). **This replaces the old `**Criterion:** Cn` prose** — don't write that line anymore; pass `criterion_ids` instead so the task is linked in `task_criteria` at creation and `/status` counts it with no backfill.
+   - **`touches` is now OPTIONAL (task 882 / [ADR 0049](../../../docs/adr/<redacted>.md)).** Omit it (or leave it blank) unless you already know a tight file set and want the advisory overlap signal during the brainstorm. At first `/builder-ship` the server backfills `touches[]` from the real committed diff — the declared set becomes what git actually reported. Don't burn planning effort predicting file lists; a rough or absent prediction is fine and no longer ship-blocking.
+   - **`requires_rank` AUTO-DERIVES — you don't hand-set it per task (task [#1498](https://example.com/builders#/task/1498) / [ADR 0084](../../../docs/adr/<redacted>.md)).** On create the server floors a task at `metic` when it is `security_sensitive` or its `touches` reach the permission / authz / ship-grade / deploy / migration core (the same protected paths a sub-Metic builder can't push to); everything else stays the open `xenos` default. To deliberately gate a task **higher** than the auto-floor (e.g. owner-only work), pass `requires_rank: 'metic' | 'archon'` on the task — it can only RAISE the floor, never drop below it.
+   - **Pass `goal_id: <gid>` on each task** so it lands under its goal (not the version's default catch-all). `POST /tasks` now honors `goal_id` (validated to belong to the version); to move an already-created task, `PATCH /tasks/:id` with `{goal_id}` (task 1763). `criterion_ids` accepts a **slug** (the `criterion_id` you set above), a `"Cn"` position, or a numeric id — the slug is position-independent and cleanest.
+   - A main() that POSTs each task **with its `criterion_ids`** (idempotent on `source_ref`; the criterion links are inserted at create, idempotent on `(task_id, criterion_id)`), PATCHes `idea_inbox` for promotions, and after all tasks exist, POSTs `task_dependencies` via `POST /tasks/:id/dependencies` (resolving each R## to the just-created task ID). Idempotent on `(task_id, depends_on_task_id)`. (Need to re-attribute an already-seeded task? `POST /tasks/:id/criteria` with `{criterion_ids:['Cn',...]}`; `DELETE /tasks/:id/criteria/:criterionId` to detach — both Metic+ ([ADR 0090](../../../docs/adr/<redacted>.md)), mirroring the dependency endpoints.)
+
+4. **Apply the migration** (commit + push + deploy, or direct psql via SSH for hot-fix style).
+
+5. **Run the seed script.** Verify exit code 0; verify totals via `GET /api/gds/public/progress` and `GET /api/gds/versions/<ver>/done-when`.
+
+6. **Promote the zero-dep layer to `ready`.** Every newly-seeded task lands `status='backlog'`. The auto-promotion trigger only fires when a *dependency* ships — so a task with zero deps has nothing to wait for and would sit unclaimable forever. Run, in the same psql session as the migration (or via SSH to the droplet):
+
+   ```sql
+   UPDATE tasks
+   SET status = 'ready', promoted_at = now()
+   WHERE version_id = '<ver>'
+     AND status = 'backlog'
+     AND kind <> 'spike'
+     AND id NOT IN (SELECT task_id FROM task_dependencies)
+   RETURNING id, title, priority, kind;
+   ```
+
+   Capture the `RETURNING` rows — the max `priority` value is the input for step 7. Spikes are intentionally excluded; they never auto-promote (kind='spike' convention, [ADR 0015](../../../docs/adr/<redacted>.md)).
+
+7. **Surface higher-priority spikes still in backlog.** Spikes don't auto-flow because their output reshapes downstream work — that's a feature, not a bug. But the planning session just decided the priority order, so a high-priority spike sitting unstarted while lower-priority non-spike work flows to `ready` is a coordination smell worth one explicit mention. Query:
+
+   ```sql
+   SELECT id, title, priority
+   FROM tasks
+   WHERE version_id = '<ver>'
+     AND status = 'backlog'
+     AND kind = 'spike'
+     AND priority >= <max_priority_from_step_6>
+   ORDER BY priority DESC, title;
+   ```
+
+   The bar is **relative** — `>= max(priority of the rows promoted in step 6)`. If lower-priority non-spike work was promoted, only equal-or-higher-priority spikes surface; lower-priority spikes are noise at planning-land time and stay silent.
+
+   If the query returns rows, surface them to the user verbatim:
+
+   > "Heads up — these spikes sit at priority ≥ the top of your ready queue. They don't auto-promote (kind='spike', [ADR 0015](../../../docs/adr/<redacted>.md)). If any gates downstream work, open it manually: `POST /api/gds/tasks/<id>/promote`"
+
+   If the query returns nothing, stay silent. Don't volunteer info about lower-priority spikes — the next planning session or `/idea-triage` walk will handle those at the right moment.
+
+8. **Commit + push** the migration + seed script + any new skill files + the session-log entry.
+
+9. **Ship the meta task** via `/builder-ship` with a clean value-summary.
+
+## How to use — quick reference
+
+All API calls go through the cross-platform `node scripts/gds/api.js` helper —
+it signs each request with your session token (no manual token extraction) and
+runs on Windows/macOS/Linux.
+
+```
+# Phase 1 — pull state
+node scripts/gds/api.js GET /api/gds/public/versions
+node scripts/gds/api.js GET "/api/gds/tasks?version=<id>"
+node scripts/gds/api.js GET /api/gds/inbox
+node scripts/gds/api.js GET /api/gds/versions/<id>/done-when
+```
+
+Phase 5 writes use the same `POST /tasks`, `PATCH /inbox/:id` shape as `idea-triage` and `seed-v3-tasks.js`. Mirror those patterns rather than inventing new ones.
+
+## Tone for the user
+
+Lars is the prompter (see CLAUDE.md §2). Frame criteria and tasks in terms of outcomes and player/builder experience, not implementation. When asking him questions, ask about *what changes when this is true*, not *how would we build it*. Decide implementation details yourself and present them for confirmation.
+
+When the user pushes back ("criteria 4/5/6 are weak"), take it seriously and rewrite. Strong outcome criteria are the hard part — the rest of the session is downstream of them.
+
+When the user says "I am ready to rank" or "produce the initial ranking," do it in one shot. Don't bounce back with more clarification questions unless something genuinely ambiguous needs resolving.
+
+## After the session — improvements pass
+
+At the end of every planning session, ask the user the retrospective question:
+
+> "Anything we should do differently in the next planning session? My own observations from this one:"
+
+Then offer 2-4 concrete recommendations based on how the session actually went (e.g. weak criteria caught late, ranking done by chat vs artifact, a schema constraint hit at first write). File them as `idea_inbox` rows tagged `kind='skill-friction'` so the skill improves over time.

package/.claude/skills/priority-session/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: priority-session
+description: Run a structured priority session — a trusted builder answers a handful of plain-speech questions, and the answers reweight the GDS idea_inbox and suggest what to claim next. Triggers when the user says "/priority-session", "run a priority session", "what should I work on next", "reprioritize the inbox", "what feels most important right now", or "help me decide what to claim". Metic+ rank only (Metic and Archon; not Xenos).
+---
+
+You are running a **priority session** for the Game Development System (GDS). Where a **planning session** sets a *version's* scope (criteria + a fresh ranked task list), a priority session works the *present tense*: it takes the open `idea_inbox` exactly as it stands and reweights it against how the builder actually feels about the work right now — what's stuck, what would unblock the most people, what they're excited to build. The session ends with a **weighted ranking of the open ideas** and a single **"what should I claim next?"** suggestion, and it writes a durable session-log entry so the reweighting is on the audit trail.
+
+This is the live-flight complement to `/planning-session`: planning sessions set a version's scope; priority sessions reweight the present queue when the builder isn't sure where to point their energy.
+
+## Rank gate — Metic+ only
+
+**Gated to Metic+ (Metic, Archon); not Xenos.** Reweighting the whole team's inbox is a trusted-builder operation (GDS-V3 criterion C2, `three-ranks-gate-everything`).
+
+**Enforce the gate at the very top of the session, before reading anything else:**
+
+1. Call `GET /api/gds/me` and read `builder.rank`. Compare case-insensitively (lowercase it before testing) — the `builders.rank` enum casing is defined by V3.R04; until it ships, normalize defensively.
+2. **If `rank` is present and lowercases to `xenos`** → stop immediately. Tell the builder: *"Priority sessions are a Metic+ operation — they reweight the whole team's idea queue. You're currently Xenos. Ask an Archon to promote you, then run this again."* Do not read the inbox, do not propose a ranking.
+3. **If `rank` lowercases to `metic` or `archon`** → proceed.
+4. **If `rank` is absent** (the server-enforced rank system — V3.R04 / criterion C7 — has not shipped yet, so `/me` returns no `rank` field): treat the session as available, exactly as `/planning-session` does today ("available to all builders for now; rank-gates to Metic+ at end of V3"). Note in the session-log entry that the gate ran in pre-rank passthrough mode. The moment `builders.rank` lands, this skill enforces it for real with no edit — the check above already reads the field.
+
+> The gate is the *intent* surfaced to the operator; the server is the *enforcement* — markdown never grants authority (criterion C7).
+
+## When to invoke
+
+- The builder asks "what should I work on next?" and the claimable list is long enough that rank-by-priority alone isn't a clear answer.
+- The open `idea_inbox` has grown and the team's sense of what matters has drifted from the priorities filed weeks ago.
+- A builder is starting a work block and wants to point their energy at the thing that's both high-leverage *and* something they're motivated to do.
+
+## When NOT to invoke
+
+- **To set a version's scope** — that's `/planning-session`. Priority sessions never write criteria or create the version's task spine.
+- **To verdict the inbox** (promote / discard / merge each idea) — that's `/idea-triage`. A priority session *ranks* open ideas; it doesn't close them. The two are complementary: triage keeps the inbox clean, priority sessions tell you which clean idea to grab first.
+- **For a Xenos** — see the rank gate above.
+- **When the inbox is empty** — there's nothing to reweight. Fall back to `/builder-start` to surface claimable tasks and pick by standard priority.
+
+## The session — four phases
+
+### Phase 1 — Pull the present state
+
+Read everything the reweighting depends on. Do this before asking the builder anything, so their answers land against real data, not guesses.
+
+1. `GET /api/gds/me` — rank gate (above) **and** the builder's `active_claims` (don't suggest claiming something they already hold) and `total_credits`.
+2. `GET /api/gds/inbox` — the open ideas. This is the set you will rank. Capture each idea's `id`, `title`, `body_md`, `kind`, `suggested_version`, `suggested_priority`, `captured_at`, `captured_by`.
+3. `GET /api/gds/tasks/claimable` — what's *actually claimable right now* (deps shipped, parallel-safe). The "what should I claim next?" answer must come from this list, never from an idea that hasn't been promoted to a task yet.
+4. `GET /api/gds/blockers` (read-public, no auth) — open blockers. An idea that would resolve or route around a current blocker scores higher on the "unblock the most builders" axis.
+
+If `open_count` is 0, print *"inbox empty — nothing to reprioritize. Running `/builder-start` instead to surface claimable tasks."* and stop the priority flow.
+
+**Surface a compact summary back** before the questions: N open ideas (grouped by kind), M claimable tasks, K open blockers, the builder's current claims. This is the canvas they're about to reweight.
+
+### Phase 2 — The plain-speech questions
+
+Ask the builder a short set of **5–7 plain-language questions**, one at a time or as a single block (let them answer however they like). These are *feelings about the work*, not implementation questions — Lars is the prompter (CLAUDE.md §2): frame around outcomes and motivation, never around design patterns. Keep each question to one sentence.
+
+Ask these (you may lightly reword for tone, but keep the intent):
+
+1. **What feels stuck?** — Which area of the project keeps not moving, or keeps coming up and getting deferred?
+2. **What would unblock the most builders?** — If you fixed one thing, what would free up the most other work for the whole team?
+3. **What excites you right now?** — What would you actually *enjoy* building this block? (Motivation is a real multiplier — a builder ships faster on work they want to do.)
+4. **What's the most expensive thing to keep ignoring?** — What's quietly accruing cost, risk, or debt the longer we leave it?
+5. **What would a player or a watching builder notice this week?** — What's the highest-visibility win available right now?
+6. **What's risky if we get it wrong later?** — Is there a decision or foundation that's cheap to set right now and painful to unwind once built on?
+7. **How much time and energy do you have this block?** — Quick wins, or room to sink into something deep? (This shapes the *claim* suggestion, not the ranking.)
+
+You don't have to ask all seven if the builder's first answers already cover the field — but ask at least five, and always ask #1, #2, #3, and #7 (those four directly feed the weights below and the claim suggestion). Capture the answers verbatim; you'll cite them in the session log.
+
+### Phase 3 — Weight and rank
+
+Turn the answers into a transparent score per open idea, then present the ranking.
+
+**Scoring model.** Score each open idea 0–5 on each of four axes, then blend. The axes map directly onto the questions so the builder can see *why* an idea moved:
+
+| Axis | Fed by | What earns a high score |
+|---|---|---|
+| **Stuck / momentum** | Q1 | The idea targets an area the builder named as stuck or repeatedly deferred. |
+| **Leverage / unblocks** | Q2, blockers list | The idea unblocks other tasks or resolves/routes around an open blocker. Cross-check `blockers` and any task `dependencies[]` the idea would clear. |
+| **Excitement / motivation** | Q3 | The idea is in or near the area the builder said excites them. |
+| **Cost-of-delay / risk** | Q4, Q6 | The idea targets accruing cost, risk, or a cheap-now/expensive-later decision. |
+
+`score = 1.0·stuck + 1.2·leverage + 0.8·excitement + 1.0·cost_of_delay`
+
+Leverage is weighted highest because unblocking the team is the strongest team-level signal; excitement is weighted slightly lower because it's a personal multiplier, not a team priority — but it stays in the blend deliberately, since a motivated builder ships. Start from each idea's existing `suggested_priority` as a faint prior (break ties with it), but let the answers dominate — the whole point of the session is that today's felt priorities override stale filed ones.
+
+**Present the ranking** as a numbered list, highest score first. For each idea show: rank, `#id`, title, the blended score, the per-axis breakdown (e.g. `stuck 4 · leverage 5 · excite 2 · cost 3`), and a one-line *why it ranked here* that quotes the relevant answer. Numbering lets the builder reorder by number — *"bump 3 above 1, drop 5"* — the same edit-by-number convention `/planning-session` and `/idea-triage` use.
+
+**Let the builder adjust.** Ask: *"Anything mis-ranked? Reorder, or tell me an axis I read wrong."* Re-blend if they push back — their override wins. This is a human session; the model is a starting point, not a verdict.
+
+**Persisting the reweighting — not yet wired.** A priority session's ranking lives in the **session-log entry** (Phase 4), not in a mutated inbox. The `idea_inbox` `PATCH` route (`src/bongos/routes/inbox.js` / `inbox.updateIdea()`) currently only accepts `status`, `kind`, `promoted_to_task_id`, and `reviewed_at` — it does **not** accept `suggested_priority`, so a `PATCH` trying to bump it would return 200 but change nothing (a silent no-op). Do **not** attempt it. If the builder wants the new order to durably stick in the inbox, that's a follow-up: file an `idea_inbox` row (`kind='skill-friction'`) asking to add `suggested_priority` to the inbox PATCH allowlist so a future priority session can persist its ranking. Until that ships, the log entry is the canonical record of the reweight.
+
+### Phase 4 — "What should I claim next?" + land the log
+
+**Make the claim suggestion.** This is the single most useful output. Cross the ranking against `GET /api/gds/tasks/claimable` and the builder's Q7 (time/energy):
+
+- The top-ranked idea is only a valid claim suggestion **if it's already a claimable task**. An open idea is *not* claimable — it's an idea. If the top idea hasn't been promoted to a task yet, say so and offer: *"This isn't a task yet — want me to promote it via `/idea-triage`, or claim the highest-ranked thing that's already a task?"*
+- Filter claimable tasks by the ranking's themes and by Q7: if the builder said "quick win," prefer low `est_minutes`; if "deep block," prefer the high-leverage foundational work even if it's bigger.
+- Never suggest something in the builder's `active_claims`.
+- Present **one** primary suggestion with a one-line rationale tying it to their answers, plus 1–2 runners-up. End with the exact command: `node scripts/gds/claim.js <id> --worktree <name>` (or `/builder-claim <id>`).
+
+**Write the session-log entry.** A priority session is a real decision on the audit trail — record it. Write `docs/session-logs/YYYY-MM-DD-priority-session.md` (append a numeric suffix if one already exists today) containing:
+
+- Date, builder (`github_login` + rank, or "pre-rank passthrough"), credits at session start.
+- The 5–7 questions asked and the builder's answers verbatim.
+- The full weighted ranking with per-axis scores.
+- Any `suggested_priority` writes made (idea id → new value).
+- The claim suggestion and whether the builder took it.
+
+Prepend a one-line link to the CLAUDE.md §13 Session Log index (newest at top), matching the format of the existing entries. Per-entry prose stays in the dated file, not in CLAUDE.md — same discipline as every other session.
+
+## How to use — quick reference
+
+```bash
+# Auth: cli-lib.js resolves the session token (new path gds-session.json,
+# legacy fallback pms-session.json) and signs every request. Prefer driving the
+# API through it rather than re-deriving the token inline.
+node -e "const {apiCall}=require('./scripts/gds/cli-lib.js'); \
+  apiCall('GET','/api/gds/me').then(r=>console.log(JSON.stringify(r.data,null,2)))"
+
+# Phase 1 — pull state
+node -e "const {apiCall}=require('./scripts/gds/cli-lib.js'); \
+  apiCall('GET','/api/gds/inbox').then(r=>console.log(JSON.stringify(r.data,null,2)))"
+node -e "const {apiCall}=require('./scripts/gds/cli-lib.js'); \
+  apiCall('GET','/api/gds/tasks/claimable').then(r=>console.log(JSON.stringify(r.data,null,2)))"
+node -e "const {apiCall}=require('./scripts/gds/cli-lib.js'); \
+  apiCall('GET','/api/gds/blockers').then(r=>console.log(JSON.stringify(r.data,null,2)))"   # read-public
+
+# Phase 4 — the suggestion resolves to a real claim command
+node scripts/gds/claim.js <task_id> --worktree <worktree-name>
+```
+
+The read shapes (`/inbox` → `{ ideas, open_count }`, `/me` → `{ builder, active_claims }`) are the same ones `/idea-triage` and `/planning-session` use. Mirror those read patterns rather than inventing new ones. There is no priority-session write to the inbox today — see "Persisting the reweighting — not yet wired" above.
+
+## Tone for the user
+
+Lars is the prompter (CLAUDE.md §2 — EE background, not a software engineer). The questions are deliberately plain-speech: ask about feelings, outcomes, and what he'd actually enjoy, never about implementation. Decide the scoring and the claim mechanics yourself; present the ranking and the one suggestion for confirmation. When he overrides a rank, take it — the session exists to capture *his* present-tense priorities, and the model is just scaffolding for that conversation.

package/.claude/skills/read-session-export/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: read-session-export
+description: Read a Claude Code `/export` zip quickly and consistently — the conversation, the assistant's thinking ("the thoughts"), and what the tools did — so you can answer questions about a past session. Triggers when the user drops a `session-export-*.zip` (or names one) and says "read this session", "what happened in this session", "what was I/you thinking here", "summarize this export", "read the latest session export", or "/read-session-export". This READS the existing export — it does not create a new one. Local + read-only, no GDS auth, no network.
+---
+
+The user already has the zip — Claude Code's built-in `/export` made it. Your job is to **read it well**: a session export is the same shape every time, so don't go spelunking through it by hand or load the megabytes of debug logs. Run the reader, which prints a compact transcript (prompts + thinking + replies + one-line tool calls) to stdout, then answer whatever the user actually asked.
+
+```bash
+node scripts/gds/read-session-export.js <export.zip>     # read it (compact transcript → stdout)
+node scripts/gds/read-session-export.js --latest         # newest session-export-*.zip in ~/Downloads
+```
+
+Then **read that output and respond to the user's real intent** — summarize the session, pull out the reasoning behind a decision, find where something went wrong, list what was built. Don't just paste the transcript back; that's the raw material, not the answer.
+
+## Pick the right depth (it's fast either way)
+
+| The ask | Run |
+|---|---|
+| "What is this / how long / what model" | `--meta` (header only: model, dates, counts) |
+| "What was I/you *thinking*" | `--thoughts` (only the 💭 thinking blocks) |
+| Normal "read / summarize this session" | _(no flag)_ — compact transcript, tool results clipped |
+| "I need the full tool output / exact text" | `--full` (loosens the result clipping) |
+
+For a long session (a `--meta` showing hundreds of tool calls / thousands of lines), start with `--meta`, then `--thoughts` or a targeted read — don't dump the whole thing into context if the user only wants the gist.
+
+## What you're reading (the constant layout)
+
+A `/export` zip is identical every time, which is why this is reliable:
+
+- `metadata.json` — model, effort, title, cwd, branch, timestamps.
+- `<cliSessionId>.jsonl` — **the transcript**, one JSON record per line. Assistant records carry `content[]` blocks of type `thinking` (the thoughts), `text` (the reply), and `tool_use`; the matching `tool_result` rides in the next `user` record. The reader stitches these together.
+- `<cliSessionId>/subagents/agent-*.jsonl` — subagent transcripts (rendered after the main one).
+- `<cliSessionId>/tool-results/*.txt` — outputs too big to inline.
+- `logs/*.log` — app debug logs. **Not the conversation** — ignored.
+
+You rarely need this — the reader handles it — but it's here so you can read a record by hand if you must.
+
+## The thinking may be redacted — and what to show instead
+
+Whether "the thoughts" are actually readable depends on the model that ran the session, not on this tool:
+
+- **Sonnet sessions** → thinking exports as plaintext; you'll see the real reasoning.
+- **Opus sessions** (e.g. `claude-opus-4-8`) → thinking is **redacted**: the export carries only an encrypted signature, not the words. The reader states this once in the header (`💭 0 thoughts (+N redacted)` + a one-line banner) and otherwise keeps the body clean.
+
+**The substitute for redacted thinking is already in the transcript — not in the logs.** When the thoughts are encrypted, lean on what Claude actually *said and did*: the **text replies** routinely state the reasoning in plain language ("the problem is X, so I'll Y"), and the **tool-call sequence** shows the investigation step by step. The reader surfaces both, so you can reconstruct the "why" of a redacted session from its actions. (The zip's `logs/*.log` are NOT a fallback: they're app-wide, multi-day rolling logs with no per-session correlation and no reasoning — ignore them.)
+
+So if the user exported an Opus session hoping to re-read the literal reasoning, tell them plainly it's redacted — then answer their question anyway from the text + actions, which usually makes the reasoning clear.
+
+## Constraints
+
+- **Reads, never writes.** Output goes to stdout for you to consume; it creates no files and never modifies the zip.
+- **Local + zero-dependency.** Pure Node stdlib (a small `zlib` ZIP reader) — no GDS session, no network, no install. Works on any builder machine.
+- ZIP64 archives (multi-GB) are refused with a clear message; no real session export hits that.
+
+## Files this skill touches
+
+- Runs: `node scripts/gds/read-session-export.js` (the whole implementation).
+- Reads: the `session-export-*.zip` you point it at. Writes: nothing.

package/.claude/skills/recall/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: recall
+description: One-call project-knowledge search across the repo docs + DB prose (tasks, learnings, session logs). Triggers when the user says "/recall", "recall …", "what do we know about X", "have we done X before", "did a past session hit X", "search the docs/ADRs for X", "is there an ADR about X", or before re-solving something that smells already-solved. Read-only; rank-scoped server-side. Run it instead of grepping the tree or asking the user to remember.
+---
+
+You are answering "what do we already know about X?" — the GDS-V4 one-call-recall capability ([ADR 0060](../../../docs/adr/0060-gds-retrieval-layer.md)). Before this existed, recall meant grepping the repo + eyeballing session logs + hoping you remembered the right ADR. Now one call searches the indexed corpus (every repo markdown + nightly-indexed DB prose: task descriptions, learnings, session-log summaries, recent shipped-task summaries) with full-text + typo-tolerant fuzzy matching fused by RRF, and returns the most relevant sections with their breadcrumb (file > heading > subheading).
+
+## Two-step flow: summary first, then expand (progressive disclosure)
+
+Recall uses **progressive disclosure with token-cost visibility** ([ADR 0095](../../../docs/adr/<redacted>.md) C1). You don't pay for the full corpus in one shot:
+
+1. **Step 1 — the summary layer.** `recall <query>` returns a *ranked, compact* list: each hit is a title, breadcrumb, snippet, and a **token-cost label** — `~N tok` is what a full read of that hit would cost, and a `~N tokens to expand all` headline totals the whole result set. You see what a deeper read will COST before you pay for it.
+2. **Step 2 — expand the one you want.** `recall --expand <id>` fetches just that hit's full content (the id is the `#NNN` printed at the head of each result line). Spend tokens only on the hit that actually answers the question — typically one, not all ten.
+
+So the loop is: search → read the cheap summaries + costs → expand the single best hit (or open its `source_ref` directly). A `→ recall --expand <id>` hint prints under any hit whose snippet is only a preview of a larger section.
+
+## When to reach for it (liberally)
+
+- The user asks about a past decision, a footgun, an ADR, "how does X work", or "have we done X."
+- You're about to design or build something that might already be solved — search first (the "romantic-gauss redundant-work" case: a parallel/past session may have already fixed it).
+- You need the canonical doc for a topic and don't know its exact path.
+
+## How to use
+
+```bash
+node scripts/gds/recall.js <query…>            # STEP 1: ranked summary + per-hit token cost; query is the rest of the line, quotes optional
+node scripts/gds/recall.js trust boundary
+node scripts/gds/recall.js "grader bypass" --limit 5
+node scripts/gds/recall.js nightly backup --kind doc     # restrict to docs (vs --kind db for DB prose)
+node scripts/gds/recall.js --expand 1234       # STEP 2: full content of hit #1234
+node scripts/gds/recall.js <query…> --json     # raw JSON for further processing
+```
+
+Each summary result shows the hit id (`#NNN`, the handle for `--expand`), the title, the breadcrumb (`file > H1 > H2`), the source ref, a relevance score, which legs matched (`fts+trgm`), a snippet, and the **token cost** to expand it. Either `recall --expand <id>` for the full section in-band, or open the cited `source_ref` directly.
+
+## What to do with results
+
+- **Read the summary layer first; expand sparingly.** The whole point of step 1 is to spend almost no tokens deciding *which* hit is worth a full read. Look at the snippets + costs, then `--expand` (or open `source_ref` for) the one or two that actually answer the question — don't expand all of them.
+- **Relay the relevant ones**, each with its `source_ref` so the user (and you) can open the exact section — don't dump all of them; pick what answers the question.
+- If recall surfaces an existing ADR / task / learning that already covers the work, **say so and link it** rather than re-deriving — that's the whole point.
+- If `No matches`, the topic may be unindexed (a brand-new doc indexes on the next deploy; DB prose indexes nightly). Fall back to a targeted grep / `/status` only then.
+
+## Constraints
+
+- **Read-only + rank-scoped.** Results are filtered server-side to your live rank + your own private chunks ([ADR 0060](../../../docs/adr/0060-gds-retrieval-layer.md) §6 / [ADR 0016](../../../docs/adr/<redacted>.md)) — a sub-Metic session will not see permission-core docs, and you never see another builder's private memory. Don't try to widen scope via flags; there's no such flag.
+- **Authenticated.** Recall searches *as you*, so it needs a builder session (`/builder-setup` once). A 401 means "sign in first."
+- Don't paste the raw JSON at the user unless they ask — summarize + cite.
+
+## Files this skill touches
+
+- Calls: `POST /api/gds/search` via `scripts/gds/recall.js` — twice over the same route: `{ q }` for the summary layer (step 1) and `{ expand: <id> }` for one hit's full content (step 2).
+- Reads: `~/.config/otb/gds-session.json` (the session token, like every `/builder-*` CLI).