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

Ревью ТЗ — issue #20, заход r1

• Issue: https://github.com/Matysh/houseplan-card/issues/20
• ТЗ: docs/specs/020-glow-open-door-spill.md (коммит 962b1d0d, ветка issue/20-glow-open-door-spill, единственный коммит поверх origin/dev)
• Трек: обычный (владелец явно снял small 2026-08-15 и подтвердил «лёгкий трек: нет» повторно 2026-08-28 — меняется горячий geometry/cache path и требуется performance proof)
• Заход: r1 · блокирующих циклов израсходовано 0 из 4
• Вердикт: зелёный · High: 0 · Medium: 0

Скоуп ревью

Проверялось ТЗ docs/specs/020-glow-open-door-spill.md как артефакт этапа S4-spec-review: обязательные разделы §7.1 PROCESS.md, однозначность и доказуемость AC1…AC10, соответствие docs/SCOPE.md, канонической модели docs/LIGHT.md и терминологии docs/USER-GUIDE.ru.md, а также независимая проверка каждого фактического утверждения ТЗ о текущем коде (не пересказ автора) — ТЗ описывает конкретные функции, кэш-ключи и геометрические типы, и первый вопрос ревью к такому тексту: существуют ли они там, где сказано, и делают ли то, что сказано. Продуктового кода по #20 нет (ветка содержит только правку ТЗ), поэтому гейты §8 к этому заходу неприменимы.

История issue: тело 2026-08-09 описывало старую (уже не существующую) модель интервалов-occluder; комментарий владельца 2026-08-11 актуализировал механику под пост-#71 модель полигона видимости; комментарий 2026-08-15 зафиксировал P3/feature/обычный трек и закрыл продуктовые вопросы («Вопросы: нет — поведение проёма без contact entity и fallback уже определены»); комментарий 2026-08-28 подтвердил взятие в работу и текущую редакцию ТЗ. Предыдущего цикла ревью ТЗ на этом issue не было — это первый заход, раздел «Унаследовано из r0» не применяется.

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

1. Прочитаны docs/SCOPE.md, AGENTS.md, PROCESS.md (§2.3–2.10, §7.1, §7.2) целиком.
2. Прочитано тело issue #20 и все четыре комментария владельца.
3. Прочитан файл ТЗ 020-glow-open-door-spill.md целиком (224 строки).
4. Прочитан канонический docs/LIGHT.md целиком — источник истины для модели света, на которую ТЗ явно ссылается.
5. Проверена терминология в docs/USER-GUIDE.ru.md (Glow, ворота как аналог двери, «стены не пропускают Glow») — используемые в ТЗ слова не изобретены, они те же, что видит пользователь в интерфейсе.
6. Независимо сверены с кодом все технические утверждения ТЗ, которые могли бы оказаться недоказанной догадкой, выданной за факт:
   • _lightBarriers() (src/houseplan-card.ts:10261-10392) — подтверждена фильтрация passages через isInteriorLightOpeningType (allowlist door | gate | passage), проверка пола по обе стороны (onFloor), разделение контурных вырезов (roomPassages/cuts) и партиций (_partitionOpeningCuts → PartitionOpeningCut), кэш-ключ contentFingerprint([raw, cellCm, gridPitch]) — сейчас не содержит состояние проёмов, что и есть повод для задачи;
   • openingAmount() (src/logic.ts:316-324) — подтверждён текущий бинарный контракт (0/1, fallback 1 для двери/ворот без датчика, unavailable/unknown не меняются invert) — ровно то, что таблица ТЗ §"Контракт поведения / 1" описывает как сохраняемый инвариант для известного/fallback случая; расширение под current_position cover — заявленная новая работа, не выдаётся за существующую;
   • _openingAmt()/OpeningVisibleSpec.amount (src/houseplan-card.ts: 12303-12309, src/render/opening-symbol.ts:8-61) — подтверждено, что символ проёма уже использует единое дробное amount в [0,1] (Math.max(0, Math.min(1, spec.amount))), то есть претензия ТЗ «один коэффициент для символа и Glow» технически реализуема без переделки символа — расширяется только источник числа;
   • PartitionOpeningCut (src/physical-geometry.ts:145-186) — подтверждён генерический сегмент {hostId, a, b, depth}, не привязанный к полной длине проёма — масштабирование a/b вокруг центра для частичного выреза, которое требует ТЗ, архитектурно естественно;
   • _roomWallOpeningInputs() (src/houseplan-card.ts:7494-7505, geometryRoomOpeningInputs) отдаёт {x, y, angle, length} на проём — подтверждено, что вырез строится из length вокруг центра (houseplan-card.ts:10310-10314), то есть length * amount с тем же центром/осью — не выдумка, а прямое следствие существующей формулы;
   • _contactCandidates() (src/houseplan-editor-runtime.ts:6379-6394) — подтверждено, что cover-домен уже допустим как opening.contact для дверных device_class (door, garage_door, garage, opening, window) — «доступный cover» в контракте ТЗ не новая возможность привязки, а новое использование уже существующей;
   • lruWrite(this._lightBarrierPool, cacheKey, entry, 8) и lruWrite(this._glowClipCache, clipKey, geometry, 256) (houseplan-card.ts:10389, 10506) — подтверждены названные в ТЗ границы LRU;
   • demo/smoke_glow.mjs, demo/fixtures/large-house.mjs, demo/benchmark_glow.mjs — подтверждено существование large-house-фикстуры и Glow-бенчмарка, на которые опирается AC9, ничего вымышленного.
