@bongos/core 1.17.0

package/migrations/176_promotion_respects_open_blockers.sql

@@ -0,0 +1,58 @@
+-- 176_promotion_respects_open_blockers.sql — dep-ship auto-promotion must not
+-- un-block a task with an open blocker (V4.R15 / task 953, promotes idea 226).
+--
+-- Bug: the dependency auto-promotion triggers (163) promote a backlog task to
+-- 'ready' the moment its full dep set is done. But a task can sit in 'backlog'
+-- while ALSO carrying an open blocker link (task_blockers -> blockers, status
+-- 'open') — e.g. idea 226: task #859 was backlog + linked to operator-cutover
+-- blocker #13; when its deps shipped, promotion flipped it to 'ready'
+-- (claimable) and silently bypassed the open blocker. A task waiting on a
+-- blocker must stay un-promoted until the blocker resolves (009's
+-- blocker-resolve trigger is what should release it, not a dep ship).
+--
+-- Fix: fold an "no open blocker" check into task_is_fully_unblocked — the shared
+-- predicate every promotion trigger (163: ship / criterion-satisfy /
+-- goal-achieve) re-checks before flipping backlog -> ready. One CREATE OR
+-- REPLACE fixes all three paths and fail-closes any future promotion caller.
+-- The blocker check matches the resolve trigger (009): a blocker is "open" iff
+-- blockers.status = 'open'; legacy markdown-anchor links (blocker_ref text, no
+-- blocker_id row) are not tracked here and behave exactly as before.
+--
+-- Promotion still only ever flips backlog -> ready, so the AFTER triggers can't
+-- recurse. Idempotent: pure CREATE OR REPLACE of the predicate function.
+
+BEGIN;
+
+CREATE OR REPLACE FUNCTION task_is_fully_unblocked(p_task_id bigint)
+RETURNS boolean AS $$
+  SELECT
+    -- (1) no gating dependency edge points at an un-done node …
+    NOT EXISTS (
+      WITH gating AS (
+        SELECT d.to_kind, d.to_id
+          FROM dependencies d
+          JOIN tasks t ON t.id = p_task_id
+         WHERE (d.from_kind = 'task'      AND d.from_id = t.id)
+            OR (d.from_kind = 'goal'      AND d.from_id = t.goal_id)
+            OR (d.from_kind = 'criterion' AND d.from_id IN (
+                  SELECT tc.criterion_id FROM task_criteria tc WHERE tc.task_id = t.id))
+      )
+      SELECT 1
+        FROM gating g
+       WHERE NOT (
+            (g.to_kind = 'task'      AND EXISTS (SELECT 1 FROM tasks              x WHERE x.id = g.to_id AND x.status = 'shipped'))
+         OR (g.to_kind = 'criterion' AND EXISTS (SELECT 1 FROM done_when_criteria x WHERE x.id = g.to_id AND x.satisfied))
+         OR (g.to_kind = 'goal'      AND EXISTS (SELECT 1 FROM goals              x WHERE x.id = g.to_id AND x.status = 'achieved'))
+       )
+    )
+    -- … AND (2) the task has no open blocker linked via task_blockers (V4.R15).
+    AND NOT EXISTS (
+      SELECT 1
+        FROM task_blockers tb
+        JOIN blockers b ON b.id = tb.blocker_id
+       WHERE tb.task_id = p_task_id
+         AND b.status = 'open'
+    );
+$$ LANGUAGE sql STABLE;
+
+COMMIT;

package/migrations/176_ui_discipline.sql

