Skip to content

paths: a directory can say its own contents are not current - #6

Merged
melbinjp merged 1 commit into
mainfrom
paths/directory-declares-its-contents-stale
Aug 18, 2026
Merged

paths: a directory can say its own contents are not current#6
melbinjp merged 1 commit into
mainfrom
paths/directory-declares-its-contents-stale

Conversation

@melbinjp

Copy link
Copy Markdown
Owner

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.

docs/Docs_To_Review/README.md

# Docs To Review (archival)
This directory is **not published by Mintlify** (`.mintignore` excludes it).
Files here are internal / archival / pending-audit. They are **not** the source of truth.

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 a
sibling.

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:

  1. It matched vocabulary, not declarations. One repo's docs/README.md has a contents
    row reading "Archived history | Preserves completed or superseded context"; another's
    ADR folder lists Deprecated as an allowed status value.
  2. The README that matched sat at docs/, so one loose hit silenced an entire docs tree.
  3. "not published" is about npm and crates.io, and says nothing about authority.

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

"Everything in this directory is a historical record."

from the two sentences the anchor removes, where the phrase is present and the sentence is
about something else:

"docs/adr/0011-....md predates this directory and is preserved as immutable historical record. ... New PRDs live here."
"bender is configured via the configuration.nix file in this directory, and does not currently use Nix flakes."

The second is why the denial carries a copula: bare not current matched does not currently.

Measurement

silenced of which behind a filing
naive, any depth 95 / 217 95
naive, immediate children 31 31
final, anchored 29 0

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 marked
folder. 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

  • A repository whose only docs sit in a marked folder was told its checkout was broken.
    vanished_documents asks HEAD whether an empty run means a failed clone; HEAD knows nothing
    about a folder marker. It now only runs when nothing was deliberately set aside.
  • That same path then said "No documentation found", which is the same lie in a friendlier
    voice - documentation was found and we chose not to judge it. The reasons are now printed
    on both exits, which is why report_set_aside exists.

The skip is quoted, not counted

   docs/Docs_To_Review/ says its own contents are not current, not judged (16): ARCHITECTURE.md, ...
     its README: "Files here are internal / archival / pending-audit. They are **not** the source of truth."

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.

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.
@melbinjp
melbinjp merged commit 6124d99 into main Aug 18, 2026
20 checks passed
@melbinjp
melbinjp deleted the paths/directory-declares-its-contents-stale branch August 18, 2026 13:28
@melbinjp melbinjp mentioned this pull request Aug 18, 2026
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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant