houseplan-card/docs/reviews/SPEC-REVIEW-231-r2.md

# SPEC-REVIEW-231-r2

- **Issue:** #231 — декоративный слой виден поверх заливок комнат
- **ТЗ:** `docs/specs/231-decor-layer-order.md`
- **r1 ревьюировано на:** commit `e023adb` (см. `docs/reviews/SPEC-REVIEW-231-r1.md`, зафиксирован в заголовке документа; дополнительно подтверждён комментарием автора «Предыдущий reviewed SHA ТЗ: e023adb»)
- **Дельта r1→r2:** commit `9410be6` («docs(spec): prove decor above room hover»)
- **Заход:** r2 · блокирующих циклов израсходовано 1 из 4
- **Вердикт:** зелёный · High: 0 · Medium: 0

## Скоуп ревью

Второй заход, разбор по дельте (PROCESS.md §2.10). r1 вернул ровно одну находку —
Medium M1 (пробел в доказательстве позиции decor относительно room hover fill).
Дельта `git diff e023adb..9410be6 -- docs/specs/231-decor-layer-order.md` —
единственный файл, 13 строк, два хунка: правка AC2 (§14) и добавление в план
автотестов (§15.1, §15.2). Никакого ребейза на ушедший вперёд `dev`, смены
контракта поведения или новой подсистемы: `git show --stat 9410be6` подтверждает
ровно один изменённый файл. Дельта локальна и несопоставима по объёму с исходным
ТЗ (352 строки) → по правилу §2.10 полный повторный разбор не требуется, кроме
AC2 и того, что дельта задевает.

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

1. Найден вердикт r1 в комментариях issue (2026-08-22T15:18:46Z, жёлтый, заход
   r1, блокирующих циклов 0/4, High 0, Medium 1) и приложенный документ
   `docs/reviews/SPEC-REVIEW-231-r1.md` (коммит `d2e7626`), где reviewed SHA
   назван явно в заголовке — `e023adb`. Разночтения между комментарием-вердиктом
   (SHA не упомянут в тексте самого комментария) и документом (SHA назван) нет
   практического значения: документ — канонический артефакт ревью, комментарий
   — его краткое резюме; процесс не требует дублировать SHA в самом комментарии.
2. Объявлена дельта: `git diff e023adb..9410be6 -- docs/specs/231-decor-layer-order.md`
   и `git show --stat 9410be6` — единственный файл, только §14/AC2 и §15.1/§15.2.
3. Прочитан комментарий автора о правке (2026-08-22T15:20:09Z): заявлено закрытие
   M1 через правку AC2, добавление DOM-order + raster проверки и включение
   `smoke_glow.mjs` в целевой список гейтов. Проверено построчно ниже, а не
   принято на слово.
4. Сверены реальные имена классов/методов, на которые ссылается новая
   формулировка AC2/§15.2, с фактическим кодом:
   - `.room-hover-fill-layer` — существует (`src/houseplan-card.ts:11865`,
     `<g class="room-hover room-hover-fill-layer" ...>`);
   - `.decorlayer` — существует (`src/houseplan-card.ts:10094`);
   - `compareDocumentPosition` между hover-fill-layer и другим слоем — уже
     реальный работающий паттерн в `demo/smoke_glow.mjs:245-261`
     (`hoverFillLayer.compareDocumentPosition(glowLayer) & Node.DOCUMENT_POSITION_FOLLOWING`),
     то есть предложенное расширение того же ассерта на `.decorlayer`
     технически осуществимо, а не гипотетическая заявка.
5. Проверено соответствие новой формулировки AC2 нормативному §8.1, который сам
   не менялся дельтой и уже требовал этот порядок в r1 (сама находка M1 была о
   разрыве между §8.1 и AC, а не о неверном §8.1) — теперь AC2 текстуально
   покрывает то же, что §8.1: room hover fill → обычный тоннель → Glow-base
   комнаты → Glow-base тоннеля → decor.
6. Проверено, что доказательство в §15.2 не сводится к одному
   `compareDocumentPosition` — явно требуется дополнительный raster sample
   «decor внутри подсвеченной комнаты», что соответствует общему правилу того же
   раздела («один compareDocumentPosition без пиксельного/поведенческого assert
   не считается доказательством AC1–AC3») и снимает риск M1-сценария (decor
   вставлен раньше hover fill, но формально после тоннелей — тест теперь ловит
   именно эту перестановку и по DOM, и по пикселю).
7. Проверено AC5 (documented mutant, «краснеет по AC1/AC2») — не менялся текстом,
   но теперь корректно покрывает и новую часть AC2 (hover), так как ссылается на
   AC2 целиком, а не на прежнюю более узкую формулировку.
8. Проверено, что правка не расширяет и не сужает скоуп: §6/§7 (входит/не входит),
   §8.2 (Glow blend, открытый технический риск), §8.3/§19.1 (решение владельца по
   Q1), §9 (hide/editor/backdrop parity), §10 (touch/UX), §11 (данные/i18n),
   §16 (риски), §17 (откат), §18 (release-артефакты) — во всех этих разделах
   дельта не тронула ни строки; в них нет ссылок на изменённый текст AC2/§15,
   которые дельта могла бы сделать противоречивыми.