@@ -0,0 +1,40 @@
+-- 176_ui_discipline.sql — task 1376 / GDS-V4: add the `ui` discipline.
+--
+-- The discipline set after migration 086 was:
+--   engineer | artist | ideator | unclassified   (tasks.discipline)
+--   engineer | artist | ideator                  (builders.preferred_disciplines)
+--
+-- This adds a fifth interest area: `ui` — UI/interface DESIGN work (Figma,
+-- Claude-Design, design systems, layout/wireframes). It splits out of the
+-- pixel-art `artist` lane (ADR 0079): producing interface designs is a distinct
+-- discipline from producing pixel-art assets, and it routes to its own /design
+-- work-mode (scripts/gds/discipline-modes.json) instead of /paint.
+--
+-- Purely additive — no data backfill. Existing rows keep their discipline; the
+-- only change is that 'ui' is now an accepted value on both CHECK constraints.
+-- The task-classifier (modules/lifecycle/task-classifier.js) can now assign it,
+-- and POST /tasks accepts it via VALID_DISCIPLINES.
+--
+-- discipline is a text column (not a native enum) and the claimable_tasks /
+-- tasks_session_fit views project it by value, so no view rebuild is needed.
+--
+-- Constraints are dropped before being re-added with the widened set, matching
+-- the pattern in migration 086. Idempotent: safe to re-run.
+
+BEGIN;
+
+-- tasks.discipline — add 'ui' to the accepted set.
+ALTER TABLE tasks DROP CONSTRAINT IF EXISTS tasks_discipline_check;
+ALTER TABLE tasks ADD CONSTRAINT tasks_discipline_check
+  CHECK (discipline IN ('engineer', 'artist', 'ideator', 'ui', 'unclassified'));
+
+-- builders.preferred_disciplines — add 'ui' so a builder can opt into the lane.
+-- (Never carries 'unclassified' — that's a task state, not an interest area.)
+ALTER TABLE builders DROP CONSTRAINT IF EXISTS builders_preferred_disciplines_check;
+ALTER TABLE builders ADD CONSTRAINT builders_preferred_disciplines_check
+  CHECK (preferred_disciplines <@ ARRAY['engineer', 'artist', 'ideator', 'ui']::text[]);
+
+INSERT INTO schema_migrations (version) VALUES ('176_ui_discipline')
+  ON CONFLICT (version) DO NOTHING;
+
+COMMIT;

package/migrations/177_require_reward_before_workable.sql

@@ -0,0 +1,76 @@
+-- 177 require a credits_reward (drachmae) before a task is workable
+-- Applied under task 1670 (GDS-V4 — Require a credits_reward value before a task
+-- can become READY / be CLAIMED). See docs/adr/0096-require-reward-before-workable.md.
+-- Idempotent on re-run.
+--
+-- Problem: tasks.credits_reward defaults to 0 (migration 003). A task could be
+-- promoted to 'ready' and claimed+shipped while paying 0 drachmae. This migration
+-- closes the auto-promote half of the gate (the route + claim halves live in
+-- modules/lifecycle/routes/tasks.js + db.js) and GRANDFATHERS every task that is
+-- ALREADY workable so no currently-claimable work is stranded.
+--
+-- Grandfathering (the critical invariant): there are ~57 'ready' tasks with
+-- credits_reward=0 right now. We must NOT make any of them unclaimable, and must
+-- NOT retro-demote any 'ready' task to backlog.
+--   1. We add a reward_gate_exempt boolean and set it TRUE for every task that is
+--      already at or past 'ready' (ready/active/completed/confirmed/shipped). The
+--      route + claim backstop honor this flag, so existing claimable + in-flight
+--      work is permanently exempt. NEW tasks default the column to FALSE, so the
+--      gate applies only to future promotions/claims.
+--   2. The auto-promote predicate change below only affects FUTURE backlog->ready
+--      evaluations (the triggers fire on later ship/satisfy/achieve events) — it
+--      never re-evaluates a row already in 'ready', so no demotion can occur.
+
+BEGIN;
+
+-- (1) The grandfather flag. Idempotent: ADD COLUMN IF NOT EXISTS.
+ALTER TABLE tasks ADD COLUMN IF NOT EXISTS reward_gate_exempt boolean NOT NULL DEFAULT false;
+
+-- Stamp every task that is already workable (or beyond) as exempt. A clean no-op
+-- on re-run (it only ever sets false->true on the snapshot of already-advanced
+-- rows; a fresh replay re-marks the same set). Backlog/blocked rows are NOT
+-- exempted — going forward they must carry a reward to advance.
+UPDATE tasks
+   SET reward_gate_exempt = true
+ WHERE reward_gate_exempt = false
+   AND status IN ('ready', 'active', 'completed', 'confirmed', 'shipped');
+
+-- (2) The auto-promotion predicate. A task is auto-promotable to 'ready' only when
+-- it is fully dependency-unblocked AND it has something to pay (a positive
+-- credits_reward) OR it is grandfathered. Adding the reward clause here (the single
+-- predicate shared by all three promotion triggers — promote_dependents_on_ship /
+-- _criterion_satisfy / _goal_achieve) keeps unrewarded backlog tasks OUT of 'ready'
+-- without touching any row already in 'ready' (triggers never re-evaluate those).
+CREATE OR REPLACE FUNCTION task_is_fully_unblocked(p_task_id bigint)
+RETURNS boolean AS $$
+  SELECT
+    -- reward gate (task 1670 / ADR 0096): present + positive, or grandfathered.
+    EXISTS (
+      SELECT 1 FROM tasks t
+       WHERE t.id = p_task_id
+         AND (t.reward_gate_exempt = true OR COALESCE(t.credits_reward, 0) > 0)
+    )
+    -- dependency gate (migration 163): NONE of the task's gating edges (own + goal
+    -- + criterion) points at an un-done node. An orphaned `to` yields no EXISTS
+    -- match -> counts as un-done -> task stays blocked (fail-closed).
+    AND NOT EXISTS (
+      WITH gating AS (
+        SELECT d.to_kind, d.to_id
+          FROM dependencies d
+          JOIN tasks t ON t.id = p_task_id
+         WHERE (d.from_kind = 'task'      AND d.from_id = t.id)
+            OR (d.from_kind = 'goal'      AND d.from_id = t.goal_id)
+            OR (d.from_kind = 'criterion' AND d.from_id IN (
+                  SELECT tc.criterion_id FROM task_criteria tc WHERE tc.task_id = t.id))
+      )
+      SELECT 1
+        FROM gating g
+       WHERE NOT (
+            (g.to_kind = 'task'      AND EXISTS (SELECT 1 FROM tasks              x WHERE x.id = g.to_id AND x.status = 'shipped'))
+         OR (g.to_kind = 'criterion' AND EXISTS (SELECT 1 FROM done_when_criteria x WHERE x.id = g.to_id AND x.satisfied))
+         OR (g.to_kind = 'goal'      AND EXISTS (SELECT 1 FROM goals              x WHERE x.id = g.to_id AND x.status = 'achieved'))
+       )
+    );
+$$ LANGUAGE sql STABLE;
+
+COMMIT;

