diff --git a/docs/reviews/SPEC-REVIEW-485-r2.md b/docs/reviews/SPEC-REVIEW-485-r2.md new file mode 100644 index 00000000..5293d21e --- /dev/null +++ b/docs/reviews/SPEC-REVIEW-485-r2.md @@ -0,0 +1,171 @@ +# SPEC-REVIEW-485-r2 + +Issue: [#485](https://github.com/Matysh/houseplan-card/issues/485). +Материал: ветка `issue/485-radar-presence`, SHA `f4bab4a4bd5f4ac9b91cc16363985323a20ae907` +(baseline r1 `6550a69e6857d11aba69b65809f140d239245e88`, докс-only diff, проверено +`git diff --stat` — только `docs/SCOPE.md`, три этапных ТЗ (`stage1/2/3`) и коммит +самого документа `docs/reviews/SPEC-REVIEW-485-r1.md`). +Этап: **spec** (S4-spec-review). Заход: r2. Блокирующих циклов израсходовано 1 из 4 +(зелёный вердикт цикл не образует и бюджет не тратит, #227). +Трек: полный (метка `small` отсутствует, подтверждено `gh issue view` — `P2, feature, +S4-spec-review`). Ревьюер ≠ автор. + +## Скоуп разбора (по дельте, PROCESS §2.9/§2.10, issue #214) + +Предыдущий вердикт — [SPEC-REVIEW-485-r1](https://github.com/Matysh/houseplan-card/blob/f4bab4a4bd5f4ac9b91cc16363985323a20ae907/docs/reviews/SPEC-REVIEW-485-r1.md), +получен на SHA `6550a69e6857d11aba69b65809f140d239245e88`: жёлтый, High 0, Medium 2 +(M-1, M-2), обе находки в скоупе. Комментарий владельца сообщает исправление на +`f4bab4a4bd5f4ac9b91cc16363985323a20ae907`, без ребейза на ушедший вперёд `dev` — +`dev` не двигался (`ed9ee026` остаётся базой в обоих раундах). + +`git diff 6550a69e..f4bab4a4 --stat`: + +``` +docs/SCOPE.md | 16 ++ +docs/reviews/SPEC-REVIEW-485-r1.md | 251 ++ (коммит документа предыдущего раунда, не предмет разбора) +docs/specs/485-radar-presence-stage1.md | 25 ++ +docs/specs/485-radar-presence-stage2.md | 3 + +docs/specs/485-radar-presence-stage3.md | 5 +- +``` + +Дельта локальна: два точечных добавления (SCOPE.md-исключение + touch-декларация +этапа 1) плюс зеркальное упоминание `docs/SCOPE.md` в списках release-артефактов +этапов 2 и 3. Контракт общего документа (`485-radar-presence.md`), модель данных, +идентичность (`source_generation`/`calibration_revision`), AC-таблицы C/S1/S2/S3, +негативные свидетели, границы этапов и ответы Q1–Q4 дельтой не задеты — полный +повторный разбор не требуется, разбор ограничен тем, до чего дотягивается дельта: +двумя находками r1 и текстом вокруг них. + +## Закрытие раунда r1 + +| Находка r1 | Чем закрыта | Где это видно | +|---|---|---| +| **M-1** — исключение для записи/облака/тепловой карты не зафиксировано в `docs/SCOPE.md` | В `docs/SCOPE.md` добавлены два узких исключения #485 по образцу #89/#53: (а) под «Device/entity administration» — создание/удаление только собственных производных room-presence/estimated-count сущностей по подтверждению HA-админа, без автоматизаций и без переименования/переноса/отключения источников; (б) под «History, graphs, statistics» — записи ≤24 ч по явному запуску, raw TTL ≤24 ч, отдельно включаемые агрегаты ≤7 дней, каждый сеанс агрегации ≤24 ч, доступ по праву редактирования, без автопродления/непрерывного сбора/облака/идентификации личности. Все три этапных документа (`stage1` §10, `stage2` release-раздел, `stage3` release-раздел) теперь называют `docs/SCOPE.md` и требуют сверки реализации с этой рамкой без молчаливого расширения. | `docs/SCOPE.md:97-114` (после `git show f4bab4a4:docs/SCOPE.md`); `stage1.md:529-533`; `stage2.md:671-673`; `stage3.md:766-769` | +| **M-2** — этап 1 не даёт обязательную touch-классификацию мастера калибровки | В `stage1.md` §5.2 добавлен абзац, начинающийся дословно `**Touch editor: best effort / intentionally degraded.**` — ровно одна из трёх формулировок, требуемых `docs/TOUCH-SUPPORT.md` («Documentation rule»). Обоснование — десктоп как эталон, обязательный отсчёт перед перемещением, доступные Retry/ручная настройка. Явно перечислены случаи, которые не должны фиксировать промежуточное состояние: Cancel/Back, потеря разрешения, `visibilitychange`/скрытие страницы, pinch, второй указатель, `pointercancel` — это дословно покрывает «Safety floor» из `docs/TOUCH-SUPPORT.md` («…never permits… saving unintended geometry merely because a pinch, pointer cancellation or second touch was misread as a click»). View/kiosk touch не затронуты, S1-10/S1-18 названы как несущие эту границу. | `stage1.md:228-246` | + +Обе находки закрыты предметно, а не декларативно: правки лежат ровно там, где r1 +указал место и формулировку, и используют то же прецедентное оформление (#89/#53 +для SCOPE.md, точная фраза из TOUCH-SUPPORT.md для touch-декларации). Новых +формулировок, которые расширяли бы рамку задачи или противоречили ответам +Q1–Q4/владельца, не найдено. + +## Унаследовано из r1 + +Ниже принято без повторной проверки в этом раунде, так как дельта их не задевает; +основание — [SPEC-REVIEW-485-r1](https://github.com/Matysh/houseplan-card/blob/f4bab4a4bd5f4ac9b91cc16363985323a20ae907/docs/reviews/SPEC-REVIEW-485-r1.md) +на SHA `6550a69e6857d11aba69b65809f140d239245e88`: + +- Продуктовая рамка и границы этапов (1 → 2 → 3), их взаимное непересечение и + корректность отнесения к J1/`docs/SCOPE.md` («Known gaps»). +- Единая модель идентичности (`source_generation`, `calibration_revision`, + `server_session_id`/`seq`) и её согласованное использование во всех трёх этапах. +- Полнота AC-таблиц C-1…C-8, S1-1…S1-18, S2-1…S2-22, S3-1…S3-18: колонка + доказательства и негативный свидетель у каждого критерия. +- «Одно число — один источник» для оценки зоны (stage2 §4.3/§10) и native-состояния + комнаты (stage3 §7.2). +- Матрицы совместимости/жизненного цикла (импорт, дублирование, удаление комнаты, + смена пространства, старый фронтенд) для каждого нового поля. +- Продуктовые вопросы Q1–Q4 закрыты подтверждением владельца, скрытых догадок, + выданных за факт, кроме двух находок r1 (уже закрытых), не найдено. +- Перекрёстные ссылки между четырьмя документами и запись в `docs/specs/README.md` + корректны, битых ссылок нет. +- Touch-декларации этапов 2 и 3 (были даны дословно уже в r1, дельтой не тронуты). + +## Как проверялось в этом раунде + +- `git diff 6550a69e..f4bab4a4 --stat` и построчный `git diff` по пяти изменённым + файлам — предмет разбора ограничен им. +- Каждая правка сверена дословно с «Как чинится» из r1 (см. таблицу выше) и с + первоисточником требования: прецедентный формат исключений SCOPE.md (`git show` + секций #89/#53) и точная триада формулировок `docs/TOUCH-SUPPORT.md:178-180` плюс + «Safety floor» `docs/TOUCH-SUPPORT.md:82-92`. +- Проверено, что новый текст SCOPE.md количественно совпадает с решением владельца + Q3 (запись ≤24 ч по ручному запуску, raw TTL 24 ч, агрегаты ≤7 дней, отдельное + включение, право редактирования, без автопродления) — расхождений нет. +- Проверено, что упоминание `docs/SCOPE.md` добавлено в раздел release-артефактов + во всех трёх этапных документах (stage1/2/3), как требовало «как чинится» M-1, + а не только в одном. +- `git diff --check 6550a69e..f4bab4a4 -- <изменённые файлы>` — чисто (нет + trailing-whitespace/conflict-маркеров). +- `node scripts/check-docs.mjs` — `Documentation checks passed (7 files, 12 + external links)`. Не являлось обязательным гейтом для этого раунда (diff не + трогает `src/**`), прогнан дополнительно как дешёвая проверка ссылок/таблиц, + раз автор заявил его в комментарии. +- Трейлеры коммита `f4bab4a4` — `Issue: #485`, `User-Visible: no`; верно для + докс-only изменения без видимого поведения. +- Метки issue (`gh issue view 485`): `P2, feature, S4-spec-review`, `small` + отсутствует — трек не изменился, полный разбор запрошен корректно (этот раунд — + сокращённый по дельте согласно §2.9/§2.10, а не по треку `small`). + +## Находки + +Нет. Обе находки r1 закрыты предметно (см. «Закрытие раунда r1»); дельта не +вносит новых утверждений, которые расширяли бы `docs/SCOPE.md` за пределы решения +владельца, ослабляли touch-safety floor или противоречили унаследованным AC. + +## Что проверено и корректно + +- SCOPE.md-исключения количественно совпадают с зафиксированными owner-defaults + (Q1–Q4) и с этапными документами (24 ч / 7 дней / право редактирования / без + автопродления), нигде не расширены сверх того, что уже описано в общем контракте + и этапах. +- Touch-декларация этапа 1 использует ровно требуемую формулировку и явно + перечисляет случаи, которые не должны фиксировать промежуточное состояние — + это конкретнее общего требования `docs/TOUCH-SUPPORT.md` и совпадает по духу с + декларациями этапов 2/3. +- Ссылка на `docs/SCOPE.md` как release-артефакт добавлена во всех трёх этапных + документах, а не выборочно. +- Комментарий автора корректно называет дельту («только `docs/SCOPE.md` и три + этапных ТЗ; алгоритмы, модель данных, продуктовый код и тесты не изменены») — + проверено `git diff --stat` и совпадает. + +## Чего не проверял + +- Не перепроверял полностью AC-таблицы C/S1/S2/S3, продуктовую рамку, единую + модель идентичности, совместимость и Q1–Q4 — дельта их не касается, раздел + «Унаследовано из r1» перечисляет, что принято без повторной проверки. +- Не запускал `npx tsc --noEmit`, `npm test`, `npm run build`, `npm run + invariants`, браузерные смоки, `golden:verify`, `pytest tests_backend`, + перфопрофили — diff докс-only, не касается `src/**`/`custom_components/**/*.py`; + ни один AC пакета не требует их прогона для стадии spec-review. Зелёный Validate + на `f4bab4a4` (https://github.com/Matysh/houseplan-card/actions/runs/34219795897) + подтверждает дешёвые гейты репозитория в целом, доказательной нагрузки для + AC C-1…C-8/S1…S3 не несёт (они про будущую реализацию). +- Не проверял английскую версию `docs/USER-GUIDE.md` построчно — дельта не + вводит нового пользовательского текста вне SCOPE.md/спек, i18n-таблицы `radar.*` + дельтой не тронуты. + +## Вердикт + +**Зелёный.** Обе Medium-находки r1 закрыты предметно и в точности по указанному в +r1 месту и формулировке; новых находок дельта не порождает. High — 0, Medium — 0. +Цикл не образуется, бюджет остаётся 1 из 4. Итог раунда: комплект готов к переходу +S4 → S5 по команде владельца («довести до `S5-ready`, реализацию не начинать»). + +--- + + + +## Материал раунда + +- Ветка: `issue/485-radar-presence`, коммит `f4bab4a4bd5f` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет. +- Дерево материала: `1c753a0522a863553d41e59a536c10018b733dd3` + ``` + git log --all --format='%H %T' | grep 1c753a0522a8 + ``` +- ТЗ `docs/specs/485-radar-presence-stage1.md`, блоб `254a99726d27659900b5b0cb82e9f294912e5f35` + ``` + git log --all --find-object=254a99726d27659900b5b0cb82e9f294912e5f35 -- docs/specs/485-radar-presence-stage1.md + ``` +- ТЗ `docs/specs/485-radar-presence-stage2.md`, блоб `b403e73fc26ba0ffb97be4ffa73be067d179880f` + ``` + git log --all --find-object=b403e73fc26ba0ffb97be4ffa73be067d179880f -- docs/specs/485-radar-presence-stage2.md + ``` +- ТЗ `docs/specs/485-radar-presence-stage3.md`, блоб `c65e28389d762216c47f00249bdb751f3c9d5082` + ``` + git log --all --find-object=c65e28389d762216c47f00249bdb751f3c9d5082 -- docs/specs/485-radar-presence-stage3.md + ``` +- ТЗ `docs/specs/485-radar-presence.md`, блоб `8b56afbdbb5923e002513a31e05a83563e5d0c02` + ``` + git log --all --find-object=8b56afbdbb5923e002513a31e05a83563e5d0c02 -- docs/specs/485-radar-presence.md + ```