paths: a directory can say its own contents are not current - #6
Merged
Merged
Conversation
People mark a drafts folder with a sentence in the folder's README and docproof could not see it. Twenty-nine findings in one repository sat under 'Files here are internal / archival / pending-audit. They are not the source of truth.' The naive form was measured first and silenced 95 of 217 corpus findings, 66 of them in a repository whose findings had been filed as PRs hours earlier. Three defects: it matched vocabulary rather than declarations (a contents-table row saying 'superseded context'; an ADR folder listing Deprecated as an allowed VALUE), the README it matched sat at docs/ so one hit silenced a whole tree, and 'not published' is about npm rather than authority. Final form needs a conjunction - name the contents AND deny their authority - with the naming half opening the line, which is grammatical rather than lexical: a folder marker is a statement whose subject is the folder. 2 directories across 171 repositories, both correct, 29 silenced, and 0 of them a document behind a filing - checked per document, because that repo has two files named TAURI_VALIDATION_REPORT.md and a per-repo count said the opposite. 34 broken becomes 5 there, and those 5 are what a person classified as real by hand. The 66-finding repository is unchanged at 6. Two bugs surfaced and fixed: an all-disclaimed repository was told its checkout was broken, because vanished_documents asks a HEAD that knows nothing about folder markers; and that path then said 'No documentation found' when documentation was found and set aside. Reasons now print on both exits. Not recursive, and the skip is quoted rather than counted.
Merged
melbinjp
added a commit
that referenced
this pull request
Aug 18, 2026
Two things the listing does not yet carry. #5 is the one that matters to anyone who installs it: the CLI died on any commit message holding a character outside the console codepage, which is how it explains itself. On Windows that is a traceback where the report should be, under exit code 1 - the same code as 'claims contradicted'. #6 stops it arguing with a folder that says, in its own README, that its contents are not the source of truth. On the repository that motivated it, 34 findings become 5, and those 5 are what a person had already classified as real. README pins move with the version because release.yml refuses a tag whose README names a different one.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
People mark a drafts folder by putting a sentence in the folder's README, and docproof could
not see it. This is the fifth skip shape and the first that reads a file other than the
document being judged.
Twenty-nine findings in one repository sat under that sentence. Reporting them is not a
wrong claim about the tree - those files really are stale - it is arguing with a decision the
project wrote down, in the one place a reader would look for it.
The four shapes we had are path-scoped (
HISTORICAL), sentence-scoped (TOMBSTONE),label-line-scoped (
RETIRED_LABEL) and field-scoped (declares_done). None can reach asibling.
The naive version was measured first, and it was a disaster
Matching the vocabulary anywhere in a directory README silences 95 of 217 corpus findings,
66 of them in a repository whose findings were filed as pull requests hours earlier. A rule
that retracts a filing is not a precision rule.
Three defects, each visible only by running it:
docs/README.mdhas a contentsrow reading "Archived history | Preserves completed or superseded context"; another's
ADR folder lists
Deprecatedas an allowed status value.docs/, so one loose hit silenced an entire docs tree.What it requires instead
A conjunction - the sentence must name the directory's contents and deny their
authority - and the naming half must open the line. That second condition is grammatical
rather than lexical: English puts the subject first, and a folder marker is a statement whose
subject is the folder. It is what separates
from the two sentences the anchor removes, where the phrase is present and the sentence is
about something else:
The second is why the denial carries a copula: bare
not currentmatcheddoes not currently.Measurement
Two directories across 171 repositories, both readings correct.
The zero is checked per-DOCUMENT, not per-repository, and here that matters more than it
looks: the affected repository holds two different files called
TAURI_VALIDATION_REPORT.md,one at
docs/that a pull request was opened about and an archival copy inside the markedfolder. A count by repository cannot tell those apart and briefly claimed the opposite.
End to end on that repository: 34 broken becomes 5, and the 5 are exactly the ones a
person had already classified as real by hand. On the repository with 66 findings: 6 before,
6 after, identical.
Thin base, taken anyway, and the reason is the honest one: that project would otherwise be
shown 34 findings of which one is real, and a tool that cries wolf gets uninstalled inside a
minute whatever else is true about it.
Two bugs this surfaced, both fixed here
vanished_documentsasks HEAD whether an empty run means a failed clone; HEAD knows nothingabout a folder marker. It now only runs when nothing was deliberately set aside.
voice - documentation was found and we chose not to judge it. The reasons are now printed
on both exits, which is why
report_set_asideexists.The skip is quoted, not counted
Every other skip can be audited by opening the document that was skipped. This one's reason
lives in a neighbouring file the reader is not looking at, so a bare count would be a skip
nobody could check.
Not recursive, deliberately: a marker is a statement about the things beside it, and
letting it reach down through subdirectories is how defect 2 gets back in. Tested.
Twelve new tests, each one a defect that was measured rather than imagined. 158 pass, ruff
clean, docproof passes on itself.