From e943e2f1b2de33670dd62e33b773e715c8d318f0 Mon Sep 17 00:00:00 2001 From: "claude[bot]" <209825114+claude[bot]@users.noreply.github.com> Date: Sat, 22 Aug 2026 15:24:00 +0000 Subject: [PATCH] docs: review document for #231 Issue: #231 User-Visible: no --- docs/reviews/SPEC-REVIEW-231-r2.md | 143 +++++++++++++++++++++++++++++ 1 file changed, 143 insertions(+) create mode 100644 docs/reviews/SPEC-REVIEW-231-r2.md diff --git a/docs/reviews/SPEC-REVIEW-231-r2.md b/docs/reviews/SPEC-REVIEW-231-r2.md new file mode 100644 index 00000000..043d86b9 --- /dev/null +++ b/docs/reviews/SPEC-REVIEW-231-r2.md @@ -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`, + ``); + - `.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`.