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

# SPEC-REVIEW-309-r1

Issue: https://github.com/Matysh/houseplan-card/issues/309 «Стыковочные узлы: визуальный лимит mitre и устранение паразитных парных патчей»
Этап: spec (обычный трек — сложность/риск владельца 6/10 и 7/10, `small` невозможен)
Заход: r1 · блокирующих циклов израсходовано 0 из 4
Ревьюер: Claude (сессия ревью ТЗ), артефакт: `docs/specs/309-junction-visual-limit.md` в ветке `issue/309-junction-visual-limit`, коммит `ff623cd4` (только этот файл; `git diff origin/dev...HEAD --stat` — 1 файл, 72 строки, никакого кода).

## Скоуп

ТЗ описывает три класса визуальных артефактов кладки в узлах стыка стен (шип, горб,
ступенька), обнаруженных владельцем на реальном экспорте после #302 (полный mitre).
Решения владельца зафиксированы 2026-08-25 в аналитике issue: визуальный порог среза
`1.5·max(h)` вместо санитарного `MITRE_LIMIT=4`, форма среза — плоская фаска
перпендикулярно биссектрисе, устранение паразитных mitre-патчей между не-соседними
по азимуту лучами узла. Продуктовая рамка — рендер кладки стен как таковой, то есть
J1 SCOPE.md («show the whole home... spatially», точность отображения) и J6
(«keep the plan true»): задача не расширяет и не меняет job, чинит форму существующей
геометрии, принятой в #302. Соответствие подтверждаю.

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

Не на веру автору — с чтением текущего кода `src/wall-thickness.ts`,
`src/physical-geometry.ts`, `demo/golden/matrix.mjs`, `docs/WALL-THICKNESS.md`,
`docs/specs/README.md`, `PROCESS.md` §2.4/§2.5/§7.1/§7.2, `AGENTS.md`, `docs/SCOPE.md`:

1. `src/wall-thickness.ts:80` — `MITRE_LIMIT = 4` существует и является ровно тем
   санитарным пределом, о котором говорит §3.1 ТЗ.
2. `src/wall-thickness.ts:1082-1150` (`linearWallJoinPatches`) — построчно
   подтверждает: (a) функция перебирает **все** пары лучей `i<j` без фильтра
   соседства по азимуту, хотя лучи уже отсортированы по `atan2` (строка ~1125) —
   это буквально подтверждает механизм «ступеньки», описанный автором во втором
   комментарии issue (паразитный патч между не-соседними лучами); (b) строка 1144
   — `limit = MITRE_LIMIT * Math.max(a.halfDepth, b.halfDepth)` — ровно та ветка,
   на которую ссылается аналитика issue как источник «шипа»; контракт §3.2 ТЗ
   правит именно эту ветку.
3. `src/wall-thickness.ts:2087` (веера `junctionNodeGeometry`) — тот же
   `MITRE_LIMIT`-предел на ветке фанов, соответствует ссылке аналитики «:2087» и
   контракту §3.4 ТЗ.
4. Проверил область действия `linearWallJoinPatches` по всем вызовам:
   `src/physical-geometry.ts:242` (канонические draft/partition-тела),
   `src/houseplan-card.ts:19961` (live-превью рисования),
   `src/wall-thickness.ts:1211` внутри `drawWallPreviewD` (превью открытого
   контура). Все три — один и тот же экспорт. Это прямо подтверждает заявление
   §3.5 ТЗ «превью использует ту же парную логику» — не декларация, а следствие
   того, что все три сайта вызывают одну функцию; менять код в одном месте нельзя.
5. `src/wall-thickness.ts:2166` (`junctionContractHoles`) и
   `demo/smoke_junction_holes.mjs` — оба существуют, соответствуют ссылкам §3.5/AC5.
6. `demo/golden/matrix.mjs:577-621` — блок `#302: junction close-ups` содержит
   ровно **15** сцен `junction-*` (посчитано `grep -c`) плюс отдельно
   `junction-owner-repro-dark` (строка 620) = 16 сцен итого, не 16 крупноплановых
   + repro = 17, как можно прочитать в тексте ТЗ (см. Находки, Low).
7. `docs/specs/README.md` — «Обязательные release-артефакты номерного ТЗ»: явный
   перечень (changelog RU+EN, затронутая документация, golden/screenshots и способ
   review) обязателен, если задача меняет пользовательское поведение. Рендер стыков
   — видимое поведение (форма кладки в Plan/View/kiosk/Static/hidden-Iso, общий
   структурный кэш по `docs/WALL-THICKNESS.md` §3), значит раздел обязателен.
