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

SPEC-REVIEW-267-r1

• Issue: https://github.com/Matysh/houseplan-card/issues/267
• Этап: ТЗ на ревью (PROCESS.md §2.4)
• Заход: r1 · блокирующих циклов израсходовано 0 из 4 (первый заход)
• Материал: docs/specs/267-device-presentation-decision-table.md на SHA c5e14526 (ветка issue/267-device-presentation-table), плюс тело issue и два комментария («Аналитика», «ТЗ готово к независимому ревью»)
• Вердикт: зелёный

Скоуп ревью

Первый заход — разбор полный. Проверялось:

1. соответствие docs/SCOPE.md (какой Core user job закрывает задача);
2. обязательные разделы ТЗ по PROCESS.md §7.1 и однозначность/доказуемость каждого AC;
3. отсутствие догадок, выданных за факт — каждое «зафиксированное продуктовое решение» (§3 ТЗ) сверено с первоисточником (docs/USER-GUIDE.ru.md §12, issue #251/#274/#98) построчно;
4. измеренная база (строки/ветвления/имена функций) сверена с текущим src/device-presentation.ts на HEAD;
5. технические допущения (§20 ТЗ) — что помечено как «можно менять на ревью», не выдано за продуктовое решение;
6. инструменты, на которые ссылается план тестов (scripts/mutation-gate.mjs --check/--id=, scripts/smoke-select.mjs, существующие smoke-файлы), существуют и поддерживают заявленный интерфейс.

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

Что	Команда/действие	Результат
Класс изменения коммита	git show --stat HEAD	только docs/specs/267-*.md + docs/specs/README.md — класс C, соответствует заявленному в шапке ТЗ
Измеренная база §2 ТЗ	wc -l src/device-presentation.ts, grep -n на resolvePresentationSources/resolveDevicePresentation	781 строка, функции на строках 252→404 (152) и 600→781 (181) — совпадает с заявленными 781/152/182
Существование смежных модулей §7.2	ls src/device-*.ts	device-visual.ts, device-pulse.ts, device-value-badge.ts, device-face.ts, device-toggle.ts — все существуют, как заявлено
Соответствие §3.2 (#251)	чтение docs/USER-GUIDE.ru.md:914-921	текст руководства слово в слово подтверждает решение (доступность контроллера только по своим сущностям, виртуальный контроллер доступен)
Соответствие §3.3 (#274)	чтение docs/USER-GUIDE.ru.md:922-924	подтверждено: удалённая цель не делает контроллер недоступным и не расходит план/preview
Соответствие §3.4 (#98, пульсации)	чтение docs/USER-GUIDE.ru.md:945-963	подтверждено: обычная пульсация только в «Значок + состояние и активность», статичных колец нет
Соответствие §3.5 (static_icon)	чтение docs/USER-GUIDE.ru.md:1007-1014	подтверждено дословно, включая исключение hover/controls/Glow/заливки
L05 (hidden_design_preview) не выдумка	grep -rn hidden_design_preview src/ test/	строка уже существует в device-presentation.ts:87,728, i18n/ru.json:236, покрыта test/device-presentation.test.mjs:751 — существующее поведение, не новая догадка
F09–F12 (value fallback reasons)	grep -rn value_ambiguous_sources|value_virtual|activity_display_disabled	все три reason уже в коде и тестах
F16 (LQI-полосы 0/40, 41/179, 180+)	чтение markerLqiBand() (device-presentation.ts:46-49)	точное совпадение границ
Инструмент mutation-gate.mjs --id=/--check	grep -n "'--check'" , grep -n "startsWith('--id="	оба флага существуют и поддерживаются
Смоки, названные в ТЗ	ls demo/smoke_*.mjs | grep -E "wireless|device_icon"	smoke_wireless_controller_parity.mjs, smoke_device_icon_design.mjs существуют
Легаси-совместимость ripple→icon_ripple (§13)	чтение normalizeDeviceDisplay() (src/logic.ts:852-856)	подтверждено дословно
Связанные issues реальны и закрыты	gh issue view 98/251/274/34	#98, #251, #274 закрыты и по теме совпадают с описанием в ТЗ; #34 открыт как архитектурный umbrella — корректная ссылка, не блокирующая зависимость
Уникальность decision row ID	grep по ^| L0|^| S0… + uniq -d	дубликатов ID нет (30 строк: 6 L, 13 S, 17 F, 8 A)
Порядок приоритета §7.3 vs реальный код	чтение resolveDevicePresentation() целиком (device-presentation.ts:600-781)	заявленный порядок (lifecycle → static → alarm переживает live-gate → live-gate → controller availability → …) соответствует фактической последовательности веток в текущей реализации — не выдумана «идеальная» модель без связи с кодом
Индекс docs/specs/README.md	git diff HEAD~1 HEAD -- docs/specs/README.md	строка #267 добавлена в том же коммите, ссылка верна
node scripts/check-docs.mjs	прогнан	Documentation checks passed (7 files, 10 external links) — зелёный
git diff --check на коммит спеки	git diff --check HEAD~1 HEAD -- docs/specs/267-*.md	не зелёный: 548: new blank line at EOF (см. находки, Low)

Гейты typecheck/test/build не гонялись: коммит c5e14526 — чистый класс C (только docs/specs/**), продуктовый код не менялся, src/** не тронут, и check-docs.mjs (который зависит от src/**) уже прогнан и зелёный. Браузерные смоки, golden, инварианты геометрии, backend-тесты — неприменимы: diff не касается src/**/custom_components/** в этом заходе, это ещё не реализация.

Находки

Low-1 — заявление «git diff --check — green» в хендоффе не совпадает с фактом

Файл: issue #267, комментарий «ТЗ готово к независимому ревью» (2026-08-27T18:17:33Z).

Автор указал git diff --check как один из двух прогнанных чеков и заявил результат «green». Повторный прогон git diff --check HEAD~1 HEAD -- docs/specs/267-device-presentation-decision-table.md даёт 548: new blank line at EOF (файл заканчивается двумя переводами строки вместо одного), exit code 2. Само по себе это не искажает содержание ТЗ и не влияет ни на один AC — check-docs.mjs, единственный настоящий гейт для доков в этом диффе, зелёный. Но правило «"Verified" без названного результата не является доказательством» работает в обе стороны: названный результат должен быть точным. Ложноположительный «green» в хендоффе — ровно тот тип записи, который процесс просит не допускать.

Решение ревьюера: снимается без правки. Косметическая лишняя пустая строка в конце файла, не блокирует переход в S5-ready; будет естественно убрана следующим коммитом по ветке (код или доп. правка спеки), отдельного возврата на цикл не оправдывает.

Что не является находкой (проверено и отклонено как ложное подозрение)

• Отсутствие отдельных заголовков «UX» и «Модель данных и миграция». PROCESS.md §7.1 требует эти темы по содержанию, а не буквальным заголовком. Содержание есть: §1 «Что человек увидит» прямо формулирует отсутствие видимых изменений, §12 не-скоуп явно исключает новые статусы/цвета/иконки/ display-режимы, §13 явно закрывает данные/миграцию («отсутствуют», normalizeDeviceDisplay() остаётся read-gate). Прецедент того же жанра задач — docs/specs/264-resize-controller.md — построен по не идентичному, но сопоставимому по духу набору разделов. Не находка.
• «Открытых продуктовых вопросов нет» при сложности 7/10. Проверено предметно, а не на слово: все три продуктовых вопроса из тела issue («что видит человек при доступном контроллере/недоступной цели», «приоритет осей при конфликте», «сколько состояний имеет право быть различимыми») закрыты ссылкой на уже принятые решения (#251, #274, USER-GUIDE §12) и на явный не-скоуп «новых статусов/цветов/иконок нет» — это не отказ отвечать, а предметный ответ «поведение не меняется, только структура кода». Для refactor-only задачи с зафиксированным контрактом это корректно, а не недосмотр.
• Достижимость AC2 («renderer и surfaces не принимают альтернативных решений по raw HA state»). В houseplan-card.ts действительно остаются прямые обращения к hass.states[...] (vacuum-телеметрия, friendly_name для подписей/тултипов, состояние contact/lock для соседних, не face-related элементов). AC2 ограничен явно: «Lifecycle/display/status/content/ diagnostics gates из resolveDevicePresentation()» — то есть про вынос уже существующих внутри функции веток, а не про полный запрет чтения hass.states во всём файле. Формулировка не создаёт невыполнимое требование.

Проверка обязательных разделов (PROCESS.md §7.1)

Сценарий и персона (§1) — есть, персона из docs/SCOPE.md (домашний администратор + разработчик как второй адресат документа). Что человек увидит до/после (§1) — есть, явно «ничего нового». Проблема (§2) — есть, с измеренной и подтверждённой базой. Скоуп/не-скоуп (§11/§12) — есть, не-скоуп явно закрывает риск декартова произведения и попутных продуктовых изменений. Контракт поведения — распределён по §3 (зафиксированные решения) и §6 (таблицы рядов), содержательно присутствует. UX/данные и миграция — покрыты содержательно (см. «что не является находкой» выше). i18n — явно «нет новых строк» (§13), проверено: задача не должна трогать src/i18n/*.json, её и не трогает вне ТЗ. AC1…AC10 — пронумерованы, у каждого указан способ доказательства (§15). План автотестов — есть (§16), с точным списком команд перед S7. Риски — есть (§18), адресуют именно те риски, которые релевантны этому рефакторингу (декартово произведение, второй resolver, plan/preview расхождение, регрессия pixel-parity). Откат — есть (§19), корректен для чисто структурного рефакторинга без миграции. Release-артефакты — есть (§17), корректно User-Visible: no.

Проверка AC на однозначность и доказуемость

Каждый из AC1–AC10 формулирует наблюдаемое или механически проверяемое условие и называет способ доказательства (unit/architecture test/mutation registry/smoke/golden/code review), без AC вида «работает корректно» без критерия. AC4 и AC5 образуют закрытую петлю «документ ↔ fixture ↔ mutant», которая явно защищает от того самого дрейфа, ради которого затевается задача (документ описывает желаемое, а не то, что тест умеет проверить). AC8 — единственный жёсткий pixel/config-контракт рефакторинга — корректно замкнут на существующий golden:verify и docs screenshot gate, а не на новое самодельное сравнение.

Отдельно проверено на воспроизводимость до кода: порядок приоритетов §7.3 не является постулированной автором целевой моделью, оторванной от реальности — он совпадает с фактической последовательностью условий в resolveDevicePresentation() на HEAD (эффективная скрытость → static → alarm переживает live-gate → live-gate → controller availability → value/icon/pulse). Это значит рефакторинг, скорее всего, реализуем без скрытого изменения поведения, а не переписывает контракт под видом документирования.

Унаследовано / предыдущие раунды

Неприменимо — это первый заход (r1) по этому этапу.

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

• Реализацию (класс A/B) — её ещё нет, диапазон S3-spec/S4-spec-review правок кода не касается.
• typecheck/npm test/npm run build/браузерные смоки/golden/инварианты геометрии/backend — неприменимы к чисто документационному коммиту этого захода; будут обязательны на код-ревью.
• Реальную достижимость AC9 (O(1) policy) и AC7 (surface parity) на уровне производительности/поведения — это утверждения о будущей реализации, доказываются на код-ревью, а не на этапе ТЗ.
• Полноту декомпозиции §6 (все ли нужные строки перечислены, не пропущена ли комбинация) — не пересчитывал декартово произведение осей вручную; проверил выборочно, что перечисленные строки соответствуют реальным веткам кода и реальным issue-регрессиям (#251, #274), и что ID уникальны. Полнота набора рядов — предметная (product) оценка автора и владельца, а не то, что ревьюер ТЗ обязан пересчитать с нуля при отсутствии признаков пропуска.