@bongos/core 1.23.21 → 1.24.1

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

@@ -16,7 +16,7 @@ const doneWhen = require('./done-when.js');
 const { deriveRequiredRank, highestRank } = require('./db-rank-authz.js');
 const { nonTerminalSql, isTerminalStatus } = require('./task-status');
 const { maintenanceGoalTitle } = require('./goal-advisory.js');
-const { SMOKE_NOT_LIKE } = require('./db-shared.js');
+const { SMOKE_NOT_LIKE, idKey } = require('./db-shared.js');
 const { executorFor, inTransaction } = require('./db-executor.js');
 // Task 1003660 — closing a goal cancels its pending invites + join requests.
 const { cancelPendingMembershipRequests } = require('./goal-close-sweep.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 };
 }
@@ -733,28 +746,43 @@ async function archiveGoalWithDispositions({ goalId, plan = [], reason }, deps =
       return { goal: goalRows[0], applied: [], alreadyArchived: true };
     }
 
-    const applied = [];
-    for (const step of plan) {
+    // task 1004929: every plan task is locked and read in ONE statement, and the
+    // active claims on them in one more, instead of two round trips per step. The
+    // locks are taken in id order (no deadlock against another batch), then the
+    // plan is walked in memory in PLAN order, so the applied list and the first
+    // error are what the per-step loop produced. `inGoal` tracks this call's own
+    // writes, so a task named twice reads the state the first step left behind.
+    const inGoal = new Map();
+    const claimedIds = new Set();
+    if (plan.length > 0) {
+      const ids = plan.map((step) => step.taskId);
       const { rows: tRows } = await client.query(
-        `SELECT id, title, status FROM tasks WHERE id = $1 AND goal_id = $2 FOR UPDATE`,
-        [step.taskId, goalId]
+        `SELECT id, title, status FROM tasks WHERE id = ANY($1::bigint[]) AND goal_id = $2 ORDER BY id FOR UPDATE`,
+        [ids, goalId]
+      );
+      for (const row of tRows) inGoal.set(idKey(row.id), row);
+      const { rows: claimed } = await client.query(
+        `SELECT DISTINCT task_id FROM claims WHERE task_id = ANY($1::bigint[]) AND released_at IS NULL`, [ids]
       );
+      for (const row of claimed) claimedIds.add(idKey(row.task_id));
+    }
+
+    const applied = [];
+    for (const step of plan) {
+      const task = inGoal.get(idKey(step.taskId));
       // The task left this goal (or shipped) while the caller was deciding. Not an
       // error: the disposition is moot, and the final re-count is what actually
       // guards the invariant. Recorded as 'skipped' so the response tells the
       // truth about what this call did rather than claiming a write it never made.
-      if (!tRows[0]) { applied.push({ task_id: String(step.taskId), verb: step.verb, result: 'skipped_not_in_goal' }); continue; }
-      if (isTerminalStatus(tRows[0].status)) {
-        applied.push({ task_id: String(step.taskId), verb: step.verb, result: 'skipped_already_terminal', status: tRows[0].status });
+      if (!task) { applied.push({ task_id: String(step.taskId), verb: step.verb, result: 'skipped_not_in_goal' }); continue; }
+      if (isTerminalStatus(task.status)) {
+        applied.push({ task_id: String(step.taskId), verb: step.verb, result: 'skipped_already_terminal', status: task.status });
         continue;
       }
 
-      const { rows: claimed } = await client.query(
-        `SELECT id FROM claims WHERE task_id = $1 AND released_at IS NULL LIMIT 1`, [step.taskId]
-      );
-      if (claimed[0]) {
+      if (claimedIds.has(idKey(step.taskId))) {
         throw Object.assign(new Error('task has an active claim'), {
-          code: 'TASK_HAS_ACTIVE_CLAIM', taskId: String(step.taskId), taskTitle: tRows[0].title,
+          code: 'TASK_HAS_ACTIVE_CLAIM', taskId: String(step.taskId), taskTitle: task.title,
         });
       }
 
@@ -766,6 +794,7 @@ async function archiveGoalWithDispositions({ goalId, plan = [], reason }, deps =
             WHERE id = $1`,
           [step.taskId, `Abandoned: ${reason}`]
         );
+        task.status = 'abandoned';
         applied.push({ task_id: String(step.taskId), verb: 'abandon', result: 'abandoned' });
       } else {
         const { rows: dest } = await client.query(
@@ -780,6 +809,7 @@ async function archiveGoalWithDispositions({ goalId, plan = [], reason }, deps =
           });
         }
         await client.query(`UPDATE tasks SET goal_id = $2, updated_at = now() WHERE id = $1`, [step.taskId, step.toGoalId]);
+        if (idKey(step.toGoalId) !== idKey(goalId)) inGoal.delete(idKey(step.taskId));
         applied.push({ task_id: String(step.taskId), verb: 'move', result: 'moved', to_goal_id: String(step.toGoalId) });
       }
     }

package/modules/lifecycle/db-shared.js

@@ -104,10 +104,19 @@ async function mostRecentClaimHolderId(client, taskId) {
   return rows[0]?.builder_id ?? null;
 }
 
+// One spelling of a bigint id as a Map key (task 1004929). pg returns bigint
+// columns as strings while a plan may carry numbers, so a batched locked read
+// (the goal archive, the version close) matches its rows back to the plan steps
+// through this on both sides. A value BigInt cannot read keeps its own string.
+function idKey(v) {
+  try { return BigInt(v).toString(); } catch { return String(v); }
+}
+
 module.exports = {
   SMOKE_NOT_LIKE,
   gradePassCount,
   gradeQualityWhere,
+  idKey,
   median,
   mostRecentClaimHolderId,
   sealSessionLog,

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/db-versions.js

@@ -14,7 +14,7 @@ const api = require('../../src/module-api');
 const { pool, withTx } = api;
 const doneWhen = require('./done-when.js');
 const { nonTerminalSql } = require('./task-status');
-const { SMOKE_NOT_LIKE } = require('./db-shared.js');
+const { SMOKE_NOT_LIKE, idKey } = require('./db-shared.js');
 const { executorFor, inTransaction } = require('./db-executor.js');
 // db-goals.js does NOT require this file, so this direction adds no require cycle
 // (fitness pins the count). createVersion needs it to seed a version's FIRST goal
@@ -372,18 +372,29 @@ async function closeVersion({ versionId, plan = [], reason, planningVersionId =
       });
     }
 
-    const applied = [];
-    for (const step of plan) {
+    // task 1004929: every plan goal is locked and read in ONE statement instead of
+    // one round trip per step. Locks are taken in id order (no deadlock against
+    // another batch); the plan is then walked in memory in PLAN order, so the
+    // applied list is what the per-step loop produced. Each step's own archive is
+    // mirrored into `onVersion`, so a goal named twice reads 'archived' second time.
+    const onVersion = new Map();
+    if (plan.length > 0) {
       const { rows: gRows } = await client.query(
-        `SELECT id, title, status FROM goals WHERE id = $1 AND version_id = $2 FOR UPDATE`,
-        [step.goalId, versionId]
+        `SELECT id, title, status FROM goals WHERE id = ANY($1::bigint[]) AND version_id = $2 ORDER BY id FOR UPDATE`,
+        [plan.map((step) => step.goalId), versionId]
       );
+      for (const row of gRows) onVersion.set(idKey(row.id), row);
+    }
+
+    const applied = [];
+    for (const step of plan) {
+      const goal = onVersion.get(idKey(step.goalId));
       // The goal moved or closed itself while the caller was deciding. Not an
       // error — the final re-count is what guards the invariant — but recorded so
       // the response says what this call actually did.
-      if (!gRows[0]) { applied.push({ goal_id: String(step.goalId), verb: step.verb, result: 'skipped_not_on_version' }); continue; }
-      if (gRows[0].status !== 'open') {
-        applied.push({ goal_id: String(step.goalId), verb: step.verb, result: 'skipped_already_closed', status: gRows[0].status });
+      if (!goal) { applied.push({ goal_id: String(step.goalId), verb: step.verb, result: 'skipped_not_on_version' }); continue; }
+      if (goal.status !== 'open') {
+        applied.push({ goal_id: String(step.goalId), verb: step.verb, result: 'skipped_already_closed', status: goal.status });
         continue;
       }
 
@@ -410,6 +421,7 @@ async function closeVersion({ versionId, plan = [], reason, planningVersionId =
           [step.goalId, `Abandoned: ${reason}`]
         );
         await client.query(`UPDATE goals SET status = 'archived', updated_at = now() WHERE id = $1`, [step.goalId]);
+        Object.assign(goal, { status: 'archived' }); // mirror the write above for a goal named twice
         await cancelPendingMembershipRequests(client, step.goalId);
         applied.push({ goal_id: String(step.goalId), verb: 'abandon', result: 'archived', tasks_abandoned: killed.length });
       } else {
@@ -502,6 +514,7 @@ async function closeVersion({ versionId, plan = [], reason, planningVersionId =
         // on the way out rather than being special-cased around it (the brief's
         // explicit ask).
         await client.query(`UPDATE goals SET status = 'archived', updated_at = now() WHERE id = $1`, [step.goalId]);
+        Object.assign(goal, { status: 'archived' }); // mirror the write above for a goal named twice
         await cancelPendingMembershipRequests(client, step.goalId);
 
         applied.push({

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"