@bongos/core 1.20.5 → 1.20.7

package/docs/api/openapi.json

@@ -105,6 +105,10 @@
       "name": "cost",
       "description": "Endpoints under `/api/bongos/cost`."
     },
+    {
+      "name": "criterion-uats",
+      "description": "Endpoints under `/api/bongos/criterion-uats`."
+    },
     {
       "name": "dependencies",
       "description": "Endpoints under `/api/bongos/dependencies`."
@@ -4921,6 +4925,51 @@
         ]
       }
     },
+    "/criterion-uats/recordings/{name}": {
+      "get": {
+        "operationId": "get_criterion_uats_recordings_name",
+        "tags": [
+          "criterion-uats"
+        ],
+        "summary": "GET /criterion-uats/recordings/:name",
+        "description": "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.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/lifecycle/routes/criterion-uat.js",
+        "parameters": [
+          {
+            "name": "name",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `name`."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/dependencies": {
       "post": {
         "operationId": "post_dependencies",
@@ -5231,6 +5280,72 @@
         ]
       }
     },
+    "/done-when/{criterionId}/backend-only": {
+      "put": {
+        "operationId": "put_done_when_criterionId_backend_only",
+        "tags": [
+          "done-when"
+        ],
+        "summary": "PUT /done-when/:criterionId/backend-only",
+        "description": "perm criterion.create + the per-goal authoring wall (ADR 0154).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `criterion.create` (all required).",
+        "x-rank": "metic+archon",
+        "x-source": "modules/lifecycle/routes/criterion-uat.js",
+        "x-permissions": [
+          "criterion.create"
+        ],
+        "parameters": [
+          {
+            "name": "criterionId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `criterionId`."
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PutDoneWhenCriterionIdBackendOnlyRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PutDoneWhenCriterionIdBackendOnlyResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/done-when/{criterionId}/satisfy": {
       "post": {
         "operationId": "post_done_when_criterionId_satisfy",
@@ -5238,7 +5353,7 @@
           "done-when"
         ],
         "summary": "POST /done-when/:criterionId/satisfy",
-        "description": "Auth (Metic+): confirm a criterion — flip it to satisfied. Accepts optional satisfied_by_task_id so the UI can show which ship-task fulfilled it. When the criterion belongs to a goal and was its LAST unsatisfied one, the goal auto- flips open→achieved (ADR 0086 §6 / BV1.R63). Re-ranked Archon→Metic+ so the planner — not only the Archon — closes the criterion/goal loop; the route is 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).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `criterion.satisfy` (all required).",
+        "description": "Auth (Metic+): confirm a criterion — flip it to satisfied. Accepts optional satisfied_by_task_id so the UI can show which ship-task fulfilled it. When the criterion belongs to a goal and was its LAST unsatisfied one, the goal auto- flips open→achieved (ADR 0086 §6 / BV1.R63). Re-ranked Archon→Metic+ so the planner — not only the Archon — closes the criterion/goal loop; the route is 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.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `criterion.satisfy` (all required).",
         "x-rank": "metic+archon",
         "x-source": "modules/lifecycle/routes/done-when.js",
         "x-permissions": [
@@ -5290,6 +5405,183 @@
         ]
       }
     },
+    "/done-when/{criterionId}/uat": {
+      "get": {
+        "operationId": "get_done_when_criterionId_uat",
+        "tags": [
+          "done-when"
+        ],
+        "summary": "GET /done-when/:criterionId/uat",
+        "description": "a criterion and its goal are readable by any builder.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/lifecycle/routes/criterion-uat.js",
+        "parameters": [
+          {
+            "name": "criterionId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `criterionId`."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      },
+      "post": {
+        "operationId": "post_done_when_criterionId_uat",
+        "tags": [
+          "done-when"
+        ],
+        "summary": "POST /done-when/:criterionId/uat",
+        "description": "perm criterion.review; the non-shipper wall is in-handler.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `criterion.review` (all required).",
+        "x-rank": "metic+archon",
+        "x-source": "modules/lifecycle/routes/criterion-uat.js",
+        "x-permissions": [
+          "criterion.review"
+        ],
+        "parameters": [
+          {
+            "name": "criterionId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `criterionId`."
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostDoneWhenCriterionIdUatRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostDoneWhenCriterionIdUatResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/done-when/{criterionId}/uat/recording": {
+      "post": {
+        "operationId": "post_done_when_criterionId_uat_recording",
+        "tags": [
+          "done-when"
+        ],
+        "summary": "POST /done-when/:criterionId/uat/recording",
+        "description": "perm criterion.review: evidence for a UAT sign-off.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `criterion.review` (all required).",
+        "x-rank": "metic+archon",
+        "x-source": "modules/lifecycle/routes/criterion-uat.js",
+        "x-permissions": [
+          "criterion.review"
+        ],
+        "parameters": [
+          {
+            "name": "criterionId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `criterionId`."
+          }
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "additionalProperties": true
+              }
+            }
+          },
+          "x-validated": false,
+          "x-body-undocumented": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostDoneWhenCriterionIdUatRecordingResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/done-when/{criterionId}/unsatisfy": {
       "post": {
         "operationId": "post_done_when_criterionId_unsatisfy",
@@ -25365,10 +25657,71 @@
           "satisfied_by_task_id": {
             "type": "integer",
             "minimum": 1
+          },
+          "override_reason": {
+            "type": "string",
+            "maxLength": 2000
           }
         },
         "additionalProperties": false
       },
+      "PostDoneWhenCriterionIdUatRecordingResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "recording": {},
+          "bytes": {}
+        },
+        "required": [
+          "ok",
+          "recording",
+          "bytes"
+        ]
+      },
+      "PostDoneWhenCriterionIdUatRequest": {
+        "type": "object",
+        "properties": {
+          "kind": {
+            "type": "string",
+            "maxLength": 32
+          },
+          "recording": {
+            "type": "string",
+            "maxLength": 80
+          },
+          "live_attested": {
+            "type": "boolean"
+          },
+          "note": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "kind"
+        ],
+        "additionalProperties": false
+      },
+      "PostDoneWhenCriterionIdUatResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "signoff": {},
+          "criterion_closed": {},
+          "achieved_goals": {},
+          "closed_versions": {}
+        },
+        "required": [
+          "ok",
+          "signoff",
+          "criterion_closed",
+          "achieved_goals",
+          "closed_versions"
+        ]
+      },
       "PostDoneWhenCriterionIdUnsatisfyResponse": {
         "type": "object",
         "properties": {
@@ -28844,6 +29197,33 @@
           "counter"
         ]
       },
+      "PutDoneWhenCriterionIdBackendOnlyRequest": {
+        "type": "object",
+        "properties": {
+          "backend_only": {
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "backend_only"
+        ],
+        "additionalProperties": false
+      },
+      "PutDoneWhenCriterionIdBackendOnlyResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "criterion_id": {},
+          "backend_only": {}
+        },
+        "required": [
+          "ok",
+          "criterion_id",
+          "backend_only"
+        ]
+      },
       "PutGovernmentRanksRankKeyPermissionsPermissionKeyResponse": {
         "type": "object",
         "properties": {
@@ -29094,9 +29474,9 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 455,
-  "x-schema-count": 487,
-  "x-undocumented-bodies": 11,
-  "x-response-schemas": 331,
+  "x-endpoint-count": 460,
+  "x-schema-count": 492,
+  "x-undocumented-bodies": 12,
+  "x-response-schemas": 334,
   "x-generated-by": "scripts/gds/gen-api-docs.js"
 }

package/docs/api-reference.md

@@ -2,7 +2,7 @@
 
 # Bongos API reference
 
-> **Generated from the live route files** — the route file is authoritative. 455 endpoints across 81 route files.
+> **Generated from the live route files** — the route file is authoritative. 460 endpoints across 82 route files.
 > Machine-readable spec: [`docs/api/openapi.json`](api/openapi.json) (OpenAPI 3.1). Rendered docs site: **`/docs`** (e.g. `cloudbongos.com/docs`).
 
 Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust-boundary-server-enforced-permissions.md)): `public` < `any-builder` < `metic+archon` < `archon`.
@@ -215,6 +215,12 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 |---|---|---|---|---|
 | POST | `/api/bongos/cost` | `any-builder` | `task_id`, `amount_usd`, `category`, `description`, `source`, `source_ref`, `recorded_at`, `fresh_input_usd`, `cache_read_usd`, `cache_write_usd`, `output_usd`, `builder_id`, `skill_name` | log cost on own claim (idempotent via source/source_ref). |
 
+## `criterion-uats` (1)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/criterion-uats/recordings/:name` | `any-builder` | — | evidence about a criterion any builder can read. |
+
 ## `dependencies` (2)
 
 | Method | Path | Rank | Body | Description |
@@ -230,12 +236,16 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | POST | `/api/bongos/discord/channels/reconcile` | `metic+archon` | — | POST /api/bongos/discord/channels/reconcile — apply the config to Discord now. |
 | GET | `/api/bongos/discord/channels/snapshot` | `metic+archon` | — | GET /api/bongos/discord/channels/snapshot — what docs/discord/channels.json WOULD say if it described the guild exactly as it is right no… |
 
-## `done-when` (4)
+## `done-when` (8)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
 | PATCH | `/api/bongos/done-when/:criterionId` | `metic+archon` | `criterion_md`, `goal_id` | PATCH /done-when/:criterionId — amend a criterion's TEXT (task 1003102) and/or MOVE it between goals (task 1003509). |
-| POST | `/api/bongos/done-when/:criterionId/satisfy` | `metic+archon` | `satisfied_by_task_id` | Auth (Metic+): confirm a criterion — flip it to satisfied. |
+| PUT | `/api/bongos/done-when/:criterionId/backend-only` | `metic+archon` | `backend_only` | perm criterion.create + the per-goal authoring wall (ADR 0154). |
+| POST | `/api/bongos/done-when/:criterionId/satisfy` | `metic+archon` | `satisfied_by_task_id`, `override_reason` | Auth (Metic+): confirm a criterion — flip it to satisfied. |
+| GET | `/api/bongos/done-when/:criterionId/uat` | `any-builder` | — | a criterion and its goal are readable by any builder. |
+| POST | `/api/bongos/done-when/:criterionId/uat` | `metic+archon` | `kind`, `recording`, `live_attested`, `note` | perm criterion.review; the non-shipper wall is in-handler. |
+| POST | `/api/bongos/done-when/:criterionId/uat/recording` | `metic+archon` | _undocumented_ | perm criterion.review: evidence for a UAT sign-off. |
 | POST | `/api/bongos/done-when/:criterionId/unsatisfy` | `metic+archon` | — | Auth: flip a criterion back to unsatisfied (rare; for corrections). |
 | GET | `/api/bongos/done-when/pending-review` | `metic+archon` | — | Auth (Metic+): the criterion review queue — every criterion auto-flagged "met — pending review" (≥1 linked task, all shipped, not yet con… |
 
@@ -809,5 +819,5 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 
 ---
 
-> 11 write endpoint(s) take a JSON body with no declared validator schema — their fields are not yet machine-documented. Adding a `validateOrRespond` schema (`src/bongos/routes/_helpers.js`) surfaces them here automatically.
+> 12 write endpoint(s) take a JSON body with no declared validator schema — their fields are not yet machine-documented. Adding a `validateOrRespond` schema (`src/bongos/routes/_helpers.js`) surfaces them here automatically.
 

package/docs/architecture.md

@@ -183,6 +183,13 @@ task_criteria(task_id FK tasks, criterion_id FK done_when_criteria, source 'back
               -- ship that CLOSED it). Backed GET /versions/:id/progress + /status. Populated on task-create
               -- via POST /tasks { criterion_ids } + the /tasks/:id/criteria manage endpoints (#438); "Cn" is
               -- the 1-based position by (sort_order, criterion_id). idx on (criterion_id) + (task_id).
+lifecycle_criterion_uats(id, criterion_id FK done_when_criteria, kind 'uat'|'backend_signoff'|'override',
+              signed_off_by FK builders, recording_file, live_basis 'deploy_reading'|'attested'|'not_checked',
+              note, created_at)  -- lifecycle_015 (task 1004392, ADR 0351): APPEND-ONLY sign-offs. A criterion
+              -- closes only with a uat/backend_signoff row no older than its newest linked ship; until then
+              -- it reads "Awaiting UAT". An `override` row is what POST /done-when/:id/satisfy writes now.
+lifecycle_criterion_backend_only(criterion_id PK FK done_when_criteria, marked_by, marked_at)
+              -- presence = backend-only (no screen to record); settable only while the criterion is open.
 session_pulses(claim_id PK, builder_id, last_pulse_at)  -- heartbeat for stale-claim detection
 task_grades(id, task_id UNIQUE, score NUMERIC(3,1), passed bool, threshold NUMERIC(3,1),
             grader_kind 'auto'|'subagent'|'lars', grader_version, rubric_scores jsonb,