ADORSYS-GIS / ADORSYS-GIS/ai-helm

[Ticket]: Three ADR numbers are used twice (0050, 0077, 0118) — renumber and add a CI guard

Ouverte
#1,073 0 commentaires 0 réactions 0 personnes assignées Voir sur GitHub
ticket
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.

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.