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

# SPEC-REVIEW-239-r1

- **Issue:** https://github.com/Matysh/houseplan-card/issues/239
- **ТЗ:** `docs/specs/239-grid-scale-invariance.md`
- **Ветка / SHA:** `issue/239-grid-scale-invariance` @ `4c065f5`
- **Этап:** spec (PROCESS.md §2.4) · трек: обычный (`small`/`trivial` явно
  отклонены автором в аналитике issue — несколько рендереров, новый default,
  i18n, влияние на touch/performance)
- **Заход:** r1 · блокирующих циклов израсходовано 0/4 до этого вердикта
- **Ревьюер:** Claude, роль «ревьюер ТЗ»

## Скоуп

Оценивалось только ТЗ #239 — единый визуальный контракт «масштаб сетки
(`cell_cm`) не должен менять внешний вид плана» плюс новый default нового
пространства (1 см метрика / 1 дюйм imperial). Код не менялся и не
оценивался: этап S4, реализации нет, весь диапазон `origin/dev..HEAD`
состоит из одного docs-коммита.

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

1. Прочитаны `docs/SCOPE.md`, `AGENTS.md`, `PROCESS.md` целиком (первый цикл,
   правило «по дельте» §2.10 не применяется).
2. Прочитано тело issue #239 и оба комментария (аналитика с оценкой
   9/9/8/8/P1/bug/обычный трек, затем хендофф «ТЗ готово»).
3. Прочитан файл `docs/specs/239-grid-scale-invariance.md` целиком (481
   строка) и запись в `docs/specs/README.md`.
4. Построчно перепроверены фактические ссылки ТЗ на код (не поверено на
   слово — большинство утверждений §3 являются "подтверждено по коду", что
   обязывает проверить):
   - `src/houseplan-card.ts:14088`, `:14459` — `cellCm: 5` в manual create и
     floors-import draft — совпадает;
   - `src/houseplan-card.ts:20591-20595` — поле `space.scale_label` /
     `space.scale_unit` всегда рендерит сырые см без ветвления на
     `hass.config.unit_system.length === 'mi'` — совпадает буквально
     (заявление ТЗ §3.3, а не догадка);
   - `src/houseplan-card.ts:295-296` — `CELL_CM_MIN = 0.1`, `CELL_CM_MAX =
     1000` — совпадает с §5.2/§7.1 (диапазон не расширяется);
   - `src/render/opening-symbol.ts:34-42` — `jambHalf` fallback `4`,
     `outlineHalf = Math.max(16, jambHalf+8, gateDepth+8)`, `hitHalf =
     Math.max(20, ...+10, ...+12)` — совпадает с заявленными «4-12 units»;
   - `src/wall-thickness.ts:31-43` (`HATCH_REFERENCE_CELL_CM = 5`,
     `HATCH_BASE_STEP_UNITS = 8`) — арифметика `8 × (5/5) × (шаг сетки)` даёт
     заявленные 9.6 см из #230 и AC5 — проверено вычислением, не с чужих слов;
   - `src/iso-projection.ts:29-30` — `ISO_WALL_HEIGHT = 64`,
     `ISO_FLOOR_EDGE_HEIGHT = 10` — заявленные «user units» константы
     существуют и не параметризованы `cell_cm`, совпадает с §3.2.5;
   - `src/houseplan-card.ts:5241,5178-5254` — `_isoGeometryCache.get(source.key)`
     подтверждает риск «тёплый remount вернёт старую высоту», если `source.key`
     не будет включать масштаб — корректно учтено в таблице рисков §16, а не
     пропущено;
   - `src/space-geometry.ts:442-478` (`iconUnit`, `iconCqw`) — числитель и
     знаменатель оба выведены из содержимого плана в тех же plan units, поэтому
     при физически эквивалентном плане (`k = 5/cell_cm`) множитель `k`
     сокращается сам — заявление §3.1 «эти пути уже верны, не домножать»
     подтверждено алгеброй, а не принято на веру;
   - `docs/USER-GUIDE.ru.md:1092,1145` — термины «дюйм»/«фут» для физических
     размеров уже существуют в продукте, значит предлагаемая подпись «1 дюйм на
     клетку» не изобретает новую терминологию.
5. Сверены §5 (входит/не входит) с §6 (классификация размеров) и §8
   (контракт по поверхностям) на отсутствие противоречий — реестр
   `Physical/Screen/Plan-relative/Visual unit/Grid` покрывает все пункты §3.2
   без пропусков и без двойного назначения одного размера в два класса.
