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

# SPEC-REVIEW-271-r1

Issue: #271 — «Degree-3 узел достраивает короткий луч до 8×H и рисует несуществующую стену и тень»
Этап: spec (PROCESS.md §2.4)
Заход: r1 · блокирующих циклов израсходовано 0 из 4
ТЗ: `docs/specs/271-finite-multiwall-rays.md`, SHA `482b2be512b38cadb40855b79b710f6602d5eb54`

## Скоуп разбора

Первый заход — разбор полный. Проверено: `docs/SCOPE.md`, `AGENTS.md`, `PROCESS.md`
(включая §2.4, §7.1, §4), тело issue #271 и оба комментария (аналитика +
«ТЗ готово к ревью»), канонический `docs/WALL-THICKNESS.md`, сам ТЗ, исходный код
`src/wall-thickness.ts` (интерфейс `MultiWallNodeRay`, `buildMultiWallNodeMap`,
`bevelMultiWallBody`, константы `MITRE_LIMIT`, `MULTI_WALL_JOIN_LIMIT`), связанные
issue #249/#261/#270/#272/#273 (заголовки и статусы — все закрыты либо остаются
открытыми отдельными задачами, ни одна не дублирует #271).

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

1. Сверил числа из таблицы issue/ТЗ (реальная длина луча vs. текущий rebuild) с
   формулой в коде: `radius = MITRE_LIMIT * node.halfDepth + eps*2`,
   `extent = radius * 2` (`src/wall-thickness.ts:2032-2033`) — при `MITRE_LIMIT=4`
   это ровно `8×halfDepth`. Пример узла 2 `(2404.167, 1245.833)`: `H=62.5` →
   `8×62.5=500.000`, совпадает с «Текущий rebuild» в таблице ТЗ. Формула и цифры
   не выдуманы, а прослеживаются до реального кода.
2. Проверил, что `MultiWallNodeRay` (`src/wall-thickness.ts:51-54`) действительно
   хранит только `{u, halfDepth}` без длины — корневая причина, заявленная в §3
   ТЗ, подтверждена чтением, не только цитированием issue.
3. Сверил каждый обязательный раздел ТЗ с перечнем PROCESS.md §7.1: сценарий,
   что человек увидит, проблема, скоуп/не-скоуп, контракт, UX, модель
   данных/миграция, i18n, AC1…ACn с доказательством, план автотестов, риски,
   откат, release-артефакты — присутствуют все.
4. Прочитал все девять AC на однозначность и способ доказательства; для каждого
   проверил, что критерий формулирует наблюдаемое условие (геометрия/присутствие
   material), а не расплывчатое «стало лучше».
5. Проверил список «не входит» (§5) против реально открытых соседних issue
   (#272 — белые треугольные дыры вне probe #261; #273 — sub-grid островок при
   Optimize) — границы скоупа корректны, чужого не захватывают.
6. Проверил путь ТЗ (`docs/specs/271-finite-multiwall-rays.md`) — issue не
   помечен `small`, файл обязателен и создан по имени `<NN>-<slug>.md`, что
   соответствует правилу.
7. Проверил, что упомянутые файлы существуют: `test/wall-thickness.test.mjs`,
   `docs/ARCHITECTURE.md`, `docs/TESTING.md`, `docs/CONFIG-COMPATIBILITY.md` —
   все на месте, ссылки не битые.

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

## Находки

Нет. Ни одной High или Medium находки — ни в скоупе, ни вне его.

Разобрано отдельно и отклонено как находка:
- **Полнота списка документации (§9).** ТЗ включает `docs/USER-GUIDE.md` /
  `docs/USER-GUIDE.ru.md` в список документов на обновление, хотя пользователю
  не добавляется ни один новый видимый термин или контрол. Это не дефект: раз
  видимая геометрия меняется (`User-Visible: yes` в §10), а требование
  AGENTS.md — обновлять UI-терминологию из USER-GUIDE при изменении видимого
  поведения — включение файла в список консервативно и не создаёт риска;
  решение оставить формулировку в тексте или сократить список — на усмотрение
  автора при реализации, Low, не фиксирую отдельно.
