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

# SPEC-REVIEW-122-r1

- **Issue:** https://github.com/Matysh/houseplan-card/issues/122
- **ТЗ под ревью:** `docs/specs/122-isometric-stage2.md` (коммит `76ce755`,
  ветка `issue/122-isometric-stage2`)
- **Роль:** ревьюер ТЗ (не автор), этап `S4-spec-review`
- **Трек:** обычный (не `small`) — аналитика владельца оценила сложность и
  риск 9/10, поверхностей больше одной (рендер/геометрия/UX/perf); лёгкий трек
  корректно не применён, `docs/specs/<NN>-*.md` присутствует
- **Цикл:** r1/4 (полный трек, лимит 4)

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

Проверялось соответствие ТЗ:

- `docs/SCOPE.md` — попадание в Core user jobs (J1/J2/J3), узкое
  owner-approved исключение из фотореалистичного/3D-запрета, инвариант lock;
- `PROCESS.md` §2.4/§2.5 (DoR), §7.1 (обязательные разделы ТЗ), §12
  (запреты), §3 (правила 1, 2, 6, 9);
- `AGENTS.md` — классы файлов (только `docs/**` в этом коммите), ветка,
  трейлеры;
- нормативному предшественнику `docs/specs/089-isometric-view-stage1.md` и
  `docs/adr/089-isometric-stage1-renderer.md` — что Stage 2 не переписывает
  принятые решения Stage 1 задним числом;
- каноническим документам затронутой подсистемы: `docs/ISOMETRIC.md`,
  `docs/WALL-THICKNESS.md`, `docs/LIGHT.md`, `docs/TOUCH-SUPPORT.md`,
  `docs/UX-MODES.md`;
- `docs/USER-GUIDE.ru.md` — что видимого пользователю текста не появляется и
  документ не должен меняться;
- фактическому состоянию кода (`src/render/opening-symbol.ts`, `src/logic.ts`,
  `src/labs.ts`, `demo/golden/matrix.mjs`) — на предмет того, что технические
  утверждения ТЗ не являются непроверенной догадкой;
- треду issue #122 целиком, включая аналитику S2, вопросы владельца Q0–Q6 и
  их принятие, а также связанному issue #124 (performance-блокер).

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

1. Прочитан весь тред issue #122: аналитика (ценность 7/10, P2, сложность
   9/10), пакет вопросов владельцу Q0–Q6 с default-вариантами, принятие всех
   default'ов владельцем 2026-08-13, хендофф автора «ТЗ готово к ревью».
   Подтверждено, что ни один вопрос не был техническим, замаскированным под
   продуктовый: Q0 (приоритет/ценность), Q1 (объём видимого сравнения
   Stage1/Stage2 — второй флаг или нет), Q2 (что задают референсы: материал
   или замена содержимого), Q3 (визуальное представление проёмов), Q4 (новый
   декоративный свет — да/нет), Q5 (floor edge/тени), Q6 (деградация) — все
   про то, что видит пользователь, и про объём этого issue.
2. Сверены обязательные разделы ТЗ (§7.1 `PROCESS.md`) — таблица ниже.
3. Прочитан `docs/specs/089-isometric-view-stage1.md` целиком и
   `docs/ISOMETRIC.md` — подтверждено, что Stage 2 ссылается на реальные
   решения Stage 1 (`wallBodiesGeometry()`, единая проекция, fingerprint без
   `_cfgEpoch`/HA state, LRU-кэш на 8 сцен, latched flat fallback,
   `projectedFrame()`, Labs-грамматика `iso`/`since 1.62.0`/`expires 1.65.0`)
   и не выдаёт их за собственное изобретение и не переписывает Stage 1 задним
   числом (ADR-89 не трогается, заводится новый `docs/adr/122-*.md`).
4. Прочитан `src/labs.ts` (`since: '1.62.0'`, `expires: '1.65.0'`) и
   `package.json` (`version: 1.63.0`) — утверждение ТЗ «expiry не расширяется,
   `1.65.0-beta.1` уже мёртв» технически корректно и согласуется с описанным в
   `docs/ISOMETRIC.md` числовым сравнением ядра версии.
