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

SPEC-REVIEW — Issue #54 · заход r2

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

Скоуп раунда

Этап — ревью ТЗ (PROCESS.md §2.4). Раунд не первый: разбор ведётся по дельте (PROCESS.md §2.9, issue #214), а не заново.

• Вердикт r1: жёлтый, SHA a6a3df931079a008dd4e7f7d602800e46c353192 (полный: a6a3df931079a008dd4e7f7d602800e46c353192 — совпадает с git log как a6a3df93 docs: specify contextual zigbee links). SHA в вердикте r1 был назван явно — не находка.
• Правка автора: коммит aed0b5b65a0d47b99fb15f139a183945558b41a4 (aed0b5b6 docs: address zigbee spec review), трейлеры Issue: #54, User-Visible: no — корректно, изменён только текст ТЗ, продуктовый код не тронут.
• Дельта: git diff a6a3df93..aed0b5b6 — один файл, docs/specs/054-zigbee-topology-overlay.md (+45/−7 строк). Дополнительно в дереве появился docs/reviews/SPEC-REVIEW-54-r1.md — это публикация предыдущего раунда шагом конвейера, не предмет разбора.
• Дельта локальна: правки закрывают ровно три находки предыдущего раунда, новых подсистем не задето, продуктовая рамка и AC1–AC20 дельтой не затронуты. Полный разбор не требуется — веду по дельте.

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

• git diff a6a3df93..aed0b5b6 -- docs/specs/054-zigbee-topology-overlay.md построчно.
• git diff a6a3df93..aed0b5b6 --check — чисто, без пробельных дефектов.
• node scripts/check-docs.mjs — Documentation checks passed (7 files, 12 external links). Диф не трогает src/**, поэтому по правилу задачи этот гейт не был обязателен, но дешёв и уже выполнен — привожу результат.
• Сверка новой формулировки персоны с docs/SCOPE.md (grep по таблице персон).
• Сверка формата нового раздела «Затронутые файлы и модули» с прецедентом docs/specs/348-german-localization.md:322 (§12 там же).
• Проверка PROCESS.md §2.5 (DoR) на предмет буквальной формулировки пункта «перечислены затронутые файлы и модули».
• Поиск числовых ссылок на номера разделов (§NN, «раздел NN») внутри документа — на случай, если ренумерация разделов после вставки нового §15 оставила битую перекрёстную ссылку.

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

Находка r1	Чем закрыта	Где это видно
M1 — нет обязательного по DoR раздела «Затронутые файлы и модули»	Добавлен раздел ## 15. Затронутые файлы и модули с продуктовым, доказательным и документационным scope, плюс явная запись «custom_components/houseplan/**/*.py не планируется»	docs/specs/054-zigbee-topology-overlay.md:469-502
L1 — персона «Enthusiast/Power User» не совпадает с именем в docs/SCOPE.md	Персона переименована в Home admin (HA enthusiast) — совпадает с канонической строкой таблицы SCOPE (Home admin (primary) | HA enthusiast, …)	docs/specs/054-zigbee-topology-overlay.md:13, ср. docs/SCOPE.md:28
L2 — AC14 неоднозначен на фоне «House Plan backend не добавляется»	Доказательство AC14 уточнено: «HA MQTT contract fixture на Linux CI (не House Plan backend)» — согласуется с условным п.7 плана автотестов («если реализация добавляет House Plan backend surface…»)	docs/specs/054-zigbee-topology-overlay.md:412-416, ср. :460-461
L3 — численные performance-бюджеты фиксируются не в ТЗ	В §19 «Предположения автора» добавлена явная запись момента и метода фиксации: «до S7 по измеренному dev-стенду для уже перечисленных fixtures, а не угадываются на этапе ТЗ»	docs/specs/054-zigbee-topology-overlay.md:550-551

Все три находки закрыты текстом, а не заявлением: правка видна построчно в дифе, формулировки не противоречат остальному документу.

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

Без повторной проверки в этом раунде приняты следующие выводы r1 (документ docs/reviews/SPEC-REVIEW-54-r1.md, SHA a6a3df93), поскольку дельта их не задевает:

• структура ТЗ полна по §7.1 — все обязательные разделы присутствуют (кроме ранее отсутствовавшего §15, который дельта как раз добавила и который разобран выше отдельно, не по наследству);
• продуктовая рамка выдержана, все продуктовые развилки закрыты решением владельца 2026-09-04 (переключатель в «Общих настройках», hover-only, cross-space count без линии, отсутствие нового touch-жеста);
• provider-контракты (ZHA zha/devices, Z2M bridge/request/networkmap) подкреплены конкретными версиями/SHA источников Stage 0;
• AC1–AC13, AC15–AC20 проверяемы, у каждого указан способ доказательства; дельта не меняла их текст;
• догадок, выданных за факт без пометки предположения, не найдено;
• i18n-ключи en+ru перечислены (§12), миграция/compatibility решены (§8), влияние на touch названо (§11, §15 UX), откат описан (было §16, теперь §17) — по существу не менялся, только сдвинут номер заголовка.

Находки

Нет. Round r2 не вносит новых Medium/High. Ренумерация заголовков (§15→16, §16→17, §17→18, §18→19, §19→20) проверена на отсутствие битых перекрёстных ссылок по номеру — таких ссылок в документе нет вовсе (все ссылки — по названию раздела или по AC/номеру, не по «§NN»), так что ренумерация не несёт риска.

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

• Новый §15 соответствует конвенции репозитория (сверено с docs/specs/348-german-localization.md:322) и по существу отвечает пункту DoR «перечислены затронутые файлы и модули» (PROCESS.md §2.5).
• Формулировка AC14 после правки не противоречит остальным упоминаниям «House Plan backend» в документе (§14 п.7, §15).
• Персона в §1 после правки текстуально совпадает с источником в docs/SCOPE.md.
• git diff --check и node scripts/check-docs.mjs — зелёные на текущем SHA.
• Трейлеры коммита aed0b5b6 (Issue: #54, User-Visible: no) верны для документационной правки без изменения продуктового кода.

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

• Полный повторный разбор AC1–AC20, продуктовой рамки и §7.1-структуры — по правилам §2.9 дельта локальна (три точечные правки текста), поэтому эти выводы унаследованы из r1 без повторной проверки (раздел выше).
• npx tsc --noEmit, npm test, npm run build, инварианты модели, browser-смоки, golden:verify — не запускал: диф этого раунда не касается src/**, test/** ни какого-либо продуктового или тестового кода, это этап ревью ТЗ, а не код-ревью, и продуктовый код в задаче ещё не писался («Продуктовый код не менялся» подтверждено и git diff --stat за оба раунда — единственный тронутый файл вне docs/reviews/ это сам файл ТЗ).
• Смок-селектор scripts/smoke-select.mjs не запускал по той же причине — нет диффа в коде, который он мог бы сопоставить со смоками.

Заключение

Обе находки предыдущего раунда (M1 в скоупе, L1–L3 сняты) закрыты точным текстом, без побочных противоречий. Новых находок в дельте r2 не появилось. ТЗ готово к переходу в S4-spec-review → следующий процессный статус (готово к разработке при выполнении остальных пунктов DoR, которые не требовали правки в этом раунде).

---

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

• Ветка: issue/54-zigbee-topology-hover, коммит aed0b5b65a0d — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
• Дерево материала: ba3907400dbc13254d3ff4d3157632bca33beaca

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