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

# SPEC-REVIEW-290-r1

- **Issue:** https://github.com/Matysh/houseplan-card/issues/290
- **Этап:** spec (PROCESS.md §2.4)
- **Заход:** r1 · блокирующих циклов израсходовано 0 из 4
- **Ревьюируемый артефакт:** `docs/specs/290-near-axis-authoring-and-repair.md`,
  ветка `issue/290-near-axis-authoring-repair`, коммит `dcdb7565`
- **Вердикт:** жёлтый

## Скоуп ревью

Issue не помечен `small`/`trivial` → обычный трек, ТЗ обязано жить файлом в
`docs/specs/`. Диапазон изменений от `origin/dev` — ровно один файл
(`docs/specs/290-near-axis-authoring-and-repair.md`, класс C), что и требуется
на этапе `S4-spec-review`: продуктовый код не тронут.

Задача — часть цепочки #284 (канонизация координат записи) → #279 (устойчивый
рендер почти-ортогонального T-стыка) → #290 (не создавать такую геометрию
молча и дать явный способ её исправить). Продуктовая рамка по `docs/SCOPE.md`
— J6 («Keep the plan true as the home evolves»): администратор должен видеть и
контролировать изменение геометрии, Optimize обязан явно сообщать о
lossy-исправлениях. Это совпадает с собственной оценкой аналитика в issue.

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

1. Прочитаны `docs/SCOPE.md`, `PROCESS.md` (жизненный цикл, §7.1, §8),
   `AGENTS.md`.
2. Прочитано тело issue #290 целиком и все три комментария (аналитика,
   продуктовые вопросы с defaults, ссылка на готовое ТЗ).
3. Прочитан весь текст `docs/specs/290-near-axis-authoring-and-repair.md`
   (313 строк).
4. Сверено с каноническими документами задетых подсистем: `docs/CANVAS.md`
   (снап/Shift/hover-resolver, барьер канонизации координат записи, «Оптимизировать
   планы»), `docs/RESIZE.md` (safe-resize contract, eligibility, pure pipeline,
   Undo), `docs/WALL-THICKNESS.md` (модель `walls[]`, `wallKey`, rekey после
   Resize/Optimize), `docs/USER-GUIDE.ru.md` (текущий текст диалога
   «Оптимизировать планы» и его таблица операций).
5. Прочитаны связанные issue #279 (полная переписка причины/фикстуры),
   #277 (safe Resize), #248 (идемпотентность Optimize), #284 (канонизация
   записи) — все указаны в ТЗ как связанные.
6. Сверены существующие тестовые фикстуры: `test/fixtures/279-near-orthogonal-junction.json`,
   `test/fixtures/real-plan-second-floor.json`, `test/fixtures/coordinate-canonicalization.json`
   — на предмет соответствия тому, что AC4 называет «minimized fixture из #284».
7. Прочитан существующий продуктовый код на предмет уже введённой константы
   `MULTI_WALL_NEAR_ORTHOGONAL_MAX_DEGREES = 0.25` (`src/wall-thickness.ts:84`),
   чтобы проверить, не конфликтует ли предлагаемый общий `NEAR_AXIS_MAX_DEGREES`
   с уже существующим порогом того же значения.
8. Для сравнения формата прочитаны полностью аналогичные недавние ТЗ той же
   геометрической линии — `docs/specs/277-safe-resize.md` и
   `docs/specs/279-near-orthogonal-junction.md` — как ориентир на «Риски»,
   «Rollback» и формат таблицы AC/Доказательство, принятый в этом репозитории.

Гейты (`typecheck`/`test`/`build`) не запускались: на этапе `spec` продуктовый
код не менялся, диапазон diff состоит из одного файла документации, гоны не
применимы к этому этапу.

## Находки

### Medium (в скоупе задачи — чинится в этом же ТЗ)

**M1. Отсутствуют обязательные разделы §7.1 «риски» и «откат».**

- **Файл:** `docs/specs/290-near-axis-authoring-and-repair.md`
- **PROCESS.md §7.1:** «Обязательные разделы ТЗ: сценарий · что человек увидит
  до и после · проблема · скоуп и не-скоуп · контракт поведения · UX · модель
  данных и миграция · i18n · критерии приёмки AC1…ACn с указанием
  доказательства · план автотестов · риски · откат · release-артефакты.»
- **Что не так:** в документе нет ни одного раздела «Риски» и ни одного
  раздела/абзаца «Откат/Rollback». Единственное упоминание слова «риск» — в
  шапке, это число самооценки аналитика (9/10), не анализ. Раздел 11
  («Release») описывает только трейлеры коммита и требование Linux-артефакта
  для golden — про то, как вернуть изменение назад (revert commit? нужен ли
  Labs-флаг? что произойдёт со старыми планами, если поведение окажется
  ошибочным и придётся откатывать) не сказано ни слова.
- **Почему это не мелочь:** это не формальность, а действующая практика в этой
  же геометрической линии задач. Оба непосредственных предшественника —
  `docs/specs/277-safe-resize.md` (§12.1 «Риски и меры», таблица из 10 строк, и
  §17 «Release-артефакты и rollback» с явным «Rollback — revert implementation
  commit... После rollback вернётся широкий нестабильный UI, поэтому release
  rollback должен быть полным и сопровождаться предупреждением») и
  `docs/specs/279-near-orthogonal-junction.md` (§5 «Совместимость, риски и
  performance») — оба содержат этот анализ. У #290 риск выше, чем у #277: здесь
  вводится **автоматическое изменение геометрии при рисовании без обходного
  модификатора** (§5.1 ТЗ, п. «Специального modifier bypass нет») — то есть
  редактор будет менять то, что нарисовал пользователь, без явного согласия в
  моменте. Ровно такой случай (переопределение поведения без spec на риски)
  — то, ради чего DoR требует «влияние… названо (или явно «нет»)» и «риски
  перечислены» (PROCESS.md §2.5).
- **Воспроизведение:** `grep -niE "риск|откат|rollback"` по файлу ТЗ (кроме
  строки самооценки в шапке и одного упоминания «downgrade не требует
  migration» в §9) не находит содержательного раздела.
- **Требуется:** добавить раздел «Риски» (минимум: ложные срабатывания
  auto-straightening на длинных почти-диагональных стенах около границы
  0.25°; двойной подсчёт shared-стены между Optimize-кандидатами; конфликт с
  параллельно идущими #276/#278/#281, которые тоже трогают Optimize-геометрию,
  как это явно оговорено в #277 §12.1) и раздел «Откат» (что происходит, если
  после релиза найден дефект: revert коммита, нет миграции схемы, старые планы
  с уступом остаются как есть до следующего Optimize).

**M2. AC исходного issue про `npm run invariants` на реальных данных и
видимое снижение числа почти-ортогональных узлов не перенесён в ТЗ.**

- **Файл:** `docs/specs/290-near-axis-authoring-and-repair.md`, раздел 8
  (AC1–AC10), в сравнении с AC6 тела issue #290.
- **Что не так:** issue формулирует шестой критерий приёмки явно: «`npm run
  invariants` на обоих реальных планах — код 0; после выпрямления уступа число
  почти-ортогональных узлов уменьшается, и это видно в отчёте Optimize». В ТЗ
  этому соответствует только AC5, но AC5 требует нулевых нарушений
  `checkWallKeys`/`checkMixedRoleRecords`/preflight на **минимизированной
  фикстуре**, а не на «обоих реальных планах», и не требует показать
  уменьшение числа почти-ортогональных узлов ни в выводе
  `scripts/model-invariants.mjs`, ни в `OptimizeReport`. Раздел 10
  («Ожидаемые файлы» → Tests/evidence) тоже не называет
  `node scripts/model-invariants.mjs --config <...>` явно, хотя PROCESS.md §8
  делает эту команду обязательной ровно для диффов, трогающих геометрию и
  ссылки на неё (edges, `wall thickness records`, `open_spans`) — а это ядро
  задачи #290.
