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

# SPEC-REVIEW-462-r2

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

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

- Предыдущий вердикт: жёлтый · заход r1 · High: 0 · Medium: 1 → в задаче
  (комментарий issue, 2026-09-05T11:03:23Z).
- **SHA в самом вердикте (комментарии issue) не назван** — это находка процесса
  фиксации, отдельно от содержательного разбора (см. «Находки», Low-2). SHA
  восстановлен из документа `docs/reviews/SPEC-REVIEW-462-r1.md`, где он назван
  явно: `12ddd107a9cdd9b12ea8411360760f684f5293c1`, и подтверждён порядком коммитов
  (`910eedb4 docs: review document for #462` — публикация документа r1 —
  следует сразу за `12ddd107`, до `8973431f`, который отвечает на находку r1).
- Дельта этого раунда: `git diff 12ddd107..e9e3d6bd -- docs/specs/462-card-resource-registration.md`
  (151 изменённая строка), двумя коммитами:
  `8973431f` («Замечание SPEC-REVIEW r1 исправлено» + новый YAML resource_mode
  контракт + источник touch-target) и `e9e3d6bd` («устранены технические
  двусмысленности» — retry timing/cancellation, нормализация версии, translations
  category, card-level overlay в ранних render-states, kiosk-guard дополнения).

Дельта не локальна: она вводит новый терминологический контракт поведения HA
(«YAML resources mode» vs «Legacy full-YAML dashboard mode», см. ниже) и меняет
формулировку четырёх AC (AC1, AC3, AC12, AC13) плюс план тестов и риски. По
правилу «смена контракта поведения → полный разбор» я перечитал документ
целиком (§1–22) и проверил новые технические утверждения по коду HA, а не
только территорию, формально задетую диффом.

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

Прочитано перед разбором: `docs/SCOPE.md` (Core user jobs, J4), `AGENTS.md`,
`PROCESS.md` §1–10, тело issue #462 и все 8 комментариев (включая решение
владельца о тихой kiosk-перезагрузке и аналитику 2026-09-05), документ и
находки `SPEC-REVIEW-462-r1.md`, `docs/UX-MODES.md` (Kiosk mode),
`docs/TOUCH-SUPPORT.md`. Сам документ ТЗ — целиком, §1–22.

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

Ревью состязательное: issue + ТЗ + код `dev` + прямая проверка технических
утверждений о платформе HA, без доверия формулировке «по официальному контракту
HA» на слово (именно так был подписан коммит `8973431f`).

1. **Материал среды.** `pip index versions homeassistant` в этом окружении
   зеркалирует PyPI и обрывается на `2025.1.4` (последняя доступная версия) —
   то же ограничение уже зафиксировал r1 («не проверялся HA 2026.8 напрямую»).
   Скачан `homeassistant==2025.1.4` (`pip download --no-deps`) и прочитан исходник
   компонента `lovelace`.
2. **Ключевая новая находка.** `homeassistant/components/lovelace/__init__.py`
   (2025.1.4) содержит единственный `CONFIG_SCHEMA` для домена `lovelace`:
   ```python
   vol.Optional(CONF_MODE, default=MODE_STORAGE): vol.All(vol.Lower, vol.In([MODE_YAML, MODE_STORAGE])),
   vol.Optional(CONF_DASHBOARDS): ...,
   vol.Optional(CONF_RESOURCES): [RESOURCE_SCHEMA],
   ```
   Один `mode` одновременно решает: (а) в YAML ли dashboard, (б) читаются ли
   `resources:` из YAML. В ветке `else` (mode != yaml, т.е. storage — умолчание)
   код явно делает `_LOGGER.warning("Lovelace is running in storage mode. Define
   resources via user interface")`, если `yaml_resources is not None` — то есть
   **подтверждает**, а не опровергает исходную посылку issue («в storage-режиме
   `lovelace.resources` из YAML игнорируется целиком»). Отдельного ключа
   `resource_mode`, который расцеплял бы «источник ресурсов» и «режим dashboard»,
   в схеме нет. `grep -r resource_mode` по всему распакованному пакету (`.py`,
   все файлы) — ноль совпадений. `grep -rn resource_mode` по всему репозиторию
   houseplan-card вне `docs/specs/462-*.md` — тоже ноль: концепция не
   встречается больше нигде в кодовой базе, документации или прежних раундах.
