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

SPEC-REVIEW-289-r1

• Issue: https://github.com/Matysh/houseplan-card/issues/289
• Артефакт ТЗ: docs/specs/289-no-mixed-role-resize.md
• Ветка/коммит: issue/289-no-mixed-role-resize @ 5e169f48 (origin/dev + 1 коммит, подтверждено git diff origin/dev..HEAD --stat — единственное изменение это сам файл ТЗ, 234 строки; продуктовый код не тронут)
• Заход: r1 (первый прогон, раздел «дельта/унаследовано» не применяется — §2.10 PROCESS.md)
• Вердикт: жёлтый · High: 0 · Medium: 3 · Low: 2

Скоуп ревью

ТЗ описывает продуктовое поведение: Resize не должен позволять жесту превратить часть ранее общей боковой стены в наружную (или наоборот) без разреза записи толщины — вместо этого рукоятка должна быть заранее disabled с понятной причиной. Задача не small (меток small/trivial на issue нет), значит ТЗ обязано жить файлом в docs/specs/ — это выполнено.

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

1. docs/SCOPE.md, AGENTS.md, PROCESS.md — рамка процесса и продукта.
2. Тело issue #289 и все три комментария (аналитика, продуктовый вопрос Q1 с default, готовность ТЗ) — сверил, что ТЗ реализует именно принятый default («запретить частичный сдвиг», не «разрезать запись»).
3. docs/RESIZE.md и docs/WALL-THICKNESS.md — канон подсистемы, на предмет расхождений терминологии и повторного изобретения уже существующих понятий.
4. docs/USER-GUIDE.ru.md — сверка терминологии интерфейса (раздел «Resize», строки 458–474).
5. Само ТЗ (docs/specs/289-no-mixed-role-resize.md), построчно, с проверкой каждого утверждения о текущем поведении по коду:
   • src/resize.ts: resolveSafeResize() (строки 629–728) и validateSafeResize() (791–886) — чтобы проверить заявление §1 «текущий resolver проверяет ownership только moving edge, не двух side edges»;
   • scripts/model-invariants.mjs: checkMixedRoleRecords, checkWallKeys, checkWallRecordsPreserved, checkReferences, checkPhysicalGeometry — чтобы проверить, что все инструменты, названные в AC5, существуют и возвращают то, что от них ожидает ТЗ (в частности, что checkWallKeys действительно никогда не кладёт результат в violations, а только в notes — семантика «ноль нарушений» в AC5 подтвердилась);
   • src/i18n/en.json / ru.json — существование ключей resize.disabled.partial-shared и resize.commit_failed, чтобы отличить переиспользование от изобретённого нового поведения;
   • test/fixtures/resize-safe-regression.json — существующая фикстура, упомянутая в docs/RESIZE.md, для понимания, что #289 расширяет уже обжитой класс тестов, а не создаёт первую регрессионную фикстуру с нуля.
6. Не прогонялись typecheck/test/build/инварианты: диапазон коммитов на ветке не содержит продуктового кода (см. п. «Ветка/коммит» выше) — гейты класса A/B не применимы к чисто документационному коммиту на этапе ТЗ.

Находки

M1 (Medium, в скоупе) — раздел «Риски» отсутствует полностью

§7.1 PROCESS.md перечисляет «риски» как обязательный раздел ТЗ; DoR (§2.5) отдельно требует «риски перечислены» до перехода в «Готово к разработке». В документе слово «риск» встречается только один раз — в шапке, как оценочная цифра S2-аналитики («риск 9/10»), скопированная из комментария аналитика. Ни одного предложения о том, какие риски несёт именно это решение — например, что более строгий ownership-анализ может задеть легитимные resize-жесты на грани эвристики (ложноположительный partial-shared), или что directed-clamp по двум side edges одновременно — новый код на горячем пути pointermove, — не написано. Раздел docs/RESIZE.md §Performance частично закрывает производительность («Pointermove не получает новый глобальный O(R×E) анализ»), но это не заменяет отдельный разбор рисков внедрения самой проверки.

