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

SPEC-REVIEW-123-r1

• Issue: https://github.com/Matysh/houseplan-card/issues/123
• ТЗ под ревью: docs/specs/123-corner-split-wall.md (коммит ba56d4f)
• Роль: ревьюер ТЗ (не автор), этап S4-spec-review
• Трек: обычный (не small) — оценка сложности 7/10, больше одной поверхности, визуальная и световая геометрия; лёгкий трек корректно не применён
• Цикл: r1/4

Скоуп ревью

Проверялось соответствие ТЗ:

• docs/SCOPE.md — попадание в Core user jobs, отсутствие расширения скоупа;
• PROCESS.md §2.4, §2.5 (DoR), §7.1 (обязательные разделы) и §12 (запреты);
• AGENTS.md — классы файлов, ветка, легитимность приёма чужого issue в процесс;
• каноническим документам затронутой подсистемы: docs/WALL-THICKNESS.md, docs/SUN.md, docs/LIGHT.md, docs/ISOMETRIC.md, docs/TOUCH-SUPPORT.md, docs/CONFIG-COMPATIBILITY.md;
• docs/USER-GUIDE.ru.md — терминология «Split» / «Перегородка»;
• фактическому состоянию кода (src/wall-thickness.ts, src/iso-walls.ts, src/space-render.ts, test/wall-thickness.test.mjs) — на предмет того, что технические утверждения ТЗ не являются непроверенной догадкой.

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

1. Прочитан весь тред issue #123, включая решение владельца о приёме чужого issue в процесс (после правки конвейера, коммит 024cdc0, issue #114) и протокол аналитики с defaults Q1–Q3, принятыми владельцем 2026-08-13 (комментарий https://github.com/Matysh/houseplan-card/issues/123#issuecomment-5283843252).
2. Сверены обязательные разделы ТЗ (§7.1 PROCESS.md) построчно — см. таблицу ниже.
3. Прочитан код wallBodiesGeometry() (src/wall-thickness.ts:1361-1412): подтверждено, что тело стены строится как per-room outset(poly, half) − inset(poly, half), затем union по комнатам — именно механизм, который ТЗ называет причиной дефекта (диагональный Split из вершины вносит острые митры дочерних комнат в наружный union).
4. Прочитан src/iso-walls.ts и docs/ISOMETRIC.md — подтверждено, что скрытая изометрия уже потребляет тот же wallBodiesGeometry() MultiPolygon, а не отдельную модель; утверждение ТЗ §6.4 о единой геометрии для Plan/View/ houseplan-space-card/изометрии не является новым архитектурным изобретением автора, а фиксирует уже существующий контракт.
5. Прочитан docs/LIGHT.md («Opaque: the wall bodies exactly as the plan draws them (wallBodiesGeometry)») — подтверждает AC7 (Glow/солнце используют то же исправленное preграждение) технически достижимым без отдельной правки light-барьеров.
6. Прочитан docs/TOUCH-SUPPORT.md — формулировка «safety floor» и «pointer cancellation» в ТЗ §9 дословно соответствует канону, а не придумана.
7. Прочитан docs/USER-GUIDE.ru.md (таблица инструментов, разделы «Split» и «Перегородка») — терминология ТЗ совпадает с пользовательским словарём, различие Split/Перегородка воспроизведено верно и явно вынесено в не-скоуп (п.5.4).
8. Прочитан test/wall-thickness.test.mjs — регрессионные сценарии, которые ТЗ в §11.1 п.7 требует не сломать (partial shared wall, virtual-T mitre, nested room, 45° wall, split materialisation), реально существуют в файле, то есть план автотестов не ссылается на несуществующее покрытие.
9. Проверено, что docs/ARCHITECTURE.md, docs/STATUS.md, docs/CHANGELOG(.ru).md существуют — release-артефакты в §13 указывают на реальные файлы.
10. Проверена запись в docs/specs/README.md — строка на #123 добавлена в том же коммите, ссылка issue ↔ ТЗ двусторонняя.

Обязательные разделы (§7.1 PROCESS.md)

Раздел	Есть	Комментарий
Сценарий (персона/поверхность/момент)	✅	§1
Что человек увидит до/после (без терминов реализации)	✅	§1, одна фраза
Проблема	✅	§2, с воспроизведёнными числами bbox на 948f284
Скоуп / не-скоуп	✅	§4 / §5
Контракт поведения	✅	§6
UX	✅	§9
Модель данных и миграция	✅	§8
i18n	✅	§9 (пусто, обосновано)
AC1…ACn с доказательством	✅	§10, 13 штук, каждый с типом
План автотестов	✅	§11
Риски	✅	§14
Откат	✅	§15
Release-артефакты	✅	§13

