@bongos/core 1.23.22 → 1.24.2

package/modules/lifecycle/db-claims.js

@@ -15,6 +15,8 @@ const { pool, withTx } = api;
 const log = api.logger('lifecycle');
 const seams = api;
 const { touchesOverlap } = api.pathMatch;
+const { notPageMarkerSql } = require('./page-tweak-artist.js');
+const { heldPagesForTouches } = require('./page-notice.js');
 // CLAIM_ANY / CLAIM_NEWCOMER name the two atoms in the refusal message. The
 // decision itself moved to db-rank-authz.claimGate (task 1003196), so this file
 // no longer calls claimEligibilityAllows / rankAllowsTask / xenosClaimAllowed
@@ -27,6 +29,9 @@ const { goalMembershipFailures } = require('./claim-feed.js');
 // called from all three claim surfaces below, so a flagged task can't be
 // claimed via the batch path as a bypass of the single-claim gate.
 const { relevanceFrictionFailures } = require('./db-relevance-flags.js');
+// task 1004950 / ADR 0395: a task that needs server access refuses a claimer
+// without the grant — the third extracted gate in the same shape.
+const { taskNeedsFailures } = require('./task-needs-gate.js');
 const { unsatisfiedDeps } = require('./db-deps-criteria.js');
 // depRefusalRow: the ONE shape a DEPS_NOT_SHIPPED refusal carries. All three
 // claim paths below use it — hand-building the object here is what made task
