houseplan-card/docs/reviews/CODE-REVIEW-422-r1.md

# CODE-REVIEW-422-r1

- Issue: https://github.com/Matysh/houseplan-card/issues/422
- Ветка: `issue/422-capture-and-anchor-gates`
- SHA материала (сверен `git rev-parse HEAD` перед выводом итогов): `653b9a763294cf3c88537bf129e0d8f8f4e6e9c4`
- Заход: r1 (первый код-ревью раунда, разбор полный — дельта по §2.10 не применяется)
- Класс изменений: только B (`.github/**`, `demo/**`, `scripts/**`, `test/**`) — продуктового кода (`src/**`, `custom_components/**/*.py`) нет
- ТЗ: `docs/specs/422-capture-and-anchor-gates.md`, ревью ТЗ — зелёное, `docs/reviews/SPEC-REVIEW-422-r1.md`

## Скоуп

Две независимые правки гейтов, обе из аудита v1.70.0:

1. Гейт стабильности съёмки документации мерил три снимка **внутри одного
   процесса** и был бы зелёным на дефекте #410 (обрезка кадра плавала
   **между** прогонами). Добавлен кросс-прогонный гейт
   `scripts/capture-determinism.mjs` — снимает набор дважды в разных
   процессах и сравнивает хеши; старая проверка `--stability=3` сохранена.
   Целочисленная обрезка (`demo/docs/clip.mjs`) вынесена в чистую функцию и
   покрыта юнитом.
2. Живость якоря материала ревью-документа (`scripts/review-doc-guard.mjs`)
   проверялась `git cat-file -e` — наличием объекта в локальной базе, а не
   достижимостью. Заменено на `anchorLiveness()`: достижимость от
   `refs/remotes/origin` и тегов, той же командой, что печатается читателю.

Ветка ребейзнута на `dev` после мержа #424 (починка компоситора, была
блокирующей зависимостью — конвейер съёмки не мог быть введён красным по
известной причине). После ребейза дерево пересъёмки дало 10/10 совпадений,
изменился только отпечаток скрипта в манифесте.

## Как проверялось

