@bongos/core 1.19.918 → 1.19.919

package/modules/lifecycle/removal-proposals.js

@@ -0,0 +1,259 @@
+'use strict';
+
+// modules/lifecycle/removal-proposals.js — THE ANSWER to "was this removed?"
+// (task 1004095 / BV2.R16, goal 1000095; ADR 0313 + ADR 0319).
+//
+// WHAT CAME BEFORE. A ship that deletes files an earlier SHIPPED task put there
+// files a question: the `removal-proposed-on-ship` cascade (task 1004090) creates
+// one task at `backlog` naming the affected work. That is deliberately a QUESTION
+// and not a verdict — refactors, renames and file moves all look like deletions to
+// a diff, so a derived-only signal would dim the sky continuously (ADR 0313, spec
+// decision 13). Nothing in the system could answer it. This file is the answer.
+//
+// THE TWO ANSWERS MUST BE DISTINGUISHABLE, AND THAT IS THE WHOLE POINT. Answering
+// either way leaves nothing to build, so either way the proposal task ends
+// `abandoned`. If the status were the only record, "yes, that work is gone" and
+// "no, that was a refactor" would be the same row — and brightness (BV2.R20), the
+// live share of a descent, would have no way to tell the star it must dim from the
+// one it must not. So the verdict is written to `lifecycle_removal_verdicts`
+// (migration lifecycle_009) and the status change is what takes the answered
+// question out of the queues. Both in ONE transaction: a verdict with no closed
+// task would be re-answerable, and a closed task with no verdict is the exact
+// erasure this file exists to prevent.
+//
+// WHAT IS NOT HERE: the list of tasks whose work was removed. The cascade files
+// one task per rule per ship with no field for a target (ADR 0242 forbids widening
+// the runner to fan out), so that list travels as PROSE in the proposal's body —
+// the owner's decision of 2026-09-20, recorded in cascade.js:removalProposalBody.
+// This file does not parse that prose and must not start: a body is written for a
+// person to read, and a reader that silently depends on its line shape breaks the
+// day somebody improves the wording. What brightness gets from here is the
+// verdict and `ship_task_id`, both structured.
+//
+// ROT IS INHERITED, NOT REBUILT. An unanswered proposal is a `backlog` task, which
+// is a rottable status (../rot.js TASK_ROTTABLE_STATUSES), so it enters the
+// existing rot feed on the project's normal clock with no code here at all — spec
+// decision 14, and the reason that decision had no competing option. Answering it
+// moves it to `abandoned`, which is terminal and not rottable, so an answered
+// proposal leaves the feed by the same mechanism.
+//
+// MODULE BOUNDARY: reaches core only through the published doorway
+// `../../src/module-api`; `./cascade` is an intra-module sibling.
+
+const api = require('../../src/module-api');
+const { CASCADE_SOURCE, REMOVAL_RULE_KEY, cascadeSourceRef } = require('./cascade');
+
+const { pool } = api;
+
+// The two answers, as an ALLOW-LIST. Mirrors the CHECK in lifecycle_009 — and a
+// deny-list here ("anything that is not 'dismissed' confirms") would admit every
+// value added to the vocabulary later, with the admitted one being the answer that
+// moves money. Exported so the route and the tests read the same set.
+const VERDICTS = Object.freeze(['confirmed', 'dismissed']);
+
+// The `source_ref` prefix every removal proposal carries, BUILT from the same
+// function that writes it rather than typed out. `cascadeSourceRef(key, id)`
+// returns `cascade-<key>-<id>`, so calling it with an empty id yields exactly the
+// prefix, and a change to either half of that format reaches this read instead of
+// quietly making it match nothing. The trailing separator is part of the prefix,
+// which is what stops `…-on-ship-12` from matching proposal `…-on-ship-1234`.
+//
+// The SQL below matches it with `starts_with`, never `LIKE $2 || '%'`. A rule key
+// is free to contain an underscore, and an underscore is a LIKE wildcard — so the
+// LIKE form would silently widen the match the day somebody names a rule
+// `removal_proposed`, and widening a read that decides what may be answered is
+// not a bug that announces itself.
+const PROPOSAL_SOURCE_REF_PREFIX = cascadeSourceRef(REMOVAL_RULE_KEY, '');
+
+// shipTaskIdFromSourceRef — the ship a proposal is about, recovered from its ref.
+// Pure. Returns a positive integer, or null when the ref is not a removal
+// proposal's or its tail is not a plain id. Null is a legal outcome and is stored
+// as such: a malformed ref must not make a proposal unanswerable, because the
+// verdict is the record that matters and the ship id is a convenience for the
+// reader that comes next.
+function shipTaskIdFromSourceRef(sourceRef) {
+  if (typeof sourceRef !== 'string' || !sourceRef.startsWith(PROPOSAL_SOURCE_REF_PREFIX)) return null;
+  const tail = sourceRef.slice(PROPOSAL_SOURCE_REF_PREFIX.length);
+  if (!/^\d+$/.test(tail)) return null;
+  const n = Number(tail);
+  return Number.isSafeInteger(n) && n > 0 ? n : null;
+}
+
+const MAX_PROPOSAL_ROWS = 50;
+
+// listPending — the removal proposals nobody has answered yet, oldest first.
+//
+// OLDEST FIRST, unlike the nod queue's newest-first: a proposal that has waited is
+// the one about to rot, and a queue that buries it under today's is a queue whose
+// tail nobody ever sees.
+//
+// "Unanswered" is TWO facts and both are required. A proposal with no verdict row
+// is unanswered; a proposal still at `backlog` has not been closed some other way
+// (killed off the rot feed, say). Reading only the verdict table would keep
+// offering an answer for a task somebody already abandoned by hand, and reading
+// only the status would re-offer one this route has already answered if the two
+// ever drift.
+async function listPending({ limit = 20 } = {}, deps = {}) {
+  const db = deps.pool || pool;
+  const cap = Math.max(1, Math.min(MAX_PROPOSAL_ROWS, Number(limit) || 20));
+  const { rows } = await db.query(
+    `SELECT t.id::text        AS proposal_task_id,
+            t.title           AS title,
+            t.description     AS description,
+            t.source_ref      AS source_ref,
+            t.goal_id::text   AS goal_id,
+            g.title           AS goal_title,
+            t.created_at      AS filed_at
+       FROM tasks t
+       LEFT JOIN goals g ON g.id = t.goal_id
+      WHERE t.source = $1
+        AND starts_with(t.source_ref, $2)
+        AND t.status = 'backlog'
+        AND NOT EXISTS (SELECT 1 FROM lifecycle_removal_verdicts v WHERE v.proposal_task_id = t.id)
+      ORDER BY t.created_at ASC, t.id ASC
+      LIMIT $3`,
+    [CASCADE_SOURCE, PROPOSAL_SOURCE_REF_PREFIX, cap]
+  );
+  return rows.map((r) => ({ ...r, ship_task_id: shipTaskIdFromSourceRef(r.source_ref) }));
+}
+
+// countPending — the same population as a number, for the slice's count pill. Its
+// own query rather than `rows.length`, because the list is capped and a pill that
+// silently reported the cap would under-state a backlog exactly when it mattered.
+async function countPending(deps = {}) {
+  const db = deps.pool || pool;
+  const { rows } = await db.query(
+    `SELECT count(*)::int AS n
+       FROM tasks t
+      WHERE t.source = $1
+        AND starts_with(t.source_ref, $2)
+        AND t.status = 'backlog'
+        AND NOT EXISTS (SELECT 1 FROM lifecycle_removal_verdicts v WHERE v.proposal_task_id = t.id)`,
+    [CASCADE_SOURCE, PROPOSAL_SOURCE_REF_PREFIX]
+  );
+  return (rows[0] && rows[0].n) || 0;
+}
+
+// The one-line trace left on the closed task, so the ledger reads honestly to
+// somebody who never opens the verdict table. Exported and pinned by test: it is
+// the only place the two answers are put into prose, and it must never become the
+// thing a reader PARSES — the verdict row is the record; this is the courtesy.
+function closureSummary(verdict, note) {
+  const head = verdict === 'confirmed'
+    ? 'Removal confirmed — the work named above is gone.'
+    : 'Removal dismissed — the deletion was not a removal of that work.';
+  const tail = typeof note === 'string' && note.trim() ? ` ${note.trim()}` : '';
+  return `${head}${tail}`;
+}
+
+// recordVerdict — answer ONE proposal: write the verdict and close the question,
+// in a single transaction.
+//
+// EVERY REFUSAL IS A NAMED CODE, never a silent no-op, because each of them is a
+// different thing for the caller to say:
+//   NOT_FOUND          — no such task.
+//   NOT_A_PROPOSAL     — a real task that is not a removal proposal. Answering it
+//                        would write a verdict about work nobody proposed removing.
+//   ALREADY_DECIDED    — a verdict exists. NOT an upsert and not an idempotent
+//                        200: overwriting would destroy the record that a person
+//                        answered differently, and the PK in lifecycle_009 refuses
+//                        it at the schema too. The existing verdict rides out on
+//                        the error so the caller can say what it was.
+//   PROPOSAL_CLOSED    — the task is no longer at `backlog` (killed off the rot
+//                        feed, promoted, claimed). The question is gone; a verdict
+//                        on it would answer something that is not being asked.
+//   BAD_VERDICT        — not one of VERDICTS.
+//
+// The row is locked FOR UPDATE before any of the row-scoped checks, so two people
+// pressing Confirm and Dismiss at the same moment cannot both read "undecided" and
+// both write. The second one loses on ALREADY_DECIDED rather than overwriting.
+//
+// #538 test seam: a caller-supplied pool is honoured ONLY under NODE_ENV==='test',
+// the abandonTask / confirmTask convention, so a test can drive the transaction
+// with a SQL-aware fake and production callers cannot reach it.
+async function recordVerdict({ proposalTaskId, verdict, note = null, builderId = null }, deps = {}) {
+  if (!VERDICTS.includes(verdict)) {
+    throw Object.assign(new Error(`verdict must be one of ${VERDICTS.join(', ')}`), { code: 'BAD_VERDICT' });
+  }
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const client = await activePool.connect();
+  try {
+    await client.query('BEGIN');
+
+    const { rows: taskRows } = await client.query(
+      `SELECT id::text AS id, title, status, source, source_ref FROM tasks WHERE id = $1 FOR UPDATE`,
+      [proposalTaskId]
+    );
+    if (taskRows.length === 0) {
+      throw Object.assign(new Error('task not found'), { code: 'NOT_FOUND' });
+    }
+    const task = taskRows[0];
+    const shipTaskId = shipTaskIdFromSourceRef(task.source_ref);
+    if (task.source !== CASCADE_SOURCE
+        || typeof task.source_ref !== 'string'
+        || !task.source_ref.startsWith(PROPOSAL_SOURCE_REF_PREFIX)) {
+      throw Object.assign(new Error(`task ${proposalTaskId} is not a removal proposal`), { code: 'NOT_A_PROPOSAL' });
+    }
+
+    const { rows: existing } = await client.query(
+      `SELECT verdict, decided_by::text AS decided_by, decided_at
+         FROM lifecycle_removal_verdicts WHERE proposal_task_id = $1`,
+      [proposalTaskId]
+    );
+    if (existing.length > 0) {
+      throw Object.assign(new Error(`proposal ${proposalTaskId} was already ${existing[0].verdict}`), {
+        code: 'ALREADY_DECIDED',
+        existing: existing[0],
+      });
+    }
+    if (task.status !== 'backlog') {
+      throw Object.assign(new Error(`proposal ${proposalTaskId} is '${task.status}', not an open question`), {
+        code: 'PROPOSAL_CLOSED',
+        status: task.status,
+      });
+    }
+
+    const { rows: written } = await client.query(
+      `INSERT INTO lifecycle_removal_verdicts
+         (proposal_task_id, ship_task_id, verdict, decided_by, note)
+       VALUES ($1, $2, $3, $4, NULLIF($5, ''))
+       RETURNING proposal_task_id::text AS proposal_task_id,
+                 ship_task_id::text     AS ship_task_id,
+                 verdict, decided_by::text AS decided_by, decided_at, note`,
+      [proposalTaskId, shipTaskId, verdict, builderId, typeof note === 'string' ? note.slice(0, 2000).trim() : '']
+    );
+
+    // The question is answered, so it is no longer work: 'abandoned' is the
+    // ledger's one spelling of "finished with the project, not delivered"
+    // (../task-status.js TERMINAL_STATUSES). ADR 0313 rejected a `removed` status
+    // for the SHIPPED work; this is the proposal's own row, not that work's, and a
+    // confirmed removal still leaves `shipped` terminal and every credit paid.
+    await client.query(
+      `UPDATE tasks
+          SET status = 'abandoned',
+              value_summary = COALESCE(value_summary, $2),
+              updated_at = now()
+        WHERE id = $1`,
+      [proposalTaskId, closureSummary(verdict, note)]
+    );
+
+    await client.query('COMMIT');
+    return { ...written[0], proposal_title: task.title, ship_task_id: shipTaskId == null ? null : String(shipTaskId) };
+  } catch (err) {
+    await client.query('ROLLBACK').catch(() => {});
+    throw err;
+  } finally {
+    client.release();
+  }
+}
+
+module.exports = {
+  VERDICTS,
+  MAX_PROPOSAL_ROWS,
+  PROPOSAL_SOURCE_REF_PREFIX,
+  shipTaskIdFromSourceRef,
+  closureSummary,
+  listPending,
+  countPending,
+  recordVerdict,
+};

