doc-triggers cannot see root documents, so their headers are decorative #22

New Issue

Closed

opened 2026-08-18 00:07:50 -05:00 by null · 0 comments

null commented

2026-08-18 00:07:50 -05:00

Owner

doc-triggers.py collects governing documents with:

DOCS = ROOT / "docs"
for doc in sorted(DOCS.rglob("*.md")):

So it reads nothing at the repository root. README.md, project-readme-template.md and the two new START-HERE-*.md documents all carry Status, Governs and Review trigger lines that nothing ever reads. Changing a file those documents govern fires nothing, and the output says "No document's Governs matched these paths" — which is true of the tool and false of the repository.

Demonstrated after correcting README.md's own Governs: line, which said Projects/Template/** — accurate while this was a folder inside Projects/, and matching nothing once it became a repository root. It now names the three root documents it actually makes claims about, and still fires nothing, because the tool cannot see it.

This is the same family as #21 and worth counting as one. There, three documents were classified as path-governing and given a glob no file could match; here, four documents are excluded from collection altogether. Both are a check that is silent about the thing it was pointed at, and in both cases the screen said something reassuring instead.

Root documents genuinely do govern paths. README.md describes the two start-here documents and links to them; when one is renamed or rewritten, README is exactly the document that should be revisited, and today nothing says so.

Fix: collect from the root as well — ROOT.glob("*.md") alongside the existing DOCS.rglob("*.md"), non-recursive at the root so a vendored copy or a stray directory of notes cannot enrol itself. Everything downstream already handles a document path outside docs/.

Worth checking while in there whether anything else assumes documents live only under docs/; the same assumption in the conformance reader is what excluded these files from doc-claims until they were staged.

Handing over rather than taking it, since doc-triggers.py has been rewritten twice today and two sessions in one file is the collision commit-mine.sh exists to prevent.

Verify: touching START-HERE-New-Project.md fires README.md, and touching a file under docs/ still fires exactly what it fires today.

`doc-triggers.py` collects governing documents with: DOCS = ROOT / "docs" for doc in sorted(DOCS.rglob("*.md")): So it reads nothing at the repository root. `README.md`, `project-readme-template.md` and the two new `START-HERE-*.md` documents all carry `Status`, `Governs` and `Review trigger` lines that **nothing ever reads**. Changing a file those documents govern fires nothing, and the output says "No document's Governs matched these paths" — which is true of the tool and false of the repository. Demonstrated after correcting `README.md`'s own `Governs:` line, which said `Projects/Template/**` — accurate while this was a folder inside `Projects/`, and matching nothing once it became a repository root. It now names the three root documents it actually makes claims about, and still fires nothing, because the tool cannot see it. **This is the same family as #21 and worth counting as one.** There, three documents were classified as path-governing and given a glob no file could match; here, four documents are excluded from collection altogether. Both are a check that is silent about the thing it was pointed at, and in both cases the screen said something reassuring instead. Root documents genuinely do govern paths. `README.md` describes the two start-here documents and links to them; when one is renamed or rewritten, README is exactly the document that should be revisited, and today nothing says so. Fix: collect from the root as well — `ROOT.glob("*.md")` alongside the existing `DOCS.rglob("*.md")`, non-recursive at the root so a vendored copy or a stray directory of notes cannot enrol itself. Everything downstream already handles a document path outside `docs/`. Worth checking while in there whether anything else assumes documents live only under `docs/`; the same assumption in the conformance reader is what excluded these files from `doc-claims` until they were staged. Handing over rather than taking it, since `doc-triggers.py` has been rewritten twice today and two sessions in one file is the collision `commit-mine.sh` exists to prevent. Verify: touching START-HERE-New-Project.md fires README.md, and touching a file under docs/ still fires exactly what it fires today.