@bongos/core 1.19.915 → 1.19.917

package/modules/ideas/projection.js

@@ -0,0 +1,103 @@
+// modules/ideas/projection.js — the SHAPE every idea read returns (task 1004115).
+//
+// Carved out of inbox.js, which sat at exactly the 1,500-line ratchet ceiling
+// (scripts/gds/fitness-ratchets.js OVERSIZE_LINES) and could therefore not grow
+// by one line. That ceiling had started deciding the design rather than the
+// domain: modules/ideas/CLAUDE.md records two files (trail-descent.js,
+// trail-size.js) that exist partly because of it, and task 1004084 shipped an
+// inline require() inside a call expression to save a line.
+//
+// THIS FILE IS THE BOTTOM OF THE MODULE. It holds the column lists, the grade
+// vocabulary and the join fragment that the reads in reads.js, trail.js and
+// grades.js all splice into SQL — the "one column list every idea read returns"
+// argument below is exactly why they must share a file rather than a copy. It
+// requires NOTHING: no doorway, no pool, no sibling. That is deliberate and
+// load-bearing — every other file in the carve depends on this one, so anything
+// added here that reached back up would make the module cyclic
+// (require_cycle_count is a baselined ratchet).
+
+// The one column list every idea read returns. Four copies had to stay in step
+// (capture / list / get / update-RETURNING); core_195 added two columns to each,
+// so it is now a constant rather than four places to forget. Kept as names rather
+// than a string so the qualified form (task 1002916 joined the grade table in, and
+// an unqualified `id` is ambiguous across a join) is derived, not a fifth copy.
+const IDEA_COL_NAMES = [
+  'id', 'title', 'body_md', 'kind', 'suggested_version', 'suggested_priority',
+  'captured_at', 'captured_by', 'status', 'promoted_to_task_id', 'reviewed_at',
+  'merged_into_idea_id', 'triage_note',
+  // core_222 (task 1003060, BV1.R02): the routing HINT — "this probably belongs
+  // to goal N" — on a row that did NOT convert. Added to the shared list because
+  // R02 shipped the column and nothing read it: /idea-triage (R13) cannot walk
+  // homeless-only work if the read that feeds it never returns the hint. Strictly
+  // advisory: no rank check, no scope wall, and no payout may read it (see the
+  // migration's own header). The BINDING home for "which goal" is tasks.goal_id.
+  'suggested_goal_id',
+];
+const IDEA_COLS = IDEA_COL_NAMES.join(', ');
+const IDEA_COLS_Q = IDEA_COL_NAMES.map((c) => `i.${c}`).join(', ');
+
+// -------------------------------------------------------------------------
+// Idea grades (task 1002916 / BV1.R140, goal 1000062)
+//
+// Three grades, from the owner's brief:
+//   quick — title + description, open to every role, aimed at turning a thought
+//           into a task fast. NOT a draft Full Idea.
+//   spark — a Quick Idea whose AUTHOR marked it as needing development. The mark
+//           is the consent that makes cross-builder development fair (R144).
+//   full  — carries the base template's five fields, scored on completeness.
+//
+// AN IDEA WITH NO ideas_grades ROW READS AS QUICK. That is the design, not a
+// fallback: every idea captured before this shipped keeps grade='quick' without
+// a row being written or a column being backfilled. The COALESCE below is where
+// that rule lives, and it is the reason the reads LEFT JOIN rather than JOIN.
+// An explicit quick row is equally legal (un-sparking writes one) and reads the
+// same, so callers never have to care which of the two they are looking at.
+const DEFAULT_GRADE = 'quick';
+const VALID_GRADES = ['quick', 'spark', 'full'];
+
+// Which template `field_values` was written against. Stored per row so a project
+// that later defines its own shape (R156) does not retro-reinterpret ideas
+// written against the base one. R141 declares what 'base-v1' actually contains —
+// this module only records which template a row used.
+const DEFAULT_TEMPLATE_KEY = 'base-v1';
+const TEMPLATE_KEY_RE = /^[a-z][a-z0-9-]*$/;
+const TEMPLATE_KEY_MAX = 64;
+
+// Mirrors ideas_grades_field_values_size_chk. Declared here too so an oversize
+// payload gets a structured 400 instead of a constraint-violation 500.
+const FIELD_VALUES_MAX = 32768;
+
+// The grade half of an idea read: the COALESCE above, plus the template-shaped
+// store and the score. `g.*` columns are NULL for an ungraded idea, which is
+// exactly right — it has no template and no score, it just has a default grade.
+// developed_by/developed_at (ideas_005, task 1002922 / BV1.R146) ride along on
+// EVERY idea read rather than needing a second query: "who developed this" is
+// part of an idea's identity once it has been developed, and the R145 queue, the
+// hall detail view (R153) and the R147 credit split all want it. NULL for the
+// overwhelming majority of rows — a quick idea and a self-authored Full Idea were
+// never developed by anyone — which is the honest answer, not a missing one.
+const GRADE_COLS_Q = `COALESCE(g.grade, '${DEFAULT_GRADE}') AS grade,
+            g.template_key, g.field_values, g.completeness_score,
+            g.developed_by, g.developed_at`;
+const IDEA_JOIN_GRADE = `LEFT JOIN ideas_grades g ON g.idea_id = i.id`;
+
+// The same projection for a row that provably has no grade row yet (a just-
+// INSERTed idea), so INSERT…RETURNING does not need a second round trip to
+// return the same shape every other read returns.
+function ungradedProjection() {
+  return { grade: DEFAULT_GRADE, template_key: null, field_values: null, completeness_score: null, developed_by: null, developed_at: null };
+}
+
+module.exports = {
+  IDEA_COLS,
+  IDEA_COLS_Q,
+  DEFAULT_GRADE,
+  VALID_GRADES,
+  DEFAULT_TEMPLATE_KEY,
+  TEMPLATE_KEY_RE,
+  TEMPLATE_KEY_MAX,
+  FIELD_VALUES_MAX,
+  GRADE_COLS_Q,
+  IDEA_JOIN_GRADE,
+  ungradedProjection,
+};

