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

SPEC-REVIEW-505-r2

Issue: https://github.com/Matysh/houseplan-card/issues/505 Стадия: ТЗ на ревью (S4-spec-review), полный трек (не пересматривается в r2 — основание трека не затронуто дельтой). Заход: r2 · блокирующих циклов израсходовано 1 из 4 (жёлтый r1 бюджет потратил; зелёный r2 цикла не образует, #227). Материал: docs/specs/505-summary-panel-design-parity.md на SHA 8c0962f36f2b93dd0c043806aa2e838d570fcd1c (ветка issue/505-summary-panel-polish, коммит «docs: address summary panel spec review r1»). Рабочая копия уже стоит на этом SHA (HEAD detached at origin/issue/505-summary-panel-polish).

1. Скоуп ревью — почему разбор по дельте

Предыдущий раунд: docs/reviews/SPEC-REVIEW-505-r1.md, вердикт жёлтый, заход r1, High 0 / Medium 2 / Low 1, материал на SHA 8defee4ce1cb0f2794495c03173348c7a6c34e13. SHA в вердикте r1 назван явно (в самом документе, раздел «Материал раунда») — расследовать не пришлось.

Дельта: git diff 8defee4ce1cb0f2794495c03173348c7a6c34e13..8c0962f36f2b93dd0c043806aa2e838d570fcd1c затрагивает ровно два файла:

• docs/reviews/SPEC-REVIEW-505-r1.md — публикация документа r1 конвейером (не предмет разбора, это чужой артефакт);
• docs/specs/505-summary-panel-design-parity.md — 46 insertions / 5 deletions, единственный коммит 8c0962f3 с трейлерами Issue: #505 / User-Visible: no.

Правка сугубо аддитивна и локальна:

1. добавлены два новых раздела в начало документа — «Сценарий» и «Что человек увидит до и после» (перед прежним «1. Problem, value and scope»);
2. переписан один абзац в конце §8 (список визуальных пар);
3. добавлен раздел «Принятые технические предположения» в конец документа (после прежнего раздела 9).

Ни один из существующих разделов 1–9, таблица AC1–AC11, Baseline (dev@abbca50c), тело issue (updated_at issue = момент последнего комментария автора, содержимое не менялось со времени r1 — сверено построчно) не тронуты. Это не ребейз (baseline тот же abbca50c), не смена контракта поведения, не новая подсистема, объём дельты (46 строк) на порядок меньше исходного ТЗ (291 строка). Разбор по дельте: полная переоценка нужна только находкам r1 и участку текста, который они затронули; AC1–AC11 и весь технический анализ §2–7 наследуются без повторной проверки.

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

