houseplan-card/docs/reviews/SPEC-REVIEW-218-r1.md

SPEC-REVIEW-218-r1

• Issue: #218 — одна комната с floating-point шумом в координатах гасит свечение во всём пространстве
• Артефакт ТЗ: docs/specs/218-glow-floor-geometry.md
• Ветка/SHA: issue/218-glow-floor-geometry @ c6ff34c
• Трек: обычный (не small) — файл ТЗ существует, что соответствует отсутствию метки small/trivial на issue
• Цикл: r1/4
• Вердикт: жёлтый · High: 0 · Medium: 1 (в скоупе)

Скоуп ревью

Первый цикл — разбор полный. Проверялись: тело issue #218 целиком (включая воспроизведение владельца и мутационный гейт, вписанный туда автором отчёта), оба комментария (аналитика владельца, хендофф автора ТЗ), docs/specs/218-glow-floor-geometry.md целиком, соответствие обязательным разделам §7.1 PROCESS.md, техническая достоверность «Подтверждённой причины» по фактическому коду, согласованность с каноном docs/LIGHT.md и с прецедентом #197 (docs/WALL-THICKNESS.md, docs/ARCHITECTURE.md:414).

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

• docs/SCOPE.md, AGENTS.md, PROCESS.md — прочитаны целиком; §2.4/§7.1/§8 применены к ТЗ. Job — J1 («живая пространственная картина того, что сейчас происходит»); анализ владельца в issue уже привязывает дефект к J1, ТЗ не расширяет и не переопределяет привязку.
• docs/LIGHT.md — сверена модель Glow («лампа освещает пол, который видит», §«From barriers to a lit region» про intersectionPaths, раздел про fail-dark источника в кладке) — контракт §8.2/§11 ТЗ ей не противоречит и явно её сохраняет.
• src/physical-geometry.ts:224-275 (unionBodies, intersectionPaths, geometryPolygonPaths) — прочитаны построчно. Подтверждено дословно: unionBodies глотает исключение polyclip и возвращает null (:228-230); intersectionPaths строит limit = unionBodies(bounds) и при !limit возвращает [] для всего вызова (:263-265), а падение самого intersection(base, limit) тоже даёт [] с комментарием «fail dark» (:266-274). Это ровно цепочка, которую ТЗ описывает в §3 — диагноз не догадка, а прочитанный код.
• src/physical-geometry.ts:285-302 (floorMinusBodies) — подтверждён прецедент последовательного difference как деградации при падении объединения; ТЗ §8.2 предлагает симметричный покомнатный путь для intersectionPaths, а не изобретает шаблон с нуля.
• src/houseplan-card.ts:14880-14998 (_lightBarriers) — подтверждено, что floor уже является массивом полигонов по комнате (floor: polys.map((x) => x.poly), :14987), а не заранее слитой геометрией. Это делает покомнатную деградацию из §8.2 технически реализуемой без изменения формы входных данных, вопреки риску, что ТЗ потребует данных, которых нет на этом уровне.
• src/houseplan-card.ts:15001-15117 (_renderGlowLayer) — подтверждено, что intersectionPaths([seen], floor) вызывается на каждый источник и что уже существует guard pointInOpaquePlanBody для источника в кладке (fail-dark, который §7/§8.2 ТЗ явно обязуется не ослаблять).
• docs/WALL-THICKNESS.md:125,198,213, docs/ARCHITECTURE.md:414, docs/TESTING.md:2304 — подтверждён прецедент #197 («один вырожденный стык не должен гасить остальные стены всего пространства»), на который ссылается и §4.4 ТЗ, и аналитика владельца в issue. Ссылка не декоративна — это реальный принятый прецедент того же класса дефекта.
• demo/smoke_glow_fail_dark.mjs, demo/smoke_glow.mjs, demo/smoke_glow_blending.mjs, demo/benchmark_glow.mjs — существование подтверждено; это ровно файлы, которые §16.2/AC5/AC9 ТЗ называют целевыми гейтами, а не вымышленные пути.
• scripts/mutation-gate.mjs — формат реестра (id/patches/guard/because) сверен; таблица §16.3 ТЗ описывает мутанты на уровне намерения (что за правку они бы отменили и какой guard должен упасть), а не выдаёт себя за готовые патчи — этого от ТЗ и не требуется.
• Пересчитан по коду масштаб quantum = 1e-6 единицы плана: GRID_PITCH = NORM_W/GRID_N = 1000/240, _cellCm по умолчанию 5 см (src/houseplan-card.ts:6013-6016) → 1 единица плана ≈ 1.2 см, то есть 1e-6 единицы ≈ 1.2·10⁻⁸ м, а не заявленные в ТЗ «10⁻⁹ м». См. находку Low ниже — на исполнимость AC это не влияет.
• Код продукта не менялся и не запускался на этапе spec — ревью ограничивается статическим чтением src/** и docs/**; отдельно сказано в разделе «Чего не проверял».

Находки

Medium (в скоупе, чинится в этом же ТЗ) — отсутствует обязательный раздел «Риски»

PROCESS.md §7.1 фиксирует список обязательных разделов ТЗ: «…AC1…ACn с указанием доказательства · план автотестов · риски · откат · release-артефакты». В docs/specs/218-glow-floor-geometry.md заголовка «Риски» нет вовсе (grep -in "риск" по файлу — ноль совпадений), и не только по названию: содержательного свода «что может пойти не так» нет ни в одном разделе. Формулировка «Quantum является техническим контрактом… изменение после ревью требует доказать…» (§8.1) — это governance-условие на будущее изменение константы, а не разбор рисков текущей задачи; §10 и §14 говорят про конкретный технический контракт, но не собирают риски документа в одном месте, как того требует чек-лист DoR (§2.5 PROCESS.md — «открытых продуктовых вопросов нет; риски перечислены» тоже требует явного перечня).

Для сравнения — предыдущее ревью того же типа (SPEC-REVIEW-217-r1.md) прямо проверяло присутствие «риски (§15)» как отдельного пункта чек-листа; здесь пункта нет физически.

Почему это Medium, а не High: раздел не создаёт открытой продуктовой неопределённости и не блокирует реализацию — содержательные предпосылки частично рассеяны по документу (governance quantum в §8.1, недоказанность корневой причины Glow-base в §10, стоимость прогона mutation-gate в §16.3), а инженерная часть ТЗ технически состоятельна (проверено кодом выше). Но раздел обязателен по §7.1 буквально, и его полное отсутствие — не опечатка, а пробел структуры документа, который автор должен закрыть перед выходом в «Готово к разработке».

Что чинить: добавить раздел «Риски», собрав минимум:

• изменение общего эпсилона unionBodies() затрагивает не только Glow, а весь boolean-слой (масонри, floorMinusBodies, physicalBodiesPath) — риск регрессии в соседних потребителях, если квантование когда-нибудь перестанет быть no-op для валидных планов;
• наблюдение Glow-base (§10) может не воспроизвестись той же причиной — риск остаться недокументированным при отрицательном результате;
• стоимость прогона mutation-gate.mjs для новых мутантов перед релизом (уже упомянута в §16.3 как факт, но не как риск бюджета review-цикла);
• легаси-планы с перекрывающимися комнатами (упомянуты в §8.2 как то, что нормальный путь обязан беречь) — риск того, что покомнатный fallback даст иное покрытие пола, чем текущий merged path, на таких планах.

Это не требует переписывания ТЗ — достаточно одного раздела, синтезирующего уже имеющийся материал; технической неопределённости к решению владельцу это не добавляет.

Low (снята с записью, не блокирует)

§8.1 ТЗ утверждает: «quantum 1e-6 единицы плана = 10⁻⁹ м». Пересчёт по GRID_PITCH = NORM_W/GRID_N (src/space-geometry.ts:11, :197-199) и _cellCm по умолчанию 5 см (src/houseplan-card.ts:6013-6016) даёт 1e-6 единицы ≈ 1.2e-8 м — на порядок больше заявленного. Расхождение чисто иллюстративное: качественный вывод абзаца («далеко за пределами любой видимой/физической точности плана») верен при любом разумном cell_cm, ни один AC и ни один тест не ссылается на конкретное число метров, и cell_cm конфигурируем per-space, так что «единица = 10⁻⁹ м» в принципе не может быть универсально точной константой. Снимаю без цикла: правки не требую, но если автор будет трогать ТЗ по Medium-находке выше, стоит заменить точное число на формулировку без привязки к конкретным метрам (например, «на много порядков меньше миллиметра при любом реалистичном масштабе плана»).

Проверка обязательных разделов §7.1

Присутствуют и содержательны: сценарий (§1) · что человек увидит до/после (§2) · подтверждённая причина = проблема (§3) · нормативные источники и приоритет (§4) · цели (§5) · scope/не-scope (§6/§7) · контракт поведения (§8/§9/§10) · UX/accessibility/touch (§11) · данные/migration/privacy/i18n (§12) · архитектура (§13) · performance/security (§14) · AC1…AC10, каждый с доказательством (§15) · план автотестов (§16) · release-артефакты (§17) · откат (§18) · принятые предположения (§19).

Отсутствует: риски как отдельный раздел — единственный пункт списка §7.1, не найденный в документе ни по заголовку, ни по содержанию (см. Medium выше).

Продуктовых открытых вопросов нет — и корректно нет: сценарий, ожидаемое поведение до/после и приоритет между «не гасить весь этаж» и «сохранить fail-dark для реально небезопасных случаев» уже зафиксированы решением владельца в комментарии-аналитике (не додуманы автором ТЗ). Единственная техническая неопределённость (наблюдение Glow-base, §10) явно помечена как «если не воспроизведётся — зафиксировать и не расширять #218», что соответствует правилу «размытое место не додумывается, а разбирается предположением с явной пометкой» (§19 п.5 ТЗ).

Каждый AC1–AC10 однозначен, имеет названный способ доказательства (unit/browser smoke/golden/«source review»/docs diff) и, где применимо, явно требует падения до фикса («красный при mutant без normalization» — AC1; «тест красный на коде до #218» — AC2) — это соответствует правилу «AC доказывает автотест, который умеет падать», а не одно предъявление.

Проверка «догадка выдана за факт»

Технические утверждения ТЗ о текущем поведении сверены с кодом построчно (см. раздел «Как проверялось») и подтверждены, а не переписаны со слов автора отчёта issue. Утверждения о том, чего ТЗ не гарантирует (наблюдение Glow-base, точная конверсия quantum в метры) либо явно помечены условием (§10), либо являются декоративной иллюстрацией без влияния на AC (см. Low). Других мест, где предположение подано как решённый факт без пометки, не найдено.

Соответствие SCOPE.md

Задача устраняет полный, беззвучный отказ Core user job J1 («живая пространственная картина происходящего сейчас») для целого пространства на любом плане, где комната когда-либо резалась/двигалась — то есть практически на любом реальном плане. Не расширяет продуктовый скоуп: радиус, цвет, opacity, blend, анимация, visibility-алгоритм, проёмы и защита источника в кладке явно исключены в §7 ТЗ и остаются неизменными. Не вводит новых настроек, новых i18n-строк и не касается раздела «Out of scope» SCOPE.md.

Соответствие TOUCH-SUPPORT.md / CONFIG-COMPATIBILITY.md

Изменение — чистая геометрия рендера без новых элементов UI и взаимодействий; §11 ТЗ прямо фиксирует идентичный render для mouse/touch/pen в View/kiosk и редакторах, что не создаёт нового touch-контракта и не требует отдельной проверки по TOUCH-SUPPORT.md. §12 ТЗ фиксирует отсутствие изменений конфига/схемы/миграции; при отсутствии новых compatibility-полей это не конфликтует с CONFIG-COMPATIBILITY.md.

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

• Реальная browser-геометрия и golden-рендер не запускались — на этапе spec кода ещё нет; проверка ограничена статическим чтением текущего src/** и сверкой заявленной цепочки вызовов с ним.
• Не проверялась реальная величина деградации/perf-профиль benchmark_glow.mjs — на этой стадии нет реализации для профилирования; §14 ТЗ корректно ограничивает решение одним линейным проходом и переносит измерение на code-review.
• Точная форма будущего test/physical-geometry.test.mjs и целевого smoke (расширение smoke_glow.mjs либо новый файл) не проверялась предметно — это технический выбор автора, явно оставленный реализации (§16.2 ТЗ), и ревью ТЗ не обязано фиксировать его заранее.
• Приватный реальный экспорт владельца не запрашивался и не читался — ТЗ корректно ограничивается минимизированной анонимизированной fixture (§19 п.4), что и требуется privacy-контрактом §12.

Вердикт

Жёлтый: High 0, Medium 1 — в скоупе, чинится автором в текущем ТЗ (добавить раздел «Риски»), без создания отдельного issue. После правки — повторный цикл разбирается по дельте (§2.9/§2.10 PROCESS.md): дельта ограничена одним новым разделом, остальное наследуется из этого документа.