Все обязательные разделы присутствуют и содержательны, не формальные заглушки.

Находки

Находок уровня High и Medium нет.

Low-1 — тип доказательства AC11 не входит буквально в перечень §2.5

Файл: docs/specs/123-corner-split-wall.md:293-295

AC11 помечен (performance + ревью кода). DoR (PROCESS.md §2.5) перечисляет допустимые типы доказательства как unit / backend / smoke / golden / «ревью кода»; литерала performance в этом перечне нет. По существу критерий всё равно доказуем: в ТЗ явно указано «ревью кода» вторым типом, а performance_smoke/large-house benchmark — существующие release-blocking гейты (§11.4 этого же ТЗ, PROCESS.md §8), а не новый вид проверки. Блокирующим не является, но для чистоты трассируемости стоит переформулировать доказательство AC11 как «ревью кода» с явной ссылкой на существующий performance_smoke/ large-house benchmark, не вводя пятый тип доказательства.

Решение ревьюера: Low, не блокирует. Можно поправить формулировку при следующей правке ТЗ или снять с этой записью — оставляю на усмотрение автора, т.к. критерий по сути проверяем и не создаёт риска для DoR.

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

• Легитимность приёма issue в процесс (чужой автор, но явно допущен владельцем после правки конвейера #114) — не относится к дефектам ТЗ, отдельно зафиксировано в треде issue самим владельцем.
• Соответствие docs/SCOPE.md: задача закрывает J6 («Keep the plan true as the home evolves») и частично J4 (встроенный редактор без искажений архитектуры), обе строки в статусе «Closed» — это регрессионный баг внутри уже принятой функциональности, а не новая фича и не расширение скоупа.
• Владелец лично принял defaults Q1–Q3 и приоритет P2 (комментарии 2026-08-13T16:52 и 17:00) — открытых продуктовых вопросов в финальной редакции ТЗ нет, и это корректно: вопросы были заданы и закрыты на этапе аналитики, а не додуманы автором.
• Технический диагноз причины (per-room outset−inset union, острые митры дочерних комнат Split входят в наружный силуэт) подтверждён чтением src/wall-thickness.ts — не голословное утверждение автора.
• Раздел 16 «Принятые технические предположения» корректно отделяет свободно изменяемые технические решения (имена helper'ов, конкретная boolean- декомпозиция, имя golden/smoke сценария) от решений владельца Q1–Q3, которые пересмотру не подлежат — ни одна догадка не выдана за факт без пометки.
• Не найдено ни одного утверждения о поведении, которое не следует ни из канонических документов, ни из принятых владельцем defaults, ни из чтения существующего кода, и при этом не помечено как предположение.
• AC1–AC13 однозначны, у каждого указан тип доказательства и он входит (кроме Low-1) в допустимый по DoR список; план автотестов (§11) даёт конкретный, проверяемый маршрут для каждого, включая явное требование «тест из п.3 обязан краснеть на 948f284» — критерий, защищающий от неспособного падать теста.
• Не-скоуп (§5) корректно отсекает смежные соблазны (не превращать Split в Перегородку, не трогать инструмент «Перегородка», не менять модель данных, не вводить новый UX для cap/join) — типичные места, где скоуп мог бы незаметно расшириться.
• Release-артефакты (§13) перечисляют реальные файлы, включая docs/WALL-THICKNESS.md (exterior/shared junction invariant) и docs/USER-GUIDE.ru.md — корректная точка правки терминологии для пользователя.
• Реестр docs/specs/README.md обновлён тем же коммитом, ссылка issue ↔ ТЗ двусторонняя (PROCESS.md §7.1).

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

• Не проверял, что предложенная в §7 архитектурная декомпозиция (exterior envelope vs shared divider body) реализуема без регрессии в polyclip-ts-based boolean операциях — это по правилам ТЗ (§16 п.2) свободно изменяемое техническое предположение автора кода, не предмет ревью ТЗ.
• Не проверял производительность реального large-house benchmark — AC11 предполагает существующий гейт, а не новый, и это станет предметом ревью кода/пре-релизного гейта, не ревью ТЗ.
• Не запускал никаких автотестов — на этапе spec это не требуется; проверка существования регрессионных сценариев (см. «Как проверялось», п.8) сделана чтением файла, не исполнением.
• Не проверял корректность конкретных числовых bbox-диагностик из §2 — доверяю записи владельца/автора в треде issue как источнику числа, поскольку оно уже независимо зафиксировано в комментарии аналитики до написания ТЗ.

Вердикт

Зелёный. High: 0, Medium: 0. Одна находка Low (AC11 формулировка типа доказательства) — не блокирует, оставлена автору на усмотрение с записью в этом документе (не «TODO», а фиксированное решение ревьюера: можно поправить или отклонить без нового цикла).