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

# SPEC-REVIEW-117-r1

- **Issue:** https://github.com/Matysh/houseplan-card/issues/117
- **ТЗ под ревью:** `docs/specs/117-registryless-opening-entity.md` (коммит `cc2298816b8ca4e41a41830fef69fd2ee1cb7ed9`)
- **Роль:** ревьюер ТЗ (не автор), этап `S4-spec-review`
- **Трек:** обычный (не `small`) — аналитика оценила сложность 4/10, риск 5/10
  (> 3), поверхности: opening entity picker/resolver, View state/action,
  unit/smoke/docs — больше одной поверхности; лёгкий трек корректно не применён
- **Цикл:** r1/4

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

Проверялось соответствие ТЗ:
- `docs/SCOPE.md` — попадание в Core user jobs, отсутствие расширения скоупа;
- `PROCESS.md` §2.4, §2.5 (DoR), §7.1 (обязательные разделы), §3.18 и §12
  (запреты, включая «Medium как TODO в тексте ревью»);
- `AGENTS.md` — классы файлов, ветка, трейлеры;
- `docs/USER-GUIDE.ru.md` — терминология «Контактный датчик» / «Замок» /
  «проём»;
- issue #104 — откуда #117 выделен решением владельца, и не пересекается ли
  ТЗ с уже закрытым скоупом #104 (marker tombstone);
- фактическому состоянию кода (`src/ha-binding-status.ts`, `src/houseplan-card.ts`)
  — на предмет того, что технические утверждения ТЗ не являются непроверенной
  догадкой, а не описанием несуществующего поведения.

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

1. Прочитано тело issue #117 (автор — владелец, `Matysh`, 2026-08-13) и оба
   комментария: аналитика (2026-08-14, P2/bug/обычный трек, продуктовых
   вопросов нет) и заведение ТЗ (2026-08-15, ссылка на файл и коммит).
2. Прочитан весь текст `docs/specs/117-registryless-opening-entity.md`
   (223 строки) построчно.
3. Прочитан `src/ha-binding-status.ts:308-545`: подтверждено, что
   `activeRegistryHass()` уже сознательно сохраняет live state registry-less
   сущности (комментарий в коде на строках 342-346 прямо это объясняет), а
   `renderOpeningEntityAvailable()` (строка 538) требует одновременно
   `.entities[entityId]` **и** `.states[entityId]` — то есть расхождение,
   которое ТЗ называет причиной бага, реально существует в коде, а не
   придумано. Более того, комментарий к функции на строке 536 уже сегодня
   говорит: «Registry-less render parity is #117» — само ТЗ не изобретает
   этот план, а закрывает уже отмеченный в коде долг.
4. Прочитан `src/houseplan-card.ts:16256-16380`: подтверждено, что и
   `_openingAmt()`, и `_renderOpeningLocks()` идут через единственную точку
   `_renderOpeningEntityAvailable()` → `renderOpeningEntityAvailable(this._renderPlanHass, eid)`
   — то есть один фикс на уровне `ha-binding-status.ts` действительно
   закрывает contact и lock одновременно, как заявляет ТЗ, без риска
   рассинхронизации двух копий логики.
5. Прочитано `_captureRenderDeviceSnapshot()` (`src/houseplan-card.ts:3559-3673`):
   подтверждено, что `opening.contact`/`opening.lock` уже входят в `entityIds`
   при захвате snapshot (строки 3595-3596) и что `planHass` в этом снимке —
   результат `activeRegistryHass()` (строка 3553/3574) — то есть registry-less
   state уже присутствует в замороженном кадре сегодня; баг только в лишней
   проверке `.entities[entityId]` при чтении, как и утверждает §2 ТЗ.
6. Прочитан `src/houseplan-card.ts:16269-16284` (`_renderEntityAvailable` vs
   `_renderOpeningEntityAvailable`): подтверждено, что общий
   `_renderEntityAvailable()` (используется для прочих marker-биндингов) не
   входит в фикс — ТЗ §4 прямо исключает «generic поддержку registry-less
   entities во всех marker bindings», и это согласуется с кодом: два разных
   потребителя, значит сужение скоупа не оставляет незамеченного разрыва.
