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

# SPEC-REVIEW-288-r1

- **Issue:** https://github.com/Matysh/houseplan-card/issues/288
- **Этап:** spec (PROCESS.md §2.4)
- **Заход:** r1 · блокирующих циклов израсходовано 0 из 4 (правило #227 —
  зелёный вердикт бюджет не тратит, но этот вердикт не зелёный)
- **Документ ТЗ:** `docs/specs/288-bounded-multiwall-corridor.md`
- **SHA на момент ревью:** `cb0f9e7351e919701666dfd05b53f0e218e672a5`
  (коммит `docs: specify bounded multiwall corridor`)
- **Первый заход** — раздел «объём по дельте» (§2.10) не применяется, разбор
  полный.

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

Проверено: тело issue #288 и оба комментария (аналитика + «ТЗ готово»),
`docs/specs/288-bounded-multiwall-corridor.md` целиком, `docs/SCOPE.md`,
`docs/WALL-THICKNESS.md` (канонический документ подсистемы), фрагменты
`src/wall-thickness.ts` (константы `MITRE_LIMIT`/`MULTI_WALL_JOIN_LIMIT`,
типы `MultiWallNodeRay`/`MultiWallNodeRaySupport`, функции
`multiWallBevelCutsAt`, `multiWallRayStripGeometry`, `bevelMultiWallBody`),
`demo/smoke_real_plan_masonry.mjs`, `test/fixtures/real-plan-second-floor.json`
(структура), `scripts/model-invariants.mjs` (наличие `--config`), и для
сравнения структуры — специфи́кации `docs/specs/275-multiwall-strip-containment.md`
и `docs/specs/278-wall-union-isolation.md` (та же подсистема, сопоставимый
риск/сложность — использованы как прецедент требуемых разделов).

Как проверялось: ревью текстовое — сверка формулировок ТЗ с телом issue
(числа/причина совпадают буквально), с идентификаторами в реальном коде
(`MITRE_LIMIT`, `node.halfDepth`, `MultiWallNodeRay.supports` — все существуют
и используются именно так, как описывает контракт §3.1), с формулировками
`docs/WALL-THICKNESS.md` (ссылки на #249/#261/#271/#272/#275/#278/#279 в AC4
и в тексте документа совпадают с уже задокументированным поведением, не
изобретены), и структурное — сверка присутствия обязательных разделов §7.1
с прецедентными спеками той же подсистемы. Продуктового кода в диапазоне нет
(diff ограничен `docs/specs/**`, класс C) — гейты §8 к этапу spec не относятся
и не запускались; это гейты этапа code (§2.7).

## Находки

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

**M1. Отсутствуют обязательные разделы «Риски» и «Откат» (§7.1, DoR §2.5).**

`docs/specs/288-bounded-multiwall-corridor.md` не содержит ни одного раздела
с анализом рисков, ни раздела откат/rollback. Единственное упоминание слова
«риск» — оценочная цифра в шапке (`риск 8/10`), без содержания. Проверено
`grep -n -i "риск\|rollback\|откат"` по всему файлу — единственное совпадение
строка 7.

PROCESS.md §7.1 перечисляет обязательные разделы ТЗ явно: «…план автотестов ·
риски · откат · release-артефакты» — оба отсутствующих раздела в списке есть.
DoR §2.5 повторяет то же как отдельные обязательные пункты очереди: «влияние
на производительность… названо», «**откат**: как выключить или вернуть
назад», «риски перечислены». Пока эти пункты не выполнены, статус не может
стать «Готово к разработке» буквально по тексту §2.5: «Если хоть один пункт
не выполнен — статус не «Готово к разработке», как бы ни хотелось начать».

Это не абстрактная формальность именно для данной задачи: сам автор оценил
риск как 8/10 и сложность 7/10 (P1, обычный трек — не `small`), а фикс трогает
общий для всех T/L/multi-wall стыков код (`bevelMultiWallBody`,
`multiWallBevelCutsAt`), от которого зависят уже закрытые контракты #249,
#261, #271, #272, #275, #278, #279 — то есть реальный риск регрессии высок и
уже отражён самим объёмом AC4, но нигде не назван явно как риск с мерой
(«риск: регрессия одного из семи прежних контрактов → мера: AC4 перегоняет
весь их набор»). Откат для правки без миграции и без флага — скорее всего
«просто revert коммита», но это должно быть сказано, а не подразумеваться:
раздел 6 («Совместимость…») описывает только *отсутствие* новых
compatibility-полей, а не механику отката самой правки.

