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

# SPEC-REVIEW-178-r2

- **Issue:** https://github.com/Matysh/houseplan-card/issues/178
- **ТЗ:** [`docs/specs/178-toggle-entity.md`](../specs/178-toggle-entity.md)
  (commit `76f75f85aafabcf9f698c85de0185e2ee64a98b5`, ветка `issue/178-toggle-entity`)
- **Ревьюер:** Claude (ревью ТЗ ≠ автор), этап `S4-spec-review`, сессия без
  контекста написания ТЗ и без контекста r1
- **Цикл:** r2/4 (обычный трек — issue не `small`/`trivial`; метки `P1`,
  `feature`, `S4-spec-review`)

## Скоуп ревью

Повторное ревью ТЗ #178 после красного вердикта r1 (High-1: отсутствовали
обязательные разделы «Риски», «Откат», `Touch editor: …`,
«Производительность»; Low-1: AC без инлайн-привязки к способу доказательства).
Автор внёс правки коммитом `76f75f8` (`docs: address review of toggle entity
spec`) — только документация, продуктовый код не менялся:
`git diff origin/dev...HEAD --stat` показывает изменения только в
`docs/reviews/SPEC-REVIEW-178-r1.md`, `docs/specs/178-toggle-entity.md`,
`docs/specs/README.md`. Задача — проверить (а) что оба High/Low из r1
действительно закрыты по существу, а не только по названию раздела, (б) что
переразметка секций (§14→§18, вставка новых §14–17) не сломала внутренние
ссылки и нумерацию AC↔тестов, (в) что новый текст не содержит догадок,
выданных за факты, (г) что документ в целом снова проходит §7.1/§2.5
целиком, а не только по пункту, который был назван в r1.

Не в скоупе: реализация — её по-прежнему нет (тот же `git diff` подтверждает
пустой `src/**`/`custom_components/**/*.py`), поэтому код-ревью не
проводилось и не должно.

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

1. `docs/SCOPE.md`, `AGENTS.md`, `PROCESS.md` целиком (§1, §2.4, §2.5, §5,
   §7.1, §7.2, §8) — независимо от r1, в свежей сессии.
2. Issue #178: тело, комментарий аналитики владельца, «взял в работу», «ТЗ
   готово», вердикт r1, комментарий автора о внесённых правках.
3. `docs/reviews/SPEC-REVIEW-178-r1.md` целиком — что именно требовалось
   исправить и какими словами.
4. `git diff e46ef6f..76f75f8 -- docs/specs/178-toggle-entity.md` — построчный
   дифф, чтобы увидеть ровно то, что изменилось (только вставка §14–17,
   переразметка §14→§18/§15→§19/§16→§20, добавление «Доказательство:» к
   каждому пункту §19).
5. Текущий полный текст `docs/specs/178-toggle-entity.md` (76f75f8) целиком,
   не только новые разделы — иначе есть риск подтвердить фикс формально и не
   заметить, что старые разделы стали противоречить новым.
6. Перекрёстные ссылки `§N.M` по всему файлу (`grep -n "§[0-9]"`) — проверено,
   что после переразметки не осталось ссылок на устаревшие номера разделов
   (например, старое «§14» тестового контракта не должно указывать на новый
   «§14 Touch»). Не осталось ни одной.
7. `docs/TOUCH-SUPPORT.md` целиком — точная формулировка обязательной строки
   (`Touch editor: supported/best effort/intentionally degraded/not exposed`,
   строки 147–151) и смысл «best-effort editors» / «safety floor».
8. `docs/CONFIG-COMPATIBILITY.md` (раздел `marker.light_entity`, строки
   176–191) — сверка формулировок §16 «Откат» ТЗ (lossless doctrine, «старый
   frontend стирает только при реконструкции marker») с уже принятым каноном
   для прецедентного поля.