package/modules/ideas/ratify.js

@@ -0,0 +1,211 @@
+// modules/ideas/ratify.js — criterion-proposal ratification (task 1004115;
+// the transaction itself is V3.R31).
+//
+// Carved out of inbox.js verbatim, and the most clearly separable thing in it:
+// this is the ONE place the ideas module writes done_when_criteria, karma_log
+// and criterion_proposal_audit — three tables no other function here touches —
+// in a single transaction. It reads one idea_inbox row and never uses the
+// shared idea projection, so unlike every other carved file it depends on
+// nothing but the doorway.
+//
+// It is a PLANNING write wearing an idea's clothes: a Metic proposes through
+// the inbox because that is the capture surface everyone already has, and an
+// Archon ratifies it into a version's scope. Keeping it beside the triage
+// writes made the two look like the same kind of act. They are not.
+
+const { pool } = require('../../src/module-api');
+
+// -------------------------------------------------------------------------
+// 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/bongos/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();
+  }
+}
+
+module.exports = {
+  KARMA_RATIFY_DELTA,
+  KARMA_RATIFY_REASON,
+  parseProposalBody,
+  ratifyCriterionProposal,
+};

package/modules/ideas/reads.js

@@ -0,0 +1,96 @@
+// modules/ideas/reads.js — the three plain idea reads (task 1004115).
+//
+// listOpenIdeas / getIdea / countOpenIdeas, carved out of inbox.js verbatim.
+// They are grouped because they are the reads with no second relation in them:
+// the trail (trail.js) joins lineage and outcomes, the spark queue (grades.js)
+// starts from ideas_grades, the descent (trail-descent.js) walks task-to-task.
+// These three just read idea_inbox with its grade attached.
+//
+// IT SITS BELOW grades.js ON PURPOSE. developSpark needs getIdea to build the
+// idea.graded.full payload, and updateIdea in inbox.js needs it too. Leaving it
+// in inbox.js would have made inbox -> grades -> inbox a require cycle, which
+// is a baselined ratchet (require_cycle_count). Reads depend on projection.js
+// and skill-friction.js and on nothing above them.
+
+const { pool } = require('../../src/module-api');
+const { IDEA_COLS_Q, GRADE_COLS_Q, IDEA_JOIN_GRADE } = require('./projection');
+const { skillFrictionHiddenClause } = require('./skill-friction');
+
+// -------------------------------------------------------------------------
+// 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 marker is a kind OR a legacy title prefix — see
+// skillFrictionHiddenClause, which is the only place that knows that.
+async function listOpenIdeas({ kind = null, limit = 50, viewerRank = null } = {}) {
+  const params = [];
+  const where = [`i.status = 'open'`];
+  if (kind) {
+    params.push(kind);
+    where.push(`i.kind = $${params.length}`);
+  }
+  const hideFriction = skillFrictionHiddenClause(viewerRank, params, 'i');
+  if (hideFriction) where.push(hideFriction);
+  params.push(limit);
+  const { rows } = await pool.query(
+    `SELECT ${IDEA_COLS_Q}, ${GRADE_COLS_Q}
+       FROM idea_inbox i
+       ${IDEA_JOIN_GRADE}
+      WHERE ${where.join(' AND ')}
+      ORDER BY i.captured_at DESC
+      LIMIT $${params.length}`,
+    params
+  );
+  return rows;
+}
+
+// The by-id read. It carries the two people's LOGINS as well as their ids
+// (task 1002929 / R153): an idea's attribution is a claim about humans, and
+// "captured_by: 41" is not attribution to anyone reading it. Named to match the
+// R145 spark queue's `filed_by_login` so the two idea surfaces agree.
+//
+// Both joins are LEFT: a builder row can be missing (an FK that went
+// ON DELETE SET NULL), and an idea nobody developed has no developer at all —
+// which is the common case, not an error. A plain JOIN here would drop most of
+// the inbox, the same trap the grade join documents above.
+async function getIdea(id) {
+  const { rows } = await pool.query(
+    `SELECT ${IDEA_COLS_Q}, ${GRADE_COLS_Q},
+            ba.github_login AS filed_by_login,
+            bd.github_login AS developed_by_login
+       FROM idea_inbox i
+       ${IDEA_JOIN_GRADE}
+       LEFT JOIN builders ba ON ba.id = i.captured_by
+       LEFT JOIN builders bd ON bd.id = g.developed_by
+      WHERE i.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'`];
+  const hideFriction = skillFrictionHiddenClause(viewerRank, params);
+  if (hideFriction) where.push(hideFriction);
+  const { rows } = await pool.query(
+    `SELECT count(*)::int AS n FROM idea_inbox WHERE ${where.join(' AND ')}`,
+    params
+  );
+  return rows[0].n;
+}
+
+module.exports = {
+  listOpenIdeas,
+  getIdea,
+  countOpenIdeas,
+};

