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

SPEC-REVIEW — Issue #278 · заход r1

• Issue: https://github.com/Matysh/houseplan-card/issues/278
• ТЗ: docs/specs/278-wall-union-isolation.md (SHA d906e5d8, ветка issue/278-wall-union-isolation)
• Трек: обычный (small/trivial явно исключены автором) — файл ТЗ обязателен, что соблюдено.
• Заход: r1 · блокирующих циклов израсходовано 0 из 4.

Скоуп ревью

Ревью ТЗ по PROCESS.md §2.4/§7.1: выполнимость и проверяемость AC1–AC15, отсутствие догадок, выданных за факт, полнота обязательных разделов, согласие с docs/SCOPE.md и каноническими документами подсистемы (docs/WALL-THICKNESS.md), непротиворечивость связанным issue (#141, #197, #199, #276, #277).

Продуктовый код не менялся (git diff --stat origin/dev...HEAD — только docs/specs/278-wall-union-isolation.md и запись в docs/specs/README.md), поэтому гейты tsc/test/build/check-docs к этому заходу не применяются: на этапе spec трогается только документ, дерево кода идентично dev.

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

1. Прочитан текст issue #278 и оба комментария автора (аналитика 10/9/7/9, P1, уточнение доказательной базы после повторного запуска preflight #199 на payload.config).
2. Прочитан docs/SCOPE.md — задача закрывает J1/J4/J6 (не даёт локальному дефекту физической геометрии визуально стирать этаж; план должен "keep the plan true").
3. Прочитан docs/WALL-THICKNESS.md §9 (Independent partitions, drafts and columns) — сверка терминологии extraBodies, physicalBodySet(), joined/raw body set, Glow/sun/clean-floor consumers.
4. Прочитан код src/wall-thickness.ts (wallBodiesGeometry, wallBodiesUnionPath, циклы roomRings/wallEdgeBodies/extraBodies, строки 2743–2880) — проверка центрального технического утверждения ТЗ.
5. Проверены issue #197 (закрыт) и #199 (закрыт) — согласованность границ "не дубликат".
6. Проверены #276 и #277 — оба сейчас также в S4-spec-review (не смержены), что важно для оценки принятого предположения о порядке merge (§18.4).
7. Проверено существование файлов, названных в плане тестов: test/wall-thickness.test.mjs, test/plan-geometry-preflight.test.mjs, scripts/model-invariants.mjs — существуют; demo/smoke_wall_union_isolation.mjs — не существует (ожидаемо, создаётся в разработке).
8. Проверено использование evenodd fill-rule в houseplan-card.ts/ space-render.ts/physical-geometry.ts — утверждение §5.7 о риске схлопывания coincident-компонента подтверждено существующим кодом и существующим комментарием в physical-geometry.ts про запрет конкатенации противоположно ориентированных rings в один evenodd path.
9. Сверены со смежными принятыми ТЗ той же подсистемы — docs/specs/253-resize-wall-thickness.md и docs/specs/275-multiwall-strip-containment.md — на состав обязательных разделов по PROCESS.md §7.1.

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

• Технический диагноз не догадка, а прочитанный код. Утверждение §2/§12.4 "цикл extraBodies в wallBodiesGeometry() не имеет per-piece try/catch, в отличие от roomRings и wallEdgeBodies, и исключение улетает во внешний catch, обнуляя весь результат" — подтверждено построчно (src/wall-thickness.ts:2815-2823 и :2830-2840 оба оборачивают тело цикла в try/catch, :2872-2875 — нет). Это именно то различие, которое делает ТЗ проверяемым, а не спекулятивным.
• roomGeom действительно исключает extras (:2851 вычисляется до for (const extra of extraBodies) на :2872) — соответствует AC5 ("room area не включает extras").
• Границы с #197/#199 объяснены и согласуются с фактическим текстом закрытых issue: #197 — единичный virtual-junction patch, здесь другой узел отказа; #199 — preflight Optimize, здесь — barrier для обычных commit-путей, которых у #199 не было. Автор дополнительно подтвердил во втором комментарии issue, что #199 не регрессировал (wall-null при повторном прогоне на точном payload.config), и перенёс эту находку в границу задачи (§3.5) — хорошая практика: уточнение доказательной базы отражено в ТЗ, а не осталось только в комментарии.
• Типизированный контракт §4 (ok/degraded-extra/failed-core/ not-applicable) и разделение strict/render-safe режимов дают однозначный, проверяемый словарь для AC1–AC3, AC6.
• Canonical-consumers claim (§6) подтверждён кодом: houseplan-card.ts, space-render.ts и plan-geometry-preflight.ts — все три реальных потребителя wallBodiesGeometry/wallBodiesUnionPath в src/.
• Явно помечены принятые технические предположения (§18) с правом ревьюера их оспорить — соответствует PROCESS.md §7.1: имена classes/reasons, бюджет bounded-toast, отсутствие отдельного repair UI, порядок merge #276→#277→#278. Открытых продуктовых вопросов действительно нет ни одного размытого места, которое требовало бы решения владельца, а не инженерного суждения.
• AC1–AC15 в целом привязаны к конкретному способу доказательства (unit, property/permutation matrix, production-bundle smoke, mutation, benchmark) — ни один AC не оставлен без названного способа проверки.
• Non-scope (§11) корректно выносит #276 (устранение конкретного redundant partition) и #277 (safe Resize) за периметр, не пытаясь тихо взять на себя их скоуп.

Находки

Medium (в скоупе, блокирует зелёный вердикт)

M1 — отсутствует обязательный раздел «Риски». PROCESS.md §7.1 перечисляет обязательные разделы ТЗ: «…критерии приёмки AC1…ACn с указанием доказательства · план автотестов · риски · откат · release-артефакты». В docs/specs/278-wall-union-isolation.md слово «риск» встречается один раз — как число в общей оценке заголовка («риск 9/10», строка 7) — и это всё; отдельного раздела с анализом рисков и мер нет вообще (структура документа: §1 Сценарий → …→ §13 Производительность → §14 Touch → §15 AC → §16 План тестов → §17 Release-артефакты и rollback → §18 Принятые предположения — раздела «Риски» между планом тестов и rollback, где он стоит в соседних ТЗ этой же подсистемы, нет).

Это не формальность: два родственных ТЗ той же геометрической подсистемы, написанные тем же автором, содержат именно такой раздел — docs/specs/253-resize-wall-thickness.md (§14 «Риски и защита») и docs/specs/275-multiwall-strip-containment.md (§11 «Риски и меры»). #278 — не менее рискованная задача (та же авторская оценка «риск 9/10», плюс явная кросс-issue зависимость), и именно здесь отсутствие анализа заметно:

• §18.4 фиксирует предположение о порядке merge #276→#277→#278, но на момент этого ревью #276 и #277 оба ещё в S4-spec-review, то есть все три задачи идут параллельно, а не последовательно, как предполагает пункт. Что произойдёт, если #278 будет реализован и смержен раньше #277 (временный adapter, который #278 должен удалить, ещё не существует), или #276 не будет готов к моменту, когда #278 нужен для AC6 (barrier зелёный «после valid #276 reconciliation») — не разобрано ни как риск, ни как assumption с планом на случай отклонения от предполагаемого порядка.
• Риск деградации UX для реальных легаси-планов (после этой задачи план с повреждённым extra навсегда останется в degraded-extra и будет виден как изолированный компонент до ручного #276-ремонта) заявлен как продуктовый контракт (§18.5), но не оценён как риск с мерой (например: сколько таких планов может существовать в проде, что видит пользователь до вмешательства).
• Риск того, что «reusable strict geometry transaction barrier» (§7) станет тем самым единственным источником правды, но при интеграции с уже реализуемым #277 останется временный дублирующий adapter дольше одного цикла — упомянут как admission (§18.4 «удаляет временный adapter»), но не как риск с последствием, если удаление не произойдёт до релиза.

Почему Medium, а не High: ни один AC не становится невыполнимым или непроверяемым из-за этого пропуска — сам контракт §3–§9 самодостаточен и проверяем без раздела «Риски». Это дефект полноты документа, а не дефект проверяемости критериев, поэтому не блокирует по критерию «ТЗ невыполнимо», но прямо нарушает обязательный список разделов §7.1 → жёлтый вердикт, правка остаётся в этом ТЗ (Medium в скоупе, решение владельца 2026-08-19 / #202: не заводится отдельный issue).

Как закрыть: добавить раздел «Риски» (после §13/§14 или перед §17, по образцу 253/275), явно разобрав минимум три пункта выше — параллельность #276/#277/#278, судьбу legacy degraded-extra планов без #276-ремонта и жизненный цикл временного adapter #277.

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

• Реализуемость union()/polyclip-ts конкретно для сценария «сохранить primary geometry при исключении на N-м extra и продолжить с N+1» — прочитано только текущее поведение (общий catch), не пробовалась экспериментальная реализация; на этапе spec это ожидаемо не требуется.
• Полный список файлов/модулей, которые будут затронуты в реализации — не входит в обязательные разделы ТЗ §7.1 (это чек-лист DoR §2.5), поэтому не оценивался как находка.
• Golden/perf/smoke наборы не запускались — код не менялся, гейты §8 к spec-этапу неприменимы; таблица гейтов не прикладывается по той же причине.
• Не проверялось содержимое приложенного 33.json (не публикуется по политике приватности, согласно самому issue) — доверился описанию автора и перепроверил через код, что описанный механизм отказа (extraBodies без try/catch) реален и достаточен для воспроизведения заявленного симптома.

Вердикт

Жёлтый. Единственная находка — M1, в скоупе задачи, не заводится отдельным issue. После добавления раздела «Риски» документ готов к повторному циклу.