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

# SPEC-REVIEW-561-r1

## Скоуп

Issue #561 (`bug`, `P3`, `S4-spec-review`, полный трек — критерий `small`
«сложность/риск ≤3» не пройден, о чём аналитика прямо сказала). Предмет: устойчивость
identity локальных настроек сводной панели (`show`/`icon_scale`/`font_scale`) в
нативном HA Masonry после полного reload/rebalancing колонок, когда `stableSummaryPlacementSlot()`
строит ключ из фактического DOM-пути (включая номер визуальной колонки), а не из
канонического порядка `hui-masonry-view.cards`. ТЗ живёт в теле issue, раздел `## ТЗ`,
как того требует #517.

Материал ревью: тело issue #561 на момент разбора (нормализованный `sha256` тела
фиксирует сам конвейер в блоке якорей — вручную не пересчитывал). Рабочее дерево
репозитория — `b26d9694` (`origin/dev`), совпадает с материалом, названным в задании.

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

- Прочитаны `docs/SCOPE.md` (J1/J6, персоны, touch-контракт), `AGENTS.md`, `PROCESS.md`
  §1–§7 целиком, `docs/TOUCH-SUPPORT.md` целиком.
- Прочитано тело issue #561 целиком (постановка риска + `## ТЗ`) и оба комментария
  (`S2 — аналитика`, `Вопрос владельцу Q1`) через `gh issue view 561 --json body,comments`.
- Прочитан текущий код, который ТЗ обязуется заменить: `src/summary-panel-identity.ts`
  (`stableSummaryPlacementSlot`, `structuralPath`, `enclosingNativeCard`) и
  `src/summary-panel-runtime-loaded.ts` (`preferenceKey`, `loadLocal`, `saveLocal`,
  использование `storage_unavailable`).
- Прочитан `src/summary-panel.ts` (`summaryLocalKey`, `parseSummaryLocal`,
  `SUMMARY_PANEL_LEGACY_SCALE_KEY`) — проверка, что «legacy scale seed» в AC5 это
  существующий отдельный глобальный ключ `houseplan_card_kiosk_v1`, а не спорный
  per-card DOM-ключ, то есть решение владельца по Q1 (старые DOM-path ключи не
  переносятся) этому не противоречит.
- Прочитан существующий регресс-тест `test/summary-panel.test.mjs`
  (`#437 placement identity survives Masonry reflow and inner-card remount`,
  строки 249–268): подтверждено буквально то, что говорит аналитика — тест
  переставляет уже созданные `firstWrapper`/`secondWrapper` внутри `masonry.children`
  (same-wrapper reflow), но никогда не создаёт новые wrapper-объекты для полного
  reload. Значит новый AC1 (новые `view/card/column` объекты) — это не дублирование
  существующего покрытия, а реально недостающий кейс.
- Прочитан архивный `docs/specs/437-summary-panel.md` §8.2 (строки 419–443): исходный
  контракт #437 уже требовал для Masonry «индекс в исходном cards, не номер визуальной
  колонки» — то есть #561 закрывает именно расхождение между тем контрактом и
  фактической реализацией, а не придумывает новый.
- Проверено существование всех файлов, которые ТЗ называет затронутыми:
  `src/summary-panel-identity.ts`, `src/summary-panel-runtime-loaded.ts`,
  `test/summary-panel.test.mjs`, `scripts/mutation-gate.mjs`, `demo/smoke_summary_panel.mjs`
  (и соседние `smoke_summary_*`) — все на месте.
- Проверен текст `summary.storage_unavailable` (`src/summary-panel-i18n.ts:45,113,181,249`):
  «These screen settings work for this session but cannot be saved in this browser» —
  достаточно нейтрален, чтобы AC4 мог переиспользовать его для «identity ещё не
  разрешена», не вводя новый i18n-ключ, как ТЗ и заявляет.
- Код продукта не менял и не правил — только ревью ТЗ.

## Находки

### Medium (в скоупе задачи — возврат автору, отдельный issue не заводится)

**M1. ТЗ не называет явно влияние на touch/View/kiosk — обязательный, блокирующий
пункт DoR (§2.5: «влияние на touch по `docs/TOUCH-SUPPORT.md` (View и киоск —
блокирующие)»).**

- Файл: тело issue #561, раздел `## ТЗ`.
- Слово «touch» и «kiosk»/«киоск» не встречается в тексте ТЗ ни разу
  (`gh issue view 561 --json body -q '.body' | grep -ni "touch\|kiosk\|киоск"` —
  пусто).
- `docs/TOUCH-SUPPORT.md` прямо называет сводную панель поддерживаемой View-
  поверхностью и требует, чтобы она «remain usable after backgrounding, resize,
  orientation changes and warm remount», а киоск — «Primary supported environment»
  для View. Ротация планшета в киоске — это ровно тот случай, который контракт п.2
  ТЗ описывает технически («адаптивный переход между разным числом Masonry-колонок»)
  и который покрывают AC1/AC3, просто без слова «touch/kiosk» рядом.
- Из-за этого DoR-пункт формально не закрыт: пятый пункт чек-листа «Готово к
  разработке» (§2.5) требует явного утверждения, а не подразумеваемого. Это не
  находка о реальном дефекте поведения — по существу сценарий уже покрыт AC1/AC3 —
  а находка о неполноте самого ТЗ как артефакта, обязательного для перехода в
  `S5-ready`.
- **Как закрыть:** одно-два предложения в разделе 2 или 6, прямо говорящие
  `Touch/kiosk: …`, с указанием, какой AC доказывает переживание ориентации/resize
  на киоск-планшете (по факту — уже написанные AC1/AC3), либо явное «не влияет,
  потому что…», если авторы считают иначе.

### Low (снимаю с записью, не блокирует)

