[ideaship]

The drift docs promise a complete roster — ## The checks says the plugins run
in registry order and "the report renders them the same way", and each one gets
a ### Plugin: <name> section — but nothing enforces it, and two gaps had
opened:

• kolla_source_ref_phase merged with no section at all, so the only
  description of the check was its module docstring.
• the kolla_mirror_verbatim section still described a single
  all/001-kolla-defaults.yml, which the mirror-layer series (74ac6e5..9edc160)
  replaced with a per-service all/001-*.yml layer.

The docstring is not the operator-facing surface. A maintainer meets a check as
a red line in the nightly release-tox-drift report and goes to the group doc;
nothing in the run points at a module docstring.

Why it happened, and what stops it

## Adding a plugin in the kolla doc is the canonical recipe — the image doc and
the new catalog doc both defer to it. It listed the module contract, the registry
entry, the config stanza and the test pattern. It never said to document the
check. The one step missing from the recipe is the one that got missed, twice.

This adds the step, in the kolla recipe and in the image doc's short form, and
says what a section consists of (stage lead, command, Reads:/Fix: bullets) so
it reads as a requirement rather than a reminder to be thorough.

It is prose, not enforcement: a plugin can still merge undocumented. A tolerant
registry test — every registered plugin's name appears in some heading under
docs/, no fixed file or heading level — would close that, and would survive the
restructure this file is heading for. Left out of this PR deliberately; happy to
add it.

Commits

• docs: document kolla_source_ref_phase — what it compares (each
  openstack_projects ref against the latest lifecycle phase opendev still
  publishes a tarball for), why it probes artifacts rather than branches, why an
  inconclusive probe reports unverified rather than clean, and why no
  --base-dir can stand in for it (EXTERNAL_HOSTS, a property no other kolla
  plugin has and one an operator currently discovers as an error message).
• docs: read the 001 mirror as a layer — the layer, its lexical merge order and
  why that matters (upstream defines the database_* keys in both common.yml
  and database.yml and relies on database.yml winning), and the fallback to
  the layer glob for the monolithic upstream layout of 2025.1 and earlier.
• docs: make documenting a plugin part of adding one — the recipe step.

The four-stage framing in ## The checks describes a kolla service, and
kolla_source_ref_phase is about the release manifest rather than any one
service, so it is introduced as sitting ahead of the stages instead of being
renumbered into the list.

Merge order for the queue behind this

Docs-only, no behaviour change, and deliberately placed first so the queued
plugin PRs land against a doc that already asks them for a section. I
test-merged this branch against each of them in both directions, then all five
sequentially:

drift-docs-plugin-coverage → 2685 → 2693 → 2690 → 2643

• Add role_registry_orphan: flag docker_registry_* role defaults nothing uses #2685
• drift: check inventory at every release ref #2693
• Add catalog drift plugin group #2690
• Add drift check for retired release references #2643

Everything is clean except one unavoidable collision between the last two:
2643 and 2690 both append their plugins: stanza at EOF of
src/drift-config.yml. It fires in either order; keeping both lines resolves
it. 2643 goes last because it is a draft and 19 commits behind, so it absorbs
that one line in the rebase it needs anyway — and picks up its own doc section
there. Verified end state of all five merged: 529 passed, 2 skipped, lint clean.

Verification

tox -e drift-test on this branch: 420 passed. flake8, black and yamllint clean.
No source changes, so no drift run is affected.

Note for a reviewer

docs/check-drift-kolla.md is 512 lines after this, with 13 plugin sections in
one file, and the queued PRs add ~40 more. These commits are additive and do not
depend on the current layout, so a later split (one file per plugin, group docs
keeping run/input-resolution/allowlist/release-model) does not have to unpick
them.