package/modules/lifecycle/routes/removal-proposals.js

@@ -0,0 +1,140 @@
+'use strict';
+
+// modules/lifecycle/routes/removal-proposals.js — the doorway for answering a
+// removal proposal (task 1004095 / BV2.R16, goal 1000095; ADR 0313 + ADR 0319).
+//
+// TWO ROUTES AND NO NEW PERMISSION. Confirming a removal sits at the same floor as
+// the nod — Metic+ via the EXISTING `task.promote` atom (spec decision 15) — which
+// is the precedent the nod slice set in this same card (task 1003066 reused
+// POST /tasks/:id/promote rather than minting an endpoint). The read carries the
+// same atom as the write, so a caller who can SEE the queue can act on it: the two
+// gates agree by construction instead of by coincidence.
+//
+// WHY A NEW ROUTE AT ALL, when the nod reused one. There is no existing route that
+// MEANS "that work is genuinely gone". /tasks/:id/abandon would close the question
+// without recording which answer was given, which is the one thing this feature
+// exists to produce. So: the permission is reused, the verb is not.
+//
+// WHY /removal-proposals AND NOT /tasks/removal-proposals. Express matches in
+// registration order and the `tasks` route file — which declares `/tasks/:id` — is
+// mounted first by the manifest. A literal single segment under /tasks declared in
+// a later file is unreachable: it would arrive as /tasks/:id with id='removal-
+// proposals' and 400 on parseId. The same trap modules/ideas/routes/inbox.js
+// documents for /inbox/awaiting-nod, avoided by not sharing the prefix at all;
+// /override-requests in tasks.js is the existing precedent for a top-level noun.
+//
+// The route is only the doorway; ../removal-proposals.js owns the SQL and the
+// transaction. Keep it that way — this file must never grow a query.
+//
+// MODULE BOUNDARY: reaches core only through the published doorway
+// `../../../src/module-api`; `../removal-proposals` is an intra-module sibling.
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const proposals = require('../removal-proposals');
+
+const log = api.logger('lifecycle');
+
+// The floor: `task.promote` is Metic+ and is the atom the nod already carries,
+// which is what makes 'the same floor as the nod' a fact about the gate rather
+// than a claim in a comment.
+//
+// WRITTEN AS A LITERAL AT EACH GATE, not lifted into a const, and that is not an
+// oversight: the route-rank auditor (src/bongos/route-rank-check.js) reads the
+// atom out of the middleware list with a regex and classifies an unresolvable
+// gate as 'unknown' — which FAILS CLOSED and hard-fails CI for a write route.
+// A gate a machine cannot read is a gate nobody can audit.
+
+module.exports = function buildRemovalProposalsRouter() {
+  const router = express.Router();
+
+  // GET /removal-proposals — the removal questions nobody has answered yet.
+  //
+  // rank: metic+archon (task.promote). No client-side rank gate is needed or wanted in the
+  // hall: a non-triager's fetch 403s and the slice renders nothing. One gate, on
+  // the server, beats a client check that can disagree with it.
+  router.get('/removal-proposals', api.requireBuilder, api.requirePermission('task.promote'), async (req, res) => {
+    try {
+      const { limit } = api.parsePagination(req, { defaultLimit: 20, maxLimit: proposals.MAX_PROPOSAL_ROWS });
+      const [pending, count] = await Promise.all([
+        proposals.listPending({ limit }),
+        proposals.countPending(),
+      ]);
+      // A queue read is a "what is still open" question; a cached one is wrong the
+      // moment somebody answers a row. Same posture as GET /inbox/rotting.
+      res.set('Cache-Control', 'no-store');
+      res.json({ pending, count });
+    } catch (err) {
+      log.error(`GET /removal-proposals: ${err && err.message}`);
+      res.fail('removal_proposals_read_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // POST /removal-proposals/:id/decide — confirm or dismiss ONE proposal.
+  //
+  // ONE ROUTE WITH AN ENUM rather than /confirm and /dismiss, because the two
+  // answers are the same act with opposite content and splitting them would invite
+  // the two halves to drift in what they close, what they record and what they
+  // refuse. The enum is validated against an allow-list in the domain layer and by
+  // the CHECK in lifecycle_009 — neither admits a value the other does not.
+  //
+  // rank: metic+archon (task.promote), the same atom as the read above.
+  router.post('/removal-proposals/:id/decide', api.requireBuilder, api.requirePermission('task.promote'), async (req, res) => {
+    // The enum is read from the domain's own allow-list, never re-typed here, so
+    // the request gate and the CHECK in lifecycle_009 cannot disagree about what a
+    // verdict is. The domain re-checks it too — it is callable without this route
+    // — and that second check is pinned by its own test rather than through here,
+    // because a branch only reachable past this gate would be covered in name only.
+    if (api.validateOrRespond(req, res, {
+      verdict: { type: 'string', required: true, enum: proposals.VERDICTS },
+      note: { type: 'string', maxLength: 2000 },
+    })) return;
+    const id = api.parseId(req, res, { code: 'bad_task_id', positiveInt: true });
+    if (id === null) return;
+    try {
+      const decided = await proposals.recordVerdict({
+        proposalTaskId: id,
+        verdict: req.body.verdict,
+        note: typeof req.body.note === 'string' ? req.body.note : null,
+        builderId: Number(req.builder.id),
+      });
+      res.json({ ok: true, ...decided });
+    } catch (err) {
+      // Each refusal keeps its own code and status: a caller that cannot tell
+      // "already answered" from "not a proposal" cannot say anything useful to the
+      // person who pressed the button.
+      if (err.code === 'BAD_VERDICT') {
+        return res.fail('bad_verdict', {
+          status: 400,
+          message: `verdict must be one of ${proposals.VERDICTS.join(', ')}`,
+          details: { allowed: proposals.VERDICTS },
+        });
+      }
+      if (err.code === 'NOT_FOUND') return res.fail('task_not_found', 404);
+      if (err.code === 'NOT_A_PROPOSAL') {
+        return res.fail('not_a_removal_proposal', {
+          status: 409,
+          message: `task ${id} was not filed by the removal cascade — there is no removal question on it to answer`,
+        });
+      }
+      if (err.code === 'ALREADY_DECIDED') {
+        return res.fail('removal_already_decided', {
+          status: 409,
+          message: err.message,
+          details: { existing: err.existing || null },
+        });
+      }
+      if (err.code === 'PROPOSAL_CLOSED') {
+        return res.fail('removal_proposal_closed', {
+          status: 409,
+          message: err.message,
+          details: { status: err.status || null },
+        });
+      }
+      log.error(`POST /removal-proposals/:id/decide: ${err && err.message}`);
+      res.fail('removal_verdict_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  return router;
+};

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.918",
+  "version": "1.19.919",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.918",
+      "version": "1.19.919",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.918",
+  "version": "1.19.919",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/hall-preview/refresh-fixtures.js

@@ -31,6 +31,12 @@ const SNAPSHOTS = [
   ['leaderboard', 'leaderboard'],
   ['inbox', 'inbox', trimList('ideas', 25)],
   ['inbox/awaiting-nod?limit=20', 'inbox__awaiting-nod', trimList('awaiting', 25)],
+  // The attention card's removal-proposal slice (task 1004095). Snapshotted like
+  // the nod queue beside it — and, like it, the LIVE answer is usually empty, so
+  // the checked-in fixture is hand-written rows rather than whatever this run
+  // happened to catch. A slice that only ever renders its empty state cannot be
+  // looked at, which is this harness's whole job.
+  ['removal-proposals', 'removal-proposals', trimList('pending', 25)],
   ['goals', 'goals'],
   ['goals/inbox', 'goals__inbox'],
   // goal details: a handful of REAL ids (exact-match fixtures) + goal 25

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.918'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.919'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/blockers_hall.mjs

@@ -57,8 +57,22 @@ test('the blocker row carries .ginbox__item, so the card\'s count-pill and visib
   assert.match(GOAL_INBOX_SRC, /function blockerRowHtml[\s\S]*?class="ginbox__item"/);
 });
 
-test('the mount() boot sequence actually calls loadBlockers()', () => {
-  assert.match(GOAL_INBOX_SRC, /loadNodQueue\(\);\s*\n\s*loadBlockers\(\);\s*\n\s*loadRot\(\);/);
+test('the mount() boot sequence actually calls loadBlockers(), in its place in the order', () => {
+  // WHAT THIS PINS IS THE CALL AND ITS PLACE, not the three lines that used to
+  // sit adjacent. The original regex required loadBlockers() to be sandwiched
+  // between loadNodQueue() and loadRot() with nothing between them, so adding a
+  // FOURTH slice to the card (task 1004095's removal proposals) redded a test
+  // whose real invariant — the blockers feed is booted, after the nod and before
+  // rot — still held exactly. A slice is expected to be added here; the ordering
+  // rule the card's own comments state is what must not change.
+  const boot = /host\.addEventListener\('click', onClick\);([\s\S]*?)window\.OTBProfileNudge/.exec(GOAL_INBOX_SRC);
+  assert.ok(boot, 'the mount() boot block must be findable');
+  const at = (name) => boot[1].indexOf(`${name}();`);
+  assert.ok(at('loadBlockers') !== -1, 'mount() must actually call loadBlockers()');
+  assert.ok(at('loadNodQueue') !== -1 && at('loadNodQueue') < at('loadBlockers'),
+    'the nod queue boots before blockers');
+  assert.ok(at('loadRot') !== -1 && at('loadBlockers') < at('loadRot'),
+    'blockers boot before rot — rot is the standing question that sits last');
 });
 
 // ---- the full queue page (blockers.html + blockers.js) ---------------------