diff --git a/docs/reviews/SPEC-REVIEW-309-r3.md b/docs/reviews/SPEC-REVIEW-309-r3.md new file mode 100644 index 00000000..35642449 --- /dev/null +++ b/docs/reviews/SPEC-REVIEW-309-r3.md @@ -0,0 +1,195 @@ +# SPEC-REVIEW-309-r3 + +Issue: https://github.com/Matysh/houseplan-card/issues/309 «Стыковочные узлы: визуальный лимит mitre и устранение паразитных парных патчей» +Этап: spec (обычный трек — сложность/риск владельца 6/10 и 7/10, `small` невозможен) +Заход: r3 · блокирующих циклов израсходовано 2 из 4 (до этого раунда) +Ревьюер: Claude (сессия ревью ТЗ), артефакт: `docs/specs/309-junction-visual-limit.md`, коммит `2ade4352` (ветка `issue/309-junction-visual-limit`). `git diff origin/dev...HEAD --stat` — 3 файла документации (спек + `SPEC-REVIEW-309-r1.md` + `SPEC-REVIEW-309-r2.md`), кода нет. + +## Скоуп + +Продуктовая рамка не изменилась с r1/r2 — рендер кладки в узлах стыка стен +(J1/J6 SCOPE.md), см. `SPEC-REVIEW-309-r1.md`, раздел «Скоуп»: соответствие +подтверждено там, дельта r3 её не задевает, наследую без повторной проверки. + +Предмет r3 — ревизия 3 ТЗ (коммит `2ade4352`), написанная в ответ на жёлтый +вердикт r2: «§3.6 — явный не-скоуп механизма #249 …; §3.8a — touch-impact …» +(комментарий владельца от 2026-08-25T18:13:49Z, `IC_kwDOTOcLQM8AAAABQr2fJA` +— id `5414712356`). Разбор по дельте (§2.10): единственная находка r2 состояла +из двух подпунктов одного Medium, дельта — точечная правка того же файла +(два новых абзаца), новую подсистему не задевает, контракт поведения (§3.1–3.5) +не меняет → полный повторный разбор не требуется, проверяю дельту плюс всё, до +чего она дотягивается. + +## Как проверялось + +1. Нашёл вердикт предыдущего раунда и SHA, на котором он получен: комментарий + `5414679506` (2026-08-25T18:11:18Z) — «Вердикт: жёлтый · заход r2 · + блокирующих циклов 2/4 · High: 0 · Medium: 1 → в задаче», документ + `docs/reviews/SPEC-REVIEW-309-r2.md`, получен на коммите спека `f0ea376a` + (сам документ явно называет этот SHA в шапке — не находка, SHA назван). +2. Объявляю дельту: `git diff f0ea376a..2ade4352 -- docs/specs/309-junction-visual-limit.md` + — 10 вставленных строк, 1 изменённая (строка статуса), 0 удалённых. Все + вставки: (a) новый абзац в §3.6 «Скоуп и не-скоуп» про механизм #249; (b) новый + раздел §3.8a «Touch»; (c) новая строка AC «7a» (помечена в тексте как AC8) про + не-скоуп #249. Разделы §0–§3.5, §4, AC1-6 и AC7 (мутанты), §6, §7 — байт-в-байт + те же, что были на `f0ea376a` и уже проверены в r1/r2. +3. По каждому из 2 подпунктов находки r2 построчно сверил новый текст с + требованием (таблица «Закрытие раунда r2» ниже) и перепроверил фактическую + точность заявлений — не на веру автору, чтением кода: + - `src/wall-thickness.ts:80` (`MITRE_LIMIT = 4`), `:83` + (`MULTI_WALL_JOIN_LIMIT = 1.25`, комментарий «#249» рядом в коде), + `:1996` (`node.limit: MULTI_WALL_JOIN_LIMIT * halfDepth` — единственное + место присвоения), `:1475` и `:3875` (`multiWallNodeAt(...)?.limit` — + оба сайта mitre контуров комнат), `:2612-2696` + (`multiWallBevelCutsAt`, вырез экстерьерного полотна/paper envelope через + `node.limit`, вызовы на `:2642-2666`). + - Построчно прошёл тела `linearWallJoinPatches` (`:1082-…`) и + `junctionNodeGeometry` (`:2032-…`) целиком (`awk` по диапазону функции) — + ни одна не ссылается на `.limit`/`node.limit`/`MULTI_WALL_JOIN_LIMIT`; обе + считают собственный локальный `limit = MITRE_LIMIT * max(halfDepth)` + (`:1144`, `:2087`). Это подтверждает заявление §3.6 «AC8» буквально — + функции, которые правит #309, физически не читают `node.limit`. + - `src/wall-thickness.ts:129` (`interface MultiWallNodeMap`) и + `buildMultiWallNodeMap` (`:1809`) — карта действительно общая + (используется и веером `junctionNodeGeometry`, и room-contour/paper кодом), + что подтверждает точность фразы §3.6 «`MultiWallNodeMap` используется + совместно, но `node.limit` не переопределяется». + - `src/houseplan-card.ts:19724-19760` (`touchStroke`, `physical-hit`) и + `src/styles.ts:2256-2269` — hit-зоны рисуются отдельными + ``/`` с фиксированной шириной обводки + по осевой линии/грани стены, геометрически независимо от формы патчей + стыков (`linearWallJoinPatches`/`junctionNodeGeometry`). Подтверждает + §3.8a: правка формы кладки в узле не может задеть эти элементы. +4. `git diff origin/dev...HEAD --stat` — только документация (3 файла: + спек + оба предыдущих ревью), кода нет. Как и в r1/r2, `npx tsc --noEmit` / + `npm test` / `npm run build` на этом этапе неприменимы — не гоняю по той же + причине (нет изменений `src/**`), это не пропуск гейта, а отсутствие + предмета для него. +5. Прочитал `docs/WALL-THICKNESS.md:100-230` повторно (тот же диапазон, что и + в r2) для сверки статус-кво механизма #249/#279, поскольку новый текст §3.6 + этот статус-кво пересказывает — совпадает. +6. Прочитал `docs/TOUCH-SUPPORT.md` (контракт View/kiosk как touch-first, + блокирующих поверхностей) — новый текст §3.8a не противоречит ему и + корректно называет hit-зоны/жесты/панораму-зум как неизменные. +7. `git log -1 --format=%B 2ade4352` — трейлеры `Issue: #309` / + `User-Visible: no` на месте, корректны для документационного коммита. + +## Закрытие раунда r2 + +| Находка r2 (подпункт) | Чем закрыта | Где это видно | +|---|---|---| +| #249/`node.limit` не исключены явно из скоупа | Добавлен абзац в §3.6: «Явный не-скоуп — механизм #249: `MULTI_WALL_JOIN_LIMIT = 1.25` (:83) и его потребители — `multiWallBevelCutsAt` (paper envelope) и mitre контуров комнат (:1475/:3875) — не изменяются… `MultiWallNodeMap` используется совместно, но `node.limit` не переопределяется. AC8 закрепляет это диффом» | `docs/specs/309-junction-visual-limit.md:61` | +| Touch-impact не назван явным пунктом DoR | Добавлен §3.8a «Touch (docs/TOUCH-SUPPORT.md)»: «Touch-контракт не затрагивается: … hit-зоны (`physical-hit`, touchStroke), жесты, панорама/зум и порядок обработки касаний не изменяются. View/kiosk … получают ту же геометрию из общего структурного кэша без каких-либо новых слушателей» | `:71-73` | + +Оба подпункта находки r2 закрыты полностью и по существу (не только по форме): +проверено чтением кода (шаг 3 выше), что оба заявления фактически верны, а не +правдоподобная догадка, выданная за факт. + +## Унаследовано из r2 (и транзитивно из r1) + +Без повторной проверки, по документам `docs/reviews/SPEC-REVIEW-309-r1.md` +(SHA `ff623cd4`) и `docs/reviews/SPEC-REVIEW-309-r2.md` (SHA `f0ea376a`) — +дельта r3 эти разделы не касается (сверено побайтово диффом из шага 2): + +- Продуктовая рамка/скоуп-соответствие SCOPE.md J1/J6 («Скоуп» r1). +- §0 «Сценарий» и «до/после» — персона, поверхности, момент (закрытие r1). +- Контракт §3.1–3.5: `VISUAL_MITRE_LIMIT = 1.5`, парная фаска (§3.2), фильтр + не-соседних пар в узлах ≥3 лучей (§3.3), правило вееров (§3.4), инварианты + «без дыр»/«без фантомов»/превью=персист (§3.5) — построчно проверены на + `src/wall-thickness.ts:80,1082-1150,2087`, `src/physical-geometry.ts:242` в r1. +- Математика порога: для равных толщин под 90° вылет `h·√2 ≈ 1.41h < 1.5h` — + проверено в r1, прямые/тупые углы не задеты. +- Остальная часть §3.6 «Скоуп и не-скоуп» (модель данных/конфиг, hit-зоны/снап, + политика #302 решения №5, #308) — не менялась дельтой r3, закрыта в r1/r2. +- §3.7 UX, §3.8 «Модель данных и миграция», §3.9 i18n, §3.10 Риски (4), + §3.11 Release-артефакты — закрыты в r2, дельтой r3 не тронуты. +- AC1–6 и AC7 (мутанты a-d) (§5) — однозначны, у каждого указано доказательство + (юнит/golden/смок), проверены в r1. +- План автотестов (§6) и откат (§7) — полны, проверены в r1. +- Low-находка r1 (расхождение «16» vs «15+1» junction-сцен) — снята ревьюером + без правки в r1, не проверяю повторно: не влияет ни на один AC. +- Трейлеры документационных коммитов (`Issue: #309`, `User-Visible: no`) — + корректны для `ff623cd4` и `f0ea376a`, проверено в r1/r2; для `2ade4352` та + же схема (см. «Как проверялось», шаг 7). + +## Находки + +### Low (не блокирует, отмечаю для полноты) + +**Нумерация AC в §5 разъезжается: новая строка помечена «7a», но названа в +прозе «AC8», а следующая (мутанты) осталась «7».** + +Фактическая последовательность в `## 5. AC`: `1, 2, 3, 4, 5, 6, 7a, 7`. Новая +строка, добавленная этой ревизией — `7a. **Не-скоуп #249 (AC8):** …` — стоит +*перед* уже существующим пунктом `7. **Мутанты:** …`, хотя в тексте §3.6 та же +строка называется «AC8» («AC8 закрепляет это диффом»). Формально у документа +теперь два разных обозначения одного и того же критерия (`7a` как заголовок +списка и `AC8` как ссылка на него из другого раздела), а «Мутанты» — фактически +восьмой по счёту критерий — сохранил старый номер «7». DoR (`PROCESS.md` §2.5) +требует «AC1…ACn — пронумерованные проверяемые критерии» — строго говоря, `7a` +не входит в последовательность `1..n`. + +Не блокирует: содержание однозначно (единственный кандидат на «AC8» — строка +`7a`, спутать её с чем-то другим невозможно), ни один AC не теряет +доказуемости, а на код-ревью не может возникнуть двух прочтений. Рекомендация +для следующей правки документа (не обязательно в этом раунде): перенумеровать +подряд `1…8` (не-скоуп #249 = AC7, мутанты = AC8) или убрать скобку «(AC8)» и +называть критерий по его фактическому заголовку «AC 7a» везде. Снимаю без +блокировки: чисто редакционный дефект, введённый этой же дельтой, не влияет на +проверяемость. + +## Что проверено и корректно + +- Оба подпункта находки r2 (#249/`node.limit` не исключён явно; touch-impact + не назван) закрыты полностью и по существу — не декларацией, а текстом, + который я перепроверил чтением кода и который оказался технически точным + (см. «Как проверялось», шаг 3): `linearWallJoinPatches` и + `junctionNodeGeometry` действительно не читают `node.limit`/ + `MULTI_WALL_JOIN_LIMIT`, а hit-зоны действительно нарисованы отдельными + DOM-элементами с фиксированной шириной, не зависящей от формы патча стыка. +- §3.6 корректно указывает конкретные строки-потребители #249 + (`multiWallBevelCutsAt`, `:1475`, `:3875`) — все три существуют и делают + ровно то, что написано. +- §3.8a корректно называет три поверхности, которые получают одну и ту же + геометрию из структурного кэша (View/kiosk touch-first по + `docs/TOUCH-SUPPORT.md`), не изобретая новый touch-термин. +- Новая строка AC (7a/«AC8») методологически корректна: критерий проверяем + («не входят в дифф») и способ доказательства указан («ревью кода по диффу + + существующие тесты») — тот же формат, что у остальных AC. +- Статус-строка (`Статус: ревизия 3 (после SPEC-REVIEW-309-r2: …)`) корректно + ссылается на r2 — трассируемость ревизии на месте. +- Трейлеры коммита `2ade4352`: `Issue: #309`, `User-Visible: no` — корректны + для документационной правки. +- Технический контракт (§3.1-3.5), AC1-7 (мутанты), план тестов, откат — не + менялись дельтой r3, наследуются из r1/r2 без повторной проверки (см. раздел + выше). + +## Чего не проверял + +- `npx tsc --noEmit` / `npm test` / `npm run build` — на этом этапе снова нет + изменений `src/**` (`git diff origin/dev...HEAD` — только 3 файла + документации), гейты кода относятся к этапу код-ревью (§2.7), как и в r1/r2. +- `npm run golden:capture`/`golden:verify` и фикстуру + `test/fixtures/309-junction-teeth.json` — фикстура ещё не создана, план + тестов не менялся дельтой r3, предмет реализации/код-ревью. +- Реальное поведение `multiWallBevelCutsAt`/room-polygon mitre на конкретном + экспорте владельца — заявление §3.6 проверено чтением кода (полные тела + функций, до которых #309 не дотягивается), не исполнением; для проверки + корректности текста ТЗ (а не будущей реализации) этого достаточно — + фактическую неизменность paper/room-contour рендера подтвердит код-ревью по + AC8 после реализации. +- `docs/USER-GUIDE.ru.md` — как и в r1/r2, не переоценивал: задача не вводит + пользовательских терминов интерфейса (чистая геометрия рендера). + +## Вердикт + +Зелёный. High-находок нет, Medium-находок нет. Оба подпункта Medium-находки r2 +(явный не-скоуп механизма #249/`node.limit`, явный touch-impact) закрыты +полностью и технически точно — проверено чтением кода, не на веру автору. Одна +Low-находка (нумерация нового AC «7a»/«AC8» разъезжается с соседним «7») не +блокирует: содержание однозначно, ни один AC не теряет доказуемости, дефект +чисто редакционный. Технический контракт (§3.1-3.5), AC1-7 (мутанты), план +автотестов и откат не менялись дельтой r3 и наследуются из r1/r2 без повторной +проверки. ТЗ готово к DoR (§2.5): все обязательные разделы присутствуют, +критерии приёмки однозначны и снабжены способом доказательства, открытых +продуктовых вопросов нет.