unic / unic/unic-agents-plugins
Plugin and Consumer ADR numberings share a namespace, and /build schedules the collision
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 1
- Forks
- 0
- Avg merge
- 16h 43m
- Merged PRs (30d)
- 19
Description
The problem
Two facts, both measured on 2026-08-24 while resolving #407/#401 (PR #413):
- A bare
ADR-NNNNin a Box always means a plugin ADR — that convention is now one sentence in the plugin'sAGENTS.md(§ "A Box is read where it runs"), chosen over qualifying the ~88 bare citations across the four Box YAMLs, because a citation carrying its own repository is a sentence nobody keeps current. /buildgrows the Consumer's owndocs/adr/—unic-dlc-build.yaml's report node draftsdocs/adr/NNNN-<slug>.mdinto the Consumer.DXP-DesignSystemalready holds0001and0002; the Boxes cite0011upward.
So the two numberings share a namespace, and the collision is scheduled, not hypothetical: enough /build runs and the Consumer mints an ADR-0011 of its own, at which point every bare citation in every installed Box resolves ambiguously — the harder-to-notice defect class (#401's plausible-but-wrong pointer, one level up).
The maintainer chose at #413's merge to keep the one-sentence convention for now. This ticket tracks the collision itself.
What a resolution decides (not decided here)
- Whether
/build's report node numbers Consumer ADRs from a floor (e.g. above the plugin's highest citation), prefixes them, or the collision is handled at read time by the convention sentence alone. - Whether the plugin's ~88 bare citations ever get qualified, and if so by what rule that does not rot (the objection that killed qualifying them in #413).
- Who owns the fix: the Box prose (plugin), the Consumer's ADR README, or both.
Acceptance criteria
- The collision-handling rule is decided and written where it acts:
/build's report node prose, the pluginAGENTS.mdbullet, or both — with each surface naming the other. - The rule is stated for the collision case, not only the clean case: what a reader does when
ADR-0011exists in both trees. -
DXP-DesignSystem's current ADR count is re-measured at implementation time — this body's0001/0002is a 2026-08-24 snapshot and will be stale.
Context
- Found by wayfinder-407 while resolving #401's cross-reference sweep; the maintainer's choice to defer is recorded in PR #413's review-trail summary comment.
- Related: #401 (the pointer-ambiguity class), ADR-0027 (superseding works across both ADR homes — the one plugin surface that already knows two homes exist).
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reading the report node in unic-dlc-build.yaml, the plugin AGENTS.md bullet, and the PR #413 review-trail summary. Re-measure DXP-DesignSystem's current ADR count, then decide and document the collision rule on the relevant surfaces, including what readers do when the same ADR number exists in both trees.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- markdown, yaml
- Domain
- build-system, documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100