@bongos/core 1.17.0

package/migrations/043_builder_onboarding_observability.sql

@@ -0,0 +1,66 @@
+-- V3.R14 (#238) — onboarding observability columns on builders.
+--
+-- Two new timestamps on builders so the Archon can see the funnel
+-- (signed in → shipped first task) without crawling credit_log and
+-- session_logs by hand:
+--
+--   1. onboarded_at — the moment this builder first crossed the gate.
+--      Today that's effectively created_at (first upsert from the
+--      GitHub OAuth callback), but we capture it as a separate column
+--      so we can move the definition later (e.g. "completed the
+--      welcome quest") without rewriting history.
+--
+--   2. first_ship_at — the moment this builder's first task hit
+--      'shipped' (auto-merged + deployed). The gap between
+--      onboarded_at and first_ship_at is the *time-to-first-ship* —
+--      the single most useful onboarding metric we don't yet
+--      surface. Archon roster will render TTFS per builder.
+--
+-- Backfill strategy:
+--   - onboarded_at ← created_at  (the closest proxy we have).
+--   - first_ship_at ← MIN(t.shipped_at) WHERE t.shipped_by = b.id
+--     across shipped tasks. Builders who haven't shipped stay NULL.
+--
+-- The write-side bump (shipTask in src/bongos/db.js) is responsible for
+-- keeping first_ship_at honest going forward via
+-- `UPDATE builders SET first_ship_at = COALESCE(first_ship_at, now())`.
+
+BEGIN;
+
+ALTER TABLE builders
+  ADD COLUMN IF NOT EXISTS onboarded_at  timestamptz,
+  ADD COLUMN IF NOT EXISTS first_ship_at timestamptz;
+
+-- Backfill onboarded_at from created_at. Idempotent — only fills NULLs,
+-- so re-running this migration after a partial run is safe.
+UPDATE builders
+   SET onboarded_at = created_at
+ WHERE onboarded_at IS NULL;
+
+-- Backfill first_ship_at from the earliest shipped task per builder.
+-- tasks.shipped_by is the canonical author key set by shipTask; tasks
+-- that never reached 'shipped' have shipped_at NULL and are excluded.
+UPDATE builders b
+   SET first_ship_at = sub.first_ship_at
+  FROM (
+    SELECT shipped_by AS builder_id, MIN(shipped_at) AS first_ship_at
+      FROM tasks
+     WHERE shipped_by IS NOT NULL
+       AND shipped_at IS NOT NULL
+     GROUP BY shipped_by
+  ) sub
+ WHERE b.id = sub.builder_id
+   AND b.first_ship_at IS NULL;
+
+-- Cheap roster sort: builders with the longest time-to-first-ship rise
+-- to the top of "still onboarding" queries. Index on (first_ship_at) is
+-- sparse (only ships have non-NULL) but the partial-index covering
+-- still-onboarding rows is what the Archon roster will hit most often.
+CREATE INDEX IF NOT EXISTS idx_builders_first_ship_at
+  ON builders (first_ship_at);
+
+CREATE INDEX IF NOT EXISTS idx_builders_still_onboarding
+  ON builders (onboarded_at)
+  WHERE first_ship_at IS NULL;
+
+COMMIT;

package/migrations/044_tasks_requires_rank.sql

@@ -0,0 +1,97 @@
+-- 044_tasks_requires_rank.sql — V3.R82 (#301): per-task minimum rank gate.
+--
+-- Context: V3.R15 (migration 039) added `newcomer_friendly` as the row-level
+-- gate that LETS A XENOS claim a sensitive-by-default task. This migration
+-- adds the INVERSE — a per-task floor that RAISES the minimum required rank
+-- above the default (xenos), so some tasks become Metic-only or Archon-only
+-- because they touch sensitive infra.
+--
+-- The two flags compose without contradiction:
+--   - requires_rank='xenos'        — the default; anyone may claim (subject to
+--                                    the existing xenos sandbox: if the caller
+--                                    IS a xenos, newcomer_friendly must also
+--                                    be true. This preserves the V3.R15 rule).
+--   - requires_rank='metic'        — at least a Metic may claim. Xenos blocked.
+--   - requires_rank='archon'       — only an Archon may claim. Xenos+Metic blocked.
+--
+-- Tier ordering (lowest→highest): xenos < metic < archon. This is the three
+-- LIVE ranks in V3 (ADR 0018); reserved-but-not-live ranks stay out of the
+-- CHECK enum because Lars chose to wire only three for now (#360). When/if
+-- another rank goes live, this CHECK extends in the same migration that wires
+-- the new rank.
+--
+-- View rebuild: claimable_tasks and tasks_session_fit both do SELECT t.*, so
+-- the new column flows through implicitly — but the views must be rebuilt
+-- (DROP+CREATE) because column-list changes require it (same pattern as
+-- migrations 028, 039). View bodies are unchanged.
+--
+-- View-level filter: the per-rank gate is realized in db.js listClaimableTasks
+-- at SELECT time (same pattern as the xenos/newcomer_friendly gate added in
+-- migration 039) — views are builder-agnostic (can't read session context).
+-- Belt-and-braces: db.claimTask + claimTasksBatch re-check at claim time and
+-- throw INSUFFICIENT_RANK (this migration is purely the schema piece; code
+-- changes ship alongside).
+--
+-- Idempotent: safe to re-run.
+
+ALTER TABLE tasks
+  ADD COLUMN IF NOT EXISTS requires_rank text NOT NULL DEFAULT 'xenos';
+
+-- Constrain to the three LIVE ranks. NOT VALID would let bad rows slip in;
+-- the column has a NOT NULL DEFAULT so every existing row is already 'xenos'.
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_constraint
+     WHERE conname = 'tasks_requires_rank_enum'
+       AND conrelid = 'tasks'::regclass
+  ) THEN
+    ALTER TABLE tasks
+      ADD CONSTRAINT tasks_requires_rank_enum
+      CHECK (requires_rank IN ('xenos', 'metic', 'archon'));
+  END IF;
+END $$;
+
+-- Rebuild the two SELECT t.* views so the new column flows through. Bodies
+-- identical to migration 039 — only the implicit t.* column list changes.
+
+DROP VIEW IF EXISTS claimable_tasks;
+CREATE VIEW claimable_tasks AS
+SELECT t.*,
+       pms_calibrated_minutes(t.est_minutes, t.kind) AS est_minutes_calibrated
+  FROM tasks t
+ WHERE t.status = 'ready'
+   AND t.title NOT LIKE '\_\_smoke\_\_%' ESCAPE '\'
+   AND NOT EXISTS (
+     SELECT 1 FROM task_blockers tb WHERE tb.task_id = t.id
+   )
+   AND NOT EXISTS (
+     SELECT 1 FROM claims c
+       JOIN tasks t2 ON t2.id = c.task_id
+      WHERE c.released_at IS NULL
+        AND t2.touches && t.touches
+   );
+
+DROP VIEW IF EXISTS tasks_session_fit;
+CREATE VIEW tasks_session_fit AS
+SELECT t.*,
+  CASE
+    WHEN t.automation_tag = 'overnight-safe' AND COALESCE(t.manual_degree, 5) <= 2
+         AND NOT EXISTS (SELECT 1 FROM task_blockers tb WHERE tb.task_id = t.id)
+      THEN ARRAY['autonomous','check-in','active']
+    WHEN t.automation_tag = 'live-only' OR COALESCE(t.manual_degree, 5) >= 4
+      THEN ARRAY['active']
+    ELSE ARRAY['check-in','active']
+  END AS fits_session_modes,
+  pms_calibrated_minutes(t.est_minutes, t.kind) AS est_minutes_calibrated,
+  CASE
+    WHEN t.credits_reward > 0
+     AND pms_calibrated_minutes(t.est_minutes, t.kind) IS NOT NULL
+     AND pms_calibrated_minutes(t.est_minutes, t.kind) > 0
+    THEN ROUND(t.credits_reward::numeric / pms_calibrated_minutes(t.est_minutes, t.kind), 3)
+    ELSE NULL
+  END AS credits_per_minute
+FROM tasks t;
+
+INSERT INTO schema_migrations (version) VALUES ('044_tasks_requires_rank')
+  ON CONFLICT (version) DO NOTHING;

package/migrations/045_builder_onboarding_state.sql

@@ -0,0 +1,147 @@
+-- 045_builder_onboarding_state.sql — V3.R75 (#294): auto-completing onboarding checklist.
+--
+-- #238 (migration 043) gave us the funnel basics: builders.onboarded_at and
+-- builders.first_ship_at, the two single-timestamp shortcuts the Archon roster
+-- already renders. That covers the *start* and *finish* of the funnel but
+-- nothing in between, and it gives the *builder* themselves no way to see
+-- "where am I in onboarding right now?". This migration adds the structured
+-- middle: a small state-machine row per builder that ticks itself off as
+-- events fire (Device Flow done, first /builder-start, first claim, first
+-- ship, first karma vote received, graduated).
+--
+-- Design choices:
+--
+--   * One row per builder (PRIMARY KEY = builder_id). The state is a 1:1
+--     relationship — every builder gets exactly one onboarding journey, and
+--     re-running it has no meaning. Upserts on first hit.
+--
+--   * `current_stage` is the next stage the builder needs to clear. Stays
+--     'graduated' once they've graduated. completed_stages[] is the audit
+--     trail (what they've already cleared) so the UI can render checkmarks
+--     without inferring from the cached current_stage alone.
+--
+--   * `completed_stages text[]` not `jsonb`: this is a flat append-only set
+--     of stage names. Postgres arrays + the ANY operator are the right shape;
+--     jsonb would be a strictly-worse fit for the set semantics.
+--
+--   * CHECK constraint on `current_stage` against the 7 stages so a code bug
+--     can't smuggle in 'frist_ship'-style typos. completed_stages[] is NOT
+--     CHECK-constrained per element — Postgres can't CHECK array elements
+--     against an enum without a custom domain or a trigger, and the cost
+--     isn't worth the marginal safety. The application layer normalizes
+--     stage names through markStage().
+--
+--   * `started_at` set on first row creation (when auth_complete fires).
+--     `completed_at` set when `current_stage` flips to 'graduated'. The gap
+--     between the two is the time-to-graduate metric (extends time-to-first-
+--     ship from #238 — graduation = first_ship + first_vote_received).
+--
+-- Backfill strategy:
+--
+-- Every existing builder gets a row with completed_stages reconstructed from
+-- the observability columns added in migration 043:
+--
+--   onboarded_at    IS NOT NULL → auth_complete cleared
+--   first_ship_at   IS NOT NULL → first_claim + first_ship cleared
+--                                 (you can't ship without claiming first, so
+--                                 first_claim is implied — backfilling both
+--                                 keeps the checklist coherent)
+--
+-- We can't reconstruct first_start (the GET /tasks/claimable signal) or
+-- first_vote_received (karma_log peer-vote rows) from existing data because
+-- those weren't tracked. Existing builders who have already cleared those
+-- stages WILL re-fire the event the next time they hit the endpoint —
+-- markStage() is idempotent, so the re-fire is a no-op and graduation is
+-- still reachable. primer_read has no historical signal at all and stays
+-- uncleared for everyone until the primer-read route lands (see notes_md on
+-- the issuing task).
+--
+-- current_stage is set to the FIRST stage not yet in completed_stages, with
+-- a graduation-detector that flips to 'graduated' iff all six prior stages
+-- are cleared. The application code maintains the same invariant going
+-- forward.
+--
+-- Idempotent: safe to re-run.
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS builder_onboarding_state (
+  builder_id        bigint PRIMARY KEY REFERENCES builders(id) ON DELETE CASCADE,
+  current_stage     text NOT NULL,
+  completed_stages  text[] NOT NULL DEFAULT '{}'::text[],
+  started_at        timestamptz NOT NULL DEFAULT now(),
+  completed_at      timestamptz
+);
+
+-- The seven stages. Order matters for current_stage advancement but is
+-- defined in the application layer (src/bongos/onboarding-state.js) — the DB
+-- only validates the enum membership.
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_constraint
+     WHERE conname = 'builder_onboarding_state_stage_enum'
+       AND conrelid = 'builder_onboarding_state'::regclass
+  ) THEN
+    ALTER TABLE builder_onboarding_state
+      ADD CONSTRAINT builder_onboarding_state_stage_enum
+      CHECK (current_stage IN (
+        'auth_complete',
+        'primer_read',
+        'first_start',
+        'first_claim',
+        'first_ship',
+        'first_vote_received',
+        'graduated'
+      ));
+  END IF;
+END $$;
+
+-- Sparse index for "still onboarding" queries (completed_at IS NULL) — the
+-- Archon dashboard will hit this frequently to surface in-progress builders.
+CREATE INDEX IF NOT EXISTS idx_builder_onboarding_in_progress
+  ON builder_onboarding_state (started_at)
+  WHERE completed_at IS NULL;
+
+-- ---------------------------------------------------------------------------
+-- Backfill. Inserts one row per builder if missing, with completed_stages[]
+-- reconstructed from the migration 043 observability columns.
+-- ---------------------------------------------------------------------------
+
+-- Helper: pick the first uncompleted stage in canonical order, or 'graduated'
+-- if all six are done. Inlined as a CASE in the INSERT below — keeps it one
+-- statement, no PL/pgSQL function needed.
+INSERT INTO builder_onboarding_state (builder_id, current_stage, completed_stages, started_at, completed_at)
+SELECT
+  b.id,
+  CASE
+    WHEN b.onboarded_at IS NULL THEN 'auth_complete'
+    -- primer_read has no historical signal — always next-after-auth unless
+    -- a later stage is already cleared (in which case the builder has clearly
+    -- already moved on, and we don't want to gate them on a backfilled stage
+    -- they never saw the prompt for).
+    WHEN b.first_ship_at IS NULL THEN 'primer_read'
+    -- After first_ship is cleared, the only stage left is first_vote_received.
+    ELSE 'first_vote_received'
+  END AS current_stage,
+  ARRAY(
+    SELECT s FROM (VALUES
+      ('auth_complete',    b.onboarded_at  IS NOT NULL),
+      -- first_claim is implied by first_ship_at (can't ship what you didn't
+      -- claim). Backfilling both keeps the checklist coherent for legacy rows.
+      ('first_claim',      b.first_ship_at IS NOT NULL),
+      ('first_ship',       b.first_ship_at IS NOT NULL)
+    ) AS v(s, cleared)
+    WHERE cleared
+  ) AS completed_stages,
+  COALESCE(b.onboarded_at, b.created_at, now()) AS started_at,
+  NULL::timestamptz AS completed_at
+FROM builders b
+WHERE NOT EXISTS (
+  SELECT 1 FROM builder_onboarding_state s WHERE s.builder_id = b.id
+);
+
+INSERT INTO schema_migrations (version) VALUES ('045_builder_onboarding_state')
+  ON CONFLICT (version) DO NOTHING;
+
+COMMIT;

package/migrations/046_cost_log_builder_attribution.sql

@@ -0,0 +1,42 @@
+-- 046_cost_log_builder_attribution.sql — V3.R11 (#91): per-builder cost attribution.
+--
+-- Background
+-- ----------
+-- Until now, cost_log rows carried no builder identity. Spend was attributable
+-- by task (when task_id was set) and by category, but the dashboard could not
+-- show "who spent what." That was acceptable while a single shared Google AI
+-- Studio key fed every builder's pipeline — there was nobody to attribute *to*.
+--
+-- V3.R11 (#91) flips that: each builder now registers their own Gemini key
+-- during /builder-setup, and the art pipeline knows which builder is making
+-- each call. This migration gives cost_log a place to record it.
+--
+-- Design choices
+-- --------------
+-- * Nullable column. Historical rows pre-date the feature; we must not
+--   invalidate them. New writes are expected to populate it (the route auto-
+--   fills from the authed builder when no body field is provided).
+-- * ON DELETE SET NULL — if a builder row is ever deleted, the cost survives;
+--   it just becomes attributed to "unknown" rather than vanishing.
+-- * Index on (builder_id, recorded_at DESC) for the dashboard's per-builder
+--   timeline query. The leading column is builder_id so the WHERE clause
+--   selects a builder cheaply; the trailing recorded_at DESC matches the
+--   "newest first" sort.
+--
+-- Acceptance
+-- ----------
+-- A fresh builder registering their key, running the art pipeline, and POSTing
+-- to /api/gds/cost has their builder_id stamped onto each row. The public
+-- /cost-summary endpoint exposes a by_builder aggregate that the status page
+-- renders alongside the existing by_category and by_track splits.
+
+ALTER TABLE cost_log
+  ADD COLUMN IF NOT EXISTS builder_id bigint
+    REFERENCES builders(id) ON DELETE SET NULL;
+
+CREATE INDEX IF NOT EXISTS idx_cost_log_builder_recorded
+  ON cost_log (builder_id, recorded_at DESC)
+  WHERE builder_id IS NOT NULL;
+
+INSERT INTO schema_migrations (version) VALUES ('046_cost_log_builder_attribution')
+  ON CONFLICT (version) DO NOTHING;

package/migrations/054_builder_memory.sql

@@ -0,0 +1,108 @@
+-- 054_builder_memory.sql — V3.R54 (#273): server-side store for a builder's
+-- Claude Code per-session memory dir. Implements ADR 0024 §1 (schema) and is
+-- the storage half of §4 (per-builder isolation — enforced at the helper +
+-- route layers, with the PRIMARY KEY making cross-builder collisions
+-- impossible by construction).
+--
+-- What "memory" is here (ADR 0024 "What memory means"):
+-- ----------------------------------------------------
+-- NOT code (git is canonical), NOT work-state (the GDS tables are canonical).
+-- This is the third artifact class: the markdown that Claude Code itself writes
+-- under ~/.claude/projects/<encoded-project>/memory/*.md (MEMORY.md,
+-- feedback_*.md) plus any builder-authored persistent context that isn't a git
+-- file and isn't a GDS row. Today it lives only on one laptop; this table is
+-- where it becomes server-canonical so it can follow a builder across machines
+-- and survive a dead laptop. #274 (push-on-ship) and #275 (pull-on-start) wire
+-- the round-trip; this task only lays the table + the helper layer.
+--
+-- Schema choice — Postgres TEXT, per-file rows (ADR 0024 §1)
+-- ---------------------------------------------------------
+-- The spike weighed BYTEA-per-file vs object storage (DO Spaces / S3) and chose
+-- Postgres TEXT in one new table:
+--   * content is TEXT, not BYTEA — memory files are markdown; being readable in
+--     `psql` for forensics is a real Archon convenience, and the values are
+--     kilobytes.
+--   * Object storage was REJECTED: +$5/mo minimum, +an SDK dependency, +a second
+--     auth surface, +a second backup story — all to solve a problem (large
+--     binary blobs) we don't have. Revisit only if per-file sizes routinely
+--     exceed 100 KB or the table passes ~1 GB and pg_dump time becomes painful.
+--   * git-backed memory was REJECTED: it would leak one builder's memory diffs
+--     into the public repo, contradicting the isolation requirement.
+--
+-- PRIMARY KEY (builder_id, path): one row per (builder, relative-path). `path`
+-- is the path under the builder's memory dir (e.g. 'MEMORY.md',
+-- 'feedback_auth_flows_ui_first.md'). A push for an existing (builder_id, path)
+-- is an UPSERT (last-write-wins per ADR 0024 §3 — applied in #274's push
+-- handler; the table just stores whatever the winning write left).
+--
+-- Quotas (ADR 0024 §1) are enforced at the HELPER layer (src/bongos/memory.js),
+-- not by DB constraints, so the API can return clean 413s with a prune hint:
+--   * 1 MB per file        (1000x current observed sizes)
+--   * 50 MB per builder    (50,000x current)
+--   * 2000 files per builder (defensive)
+-- byte_len + sha256 are stored so the pull side (#275) can do cheap
+-- newer/changed checks without shipping content, and so the per-builder total
+-- can be summed without scanning content.
+--
+-- Backup (ADR 0024 §5): this is a plain Postgres table, so it rides the GDS
+-- DB's nightly pg_dump (stood up by #412) for free. No separate backup story.
+--
+-- Idempotent: CREATE TABLE IF NOT EXISTS + IF NOT EXISTS indexes + ON CONFLICT
+-- DO NOTHING migration row.
+
+CREATE TABLE IF NOT EXISTS builder_memory (
+  -- Owner. Every read/write is scoped by this column (ADR 0024 §4). FK so a
+  -- row can never reference a ghost builder; ON DELETE CASCADE because a
+  -- builder's memory has no meaning once the builder row is gone (unlike
+  -- credit_log / cost_log, which preserve history on delete — memory is
+  -- mutable scratch, not an audit trail).
+  builder_id   bigint NOT NULL REFERENCES builders(id) ON DELETE CASCADE,
+  -- Relative path under the builder's memory dir, e.g. 'MEMORY.md'. NOT a
+  -- filesystem-absolute path — the local checkout path is hyphen-encoded and
+  -- machine-specific (ADR 0024 §5 path-encoding gotcha); memory is keyed by
+  -- (builder_id, relative-path) so it restores regardless of where on disk a
+  -- checkout lives.
+  path         text   NOT NULL CHECK (length(path) > 0),
+  -- The file body. TEXT (markdown), not BYTEA — see header.
+  content      text   NOT NULL,
+  -- Client's reported mtime of the file at push time. The conflict policy
+  -- (ADR 0024 §3) is last-write-wins on the SERVER clock; this column records
+  -- the source file's mtime for the pull side's newer-than comparison and for
+  -- forensics. Defaults to now() so a row is never left without one.
+  mtime        timestamptz NOT NULL DEFAULT now(),
+  -- Content hash + byte length: let the pull side (#275) detect unchanged files
+  -- cheaply and let the helper sum a builder's total bytes without scanning
+  -- content.
+  sha256       text   NOT NULL,
+  byte_len     integer NOT NULL CHECK (byte_len >= 0),
+  -- When this row was first stored / last overwritten on the server. Distinct
+  -- from mtime (which is the client file's timestamp). updated_at is the
+  -- server's truth for "when did the canonical copy last change."
+  created_at   timestamptz NOT NULL DEFAULT now(),
+  updated_at   timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (builder_id, path)
+);
+
+-- Primary access patterns:
+--   * fetch one file:  WHERE builder_id = $1 AND path = $2  → served by the PK.
+--   * list / sum for a builder: WHERE builder_id = $1       → served by the PK
+--     prefix, but an explicit index on (builder_id, updated_at DESC) keeps the
+--     "what changed since" pull query (#275) and the "newest first" listing
+--     fast without leaning on PK ordering.
+CREATE INDEX IF NOT EXISTS idx_builder_memory_builder_updated
+  ON builder_memory (builder_id, updated_at DESC);
+
+-- Auto-bump updated_at on every overwrite. Reuses the same trigger function the
+-- tasks table uses (pms_touch_updated_at, defined in 003_pms.sql) — one
+-- canonical "touch updated_at" function for the whole GDS schema.
+DROP TRIGGER IF EXISTS trg_builder_memory_updated_at ON builder_memory;
+CREATE TRIGGER trg_builder_memory_updated_at
+  BEFORE UPDATE ON builder_memory
+  FOR EACH ROW EXECUTE FUNCTION pms_touch_updated_at();
+
+-- Keep the migration counter ahead of 054 so the next claim that includes
+-- 'migrations/' allocates 055 (same convention as the recent migrations).
+UPDATE migration_counter SET next_number = GREATEST(next_number, 55) WHERE id = 1;
+
+INSERT INTO schema_migrations (version) VALUES ('054_builder_memory')
+  ON CONFLICT (version) DO NOTHING;

package/migrations/055_task_criteria.sql

@@ -0,0 +1,90 @@
+-- 055_task_criteria.sql — #435: structured criterion↔task link.
+--
+-- WHY THIS EXISTS
+-- ---------------
+-- Before this table, the only record of "which tasks satisfy criterion C8"
+-- lived as prose in each task's description (`**Criterion:** C8 — …`).
+-- Answering "what's left for C8?" therefore meant grepping seed-v3-tasks.js,
+-- eyeballing a "Gates V3.R55–V3.R63" sentence, then re-querying every task's
+-- status by hand (~10 calls). This makes the relation a first-class, queryable
+-- thing so GET /api/gds/versions/:id/progress (and the /status skill) can roll
+-- it up in one call. See ADR 0025.
+--
+-- WHY MANY-TO-MANY (and not a column on tasks)
+-- --------------------------------------------
+-- done_when_criteria.satisfied_by_task_id already exists, but it is the SINGLE,
+-- REVERSE link: the one ship-task that *closed* a criterion. We need the
+-- forward, MANY link: the many tasks that *gate*/contribute to a criterion
+-- (C8 ← R55–R63). Tasks also contribute to multiple criteria (prose like
+-- "C2, C7"), so the relation is many-to-many → a join table is the only honest
+-- shape. (ADR 0025 records the rejected alternatives.)
+--
+-- THE BACKFILL IS POSITIONAL — and that is exactly the fragility we're retiring
+-- -----------------------------------------------------------------------------
+-- The prose says "C8" but a criterion's criterion_id is a semantic slug
+-- (`cloneable-local-memory-server-sync`). "Cn" is the 1-based position by
+-- (sort_order, criterion_id) within the version: C1 = onboarding-2h, …,
+-- C8 = cloneable-local-memory-server-sync. So the backfill ranks each version's
+-- criteria with ROW_NUMBER() and joins prose "Cn" → the n-th criterion of the
+-- SAME version. A task listing "C2, C7" yields two rows.
+--
+-- This positional decode is brittle (reorder the criteria and old prose drifts),
+-- which is the whole reason this table exists: from here on the structured link
+-- is canonical and new tasks should populate task_criteria directly (follow-up
+-- task: wire task-create + a manage endpoint). This is a ONE-TIME historical
+-- backfill of the prose that existed at migration time — it is not re-run.
+--
+-- Tasks whose Criterion line has no "Cn" token (e.g. "cross-cutting (identity)",
+-- "the proof Tier 1 is done") are intentionally left unlinked; /progress counts
+-- them as unattributed rather than guessing.
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS task_criteria (
+  task_id      bigint NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+  criterion_id bigint NOT NULL REFERENCES done_when_criteria(id) ON DELETE CASCADE,
+  source       text   NOT NULL DEFAULT 'backfill',  -- 'backfill' | 'manual' | 'planning'
+  created_at   timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (task_id, criterion_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_task_criteria_criterion ON task_criteria (criterion_id);
+CREATE INDEX IF NOT EXISTS idx_task_criteria_task      ON task_criteria (task_id);
+
+-- One-time positional backfill from the **Criterion:** Cn prose.
+WITH crit_line AS (
+  -- The text of the Criterion line only (so we never pick up a stray "Cn"
+  -- elsewhere in the body). regexp_match (singular) → first occurrence.
+  SELECT id AS task_id,
+         version_id,
+         (regexp_match(description, '\*\*Criterion:\*\*\s*([^\r\n]*)'))[1] AS line
+    FROM tasks
+   WHERE description ~ '\*\*Criterion:\*\*'
+),
+crit_nums AS (
+  -- Every "Cn" token on that line → one (task, n) pair. 'g' flag handles
+  -- multi-criterion tasks ("C2, C7").
+  SELECT task_id,
+         version_id,
+         (regexp_matches(line, 'C([0-9]+)', 'g'))[1]::int AS cnum
+    FROM crit_line
+   WHERE line IS NOT NULL AND line <> ''
+),
+ranked AS (
+  -- Live 1-based position per version — same ordering listCriteria() uses.
+  SELECT id AS criterion_id,
+         version_id,
+         ROW_NUMBER() OVER (PARTITION BY version_id ORDER BY sort_order, criterion_id) AS cnum
+    FROM done_when_criteria
+)
+INSERT INTO task_criteria (task_id, criterion_id, source)
+SELECT cn.task_id, r.criterion_id, 'backfill'
+  FROM crit_nums cn
+  JOIN ranked r
+    ON r.version_id = cn.version_id
+   AND r.cnum       = cn.cnum
+ON CONFLICT DO NOTHING;
+
+INSERT INTO schema_migrations (version) VALUES ('055_task_criteria') ON CONFLICT DO NOTHING;
+
+COMMIT;

package/migrations/058_peer_votes.sql

@@ -0,0 +1,41 @@
+-- V3.R25 (#245) — builder-on-builder peer votes on confirmed/shipped work.
+--
+-- Criterion C2 (karma signal sourcing): karma (migration 040) needs a
+-- continuous peer input. Every confirmed/shipped task can be voted on by other
+-- Metic+ builders: +1 = good work, -1 = concerns. A weekly tally folds the net
+-- votes into karma_log rows for the SHIPPING builder.
+--
+-- Anti-retaliation by design — two guards:
+--   1. Anti-self-vote: enforced in the route (a CHECK can't see tasks.shipped_by
+--      from here). 403 if voter == task.shipped_by.
+--   2. 7-day karma lag: the weekly tally only folds votes that are ≥ 7 days old
+--      (recorded_at <= now() - 7d). A vote cast today can't move karma until
+--      next week, so retaliation cycles have no immediate payoff. tallied_at
+--      marks a vote as already folded so it's never double-counted; once a vote
+--      is tallied it's frozen (the route refuses to change it).
+--
+-- Feeds R26 (#246) which surfaces karma on the profile + leaderboard.
+
+CREATE TABLE IF NOT EXISTS peer_votes (
+  id                bigserial PRIMARY KEY,
+  voter_builder_id  bigint NOT NULL REFERENCES builders(id),
+  target_task_id    bigint NOT NULL REFERENCES tasks(id),
+  vote              integer NOT NULL CHECK (vote IN (-1, 1)),  -- 0 = cleared = row deleted
+  recorded_at       timestamptz NOT NULL DEFAULT now(),
+  tallied_at        timestamptz,  -- NULL = not yet folded into karma; set by the weekly tally
+  UNIQUE (voter_builder_id, target_task_id)
+);
+
+-- Net-votes-per-task read (feed + single task display).
+CREATE INDEX IF NOT EXISTS idx_peer_votes_target ON peer_votes (target_task_id);
+-- Weekly tally hot path: matured, not-yet-folded votes.
+CREATE INDEX IF NOT EXISTS idx_peer_votes_untallied ON peer_votes (recorded_at) WHERE tallied_at IS NULL;
+
+-- Supports the acclaim feed (GET /tasks/peer-votes/feed): a partial, functional
+-- index whose predicate matches the feed's WHERE (confirmed/shipped, attributed)
+-- and whose ordering matches its sort — COALESCE(shipped_at, updated_at) DESC —
+-- so the feed reads the top rows from the index instead of scanning + sorting
+-- every historical task. Without it, cost grows linearly with project history.
+CREATE INDEX IF NOT EXISTS idx_tasks_votable_recent
+  ON tasks ((COALESCE(shipped_at, updated_at)) DESC)
+  WHERE status IN ('confirmed', 'shipped') AND shipped_by IS NOT NULL;

package/migrations/059_onboarding_pick_disciplines.sql

@@ -0,0 +1,59 @@
+-- 059_onboarding_pick_disciplines.sql — 2026-05-30: reshape the onboarding path.
+--
+-- Two changes to the onboarding state machine that migration 045 established:
+--
+--   1. Remove 'first_vote_received'. Gating graduation on a peer upvote is too
+--      much to ask of a brand-new builder — they can graduate before anyone
+--      has had a chance to vote on their work. The stage is dropped from the
+--      allowed-stage set.
+--
+--   2. Add 'pick_disciplines'. New builders now choose the kind of work they
+--      want (creative / engineering / both) as an explicit onboarding step,
+--      wired to the existing builders.preferred_disciplines column (migration
+--      027). The application layer (src/bongos/onboarding-state.js STAGES) places
+--      it after 'primer_read' and before 'first_start' so the choice is made
+--      before the builder surveys the works on offer.
+--
+-- The DB only validates enum membership of current_stage; ordering lives in
+-- the app layer. So this migration just swaps the CHECK constraint's allowed
+-- set and re-homes any rows currently parked at the removed stage.
+--
+-- Grandfathering: a builder sitting at current_stage='first_vote_received' has
+-- already cleared every stage that mattered in the old model (auth → ship).
+-- Rather than re-prompt them through the reshaped path, we promote them
+-- straight to 'graduated' and stamp completed_at. completed_stages[] is an
+-- audit array (not CHECK-constrained per element), so the lingering
+-- 'first_vote_received' entry there is harmless and left as-is.
+--
+-- Idempotent: safe to re-run.
+
+BEGIN;
+
+-- 1. Re-home rows parked at the removed stage BEFORE swapping the constraint,
+--    or the new CHECK would reject them.
+UPDATE builder_onboarding_state
+   SET current_stage = 'graduated',
+       completed_at  = COALESCE(completed_at, now())
+ WHERE current_stage = 'first_vote_received';
+
+-- 2. Swap the stage enum: drop the old constraint (if present) and add the new
+--    one. Names match migration 045 so re-running is clean.
+ALTER TABLE builder_onboarding_state
+  DROP CONSTRAINT IF EXISTS builder_onboarding_state_stage_enum;
+
+ALTER TABLE builder_onboarding_state
+  ADD CONSTRAINT builder_onboarding_state_stage_enum
+  CHECK (current_stage IN (
+    'auth_complete',
+    'primer_read',
+    'pick_disciplines',
+    'first_start',
+    'first_claim',
+    'first_ship',
+    'graduated'
+  ));
+
+INSERT INTO schema_migrations (version) VALUES ('059_onboarding_pick_disciplines')
+  ON CONFLICT (version) DO NOTHING;
+
+COMMIT;