9. Прецедентные ТЗ этого формата — `docs/specs/174-linked-virtual-light-controller.md`,
   `docs/specs/164-washer-active-cycle.md`, `docs/specs/084-passive-forced-light-sources.md`,
   `docs/specs/068-help-affordance.md` — как канон формулирует touch-строку и
   секцию рисков/отката/performance на практике, и есть ли прецедент отдельной
   декларации `Touch editor: supported` для одного конкретного контрола
   внутри в целом best-effort редактора (есть, #068: «поддерживается для
   самого affordance»).
10. Выборочная сверка новых технических утверждений §15.1 с реальным кодом:
    `src/devices.ts:317-325` (`ownControllableEntities`) — подтверждено, что
    функция работает по `d.entities` одного устройства (`Array.filter`,
    `Set`), без глобального обхода registry; заявление «линейно по числу
    сущностей одного устройства, без global registry scan» — не догадка, а
    факт, подтверждённый чтением кода.
11. `docs/specs/README.md:98` — трассируемость issue↔ТЗ не нарушена правкой.

Гейты (`typecheck`/`test`/`build`) не прогонялись — на этапе ревью ТЗ
продуктового кода нет, что подтверждено пустым диффом по классам A/B
(PROCESS.md §2.7/§8 относят гейты к код-ревью, не к ревью ТЗ).

## Находки

### Low-2 — раздел touch не называет явно runtime-эффект на View/kiosk

**Файл:** `docs/specs/178-toggle-entity.md:336-348` (§14 «Touch и
accessibility»).

`docs/PROCESS.md` §2.5 требует «влияние на touch по `docs/TOUCH-SUPPORT.md`
(**View и киоск — блокирующие**)». §14 разбирает только диалог устройства
(редактор): native `<select>`, отсутствие жестов на плане, безопасность на
узкой ширине. Но #178 меняет не только UI редактора — §10/§11 меняют, какая
именно собственная сущность получает `homeassistant.turn_on/turn_off` при
обычном тапе по маркеру в **View**, то есть именно тот путь, для которого
`docs/TOUCH-SUPPORT.md` называет touch/kiosk release-blocking, а не best
effort. Раздел не говорит явно, что резолвинг цели и вызов сервиса идентичны
независимо от типа указателя (touch tap vs mouse click) и поэтому у View/kiosk
нет отдельного touch-риска — этот вывод верен (executable-путь `resolveEntity`
не различает источник события), но в документе он не сформулирован, а
прецеденты #164 (§11) и #174 (§12) для похожих runtime-изменений явно пишут
такую строку («Touch View и kiosk: полностью поддержаны и release-blocking»).

**Воспроизведение неоднозначности:** код-ревьюер, ищущий в ТЗ ответ «есть ли
touch-риск в View из-за этой правки», найдёт только раздел про диалог
редактора и должен восстанавливать вывод о View самостоятельно по §10–§11,
а не прочитать его прямо, как в прецедентах.

**Вердикт:** не блокирует. Технического риска нет — резолвер целиком
device/pointer-независим, что подтверждено чтением `src/device-toggle.ts`
(`resolveEntity`, `resolveOwnEntity`, вызываемые из общего `_cardToggle` пути
без учёта типа указателя). Снимаю с запиской: при реализации короткая фраза
«View/kiosk: не затронуты, resolver и service call одинаковы независимо от
типа указателя» в §14 закрыла бы это ощущение неполноты и избавила бы код-
ревью от необходимости восстанавливать вывод самостоятельно.

Других находок, включая High и Medium, не обнаружено.

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

- **High-1 (r1) закрыт по существу, не только по названию.** Новые §14
  (Touch и accessibility), §15.1 (Производительность), §15.2 (Security),
  §15.3 (Риски и меры), §16 (Откат), §17 (Release-артефакты) реально
  присутствуют, содержательны и не являются пустыми заглушками:
  - §14 содержит буквальную канон-строку `Touch editor: supported` —
    формат совпадает с требованием `docs/TOUCH-SUPPORT.md:147-151` и с
    прецедентом #068 (декларация для конкретного контрола внутри в целом
    best-effort редактора);
  - §15.3 — таблица из 6 рисков, каждый с мерой и ссылкой на конкретный
    тест/раздел, плюс явная оценка остаточного риска («низкий/средний»);
  - §16 — откат без миграции, включая явный запрет автоматически
    переписывать `toggle_entity` в другие поля при откате;
  - §17 — release-артефакты перечислены (changelog RU+EN, USER-GUIDE,
    CONFIG-COMPATIBILITY, golden matrix), с явной оговоркой, почему новый
    performance budget/security report не создаются (hot path и API surface
    не расширяются — подтверждено §15.1).
