From ac79f2106ecf8ecd63e80b08382274668d5f3571 Mon Sep 17 00:00:00 2001
From: Pieter Viljoen <ptr727@users.noreply.github.com>
Date: Wed, 5 Aug 2026 19:50:44 -0700
Subject: [PATCH 1/3] Fold the onboarding-feedback pass into the backlog

Two days of onboarding more repositories to the hub produced seventeen
recorded observations. Each was checked against `develop` at `b82c1a3`,
the committed `TODO.md`, and the eleven open issues before being written
down, because the value of the pass is in what is genuinely uncovered
rather than in the count.

Ten are new entries. Three amend an entry that had already reasoned
about the same surface from one example and needed the second. One was
already covered and is left alone. Two are rules that already exist and
already state the common case, where what recurs is the case the rule
leaves unstated.

## The three amendments, each adding the example the entry was missing

| Entry | What it gains |
| --- | --- |
| Reduce the copied surface | The wanted end state, and that the fleet
already runs both models without either having been chosen |
| Name hub-only machinery | The measured cost, agents rebuilding worse
versions of gates that already exist |
| The `hugo` type | That the theme carry mechanism is undecided, as a
question about the type rather than about one repository |

## Two already-documented rules, where the wording is the defect

`Closes #N` is stated and carried, so agents re-deriving it are missing
it rather than lacking it. What is genuinely absent is the case that
produces the confusion: work complete on `develop` with no promotion
imminent, which the current text does not license closing.

The clickable-link rule gets the hard part right, that a prompt renders
no link, so the reference inside it is bare and the link goes in the
message that accompanies it. It says accompanying rather than preceding,
and a message emitted after the prompt is not read before the question
is answered, which is the whole outcome the rule exists to produce.

Reading both recurrences as underspecified wording rather than as the
rule being ignored is what makes them fixable.

## One entry records a live defect rather than a preference

The README intro spec and the `HISTORY.md` mirror rule together forbid a
second paragraph, and `spec/audit.py` measures the first non-empty line,
so a legitimate second paragraph is reported. That is the same axis as
declaring the description in the registry, so the two are noted as
wanting one decision rather than two.

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 TODO.md | 24 ++++++++++++++++++++----
 1 file changed, 20 insertions(+), 4 deletions(-)

diff --git a/TODO.md b/TODO.md
index 04c96d48..dd62ea6d 100644
--- a/TODO.md
+++ b/TODO.md
@@ -2,7 +2,7 @@
 
 Running backlog for this repo, kept in a committed file so the guidance survives across environments where agent memory does not. Entries are grouped by the surface they change rather than by priority, since an entry's cost is mostly set by what it touches. Where an open issue covers the same ground it is named on the entry, so the two are read together rather than worked twice.
 
-Every issue claim below was re-checked against `develop` at `1ed0cc8` on 2026-08-03. An issue records the tree as it was on the day it was filed, so a claim in one is a starting point for a check rather than a finding to act on.
+Every issue claim below was re-checked against `develop` at `1ed0cc8` on 2026-08-03, and the entries added from the onboarding-feedback pass were checked against `develop` at `b82c1a3` on 2026-08-05. An issue records the tree as it was on the day it was filed, so a claim in one is a starting point for a check rather than a finding to act on.
 
 ## Verified Complete, Awaiting Close
 
@@ -24,6 +24,8 @@ The gates in [`scripts/`][scripts] are hub-only and are the fleet's main defense
 - Teach the `sha-pin` check in [`repo_gate.py`][repo-gate] to verify a pin **resolves**, not merely that it is shaped like a SHA. Forty hex characters is a format any fabricated string satisfies, and an agent hand-writing a plausible SHA into a workflow is a real failure mode rather than a hypothetical one. A resolvability check also catches the neighboring case, a pin whose commit was reachable only from a branch that has since been squashed and deleted, which breaks a downstream gate long after the change that caused it. Scope the network call to same-owner repositories, where the fleet's own actions live, and skip rather than fail when the host is offline so the local gate stays usable. Note that the existing `gh-write-guard` hook cannot cover this, since it watches Bash and an editor tool writing the same string into a file never reaches it.
 - Add a check that a pull request's **description** does not contradict its own branch. Three stale descriptions in one session generated six review findings between them, each one a reviewer noticing that the body named a commit, a branch, or a behavior the branch no longer carried. The cheap and precise form is to extract SHAs and `uses:` refs quoted in the body and confirm each still appears in the head tree, since those are the claims that go stale silently and the ones a reviewer actually catches. Prose claims are out of scope, and deliberately so: judging those needs a similarity heuristic, which [`spec/section-model.md`][section-model] already rejects for exactly the reason it would fail here.
 - Reconsider whether the pre-commit hook should run the doc gates now that they are diff-scoped. [`scripts/README.md`][scripts] records the current decision and its reason, that doc linters stay out of the hook so it stays fast, and that reason was sound when the only mode was a whole-tree sweep. A `--diff` run reads the lines one commit touches and finishes in about a second, so the trade has moved. The failure it would prevent is the most repeated one on record: comment sentences wrapped across lines, caught by CI or by a reviewer after the commit rather than before it, over and over within a single session. Weigh it against the standing preference for a fast hook, and against the risk of a hook that runs the gate from the wrong directory, which is its own false clean.
