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

# SPEC-REVIEW-403-r1

- Issue: https://github.com/Matysh/houseplan-card/issues/403
- Артефакт ТЗ: `docs/specs/403-area-relocation-safety.md` (полный трек, класс A;
  без метки `small`/`trivial`)
- Материал: SHA `1f9d9014` (ветка `issue/403-area-relocation-safety`,
  коммит «docs: specify area relocation safety (#403)»)
- Заход: r1 · лимит циклов ревью ТЗ для полного трека — 4 (§4), израсходовано
  до этого раунда — 0 (пять предыдущих запусков конвейера падали до первого
  обращения к модели — `is_error: true`, `modelUsage: {}` — вердикта не было
  ни разу, бюджет не тратили, см. комментарии issue)
- Ревьюер: Claude (роль «ревьюер ТЗ»), независимая сессия, без устных
  пояснений автора
- Первый раунд — разбор полный, раздела «дельта» нет (§2.10 применяется
  начиная со второго захода)

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

Bug P1, класс A, полный трек (issue не помечен `small`): две находки
свежего кода #126 на одной поверхности (`src/houseplan-card.ts`,
`_syncAreaRelocations` и обработка отказов):

- **C2 (High из аудита)** — отказ `houseplan/config/set` во время переезда
  area оставляет `layout` уже удалённым (удаление успело пройти раньше) и
  не восстанавливает позицию и не помечает устройство как требующее
  внимания — ручная расстановка маркера теряется молча, самовоспроизводяще
  (снапшот откатывается на старую area → следующий authoritative-проход
  снова решает `relocate`).
- **M1 (Medium из аудита)** — переезд area **любого** устройства чистит
  **весь** стек Undo позиций (`_devicePositionHistory.clear()`), включая
  записи устройств, которых переезд не касался, и без уведомления (в
  отличие от соседнего класса очистки истории — `history.device_stale`).

Задача ложится на J6 `docs/SCOPE.md` («Keep the plan true as the home
evolves» — оптимистичная блокировка, ручная расстановка маркеров) и на
стоящее правило SCOPE.md «никогда не удалять данные пользователя по
догадке» — обе находки именно про это: ручная позиция маркера — данные,
введённые пользователем руками.

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

1. Прочитаны целиком `docs/SCOPE.md`, `AGENTS.md`, `PROCESS.md` (§1, §2.4,
   §2.5, §4, §5, §6, §7.1, §7.2, §8), тело issue #403 и все восемь
   комментариев (включая последовательность из шести неудачных запусков
   конвейера — учтено при подсчёте бюджета циклов, ни один из них вердикта
   не дал).
2. Прочитан весь текст ТЗ `docs/specs/403-area-relocation-safety.md`.
3. Каждое фактическое утверждение ТЗ о коде сверено построчно с деревом на
   `1f9d9014`:
   - `_maybeRebuildDevices`/`_syncAreaRelocations`
     (`src/houseplan-card.ts:5016-5254`) прочитаны целиком;
   - подтверждено: ветка отказа **удаления** layout восстанавливает позицию
     (`applyDevicePlacement(before)`, фактическая строка `:5184`, ТЗ называет
     `:5183` — расхождение в одну строку, не искажает факт);
   - подтверждено: ветка отказа **записи конфига** (`catch` на `:5223-5248`,
     ТЗ называет тот же диапазон точно) восстанавливает только
     `marker_area_snapshot`/`new_device_ids` в памяти (если фингерпринт не
     разошёлся) и **не восстанавливает** удалённую позицию — заявление ТЗ
     подтверждено буквально, строка в строку;
   - подтверждён механизм самовоспроизведения: `resolveDeviceAreaRelocations`
     (`src/device-area-relocation.ts:181-188`) решает `relocate = true`
     ровно когда `previous.area !== area`; после откатa снапшота на старую
     area это условие снова истинно на следующем authoritative-проходе —
     цикл, описанный в ТЗ, воспроизводится логикой резолвера, а не является
     догадкой;
   - подтверждена находка M1: `_devicePositionHistory.clear()`
     (`src/houseplan-card.ts:5062-5065` — ТЗ называет `:5056-5058`,
     расхождение в 6 строк, см. находку L1) стоит под условием «есть хоть
     одно переезжающее устройство», без фильтра по `deviceId`;
   - `CommandStack` (`src/command-stack.ts`) не имеет метода выборочного
     удаления — подтверждено, что контракт AC5/AC6 («снимается история
     переехавших, а не весь стек») требует нового метода, но это техническая
     деталь реализации, а не пробел ТЗ (стек типизирован по
     `NamedCommand<DevicePositionState>`, `deviceId` уже есть в каждой
     записи — технически осуществимо без изменения формата данных);
   - `toast.pos_save_failed`/`toast.cfg_save_failed`/`toast.conflict`/
     `history.device_stale` — все четыре ключа существуют в `src/i18n/ru.json`
     (и en/de/fr) — заявления ТЗ о «существующей метке» и «существующем
     уведомлении» подтверждены, не придуманы;
   - `registryFollowingBinding`/формат `binding` (`device-area-relocation.ts:95-107`)
     — подтверждён формат `${bindingKind}:${bindingRef}`, ровно то, что автор
     сам называет причиной трёх неудачных попыток воспроизведения C2 до
     финального успешного прогона (комментарии аналитики) — воспроизведение
     не голословно, ошибка автора зафиксирована и исправлена явно.
4. Проверено соответствие терминологии `docs/USER-GUIDE.ru.md`: раздел
   «Устройства» (`:757-771`) документирует именно тот успешный путь, который
   AC2 требует сохранить («старая позиция удаляется… появляется красная
   отметка внимания»), и раздел «История редактора» (`:260`, `:808-809`)
   подтверждает существующий контракт Undo (50 команд, best effort на touch) —
   спецификация не вводит новых терминов и не противоречит гайду.
5. Проверено `docs/TOUCH-SUPPORT.md` и DoR-чек-лист §2.5 на обязательные
   пункты «влияние на touch» и «влияние на производительность» — см. находку
   H1.
6. Проверены обязательные разделы §7.1 — присутствуют все (сценарий · что
   человек увидит до/после · проблема и контракт по каждому пункту · скоуп/
   не-скоуп · UX · модель данных и миграция · i18n · AC1–AC7 с доказательством ·
   план автотестов · риски · откат · release-артефакты).
7. Проверено существование инструментов, на которые ссылается план тестов:
   `scripts/mutation-gate.mjs` есть, ни одного мутанта `area-relocation-*` в
   нём пока нет (согласуется с ТЗ — это новые мутанты); `demo/smoke_area_relocation.mjs`
   существует и уже умеет мокать отказ `houseplan/config/set`
   (`rejectKettleRelocation`, строки 19/262/279) — план AC1/AC4 технически
   реализуем на существующей инфраструктуре смоков, не является фантазией.
8. Гейты кода (`tsc`, `test`, `build`) не гонялись: на этапе ТЗ продуктового
   диффа нет (класс C — только `docs/specs/**`), гонять их не над чем.

## Находки

### H1 (High, блокирует, в скоупе). ТЗ не называет два обязательных пункта DoR — влияние на touch/kiosk и на производительность

**Где**: весь файл `docs/specs/403-area-relocation-safety.md` — ни разу не
упоминает touch, kiosk, `TOUCH-SUPPORT.md`, производительность, перф или
бюджет (`grep -i "touch|kiosk|перф|производительн|performance"` по файлу —
ноль совпадений).

**Почему это находка, а не формальность**. PROCESS.md §2.5 перечисляет
обязательные пункты «Готово к разработке» и требует по каждому явную
запись, а не молчание: «влияние на производительность и бюджеты названо
(**или явно «нет»**)» и «влияние на touch по `docs/TOUCH-SUPPORT.md`
(**View и киоск — блокирующие**)». Оба пункта — из списка, помеченного
«Все пункты обязательны», и: «Если хоть один пункт не выполнен — статус не
«Готово к разработке», как бы ни хотелось начать». Ни один из двух пунктов
в ТЗ не назван — ни утвердительно, ни отрицательно.

Это не абстрактная бумажная претензия: у задачи есть настоящая View/kiosk
грань. AC2 фиксирует видимый на любом клиенте (включая киоск-планшет — J1
`docs/SCOPE.md`, «Show the whole home … device states») эффект успешного
переезда — маркер оказывается в новой комнате с отметкой внимания; это
именно то поведение, что описано в `docs/USER-GUIDE.ru.md:761-767`.
Симметрично, дефект C2 в необработанном виде **тоже виден на киоске** —
маркер молча возвращается в центр комнаты. То есть эта ветка кода реально
затрагивает View/kiosk-наблюдаемое поведение, а не только редакторский
слой, и именно поэтому DoR требует явного заявления, а не тишины.
AC5/AC6 (сужение очистки Undo) относятся к редактору устройств, для
которого touch уже документирован как best effort (`USER-GUIDE.ru.md:260`,
`:808-809`) — но это тоже должно быть **названо**, а не молчаливо
унаследовано: без явной строки нельзя отличить «автор сверился с
TOUCH-SUPPORT.md и решил, что контракт не меняется» от «автор не думал про
touch вовсе» (тот же аргумент, которым в SPEC-REVIEW-402-r1 было обосновано
идентичное H1-заключение для #402 — прецедент этого же ревьюера на этом же
проекте).

Фактическая оценка по существу (для экономии цикла): последствий, скорее
всего, нет ни для touch, ни для перфа. Обе правки — (1) порядок операций в
одном async-методе `_syncAreaRelocations` плюс восстановление/повторная
попытка записи при отказе, (2) точечный фильтр по `deviceId` в
уже существующей структуре истории на 50 записей. Ни жесты, ни рендер, ни
DOM, ни сетевые вызовы сверх уже выполняемых не меняются. Но это вывод
ревьюера, а не факт, зафиксированный автором в ТЗ, — фиксировать обязан
автор.

**Требуемая правка** (несколько строк текста, не кода): добавить в ТЗ,
например —
- `Touch: не затронут — правка меняет порядок серверной записи
  (_syncAreaRelocations) и фильтр очистки Undo-стека по deviceId, не
  касается drag/tap-жестов, рендера или DOM; наследует существующий
  контракт Undo/Redo (best effort на touch, USER-GUIDE §10). View/kiosk:
  наблюдаемый эффект (AC1/AC2) — позиционный, не входной, контракта View на
  touch не меняет.`
- `Производительность: нет — правка не добавляет новых циклов, подписок или
  сетевых вызовов сверх уже выполняемых `_syncAreaRelocations`/`_writeConfig`;
  фильтр истории работает на существующем массиве максимум 50 записей.`

### L1 (Low, снимается с записью). Номер строк для сниппета M1 отстал от кода на SHA `1f9d9014`

**Где**: `docs/specs/403-area-relocation-safety.md`, раздел «(2) M1»:
«`src/houseplan-card.ts:5056-5058`».

**Проверено чтением**: на `1f9d9014` этот диапазон (`:5056-5058`) — три
строки середины вызова `resolveDeviceAreaRelocations` (`model:`, `layout:`,
`snapshot:` — параметры объекта опций), не имеющие отношения к M1. Сам
процитированный в ТЗ сниппет (`this._areaRelocationIds = new
Set(...); if (...) { this._cancelDeviceDrag(); this._devicePositionHistory.clear();`)
дословно совпадает с кодом, но находится на строках `:5062-5065`.
Содержание находки верно и не пострадало (сверено выше, в «Как
проверялось», п.3), только адрес неточен — вероятно, из-за смещения при
правках между тем, когда аналитика собирала цитату, и фиксацией ТЗ.

**Решение ревьюера**: не блокирует, не создаёт отдельного цикла. Снимаю с
записью — исправить номера строк можно попутно при правке по H1 (тот же
файл будет открыт на редактирование), отдельного возврата ради одной этой
находки не требуется.

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

- **Диагноз C2 точен и воспроизводим**: ветка отказа удаления восстанавливает
  layout (`:5184`), ветка отказа записи конфига — нет (`:5223-5248`); порядок
  «delete-first» (`:5147` комментарий «Layout deletion is deliberately
  completed before provenance advances») подтверждён и корректно процитирован.
  Самовоспроизводящийся цикл (снапшот откатывается → резолвер снова решает
  `relocate`) подтверждён логикой `resolveDeviceAreaRelocations`
  (`device-area-relocation.ts:181-188`), а не выдан за факт без опоры на код.
- **Диагноз M1 точен**: `clear()` действительно безусловен по всему набору
  переезжающих устройств, `history.device_stale` действительно существует как
  образец уже принятого в проекте паттерна уведомления об очистке истории.
- **Два допустимых исхода C2 (запись первой / восстановление при отказе)
  сформулированы как решаемая ревьюером/автором техническая развилка**, а не
  как догадка, выданная за факт — с явным критерием выбора (AC3, свойство
  delete-first) и явной эскалацией в §"Риски", если восстановление тоже
  отказывает («потеря неизбежна» → AC1 формулируется как «позиция ИЛИ
  метка», не «позиция всегда»). Это корректное использование блока
  «принято предположительно» из §7.1 AGENTS.md для чисто технических решений.
- **AC1–AC7 однозначны и указывают способ доказательства** (браузерный смок,
  для AC7 — уже существующий `demo/smoke_area_relocation.mjs`). Способ
  реалистичен: существующий смок #126 уже умеет мокать отказ `config/set`
  (`rejectKettleRelocation`), новый смок под #403 — органичное расширение
  того же приёма, не изобретение с нуля.
- **Скоуп/не-скоуп корректен и не пересекается** с #126 (критерии переезда,
  формат снапшота — не трогаются), #74/#397 (механика Undo как таковая — не
  трогается, трогается только объём очистки), #406 «г» (гигиена снапшотов
  исчезнувших устройств — не относится к этой находке).
