unic / unic/unic-agents-plugins

Plugin and Consumer ADR numberings share a namespace, and /build schedules the collision

Open
#418 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

app:unic-archon-dlc needs-specs p3 tech-debt
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):

  1. A bare ADR-NNNN in a Box always means a plugin ADR — that convention is now one sentence in the plugin's AGENTS.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.
  2. /build grows the Consumer's own docs/adr/unic-dlc-build.yaml's report node drafts docs/adr/NNNN-<slug>.md into the Consumer. DXP-DesignSystem already holds 0001 and 0002; the Boxes cite 0011 upward.

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 plugin AGENTS.md bullet, 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-0011 exists in both trees.
  • DXP-DesignSystem's current ADR count is re-measured at implementation time — this body's 0001/0002 is 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.