ADORSYS-GIS / ADORSYS-GIS/ai-helm
[Ticket]: Three ADR numbers are used twice (0050, 0077, 0118) — renumber and add a CI guard
- Langage dominant
- Go Template
- Étoiles
- 3
- Forks
- 1
- Merge moyen
- 19 h 24 min
- PR mergées (30 j)
- 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.
Guide de contribution
Ouvrir le guide de contribution
Évaluation
Cette issue n'a pas encore été évaluée.