@bongos/core 1.24.10 → 1.24.12

package/modules/lifecycle/migrations/lifecycle_018_pay_terms.sql

@@ -0,0 +1,64 @@
+-- lifecycle_018_pay_terms.sql — task 1004990 (goal 1000092; ADR 0385 decision 3
+-- and its 2026-10-29 amendment).
+--
+-- The PROJECT sets the pay, not Bongos. A task can carry zero or more pay terms,
+-- each in the project's own words: a type, an amount and a unit as the project
+-- states them, and a note. A project can also keep standing pay terms that apply
+-- to every task without terms of its own — that is the project's pay policy,
+-- and per the owner's ruling it lives here, in the database, changed on the
+-- project's settings page, never in the branding pack.
+--
+-- A LIFECYCLE MIGRATION, NOT A CORE ONE: these are brand-new tables the lifecycle
+-- module owns (modules/lifecycle/pay-terms.js is their only reader and writer), so
+-- they are lifecycle_-namespaced here, the lifecycle_017_notes precedent — a core
+-- migration is only for a change to a core table.
+--
+-- RECORDS ONLY. Nothing here moves, holds, owes or guarantees money; the amount
+-- is TEXT on purpose, so no code can sum it into a balance (ADR 0387: money stays
+-- with the processor). Bongos suggests no amount: no column has a default.
+--
+-- THE SHAPE IS A HISTORY OF WHOLE SETS. Each change appends one set row (who,
+-- when, which task — NULL for the project's standing terms) and the terms that
+-- set holds. The newest set is current; a set with no terms means "no pay terms".
+-- So the audit trail of who changed what and when is the table itself, and
+-- nothing is ever edited or deleted: a row trigger refuses UPDATE and DELETE on
+-- both tables. (A whole-table wipe is not guarded here: the module-migration gate
+-- keeps module migrations additive and refuses that statement's keyword outright,
+-- and no code path in the tree issues one.)
+
+CREATE TABLE IF NOT EXISTS lifecycle_pay_term_sets (
+  id       bigserial PRIMARY KEY,
+  task_id  bigint REFERENCES tasks(id),          -- NULL = the project's standing terms
+  set_by   bigint NOT NULL REFERENCES builders(id),
+  set_at   timestamptz NOT NULL DEFAULT now()
+);
+
+-- The current set for a task (or for the project, task_id NULL): newest first.
+CREATE INDEX IF NOT EXISTS lifecycle_pay_term_sets_current
+  ON lifecycle_pay_term_sets (task_id, set_at DESC, id DESC);
+
+CREATE TABLE IF NOT EXISTS lifecycle_pay_terms (
+  id        bigserial PRIMARY KEY,
+  set_id    bigint NOT NULL REFERENCES lifecycle_pay_term_sets(id),
+  position  smallint NOT NULL CHECK (position BETWEEN 0 AND 9),
+  pay_type  text NOT NULL CHECK (pay_type IN
+              ('cash', 'equity', 'module_share', 'credit_pool', 'non_monetary', 'self_managed')),
+  amount    text CHECK (amount IS NULL OR char_length(amount) BETWEEN 1 AND 64),
+  unit      text CHECK (unit IS NULL OR char_length(unit) BETWEEN 1 AND 32),
+  note      text CHECK (note IS NULL OR char_length(note) BETWEEN 1 AND 500),
+  UNIQUE (set_id, position)
+);
+
+CREATE OR REPLACE FUNCTION lifecycle_pay_terms_refuse_change() RETURNS trigger AS $$
+BEGIN
+  RAISE EXCEPTION 'pay terms are a history: % on % is refused; set a new set of terms instead', TG_OP, TG_TABLE_NAME
+    USING ERRCODE = 'check_violation';
+END;
+$$ LANGUAGE plpgsql;
+
+DROP TRIGGER IF EXISTS lifecycle_pay_term_sets_append_only ON lifecycle_pay_term_sets;
+CREATE TRIGGER lifecycle_pay_term_sets_append_only BEFORE UPDATE OR DELETE ON lifecycle_pay_term_sets
+  FOR EACH ROW EXECUTE FUNCTION lifecycle_pay_terms_refuse_change();
+DROP TRIGGER IF EXISTS lifecycle_pay_terms_append_only ON lifecycle_pay_terms;
+CREATE TRIGGER lifecycle_pay_terms_append_only BEFORE UPDATE OR DELETE ON lifecycle_pay_terms
+  FOR EACH ROW EXECUTE FUNCTION lifecycle_pay_terms_refuse_change();

package/modules/lifecycle/pay-terms.js

@@ -0,0 +1,171 @@
+// modules/lifecycle/pay-terms.js — what a task pays, in the PROJECT's words
+// (task 1004990, goal 1000092; ADR 0385 decision 3 and its 2026-10-29 amendment).
+//
+// The project sets the pay, not Bongos. A task carries zero or more pay terms:
+// a type, and an amount, unit and note exactly as the project states them. A
+// project may also keep STANDING terms (task_id NULL) — its pay policy — which a
+// builder sees on any task that has none of its own. Per the owner's ruling that
+// policy lives in the database (modules/lifecycle/migrations/lifecycle_018_pay_terms.sql) and is changed
+// on the project's settings page, with the table itself as the audit trail; it
+// never lives in the branding pack.
+//
+// THREE RULES THIS FILE HOLDS:
+//   1. Bongos suggests no amount. There is no default and nothing is filled in:
+//      a term the project gave no amount has amount null, and every reader shows
+//      it as "not stated" — never a number Bongos chose.
+//   2. Records only. The amount is text as stated; nothing here parses, sums or
+//      converts it, so no balance or amount owed can come out of it (ADR 0387).
+//   3. A self-managed term always carries SELF_MANAGED_LABEL, so wherever it is
+//      shown it says Bongos moves and guarantees none of that money (plan P2.4).
+//
+// Who may write is decided by the ROUTE (task.edit for a task's terms,
+// project.settings.manage for the project's), on the server (ADR 0016).
+
+const api = require('../../src/module-api');
+
+const PAY_TYPES = ['cash', 'equity', 'module_share', 'credit_pool', 'non_monetary', 'self_managed'];
+const PAY_TYPE_LABELS = {
+  cash: 'Cash',
+  equity: 'Equity',
+  module_share: 'A share of a module',
+  credit_pool: 'A share of a credit pool',
+  non_monetary: 'Not money',
+  self_managed: 'Paid by the project itself',
+};
+const SELF_MANAGED_LABEL = 'Paid by the project on its own systems. Bongos does not move or guarantee this money.';
+const MAX_TERMS = 10;
+const LIMITS = { amount: 64, unit: 32, note: 500 };
+
+// PURE. Checks a list of terms as sent by a client. Returns { terms } (each
+// { pay_type, amount, unit, note }, blanks as null) or { error }. It never fills
+// a field in: what the project did not state stays null.
+function normalizePayTerms(input) {
+  if (!Array.isArray(input)) return { error: 'pay_terms is a list (empty for none).' };
+  if (input.length > MAX_TERMS) return { error: `A task carries at most ${MAX_TERMS} pay terms.` };
+  const terms = [];
+  for (let i = 0; i < input.length; i += 1) {
+    const t = input[i];
+    if (!t || typeof t !== 'object' || Array.isArray(t)) return { error: `pay term ${i + 1} is not an object.` };
+    const extra = Object.keys(t).filter((k) => !['pay_type', 'amount', 'unit', 'note'].includes(k));
+    if (extra.length) return { error: `pay term ${i + 1} has an unknown field: ${extra.join(', ')}.` };
+    if (!PAY_TYPES.includes(t.pay_type)) {
+      return { error: `pay term ${i + 1}: pay_type must be one of ${PAY_TYPES.join(', ')}.` };
+    }
+    const out = { pay_type: t.pay_type };
+    for (const field of ['amount', 'unit', 'note']) {
+      const v = t[field];
+      if (v == null) { out[field] = null; continue; }
+      if (typeof v !== 'string') return { error: `pay term ${i + 1}: ${field} is text, as the project states it.` };
+      const s = v.trim();
+      if (s.length > LIMITS[field]) return { error: `pay term ${i + 1}: ${field} is at most ${LIMITS[field]} characters.` };
+      out[field] = s || null;
+    }
+    terms.push(out);
+  }
+  return { terms };
+}
+
+// PURE. One stored term as every reader shows it. The self-managed label rides on
+// the term itself, so no surface can show the term without it.
+function displayTerm(row) {
+  return {
+    pay_type: row.pay_type,
+    type_label: PAY_TYPE_LABELS[row.pay_type] || row.pay_type,
+    amount: row.amount ?? null,
+    unit: row.unit ?? null,
+    note: row.note ?? null,
+    label: row.pay_type === 'self_managed' ? SELF_MANAGED_LABEL : null,
+  };
+}
+
+// Append one set: the whole list of terms for a task (taskId) or for the project
+// (taskId null). One transaction, so a set is never half-written. Returns the set.
+async function setPayTerms({ taskId = null, terms, builderId }, { db } = {}) {
+  const run = async (client) => {
+    const { rows: [set] } = await client.query(
+      'INSERT INTO lifecycle_pay_term_sets (task_id, set_by) VALUES ($1, $2) RETURNING id, task_id, set_by, set_at',
+      [taskId, builderId]);
+    // Every term in ONE statement, positions from unnest's ordinality, so a set of
+    // ten is one round trip, not ten.
+    if (terms.length) {
+      await client.query(
+        `INSERT INTO lifecycle_pay_terms (set_id, position, pay_type, amount, unit, note)
+         SELECT $1, (t.n - 1)::smallint, t.pay_type, t.amount, t.unit, t.note
+           FROM unnest($2::text[], $3::text[], $4::text[], $5::text[])
+                WITH ORDINALITY AS t(pay_type, amount, unit, note, n)`,
+        [set.id, terms.map((t) => t.pay_type), terms.map((t) => t.amount), terms.map((t) => t.unit), terms.map((t) => t.note)]);
+    }
+    return { set_id: set.id, task_id: set.task_id, set_by: set.set_by, set_at: set.set_at, terms: terms.map(displayTerm) };
+  };
+  if (db) return run(db);
+  return api.withTx(run);
+}
+
+// The current sets for these tasks, plus the project's standing set, in two reads
+// (lifecycle_pay_term_sets_current). Returns Map<taskIdString, view>, where a view is
+// { source: 'task' | 'project' | 'none', terms, set_by, set_at }. A task whose
+// newest set is EMPTY says so ('task', no terms): the project chose "no pay terms"
+// for it, which the standing terms must not paper over.
+async function readPayTerms(taskIds, { db } = {}) {
+  const exec = db || api.pool;
+  const ids = [...new Set((taskIds || []).map((x) => String(x)))];
+  const { rows: sets } = await exec.query(
+    `SELECT DISTINCT ON (task_id) id, task_id, set_by, set_at
+       FROM lifecycle_pay_term_sets
+      WHERE task_id = ANY($1::bigint[]) OR task_id IS NULL
+      ORDER BY task_id, set_at DESC, id DESC`, [ids]);
+  const setIds = sets.map((s) => s.id);
+  const termsBySet = new Map();
+  if (setIds.length) {
+    const { rows } = await exec.query(
+      `SELECT set_id, pay_type, amount, unit, note FROM lifecycle_pay_terms
+        WHERE set_id = ANY($1::bigint[]) ORDER BY set_id, position`, [setIds]);
+    for (const r of rows) {
+      const k = String(r.set_id);
+      if (!termsBySet.has(k)) termsBySet.set(k, []);
+      termsBySet.get(k).push(displayTerm(r));
+    }
+  }
+  const view = (s, source) => ({ source, terms: termsBySet.get(String(s.id)) || [], set_by: s.set_by, set_at: s.set_at });
+  const project = sets.find((s) => s.task_id == null);
+  const out = new Map();
+  for (const id of ids) {
+    const own = sets.find((s) => s.task_id != null && String(s.task_id) === id);
+    if (own) out.set(id, view(own, 'task'));
+    else if (project && (termsBySet.get(String(project.id)) || []).length) out.set(id, view(project, 'project'));
+    else out.set(id, { source: 'none', terms: [], set_by: null, set_at: null });
+  }
+  return out;
+}
+
+// The project's standing terms and their history (newest first, at most `limit`
+// sets), for the settings page: who changed what, and when.
+async function readProjectPayTerms({ db, limit = 10 } = {}) {
+  const exec = db || api.pool;
+  const { rows: sets } = await exec.query(
+    `SELECT s.id, s.set_by, s.set_at, b.github_login AS set_by_login
+       FROM lifecycle_pay_term_sets s LEFT JOIN builders b ON b.id = s.set_by
+      WHERE s.task_id IS NULL
+      ORDER BY s.set_at DESC, s.id DESC LIMIT $1`, [limit]);
+  const termsBySet = new Map();
+  if (sets.length) {
+    const { rows } = await exec.query(
+      `SELECT set_id, pay_type, amount, unit, note FROM lifecycle_pay_terms
+        WHERE set_id = ANY($1::bigint[]) ORDER BY set_id, position`, [sets.map((s) => s.id)]);
+    for (const r of rows) {
+      const k = String(r.set_id);
+      if (!termsBySet.has(k)) termsBySet.set(k, []);
+      termsBySet.get(k).push(displayTerm(r));
+    }
+  }
+  const history = sets.map((s) => ({
+    set_by: s.set_by, set_by_login: s.set_by_login || null, set_at: s.set_at,
+    terms: termsBySet.get(String(s.id)) || [],
+  }));
+  return { terms: history.length ? history[0].terms : [], history };
+}
+
+module.exports = {
+  PAY_TYPES, PAY_TYPE_LABELS, SELF_MANAGED_LABEL, MAX_TERMS,
+  normalizePayTerms, displayTerm, setPayTerms, readPayTerms, readProjectPayTerms,
+};

package/modules/lifecycle/routes/project-settings.js

@@ -34,9 +34,49 @@ const express = require('express');
 const api = require('../../../src/module-api');
 const goalCategory = require('../goal-category');
 const autopickup = require('../autopickup');
+const payTermsLib = require('../pay-terms'); // task 1004990
 
 const log = api.logger('lifecycle');
 
+// --- pay terms: the project's standing pay policy (task 1004990) --------------
+//
+// ADR 0385 decision 3: the project, not Bongos, sets the pay. The owner ruled
+// (2026-10-29) that this policy lives in a database table, changed here, with an
+// audit trail — never in the branding pack. The row carries the current terms,
+// the recent history (who, when, what) and the six types, and suggests no amount.
+function payTermsRow(policy) {
+  if (!policy) {
+    return {
+      key: 'pay_terms',
+      title: 'Pay terms',
+      editable: false,
+      state: 'unavailable',
+      sentence: 'The project’s pay terms could not be read just now.',
+      source: 'lifecycle_pay_term_sets / lifecycle_pay_terms tables',
+      reads: { file: 'lifecycle_pay_terms (migration lifecycle_018)', adr: 'ADR 0385' },
+    };
+  }
+  const terms = policy.terms || [];
+  return {
+    key: 'pay_terms',
+    title: 'Pay terms',
+    editable: true,
+    state: 'live',
+    value: {
+      terms,
+      history: (policy && policy.history) || [],
+      types: payTermsLib.PAY_TYPES.map((t) => ({ type: t, label: payTermsLib.PAY_TYPE_LABELS[t] })),
+      max: payTermsLib.MAX_TERMS,
+      self_managed_label: payTermsLib.SELF_MANAGED_LABEL,
+    },
+    sentence: terms.length
+      ? 'What this project pays for its work, in its own words. A builder sees it before claiming any task that has no pay terms of its own. Bongos records it and moves no money.'
+      : 'This project has not stated standing pay terms. A task can still carry its own. Bongos suggests no amount and moves no money.',
+    source: 'lifecycle_pay_term_sets / lifecycle_pay_terms tables',
+    reads: { file: 'lifecycle_pay_terms (migration lifecycle_018)', adr: 'ADR 0385' },
+  };
+}
+
 // --- ship mode: who starts a ship (task 1004628, ADR 0369) -------------------
 //
 // One row shape, two readers: the settings page (inside GET /project-settings) and
@@ -292,6 +332,12 @@ module.exports = function buildProjectSettingsRouter() {
       const categories = await goalCategory.listCategories({ includeInactive: true });
       const shipMode = await api.projectSettings.resolveShipMode();
       const tweak = await api.projectSettings.resolveTweakAutopickup();
+      // One unreadable table must not take the whole page down: the row says it
+      // could not be read, and the other rows still draw.
+      const payPolicy = await payTermsLib.readProjectPayTerms().catch((err) => {
+        log.error(`GET /project-settings: pay terms read failed: ${err && err.message}`);
+        return null;
+      });
 
       // A settings read is a configuration comparison — a cached one is wrong the
       // moment somebody turns a knob (the rot.js precedent).
@@ -339,6 +385,7 @@ module.exports = function buildProjectSettingsRouter() {
             source: 'work_categories table',
             reads: { file: 'work_categories (migration core_226)', adr: 'ADR 0192' },
           },
+          payTermsRow(payPolicy),
           creditRow(),
           equityRow(),
           upmarketRow(),
@@ -464,6 +511,53 @@ module.exports = function buildProjectSettingsRouter() {
     }
   });
 
