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

SPEC-REVIEW-294-r1

• Issue: https://github.com/Matysh/houseplan-card/issues/294
• Этап: ревью ТЗ (PROCESS.md §2.4)
• Заход: r1 · блокирующих циклов израсходовано 0/4 → 1/4 после этого вердикта
• Ревьюер: Claude (роль «ревьюер ТЗ», сессия отдельна от автора)
• Предмет ревью: docs/specs/294-wall-esc-detach.md на SHA 8e86b0a5 (ветка issue/294-wall-esc-detach), тело issue #294 и оба комментария аналитики/хендоффа автора.
• Трек: обычный (не small) — верно: метка small на issue отсутствует, спецификация оформлена файлом, как и требует §5.

Скоуп

Первый заход, дельты нет — разбор полный по §2.4/§7.1: продуктовая рамка, однозначность контракта Esc для активной цепочки стен, полнота AC и их доказуемость, отсутствие выданных за факт догадок, соответствие docs/USER-GUIDE*.md и терминологии SCOPE/UX-MODES.

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

1. Прочитаны docs/SCOPE.md, AGENTS.md, PROCESS.md (§1–§9, §7.1 отдельно).
2. Прочитаны тело issue #294 и все три комментария (аналитика, «Взял», хендофф автора).
3. Прочитан docs/specs/294-wall-esc-detach.md целиком на SHA 8e86b0a5.
4. Утверждения «Подтверждение по коду» из аналитики и §1/§3 ТЗ о текущем поведении сверены с реальным исходником на той же ветке (src/houseplan-card.ts, обработчик _onKey, _finishWallChain, _undoPoint, _undoActiveDraftPoint, _resumeLastDraft, _resumeDraftBySpace, _activateMarkupTool) — все технические утверждения спецификации подтверждаются кодом, ни одно не является непомеченной догадкой.
5. Сверены docs/USER-GUIDE.ru.md и docs/USER-GUIDE.md на предмет текущей формулировки контракта Esc/Ctrl+Z для инструмента «Стены»/Draw, чтобы проверить полноту AC7 и раздела 5 ТЗ.
6. docs/TOUCH-SUPPORT.md и docs/UX-MODES.md проверены на отсутствие противоречащих утверждений о touch/лестнице Escape — противоречий нет.
7. Гейты (typecheck/test/build/check-docs) не запускались: изменения этого раунда — только docs/specs/** (класс C), продуктовый код не существует до S5-ready; сами по себе они ничего не проверяют для ТЗ. Это сознательное решение объёма, а не пропуск.

Находки

Medium (в скоупе задачи, чинится в текущем ТЗ) — AC7 уже формулировкой не покрывает весь текст, который спецификация обязана исправить

Файл: docs/specs/294-wall-esc-detach.md, раздел 5 и AC7.

Суть. Раздел 5 обещает: «docs/USER-GUIDE.md и docs/USER-GUIDE.ru.md должны явно описать тот же контракт в разделах keyboard/cancel и Rooms/Walls». Но проверяемый критерий AC7 сужает обязательство:

Старое утверждение «Esc/Ctrl+Z — убрать точку» отсутствует в затронутых Walls-разделах; i18n parity зелёный.

AC7 — это единственное, что реально проверяется («ревью кода» + unit/i18n-parity), а не раздел 5. А формулировка старого утверждения, которое AC7 обязуется убрать, привязана буквальной цитатой и словом «Walls-разделах» — то есть не покрывает как минимум четыре конкретных места, где тот же неверный контракт «Esc для Draw убирает/отменяет операцию» сформулирован другими словами вне «Walls»-раздела:

• docs/USER-GUIDE.ru.md:223 (таблица поверхностей ввода, строка «Рисование и точный drag»): `Esc` отменяет операцию;
• docs/USER-GUIDE.ru.md:241 (раздел «Клавиши отмены», строка «Незавершённый Draw/Split»): «Убирает последнюю точку или выходит из инструмента»;
• docs/USER-GUIDE.md:207 (таблица поверхностей ввода, строка «Draw or precise drag»): `Esc` cancels the operation;
• docs/USER-GUIDE.md:216-217 (раздел «Cancel and undo»): «Esc cancels an unfinished path, current drag/resize/rotation, or the top dialog without undoing an already committed action.»

Ни одна из этих четырёх строк не содержит буквальной фразы «Esc/Ctrl+Z — убрать точку» и не лежит в «Walls»-разделе — значит, автоматическая или ручная проверка AC7 «по букве» пройдёт, даже если все четыре останутся нетронутыми. После реализации это даст прямое текстовое противоречие внутри одной документации: раздел про стены будет говорить «Esc завершает цепочку, геометрия сохраняется», а общая таблица «Клавиши отмены»/«Cancel and undo» — по-прежнему «Esc убирает точку/отменяет операцию» для того же инструмента Draw. Это ровно тот класс дефекта, который PROCESS.md §8 требует ловить («одно число — один источник», расширительно — одно поведение не должно быть описано двумя разными способами в одном документе).

Сценарий проявления: пользователь читает раздел 8 «Rooms and walls» — видит новый корректный контракт; тот же пользователь листает раздел 6 «Cancel and undo» или сводную таблицу горячих клавиш — видит старое, теперь неверное утверждение «Esc отменяет операцию/убирает точку». Документация one-source-of-truth не выполняется, при этом AC7 в исполнении «по букве» формально зелёный.

Почему это Medium, а не High: для активной задачи №294 продуктовый контракт (§3 ТЗ) сформулирован полно и однозначно, регресс поведения не грозит — страдает только точность документации, causing user confusion, но не потерю данных или неработающую функцию. Находка в скоупе текущей задачи (тот же файл, тот же тип правки, что и остальные пункты раздела 5) — чинится здесь же, отдельный issue не заводится (§202).

Что нужно поправить в ТЗ: переформулировать AC7 (и, по необходимости, раздел 5) так, чтобы явно перечислить все места, где сегодня утверждается «Esc для Draw убирает точку/отменяет операцию» — включая обе таблицы поверхностей ввода (RU/EN) и разделы «Клавиши отмены»/«Cancel and undo», а не только цитату и «Walls-разделы». Также стоит явно решить для EN «Create a room» (docs/USER-GUIDE.md:294-299): в отличие от RU-версии (строка 412), в этом месте английского руководства сегодня вообще нет утверждения про Esc/Ctrl+Z — паритет с RU-версией по этому контракту не назван требованием.

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

• Персона/поверхность/момент действия читаются однозначно из текста, хотя и без отдельного заголовка «Сценарий»: Home admin, Plan editor, инструмент «Стены», активная незамкнутая цепочка. Согласуется с docs/SCOPE.md (редакторы — только для Home admin, десктоп).
• Никаких догадок, выданных за факт: каждое утверждение о текущем поведении («Esc вызывает _undoPoint()», «смена инструмента идёт через _finishWallChain()», «переключение Стены→Колонна→Стены уже даёт нужный результат») подтверждено чтением src/houseplan-card.ts на той же ветке — см. пункт 4 «Как проверялось».
• Контракт Esc (§3.1–3.4 ТЗ) внутренне непротиворечив и совпадает с формой существующего кода: тот же history.wall_chain_finish, тот же путь materialization, тот же приоритет диалогов (_roomDialog проверяется в обработчике раньше ветки tool === 'draw' и уже завершается return, то есть требование «этот же keydown не должен дополнительно завершить восстановленный draft» уже выполняется существующей структурой кода, а не требует новой архитектуры).
• Различение Esc (finish) и Ctrl/Cmd+Z (undo point) — с AC4 отдельно и явно проверяемо через реальный keydown, что закрывает риск «Esc и Undo слились в одну кнопку», названный в разделе 9 ТЗ.
• AC1/AC2 намеренно используют различимые толщины AB/BC, чтобы merge коллинеарных сегментов одной толщины (_mergeSpacePartitions) не смазал проверку количества сегментов — разумная защита от ложноположительного прохождения теста.
• Не-скоуп (раздел 6) чётко исключает face-detection, touch-команду finish, формат хранения, Escape других инструментов — расширения скоупа не просматривается.
• Модель данных/миграция/i18n/touch/perf/security (разделы 8, 13) — сделанные предположения обоснованы и помечены как таковые в разделе 13, спор по ним решается вердиктом ревьюера, а не владельцем; ни один пункт не требует продуктового вопроса владельцу (нет открытых вопросов — подтверждаю).
• Trailers коммита спецификации корректны: Issue: #294, User-Visible: no — спецификация не меняет поведение, только документ; класс C, отдельный issue не требуется (входит в DoD текущего).
• Откат (раздел 10) достаточен: чистый revert, миграция назад не нужна из-за отсутствия изменений схемы.

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

• Гейты typecheck/test/build/check-docs/смоки — не запускались: раунд правит только docs/specs/**, продуктового кода ещё нет (issue не в S5-ready), эти гейты не применимы к этапу ТЗ.
• Реализуемость AC на уровне конкретного будущего диффа кода — предмет код-ревью, не ТЗ-ревью; здесь проверялась только проверяемость и однозначность формулировок.
• Issue #173 не читалась целиком построчно — использована как контекст по цитате в теле #294 и по факту существования кода единого инструмента «Стены», который уже найден и прочитан напрямую.

Вердикт

Жёлтый: единственная находка — Medium в скоупе задачи (пробел в формулировке AC7/раздела 5, из-за которого исправление может формально пройти проверку и оставить документацию внутренне противоречивой). High нет. Автор правит формулировку AC7 (и, если нужно, раздел 5) в этом же ТЗ, фикс проходит повторный цикл ревью по дельте (§2.10).