Skip to content

docs(adr): repair the decisions index — layout, and one row that described the rejected option - #153

Merged
h1d3mun3 merged 2 commits into
stack/virtiofs-staleness-2026-07from
docs/decisions-index-layout
Jul 28, 2026
Merged

docs(adr): repair the decisions index — layout, and one row that described the rejected option#153
h1d3mun3 merged 2 commits into
stack/virtiofs-staleness-2026-07from
docs/decisions-index-layout

Conversation

@h1d3mun3

Copy link
Copy Markdown
Owner

Two independent fixes to docs/decisions/README.md, kept as separate commits so either can be
dropped. 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 | 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
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 is
absent"
. That is not what it does — and it is not a slip, it is exactly the alternative ADR-0012
exists to rule out:

implementation augur:3931if $_fresh_clone; then
its own comment augur:3921"WRITE-ONCE, gated on _fresh_cloneNOT 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 load-bearing: 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 — 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.md only. No code, no invariant, no snapshot. Found while auditing the
decisions index during the #124/#135 series; the layout half was already on the known-issues list.

🤖 Generated with Claude Code

h1d3mun3 and others added 2 commits July 28, 2026 22:26
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>
@h1d3mun3
h1d3mun3 merged commit ed44e81 into stack/virtiofs-staleness-2026-07 Jul 28, 2026
2 checks passed
@h1d3mun3
h1d3mun3 deleted the docs/decisions-index-layout branch July 28, 2026 13:30
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