- **Low-1 (r1) закрыт полностью.** Все 12 пунктов §19 (Acceptance criteria)
  теперь несут инлайн **«Доказательство:»** с точными номерами
  `unit §18.1.N` / `smoke §18.2.N` / `golden §18.3` / «code review diff» /
  «commit trailers/process gate». Сверено вручную AC↔тест для каждого из 12
  пунктов — расхождений или AC без реального покрывающего теста не найдено
  (AC8, к примеру, корректно указывает на §18.1.10, а не на первый попавшийся
  номер).
- **Переразметка секций не сломала перекрёстные ссылки.** `grep -n "§[0-9]"`
  по всему файлу показывает только актуальные номера (§7.1, §7.2, §8.1
  внутри неизменных старых разделов; §15/§18.x/§18.1–3 — внутри новых/
  переразмеченных). Ни одной ссылки на «осиротевший» номер раздела.
- **Новые технические утверждения не являются догадками.** Проверено
  построчно: claim §15.1 о линейности и отсутствии global registry scan
  подтверждён чтением `ownControllableEntities()` (`src/devices.ts:317-325`)
  — функция работает строго по `d.entities` одного устройства.
- **Содержание разделов 1–13 не изменилось** (сверено диффом `e46ef6f..76f75f8`)
  и уже было построчно проверено против кода в r1 (resolveOwnEntity,
  ownRoleCandidates, ownControllableEntities, диалоговый паттерн
  `light_entity`, backend-валидация, virtualize-allowlist) — переносить эту
  проверку заново нет смысла, т.к. код с r1 не менялся.
- **Трассируемость issue↔ТЗ↔review на месте**: `docs/specs/README.md:98`,
  шапка ТЗ, комментарии issue.
- **Продуктовых вопросов владельцу не осталось** — ни в исходном ТЗ, ни в
  правке r1→r2 не появилось нового технического вопроса, выданного за
  продуктовый; §20 «Принятые технические предположения» остаётся
  корректно отделённым от нормативных решений §4.

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

- Реализацию — её нет: `git diff origin/dev...HEAD` для `src/**` и
  `custom_components/**/*.py` пуст (проверено).
- Гейты `typecheck`/`test`/`build`/browser smoke — не относятся к этапу
  ревью ТЗ; предмет будущего code-review (PROCESS.md §2.7/§8).
- `python -m pytest tests_backend` — backend не менялся на этой ветке.
- Golden/perf-эталоны — сценарии описаны в §18.3/§18.2, реализации для сверки
  нет.
- Не повторял вручную полную построчную сверку разделов 1–13 с кодом — это
  уже сделано в SPEC-REVIEW-178-r1.md и код с тех пор не менялся (подтверждено
  диффом); повторный полный обход добавил бы задержку без новой информации.

## Вердикт

Оба блокирующих/неблокирующих пункта r1 закрыты содержательно, а не
формально: обязательные разделы существуют и информативны, AC несут точную
привязку к доказательству, переразметка не повредила перекрёстные ссылки.
Новых High/Medium не найдено. Единственная новая находка — Low-2 (раздел
touch не проговаривает явно, что runtime-эффект правки в View/kiosk
device/pointer-независим) — не блокирует: риск фактически отсутствует и
подтверждён чтением резолвера, а сама формулировка дёшево дополняется на
следующей правке документа без нового цикла ревью.

**Вердикт: зелёный · цикл r2/4 · High: 0 · Medium: 0 → нет · Документ:
docs/reviews/SPEC-REVIEW-178-r2.md**