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

# SPEC-REVIEW-329-r1

Issue: #329 · Этап: spec (S4-spec-review) · Заход: r1 · Трек: обычный
ТЗ: `docs/specs/329-junction-limits.md`, коммит `8dce8453975121a89263d44243e49059f7000da7`
(докоммит: `docs: spec #329 — wall junction limits and an honest sharp apex`, только
класс C — `docs/specs/**`, продуктовый код не тронут).

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

Изменение — новый файл ТЗ на 151 строку, без сопутствующих правок кода. Задача
не помечена `small`/`trivial`, поэтому полноценный файл ТЗ обязателен —
формально верно. Ревью охватывает весь документ целиком (заход первый,
дельта = документ полностью).

Продуктовая рамка (`docs/SCOPE.md`): задача — правка визуального дефекта
масонри (некорректный рендер стыка стен) плюс новый барьер на запись
геометрии. Это не новая функция, а восстановление корректности существующей
геометрической модели (примыкает к J6 «keep the plan true» и общей
целостности рендера стен, на которой держатся J1/J5/J7). Конфликта со SCOPE
не вижу, владелец решение принял явно в чате issue.

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

- Прочитаны `docs/SCOPE.md`, `PROCESS.md` (весь, включая §2.4, §2.10, §7.1),
  `AGENTS.md`.
