File the Deletion Sweep Where a Repo-Owned Deletion Reaches It - #656
Merged
Conversation
The sweep landed inside the bullet for a hub-only finding, and the case that generalized it was not one. A repository deleting its own file has no divergences entry, no retire disposition, and no reason to read that bullet, so the rule was documented in the one place its originating case could not find it. Nothing about the sweep depends on who owned the file. It is now its own bullet in AUDIT.md section 10, stated as governing any deletion, and RESYNC.md section 4 says the three disposition bullets above it belong to the detector while the sweep turns on nothing. The repo-owned case is promoted to evidence rather than left as a footnote, because it is what shows the rule is not hub-only, and it is now measured rather than predicted: removing the inline link to a nested AGENTS.md tripped MD053 on the definition it orphaned, so the delete-the-file-only path failed CI rather than merely breaking prose. Raised by the ESPHome-Config agent, which verified the merged text rather than taking it and found the scoping while executing the deletion the rule came from. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Refines the deletion-remedy guidance in the hub’s operational documentation so the “inbound reference sweep” is documented where it applies to any file deletion (including repo-owned deletions), not only hub-only: findings.
Changes:
- AUDIT.md: Splits the inbound-reference sweep into its own bullet and leaves
retiredisposition confirmation scoped tohub-only:. - RESYNC.md: Clarifies that the sweep is disposition-agnostic, and promotes the repo-owned deletion case (with the observed MD053 failure) as evidence.
- Both: Strengthens the rationale for treating the sweep as part of the deletion action, not follow-up.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| RESYNC.md | Re-scopes and strengthens the deletion sweep guidance in the resync procedure, including measured evidence. |
| AUDIT.md | Re-structures section 10 deletion guidance to separate hub-only:-specific checks from the general sweep rule. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Widening the rule to any deletion left RESYNC.md contradicting itself: the bullet said it governs any deletion and then described the link case as needing a hub equivalent and the mention case as having none, which is the narrow framing the widening was supposed to remove. AUDIT.md had been generalized in the same change, so the two documents also stated one rule two ways. Both now read that a link whose target has an equivalent elsewhere is re-pointed at it, with the hub's copy named as that equivalent for a hub-hosted file rather than as the only kind, and that a mention with no equivalent anywhere is removed. The one remaining mention of a hub equivalent describes the evidence case, where the deleted file genuinely had no hub counterpart, and is a fact about that case rather than a scope on the rule. The bolded lead-in carried two sentences where every other bullet in the section bolds only its headline, so the scope sentence moves out of the bold. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Uh oh!
There was an error while loading. Please reload this page.
ptr727 added a commit
that referenced
this pull request
Aug 10, 2026
A fleet-wide defect that **no downstream repository can fix**, so it is the hub's to sweep for the whole class at once. ## Problem Two `verbatim` `GOVERNANCE.md` sections cite `repo-config/configure.sh` as though the reader had a copy: | Section | Form | |---|---| | `Branching Model` | A repo-relative **inline link**, `[configure.sh](./repo-config/configure.sh)` | | `Repository Boundaries and Write Safety` | The bare path, as the **worked example** of when suppressing a write's stdout is legitimate | Both sections are byte-locked fleet-wide, so **all 22 repositories carry those exact words**. The file was retired from the manifest and carries a `retire` disposition in `spec/divergences.json`, so **none of them carries it.** The link resolves nowhere and the example cannot be opened. A downstream repository cannot correct this: editing a verbatim section is what the fidelity check exists to prevent. This file's own `Documentation Style Conventions` rule says so directly, that a review finding against carried rule text is fixed at the hub for the whole class and re-vendored. ## The correct form was already written down `Hub-Hosted Tooling` states it: *"A tool named in a carried rule is therefore named as the hub's, since the alternative is a pointer to a path the reader does not have."* Both mentions now follow that. `Branching Model` additionally says the script runs **from a hub checkout against the repository named on its command line**, which is the invocation a reader actually needs in place of a path they lack. ## Provenance, and the sequencing consequence Raised by the **ESPHome-Config agent** over peer messaging. Sweeping the inbound references for its own `configure.sh` retirement, it found **eleven hits across five files**, and two of them sat inside carried sections its own preamble forbids it to edit: > *"I cannot complete the inbound sweep for configure.sh without either editing carried prose or having already done the AGENTS/GOVERNANCE split that replaces those sections wholesale."* That is a real ordering constraint the hub had not stated: **for any repository whose carried rule text cites the file being retired, the hub-only retirement depends on the instruction set being current first.** This PR removes the constraint at its source rather than documenting it, since after this there is no carried section citing the path. It also observed a **fourth reference shape** that [#654](#654) and [#656](#656) do not cover: a mention that is *about* the path rather than a *use* of it, such as incident history recording that a backtick-quoted `configure.sh` in a review reply once executed the script. "Remove the mention" is wrong for that shape, because the history stays true. Not addressed here, and worth its own decision. ## Verification Checked mechanically rather than by eye: zero repo-relative pointers to `configure.sh` remain in any `verbatim` section of `GOVERNANCE.md`, walking the fidelity declarations in `spec/files.json` rather than a hand list of section names. `prose_lint --diff HEAD`, `markdownlint-cli2`, `editorconfig-checker`: all clean. ## Note on ordering This changes two verbatim sections, so it makes every downstream copy stale and belongs in the next promotion. A Blog resync is in progress on an unpushed branch and is **held** for it, so Blog re-vendors these two sections once from corrected text rather than twice. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Follow-up to #654, fixing a scoping defect in it.
Problem
#654 put the inbound-reference sweep inside the bullet for "A
hub-only:finding" inAUDIT.mdsection 10, and after three disposition-specific bullets inRESYNC.mdsection 4 whose intro scopes to the hub-only detector.The case that produced the rule was not a hub-only finding. It was a repository deleting its own file: no
spec/divergences.jsonentry, noretiredisposition, no hub equivalent. So the rule its case generalized was documented in the one place its case could not reach, and an agent removing a repo-owned file finds nothing.Nothing about the sweep depends on who owned the file. Only the
retire-confirmation step is hub-only-specific.Change
AUDIT.mdsection 10: the sweep becomes its own bullet, stated as governing any deletion. Theretireconfirmation stays with thehub-only:bullet, where it belongs.RESYNC.mdsection 4: the sweep bullet says the three bullets above it turn on a disposition and belong to the detector, while the sweep turns on nothing.The second case is now measured, not predicted
#654 said an orphaned definition "fails the no-unused-defs rule". That has since been observed rather than argued: removing the inline link to a nested
AGENTS.mdtrippedMD053on the definition it orphaned, before the author reached that edit. So the delete-the-file-only path fails CI rather than merely breaking prose, which is a stronger claim than the one shipped.Provenance
Raised by the ESPHome-Config agent over peer messaging. It verified #654's merged text against
ca3df85rather than taking it on trust, and found the scoping while executing the very deletion the rule came from. Its words: "the rule that my case generalized is documented in the one place my case would not have reached."That is the second defect this loop has caught in my own merged work today, both times by a reader doing the thing the doc describes rather than reading it.
Verification
prose_lint --diff HEAD,markdownlint-cli2on both files,editorconfig-checker,repo_gate --check eol: all clean.🤖 Generated with Claude Code