+  // GET /pay-terms?task_ids=1,2,3 — what each task pays, in the project's words
+  // (task 1004990, ADR 0385 D3), for a list of tasks in one read: the hall task page
+  // and `bongos start` show it so a builder sees the pay BEFORE claiming. Each entry
+  // is { source: 'task' | 'project' | 'none', terms, set_by, set_at }; a task with
+  // none of its own shows the project's standing terms (set below), and a
+  // self-managed term carries its "Bongos does not move or guarantee this money"
+  // label. Records only — no amount here is a Bongos figure. It lives beside the
+  // standing-terms write because both serve the one pay-terms table pair.
+  // rank: any-builder — the same task metadata GET /tasks/:id serves; nothing changed.
+  router.get('/pay-terms', api.requireBuilder, async (req, res) => {
+    const raw = String((req.query && req.query.task_ids) || '');
+    const ids = raw.split(',').map((s) => s.trim()).filter(Boolean);
+    if (!ids.length || ids.length > 50 || !ids.every((s) => /^\d{1,18}$/.test(s))) {
+      return res.fail('bad_task_ids', { status: 400, message: 'task_ids is a comma list of 1 to 50 task ids.' });
+    }
+    try {
+      const map = await payTermsLib.readPayTerms(ids);
+      res.json({ pay_terms: Object.fromEntries(map) });
+    } catch (err) {
+      log.error(`GET /pay-terms: ${err && err.message}`);
+      res.fail('pay_terms_read_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // PATCH /project-settings/pay-terms — body { terms: [{ pay_type, amount?, unit?, note? }] }
+  // (task 1004990; ADR 0385 decision 3 and the owner's 2026-10-29 ruling). The
+  // project's STANDING pay terms: what a builder is shown on any task that carries
+  // none of its own. The whole list replaces the current set; [] means none. Every
+  // change is a new row naming who set it and when, and the old sets stay, so the
+  // table is the audit trail the owner asked for. Bongos fills nothing in.
+  //
+  // rank: project.settings.manage (metic+, government_010), the same atom as the
+  // other writes on this page.
+  router.patch('/project-settings/pay-terms', api.requireBuilder, api.requirePermission('project.settings.manage'), api.requireActAlone('rules'), async (req, res) => {
+    if (api.validateOrRespond(req, res, { terms: { required: true } })) return; // a list; checked by pay-terms.js
+    const parsed = payTermsLib.normalizePayTerms(req.body.terms);
+    if (parsed.error) return res.fail('bad_pay_terms', { status: 400, message: parsed.error });
+    try {
+      await payTermsLib.setPayTerms({ taskId: null, terms: parsed.terms, builderId: req.builder.id });
+      const policy = await payTermsLib.readProjectPayTerms();
+      res.json({ ok: true, row: payTermsRow(policy) });
+    } catch (err) {
+      log.error(`PATCH /project-settings/pay-terms: ${err && err.message}`);
+      res.fail('project_settings_write_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
   // --- tweak auto-pickup (task 1004677, ADR 0371 D3/D5) ----------------------
   //
   // GET /project-settings/tweak-autopickup — the switch, the monthly cap, and how

package/modules/lifecycle/routes/task-write-routes.js

@@ -28,6 +28,7 @@ const { isModuleKey, moduleKeys } = api.moduleScopeMap;
 const { validateOrRespond, LIMITS, parseId } = api;
 const { badKind, badNeeds, detectsMigration } = require('./task-route-helpers.js');
 const { describeCheckViolation } = require('../pg-constraint-fail.js');
+const payTermsLib = require('../pay-terms.js'); // task 1004990
 const { goalNotOpenRefusal } = require('./goal-route-authz.js');
 const { resolveUpkeepHome, isUpkeepFiling, UPKEEP_HINT } = require('../upkeep-home.js'); // task 1004597
 // task 1003208: structured logging (pino via the doorway) — was console.*.
@@ -39,6 +40,11 @@ module.exports = function registerTaskWriteRoutes(router) {
   // shape tasks. Was Archon-only (task #106 / ADR 0016; three-rank model #360 /
   // ADR 0018). A Xenos/Thetes still cannot author — they file ideas. Setting rank
   // and closing versions stay Archon. The every-route audit is task #231 (V3.R06).
+  // NO pay_terms HERE, on purpose (task 1004990): the task's rule is that only
+  // someone who may EDIT a task sets its pay terms, and this route is gated on
+  // task.create, not task.edit — so terms are set with PATCH /tasks/:id right after
+  // create, under that route's task.edit gate. The strict validator refuses the
+  // field here rather than letting a create quietly widen who may set pay.
   // rank: metic+archon — create work (plan/scope mutation); ADR 0090 (was ADR 0016/0018 archon).
   router.post('/tasks', auth.requireBuilder, auth.requirePermission('task.create'), async (req, res) => {
     if (validateOrRespond(req, res, {
@@ -387,6 +393,10 @@ module.exports = function registerTaskWriteRoutes(router) {
       // the hint had been unreachable dead code behind unknown_field since the
       // R11 strict-validation sweep landed after it.
       status: {},
+      // task 1004990 (ADR 0385 D3): the task's pay terms, in the project's own
+      // words — a list, [] for none. Checked inline by pay-terms.js; the whole list
+      // replaces the current set and the old set stays as history.
+      pay_terms: {},
     })) return;
     const id = parseId(req, res, { code: 'bad_task_id', positiveInt: true });
     if (id === null) return;
@@ -412,6 +422,7 @@ module.exports = function registerTaskWriteRoutes(router) {
     const hasTitle = Object.prototype.hasOwnProperty.call(body, 'title');
     const hasPriority = Object.prototype.hasOwnProperty.call(body, 'priority');
     const hasValueSummary = Object.prototype.hasOwnProperty.call(body, 'value_summary');
+    const hasPayTerms = Object.prototype.hasOwnProperty.call(body, 'pay_terms');
     // #514: status is a lifecycle field, not a PATCH-able column — it moves only
     // through the dedicated transition routes. The #506 session tried
     // `PATCH status=ready`, got the generic no_supported_fields error, and had
@@ -423,8 +434,8 @@ module.exports = function registerTaskWriteRoutes(router) {
     if (Object.prototype.hasOwnProperty.call(body, 'status')) {
       return res.fail('status_not_patchable', { status: 400, message: STATUS_HINT });
     }
-    if (!hasParent && !hasKind && !hasDiscipline && !hasNewcomerOrXenos && !hasParallelSafe && !hasSecuritySensitive && !hasAutomationTag && !hasNeeds && !hasNeedsMigration && !hasRequiresRank && !hasModuleKey && !hasGoalId && !hasDescription && !hasTitle && !hasPriority && !hasValueSummary) {
-      return res.fail('no_supported_fields', { status: 400, message: 'PATCH /tasks/:id supports parent_task_id, kind, discipline, title, description, value_summary, priority, parallel_safe, security_sensitive, automation_tag, needs, needs_migration, requires_rank, module_key, goal_id, and newcomer_friendly (alias: xenos_claimable). ' + STATUS_HINT });
+    if (!hasParent && !hasKind && !hasDiscipline && !hasNewcomerOrXenos && !hasParallelSafe && !hasSecuritySensitive && !hasAutomationTag && !hasNeeds && !hasNeedsMigration && !hasRequiresRank && !hasModuleKey && !hasGoalId && !hasDescription && !hasTitle && !hasPriority && !hasValueSummary && !hasPayTerms) {
+      return res.fail('no_supported_fields', { status: 400, message: 'PATCH /tasks/:id supports parent_task_id, kind, discipline, title, description, value_summary, priority, pay_terms, parallel_safe, security_sensitive, automation_tag, needs, needs_migration, requires_rank, module_key, goal_id, and newcomer_friendly (alias: xenos_claimable). ' + STATUS_HINT });
     }
     // ---- task 1002609 (G-22): settle EVERY gate and validation before the ----
     // ---- FIRST write. The previous shape validated-and-wrote per field in ----
@@ -555,6 +566,16 @@ module.exports = function registerTaskWriteRoutes(router) {
         return res.fail(`bad_${field}`, { status: 400, message: `${field} must be a boolean` });
       }
     }
+    // task 1004990: pay terms are checked here with the other gates, so a bad list
+    // refuses the whole request before any field is written. Who may set them is
+    // this route's own task.edit gate (ADR 0016) — the same person who may edit
+    // the task. Nothing is filled in: a term without an amount stays without one.
+    let payTerms = null;
+    if (hasPayTerms) {
+      payTerms = payTermsLib.normalizePayTerms(body.pay_terms);
+      if (payTerms.error) return res.fail('bad_pay_terms', { status: 400, message: payTerms.error });
+      if (!(await db.getTask(id))) return res.fail('task_not_found', 404);
+    }
     // ---- all gates passed: apply the writes. Order preserved from the old ----
     // shape — requires_rank still runs AFTER security_sensitive so a
     // same-request flag flip is already reflected in the derived floor.
@@ -695,10 +716,20 @@ module.exports = function registerTaskWriteRoutes(router) {
         return res.fail('patch_failed', { status: 500, message: 'internal error' });
       }
     }
-    if (!hasParent) return res.json({ task: updated });
+    let payTermsSet;
+    if (hasPayTerms) {
+      try {
+        payTermsSet = await payTermsLib.setPayTerms({ taskId: id, terms: payTerms.terms, builderId: req.builder.id });
+        if (!updated) updated = await db.getTask(id);
+      } catch (err) {
+        log.error('[gds] PATCH /tasks/:id pay_terms', err);
+        return res.fail('patch_failed', { status: 500, message: 'internal error' });
+      }
+    }
+    if (!hasParent) return res.json(payTermsSet ? { task: updated, pay_terms: payTermsSet } : { task: updated });
     try {
       const task = await hierarchy.attachParent(id, body.parent_task_id);
-      res.json({ task });
+      res.json(payTermsSet ? { task, pay_terms: payTermsSet } : { task });
     } catch (err) {
       if (err && err.code) {
         const status =

package/modules/market-watch/db.js

@@ -130,14 +130,16 @@ const FOUND_IN_SQL = `
     JOIN market_watch_items i ON i.id = e.item_id
    WHERE i.project = $1 AND e.run_id IS NOT NULL AND ($2::bigint IS NULL OR e.item_id = $2)`;
 
+// `knownRuns` (here, in getItem, caseFile and scoreHistory): the numbered runs when the caller
+// already read them, so one page load reads market_watch_runs once (task 1004939).
 // listItems — the home desk: every tracked item with its latest overall score, last
 // finding, level and streak.
-async function listItems(pool, { project, kind = null, includeRemoved = false, id = null } = {}) {
+async function listItems(pool, { project, kind = null, includeRemoved = false, id = null, knownRuns = null } = {}) {
   need(project);
   const [{ rows: items }, { rows: found }, runs] = await Promise.all([
     pool.query(ITEMS_SQL, [project, kind, includeRemoved, id]),
     pool.query(FOUND_IN_SQL, [project, id]),
-    numberedRuns(pool, { project }),
+    knownRuns || numberedRuns(pool, { project }),
   ]);
   const byItem = new Map();
   for (const f of found) {
@@ -154,8 +156,8 @@ async function listItems(pool, { project, kind = null, includeRemoved = false, i
 }
 
 // getItem — one item, with removed ones included (its page still opens).
-async function getItem(pool, { project, id }) {
-  const rows = await listItems(pool, { project, includeRemoved: true, id });
+async function getItem(pool, { project, id, knownRuns = null }) {
+  const rows = await listItems(pool, { project, includeRemoved: true, id, knownRuns });
   return rows[0] || null;
 }
 
@@ -168,11 +170,11 @@ const CASE_FILE_SQL = `
    ORDER BY e.pinned DESC, e.found_on DESC, e.id DESC`;
 
 // caseFile — the item page's sortable table: found, run, type, takeaway, confidence, source.
-async function caseFile(pool, { project, itemId }) {
+async function caseFile(pool, { project, itemId, knownRuns = null }) {
   need(project);
   const [{ rows }, runs] = await Promise.all([
     pool.query(CASE_FILE_SQL, [project, itemId]),
-    numberedRuns(pool, { project }),
+    knownRuns || numberedRuns(pool, { project }),
   ]);
   const runN = new Map(runs.map((r) => [String(r.id), r.n]));
   return rows.map((e) => ({ ...e, id: Number(e.id), run: e.run_id == null ? null : runN.get(String(e.run_id)) ?? null }));
@@ -185,11 +187,11 @@ const SCORES_SQL = `
    WHERE i.project = $1 AND s.item_id = $2`;
 
 // scoreHistory — the item page's sparklines, one per dimension plus 'overall'.
-async function scoreHistory(pool, { project, itemId }) {
+async function scoreHistory(pool, { project, itemId, knownRuns = null }) {
   need(project);
   const [{ rows }, runs] = await Promise.all([
     pool.query(SCORES_SQL, [project, itemId]),
-    numberedRuns(pool, { project }),
+    knownRuns || numberedRuns(pool, { project }),
   ]);
   return sparklines(rows, runs);
 }

package/modules/market-watch/module.json

@@ -1,7 +1,7 @@
 {
   "key": "market-watch",
   "title": "Market Watch (a weekly AI watch on a project's market)",
-  "description": "A weekly AI watch on a project's competitors, partners and topics, with a sourced log per tracked item and a weekly question to members (goal 1000137). Its data model (tables, read queries and the hub seed of the 2026-10-28 research), its weekly run (an hourly poller that researches each tracked item on the project's own Anthropic key, under the monthly cap), the weekly ask card in the hall's attention inbox (task 1004940), its rules page (the watch rules in plain words, members' proposed changes, and the owner's or the government's decision on each, task 1004941) and the owner's settings (on/off, monthly cap, cadence, the project key; task 1004938) are in. Off by default, and it cannot be turned on behind an open join door with no payer, because every run will spend the project's AI budget.",
+  "description": "A weekly AI watch on a project's competitors, partners and topics, with a sourced log per tracked item and a weekly question to members (goal 1000137). Its data model (tables, read queries and the hub seed of the 2026-10-28 research), its weekly run (an hourly poller that researches each tracked item on the project's own Anthropic key, under the monthly cap), the weekly ask card in the hall's attention inbox (task 1004940), its home and tracked-item pages (task 1004939), its rules page (the watch rules in plain words, members' proposed changes, and the owner's or the government's decision on each, task 1004941) and the owner's settings (on/off, monthly cap, cadence, the project key; task 1004938) are in. Off by default, and it cannot be turned on behind an open join door with no payer, because every run will spend the project's AI budget.",
   "version": "0.4.0",
   "coreVersion": "^1.22.0",
   "category": {
@@ -15,6 +15,7 @@
     "migrations": true,
     "routes": [
       "ask",
+      "pages",
       "rules",
       "settings"
     ],