5. Прочитан `src/render/opening-symbol.ts` — подтверждены буквально: gate
   открывается ровно на 10° (`10 * amount`, `docs/specs/122:213-215` против
   `opening-symbol.ts:97`), window — двухстворчатый casement
   (`rotate(${-90*amount})`/`rotate(${90*amount})`, `opening-symbol.ts:83-89`
   против §6.5 «two-leaf/casement»). Это не догадка автора, а точное описание
   существующего кода.
6. Прочитан `openingAmount()` в `src/logic.ts:316-323` — подтверждено
   поведение «no contact → door/gate open (1), window closed (0)», которое ТЗ
   называет «static-open default when no contact exists» (§6.5, Door/Gate).
7. Прочитан `docs/LIGHT.md` и `docs/WALL-THICKNESS.md` — подтверждено, что
   «один регион света на источник», «wallBodiesGeometry как единственный
   источник тела стены», «exterior silhouette из union центральных линий» —
   реальные, а не придуманные инварианты, на которые ТЗ ссылается в §6.3, §6.7,
   §7.
8. Прочитан `docs/TOUCH-SUPPORT.md` целиком — формулировки ТЗ §6.8
   («pointer/focus/ARIA inert», «View и kiosk остаются полностью
   поддерживаемыми», «touch-only failure — product defect») дословно
   отражают контракт, а не изобретены заново.
9. Прочитан `docs/USER-GUIDE.ru.md` — поиском подтверждено отсутствие каких-
   либо упоминаний изометрии/объёмного вида; утверждение ТЗ §9 «документ
   остаётся молчащим про скрытый Iso» верно на текущий момент.
10. Проверено существование golden-сцены `isometric-no-borders-dark` в
    `demo/golden/matrix.mjs:23` — AC15/§12.3 ссылаются на реальный, а не
    вымышленный сценарий.
11. Прочитан issue #124 (`gh issue view 124`) — подтверждено: воспроизводимый
    performance-регресс `viewToggleMs.median 192.8мс` vs лимит `131.7мс` на
    exact-SHA профиле `large-house-isometric-v1`, статус `S1-new` (ещё не
    проанализирован). ТЗ §10 корректно описывает его как DoR-блокер
    реализации (не ревью), с двумя явными путями снятия (закрытие #124 или
    отдельное явное решение владельца) — ни то, ни другое не подменяет и не
    ослабляет существующий бюджет.
12. Проверено `docs/specs/README.md:80` — строка на #122 добавлена в том же
    коммите, ссылка issue ↔ ТЗ двусторонняя.
13. Проверены трейлеры коммита `76ce755`: `Issue: #122`, `User-Visible: no`;
    `git show --stat` подтверждает изменение только `docs/specs/122-*.md` и
    `docs/specs/README.md` — класс C, продуктовый код (класс A) не менялся,
    правило №1 `AGENTS.md`/`PROCESS.md` соблюдено на этапе `spec`.

## Обязательные разделы (§7.1 PROCESS.md)

| Раздел | Есть | Комментарий |
|---|---|---|
| Сценарий (персона/поверхность/момент) | ✅ | §1 |
| Что человек увидит до/после (без терминов реализации) | ✅ | §1, одной фразой |
| Проблема | ✅ | §2 |
| Скоуп / не-скоуп | ✅ | §4 / §5 |
| Контракт поведения | ✅ | §6 (8 подразделов) |
| UX | ✅ | §9 (явно: нет нового UI/i18n) |
| Модель данных и миграция | ✅ | §8 |
| i18n | ✅ | §9 (пусто, обосновано) |
| AC1…ACn с доказательством | ✅ | §11, 16 штук, каждый с типом |
| План автотестов | ✅ | §12 (unit/smoke/golden/performance/backend) |
| Риски | ✅ | §14, 12 строк с вероятностью/impact/mitigation |
| Откат | ✅ | §15 |
| Release-артефакты | ✅ | §13 |

