Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions RESYNC.md
Original file line number Diff line number Diff line change
Expand Up @@ -102,6 +102,7 @@ flowchart LR
- **An `accepted` disposition closes the hit permanently**, whether it is a path collision or a file every repository legitimately owns, such as `LICENSE` and `TODO.md`.
- **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. The named-path half of this class is mechanized: `scripts/prose_lint.py --check dead-path` reports a Markdown mention of a path git once tracked and the tree no longer holds, continuously rather than only at deletion time, so the manual read here is what covers the description that names no path, which no pattern reaches. 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.
- **The sweep covers references and descriptions.** Remove or replace every link, command, and prose claim that depends on the deleted path. Remove each orphaned reference definition in the same edit so Markdown remains valid.
- **A repository's pinned `validate-task.yml` SHA can predate the `retire` disposition's own `dead-path` exemption.** `dead_path_findings()` in `.github/actions/prose-gate/prose_lint.py` exempts a path from a `dead-path` finding only when that path sits in its `HUB_HOSTED` set, a literal list kept in step with `spec/divergences.json`'s `retire` entries. A repository whose pin predates the hub commit that added a path to `HUB_HOSTED` does not see that exemption yet, so deleting the retired local copy per this procedure leaves that repository's own CI failing a `dead-path` finding on the exact path just retired. Before deleting a path with a matching `HUB_HOSTED` entry, run `git log main -1 --format=%H -S'<path>' -- .github/actions/prose-gate/prose_lint.py` from the fetched hub checkout to read the exemption commit, then `git merge-base --is-ancestor <exemption-sha> <pinned-sha>` against the repository's pinned `validate-task.yml` SHA. A SHA is opaque, so ancestry is what settles the order, never a text or timestamp comparison. If the ancestry check fails, bump the pin first, in the same resync, before retiring the local copy.

## 5. What a Resync Cannot Detect

Expand Down