package/modules/ideas/trail.js

@@ -0,0 +1,111 @@
+// modules/ideas/trail.js — THE IDEA TRAIL: every idea one builder filed, and
+// what became of each (task 1004115; the read itself is task 1003281).
+//
+// Carved out of inbox.js verbatim. It joins its own siblings — trail-descent.js
+// hangs the task-to-task walk under these rows, trail-size.js hangs what the
+// descent has paid — and both of those were put in their own file for the
+// reason this carve now applies to the read itself: inbox.js was AT the
+// 1,500-line ratchet, so "a different relation deserves a different file" and
+// "nothing more fits" had become the same sentence. They are separable again.
+// The trail is a read keyed by PERSON; inbox.js is the capture chokepoint and
+// the triage writes.
+
+const { pool } = require('../../src/module-api');
+const { IDEA_COLS_Q, GRADE_COLS_Q, IDEA_JOIN_GRADE } = require('./projection');
+const { skillFrictionHiddenClause } = require('./skill-friction');
+
+// -------------------------------------------------------------------------
+// The idea TRAIL — every idea one builder filed, and what became of it
+// (task 1003281, goal 1000072, criterion legibility-activity-by-role).
+//
+// THE READ THAT EXISTS NOWHERE ELSE, and the reason the criterion was written:
+// the owner could file an idea and then never find out what happened to it.
+// Every other idea read is scoped to what is STILL OPEN — listOpenIdeas, the
+// spark queue, the nod queue — so a promoted, discarded or merged idea drops
+// out of every surface the moment it is triaged, which is exactly when its
+// outcome becomes interesting. This read is scoped to a PERSON instead of to a
+// status, so nothing they filed ever leaves it.
+//
+// NO NEW STORAGE. The four outcomes are already on the row: `status` says which
+// one, `promoted_to_task_id` + ideas_task_lineage say which task a promotion
+// produced, `merged_into_idea_id` says which idea absorbed a merge, and
+// `triage_note` carries the triager's sentence (core_195, task 1002447). The
+// joins below turn those ids into names so a reader gets "became task #1003281
+// — See what you did, by role" rather than a number they must go look up.
+//
+// AN OPEN IDEA IS AN OUTCOME. It reads as "still open", never as an absence —
+// one of the four the criterion names. That is why status is returned verbatim
+// and the surface renders it, rather than the read filtering open rows out.
+//
+// LINEAGE, NOT JUST THE LEGACY COLUMN. One idea can become MANY tasks
+// (ideas_task_lineage, task 1002997), while `promoted_to_task_id` holds only the
+// first. Both are returned: the lineage array is the complete answer, the legacy
+// column is the only answer for promotions that predate the lineage table. The
+// LATERAL is bounded by the page window, so this stays one query, not an N+1.
+const IDEA_TRAIL_DEFAULT_LIMIT = 20;
+const IDEA_TRAIL_MAX_LIMIT = 100;
+
+// The WHERE this list and its count share, so the pager can never claim rows the
+// list will not show. viewerRank applies the SAME skill-friction gate as every
+// other idea read (V3.R70 / #289) — including on a builder reading their OWN
+// trail: the gate is about what a rank may see, not about authorship.
+function ideaTrailWhere(builderId, viewerRank, params) {
+  params.push(builderId);
+  const where = [`i.captured_by = $${params.length}`];
+  const hideFriction = skillFrictionHiddenClause(viewerRank, params, 'i');
+  if (hideFriction) where.push(hideFriction);
+  return where.join(' AND ');
+}
+
+async function listIdeaTrailForBuilder(builderId, { limit = IDEA_TRAIL_DEFAULT_LIMIT, offset = 0, viewerRank = null } = {}, deps = {}) {
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const lim = Math.min(Math.max(Number.isInteger(Number(limit)) ? Number(limit) : IDEA_TRAIL_DEFAULT_LIMIT, 1), IDEA_TRAIL_MAX_LIMIT);
+  const off = Number.isInteger(Number(offset)) && Number(offset) > 0 ? Number(offset) : 0;
+  const params = [];
+  const where = ideaTrailWhere(builderId, viewerRank, params);
+  params.push(lim, off);
+  const { rows } = await activePool.query(
+    `SELECT ${IDEA_COLS_Q}, ${GRADE_COLS_Q},
+            pt.title  AS promoted_task_title,
+            pt.status AS promoted_task_status,
+            mi.title  AS merged_into_idea_title,
+            mi.status AS merged_into_idea_status,
+            COALESCE(lin.tasks, '[]'::json) AS lineage_tasks
+       FROM idea_inbox i
+       ${IDEA_JOIN_GRADE}
+       LEFT JOIN tasks pt ON pt.id = i.promoted_to_task_id
+       LEFT JOIN idea_inbox mi ON mi.id = i.merged_into_idea_id
+       LEFT JOIN LATERAL (
+         SELECT json_agg(json_build_object(
+                  'task_id', l.task_id, 'origin', l.origin,
+                  'title', lt.title, 'status', lt.status
+                ) ORDER BY l.task_id) AS tasks
+           FROM ideas_task_lineage l
+           JOIN tasks lt ON lt.id = l.task_id
+          WHERE l.idea_id = i.id
+       ) lin ON true
+      WHERE ${where}
+      ORDER BY i.captured_at DESC, i.id DESC
+      LIMIT $${params.length - 1} OFFSET $${params.length}`,
+    params
+  );
+  return rows;
+}
+
+async function countIdeaTrailForBuilder(builderId, { viewerRank = null } = {}, deps = {}) {
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const params = [];
+  const where = ideaTrailWhere(builderId, viewerRank, params);
+  const { rows } = await activePool.query(
+    `SELECT count(*)::int AS n FROM idea_inbox i WHERE ${where}`,
+    params
+  );
+  return rows[0].n;
+}
+
+module.exports = {
+  IDEA_TRAIL_DEFAULT_LIMIT,
+  IDEA_TRAIL_MAX_LIMIT,
+  listIdeaTrailForBuilder,
+  countIdeaTrailForBuilder,
+};

