doc-triggers never fires three documents whose Governs carries a gloss after the glob #21

New Issue

Closed

opened 2026-08-17 23:51:35 -05:00 by null · 0 comments

null commented

2026-08-17 23:51:35 -05:00

Owner

The cause is a Governs: entry that carries a gloss after the glob:

docs/data/README.md              Governs: docs/data/** — the assets privacyllc.dev renders for this project
docs/data/img/README.md          Governs: docs/data/img/** — the three files and their sizes
docs/architecture/githooks/README.md  Governs: docs/architecture/githooks/** and the .githooks/ a project installs

Governs: is split on commas only, so each of those is one entry and the whole string is used as the glob. looks_like_path() says yes (it contains /), so the document is classified as path-governing rather than subject-governing. Then matches() tests fnmatch("docs/data/img/icon.webp", "docs/data/** — the assets privacyllc.dev renders for this project"), which is false and always will be. The document is therefore not fired, and — because it was classified as path-governing — it is also absent from the "govern a subject rather than paths, judge them yourself" list that exists precisely to stop a reader concluding everything was checked.

Measured at 81e3268:

docs/data/README.md              vs docs/data/img/icon.webp             -> False
docs/data/img/README.md          vs docs/data/img/icon.webp             -> False
docs/architecture/githooks/README.md vs docs/architecture/githooks/pre-commit -> False

What it costs

This is the same class as #20 and the opposite sign, which makes it worse. #20 was a document firing when it should not — a false prompt, and the cost is a glance. This is a document silently not firing when it should — the cost is a document that goes quietly stale while a tool whose entire purpose is to prevent that reports success. GUARDS.md opens with the sentence that applies: a guard that cannot fail is worse than no guard, because it is trusted.

docs/data/img/README.md is the document that governs the branding assets, which is the subject of open issue #14. Editing those assets has never once prompted the document that specifies their names, dimensions and ceilings.

The gloss is in the template's own documents at its first commit (6965915), so no adopting project has ever had these three fire either.

What to do

Extract the glob from the entry rather than using the entry whole:

Cut the entry at the first gloss marker — an em dash, en dash, or -- surrounded by spaces — and keep the left side.
Take the whitespace-separated tokens of that left side which themselves pass looks_like_path().
If that yields nothing, fall back to the entry as it is, so an entry shaped in some way not foreseen here behaves exactly as it does today.

Keep classification untouched: whether a document is path-governing or subject-governing must still be decided by looks_like_path() on the whole entry, or documents move between the two lists as a side effect.

Also treat a glob with a trailing / as a directory prefix. docs/architecture/githooks/README.md governs "the .githooks/ a project installs", and after step 2 that yields the bare token .githooks/, which fnmatch will not match against .githooks/pre-commit.

Traps

Do not strip on a bare -: source-grep and doc-claims appear in these headers and would be cut in half.
The gloss cut must require surrounding whitespace, or a path containing a dash is truncated.
privacyllc.dev in the docs/data/README.md gloss passes looks_like_path() on the extension rule, so extracting tokens from the whole entry rather than from the left of the gloss reintroduces it as a spurious glob. Cutting at the gloss first is what avoids it.
Verify against every document in the tree, not the three named here — the corpus is the test.

Verify: docs/data/README.md and docs/data/img/README.md both fire on docs/data/img/icon.webp; docs/architecture/githooks/README.md fires on docs/architecture/githooks/pre-commit and on .githooks/pre-commit; privacyllc.dev does not match docs/data/README.md; the seven path-governing and twelve subject-governing documents are classified exactly as they are now.

Three of the seven path-governing documents have never fired, for anything, since the template was first committed. They are not reported as skipped either — they fall into neither list, so nothing on screen says they were not checked. The cause is a `Governs:` entry that carries a gloss after the glob: ``` docs/data/README.md Governs: docs/data/** — the assets privacyllc.dev renders for this project docs/data/img/README.md Governs: docs/data/img/** — the three files and their sizes docs/architecture/githooks/README.md Governs: docs/architecture/githooks/** and the .githooks/ a project installs ``` `Governs:` is split on commas only, so each of those is **one entry** and the whole string is used as the glob. `looks_like_path()` says yes (it contains `/`), so the document is classified as path-governing rather than subject-governing. Then `matches()` tests `fnmatch("docs/data/img/icon.webp", "docs/data/** — the assets privacyllc.dev renders for this project")`, which is false and always will be. The document is therefore not fired, and — because it was classified as path-governing — it is also absent from the "govern a subject rather than paths, judge them yourself" list that exists precisely to stop a reader concluding everything was checked. Measured at `81e3268`: ``` docs/data/README.md vs docs/data/img/icon.webp -> False docs/data/img/README.md vs docs/data/img/icon.webp -> False docs/architecture/githooks/README.md vs docs/architecture/githooks/pre-commit -> False ``` ## What it costs This is the same class as #20 and the opposite sign, which makes it worse. #20 was a document firing when it should not — a false prompt, and the cost is a glance. This is a document silently not firing when it should — the cost is a document that goes quietly stale while a tool whose entire purpose is to prevent that reports success. `GUARDS.md` opens with the sentence that applies: a guard that cannot fail is worse than no guard, because it is trusted. `docs/data/img/README.md` is the document that governs the branding assets, which is the subject of open issue #14. Editing those assets has never once prompted the document that specifies their names, dimensions and ceilings. The gloss is in the template's own documents at its first commit (`6965915`), so no adopting project has ever had these three fire either. ## What to do Extract the glob from the entry rather than using the entry whole: 1. Cut the entry at the first gloss marker — an em dash, en dash, or ` -- ` surrounded by spaces — and keep the left side. 2. Take the whitespace-separated tokens of that left side which themselves pass `looks_like_path()`. 3. If that yields nothing, fall back to the entry as it is, so an entry shaped in some way not foreseen here behaves exactly as it does today. Keep classification untouched: whether a document is path-governing or subject-governing must still be decided by `looks_like_path()` on the **whole entry**, or documents move between the two lists as a side effect. Also treat a glob with a trailing `/` as a directory prefix. `docs/architecture/githooks/README.md` governs "the `.githooks/` a project installs", and after step 2 that yields the bare token `.githooks/`, which `fnmatch` will not match against `.githooks/pre-commit`. ## Traps - Do not strip on a bare `-`: `source-grep` and `doc-claims` appear in these headers and would be cut in half. - The gloss cut must require surrounding whitespace, or a path containing a dash is truncated. - `privacyllc.dev` in the `docs/data/README.md` gloss passes `looks_like_path()` on the extension rule, so extracting tokens from the *whole* entry rather than from the left of the gloss reintroduces it as a spurious glob. Cutting at the gloss first is what avoids it. - Verify against every document in the tree, not the three named here — the corpus is the test. Verify: `docs/data/README.md` and `docs/data/img/README.md` both fire on `docs/data/img/icon.webp`; `docs/architecture/githooks/README.md` fires on `docs/architecture/githooks/pre-commit` and on `.githooks/pre-commit`; `privacyllc.dev` does not match `docs/data/README.md`; the seven path-governing and twelve subject-governing documents are classified exactly as they are now.