| Гейт | Команда | Результат |
|---|---|---|
| Typecheck | `npx tsc --noEmit` | чисто, без вывода |
| Unit-тесты | `npm test` | **1765 pass / 0 fail / 1 skipped** (1766 всего) — совпадает с заявленным автором числом |
| Build + сверка бандлов | `npm run build && npm run bundle:sync`, `cmp` трёх копий | `dist` = `custom_components/houseplan/frontend` = `demo/srv/assets`, побайтово |
| `check-docs.mjs` | `node scripts/check-docs.mjs` | **КРАСНЫЙ** — см. находку H1. На `origin/dev` тот же скрипт зелёный (проверено отдельным `git worktree`) |
| Новые юниты | `node --test test/capture-clip.test.mjs`, `node --test test/review-doc-guard.test.mjs` | 5/5 и 24/24 pass |
| Оба мутанта (умеют падать) | `node scripts/mutation-gate.mjs --id=capture-drifts-between-runs`, `--id=anchor-liveness-ignores-reachability` | оба «покраснел, как обязан», поймано 1 из 1 |
| Реестр мутантов согласован с кодом | `node scripts/mutation-gate.mjs --check` | оба новых якоря (`capture-drifts-between-runs`, `anchor-liveness-ignores-reachability`) применились чисто, `FAIL` нет |
| Новый кросс-прогонный гейт целиком, вживую | `node scripts/capture-determinism.mjs` (реальный Chromium, реальная съёмка дважды) | **зелёный**: «съёмка воспроизводима: 10 кадров совпали между прогонами» — рабочее дерево после этого возвращено `git checkout -- docs/images/` |
| CI на этом SHA | — | нет зелёного прогона; реальный workflow-run [33672132518](https://github.com/Matysh/houseplan-card/actions/runs/33672132518) на этом же SHA — `failure`, job «Предполётные проверки» падает на шаге `check-docs.mjs --external` с той же ошибкой, что я воспроизвёл локально |

**Не прогонялось и почему:**
- Браузерные `demo/smoke_*.mjs` — diff не трогает `src/**`;
  `node scripts/smoke-select.mjs --base origin/dev --head HEAD` подтверждает:
  «Исполняемого frontend-диффа нет… Browser-smoke этим диффом не выбираются».
- `npm run golden:verify` — визуальный результат карточки не меняется (diff не
  трогает `src/**`, скриншоты документации — не golden-эталоны продукта).
- `python -m pytest tests_backend -q` — Python не тронут.
- `node scripts/model-invariants.mjs` — геометрия/`layout`/толщина стен/
  `marker.space`/`open_spans` не затронуты.
- Полный `docs-screenshots.yml` в CI (`workflow_dispatch`) — недоступен из
  ревью-сессии; вместо этого прогнан эквивалент локально
  (`node scripts/capture-determinism.mjs` вживую) и сверен с реальным прогоном
  автора на CI (см. таблицу выше).

## Находки

### High H1 — коммит `653b9a76` кладёт в манифест неверный `captureScriptSha256`, гейт `docs` красный на этом SHA

`docs/images/screenshots.json` после коммита «docs: refresh the capture
fingerprint after the clip extraction» хранит
`captureScriptSha256: 12eb99bc095f…`. Реальный хеш файла `demo/docs/capture.mjs`
на этом дереве — `cadb8e1bcab9…` (`git show HEAD:demo/docs/capture.mjs | sha256sum`).
Значение `12eb99bc…` — это хеш `capture.mjs` **до** выноса `wholePixelClip` в
`clip.mjs` (совпадает с версией файла на коммитах `70805c9c`/`8ed8ecc3`,
предшествующих рефакторингу в `d59ceee9`). То есть коммит, который по
сообщению должен был «обновить отпечаток после выноса обрезки», записал
отпечаток **до** него — похоже на пересъёмку со старой копии скрипта до
финального ребейза, зафиксированную посмертно.

**Воспроизведено дважды, независимо:**
```
node scripts/check-docs.mjs
→ ERROR screenshot capture script changed; run npm run build && node demo/docs/capture.mjs
```
и тем же образом в живом CI на этом самом SHA — прогон
[33672132518](https://github.com/Matysh/houseplan-card/actions/runs/33672132518),
job «Предполётные проверки: документация, провенанс, процесс», шаг
«Документация: гайды, ченджлоги, скриншот-индекс»:
```
ERROR screenshot capture script changed; run npm run build && node demo/docs/capture.mjs
##[error]Process completed with exit code 1.
```
Контрольная проверка: тот же `check-docs.mjs` на `origin/dev` (отдельный
`git worktree`) — зелёный, «Documentation checks passed». Дефект вносится
именно этим диффом, не окружением.

Сами PNG и их `imageSha256` в манифесте совпадают с байтами на диске — порча
только в одном поле (`captureScriptSha256`). Это `docs` — один из
обязательных job'ов `validate.yml` (AGENTS.md, список #191); красный он не
может уйти в `S8-merged` по прецеденту #230/#234.

**Чем чинится:** пересъёмка на финальном дереве, `npm run build && node
demo/docs/capture.mjs`, коммит обновлённого `docs/images/screenshots.json`
(и, если изменятся байты кадров — самих PNG).

### Medium M1 (в скоупе) — AC8 не доказан: замера времени конвейера нет ни в issue, ни в коммитах

ТЗ явно требует: «Конвейер не стал заметно дольше… Доказательство: замер до и
после, разница названа в issue числом». Ни в одном комментарии issue #422, ни
в сообщениях коммитов такого числа нет — только общее «оба гейта готовы» и
последующий разбор дефекта #424. Единственная цифра, которая нашлась вживую —
общая длительность одного CI-job'а без разбивки на «до» и «после»
(`Съёмка и сверка скриншот-индекса`, 76 c, прогон
[33657466605](https://github.com/Matysh/houseplan-card/actions/runs/33657466605)) —
это не сравнение, а единственная точка. Риск в самом ТЗ («второй прогон
удваивает время шага») признан явно и там же названо смягчение («звести к
нетривиальным сценариям, если удвоение дорого») — но без цифры невозможно
понять, нужно ли смягчение вообще.

### Medium M2 (в скоупе) — комитченный мутант AC1/AC2 не проверяет сам новый гейт; `frameHashes`/`driftBetweenRuns` без юнитов

AC1 требует доказательства, что кросс-прогонный гейт красный на мутации,
«моделирующей #410» (сдвиг обрезки, постоянный в процессе, разный между
прогонами); AC2 — что **та же** мутация оставляет старый `--stability=3`
зелёным, и оба факта доказываются «мутантом в `scripts/mutation-gate.mjs`,
прогнанным штатным раннером».

Комитченный мутант `capture-drifts-between-runs`
(`scripts/mutation-gate.mjs:960-971`) патчит `demo/docs/clip.mjs`
(`Math.floor` → `Math.round`) и охраняется `test/capture-clip.test.mjs` —
это прямое попадание в AC4 (целочисленная обрезка), но не в AC1/AC2: он не
трогает и не запускает ни `scripts/capture-determinism.mjs`, ни
`--stability=3`. У самого нового гейта (`frameHashes`, `driftBetweenRuns` в
`scripts/capture-determinism.mjs`) нет ни одного прямого юнита и ни одного
мутанта — единственная проверка их логики это полный браузерный прогон,
которого в цикле реализации не бывает (§8).

Живое AC1-доказательство есть — реальный дефект #424 (не синтетическая
мутация) на этой же ветке дал кросс-прогонный гейт красным на CI, теми же
хешами что и в песочнице автора (прогон `33657466605`). Но AC2 (что старый
`--stability=3` в этот момент остаётся зелёным) не проверено даже так: в
том прогоне шаг `--stability=3` стоял **после** упавшего кросс-прогонного и
был помечен `skipped`, а не `success`. Разрыв «`--stability` стабильно зелёный
на этом классе дефектов» держится только на историческом знании из #410, не
на прогоне в этой задаче.

Предложение (не обязывающее, автор волен решить иначе): либо добавить прямой
юнит на `frameHashes`/`driftBetweenRuns` (это чистые функции — дёшево), либо
переименовать/дополнить формулировку AC1/AC2 «доказательство», раз реальное
доказательство идёт через живой инцидент #424, а не через мутант.

### Low L1 (снято с записью) — комментарий в `docs-screenshots.yml` про «третий прогон»

Комментарий у шага `--stability=3` («снимать набор третий раз ради порядка
строк в логе незачем») предполагает, что читатель уже понимает, что перед ним
второй **набор** кадров, а не третий прогон капчура в буквальном смысле счёта
запусков (`capture-determinism.mjs` = 2 прогона, затем `--stability` = ещё 3
внутрипроцессных снимка на сценарий). Формально AC9 («комментарий
соответствует фактическому порядку шагов») выполнен — порядок шагов описан
верно, спор только о том, что «третий» считает по-разному в двух местах
одного комментария. Не блокирует, автор может уточнить при следующей правке
файла или оставить как есть.

## Проверено и корректно

- **AC3** (проверка «не плавает внутри одного состояния» сохранена) —
  проверено чтением `demo/docs/capture.mjs`: код ветки `STABILITY_SHOTS`
  (сравнение через `comparePairs`, `continue` до записи файла) не тронут
  диффом, только вынесен комментарий.
- **AC4** (целочисленная обрезка) — доказано автотестом
  (`test/capture-clip.test.mjs`, 5/5), тест умеет падать: мутант
  `capture-drifts-between-runs` красит именно его.
- **AC5/AC6/AC7** (достижимость якоря, а не наличие; старое поведение #414 не
  сломано; дерево/блоб/тип через `cat-file -t`) — доказано автотестом
  (`test/review-doc-guard.test.mjs`, новые 8 тестов из 24, все зелёные), тест
  умеет падать (мутант `anchor-liveness-ignores-reachability`). Дополнительно
  прочитан код `anchorLiveness()` и вручную проверены обе git-команды
  (`--find-object` без пути, `--format=%T`) на текущем репозитории — обе ведут
  себя так, как описано в коде.
- **Область поиска — `refs/remotes/origin`+теги, не `--all`** — отдельный тест
  подтверждает («областью поиска служат origin и теги, а не --all»); расхождение
  с командой, которую видит человек в `materialAnchorBlock` (там всё ещё
  `--all`), уже разобрано и принято ревьюером ТЗ в r1 (`--all` — надмножество,
  ложноотрицательных не даёт) — не пересматриваю, дельта диффа этого места не
  касается.
- **AC1 (позитив)** — доказано исполнением реального браузерного гейта дважды:
  на исправленном дереве (10/10 кадров совпали) и, по историческим данным CI
  этой же ветки, на неисправленном (до #424) — гейт был красным с тем же
  «отпечатком» дефекта, что и исходный #410 (пиксели на сглаженных границах).
- **AC9** — проверено чтением `.github/workflows/docs-screenshots.yml`:
  фактический порядок — `capture-determinism.mjs` → `--stability=3` → «Хеши
  кадров» → «Вердикт»; комментарий над каждым шагом соответствует (кроме
  формулировки L1).
- Трейлеры всех четырёх коммитов (`Issue: #422`, `User-Visible: no`) на
  месте; changelog не тронут — верно, видимого поведения продукта нет.
- Класс файлов — только B, инфраструктурный маршрут с файлом ТЗ уже принят
  ревью ТЗ r1 со ссылкой на прецеденты (#398, #399, #404) — не пересматриваю.
- Три копии бандла (`dist`, `custom_components/houseplan/frontend`,
  `demo/srv/assets`) синхронны побайтово.

## Чего не проверял

- Полный `docs-screenshots.yml` через `workflow_dispatch` на этом SHA — нет
  прав на диспетчеризацию из ревью-сессии; опираюсь на прогон автора
  (`33657466605`, до фикса #424) и собственный локальный прогон
  эквивалентного шага.
- `python -m pytest tests_backend` — diff не касается `custom_components/**`,
  пропущено по правилу «нужно только если тронут бэкенд».
- Полный `npm run golden:verify` — не запускал: diff не меняет визуальный
  результат карточки (только инструмент съёмки *документационных* скриншотов),
  а golden-эталоны продукта отдельны от `docs/images/screenshots.json`.
- Производительность съёмки как таковая — числа нет ни у автора, ни у меня;
  см. M1.

## Материал раунда

<!-- material-anchors: заполняется шагом публикации -->

---

<!-- material-anchors: сгенерировано конвейером (#414) -->

## Материал раунда

- Ветка: `issue/422-capture-and-anchor-gates`, коммит `653b9a763294` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
- Дерево материала: `f0b4c84fbe45cfa5d0e7be19af9387b0d3a79e62`
  ```
  git log --all --format='%H %T' | grep f0b4c84fbe45
  ```
- ТЗ `docs/specs/422-capture-and-anchor-gates.md`, блоб `797df838584f268fb2f1e99a41b5dad15088d698`
  ```
  git log --all --find-object=797df838584f268fb2f1e99a41b5dad15088d698 -- docs/specs/422-capture-and-anchor-gates.md
  ```