6. Сопоставлены критерии приёмки §13 (AC1–AC16) с планом автотестов §14 —
   не как формальность, а по прямому указанию для этого этапа: «указание
   способа доказательства». Для сверки взяты два прецедента из этого же
   репозитория: `docs/specs/230-hatch-density-normalization.md` §13 (план
   тестов поимённо покрывает AC1–AC12) и `docs/specs/238-opening-inner-distances.md`
   §15 (таблица AC с отдельной графой «Доказательство» для всех 15 AC, включая
   мета-критерии производительности и документации — AC14 «unit со
   счётчиком/ревью кода», AC15 «provenance + ревью кода»). См. находку ниже.
7. Проверен гейт `node scripts/check-docs.mjs` — единственный применимый на
   docs-only диффе класса C. `npx tsc --noEmit` / `npm test` / `npm run build`
   не запускались: диапазон изменений не содержит ни одного файла класса A/B
   (`git diff origin/dev...HEAD --stat` — только `docs/specs/239-*.md` и
   строка в `docs/specs/README.md`), эти гейты ничего не проверяют на чистой
   документации и были бы тратой времени без предмета (см. «Объём гейтов
   соразмерен задаче»).

## Находки

### Medium (в скоупе задачи — исправляется в этом ТЗ)

**M1. §13 Acceptance criteria не указывает способ доказательства для AC13,
AC14, AC16, и это не восстанавливается однозначно ни из §14 «План
автотестов», ни из таблицы рисков §16.**

