docs(api): define durable shape evidence prerequisite

[seonghobae]

Summary

• define the durable owner path required before automatic chat-only/Responses-only detection can safely emit routing tags
• require source-backed, refresh-scoped probe evidence and inconclusive handling for auth, quota, timeout, transport, and server failures
• document why the current production provider inventory has no honest explicit API-version registry entry

Dependency

Stacked on #1012 (feat/chat-responses-shape-translation). This PR is a proposed prerequisite contract only and must not be treated as proof that active detection is implemented. The implementation follow-up requires the provider-catalog schema, refresh integration, agent evidence linkage, and endpoint tests listed in ADR 0129.

Validation

uv run pytest -q tests/test_planning_adr_identifiers.py tests/test_paper_contracts.py
5 passed
git diff --check
passed

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Team

Run ID: d718b8bc-8771-4282-95c9-194fe20ebe17

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[seonghobae]

ADR number collision: 0129 is claimed by two open PRs

Found by an org-wide sweep of ADR filenames across main and all 62 open PRs. CLAUDE.md requires: "Planning filenames use four digits and must be unique across current main and every open PR. A same-number collision is a rename, not a redesign."

The collision

PR	File (status added)	PR created
#1030	docs/planning/adrs/0129-canonical-immutable-release.md	2026-09-02T19:20:57Z
#1051 (this PR)	docs/planning/adrs/0129-durable-upstream-api-shape-evidence.md	2026-09-04T07:53:35Z

0129 does not exist on main, so both are genuinely new claims on the same number.

Suggested resolution — a rename, not a redesign. Two things point the same way: #1030 claimed the number first, and its PR title embeds the number (canonical immutable GitHub Release mechanism (ADR 0129)), so renumbering that one would also mean retitling it. The next free number in this series is 0130 (0124–0129 occupied).

Nothing in this PR's content is in question — only the filename and any in-document self-reference.

Note that #1030 is currently a draft. That does not change the analysis: the rule is scoped to every open PR, and a draft is open. If #1030 is later closed without merging, 0129 frees up and this PR could reclaim it.

Method / limitations, so this is checkable rather than taken on faith. ADR filenames were collected via pulls/{n}/files for every open PR and intersected by four-digit prefix; only status != "removed" entries counted. No open PR exceeds 100 changed files, so single-page pagination did not truncate the scan. main itself is clean — 38 ADRs, zero duplicate numbers. The only other collision found org-wide was 0042 (#911 vs #972), reported separately.

[seonghobae]

Adjudication evidence (host 1 session, 2026-09-06 KST; full report with commands in #1080). Nothing here closes, flips, or retargets anything — the decision is the opener's.

ADR 0129 collides with #1030, and tests/test_planning_adr_identifiers.py enforces uniqueness, so whichever lands second turns main red on a textually clean merge; 0131 is free. Run that test against main + #1030, not this tree alone (its "5 passed" is true only here). Base is #1012's head — retarget to main after #1012 lands; the delta then collapses to one ADR file. Do not merge this into the feature branch.