Carry the current copilot-instructions runbook, which had fallen far behind - #94
Conversation
…behind The carried copy was at 170 lines against the hub's 358 and was missing whole sections rather than trailing on wording: the refusal-detection snippet, the suppressed low-confidence findings block and its multi-shape matching, the clear-and-re-request mechanics for a request that is never picked up, the unrecognized-shape rule that blocks the loop and earns an issue, the third carried-content constraint on hub script pointers, and the Disproved Claims section. Nothing said so. The file is intent fidelity checked for presence and for three section headings, all three of which were present, so a body this far behind produced no finding. It surfaced only because the hub touched the file at 6f1dfb5 and tripped the timestamp advisory, which is the gap ProjectTemplate#727 describes. Three adaptations, and nothing else differs from hub main b09078e: - <owner> and <repo> filled as this repository. <N> stays a placeholder, being a pull request number. - Project-specific conventions route to OPERATIONS.md rather than GOVERNANCE.md, since this repository's GOVERNANCE.md is byte-locked carried law that cannot hold a rule specific to it. - Disproved Claims carries the section's shape and its four rules with no entries. The hub's five entries name its own files and revisions and are not this repository's to hold, and the ledger starts empty rather than seeded. The distinctive-phrase probe found no repo-local rule inside the file. Verified with markdownlint, editorconfig-checker, and the fleet prose gate over the changed lines.
There was a problem hiding this comment.
Pull request overview
This PR resyncs the carried .github/copilot-instructions.md runbook with the current ptr727/ProjectTemplate version, restoring multiple missing sections so the repository’s Copilot review workflow and edge-case handling match the hub’s maintained guidance.
Changes:
- Updates the document preface to reflect current routing/authority (AGENTS as entry point; repo-specific conventions in
OPERATIONS.md). - Restores missing Copilot review-loop mechanics (refusal detection, suppressed-comments detection, coverage nuance, retry/unstuck workflows).
- Adds the “Disproved Claims” section scaffold to support repo-local tracking over time.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
…laim The review read the token as a misspelling to correct. It is a quotation: the bullet cites a path a Copilot round actually emitted as the evidence that a partial round can name a file no diff carries. Correcting it would delete the evidence and invert the sentence. The ledger existed with no entries as of the carry, and this is what it is for, since the next round on any pull request touching this file reads the same token with no memory of this one.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.
Suppressed comments (2)
.github/copilot-instructions.md:331
- PR description states the carried "Disproved Claims" section should include the rules but start with no entries for this repository; however this change adds an initial entry about the
GOVENANCE.mdspelling (lines 328-331). Please align either the PR description (if the entry is intended) or the file content (if the section must start empty as described).
- **`GOVENANCE.md` in the partial-coverage bullet of this file is a misspelling and should read `GOVERNANCE.md`.** Raised as an inline finding, reasoning from the correct spelling earlier in the same bullet and from the file that actually exists at the repository root.
- **Disproved by** - reading the sentence the token sits in. It is a quotation, not a reference: "one round here naming `GOVENANCE.md`, a path no diff carries" quotes a path a Copilot review round emitted, as the evidence that a partial round can name a file the diff does not contain. Correcting the spelling would delete the evidence and leave the sentence asserting that a round named a path that does exist, which is the opposite of what it records. The same quotation appears in three further hub files describing the same observed round, so it is a deliberate spelling carried consistently rather than one slip.
- **Proved against** - the `Counts unequal` bullet under "Reading a Coverage Line" in this file, carried from `ptr727/ProjectTemplate` `main` at `b09078e`, where the identical token also appears in `scripts/pr_review.py`, `scripts/README.md`, and `TODO.md`.
- **Delete when** - the quotation is reworded to mark itself as quoted reviewer output, or the bullet stops citing that round.
.github/copilot-instructions.md:21
- The sentence about
AGENTS.mdbeing a thin router with “three byte-locked sections” and “no repository-specific ones” appears inaccurate for this repo:AGENTS.mdincludes repository-specific context (e.g. the ESPHome-Config description) and only explicitly marks one section as byte-locked (the Fleet Bootstrap section). This could mislead reviewers about what content is carried vs repo-specific.
Several of this repository's governance files are carried from a shared template and kept in sync across a fleet of sibling repositories, among them `AGENTS.md`, `CODESTYLE.md`, `WORKFLOW.md`, this file, and the `repo-config/` rulesets. Most of `GOVERNANCE.md` is universal fleet law: every section that states a rule, as opposed to the two that describe this repository's own directory tree and devcontainer, is byte-locked and verified by an automated byte-for-byte match against the template canonical, not by line-by-line review. `AGENTS.md` is the thin router and carries three byte-locked sections of its own, with no repository-specific ones.
The carried sentence said AGENTS.md carries three byte-locked sections "with no repository-specific ones". True of the sections, misleading about the file: everything above the first H2 is this repository's own prose, naming what this repository is and routing to OPERATIONS.md, CODESTYLE.md, WORKFLOW.md and DEVICES.md. That sentence exists to tell a reviewer what may be edited, so reading it as "none of AGENTS.md is editable" is the failure it should prevent. It now names the three sections and says the preamble above them is editable repository content. Raised as a suppressed low-confidence finding on this pull request. The same wording is inaccurate at the hub for the same reason, since its own AGENTS.md carries a preamble too, so it is filed there rather than only fixed here.
|
Answering the round-2 suppressed finding, which opens no thread to resolve.
Accepted, fixed in d50194e. The finding is correct. That sentence is true of the sections and misleading about the file: everything above It matters because that sentence exists to tell a reviewer what may be edited, so being read as "none of The wording is inaccurate at the hub for the same reason, since its own For the record, this is now the fourth adaptation in this pull request, alongside the placeholder fills, the |
|
Answering the second suppressed finding, raised on
Accepted, and the description was the stale half. It was written when the ledger was empty, and two later commits on this branch changed the file underneath it without updating it. The description now says the ledger started empty and holds one entry earned during this pull request's own review, and it lists the fourth adaptation the same commits added. Worth noting the shape, since it is the one the runbook warns about: a description that was accurate when written and became false while the branch moved. Nothing flags that, and a reviewer reading the description against the diff is the only thing that catches it. The finding was right. |
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.md` is 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 spelled `GOVERNANCE.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`, the `Counts unequal` bullet - `scripts/README.md` - `TODO.md` `scripts/pr_review.py:778` and `scripts/tests/test_pr_review.py:1320` are deliberately unchanged, per the issue's own note that a Python string literal reads less like a path. The `pr_review.py` docstring 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.md` is 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 of `AGENTS.md` is editable" when every `AGENTS.md` preamble 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 exactly `Fleet Bootstrap`, `Context and Delegation Discipline`, and `Where the Rules Live` as 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 `intent` fidelity 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 the `test_pr_review` and `test_prose_lint` modules all pass. All three files keep their CRLF endings.
…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.
The hub took both findings this pull request raised. The byte-lock sentence landed there in the same wording used here, so what was an adaptation is now the canonical and this copy simply matches it. The GOVENANCE quotation is now marked as the reviewer's own spelling. That marking is the Delete when condition the ledger entry named, so the entry is deleted rather than edited to look current, which is what the section's own rule prescribes for an entry whose subject moves. The ledger is empty again, and it did its job: the claim was raised once, disproved once, and the proof outlived the thread long enough to reach the hub and be fixed at the source. Three adaptations remain against hub main 79f4f17, and nothing else differs: the placeholder fills, the OPERATIONS.md routing, and the absence of the hub's own five ledger entries.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.
Suppressed comments (1)
.github/copilot-instructions.md:238
- The example command uses a
--repo ptr727/<name>placeholder, but this carried file otherwise hard-codesptr727/ESPHome-Configthroughout. This inconsistency makes the snippet less copy/pasteable and contradicts the PR description that owner/repo placeholders are filled for this repository.
**Use the hub's helper, which has nowhere to type an id.** `scripts/pr_review.py reply <N> --repo ptr727/<name> --match "<words from the finding>" --body "<answer>" --resolve` queries the thread id itself and passes it straight to the mutation. That rule is known and read by the agents that break it anyway, three times so far, so the shape is what changes rather than the wording. It selects on the finding's own words rather than a line number, since a fix push moves the line; it refuses on no match and on more than one rather than picking; and it does not resolve a thread whose reply came back without a `url`. Cross-owner targets it refuses outright, which is where the hand-run form below applies, and there the `gh-write-guard` hook is what reads the maintainer's grant. It is hub-hosted per [GOVERNANCE.md "Hub-Hosted Tooling"](../GOVERNANCE.md#hub-hosted-tooling), so it is invoked from a hub checkout and never rebuilt locally.
The hub writes `--repo <owner>/<name>` in the helper example and `<owner>/<repo>` in every other occurrence, so a fill keyed on the placeholders the manifest names, <owner> and <repo>, leaves that line reading `ptr727/<name>`. It now names this repository like the rest of the file. Raised as a suppressed finding on this pull request. The `<name>` spelling is the hub's, so it will do the same to every repository that carries this file, and it is reported there rather than only fixed here.
|
Answering the round-4 suppressed finding, which opens no thread to resolve.
Accepted, fixed in d71b49e. Correct, and the cause is worth naming: the hub writes that placeholder as Filled here as The two earlier suppressed findings on this pull request are already answered above, and both are now moot against the current head: the ledger entry they concern was retired in |
Resync rounds 2 and 3, against
ptr727/ProjectTemplatemain@79f4f17.The hub touched
.github/copilot-instructions.mdat6f1dfb5, which tripped the timestamp advisory and exposed something much larger: the carried copy was 170 lines against the hub's 358, missing whole sections rather than trailing on wording.What was missing
commit.oidand zero threads, so every coverage check passes and a round that never happened reads as a round that found nothing.Nothing reported it
The file is
intentfidelity, checked for presence and for three named section headings. All three headings were present, so a body this far behind produced no finding anywhere. It surfaced only because the hub happened to touch the file. That gap is ProjectTemplate#727.The three adaptations, and nothing else
Normalizing the placeholders back, this file now differs from hub
main@79f4f17in exactly three places:<owner>and<repo>filled as this repository.<N>stays a placeholder, being a pull request number.OPERATIONS.mdrather thanGOVERNANCE.md. This repository'sGOVERNANCE.mdis byte-locked carried law with two intent sections, so a rule specific to this repository cannot live there.ProjectTemplate's own files and revisions, and the section's own fourth rule says a repository carrying a copy holds the shape rather than those findings.The ledger earned an entry and then retired it, which is the design working
Round 2 review read the quoted
GOVENANCE.mdtoken as a typo to correct. It is a quotation of a misspelling Copilot itself emitted, cited as the evidence that a partial round can name a path no diff carries, so "fixing" it would delete the evidence and invert the sentence. That was declined and recorded as this repository's first ledger entry (860771b), whoseDelete whennamed the one thing that would end it: the quotation being reworded to mark itself as quoted.The hub did exactly that, in #737, so the entry is now deleted (
928e109) rather than edited to look current, which is what the section prescribes for an entry whose subject moves. The claim was raised once, disproved once, and the proof outlived the thread long enough to reach the hub and be fixed at the source.A second round-2 finding said the byte-lock sentence misdescribed
AGENTS.mdhere, and was right. The hub took that fix too, in #738, in the same wording used here, so what was a fourth adaptation is now the canonical and this copy simply matches it.The
carried-instruction-file-guardprobe ran over the old copy first and found no repo-local rule inside it: every target-only line was an older phrasing of a hub line, a placeholder fill, or theOPERATIONS.mdrouting kept above.Verification
markdownlint-cli2over**/*.md,editorconfig-checker, and the hubprose_lint.pyover the 200 changed lines. All clean.