package/migrations/178_reward_gate_auto_assign_revert_autopromote.sql

@@ -0,0 +1,61 @@
+-- 178 reward gate: AUTO-ASSIGN at the gate, revert the migration-177 auto-promote
+-- reward clause.
+--
+-- Applied under task 1673 (GDS-V4 — amend task 1670 / ADR 0096). See the dated
+-- 2026-06-28 amendment in docs/adr/0096-require-reward-before-workable.md.
+-- Idempotent on re-run.
+--
+-- The gate no longer BLOCKS an unrewarded task from becoming workable — it
+-- AUTO-ASSIGNS a capped, audited credits_reward at the promote route + the claim
+-- path (both in modules/lifecycle/{routes/tasks.js,db.js}). Because claim-time
+-- auto-assign covers every task, the auto-promotion predicate no longer needs a
+-- reward clause: migration 177 added `(reward_gate_exempt OR credits_reward > 0)`
+-- to task_is_fully_unblocked; this migration REVERTS that, restoring the
+-- dependency-doneness check ONLY (the migration-163 definition). A deps-shipped
+-- task now auto-promotes backlog->ready even at 0 reward; the claim path assigns a
+-- real value before any work starts.
+--
+-- The reward_gate_exempt column (added by 177) becomes INERT: nothing reads it
+-- anymore (the gate auto-assigns regardless of the flag, so the grandfathered
+-- ~27 tasks earn a fair value when claimed). We leave the column in place — a
+-- later migration may drop it once the backfill (task 1672) is complete. See the
+-- ADR amendment.
+--
+-- No data backfill, no demotion: CREATE OR REPLACE only swaps the predicate body;
+-- the auto-promotion triggers (migration 163) reference the same function and pick
+-- up the reverted body on their next fire. Rows already in 'ready' are never
+-- re-evaluated, so nothing moves.
+
+BEGIN;
+
+-- Revert task_is_fully_unblocked to the migration-163 deps-doneness predicate
+-- (drop the 177 reward-gate clause). TRUE iff NONE of the task's gating edges
+-- (own + goal + criterion) points at an un-done node. An orphaned `to` yields no
+-- EXISTS match -> counts as un-done -> task stays blocked (fail-closed). This is
+-- byte-identical to the 163 body.
+CREATE OR REPLACE FUNCTION task_is_fully_unblocked(p_task_id bigint)
+RETURNS boolean AS $$
+  SELECT NOT EXISTS (
+    WITH gating AS (
+      SELECT d.to_kind, d.to_id
+        FROM dependencies d
+        JOIN tasks t ON t.id = p_task_id
+       WHERE (d.from_kind = 'task'      AND d.from_id = t.id)
+          OR (d.from_kind = 'goal'      AND d.from_id = t.goal_id)
+          OR (d.from_kind = 'criterion' AND d.from_id IN (
+                SELECT tc.criterion_id FROM task_criteria tc WHERE tc.task_id = t.id))
+    )
+    SELECT 1
+      FROM gating g
+     WHERE NOT (
+          (g.to_kind = 'task'      AND EXISTS (SELECT 1 FROM tasks              x WHERE x.id = g.to_id AND x.status = 'shipped'))
+       OR (g.to_kind = 'criterion' AND EXISTS (SELECT 1 FROM done_when_criteria x WHERE x.id = g.to_id AND x.satisfied))
+       OR (g.to_kind = 'goal'      AND EXISTS (SELECT 1 FROM goals              x WHERE x.id = g.to_id AND x.status = 'achieved'))
+     )
+  );
+$$ LANGUAGE sql STABLE;
+
+INSERT INTO schema_migrations (version) VALUES ('178_reward_gate_auto_assign_revert_autopromote')
+  ON CONFLICT (version) DO NOTHING;
+
+COMMIT;