Все обязательные разделы присутствуют и содержательны. Дополнительно
присутствуют продуктовые под-разделы §7.1 (персона/поверхность/момент внутри
§1) и явный блок §16 «принятые технические предположения — можно менять без
пересмотра продукта», корректно отделённый от решений владельца §3.

## Находки

Находок уровня **High** и **Medium** нет.

### Low-1 — отсутствует буквальная декларация «Touch editor: …»

**Файл:** `docs/specs/122-isometric-stage2.md` (весь документ)

`docs/TOUCH-SUPPORT.md` («Documentation rule») требует от новых спецификаций
редакторных фич явно указывать одно из: `Touch editor: supported` / `best
effort / intentionally degraded` / `not exposed`. Предшественник, Stage 1
(`docs/specs/089-isometric-view-stage1.md`, §7 «Touch editor: не exposed»),
эту декларацию давал буквально, хотя ситуация идентична — редакторы Stage 2
не касается вовсе (§6.1 «Editors and houseplan-space-card stay Flat»). Stage 2
такой буквальной строки не содержит, хотя по содержанию §6.1/§6.8 поведение
однозначно совпадает с «not exposed» — реальной неоднозначности для
разработчика или ревьюера кода нет.

**Решение ревьюера:** Low, не блокирует. Формально Stage 2 не вводит новую
редакторную фичу (правило `TOUCH-SUPPORT.md` адресовано именно им), а
содержательно контракт «редакторы не меняются» зафиксирован дважды (§6.1,
§9). Оставляю на усмотрение автора — можно добавить строку `Touch editor: not
exposed` при следующей правке для единообразия с Stage 1, можно снять этой
записью.

### Low-2 — три AC используют тип доказательства вне буквального перечня §2.5

**Файл:** `docs/specs/122-isometric-stage2.md:445-457` (AC13, AC15, AC16)

DoR (`PROCESS.md` §2.5) перечисляет типы доказательства как `unit` / `backend`
/ `smoke` / `golden` / «ревью кода». AC13 помечен только `(performance)`,
AC15 — `(golden + documentation review)`, AC16 — `(typecheck + unit + build)`.
Буквально `performance`, `typecheck`, `build` и `documentation review` в этот
перечень не входят. По существу все три доказуемы существующими механизмами:
`performance_smoke`/Full Performance и `typecheck`/`build` — реальные
release-blocking гейты `PROCESS.md` §8, а «documentation review» — часть
обычного код-ревью (§2.7). Тот же паттерн уже был отмечен как Low-1 в
`SPEC-REVIEW-123-r1` и оставлен автору без блокировки цикла.

**Решение ревьюера:** Low, не блокирует. Переформулировка в термины §2.5 (например,
«ревью кода со ссылкой на `performance_smoke`/exact-SHA Full Performance» и
«ревью кода со ссылкой на зелёный `typecheck`/`test`/`build`») повысила бы
буквальную трассируемость, но не меняет, чем на практике будет доказан
критерий. Оставляю на усмотрение автора или снимаю этой записью.

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

- Соответствие `docs/SCOPE.md`: задача закрывает J1/J2/J3, остаётся внутри
  узкого owner-approved исключения (2.5D, не фотореализм/не свободная камера/
  не interior editor), не трогает единственную санкционированную поверхность
  actuation замков (`docs/SCOPE.md` «The lock invariant»).
- Все вопросы владельцу (Q0–Q6) — продуктовые (видимое поведение, объём
  видимых изменений), ни один технический вопрос не был переадресован
  владельцу; все ответы получены и внесены в ТЗ без расширения скоупа.
- ТЗ явно наследует, а не переопределяет Stage 1: проекция, `wallBodiesGeometry`,
  fingerprint без `_cfgEpoch`/HA-состояния, LRU-кэш 8 сцен, latched flat
  fallback, Labs-грамматика `iso`/`1.62.0`/`1.65.0` — все повторно
  использованы корректно, ни одно принятое решение Stage 1 не переписывается
  задним числом (историческая ADR-89 остаётся неприкосновенной, заводится
  новая `docs/adr/122-isometric-stage2-composition.md`).
