docs: review document for #375

Issue: #375
User-Visible: no

docs/reviews/SPEC-REVIEW-375-r2.md

@@ -0,0 +1,179 @@
+# SPEC-REVIEW-375-r2
+
+Issue: [#375](https://github.com/Matysh/houseplan-card/issues/375) — «Glow в space-card: static-путь потерял кэш-иерархию полной карты»
+Этап: spec (ревью ТЗ, PROCESS.md §2.4) · трек: `small` (лёгкий, ТЗ в теле issue)
+Заход: r2 · блокирующих циклов израсходовано 1 из 2 (лимит лёгкого трека — 2, §4)
+
+## 1. Скоуп проверки
+
+Раунд r1 (см. ниже) уже прочитал ТЗ целиком и построчно перепроверил все четыре
+диагноза (К1–К4/V6a–V6d) и AC1–AC6 чтением `dev` на момент r1. Единственная
+блокирующая находка r1 — отсутствие обязательного раздела «Откат» (Medium, в
+скоупе) плюс два Low-примечания DoR (миграция/compatibility, touch).
+
+Автор ответил правкой тела issue (комментарий Matysh, 2026-08-29T17:46:02Z,
+«Редакция 2», возврат в `S4-spec-review`). Дельта r1→r2 **полностью локальна**:
+это единственная правка тела issue между вердиктом r1 и текущим моментом (см.
+§2 ниже) — не ребейз, не смена контракта, не новая подсистема. По правилу §2.10
+разбор в r2 сужен до дельты; AC1–AC6, продуктовая рамка (сценарий, объём К1–К4)
+и анализ поверхностей унаследованы из r1 без повторной проверки (раздел 4).
+
+## 2. Метод: как восстановлена дельта
+
+Вердикт r1 (комментарий `claude`, 2026-08-29T17:43:11Z) **не называет SHA/ревизию
+тела issue**, на которой он получен — это ровно та находка, которую фиксирует
+PROCESS.md §2.10 п.1 («SHA в вердикте не назван — это находка»). Для issue-body
+ТЗ прямого эквивалента git SHA нет, поэтому состояние восстановлено через историю
+редактирования тела issue (GitHub GraphQL `userContentEdits`, 3 записи правок):
+
+- edit `2026-08-29T17:25:45Z` — первая редакция ТЗ (аналитика → ТЗ);
+- edit `2026-08-29T17:32:37Z` — «редакция 1», ровно то состояние, которое получило
+  вердикт r1 (комментарий вердикта идёт сразу за этой правкой, до следующей);
+- edit `2026-08-29T17:46:01Z` — «редакция 2», правка **сразу после** вердикта r1
+  и **до** комментария автора «Возвращаю S4» (17:46:02Z) — это и есть материал r2.
+
+`diff` между снимком 17:32:37Z (r1) и снимком 17:46:01Z (r2), сверенным построчно:
+
+```diff
+-# ТЗ (лёгкий трек, редакция 1)
++# ТЗ (лёгкий трек, редакция 2)
+...
+-## 7. Принятые предположения
++## 7. Откат
++
++Обычный `git revert` одного коммита: фича-флагов нет, миграций нет, персистентных
++данных нет (все четыре правки — кэши в памяти страницы и non-enumerable свойство
++на объекте в памяти). Откат возвращает прежнюю (медленную, но корректную)
++картину; parity сцен не зависит от направления.
++
++**DoR-примечания:** миграция/compatibility — нет (ни одного изменения хранимых
++форматов или WS-контрактов); touch — не влияет (`docs/TOUCH-SUPPORT.md` не
++задет: правки не касаются ввода).
++
++## 8. Принятые предположения
+ ...
+```
+
+Других расхождений нет (сверено дифф-инструментом построчно; единственная
+дополнительная разница — завершающий перевод строки, не содержательна). Живое
+тело issue (`gh issue view 375 --json body`) на момент этого ревью побайтово
+совпадает со снимком правки 17:46:01Z — после «редакции 2» issue больше не
+редактировался.
+
+## 3. Закрытие раунда r1
+
+| Находка r1 | Чем закрыта | Где видно |
+|---|---|---|
+| Medium (в скоупе): отсутствует обязательный раздел «Откат» (`AGENTS.md`/`PROCESS.md` §5, DoR §2.5) | Добавлен раздел `## 7. Откат` с описанием отката (`git revert`, нет флагов/миграций/персистентных данных) | Тело issue, между «## 6. i18n / Release-артефакты» и (переномерованным) «## 8. Принятые предположения»; правка тела issue 2026-08-29T17:46:01Z |
+| Low: DoR-пункт «миграция/compatibility» не закрыт явным «нет» | Строка «миграция/compatibility — нет (ни одного изменения хранимых форматов или WS-контрактов)» | Тот же раздел «## 7. Откат», подпункт «DoR-примечания» |
+| Low: DoR-пункт «влияние на touch» не закрыт явным «нет» | Строка «touch — не влияет (`docs/TOUCH-SUPPORT.md` не задет: правки не касаются ввода)» | Там же |
+
+Обе Low-находки и Medium-находка закрыты текстом, а не заявлением: раздел
+присутствует в теле issue дословно, как процитировано выше.
+
+Проверка правдивости добавленных утверждений (не принимается на слово, т.к. это
+новый текст, ранее не читанный ни одним раундом):
+
+- «миграция/compatibility — нет»: сверено с `docs/CONFIG-COMPATIBILITY.md` —
+  реестр посвящён персистентным полям конфига (`space.wall_segments[]`,
+  `expected_rev` и т.д.); ни один из четырёх пунктов К1–К4 (кэш light-графа,
+  `sourceFingerprint` на geometry-объекте, LRU барьерной сцены, кэш
+  `enabledClip`) не касается хранимого формата конфига или WS-контракта записи
+  — это внутримодульные in-memory кэши. Утверждение верно.
+- «touch — не влияет»: сверено с `docs/TOUCH-SUPPORT.md` — документ описывает
+  политику указателя/hover и editor-vs-View контракт; ни один из К1–К4 не
+  меняет обработку ввода или рендер, видимый пользователю (ТЗ прямо заявляет
+  «видимых изменений нет — только скорость»). Утверждение верно.
+
+## 4. Унаследовано из r1
+
+Без повторной проверки в r2 приняты (документ и ревизия, на которой получен
+вывод — см. §2 выше, снимок правки issue `2026-08-29T17:32:37Z`; отдельного
+файла `docs/reviews/SPEC-REVIEW-375-r1.md` в рабочем дереве на момент этого
+раунда нет — по механике этого конвейера публикующий шаг кладёт его в
+`docs/reviews/` уже после вердикта, из `REVIEW_DOC` предыдущего раунда; текст
+вердикта процитирован по комментарию issue):
+
+- Все четыре диагноза К1–К4 (V6a–V6d) — не догадка, каждая строка/тест/бюджет
+  подтверждён чтением `dev` на строках `glow-scene.ts:177,319`,
+  `space-render.ts:113-129,501-510,654-671`,
+  `houseplan-card.ts:8455-8461,1815,10267,10296,9383-9393`, `devices.ts:426,602-606`.
+  Дельта r2 не касается этих строк и не меняет ни один из диагнозов — переверять
+  нечего.
+- AC1–AC6 пронумерованы, проверяемы, доказательства названы (`unit`/мутанты),
+  AC6 корректно привязан к AC1/AC3. Дельта r2 не трогает раздел «3. AC» — ни
+  одной строки в диффе выше.
+- Продуктовая рамка (раздел «1. Сценарий», «2. Объём») и анализ поверхностей
+  (комментарий аналитики 2026-08-29T17:31:53Z) — не задеты диффом.
+- Раздел «4. План тестов» и «5. Риски» — не задеты диффом.
+
+## 5. Проверка обязательных разделов (§7.1) — после правки
+
+Полный набор для лёгкого трека (issue-тело): проблема · контракт · AC1…ACn с
+доказательством · откат. Все на месте после «редакции 2»:
+
+- проблема — «## Суть» + «## 1. Сценарий»;
+- контракт — «## 2. Объём» (К1–К4) + «## 1. Сценарий», последняя фраза
+  («видимых изменений нет... parity сохраняется байт-в-байт»);
+- AC1…AC6 с доказательством — «## 3. AC»;
+- откат — «## 7. Откат» (новое).
+
+DoR-чеклист (§2.5) теперь закрыт полностью явными «нет»/значениями по каждому
+пункту: миграция/compatibility, touch, i18n (§6: «не задето»), перф (AC5 +
+план тестов: «бюджет дельта ≈ 0»), release-артефакты (§6: changelog RU+EN),
+риски (§5), открытых продуктовых вопросов нет (раздел «8. Принятые
+предположения» — верно оформлен как предположения, а не как замаскированный
+продуктовый вопрос: обе позиции — технические решения по конкретике
+реализации, ревьюер вправе их оспорить и не оспаривает, см. ниже).
+
+Проверка «Принятые предположения» (§8, ранее §7) на «догадка выдана за
+решение»: обе позиции — LRU-ёмкость 8 (зеркалит существующий `_lightBarrierPool`
+полной карты, значение не придумано, а взято из уже работающего кода) и
+включение К4 в этот же issue (соседняя дешёвая правка, без продуктового
+компонента) — корректно оформлены как технические допущения. Продуктовых
+вопросов, которые должны были уйти владельцу, в тексте нет.
+
+## 6. Находки этого раунда
+
+Блокирующих (High) находок нет. Medium в скоупе — нет: обе находки r1 закрыты
+текстом, а не декларацией (§3). Новых находок делта не вносит.
+
+Единственное наблюдение процесса (не находка задачи, не блокирует): вердикт r1
+не назвал явный якорь ревизии тела issue, на которой он получен (§2.10 п.1,
+формально применимо и к этапу spec). Дельта тем не менее восстановлена
+однозначно через историю правок GitHub (`userContentEdits`) — три
+последовательные правки с точными таймстемпами и полными снимками текста, зазор
+между вердиктом r1 (17:43:11Z) и следующей правкой (17:46:01Z) не оставляет
+неоднозначности, какое состояние ревьюер r1 оценивал. Дальнейшего действия не
+требует; фиксирую как процессное наблюдение на будущее для ревьюеров spec-этапа.
+
+## 7. Что проверено и корректно
+
+- Раздел «Откат» присутствует, содержателен, соответствует факту (нет флагов,
+  нет миграций, нет персистентных данных — все четыре правки К1–К4 действительно
+  ограничены in-memory кэшами и non-enumerable свойством, что подтверждено ещё
+  в r1 построчным чтением кода).
+- Оба DoR-примечания (migration/compatibility, touch) фактически верны — сверено
+  с `docs/CONFIG-COMPATIBILITY.md` и `docs/TOUCH-SUPPORT.md` в этом раунде.
+- Дельта r1→r2 локальна, не касается AC, объёма, рисков, плана тестов —
+  дальнейшая проверка этих разделов из r1 наследуется законно.
+- Issue сохраняет метку `small`, критерии лёгкого трека (§5 PROCESS.md) не
+  нарушены правкой (правка добавляет только процессный раздел, не меняет
+  поверхность/риск/сложность).
+
+## 8. Чего не проверял и почему
+
+- Код (`src/glow-scene.ts`, `src/space-render.ts` и т.д.) — не применимо на
+  этапе spec: реализация ещё не начата, issue не покидал `S3/S4`, кода по этому
+  issue в `dev` нет. Гейты `tsc`/`test`/`build`/смоки/инварианты модели относятся
+  к этапу code-review (§2.7, §8 PROCESS.md) и будут прогнаны там.
+- Повторное построчное чтение `dev` под K1–K4 — не требовалось: дельта r1→r2 не
+  касается этих строк, диагнозы уже перепроверены в r1 (§4).
+- Содержательный технический спор с ревьюером r1 по поводу самих AC — предмета
+  для спора нет, дельта его не вносит.
+
+## 9. Вердикт
+
+Зелёный. Обе находки r1 закрыты текстом по месту, дельта локальна и не вносит
+новых находок, обязательные разделы ТЗ (§7.1) и DoR-чеклист (§2.5) закрыты
+полностью. Issue готово к переходу в «Готово к разработке» (`S5-ready`).