7. Проверено соответствие docs/SCOPE.md: владелец уже классифицировал задачу как «пространственная правдивость света» (комментарий 2026-08-15) — это часть J1 («живой пространственный обзор») и общей заявки миссии «live, tappable map»; ревью не переоткрывает уже принятое владельцем scope-решение.
8. Проверены незакрытые продуктовые вопросы: их нет — владелец прямо подтвердил в комментарии 2026-08-15, что поведение без contact entity и fallback уже определено; в ТЗ нет ни одного утверждения о видимом поведении, помеченного как решённое, но не подтверждённого ни одним документом или существующим кодом.
9. Код не запускался, гейты §8 не прогонялись — на этапе ревью ТЗ продуктового кода нет (см. «Скоуп ревью» выше).

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

Все присутствуют и содержательны: сценарий (персона/поверхность/момент) · что человек увидит до/после (одна фраза, без терминов реализации, кроме слова «Glow», которое само является интерфейсным термином из USER-GUIDE.ru.md, а не внутренним) · проблема · скоуп и не-скоуп · контракт поведения · UX · модель данных и миграция · i18n · AC1…AC10 с указанным способом доказательства (unit/smoke/golden/CI-perf) · план автотестов · риски и меры · откат · release-артефакты · блок «принято предположительно».

Блок «принято предположительно» (§218-223 ТЗ) содержит только технические решения (форма и файл чистого aperture-хелпера, сериализация signature, механика частичного PartitionOpeningCut, разбиение smoke/golden файлов) — ни одно из них не является продуктовым вопросом, спрятанным под видом допущения.

Проверка AC

Все десять AC пронумерованы, формулируют конкретное наблюдаемое поведение (или измеримый контракт кэша/perf) и называют способ доказательства:

• AC1, AC2 — closed/open переход, unit геометрии + browser smoke с переключением состояния fake hass;
• AC3 — частичное открытие через cover.current_position, unit + smoke по пикселям;
• AC4 — матрица invert на известных/fallback состояниях, unit;
• AC5 — классификатор типов (door/gate/passage прозрачны, window/наружная дверь/неизвестный тип непрозрачны), unit + smoke;
• AC6 — паритет контурной стены и независимой перегородки, geometry unit + smoke fixture;
• AC7 — fail-dark источника внутри закрытого проёма, source-guard unit/smoke;
• AC8 — контракт кэша (переиспользование при посторонней сигнатуре, новый ключ при смене amount, bounded LRU), unit;
• AC9 — perf-бюджет на large-house fixture, exact-SHA CI performance smoke перед бетой (согласовано с AGENTS.md: performance/golden — предрелизный гейт, а не гейт этой стадии);
• AC10 — golden-сцена closed/open/50%, reviewed Linux golden-артефакт.

Все десять привязаны к реально существующим точкам расширения кода (см. п.6 выше), ни один не описывает несуществующий API как готовый.

Находки

Не найдено ни одной High- или Medium-находки. ТЗ не содержит утверждений о поведении, которых нет ни в docs/LIGHT.md, ни в текущем коде и которые не помечены как допущение; открытых продуктовых вопросов нет — они закрыты владельцем заранее.

L1 (Low, снимается без правки) — влияние на touch не названо отдельной строкой

DoR-чеклист (PROCESS.md §2.5) требует явно названного влияния на touch по docs/TOUCH-SUPPORT.md. В самом ТЗ такой отдельной строки нет. Снимаю без правки: раздел «УХ» ТЗ прямо утверждает «новых контролов и сообщений нет» — изменение целиком в рендеринге Glow в View/kiosk, без нового взаимодействия, а docs/TOUCH-SUPPORT.md требует паритета именно для интерактивных путей View, которых здесь не появляется. Рендер одинаков на любом указывающем устройстве; отдельно фиксировать «влияние: нет» было бы формальностью, а не содержательной проверкой. Если автор всё же добавит эту строку явно в ТЗ — это не будет считаться повторным циклом ревью.

Что проверено и корректно

• все причинно-следственные утверждения ТЗ о текущей модели (_lightBarriers, openingAmount, PartitionOpeningCut, LRU-границы, cover-контакты, large-house-фикстура) подтверждены чтением кода, а не поверены на слово;
• контракт таблицы «Один коэффициент открытия» не противоречит текущему поведению openingAmount() для известных/fallback случаев — расширяет его, не переопределяя уже проверенный инвариант;
• не-скоуп корректно исключает наружный свет, tunnel fill, автоматическое управление дверью и смену конфигурационной схемы — ни один пункт не расширяет заявленный скоуп «мимоходом»;
• release-артефакты называют актуализацию docs/LIGHT.md, что необходимо: канонический документ сейчас не описывает частичную апертуру и обязан получить это описание в том же изменении;
• открытых продуктовых вопросов нет, что подтверждено собственным комментарием владельца, а не заявлением автора ТЗ.

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

• Не запускал npm run typecheck/npm test/npm run build — продуктового кода в ветке нет, применять их не к чему на этой стадии.
• Не проверял производительность фактическим прогоном benchmark_glow.mjs — AC9 сам относит это доказательство к предрелизному exact-SHA CI, а не к этому циклу.
• Не проверял golden — сцена ещё не существует (AC10, план автотестов п.4), проверять нечего до реализации.
• Не оценивал точную формулу сериализации openingStateSignature и место файла aperture-хелпера — оба явно вынесены в блок «принято предположительно, поменять свободно» и не являются предметом этого ревью.

Вердикт

Зелёный. ТЗ готово к разработке.