Conversation
A backlog entry, not a fix. TODO disposition: **New entry**, per `TODO.md` rule 8. ## What happened A reviewer raised the same false claim **twice** about the same canonical: 1. Against the hub's `AUDIT.md` section 6 snippet, where it was **disproved by execution** — running both builtins on `jq-1.5-1-a5b5cbe` showed `keys_unsorted` evaluates there while `walk(.)` answers a compile error. Recorded in `.github/copilot-instructions.md`. 2. Against a downstream repository's **carried copy** of that same snippet, where it was disproved a second time, independently, from the jq 1.5 manual. The downstream repository could not cite the first disproof. The record's own preamble says so: > *"The entries are this repository's own. Each names a file and a revision, so a repository holding a copy of this file carries the shape and the rules above rather than these findings, deletes an entry whose subject it does not carry, and records what it has proved itself."* ## Why this is a decision and not a defect **The existing rule is right about what it governs.** Carrying the hub's findings downstream would carry claims about files a repository does not have, each naming a revision it never had. That is exactly the staleness the per-repository rule prevents, so the answer cannot be to relax it. Any fix has to distinguish the *subject* of a finding from the *repository that filed it*. **And the independent re-derivation was not wasted.** The second disproof came from the manual where the first came from a binary, so together they cover intent and behavior rather than repeating each other. A rule that suppressed the second would have lost that. **The cost is bounded**: once per repository per finding, on carried text only, and only when a reviewer raises the same point twice. Small enough that **doing nothing is a legitimate outcome**, which is why it is recorded as `decision` rather than acted on. ## Provenance Found by the **ESPHome-Config agent**, which declined the finding on its own repository with a manual citation and a verified `keys ≡ keys_unsorted|sort` equivalence check, then reported it upward because the finding was aimed at carried fleet text and would have been a fleet-wide defect had it held. It noted the citation would be "ready rather than relitigating it" for the next repository. I checked, and under the current rule it will not be, which is the gap this entry records. I verified the claim myself against the hub's record rather than adopting the peer's verdict. Both disproofs stand. ## Verification `prose_lint --diff HEAD`, `repo_gate --check eol`, `markdownlint-cli2`, `editorconfig-checker`: clean. Both reference names used (`copilot-instructions`, `section-model`) already resolve in `TODO.md`. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
A gap in the deletion sweep, found by running the sweep correctly and still leaving a stale claim behind. ## Problem `AUDIT.md` section 10 and `RESYNC.md` section 4 tell a reader to *"grep the path tree-wide first and read every hit."* That finds **uses** of a file and cannot find a **description** of it. A layout bullet calling a deleted script *"the apply script"* names no path, so it survives every search for one and goes stale silently. ## Measured, not predicted Blog's resync deleted its carried `repo-config/configure.sh`, swept the path across the tree, read every hit, and merged. `GOVERNANCE.md` "Repository Layout" still described `repo-config/` as holding *"branch rulesets and the apply script"*. The sweep was run correctly. The rule was what fell short. It was caught one PR later, by eye, while adding an unrelated bullet to the same section. Since then the ESPHome-Config agent has confirmed the same shape sitting in its own tree, unswept, ahead of its own `configure.sh` retirement: its `Repository Layout` bullet carries the identical wording. Its eleven grep hits across five files are a floor rather than a count. ## Change Both files gain the same instruction, in the same words: after the path grep, read the files whose job is to say what the repo holds. **They are not byte-identical, and that is intended.** An earlier version of this description claimed an identical sentence, which was wrong twice over: the wording differed, and what had actually been verified was that a substring appeared in both. That overclaim generated four review findings and two rounds of edits to content that was already correct. What is true is narrower and is the thing that matters: **the same rule, stated in the same words, with each file carrying its own emphasis and its own evidence.** `RESYNC.md` bolds it as a procedure step and carries the measured case; `AUDIT.md` states it as a reference and names the stale section inline. Two further improvements from review, both real: - The `AUDIT.md` instruction was embedded mid-sentence on a lowercase "then". In a procedure, a step hidden inside another clause is a step a reader skips. It is its own sentence now. - It named no location. It now names `GOVERNANCE.md` "Repository Layout", the section that actually went stale, so a reader knows where to look rather than only what to look for. ## What this does not claim No mechanical check, because a description names nothing a grep can anchor to. It tells the reader where to look, which is narrower and more honest than "read everything." ## Verification `prose_lint --diff HEAD`, `repo_gate --check eol`, `markdownlint-cli2` on both files, `editorconfig-checker`: clean. One defect of my own in this branch, fixed in `a12cd33`: a Python `read_text`/`write_text` rewrite silently converted `RESYNC.md` to LF against this repo's CRLF, and the push went out before `editorconfig-checker`'s exit was read. Restored and verified content-identical with `git diff --ignore-cr-at-eol`. Every later edit here uses `read_bytes`/`write_bytes` and gates before committing. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR promotes two previously-reviewed documentation/procedure refinements into develop: (1) a correction to the deletion “sweep” guidance so it catches descriptive text that a path grep cannot find, and (2) a new TODO backlog entry capturing an open decision about where to record disproofs that target carried fleet text.
Changes:
- Add a new TODO “decision” cluster describing the open question of where fleet-wide disproofs about carried canonical text should live.
- Update deletion-sweep guidance in both
RESYNC.mdandAUDIT.mdto explicitly include reading “repo layout/what it holds” documents after grepping paths, because descriptions can remain stale without containing the deleted path.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| TODO.md | Adds a new decision/backlog entry about handling disproofs for findings on carried fleet text. |
| RESYNC.md | Strengthens the deletion sweep step to include reading repository-description files (e.g., layout docs) after path greps. |
| AUDIT.md | Mirrors the same deletion sweep correction in the convergence guidance, pointing to GOVERNANCE.md “Repository Layout” as the measured stale case. |
💡 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.
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.
Two squashes.
Merge with a merge commit, never a squash, and never with
--delete-branch— this PR's head isdevelop.Why #660 wants promoting rather than waiting
It corrects a rule that is actively being followed. Blog's resync ran the sweep correctly, merged, and still left
GOVERNANCE.md"Repository Layout" describingrepo-config/as holding "the apply script" — a file it had just deleted.The ESPHome-Config agent has since confirmed the identical wording sits unswept in its own
Repository Layout, ahead of its ownconfigure.shretirement. Its eleven grep hits across five files are a floor rather than a count. Promoting this puts the corrected rule in front of that work rather than behind it.Verification on the merged head
spec/validate.pyOK,spec/audit.py --selftestPASS, 557 script tests OK,editorconfig-checkerclean,repo_gate --check eolclean, working tree clean.One defect of my own was found and fixed inside #660: a Python
read_text/write_textrewrite silently convertedRESYNC.mdto LF against this repo's CRLF. Restored ina12cd33and verified content-identical withgit diff --ignore-cr-at-eol.editorconfig-checkeris the only gate that sees that class.🤖 Generated with Claude Code