houseplan-card/docs/reviews/SPEC-REVIEW-462-r3.md

# SPEC-REVIEW-462-r3

- **Issue:** https://github.com/Matysh/houseplan-card/issues/462
- **Спецификация:** `docs/specs/462-card-resource-registration.md`, коммит `b45c3464`
  (ветка `issue/462-card-resource-registration`, HEAD на момент ревью — тот же SHA)
- **Трек:** полный
- **Заход:** r3 · блокирующих циклов израсходовано 2 из 4 (лимит на полном треке — 4;
  зелёный вердикт этого раунда бюджет не тратит, #227)

## Материал раунда r2 (для дельты)

- Предыдущий вердикт: красный · заход r2 · High: 1 · Medium: 0 → в задаче
  (комментарий issue, 2026-09-05T11:22:44Z), документ
  `docs/reviews/SPEC-REVIEW-462-r2.md`.
- SHA материала r2 назван в документе дважды (шапка и «Материал раунда»):
  `e9e3d6bd7d8e61a0e7d561da76b19cedb157f32b`. Резолвится и сейчас как предок
  `HEAD` (`git merge-base --is-ancestor e9e3d6bd HEAD` → успех) — ребейза не
  было, восстановление по дереву/блобу не требовалось.
- Дельта этого раунда: `git diff e9e3d6bd..HEAD -- docs/specs/462-card-resource-registration.md`,
  два коммита: `c56afbd3` («docs: cite Home Assistant resource mode contract» —
  ответ на High r2) и `b45c3464` («docs: cover native more-info reload guard» —
  самостоятельно найденный автором до кода дополнительный unsafe-path в §11.3).
  40 изменённых строк, пять точек правки: §3 (новое обоснование версионной
  границы), §11.3 (расширение guard-условия про native more-info), §12 (те же
  ссылки в тексте документации), AC8 (§15) и план тестов (§16).

Дельта не вводит новый терминологический контракт и не задевает подсистему,
которую не разбирал r2: она (а) подкрепляет источниками уже существующее в r2
разделение storage/YAML-resource-mode и (б) уточняет один из guard-предикатов
kiosk-перезагрузки, не меняя ни матрицу §11.1, ни список § заявленных outcome,
ни какой-либо другой AC. Оба места делта касается напрямую (AC1/§12 через
источники; AC8/§11.3/§16 через native more-info) — только эти два узла и
проверялись заново по существу; остальное наследуется из r2.

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

Прочитано перед разбором: `docs/SCOPE.md` (Core user jobs, J4), `AGENTS.md`,
`PROCESS.md` §1–10 и §2.10 (объём по дельте), тело issue #462 и все 13
комментариев (включая комментарии автора о закрытии High через PR HA и о новом
guard native more-info), документы и находки `SPEC-REVIEW-462-r1.md` и
`SPEC-REVIEW-462-r2.md`, `docs/UX-MODES.md` (Kiosk mode), `docs/TOUCH-SUPPORT.md`.
Из самого ТЗ перечитаны §3, §11.3, §12, AC8, §16 целиком; остальные разделы —
по диффу и по унаследованному выводу r1/r2 (см. «Унаследовано из r2»).

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

В этой сессии, в отличие от r1 и r2, `WebFetch` (по прямым URL) отказал тем же
`permission denied`, но `gh api` (через `Bash`) сработал без ограничений и дал
прямой доступ к GitHub REST API `home-assistant/core` — то есть найденный в r1/r2
пробел («не подтверждено — WebSearch/WebFetch недоступны») в этом раунде закрыт
не доверием к цитате автора, а независимой проверкой того же источника другим
инструментом.

1. **Проверка PR, закрывшего High r2.**
   `gh api repos/home-assistant/core/pulls/161816` — существует, `merged: true`,
   `merge_commit_sha: 190fe10eed42d6ed5122bf873e61986851bc0b15` (совпадает с
   сокращённым `190fe10` из ТЗ), `milestone.title: "2026.2.0"` (совпадает с
   заявленным в ТЗ), заголовок «Allow lovelace path for dashboard in yaml and fix
   yaml dashboard migration», описание автора PR дословно: «Introduce a new key :
   `resource_mode` to replace `mode` so it's clear that it's only for resources.» —
   то есть первоисточник подтверждает именно то утверждение, которое ТЗ
   приписывает ему, а не общую формулировку не по делу.
2. **Проверка исходника на теге, где утверждается контракт.**
   `gh api repos/home-assistant/core/contents/homeassistant/components/lovelace/__init__.py?ref=2026.2.0`
   (сохранён локально, прочитан полностью). Подтверждено дословно:
   - `CONFIG_SCHEMA` домена `lovelace` содержит `vol.Optional(CONF_MODE, default=MODE_STORAGE)`
     **и отдельно** `vol.Optional(CONF_RESOURCE_MODE)` — два независимых
     необязательных ключа, не один "mode" как было в 2025.1.4 (r2 проверял ровно
     эту версию и не нашёл там `resource_mode` — версии до и после границы
     действительно различаются, как и утверждает ТЗ);
   - `resource_mode = config[DOMAIN].get(CONF_RESOURCE_MODE, mode)` — при
     отсутствии `resource_mode` поведение полностью откатывается к старому
     единому `mode` (обратная совместимость сохранена, ТЗ этого не утверждает
     явно, но и не противоречит);
   - `if resource_mode == MODE_YAML: resource_collection = await create_yaml_resource_col(...)`
     — YAML-ресурсы загружаются по значению `resource_mode`, **независимо** от
     того, что находится в `mode` (то есть независимо от режима dashboard) — это
     дословно тот функциональный контракт, который ТЗ описывает в §3/§5/§12/AC1;
   - ветка `else` (когда `resource_mode != yaml`, т.е. storage) сохраняет старый
     `_LOGGER.warning("Lovelace is running in storage mode. Define resources via
     user interface")` при непустых `yaml_resources` — то есть для HA без
     `resource_mode: yaml` (в том числе для версий до 2026.2, где ключа вообще
     нет) исходная посылка issue («в storage-режиме `lovelace.resources` из YAML
     игнорируется целиком») остаётся верной, и ТЗ её не отменяет — оно вводит
     доп. путь **только** для новых версий, что и обещает.
3. **Проверка риска "чужой ключ ломает валидацию"**, которым r2 обосновывал
   серьёзность High. Внутренний `vol.Schema({...})` для домена `lovelace` не
   объявляет `extra=vol.ALLOW_EXTRA` (только внешний `CONFIG_SCHEMA` — это
   касается ключей вне `lovelace:`, не внутри него) — значит на версиях **до**
   2026.2, где `resource_mode` не входит в схему, этот ключ до сих пор обвалил бы
   валидацию `lovelace:`. Проверил формулировку ТЗ (§12, «Legacy HA
   2024.6–2026.1»): современный snippet с `resource_mode` предлагается **только**
   для «HA 2026.2+», отдельная explicitly помеченная legacy-секция без этого
   ключа — для старых версий. Риск, которым r2 блокировал находку, ТЗ
   структурно исключает версионным разделением, а не только цитатой.
4. **Проверка дельты по native more-info guard (§11.3, AC8).** Прочитан
   `src/houseplan-card.ts`: `_openMoreInfo` (строка 5565) — единственная точка
   вызова `fireEvent(this, 'hass-more-info', …)` в файле; все places, открывающие
   more-info (right-click `view`-стейджа `:5618`, action handler `:5746-5747`,
   кнопки info-card `:12402`, `:13334`, `:13376`), проходят через неё. `grep -n
   _cyclePausedUntil` показывает единственную точку записи паузы —
   `_stagePointerDown` (`:6691`), и только при `this._kiosk`, только на
   pointerdown по сцене. Кнопки info-card на `:12402` делают
   `e.stopPropagation()` перед вызовом `_openMoreInfo`, то есть их клик не
   обязан долетать до обработчика сцены; клавиатурный и «внутренний
   программный» пути тем более не проходят через `pointerdown`. Значит
   формулировка ТЗ «одной паузы из stage pointerdown недостаточно» и «единая
   точка открытия more-info обязана продлить `_cyclePausedUntil`» — не догадка,
   а точное описание существующей архитектуры и корректно найденная дыра:
   единственная уже существующая точка сведения (`_openMoreInfo`) —
   реалистичное место для реализации, что соответствует §17 («точные helper
   names остаются за реализацией»).
5. **Согласованность правки по всем пяти точкам делты** (§3, §11.3, §12, AC8,
   §16 «Browser smoke/golden») — не осталось места, где старая формулировка
   («открытие уже ставит общую interaction pause») продолжала бы жить рядом с
   новой; численно проверено, что заново введённая фраза одна и та же по
   смыслу во всех пяти местах.
6. Не прогонялись `typecheck`/`test`/`build` — этап spec, кода нет; они
   применимы к код-ревью (§2.7 `PROCESS.md`), не к этому этапу.

## Находки

Ни одной High- или Medium-находки в делте `e9e3d6bd..HEAD` не обнаружено.

## Закрытие раунда r2

| Находка r2 | Чем закрыта | Где это видно |
|---|---|---|
| High: контракт `lovelace.resource_mode: yaml` для «HA 2026.2+» не подтверждён, противоречит доступной версии HA (2025.1.4) и собственной посылке issue; риск сломать `lovelace:` валидацией на старых HA | Первичные источники добавлены в ТЗ (PR, merge-коммит, тег, офиц. документация) и **независимо перепроверены в этом раунде напрямую через `gh api`** против реального исходника `homeassistant/components/lovelace/__init__.py` на теге `2026.2.0`: `CONF_RESOURCE_MODE` — реальный, отдельный от `CONF_MODE` optional-ключ схемы; `resource_mode == MODE_YAML` грузит YAML-ресурсы независимо от `mode` дашборда; версии до 2026.2 (без ключа) по-прежнему получают только legacy-snippet — риск валидации закрыт версионным разделением, а не игнорированием | `docs/specs/462-card-resource-registration.md` §3 (строки 75–93), §12 (398–436), AC1 (468–475); коммит `c56afbd3`; см. «Как проверялось» пп.1–3 этого документа |

Единственная находка r2 закрыта по существу и подтверждена независимо, не на
слово автора. Новых находок делта не внесла.

## Унаследовано из r2 (без повторной проверки в этом раунде)

Следующее не тронуто дельтой `e9e3d6bd..HEAD` за пределами описанного выше и
принимается по документам `docs/reviews/SPEC-REVIEW-462-r1.md` (SHA материала
`12ddd107a9cdd9b12ea8411360760f684f5293c1`) и
`docs/reviews/SPEC-REVIEW-462-r2.md` (SHA материала `e9e3d6bd7d8e61a0e7d561da76b19cedb157f32b`):

- Наличие и содержание обязательных разделов §7.1 `PROCESS.md` (сценарий, что
  человек увидит, причина, скоуп/не-скоуп, контракт §8–11, данные/миграция,
  i18n, AC1…AC13, план тестов, риски, откат, release-артефакты, §22).
- Закрытие обеих находок r1 (баннер vs terminal-тост #353; touch-target 44×44
  как локальный, не канонный порог) — таблица «Закрытие раунда r1» в
  `SPEC-REVIEW-462-r2.md`; дельта этого раунда их не касалась.
- Существование и смысл символов кода, проверенных в r1/r2:
  `_register_lovelace_resource`/`_lovelace_resources`
  (`custom_components/houseplan/__init__.py:336-378`), `manifest.json`
  (dependencies без `lovelace`), `system_health_info`, `CARD_VERSION`
  (`src/houseplan-card.ts:402`), `integration_version` в `config/get`,
  `_preflightVersionsDiffer`, `persistent_notification.async_create` как
  синхронный `@callback`, card-level overlay в трёх ранних render-ветках
  (`src/houseplan-card.ts:11282-11320`).
- Подтверждённая по реальным wheel `homeassistant==2024.6.0` и `==2025.1.4`
  цепочка зависимостей `houseplan → frontend → lovelace` и отсутствие
  `remove_extra_js_url` в 2024.6 (§8.2, п.9 и абзац после).
- Пригодность `homeassistant.helpers.start.async_at_started` в связке с
  `entry.async_on_unload` (§22 п.3).
- Полный список из 4 файлов документации с исходным невалидным плоским
  `resources:` (README.md, README.ru.md, docs/USER-GUIDE.md,
  docs/USER-GUIDE.ru.md) и обоснование выбора `persistent_notification` вместо
  Repairs (§22 п.1).
- Соответствие `docs/SCOPE.md`: задача закрывает J4, out-of-scope не задет.
- AC2–AC7, AC9–AC13 — формулировки не менялись делтой `e9e3d6bd..HEAD` (сверено
  построчно диффом); принимаю их однозначность и доказуемость как установленную
  в r1/r2. AC1 и AC8 менялись — перепроверены заново в этом раунде (см. «Как
  проверялось» пп.1–4 и «Закрытие раунда r2»).

## Что проверено и корректно (в этом раунде)

- Источники для `lovelace.resource_mode` — реальны, дают именно то
  утверждение, которое им приписано, и независимо подтверждены против
  исходного кода HA на названном теге, а не только против цитаты автора.
- Версионное разделение snippet'ов (2026.2+ / legacy 2024.6–2026.1) структурно
  исключает риск, из-за которого High r2 был серьёзным (обвал валидации
  `lovelace:` на старых HA неизвестным ключом): новый ключ предлагается только
  там, где он существует в схеме.
- Новое guard-условие native more-info (§11.3/AC8) описывает существующую,
  проверенную по коду архитектуру (`_openMoreInfo` как единая точка сведения,
  `_cyclePausedUntil` как единственная точка паузы только из
  `_stagePointerDown`), а не гипотетический символ; реализуемо без новой
  неоднозначности в AC8 и плане тестов.
- Правка внесена согласованно во всех пяти местах, которые она логически
  затрагивает (§3, §11.3, §12, AC8, §16) — старая и новая формулировка нигде не
  остались одновременно.
- AC1 и AC8 после делты остаются однозначными и называют способ доказательства
  (`unit`/docs contract для AC1; `unit + browser + mutation` для AC8).

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

- Не проверял версии HA новее `2026.2.0` — не требуется: делта именно
  зафиксировала версионную границу на этом теге, дальнейшие версии вне спора.
- Не проверял официальную документацию `home-assistant.io/dashboards/dashboards/`
  напрямую (WebFetch по прямому URL отказал тем же `permission denied`, что и в
  r1/r2) — не потребовалось: первичный источник (PR + исходник тега) сильнее
  вторичного (документация) и уже даёт исчерпывающее прямое подтверждение.
- Не прогонял `typecheck`/`test`/`build` — этап spec, кода ещё нет; гейты
  применимы к код-ревью, не к этому этапу.
- Не переоткрывал AC2–AC7, AC9–AC13, §8–10, §13–15, §17–22 по существу — делта
  их не касалась (см. «Унаследовано из r2»).
- Не оценивал landing page/дистрибуцию — вне репозитория, зона Claude по
  `AGENTS.md`, не часть ТЗ.

## Вывод

Единственная блокирующая находка r2 закрыта по существу и подтверждена
независимой проверкой первичного источника, а не принята на слово. Делта
сверх этого (native more-info reload guard) — корректное, реализуемое и
согласованное уточнение существующего требования, без новых High/Medium.
Задача готова к разработке.

## Материал раунда

- Ветка: `issue/462-card-resource-registration`
- SHA материала: `b45c3464ca1847b5f9041bdc277a0c01de49eb19`
- Дерево материала: `d8d3c0f0dd8cfabad9e9cb583142bda2a8f50ddb`
- Файл ТЗ: `docs/specs/462-card-resource-registration.md`, блоб
  `d3620eab48950255aa91240cd70ec3ed1edfd756`
- SHA r2 (для дельты): `e9e3d6bd7d8e61a0e7d561da76b19cedb157f32b`

---

<!-- material-anchors: сгенерировано конвейером (#414) -->

## Материал раунда

- Ветка: `issue/462-card-resource-registration`, коммит `b45c3464ca18` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
- Дерево материала: `d8d3c0f0dd8cfabad9e9cb583142bda2a8f50ddb`
  ```
  git log --all --format='%H %T' | grep d8d3c0f0dd8c
  ```
- ТЗ `docs/specs/462-card-resource-registration.md`, блоб `d3620eab48950255aa91240cd70ec3ed1edfd756`
  ```
  git log --all --find-object=d3620eab48950255aa91240cd70ec3ed1edfd756 -- docs/specs/462-card-resource-registration.md
  ```