- **Соответствие `docs/SCOPE.md`**: закрывает J6 (оптимистичная блокировка,
  ручная расстановка маркеров) и защищает от нарушения стоящего правила
  «никогда не удалять пользовательские данные по инференсу» — задача не
  расширяет продукт, а чинит потерю уже введённых пользователем данных.
- **i18n-раздел корректно условен**: если решение обходится существующей
  меткой внимания — новых строк нет; если потребуется отдельное уведомление —
  явно предписано добавить ключ во все четыре словаря. Не оставляет открытого
  вопроса без явного правила на оба исхода.
- **Откат и release-артефакты адекватны масштабу**: обе правки локальны
  (один метод, один фильтр), changelog User-Visible: yes корректно назван
  (пользователь увидит, что расстановка переживает отказ записи).
- **Метки issue** (`bug`, `P1`, `S4-spec-review`, без `small`/`trivial`)
  согласуются с заявленным в ТЗ полным треком — задание корректно определило
  входной трек.
- **Инфраструктурная переписка issue** (шесть провалившихся прогонов
  конвейера, `is_error`/`modelUsage: {}`) не образует циклов ревью:
  вердикта не было ни в одном из них, бюджет §4 остаётся 0 до этого раунда.

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

- **Гейты кода** (`npx tsc --noEmit`, `npm test`, `npm run build`,
  `check-docs`, смоки, инварианты модели) — не гонялись: на этапе ТЗ
  продуктового кода нет, диффа для гейтов не существует (диапазон
  `origin/dev..HEAD` состоит только из `docs/specs/403-area-relocation-safety.md`).
  Это предмет код-ревью после реализации.
