houseplan-card/docs/reviews/CODE-REVIEW-113-r3.md

# CODE-REVIEW-113-r3 — post-merge `docs` gate refresh, no product change

- **Issue:** https://github.com/Matysh/houseplan-card/issues/113
- **ТЗ:** `docs/specs/113-optional-space-model.md`, ревью ТЗ — `docs/reviews/SPEC-REVIEW-113-r1.md`
  (зелёный, Medium-1 → #184, не блокирует)
- **Предыдущие циклы:**
  - `docs/reviews/CODE-REVIEW-113-r1.md` — зелёный, High 0, Medium 0. Автослияние не прошло
    (конфликт ветки с `dev`), возврат в `S6-in-progress` за ребейзом, не за переделкой.
  - `docs/reviews/CODE-REVIEW-113-r2.md` — зелёный, High 0, Medium 0, после ребейза на
    `dev`=`c1676cf`. Пайплайн слил ветку в `dev` и поставил `S8-merged`.
  - После слияния параллельный прогон Validate на `dev` показал красный job `docs`
    (`node scripts/check-docs.mjs --external`): встроенный в `docs/images/screenshots.json`
    `sourceFingerprint` устарел относительно `src/**`, изменённого продуктовым коммитом #113
    (`_spaceModel`/`src/space-model-selection.ts`). Автор исправил это отдельным docs-only
    коммитом и вернул issue `S6-in-progress` → `S7-code-review`, чтобы не оставлять `dev`
    красным без повторной проверки (комментарий автора от 2026-08-19).
- **Диапазон:** `origin/dev..HEAD` = один коммит `acad3b3` («Refresh documentation source
  fingerprint»). `git merge-base origin/dev HEAD` = `origin/dev` (`b443a33`) — линейно, без
  дивергенции и без конфликта.
- **Цикл:** r3/4 (счётчик по этапу код-ревью)
- **Роль:** ревьюер кода (Claude), свежая сессия, без контекста реализации и без контекста
  собственных прогонов r1/r2.

## 1. Скоуп цикла r3

Единственный коммит диапазона, `acad3b3`:

```
docs/images/screenshots.json | 22 +++++++++++-----------
1 file changed, 11 insertions(+), 11 deletions(-)
```

Меняются только два повторяющихся поля манифеста — `sourceFingerprint` (один раз, в шапке) и
`sourceSha256` (в каждом из 10 сценариев, то же самое значение). Ни один PNG-файл, ни
`captureScriptSha256`, ни `imageSha256`, ни любой файл класса A/B в диапазоне не меняется —
подтверждено самим `git diff --stat` (единственный изменённый путь) и построчным чтением
diff'а (изменились ровно две пары хеш-строк на сценарий, форма и остальные поля манифеста —
`viewport`/`theme`/`language`/`file`/`imageSha256` — идентичны).

