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

# SPEC-REVIEW-366-r2

Issue: #366 — «Glow #20: движущиеся ворота на cover-сущности вызывают до ~100
пересчётов геометрии света за одно открытие»
Этап: ТЗ на ревью (S4-spec-review), лёгкий трек (`small`)
Заход: r2 · блокирующих циклов ревью ТЗ израсходовано 1 из 2 (лимит §4 для лёгкого трека)
Материал: тело issue #366 на момент ревью (ревизия 2), дерево `dev` на SHA
`c50d9e42903921589eca8dc90c113ca329e3c6f5`
Предыдущий раунд: `docs/reviews/SPEC-REVIEW-366-r1.md`, вердикт жёлтый, материал —
дерево `dev` на SHA `f2e365726a6e28a9acf03b6a37b4d2099770229d`
Вердикт: **зелёный**

## Скоуп раунда

Разбор по дельте (§2.10 PROCESS.md), а не заново. Артефакт ТЗ живёт в теле
issue (small-трек), поэтому формального `git diff` файла нет; дельта
установлена тремя способами и все три сходятся:

1. футер ревизии 2 сам перечисляет изменения: «M1 — AC4 называет реальный
   `smoke_glow.mjs`... M2 — визуальная ступенчатость явно помечена как
   принятое предположение... Low: строки уточнятся по факту в код-ревью;
   `docs/LIGHT.md` §Caching добавлен в release-артефакты реализации»;
2. прямое сравнение текущего тела issue с фрагментами, процитированными в
   `SPEC-REVIEW-366-r1.md`: разделы «Проблема», «Направление фикса»,
   «AC-кандидаты», К1, К2, AC1/AC2/AC3/AC5, «Откат» byte-идентичны цитатам r1
   — менялись только формулировка AC4 и добавленный блок «Принято
   предположительно»;
