docs(runbook): four rules not three, and the switch step §0 never had (#413) - #501
Merged
Merged
Conversation
…#413) build-the-nas.md §0 is complete and §1–§7 is blocked on two drives that have not been delivered. So this corrects the documents the build will be run from rather than advancing the build. Four things were wrong, and three of them were files contradicting themselves. THE RULE COUNT. Four passes were created on 2026-09-16; §0.5's heading, its table and two other documents still said three. §0.5 now lists four rows, one per port, and carries each rule's description — which §0.6 has started matching on. network.md said "the three rules created that day" seven lines above a bullet correctly saying four. security.md was worse: "Neither is created yet; both wait on the host that would use them", of two decisions, only one of which is still pending. Checked on the live ruleset: ADR-0016's passes exist, ADR-0035's pass to the Hue bridge genuinely does not, so the sentence is split rather than replaced. stacks/media/README.md called the Hicks access "the one rule" and it is two. THE RECORDED PROOF. §0.6's evidence was "167-168 before 169 on igc0.99, 194-195 before 196 on igc0.50". Those numbers are right for `pfctl -sr | grep -n` and wrong for `pfctl -sr -vv`, which numbers the same four rules @148, @149, @175 and @176 — both read off the live ruleset in one invocation, the two disagreeing by however many scrub rules precede the filter set. The command §0.6 needs is the one the numbers do not match, because the tripwire check reads a counter and counters only come from -vv. §0.6 now asserts the invariant by rule description and says to read the order rather than the numbers. The tripwire wording separates packets, which must be zero, from evaluations, which only climb: 118,621 then 128,629 with nothing wrong on either day. THE SWITCH STEP. §0 never said the port had to move from VLAN 30 to VLAN 40, nor which port it was. Added as §0.2b — before §0.3, because a static on a port still carrying VLAN 30 is a host with no gateway and makes §0.4's reservation and §0.5's four rules silently pointless. Lettered rather than renumbering §0.3 onward, because ADR-0016 and ADR-0040 both cite §0.5 by name and ADRs are immutable. THREE GAPS THAT WOULD BITE MID-BUILD. §2 offered SSH as an alternative to the console; TrueNAS ships it disabled and §0.5 says the port-22 pass is inert. §6 said "deploy the stack" with no command. §6's QSV check was `ls -l /dev/dri` on the host, which re-confirms the half that was never in doubt — ADR-0040's reopen condition is whether a container reaches the iGPU, so the check now runs inside it and looks at the supplementary groups group_add exists to set. §7's 9100 bullet read as a step that would pass, when nothing in §1–§6 stands up a listener and #256 has yet to settle its shape. Also adds the /stacks/media Dependabot entry. ADR-0040 keeps the media stack in this repository so that "Dependabot, the digest pins and make validate keep reaching it", and build-the-nas.md §6 and the stack README repeat the claim. The pins and make validate did reach it; Dependabot did not. Verified against the live firewall from morpheus: all four passes above Block access to CasaBonita on their interfaces, 443 still refused from Winterfell, igc0.40 tripwire zero packets. Refs #413 Closes #481 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
main landed #481's switch step (PR #494) while this branch was doing the same work. Resolved by taking main's §0.2b wholesale — it is the better section: it has the cable-colour re-patch (ADR-0009), the TrueNAS test-and-confirm rollback that explains *why* the order matters, and the port 1 / port 3 exclusions. This branch's own §0.2b is dropped entirely. Four conflicts, each resolved to keep both intents: - Header "You will need": main's `neo` web UI and yellow lead, plus this branch's correction that smaug's web UI cannot run §2 or §6 and SSH is off. - Status block: main's, which carries the §0.2b line and the note that it is the one step in §0 without a date. - §0.2b: main's, plus one sentence this branch had and main lacks — that the section must stay lettered, because renumbering §0.3 onward would move §0.5, which ADR-0016 and ADR-0040 both cite by name and ADRs are immutable. - §7: main's port-15 bullet, which is better worded (read in the switch UI, not inferred from the host having an address), plus this branch's #256 cross-reference on the 9100 bullet and the packets-versus-evaluations split on the tripwire. main's §0.5 still said "Create the three rules", so this branch's rule-count correction is unaffected and still needed. NOTE: main is red independently of this merge — README.md:95-96 claim 41 ADRs and 26 runbooks against 42 and 27 on disk, and two ADR-0041 files exist (0041-run-the-crs326-... and 0041-terminate-the-remote-path-...). None of those files are touched by this branch. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
6 tasks
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>
This was referenced Sep 18, 2026
Two conflicts, resolved in opposite directions. docs/security.md — took main's wholesale. It rewrites the paragraph into two labelled halves, "CasaBonita's exist" and "Skids' does not exist", adds that the passes were verified in position with pfctl rather than read off the web UI, notes that the 22 is inert under ADR-0040, points at network.md as the authority for the list, and cites #134 for the Skids pass. That is strictly better than this branch's split of the same sentence, so this branch's version of security.md is dropped entirely. docs/network.md — kept this branch's. main corrected the first bullet's count from three to four; this branch removes the count from that bullet altogether and leaves the next one as the sole authority, because the count being stated twice is what let the two drift apart in the first place. Correcting both leaves the drift vector in place. This side also carries the port-15 bullet. NOTE: check-docs is still red on this branch, entirely from main — the two ADR-0041 files and README.md's ADR and runbook counts. PR #509 fixes those; nothing here can. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
3 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
build-the-nas.md§0 is complete and §1–§7 is blocked on two drives that havenot been delivered — the last carrier event is 2026-09-11 and the estimated
window (Mon Sep 14 – Thu Sep 17) has now lapsed. So this corrects the documents
the build will be run from rather than advancing the build.
What this PR still contributes
§0.6's recorded proof pointed at the wrong command — the core of it
The evidence read "167–168 before 169 on
igc0.99, 194–195 before 196 onigc0.50". Those are right forpfctl -sr | grep -nand wrong forpfctl -sr -vv, which numbers the same four rules@148,@149,@175,@176. Both readings came off the live ruleset in one invocation — theydisagree by however many
scrubrules precede the filter set, because-vvnumbers each ruleset from zero while
grep -ncounts output lines.The command §0.6 needs is the one the numbers do not match, because the
tripwire check reads a counter and counters only come from
-vv. §0.6 nowproves position by rule description, with a command verified against
morpheus, and says to read the order rather than the numbers. §0.5 carrieseach rule's description because §0.6 matches on it.
The tripwire wording now separates packets, which must be zero, from
evaluations, which only climb — 118,621, then 128,629, then 129,266, with
nothing wrong on any reading.
§0.5's count, and
stacks/media/README.md§0.5 was headed "Create the three rules" over a three-row table while the
callout at the top of the same file said four. Now four rows, one per port.
stacks/media/README.mdcalled the Hicks access "the one rule"; it is two.network.md— the count now lives in one bulletAdopted from #502, which had the better answer: two adjacent bullets both
counted the passes and drifted apart, so the first no longer counts them at all
and the second is the authority. Correcting both would have left the drift
vector in place. Also carries the port-15 record.
Three gaps that would have bitten mid-build
disabled, §0.5 says the port-22 pass is inert, and
10.0.40.30:22is closedfrom the monitoring host.
ls -l /dev/drion the host, which re-confirms thehalf that was never in doubt. ADR-0040's reopen condition is whether a
container reaches the iGPU, so the check now runs inside it and inspects
the supplementary groups
group_addexists to set.9100bullet read as a step that would pass, when nothing in §1–§6stands up a listener and Add the scrape path for a host that pushes nothing #256 has yet to settle its shape.
One claim made true rather than softened
ADR-0040 keeps
stacks/mediahere so that "Dependabot, the digest pins andmake validatekeep reaching it", and §6 and the stack README repeat it. Thepins and
make validatedid reach it; Dependabot did not — there was no/stacks/mediaentry, so the Jellyfin digest pin was rotting unattended.One sentence kept from this branch's own §0.2b
main's §0.2b (PR #494) is the better section and is what survives — cable
colour, the TrueNAS test-and-confirm rollback, the port 1 / port 3 exclusions.
This branch added one thing it lacked: that the section must stay lettered,
because renumbering §0.3 onward would move §0.5, which ADR-0016 and ADR-0040
both cite by name while ADRs are immutable (ADR-0001).
What this PR dropped to peers
security.md— main's rewrite into "CasaBonita's exist" / "Skids' doesnot exist" is better than this branch's split of the same sentence, and was
taken wholesale. Both had independently found that the sentence covered two
decisions and only one half had gone stale; checked against the live ruleset,
ADR-0035's pass to
10.0.20.104genuinely still does not exist.CI
check-docsis red on this branch entirely frommain— twoADR-0041files and
README.md's ADR and runbook counts. Nothing here causes or can fixit; #509 does. This PR goes green
once that merges.
Re-read from
morpheusbefore pushing: four passes above Block access toCasaBonita on their interfaces,
443still refused from Winterfell,igc0.40tripwire zero packets.Scope
Refs #413— the build is not done; the drives are still in transit and§1–§7 is untouched.
Found and left out, worth their own issues:
make backup STACK=mediadiestoday for want of a backup sentinel,
scripts/pin-digests.shonly ever readsstacks/observability, andREADME.md:210says 39 ADRs in a spotcheck_docs.pydoes not guard.🤖 Generated with Claude Code