Как закрыть: добавить раздел «Риски» — минимум: риск чрезмерно строгого disable (ложноположительные срабатывания на legit-жестах, покрывается AC3/AC4/ AC8), риск регресса производительности на большом плане (покрывается docs/RESIZE.md p95-бюджетами, но это нужно явно связать), риск того, что ownership-профиль устареет при вложенном/составном изменении темы (multiple- rooms уже existing stop).

M2 (Medium, в скоупе) — раздел «Откат» отсутствует полностью

Тот же §7.1 требует явный раздел «откат»; DoR требует «откат: как выключить или вернуть назад (флаг Labs, обратная миграция)». В документе нет ни слова «откат», ни эквивалентного рассуждения. Поскольку задача не меняет схему/ миграцию (§7 «Persisted schema/model version не меняются»), ответ, вероятно, тривиален — «отката как флага не требуется, откат это revert коммита, т.к. persisted-данные не переписываются и разрешённые сценарии не деградируют» — но это решение должно быть записано явно, а не додумываться ревьюером или разработчиком.

M3 (Medium, в скоупе) — 6 из 9 AC не указывают способ доказательства

§7.1 требует «критерии приёмки AC1…ACn с указанием доказательства»; DoR дублирует это отдельным пунктом. AC7 явно называет смок (demo/smoke_room_resize.mjs), AC8 явно называет мутационный тест, AC9 явно перечисляет гейты — но AC1–AC6 описывают только ожидаемое поведение (что должна вернуть функция, что должно остаться неизменным), не говоря, каким именно тестом/каким инструментом это доказывается. Способ вывести это из контекста существует (все они — чистые функции, естественная площадка — test/resize.test.mjs, как и для существующих сценариев в docs/RESIZE.md §Verification), поэтому неоднозначности в реализуемости нет — но формальное требование не выполнено систематически, не разово, и я обязан отметить это явно, а не «додумать за автора». Тривиально чинится: одна строка на AC вида «Доказательство: unit, test/resize.test.mjs» / «инвариант, npm run invariants».

Итог по Medium: все три — редакционные/структурные пробелы конкретно в этом документе, ни один не требует нового продуктового решения владельца и не меняет контракт §2/§4 — правятся тем же автором в рамках этого же issue, отдельный issue не заводится (#202).

L1 (Low) — терминология «рукоятка» вместо канонической «ручка»

docs/USER-GUIDE.ru.md:467 и уже существующие строки i18n (title.markup_resize, markup.hint_resize) называют элемент управления Resize «ручка». Слово «рукоятка» в репозитории отсутствует везде, кроме этого нового ТЗ, где оно использовано 5 раз (§2, §3, §4.2×3). AGENTS.md прямо требует: «для работы, меняющей видимое поведение, читать docs/USER-GUIDE.ru.md — терминология интерфейса берётся оттуда, а не изобретается, или UI начинает говорить на языке разработчика». Сам disabled- текст в AC2 («Нельзя сдвинуть только часть общей стены») дословно совпадает с решением владельца и дефекта не содержит — расхождение только в описательной прозе ТЗ, но именно она станет источником терминологии для реализации и код-ревью. Рекомендация: заменить «рукоятка» → «ручка» по всему документу.

L2 (Low) — i18n-ключ не назван по имени

§10, предположение 1: «существующий reason key partial-shared переиспользуется» — это ключ значения reason в SafeResizeResolution (src/resize.ts:37), а не сам i18n-ключ перевода. Реальный ключ перевода, который получит новый текст — resize.disabled.partial-shared (подтверждено в src/i18n/en.json:90, ru.json:90) — нигде в документе не назван буквально. DoR требует «i18n: ключи en + ru перечислены». Поскольку ключ уже существует (не создаётся новый), риск неоднозначности невелик, но раздел должен явно назвать его, а не полагаться на то, что разработчик найдёт его сам по строке reason.

Что проверено и корректно (не находка, а подтверждение)

• Причина дефекта (§1) фактически точна. Прочитал resolveSafeResize() целиком: ownership-проверка (partial/unequal/exact, строки 660–677) выполняется только для moving edge. validateSafeResize() проверяет для side edges лишь ось (sideAxis) и посадку проёмов (sideOpeningFits), но не сравнивает получившийся side-интервал с геометрией соседних комнат. Значит утверждение «resolver не доказывает роль side edges после изменения длины» — не догадка, а точное описание кода.
• Симметричность контракта §4.2 проверена геометрически. Прогнал вручную сценарий из репро: при удлинении side-стены новый хвост становится наружным (mixed-role на записи этой комнаты) — очевидная часть. Менее очевидная — что при укорачивании (обратное направление) mixed-role возникает не у текущей комнаты, а у соседней (её длинный shared-участок теряет часть партнёра и должен разделиться на shared+outer). Именно это покрывает второй пункт §4.2: «оставляет продолжение у B, которым A больше не владеет». Формулировка «оба направления небезопасны» в exact-репро — корректна, не преувеличение.
• Инструменты и ключи, упомянутые в AC, существуют и делают ровно то, что написано: checkMixedRoleRecords, checkWallRecordsPreserved, checkWallKeys, checkReferences, checkPhysicalGeometry (scripts/model-invariants.mjs), resize.commit_failed (src/houseplan-card.ts:8636, оба i18n-файла). Ничего не изобретено.
• Скоуп/не-скоуп (§5) не расползается: явно исключены разрез записи, смена толщины, каскад топологии, рефактор #264, ретро-починка через Optimize, #288 и #290 — совпадает с картиной, полученной из истории issue (дубликаты проверены аналитиком: #233, #253, #264, #277, #281, #287).
• Продуктовое решение (§2) совпадает слово в слово с ответом владельца на Q1 (default «запретить», без auto-split, с текстом «Нельзя сдвинуть только часть общей стены») — открытых продуктовых вопросов действительно не осталось, значит вынесение владельцу новых вопросов не требуется.
• Терминология вне «рукоятки» (endpoint-to-endpoint, geometry preflight, safety floor, centreline) сверена с RESIZE.md/WALL-THICKNESS.md/ TOUCH-SUPPORT.md/ARCHITECTURE.md — совпадает с каноном, ничего не изобретено заново.
• Совместимость (§7): утверждение «persisted schema/model version не меняются» соответствует docs/CONFIG-COMPATIBILITY.md-классу решений — задача не требует миграции, что снимает часть требований DoR (но не заменяет отсутствующий явный раздел «откат», см. M2).

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

• Продуктовый код и тесты — на этой ветке их не существует (это стадия ТЗ, git diff origin/dev..HEAD содержит только сам файл спецификации). Гейты typecheck/test/build/invariants не прогонялись: неприменимо к чисто документационному коммиту, и §1 PROCESS.md не требует их для класса C.
• Английский текст disabled-причины — ТЗ говорит только «EN передаёт тот же смысл» и сознательно не фиксирует точную строку; это оставлено как редакционная свобода реализации (аналогично другим reason-текстам в en.json), не считаю это пробелом.
• Содержимое будущей анонимизированной фикстуры из #284 (файл ещё не создан) — не могу проверить, действительно ли она будет содержать узлы 928/971 и координаты y=3.866666667 → 4.045833333 из issue; это дело реализации и код-ревью, а не спецификации.
• Производительность на реальном плане владельца — числа p95 в docs/RESIZE.md не пересчитывались; спецификация лишь ссылается на них, что на этой стадии достаточно.

Итог

High: 0. Medium: 3 (M1 «Риски», M2 «Откат», M3 — доказательство по AC), все три — редакционные пробелы этого самого документа, чинятся автором ТЗ в рамках текущего issue без нового продуктового решения владельца. Low: 2 (терминология «рукоятка»/«ручка», явное имя i18n-ключа) — либо правятся тем же проходом, либо снимаются автором с запиской. Технический контракт (§2–§4), AC1–AC9 по существу и границы скоупа (§5) проверены точным чтением кода и канона и найдены корректными — рекомендую вернуть на правку только ради структурной полноты документа, не из-за ошибки в самом решении.