7. Прочитан `docs/USER-GUIDE.ru.md:409-444` («Настройки проёма», «Замок») —
   терминология ТЗ («контакт», «замок», «info card», «unlock confirmation»)
   совпадает с пользовательским словарём; текущая формулировка «Контактный
   датчик и замок — самостоятельные точные привязки проёма» уже описывает
   независимость от marker (#104), но ничего не говорит о registry —
   подтверждает, что баг сегодня не задокументирован пользователю и правка
   §14 (уточнить в user-guide поддержку YAML-сущности без `unique_id`)
   осмысленна.
8. Сверено, что упомянутые в плане тестирования файлы существуют:
   `test/ha-binding-status.test.mjs`, `test/render-device-snapshot.test.mjs`,
   `demo/smoke_opening_binding.mjs`, `demo/smoke_lock_action.mjs`,
   `demo/smoke_lock_invariant.mjs` — план тестирования не ссылается на
   несуществующее покрытие.
9. Прочитано тело issue #104: подтверждено, что #104 занимался независимостью
   opening-биндинга от marker tombstone (не от registry-строки) — #117 не
   пересекается с уже закрытым скоупом #104, а закрывает отдельно вынесенную
   часть, как и написано в issue.
10. Проверена запись `docs/specs/README.md:85` — добавлена тем же коммитом,
    ссылка issue ↔ ТЗ двусторонняя.
11. Автор issue — владелец (`Matysh`), легитимность входа в процесс вопросов
    не вызывает.

## Обязательные разделы (§7.1 PROCESS.md)

| Раздел | Есть | Комментарий |
|---|---|---|
| Сценарий (персона/поверхность/момент) | ❌ | нет отдельного раздела; персона и поверхность не названы явно нигде в документе |
| Что человек увидит до/после (без терминов реализации) | ❌ | ближе всего — последняя фраза §1 («сохранённый contact/lock не влияет на отрисованный проём»), но она внутри технического абзаца с `hass.states`/render path, а не отдельной продуктовой фразой |
| Проблема | ✅ | §1–2, с точной причиной по коду |
| Скоуп / не-скоуп | ✅ | §3 (Цели) / §4 (Не входит) |
| Контракт поведения | ✅ | §5, §8, §9 |
| UX | ~ | нет отдельного раздела, но §6 (матрица), §8, §9 покрывают поведение по существу |
| Модель данных и миграция | ✅ | §10 («config/storage/API не меняются») |
| i18n | ✅ | §14 («новых RU/EN строк нет») |
| AC1…ACn с доказательством | ~ | §11, 10 пунктов, но без инлайн-тега типа доказательства у каждого (см. Low-2) |
| План автотестов | ✅ | §12 |
| Риски | ✅ | §15 |
| Откат | ✅ | §15 |
| Release-артефакты | ✅ | §14 |

Два обязательных продуктовых раздела (сценарий, что человек увидит) в виде
отдельных секций отсутствуют — см. Low-1. Технической неоднозначности это не
создаёт: контент восстановим из §1/§9 и подтверждён чтением кода (см. «Как
проверялось»), поэтому не поднимаю до High/Medium (см. обоснование в Low-1).

## Находки

Находок уровня **High** и **Medium** нет.

### Low-1 — нет отдельных разделов «Сценарий» и «Что человек увидит»

**Файл:** `docs/specs/117-registryless-opening-entity.md:9-17` (§1)

PROCESS.md §7.1 требует эти два раздела первыми и объясняет почему: «ТЗ,
которое не может ответить на эти два вопроса, описывает работу, а не
изменение продукта». В этом ТЗ persona/surface/moment нигде не названы явно,
а «что увидит человек» растворено в техническом абзаце про `hass.states` и
render path.

Восстановленный ответ (проверяемый по SCOPE.md и коду, не по догадке):
персона — **Home admin** привязывает live YAML-сущность без `unique_id`
(например, `binary_sensor` без `unique_id`) к контакту/замку проёма в Plan
editor, picker её принимает; после сохранения все три персоны, смотрящие на
**View** (включая kiosk-планшет), видят проём/замок, который не реагирует на
реальное изменение состояния сущности, хотя в HA оно меняется. После фикса —
тот же проём ведёт себя как с обычной зарегистрированной сущностью.

**Решение ревьюера:** Low, не блокирует. Ни один AC не становится
двусмысленным из-за отсутствия этих разделов, и содержание однозначно
восстанавливается из §1/§9/кода — не тот случай, когда «домыслил ревьюер»
подменяет решение владельца, потому что сама сцена уже зафиксирована в issue
и SCOPE.md (View — продукт для двух персон), а не изобретена сейчас. Оставляю
на усмотрение автора: можно добавить двумя короткими фразами при следующей
правке файла, отдельного цикла ревью это не требует.

### Low-2 — AC1–AC10 (§11) не несут инлайн-тег способа доказательства

**Файл:** `docs/specs/117-registryless-opening-entity.md:145-158`

DoR (`PROCESS.md` §2.5) требует: «AC1…ACn — ... у каждого указано, чем он
доказывается: `unit` / `backend` / `smoke` / `golden` / «ревью кода»». Ни один
из десяти пунктов §11 не несёт такой пометки; способ доказательства нужно
реконструировать из §12 «План тестирования» отдельно.

Реконструкция (сверена с реальными файлами, см. «Как проверялось», п.8):

| AC | Доказательство |
|---|---|
| AC1 (registry-less contact меняет presentation) | `smoke`: новый YAML-like `binary_sensor` сценарий (§12) |
| AC2 (registry-less lock badge) | `smoke`: новый YAML-like `lock` сценарий (§12) |
| AC3 (frame использует projection, не raw hass) | `unit`: mutation-guard «вернуть `.entities[entityId]` — YAML case красный» (§12) — единственный AC, где мутационный тест сам по себе и есть доказательство, а не просто регрессия |
| AC4 (registry entity — прежнее поведение) | `smoke`/`golden`: существующие opening-сценарии без изменений |
| AC5 (disabled/orphan/missing остаются unavailable) | `unit`: расширенная матрица в `ha-binding-status.test.mjs` |
| AC6 (limited-registry live entity работает) | `unit`: тот же файл, ветка `authoritative: false` |
| AC7 (marker tombstone не блокирует) | `smoke`: «same entity tombstoned as marker» (§12) |
| AC8 (lock security/confirmation не меняются) | не назван явно; фактически покрыт существующими `demo/smoke_lock_action.mjs` и `demo/smoke_lock_invariant.mjs` (регрессия, п.3 «Регрессия» §12) плюс «ревью кода» |
| AC9 (state update без geometry/config rebuild) | `smoke`: «render snapshot atomicity on state tick» (§12) |
| AC10 (существующие opening golden/interactions без регресса) | `golden`/`smoke`: регрессионный прогон существующих сценариев (§12, явно уточнено, что golden-эталоны не переакцептуются) |

Каждый AC в итоге прослеживается к конкретному, реально существующему тесту
или к явно допустимому DoR методу «ревью кода» (AC8). Ни один пункт не
остаётся недоказуемым по существу — разрыв чисто в оформлении: тег не
проставлен инлайн, как это было сделано, например, в предыдущем ТЗ #123 (13/13
AC с явным типом).