Прецедент: спеки той же подсистемы и сопоставимого риска — `#275`
(`docs/specs/275-multiwall-strip-containment.md`, разделы «11. Риски и меры» и
«12. Rollback») и `#278` (`docs/specs/278-wall-union-isolation.md`, разделы
«12.1. Риски и меры» и «17. Release-артефакты и rollback») — оба раздела
присутствуют. #288 того же класса дефекта и не легче ни по одной из этих
двух метрик, но раздела не имеет.

**Чем закрывается:** добавить в ТЗ раздел «Риски и меры» (минимум: риск
регрессии multi-wall контрактов #249/#261/#271/#272/#275/#278/#279 → мера
AC4; риск undershooting/overshooting отсечения у соседней стены → мера AC3 +
AC7 mutation) и раздел «Откат» (одна фраза: чистый revert коммита, миграции и
флага не требуется, поскольку модель данных не меняется). Это не требует
пересмотра геометрического контракта — правка текстовая.

### Low

**L1. «Связано» в шапке не включает #279, хотя AC4 явно на него ссылается.**

Шапка документа (строка 11) перечисляет «#249, #261, #271, #272, #275, #278,
#284–#286», но AC4 (строка 127) прямо требует «near-orthogonal #279 остаётся
защищённым». #279 — тот же класс контрактов, задействован в проверке
регрессии, и разумно ожидать его в списке связанных issue. Не блокирует
проверяемость ни одного AC и не влияет на выполнимость — чисто
трассируемость документа. Решение оставляю на автора: либо дополнить строку
11, либо снять как не влияющее (в этом случае — с записью в документе, а не
молчанием, по требованию §12 «Оставили в тексте ревью не считается
закрытием» — здесь это Low, а не Medium, поэтому достаточно осознанного
снятия).

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

- **Раздел «Сценарий» и диагноз причины (п.1).** Числа `349/120/5` шагов,
  толщины `30/30/30` см, соседняя стена `20` см, радиус
  `MITRE_LIMIT × H = 4 × 15 = 60`, вырез `60 − 15 = 45` — воспроизводят тело
  issue буквально, без искажений и без добавления недоказанных деталей.
  Диагноз в issue помечен владельцем как «Подтверждённая причина» (совпадение
  вычисленной величины с измеренной), так что повторение его в ТЗ как факта —
  не догадка, выданная за решение, а корректное наследование уже
  подтверждённого вывода.
- **Идентификаторы контракта существуют в коде.** `MITRE_LIMIT` (`src/wall-thickness.ts:78`),
  `MultiWallNodeRay.supports`/`halfDepth` (там же, интерфейсы объявления и
  использование в `multiWallRayStripGeometry`/`bevelMultiWallBody`) — контракт
  §3.1 ссылается на реально существующие структуры, а не на вымышленные.
- **AC1/AC2 привязаны к существующему воспроизводимому инструменту.**
  `demo/smoke_real_plan_masonry.mjs` уже в дереве (класс B, коммит
  `c654e0ec`/`d5659478`), считает разрывы по каждому ребру каждой комнаты
  (не только по четырём известным точкам), различает объявленный `open_span`
  от дефекта. Требование AC1 «gapCount: 0, totalGapSteps: 0 плюс обновление
  чисел `PLANS` в том же коммите» и AC2 «first-floor остаётся на нуле» —
  однозначны и проверяются одной командой.
- **AC3 — table-driven unit, синтетическая, но осознанно упрощённая
  конфигурация** (три луча `349/120/5` при `30/30/20` см вместо реальных
  четырёх стен узла) корректна как проверка контракта §3.1 в отрыве от
  конкретной топологии реального плана: контракт формулируется через
  собственный half-depth соседнего ray, а не через воспроизведение точной
  геометрии дома. AC1 остаётся источником истины для реального дефекта,
  AC3 — независимая unit-гарантия того же правила на разных `cell_cm` и
  порядках лучей.