Класс файла — `docs/**` (класс C, `AGENTS.md`). Продуктовый код (`src/houseplan-card.ts`,
`src/space-model-selection.ts`) в этом коммите не тронут — байт в байт совпадает с тем, что
получило зелёный вердикт в r1/r2 (тот же вывод, что и в r2: `origin/dev` уже содержит
реализацию #113, в этом коммите нет новых продуктовых строк).

`Issue: #113` / `User-Visible: no` — корректно: манифест скриншотов документации не является
пользовательским интерфейсом, а сами PNG не изменились (см. §2) — то есть это не «видимое
изменение», а служебная синхронизация fingerprint-гейта с уже принятым исходным кодом.

Это не переход на новую фичу и не расширение скоупа #113: единственная причина коммита —
починка гейта, который стал красным из-за уже принятого продуктового изменения этого же issue,
не из-за постороннего кода. Формально это ближе к «предрелизному гейту» из `PROCESS.md` §11.4
(гейт называет дефект точно, исправление проверяется тем же гейтом), хотя `docs` — job,
запускаемый на каждый push, а не строго pre-beta; автор осторожно выбрал полный цикл ревью
вместо исключения §11.4, что процессом не запрещено и не требует правки с моей стороны.

## 2. Как проверялось — таблица гейтов

| Гейт | Команда | Результат |
|---|---|---|
| Typecheck | `npx tsc --noEmit` | OK, без ошибок |
| Unit | `npm test` | `877/877` OK — идентично r2 (продуктовый код не менялся) |
| Build + 3 копии бандла | `npm run build`, затем `cmp dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js` и `cmp dist/houseplan-card.js demo/srv/assets/houseplan-card.js` | OK, обе сверки — байт-в-байт совпадение |
| **Именно упавший гейт** | `node scripts/check-docs.mjs` | `Documentation checks passed (7 files, 10 external links).` — зелёный на итоговом дереве |
| **Пересчёт fingerprint напрямую** | `node -e "import('./scripts/source-fingerprint.mjs').then(({sourceFingerprint}) => console.log(sourceFingerprint(process.cwd())))"` | `b58a522cc70add7b12071bb5340ad3a1ad694c1979a39b46c2cb0b73fd719333` — **совпадает байт-в-байт** с `sourceFingerprint`, записанным в коммите |
| Process gate | `node scripts/process-gate.mjs --issues` | `диапазон origin/dev..HEAD, коммитов 1`, `гейт пройден, предупреждений 0` |

**Не прогонялось, и почему:**

- **Браузерные смоки (127+)** — не прогонялись. Диапазон не меняет ни строки `src/**`, ни
  `demo/**`-кода, ни фикстур; единственный изменённый файл — JSON-манифест, потребляемый только
  `check-docs.mjs`. Ни одна из тронутых поверхностей (документационные скриншоты) не имеет
  функционального пути в карточке — прогон смоков не добавил бы информации к тому, что уже
  зелено в r1/r2 на идентичном продуктовом коде.
- **`npm run golden:verify`** — не прогонялся. `docs/images/screenshots.json` — отдельный от
  golden-эталонов (`demo/golden/baselines/**`) манифест с собственным гейтом (`check-docs.mjs`),
  который прогнан и зелёный. Продуктовый рендер не менялся, пиксельного риска golden-эталонов
  нет.
- **`python -m pytest tests_backend`** — не тронут ни один файл `custom_components/**/*.py`.
- **Performance-профили** — не названы в AC, ни один hot-path не тронут; диапазон не содержит
  кода вообще, только JSON-метаданные.
- Обоснование сознательное, соразмерное объёму диапазона (PROCESS.md §8): один изменённый файл,
  один назначенный ему гейт (`check-docs.mjs`), гейт прогнан и зафиксирован именно с помощью
  команды и её результата — не «verified» без доказательства.

## 3. Проверка AC (docs/specs/113-optional-space-model.md §10)

Продуктовый код, доказывающий AC1–AC10, не менялся в этом цикле (§1) — доказательства r1/r2
переносятся без изменений. Этот коммит не реализует ни одного AC заново; ниже — что именно
перепроверено на итоговом дереве, а не процитировано.

| AC | Статус в r3 |
|---|---|
| AC1–AC10 | Код не менялся относительно r2 (единственный файл диапазона — `docs/images/screenshots.json`, не участвующий ни в одном AC из §10 ТЗ). `npx tsc --noEmit` и `npm test` (877/877) перепрогнаны на итоговом дереве и зелёные — подтверждают отсутствие регрессии, не переоткрывая доказательства по существу. |

Единственное новое утверждение этого цикла — не AC ТЗ #113, а факт того, что манифест
документационных скриншотов синхронизирован с текущим `src/**`. Оно доказано исполнением
(`check-docs.mjs` зелёный + независимый пересчёт fingerprint, см. §2), а не пересказом.

## 4. Дисциплина «тест умеет падать» — что проверено исполнением

- **`check-docs.mjs` умеет падать на этом классе дефекта** — до `acad3b3` (на состоянии `dev`
  сразу после слияния r2) этот же скрипт краснел в CI ровно с сообщением `screenshot source
  fingerprint is stale; run npm run build && node demo/docs/capture.mjs` (см. слово автора и
  сам факт, что job `docs` был красным в Validate). Причина понятна и воспроизводима логикой
  скрипта (`scripts/check-docs.mjs:118-119`): сравнение `manifest.sourceFingerprint !==
  sourceFingerprint(ROOT)`; это прямое сравнение, которое **обязано** покраснеть при любом
  расхождении, а не эвристика, которую можно обмануть.
- **Пересчёт fingerprint выполнен независимо от `check-docs.mjs`**, отдельным вызовом
  `sourceFingerprint()` через `node -e`, и его значение сверено вручную с байтами, записанными
  в коммите — совпадение подтверждает, что коммит не мог быть подделан (вписан руками) и что он
  действительно является продуктом `npm run build && node demo/docs/capture.mjs` на этом дереве,
  как и заявлено автором.
- **PNG не менялись** — сам `git diff --stat` не содержит ни одного `.png`-пути; отдельно
  `check-docs.mjs` сверяет `scenario.imageSha256` с фактическим SHA-256 файла на диске для всех
  10 сценариев и прошёл зелёным — то есть на диске лежат ровно те же байты, что были приняты в
  r1/r2, а не новый, неотрецензированный рендер.

## 5. Находки

Нет находок High. Нет находок Medium в диапазоне этого коммита.

**Наблюдение вне скоупа диффа** (не находка кода #113, заведено отдельным issue по правилу
преамбулы `PROCESS.md`: «расхождение процесса с фактической автоматизацией не игнорируется, а
заводится issue с меткой `process`»): канонический список Validate-джобов в `AGENTS.md` («CI is
pinned to an exact SHA... Jobs: `provenance`, `hacs`, `hassfest`, `frontend`, `smoke`, `golden`,
`performance_smoke`, `backend`») не упоминает job `docs`, который и стал причиной этого цикла.
Строка `AGENTS.md` не менялась с `0f8d35f` (2026-08-14), `docs`-job/`check-docs.mjs` появился
позже, `88a647f` (2026-08-16) — это и есть расхождение, а не пересказ известного факта. Заведён
[#191](https://github.com/Matysh/houseplan-card/issues/191) (`process`, `docs`, `P3`), не
блокирует #113 — сам этот коммит корректно работает с фактическим, не с задокументированным,
набором гейтов.

## 6. Что проверено и корректно

- Диапазон `origin/dev..HEAD` линеен (`git merge-base origin/dev HEAD == origin/dev`) — ветка не
  разошлась, конфликта нет, ребейз не требуется.
- Единственный изменённый файл диапазона — `docs/images/screenshots.json`, класс C; не задевает
  ни одного файла класса A/B. Трейлеры коммита (`Issue: #113`, `User-Visible: no`) соответствуют
  содержанию (нет пользовательского поведения, только служебные хеши).
- `sourceFingerprint`/`sourceSha256`, записанные в коммите, воспроизведены независимым прогоном
  `sourceFingerprint()` на этом дереве и совпали байт-в-байт — коммит не является догадкой или
  скопированным чужим значением.
- `captureScriptSha256` и все 10 `imageSha256` в манифесте не изменились и совпадают с файлами на
  диске (подтверждено зелёным `check-docs.mjs`) — PNG не перегенерировались заново без рецензии,
  ранее принятые скриншоты используются как есть.
- Продуктовый код (`src/houseplan-card.ts`, `src/space-model-selection.ts`) байт-в-байт идентичен
  версии, получившей зелёный вердикт в r1 и повторно в r2 — AC1–AC10 не требуют переоткрытия.
- Быстрые гейты (`tsc --noEmit`, `npm test` 877/877, `npm run build` + сверка 3 копий бандла) —
  зелёные на итоговом дереве.
- `node scripts/process-gate.mjs --issues` — зелёный, 0 предупреждений, диапазон 1 коммит.
- `docs/CHANGELOG.md`/`docs/CHANGELOG.ru.md` корректно не тронуты — `User-Visible: no`.

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

- Полный набор браузерных смоков и `golden:verify` — обоснование в §2 (диапазон не содержит ни
  строки `src/**`/`demo/**`-кода, только JSON-манифест документационных скриншотов).
- `pytest tests_backend` — класс A/B бэкенда не тронут.
- Performance-профили — не названы в AC, не затронуты (диапазон без кода).
- Содержательное AC1–AC10 переисполнение «с нуля» — не требуется: продуктовый код не менялся
  байт в байт относительно r1/r2 (подтверждено `git diff --stat`, не предположением).
- Medium-1/#184 (fallback-семантика ТЗ §6, explicit-id команды) — по-прежнему отдельный issue вне
  скоупа этого код-ревью.
- Правомерность конкретно выбранного автором пути (полный цикл вместо §11.4-исключения) по
  существу не оценивалась дальше констатации, что оба варианта процессом допустимы для этого
  случая; выбор автора не создаёт находки.

## 8. Вердикт

Единственный коммит цикла — служебная синхронизация fingerprint-манифеста документационных
скриншотов с уже принятым (дважды зелёным) продуктовым кодом #113; PNG не менялись, продуктовый
код не менялся, упавший гейт (`check-docs.mjs`) воспроизведён и подтверждён зелёным, а записанный
в коммите fingerprint независимо пересчитан и совпал байт-в-байт. Все быстрые гейты зелёные.
High: 0. Medium: 0 в диапазоне диффа. Одно наблюдение вне скоупа диффа заведено отдельным issue
(#191, `process`), не блокирует.

**Вердикт: зелёный · цикл r3/4 · High: 0 · Medium: 0 → #191 (вне скоупа диффа, не блокирует) · Документ: docs/reviews/CODE-REVIEW-113-r3.md**