Assert a floor on what a diff-scoped prose run actually scanned

[ptr727]

Why

Every verdict a --diff run reports rests on a scope the run never checked. A gate that finds nothing is indistinguishable from a gate with nothing to find, and the exit code is the same either way.

Four routes to that false clean are already on record, each closed by a guard written after a reviewer noticed it: an unresolvable base widening to a whole-tree scan, a multi-line paths input read only to its first newline, a diff taken in one repository while scanning another, and a path under no repository at all. Per-route guards are the wrong shape for a fifth, because the fifth is found by a reviewer or not at all. LEAST_PLAUSIBLE is already the floor on a whole-tree sweep, so the shape exists in the file and the --diff path is what lacked it.

Fresh evidence for the entry came from the session before this one, where prose_lint --diff --summary printed 0 violation(s) across 0 file(s) on a real change and distinguishing that from a scoping failure took a hand-written call into changed_lines() to prove the scope was non-empty.

What changed

A run that resolves a non-empty diff and matches none of the files it names now exits 2 naming them, instead of exiting 0.

Zero alone is not the test. A change touching only files the rules do not read, an image or a lock file, legitimately matches nothing, so the comparison is against the diff's own list of files this run could have read. unread_diff_files() builds that list, and asked_about() keeps a caller who narrowed the scan on purpose from being told the narrowing is a defect.

The exit code is 2 rather than 1, matching the two guards beside it, so a caller can tell "the gate could not run" from "the gate ran and found something".

The floor found the fifth route immediately

git diff reports repository-relative keys while discovery keys off the directory the run started in. Run from a subdirectory, the intersection is empty and the run reports clean. No existing guard covers it, and it is why unread_diff_files() resolves keys against the repository top level: reading them against the working directory would leave the list empty in exactly the case it exists to catch.

Measured on this branch's own diff, run from scripts/, with the previous revision extracted to a temporary path so both run against the same tree. The error text is verbatim, wrapped here for width:

$ git show HEAD~1:scripts/prose_lint.py > /tmp/prev_prose_lint.py
$ cd scripts && python3 /tmp/prev_prose_lint.py . --diff develop --check dupword
$ echo $?
0

$ cd scripts && python3 prose_lint.py . --diff develop --check dupword
error: the diff against 'develop' names 2 readable file(s) this run was asked about, and the
scan matched none of them: scripts/prose_lint.py, scripts/test_prose_lint.py. Refusing to
report a clean run, since a gate that read nothing is indistinguishable from a gate with
nothing to read. Check that the run starts at the repository top level and that the requested
paths cover the change.
$ echo $?
2

Both directions are tested, and the second one is the larger half

Ten cases. Three fail against the previous revision, which is what proves the floor bites. The other seven pass against both revisions on purpose: they hold the direction that matters more, that a legitimate zero stays a clean run. A gate that cries wolf on a commit adding a logo is how a safety check stops being read.

The must-not-fire cases are a deliberate narrowing, an empty diff, an excluded file, a generated tree, a path the diff names that no longer exists, and a binary. Each was confirmed against a real run as well as a mocked one, the binary case with an actual PNG committed in a scratch repository.

Verification

• python3 scripts/test_prose_lint.py - 173 pass, up from 163.
• python3 spec/validate.py, python3 spec/audit.py --selftest, python3 scripts/repo_gate.py - all clean.
• python3 scripts/prose_lint.py . --check charset --check dupword --check spelling - clean, the blocking CI run.
• python3 scripts/prose_lint.py . --diff develop - clean, and it caught two comment blocks in this change breaking the one-sentence-per-line rule, which are fixed.
• Re-run after rebasing onto develop at 3f91868 rather than only on the base the work started from.

Honest limits

An absolute path argument produces an empty list rather than a finding, so the floor falls back to today's behavior there instead of over-blocking. Deletions never enter the scope map at all, since a deletion hunk yields an empty line range, so they cannot trigger it.

The CI jobs in this repo call prose_lint.py without --diff, so nothing here changes what this repo's own pipeline reports. The consumer is .github/actions/prose-gate, which passes --diff and runs from the caller's repository root.

Backlog

Carries the TODO.md cluster "The Prose Gate Scope Floor" whole. It unblocks "The Representative-Data Path Check", which is worth having only once the gate can prove it read something. Per selection step 9 the cluster is deleted when this merges, which is a follow-up commit rather than part of this diff.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR strengthens the reliability of scripts/prose_lint.py --diff by asserting a minimum “diff scope floor”: if a non-empty diff is resolved but the scan matches none of the diff’s readable, in-scope files, the run now fails (exit code 2) rather than reporting a false clean.

Changes:

• Add asked_about() and unread_diff_files() helpers to determine which diff-named files the run was asked to cover and could have read.
• Update main() to exit 2 (with a targeted error message) when a non-empty diff yields zero matched files but the diff names readable files that should have been scanned.
• Add a new TestDiffScopeFloor suite covering both “must fire” and “must not fire” scenarios (including the subdirectory-run key mismatch).

Reviewed changes

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

File	Description
scripts/prose_lint.py	Implements the diff-scope floor check and supporting helpers, returning exit code 2 on confirmed scoping failures.
scripts/test_prose_lint.py	Adds focused unit tests validating the new floor behavior and guarding legitimate zero-match cases.