ADORSYS-GIS / ADORSYS-GIS/ai-helm
[Ticket]: Three ADR numbers are used twice (0050, 0077, 0118) — renumber and add a CI guard
- Dominant language
- Go Template
- Stars
- 3
- Forks
- 1
- Avg merge
- 19h 24m
- Merged PRs (30d)
- 80
Description
### Type
Operational task
### Summary
Three ADR numbers are used by **two different files each** on `main`, and `docs/adr/README.md` indexes both under the same number. Since ADRs are cited as contracts across repos and issues, a bare "ADR-0050" reference is currently ambiguous.
| Number | File A | File B |
|---|---|---|
| **0050** | `0050-opencode-toolbelt-0.8.0-and-interactive-browser-feedback.md` (added 2026-06-14) | `0050-kimi-k2.7-code-supersedes-k2.6-as-frontend-pro-backing.md` (added 2026-06-18) |
| **0077** | `0077-phoenix-style-chat-dashboards.md` (added 2026-07-07) | `0077-my-usage-dashboard.md` (added 2026-07-13) |
| **0118** | `0118-grafana-pdf-export.md` (added 2026-08-03) | `0118-fp8-kv-cache-fleet-default.md` (added 2026-08-03) |
In each pair the **later** file is the squatter — it took a number already in use.
### Intent
`CLAUDE.md` makes ADRs the source of truth for "why", and they are cited by number from other repos (`ai-helm-values`, `lightbridge-*`) and from issue bodies. A number that resolves to two different decisions makes those citations unverifiable, and the ambiguity compounds: ADR-0075 already has to disambiguate by *filename* when it amends "the GLM-5.2 non-adoption call in ADR-0050".
This is cheap to fix now and gets more expensive with every new citation.
### Source of truth (links)
- `docs/adr/README.md` — indexes both members of each pair as separate rows under the same number
- `CLAUDE.md` § "Read these first when changing anything architectural"
- `CLAUDE.md` § "ADRs are immutable once Accepted"
- Found by the 2026-09-01 cross-repo open-issue triage sweep
### Current Behavior
`ls docs/adr/*.md | sed 's#.*/##' | cut -d- -f1 | sort | uniq -d` returns `0050`, `0077`, `0118`. Both files of each pair are `Accepted`, and both appear in the README index.
### Expected Behavior
Every ADR number resolves to exactly one decision. `uniq -d` over the numbers returns nothing, and CI keeps it that way.
### Acceptance Criteria
1. Each collision resolved by renumbering the **later-added** file to a fresh number (next free is **0136**; highest in use today is 0135). The earlier file keeps its number.
2. `docs/adr/README.md` updated so each number appears once, with the renumbered entries moved to their new position.
3. Every inbound citation of a renumbered ADR updated — sweep `docs/`, `charts/`, `CLAUDE.md`, `AGENTS.md`, and open issues. ⚠️ Note ADR-0075 cites `0050` **by filename**, which survives renaming; bare-number citations do not.
4. Renames done with `git mv` so history is preserved.
5. **A CI guard** so this cannot recur — fail the build when two files in `docs/adr/` share a numeric prefix. This is the acceptance criterion that matters; without it the cleanup is a one-off.
### Out of Scope
- Editing any ADR's decision body. These are `Accepted` and immutable (`CLAUDE.md`); this is a renumber + reindex, not a rewrite.
- The **broken** ADR references in the GitLab multi-forge epic — that is a different defect (the cited ADR does not exist at all), tracked separately.
### Technical Context
`0118` is the interesting pair: both files were added on the **same day**, which is how the collision escaped review. That also means the "later file is the squatter" rule needs a human call for `0118` specifically — pick whichever has fewer inbound citations.
### Risks
- Renumbering breaks any external bookmark or citation not in this repo. Grep `ai-helm-values` and the `lightbridge-*` repos before renaming, not after.
- Doing the renumber without acceptance criterion 5 means this recurs. It has already happened three times.
### Test Plan
`ls docs/adr/*.md | sed 's#.*/##' | cut -d- -f1 | sort | uniq -d` returns empty. The new CI guard fails when a duplicate is deliberately introduced, then passes when it is removed.
### AI Usage Declaration
Investigation and drafting by Claude Opus 5, during a cross-repo open-issue triage sweep on 2026-09-01. The collisions and the ADR-0075 filename-citation detail were verified directly against `origin/main`. AI output is not truth — the owner verifies before acting.
Contributor guide
Research direction
Start with the duplicate-number command and inspect the six files in docs/adr/ plus docs/adr/README.md; read the ADR guidance in CLAUDE.md before choosing the 0118 resolution. Search docs/, charts/, CLAUDE.md, AGENTS.md, and the named external repositories for bare-number citations, then verify the duplicate check is empty and that the CI guard fails on an introduced duplicate and passes after removal.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- git, markdown
- Domain
- ci-cd, documentation
- Issue type
- Refactor
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 42/100