diff --git a/docs/reviews/SPEC-REVIEW-54-r2.md b/docs/reviews/SPEC-REVIEW-54-r2.md new file mode 100644 index 00000000..5326e52a --- /dev/null +++ b/docs/reviews/SPEC-REVIEW-54-r2.md @@ -0,0 +1,130 @@ +# 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 + ```