**L1. Разделы «сценарий» и «что человек увидит до/после» не оформлены отдельными
подзаголовками первыми, как того требует PROCESS.md §7.1** («Два первых раздела —
продуктовые, и они идут первыми не случайно»). По содержанию оба вопроса закрыты:
раздел 1 («Проблема и цель») называет персону через контекст #437/SCOPE J1/J6 и
условия появления бага, раздел 2 («Пользовательский контракт», особенно пункты 1–2)
формулирует «что человек увидит» без терминов реализации («местные настройки
остаются независимыми», «сохраняют настройку именно своей карточки»). Снимаю: смысл
присутствует, реорганизация — не более чем польза для читаемости, откладывать
задачу ради неё нецелесообразно.

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

- **Риск не выдан за факт** (проверка на «пользователь заявил догадку решением»):
  ключевое утверждение аналитика — расхождение с реальным `hui-view.ts`/
  `hui-masonry-view.ts` пинованной версии `20260729.7` — подтверждено конкретными
  ссылками на исходники HA с номерами строк в комментарии `S2`, а не голым
  заявлением. Технические детали контракта раздела 3 (canonical index, порядок
  обхода composed ancestors, поведение WeakMap-кеша) прослеживаются к реальному
  коду `summary-panel-identity.ts`, который они заменяют, — ни одного пункта,
  придуманного без опоры на существующий код или подтверждённое поведение HA.
- **Единственный продуктовый вопрос (Q1) задан и решён предсказуемо**: дефолт
  («не переносить неоднозначные ключи, обычные defaults, пользователь один раз
  перенастраивает») зафиксирован в разделе 2 п.5 как решение владельца и совпадает
  с рекомендованным по умолчанию вариантом из вопроса — не более широкое и не
  более узкое решение, чем спрашивалось.
- **Технические допущения промаркированы, а не выданы за факт**: раздел 8 явно
  помечает как «принято предположительно, менять свободно» — форму версии/имени
  slot (`masonry-v2:<index>`), сохранение после явного reorder (уже было решено
  в #437, не ново), выбор «unresolved лучше эвристической записи».
- **Каждый AC1–AC8 указывает способ доказательства** (unit/unit/unit/unit-runtime/
  unit/unit/mutation/frontend) и сформулирован как проверяемое утверждение, а не
  пожелание: у AC1 явно назван негативный якорь («старый slot C никогда не равен
  новому slot B» — это прямое повторение воспроизведённого дефекта, а не общая
  фраза).
- **AC7 — именно защитный AC с названным мутантом** (замена canonical-index на
  visual-column index / снятие fail-closed guard), что закрывает системную дыру,
  которую сам процесс называет причиной прошлых проблем (#435, #423): дефектный
  guard, зелёный без единого мутанта. Здесь мутант закладывается уже на этапе
  спецификации.
- **Скоуп не размыт**: явно исключены новый `card_id`, серверная миграция,
  перенос предпочтений после ручного reorder (наследие #437), расширение на
  Sections/unknown wrappers. Ничего из этого не просочилось в AC под видом
  «заодно поправим».
- **Откат и release-артефакты названы**: откат — вернуть прежний resolver и тесты,
  без миграции данных; changelog RU+EN, `docs/ARCHITECTURE.md`/`docs/TESTING.md`
  затронуты по существу (источник identity меняется).
- **i18n и совместимость сервера/конфигурации явно закрыты** («не меняются») —
  соответствует тому, что фактически меняется только клиентский resolver.
- **Формат: "small" не подходит и это названо явно** аналитиком («сложность и
  риск 5/10… не проходит критерий `small` «сложность и риск ≤3»; затрагивается
  browser-local compatibility-контракт ключей») — соответствует требованию §338
  называть нарушенный критерий, а не просто выбрать полный трек.

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

- Не запускал никакие гейты (`typecheck`/`test`/`build`/`mutation-gate`) — на этапе
  ревью ТЗ кода ещё нет, реализация не начата (`S6-in-progress` не наступил),
  проверять нечего.
- Не проверял реальное поведение `hui-masonry-view.cards` в живом Home Assistant —
  доверился ссылкам на исходники HA `20260729.7` в комментарии аналитика (конкретные
  файлы и диапазоны строк), сам HA-фронтенд не разворачивал.
- Не проверял # 493 и #552 построчно на предмет пересечения — принял утверждение
  аналитика об отсутствии дублирования на основании описанных в issue отличий
  (repeated `setConfig`/lifecycle vs E2E journeys vs identity resolution), не
  вычитывал сами issue #493/#552.
- Не оценивал, отвечал ли владелец на Q1 именно комментарием в GitHub — в треде
  issue отдельного ответа нет, но раздел 2 п.5 ТЗ фиксирует решение текстом,
  совпадающим с предложенным дефолтом; процесс не требует, чтобы решение владельца
  обязательно приходило тем же каналом, что вопрос.

## Вывод

Единственная блокирующая (в бюджете цикла) находка — M1, чисто оформительская по
существу (сценарий уже спроектирован и покрыт AC1/AC3), но формально пропущенный
обязательный пункт DoR. High-находок нет. Вердикт — жёлтый: автор дописывает
явное указание touch/kiosk-влияния (или явное «не применимо» с обоснованием) в
тот же раздел ТЗ, без пересмотра AC/контракта, и документ уходит на второй заход.

---

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

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

- Ветка: `dev`, коммит `b26d9694025e` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
- Дерево материала: `22783006accc33717edd960c94098bf536d89e25`
  ```
  git log --all --format='%H %T' | grep 22783006accc
  ```
- Тело issue: `5c619c9775f834a6607d8623a303f1ba412d1f0cf9c4f4fa8b0e2fcf50cef47b`
- Вердикт конвейера: `yellow` · High 0