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

# SPEC-REVIEW-304-r1

Issue: #304 «Редактор плана: режим «Толщина» скрывает часть осевых линий и узлов стен»
Этап: spec (лёгкий трек, метка `small`)
Заход: r1 · блокирующих циклов израсходовано 0 из 2 (лимит лёгкого трека — 2)
Ревьюер: Claude (сессия ревью ТЗ), артефакт — комментарий в issue + этот документ (по правилу §5 документ не обязателен, но публикуется для трассируемости).

## Скоуп

ТЗ живёт в теле issue #304 (комментарий владельца от 2026-08-25 подтверждает `small`).
Задача: unify статический слой архитектурных осей/узлов Plan editor (`plan-snap-overlay`)
так, чтобы он не зависел от активного `MarkupTool` — сейчас полный слой рендерится
только для `draw`, а в остальных девяти инструментах его подменяет
`hidden-wall-diagnostic-overlay`, который по контракту показывает только скрытые
перекрывающиеся *независимые* источники (draft/partition), а не полную геометрию
комнат. AC1–AC7, план проверок, риски, откат и release-артефакты присутствуют.

Продуктовая рамка: J6 SCOPE.md — «Keep the plan true as the home evolves», конкретно
«достоверная топология при поддержании плана». Owner-комментарий явно ссылается на J6.
Соответствие подтверждаю: задача не расширяет и не меняет ни один Core user job,
чинит расхождение представления внутри уже принятого поведения инструмента «Стены».

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

Ревью ТЗ выполнялось не на веру автору, а с чтением текущего кода — задача описывает
конкретный технический механизм бага, и его нужно было заземлить, а не принять как
заявление:

1. `docs/SCOPE.md`, `AGENTS.md`, `PROCESS.md` §2.4/§2.10/§5/§7.1/§7.2/§12 — рамка процесса
   и лёгкого трека.
2. Тело issue #304 и оба комментария владельца (аналитика + передача на ревью).
3. `docs/USER-GUIDE.ru.md:373-379` — подтверждает, что текущая документация уже
   фиксирует осевые линии как поведение именно инструмента «Стены»; после фикса это
   предложение придётся расширить на все инструменты Plan editor, что ТЗ и заявляет
   в Release-артефактах.
4. `src/houseplan-card.ts`:
   - `588` — `type MarkupTool = 'select' | 'draw' | 'column' | 'merge' | 'split' |
     'resize' | 'opening' | 'boundary' | 'wallthick' | 'delroom'` — ровно десять
     значений, как в AC2, не выдумка;
   - `1524-1526` — `get _markup(): boolean { return this._mode === 'plan'; }` — статический
     слой физически не может просочиться в View/Device/Backdrop-editor, потому что все
     точки рендера overlay обёрнуты в `this._markup ? … : nothing`; AC5 — не гипотеза, а
     прямое следствие текущей структуры кода;
   - `17565` `_renderWallBodies`, `17572-17573` `_renderHiddenWallDiagnosticOverlay`
     (без условия на `_tool`, то есть рендерится во всех markup-инструментах),
     `17578-17579` `${this._markup && this._tool === 'draw' ? … this._renderPlanSnapOverlay()
     … : nothing}` — это буквальное подтверждение корневой причины из issue: полный
     `plan-snap-overlay` гейтится на `draw`, diagnostic-слой остаётся один во всех
     остальных.
5. `src/plan-snap-overlay.ts`:
   - `166-215` `buildHiddenWallDiagnosticGeometry` — `hidden = sources.filter(source =>
     source.kind !== 'room' && sources.some(other => other !== source &&
     positiveCollinearOverlap(...)))` — буквально подтверждает контракт «показывает
     только скрытые перекрывающиеся независимые источники», room-only рёбра без партнёра
     по перекрытию никогда сюда не попадают. Это и есть причина «части осей нет в
     Толщина» — не домысел автора ТЗ, а прочитанный код;
   - `228` `buildPlanSnapGeometry` — существующая каноническая геометрия, которую фикс
     предлагает переиспользовать для статического слоя во всех инструментах (contract p.3);
6. `demo/smoke_plan_snap_overlay.mjs:236-239` — `result.otherPlanToolsHaveHiddenDiagnostic =
   !overlay() && !!diagnostic && …` — буквально закрепляет `!overlay()` (полного слоя нет)
   для инструмента `select` как ожидаемое поведение. Это подтверждает заявление issue
   «smoke сейчас закрепляет это расхождение вместо проверки межинструментального
   инварианта» — не голословно, а строкой теста.