- **Отсутствие имени конкретного нового smoke-файла в AC4/AC5.** Смок ещё не
  существует (создаётся в реализации), поэтому называть файл в ТЗ не требуется —
  PROCESS.md §7.1/2.5 просит указать *категорию* доказательства (`smoke`), а не
  имя ещё не написанного файла. Не находка.

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

- **Корневая причина** (§3 ТЗ) совпадает с кодом посимвольно: `MultiWallNodeRay`
  теряет длину, `bevelMultiWallBody` перестраивает луч на `8×H`. Не догадка —
  прослежено до строк кода.
- **Сценарий и персона** (§1): администратор нажимает Optimize → Plan/View,
  видит несуществующую стену/тень — прямая связь с J1 («правдиво показывать
  дом») и J6 (одна геометрия для всех потребителей), обе строки есть в
  `docs/SCOPE.md`.
- **Скоуп/не-скоуп** (§5) явно исключает соседние открытые дефекты (#272 белые
  дыры, #273 sub-grid островок, форма #249 bevel, `MITRE_LIMIT`/
  `MULTI_WALL_JOIN_LIMIT`) — задача не разрастается на смежные баги.
- **Контракт §6** формулирует финитность луча через проверяемые условия:
  локальная полоса существует только на `t ∈ [0, length]`; правило дедупликации
  co-directional дубликатов явно запрещает «перекрыть зазор» присутствием
  соседнего короткого/толстого дубликата (типичная ловушка, которую легко
  упустить) — прямо закрыто текстом контракта.
- **AC1-AC9** — каждый формулирует наблюдаемое состояние геометрии
  (присутствие/отсутствие material в конкретной точке, конкретные числа
  `20.833 → не 500`, `12.5 → не 110`) и называет способ доказательства (unit /
  geometry unit / targeted smoke / golden semantic probe / mutation). AC7
  отдельно требует, чтобы мутант **уронил** AC2 или AC4 — то есть тест на
  фальсифицируемость заложен в само ТЗ, а не оставлен на усмотрение код-ревью.
- **Технические предположения (§13)** помечены явно как «assumed, change
  freely» и действительно являются техническими (внутреннее представление
  finite support), а не спрятанным продуктовым решением. Предположение про
  `wall_columns` унаследовано от собственного анализа владельца в комментарии
  аналитики, а не изобретено автором ТЗ.
- **Совместимость/UX/perf/touch** (§7): персистентная модель не меняется,
  миграции нет, новых контролов/i18n/HA-вызовов нет, touch явно назван («новых
  keyboard/touch/focus/ARIA... нет»), perf ограничен явным запретом нового
  глобального `O(E²)` прохода.
- **Откат (§12)** запрещает частичный откат только тестов — учтён урок, из-за
  которого регрессия становится снова невидимой.
- Продуктовых вопросов владельцу нет и не должно быть: единственное решение
  задачи («физическое тело не может продолжаться дальше конца отрезка») уже
  прямо следует из J1 и не требует выбора между персонами или трактовки
  пограничного случая.

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

- Не проверял реализацию (её нет — это стадия spec, код не менялся).
- Не прогонял `typecheck`/`test`/`build`/`check-docs` — не относится к этому
  этапу, диапазон изменений раунда состоит из одного документного коммита.
- Не воспроизводил приватные `1.json`/`2.json` владельца — они не в репозитории
  по правилу «не коммитить пользовательские данные»; проверка ограничилась
  числами, которые ТЗ и issue цитируют, и сверкой формулы в коде.
- Не оценивал, оптимальна ли выбранная будущая технической реализация
  (union конечных spans vs. clipped polygon) — это по §13 оставлено автору
  реализации и будет предметом код-ревью.

## Вердикт

Все обязательные разделы (PROCESS.md §7.1) присутствуют, каждый AC однозначен и
называет способ доказательства, корневая причина подтверждена чтением кода, а
не выдана за факт без опоры. Открытых продуктовых вопросов нет и не должно
быть.

**Зелёный.**