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

# SPEC-REVIEW-585-r1

**Issue:** [#585](https://github.com/Matysh/houseplan-card/issues/585) — узкая разрешимая щель между узлами решётки 4 px теряется при разрешении коллизий поднятых 2.5D-маркеров.
**Этап:** ТЗ на ревью (`S4-spec-review`), заход r1, полный трек (не `small`: сложность/риск 8/10, влияние на производительность).
**Ревьюер:** независимая сессия, без контекста реализации (в реализации кода ещё не участвовал никто — `S6-in-progress` не проходился).
**Вердикт: зелёный.**

---

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

Тело issue #585 целиком: репорт дефекта («Что не так» / «Чем доказано» / «Почему не
починено в бете» / «Как чинить по-настоящему» / «Приёмка»), раздел `## ТЗ` (16
пронумерованных подразделов по PROCESS.md §7.1) и единственный комментарий —
`S2-analysis` от 2026-09-19, фиксирующий полный трек с названным нарушенным
критерием §5.

Задача — исправление ранее одобренного исключения из `docs/SCOPE.md` (2.5D,
issue #89): скрытый experimental-вид за `hp_alpha`, сохранённая модель/камера/
пользовательский контракт не трогаются, меняется только взаимное размещение
поднятых маркеров устройств и замков проёмов внутри уже принятого бюджета 48 CSS
px / 4 CSS px.

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

Прочитано в порядке, предписанном заданием:

1. `docs/SCOPE.md` — мандат 2.5D как узкое одобренное исключение (#89), инвариант
   блокировки замков (не задет — задача не касается действий).
2. `AGENTS.md`, `PROCESS.md` (главы 1–14 целиком) — классы файлов, лёгкий трек и
   критерий его отказа, §7.1 обязательные разделы ТЗ, §2.4/§2.10 формат ревью и
   правило деления по дельте (не применялось: это r1, других документов по #585
   в `docs/reviews/` и в истории git нет — проверено `find` и
   `git log --all --oneline | grep 585`, единственный релевантный коммит
   `9683a590` — временное расширение допусков перед бетой, не фикс).
3. Тело issue #585 и его единственный комментарий (аналитика).
4. `docs/USER-GUIDE.ru.md` — не требуется: фича скрыта за `hp_alpha`, не входит
   в пользовательский интерфейс, ТЗ явно фиксирует `User-Visible: no`.
5. `docs/ISOMETRIC.md` целиком (Stage 1/2/4) — проверка того, что числа и
   формулировки ТЗ (48 CSS px, 4 CSS px, камера `rotDeg=0 tiltDeg=20`,
   исключение room labels из взаимной коллизии, отсутствие тетера/подложки)
   совпадают с зафиксированным контрактом, а не изобретены заново.
6. `src/iso-overlays.ts` целиком — сверка утверждений ТЗ с действующей
   реализацией `resolveIsoOverlayPlacement`/`resolveIsoOverlayCollisions`:
   стабильный порядок (`nudgeDistanceCss` → `kind\0id`), текущий грубый шаг
   4 px (`ISO_OVERLAY_GROUP_COARSE_STEP_CSS_PX`, коммит `699ab471`/#583),
   существующий broad phase по ячейкам (`nearby`, `wallsNear`), деградированный
   fallback с минимальным штрафом (`penalty`), исключение room labels
   (`IsoOverlayCollisionKind = Exclude<IsoRaisedOverlayKind, 'room-label'>`).
7. `demo/performance/budgets-large-house-isometric.json`,
   `demo/performance/budgets-isometric-stage3-dense.json` — текущие значения
   `noiseAllowanceMs` (450/150/120) сверены с числами ТЗ §10 (что именно
   временное и что возвращается к 150/60/75).
8. `test/performance-budget.test.mjs` (строки 260–290) — тест
   `'изометрический допуск жеста покрывает ровно принятый шаг #583, не больше
   (#585)'` уже сегодня фиксирует эти же временные числа и явно называет #585
   как задачу, которая их отменит. ТЗ описывает уже существующий, а не
   придуманный контракт.
9. `demo/fixtures/large-house.mjs:33` — `name: \`Room ${floor + 1}.${index +
   1}\`` подтверждает, что «Room 2.5» из АС2 — реальное имя комнаты фикстуры
   `large` (этаж 2, комната 5), а не опечатка/догадка.
10. `demo/golden/matrix.mjs:284` и `demo/golden/baselines/` — сцена
    `isometric-large-warm-remount-dark` (fixture `large`, space `perf-floor-2`,
    mode `view`) существует и baseline-файл на месте.
11. `demo/performance/*.json` / `scripts` — имена профилей
    `large-house-isometric-v1` и `isometric-stage3-dense-v1` совпадают с полем
    `profile` обоих budget-файлов, значит АС6 ссылается на реальные профили.

Гейты не запускались: этап ТЗ не подразумевает исполнение кода (§2.4), материал
для проверки — текст, а не диапазон коммитов. Кода по #585 в ветке ещё нет
(`git log --all` не находит коммитов реализации #585 после `9683a590`).

## 3. Находки

Нет ни одной High- или Medium-находки.

**Low (снята с записью, не блокирует).** Раздел «1. Сценарий» не называет
персону `docs/SCOPE.md` по имени (например, «home admin»), хотя PROCESS.md §7.1
явно требует называть персону. Ситуация описана однозначно — включение
скрытого `hp_alpha` через URL/hash-параметр физически доступно только тому, кто
осознанно лезет в query/hash грамматику продукта, то есть тому же «home admin»,
единственной персоне со сценариями настройки/тестирования по SCOPE.md; у
«household members» и «guests/kiosk» нет пути включить эксперимент. Отсутствие
буквального слова не создаёт риска неверного толкования и не влияет ни на один
AC — снимаю без правки текста.

## 4. Обязательные разделы §7.1 — проверка полноты

Все обязательные разделы присутствуют и пронумерованы в теле issue:
сценарий (1) · что человек увидит до/после (2) · проблема (3) · скоуп (4) и
не-скоуп (5) · контракт поведения (6) · UX (7) · модель данных и миграция (8) ·
i18n (9) · производительность (10, сверх минимума §7.1, обоснованно для этой
задачи) · критерии приёмки AC1…AC8 с доказательством (11) · план автотестов
(12) · затронутые файлы (13) · риски и откат (14) · release-артефакты (15) ·
принятые предположения (16). Ничего из требуемого не пропущено.

Раздел 2 («До/после») — одна фраза без терминов реализации, как требуется:
«в Room 2.5 два маркера визуально совмещаются» → «оба маркера видны раздельно».

## 5. Однозначность AC и способ доказательства

| AC | Формулировка проверяема? | Доказательство названо? |
|---|---|---|
| AC1 | Да — числовые пороги (≤48 px сдвиг, ≥4 px зазор, внутри комнаты, без пересечения стены) | unit, узкий геометрический свидетель |
| AC2 | Да — конкретная сцена и комната названы и существуют в фикстуре/матрице голденов (проверено, п.2.9–2.10 выше) | golden + unit (двойной оракул, без golden как единственного судьи — прямое требование #435-класса) |
| AC3 | Да — перечислены все существующие контракты (порядок/перестановка, радиус, room/hole/wall safety, исключение room labels, fit-mode skip, degraded fallback) | unit |
| AC4 | Ограниченность поиска сформулирована качественно («существенно меньше полного диска», «нет площадного перебора 1 px»), но абсолютный запрет — полного скана диска — задан точно и проверяем по коду | unit + ревью кода (названо явно, не спрятано за «прочитано глазами») |
| AC5 | Да — «меняется только объявленная сцена» с явным условием на исключения | golden |
| AC6 | Да — точные числа допусков (150/60/75), неизменность hardMax/ratio, точный SHA CI | Linux CI (perf-профили названы по имени) |
| AC7 | Да — команды названы буквально | `npm run typecheck`, `npm run test:unit`, `npm run build` |
| AC8 | Да — три конкретных документа | ревью кода |

Единственная качественная формулировка (AC4, «существенно меньше») не создаёт
находки: жёсткая, машинно проверяемая часть контракта («не содержит площадного
перебора 1 px по диску», п.6.5–6.8 контракта поведения) уже количественная и её
достаточно для отказа реализации, вернувшейся к старому алгоритму под новым
именем. Точный коэффициент сокращения — деталь, которую пользователь не
наблюдает, и её по PROCESS.md §7.1 решают агенты, а не владелец.

## 6. Проверка «догадка выдана за факт»

Каждое утверждение о существующем поведении в ТЗ (числа 48/4 CSS px, порядок
сортировки, отсутствие тетера/подложки, исключение room labels, деградированный
fallback, текущие временные допуски 450/150/120, профили performance, имя
проблемной сцены и комнаты) сверено с действующим кодом, тестами, budget-json
или `docs/ISOMETRIC.md` (см. §2 выше) — совпадает буквально, ничего не
изобретено задним числом.

Единственное явно новое техническое решение — сам способ поиска (граничный
перебор вместо площадного/решётчатого скана, п.6.5–6.8 контракта) — помечено в
разделе 16 «Принятые предположения» как техническое решение автора, подлежащее
пересмотру ревьюером кода, а не как факт о существующей системе. Это ровно тот
случай, когда решать не пользователю: способ поиска пользователем не
наблюдается, наблюдается только результат (АС1–АС5).

Открытых продуктовых вопросов автор не поднимал и не должен: сценарий,
объём видимых изменений (только внутри уже скрытого эксперимента, обычный вид
не трогается) и деградация (существующий контракт degraded, не новый) уже
зафиксированы предыдущими задачами (#570, #583) и не требуют решения владельца
заново.

## 7. Соответствие DoR (§2.5) на выходе из ревью

- ТЗ существует в теле issue, ссылка issue↔ТЗ на месте (это и есть issue) — ✅;
- AC1…AC8 пронумерованы, у каждого назван способ доказательства — ✅ (см. §5);
- затронутые файлы и модули перечислены (§13 ТЗ) — ✅;
- i18n: явно «нет новых строк/ключей» — ✅;
- миграция/compatibility: явно «не меняются», согласуется с
  `docs/CONFIG-COMPATIBILITY.md` (алгоритм работает только с производной
  экранной геометрией кадра, схему не трогает) — ✅;
- производительность: названа количественно, включая обратный откат временных
  допусков и неизменность hard-потолков — ✅;
- touch: явно сохранён существующий контракт («Фокус, hover, click/tap и
  HA-действия остаются привязаны к визуально смещённому маркеру по
  существующему контракту», §7 ТЗ) — влияния нет, названо — ✅;
- release-артефакты: явно `User-Visible: no`, никакого changelog — ✅;
- откат: атомарный откат алгоритма + baseline + budget allowances — ✅;
- открытых продуктовых вопросов нет (см. §6 выше) — ✅.

Все пункты DoR выполнены — задача готова к переходу в `S5-ready`.

## 8. Что не проверялось (и почему это не требуется на этом этапе)

- Работоспособность самого граничного алгоритма (это предмет кода, а не ТЗ);
  на этапе спецификации проверяется формулируемость и проверяемость контракта,
  а не его реализация.
- Реальный прогон `npm run typecheck` / `npm test` / `npm run build` — код по
  #585 в ветке не появился, гонять гейты не на чём.
- Правильность цифр в таблицах «Чем доказано» / «Почему не починено в бете» —
  это диагностика самого автора, не входящая в проверяемый контракт ТЗ (АС не
  утверждают ни одно из измеренных там чисел); её будет проверять код-ревью на
  реальном прогоне Linux CI по АС6.
- Полный список из 12 изометрических голденов и byte-diff у остальных 11 — вне
  ТЗ-ревью, входит в АС5 и проверяется код-ревью по итогам съёмки.

---

**Материал раунда:** тело issue #585 на момент разбора (id issue: 585,
единственный комментарий `S2-analysis` от 2026-09-19T19:03:26Z). Других
документов ревью или коммитов реализации по #585 в репозитории нет —
`git log --all --oneline | grep 585` находит только `9683a590` (предшествующее
временное расширение допусков, не относится к этой ТЗ-редакции). Раздел
«Унаследовано из r0» не пишется: это первый заход.

---

<!-- material-anchors: сгенерировано конвейером (#414) -->

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

- Ветка: `dev`, коммит `c38382b7318a` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
- Дерево материала: `a34fbb3a3bd1828db2c7fb65a42e43f9ae921195`
  ```
  git log --all --format='%H %T' | grep a34fbb3a3bd1
  ```
- Тело issue: `7e85ec65b07414bb734b5f19ffb10510ee60b3af4fdb52ed429df29d2593ebc8`
- Вердикт конвейера: `green` · High 0