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

SPEC-REVIEW-276-r1

• Issue: https://github.com/Matysh/houseplan-card/issues/276
• Этап: ТЗ на ревью (PROCESS.md §2.4)
• Заход: r1 · блокирующих циклов израсходовано 0 из 4
• ТЗ: docs/specs/276-coincident-partition-reconciliation.md (commit a06c94b9, ветка issue/276-reconcile-coincident-partition)
• Вердикт: красный · High: 1 · Medium: 3 (все в скоупе задачи)

Скоуп

Обычный трек (не small), ТЗ — отдельный файл docs/specs/276-*.md. Диффом этого раунда является вся первая редакция ТЗ (это r1, дельта не применяется — §2.10 не в силе). Продуктовый код не менялся, диапазон правок — только docs/specs/276-coincident-partition-reconciliation.md и docs/specs/README.md (commit a06c94b9, 249 добавленных строк).

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

• Прочитаны docs/SCOPE.md, AGENTS.md, PROCESS.md §2, §4, §7.1, §7.2, §2.5 (DoR).
• Прочитано тело issue #276 и все 4 комментария (аналитика, связанные #277/ #278, claim, хендофф).
• Прочитан целиком сам документ ТЗ (docs/specs/276-coincident-partition- reconciliation.md, 249 строк).
• Сверка терминологии и заявленной причины с канонической документацией: docs/WALL-THICKNESS.md (модель independent partitions, §9), фрагменты docs/USER-GUIDE.ru.md про инструмент «Граница», «Оптимизировать планы» и проёмы на совпадающей независимой стене, docs/ARCHITECTURE.md (Undo/Redo стек, Optimize/model-v7).
• Сверка упомянутых в ТЗ функций и артефактов с фактическим деревом (grep/find по src/**, docs/**): physicalBodyParts(), _boundaryBlocked(), _wallUnionGeometry(), mergeCollinearPartitions(), optimizePlans(), PLAN_MODEL_VERSION, resolveOpeningWallAssociation, test/plan-geometry-preflight.test.mjs — все существуют, заявленное поведение соответствует коду.
• Прочитан код Optimize Undo/Apply (src/houseplan-card.ts:15120–15208) для проверки заявленного контракта Undo/Redo (см. находку H1).
• Docs-гейты для этого дифф-скоупа (spec-only, класс C) — не запускались: правки не трогают src/**, node scripts/check-docs.mjs не относится к этому раунду (автор уже отчитался о зелёном прогоне в хендоффе, что достаточно для docs-диффа). tsc/test/build неприменимы — код не менялся.

Находки

H1 (High, блокирует). Заявленный Redo для серверной отмены Optimize не существует и не заявлен как новая работа

Где: §6 «UI и отчёт Optimize», абзац «После Apply»: «Undo одним действием восстанавливает partition и исходный hosted host, Redo снова канонизирует.» Тот же контракт закреплён в §12 AC7: «Apply — один WS call, Undo/Redo восстанавливают обе формы.»

Как воспроизвести противоречие: Optimize использует не общий 50-командный _geometryHistory (Ctrl+Z/Ctrl+Shift+Z), а отдельный one-shot серверный snapshot:

• _alignOptimizedConfirm() (src/houseplan-card.ts:15120–15150) после Apply очищает _geometryHistory.clear() и включает единственный флаг _canOptimizeUndo по ответу сервера (can_undo);
• _undoPlanOptimization() (src/houseplan-card.ts:15169–15208) на houseplan/plan/optimize_undo снова зовёт _geometryHistory.clear() и ставит _canOptimizeUndo = false — после отмены никакого «Redo» не существует: кнопка в блоке Undo Optimize (src/houseplan-card.ts:16434– 16437) только одна, mdi:undo-variant, без парного redo-действия;
• docs/USER-GUIDE.ru.md:1444 независимо описывает тот же контракт словами для пользователя: «После оптимизации доступна одна серверная отмена, но только до следующего изменения плана… Новый edit делает резервную копию оптимизации устаревшей.» Ни там, ни в docs/ARCHITECTURE.md нет упоминания Redo применительно к Optimize.

Итого: заявление «Redo снова канонизирует» не соответствует ни одному существующему механизму и не помечено в ТЗ как предположение или как новая работа (в §7 «В скоупе» / §9 «Архитектурный контракт» о добавлении Redo-пути для Optimize нет ни слова, в §8 «Не входит» — тоже). Это ровно тот случай, который процесс называет замечанием: «утверждение о поведении, которого нет ни в одном документе и которое не помечено как предположение». AC7 в текущей форме либо недоказуем (Redo нечем закрыть без изобретения новой функциональности за пределами заявленного скоупа), либо реализация втихую досоздаст Redo-путь для Optimize, чего никто не решал.

Требуется: либо убрать пункт про Redo из §6/AC7 и явно описать, что после Undo Optimize канонизация не восстанавливается автоматически (пользователь может только повторно нажать «Оптимизировать»), либо — если Redo для Optimize действительно нужен продукту — вынести это отдельным продуктовым вопросом владельцу (это расширение существующего контракта one-shot undo, а не деталь реализации).

M1 (Medium, в скоупе). Раздел «Риски» отсутствует — обязательный пункт DoR

PROCESS.md §2.5 требует явно: «открытых продуктовых вопросов нет; риски перечислены» — как отдельный обязательный пункт перед переводом в S5-ready. В документе нет ни заголовка, ни абзаца, который перечислял бы риски и меры (аналог §11 «Риски и меры» в предыдущем спеке той же подсистемы, docs/specs/275-multiwall-strip-containment.md:402). §10 «Производительность» задаёт бюджет как контракт, а не как риск с митигацией; §14 обсуждает только rollback. Ничего не сказано, например, про риск того, что реальные экспорты (на которые ссылается сама issue) содержат ещё не описанные комбинации (частичное перекрытие, разная толщина), которые попадут в «неоднозначный случай» и останутся неисправленными молча — это стоит явно назвать риском с принятой мерой (отчёт Optimize должен это показывать/не показывать?).

Требуется: добавить раздел «Риски» с перечислением и принятыми мерами.

M2 (Medium, в скоупе). Не перечислены затронутые файлы и модули — обязательный пункт DoR

PROCESS.md §2.5: «перечислены затронутые файлы и модули» — обязательный пункт. В документе нет ни одного упоминания src/*.ts (проверено: grep -n "src/\|\.ts\b" по файлу спецификации — 0 совпадений), хотя аналитика в комментарии issue #276 уже называет конкретные функции (physicalBodyParts(), _boundaryBlocked(), _wallUnionGeometry(), optimizePlans(), mergeCollinearPartitions()) и, значит, авторы уже знают, где лежит код. Раздел 9 «Архитектурный контракт» говорит только расплывчато: «Pure helper живёт рядом с Optimize/wall merge либо в отдельном модуле» — этого недостаточно для DoR-чеклиста, который требует список файлов/модулей, а не намерение.

Требуется: явный список (src/plan-optimizer.ts, src/wall-merge.ts, src/physical-geometry.ts, src/houseplan-card.ts — или что решит автор) — хотя бы приблизительный, он и так «принято предположительно, поменять свободно» по §7.1.

M3 (Medium, в скоупе). Ссылка на несуществующий канонический документ docs/PLAN-OPTIMIZE.md

Файл упомянут дважды: в шапке («Связано: …, docs/WALL-THICKNESS.md, docs/PLAN-OPTIMIZE.md», строка 12) и в §14 «Release-артефакты и rollback» как документ, который коммит реализации обязан обновить (строка 228). Проверено: find docs -iname "*optimiz*" не находит такого файла — в репозитории существуют только спеки docs/specs/{198,199,223,248,252,273}- optimize-*.md, а канонический материал по Optimize фактически распределён между docs/USER-GUIDE.ru.md (раздел про «Общие настройки → Оптимизировать планы», строки ~1392–1449) и docs/ARCHITECTURE.md (строка 1036: «Optimize Plans performs the equivalent idempotent model-v7 migration»). Утверждение о существовании отдельного канонического файла — факт, поданный без пометки «предположение», и он неверен уже сейчас: если раздел §14 будет исполнен буквально, автор реализации не найдёт файл для правки.

Требуется: заменить ссылку на реально существующие документы (docs/USER-GUIDE.ru.md, docs/ARCHITECTURE.md) либо явно решить создать новый docs/PLAN-OPTIMIZE.md и пометить это как отдельное техническое решение автора (§7.1 разрешает такие решения принимать самостоятельно, но не молча выдавать несуществующее за существующее).

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

• Первые два продуктовых раздела по сути отвечают на нужные вопросы, хотя и не оформлены отдельным «Что человек увидит до и после» (как это сделано в docs/specs/275-*.md, §4): §1 даёт сценарий и персону, §6 «После Apply» перечисляет наблюдаемый результат (толщина сразу видна, Boundary разрешает virtual, проём не двигается). Контент присутствует, просто размазан по двум разделам и не сведён в одну фразу без терминов реализации — граница между этим и полноценным замечанием тонкая, решил не заводить отдельным пунктом поверх H1/M1–M3, но авторам стоит это поправить попутно.
• Причина дефекта подтверждена документами, а не выдумана. Root-cause в §2 совпадает и с issue-аналитикой, и с docs/WALL-THICKNESS.md §9 («A precisely collinear room wall covering the same interval is cut as a composite; a crossing/nearby body is not») и docs/USER-GUIDE.ru.md:555 («Если независимая стена точно совпадает со стеной комнаты, House Plan использует её как явную привязку и прорезает единое составное тело») — то есть рендер/cut уже корректно строит составное тело, а баг именно там, где указано: thickness edit, _boundaryBlocked(), Optimize dedup. Ни одна упомянутая функция/константа не выдумана — все существуют в src/. проверено чтением, не исполнением.
• Условие безопасной канонизации (§4) консервативно и покрыто негативной матрицей (AC2): partial/longer/shorter/composite/non-shared/virtual/ different-cm/ambiguous-extra остаются без изменений. Это разумный default, не требующий отдельного вопроса владельцу — граница технической, а не продуктовой ответственности (§7.1).
• Скоуп согласован с docs/SCOPE.md. Комментарий аналитики верно относит задачу к J4/J6; View mode не получает новых интеракций, touch-контракт не расширяется (Plan editor остаётся desktop-first) — соответствует TOUCH-SUPPORT.md и §7.1 разделу 11 самого ТЗ.
• Связанные issue корректно разведены. #277 (Resize ambiguity) и #278 (общий wall-union fallback при исчезновении кладки) верно исключены из скоупа (§8) и совпадают с формулировками в комментарии владельца к #276.
• Все AC1–AC14 указывают способ доказательства (unit/negative-matrix/ golden/smoke/benchmark/review), ни один не оставлен без «Доказательство».
• Производительность и touch закрывают DoR-пункты явными числами (§10: ≤15% p95 / ≤25 ms) и явным «новых жестов нет» (§11) — нет необходимости возвращать как замечание.
• Preflight-механизм (#199), на который опирается §4.8 и AC9, реально существует и тестируем (src/plan-geometry-preflight.ts, test/plan-geometry-preflight.test.mjs) — проверено чтением, план «Injectable unit» правдоподобен.
• i18n: формат отчёта (два RU/EN счётчика, нулевые строки скрыты) совпадает с уже принятым паттерном Optimize preview в USER-GUIDE.ru.md. Конкретные ключи (gs.*) не названы буквально — это Low, не блокирует; автор решает при реализации.

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

• Не запускал npx tsc --noEmit / npm test / npm run build / node scripts/check-docs.mjs — диапазон коммита r1 не трогает src/** и не является кодом; гейты реализации к спек-ревью неприменимы, продуктовый код не менялся.
• Не запускал browser smoke / golden / инварианты модели — geometry/wall/ layout ещё не менялись, это фикстуры и код будущей реализации.
• Не проверял реальный пользовательский экспорт, упомянутый в issue (владелец не приложил его из-за пользовательских данных) — верю описанию из комментария аналитики, синтетическая fixture в ТЗ (§7, §13) — это корректная замена по правилам issue.
• Не оценивал сложность/трудозатраты реализации (7/10 в аналитике) — вне компетенции спек-ревью.

Вывод

High-находка (H1) блокирует переход в S5-ready: контракт Redo для Optimize Undo не существует и не заявлен как новая работа, из-за чего AC7 недоказуем как написано. Три Medium-находки (M1–M3) — все в скоупе задачи и чинятся тем же автором в этом же ТЗ без нового issue: отсутствующий раздел «Риски», отсутствующий список затронутых файлов/модулей (оба — обязательные пункты DoR §2.5) и ссылка на несуществующий docs/PLAN-OPTIMIZE.md. Открытых продуктовых вопросов владельцу нет — все находки технические, снимаются автором ТЗ.