- **`scripts/mutation-gate.mjs` / `demo/smoke_area_relocation.mjs` —
  запуск**: не запускал ни то, ни другое; только убедился построчным чтением,
  что оба файла существуют, а механизм мока отказа WS (`rejectKettleRelocation`)
  в существующем смоке технически совместим с планом автотестов ТЗ (AC1/AC4).
- **Реальный браузерный повтор репродукции C2/M1** — на этапе ТЗ кода
  нет; воспроизведение, описанное автором аналитики (лог WS-вызовов,
  состояние `layoutHasDevice`/`snapshotAreaNow`/`attention`/`undoAvailable`),
  принято на основании сверки с логикой резолвера и обработчика отказа в
  текущем дереве (см. «Как проверялось», п.3), а не путём собственного
  запуска браузера — независимая браузерная перепроверка будет предметом
  код-ревью, когда появится смок.
- **`CommandStack`-реализация выборочного удаления** — не проектировал и не
  требовал конкретного API; отметил только, что текущий тип данных
  (`NamedCommand<DevicePositionState>` с `deviceId` в каждой записи) делает
  контракт AC5/AC6 технически осуществимым, выбор метода — за реализацией.
- **Таблицу `docs/specs/README.md`** — строка для #403 в неё не добавлена;
  это известный, не относящийся к этой задаче долг (§7.3 п.1 PROCESS.md),
  не поднимаю отдельной находкой.

## Вывод

Диагноз и контракт по обеим находкам аудита (C2, M1) точны, построчно
сверены с кодом на `1f9d9014` и не содержат догадок, выданных за факт; AC1–
AC7 однозначны, доказуемы и реалистичны на существующей тестовой
инфраструктуре. Единственная блокирующая находка — процедурная (H1):
ТЗ не называет обязательные по DoR §2.5 пункты про touch/kiosk и
производительность. По существу риска в обоих пунктах, скорее всего, нет,
и правка — несколько строк текста; возвращаю жёлтым, не красным.