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

SPEC-REVIEW-230-r2

• Issue: https://github.com/Matysh/houseplan-card/issues/230
• ТЗ: docs/specs/230-hatch-density-normalization.md
• Ветка / SHA: issue/230-hatch-density-normalization @ 44a35fd
• Этап: spec (PROCESS.md §2.4) · трек: small (метка на issue)
• Заход: r2 · блокирующих циклов израсходовано 1/4 до этого вердикта
• Ревьюер: Claude, роль «ревьюер ТЗ»
• Предыдущий раунд: SPEC-REVIEW-230-r1.md, вердикт жёлтый на SHA 2396044 (комментарий issue от 2026-08-21T11:46:32Z). SHA в вердикте r1 не был назван явно в тексте — восстановлен по коммиту docs: review document for #230 (6872dc4, родитель 2396044) и подтверждён телом комментария.

Скоуп раунда

Разбор по дельте (PROCESS.md §2.10): сравнивается 2396044 (SHA r1) → 44a35fd (текущий HEAD). Дельта — правка того же файла ТЗ, git diff 2396044..44a35fd -- docs/specs/230-hatch-density-normalization.md, 42 вставки / 12 удалений, локализована в §11 п.2, §12 (AC10, новые AC11/AC12), §13, §14, §15. Код не менялся (реализации всё ещё нет, этап S4). Дельта локальна и продуктовое решение владельца не меняет — полный повторный разбор всего документа не требуется; §1–§10, §16, §17 и AC1–AC9 наследуются из r1 (см. раздел «Унаследовано»). Отдельно проверено, не создала ли правка новое противоречие с неизменённой частью документа — нашла (см. Low-1 ниже).

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

1. Найден вердикт r1 и SHA, на котором он получен (см. выше).
2. Получены git diff 2396044..44a35fd и текущий полный текст файла ТЗ.
3. По каждой находке r1 (High-1, Medium-1, Low-1) построчно сверено, что именно в дельте её закрывает — раздел «Закрытие раунда r1» ниже.
4. Пересчитана таблица шагов в §11 п.2 самостоятельно, по той же формуле, что цитирует ТЗ: inv = max(0.4, 1/max(zoom,0.4)), шаг-сейчас = 8·inv.
   • zoom 0.4: inv = max(0.4, 1/0.4) = 2.5 → 8·2.5 = 20.0 — совпадает со строкой ТЗ.
   • zoom 2.5: inv = max(0.4, 1/2.5) = max(0.4,0.4) = 0.4 → 8·0.4 = 3.2 — совпадает.
   • «шаг после» для обеих сцен — wallHatchStepUnits(5) = 8·(5/5) = 8 — совпадает с заявленным.
5. Прочитан текущий AC10–AC12 и сверен с §13 (план тестов) и §14 (мутанты): каждый новый AC покрыт ровно одним пунктом плана тестов и как минимум одним мутантом-гвардом; осиротевших AC нет, осиротевших мутантов нет. wallHatchStepUnits(25) = 8·(5/25) = 1.6, что отличимо от старой константы 8 в space-render.ts — AC12 способен упасть, если правку второго рендерера не сделают.
6. Прочитано тело issue #230 и все три комментария (r1-заявка автора, вердикт r1, ответ автора на r2) — расчёт таблицы в комментарии автора совпадает с расчётом в файле ТЗ и с пересчётом в п.4.
7. Проверено, не противоречит ли скорректированный §11/AC10–12 неизменённым разделам документа. Нашлось: §5 («Цели»), второй пункт — см. Low-1.
8. Код, гейты, автотесты не запускались — реализации нет, это ожидаемо на этапе ревью ТЗ (как и в r1).

Закрытие раунда r1