package/modules/lifecycle/cascade.js

@@ -17,7 +17,7 @@
 // shipped task looks like THIS, file THAT task, for THAT discipline. There is no
 // condition language, no stored rules, no per-project configuration and no UI —
 // every one of those is a thing to add when a second and third cascade exist and
-// have shown what they have in common. Today `CASCADES` ships EMPTY: the
+// have shown what they have in common. `CASCADES` no longer ships empty: the
 // mechanism, its idempotency and its non-blocking property are proved by the
 // tests' own declarations, and R04 (task 1003115) writes the first production
 // entry. A mechanism whose first real rule is written by the task that needs it
@@ -169,6 +169,50 @@ function artistReviewBody(task) {
   ].join('\n');
 }
 
+// The removal proposal's body (task 1004090 / BV2.R15, ADR 0313).
+//
+// IT ASKS, IT DOES NOT TELL. Every line here is written so a reader confirms or
+// dismisses on the evidence rather than rubber-stamping a verdict — because the
+// owner chose propose-then-confirm precisely for the cases this derivation cannot
+// tell apart from a real removal. The three it CAN tell apart (a rename, a move,
+// a rewrite in place) are already excluded upstream in removal-derivation.js.
+//
+// The affected tasks and paths are named as PROSE, deliberately. A cascade files
+// one task per rule per ship keyed on (rule, ship), with no field for a target,
+// and R05's runner may not be widened to fan out (ADR 0242). Owner decision
+// 2026-09-20: the body carries them and R20 designs its own storage when it needs
+// one. So this text IS the record until then — keep it readable and keep it exact.
+function removalProposalBody(task, ctx) {
+  const found = ((ctx || {}).removals) || [];
+  const lines = [];
+  lines.push(`Shipping task ${task.id} deleted files that earlier SHIPPED work put there.`);
+  lines.push('');
+  lines.push('**This is a question, not a verdict.** Nothing has been marked removed, no');
+  lines.push('status changed and no credit moved — and none of that happens unless a person');
+  lines.push('confirms below. `shipped` is terminal and stays terminal.');
+  lines.push('');
+  lines.push('**Removed work attributed to:**');
+  for (const r of found) {
+    lines.push(`  - task ${r.taskId}${r.title ? ` — ${r.title}` : ''}`);
+    for (const path of r.paths) lines.push(`      ${path}`);
+  }
+  lines.push('');
+  if ((ctx || {}).removalTruncated) {
+    lines.push(`Note: this ship deleted ${(ctx || {}).removalDeletedCount} paths, more than the`);
+    lines.push('attribution cap, so the list above is PARTIAL. A ship that large is usually a');
+    lines.push('move or a sweep — weigh that before confirming.');
+    lines.push('');
+  }
+  lines.push('**Confirm** if that work is genuinely gone: the ideas whose descent it belongs');
+  lines.push('to will dim accordingly. **Dismiss** if this was a refactor, a move the rename');
+  lines.push('detection missed, or a deletion of something already superseded — dismissing is');
+  lines.push('what stops the sky being dimmed for a reason that is not real.');
+  lines.push('');
+  lines.push('Attribution runs through `claims.published_head_sha`, so a deletion whose origin');
+  lines.push('predates that record is silently absent rather than guessed at.');
+  return lines.join('\n');
+}
+
 // Production rules. The artist review is the first (R04); add another by
 // appending an entry, never by touching the runner (ADR 0242).
 const CASCADES = Object.freeze([
@@ -189,6 +233,25 @@ const CASCADES = Object.freeze([
     title: (t) => `Artist review: the copy and visuals that shipped in task ${t.id}`,
     body: artistReviewBody,
   }),
+  Object.freeze({
+    key: 'removal-proposed-on-ship',
+    // ENGINEER, not artist: confirming asks whether deleted code is genuinely
+    // gone or was moved, which is a question about the diff.
+    discipline: 'engineer',
+    kind: 'unclassified',
+    // The anti-recursion guard FIRST, the same order and for the same reason as
+    // the rule above — a cascade-generated task must never cascade.
+    //
+    // The candidates are resolved ONCE into ctx by runCascadesForShip, never
+    // here: a `when` is pure and synchronous by contract, and this derivation is
+    // a network read. An absent ctx therefore means "nothing was derived" and
+    // files nothing — the opposite default to the artist gate above, and
+    // deliberately so: silence about a removal must never be read as a removal.
+    when: (t, ctx) => t.source !== CASCADE_SOURCE
+      && Array.isArray((ctx || {}).removals) && (ctx || {}).removals.length > 0,
+    title: (t) => `Was this removed? Task ${t.id} deleted earlier shipped work`,
+    body: removalProposalBody,
+  }),
 ]);
 
 // THE TRIGGERS. A cascade reacts to a state transition; there are two, and this
