@bongos/core 1.20.4 → 1.20.6

package/.claude/skills/goal-uat/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: goal-uat
+description: >-
+  Test criteria awaiting UAT on the live site, then sign off. Metic+. Triggers: "/goal-uat", "what's awaiting UAT".
+---
+
+You are running the **goal-uat** session: the closing step of a goal. A criterion no longer closes because its linked tasks shipped ([ADR 0351](../../../docs/adr/0351-a-criterion-closes-on-a-uat.md), task 1004392). Once its work has shipped it reads **Awaiting UAT**, and it closes only when a person who did **not** ship that work does what the criterion describes **on the live site** and signs it off.
+
+This is the owner's rule because criteria were being closed by any tasks that happened to be linked to them, whether or not the thing the criterion describes was real. A UAT is the check against the criterion's **words**, not against the task list. Hold it to that.
+
+## Rank gate: Metic+ only
+
+Signing off rides `criterion.review` (Metic+); the server enforces it. Check first so a Xenos is not walked into a wall of 403s: `node scripts/gds/api.js GET /api/bongos/me` and read `builder.rank`. If it lowercases to `xenos` or `thetes`, stop and say: *"Signing off a UAT is a Metic+ step. Ask an Archon to promote you, or ask a Metic to run it."*
+
+## The three checks (what you are verifying)
+
+| Check | Passes when | Who decides |
+|---|---|---|
+| **Code** | every linked task is done and at least one shipped | automatic |
+| **Live** | the shipped work is running on the deployed site | read automatically where the site can tell; otherwise the signer confirms it |
+| **UAT** | a signed-in person performed the criterion on the live site; a recording is stored | the signer, who must not have shipped any linked task (the project owner excepted) |
+
+A criterion marked **backend-only** (set when it was written, visible on the criterion) has no screen to record, so it takes a recording-free **backend sign-off** instead. It still needs a non-shipper to sign it.
+
+## Step 1: the queue
+
+```
+node scripts/gds/uat.js --queue
+```
+
+(Add `--version <id>` to scope it.) If nothing is awaiting UAT, say so and stop. If the builder named a goal, keep only that goal's rows.
+
+## Step 2: one criterion at a time
+
+For each, run `node scripts/gds/uat.js <criterion-id>` and present, in plain words:
+
+- the criterion's text, in full;
+- its goal, and whether it is the goal's **last** open criterion (then signing it off achieves the goal);
+- the Live line (running, not yet, or "this site cannot tell");
+- whether it is backend-only.
+
+Then tell the tester exactly what to do **on the live site**, derived from the criterion's words: which page, what to click, what they should see. Write it as a short numbered script. If the criterion's words describe something the tester cannot find on the live site, that is the answer: **it is not met.** Say so and go to Step 4 (reject) rather than looking for a reading under which it passes.
+
+## Step 3: record and sign off
+
+The tester records their screen doing the script (any screen recorder that saves **mp4 or webm**, up to **100 MB**; Windows: Win+Alt+R with Xbox Game Bar, or the Snipping Tool's record button; macOS: Cmd+Shift+5). Then:
+
+```
+node scripts/gds/uat.js <criterion-id> --recording <path-to-file> --note "<one line: what was checked>"
+```
+
+For a backend-only criterion, after the tester has checked it by whatever means proves it (a log line, an API read, a test run against live):
+
+```
+node scripts/gds/uat.js <criterion-id> --backend-signoff --note "<how it was checked>"
+```
+
+Add `--live-attested` only when the server says this site cannot tell whether the work is live, and only if the tester really did it on the live site.
+
+**Refusals, in the words to give the builder:**
+
+| Refusal | Meaning |
+|---|---|
+| `signer_shipped_this_work` | they shipped linked work; someone else signs this one |
+| `work_not_live` | shipped but not deployed yet; sign off after the deploy |
+| `criterion_not_awaiting_uat` | linked work still open (or none linked, or all abandoned: that is `/goal-review`) |
+| `criterion_needs_recording` / `criterion_is_backend_only` | wrong kind of sign-off for this criterion |
+| `live_attestation_required` | confirm it was tested on the live site (`--live-attested`) |
+
+A sign-off on a goal's last open criterion reports the goal achieved; say so.
+
+## Step 4: when it is NOT met
+
+The shipped work does not do what the criterion says. Do not sign off. File the missing work as a task linked to the criterion (`POST /api/bongos/tasks`, then `POST /api/bongos/tasks/<id>/criteria` with `{"criterion_id": <criterion-id>}`) so the criterion drops back to Open until that ships. That is what happened to `wa7-government` (task 1004400).
+
+## What this skill does NOT do
+
+- It never uses `POST /done-when/:id/satisfy`. That is the **override** now: it requires a written `override_reason` and the criterion reads "Satisfied (override)" for good. Use it only when the owner asks, and never to get past a refusal above.
+- It never marks a criterion backend-only to avoid recording one. Backend-only is set while a criterion is still open (`uat.js <id> --backend-only on`), and the server refuses it once the criterion is awaiting UAT.
+- The all-abandoned and no-linked-task residue is `/goal-review`'s, not this skill's.
+
+## Summary to give at the end
+
+Criteria walked · signed off (ids) · goals achieved · rejected, with the follow-up task filed for each · left waiting (not live yet, or no tester available).

package/clients/bongos-client/README.md

@@ -5,7 +5,7 @@ A **generated**, zero-dependency typed client for the Bongos API — produced fr
 by hand; it regenerates when the spec changes, so it can never drift from the routes.
 
 - API version: **v1** (served at `/api/bongos/v1`)
-- 455 operations across 69 resource groups
+- 460 operations across 70 resource groups
 
 ## Use it from your project
 

package/clients/bongos-client/bongos-client.global.js

@@ -332,6 +332,10 @@ function createClient(opts = {}) {
       // POST /cost — rank: any-builder — POST /cost
       postCost: (args) => request("POST", "/cost", { hasBody: true }, args),
     },
+    "criterionUats": {
+      // GET /criterion-uats/recordings/{name} — rank: any-builder — GET /criterion-uats/recordings/:name
+      getCriterionUatsRecordingsName: (args) => request("GET", "/criterion-uats/recordings/{name}", { hasBody: false }, args),
+    },
     "dependencies": {
       // DELETE /dependencies — rank: archon — DELETE /dependencies
       deleteDependencies: (args) => request("DELETE", "/dependencies", { hasBody: false }, args),
@@ -349,8 +353,16 @@ function createClient(opts = {}) {
     "doneWhen": {
       // PATCH /done-when/{criterionId} — rank: metic+archon — PATCH /done-when/:criterionId
       patchDoneWhenCriterionId: (args) => request("PATCH", "/done-when/{criterionId}", { hasBody: true }, args),
+      // PUT /done-when/{criterionId}/backend-only — rank: metic+archon — PUT /done-when/:criterionId/backend-only
+      putDoneWhenCriterionIdBackendOnly: (args) => request("PUT", "/done-when/{criterionId}/backend-only", { hasBody: true }, args),
       // POST /done-when/{criterionId}/satisfy — rank: metic+archon — POST /done-when/:criterionId/satisfy
       postDoneWhenCriterionIdSatisfy: (args) => request("POST", "/done-when/{criterionId}/satisfy", { hasBody: true }, args),
+      // GET /done-when/{criterionId}/uat — rank: any-builder — GET /done-when/:criterionId/uat
+      getDoneWhenCriterionIdUat: (args) => request("GET", "/done-when/{criterionId}/uat", { hasBody: false }, args),
+      // POST /done-when/{criterionId}/uat — rank: metic+archon — POST /done-when/:criterionId/uat
+      postDoneWhenCriterionIdUat: (args) => request("POST", "/done-when/{criterionId}/uat", { hasBody: true }, args),
+      // POST /done-when/{criterionId}/uat/recording — rank: metic+archon — POST /done-when/:criterionId/uat/recording
+      postDoneWhenCriterionIdUatRecording: (args) => request("POST", "/done-when/{criterionId}/uat/recording", { hasBody: true }, args),
       // POST /done-when/{criterionId}/unsatisfy — rank: metic+archon — POST /done-when/:criterionId/unsatisfy
       postDoneWhenCriterionIdUnsatisfy: (args) => request("POST", "/done-when/{criterionId}/unsatisfy", { hasBody: true }, args),
       // GET /done-when/pending-review — rank: metic+archon — GET /done-when/pending-review

package/clients/bongos-client/index.cjs

@@ -331,6 +331,10 @@ function createClient(opts = {}) {
       // POST /cost — rank: any-builder — POST /cost
       postCost: (args) => request("POST", "/cost", { hasBody: true }, args),
     },
+    "criterionUats": {
+      // GET /criterion-uats/recordings/{name} — rank: any-builder — GET /criterion-uats/recordings/:name
+      getCriterionUatsRecordingsName: (args) => request("GET", "/criterion-uats/recordings/{name}", { hasBody: false }, args),
+    },
     "dependencies": {
       // DELETE /dependencies — rank: archon — DELETE /dependencies
       deleteDependencies: (args) => request("DELETE", "/dependencies", { hasBody: false }, args),
@@ -348,8 +352,16 @@ function createClient(opts = {}) {
     "doneWhen": {
       // PATCH /done-when/{criterionId} — rank: metic+archon — PATCH /done-when/:criterionId
       patchDoneWhenCriterionId: (args) => request("PATCH", "/done-when/{criterionId}", { hasBody: true }, args),
+      // PUT /done-when/{criterionId}/backend-only — rank: metic+archon — PUT /done-when/:criterionId/backend-only
+      putDoneWhenCriterionIdBackendOnly: (args) => request("PUT", "/done-when/{criterionId}/backend-only", { hasBody: true }, args),
       // POST /done-when/{criterionId}/satisfy — rank: metic+archon — POST /done-when/:criterionId/satisfy
       postDoneWhenCriterionIdSatisfy: (args) => request("POST", "/done-when/{criterionId}/satisfy", { hasBody: true }, args),
+      // GET /done-when/{criterionId}/uat — rank: any-builder — GET /done-when/:criterionId/uat
+      getDoneWhenCriterionIdUat: (args) => request("GET", "/done-when/{criterionId}/uat", { hasBody: false }, args),
+      // POST /done-when/{criterionId}/uat — rank: metic+archon — POST /done-when/:criterionId/uat
+      postDoneWhenCriterionIdUat: (args) => request("POST", "/done-when/{criterionId}/uat", { hasBody: true }, args),
+      // POST /done-when/{criterionId}/uat/recording — rank: metic+archon — POST /done-when/:criterionId/uat/recording
+      postDoneWhenCriterionIdUatRecording: (args) => request("POST", "/done-when/{criterionId}/uat/recording", { hasBody: true }, args),
       // POST /done-when/{criterionId}/unsatisfy — rank: metic+archon — POST /done-when/:criterionId/unsatisfy
       postDoneWhenCriterionIdUnsatisfy: (args) => request("POST", "/done-when/{criterionId}/unsatisfy", { hasBody: true }, args),
       // GET /done-when/pending-review — rank: metic+archon — GET /done-when/pending-review

package/clients/bongos-client/index.d.ts

@@ -286,7 +286,10 @@ export interface PostCostRequest { task_id?: number; amount_usd: number; categor
 export interface PostCostResponse { skipped?: boolean; reason?: unknown; id?: unknown; recorded_at?: unknown }
 export interface PostDependenciesResponse { ok: boolean; dependency: unknown }
 export interface PostDiscordChannelsReconcileResponse { ok: boolean; applied: unknown; failed: unknown; total: unknown; warnings: unknown }
-export interface PostDoneWhenCriterionIdSatisfyRequest { satisfied_by_task_id?: number }
+export interface PostDoneWhenCriterionIdSatisfyRequest { satisfied_by_task_id?: number; override_reason?: string }
+export interface PostDoneWhenCriterionIdUatRecordingResponse { ok: boolean; recording: unknown; bytes: unknown }
+export interface PostDoneWhenCriterionIdUatRequest { kind: string; recording?: string; live_attested?: boolean; note?: string }
+export interface PostDoneWhenCriterionIdUatResponse { ok: boolean; signoff: unknown; criterion_closed: unknown; achieved_goals: unknown; closed_versions: unknown }
 export interface PostDoneWhenCriterionIdUnsatisfyResponse { criterion: unknown }
 export interface PostGateApprovalsPrApproveResponse { ok: boolean; pr: unknown; already_clear?: boolean; message: unknown; head_sha?: unknown; status_set?: boolean; recheck?: unknown; held_for_artist?: unknown }
 export interface PostGithubRepoVisibilityRequest { repo: string; visibility: "public" | "private" }
@@ -480,6 +483,8 @@ export interface PostVersionsRequest { id: string; name: string; status?: string
 export interface PostVersionsResponse { version: unknown; goal: unknown; criteria: unknown }
 export interface PutCopyDeskPagesPageIdDraftRequest { reading_hash: string; lines: unknown[] }
 export interface PutCopyDeskPagesPageIdDraftResponse { ok: boolean; outcome: unknown; page_id: unknown; round: unknown; draft: unknown; counter: unknown }
+export interface PutDoneWhenCriterionIdBackendOnlyRequest { backend_only: boolean }
+export interface PutDoneWhenCriterionIdBackendOnlyResponse { ok: boolean; criterion_id: unknown; backend_only: unknown }
 export interface PutGovernmentRanksRankKeyPermissionsPermissionKeyResponse { ok: boolean; rank_key: unknown; permission_key: unknown; granted: unknown }
 export interface PutMingleOptInRequest { opted_in: boolean }
 export interface PutMingleOptInResponse { opted_in: unknown; updated_at: unknown }
@@ -752,6 +757,10 @@ export interface BongosClient {
     /** POST /cost — rank: any-builder */
     postCost(args: RequestArgs & { body: PostCostRequest }): Promise<PostCostResponse>;
   };
+  "criterionUats": {
+    /** GET /criterion-uats/recordings/{name} — rank: any-builder */
+    getCriterionUatsRecordingsName(args?: RequestArgs): Promise<ApiResponse>;
+  };
   "dependencies": {
     /** DELETE /dependencies — rank: archon */
     deleteDependencies(args?: RequestArgs): Promise<DeleteDependenciesResponse>;
@@ -769,8 +778,16 @@ export interface BongosClient {
   "doneWhen": {
     /** PATCH /done-when/{criterionId} — rank: metic+archon */
     patchDoneWhenCriterionId(args?: RequestArgs & { body?: PatchDoneWhenCriterionIdRequest }): Promise<PatchDoneWhenCriterionIdResponse>;
+    /** PUT /done-when/{criterionId}/backend-only — rank: metic+archon */
+    putDoneWhenCriterionIdBackendOnly(args: RequestArgs & { body: PutDoneWhenCriterionIdBackendOnlyRequest }): Promise<PutDoneWhenCriterionIdBackendOnlyResponse>;
     /** POST /done-when/{criterionId}/satisfy — rank: metic+archon */
     postDoneWhenCriterionIdSatisfy(args?: RequestArgs & { body?: PostDoneWhenCriterionIdSatisfyRequest }): Promise<ApiResponse>;
+    /** GET /done-when/{criterionId}/uat — rank: any-builder */
+    getDoneWhenCriterionIdUat(args?: RequestArgs): Promise<ApiResponse>;
+    /** POST /done-when/{criterionId}/uat — rank: metic+archon */
+    postDoneWhenCriterionIdUat(args: RequestArgs & { body: PostDoneWhenCriterionIdUatRequest }): Promise<PostDoneWhenCriterionIdUatResponse>;
+    /** POST /done-when/{criterionId}/uat/recording — rank: metic+archon */
+    postDoneWhenCriterionIdUatRecording(args?: RequestArgs): Promise<PostDoneWhenCriterionIdUatRecordingResponse>;
     /** POST /done-when/{criterionId}/unsatisfy — rank: metic+archon */
     postDoneWhenCriterionIdUnsatisfy(args?: RequestArgs): Promise<PostDoneWhenCriterionIdUnsatisfyResponse>;
     /** GET /done-when/pending-review — rank: metic+archon */

package/clients/bongos-client/index.mjs

@@ -328,6 +328,10 @@ export function createClient(opts = {}) {
       // POST /cost — rank: any-builder — POST /cost
       postCost: (args) => request("POST", "/cost", { hasBody: true }, args),
     },
+    "criterionUats": {
+      // GET /criterion-uats/recordings/{name} — rank: any-builder — GET /criterion-uats/recordings/:name
+      getCriterionUatsRecordingsName: (args) => request("GET", "/criterion-uats/recordings/{name}", { hasBody: false }, args),
+    },
     "dependencies": {
       // DELETE /dependencies — rank: archon — DELETE /dependencies
       deleteDependencies: (args) => request("DELETE", "/dependencies", { hasBody: false }, args),
@@ -345,8 +349,16 @@ export function createClient(opts = {}) {
     "doneWhen": {
       // PATCH /done-when/{criterionId} — rank: metic+archon — PATCH /done-when/:criterionId
       patchDoneWhenCriterionId: (args) => request("PATCH", "/done-when/{criterionId}", { hasBody: true }, args),
+      // PUT /done-when/{criterionId}/backend-only — rank: metic+archon — PUT /done-when/:criterionId/backend-only
+      putDoneWhenCriterionIdBackendOnly: (args) => request("PUT", "/done-when/{criterionId}/backend-only", { hasBody: true }, args),
       // POST /done-when/{criterionId}/satisfy — rank: metic+archon — POST /done-when/:criterionId/satisfy
       postDoneWhenCriterionIdSatisfy: (args) => request("POST", "/done-when/{criterionId}/satisfy", { hasBody: true }, args),
+      // GET /done-when/{criterionId}/uat — rank: any-builder — GET /done-when/:criterionId/uat
+      getDoneWhenCriterionIdUat: (args) => request("GET", "/done-when/{criterionId}/uat", { hasBody: false }, args),
+      // POST /done-when/{criterionId}/uat — rank: metic+archon — POST /done-when/:criterionId/uat
+      postDoneWhenCriterionIdUat: (args) => request("POST", "/done-when/{criterionId}/uat", { hasBody: true }, args),
+      // POST /done-when/{criterionId}/uat/recording — rank: metic+archon — POST /done-when/:criterionId/uat/recording
+      postDoneWhenCriterionIdUatRecording: (args) => request("POST", "/done-when/{criterionId}/uat/recording", { hasBody: true }, args),
       // POST /done-when/{criterionId}/unsatisfy — rank: metic+archon — POST /done-when/:criterionId/unsatisfy
       postDoneWhenCriterionIdUnsatisfy: (args) => request("POST", "/done-when/{criterionId}/unsatisfy", { hasBody: true }, args),
       // GET /done-when/pending-review — rank: metic+archon — GET /done-when/pending-review

package/docs/adr/0015-task-dependencies-and-auto-promotion.md

@@ -58,6 +58,8 @@ The function fires when `NEW.status='shipped' AND OLD.status<>'shipped'`. It sca
 
 `claimTasksBatch` does the same check per-task but treats batch-internal deps as "OK" (the batch is worked serially).
 
+**The batch caller owns the ordering (task 1004391).** "Worked serially" is a promise the caller makes, not one the system keeps. `claimTasksBatch` (now in [modules/lifecycle/db-claims.js](../../modules/lifecycle/db-claims.js), with its dry-run twin in the same file) only waives the claim-time check for a dependency that is claimed in the same batch; **nothing at ship time checks that the dependency shipped first**. Once both are claimed, a dependent can pass `completed`, `confirmed` and land on `main` before the task it depends on. Whoever claims a batch — a builder, `/builder-sequence`, the autonomous runner — must ship each in-batch dependency before its dependent. The owner chose to write this rule down rather than add a ship-time gate (which would change the protected ship pipeline); if dependents landing out of order ever causes real damage, the gate is the follow-up.
+
 ### API surface
 
 | Verb     | Path                                          | Body / returns                                           |

package/docs/adr/0183-criteria-close-themselves.md

@@ -1,6 +1,6 @@
 # ADR 0183 — A done-when criterion closes itself; the review queue becomes a place to look
 
-- **Status:** accepted
+- **Status:** superseded in part by [ADR 0351](0351-a-criterion-closes-on-a-uat.md) (2026-09-29): shipped linked tasks are now only the first of three checks, and a criterion closes on a UAT sign-off. The delivery guard below is kept.
 - **Date:** 2026-08-21
 - **Task:** 1002069 (owner request 2026-07-05, scope owner-confirmed)
 - **Supersedes part of:** [ADR 0086](0086-goal-scoped-work-hierarchy.md) §6 / BV1.R63 — the criterion auto-flag stays, but confirming it is no longer the only way a criterion closes.

package/docs/adr/0310-a-speciality-offers-skills-and-the-adopter-chooses-them.md

@@ -76,6 +76,6 @@ Deliberately separate tasks, because the middle one is where the ruling lives an
 
 1. **Schema + validation** — the offered set on the catalog, the enabled set on the adoption, `validateDraft`, the routes. Refuses a skill the instance does not have. *Built in task 1004072 (`skills` / `enabled_skills`, specialities_003, `modules/specialities/skills.js`).*
 2. **The walkthrough** — the adoption flow that presents each skill and takes a decision. The ruling's real deliverable. *Built in task 1004073 (`GET /specialities/:id/skills`, `skills.explainSkill`, the hall settings panel). The consequence above came true: skill descriptions are model-facing, so a SKILL.md may now carry optional people-facing `plain:` / `reach-for:` / `cost:` lines, and the walkthrough says so when it had to derive the words instead.*
-3. **Injection** — the enabled set reaches the session through the contract the Conductor already injects; a line naming the skills this builder leans on, per [ADR 0296](0296-a-role-speciality-is-data-over-three-existing-surfaces.md)'s pattern of using surfaces that exist.
+3. **Injection** — the enabled set reaches the session through the contract the Conductor already injects; a line naming the skills this builder leans on, per [ADR 0296](0296-a-role-speciality-is-data-over-three-existing-surfaces.md)'s pattern of using surfaces that exist. *Built in task 1004074: `describeForApi` appends one sentence naming the enabled skills — only those still offered and installed — after the provenance fence, since the list is the adopter's choice and not the author's prose. It says it is advice and not permission. Nothing enabled adds nothing. No new mechanism: the port, `GET /me` and the Conductor are unchanged in shape, and the Conductor's craft match scopes the line with the rest of the contract. Pinned end to end by `tests/speciality_session_skills.mjs`.*
 
 Nothing is built by this ADR. It is the decision task 1003978 asked to be made first.

package/docs/adr/0351-a-criterion-closes-on-a-uat.md

@@ -0,0 +1,73 @@
+# ADR 0351 — A criterion closes on a UAT, not on its linked tasks shipping
+
+- **Status:** accepted
+- **Date:** 2026-09-29
+- **Task:** [task 1004392](https://cloudbongos.com/builders#/task/1004392) (goal 1000089 — working area 3, Human project management); the hall half is [task 1004402](https://cloudbongos.com/builders#/task/1004402)
+- **Deciders:** the owner (Archon) decided every point below in chat on 2026-09-29, from options Claude laid out. Claude wrote the record.
+- **Supersedes:** [ADR 0183](0183-criteria-close-themselves.md)'s rule that a criterion whose linked tasks all shipped is satisfied. Its delivery guard (at least one task actually shipped) is kept, as the first of three checks.
+
+## Context
+
+ADR 0183 made a criterion close itself the moment every task linked to it shipped, because criteria waiting for a human confirm were leaving the board wrong. It fixed that, and it made a criterion something you could close without anyone reading it: link any tasks, ship them, done.
+
+It happened. The owner asked why working area 7 (goal 1000111) was blocked, and on the way the criterion `wa7-government` showed satisfied. Its text asks for fully customizable ranks and recommended governments for different project types and sizes. The six tasks that closed it were Board Room navigation work. On the live site there were zero custom ranks, the government recommendation read headcount only and named a charter the page itself marks "documented for later", and a board amendment ratified on 25 Aug had never taken effect. Every check the system ran said done.
+
+The owner's diagnosis: a criterion has to be achieved in the code **and** in what a person can actually do on the live site, and closing one is a bigger review step than a task shipping.
+
+## Decision
+
+### 1. Three checks, and only the first is automatic
+
+| Check | Passes when |
+|---|---|
+| **Code** | every linked task is terminal and at least one shipped (ADR 0183's delivery guard) |
+| **Live** | the shipped work is running on the deployed site |
+| **UAT** | a signed-in person performed the criterion on the live site, and a recording of it is stored |
+
+`autoSatisfyShippedCriteria` still runs from the ship transaction and the reconciler sweep, with its goal and version cascade, but a criterion is a candidate only when it also carries a **current** sign-off: a `uat` or `backend_signoff` row in `lifecycle_criterion_uats` created no earlier than the newest linked ship. Work linked and shipped after a sign-off is work nobody checked, so that criterion waits for a fresh UAT.
+
+### 2. "Awaiting UAT" is a state people can see
+
+A criterion whose Code check passes and has no current sign-off reads **Awaiting UAT**, so the board shows the baseline is met (the owner asked for this explicitly). The states, derived in one place (`modules/lifecycle/criterion-uat.js` `uatState`) and carried on every criterion read (`/status`, the goal page, the review queue): Open · Awaiting UAT · Satisfied (UAT) · Satisfied (backend sign-off) · Satisfied (override) · Closed before UAT.
+
+### 3. The signer cannot have shipped the work, and one step is the sign-off
+
+Whoever submits the recording is the sign-off; there is no second approver. The server refuses them if they shipped any linked task, with one exception, the **project owner**, so a solo project cannot deadlock on its own work. The permission is `criterion.review`, the review queue's own atom (Metic+), because the sign-off is that review now.
+
+### 4. The recording lives on the project's own server
+
+An mp4 or webm, up to 100 MB, uploaded as a raw body, screened by type and magic bytes, stored under a server-minted name outside the git tree, and served only to signed-in builders. No third-party service, no new monthly cost.
+
+### 5. Backend-only is decided when the criterion is written
+
+A criterion with no screen can be marked **backend-only**, and then takes a recording-free backend sign-off, still from a non-shipper. The flag is an authoring act (`criterion.create` plus the goal's authoring wall, ADR 0154) and the server refuses to change it once the criterion is Awaiting UAT or closed, so the person closing it cannot choose to skip the recording.
+
+### 6. Live is read where the site can tell, and attested where it cannot
+
+On the Bongos hall the `npm-release` module already places every task in a deploy stage; it now provides that as the `deploy.taskWhere` port, and a sign-off is refused while any linked shipped task is not running on the site. Most instances have no such reading, and a reading that fails is treated the same way: the signer confirms they tested it on the live site, and the row records `live_basis = 'attested'`. An outage never blocks a person; it only moves the claim to their word, which is recorded as such.
+
+### 7. Criteria already closed stay closed
+
+The owner chose not to reopen them: reopening every satisfied criterion would reopen finished goals across the project. They read "Closed before UAT" because they carry no sign-off row. `wa7-government` alone was reopened, by hand, with a task (1004400) linked to it so the sweep cannot close it again.
+
+### 8. The manual confirm becomes a recorded override
+
+`POST /done-when/:id/satisfy` survives as the escape hatch (a criterion met some other way still needs one) but requires `override_reason`, writes an `override` row, and the criterion reads "Satisfied (override)" permanently.
+
+### 9. The walk is a skill
+
+`/goal-uat` scripts the live-site test from the criterion's words, collects the recording and signs it off, through `scripts/gds/uat.js`. `/goal-review` keeps only the residue a UAT cannot test (all linked work abandoned, or none linked). The hall controls are task 1004402.
+
+## Consequences
+
+- From the release that carries this, no criterion closes without a person. Goals whose last criterion is Awaiting UAT wait for one. That is the intended cost; ADR 0183's worry was a board that lies, and a board that says "Awaiting UAT" is telling the truth.
+- The pile-up ADR 0183 was written against can come back as an Awaiting UAT backlog. `/goal-uat` and the hall controls exist to keep that queue fast to work; if it grows anyway, the fix is making UAT cheaper, not letting criteria close themselves again.
+- Between this piece and task 1004402 the hall's Confirm button no longer closes a criterion; it explains that criteria close on a UAT.
+
+## Alternatives rejected
+
+- **A human review of the task list instead of the live site.** That is what `/goal-review` was, and it checked the tasks, not the words.
+- **Two-person sign-off** (a recorder and a separate approver). Heavier, and the non-shipper rule already puts a second person on the work.
+- **A link to a recording on an outside service.** Links rot and leave the ledger; the owner chose the project's own server.
+- **Refusing the sign-off when the deploy reading fails.** That blocks a person on an outage; attestation is recorded as attestation.
+- **Reopening every satisfied criterion.** Rejected by the owner (decision 7).

package/docs/adr/README.md

@@ -59,6 +59,33 @@ When a later decision overrides an earlier one, **do not edit the old ADR**. Ins
 
 This keeps the decision history honest and traceable.
 
+## Citing an ADR, and the numbers two files share
+
+**Cite an ADR by its filename, not by its number alone.** Write a link — `[ADR 0195](0195-adr-numbers-are-checked-like-migration-numbers.md)` — or the bare filename. A number by itself is ambiguous for the 20 numbers below, and a reader (human or agent) given only "ADR 0024" has two documents to choose from and no way to know which was meant. No tool resolves an ADR by number: the harm is to whoever reads the prose.
+
+These 20 numbers are each shared by exactly two files. They are **accepted history, not a to-do**: they are not renumbered, because renaming a file breaks every existing citation to it, which is the harm this rule prevents. `scripts/gds/adr-namespace.js` (fitness Check 31, part of the required `unit` check; [ADR 0195](0195-adr-numbers-are-checked-like-migration-numbers.md)) freezes each pair by exact filename in `LEGACY_DUPLICATE_ADRS`, so a new collision, a third file on one of these numbers, or a rename of either half fails CI. The list may shrink and never grows. A new ADR takes its number from `node scripts/gds/next-number.js`.
+
+- **0008** — [`0008-family-based-tile-generation.md`](0008-family-based-tile-generation.md) · [`0008-google-chat-oauth-user-auth.md`](0008-google-chat-oauth-user-auth.md)
+- **0024** — [`0024-cloneable-repo-local-first-memory.md`](0024-cloneable-repo-local-first-memory.md) · [`0024-multi-agent-system-architecture.md`](0024-multi-agent-system-architecture.md)
+- **0025** — [`0025-offsite-backup-vendor-digitalocean-spaces.md`](0025-offsite-backup-vendor-digitalocean-spaces.md) · [`0025-structured-criterion-task-link.md`](0025-structured-criterion-task-link.md)
+- **0044** — [`0044-mediterranean-palette-replacement.md`](0044-mediterranean-palette-replacement.md) · [`0044-per-box-live-game-preview.md`](0044-per-box-live-game-preview.md)
+- **0057** — [`0057-container-cost-ledger.md`](0057-container-cost-ledger.md) · [`0057-discord-archon-approval-channels.md`](0057-discord-archon-approval-channels.md)
+- **0072** — [`0072-bongos-app-mac-signed-first-windows-deferred.md`](0072-bongos-app-mac-signed-first-windows-deferred.md) · [`0072-dev-box-code-staleness-visibility.md`](0072-dev-box-code-staleness-visibility.md)
+- **0073** — [`0073-builder-needs-signal-and-byok-gemini-key.md`](0073-builder-needs-signal-and-byok-gemini-key.md) · [`0073-secrets-scan-exclude-uri-detector.md`](0073-secrets-scan-exclude-uri-detector.md)
+- **0082** — [`0082-productized-key-storage-provisioning.md`](0082-productized-key-storage-provisioning.md) · [`0082-server-side-merge-conflict-auto-resolution.md`](0082-server-side-merge-conflict-auto-resolution.md)
+- **0087** — [`0087-bongos-app-architecture-and-handoff-contract.md`](0087-bongos-app-architecture-and-handoff-contract.md) · [`0087-compete-on-governance-not-tooling-cursor.md`](0087-compete-on-governance-not-tooling-cursor.md)
+- **0095** — [`0095-borrowed-memory-and-retrieval-concepts.md`](0095-borrowed-memory-and-retrieval-concepts.md) · [`0095-cross-agent-context-management.md`](0095-cross-agent-context-management.md)
+- **0097** — [`0097-one-active-claim-per-session-and-worktree-binding.md`](0097-one-active-claim-per-session-and-worktree-binding.md) · [`0097-retroactive-reward-backfill.md`](0097-retroactive-reward-backfill.md)
+- **0103** — [`0103-core-first-extraction-cloud-bongos-trunk.md`](0103-core-first-extraction-cloud-bongos-trunk.md) · [`0103-gdsv4-bongos-consolidation.md`](0103-gdsv4-bongos-consolidation.md)
+- **0144** — [`0144-devbox-rehome-onto-cloudbongos-plane.md`](0144-devbox-rehome-onto-cloudbongos-plane.md) · [`0144-federated-single-logout-backchannel.md`](0144-federated-single-logout-backchannel.md)
+- **0145** — [`0145-devbox-app-branding-driven-module.md`](0145-devbox-app-branding-driven-module.md) · [`0145-free-hosted-project-tier-isolation-and-domain-separation.md`](0145-free-hosted-project-tier-isolation-and-domain-separation.md)
+- **0152** — [`0152-landing-gate-served-by-the-core-app.md`](0152-landing-gate-served-by-the-core-app.md) · [`0152-metic-task-abandonment.md`](0152-metic-task-abandonment.md)
+- **0167** — [`0167-gate-trust-link-agpl-default.md`](0167-gate-trust-link-agpl-default.md) · [`0167-module-catalog-source-vs-provenance.md`](0167-module-catalog-source-vs-provenance.md)
+- **0172** — [`0172-editable-rank-roles-substrate-axis.md`](0172-editable-rank-roles-substrate-axis.md) · [`0172-per-craft-compensation-ideator-credit-lane.md`](0172-per-craft-compensation-ideator-credit-lane.md)
+- **0184** — [`0184-a-task-visual-inherits-its-summary-audience.md`](0184-a-task-visual-inherits-its-summary-audience.md) · [`0184-ship-requires-an-assurance.md`](0184-ship-requires-an-assurance.md)
+- **0187** — [`0187-collab-four-decisions.md`](0187-collab-four-decisions.md) · [`0187-oauth-handshake-cookie-lifetime.md`](0187-oauth-handshake-cookie-lifetime.md)
+- **0192** — [`0192-a-category-orients-and-authorises-nothing.md`](0192-a-category-orients-and-authorises-nothing.md) · [`0192-platform-visibility-member-door.md`](0192-platform-visibility-member-door.md)
+
 ## Index
 
 | # | Title | Topic |
@@ -442,3 +469,4 @@ This keeps the decision history honest and traceable.
 | 0348 | [**The web tier may look, read-only, at what an owner's Render key can see** ([task 1004352](https://cloudbongos.com/builders#/task/1004352), goal 1000106 — working area 1, owner Lars). Amends ADR 0111 §2. **D1 (owner):** one route, `POST /provisioning/render/lookup`, may call Render from the web tier — GET only (workspaces; web services in one named workspace), the owner's key held for that request and never stored, logged or returned, every service checked to carry the workspace asked about, capped per builder. Every write stays in the runner. **D2 (owner):** a key sent during a Create rides the project's own `provision` run; the runner sets the app up on Render straight after the project is up and clears the key either way.](0348-the-web-tier-may-look-read-only-at-what-an-owners-render-key-can-see.md) | provisioning / security / render |
 | 0349 | [**A version preview is a sandboxed child the web tier launches, reached by a cookie** ([task 1004300](https://cloudbongos.com/builders#/task/1004300), goal 1000090 — BONGOS-V2, owner Lars, approved 2026-09-29). Amends ADR 0293 D1 for this feature only. **D1 (owner):** route by a `bongos_preview` cookie through an optional `request.divert` seam, not a path; forward only with the cookie, off the sign-in and preview paths, with no Bearer, and with `core.pin.move` re-checked on every request. **D2 (owner):** the npm-release module launches the preview itself, with a deny-by-default environment, a dump-and-restore copy of the database (never a template copy), one at a time, 20-minute idle stop, published versions within 30 of the running one. **D3:** the same database role and no egress firewall are accepted for now.](0349-a-version-preview-is-a-sandboxed-child-the-web-tier-launches.md) | modules / npm-release / deploy |
 | 0350 | [**The hub holds a per-project WRITE deploy key, so a hosted project's upgraded pin always reaches its GitHub repo** ([task 1004291](https://cloudbongos.com/builders#/task/1004291), follow-up to task 1004065). Amends ADR 0176. The owner's token lasts one hour and the checkout's own key is read-only, so most hosted upgrades ended "GitHub was not updated". **D1:** a second deploy key per repo, registered `read_only: false` as `cloudbongos-pin-<slug>`, the pull key untouched. **D2:** kept outside every checkout in the runner's own directory (0700 dir, 0600 key, modes verified), unreadable by the project's account. **D3:** minted at standup and whenever a fresh owner token finds none, so reconnecting GitHub once is enough. **D4:** `pushUpgradePin` tries write key, then owner token, then origin, never forced. **D5:** revoked on teardown and disconnect. **D6:** a project on the shared app user is refused a key: "needs its own account first". **D7:** /deploy says reconnecting sets up lasting access.](0350-the-hub-holds-a-per-project-write-deploy-key-so-a-hosted-upgrade-reaches-github.md) | provisioning / security |
+| 0351 | [**A criterion closes on a UAT, not on its linked tasks shipping** ([task 1004392](https://cloudbongos.com/builders#/task/1004392), goal 1000089 — working area 3). Supersedes ADR 0183's close rule. `wa7-government` had closed on six Board Room navigation tasks while nothing it describes was on the live site. **D1:** three checks — Code (linked tasks done, ≥1 shipped; automatic), Live, UAT — and the sweep closes a criterion only with a CURRENT sign-off (no older than the newest linked ship). **D2 (owner):** "Awaiting UAT" is a visible state. **D3 (owner):** one step; the signer is refused if they shipped linked work, the project owner excepted. **D4 (owner):** an mp4/webm up to 100 MB on the project's own server. **D5 (owner):** backend-only is set while a criterion is open and takes a recording-free sign-off. **D6 (owner):** Live is read via the `deploy.taskWhere` port where the site can tell, attested otherwise. **D7 (owner):** already-closed criteria stay closed ("Closed before UAT"). **D8:** `/satisfy` is a recorded override that needs a reason. **D9:** `/goal-uat` + `scripts/gds/uat.js`; the hall is task 1004402.](0351-a-criterion-closes-on-a-uat.md) | lifecycle / criteria / review |