Skip to content

.NET: docs(decisions): resolve duplicate ADR sequence numbers (0016, 0021, 0024) - #6046

Merged
westey (westey-m) merged 2 commits into
microsoft:mainfrom
jluocsa:docs/resolve-duplicate-adr-numbers
Aug 31, 2026
Merged

.NET: docs(decisions): resolve duplicate ADR sequence numbers (0016, 0021, 0024)#6046
westey (westey-m) merged 2 commits into
microsoft:mainfrom
jluocsa:docs/resolve-duplicate-adr-numbers

Conversation

@jluocsa

Copy link
Copy Markdown
Member

…0024)

Three ADR pairs in docs/decisions/ shared sequence numbers despite the directory README's guidance to pick unique numbers. This commit renames the file in each pair that does not already have established cross-references.

Renames:

  • 0016-structured-output.md -> 0027-structured-output.md

  • 0021-agent-skills-design.md -> 0028-agent-skills-design.md

  • 0024-codeact-integration.md -> 0029-codeact-integration.md

Pure rename; no content edits.

Motivation and Context

Description

Contribution Checklist

  • The code builds clean without any errors or warnings
  • The PR follows the Contribution Guidelines
  • All unit tests pass, and I have added new tests where possible
  • Is this a breaking change? If yes, add "[BREAKING]" prefix to the title of the PR.

Copilot AI review requested due to automatic review settings May 22, 2026 21:41

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot wasn't able to review any files in this pull request.

@moonbox3 Evan Mattson (moonbox3) added the documentation Usage: [Issues, PRs], Target: documentation in the code base and learn docs label May 22, 2026

@jluocsa John CSA (jluocsa) left a comment

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Author verification note (not a self-approval — flagging for reviewer convenience):

What I verified before pushing:

  1. Tiebreaker policy applied consistently. For each colliding pair, the file that kept its number is the one with stronger "anchoring" signal:

    • 0016 → kept python-context-middleware.md (status: accepted, cited 5× by 0019-python-context-compaction-strategy.md).
    • 0021 → kept provider-leading-clients.md (status: accepted, dated 2026-03-20 vs agent-skills-design proposed 2026-03-23).
    • 0024 → kept prompt-injection-defense.md (proposed 2026-01-14, earlier than codeact-integration proposed 2026-04-07).
  2. No content changes. All three operations are pure git mv — diff shows 3 files renamed, 0 insertions, 0 deletions, 100% similarity. Commit SHA: e8a91efe9ae5d07d5a0a4d4ffb073bc5d8485c00.

  3. No dangling cross-references. Searched docs/decisions/ for references to the moved files by their old numbers (ADR-0016 structured, 0016-structured-output, ADR-0021 agent-skills, 0021-agent-skills-design, ADR-0024 codeact, 0024-codeact-integration) — none found outside the renamed files themselves. The 5 citations of ADR-0016 in 0019-python-context-compaction-strategy.md correctly refer to the kept python-context-middleware.md.

  4. Sequence integrity post-merge: new highest assigned number becomes 0029. Next free number is 0030.

  5. Out of scope (intentionally):

    • No reorganizing ADRs by date or theme.
    • No edit to docs/decisions/README.md — its existing guidance ("Check for existing PRs to make sure you use the correct sequence number") already addresses the root cause.

If maintainers prefer a different tiebreaker (e.g., always keep the earlier-dated file regardless of status), I can re-run the renames with the alternative policy — the operation is mechanical and reversible.

@jluocsa

Copy link
Copy Markdown
Member Author

Updated to fix the markdown-link-check failure: my prior audit was scoped to docs/decisions/ and missed 6 cross-references in the wider tree (README.md, dotnet/src/Microsoft.Agents.AI.Hyperlight/README.md, and the two docs/features/code_act/*-implementation.md files). The new commit retargets those links to the renumbered ADRs (0021→0028, 0024→0029).

Verified with git grep across the full repo (excluding docs/decisions/) that no remaining references to the old ADR numbers exist. The merge-gatekeeper failure was a downstream of markdown-link-check; it should clear automatically once the linkspector reruns green.

@moonbox3 Evan Mattson (moonbox3) added the .NET Usage: [Issues, PRs], Target: .Net label May 22, 2026
@github-actions github-actions Bot changed the title docs(decisions): resolve duplicate ADR sequence numbers (0016, 0021, 0024) .NET: docs(decisions): resolve duplicate ADR sequence numbers (0016, 0021, 0024) May 22, 2026
@jluocsa

Copy link
Copy Markdown
Member Author

Rebased onto current main — and importantly, the target numbers had to change.

When I opened this, the plan was 0016 → 0027, 0021 → 0028, 0024 → 0029. Since then main has claimed all three of those slots:

  • 0027-hosting-channels.md
  • 0028-hosting-linking-multicast-enhancements.md
  • 0029-mcp-skill-templates-and-direct-references.md and 0029-python-agent-session-identity.md

So merging the original version would have created new collisions (0027 ×2, 0028 ×2, 0029 ×4) rather than removing them. Worth flagging that git still reported this as a clean merge — renames to new filenames never conflict textually, so the collision wouldn't have shown up in the merge check.

This is now renumbered onto the next free slots instead:

ADR was now
structured-output 0016 0036
agent-skills-design 0021 0037
codeact-integration 0024 0038

The renames are pure git mv (no content changes), and all 6 cross-references were updated across README.md, docs/features/code_act/{dotnet,python}-implementation.md, and dotnet/src/Microsoft.Agents.AI.Hyperlight/README.md. I verified every relative link still resolves to an existing file (0 dead links).

One thing worth a separate issue: three duplicate pairs remain on main that are outside this PR's scope — 0029, 0032 (dotnet-hosting-protocol-helpers / durable-azure-functions-extraction) and 0035 (dotnet-agent-hooks-enforcement / foundry-hosting-resilient-long-running-agents). Happy to fold those in here if you'd prefer a single sweep.

@github-merge-queue
github-merge-queue Bot removed this pull request from the merge queue due to failed status checks Aug 31, 2026
This was referenced Sep 7, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Usage: [Issues, PRs], Target: documentation in the code base and learn docs .NET Usage: [Issues, PRs], Target: .Net

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants