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

# SPEC-REVIEW-220-r1

- **Issue:** https://github.com/Matysh/houseplan-card/issues/220
- **ТЗ:** `docs/specs/220-space-tab-reorder.md` (коммит `0fd2331`)
- **Ревьюер:** Claude (роль «ревьюер ТЗ», PROCESS.md §2.4)
- **Цикл:** r1/2 (обычный трек — лимит 4, но фиксирую фактический номер цикла)
- **Вердикт:** жёлтый · High: 0 · Medium: 2 (обе в скоупе задачи)

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

Полный разбор — первый цикл. Проверено:

1. `docs/SCOPE.md` — соответствие job J6, персона «администратор плана».
2. `AGENTS.md`, `PROCESS.md` §2.4, §2.5, §7.1 — обязательные разделы ТЗ,
   критерии DoR, формат вердикта.
3. Тело issue #220 и оба комментария (аналитика → `S3-spec`; хендофф ТЗ →
   `S4-spec-review`).
4. `docs/USER-GUIDE.ru.md` — терминология «пространство», «вкладка».
5. `docs/TOUCH-SUPPORT.md` — канонический документ для editor-only фичи с
   явным touch-решением владельца.
6. `docs/CONFIG-COMPATIBILITY.md` — паттерн описания новых/условных полей.
7. Код на `dev` (`src/houseplan-card.ts`, `src/logic.ts`, `src/devices.ts`) —
   сверка всех фактических утверждений ТЗ (номера строк, сигнатуры,
   поведение).

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

- Построчное чтение ТЗ (`docs/specs/220-space-tab-reorder.md`, 236 строк)
  против требуемых разделов §7.1 — все присутствуют: сценарий, что человек
  увидит до/после, подтверждённая причина, скоуп/не-скоуп, контракт поведения,
  данные/i18n/a11y/security, performance, риски, AC1…AC8 с доказательством,
  план автотестов, мутационный гейт, release-артефакты, откат, блок
  принятых предположений.
- Каждая техническая ссылка на код (`houseplan-card.ts:15717/6692/3350/4273/
  1165`, `devices.ts:1058/1063/1249`, `logic.ts:1870-1879`) сверена с текущим
  `dev` через `grep`/чтение файлов — расхождение только в точных номерах строк
  (код на `dev` сдвинулся на десятки строк с момента анализа), сама логика,
  сигнатуры и поведение подтверждены дословно:
  - `navigationSpaces = fixed.kind === 'valid' ? [space] : model` (`:15673`,
    рендер вкладок `:15746`) — подтверждает побочный эффект: при активном
    `floor` (#210) в панели всегда ровно один таб, значит правило AC5 «одно
    пространство — обработчики не навешиваются» само по себе накрывает и этот
    случай, отдельной ветки в контракте не требуется;
  - `firstSpaceId: this._model[0]?.id || ''` встречается дважды
    (`houseplan-card.ts:3350`, `:4273`), потребляется в `devices.ts` в
    `resolveExplicitMarkerPlacement` и в ветке virtual-маркера — подтверждён
    риск, ради которого написан §8.3/AC3;
  - `swipeTarget(dx, dy, zoom, spaceIds, current, minPx)` (`logic.ts:1870`)
    принимает `spaceIds` параметром, вызывающий код передаёт
    `this._model.map((m) => m.id)` (`houseplan-card.ts:5719`) — заявление §8.4
    «изменений не требует» подтверждено буквально;
  - `_fixedFloorState` (`:1165`) действительно имеет ветвь
    `out-of-range-index` — таблица в §«подтверждённая причина» точна;
  - `_canEdit` (`:845`, серверный `can_write`/`is_admin`) и `_mode` (тип
    `'view'|'plan'|'devices'|'decor'`, `mode-transition.ts:1`) — разные
    независимые гварды, оба перечислены в §8.1 корректно и раздельно;
  - `_writeConfig`/`expected_rev` (`:6702`) — существующий механизм, на
    который опирается AC6, подтверждён.
  - Итог: ни одного факта, выданного за решение без опоры на код или на
    явный owner-decision, не найдено. Все «подтверждённые причины» в ТЗ
    подтверждаются.
- `docs/TOUCH-SUPPORT.md` прочитан целиком — раздел «Documentation rule»
  (строки 153–165) обязывает каждую спецификацию новой editor-фичи явно
  указать один из трёх ярлыков: `Touch editor: supported` /
  `best effort / intentionally degraded` / `not exposed`. В ТЗ #220 такой
  строки нет (см. находку M1).
- `docs/CONFIG-COMPATIBILITY.md` прочитан как образец того, как описываются
  новые/условные поля конфигурации, для сверки с находкой M2.
- AC1…AC8 проверены на однозначность и наличие способа доказательства —
  все восемь пронумерованы и каждый называет `unit`/`smoke`/`diff` (см.
  ниже раздел «AC»).
- Блок §17 «Принятые предположения» проверен на то, что в нём действительно
  лежат только технические решения (не продуктовые) — да, все четыре пункта
  такие; продуктовые вопросы (тач, права, клавиатура) закрыты явными
  owner-decision в §4, что подтверждается вторым комментарием issue.

## Находки

### M1 — Medium, в скоупе. Отсутствует обязательная touch-классификация

`docs/TOUCH-SUPPORT.md` («Documentation rule», строки 153–165) требует, чтобы
спецификация новой editor-фичи явно называла один из трёх статусов:
`Touch editor: supported` / `best effort / intentionally degraded` /
`not exposed`. Задача #220 добавляет новую editor-фичу (перетаскивание
вкладок), которая по прямому решению владельца (§4.1 ТЗ) на сенсорных
экранах не работает вовсе — это классический случай `not exposed`. ТЗ нигде
не содержит этой строки (проверено `grep -n -i "touch editor"
docs/specs/220-space-tab-reorder.md` → пусто).

**Почему это не формальность.** Правило существует специально для того, чтобы
touch-ограничение было явным, а не выведенным читателем ТЗ из контекста: §103
того же документа («Deliberate degradation rule») требует пяти условий,
включая «touch limitation is deliberate, described in the user-facing
limitations» — описание в USER-GUIDE запланировано (§15 ТЗ), но сама
классификация как акт признания решения — нет.

**Чем закрывается:** одна строка вида `Touch editor: not exposed —
перетаскивание вкладок работает только мышью в редакторах (§4.1, §7)` в ТЗ,
рядом с §4 или §9. Не требует новых AC и не меняет скоуп.

### M2 — Medium, в скоупе. §9 утверждает «нет нового поля», хотя §8.3/§17.3 предполагают обратное

§9 («Данные») формулирует как решённый факт: *«только порядок элементов
массива `spaces`. Ни одно поле не добавляется и не удаляется; миграции и
compatibility-полей нет»*.

Это противоречит собственному §8.3/§17.3 того же документа. Причина
противоречия не косметическая, а структурная: сегодня «первое пространство»
физически **не имеет** другого представления, кроме позиции 0 в массиве —
отдельного поля-якоря или временной метки создания не существует
(подтверждено чтением `devices.ts` и `houseplan-card.ts`: `firstSpaceId`
везде вычисляется как `_model[0]?.id`). Значит, чтобы якорь **пережил
перезагрузку страницы** — а он обязан её пережить, иначе после reload
`_model[0]` снова укажет на новый первый элемент (тот, что оказался на месте
0 после перестановки), и AC3 перестанет выполняться при следующей сессии —
единственный способ сохранить инвариант «маркер не меняет `space`» состоит в
том, чтобы **где-то записать исходный id постоянно**. Собственный блок
предположений автора (§17.3) прямо это и предлагает: «хранить якорь в
`settings` при первой записи конфигурации».

То есть §9 отвечает «нет» на вопрос, который DoR (`PROCESS.md` §2.5: «миграция
и compatibility-поля решены по `docs/CONFIG-COMPATIBILITY.md`») требует
решить, а не задекларировать закрытым текстом, который тут же опровергается
соседним разделом. Технический выбор (само устройство поля) законно оставлен
автору — но факт «поле, скорее всего, появится» должен быть проговорён в §9,
а не спрятан только в необязательном для чтения блоке предположений.

**Последствие, если не поправить.** Если реализация действительно добавит
поле в `settings` (наиболее вероятный путь по собственному §17.3),
`docs/CONFIG-COMPATIBILITY.md` не получит записи о новом поле, хотя документ
существует ровно для таких случаев (сравните с трактовкой `known_devices`,
`custom_fill`, `bg_mode` — все новые поля `settings` в этом файле
задокументированы отдельным разделом с историей совместимости).

**Чем закрывается:** переформулировать §9 в духе «если якорь потребует нового
поля в `settings` — оно аддитивно и forward-compatible: старые клиенты его
игнорируют, при отсутствии поля fallback остаётся прежним (`_model[0]`)», и
добавить короткую запись в `docs/CONFIG-COMPATIBILITY.md` в том же коммите,
где появится реализация (не обязательно сейчас, но контракт должен быть
проговорён в ТЗ, а не отрицаться).

