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

SPEC-REVIEW-230-r1

• Issue: https://github.com/Matysh/houseplan-card/issues/230
• ТЗ: docs/specs/230-hatch-density-normalization.md
• Ветка / SHA: issue/230-hatch-density-normalization @ 2396044
• Этап: spec (PROCESS.md §2.4) · трек: small (метка на issue)
• Заход: r1 · блокирующих циклов израсходовано 0/4 до этого вердикта
• Ревьюер: Claude, роль «ревьюер ТЗ»

Скоуп

Оценивалось ТЗ #230 — нормализация плотности штриховки тела стены к физическим сантиметрам плана и удаление зумовой компенсации паттерна. Код не менялся и не оценивался (реализации нет, этап S4). Проверялись: соответствие docs/SCOPE.md, фактическая точность ссылок на код и на golden-фикстуры, однозначность и доказуемость AC1–AC10, согласованность Scope/Contract/AC между собой.

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

1. Прочитаны docs/SCOPE.md, PROCESS.md целиком (первый цикл, правило «по дельте» §2.10 не применяется).
2. Прочитано тело issue #230 и единственный комментарий («ТЗ готово, на ревью»); в истории issue нет отдельного S2-analysis-комментария с шаблонной «Оценкой» (§7.2) — трек small и метки bug/polish видны только как текущее состояние.
3. Прочитан файл ТЗ целиком.
4. Построчно проверены все фактические ссылки на код:
   • src/wall-thickness.ts:40-73 (wallBodyNeedsSolid, WALL_HATCH_MIN_PX = 3, clampWallCm, wallCmToUnits) — совпадает с ТЗ;
   • src/houseplan-card.ts:6163-6166 (_cellCm, дефолт 5 при нечисловом/≤0 значении) — совпадает;
   • src/houseplan-card.ts:11079-11093 (_wallHatchDefs, const inv = ..., patternTransform="rotate(45) scale(${inv})") — совпадает буквально;
   • src/space-render.ts:509-513 (тот же <pattern> без scale, только rotate(45)) — подтверждает заявленное расхождение рендереров уже сегодня;
   • src/space-geometry.ts:11,197,199 (NORM_W=1000, GRID_N=240, GRID_PITCH=NORM_W/GRID_N≈4.1667) — подтверждает таблицу в §3 ТЗ;
   • src/houseplan-card.ts:285-286, src/plan-optimizer.ts:32-33 (CELL_CM_MIN=0.1, CELL_CM_MAX=1000) — подтверждает диапазон cell_cm из §8.3.
