@bongos/core 1.23.22 → 1.24.1

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,
+};

package/modules/lifecycle/page-notice.js

@@ -0,0 +1,124 @@
+// modules/lifecycle/page-notice.js — WHO IS UPDATING A PAGE, in one read (task 1004948).
+//
+// An artist's page claim is a marker (task 1004947), so nothing blocks anyone;
+// this is the other half: telling people. `heldPagesForTouches` answers, for the
+// files a task touches, which pages an artist is updating right now, who, and
+// since when. `engineeringActiveOnPage` answers the reverse for an artist: whose
+// engineering claims are open on files that page is made of. Information only:
+// nothing here refuses, gates or writes, and a failed read answers "no notice"
+// rather than throwing, because a heads-up must never break a claim.
+//
+// Every notice is `{ page_id, holder, since, task_id, line }`, the same shape on
+// every surface (claim output, GET /me, the Conductor). Names and ids that reach a
+// session as text are cleaned first: a display name is somebody else's words.
+// Engineering work is reported by holder only, never by title: a task's title can
+// belong to a goal the asking artist may not read (ADR 0112).
+//
+// Reads through the caller's executor (a pool or a transaction client) and the
+// doorway's path matcher, like the rest of the claim ladder.
+
+'use strict';
+
+const api = require('../../src/module-api');
+const { touchesOverlap } = api.pathMatch;
+const { PAGE_TWEAK_SOURCE, webClaimPredicate } = require('./page-tweak-artist.js');
+
+// Open page markers / claims are bounded by concurrent people; the cap is a backstop.
+const ROW_CAP = 500;
+
+// 'page-tweak/builders:studio/r2' -> 'builders:studio' ('' when malformed).
+function pageIdOf(sourceRef) {
+  const m = /^page-tweak\/([a-z0-9:-]{1,80})\/r[1-9][0-9]*$/.exec(String(sourceRef || ''));
+  return m ? m[1] : '';
+}
+
+// A name that is safe to print into a session's context: no control characters,
+// no newlines, at most 60 characters.
+function cleanName(raw, fallback) {
+  const s = String(raw == null ? '' : raw).replace(/[\u0000-\u001f\u007f]+/g, ' ').replace(/\s+/g, ' ').trim().slice(0, 60);
+  return s || fallback;
+}
+
+// One line a person or an AI session reads: gentle, never a refusal.
+function noticeLine(n) {
+  const since = n.since ? new Date(n.since).toISOString().slice(0, 10) : 'recently';
+  return `${n.page_id} is being updated by ${n.holder} (since ${since}) — expect copy changes on it.`;
+}
+
+// Every open page marker, with its holder: ONE read for any number of tasks.
+async function openMarkers(exec) {
+  const { rows } = await exec.query(
+    `SELECT t.id AS task_id, t.source_ref, t.touches, c.claimed_at,
+            COALESCE(b.display_name, b.github_login) AS holder
+       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
+        AND t.source = '${PAGE_TWEAK_SOURCE}'
+        AND ${webClaimPredicate('c')}
+      ORDER BY c.claimed_at
+      LIMIT ${ROW_CAP}`
+  );
+  return rows;
+}
+
+function noticesFor(touches, markers, exceptTaskId) {
+  if (!Array.isArray(touches) || touches.length === 0) return [];
+  return markers
+    .filter((r) => String(r.task_id) !== String(exceptTaskId) && touchesOverlap(touches, r.touches))
+    .map((r) => {
+      const n = { page_id: pageIdOf(r.source_ref), holder: cleanName(r.holder, 'an artist'), since: r.claimed_at, task_id: String(r.task_id) };
+      return { ...n, line: noticeLine(n) };
+    })
+    .filter((n) => n.page_id);
+}
+
+// heldPagesForTouches(touches, exec, { exceptTaskId }) -> notices  (empty on no overlap or any failure)
+async function heldPagesForTouches(touches, exec, { exceptTaskId = null } = {}) {
+  if (!Array.isArray(touches) || touches.length === 0) return [];
+  try {
+    return noticesFor(touches, await openMarkers(exec), exceptTaskId);
+  } catch (_) {
+    return [];
+  }
+}
+
+// noticesForClaims(claims, exec) -> Map(task_id -> notices): ONE read for all of a
+// builder's claims (GET /me), instead of one per claim. A claim with no touches or
+// no overlap maps to [].
+async function noticesForClaims(claims, exec = api.pool) {
+  const out = new Map();
+  const list = Array.isArray(claims) ? claims : [];
+  for (const c of list) out.set(String(c.task_id), []);
+  if (list.length === 0) return out;
+  try {
+    const markers = await openMarkers(exec);
+    for (const c of list) out.set(String(c.task_id), noticesFor(c.touches, markers, c.task_id));
+  } catch (_) { /* heads-up only */ }
+  return out;
+}
+
+// engineeringActiveOnPage(pageTouches, exec) -> [{ task_id, holder }]
+// Open worktree claims on real code work (never a page round, whoever holds it)
+// whose files overlap the page's files. No title: see the header.
+async function engineeringActiveOnPage(pageTouches, exec = api.pool) {
+  if (!Array.isArray(pageTouches) || pageTouches.length === 0) return [];
+  try {
+    const { rows } = await exec.query(
+      `SELECT t.id AS task_id, t.touches, COALESCE(b.display_name, b.github_login) AS holder
+         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
+          AND t.source IS DISTINCT FROM '${PAGE_TWEAK_SOURCE}'
+        LIMIT ${ROW_CAP}`
+    );
+    return rows
+      .filter((r) => touchesOverlap(pageTouches, r.touches))
+      .map((r) => ({ task_id: String(r.task_id), holder: cleanName(r.holder, 'an engineer') }));
+  } catch (_) {
+    return [];
+  }
+}
+
+module.exports = { heldPagesForTouches, noticesForClaims, engineeringActiveOnPage };

