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

# SPEC-REVIEW-310-r1

Issue: #310 «Парный острый стык: вернуть полное остриё, зубец торца толстой стены срезать по граням острия (follow-up #309)»
Этап: ревью ТЗ (PROCESS.md §2.4)
Документ ТЗ: `docs/specs/310-pair-apex.md` (ветка `issue/310-pair-apex`, ревизия 1, коммит `c8d56b6c`)
Заход: r1 · блокирующих циклов израсходовано 0 из 4
Метка: `small` не установлена → полный трек, файл ТЗ обязателен (создан) — соответствует.

## Скоуп

Ревью покрывает `docs/specs/310-pair-apex.md` целиком и его соответствие:
- телу issue #310 и обоим комментариям владельца (аналитика + «ТЗ готово»);
- `docs/SCOPE.md` (продуктовая рамка);
- `docs/WALL-THICKNESS.md` (канонический документ подсистемы, разделы про #302/#271/#309);
- фактическому коду `src/wall-thickness.ts`, `src/physical-geometry.ts`, `src/houseplan-card.ts` — не для код-ревью (правок в них нет), а чтобы отличить в ТЗ утверждение-факт от догадки, выданной за решение (обязательная проверка этапа spec).

Изменений кода в диапазоне нет: единственный коммит на ветке — `c8d56b6c docs: spec for #310 pair apex and butt-end trim` (`docs/specs/310-pair-apex.md`, 70 строк, `User-Visible: no`, трейлер `Issue: #310` на месте). Гейты типа `tsc`/`test`/`build` не запускал — это этап ТЗ, продуктовый код не менялся.

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

1. Прочитаны `docs/SCOPE.md`, `AGENTS.md`, `PROCESS.md` §§1–7.2 — заход r1, правило §2.10 (разбор по дельте) не применяется.
2. Прочитано тело issue #310 и оба комментария (`gh issue view 310 --json ... `) — решения владельца от 2026-08-25 сверены построчно с §1 и §2 ТЗ.
3. Прочитан `docs/WALL-THICKNESS.md` (разделы про #302 junction nodes, #309 visual mitre limit, #271 lateral trim) — технический контекст ТЗ сверен с зафиксированным контрактом подсистемы.
4. Прочитан код: `linearWallJoinPatches`, `chamferApex`, `linearWallBody`, `physicalBodyParts`/`physicalBodySet`, `buildMultiWallNodeMap`, `junctionNodeGeometry`, `junctionContractHoles`, `virtualJunctionPatches`, `unionJunctionPatches`, все три сайта использования `linearWallJoinPatches` (`wall-thickness.ts:1261` превью, `physical-geometry.ts:242` физическая геометрия, `houseplan-card.ts:19961` превью протяжки) и все четыре сайта `physicalBodyParts(...)` в `houseplan-card.ts`/`space-render.ts` — чтобы подтвердить или опровергнуть каждое техническое утверждение ТЗ (не мог ли автор выдать догадку за факт).
5. Прочитана фикстура `test/fixtures/309-junction-teeth.json` и посчитаны вручную лучи в каждом из трёх узлов (`step`, `spike`, `hump`) по координатам партиций, чтобы проверить утверждение ТЗ «step/hump не трогаются, потому что это узлы ≥3 лучей».
6. Прочитан и воспроизведён логически существующий тест `test/wall-thickness.test.mjs:3178` («issue 309 the full teeth fixture leaves no junction holes»), включая его собственный assert `map.nodes.length >= 2` — это прямое доказательство того, что делает находка №1 ниже.
7. Сверены AC1–AC7 и план тестов (§8) на однозначность, наличие способа доказательства и реальное существование называемых идентификаторов/функций/тестов (все существуют в коде — не фантазия автора).

## Находки

### [High] AC5 и Риск №2 называют детектор, который структурно не видит узел-пару — риск «дыры на границе среза» остаётся без рабочей проверки

**Файл:** `docs/specs/310-pair-apex.md`, §5 (риск 2) и §7 (AC5).

**Что не так.** Риск 2 прямо называет главную опасность задачи: «Новое вычитание — дыры на границе среза», и единственным гейтом под этот риск объявляет «детектор дыр (#302) на фикстуре и сценах» — то есть AC5: «детектор `junctionContractHoles` пуст на фикстуре и сценах». Это не так: `junctionContractHoles(geometry, map, options)` перебирает исключительно `map.nodes`, а `map` строится через `buildMultiWallNodeMap`, которая **отбрасывает узел, если у него меньше трёх канонических лучей** — дважды, явным `continue`:

```
src/wall-thickness.ts:1984   if (rays.length < 3) continue;
src/wall-thickness.ts:2032   if (canonicalRays.length < 3) continue;
```

Узел-пара (ровно два луча) — это ровно тот случай, который #310 создаёт и меняет: `linearWallJoinPatches` явно обрабатывает его отдельной ручной веткой именно потому, что «#309: узел с тремя и более каноническими лучами закрывается веерами вместо парных патчей» (комментарий в коде, `wall-thickness.ts:1137-1141`). Он никогда не попадёт в `map.nodes`, а значит `junctionContractHoles` никогда не просемплирует окрестность этого узла — независимо от того, есть там дыра или нет.

**Это не гипотеза, а воспроизводимый факт на собственной фикстуре задачи.** В `test/fixtures/309-junction-teeth.json` у узла `spike` (2.2208, 1.35) ровно два луча — партиции `mt8liuxi-0` (10 см) и `mt8liuxi-1` (20 см), сходящиеся только там. У узлов `step` (0.8083, 1.2333) и `hump` (1.7583, 1.6125) — 4 и 3 луча соответственно (посчитано по координатам концов партиций в фикстуре). Уже существующий тест `test/wall-thickness.test.mjs:3178` («issue 309 the full teeth fixture leaves no junction holes») строит `map` из этой же фикстуры и утверждает `assert.ok(map.nodes.length >= 2, ...)` — то есть в `map.nodes` попадают ровно `step` и `hump`, а `spike` — нет. Это тот самый узел, который #310 меняет и в котором вводит новое адресное вычитание.

**Почему это блокирует, а не мелочь.** Ручного тестирования нет ни на одном этапе процесса — по правилам этапа код-ревью именно автотест отвечает на вопрос «оно вообще работает», а на этапе ТЗ моя задача — убедиться, что AC доказуемо тем способом, который в нём назван. AC5, как написан, доказывает отсутствие дыр там, где #310 ничего не меняет (веера ≥3 лучей — они и так «не-скоуп», §2.3), и не доказывает ничего в узле, где появляется новая булева вычитающая операция — ровно там, где риск и назван. Ни один из остальных AC этот пробел не закрывает: AC2 проверяет одну конкретную точку в прежней зоне зубца (не «нет ли дыры где-то ещё на границе среза»), AC3 — только тело **за пределами** `2·halfDepth` (граница среза находится внутри этого радиуса, а не за ним), AC4 — байтовое неизменность **других** узлов, AC6 — не относящийся случай, а мутанты §7.7(a-c) моделируют «фаска вернулась», «трим выключен», «трим не ограничен» — ни один не моделирует «трим сработал в правильных границах, но оставил щель/дыру на стыке с патчем». То есть при реализации с корректной формой контура (AC1/AC2 пройдут) и корректным поведением за радиусом (AC3 пройдёт) дыра ровно на границе среза может пройти весь набор ACs незамеченной.

**Воспроизведение (как убедиться самостоятельно):**
```
grep -n "if (rays.length < 3) continue;\|if (canonicalRays.length < 3) continue;" src/wall-thickness.ts
# 1984 и 2032 — оба фильтра ограничивают map.nodes узлами ≥3 лучей
sed -n '3178,3200p' test/wall-thickness.test.mjs
# assert.ok(map.nodes.length >= 2, 'fixture keeps its multi-wall nodes') — из трёх узлов
# фикстуры в map попадают только 2 (степ и горб); spike (парный) исключён по построению.
```

**Что нужно поправить в ТЗ** (не мой выбор решения — это техническая деталь, автор/ревьюер решают сами по §7.1): AC5 должен либо (а) получить отдельный способ доказательства для узла-пары — например прямая проверка «нет дырки» через сэмплирование окрестности узла на `physicalBodySet.geometry` тем же приёмом, что и `junctionContractHoles`, но без фильтра по числу лучей, либо (б) явно расширить вход `junctionContractHoles`/его карту так, чтобы 2-лучевые узлы тоже туда попадали. Любой вариант — правка внутри этого же ТЗ, не смена подхода.

### [Low] Технические решения реализации не оформлены явным блоком «принято предположительно, поменять свободно» — принимаю сам, без правки ТЗ

**Файл:** `docs/specs/310-pair-apex.md`, §2.2 (место среза в конвейере: «второе адресное вычитание рядом с тримом #271, той же фазой в потребителях»).

Это решение, которое пользователь не наблюдает (внутренняя фазировка), и по PROCESS.md такие решения должны попадать в явный блок «принято предположительно, поменять свободно», чтобы ревьюер мог его оспорить целенаправленно. Блока нет — решения просто вписаны в контракт. По существу возражений нет: разместить новый трим рядом с существующим #271-тримом и в той же фазе потребителей — разумный дефолт, не создающий новой архитектурной сущности. Снимаю с записью, правки не требую.

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

- **Продуктовая рамка (§0 ТЗ).** Сценарий и «до/после» присутствуют, персона (Home admin, десктоп-редакторы) и связь с J1/J6 (`docs/SCOPE.md`) не нарушены; задача не расширяет скоуп — это точечный визуальный баг-фикс геометрии кладки, ранее принятой владельцем как дефект (#309 follow-up).
- **Решения владельца перенесены точно.** §1 ТЗ («полный mitre без лимита в узлах-двойках», «зубец срезается продолжением грани острия») буквально совпадает с текстом обоих комментариев владельца в issue — не переформулировано и не дополнено собственными догадками автора.
- **Технический контракт §2.1 проверен построчно по коду.** Утверждение «mitre-патч строится как до #309: `[node, pA, hit, pB]` без проверки `VISUAL_MITRE_LIMIT` и без `chamferApex`» точно описывает нынешний код (`wall-thickness.ts:1193-1197`) с одной заменой: убрать применение `VISUAL_MITRE_LIMIT`/`chamferApex` именно в этой ветке. Утверждение «`MITRE_LIMIT` в парной ветке не применяется» тоже подтверждено — `lineIntersect` (строка 1339) не использует `MITRE_LIMIT` вовсе, он и раньше не участвовал в парной ветке.
- **Технический контракт §2.2 (торцевой трим) обоснован реальной геометрией, а не выдумкой.** `linearWallBody` (строка 1062) действительно строит плоский прямоугольный торец, перпендикулярный оси стены — источник «зубца» у толстой стены при остром угле подтверждён кодом, а не является догадкой автора, выданной за факт. Границы «вдоль оси не дальше `2·halfDepth`(своей)» однозначны и проверяемы.
- **Сверка узлов фикстуры вручную.** Три узла `309-junction-teeth` — это `step` (4 луча), `spike` (2 луча) и `hump` (3 луча); заявление §0/§2.3 «step/hump не трогаются, потому что там узлы ≥3 лучей» подтверждено пересчётом координат, а не принято на веру.
- **Перечень потребителей парных патчей (§3 скоуп) полон.** `linearWallJoinPatches` имеет ровно три вызывающих места (превью открытого контура в `drawWallPreviewD`, `physicalBodyParts`, интерактивное превью протяжки в `houseplan-card.ts:19961`), а `physicalBodyParts(...).all` — единственный источник тела партиций для статического/полного 2D-рендера (`space-render.ts:236`), 2.5D-изо (`houseplan-card.ts:5330`), физической идентичности (`houseplan-card.ts:13990`) и барьеров света (`houseplan-card.ts:16258`). Заявление §4 «меняется форма кладки на всех поверхностях через общий структурный кэш» подтверждено — не общие слова.
- **Не-скоуп корректен.** `virtualJunctionPatches`/`unionJunctionPatches` (виртуальные Т-стыки контуров комнат у вырезов) и #249-механизм (`multiWallBevelCutsAt`, ≥3-лучевые узлы) — действительно отдельные, не связанные с узлом-парой механизмы; исключение их из скоупа обоснованно.
- **AC1, AC3, AC4, AC6, AC7 однозначны и имеют реальный, существующий способ доказательства** (проверены имена функций/тестов — `physicalBodySet`, golden-сцены `junction-309-step/hump-dark`, `junction-309-spike-dark`, матрица `demo/golden/matrix.mjs:620-627`, существующий тест-паттерн мутантов). AC2 приемлем при условии, что «проба» и пересъёмка golden-сцены вместе покрывают форму контура визуально и точечно.
- **Риск №1** (возврат длинных «хвостов» на почти встречных стенах) корректно квалифицирован как осознанный и уже исторически принятый (было так до #309); фолбэк для вырожденных пар не меняется и это подтверждено кодом (`lineIntersect` возвращает `null` только при параллельности).
- **Риск №3** (интерференция #271+#310 трима) адекватно закрыт отдельным юнитом «пара с коротким толстым саппортом» в §8 — обе техники применяются к взаимно исключающим степеням узла (#271 требует ≥3 луча, #310 — ровно 2), риск реален только когда один и тот же короткий толстый отрезок стены одним концом попадает в узел-пару, а другим — в ≥3-лучевой узел; тест-план это учитывает.
- **Release-артефакты, откат, UX/i18n/данные (§4, §6, §9)** — полны, корректны, ничего не упущено: нет миграции, нет новых полей, откат — чистый ревёрт геометрии.
- **Трейлеры коммита** (`Issue: #310`, `User-Visible: no`) на месте, класс изменения (C — документация) корректен, отдельный issue на инфраструктуру не нужен.

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

- Полный обход всей `demo/golden/matrix.mjs` на предмет иных 2-лучевых острых пар за пределами трёх названных `junction-309-*`-сцен и владельческого репро — проверил вручную состав сцен `arms:`-семейства (все ≥3 луча) и `junction-owner-repro`/`junction-patch-resilience` (по имени и связи с #302, тоже ≥3-лучевые механизмы), но не гонял `npm run golden:verify` целиком — на этапе ТЗ код не менялся, гонять нечего; это ляжет на код-ревью после реализации.
- Не проверял фактическую работу `chamferApex`/геометрических формул на предмет численных краевых случаев (например, поведение при `sin` близком к нулю в самой парной ветке) — это код-ревью реализации, а не ревью контракта.
- Не запускал `npm run typecheck`/`npm test`/`npm run build` — на этой ветке нет изменений продуктового или тестового кода, гонять эти гейты нечего.
- Не проверял `npm run invariants` — задача не трогает модель данных (нет изменений `layout`, записей толщины, `marker.space`, `open_spans`), только вычисляемую геометрию рендера; инвариант о ключе решёточного ребра неприменим.

## Итог

Один блокирующий (High) недочёт: главный названный риск задачи («дыры на границе нового среза») не имеет рабочей проверки, потому что единственный названный для него гейт (`junctionContractHoles`) структурно не видит 2-лучевые узлы — а именно такой узел #310 и меняет. Остальное ТЗ технически точное, продуктовая рамка и решения владельца перенесены без искажений и без выданных за факт догадок. Возврат автору для правки AC5 (и, по желанию, снятого Low-замечания не требуется). Полный повторный разбор при r2 не обязателен, если правка ограничится AC5/§7 — это точечная правка внутри уже проверенного контракта.