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

SPEC-REVIEW — issue #318 · заход r1

• Этап: spec (PROCESS.md §2.4)
• Артефакт ТЗ: docs/specs/318-empty-controller-roster.md (полный трек; docs/specs/README.md — строка добавлена)
• SHA ревью: 1242a3b1badf13a8785c7e176da2c3f765ccdad8 (ветка issue/318-switch-render-state, коммит "docs: specify empty-roster controller state", Issue: #318 · User-Visible: no — трейлеры корректны: коммит документальный, пользовательского поведения ещё не меняет)
• Заход: r1 · блокирующих циклов израсходовано 0 из 4

Скоуп

Issue #318: маркер физического беспроводного выключателя без единой собственной сущности registry (device: binding активен, own roster = [], controls: [light.wall_lights]) навсегда остаётся в приглушённой (unavailable) подаче независимо от состояния управляемой цели. Owner уже принял продуктовое решение в комментариях issue до написания ТЗ: активный физический device-binding с пустым собственным roster считается доступным и следует controls; непустой roster без единого живого состояния остаётся unavailable по контракту #251. ТЗ реализует это решение.

Трек — полный, обоснованно: меняется публичный UX-контракт (строка S05 таблицы решений docs/DEVICE-PRESENTATION.md), затронут общий presentation resolver на всех поверхностях (plan/preview/hosted Static). Названный критерий лёгкого трека, который задача не проходит, указан в самом ТЗ.

Затронутая подсистема: docs/DEVICE-PRESENTATION.md / docs/ARCHITECTURE.md (канон availability/status controller), плюс docs/USER-GUIDE.ru.md для пользовательской терминологии.

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

1. Прочитан docs/SCOPE.md — задача закрывает J1 («что происходит сейчас») и J3 («быстрое очевидное действие»); ложный сигнал недоступности прямо противоречит J1.
2. Прочитаны AGENTS.md, PROCESS.md §1–2.4, §4, §5, §7.1–7.3 — формат документа, обязательные разделы, бюджет циклов, критерий полного трека.
3. Прочитано тело issue #318 и все 4 комментария: заявка → анализ аналитика с продуктовым вопросом → решение владельца → хендофф автора ТЗ. Продуктовый вопрос был ровно один, и он закрыт до старта этого ревью.
4. Прочитан весь файл ТЗ docs/specs/318-empty-controller-roster.md (295 строк) целиком, раздел за разделом на соответствие §7.1.
5. Прочитаны канонические документы: docs/DEVICE-PRESENTATION.md (таблица решений, строки S03–S09), docs/ARCHITECTURE.md (цитаты «Yellow means working» из issue подтверждены как существующий канон), docs/USER-GUIDE.ru.md (раздел 12 «Визуальные состояния устройств», строки 958–1004 — текущая документированная формулировка, которую ТЗ обязано будет уточнить в коде).
6. Сверены с реальным кодом все технические утверждения диагноза (§3) и контракта (§6.1–6.3), а не приняты на веру:
   • controllerAvailability() (src/device-presentation.ts:208-217) — (d.entities || []).some(...) на пустом массиве безусловно даёт false → unavailable. Диагноз ТЗ («пустой список безусловно даёт unavailable») подтверждён чтением, не исполнением.
   • resolveHaBindingStatus() (src/ha-binding-status.ts:414-463) — ветка kind === 'device', allEntityIds.length === 0: isRegistryEntryEnabled(device) истинно (устройство активно), enabledEntityIds = [].filter(...) = [], условие allEntityIds.length && !enabledEntityIds.length ложно (первый операнд 0) → возвращается { kind: 'active', enabledEntityIds: [], allEntityIds: [] }. Это ровно сценарий #318 и ровно предикат §6.1 ТЗ («active», bindingKind === 'device', roster []). Подтверждено чтением.
   • Термины bindingKind, bindingStatus.kind (active/ha_disabled/ orphaned/unverified), DevItem.entities — все существуют в src/devices.ts, src/ha-binding-status.ts с ровно теми значениями, которые ТЗ им приписывает.
   • Идентификаторы тестовых артефактов из плана и AC — все существующие, не выдуманные: test/device-presentation.test.mjs (1092 строки), demo/smoke_wireless_controller_parity.mjs (162 строки), scripts/mutation-gate.mjs содержит мутанты controller-availability-follows-target, wireless-controller-loses-filtered-target-role, wireless-controller-preview-drops-sibling-markers (используются также в test/fixtures/device-presentation-decisions.mjs для S03/S05/S07).
   • docs/DEVICE-PRESENTATION.md строка S05 сегодня буквально гласит «цель работает, controller не имеет live entity → faded controller» — ТЗ §9 корректно называет её на разделение.
   • docs/USER-GUIDE.ru.md:979 и таблица строка 1000 сегодня документируют «отсутствуют» (нулевой roster) как один из триггеров бледного маркера — это ровно текст, который реализация обязана сузить; ТЗ §9 называет этот документ в списке правок, не давая финальной формулировки (корректно — формулировка не продуктовый факт, а редактура канона).
7. Проверено соответствие обязательного чек-листа docs/specs/README.md («Обязательные release-артефакты номерного ТЗ») — все четыре пункта закрыты разделами §9 и §15 ТЗ.
8. Проверено, что коммит на ветке ровно один, docs-only, класс C по AGENTS.md (не требует ревью само по себе, но здесь — часть DoD этапа spec), трейлеры корректны для docs-only коммита.

Гейты не гонялись: этап — ревью ТЗ, продуктового кода в диффе нет (класс C, только docs/**). Раздел «чего не проверял» — ниже.

Находки

Нет. Ни одной High- или Medium-находки.

Проверены типичные классы дефектов спек-ревью и не обнаружены:

• Догадка, выданная за факт. Не найдена: единственный продуктовый вопрос (эмпти-roster active device = доступен?) задан аналитиком и решён владельцем до старта написания ТЗ (комментарии от 12:37 и 12:42). §16 ТЗ содержит явный блок «принято предположительно, поменять свободно» ровно для технических, не продуктовых решений (расположение предиката, отсутствие нового enum, ID decision trace) — как и требует §7.1.
• Отсутствие открытого вопроса при сложной задаче. Вопрос был; он снят корректно, до, а не во время написания ТЗ.
• Несуществующие идентификаторы/файлы в AC и плане. Все имена функций, тестовых файлов и mutation ID существуют в дереве репозитория (см. выше).
• Расхождение с каноном подсистемы. Диагноз и предлагаемое правило не противоречат ни одному существующему решению таблицы S01–S09; #251 и #274 явно сохранены как негативные тесты (AC3, AC4).
• Нарушение SCOPE.md. Изменение — узкое исправление существующего J1/J3 сценария, не расширяет функциональность и не вводит новый визуальный элемент (§5 «Не входит» явно запрещает новый badge/glyph/pulse/цвет/текст).
• Единое число, два источника. Неприменимо: изменение касается только availability/цвета подложки, не вводит и не дублирует числовое значение.
• Отсутствие раздела §7.1. Все обязательные разделы присутствуют: сценарий и персона (§1), что человек увидит до/после (§2), проблема (§3), скоуп/не-скоуп (§5), контракт поведения (§6), UX (§7), модель данных/миграция (§8), i18n (§9), AC1–AC9 с доказательствами (§10), план автотестов (§11), перф/безопасность (§12), риски (§13), откат (§14), release-артефакты (§15).
• Владельцу вынесен технический вопрос под видом продуктового. Не найдено: единственный заданный вопрос («считать ли активный device-binding без сущностей доступным») — ровно продуктовый по определению §7.1 (что человек видит).

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

• Формат документа, нумерация разделов, наличие всех обязательных пунктов §7.1 PROCESS.md.
• Трек задачи (полный) обоснован названным критерием, а не молчаливым умолчанием.
• Диагноз причины (§3 ТЗ) — подтверждён построчным чтением controllerAvailability() и resolveHaBindingStatus(), соответствует фактическому коду один в один.
• Предикат «active physical device binding» (§6.1) — реализуем на существующих полях (bindingKind, bindingStatus.kind, d.virtual), не требует новых данных.
• Матрица §6.2 непротиворечива и покрывает все девять комбинаций binding×roster×target из отдельного анализа, включая явно исключённые virtual/ha-disabled/orphaned строки.
• Скоуп/не-скоуп (§5) точно очерчивает границу: entity-bound markers, registry-как-online-для-непустого-roster, новый visual vocabulary — всё явно исключено, что закрывает главный риск (широкое ослабление контракта #251).
• AC1–AC9 каждый называет способ доказательства через существующий или явно спланированный тестовый механизм (unit, production-bundle smoke, mutation-gate, diff audit), ни один не оставлен голословным.
• Release-артефакты (§15) и обязательный чек-лист docs/specs/README.md закрыты: changelog RU/EN, список затронутой пользовательской документации, явное заявление об отсутствии новых screenshot/golden baseline при условии зелёных существующих сьютов.
• Откат (§14) описан и не требует обратной миграции данных, так как модель/ конфигурация не меняются (§8 подтверждён отдельно).
• Ветка, коммит и трейлеры соответствуют AGENTS.md: issue/318-switch-render-state, один docs-only коммит, Issue: #318 + User-Visible: no, SHA хендоффа (1242a3b) совпадает с фактическим HEAD.

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

• Гейты typecheck/test/build/bundle:sync/bundle:budget/check-docs — не гонялись. На этом этапе в диффе нет ни одного файла класса A/B/D (только docs/specs/**), продуктовый код не менялся, гонять их бессмысленно: они проверяют код, которого ещё нет. Ссылка на зелёный Validate 1242a3b1 (https://github.com/Matysh/houseplan-card/actions/runs/33172444930) относится к этому же SHA и подтверждает, что репозиторий в целом зелёный, но это не подменяет проверку самого ТЗ — она сделана вручную чтением.
• Смоки, golden, mutation-gate, invariants — не прогонялись и не должны: это план на этап реализации (§11 ТЗ), сейчас проверяется только существование названных файлов/идентификаторов, не их поведение под ещё не написанный код.
• Финальная формулировка правок канона (DEVICE-PRESENTATION.md S05, ARCHITECTURE.md, USER-GUIDE.md/USER-GUIDE.ru.md, TESTING.md) — ТЗ правомерно откладывает точный текст на этап реализации; проверено только, что список затронутых документов полон и совпадает с реальными текущими формулировками, которые придётся менять (см. «Как проверялось», пункт 6).
• UI/браузер — на этапе ревью ТЗ ручного тестирования нет по определению этапа; кода для проверки не существует.

Унаследовано из r

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

Вердикт

Зелёный. Спецификация полна по §7.1, продуктовый вопрос закрыт владельцем до написания, технический диагноз и контракт проверены построчным чтением кода и совпадают с реальностью, скоуп/не-скоуп корректно ограничивают риск ослабления контракта #251, AC доказуемы существующими или явно запланированными механизмами. High: 0. Medium: 0.