+- Audit the fleet's shell surface by size and branching, and decide per script whether Python with unit tests is the cheaper form. The evidence is the review record rather than a language preference: a non-trivial shell script earns findings round after round, while every gate under [`scripts/`][scripts] carries a `test_<script>.py` beside it and converges in one or two. `repo-config/configure.sh` and `host-setup/agent-safety/install.sh` are the two worth measuring, and the measure is lines, branch count, and the review rounds each has actually cost, not a general claim about the two languages. Two constraints bound the answer before anything is rewritten. A bootstrap script runs before anything is installed, so an installer that needs the Python it exists to install is not a rewrite worth having, which protects `install.sh` more than it protects `configure.sh`. And `configure.sh` is carried `verbatim` to the fleet, so changing its form is a re-vendor for every repository holding it, which makes this the same visit as the hub-hosted tooling entry below rather than a separate one.
+- Move the commands that keep failing the same way into helper functions, rather than restating the rule they keep failing against. Two are on record. A command run from the wrong working directory, which does not error and instead returns a confident answer about a different tree. And a GitHub node id typed by hand into a mutation, which the `gh-write-guard` hook correctly refused because the id had not come from a query in that same command. The second is the instructive one, since the rule it broke is stated plainly in [`GOVERNANCE.md`][governance] and in the host-level guidance, and an agent that had read both still reached for the literal, which says the shape of the operation is what fails rather than the agent's knowledge of the rule. A reply-and-resolve helper in [`pr_review.py`][pr-review] would take a pull request number and a finding, query the thread ids itself, and never put an id anywhere a hand could type one, which removes the failure instead of detecting it. Note the dependency: a helper only helps where it can be run, so this is worth building only alongside the question below about whether a downstream repository can reach a hub script at all.
 - Fix the newline parsing in [`gh-write-guard.py`][write-guard], where `_git_subcommand_arglists` ends a `git push` argument list at `&&` but not at a newline, so every token on a later line of the same command is read as a refspec. Measured against the installed hook, `git push -u origin revendor/x` alone resolves to the one branch, while the same push followed by a newline and `gh pr create` with a base of `develop` resolves to five, meaning `revendor/x`, `gh`, `pr`, `create`, and `develop`. The `&&` form resolves correctly, which is what isolates the defect to the newline case. The direction of the error is over-blocking rather than under-blocking, so it is a usability defect rather than a safety hole, and that is exactly why it is worth fixing rather than tolerating: the denial tells the agent it is attempting a direct push to a protected branch that only lands by bypassing a rule with admin power, when the push targets an ordinary feature branch. An agent that believes the message either escalates a push needing no escalation or goes looking for a way around the guard, and teaching a safety hook to cry wolf is how it stops being read. Note the fix reaches every host only when `host-setup/agent-safety/install.sh` is re-run, so it lands with the rollout work in [#365][issue-365] rather than ahead of it, and the entry to write alongside the fix is a self-test case for the newline form, since the existing suite covers the `&&` form and passed throughout.
 
 ## Carried Content and Propagation
@@ -33,16 +35,22 @@ Everything here changes a file the fleet holds a copy of, so each entry costs a
 - Re-vendor the changed `verbatim` content across the fleet, which is one sweep covering five files. `repo-config/configure.sh` is carried `verbatim` with `appliesTo: "*"` and the hub swept it to one sentence per line. In `AGENTS.md`, "Context and Delegation Discipline" carries the wait rule's failure clause and "Where the Rules Live" carries a row for the new section named below. In `GOVERNANCE.md`, "Verification Discipline" carries the rule that a launched process is not a result, "PR Review Etiquette" carries the five outcomes that close a finding, "Repository Boundaries and Write Safety" carries the rule that a refused write is reported rather than re-shaped, and "Representative Data in Agent-Authored Text" is an entirely new carried section that no downstream repo holds, which the audit reports as a missing section rather than as drift. Three further `GOVERNANCE.md` sections differ by a single word each, "Documentation Style Conventions", "Communicating with the User" and "Repository Details", where the format's name was capitalized to the convention `CODESTYLE.md` "Markdown and Spelling" now states, so they are byte-mismatched for a reason a reader of the diff would otherwise call cosmetic. Two comment lines in `.markdownlint-cli2.jsonc` took the same capitalization, and that file is `verbatim` and `whole`, so every downstream copy is byte-mismatched on a config nothing else changed about. `CODESTYLE.md` carries the new item and is the fifth file, at `intent` rather than `verbatim` fidelity, so it reaches the fleet as a rule each repo adopts in its own copy rather than as bytes to match, and the same mixed spelling is waiting in every downstream tree. Every repo already holding a copy of a changed section is byte-mismatched against the hub until it takes the new one, which the audit reports as stale rather than modified. This sweep is also the follow-through [#489][issue-489] and [#379][issue-379] were waiting on, and the `.editorconfig` line in [#353][issue-353] rides the same visit to each repo. Regenerate [reports/divergences.md][divergences-report] before using it as the work list, since the committed copy is dated 2026-07-22 and therefore predates the router split, which shows in it naming "Repository Boundaries and Write Safety", "Git and Commit Rules" and "Verification Discipline" as `AGENTS.md` sections when all three now live in `GOVERNANCE.md`. A stale ledger is the same hazard as a stale exemption, in that it hands out a work list measured against a tree that no longer exists.
 - Drop the unused `GITHUB_TOKEN` grants from the merge-bot workflow, per [#521][issue-521], which the tree confirms is still open, since all four jobs still carry `contents: write` and `pull-requests: write` while every write in the file authenticates with the App token. The finding is least privilege on the highest-blast-radius shape in the fleet, a `pull_request_target` workflow holding an App private key, where the grant is not exploitable today only because no step consumes it. Three things to settle: whether to drop the job-level blocks or set a workflow-level `permissions: {}`, whether the audit should compare permissions at all given the file is `interface` fidelity with only a `requiredJobKeys` contract, and the re-vendor, since every repo carries the file. Note that [`spec/files.json`][files] now declares this workflow at `appliesTo: "*"`, which closes the separate gap [#456][issue-456] raised, that D8.1 graded a file the file spec never required.
 - State the rule that an agent never assumes a Docker image is present locally, however recently it pulled one, because a background prune can remove an image between two commands of the same session and the run then fails on something that worked minutes earlier. The prescription is the always-pull flag by default, and an explicit `docker pull <image>:<tag>` before use where the flag does not apply. The four documented lint invocations already carry `--pull=always`, in [`GOVERNANCE.md`][governance] "Running the Linters Locally", mirrored in [`OPERATIONS.md`][operations] and both VS Code task snippets, so what is missing is the rule rather than the one-liners: an agent composing an ad-hoc `docker run` drops the flag precisely because it believes the image is already cached. Two things to settle when writing it. Where it lives, since that section is scoped to the four lint tools while the rule covers any container an agent starts, which argues for placing it with the Docker or verification guidance instead, and whether it is carried to the fleet, since every repo runs the same images from the same instructions. Note the limit before writing it, so the flag does not read as the whole answer: `docker run` against a registry tag re-pulls an absent image on its own, so the cases that actually break are a locally built tag with no registry to pull from, and any command that branches on the image being present (`docker image inspect`, `docker images`) rather than simply running it.
-- Decide where a carried file may name hub-only machinery, since `GOVERNANCE.md` "PR Review Etiquette" points at `scripts/pr_review.py` and the fleet carries the section but not the script. A downstream reader follows that pointer to a path their repo does not have. Either the script joins the carried set, or the rule states the behavior and drops the tool name the way the coordination-reference rule already requires for the template repo itself.
+- Decide where a carried file may name hub-only machinery, since `GOVERNANCE.md` "PR Review Etiquette" points at `scripts/pr_review.py` and the fleet carries the section but not the script. A downstream reader follows that pointer to a path their repo does not have. Either the script joins the carried set, or the rule states the behavior and drops the tool name the way the coordination-reference rule already requires for the template repo itself. The cost of leaving it unresolved is measured rather than hypothetical, because downstream agents hand-roll the review and prose checks the hub already ships. Several sessions had to be redirected to [`pr_review.py`][pr-review] and [`prose_lint.py`][prose-lint] by hand, each one having built its own worse version of a gate that exists, and none of them did anything wrong, since the tool they were pointed at is not in their tree and nothing they can read says how to reach it. A rule that names a tool its reader cannot run is worse than either resolution, because it teaches the reader that a pointer in carried text is decorative.
+- Define the fleet's own vocabulary somewhere a repository with no history will find it, because the words a request is phrased in are defined nowhere it can read. **Hub** is used throughout these docs and in every request asking a repository to reconcile or audit itself against the canonical, and no file states that it means this repository, so a repository carrying no instruction set has to be told what the hub is, where it lives, and which file to open, by hand, each time. The review loop has the opposite shape of the same problem: [`GOVERNANCE.md`][governance] "Expected Review Loop" states the procedure precisely and never presents its name as the way to ask for it, so every request improvises a phrasing and the scope an agent reads out of it moves with the wording. A defined term is what makes "close the review loop on #123" a complete instruction. Two things to settle. Where the definitions live, since the natural home is the byte-locked Fleet Bootstrap section of [`AGENTS.md`][agents] and a repository with no carried instruction set is precisely the one that does not have it, which leaves the hub's own `README.md` as the only surface a stranger to the fleet reads first. And whether the entry point is named per task rather than per repository state, since the bootstrap section already routes correctly and the gap is that the router is unreachable rather than that it is wrong. Note that an edit to the byte-locked section lands with [#552][issue-552], which already holds that section open, rather than as a change of its own.
 - Revisit [#305][issue-305], which asks for a propagation path for the rule docs and is the oldest open issue here, because most of the machinery it asked for has since been built and the issue has not been re-scoped to match. The fidelity model, the `spec/files.json` manifest, [`spec/divergences.json`][divergences] with its generated [reports/divergences.md][divergences-report], and [`AUDIT.md`][audit-doc] section 10 together give the canonical-versus-adapted split and the audit path the issue proposed. What is genuinely still missing is the push half, since every one of those detects drift while the sweep that fixes it is manual, which is exactly the entry above. Either re-scope the issue to the push half or close it against the entry above and the audit-automation entry below.
-- Reduce the surface that is copied downstream at all, since every carried file is a copy that breaks when it is not the current one. `repo-config/configure.sh` is the worked example from this session: a defect in its check mode was fixed once in the hub and immediately turned into a re-vendor owed by every repository carrying it, and until each takes the fix they run different logic while reporting the same command. A repository that misses the sweep does not fail loudly. It quietly audits itself with an older script. The alternative is for the hub to host the tool and for each downstream repository to call it rather than hold a copy, so one edit reaches the fleet and no stale copy exists to detect, re-vendor, or classify. This is the same argument as the reusable-workflow entry below and should be settled with it rather than separately, since both are about consuming hub code at runtime instead of vendoring it. Three things to settle. What the fleet actually needs vendored, which is the content a repository is audited against and could not run without, against what only needs to be reachable. How a consumed tool is pinned, because consuming hub code at runtime is a floating dependency unless it names a commit, and the action-pinning rule already requires exactly that. And what a repository does when the hub is unreachable, since a vendored copy still works offline and a called one does not, which is the real cost being traded away.
+- Reduce the surface that is copied downstream at all, since every carried file is a copy that breaks when it is not the current one. `repo-config/configure.sh` is the worked example from this session: a defect in its check mode was fixed once in the hub and immediately turned into a re-vendor owed by every repository carrying it, and until each takes the fix they run different logic while reporting the same command. A repository that misses the sweep does not fail loudly. It quietly audits itself with an older script. The alternative is for the hub to host the tool and for each downstream repository to call it rather than hold a copy, so one edit reaches the fleet and no stale copy exists to detect, re-vendor, or classify. This is the same argument as the reusable-workflow entry below and should be settled with it rather than separately, since both are about consuming hub code at runtime instead of vendoring it. Three things to settle. What the fleet actually needs vendored, which is the content a repository is audited against and could not run without, against what only needs to be reachable. How a consumed tool is pinned, because consuming hub code at runtime is a floating dependency unless it names a commit, and the action-pinning rule already requires exactly that. And what a repository does when the hub is unreachable, since a vendored copy still works offline and a called one does not, which is the real cost being traded away. The fleet already runs both models without either having been chosen against the other, since `repo-config/configure.sh` is carried while every gate under [`scripts/`][scripts] is hub-only, and the wanted end state is the second one: a script that is identical everywhere lives in the hub once and a downstream repository calls it, which removes the re-vendor rather than scheduling it. The near-term half needs no decision to start on, which is deleting a downstream config script whose content is only ever the hub's, because a per-repo copy of a file with no per-repo content is drift waiting to be detected and nothing is lost by not having it.
 - Investigate replacing copy-pasted workflow content with cross-repo reuse, now that this repo is public. A public repository's composite actions and reusable workflows can be consumed by any other repository regardless of owner type, so the organization account this pattern was assumed to require is not needed, and the constraint that shaped the current vendor-everything model no longer holds. The catalog under [`catalog/snippets/workflows/`][workflows] is copied into each repo today, which means a fix to a shared job is a sweep across the fleet rather than one edit here, and it is the mechanism by which a defect in a snippet seeds itself into every repo that adopted it. Scope the investigation to which jobs are genuinely identical across repos against which only look similar, since a reusable workflow that needs a long input list to cover per-repo variation is worse than the copy it replaces. Settle the ref policy in the same pass, because consuming hub code at CI time is a floating dependency unless it is pinned, and [`GOVERNANCE.md`][governance] "Action pinning" requires a commit SHA for every action with one documented exception. Note that `uses:` does not accept expressions, so a per-branch ref cannot be selected in the workflow file and any branch-dependent behavior belongs inside the consumed action instead.
+- Make a table of contents standard for a long document rather than for the README alone. [`spec/readme-structure.md`][readme-structure] fixes one at README position 4 and [`GOVERNANCE.md`][governance] states how it is generated and which headings it excludes, and no other file in the hub carries one, which leaves the three longest documents in the fleet without the thing that makes them navigable: `CODESTYLE.md` at 516 lines, `GOVERNANCE.md` at 421, and `WORKFLOW.md` at 298. Two things to settle. The threshold, stated in headings or lines rather than left to judgment, so the audit can check it and no repository is put in the position of arguing that its own document is short. And how it sits with the reference-link exception, since the four agent-instruction files keep inline links exactly because they are read one section at a time, which is the same property that makes a contents list worth having in them, and the generated list is already the one exception that rule carries. Note the mechanical constraint before adopting it, that the list is filled by the Markdown All in One extension on save, so a file nobody opens in the editor grows a stale contents list rather than none, and a stale one is worse than absent because it is read as current.
+- State that an operational repository still opens a pull request for a large or risky change, even though its model permits committing straight to `develop`. [`GOVERNANCE.md`][governance] "Operational Repositories" grants the direct commit and says nothing about when to decline the grant, and `repo-config/operational/develop.json` carries only `deletion`, `non_fast_forward` and `required_signatures`, so nothing mechanical stands between an agent and a large unreviewed change landing on the live surface. The reason the grant exists is the one-line config edit that a review round costs more than it protects, and that reason stops applying well before a change gets large. Settle what counts as large, and prefer a stated shape over a line count, since the property that matters is whether the change can be read at a glance and reverted cleanly rather than how many lines it moved. Note that this stays guidance by construction, because adding a `pull_request` rule to the operational ruleset would withdraw the direct-commit grant that the whole model exists to give.
+- Say when an issue is closed by hand, not only that the closing keyword belongs on the promotion pull request. [`GOVERNANCE.md`][governance] "Git and Commit Rules" already states that `Closes #N` fires only on a merge into the default branch and therefore goes on the `develop -> main` promotion, and downstream agents keep re-deriving that rule and reporting it as a discovery, which says it is being missed rather than that it is missing. What the rule genuinely does not cover is the case that produces the confusion, which is work complete on `develop` while a promotion is not imminent, leaving the issue open with nothing on it recording that it is done. The current text licenses a hand-close only once a promotion has merged without the keyword, which is the narrower case. Widen it to say that an issue is closed when the work is verifiably complete, citing the squash SHA that completed it, and that the promotion keyword is the automation for the common case rather than the only permitted route. [#552][issue-552] is the live example, fixed by the merge of [#572][pr-572] and open at the time of writing.
+- Say that the message carrying the clickable link comes **before** the prompt it accompanies, which [`GOVERNANCE.md`][governance] "Communicating with the User" leaves unstated. The rule already gets the hard part right, that an interactive prompt renders neither a Markdown link nor a bare URL, so the reference inside it is a bare `#123` and the link goes in the message that accompanies it. It says accompanying rather than preceding, and a message emitted after the prompt is not read before the question is answered, which is the entire outcome the rule exists to produce. This keeps recurring in practice, so read the recurrence as the wording being underspecified rather than as the rule being ignored, which is the same diagnosis the entry above reaches about the closing keyword.
 
 ## Audit and Spec Model
 
 - Teach the audit to see content sitting in the wrong file, per [#523][issue-523], which the tree confirms is untouched, since [`spec/audit.py`][audit] still checks file presence, declared-section presence, verbatim hashes, and workflow interface conformance and nothing that reads a heading against a destination. The case that found it is a repo whose `.github/copilot-instructions.md` carried 311 lines under nine headings that [`spec/section-model.md`][section-model] assigns to `ARCHITECTURE.md` and `OPERATIONS.md`, reported as a missing-file letter while the misplacement that caused it was invisible. The shape that fits the engine is structural, collecting the level-two headings of an `intent` file, subtracting the ones [`spec/files.json`][files] declares for it, and comparing the remainder against the headings other destinations declare. The similarity-based version is explicitly rejected by `section-model.md`, and a detector built on it produces findings whose remedy is to delete content. Four things to settle, all in the issue: whether an undeclared heading is a finding at all given a repo may add locally, whether the destination mapping becomes declared data rather than prose, whether it reaches the advisory `ARCHITECTURE.md`, and how many repos are affected, which is measured before the check is designed rather than after it starts reporting.
 - State what a `driftNote` may contain at the moment one is written, not only what happens to it once the deviation clears, and widen the check that guards it. [`AUDIT.md`][audit-doc] section 8 says a note records a current deviation and is deleted once resolved, which is a rule about a note's end of life and leaves an agent authoring one with no rule about its content. PhotoCleaner is the worked example, in [#537][pr-537]: asked to self-audit and reconcile its notes, the agent wrote a completion record ("baseline onboarding completed"), a historical fact (the date a past version first published), and a description of the repo conforming to the README spec. All three are prose about the past or about compliance rather than a current deviation, and none of them is what the field is for. Read that as an incomplete instruction rather than an agent ignoring one, since nothing it was given forbids any of the three. Two things to settle. The rule wants stating positively at authoring time, that a note names a deviation that is true right now and would still be true if nobody read it, so history, completion, and conformance are each out by construction, and a repo doing exactly what the spec requires earns no note at all. And the detector needs the same widening, because [`spec/audit.py`][audit] currently flags a stale note by matching words that assert *outstanding* work ("pending", "not yet", "missing", "behind"), which is the opposite polarity to all three of PhotoCleaner's notes, and it only runs that check when the repo audits clean, which PhotoCleaner did not until the round that found this. A guard that fires only on one polarity, and only in the state where the problem has already gone, cannot see the failure it exists to catch. Note the limit before building it, since it is the same limit the section model already records: judging whether a sentence describes a current deviation is a semantic call, so the honest target is the shapes that are mechanically recognizable, a past-tense completion verb and an explicit date among them, with the rest left to the rule.
 - Declare the canonical short description in [`registry/repos.json`][repos] instead of deriving it by parsing the README, which makes every check and every push deterministic. Today [`spec/audit.py`][audit] extracts the intro line after the H1 and compares the GitHub About panel and the Docker Hub short description against it, so the source of truth lives inside prose. That forces anything wanting the value to parse Markdown, and PhotoCleaner#32 shows the cost, since a workflow step that reads the intro at publish time needs nine guards against headings, block quotes, all four list markers, ordered lists, HTML, tables, code, links and the length cap, and every one of them fails the release rather than the tagline. Adding a `description` field turns the README intro into a third mirror rather than the source, so the audit compares all three against one declared value, the Docker workflow pushes a literal with no parser, and `repo-config/configure.sh` can set the GitHub About panel from the same field it already sets every other repository setting from. The 100-character cap stays, since Docker Hub's short description is still the tightest surface. Add the field to `registry/repos.schema.json` as well, which sets `additionalProperties: false`, and make it optional at first so the audit falls back to the README intro while repos adopt it one at a time. The disposition is recorded on [#509][issue-509], and the ask on the Docker repos is only that the parsing step is not propagated further while the field is pending.
+- Let the README intro carry more than the tagline, and say which line the mirrors actually take. [`spec/readme-structure.md`][readme-structure] item 1 reads as though the canonical description **is** the paragraph after the H1, capped at 100 characters and link-free, and [`CODESTYLE.md`][codestyle] "Markdown and Spelling" then has `HISTORY.md` copy "the same intro paragraph" verbatim. Read together they forbid a README from saying anything further about itself above the fold, which is a real cost on a repository whose purpose needs a sentence of context, and the cap they enforce exists for Docker Hub's short description rather than for the reader. State the shape instead: the first line after the H1 is the tagline, it alone is bound by the 100-character link-free rule, and it alone mirrors to the GitHub About panel, the Docker Hub short description, and the `HISTORY.md` opening, with any further paragraph free prose that no mirror reads and no cap applies to. The audit changes with it, since it currently measures the first non-empty line and would otherwise start reporting a legitimate second paragraph. Note this is the same axis as the entry above, because declaring the description in [`registry/repos.json`][repos] makes every mirror read a field rather than parse a paragraph and settles the ambiguity by construction, so the two want deciding together rather than one after the other.
 - Rework [`spec/readme-structure.md`][readme-structure] to match the hand-crafted PlexCleaner README, which is the shape the maintainer wants, and make the result auditable rather than advisory. Four concrete divergences are already identified, measured against PlexCleaner `README.md`, this repo's `README.md`, and the current spec. First, the distribution bullet is labeled by deliverable: PlexCleaner ships executables and calls the channel **Binary Releases**, while the spec fixes the label as **Versioned Releases** for every repo, so the label belongs in a per-channel table rather than as one string. Second, the license shield sits in the top **Build Status** block here and at the very bottom of PlexCleaner, inside a closing `## License` section that reads `Licensed under the [MIT License]` followed by the shield, immediately before the link definitions. Third, the Release Notes section closes with `See Release History for complete release notes and older versions.` in PlexCleaner against `See Release History for the full history.` here, and the PlexCleaner form is the wanted one. Note that PlexCleaner writes that link inline, which the reference-style rule forbids, so adopt the wording and keep the reference form. Fourth, the channel bullets and their shields vary by deliverable, meaning GitHub binaries, Docker Hub, NuGet, and PyPI each carry a different bullet label and a different shield set, which is what a per-type table has to encode for the `readme-structure` audit dimension to check a repo against its own declared types.
 - Decide whether the canonical README section order follows PlexCleaner, which is a separate question from the four divergences above and affects every repo plus the `readme-structure` audit. PlexCleaner places **Questions or Issues** immediately after the Table of Contents, where the spec orders it ninth, and it carries sections the spec names nowhere, including Performance Considerations, Runtime Metrics, Custom Plugins, Testing, Development Tooling, Feature Ideas, and Sample Media Files. Under the recurrence rule in [`spec/section-model.md`][section-model] those last ones are correctly repo-specific and stay undeclared, so the open question is only the position of the sections the spec already names.
 - Declare locally-required secrets the way GitHub-stored ones are already declared, and make a gitignored `secrets/` directory the fleet standard that holds them. [`spec/secrets.json`][secrets] covers only the Actions and Dependabot stores, so a repo that deploys somewhere has no declared way to say what it needs at runtime, and the required set is discoverable only by reading the deploy. The pattern already runs in the fleet in two shapes: HomeAutomation-Config keeps a gitignored secrets directory of env files and Docker secret files, and ESPHome-Config keeps a gitignored `secrets.yaml` beside a committed `_secrets.yaml`. The committed file carries the required names with dummy values, so the shape of the requirement is in git while the values never are, which is the same split the GitHub side already gets from `requiredSecrets[]`. Blog needs it immediately, since it deploys on the proxmox host through HomeAutomation-Config's Docker Compose stack and carries the copy destinations and the internal URI. The hub carries neither the directory nor a `.gitignore` entry for one today, so adopting it here comes first. Note that the **GitHub** side has the same missing axis, surfaced by the `hugo` type: a deploy's credentials are per-environment GitHub Environment secrets and variables, `stores` is a closed enum of `actions` and `dependabot`, and `spec/audit.py` seeds `required_by_store` with those two keys and indexes it unguarded, so adding an `environments` value to the enum raises `KeyError` for every repo whose `publish[]` maps to that mechanism. The type landed with an optional `environments` block added to [`spec/secrets.schema.json`][secrets-schema] and described in `spec/secrets.json`'s note, so a repo that needs it may declare its per-environment names and the shape is legal rather than an invention. The hub's own `spec/secrets.json` carries no such block, having no environments of its own, and no tool reads one where it exists. That is honest but it is not a gate, so a clean audit says nothing about whether an environment is configured. Solving it properly means a store vocabulary that does not crash on an unknown key and a per-environment secrets and variables fetch, and it is the same axis as the local half above rather than a separate problem.
@@ -53,7 +61,7 @@ Everything here changes a file the fleet holds a copy of, so each entry costs a
 ## Onboarding and New Types
 
 - Give [`STANDUP.md`][standup] an explicit branch-bootstrap step, because it currently says nothing about how `main` and `develop` come into being and an agent therefore commits onto whichever branch it finds. Note that section 0A now covers the human-gated prerequisites from [#490][issue-490], so this is the remaining half of that gap rather than the whole of it. The sequence that avoids every cleanup problem is: create `main` and leave it carrying nothing, create `develop` from `main` and leave it carrying nothing, create the first feature branch from `develop` and do the whole standup there, add the repo to GitHub and apply the repo config while still on that branch, then open a normal pull request to `develop` when the repo is ready. Nothing ever has to be cleaned off `main` or `develop`, because nothing ever reached them without review. Note the mechanical wrinkle when writing this up: a git branch cannot exist without a commit, so "carrying nothing" means exactly one signed empty root commit (`git commit --allow-empty`), and section 0's signing window applies to that commit like any other. The alternative of committing onto `develop` and squashing afterwards does not work: `non_fast_forward` is set on both `develop` payloads, so the history cannot be rewritten without disabling the ruleset, and Blog was correctly blocked when it tried. Worth stating that the protection is uneven, since a `release` repo's `repo-config/develop.json` carries a `pull_request` rule that blocks a direct commit outright, while `repo-config/operational/develop.json` carries only `deletion`, `non_fast_forward` and `required_signatures`, so on an operational repo a direct commit succeeds and only the instruction stands between the agent and an unfixable history. The reason it matters on a public repo is that the exploratory standup history is where PII, secrets and noise commits accumulate, and squashing a feature branch is the one chance to leave them out.
-- The static-site generator type from [#456][issue-456] and [#558][issue-558] has landed as `hugo`, with the deploy destination as the `self-hosted` publish target and the `deploy-ssh` mechanism. Correct the record while reading this, because three details the intake predicted are wrong against what Blog actually runs, and planning from the prediction would encode requirements the repo does not meet: the theme is **vendored with no recorded upstream ref**, not a Dependabot-tracked submodule; the generator is **pinned by version and SHA256**, not run at latest; and the deploy is a **separate dispatch** from the GitHub release, not a tag cut last after the live check. What was settled and did hold: the deploy is a publish, the type is named for the generator with the generic checks phrased so they do not name it, and the URL parity gate asserting a floor on the golden list length before comparing is the check of record. What remains: promote the generator-agnostic `hugo.*` checks to a shared type when a second generator arrives, which `spec/type-model.md` "Generators" makes a registry edit by construction. Also still true and stated nowhere else, the `copilot_code_review` rule in both ruleset payloads does not gate a merge today because gated Copilot review is an invite-only beta, which deserves a sentence near the merge gate so no repo reads the rule as the enforcement and relaxes the manual discipline actually holding the line.
+- The static-site generator type from [#456][issue-456] and [#558][issue-558] has landed as `hugo`, with the deploy destination as the `self-hosted` publish target and the `deploy-ssh` mechanism. Correct the record while reading this, because three details the intake predicted are wrong against what Blog actually runs, and planning from the prediction would encode requirements the repo does not meet: the theme is **vendored with no recorded upstream ref**, not a Dependabot-tracked submodule; the generator is **pinned by version and SHA256**, not run at latest; and the deploy is a **separate dispatch** from the GitHub release, not a tag cut last after the live check. What was settled and did hold: the deploy is a publish, the type is named for the generator with the generic checks phrased so they do not name it, and the URL parity gate asserting a floor on the golden list length before comparing is the check of record. What remains: promote the generator-agnostic `hugo.*` checks to a shared type when a second generator arrives, which `spec/type-model.md` "Generators" makes a registry edit by construction, and decide how a `hugo` repository is meant to carry its theme at all, which the type declares nothing about today. The candidates are the vendored copy Blog actually ships, a submodule pinned to an upstream ref, and a separate fleet-owned repository the site consumes, and they differ along exactly the axis the carried-content entries above are about, since a vendored theme is a copy that goes stale with nothing detecting it and a submodule is a pin that Dependabot can see. Settle it as a question about the type rather than about Blog, because whatever is decided becomes the type's contract and the second generator inherits it. Also still true and stated nowhere else, the `copilot_code_review` rule in both ruleset payloads does not gate a merge today because gated Copilot review is an invite-only beta, which deserves a sentence near the merge gate so no repo reads the rule as the enforcement and relaxes the manual discipline actually holding the line.
 - Finish onboarding hardening (from [#310][issue-310]): make the [`AUDIT.md`][audit-doc] 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.
 - Add a linter-only Python project type for codegen and boilerplate Python, code that runs during another tool's build to emit generated source (for example 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`.
@@ -69,6 +77,8 @@ Everything here changes a file the fleet holds a copy of, so each entry costs a
 ## Fleet Chores
 
 - Measure review rounds against pull request size, and decide what the number licenses. The recent loops suggest a large change earns a different finding every round while a small one converges in one or two, which would make change size the lever on review cost rather than the reviewer's thoroughness, and would argue for splitting a change before review rather than discovering it through five rounds of findings. The data needs no new instrumentation, since the review history already carries it: for each recent pull request, record the diff size in files and lines, the number of rounds, and the findings per round, counting suppressed findings alongside threaded ones because they are the majority of what these loops produce. The outcome worth having is a threshold [`GOVERNANCE.md`][governance] can state in the branching or review guidance, expressed as the size at which a change is split rather than as advice to keep changes small. Note two confounds before drawing a line from the numbers. A large change is usually also a novel one, so size and unfamiliarity move together and the record should note what kind of change each was. And a round that finds something new is not evidence of a problem by itself, since a round that finds something new is the reviewer working, so the metric to watch is findings that a smaller first cut would have surfaced earlier rather than findings per round on its own.
+- Try local defensive-review subagents as a first pass before the remote reviewer, and measure what the pass is worth. The remote loop is thorough and it is also where most of a session's tokens and wall-clock go, and it delivers its findings one round at a time, which is the slowest available way to learn that a change had five problems. A local pass prompted adversarially, one agent per lens rather than one general reviewer, would surface the mechanical half before the branch is even pushed. Scope the experiment to what it can actually prove: run both for a stretch, record which findings the local pass caught that the remote reviewer then raised anyway, and keep it only where that overlap is large enough to shorten the remote loop rather than to add a step in front of it. Note the trap that makes this worth designing carefully rather than just trying. A local pass that finds nothing reads exactly like a clean change, and the next inference from there is that the remote review can be skipped, which is the one outcome the review contract exists to prevent, so the local pass is an input to the loop and never a substitute for the round the merge gate requires.
+- Record a disproved review finding somewhere the next round will read it, so the same proof is not built twice. [`.github/copilot-instructions.md`][copilot-instructions] already says the reviewer is sometimes factually wrong, already requires a decline to carry evidence, and already keeps a list of known non-working request paths, which is the shape this wants. What it has nowhere to put is the finding itself, so a claim disproved against a downloaded binary in one session is argued from scratch in the next. The worked example is the claim that `keys_unsorted` needs jq 1.6, disproved against a 1.5 binary on which `keys_unsorted` works and `walk/1` does not. Note the reason this is not simply a list to append to, which is that a disproof is true of one tree at one revision, so an entry outliving the code it was proved against becomes a reason not to check, and that is strictly worse than re-proving it. Each entry therefore records what was tested and against which revision, and an entry whose subject changes is deleted rather than edited.
 - Refresh the README, which 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, since it must track what the docs contain.
 - 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][issue-363]).
 - Sweep `ManagePackageVersionsCentrally` placement to `Directory.Packages.props` fleet-wide, since PlexCleaner sets it in `Directory.Build.props`, off the CODESTYLE canonical.
@@ -91,18 +101,23 @@ Everything here changes a file the fleet holds a copy of, so each entry costs a
 [issue-519]: https://github.com/ptr727/ProjectTemplate/issues/519
 [issue-521]: https://github.com/ptr727/ProjectTemplate/issues/521
 [issue-523]: https://github.com/ptr727/ProjectTemplate/issues/523
+[issue-552]: https://github.com/ptr727/ProjectTemplate/issues/552
 [issue-558]: https://github.com/ptr727/ProjectTemplate/issues/558
 [issue-570]: https://github.com/ptr727/ProjectTemplate/issues/570
 
 <!-- Pull requests -->
 
 [pr-537]: https://github.com/ptr727/ProjectTemplate/pull/537
+[pr-572]: https://github.com/ptr727/ProjectTemplate/pull/572
 
 <!-- Repo -->
 
 [agent-safety]: ./host-setup/agent-safety/
+[agents]: ./AGENTS.md
 [audit]: ./spec/audit.py
 [audit-doc]: ./AUDIT.md
+[codestyle]: ./CODESTYLE.md
+[copilot-instructions]: ./.github/copilot-instructions.md
 [divergences]: ./spec/divergences.json
 [divergences-report]: ./reports/divergences.md
 [files]: ./spec/files.json
@@ -110,6 +125,7 @@ Everything here changes a file the fleet holds a copy of, so each entry costs a
 [markdownlint]: ./.markdownlint-cli2.jsonc
 [matrix]: ./reports/conformance-matrix.md
 [operations]: ./OPERATIONS.md
+[pr-review]: ./scripts/pr_review.py
 [prose-lint]: ./scripts/prose_lint.py
 [readme-structure]: ./spec/readme-structure.md
 [repo-gate]: ./scripts/repo_gate.py

From 0607df5ddcadee04b28d87941ef1b063413f2fb9 Mon Sep 17 00:00:00 2001
From: Pieter Viljoen <ptr727@users.noreply.github.com>
Date: Wed, 5 Aug 2026 19:55:22 -0700
Subject: [PATCH 2/3] Name the filed issues on the entries they cover

`TODO.md` states in its own preamble that where an open issue covers the
same ground it is named on the entry, so the two are read together
rather than worked twice. Seven entries from the onboarding-feedback
pass now have an issue and were carrying no reference to it.

| Issue | Entries |
| --- | --- |
| #577 | The README intro above the tagline |
| #578 | Hand-closing an issue, the link before the prompt, and the
operational pull request, numbered by their position in the issue |
| #579 | The fleet vocabulary and its entry point |
| #580 | Naming hub-only machinery, and the helper functions that
depend on reaching it |

The three that share #578 name their item number within it, because the
issue bundles three edits to the same carried file and an unqualified
reference would not say which one an entry is waiting on.

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 TODO.md | 284 ++++++++++++++++++++++++++++----------------------------
 1 file changed, 144 insertions(+), 140 deletions(-)

diff --git a/TODO.md b/TODO.md
index dd62ea6d..21552c78 100644
--- a/TODO.md
+++ b/TODO.md
@@ -1,140 +1,144 @@
-# TODO
-
-Running backlog for this repo, kept in a committed file so the guidance survives across environments where agent memory does not. Entries are grouped by the surface they change rather than by priority, since an entry's cost is mostly set by what it touches. Where an open issue covers the same ground it is named on the entry, so the two are read together rather than worked twice.
-
-Every issue claim below was re-checked against `develop` at `1ed0cc8` on 2026-08-03, and the entries added from the onboarding-feedback pass were checked against `develop` at `b82c1a3` on 2026-08-05. An issue records the tree as it was on the day it was filed, so a claim in one is a starting point for a check rather than a finding to act on.
-
-## Verified Complete, Awaiting Close
-
-Each of these was checked line by line against the current tree and has nothing left to do here. Closing them is the maintainer's call, and each wants the evidence quoted in the closing comment rather than a bare close.
-
-- [#509][issue-509] (PhotoCleaner spec questions) is complete on all five items. Item 1, `.github/copilot-instructions.md` now reads "Most of `GOVERNANCE.md` is universal fleet law" and describes `AGENTS.md` as the thin router carrying two byte-locked sections and no repository-specific ones. Item 2, `CODESTYLE.md` "Markdown and Spelling" now names `details` and `summary` as allowed, matching [`.markdownlint-cli2.jsonc`][markdownlint]. Item 3, [`spec/readme-structure.md`][readme-structure] now states the private-repository behavior outright, that the full shape is carried and the GitHub-sourced badges render broken until the flip, which is accepted rather than worked around. Item 4, the same file now says the `HISTORY.md` mirror rule lives in `CODESTYLE.md`, which every repo carries, so the rule has a carried home and the file states only what the audit does with it. Item 5, `WORKFLOW.md` D2.2 now reads "the check exits early while the job still reports success" and spells out why a job-level `if:` would couple the release to smoke through `needs:`.
-- [#490][issue-490] (STANDUP has no repo-creation step) is complete on all four suggestions. [`STANDUP.md`][standup] carries a new section 0A, "Hand Over What Only the Maintainer Can Supply", listing the repository, the installed App, the App secret values in both stores, and every declared publish credential and environment. It states that a repo with no remote is not partially stood up but not started, and that a blocking prerequisite is escalated the moment it is found rather than carried, which is the failure mode the issue diagnosed in the agent's own task list. Step 4 now opens with `gh repo view` and carries the ruleset ordering constraint that the issue asked for.
-- [#489][issue-489] (Blog carry findings) is closed on all six items by the maintainer's own status table, five fixed and one resolved as needing no change. The single piece of follow-through it leaves is the `repo-config/configure.sh` re-vendor, which is already carried by the re-vendor entry below rather than by this issue.
-- [#379][issue-379] (Financial-Modeling fidelity findings) is dispositioned on all six items, and the manifest gap the follow-up raised was fixed by adding `repo-config/configure.sh` and `repo-config/settings.json` to [`spec/files.json`][files]. What holds it open is a downstream acknowledgement and that repo's own re-vendor, neither of which is hub work.
-- [#353][issue-353] (`.editorconfig` relaxes all analyzers) is done hub-side, and the tree confirms it, since `dotnet_analyzer_diagnostic.severity` no longer appears in `.editorconfig`. What holds it open is the downstream re-vendor across six C# repos, sequenced in the issue so PhotoCleaner's 362 sites do not gate the other five. That is cross-repo work needing the maintainer to name the repos.
-
-## Gate Honesty
-
-The gates in [`scripts/`][scripts] are hub-only and are the fleet's main defense against agent-authored drift, so a gate that reports clean without having read anything is the worst failure available here. The `gh-write-guard` hook in [`host-setup/agent-safety/`][agent-safety] is grouped with them, since it is the same kind of instrument even though it ships per host rather than per repo. These entries are ordered so the scope floor lands before anything relies on a clean verdict.
-
-- Make [`prose_lint.py`][prose-lint] assert a floor on its own scope, applying to itself the rule [`GOVERNANCE.md`][governance] already states: a gate that finds nothing is indistinguishable from a gate with nothing to find. A `--diff` run that resolves a non-empty diff and then matches **zero** files has almost certainly failed to scope rather than found a clean change, so it should say so instead of exiting 0. One session produced four separate routes to that same false clean: an unresolvable base widening to a whole-tree scan, a multi-line `paths` input read only to its first newline, a diff taken in one repository while scanning another, and a path under no repository at all. Each was fixed with its own guard, which is the wrong shape, because the fifth route will need a fifth guard and will be found the same way the first four were, by a reviewer rather than by the gate. A floor assertion covers the family. Note the honest limit before building it: a change touching only files the gate does not read (an image, a lock file) legitimately scopes to zero, so the assertion compares against the diff's own file list rather than against zero alone. This lands first, because every entry below it produces verdicts that are only worth reading once the gate can prove it read something.
-- Clear the [#519][issue-519] prose backlog, starting with `catalog/snippets/**`. Two of the four changes that issue planned have already landed and its headline numbers are stale, so re-measure before quoting anything from it. `comment-wrap` and `comment-case` are now in `DEFAULT_RULES`, and `reports/` is now exempt as a generated tree, which is why the current figures are **559** whole-tree under the default rules and **184** under `catalog/snippets` alone rather than the 668 and 119 the issue records. The whole-tree figure is the one that moves, having been 534 when this entry was written and 520 by the time [#570][issue-570] scoped the semicolon exemption to the sentence it lives in, which reported 44 semicolons the rule had been silent on. Re-measure it rather than quoting it, since a fix to the gate moves it as readily as a fix to the prose does. The snippets lead the fix order for the reason the issue gives, that a non-conformant snippet seeds its violations into every repo that adopts it and the downstream repo is then flagged for content it was handed. What remains undecided is whether the gate itself becomes a carried file rather than a hub-only one, which is the same question the entry below on hub-only machinery asks from the other direction.
-- Gate the pattern-detectable half of the representative-data rule in [`prose_lint.py`][prose-lint], meaning an absolute home path (`/home/<name>`, `/Users/<name>`, `C:\Users\<name>`) or a bare drive letter sitting in committed prose, a code comment, or a fixture. [`GOVERNANCE.md`][governance] "Representative Data in Agent-Authored Text" states the rule and says why a check is a floor rather than an answer, so the check is introduced as covering the easy half or it gets read as closing the rule, which is the specific way it would make things worse. Three things to settle when writing it. The exemption carries the whole burden, since the rule's own wording, the `host-setup/` docs, and the audit's examples all quote path shapes in order to describe them, and a wrong exemption hands out a work list that damages correct documents. The leak that motivated the rule was in a pull request comment, which no committed-file linter reads at all, so say what surface the gate covers rather than letting its name imply the rule. And a home path in an operational repo's runbook may be the literal path an operator types, which is the repo's own content rather than an agent quoting the maintainer's environment, so decide whether the finding is scoped by file, by repo type, or left for the author to judge.
-- Teach the `sha-pin` check in [`repo_gate.py`][repo-gate] to verify a pin **resolves**, not merely that it is shaped like a SHA. Forty hex characters is a format any fabricated string satisfies, and an agent hand-writing a plausible SHA into a workflow is a real failure mode rather than a hypothetical one. A resolvability check also catches the neighboring case, a pin whose commit was reachable only from a branch that has since been squashed and deleted, which breaks a downstream gate long after the change that caused it. Scope the network call to same-owner repositories, where the fleet's own actions live, and skip rather than fail when the host is offline so the local gate stays usable. Note that the existing `gh-write-guard` hook cannot cover this, since it watches Bash and an editor tool writing the same string into a file never reaches it.
-- Add a check that a pull request's **description** does not contradict its own branch. Three stale descriptions in one session generated six review findings between them, each one a reviewer noticing that the body named a commit, a branch, or a behavior the branch no longer carried. The cheap and precise form is to extract SHAs and `uses:` refs quoted in the body and confirm each still appears in the head tree, since those are the claims that go stale silently and the ones a reviewer actually catches. Prose claims are out of scope, and deliberately so: judging those needs a similarity heuristic, which [`spec/section-model.md`][section-model] already rejects for exactly the reason it would fail here.
-- Reconsider whether the pre-commit hook should run the doc gates now that they are diff-scoped. [`scripts/README.md`][scripts] records the current decision and its reason, that doc linters stay out of the hook so it stays fast, and that reason was sound when the only mode was a whole-tree sweep. A `--diff` run reads the lines one commit touches and finishes in about a second, so the trade has moved. The failure it would prevent is the most repeated one on record: comment sentences wrapped across lines, caught by CI or by a reviewer after the commit rather than before it, over and over within a single session. Weigh it against the standing preference for a fast hook, and against the risk of a hook that runs the gate from the wrong directory, which is its own false clean.
-- Audit the fleet's shell surface by size and branching, and decide per script whether Python with unit tests is the cheaper form. The evidence is the review record rather than a language preference: a non-trivial shell script earns findings round after round, while every gate under [`scripts/`][scripts] carries a `test_<script>.py` beside it and converges in one or two. `repo-config/configure.sh` and `host-setup/agent-safety/install.sh` are the two worth measuring, and the measure is lines, branch count, and the review rounds each has actually cost, not a general claim about the two languages. Two constraints bound the answer before anything is rewritten. A bootstrap script runs before anything is installed, so an installer that needs the Python it exists to install is not a rewrite worth having, which protects `install.sh` more than it protects `configure.sh`. And `configure.sh` is carried `verbatim` to the fleet, so changing its form is a re-vendor for every repository holding it, which makes this the same visit as the hub-hosted tooling entry below rather than a separate one.
-- Move the commands that keep failing the same way into helper functions, rather than restating the rule they keep failing against. Two are on record. A command run from the wrong working directory, which does not error and instead returns a confident answer about a different tree. And a GitHub node id typed by hand into a mutation, which the `gh-write-guard` hook correctly refused because the id had not come from a query in that same command. The second is the instructive one, since the rule it broke is stated plainly in [`GOVERNANCE.md`][governance] and in the host-level guidance, and an agent that had read both still reached for the literal, which says the shape of the operation is what fails rather than the agent's knowledge of the rule. A reply-and-resolve helper in [`pr_review.py`][pr-review] would take a pull request number and a finding, query the thread ids itself, and never put an id anywhere a hand could type one, which removes the failure instead of detecting it. Note the dependency: a helper only helps where it can be run, so this is worth building only alongside the question below about whether a downstream repository can reach a hub script at all.
-- Fix the newline parsing in [`gh-write-guard.py`][write-guard], where `_git_subcommand_arglists` ends a `git push` argument list at `&&` but not at a newline, so every token on a later line of the same command is read as a refspec. Measured against the installed hook, `git push -u origin revendor/x` alone resolves to the one branch, while the same push followed by a newline and `gh pr create` with a base of `develop` resolves to five, meaning `revendor/x`, `gh`, `pr`, `create`, and `develop`. The `&&` form resolves correctly, which is what isolates the defect to the newline case. The direction of the error is over-blocking rather than under-blocking, so it is a usability defect rather than a safety hole, and that is exactly why it is worth fixing rather than tolerating: the denial tells the agent it is attempting a direct push to a protected branch that only lands by bypassing a rule with admin power, when the push targets an ordinary feature branch. An agent that believes the message either escalates a push needing no escalation or goes looking for a way around the guard, and teaching a safety hook to cry wolf is how it stops being read. Note the fix reaches every host only when `host-setup/agent-safety/install.sh` is re-run, so it lands with the rollout work in [#365][issue-365] rather than ahead of it, and the entry to write alongside the fix is a self-test case for the newline form, since the existing suite covers the `&&` form and passed throughout.
-
-## Carried Content and Propagation
-
-Everything here changes a file the fleet holds a copy of, so each entry costs a hub edit plus a sweep, and the sweep is the part that gets skipped.
-
-- Re-vendor the changed `verbatim` content across the fleet, which is one sweep covering five files. `repo-config/configure.sh` is carried `verbatim` with `appliesTo: "*"` and the hub swept it to one sentence per line. In `AGENTS.md`, "Context and Delegation Discipline" carries the wait rule's failure clause and "Where the Rules Live" carries a row for the new section named below. In `GOVERNANCE.md`, "Verification Discipline" carries the rule that a launched process is not a result, "PR Review Etiquette" carries the five outcomes that close a finding, "Repository Boundaries and Write Safety" carries the rule that a refused write is reported rather than re-shaped, and "Representative Data in Agent-Authored Text" is an entirely new carried section that no downstream repo holds, which the audit reports as a missing section rather than as drift. Three further `GOVERNANCE.md` sections differ by a single word each, "Documentation Style Conventions", "Communicating with the User" and "Repository Details", where the format's name was capitalized to the convention `CODESTYLE.md` "Markdown and Spelling" now states, so they are byte-mismatched for a reason a reader of the diff would otherwise call cosmetic. Two comment lines in `.markdownlint-cli2.jsonc` took the same capitalization, and that file is `verbatim` and `whole`, so every downstream copy is byte-mismatched on a config nothing else changed about. `CODESTYLE.md` carries the new item and is the fifth file, at `intent` rather than `verbatim` fidelity, so it reaches the fleet as a rule each repo adopts in its own copy rather than as bytes to match, and the same mixed spelling is waiting in every downstream tree. Every repo already holding a copy of a changed section is byte-mismatched against the hub until it takes the new one, which the audit reports as stale rather than modified. This sweep is also the follow-through [#489][issue-489] and [#379][issue-379] were waiting on, and the `.editorconfig` line in [#353][issue-353] rides the same visit to each repo. Regenerate [reports/divergences.md][divergences-report] before using it as the work list, since the committed copy is dated 2026-07-22 and therefore predates the router split, which shows in it naming "Repository Boundaries and Write Safety", "Git and Commit Rules" and "Verification Discipline" as `AGENTS.md` sections when all three now live in `GOVERNANCE.md`. A stale ledger is the same hazard as a stale exemption, in that it hands out a work list measured against a tree that no longer exists.
-- Drop the unused `GITHUB_TOKEN` grants from the merge-bot workflow, per [#521][issue-521], which the tree confirms is still open, since all four jobs still carry `contents: write` and `pull-requests: write` while every write in the file authenticates with the App token. The finding is least privilege on the highest-blast-radius shape in the fleet, a `pull_request_target` workflow holding an App private key, where the grant is not exploitable today only because no step consumes it. Three things to settle: whether to drop the job-level blocks or set a workflow-level `permissions: {}`, whether the audit should compare permissions at all given the file is `interface` fidelity with only a `requiredJobKeys` contract, and the re-vendor, since every repo carries the file. Note that [`spec/files.json`][files] now declares this workflow at `appliesTo: "*"`, which closes the separate gap [#456][issue-456] raised, that D8.1 graded a file the file spec never required.
-- State the rule that an agent never assumes a Docker image is present locally, however recently it pulled one, because a background prune can remove an image between two commands of the same session and the run then fails on something that worked minutes earlier. The prescription is the always-pull flag by default, and an explicit `docker pull <image>:<tag>` before use where the flag does not apply. The four documented lint invocations already carry `--pull=always`, in [`GOVERNANCE.md`][governance] "Running the Linters Locally", mirrored in [`OPERATIONS.md`][operations] and both VS Code task snippets, so what is missing is the rule rather than the one-liners: an agent composing an ad-hoc `docker run` drops the flag precisely because it believes the image is already cached. Two things to settle when writing it. Where it lives, since that section is scoped to the four lint tools while the rule covers any container an agent starts, which argues for placing it with the Docker or verification guidance instead, and whether it is carried to the fleet, since every repo runs the same images from the same instructions. Note the limit before writing it, so the flag does not read as the whole answer: `docker run` against a registry tag re-pulls an absent image on its own, so the cases that actually break are a locally built tag with no registry to pull from, and any command that branches on the image being present (`docker image inspect`, `docker images`) rather than simply running it.
-- Decide where a carried file may name hub-only machinery, since `GOVERNANCE.md` "PR Review Etiquette" points at `scripts/pr_review.py` and the fleet carries the section but not the script. A downstream reader follows that pointer to a path their repo does not have. Either the script joins the carried set, or the rule states the behavior and drops the tool name the way the coordination-reference rule already requires for the template repo itself. The cost of leaving it unresolved is measured rather than hypothetical, because downstream agents hand-roll the review and prose checks the hub already ships. Several sessions had to be redirected to [`pr_review.py`][pr-review] and [`prose_lint.py`][prose-lint] by hand, each one having built its own worse version of a gate that exists, and none of them did anything wrong, since the tool they were pointed at is not in their tree and nothing they can read says how to reach it. A rule that names a tool its reader cannot run is worse than either resolution, because it teaches the reader that a pointer in carried text is decorative.
-- Define the fleet's own vocabulary somewhere a repository with no history will find it, because the words a request is phrased in are defined nowhere it can read. **Hub** is used throughout these docs and in every request asking a repository to reconcile or audit itself against the canonical, and no file states that it means this repository, so a repository carrying no instruction set has to be told what the hub is, where it lives, and which file to open, by hand, each time. The review loop has the opposite shape of the same problem: [`GOVERNANCE.md`][governance] "Expected Review Loop" states the procedure precisely and never presents its name as the way to ask for it, so every request improvises a phrasing and the scope an agent reads out of it moves with the wording. A defined term is what makes "close the review loop on #123" a complete instruction. Two things to settle. Where the definitions live, since the natural home is the byte-locked Fleet Bootstrap section of [`AGENTS.md`][agents] and a repository with no carried instruction set is precisely the one that does not have it, which leaves the hub's own `README.md` as the only surface a stranger to the fleet reads first. And whether the entry point is named per task rather than per repository state, since the bootstrap section already routes correctly and the gap is that the router is unreachable rather than that it is wrong. Note that an edit to the byte-locked section lands with [#552][issue-552], which already holds that section open, rather than as a change of its own.
-- Revisit [#305][issue-305], which asks for a propagation path for the rule docs and is the oldest open issue here, because most of the machinery it asked for has since been built and the issue has not been re-scoped to match. The fidelity model, the `spec/files.json` manifest, [`spec/divergences.json`][divergences] with its generated [reports/divergences.md][divergences-report], and [`AUDIT.md`][audit-doc] section 10 together give the canonical-versus-adapted split and the audit path the issue proposed. What is genuinely still missing is the push half, since every one of those detects drift while the sweep that fixes it is manual, which is exactly the entry above. Either re-scope the issue to the push half or close it against the entry above and the audit-automation entry below.
-- Reduce the surface that is copied downstream at all, since every carried file is a copy that breaks when it is not the current one. `repo-config/configure.sh` is the worked example from this session: a defect in its check mode was fixed once in the hub and immediately turned into a re-vendor owed by every repository carrying it, and until each takes the fix they run different logic while reporting the same command. A repository that misses the sweep does not fail loudly. It quietly audits itself with an older script. The alternative is for the hub to host the tool and for each downstream repository to call it rather than hold a copy, so one edit reaches the fleet and no stale copy exists to detect, re-vendor, or classify. This is the same argument as the reusable-workflow entry below and should be settled with it rather than separately, since both are about consuming hub code at runtime instead of vendoring it. Three things to settle. What the fleet actually needs vendored, which is the content a repository is audited against and could not run without, against what only needs to be reachable. How a consumed tool is pinned, because consuming hub code at runtime is a floating dependency unless it names a commit, and the action-pinning rule already requires exactly that. And what a repository does when the hub is unreachable, since a vendored copy still works offline and a called one does not, which is the real cost being traded away. The fleet already runs both models without either having been chosen against the other, since `repo-config/configure.sh` is carried while every gate under [`scripts/`][scripts] is hub-only, and the wanted end state is the second one: a script that is identical everywhere lives in the hub once and a downstream repository calls it, which removes the re-vendor rather than scheduling it. The near-term half needs no decision to start on, which is deleting a downstream config script whose content is only ever the hub's, because a per-repo copy of a file with no per-repo content is drift waiting to be detected and nothing is lost by not having it.
-- Investigate replacing copy-pasted workflow content with cross-repo reuse, now that this repo is public. A public repository's composite actions and reusable workflows can be consumed by any other repository regardless of owner type, so the organization account this pattern was assumed to require is not needed, and the constraint that shaped the current vendor-everything model no longer holds. The catalog under [`catalog/snippets/workflows/`][workflows] is copied into each repo today, which means a fix to a shared job is a sweep across the fleet rather than one edit here, and it is the mechanism by which a defect in a snippet seeds itself into every repo that adopted it. Scope the investigation to which jobs are genuinely identical across repos against which only look similar, since a reusable workflow that needs a long input list to cover per-repo variation is worse than the copy it replaces. Settle the ref policy in the same pass, because consuming hub code at CI time is a floating dependency unless it is pinned, and [`GOVERNANCE.md`][governance] "Action pinning" requires a commit SHA for every action with one documented exception. Note that `uses:` does not accept expressions, so a per-branch ref cannot be selected in the workflow file and any branch-dependent behavior belongs inside the consumed action instead.
-- Make a table of contents standard for a long document rather than for the README alone. [`spec/readme-structure.md`][readme-structure] fixes one at README position 4 and [`GOVERNANCE.md`][governance] states how it is generated and which headings it excludes, and no other file in the hub carries one, which leaves the three longest documents in the fleet without the thing that makes them navigable: `CODESTYLE.md` at 516 lines, `GOVERNANCE.md` at 421, and `WORKFLOW.md` at 298. Two things to settle. The threshold, stated in headings or lines rather than left to judgment, so the audit can check it and no repository is put in the position of arguing that its own document is short. And how it sits with the reference-link exception, since the four agent-instruction files keep inline links exactly because they are read one section at a time, which is the same property that makes a contents list worth having in them, and the generated list is already the one exception that rule carries. Note the mechanical constraint before adopting it, that the list is filled by the Markdown All in One extension on save, so a file nobody opens in the editor grows a stale contents list rather than none, and a stale one is worse than absent because it is read as current.
-- State that an operational repository still opens a pull request for a large or risky change, even though its model permits committing straight to `develop`. [`GOVERNANCE.md`][governance] "Operational Repositories" grants the direct commit and says nothing about when to decline the grant, and `repo-config/operational/develop.json` carries only `deletion`, `non_fast_forward` and `required_signatures`, so nothing mechanical stands between an agent and a large unreviewed change landing on the live surface. The reason the grant exists is the one-line config edit that a review round costs more than it protects, and that reason stops applying well before a change gets large. Settle what counts as large, and prefer a stated shape over a line count, since the property that matters is whether the change can be read at a glance and reverted cleanly rather than how many lines it moved. Note that this stays guidance by construction, because adding a `pull_request` rule to the operational ruleset would withdraw the direct-commit grant that the whole model exists to give.
-- Say when an issue is closed by hand, not only that the closing keyword belongs on the promotion pull request. [`GOVERNANCE.md`][governance] "Git and Commit Rules" already states that `Closes #N` fires only on a merge into the default branch and therefore goes on the `develop -> main` promotion, and downstream agents keep re-deriving that rule and reporting it as a discovery, which says it is being missed rather than that it is missing. What the rule genuinely does not cover is the case that produces the confusion, which is work complete on `develop` while a promotion is not imminent, leaving the issue open with nothing on it recording that it is done. The current text licenses a hand-close only once a promotion has merged without the keyword, which is the narrower case. Widen it to say that an issue is closed when the work is verifiably complete, citing the squash SHA that completed it, and that the promotion keyword is the automation for the common case rather than the only permitted route. [#552][issue-552] is the live example, fixed by the merge of [#572][pr-572] and open at the time of writing.
-- Say that the message carrying the clickable link comes **before** the prompt it accompanies, which [`GOVERNANCE.md`][governance] "Communicating with the User" leaves unstated. The rule already gets the hard part right, that an interactive prompt renders neither a Markdown link nor a bare URL, so the reference inside it is a bare `#123` and the link goes in the message that accompanies it. It says accompanying rather than preceding, and a message emitted after the prompt is not read before the question is answered, which is the entire outcome the rule exists to produce. This keeps recurring in practice, so read the recurrence as the wording being underspecified rather than as the rule being ignored, which is the same diagnosis the entry above reaches about the closing keyword.
-
-## Audit and Spec Model
-
-- Teach the audit to see content sitting in the wrong file, per [#523][issue-523], which the tree confirms is untouched, since [`spec/audit.py`][audit] still checks file presence, declared-section presence, verbatim hashes, and workflow interface conformance and nothing that reads a heading against a destination. The case that found it is a repo whose `.github/copilot-instructions.md` carried 311 lines under nine headings that [`spec/section-model.md`][section-model] assigns to `ARCHITECTURE.md` and `OPERATIONS.md`, reported as a missing-file letter while the misplacement that caused it was invisible. The shape that fits the engine is structural, collecting the level-two headings of an `intent` file, subtracting the ones [`spec/files.json`][files] declares for it, and comparing the remainder against the headings other destinations declare. The similarity-based version is explicitly rejected by `section-model.md`, and a detector built on it produces findings whose remedy is to delete content. Four things to settle, all in the issue: whether an undeclared heading is a finding at all given a repo may add locally, whether the destination mapping becomes declared data rather than prose, whether it reaches the advisory `ARCHITECTURE.md`, and how many repos are affected, which is measured before the check is designed rather than after it starts reporting.
-- State what a `driftNote` may contain at the moment one is written, not only what happens to it once the deviation clears, and widen the check that guards it. [`AUDIT.md`][audit-doc] section 8 says a note records a current deviation and is deleted once resolved, which is a rule about a note's end of life and leaves an agent authoring one with no rule about its content. PhotoCleaner is the worked example, in [#537][pr-537]: asked to self-audit and reconcile its notes, the agent wrote a completion record ("baseline onboarding completed"), a historical fact (the date a past version first published), and a description of the repo conforming to the README spec. All three are prose about the past or about compliance rather than a current deviation, and none of them is what the field is for. Read that as an incomplete instruction rather than an agent ignoring one, since nothing it was given forbids any of the three. Two things to settle. The rule wants stating positively at authoring time, that a note names a deviation that is true right now and would still be true if nobody read it, so history, completion, and conformance are each out by construction, and a repo doing exactly what the spec requires earns no note at all. And the detector needs the same widening, because [`spec/audit.py`][audit] currently flags a stale note by matching words that assert *outstanding* work ("pending", "not yet", "missing", "behind"), which is the opposite polarity to all three of PhotoCleaner's notes, and it only runs that check when the repo audits clean, which PhotoCleaner did not until the round that found this. A guard that fires only on one polarity, and only in the state where the problem has already gone, cannot see the failure it exists to catch. Note the limit before building it, since it is the same limit the section model already records: judging whether a sentence describes a current deviation is a semantic call, so the honest target is the shapes that are mechanically recognizable, a past-tense completion verb and an explicit date among them, with the rest left to the rule.
-- Declare the canonical short description in [`registry/repos.json`][repos] instead of deriving it by parsing the README, which makes every check and every push deterministic. Today [`spec/audit.py`][audit] extracts the intro line after the H1 and compares the GitHub About panel and the Docker Hub short description against it, so the source of truth lives inside prose. That forces anything wanting the value to parse Markdown, and PhotoCleaner#32 shows the cost, since a workflow step that reads the intro at publish time needs nine guards against headings, block quotes, all four list markers, ordered lists, HTML, tables, code, links and the length cap, and every one of them fails the release rather than the tagline. Adding a `description` field turns the README intro into a third mirror rather than the source, so the audit compares all three against one declared value, the Docker workflow pushes a literal with no parser, and `repo-config/configure.sh` can set the GitHub About panel from the same field it already sets every other repository setting from. The 100-character cap stays, since Docker Hub's short description is still the tightest surface. Add the field to `registry/repos.schema.json` as well, which sets `additionalProperties: false`, and make it optional at first so the audit falls back to the README intro while repos adopt it one at a time. The disposition is recorded on [#509][issue-509], and the ask on the Docker repos is only that the parsing step is not propagated further while the field is pending.
-- Let the README intro carry more than the tagline, and say which line the mirrors actually take. [`spec/readme-structure.md`][readme-structure] item 1 reads as though the canonical description **is** the paragraph after the H1, capped at 100 characters and link-free, and [`CODESTYLE.md`][codestyle] "Markdown and Spelling" then has `HISTORY.md` copy "the same intro paragraph" verbatim. Read together they forbid a README from saying anything further about itself above the fold, which is a real cost on a repository whose purpose needs a sentence of context, and the cap they enforce exists for Docker Hub's short description rather than for the reader. State the shape instead: the first line after the H1 is the tagline, it alone is bound by the 100-character link-free rule, and it alone mirrors to the GitHub About panel, the Docker Hub short description, and the `HISTORY.md` opening, with any further paragraph free prose that no mirror reads and no cap applies to. The audit changes with it, since it currently measures the first non-empty line and would otherwise start reporting a legitimate second paragraph. Note this is the same axis as the entry above, because declaring the description in [`registry/repos.json`][repos] makes every mirror read a field rather than parse a paragraph and settles the ambiguity by construction, so the two want deciding together rather than one after the other.
-- Rework [`spec/readme-structure.md`][readme-structure] to match the hand-crafted PlexCleaner README, which is the shape the maintainer wants, and make the result auditable rather than advisory. Four concrete divergences are already identified, measured against PlexCleaner `README.md`, this repo's `README.md`, and the current spec. First, the distribution bullet is labeled by deliverable: PlexCleaner ships executables and calls the channel **Binary Releases**, while the spec fixes the label as **Versioned Releases** for every repo, so the label belongs in a per-channel table rather than as one string. Second, the license shield sits in the top **Build Status** block here and at the very bottom of PlexCleaner, inside a closing `## License` section that reads `Licensed under the [MIT License]` followed by the shield, immediately before the link definitions. Third, the Release Notes section closes with `See Release History for complete release notes and older versions.` in PlexCleaner against `See Release History for the full history.` here, and the PlexCleaner form is the wanted one. Note that PlexCleaner writes that link inline, which the reference-style rule forbids, so adopt the wording and keep the reference form. Fourth, the channel bullets and their shields vary by deliverable, meaning GitHub binaries, Docker Hub, NuGet, and PyPI each carry a different bullet label and a different shield set, which is what a per-type table has to encode for the `readme-structure` audit dimension to check a repo against its own declared types.
-- Decide whether the canonical README section order follows PlexCleaner, which is a separate question from the four divergences above and affects every repo plus the `readme-structure` audit. PlexCleaner places **Questions or Issues** immediately after the Table of Contents, where the spec orders it ninth, and it carries sections the spec names nowhere, including Performance Considerations, Runtime Metrics, Custom Plugins, Testing, Development Tooling, Feature Ideas, and Sample Media Files. Under the recurrence rule in [`spec/section-model.md`][section-model] those last ones are correctly repo-specific and stay undeclared, so the open question is only the position of the sections the spec already names.
-- Declare locally-required secrets the way GitHub-stored ones are already declared, and make a gitignored `secrets/` directory the fleet standard that holds them. [`spec/secrets.json`][secrets] covers only the Actions and Dependabot stores, so a repo that deploys somewhere has no declared way to say what it needs at runtime, and the required set is discoverable only by reading the deploy. The pattern already runs in the fleet in two shapes: HomeAutomation-Config keeps a gitignored secrets directory of env files and Docker secret files, and ESPHome-Config keeps a gitignored `secrets.yaml` beside a committed `_secrets.yaml`. The committed file carries the required names with dummy values, so the shape of the requirement is in git while the values never are, which is the same split the GitHub side already gets from `requiredSecrets[]`. Blog needs it immediately, since it deploys on the proxmox host through HomeAutomation-Config's Docker Compose stack and carries the copy destinations and the internal URI. The hub carries neither the directory nor a `.gitignore` entry for one today, so adopting it here comes first. Note that the **GitHub** side has the same missing axis, surfaced by the `hugo` type: a deploy's credentials are per-environment GitHub Environment secrets and variables, `stores` is a closed enum of `actions` and `dependabot`, and `spec/audit.py` seeds `required_by_store` with those two keys and indexes it unguarded, so adding an `environments` value to the enum raises `KeyError` for every repo whose `publish[]` maps to that mechanism. The type landed with an optional `environments` block added to [`spec/secrets.schema.json`][secrets-schema] and described in `spec/secrets.json`'s note, so a repo that needs it may declare its per-environment names and the shape is legal rather than an invention. The hub's own `spec/secrets.json` carries no such block, having no environments of its own, and no tool reads one where it exists. That is honest but it is not a gate, so a clean audit says nothing about whether an environment is configured. Solving it properly means a store vocabulary that does not crash on an unknown key and a per-environment secrets and variables fetch, and it is the same axis as the local half above rather than a separate problem.
-- Canonicalize Python linter-config placement on `pyproject.toml`, since one cataloged repo uses a standalone `.ruff.toml` plus `pyrightconfig.json`. Track it as a drift finding and fix it downstream.
-- 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. This is paced by maintainer capacity rather than blocked on anything, since repos are brought up to spec as they are worked on, so the entry records the outstanding set rather than a defect.
-- Revisit automating the audit, which was explored and deliberately deferred, recorded here so the reasoning is not re-derived from scratch. Three shapes were considered: a scheduled hub-driven audit publishing each report as a workflow artifact, the same thing committing the report back the way the codegen bot updates its own files, and a pull-request hook in each downstream repo that audits itself against the current hub. Three things blocked all of them. Until the fleet reaches stasis with every repo onboarded, a scheduled run reports mostly noise, since a repo mid-onboarding is expected to be non-conformant. The hub has to be stable before downstreams can audit against it, because a hub change lands as fleet-wide findings the same day. And the downstream half is a catch-22, since a self-auditing pull-request hook is CI instrumentation the repos that most need it do not yet carry. The agreed outcome was the on-demand audit that [`AUDIT.md`][audit-doc] describes today. Worth reopening once the fleet is onboarded and the hub goes a stretch without carried-content changes, and the artifact shape is the one to try first, since it produces evidence without committing anything and so cannot generate review load while the noise level is still unknown.
-
-## Onboarding and New Types
-
-- Give [`STANDUP.md`][standup] an explicit branch-bootstrap step, because it currently says nothing about how `main` and `develop` come into being and an agent therefore commits onto whichever branch it finds. Note that section 0A now covers the human-gated prerequisites from [#490][issue-490], so this is the remaining half of that gap rather than the whole of it. The sequence that avoids every cleanup problem is: create `main` and leave it carrying nothing, create `develop` from `main` and leave it carrying nothing, create the first feature branch from `develop` and do the whole standup there, add the repo to GitHub and apply the repo config while still on that branch, then open a normal pull request to `develop` when the repo is ready. Nothing ever has to be cleaned off `main` or `develop`, because nothing ever reached them without review. Note the mechanical wrinkle when writing this up: a git branch cannot exist without a commit, so "carrying nothing" means exactly one signed empty root commit (`git commit --allow-empty`), and section 0's signing window applies to that commit like any other. The alternative of committing onto `develop` and squashing afterwards does not work: `non_fast_forward` is set on both `develop` payloads, so the history cannot be rewritten without disabling the ruleset, and Blog was correctly blocked when it tried. Worth stating that the protection is uneven, since a `release` repo's `repo-config/develop.json` carries a `pull_request` rule that blocks a direct commit outright, while `repo-config/operational/develop.json` carries only `deletion`, `non_fast_forward` and `required_signatures`, so on an operational repo a direct commit succeeds and only the instruction stands between the agent and an unfixable history. The reason it matters on a public repo is that the exploratory standup history is where PII, secrets and noise commits accumulate, and squashing a feature branch is the one chance to leave them out.
-- The static-site generator type from [#456][issue-456] and [#558][issue-558] has landed as `hugo`, with the deploy destination as the `self-hosted` publish target and the `deploy-ssh` mechanism. Correct the record while reading this, because three details the intake predicted are wrong against what Blog actually runs, and planning from the prediction would encode requirements the repo does not meet: the theme is **vendored with no recorded upstream ref**, not a Dependabot-tracked submodule; the generator is **pinned by version and SHA256**, not run at latest; and the deploy is a **separate dispatch** from the GitHub release, not a tag cut last after the live check. What was settled and did hold: the deploy is a publish, the type is named for the generator with the generic checks phrased so they do not name it, and the URL parity gate asserting a floor on the golden list length before comparing is the check of record. What remains: promote the generator-agnostic `hugo.*` checks to a shared type when a second generator arrives, which `spec/type-model.md` "Generators" makes a registry edit by construction, and decide how a `hugo` repository is meant to carry its theme at all, which the type declares nothing about today. The candidates are the vendored copy Blog actually ships, a submodule pinned to an upstream ref, and a separate fleet-owned repository the site consumes, and they differ along exactly the axis the carried-content entries above are about, since a vendored theme is a copy that goes stale with nothing detecting it and a submodule is a pin that Dependabot can see. Settle it as a question about the type rather than about Blog, because whatever is decided becomes the type's contract and the second generator inherits it. Also still true and stated nowhere else, the `copilot_code_review` rule in both ruleset payloads does not gate a merge today because gated Copilot review is an invite-only beta, which deserves a sentence near the merge gate so no repo reads the rule as the enforcement and relaxes the manual discipline actually holding the line.
-- Finish onboarding hardening (from [#310][issue-310]): make the [`AUDIT.md`][audit-doc] 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.
-- Add a linter-only Python project type for codegen and boilerplate Python, code that runs during another tool's build to emit generated source (for example 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`.
-
-## Host and Environment
-
-- State the rule that an agent works only in its own checkout, in its own directory, on its own feature branch, and never writes to a repository because it happened to be on disk. A clone left in a scratch directory is convenient exactly when it is most dangerous, since the operations that cross the boundary are the ordinary ones rather than the reckless ones. A blanket `git add -A` sweeps another agent's uncommitted work into your commit, a `git reset --hard` deletes it outright, and a branch switch carries it along into a change it has nothing to do with. This session produced the first of those: a blanket add swept a second agent's in-progress registration work into an unrelated commit and pushed it, and the work survived only because it was rescued and restored by hand afterwards. Care does not make a shared working tree safe, because every one of those commands is correct in isolation and wrong only because of who else is in the directory. Two things to settle when writing it. Whether the rule is stated as one checkout per agent or one checkout per task, since a single agent moving between two repositories in one directory hits the same hazard as two agents sharing one. And what an agent does when it finds a foreign checkout anyway, where the answer is to leave it alone and clone its own rather than to work carefully in it.
-- Extend the same rule to **reading**, which is the more common case and the easier one to think is harmless. A clone on disk is not the branch it names. It is whatever that clone was last fetched to, so reading it to answer what a repository carries answers a different question, which is what that clone last saw. The failure is silent, because the read succeeds and returns a plausible answer. This session produced two instances. A detection pass over local clones reported one repository as still drifted on a file whose fix had already merged, because that clone's refs predated the merge, and the correction came from a fetch rather than from the read. A second pass then reported a repository as missing a file it does carry, because the local checkout sat on a branch behind the one being measured. State the working practice with the rule: read the live ref through the API where a claim will be acted on, or fetch immediately before reading, and name the ref and commit in any finding derived from a local read so a reader can tell what was actually measured. Note the exception worth keeping, which is that a local clone is the right tool for anything needing history or a build, since those are what an API read cannot give.
-
-- Finish the [#365][issue-365] rollout, which has two halves and one of them is invisible from here. Four machines are still unchecked, WSL2 Ubuntu, the MacBook Air, and both ThinkPads, plus any headless or cron environment that runs Claude Code with the token. A ticked row means the `CLAUDE.md` text and not the hook, since only running `host-setup/agent-safety/install.sh` deploys both layers, and the proxmox host proved that distinction the hard way by carrying the documentary half alone for eight days on the very machine where the incident originated. Note also the follow-up left open on this host and never applied, that the superseded `## Safety rules` section from [#364][issue-364] still sits above the canonical `agent-safety v1` block in `~/.claude/CLAUDE.md`, so the two overlap. Removing the superseded section is a judgment call on a per-machine file, which is why it was surfaced rather than applied.
-- Fill in the remaining cells of the [#483][issue-483] host tooling matrix, which is the reference that makes the per-machine chore above repeatable, so the two close together rather than either alone. Linux, Windows and WSL2 are filled in and verified. **macOS** needs someone on that platform, the **Proxmox** question is whether that host is a shell for agent work or also runs containers, which decides whether `docker` is required there at all, and the engine-inside-the-distro variant of the WSL2 `docker` cell is still unverified since that host only exercised the Docker Desktop integration. Honor the issue's own rule when filling a cell, that an unverified install command is worse than a blank, because a blank prompts a question while a wrong command produces a broken host and a false sense that setup succeeded.
-
-## Fleet Chores
-
-- Measure review rounds against pull request size, and decide what the number licenses. The recent loops suggest a large change earns a different finding every round while a small one converges in one or two, which would make change size the lever on review cost rather than the reviewer's thoroughness, and would argue for splitting a change before review rather than discovering it through five rounds of findings. The data needs no new instrumentation, since the review history already carries it: for each recent pull request, record the diff size in files and lines, the number of rounds, and the findings per round, counting suppressed findings alongside threaded ones because they are the majority of what these loops produce. The outcome worth having is a threshold [`GOVERNANCE.md`][governance] can state in the branching or review guidance, expressed as the size at which a change is split rather than as advice to keep changes small. Note two confounds before drawing a line from the numbers. A large change is usually also a novel one, so size and unfamiliarity move together and the record should note what kind of change each was. And a round that finds something new is not evidence of a problem by itself, since a round that finds something new is the reviewer working, so the metric to watch is findings that a smaller first cut would have surfaced earlier rather than findings per round on its own.
-- Try local defensive-review subagents as a first pass before the remote reviewer, and measure what the pass is worth. The remote loop is thorough and it is also where most of a session's tokens and wall-clock go, and it delivers its findings one round at a time, which is the slowest available way to learn that a change had five problems. A local pass prompted adversarially, one agent per lens rather than one general reviewer, would surface the mechanical half before the branch is even pushed. Scope the experiment to what it can actually prove: run both for a stretch, record which findings the local pass caught that the remote reviewer then raised anyway, and keep it only where that overlap is large enough to shorten the remote loop rather than to add a step in front of it. Note the trap that makes this worth designing carefully rather than just trying. A local pass that finds nothing reads exactly like a clean change, and the next inference from there is that the remote review can be skipped, which is the one outcome the review contract exists to prevent, so the local pass is an input to the loop and never a substitute for the round the merge gate requires.
-- Record a disproved review finding somewhere the next round will read it, so the same proof is not built twice. [`.github/copilot-instructions.md`][copilot-instructions] already says the reviewer is sometimes factually wrong, already requires a decline to carry evidence, and already keeps a list of known non-working request paths, which is the shape this wants. What it has nowhere to put is the finding itself, so a claim disproved against a downloaded binary in one session is argued from scratch in the next. The worked example is the claim that `keys_unsorted` needs jq 1.6, disproved against a 1.5 binary on which `keys_unsorted` works and `walk/1` does not. Note the reason this is not simply a list to append to, which is that a disproof is true of one tree at one revision, so an entry outliving the code it was proved against becomes a reason not to check, and that is strictly worse than re-proving it. Each entry therefore records what was tested and against which revision, and an entry whose subject changes is deleted rather than edited.
-- Refresh the README, which 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, since it must track what the docs contain.
-- 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][issue-363]).
-- Sweep `ManagePackageVersionsCentrally` placement to `Directory.Packages.props` fleet-wide, since PlexCleaner sets it in `Directory.Build.props`, off the CODESTYLE canonical.
-- Consider renaming this repo to reflect the audit-catalog identity, which updates badge and link URLs across the fleet.
-
-<!-- Issues -->
-
-[issue-305]: https://github.com/ptr727/ProjectTemplate/issues/305
-[issue-310]: https://github.com/ptr727/ProjectTemplate/issues/310
-[issue-353]: https://github.com/ptr727/ProjectTemplate/issues/353
-[issue-363]: https://github.com/ptr727/ProjectTemplate/issues/363
-[issue-364]: https://github.com/ptr727/ProjectTemplate/issues/364
-[issue-365]: https://github.com/ptr727/ProjectTemplate/issues/365
-[issue-379]: https://github.com/ptr727/ProjectTemplate/issues/379
-[issue-456]: https://github.com/ptr727/ProjectTemplate/issues/456
-[issue-483]: https://github.com/ptr727/ProjectTemplate/issues/483
-[issue-489]: https://github.com/ptr727/ProjectTemplate/issues/489
-[issue-490]: https://github.com/ptr727/ProjectTemplate/issues/490
-[issue-509]: https://github.com/ptr727/ProjectTemplate/issues/509
-[issue-519]: https://github.com/ptr727/ProjectTemplate/issues/519
-[issue-521]: https://github.com/ptr727/ProjectTemplate/issues/521
-[issue-523]: https://github.com/ptr727/ProjectTemplate/issues/523
-[issue-552]: https://github.com/ptr727/ProjectTemplate/issues/552
-[issue-558]: https://github.com/ptr727/ProjectTemplate/issues/558
-[issue-570]: https://github.com/ptr727/ProjectTemplate/issues/570
-
-<!-- Pull requests -->
-
-[pr-537]: https://github.com/ptr727/ProjectTemplate/pull/537
-[pr-572]: https://github.com/ptr727/ProjectTemplate/pull/572
-
-<!-- Repo -->
-
-[agent-safety]: ./host-setup/agent-safety/
-[agents]: ./AGENTS.md
-[audit]: ./spec/audit.py
-[audit-doc]: ./AUDIT.md
-[codestyle]: ./CODESTYLE.md
-[copilot-instructions]: ./.github/copilot-instructions.md
-[divergences]: ./spec/divergences.json
-[divergences-report]: ./reports/divergences.md
-[files]: ./spec/files.json
-[governance]: ./GOVERNANCE.md
-[markdownlint]: ./.markdownlint-cli2.jsonc
-[matrix]: ./reports/conformance-matrix.md
-[operations]: ./OPERATIONS.md
-[pr-review]: ./scripts/pr_review.py
-[prose-lint]: ./scripts/prose_lint.py
-[readme-structure]: ./spec/readme-structure.md
-[repo-gate]: ./scripts/repo_gate.py
-[reports]: ./reports/
-[repos]: ./registry/repos.json
-[scripts]: ./scripts/README.md
-[secrets]: ./spec/secrets.json
-[secrets-schema]: ./spec/secrets.schema.json
-[section-model]: ./spec/section-model.md
-[standup]: ./STANDUP.md
-[workflows]: ./catalog/snippets/workflows/
-[write-guard]: ./host-setup/agent-safety/gh-write-guard.py
+# TODO
+
+Running backlog for this repo, kept in a committed file so the guidance survives across environments where agent memory does not. Entries are grouped by the surface they change rather than by priority, since an entry's cost is mostly set by what it touches. Where an open issue covers the same ground it is named on the entry, so the two are read together rather than worked twice.
+
+Every issue claim below was re-checked against `develop` at `1ed0cc8` on 2026-08-03, and the entries added from the onboarding-feedback pass were checked against `develop` at `b82c1a3` on 2026-08-05. An issue records the tree as it was on the day it was filed, so a claim in one is a starting point for a check rather than a finding to act on.
+
+## Verified Complete, Awaiting Close
+
+Each of these was checked line by line against the current tree and has nothing left to do here. Closing them is the maintainer's call, and each wants the evidence quoted in the closing comment rather than a bare close.
+
+- [#509][issue-509] (PhotoCleaner spec questions) is complete on all five items. Item 1, `.github/copilot-instructions.md` now reads "Most of `GOVERNANCE.md` is universal fleet law" and describes `AGENTS.md` as the thin router carrying two byte-locked sections and no repository-specific ones. Item 2, `CODESTYLE.md` "Markdown and Spelling" now names `details` and `summary` as allowed, matching [`.markdownlint-cli2.jsonc`][markdownlint]. Item 3, [`spec/readme-structure.md`][readme-structure] now states the private-repository behavior outright, that the full shape is carried and the GitHub-sourced badges render broken until the flip, which is accepted rather than worked around. Item 4, the same file now says the `HISTORY.md` mirror rule lives in `CODESTYLE.md`, which every repo carries, so the rule has a carried home and the file states only what the audit does with it. Item 5, `WORKFLOW.md` D2.2 now reads "the check exits early while the job still reports success" and spells out why a job-level `if:` would couple the release to smoke through `needs:`.
+- [#490][issue-490] (STANDUP has no repo-creation step) is complete on all four suggestions. [`STANDUP.md`][standup] carries a new section 0A, "Hand Over What Only the Maintainer Can Supply", listing the repository, the installed App, the App secret values in both stores, and every declared publish credential and environment. It states that a repo with no remote is not partially stood up but not started, and that a blocking prerequisite is escalated the moment it is found rather than carried, which is the failure mode the issue diagnosed in the agent's own task list. Step 4 now opens with `gh repo view` and carries the ruleset ordering constraint that the issue asked for.
+- [#489][issue-489] (Blog carry findings) is closed on all six items by the maintainer's own status table, five fixed and one resolved as needing no change. The single piece of follow-through it leaves is the `repo-config/configure.sh` re-vendor, which is already carried by the re-vendor entry below rather than by this issue.
+- [#379][issue-379] (Financial-Modeling fidelity findings) is dispositioned on all six items, and the manifest gap the follow-up raised was fixed by adding `repo-config/configure.sh` and `repo-config/settings.json` to [`spec/files.json`][files]. What holds it open is a downstream acknowledgement and that repo's own re-vendor, neither of which is hub work.
+- [#353][issue-353] (`.editorconfig` relaxes all analyzers) is done hub-side, and the tree confirms it, since `dotnet_analyzer_diagnostic.severity` no longer appears in `.editorconfig`. What holds it open is the downstream re-vendor across six C# repos, sequenced in the issue so PhotoCleaner's 362 sites do not gate the other five. That is cross-repo work needing the maintainer to name the repos.
+
+## Gate Honesty
+
+The gates in [`scripts/`][scripts] are hub-only and are the fleet's main defense against agent-authored drift, so a gate that reports clean without having read anything is the worst failure available here. The `gh-write-guard` hook in [`host-setup/agent-safety/`][agent-safety] is grouped with them, since it is the same kind of instrument even though it ships per host rather than per repo. These entries are ordered so the scope floor lands before anything relies on a clean verdict.
+
+- Make [`prose_lint.py`][prose-lint] assert a floor on its own scope, applying to itself the rule [`GOVERNANCE.md`][governance] already states: a gate that finds nothing is indistinguishable from a gate with nothing to find. A `--diff` run that resolves a non-empty diff and then matches **zero** files has almost certainly failed to scope rather than found a clean change, so it should say so instead of exiting 0. One session produced four separate routes to that same false clean: an unresolvable base widening to a whole-tree scan, a multi-line `paths` input read only to its first newline, a diff taken in one repository while scanning another, and a path under no repository at all. Each was fixed with its own guard, which is the wrong shape, because the fifth route will need a fifth guard and will be found the same way the first four were, by a reviewer rather than by the gate. A floor assertion covers the family. Note the honest limit before building it: a change touching only files the gate does not read (an image, a lock file) legitimately scopes to zero, so the assertion compares against the diff's own file list rather than against zero alone. This lands first, because every entry below it produces verdicts that are only worth reading once the gate can prove it read something.
+- Clear the [#519][issue-519] prose backlog, starting with `catalog/snippets/**`. Two of the four changes that issue planned have already landed and its headline numbers are stale, so re-measure before quoting anything from it. `comment-wrap` and `comment-case` are now in `DEFAULT_RULES`, and `reports/` is now exempt as a generated tree, which is why the current figures are **559** whole-tree under the default rules and **184** under `catalog/snippets` alone rather than the 668 and 119 the issue records. The whole-tree figure is the one that moves, having been 534 when this entry was written and 520 by the time [#570][issue-570] scoped the semicolon exemption to the sentence it lives in, which reported 44 semicolons the rule had been silent on. Re-measure it rather than quoting it, since a fix to the gate moves it as readily as a fix to the prose does. The snippets lead the fix order for the reason the issue gives, that a non-conformant snippet seeds its violations into every repo that adopts it and the downstream repo is then flagged for content it was handed. What remains undecided is whether the gate itself becomes a carried file rather than a hub-only one, which is the same question the entry below on hub-only machinery asks from the other direction.
+- Gate the pattern-detectable half of the representative-data rule in [`prose_lint.py`][prose-lint], meaning an absolute home path (`/home/<name>`, `/Users/<name>`, `C:\Users\<name>`) or a bare drive letter sitting in committed prose, a code comment, or a fixture. [`GOVERNANCE.md`][governance] "Representative Data in Agent-Authored Text" states the rule and says why a check is a floor rather than an answer, so the check is introduced as covering the easy half or it gets read as closing the rule, which is the specific way it would make things worse. Three things to settle when writing it. The exemption carries the whole burden, since the rule's own wording, the `host-setup/` docs, and the audit's examples all quote path shapes in order to describe them, and a wrong exemption hands out a work list that damages correct documents. The leak that motivated the rule was in a pull request comment, which no committed-file linter reads at all, so say what surface the gate covers rather than letting its name imply the rule. And a home path in an operational repo's runbook may be the literal path an operator types, which is the repo's own content rather than an agent quoting the maintainer's environment, so decide whether the finding is scoped by file, by repo type, or left for the author to judge.
+- Teach the `sha-pin` check in [`repo_gate.py`][repo-gate] to verify a pin **resolves**, not merely that it is shaped like a SHA. Forty hex characters is a format any fabricated string satisfies, and an agent hand-writing a plausible SHA into a workflow is a real failure mode rather than a hypothetical one. A resolvability check also catches the neighboring case, a pin whose commit was reachable only from a branch that has since been squashed and deleted, which breaks a downstream gate long after the change that caused it. Scope the network call to same-owner repositories, where the fleet's own actions live, and skip rather than fail when the host is offline so the local gate stays usable. Note that the existing `gh-write-guard` hook cannot cover this, since it watches Bash and an editor tool writing the same string into a file never reaches it.
+- Add a check that a pull request's **description** does not contradict its own branch. Three stale descriptions in one session generated six review findings between them, each one a reviewer noticing that the body named a commit, a branch, or a behavior the branch no longer carried. The cheap and precise form is to extract SHAs and `uses:` refs quoted in the body and confirm each still appears in the head tree, since those are the claims that go stale silently and the ones a reviewer actually catches. Prose claims are out of scope, and deliberately so: judging those needs a similarity heuristic, which [`spec/section-model.md`][section-model] already rejects for exactly the reason it would fail here.
+- Reconsider whether the pre-commit hook should run the doc gates now that they are diff-scoped. [`scripts/README.md`][scripts] records the current decision and its reason, that doc linters stay out of the hook so it stays fast, and that reason was sound when the only mode was a whole-tree sweep. A `--diff` run reads the lines one commit touches and finishes in about a second, so the trade has moved. The failure it would prevent is the most repeated one on record: comment sentences wrapped across lines, caught by CI or by a reviewer after the commit rather than before it, over and over within a single session. Weigh it against the standing preference for a fast hook, and against the risk of a hook that runs the gate from the wrong directory, which is its own false clean.
+- Audit the fleet's shell surface by size and branching, and decide per script whether Python with unit tests is the cheaper form. The evidence is the review record rather than a language preference: a non-trivial shell script earns findings round after round, while every gate under [`scripts/`][scripts] carries a `test_<script>.py` beside it and converges in one or two. `repo-config/configure.sh` and `host-setup/agent-safety/install.sh` are the two worth measuring, and the measure is lines, branch count, and the review rounds each has actually cost, not a general claim about the two languages. Two constraints bound the answer before anything is rewritten. A bootstrap script runs before anything is installed, so an installer that needs the Python it exists to install is not a rewrite worth having, which protects `install.sh` more than it protects `configure.sh`. And `configure.sh` is carried `verbatim` to the fleet, so changing its form is a re-vendor for every repository holding it, which makes this the same visit as the hub-hosted tooling entry below rather than a separate one.
+- Move the commands that keep failing the same way into helper functions, rather than restating the rule they keep failing against, per [#580][issue-580]. Two are on record. A command run from the wrong working directory, which does not error and instead returns a confident answer about a different tree. And a GitHub node id typed by hand into a mutation, which the `gh-write-guard` hook correctly refused because the id had not come from a query in that same command. The second is the instructive one, since the rule it broke is stated plainly in [`GOVERNANCE.md`][governance] and in the host-level guidance, and an agent that had read both still reached for the literal, which says the shape of the operation is what fails rather than the agent's knowledge of the rule. A reply-and-resolve helper in [`pr_review.py`][pr-review] would take a pull request number and a finding, query the thread ids itself, and never put an id anywhere a hand could type one, which removes the failure instead of detecting it. Note the dependency: a helper only helps where it can be run, so this is worth building only alongside the question below about whether a downstream repository can reach a hub script at all.
+- Fix the newline parsing in [`gh-write-guard.py`][write-guard], where `_git_subcommand_arglists` ends a `git push` argument list at `&&` but not at a newline, so every token on a later line of the same command is read as a refspec. Measured against the installed hook, `git push -u origin revendor/x` alone resolves to the one branch, while the same push followed by a newline and `gh pr create` with a base of `develop` resolves to five, meaning `revendor/x`, `gh`, `pr`, `create`, and `develop`. The `&&` form resolves correctly, which is what isolates the defect to the newline case. The direction of the error is over-blocking rather than under-blocking, so it is a usability defect rather than a safety hole, and that is exactly why it is worth fixing rather than tolerating: the denial tells the agent it is attempting a direct push to a protected branch that only lands by bypassing a rule with admin power, when the push targets an ordinary feature branch. An agent that believes the message either escalates a push needing no escalation or goes looking for a way around the guard, and teaching a safety hook to cry wolf is how it stops being read. Note the fix reaches every host only when `host-setup/agent-safety/install.sh` is re-run, so it lands with the rollout work in [#365][issue-365] rather than ahead of it, and the entry to write alongside the fix is a self-test case for the newline form, since the existing suite covers the `&&` form and passed throughout.
+
+## Carried Content and Propagation
+
+Everything here changes a file the fleet holds a copy of, so each entry costs a hub edit plus a sweep, and the sweep is the part that gets skipped.
+
+- Re-vendor the changed `verbatim` content across the fleet, which is one sweep covering five files. `repo-config/configure.sh` is carried `verbatim` with `appliesTo: "*"` and the hub swept it to one sentence per line. In `AGENTS.md`, "Context and Delegation Discipline" carries the wait rule's failure clause and "Where the Rules Live" carries a row for the new section named below. In `GOVERNANCE.md`, "Verification Discipline" carries the rule that a launched process is not a result, "PR Review Etiquette" carries the five outcomes that close a finding, "Repository Boundaries and Write Safety" carries the rule that a refused write is reported rather than re-shaped, and "Representative Data in Agent-Authored Text" is an entirely new carried section that no downstream repo holds, which the audit reports as a missing section rather than as drift. Three further `GOVERNANCE.md` sections differ by a single word each, "Documentation Style Conventions", "Communicating with the User" and "Repository Details", where the format's name was capitalized to the convention `CODESTYLE.md` "Markdown and Spelling" now states, so they are byte-mismatched for a reason a reader of the diff would otherwise call cosmetic. Two comment lines in `.markdownlint-cli2.jsonc` took the same capitalization, and that file is `verbatim` and `whole`, so every downstream copy is byte-mismatched on a config nothing else changed about. `CODESTYLE.md` carries the new item and is the fifth file, at `intent` rather than `verbatim` fidelity, so it reaches the fleet as a rule each repo adopts in its own copy rather than as bytes to match, and the same mixed spelling is waiting in every downstream tree. Every repo already holding a copy of a changed section is byte-mismatched against the hub until it takes the new one, which the audit reports as stale rather than modified. This sweep is also the follow-through [#489][issue-489] and [#379][issue-379] were waiting on, and the `.editorconfig` line in [#353][issue-353] rides the same visit to each repo. Regenerate [reports/divergences.md][divergences-report] before using it as the work list, since the committed copy is dated 2026-07-22 and therefore predates the router split, which shows in it naming "Repository Boundaries and Write Safety", "Git and Commit Rules" and "Verification Discipline" as `AGENTS.md` sections when all three now live in `GOVERNANCE.md`. A stale ledger is the same hazard as a stale exemption, in that it hands out a work list measured against a tree that no longer exists.
+- Drop the unused `GITHUB_TOKEN` grants from the merge-bot workflow, per [#521][issue-521], which the tree confirms is still open, since all four jobs still carry `contents: write` and `pull-requests: write` while every write in the file authenticates with the App token. The finding is least privilege on the highest-blast-radius shape in the fleet, a `pull_request_target` workflow holding an App private key, where the grant is not exploitable today only because no step consumes it. Three things to settle: whether to drop the job-level blocks or set a workflow-level `permissions: {}`, whether the audit should compare permissions at all given the file is `interface` fidelity with only a `requiredJobKeys` contract, and the re-vendor, since every repo carries the file. Note that [`spec/files.json`][files] now declares this workflow at `appliesTo: "*"`, which closes the separate gap [#456][issue-456] raised, that D8.1 graded a file the file spec never required.
+- State the rule that an agent never assumes a Docker image is present locally, however recently it pulled one, because a background prune can remove an image between two commands of the same session and the run then fails on something that worked minutes earlier. The prescription is the always-pull flag by default, and an explicit `docker pull <image>:<tag>` before use where the flag does not apply. The four documented lint invocations already carry `--pull=always`, in [`GOVERNANCE.md`][governance] "Running the Linters Locally", mirrored in [`OPERATIONS.md`][operations] and both VS Code task snippets, so what is missing is the rule rather than the one-liners: an agent composing an ad-hoc `docker run` drops the flag precisely because it believes the image is already cached. Two things to settle when writing it. Where it lives, since that section is scoped to the four lint tools while the rule covers any container an agent starts, which argues for placing it with the Docker or verification guidance instead, and whether it is carried to the fleet, since every repo runs the same images from the same instructions. Note the limit before writing it, so the flag does not read as the whole answer: `docker run` against a registry tag re-pulls an absent image on its own, so the cases that actually break are a locally built tag with no registry to pull from, and any command that branches on the image being present (`docker image inspect`, `docker images`) rather than simply running it.
+- Decide where a carried file may name hub-only machinery, per [#580][issue-580], since `GOVERNANCE.md` "PR Review Etiquette" points at `scripts/pr_review.py` and the fleet carries the section but not the script. A downstream reader follows that pointer to a path their repo does not have. Either the script joins the carried set, or the rule states the behavior and drops the tool name the way the coordination-reference rule already requires for the template repo itself. The cost of leaving it unresolved is measured rather than hypothetical, because downstream agents hand-roll the review and prose checks the hub already ships. Several sessions had to be redirected to [`pr_review.py`][pr-review] and [`prose_lint.py`][prose-lint] by hand, each one having built its own worse version of a gate that exists, and none of them did anything wrong, since the tool they were pointed at is not in their tree and nothing they can read says how to reach it. A rule that names a tool its reader cannot run is worse than either resolution, because it teaches the reader that a pointer in carried text is decorative.
+- Define the fleet's own vocabulary somewhere a repository with no history will find it, per [#579][issue-579], because the words a request is phrased in are defined nowhere it can read. **Hub** is used throughout these docs and in every request asking a repository to reconcile or audit itself against the canonical, and no file states that it means this repository, so a repository carrying no instruction set has to be told what the hub is, where it lives, and which file to open, by hand, each time. The review loop has the opposite shape of the same problem: [`GOVERNANCE.md`][governance] "Expected Review Loop" states the procedure precisely and never presents its name as the way to ask for it, so every request improvises a phrasing and the scope an agent reads out of it moves with the wording. A defined term is what makes "close the review loop on #123" a complete instruction. Two things to settle. Where the definitions live, since the natural home is the byte-locked Fleet Bootstrap section of [`AGENTS.md`][agents] and a repository with no carried instruction set is precisely the one that does not have it, which leaves the hub's own `README.md` as the only surface a stranger to the fleet reads first. And whether the entry point is named per task rather than per repository state, since the bootstrap section already routes correctly and the gap is that the router is unreachable rather than that it is wrong. Note that an edit to the byte-locked section lands with [#552][issue-552], which already holds that section open, rather than as a change of its own.
+- Revisit [#305][issue-305], which asks for a propagation path for the rule docs and is the oldest open issue here, because most of the machinery it asked for has since been built and the issue has not been re-scoped to match. The fidelity model, the `spec/files.json` manifest, [`spec/divergences.json`][divergences] with its generated [reports/divergences.md][divergences-report], and [`AUDIT.md`][audit-doc] section 10 together give the canonical-versus-adapted split and the audit path the issue proposed. What is genuinely still missing is the push half, since every one of those detects drift while the sweep that fixes it is manual, which is exactly the entry above. Either re-scope the issue to the push half or close it against the entry above and the audit-automation entry below.
+- Reduce the surface that is copied downstream at all, since every carried file is a copy that breaks when it is not the current one. `repo-config/configure.sh` is the worked example from this session: a defect in its check mode was fixed once in the hub and immediately turned into a re-vendor owed by every repository carrying it, and until each takes the fix they run different logic while reporting the same command. A repository that misses the sweep does not fail loudly. It quietly audits itself with an older script. The alternative is for the hub to host the tool and for each downstream repository to call it rather than hold a copy, so one edit reaches the fleet and no stale copy exists to detect, re-vendor, or classify. This is the same argument as the reusable-workflow entry below and should be settled with it rather than separately, since both are about consuming hub code at runtime instead of vendoring it. Three things to settle. What the fleet actually needs vendored, which is the content a repository is audited against and could not run without, against what only needs to be reachable. How a consumed tool is pinned, because consuming hub code at runtime is a floating dependency unless it names a commit, and the action-pinning rule already requires exactly that. And what a repository does when the hub is unreachable, since a vendored copy still works offline and a called one does not, which is the real cost being traded away. The fleet already runs both models without either having been chosen against the other, since `repo-config/configure.sh` is carried while every gate under [`scripts/`][scripts] is hub-only, and the wanted end state is the second one: a script that is identical everywhere lives in the hub once and a downstream repository calls it, which removes the re-vendor rather than scheduling it. The near-term half needs no decision to start on, which is deleting a downstream config script whose content is only ever the hub's, because a per-repo copy of a file with no per-repo content is drift waiting to be detected and nothing is lost by not having it.
+- Investigate replacing copy-pasted workflow content with cross-repo reuse, now that this repo is public. A public repository's composite actions and reusable workflows can be consumed by any other repository regardless of owner type, so the organization account this pattern was assumed to require is not needed, and the constraint that shaped the current vendor-everything model no longer holds. The catalog under [`catalog/snippets/workflows/`][workflows] is copied into each repo today, which means a fix to a shared job is a sweep across the fleet rather than one edit here, and it is the mechanism by which a defect in a snippet seeds itself into every repo that adopted it. Scope the investigation to which jobs are genuinely identical across repos against which only look similar, since a reusable workflow that needs a long input list to cover per-repo variation is worse than the copy it replaces. Settle the ref policy in the same pass, because consuming hub code at CI time is a floating dependency unless it is pinned, and [`GOVERNANCE.md`][governance] "Action pinning" requires a commit SHA for every action with one documented exception. Note that `uses:` does not accept expressions, so a per-branch ref cannot be selected in the workflow file and any branch-dependent behavior belongs inside the consumed action instead.
+- Make a table of contents standard for a long document rather than for the README alone. [`spec/readme-structure.md`][readme-structure] fixes one at README position 4 and [`GOVERNANCE.md`][governance] states how it is generated and which headings it excludes, and no other file in the hub carries one, which leaves the three longest documents in the fleet without the thing that makes them navigable: `CODESTYLE.md` at 516 lines, `GOVERNANCE.md` at 421, and `WORKFLOW.md` at 298. Two things to settle. The threshold, stated in headings or lines rather than left to judgment, so the audit can check it and no repository is put in the position of arguing that its own document is short. And how it sits with the reference-link exception, since the four agent-instruction files keep inline links exactly because they are read one section at a time, which is the same property that makes a contents list worth having in them, and the generated list is already the one exception that rule carries. Note the mechanical constraint before adopting it, that the list is filled by the Markdown All in One extension on save, so a file nobody opens in the editor grows a stale contents list rather than none, and a stale one is worse than absent because it is read as current.
+- State that an operational repository still opens a pull request for a large or risky change, even though its model permits committing straight to `develop`, which is item 3 of [#578][issue-578]. [`GOVERNANCE.md`][governance] "Operational Repositories" grants the direct commit and says nothing about when to decline the grant, and `repo-config/operational/develop.json` carries only `deletion`, `non_fast_forward` and `required_signatures`, so nothing mechanical stands between an agent and a large unreviewed change landing on the live surface. The reason the grant exists is the one-line config edit that a review round costs more than it protects, and that reason stops applying well before a change gets large. Settle what counts as large, and prefer a stated shape over a line count, since the property that matters is whether the change can be read at a glance and reverted cleanly rather than how many lines it moved. Note that this stays guidance by construction, because adding a `pull_request` rule to the operational ruleset would withdraw the direct-commit grant that the whole model exists to give.
+- Say when an issue is closed by hand, not only that the closing keyword belongs on the promotion pull request, which is item 1 of [#578][issue-578]. [`GOVERNANCE.md`][governance] "Git and Commit Rules" already states that `Closes #N` fires only on a merge into the default branch and therefore goes on the `develop -> main` promotion, and downstream agents keep re-deriving that rule and reporting it as a discovery, which says it is being missed rather than that it is missing. What the rule genuinely does not cover is the case that produces the confusion, which is work complete on `develop` while a promotion is not imminent, leaving the issue open with nothing on it recording that it is done. The current text licenses a hand-close only once a promotion has merged without the keyword, which is the narrower case. Widen it to say that an issue is closed when the work is verifiably complete, citing the squash SHA that completed it, and that the promotion keyword is the automation for the common case rather than the only permitted route. [#552][issue-552] is the live example, fixed by the merge of [#572][pr-572] and open at the time of writing.
+- Say that the message carrying the clickable link comes **before** the prompt it accompanies, which is item 2 of [#578][issue-578] and which [`GOVERNANCE.md`][governance] "Communicating with the User" leaves unstated. The rule already gets the hard part right, that an interactive prompt renders neither a Markdown link nor a bare URL, so the reference inside it is a bare `#123` and the link goes in the message that accompanies it. It says accompanying rather than preceding, and a message emitted after the prompt is not read before the question is answered, which is the entire outcome the rule exists to produce. This keeps recurring in practice, so read the recurrence as the wording being underspecified rather than as the rule being ignored, which is the same diagnosis the entry above reaches about the closing keyword.
+
+## Audit and Spec Model
+
+- Teach the audit to see content sitting in the wrong file, per [#523][issue-523], which the tree confirms is untouched, since [`spec/audit.py`][audit] still checks file presence, declared-section presence, verbatim hashes, and workflow interface conformance and nothing that reads a heading against a destination. The case that found it is a repo whose `.github/copilot-instructions.md` carried 311 lines under nine headings that [`spec/section-model.md`][section-model] assigns to `ARCHITECTURE.md` and `OPERATIONS.md`, reported as a missing-file letter while the misplacement that caused it was invisible. The shape that fits the engine is structural, collecting the level-two headings of an `intent` file, subtracting the ones [`spec/files.json`][files] declares for it, and comparing the remainder against the headings other destinations declare. The similarity-based version is explicitly rejected by `section-model.md`, and a detector built on it produces findings whose remedy is to delete content. Four things to settle, all in the issue: whether an undeclared heading is a finding at all given a repo may add locally, whether the destination mapping becomes declared data rather than prose, whether it reaches the advisory `ARCHITECTURE.md`, and how many repos are affected, which is measured before the check is designed rather than after it starts reporting.
+- State what a `driftNote` may contain at the moment one is written, not only what happens to it once the deviation clears, and widen the check that guards it. [`AUDIT.md`][audit-doc] section 8 says a note records a current deviation and is deleted once resolved, which is a rule about a note's end of life and leaves an agent authoring one with no rule about its content. PhotoCleaner is the worked example, in [#537][pr-537]: asked to self-audit and reconcile its notes, the agent wrote a completion record ("baseline onboarding completed"), a historical fact (the date a past version first published), and a description of the repo conforming to the README spec. All three are prose about the past or about compliance rather than a current deviation, and none of them is what the field is for. Read that as an incomplete instruction rather than an agent ignoring one, since nothing it was given forbids any of the three. Two things to settle. The rule wants stating positively at authoring time, that a note names a deviation that is true right now and would still be true if nobody read it, so history, completion, and conformance are each out by construction, and a repo doing exactly what the spec requires earns no note at all. And the detector needs the same widening, because [`spec/audit.py`][audit] currently flags a stale note by matching words that assert *outstanding* work ("pending", "not yet", "missing", "behind"), which is the opposite polarity to all three of PhotoCleaner's notes, and it only runs that check when the repo audits clean, which PhotoCleaner did not until the round that found this. A guard that fires only on one polarity, and only in the state where the problem has already gone, cannot see the failure it exists to catch. Note the limit before building it, since it is the same limit the section model already records: judging whether a sentence describes a current deviation is a semantic call, so the honest target is the shapes that are mechanically recognizable, a past-tense completion verb and an explicit date among them, with the rest left to the rule.
+- Declare the canonical short description in [`registry/repos.json`][repos] instead of deriving it by parsing the README, which makes every check and every push deterministic. Today [`spec/audit.py`][audit] extracts the intro line after the H1 and compares the GitHub About panel and the Docker Hub short description against it, so the source of truth lives inside prose. That forces anything wanting the value to parse Markdown, and PhotoCleaner#32 shows the cost, since a workflow step that reads the intro at publish time needs nine guards against headings, block quotes, all four list markers, ordered lists, HTML, tables, code, links and the length cap, and every one of them fails the release rather than the tagline. Adding a `description` field turns the README intro into a third mirror rather than the source, so the audit compares all three against one declared value, the Docker workflow pushes a literal with no parser, and `repo-config/configure.sh` can set the GitHub About panel from the same field it already sets every other repository setting from. The 100-character cap stays, since Docker Hub's short description is still the tightest surface. Add the field to `registry/repos.schema.json` as well, which sets `additionalProperties: false`, and make it optional at first so the audit falls back to the README intro while repos adopt it one at a time. The disposition is recorded on [#509][issue-509], and the ask on the Docker repos is only that the parsing step is not propagated further while the field is pending.
+- Let the README intro carry more than the tagline, and say which line the mirrors actually take, per [#577][issue-577]. [`spec/readme-structure.md`][readme-structure] item 1 reads as though the canonical description **is** the paragraph after the H1, capped at 100 characters and link-free, and [`CODESTYLE.md`][codestyle] "Markdown and Spelling" then has `HISTORY.md` copy "the same intro paragraph" verbatim. Read together they forbid a README from saying anything further about itself above the fold, which is a real cost on a repository whose purpose needs a sentence of context, and the cap they enforce exists for Docker Hub's short description rather than for the reader. State the shape instead: the first line after the H1 is the tagline, it alone is bound by the 100-character link-free rule, and it alone mirrors to the GitHub About panel, the Docker Hub short description, and the `HISTORY.md` opening, with any further paragraph free prose that no mirror reads and no cap applies to. The audit changes with it, since it currently measures the first non-empty line and would otherwise start reporting a legitimate second paragraph. Note this is the same axis as the entry above, because declaring the description in [`registry/repos.json`][repos] makes every mirror read a field rather than parse a paragraph and settles the ambiguity by construction, so the two want deciding together rather than one after the other.
+- Rework [`spec/readme-structure.md`][readme-structure] to match the hand-crafted PlexCleaner README, which is the shape the maintainer wants, and make the result auditable rather than advisory. Four concrete divergences are already identified, measured against PlexCleaner `README.md`, this repo's `README.md`, and the current spec. First, the distribution bullet is labeled by deliverable: PlexCleaner ships executables and calls the channel **Binary Releases**, while the spec fixes the label as **Versioned Releases** for every repo, so the label belongs in a per-channel table rather than as one string. Second, the license shield sits in the top **Build Status** block here and at the very bottom of PlexCleaner, inside a closing `## License` section that reads `Licensed under the [MIT License]` followed by the shield, immediately before the link definitions. Third, the Release Notes section closes with `See Release History for complete release notes and older versions.` in PlexCleaner against `See Release History for the full history.` here, and the PlexCleaner form is the wanted one. Note that PlexCleaner writes that link inline, which the reference-style rule forbids, so adopt the wording and keep the reference form. Fourth, the channel bullets and their shields vary by deliverable, meaning GitHub binaries, Docker Hub, NuGet, and PyPI each carry a different bullet label and a different shield set, which is what a per-type table has to encode for the `readme-structure` audit dimension to check a repo against its own declared types.
+- Decide whether the canonical README section order follows PlexCleaner, which is a separate question from the four divergences above and affects every repo plus the `readme-structure` audit. PlexCleaner places **Questions or Issues** immediately after the Table of Contents, where the spec orders it ninth, and it carries sections the spec names nowhere, including Performance Considerations, Runtime Metrics, Custom Plugins, Testing, Development Tooling, Feature Ideas, and Sample Media Files. Under the recurrence rule in [`spec/section-model.md`][section-model] those last ones are correctly repo-specific and stay undeclared, so the open question is only the position of the sections the spec already names.
+- Declare locally-required secrets the way GitHub-stored ones are already declared, and make a gitignored `secrets/` directory the fleet standard that holds them. [`spec/secrets.json`][secrets] covers only the Actions and Dependabot stores, so a repo that deploys somewhere has no declared way to say what it needs at runtime, and the required set is discoverable only by reading the deploy. The pattern already runs in the fleet in two shapes: HomeAutomation-Config keeps a gitignored secrets directory of env files and Docker secret files, and ESPHome-Config keeps a gitignored `secrets.yaml` beside a committed `_secrets.yaml`. The committed file carries the required names with dummy values, so the shape of the requirement is in git while the values never are, which is the same split the GitHub side already gets from `requiredSecrets[]`. Blog needs it immediately, since it deploys on the proxmox host through HomeAutomation-Config's Docker Compose stack and carries the copy destinations and the internal URI. The hub carries neither the directory nor a `.gitignore` entry for one today, so adopting it here comes first. Note that the **GitHub** side has the same missing axis, surfaced by the `hugo` type: a deploy's credentials are per-environment GitHub Environment secrets and variables, `stores` is a closed enum of `actions` and `dependabot`, and `spec/audit.py` seeds `required_by_store` with those two keys and indexes it unguarded, so adding an `environments` value to the enum raises `KeyError` for every repo whose `publish[]` maps to that mechanism. The type landed with an optional `environments` block added to [`spec/secrets.schema.json`][secrets-schema] and described in `spec/secrets.json`'s note, so a repo that needs it may declare its per-environment names and the shape is legal rather than an invention. The hub's own `spec/secrets.json` carries no such block, having no environments of its own, and no tool reads one where it exists. That is honest but it is not a gate, so a clean audit says nothing about whether an environment is configured. Solving it properly means a store vocabulary that does not crash on an unknown key and a per-environment secrets and variables fetch, and it is the same axis as the local half above rather than a separate problem.
+- Canonicalize Python linter-config placement on `pyproject.toml`, since one cataloged repo uses a standalone `.ruff.toml` plus `pyrightconfig.json`. Track it as a drift finding and fix it downstream.
+- 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. This is paced by maintainer capacity rather than blocked on anything, since repos are brought up to spec as they are worked on, so the entry records the outstanding set rather than a defect.
+- Revisit automating the audit, which was explored and deliberately deferred, recorded here so the reasoning is not re-derived from scratch. Three shapes were considered: a scheduled hub-driven audit publishing each report as a workflow artifact, the same thing committing the report back the way the codegen bot updates its own files, and a pull-request hook in each downstream repo that audits itself against the current hub. Three things blocked all of them. Until the fleet reaches stasis with every repo onboarded, a scheduled run reports mostly noise, since a repo mid-onboarding is expected to be non-conformant. The hub has to be stable before downstreams can audit against it, because a hub change lands as fleet-wide findings the same day. And the downstream half is a catch-22, since a self-auditing pull-request hook is CI instrumentation the repos that most need it do not yet carry. The agreed outcome was the on-demand audit that [`AUDIT.md`][audit-doc] describes today. Worth reopening once the fleet is onboarded and the hub goes a stretch without carried-content changes, and the artifact shape is the one to try first, since it produces evidence without committing anything and so cannot generate review load while the noise level is still unknown.
+
+## Onboarding and New Types
+
+- Give [`STANDUP.md`][standup] an explicit branch-bootstrap step, because it currently says nothing about how `main` and `develop` come into being and an agent therefore commits onto whichever branch it finds. Note that section 0A now covers the human-gated prerequisites from [#490][issue-490], so this is the remaining half of that gap rather than the whole of it. The sequence that avoids every cleanup problem is: create `main` and leave it carrying nothing, create `develop` from `main` and leave it carrying nothing, create the first feature branch from `develop` and do the whole standup there, add the repo to GitHub and apply the repo config while still on that branch, then open a normal pull request to `develop` when the repo is ready. Nothing ever has to be cleaned off `main` or `develop`, because nothing ever reached them without review. Note the mechanical wrinkle when writing this up: a git branch cannot exist without a commit, so "carrying nothing" means exactly one signed empty root commit (`git commit --allow-empty`), and section 0's signing window applies to that commit like any other. The alternative of committing onto `develop` and squashing afterwards does not work: `non_fast_forward` is set on both `develop` payloads, so the history cannot be rewritten without disabling the ruleset, and Blog was correctly blocked when it tried. Worth stating that the protection is uneven, since a `release` repo's `repo-config/develop.json` carries a `pull_request` rule that blocks a direct commit outright, while `repo-config/operational/develop.json` carries only `deletion`, `non_fast_forward` and `required_signatures`, so on an operational repo a direct commit succeeds and only the instruction stands between the agent and an unfixable history. The reason it matters on a public repo is that the exploratory standup history is where PII, secrets and noise commits accumulate, and squashing a feature branch is the one chance to leave them out.
+- The static-site generator type from [#456][issue-456] and [#558][issue-558] has landed as `hugo`, with the deploy destination as the `self-hosted` publish target and the `deploy-ssh` mechanism. Correct the record while reading this, because three details the intake predicted are wrong against what Blog actually runs, and planning from the prediction would encode requirements the repo does not meet: the theme is **vendored with no recorded upstream ref**, not a Dependabot-tracked submodule; the generator is **pinned by version and SHA256**, not run at latest; and the deploy is a **separate dispatch** from the GitHub release, not a tag cut last after the live check. What was settled and did hold: the deploy is a publish, the type is named for the generator with the generic checks phrased so they do not name it, and the URL parity gate asserting a floor on the golden list length before comparing is the check of record. What remains: promote the generator-agnostic `hugo.*` checks to a shared type when a second generator arrives, which `spec/type-model.md` "Generators" makes a registry edit by construction, and decide how a `hugo` repository is meant to carry its theme at all, which the type declares nothing about today. The candidates are the vendored copy Blog actually ships, a submodule pinned to an upstream ref, and a separate fleet-owned repository the site consumes, and they differ along exactly the axis the carried-content entries above are about, since a vendored theme is a copy that goes stale with nothing detecting it and a submodule is a pin that Dependabot can see. Settle it as a question about the type rather than about Blog, because whatever is decided becomes the type's contract and the second generator inherits it. Also still true and stated nowhere else, the `copilot_code_review` rule in both ruleset payloads does not gate a merge today because gated Copilot review is an invite-only beta, which deserves a sentence near the merge gate so no repo reads the rule as the enforcement and relaxes the manual discipline actually holding the line.
+- Finish onboarding hardening (from [#310][issue-310]): make the [`AUDIT.md`][audit-doc] 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.
+- Add a linter-only Python project type for codegen and boilerplate Python, code that runs during another tool's build to emit generated source (for example 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`.
+
+## Host and Environment
+
+- State the rule that an agent works only in its own checkout, in its own directory, on its own feature branch, and never writes to a repository because it happened to be on disk. A clone left in a scratch directory is convenient exactly when it is most dangerous, since the operations that cross the boundary are the ordinary ones rather than the reckless ones. A blanket `git add -A` sweeps another agent's uncommitted work into your commit, a `git reset --hard` deletes it outright, and a branch switch carries it along into a change it has nothing to do with. This session produced the first of those: a blanket add swept a second agent's in-progress registration work into an unrelated commit and pushed it, and the work survived only because it was rescued and restored by hand afterwards. Care does not make a shared working tree safe, because every one of those commands is correct in isolation and wrong only because of who else is in the directory. Two things to settle when writing it. Whether the rule is stated as one checkout per agent or one checkout per task, since a single agent moving between two repositories in one directory hits the same hazard as two agents sharing one. And what an agent does when it finds a foreign checkout anyway, where the answer is to leave it alone and clone its own rather than to work carefully in it.
+- Extend the same rule to **reading**, which is the more common case and the easier one to think is harmless. A clone on disk is not the branch it names. It is whatever that clone was last fetched to, so reading it to answer what a repository carries answers a different question, which is what that clone last saw. The failure is silent, because the read succeeds and returns a plausible answer. This session produced two instances. A detection pass over local clones reported one repository as still drifted on a file whose fix had already merged, because that clone's refs predated the merge, and the correction came from a fetch rather than from the read. A second pass then reported a repository as missing a file it does carry, because the local checkout sat on a branch behind the one being measured. State the working practice with the rule: read the live ref through the API where a claim will be acted on, or fetch immediately before reading, and name the ref and commit in any finding derived from a local read so a reader can tell what was actually measured. Note the exception worth keeping, which is that a local clone is the right tool for anything needing history or a build, since those are what an API read cannot give.
+
+- Finish the [#365][issue-365] rollout, which has two halves and one of them is invisible from here. Four machines are still unchecked, WSL2 Ubuntu, the MacBook Air, and both ThinkPads, plus any headless or cron environment that runs Claude Code with the token. A ticked row means the `CLAUDE.md` text and not the hook, since only running `host-setup/agent-safety/install.sh` deploys both layers, and the proxmox host proved that distinction the hard way by carrying the documentary half alone for eight days on the very machine where the incident originated. Note also the follow-up left open on this host and never applied, that the superseded `## Safety rules` section from [#364][issue-364] still sits above the canonical `agent-safety v1` block in `~/.claude/CLAUDE.md`, so the two overlap. Removing the superseded section is a judgment call on a per-machine file, which is why it was surfaced rather than applied.
+- Fill in the remaining cells of the [#483][issue-483] host tooling matrix, which is the reference that makes the per-machine chore above repeatable, so the two close together rather than either alone. Linux, Windows and WSL2 are filled in and verified. **macOS** needs someone on that platform, the **Proxmox** question is whether that host is a shell for agent work or also runs containers, which decides whether `docker` is required there at all, and the engine-inside-the-distro variant of the WSL2 `docker` cell is still unverified since that host only exercised the Docker Desktop integration. Honor the issue's own rule when filling a cell, that an unverified install command is worse than a blank, because a blank prompts a question while a wrong command produces a broken host and a false sense that setup succeeded.
+
+## Fleet Chores
+
+- Measure review rounds against pull request size, and decide what the number licenses. The recent loops suggest a large change earns a different finding every round while a small one converges in one or two, which would make change size the lever on review cost rather than the reviewer's thoroughness, and would argue for splitting a change before review rather than discovering it through five rounds of findings. The data needs no new instrumentation, since the review history already carries it: for each recent pull request, record the diff size in files and lines, the number of rounds, and the findings per round, counting suppressed findings alongside threaded ones because they are the majority of what these loops produce. The outcome worth having is a threshold [`GOVERNANCE.md`][governance] can state in the branching or review guidance, expressed as the size at which a change is split rather than as advice to keep changes small. Note two confounds before drawing a line from the numbers. A large change is usually also a novel one, so size and unfamiliarity move together and the record should note what kind of change each was. And a round that finds something new is not evidence of a problem by itself, since a round that finds something new is the reviewer working, so the metric to watch is findings that a smaller first cut would have surfaced earlier rather than findings per round on its own.
+- Try local defensive-review subagents as a first pass before the remote reviewer, and measure what the pass is worth. The remote loop is thorough and it is also where most of a session's tokens and wall-clock go, and it delivers its findings one round at a time, which is the slowest available way to learn that a change had five problems. A local pass prompted adversarially, one agent per lens rather than one general reviewer, would surface the mechanical half before the branch is even pushed. Scope the experiment to what it can actually prove: run both for a stretch, record which findings the local pass caught that the remote reviewer then raised anyway, and keep it only where that overlap is large enough to shorten the remote loop rather than to add a step in front of it. Note the trap that makes this worth designing carefully rather than just trying. A local pass that finds nothing reads exactly like a clean change, and the next inference from there is that the remote review can be skipped, which is the one outcome the review contract exists to prevent, so the local pass is an input to the loop and never a substitute for the round the merge gate requires.
+- Record a disproved review finding somewhere the next round will read it, so the same proof is not built twice. [`.github/copilot-instructions.md`][copilot-instructions] already says the reviewer is sometimes factually wrong, already requires a decline to carry evidence, and already keeps a list of known non-working request paths, which is the shape this wants. What it has nowhere to put is the finding itself, so a claim disproved against a downloaded binary in one session is argued from scratch in the next. The worked example is the claim that `keys_unsorted` needs jq 1.6, disproved against a 1.5 binary on which `keys_unsorted` works and `walk/1` does not. Note the reason this is not simply a list to append to, which is that a disproof is true of one tree at one revision, so an entry outliving the code it was proved against becomes a reason not to check, and that is strictly worse than re-proving it. Each entry therefore records what was tested and against which revision, and an entry whose subject changes is deleted rather than edited.
+- Refresh the README, which 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, since it must track what the docs contain.
+- 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][issue-363]).
+- Sweep `ManagePackageVersionsCentrally` placement to `Directory.Packages.props` fleet-wide, since PlexCleaner sets it in `Directory.Build.props`, off the CODESTYLE canonical.
+- Consider renaming this repo to reflect the audit-catalog identity, which updates badge and link URLs across the fleet.
+
+<!-- Issues -->
+
+[issue-305]: https://github.com/ptr727/ProjectTemplate/issues/305
+[issue-310]: https://github.com/ptr727/ProjectTemplate/issues/310
+[issue-353]: https://github.com/ptr727/ProjectTemplate/issues/353
+[issue-363]: https://github.com/ptr727/ProjectTemplate/issues/363
+[issue-364]: https://github.com/ptr727/ProjectTemplate/issues/364
+[issue-365]: https://github.com/ptr727/ProjectTemplate/issues/365
+[issue-379]: https://github.com/ptr727/ProjectTemplate/issues/379
+[issue-456]: https://github.com/ptr727/ProjectTemplate/issues/456
+[issue-483]: https://github.com/ptr727/ProjectTemplate/issues/483
+[issue-489]: https://github.com/ptr727/ProjectTemplate/issues/489
+[issue-490]: https://github.com/ptr727/ProjectTemplate/issues/490
+[issue-509]: https://github.com/ptr727/ProjectTemplate/issues/509
+[issue-519]: https://github.com/ptr727/ProjectTemplate/issues/519
+[issue-521]: https://github.com/ptr727/ProjectTemplate/issues/521
+[issue-523]: https://github.com/ptr727/ProjectTemplate/issues/523
+[issue-552]: https://github.com/ptr727/ProjectTemplate/issues/552
+[issue-558]: https://github.com/ptr727/ProjectTemplate/issues/558
+[issue-570]: https://github.com/ptr727/ProjectTemplate/issues/570
+[issue-577]: https://github.com/ptr727/ProjectTemplate/issues/577
+[issue-578]: https://github.com/ptr727/ProjectTemplate/issues/578
+[issue-579]: https://github.com/ptr727/ProjectTemplate/issues/579
+[issue-580]: https://github.com/ptr727/ProjectTemplate/issues/580
+
+<!-- Pull requests -->
+
+[pr-537]: https://github.com/ptr727/ProjectTemplate/pull/537
+[pr-572]: https://github.com/ptr727/ProjectTemplate/pull/572
+
+<!-- Repo -->
+
+[agent-safety]: ./host-setup/agent-safety/
+[agents]: ./AGENTS.md
+[audit]: ./spec/audit.py
+[audit-doc]: ./AUDIT.md
+[codestyle]: ./CODESTYLE.md
+[copilot-instructions]: ./.github/copilot-instructions.md
+[divergences]: ./spec/divergences.json
+[divergences-report]: ./reports/divergences.md
+[files]: ./spec/files.json
+[governance]: ./GOVERNANCE.md
+[markdownlint]: ./.markdownlint-cli2.jsonc
+[matrix]: ./reports/conformance-matrix.md
+[operations]: ./OPERATIONS.md
+[pr-review]: ./scripts/pr_review.py
+[prose-lint]: ./scripts/prose_lint.py
+[readme-structure]: ./spec/readme-structure.md
+[repo-gate]: ./scripts/repo_gate.py
+[reports]: ./reports/
+[repos]: ./registry/repos.json
+[scripts]: ./scripts/README.md
+[secrets]: ./spec/secrets.json
+[secrets-schema]: ./spec/secrets.schema.json
+[section-model]: ./spec/section-model.md
+[standup]: ./STANDUP.md
+[workflows]: ./catalog/snippets/workflows/
+[write-guard]: ./host-setup/agent-safety/gh-write-guard.py

From 7ec472c903c1094bfd919588b13a8754d843625c Mon Sep 17 00:00:00 2001
From: Pieter Viljoen <ptr727@users.noreply.github.com>
Date: Wed, 5 Aug 2026 19:56:35 -0700
Subject: [PATCH 3/3] Restore CRLF line endings on TODO.md

The previous commit rewrote the file through a Python helper that reads
with universal newlines and writes back plain LF, so every line in the
file changed ending while eight lines changed content. `.editorconfig`
declares CRLF the default and lists TODO.md in none of the LF
exceptions, so the file was correct before and is correct again.

The content is byte-identical to the previous commit:

```console
$ git diff --ignore-cr-at-eol HEAD --stat
$
```

Neither local gate catches this, and their scopes say why. `repo_gate.py
--check eol` compares the `.gitattributes` LF pins against the
`.editorconfig` overrides and reads no file content at all, so a
whole-file ending flip is outside what it measures. `prose_lint.py`
reads lines rather than terminators. CI would have caught it, since
editorconfig-checker enforces the `[*] end_of_line = crlf` default, so
the gap is in the pre-push loop rather than in the defenses.

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 TODO.md | 288 ++++++++++++++++++++++++++++----------------------------
 1 file changed, 144 insertions(+), 144 deletions(-)

diff --git a/TODO.md b/TODO.md
index 21552c78..2ac4df94 100644
--- a/TODO.md
+++ b/TODO.md
@@ -1,144 +1,144 @@
-# TODO
-
-Running backlog for this repo, kept in a committed file so the guidance survives across environments where agent memory does not. Entries are grouped by the surface they change rather than by priority, since an entry's cost is mostly set by what it touches. Where an open issue covers the same ground it is named on the entry, so the two are read together rather than worked twice.
-
-Every issue claim below was re-checked against `develop` at `1ed0cc8` on 2026-08-03, and the entries added from the onboarding-feedback pass were checked against `develop` at `b82c1a3` on 2026-08-05. An issue records the tree as it was on the day it was filed, so a claim in one is a starting point for a check rather than a finding to act on.
-
-## Verified Complete, Awaiting Close
-
-Each of these was checked line by line against the current tree and has nothing left to do here. Closing them is the maintainer's call, and each wants the evidence quoted in the closing comment rather than a bare close.
-
-- [#509][issue-509] (PhotoCleaner spec questions) is complete on all five items. Item 1, `.github/copilot-instructions.md` now reads "Most of `GOVERNANCE.md` is universal fleet law" and describes `AGENTS.md` as the thin router carrying two byte-locked sections and no repository-specific ones. Item 2, `CODESTYLE.md` "Markdown and Spelling" now names `details` and `summary` as allowed, matching [`.markdownlint-cli2.jsonc`][markdownlint]. Item 3, [`spec/readme-structure.md`][readme-structure] now states the private-repository behavior outright, that the full shape is carried and the GitHub-sourced badges render broken until the flip, which is accepted rather than worked around. Item 4, the same file now says the `HISTORY.md` mirror rule lives in `CODESTYLE.md`, which every repo carries, so the rule has a carried home and the file states only what the audit does with it. Item 5, `WORKFLOW.md` D2.2 now reads "the check exits early while the job still reports success" and spells out why a job-level `if:` would couple the release to smoke through `needs:`.
-- [#490][issue-490] (STANDUP has no repo-creation step) is complete on all four suggestions. [`STANDUP.md`][standup] carries a new section 0A, "Hand Over What Only the Maintainer Can Supply", listing the repository, the installed App, the App secret values in both stores, and every declared publish credential and environment. It states that a repo with no remote is not partially stood up but not started, and that a blocking prerequisite is escalated the moment it is found rather than carried, which is the failure mode the issue diagnosed in the agent's own task list. Step 4 now opens with `gh repo view` and carries the ruleset ordering constraint that the issue asked for.
-- [#489][issue-489] (Blog carry findings) is closed on all six items by the maintainer's own status table, five fixed and one resolved as needing no change. The single piece of follow-through it leaves is the `repo-config/configure.sh` re-vendor, which is already carried by the re-vendor entry below rather than by this issue.
-- [#379][issue-379] (Financial-Modeling fidelity findings) is dispositioned on all six items, and the manifest gap the follow-up raised was fixed by adding `repo-config/configure.sh` and `repo-config/settings.json` to [`spec/files.json`][files]. What holds it open is a downstream acknowledgement and that repo's own re-vendor, neither of which is hub work.
-- [#353][issue-353] (`.editorconfig` relaxes all analyzers) is done hub-side, and the tree confirms it, since `dotnet_analyzer_diagnostic.severity` no longer appears in `.editorconfig`. What holds it open is the downstream re-vendor across six C# repos, sequenced in the issue so PhotoCleaner's 362 sites do not gate the other five. That is cross-repo work needing the maintainer to name the repos.
-
-## Gate Honesty
-
-The gates in [`scripts/`][scripts] are hub-only and are the fleet's main defense against agent-authored drift, so a gate that reports clean without having read anything is the worst failure available here. The `gh-write-guard` hook in [`host-setup/agent-safety/`][agent-safety] is grouped with them, since it is the same kind of instrument even though it ships per host rather than per repo. These entries are ordered so the scope floor lands before anything relies on a clean verdict.
-
-- Make [`prose_lint.py`][prose-lint] assert a floor on its own scope, applying to itself the rule [`GOVERNANCE.md`][governance] already states: a gate that finds nothing is indistinguishable from a gate with nothing to find. A `--diff` run that resolves a non-empty diff and then matches **zero** files has almost certainly failed to scope rather than found a clean change, so it should say so instead of exiting 0. One session produced four separate routes to that same false clean: an unresolvable base widening to a whole-tree scan, a multi-line `paths` input read only to its first newline, a diff taken in one repository while scanning another, and a path under no repository at all. Each was fixed with its own guard, which is the wrong shape, because the fifth route will need a fifth guard and will be found the same way the first four were, by a reviewer rather than by the gate. A floor assertion covers the family. Note the honest limit before building it: a change touching only files the gate does not read (an image, a lock file) legitimately scopes to zero, so the assertion compares against the diff's own file list rather than against zero alone. This lands first, because every entry below it produces verdicts that are only worth reading once the gate can prove it read something.
-- Clear the [#519][issue-519] prose backlog, starting with `catalog/snippets/**`. Two of the four changes that issue planned have already landed and its headline numbers are stale, so re-measure before quoting anything from it. `comment-wrap` and `comment-case` are now in `DEFAULT_RULES`, and `reports/` is now exempt as a generated tree, which is why the current figures are **559** whole-tree under the default rules and **184** under `catalog/snippets` alone rather than the 668 and 119 the issue records. The whole-tree figure is the one that moves, having been 534 when this entry was written and 520 by the time [#570][issue-570] scoped the semicolon exemption to the sentence it lives in, which reported 44 semicolons the rule had been silent on. Re-measure it rather than quoting it, since a fix to the gate moves it as readily as a fix to the prose does. The snippets lead the fix order for the reason the issue gives, that a non-conformant snippet seeds its violations into every repo that adopts it and the downstream repo is then flagged for content it was handed. What remains undecided is whether the gate itself becomes a carried file rather than a hub-only one, which is the same question the entry below on hub-only machinery asks from the other direction.
-- Gate the pattern-detectable half of the representative-data rule in [`prose_lint.py`][prose-lint], meaning an absolute home path (`/home/<name>`, `/Users/<name>`, `C:\Users\<name>`) or a bare drive letter sitting in committed prose, a code comment, or a fixture. [`GOVERNANCE.md`][governance] "Representative Data in Agent-Authored Text" states the rule and says why a check is a floor rather than an answer, so the check is introduced as covering the easy half or it gets read as closing the rule, which is the specific way it would make things worse. Three things to settle when writing it. The exemption carries the whole burden, since the rule's own wording, the `host-setup/` docs, and the audit's examples all quote path shapes in order to describe them, and a wrong exemption hands out a work list that damages correct documents. The leak that motivated the rule was in a pull request comment, which no committed-file linter reads at all, so say what surface the gate covers rather than letting its name imply the rule. And a home path in an operational repo's runbook may be the literal path an operator types, which is the repo's own content rather than an agent quoting the maintainer's environment, so decide whether the finding is scoped by file, by repo type, or left for the author to judge.
-- Teach the `sha-pin` check in [`repo_gate.py`][repo-gate] to verify a pin **resolves**, not merely that it is shaped like a SHA. Forty hex characters is a format any fabricated string satisfies, and an agent hand-writing a plausible SHA into a workflow is a real failure mode rather than a hypothetical one. A resolvability check also catches the neighboring case, a pin whose commit was reachable only from a branch that has since been squashed and deleted, which breaks a downstream gate long after the change that caused it. Scope the network call to same-owner repositories, where the fleet's own actions live, and skip rather than fail when the host is offline so the local gate stays usable. Note that the existing `gh-write-guard` hook cannot cover this, since it watches Bash and an editor tool writing the same string into a file never reaches it.
-- Add a check that a pull request's **description** does not contradict its own branch. Three stale descriptions in one session generated six review findings between them, each one a reviewer noticing that the body named a commit, a branch, or a behavior the branch no longer carried. The cheap and precise form is to extract SHAs and `uses:` refs quoted in the body and confirm each still appears in the head tree, since those are the claims that go stale silently and the ones a reviewer actually catches. Prose claims are out of scope, and deliberately so: judging those needs a similarity heuristic, which [`spec/section-model.md`][section-model] already rejects for exactly the reason it would fail here.
-- Reconsider whether the pre-commit hook should run the doc gates now that they are diff-scoped. [`scripts/README.md`][scripts] records the current decision and its reason, that doc linters stay out of the hook so it stays fast, and that reason was sound when the only mode was a whole-tree sweep. A `--diff` run reads the lines one commit touches and finishes in about a second, so the trade has moved. The failure it would prevent is the most repeated one on record: comment sentences wrapped across lines, caught by CI or by a reviewer after the commit rather than before it, over and over within a single session. Weigh it against the standing preference for a fast hook, and against the risk of a hook that runs the gate from the wrong directory, which is its own false clean.
-- Audit the fleet's shell surface by size and branching, and decide per script whether Python with unit tests is the cheaper form. The evidence is the review record rather than a language preference: a non-trivial shell script earns findings round after round, while every gate under [`scripts/`][scripts] carries a `test_<script>.py` beside it and converges in one or two. `repo-config/configure.sh` and `host-setup/agent-safety/install.sh` are the two worth measuring, and the measure is lines, branch count, and the review rounds each has actually cost, not a general claim about the two languages. Two constraints bound the answer before anything is rewritten. A bootstrap script runs before anything is installed, so an installer that needs the Python it exists to install is not a rewrite worth having, which protects `install.sh` more than it protects `configure.sh`. And `configure.sh` is carried `verbatim` to the fleet, so changing its form is a re-vendor for every repository holding it, which makes this the same visit as the hub-hosted tooling entry below rather than a separate one.
-- Move the commands that keep failing the same way into helper functions, rather than restating the rule they keep failing against, per [#580][issue-580]. Two are on record. A command run from the wrong working directory, which does not error and instead returns a confident answer about a different tree. And a GitHub node id typed by hand into a mutation, which the `gh-write-guard` hook correctly refused because the id had not come from a query in that same command. The second is the instructive one, since the rule it broke is stated plainly in [`GOVERNANCE.md`][governance] and in the host-level guidance, and an agent that had read both still reached for the literal, which says the shape of the operation is what fails rather than the agent's knowledge of the rule. A reply-and-resolve helper in [`pr_review.py`][pr-review] would take a pull request number and a finding, query the thread ids itself, and never put an id anywhere a hand could type one, which removes the failure instead of detecting it. Note the dependency: a helper only helps where it can be run, so this is worth building only alongside the question below about whether a downstream repository can reach a hub script at all.
-- Fix the newline parsing in [`gh-write-guard.py`][write-guard], where `_git_subcommand_arglists` ends a `git push` argument list at `&&` but not at a newline, so every token on a later line of the same command is read as a refspec. Measured against the installed hook, `git push -u origin revendor/x` alone resolves to the one branch, while the same push followed by a newline and `gh pr create` with a base of `develop` resolves to five, meaning `revendor/x`, `gh`, `pr`, `create`, and `develop`. The `&&` form resolves correctly, which is what isolates the defect to the newline case. The direction of the error is over-blocking rather than under-blocking, so it is a usability defect rather than a safety hole, and that is exactly why it is worth fixing rather than tolerating: the denial tells the agent it is attempting a direct push to a protected branch that only lands by bypassing a rule with admin power, when the push targets an ordinary feature branch. An agent that believes the message either escalates a push needing no escalation or goes looking for a way around the guard, and teaching a safety hook to cry wolf is how it stops being read. Note the fix reaches every host only when `host-setup/agent-safety/install.sh` is re-run, so it lands with the rollout work in [#365][issue-365] rather than ahead of it, and the entry to write alongside the fix is a self-test case for the newline form, since the existing suite covers the `&&` form and passed throughout.
-
-## Carried Content and Propagation
-
-Everything here changes a file the fleet holds a copy of, so each entry costs a hub edit plus a sweep, and the sweep is the part that gets skipped.
-
-- Re-vendor the changed `verbatim` content across the fleet, which is one sweep covering five files. `repo-config/configure.sh` is carried `verbatim` with `appliesTo: "*"` and the hub swept it to one sentence per line. In `AGENTS.md`, "Context and Delegation Discipline" carries the wait rule's failure clause and "Where the Rules Live" carries a row for the new section named below. In `GOVERNANCE.md`, "Verification Discipline" carries the rule that a launched process is not a result, "PR Review Etiquette" carries the five outcomes that close a finding, "Repository Boundaries and Write Safety" carries the rule that a refused write is reported rather than re-shaped, and "Representative Data in Agent-Authored Text" is an entirely new carried section that no downstream repo holds, which the audit reports as a missing section rather than as drift. Three further `GOVERNANCE.md` sections differ by a single word each, "Documentation Style Conventions", "Communicating with the User" and "Repository Details", where the format's name was capitalized to the convention `CODESTYLE.md` "Markdown and Spelling" now states, so they are byte-mismatched for a reason a reader of the diff would otherwise call cosmetic. Two comment lines in `.markdownlint-cli2.jsonc` took the same capitalization, and that file is `verbatim` and `whole`, so every downstream copy is byte-mismatched on a config nothing else changed about. `CODESTYLE.md` carries the new item and is the fifth file, at `intent` rather than `verbatim` fidelity, so it reaches the fleet as a rule each repo adopts in its own copy rather than as bytes to match, and the same mixed spelling is waiting in every downstream tree. Every repo already holding a copy of a changed section is byte-mismatched against the hub until it takes the new one, which the audit reports as stale rather than modified. This sweep is also the follow-through [#489][issue-489] and [#379][issue-379] were waiting on, and the `.editorconfig` line in [#353][issue-353] rides the same visit to each repo. Regenerate [reports/divergences.md][divergences-report] before using it as the work list, since the committed copy is dated 2026-07-22 and therefore predates the router split, which shows in it naming "Repository Boundaries and Write Safety", "Git and Commit Rules" and "Verification Discipline" as `AGENTS.md` sections when all three now live in `GOVERNANCE.md`. A stale ledger is the same hazard as a stale exemption, in that it hands out a work list measured against a tree that no longer exists.
-- Drop the unused `GITHUB_TOKEN` grants from the merge-bot workflow, per [#521][issue-521], which the tree confirms is still open, since all four jobs still carry `contents: write` and `pull-requests: write` while every write in the file authenticates with the App token. The finding is least privilege on the highest-blast-radius shape in the fleet, a `pull_request_target` workflow holding an App private key, where the grant is not exploitable today only because no step consumes it. Three things to settle: whether to drop the job-level blocks or set a workflow-level `permissions: {}`, whether the audit should compare permissions at all given the file is `interface` fidelity with only a `requiredJobKeys` contract, and the re-vendor, since every repo carries the file. Note that [`spec/files.json`][files] now declares this workflow at `appliesTo: "*"`, which closes the separate gap [#456][issue-456] raised, that D8.1 graded a file the file spec never required.
-- State the rule that an agent never assumes a Docker image is present locally, however recently it pulled one, because a background prune can remove an image between two commands of the same session and the run then fails on something that worked minutes earlier. The prescription is the always-pull flag by default, and an explicit `docker pull <image>:<tag>` before use where the flag does not apply. The four documented lint invocations already carry `--pull=always`, in [`GOVERNANCE.md`][governance] "Running the Linters Locally", mirrored in [`OPERATIONS.md`][operations] and both VS Code task snippets, so what is missing is the rule rather than the one-liners: an agent composing an ad-hoc `docker run` drops the flag precisely because it believes the image is already cached. Two things to settle when writing it. Where it lives, since that section is scoped to the four lint tools while the rule covers any container an agent starts, which argues for placing it with the Docker or verification guidance instead, and whether it is carried to the fleet, since every repo runs the same images from the same instructions. Note the limit before writing it, so the flag does not read as the whole answer: `docker run` against a registry tag re-pulls an absent image on its own, so the cases that actually break are a locally built tag with no registry to pull from, and any command that branches on the image being present (`docker image inspect`, `docker images`) rather than simply running it.
-- Decide where a carried file may name hub-only machinery, per [#580][issue-580], since `GOVERNANCE.md` "PR Review Etiquette" points at `scripts/pr_review.py` and the fleet carries the section but not the script. A downstream reader follows that pointer to a path their repo does not have. Either the script joins the carried set, or the rule states the behavior and drops the tool name the way the coordination-reference rule already requires for the template repo itself. The cost of leaving it unresolved is measured rather than hypothetical, because downstream agents hand-roll the review and prose checks the hub already ships. Several sessions had to be redirected to [`pr_review.py`][pr-review] and [`prose_lint.py`][prose-lint] by hand, each one having built its own worse version of a gate that exists, and none of them did anything wrong, since the tool they were pointed at is not in their tree and nothing they can read says how to reach it. A rule that names a tool its reader cannot run is worse than either resolution, because it teaches the reader that a pointer in carried text is decorative.
-- Define the fleet's own vocabulary somewhere a repository with no history will find it, per [#579][issue-579], because the words a request is phrased in are defined nowhere it can read. **Hub** is used throughout these docs and in every request asking a repository to reconcile or audit itself against the canonical, and no file states that it means this repository, so a repository carrying no instruction set has to be told what the hub is, where it lives, and which file to open, by hand, each time. The review loop has the opposite shape of the same problem: [`GOVERNANCE.md`][governance] "Expected Review Loop" states the procedure precisely and never presents its name as the way to ask for it, so every request improvises a phrasing and the scope an agent reads out of it moves with the wording. A defined term is what makes "close the review loop on #123" a complete instruction. Two things to settle. Where the definitions live, since the natural home is the byte-locked Fleet Bootstrap section of [`AGENTS.md`][agents] and a repository with no carried instruction set is precisely the one that does not have it, which leaves the hub's own `README.md` as the only surface a stranger to the fleet reads first. And whether the entry point is named per task rather than per repository state, since the bootstrap section already routes correctly and the gap is that the router is unreachable rather than that it is wrong. Note that an edit to the byte-locked section lands with [#552][issue-552], which already holds that section open, rather than as a change of its own.
-- Revisit [#305][issue-305], which asks for a propagation path for the rule docs and is the oldest open issue here, because most of the machinery it asked for has since been built and the issue has not been re-scoped to match. The fidelity model, the `spec/files.json` manifest, [`spec/divergences.json`][divergences] with its generated [reports/divergences.md][divergences-report], and [`AUDIT.md`][audit-doc] section 10 together give the canonical-versus-adapted split and the audit path the issue proposed. What is genuinely still missing is the push half, since every one of those detects drift while the sweep that fixes it is manual, which is exactly the entry above. Either re-scope the issue to the push half or close it against the entry above and the audit-automation entry below.
-- Reduce the surface that is copied downstream at all, since every carried file is a copy that breaks when it is not the current one. `repo-config/configure.sh` is the worked example from this session: a defect in its check mode was fixed once in the hub and immediately turned into a re-vendor owed by every repository carrying it, and until each takes the fix they run different logic while reporting the same command. A repository that misses the sweep does not fail loudly. It quietly audits itself with an older script. The alternative is for the hub to host the tool and for each downstream repository to call it rather than hold a copy, so one edit reaches the fleet and no stale copy exists to detect, re-vendor, or classify. This is the same argument as the reusable-workflow entry below and should be settled with it rather than separately, since both are about consuming hub code at runtime instead of vendoring it. Three things to settle. What the fleet actually needs vendored, which is the content a repository is audited against and could not run without, against what only needs to be reachable. How a consumed tool is pinned, because consuming hub code at runtime is a floating dependency unless it names a commit, and the action-pinning rule already requires exactly that. And what a repository does when the hub is unreachable, since a vendored copy still works offline and a called one does not, which is the real cost being traded away. The fleet already runs both models without either having been chosen against the other, since `repo-config/configure.sh` is carried while every gate under [`scripts/`][scripts] is hub-only, and the wanted end state is the second one: a script that is identical everywhere lives in the hub once and a downstream repository calls it, which removes the re-vendor rather than scheduling it. The near-term half needs no decision to start on, which is deleting a downstream config script whose content is only ever the hub's, because a per-repo copy of a file with no per-repo content is drift waiting to be detected and nothing is lost by not having it.
-- Investigate replacing copy-pasted workflow content with cross-repo reuse, now that this repo is public. A public repository's composite actions and reusable workflows can be consumed by any other repository regardless of owner type, so the organization account this pattern was assumed to require is not needed, and the constraint that shaped the current vendor-everything model no longer holds. The catalog under [`catalog/snippets/workflows/`][workflows] is copied into each repo today, which means a fix to a shared job is a sweep across the fleet rather than one edit here, and it is the mechanism by which a defect in a snippet seeds itself into every repo that adopted it. Scope the investigation to which jobs are genuinely identical across repos against which only look similar, since a reusable workflow that needs a long input list to cover per-repo variation is worse than the copy it replaces. Settle the ref policy in the same pass, because consuming hub code at CI time is a floating dependency unless it is pinned, and [`GOVERNANCE.md`][governance] "Action pinning" requires a commit SHA for every action with one documented exception. Note that `uses:` does not accept expressions, so a per-branch ref cannot be selected in the workflow file and any branch-dependent behavior belongs inside the consumed action instead.
-- Make a table of contents standard for a long document rather than for the README alone. [`spec/readme-structure.md`][readme-structure] fixes one at README position 4 and [`GOVERNANCE.md`][governance] states how it is generated and which headings it excludes, and no other file in the hub carries one, which leaves the three longest documents in the fleet without the thing that makes them navigable: `CODESTYLE.md` at 516 lines, `GOVERNANCE.md` at 421, and `WORKFLOW.md` at 298. Two things to settle. The threshold, stated in headings or lines rather than left to judgment, so the audit can check it and no repository is put in the position of arguing that its own document is short. And how it sits with the reference-link exception, since the four agent-instruction files keep inline links exactly because they are read one section at a time, which is the same property that makes a contents list worth having in them, and the generated list is already the one exception that rule carries. Note the mechanical constraint before adopting it, that the list is filled by the Markdown All in One extension on save, so a file nobody opens in the editor grows a stale contents list rather than none, and a stale one is worse than absent because it is read as current.
-- State that an operational repository still opens a pull request for a large or risky change, even though its model permits committing straight to `develop`, which is item 3 of [#578][issue-578]. [`GOVERNANCE.md`][governance] "Operational Repositories" grants the direct commit and says nothing about when to decline the grant, and `repo-config/operational/develop.json` carries only `deletion`, `non_fast_forward` and `required_signatures`, so nothing mechanical stands between an agent and a large unreviewed change landing on the live surface. The reason the grant exists is the one-line config edit that a review round costs more than it protects, and that reason stops applying well before a change gets large. Settle what counts as large, and prefer a stated shape over a line count, since the property that matters is whether the change can be read at a glance and reverted cleanly rather than how many lines it moved. Note that this stays guidance by construction, because adding a `pull_request` rule to the operational ruleset would withdraw the direct-commit grant that the whole model exists to give.
-- Say when an issue is closed by hand, not only that the closing keyword belongs on the promotion pull request, which is item 1 of [#578][issue-578]. [`GOVERNANCE.md`][governance] "Git and Commit Rules" already states that `Closes #N` fires only on a merge into the default branch and therefore goes on the `develop -> main` promotion, and downstream agents keep re-deriving that rule and reporting it as a discovery, which says it is being missed rather than that it is missing. What the rule genuinely does not cover is the case that produces the confusion, which is work complete on `develop` while a promotion is not imminent, leaving the issue open with nothing on it recording that it is done. The current text licenses a hand-close only once a promotion has merged without the keyword, which is the narrower case. Widen it to say that an issue is closed when the work is verifiably complete, citing the squash SHA that completed it, and that the promotion keyword is the automation for the common case rather than the only permitted route. [#552][issue-552] is the live example, fixed by the merge of [#572][pr-572] and open at the time of writing.
-- Say that the message carrying the clickable link comes **before** the prompt it accompanies, which is item 2 of [#578][issue-578] and which [`GOVERNANCE.md`][governance] "Communicating with the User" leaves unstated. The rule already gets the hard part right, that an interactive prompt renders neither a Markdown link nor a bare URL, so the reference inside it is a bare `#123` and the link goes in the message that accompanies it. It says accompanying rather than preceding, and a message emitted after the prompt is not read before the question is answered, which is the entire outcome the rule exists to produce. This keeps recurring in practice, so read the recurrence as the wording being underspecified rather than as the rule being ignored, which is the same diagnosis the entry above reaches about the closing keyword.
-
-## Audit and Spec Model
-
-- Teach the audit to see content sitting in the wrong file, per [#523][issue-523], which the tree confirms is untouched, since [`spec/audit.py`][audit] still checks file presence, declared-section presence, verbatim hashes, and workflow interface conformance and nothing that reads a heading against a destination. The case that found it is a repo whose `.github/copilot-instructions.md` carried 311 lines under nine headings that [`spec/section-model.md`][section-model] assigns to `ARCHITECTURE.md` and `OPERATIONS.md`, reported as a missing-file letter while the misplacement that caused it was invisible. The shape that fits the engine is structural, collecting the level-two headings of an `intent` file, subtracting the ones [`spec/files.json`][files] declares for it, and comparing the remainder against the headings other destinations declare. The similarity-based version is explicitly rejected by `section-model.md`, and a detector built on it produces findings whose remedy is to delete content. Four things to settle, all in the issue: whether an undeclared heading is a finding at all given a repo may add locally, whether the destination mapping becomes declared data rather than prose, whether it reaches the advisory `ARCHITECTURE.md`, and how many repos are affected, which is measured before the check is designed rather than after it starts reporting.
-- State what a `driftNote` may contain at the moment one is written, not only what happens to it once the deviation clears, and widen the check that guards it. [`AUDIT.md`][audit-doc] section 8 says a note records a current deviation and is deleted once resolved, which is a rule about a note's end of life and leaves an agent authoring one with no rule about its content. PhotoCleaner is the worked example, in [#537][pr-537]: asked to self-audit and reconcile its notes, the agent wrote a completion record ("baseline onboarding completed"), a historical fact (the date a past version first published), and a description of the repo conforming to the README spec. All three are prose about the past or about compliance rather than a current deviation, and none of them is what the field is for. Read that as an incomplete instruction rather than an agent ignoring one, since nothing it was given forbids any of the three. Two things to settle. The rule wants stating positively at authoring time, that a note names a deviation that is true right now and would still be true if nobody read it, so history, completion, and conformance are each out by construction, and a repo doing exactly what the spec requires earns no note at all. And the detector needs the same widening, because [`spec/audit.py`][audit] currently flags a stale note by matching words that assert *outstanding* work ("pending", "not yet", "missing", "behind"), which is the opposite polarity to all three of PhotoCleaner's notes, and it only runs that check when the repo audits clean, which PhotoCleaner did not until the round that found this. A guard that fires only on one polarity, and only in the state where the problem has already gone, cannot see the failure it exists to catch. Note the limit before building it, since it is the same limit the section model already records: judging whether a sentence describes a current deviation is a semantic call, so the honest target is the shapes that are mechanically recognizable, a past-tense completion verb and an explicit date among them, with the rest left to the rule.
-- Declare the canonical short description in [`registry/repos.json`][repos] instead of deriving it by parsing the README, which makes every check and every push deterministic. Today [`spec/audit.py`][audit] extracts the intro line after the H1 and compares the GitHub About panel and the Docker Hub short description against it, so the source of truth lives inside prose. That forces anything wanting the value to parse Markdown, and PhotoCleaner#32 shows the cost, since a workflow step that reads the intro at publish time needs nine guards against headings, block quotes, all four list markers, ordered lists, HTML, tables, code, links and the length cap, and every one of them fails the release rather than the tagline. Adding a `description` field turns the README intro into a third mirror rather than the source, so the audit compares all three against one declared value, the Docker workflow pushes a literal with no parser, and `repo-config/configure.sh` can set the GitHub About panel from the same field it already sets every other repository setting from. The 100-character cap stays, since Docker Hub's short description is still the tightest surface. Add the field to `registry/repos.schema.json` as well, which sets `additionalProperties: false`, and make it optional at first so the audit falls back to the README intro while repos adopt it one at a time. The disposition is recorded on [#509][issue-509], and the ask on the Docker repos is only that the parsing step is not propagated further while the field is pending.
-- Let the README intro carry more than the tagline, and say which line the mirrors actually take, per [#577][issue-577]. [`spec/readme-structure.md`][readme-structure] item 1 reads as though the canonical description **is** the paragraph after the H1, capped at 100 characters and link-free, and [`CODESTYLE.md`][codestyle] "Markdown and Spelling" then has `HISTORY.md` copy "the same intro paragraph" verbatim. Read together they forbid a README from saying anything further about itself above the fold, which is a real cost on a repository whose purpose needs a sentence of context, and the cap they enforce exists for Docker Hub's short description rather than for the reader. State the shape instead: the first line after the H1 is the tagline, it alone is bound by the 100-character link-free rule, and it alone mirrors to the GitHub About panel, the Docker Hub short description, and the `HISTORY.md` opening, with any further paragraph free prose that no mirror reads and no cap applies to. The audit changes with it, since it currently measures the first non-empty line and would otherwise start reporting a legitimate second paragraph. Note this is the same axis as the entry above, because declaring the description in [`registry/repos.json`][repos] makes every mirror read a field rather than parse a paragraph and settles the ambiguity by construction, so the two want deciding together rather than one after the other.
-- Rework [`spec/readme-structure.md`][readme-structure] to match the hand-crafted PlexCleaner README, which is the shape the maintainer wants, and make the result auditable rather than advisory. Four concrete divergences are already identified, measured against PlexCleaner `README.md`, this repo's `README.md`, and the current spec. First, the distribution bullet is labeled by deliverable: PlexCleaner ships executables and calls the channel **Binary Releases**, while the spec fixes the label as **Versioned Releases** for every repo, so the label belongs in a per-channel table rather than as one string. Second, the license shield sits in the top **Build Status** block here and at the very bottom of PlexCleaner, inside a closing `## License` section that reads `Licensed under the [MIT License]` followed by the shield, immediately before the link definitions. Third, the Release Notes section closes with `See Release History for complete release notes and older versions.` in PlexCleaner against `See Release History for the full history.` here, and the PlexCleaner form is the wanted one. Note that PlexCleaner writes that link inline, which the reference-style rule forbids, so adopt the wording and keep the reference form. Fourth, the channel bullets and their shields vary by deliverable, meaning GitHub binaries, Docker Hub, NuGet, and PyPI each carry a different bullet label and a different shield set, which is what a per-type table has to encode for the `readme-structure` audit dimension to check a repo against its own declared types.
-- Decide whether the canonical README section order follows PlexCleaner, which is a separate question from the four divergences above and affects every repo plus the `readme-structure` audit. PlexCleaner places **Questions or Issues** immediately after the Table of Contents, where the spec orders it ninth, and it carries sections the spec names nowhere, including Performance Considerations, Runtime Metrics, Custom Plugins, Testing, Development Tooling, Feature Ideas, and Sample Media Files. Under the recurrence rule in [`spec/section-model.md`][section-model] those last ones are correctly repo-specific and stay undeclared, so the open question is only the position of the sections the spec already names.
-- Declare locally-required secrets the way GitHub-stored ones are already declared, and make a gitignored `secrets/` directory the fleet standard that holds them. [`spec/secrets.json`][secrets] covers only the Actions and Dependabot stores, so a repo that deploys somewhere has no declared way to say what it needs at runtime, and the required set is discoverable only by reading the deploy. The pattern already runs in the fleet in two shapes: HomeAutomation-Config keeps a gitignored secrets directory of env files and Docker secret files, and ESPHome-Config keeps a gitignored `secrets.yaml` beside a committed `_secrets.yaml`. The committed file carries the required names with dummy values, so the shape of the requirement is in git while the values never are, which is the same split the GitHub side already gets from `requiredSecrets[]`. Blog needs it immediately, since it deploys on the proxmox host through HomeAutomation-Config's Docker Compose stack and carries the copy destinations and the internal URI. The hub carries neither the directory nor a `.gitignore` entry for one today, so adopting it here comes first. Note that the **GitHub** side has the same missing axis, surfaced by the `hugo` type: a deploy's credentials are per-environment GitHub Environment secrets and variables, `stores` is a closed enum of `actions` and `dependabot`, and `spec/audit.py` seeds `required_by_store` with those two keys and indexes it unguarded, so adding an `environments` value to the enum raises `KeyError` for every repo whose `publish[]` maps to that mechanism. The type landed with an optional `environments` block added to [`spec/secrets.schema.json`][secrets-schema] and described in `spec/secrets.json`'s note, so a repo that needs it may declare its per-environment names and the shape is legal rather than an invention. The hub's own `spec/secrets.json` carries no such block, having no environments of its own, and no tool reads one where it exists. That is honest but it is not a gate, so a clean audit says nothing about whether an environment is configured. Solving it properly means a store vocabulary that does not crash on an unknown key and a per-environment secrets and variables fetch, and it is the same axis as the local half above rather than a separate problem.
-- Canonicalize Python linter-config placement on `pyproject.toml`, since one cataloged repo uses a standalone `.ruff.toml` plus `pyrightconfig.json`. Track it as a drift finding and fix it downstream.
-- 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. This is paced by maintainer capacity rather than blocked on anything, since repos are brought up to spec as they are worked on, so the entry records the outstanding set rather than a defect.
-- Revisit automating the audit, which was explored and deliberately deferred, recorded here so the reasoning is not re-derived from scratch. Three shapes were considered: a scheduled hub-driven audit publishing each report as a workflow artifact, the same thing committing the report back the way the codegen bot updates its own files, and a pull-request hook in each downstream repo that audits itself against the current hub. Three things blocked all of them. Until the fleet reaches stasis with every repo onboarded, a scheduled run reports mostly noise, since a repo mid-onboarding is expected to be non-conformant. The hub has to be stable before downstreams can audit against it, because a hub change lands as fleet-wide findings the same day. And the downstream half is a catch-22, since a self-auditing pull-request hook is CI instrumentation the repos that most need it do not yet carry. The agreed outcome was the on-demand audit that [`AUDIT.md`][audit-doc] describes today. Worth reopening once the fleet is onboarded and the hub goes a stretch without carried-content changes, and the artifact shape is the one to try first, since it produces evidence without committing anything and so cannot generate review load while the noise level is still unknown.
-
-## Onboarding and New Types
-
-- Give [`STANDUP.md`][standup] an explicit branch-bootstrap step, because it currently says nothing about how `main` and `develop` come into being and an agent therefore commits onto whichever branch it finds. Note that section 0A now covers the human-gated prerequisites from [#490][issue-490], so this is the remaining half of that gap rather than the whole of it. The sequence that avoids every cleanup problem is: create `main` and leave it carrying nothing, create `develop` from `main` and leave it carrying nothing, create the first feature branch from `develop` and do the whole standup there, add the repo to GitHub and apply the repo config while still on that branch, then open a normal pull request to `develop` when the repo is ready. Nothing ever has to be cleaned off `main` or `develop`, because nothing ever reached them without review. Note the mechanical wrinkle when writing this up: a git branch cannot exist without a commit, so "carrying nothing" means exactly one signed empty root commit (`git commit --allow-empty`), and section 0's signing window applies to that commit like any other. The alternative of committing onto `develop` and squashing afterwards does not work: `non_fast_forward` is set on both `develop` payloads, so the history cannot be rewritten without disabling the ruleset, and Blog was correctly blocked when it tried. Worth stating that the protection is uneven, since a `release` repo's `repo-config/develop.json` carries a `pull_request` rule that blocks a direct commit outright, while `repo-config/operational/develop.json` carries only `deletion`, `non_fast_forward` and `required_signatures`, so on an operational repo a direct commit succeeds and only the instruction stands between the agent and an unfixable history. The reason it matters on a public repo is that the exploratory standup history is where PII, secrets and noise commits accumulate, and squashing a feature branch is the one chance to leave them out.
-- The static-site generator type from [#456][issue-456] and [#558][issue-558] has landed as `hugo`, with the deploy destination as the `self-hosted` publish target and the `deploy-ssh` mechanism. Correct the record while reading this, because three details the intake predicted are wrong against what Blog actually runs, and planning from the prediction would encode requirements the repo does not meet: the theme is **vendored with no recorded upstream ref**, not a Dependabot-tracked submodule; the generator is **pinned by version and SHA256**, not run at latest; and the deploy is a **separate dispatch** from the GitHub release, not a tag cut last after the live check. What was settled and did hold: the deploy is a publish, the type is named for the generator with the generic checks phrased so they do not name it, and the URL parity gate asserting a floor on the golden list length before comparing is the check of record. What remains: promote the generator-agnostic `hugo.*` checks to a shared type when a second generator arrives, which `spec/type-model.md` "Generators" makes a registry edit by construction, and decide how a `hugo` repository is meant to carry its theme at all, which the type declares nothing about today. The candidates are the vendored copy Blog actually ships, a submodule pinned to an upstream ref, and a separate fleet-owned repository the site consumes, and they differ along exactly the axis the carried-content entries above are about, since a vendored theme is a copy that goes stale with nothing detecting it and a submodule is a pin that Dependabot can see. Settle it as a question about the type rather than about Blog, because whatever is decided becomes the type's contract and the second generator inherits it. Also still true and stated nowhere else, the `copilot_code_review` rule in both ruleset payloads does not gate a merge today because gated Copilot review is an invite-only beta, which deserves a sentence near the merge gate so no repo reads the rule as the enforcement and relaxes the manual discipline actually holding the line.
-- Finish onboarding hardening (from [#310][issue-310]): make the [`AUDIT.md`][audit-doc] 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.
-- Add a linter-only Python project type for codegen and boilerplate Python, code that runs during another tool's build to emit generated source (for example 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`.
-
-## Host and Environment
-
-- State the rule that an agent works only in its own checkout, in its own directory, on its own feature branch, and never writes to a repository because it happened to be on disk. A clone left in a scratch directory is convenient exactly when it is most dangerous, since the operations that cross the boundary are the ordinary ones rather than the reckless ones. A blanket `git add -A` sweeps another agent's uncommitted work into your commit, a `git reset --hard` deletes it outright, and a branch switch carries it along into a change it has nothing to do with. This session produced the first of those: a blanket add swept a second agent's in-progress registration work into an unrelated commit and pushed it, and the work survived only because it was rescued and restored by hand afterwards. Care does not make a shared working tree safe, because every one of those commands is correct in isolation and wrong only because of who else is in the directory. Two things to settle when writing it. Whether the rule is stated as one checkout per agent or one checkout per task, since a single agent moving between two repositories in one directory hits the same hazard as two agents sharing one. And what an agent does when it finds a foreign checkout anyway, where the answer is to leave it alone and clone its own rather than to work carefully in it.
-- Extend the same rule to **reading**, which is the more common case and the easier one to think is harmless. A clone on disk is not the branch it names. It is whatever that clone was last fetched to, so reading it to answer what a repository carries answers a different question, which is what that clone last saw. The failure is silent, because the read succeeds and returns a plausible answer. This session produced two instances. A detection pass over local clones reported one repository as still drifted on a file whose fix had already merged, because that clone's refs predated the merge, and the correction came from a fetch rather than from the read. A second pass then reported a repository as missing a file it does carry, because the local checkout sat on a branch behind the one being measured. State the working practice with the rule: read the live ref through the API where a claim will be acted on, or fetch immediately before reading, and name the ref and commit in any finding derived from a local read so a reader can tell what was actually measured. Note the exception worth keeping, which is that a local clone is the right tool for anything needing history or a build, since those are what an API read cannot give.
-
-- Finish the [#365][issue-365] rollout, which has two halves and one of them is invisible from here. Four machines are still unchecked, WSL2 Ubuntu, the MacBook Air, and both ThinkPads, plus any headless or cron environment that runs Claude Code with the token. A ticked row means the `CLAUDE.md` text and not the hook, since only running `host-setup/agent-safety/install.sh` deploys both layers, and the proxmox host proved that distinction the hard way by carrying the documentary half alone for eight days on the very machine where the incident originated. Note also the follow-up left open on this host and never applied, that the superseded `## Safety rules` section from [#364][issue-364] still sits above the canonical `agent-safety v1` block in `~/.claude/CLAUDE.md`, so the two overlap. Removing the superseded section is a judgment call on a per-machine file, which is why it was surfaced rather than applied.
-- Fill in the remaining cells of the [#483][issue-483] host tooling matrix, which is the reference that makes the per-machine chore above repeatable, so the two close together rather than either alone. Linux, Windows and WSL2 are filled in and verified. **macOS** needs someone on that platform, the **Proxmox** question is whether that host is a shell for agent work or also runs containers, which decides whether `docker` is required there at all, and the engine-inside-the-distro variant of the WSL2 `docker` cell is still unverified since that host only exercised the Docker Desktop integration. Honor the issue's own rule when filling a cell, that an unverified install command is worse than a blank, because a blank prompts a question while a wrong command produces a broken host and a false sense that setup succeeded.
-
-## Fleet Chores
-
-- Measure review rounds against pull request size, and decide what the number licenses. The recent loops suggest a large change earns a different finding every round while a small one converges in one or two, which would make change size the lever on review cost rather than the reviewer's thoroughness, and would argue for splitting a change before review rather than discovering it through five rounds of findings. The data needs no new instrumentation, since the review history already carries it: for each recent pull request, record the diff size in files and lines, the number of rounds, and the findings per round, counting suppressed findings alongside threaded ones because they are the majority of what these loops produce. The outcome worth having is a threshold [`GOVERNANCE.md`][governance] can state in the branching or review guidance, expressed as the size at which a change is split rather than as advice to keep changes small. Note two confounds before drawing a line from the numbers. A large change is usually also a novel one, so size and unfamiliarity move together and the record should note what kind of change each was. And a round that finds something new is not evidence of a problem by itself, since a round that finds something new is the reviewer working, so the metric to watch is findings that a smaller first cut would have surfaced earlier rather than findings per round on its own.
-- Try local defensive-review subagents as a first pass before the remote reviewer, and measure what the pass is worth. The remote loop is thorough and it is also where most of a session's tokens and wall-clock go, and it delivers its findings one round at a time, which is the slowest available way to learn that a change had five problems. A local pass prompted adversarially, one agent per lens rather than one general reviewer, would surface the mechanical half before the branch is even pushed. Scope the experiment to what it can actually prove: run both for a stretch, record which findings the local pass caught that the remote reviewer then raised anyway, and keep it only where that overlap is large enough to shorten the remote loop rather than to add a step in front of it. Note the trap that makes this worth designing carefully rather than just trying. A local pass that finds nothing reads exactly like a clean change, and the next inference from there is that the remote review can be skipped, which is the one outcome the review contract exists to prevent, so the local pass is an input to the loop and never a substitute for the round the merge gate requires.
-- Record a disproved review finding somewhere the next round will read it, so the same proof is not built twice. [`.github/copilot-instructions.md`][copilot-instructions] already says the reviewer is sometimes factually wrong, already requires a decline to carry evidence, and already keeps a list of known non-working request paths, which is the shape this wants. What it has nowhere to put is the finding itself, so a claim disproved against a downloaded binary in one session is argued from scratch in the next. The worked example is the claim that `keys_unsorted` needs jq 1.6, disproved against a 1.5 binary on which `keys_unsorted` works and `walk/1` does not. Note the reason this is not simply a list to append to, which is that a disproof is true of one tree at one revision, so an entry outliving the code it was proved against becomes a reason not to check, and that is strictly worse than re-proving it. Each entry therefore records what was tested and against which revision, and an entry whose subject changes is deleted rather than edited.
-- Refresh the README, which 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, since it must track what the docs contain.
-- 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][issue-363]).
-- Sweep `ManagePackageVersionsCentrally` placement to `Directory.Packages.props` fleet-wide, since PlexCleaner sets it in `Directory.Build.props`, off the CODESTYLE canonical.
-- Consider renaming this repo to reflect the audit-catalog identity, which updates badge and link URLs across the fleet.
-
-<!-- Issues -->
-
-[issue-305]: https://github.com/ptr727/ProjectTemplate/issues/305
-[issue-310]: https://github.com/ptr727/ProjectTemplate/issues/310
-[issue-353]: https://github.com/ptr727/ProjectTemplate/issues/353
-[issue-363]: https://github.com/ptr727/ProjectTemplate/issues/363
-[issue-364]: https://github.com/ptr727/ProjectTemplate/issues/364
-[issue-365]: https://github.com/ptr727/ProjectTemplate/issues/365
-[issue-379]: https://github.com/ptr727/ProjectTemplate/issues/379
-[issue-456]: https://github.com/ptr727/ProjectTemplate/issues/456
-[issue-483]: https://github.com/ptr727/ProjectTemplate/issues/483
-[issue-489]: https://github.com/ptr727/ProjectTemplate/issues/489
-[issue-490]: https://github.com/ptr727/ProjectTemplate/issues/490
-[issue-509]: https://github.com/ptr727/ProjectTemplate/issues/509
-[issue-519]: https://github.com/ptr727/ProjectTemplate/issues/519
-[issue-521]: https://github.com/ptr727/ProjectTemplate/issues/521
-[issue-523]: https://github.com/ptr727/ProjectTemplate/issues/523
-[issue-552]: https://github.com/ptr727/ProjectTemplate/issues/552
-[issue-558]: https://github.com/ptr727/ProjectTemplate/issues/558
-[issue-570]: https://github.com/ptr727/ProjectTemplate/issues/570
-[issue-577]: https://github.com/ptr727/ProjectTemplate/issues/577
-[issue-578]: https://github.com/ptr727/ProjectTemplate/issues/578
-[issue-579]: https://github.com/ptr727/ProjectTemplate/issues/579
-[issue-580]: https://github.com/ptr727/ProjectTemplate/issues/580
-
-<!-- Pull requests -->
-
-[pr-537]: https://github.com/ptr727/ProjectTemplate/pull/537
-[pr-572]: https://github.com/ptr727/ProjectTemplate/pull/572
-
-<!-- Repo -->
-
-[agent-safety]: ./host-setup/agent-safety/
-[agents]: ./AGENTS.md
-[audit]: ./spec/audit.py
-[audit-doc]: ./AUDIT.md
-[codestyle]: ./CODESTYLE.md
-[copilot-instructions]: ./.github/copilot-instructions.md
-[divergences]: ./spec/divergences.json
-[divergences-report]: ./reports/divergences.md
-[files]: ./spec/files.json
-[governance]: ./GOVERNANCE.md
-[markdownlint]: ./.markdownlint-cli2.jsonc
-[matrix]: ./reports/conformance-matrix.md
-[operations]: ./OPERATIONS.md
-[pr-review]: ./scripts/pr_review.py
-[prose-lint]: ./scripts/prose_lint.py
-[readme-structure]: ./spec/readme-structure.md
-[repo-gate]: ./scripts/repo_gate.py
-[reports]: ./reports/
-[repos]: ./registry/repos.json
-[scripts]: ./scripts/README.md
-[secrets]: ./spec/secrets.json
-[secrets-schema]: ./spec/secrets.schema.json
-[section-model]: ./spec/section-model.md
-[standup]: ./STANDUP.md
-[workflows]: ./catalog/snippets/workflows/
-[write-guard]: ./host-setup/agent-safety/gh-write-guard.py
+# TODO
+
+Running backlog for this repo, kept in a committed file so the guidance survives across environments where agent memory does not. Entries are grouped by the surface they change rather than by priority, since an entry's cost is mostly set by what it touches. Where an open issue covers the same ground it is named on the entry, so the two are read together rather than worked twice.
+
+Every issue claim below was re-checked against `develop` at `1ed0cc8` on 2026-08-03, and the entries added from the onboarding-feedback pass were checked against `develop` at `b82c1a3` on 2026-08-05. An issue records the tree as it was on the day it was filed, so a claim in one is a starting point for a check rather than a finding to act on.
+
+## Verified Complete, Awaiting Close
+
+Each of these was checked line by line against the current tree and has nothing left to do here. Closing them is the maintainer's call, and each wants the evidence quoted in the closing comment rather than a bare close.
+
+- [#509][issue-509] (PhotoCleaner spec questions) is complete on all five items. Item 1, `.github/copilot-instructions.md` now reads "Most of `GOVERNANCE.md` is universal fleet law" and describes `AGENTS.md` as the thin router carrying two byte-locked sections and no repository-specific ones. Item 2, `CODESTYLE.md` "Markdown and Spelling" now names `details` and `summary` as allowed, matching [`.markdownlint-cli2.jsonc`][markdownlint]. Item 3, [`spec/readme-structure.md`][readme-structure] now states the private-repository behavior outright, that the full shape is carried and the GitHub-sourced badges render broken until the flip, which is accepted rather than worked around. Item 4, the same file now says the `HISTORY.md` mirror rule lives in `CODESTYLE.md`, which every repo carries, so the rule has a carried home and the file states only what the audit does with it. Item 5, `WORKFLOW.md` D2.2 now reads "the check exits early while the job still reports success" and spells out why a job-level `if:` would couple the release to smoke through `needs:`.
+- [#490][issue-490] (STANDUP has no repo-creation step) is complete on all four suggestions. [`STANDUP.md`][standup] carries a new section 0A, "Hand Over What Only the Maintainer Can Supply", listing the repository, the installed App, the App secret values in both stores, and every declared publish credential and environment. It states that a repo with no remote is not partially stood up but not started, and that a blocking prerequisite is escalated the moment it is found rather than carried, which is the failure mode the issue diagnosed in the agent's own task list. Step 4 now opens with `gh repo view` and carries the ruleset ordering constraint that the issue asked for.
+- [#489][issue-489] (Blog carry findings) is closed on all six items by the maintainer's own status table, five fixed and one resolved as needing no change. The single piece of follow-through it leaves is the `repo-config/configure.sh` re-vendor, which is already carried by the re-vendor entry below rather than by this issue.
+- [#379][issue-379] (Financial-Modeling fidelity findings) is dispositioned on all six items, and the manifest gap the follow-up raised was fixed by adding `repo-config/configure.sh` and `repo-config/settings.json` to [`spec/files.json`][files]. What holds it open is a downstream acknowledgement and that repo's own re-vendor, neither of which is hub work.
+- [#353][issue-353] (`.editorconfig` relaxes all analyzers) is done hub-side, and the tree confirms it, since `dotnet_analyzer_diagnostic.severity` no longer appears in `.editorconfig`. What holds it open is the downstream re-vendor across six C# repos, sequenced in the issue so PhotoCleaner's 362 sites do not gate the other five. That is cross-repo work needing the maintainer to name the repos.
+
+## Gate Honesty
+
+The gates in [`scripts/`][scripts] are hub-only and are the fleet's main defense against agent-authored drift, so a gate that reports clean without having read anything is the worst failure available here. The `gh-write-guard` hook in [`host-setup/agent-safety/`][agent-safety] is grouped with them, since it is the same kind of instrument even though it ships per host rather than per repo. These entries are ordered so the scope floor lands before anything relies on a clean verdict.
+
+- Make [`prose_lint.py`][prose-lint] assert a floor on its own scope, applying to itself the rule [`GOVERNANCE.md`][governance] already states: a gate that finds nothing is indistinguishable from a gate with nothing to find. A `--diff` run that resolves a non-empty diff and then matches **zero** files has almost certainly failed to scope rather than found a clean change, so it should say so instead of exiting 0. One session produced four separate routes to that same false clean: an unresolvable base widening to a whole-tree scan, a multi-line `paths` input read only to its first newline, a diff taken in one repository while scanning another, and a path under no repository at all. Each was fixed with its own guard, which is the wrong shape, because the fifth route will need a fifth guard and will be found the same way the first four were, by a reviewer rather than by the gate. A floor assertion covers the family. Note the honest limit before building it: a change touching only files the gate does not read (an image, a lock file) legitimately scopes to zero, so the assertion compares against the diff's own file list rather than against zero alone. This lands first, because every entry below it produces verdicts that are only worth reading once the gate can prove it read something.
+- Clear the [#519][issue-519] prose backlog, starting with `catalog/snippets/**`. Two of the four changes that issue planned have already landed and its headline numbers are stale, so re-measure before quoting anything from it. `comment-wrap` and `comment-case` are now in `DEFAULT_RULES`, and `reports/` is now exempt as a generated tree, which is why the current figures are **559** whole-tree under the default rules and **184** under `catalog/snippets` alone rather than the 668 and 119 the issue records. The whole-tree figure is the one that moves, having been 534 when this entry was written and 520 by the time [#570][issue-570] scoped the semicolon exemption to the sentence it lives in, which reported 44 semicolons the rule had been silent on. Re-measure it rather than quoting it, since a fix to the gate moves it as readily as a fix to the prose does. The snippets lead the fix order for the reason the issue gives, that a non-conformant snippet seeds its violations into every repo that adopts it and the downstream repo is then flagged for content it was handed. What remains undecided is whether the gate itself becomes a carried file rather than a hub-only one, which is the same question the entry below on hub-only machinery asks from the other direction.
+- Gate the pattern-detectable half of the representative-data rule in [`prose_lint.py`][prose-lint], meaning an absolute home path (`/home/<name>`, `/Users/<name>`, `C:\Users\<name>`) or a bare drive letter sitting in committed prose, a code comment, or a fixture. [`GOVERNANCE.md`][governance] "Representative Data in Agent-Authored Text" states the rule and says why a check is a floor rather than an answer, so the check is introduced as covering the easy half or it gets read as closing the rule, which is the specific way it would make things worse. Three things to settle when writing it. The exemption carries the whole burden, since the rule's own wording, the `host-setup/` docs, and the audit's examples all quote path shapes in order to describe them, and a wrong exemption hands out a work list that damages correct documents. The leak that motivated the rule was in a pull request comment, which no committed-file linter reads at all, so say what surface the gate covers rather than letting its name imply the rule. And a home path in an operational repo's runbook may be the literal path an operator types, which is the repo's own content rather than an agent quoting the maintainer's environment, so decide whether the finding is scoped by file, by repo type, or left for the author to judge.
+- Teach the `sha-pin` check in [`repo_gate.py`][repo-gate] to verify a pin **resolves**, not merely that it is shaped like a SHA. Forty hex characters is a format any fabricated string satisfies, and an agent hand-writing a plausible SHA into a workflow is a real failure mode rather than a hypothetical one. A resolvability check also catches the neighboring case, a pin whose commit was reachable only from a branch that has since been squashed and deleted, which breaks a downstream gate long after the change that caused it. Scope the network call to same-owner repositories, where the fleet's own actions live, and skip rather than fail when the host is offline so the local gate stays usable. Note that the existing `gh-write-guard` hook cannot cover this, since it watches Bash and an editor tool writing the same string into a file never reaches it.
+- Add a check that a pull request's **description** does not contradict its own branch. Three stale descriptions in one session generated six review findings between them, each one a reviewer noticing that the body named a commit, a branch, or a behavior the branch no longer carried. The cheap and precise form is to extract SHAs and `uses:` refs quoted in the body and confirm each still appears in the head tree, since those are the claims that go stale silently and the ones a reviewer actually catches. Prose claims are out of scope, and deliberately so: judging those needs a similarity heuristic, which [`spec/section-model.md`][section-model] already rejects for exactly the reason it would fail here.
+- Reconsider whether the pre-commit hook should run the doc gates now that they are diff-scoped. [`scripts/README.md`][scripts] records the current decision and its reason, that doc linters stay out of the hook so it stays fast, and that reason was sound when the only mode was a whole-tree sweep. A `--diff` run reads the lines one commit touches and finishes in about a second, so the trade has moved. The failure it would prevent is the most repeated one on record: comment sentences wrapped across lines, caught by CI or by a reviewer after the commit rather than before it, over and over within a single session. Weigh it against the standing preference for a fast hook, and against the risk of a hook that runs the gate from the wrong directory, which is its own false clean.
+- Audit the fleet's shell surface by size and branching, and decide per script whether Python with unit tests is the cheaper form. The evidence is the review record rather than a language preference: a non-trivial shell script earns findings round after round, while every gate under [`scripts/`][scripts] carries a `test_<script>.py` beside it and converges in one or two. `repo-config/configure.sh` and `host-setup/agent-safety/install.sh` are the two worth measuring, and the measure is lines, branch count, and the review rounds each has actually cost, not a general claim about the two languages. Two constraints bound the answer before anything is rewritten. A bootstrap script runs before anything is installed, so an installer that needs the Python it exists to install is not a rewrite worth having, which protects `install.sh` more than it protects `configure.sh`. And `configure.sh` is carried `verbatim` to the fleet, so changing its form is a re-vendor for every repository holding it, which makes this the same visit as the hub-hosted tooling entry below rather than a separate one.
+- Move the commands that keep failing the same way into helper functions, rather than restating the rule they keep failing against, per [#580][issue-580]. Two are on record. A command run from the wrong working directory, which does not error and instead returns a confident answer about a different tree. And a GitHub node id typed by hand into a mutation, which the `gh-write-guard` hook correctly refused because the id had not come from a query in that same command. The second is the instructive one, since the rule it broke is stated plainly in [`GOVERNANCE.md`][governance] and in the host-level guidance, and an agent that had read both still reached for the literal, which says the shape of the operation is what fails rather than the agent's knowledge of the rule. A reply-and-resolve helper in [`pr_review.py`][pr-review] would take a pull request number and a finding, query the thread ids itself, and never put an id anywhere a hand could type one, which removes the failure instead of detecting it. Note the dependency: a helper only helps where it can be run, so this is worth building only alongside the question below about whether a downstream repository can reach a hub script at all.
+- Fix the newline parsing in [`gh-write-guard.py`][write-guard], where `_git_subcommand_arglists` ends a `git push` argument list at `&&` but not at a newline, so every token on a later line of the same command is read as a refspec. Measured against the installed hook, `git push -u origin revendor/x` alone resolves to the one branch, while the same push followed by a newline and `gh pr create` with a base of `develop` resolves to five, meaning `revendor/x`, `gh`, `pr`, `create`, and `develop`. The `&&` form resolves correctly, which is what isolates the defect to the newline case. The direction of the error is over-blocking rather than under-blocking, so it is a usability defect rather than a safety hole, and that is exactly why it is worth fixing rather than tolerating: the denial tells the agent it is attempting a direct push to a protected branch that only lands by bypassing a rule with admin power, when the push targets an ordinary feature branch. An agent that believes the message either escalates a push needing no escalation or goes looking for a way around the guard, and teaching a safety hook to cry wolf is how it stops being read. Note the fix reaches every host only when `host-setup/agent-safety/install.sh` is re-run, so it lands with the rollout work in [#365][issue-365] rather than ahead of it, and the entry to write alongside the fix is a self-test case for the newline form, since the existing suite covers the `&&` form and passed throughout.
+
+## Carried Content and Propagation
+
+Everything here changes a file the fleet holds a copy of, so each entry costs a hub edit plus a sweep, and the sweep is the part that gets skipped.
+
+- Re-vendor the changed `verbatim` content across the fleet, which is one sweep covering five files. `repo-config/configure.sh` is carried `verbatim` with `appliesTo: "*"` and the hub swept it to one sentence per line. In `AGENTS.md`, "Context and Delegation Discipline" carries the wait rule's failure clause and "Where the Rules Live" carries a row for the new section named below. In `GOVERNANCE.md`, "Verification Discipline" carries the rule that a launched process is not a result, "PR Review Etiquette" carries the five outcomes that close a finding, "Repository Boundaries and Write Safety" carries the rule that a refused write is reported rather than re-shaped, and "Representative Data in Agent-Authored Text" is an entirely new carried section that no downstream repo holds, which the audit reports as a missing section rather than as drift. Three further `GOVERNANCE.md` sections differ by a single word each, "Documentation Style Conventions", "Communicating with the User" and "Repository Details", where the format's name was capitalized to the convention `CODESTYLE.md` "Markdown and Spelling" now states, so they are byte-mismatched for a reason a reader of the diff would otherwise call cosmetic. Two comment lines in `.markdownlint-cli2.jsonc` took the same capitalization, and that file is `verbatim` and `whole`, so every downstream copy is byte-mismatched on a config nothing else changed about. `CODESTYLE.md` carries the new item and is the fifth file, at `intent` rather than `verbatim` fidelity, so it reaches the fleet as a rule each repo adopts in its own copy rather than as bytes to match, and the same mixed spelling is waiting in every downstream tree. Every repo already holding a copy of a changed section is byte-mismatched against the hub until it takes the new one, which the audit reports as stale rather than modified. This sweep is also the follow-through [#489][issue-489] and [#379][issue-379] were waiting on, and the `.editorconfig` line in [#353][issue-353] rides the same visit to each repo. Regenerate [reports/divergences.md][divergences-report] before using it as the work list, since the committed copy is dated 2026-07-22 and therefore predates the router split, which shows in it naming "Repository Boundaries and Write Safety", "Git and Commit Rules" and "Verification Discipline" as `AGENTS.md` sections when all three now live in `GOVERNANCE.md`. A stale ledger is the same hazard as a stale exemption, in that it hands out a work list measured against a tree that no longer exists.
+- Drop the unused `GITHUB_TOKEN` grants from the merge-bot workflow, per [#521][issue-521], which the tree confirms is still open, since all four jobs still carry `contents: write` and `pull-requests: write` while every write in the file authenticates with the App token. The finding is least privilege on the highest-blast-radius shape in the fleet, a `pull_request_target` workflow holding an App private key, where the grant is not exploitable today only because no step consumes it. Three things to settle: whether to drop the job-level blocks or set a workflow-level `permissions: {}`, whether the audit should compare permissions at all given the file is `interface` fidelity with only a `requiredJobKeys` contract, and the re-vendor, since every repo carries the file. Note that [`spec/files.json`][files] now declares this workflow at `appliesTo: "*"`, which closes the separate gap [#456][issue-456] raised, that D8.1 graded a file the file spec never required.
+- State the rule that an agent never assumes a Docker image is present locally, however recently it pulled one, because a background prune can remove an image between two commands of the same session and the run then fails on something that worked minutes earlier. The prescription is the always-pull flag by default, and an explicit `docker pull <image>:<tag>` before use where the flag does not apply. The four documented lint invocations already carry `--pull=always`, in [`GOVERNANCE.md`][governance] "Running the Linters Locally", mirrored in [`OPERATIONS.md`][operations] and both VS Code task snippets, so what is missing is the rule rather than the one-liners: an agent composing an ad-hoc `docker run` drops the flag precisely because it believes the image is already cached. Two things to settle when writing it. Where it lives, since that section is scoped to the four lint tools while the rule covers any container an agent starts, which argues for placing it with the Docker or verification guidance instead, and whether it is carried to the fleet, since every repo runs the same images from the same instructions. Note the limit before writing it, so the flag does not read as the whole answer: `docker run` against a registry tag re-pulls an absent image on its own, so the cases that actually break are a locally built tag with no registry to pull from, and any command that branches on the image being present (`docker image inspect`, `docker images`) rather than simply running it.
+- Decide where a carried file may name hub-only machinery, per [#580][issue-580], since `GOVERNANCE.md` "PR Review Etiquette" points at `scripts/pr_review.py` and the fleet carries the section but not the script. A downstream reader follows that pointer to a path their repo does not have. Either the script joins the carried set, or the rule states the behavior and drops the tool name the way the coordination-reference rule already requires for the template repo itself. The cost of leaving it unresolved is measured rather than hypothetical, because downstream agents hand-roll the review and prose checks the hub already ships. Several sessions had to be redirected to [`pr_review.py`][pr-review] and [`prose_lint.py`][prose-lint] by hand, each one having built its own worse version of a gate that exists, and none of them did anything wrong, since the tool they were pointed at is not in their tree and nothing they can read says how to reach it. A rule that names a tool its reader cannot run is worse than either resolution, because it teaches the reader that a pointer in carried text is decorative.
+- Define the fleet's own vocabulary somewhere a repository with no history will find it, per [#579][issue-579], because the words a request is phrased in are defined nowhere it can read. **Hub** is used throughout these docs and in every request asking a repository to reconcile or audit itself against the canonical, and no file states that it means this repository, so a repository carrying no instruction set has to be told what the hub is, where it lives, and which file to open, by hand, each time. The review loop has the opposite shape of the same problem: [`GOVERNANCE.md`][governance] "Expected Review Loop" states the procedure precisely and never presents its name as the way to ask for it, so every request improvises a phrasing and the scope an agent reads out of it moves with the wording. A defined term is what makes "close the review loop on #123" a complete instruction. Two things to settle. Where the definitions live, since the natural home is the byte-locked Fleet Bootstrap section of [`AGENTS.md`][agents] and a repository with no carried instruction set is precisely the one that does not have it, which leaves the hub's own `README.md` as the only surface a stranger to the fleet reads first. And whether the entry point is named per task rather than per repository state, since the bootstrap section already routes correctly and the gap is that the router is unreachable rather than that it is wrong. Note that an edit to the byte-locked section lands with [#552][issue-552], which already holds that section open, rather than as a change of its own.
+- Revisit [#305][issue-305], which asks for a propagation path for the rule docs and is the oldest open issue here, because most of the machinery it asked for has since been built and the issue has not been re-scoped to match. The fidelity model, the `spec/files.json` manifest, [`spec/divergences.json`][divergences] with its generated [reports/divergences.md][divergences-report], and [`AUDIT.md`][audit-doc] section 10 together give the canonical-versus-adapted split and the audit path the issue proposed. What is genuinely still missing is the push half, since every one of those detects drift while the sweep that fixes it is manual, which is exactly the entry above. Either re-scope the issue to the push half or close it against the entry above and the audit-automation entry below.
+- Reduce the surface that is copied downstream at all, since every carried file is a copy that breaks when it is not the current one. `repo-config/configure.sh` is the worked example from this session: a defect in its check mode was fixed once in the hub and immediately turned into a re-vendor owed by every repository carrying it, and until each takes the fix they run different logic while reporting the same command. A repository that misses the sweep does not fail loudly. It quietly audits itself with an older script. The alternative is for the hub to host the tool and for each downstream repository to call it rather than hold a copy, so one edit reaches the fleet and no stale copy exists to detect, re-vendor, or classify. This is the same argument as the reusable-workflow entry below and should be settled with it rather than separately, since both are about consuming hub code at runtime instead of vendoring it. Three things to settle. What the fleet actually needs vendored, which is the content a repository is audited against and could not run without, against what only needs to be reachable. How a consumed tool is pinned, because consuming hub code at runtime is a floating dependency unless it names a commit, and the action-pinning rule already requires exactly that. And what a repository does when the hub is unreachable, since a vendored copy still works offline and a called one does not, which is the real cost being traded away. The fleet already runs both models without either having been chosen against the other, since `repo-config/configure.sh` is carried while every gate under [`scripts/`][scripts] is hub-only, and the wanted end state is the second one: a script that is identical everywhere lives in the hub once and a downstream repository calls it, which removes the re-vendor rather than scheduling it. The near-term half needs no decision to start on, which is deleting a downstream config script whose content is only ever the hub's, because a per-repo copy of a file with no per-repo content is drift waiting to be detected and nothing is lost by not having it.
+- Investigate replacing copy-pasted workflow content with cross-repo reuse, now that this repo is public. A public repository's composite actions and reusable workflows can be consumed by any other repository regardless of owner type, so the organization account this pattern was assumed to require is not needed, and the constraint that shaped the current vendor-everything model no longer holds. The catalog under [`catalog/snippets/workflows/`][workflows] is copied into each repo today, which means a fix to a shared job is a sweep across the fleet rather than one edit here, and it is the mechanism by which a defect in a snippet seeds itself into every repo that adopted it. Scope the investigation to which jobs are genuinely identical across repos against which only look similar, since a reusable workflow that needs a long input list to cover per-repo variation is worse than the copy it replaces. Settle the ref policy in the same pass, because consuming hub code at CI time is a floating dependency unless it is pinned, and [`GOVERNANCE.md`][governance] "Action pinning" requires a commit SHA for every action with one documented exception. Note that `uses:` does not accept expressions, so a per-branch ref cannot be selected in the workflow file and any branch-dependent behavior belongs inside the consumed action instead.
+- Make a table of contents standard for a long document rather than for the README alone. [`spec/readme-structure.md`][readme-structure] fixes one at README position 4 and [`GOVERNANCE.md`][governance] states how it is generated and which headings it excludes, and no other file in the hub carries one, which leaves the three longest documents in the fleet without the thing that makes them navigable: `CODESTYLE.md` at 516 lines, `GOVERNANCE.md` at 421, and `WORKFLOW.md` at 298. Two things to settle. The threshold, stated in headings or lines rather than left to judgment, so the audit can check it and no repository is put in the position of arguing that its own document is short. And how it sits with the reference-link exception, since the four agent-instruction files keep inline links exactly because they are read one section at a time, which is the same property that makes a contents list worth having in them, and the generated list is already the one exception that rule carries. Note the mechanical constraint before adopting it, that the list is filled by the Markdown All in One extension on save, so a file nobody opens in the editor grows a stale contents list rather than none, and a stale one is worse than absent because it is read as current.
+- State that an operational repository still opens a pull request for a large or risky change, even though its model permits committing straight to `develop`, which is item 3 of [#578][issue-578]. [`GOVERNANCE.md`][governance] "Operational Repositories" grants the direct commit and says nothing about when to decline the grant, and `repo-config/operational/develop.json` carries only `deletion`, `non_fast_forward` and `required_signatures`, so nothing mechanical stands between an agent and a large unreviewed change landing on the live surface. The reason the grant exists is the one-line config edit that a review round costs more than it protects, and that reason stops applying well before a change gets large. Settle what counts as large, and prefer a stated shape over a line count, since the property that matters is whether the change can be read at a glance and reverted cleanly rather than how many lines it moved. Note that this stays guidance by construction, because adding a `pull_request` rule to the operational ruleset would withdraw the direct-commit grant that the whole model exists to give.
+- Say when an issue is closed by hand, not only that the closing keyword belongs on the promotion pull request, which is item 1 of [#578][issue-578]. [`GOVERNANCE.md`][governance] "Git and Commit Rules" already states that `Closes #N` fires only on a merge into the default branch and therefore goes on the `develop -> main` promotion, and downstream agents keep re-deriving that rule and reporting it as a discovery, which says it is being missed rather than that it is missing. What the rule genuinely does not cover is the case that produces the confusion, which is work complete on `develop` while a promotion is not imminent, leaving the issue open with nothing on it recording that it is done. The current text licenses a hand-close only once a promotion has merged without the keyword, which is the narrower case. Widen it to say that an issue is closed when the work is verifiably complete, citing the squash SHA that completed it, and that the promotion keyword is the automation for the common case rather than the only permitted route. [#552][issue-552] is the live example, fixed by the merge of [#572][pr-572] and open at the time of writing.
+- Say that the message carrying the clickable link comes **before** the prompt it accompanies, which is item 2 of [#578][issue-578] and which [`GOVERNANCE.md`][governance] "Communicating with the User" leaves unstated. The rule already gets the hard part right, that an interactive prompt renders neither a Markdown link nor a bare URL, so the reference inside it is a bare `#123` and the link goes in the message that accompanies it. It says accompanying rather than preceding, and a message emitted after the prompt is not read before the question is answered, which is the entire outcome the rule exists to produce. This keeps recurring in practice, so read the recurrence as the wording being underspecified rather than as the rule being ignored, which is the same diagnosis the entry above reaches about the closing keyword.
+
+## Audit and Spec Model
+
+- Teach the audit to see content sitting in the wrong file, per [#523][issue-523], which the tree confirms is untouched, since [`spec/audit.py`][audit] still checks file presence, declared-section presence, verbatim hashes, and workflow interface conformance and nothing that reads a heading against a destination. The case that found it is a repo whose `.github/copilot-instructions.md` carried 311 lines under nine headings that [`spec/section-model.md`][section-model] assigns to `ARCHITECTURE.md` and `OPERATIONS.md`, reported as a missing-file letter while the misplacement that caused it was invisible. The shape that fits the engine is structural, collecting the level-two headings of an `intent` file, subtracting the ones [`spec/files.json`][files] declares for it, and comparing the remainder against the headings other destinations declare. The similarity-based version is explicitly rejected by `section-model.md`, and a detector built on it produces findings whose remedy is to delete content. Four things to settle, all in the issue: whether an undeclared heading is a finding at all given a repo may add locally, whether the destination mapping becomes declared data rather than prose, whether it reaches the advisory `ARCHITECTURE.md`, and how many repos are affected, which is measured before the check is designed rather than after it starts reporting.
+- State what a `driftNote` may contain at the moment one is written, not only what happens to it once the deviation clears, and widen the check that guards it. [`AUDIT.md`][audit-doc] section 8 says a note records a current deviation and is deleted once resolved, which is a rule about a note's end of life and leaves an agent authoring one with no rule about its content. PhotoCleaner is the worked example, in [#537][pr-537]: asked to self-audit and reconcile its notes, the agent wrote a completion record ("baseline onboarding completed"), a historical fact (the date a past version first published), and a description of the repo conforming to the README spec. All three are prose about the past or about compliance rather than a current deviation, and none of them is what the field is for. Read that as an incomplete instruction rather than an agent ignoring one, since nothing it was given forbids any of the three. Two things to settle. The rule wants stating positively at authoring time, that a note names a deviation that is true right now and would still be true if nobody read it, so history, completion, and conformance are each out by construction, and a repo doing exactly what the spec requires earns no note at all. And the detector needs the same widening, because [`spec/audit.py`][audit] currently flags a stale note by matching words that assert *outstanding* work ("pending", "not yet", "missing", "behind"), which is the opposite polarity to all three of PhotoCleaner's notes, and it only runs that check when the repo audits clean, which PhotoCleaner did not until the round that found this. A guard that fires only on one polarity, and only in the state where the problem has already gone, cannot see the failure it exists to catch. Note the limit before building it, since it is the same limit the section model already records: judging whether a sentence describes a current deviation is a semantic call, so the honest target is the shapes that are mechanically recognizable, a past-tense completion verb and an explicit date among them, with the rest left to the rule.
+- Declare the canonical short description in [`registry/repos.json`][repos] instead of deriving it by parsing the README, which makes every check and every push deterministic. Today [`spec/audit.py`][audit] extracts the intro line after the H1 and compares the GitHub About panel and the Docker Hub short description against it, so the source of truth lives inside prose. That forces anything wanting the value to parse Markdown, and PhotoCleaner#32 shows the cost, since a workflow step that reads the intro at publish time needs nine guards against headings, block quotes, all four list markers, ordered lists, HTML, tables, code, links and the length cap, and every one of them fails the release rather than the tagline. Adding a `description` field turns the README intro into a third mirror rather than the source, so the audit compares all three against one declared value, the Docker workflow pushes a literal with no parser, and `repo-config/configure.sh` can set the GitHub About panel from the same field it already sets every other repository setting from. The 100-character cap stays, since Docker Hub's short description is still the tightest surface. Add the field to `registry/repos.schema.json` as well, which sets `additionalProperties: false`, and make it optional at first so the audit falls back to the README intro while repos adopt it one at a time. The disposition is recorded on [#509][issue-509], and the ask on the Docker repos is only that the parsing step is not propagated further while the field is pending.
+- Let the README intro carry more than the tagline, and say which line the mirrors actually take, per [#577][issue-577]. [`spec/readme-structure.md`][readme-structure] item 1 reads as though the canonical description **is** the paragraph after the H1, capped at 100 characters and link-free, and [`CODESTYLE.md`][codestyle] "Markdown and Spelling" then has `HISTORY.md` copy "the same intro paragraph" verbatim. Read together they forbid a README from saying anything further about itself above the fold, which is a real cost on a repository whose purpose needs a sentence of context, and the cap they enforce exists for Docker Hub's short description rather than for the reader. State the shape instead: the first line after the H1 is the tagline, it alone is bound by the 100-character link-free rule, and it alone mirrors to the GitHub About panel, the Docker Hub short description, and the `HISTORY.md` opening, with any further paragraph free prose that no mirror reads and no cap applies to. The audit changes with it, since it currently measures the first non-empty line and would otherwise start reporting a legitimate second paragraph. Note this is the same axis as the entry above, because declaring the description in [`registry/repos.json`][repos] makes every mirror read a field rather than parse a paragraph and settles the ambiguity by construction, so the two want deciding together rather than one after the other.
+- Rework [`spec/readme-structure.md`][readme-structure] to match the hand-crafted PlexCleaner README, which is the shape the maintainer wants, and make the result auditable rather than advisory. Four concrete divergences are already identified, measured against PlexCleaner `README.md`, this repo's `README.md`, and the current spec. First, the distribution bullet is labeled by deliverable: PlexCleaner ships executables and calls the channel **Binary Releases**, while the spec fixes the label as **Versioned Releases** for every repo, so the label belongs in a per-channel table rather than as one string. Second, the license shield sits in the top **Build Status** block here and at the very bottom of PlexCleaner, inside a closing `## License` section that reads `Licensed under the [MIT License]` followed by the shield, immediately before the link definitions. Third, the Release Notes section closes with `See Release History for complete release notes and older versions.` in PlexCleaner against `See Release History for the full history.` here, and the PlexCleaner form is the wanted one. Note that PlexCleaner writes that link inline, which the reference-style rule forbids, so adopt the wording and keep the reference form. Fourth, the channel bullets and their shields vary by deliverable, meaning GitHub binaries, Docker Hub, NuGet, and PyPI each carry a different bullet label and a different shield set, which is what a per-type table has to encode for the `readme-structure` audit dimension to check a repo against its own declared types.
+- Decide whether the canonical README section order follows PlexCleaner, which is a separate question from the four divergences above and affects every repo plus the `readme-structure` audit. PlexCleaner places **Questions or Issues** immediately after the Table of Contents, where the spec orders it ninth, and it carries sections the spec names nowhere, including Performance Considerations, Runtime Metrics, Custom Plugins, Testing, Development Tooling, Feature Ideas, and Sample Media Files. Under the recurrence rule in [`spec/section-model.md`][section-model] those last ones are correctly repo-specific and stay undeclared, so the open question is only the position of the sections the spec already names.
+- Declare locally-required secrets the way GitHub-stored ones are already declared, and make a gitignored `secrets/` directory the fleet standard that holds them. [`spec/secrets.json`][secrets] covers only the Actions and Dependabot stores, so a repo that deploys somewhere has no declared way to say what it needs at runtime, and the required set is discoverable only by reading the deploy. The pattern already runs in the fleet in two shapes: HomeAutomation-Config keeps a gitignored secrets directory of env files and Docker secret files, and ESPHome-Config keeps a gitignored `secrets.yaml` beside a committed `_secrets.yaml`. The committed file carries the required names with dummy values, so the shape of the requirement is in git while the values never are, which is the same split the GitHub side already gets from `requiredSecrets[]`. Blog needs it immediately, since it deploys on the proxmox host through HomeAutomation-Config's Docker Compose stack and carries the copy destinations and the internal URI. The hub carries neither the directory nor a `.gitignore` entry for one today, so adopting it here comes first. Note that the **GitHub** side has the same missing axis, surfaced by the `hugo` type: a deploy's credentials are per-environment GitHub Environment secrets and variables, `stores` is a closed enum of `actions` and `dependabot`, and `spec/audit.py` seeds `required_by_store` with those two keys and indexes it unguarded, so adding an `environments` value to the enum raises `KeyError` for every repo whose `publish[]` maps to that mechanism. The type landed with an optional `environments` block added to [`spec/secrets.schema.json`][secrets-schema] and described in `spec/secrets.json`'s note, so a repo that needs it may declare its per-environment names and the shape is legal rather than an invention. The hub's own `spec/secrets.json` carries no such block, having no environments of its own, and no tool reads one where it exists. That is honest but it is not a gate, so a clean audit says nothing about whether an environment is configured. Solving it properly means a store vocabulary that does not crash on an unknown key and a per-environment secrets and variables fetch, and it is the same axis as the local half above rather than a separate problem.
+- Canonicalize Python linter-config placement on `pyproject.toml`, since one cataloged repo uses a standalone `.ruff.toml` plus `pyrightconfig.json`. Track it as a drift finding and fix it downstream.
+- 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. This is paced by maintainer capacity rather than blocked on anything, since repos are brought up to spec as they are worked on, so the entry records the outstanding set rather than a defect.
+- Revisit automating the audit, which was explored and deliberately deferred, recorded here so the reasoning is not re-derived from scratch. Three shapes were considered: a scheduled hub-driven audit publishing each report as a workflow artifact, the same thing committing the report back the way the codegen bot updates its own files, and a pull-request hook in each downstream repo that audits itself against the current hub. Three things blocked all of them. Until the fleet reaches stasis with every repo onboarded, a scheduled run reports mostly noise, since a repo mid-onboarding is expected to be non-conformant. The hub has to be stable before downstreams can audit against it, because a hub change lands as fleet-wide findings the same day. And the downstream half is a catch-22, since a self-auditing pull-request hook is CI instrumentation the repos that most need it do not yet carry. The agreed outcome was the on-demand audit that [`AUDIT.md`][audit-doc] describes today. Worth reopening once the fleet is onboarded and the hub goes a stretch without carried-content changes, and the artifact shape is the one to try first, since it produces evidence without committing anything and so cannot generate review load while the noise level is still unknown.
+
+## Onboarding and New Types
+
+- Give [`STANDUP.md`][standup] an explicit branch-bootstrap step, because it currently says nothing about how `main` and `develop` come into being and an agent therefore commits onto whichever branch it finds. Note that section 0A now covers the human-gated prerequisites from [#490][issue-490], so this is the remaining half of that gap rather than the whole of it. The sequence that avoids every cleanup problem is: create `main` and leave it carrying nothing, create `develop` from `main` and leave it carrying nothing, create the first feature branch from `develop` and do the whole standup there, add the repo to GitHub and apply the repo config while still on that branch, then open a normal pull request to `develop` when the repo is ready. Nothing ever has to be cleaned off `main` or `develop`, because nothing ever reached them without review. Note the mechanical wrinkle when writing this up: a git branch cannot exist without a commit, so "carrying nothing" means exactly one signed empty root commit (`git commit --allow-empty`), and section 0's signing window applies to that commit like any other. The alternative of committing onto `develop` and squashing afterwards does not work: `non_fast_forward` is set on both `develop` payloads, so the history cannot be rewritten without disabling the ruleset, and Blog was correctly blocked when it tried. Worth stating that the protection is uneven, since a `release` repo's `repo-config/develop.json` carries a `pull_request` rule that blocks a direct commit outright, while `repo-config/operational/develop.json` carries only `deletion`, `non_fast_forward` and `required_signatures`, so on an operational repo a direct commit succeeds and only the instruction stands between the agent and an unfixable history. The reason it matters on a public repo is that the exploratory standup history is where PII, secrets and noise commits accumulate, and squashing a feature branch is the one chance to leave them out.
+- The static-site generator type from [#456][issue-456] and [#558][issue-558] has landed as `hugo`, with the deploy destination as the `self-hosted` publish target and the `deploy-ssh` mechanism. Correct the record while reading this, because three details the intake predicted are wrong against what Blog actually runs, and planning from the prediction would encode requirements the repo does not meet: the theme is **vendored with no recorded upstream ref**, not a Dependabot-tracked submodule; the generator is **pinned by version and SHA256**, not run at latest; and the deploy is a **separate dispatch** from the GitHub release, not a tag cut last after the live check. What was settled and did hold: the deploy is a publish, the type is named for the generator with the generic checks phrased so they do not name it, and the URL parity gate asserting a floor on the golden list length before comparing is the check of record. What remains: promote the generator-agnostic `hugo.*` checks to a shared type when a second generator arrives, which `spec/type-model.md` "Generators" makes a registry edit by construction, and decide how a `hugo` repository is meant to carry its theme at all, which the type declares nothing about today. The candidates are the vendored copy Blog actually ships, a submodule pinned to an upstream ref, and a separate fleet-owned repository the site consumes, and they differ along exactly the axis the carried-content entries above are about, since a vendored theme is a copy that goes stale with nothing detecting it and a submodule is a pin that Dependabot can see. Settle it as a question about the type rather than about Blog, because whatever is decided becomes the type's contract and the second generator inherits it. Also still true and stated nowhere else, the `copilot_code_review` rule in both ruleset payloads does not gate a merge today because gated Copilot review is an invite-only beta, which deserves a sentence near the merge gate so no repo reads the rule as the enforcement and relaxes the manual discipline actually holding the line.
+- Finish onboarding hardening (from [#310][issue-310]): make the [`AUDIT.md`][audit-doc] 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.
+- Add a linter-only Python project type for codegen and boilerplate Python, code that runs during another tool's build to emit generated source (for example 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`.
+
+## Host and Environment
+
+- State the rule that an agent works only in its own checkout, in its own directory, on its own feature branch, and never writes to a repository because it happened to be on disk. A clone left in a scratch directory is convenient exactly when it is most dangerous, since the operations that cross the boundary are the ordinary ones rather than the reckless ones. A blanket `git add -A` sweeps another agent's uncommitted work into your commit, a `git reset --hard` deletes it outright, and a branch switch carries it along into a change it has nothing to do with. This session produced the first of those: a blanket add swept a second agent's in-progress registration work into an unrelated commit and pushed it, and the work survived only because it was rescued and restored by hand afterwards. Care does not make a shared working tree safe, because every one of those commands is correct in isolation and wrong only because of who else is in the directory. Two things to settle when writing it. Whether the rule is stated as one checkout per agent or one checkout per task, since a single agent moving between two repositories in one directory hits the same hazard as two agents sharing one. And what an agent does when it finds a foreign checkout anyway, where the answer is to leave it alone and clone its own rather than to work carefully in it.
+- Extend the same rule to **reading**, which is the more common case and the easier one to think is harmless. A clone on disk is not the branch it names. It is whatever that clone was last fetched to, so reading it to answer what a repository carries answers a different question, which is what that clone last saw. The failure is silent, because the read succeeds and returns a plausible answer. This session produced two instances. A detection pass over local clones reported one repository as still drifted on a file whose fix had already merged, because that clone's refs predated the merge, and the correction came from a fetch rather than from the read. A second pass then reported a repository as missing a file it does carry, because the local checkout sat on a branch behind the one being measured. State the working practice with the rule: read the live ref through the API where a claim will be acted on, or fetch immediately before reading, and name the ref and commit in any finding derived from a local read so a reader can tell what was actually measured. Note the exception worth keeping, which is that a local clone is the right tool for anything needing history or a build, since those are what an API read cannot give.
+
+- Finish the [#365][issue-365] rollout, which has two halves and one of them is invisible from here. Four machines are still unchecked, WSL2 Ubuntu, the MacBook Air, and both ThinkPads, plus any headless or cron environment that runs Claude Code with the token. A ticked row means the `CLAUDE.md` text and not the hook, since only running `host-setup/agent-safety/install.sh` deploys both layers, and the proxmox host proved that distinction the hard way by carrying the documentary half alone for eight days on the very machine where the incident originated. Note also the follow-up left open on this host and never applied, that the superseded `## Safety rules` section from [#364][issue-364] still sits above the canonical `agent-safety v1` block in `~/.claude/CLAUDE.md`, so the two overlap. Removing the superseded section is a judgment call on a per-machine file, which is why it was surfaced rather than applied.
+- Fill in the remaining cells of the [#483][issue-483] host tooling matrix, which is the reference that makes the per-machine chore above repeatable, so the two close together rather than either alone. Linux, Windows and WSL2 are filled in and verified. **macOS** needs someone on that platform, the **Proxmox** question is whether that host is a shell for agent work or also runs containers, which decides whether `docker` is required there at all, and the engine-inside-the-distro variant of the WSL2 `docker` cell is still unverified since that host only exercised the Docker Desktop integration. Honor the issue's own rule when filling a cell, that an unverified install command is worse than a blank, because a blank prompts a question while a wrong command produces a broken host and a false sense that setup succeeded.
+
+## Fleet Chores
+
+- Measure review rounds against pull request size, and decide what the number licenses. The recent loops suggest a large change earns a different finding every round while a small one converges in one or two, which would make change size the lever on review cost rather than the reviewer's thoroughness, and would argue for splitting a change before review rather than discovering it through five rounds of findings. The data needs no new instrumentation, since the review history already carries it: for each recent pull request, record the diff size in files and lines, the number of rounds, and the findings per round, counting suppressed findings alongside threaded ones because they are the majority of what these loops produce. The outcome worth having is a threshold [`GOVERNANCE.md`][governance] can state in the branching or review guidance, expressed as the size at which a change is split rather than as advice to keep changes small. Note two confounds before drawing a line from the numbers. A large change is usually also a novel one, so size and unfamiliarity move together and the record should note what kind of change each was. And a round that finds something new is not evidence of a problem by itself, since a round that finds something new is the reviewer working, so the metric to watch is findings that a smaller first cut would have surfaced earlier rather than findings per round on its own.
+- Try local defensive-review subagents as a first pass before the remote reviewer, and measure what the pass is worth. The remote loop is thorough and it is also where most of a session's tokens and wall-clock go, and it delivers its findings one round at a time, which is the slowest available way to learn that a change had five problems. A local pass prompted adversarially, one agent per lens rather than one general reviewer, would surface the mechanical half before the branch is even pushed. Scope the experiment to what it can actually prove: run both for a stretch, record which findings the local pass caught that the remote reviewer then raised anyway, and keep it only where that overlap is large enough to shorten the remote loop rather than to add a step in front of it. Note the trap that makes this worth designing carefully rather than just trying. A local pass that finds nothing reads exactly like a clean change, and the next inference from there is that the remote review can be skipped, which is the one outcome the review contract exists to prevent, so the local pass is an input to the loop and never a substitute for the round the merge gate requires.
+- Record a disproved review finding somewhere the next round will read it, so the same proof is not built twice. [`.github/copilot-instructions.md`][copilot-instructions] already says the reviewer is sometimes factually wrong, already requires a decline to carry evidence, and already keeps a list of known non-working request paths, which is the shape this wants. What it has nowhere to put is the finding itself, so a claim disproved against a downloaded binary in one session is argued from scratch in the next. The worked example is the claim that `keys_unsorted` needs jq 1.6, disproved against a 1.5 binary on which `keys_unsorted` works and `walk/1` does not. Note the reason this is not simply a list to append to, which is that a disproof is true of one tree at one revision, so an entry outliving the code it was proved against becomes a reason not to check, and that is strictly worse than re-proving it. Each entry therefore records what was tested and against which revision, and an entry whose subject changes is deleted rather than edited.
+- Refresh the README, which 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, since it must track what the docs contain.
+- 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][issue-363]).
+- Sweep `ManagePackageVersionsCentrally` placement to `Directory.Packages.props` fleet-wide, since PlexCleaner sets it in `Directory.Build.props`, off the CODESTYLE canonical.
+- Consider renaming this repo to reflect the audit-catalog identity, which updates badge and link URLs across the fleet.
+
+<!-- Issues -->
+
+[issue-305]: https://github.com/ptr727/ProjectTemplate/issues/305
+[issue-310]: https://github.com/ptr727/ProjectTemplate/issues/310
+[issue-353]: https://github.com/ptr727/ProjectTemplate/issues/353
+[issue-363]: https://github.com/ptr727/ProjectTemplate/issues/363
+[issue-364]: https://github.com/ptr727/ProjectTemplate/issues/364
+[issue-365]: https://github.com/ptr727/ProjectTemplate/issues/365
+[issue-379]: https://github.com/ptr727/ProjectTemplate/issues/379
+[issue-456]: https://github.com/ptr727/ProjectTemplate/issues/456
+[issue-483]: https://github.com/ptr727/ProjectTemplate/issues/483
+[issue-489]: https://github.com/ptr727/ProjectTemplate/issues/489
+[issue-490]: https://github.com/ptr727/ProjectTemplate/issues/490
+[issue-509]: https://github.com/ptr727/ProjectTemplate/issues/509
+[issue-519]: https://github.com/ptr727/ProjectTemplate/issues/519
+[issue-521]: https://github.com/ptr727/ProjectTemplate/issues/521
+[issue-523]: https://github.com/ptr727/ProjectTemplate/issues/523
+[issue-552]: https://github.com/ptr727/ProjectTemplate/issues/552
+[issue-558]: https://github.com/ptr727/ProjectTemplate/issues/558
+[issue-570]: https://github.com/ptr727/ProjectTemplate/issues/570
+[issue-577]: https://github.com/ptr727/ProjectTemplate/issues/577
+[issue-578]: https://github.com/ptr727/ProjectTemplate/issues/578
+[issue-579]: https://github.com/ptr727/ProjectTemplate/issues/579
+[issue-580]: https://github.com/ptr727/ProjectTemplate/issues/580
+
+<!-- Pull requests -->
+
+[pr-537]: https://github.com/ptr727/ProjectTemplate/pull/537
+[pr-572]: https://github.com/ptr727/ProjectTemplate/pull/572
+
+<!-- Repo -->
+
+[agent-safety]: ./host-setup/agent-safety/
+[agents]: ./AGENTS.md
+[audit]: ./spec/audit.py
+[audit-doc]: ./AUDIT.md
+[codestyle]: ./CODESTYLE.md
+[copilot-instructions]: ./.github/copilot-instructions.md
+[divergences]: ./spec/divergences.json
+[divergences-report]: ./reports/divergences.md
+[files]: ./spec/files.json
+[governance]: ./GOVERNANCE.md
+[markdownlint]: ./.markdownlint-cli2.jsonc
+[matrix]: ./reports/conformance-matrix.md
+[operations]: ./OPERATIONS.md
+[pr-review]: ./scripts/pr_review.py
+[prose-lint]: ./scripts/prose_lint.py
+[readme-structure]: ./spec/readme-structure.md
+[repo-gate]: ./scripts/repo_gate.py
+[reports]: ./reports/
+[repos]: ./registry/repos.json
+[scripts]: ./scripts/README.md
+[secrets]: ./spec/secrets.json
+[secrets-schema]: ./spec/secrets.schema.json
+[section-model]: ./spec/section-model.md
+[standup]: ./STANDUP.md
+[workflows]: ./catalog/snippets/workflows/
+[write-guard]: ./host-setup/agent-safety/gh-write-guard.py