diff --git a/documentation/runbooks/workspace-CLAUDE.md b/documentation/runbooks/workspace-CLAUDE.md index 76ea98c..c8b46d3 100644 --- a/documentation/runbooks/workspace-CLAUDE.md +++ b/documentation/runbooks/workspace-CLAUDE.md @@ -178,7 +178,7 @@ turns a true alarm into one the operator dismisses. ### A comment asserting an invariant needs a test pinning it, or it is a wish -**Six instances in this project have shipped guarantees the code did not provide** — each survived +**Seven instances in this project have shipped guarantees the code did not provide** — each survived review because the comment read as settled: | # | Comment | What it claimed | What the code did | @@ -189,10 +189,14 @@ review because the comment read as settled: | 4 | `classifyRunStates` I1 | *"StateStopped means deliberately stopped by the user"* | quiesce stops stacks the same way — a failed restart was silent (F-CRIT-1) | | 5 | `inflight.go` | *"a caller that cannot acquire DEFERS"* | the backup caller recorded a failure and paged the operator (F-A1) | | 6 | `quiesce.go` | the agent's 409 *prevents* "a spurious failure" | on the start path it produced one (F-A1) | +| 7 | `recovery_unit.go` B2 refusal (R-181) | *"the previous unit is untouched and NOTHING was deleted"* | *nothing deleted* held; **untouched was measured false** — the floor was checked ONLY in `captureAllRecoveryUnits`, while the two dump legs wrote the bulk into the same tree first and unguarded, so a 182,272 B tar became 2,147,666,432 B under a manifest that had not moved | -Two of these (4 and 5/6) were found by Campaign 8 **on live hardware**, not by review or unit tests -— #4 had a green, red-proofed test suite over a production path that was broken two independent -ways. So: +Three of these (4, 5/6 and 7) were found **on live hardware**, not by review or unit tests — #4 had a +green, red-proofed test suite over a production path that was broken two independent ways, and #7 +survived a full green suite plus three of its own red-proofs, because every one of them asserted the +mechanism inside `captureAllRecoveryUnits` and none asserted the **consequence** across the whole +backup run. The test that would have caught it is the one #7's fix ships: fingerprint the tree before +and after, and compare. So: - If a comment states an invariant, **name the test that pins it**, or write one. - If an invariant has a stated dependency (*"if either invariant changes, revisit this"*), that is