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

SPEC-REVIEW-316-r1

Issue: #316 · ТЗ: docs/specs/316-opening-host-auto-resolution.md · ветка issue/316-migration-auto-resolve · SHA материала ревью: 36f735ae (docs: spec #316 — migration auto-resolves opening-host conflicts). Трек: обычный (метка small отсутствует) → требуется файл ТЗ и отдельный документ ревью, что и сделано.

Скоуп

Владелец решил в чате (комментарий S2→S4, 2026-08-26): конфликт «проём ↔ нулевая стена» миграция v9 разрешает автоматически, рисование нигде не блокируется. Настоящее ТЗ формализует правила авто-разрешения (§3.1–3.4) и сужает контракт #306 §8.2 п.4. Отдельная задача #319 (бэкенд-гард против stale-клиента) прямо исключена из скоупа — правильно, это независимый инвариант.

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

Ревью документа без исполнения кода (стадия ТЗ, код ещё не написан — commit 36f735ae содержит только спецификацию). Проверено:

1. Полное чтение docs/SCOPE.md, AGENTS.md, PROCESS.md (см. системный промпт) — обязательные разделы §7.1 и чек-лист DoR §2.5 сверены построчно.
2. Тело issue #316 и оба комментария (аналитика с воспроизведением, решение владельца S2→S4) — сверено, что ТЗ не расходится с зафиксированной причиной и решением.
3. Чтение текущего (до фикса) src/wall-segment-model.ts: buildAtoms, resolveRoomOpeningHost, hostRoomOpenings, migrateSpace, commitWallSegmentModel — сверка каждого нормативного правила §3 ТЗ с реальным кодом, который оно должно изменить.
4. Проверка ссылок ТЗ на прежние документы: docs/specs/306-zero-thickness-walls.md §8.2 п.4 и п.8 (ровно то, что ТЗ #316 объявляет заменяемым/сужаемым — подтверждено построчно), docs/WALL-THICKNESS.md §9 (независимая кладка, opening cannot punch a coincident independent wall), issue #313 (полный текст).
5. Проверка мест использования resolveRoomOpeningHost в houseplan-card.ts (drag/placement путь, строки ~12680–12684 и ~12828–12834) — подтверждает claim §3.3 «picker/placement уже умеет переставлять безхостовый проём».
6. Проверка scripts/config-field-registry.mjs (запись spaces[].openings[].host=wall) и backend validation.py (vol.Optional("host")) — сверка, меняется ли контракт совместимости, который ТЗ должно менять/документировать.
7. Поиск i18n-ключей toast.zero_wall_migration_blocked / wall_model.reason.opening-host в src/i18n/{ru,en}.json — проверка, остаются ли они актуальны для пост-v9 fail-closed случая (AC5).
8. ls demo/smoke_*.mjs — проверка существующего покрытия по теме (нашёлся smoke_inert_openings.mjs, но по не относящемуся термину — см. находку L1).

Гейты typecheck/test/build не прогонялись: на этапе ТЗ продуктового кода ещё нет, диапазон изменений — исключительно docs/specs/316-*.md (класс C). Это не пропуск гейта — гейтов для класса C на этой стадии не предусмотрено.

Находки

M1 (Medium, в скоупе) — ТЗ не закрывает несколько обязательных разделов §7.1 / чек-листа DoR §2.5

Отсутствуют полностью, не как «неявно покрыто», а буквально нет ни строки:

• i18n — не сказано даже «изменений нет». Между тем это не тривиально: AC5 подразумевает, что wall_model.reason.opening-host и toast.zero_wall_migration_blocked остаются в строю для пост-v9 fail-closed случая — я проверил, ключи в ru.json/en.json есть и не тронуты, но ТЗ обязано сказать это явно, а не оставлять ревьюеру реконструировать.
• Release-артефакты — changelog RU+EN, документация, golden/скриншоты не упомянуты вовсе. Это не формальность: правило 3.1 меняет зонирование cm:0 относительно beta.3 (сам документ признаёт это в разделе «Риски»), то есть меняет видимую геометрию стен в местах с легаси-проёмами — а значит потенциально golden-эталоны, где такая геометрия зафиксирована. ТЗ не говорит, требуется ли пересъёмка/сверка golden, и не резервирует правку docs/CHANGELOG.md/docs/CHANGELOG.ru.md, хотя описанное поведение прямо user-visible (пользователь больше не видит блокирующий тост, комната рисуется).
• Затронутые файлы/модули — DoR §2.5 требует их перечисления (docs/specs/README.md дальше по цепочке это использует); в ТЗ нет списка (ожидаемо: wall-segment-model.ts, возможно scripts/config-field-registry.mjs, docs/specs/306-*.md cross-ref).
• Влияние на производительность и на touch — ни разу не названо, даже как «нет» с обоснованием. Оба пункта DoR §2.5 сформулированы как обязательные к явному ответу («или явно "нет"»), не как опциональные.
• Compatibility-поле по docs/CONFIG-COMPATIBILITY.md — ТЗ не упоминает этот документ вовсе, хотя правило 3.3 меняет реальный контракт совместимости: scripts/config-field-registry.mjs, запись spaces[].openings[].host=wall (строки 291–303), сейчас гласит «required for contour openings in model v8» и «materialize only when exactly one carrier is proven» — то есть текущий машиночитаемый канон прямо противоречит новому §3.3 («без host» становится валидным персистентным v9-состоянием при отсутствии кандидата). Правило «документация — в том же коммите, что поведение» (PROCESS.md, правило 11) требует, чтобы эта запись реестра тоже обновлялась; ТЗ должно было назвать это явно как часть контракта, а не оставить открытие ревьюеру.

Отдельно: раздел «принято предположительно, поменять свободно» (обязателен по PROCESS.md §7.1 для всего, что автор решает сам без вопроса владельцу) в документе отсутствует полностью, хотя решений уровня «непродуктовых, но не очевидных» несколько: порядок tie-break в 3.2 (текущий host → расстояние → cm → id), и — что важнее — семантика «инертного» проёма в 3.3 (проём остаётся в данных, но перестаёт резать стену/создавать тоннель) — это уже граничит с «что считать приемлемой деградацией», один из двух видов вопросов, которые процесс резервирует за владельцем (PROCESS.md §7.1). Формально владелец уже дал общую директиву «рисование нигде не блокируется», и 3.3 — разумное техническое следствие, но фиксация этого решения явным блоком (а не внутри нормативного правила) — то, что требует процесс, и то, что даёт ревьюеру предмет для несогласия, а не факт.

Почему Medium, а не High: ни один из этих пробелов не делает уже написанные правила §3 невыполнимыми или непроверяемыми — рассуждение корректно и обосновано кодом (проверено чтением wall-segment-model.ts, см. «Как проверялось» п.3–6). Но по букве DoR §2.5 «если хоть один пункт не выполнен — статус не "Готово к разработке"», и здесь не выполнено сразу пять пунктов чек-листа. Чинится в этом же ТЗ без изменения контракта §3 — ревизия 2 добавляет разделы, не переписывает правила.

M2 (Medium, в скоупе) — AC3 описывает фикстуру, не достижимую в названном ею механизме

AC3: «Два коллинеарных совпадающих кандидата (контурный + независимый, кейс #313)». Формулировка правила 3.2 сама ссылается на resolveRoomOpeningHost.eligible, а функция (проверено чтением src/wall-segment-model.ts:588–615) принимает единственный параметр segments: readonly WallSegmentEntry[] — это space.wall_segments, собранный buildAtoms только из полигонов комнат (контурные атомы). Независимая кладка (partitions, room_drafts, wall_columns) в эту коллекцию не попадает вообще, а hostRoomOpenings сама явно пропускает opening.host?.kind === 'partition' (строка 620) — партиционные проёмы резолвятся другим путём, не через это правило. Значит «контурный + независимый» кандидат для resolveRoomOpeningHost в принципе не может возникнуть так, как описано.

Ссылка на «кейс #313» тоже не подтверждает сценарий: issue #313 — это инструмент «Толщина» (_wallThickHit), не умеющий выбирать отдельно стоящие стены/драфты в UI; он не о неоднозначности хоста проёма и не про два коллинеарных кандидата в wall_segments. Единственная найденная опора для «coincident»-сценария — docs/WALL-THICKNESS.md §9 («opening cannot punch a coincident independent wall», строки 480–509, smoke_optimize_coincident_partition.mjs) — но это Optimize-конкретный путь материализации, отдельный от resolveRoomOpeningHost, и там для партиционных проёмов другой резолвер (host:{kind:'partition'}).

Реальный источник неоднозначности внутри resolveRoomOpeningHost скорее находится на стыке двух соседних контурных атомов (например, на границе смены толщины — smoke_wall_thickness_transition.mjs), где проём у самого стыка формально укладывается в допуск EPS/ GRID_STEP_N * 0.02 сразу для двух атомов. Это не то же самое, что заявлено в AC3.

Что нужно от автора: заменить фикстуру AC3 (и её обоснование) на реально достижимую внутри resolveRoomOpeningHost — два коллинеарных контурных атома на стыке (thickness-transition или аналогичный кейс), с корректной ссылкой на источник, либо явно показать код-путь, которым независимая кладка всё же попадает в segments (если такой существует и я его не нашёл — тогда снимаю находку).

Почему Medium: правило 3.2 (сам алгоритм tie-break) звучит разумно и тестируемо — есть исполнимая, реально достижимая фикстура для той же цели (стык двух контурных атомов). Дефект локален к описанию AC3, не к нормативному правилу.

L1 (Low) — коллизия термина «инертный»

§3.3 называет безхостовый проём «инертным» («проём... становится инертным: не создаёт тоннель/вырез/тело, не участвует в физике»). Термин уже занят: docs/UX-MODES.md (строки 18, 207) использует «inert» для конкретного контракта — блокировки взаимодействия в View/kiosk по lock guard, установленного docs/SCOPE.md. В коде есть отдельный смок demo/smoke_inert_openings.mjs, который проверяет именно View-инертность (pointer-events/cursor), а не отсутствие хоста — это подтверждено чтением файла. Новое состояние (проём без host, при этом по-прежнему интерактивный и перетаскиваемый в Plan mode — см. houseplan-card.ts:12680–12684) описывает нечто иное, и повторное использование того же русского слова создаёт риск, что будущий автор кода/теста перепутает два разных инварианта по имени.

Предложение: выбрать другой термин («безхостовый», «unhosted», «проём без носителя» — как и названо в остальном тексте ТЗ) и не использовать «инертный» применительно к этому состоянию.

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

• Причинно-следственная цепочка (§1) точно совпадает с воспроизведением из аналитического комментария владельца — не домысел, а прямая трассировка к commitWallSegmentModel/hostRoomOpenings в текущем коде.
• Границы (§2): корректно и дословно сверено с #306 §8.2 — заменяется ровно пункт 4 («legacy-конфликт... блокирует миграцию всего пространства»), пункты 1–3 (picker не предлагает 0 как host, запрет перевода host-атома в 0, отсутствие tunnel/fill у нулевой стены) и пункт 7 (§8, строка 68: «новый проём на нулевой стене запрещён») остаются в силе как пост-миграционные — согласуется с исходным текстом #306.
• Правило 3.1 (проём удерживает стену) — физический смысл обоснован, критерий (интервал проёма пересекает интервал атома, допуск GRID_STEP_N * 0.02, тот же угловой критерий) идентичен уже существующему eligible() в resolveRoomOpeningHost — заимствование проверенного критерия, а не новое изобретение. Технически потребует перестановки порядка вычислений в buildAtoms (сейчас cuts считаются до того, как известны cm/host), но это вопрос реализации, не корректности ТЗ.
• Правило 3.3 (проём без кандидатов → безхостовое состояние, рендер по x/y) — подтверждено чтением space-render.ts:285 и plan-geometry-preflight.ts:224/276: обе точки уже трактуют !opening.host как проходной случай («return [opening]»/«return [fallback]»), то есть рендер по x/y для безхостового проёма — не придуманное поведение, а уже существующий код-путь. Claim про picker/placement также подтверждён (см. «Как проверялось» п.5).
• AC1, AC2, AC4–AC6 — сформулированы однозначно, с указанным способом доказательства (smoke/unit/backend), фикстуры проверяемы по описанному коду.
• Обратной совместимости данных, уже мигрировавших на beta.3, дано явное и честное признание в разделе «Риски» — без попытки выдать частичный охват за полный.
• Откат (§6) конкретен и проверяем: ревёрт ветки восстанавливает прежнее поведение, уже мигрировавшие v9-документы остаются валидными.

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

• Не проверял осуществимость реализации на уровне алгоритма (порядок вычислений в buildAtoms/hostRoomOpenings для правил 3.1–3.3) — это задача автора кода, не предмет ревью ТЗ; я лишь убедился, что используемые в правилах критерии (допуски, угловой тест) уже есть в кодовой базе и не придуманы с нуля.
• Не прогонял никаких гейтов (typecheck/test/build/смоки/golden) — на этой стадии продуктового кода нет, класс изменений C (документация), гейты для класса C не предусмотрены до кода.
• Не проверял #319 (бэкенд-гард) — прямо исключён из скоупа этим ТЗ и корректно помечен как отдельная задача.
• Не оценивал точную реализуемость AC6 (байтовая идемпотентность) — доверяю существующему паттерну (commitWallSegmentModel уже задуман идемпотентным для Optimize, судя по комментариям в коде), предметно не проверял иначе как чтением.

Вывод

High-находок нет. M1 и M2 — в скоупе задачи, чинятся в этом же ТЗ без пересмотра нормативных правил §3 (кроме фикстуры AC3). Вердикт — жёлтый, документ возвращается автору на ревизию 2.