docs(adr): repair the decisions index — layout, and one row that described the rejected option - #153
Merged
h1d3mun3 merged 2 commits intoJul 28, 2026
Conversation
A blank line inside a GitHub-flavoured Markdown table ends it. Three of them — after 0012, after 0014 and after 0015 — meant the index rendered as FOUR separate tables, each re-drawing the "ADR | Decision" header, with 0015 and 0016 as one-row tables of their own. The rows themselves were fine; only the separators were wrong. Removing the three blank lines is the whole fix. All 16 ADR files have an index row and all 16 rows point at a file that exists — verified rather than assumed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The index said cmd_up_macos "writes the now-generic onboarding stub only when
the file is absent". That is not what it does, and it is not a slip — it is
precisely the alternative ADR-0012 exists to rule out.
implementation augur:3931 if $_fresh_clone; then
its comment augur:3921 "WRITE-ONCE, gated on _fresh_clone … NOT on the
file's absence"
ADR-0012 § :85 "only when this `up` just cloned the VM"
ADR-0012 § :93 an existence check is "a weaker check
masquerading as the same thing"
The distinction is the whole point: the base VM is a long-lived mutable disk
that can accumulate its own stale ~/.claude.json between builds, so an
existence check finds *a* file on a fresh clone and silently inherits it into
every new project. An index that states the rejected option as the implemented
one sends a reader looking for a bug that is not there — or, worse, invites
someone to "simplify" the gate back into the defect.
Corrected to match, with the reason, so the row survives the next person who
wonders why it is not just `[ -f ]`.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2 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.
Two independent fixes to
docs/decisions/README.md, kept as separate commits so either can bedropped. Neither depends on the egress audit.
1. The index table was split into four
A blank line inside a GitHub-flavoured Markdown table ends it. There were three — after 0012,
after 0014 and after 0015 — so the index rendered as four separate tables, each re-drawing the
ADR | Decisionheader, with 0015 and 0016 as one-row tables of their own.The rows themselves were fine; only the separators were wrong. Removing the three blank lines is the
entire fix.
Verified rather than assumed: all 16 ADR files have an index row, and all 16 rows point at a file
that exists.
2. The 0012 row described the approach 0012 rejects
The index said
cmd_up_macos"writes the now-generic onboarding stub only when the file isabsent". That is not what it does — and it is not a slip, it is exactly the alternative ADR-0012
exists to rule out:
augur:3931—if $_fresh_clone; thenaugur:3921— "WRITE-ONCE, gated on_fresh_clone… NOT on the file's absence"upjust cloned the VM"The distinction is load-bearing: the base VM is a long-lived mutable disk that can accumulate its
own stale
~/.claude.jsonbetween builds, so an existence check finds a file on a fresh clone andsilently inherits it into every new project — which is the bug 0012 was written about.
An index that states the rejected option as the implemented one sends a reader hunting for a defect
that is not there, or — worse — invites someone to "simplify" the gate back into the defect. The row
now matches the code and carries the reason.
Scope
docs/decisions/README.mdonly. No code, no invariant, no snapshot. Found while auditing thedecisions index during the #124/#135 series; the layout half was already on the known-issues list.
🤖 Generated with Claude Code