@bongos/core 1.23.21 → 1.24.1

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

@@ -7,8 +7,9 @@
 // WHY THIS ROUTE EXISTS. Goal 1000072's thesis is that this project is legible to
 // Claude and illegible to a human: the system knows everything and exposes almost
 // none of it in a shape a person can hold. The five values here — the rot timer, the
-// category set, how credits are calculated, whether equity is real, and what share of
-// upmarket revenue is paid on credits — were each answerable only by reading source.
+// category set, how credits are calculated, what credits are (and are not) next to
+// equity, and whether a credit-weighted pool can pay out — were each answerable only
+// by reading source.
 // This route is the TRANSLATION LAYER, not a new capability: it invents no value and
 // stores nothing of its own.
 //
@@ -20,10 +21,11 @@
 // and say why.
 //
 // AND THE ONE THAT KEEPS IT HONEST: a fundamental with no knob behind it is reported
-// as ABSENT, never as a plausible zero. `upmarket_percent` is that row today — the
-// task asked for it, and no such knob exists anywhere in this codebase. Rendering it
-// as "0%" would be a fabricated fact about the project's economics; saying "there is
-// no such setting yet, and here is where it would live" is the legible answer.
+// as ABSENT or GATED, never as a plausible zero. `upmarket_percent` (shown as the
+// credit-weighted pool) is that row today: no such knob exists, and ADR 0385 gates
+// the pay type behind counsel and a signed rule. Rendering it as "0%" would be a
+// fabricated fact about the project's economics; saying "not available, and here is
+// what gates it" is the legible answer.
 //
 // MODULE BOUNDARY: reaches core only through the published doorway
 // `../../../src/module-api`; `../goal-category` is an intra-module sibling.
@@ -118,58 +120,64 @@ function creditRow() {
   // (ADR 0146). A page that showed the estimate without that sentence would be telling
   // a builder they will earn a number this instance has decided not to pay.
   const estimate = policy.perTaskCredit
-    ? 'A task’s own credit estimate is also paid, scaled by its kind.'
-    : 'A task’s credit estimate is an advertised guide only — this instance pays cost-plus and nothing else.';
+    ? 'A task’s own credit estimate is also awarded, scaled by its kind.'
+    : 'A task’s credit estimate is an advertised guide only — this instance awards cost-plus credits and nothing else.';
+  // Wording per ADR 0387: the formula's INPUT is USD, so the credits are "sized by"
+  // the session's cost — never "worth" dollars, and never money.
   return {
     key: 'credit_calculation',
     title: 'Credit calculation',
     editable: false,
     state: 'live',
     value: { marginPct: policy.marginPct, usdPeg: policy.usdPeg, mode: policy.mode, perTaskCredit: policy.perTaskCredit },
-    sentence: `A shipped session pays round(true cost in USD × ${mult}${pegNote}). ${estimate}`,
+    sentence: `A shipped session earns round(true cost in USD × ${mult}${pegNote}) credits, sized by the session’s cost in USD. Credits measure contribution; they are not money. ${estimate}`,
     source: 'branding pack → `reward`',
     reads: { file: 'config/branding.json → reward', adr: 'ADR 0054, ADR 0146' },
   };
 }
 
-// Equity. THE OWNER DECIDED THIS (2026-08-25) and the decision is that it is NOT REAL:
-// credits ARE the ownership stream today, and no legal equity is issued. The page says
-// that plainly rather than implying a cap table exists — an owner reading their own
-// settings page must not come away believing shares are being issued. If issuance ever
-// becomes real it gets its own decision record; the Board Room spec already parks
-// Howey / Subchapter T explicitly out of scope.
+// Equity. Bongos issues none, and credits are NOT equity. The owner's 2026-08-25
+// decision (no legal equity issued) stands; the older ADR 0054 framing that a credit
+// IS a unit of ownership was superseded on 2026-10-29 (ADR 0385 decisions 2-3, ADR
+// 0387): credits are a project-scoped contribution meter, and equity, if a project
+// offers any, is that project's own grant, one signature each. The page says that
+// plainly — an owner reading their own settings page must not come away believing
+// credits are shares or that a cap table exists. The key stays `equity_calculation`
+// so existing readers keep working.
 function equityRow() {
   return {
     key: 'equity_calculation',
-    title: 'Equity calculation',
+    title: 'Equity',
     editable: false,
     state: 'not-yet-real',
-    sentence: 'No legal equity is issued. Credits are the ownership stream this project actually runs — '
-      + 'the owner’s framing in ADR 0054 is that a credit IS a unit of ownership. There is no cap table, '
-      + 'no share class and no issuance behind this row.',
-    source: 'owner decision, 2026-08-25',
-    reads: { file: 'docs/adr/0054-drachmae-token-reward.md', adr: 'ADR 0054' },
+    sentence: 'Credits are a contribution meter, not ownership: they measure work on this project '
+      + 'and are never money, never redeemable and never equity. No legal equity is issued here. '
+      + 'Equity, if any, is granted by the project separately, one signed grant at a time — '
+      + 'there is no cap table and no share class behind this row.',
+    source: 'owner decisions, 2026-08-25 and 2026-10-29',
+    reads: { file: 'docs/adr/0054-session-token-reward-cost-plus.md', adr: 'ADR 0054 (superseded in part), ADR 0385, ADR 0387' },
   };
 }
 
-// The share of upmarket revenue paid out on credits. NO SUCH KNOB EXISTS — searched
-// across code, config, migrations and docs on this task and found only prose in an
-// unrelated competitive-analysis file. So this row reports ABSENCE and names where the
-// setting would live if it became real, which is the actionable fact. A rendered "0%"
-// would be a fabricated economic claim; an omitted row would leave the owner to
-// rediscover the gap by grep.
+// The credit-weighted pool: a project dividing a pool of its OWN money by credit
+// share (ADR 0387 decision 3). The row key stays `upmarket_percent` (its first name,
+// "share of upmarket revenue paid on credits") so existing readers keep working.
+// NO SUCH KNOB EXISTS, and ADR 0385's pay-type gates hold this one shut until the
+// wording rule is in force, the model's inputs are visible and a signed payout rule
+// exists — with counsel's answer on held item 2 first. So the row reports GATED,
+// never a rendered "0%", which would be a fabricated economic claim.
 function upmarketRow() {
   return {
     key: 'upmarket_percent',
-    title: 'Percent of upmarket revenue paid on credits',
+    title: 'Credit-weighted pool',
     editable: false,
-    state: 'absent',
-    sentence: 'This project has no such setting yet — nothing in the code, config or database '
-      + 'defines it, so there is no number to show. It would belong beside the other reward '
-      + 'terms in the branding pack’s `reward` block, and paying against it would need its own '
-      + 'decision record first.',
-    source: 'not configured anywhere',
-    reads: { file: 'config/branding.json → reward (where it would live)', adr: null },
+    state: 'gated',
+    sentence: 'Not available (gated). A project could one day divide a pool of its own money by '
+      + 'credit share, but that pay type stays switched off until counsel clears it and the '
+      + 'project signs a payout rule. Bongos sets no share and no rate, and no dollar value is '
+      + 'ever read off a credit.',
+    source: 'gated by ADR 0385 (pay-type gates)',
+    reads: { file: 'docs/adr/0385-money-lives-with-a-processor-credits-stay-a-project-meter.md', adr: 'ADR 0385, ADR 0387' },
   };
 }
 

package/modules/lifecycle/routes/task-route-helpers.js

@@ -251,10 +251,31 @@ function badKind(res) {
 }
 
 