**Решение ревьюера:** Low, не блокирует. Реконструкция выше снимает риск
«недоказанного AC» для этого цикла; рекомендую при следующей правке файла
добавить тег каждому AC (особенно явно объявить AC8 как «ревью кода +
`smoke_lock_action.mjs`/`smoke_lock_invariant.mjs`», а не оставлять
подразумеваемым). Отдельного issue не завожу: это дефект оформления текущего
ТЗ, а не самостоятельная будущая работа — заводить для него `S1-new` issue
было бы имитацией процесса, а не пользой.

### Low-3 — матрица (§6) не содержит отдельной строки для registry-less entity в состоянии `unavailable/unknown`

**Файл:** `docs/specs/117-registryless-opening-entity.md:79-95`

Матрица явно разбирает «registry entity `unavailable/unknown`» (строка 85), но
не добавляет параллельную строку для «YAML/no registry row entity в
`unavailable/unknown`». Пояснение под таблицей («unavailable/unknown здесь
означает, что exact reference существует... #117 не подменяет эти states
active/open») по формулировке относится к обеим ветвям, и это подтверждено
чтением кода: `openingAmount()` (`src/logic.ts:316`) не различает
registry-статус сущности, работает только со строкой state — поэтому поведение
для YAML-сущности в `unavailable` идентично зарегистрированной. Риска для
корректности нет, только асимметрия изложения.

**Решение ревьюера:** Low, снимаю с этой записью, правка не обязательна.

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

- Соответствие `docs/SCOPE.md`: правка внутри уже закрытых J4 (онбординг/editor)
  и J6 («Keep the plan true as the home evolves», два редактора, drag/resize,
  editable icon rules) — это регрессионный/пограничный баг внутри принятой
  функциональности opening-биндинга, а не новая фича и не расширение скоупа.
- Технический диагноз (§2) подтверждён построчным чтением `ha-binding-status.ts`
  и `houseplan-card.ts` — не голословное утверждение автора; комментарий в коде
  уже сегодня ссылается на #117 как на известный долг.