- Технические утверждения о существующем коде (10° gate, two-leaf window,
  static-open default при отсутствии contact, один регион света на источник,
  `wallBodiesGeometry` как единственный источник геометрии стен) подтверждены
  чтением реального кода, а не приняты на слово автора.
- Скоуп/не-скоуп (§4/§5) корректно отсекает публичный rollout, второй флаг
  `iso2`, свободную камеру/#82, новые material-настройки, объёмные редакторы и
  `houseplan-space-card`, схемные поля высоты/подоконника, WebGL/Three.js — все
  типичные места, где скоуп мог бы незаметно расшириться, явно закрыты.
- Зависимость от #124 обработана корректно: не как продуктовое решение
  Q0–Q6 (не переоткрывает их), а как отдельный DoR-блокер реализации (§10) с
  двумя явными путями снятия; ревью ТЗ по правилам `PROCESS.md` §10 разрешено
  вести, пока #124 открыт.
- i18n/UX (§9): подтверждено отсутствием новых строк, README/CHANGELOG/
  USER-GUIDE не обещают публичную функцию — соответствует `User-Visible: no`
  контракту для всей будущей реализации.
- Модель данных и совместимость (§8): подтверждено отсутствием новых
  схемных полей, ключей `localStorage` версий и compatibility-записей;
  откат (§15) не требует миграции и работает немедленно через
  `?hp-labs=-iso`/`off`, как и в Stage 1.
- AC1–AC16 однозначны, у каждого указан тип доказательства (за вычетом Low-2)
  и план автотестов (§12) даёт конкретный, воспроизводимый по коду маршрут;
  §12.1 явно требует, чтобы каждый unit-мутант «умел падать» (удаление
  внешнего edge, сдвиг leaf с jamb, включение HA-состояния в cache key,
  дублирование floor symbol, лишний light layer).
- Не найдено ни одного продуктового утверждения о поведении, которое не
  следует ни из канонических документов, ни из решений владельца Q0–Q6, ни
  из чтения существующего кода, и при этом не помечено как предположение;
  раздел §16 корректно отделяет свободно изменяемые технические детали
  (именование модулей, точные проценты высоты панелей, число SVG-корней) от
  зафиксированных владельцем решений.
- Реестр `docs/specs/README.md` обновлён тем же коммитом, коммит несёт
  корректные трейлеры (`Issue: #122`, `User-Visible: no`) и не содержит
  изменений класса A — правило №1 соблюдено на этапе `spec`.

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

- Не проверял реализуемость конкретной геометрической декомпозиции
  (`iso-openings.ts`/`iso-scene.ts`, точные проценты высоты панелей, число
  SVG-defs) — по правилам ТЗ (§16) это свободно изменяемое техническое
  предположение автора кода, не предмет ревью ТЗ.
- Не проверял реальный performance-профиль `large-house-isometric-v1` и не
  прогонял #124 — на этапе `spec` это не требуется; факт открытости и
  статус #124 (`S1-new`) проверен через `gh issue view`, не исполнением
  бенчмарка.
- Не запускал никаких автотестов, golden или смоков — на этапе `spec` это не
  требуется; существование референсных артефактов (`isometric-no-borders-dark`
  в `demo/golden/matrix.mjs`) проверено чтением файла, не исполнением.
- Не проверял содержимое `docs/adr/089-isometric-stage1-renderer.md` построчно
  на полное покрытие всех констант камеры — доверился ссылке ТЗ и
  `docs/ISOMETRIC.md` как согласованному пересказу; расхождений при чтении
  обоих источников не обнаружено.
- Не оценивал субъективную эстетическую адекватность референсов владельца
  (issue #89, комментарий с изображениями) — это продуктовое решение,
  принятое владельцем через Q2 и не подлежащее пересмотру ревьюером ТЗ.

## Вердикт

Зелёный. High: 0, Medium: 0. Две находки Low (отсутствие буквальной
декларации `Touch editor: …` и три AC с типом доказательства вне буквального
перечня §2.5) — не блокируют, оставлены автору на усмотрение с записью в этом
документе; при желании их можно поправить в этом же цикле без возврата в
`S3-spec`.