Находка r1	Чем закрыта	Где это видно
High-1 — риск-анализ и AC10 построены на неверной посылке «фикстуры не меняют зум»	§11 п.2 переписан: явно называет обе зумовые сцены, приводит таблицу «шаг сейчас/после», признаёт изменение ожидаемым следствием §4.2. AC10 сужен до «расходится ровно на двух сценах, третья — провал». Добавлен AC11 на осознанное переснятие через golden:accept -- --reviewed	docs/specs/230-hatch-density-normalization.md:189-207 (§11 п.2), :244-246 (AC10), :248-250 (AC11)
Medium-1 — контракт «оба рендерера» не имел собственного AC для space-render.ts	Добавлен AC12: space-render.ts при cell_cm: 25 строит width/height по wallHatchStepUnits(25), без scale. Смок demo/smoke_wall_hatch_density.mjs расширен на статический рендерер. Добавлен мутант hatch-static-renderer-untouched	:252-256 (AC12), :261-263 (§13), :276 (§14)
Low-1 — WALL-THICKNESS.md не входил в release-артефакты	§15 явно называет docs/WALL-THICKNESS.md каноническим документом подсистемы и требует правки в нём в том же коммите	:282-285 (§15)

Все три находки r1 закрыты по существу, не декларативно: формулы в новой таблице §11 п.2 пересчитаны независимо (см. «Как проверялось», п.4) и совпадают; AC12 действительно различим от старого поведения численно (8 vs 1.6), то есть способен упасть, если правку в space-render.ts не внесут; AC10 в новой формулировке — falsifiable в обе стороны (ловит и «третью» разошедшуюся сцену, и случай, когда ожидаемые две сцены не разошлись).

Унаследовано из r1

Принято без повторной проверки, документ SPEC-REVIEW-230-r1.md на SHA 2396044; дельта r1→r2 их не касается:

• §1–2 продуктовая рамка (сценарий/персона, видимое изменение до/после) — отвечает на оба обязательных вопроса, персона из docs/SCOPE.md J4/J6.
• §3 подтверждённая причина и вывод «формула issue неверна, верный множитель — 5/cell_cm» — проверено алгебраическим пересчётом в r1.
• §4 продуктовые решения владельца — зафиксированы, не менялись.
• §6–7 Scope / Не входит в задачу — включая проверку по коду, что space-card.ts не третий независимый потребитель паттерна.
• §8 Контракт (шаг, применение, пределы, защита от каши) и алгебраическое доказательство AC2/AC3 (независимость числа полос от cell_cm, пропорциональность толщине).
• §9–10 данные/i18n/perf.
• AC1, AC4–AC9 — однозначны, проверяемы, указывают способ доказательства; не затронуты дельтой.
• §16 Откат, §17 Принятые предположения.
• Обязательные разделы §7.1 присутствуют по существу (полный перечень — в r1).
• Мутационный гейт для мутантов, унаследованных из r1 (hatch-step-ignores-cell-cm, hatch-step-inverted, hatch-step-unclamped, hatch-stroke-not-scaled, hatch-zoom-compensation-back, hatch-density-solid-threshold-off).

Находки

Low-1 — §5 «Цели» не обновлён вслед за исправлением §11/AC10–11 и противоречит им

Файл: docs/specs/230-hatch-density-normalization.md:92-93 (§5, второй пункт).

Формулировка ТЗ: «При cell_cm: 5 вид не меняется — ни на карте, ни в статическом рендерере, ни в golden-эталонах.»

Проблема. Это безусловное утверждение написано до правки r2 и не обновлено вместе с ней. После правки §11 п.2 и AC10/AC11 прямо утверждают обратное для двух конкретных golden-эталонов: large-house-zoom-040-dark и large-house-zoom-250-dark — обе сцены сняты на фикстуре cell_cm: 5 (perf-floor-1), и обе, по признанию самого документа, «изменятся — и это прямое следствие решения владельца §4.2». Причина расхождения — не в cell_cm-зависимой части правки (при cell_cm: 5 шаг действительно не меняется, 8 → 8), а во втором, отдельном решении владельца — удалении зумовой компенсации. §5 говорит только про cell_cm: 5 и не делает оговорки про зум, поэтому как написано противоречит §11/AC10/AC11 в одном и том же документе для того же значения cell_cm.

