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

SPEC-REVIEW-505-r1

Issue: https://github.com/Matysh/houseplan-card/issues/505 Стадия: ТЗ на ревью (S4-spec-review), полный трек (лёгкий отклонён аналитиком — сложность/риск >3, три поверхности, поддерживаемый touch-контракт). Заход: r1 (первый прогон ревью ТЗ для этой задачи). Материал: docs/specs/505-summary-panel-design-parity.md на SHA 8defee4ce1cb0f2794495c03173348c7a6c34e13 (ветка issue/505-summary-panel-polish, коммит «docs: specify summary panel designer parity»). Рабочая копия уже стоит на этом SHA.

1. Скоуп ревью

Задача расширена владельцем 2026-09-09: к четырём исходным UX-исправлениям (плавное скрытие панели, широкий диалог настроек, удаление Sizes on this screen, зависимость mobile-опции от master-переключателя) добавлено полное визуальное/поведенческое соответствие трёх поверхностей (шапка, панель, диалог настроек) прототипу Dashboard 5 из архива макет.zip (sha256:bc754c16c9…357e15).

Ревью охватывает:

• само ТЗ docs/specs/505-summary-panel-design-parity.md;
• вспомогательные документы docs/design/505-summary-panel/** (референс, handoff, README);
• обновление индекса docs/specs/README.md;
• соответствие ТЗ телу issue #505 и обоим комментариям аналитики (r1 «первая версия задачи», r2 «возобновление после расширения scope»);
• соответствие docs/SCOPE.md, AGENTS.md, PROCESS.md §7.1/§7.2/§5, docs/USER-GUIDE.ru.md, docs/TOUCH-SUPPORT.md, docs/CONFIG-COMPATIBILITY.md.

Это первый заход — раздела «Унаследовано из r0» не требуется, разбор полный.

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

• Прочитаны docs/SCOPE.md, AGENTS.md, PROCESS.md целиком (включая §2.4, §2.10, §4, §5, §7.1, §7.2, §9) перед оценкой.
• Прочитано тело issue #505 и все три комментария (аналитика r1, пауза владельца, возобновление аналитики r2 после расширения scope).
• Прочитан ТЗ-документ целиком (git show origin/issue/505-summary-panel-polish:docs/specs/505-summary-panel-design-parity.md).
• Проверены фактические утверждения ТЗ о текущем состоянии dev чтением кода:
  • renderPanel() в src/summary-panel-runtime-loaded.ts:182-192 действительно возвращает nothing сразу при !visible — exit-анимация невозможна, подтверждает описанную причину дефекта №1;
  • src/summary-panel-style.ts содержит только @keyframes hp-summary-in-right и hp-summary-in-bottom (строки 144–152) — входных keyframes для скрытия нет;
  • min-width в src/summary-panel-style.ts:156 навешен на .summary-editor (внутренний контент), а не на оболочку hp-dialog — подтверждает причину переполнения диалога;
  • src/summary-panel-editor.ts не связывает disabled mobile-чекбокса (строка ~102) с dialog.localShow — подтверждает независимость от master-переключателя;
  • summary-sizes-title/summary.sizes_title (строка 58) по-прежнему рендерится — раздел Sizes on this screen не удалён. Все пять фактических предпосылок ТЗ верны на названном SHA.
• Проверен механизм wide-диалога: --hp-dialog-wide-width уже используется (src/styles/dialogs.styles.ts:1592, device-inbox-dialog), hp-dialog.ts:163 читает эту переменную для .surface при wide — предпочтение ТЗ «переиспользовать системный wide-dialog contract» технически реализуемо без новой инфраструктуры.
• Проверено соответствие терминологии docs/USER-GUIDE.ru.md (раздел «Сводная панель», строки 261–314) — используемые в ТЗ названия настроек и поведение совпадают с зафиксированным пользовательским контрактом (общий/локальный scope настроек, ресайз-скрытие, mobile-политика). Обновление самого гайда корректно отнесено к §9 «Release artifacts» реализации, а не к этапу ТЗ.
• Проверено docs/TOUCH-SUPPORT.md:48-56 — сводная панель и её простая форма настроек явно объявлены полноценной View-поверхностью с 44×44 px целями; требования ТЗ по touch-таргетам этому не противоречат.
• Проверено docs/CONFIG-COMPATIBILITY.md:100-132 («Summary panel namespace (#437)») — утверждение ТЗ «Config namespace stays version1; compatibility registry/storage shapes do not change» и утверждение, что локальные size-preferences — браузерные runtime-данные вне серверного конфига, соответствуют канону; удаление UI-раздела Sizes on this screen не требует правки этого документа.
• Проверена целостность референс-архива: docs/design/505-summary-panel/reference/ содержит воспроизводимый index.html, CSS/JS/SVG и три handoff-документа; README задачи и README референса указывают SHA-256 архива и совпадают между собой и с телом issue.
• Сверено обновление docs/specs/README.md — строка для #505 добавлена.
• Прогнан node scripts/process-gate.mjs --range origin/dev..origin/issue/505-summary-panel-polish → «гейт пройден, предупреждений 0» (офлайн-часть; статус issue не проверялся флагом --issues, т.к. факт статуса уже виден в метках issue: S4-spec-review, без blocked).
• Проверены трейлеры коммита 8defee4c: Issue: #505, User-Visible: no — корректно для документации без изменения продуктового поведения.
• Проверен CI: gh run list --branch issue/505-summary-panel-polish → прогон 34316129681, completed/success, headSha == 8defee4ce1cb… — точный SHA материала. (Уточнение к вводным этого ревью: там указано, что зелёного Validate на этом SHA не найдено — это было неверно, прогон найден и зелёный; дешёвые гейты дополнительно вручную не гонялись, так как класс изменений — только C (документация), продуктовый код не тронут, и зафиксированный CI прогон уже покрывает docs/process-gate/provenance.)
• Сверена диффа git diff origin/dev..origin/issue/505-summary-panel-polish --stat — только docs/**, класс C; продуктовый код (src/**, custom_components/**) не изменён, что и требуется на этапе ТЗ.

3. Находки

Medium — отсутствуют обязательные первые разделы «Сценарий» и «Что человек увидит до и после» (PROCESS.md §7.1)

docs/specs/505-summary-panel-design-parity.md, раздел 1 «Problem, value and scope» объединяет проблему, ценность и скоуп, но нигде явно не называет: какая персона (docs/SCOPE.md: home admin / household members / kiosk) на какой поверхности и в какой момент встречает это изменение, и не даёт отдельной фразы «что человек увидит до и после» без терминов реализации. PROCESS.md §7.1 требует эти два раздела первыми и явно: «ТЗ, которое не может ответить на эти два вопроса, описывает работу, а не изменение продукта». Это не абстрактное требование формата — непосредственно предшествующий и тематически связанный ТЗ того же автора, docs/specs/493-summary-panel-hardening.md (issue #493, та же подсистема, тот же день), содержит именно эти два раздела первыми (## 1. Сценарий, ## 2. Что человек увидит до и после, строки 11 и 24), то есть автору конвенция известна и обычно соблюдается — здесь она пропущена целиком, а не сокращена.

Сценарий проявления: ревьюер (или будущий читатель ТЗ, включая ревьюера кода на следующем этапе) не может быстро проверить, что изменение решает заявленный пользовательский сценарий, а не просто список визуальных требований — именно такой класс дефекта («AC выполнены, но сценарий не решён») явно разрешён как основание для жёлтого вердикта в PROCESS.md §2.4/§7.2. Материал, впрочем, косвенно восстановим (персоны и поверхности разбросаны по §2–3 и по комментарию аналитики), поэтому находка — дефект формы и трассируемости, а не скрытая двусмысленность поведения; поэтому Medium, а не High.

Как чинится: добавить в начало документа (перед текущим «1. Problem, value and scope», со сдвигом нумерации) два раздела по образцу #493 — «Сценарий» (admin/household member/kiosk-пользователь на View/kiosk/диалоге настроек, в момент открытия карточки, включения показа или редактирования блоков) и «Что человек увидит до и после» (одной фразой, без терминов реализации: сейчас составной контрол и панель визуально не совпадают с согласованным прототипом и не позволяют держать диалог настроек без горизонтальной прокрутки; после — шапка/панель/диалог выглядят и ведут себя как согласованный дизайн, функционал не теряется).

Medium — отсутствует обязательный раздел «Принятые технические предположения» (PROCESS.md §7.1/§7)

ТЗ #505 не содержит финального блока «принято предположительно, поменять свободно», хотя делает по ходу текста ряд односторонних технических решений, которые пользователь не наблюдает и которые PROCESS.md §7 прямо требует выносить в такой явный блок, чтобы ревьюер мог их оспорить: точное имя CSS custom property для реального HA-диалога (--ha-dialog-width-md, §6, помечено «verify actual pinned HA frontend contract», то есть уже осознаётся как непроверенное), состав и расположение новых файлов реализации (§7, «Expected files: …»), новые i18n-ключи и их точные имена (§6), решение переиспользовать --hp-dialog-wide-width вместо отдельного механизма. Ни один из этих пунктов не проходил как продуктовый вопрос владельцу (и не должен был), но без явного блока они читаются как окончательные решения ТЗ, а не как предположения, которые исполнитель волен скорректировать при сохранении AC. Тот же #493 (строки 462 и далее, «## 20. Принятые технические предположения», 7 пунктов) — прямой прецедент того же автора для той же подсистемы, показывающий, что формат достижим без дополнительной информации: большая часть содержимого уже есть в тексте ТЗ, недостаёт только явного заголовка и итоговой фразы «эти пункты не меняют видимый контракт и могут быть скорректированы ревьюером при сохранении AC».

Как чинится: добавить раздел «Принятые технические предположения» в конец документа (после текущего раздела 9), перечислив как минимум: точное имя CSS-переменной ширины real-HA диалога подлежит проверке при реализации; состав файлов из §7 ориентировочный; конкретные ключи i18n, кроме перечисленных как обязательные, могут быть переименованы при сохранении семантики; способ хранения generation-guard для анимации (упомянут в §4, но не в отдельном пункте — имя/модуль структуры state machine не названы явно как свободные).

Low — неполный список визуальных пар в разделе доказательств (§8)

Абзац «Visual evidence is mandatory» в конце §8 перечисляет «control+open right panel and settings, dark desktop, bottom portrait, kiosk; plus narrow native/real HA settings screenshots». Чек-лист самого issue («Дополнительные критерии приёмки», пункт 4) требует пары «desktop light/dark, bottom, kiosk, mobile» — пять явно названных контекстов. В тексте ТЗ явно назван «dark desktop», но не назван отдельно «light desktop» (light, предположительно, подразумевается базовым/неотмеченным вариантом «control+open right panel and settings»), и «mobile» из чек-листа issue визуально не отделён от «narrow native/real HA settings screenshots» — неясно, требуется ли отдельная пара для мобильного отображения самой панели (не только диалога настроек) в узкой View. Это не блокирует понимание общего требования (AC10 дополнительно требует смок-проверку 320/390/desktop, light/dark, RU/EN/DE/FR), и не меняет ни одного AC по существу, поэтому не блокирует зелёный вердикт — достаточно явно перечислить все пять контекстов из чек-листа issue при правке двух Medium-находок выше, либо оставить как есть с запиской, что реализация интерпретирует this list по образцу issue буквально. Снимается автором на своё усмотрение с пометкой в ТЗ.

4. Что проверено и корректно

• Формат этапа: issue не помечен small/trivial, полный трек выбран и обоснован дважды (первичная аналитика — сложность/риск >3 и touch-контракт; повторная аналитика после расширения scope — три поверхности плюс touch), файл ТЗ существует по правильному пути и имени (docs/specs/505-summary-panel-design-parity.md), ссылки issue↔ТЗ на месте.
• Продуктовая рамка: задача остаётся внутри одобренного исключения #437 из docs/SCOPE.md (read-only summary overlay); ТЗ явно перечисляет, что НЕ переносится из демо (fake data, localStorage, HA-хром, сворачивание блоков, отдельные экранные размеры) — совпадает и с §2 SCOPE.md, и с телом issue.
• Приоритет источников истины задан явно и в правильном порядке: owner requirements > текущие контракты House Plan (данные/безопасность/a11y) > визуальный референс > детали демо-реализации — снимает риск слепого копирования прототипа поверх контрактов.
• Технический анализ причин всех четырёх исходных дефектов подтверждён чтением актуального кода (см. §2 выше) — не голословен.
• Явное разведение прототипной и продуктовой логики там, где они расходятся: IMPLEMENTATION-NOTES.md референса описывает выбор позиции по matchMedia("orientation: portrait"), тогда как ТЗ §3 прямо фиксирует, что действующий resolver «stage width >= height => right» авторитетен и не является viewport-ориентацией — корректное решение конфликта в пользу существующего контракта, а не слепое копирование демо.
• AC1–AC11 пронумерованы, у каждого явно указан способ доказательства (smoke/визуальная сверка/runtime-тест/gate), не перекрываются бессмысленно и покрывают все пункты обоих чек-листов issue (четыре исходных + расширенные). Для дорогих защитных проверок (AC3 exit-DOM-retention, AC5 shell-wide sizing) явно требуется отрицательный свидетель и mutation-gate — соответствует PROCESS.md §2.7 «чем краснеет».
• Анимационная state machine (§4) описана как явные состояния hidden→entering→visible→exiting→hidden с generation-guard против «призраков», явно перечисленными граничными случаями (reduced motion, resize/anchor change, скрытый документ, смена identity, editor entry) — не оставляет открытых вопросов по логике жизненного цикла.
• Config-совместимость и данные не меняются (namespace version 1, local-only size prefs вне серверного конфига) — подтверждено docs/CONFIG-COMPATIBILITY.md, миграция не требуется, откат тривиален.
• i18n: новые ключи перечислены явно (en/ru/de/fr), с условием на переиспользование существующих и удаление summary.sizes_title только при отсутствии других потребителей — проверяемо статическим поиском на этапе код-ревью.
• Touch/a11y: 44×44 px, disabled-семантика, keyboard/focus traversal — согласовано с docs/TOUCH-SUPPORT.md, который прямо относит эту поверхность к гарантированному View-контракту, а не к best-effort editor.
• Продуктовых вопросов владельцу не осталось — оба комментария аналитики подтверждают это, и текст ТЗ действительно не содержит скрытых догадок о видимом поведении, выданных за факт (единственное место, где остаётся неопределённость — имя HA CSS-переменной — прямо помечено как требующее проверки, а не заявлено как факт).
• Процесс/гейты: коммит несёт корректные трейлеры, process-gate.mjs проходит без предупреждений, CI зелёный на точном материале ревью, диапазон диффа ограничен классом C (документация), продуктовый код не тронут — как и должно быть на этапе ТЗ.
• Индекс docs/specs/README.md обновлён.

5. Чего не проверял

• Пиксельное сравнение реализации с прототипом — на этапе ТЗ реализации не существует, сверка станет обязанностью код-ревью (AC1/AC2/AC6/AC10 явно требуют парные скриншоты как доказательство).
• Тяжёлые браузерные гейты (golden, smoke_*, performance_smoke, pytest tests_backend) не запускались — не относится к этапу ТЗ, продуктовый код и тесты не изменены этим коммитом.
• Флаг --issues у process-gate.mjs не использовался (нужен токен с широким доступом к Issues API сверх текущего); статус подтверждён напрямую через gh issue view — ровно одна метка S4-spec-review, без blocked.
• Не проверялось содержимое самого архива макет.zip за пределами зафиксированного SHA-256 и распакованных docs/design/505-summary-panel/reference/** файлов — оригинальный архив в репозиторий не входит, воспроизводимость обеспечена самими распакованными файлами.

6. Вердикт

High: 0. Medium: 2 (обе — дефект формата ТЗ по PROCESS.md §7.1, в скоупе текущей задачи, чинятся правкой того же документа без нового технического исследования). Low: 1 (снимается автором на своё усмотрение).

Обязательные разделы присутствуют по существу содержания, но не по форме, предписанной PROCESS.md §7.1 и подтверждённой прецедентом #493 того же автора; это возврат на доработку ТЗ, а не отклонение — формат восстановим без нового анализа.

Вердикт: жёлтый · заход r1 · блокирующих циклов 1/4 · High: 0 · Medium: 2 → в задаче

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

• Ветка: issue/505-summary-panel-polish
• SHA материала: 8defee4ce1cb0f2794495c03173348c7a6c34e13
• Дерево ТЗ: docs/specs/505-summary-panel-design-parity.md на указанном SHA
• Поиск при устаревании ветки: git log --all --format='%H %T' | grep <дерево HEAD^{tree}> git log --all --find-object=<блоб docs/specs/505-summary-panel-design-parity.md> -- docs/specs/505-summary-panel-design-parity.md

---

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

• Ветка: issue/505-summary-panel-polish, коммит 8defee4ce1cb — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
• Дерево материала: eddbf58ae62fc94849148a7d3881d5543cf16870

  git log --all --format='%H %T' | grep eddbf58ae62f
  

• ТЗ docs/specs/505-summary-panel-design-parity.md, блоб 61a52163e5a30f3b86f24de3ace9fbd6ebb4e0a5

  git log --all --find-object=61a52163e5a30f3b86f24de3ace9fbd6ebb4e0a5 -- docs/specs/505-summary-panel-design-parity.md
  

• Вердикт конвейера: yellow · High 0