ADORSYS-GIS / ADORSYS-GIS/ai-helm

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

Open
#1,073 0 comments 0 reactions 0 assignees View on GitHub
ticket
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.