8. `PROCESS.md` §7.1 — обязательные разделы ТЗ: сценарий · что человек увидит ·
   проблема · скоуп и не-скоуп · контракт · UX · модель данных и миграция · i18n ·
   AC1…ACn · план автотестов · риски · откат · release-артефакты.
9. `git log -1 --format=%B ff623cd4` — трейлеры `Issue: #309` / `User-Visible: no`
   на месте (документация, код не менялся).

## Находки

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

**Отсутствуют несколько обязательных разделов §7.1, включая оба продуктовых.**

Файл `docs/specs/309-junction-visual-limit.md` содержит: Проблема (§1), Решения
владельца (§2), Контракт (§3), Затрагиваемые поверхности (§4), AC (§5), План
тестов (§6), Откат (§7). Отсутствуют как отдельные разделы:

- **Сценарий** — какая персона, на какой поверхности, в какой момент встретит
  изменение (PROCESS.md §7.1, первый из двух обязательных продуктовых разделов).
  Проблема формулирует технический механизм (mitre, лучи, паразитные патчи), но
  не называет персону/поверхность. Это не мелочь: рендер узлов — общий структурный
  кэш (`docs/WALL-THICKNESS.md` §3: «Full and Static render paths reuse the same
  structural cache»), поэтому фикс проявится не только в Plan editor (где владелец
  заметил дефект), но и в View, kiosk, Static, hidden-Iso — у всех трёх персон
  SCOPE.md, не только у Home admin. Это технический факт, не продуктовый вопрос —
  автор может и должен написать его сам, без обращения к владельцу.
- **Что человек увидит до и после**, одной фразой без терминов реализации (второй
  обязательный продуктовый раздел). Ближайшее к этому — техническое описание в §1
  (шип/горб/ступенька), но это не заменяет требуемую формулировку «до: кладка узла
  выступает зубцом/пикой/уступом за естественный контур; после: кладка узла
  ограничена аккуратной фаской, без выступов».