7. `demo/golden/matrix.mjs`, `demo/golden/harness.mjs` — существуют, ссылка в скоупе ТЗ
   не на вымышленную инфраструктуру.
8. `docs/TOUCH-SUPPORT.md` — grep по overlay/snap не дал контрактных ограничений на этот
   слой; заявление «touch-контракт не расширяется» не противоречит канону (слой был и
   остаётся `pointer-events: none`, десктоп-first редактор не меняется).
9. `docs/WALL-THICKNESS.md`, `docs/CANVAS.md`, `docs/UX-MODES.md` — grep по overlay/wallthick
   не нашёл предписаний, которым ТЗ противоречило бы.

## Находки

Нет находок уровня High или Medium. Задача полностью укладывается в лёгкий трек:
сложность/риск, заявленные владельцем (3/10 и 3/10), подтверждаются техническим
разбором — правка изолирована в рендер-гейтинге одного файла плюс возможное
разделение геометрии в `plan-snap-overlay.ts`, без миграции, новых i18n-ключей,
нового UX-контракта (видимое поведение просто перестаёт зависеть от инструмента —
это и есть заявленный "после") и без touch-влияния.

Low, не блокирует, не требует правки:
- AC1 фиксирует магическое число «шесть узлов» для контрольного участка. Это не
  домысел: число заземлено в приложенных к issue скриншотах (`2026-08-25_15-46-52.png`
  — полный вид «Стены») и будет закреплено unit-фикстурой на этапе реализации (план
  проверок, п.1). Претензий к формулировке нет, отмечаю для полноты «чего не проверял».

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

- Обязательные разделы §7.1 (для лёгкого трека — §5: проблема, контракт, AC1…ACn с
  доказательством, откат) присутствуют, ТЗ фактически даёт больше, чем требует лёгкий
  трек (сценарий, эдж-кейсы, риски, release-артефакты).
- Каждый AC (1–7) однозначен, имеет способ доказательства (`unit`/`smoke`/`golden`/
  «ревью кода») и указывает конкретный наблюдаемый инвариант, а не реализацию.
- Корневая причина бага, названная в issue, дословно подтверждается кодом — это не
  «догадка, выданная за решение»: технический механизм проверен построчно (см. выше).
- Контракт поведения (пп.1–7) полон: перечисляет все 10 инструментов, явно разделяет
  статическую топологию и transient-состояния инструмента «Стены», фиксирует
  presentation-only и `pointer-events: none`, границы режимов (View/Device/Backdrop) и
  отсутствие промежуточного пустого кадра при переключении.
- Скоуп/не-скоуп корректно исключают алгоритмы привязки/записи толщины и построения
  стен — фикс ограничен представлением, не моделью.
- Совместимость, миграция, i18n, touch, performance разобраны и обоснованы отсутствием
  влияния, а не пропущены молчанием.
- Риски (двойная отрисовка, порядок рендера, случайная утечка transient-маркеров,
  инвалидация кэша на pointermove) названы предметно и совпадают с зонами, которые я
  сам выявил бы при чтении кода рендер-конвейера — заявка не занижает риск.
- Откат тривиален и реалистичен (revert рендер-гейтинга, схема/данные не меняются).
- Owner-аналитика подтверждает соответствие job J6, дубликаты проверены и отклонены
  предметно (#232 — про другое: hover при рисовании).

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

- Не проверял на глаз итоговое число узлов/сегментов для контрольной fixture построчным
  выполнением `buildPlanSnapGeometry`/`buildHiddenWallDiagnosticGeometry` — это задача
  unit-теста на этапе реализации, а не спецификации; на этапе ТЗ важно было убедиться,
  что функции и семантика существуют и соответствуют описанному контракту, что сделано.
- Не запускал `npm test`/`npm run build`/`typecheck` — на этапе ревью ТЗ гейты кода не
  прогоняются (нечего собирать, код не менялся), это относится к этапу код-ревью (§2.7).
- Не проверял golden/смоук-набор целиком — задача их ещё не создала (в скоупе только
  план их появления), это тоже предмет код-ревью.
- Не оценивал реальный экспорт `houseplan-space-convergence-test-...json`, приложенный к
  issue (файл не запрашивался и не был нужен: код уже подтверждает механизм независимо
  от конкретного экспорта).

## Вердикт

Зелёный. ТЗ проверяемо, однозначно, технически заземлено чтением кода, укладывается в
лёгкий трек и закрывает продуктовую строку J6. High/Medium-находок нет.