Read the Line-Ending Pins Against the Tree, Not Just Each Other

[ptr727]

Closes#633.

The gap

repo_gate.py --check eol compares .gitattributes against .editorconfig and never compares either against the repository. That direction is correct and stays unchanged. What it cannot see is the tree: both documents can agree perfectly and both be wrong about the repository they describe, and spec/files.json marks .gitattributes as intent, so what stood in the gap was an agent reading the file for meaning during an audit.

Measured, not argued

ptr727/Blog at 392de22 carried both shapes. Run against that commit:

--- eol, before and after this change ---
[ok ] eol 0 issue(s)
note: .editorconfig sets end_of_line = lf globally, so that default satisfies
every pin and nothing here read pin content. Use eol-coverage instead.
--- eol-coverage, new ---
[FAIL] eol-coverage 3 issue(s)
ops/vps-backup-pull: a shebang script git resolves to `eol: unspecified`, not `lf`
.gitattributes pins `deploy/blog-deploy-shell` to LF and no tracked file matches it
.gitattributes pins `deploy/authorized_keys` to LF and no tracked file matches it

All three reported defects caught, and Blog's other six pins raise nothing. ops/vps-backup-pull is run unattended by systemd on a backup host, so a CRLF checkout hands it a broken interpreter line.

The dead pin is the worse half. The comment above Blog's two asserted the extensionless case was handled, so the one real instance twenty lines up read as covered by everyone who opened the file. A dead pin does not merely fail to bind, it reads as coverage.

What ships

• eol-coverage, a new check rather than a widened eol. Widening in place would make the docstring, scripts/README.md, and TestEol wrong at once, and would destroy the ability to ask the config question alone.
• unpinned: a tracked file opening #! that git does not resolve to eol=lf. Delegates to git check-attr, so it cannot disagree with what a checkout applies. The shebang decides rather than the mode bit, since the two move independently. This starts enforcing the GOVERNANCE.md "Line Endings" sentence "any repo whose tooling ships extensionless scripts adds the matching path pin", which had nothing behind it. This repo passes with zero slack: 16 tracked #! files, 16 resolving to lf.
• dead: a pin matching no tracked file, unless its block is marked forward-declared.
• A vacuity note on eol. Where .editorconfig sets [*] end_of_line = lf, the override the check looks for is satisfied by the global default for any path, an absent one included, so the check asserts nothing about pin content. Blog is shaped that way, as are the repos declaring lineEndings: lf in registry/repos.json. It does not fail there, it says what it did not read.

The exemption decision

Three of this repo's pins match nothing today and all three are correct: uv.lock, Dockerfile, *.Dockerfile. .gitattributes is carried, so those go live the moment a consumer adds a lockfile or a Dockerfile, which the file already said in prose. The forward-declared token makes that prose machine-readable and travels with the carried copy, so a python repo holding the baseline without a lockfile stays exempt too.

Two alternatives rejected: an exception list inside the script restates data the scanned repository already carries, and diffing against the hub's own .gitattributes makes a repo gate change verdict when another repository changes and cannot run standalone.

What it trades away is stated rather than left to be found: the mark reaches to the next blank line, so a pin appended under a marked block inherits an exemption nobody wrote for it, and that fails open. TestGitattributesCoupling therefore names the three pins the marking is for and fails the moment a fourth arrives, rather than the parser growing a second rule.

Two implementation notes

Matching is gitattributes matching, not pathspec matching.git ls-files -- <pattern> is the cheap way to ask whether a pin binds anything and is a different language: there * crosses a /, so capture/*.py also matches capture/sub/x.py and a dead pin reads as live. attr_glob handles basename-versus-anchored, the leading slash, ** as a whole segment, and character classes, with a 20-case table.

The shebang floor is a suite case rather than a runtime finding. A source-only configuration repo shipping no scripts is legitimately clean, so failing an empty scan would be a false finding in the common fleet case. What must not go unnoticed is this repo's own scan going quiet, which TestCoverageFloors holds instead. Every run still prints its counters, for the reason sha-pin does.

Deliberately out of scope

The symmetric .editorconfig reading, a path-specific section naming files that do not exist. This repo's [.github/workflows/*] and [catalog/snippets/workflows/*] sections are legitimately broad, so the exemption needs measuring against the live corpus before a gate is built on it. Recorded in TODO.md under Standalone Chores.

TODO.md also gains a ready Work Cluster for the general case this issue is one instance of: an observer that reads merged fleet pull requests and classifies each changed path against what the hub declares it owns. Nothing detected the downstream editing hub-managed CI files here except the maintainer noticing.

Verification

• 496 script self-tests pass, test_repo_gate.py going 46 to 70 cases, harness floor raised to 68.
• Each direction was watched failing on the reintroduced defect in a scratch clone, and passing again on restore, rather than trusted from a green run.
• spec/validate.py, spec/audit.py --selftest, all three repo gates, whole-tree prose_lint.py, markdownlint-cli2 and editorconfig-checker all clean. CRLF preserved in the three Markdown and dotfile edits, LF in both scripts.

[Copilot]

Pull request overview

Adds a new filesystem-facing line-ending gate (eol-coverage) so the existing eol check is no longer “document-to-document only” and can detect cases where .gitattributes/.editorconfig agree with each other but are still wrong for the tracked tree (including dead pins and unpinned shebang scripts).

Changes:

• Add eol-coverage to scripts/repo_gate.py, including forward-declared pin marking, shebang detection, and gitattributes-style glob matching for dead-pin detection.
• Expand scripts/test_repo_gate.py with unit/integration-style tests covering the new check, the forward-declared marker behavior, and matching semantics.
• Update documentation and carried baseline prose to make the new behavior and the forward-declared convention explicit (scripts/README.md, .gitattributes, TODO.md).

Reviewed changes

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

Show a summary per file

File	Description
TODO.md	Records follow-up work and links related to the newly closed gap and future symmetric .editorconfig coverage reading.
scripts/test_repo_gate.py	Adds/extends tests for eol-coverage, forward-declared pin parsing, gitattributes glob semantics, and non-vacuity floors.
scripts/repo_gate.py	Implements the new eol-coverage check plus shared pin parsing, shebang scanning, and dead-pin detection.
scripts/README.md	Documents the new check, its rationale, and the forward-declared exemption mechanism.
.gitattributes	Marks the lockfile/Dockerfile LF pins as forward-declared so dead-pin detection can distinguish carried-baseline pins from genuinely dead ones.

---

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