@bongos/core 1.20.4 → 1.20.6

package/modules/lifecycle/done-when.js

@@ -31,6 +31,20 @@ const { executorFor } = require('./db-executor.js');
 // here creates no cycle (db-versions.js requires THIS file, which is why the
 // rule could not live beside closeVersion).
 const { autoCloseVersionsForGoals } = require('./version-autoclose.js');
+// task 1004392 — the UAT state derivation. Pure and dependency-free, so no cycle.
+const { uatState, UAT_STATES } = require('./criterion-uat.js');
+
+// The two UAT columns every criterion read carries, as correlated subqueries on
+// the done_when_criteria row named by `alias`: the kind of its newest sign-off (null =
+// none) and whether it is marked backend-only. Declared once so the /status
+// rollup, the goal page and the review queue read the same two facts.
+function uatReadColumnsSql(alias) {
+  return `(SELECT u.kind FROM lifecycle_criterion_uats u
+                  WHERE u.criterion_id = ${alias}.id
+                  ORDER BY u.created_at DESC, u.id DESC LIMIT 1) AS uat_kind,
+                EXISTS (SELECT 1 FROM lifecycle_criterion_backend_only b
+                         WHERE b.criterion_id = ${alias}.id) AS backend_only`;
+}
 
 // isPendingReview — the ONE derivation of the "met — pending review" auto-flag
 // (ADR 0086 §6 / BV1.R63): a criterion with >=1 linked task, every one shipped,
@@ -137,7 +151,8 @@ async function listPendingReviewCriteria({ versionId = null } = {}, deps = {}) {
   const { rows } = await activePool.query(
     `WITH pending AS (
        SELECT c.id, c.version_id, c.criterion_id, c.criterion_md, c.goal_id, c.sort_order,
-              count(tc.task_id)::int AS task_total
+              count(tc.task_id)::int AS task_total,
+              count(*) FILTER (WHERE t.status = 'shipped')::int AS shipped_total
          FROM done_when_criteria c
          JOIN task_criteria tc ON tc.criterion_id = c.id
          JOIN tasks t          ON t.id = tc.task_id
@@ -152,7 +167,8 @@ async function listPendingReviewCriteria({ versionId = null } = {}, deps = {}) {
         GROUP BY goal_id
      )
      SELECT p.id, p.version_id, p.criterion_id, p.criterion_md, p.goal_id,
-            p.sort_order, p.task_total,
+            p.sort_order, p.task_total, p.shipped_total,
+            ${uatReadColumnsSql('p')},
             g.title  AS goal_title,
             g.status AS goal_status,
             COALESCE(gu.unsatisfied = 1, false) AS is_last_in_goal
@@ -163,7 +179,16 @@ async function listPendingReviewCriteria({ versionId = null } = {}, deps = {}) {
       ORDER BY p.version_id, p.sort_order, p.id`,
     [versionId]
   );
-  return rows;
+  // task 1004392: every row carries its UAT state. The queue holds two kinds of
+  // row now — AWAITING UAT (delivered, waiting for a sign-off: /goal-uat) and the
+  // all-abandoned residue (nothing delivered: /goal-review decides it).
+  return rows.map((r) => {
+    const { uat_kind: latestKind, ...row } = r;
+    const uat_state = uatState({
+      satisfied: false, linked: r.task_total, unshipped: 0, shipped: r.shipped_total, latestKind,
+    });
+    return { ...row, backend_only: r.backend_only === true, uat_state, awaiting_uat: uat_state === UAT_STATES.AWAITING_UAT };
+  });
 }
 
 // Roll up every criterion for a version together with the tasks that gate it
