docs(review): confident-zero design review of coord-send, coord-count, board, route
14 findings, one lens: every place an unknown or an error becomes a confident zero or a successful exit. All measured against throwaway fixtures; no behavior changed. Operator prioritizes. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NYneni3VzRUMn1UFszytrf
This commit is contained in:
parent
03e36c9499
commit
108a73a497
1 changed files with 259 additions and 0 deletions
259
docs/2026-08-14-confident-zero-review.md
Normal file
259
docs/2026-08-14-confident-zero-review.md
Normal file
|
|
@ -0,0 +1,259 @@
|
|||
# Design review: where an unknown or an error becomes a confident zero or a successful exit
|
||||
|
||||
Date: 2026-08-14. Reviewer: Fable 5/xhigh session (no advisor - Fable cannot
|
||||
carry one). Scope ordered by the operator: ONE lens over four scripts. No fix
|
||||
is implemented here; the operator prioritizes.
|
||||
|
||||
## Surface examined (the denominator for every "nothing further found" below)
|
||||
|
||||
```
|
||||
$ wc -l scripts/coord-send.sh scripts/coord-count.sh scripts/board.sh scripts/route.sh
|
||||
237 scripts/coord-send.sh
|
||||
133 scripts/coord-count.sh
|
||||
1083 scripts/board.sh
|
||||
329 scripts/route.sh
|
||||
1782 total
|
||||
```
|
||||
|
||||
All 1782 lines were read in full. Every claim below is produced by a command
|
||||
shown with it; each was run against a throwaway mailbox/tree under the session
|
||||
scratchpad (`CLAUDE_COORD_DIR` / `BOARD_ROOTS` fixtures), never the real
|
||||
mailbox. NOT examined (out of assignment scope, reported as unmeasured, not
|
||||
clean): coord-inbox.sh, coord-done.sh, coord-sweep.sh, brief-nightly.sh, the
|
||||
four selftests, and both hooks except a single grep of
|
||||
pre-state-line-guard.mjs for finding 13.
|
||||
|
||||
## Findings, most severe first (reviewer's ranking; operator decides)
|
||||
|
||||
### 1. board.sh: a missing coord-count.sh sibling silently zeroes all debt
|
||||
|
||||
board.sh:381, 395, 409, 516-517 all gate on `[ -f "$SELFDIR/coord-count.sh" ]`
|
||||
and silently skip when it fails; the four invocations also discard stderr.
|
||||
Measured by copying board.sh + route.sh (without coord-count.sh) to a
|
||||
scratch dir, against a fixture mailbox where repo-a holds one reply-owing
|
||||
message:
|
||||
|
||||
```
|
||||
real board.sh --brief : "repo-a INN 1 done" / "1 repo skylder svar"
|
||||
copied board.sh --brief: "Ingen repo skylder noen et svar i dag."
|
||||
"Disse har bare FYI-post ...: repo-a" <- mislabel
|
||||
real --inbox-plan : 1 block
|
||||
copied --inbox-plan : 0 blocks
|
||||
```
|
||||
|
||||
Not just absence: the fallback branch actively relabels a reply-owing message
|
||||
as FYI. Dead-letter and orphan cross-checks vanish silently too. A missing
|
||||
sibling is a real deployment state, not hypothetical - the 0.12.1 deployed-copy
|
||||
incident is exactly this shape.
|
||||
|
||||
### 2. coord-send: exit 0 to any well-formed recipient; mailbox created on the spot
|
||||
|
||||
(Known instance, re-verified.) coord-send.sh:156-158 validates only the FORM
|
||||
of the name; :176 `mkdir -p` creates the mailbox.
|
||||
|
||||
```
|
||||
$ CLAUDE_COORD_DIR=$T bash scripts/coord-send.sh --from testsender \
|
||||
--to repo-mailbxo --subject test --message hei
|
||||
coord-send: delivered to repo-mailbxo (...) # exit 0, mailbox now exists
|
||||
```
|
||||
|
||||
A typo'd recipient gets a mailbox no session will ever read, and the sender is
|
||||
told "delivered". The WP1d dead-letter column is the compensating control
|
||||
being designed - but see findings 8 and 11 for two holes in that net.
|
||||
|
||||
### 3. board.sh: a route line outside the vocabulary yields a confident command
|
||||
|
||||
(Known instance; the measured mechanism is worse than "parses to 0" - it
|
||||
parses to a VALID value.) route_cmd_for()'s sed captures `[a-z-]*`
|
||||
(board.sh:481-484), so `path=known2` extracts `known`, which route.sh then
|
||||
legitimately accepts:
|
||||
|
||||
```
|
||||
STATE.md: <!-- route: path=known2; verification=strong; reversibility=cheap; scope=local; ... -->
|
||||
--plan : command=claude --model sonnet --effort high --advisor opus
|
||||
```
|
||||
|
||||
The function's own comment says "a guessed command reads as authoritative";
|
||||
the reader violates it while the calculator stays clean. Fully-invalid tokens
|
||||
(`path=foo`) ARE caught (route.sh dies, command_missing= emitted); it is the
|
||||
prefix/case class that slips through as a confident answer.
|
||||
|
||||
### 4. board.sh: status tokens outside the vocabulary parse to a valid prefix or to "?"
|
||||
|
||||
Same `[a-z-]*` capture at board.sh:285. Fixture measurements:
|
||||
|
||||
```
|
||||
status=done2 -> table shows "done", sorted into FERDIG; no MALFORMED warning
|
||||
status=Planned -> "?"; footer says "1 repo mangler board-linje" (it HAS one)
|
||||
```
|
||||
|
||||
The MALFORMED detector (board.sh:294-298) only ever sees what the regex
|
||||
delivers, so it catches exactly the all-lowercase unknown tokens and nothing
|
||||
else. `done2` becomes a confident `done`; a case typo becomes "missing board
|
||||
line", which is a wrong diagnosis printed as fact.
|
||||
|
||||
### 5. coord-count: missing mailbox root -> exit 0, empty output
|
||||
|
||||
coord-count.sh:59 `[ -d "$COORD" ] || exit 0`.
|
||||
|
||||
```
|
||||
$ CLAUDE_COORD_DIR=/nonexistent-coord-xyz bash scripts/coord-count.sh; echo $?
|
||||
0 # no output, no stderr
|
||||
```
|
||||
|
||||
"Always exit 0" is the SessionStart contract and can stay - but nothing (not
|
||||
even stderr, which interactive callers WOULD see) distinguishes "no mail
|
||||
anywhere" from "the root does not exist". Every board consumer inherits the
|
||||
zero, so one typo'd CLAUDE_COORD_DIR reads as a machine-wide clean slate.
|
||||
|
||||
### 6. board.sh: git failure -> DRT=0 (and the same shape in INN and ALDER)
|
||||
|
||||
board.sh:247 `git status --porcelain 2>/dev/null | wc -l`: any git error
|
||||
(corrupt repo, dubious-ownership refusal) -> empty pipe -> 0. Fixture repo-d
|
||||
with `.git` as an empty file, an uncommitted STATE.md inside:
|
||||
|
||||
```
|
||||
repo-a (working git, same content): DRT 1
|
||||
repo-d (git errors out): DRT 0
|
||||
```
|
||||
|
||||
Same mechanism, not separately measured: inbox `ls | wc -l` at :251-253
|
||||
(unreadable inbox -> INN 0) and `stat` failure -> age=0 at :276-277 (ALDER
|
||||
"touched today"). SISTE handles its error case correctly ("-", :260-264) and
|
||||
is the in-file counterexample.
|
||||
|
||||
### 7. coord-send: --to is the only line-oriented field never sanitized
|
||||
|
||||
sanitize_field exists for exactly this (coord-send.sh:76-80) and is applied to
|
||||
FROM (:81) and SUBJECT (:141) - denominator: 3 grep hits for sanitize_field,
|
||||
none covering TO. A newline in --to therefore lands verbatim in the `to:`
|
||||
frontmatter line:
|
||||
|
||||
```
|
||||
$ ... --to "$(printf 'x\nreply-expected: no')" ... # exit 0
|
||||
frontmatter: to: x / reply-expected: no / ... / reply-expected: yes
|
||||
$ coord-count on that mailbox:
|
||||
x
|
||||
reply-expected: no\t1\t0\t0 # two-line record breaks the TSV; owed=0
|
||||
```
|
||||
|
||||
The injected line silences the debt that the engine itself declared
|
||||
(`reply-expected: yes`), defeating coord-count's own stated rule that only
|
||||
the frontmatter block may speak - the attack line IS inside the block. Only
|
||||
self-inflicted (the sender already controls --fyi), so robustness rather than
|
||||
security - but a malformed name both corrupts the count format and zeroes an
|
||||
owed reply, with exit 0.
|
||||
|
||||
### 8. coord-send: names in the `..foo` class are deliverable but uncountable
|
||||
|
||||
Send guards exact `.`/`..` only (:96, :128, :156-158); coord-count's globs
|
||||
`"$COORD"/* "$COORD"/.[!.]*` (:82) can never match a name starting with `..`:
|
||||
|
||||
```
|
||||
$ ... --to ..foo ... -> exit 0, delivered
|
||||
$ ls -a $T -> ..foo repo-mailbxo
|
||||
$ coord-count -> repo-mailbxo 1 1 0 # ..foo absent
|
||||
```
|
||||
|
||||
Mail there is not "never read" - it is never COUNTED, so the dead-letter net
|
||||
(finding 2's compensating control) has a hole for exactly this class.
|
||||
|
||||
### 9. coord-send --reply-to: coord-done failure suppressed, success claimed
|
||||
|
||||
coord-send.sh:234 runs coord-done with `>/dev/null 2>&1` and then
|
||||
unconditionally prints success. Measured with a stub coord-done.sh (`exit 1`):
|
||||
|
||||
```
|
||||
coord-send: original (...) marked handled # exit 0
|
||||
$ ls inbox/ -> original still there; no archive/ exists
|
||||
```
|
||||
|
||||
Self-healing over time (the un-archived original keeps re-injecting), but the
|
||||
printed claim is false at the moment it is made, and a session trusting it
|
||||
will report the reply debt as closed.
|
||||
|
||||
### 10. board.sh: invalid roots -> silence with exit 0
|
||||
|
||||
board.sh:235 exits 0 before any rendering when discovery finds nothing:
|
||||
|
||||
```
|
||||
$ BOARD_ROOTS=/nonexistent-xyz bash scripts/board.sh --plan; echo $?
|
||||
0 # no output at all
|
||||
```
|
||||
|
||||
brief-nightly.sh compensates in ITS path (empty render = failure); the
|
||||
interactive table, --plan, --inbox-plan and any driver consuming them get
|
||||
"no repos exist" as a clean success.
|
||||
|
||||
### 11. coord-count: column 4's "-" means three different things
|
||||
|
||||
"Has .origin", "no filename matched the timestamp grammar", and "date parse
|
||||
failed" all print the same token (:111-125):
|
||||
|
||||
```
|
||||
claimedrepo 1 1 - # has .origin (fine)
|
||||
deadrepo 1 1 - # NO .origin, ungrammatical filename -> unmeasurable
|
||||
deadrepo2 1 1 13 # the only distinguishable case
|
||||
```
|
||||
|
||||
The fail-safe direction is documented and right; the collapse is not: a
|
||||
consumer cannot tell "not a dead letter" from "not measured", which is the
|
||||
exact reporting rule this machine's Verifiseringslov exists to enforce.
|
||||
Unmeasured but mechanical: the column rests on BSD-only `date -j` (:117), so
|
||||
on Linux (this is a public plugin) every mailbox prints "-" forever and WP1d
|
||||
detection is silently inert machine-wide.
|
||||
|
||||
### 12. board.sh:895: the banned NR==FNR idiom survives in the --focus join
|
||||
|
||||
```
|
||||
$ grep -n 'NR==FNR' scripts/*.sh
|
||||
board.sh:554,555,831,987 <- four comment lines banning it
|
||||
board.sh:895 <- one live code site (the --focus keep-join)
|
||||
```
|
||||
|
||||
Currently safe only through a distant invariant (every resolved slug is
|
||||
declared by >=1 repo, so fp_names is never empty while applied). If any
|
||||
future change lets fp_names be empty, the whole plan silently becomes
|
||||
"0 tabber" - the exact measured 0.21.0 defect this file's comments were
|
||||
written against. The selftest's NR==FNR regression check (board-selftest.sh
|
||||
:1224-1247) covers the OTHER joins only.
|
||||
|
||||
### 13. The MAX_LINES class: operator decisions cast into version-pinned code
|
||||
|
||||
(Known instance, confirmed and extended.)
|
||||
|
||||
```
|
||||
source pre-state-line-guard.mjs:59 MAX_LINES = 120
|
||||
cache .../repo-mailbox/0.23.0/...mjs:57 MAX_LINES = 60
|
||||
cache .../repo-mailbox/0.24.0/...mjs:59 MAX_LINES = 120
|
||||
$ grep -c 'process.env' hooks/scripts/pre-state-line-guard.mjs -> 0
|
||||
```
|
||||
|
||||
No env override exists, so a decision reaches enforcement only via release +
|
||||
cache update + per-tab restart (the 60-vs-120 gap was live on this machine
|
||||
between the decision and tonight's update). Same class found in scope:
|
||||
the dead-letter 3-day threshold (board.sh:398) is likewise hard-coded with no
|
||||
override. NESTE_WIDTH=38 is cosmetic and documented as the column's property.
|
||||
|
||||
### 14. Footnote: coord-count's header contract vs. its own code
|
||||
|
||||
Header says "Exit: always 0"; `--exclude` without a value exits 2 (:49). The
|
||||
loud direction is the right one - the header is what needs the correction.
|
||||
|
||||
## The positive control
|
||||
|
||||
route.sh is the in-repo proof that the loud pattern is achievable: every
|
||||
trait is a closed set, every unknown value dies with exit 2, the last-session
|
||||
record is all-or-none, and empty rationale is refused. board.sh's chain-root
|
||||
walk ("credit NOBODY over a guess") is the same discipline. Every finding
|
||||
above is a deviation from a house style the repo itself already defines.
|
||||
|
||||
## Coverage statement
|
||||
|
||||
Within the 1782 lines read: 37 `2>/dev/null` occurrences (grep -c over the
|
||||
four files) were each judged during the full read; the ones that convert an
|
||||
error into a confident zero/success are findings 1, 5, 6, 9 above, the
|
||||
remainder either fail closed (e.g. coord-send:106 refuses on unreadable
|
||||
sender) or feed paths that label their unknowns. No further instances found
|
||||
within that surface; the unexamined scripts listed at the top are NOT claimed
|
||||
clean.
|
||||
Loading…
Add table
Add a link
Reference in a new issue