Docs: say what a kind's battery is, in one place #688

Where?

kinds/README.md (the opening paragraph and the workflows row of the pack.yml table), and the other places that say "battery" without saying what it is: docs/adopting.md, docs/configuration.md (workflows row), docs/maintaining.md, the comments of kinds/*/pack.yml, .github/workflows/plugin-checks-wp.yml and scripts/sync-repos.py (kind_battery() and its callers doc header).

What is missing, wrong or unclear?

"Battery" (a kind's battery, "ready for the battery") is used across the docs, the packs and the scripts, but no page says what it means. A maintainer reading the autopilot's question on #684 ("where 'ready for the battery' is read from") could not tell what it referred to. The closest is the opening paragraph of kinds/README.md ("the list of workflows that make up its battery"), which uses the word as if it were already known, and does not say how the battery differs from the workflows every repository gets, nor that a repository gets the caller that runs it.

Proposed solution

One definition, in one place, that every other mention links to: in kinds/README.md, under "What a pack holds" or as a short "Words" paragraph near the top, say that a kind's battery is the set of reusable workflows that check, test, release and publish a repository of that kind (pack.yml workflows, for wordpress-plugin plugin-checks-wp.yml, plugin-tests-wp.yml, plugin-release-wp.yml and plugin-publish-wp.yml); that it is distinct from the workflows every repository gets whatever its kind (repos.yml every-repository: conventions, review, pull-request comments); that a repository runs it through its callers, the small files in its own .github/workflows/ that scripts/sync-repos.py callers writes from workflow-templates/; and what "ready for the battery" means once #681 settles it (the files the battery needs at the repository's root). The workflows rows of kinds/README.md and docs/configuration.md, and docs/adopting.md, link to that definition instead of repeating the word bare. If docs/model.md keeps a glossary, the term goes there with a link to the same place.

Problem

A word that only the people who wrote the engine understand makes the autopilot's questions, the drift report and the docs unreadable to everyone else, the maintainer included, and an answer given without understanding the question is a decision taken blind.

Scope

kinds/README.md, docs/configuration.md, docs/adopting.md, docs/maintaining.md, and docs/model.md only if it has a glossary. Words only: no workflow, script or pack changes.

Out of scope

What "ready for the battery" checks and where it is read from, which #681 decides. Renaming the term.

Acceptance criteria

C1: Given kinds/README.md, when a reader looks for what a battery is, then one paragraph defines it, names the pack key it comes from (workflows), gives the wordpress-plugin example, and says how it differs from the workflows every repository gets and how a repository runs it (its callers).
C2: Given docs/configuration.md, docs/adopting.md and docs/maintaining.md, when they say "battery", then the first mention on each page links to that definition.

Criticality

Normal

Who works on it

• I want to work on this myself

🤖 AI-assisted · Claude Opus 5.5 (Anthropic)

Spec: approach

Add a short section ## The battery to kinds/README.md, right after the pack.yml table in "What a pack holds" (its heading gives the stable anchor #the-battery), holding one paragraph that says: a kind's battery is the reusable workflows in .github/workflows/ that check, test, release and publish a repository of that kind, as listed under the pack's workflows key; for wordpress-plugin, plugin-checks-wp.yml, plugin-tests-wp.yml, plugin-release-wp.yml and plugin-publish-wp.yml; it differs from the workflows every repository gets whatever its kind (repos.yml every-repository: issues.yml, pull-request-comments.yml, and org-pull-request.yml that the organisation's ruleset requires) because only a repository of that kind gets it; and a repository runs it through its callers, the files from workflow-templates/ that sync-repos.py callers writes into its .github/workflows/ and that name the battery's workflows (GitHub cannot pick a reusable workflow from data). The earlier mentions in kinds/README.md (intro, the workflows row) link to that section.

In docs/adopting.md and docs/maintaining.md, the first "battery" on each page becomes a link to ../kinds/README.md#the-battery. docs/configuration.md is generated by scripts/settings.py docs from policy/settings-schema.yml (test_configuration_doc.py fails a hand edit), so the link goes into the says: of the workflows setting there and the page is regenerated with python3 scripts/settings.py docs > docs/configuration.md. That is a change of words in a data file under policy/, not of a workflow, script or pack; docs/model.md has no glossary and no "battery", so it is left alone. Nothing widens any permission, secret, lane or limit.

Spec: files

• kinds/README.md
• docs/adopting.md
• docs/maintaining.md
• policy/settings-schema.yml (the says: of the workflows setting only)
• docs/configuration.md (regenerated)
• tests/workflows/test_battery_doc.py (new)

Spec: tests

• C1 → tests/workflows/test_battery_doc.py
• C2 → tests/workflows/test_battery_doc.py