docs(adr): untrack the 104th releases file, unlink its ADR 0076 citation, and record D6 - #241
Open
wshallwshall wants to merge 1 commit into
Open
docs(adr): untrack the 104th releases file, unlink its ADR 0076 citation, and record D6#241wshallwshall wants to merge 1 commit into
wshallwshall wants to merge 1 commit into
Conversation
… left on purpose PR #235 removed 103 files. A 104th, docs/releases/HANDOFF-232-router-steps.md, entered main via PR #225 (ADR 0076 Amendment D, BACKLOG #232) WHILE #235 was open, so #235 -- which removed 101 paths named INDIVIDUALLY -- could not have covered a file created after its commit was built. A .gitignore rule does not untrack, so /docs/releases/ left it behind and the directory came back holding exactly one file. Untracked here, with custody taken by the vault FIRST (09e3cd4e, pushed) as with the other 103. No new ignore rule was needed: /docs/releases/ already covers the path once nothing under it is tracked, which is now true. Verified against a tracked-files-only `git archive` export -- the directory is empty in a fresh checkout. THE SHAPE IS THE LESSON, not the file. A removal that ENUMERATES paths has a window, open for exactly as long as the PR is, during which the directory it is clearing can be refilled. Nothing detected this: it surfaced only because a merge conflict forced a re-read of the tree. Recorded in ADR 0160 so a future phase re-checks the directory at MERGE time rather than trusting the file list computed when the branch was cut. ADR 0076's link to that file is unlinked to its plain name -- the same treatment the other 37 got, and necessary here because untracking it would otherwise leave a 404 in a document that stays. NEW SECTION D6 -- CONSIDERED AND LEFT. Three sets were found during Phase 1 and deliberately not acted on. They are recorded because a sweep run against D1 surfaces all three again, and an unrecorded "we looked and left it" is indistinguishable from an oversight: * 11 files citing docs/releases/ in PROSE. Not links; nothing 404s. Provenance reads true after the file moves. ADR 0160's OWN citations must never be "cleaned" -- it is the ADR that removed the directory and the paths are its evidence. * 22 handoff DOCUMENTS outside docs/releases/. A name-based sweep reports 155; 133 of those are benchmark DATA files that merely sit inside HANDBACK_* directories, so the naive number overstates it six-fold. The bench handoffs carry the measurement narrative for the data beside them, and removing them would strip rationale from records that stay. * Unanchoring /HANDOFF-*.md. REJECTED, and the reasoning is kept in .gitignore beside the rule so it is refuted where it will next be proposed: the two locations that matter (repo root, docs/releases/) are both already covered, and an unanchored pattern would fail closed on docs/benchmarks/, where 21 handoffs are tracked ON PURPOSE and a new benchmark run legitimately produces another. Verified: ruff check + format clean (1044 files), 53 doc guards pass, link guards re-run against a tracked-files-only export (17 passed), backlog_status_check 337 items, all 155 ADR table rows uniform at 5 cells.
wshallwshall
enabled auto-merge (squash)
August 6, 2026 14:02
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
1 participant
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.
Closes the follow-ups left open by #235. 5 files, +51 -202. Docs-only.
THE 104TH FILE. docs/releases/HANDOFF-232-router-steps.md landed via PR #225 (ADR 0076
Amendment D) WHILE #235 was open, so #235's removal of 101 specific files never covered
it -- and gitignore does not untrack. It is now untracked. No new ignore rule is needed:
/docs/releases/ covers it once nothing under it is tracked, which this makes true.
Verified on a
git archiveexport -- the directory is EMPTY in a fresh checkout.ADR 0076:667 linked to that file and is unlinked here. Required, not cosmetic: untracking
without it leaves a 404 in a document that stays.
CUSTODY FIRST, as with the other 103: vault commit 09e3cd4e took custody BEFORE the file
left the public tree. That half is already pushed and is independent of this branch.
⭐ THE UNANCHOR PROPOSAL IS REFUTED, REVERSING THE AUTHOR'S OWN EARLIER RECOMMENDATION.
Dropping the leading slash from /HANDOFF-*.md was pitched twice as a cheap tightening. It
is the wrong fix:
covered. The case cited as proof the gap was real (docs(adr): ADR 0076 Amendment D -- the route row, and the CLAUDE.md section 12 carve-out (BACKLOG #232) #225 dropping a handoff into
docs/releases/) is closed by the DIRECTORY rule the moment nothing is tracked there,
which this commit makes true. The argument rested on a gap its own fix shuts.
tracked ON PURPOSE and a new benchmark run legitimately produces another.
The reasoning is written into .gitignore BESIDE the rule, not only into the ADR, so it is
refuted where it will next be proposed.
D6 RECORDS THE REMAINING TWO AS CONSIDERED-AND-LEFT, with their traps:
citations must never be "cleaned" -- it is the ADR that removed the directory and
those paths are its evidence.
benchmark DATA files inside HANDBACK_* directories, so the naive number overstates it
6x. That number is the trap and it is now written down.
VERIFIED: based on 123d08b (current main), merge-tree clean. ruff check + format clean
(1044), 53 doc guards, link guards re-run against a tracked-files-only export (17 passed),
backlog_status_check 337 items, all 155 ADR rows uniform at 5 cells. Full pre-commit ran;
no --no-verify.