houseplan-card/docs/specs/422-capture-and-anchor-gates.md

ТЗ #422 — Гейт съёмки меряет между прогонами, гейт якорей — достижимость

• Issue: https://github.com/Matysh/houseplan-card/issues/422
• Приоритет: P3, infra; полный трек — две несвязанные поверхности (съёмка документации и гейт ревью-документа), критерий «одна поверхность» для small не выполняется. Класс файлов — только B (.github/**, demo/**, scripts/**, test/**), продуктового кода задача не касается; прецеденты инфраструктурных задач с файлом ТЗ — #398, #399, #404
• Ревизия: 1 (2026-09-02)

Сценарий

Две проверки, каждая заведена после конкретного инцидента, и каждая на своём же инциденте промолчала бы.

Первая: после #410 в конвейер добавлен шаг «Кадр не плавает внутри одного состояния». Он делает три снимка подряд в одном процессе. Дефект #410 был не такой: обрезка кадра плавала между прогонами, и три снимка внутри одного процесса совпали бы всегда.

Вторая: после #413 гейт отказывает ревью-документу, объявившему материал на несуществующем коммите. После #414 отказ смягчается, если в машинном блоке есть живые якоря — дерево и блоб, которые ребейз не меняет. Живость якоря проверяется git cat-file -e, то есть наличием объекта в локальной базе. Объект, созданный на машине автора и никуда не привязанный, этой проверке удовлетворяет.

Что человек увидит до и после

Видимого поведения продукта задача не меняет — меняется то, что видит инженер.

До: (1) съёмка может стать недетерминированной между прогонами, а гейт останется зелёным; (2) отказ «материал ревью недостижим» смягчается объектом, существующим только на машине, где ошибку и совершили. После: недетерминированность съёмки между прогонами роняет конвейер; якорь считается живым только если он достижим из refs/remotes/origin или тегов — то есть если команда, которую документ печатает читателю, действительно находит материал.

Проблема и контракты по пунктам

(1) Гейт стабильности съёмки

demo/docs/capture.mjs:290-312 в режиме --stability=N делает N снимков в одном процессе без правки состояния и сравнивает их попиксельно. .github/workflows/docs-screenshots.yml:99-100 вызывает его с --stability=3.

Воспроизведено исполнением. В capture.mjs внесена мутация, точно моделирующая #410: смещение обрезки на 1 px, постоянное внутри процесса и разное между прогонами.

node demo/docs/capture.mjs --stability=3   → «кадр не плавает ни в одном сценарии»
прогон A: 6ba168494519a10dd659
прогон Б: 4142a6ab9558cb481ecc              ← 08-room-card.png разошёлся

Шаг «Хеши кадров» (:101-103) печатает sha256sum в лог, но ничего не сравнивает: это материал для человека, а не гейт.

Контракт: воспроизводимость съёмки проверяется там, где она нарушалась — между независимыми прогонами. Два полных запуска capture.mjs в разных процессах на одном и том же коммите обязаны дать побайтово совпадающие кадры; расхождение роняет конвейер и называет разошедшиеся файлы.

Проверка внутри одного состояния при этом остаётся: она отвечает на другой вопрос — «плавает ли кадр от времени внутри страницы» — и стоит дёшево. Одна не заменяет другую; вместе они покрывают обе оси, по которым съёмка может поехать.

Отдельно — корневая правка #410: целочисленная обрезка (capture.mjs:284-289) не покрыта ничем. Выражение чистое (вход — прямоугольник с дробями, выход — целый), значит проверяется юнитом без браузера.

(2) Живость якорей материала

scripts/review-doc-guard.mjs:305-307:

const resolveObjects = (object) => spawnSync('git', ['cat-file', '-e', object], …).status === 0;

git cat-file -e истинен для любого объекта в локальной базе, включая недостижимый и обречённый на gc. Для SHA раунда достижимость намеренно считается от refs/remotes/origin и тегов (:298-304), для якорей — нет.

Воспроизведено исполнением:

объект 8ce20a2a0a8b… (git hash-object -w, ни к чему не привязан)
  git cat-file -e:              признаёт живым
  достижим из origin/тегов:     НЕТ
  git log --all --find-object:  не находит
danglingMaterialRefusal(недостижимый SHA + этот якорь) → WARNING, отказ смягчён

Контракт: якорь считается живым тогда и только тогда, когда его находит команда, которую документ печатает читателю (materialAnchorBlock), выполненная в области refs/remotes/origin и тегов. Для дерева это перебор %T по тем же ссылкам, для блоба — --find-object по ним же; тип объекта различается git cat-file -t. Область --all не годится: она включает локальные ветки, а их у ревьюера нет.

Граница: гейт по-прежнему судит момент публикации, а не будущее ветки (§«Чего этот рубеж НЕ умеет» в самом файле). Задача не меняет этой границы — она только приводит проверку якоря к той же строгости, что и проверка SHA.

Скоуп / не-скоуп

В скоупе: кросс-прогонная проверка съёмки (capture.mjs, шаг конвейера), юнит на целочисленную обрезку, проверка достижимости якорей в review-doc-guard.mjs, тесты и мутанты, комментарий о порядке шагов в docs-screenshots.yml.

Не в скоупе: состав сценариев съёмки и их фикстуры; порог кадров-свидетелей (#408/#409 — закрыты); формат машинного блока якорей (#414); правило «SHA раунда обязан быть достижим» (#413) — оно не меняется; три проверки, не умеющие падать (#421) — соседний класс, своя задача.

UX, модель данных, i18n

Не применимо: продуктового кода задача не касается, пользовательских строк не добавляет.

Критерии приёмки

• AC1. Съёмка, недетерминированная между прогонами, роняет конвейер: два независимых запуска capture.mjs на одном коммите сравниваются побайтово, расхождение печатает имена файлов и завершается ненулевым кодом. Доказательство: прогон на коде с мутацией, моделирующей #410 (смещение обрезки, постоянное в процессе и разное между прогонами), — гейт красный.
• AC2. Отрицательный прогон обязателен: та же мутация при старом гейте (--stability=3) остаётся зелёной. Доказательство: мутант в scripts/mutation-gate.mjs, прогнанный штатным раннером.
• AC3. Проверка «кадр не плавает внутри одного состояния» сохранена и по-прежнему краснеет на нестабильности внутри процесса. Доказательство: существующий режим --stability не тронут в части сравнения.
• AC4. Целочисленная обрезка покрыта юнитом: дробный прямоугольник расширяется до целого, цель не теряет ни полпикселя по краю. Доказательство: тест в test/, краснеющий при замене Math.ceil/Math.floor на округление к ближайшему.
• AC5. Якорь, существующий только локально, не смягчает отказ: danglingMaterialRefusal с недостижимым SHA и таким якорем возвращает отказ, а не warning. Доказательство: тест с подставным resolveObjects, отражающим достижимость, а не наличие.
• AC6. Достижимый якорь по-прежнему смягчает отказ до warning — поведение #414 не сломано. Доказательство: тот же тест, вторая ветка; существующие тесты review-doc-guard зелёные без правок их утверждений.
• AC7. Дерево и блоб проверяются каждый своей командой, тип определяется git cat-file -t; неизвестный тип объекта живым не считается. Доказательство: юнит на трёх входах.
• AC8. Конвейер не стал заметно дольше: второй прогон съёмки — это ещё один capture.mjs на том же браузере. Доказательство: замер до и после, разница названа в issue числом.
• AC9. Комментарий о порядке шагов в docs-screenshots.yml соответствует фактическому порядку. Доказательство: чтение файла — комментарий и порядок шагов сверяются глазами в одном экране.

План автотестов

Юниты (test/):

1. capture-clip.test.mjs — целочисленная обрезка на дробных входах (AC4).
2. review-doc-guard.test.mjs (дополнение) — якорь недостижим → отказ; достижим → warning; неизвестный тип → не живой (AC5, AC6, AC7).

Гейт конвейера: шаг, запускающий съёмку дважды и сравнивающий хеши всех кадров (AC1). Локально та же проверка доступна командой, названной в docs/TESTING.md.

Мутанты (scripts/mutation-gate.mjs):

• capture-drifts-between-runs: смещение обрезки, постоянное в процессе и разное между прогонами → новый кросс-прогонный гейт красный, старый --stability зелёный (AC1, AC2);
• anchor-liveness-ignores-reachability: вернуть git cat-file -e → тест AC5 красный.

Риски

• Второй прогон съёмки удваивает время шага. Съёмка десяти сценариев — не самая долгая часть конвейера, но и не бесплатная. Смягчение: AC8 требует замера, а не предположения; если удвоение окажется дорогим, второй прогон можно свести к тем сценариям, где обрезка нетривиальна (room-card и соседи) — но тогда это должно быть записано, а не подразумеваться.
• Кросс-прогонное сравнение поймает не только нашу недетерминированность. Обновление Chromium в кэше между двумя прогонами одного job'а невозможно, но системный шрифтовой кэш и подобное — теоретически да. Смягчение: оба прогона идут в одном job'е, на одном браузере и одном коммите; если гейт начнёт краснеть по внешней причине, это само по себе важная новость.
• Проверка достижимости якорей дороже cat-file -e. Перебор %T по ссылкам origin — это git log по всей истории. Смягчение: вызывается только в редкой ветке (SHA раунда уже недостижим), то есть на отказе, а не на каждом прогоне.
• Ужесточение якорей сделает часть прошлых отчётов формально негодными. Это правда и это цель: смягчение, которое не воспроизводится, хуже отсутствия смягчения. Смягчение риска: сообщение отказа обязано называть команду, которой ревьюер может проверить якорь сам.

Откат

Обе правки локальны и независимы: шаг конвейера снимается отдельно от проверки достижимости. Данные пользователя и продуктовый код не затрагиваются.

Release-артефакты

• docs/CHANGELOG.md / docs/CHANGELOG.ru.md: не требуется (User-Visible: no).
• docs/TESTING.md: команда локального кросс-прогонного сравнения съёмки.
• Скриншоты не меняются: задача проверяет съёмку, а не кадры.