@@ -197,12 +222,14 @@ async function criterionProgress(versionId) {
   const [{ rows }, { rows: unattr }, goalRows] = await Promise.all([
     pool.query(
       `WITH ranked AS (
-         SELECT id, version_id, criterion_id, criterion_md, satisfied, goal_id,
-                ROW_NUMBER() OVER (ORDER BY sort_order, criterion_id) AS cnum
-           FROM done_when_criteria
-          WHERE version_id = $1
+         SELECT d.id, d.version_id, d.criterion_id, d.criterion_md, d.satisfied, d.goal_id,
+                ROW_NUMBER() OVER (ORDER BY d.sort_order, d.criterion_id) AS cnum,
+                ${uatReadColumnsSql('d')}
+           FROM done_when_criteria d
+          WHERE d.version_id = $1
        )
        SELECT r.cnum, r.id, r.criterion_id, r.criterion_md, r.satisfied, r.goal_id,
+              r.uat_kind, r.backend_only,
               t.id AS task_id, t.title AS task_title, t.status AS task_status
          FROM ranked r
          LEFT JOIN task_criteria tc ON tc.criterion_id = r.id
@@ -275,6 +302,8 @@ function buildCriterionProgress(versionId, rows, unattributedCount = 0, goalRows
         criterion_md: row.criterion_md,
         satisfied: row.satisfied,
         goal_id: row.goal_id ?? null,
+        backend_only: row.backend_only === true,
+        uat_kind: row.uat_kind ?? null,
         tasks: [],
       };
       byCrit.set(row.id, c);
@@ -300,7 +329,14 @@ function buildCriterionProgress(versionId, rows, unattributedCount = 0, goalRows
     const pending_review = isPendingReview({
       satisfied: c.satisfied, linked: c.tasks.length, unshipped: remaining.length,
     });
-    return { ...c, counts: { ...counts, shipped, remaining: remaining.length }, remaining, pending_review };
+    // task 1004392: the UAT state (Awaiting UAT once the Code check passes).
+    // NARROWER than pending_review on purpose — an all-abandoned criterion is
+    // flagged for a person but is not awaiting a UAT, since nothing was delivered.
+    const { uat_kind: uatKind, ...rest } = c;
+    const uat_state = uatState({
+      satisfied: c.satisfied, linked: c.tasks.length, unshipped: remaining.length, shipped, latestKind: uatKind,
+    });
+    return { ...rest, counts: { ...counts, shipped, remaining: remaining.length }, remaining, pending_review, uat_state, awaiting_uat: uat_state === UAT_STATES.AWAITING_UAT };
   });
 
   // Version → Goals → Criteria (ADR 0086 §2). A version is "done" when it HAS
@@ -331,7 +367,10 @@ function buildCriterionProgress(versionId, rows, unattributedCount = 0, goalRows
 // fulfilled the criterion (UI improvement, not required by the gate).
 //
 // Returns the updated row, or null if no row matched.
-async function markCriterion(criterionId, satisfiedByTaskId = null) {
+// deps.client (task 1004392): the override route writes its override row and
+// this flip in ONE transaction, so an override can never be recorded without
+// the criterion it overrode actually closing.
+async function markCriterion(criterionId, satisfiedByTaskId = null, deps = {}) {
   const id = Number(criterionId);
   if (!Number.isFinite(id)) return null;
   const taskId =
@@ -341,7 +380,7 @@ async function markCriterion(criterionId, satisfiedByTaskId = null) {
   if (taskId != null && !Number.isFinite(taskId)) {
     throw new Error('markCriterion: satisfiedByTaskId must be numeric');
   }
-  const { rows } = await pool.query(
+  const { rows } = await executorFor(deps, pool).query(
     `UPDATE done_when_criteria
         SET satisfied             = true,
             satisfied_by_task_id  = $2,
@@ -381,10 +420,10 @@ async function unmarkCriterion(criterionId) {
 // -------------------------------------------------------------------------
 
 // autoSatisfyShippedCriteria — flip every criterion whose gating set is fully
-// DELIVERED to satisfied=true, then cascade any goal whose criteria are now all
-// satisfied to `achieved`. This retires the manual /goal-review confirm step as
-// the ONLY way a criterion closes (owner request 2026-07-05): the review queue
-// becomes a place to look, not a gate to pass.
+// DELIVERED and carries a current UAT sign-off to satisfied=true, then cascade
+// any goal whose criteria are now all satisfied to `achieved`. (Until task
+// 1004392 delivery alone closed it — owner request 2026-07-05, ADR 0183; the
+// owner reversed that on 2026-09-29, see the UAT GATE note below.)
 //
 // `exec` is a pg client OR the pool — the caller decides. That is the whole
 // design: shipTask passes its OPEN TRANSACTION CLIENT so the criterion flip and
@@ -418,24 +457,46 @@ async function unmarkCriterion(criterionId) {
 //
 // Returns { criteria: [...], goals: [...] } — the rows actually changed, so a
 // caller can log or broadcast exactly what closed (empty arrays on a no-op).
-async function autoSatisfyShippedCriteria(exec, { taskId = null } = {}) {
+//
+// ⚠ THE UAT GATE (task 1004392, ADR 0351 — supersedes ADR 0183's "shipped is
+// enough"). Delivery is now only the CODE check. A criterion closes here only
+// when it ALSO carries a CURRENT sign-off in lifecycle_criterion_uats: a `uat`
+// (recorded on the live site) or a `backend_signoff`, created no earlier than the
+// newest linked ship. The recency clause is the point, not a detail: a sign-off
+// watched the work as it stood; a task linked and shipped after it is work
+// nobody checked, so that criterion waits for a fresh UAT. An `override` row is
+// not a candidate here because the override route satisfies directly.
+//
+// So the ship hook and the reconciler sweep keep running and keep their goal and
+// version cascade, and simply find nothing to close until someone signs off. The
+// third scope, { criterionId }, is the sign-off route's own call, inside its
+// transaction, so the criterion (and its goal) close in the same commit as the
+// sign-off that closed them.
+async function autoSatisfyShippedCriteria(exec, { taskId = null, criterionId = null } = {}) {
   const scopedTaskId = taskId == null ? null : Number(taskId);
   if (scopedTaskId != null && !Number.isFinite(scopedTaskId)) {
     throw new Error('autoSatisfyShippedCriteria: taskId must be numeric');
   }
+  const scopedCriterionId = criterionId == null ? null : Number(criterionId);
+  if (scopedCriterionId != null && !Number.isFinite(scopedCriterionId)) {
+    throw new Error('autoSatisfyShippedCriteria: criterionId must be numeric');
+  }
   const { rows: criteria } = await exec.query(
     `WITH candidate AS (
        SELECT c.id,
               -- Attribute the close to a task that actually shipped. In scoped
               -- mode that is the shipping task; unscoped, the highest shipped id
               -- (deterministic, and the most recent contributor).
-              max(tc.task_id) FILTER (WHERE t.status = 'shipped') AS by_task
+              max(tc.task_id) FILTER (WHERE t.status = 'shipped') AS by_task,
+              -- The newest linked ship: a sign-off older than this is stale.
+              max(t.shipped_at) FILTER (WHERE t.status = 'shipped') AS last_ship
          FROM done_when_criteria c
          JOIN task_criteria tc ON tc.criterion_id = c.id
          JOIN tasks t          ON t.id = tc.task_id
         WHERE c.satisfied = false
           AND ($1::bigint IS NULL OR c.id IN (
                 SELECT criterion_id FROM task_criteria WHERE task_id = $1::bigint))
+          AND ($2::bigint IS NULL OR c.id = $2::bigint)
         GROUP BY c.id
        HAVING count(*) FILTER (WHERE ${nonTerminalSql()}) = 0
           AND count(*) FILTER (WHERE t.status = 'shipped') >= 1
@@ -446,9 +507,13 @@ async function autoSatisfyShippedCriteria(exec, { taskId = null } = {}) {
             checked_at           = now()
        FROM candidate
       WHERE c.id = candidate.id
+        AND EXISTS (SELECT 1 FROM lifecycle_criterion_uats u
+                     WHERE u.criterion_id = candidate.id
+                       AND u.kind IN ('uat', 'backend_signoff')
+                       AND u.created_at >= COALESCE(candidate.last_ship, '-infinity'::timestamptz))
      RETURNING c.id, c.version_id, c.criterion_id, c.criterion_md, c.goal_id,
                c.satisfied_by_task_id`,
-    [scopedTaskId]
+    [scopedTaskId, scopedCriterionId]
   );
   if (criteria.length === 0) return { criteria: [], goals: [] };
 
@@ -558,6 +623,8 @@ module.exports = {
   buildCriterionProgress,
   buildGoals,
   isPendingReview,
+  uatState,
+  uatReadColumnsSql,
   autoSatisfyShippedCriteria,
   describeAutoClose,
   closeCompletedWorkForShip,

package/modules/lifecycle/migrations/lifecycle_015_criterion_uat.sql

@@ -0,0 +1,73 @@
+-- lifecycle_015_criterion_uat.sql — a criterion closes on a UAT, not on its
+-- linked tasks shipping (task 1004392, goal 1000089; ADR 0351).
+--
+-- WHY. ADR 0183 let a criterion close itself the moment every task linked to it
+-- shipped. Nothing read the criterion's words: link any tasks, ship them, and it
+-- closed. wa7-government did exactly that on six Board Room navigation tasks
+-- while the thing it describes (configurable ranks, recommended governments by
+-- project type and size) was not on the live site at all. Shipped code is now
+-- only the FIRST of three checks; the criterion reads "Awaiting UAT" until a
+-- person who did not ship the work signs it off on the live site.
+--
+-- TWO MODULE TABLES, and neither alters a core table. ADR 0083 lets a module
+-- migration create only its own lifecycle_-namespaced tables, so the
+-- backend-only flag is a row beside the criterion (present = backend-only)
+-- rather than a column on done_when_criteria. Both reference the core table the
+-- way lifecycle_010 references tasks.
+--
+-- THE SIGN-OFF IS APPEND-ONLY. A row is never updated or deleted by the app: it
+-- is the record that a named person checked the criterion's words against the
+-- live site on a given day. Whether it still COUNTS is derived at read time (a
+-- sign-off older than the newest linked ship is stale, because the work it
+-- watched has since changed), never by rewriting the row.
+--
+-- PORTABLE and replay-safe: IF NOT EXISTS throughout, no instance data. Already
+-- satisfied criteria are untouched (the owner's 2026-09-29 decision: they stay
+-- closed, and read as "closed before UAT" because they carry no row here).
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS lifecycle_criterion_uats (
+  id               bigserial PRIMARY KEY,
+  criterion_id     bigint      NOT NULL REFERENCES done_when_criteria(id) ON DELETE CASCADE,
+
+  -- What kind of sign-off this is:
+  --   uat              a person performed the criterion on the live site and a
+  --                    recording of it is stored (recording_file is required)
+  --   backend_signoff  the criterion is backend-only, so there is nothing to
+  --                    record; a non-shipper still signs that it is done and live
+  --   override         POST /done-when/:id/satisfy, the escape hatch, which now
+  --                    has to say why (note is required) and is recorded as such
+  kind             text        NOT NULL CHECK (kind IN ('uat', 'backend_signoff', 'override')),
+  signed_off_by    bigint      NOT NULL REFERENCES builders(id),
+
+  -- The stored recording's server-minted name (uat-<criterion>-<16 hex>.<ext>),
+  -- served by GET /criterion-uats/recordings/:name. Never a user-supplied path.
+  recording_file   text        CHECK (recording_file IS NULL OR recording_file ~ '^uat-[0-9]{1,12}-[0-9a-f]{16}\.(mp4|webm)$'),
+
+  -- How "it is live" was established:
+  --   deploy_reading  the instance read it (every linked shipped task runs here)
+  --   attested        the instance cannot read it, so the signer said so
+  --   not_checked     an override, which checks nothing
+  live_basis       text        NOT NULL CHECK (live_basis IN ('deploy_reading', 'attested', 'not_checked')),
+  note             text        CHECK (note IS NULL OR length(note) <= 2000),
+  created_at       timestamptz NOT NULL DEFAULT now(),
+
+  CHECK (kind <> 'uat' OR recording_file IS NOT NULL),
+  CHECK (kind <> 'override' OR (note IS NOT NULL AND length(btrim(note)) > 0))
+);
+
+CREATE INDEX IF NOT EXISTS lifecycle_criterion_uats_criterion
+  ON lifecycle_criterion_uats (criterion_id, created_at DESC);
+
+-- A criterion marked backend-only: it has no screen, so it cannot be checked by
+-- a recording. Set while the criterion is still open (the route refuses it once
+-- the criterion is awaiting UAT or closed), so the person closing it cannot
+-- choose to skip the recording at close time.
+CREATE TABLE IF NOT EXISTS lifecycle_criterion_backend_only (
+  criterion_id  bigint      PRIMARY KEY REFERENCES done_when_criteria(id) ON DELETE CASCADE,
+  marked_by     bigint      NOT NULL REFERENCES builders(id),
+  marked_at     timestamptz NOT NULL DEFAULT now()
+);
+
+COMMIT;

package/modules/lifecycle/module.json

@@ -14,6 +14,7 @@
       "claims",
       "versions",
       "done-when",
+      "criterion-uat",
       "goals",
       "dependencies",
       "gate-approvals",

package/modules/lifecycle/routes/criterion-uat.js

@@ -0,0 +1,169 @@
+// modules/lifecycle/routes/criterion-uat.js — the UAT a criterion must pass
+// before it closes (task 1004392, goal 1000089; ADR 0351). The rules are pure in
+// ../criterion-uat.js; the transaction is ../criterion-uat-db.js.
+//
+//   POST /done-when/:criterionId/uat/recording  upload the recording (raw mp4/webm body)
+//   POST /done-when/:criterionId/uat            sign it off (a UAT, or a backend sign-off)
+//   GET  /done-when/:criterionId/uat            its three checks + every sign-off
+//   PUT  /done-when/:criterionId/backend-only   mark it backend-only while it is still open
+//   GET  /criterion-uats/recordings/:name       play a stored recording
+//
+// WHO. Signing off and uploading reuse `criterion.review` — the permission the
+// criterion review queue already runs on (Metic+), because a UAT sign-off IS that
+// review now. The in-handler wall on top of it is the one that matters: nobody who
+// shipped the linked work may sign it off (the project owner excepted). Marking
+// backend-only is a criterion-AUTHORING act (the owner: "set when the criterion is
+// written"), so it takes `criterion.create` plus the same per-goal authoring wall
+// as creating or editing a criterion (authorizeCriterionCreate, ADR 0154).
+//
+// Reading the UAT picture and playing a recording need only a signed-in builder:
+// a criterion and its goal are readable by any builder (ADR 0112 privacy is
+// join-gating, not read-hiding), and the recording is evidence ABOUT that criterion.
+
+const express = require('express');
+const fs = require('node:fs/promises');
+const api = require('../../../src/module-api');
+const db = require('../db');
+const doneWhen = require('../done-when');
+const uat = require('../criterion-uat');
+const uatDb = require('../criterion-uat-db');
+const { authorizeCriterionCreate } = require('./done-when');
+const { validateOrRespond, parseId, asyncHandler } = api;
+const log = api.logger('lifecycle');
+
+// The recording arrives as a RAW body, not base64 JSON: at the 100 MB cap a
+// base64 JSON body would be ~134 MB held twice in memory. One byte over the cap
+// so screenRecording, not the body parser, gives the human-worded refusal.
+const recordingBody = express.raw({
+  type: Object.keys(uat.EXT_BY_TYPE),
+  limit: uat.MAX_RECORDING_BYTES + 1,
+});
+
+// A refusal's extra facts (the open tasks, the tasks not live yet) ride the
+// envelope's `details` — res.fail drops any other key, and a refusal that says
+// "some work is not live" without naming it leaves the signer guessing.
+function sendRefusal(res, refusal) {
+  const { code, status, message, ...detail } = refusal;
+  return res.fail(code, { status, message, ...(Object.keys(detail).length ? { details: detail } : {}) });
+}
+
+module.exports = function buildCriterionUatRouter() {
+  const router = express.Router();
+
+  // rank: metic+archon — perm criterion.review: evidence for a UAT sign-off.
+  router.post('/done-when/:criterionId/uat/recording', api.requireBuilder, api.requirePermission('criterion.review'), (req, res, next) => {
+    recordingBody(req, res, (err) => {
+      if (err && err.type === 'entity.too.large') {
+        return res.fail('too_big', { status: 413, message: uat.screenMessage('too_big') });
+      }
+      return next(err);
+    });
+  }, asyncHandler('POST /done-when/:criterionId/uat/recording', async (req, res) => {
+    const id = parseId(req, res, { param: 'criterionId', code: 'bad_criterion_id' });
+    if (id === null) return;
+    if (!(await doneWhen.getCriterion(id))) return res.fail('criterion_not_found', 404);
+    const buf = Buffer.isBuffer(req.body) ? req.body : null;
+    const stored = await uat.persistRecording(buf, { criterionId: id, contentType: req.headers['content-type'] });
+    if (!stored.ok) return res.fail(stored.reason, { status: 400, message: uat.screenMessage(stored.reason) });
+    res.status(201).json({ ok: true, recording: stored.file, bytes: stored.bytes });
+  }, { errorCode: 'uat_recording_failed' }));
+
+  // rank: metic+archon — perm criterion.review; the non-shipper wall is in-handler.
+  router.post('/done-when/:criterionId/uat', api.requireBuilder, api.requirePermission('criterion.review'), asyncHandler('POST /done-when/:criterionId/uat', async (req, res) => {
+    if (validateOrRespond(req, res, {
+      kind: { required: true, type: 'string', maxLength: 32 },
+      recording: { type: 'string', maxLength: 80 },
+      live_attested: { type: 'boolean' },
+      note: { type: 'string', maxLength: uat.MAX_NOTE_LENGTH },
+    })) return;
+    const id = parseId(req, res, { param: 'criterionId', code: 'bad_criterion_id' });
+    if (id === null) return;
+    const recording = req.body.recording || null;
+    if (recording && !uat.resolveSafe(recording)) return res.fail('bad_recording', 400);
+    if (recording) {
+      try { await fs.access(uat.resolveSafe(recording)); } catch {
+        return res.fail('recording_not_found', { status: 400, message: 'That recording is not on the server. Upload it again.' });
+      }
+    }
+    const out = await uatDb.signOff({
+      criterionId: id,
+      kind: req.body.kind,
+      signerId: req.builder.id,
+      recording,
+      liveAttested: req.body.live_attested === true,
+      note: req.body.note ?? null,
+    });
+    if (!out.ok) return sendRefusal(res, out.refusal);
+    const closed = out.closed || {};
+    log.info({ criterionId: id, kind: req.body.kind, signer: req.builder.id }, 'criterion UAT signed off');
+    res.status(201).json({
+      ok: true,
+      signoff: out.signoff,
+      criterion_closed: (closed.criteria || []).some((c) => Number(c.id) === id),
+      achieved_goals: (closed.goals || []).map((g) => g.id),
+      closed_versions: (closed.versionsClosed || []).map((v) => (v && v.id) || v),
+    });
+  }, { errorCode: 'uat_signoff_failed' }));
+
+  // rank: any-builder — a criterion and its goal are readable by any builder.
+  router.get('/done-when/:criterionId/uat', api.requireBuilder, asyncHandler('GET /done-when/:criterionId/uat', async (req, res) => {
+    const id = parseId(req, res, { param: 'criterionId', code: 'bad_criterion_id' });
+    if (id === null) return;
+    const view = await uatDb.uatView(id);
+    if (!view) return res.fail('criterion_not_found', 404);
+    res.json(view);
+  }, { errorCode: 'uat_read_failed' }));
+
+  // rank: metic+archon — perm criterion.create + the per-goal authoring wall (ADR 0154).
+  router.put('/done-when/:criterionId/backend-only', api.requireBuilder, api.requirePermission('criterion.create'), asyncHandler('PUT /done-when/:criterionId/backend-only', async (req, res) => {
+    if (validateOrRespond(req, res, { backend_only: { required: true, type: 'boolean' } })) return;
+    const id = parseId(req, res, { param: 'criterionId', code: 'bad_criterion_id' });
+    if (id === null) return;
+    const out = await uatDb.setBackendOnly({
+      criterionId: id,
+      builderId: req.builder.id,
+      backendOnly: req.body.backend_only,
+      // The authoring wall, resolved exactly as PATCH /done-when/:id resolves it,
+      // on the transaction client so the decision and the write see one snapshot.
+      authorize: async (client, criterion) => {
+        const version = await db.getVersion(criterion.version_id, { client });
+        const goal = criterion.goal_id != null ? await db.getGoal(criterion.goal_id, { client }) : null;
+        const actorMembership = (goal && req.builder.rank !== 'archon')
+          ? await db.getGoalMember({ goalId: goal.id, builderId: req.builder.id }, { client })
+          : null;
+        const decision = authorizeCriterionCreate({ goal, version, actorId: req.builder.id, actorRank: req.builder.rank, actorMembership });
+        return decision.ok ? null : { code: decision.body.error, status: decision.status, message: decision.body.message };
+      },
+    });
+    if (!out.ok) return sendRefusal(res, out.refusal);
+    res.json({ ok: true, criterion_id: id, backend_only: out.backend_only });
+  }, { errorCode: 'backend_only_failed' }));
+
+  // rank: any-builder — evidence about a criterion any builder can read. The
+  // audience is the criterion's: any signed-in builder of THIS instance (criteria
+  // are readable by every builder, ADR 0112). One instance is one project, so
+  // this never crosses a tenant; the server-minted name is not the access control.
+  router.get('/criterion-uats/recordings/:name', api.requireBuilder, async (req, res) => {
+    const filePath = uat.resolveSafe(req.params.name);
+    if (!filePath) return res.fail('bad_name', 400);
+    try {
+      await fs.access(filePath);
+    } catch {
+      return res.fail('not_found', 404);
+    }
+    res.setHeader('X-Content-Type-Options', 'nosniff');
+    res.setHeader('Content-Disposition', 'inline');
+    res.setHeader('Content-Security-Policy', "default-src 'none'; sandbox");
+    res.setHeader('Cache-Control', 'private, max-age=86400');
+    // sendFile honours Range requests, so a browser can seek a long recording.
+    res.type(uat.contentTypeForName(req.params.name));
+    res.sendFile(filePath, (err) => {
+      if (err && !res.headersSent) {
+        log.error({ name: req.params.name, err: err.message }, 'uat recording read failed');
+        res.fail('read_failed', 500);
+      }
+    });
+  });
+
+  return router;
+};

package/modules/lifecycle/routes/done-when.js

@@ -21,6 +21,8 @@ const db = require('../db');
 const { isGoalOwnerOrManager } = require('../goal-authz');
 // task 1003102 — prose correction + the satisfied-criterion refusal decision.
 const goalEdits = require('../goal-edits.js');
+// task 1004392 — /satisfy is the override now and records itself as one.
+const uatDb = require('../criterion-uat-db.js');
 const { validateOrRespond, parseId, asyncHandler, LIMITS } = api;
 
 // authorizeCriterionCreate — the ORDERED, FAIL-CLOSED decision for a non-Archon
@@ -212,9 +214,19 @@ module.exports = function buildDoneWhenRouter() {
   // pinned in route-rank-check.MODULE_EXPECTED_RANKS.lifecycle so a further
   // downgrade is caught.
   // rank: metic+archon — criterion confirmation + goal auto-achieve (the closing loop).
+  //
+  // ⚠ SINCE TASK 1004392 (ADR 0351) THIS IS THE OVERRIDE, NOT THE CLOSE. A
+  // criterion closes on a UAT sign-off (POST /done-when/:id/uat); flipping it here
+  // skips the UAT, which is exactly how a criterion gets closed without anyone
+  // checking its words. So it now REQUIRES `override_reason`, writes an `override`
+  // sign-off row carrying it, and the criterion then reads "Satisfied (override)"
+  // everywhere — never as a UAT. The escape hatch stays (an all-abandoned
+  // criterion that was met another way still needs one); it is just no longer
+  // silent.
   router.post('/done-when/:criterionId/satisfy', auth.requireBuilder, auth.requirePermission('criterion.satisfy'), asyncHandler('POST /done-when/:criterionId/satisfy', async (req, res) => {
     if (validateOrRespond(req, res, {
       satisfied_by_task_id: { type: 'integer', min: 1 },
+      override_reason: { type: 'string', maxLength: 2000 },
     })) return;
     const id = parseId(req, res, { param: 'criterionId', code: 'bad_criterion_id' });
     if (id === null) return;
@@ -222,8 +234,20 @@ module.exports = function buildDoneWhenRouter() {
     // 200-with-null-body (acceptance criterion #5).
     const existing = await doneWhen.getCriterion(id);
     if (!existing) return res.fail('criterion_not_found', 404);
+    const reason = String(req.body?.override_reason || '').trim();
+    if (!reason) {
+      return res.fail('override_reason_required', {
+        status: 400,
+        message: 'A criterion now closes on a UAT: a person who did not ship the work tests it on the live site and signs it off (POST /done-when/:id/uat, or /goal-uat). Closing it here skips that, so say why in override_reason.',
+      });
+    }
     const taskId = req.body?.satisfied_by_task_id ?? null;
-    const updated = await doneWhen.markCriterion(id, taskId);
+    // ONE transaction: an override row with no flip behind it would claim a
+    // close that never happened, so the two commit together or not at all.
+    const updated = await api.withTx(async (client) => {
+      await uatDb.recordOverride(client, { criterionId: id, signerId: req.builder.id, reason });
+      return doneWhen.markCriterion(id, taskId, { client });
+    }, { pool: api.pool });
     // Auto-achieve: confirming a goal's last criterion flips it open→achieved.
     // A criterion with no goal (goal_id NULL) completes no goal.
     let goalResult = { achieved: false, goal: null };

package/modules/npm-release/module.json

@@ -22,6 +22,8 @@
       "task-where"
     ]
   },
-  "provides": [],
+  "provides": [
+    "deploy.taskWhere"
+  ],
   "consumes": []
 }

package/modules/npm-release/routes/task-where.js

@@ -17,13 +17,30 @@
 
 const express = require('express');
 const api = require('../../../src/module-api');
-const { readTaskWhere } = require('../work');
+const { readTaskWhere, readTasksWhere } = require('../work');
 
 const log = api.logger('npm-release');
 
+// THE `deploy.taskWhere` PORT (task 1004392, ADR 0351). A criterion's UAT has a
+// LIVE check, and on this hall the answer is exactly this reading: a linked task
+// whose stage is live_unreleased or released is running here. The lifecycle
+// module resolves it OPTIONALLY (it may not require a sibling module, ADR 0083),
+// so an instance without this module simply has no reading and the UAT signer
+// attests instead. Registered from the route factory — the one boot hook that
+// also runs when a test rebuilds the router — and hasProvider-guarded.
+const DEPLOY_PORT = 'deploy.taskWhere';
+
 module.exports = function buildNpmReleaseTaskWhereRouter({ read = readTaskWhere } = {}) {
   const router = express.Router();
 
+  if (!api.hasProvider(DEPLOY_PORT)) {
+    api.registerProvider(DEPLOY_PORT, {
+      readTaskWhere: (id) => read({ pool: api.pool, id }),
+      // The batch form reads the registry and notes ONCE for every id.
+      readTasksWhere: (ids) => readTasksWhere({ pool: api.pool, ids }),
+    });
+  }
+
   router.get(
     '/npm-release/task/:id',
     api.requireBuilder,

package/modules/npm-release/work.js

@@ -293,13 +293,44 @@ async function readTaskWhere({ pool, id, pkg = configuredPackage(), live, instal
     [taskId],
   );
   if (!rows.length) return null;
-  const r = rows[0];
-  const task = { id: String(r.id), status: r.status, summary: r.value_summary || null, at: r.at instanceof Date ? r.at.toISOString() : r.at };
-  const base = { task_id: task.id, package: pkg, status: task.status };
-  if (!['completed', 'confirmed', 'shipped'].includes(task.status)) return { ...base, stage: null };
+  const task = taskFromRow(rows[0]);
+  if (!['completed', 'confirmed', 'shipped'].includes(task.status)) return { task_id: task.id, package: pkg, status: task.status, stage: null };
+  return whereFrom(task, pkg, await readVersions({ pkg, live, installedNotes, get, now, store }));
+}
 
-  const { liveVersion, registry, versions, notesError, coversTo, published, released } =
-    await readVersions({ pkg, live, installedNotes, get, now, store });
+function taskFromRow(r) {
+  return { id: String(r.id), status: r.status, summary: r.value_summary || null, at: r.at instanceof Date ? r.at.toISOString() : r.at };
+}
+
+/**
+ * readTasksWhere — the same reading for MANY tasks, with the versions read ONCE (task
+ * 1004392). A criterion's UAT Live check asks where every linked shipped task is; calling
+ * readTaskWhere per task re-read the registry and the release notes for each one, though
+ * that half of the reading does not depend on the task at all. Returns { [taskId]: where }
+ * for the ids that exist; an unknown id is simply absent.
+ */
+async function readTasksWhere({ pool, ids, pkg = configuredPackage(), live, installedNotes = readInstalledNotes, get, now, store } = {}) {
+  const clean = [...new Set((ids || []).map(String).filter((id) => /^\d{1,12}$/.test(id)))];
+  if (!clean.length) return {};
+  const { rows } = await pool.query(
+    `SELECT id, status, value_summary, COALESCE(shipped_at, updated_at) AS at FROM tasks WHERE id = ANY($1::bigint[])`,
+    [clean],
+  );
+  if (!rows.length) return {};
+  const reading = await readVersions({ pkg, live, installedNotes, get, now, store });
+  const out = {};
+  for (const r of rows) {
+    const task = taskFromRow(r);
+    out[task.id] = ['completed', 'confirmed', 'shipped'].includes(task.status)
+      ? whereFrom(task, pkg, reading)
+      : { task_id: task.id, package: pkg, status: task.status, stage: null };
+  }
+  return out;
+}
+
+// Place one task against a versions reading — the shared tail of both readers.
+function whereFrom(task, pkg, { liveVersion, registry, versions, notesError, coversTo, published, released }) {
+  const base = { task_id: task.id, package: pkg, status: task.status };
   const stages = placeTasks({ tasks: [task], versions, live: liveVersion, released, coveredAt: coversTo ? published[coversTo] || null : null });
   const stage = Object.keys(stages).find((k) => stages[k].length) || null;
   const row = stage ? stages[stage][0] : {};
@@ -316,4 +347,4 @@ async function readTaskWhere({ pool, id, pkg = configuredPackage(), live, instal
   };
 }
 
-module.exports = { readWork, readTaskWhere };
+module.exports = { readWork, readTaskWhere, readTasksWhere };

package/modules/specialities/routes/specialities.js

@@ -86,6 +86,13 @@ const port = {
   // which knows the craft of the claim in hand; this just reports them all.
   async describeActiveFor(builderId) {
     const rows = await db.listAdoptions(builderId);
+    // The enabled-skills line names only skills this instance still has. A
+    // failed skills read must not cost the builder their whole contract, so it
+    // degrades to "unknown" (offered-only filter) rather than throwing.
+    let installed = null;
+    if (rows.some((r) => r.active && Array.isArray(r.enabled_skills) && r.enabled_skills.length)) {
+      try { installed = installedSkills(); } catch { installed = null; }
+    }
     const out = [];
     for (const row of rows) {
       if (!row.active) continue;
@@ -95,7 +102,7 @@ const port = {
       const full = await db.getSpeciality(row.id);
       const selfAuthored = !!full && full.owner_kind === 'builder'
         && String(full.owner_builder_id) === String(builderId);
-      const described = S.describeForApi(row, { ...training, selfAuthored });
+      const described = S.describeForApi(row, { ...training, selfAuthored, installed });
       if (described) out.push({ ...described, discipline: row.discipline, name: row.name });
     }
     return out;