Почему не блокирует. ACs 10, 11 и 12 — обязывающая, точная и самодостаточная часть контракта; они не ссылаются на §5 и не зависят от его формулировки. Разработчик, который реализует задачу по AC, получит верное поведение независимо от того, поправлена ли фраза в §5. Риск — не в неверной реализации, а в том, что читатель, остановившийся на §5, сделает неверный вывод о golden без учёта §11 — то есть это дефект качества текста, не дефект контракта.

Что нужно. Одна фраза-оговорка в §5, например: «...кроме двух golden-сцен, снятых при зуме ≠ 1 (large-house-zoom-040-dark, large-house-zoom-250-dark) — см. §11 п.2» — либо сузить формулировку до «шаг паттерна не меняется» (что действительно верно при cell_cm: 5 безусловно), не упоминая golden-эталоны в этом пункте вовсе.

Решение ревьюера. Low, не блокирует и не влияет на проверяемость AC10–AC12 — снимаю с рекомендацией поправить одной фразой при следующей правке файла (не обязательно отдельным циклом).

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

• Все три находки r1 закрыты по существу (см. таблицу выше), включая пересчёт числовых значений, а не просто присутствие текста.
• Новый AC10 falsifiable в обе стороны: провалится и если разойдётся третья сцена, и если ожидаемые две не разойдутся вовсе (что покрывает ранее открытый в r1 вопрос — попадает ли perf-floor-1 в режим solid на этих зумах; правильный исход теперь виден по факту прогона, а не предсказывается заранее).
• AC11 и AC12 указывают способ доказательства (процесс golden:accept -- reviewed с записью в отчёте; браузерный смок) и не оставляют пространства для интерпретации.
• §13/§14 согласованы с новыми AC: ни один AC не остался без пункта плана тестов, ни один новый мутант не остался без AC-обоснования.
• §15 теперь называет все три необходимые точки: оба CHANGELOG, USER-GUIDE.ru.md, канонический WALL-THICKNESS.md.

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

Не требуются. Единственная находка раунда (Low-1) — текстовая несогласованность внутри документа, решается редактурой, не требует нового продуктового решения: владелец уже высказался (§4 п.2, комментарий от 2026-08-21), автору дельты нужно распространить эту формулировку на §5.

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

• Реализацию — её не существует на этом этапе (не изменилось с r1).
• Полный построчный обзор demo/golden/matrix.mjs (~40 сцен) на предмет третьих сцен с zoom ≠ 1 вне large/perf-floor-1 — не требуется для вывода этого раунда: AC10 в текущей формулировке сам ловит любую такую сцену как провал критерия на этапе код-ревью/CI, независимо от того, нашёл ли её ревьюер ТЗ заранее.
• Действительно ли perf-floor-1 на этих двух зумах уже сегодня в режиме solid — не пересчитывалось; не влияет на вывод, так как новая формулировка AC10 корректно обрабатывает оба исхода (см. «Что проверено и корректно»).
• Гейты (tsc, npm test, npm run build, смоки, golden:verify) не прогонялись — стадия spec, кода нет; это симметрично r1 и ожидаемо.

Вердикт

Все блокирующие и заявленные-в-скоупе находки r1 (High-1, Medium-1, Low-1) закрыты по существу и проверены пересчётом, а не на слово автора. Единственная находка этого раунда — Low, текстовая несогласованность §5 с исправленным §11/AC10–11, не влияющая на проверяемость контракта; снимается решением ревьюера с рекомендацией автору. High: 0, Medium: 0. Итог — зелёный: ТЗ готово к статусу «Готово к разработке» (PROCESS.md §2.5).