• git diff 8defee4c..8c0962f3 -- docs/specs/505-summary-panel-design-parity.md — построчно, для локализации правки и проверки отсутствия побочных правок.
• Полное чтение текущего файла docs/specs/505-summary-panel-design-parity.md на SHA 8c0962f3 (не только диффа) — чтобы увидеть новые разделы в контексте, а не изолированно.
• Прочитан текст issue #505 и все 5 комментариев (аналитика ×2, пауза, возобновление, r1-вердикт, отчёт о правках) — подтверждено, что тело issue и объём scope не менялись после r1, и что комментарий автора (comment 4) корректно описывает содержание фактической правки.
• Проверено соответствие терминологии персон в новом разделе «Сценарий» канону docs/SCOPE.md:28-30 — «Home admin» / «Household members» / «Guests / kiosk» и их типовые поверхности (desktop / phone / wall tablet kiosk) совпадают дословно по смыслу с «Администратор дома на desktop», «домочадец ... на телефоне», «гость ... в киоске».
• Проверено, что новые разделы не содержат терминов реализации (CSS/код/имена функций) — только пользовательское поведение и персоны, как требует PROCESS.md §7.1.
• Проверено, что раздел «Принятые технические предположения» стоит в конце документа (после раздела 9), как требует PROCESS.md §7 («записывается явным блоком в конце ТЗ»), и что все четыре односторонних технических решения, названные в r1-находке M2 (имя CSS-переменной, состав файлов, имена i18n-ключей, механика generation-guard/анимации), в явном виде перечислены.
• Проверено, что расширенный абзац visual evidence в §8 перечисляет все пять контекстов чек-листа issue («Дополнительные критерии приёмки», пункт 4) отдельно: desktop light, desktop dark, bottom portrait, kiosk, mobile View panel — плюс отдельно диалог настроек light/dark desktop и narrow native/real HA.
• grep -n '§[0-9]\|Sections' по всему файлу — все существующие перекрёстные ссылки (§2–3, Sections4–8, §2, §7, §6) продолжают указывать на прежние номерованные разделы 1–9; новые разделы намеренно не пронумерованы и не сдвинули нумерацию, поэтому ни одна ссылка не сломана. Это лучше, чем предложенный в r1-находке M1 вариант «со сдвигом нумерации» — автор выбрал более безопасный способ починки, не создав новый класс дефекта (битые ссылки на разделы).
• Прогнан node scripts/process-gate.mjs --range 8defee4c..8c0962f3 → «гейт пройден, предупреждений 0» (офлайн-часть; --issues не запускался — статус issue уже виден в метках: S4-spec-review, без blocked).
• Проверены трейлеры коммита 8c0962f3: Issue: #505, User-Visible: no — корректно, правка чисто документационная.
• Проверен CI на точном материале ревью: gh run view 34316874922 → Проверка (CI), headSha == 8c0962f36f2b93dd0c043806aa2e838d570fcd1c, status: completed, conclusion: success. Детализация по джобам (gh api .../commits/8c0962f3.../check-runs): лёгкие джобы «Фронтенд: типы, юниты, мутанты, синхрон бандла», «Предполётные проверки: документация, провенанс, процесс», «Классификация изменённых файлов», «Мутанты по диффу (1–3/3)», «Переиспользование: это дерево уже проверено» — все success; тяжёлые джобы (смоки, golden, perf, backend pytest, HACS/Hassfest) — skipped, что ожидаемо для чисто документационного диффа класса C. Уточнение к вводным этого раунда: там указано «Зелёного Validate на этом SHA нет — прогон не найден, не завершён либо не success» — это не подтвердилось, как и в r1 с тем же типом утверждения; прогон найден и зелёный именно на материале ревью. Дополнительно вручную дешёвые гейты не гонялись сверх process-gate.mjs — диапазон диффа ограничен docs/** (git diff --stat origin/dev..8c0962f3 подтверждает, что src/**/custom_components/** не тронуты во всей ветке), поэтому tsc/npm test/npm run build/ check-docs.mjs к предмету этого раунда не относятся, а к предмету всей ветки их уже покрыл зафиксированный зелёный CI-прогон на этом SHA.

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

Находка r1	Чем закрыта	Где это видно
Medium — отсутствуют разделы «Сценарий» и «Что человек увидит до и после» (PROCESS.md §7.1)	Оба раздела добавлены первыми в документе, до прежнего «1. Problem, value and scope»; названы персоны admin/household member/guest-kiosk по канону SCOPE.md, одна фраза «что увидит» без терминов реализации	docs/specs/505-summary-panel-design-parity.md:9-22 (в текущем файле на 8c0962f3)
Medium — отсутствует раздел «Принятые технические предположения» (PROCESS.md §7/§7.1)	Раздел добавлен в конец документа; перечислены все 4 пункта из находки: имя CSS-переменной real-HA диалога помечено как подлежащее проверке, состав файлов §7 назван планом реализации, имена i18n-ключей допущены к переименованию при сохранении семантики, механика lifecycle-анимации (CSS transitions/WAAPI, generation guards) явно оставлена на усмотрение реализации	docs/specs/505-summary-panel-design-parity.md:271-291
Low — неполный список визуальных пар в §8	Абзац переписан, все пять контекстов чек-листа issue названы отдельно поимённо (desktop light/dark, bottom portrait, kiosk, mobile View panel) плюс отдельно диалог настроек	docs/specs/505-summary-panel-design-parity.md:233-243

Все три находки закрыты правкой того же файла без нового технического исследования, как и предполагал вердикт r1 («формат восстановим без нового анализа»). Новых дефектов формата правка не внесла — численность и ссылки разделов 1–9 не пострадали (см. §2 выше).

4. Унаследовано из r1

Принято без повторной проверки в этом раунде, основание — документ docs/reviews/SPEC-REVIEW-505-r1.md на SHA 8defee4ce1cb0f2794495c03173348c7a6c34e13, поскольку дельта r1→r2 не затрагивает предмет этих пунктов:

• продуктовая рамка и соответствие docs/SCOPE.md (исключение #437 для read-only summary overlay), приоритет источников истины owner > контракты House Plan > прототип > демо;
• технический анализ причин всех четырёх исходных дефектов, подтверждённый чтением кода dev@abbca50c (renderPanel() возвращает nothing без exit-анимации, отсутствие exit-keyframes, min-width на .summary-editor, несвязанный mobile-чекбокс, нерасширенный Sizes on this screen);
• корректность механизма wide-диалога (--hp-dialog-wide-width, hp-dialog.ts:163) как технически реализуемого пути;
• согласованность с docs/USER-GUIDE.ru.md (раздел «Сводная панель»), docs/TOUCH-SUPPORT.md:48-56 (44×44 px, гарантированный View-контракт), docs/CONFIG-COMPATIBILITY.md:100-132 (namespace version 1 не меняется, local size prefs вне серверного конфига);
• целостность референс-архива docs/design/505-summary-panel/reference/** и совпадение SHA-256 между README задачи, README референса и телом issue;
• обновление docs/specs/README.md (строка для #505 добавлена);
• полнота и однозначность таблицы AC1–AC11, включая требование отрицательного свидетеля и mutation-gate для дорогих AC3/AC5;
• отсутствие открытых продуктовых вопросов владельцу (текст ТЗ не выдаёт догадку за факт нигде, кроме явно помеченного «verify actual pinned HA frontend contract»).

Эти пункты дельта r2 не касается: ни один из трёх изменённых участков текста (два новых вводных раздела, абзац visual evidence, финальный блок предположений) не переопределяет и не сужает ни один из перечисленных пунктов.

5. Находки (r2)

Нет. Дельта полностью закрывает обе Medium- и одну Low-находку r1, не привнося нового дефекта содержания или формата.

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

• Все три находки r1 закрыты по существу (см. таблицу §3), а не переформулированы без изменения сути.
• Терминология персон в новом разделе «Сценарий» — канонические термины docs/SCOPE.md, не изобретённые.
• «Что человек увидит до и после» — одна фраза, без терминов реализации, как требует PROCESS.md §7.1.
• «Принятые технические предположения» размещены в конце документа и явно разрешают ревьюеру их оспорить — соответствует формулировке PROCESS.md §7.
• Правка не переименовала и не сдвинула номера существующих разделов — все внутренние перекрёстные ссылки (§2–3, §6, §7, Sections4–8) остались корректны.
• Baseline (dev@abbca50c), таблица AC1–AC11 и весь технический контракт поведения (§2–7, §9) в дельте не менялись — не о чем спорить заново.
• Коммит несёт корректные трейлеры (Issue: #505, User-Visible: no — верно для чисто документационной правки), process-gate.mjs проходит без предупреждений на диапазоне r1→r2.
• CI зелёный именно на материале этого раунда (8c0962f3, run 34316874922, Проверка (CI)), включая релевантные для класса C джобы (фронтенд типы/юниты/мутанты/синхрон бандла, предполётные документация/провенанс/ процесс).
• Диапазон всей ветки dev..8c0962f3 подтверждён как класс C: только docs/**, продуктовый код не тронут.

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

• Полный повторный разбор разделов 1–9 и таблицы AC1–AC11 — не требуется, дельта их не касается (обоснование в §1 и §4 выше).
• Пиксельное сравнение реализации с прототипом и тяжёлые браузерные гейты (golden, smoke_*, performance_smoke, pytest tests_backend) — как и в r1, не относится к этапу ТЗ; продуктовый код по-прежнему не существует и не менялся.
• Содержимое архива макет.zip за пределами зафиксированного SHA-256 — не переисследовалось повторно, наследуется из r1.
• Флаг --issues у process-gate.mjs — статус issue подтверждён напрямую через gh issue view (метка S4-spec-review, без blocked).

8. Вердикт

High: 0. Medium: 0. Обе Medium- и одна Low-находка r1 закрыты правкой того же документа, дельта не привнесла нового дефекта. Дельта локальна (один файл документации, 46/5 строк, без ребейза, без смены baseline, без смены контракта поведения) — полный переразбор не требуется и не проводился.

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

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

• Ветка: issue/505-summary-panel-polish
• SHA материала: 8c0962f36f2b93dd0c043806aa2e838d570fcd1c
• Дерево материала: 2af4e1c1420a56d9914b793d60e8024fd3181f16

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

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

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

• Предыдущий раунд: docs/reviews/SPEC-REVIEW-505-r1.md, SHA 8defee4ce1cb0f2794495c03173348c7a6c34e13
• Вердикт конвейера: green · High 0 · Medium 0

---

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

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

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

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

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

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