- AC13 (инвариант `cell_cm: 5` = pre-#239 контракт) частично закрыт: в самом
  тексте AC упомянут «current golden», так что проверяемость угадывается, но
  §14.3 говорит лишь «Golden baseline разработчик не принимает» — не называет
  golden прямым доказательством AC13.
- AC14 (touch/gesture-инвариант: pan/pinch/pointercancel не получают новых
  действий, opening action area не меньше эталонной) не назван ни в одном
  пункте §14, а из таблицы рисков (§16, строка «Touch target станет physical»)
  восстанавливается только половина критерия — про размер hit-area, но не про
  «никакой новый жест ничего не запускает».
- AC16 (EN/RU user guide и оба changelog объясняют новый контракт) не назван
  ни в §14, ни в release-артефактах §17 как проверяемый пункт, хотя оба
  changelog там перечислены как артефакт.

Это не придирка к форме: у этой же задачи есть два прямых прецедента в этом
репозитории, оба прошли ревью зелёными на этом самом требовании процесса.
`docs/specs/230-hatch-density-normalization.md` §13 поимённо связывает каждый
AC1–AC12 с тестом. `docs/specs/238-opening-inner-distances.md` §15 — тот же
issue-поток, тот же автор, документ на день раньше #239 — держит отдельную
графу «Доказательство» и заполняет её даже для мета-критериев вроде
производительности (AC14: «unit со счётчиком/ревью кода») и документации
(AC15: «provenance + ревью кода»). #239 явно откатывается от этой практики без
объяснения, и без неё код-ревью не имеет явного контракта: чем именно должна
быть закрыта строка «pan/pinch не получают новых действий» — тестом или
утверждением автора. Учитывая объём и риск задачи (сложность 8/10, риск 8/10 в
собственной оценке автора), для «not by accident» touch-инварианта и для
одного из главных anti-regression AC (AC13) это не косметика.

**Как починить:** добавить в §13 колонку «Доказательство» (как в #238 §15)
либо явно перечислить AC13/AC14/AC16 в §14 с указанием конкретного смока,
unit-теста или «ревью кода» — по аналогии с уже принятым для этой же задачи
подходом «AC15 — только ревью кода, потому что perf-гейт до беты» (эта фраза
в документе уже есть для AC15, её не хватает для соседних AC).

### Low (снимается с записью, не блокирует)

**L1. §10 «Данные, i18n...» не называет конкретный текст/ключ новой imperial-
подписи внутри самого i18n-раздела** — формулировка «новые EN/RU строки нужны
для imperial unit label» не самодостаточна. Текст фактически дан двумя
разделами ниже, в §9.2 («дюйм на клетку» / `in per cell`), так что
неоднозначности для реализации нет — но это расходится с конвенцией
остальных 239 спеков репозитория (например, #157: «`opening.passage`,
`opening.passage_binding_warning`»; #167: «label «Plan only»»; #094:
«`tap.toggle`: «Переключить состояние»»), где i18n-раздел сам перечисляет
строки, а не отсылает к UX-разделу. Снимаю как Low: содержательно текст уже
в документе, вопрос чисто в консолидации. Автор может перенести/продублировать
строку в §10 попутно с фиксом M1 либо оставить как есть.

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

- **Продуктовая рамка.** Сценарий и «что человек увидит» — обе продуктовые
  секции §7.1 присутствуют первыми, отвечают на «какая персона / какая
  поверхность / какой момент» и не используют термины реализации. Задача
  закрывает J4/J6 из `docs/SCOPE.md`, конфликтов с out-of-scope нет.
- **Ни одной догадки, выданной за факт.** Каждое диагностическое утверждение
  §3 («что уже масштабируется правильно» / «где инвариант нарушен») проверено
  построчно по коду (см. «Как проверялось», п.4) и совпадает буквально, а не
  на уровне пересказа. Технические решения (§19) явно помечены как «assumed,
  change freely» и не выданы за продуктовое решение.
- **Продуктовых вопросов владельцу нет, и это оправдано.** Единственный
  потенциально продуктовый вопрос — «должен ли визуально измениться уже
  существующий сохранённый план с `cell_cm ≠ 5` после фикса» — уже
  разрешён самим текстом issue («Нужно проверить и при необходимости
  нормализовать весь визуальный контракт»): это и есть цель бага, не
  побочный эффект, и AC13/§17 changelog корректно фиксируют это как
  осознанное, объявленное в changelog поведение, а не тихую перерисовку.
- **Скоуп/не-скоуп непротиворечивы.** §5.2 явно запрещает менять
  `GRID_N`/`GRID_PITCH`/snap-алгоритм и migration существующих `cell_cm` —
  это ровно то, что держит задачу в границах «визуальный слой», не
  «координатная модель», и совпадает с диапазоном 0.1…1000, подтверждённым в
  коде.
- **Классификация размеров (§6) внутренне непротиворечива** и предотвращает
  ровно ту ошибку, которую называет главным риском сам автор (общий CSS/SVG
  transform повторно умножил бы уже верные physical/plan-relative пути) —
  проверено алгеброй на `iconCqw`/`iconUnit` (см. «Как проверялось», п.4).
- **AC1–AC12 однозначны и алгебраически проверяемы** без реализации:
  например AC1 (`gridVisualScale(5) === 1`, `5/cellCm` для остальных, `1` для
  невалидных), AC5 (physical-контроль не должен домножаться второй раз — уже
  сформулирован как мутационный тест, а не как описание), AC9 (canonical
  `2.54` для imperial — точное значение 1 дюйма, не приближение).
- **Откат (§18) и release-артефакты (§17) полны**: один revert коммита,
  явное заявление «данные не мигрируют и остаются валидными и после отката»,
  оба changelog, оба USER-GUIDE, CANVAS.md, ARCHITECTURE.md, TESTING.md и
  пересъёмка public docs screenshot — ничего из обязательного набора не
  забыто.
- **Риски (§16) содержательны, не общие слова**: каждая строка называет
  конкретный механизм провала (например, «px/unitless `calc()` в SVG
  вычислится не в те units») и конкретную защиту, без карго-культных «будем
  осторожны».
- **Гейт docs зелёный**: `node scripts/check-docs.mjs` → `Documentation
  checks passed (7 files, 10 external links)`.

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

- `npx tsc --noEmit`, `npm test`, `npm run build` — не запускал: диапазон
  диффа не содержит файлов класса A/B (только `docs/specs/239-*.md` и строка
  реестра), эти гейты не имеют предмета проверки на этом этапе и их прогон на
  чистой документации был бы потерей времени, а не тщательностью.
- Реализацию классов Physical/Screen/Plan-relative/Visual/Grid — кода ещё
  нет, оценивалась только логическая непротиворечивость классификации, не её
  будущее исполнение.
- Полный текст остальных ~470 существующих ТЗ репозитория — выбраны только
  #230 (единственный прямой предок контракта) и #238 (непосредственно
  предыдущая задача в очереди, тот же автор) как контрольные образцы
  конвенции «AC → доказательство»; это не полная статистика по всем спекам,
  а два целевых прецедента, достаточных для находки M1.
- Golden/browser smoke/performance — не запускались и не должны: реализации
  нет, эти гейты относятся к S6/S7 и предрелизному прогону (PROCESS.md §8),
  не к ревью ТЗ.