@bongos/core 1.17.0

package/migrations/003_pms.sql

@@ -0,0 +1,284 @@
+-- 003_pms.sql — Project management system schema
+--
+-- Tables for builders (people), versions (game V1, PMS-V1, ...),
+-- tasks, claims (atomic safety), cost_log, credit_log, builder_sessions
+-- (GitHub auth), and session_logs (per-task work entries).
+--
+-- See docs/adr/0010-pms-architecture.md for the rationale.
+-- See limitations/pms-v1.md for what PMS-V1 ships.
+--
+-- Idempotent: safe to re-run.
+
+-- =========================================================================
+-- builders — one row per human (or AI) who can claim and ship tasks
+-- =========================================================================
+CREATE TABLE IF NOT EXISTS builders (
+  id              bigserial PRIMARY KEY,
+  -- GitHub user.id (numeric), as a string for portability
+  github_id       text NOT NULL UNIQUE,
+  -- GitHub login (display handle, can change — github_id is the stable key)
+  github_login    text NOT NULL,
+  display_name    text NOT NULL,
+  avatar_url      text,
+  created_at      timestamptz NOT NULL DEFAULT now(),
+  -- Cached for cheap leaderboard reads; authoritative source is sum(credit_log.delta)
+  total_credits   integer NOT NULL DEFAULT 0
+);
+
+CREATE INDEX IF NOT EXISTS idx_builders_total_credits ON builders (total_credits DESC);
+
+-- =========================================================================
+-- versions — internal AND product tracks (game V1, PMS-V1, V2, etc.)
+-- =========================================================================
+CREATE TABLE IF NOT EXISTS versions (
+  -- short id like 'V1', 'V2', 'PMS-V1', 'PMS-V2'
+  id              text PRIMARY KEY,
+  name            text NOT NULL,
+  -- 'product' = player-facing game version; 'internal' = infrastructure track
+  track           text NOT NULL CHECK (track IN ('product', 'internal')),
+  status          text NOT NULL CHECK (status IN ('planning', 'building', 'shipped', 'frozen')),
+  scope_doc_path  text,        -- e.g. 'limitations/current-version.md'
+  started_at      timestamptz NOT NULL DEFAULT now(),
+  shipped_at      timestamptz,
+  -- Free-text "what shipping this version means"; rendered on the public status page
+  done_when       text
+);
+
+-- =========================================================================
+-- tasks — work units. The core of the PMS.
+-- =========================================================================
+CREATE TABLE IF NOT EXISTS tasks (
+  id              bigserial PRIMARY KEY,
+  version_id      text NOT NULL REFERENCES versions(id),
+  title           text NOT NULL,
+  -- markdown allowed
+  description     text NOT NULL DEFAULT '',
+  status          text NOT NULL DEFAULT 'backlog'
+                  CHECK (status IN ('backlog', 'ready', 'active', 'blocked', 'shipped', 'abandoned')),
+
+  -- Parallel-safety fingerprint. Each entry is a path or path-prefix
+  -- (e.g. 'src/pms/', 'public/game/scenes/WorldScene.js').
+  -- Two tasks are parallel-safe iff their touches arrays are disjoint.
+  touches         text[] NOT NULL DEFAULT '{}',
+
+  -- Tags (Lars's request): time, cost, manual-degree, priority, automation.
+  est_minutes     integer,                  -- self-reported wall-clock estimate
+  est_cost_usd    numeric(10,4),            -- expected API/infra spend
+  manual_degree   integer CHECK (manual_degree BETWEEN 1 AND 5),
+                                            -- 1 = fully automated; 5 = needs Lars present
+  priority        integer CHECK (priority BETWEEN 1 AND 5),
+                                            -- 1 = critical to ship; 5 = nice-to-have
+  automation_tag  text CHECK (automation_tag IN ('overnight-safe', 'needs-input', 'live-only')),
+  credits_reward  integer NOT NULL DEFAULT 0,
+
+  -- Provenance + lifecycle
+  source          text,                     -- 'backlog-import' | 'chat-inbox' | 'session' | 'manual'
+  source_ref      text,                     -- e.g. 'backlog.md#visible-other-players'
+  promoted_at     timestamptz,
+  shipped_at      timestamptz,
+  shipped_by      bigint REFERENCES builders(id),
+  -- Public-facing one-line summary of value delivered, shown on status.amazonprimea.com.
+  value_summary   text,
+
+  created_at      timestamptz NOT NULL DEFAULT now(),
+  updated_at      timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS idx_tasks_version_status ON tasks (version_id, status);
+CREATE INDEX IF NOT EXISTS idx_tasks_priority ON tasks (priority);
+CREATE INDEX IF NOT EXISTS idx_tasks_touches_gin ON tasks USING gin (touches);
+
+-- Auto-bump updated_at
+CREATE OR REPLACE FUNCTION pms_touch_updated_at() RETURNS trigger AS $$
+BEGIN
+  NEW.updated_at = now();
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+DROP TRIGGER IF EXISTS trg_tasks_updated_at ON tasks;
+CREATE TRIGGER trg_tasks_updated_at
+  BEFORE UPDATE ON tasks
+  FOR EACH ROW EXECUTE FUNCTION pms_touch_updated_at();
+
+-- =========================================================================
+-- task_blockers — many-to-many: task ↔ blocker entry (markdown anchor)
+-- =========================================================================
+CREATE TABLE IF NOT EXISTS task_blockers (
+  task_id         bigint NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+  -- e.g. 'blockers/blockers.md#stripe-credentials' — markdown is canonical
+  blocker_ref     text NOT NULL,
+  PRIMARY KEY (task_id, blocker_ref)
+);
+
+-- =========================================================================
+-- claims — atomic concurrency safety. One active claim per task.
+-- =========================================================================
+CREATE TABLE IF NOT EXISTS claims (
+  id              bigserial PRIMARY KEY,
+  task_id         bigint NOT NULL REFERENCES tasks(id),
+  builder_id      bigint NOT NULL REFERENCES builders(id),
+  worktree_name   text,                     -- e.g. 'bold-shannon-21f38e' — for context only
+  claimed_at      timestamptz NOT NULL DEFAULT now(),
+  released_at     timestamptz,              -- NULL = still active
+  outcome         text CHECK (outcome IN ('shipped', 'abandoned', 'partial', 'expired'))
+);
+
+-- The teeth of the claim system: at most one active claim per task.
+-- A second concurrent INSERT will fail with a clean unique-violation,
+-- which the API catches and returns as "already claimed."
+CREATE UNIQUE INDEX IF NOT EXISTS uniq_active_claim_per_task
+  ON claims (task_id) WHERE released_at IS NULL;
+
+CREATE INDEX IF NOT EXISTS idx_claims_builder_active
+  ON claims (builder_id) WHERE released_at IS NULL;
+
+-- =========================================================================
+-- cost_log — money spent (API, infra, art, other). Optionally task-attributed.
+-- =========================================================================
+CREATE TABLE IF NOT EXISTS cost_log (
+  id              bigserial PRIMARY KEY,
+  task_id         bigint REFERENCES tasks(id),  -- NULL for non-task spend (infra, domain, etc.)
+  amount_usd      numeric(10,4) NOT NULL,
+  category        text NOT NULL CHECK (category IN
+    ('api', 'compute', 'infra', 'domain', 'art', 'other')),
+  description     text,
+  source          text,                          -- 'art-cost-ledger' | 'manual' | 'anthropic-api' | ...
+  source_ref      text,                          -- e.g. 'art/iterations/cost_ledger.jsonl#L142'
+  recorded_at     timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS idx_cost_log_recorded ON cost_log (recorded_at);
+CREATE INDEX IF NOT EXISTS idx_cost_log_task ON cost_log (task_id);
+CREATE INDEX IF NOT EXISTS idx_cost_log_category ON cost_log (category);
+
+-- =========================================================================
+-- credit_log — append-only ledger. builders.total_credits is a cache.
+-- =========================================================================
+CREATE TABLE IF NOT EXISTS credit_log (
+  id              bigserial PRIMARY KEY,
+  builder_id      bigint NOT NULL REFERENCES builders(id),
+  task_id         bigint REFERENCES tasks(id),
+  delta           integer NOT NULL,             -- positive = earned, negative = spent (future)
+  reason          text NOT NULL,                -- 'task.shipped' | 'task.bonus' | 'redemption' | ...
+  recorded_at     timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS idx_credit_log_builder ON credit_log (builder_id, recorded_at);
+
+-- Keep builders.total_credits in sync via trigger
+CREATE OR REPLACE FUNCTION pms_apply_credit() RETURNS trigger AS $$
+BEGIN
+  UPDATE builders
+     SET total_credits = total_credits + NEW.delta
+   WHERE id = NEW.builder_id;
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+DROP TRIGGER IF EXISTS trg_credit_log_apply ON credit_log;
+CREATE TRIGGER trg_credit_log_apply
+  AFTER INSERT ON credit_log
+  FOR EACH ROW EXECUTE FUNCTION pms_apply_credit();
+
+-- =========================================================================
+-- builder_sessions — auth tokens (GitHub-derived)
+-- =========================================================================
+CREATE TABLE IF NOT EXISTS builder_sessions (
+  id              bigserial PRIMARY KEY,
+  builder_id      bigint NOT NULL REFERENCES builders(id),
+  -- 64+ char random hex; sent by clients as a Bearer token
+  token           text NOT NULL UNIQUE,
+  -- 'cli' (slash commands) or 'web' (/builders page)
+  source          text NOT NULL CHECK (source IN ('cli', 'web')),
+  user_agent      text,
+  created_at      timestamptz NOT NULL DEFAULT now(),
+  last_used_at    timestamptz NOT NULL DEFAULT now(),
+  expires_at      timestamptz,                  -- NULL = no expiry (CLI tokens default to no expiry)
+  revoked_at      timestamptz
+);
+
+CREATE INDEX IF NOT EXISTS idx_builder_sessions_token ON builder_sessions (token);
+CREATE INDEX IF NOT EXISTS idx_builder_sessions_builder ON builder_sessions (builder_id);
+
+-- =========================================================================
+-- session_logs — per-task work entries (the "what I did" record)
+-- =========================================================================
+CREATE TABLE IF NOT EXISTS session_logs (
+  id              bigserial PRIMARY KEY,
+  builder_id      bigint NOT NULL REFERENCES builders(id),
+  task_id         bigint REFERENCES tasks(id),
+  claim_id        bigint REFERENCES claims(id),
+  worktree_name   text,
+  started_at      timestamptz NOT NULL,
+  ended_at        timestamptz NOT NULL,
+  outcome         text NOT NULL CHECK (outcome IN ('shipped', 'partial', 'abandoned')),
+  notes_md        text,                         -- handoff-template-shaped markdown
+  -- Confidence tag at session-end (verified-prod / verified-smoke / implemented-not-verified)
+  confidence      text CHECK (confidence IN ('verified-prod', 'verified-smoke', 'implemented-not-verified', 'na'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_session_logs_task ON session_logs (task_id);
+CREATE INDEX IF NOT EXISTS idx_session_logs_builder ON session_logs (builder_id);
+CREATE INDEX IF NOT EXISTS idx_session_logs_ended ON session_logs (ended_at);
+
+-- =========================================================================
+-- Seed: the two known versions
+-- =========================================================================
+-- Instance-seed guard (task 1704 / ADR 0105): these are OTB product versions —
+-- scope-truth that must NOT seed onto a vanilla / non-owning DB. scripts/migrate.sh
+-- sets app.seed_instance_data='off' on such a boot; unset (direct psql / OTB) = seed.
+DO $seed$ BEGIN IF current_setting('app.seed_instance_data', true) IS DISTINCT FROM 'off' THEN
+INSERT INTO versions (id, name, track, status, scope_doc_path, started_at, done_when)
+VALUES
+  ('V1', 'Game V1 — first playable purchase loop', 'product', 'building',
+   'limitations/current-version.md', '2026-05-08'::timestamptz,
+   'A visitor can land in the world, walk to the vendor, buy a real item, and Hermeslines fulfills it.'),
+  ('PMS-V1', 'PMS V1 — project management system, parallel internal track', 'internal', 'building',
+   'limitations/pms-v1.md', '2026-05-09'::timestamptz,
+   'Builders auth via GitHub. Slash commands claim/ship tasks atomically. Backlog migrated. Public status page live.')
+ON CONFLICT (id) DO NOTHING;
+END IF; END $seed$;
+
+-- =========================================================================
+-- Helper view: claimable_tasks
+-- =========================================================================
+-- Tasks that are status='ready', not blocked, and whose touches[] does
+-- not overlap with any currently-active claim. Used by /builder-start.
+CREATE OR REPLACE VIEW claimable_tasks AS
+SELECT t.*
+  FROM tasks t
+ WHERE t.status = 'ready'
+   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    -- array-overlap operator
+   );
+
+-- =========================================================================
+-- Helper view: version_progress
+-- =========================================================================
+-- For status.amazonprimea.com. Counts shipped vs total per version,
+-- weighted by priority (lower priority number = more weight).
+CREATE OR REPLACE VIEW version_progress AS
+SELECT v.id AS version_id,
+       v.name,
+       v.track,
+       v.status,
+       count(*) FILTER (WHERE t.status = 'shipped') AS shipped_count,
+       count(*) AS total_count,
+       COALESCE(SUM(CASE WHEN t.status = 'shipped'
+                         THEN (6 - COALESCE(t.priority, 5))
+                         ELSE 0 END), 0) AS shipped_weight,
+       COALESCE(SUM(6 - COALESCE(t.priority, 5)), 0) AS total_weight
+  FROM versions v
+  LEFT JOIN tasks t ON t.version_id = v.id
+ GROUP BY v.id, v.name, v.track, v.status;
+
+INSERT INTO schema_migrations (version) VALUES ('003_pms')
+  ON CONFLICT (version) DO NOTHING;

package/migrations/004_pms_cost_idempotency.sql

@@ -0,0 +1,13 @@
+-- 004_pms_cost_idempotency.sql
+-- Make cost_log idempotent: same (source, source_ref) pair can only be inserted once.
+-- This unblocks safe re-runs of backfill scripts (e.g. art ledger, future automated cost feeds).
+--
+-- The index is partial — only enforced when BOTH source and source_ref are non-null —
+-- so manual cost entries (which often omit one or both) remain unrestricted.
+
+CREATE UNIQUE INDEX IF NOT EXISTS uniq_cost_log_source_ref
+  ON cost_log (source, source_ref)
+  WHERE source IS NOT NULL AND source_ref IS NOT NULL;
+
+INSERT INTO schema_migrations (version) VALUES ('004_pms_cost_idempotency')
+  ON CONFLICT (version) DO NOTHING;

package/migrations/005_pms_smoke_filter.sql

@@ -0,0 +1,44 @@
+-- 005_pms_smoke_filter.sql
+-- Filter synthetic smoke-test tasks (title LIKE '__smoke__%') from public surfaces
+-- so the smoke harness can exercise the write path in production without
+-- polluting the dashboard, the claimable-tasks list, or the progress meter.
+
+DROP VIEW IF EXISTS claimable_tasks;
+DROP VIEW IF EXISTS version_progress;
+
+CREATE VIEW version_progress AS
+SELECT v.id AS version_id,
+       v.name,
+       v.track,
+       v.status,
+       count(*) FILTER (WHERE t.status = 'shipped') AS shipped_count,
+       count(*) AS total_count,
+       COALESCE(sum(
+         CASE WHEN t.status = 'shipped' THEN 6 - COALESCE(t.priority, 5) ELSE 0 END
+       ), 0)::bigint AS shipped_weight,
+       COALESCE(sum(6 - COALESCE(t.priority, 5)), 0)::bigint AS total_weight
+  FROM versions v
+  LEFT JOIN tasks t
+    ON t.version_id = v.id
+   AND (t.title IS NULL OR t.title NOT LIKE '\_\_smoke\_\_%' ESCAPE '\')
+ GROUP BY v.id, v.name, v.track, v.status;
+
+CREATE VIEW claimable_tasks AS
+SELECT id, version_id, title, description, status, touches,
+       est_minutes, est_cost_usd, manual_degree, priority,
+       automation_tag, credits_reward, source, source_ref,
+       promoted_at, shipped_at, shipped_by, value_summary,
+       created_at, updated_at
+  FROM tasks t
+ WHERE status = 'ready'
+   AND 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
+   );
+
+INSERT INTO schema_migrations (version) VALUES ('005_pms_smoke_filter')
+  ON CONFLICT (version) DO NOTHING;