Conversation
… counts
`main` is red. Three failures, all from two PRs merging within a minute of each
other without seeing one another:
README.md:95 claims 41 ADRs; the repository has 42
README.md:96 claims 26 runbooks; the repository has 27
ADR-0041 is claimed by 2 files — renumber the one that landed second
#491 gave ADR-0041 to *Run the CRS326 on RouterOS* at 23:27:57Z and #495 gave
the same number to *Terminate the remote path on the lab* at 23:28:52Z. The
ADR-numbering assertion is exactly the check for this; it fired one merge too
late, because each branch was green against a `main` that did not yet hold the
other.
The remote-path ADR landed second, so it becomes **ADR-0042** — which is what
`check_docs.py` asks for by name. Renumbered: the filename, its own H1, eleven
links that targeted it, and thirteen bare `ADR-0041` mentions that meant it.
Every remaining `ADR-0041` in the tree is the CRS326 one, checked individually
rather than by pattern, because the two ADRs shared a number and a
search-and-replace would have renumbered both.
Two of the bare mentions are inside other ADRs' amendment blockquotes (ADR-0011,
ADR-0014). Updating a pointer to a renumbered file is not revising a decision,
so ADR-0001's immutability is not in question — and leaving them would be
leaving a reference to a number that now means something else.
`open-the-remote-path.md`'s pfSense rule descriptions change with it
(`WireGuard peers — ADR-0042`). Safe: the tunnel does not exist, its runbook is
gated on the jumpbox of #436, and `restore-the-firewall.md` still counts the
tripwires as though it were unbuilt.
The two README counts are the arithmetic consequence of the same two merges —
one ADR and two runbooks arrived, and the sentence that counts them did not
move.
Refs #491 #495
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Four inbound passes were created for `smaug` on 2026-09-16 — Hicks to `443` and to `8096`, `10.0.99.20` to `9100` and to `22` — and prose still said three. `build-the-nas.md` §0.5 was headed "the three rules" over a three-row table while the status callout at the top of the same file said four were created. The table now has four rows, one rule per port, and the section says why the ADR's count was three: that table wrote the Hicks pass as a single row with a port list, so three counted rows rather than rules. Updated rather than marked as the as-planned version. §0.1 sets that precedent for a BIOS procedure kept "for the next machine", but these are four specific rules for one host and there is no next machine for them — a runbook should instruct what exists. `network.md` stated the count in two adjacent bullets, which is the drift vector rather than an instance of it. #493 corrected the first bullet from three to four while this branch was open; this goes one step further and stops it counting them at all. The next bullet enumerates all four and is the authority. `security.md` needed the same fix and #493 made it better than this branch had: it separates CasaBonita's four created passes from Skids' uncreated one, records that position was verified with `pfctl` rather than the web UI, and cites ADR-0040 for the inert `22`. That version is kept and this branch's edit to the file is dropped. ADR-0016 and ADR-0040 are untouched: ADR-0001 makes them immutable, ADR-0040 already carries the ports correction, and ADR-0016's "three" is a true statement about what it wrote. `roadmap.md` already had it right. No `check_docs.py` guard. `firewall-claims.yaml` cannot source this count — its own header says it is "deliberately NOT a list of what each segment can reach", that host-and-port exceptions live in `network.md` instead, and that rule bodies are not published there; it is also `--derive`d rather than authored. These four passes exist in no machine-readable form in the repository, and the checker that does read rule bodies asks the live firewall, which ADR-0026 puts outside CI by design. The fix available instead is the one applied here: state the number once per document, next to the thing it counts. Refs #413 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
57e1bfd to
9ed0133
Compare
#502's CI fails on three disagreements that are main's, not this branch's: README's ADR and runbook counts, and two files both claiming ADR-0041. #504 fixes all three and is green. Merged here so this PR can be verified on its own merits; the diff collapses back to two files once #504 lands on main.
CI: the failure was
|
The count was stated in two adjacent bullets and they drifted apart — one said three long after four existed, which is how #501 found it. Correcting both would have left the drift vector in place, so the first bullet no longer counts them at all and the second is the authority. Taken from #502, which reached the same three files independently and had the better answer on this one point. Refs #413 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
Superseded by #501, which reached Closing this rather than #501 on content coverage alone — not because it Both PRs also independently found the Two sessions doing this twice is the cost worth noting, not the prose. |
1 participant
Four inbound passes were created for
smaugon 2026-09-16 — Hicks to443andto
8096,10.0.99.20to9100and to22— and prose still said three.Note
Narrowed while open. This started as three files. #493 merged in the
meantime and fixed
security.mdbetter than this branch had, so that edit isdropped and its version kept. What remains is §0.5, which nothing else has
touched, and one line in
network.md.build-the-nas.md§0.5 — updated to four, not marked as-plannedIt was headed "Create the three rules" over a three-row table while the status
callout at the top of the same file said four were created. The table now has
four rows, one rule per port, and the section says why the ADR's count was three:
that table wrote the Hicks pass as a single row carrying a port list, so
three counted rows rather than rules.
The alternative was §0.1's precedent — a section kept as written "for the next
machine" with reality in the callout. Rejected here: §0.1 describes a procedure
that generalises, while §0.5 is four specific rules for one host, and there is no
next machine for them. A runbook should instruct what exists.
network.md— the count was stated twiceTwo adjacent bullets in the CasaBonita notes said "the three rules created that
day" and then "four host-scoped, port-scoped passes". #493 corrected the
first to "four" while this branch was open. That fixes the instance; this fixes
the vector — the first bullet no longer counts them at all, and the second
enumerates all four and stays the authority. Two adjacent statements of one
number is how this drifted to begin with.
security.md— dropped, and whyThis branch had its own fix for the same defect there (it said ADR-0016 "writes
three passes" and then "Neither is created yet", false since 2026-09-16).
#493's version is better and is kept: it separates CasaBonita's four created
passes from Skids' single uncreated one, records that position was verified with
pfctlrather than the web UI, and cites ADR-0040 for the inert22.Left alone, deliberately
carries the ports correction, and ADR-0016's "three" is a true statement about
what it wrote.
roadmap.mdalready had this right — "ADR-0016 wrote down three rules …Four exist since 2026-09-16" — and needed no change.
On a
check_docs.pyguard: not fromfirewall-claims.yamlThe suggestion cannot be implemented from that source, and the file says so
itself:
It is also
--derived frompfctlrather than authored, so it cannot be widenedby hand. These four passes exist in no machine-readable form in the
repository — the only other mention is a comment in
stacks/media/compose.yaml— and the checker that does read rule bodies,
check_firewall_claims.py, asksthe live firewall, which ADR-0026 puts outside CI by design.
So there is no source to guard against. The fix that is available is the one
this PR applies, and
check_docs.py's own comments say it is always on thetable: state the number once per document, next to the thing it counts.
A self-consistency assertion — heading count == rows in the table below it —
would be implementable, but it would be the first assertion scoped to a single
heading in a single runbook rather than to the estate, and it would make the
eleventh assertion, which cascades into README's own guarded count of them.
Worth a separate discussion rather than smuggling in here.
Blast radius
secrets/*.sops.yamlDocumentation only. The four rules described have existed since 2026-09-16; this
changes how many the prose says there are, not how many there are.
Verification
Important
mainis red independently of this PR, so CI here fails until it isfixed:
#491 and #495 each added an ADR-0041 fifty-five seconds apart, neither seeing
the other. #504 fixes it; merge that first and this goes green.
Refs #413
🤖 Generated with Claude Code