- **Скоуп и не-скоуп** как явный раздел (сейчас скоуп восстанавливается только из
  §4 «Затрагиваемые поверхности», не-скоуп не сформулирован вовсе — например, не
  сказано explicitly, что #249-шеврон для near-orthogonal узлов (#279) и общая
  политика `thickLength` (#271) не пересматриваются, кроме одной фразы в §3.4).
- **UX** — раздел отсутствует; для чисто рендер-геометрической задачи корректный
  ответ короткий («интерактивных элементов нет, только форма кладки»), но раздел
  должен присутствовать явно, а не подразумеваться.
- **Модель данных и миграция** — не упомянуто явно. Ответ тривиален («нет модели
  данных, нет миграции — чистая рендер-геометрия из уже сохранённых `walls`/
  `partitions`»), но DoR (§2.5) требует явного «нет», а не молчания.
- **i18n** — не упомянуто явно. Ответ тривиален («нет новых строк»), нужен явный
  раздел с этим ответом (DoR §2.5).
- **Риски** — не назван явный раздел (частично риск виден из §3.3 — «решение
  фиксируется при реализации измерением» — но общего перечня рисков нет: например,
  риск того, что после запрета несоседних пар в узлах ≥3 лучей часть существующих
  16 golden-сцен изменится непредсказуемо и потребует пересмотра больше, чем
  ожидается).
- **Release-артефакты** — не выделены как раздел. §4 упоминает
  `docs/WALL-THICKNESS.md §3`, но нет явного перечисления `docs/CHANGELOG.md` +
  `docs/CHANGELOG.ru.md` (обязательны по `docs/specs/README.md`, поскольку меняется
  пользовательское поведение — форма отображаемой кладки) и способа ревью golden
  (`--reviewed`, кто и как принимает изменившиеся сцены).

Все перечисленные пункты решаются самим автором без вопроса владельцу — ни один
не требует продуктового решения, которого ещё нет (персона/поверхность вытекают
из общего рендер-пайплайна, i18n/миграция/UX ответы тривиальны «нет»,
release-артефакты — механическое перечисление). Без High-находок это жёлтый
вердикт: разделы дописываются в этом же файле, следующий заход проверяется по
дельте (§2.10).

### Low (не блокирует, отмечаю для полноты)

- §3.5 и §4 повторяют формулировку «Все 16 junction-сцен» из
  `docs/WALL-THICKNESS.md` («Junction tooling»: «sixteen close-up golden scenes
  (`junction-*`) plus the owner's repro scene»). Фактически в
  `demo/golden/matrix.mjs:580-615` ровно **15** близких-планов `junction-*`
  (посчитано `grep -c`), плюс `junction-owner-repro-dark` — итого 16 сцен, не
  16+1=17. Формулировка ТЗ («Все 16 junction-сцен + junction-owner-repro-dark»)
  наследует ту же неточность канонического документа. Не блокирует ни один AC —
  AC6 («весь сет зелёный») не зависит от точного числа, golden-раннер прогоняет
  фактический список сцен, а не названное количество. Рекомендация: при правке
  раздела не привязываться к числу («весь текущий junction-сет»), либо явно
  посчитать `grep -c "id: 'junction-" demo/golden/matrix.mjs` перед фиксацией
  цифры — это тот же класс дефекта, о котором предупреждает `AGENTS.md`
  («Never copy test counts into documents by hand; they go stale»), просто
  применённый не к тестам, а к golden-сценам. Снимаю без правки по решению
  ревьюера: не влияет на проверяемость ни одного AC.

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

- Обязательные технические разделы §7.1 (проблема, контракт поведения, AC1…7 с
  доказательством, план автотестов, откат) присутствуют и полны.
- Корневые причины всех трёх артефактов не являются догадкой: автор подтвердил
  их исполнением на реальном экспорте (dev @ dc68868) и указал точные строки кода
  (`:80`, `:1144`, `:2087`), которые я перепроверил построчно — они существуют и
  делают ровно то, что написано в issue и в ТЗ.
- Инвариант «превью = персист» (§3.5, п.3) — не заявление, а прямое следствие
  того, что `linearWallJoinPatches` имеет единственный экспорт и три вызывающих
  сайта (`physical-geometry.ts:242`, `houseplan-card.ts:19961`,
  `wall-thickness.ts:1211`); правка одной функции автоматически меняет все три.
- Порог `1.5·max(h)` и граница «прямые/тупые углы не затрагиваются» (AC4)
  математически корректны: для равных толщин под 90° вершина mitre лежит на
  `h·√2 ≈ 1.41h`, что действительно `< 1.5h` — контракт не ломает обычные углы.
- Контракт §3.3 (запрет паразитных пар в узлах ≥3 лучей) технически реализуем на
  существующей структуре: лучи в `linearWallJoinPatches` уже сортируются по
  `atan2` перед перебором пар (строка ~1125), так что «соседние по азимуту»
  проверяется без новой инфраструктуры — просто ограничением диапазона `j`.
- Мутанты AC7 (a)-(d) однозначно целятся в четыре разных пункта контракта
  (порог, форма среза, фильтр соседства, направление фаски) и их легко отличить
  друг от друга — не избыточны и не дублируют друг друга.
- «Без дыр» (#302) и «без фантомов» (#271) named как обязательные инварианты с
  конкретными существующими инструментами (`junctionContractHoles`,
  `smoke_junction_holes.mjs`, `thickLength`-лимиты) — все три существуют и делают
  заявленное.
- Аналитика issue и передача в S4 (владелец) корректно ссылаются на #302/#271 как
  на предшествующие задачи, не пересекаются с #303 (заявлено и не противоречит
  прочитанным документам).
- Трейлеры коммита `ff623cd4` (`Issue: #309`, `User-Visible: no`) корректны для
  чисто документационного коммита.

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

- Не прогонял `npx tsc --noEmit` / `npm test` / `npm run build` — на этом этапе
  нет изменений кода (`git diff origin/dev...HEAD` — один файл документации),
  гейты кода относятся к этапу код-ревью (§2.7).
- Не запускал `npm run golden:capture`/`golden:verify` и не пересчитывал вручную
  контур `junctionContractHoles` на реальном экспорте владельца — фикстура
  `test/fixtures/309-junction-teeth.json` из плана тестов ещё не создана, это
  предмет реализации и последующего код-ревью.
- Не проверял файл экспорта владельца (`houseplan-space-convergence-test-...json`)
  построчно на точное число «13 комнат/24 перегородки» (AC5) — доверяю
  подтверждённому исполнением заявлению автора аналитики; при код-ревью это
  число будет видно по фикстуре теста.
- Не оценивал `docs/USER-GUIDE.ru.md` на предмет новой терминологии — задача не
  вводит пользовательских терминов (чистая геометрия рендера), проверка
  нерелевантна.

## Вердикт

Жёлтый. High-находок нет. Один Medium **в скоупе** задачи: отсутствуют
обязательные разделы ТЗ §7.1 (Сценарий, Что человек увидит, явный Скоуп/не-скоуп,
UX, Модель данных и миграция, i18n, Риски, Release-артефакты) — все решаются
автором самостоятельно, без вопроса владельцу, и дописываются в этом же файле.
Технический контракт (§3.1-3.5) и критерии приёмки (AC1-7) при этом полны,
однозначны, обоснованы прочтением кода и не содержат догадок, выданных за факт.