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

# SPEC-REVIEW-471-r1

- **Issue:** https://github.com/Matysh/houseplan-card/issues/471
- **Этап:** ревью ТЗ (PROCESS.md §2.4)
- **Заход:** r1 · блокирующих циклов израсходовано 0 из 4 (лимит лёгкого трека
  не применяется — задача идёт полным треком)
- **Артефакт ТЗ:** `docs/specs/471-isometric-overlay-white-plates.md`,
  коммит `5dbcbb81ef24f729f0febd2b836a46196faaf861` на ветке
  `issue/471-isometric-overlay-plates` (docs-only, класс C)
- **Вердикт:** зелёный

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

Первый заход ревью ТЗ. Разбор полный (не по дельте — предыдущего раунда нет).
Проверялось:

1. Соответствие `docs/SCOPE.md` — задача внутри уже утверждённого исключения
   `#89` (2.5D presentation скрытого изометрического режима) и не расширяет
   его; никакой новой функциональности, только визуальный откат декоративного
   элемента.
2. Правильность классификации трека — файл ТЗ существует (задача не `small`),
   что подтверждено и собственным комментарием владельца в issue
   (`лёгкий трек: нет — меняется принятый UX-контракт #160`).
3. Полнота обязательных разделов §7.1.
4. Однозначность и доказуемость каждого AC (AC1…AC8), в т.ч. наличие метода
   доказательства у каждого.
5. Не выдана ли догадка за факт — все технические утверждения о текущем
   поведении сверены с реальным кодом и документами, а не приняты на слово
   автора.
6. Отсутствие продуктовых вопросов, которые следовало задать владельцу, но
   вместо этого решены технически.

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

Читал только — правки в код и ТЗ не вносил (роль ревьюера ТЗ).

- Прочитаны `docs/SCOPE.md`, `AGENTS.md`, `PROCESS.md` полностью.
- Прочитано тело issue #471 и оба комментария (оценка владельца, занятие
  автором).
- Прочитан файл ТЗ `docs/specs/471-isometric-overlay-white-plates.md`
  целиком (395 строк).
