Skip to content

πŸ“ docs(adr): ADR consistency cleanup β€” numbering, nav, format, cross-refs#422

Merged
sodre merged 4 commits into
mainfrom
fix/adr-numbering-collision
Jun 12, 2026
Merged

πŸ“ docs(adr): ADR consistency cleanup β€” numbering, nav, format, cross-refs#422
sodre merged 4 commits into
mainfrom
fix/adr-numbering-collision

Conversation

@sodre

@sodre sodre commented Jun 12, 2026

Copy link
Copy Markdown
Member

Summary

This PR collects four commits of ADR consistency cleanup on main:

  1. Resolve the duplicate ADR-121 β€” two Accepted ADRs both claimed number 121. Native-sync keeps 121 (earlier file, referenced externally by CLAUDE.md); the IAM policy-rename ADR is renumbered 121 β†’ 124 (next free number after 123-local-secondary-indexes). Structural collision fix only β€” no decision content changed, consistent with the ADR immutability rule.
  2. Normalize ADR-121 (native-sync) status header β€” it used a ## Status heading with the value on a separate line; normalized to the **Status:** / **Date:** inline format mandated by ADR-000 (Date 2026-02-02, from the file's creation commit).
  3. Add ADRs 114-124 to the mkdocs navigation β€” the nav previously stopped at ADR-113, leaving 114-124 unreachable from the docs site. Added thematic groups covering 114-124 and reflecting the corrected numbering.
  4. Resolve cross-ADR consistency issues surfaced by /adr consistency:
    • ADR-107: annotate its partial supersession by ADR-117. Two Accepted ADRs asserted opposite IAM defaults (roles-by-default vs policies-by-default); flag it in the status line and add a Decision note pointing to ADR-117 (current default) and ADR-124 (policy rename) so the reversed default is unambiguous.
    • ADR-100: this Proposed index still presented superseded sub-decisions (102β†’118, 103β†’122) as authoritative and used the pre-composite #LIMIT# schema. Mark the superseded rows and show the current composite #CONFIG keys.
    • ADR-013: accept it. It was Proposed yet already superseded ADR-012 β€” an invalid state. Its decision is complete and already operationalized as .claude/rules/docs-parity.md, so finalize the status.

This is the main-branch half of a coordinated cleanup. The other halves renumber ADRs on open PRs so the whole sequence is collision-free:

Together these yield a collision-free ADR sequence 121-132.

Test plan

  • ls docs/adr/12*.md shows no duplicate ADR numbers
  • grep -rn "121-policy-rename" docs/ returns no stale references
  • ADR-124 header reads # ADR-124: Rename IAM Policies for Clarity
  • ADR-121 header uses the **Status:** / **Date:** inline format
  • mkdocs build reaches ADRs 114-124 from the nav
  • ADR-107 status line notes the partial supersession by ADR-117
  • ADR-100 marks the 102β†’118 / 103β†’122 superseded rows and shows #CONFIG keys
  • ADR-013 status reads Accepted

πŸ€– Generated with Claude Code

…ame to 124

Two Accepted ADRs both claimed number 121 on main:
- 121-native-sync-unasync.md (created first, referenced by CLAUDE.md)
- 121-policy-rename-clarity.md (created later, amends ADR-117)

Native-sync keeps 121 since it is the earlier file and is referenced
externally (CLAUDE.md). Renumber the IAM policy-rename ADR to 124 (next
free number after 123-local-secondary-indexes). This is a structural
collision fix, not a decision change, so it is consistent with the
ADR immutability rule.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
sodre added a commit that referenced this pull request Jun 12, 2026
…→ 124)

This branch forked from main after both ADR-121 files existed, so it
carried the same duplicate-121 collision. Apply the identical fix used
on main (#422): rename policy-rename-clarity 121 β†’ 124 so the branch is
self-consistent and merges cleanly.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
sodre and others added 2 commits June 11, 2026 21:33
ADR-121 (native-sync) used a `## Status` heading with the value on a
separate line, unlike every other ADR which uses the `**Status:**` /
`**Date:**` inline format mandated by ADR-000. Normalize it (Date taken
from the file's creation commit, 2026-02-02).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The ADR nav stopped at ADR-113; ADRs 114-124 existed as files but were
unreachable from the docs site. Add thematic groups (Composite Items,
IAM Resources, Config Hierarchy & TTL, Sync & Repository, Pre-1.0
Hardening) covering 114-124, reflecting the corrected numbering
(121=native-sync, 124=policy-rename).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@sodre sodre changed the title ♻️ refactor(adr): resolve duplicate ADR-121 by renumbering policy-rename to 124 πŸ“ docs(adr): fix ADR-121 numbering collision + nav/format cleanup Jun 12, 2026
@codecov

codecov Bot commented Jun 12, 2026

Copy link
Copy Markdown

Codecov Report

βœ… All modified and coverable lines are covered by tests.
βœ… Project coverage is 29.14%. Comparing base (6878b6d) to head (3054287).
βœ… All tests successful. No failed tests found.

❗ There is a different number of reports uploaded between BASE (6878b6d) and HEAD (3054287). Click for more details.

HEAD has 3 uploads less than BASE
Flag BASE (6878b6d) HEAD (3054287)
unit 1 0
e2e 1 0
integration 1 0
Additional details and impacted files
@@             Coverage Diff             @@
##             main     #422       +/-   ##
===========================================
- Coverage   92.38%   29.14%   -63.25%     
===========================================
  Files          37       37               
  Lines        7854     7854               
===========================================
- Hits         7256     2289     -4967     
- Misses        598     5565     +4967     
Flag Coverage Ξ”
doctest 29.14% <ΓΈ> (ΓΈ)
e2e ?
integration ?
unit ?

Flags with carried forward coverage won't be shown. Click here to find out more.

β˜” View full report in Codecov by Harness.
πŸ“’ Have feedback on the report? Share it here.

Surfaced by the /adr consistency audit:

- ADR-107: annotate the partial supersession by ADR-117. Two Accepted
  ADRs asserted opposite IAM defaults (roles-by-default vs policies-by-
  default). Flag it in the status line and add a Decision note pointing
  to ADR-117 (current default) and ADR-124 (policy rename), so the
  reversed default is unambiguous to readers/enforcement.
- ADR-100: this Proposed index still presented superseded sub-decisions
  (102β†’118, 103β†’122) as authoritative and used the pre-composite
  `#LIMIT#` schema. Add a standing note, mark the superseded rows, and
  show current composite `#CONFIG` keys alongside the originals.
- ADR-013: accept it. It was Proposed yet already superseded ADR-012 β€”
  an invalid state. Its decision is complete and already operationalized
  as .claude/rules/docs-parity.md, so finalize the status.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@sodre sodre changed the title πŸ“ docs(adr): fix ADR-121 numbering collision + nav/format cleanup πŸ“ docs(adr): ADR consistency cleanup β€” numbering, nav, format, cross-refs Jun 12, 2026
@sodre sodre marked this pull request as ready for review June 12, 2026 01:51
@sodre sodre merged commit 1277a70 into main Jun 12, 2026
10 of 11 checks passed
@sodre sodre deleted the fix/adr-numbering-collision branch June 12, 2026 02:19
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