Say That a Path Grep Misses a Description of the File

[ptr727]

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

[Copilot]

Pull request overview

This PR tightens the documented deletion-sweep procedure so it no longer relies solely on path-based greps (which catch usages but can miss prose descriptions of a file/directory), by adding an explicit step to reread the repository-description docs after the grep.

Changes:

• Update RESYNC.md deletion workflow to add a post-grep step: read the files that describe what the repo holds, to catch stale descriptions that don`t name the deleted path.
• Update AUDIT.md convergence guidance to include the same post-grep step for any deletion.
• Add a short, measured example motivating why a path grep can miss stale layout prose.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
RESYNC.md	Extends the deletion sweep guidance to include checking repo-description docs after grepping for the deleted path.
AUDIT.md	Mirrors the deletion sweep guidance update in the audit convergence procedure.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

Suppressed comments (1)

AUDIT.md:169

• The PR description says both files carry an identical sentence for this new instruction, but here the wording is embedded mid-sentence (lowercase "then" after a comma) and the follow-up "layout section" example doesn't name where to look. Splitting this into a separate sentence starting with "Then" (matching RESYNC.md) and naming the concrete location (e.g. GOVERNANCE.md "Repository Layout") makes the procedure unambiguous and keeps the two documents in sync.

- **Any deletion sweeps the inbound references to the path, and the sweep is part of the deletion rather than follow-up.** This governs every removal and not only a `hub-only:` one, because nothing about it depends on who owned the file: the removal is one edit and finishing the job usually takes several more, so grep the path tree-wide first and read every hit, then read the files whose job is to say what the repo holds, since a grep for the path finds uses of the file and misses descriptions of it. A layout section calling a deleted script "the apply script" names no path and survives every search for one. A link whose target has an equivalent elsewhere is re-pointed at it, the hub's copy being that equivalent for a hub-hosted file, a **runnable command** citing the path is rewritten to the invocation that still works, and a mention with no equivalent anywhere is removed along with its reference definition, which [GOVERNANCE.md "Documentation Style Conventions"][governance-documentation-style] requires because an orphaned definition fails the no-unused-defs rule. Measured rather than hypothetical, in both directions: retiring `configure.sh` makes five lines of one repo's carried `repo-config/README.md` wrong, two of them commands a reader would run, and deleting a repo-owned nested `AGENTS.md` took three edits across two files, where removing the inline link alone tripped `MD053` on the definition it orphaned and would have failed CI rather than merely breaking prose.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

Suppressed comments (1)

RESYNC.md:76

• The PR description says both files carry the identical sentence; in RESYNC.md that sentence is bolded, so it isn't literally identical to the AUDIT.md wording. If exact matching is intentional (e.g., to simplify future audits/grep), make the sentence formatting consistent by removing the bold markers here (or applying the same formatting in both files).

- **Sweep every inbound reference to the path, and count that as part of the deletion.** This governs any deletion rather than only a `hub-only:` finding. The three bullets above turn on a disposition and so belong to this detector, where the sweep turns on nothing: it applies the same way to a file the repository owns and removes for reasons of its own, which is where the fleet first hit it. Deleting the file is one edit and finishing the job usually takes several more, so grep the path tree-wide before deleting and read every hit. **Then read the files whose job is to say what the repo holds, since a grep for the path finds uses of the file and misses descriptions of it.** A layout section calling a deleted script "the apply script" names no path, so it survives every search for one and goes stale silently. This is measured rather than predicted: a resync deleted a carried script, swept its path across the tree, merged, and left `GOVERNANCE.md` "Repository Layout" still describing the directory as holding it. Three shapes appear among the hits and they are fixed differently. A link whose target has an equivalent elsewhere is **re-pointed** at it, the hub's copy being that equivalent for a hub-hosted file, since a pointer that resolves nowhere teaches a reader that a pointer in carried text is decorative. A **runnable command** citing the deleted path is rewritten to the invocation that still works, and this is the one that costs a reader real time, because a documented command fails where a dead link merely disappoints. A mention with no equivalent anywhere is **removed** rather than re-pointed, and removing a reference-style link removes its definition with it, per [GOVERNANCE.md "Documentation Style Conventions"][governance-documentation-style], since an orphaned definition fails the no-unused-defs rule and is a gate failure rather than untidiness.

[ptr727]

Both suppressed findings answered together, since they and the two threads all trace to one cause: the description claimed an identical sentence and that claim was false.

What was actually verified was that the substring finds uses of the file and misses descriptions of it appeared in both files. I then wrote "Both files verified to carry the identical sentence", which is a wider statement than the check supported. Two rounds of edits went into chasing a claim I should have corrected instead. The description now says the true and narrower thing.

The two concrete suggestions inside those findings were both right and are taken in ed00ea7:

• AUDIT.md opened the instruction mid-sentence on a lowercase "then" after a comma. In a procedure a step hidden inside another clause is a step a reader skips. It is its own sentence now, matching RESYNC.md's structure.
• It named no location. It now names GOVERNANCE.md "Repository Layout" inline, which is the section that actually went stale, so the instruction says where to look rather than only what to look for.

The bold in RESYNC.md stays. Exact matching was never the intent, so the formatting difference is not a defect to normalize away: that file is a procedure and the sentence is a step in it, where AUDIT.md is a reference stating the same rule.

Since this PR is about a rule that missed something, worth recording that the rule it fixes has now been confirmed twice from outside: the ESPHome-Config agent reports the identical "and the apply script" wording sitting unswept in its own Repository Layout, ahead of its own configure.sh retirement, which makes its eleven grep hits across five files a floor rather than a count.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.