### Low — не является блокирующим, не требует правки

- Гвард начала drag (`pointerdown` по `.tab`, порог 4px) не оговаривает
  явно элемент `.tabedit` (шестерёнка настройки пространства) внутри вкладки:
  текущий обработчик шестерёнки — `@click` с `e.stopPropagation()`
  (`houseplan-card.ts:15754`), но `pointerdown`, скорее всего, будет повешен
  на `.tab`, а не на кнопку, и `stopPropagation` в `@click` не остановит
  всплытие `pointerdown`. Реализация почти наверняка и так исключит `.tabedit`
  из зоны старта drag (иначе шестерёнка перестанет открывать диалог при
  случайном микросдвиге курсора) — это тривиальная деталь без продуктовой
  неоднозначности и без риска потери данных. Снимаю без правки: чисто
  реализационная деталь, накрываемая кодревью.

## AC — проверка на однозначность и доказуемость

| AC | Однозначен | Способ доказательства указан | Комментарий |
|---|---|---|---|
| AC1 | да | `smoke` | конкретное поведение: позиция + переживает reload |
| AC2 | да | `smoke` | порог 4px, оба исхода (клик/drag) проверяемы |
| AC3 | да | `unit` (`buildDevices`) | явно требует «тест красный до развязки» — хорошая практика |
| AC4 | да | `unit`+`smoke` | подтверждено чтением кода: `swipeTarget` не требует правок |
| AC5 | да | `unit`+`smoke` | четыре условия исключения перечислены явно и проверяемо |
| AC6 | да | `unit`/`smoke` | опирается на существующий механизм `expected_rev` |
| AC7 | да | `smoke` | «один раз за сессию» — паттерн уже есть в коде (`_onboardingShown`), не изобретён |
| AC8 | да | `diff` + сверка бандлов | стандартный release-гейт |

Ни один AC не сформулирован расплывчато, у каждого назван корректный способ
доказательства применительно к тому, что он утверждает.

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

- Персона и job (`docs/SCOPE.md` J6) подобраны верно, сценарий и «что человек
  увидит» — в пользовательских терминах, без реализации.
- Продуктовые решения (§4) действительно закрывают все три продуктовых
  вопроса из аналитики (тач/права/клавиатура) явной ссылкой на owner-decision
  2026-08-20, а не на догадку исполнителя.
- Все три места, где порядок массива несёт скрытый смысл (`firstSpaceId`,
  `swipeTarget`, числовой `floor`), названы, подтверждены по коду и закрыты
  разделами контракта (§8.3, §8.4, §8.5) — это тот самый риск, ради которого
  задача вообще была оценена в сложность 4/10, а не 1/10.
- Технические предположения (§17) действительно технические — ни один пункт
  не требует продуктового решения владельца, что соответствует правилу
  «размытое место не додумывается, а выносится владельцу» из PROCESS.md §7.1
  (здесь размытых продуктовых мест не осталось).
- Мутационный гейт целится в самые опасные регрессии (потеря записи, съеденный
  клик, возврат порядко-зависимого `firstSpaceId`, снятие проверки
  `pointerType`) — это именно те четыре мутанта, которые действительно ловят
  типовые ошибки такой фичи.
- Release-артефакты (§15) и откат (§16) присутствуют и покрывают оба
  changelog, оба USER-GUIDE, отсутствие влияния на golden/perf.

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

- Не проверял реализацию — её ещё нет (это ревью ТЗ, код не существует).
- Не запускал никаких гейтов/тестов: на этапе ревью ТЗ гейты (`typecheck`,
  `npm test`, `npm run build`) неприменимы — класса A/B изменений нет, только
  документация (класс C).
- Не проверял `docs/specs/README.md` на полноту сверх наличия строки про
  #220 — строка присутствует, этого достаточно для этого этапа.
- Не оценивал абсолютную величину порога 4px и механику «вставка перед» —
  оба явно помечены автором как «принято предположительно, поменять
  свободно» (§17.1–17.2), оспаривать нечего: реализация вправе выбрать другое
  значение без нового цикла ревью.

## Итог

Два Medium-замечания, обе в скоупе задачи, обе устраняются точечной правкой
текста ТЗ (без изменения AC, скоупа или контракта поведения). High-находок
нет. Вердикт — жёлтый: автор правит §4/§9 ТЗ (добавляет touch-классификацию и
снимает противоречие в разделе «Данные»), правка проходит второй цикл ревью
ТЗ. Задача не `small`, лимит циклов ревью ТЗ — 4 (`PROCESS.md` §4); этот
раунд — первый из них.