docs(records): Piece D build note, TOOLS.md review verbs, DEFERRED updates (#1508)

Co-Authored-By: Claude Opus 5.5 <[email protected]>

BUILD-LOG.md

@@ -3332,3 +3332,36 @@ queue suite passed 24 there and failed its 2 live checks, because the
 export isn't the canonical root. That is a real limit of the recipe after
 genesis, not a defect in row 10 (DEFERRED). In the canonical checkout the
 queue suite passed 26/26 with the same files.
+
+## 2026-09-27: Queue Piece D, reviews as issue comments (#1508, Darkwing)
+
+f539466f lands row 12. `queue move ID in-review` posts the review request
+as a Gitea comment as the acting seat, and `queue review record` reads
+the verdicts back. Reviews stop being files in `docs/plans/reviews/`.
+
+Filbert's round 1 (a2dc2302) found C1: on a comment round,
+in-review→waiting-on-jason needed no approvals. The move now takes the
+same approval and unresolved checks as in-review→done, and Filbert
+corrected the plan table (293747cd). Round 2 (cf1d3fd0) approved it.
+Filbert asked for n1 before the commit: four test lines that kill the
+last surviving mutant, which counted an earlier round's approval. Filbert
+checked those lines, and they didn't go back for another round.
+
+`scripts/gitea-api.sh` now reads the raw per-seat token files, because
+the files Jason ruled on aren't JSON (lead decisions 37 to 39). Rocko
+round 1 (e896192f): curl ran on an empty config after a failed second
+read. Round 2 (2096b0a3): an inherited exported `CFG` carried the token
+into curl's environment. Darkwing fixed both, and also closed
+`SHELLOPTS=allexport`. Sage's lead check passed: 12 dummy cases keep the
+token in the config stream only, and removing `export -n` leaks it in
+all 12.
+
+Sage checked the manifest (b402fb38, 19 of 19 OK) after applying
+build.patch 28d0790e and helper.patch 48edd46b at cdcedb27. On an index
+export the suites passed: config 24, task 90, foundation 44, conductor
+17, release 14, auth 15, discord 64, extension-package 18, queue 27
+(live checks skipped outside the canonical root). Ledger tests passed
+58/58. The canonical checkout's queue suite passed 29/29. Correction: the
+first export run failed task 31 and release 3 because Docker had no
+address pools left. Sage removed 12 empty leftover export networks, and
+the rerun passed.

docs/SESSIONS.md

@@ -435,3 +435,7 @@ are never rewritten or removed; corrections are new entries.
 2026-09-27T01:14:09Z | Sage (T3 Claude Code, thread 1ef1e4f8) | queue A2 commit | Filbert A2 r1 approve (f167b85e); 21 files match manifest 782bcb62; queue-md and tools-md patches applied; nine suites green on index export; lead decision 35. Genesis next.
 2026-09-27T01:17:18Z | Sage (T3 Claude Code, thread 1ef1e4f8) | queue genesis (#1508) | map check ok; hook installed; genesis rev 0, 30 rows (3377b877); assign 10 sage and row 13 gate reword (42f3f2d9, rev 2); verify and render current; queue suite 26/26
 2026-09-27T01:24:24Z | Sage (T3 Claude Code, thread 1ef1e4f8) | row 10 and lead decision 36 (#1508) | seats read the queue (5efe28ab), header to goals review (eae341d3), row 10 waits on Gate G; #1510 stays with Jason (no quote accepts it); CHAT-03 author Dewey, reviewers Filbert and Rocko; export recipe live-check limit to DEFERRED
+2026-09-27T02:40:25Z | Filbert (T3 Claude Code, thread 9cb9731e) | queue Piece D review r1 (#1508, row 12) | changes requested, 1 item (C1: in-review→waiting-on-jason skips reviewer approvals on a comment round; plan-table gap, reproduced); build.patch cb7a6c66 manifest 10/10, 141/141 tests, 24/24 own mutants killed; report a2dc2302; no commit
+2026-09-27T02:43:14Z | Filbert (T3 Claude Code, thread 9cb9731e) | queue plan C1 correction (#1508, row 12) | per Sage's ruling: plan table line 1470 and 8.9 receipts now gate in-review→waiting-on-jason on reviewer approvals; log entry added; plan sha256 293747cd; uncommitted, for the D commit
+2026-09-27T03:12:01Z | Filbert (T3 Claude Code, thread 9cb9731e) | queue Piece D review r2 (#1508, row 12) | approved: C1 fix correct; build.patch 8a19f7fa manifest 10/10 at cdcedb27, 142/142 tests; 7 of 8 own mutants killed, the stale-approval survivor gets a checked 4-line test (n1); report cf1d3fd0; no commit
+2026-09-27T15:07:51Z | Sage (T3 Claude Code, thread 1ef1e4f8) | queue Piece D commit (#1508, row 12) | manifest b402fb38 19/19; helper lead check (decision 39); nine suites green on export after removing 12 empty leftover networks; f539466f; TOOLS.md from Darkwing's proposal; DEFERRED n2 and cold-start flake

docs/TOOLS.md

@@ -128,7 +128,7 @@ Push is never automatic.
 | `scripts/test-release.sh` | Release selftests | 14 cases |
 | `scripts/test-conductor.sh` | Auto-apply selftests (sandboxed) | 17 cases |
 | `scripts/test-auth.sh` | Auth checkpoint selftests (no Docker) | 13 cases |
-| `scripts/gitea-api.sh <METHOD> <path> [body]` | Gitea API helper | Token never on argv/stdout |
+| `scripts/gitea-api.sh <METHOD> <path> [body]` | Gitea API helper; reads the JSON credential file or a raw per-seat token file | Token never on argv/stdout |
 
 ## Seat launch with registration (`scripts/mosaic`)
 
@@ -153,6 +153,8 @@ usage. Details and the record's fields: `packages/seat/README.md`.
 scripts/mosaic queue list | show ID | next [SEAT]
 scripts/mosaic queue add|move|release|assign|note|set ... --op ID [--by NAME]
 scripts/mosaic queue verify [--current] | render [--check] | sync | unlock [--check-gate]
+scripts/mosaic queue review request|resolve|abandon|record ... --op ID [--by NAME]
+scripts/mosaic queue review verify-commit ID REF
 scripts/queue-commit.sh -m MSG
 ```
 
@@ -162,8 +164,12 @@ Canonical checkout only. Every change needs an `--op ID` chosen before the
 first attempt and reused on retry; only an op whose `ok <op> rev N` receipt
 printed is done. The lead commits queue changes with `scripts/queue-commit.sh`;
 the pre-commit guard refuses any other commit that stages the two queue files.
+Moving a row with reviewers to in-review posts one review request comment
+on its issue as the acting seat, with the seat's own token file in
+`MOSAIC_GITEA_CREDENTIAL_FILE`; reviewers then run `review record`.
 Exit codes: `0` ok · `1` failed · `2` invalid or refused · `3` uncertain,
-retry the same op · `4` usage. Details: `packages/queue/README.md`.
+retry the same op (for a review request, the retry sends nothing; resolve or
+abandon it) · `4` usage. Details: `packages/queue/README.md`.
 
 ## Discord connector (`scripts/discord.sh`)
 

docs/plans/DEFERRED.md

@@ -121,6 +121,10 @@ at every gate. Started 2026-09-12 during the control board MVP.
   address pools have been fully subnetted". Sage removed its own five stale
   networks. The dw-* ones are still there. Fix: the export recipe, or the
   suites, removes the project network on exit. (2026-09-26)
+  2026-09-27: it happened again on the Piece D candidate (task 31 and
+  release 3 failures). Sage removed 12 leftover export networks from
+  other seats, each checked for zero attached containers first, and both
+  suites then passed. Still open.
 
 - **Ledger T3 read: snapshot isolation has no test.** `readT3` runs every
   query in one read transaction, but no test proves a write landing during
@@ -134,14 +138,18 @@ at every gate. Started 2026-09-12 during the control board MVP.
   Sage asked the SetSpark lead to use a one-word role. The rule stays as
   it is. (2026-09-26, #1506)
 
-- **Queue suite fails its live checks outside the canonical checkout.**
+- **Queue: an owner listed as a reviewer blocks the row.** `set reviewers`
-  Since genesis (3377b877), `test-queue.sh` runs `queue verify` and `render
+  and `assign` accept the row's owner as a reviewer. The owner can't record
-  --check` whenever HEAD holds `queue.json`. Both refuse in an index export
+  a verdict on their own row, so the row can't leave review. That fails
-  or review clone ("this checkout is /tmp/...; the queue's canonical root
+  closed. Fix: refuse the owner in both verbs. Filbert's n2 on Piece D r2
-  is ..."), so the export recipe reports 24 passed, 2 failed. The canonical
+  (cf1d3fd0). (2026-09-27, #1508)
-  checkout passes 26/26. Fix: skip the live checks, with a printed reason,
+- **Queue tests: one unexplained failure on a cold start.** Darkwing's
-  when the toplevel isn't the recorded `canonicalRoot`. Darkwing, with
+  first run of the D candidate in a fresh clone gave 141 passed, 1 failed.
-  row 12 or 13. (2026-09-27, #1508, lead decision 36)
+  The failing test's name wasn't captured. 15 reruns passed 142/0,
+  sequential and parallel. Darkwing suspects a timing bound, most likely
+  the 300 ms deadline case in the transport test, which allows 4000 ms.
+  That isn't confirmed. Next time: capture the name, then fix it as its
+  own patch. (2026-09-27, #1508)
 
 ## Queue
 
@@ -158,3 +166,8 @@ Moved to `docs/plans/QUEUE.md` on 2026-09-13. This file holds only gaps.
 - Combined concurrent test hangs (2026-09-14, #1509): closed on evidence from 3edb15eb. At default concurrency the union passed 406/406 three times on the R2 snapshot and 408/408 on the commit's index, where clean HEAD had hung four runs out of four. The inherited-intermittency entry from 2026-09-15 stays open until a later run shows it is the same cause.
 - A nested `node --test` passes even when its tests fail (2026-09-26, #1508): closed. Queue A1 (34a72af9) clears NODE_TEST_CONTEXT on its own path. N13 fixes `test-foundation.sh` and `test-discord.sh`, each with a check that fails the suite if the clearing is lost. Darkwing wrote it (n13.patch 00868b2f) and Filbert approved it (e464be6c). Sage's grep on 2026-09-27 finds no other nested `node --test`: in scripts, only the two suites, `test-queue.sh` and `queue-commit.sh`, and in JS, only the queue test that covers the fix.
 - SetSpark service accepted any string as a decision approver (2026-09-26, #1509): closed. Fixed in shared-signals cc74d92 (Rocko approved R2, lead decision 24). The operations seat (T3 12fe8cda) deployed it to VM 1022 at 00:23Z on 2026-09-27. The running `service.py` hash matches cc74d92, and `/healthz` returns 200 inside the network and through the public tunnel. The read-only README survey found one row breaking the rule (DEC-009, Proposed, version 1), one open request that isn't ready (DEC-009's), and no Accepted decision with more than 16 approvers. No rows changed. DEC-009 stays as stored (lead decisions 21 and 28). The service now refuses approvals on it, so nothing can go wrong silently. Side effect: `up -d` also recreated caddy, about 20 s of edge downtime for all hosts. That is for the shared-signals deploy procedure to fix, not Mosaic.
+- Queue suite failed its live checks outside the canonical checkout
+  (2026-09-27, #1508): closed by Piece D, f539466f. `test-queue.sh` now
+  skips `verify` and `render --check` with a printed reason when the
+  toplevel isn't the recorded `canonicalRoot`. An index export passed
+  27/0, and the canonical checkout 29/0.