- **Почему это не формальность:** минимизированная фикстура доказывает, что
  механизм работает на сконструированном случае; она не доказывает, что на
  реальном плане (с сотнями узлов, где уже случались #253/#258/#259) число
  почти-ортогональных узлов действительно падает, а не создаётся новый класс
  случаев в другом месте плана. Именно необходимость такой проверки на
  реальных данных и породила #279 (реальный экспорт `44.json`) и практику
  «второго реального плана» в текущей серии коммитов ветки
  (`test: add a second real plan to the masonry gate`,
  `test: one thickness record must not describe two wall roles`) — то есть
  инфраструктура для анонимизированной проверки на реальных/близких к реальным
  данным в этом репозитории уже есть и используется соседними задачами.
- **Требуется:** либо явно перенести требование issue в AC (анонимизированная
  фикстура, произведённая из реального плана, а не полностью синтетическая
  «minimized»; факт снижения near-orthogonal-count через
  `scripts/model-invariants.mjs` до/после Optimize), либо явно и обоснованно
  сузить критерий с указанием, почему полный реальный план как источник
  проверки не нужен — так же, как #277 §16 прямо объясняет использование
  анонимизированной регрессионной фикстуры вместо сырого экспорта. Молчаливое
  сужение критерия приёмки, сформулированного в issue, без объяснения —
  ровно тот случай, который ревью обязано ловить.

### Low (снимается либо правится, с записью)

**L1. AC4 неточно называет источник fixture.**

- **Файл:** `docs/specs/290-near-axis-authoring-and-repair.md`, AC4: «Minimized
  fixture из #284 содержит duplicated shared physical edge `316×1`».
- **Наблюдение:** узел, который АС4 описывает (`316×1`, координаты
  `(-1.670833333, 2.95)`/`(-0.354166667, 2.954166667)`), — это **буквально**
  `test/fixtures/279-near-orthogonal-junction.json` (сверено байт в байт: тот
  же `node`, те же координаты стен). Issue #284 — про барьер канонизации
  координат записи (`snap = v => Math.round(v*240)/240`), отдельная задача про
  другой механизм; она не производила эту fixture. Вероятная причина —
  смешение «issue #284 как общее исследование, откуда взят пример» и «issue
  #279 как задача, где эта fixture уже закоммичена». Это не блокирует
  реализацию (fixture физически существует и полностью подходит под описание
  AC4), но при написании автотеста первое, что сделает исполнитель — будет
  искать/создавать fixture «из #284», где её нет.
- **Решение ревьюера:** Low, не эскалируется. Достаточно поправить ссылку на
  `test/fixtures/279-near-orthogonal-junction.json` (или явно сказать «тот же
  случай, что и в #279») при следующей правке файла; отдельного цикла ради
  этого не требуется.

## Что проверено и признано корректным

- **Обязательные продуктовые разделы §7.1** («сценарий», «что человек
  увидит») присутствуют и содержательны (разделы 1 и 3); ТЗ отвечает на оба
  вопроса без терминов реализации в пользовательской части.
- **Продуктовые вопросы владельцу закрыты.** Ровно три вопроса
  (выравнивать/предупреждать, поведение Optimize, единый допуск) заданы одним
  комментарием с defaults, каждый — что человек видит/делает, не техническое
  решение, выданное за продуктовое. Раздел 2 ТЗ фиксирует все три ответа
  дословно, раздел «Открытых продуктовых вопросов нет» подтверждён — при
  чтении issue и ТЗ вместе противоречий не найдено.
- **Единый допуск и его источник (раздел 4)** сформулирован проверяемо:
  включительная граница `0.25°`, `316×1` классифицируется, `316×2` — нет,
  zero-length исключён, инвариантность к endpoint order/winding/scale/theme
  названа явно. AC1 требует единый source threshold и source-guard против
  отдельных литералов `0.25` — реализуемо и falsifiable (мутант «порог ниже
  `0.181315°`» и «strict `<`» в AC9 корректно бьют по обеим сторонам границы).
  То, что предлагается использовать *то же числовое значение*, что уже занято
  `MULTI_WALL_NEAR_ORTHOGONAL_MAX_DEGREES` в `src/wall-thickness.ts:84` для
  другого геометрического сравнения (угол между двумя лучами, а не отклонение
  одного луча от глобальной оси) — техническое решение, а не путаница: раздел
  4 явно оговаривает, что renderer может продолжать использовать
  «эквивалентный dot/sine form for orthogonal pairs», то есть общий источник —
  это значение допуска, а не буквально один и тот же exported symbol. Это
  подпадает под «принято предположительно, поменять свободно» и не требует
  отдельного продуктового решения.
- **Негативный контракт (диагонали не трогаются)** описан симметрично
  положительному на всех трёх путях (Walls, Resize, Optimize) и покрыт
  отдельным AC6 плюс мутантами AC9 «считать room copies как две стены» /
  «repair only one owner shared wall», что закрывает риск двойного счёта
  расшаренной стены — именно то, из-за чего первоначальный AC issue выделял
  этот пункт отдельно.
- **Совместимость с существующими контрактами подсистем.** Раздел 5.2
  корректно наследует существующий контракт `docs/RESIZE.md` («только
  numerically horizontal/vertical edge eligible», epsilon поглощает только
  storage noise) и не пытается расширить Resize eligibility на near-axis
  случаи — вместо этого явно направляет их через Optimize (раздел 12, пункт
  2), что не противоречит ни `RESIZE.md`, ни `WALL-THICKNESS.md`. Раздел 6.1
  корректно ссылается на существующий канонический механизм ключей толщины
  (`wallKey`, exact-span lookup) из `WALL-THICKNESS.md` вместо изобретения
  нового формата хранения — толщина не становится отдельным «candidate»,
  а reprojection'ится из исправленной геометрии существующим pipeline, что
  соответствует модели `WALL-THICKNESS.md` («key is computed from
  lattice-stable endpoints»).
- **Touch/производительность (раздел 9)** соответствует терминологии
  `docs/TOUCH-SUPPORT.md` дословно («View/kiosk rendering fully supported» ↔
  «Fully supported» в таблице `TOUCH-SUPPORT.md`), не расширяет editor parity
  на touch сверх «best effort», не блокирует pinch/pan/pointercancel —
  соответствует установленному продуктовому решению («editors are
  desktop-first»). Заявление «Authoring classifier `O(1)`» и «Optimize pass
  линейный по edges» не противоречит существующим performance-бюджетам
  `RESIZE.md` и не заявляет числ, которые нечем будет доказать: сохранена
  ссылка на «full performance gate обязателен».
- **Никаких догадок, выданных за факт, не найдено** среди технических
  утверждений о **существующем** поведении: каждая проверенная ссылка на
  текущий контракт (Shift 45°, safe Resize eligibility, `wallKey`,
  барьер канонизации записи #284) точно соответствует канону в `CANVAS.md` /
  `RESIZE.md` / `WALL-THICKNESS.md`. Пункт раздела 12 («Принятые технические
  предположения») корректно ограничен вопросами, которые пользователь не
  наблюдает (какой endpoint двигается при равной безопасности кандидатов,
  что unsafe-repair не обязан чинить любой ценой) — то есть именно тем
  классом решений, которые PROCESS.md §7.1 разрешает решать автору/ревьюеру
  без владельца.
- **i18n, DoR-чеклист.** Раздел 10 называет оба файла (`en.json`/`ru.json`);
  конкретные ключи на этапе ТЗ не требуются — сверено с #277/#279, которые на
  этом же этапе тоже ограничиваются общей фразой «RU/EN i18n» без перечисления
  ключей.
- **Файл ТЗ лежит в правильном месте и правильно назван** —
  `docs/specs/290-near-axis-authoring-and-repair.md`, номер совпадает с
  номером issue, что соответствует PROCESS.md §2.3.

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

- **Не проверял, что перечисленные в ТЗ файлы (`src/resize.ts`,
  `src/align-grid.ts`/`src/plan-optimizer.ts`, `src/houseplan-card.ts`)
  действительно являются правильными точками внедрения** — на этапе ТЗ кода
  ещё нет, а раздел 10 явно помечен как «Ожидаемые файлы», то есть прогноз, а
  не обязательство; проверка предметна для код-ревью.
- **Не оценивал реальную достижимость перфоманс-бюджетов** («Authoring
  classifier O(1)», сохранение p95 из `RESIZE.md`) — это будет проверяться
  performance-гейтом перед бетой, не на этапе спецификации.
- **Не проверял мутационный registry** (AC9) на предмет технической
  реализуемости каждого конкретного мутанта в текущей кодовой базе — на этом
  этапе mutation ids не существуют, это работа код-ревью.
- **Не запускал никаких гейтов** (`typecheck`/`test`/`build`) — diff этого
  раунда состоит из одного файла документации класса C, гейты к этапу spec не
  относятся (см. «Как проверялось»).
- **Не проверял docs/CONFIG-COMPATIBILITY.md registry на конкретные записи** —
  ТЗ утверждает отсутствие изменений схемы (раздел 9), новых persisted-полей
  нет, поэтому реестр совместимости не должен получать новых записей; это
  утверждение принято на веру как техническое (не продуктовое) без
  дополнительной проверки скрипта `config-field-registry.mjs`, так как задача
  явно заявляет «schema не меняется».

## Вывод

Продуктовая часть ТЗ (сценарий, видимый результат, продуктовые решения
владельца, критерии приёмки как таковые, негативный контракт для диагоналей)
выполнена тщательно и без домыслов, выданных за факт. Причина жёлтого вердикта
— два содержательных пробела в обязательных разделах и трассируемости AC:
отсутствие анализа рисков и плана отката (§7.1), и молчаливое сужение AC6
issue (проверка на реальных данных, видимое снижение числа
почти-ортогональных узлов) без объяснения. Оба пункта — Medium в скоупе этой
же задачи и чинятся правкой того же файла, без нового issue и без обращения к
владельцу.