9. Гейты кода не прогонялись — продуктовый код не менялся ни в дельте, ни в
   исходном ТЗ; на этапе ТЗ это не относится к предмету ревью (см. также §10
   `Чего не проверял` r1, неизменное основание). `git diff --check` и
   `node scripts/check-docs.mjs --external`, упомянутые автором, — гигиена
   коммита ТЗ, не предмет спецификационного ревью.

## Закрытие раунда r1

| Находка r1 | Чем закрыта | Где это видно |
|---|---|---|
| **M1** — §8.1 требует decor после room hover fill, но ни AC1, ни AC2, ни AC3 это не проверяли; `smoke_glow.mjs` умел сравнивать DOM-порядок hover-fill-layer, но не упоминал `.decorlayer` | AC2 (§14 п.2) переписан: явно требует «decor следует в DOM и визуально лежит после **room hover fill**, обычного тоннеля, Glow-base комнаты и Glow-base тоннеля; hover-подсветка не тонирует decor». План автотестов (§15.1) добавляет `node demo/smoke_glow.mjs` в целевой список гейтов. Обязательная fixture (§15.2) добавляет «активный room hover с существующей `.room-hover-fill-layer`; целевой assert проверяет `compareDocumentPosition` от неё к `.decorlayer` и raster sample на decor внутри подсвеченной комнаты» | `docs/specs/231-decor-layer-order.md` §14 AC2 (строки 225-229) и §15.1/§15.2 (строки 266, 284-286); дельта `git diff e023adb..9410be6` |

Закрытие проверено не на слово автора: имена классов и метод сравнения DOM-позиции
существуют в реальном коде и в уже работающем аналогичном ассерте (см. «Как
проверялось», пп. 4). Формальный сценарий обхода из M1 («decor вставлен до hover
fill, но AC2 всё равно зелёный, потому что тоннели/Glow-base идут после него»)
теперь не проходит: новый DOM-order assert проверяет позицию `.decorlayer`
непосредственно относительно `.room-hover-fill-layer`, а не только относительно
тоннелей.

## Унаследовано из r1

Принято без повторной проверки, по `docs/reviews/SPEC-REVIEW-231-r1.md` @ SHA
`e023adb` — дельта r2 не касается ни одного из этих разделов:

- продуктовая рамка (сценарий, персона, «что человек увидит до/после», привязка
  к J1 из `docs/SCOPE.md`) — §1, §2;
- подтверждённая по коду причина дефекта (§3) и приоритет нормативных источников
  (§4);
- цели и scope/не-scope (§5, §6, §7), включая явное исключение per-object флага
  «под планом»;
- нормативный порядок слоёв §8.1 (сама граница, а не её покрытие тестами),
  Glow-риск §8.2 с корректной эскалацией вместо молчаливого решения, компат
  старого decor и решение владельца по Q1 §8.3;
- hide/editor/backdrop parity §9, touch/UX §10, данные/миграция/i18n §11,
  архитектура и зоны изменений §12, performance/security §13;
- AC1, AC3, AC4, AC6, AC7, AC8 (§14) — их текст и доказательства дельта не
  меняла;
- golden-план §15.3, риски §16, откат §17, release-артефакты §18, принятые
  предположения §19.

## Что проверено и корректно (дельта r2)

- AC2 больше не расходится с §8.1: нормативное требование и критерий приёмки
  теперь говорят об одном и том же порядке.
- Доказательство AC2 — не голословное «DOM-order», а конкретный метод
  (`compareDocumentPosition` между двумя названными, существующими в коде
  классами) плюс обязательный пиксельный/поведенческий assert, как требует
  общее правило §15.2 для AC1–AC3.
- `smoke_glow.mjs` включён в целевой список гейтов реализации (§15.1) —
  устраняет ровно тот пробел, который отметил r1 (существующий тест умел
  сравнивать hover-позицию, но не был назван обязательным для этой задачи).
- Дельта не вводит новых догадок: формулировка AC2 не утверждает ничего, что не
  вытекало бы уже из §8.1 и решения владельца в теле issue.
- Дельта не расширяет и не сужает скоуп, не меняет контракт поведения сверх
  того, что было согласовано в r1 и владельцем.

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

- Не проверял разделы, не тронутые дельтой и перечисленные выше как
  «Унаследовано из r1» — они разобраны r1 по коду и issue, повторная
  верификация не требуется по PROCESS.md §2.10.
- Не прогонял `typecheck`/`test`/`build`/golden/smoke — продуктовый код не
  менялся ни в исходном ТЗ, ни в дельте r2; эти гейты относятся к будущему
  код-ревью, а не к ревью ТЗ.
- Не проверял фактическое визуальное поведение Glow-blend на decor в браузере —
  на этапе ТЗ нет кода для запуска; это остаётся открытым техническим риском
  §8.2, корректно вынесенным в реализацию с явным запретом молчаливого решения.

## Резюме

Единственная находка r1 (M1, Medium, в скоупе) закрыта точным и проверяемым
изменением AC2 и плана автотестов, без догадок и без расширения скоупа. Новых
находок в дельте r2 нет. Остальной контракт наследуется из r1 без повторной
проверки, так как дельта его не касается. Вердикт: зелёный, ТЗ переходит в
`S5-ready`.