- **AC4** — список регрессионных контрактов (#249 дискардед wedge,
  #261 retained wedge, #271 finite rays, #272 enclosed holes, #275 protected
  strips, #278 union failure isolation, #279 near-orthogonal) совпадает слово
  в слово с формулировками §3 `docs/WALL-THICKNESS.md`, не выдуман.
- **AC7 (мутант)** — явно требует, чтобы порча корридора до зависимости
  только от `MITRE_LIMIT × node.halfDepth` валила AC1 или AC3; это тест на
  «умеет падать», а не декларация покрытия.
- **Раздел 4 «Scope»**, особенно «Не входит» (никакого переписывания
  persisted-данных, никакого изменения глобальных констант, никакой новой
  модели стен из ADR #282) корректно ограничивает скоуп и явно исключает
  соседние задачи #289/#290, не позволяя дефекту раздуться в рефакторинг.
- **Раздел 8 «Порядок интеграции»** относительно ветки `#260`
  (`issue/260-fixture-wall-keys`) корректно и без искажений повторяет
  требование самого issue («влить до пересъёмки скриншотов») и явно
  оговаривает, что #260 не входит в продуктовый скоуп #288 — не является
  попыткой расширить скоуп чужой задачей.
- **«Принятые технические предположения» (п.9)** — все четыре пункта
  действительно технические (верхняя граница ущерба, конкретный алгоритм
  connector-а, объём фикстур, touch-политика), ни один не является
  продуктовым вопросом, который следовало бы адресовать владельцу; блок
  оформлен явно как предположение, что соответствует требованию §7.1
  («принято предположительно, поменять свободно»), а не выдаёт догадку за
  факт.
- **Совместимость/touch/performance (п.6)** — «модель данных не меняется»
  подтверждается отсутствием любых изменений схемы/`layout`/`Optimize` во
  всём документе; touch-формулировка («View на touch и kiosk получает тот же
  canonical result») соответствует терминологии `docs/TOUCH-SUPPORT.md`
  (View — гарантированная поверхность, редактор — best effort), не изобретает
  новый термин.
- **Продуктовых вопросов владельцу нет** — и это корректно: единственная
  видимая пользователем перемена — «стены рисуются без разрыва», без нового
  UX-контракта, без выбора между персонами. Открытых развилок, требующих
  продуктового решения владельца, в тексте не найдено.

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

- Не запускал `npx tsc --noEmit` / `npm test` / `npm run build` /
  `node scripts/check-docs.mjs` — diff ограничен `docs/specs/288-*.md`
  (класс C), продуктовый код и тесты не менялись; эти гейты относятся к
  этапу code-review (§2.7) и будут обязательны там.
- Не выполнял `node demo/smoke_real_plan_masonry.mjs` живьём — на этапе spec
  еще нет реализации; текущий (добавленный ранее, в другом issue) результат
  `gapCount: 4, totalGapSteps: 181` уже зафиксирован в самом smoke-файле и
  подтверждён текстом issue, повторный прогон здесь ничего нового не даёт.
- Не проверял, действительно ли предложенная в AC3 синтетическая
  конфигурация (3 луча, включая «соседнюю» стену как один из лучей) технически
  достаточна для воспроизведения именно того случая, где четвёртая
  (не инцидентная узлу) стена теряет материал — если в реальности дефект
  затрагивает стену, geometрически не входящую в `node.rays` того же узла,
  синтетический repro AC3 может не поймать в точности этот путь кода. Это не
  повод для находки: AC1 (реальный smoke) остаётся источником истины
  независимо от того, что покажет AC3, и авторская реализация обязана
  удовлетворить AC1 в любом случае. Точную топологию дефектного пути стоит
  перепроверить на этапе code-review по фактическому диффу.
- Не проверял golden baseline и её текущее состояние (`artifacts/golden/`) —
  AC6 описывает будущую работу (targeted golden для реального плана ещё не
  существует), нечего сверять до реализации.

## Вердикт

High-находок нет. Одна Medium-находка (M1) — в скоупе задачи, не требует
отдельного issue (#202) и чинится добавлением двух коротких разделов в тот же
файл ТЗ. Одна Low-находка (L1) — на решение автора (дополнить или снять с
записью).

```
Вердикт: жёлтый · заход r1 · блокирующих циклов 0/4 · High: 0 · Medium: 1 → в задаче
Документ: docs/reviews/SPEC-REVIEW-288-r1.md
```