docs(adr): reconcile the register — 13 unmerged ADRs into one contiguous sequence - #644
Open
seanspeaks wants to merge 1 commit into
Open
docs(adr): reconcile the register — 13 unmerged ADRs into one contiguous sequence#644seanspeaks wants to merge 1 commit into
seanspeaks wants to merge 1 commit into
Conversation
…sequence The register had eight number collisions across six open PRs, four against numbers already merged to next. Three different decisions were all titled ADR-027 (next's SSM Parameter Offload, #624's Configuration & Secrets Model, #620's Integration Versioning) and a fourth reused ADR-010 (#545's Decouple AWS, against next's Reporting as an Admin Operation). ADR-014 created one register but no way to CLAIM a number, so every author picks max+1 in isolation and collides with branches they cannot see. Each PR is internally consistent; the conflict only exists between them. This PR moves every unmerged ADR into one sequence so the feature branches can drop their doc files and carry only code. Assignment: uncontested claims keep their numbers (032/033/034 from #641/#640/#643); contested ones re-assign by PR age (#545 < #619 < #620 < #624) with clusters kept contiguous. 028-030 are filled rather than left as holes — a number that has only ever existed in an unmerged branch is not yet claimed. Result is 001-041 with no gaps and no duplicates. 028, 029 Multi-Provider Support, Decouple AWS SDK from core <- #545 (was unnumbered, 010) 030 Integration Versioning <- #620 (was 027) 032-034 unchanged <- #641, #640, #643 035-037 App Init, Skills, Agent Pipeline <- #619 (was 028-030) 038-041 Configuration & Secrets cluster <- #624 (was 027-030) Cross-references were rewritten per source PR, because the same token means different things in different branches: ADR-010 in #624/#641 is next's merged Reporting ADR and is left alone, while ADR-010 in #545 is its own Decouple-AWS ADR and becomes ADR-029. Also completes two things ADR-014 mandated but did not finish: ADR-004 and ADR-005 still used the '## Status' heading form, and ADR-005 still had the old 'Architecture Decision Record:' title. Both now carry the standard block. Deciders were unrecorded for those two and are marked TBD rather than invented. ADR-014 gains an amendment specifying that numbers are claimed at PR-open time and enforced by CI, with the reasoning for not deferring assignment to merge time, plus the rule that merged numbers are permanent while unmerged ones are not yet claimed. .github/workflows/adr-number-check.yml enforces it. README.md and website/roadmap/data/adrs.json are regenerated from the files. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
There was a problem hiding this comment.
Claude Code Review
Claude Code Review is paused for this repository. To reconnect it, an admin of this repository's GitHub organization (or the account owner, for personal repositories) who can also manage your Claude organization's Code Review settings needs to re-link GitHub in Code Review settings. This is a one-time step.
Tip: disable this comment in your organization's Code Review settings.
✅ Deploy Preview for friggframework-org ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
This was referenced Aug 31, 2026
|
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.
The problem
The register has eight number collisions across six open PRs, four of them against numbers already merged to
next. Three different decisions are currently titledADR-027:nextADR-014 created one register but no way to claim a number. Every author picks
max + 1in isolation, so each PR is internally consistent and only collides with branches its author cannot see. Nothing catches it.What this does
Moves every unmerged ADR into one sequence, so the feature branches can drop their doc files and carry only code.
Assignment rule: uncontested claims keep their numbers; contested ones re-assign by PR age (#545 < #619 < #620 < #624), with clusters kept contiguous.
docs/architecture/ADR-MULTI-PROVIDER-SUPPORT.md)Result: 001–041, no gaps, no duplicates. 028–030 are filled rather than left as holes — a number that has only ever existed in an unmerged branch is not yet claimed.
#545's two ADRs also move out of
docs/architecture/, which ADR-014 retired for ADRs; they were the last two left there.Cross-references
Rewritten per source PR, because the same token means different things in different branches:
ADR-010in docs(adr): Configuration & Secrets — 027 model · 028 provider · 029 management · 030 docs/maturation #624 and docs(adr): ADR-032 integration deletion data cleanup #641 refers tonext's merged Reporting as an Admin Operation (admin API key) → left aloneADR-010in feat: provider plugin architecture + Netlify adapter #545 refers to its own Decouple AWS ADR → rewritten to ADR-029Both intra-cluster link sets (#619's three, #624's four) were remapped, including two compound references (
ADR-027/028) that a naïve word-boundary pass would have half-rewritten.Two things ADR-014 mandated but didn't finish
ADR-004 and ADR-005 still used the
## Statusheading form, and ADR-005 still had the old# Architecture Decision Record:title. Both now carry the standard block. Deciders were unrecorded for those two and are markedTBDrather than invented — worth someone filling in.Preventing recurrence
ADR-014 gains an amendment: numbers are claimed at PR-open time and enforced by CI, not assigned at merge. It records why deferring to merge is worse (the file is named wrong for the whole review, cross-links can't be written, and someone repeats this reconciliation by hand at every merge), and the rule that merged numbers are permanent while unmerged ones are not yet claimed.
.github/workflows/adr-number-check.ymlenforces it: on any PR touchingdocs/architecture-decisions/**it checks the claimed numbers againstnextand against every other open PR, verifies filename matches heading, and reports the next free number on failure. It re-runs whennextmoves so the loser of a simultaneous claim goes red before merge.This is the one non-docs file here — drop that commit if you'd rather keep this docs-only, though then nothing stops the next collision.
Follow-up on the source PRs
Each should drop its ADR files and carry only code; I'm commenting on them individually. Nothing here touches their code, and no branch has been force-pushed.
README.mdandwebsite/roadmap/data/adrs.jsonare regenerated from the files rather than hand-edited.🤖 Generated with Claude Code