docs(adr): unify the ADR practice with the sibling packages, enforce the index - #33
Merged
Conversation
…the index Adds the two rules this repo lacked — qualified cross-repo citations and a mandatory index entry — plus the shared scripts/check-adr-index.py that enforces the second (composer adr, CI job, folded into composer check). docs/adr/ here is already clean on all four failure modes; the check guards against the drift a sibling had already accumulated. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KvMQkTAH56HnoeUHQTuAAk
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Part of unifying ADR infrastructure across the four Composer packages (
styleguide,timber-kit,definition-kit,acf-json-schema).tailwind-baseis deliberately out of scope — it is not a Composer package.Context
The good parts of the practice were split across repos. This one was already in the best shape of the four: five ADRs, all indexed, a full
AGENTS.mdsection, the restraint rules, the template block — and, uniquely, the habit of citing an ADR at the point of the constraint it explains rather than only from the index (AGENTS.md:51→ "…the per-type branch lives in the generatedfield-itemgate now (ADR 0005)"). That habit is being carried to the siblings.What was missing were two rules and any enforcement.
What changes
tailwind-base ADR-0007, never a bareADR 0007. Numbering spaces are per-repo, so a bare number sends the reader to this repo'sdocs/adr/— where0007does not exist at all. Inparisek/styleguideexactly that had happened: six comments insrc/cited a bareADR 0007that lives intailwind-base, reading as a dangling reference.scripts/check-adr-index.py— shared verbatim with the three siblings — fails on an ADR missing from the index, a duplicate number, an index entry with no file, or an off-convention filename. Wired ascomposer adr, folded intocomposer check, and as the CI job docs/adr/ index is in sync (~4 s, no PHP setup needed).This repo passes all four checks today. Nothing here is broken — the check is a guard against drift a sibling had already accumulated (a 429-line draft sitting in
docs/adr/off-convention and absent from the index, removed in parisek/timber-kit#96).Not included
Introducing
styleguide's full documentation-gate table (| You changed… | Update… |) into this repo. That is a larger unification than ADRs and deserves its own decision; the merge-gate sentence carries the same obligation for ADRs in the meantime.composer.jsonstays normalized (composer normalizeverified). No runtime code touched.