- Прочитано тело issue #329 и оба комментария владельца (`gh issue view 329
  --comments`) — сверены пять нормативных ограничений П1–П5 из ТЗ дословно с
  решением владельца в чате: совпадают без искажений.
- Прочитан канонический `docs/WALL-THICKNESS.md` целиком, включая разделы про
  #309 (visual mitre limit / chamfer) и #310 (pair apex / butt-end trim), на
  которые ссылается §4 ТЗ — ссылки корректны, терминология («мitre»,
  «биссектриса», «внутренние грани») не расходится с каноном.
- Прочитан `docs/USER-GUIDE.ru.md`: раздел «Инструменты плана», таблица
  Resize, раздел про геометрическую проверку/диагностику при Optimize — искал
  установленную терминологию для UX отказа записи (см. находку M1).
- Проверено `git show --stat` на коммит ТЗ: тронут только
  `docs/specs/329-junction-limits.md`, продуктовый код и гейты не задеты —
  прогон `typecheck`/`test`/`build` для чисто документационного коммита класса
  C не требуется (PROCESS.md §1 таблица классов, §8 — гейты код-ревью), не
  прогонял.
- Grep по `custom_components/houseplan/validation.py` — подтверждён
  прецедент семантической дельта-валидации (`invalid_partition_opening_jamb_margin`),
  на который ссылается §5 ТЗ: ссылка не выдумана, паттерн существует.
- Grep по `src/grid-scale.ts`, `src/plan-optimizer.ts` — подтверждено, что
  `cell_cm` — реальный настраиваемый параметр (диапазон 0.1–1000 см, по
  умолчанию 5 см), не константа — относится к находке L1.

## Находки

### M1 (Medium, в скоупе) — UX отказа записи заявлен как факт, а не как решение, и не согласован с уже существующим поведением Resize

`docs/specs/329-junction-limits.md`, §2 (нормативные ограничения, преамбула):
«Нарушение = отказ всей записи, план не изменён, **тост** называет конкретное
правило.» §3 распространяет это на все пять поверхностей записи: рисование и
завершение контура, черновики, независимые стены/перегородки, **Resize**,
инструмент **«Толщина»**, merge/split.

Это утверждение о видимом поведении — то есть продуктовый факт, а не
техническая деталь. Но `docs/USER-GUIDE.ru.md` уже фиксирует для Resize
контракт отказа, который тостом не является:

- строка 482: «Боковая стена перестала бы быть общей... → **ручка
  объясняет**: «Нельзя сдвинуть только часть общей стены»»;
- строка 483: «Общая граница частичная... → **ручка остаётся видимой, но
  приглушена; наведение, фокус или нажатие объясняет запрет**»;
- строка 492–493: «Неоднозначный результат **отклоняется целиком**...» — без
  упоминания тоста;
- для пакетной геометрической проверки Optimize (строка 1438) отказ
  оформлен отдельным **диалогом** с «Скопировать диагностику», тоже не
  тостом.

Т.е. в продукте уже как минимум два разных established UI-паттерна отказа
структурной записи (приглушённая ручка с текстом на фокус/hover — для
Resize; диалог с диагностикой — для пакетной геометрической проверки), и ни
один не является тостом. ТЗ утверждает единый тост для всех пяти
поверхностей, не упоминая эти прецеденты и не помечая выбор как
предположение в §9. AC7 (Resize/«Толщина») тоже не называет способ обратной
связи — только «отказ fail-closed, план байт-неизменен», что расходится с
общей формулировкой §2.

Это ровно тот класс дефекта, о котором предупреждает процесс: «утверждение о
поведении, которого нет ни в одном документе и которое не помечено как
предположение». Здесь оно к тому же противоречит документированному
поведению Resize.

**Чем это грозит.** Реализация по букве §2 добавит тост поверх уже
существующей ручки-объяснения на Resize — пользователь увидит два
одновременных, возможно противоречащих, сообщения об одном и том же отказе,
либо автор в процессе кодирования тихо перепишет UX Resize под тост, что
является расширением скоупа (смена established UX-контракта отдельного
инструмента) без отдельного продуктового решения.

**Что нужно сделать.** Явно расписать, какой канал обратной связи
используется на КАЖДОЙ из пяти поверхностей (§3), сверяясь с уже
задокументированным поведением каждого инструмента: тост уместен там, где
сегодня нет собственного канала (рисование/завершение контура, черновики,
merge/split), а для Resize — либо переиспользовать существующий
приглушённая-ручка-и-объяснение канал (без тоста), либо явно зафиксировать
как новое продуктовое решение и передать вопрос владельцу по правилам §7.1
(«что человек видит», с предлагаемым вариантом по умолчанию).

### M2 (Medium, в скоупе) — AC5 описывает два разных теста одной фразой и непроверяем в текущей формулировке

`docs/specs/329-junction-limits.md`, §8, AC5:
> «Повторение «шпиля» из фикстуры issue рисованием — отказ по просвету (даже
> если каждый угол ≥ 15°, но толщины съедают комнату).»

Фикстура issue (`houseplan-space-test2-2026-08-27_16-14-48.json`, комната
`rmtbq3k5e-0`) имеет вершину ≈9.9° — она нарушает П1 (угол < 15°) сама по
себе. Отказ по этой фикстуре AC1 уже проверяет (угол). Формулировка AC5
одновременно (а) ссылается на эту же фикстуру и (б) оговаривает «даже если
каждый угол ≥ 15°» — то есть описывает СОВЕРШЕННО ДРУГУЮ геометрию (все углы
проходят П1, но толщины стен всё равно съедают просвет комнаты ниже 25 см²).
Это два разных теста, слитых в один AC, и как единое проверяемое утверждение
он не воспроизводим: не названо, каким конкретно углам/длинам/толщинам
соответствует случай «угол ≥15°, но просвет < 25 см²» — то есть ровно то
несогласованное место, где догадка выдаётся за факт, если разработчик сам
подберёт числа.

**Что нужно сделать.** Разделить на AC5a (повтор фикстуры issue — отказ,
допустимо по любому из П1/П5, тест уже частично покрыт AC1) и AC5b —
отдельная синтетическая геометрия с конкретными числами (углы, длины,
толщины), где все углы ≥15° проходят П1, но просвет всё равно < 25 см², и
именно она доказывает независимость П5 от П1.

### L1 (Low) — параллель «5 см = 1 клетка» вводит в заблуждение при нестандартном `cell_cm`

`docs/specs/329-junction-limits.md`, §2, П4 и П5: «не ближе **5 см** (1
клетка)» и «≥ **25 см²** (1 клетка 5×5)». `cell_cm` — реальный настраиваемый
параметр пространства (0.1–1000 см, `src/grid-scale.ts`,
`src/plan-optimizer.ts`), а не константа. Числа П4/П5 читаются как абсолютные
сантиметровые пороги (не масштабируются с `cell_cm`) — это, видимо, и есть
решение владельца (в его формулировке те же 5 см/25 см² даны как абсолютные
величины, «клетка» — только пояснение при дефолтной сетке). Но
параллель «(1 клетка)» рядом с абсолютным числом может подтолкнуть
реализацию к ошибочному масштабированию порога на `cell_cm` пространства,
отличном от 5 см. Снимается редакционно: убрать скобку «(1 клетка...)» из
нормативного текста П4/П5 либо явно дописать «абсолютная величина, не
зависит от `cell_cm` пространства». Не блокирует — правится или снимается
решением ревьюера; фиксирую как Low, автор может снять с той же
формулировкой.

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

- Пять численных ограничений П1–П5 в ТЗ дословно совпадают с решением
  владельца в чате issue — искажений или добавленных «от себя» цифр нет.
- Граница применения (§3): проверки только на записи, изменяющей
  геометрию; легаси/импорт/восстановление/миграция не блокируются;
  Optimize не обязан чинить легаси, но не должен создавать новых нарушений —
  сформулировано как явный пост-условный AC (AC10), проверяемо.
- §4 (рендер легаси-острия) корректно опирается на существующий канон:
  #309 (visual mitre limit / chamfer) и #310 (pair apex, «нода из ровно двух
  лучей») в `docs/WALL-THICKNESS.md` действительно описывают именно тот
  механизм, который вырождается в «трезубец» при полном перекрытии тел —
  ссылки точны, не выдуманы.
- Геометрический контракт фаски §4 явно и корректно продублирован в §9 как
  «принято предположительно, поменять свободно» — не выдаётся за
  окончательное решение, ревьюер вправе оспорить: не оспариваю, реализация
  разумна.
- §5 (бэкенд): ссылка на существующий паттерн семантической
  дельта-валидации (`invalid_partition_opening_jamb_margin` в
  `custom_components/houseplan/validation.py`) подтверждена чтением кода —
  прецедент реален, а не придуман для ТЗ.
- Обязательные разделы §7.1 присутствуют по содержанию (сценарий, что видит
  пользователь, проблема, скоуп/не-скоуп — слиты в §1/§3, но содержательно
  покрыты, контракт поведения §2/§4, модель данных/миграция §3/§6, i18n §6,
  AC1–AC10 с указанием способа доказательства, план автотестов §6, риски
  §10, откат §11, release-артефакты §6). Формальных пропусков разделов нет.
- Новых полей конфига нет, `config-field-registry` не трогается — заявлено
  явно (§6), согласуется с `docs/CONFIG-COMPATIBILITY.md` (миграция/импорт
  легаси не блокируются, что и требует этот документ).
- AC1–AC4, AC6–AC10 однозначны, у каждого названы конкретные граничные числа
  и способ доказательства (unit/smoke/golden/backend), тест умеет
  различать pass/fail на границе — реализуемо без дополнительных догадок.
- Открытых догадок, выданных за факт технических решений, не найдено за
  пределами M1 (продуктовый вопрос UX) — все технические допущения явно
  оформлены в §9 «принято предположительно».
- Артефакт корректного класса: файл `docs/specs/329-junction-limits.md`,
  имя соответствует `<NN>-<slug>.md`, задача не `small`, полноценный файл
  обязателен и присутствует.

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

- Код не менялся в этом коммите (только `docs/specs/**`, класс C) — гейты
  `typecheck`/`test`/`build`/`check-docs`/инварианты модели не прогонял: они
  не относятся к чисто документационной правке на этапе spec-review и
  прогоняются на этапе код-ревью.
- Не проверял, как именно физтела считаются в кэше для П5 (реализация ещё не
  существует) — это заявлено как assumed в §9, оценка технической реализации
  относится к код-ревью.
- Не проверял golden-матрицу на предмет «нет вершин острее 15°» — ТЗ само
  требует подтвердить это прогоном на этапе реализации (§6), это не задача
  spec-ревью.
- Не запрашивал у владельца дополнительных продуктовых уточнений — вопрос
  M1 возвращается автору ТЗ как находка, а не выносится владельцу напрямую
  (по регламенту дуб. технических/продуктовых вопросов на этапе ревью решает
  ревьюер вплоть до исчерпания лимита циклов).

## Вердикт

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