@bongos/core 1.19.358 → 1.19.360

package/modules/dev-box/app/src/vendor/bongos-client.cjs

@@ -251,6 +251,14 @@ function createClient(opts = {}) {
       // POST /claims/batch/validate — rank: any-builder — POST /claims/batch/validate
       postClaimsBatchValidate: (args) => request("POST", "/claims/batch/validate", { hasBody: true }, args),
     },
+    "closeness": {
+      // GET /closeness/for-me — rank: any-builder — GET /closeness/for-me
+      getClosenessForMe: (args) => request("GET", "/closeness/for-me", { hasBody: false }, args),
+      // GET /closeness/weights — rank: any-builder — GET /closeness/weights
+      getClosenessWeights: (args) => request("GET", "/closeness/weights", { hasBody: false }, args),
+      // GET /closeness/with/{builderId} — rank: any-builder — GET /closeness/with/:builderId
+      getClosenessWithBuilderId: (args) => request("GET", "/closeness/with/{builderId}", { hasBody: false }, args),
+    },
     "copyDesk": {
       // POST /copy-desk/flags — rank: any-builder — POST /copy-desk/flags
       postCopyDeskFlags: (args) => request("POST", "/copy-desk/flags", { hasBody: true }, args),
@@ -715,6 +723,16 @@ function createClient(opts = {}) {
       // POST /sso/token — rank: public — POST /sso/token
       postSsoToken: (args) => request("POST", "/sso/token", { hasBody: true }, args),
     },
+    "taskRecommendations": {
+      // POST /task-recommendations — rank: any-builder — POST /task-recommendations
+      postTaskRecommendations: (args) => request("POST", "/task-recommendations", { hasBody: true }, args),
+      // PATCH /task-recommendations/{id} — rank: any-builder — PATCH /task-recommendations/:id
+      patchTaskRecommendationsId: (args) => request("PATCH", "/task-recommendations/{id}", { hasBody: true }, args),
+      // GET /task-recommendations/for-me — rank: any-builder — GET /task-recommendations/for-me
+      getTaskRecommendationsForMe: (args) => request("GET", "/task-recommendations/for-me", { hasBody: false }, args),
+      // GET /task-recommendations/mine — rank: any-builder — GET /task-recommendations/mine
+      getTaskRecommendationsMine: (args) => request("GET", "/task-recommendations/mine", { hasBody: false }, args),
+    },
     "taskVisuals": {
       // GET /task-visuals/{name} — rank: public — GET /task-visuals/:name
       getTaskVisualsName: (args) => request("GET", "/task-visuals/{name}", { hasBody: false }, args),
@@ -760,6 +778,8 @@ function createClient(opts = {}) {
       postTasksIdPublishBranch: (args) => request("POST", "/tasks/{id}/publish-branch", { hasBody: true }, args),
       // GET /tasks/{id}/publish-status — rank: any-builder — GET /tasks/:id/publish-status
       getTasksIdPublishStatus: (args) => request("GET", "/tasks/{id}/publish-status", { hasBody: false }, args),
+      // GET /tasks/{id}/recommendations — rank: any-builder — GET /tasks/:id/recommendations
+      getTasksIdRecommendations: (args) => request("GET", "/tasks/{id}/recommendations", { hasBody: false }, args),
       // POST /tasks/{id}/ship — rank: any-builder — POST /tasks/:id/ship
       postTasksIdShip: (args) => request("POST", "/tasks/{id}/ship", { hasBody: true }, args),
       // DELETE /tasks/{id}/visual — rank: any-builder — DELETE /tasks/:id/visual

package/modules/lifecycle/closeness-weights.json

@@ -0,0 +1,64 @@
+{
+  "_comment": [
+    "The closeness scoring model, as DATA (task 1003174 / C04, goal 1000075; criterion",
+    "collab-closeness-consented, ADR 0187 §2). The owner's decision was explicit that the",
+    "weights are data rather than constants buried in a function, so they can be reviewed",
+    "and changed without a code-archaeology dig. This file IS that review surface, and it",
+    "is served verbatim by GET /closeness/weights so the number can always be audited",
+    "against the model that produced it.",
+    "",
+    "HOW A SCORE IS BUILT. Each signal counts real events between two builders. That count",
+    "is divided by the signal's `saturation` and clamped to 1, so a signal is 'full' once",
+    "it has happened `saturation` times and no single runaway count can dominate. The",
+    "closeness score is the weighted sum of those clamped values, expressed 0..1.",
+    "",
+    "WEIGHTS ARE RENORMALISED OVER AVAILABLE SIGNALS. A signal with `available: false`",
+    "cannot be measured yet, and its weight is redistributed across the rest rather than",
+    "counted as zero. Counting it as zero would depress every pair's score identically and,",
+    "worse, the explanation would read as 'you never talk' when the truth is 'nothing here",
+    "can see whether you talk'. The explanation names every excluded signal for this reason.",
+    "",
+    "CHANGING A WEIGHT is a product decision about how the system describes real people to",
+    "each other. Weights should sum to 1 across ALL signals (the test asserts it); the",
+    "renormalisation handles the available subset at read time."
+  ],
+
+  "version": 1,
+  "scale": "0..1, rendered as 0..100 on any surface that shows a number",
+
+  "signals": [
+    {
+      "key": "co_claim",
+      "label": "Worked the same goal at the same time",
+      "description": "You each held an active claim on a task in the same goal, and those claims overlapped in time. This is the live version of working alongside someone: you were both holding work in the same place at once.",
+      "weight": 0.3,
+      "saturation": 5,
+      "available": true
+    },
+    {
+      "key": "co_build_session",
+      "label": "Sat down to it in the same stretch",
+      "description": "You logged work sessions on tasks in the same goal that overlapped in time. A claim can sit open for days; a session is the hours actually spent, so this is the closer measure of being present together. The owner's decision (ADR 0187 §3) is that the unit of collaboration is the GOAL, never a shared claim — nobody co-runs a claim, and this signal does not pretend they do.",
+      "weight": 0.3,
+      "saturation": 5,
+      "available": true
+    },
+    {
+      "key": "shipped_together_goal",
+      "label": "Shipped into the same goal",
+      "description": "Distinct goals where you have each shipped at least one task. Unlike the two above, this ignores timing entirely — it is the durable record that you both built the same thing, even months apart.",
+      "weight": 0.25,
+      "saturation": 3,
+      "available": true
+    },
+    {
+      "key": "comms_mention",
+      "label": "Talked to or mentioned each other",
+      "description": "Messages and mentions between you. NOT MEASURABLE YET: this needs the Discord-into-the-hall mirror, which is C06 of this goal (task 1003176) and is still an open decision. Until it lands this signal is unavailable and its weight is redistributed across the others — it is never silently counted as zero, because 'we cannot see your conversations' and 'you never speak' are different facts and only one of them is true.",
+      "weight": 0.15,
+      "saturation": 20,
+      "available": false,
+      "blocked_by": "task 1003176 (C06 — Discord chat mirrors INTO the hall)"
+    }
+  ]
+}

package/modules/lifecycle/closeness.js

@@ -0,0 +1,363 @@
+// modules/lifecycle/closeness.js — how close two builders are, and WHY
+// (task 1003174 / C04, goal 1000075; criterion collab-closeness-consented,
+// ADR 0187 §2).
+//
+// THE DECISION. Closeness is a WEIGHTED BLEND — co-claims, co-build sessions,
+// goals shipped together, and comms/mentions once C06 mirrors chat in — not a
+// single signal. The owner took the blend knowing its risk, and attached two
+// conditions that are part of the deliverable rather than follow-ups:
+//
+//   1. THE WEIGHTS ARE DATA. They live in ./closeness-weights.json and are served
+//      verbatim by the route, so the model can be reviewed and changed without a
+//      code-archaeology dig. Nothing in this file hard-codes a weight.
+//
+//   2. "WHY AM I CLOSE TO THEM" IS ANSWERABLE. Every score carries its own
+//      breakdown: per signal, the raw count, what it was divided by, its weight,
+//      and what it contributed. A number that ranks real colleagues and cannot say
+//      what it is made of becomes unfair with nothing to point at, which is
+//      exactly what was raised when the blend was chosen.
+//
+// AN UNAVAILABLE SIGNAL IS NOT A ZERO. comms_mention cannot be measured until the
+// C06 mirror exists. Scoring it as zero would depress every pair identically AND
+// make the explanation say "you never talk", which is not what is true — what is
+// true is that nothing here can see whether you talk. So unavailable signals are
+// dropped and the remaining weights are renormalised, and the breakdown names what
+// was excluded and why.
+//
+// CONSENT. ADR 0171's posture is fail-closed account state with the hide flag
+// enforced in the READ path (task 1002277) — a builder who hid their profile must
+// not reappear as a node in someone else's graph. This file routes EVERY graph
+// read through one gate, `applyConsent`, rather than filtering at each call site,
+// so C05 (task 1003175, "consent is the read path, not a filter bolted on after")
+// has a single structural place to make it so. The gate FAILS CLOSED on error:
+// a consent read that throws drops the graph to empty rather than serving it.
+//
+// A KNOWN PERFORMANCE GAP, measured rather than assumed. The signal joins key on
+// tasks.goal_id (NO index), claims.builder_id and claims.task_id (indexed only
+// partially, on ACTIVE claims — closeness reads history) and tasks.shipped_by
+// (partial too). At today's size that is fine; it scales with total table size
+// rather than goal size. The indexes belong in a core_ migration, not here — a
+// module migration may only touch its own lifecycle_ tables (ADR 0083 §5), and
+// the fitness check enforces it. Filed with the SQL as task 1003268.
+//
+// Reaches core only through the doorway (ADR 0083). The core tables it reads
+// (claims, tasks, session_logs, builders) are read-only here.
+
+'use strict';
+
+const { pool } = require('../../src/module-api');
+const WEIGHTS = require('./closeness-weights.json');
+
+const MAX_ROWS = 100;
+// Signals are counted over a trailing window: a collaboration from two years ago
+// is history, not closeness. Long enough that a slow-moving goal still counts.
+const WINDOW_DAYS = 365;
+
+function capRows(n) {
+  const v = Number(n);
+  return Number.isInteger(v) && v > 0 && v <= MAX_ROWS ? v : MAX_ROWS;
+}
+
+// ---------------------------------------------------------------------------
+// The model
+// ---------------------------------------------------------------------------
+
+// The weights file, as loaded. Exposed so the route can serve it verbatim — the
+// audit surface must show the SAME data the scorer used, not a restatement.
+function weightsModel() { return WEIGHTS; }
+
+function availableSignals() { return WEIGHTS.signals.filter((s) => s.available === true); }
+function unavailableSignals() { return WEIGHTS.signals.filter((s) => s.available !== true); }
+
+// PURE. counts -> { score, breakdown, excluded }.
+//
+// `counts` is { [signalKey]: number }. Missing keys are 0 — a signal that IS
+// measurable and simply did not happen is a real zero, unlike an unavailable one.
+//
+// Returns:
+//   score      — 0..1, the weighted sum over AVAILABLE signals with weights
+//                renormalised to sum to 1 across that subset.
+//   breakdown  — one row per available signal: the count, the saturation it was
+//                measured against, the clamped value, the effective (renormalised)
+//                weight, and the contribution to the score. This IS the answer to
+//                "why am I close to them".
+//   excluded   — the unavailable signals, each with the reason, so a surface can
+//                say what the number could not see.
+function scoreCloseness(counts = {}) {
+  const avail = availableSignals();
+  const totalWeight = avail.reduce((sum, s) => sum + (Number(s.weight) || 0), 0);
+
+  // No available signal, or weights that sum to nothing, means there is no model
+  // to score with. Answer 0 with an empty breakdown rather than dividing by zero
+  // and returning NaN dressed up as a closeness.
+  if (!avail.length || totalWeight <= 0) {
+    return { score: 0, breakdown: [], excluded: unavailableSignals().map(excludedRow), scorable: false };
+  }
+
+  // Contributions are computed at full precision and the TOTAL is rounded once.
+  // Summing already-rounded rows instead lost a ten-thousandth per signal, so a
+  // pair at full on every available signal scored 0.9999 rather than 1 — a score
+  // that can never reach its own maximum is a small lie the explanation would
+  // then have to carry.
+  let raw = 0;
+  const breakdown = avail.map((s) => {
+    const count = Math.max(0, Number(counts[s.key]) || 0);
+    const saturation = Math.max(1, Number(s.saturation) || 1);
+    const value = Math.min(count / saturation, 1);
+    const effectiveWeight = (Number(s.weight) || 0) / totalWeight;
+    raw += value * effectiveWeight;
+    return {
+      key: s.key,
+      label: s.label,
+      description: s.description,
+      count,
+      saturation,
+      value: round4(value),
+      declared_weight: Number(s.weight) || 0,
+      effective_weight: round4(effectiveWeight),
+      contribution: round4(value * effectiveWeight),
+    };
+  });
+
+  const score = round4(raw);
+  return { score, breakdown, excluded: unavailableSignals().map(excludedRow), scorable: true };
+}
+
+function excludedRow(s) {
+  return {
+    key: s.key,
+    label: s.label,
+    declared_weight: Number(s.weight) || 0,
+    reason: 'not_measurable_yet',
+    // Why this matters, in the payload rather than only in a comment: a surface
+    // that shows a score must be able to say what the score could not see.
+    explanation: `This signal cannot be measured yet, so it was excluded and its weight redistributed across the others — it was NOT counted as zero.${s.blocked_by ? ` Waiting on ${s.blocked_by}.` : ''}`,
+  };
+}
+
+function round4(n) { return Math.round(n * 10000) / 10000; }
+
+// A one-sentence rendering of a breakdown, for a surface with no room for a table.
+// PURE, and built from the SAME rows the score came from, so the sentence cannot
+// drift from the arithmetic.
+function explainInWords(scored) {
+  if (!scored || !scored.scorable) return 'There is no closeness model available to score this pair.';
+  const contributing = scored.breakdown.filter((r) => r.count > 0);
+  if (!contributing.length) return 'Nothing measurable has happened between you yet.';
+  const parts = contributing
+    .slice()
+    .sort((a, b) => b.contribution - a.contribution)
+    .map((r) => `${r.label.toLowerCase()} (${r.count})`);
+  const tail = scored.excluded.length
+    ? ` Not counted: ${scored.excluded.map((e) => e.label.toLowerCase()).join(', ')} — not measurable yet.`
+    : '';
+  return `Mostly ${parts.join(', then ')}.${tail}`;
+}
+
+// ---------------------------------------------------------------------------
+// The signals, read from the live tables
+// ---------------------------------------------------------------------------
+//
+// Each read answers ONE question for one builder, and returns a Map of
+// otherBuilderId -> count. They are separate queries rather than one join so a
+// signal can be added, removed, or reweighted without touching the others — the
+// same reason the weights are data.
+//
+// EACH TAKES AN OPTIONAL `otherId`, which narrows the same query to a single pair
+// rather than the whole graph. That is deliberately a PARAMETER and not a second
+// set of pair-shaped functions: two hand-written definitions of "what a co-claim
+// is" would drift, and the one that drifted would be the one nobody reads. The
+// graph read passes null; closenessBetween passes the id.
+
+// co_claim — claims by the two builders on tasks in the SAME GOAL whose active
+// windows overlapped. `released_at IS NULL` means still open, so COALESCE to now().
+async function coClaimCounts(builderId, { otherId = null } = {}, deps = {}) {
+  const activePool = deps.pool || pool;
+  const { rows } = await activePool.query(
+    `SELECT other.builder_id AS other_id, count(DISTINCT t_mine.goal_id)::int AS n
+       FROM claims mine
+       JOIN tasks  t_mine  ON t_mine.id = mine.task_id AND t_mine.goal_id IS NOT NULL
+       JOIN tasks  t_other ON t_other.goal_id = t_mine.goal_id
+       JOIN claims other   ON other.task_id = t_other.id AND other.builder_id <> $1
+      WHERE mine.builder_id = $1
+        AND ($3::bigint IS NULL OR other.builder_id = $3)
+        AND mine.claimed_at > now() - ($2 || ' days')::interval
+        AND tstzrange(mine.claimed_at,  COALESCE(mine.released_at,  now()))
+         && tstzrange(other.claimed_at, COALESCE(other.released_at, now()))
+      GROUP BY other.builder_id`,
+    [builderId, String(WINDOW_DAYS), otherId]
+  );
+  return toCountMap(rows);
+}
+
+// co_build_session — logged work sessions on tasks in the same goal that overlapped
+// in time. Distinct from co_claim on purpose: a claim can sit open for days, a
+// session is the hours actually spent, so this is the closer measure of presence.
+async function coSessionCounts(builderId, { otherId = null } = {}, deps = {}) {
+  const activePool = deps.pool || pool;
+  const { rows } = await activePool.query(
+    `SELECT other.builder_id AS other_id, count(*)::int AS n
+       FROM session_logs mine
+       JOIN tasks t_mine  ON t_mine.id = mine.task_id AND t_mine.goal_id IS NOT NULL
+       JOIN tasks t_other ON t_other.goal_id = t_mine.goal_id
+       JOIN session_logs other ON other.task_id = t_other.id AND other.builder_id <> $1
+      WHERE mine.builder_id = $1
+        AND ($3::bigint IS NULL OR other.builder_id = $3)
+        AND mine.started_at > now() - ($2 || ' days')::interval
+        AND tstzrange(mine.started_at,  mine.ended_at)
+         && tstzrange(other.started_at, other.ended_at)
+      GROUP BY other.builder_id`,
+    [builderId, String(WINDOW_DAYS), otherId]
+  );
+  return toCountMap(rows);
+}
+
+// shipped_together_goal — DISTINCT goals into which both have shipped at least one
+// task. Timing is deliberately ignored: this is the durable record that you both
+// built the same thing, even months apart.
+async function shippedTogetherCounts(builderId, { otherId = null } = {}, deps = {}) {
+  const activePool = deps.pool || pool;
+  const { rows } = await activePool.query(
+    `SELECT t_other.shipped_by AS other_id, count(DISTINCT t_mine.goal_id)::int AS n
+       FROM tasks t_mine
+       JOIN tasks t_other ON t_other.goal_id = t_mine.goal_id
+      WHERE t_mine.shipped_by = $1
+        AND t_mine.goal_id IS NOT NULL
+        AND t_mine.shipped_at > now() - ($2 || ' days')::interval
+        AND t_other.shipped_by IS NOT NULL
+        AND t_other.shipped_by <> $1
+        AND ($3::bigint IS NULL OR t_other.shipped_by = $3)
+      GROUP BY t_other.shipped_by`,
+    [builderId, String(WINDOW_DAYS), otherId]
+  );
+  return toCountMap(rows);
+}
+
+function toCountMap(rows) {
+  const m = new Map();
+  for (const r of rows) {
+    if (r.other_id == null) continue;
+    m.set(String(r.other_id), Number(r.n) || 0);
+  }
+  return m;
+}
+
+// ---------------------------------------------------------------------------
+// Consent — ONE gate, fail-closed
+// ---------------------------------------------------------------------------
+//
+// Every graph read passes through here, so C05 has a single structural place to
+// make consent the read path rather than a filter bolted on at each call site.
+//
+// `hiddenIdsFor` is injected: the platform-identity hub owns the hide flag
+// (ADR 0171 D2/D4) and lifecycle must not reach across a module boundary to read
+// it (ADR 0083). The route resolves the port and passes a reader in; where no hub
+// is enabled there is no hub-level hide flag to honour, and NOTHING is suppressed
+// by this mechanism — which is correct, not a hole: on such an instance nobody has
+// been offered the switch. What is NOT tolerated is an ERROR being read as
+// "nobody is hidden", so a throwing reader empties the graph.
+async function applyConsent(entries, hiddenIdsFor) {
+  if (typeof hiddenIdsFor !== 'function') return entries;
+  let hidden;
+  try {
+    hidden = await hiddenIdsFor(entries.map((e) => e.builder_id));
+  } catch (_) {
+    // FAIL CLOSED. An unreadable consent state is not permission.
+    return [];
+  }
+  if (!hidden) return [];                       // ditto: null is not "nobody"
+  const set = hidden instanceof Set ? hidden : new Set((hidden || []).map(String));
+  return entries.filter((e) => !set.has(String(e.builder_id)));
+}
+
+// ---------------------------------------------------------------------------
+// The graph
+// ---------------------------------------------------------------------------
+
+// Everyone this builder has any measurable closeness to, scored and explained,
+// strongest first. `hiddenIdsFor` is the consent gate above.
+// `otherId` narrows every signal query to one pair at the DATABASE, so the pair
+// read does not fetch a hundred rows to keep one. It is threaded through rather
+// than filtered afterwards — see the note above the signal reads.
+async function closenessFor(builderId, { limit = MAX_ROWS, hiddenIdsFor, otherId = null } = {}, deps = {}) {
+  const activePool = deps.pool || pool;
+  const [coClaim, coSession, shipped] = await Promise.all([
+    coClaimCounts(builderId, { otherId }, { pool: activePool }),
+    coSessionCounts(builderId, { otherId }, { pool: activePool }),
+    shippedTogetherCounts(builderId, { otherId }, { pool: activePool }),
+  ]);
+
+  const ids = new Set([...coClaim.keys(), ...coSession.keys(), ...shipped.keys()]);
+  let entries = [...ids].map((otherId) => {
+    const counts = {
+      co_claim: coClaim.get(otherId) || 0,
+      co_build_session: coSession.get(otherId) || 0,
+      shipped_together_goal: shipped.get(otherId) || 0,
+    };
+    const scored = scoreCloseness(counts);
+    return {
+      builder_id: otherId,
+      score: scored.score,
+      // The explanation travels WITH the score, on every surface, rather than
+      // behind a second call a caller may not make. That is the decision.
+      why: { breakdown: scored.breakdown, excluded: scored.excluded, in_words: explainInWords(scored) },
+    };
+  }).filter((e) => e.score > 0);
+
+  entries = await applyConsent(entries, hiddenIdsFor);
+  entries.sort((a, b) => b.score - a.score || String(a.builder_id).localeCompare(String(b.builder_id)));
+  entries = entries.slice(0, capRows(limit));
+
+  return hydrate(entries, activePool);
+}
+
+// One pair, with the same breakdown the graph carries. Separate from closenessFor
+// so "why am I close to THEM" is answerable directly, without paging a graph.
+async function closenessBetween(builderId, otherId, { hiddenIdsFor } = {}, deps = {}) {
+  const activePool = deps.pool || pool;
+  if (String(builderId) === String(otherId)) return null;
+  // NARROWED AT THE DATABASE, not filtered in memory. This used to call the graph
+  // read and then find() the one row it wanted, which ran three self-joins and a
+  // hydrate over up to a hundred builders to answer a question about one — on
+  // what is likely a per-profile-view route. Passing otherId pushes the narrowing
+  // into the same queries, so there is still exactly one definition of each
+  // signal and the pair read costs a pair.
+  const graph = await closenessFor(builderId, { limit: 1, hiddenIdsFor, otherId }, { pool: activePool });
+  const found = graph.find((e) => String(e.builder_id) === String(otherId));
+  if (found) return found;
+
+  // Not in the graph. That is either "no measurable closeness" or "consent says
+  // no", and this deliberately does not distinguish them: a caller able to tell
+  // the two apart could detect that a specific builder has hidden themselves,
+  // which is the thing the hide flag exists to prevent.
+  return null;
+}
+
+// Attach the names a surface needs. Done once, after scoring and consent, so a
+// suppressed builder's identity is never read at all.
+async function hydrate(entries, activePool) {
+  if (!entries.length) return [];
+  const { rows } = await activePool.query(
+    `SELECT id, github_login, display_name, avatar_url
+       FROM builders WHERE id = ANY($1::bigint[])`,
+    [entries.map((e) => e.builder_id)]
+  );
+  const byId = new Map(rows.map((r) => [String(r.id), r]));
+  return entries.map((e) => {
+    const b = byId.get(String(e.builder_id)) || {};
+    return {
+      ...e,
+      github_login: b.github_login || null,
+      display_name: b.display_name || null,
+      avatar_url: b.avatar_url || null,
+    };
+  });
+}
+
+module.exports = {
+  WINDOW_DAYS, MAX_ROWS, capRows,
+  weightsModel, availableSignals, unavailableSignals,
+  scoreCloseness, explainInWords,
+  coClaimCounts, coSessionCounts, shippedTogetherCounts,
+  applyConsent, closenessFor, closenessBetween,
+};

package/modules/lifecycle/lifecycle.js

@@ -19,6 +19,7 @@
 const db = require('./db');
 const classifier = require('./task-classifier');
 const helpRequests = require('./help-requests');
+const taskRecommendations = require('./task-recommendations');
 
 module.exports = {
   // --- retired doorway leaks (ADR 0093 §3) ---------------------------------
@@ -39,6 +40,10 @@ module.exports = {
   // task 1003171 (C01): the count of open help requests addressed to a builder,
   // so the kernel's /me can put it in the needs ctx WITHOUT importing this module.
   openHelpRequestsFor: (...a) => helpRequests.countOpenForBuilder(...a),
+  // task 1003173 (C03): the count of open task recommendations waiting on a
+  // builder, exposed the same way and for the same reason — a recommendation
+  // nobody surfaces is merely stored.
+  openTaskRecommendationsFor: (...a) => taskRecommendations.countOpenForRecipient(...a),
   getTask: (...a) => db.getTask(...a),
   listVersions: (...a) => db.listVersions(...a),
   versionProgress: (...a) => db.versionProgress(...a),

package/modules/lifecycle/migrations/lifecycle_005_task_recommendations.sql

@@ -0,0 +1,90 @@
+-- lifecycle_005_task_recommendations.sql — "you should look at this": recommending
+-- a task to someone, which is NOT handing it to them (task 1003173 / C03,
+-- goal 1000075; criterion collab-pass-a-task, ADR 0187 §3).
+--
+-- THE DECISION THIS TABLE ENCODES. Passing a task RECOMMENDS it; it never
+-- transfers the claim. The recipient still claims it themselves, so claim/release
+-- stays the single path to holding a task and nobody acquires work without opting
+-- in. There is deliberately NO transfer column, NO 'accepted' status that grants
+-- anything, and no seam for a future transfer: the decision was recommend-only,
+-- and an unused seam is a cost that later reads as an intention.
+--
+-- WHY THE REASON IS NOT NULLABLE. The criterion's own argument is that a
+-- recommendation which leaves no trace is indistinguishable from a task quietly
+-- changing hands. A reason the sender must write is what makes the ledger a
+-- record of a judgement rather than a nudge — so it is NOT NULL with a non-blank
+-- CHECK, the same shape lifecycle_help_requests gives what_is_stuck.
+--
+-- DECLINING COSTS NOTHING, and that is why 'declined' is just a status here and
+-- nothing else in the schema references it. There is no counter, no cooldown, no
+-- penalty column on either party, and no karma or credit link — a table that
+-- recorded a decline anywhere but here would be the penalty the criterion forbids.
+--
+-- MODULE-OWNED and `lifecycle_`-prefixed, so fitness check 11 permits it: a NEW
+-- table the lifecycle module owns outright, unlike `tasks`/`builders` which are
+-- core tables it only references (ADR 0083 §Decision #5). Mirrors
+-- lifecycle_004_help_requests, its sibling under this goal.
+
+CREATE TABLE IF NOT EXISTS lifecycle_task_recommendations (
+  id                bigserial PRIMARY KEY,
+
+  task_id           bigint NOT NULL REFERENCES tasks(id),
+  recommended_by    bigint NOT NULL REFERENCES builders(id),
+  recommended_to    bigint NOT NULL REFERENCES builders(id),
+
+  -- Required, per the criterion. See the header: this column IS the trace.
+  reason            text NOT NULL,
+
+  -- 'open'      — sent, not yet acted on
+  -- 'declined'  — the recipient said no. Terminal, and carries no consequence.
+  -- 'withdrawn' — the sender took it back. Also terminal.
+  --
+  -- There is NO 'accepted'. Accepting a recommendation is CLAIMING THE TASK, which
+  -- is the claims table's job and the recipient's own action; a status here saying
+  -- "accepted" would be a second, weaker record of holding work and would make this
+  -- table look like the place claims come from. Whether the recipient went on to
+  -- claim it is answered by joining tasks/claims, not by a column here.
+  status            text NOT NULL DEFAULT 'open',
+
+  created_at        timestamptz NOT NULL DEFAULT now(),
+  updated_at        timestamptz NOT NULL DEFAULT now(),
+
+  CONSTRAINT lifecycle_task_recommendations_reason_chk
+    CHECK (length(btrim(reason)) > 0),
+
+  CONSTRAINT lifecycle_task_recommendations_status_chk
+    CHECK (status IN ('open', 'declined', 'withdrawn')),
+
+  -- Recommending a task to yourself is not a recommendation.
+  CONSTRAINT lifecycle_task_recommendations_not_self_chk
+    CHECK (recommended_by <> recommended_to)
+);
+
+-- One OPEN recommendation of a given task to a given person. A second send is the
+-- same judgement repeated, and two identical open rows would make the recipient's
+-- list lie about how many distinct things are waiting on them. Partial, so the
+-- same task CAN be recommended again after a decline or a withdrawal — the
+-- decision was that declining costs nothing, and a permanent unique key would
+-- quietly make a decline final.
+CREATE UNIQUE INDEX IF NOT EXISTS lifecycle_task_recommendations_open_uniq
+  ON lifecycle_task_recommendations (task_id, recommended_to) WHERE status = 'open';
+
+-- The recipient's read: "what has been recommended to me". Partial — a settled
+-- recommendation is history and never needs routing again (the 004 pattern).
+CREATE INDEX IF NOT EXISTS lifecycle_task_recommendations_open_to_idx
+  ON lifecycle_task_recommendations (recommended_to) WHERE status = 'open';
+
+-- The sender's read, and the audit read the criterion asks for: the recommendation
+-- and its author are readable AFTERWARDS, so this one is not filtered by status.
+CREATE INDEX IF NOT EXISTS lifecycle_task_recommendations_by_idx
+  ON lifecycle_task_recommendations (recommended_by, created_at DESC);
+
+-- "Who recommended this task, and why" — the per-task history.
+CREATE INDEX IF NOT EXISTS lifecycle_task_recommendations_task_idx
+  ON lifecycle_task_recommendations (task_id, created_at DESC);
+
+COMMENT ON TABLE lifecycle_task_recommendations IS
+  'A recommendation that someone look at a task (task 1003173). It NEVER transfers a claim: there is no accepted status and no transfer column, because claiming remains the recipient''s own action.';
+
+INSERT INTO schema_migrations (version) VALUES ('lifecycle_005_task_recommendations')
+ON CONFLICT (version) DO NOTHING;

package/modules/lifecycle/module.json

@@ -19,6 +19,8 @@
       "analytics",
       "lifecycle",
       "help-requests",
+      "recommendations",
+      "closeness",
       "visuals"
     ],
     "pollers": [