docs: review document for #231

Issue: #231 User-Visible: no
2026-09-29 03:09:36 +00:00 · 2026-08-22 15:24:00 +00:00
parent 9410be6028
commit e943e2f1b2
1 changed files with 143 additions and 0 deletions
@@ -0,0 +1,143 @@
+# 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`.