+// task 1004950 / ADR 0395: a task's needs are a subset of TASK_NEEDS. Shared by
+// POST /tasks, PATCH /tasks/:id and POST /goals/:id/tasks so all three refuse alike.
+function badNeeds(res, bad) {
+  const valid = api.taskNeeds.TASK_NEEDS;
+  return res.fail('bad_needs', { status: 400, message: `needs must list only: ${valid.join(', ')} (unknown: ${bad.join(', ')}). Most tasks need neither.`, details: { valid } });
+}
+
+// ?needs= on GET /tasks and GET /tasks/claimable (task 1004950): one need
+// ('owner' | 'server') or 'none'. Shared so the two lists agree on the vocabulary.
+const NEEDS_FILTERS = new Set([...api.taskNeeds.TASK_NEEDS, 'none']);
+function parseNeedsFilter(raw) {
+  if (raw === undefined || raw === '') return undefined;
+  return NEEDS_FILTERS.has(raw) ? raw : { bad: 'bad_needs' };
+}
+function badNeedsFilter(res) {
+  return res.fail('bad_needs', { status: 400, message: `needs must be one of ${[...NEEDS_FILTERS].join(' | ')}.` });
+}
+
 module.exports = {
+  badNeedsFilter,
+  parseNeedsFilter,
   MIGRATION_KEYWORD_RE,
   VALID_FITS,
   badKind,
+  badNeeds,
   deHashRefs,
   detectsMigration,
   gateTaskOwnership,

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

@@ -26,7 +26,7 @@ const { buildDependencyAdvisory } = require('../dependency-advisory');
 const { classifyTaskKind, VALID_KINDS, WRITABLE_DISCIPLINES, resolveWriteDiscipline, VOTABLE_TASK_STATUSES, TASK_FIELD_BOUNDS } = require('../task-classifier');
 const { isModuleKey, moduleKeys } = api.moduleScopeMap;
 const { validateOrRespond, LIMITS, parseId } = api;
-const { badKind, detectsMigration } = require('./task-route-helpers.js');
+const { badKind, badNeeds, detectsMigration } = require('./task-route-helpers.js');
 const { describeCheckViolation } = require('../pg-constraint-fail.js');
 const { goalNotOpenRefusal } = require('./goal-route-authz.js');
 const { resolveUpkeepHome, isUpkeepFiling, UPKEEP_HINT } = require('../upkeep-home.js'); // task 1004597
@@ -62,6 +62,7 @@ module.exports = function registerTaskWriteRoutes(router) {
       newcomer_friendly: { type: 'boolean' },  // V3.R15 #239 — Xenos-claimable flag
       security_sensitive: { type: 'boolean' },  // task 990 — Archon-only ship broadcast
       requires_rank: { type: 'string', maxLength: 16 },  // task 1498 / ADR 0084 — per-task rank floor (auto-derived; explicit value can only raise it)
+      needs: {},  // task 1004950 / ADR 0395 — ['owner'|'server'] or a comma list; checked inline
       auto_detect_touches: { type: 'boolean' },
       // task 438: link the new task to done-when criteria at creation time. Each
       // element is a criterion_id slug (required on a multi-goal version — task
@@ -169,6 +170,9 @@ module.exports = function registerTaskWriteRoutes(router) {
         return res.fail('bad_requires_rank', { status: 400, message: `requires_rank must be one of ${db.LIVE_RANK_LADDER.join(' | ')}. The floor auto-derives from touches + security_sensitive; an explicit value can only raise it.`, details: { valid: db.LIVE_RANK_LADDER } });
       }
     }
+    // task 1004950 / ADR 0395: what the task needs beyond the build loop.
+    const createNeeds = api.taskNeeds.normalizeNeeds(body.needs);
+    if (!createNeeds.ok) return badNeeds(res, createNeeds.bad);
     // BV1.R53 (task 1422): validate module_key against MODULE_SCOPE_MAP.
     if (body.module_key != null && !isModuleKey(body.module_key)) {
       return res.fail('bad_module_key', { status: 400, message: `module_key must be one of the known module keys, or omitted. Valid keys: ${moduleKeys().join(', ')}.`, details: { valid: moduleKeys() } });
@@ -245,6 +249,7 @@ module.exports = function registerTaskWriteRoutes(router) {
         requiresRank: body.requires_rank ?? null,
         moduleKey: body.module_key ?? null,
         goalId: body.goal_id ?? null,
+        needs: createNeeds.needs,
         // task 1003278 — attribution, from the AUTHENTICATED request, never the
         // body: who created a task is a fact about the caller, not an input.
         createdBy: req.builder.id,
@@ -348,6 +353,7 @@ module.exports = function registerTaskWriteRoutes(router) {
       xenos_claimable: { type: 'boolean' },              // pre-rename alias for newcomer_friendly
       security_sensitive: { type: 'boolean' },           // task 990 — Archon-only ship broadcast
       automation_tag: { type: 'string', maxLength: 64 },
+      needs: {},                                         // task 1004950 — ['owner'|'server'], a comma list, or null/[] to clear; checked inline
       needs_migration: { type: 'boolean' },              // task 1002648 — correct the create-time heuristic's flag (the claim-time allocator keys off it)
       // task 1002647 (map s4.3): the task body is a load-bearing builder prompt
       // and was settable only at create — no route edited it at any rank. Now
@@ -397,6 +403,7 @@ module.exports = function registerTaskWriteRoutes(router) {
     const hasParallelSafe = Object.prototype.hasOwnProperty.call(body, 'parallel_safe');
     const hasSecuritySensitive = Object.prototype.hasOwnProperty.call(body, 'security_sensitive');
     const hasAutomationTag = Object.prototype.hasOwnProperty.call(body, 'automation_tag');
+    const hasNeeds = Object.prototype.hasOwnProperty.call(body, 'needs');
     const hasNeedsMigration = Object.prototype.hasOwnProperty.call(body, 'needs_migration');
     const hasRequiresRank = Object.prototype.hasOwnProperty.call(body, 'requires_rank');
     const hasModuleKey = Object.prototype.hasOwnProperty.call(body, 'module_key');
@@ -416,8 +423,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 && !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_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) {
+      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 });
     }
     // ---- task 1002609 (G-22): settle EVERY gate and validation before the ----
     // ---- FIRST write. The previous shape validated-and-wrote per field in ----
@@ -476,6 +483,8 @@ module.exports = function registerTaskWriteRoutes(router) {
         return res.fail('bad_automation_tag', { status: 400, message: 'automation_tag must be one of overnight-safe | live-only | needs-input, or null to clear', details: { valid: Array.from(VALID_AUTOMATION_TAGS) } });
       }
     }
+    const patchNeeds = hasNeeds ? api.taskNeeds.normalizeNeeds(body.needs) : null;
+    if (patchNeeds && !patchNeeds.ok) return badNeeds(res, patchNeeds.bad);
     if (hasModuleKey) {
       // BV1.R53 (task 1422): assign or clear the module affinity label. null clears.
       if (body.module_key !== null && !isModuleKey(body.module_key)) {
@@ -577,6 +586,15 @@ module.exports = function registerTaskWriteRoutes(router) {
         return res.fail('patch_failed', { status: 500, message: 'internal error' });
       }
     }
+    if (hasNeeds) {
+      try {
+        updated = await db.updateTaskNeeds(id, patchNeeds.needs);
+        if (!updated) return res.fail('task_not_found', 404);
+      } catch (err) {
+        log.error('[gds] PATCH /tasks/:id needs', err);
+        return res.fail('patch_failed', { status: 500, message: 'internal error' });
+      }
+    }
     if (hasNeedsMigration) {
       try {
         updated = await db.updateTaskNeedsMigration(id, body.needs_migration);

package/modules/lifecycle/routes/tasks.js

@@ -91,7 +91,7 @@ const PUBLISH_BUNDLE_MAX_BYTES = 20 * 1024 * 1024; // 20 MB decoded bundle
 // autolinks to GitHub's own issue space (dead links for GDS task ids — task 916).
 // Mirrors ship.js sanitizeGitHubRefs (which lives in scripts/ and isn't requirable
 // here).
-const { MIGRATION_KEYWORD_RE, VALID_FITS, badKind, deHashRefs, detectsMigration, gateTaskOwnership, graderBypassEnabled, isVerifyTask, peerVoteNet, postGateAuthorTrust, rankAttestsGateTrust } = require('./task-route-helpers.js');
+const { MIGRATION_KEYWORD_RE, VALID_FITS, badKind, badNeedsFilter, parseNeedsFilter, deHashRefs, detectsMigration, gateTaskOwnership, graderBypassEnabled, isVerifyTask, peerVoteNet, postGateAuthorTrust, rankAttestsGateTrust } = require('./task-route-helpers.js');
 // task 1003208: structured logging (pino via the doorway) — was console.*.
 const log = api.logger('lifecycle');
 const registerTaskWriteRoutes = require('./task-write-routes.js'); // task 1003206 — POST /tasks + PATCH /tasks/:id
@@ -176,10 +176,11 @@ module.exports = function buildTasksRouter() {
     if (limit && limit.bad) return res.fail('bad_limit', { status: 400, message: 'limit must be a positive integer up to 1000.' });
     const offset = posInt(offsetRaw, 'bad_offset');
     if (offset && offset.bad) return res.fail('bad_offset', { status: 400, message: 'offset must be a positive integer.' });
+    const needs = parseNeedsFilter(req.query.needs); if (needs && needs.bad) return badNeedsFilter(res); // task 1004950
 
     const tasks = await db.listTasks({
       versionId: version, status, kind, discipline, goalId,
-      createdBy, staleDays, limit, offset,
+      createdBy, staleDays, limit, offset, needs,
     });
     // ?include=deps (hall redesign task 1002439) — enrich each task with its
     // dependency summary (`blocked_by[]` with per-target satisfied state, and a
@@ -216,16 +217,15 @@ module.exports = function buildTasksRouter() {
     if (claimStaleDays && claimStaleDays.bad) return res.fail('bad_stale_days', { status: 400, message: 'stale_days must be a positive integer number of days.' });
     // ?limit=N — opt-in, for a caller that renders N rows (goal 1000072). It slices the
     // RETURNED feed, never the query — lifecycle/CLAUDE.md has the why.
+    const claimNeeds = parseNeedsFilter(req.query.needs); if (claimNeeds && claimNeeds.bad) return badNeedsFilter(res); // task 1004950
     const claimLimit = posInt(req.query.limit, 'bad_limit', 1000);
     if (claimLimit && claimLimit.bad) return res.fail('bad_limit', { status: 400, message: 'limit must be a positive integer (max 1000).' });
     const [feed, active] = await Promise.all([
       db.listClaimableTasks({
-        versionId: version || null,
-        builderId: req.builder.id,
-        discipline: discipline || null,
-        fit: fit || null,
+        versionId: version || null, builderId: req.builder.id,
+        discipline: discipline || null, fit: fit || null,
         createdBy: claimCreatedBy ?? null,
-        staleDays: claimStaleDays ?? null,
+        staleDays: claimStaleDays ?? null, needs: claimNeeds ?? null,
       }),
       req.query.group === 'goal' ? [] : db.listActiveClaims(),
     ]);
@@ -507,11 +507,11 @@ module.exports = function buildTasksRouter() {
   // the numeric done_when_criteria.id, mirroring DELETE deps/:depId).
   // rank: metic+archon — removes a criterion↔task edge; task-shaping, Metic+ (ADR 0090).
   router.delete('/tasks/:id/criteria/:criterionId', auth.requireBuilder, auth.requirePermission('task.criterion.manage'), async (req, res) => {
-    const id = Number(req.params.id);
-    const criterionId = Number(req.params.criterionId);
-    if (!Number.isFinite(id) || !Number.isFinite(criterionId)) {
-      return res.fail('bad_task_id', 400);
-    }
+    // task 1004984: whole positive ids only (Number.isFinite let 7.5 through).
+    const id = parseId(req, res, { code: 'bad_task_id', positiveInt: true });
+    if (id === null) return;
+    const criterionId = parseId(req, res, { param: 'criterionId', code: 'bad_criterion_id', positiveInt: true });
+    if (criterionId === null) return;
     const removed = await db.removeTaskCriterion(id, criterionId);
     res.json({ ok: true, removed });
   });

package/modules/lifecycle/ship-assurance.js

@@ -194,12 +194,15 @@ function githubAccessCause(errors) {
 // best-effort by design: insertAuditLog uses the module pool rather than the
 // ship's transaction client, and an audit miss must never roll back a landed ship
 // (the posture src/bongos/middleware/audit.js already takes).
+// method is 'POST' — the ship route's own verb. audit_log's CHECK admits only
+// POST/PATCH/PUT/DELETE (migration 033), so the old 'SHIP' failed every write
+// and the record never existed (task 1004879).
 async function recordShipAssurance({ insertAuditLog, taskId, builderId, assurance, log }) {
   try {
     await insertAuditLog({
       builderId,
       route: `/tasks/${taskId}/ship`,
-      method: 'SHIP',
+      method: 'POST',
       requestBodyRedacted: { ship_assurance: assurance },
       responseStatus: 200,
       surface: 'lifecycle',

package/modules/lifecycle/ship-card.js

@@ -447,10 +447,15 @@ function buildCardModel(input = {}) {
     let deployText;
     let deployCommit = null;
     let hostedText = null;
+    // task 1004741: "live" only when a reading SAYS the live build carries this
+    // merge. Shipped means merged; a merge reaches no instance until a published
+    // release carries it and the pin moves (merge-reach.js).
+    let liveConfirmed = false;
     if (stage === 'shipped') {
       deployCommit = input.deploy && input.deploy.commit ? String(input.deploy.commit) : null;
       const reach = boundReading(input.deploy && input.deploy.reach);
       if (reach) {
+        liveConfirmed = reach.includes === true;
         // task 1004682: who sees this merge, in the one shared wording
         // (merge-reach.js) — the hub's live build as read, then the hosted rule.
         // A bare "live · <sha>" read as "every user has it", which is only true
@@ -458,7 +463,8 @@ function buildCardModel(input = {}) {
         // boundReading re-bounds it (host-shaped, hex, boolean) before printing.
         [deployText, hostedText] = whoSeesAMerge(reach);
       } else {
-        deployText = deployCommit ? `live · ${deployCommit}` : 'live';
+        // No reading of the live build: say what is known (it merged), never "live".
+        deployText = `merged${deployCommit ? ` · ${deployCommit}` : ''} — not live until a published release carries it and the pin moves`;
       }
     } else if (stage === 'confirmed') {
       // task 1002541: this line used to be unconditional, driven by the STATUS
@@ -491,7 +497,7 @@ function buildCardModel(input = {}) {
 
     addFact('', changed);
     if (gradeText) addFact('grade', gradeText, { cls: gradeCls });
-    if (stage === 'shipped') addFact('live', deployCommit, { mono: true });
+    if (stage === 'shipped') addFact(liveConfirmed ? 'live' : 'merged', deployCommit, { mono: true });
     // The reason can be a full sentence — too long for a fact chip, so the chip
     // carries the alarm and the reason rides in its tooltip (the Deploy row above
     // always shows it in full).

package/modules/lifecycle/task-needs-gate.js

@@ -0,0 +1,70 @@
+// taskNeedsFailures — the claim-time half of "a task says what it needs" (task
+// 1004950, ADR 0395). The goalMembershipFailures / relevanceFrictionFailures
+// shape: one DB-read check called from all THREE claim surfaces in db-claims.js
+// (claimTask, claimTasksBatch, validateClaimBatch), so no surface can advertise
+// or take a claim another refuses.
+//
+// Only `server` refuses. `owner` work is claimable — by the owner, the one person
+// the feed shows it to; refusing it here would also refuse the owner's own agent
+// session, which is how the owner does that work. The feed is where `owner`
+// narrows (db-tasks.listClaimableTasks).
+//
+// `client` is the caller's open txn client (claimTask) or the pool itself (the
+// read-only dry run). Capabilities are resolved fresh, once per call, through the
+// doorway — never from the request body (ADR 0016). Returns [{ task_id, refusal }].
+
+'use strict';
+
+const api = require('../../src/module-api');
+
+async function taskNeedsFailures({ client, tasks, builderId, deps = {} }) {
+  const ids = (tasks || []).map((t) => Number(t.id)).filter((n) => Number.isFinite(n));
+  if (ids.length === 0) return [];
+  const { rows } = await client.query(
+    `SELECT id, needs FROM tasks WHERE id = ANY($1::bigint[]) AND cardinality(needs) > 0`,
+    [ids]
+  );
+  if (rows.length === 0) return [];
+  const needsApi = api.taskNeeds;
+  const capabilities = await (deps.resolveCapabilities || needsApi.resolveCapabilities)(builderId);
+  const failures = [];
+  for (const r of rows) {
+    const refused = needsApi.claimRefusalNeeds(r.needs, capabilities);
+    if (refused.length === 0) continue;
+    failures.push({
+      task_id: Number(r.id),
+      refusal: {
+        code: 'NEEDS_SERVER_ACCESS',
+        message: needsApi.SERVER_REFUSAL_MESSAGE,
+        needs: refused,
+      },
+    });
+  }
+  return failures;
+}
+
+// --- The two list filters (task 1004950), here so db-tasks.js stays under its cap.
+
+// needsFilterWhere — the board's ?needs= filter: one need, or 'none' for work that
+// needs nothing beyond the build loop. A filter on what a list shows, never a
+// narrowing of what anyone may read. Pushes its param; returns the clause or null.
+function needsFilterWhere(needs, alias, params) {
+  const col = alias ? `${alias}.needs` : 'needs';
+  if (needs === 'none') return `cardinality(${col}) = 0`;
+  if (!needs) return null;
+  params.push(needs); // @> so tasks_needs_idx (core_285) serves it
+  return `${col} @> ARRAY[$${params.length}]::text[]`;
+}
+
+// capabilityFeedWhere — the RECOMMEND rule (ADR 0395): a task's needs must be a
+// subset of the viewer's capabilities, resolved fresh. The autonomous/parallel
+// runner is an agent working alone, so it never holds `owner` whoever it runs as —
+// an agent cannot make the owner's decision. Pushes its param; returns the clause.
+async function capabilityFeedWhere(builderId, fit, alias, params, deps = {}) {
+  const capabilities = await (deps.resolveCapabilities || api.taskNeeds.resolveCapabilities)(builderId);
+  const unattended = fit === 'autonomous' || fit === 'parallel';
+  params.push(unattended ? capabilities.filter((c) => c !== 'owner') : capabilities);
+  return api.taskNeeds.feedNeedsClause(alias, `$${params.length}`);
+}
+
+module.exports = { taskNeedsFailures, needsFilterWhere, capabilityFeedWhere };

package/modules/market-watch/CLAUDE.md

@@ -0,0 +1,15 @@
+# @bongos/core — installed platform dependency (not your project's CLAUDE.md)
+
+This file is a placeholder shipped inside the **@bongos/core** package. The core's own
+internal agent notes are intentionally omitted from the published artifact so they cannot
+load into your instance's context.
+
+**It does not govern this repository.** Your own root `CLAUDE.md`, your `.claude/`
+directory, and the live Bongos database are the source of truth for how work happens here
+and who may do what.
+
+You are seeing this only because an agent opened a file under `node_modules/@bongos/core/`.
+Nothing in here needs to be read to use the platform — run `bongos help` for commands.
+
+_To work ON the platform core itself, use the standalone @bongos/core source repository,
+not this vendored copy._