diff --git a/docs/decisions/records/testing/guard-pins-the-artifact-not-a-shape.md b/docs/decisions/records/testing/guard-pins-the-artifact-not-a-shape.md index ec9b79df1..a0152f1b8 100644 --- a/docs/decisions/records/testing/guard-pins-the-artifact-not-a-shape.md +++ b/docs/decisions/records/testing/guard-pins-the-artifact-not-a-shape.md @@ -17,8 +17,10 @@ someone stops it. Measured 2026-08-30 across two unrelated subjects: a guard par decide whether a command runs the SPA suite was wrong **nine** ways from one mechanism (#887), its replacement — a partial match of `web/vite.config.ts` — **seven** further ways, and a lexical rule over a hook preamble **five** (#891). Every fix was locally correct and none of the three sequences -converged. All three ended in the same move, and a pin has never been defeated by a respelling -because it does not have to RECOGNISE one in order to reject it. +converged. All three ended in the same move: a pin cannot be defeated by a respelling of what it +COMPARES, since it need not RECOGNISE one in order to reject it. What stays exposed is whatever it +does not compare — nothing for a whole-file pin, and exactly the reach of the SELECTOR for a pin +scoped by one, which is why `mechanics:` states the hook pin's. **Why the pin is the DEFAULT and not the remedy — the first thing #901 left open.** The rejected alternative is the tempting one: write the shape-matcher, and pin only once it has been defeated. It @@ -63,8 +65,11 @@ their own records — `ci.image-build-delegates-the-spa-suite` and `testing.guard-derives-population-from-source` answers the case where the authoritative source is MISSING (create one, never approximate it with a predicate over text) and this one the case where the artifact IS present and authoritative and what is approximated is its GRAMMAR. -`docs/defect-shapes-773.md` §4 argues the general form; what was missing is a rule resolvable BY -TOPIC, since `docs/guard-inventory.md` carries its precedent per incident, findable only inside one. +`docs/defect-shapes-773.md` does NOT carry this rule: its §3.6 partition lists the nearest class, +string-predicate churn, as `no detector proposed`, and §3.7 argues that class away as a cross-cutting +property. Only §4's closing meta-finding supports the FORM — a class-level rule beats one record per +instance — so the rule itself is new here, and resolvable BY TOPIC, where `docs/guard-inventory.md` +carries its precedent per incident, findable only inside one. **What this does not cover.** Predicates over structured input a real parser produces — an AST, the git index, parsed workflow YAML consumed as data — are not approximations and keep their shape