docs: renumber the tracked-black-level ADR to 0028 - #616
Merged
Conversation
Two ADRs landed as 0027 within a day of each other from parallel branches: the SQM docs refresh (#606) and the optical-train docs (#608). The recurring cause is each worktree taking "next integer" off a main that does not yet have the other's ADR. Resolved with the agreed rules: the most-referenced file keeps the contested number, and latecomers move to the lowest globally-free slot. The FOV-gate ADR keeps 0027 -- it is linked from CONTEXT-MAP and referenced by ten bare `docs/adr/0027` mentions in the shipping code and tests of #609, and churning code comments is exactly what the tiebreak is meant to avoid. The tracked black level ADR moves to 0028, the lowest slot free across every branch and remote (0027 is also reserved by #571, which will need 0029 when it merges). Rename plus its three inbound references; the ADR's own text is untouched and carries no "renumbered from" breadcrumb, per the same rules. The bare "See ADR 0027" in the SQM glossary becomes an explicit link, since a bare number is what made this ambiguous to read in the first place. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
brickbots
marked this pull request as ready for review
August 15, 2026 02:01
brickbots
added a commit
that referenced
this pull request
Aug 18, 2026
0027 was already taken twice over. #608/#606 collided on it and were resolved by #616 (FOV gate keeps 0027, tracked black level moved to 0028); this branch, cut before that, carried a third 0027. Under the standing tiebreak the most-referenced ADR keeps the number, and the FOV gate wins by a wide margin -- CONTEXT-MAP.md, docs/ax/sqm.md, docs/ax/positioning.md, positioning/CONTEXT.md, ADR 0029 and two test modules all point at it, against three references here. The 2.6.2 test plan (P1.4) earmarked 0029 for this branch, but 0029 was taken by the lens-confidence ADR in the meantime, so this takes 0030 -- the lowest free number. Three inbound references updated. No content change; ADR titles in this repo carry no number, so the rename is the whole of it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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.
maincurrently has two ADR 0027s, landed a day apart from parallel branches:0027-fov-gate-derived-from-optical-train.md0027-tracked-black-level-supersedes-stored-bias.mdSame recurring cause as the earlier 0003/0004/0005/0010 and 0020 collisions: each worktree takes "next integer" off a
mainthat does not yet carry the other's ADR.Who keeps 0027
Applying the agreed rules — most-referenced keeps the contested number, latecomers move to the lowest globally-free slot,
git mvonly, no breadcrumb:CONTEXT-MAP.mdandpositioning/CONTEXT.md, and Derive field of view from the optical train (sensor × lens) #609 (open, mergeable, green) carries ten baredocs/adr/0027mentions acrossoptics.py,camera_profiles.py,camera_debug.py,solver.py,ui/callbacks.py,ui/menu_structure.pyand two test modules. Minimising churn in code comments is exactly what the tiebreak exists for.Worth flagging that this is the one case where the rules disagree with each other: #606 merged before #608, so a pure earliest-creation tiebreak would have gone the other way. Reference count is the primary rule and creation date only breaks ties, so 0027 stays with the FOV gate — but say the word if you would rather have it the other way round, it is a two-minute change while #609 is still open.
Changes
git mv docs/adr/0027-tracked-black-level-…→0028-tracked-black-level-…(content untouched, no "renumbered from" note).docs/ax/sqm.md×2 anddocs/ax/sqm/CONTEXT.md.See ADR 0027.becomes an explicit link — a bare number is what made this ambiguous to read in the first place.No code changes, and no ADR other than the renamed one is touched.
Verification
0027-tracked-black-levelremains anywhere in the repo.(…adr/NNNN-….md)link across all.md/.rstfiles resolves to a file that exists (script-checked, not eyeballed)..understand-anythingartifact mentions the old name, so nothing needs regenerating.Still outstanding (not fixed here)
fix/equipment-input-validation) carries a third0027-equipment-measurements-are-validated-floats.md. Per the documented practice for unmerged branches — same as the One sourceless object image per object + on-device image download (ADR 0018) #502/0018 case — it is left alone and resolved at merge; it should take 0029, since 0028 is now taken.0018collision.🤖 Generated with Claude Code