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

SPEC-REVIEW-199-r1 — Optimize geometry preflight

• Issue: https://github.com/Matysh/houseplan-card/issues/199
• ТЗ: docs/specs/199-optimize-geometry-preflight.md, коммит 0ac63b6 на ветке issue/199-optimize-geometry-preflight (родитель c397b78 → 4dbdb44 → dev@0d91c1e на момент ревью).
• Трек: обычный (issue не помечен small), файл ТЗ обязателен и создан.
• Заход: r1 (первый цикл этого этапа для #199).
• Вердикт: см. итог ниже.

Скоуп ревью

Разобрано ТЗ целиком: сценарий, продуктовые решения владельца (Q1–Q3 в комментариях issue), контракт preflight (§7), UX-контракт (§8), backend/ atomicity (§9), производительность (§10), AC1–AC14 (§11), план тестов (§12), риски (§13), touch (§14), release-артефакты и rollback (§15), блок принятых технических предположений (§16).

Ревью строго по PROCESS.md §2.4: ищу, где ТЗ невыполнимо или непроверяемо, а не соглашаюсь с автором. Устных пояснений автора не было — только issue, комментарии и файл ТЗ.

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

1. Прочитаны docs/SCOPE.md, AGENTS.md, PROCESS.md целиком.
2. Прочитано тело issue #199 и все 6 комментариев (аналитика, продуктовые вопросы Q1–Q3, решения владельца, хендофф автора ТЗ).
3. Прочитан файл ТЗ целиком (419 строк).
4. Каждая техническая ссылка ТЗ на существующий код проверена по origin/dev (не по слухам автора):
   • все перечисленные символы (_openAlignDialog, optimizePlans, wallBodiesGeometry, floorFootprintGeometry, _runAlignToGrid, _renderAlignDialog, contentFingerprint, resolveOpenCuts, wallIntervals, partitionOpeningHasCompositeRoomWall, physicalBodyParts, spaceModels, NORM_W, GRID_STEP_N, GRID_PITCH, gs.align_none, gs.align_done) найдены git grep в заявленных файлах;
   • прочитан код _openAlignDialog / _runAlignToGrid / _renderAlignDialog (src/houseplan-card.ts:14903-15985) — подтверждает описанный в ТЗ текущий контракт диалога (changed:false → gs.align_none без Apply, changed:true → отчёт + Apply);
   • прочитаны оба реальных вызова wallBodiesGeometry() в продуктовом коде: iso-путь (_isoSource, строка ~5206) бросает Error при null и наличии стен/тел — это ровно тот "structural failure", который ТЗ требует ловить; light-barrier-путь (~15652) деградирует мягко (fallback на сырой контур). Плюс _wallUnionGeometry (~11259) — путь, которым реально рисуется масонри в 2D-виде: при null/пустом union он тоже молча откатывается на paperRoomShapes, то есть именно так пользователь видел "исчезнувшую кладку" в #197;
   • прочитан wallBodiesUnionPath() и floorFootprintGeometry() в src/wall-thickness.ts — подтверждает различение ТЗ §7.3 между null (structural failure) и «успешный пустой результат» (united && !d → не ошибка, просто нет масонри);
   • подтверждён large-house fixture (demo/fixtures/large-house.mjs): FLOOR_COUNT=3, ROOMS_PER_FLOOR=20 → 60 комнат, OPENING_COUNT=100, PARTITION_COUNT=60, COLUMN_COUNT=40 — числа в §10 ТЗ совпадают буквально;
   • проверены мутационные ID в scripts/mutation-gate.mjs — формат (kebab-case, уже есть прецеденты вроде union-failure-kills-space, union-failure-silent) совпадает с предложенными в ТЗ ID.
5. Прочитан docs/CANVAS.md §9.5 («Оптимизировать планы») — контракт диалога, optimizePlans, one-deep snapshot, «отчёт — верхняя граница» совпадают с тем, как ТЗ их описывает.
6. Прочитан docs/TOUCH-SUPPORT.md — safety floor («no data corruption or silent loss of saved plan data») дословно то основание, на которое ссылается ТЗ §1/§14.
7. Прочитан docs/USER-GUIDE.ru.md (разделы про Optimize/толщину стен) — используемая в ТЗ терминология («Общие настройки → Оптимизировать планы», «предпросмотр», «отмена») не изобретена, а взята оттуда.
8. Сверены два ближайших прецедента той же подсистемы для проверки единообразия: docs/specs/223-optimize-coordinate-canonicalization.md и реализация #224 (git show 4a798e3 --stat) — чтобы понять, что в этом диалоге принято фиксировать в ТЗ дословно (RU+EN строки диалога) и что действительно исторически остаётся вне DoD (английский USER-GUIDE.md в #223/#224 не трогался — значит расхождение с ним не считается дефектом и в ТЗ #199 тоже).
9. Проверен формат записи docs/specs/README.md (двухколоночная таблица issue↔ТЗ, без колонки «Статус ТЗ») — соответствует актуальному состоянию PROCESS.md §7.3 п.1.

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

Находки

Medium (в скоупе — чинится в этом же ТЗ)

M1. Английский текст сообщения об отказе и подсказки не зафиксирован дословно — только «эквивалент», что делает AC6 непроверяемым для EN-локали.

• Файл: docs/specs/199-optimize-geometry-preflight.md, §8.1.
• Текущий текст:

  - RU: «Не удалось безопасно проверить геометрию следующих пространств:
    {spaces}{more}.»
  - RU hint: «Планы не изменены. Обновите House Plan и повторите. Если ошибка
    останется, приложите экспорт пространства к отчёту об ошибке.»
  - EN: equivalent plain-language text without implementation terms.
  

  Для двух главных предложений диалога EN-строка не приведена вообще — только директива «эквивалентный текст». При этом в том же §8.1 для меньших подстрок (fallback-имя Space N, суффикс and N more) EN дан дословно — несогласованность внутри одного раздела.
• Почему это находка, а не техническая деталь: это пользовательский текст нового диалогового состояния, то есть ровно то, что PROCESS.md §7.1 требует фиксировать в ТЗ, а не отдавать на изобретение при реализации («Владельцу задаются только продуктовые вопросы» не означает, что английскую копию придумывает реализатор без утверждённого текста — второй язык тоже наблюдаем пользователем).
• Прецедент того же диалога: docs/specs/223-optimize-coordinate-canonicalization.md §7 добавляет новую строку в тот же Align-диалог и даёт пару целиком:

  - RU: «обновлено пространств: {c}; устранён шум координат: {p}»;
  - EN: «spaces updated: {c}; noisy coordinate values removed: {p}».
  

  #199 — прямое продолжение той же серии задач (#197/#198/#223/#224/#229) над тем же диалогом; стандарт "RU+EN дословно" в ней уже установлен и не должен тихо ослабляться для более заметного по важности сообщения (блокирующий отказ, а не информационная строка).
• Как воспроизвести проверку: открыть §8.1 ТЗ, попытаться написать unit-тест на AC6 («i18n/UI unit») для английской локали — не из чего писать assertion на конкретную строку, только на «что-то не техническое».
• Фикс: дописать в §8.1 дословный EN-эквивалент RU-сообщения и RU-hint (по образцу уже данных в том же разделе пар "Space N"/"and N more").
• Серьёзность: Medium, в скоупе задачи. High-находок нет, поэтому цикл жёлтый, правка — в этом же ТЗ, без нового issue (#202).

Low (снимается без действия, для протокола)

• Хендофф-комментарий автора ТЗ в issue содержит артефакт шаблона: «Коммит: $sha.» — переменная не подставлена. Это дефект комментария, не ТЗ; на содержание, полноту и проверяемость документа docs/specs/199-*.md не влияет. Не блокирует, отмечаю для протокола; ревьюер не правит issue-комментарии.

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

• Продуктовая рамка (§1–§2). Персона (домашний администратор), поверхность («Общие настройки → Оптимизировать планы») и момент названы; предложение «до/после» дано без терминов реализации. Явно назван J6 из SCOPE.md и safety floor TOUCH-SUPPORT.md — оба подтверждены чтением исходников этих документов, ссылка не декоративна.
• Проблема подтверждена по коду, а не заявлена. Пять шагов §3 (preview → candidate → Apply → backend без polyclip-проверки) построчно совпадают с реальным _openAlignDialog/_runAlignToGrid в src/houseplan-card.ts; в частности, реальный fallback _wallUnionGeometry → paperRoomShapes при null/пустом union — это ровно механизм "молча исчезнувшая кладка" из #197, на который ссылается ТЗ.
• Различение null (structural failure) и «успешный пустой результат» (§7.3) — не абстракция, а точное описание существующего поведения wallBodiesUnionPath()/floorFootprintGeometry(): первое — жёсткая ошибка (iso-путь её бросает исключением), второе — легитимный «пустая комната без кладки» результат, который renderer рисует как обычные комнаты. AC2/AC3 формулируют именно эту границу, и она проверяема.
• Продуктовые решения владельца (Q1–Q3) перенесены в контракт без искажения: whole-plan block при любом failure (§7.1, AC4), блокировка уже деградированного пространства без исключения «не стало хуже» (§4 п.2, AC5), сообщение с именами пространств без технических деталей и без кнопки Apply (§8.1, AC6) — всё совпадает с текстом решений владельца в issue.
• Non-scope (§6) явно исключает ремонт найденной геометрии, частичный Apply, смену geometry engine, миграцию схемы, изменение времени жизни Undo — снимает риск расползания скоупа, который прямо запрещён PROCESS.md §12.
• Performance-бюджет (§10) — не оценка на глаз. Числа fixture (3 пространства/60 комнат/100 проёмов/60 partitions/40 columns) и базовое измерение (median 155.9 ms / p95 162.56 ms / max 163.67 ms) сверены с demo/fixtures/large-house.mjs и являются реальным замером автора, а не придуманным ориентиром; относительный бюджет (20%+15ms поверх прямого builder) корректно отделяет overhead preflight-обвязки от уже дорогого polyclip-прохода.
• Backend/atomicity (§9) не добавляет новый параметр endpoint и не требует второй реализации polyclip на Python — согласуется с Non-scope и с описанным в CANVAS.md §9.5 контрактом одной атомарной транзакции.
• AC1–AC14 — каждый пронумерован, однозначен и указывает способ доказательства (unit/smoke/golden/mutation/benchmark/code review), что требуется §2.5 DoR.
• Блок §16 «Принятые технические предположения» корректно отделяет ненаблюдаемые пользователем решения (имена модулей, fingerprint-механизм, отсутствие preflight_passed в backend) от продуктового контракта и явно помечен как «ревьюер может оспорить» — соответствует PROCESS.md §7.1.
• Формальная структура ТЗ покрывает все обязательные разделы §7.1 (сценарий · что видит человек · проблема · скоуп/не-скоуп · контракт · UX · данные/миграция · i18n · AC с доказательством · план тестов · риски · откат · release-артефакты); запись docs/specs/README.md обновлена в формате, актуальном после чистки колонки «Статус ТЗ».
• Rollback (§15) — простой revert реализационного коммита, персистентные данные не меняются новым preflight, что верно логически (preflight ничего не пишет и не канонизирует сверх уже полученного Optimize-кандидата, §7.3).

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

• Не проверялся сам будущий код реализации — его ещё нет, ревью только ТЗ.
• Не запускались typecheck/test/build — на этапе ревью ТЗ продукт не меняется, гейты неприменимы.
• Не оценивалась реальная производительность на CI-машине (замер в ТЗ — замер автора на его Windows-чекауте); согласно ТЗ §10 это будущая забота code-review при нестабильности абсолютного бюджета в CI.
• Не проверялись мутационные тесты scripts/mutation-gate.mjs предметно (их ещё нет для #199) — сверен только формат ID с существующими записями.
• Не исследовался docs/CONFIG-COMPATIBILITY.md построчно — ТЗ прямо заявляет «без изменений и миграции», и этот пункт не оспаривается: он логически следует из того, что preflight — чистая read-only проверка существующего candidate, ничего не пишущая в schema.

Итог

Единственная находка — Medium, в скоупе задачи, чинится правкой текста ТЗ (добавить дословный EN-текст в §8.1), без нового issue (#202). High-находок нет. Технические предположения корректны и проверены по коду origin/dev предметно, а не приняты на слово автора.

Вердикт: жёлтый · заход r1 · блокирующих циклов 1/4 · High: 0 · Medium: 1 → в задаче