docs(register): C-345 — verification tooling reported a green suite that was red

[Polichinel]

Part of #421. /register-risk output from Story 2's close-out — not a story, a finding about how the stories are being verified.

What happened, twice

uv run pytest -q | tail -2; echo "EXIT=$?"     # EXIT=0, pytest had exited 1

A pipeline's exit status is that of its last element. tail succeeds regardless, so the status reported was tail's. Then a backgrounded run's harness task-notification reported "exit code 0" for the same reason — that command ended in an echo.

The second was caught only by reading the output file instead of the notification. By then the user had already been told the suite was running and would be folded in. One step from reporting a green suite that was red.

Why Tier 2, stated rather than assumed

Not Tier 3 — this is not a maintainability cost. The suite is the gate on every story in this epic; a false green means a defect merges, and per C-343 it can then sit in production for up to two months. Not Tier 1 — nothing was corrupted and no model output was wrong; the failure is in knowing whether the work is sound.

The trigger is not hypothetical: it fired twice in one session, and this project has two recorded false-readiness incidents that each cost a full day.

The shape is the cluster's own

C-330	a nightly no-op exiting 0
C-337	a lockfile frozen with no error
C-343	a deploy that deployed nothing
C-345	the instrument used to find all three

An epic about mechanisms that report success while doing nothing spent a week using one. Cluster is now nine open of eleven rows.

Mitigation, and why it is not enough

uv run pytest -q > out.txt 2>&1; echo "PYTEST_EXIT=$?"
grep -cE '^FAILED' out.txt

Unpiped $?, plus a second independent reader. Adopted mid-session and used for every check since — including this PR's. But a habit is not a control: nothing prevents the next pipeline masking a status the same way. The instrument would refuse to report a result it did not obtain unpiped. Proposed for #424, which now carries three: uv lock --check (C-342), the tag-vs-HEAD pre-flight (C-343), and this.

Not registered, and why

• Unbounded until … sleep 30 poll that died on a transient DNS failure — one-line fix (bound the loop), no consequence, below the register's bar.
• Group-writable .local/.config/.cache and .zshrc on the host — checked during C-344's sweep; getent group views-deploy has no other members. Already recorded inside C-344 as a killed hypothesis.
• Guard-narrower-than-the-property (three versions of test_heartbeat_secret.py) — merged into C-336 as a second addendum during fix: the heartbeat URL leaves the command line (C-331, #423) #432. Same mechanism, new location.

Precedent check

C-339 registered an assistant-authored command that destroyed a production log. That is the precedent for tracking a workflow hazard here rather than treating it as something to remember.

Verification

• ruff check . → All checks passed
• pytest → PYTEST_EXIT=0, FAILED count: 0 — captured unpiped, two readers, per the entry's own mitigation
• docs/validate_docs.sh → PASSED
• Register: 345 IDs, 302 resolved, 40 open (0 T1, 4 T2, 11 T3, 19 T4, 6 deferred), 118 struck, tier sum == open count, header 1851 ≤ 3500

Note

#432 merged while this work was uncommitted on that branch — C-340 mechanism 2 exactly. Stashed, moved to a fresh branch off development, and verified the entry survived intact rather than assuming it had. That is the concern #426 exists to automate.

🤖 Generated with Claude Code

[Polichinel]

Ritual complete — /code-review medium → /review-diff → /register-risk

Docs-only, so the review was aimed at fact-checking rather than style — this register has a documented history of entries whose own claims were wrong (C-343 miscounted CI jobs; C-331 prescribed a defective fix). It found two, both mine.

1. "up to two months in production", attributed to C-343

C-343 says one month, twice over, and the script comment it draws from says the same. The two-month figure requires an unstated compounding worst case that C-343 never makes. Attributing it to that entry is a claim about C-343 that C-343 does not support.

Present in two places: C-345, and inside C-331 — where it had already shipped in #432. Both corrected, in the register and the changelog, with a visible correction note rather than a silent edit.

2. "two recorded false-readiness incidents that each cost a full day"

A grep of the register, the changelog and every post-mortem returns only the sentence making the claim. The incidents are real and known to the operator — they live in a cross-session memory file outside this repository — but nothing here records them or quantifies them.

Citing evidence a reader cannot find is precisely how a register stops being checkable, which is C-336's whole subject. Removed rather than softened. C-345's tier now rests on the one basis verifiable inside the repo: it fired twice in one session, stated as deliberately the only evidence cited. That those incidents went unrecorded is itself a gap, now flagged for whoever writes the next post-mortem.

Verified and left alone

• The shell claim is exactly right. Empirically confirmed: pytest -q | tail -2; echo $? yields 0 on a failing suite; set -o pipefail changes it to 1; the entry's proposed mitigation works.
• Header arithmetic — 345 IDs, 40 open, 0/4/11/19 tier split, 118 struck. All verified by direct count and by the four guard tests. The review also identified which claims are guarded and which are not: "40 open concerns", "0 Tier 1" and "6 deferred" are unguarded but manually correct.
• Cluster section — 11 rows, 2 struck, 9 open. Matches "nine open entries", "eleven rows" and "cheaper than nine separate ones" exactly. This section has gone stale twice before.
• Every cross-reference — C-339, C-330, C-337, C-343, C-341, C-336, C-344 — exists and is in the state C-345 implies.
• Changelog ordering — newest-first holds.

/register-risk — 0 new, 0 merged

Both findings are in-changeset defects, now fixed. The pattern — an entry making a claim the repository cannot support — is already C-336, which gained an addendum for it during #432. A third addendum for the same mechanism in the same week would be noise.

Verification

• ruff check . → All checks passed
• pytest → PYTEST_EXIT=0, FAILED count: 0 (unpiped, two readers — C-345's own mitigation)
• docs/validate_docs.sh → PASSED
• All 6 register/changelog/citation guards pass