docs: review document for #205

Issue: #205
User-Visible: no

docs/reviews/CODE-REVIEW-205-r2.md

@@ -0,0 +1,266 @@
+# CODE-REVIEW-205-r2 — продолжение следа пылесоса после короткой остановки
+
+- Issue: [#205](https://github.com/Matysh/houseplan-card/issues/205)
+- Этап: `code` (PROCESS.md §2.7)
+- Диапазон: `origin/dev...HEAD`, `origin/dev` = `5dc9016` («docs: review document
+  for #204»), `HEAD` = `e158f8f` (ветка `issue/205-vacuum-trail-grace`, detached
+  `HEAD`); merge-base — `5dc9016`
+- ТЗ: [`docs/specs/205-vacuum-trail-resume-grace.md`](../specs/205-vacuum-trail-resume-grace.md),
+  ревью ТЗ зелёное — [`SPEC-REVIEW-205-r1.md`](SPEC-REVIEW-205-r1.md)
+- Предыдущий цикл: [`CODE-REVIEW-205-r1.md`](CODE-REVIEW-205-r1.md) —
+  **зелёный**, High: 0, Medium: 0; вернулся не по замечаниям, а из-за конфликта
+  ребейза на ушедший вперёд `dev` (issue-комментарии от 2026-08-19 17:53–17:58)
+- Цикл: **r2/4**
+- Ревьюер: Claude, свежая сессия, без переписки с автором реализации
+- Вердикт: **зелёный**
+
+## Скоуп ревью
+
+После r1 ветка была отправлена в `S6-in-progress` не по существу правки, а
+из-за конфликта при рейбейзе на `dev`, который тем временем принял #204
+(«fix: show honest new-space display defaults», трогает `src/houseplan-card.ts`
+и `src/space-dialog.ts`). Автор перебазировал `issue/205-vacuum-trail-grace` на
+`origin/dev` (`5dc9016`) и запушил force-with-lease; новый `HEAD` — `e158f8f`.
+
+Пять коммитов диапазона:
+
+1. `5c09591` «docs: specify vacuum trail resume grace» — ТЗ (класс C), уже
+   зелёное ревью (`SPEC-REVIEW-205-r1.md`), содержимое не пересматриваю заново.
+2. `d31ad3c` «docs: review document for #205» — сам документ ревью ТЗ (класс C).
+3. `56e0114` «fix: resume vacuum trails after short stops» — единственный
+   продуктовый коммит (класс A/B), `Issue: #205`, `User-Visible: yes`, те же
+   12 файлов, что были в `11b0283` на r1: `custom_components/houseplan/trails.py`,
+   `demo/smoke_vacuum.mjs`, `scripts/mutation-gate.mjs`,
+   `scripts/trail-resume-test-guard.mjs`, `tests_backend/test_trails.py`,
+   `tests_backend/test_trail_recorder.py`, `docs/CHANGELOG.md`,
+   `docs/CHANGELOG.ru.md`, `docs/STATUS.md`, `docs/TESTING.md`,
+   `docs/USER-GUIDE.ru.md`, `docs/VACUUM.md`.
+4. `edf532e` «docs: review document for #205» — документ ревью кода r1 (класс C).
+5. `e158f8f` «docs: refresh rebased screenshot provenance» — новый для этого
+   цикла коммит (класс C), `Issue: #205`, `User-Visible: no`: только
+   `docs/images/06-device-editor.png` и `docs/images/screenshots.json`
+   (обновлённый `sourceFingerprint`/`sourceSha256`/один `imageSha256`).
+
+Прочитано целиком заново: `docs/SCOPE.md`, `AGENTS.md`, `PROCESS.md`, тело
+issue #205 и все 8 комментариев (включая два новых — «слот S7 освободился»,
+«код-ревью зелёное, но конфликт с dev» и «конфликт разрешён» с перечнем
+локальных прогонов автора на Windows после ребейза), оба существующих
+документа ревью (`SPEC-REVIEW-205-r1.md`, `CODE-REVIEW-205-r1.md`),
+`docs/specs/205-vacuum-trail-resume-grace.md`, `docs/VACUUM.md` целиком, весь
+diff `custom_components/houseplan/trails.py` (построчно), оба изменённых
+тестовых файла целиком, оба скрипта mutation-gate/guard, все изменения в
+changelog/`STATUS.md`/`TESTING.md`/`USER-GUIDE.ru.md`/`VACUUM.md`,
+`scripts/source-fingerprint.mjs`.
+
+## Что именно проверяет этот цикл
+
+AGENTS.md прямо требует не считать повторное ревью формальностью: «после
+ребейза на новый `dev` это другой код». Поэтому проверка строилась в два слоя:
+
+1. **Тождество продуктового содержимого.** Сравнил diff `origin/dev...HEAD` по
+   каждому из 12 файлов продуктового коммита с построчным разбором, записанным
+   в `CODE-REVIEW-205-r1.md` — совпадает буквально (тот же `can_resume_trail_run`,
+   те же условия `is None`/`is not None` в `on_point`/`end_run`, те же тестовые
+   функции и та же mutation-запись). Прежний `HEAD` `11b0283` в этом чекауте
+   недоступен как объект (ребейз переписал историю), поэтому тождество
+   устанавливалось не через `git diff <old>..<new>`, а через построчную сверку
+   текущего diff с тем, что r1 уже зафиксировал как проверенное и исполненное —
+   это надёжнее, чем доверие тексту хендоффа, потому что сверяется с
+   собственноручно перепроверенным прошлым циклом, а не с заявлением автора.
+2. **Легитимность нового коммита ребейза.** `e158f8f` не трогает
+   `custom_components/**` и не расширяет скоуп #205 — он синхронизирует
+   provenance скриншотов с деревом `src/**`, изменившимся из-за #204.
+
+### Почему `e158f8f` — корректное разрешение конфликта, а не посторонняя правка
+
+`docs/images/screenshots.json.sourceFingerprint` — это `sha256` над
+содержимым `src/**` плюс `package.json`/`package-lock.json`/
+`rollup.config.mjs`/`tsconfig.json`/`scripts/source-fingerprint.mjs`
+(`scripts/source-fingerprint.mjs`, читал целиком). До ребейза `205` не трогал
+`src/**`, но принявший его `dev` уже содержал #204, который правит
+`src/houseplan-card.ts` и `src/space-dialog.ts` — старое значение
+`sourceFingerprint`, зафиксированное на branch #205 до ребейза, стало не
+соответствовать актуальному дереву. Пересчитал сам:
+
+```
+node -e "import('./scripts/source-fingerprint.mjs').then(m => console.log(m.sourceFingerprint()))"
+→ b86fe263f5e381c483534a0f7372a44478f5ef10b14416ee5c7a87e6f26a103d
+```
+
+совпадает с закоммиченным значением в `e158f8f` — не принято на слово.
+Единственная изменившаяся картинка — `06-device-editor.png` (её `imageSha256`
+изменился), остальные девять сценариев сохранили прежний `imageSha256` —
+согласуется с тем, что #204 меняет именно поведение редактора устройств
+(`src/space-dialog.ts`), а не View/другие поверхности.
+
+Дополнительно исполнил `node demo/docs/capture.mjs` в этой среде, чтобы
+эмпирически проверить регенерацию — все десять PNG получились с другим
+побайтовым содержимым, чем закоммиченные (не только `06-device-editor.png`).
+Разобрался: это межсредовой шум рендера (шрифты/GPU текущего Linux-песочницы
+против среды, где скриншоты реально захватывались), а не дефект коммита —
+даже нетронутые этим коммитом файлы (например `01-view-desktop.png`)
+регенерировались иначе. Захват PNG не детерминирован между машинами по
+конструкции инструмента; коммит проверяется через `sourceFingerprint` (числовой
+хеш, воспроизведён точно), а не через побитовое совпадение растра. Откатил
+локальную регенерацию (`git checkout -- docs/images/`), в рабочем дереве
+чисто. Это не входит ни в один обязательный гейт (не diff рендера/геометрии/
+стилей — `npm run golden:verify` для скриншотов документации не применяется),
+поэтому не аргумент против коммита, а дополнительная, необязательная проверка.
+
+## Как проверялось (гейты этого цикла)
+
+Зависимости и Chromium уже установлены средой ревью; `npm ci` не запускался.
+Backend Python в этой среде без `pytest`/`voluptuous` — оба установлены
+`pip install` перед прогоном (сеть доступна), как и в r1, чтобы гейт был
+реальным исполнением.
+
+| Гейт | Команда | Результат |
+|---|---|---|
+| Типы | `npx tsc --noEmit` | green |
+| Unit | `npm test` | **919/919** green (912 в r1 + 7 новых от вошедших между `ad8e7a5` и `5dc9016` коммитов дерева `dev`, включая #204; ни один тест не относится к #205 и не изменился по содержанию #205) |
+| Сборка + синхронность бандлов | `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` | green, обе копии байт-в-байт совпадают |
+| Whitespace | `git diff --check origin/dev...HEAD` | чисто |
+| Backend — targeted | `python -m pytest tests_backend/test_trails.py tests_backend/test_trail_recorder.py -q` | **37 passed** |
+| Backend — полный pure/stub набор | `python -m pytest tests_backend -q` (после установки `pytest`+`voluptuous`) | **172 passed** — то же число, что в r1 |
+| Целевой смок (назван в AC8) | `node demo/smoke_vacuum.mjs` | `OK` |
+| Mutation guard (AC10), точечно | `node scripts/mutation-gate.mjs --id=vacuum-trail-resume-disabled` | `ok чистый прогон` → `ok vacuum-trail-resume-disabled: тест покраснел, как обязан` → `поймано 1 из 1` |
+| Mutation gate, полный набор | `node scripts/mutation-gate.mjs --check` | все **36** мутантов пойманы (35 + новый на r1, число не изменилось — конфликт ребейза не потерял и не задвоил запись) |
+| Провенанс скриншотов (доп., не гейт) | `node -e "…sourceFingerprint()…"` | совпадает с закоммиченным значением `e158f8f` |
+| Документные ссылки (доп., не гейт) | `node scripts/check-docs.mjs --external` | `Documentation checks passed (7 files, 10 external links)` |
+
+Не прогонялись (соразмерность гейта, PROCESS.md §8) — по тем же причинам, что
+и в r1, диапазон этого цикла их не меняет: полный набор из 127 браузерных
+смоков (единственный релевантный, `smoke_vacuum.mjs`, прогнан), `npm run
+golden:verify` (diff не трогает ни один файл рендера/геометрии/стилей;
+провенанс документационных скриншотов — не golden-гейт и проверен отдельно
+выше), performance-профили (в AC не названы, алгоритм O(1) на точку не
+менялся с r1). Полный HA-harness backend — канонически только Linux CI
+(`.venv-backend` недоступен в среде ревью).
+
+### Проверка дисциплины «тест умеет падать»
+
+Как и в r1 — не поверил заявлению автора «mutant caught (1/1)» из комментария
+после ребейза, а повторил сам: `node scripts/mutation-gate.mjs
+--id=vacuum-trail-resume-disabled` патчит `resumed = bool(cur and
+can_resume_trail_run(cur, map_id, now))` → `resumed = False`, гоняет
+таргетированный `scripts/trail-resume-test-guard.mjs` и подтверждает, что при
+отключённом resume фокусный набор краснеет, а на чистом дереве — зелёный.
+
+## Построчная проверка кода против контракта ТЗ (раздел 6)
+
+Diff `custom_components/houseplan/trails.py` в этом цикле идентичен тому, что
+разобран построчно в `CODE-REVIEW-205-r1.md` (та же сигнатура
+`can_resume_trail_run`, тот же порядок проверок `map_id`/`bool`/`isinstance`/
+`math.isfinite`, те же изменённые условия в `on_point`/`end_run`). Повторно
+прогнал каждый пункт контракта против исполняемых тестов на текущем `HEAD`, а
+не принял вывод r1 как данность:
+
+- **П.1–3 (resume при совпадении map_id и grace; жёсткая граница на другой
+  карте; включительная граница 30:00)** — `test_ended_run_resumes_within_grace_and_duplicate_is_a_change`,
+  `test_resume_grace_is_inclusive_then_rotates_after_epsilon`,
+  `test_resume_never_crosses_maps_and_malformed_timestamps_fail_closed` —
+  исполнены на `HEAD`, зелёные.
+- **П.4 (дубликат точки после resume → `changed=True`, точка не
+  добавляется)** — тот же тест, значение `resumed` возвращается корректно.
+- **П.5 (malformed/bool/nan/inf/clock rollback fail closed)** — тот же тест
+  плюс `test_resume_fails_closed_on_clock_rollback_and_survives_restart_shape`
+  — исполнены.
+- **П.6 (idempotent `end_run`)** — `end_run` использует `cur.get("ended") is
+  None`, подтверждено `test_repeated_short_stops_keep_all_points_and_existing_previous`.
+- **П.7 (`unavailable`/`unknown`/missing нейтральны)** — ветка `_sample` не
+  менялась, recorder-тест `test_short_available_stops_resume_one_run_and_neutral_states_do_not_shift_window`
+  подтверждает.
+- **П.8 (единый контракт для любого available non-moving state)** —
+  `test_any_available_nonmoving_state_uses_the_same_grace_contract`
+  (`paused`, `idle`, `error`, `washing`, `docked`) — исполнен.
+
+## Проверка AC1–AC11
+
+Идентична r1 по существу — тот же код, те же тесты, все исполнены на
+рейбейзнутом `HEAD` в этой сессии:
+
+| AC | Статус | Как доказано в этом цикле |
+|---|---|---|
+| AC1 | Доказан | `test_ended_run_resumes_within_grace_and_duplicate_is_a_change`, `test_short_available_stops_...` — исполнены. |
+| AC2 | Доказан | `test_resume_grace_is_inclusive_then_rotates_after_epsilon` — исполнен. |
+| AC3 | Доказан | `test_resume_never_crosses_maps_...` — исполнен. |
+| AC4 | Доказан | тот же тест, проверены и `points`, и возвращаемое значение. |
+| AC5 | Доказан | `test_repeated_short_stops_keep_all_points_and_existing_previous` — исполнен. |
+| AC6 | Доказан | `test_short_available_stops_...` + `test_any_available_nonmoving_state_...` — исполнены. |
+| AC7 | Доказан | `test_resume_fails_closed_on_clock_rollback_and_survives_restart_shape` — исполнен. |
+| AC8 | Доказан | `node demo/smoke_vacuum.mjs` → `OK`; `_renderVacuums` по-прежнему не читает `ended` (код `src/houseplan-card.ts` не тронут ни #205, ни ребейзом на этом участке). |
+| AC9 | Доказан | Полный прогон `tests_backend/test_trails.py` + `test_trail_recorder.py` (37 тестов), включая нетронутые source-health/two-floor/decimation/delete/map-switch кейсы. |
+| AC10 | Доказан | Mutation guard перепроверен самостоятельно, красный при отключённом фиксе, зелёный на исходном коде. |
+| AC11 | Доказан | Таблица гейтов выше — все зелёные, исполнены в этой сессии на текущем `HEAD`. |
+
+## Находки
+
+Ни одной **High**. Ни одной **Medium**. Ни одной **Low**.
+
+Продуктовый код, тесты и mutation-запись — тождественны r1 (уже принятому
+зелёным); единственный новый в этом цикле коммит (`e158f8f`) — легитимное,
+проверенное пересчётом хеша разрешение конфликта ребейза вне продуктовых
+файлов. Оснований для новых замечаний нет.
+
+## Что проверено и признано корректным
+
+- **Причина и контракт ТЗ реализованы буквально** — не переоткрывал заново
+  «с нуля», а сверил текущий diff с уже построчно разобранным в r1 построчным
+  разбором, затем перепроверил каждый пункт исполнением соответствующего теста
+  на текущем `HEAD` — совпадение полное.
+- **Ребейз не изменил семантику.** 12 файлов продуктового коммита `56e0114`
+  идентичны по содержанию 12 файлам `11b0283` из r1 (сверено файл за файлом);
+  расхождения есть только в `docs/STATUS.md` (естественно упоминает #204
+  вместо старого перечня issue-веток) — не поведенческое расхождение.
+- **Тесты умеют падать, не только показывают зелёное.** Собственноручно
+  воспроизвёл mutation-guard (AC10) на рейбейзнутом дереве.
+- **Гейты воспроизведены самостоятельно** на новом `HEAD`, не переписаны из
+  комментария автора после ребейза: typecheck, 919/919 unit, сборка + три
+  синхронные копии бандла, 172 backend pure/stub теста, целевой смок, полный
+  mutation-gate (36/36).
+- **Провенанс скриншотов легитимен.** `sourceFingerprint` пересчитан
+  независимо и совпадает; изменившийся `06-device-editor.png` объясняется
+  тем, что #204 меняет именно поведение редактора устройств.
+- **Документация и трейлеры.** Оба changelog правлены в том же коммите, что и
+  код (`User-Visible: yes`); коммит ребейза (`e158f8f`) — `User-Visible: no`,
+  корректно для чисто документационной синхронизации. Ветка соответствует
+  трейлерам `Issue: #205`. `git diff --check` чист.
+- **Не расширяет скоуп.** Diff идентичен r1 по продуктовым файлам; новый
+  коммит этого цикла — только `docs/images/**`, вне `custom_components/**` и
+  `src/**`.
+
+## Чего не проверял
+
+- **Полный набор из 127 браузерных смоков** — не запускал; diff не касается
+  canvas/редакторов/other rendering surfaces сверх уже названного в AC8
+  `smoke_vacuum.mjs`, который исполнен явно.
+- **`npm run golden:verify`** — не запускал; diff не меняет ни один файл
+  рендера/геометрии/стилей продукта.
+- **Побайтовое совпадение регенерированных документационных PNG** —
+  сознательно не использую как критерий: перезахват скриншотов в этой среде
+  дал другие байты даже для файлов, не тронутых этим коммитом (шрифты/GPU
+  Linux-песочницы отличаются от среды исходного захвата). Легитимность
+  коммита проверена через `sourceFingerprint` (детерминированный хеш
+  исходников), а не через растр.
+- **Полный HA-harness backend (`test_ha_*.py` с реальным Home Assistant)** —
+  в среде ревью нет `.venv-backend`/пакета `homeassistant`; канонический
+  прогон — Linux CI на точном SHA.
+- **Perf-профили** — не названы в AC, изменение O(1) на точку не менялось с
+  r1.
+- **Живой робот/симулятор демо-стенда** — вне цикла код-ревью без ручного
+  тестирования.
+- **Возможное визуальное склеивание двух реальных уборок в пределах 30
+  минут** — явно принятый владельцем trade-off (раздел 6 ТЗ), не дефект.
+
+## Вердикт
+
+**Зелёный · цикл r2/4 · High: 0 · Medium: 0 → нет новых issue.**
+
+Продуктовое содержимое не изменилось со времени зелёного r1 — сверено файл за
+файлом и перепроверено исполнением всех тестов и гейтов на рейбейзнутом
+`HEAD`, а не принято на слово ни из r1, ни из комментария автора после
+ребейза. Единственный новый в этом цикле коммит синхронизирует provenance
+документационных скриншотов с деревом, куда за время ожидания слота `S7`
+вошёл #204; легитимность проверена независимым пересчётом
+`sourceFingerprint`, а не принята на веру. Следующий статус — очередь на
+пре-релиз (`S8-merged` после мёржа в `dev`).