- Единая точка фикса (`renderOpeningEntityAvailable`) реально закрывает и
  contact, и lock одновременно — проверено по вызывающему коду, а не
  предположено.
- Матрица поведения (§6) корректно защищает все смежные случаи, которые могли
  бы регрессировать: явный `disabled_by` у сущности и у устройства,
  authoritative orphan, отсутствующий state, limited-registry режим — все эти
  ветки уже реализованы в `activeRegistryHass()`/`resolveHaBindingStatus()` и
  проверены построчно (см. «Как проверялось», п.3).
- Независимость от marker tombstone (AC7) корректно унаследована из #104:
  `renderOpeningEntityAvailable` не обращается к `isRemovedPlanEntity()`, в
  отличие от соседнего `_renderEntityAvailable()` — сужение скоупа (§4,
  «generic поддержка... во всех marker bindings» — не входит) не оставляет
  незамеченного разрыва, оба потребителя разделены в коде.
- Lock security и confirmation (§9) сформулированы дословно в терминах
  существующего инварианта `docs/SCOPE.md` («The lock invariant, stated
  precisely») — не ослабление и не новая семантика actuation.
- Раздел 16 «Принятые технические предположения» корректно отделяет свободно
  изменяемые технические решения от продуктового контракта; ни одна догадка не
  выдана за факт без пометки — я не нашёл ни одного утверждения о поведении,
  которое не следует из кода, SCOPE.md или явно принятых допущений.
- Открытых продуктовых вопросов действительно нет: единственные развилки
  (registry vs registry-less, authoritative vs limited access, disabled vs
  orphaned) — все технические, не продуктовые, и решены автором согласно
  правилу §7.1 «всё, чего пользователь не наблюдает, агенты решают сами».
- Терминология (USER-GUIDE.ru.md) не изобретена заново — «контакт», «замок»,
  «info card», «unlock confirmation» совпадают с действующим словарём.
- Совместимость (§10): config/storage/API не меняются, существующие
  registry-backed openings объявлены pixel-identical, touch/kiosk жесты не
  меняются, i18n ключей не добавляется — всё согласуется с
  `docs/CONFIG-COMPATIBILITY.md` и `docs/TOUCH-SUPPORT.md` (нет заявленного
  влияния, что и требуется).
- Реестр `docs/specs/README.md` обновлён тем же коммитом, ссылка issue ↔ ТЗ
  двусторонняя; issue заведён владельцем — легитимность входа в процесс не
  вызывает вопросов.
- Golden явно не требует переакцептации (существующие baseline не меняются) —
  корректное сужение release-артефактов, не попытка обойти гейт.

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

- Не запускал никаких автотестов или смоков — на этапе `spec` это не
  требуется; существование файлов, упомянутых в плане тестирования, проверено
  чтением (`test/ha-binding-status.test.mjs`, `test/render-device-snapshot.test.mjs`,
  `demo/smoke_opening_binding.mjs`, `demo/smoke_lock_action.mjs`,
  `demo/smoke_lock_invariant.mjs`), не исполнением.
- Не проверял реальное поведение реальной HA-инсталляции с YAML-сущностью без
  `unique_id` — это будет предметом browser smoke на код-ревью (§12 плана
  тестирования), не ревью ТЗ.
- Не проверял `src/logic.ts:openingAmount()` построчно на предмет всех
  инвариантов инверсии/leaf-угла — доверяю формулировке §8 «state проходит
  текущий `openingAmount(...)`; invert сохраняется» как описанию уже
  существующего, не нового контракта; это не предмет этого фикса (§4: «не
  входит в задачу» новые opening types или geometry).
- Не проверял historical переписку по ревью ТЗ #104 (сам документ ревью #104
  не найден отдельно) — доверяю формулировке issue #117 «решением владельца
  registry-less render исключён из scope #104», подтверждённой владельцем в
  комментарии аналитики (нет открытых вопросов/несогласия по этой границе).
- Не проверял производительность — ТЗ явно заявляет «нет» (§14), и правка не
  трогает горячий путь по кадрам иначе, чем чтением одного дополнительного
  boolean на существующей projection.

## Вердикт

Зелёный. High: 0, Medium: 0. Три находки Low (отсутствие двух обязательных
продуктовых разделов; отсутствие инлайн-тегов доказательства у AC1–AC10;
асимметрия одной строки матрицы) — ни одна не блокирует и не оставляет
AC недоказуемым по существу; все зафиксированы с реконструкцией и оставлены на
усмотрение автора при следующей правке файла, без нового цикла ревью.