- Технические утверждения ТЗ сверены построчно с исходным кодом:
  - `src/iso-scene-render.ts` — существование и сигнатуры
    `ISO_RAISED_FOOTPRINT`, `isoRaisedOverlayHalfSize()`; ветки для
    `device` / `room-label` / `opening-lock`; точные числа
    `roomMetricTextCharacters` (`temperature: 10, humidity: 8, lqi: 6,
    light: 24`) — совпадают с текстом issue дословно.
  - `src/iso-overlays.ts` — наличие `resolveIsoOverlayPlacement()`.
  - `src/styles/plan.styles.ts` — точное значение заливки
    `.iso-overlay-plate { fill: rgba(248, 249, 247, 0.9) }` (свет),
    `rgba(68, 77, 81, 0.92)` (тёмная тема), forced-colors ветка с
    `fill: Canvas`, `.iso-overlay-plate-texture`.
  - `test/isometric-contract.test.mjs` — текущие assert на
    `class="iso-overlay-plate ..."`, на dark/forced-colors CSS-правила —
    подтверждают, что контракт сегодня действительно требует видимый
    polygon, как и заявляет ТЗ (AC2 будет требовать обратного).
  - `demo/golden/baselines/isometric-stage3-overlays-{light,dark}.png` —
    файлы существуют.
  - `docs/ISOMETRIC.md` (4 упоминания `plate`/`footprint`),
    `docs/adr/160-isometric-stage3-overlays.md` (raised plate описан как
    видимая floor-parallel поверхность), `docs/ARCHITECTURE.md` (строки
    719–726, «raised plate corners», «floor-parallel SVG plate») — все три
    документа сегодня действительно описывают plate как видимую
    поверхность, значит их обновление в скоупе задачи обосновано, а не
    придумано.
  - `docs/STATUS.md` — подтверждено, что Stage 3 (#160) сейчас
    «hidden … without public enablement or changelog entry», что
    оправдывает `User-Visible: no` в §17 ТЗ по аналогии с исходным
    коммитом `ee7d4869` (`feat: implement isometric stage 3`, тоже
    `User-Visible: no`).
  - `docs/TESTING.md` — упоминания слова «plate» в этом файле относятся к
    не связанной подсистеме (working-state plate иконки устройства), не к
    isometric raised overlay; ТЗ корректно ограничивает правку `TESTING.md`
    фразой «только в части действующего Stage 3».
  - `src/iso-scene-render.ts:1130` — `hp-iso-overlay-texture` паттерн
    привязан к `root === 'overlays'` и используется отдельно от wall/floor
    material nuance — подтверждает, что удаление overlay-текстуры (W6) не
    затрагивает материалы стен/пола, как и заявлено в §8 ТЗ.
- Файлы, перечисленные в §16 «Ожидаемые файлы реализации», проверены на
  существование: `test/iso-overlays.test.mjs`, `test/iso-scene-render.test.mjs`,
  `test/isometric-contract.test.mjs`, `demo/smoke_isometric_contract.mjs`,
  `demo/smoke_isometric_live_touch.mjs`, `docs/specs/160-isometric-stage3.md`,
  `docs/adr/160-isometric-stage3-overlays.md` — все существуют.

Гейты (typecheck/test/build) не гонялись: изменение этого раунда — только
docs (класс C), продуктовый код не тронут, гейты кода к ревью ТЗ не
относятся.

## Находки

Нет High. Нет Medium. Одна Low-находка, снимается ревьюером без возврата
автору.

- **Low — отсутствует буквальный раздел «Проблема» (§7.1).** ТЗ переходит от
  §2 «Что человек увидит до/после» сразу к §3 «Подтверждённая причина и
  заменяемый контракт», не давая отдельного заголовка «Проблема». Содержательно
  проблема полностью раскрыта — в issue (детальное «Проблема» и
  «Воспроизведение») и в §1–§3 ТЗ (сценарий, видимый эффект, причина). Снимаю
  без правки: дублировать содержание issue под отдельным заголовком добавило
  бы только повторение, не новую информацию.

## Что проверено и признано корректным

- **Полнота §7.1.** Все обязательные разделы присутствуют по содержанию:
  сценарий (§1), видимый эффект до/после (§2), проблема/причина (§3),
  скоуп/не-скоуп (§5, §6), контракт поведения (§4, §7, §8), UX (§10), модель
  данных и миграция (§11), i18n (§11, «новых строк нет»), AC1…AC8 с методом
  доказательства у каждого (§14), план автотестов (§15, плюс таблица red
  witness — избыточно хорошо для этапа ТЗ), риски (§18), откат (§19),
  release-артефакты (§17).
- **Ни одной догадки, выданной за факт.** Каждое утверждение о текущем
  поведении кода и документов, которое я выборочно перепроверил, подтвердилось
  дословно (см. «Как проверялось»). Технические предположения на будущее
  корректно вынесены в явный блок §20 «Принятые технические предположения —
  можно менять на ревью» и не маскируются под решённые факты.
- **Продуктовых вопросов, скрытых как технические, не найдено.** §20.3
  (fit/home сохраняет прежний envelope) на первый взгляд похож на продуктовый
  вопрос о видимом framing, но по факту фиксирует нулевое изменение уже
  видимого поведения (защита от регресса, а не новое решение) и явно
  откладывает возможное последующее уточнение framing в отдельную задачу —
  корректно решать технически, эскалации не требовалось.
  §20.4 и §20.5 не новые решения, а повтор того, что уже прямо сказано в
  теле issue.
- **Классификация трека верна.** Файл ТЗ создан (не `small`), что совпадает и
  с собственной оценкой владельца в issue-комментарии. Критерий, который
  задача не проходит, назван явно («меняется принятый UX-контракт #160»),
  как того требует AGENTS.md.
- **Согласованность с `docs/SCOPE.md`.** Работа не расширяет ранее одобренное
  исключение #89 (2.5D presentation), а чинит визуальный дефект внутри него;
  из категорий Out-of-scope ничего не затронуто.
- **AC доказуемы и не размыты.** Каждый из AC1–AC8 формулирует проверяемое
  условие («нет .iso-overlay-plate в SVG», «anchors/nudge/tether совпадают
  на fixtures до/после», «44×44 px сохраняется», и т.д.) и называет способ
  доказательства (`unit`/`contract`/`smoke`/`golden`/`review`), как того
  требует DoR (PROCESS.md §2.5).
- **Не-скоуп закрывает реальный риск расползания.** Явно исключены смежные и
  правдоподобно соблазнительные правки — камера, footprint размеры,
  редизайн typography/shell, альтернативная текстовая подложка вместо белой
  plate (последнее прямо описано как «отдельное продуктовое решение»).
- **Откат и release-артефакты согласованы с прецедентом.** `User-Visible: no`
  подтверждён тем же выбором в исходном коммите Stage 3 (`ee7d4869`) и
  текущим статусом `docs/STATUS.md` («hidden … without public enablement»).

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

- Не читал сам продуктовый код в объёме, достаточном для код-ревью
  (`src/iso-overlays.ts` целиком, полную реализацию `render...` функций) —
  это задача этапа код-ревью, а не ревью ТЗ; здесь код читался только
  выборочно, чтобы верифицировать конкретные фактические утверждения ТЗ.
- Не гонял typecheck/test/build/golden — код ещё не менялся, гейты
  неприменимы на этом этапе.
- Не проверял `docs/specs/160-isometric-stage3.md` и
  `docs/adr/160-isometric-stage3-overlays.md` построчно целиком — только
  выборочно, для подтверждения текущей терминологии «plate».
- Не оценивал визуально сам артефакт (белые прямоугольники) — ручного
  тестирования на этапе ревью ТЗ нет, а сам артефакт не оспаривается: автор
  и владелец (в оценке) уже согласны, что дефект существует и воспроизводим.

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

- Ветка: `issue/471-isometric-overlay-plates`
- SHA материала: `5dbcbb81ef24f729f0febd2b836a46196faaf861`
- ТЗ: `docs/specs/471-isometric-overlay-white-plates.md` (единственный
  коммит на дельте к `dev`)

---

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

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

- Ветка: `issue/471-isometric-overlay-plates`, коммит `5dbcbb81ef24` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
- Дерево материала: `3d667d66b10115b9300bca5ad1b406447aff97b0`
  ```
  git log --all --format='%H %T' | grep 3d667d66b101
  ```
- ТЗ `docs/specs/471-isometric-overlay-white-plates.md`, блоб `1ef8a58c9af0140089c3e20a2ded7c72cfac7402`
  ```
  git log --all --find-object=1ef8a58c9af0140089c3e20a2ded7c72cfac7402 -- docs/specs/471-isometric-overlay-white-plates.md
  ```