3. `git diff f2e365726a6e28a9acf03b6a37b4d2099770229d..HEAD --stat -- src/logic.ts src/houseplan-card.ts demo/smoke_glow.mjs demo/smoke_junction_limits.mjs docs/LIGHT.md`
   — пусто. Дерево `dev` для всех файлов, на которые опирался r1, не сдвинулось
   ни на строку между SHA r1 и текущим HEAD (три коммита между ними — доки по
   #369 и публикация самого `SPEC-REVIEW-366-r1.md`, продукта не касаются).
   Значит это не ребейз на ушедший вперёд `dev` (§2.10 «разбор остаётся
   полным, если...») — условие для сокращённого разбора выполнено, а не
   просто заявлено.

Дельта локальна и мала по объёму относительно исходного ТЗ: правка текста
одного AC и добавление одного маркирующего абзаца. Новая подсистема не
задета, контракт (К1/К2, формула квантования, единственная точка применения)
не менялся. Полный повторный разбор не требуется.

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

Дельта проверена по существу, не на слово автора:

- **M1** (было: AC4 называл несуществующий `smoke_door_glow*` плюс
  необоснованный `smoke_junction_limits`). Текущий AC4: «существующие
  смоки/golden #20 зелёные без правки ассертов — прежде всего
  `demo/smoke_glow.mjs` (строки ~598-631 уже гоняют `current_position`
  0/50/100 — все узлы сетки 0.05) плюс полный смок-набор по smoke-select
  дельты». Прочитал `demo/smoke_glow.mjs:598-631` — `setDoorPosition(0)` на
  :627 и `setDoorPosition(50)` на :629, начальный `current_position: 100` на
  :360 (`glow_dynamic_door` через `current_position` реально существует и
  реально использует доли 0/0.5/1.0 — узлы сетки 0.05 из К1). Название файла
  и утверждение о его содержимом точны. Ссылка на `smoke_junction_limits` без
  обоснования убрана, вместо неё — отсылка на инструмент выбора смоков по
  дельте (`scripts/smoke-select.mjs`), который и предназначен закрыть этот
  класс вопроса, когда код появится. **M1 закрыта по существу, не просто
  переформулирована.**
- **M2** (было: «5% неразличимо» подано фактом, не пометкой). Текущий текст
  содержит отдельный абзац: «**Принято предположительно (r1-M2):** визуальная
  цена — вырез света ступает по 5% длины проёма. Предположение: ... Если
  полевые впечатления владельца после беты скажут обратное — квант
  уменьшается правкой одной константы (0.02 ⇒ ≤51 пересчёт) либо решение
  пересматривается в сторону debounce; цена отката — один revert.» Это ровно
  формат «принято предположительно, поменять свободно» из §7.1, названо явное
  условие пересмотра и цена отката. **M2 закрыта.**
- **L1** (номера строк в ТЗ отстали от `dev`). Автор явно отложил до
  код-ревью («строки уточнятся по факту»), не стал переписывать текст ТЗ.
  Проверил актуальность: поскольку `houseplan-card.ts` не менялся между SHA
  r1 и текущим HEAD (см. diff --stat выше), расхождение то же самое, что было
  на r1 (было −1 к номеру), не выросло. Отложенное решение приемлемо: Low
  находится на усмотрение ревьюера, а номера строк реализация всё равно
  сверит перед кодом.
- **L2** (`docs/LIGHT.md` не назван в release-артефактах). Футер ревизии 2
  утверждает «`docs/LIGHT.md` §Caching добавлен в release-артефакты
  реализации» — проверил текст всего тела issue (`grep -in "light.md\|release"`
  по полному телу): единственное вхождение `LIGHT.md` — сама эта фраза в
  футере. В основном тексте ТЗ (раздел «User-Visible») по-прежнему только
  «changelog en+ru», отдельного упоминания `docs/LIGHT.md` в тексте контракта
  или отката нет. **Заявление футера не подтверждено текстом документа** —
  см. находку L2′ ниже.
- К1/К2/AC1/AC2/AC3/AC5/откат — не перепроверялись заново по существу
  (наследуются из r1, см. раздел ниже), т.к. дельта их текста не касается и
  дерево `dev`, от которого зависела их проверка, не двигалось.

## Находки

Находок, блокирующих цикл (High или Medium в скоупе без ответа), нет.

### L2′ (Low, не блокирует) — расхождение футера ревизии 2 с фактическим текстом ТЗ

Футер ревизии 2 заявляет, что `docs/LIGHT.md` §Caching добавлен в
release-артефакты реализации. По факту в теле issue такой записи нет —
раздел «User-Visible» называет только changelog en+ru, отдельного упоминания
`docs/LIGHT.md` как обязательного release-артефакта нет ни в контракте, ни в
разделе отката.

**Почему Low:** предыдущая находка L2 (r1) была необязательной («правится
либо снимается решением ревьюера с записью, если сочтёт достаточным
changelog»). Обновление канонического документа подсистемы при смене
контракта сигнатуры всё равно требуется по DoR (§2.5 «release-артефакты...
документация») и будет проверено на код-ревью независимо от текста ТЗ —
неточность футера не создаёт риска пропустить реальную правку `LIGHT.md`,
только неточно описывает, что уже сделано на этапе ТЗ.

**Диспозиция:** снимаю без правки текста ТЗ, с записью здесь. Требование к
разработчику остаётся: при реализации обновить `docs/LIGHT.md` §Caching
числовым шагом квантования (0.05) тем же коммитом, что и код — это проверит
код-ревью (S7), а не повторный цикл ревью ТЗ.

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

| Находка (r1) | Чем закрыта | Где видно |
|---|---|---|
| **M1** — AC4 называет несуществующий/необоснованный смок | AC4 переписан: называет реальный `demo/smoke_glow.mjs` (проверено: строки 598-631 действительно двигают `current_position` через 0/50/100, узлы сетки 0.05) + отсылка к `smoke-select.mjs` вместо необоснованного `smoke_junction_limits` | Тело issue #366, раздел «AC и доказательства», пункт **AC4** |
| **M2** — визуальная ступенчатость подана фактом, не предположением | Добавлен абзац «Принято предположительно (r1-M2)» с явным условием пересмотра и ценой отката | Тело issue #366, между К2 и «AC и доказательства» |
| **L1** — номера строк в ТЗ отстали от `dev` | Не исправлено текстом; автор явно отложил до код-ревью. Расхождение не выросло — `houseplan-card.ts` не менялся с r1 (см. `git diff --stat` в разделе «Как проверялось») | Футер ревизии 2: «строки уточнятся по факту в коде-ревью» |
| **L2** — `docs/LIGHT.md` не назван в release-артефактах | **Не закрыта фактически**, несмотря на заявление футера — см. находку L2′. Снимается как Low с явной запиской, требование переносится на код-ревью | Футер ревизии 2 vs тело issue (нет строки в разделе User-Visible) |

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

Без повторной проверки принято из `docs/reviews/SPEC-REVIEW-366-r1.md`
(SHA `f2e365726a6e28a9acf03b6a37b4d2099770229d`), поскольку дельта этого
раунда их текста не касается, а код, на котором строилась проверка, не
изменился (`git diff --stat` пуст для `src/logic.ts`,
`src/houseplan-card.ts`, `demo/smoke_glow.mjs`, `docs/LIGHT.md` между тем SHA
и текущим `HEAD`):

- Локализация проблемы (`openingLightStateSignature`,
  `src/logic.ts:344-357`, `amount.toFixed(3)`) и её причина (cover
  `current_position` в процентах даёт новую сигнатуру на каждый процент хода);
- Соответствие `docs/SCOPE.md` (починка перф-дефекта в рамках J1/J7, не новая
  функция) и обоснованность small-трека (одна поверхность, геометрия/миграции
  не тронуты);
- К1 — единственная точка квантования (`passageStates`,
  `src/houseplan-card.ts:10352-10361` на момент r1) реально питает и
  сигнатуру, и длину выреза, и partition-cut — принцип «одно число — один
  источник» (§8 PROCESS.md) соблюдён архитектурно;
- К2 и математика квантования: сетка 0.05 на [0,1] даёт ровно 21 узел;
  `Math.round(clamp(x)/0.05)*0.05` даёт `0.30`/`0.31` → один и тот же узел,
  `0.30`/`0.33` → разные, `NaN/-1/2` → корректный зажим — проверено в r1
  прямым расчётом, формула в теле issue не менялась;
- AC1 (юнит на `quantizeOpeningLightAmount`), AC2 (≤21 сигнатура на свипе),
  AC3 (binary-двери байт-в-байт — квантование стоит выше
  `openingLightStateSignature`, существующие юниты её не заденут), AC5
  (мутант «квант → identity» красит AC2 детерминированно) — тексты AC1-3,5 не
  менялись между r1 и r2, проверка r1 остаётся в силе;
- Откат (один revert, кэш самоинвалидируется сигнатурой, конфиг не участвует)
  — текст не менялся;
- `User-Visible: yes` с обоими changelog — учтено верно (с оговоркой L2′ про
  `LIGHT.md` выше, которая новая для этого раунда).

## Что проверено и корректно (этот раунд)

- Обе Medium-находки r1 закрыты предметно: правка текста, а не риторическая
  переформулировка — проверено чтением файла-доказательства (`smoke_glow.mjs`)
  и текста добавленного абзаца допущения;
- Дерево `dev`, от которого зависела проверка r1, не двигалось — условие
  «разбор остаётся полным при ребейзе» неприменимо, сокращённый разбор
  правомерен;
- Новых Medium/High находок делта не создала.

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

- Код не написан — `typecheck`/`test`/`build`, `npm run golden:verify`,
  `node scripts/model-invariants.mjs`, смоки браузером — не мой гейт на этапе
  ревью ТЗ, предмет S7 (код-ревью). Дешёвые гейты не гонял: делта этого
  раунда — текст issue, `src/**` не тронут.
- Не проверял глазом визуальную неразличимость 5%-ступени в браузере —
  унаследовано из r1 как оценка правдоподобия, теперь явно помеченная в самом
  ТЗ как предположение с планом пересмотра, что и было целью M2.
- Не проверял, будет ли `docs/LIGHT.md` реально обновлён при реализации — это
  требование переносится на код-ревью (см. L2′).

## Вердикт

Обе блокирующие Medium-находки r1 закрыты по существу и проверяемо. Новых
находок делта не породила, кроме одной некритичной (L2′, footer расходится с
телом issue, снята с запиской). Технический контракт и AC остаются
доказуемыми в объёме, установленном r1. Issue готово к переходу в
`S5-ready`.