5. Алгебраически проверены формулы AC1–AC6: wallHatchStepUnits(cellCm) = 8·(5/cellCm); отношение wallCmToUnits(cm,cell,GP)/wallHatchStepUnits(cell) = cm·GP/40 не зависит от cell, то есть AC2 доказывает именно заявленную инвариантность, а для cm=30 против cm=15 отношение ровно вдвое (AC3). Клампы [0.5, 80] алгебраически покрывают весь диапазон cell_cm 0.1…1000 без разрывов (AC5).
6. Проверена схема вызова wallBodyNeedsSolid в обоих рендерерах (houseplan-card.ts:11312, space-render.ts:473) — точка интеграции для нового wallHatchNeedsSolid (§8.4) существует и однозначна.
7. Проверены golden-фикстуры, а не только текст ТЗ о них: demo/fixtures/large-house.mjs:209-218 (perf-floor-1, cell_cm: 5, стены 15 см, show_borders: true) и demo/golden/matrix.mjs:328-331 (сценарии large-house-zoom-040-dark — zoom: 0.4, large-house-zoom-250-dark — zoom: 2.5, оба на fixture: 'large', space: 'perf-floor-1') — см. High-1.
8. Проверено, что src/space-card.ts не является третьим независимым потребителем паттерна: он рендерит через renderSpaceStatic из space-render.ts (уже в скоупе §6), CSS-класс .wallbody{fill:url(#hp-wall-hatch)} лишь ссылается на тот же <pattern>, который создаёт вызванный рендерер — не находка.
9. Проверено docs/WALL-THICKNESS.md §3 (Body render) — текущая редакция не описывает ни зависимость шага паттерна от cell_cm, ни зумовую компенсацию, то есть менять там формально нечего, но раздел про решение «убрать зумовую компенсацию» отсутствует — см. Low-1.
10. Проверено docs/USER-GUIDE.ru.md:442 — существующая строка про штриховку («на малом масштабе штриховка скрывается, тело остаётся») не противоречит планируемой правке §15.
11. Код не запускался, гейты не гонялись — реализации нет, это ожидаемо на этапе ревью ТЗ.

Находки

High-1 — риск-анализ и AC10 построены на неверной посылке о golden-фикстурах

Файл: docs/specs/230-hatch-density-normalization.md, §11 «Риски», п.2 (Golden) и §12, AC10.

Формулировка ТЗ: «Все golden-фикстуры используют cell_cm: 5 (demo/fixtures/*.mjs, demo/golden/harness.mjs) и не меняют зум, поэтому эталоны не должны измениться ни в одном пикселе. Это проверяемое утверждение: golden:verify обязан пройти без переснятия.»

Проблема. Первая половина утверждения верна: оба файла фикстур (demo/fixtures/large-house.mjs, demo/fixtures/visual-matrix.mjs) задают cell_cm: 5 для каждого пространства. Вторая половина — «не меняют зум» — фактически неверна: demo/golden/matrix.mjs:328-331 определяет ровно два сценария на фикстуре large (пространство perf-floor-1, стены 15 см, show_borders: true, то есть тело стены рисуется):

{ id: 'large-house-zoom-040-dark', fixture: 'large', space: 'perf-floor-1',
  mode: 'view', zoom: 0.4, theme: 'dark', viewport: { width: 1180, height: 900 }, ...stage },
{ id: 'large-house-zoom-250-dark', fixture: 'large', space: 'perf-floor-1',
  mode: 'view', zoom: 2.5, theme: 'dark', viewport: { width: 1180, height: 900 }, ...stage },

demo/golden/harness.mjs:440-441 применяет scenario.zoom через card._applyView(scenario.zoom, 500, 500) — то есть зум реально устанавливается перед снимком, а не игнорируется.

Это не мелкая деталь, а прямое противоречие продуктовому решению владельца из того же ТЗ (§4, п.2): «Зумовая компенсация убирается... Число полос внутри стены одинаково на любом зуме». Сегодня inv = max(0.4, 1/max(zoom,0.4)) при zoom=0.4 даёт inv=2.5, при zoom=2.5 даёт inv=0.4 — то есть паттерн hp-wall-hatch в этих двух golden-сценах сегодня отрисован с ненулевым масштабом, а после правки patternTransform вообще не содержит scale (§8.2 ТЗ, дословно: «Множителя 1/zoom больше нет ни в одном рендерере»). Это ровно та точка, где линии паттерна на экране видимо переместятся — если тело стены на этих экранах не провалилось в solid (порог WALL_HATCH_MIN_PX=3), разница будет пикселем, особенно на zoom: 2.5 (зум внутрь, то есть больше пикселей на юнит, а не меньше — вероятность попасть в solid-режим там ниже, чем на zoom: 0.4).

Почему это находка, а не техническая деталь. Владелец явно одобрил именно это изменение видимого поведения при зуме (§4, п.2) — то есть расхождение этих двух golden-сцен, если оно произойдёт, не является «правка задела больше заявленного» из формулировки риска в самом ТЗ; это прямое и ожидаемое следствие продуктового решения, зафиксированного в том же документе. ТЗ противоречит самому себе: §4 обещает видимое изменение при любом зуме ≠ эталонного поведения на экране, а §11/AC10 обещают, что ни одна golden-сцена не изменится ни на пиксель. Оба обещания не могут быть верны одновременно для сцен, снятых при zoom ≠ 1.

Почему это блокирует, а не варьируется по ходу реализации. AC10 — единственная строка ТЗ, которая должна поймать регрессию из риска №3 (расхождение карты и статического рендерера) и защитить от случайного охвата больше заявленного. Если формулировка AC10 неверна, разработчик либо (а) увидит красный golden:verify там, где всё сделано правильно, и не будет знать, чинить код или переснимать эталон — ровно то самое решение, которое процесс явно запрещает принимать в одиночку («переснятие ради зелёного CI», §12 PROCESS.md), либо (б) продавит переснятие двух сцен без разбора, чтобы пройти AC10, что легитимно только через golden:accept -- --reviewed, но ТЗ не называет этот путь и не готовит к нему код-ревью.

Что нужно. Явно разобрать оба сценария large-house-zoom-*-dark в §11/§12:

1. посчитать/оговорить, действительно ли тело стены perf-floor-1 (15 см, cell_cm: 5) остаётся в режиме hatch (не solid) на этих двух зумах при их viewport; и
2. если остаётся — заранее объявить, что эти две сцены ожидаемо меняются (это следствие §4 п.2, не побочный эффект) и должны быть переснятые через golden:accept -- --reviewed с отдельной пометкой в хендоффе, ЛИБО сузить AC10 формулировкой вида «golden:verify проходит без переснятия для всех сцен, кроме large-house-zoom-040-dark/large-house-zoom-250-dark, которые меняются предсказуемо и переснимаются по правилу §12 PROCESS.md».

Medium-1 — контракт «оба рендерера» не имеет собственного доказательства для статического рендерера

Файл: docs/specs/230-hatch-density-normalization.md, §6, §8.2, AC7, AC8, §13.

Проблема. §6 (Scope) и §8.2 (Contract) требуют, чтобы оба рендерера — houseplan-card.ts (интерактивная карта) и space-render.ts (статический рендерер Room View card / киоск) — строили <pattern> через wallHatchStepUnits(cellCm). Но AC7 и AC8 явно говорят «в разметке карты» / «на реальной карте», и запланированный смок (§13, demo/smoke_wall_hatch_density.mjs) описан как проверка «на реальной карте при cell_cm 5 и 25» — то есть тоже только интерактивный рендерер. Ни один AC не проверяет разметку паттерна space-render.ts при cell_cm ≠ 5.

AC10 (golden:verify) не закрывает этот пробел: как показано в High-1, все golden-сцены используют cell_cm: 5, а при cell_cm === 5 wallHatchStepUnits(5) === 8 — то есть числовое совпадение со старой константой width="8" height="8". Если разработчик поправит только houseplan-card.ts и оставит в space-render.ts:509 старый жёстко заданный width="8" height="8", все AC1–AC10 в текущей формулировке останутся зелёными, а требование §6/§8.2 «тот же паттерн через ту же функцию» останется невыполненным и непроверенным ни одним автотестом — регрессия того самого расхождения рендереров, которое ТЗ называет риском №3 и обещает зафиксировать тестом.

Что нужно. Одна из двух правок: расширить формулировку AC7/AC8 (или добавить AC7b) так, чтобы она явно требовала проверки разметки паттерна space-render.ts при cell_cm ≠ 5 — например, через прямой вызов renderSpaceStatic/buildSpaceDevices с фикстурой cell_cm: 25 и разбор получившейся строки <pattern>, не обязательно в браузере. Это устраняет пробел без изменения продуктового контракта.

Low-1 — канонический документ подсистемы не входит в release-артефакты

Файл: docs/specs/230-hatch-density-normalization.md, §15.

docs/WALL-THICKNESS.md §3 («Body render») — канонический документ ровно той подсистемы, которую меняет эта задача (штриховка тела стены), и в этом же документе уже принято фиксировать точечные решения такого рода инлайн-ссылками на issue (#197, #198, #201 в тексте §3/§8). §15 ТЗ называет только оба CHANGELOG и строку в docs/USER-GUIDE.ru.md, не упоминая обновление WALL-THICKNESS.md фразой про новую формулу шага и про то, что зумовая компенсация паттерна больше не существует ни в одном рендерере. Не блокирует и не влияет на проверяемость AC — снимаю с рекомендацией добавить одну фразу в §3 канона в том же коммите, что и код (по аналогии с уже принятой в документе практикой).

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

• Обязательные разделы §7.1 присутствуют по существу: сценарий и персона (§1), видимое изменение до/после (§2), причина (§3), продуктовые решения владельца (§4), цели (§5), scope/не-scope (§6–7), контракт (§8), данные/i18n (§9), performance (§10), риски (§11), AC1–AC10 (§12), план тестов (§13), мутационный гейт (§14), release-артефакты (§15), откат (§16), явный блок предположений (§17).
• Продуктовая рамка (§1–2) отвечает на оба обязательных вопроса — персона («ведёт планы двух домов» из docs/SCOPE.md J4/J6), поверхность (десктопный просмотр плана), объём видимого изменения одной фразой без терминов реализации.
• Главный технический вывод ТЗ верен и лучше исходного issue. Формула из тела issue (cell_cm/5) действительно усугубляет разброс, а не устраняет его — проверено алгебраическим пересчётом (см. «Как проверялось», п.5) тем же способом, каким ТЗ его приводит. Обратный множитель 5/cellCm — корректное решение поставленной владельцем задачи «привязать плотность к сантиметрам плана».
• AC1, AC4, AC5, AC6, AC9 однозначны, проверяемы и указывают способ доказательства (unit); тривиально вычисляются вручную и дают ожидаемый автором результат — не оставляют пространства для интерпретации при написании теста.
• AC2/AC3 математически доказывают именно то, что заявлено целью (§5): независимость числа полос от cell_cm и пропорциональность толщине стены, а не декларируют это без доказательства.
• Обращение к геттеру _cellCm (нечисловой/нулевой/отрицательный → 5) в §8.1 зафиксировано с точной ссылкой на существующий прецедент (houseplan-card.ts:6163) — не самостоятельно изобретённое правило.
• §7 («Не входит в задачу») корректно исключает угол штриховки, порог WALL_HATCH_MIN_PX, изометрию (_renderProjection === 'iso' — подтверждено чтением houseplan-card.ts:11303) и штриховку прочих сущностей — все четыре исключения проверены по коду, а не заявлены на веру.
• Touch editor: not exposed — корректное значение: задача не добавляет ни одного взаимодействия, только характер отрисовки уже существующего слоя.
• Мутационный гейт (§14) целится в реальные, а не декоративные ошибки: hatch-step-inverted прямо воспроизводит ошибку из формулировки issue, hatch-zoom-compensation-back защищает именно от регрессии, названной в риске №3.
• Откат (§16) реалистичен: чистая функция, конфиг не меняется, revert безопасен.

Продуктовые вопросы владельцу

Не требуются. Единственная точка, где решение владельца уже расходится с текстом того же ТЗ (High-1), решается не новым продуктовым вопросом, а уточнением формулировки риска/AC — владелец уже высказался по существу (§4, п.2), автору нужно привести §11/AC10 в соответствие с этим решением, а не получить новое.

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

• Реализацию — её не существует на этом этапе.
• Действительно ли large-house-zoom-040-dark / large-house-zoom-250-dark сегодня попадают в solid-режим по WALL_HATCH_MIN_PX=3 или показывают видимую штриховку — для этого нужно посчитать pxPerUnit через реальный viewport/_baseVb/_applyView этой фикстуры или прогнать golden:verify по факту. Не требуется для вывода High-1: сам факт, что ТЗ безусловно утверждает «зум не меняется» при наличии двух сцен с zoom ≠ 1, уже делает риск-анализ и AC10 недостоверными независимо от точного числового исхода.
• Соответствие метки small фактической сложности задачи (три модуля, golden-риск, требующий отдельного расчёта) — не поднимаю как находку: ТЗ существует как полноценный файл docs/specs/230-*.md независимо от метки трека, содержание оценивается по существу, а не по тому, в какой контейнер его положили.
• demo/golden/harness.mjs целиком и остальные ~40 golden-сцен построчно — проверено выборочно (grep на zoom:/cell_cm), достаточно для вывода High-1; полный построчный обзор оставляю код-ревью при реализации.

Вердикт

Одна блокирующая находка (High-1): риск-анализ и AC10 построены на проверяемо неверной посылке о golden-фикстурах, что делает главный защитный AC задачи ненадёжным как написано. Medium-1 и Low-1 в скоупе задачи и чинятся правкой текста ТЗ, без изменения продуктового решения владельца. Итог — жёлтый: возврат автору на правку ТЗ, повторный цикл ревью по дельте (PROCESS.md §2.10).