@@ -251,6 +256,13 @@ async function claimTask({ taskId, builderId, worktreeName, headSha, creatorSess
     const relevanceRefusals = await relevanceFrictionFailures({ client, tasks: [task] });
     if (relevanceRefusals.length > 0) throw relevanceRefusals[0].refusal;
 
+    // task 1004950 / ADR 0395: a task that needs the live server refuses a
+    // claimer without the server grant. Same extracted check on all three
+    // surfaces (task-needs-gate.js). `owner` never refuses here — the feed is
+    // where owner work narrows to the owner.
+    const needsRefusals = await taskNeedsFailures({ client, tasks: [task], builderId });
+    if (needsRefusals.length > 0) throw needsRefusals[0].refusal;
+
     // The claim gate (ADR 0015, generalized in task 1516 / ADR 0086 §5): a task
     // can't be claimed while any dependency is un-done — its OWN edges plus those
     // inherited from its goal/criteria, where "done" = task shipped | criterion
@@ -300,7 +312,7 @@ async function claimTask({ taskId, builderId, worktreeName, headSha, creatorSess
     const { rows: activeClaimRows } = await client.query(
       `SELECT c.id, t.id AS task_id, t.title, t.touches, t.module_key FROM claims c
          JOIN tasks t ON t.id = c.task_id
-        WHERE c.released_at IS NULL AND t.id <> $1`,
+        WHERE c.released_at IS NULL AND t.id <> $1 AND ${notPageMarkerSql('c', 't')}`,
       [taskId]
     );
     // BV1.R53 (task 1422): module-disjointness is a HARD gate (not advisory) when
@@ -460,7 +472,10 @@ async function claimTask({ taskId, builderId, worktreeName, headSha, creatorSess
         console.log('[gds] graduation broadcast post-claim failed:', e && e.message);
       }
     }
-    return { ...insertClaim.rows[0], just_unlocked: justUnlocked, overlap_warning: overlapWarning, sibling_overlap_warning: siblingWarning };
+    // task 1004948: a gentle heads-up, never a refusal, when this task's files belong
+    // to a page an artist is updating. Read after the commit; a failed read is "none".
+    const pageNotice = await heldPagesForTouches(task.touches, client, { exceptTaskId: taskId });
+    return { ...insertClaim.rows[0], just_unlocked: justUnlocked, overlap_warning: overlapWarning, sibling_overlap_warning: siblingWarning, page_notice: pageNotice };
   } catch (err) {
     await client.query('ROLLBACK').catch(() => {});
     if (err && err.code === '23505') {
@@ -658,6 +673,12 @@ async function claimTasksBatch({ taskIds, builderId, worktreePrefix, creatorSess
       failures.push({ task_id: f.task_id, reason: code, ...rest });
     }
 
+    // task 1004950: the SAME extracted server-access gate as claimTask.
+    for (const f of await taskNeedsFailures({ client, tasks: taskRows, builderId })) {
+      const { code, ...rest } = f.refusal;
+      failures.push({ task_id: f.task_id, reason: code, ...rest });
+    }
+
     // Per-task dependency check (ADR 0015, generalized task 1516). An EXTERNAL dep
     // (not in this batch) must already be done; a batch-internal dep isn't done yet
     // at claim time but doesn't block — the batch is worked serially. "Internal"
@@ -724,7 +745,8 @@ async function claimTasksBatch({ taskIds, builderId, worktreePrefix, creatorSess
          FROM claims c
          JOIN tasks t ON t.id = c.task_id
         WHERE c.released_at IS NULL
-          AND t.id <> ALL($1::bigint[])`,
+          AND t.id <> ALL($1::bigint[])
+          AND ${notPageMarkerSql('c', 't')}`,
       [uniqIds]
     );
     for (const t of taskRows) {
@@ -966,7 +988,7 @@ async function validateClaimBatch({ taskIds, builderId }) {
   const { rows: activeClaims } = await pool.query(
     `SELECT c.id AS claim_id, t.title, t.touches, t.module_key
        FROM claims c JOIN tasks t ON t.id = c.task_id
-      WHERE c.released_at IS NULL AND t.id <> ALL($1::bigint[])`,
+      WHERE c.released_at IS NULL AND t.id <> ALL($1::bigint[]) AND ${notPageMarkerSql('c', 't')}`,
     [uniqIds]
   );
 
@@ -1014,6 +1036,12 @@ async function validateClaimBatch({ taskIds, builderId }) {
     push(f.task_id, { reason: code, ...rest });
   }
 
+  // task 1004950: server-access, kept in sync with claimTask + claimTasksBatch.
+  for (const f of await taskNeedsFailures({ client: pool, tasks: taskRows, builderId })) {
+    const { code, ...rest } = f.refusal;
+    push(f.task_id, { reason: code, ...rest });
+  }
+
   // Dependencies — external to the batch only (a batch-internal dep is fine;
   // the batch is worked serially, same rule as claimTasksBatch).
   const batchIdSet = new Set(uniqIds);

package/modules/lifecycle/db-goals.js

@@ -487,14 +487,19 @@ async function reorderGoals({ versionId, orderedIds }, deps = {}) {
 // FOR UPDATE on its transaction client, and this UPDATE on a pool connection
 // blocks on that lock — while the transaction is awaiting this UPDATE before it
 // can COMMIT and release it. Neither side can move.
-async function setGoalStatus({ goalId, status }, deps = {}) {
+//
+// `fromStatus` (task 1001693) makes the move conditional: the row flips only if it
+// still reads that status, and null comes back otherwise. The achieve path uses it
+// so exactly one caller wins a goal's flip to `achieved`, and only the winner books
+// the goal-achievement karma.
+async function setGoalStatus({ goalId, status, fromStatus = null }, deps = {}) {
   const activePool = executorFor(deps, pool);
   const { rows } = await activePool.query(
     `UPDATE goals
         SET status = $2, updated_at = now()
-      WHERE id = $1
+      WHERE id = $1 AND ($3::text IS NULL OR status = $3::text)
       RETURNING ${GOAL_COLS}`,
-    [goalId, status]
+    [goalId, status, fromStatus]
   );
   // A goal leaving `open` takes no new members, so its pending asks are dead.
   if (rows[0] && status !== 'open') await cancelPendingMembershipRequests(activePool, goalId);
@@ -547,7 +552,16 @@ async function achieveGoalIfComplete({ goalId }, deps = {}) {
   // This never blocks a SHIP; it declines only the goal's flip to achieved, and
   // the goal simply stays open until its last task lands or is abandoned.
   if (unfinishedTasks > 0) return { achieved: false, goal, unfinishedTasks };
-  const updated = await setGoalStatus({ goalId, status: 'achieved' }, deps);
+  // Conditional on still reading `open` (task 1001693): two overrides closing a
+  // goal's last criteria at once both reach here, and only one may flip it and
+  // book its karma. The loser reports the goal as achieved, which it now is, and
+  // leaves the reward and the version close to the winner.
+  const updated = await setGoalStatus({ goalId, status: 'achieved', fromStatus: 'open' }, deps);
+  if (!updated) return { achieved: true, goal: await getGoal(goalId, { ...deps, forUpdate: false }), versionsClosed: [] };
+  const exec = executorFor(deps, pool);
+  // The same reward the ship-time flip books, through the same helper, so a failed
+  // booking is logged the same way on both doors.
+  await doneWhen.rewardAchievedGoals(exec, [updated]);
 
   // BV1.R16 (task 1003603, ADR 0263 §§3–4): the SECOND achievement writer. A goal
   // reaching `achieved` may have been the version's last non-maintenance goal, and
@@ -559,7 +573,6 @@ async function achieveGoalIfComplete({ goalId }, deps = {}) {
   //
   // Runs on the caller's exec so it sees the flip above, which in the ship path is
   // still uncommitted. Never throws: autoCloseVersionsForGoals catches per version.
-  const exec = executorFor(deps, pool);
   const versionsClosed = await autoCloseVersionsForGoals(exec, [updated]);
   return { achieved: true, goal: updated, versionsClosed };
 }

package/modules/lifecycle/db-tasks.js

@@ -22,6 +22,8 @@ const { isReservedCriterionSlug } = require('./criterion-ref.js');
 const { resolveWriteDiscipline, WRITABLE_DISCIPLINES } = require('./task-classifier.js');
 const { gateOnSpecTask } = require('./goal-spec-task.js');
 const { ensureArtistReviewGoal } = require('./artist-review-goal.js');
+const { notPageMarkerSql } = require('./page-tweak-artist.js');
+const { needsFilterWhere, capabilityFeedWhere } = require('./task-needs-gate.js');
 
 // -------------------------------------------------------------------------
 // Tasks
@@ -147,6 +149,7 @@ async function createTask({
   // (requiresRank stays null for the goal vector → derived purely from touches +
   // sensitivity), so goal_id never influences the requires_rank clamp.
   goalId = null,
+  needs = [], // task 1004950 / ADR 0395 — ⊆ ['owner','server']; routes normalize, the CHECK backstops
   // task 1003278: WHO created it — the builder id from the authenticated request.
   // Nullable, appended at the end (the goals bind-order convention): a system
   // path with no builder in the request (a seed, a migration backfill) passes
@@ -267,13 +270,13 @@ async function createTask({
                         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, created_by, promoted_at)
+                        security_sensitive, requires_rank, module_key, goal_id, created_by, promoted_at, needs)
      VALUES ($1, $2, $3, $4, $5,
              $6, $7, $8, $9,
              $10, $11, $12, $13, $14,
              $15, $16, $17, $18, $19,
              $20, $21, $22, $23, $24,
-             CASE WHEN $4 IN ('ready','active') THEN now() ELSE NULL END)
+             CASE WHEN $4 IN ('ready','active') THEN now() ELSE NULL END, $25)
      RETURNING *`,
     [
       versionId,
@@ -300,6 +303,7 @@ async function createTask({
       moduleKey ?? null,
       goalIdEffective ?? null,
       createdBy ?? null,
+      Array.isArray(needs) ? needs : [],
     ]
   );
   // task 1677 / ADR 0096: audit each creation-time auto-assignment so the trail is
@@ -357,7 +361,7 @@ async function findTaskBySourceRef({ source, sourceRef } = {}, deps = {}) {
 
 const TASK_SETTER_COLUMNS = new Set([
   'kind', 'discipline', 'newcomer_friendly', 'security_sensitive', 'parallel_safe', 'automation_tag',
-  'needs_migration', 'module_key', 'description', 'title', 'priority', 'value_summary',
+  'needs_migration', 'module_key', 'description', 'title', 'priority', 'value_summary', 'needs',
 ]);
 
 async function updateTaskColumn(id, column, value) {
@@ -647,6 +651,7 @@ async function updateTaskParallelSafe(id, parallelSafe) { return updateTaskColum
 // 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); }
+async function updateTaskNeeds(id, needs) { return updateTaskColumn(id, 'needs', needs); }
 
 // task 1002648: correct the create-time migration heuristic's verdict — a false
 // flag makes claiming reserve a migration number that goes unused (task 1002614
@@ -777,7 +782,7 @@ async function getTask(id) {
 }
 
 
-async function listTasks({ versionId, status, kind, discipline, goalId, createdBy, staleDays, limit, offset } = {}) {
+async function listTasks({ versionId, status, kind, discipline, goalId, createdBy, staleDays, limit, offset, needs } = {}) {
   const params = [];
   const where = [];
   if (versionId) {
@@ -800,6 +805,7 @@ async function listTasks({ versionId, status, kind, discipline, goalId, createdB
     params.push(goalId);
     where.push(`goal_id = $${params.length}`);
   }
+  const needsWhere = needsFilterWhere(needs, '', params); if (needsWhere) where.push(needsWhere); // task 1004950
   // task 1003278 — the creator + staleness axes, server-side. They exist HERE and
   // not only in the browser because the board was reducing the whole table to
   // answer them: GET /tasks?status=backlog measured 690,625 bytes on 2026-08-25,
@@ -1015,6 +1021,7 @@ const CLAIMABLE_SQL = `
        SELECT 1 FROM claims c
          JOIN tasks t2 ON t2.id = c.task_id
         WHERE c.released_at IS NULL
+          AND ${notPageMarkerSql('c', 't2')}
           AND t2.touches && t.touches
      )`;
 const SESSION_FIT_SQL = `
@@ -1028,7 +1035,7 @@ const SESSION_FIT_SQL = `
     END AS fits_session_modes
     FROM tasks t`;
 
-async function listClaimableTasks({ versionId = null, builderId = null, discipline = null, fit = null, createdBy = null, staleDays = null } = {}) {
+async function listClaimableTasks({ versionId = null, builderId = null, discipline = null, fit = null, createdBy = null, staleDays = null, needs = null } = {}) {
   const params = [];
   const where = [];
   let goalJoin = '';
@@ -1037,6 +1044,7 @@ async function listClaimableTasks({ versionId = null, builderId = null, discipli
     params.push(versionId);
     where.push(`v.version_id = $${params.length}`);
   }
+  const needsWhere = needsFilterWhere(needs, 'v', params); if (needsWhere) where.push(needsWhere); // task 1004950: the 'waiting on you' queue
   if (discipline) {
     params.push(discipline);
     where.push(`v.discipline = $${params.length}`);
@@ -1110,6 +1118,7 @@ async function listClaimableTasks({ versionId = null, builderId = null, discipli
     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`;
+    where.push(await capabilityFeedWhere(builderId, fit, 'v', params)); // task 1004950 / ADR 0395: only what the viewer can do
   }
   // Autonomy / parallel-eligibility filter. Joining the session-fit relation
   // (also a SELECT t.* shape) makes bare column names like priority/created_at
@@ -1470,7 +1479,7 @@ module.exports = {
   suggestCreditsReward,
   taskTouchesProtectedPath,
   updateCriterionGoal,
-  updateTaskAutomationTag,
+  updateTaskAutomationTag, updateTaskNeeds,
   updateTaskDescription,
   updateTaskTitle,
   updateTaskDiscipline,

package/modules/lifecycle/done-when.js

@@ -23,7 +23,7 @@
 //   POST /api/bongos/done-when/:criterionId/satisfy        — auth
 //   POST /api/bongos/done-when/:criterionId/unsatisfy      — auth
 
-const { pool } = require('../../src/module-api');
+const { pool, resolveOptional } = require('../../src/module-api');
 const { nonTerminalSql } = require('./task-status');
 const { SMOKE_NOT_LIKE } = require('./db-shared.js');
 const { executorFor } = require('./db-executor.js');
@@ -618,9 +618,30 @@ async function achieveCompletedGoals(exec, goalIds) {
   // Task 1003660: an achieved goal takes no new members — close its pending asks
   // on the same executor, so the cancel rides the ship transaction.
   await cancelPendingMembershipRequests(exec, rows.map((g) => g.id));
+  await rewardAchievedGoals(exec, rows);
   return rows;
 }
 
+// rewardAchievedGoals — the goal-achievement karma (task 1001693 / BV1.P5.3, ADR
+// 0101 Part 3), booked through the economy's `reward` port for each goal THIS
+// statement flipped. Only the caller whose UPDATE ... WHERE status = 'open'
+// returned the row gets here, so a concurrent ship or sweep cannot award twice.
+// Optional and best-effort: no economy module means no karma, and the award runs
+// under its own SAVEPOINT (goal-reward.js) so a failed karma write cannot abort
+// the ship that achieved the goal. The catch here is for a provider that throws.
+async function rewardAchievedGoals(exec, goals) {
+  const reward = resolveOptional('reward');
+  if (!reward || typeof reward.awardGoalAchievementKarma !== 'function') return;
+  for (const g of goals) {
+    try {
+      const r = await reward.awardGoalAchievementKarma(exec, { goalId: g.id });
+      if (r && r.reason === 'failed') console.warn(`[lifecycle] goal ${g.id} achieved; its karma was not booked: ${r.error}`);
+    } catch (e) {
+      console.warn(`[lifecycle] goal ${g.id} achieved; its karma was not booked: ${e && e.message}`);
+    }
+  }
+}
+
 // describeAutoClose — the one-line summary of what a close actually closed, or
 // null on a no-op. Pure + here rather than in db.js because db.js is over the
 // fitness oversize threshold: growth there has to be paid for, and formatting is
@@ -674,6 +695,7 @@ module.exports = {
   autoSatisfyShippedCriteria,
   describeAutoClose,
   closeCompletedWorkForShip,
+  rewardAchievedGoals,
   markCriterion,
   unmarkCriterion,
 };

package/modules/lifecycle/lifecycle.js

@@ -26,6 +26,7 @@ const activity = require('./activity');
 const mingle = require('./mingle');
 const pageTweakReads = require('./page-tweak-reads');
 const pageTweakClaim = require('./page-tweak-claim');
+const pageNotice = require('./page-notice');
 const pageTweakWrite = require('./page-tweak-write');
 const pageTweakApprove = require('./page-tweak-approve');
 
@@ -165,6 +166,10 @@ module.exports = {
   // read the part-3 claim gate uses, surfaced to me.js so the CLI + hall can
   // show the owed-rebase warning that gates new claims (reward lands on ship).
   needsRebaseTasksForBuilder: (...a) => db.needsRebaseTasksForBuilder(...a),
+  // task 1004948: the page-update heads-up lines for a claim's files, for GET /me.
+  noticesForClaims: (...a) => pageNotice.noticesForClaims(...a),
+  // task 1004948: engineering claims open on a page's files, for the artist's editor read.
+  engineeringActiveOnPage: (...a) => pageNotice.engineeringActiveOnPage(...a),
   // builders.js (the Archon roster): the roster + stale-claim + per-builder grade.
   getBuildersRoster: (...a) => db.getBuildersRoster(...a),
   getActiveClaimsForBuilderWithStale: (...a) => db.getActiveClaimsForBuilderWithStale(...a),

package/modules/lifecycle/migrations/lifecycle_017_notes.sql

@@ -0,0 +1,46 @@
+-- lifecycle_017_notes.sql — notes on a task or a goal (task 1004745, goal 1000095).
+--
+-- WHAT IT IS. A place to put information that helps scope a task or goal, or helps
+-- finish it: a decision, an open question, a link, a risk, progress. Each note is
+-- short, dated and has an author.
+--
+-- WHY `kind` IS A COLUMN. Notes are shown GROUPED BY PURPOSE (scope, decision,
+-- question, reference, progress, risk, other) instead of as one growing list, so the
+-- purpose has to be stored, not re-guessed on every read. `kind_source` records
+-- whether the author chose it or the heuristic did, so a wrong guess can be told
+-- apart from a deliberate choice and a later smarter grouper knows which to revisit.
+--
+-- A note is about a task OR a goal, never both, and never neither.
+--
+-- MODULE-OWNED and `lifecycle_`-prefixed, so fitness check 11 permits it: a NEW
+-- table the lifecycle module owns outright (ADR 0083 §Decision #5).
+
+CREATE TABLE IF NOT EXISTS lifecycle_notes (
+  id           bigserial PRIMARY KEY,
+  task_id      bigint REFERENCES tasks(id),
+  goal_id      bigint REFERENCES goals(id),
+  author_id    bigint NOT NULL REFERENCES builders(id),
+  body         text NOT NULL,
+  kind         text NOT NULL DEFAULT 'other',
+  kind_source  text NOT NULL DEFAULT 'auto',
+  created_at   timestamptz NOT NULL DEFAULT now(),
+  updated_at   timestamptz NOT NULL DEFAULT now(),
+
+  CONSTRAINT lifecycle_notes_subject_chk
+    CHECK ((task_id IS NOT NULL) <> (goal_id IS NOT NULL)),
+  CONSTRAINT lifecycle_notes_body_chk
+    CHECK (length(btrim(body)) BETWEEN 1 AND 4000),
+  CONSTRAINT lifecycle_notes_kind_chk
+    CHECK (kind IN ('scope', 'decision', 'question', 'reference', 'progress', 'risk', 'other')),
+  CONSTRAINT lifecycle_notes_kind_source_chk
+    CHECK (kind_source IN ('author', 'auto'))
+);
+
+-- The two reads: everything on one task, everything on one goal, newest first.
+CREATE INDEX IF NOT EXISTS lifecycle_notes_task_idx
+  ON lifecycle_notes (task_id, created_at DESC) WHERE task_id IS NOT NULL;
+CREATE INDEX IF NOT EXISTS lifecycle_notes_goal_idx
+  ON lifecycle_notes (goal_id, created_at DESC) WHERE goal_id IS NOT NULL;
+
+INSERT INTO schema_migrations (version) VALUES ('lifecycle_017_notes')
+ON CONFLICT (version) DO NOTHING;

package/modules/lifecycle/module.json

@@ -34,7 +34,8 @@
       "sky",
       "goal-task-relevance",
       "moving",
-      "task-votes"
+      "task-votes",
+      "notes"
     ],
     "pollers": [
       "publish-reconciler"

package/modules/lifecycle/notes.js

@@ -0,0 +1,219 @@
+// modules/lifecycle/notes.js — notes on a task or goal, grouped by purpose
+// (task 1004745, goal 1000095).
+//
+// A note is a short piece of information that helps scope a task or goal or helps
+// finish it. A long thread of them reads badly, so they are shown GROUPED BY
+// PURPOSE — what is decided, what is still a question, what to read, what is
+// risky — with the newest few open in each group and the rest folded away.
+//
+// THE PURPOSE IS CHOSEN BY THE AUTHOR, AND GUESSED WHEN THEY DO NOT. Guessing by
+// text likeness would need a model call per note and could regroup a reader's page
+// under them; a stored purpose is stable, cheap and the author's own word. The
+// guess (`suggestKind`) is a few plain rules (a link, a question mark, "decided",
+// "risk") used only when no purpose was given, and is stored with
+// kind_source 'auto' so it can be told from a deliberate choice.
+//
+// Reaches core only through the doorway (ADR 0083).
+
+'use strict';
+
+const api = require('../../src/module-api');
+
+const { pool } = api;
+
+const MAX_BODY = 4000;
+
+// The most notes one task or goal carries, so no one can bury a page in them.
+const MAX_NOTES_PER_SUBJECT = 500;
+
+// Display order is the order a person scoping work wants to read: what the work is,
+// what was decided, what is still open, what is risky, how far along it is, what to
+// read, and everything else last.
+const KINDS = Object.freeze([
+  { key: 'scope', label: 'Scope', hint: 'What is in and out' },
+  { key: 'decision', label: 'Decisions', hint: 'What was settled, and why' },
+  { key: 'question', label: 'Open questions', hint: 'What still needs an answer' },
+  { key: 'risk', label: 'Risks', hint: 'What could go wrong' },
+  { key: 'progress', label: 'Progress', hint: 'How far along it is' },
+  { key: 'reference', label: 'Links & reading', hint: 'Where to look' },
+  { key: 'other', label: 'Other', hint: 'Anything else' },
+]);
+const KIND_KEYS = Object.freeze(KINDS.map((k) => k.key));
+
+// How many notes a group shows before folding the rest behind "show more".
+const OPEN_PER_GROUP = 3;
+
+// A purpose from the words, for a note written without one. Order matters: the
+// first rule that matches wins, and 'other' is the honest answer when none does.
+function suggestKind(body) {
+  const t = String(body == null ? '' : body).trim().toLowerCase();
+  if (!t) return 'other';
+  if (/\b(decided|decision|we will|we'll go with|going with|agreed|chose|chosen)\b/.test(t)) return 'decision';
+  if (/\b(risk|danger|could break|might break|breaks|careful|watch out|blocker|blocked)\b/.test(t)) return 'risk';
+  if (t.includes('?') || /^(how|what|why|should|can|could|does|do|is|are|who|when|where)\b/.test(t)) return 'question';
+  if (/\b(in scope|out of scope|scope|must|should include|needs to|acceptance|done when)\b/.test(t)) return 'scope';
+  if (/\b(done|finished|shipped|merged|started|working on|in progress|so far|next step)\b/.test(t)) return 'progress';
+  if (/https?:\/\/|\bsee (the )?(docs?|adr|spec|page|link)\b|\bdocs?\b|\badr\b|\bspec\b/.test(t)) return 'reference';
+  return 'other';
+}
+
+// Which of the two subjects a request names: { taskId } or { goalId }, else null.
+// Exactly one id must be present and a positive integer.
+function subjectOf(src) {
+  const num = (v) => (v == null || v === '' ? null : (Number.isInteger(Number(v)) && Number(v) > 0 ? Number(v) : NaN));
+  const taskId = num(src.task_id);
+  const goalId = num(src.goal_id);
+  if (Number.isNaN(taskId) || Number.isNaN(goalId)) return null;
+  if ((taskId == null) === (goalId == null)) return null;
+  return taskId != null ? { taskId } : { goalId };
+}
+
+// Validate an incoming note; `kind` may be absent (then guessed).
+function validateNote(input) {
+  const errors = [];
+  const body = input && typeof input.body === 'string' ? input.body.trim() : '';
+  if (!body) errors.push({ field: 'body', reason: 'required' });
+  else if (body.length > MAX_BODY) errors.push({ field: 'body', reason: `at most ${MAX_BODY} characters` });
+  const kind = input ? input.kind : undefined;
+  if (kind != null && !KIND_KEYS.includes(kind)) errors.push({ field: 'kind', reason: `pick a group: ${KINDS.map((k) => k.label).join(', ')}` });
+  if (!subjectOf(input || {})) errors.push({ field: 'subject', reason: 'say whether the note is on a task or on a goal, not both' });
+  if (errors.length) return { ok: false, errors };
+  return {
+    ok: true,
+    body,
+    kind: kind == null ? suggestKind(body) : kind,
+    kindSource: kind == null ? 'auto' : 'author',
+  };
+}
+
+// Rows (newest first, or any order) -> the grouped view the page renders. Empty
+// groups are left out; within a group newest comes first; `open` is what shows
+// at once and `folded` is what waits behind "show more".
+function groupNotes(rows, { openPerGroup = OPEN_PER_GROUP } = {}) {
+  const byKind = new Map(KIND_KEYS.map((k) => [k, []]));
+  for (const r of rows || []) {
+    const k = byKind.has(r.kind) ? r.kind : 'other';
+    byKind.get(k).push(r);
+  }
+  const groups = [];
+  for (const meta of KINDS) {
+    const list = byKind.get(meta.key).slice().sort((a, b) => new Date(b.created_at) - new Date(a.created_at));
+    if (!list.length) continue;
+    groups.push({
+      kind: meta.key,
+      label: meta.label,
+      hint: meta.hint,
+      count: list.length,
+      latest_at: list[0].created_at,
+      open: list.slice(0, openPerGroup),
+      folded: list.slice(openPerGroup),
+    });
+  }
+  return groups;
+}
+
+const COLS = 'n.id, n.task_id, n.goal_id, n.author_id, n.body, n.kind, n.kind_source, n.created_at, n.updated_at, '
+  + 'b.github_login AS author_login, b.display_name AS author_name, b.avatar_url AS author_avatar_url';
+
+// Every note on one task or goal, newest first. `subject` is { taskId } or { goalId }.
+async function listNotes(subject, deps = {}) {
+  const db = deps.pool || pool;
+  const col = subject.taskId != null ? 'n.task_id' : 'n.goal_id';
+  const id = subject.taskId != null ? subject.taskId : subject.goalId;
+  const { rows } = await db.query(
+    `SELECT ${COLS} FROM lifecycle_notes n JOIN builders b ON b.id = n.author_id
+      WHERE ${col} = $1 ORDER BY n.created_at DESC, n.id DESC LIMIT $2`,
+    [id, MAX_NOTES_PER_SUBJECT]
+  );
+  return rows;
+}
+
+// How many notes a task or goal already carries (for the per-subject cap).
+async function countNotes(subject, deps = {}) {
+  const db = deps.pool || pool;
+  const col = subject.taskId != null ? 'task_id' : 'goal_id';
+  const id = subject.taskId != null ? subject.taskId : subject.goalId;
+  const { rows } = await db.query(`SELECT count(*)::int AS n FROM lifecycle_notes WHERE ${col} = $1`, [id]);
+  return rows[0].n;
+}
+
+async function addNote({ taskId = null, goalId = null, authorId, body, kind, kindSource }, deps = {}) {
+  const db = deps.pool || pool;
+  const { rows } = await db.query(
+    `WITH ins AS (
+       INSERT INTO lifecycle_notes (task_id, goal_id, author_id, body, kind, kind_source)
+       VALUES ($1, $2, $3, $4, $5, $6) RETURNING *
+     )
+     SELECT ${COLS} FROM ins n JOIN builders b ON b.id = n.author_id`,
+    [taskId, goalId, authorId, body, kind, kindSource]
+  );
+  return rows[0];
+}
+
+// Re-file a note under another purpose. Only its author or a Metic+ may (the route
+// decides who; this just writes), and the choice is now the author's.
+async function setKind(id, kind, deps = {}) {
+  const db = deps.pool || pool;
+  const { rows } = await db.query(
+    `UPDATE lifecycle_notes SET kind = $2, kind_source = 'author', updated_at = now()
+      WHERE id = $1 RETURNING id, kind, kind_source, author_id`,
+    [id, kind]
+  );
+  return rows[0] || null;
+}
+
+async function getNote(id, deps = {}) {
+  const db = deps.pool || pool;
+  const { rows } = await db.query('SELECT id, author_id, kind, task_id, goal_id FROM lifecycle_notes WHERE id = $1', [id]);
+  return rows[0] || null;
+}
+
+async function deleteNote(id, deps = {}) {
+  const db = deps.pool || pool;
+  const { rowCount } = await db.query('DELETE FROM lifecycle_notes WHERE id = $1', [id]);
+  return rowCount > 0;
+}
+
+// May this builder see notes on this task or goal? A private goal's notes (and those of
+// its tasks) are for its members and an Archon only, the same wall the goal's own title
+// and prose sit behind (ADR 0112). Anything else is open to every signed-in builder.
+// A task or goal that does not exist answers false too, so the route gives the same
+// 404 for "missing" and "not yours to see" from ONE read.
+async function canSee(builder, subject, deps = {}) {
+  const db = deps.pool || pool;
+  const { rows } = subject.taskId != null
+    ? await db.query('SELECT g.id AS goal_id, g.visibility FROM tasks t LEFT JOIN goals g ON g.id = t.goal_id WHERE t.id = $1', [subject.taskId])
+    : await db.query('SELECT g.id AS goal_id, g.visibility FROM goals g WHERE g.id = $1', [subject.goalId]);
+  const g = rows[0];
+  if (!g) return false;
+  if (g.visibility !== 'private' || api.rankMeetsThreshold(builder.rank, ['archon'])) return true;
+  const m = await db.query('SELECT 1 FROM goal_members WHERE goal_id = $1 AND builder_id = $2', [g.goal_id, builder.id]);
+  return m.rows.length > 0;
+}
+
+// Who may re-file or delete a note: its author, or a Metic or above. The rank is the live
+// one on the authenticated request (ADR 0016), compared through the kernel's own ladder.
+function canChange(builder, note) {
+  if (String(builder.id) === String(note.author_id)) return true;
+  return api.rankMeetsThreshold(builder.rank, ['metic', 'archon']);
+}
+
+module.exports = {
+  KINDS,
+  MAX_NOTES_PER_SUBJECT,
+  subjectOf,
+  canSee,
+  canChange,
+  countNotes,
+  KIND_KEYS,
+  MAX_BODY,
+  suggestKind,
+  validateNote,
+  groupNotes,
+  listNotes,
+
+  addNote,
+  setKind,
+  getNote,
+  deleteNote,
+};