Host the PR-body-as-spec template org-wide; adopt the convention here

[lesnik512]

What

Two repos have now moved to a convention where the PR body is the spec for a change — there is
no committed change file, no lane to pick, and no planning/ tree:

• modern-di — PRs #424–#450
• faststream-outbox — chore: adopt the modern-di convention; drop planning/ and architecture/ faststream-outbox#159 (open)

Both carry an identical-in-shape .github/PULL_REQUEST_TEMPLATE.md, differing only in the package
path and the test command. This repo already hosts the org-default template at
.github/PULL_REQUEST_TEMPLATE.md, so it is the natural home — but the default is currently the
generic Summary / Changes / Checklist form, which does not carry the parts that make the convention
work.

Why the generic template is not enough

The convention's template is not a nicer checklist; four of its prompts are the convention:

• The admission check. Before writing a fact anywhere: derivable from the package → don't write
  it; enforceable → a test; a user needs it → docs/; otherwise it does not get written. Without
  this prompt at review time, prose accretes and the planning/ tree grows back.
• The invariant pin. If a wrong change could pass silently, pin it with a test whose name is the
  claim and whose docstring opens INVARIANT: and says what breaks it.
• ADR routing. A rejected alternative with load-bearing reasoning goes to docs/adr/, not into
  the PR body where it is lost on merge.
• Issue routing. Real work you are not doing now becomes an issue, not a deferred-work file.

The generic template's "Docs updated if behavior or public API changed" asks the old question —
did you update the page? — which is what let the capability pages in both repos ratchet toward
restating code.

Proposed

1. Adopt the convention in this repo. planning/.convention-version is still 2.0.0, and this
   repo still carries planning/ and architecture/. Deciding for the org while running the older
   convention here is the awkward part; doing it first also proves the migration on a docs-shaped
   repo rather than a library.
2. Replace the org-default .github/PULL_REQUEST_TEMPLATE.md with the convention form, written
   generically — the two repo-specific bits are the package directory and the test command, which
   can be phrased as "the package" and "the repo's full-suite recipe".
3. Then the local copies come out. Once the default is in place, modern-di and
   faststream-outbox delete their own .github/PULL_REQUEST_TEMPLATE.md and inherit it. Both are
   deliberately keeping theirs until step 2 lands, since a repo-local template silently wins over
   the org default and there is no signal when the two drift.

Open question

Whether the generic form loses too much. The value of the checklist is partly that it names the
repo's actual gate (just test at 100% coverage in faststream-outbox, just test-ci in
modern-di). If the generic version reads as boilerplate, the alternative is to keep the template
local per repo and instead put the convention — the admission check and the four routes — in this
repo's CLAUDE.md as an org-wide rule, with each repo's template referencing it.

[lesnik512]

This was generated by AI during triage.

Triage outcome: ready-for-human, scope narrowed to step 1

Splitting. Step 1 stays here. Steps 2 and 3 move to a follow-up issue, because verification turned up a blocker they cannot clear as written.

Step 2 would mis-instruct 21 repos

The org default is inherited by everything without a local template. Measured across the 28 non-archived repos:

• 5 have their own .github/PULL_REQUEST_TEMPLATE.md — .github, chat-app, faststream-outbox, modern-di, that-depends.
• 23 inherit the org default.
• 23 still carry planning/.
• The overlap is 21 repos.

Replacing the org default with the convention form would hand those 21 a template instructing "file an ADR in docs/adr/", "no change file", "no lane to pick" — while they still run planning/ with planning/decisions/, change files, and just check-planning as a gate. The template would contradict each repo's own workflow on the day it lands, with nothing in CI to notice. That is the same class of defect the body identifies in the generic template, pointed the other way.

Only two repos have actually adopted the convention: modern-di and faststream-outbox. Every other repo is on the old one.

The two templates differ in more than two places

The body says they are "identical-in-shape, differing only in the package path and the test command". Diffing them shows three parameterizable axes and one semantic divergence:

Divergence	Kind
package path (modern_di/ vs faststream_outbox/)	parameter, as claimed
test recipe (just test-ci vs just test)	parameter, as claimed
just bench-check as a stated gate — only faststream-outbox	third parameter, not accounted for
ADR route: modern-di requires "with a revisit trigger"; faststream-outbox dropped that phrase	drift, not a parameter

The last one is not cosmetic, and it shows in practice: modern-di has a revisit trigger in 27 of 27 ADRs; faststream-outbox in 1 of 2. The template that omits the requirement is the repo that doesn't do it. This is precisely the silent drift the body warns about — "there is no signal when the two drift" — except it has already happened, before the org default was even touched.

Whichever way step 2 goes, that phrase needs a deliberate ruling rather than being inherited from whichever copy is used as the base.

Status correction

The body lists faststream-outbox#159 as open. It merged on 2026-09-05. Both named repos are fully on the convention now — planning/ and architecture/ are gone from both — so step 3's "the local copies come out" is the only part of those two repos still pending.

What stays here: step 1

Adopting the convention in this repo is self-contained, needs none of the above settled, and is the part the body correctly argues should go first — "deciding for the org while running the older convention here is the awkward part". It also does what the body wants it to: proves the migration on a docs-shaped repo rather than a library.

ready-for-human rather than ready-for-agent, because the migration is a series of judgment calls, not a mechanical transform:

• This repo has 24 change files and 1 decision file under planning/, plus an architecture/ tree with 5 capability pages and a deferred.md. Retiring planning/ means ruling on each: promote into architecture/, convert to an ADR under a new docs/adr/, become an issue, or drop. modern-di did this over several PRs (#429–#431, #439), not one.
• This repo has no docs/adr/ yet, and its docs/ is the published MkDocs source for modern-python.org — so an ADR directory needs a not_in_nav or exclude_docs decision, which the library repos did not face.
• just check-planning is a CI gate here and would need retiring with the tree.
• The agent-skills config merged in docs(agents): configure the engineering skills for this repo #52 documents architecture/ + planning/ as this repo's domain homes. It is written to be rewritten as part of this migration; whoever does step 1 should update docs/agents/domain.md in the same PR.

Out of scope for this issue: the org-default template and the local-copy removals, now tracked separately.

[lesnik512]

This was generated by AI during triage.

Steps 2 and 3 are now tracked in #53, labeled needs-info pending the sequencing decision. This issue is step 1 only.