@bongos/core 1.17.0

package/migrations/032_repo_health_snapshots.sql

@@ -0,0 +1,56 @@
+-- 032_repo_health_snapshots.sql — measurement substrate for repo cleanliness (V3.R91 / #352).
+--
+-- Layer 0 (SHARED SUBSTRATE) of the code-simplification plan. One table that
+-- `scripts/gds/repo-metrics.js` upserts a daily snapshot into, and that the
+-- new /api/gds/public/repo-health read-surface reads back for the status page.
+--
+-- "You can't manage what you don't measure." This is the single cheap
+-- measurement layer that Layers 1 (PREVENT, grader economy lens — #353) and
+-- 2 (REWARD — #354) and the future janitor (Layer 3) all build on top of.
+--
+-- Shape (one row per calendar date, server timezone):
+--   snapshot_date   — date key. UNIQUE so reruns the same day upsert, never
+--                     duplicate (the idempotency requirement).
+--   total_loc       — total tracked JS/MJS line count across the project.
+--   loc_by_dir      — jsonb { "src/": n, "public/game/": n, ... } current
+--                     line counts per watched directory.
+--   largest_files   — jsonb array [{ path, lines }] top-N by size.
+--   dead_exports    — int | NULL. knip unused-export count. NULL when knip is
+--                     unavailable/unconfigured (degrades gracefully — the rest
+--                     of the snapshot still records).
+--   dead_files      — int | NULL. knip unused-file count (same NULL semantics).
+--   stale_branches  — int. count of unmerged claude/* branches.
+--   max_branch_age_days — numeric | NULL. age of the oldest unmerged branch.
+--   confirmed_unshipped — int. tasks at status='confirmed' (verified, not yet
+--                     on main) — the merge-mode backlog made visible.
+--   raw             — jsonb. the full snapshot blob the CLI emitted, for any
+--                     future field we surface without a migration.
+--   created_at      — when this row was last written.
+--
+-- Idempotent: CREATE TABLE IF NOT EXISTS; the CLI upserts ON CONFLICT
+-- (snapshot_date). Re-running this migration is a no-op.
+
+CREATE TABLE IF NOT EXISTS repo_health_snapshots (
+  id                  bigserial PRIMARY KEY,
+  snapshot_date       date NOT NULL UNIQUE,
+  total_loc           integer,
+  loc_by_dir          jsonb NOT NULL DEFAULT '{}'::jsonb,
+  largest_files       jsonb NOT NULL DEFAULT '[]'::jsonb,
+  dead_exports        integer,
+  dead_files          integer,
+  stale_branches      integer NOT NULL DEFAULT 0,
+  max_branch_age_days numeric,
+  confirmed_unshipped integer NOT NULL DEFAULT 0,
+  raw                 jsonb NOT NULL DEFAULT '{}'::jsonb,
+  created_at          timestamptz NOT NULL DEFAULT now()
+);
+
+-- Trend queries read the most recent N rows by date.
+CREATE INDEX IF NOT EXISTS idx_repo_health_date ON repo_health_snapshots (snapshot_date DESC);
+
+-- Bump the migration counter past 032 so the next claim that includes
+-- 'migrations/' allocates 033.
+UPDATE migration_counter SET next_number = GREATEST(next_number, 33) WHERE id = 1;
+
+INSERT INTO schema_migrations (version) VALUES ('032_repo_health_snapshots')
+  ON CONFLICT (version) DO NOTHING;

package/migrations/033_audit_log.sql

@@ -0,0 +1,64 @@
+-- 033_audit_log.sql — append-only audit stream for privileged writes (V3.R35 / #256).
+--
+-- Today most state changes are recoverable from individual tables (credit_log,
+-- task updates, claims, etc.) but there is no single "who did what when"
+-- stream. With multiple builders authenticating against the same server we
+-- need an append-only ledger so:
+--   - the R67 Archon security view can show "all writes by builder X" in one
+--     query without scanning a dozen feature tables;
+--   - post-incident forensics has a single chronological record;
+--   - a future periodic auditor (R45) can replay write history.
+--
+-- Captured: every AUTHENTICATED WRITE (POST/PATCH/PUT/DELETE) request the
+-- /api/gds router serves. Reads (GETs) are NOT logged — volume + signal/noise.
+--
+-- Redaction: the writing middleware (src/bongos/middleware/audit.js) walks the
+-- parsed body and replaces any value whose KEY name contains 'token',
+-- 'password', 'key', or 'secret' (case-insensitive) with the literal string
+-- '<redacted>'. Recurses into nested objects + arrays. The redacted body is
+-- what lands here.
+--
+-- Retention: indefinite for V3. A retention sweep is explicitly a V4 concern.
+-- (We don't index for deletion; the v3 plan is "we'll deal with it when the
+-- table actually gets big.")
+--
+-- Idempotent: CREATE TABLE IF NOT EXISTS + ON CONFLICT DO NOTHING migration row.
+
+CREATE TABLE IF NOT EXISTS audit_log (
+  id                       bigserial PRIMARY KEY,
+  -- Who made the request. NULL would mean "unauthenticated", but the middleware
+  -- only fires for authenticated writes, so this column is NOT NULL in practice.
+  -- We still FK to builders so a stray entry can never reference a ghost.
+  builder_id               bigint NOT NULL REFERENCES builders(id),
+  -- The matched route path (e.g. '/tasks/:id', not '/tasks/256') so we can
+  -- group by endpoint. Falls back to req.path if the matched route isn't
+  -- available (some sub-router edge cases).
+  route                    text NOT NULL,
+  method                   text NOT NULL CHECK (method IN ('POST','PATCH','PUT','DELETE')),
+  -- Parsed JSON request body, with sensitive keys redacted. Stored as jsonb so
+  -- we can later run ad-hoc queries against specific fields. Defaults to '{}'.
+  request_body_redacted    jsonb NOT NULL DEFAULT '{}'::jsonb,
+  -- The HTTP status the response went out with. We log AFTER 'finish' so this
+  -- is the real status the client saw.
+  response_status          integer NOT NULL,
+  -- Client IP. Honors the express 'trust proxy' setting (set in server.js) so
+  -- we record the real client through the Cloudflare → Caddy → Node chain.
+  ip                       text,
+  -- User-Agent header, free text.
+  user_agent               text,
+  recorded_at              timestamptz NOT NULL DEFAULT now()
+);
+
+-- Forensics queries are almost always "what did builder X do" or "everything
+-- in the last N hours sorted newest-first". Index both.
+CREATE INDEX IF NOT EXISTS idx_audit_log_builder ON audit_log (builder_id, recorded_at DESC);
+CREATE INDEX IF NOT EXISTS idx_audit_log_recorded_at ON audit_log (recorded_at DESC);
+-- "Who's hitting this route" is the third common shape.
+CREATE INDEX IF NOT EXISTS idx_audit_log_route ON audit_log (route, recorded_at DESC);
+
+-- Bump the migration counter past 033 so the next claim that includes
+-- 'migrations/' allocates 034.
+UPDATE migration_counter SET next_number = GREATEST(next_number, 34) WHERE id = 1;
+
+INSERT INTO schema_migrations (version) VALUES ('033_audit_log')
+  ON CONFLICT (version) DO NOTHING;

package/migrations/034_lifecycle_breakdown_leaf_only.sql

@@ -0,0 +1,62 @@
+-- 034_lifecycle_breakdown_leaf_only.sql — fix version_lifecycle_breakdown
+-- double-count of parent + children (V3.R23 / #243).
+--
+-- Background: migration 012 created version_lifecycle_breakdown to give the
+-- public dashboard a per-state breakdown (completed / confirmed / shipped) per
+-- version. Unlike its sibling view version_progress — which was rebuilt in
+-- 006_pms_v2 (and tweaked in 012 and 017) to count ONLY LEAF TASKS — the
+-- lifecycle breakdown counts EVERY task row. The result: a parent task with 3
+-- shipped children inflates "shipped_count" by 4 (the parent's own row + each
+-- child's row), which distorts the leaderboard and the version-progress card
+-- on the status page.
+--
+-- Fix: replace version_lifecycle_breakdown with the same leaf predicate
+-- version_progress uses —
+--   NOT EXISTS (SELECT 1 FROM tasks c WHERE c.parent_task_id = t.id)
+-- — so only rows that have no children contribute. Parents become invisible
+-- to the rollup; their state is reflected by their children, which is the
+-- correct semantics (a parent is shipped when all its children are shipped,
+-- but the leaderboard cares about leaf work).
+--
+-- The column list is unchanged from migration 012 (version_id, name, track,
+-- completed_count, confirmed_count, shipped_count). Postgres rejects
+-- CREATE OR REPLACE VIEW when a column name or order changes; even though
+-- nothing changes here, the established safe pattern in this repo (see
+-- migration 017's comment) is DROP + CREATE for any view edit. Following it.
+--
+-- Forward-compatibility note: this view does NOT filter out abandoned or
+-- __smoke__ tasks beyond what migration 012 did — those are kept where they
+-- were so the per-state numerator stays honest (e.g. completed_count is "leaf
+-- tasks currently at status=completed", which by definition can't be
+-- abandoned). The __smoke__ exclusion already in 012 stays.
+
+DROP VIEW IF EXISTS version_lifecycle_breakdown;
+CREATE VIEW version_lifecycle_breakdown AS
+SELECT v.id AS version_id,
+       v.name,
+       v.track,
+       count(*) FILTER (
+         WHERE t.status = 'completed'
+           AND t.title NOT LIKE '\_\_smoke\_\_%' ESCAPE '\'
+           AND NOT EXISTS (SELECT 1 FROM tasks c WHERE c.parent_task_id = t.id)
+       ) AS completed_count,
+       count(*) FILTER (
+         WHERE t.status = 'confirmed'
+           AND t.title NOT LIKE '\_\_smoke\_\_%' ESCAPE '\'
+           AND NOT EXISTS (SELECT 1 FROM tasks c WHERE c.parent_task_id = t.id)
+       ) AS confirmed_count,
+       count(*) FILTER (
+         WHERE t.status = 'shipped'
+           AND t.title NOT LIKE '\_\_smoke\_\_%' ESCAPE '\'
+           AND NOT EXISTS (SELECT 1 FROM tasks c WHERE c.parent_task_id = t.id)
+       ) AS shipped_count
+  FROM versions v
+  LEFT JOIN tasks t ON t.version_id = v.id
+ GROUP BY v.id, v.name, v.track;
+
+-- Bump the migration counter past 034 so the next claim that includes
+-- 'migrations/' allocates 035.
+UPDATE migration_counter SET next_number = GREATEST(next_number, 35) WHERE id = 1;
+
+INSERT INTO schema_migrations (version) VALUES ('034_lifecycle_breakdown_leaf_only')
+  ON CONFLICT (version) DO NOTHING;

package/migrations/035_auth_token_hygiene.sql

@@ -0,0 +1,66 @@
+-- 035_auth_token_hygiene.sql
+--
+-- V3.R38 / task #259 — short-lived auth sessions with refresh-on-use, plus
+-- Archon-only revocation endpoints. The SCHEMA side is small: builder_sessions
+-- already has the columns we need (expires_at, last_used_at, revoked_at since
+-- 003_pms.sql). What this migration does is:
+--
+--   1. BACKFILL existing rows' expires_at with a GENEROUS 24-hour grace runway
+--      from migration time. This is intentional: the live autonomous overnight
+--      supervisor (and any builder mid-flow) holds a long-lived CLI token. If
+--      we retroactively expired it, the very session running this migration
+--      would die. The 24h grace gives every active session a window to either
+--      (a) hit a route, refresh-on-use, and roll forward into the new 1h TTL
+--      regime, or (b) sit idle and expire naturally after 24h.
+--
+--      Formula: expires_at = GREATEST(NOW() + INTERVAL '24 hours',
+--                                     last_used_at + INTERVAL '24 hours').
+--
+--      Worked example: last_used_at = NOW() - 1h → new expires_at = NOW() + 24h.
+--      Worked example: last_used_at = NOW() + 5m (clock skew) → new expires_at
+--                       = (NOW()+5m) + 24h ≈ NOW() + 24h05m. Always future.
+--
+--      Worked example: existing expires_at was NULL (the CLI-never-expires
+--                       default from 003_pms.sql) → backfilled to a future
+--                       timestamp; refresh-on-use will keep it rolling.
+--
+--   2. Add an index on (builder_id, revoked_at) so revoke-all-for-builder is
+--      cheap (touches only rows for that builder, filters out already-revoked).
+--
+-- The 1-HOUR TTL itself is enforced in code (src/bongos/db.js): createSession
+-- defaults expiresAt to NOW()+1h, and lookupSession bumps last_used_at AND
+-- expires_at = NOW()+1h on every authenticated request. We do NOT enforce the
+-- 1h cap at the SQL level — that would risk the migration retroactively
+-- punching existing sessions, and the code-level enforcement is sufficient for
+-- C7 (rank-change-near-instant: a demoted builder's tokens are revoked-all
+-- explicitly, not waited-out via TTL).
+--
+-- Idempotent: safe to re-run. The UPDATE only touches rows where the formula
+-- would push expires_at FORWARD — it never shortens an existing future expiry.
+
+BEGIN;
+
+-- 1. Backfill: every row where the current expires_at is null OR earlier than
+--    the grace window gets pushed out. Never shortens.
+UPDATE builder_sessions
+   SET expires_at = GREATEST(
+     NOW() + INTERVAL '24 hours',
+     last_used_at + INTERVAL '24 hours'
+   )
+ WHERE revoked_at IS NULL
+   AND (
+     expires_at IS NULL
+     OR expires_at < GREATEST(
+       NOW() + INTERVAL '24 hours',
+       last_used_at + INTERVAL '24 hours'
+     )
+   );
+
+-- 2. Helpful index for revoke-all-for-builder (and for filtering active
+--    sessions in admin reads). Already-revoked rows are skipped by the partial
+--    predicate so revoke-all only touches the relevant rows.
+CREATE INDEX IF NOT EXISTS idx_builder_sessions_builder_active
+  ON builder_sessions (builder_id)
+  WHERE revoked_at IS NULL;
+
+COMMIT;

package/migrations/037_builder_skill_model_prefs.sql

@@ -0,0 +1,44 @@
+-- 037_builder_skill_model_prefs.sql — per-builder model preferences per skill
+-- (V3.R85 / #304).
+--
+-- One column on `builders`, jsonb, default '{}'. Each entry maps a skill name
+-- (the directory under .claude/skills/ — e.g. 'planning-session',
+-- 'idea-triage', 'builder-claim') to a model preference token:
+--
+--   'opus'   — full-strength judgment, default for heavy-judgment skills
+--   'sonnet' — middle tier, when judgment is needed but cost matters
+--   'haiku'  — light judgment, for nearly-mechanical skills
+--   'script' — no LLM at all; the skill runs as a pure script invocation
+--              (used to record an intentional "no judgment needed here")
+--
+-- We keep this as a single jsonb column on `builders` rather than a separate
+-- `builder_skill_prefs` table because:
+--   - It's per-builder personalized config, not analytics. The natural read
+--     path is "what does THIS builder prefer for skill X" — one row by
+--     primary key. A table would force a join on every skill invocation.
+--   - The shape is sparse and irregular (builders only override skills they
+--     care about; defaults handle the rest). jsonb is the right shape.
+--   - Migrations to add a new skill don't need a backfill — a missing key
+--     just falls back to the system default, which is computed in
+--     src/bongos/skill-prefs.js.
+--   - V4 will retire the per-skill defaults in favor of per-skill-kind
+--     defaults (idea #30); having all prefs in one jsonb makes that
+--     reshape one schema-free rewrite of the helper, not a table migration.
+--
+-- Validation: the API (PATCH /api/gds/me/skill-prefs) enforces the four
+-- allowed values + a skill-name allowlist. We deliberately do NOT enforce
+-- either as a Postgres CHECK because the allowed skills change as new ones
+-- ship — a CHECK would force a code+schema coordinated change every time.
+--
+-- Idempotent: safe to re-run.
+
+ALTER TABLE builders
+  ADD COLUMN IF NOT EXISTS skill_model_prefs jsonb NOT NULL DEFAULT '{}'::jsonb;
+
+-- Bump the migration counter past 037 so the next claim that includes
+-- 'migrations/' allocates 038. (Counter was pre-reserved at claim time +
+-- bumped by hand to 037; this guarantees future allocs see >= 038.)
+UPDATE migration_counter SET next_number = GREATEST(next_number, 38) WHERE id = 1;
+
+INSERT INTO schema_migrations (version) VALUES ('037_builder_skill_model_prefs')
+  ON CONFLICT (version) DO NOTHING;

package/migrations/038_task_override_requests.sql

@@ -0,0 +1,51 @@
+-- 038_task_override_requests.sql — V3.R74 (#293).
+--
+-- When the subagent grader rejects a ship (functional_fidelity or code_quality
+-- below threshold, or confidence too low), the task stays at 'completed' — no
+-- credits, no auto-merge. Most of the time the grader is right; sometimes it's
+-- wrong (false negative on diff shape, scoring drift, mis-read intent). The
+-- builder needs a path to ask an Archon to override the failed grade.
+--
+-- Today the only override path is POST /tasks/:id/confirm — but that's
+-- Archon-only by route guard, so a Metic stuck on a bad grade has nothing
+-- between them and "ping Lars in chat." This table is the request queue.
+--
+-- Lifecycle: open → approved | denied (terminal; row is the audit trail).
+-- On 'approved', the same transaction flips the task to confirmed and pays
+-- out credits via the existing confirmTask path. The override decision row
+-- captures who approved and why.
+--
+-- Per-task uniqueness: only ONE open request at a time per task. Once decided,
+-- the row stays for forensics but a new request can be opened (e.g. the task
+-- was re-graded and failed again).
+
+CREATE TABLE IF NOT EXISTS task_override_requests (
+  id                          bigserial PRIMARY KEY,
+  task_id                     bigint NOT NULL REFERENCES tasks(id),
+  requested_by_builder_id     bigint NOT NULL REFERENCES builders(id),
+  rationale                   text NOT NULL,
+  status                      text NOT NULL DEFAULT 'open'
+                                CHECK (status IN ('open', 'approved', 'denied')),
+  decided_by_builder_id       bigint REFERENCES builders(id),
+  decided_at                  timestamptz,
+  decision_note               text,
+  created_at                  timestamptz NOT NULL DEFAULT now()
+);
+
+-- Archon queue lookup: "open requests, newest first."
+CREATE INDEX IF NOT EXISTS idx_task_override_requests_open
+  ON task_override_requests (created_at DESC)
+  WHERE status = 'open';
+
+-- Per-task lookup (when surfacing on a task detail page).
+CREATE INDEX IF NOT EXISTS idx_task_override_requests_task
+  ON task_override_requests (task_id, created_at DESC);
+
+-- At most one open request per task. Enforced as a partial unique index on
+-- task_id so historical rows (approved/denied) don't conflict.
+CREATE UNIQUE INDEX IF NOT EXISTS uniq_task_override_requests_open_per_task
+  ON task_override_requests (task_id)
+  WHERE status = 'open';
+
+INSERT INTO schema_migrations (version) VALUES ('038_task_override_requests')
+  ON CONFLICT (version) DO NOTHING;

package/migrations/039_newcomer_friendly_column.sql

@@ -0,0 +1,124 @@
+-- 039_newcomer_friendly_column.sql — V3.R15: tasks.newcomer_friendly column +
+-- view-level filter + Xenos claim-policy error code.
+--
+-- Context: V3.R15 (#239) was planned as the row-level "newcomer-friendly task"
+-- gate for the Xenos rank. In parallel, #360 / ADR 0018 (migration 029) shipped
+-- the same idea under the name `xenos_claimable`. Now V3.R15 closes by:
+--
+--   1. Renaming `xenos_claimable` → `newcomer_friendly` (the task's canonical
+--      name — describes the *property of the task*, not "who is allowed").
+--      This is a pure rename: the column already has DEFAULT false and the
+--      existing values are preserved.
+--
+--   2. Rebuilding `claimable_tasks` and `tasks_session_fit` so the renamed
+--      column flows through `SELECT t.*`. (Same body as migration 028 — the
+--      only change is the implicit column list.)
+--
+--   3. View-level filter is realized in `db.js` listClaimableTasks: when the
+--      caller is a Xenos, the SELECT adds `WHERE newcomer_friendly = true`.
+--      The view itself stays builder-agnostic — applying the per-rank filter
+--      inside the view body isn't possible (views can't read session context).
+--      Belt-and-braces: `claimTask` still re-checks at claim time and returns
+--      `rank_too_low_for_task` (the V3.R15 error code; XENOS_RESTRICTED is kept
+--      as a code-side alias for callers on the pre-rename release).
+--
+--   4. Tag at least 3 currently-open backlog tasks as newcomer_friendly=true so
+--      the queue isn't empty when a Xenos arrives. Done inline at the bottom.
+--
+-- Idempotent: safe to re-run. The rename uses an IF EXISTS guard; the view
+-- rebuilds DROP+CREATE. The tagging UPDATE is keyed on still-open backlog rows
+-- so re-runs don't churn shipped tasks.
+
+-- 1. RENAME the column. Use a DO block so re-runs are safe whether or not the
+-- rename has already happened.
+DO $$
+BEGIN
+  IF EXISTS (
+    SELECT 1 FROM information_schema.columns
+     WHERE table_name = 'tasks' AND column_name = 'xenos_claimable'
+  ) AND NOT EXISTS (
+    SELECT 1 FROM information_schema.columns
+     WHERE table_name = 'tasks' AND column_name = 'newcomer_friendly'
+  ) THEN
+    ALTER TABLE tasks RENAME COLUMN xenos_claimable TO newcomer_friendly;
+  END IF;
+END $$;
+
+-- Defensive add — only fires if a fresh DB skipped migration 029 entirely.
+ALTER TABLE tasks
+  ADD COLUMN IF NOT EXISTS newcomer_friendly boolean NOT NULL DEFAULT false;
+
+-- 2. Rebuild the two SELECT t.* views so the renamed column flows through.
+-- Same bodies as migration 028.
+
+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;
+
+-- 4. Tag at least 3 currently-open V3 backlog tasks as newcomer_friendly so a
+-- freshly-onboarded Xenos has something safe to claim. Pick small, well-scoped
+-- cleanup/docs work — anything mechanical and low-stakes. Match titles to
+-- specific shipped concepts (renumbering, docs polish, small cleanups) so the
+-- set is stable across DB states. Use NOT-already-set guard so re-runs are
+-- no-ops.
+--
+-- Three specific picks (all V3.R* tasks, all kind in ('cleanup','docs'), all
+-- short or unestimated):
+--   - any V3.R*-prefixed task with kind='docs' and status='backlog'
+--   - any V3.R*-prefixed task with kind='cleanup' and status='backlog'
+--   - any V3.R*-prefixed task with est_minutes<=45 and status='backlog'
+-- LIMIT 3 from the union; pick smallest est_minutes first. The select-into
+-- pattern stays safe even when the DB has zero matching rows (the UPDATE
+-- simply touches nothing).
+WITH candidates AS (
+  SELECT id
+    FROM tasks
+   WHERE status = 'backlog'
+     AND version_id = 'GDS-V3'
+     AND newcomer_friendly = false
+     AND (
+       kind IN ('cleanup', 'docs')
+       OR (est_minutes IS NOT NULL AND est_minutes <= 45)
+     )
+   ORDER BY COALESCE(est_minutes, 999), id
+   LIMIT 3
+)
+UPDATE tasks SET newcomer_friendly = true, updated_at = now()
+ WHERE id IN (SELECT id FROM candidates);
+
+INSERT INTO schema_migrations (version) VALUES ('039_newcomer_friendly_column')
+  ON CONFLICT (version) DO NOTHING;

package/migrations/040_builder_karma.sql

@@ -0,0 +1,58 @@
+-- V3.R24 (#244) — builders.karma + karma_log table.
+--
+-- Karma is the internal good-citizenship reputation track that sits ALONGSIDE
+-- drachmae (builders.total_credits). Drachmae rewards work shipped (objective:
+-- task verified → credit_log row → builders.total_credits bump). Karma rewards
+-- good citizenship (subjective: voting fairly, surfacing useful ideas, helping
+-- newcomers, getting proposals ratified). Separate track so a builder can see
+-- "I'm a productive shipper" vs "I'm a great teammate" as distinct signals.
+--
+-- Shape mirrors credit_log (see migrations/003_pms.sql §credit_log) exactly:
+-- append-only ledger, cached counter on the builders row, AFTER INSERT trigger
+-- keeps the counter in sync. Differences from credit_log:
+--   * No task_id link (karma is people-shaped, not task-shaped).
+--   * Adds granted_by (nullable builder_id) so manual Archon grants and peer
+--     votes can record WHO drove the delta. NULL = system-attributed (e.g. a
+--     trigger or scheduled job that bumps karma on proposal ratification).
+--
+-- Initial reason vocabulary (free-text but documented):
+--   peer_upvote          — another builder upvoted this builder's idea/comment
+--   peer_downvote        — another builder downvoted (delta is negative)
+--   proposal_ratified    — a proposal this builder authored was ratified
+--   archon_grant         — an Archon manually granted karma (granted_by set)
+-- V4 will add: claude_interaction_signal, player_upvote.
+--
+-- Foundation for R25 (voting UI) and R28 (ratification boost). Cross-refs in
+-- the task description on GDS task #244.
+
+-- 1. Cached counter on builders ---------------------------------------------
+ALTER TABLE builders ADD COLUMN IF NOT EXISTS karma integer NOT NULL DEFAULT 0;
+
+-- 2. Append-only ledger -----------------------------------------------------
+CREATE TABLE IF NOT EXISTS karma_log (
+  id              bigserial PRIMARY KEY,
+  builder_id      bigint NOT NULL REFERENCES builders(id),
+  delta           integer NOT NULL,             -- positive = earned, negative = lost
+  reason          text NOT NULL,                -- 'peer_upvote' | 'peer_downvote' | 'proposal_ratified' | 'archon_grant' | ...
+  recorded_at     timestamptz NOT NULL DEFAULT now(),
+  granted_by      bigint REFERENCES builders(id)  -- NULL = system-attributed
+);
+
+CREATE INDEX IF NOT EXISTS idx_karma_log_builder ON karma_log (builder_id, recorded_at);
+
+-- 3. Keep builders.karma in sync via trigger --------------------------------
+-- Mirrors pms_apply_credit (migrations/003_pms.sql) — same AFTER INSERT shape,
+-- same per-row UPDATE on the cached counter.
+CREATE OR REPLACE FUNCTION gds_apply_karma() RETURNS trigger AS $$
+BEGIN
+  UPDATE builders
+     SET karma = karma + NEW.delta
+   WHERE id = NEW.builder_id;
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+DROP TRIGGER IF EXISTS trg_karma_log_apply ON karma_log;
+CREATE TRIGGER trg_karma_log_apply
+  AFTER INSERT ON karma_log
+  FOR EACH ROW EXECUTE FUNCTION gds_apply_karma();

package/migrations/041_kind_multipliers_and_idea_bonus.sql

@@ -0,0 +1,42 @@
+-- 041_kind_multipliers_and_idea_bonus.sql — V3.R27 (#247).
+--
+-- Per-kind credit multipliers + staged idea-promotion bonus.
+--
+-- The multiplier table lives as a frozen constant in src/bongos/db.js
+-- (KIND_MULTIPLIERS) — NOT in this database. See ADR 0023 for the rationale:
+-- policy values deserve a code-review + commit trail, not an UPDATE on a hot
+-- table. This file exists to:
+--
+--   1. Reserve migration number 041 so the claim allocator advances cleanly.
+--   2. Document the policy at the schema layer so anyone reading the
+--      migrations folder sees the change without having to grep db.js.
+--   3. Tighten the credit_log.reason convention by recording the two new
+--      reason strings ('idea_promotion_bonus' already, 'task.confirmed'
+--      still primary) in a comment so future migrations don't accidentally
+--      collide with them.
+--
+-- Effects on existing data:
+--   - None. All existing credit_log rows are untouched (their `description`
+--     stays NULL; new rows write a "<raw>c × <mult> = <effective>c (<kind>)"
+--     string).
+--   - The credit_log.reason column is text (no CHECK), so 'idea_promotion_bonus'
+--     is accepted without a schema change. The trigger trg_credit_log_apply
+--     fires on every INSERT regardless of reason, so total_credits stays in
+--     sync without modification.
+--
+-- Idempotent: this whole file is comments + counter bump + schema_migrations
+-- INSERT. Re-running it is a no-op.
+
+-- Reason convention (informational, not enforced):
+--   'task.confirmed'        — primary ship payout, kind-multiplied (V3.R27)
+--   'ship.net_negative'     — flat +1 simplification bonus (V3.R93)
+--   'idea_promotion_bonus'  — 25% slice to idea_inbox.captured_by (V3.R27)
+--   'rank_change'           — promotion/demotion stipend (V3.R28)
+--   'task.bonus' / etc.     — legacy/manual adjustments
+
+-- Bump the migration counter past 041 so the next claim that includes
+-- 'migrations/' allocates 042.
+UPDATE migration_counter SET next_number = GREATEST(next_number, 42) WHERE id = 1;
+
+INSERT INTO schema_migrations (version) VALUES ('041_kind_multipliers_and_idea_bonus')
+  ON CONFLICT (version) DO NOTHING;

package/migrations/042_criterion_proposal_workflow.sql

@@ -0,0 +1,78 @@
+-- V3.R31 (#252) — idea_inbox.kind='criterion-proposal' workflow + audit log.
+--
+-- Adds the structured Metic-mode proposal flow. Three deliverables:
+--
+--   1. Extend the idea_inbox.kind CHECK constraint to admit 'criterion-proposal'.
+--      The existing constraint (migration 006) mirrors tasks.kind exactly; a
+--      criterion proposal is *not* a task (it doesn't ship code), so it gets
+--      its own enum value rather than reusing 'feature'/'decision'. Makes the
+--      planning-session skill's Metic-mode writes machine-checkable.
+--
+--   2. Create criterion_proposal_audit — the durable record of who proposed,
+--      who ratified, when, and what the proposal contained. Separate from the
+--      idea_inbox row so the proposal context survives even if the idea row
+--      is later edited (kind changed, title edited, etc.). Two FKs into the
+--      created done_when_criteria row and source idea_inbox row tie everything
+--      together; an Archon can run a "ratification history" report off this
+--      table without joining six other places.
+--
+--   3. NO ratify endpoint yet — that lives in src/bongos/routes/inbox.js. This
+--      migration only ships the schema scaffolding.
+--
+-- Cross-refs:
+--   - karma_log (migration 040): the ratify endpoint INSERTs a row with
+--     reason='proposal_ratified', delta=+5, granted_by=<the archon>.
+--   - planning-session skill: Metic-mode already writes `kind='criterion-proposal'`
+--     bodies as JSON { target_version, criterion_md, sort_order_hint }; this
+--     migration finally makes the CHECK constraint accept it.
+
+BEGIN;
+
+-- 1. Extend idea_inbox.kind CHECK -------------------------------------------
+-- Drop and recreate. The constraint name in migration 006 was inline (no
+-- explicit name), so Postgres autogenerated one. We name it explicitly here
+-- so future migrations can DROP it cleanly.
+DO $$
+DECLARE
+  cname text;
+BEGIN
+  SELECT conname INTO cname
+    FROM pg_constraint
+   WHERE conrelid = 'idea_inbox'::regclass
+     AND contype = 'c'
+     AND pg_get_constraintdef(oid) ILIKE '%kind%IN%';
+  IF cname IS NOT NULL THEN
+    EXECUTE format('ALTER TABLE idea_inbox DROP CONSTRAINT %I', cname);
+  END IF;
+END $$;
+
+ALTER TABLE idea_inbox
+  ADD CONSTRAINT idea_inbox_kind_check
+  CHECK (kind IN (
+    'feature','bug','infra','refactor','spike',
+    'learning-capture','cleanup','decision','blocker-resolution',
+    'unclassified','criterion-proposal'
+  ));
+
+-- 2. Audit log for ratified proposals ---------------------------------------
+CREATE TABLE IF NOT EXISTS criterion_proposal_audit (
+  id                bigserial PRIMARY KEY,
+  idea_id           bigint NOT NULL REFERENCES idea_inbox(id),
+  criterion_id      bigint NOT NULL REFERENCES done_when_criteria(id),
+  proposed_by       bigint REFERENCES builders(id),  -- NULL if idea.captured_by was null
+  ratified_by       bigint NOT NULL REFERENCES builders(id),
+  ratified_at       timestamptz NOT NULL DEFAULT now(),
+  target_version    text NOT NULL REFERENCES versions(id),
+  criterion_md      text NOT NULL,
+  sort_order_hint   integer,                          -- nullable — null means "use max+1"
+  notes_md          text NOT NULL DEFAULT ''
+);
+
+CREATE INDEX IF NOT EXISTS idx_criterion_proposal_audit_idea
+  ON criterion_proposal_audit (idea_id);
+CREATE INDEX IF NOT EXISTS idx_criterion_proposal_audit_criterion
+  ON criterion_proposal_audit (criterion_id);
+CREATE INDEX IF NOT EXISTS idx_criterion_proposal_audit_ratified_at
+  ON criterion_proposal_audit (ratified_at);
+
+COMMIT;