@bongos/core 1.17.0

package/modules/ideas/CLAUDE.md

@@ -0,0 +1,37 @@
+# `ideas` module — the idea inbox + blockers + the `ideas.capture` kernel port
+
+> The **fourth CORE-domain** carved into a module (BV1.R78, [ADR 0093](../../docs/adr/<redacted>.md) §1) — after memory (R72), grading (R73), and economy (R77). A clean, self-contained slice: its SQL already lived in dedicated `inbox.js`/`blockers.js` files (not the `db.js` monolith), so the carve is a move + a doorway re-point, OTB byte-identical. `default: true` in `module.json` — every instance captures ideas and tracks what's stuck on its owner, so it mounts unconditionally unless explicitly disabled.
+
+Owns the **methodology intake surfaces** that feed the backlog: the `idea_inbox` (free-form capture → triage → promote/discard/merge, plus the Metic-proposes / Archon-ratifies `criterion-proposal` flow that writes `done_when_criteria`), and the `blockers` queue (a thing stuck on a human; resolving one auto-promotes its linked `blocked` tasks via a DB trigger).
+
+## The boundary (the one rule)
+
+This module reaches core **only** through the published doorway `../../src/module-api.js` (`coreVersion ^1.8.0` — it needs the R78 doorway addition `parseId`, the route-param validator alongside `validateOrRespond`/`LIMITS`). It must **never** `require()` a core internal directly, and never another module. Core, in turn, must never `require()` a file in here — it reaches ideas only through the `ideas.capture` port (below). Both directions are enforced by the BV1.R44/R45 fitness checks.
+
+## The `ideas.capture` kernel PORT (ADR 0093 §5 — the headline of this carve)
+
+- **Provides — port `ideas.capture`** → `inbox.captureIdea`. Registered in `routes/inbox.js`'s factory (the loader runs it at boot, and again whenever a test rebuilds the GDS router — `hasProvider`-guarded so re-instantiation never trips the single-provider duplicate guard). Mirrors `modules/economy/routes/reward.js` (a capability registered from a route factory).
+- **It retires the `captureIdea` doorway leak.** ADR 0091 §3 parked `captureIdea` on `src/module-api.js` as a temporary "domain-leak-pending-carve" because the ideas domain wasn't a module yet. This carve deletes that re-export; the discord `#ideas` inbound (`modules/discord/discord-inbound.js`, the **sole** consumer) now resolves `ideas.capture` at call time instead of importing the doorway helper. This is the codebase's **first module→module port** (every prior port is consumed by core); discord declares it in `consumes`.
+- **Why a verb-noun port, not a doorway re-export:** the same reason `grade`/`reward` are ports — a module capability another module invokes goes behind the kernel switchboard, never a direct import (ADR 0091 §4).
+
+## Files
+
+| File | What |
+|---|---|
+| `inbox.js` | the `idea_inbox` domain: `captureIdea` (the port provider) + the keyword `classify` fallback, `listOpenIdeas`/`getIdea`/`countOpenIdeas` (with the V3.R70 skill-friction rank-visibility gate), `updateIdea`, and the `ratifyCriterionProposal` transaction (criterion-proposal → `done_when_criteria` + `karma_log` + `criterion_proposal_audit`, all in one `pool.connect()` tx). Reaches the shared pool through the doorway. |
+| `blockers.js` | the `blockers` domain: `listOpenBlockers`/`getBlocker`/`createBlocker`/`resolveBlocker`/`linkBlockerToTask`. `resolveBlocker` relies on the DB trigger on `blockers.status` to auto-promote linked `blocked` tasks. |
+| `routes/inbox.js` | `POST/GET /inbox`, `GET /inbox/:id`, `PATCH /inbox/:id` (Metic+ triage), `POST /inbox/:id/ratify` (Archon). Its factory **registers the `ideas.capture` port**. |
+| `routes/blockers.js` | `GET /blockers` (**public** — the status page reads it), `GET /blockers/:id`, `POST /blockers` (any builder files), `POST /blockers/:id/{resolve,link}` (Metic+). |
+
+## NOT in this module (deliberately left in core)
+
+- **The public idea/blocker projections** — `routes/public.js` (`projectPublicIdea`/`projectPublicBlocker`) reads `idea_inbox`/`blockers` with its **own** inline `pool.query` SELECTs (existence/ref checks for the hall's `#NNN` deep-link resolver + the public sitemap). Core querying a shared table with its own SQL is allowed; it does **not** import this module, so there is no vendored twin to keep in sync — the boundary is about code imports, not table access.
+- **The ideas/blockers CLIs** — `scripts/gds/{capture,triage,render-ideas}.js` travel with the domain but stay under `scripts/`; they now `require('../../modules/ideas/inbox')` (the economy/memory CLI precedent — `scripts/gds/autonomy-gate.js` does the same for its idea-inbox read).
+
+## Tables
+
+None owned. `idea_inbox`, `blockers`, `task_blockers`, `criterion_proposal_audit` (+ the `done_when_criteria`/`karma_log` rows the ratify tx touches) were created before the module system and stay in core `migrations/` (the `schema_migrations` stem-key makes a later relocation a no-op). The module owns the *queries*; any **new** ideas migration belongs in `modules/ideas/migrations/` namespaced `ideas_*` (the additive rule).
+
+## Tests
+
+`tests/criterion_proposal.mjs` imports `modules/ideas/inbox` (the ratify transaction). `tests/discord_inbound.mjs` exercises the consumer (it injects a stub `captureIdea` via dependency injection, so it never hits the real port). `tests/route_validation.mjs` exercises the inbox/blocker write-schemas via the dependency-free `validate()` helper (it imports `_helpers`, not these routes). The doorway-surface contract (`tests/module_api.mjs`) asserts `captureIdea` is **gone** and `parseId` is present. See ADR 0093.

package/modules/ideas/blockers.js

@@ -0,0 +1,100 @@
+// Blockers — DB-canonical replacement for blockers/blockers.md (Phase 2a).
+//
+// A blocker is a thing stuck on a human (typically Lars). When a blocker
+// resolves, a trigger on the blockers table auto-promotes every task linked
+// via task_blockers from 'blocked' → 'ready'.
+//
+// Carved into modules/ideas/ (BV1.R78 / ADR 0093 §1): reaches the shared pool
+// through the published doorway (src/module-api.js). OTB byte-identical.
+
+const { pool } = require('../../src/module-api');
+
+async function listOpenBlockers() {
+  const { rows } = await pool.query(
+    `SELECT b.id, b.title, b.body_md, b.status, b.created_at,
+            b.source, b.source_ref,
+            COALESCE(
+              (SELECT array_agg(tb.task_id ORDER BY tb.task_id)
+                 FROM task_blockers tb WHERE tb.blocker_id = b.id),
+              ARRAY[]::bigint[]
+            ) AS blocking_task_ids
+       FROM blockers b
+      WHERE b.status = 'open'
+      ORDER BY b.id`
+  );
+  return rows;
+}
+
+async function getBlocker(id) {
+  const { rows } = await pool.query(
+    `SELECT id, title, body_md, status, created_at, resolved_at, resolved_by, resolution_note,
+            source, source_ref
+       FROM blockers WHERE id = $1`,
+    [id]
+  );
+  return rows[0] || null;
+}
+
+// Idempotent: if (source, source_ref) is already taken, ON CONFLICT skips.
+// Returns the row when inserted, null when skipped.
+async function createBlocker({ title, bodyMd, source, sourceRef }) {
+  if (!title) {
+    const e = new Error('title is required');
+    e.code = 'TITLE_REQUIRED';
+    throw e;
+  }
+  const { rows } = await pool.query(
+    `INSERT INTO blockers (title, body_md, source, source_ref)
+     VALUES ($1, $2, $3, $4)
+     ON CONFLICT (source, source_ref) WHERE source IS NOT NULL AND source_ref IS NOT NULL
+       DO NOTHING
+     RETURNING id, title, body_md, status, created_at, source, source_ref`,
+    [title, bodyMd ?? '', source ?? null, sourceRef ?? null]
+  );
+  return rows[0] || null;
+}
+
+// Resolve a blocker. The trigger on blockers.status flips linked tasks
+// from 'blocked' → 'ready' atomically.
+async function resolveBlocker({ id, builderId, resolutionNote }) {
+  const { rows } = await pool.query(
+    `UPDATE blockers
+        SET status = 'resolved',
+            resolved_by = $2,
+            resolution_note = $3
+      WHERE id = $1 AND status = 'open'
+      RETURNING id, title, status, resolved_at, resolved_by, resolution_note`,
+    [id, builderId, resolutionNote ?? null]
+  );
+  if (rows.length === 0) {
+    const e = new Error('blocker not found or already resolved');
+    e.code = 'BLOCKER_NOT_OPEN';
+    throw e;
+  }
+  // After-the-fact: count how many tasks the trigger just promoted.
+  const { rows: promoted } = await pool.query(
+    `SELECT id, title FROM tasks
+      WHERE id IN (SELECT task_id FROM task_blockers WHERE blocker_id = $1)
+        AND status = 'ready'`,
+    [id]
+  );
+  return { blocker: rows[0], promoted_tasks: promoted };
+}
+
+// Link a blocker to a task (lives in task_blockers via the new blocker_id col).
+async function linkBlockerToTask({ blockerId, taskId }) {
+  await pool.query(
+    `INSERT INTO task_blockers (task_id, blocker_id, blocker_ref)
+     VALUES ($1, $2, $3)
+     ON CONFLICT DO NOTHING`,
+    [taskId, blockerId, `blocker:${blockerId}`]
+  );
+}
+
+module.exports = {
+  listOpenBlockers,
+  getBlocker,
+  createBlocker,
+  resolveBlocker,
+  linkBlockerToTask,
+};

package/modules/ideas/inbox.js

@@ -0,0 +1,459 @@
+// GDS idea_inbox helpers — structured replacement for free-form generative-ideas.md.
+//
+// Schema (migration 006_pms_v2.sql):
+//   idea_inbox(id, title, body_md, kind, suggested_version, suggested_priority,
+//              captured_at, captured_by, status, promoted_to_task_id, reviewed_at)
+//
+// kind values match tasks.kind (feature | bug | infra | refactor | spike |
+// learning-capture | cleanup | decision | blocker-resolution | unclassified).
+// status values are 'open' | 'promoted' | 'discarded' | 'merged'.
+//
+// Carved into modules/ideas/ (BV1.R78 / ADR 0093 §1): the ideas domain reaches
+// the shared pool through the published doorway (src/module-api.js — the only
+// core file a module may require, ADR 0083). OTB byte-identical.
+
+const { pool } = require('../../src/module-api');
+
+const VALID_KINDS = [
+  'feature',
+  'bug',
+  'infra',
+  'refactor',
+  'spike',
+  'learning-capture',
+  'cleanup',
+  'decision',
+  'blocker-resolution',
+  'unclassified',
+  // V3.R31 (#252) — Metics propose new version criteria via idea_inbox with
+  // structured body_md { target_version, criterion_md, sort_order_hint }.
+  // Archon ratifies via POST /api/gds/inbox/:id/ratify, which atomically
+  // inserts a done_when_criteria row, marks the idea promoted, awards karma,
+  // and writes a criterion_proposal_audit row. The kind value gates the
+  // ratify endpoint (assert kind='criterion-proposal' before promotion).
+  // CHECK constraint updated in migration 042.
+  'criterion-proposal',
+];
+const VALID_STATUSES = ['open', 'promoted', 'discarded', 'merged'];
+
+// -------------------------------------------------------------------------
+// Skill-friction tagging (task V3.R70 / #289)
+//
+// The nightly `skill-usage-review` routine files one idea_inbox row per
+// friction pattern it detects. The done-when calls these "kind='skill-friction'"
+// rows, but the DB CHECK constraint on idea_inbox.kind (migration 006) only
+// admits the fixed task-kind enum — adding a literal 'skill-friction' kind
+// would need a new migration, and migrations are explicitly out of scope for
+// this task. So we tag friction rows the same way overnight-code-review tags
+// its findings: a stable title prefix. The underlying `kind` stays a valid
+// enum value (cleanup), and SKILL_FRICTION_TAG is the machine-checkable marker.
+//
+// When the GDS-V3 rank system (V3.R04) lands a real builders.rank column +
+// idea_inbox.kind migration, this prefix convention can be promoted to a
+// first-class kind value and this marker collapses to a kind check.
+const SKILL_FRICTION_TAG = '[skill-friction]';
+
+// -------------------------------------------------------------------------
+// Rank visibility (task V3.R70 / #289)
+//
+// Three ranks are planned in GDS-V3 (V3.R04): Xenos (default for any
+// GitHub-authed person), Metic (Archon-approved), Archon. Skill-friction
+// ideas are a system-evolution signal meant for trusted builders — Xenos
+// must NOT see them in their inbox view; Metic and Archon may.
+//
+// `builders.rank` does not exist in the schema yet (it lands with R04), and
+// requireBuilder does not yet populate req.builder.rank — so today every
+// caller passes viewerRank=null. The gate is written to be correct the moment
+// rank is threaded through: it hides skill-friction rows ONLY when the viewer
+// is positively known to be Xenos. Unknown/absent rank (today's reality, where
+// no Xenos exist yet) is treated as Metic+ and sees everything — so wiring this
+// in does not regress current all-builders behavior.
+const XENOS_RANK = 'xenos';
+
+function rankCanSeeSkillFriction(viewerRank) {
+  // Hide only when we KNOW the viewer is Xenos. null/undefined/anything else
+  // (Metic, Archon, or "rank system not deployed") => allowed.
+  if (viewerRank == null) return true;
+  return String(viewerRank).toLowerCase() !== XENOS_RANK;
+}
+
+// -------------------------------------------------------------------------
+// Fallback classifier — keyword heuristics over title+body.
+//
+// Will be superseded by the real auto-classifier shipping in task #33 (B1).
+// Kept as a self-contained function here so this task does not depend on B1
+// and so B1 can drop in by re-exporting `classify` from a shared module.
+// -------------------------------------------------------------------------
+function classify(title, body = '') {
+  const text = `${title || ''} ${body || ''}`.toLowerCase();
+
+  // Order matters: more specific patterns first.
+  // "blocker" before "infra" because "blocker on infra" should classify as
+  // blocker-resolution, not infra.
+  if (/\b(blocker|blocked\s|waiting\s+on|unblock)\b/.test(text)) return 'blocker-resolution';
+  if (/\b(fix|broken|bug|regression|doesn'?t\s+work|isn'?t\s+working|crash|error)\b/.test(text)) return 'bug';
+  if (/\b(refactor|clean\s+up|rename|move\s|extract|consolidate)\b/.test(text)) return 'refactor';
+  if (/\b(research|spike|investigate|explore|prototype)\b/.test(text)) return 'spike';
+  if (/\b(learn|took\s+me|gotcha|discovered|tip\s+for|note\s+to\s+self)\b/.test(text)) return 'learning-capture';
+  if (/\b(decide|choose|pick\s|should\s+we|which\s+approach)\b/.test(text)) return 'decision';
+  if (/\b(deploy|infra|ops|monitoring|ci\b|cd\b|systemd|caddy|nginx)\b/.test(text)) return 'infra';
+  if (/\b(remove|delete|kill\s|deprecate|drop\s)\b/.test(text)) return 'cleanup';
+  return 'feature';
+}
+
+// -------------------------------------------------------------------------
+// Capture
+// -------------------------------------------------------------------------
+
+async function captureIdea({
+  title,
+  bodyMd = '',
+  kind,
+  suggestedVersion = null,
+  suggestedPriority = null,
+  capturedBy = null,
+}) {
+  if (!title || typeof title !== 'string') {
+    throw { code: 'TITLE_REQUIRED' };
+  }
+  const resolvedKind = kind || classify(title, bodyMd);
+  if (!VALID_KINDS.includes(resolvedKind)) {
+    throw { code: 'BAD_KIND', kind: resolvedKind };
+  }
+  if (
+    suggestedPriority != null &&
+    !(Number.isInteger(suggestedPriority) && suggestedPriority >= 1 && suggestedPriority <= 5)
+  ) {
+    throw { code: 'BAD_PRIORITY', priority: suggestedPriority };
+  }
+  const { rows } = await pool.query(
+    `INSERT INTO idea_inbox
+       (title, body_md, kind, suggested_version, suggested_priority, captured_by, status)
+     VALUES ($1, $2, $3, $4, $5, $6, 'open')
+     RETURNING id, title, body_md, kind, suggested_version, suggested_priority,
+               captured_at, captured_by, status, promoted_to_task_id, reviewed_at`,
+    [title, bodyMd, resolvedKind, suggestedVersion, suggestedPriority, capturedBy]
+  );
+  return rows[0];
+}
+
+// -------------------------------------------------------------------------
+// Read
+// -------------------------------------------------------------------------
+
+// viewerRank gates skill-friction visibility (V3.R70 / #289): Xenos must not
+// see skill-friction rows; Metic+ (or unknown rank, pre-R04) see everything.
+// We filter in SQL when the viewer is positively Xenos so the LIMIT still
+// returns up to `limit` *visible* rows rather than `limit` rows that then get
+// thinned out in JS. The skill-friction marker is a title prefix (see
+// SKILL_FRICTION_TAG above) because the kind enum cannot take a new value
+// without a migration.
+async function listOpenIdeas({ kind = null, limit = 50, viewerRank = null } = {}) {
+  const params = [];
+  const where = [`status = 'open'`];
+  if (kind) {
+    params.push(kind);
+    where.push(`kind = $${params.length}`);
+  }
+  if (!rankCanSeeSkillFriction(viewerRank)) {
+    params.push(`${SKILL_FRICTION_TAG}%`);
+    where.push(`title NOT LIKE $${params.length}`);
+  }
+  params.push(limit);
+  const { rows } = await pool.query(
+    `SELECT id, title, body_md, kind, suggested_version, suggested_priority,
+            captured_at, captured_by, status, promoted_to_task_id, reviewed_at
+       FROM idea_inbox
+      WHERE ${where.join(' AND ')}
+      ORDER BY captured_at DESC
+      LIMIT $${params.length}`,
+    params
+  );
+  return rows;
+}
+
+async function getIdea(id) {
+  const { rows } = await pool.query(
+    `SELECT id, title, body_md, kind, suggested_version, suggested_priority,
+            captured_at, captured_by, status, promoted_to_task_id, reviewed_at
+       FROM idea_inbox
+      WHERE id = $1`,
+    [id]
+  );
+  return rows[0] ?? null;
+}
+
+// viewerRank applies the SAME skill-friction visibility gate as listOpenIdeas
+// (V3.R70 / #289) so the count a viewer is shown matches the rows they can see:
+// a Xenos must not be told there are N open ideas when [skill-friction] rows
+// are filtered out of their list. Default null preserves the old "count
+// everything" behaviour for callers that don't have (or don't gate on) a rank.
+async function countOpenIdeas({ viewerRank = null } = {}) {
+  const params = [];
+  const where = [`status = 'open'`];
+  if (!rankCanSeeSkillFriction(viewerRank)) {
+    params.push(`${SKILL_FRICTION_TAG}%`);
+    where.push(`title NOT LIKE $${params.length}`);
+  }
+  const { rows } = await pool.query(
+    `SELECT count(*)::int AS n FROM idea_inbox WHERE ${where.join(' AND ')}`,
+    params
+  );
+  return rows[0].n;
+}
+
+// -------------------------------------------------------------------------
+// Update / merge
+// -------------------------------------------------------------------------
+
+async function updateIdea(id, { status, kind, promoted_to_task_id, reviewed_at } = {}) {
+  const sets = [];
+  const params = [id];
+  if (status !== undefined) {
+    if (!VALID_STATUSES.includes(status)) throw { code: 'BAD_STATUS', status };
+    params.push(status);
+    sets.push(`status = $${params.length}`);
+  }
+  if (kind !== undefined) {
+    if (!VALID_KINDS.includes(kind)) throw { code: 'BAD_KIND', kind };
+    params.push(kind);
+    sets.push(`kind = $${params.length}`);
+  }
+  if (promoted_to_task_id !== undefined) {
+    params.push(promoted_to_task_id);
+    sets.push(`promoted_to_task_id = $${params.length}`);
+  }
+  if (reviewed_at !== undefined) {
+    params.push(reviewed_at);
+    sets.push(`reviewed_at = $${params.length}`);
+  }
+  if (sets.length === 0) {
+    return getIdea(id);
+  }
+  const { rows } = await pool.query(
+    `UPDATE idea_inbox
+        SET ${sets.join(', ')}
+      WHERE id = $1
+      RETURNING id, title, body_md, kind, suggested_version, suggested_priority,
+                captured_at, captured_by, status, promoted_to_task_id, reviewed_at`,
+    params
+  );
+  if (rows.length === 0) throw { code: 'IDEA_NOT_FOUND' };
+  return rows[0];
+}
+
+// -------------------------------------------------------------------------
+// Criterion-proposal ratification (V3.R31 / #252)
+//
+// Atomically promotes an idea_inbox row with kind='criterion-proposal' into a
+// real done_when_criteria row, marks the idea as promoted, awards karma to
+// the proposer (delta=+3, reason='proposal_ratified'), and writes an audit
+// row capturing who proposed / who ratified / when / what.
+//
+// Called by POST /api/gds/inbox/:id/ratify (Archon-only, gated by requireRank
+// in the router). The body_md of the source idea is parsed as JSON with the
+// shape { target_version, criterion_md, sort_order_hint }; malformed bodies
+// throw BAD_BODY so the route can return a structured 400.
+//
+// Karma amount is tunable; V3.R28 (#248) sets it to +3 to recognize good civic
+// input without overweighting it relative to peer-upvote signals that arrive
+// in volume. criterion_id on the new done_when_criteria row defaults to
+// "proposal-<idea_id>" so the (version_id, criterion_id) UNIQUE constraint
+// fires if someone ratifies the same idea twice — the second attempt fails the
+// transaction rather than creating a duplicate criterion silently.
+const KARMA_RATIFY_DELTA = 3;
+const KARMA_RATIFY_REASON = 'proposal_ratified';
+
+function parseProposalBody(bodyMd) {
+  if (!bodyMd || typeof bodyMd !== 'string') {
+    throw { code: 'BAD_BODY', reason: 'body_md_empty' };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(bodyMd);
+  } catch (err) {
+    throw { code: 'BAD_BODY', reason: 'body_md_not_json', detail: err.message };
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw { code: 'BAD_BODY', reason: 'body_md_not_object' };
+  }
+  const { target_version, criterion_md, sort_order_hint } = parsed;
+  if (!target_version || typeof target_version !== 'string') {
+    throw { code: 'BAD_BODY', reason: 'target_version_required' };
+  }
+  if (!criterion_md || typeof criterion_md !== 'string') {
+    throw { code: 'BAD_BODY', reason: 'criterion_md_required' };
+  }
+  let hint = null;
+  if (sort_order_hint != null) {
+    const n = Number(sort_order_hint);
+    if (!Number.isFinite(n) || !Number.isInteger(n)) {
+      throw { code: 'BAD_BODY', reason: 'sort_order_hint_not_integer' };
+    }
+    hint = n;
+  }
+  return { target_version, criterion_md, sort_order_hint: hint };
+}
+
+async function ratifyCriterionProposal(ideaId, ratifierId, { notesMd = '' } = {}) {
+  const id = Number(ideaId);
+  if (!Number.isFinite(id)) {
+    throw { code: 'BAD_ID' };
+  }
+  const rid = Number(ratifierId);
+  if (!Number.isFinite(rid)) {
+    throw { code: 'BAD_RATIFIER' };
+  }
+  const client = await pool.connect();
+  try {
+    await client.query('BEGIN');
+
+    // a. Read + lock the idea row.
+    const { rows: ideaRows } = await client.query(
+      `SELECT id, title, body_md, kind, status, captured_by
+         FROM idea_inbox
+        WHERE id = $1
+        FOR UPDATE`,
+      [id]
+    );
+    if (ideaRows.length === 0) throw { code: 'IDEA_NOT_FOUND' };
+    const idea = ideaRows[0];
+    if (idea.kind !== 'criterion-proposal') {
+      throw { code: 'WRONG_KIND', kind: idea.kind, expected: 'criterion-proposal' };
+    }
+    if (idea.status !== 'open') {
+      throw { code: 'IDEA_NOT_OPEN', status: idea.status };
+    }
+
+    // b. Parse body_md.
+    const proposal = parseProposalBody(idea.body_md);
+
+    // c. Verify target version exists. (FK on done_when_criteria.version_id
+    //    would catch this too, but giving a 400 instead of a 23503 is friendlier.)
+    const { rows: verRows } = await client.query(
+      `SELECT id FROM versions WHERE id = $1`,
+      [proposal.target_version]
+    );
+    if (verRows.length === 0) {
+      throw { code: 'VERSION_NOT_FOUND', version_id: proposal.target_version };
+    }
+
+    // d. Resolve sort_order: prefer the hint; otherwise max(existing)+1, or 100
+    //    if no rows exist yet (matches the migration 006 default).
+    let sortOrder = proposal.sort_order_hint;
+    if (sortOrder == null) {
+      const { rows: maxRows } = await client.query(
+        `SELECT COALESCE(MAX(sort_order), 0) + 1 AS next
+           FROM done_when_criteria
+          WHERE version_id = $1`,
+        [proposal.target_version]
+      );
+      sortOrder = maxRows[0].next;
+    }
+
+    // e. INSERT done_when_criteria with criterion_id = 'proposal-<idea_id>'.
+    //    The UNIQUE (version_id, criterion_id) constraint provides natural
+    //    idempotency — re-ratifying the same idea would 23505 here.
+    const criterionRefId = `proposal-${idea.id}`;
+    const { rows: critRows } = await client.query(
+      `INSERT INTO done_when_criteria
+         (version_id, criterion_id, criterion_md, sort_order)
+       VALUES ($1, $2, $3, $4)
+       RETURNING id, version_id, criterion_id, criterion_md, sort_order`,
+      [proposal.target_version, criterionRefId, proposal.criterion_md, sortOrder]
+    );
+    const criterion = critRows[0];
+
+    // f. Mark the idea promoted. promoted_to_task_id stays NULL — a criterion
+    //    is not a task. reviewed_at is stamped to now() so triage views skip it.
+    await client.query(
+      `UPDATE idea_inbox
+          SET status              = 'promoted',
+              promoted_to_task_id = NULL,
+              reviewed_at         = now()
+        WHERE id = $1`,
+      [idea.id]
+    );
+
+    // g. Award karma to the proposer. captured_by may be NULL on legacy rows;
+    //    skip the karma insert in that case (no proposer to credit) but still
+    //    record the audit row.
+    let karmaAwarded = 0;
+    if (idea.captured_by != null) {
+      await client.query(
+        `INSERT INTO karma_log (builder_id, delta, reason, granted_by)
+         VALUES ($1, $2, $3, $4)`,
+        [idea.captured_by, KARMA_RATIFY_DELTA, KARMA_RATIFY_REASON, rid]
+      );
+      karmaAwarded = KARMA_RATIFY_DELTA;
+
+      // Note: prior to 2026-05-30 this also ticked a 'first_vote_received'
+      // onboarding stage. That stage was removed (migration 059) — graduation
+      // no longer waits on a peer vote — so there is nothing to mark here now.
+    }
+
+    // h. Audit row — durable record of the ratification event.
+    const { rows: auditRows } = await client.query(
+      `INSERT INTO criterion_proposal_audit
+         (idea_id, criterion_id, proposed_by, ratified_by,
+          target_version, criterion_md, sort_order_hint, notes_md)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
+       RETURNING id, ratified_at`,
+      [
+        idea.id,
+        criterion.id,
+        idea.captured_by,
+        rid,
+        proposal.target_version,
+        proposal.criterion_md,
+        proposal.sort_order_hint,
+        notesMd || '',
+      ]
+    );
+
+    await client.query('COMMIT');
+    return {
+      criterion_id: criterion.id,
+      criterion_ref: criterion.criterion_id,
+      version_id: criterion.version_id,
+      sort_order: criterion.sort_order,
+      audit_id: auditRows[0].id,
+      ratified_at: auditRows[0].ratified_at,
+      karma_awarded: karmaAwarded,
+      proposer_id: idea.captured_by,
+    };
+  } catch (err) {
+    await client.query('ROLLBACK').catch(() => {});
+    throw err;
+  } finally {
+    client.release();
+  }
+}
+
+// -------------------------------------------------------------------------
+// Helpers used by CLI defaults
+// -------------------------------------------------------------------------
+
+module.exports = {
+  // classifier (exported for tests + future B1 swap-in)
+  classify,
+  VALID_KINDS,
+  VALID_STATUSES,
+  // skill-friction tagging + rank visibility gate (V3.R70 / #289)
+  SKILL_FRICTION_TAG,
+  XENOS_RANK,
+  rankCanSeeSkillFriction,
+  // capture
+  captureIdea,
+  // read
+  listOpenIdeas,
+  getIdea,
+  countOpenIdeas,
+  // mutate
+  updateIdea,
+  // criterion-proposal ratification (V3.R31 / #252)
+  ratifyCriterionProposal,
+  parseProposalBody,
+  KARMA_RATIFY_DELTA,
+  KARMA_RATIFY_REASON,
+};

package/modules/ideas/module.json

@@ -0,0 +1,10 @@
+{
+  "key": "ideas",
+  "title": "Ideas",
+  "description": "The idea inbox (capture, triage, criterion-proposal ratification) and the blockers queue — the methodology surfaces that feed the backlog. A core-domain module carved out of the GDS core in BV1.R78 (ADR 0093 §1); default-on because every instance captures ideas and tracks what's stuck on its owner. Registers the `ideas.capture` kernel PORT the discord #ideas inbound resolves (ADR 0093 §5 — retiring the temporary `captureIdea` doorway leak).",
+  "coreVersion": "^1.8.0",
+  "default": true,
+  "contributes": { "routes": ["inbox", "blockers"] },
+  "provides": ["ideas.capture"],
+  "consumes": []
+}