@bongos/core 1.19.316 → 1.19.317

package/modules/lifecycle/db-tasks.js

@@ -0,0 +1,810 @@
+// modules/lifecycle/db-tasks.js — task CRUD, the reward gate, the claimable feed + task reads.
+//
+// Carved out of modules/lifecycle/db.js by task 1003204 (goal 1000079, the R03
+// de-monolith plan) — a STRUCTURAL move, not a rewrite: the code below is the
+// original db.js lines 1374-2132 unchanged. db.js remains the facade that
+// re-exports every name, so every existing db call site is unchanged.
+//
+// THE BOUNDARY (ADR 0093 §1): this file reaches core ONLY through the published
+// doorway ../../src/module-api.js — never a core internal, never a sibling module.
+
+'use strict';
+
+const api = require('../../src/module-api');
+const { pool } = api;
+const log = api.logger('lifecycle');
+const { generalGoalTitle } = require('./goal-advisory.js');
+const { matchProtected } = api.permissionPathCheck;
+const { decorateGoalMembership, capNewcomerTasks } = require('./claim-feed.js');
+const { deriveRequiredRank, highestRank } = require('./db-rank-authz.js');
+
+// -------------------------------------------------------------------------
+// Tasks
+// -------------------------------------------------------------------------
+
+
+// task 1763: resolve a version's catch-all "<version> — general" goal (created by
+// migration 160, created_by NULL). This is the fallback goal a goal-less task
+// defaults into (see createTask) so the "every task belongs to a goal" invariant
+// holds for every create-vector. Returns the goal id, or null when the version has
+// no general goal (then the caller leaves goal_id NULL rather than failing a
+// create). Honors the #538 deps.pool test seam (NODE_ENV==='test') so it is
+// unit-testable DB-free. The title mirrors migration 160's insert exactly (a spaced
+// em-dash); it is built by ../goal-advisory.generalGoalTitle so this SQL and the
+// advisory that detects the same goal can never disagree (task 1002539).
+async function generalGoalIdForVersion(versionId, deps = {}) {
+  if (versionId == null) return null;
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const { rows } = await activePool.query(
+    'SELECT id FROM goals WHERE version_id = $1 AND title = $2 LIMIT 1',
+    [versionId, generalGoalTitle(versionId)]
+  );
+  return rows[0] ? rows[0].id : null;
+}
+
+async function createTask({
+  versionId,
+  title,
+  description = '',
+  status = 'backlog',
+  touches = [],
+  estMinutes = null,
+  estCostUsd = null,
+  manualDegree = null,
+  priority = null,
+  automationTag = null,
+  creditsReward = 0,
+  source = null,
+  sourceRef = null,
+  valueSummary = null,
+  kind = 'unclassified',
+  discipline = 'unclassified',
+  parallelSafe = null,
+  newcomerFriendly = false,
+  needsMigration = false,
+  securitySensitive = false,
+  requiresRank = null,
+  moduleKey = null,
+  // BV1.R60 / ADR 0086 §3: goal-authored tasks stamp the goal they were created
+  // under (POST /goals/:id/tasks). Nullable — every other create-vector (POST
+  // /tasks, capture, restock, discord-bugs, seeds) omits it and creates a
+  // goal-less task exactly as before. The rank floor still auto-derives above
+  // (requiresRank stays null for the goal vector → derived purely from touches +
+  // sensitivity), so goal_id never influences the requires_rank clamp.
+  goalId = null,
+}, deps = {}) { // deps.client enlists this INSERT in the CALLER'S transaction (task 1003065, BV1.R01); the argument for it is at modules/ideas/inbox.js routeIdeaToGoal
+  // task 1498 / ADR 0085: every task carries a deliberate rank floor. Derive it
+  // from touches + sensitivity, then let an explicit requiresRank override only
+  // UPWARD (highestRank) — a requested rank below the derived floor is clamped
+  // up to the floor (fail-closed; the floor mirrors the trust-boundary paths a
+  // sub-Metic builder cannot push to anyway).
+  const requiresRankEffective = highestRank(
+    deriveRequiredRank(touches, securitySensitive),
+    requiresRank ?? 'xenos'
+  );
+  // task 1677 / ADR 0096 (2026-06-28): creation is now the PRIMARY reward-assignment
+  // point — every task is born with a fair drachmae value, not just at promote/claim.
+  // When the caller supplies NO positive credits_reward (null/undefined/0), auto-assign
+  // the capped (<=REWARD_SUGGESTION_CAP) suggestion from kind + est_minutes here, at the
+  // lowest create layer, so EVERY create-vector (POST /tasks, idea-promotion, capture,
+  // newcomer-restock, discord-bugs, seed scripts) inherits creation-time assignment.
+  // An explicitly-provided POSITIVE value is respected (author-set, never overridden).
+  // The promote/claim auto-assign (tasks 1670/1673) stays as a backstop for any legacy
+  // or edge path that still births a 0-reward row. Cost-plus session reward (ADR 0054)
+  // remains the ungameable primary pay driver; this per-task value is a capped floor.
+  let creditsRewardEffective = creditsReward;
+  if (rewardMissing(creditsRewardEffective)) {
+    creditsRewardEffective = suggestCreditsReward({ est_minutes: estMinutes, kind });
+  }
+  // task 1763: every task belongs to a goal. The goal-authored vector (POST
+  // /goals/:id/tasks) passes goalId; every OTHER vector (POST /tasks, capture,
+  // newcomer-restock, discord-bugs, seeds) omits it — so default a goal-less task
+  // into its version's catch-all "<version> — general" goal here, at the lowest
+  // create layer, so the invariant holds for all of them without touching each
+  // caller. If the version has no general goal the fallback is null and the task
+  // is created goal-less exactly as before — a creator must never be broken.
+  let goalIdEffective = goalId;
+  if (goalIdEffective == null) {
+    goalIdEffective = await generalGoalIdForVersion(versionId);
+  }
+  const { rows } = await (deps.client || pool).query(
+    `INSERT INTO tasks (version_id, title, description, status, touches,
+                        est_minutes, est_cost_usd, manual_degree, priority,
+                        automation_tag, credits_reward, source, source_ref, value_summary,
+                        kind, discipline, parallel_safe, newcomer_friendly, needs_migration,
+                        security_sensitive, requires_rank, module_key, goal_id, promoted_at)
+     VALUES ($1, $2, $3, $4, $5,
+             $6, $7, $8, $9,
+             $10, $11, $12, $13, $14,
+             $15, $16, $17, $18, $19,
+             $20, $21, $22, $23,
+             CASE WHEN $4 IN ('ready','active') THEN now() ELSE NULL END)
+     RETURNING *`,
+    [
+      versionId,
+      title,
+      description,
+      status,
+      touches,
+      estMinutes,
+      estCostUsd,
+      manualDegree,
+      priority,
+      automationTag,
+      creditsRewardEffective,
+      source,
+      sourceRef,
+      valueSummary,
+      kind,
+      discipline,
+      parallelSafe,
+      newcomerFriendly === true,
+      needsMigration === true,
+      securitySensitive === true,
+      requiresRankEffective,
+      moduleKey ?? null,
+      goalIdEffective ?? null,
+    ]
+  );
+  // task 1677 / ADR 0096: audit each creation-time auto-assignment so the trail is
+  // complete (the visible credits_reward on the row is the other half). Only logs
+  // when we actually filled an unset reward — an explicit positive value is silent.
+  if (rewardMissing(creditsReward) && rows[0]) {
+    console.log(
+      `[reward-gate] AUTO-ASSIGN task ${rows[0].id} credits_reward -> ${creditsRewardEffective} (cap ${REWARD_SUGGESTION_CAP}) [creation]`
+    );
+  }
+  return rows[0];
+}
+
+// task 386 (idea #85): app-level idempotency for the POST /tasks create-vector.
+// Returns the EARLIEST existing task carrying this (source, source_ref) pair, or
+// null when either is absent. Keyed on (source, source_ref) — the exact pair
+// cost_log already dedups on (see logCost: `ON CONFLICT (source, source_ref)`) —
+// so a re-submitted create (a retried POST, a capture re-run) resolves to the
+// original row instead of silently minting a duplicate.
+//
+// Deliberately NOT a DB unique constraint: the tasks table already carries
+// historical (source, source_ref) duplicates (the very bug this closes — e.g.
+// #248 dup of #252), so `CREATE UNIQUE INDEX` would fail to build on deploy. The
+// Archon-only, low-frequency POST /tasks vector makes the SELECT-then-insert race
+// window irrelevant. The other create-vectors (newcomer-restock, triage
+// promotion, discord-bugs) call createTask directly and own their own dedup, so
+// route-level idempotency leaves them untouched. #538 test seam mirrored.
+
+async function findTaskBySourceRef({ source, sourceRef } = {}, deps = {}) {
+  if (source == null || sourceRef == null || sourceRef === '') return null;
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const { rows } = await activePool.query(
+    `SELECT * FROM tasks
+      WHERE source = $1 AND source_ref = $2
+      ORDER BY id ASC
+      LIMIT 1`,
+    [source, sourceRef]
+  );
+  return rows[0] ?? null;
+}
+
+// newcomerInstanceStats (the evergreen-chore supply read) carved into
+// modules/onboarding/db.js (BV1.R81 / ADR 0093 §1) — it backs the onboarding
+// module's newcomer-restock and is part of that domain's data layer.
+
+// updateTaskColumn (task 1086, C2) — the single-column task setters below were
+// byte-identical except for the column name and (security_sensitive) a boolean
+// coercion. One allowlisted helper backs them all. The ALLOWLIST gates the
+// interpolated column name as defense-in-depth: callers pass a hard-coded literal,
+// never user input, so this can never become SQL injection.
+
+const TASK_SETTER_COLUMNS = new Set([
+  'kind', 'discipline', 'newcomer_friendly', 'security_sensitive', 'parallel_safe', 'automation_tag',
+  'needs_migration', 'module_key', 'description',
+]);
+
+async function updateTaskColumn(id, column, value) {
+  if (!TASK_SETTER_COLUMNS.has(column)) {
+    throw new Error(`updateTaskColumn: column "${column}" is not an allowed task setter`);
+  }
+  const { rows } = await pool.query(
+    `UPDATE tasks SET ${column} = $1, updated_at = now() WHERE id = $2 RETURNING *`,
+    [value, id]
+  );
+  return rows[0] ?? null;
+}
+
+
+// task 1763: (re)assign a task's goal_id. Deliberately NOT a TASK_SETTER_COLUMNS
+// flag — goal_id is a FK the PATCH /tasks/:id route validates (goal exists + same
+// version as the task) before calling this, so it stays a dedicated setter rather
+// than a bare allowlisted column. updated_at bumps like the flag setters.
+// createCriterion — add a done-when criterion to a version at RUNTIME (the
+// POST /versions/:id/done-when Archon route). ADR 0105 moved scope-truth seeds
+// out of the normal migration path, so a brand-new criterion on a running
+// instance can't be added by a plain migration; this is the live vector a
+// planning session uses. sort_order defaults to max(existing)+1 (mirrors the
+// criterion-proposal ratify path). Throws 23505 on a duplicate (version_id,
+// criterion_id) — the route maps that to 409.
+async function createCriterion({ versionId, criterionId, criterionMd, goalId = null, sortOrder = null }) {
+  let order = sortOrder;
+  if (order == null) {
+    const { rows: maxRows } = await pool.query(
+      `SELECT COALESCE(MAX(sort_order), 0) + 1 AS next FROM done_when_criteria WHERE version_id = $1`,
+      [versionId]
+    );
+    order = maxRows[0].next;
+  }
+  const { rows } = await pool.query(
+    `INSERT INTO done_when_criteria (version_id, criterion_id, criterion_md, goal_id, sort_order)
+     VALUES ($1, $2, $3, $4, $5)
+     RETURNING id, version_id, criterion_id, criterion_md, goal_id, sort_order, satisfied`,
+    [versionId, criterionId, criterionMd, goalId, order]
+  );
+  return rows[0];
+}
+
+async function updateTaskGoal(id, goalId) {
+  const { rows } = await pool.query(
+    `UPDATE tasks SET goal_id = $1, updated_at = now() WHERE id = $2 RETURNING *`,
+    [goalId, id]
+  );
+  return rows[0] ?? null;
+}
+
+
+async function updateTaskKind(id, kind) { return updateTaskColumn(id, 'kind', kind); }
+
+// task 1002647 (choke-point map s4.3): the task body is a load-bearing prompt —
+// it was settable only at create, un-editable at every rank. Editable now under
+// the same task.edit permission as the other planning fields; the global
+// write-audit middleware captures each edit's new body in audit_log.
+async function updateTaskDescription(id, description) { return updateTaskColumn(id, 'description', description); }
+
+
+async function updateTaskDiscipline(id, discipline) { return updateTaskColumn(id, 'discipline', discipline); }
+
+// #360 / ADR 0018 + V3.R15 #239: open (or close) a task to Xenos claims by
+// marking it newcomer_friendly. Default false; an Archon sets it true to let
+// the sandboxed entry rank claim+ship this task. (Column was renamed from
+// xenos_claimable → newcomer_friendly in migration 039 — the property describes
+// the *task*, not "who is allowed".) (The legacy updateTaskXenosClaimable alias
+// was removed in the task-874 dead-code sweep — it had zero callers.)
+
+async function updateTaskNewcomerFriendly(id, newcomerFriendly) { return updateTaskColumn(id, 'newcomer_friendly', newcomerFriendly); }
+
+// task 990 / migration 084 — flag a task security-sensitive (or not). When set,
+// its ship broadcast routes ONLY to the Archon-only #security-ship-feed channel
+// (ship.js chooseBroadcastTargets), never the public #ship-news / #ship-feed.
+// Explicit, never heuristic: a misfire leaks an unpatched exploit. Boolean only
+// (the === true coercion below preserves the boolean-only contract).
+
+async function updateTaskSecuritySensitive(id, securitySensitive) {
+  // task 1498 / ADR 0085: flagging a task security_sensitive RAISES its rank
+  // floor (a now-sensitive task must require Metic+). Recompute and ratchet
+  // requires_rank UP in the same atomic UPDATE so the two columns can't diverge;
+  // never lower it (an existing 'metic'/'archon' may be a protected-touch floor
+  // or a deliberate override — flipping the flag off doesn't drop the gate; an
+  // Archon can PATCH requires_rank down to the derived floor explicitly).
+  const sec = securitySensitive === true;
+  const { rows } = await pool.query(
+    `UPDATE tasks
+        SET security_sensitive = $1,
+            requires_rank = CASE WHEN $1 AND requires_rank IN ('xenos', 'thetes')
+                                 THEN 'metic' ELSE requires_rank END,
+            updated_at = now()
+      WHERE id = $2
+      RETURNING *`,
+    [sec, id]
+  );
+  return rows[0] ?? null;
+}
+
+// task 1498 / ADR 0085: set a task's rank floor explicitly (the Archon override).
+// The DERIVED floor (touches + security_sensitive) is a HARD minimum — a request
+// below it is clamped UP via highestRank, so an override can only RAISE the bar,
+// never open a sensitive task to a lower rank. `requiresRank` is one live rank
+// (xenos|thetes|metic|archon); the route validates the enum. Returns the updated
+// row, or null when the task is missing.
+
+async function updateTaskRequiresRank(id, requiresRank) {
+  const task = await getTask(id);
+  if (!task) return null;
+  const floor = deriveRequiredRank(task.touches, task.security_sensitive);
+  const effective = highestRank(floor, requiresRank ?? 'xenos');
+  const { rows } = await pool.query(
+    `UPDATE tasks SET requires_rank = $1, updated_at = now() WHERE id = $2 RETURNING *`,
+    [effective, id]
+  );
+  return rows[0] ?? null;
+}
+
+// ---------------------------------------------------------------------------
+// task 1670 / ADR 0096 — require a credits_reward (drachmae) before a task is
+// workable. credits_reward defaults to 0 (migration 003); historically a task
+// could be promoted to 'ready' and claimed+shipped while paying 0 drachmae. The
+// gate below makes a present, positive reward a precondition for the two
+// workable transitions (promote-to-ready + claim). It is AUTHOR-SET, never
+// auto-derived (ADR 0023 anti-gaming): we may SUGGEST a value, never apply it.
+//
+// Pure helpers so the route + the claim path + the unit tests all share one
+// source of truth (the deriveRequiredRank/highestRank precedent).
+// ---------------------------------------------------------------------------
+
+// A "fully unrewarded" task is one whose credits_reward is NULL or <= 0.
+function rewardMissing(creditsReward) {
+  return creditsReward === null || creditsReward === undefined || Number(creditsReward) <= 0;
+}
+
+// Suggest a starting drachmae value — derived from est_minutes scaled by a
+// coarse per-kind weight (ADR 0023 kind multipliers). ~1 drachma/min of
+// estimated work, floored at 5 so a tiny task still names a non-zero number,
+// and CAPPED at REWARD_SUGGESTION_CAP.
+//
+// task 1673 / ADR 0096 amendment (2026-06-28): the gate shifted from BLOCK to
+// AUTO-ASSIGN — this value is now PERSISTED onto the task at the promote/claim
+// gate, not merely suggested. That reverses ADR 0023's "never auto-derive"
+// stance for the *gate-time backstop only*, so the cap below is load-bearing
+// anti-gaming: it bounds how much est-inflation can balloon an auto-assigned
+// payout. The ungameable cost-plus session reward (ADR 0054) stays the PRIMARY
+// pay driver; this per-task value is a modest, capped floor. Anyone wanting more
+// than the cap must still set credits_reward by hand via PATCH /tasks/:id
+// (author-set, review-gated — the ADR 0023 path is intact for explicit values).
+const KIND_REWARD_WEIGHT = {
+  feature: 1.0, bug: 1.25, infra: 1.0, refactor: 0.85, spike: 0.75,
+  'learning-capture': 0.75, cleanup: 0.6, decision: 1.0, 'blocker-resolution': 1.25,
+  unclassified: 1.0,
+};
+const REWARD_SUGGESTION_CAP = 60; // drachmae — anti-gaming ceiling on the auto-assigned value
+function suggestCreditsReward({ est_minutes, kind } = {}) {
+  const mins = Number(est_minutes);
+  const base = Number.isFinite(mins) && mins > 0 ? mins : 30; // default ~30-min task
+  const weight = KIND_REWARD_WEIGHT[kind] ?? 1.0;
+  const raw = Math.max(5, Math.round(base * weight));
+  return Math.min(REWARD_SUGGESTION_CAP, raw); // capped so est-inflation can't balloon pay
+}
+
+// task 1673 / ADR 0096 amendment (2026-06-28): AUTO-ASSIGN at the gate instead
+// of BLOCKING. The shared decision helper for the promote route + the claim
+// backstop. Given a task, decide whether the reward gate needs to ACT:
+//   - returns { assign: N } when the task is unrewarded AND not grandfathered —
+//     the caller must persist credits_reward = N (the capped suggestion) and
+//     PROCEED (no refusal). Grandfathered/exempt rows that are still 0 also get
+//     a real value here, so the ~27 reward_gate_exempt tasks earn a fair payout
+//     when claimed.
+//   - returns null when the task already has a positive reward (nothing to do).
+// `grandfathered` is retained for signature back-compat; it no longer suppresses
+// the assignment (we WANT to value the grandfathered zero-reward tasks), so the
+// reward_gate_exempt column is now inert — see the ADR amendment.
+function rewardGateAssignment(task) {
+  if (!task) return null;
+  if (!rewardMissing(task.credits_reward)) return null;
+  return { assign: suggestCreditsReward(task) };
+}
+
+// Back-compat shim. The pre-1673 gate BLOCKED with this error object; callers and
+// the unit tests referenced it. The gate now AUTO-ASSIGNS, so the wired callers
+// no longer consult it — kept exported so any stale external reference resolves,
+// returning null (no refusal) when a reward is present.
+function rewardGateError(task, { grandfathered = false } = {}) {
+  if (!task) return null;
+  if (grandfathered || task.reward_gate_exempt === true) return null;
+  if (!rewardMissing(task.credits_reward)) return null;
+  const suggested = suggestCreditsReward(task);
+  return { code: 'REWARD_REQUIRED', suggested };
+}
+
+// Persist an auto-assigned credits_reward. Standalone (own pool query) variant
+// for the promote route. Logs an AUDIT line so every auto-assignment is traceable
+// (the visible credits_reward change is the other half of the audit trail).
+async function setCreditsReward(id, value) {
+  const { rows } = await pool.query(
+    `UPDATE tasks SET credits_reward = $1, updated_at = now() WHERE id = $2 RETURNING id, credits_reward`,
+    [value, id]
+  );
+  console.log(`[reward-gate] AUTO-ASSIGN task ${id} credits_reward -> ${value} (cap ${REWARD_SUGGESTION_CAP}) [promote]`);
+  return rows[0] ?? null;
+}
+
+// migration 028 — flag a task safe (or not) to run alongside others in a
+// parallel autonomous run. Accepts true | false | null (null = un-judged).
+
+async function updateTaskParallelSafe(id, parallelSafe) { return updateTaskColumn(id, 'parallel_safe', parallelSafe); }
+
+// Recategorize a task's automation_tag mid-life so the autonomous overnight
+// runner's --fit filter (tasks_session_fit view, migration 028) can pick it
+// up — or drop it. Accepts 'overnight-safe' | 'live-only' | 'needs-input' |
+// null. Surfaced because at task-creation triage we are often conservative
+// and leave the tag unset, then later judge that a task is safe to delegate.
+
+async function updateTaskAutomationTag(id, automationTag) { return updateTaskColumn(id, 'automation_tag', automationTag); }
+
+// task 1002648: correct the create-time migration heuristic's verdict — a false
+// flag makes claiming reserve a migration number that goes unused (task 1002614
+// burned 213 that way). Boolean only; the route validates.
+async function updateTaskNeedsMigration(id, needsMigration) { return updateTaskColumn(id, 'needs_migration', needsMigration === true); }
+
+// BV1.R53 (task 1422): assign (or clear) the module_key that declares which
+// module this task's work belongs to. Drives module-disjointness at claim time
+// and diff⊆module enforcement at ship time. Accepts any key in MODULE_SCOPE_MAP,
+// or null to clear. Validation happens in the route; this just writes the column.
+
+async function updateTaskModuleKey(id, moduleKey) { return updateTaskColumn(id, 'module_key', moduleKey); }
+
+// touches[] cleanup [4/8] (task 879): updateTaskTouches() was removed with the
+// drift scanner + the PATCH /tasks/:id touches branch + ship's drift-expand
+// flow. touches[] is no longer mutated mid-claim — a wrong up-front prediction
+// is repaired (when it matters at all) by git merge / the claim-time overlap
+// guard, not by rewriting the array. The claim-time parallel-safety invariant
+// it duplicated still lives in claimTask().
+
+
+// task 1957: credits_awarded is the ACTUAL drachmae paid out for completing a
+// task — the sum of the TASK-REWARD credit_log deltas booked against it: the
+// per-task credit (= credits_reward × kind-multiplier), the idea-promotion
+// bonus, and the net-negative (simplification) bonus, across all builders. The
+// reason allowlist is deliberate: achievement unlocks ('achievement.*') also
+// carry the shipped task's id but are GAMIFICATION, not a reward for the task,
+// so they must NOT inflate the payout (session.token_reward and rank_change
+// carry task_id=NULL and are excluded already).
+//
+// ADR 0120 "pay on land": the per-task credit reason is now 'task.shipped'
+// (booked at the confirmed→shipped flip) instead of 'task.confirmed' (booked at
+// confirm). BOTH strings are allow-listed: historical tasks confirmed under the
+// old rule carry 'task.confirmed' rows, new landings carry 'task.shipped', and
+// the one-time clawback reverses the old 'task.confirmed' deltas (a negative
+// row nets them to 0) — so summing both is correct across the transition. The
+// CASE still short-circuits to 0 for unsettled tasks; note a 'confirmed' task
+// now shows 0 until it LANDS (the credit no longer exists at confirm) — the UI
+// renders the "Est." label until the 'task.shipped' row books at land.
+const CREDITS_AWARDED_SUBQUERY =
+  `CASE WHEN t.status IN ('confirmed', 'shipped')
+        THEN (SELECT COALESCE(SUM(cl.delta), 0)::int
+                FROM credit_log cl
+               WHERE cl.task_id = t.id
+                 AND cl.reason IN ('task.confirmed', 'task.shipped', 'idea_promotion_bonus', 'ship.net_negative'))
+        ELSE 0 END`;
+
+async function getTask(id) {
+  const { rows } = await pool.query(
+    `SELECT t.*, ${CREDITS_AWARDED_SUBQUERY} AS credits_awarded,
+            pms_calibrated_minutes(t.est_minutes, t.kind) AS est_minutes_calibrated
+       FROM tasks t WHERE t.id = $1`,
+    [id]
+  );
+  return rows[0] ?? null;
+}
+
+
+async function listTasks({ versionId, status, kind, discipline, goalId } = {}) {
+  const params = [];
+  const where = [];
+  if (versionId) {
+    params.push(versionId);
+    where.push(`version_id = $${params.length}`);
+  }
+  if (status) {
+    params.push(status);
+    where.push(`status = $${params.length}`);
+  }
+  if (kind) {
+    params.push(kind);
+    where.push(`kind = $${params.length}`);
+  }
+  if (discipline) {
+    params.push(discipline);
+    where.push(`discipline = $${params.length}`);
+  }
+  if (goalId) {
+    params.push(goalId);
+    where.push(`goal_id = $${params.length}`);
+  }
+  const sql =
+    `SELECT t.*, ${CREDITS_AWARDED_SUBQUERY} AS credits_awarded,
+            pms_calibrated_minutes(t.est_minutes, t.kind) AS est_minutes_calibrated
+       FROM tasks t` +
+    (where.length ? ` WHERE ${where.join(' AND ')}` : '') +
+    ` ORDER BY priority NULLS LAST, created_at`;
+  const { rows } = await pool.query(sql, params);
+  return rows;
+}
+
+// Tasks that are ready, unblocked, and have no touches[] overlap
+// with currently active claims. Excludes tasks already claimed by this
+// builder (so the same builder doesn't see their own active claim listed
+// as "claimable").
+// `fit` (optional) narrows the list to tasks that are safe to run in an
+// autonomous/overnight session-runner (task #358):
+//   'autonomous' — autonomous-fit per the canonical tasks_session_fit view
+//                  ('autonomous' ∈ fits_session_modes, i.e. overnight-safe +
+//                  manual_degree<=2 + unblocked). claimable_tasks already
+//                  excludes blocked tasks, but we join the view so the
+//                  definition of "autonomous" lives in exactly one place.
+//   'parallel'   — autonomous-fit AND tasks.parallel_safe = true (the planning
+//                  judgment that a task is safe to run alongside others).
+//
+// SR-12 / finding G2 (task 994) — PROTECTED-PATH EXCLUSION for autonomous fit.
+// The overnight-builder runs as Archon and direct-pushes to main; every
+// write-side gate keys on the AUTHOR's rank and only blocks authors BELOW Metic,
+// so an archon-authored autonomous commit sails through all of them. A task's
+// `description` originates (via idea-triage promotion) from idea_inbox.body_md,
+// which any xenos / unlinked Discord user can seed — so attacker-seeded text can
+// reach an archon-authority agent. To stop a seeded directive from reaching the
+// permission/methodology/deploy CORE unreviewed, any --fit task whose declared
+// touches[] overlap a permission-sensitive path (the ADR 0043 protected set) is
+// EXCLUDED from the autonomous/parallel feed. Those tasks still appear in the
+// normal interactive claimable list — a human must own them; an autonomous run
+// never can. This is a HARD control (a JS post-filter on the fit query), not a
+// soft prompt instruction. Backstops the SKILL.md fencing (layer 1).
+
+// task 2181 (incident, blocker 74): these are the EXACT bodies of the
+// claimable_tasks and tasks_session_fit views (migration
+// core_190_rebuild_claimable_task_views.sql), inlined as subqueries so the
+// claimable feed reads base tables (ACCESS SHARE only) instead of the views.
+// A detached backend queued an ACCESS EXCLUSIVE DDL on the views, which parks
+// every view SELECT behind it in the lock queue — the hall's primary feed hung
+// indefinitely while raw-table reads stayed fast. Postgres inlines simple
+// views into the same plan anyway, so this is semantics- and plan-identical;
+// it just stops the query's LOCKING from referencing the view relations.
+// If the view bodies change in a future migration, change these in lockstep
+// (or fold back to the views once per-view DDL contention is a solved problem).
+const CLAIMABLE_SQL = `
+  SELECT t.*, pms_calibrated_minutes(t.est_minutes, t.kind) AS est_minutes_calibrated
+    FROM tasks t
+   WHERE t.status = 'ready'
+     AND t.title NOT LIKE '\\_\\_smoke\\_\\_%' ESCAPE '\\'
+     AND NOT EXISTS (
+       SELECT 1 FROM task_blockers tb WHERE tb.task_id = t.id
+     )
+     AND NOT EXISTS (
+       SELECT 1 FROM claims c
+         JOIN tasks t2 ON t2.id = c.task_id
+        WHERE c.released_at IS NULL
+          AND t2.touches && t.touches
+     )`;
+const SESSION_FIT_SQL = `
+  SELECT t.id,
+    CASE
+      WHEN t.automation_tag = 'overnight-safe' AND COALESCE(t.manual_degree, 5) <= 2
+           AND NOT EXISTS (SELECT 1 FROM task_blockers tb WHERE tb.task_id = t.id)
+        THEN ARRAY['autonomous','check-in','active']
+      WHEN t.automation_tag = 'live-only' OR COALESCE(t.manual_degree, 5) >= 4
+        THEN ARRAY['active']
+      ELSE ARRAY['check-in','active']
+    END AS fits_session_modes
+    FROM tasks t`;
+
+async function listClaimableTasks({ versionId = null, builderId = null, discipline = null, fit = null } = {}) {
+  const params = [];
+  const where = [];
+  let goalJoin = '';
+  let selectCols = 'v.*';
+  if (versionId) {
+    params.push(versionId);
+    where.push(`v.version_id = $${params.length}`);
+  }
+  if (discipline) {
+    params.push(discipline);
+    where.push(`v.discipline = $${params.length}`);
+  }
+  if (builderId) {
+    params.push(builderId);
+    where.push(`NOT EXISTS (
+      SELECT 1 FROM claims c2
+       WHERE c2.task_id = v.id
+         AND c2.builder_id = $${params.length}
+         AND c2.released_at IS NULL
+    )`);
+    // V3.R15 #239: view-level sandbox gate. A sandboxed builder sees ONLY
+    // newcomer_friendly tasks in the claimable feed; the live general-queue
+    // ranks see everything. The view itself is builder-agnostic (views can't
+    // read session context), so the filter is realized here at SELECT time.
+    // Belt-and-braces with the row-level check in claimTask, which still throws
+    // rank_too_low_for_task at claim time.
+    // #510: FAIL CLOSED — allowlist the general-queue ranks {thetes, metic,
+    // archon} (mirrors GENERAL_QUEUE_RANKS / xenosClaimAllowed in JS) rather than
+    // the old `<> 'xenos'` test, which failed OPEN (any reserved/unknown/typo
+    // rank — or a NULL from a missing lookup — was treated as privileged and
+    // shown the whole queue). thetes is live (#692 / ADR 0034) so it stays in.
+    where.push(`(
+      (SELECT rank FROM builders WHERE id = $${params.length}) IN ('thetes', 'metic', 'archon')
+      OR v.newcomer_friendly = true
+    )`);
+    // V3.R82 #301: view-level requires_rank floor. The CASE expressions map
+    // both sides to the live tier; a builder is shown a task iff their tier >=
+    // the task's required tier. The tiers MUST mirror REQUIRES_RANK_TIER in JS
+    // (xenos=1, thetes=2, metic=3, archon=4 — thetes added #692 / mig 068);
+    // any rank outside the four live ones collapses to 0 and is gated out —
+    // same fail-closed behaviour as rankAllowsTask in JS. Same parameter index
+    // as the xenos gate above ($${params.length}) because both refer to the
+    // same builderId.
+    where.push(`(
+      CASE (SELECT rank FROM builders WHERE id = $${params.length})
+        WHEN 'archon' THEN 4 WHEN 'metic' THEN 3 WHEN 'thetes' THEN 2 WHEN 'xenos' THEN 1 ELSE 0
+      END
+    ) >= (
+      CASE COALESCE(v.requires_rank, 'xenos')
+        WHEN 'archon' THEN 4 WHEN 'metic' THEN 3 WHEN 'thetes' THEN 2 WHEN 'xenos' THEN 1 ELSE 0
+      END
+    )`);
+    // task 1003137: ride the goal + own-membership facts along so
+    // decorateGoalMembership (claim-feed.js) can flag non-member rows joinable.
+    // Same parameter index — all three reads are the same builderId. The
+    // goal_members PK (goal_id, builder_id) means the LEFT JOIN never
+    // multiplies rows; an Archon reads as member (isMemberOrArchon convention).
+    goalJoin = ` LEFT JOIN goals g ON g.id = v.goal_id
+                 LEFT JOIN goal_members gm ON gm.goal_id = g.id AND gm.builder_id = $${params.length}`;
+    selectCols = `v.*, g.visibility AS g_visibility, g.scope_modules AS g_scope_modules, g.title AS g_title,
+      (gm.builder_id IS NOT NULL
+        OR (SELECT rank FROM builders WHERE id = $${params.length}) = 'archon') AS g_is_member`;
+  }
+  // Autonomy / parallel-eligibility filter. Joining the session-fit relation
+  // (also a SELECT t.* shape) makes bare column names like priority/created_at
+  // ambiguous, so the ORDER BY below qualifies them with v. unconditionally.
+  let fitJoin = '';
+  if (fit === 'autonomous' || fit === 'parallel') {
+    fitJoin = ` JOIN (${SESSION_FIT_SQL}) sf ON sf.id = v.id`;
+    where.push(`'autonomous' = ANY(sf.fits_session_modes)`);
+    if (fit === 'parallel') {
+      where.push(`v.parallel_safe = true`);
+    }
+  }
+  // Order by calibrated estimate (falls back to raw when calibrator returns NULL
+  // — e.g. unestimated tasks). Calibrated reflects realistic time-to-ship given
+  // recent actuals; ordering on the raw estimate puts oversized tasks at the
+  // bottom even when their actual time-to-ship is short. See migration 015.
+  const sql =
+    `SELECT ${selectCols} FROM (${CLAIMABLE_SQL}) v` + goalJoin + fitJoin +
+    (where.length ? ` WHERE ${where.join(' AND ')}` : '') +
+    ` ORDER BY v.priority NULLS LAST,
+              COALESCE(v.est_minutes_calibrated, v.est_minutes) NULLS LAST,
+              v.created_at`;
+  const { rows: rawRows } = await pool.query(sql, params);
+  // task 1003137: strip g_* scratch columns, flag non-member rows joinable.
+  const rows = rawRows.map(decorateGoalMembership);
+  // SR-12 / G2 (task 994): when the autonomous/parallel runner is asking, drop
+  // any task whose declared touches[] reach the permission/methodology/deploy
+  // core. The runner ships as Archon straight to main, so these must never be
+  // claimed unsupervised — a human owns them. Applied in JS (not SQL) so it
+  // reuses the single canonical protected-path matcher (matchProtected) shared
+  // with the grader pre-pass, pre-push hook, and main-audit — no second source
+  // of truth to drift.
+  if (fit === 'autonomous' || fit === 'parallel') {
+    // task 1003137: membership-required rows are DROPPED, not flagged — the
+    // claim gate will refuse them and an autonomous runner can't answer a join
+    // prompt. (No builderId → no membership facts; the claim gate stays the
+    // hard control.)
+    return rows.filter((t) => !taskTouchesProtectedPath(t)
+      && !(t.goal_membership && t.goal_membership.required === true));
+  }
+  // Newcomer-chore display cap (task 1266, owner decision 2026-06-19). The
+  // newcomer-floor keeps a deep supply pool (floor: 3 artist + 2 ideator) so
+  // several newcomers arriving at once each have something to grab — but that
+  // pool depth is a CROSS-BUILDER supply concept, not one person's to-do list.
+  // Shown raw, a single artist+ideator sees five near-identical "Same as above"
+  // seats. Cap the newcomer_friendly rows in the human-facing feed to 3 so the
+  // menu maps to the Xenos->Thetes bar (ship 3 works). Reached only on the
+  // human/default path — the autonomous/parallel runner returned above and is
+  // untouched. The floor replenisher counts ready+backlog rows and is likewise
+  // unaffected (it never reads this feed).
+  return capNewcomerTasks(rows);
+}
+
+// SR-12 / G2 (task 994): does this task's declared touches[] overlap any
+// permission-sensitive (ADR 0043) path? Pure + exported for unit testing.
+// Returns true if ANY declared touch matches a protected glob — such a task is
+// off-limits to the autonomous runner regardless of who would author it,
+// because the runner authors as Archon and the write-side gates can't catch a
+// high-rank automated author acting on attacker-seeded task text.
+//
+// A task with NO declared touches[] is treated as SAFE for the feed (returns
+// false): touches[] is advisory at ship time (ADR 0049), so an empty list is
+// the common honest case (e.g. a small game/doc task), not a signal of danger
+// — and the autonomous fit pool is already narrowed to overnight-safe +
+// manual_degree<=2 + unblocked tasks. The exclusion fires only on a POSITIVE
+// match against a declared protected path.
+
+function taskTouchesProtectedPath(task) {
+  const touches = Array.isArray(task && task.touches) ? task.touches : [];
+  if (touches.length === 0) return false;
+  return matchProtected(touches).length > 0;
+}
+
+// Cross-discipline recommendations for /builder-start (V3.R81 / #299).
+//
+// Given the full claimable list and the builder's preferred_disciplines,
+// returns up to `limit` tasks whose discipline is OUTSIDE the builder's
+// preferences — the "you might enjoy" section. Pure function (no DB round
+// trip): the caller already holds the claimable rows, so we just partition
+// and rank them.
+//
+// Ranking key (most relevant first):
+//   1. priority DESC          — a P5 in another lane still beats a P1
+//   2. credits-per-minute DESC — best bang-for-effort among equal priority
+//   3. est_minutes ASC         — shorter wins the tiebreak (easier to try)
+//   4. id ASC                  — stable final tiebreak
+//
+// 'unclassified' tasks are excluded: they're un-triaged, not a real lane to
+// recommend exploring. If preferred_disciplines is empty (no preference), the
+// builder already sees everything in the main list, so there is nothing
+// "outside" to recommend — return [].
+
+function rankCrossDisciplineRecommendations(claimable, preferredDisciplines, limit = 3) {
+  const rows = Array.isArray(claimable) ? claimable : [];
+  const prefs = Array.isArray(preferredDisciplines) ? preferredDisciplines : [];
+  // No stated preference → no "outside", nothing to recommend.
+  if (prefs.length === 0) return [];
+  const prefSet = new Set(prefs);
+  const cpm = (t) => {
+    const credits = Number(t.credits_reward) || 0;
+    const mins = Number(t.est_minutes_calibrated ?? t.est_minutes) || 0;
+    return mins > 0 ? credits / mins : 0;
+  };
+  const outside = rows.filter(
+    (t) => t.discipline && t.discipline !== 'unclassified' && !prefSet.has(t.discipline)
+  );
+  outside.sort((a, b) => {
+    const pa = Number(a.priority) || 0;
+    const pb = Number(b.priority) || 0;
+    if (pb !== pa) return pb - pa; // higher priority first
+    const ca = cpm(a);
+    const cb = cpm(b);
+    if (cb !== ca) return cb - ca; // higher credits/min first
+    const ma = Number(a.est_minutes_calibrated ?? a.est_minutes) || Infinity;
+    const mb = Number(b.est_minutes_calibrated ?? b.est_minutes) || Infinity;
+    if (ma !== mb) return ma - mb; // shorter first
+    return (Number(a.id) || 0) - (Number(b.id) || 0); // stable
+  });
+  return outside.slice(0, Math.max(0, limit));
+}
+
+// What's currently active across all builders. Used by /builder-start
+// for the "in-flight" sidebar so a builder can see who else is on what.
+
+async function listActiveClaims() {
+  const { rows } = await pool.query(
+    `SELECT c.id AS claim_id, c.task_id, c.builder_id, c.worktree_name, c.claimed_at,
+            t.title, t.touches, t.version_id, t.priority,
+            b.github_login, b.display_name
+       FROM claims c
+       JOIN tasks t ON t.id = c.task_id
+       JOIN builders b ON b.id = c.builder_id
+      WHERE c.released_at IS NULL
+      ORDER BY c.claimed_at`
+  );
+  return rows;
+}
+
+
+async function updateTaskStatus(id, status) {
+  await pool.query(`UPDATE tasks SET status = $2 WHERE id = $1`, [id, status]);
+}
+
+module.exports = {
+  CREDITS_AWARDED_SUBQUERY,
+  REWARD_SUGGESTION_CAP,
+  createCriterion,
+  createTask,
+  findTaskBySourceRef,
+  generalGoalIdForVersion,
+  getTask,
+  listActiveClaims,
+  listClaimableTasks,
+  listTasks,
+  rankCrossDisciplineRecommendations,
+  rewardGateAssignment,
+  rewardGateError,
+  rewardMissing,
+  setCreditsReward,
+  suggestCreditsReward,
+  taskTouchesProtectedPath,
+  updateTaskAutomationTag,
+  updateTaskDescription,
+  updateTaskDiscipline,
+  updateTaskGoal,
+  updateTaskKind,
+  updateTaskModuleKey,
+  updateTaskNeedsMigration,
+  updateTaskNewcomerFriendly,
+  updateTaskParallelSafe,
+  updateTaskRequiresRank,
+  updateTaskSecuritySensitive,
+  updateTaskStatus,
+};