docs: publish the 2026-07-29 review, the ADR log, and retire ISSUES.md - #150
Merged
Conversation
Thirteen reviewers over disjoint slices of the workspace, forbidden from reading ISSUES.md and docs/reviews/ so the pass would be genuinely clean-slate, then an adversarial verification pass instructed to refute. 140 findings: 5 BUG, 64 DESIGN, 57 SMELL, 14 NIT. The document records its own reliability caveat, which is the reason to keep it: a 1-in-137 refutation rate is the rubber-stamping failure mode, so the five BUG-severity findings were re-verified by hand from the source rather than taken on a verifier's word. Every other review in docs/reviews/ is tracked; this one was left untracked when its findings were filed as issues #102-#126.
The 17 architecture decision records existed only on design/swift-binding, which descends from the pre-release development lineage. That lineage shares no history with origin/main, so nothing on it can reach the published repository through a pull request, and the decision log has been invisible from every branch that can. Copied verbatim, no edits: these are Accepted records and their bodies are frozen. A path checkout is used rather than a merge precisely because the two lineages have no common ancestor. The Swift binding itself remains stranded on that branch and still needs a route onto this lineage.
ISSUES.md had grown to 1868 lines across 119 numbered entries and could no longer be read whole by a session that also needed to hold the code — the 2026-07-29 review deliberately withheld it from its reviewers for that reason, which is an admission that the log had stopped being usable as an input. It also duplicated a tracker the project already used, under a second set of identifiers, and its statuses drifted: I149 and I150 were both still marked OPEN although I150 shipped in PR #128 and I149 shipped two commits ago. Of the 14 open and 3 deferred entries, 6 were already represented in existing issues (I147 in #116, I149 and I150 in #102, I151 in #107, I152 and I154 in #106). The remaining 11 were filed as #138-#148, each carrying its entry verbatim plus a header naming its original id and source review. I78 needed its header line preserved as well, because it recorded a correction that contradicts the caveat in its own body. The 83 entries marked fixed were not migrated. They describe completed work and remain in git history at 0ffe3bc. This is the real cost of the change and ADR 0017 records it as such: those entries are no longer discoverable by grep in a checkout, and some of them hold genuine decision rationale. The ~167 I<number> markers in source comments are deliberately left alone. Most refer to entries closed long ago with no GitHub equivalent, so rewriting them would delete provenance across 167 sites for no navigational gain. ARCHITECTURE.md gains a note explaining what they mean and how to retrieve the retired file; the live links in README.md, ARCHITECTURE.md and THEORY.md now point at docs/adr/ and the issue tracker instead.
Two things the docs review caught. The ADR log was ported from the retired lineage with its `ISSUES.md` citations intact, which is correct — an Accepted record is superseded, not edited — but README.md and ARCHITECTURE.md now route readers to `docs/adr/` as *the* decision log, so a reader following that pointer lands on citations with no way to resolve them. Record 0000 is the register overview rather than a decision, so it carries the breadcrumb for the whole log; 0017 records the same gap as an explicit consequence of the retirement it decides. Record 0000's claim that smaller decisions "live in ISSUES.md" was simply false as of the commit that deletes the file. The review record put the I143 regression 'five commits' before its own baseline; `git rev-list --count 04534c0..d87e670` is 2.
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.
Stacked on #149.
Brings three pieces of project documentation onto the published lineage. No code changes — 712 tests still pass.
What lands
docs/reviews/review-20260729-183138.md— the clean-slate deep review that every issue in the Trust-boundary hardening gaps found by the cross-cutting security sweep #102–Cleanups in the cross-subsystem gaps #126 range cites. Those issue bodies link to this file; until now the link 404'd on this lineage.docs/adr/0000–0017— the decision log as per-decision files plus a generatedREADME.mdindex. Previously the ADRs existed only on the orphaned dev lineage.On the
I<number>markers~167 code comments cite issue ids like
I61 (ISSUES.md, 2026-05-22). These were deliberately not rewritten: most refer to entries closed long ago with no GitHub equivalent, so a rewrite would delete provenance across 167 sites for no navigational gain.ARCHITECTURE.mdgains a note explaining how to read them, and the file remains readable atgit show 0ffe3bc:ISSUES.md.Review findings addressed
A docs review (Sonnet 5) checked dangling references, link integrity, ADR frontmatter validity, supersession symmetry, and factual claims. It confirmed all 18 ADR links resolve, ids are unique and match filenames, ADR 0017's issue-mapping claims are correct against live GitHub, and
git show 0ffe3bc:ISSUES.mdresolves. Two findings were real and are fixed in the final commit:ISSUES.mdas live. Their bodies are Accepted and are superseded rather than edited, so the citations stay — but record 0000 (the register overview, not a decision) claimed smaller decisions "live inISSUES.md", which the deleting commit makes false. 0000 now carries the resolution breadcrumb for the whole log, and 0017 records the dead-citation gap as an explicit consequence of its own decision.git rev-list --count 04534c0..d87e670is 2.adr_index.pyexits 0 (18 records) and regeneratesREADME.mdidentically, confirming the index was generated rather than hand-edited.