package/migrations/179_search_chunk_usefulness.sql

@@ -0,0 +1,33 @@
+-- 179 search_chunks usefulness signal — record whether a recalled chunk was
+-- actually USED, and let that signal drive ranking (ADR 0095 C3, task 1660).
+--
+-- search_chunks is a CORE-owned table (migration 103_search_chunks.sql), so the
+-- usefulness columns land as a CORE migration here, NOT a module-owned one — a
+-- module migration may only touch its own memory_-namespaced tables (ADR 0083
+-- §Decision #5, enforced by fitness.js). The memory module owns the *queries*
+-- over search_chunks (modules/memory/search.js); core owns the table's schema.
+--
+-- WHY (ADR 0095 C3): nothing tracked whether recalled knowledge actually helped.
+-- A usefulness signal lets high-value chunks rise and dead weight fade, keeping
+-- the recall corpus high-signal as it grows. The signal is two monotonic counters
+-- (a 'useful'/'not_useful' vote — claude-mem's save-result shape: useful vs
+-- dead_end) plus the last-useful timestamp. The recall ranker reads them to apply
+-- a small, bounded multiplicative boost to the RRF fusion score (search.js).
+--
+-- Additive + idempotent: ADD COLUMN IF NOT EXISTS is safe to re-run.
+
+BEGIN;
+
+ALTER TABLE search_chunks
+  -- Times a recall caller marked this chunk as having helped (the 'useful' vote).
+  ADD COLUMN IF NOT EXISTS useful_count     integer     NOT NULL DEFAULT 0,
+  -- Times a caller marked it as NOT helpful / a dead end (the decay vote).
+  ADD COLUMN IF NOT EXISTS not_useful_count integer     NOT NULL DEFAULT 0,
+  -- When the chunk was last marked useful (carried for future time-decay /
+  -- observability; not yet weighted in the ranker).
+  ADD COLUMN IF NOT EXISTS last_useful_at   timestamptz;
+
+INSERT INTO schema_migrations (version) VALUES ('179_search_chunk_usefulness')
+  ON CONFLICT (version) DO NOTHING;
+
+COMMIT;

package/migrations/180_one_active_claim_per_session.sql

@@ -0,0 +1,54 @@
+-- 180_one_active_claim_per_session.sql
+-- task 1642 — DB-level defence-in-depth behind the app-layer guard
+-- (modules/lifecycle/routes/claims.js shouldRefuseSessionClaim).
+--
+-- THE PROBLEM. Working 2+ tasks from one worktree means every commit lands on
+-- the single branch that worktree owns; /builder-ship publishes the whole
+-- branch, so shipping one task drags the other's commits with it (commingled
+-- ships). The cure: a CLI session (≈ one worktree, identified by
+-- creator_session_id) may hold at most ONE active claim at a time.
+--
+-- "Active" is the claims-table convention released_at IS NULL — there is NO
+-- `status` column on `claims` (the task spec's `status='active'` named a column
+-- that doesn't exist on this table; the row's lifecycle lives on `tasks`). The
+-- partial unique index below therefore keys on released_at IS NULL.
+--
+-- creator_session_id IS NOT NULL is essential: a web claim (bind_session=false)
+-- stores a NULL session and is adoptable by any of the builder's CLI sessions —
+-- those must never collide with each other (many NULLs are fine) nor with a
+-- bound CLI claim. The app guard skips NULL sessions for the same reason.
+--
+-- SAFETY — a unique index FAILS to create (and would block deploy) if existing
+-- rows already violate it. Before the CREATE we mop up any pre-existing
+-- duplicate session-bound active claims, keeping the EARLIEST per session and
+-- closing the rest (released_at=now(), outcome='abandoned'). This is the same
+-- "close the dangling claim" shape as migration 174. It is idempotent: a second
+-- run finds no duplicates and closes nothing. The app-layer guard in
+-- modules/lifecycle/routes/claims.js is the AUTHORITATIVE enforcement going
+-- forward; this index is belt-and-braces and must NOT break deploy.
+
+-- Step 1 — heal any current violation so the unique index can be created.
+-- Per session, keep the earliest active bound claim (lowest claimed_at, id as
+-- tiebreak) and close every later one. A NULL creator_session_id is untouched
+-- (PARTITION BY would group all NULLs, so we exclude them from the scan).
+WITH ranked AS (
+  SELECT c.id,
+         ROW_NUMBER() OVER (
+           PARTITION BY c.creator_session_id
+           ORDER BY c.claimed_at, c.id
+         ) AS rn
+    FROM claims c
+   WHERE c.released_at IS NULL
+     AND c.creator_session_id IS NOT NULL
+)
+UPDATE claims c
+   SET released_at = now(),
+       outcome     = COALESCE(c.outcome, 'abandoned')
+  FROM ranked r
+ WHERE c.id = r.id
+   AND r.rn > 1;
+
+-- Step 2 — the teeth: at most one active claim per (non-null) session.
+CREATE UNIQUE INDEX IF NOT EXISTS uniq_active_claim_per_session
+  ON claims (creator_session_id)
+  WHERE released_at IS NULL AND creator_session_id IS NOT NULL;

