doc-triggers matches the glob but not the trigger's verb, so the trust map fires on everything #20

New Issue

Closed

opened 2026-08-17 23:42:12 -05:00 by null · 0 comments

null commented

2026-08-17 23:42:12 -05:00

Owner

Touching one script fires three documents:

$ python3 doc-triggers.py docs/architecture/scripts/verify.sh
docs/DOC_TRUST_MAP.md      trigger: Any doc added, deleted or moved; any change to which doc owns a subject
docs/TOOLS.md              trigger: Any script added to, removed from or repurposed in …
docs/architecture/README.md

Only one of the three had a trigger that applied. The session that hit this first checked all three by hand and correctly changed none.

The cause is structural, not a tuning problem. DOC_TRUST_MAP.md declares Governs: docs/**, the broadest glob in the tree, while its Review trigger is among the narrowest: any doc added, deleted or moved. Every edit to any document anywhere under docs/ matches the glob and almost none matches the trigger. It will fire on every docs change this project ever makes, forever, and it is right to — by the only rule the tool currently has.

This is the shape audit-gate.mjs argues about for npm advisories and that preflight.sh just ran into with headers: a signal that always fires is one people stop reading, and it takes the true positives with it. doc-triggers.py exits 0 by design — it is a prompt, not a gate — which makes it more vulnerable to this, not less: nothing forces anyone to look.

The fix is to match the trigger's verb, not only its glob. Git already reports the status letter, and trigger prose is unusually consistent about verbs:

added, deleted or moved → fire on A, D, R only, not M
any script added to, removed from or repurposed in … → the same
any new module, any change to a module boundary or a data shape → A and M both

A first cut needs no prose parsing at all: fire a document on modification only when its trigger does not restrict itself to existence changes, detected by looking for added/deleted/moved/removed without a changed/change to. Conservative direction matters — when the verb is unclear, fire, because a false prompt costs a glance and a missed one costs a document that is confidently wrong.

Two alternatives, both worse. Narrowing the trust map's Governs: to subject form stops it firing at all, including when a document genuinely is added — which is the one case it exists for. Leaving it is the status quo: the tool's first real use produced two false fires out of three.

Handing this to whoever holds doc-triggers.py rather than taking it, since it was rewritten an hour ago and two sessions in one file is the collision commit-mine.sh exists to prevent.

Verify: touching a script fires TOOLS.md and architecture/README.md and not DOC_TRUST_MAP.md; adding or deleting a document under docs/ still fires DOC_TRUST_MAP.md.

Touching one script fires three documents: $ python3 doc-triggers.py docs/architecture/scripts/verify.sh docs/DOC_TRUST_MAP.md trigger: Any doc added, deleted or moved; any change to which doc owns a subject docs/TOOLS.md trigger: Any script added to, removed from or repurposed in … docs/architecture/README.md Only one of the three had a trigger that applied. The session that hit this first checked all three by hand and correctly changed none. **The cause is structural, not a tuning problem.** `DOC_TRUST_MAP.md` declares `Governs: docs/**`, the broadest glob in the tree, while its `Review trigger` is among the narrowest: *any doc added, deleted or moved*. Every edit to any document anywhere under `docs/` matches the glob and almost none matches the trigger. It will fire on every docs change this project ever makes, forever, and it is right to — by the only rule the tool currently has. This is the shape `audit-gate.mjs` argues about for npm advisories and that `preflight.sh` just ran into with headers: a signal that always fires is one people stop reading, and it takes the true positives with it. `doc-triggers.py` exits 0 by design — it is a prompt, not a gate — which makes it *more* vulnerable to this, not less: nothing forces anyone to look. **The fix is to match the trigger's verb, not only its glob.** Git already reports the status letter, and trigger prose is unusually consistent about verbs: - *added, deleted or moved* → fire on `A`, `D`, `R` only, not `M` - *any script added to, removed from or repurposed in …* → the same - *any new module, any change to a module boundary or a data shape* → `A` and `M` both A first cut needs no prose parsing at all: fire a document on modification only when its trigger does not restrict itself to existence changes, detected by looking for `added`/`deleted`/`moved`/`removed` without a `changed`/`change to`. Conservative direction matters — when the verb is unclear, fire, because a false prompt costs a glance and a missed one costs a document that is confidently wrong. Two alternatives, both worse. Narrowing the trust map's `Governs:` to subject form stops it firing at all, including when a document genuinely is added — which is the one case it exists for. Leaving it is the status quo: the tool's first real use produced two false fires out of three. Handing this to whoever holds `doc-triggers.py` rather than taking it, since it was rewritten an hour ago and two sessions in one file is the collision `commit-mine.sh` exists to prevent. Verify: touching a script fires TOOLS.md and architecture/README.md and not DOC_TRUST_MAP.md; adding or deleting a document under docs/ still fires DOC_TRUST_MAP.md.