package/modules/lifecycle/page-tweak-artist.js

@@ -24,6 +24,23 @@ function webClaimPredicate(alias = 'c') {
   return `${alias}.worktree_name IS NULL AND ${alias}.creator_session_id IS NULL`;
 }
 
+// A PAGE MARKER is an artist's web claim on a page-tweak round: it says "this
+// page is being updated" and nothing more. The file-overlap checks that guard
+// engineering work against engineering work (the claimable feed, claimTask,
+// the batch claim and its dry-run) leave markers out, so an artist writing a
+// page never hides or refuses coding work on the same files. That includes
+// claimTask's module-disjointness gate, which reads the same active-claim rows:
+// a page round carries no module_key, and a marker must never hold a module.
+// Returns a SQL condition that is true for every claim that is NOT a marker.
+// COALESCE keeps it TRUE (counted) when tasks.source is NULL: without it a
+// both-NULL claim on a source-less task would evaluate to NULL and vanish.
+// src/bongos/optimizer.js carries a hand copy (core cannot require a module);
+// tests/page_tweak_marker_sql.mjs pins the two together.
+// Aliases are code literals at every call site; never pass request input.
+function notPageMarkerSql(claimAlias = 'c', taskAlias = 't') {
+  return `NOT (COALESCE(${taskAlias}.source, '') = '${PAGE_TWEAK_SOURCE}' AND ${webClaimPredicate(claimAlias)})`;
+}
+
 // The newest claim first; the id breaks a same-instant tie the same way in
 // every reader.
 function latestFirst(alias = 'c') {
@@ -83,4 +100,4 @@ function helperJoinSql(alias = 't') {
            ) helper ON true`;
 }
 
-module.exports = { PAGE_TWEAK_SOURCE, webClaimPredicate, latestFirst, artistIdSql, shippedBySql, helperJoinSql };
+module.exports = { PAGE_TWEAK_SOURCE, webClaimPredicate, notPageMarkerSql, latestFirst, artistIdSql, shippedBySql, helperJoinSql };