adr: 0001-stakeholder-outreach-draft.md claims ADR number 0001 and is missing from the adr/README.md index

Open Beginner friendly
#281 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
84/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
javascript, markdown

Research direction

Start with adr/0001-stakeholder-outreach-draft.md, the links at line 100 of adr/0001-site-ownership-and-cutover-path.md, adr/README.md, and tests/adr-contract.test.mjs. Move the supporting draft out of the numbered ADR space, update both links and the index guidance, then remove the { todo: true } flags from the two named tests and run the ADR contract test suite.

Written by the indexing model from the issue text.

Description

agent/quality documentation hive/hosted-available-lke648397-260827-5n31

Finding

adr/ currently contains three number-prefixed files:

adr/0001-site-ownership-and-cutover-path.md   <- ADR 0001
adr/0001-stakeholder-outreach-draft.md        <- not an ADR; supporting draft
adr/0002-peoplehub-fleet-status.md            <- ADR 0002

adr/0001-stakeholder-outreach-draft.md is supporting material for ADR 0001 ("a ready-to-send draft supporting ADR 0001") — it has no - **Status**: or - **Date**: header and heads itself "Stakeholder outreach draft for ADR 0001". But its filename takes the 0001- prefix, so:

  1. Two files in adr/ claim ADR number 0001, breaking the one-number-one-record convention the index table depends on.
  2. It is absent from the adr/README.md index, so a reader scanning the index does not know it exists.

Recommendation

Pick one:

  • Rename it out of the ADR number space, e.g. adr/0001-stakeholder-outreach-draft.md -> adr/supporting/stakeholder-outreach-draft.md (or adr/stakeholder-outreach-draft-for-0001.md), updating the two relative links that point at it — adr/0001-site-ownership-and-cutover-path.md line 100 and adr/README.md — and note in adr/README.md that supporting material is not numbered; or
  • Index it as a distinct row and give it the ADR header block, if it is meant to be a record in its own right.

Renaming is the smaller change and matches the file’s own self-description.

How this is tracked in tests

tests/adr-contract.test.mjs encodes both halves of this contract as { todo: true } tests, so the deviation is recorded and the suite stays green:

  • each ADR number is claimed by exactly one file
  • every number-prefixed ADR file is listed in the index

Whoever lands the fix above should drop the { todo: true } flag from those two tests in the same change; they pass as written once the collision is resolved.

Priority

  • Impact: low
  • Effort: low

Filed by quality agent (hold-gated mode)

🐝 Hive Agent: quality | Instance: hosted-available-lke648397-260827-5n31 | SHA: 00b44df

— hive: agent=quality backend=copilot model=claude-opus-5

Dominant language
JavaScript
Stars
0
Forks
2
Avg merge
2d 22h
Merged PRs (30d)
12

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.

More from cncf/endusers

All issues in cncf/endusers

Similar issues

More JavaScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.