Files
ersatztv/docs/decisions/records/testing
timothy 8081b9b9d9 fix(819): make the scope restatement closed-form, and state that as the criterion
Round 5's cold review found the class a fifth time, and it was a BLOCKER rather
than a narrowing. The restatement inlined both documented components but computed
its filename with `basename(path)` — the same helper `isInScopeSourcePath` calls
— so `basename` sat on both sides of the comparison and cancelled, exactly as the
filename predicate did in round 4 and the path table in round 3.

MEASURED on the previous head: teaching `basename` to return '' for paths four
segments deep removed 15 real tracked files, and a `pageSize: 100` planted in one
of them (`src/builder/rules/compile.ts`) went completely unseen — 36/36 green.
Reproduced here before fixing. The guard did not merely see less; it stopped
working and reported success. An `index.ts` variant hid 3 more.

What actually terminates this, and why the previous four attempts did not: each
one restated something and left something else SHARED, and "restate the scope"
gives no way to tell whether you are done. The criterion is now a checkable
property, written where the next author will edit:

  the restatement must be CLOSED FORM over the raw path — it may share NO helper,
  at ANY depth, with `isInScopeSourcePath`.

`basename` is why it is phrased that way: it reads as plumbing rather than as
policy, which is precisely why it got shared. The inlined `lastIndexOf` carries a
"do not tidy this into basename(path)" note for the same reason. Both mutations
above now redden `the shared scope predicate is EXACTLY its two documented
components`, including with the rogue site planted.

The previous head also ASSERTED that its residuals were complete, which this
blocker falsifies — a single-site edit to a shared helper narrowed scope
invisibly. Both the code comment and `docs/guard-inventory.md` now record the
three retracted mechanisms with what each one measured, and state the two
residuals as residuals rather than as closure.

Also from round 5:
- The anti-vacuity floor fired at 15 unstaged in-scope deletions with a bare
  assertion message, inside a test whose own failure text tells the reader to
  rename files or widen the glob. Wrong cause, and the #806 shape. It now carries
  its own message naming deletions first and a degenerate plugin result second.
- The Dockerfile's `docs_only` claim stated an accident as the rule.
  `ci-detect-docs-only.sh` classifies by PATH SHAPE (`docs/` or `*.md`), not by
  directory, so "any `web/**` path is not docs-only" is true only because no
  `web/*.md` is tracked. Restated, with `design-system/` named too.
- `ABSENT_FROM_DISK` emptied is an uncaught mutation. Recorded as a residual with
  its DIRECTION, which is what makes it tolerable: an empty set makes the guard
  red on an unstaged deletion, never blind.
- The decision record's `signals:` line carried neither the bounded exception's
  vocabulary nor #819, so the record's discovery surface did not carry the change
  its `rule:` makes.
- A worked example still named `src/api/generated/v1.ts`; the tracked file is
  `v1.d.ts`. Swept both tables this time rather than the one site.

Refs: #819
Decisions-Edit: yes
2026-08-29 05:12:23 +02:00
..