@@ -319,7 +382,7 @@ function cascadesFor(task, rules = CASCADES, ctx = {}, trigger = TRIGGERS.ship)
     }
     if (!hit) continue;
     try {
-      matched.push({ rule, spec: cascadeTaskSpec(rule, task, trigger) });
+      matched.push({ rule, spec: cascadeTaskSpec(rule, task, trigger, ctx) });
     } catch (e) {
       errors.push(`cascade "${rule.key}": title/body threw (${e && e.message})`);
     }
@@ -329,8 +392,11 @@ function cascadesFor(task, rules = CASCADES, ctx = {}, trigger = TRIGGERS.ship)
 
 // The createTask payload for one matched rule. The attribution preamble is
 // prepended here rather than left to each rule, so no rule can forget it.
-function cascadeTaskSpec(rule, task, trigger = TRIGGERS.ship) {
-  const body = String(rule.body(task) || '').trim();
+// `ctx` reaches body() as a second argument, mirroring when(). The artist rule
+// ignores it; the removal rule needs it, because what a ship deleted is derived
+// per run and is not a property of the task row.
+function cascadeTaskSpec(rule, task, trigger = TRIGGERS.ship, ctx = {}) {
+  const body = String(rule.body(task, ctx) || '').trim();
   const preamble =
     `Filed automatically when ${trigger.happened(task)} — the "${rule.key}" cascade `
     + `(modules/lifecycle/cascade.js). Nobody typed this; it is a REQUEST, filed at backlog, `
@@ -466,6 +532,27 @@ async function runCascadesForShip(shipped, deps = {}) {
       try { ctx.artistGate = deps.artistGateMode(); }
       catch (e) { report.errors.push(`cascade: artistGateMode() threw (${e && e.message}) — policy unread`); }
     }
+    // WHAT THIS SHIP DELETED (task 1004090 / BV2.R15, ADR 0313). Resolved here
+    // rather than in the rule for the reason the rule's own comment gives: a
+    // `when` is pure and synchronous, and this is a network read.
+    //
+    // Same posture as the policy read above — a resolver that throws is REPORTED
+    // and leaves the keys unset, so a derivation outage files no proposal and
+    // costs the ship nothing. `removalCandidates` already swallows its own
+    // failures (removal-derivation.js returns a report rather than rejecting);
+    // this try/catch is the belt to that braces, because a non-blocking promise
+    // is only non-blocking until someone edits it.
+    if (typeof deps.removalCandidates === 'function') {
+      try {
+        const derived = await deps.removalCandidates(task);
+        ctx.removals = (derived && derived.removals) || [];
+        ctx.removalTruncated = Boolean(derived && derived.truncated);
+        ctx.removalDeletedCount = (derived && derived.deletedCount) || 0;
+        for (const e of (derived && derived.errors) || []) report.errors.push(e);
+      } catch (e) {
+        report.errors.push(`cascade: removalCandidates() threw (${e && e.message}) — no removal derived`);
+      }
+    }
 
     const { matched, errors } = cascadesFor(task, deps.rules || CASCADES, ctx);
     report.errors.push(...errors);
@@ -480,6 +567,7 @@ async function runCascadesForShip(shipped, deps = {}) {
 
 module.exports = {
   CASCADES,
+  removalProposalBody,
   IDEA_CASCADES,
   TRIGGERS,
   fullIdeaScopingBody,