3. **Попытка проверить внешний источник.** `WebSearch`/`WebFetch` недоступны в
   этой сессии («haven't granted it yet» на оба вызова, дважды). Верификация
   ограничена локальным кодом платформы и внутренней согласованностью
   документа — этого достаточно, чтобы поднять находку, но не достаточно, чтобы
   на 100% исключить более поздний upstream-релиз (ниже, «Чего не проверял»).
4. **Проверка синхронности `persistent_notification.async_create`.** §9 теперь
   утверждает: флаг «уведомление создано» пишется «сразу после того, как
   синхронный callback `persistent_notification.async_create` вернулся без
   исключения». Подтверждено в исходнике 2025.1.4:
   `homeassistant/components/persistent_notification/__init__.py` — функция
   помечена `@callback` (не `async def`, не корутина), тело — синхронная запись
   в dict + `async_dispatcher_send`, реальных исключений в штатном пути нет.
   Формулировка точна.
5. **Проверка card-level overlay в ранних render-состояниях (§11.2).**
   `src/houseplan-card.ts:11282-11320` — реальность подтверждена: `fixed.kind
   === 'pending'`, `'invalid'` и `!model.length` действительно возвращают три
   независимых `<ha-card>...</ha-card>` шаблона до основной сцены. Требование
   «отдельные копии разметки в render-ветках не становятся независимыми
   состояниями» — не выдумка, а корректный ответ на реальную структуру кода;
   без него легко забыть плашку в одной из трёх веток.
6. **Проверка закрытия Medium-находки r1** (баннер против тоста #353) — по
   тексту нового §11.2 и обновлённых AC12/§16 (ниже, «Закрытие раунда r1»).
7. **Проверка закрытия Low-находки r1** (число 44×44 без источника) — §22 п.8.

## Находки

### High — новый контракт `lovelace.resource_mode: yaml` не подтверждён и
### противоречит и коду HA, и собственной посылке issue

Введено в этом раунде (`8973431f`, отсутствовало в редакции r1). §5, §12, AC1 и
план тестов (§16 «Docs/mutation») теперь утверждают, что в «HA 2026.2+»
`lovelace.resource_mode: yaml` — независимый от `lovelace.mode` ключ, который
подключает YAML-ресурсы к storage-managed dashboard. Формулировка прямая,
без оговорки «предположение»: «Нельзя утверждать, что `lovelace.resources`
всегда игнорируется storage-managed dashboard: в HA 2026.2+ именно
`resource_mode: yaml` поддерживает YAML-ресурсы независимо от режима
dashboard» (docs/specs/462-card-resource-registration.md:405-408). Коммит
`8973431f` в issue подписан «по официальному контракту HA» — то есть подан как
проверенный факт, не как гипотеза.

Что не сходится:

- В единственной доступной для проверки версии HA (`2025.1.4`, актуальная в
  индексе pip этого окружения) ключа `resource_mode` не существует нигде —
  ни в `lovelace`, ни где-либо ещё в пакете. Единственный `mode` управляет и
  dashboard, и тем, читаются ли `resources:` из YAML.
- Это прямо противоречит тому, что сама схема делает сегодня: `resources:` под
  `lovelace:` **действительно игнорируется** (с explicit warning) при
  `mode: storage` — то есть исходная посылка issue («в storage-режиме
  `lovelace.resources` из YAML игнорируется целиком») **подтверждена кодом**, а
  не опровергнута, как теперь пишет ТЗ.
- Это противоречит собственному телу issue (написано владельцем в тот же день):
  «в storage-режиме дашбордов (умолчание HA) `lovelace.resources` из YAML
  игнорируется целиком» — заявлено как подтверждённый факт полевого разбора, не
  снято ни одним последующим комментарием.
- `vol.Schema({...})` для домена `lovelace` в 2025.1.4 не имеет
  `extra=vol.ALLOW_EXTRA` (в отличие от внешней обёртки `CONFIG_SCHEMA`) —
  значит непредусмотренный ключ верхнего уровня внутри `lovelace:` обычно
  **валится валидацией конфигурации HA**, а не тихо игнорируется. Если
  `resource_mode` не появится в реальном будущем релизе именно так, как описано,
  рекомендованный «современный» sniplet из §12 может не просто не сработать
  (старая проблема #462), а **сломать загрузку `lovelace:` целиком** — то есть
  задача рискует внедрить дефект хуже исходного, ровно в том месте, которое
  должно чинить документацию.
- Утверждение не помечено в §22 («Принятые технические предположения — можно
  менять на ревью») как гипотеза, хотя структурно — это ровно тот раздел, где
  ему место, если бы оно было гипотезой, а не фактом.
- Утверждение приводит к automated docs-contract тесту (AC1, §16) и
  формулировке AC1 «мутант: … современный `mode: yaml` вместо `resource_mode:
  yaml` … делает docs contract красным» — то есть контракт будет насильно
  удерживать в README/User Guide формулировку, которую нечем подтвердить, и
  снимать её будет уже не ревью, а очередной пользовательский репорт, как #462.

**Возврат автору.** Нужно либо (а) привести проверяемый источник для
`lovelace.resource_mode` (номер release note/PR HA, который это ввёл — тогда
формулировка остаётся, но с явной ссылкой), либо (б) убрать разделение на
современный/legacy YAML-режим и вернуться к единственному подтверждённому
контракту: `lovelace.mode: yaml` меняет и dashboard, и разрешает
`resources:`, а storage-режим требует UI Resources — то есть к тому описанию,
которое уже было верно на r1 и не вызывало вопросов. Пока источник не назван —
AC1, §5, §12 и соответствующий пункт §16 остаются недоказанным техническим
угадыванием, оформленным как решённый факт. High, блокирует.

### Low-1 (наследуется, закрыта) — числовой touch-target 44×44

Была Low в r1 без источника в каноне. §22 п.8 теперь явно помечает число как
«локальный accessibility-порог», а не заимствование канона. Формулировка
r1 предлагала ровно это — принимаю как закрытую, отдельного действия не
требуется.

### Low-2 — SHA не назван в вердикт-комментарии r1

Комментарий-вердикт r1 в issue (`Вердикт: жёлтый · заход r1 …`) не называет SHA
материала, на котором получен вердикт — притом что сам документ
`SPEC-REVIEW-462-r1.md` SHA называет дважды (в шапке и в «Материале раунда»).
Практических последствий не имело: SHA восстановлен однозначно по порядку
коммитов. Не блокирует, но стоит отметить в шаблоне хендофф-комментария на
будущее — вердикт-комментарий в issue должен либо называть SHA сам, либо явно
отсылать к документу как единственному источнику SHA.

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

| Находка r1 | Чем закрыта | Где видно |
|---|---|---|
| Medium: новый version-controller баннер и terminal-тост #353 просят reload независимо и могут показаться одновременно с разными формулировками | Явное правило: terminal-тост #353 подавляется только пока видна version-mismatch плашка; network/non-terminal тост и terminal-тост без плашки не подавляются; одновременно два сообщения с одной просьбой не показываются | `docs/specs/462-card-resource-registration.md:312-318` (§11.2), AC12 (`:526-528`), план тестов §16 «Browser smoke/golden» (`:560-562`), риск §19 п.11 (`:629-631`) |
| Low: touch-target 44×44 без источника в каноне | Помечено как локальное (не канонное) accessibility-решение | §22 п.8 (`:681-683`) |

Обе находки r1 закрыты по существу, без новых открытых вопросов по ним самим.
Однако правка Medium-находки (коммит `8973431f`) в том же дыхании внесла
новую, более серьёзную находку — см. «Находки», High — что и есть причина,
по которой предупреждение §2.9/#102 в этой задаче не абстрактно: починка одного
AC создала риск в другом месте того же коммита.

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

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

- Наличие и содержание обязательных разделов §7.1 PROCESS.md (сценарий, что
  человек увидит, причина, скоуп/не-скоуп, контракт §8–11, данные/миграция,
  i18n, AC1…AC13, план тестов, риски, откат, release-артефакты, §22).
- Существование и смысл символов кода, проверенных в r1:
  `_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` (`houseplan-editor-runtime.ts:9610`),
  `_cyclePausedUntil`/`_zoom`/`_editing`/`_pendingPhysicalWrites`/
  `_writesPending`/`_vacFit`.
- Подтверждённая по реальным wheel `homeassistant==2024.6.0` и `==2025.1.4`
  цепочка зависимостей `houseplan → frontend → lovelace` (§3) и отсутствие
  `remove_extra_js_url` в 2024.6 (обосновывает `lovelace_resource_with_
  session_fallback`, §8.2 абзац после п.9). Эти два факта дельта не
  затрагивала и я их не переоткрывал.
- Пригодность `homeassistant.helpers.start.async_at_started` как
  `CALLBACK_TYPE`, совместимого с `entry.async_on_unload` (§22 п.3, базовая
  часть механизма; новым в этом раунде является только добавка secondary
  cancellable delay поверх него — это я перепроверил заново, см. «Как
  проверялось», п.2 относится к другому вопросу, а сам `async_at_started`
  переподтверждать не стал).
- Полный список из 4 файлов документации с невалидным плоским `resources:`
  (README.md:101, README.ru.md:105, docs/USER-GUIDE.md:94,
  docs/USER-GUIDE.ru.md:93) — дельта не меняла состав списка, только
  требуемое содержание правки.
- Обоснование выбора `persistent_notification` вместо Repairs (§22 п.1) через
  прецедент `custom_components/houseplan/repairs.py`.
- Соответствие SCOPE.md: задача закрывает J4, out-of-scope не задет.
- AC2, AC5, AC6, AC7, AC8, AC9, AC10, AC11 — формулировки не менялись в дельте
  (проверено `git diff` по разделам, см. «Материал раунда r1»); принимаю их
  однозначность и доказуемость как установленную в r1.

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

- Раздел «Закрытие раунда r1» — обе находки закрыты по существу, без
  формальных отписок.
- §9 (флаг notification после синхронного `async_create`) — техническая
  точность подтверждена по исходнику HA 2025.1.4.
- §11.2 card-level overlay в ранних `fixed-floor`/пустых состояниях —
  требование обосновано реальной структурой `render()` в
  `src/houseplan-card.ts` (три отдельных `<ha-card>`-ветки), не выдумка.
- §11.3 новые guard-пункты (нативный HA more-info не участвует по
  ненадёжному полю; pending layout debounce/грязные позиции устройств
  блокируют auto-reload) описаны как требования к реализации без ссылки на
  несуществующие внутренние символы — не нарушают правило «не выдавать догадку
  за решение», это раздел, где §17 явно оставляет точные имена за
  реализацией.
- §22 п.8 (touch-target) и §11.2/AC12/§16/§19 (закрытие toast/banner
  конфликта) корректно закрывают находки r1 — см. таблицу выше.
- Нумерация и внутренняя согласованность AC1–AC13 не нарушены дельтой: каждый
  из четырёх изменённых AC (AC1, AC3, AC12, AC13) по-прежнему однозначен и
  называет способ доказательства; проблема не в форме, а в фактической
  достоверности содержания AC1.

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

- Не проверял HA-версии новее `2025.1.4` напрямую — недоступны в индексе pip
  этого окружения (то же ограничение, что и в r1). Это ровно тот пробел,
  из-за которого High-находка выше сформулирована как «не подтверждено», а не
  как «стопроцентно неверно»: теоретически upstream мог ввести такой ключ
  именно так, как описано, в версии между `2025.1.4` и «2026.2+», но ни одного
  подтверждения этому нет ни в коде, ни в вебе (недоступен), ни в остальной
  части репозитория.
- `WebSearch`/`WebFetch` недоступны в сессии (permission denied на оба вызова)
  — не смог свериться с release notes/документацией HA напрямую; вся
  верификация High-находки — по исходному коду ближайшей доступной версии и
  внутренней логике самого ТЗ.
- Не прогонял `typecheck`/`test`/`build` — этап spec, кода нет; гейты
  применимы к код-ревью (§2.7), не к этому этапу.
- Не проверял AC2, AC5–AC11 заново по существу — формулировки не изменились
  дельтой, приняты из r1 (см. «Унаследовано из r1»).
- Не оценивал разделы §13/§14/§17/§18/§20/§21 заново — дельта их не касалась
  (кроме упомянутых точечных правок в §21 про «три golden» и «десять кадров»,
  которые являются числовым уточнением существующего пункта r1, а не новым
  контрактом, и не меняют вывод r1 по этим разделам).

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

- Ветка: `issue/462-card-resource-registration`
- SHA материала: `e9e3d6bd7d8e61a0e7d561da76b19cedb157f32b`
- Дерево: `7bea3d2ffb5216214a550abe845e67d7b4680797`
- ТЗ `docs/specs/462-card-resource-registration.md`, блоб
  `c507644bf4fb0f5e902ddc4628497e329afeba3c`
- SHA r1 (для дельты): `12ddd107a9cdd9b12ea8411360760f684f5293c1`

---

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

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

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