Move the backlog to TODO.md and make that the fleet destination

README.md

@@ -42,7 +42,6 @@ See [Release History][history] for the full history.
   - [For a README or Human-Facing Doc](#for-a-readme-or-human-facing-doc)
   - [For Workflows](#for-workflows)
 - [Development Environment Setup](#development-environment-setup)
-- [TODO](#todo)
 - [License](#license)
 
 ## What This Repo Is
@@ -128,21 +127,6 @@ A human-readable index of the rules agents enforce, implement, and audit. The au
 
 Contributors sign every commit. See [docs/ssh-signing.md][ssh-signing] for SSH commit-signing setup, [docs/host-setup.md][host-setup] for host prerequisites, and [docs/devcontainer.md][devcontainer] for devcontainer SSH-agent forwarding. Run the linters before pushing (see [GOVERNANCE.md "Running the Linters Locally"][governance-running-the-linters-locally-known-working-invocations]).
 
-## TODO
-
-Running backlog (kept here, in a committed file, so the guidance survives across environments where agent memory does not).
-
-- Run the first per-repo audits and populate [reports/][reports] for the seven cataloged repos.
-- Classify the standardization-backlog repos in [registry/repos.json][repos] (marked `classificationPending`) on first audit.
-- Canonicalize Python linter-config placement on `pyproject.toml` (one cataloged repo uses standalone `.ruff.toml` + `pyrightconfig.json`); track as a drift finding, fix downstream.
-- Consider renaming this repo to reflect the audit-catalog identity (updates badge and link URLs across the fleet).
-- Adopt the OCI annotation keys (`org.opencontainers.image.*`) for Docker image metadata across the Docker repos, replacing the ad-hoc and `org.label-schema.*` labels (from #363).
-- Sweep `ManagePackageVersionsCentrally` placement to `Directory.Packages.props` fleet-wide (PlexCleaner sets it in `Directory.Build.props`, off the CODESTYLE canonical).
-- Finish onboarding hardening (from #310): make the `AUDIT.md` audit a required onboarding step and run the per-type cold-start self-tests tracked in `reports/conformance-matrix.md` (`STANDUP.md` is already in place).
-- Refresh the README (it has gone stale) and evaluate a lower-maintenance structure - for example a per-section index that points into each doc with a one-line description, keeping the README as the adoption and audit-instruction entry point with pointers to the other docs. A per-section index trades brevity for a sync obligation: it must track what the docs contain.
-- Add a linter-only Python project type for codegen/boilerplate Python - code that runs during another tool's build to emit generated source (e.g. ESPHome codegen that produces enriched C++ at compile time), so it ships no unit tests and no coverage and needs only the linter. Keep it distinct from the existing `python` type, which is utility code that can and should carry unit tests and coverage (as in PlexCleaner). Until it exists, ESPHome-Config stays `source-only` and its `+python` reclassification is deferred - accept its one outstanding validation finding meanwhile.
-- Add a fleet-standard clang-format config for the `cpp` type: a catalog snippet plus a CODESTYLE C++ section defining the style, the C++ analogue of the shared ruff config, so the `cpp` clang-format check references one canonical style rather than each repo inventing its own. Base it on the ESPHome-Config agent's proposed `.clang-format`.
-
 ## License
 
 See [LICENSE][license].

STANDUP.md

@@ -63,13 +63,14 @@ Capture the source, verify the capture **against the source**, and hold the veri
 
 Copy every [`spec/files.json`][files] entry whose `appliesTo` matches the repo's **selector set**, **adapted, not cloned**. The selector set is the repo's `types` plus its `workflowModel`, `releaseTrigger`, and `consumerModel`, so filtering on type alone silently drops the entries a non-type selector carries ([`spec/scope-model.md`][scope-model] defines the four namespaces and how they resolve). The prose files (`CODESTYLE.md`, `README.md`, and the like) describe the repo's own toolchain, so adapt them to reality rather than propagating template specifics verbatim (see the "Adapt before propagating" callout in [`CODESTYLE.md`][codestyle], since a verbatim copy that misdescribes the repo is rejected in review). The baseline covers `WORKFLOW.md`, `version.json`, the two rulesets, `.github/dependabot.yml`, `.editorconfig`, `.gitattributes`, the linter configs, and the per-type files (`.vscode/tasks.json` from the language's snippet, `codecov.yml`, `.dockerignore`, `Docker/README.md`). **Every repo carries `repo-config/main.json`**, and only the `develop` payload varies by workflow model: `repo-config/develop.json` for a release repo, `repo-config/operational/develop.json` for an operational one.
 
-**Repo-specific content has a declared destination, not a judgment call.** The baseline is what a repo *carries*. Anything the repo knows that the fleet does not needs somewhere to live, and improvising a location per repo is what the destinations in [`spec/section-model.md`][section-model] exist to prevent. Three topical docs take it, chosen by what the content **is**:
+**Repo-specific content has a declared destination, not a judgment call.** The baseline is what a repo *carries*. Anything the repo knows that the fleet does not needs somewhere to live, and improvising a location per repo is what the destinations in [`spec/section-model.md`][section-model] exist to prevent. Four topical docs take it, chosen by what the content **is**:
 
 - [`CODESTYLE.md`][codestyle]: the repo's language and formatting conventions beyond the carried rules.
 - `ARCHITECTURE.md`: how a code repo is built, its module layout, data flow, and design decisions.
 - `OPERATIONS.md`: how an operational repo is run, covering runbooks, backup, log and debug procedures, tool-usage notes, and config layout.
+- `TODO.md`: the repo's running backlog, per [`spec/readme-structure.md`][readme-structure]. It keeps open work out of the README's section order, where it does not belong and changes on a different cadence from everything around it.
 
-**`OPERATIONS.md` is required on an `operational` repo**, not optional, so it appears in the baseline above with `appliesTo: ["operational"]`. It is presence-checked only, the same footing as `README.md` and `HISTORY.md`, so its content is entirely the repo's own and a repo with little to say still carries the file. It is the operational-repo analogue of `ARCHITECTURE.md`, and it is where an `AGENTS.md` split puts the repo-specific half, so real runbooks (a deploy procedure, a rollback, a retention policy, a credential rotation) go there rather than into a carried file. It is agent-instruction content, so it takes the inline-link exception the markdown rules name rather than the reference-style default. `ARCHITECTURE.md` stays advisory and is not required by any selector.
+**`OPERATIONS.md` is required on an `operational` repo**, not optional, so it appears in the baseline above with `appliesTo: ["operational"]`. It is presence-checked only, the same footing as `README.md` and `HISTORY.md`, so its content is entirely the repo's own and a repo with little to say still carries the file. It is the operational-repo analogue of `ARCHITECTURE.md`, and it is where an `AGENTS.md` split puts the repo-specific half, so real runbooks (a deploy procedure, a rollback, a retention policy, a credential rotation) go there rather than into a carried file. It is agent-instruction content, so it takes the inline-link exception the markdown rules name rather than the reference-style default. `ARCHITECTURE.md` and `TODO.md` stay advisory and are required by no selector, so a repo with nothing to say in one carries no file rather than an empty one.
 
 Choose the destination while scaffolding rather than after. Repo-specific content left in a carried file is drift, which the audit lists as an undeclared section to reconcile, and reconciling it later means moving prose that downstream readers have already started trusting in the wrong place.
 
@@ -119,6 +120,7 @@ The same [`AUDIT.md`][audit] run is the on-demand audit for any known repo, and
 [host-setup]: ./docs/host-setup.md
 [matrix]: ./reports/conformance-matrix.md
 [project-types]: ./spec/project-types.json
+[readme-structure]: ./spec/readme-structure.md
 [repo-config]: ./repo-config/
 [repo-config-carry]: ./docs/repo-config-carry.md
 [repos]: ./registry/repos.json

TODO.md

@@ -0,0 +1,21 @@
+# TODO
+
+Running backlog for this repo, kept in a committed file so the guidance survives across environments where agent memory does not.
+
+- Populate [reports/][reports] for the cataloged repos that still have no audit, since a registry `status` of `cataloged` asserts a result that only a committed report evidences. Eight repos have one.
+- Canonicalize Python linter-config placement on `pyproject.toml` (one cataloged repo uses standalone `.ruff.toml` + `pyrightconfig.json`), track as a drift finding, fix downstream.
+- Consider renaming this repo to reflect the audit-catalog identity (updates badge and link URLs across the fleet).
+- Adopt the OCI annotation keys (`org.opencontainers.image.*`) for Docker image metadata across the Docker repos, replacing the ad-hoc and `org.label-schema.*` labels (from #363).
+- Sweep `ManagePackageVersionsCentrally` placement to `Directory.Packages.props` fleet-wide (PlexCleaner sets it in `Directory.Build.props`, off the CODESTYLE canonical).
+- Finish onboarding hardening (from #310): make the `AUDIT.md` audit a required onboarding step and run the per-type cold-start self-tests tracked in [reports/conformance-matrix.md][matrix] (`STANDUP.md` is already in place).
+- Refresh the README (it has gone stale) and evaluate a lower-maintenance structure, for example a per-section index that points into each doc with a one-line description, keeping the README as the adoption and audit-instruction entry point with pointers to the other docs. A per-section index trades brevity for a sync obligation: it must track what the docs contain.
+- Add a linter-only Python project type for codegen/boilerplate Python, code that runs during another tool's build to emit generated source (e.g. ESPHome codegen that produces enriched C++ at compile time), so it ships no unit tests and no coverage and needs only the linter. Keep it distinct from the existing `python` type, which is utility code that can and should carry unit tests and coverage (as in PlexCleaner). Until it exists, ESPHome-Config stays `source-only` and its `+python` reclassification is deferred, so accept its one outstanding validation finding meanwhile.
+- Add a fleet-standard clang-format config for the `cpp` type: a catalog snippet plus a CODESTYLE C++ section defining the style, the C++ analogue of the shared ruff config, so the `cpp` clang-format check references one canonical style rather than each repo inventing its own. Base it on the ESPHome-Config agent's proposed `.clang-format`.
+- Sweep the 13 `dash` and `semicolon` findings in `README.md`. They are deferred rather than dropped, because two changes to that file are in flight and a third overlapping edit would conflict with both for no gain.
+- Clean the comment shape in `.editorconfig`, `.gitattributes` and `.gitignore` (44 `comment-wrap` and `comment-case` findings). These are the first files every new repo copies, so until they are fixed a new repo learns the shape the rules forbid.
+- Sweep the 54 `comment-wrap` and `comment-case` findings in `repo-config/configure.sh`. It is carried `verbatim`, so a downstream copy is byte-matched and cannot fix them locally, which makes this the hub's whole-class sweep rather than a next-edit correction.
+
+<!-- Repo -->
+
+[matrix]: ./reports/conformance-matrix.md
+[reports]: ./reports/

spec/readme-structure.md

@@ -4,13 +4,13 @@ The preferred `README.md` shape for a fleet project. The audit's `readme-structu
 
 ## Sections and Order
 
-1. **Title (`# <Name>`)** - the H1 **is the repository name** (a hyphenated name may render its hyphens as spaces: `Financial-Modeling` -> `Financial Modeling`), then a one-line description as the next paragraph. That description is a **single sentence, link-free plain text, at most 100 characters** - it is the one canonical short description. It doubles as the GitHub About description (GOVERNANCE.md "Repository Details") and, for a repo that publishes a Docker image, the Docker Hub short description. Both render no markdown, and Docker Hub caps the short description near 100 characters - the tightest surface, which sets the limit. The audit checks the H1 name, the length, the link-free form, and the mirrors.
+1. **Title (`# <Name>`)** - the H1 **is the repository name** (a hyphenated name may render its hyphens as spaces: `Financial-Modeling` -> `Financial Modeling`), then a one-line description as the next paragraph. That description is a **single sentence, link-free plain text, at most 100 characters**, and it is the one canonical short description. It doubles as the GitHub About description (GOVERNANCE.md "Repository Details") and, for a repo that publishes a Docker image, the Docker Hub short description. Both render no markdown, and Docker Hub caps the short description near 100 characters, the tightest surface, which sets the limit. The audit checks the H1 name, the length, the link-free form, and the mirrors.
 2. **Build and Distribution (`##`)** - a bullet per distribution channel the project actually ships, each linking where it lives: **Source Code** (the GitHub repo), **Versioned Releases** (GitHub Releases), **Docker Images** (Docker Hub), **NuGet Packages** (NuGet.org), **PyPI Packages** (PyPI.org). List only the channels the project uses. It carries three sub-sections:
    - **Build Status (`###`)** - the CI/build status shields (release build, Docker build, last commit, last build).
    - **Releases (`###`)** - the version shields (GitHub release, GitHub pre-release, Docker latest/develop, NuGet, PyPI), one per channel the project publishes.
    - **Release Notes (`###`)** - the current version and a short summary, any breaking-change callout, then a link to `HISTORY.md` for the full history.
-3. **Getting Started (`##`)** - *optional.* The shortest path to using the project. The **default is to omit it and go straight to the Table of Contents**; include Getting Started only when it is short and genuinely helpful, and skip it when it would be long or complex.
-4. **Table of Contents (`##`)** - generated by the Markdown All in One extension and auto-updated on save; leave the `## Table of Contents` heading in place and let the extension fill and maintain the list. Its inline anchor links are the one exception to the reference-link rule.
+3. **Getting Started (`##`)** - *optional.* The shortest path to using the project. The **default is to omit it and go straight to the Table of Contents**, and include Getting Started only when it is short and genuinely helpful, and skip it when it would be long or complex.
+4. **Table of Contents (`##`)** - generated by the Markdown All in One extension and auto-updated on save, so leave the `## Table of Contents` heading in place and let the extension fill and maintain the list. Its inline anchor links are the one exception to the reference-link rule.
 5. **Use Cases (`##`)** - what problems it solves (optional for a library whose purpose is obvious from the description).
 6. **Installation (`##`)** - how to install or pull it, per channel. N/A for source-only.
 7. **Configuration (`##`)** - settings, environment, config files. N/A when there is nothing to configure.
@@ -22,18 +22,24 @@ The preferred `README.md` shape for a fleet project. The audit's `readme-structu
 
 ## Shields
 
-Shields are not a top-level section - they live under **Build and Distribution** as the **Build Status** and **Releases** sub-sections. Each shield is a reference-style link; group the definitions under `<!-- Shields -->` at the bottom of the file. Stack a group's badges by ending each line except the last with a trailing backslash.
+Shields are not a top-level section. They live under **Build and Distribution** as the **Build Status** and **Releases** sub-sections. Each shield is a reference-style link, with the definitions grouped under `<!-- Shields -->` at the bottom of the file. Stack a group's badges by ending each line except the last with a trailing backslash.
 
 ## Style
 
 - Write in the current state, present tense, so the reader needs no knowledge beyond what they are reading (GOVERNANCE.md Documentation Style).
-- One logical paragraph per line; no hard-wrap.
+- One logical paragraph per line, with no hard-wrap.
 - Title-case headings with lowercase short bind words.
-- US English, ASCII only (no em-dash; use a spaced hyphen), straight quotes.
+- US English and straight quotes. Judge a non-ASCII character against the three tiers in GOVERNANCE.md "Character Set", and restructure a sentence rather than joining its clauses with an em dash or with a spaced hyphen, which that section bans in the same terms.
 - Verify every quantitative claim (counts, versions, supported platforms) against current code.
-- A project README describes only that project - no cross-repo references and no template or inheritance framing.
+- A project README describes only that project, with no cross-repo references and no template or inheritance framing.
 - Reference-style links only: every URI is a reference link defined at the bottom of the file, grouped by type under an HTML-comment header (`<!-- Shields -->`, `<!-- Workflow -->`, `<!-- Repo -->`, `<!-- External -->`) and alphabetized within each group. The auto-generated Table of Contents is the one exception, keeping inline anchor links.
 
+## TODO.md
+
+A repo's running backlog lives in a root `TODO.md`, and **a README carries no backlog section**. The README is the adoption surface a reader lands on, so open work does not belong in its section order, and the backlog changes on a different cadence from everything around it. `TODO.md` opens with a `# TODO` heading and one line saying what it holds, then a flat bullet list, each item stating the work and the reason it is owed.
+
+The file is the declared destination rather than a required file, the same footing as `ARCHITECTURE.md`. A repo with no backlog carries no `TODO.md`, and a repo with one puts it here rather than inventing a location. Work already tracked as an issue belongs in the issue, so an entry here is either not yet filed or is the local pointer to a filed one.
+
 ## HISTORY.md
 
 `HISTORY.md` is the maintainer-curated changelog and opens as the README's twin: the same `# <Title>` (without the README's ToC-omit comment) and the same intro paragraph, copied verbatim, then a `## Release History` section. The mirrored opening keeps the project identity consistent for a reader who lands on the changelog directly, and the audit checks that the title and intro match the README (HTML comments stripped).