package/migrations/181_cost_log_skill_name.sql

@@ -0,0 +1,33 @@
+-- 181_cost_log_skill_name.sql — task #385 / V3.R85 follow-up C.
+--
+-- Add skill_name to cost_log so per-skill spend is measurable.
+--
+-- Background
+-- ----------
+-- ADR #304 committed to a cost-per-skill-invocation measurement, but
+-- cost_log has no skill_name column, making it impossible to aggregate
+-- "how much does /idea-triage cost vs /builder-ship". This migration
+-- adds the column. The --skill flag on /builder-cost and the
+-- resolve-skill-model.js helper (task #385 parts A+B) wire it up at the
+-- call site, so a week of data after those land gives us the delta ADR
+-- #304's consequences section requires.
+--
+-- Design
+-- ------
+-- * Nullable. Historical rows and non-skill-invocation costs (infra,
+--   domain, art) carry no skill_name — NULL is correct, not a gap.
+-- * Text, unconstrained to a skills enum. New skills are added to
+--   skill-prefs.js/KNOWN_SKILLS without a migration; the cost_log column
+--   should not require a parallel schema change for each one.
+-- * Index on (skill_name, recorded_at DESC) for the "cost by skill over
+--   time" query shape the ADR #304 consequences analysis will run.
+
+ALTER TABLE cost_log
+  ADD COLUMN IF NOT EXISTS skill_name text;
+
+CREATE INDEX IF NOT EXISTS idx_cost_log_skill_name_recorded
+  ON cost_log (skill_name, recorded_at DESC)
+  WHERE skill_name IS NOT NULL;
+
+INSERT INTO schema_migrations (version) VALUES ('181_cost_log_skill_name')
+  ON CONFLICT (version) DO NOTHING;

package/migrations/184_claim_release_requested.sql

@@ -0,0 +1,25 @@
+-- 184_claim_release_requested.sql — the flag-for-release nudge (task 1736).
+--
+-- A goal owner/manager resolving a task conflict (GET /goals/:id/conflicts →
+-- POST /goals/:id/conflicts/resolve, action 'flag_release') asks the holder of
+-- the task's ACTIVE claim to wrap up or release. The flag is a soft nudge, not
+-- an eviction: nothing about the claim's validity changes; the holder sees it
+-- on their own claim reads (getActiveClaimsForBuilder → /api/gds/me).
+--
+-- Lives in core migrations/ (not modules/lifecycle/migrations/) because it
+-- ALTERs the SHARED claims table — a module migration may only touch its own
+-- namespaced objects (ADR 0083 §Decision #5; the fitness check enforces it).
+--
+-- Purely additive + idempotent; replay-safe on a fresh DB (no data touched).
+
+BEGIN;
+
+ALTER TABLE claims
+  ADD COLUMN IF NOT EXISTS release_requested_by   bigint REFERENCES builders(id),
+  ADD COLUMN IF NOT EXISTS release_requested_at   timestamptz,
+  ADD COLUMN IF NOT EXISTS release_requested_note text;
+
+INSERT INTO schema_migrations (version) VALUES ('184_claim_release_requested')
+  ON CONFLICT (version) DO NOTHING;
+
+COMMIT;

package/migrations/185_module_upstreaming_goal_wiring.sql

@@ -0,0 +1,59 @@
+-- 185_module_upstreaming_goal_wiring.sql
+-- ADR 0107 (task 1766) — wire up the "Module upstreaming & catalog" initiative
+-- and consolidate the ADR-0103 separation spine under its proper goal.
+--
+-- WHY A MIGRATION (not the API): the GDS HTTP API exposes POST /goals and
+-- goal-less POST /tasks (+ dependencies), but has NO endpoint to (a) attach an
+-- existing task to a goal (tasks.goal_id), or (b) reparent an orphan. Those are
+-- SQL-only today (the same gap the ADR-0103 consolidation used migration 182
+-- for). The goal (id 29) and the 7 ecosystem tasks (1767..1773) + their deps were
+-- already created via scripts/gds/seed-module-upstreaming.js; this migration does
+-- only the SQL-only finishing.
+--
+-- ADR 0105 COMPLIANCE: this is a pure MUTATION of existing OTB rows — it INSERTs
+-- NO versions/goals/criteria scope-truth, so it cannot pollute or crash a vanilla
+-- self-host. Every statement is guarded on its OTB anchor existing, so on any DB
+-- that is not this instance it affects ZERO rows (a clean no-op). It is therefore
+-- safe to carry in core migrations/ (where it auto-applies on the OTB deploy),
+-- unlike the seed files ADR 0105 relocated to migrations/instance/. Re-runnable.
+
+BEGIN;
+
+-- 1. Attach the ecosystem tasks (ADR 0107) to goal 29
+--    "Module upstreaming & catalog". No-op unless goal 29 exists (i.e. this is OTB).
+--    1767..1773 = the original 7; 1776 = the hall Modules tab + atlas provenance (§9).
+UPDATE tasks
+   SET goal_id = 29
+ WHERE id IN (1767, 1768, 1769, 1770, 1771, 1772, 1773, 1776)
+   AND EXISTS (SELECT 1 FROM goals WHERE id = 29);
+
+-- 2. Consolidate the ADR-0103 separation spine under G26
+--    "Cloud Bongos productization and self-host": the ADR task (1726),
+--    R88 extract-core (1727), and R89 split-Amazonprimea (1728) were orphaned
+--    (goal_id NULL). R85 (1689) and R86 (1690) already live under G26.
+UPDATE tasks
+   SET goal_id = 26
+ WHERE id IN (1726, 1727, 1728)
+   AND EXISTS (SELECT 1 FROM goals WHERE id = 26);
+
+-- 3. Record the ADR-0103 lineage edge the spine was missing: R88 (extract the
+--    core, 1727) depends on R84 (package-core, 1688 — shipped, so already
+--    satisfied; this only makes the dependency graph match the ADR's spine).
+--    Idempotent via the composite PK.
+--    Cycle-safe: this raw INSERT skips the app-level findDependencyCycle guard,
+--    but a cycle needs 1688 to (transitively) depend on 1727 — no such reverse
+--    edge exists, and 1688 is a shipped/older task whose dep set is settled. The
+--    worst case is not corruption but an un-promotable task (the claim gate
+--    fail-closes), and here the edge is already-satisfied so even that can't occur.
+INSERT INTO dependencies (from_kind, from_id, to_kind, to_id)
+SELECT 'task', 1727, 'task', 1688
+ WHERE EXISTS (SELECT 1 FROM tasks WHERE id = 1727)
+   AND EXISTS (SELECT 1 FROM tasks WHERE id = 1688)
+ON CONFLICT DO NOTHING;
+
+-- Self-register so this file is not re-run (the recent-migration convention;
+-- migrate.sh also backfills with ON CONFLICT, so this is belt-and-suspenders).
+INSERT INTO schema_migrations (version) VALUES ('185_module_upstreaming_goal_wiring')
+ON CONFLICT DO NOTHING;
+
+COMMIT;

package/migrations/187_goal_sort_order.sql

@@ -0,0 +1,30 @@
+-- 187_goal_sort_order.sql — per-version goal priority (task 1760).
+--
+-- goals is a CORE-owned table (created before the module system, ADR 0083
+-- §Decision #5 — a module migration may only touch its OWN <key>_-namespaced
+-- objects, so this schema change lives in core migrations/, not
+-- modules/lifecycle/migrations/, even though the query layer is lifecycle's).
+--
+-- sort_order is the OWNER'S priority ordering WITHIN a version — distinct
+-- from goal.status (lifecycle) and goal.created_at (creation history).
+-- Backfill assigns each existing goal its current (version_id, created_at, id)
+-- rank so the visible order does not jump the moment this migration lands; a
+-- fresh instance with zero goals is a no-op.
+
+BEGIN;
+
+ALTER TABLE goals
+  ADD COLUMN IF NOT EXISTS sort_order integer NOT NULL DEFAULT 0;
+
+WITH ranked AS (
+  SELECT id, row_number() OVER (PARTITION BY version_id ORDER BY created_at, id) - 1 AS rn
+  FROM goals
+)
+UPDATE goals g
+   SET sort_order = ranked.rn
+  FROM ranked
+ WHERE g.id = ranked.id
+   AND g.sort_order = 0
+   AND ranked.rn <> 0;
+
+COMMIT;

package/migrations/187_tasks_kind_check_add_verify.sql

@@ -0,0 +1,21 @@
+-- 187_tasks_kind_check_add_verify.sql
+-- App/DB enum drift fix. The application's VALID_KINDS gained 'verify' (kind='verify'
+-- verification tasks — the ADR-0088/#1053 premature-confirm guard), but the DB
+-- `tasks_kind_check` constraint (added in migration 006) was never updated to match.
+-- So `POST /tasks` with kind='verify' passed app validation, then violated the CHECK
+-- on INSERT and returned 500 create_failed. Surfaced landing the BONGOS-V1 Governance
+-- goal — 4 proof tasks (kind='verify') 500'd and fell back to 'infra'.
+--
+-- Core + platform-universal (a schema constraint every instance needs, NOT OTB
+-- scope-truth) → lives in migrations/ root, applies on every deploy. Idempotent:
+-- drop-if-exists then re-add with the full current kind set (mirrors VALID_KINDS in
+-- modules/lifecycle/task-classifier.js). A drop+re-add re-validates existing rows,
+-- all of which already hold a valid kind.
+
+ALTER TABLE tasks DROP CONSTRAINT IF EXISTS tasks_kind_check;
+ALTER TABLE tasks ADD CONSTRAINT tasks_kind_check
+  CHECK (kind IN (
+    'feature','bug','infra','refactor','spike',
+    'learning-capture','cleanup','decision','blocker-resolution',
+    'verify','unclassified'
+  ));

package/migrations/README.md

@@ -0,0 +1,88 @@
+# Authoring a migration
+
+Schema and data changes live here as `NNN_short_name.sql` files, applied in
+filename order by [`scripts/migrate.sh`](../scripts/migrate.sh) on every deploy
+and tracked by filename stem in the `schema_migrations` table.
+
+**The one rule that has actually bitten us:** a migration may be re-applied
+against a database whose data has *moved on since you wrote it* — a fresh
+restore + replay, or a later migration that renamed a row your migration
+references. So every migration must be a clean no-op on re-run, and any write
+keyed on a **hardcoded natural key** must guard for that key still existing.
+
+## Checklist
+
+- [ ] **Name it with the number reserved by your claim.** `/builder-claim` prints
+      `Migration number reserved for you: NNN`. Use exactly that — the allocator
+      (migration 008) prevents two parallel claims from colliding on a number.
+      Never guess the next number from `ls`.
+- [ ] **Wrap the whole file in `BEGIN; … COMMIT;`** so a mid-file failure rolls
+      back rather than leaving the schema half-migrated.
+- [ ] **Make every statement idempotent.** `migrate.sh` skips files already in
+      `schema_migrations`, but a fresh restore replays the whole folder — and the
+      file must survive that. Use `CREATE TABLE IF NOT EXISTS`,
+      `ALTER TABLE … ADD COLUMN IF NOT EXISTS`, `CREATE OR REPLACE`,
+      `DROP … IF EXISTS`, and `INSERT … ON CONFLICT DO NOTHING`.
+- [ ] **Guard hardcoded natural keys with `WHERE EXISTS`.** Any `INSERT`/`UPDATE`
+      that hardcodes a renameable natural key — a `version_id` like `'GDS-V3'`, a
+      builder login, a criterion slug — must guard on that key still existing, so
+      it's a clean no-op if a later migration renamed or removed it:
+
+      ```sql
+      -- Guarded so a fresh restore + replay (or a post-rename DB) is a no-op,
+      -- never a FK violation.
+      INSERT INTO done_when_criteria (version_id, cnum, criterion_md)
+      SELECT 'GDS-V3', 1, '…'
+      WHERE EXISTS (SELECT 1 FROM versions WHERE id = 'GDS-V3')
+      ON CONFLICT DO NOTHING;
+
+      UPDATE versions SET done_when = '…'
+      WHERE id = 'GDS-V3'
+        AND EXISTS (SELECT 1 FROM versions WHERE id = 'GDS-V3');
+      ```
+
+      Why this is a real rule and not paranoia: migration `<redacted>`
+      hardcoded `version_id = 'PMS-V3'`; migration `019` then renamed that id to
+      `'GDS-V3'`. On the next fresh replay, 018 ran against a DB where `PMS-V3` no
+      longer existed and the deploy broke. The fix was a `WHERE EXISTS` guard on
+      every statement (see the head of
+      [`<redacted>.sql`](<redacted>.sql)). Prefer a
+      per-statement `WHERE EXISTS` over a `DO`-block guard — a `DO` block can't
+      short-circuit the rest of the file.
+- [ ] **Don't `DELETE` rows that other tables reference.** Soft-revoke instead
+      (e.g. set `revoked_at = now()` on sessions rather than deleting — `claims`
+      has an FK). See the LarsCode reset session log for the pattern.
+- [ ] **Self-registration is automatic.** `migrate.sh` writes the
+      `schema_migrations` row itself with `ON CONFLICT DO NOTHING` after a
+      successful apply, so you do **not** need a trailing
+      `INSERT INTO schema_migrations …` — but one is harmless if you copy an old
+      file that has it.
+- [ ] **ASCII only in files read by cloud-init / shell wrappers.** Not a migration
+      issue per se, but the same "silently discarded on a stray byte" failure mode
+      bit `builder-box-cloud-init.yaml` (learning 48) — keep migrations ASCII too.
+- [ ] **Test idempotence locally before shipping.** Apply, then apply again:
+
+      ```sh
+      scripts/migrate.sh        # apply NNN
+      scripts/migrate.sh        # must print "skip NNN (already applied)" and exit 0
+      ```
+
+      For the restore-replay path, drop the `schema_migrations` row for your file
+      and re-run — it must be a clean no-op, not an error.
+
+## Anatomy of a migration file
+
+```sql
+-- NNN short human description
+-- Applied under claim <id> (task <id>, <rank prefix> — <title>).
+-- Idempotent on re-run.
+
+BEGIN;
+
+-- … guarded, idempotent statements …
+
+COMMIT;
+```
+
+The header comment is convention, not enforced — but it's how `git blame` and the
+audit trail tie a schema change back to the task that justified it.

package/migrations/core_188_goal_visibility_and_membership_requests.sql

@@ -0,0 +1,71 @@
+-- core_188_goal_visibility_and_membership_requests.sql — private goals + the
+-- invite / join-request model (task 1951, ADR 0112).
+--
+-- Adds goal PRIVACY plus the two-sided membership-request queue a private goal
+-- needs. A goal's `visibility` is 'public' (default = today's open-join) or
+-- 'private'; a private goal stays VISIBLE in the goal list but non-members can't
+-- self-join — they are INVITED (and accept) or REQUEST to join (approved by an
+-- owner/manager/Archon). goal_membership_requests is the pending queue for BOTH
+-- directions — the access_requests approval-queue pattern (modules/onboarding)
+-- applied to goal membership.
+--
+-- goals is a CORE-owned table (created in 160_goal_tier; ADR 0083 §Decision 5 —
+-- a module migration may touch only its own <key>_ objects), so these changes
+-- live in core migrations/, core_-namespaced (ADR 0108 §5: a new core migration
+-- numbered above LEGACY_BARE_CORE_MAX=187 must be core_-prefixed, else the
+-- fitness namespacing check reds the build).
+--
+-- PURELY ADDITIVE + idempotent: the new column defaults 'public' so every
+-- existing goal keeps today's behaviour, and the new table/indexes are IF NOT
+-- EXISTS. Fresh-DB-replay safe; no hard-coded builder ids (learning 1238).
+-- migrate.sh records this file's stem in schema_migrations (the modern 187
+-- pattern — the file does not self-insert).
+
+BEGIN;
+
+-- 1. Goal privacy. Default 'public' = today's open-join semantics, unchanged.
+ALTER TABLE goals
+  ADD COLUMN IF NOT EXISTS visibility text NOT NULL DEFAULT 'public'
+    CHECK (visibility IN ('public', 'private'));
+
+-- 2. The membership-request queue — one row per pending (or resolved) ask, in
+--    EITHER direction:
+--      kind='invite'  — a goal owner/manager asked builder_id to join; the
+--                       invitee accepts/declines it from their inbox.
+--      kind='request' — builder_id asked to join a (private) goal; an
+--                       owner/manager/Archon approves/denies it.
+--    created_by is who OPENED the row (the manager for an invite; the builder
+--    themselves for a request); resolved_by is who closed it. Terminal states:
+--    'accepted' (→ membership added), 'rejected' (declined/denied),
+--    'cancelled' (withdrawn/rescinded by the opener).
+CREATE TABLE IF NOT EXISTS goal_membership_requests (
+  id           bigserial PRIMARY KEY,
+  goal_id      bigint NOT NULL REFERENCES goals(id) ON DELETE CASCADE,
+  builder_id   bigint NOT NULL REFERENCES builders(id) ON DELETE CASCADE,
+  kind         text NOT NULL CHECK (kind IN ('invite', 'request')),
+  status       text NOT NULL DEFAULT 'pending'
+                 CHECK (status IN ('pending', 'accepted', 'rejected', 'cancelled')),
+  note         text,
+  created_by   bigint REFERENCES builders(id),
+  resolved_by  bigint REFERENCES builders(id),
+  created_at   timestamptz NOT NULL DEFAULT now(),
+  resolved_at  timestamptz,
+  updated_at   timestamptz NOT NULL DEFAULT now()
+);
+
+-- At most ONE pending ask per (goal, builder): an invite and a request can't
+-- both be open for the same person on the same goal, and neither can pile up
+-- duplicates (the access_requests partial-unique precedent). Resolved rows stay
+-- as the audit trail and never block a later re-ask.
+CREATE UNIQUE INDEX IF NOT EXISTS uniq_goal_membership_requests_pending
+  ON goal_membership_requests (goal_id, builder_id)
+  WHERE status = 'pending';
+
+-- Inbox reads: "my pending invites/requests" (builder_id) and "this goal's
+-- pending queue" (goal_id, status).
+CREATE INDEX IF NOT EXISTS idx_goal_membership_requests_builder
+  ON goal_membership_requests (builder_id, status);
+CREATE INDEX IF NOT EXISTS idx_goal_membership_requests_goal
+  ON goal_membership_requests (goal_id, status);
+
+COMMIT;