Skip to content

docs(adr): renumber the second ADR-0041 to 0042, and re-count the README - #509

Closed
Gerrrt wants to merge 1 commit into
mainfrom
gerrrt/adr-0041-collision
Closed

Gerrrt wants to merge 1 commit into
mainfrom
gerrrt/adr-0041-collision

Conversation

@Gerrrt

@Gerrrt Gerrrt commented Sep 18, 2026

Copy link
Copy Markdown
Owner

main is red on its own, and every open PR inherits it. make check-docs
reports three disagreements that no open PR introduced:

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: 0041-run-the-crs326-..., 0041-terminate-the-remote-path-...
  — renumber the one that landed second

Two sessions took the same ADR number, 56 seconds apart

Merged PR ADR-0041
2026-09-17 16:27:56 #491 the CRS326 on RouterOS
2026-09-17 16:28:52 #495 terminate the remote path

check_docs.py says to renumber the one that landed second, so the
remote-path ADR becomes ADR-0042 and the CRS326 one keeps 0041.

On renaming an ADR at all. ADR-0001 makes them immutable, and normally that
settles it. But immutability protects a decision's content and its identity,
and this identity was never unique — two files answering to one number is the
defect being repaired, not a decision being revised. No text inside either ADR
changed; only the filename, the title line and inbound links.

The bare mentions had to be split by hand

A global replace would have been wrong: ADR-0041 appears in prose on both
sides of the collision.

  • Stay 0041 (the CRS326): swap-the-switch.md ×5, hardware.md, ADR-0018,
    and one link label in roadmap.md.
  • Move to 0042 (the tunnel): open-the-remote-path.md,
    restore-the-firewall.md, ADR-0008, ADR-0011, ADR-0014, ADR-0022,
    network.md, observability.md, security.md, and roadmap's other mention.

roadmap.md is the only file citing both, so it was edited surgically rather
than swept.

Three of the moved mentions are firewall rule descriptions in
open-the-remote-path.md`WireGuard peers — ADR-0041`. Safe to change
because the tunnel does not exist: #436's jumpbox has not been built, so no
live rule on morpheus carries that string yet. Had it been built, this would
have needed a rule edit rather than a document edit.

Left alone deliberately

README.md:210 still says "39 architecture decision records". It is wrong
too, but check_docs.py's counted-claims pattern only matches {COUNT} ADRs,
so line 210 is unguarded and has been drifting silently for longer. Fixing the
number without fixing the blind spot would just hide it again — worth its own
issue.

Verification

make check-docs and make lint both pass on this branch. Found while
resolving a merge conflict on #501; kept separate from it so the NAS work is
not tangled with an ADR renumber.

🤖 Generated with Claude Code

`main` was red on its own. `make check-docs` reported three disagreements that
no open PR introduced, and every open PR inherited them.

TWO ADR-0041s. Two sessions each took the number, and both merged on
2026-09-17 within a minute of each other: PR #491 at 16:27:56 (the CRS326 on
RouterOS) and PR #495 at 16:28:52 (terminate the remote path). check_docs.py
says to renumber the one that landed second, so the remote-path ADR becomes
**ADR-0042** and the CRS326 one keeps 0041.

Renaming an ADR is normally forbidden — ADR-0001 makes them immutable — but
that protects a decision's content and its identity, and here the identity was
never unique to begin with. Two files answering to one number is the thing
being fixed, not a decision being revised. No text in either ADR changed.

Nine inbound references followed the rename, and the bare `ADR-0041` mentions
had to be split by hand rather than swept: `swap-the-switch.md` (5),
`hardware.md`, `ADR-0018` and one label in `roadmap.md` all mean the CRS326
and keep 0041, while `open-the-remote-path.md`, `restore-the-firewall.md`,
ADR-0008, ADR-0011, ADR-0014, ADR-0022, `network.md`, `observability.md`,
`security.md` and roadmap's other mention mean the tunnel and move to 0042.
`roadmap.md` is the only file citing both.

Three of the moved mentions are firewall rule descriptions in
`open-the-remote-path.md` — `WireGuard peers — ADR-0041`. Safe to change
because the tunnel is not built: #436's jumpbox does not exist, so no live rule
carries that string yet.

THE README COUNTS. `README.md:95-96` claimed 41 ADRs and 26 runbooks against 42
and 27 on disk. ADR-0042 and `swap-the-switch.md` / `open-the-remote-path.md`
landed without them. Note `README.md:210` still says "39 architecture decision
records" and is not covered by check_docs.py's pattern, which only matches
`{COUNT} ADRs` — left alone here, and worth its own issue.

`make check-docs` and `make lint` both pass on this branch.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Gerrrt added a commit that referenced this pull request 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>
@Gerrrt

Gerrrt commented Sep 18, 2026

Copy link
Copy Markdown
Owner Author

Duplicate. Closing in favour of
#503, which was opened 90 minutes
earlier.

Three sessions independently produced this fix — #503 at 23:36:31Z, #504 at
23:37:07Z, this one at 01:05:22Z — and all three are byte-identical: the
same 12 files, the same +27/−27, and the same 54 content lines once blob hashes
and hunk offsets are set aside. Same renumber of the remote-path ADR to 0042,
same split of the bare ADR-0041 mentions between the tunnel and the CRS326,
same two README counts. All three are green and mergeable.

That three sessions each spent a full run on the same 54 lines is the finding
worth keeping, not the diff. A red main is visible to every session at once,
so every session picks it up at once; the collision is structural rather than
anybody's mistake.

For whoever lands #503: it is the earliest and is mergeable=clean with all
three checks passing. #504 is the
other duplicate and wants closing too — left alone here rather than closing
another session's PR unasked.

Context this was found from: main has been red since the two ADR-0041 files
landed 56 seconds apart on 2026-09-17, and every open PR inherits the three
check-docs disagreements — including
#501, whose only failing check is
exactly these three lines and nothing of its own.

@Gerrrt Gerrrt closed this Sep 18, 2026
@Gerrrt
Gerrrt deleted the gerrrt/adr-0041-collision branch September 18, 2026 01:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant