From 8877e8c6d6da95fcc7248a7a667a730213ec413d Mon Sep 17 00:00:00 2001 From: "claude[bot]" <209825114+claude[bot]@users.noreply.github.com> Date: Mon, 24 Aug 2026 10:48:39 +0000 Subject: [PATCH] docs: review document for #289 Issue: #289 User-Visible: no --- docs/reviews/SPEC-REVIEW-289-r1.md | 197 +++++++++++++++++++++++++++++ 1 file changed, 197 insertions(+) create mode 100644 docs/reviews/SPEC-REVIEW-289-r1.md diff --git a/docs/reviews/SPEC-REVIEW-289-r1.md b/docs/reviews/SPEC-REVIEW-289-r1.md new file mode 100644 index 00000000..7ce6f21e --- /dev/null +++ b/docs/reviews/SPEC-REVIEW-289-r1.md @@ -0,0 +1,197 @@ +# 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) проверены точным чтением кода и +канона и найдены корректными — рекомендую вернуть на правку только ради +структурной полноты документа, не из-за ошибки в самом решении.