Mark the Quoted Misspelling and Correct What AGENTS.md Carries - #740
Merged
Conversation
Two wording defects in carried text, each of which every carrier re-raises independently because the copy is faithful. The GOVENANCE.md quotation sits next to a correctly spelled GOVERNANCE.md in the same sentence, with nothing saying it is quoted, so it reads as an obvious typo and a reviewer raises it. Fixing the spelling would delete the evidence and invert the claim, since the sentence exists to say a round named a path no diff carries. Naming it as the reviewer's own spelling ends the finding and keeps the misspelling literal. The scripts/pr_review.py and test docstrings keep the bare quotation, per the issue: a Python string literal reads less like a path, and that docstring already calls it a typo two sentences later. The AGENTS.md sentence said the file carries no repository-specific sections, which is true of the sections and misleading about the file: every AGENTS.md preamble is the repository's own prose. It now names the three byte-locked sections and states that everything above the first is the repository's, which is what a reviewer needs to tell a safe finding from one a local edit would break.
There was a problem hiding this comment.
Pull request overview
This PR updates fleet-carried documentation to (1) clearly mark an intentionally misspelled quoted filename as evidence (so it is not repeatedly “fixed” as a typo downstream), and (2) correct the description of what parts of AGENTS.md are byte-locked versus repository-specific.
Changes:
- Clarify that
AGENTS.mdcontains three byte-locked sections and that the preamble above them is repository-specific and editable. - Mark
GOVENANCE.md(misspelling) as the reviewer’s quoted spelling and explicitly note it is a path no diff carries, preserving the evidentiary value without reading as an unmarked typo. - Apply the same clarification consistently across the Markdown locations that quote the misspelling.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| TODO.md | Marks the GOVENANCE.md mention as the reviewer’s spelling to prevent recurring false “typo fix” findings. |
| scripts/README.md | Adds the same quoted-spelling marker in the partial-coverage explanation to preserve evidence and reduce downstream re-litigation. |
| .github/copilot-instructions.md | Clarifies AGENTS.md editability boundaries and marks GOVENANCE.md as an intentionally quoted reviewer spelling. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
ptr727
added a commit
that referenced
this pull request
Aug 15, 2026
…xes (#741) Promotes `develop` to `main`. Two commits since #734, both governance rather than tooling, and the trial merge is conflict-free. Closes #737 Closes #738 ## #736, the publisher and validator declared at intent fidelity `spec/files.json` gains `.github/workflows/publish-release.yml` and `.github/workflows/validate-task.yml`, and the two matching `investigate` rows leave `spec/divergences.json`, a declared file being no longer a gap. This reverses the call #732 shipped. That change settled both as `accepted`, which silences the finding and stops the audit measuring either file again, and the maintainer caught that as the opposite of what the fleet wants for them. `interface` genuinely does not fit, since job keys and triggers are per-repo across every carrier, but `intent` does: presence asserted, equivalence judged by hand, and a staleness advisory when the hub's copy moves past a carrier's. Scope is measured rather than assumed. The publisher applies to the three publishing `releaseTrigger` values, which selects exactly the 18 carriers, since every repository lacking one carries `releaseTrigger: none`. The validator applies to `*` by decision, making the reusable validation task the fleet standard. What promoting this turns on, fleet-wide, measured in one run at `audit run 2026-08-15T17:35:45Z | hub 0713008`: 0 absences for the publisher, 8 for the validator (homeassistant-purpleair, KiCadLibrary, EspDinIoT, ESPHome-Config, HomeAssistant-Config, DevKitCIoT, Vantage-Config, HolidayLights), and 30 staleness advisories. 17 of those 30 are a known false class, since the advisory has no action-pin normalization and the hub's publisher last changed in a Dependabot bump, filed as #735. `reports/plexcleaner/audit.md` is updated in the same commit, since it is the report the earlier settlement was written into. ## #740, two carried-wording fixes Both raised by Copilot against a carried copy on ptr727/ESPHome-Config#94, and both are the same failure: a faithful copy makes every carrier re-litigate one finding. - **#737**: the `GOVENANCE.md` quotation now reads as quoted ("the reviewer's own spelling and a path no diff carries") in the three Markdown occurrences. The misspelling stays literal, because it is the evidence for the sentence it sits in. - **#738**: the `AGENTS.md` sentence named no sections and read as "none of this file is editable". It now names the three byte-locked sections and states that the preamble above them is the repository's own. ## Verification Run against `develop` at `7c67328`: whole-tree prose gate, `repo_gate.py` (eol, eol-coverage, sha-pin), `spec/validate.py`, `spec/audit.py --selftest`, `build_dist.py --check`, markdownlint, and editorconfig-checker all pass. `git merge-tree` of `main` and `develop` is conflict-free, so there is no EOL-only conflict to resolve on this promotion.
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 free
to 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.
Closes #737
Closes #738
Two wording defects in
.github/copilot-instructions.md, both raised by Copilot against the carried copy on ptr727/ESPHome-Config#94. They ship together because they are the same failure: a carried file whose faithful copy makes every carrier re-litigate the same finding, which is exactly what a per-repository Disproved Claims ledger cannot absorb.#737, the unmarked quotation
GOVENANCE.mdis quoted as the spelling a review round actually emitted, and it is the evidence for the sentence it sits in: a partial round can name a path no diff carries. Nothing marked it as quoted, and it sits in the same sentence as a correctly spelledGOVERNANCE.md, so it reads as an obvious typo. Correcting the spelling would delete the evidence and invert the claim, since the sentence would then say a round named a path that does exist.Each Markdown occurrence now reads "the reviewer's own spelling and a path no diff carries", which is the marker the issue proposed and leaves the misspelling literal:
.github/copilot-instructions.md, theCounts unequalbulletscripts/README.mdTODO.mdscripts/pr_review.py:778andscripts/tests/test_pr_review.py:1320are deliberately unchanged, per the issue's own note that a Python string literal reads less like a path. Thepr_review.pydocstring also calls it "that typo" two sentences later, so the disambiguation is already there in the prose that matters.#738, what AGENTS.md actually carries
The sentence read "
AGENTS.mdis the thin router and carries three byte-locked sections of its own, with no repository-specific ones". True of the sections, wrong about the file, and wrong in a way that inverts the sentence's purpose: it exists so a reviewer knows what is safe to flag, and it reads as "none ofAGENTS.mdis editable" when everyAGENTS.mdpreamble is the repository's own prose.Reworded as the issue proposed, naming the three sections and stating that everything above the first is the repository's own and editable. Verified the three names against
spec/files.json, which declares exactlyFleet Bootstrap,Context and Delegation Discipline, andWhere the Rules Liveas the verbatim sections, so the sentence is accurate in every carrier rather than only here.Downstream
ESPHome-Config already applied the #738 reword locally, which
intentfidelity permits, and recorded #737 as its first Disproved Claims entry whose "Delete when" names this change. Both retire on that repository's next resync.Verified: whole-tree prose gate, markdownlint on the three files,
repo_gate.py,spec/validate.py,build_dist.py --check, editorconfig-checker, and thetest_pr_reviewandtest_prose_lintmodules all pass. All three files keep their CRLF endings.