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

# SPEC-REVIEW-113-r1

- **Issue:** https://github.com/Matysh/houseplan-card/issues/113
- **ТЗ под ревью:** `docs/specs/113-optional-space-model.md` (коммит
  `5f02dd38a1b60fa5064ea1291559b32c502fa1f0`, ветка
  `issue/113-optional-space-model`)
- **Роль:** ревьюер ТЗ (не автор), этап `S4-spec-review`
- **Трек:** обычный (не `small`/`trivial`) — аналитика оценила сложность и
  риск 6/10 и 7/10, что превышает порог лёгкого трека (§5 PROCESS.md, ≤3);
  ТЗ корректно лежит файлом в `docs/specs/`, зарегистрировано в
  `docs/specs/README.md:85`.
- **Цикл:** r1/4

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

Проверялось соответствие ТЗ:

- `docs/SCOPE.md` — попадание задачи в J6 («план остаётся правдивым по мере
  развития», системная защита от ложного/пустого плана), отсутствие
  расширения скоупа за пределы честного optional-контракта;
- `PROCESS.md` §2.4, §2.5 (DoR), §7.1 (обязательные разделы ТЗ), §3/§12
  (запреты, включая «догадка вместо решения»);
- `AGENTS.md` — классы файлов (класс C для этого коммита), ветка, трейлеры;
- фактическому состоянию `src/houseplan-card.ts` — на предмет того, что
  диагноз ТЗ и цифры issue (45 полевых обращений `_spaceModel().<поле>`,
  недостижимость до render-гейта, факт того, что #111 закрыл один вызов) не
  являются непроверенной догадкой;
- прецедентам house-style в уже принятых `docs/reviews/SPEC-REVIEW-*.md`
  (107, 122, 123, 131, 137, 138, 141, 146) — как единообразно оформлены
  обязательные разделы §7.1 и как в этом репозитории калибруется
  High/Medium/Low для находок такого типа (структурная полнота ТЗ против
  дефекта контракта).

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

1. Прочитан весь тред issue #113: тело (находка M3 из ревью #111), комментарий
   аналитики от 2026-08-14 (ценность 7/10 пользователю, 9/10 разработке,
   сложность/риск 6/10, 7/10, P2, tech-debt, обычный трек, «продуктовых
   вопросов нет — технические guard patterns решаются в ТЗ без вопроса
   владельцу») и комментарий автора ТЗ от 2026-08-15 («продуктовых вопросов
   нет; выбран честный optional API»). Продуктовых вопросов владельцу
   корректно не задавалось — вся задача технического характера, что
   соответствует правилу «владельцу задаются только продуктовые вопросы».
2. Построчно сверены обязательные разделы ТЗ (§7.1 PROCESS.md) — таблица
   ниже.
3. Прочитан код, на который опирается диагноз ТЗ, чтобы отличить проверенный
   факт от догадки:
   - `_spaceModel(id?): SpaceModel` (`src/houseplan-card.ts:2984`) —
     сигнатура и тело (`m.find(...) || m[0]`) подтверждают проблему буквально
     как в §1 ТЗ.
   - Подсчитано число полевых обращений `_spaceModel([^)]*)\.<поле>`:
     `rooms` — 35, `wall_columns` — 6, `room_drafts` — 2, `bg` — 2, плюс один
     дополнительный сайт `_spaceModel(spaceId).vb` (`:15897`), не учтённый в
     таблице тела issue (45 vs фактических 46). Это неточность в теле самого
     issue, не в ТЗ (ТЗ не повторяет число 45), и не влияет на контракт ТЗ —
     не выношу отдельной находкой.
   - `render()` (`:14281`) подтверждён как ранний empty-state gate
     (`if (!model.length) return html\`...\`;`), `willUpdate`/`updated`
     (`:3089`, `:3116`) подтверждены как выполняющиеся **до** и **независимо**
     от результата `render()` (Lit вызывает их для каждого прохода жизненного
     цикла), что подтверждает центральный тезис ТЗ и issue — недостижимость
     держится на порядке вызовов, а не на типе.
   - `_continuityAssetsReady()` (`:2763-2769`) подтверждён как фикс #111:
     явный `if (!this._model.length) return false;` **до** вызова
     `_spaceModel()` — соответствует описанию issue «#111 закрыл один вызов
     из render snapshot».
   - Default-parameter паттерн `space = this._spaceModel()`
     (`_physicalBodiesR`, `_rawPhysicalBodiesR`, ещё один метод — `:11668`,
     `:11679`, `:11688`) подтверждён как реально существующий — именно тот
     паттерн, который §5.3 ТЗ явно требует убрать.
   - Проверено отсутствие текущих non-null assertions на `_spaceModel()`
     (`grep "_spaceModel([^)]*)!"` — пусто) — согласуется с ТЗ §8, который
     запрещает их вводить, а не убирает существующие.
   - Найдены реальные call sites с явным `id`, показательные для §6 ТЗ:
     `_livePos(d)` (`:4535` → `this._spaceModel(d.space)`), `_vacStartFit`
     (`:15376` → `this._spaceModel(d.space)`), `_vacPlanRoomAnchors`
     (`:15302`), сайт создания/перемещения устройства (`:12043` →
     `this._spaceModel(space || undefined)`) — все передают «стабильный»,
     потенциально устаревающий `spaceId`, а не всегда `this._space`. Это
     именно тот класс вызовов, который §6 ТЗ описывает как «команды с
     stable spaceId».
   - Существующие тесты вида `test/*-contract.test.mjs`
     (`isometric-contract.test.mjs`, `release-contract.test.mjs`,
     `performance-contract.test.mjs`, `native-select-contract.test.mjs`)
     подтверждают, что «source-contract test» из §8/§10 ТЗ — не изобретённый
     механизм, а продолжение существующего паттерна репозитория.
   - `docs/ARCHITECTURE.md` и `docs/TESTING.md` существуют — release-артефакты
     §13 ТЗ ссылаются на реальные файлы, не выдуманные.
4. Сопоставлены между собой §4 (нормативный API), §6 (active id и fallback),
   §10 AC8 и §14 (риски) на непротиворечивость — обнаружено расхождение,
   см. Medium-1.
5. Проверены трейлеры и class-принадлежность: `git show --stat 5f02dd3`
   показывает только `docs/specs/113-optional-space-model.md` и
   `docs/specs/README.md` (класс C, ни одного файла класса A — продуктовый
   код не тронут до `S5-ready`, Rule #1 `AGENTS.md` соблюдено); коммит несёт
   `Issue: #113` и `User-Visible: no` — корректно для документа ТЗ, который
   сам не меняет поведение.

## Обязательные разделы (§7.1 PROCESS.md)

| Раздел | Есть | Комментарий |
|---|---|---|
| Сценарий (персона/поверхность/момент) | ⚠️ | Нет отдельного заголовка; содержание фактически распределено по §1 (кто и когда встречает пустой план) — см. Low-1 |
| Что человек увидит до/после | ⚠️ | Нет отдельного заголовка; ответ («ничего видимо не меняется, это профилактика класса #111») восстановим из §1+§9, но не сформулирован явно одной фразой — см. Low-1 |
| Проблема (с подтверждённой причиной) | ✅ | §1, факты подтверждены чтением кода (см. «Как проверялось» п.3) |
| Скоуп / не-скоуп | ✅ | §2 (цели) / §3 (не входит в задачу), границы чёткие (без глобального `noUncheckedIndexedAccess`, без миграции, без empty-state UX) |
| Контракт поведения | ✅ | §4–§8, классификация call sites по 4 категориям, конкретные примеры кода |
| Модель данных и миграция | ✅ | §9 — явно «config/layout schema и revisions не меняются» |
| UX, i18n, accessibility, touch | ⚠️ | §9 содержательно утверждает «editor touch safety floor не меняется», но не использует ни одну из трёх канонических формулировок `docs/TOUCH-SUPPORT.md` («Touch editor: supported/best effort/not exposed») — см. Low-3 |
| AC1…ACn с доказательством | ⚠️ | §10, 10 штук, пронумерованы и в целом проверяемы, но ни один не несёт явной пометки способа доказательства (`unit`/`smoke`/…), в отличие от всех сверенных прецедентов (107, 122, 123, 131, 137, 141, 146) — см. Low-2. Отдельно для AC8 отсутствие явного доказательства — не косметика, а реальный пробел, см. Medium-1 |
| План автотестов | ✅ | §11, разбит на unit/smoke/регрессию, включает mutation-тест («вернуть required signature — тест красный») |
| Риски | ✅ | §14, таблица риск/мера, 5 строк |
| Откат | ✅ | §14 (последний абзац) — без миграции данных |
| Release-артефакты | ✅ | §13, конкретный список (`ARCHITECTURE.md`, `TESTING.md`), оба файла существуют, `User-Visible: no` корректно снимает требование changelog |

Присутствует также раздел «Принятые технические предположения» (§15, 4
пункта) — соответствует требуемому PROCESS.md §7.1 блоку «принято
предположительно, поменять свободно», хотя заголовок не содержит буквально
эту оговорку (косметика, не отдельная находка).

## Находки

### Medium-1 — AC8 не имеет предъявленного механизма доказательства; риск и контракт расходятся

**Файл:** `docs/specs/113-optional-space-model.md:110-130` (§6),
`:180` (AC8), `:186-201` (§11, unit-план), `:234-241` (§14, таблица рисков)

§14 называет риск буквально: «Stale id редактирует первый space» и указывает
единственную меру — «exact lookup для commands». Это ровно тот самый риск,
который AC8 обязан закрывать: «Missing explicit stale space id не мутирует
первый space».

Но нормативный API §4 —

```ts
private _spaceModel(id?: string): SpaceModel | undefined {
  const requested = id ?? this._space;
  return this._model.find((space) => space.id === requested) ?? this._model[0];
}
```

— **всегда** возвращает `_model[0]`, когда `requested` не найден, независимо
от того, был ли `id` передан явно или нет. Для непустой модели эта функция
никогда не возвращает `undefined`: она возвращает объект, только не тот,
который просили. Проверено на реальных call sites: `_livePos(d)`
(`houseplan-card.ts:4535`) вызывает `this._spaceModel(d.space)` для позиции
устройства, `_vacStartFit` (`:15376`) — аналогично. Если пространство,
которому принадлежит устройство (`d.space`), было удалено (что штатно для
задачи #113 — «удаление последнего/произвольного space»), а другие
пространства остались, `_spaceModel(d.space)` молча вернёт **первое
оставшееся** пространство — тип этого не ловит, потому что результат
определён (не `undefined`).

Единственная названная в ТЗ мера — вынести отдельный
`_spaceModelById(id)` без fallback (§6) — сформулирована как **опция**:
«Чтобы исключить опасную двусмысленность, **допустимо** разделить API...
Это техническое разделение **рекомендуется** для drag/history/dialog
commands». Формулировка не обязывает автора реализации ввести этот метод
и не обязывает каждый call site с явным id использовать его вместо
`_spaceModel(id)`. Единственная альтернатива, которую ТЗ предлагает
взамен, — ручная проверка identity на каждом call site («callers... должны
проверять identity отдельно и abort-ить»), но:

- ни §8 (source-contract test), ни §11 (план тестов) не называют проверку,
  которая убедилась бы, что *каждый* call site с явным id либо использует
  no-fallback lookup, либо содержит ручной identity-guard;
- unit-пункт §11 «exact lookup не падает в first-space fallback» тестирует
  сам вспомогательный selector в изоляции, а не то, что производственные
  call sites (`_livePos`, `_vacStartFit`, сайт создания устройства `:12043`
  и другие, использующие явный `id`/`spaceId`) действительно его
  применяют.

**Почему это Medium, а не High:** контракт не производит немедленную,
гарантированную регрессию (в отличие от `SPEC-REVIEW-138-r1` High-1, где
буквальное прочтение ТЗ ломает работающий сегодня клик) — сегодняшний код
уже имеет такое же молчаливое поведение при stale `id`, задача #113 его не
ухудшает. Риск в том, что заявленная в AC8 защита от этого класса дефектов
не гарантирована структурно (типом или тестом), а оставлена на
дисциплину конкретных call sites без перечня, что именно нужно проверить —
то есть тот же класс проблемы, из-за которого появился сам #113
(«недостижимость держится на порядке вызовов, а не на типе»), может
частично воспроизвестись для explicit-id веток, если реализация не
проявит собственную дисциплину сверх того, что явно требует контракт.

**Что нужно поправить:** заменить «допустимо»/«рекомендуется» в §6 на
обязательное правило — любой call site, передающий явный/стабильный
`id`/`spaceId` в мутирующем или persist-контексте, обязан использовать
no-fallback lookup (или эквивалентный identity-guard), и добавить в §8/§11
конкретную проверку (source-contract grep по списку известных
call sites, либо unit-тест, дергающий каждую публичную мутирующую точку со
stale id и проверяющий отсутствие записи/side effect). Это техническое
уточнение, не продуктовый вопрос — решается автором и ревьюером кода без
эскалации владельцу.

**Решение ревьюера:** Medium, заведён отдельный issue
[#184](https://github.com/Matysh/houseplan-card/issues/184) со ссылкой на
#113 и на этот документ. Не блокирует переход ТЗ в `S5-ready`: остальной
контракт (9 из 10 AC, вся lifecycle/render/cleanup часть) самодостаточен,
проверяем и корректен, а сама эта находка — уточнение контракта, которое
разумно донести до автора кода явно, а не через возврат ТЗ на цикл.

### Low-1 — нет отдельных заголовков «Сценарий» и «Что человек увидит до/после»

**Файл:** `docs/specs/113-optional-space-model.md:9-27` (§1)

PROCESS.md §7.1 требует эти два раздела первыми, отдельно от «Проблема».
Все восемь других сверенных ТЗ репозитория (`107`, `122`, `123`, `131`,
`137`, `138`, `141`, `146`) оформляют их отдельными заголовками. В
`113-optional-space-model.md` содержание фактически присутствует —
§1 называет причину и предшествующий инцидент (#111), §9 фиксирует, что
видимое поведение не меняется, — но не сформулировано как явный ответ на
«кто/где/когда» и «одна фраза до/после». Прецедент `SPEC-REVIEW-107-r1`
(Low-1: «раздел «Проблема» не выделен отдельным заголовком») фиксирует тот
же класс находки как некритичный, если содержание по существу
присутствует.

**Решение ревьюера:** Low, не блокирует. Можно поправить в следующей
редакции (например, короткая явная фраза: «Персона — любой пользователь
View/editors при удалении пространства или холодном старте с `spaces: []`;
до — риск исключения при будущей правке порядка вызовов (класс #111),
после — тот же надёжный empty-state, без видимых изменений»), либо снять
записью в этом документе, если автор сочтёт §1 достаточным.

### Low-2 — AC1…AC10 не несут явной пометки способа доказательства

**Файл:** `docs/specs/113-optional-space-model.md:170-182` (§10)

DoR (`PROCESS.md` §2.5) и §7.1 требуют «у каждого [AC] указано, чем он
доказывается: unit / backend / smoke / golden / «ревью кода»». Ни один из
десяти пунктов §10 такой пометки не несёт — способ доказательства
приходится реконструировать по §11 (план автотестов), что для девяти из
десяти AC делается однозначно (например, AC3/AC4/AC5/AC6 — browser smoke,
AC1/AC2/AC10 — typecheck + source-contract test, AC7 — golden/существующий
скриншот, AC9 — unit), но для AC8 реконструкция не удаётся структурно (см.
Medium-1). Прецедент `SPEC-REVIEW-141-r1` (Low-3) относился к похожему, но
более мягкому случаю (формулировка доказательства вне буквального
перечня, а не полное отсутствие) и не блокировал.

**Решение ревьюера:** Low, не блокирует. При следующей правке ТЗ
рекомендуется приписать к каждому пункту §10 короткую пометку в скобках
(`(smoke)`, `(unit)`, `(typecheck+source-contract)` и т.п.) — механическая
правка без изменения контракта.

### Low-3 — нет буквальной метки touch-контракта по `docs/TOUCH-SUPPORT.md`

**Файл:** `docs/specs/113-optional-space-model.md:161-168` (§9)

`docs/TOUCH-SUPPORT.md` требует одну из трёх формулировок (`Touch editor:
supported` / `best effort / intentionally degraded` / `not exposed`) для
спецификаций, затрагивающих поведение редакторов. §9 по существу описывает
best-effort/unchanged-контракт («editor touch safety floor не меняется»),
но не использует канонический ярлык. Тот же класс находки зафиксирован как
Low и не блокировал в `SPEC-REVIEW-141-r1` (Low-1).

**Решение ревьюера:** Low, не блокирует. Косметическая правка на усмотрение
автора (добавить строку `Touch editor: best effort / intentionally
degraded (unchanged)`).

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

- **Соответствие `docs/SCOPE.md`:** задача закрывает J6 («план остаётся
  правдивым по мере развития» — плановые правки не должны ронять карточку
  при пустом плане) как профилактика, не расширяя продуктовую поверхность;
  User-Visible: no подтверждён и содержанием ТЗ (§13), и отсутствием любых
  UX/i18n/визуальных изменений в контракте.
- **Легитимность полного трека:** сложность/риск 6/10 и 7/10 превышают
  порог `small` (≤3) — полный трек и файл `docs/specs/` выбраны верно,
  issue корректно НЕ помечен `small`.
- **Технический диагноз не голословен.** Число полевых обращений
  `_spaceModel().<поле>`, факт единственного гейта в `render()`, порядок
  `willUpdate`/`updated` относительно `render()`, факт фикса #111 через
  явный ранний `return false` — всё подтверждено чтением
  `src/houseplan-card.ts`, а не пересказом issue.
- **Классификация call sites (§5) полна и специфична для этой кодовой
  базы:** default-parameter паттерн (`space = this._spaceModel()`) назван
  и подтверждён существующим в трёх методах; onboarding-гейт `updated()`
  (`this._model.length === 0`) как пример уже существующей ручной
  дисциплины, которую ТЗ формализует типом.
- **Запреты (§4) конкретны и адресуют реальный анти-паттерн:** явный запрет
  на synthetic empty `SpaceModel`, на `!` у каждого consumer, на скрытый
  fallback через `this._serverCfg.spaces[0]` — не общие слова, а прямая
  реакция на то, как решались подобные проблемы в других частях кодовой
  базы.
- **Продуктовые вопросы закрыты по процессу:** задача целиком техническая
  (tech-debt, «guard patterns»), аналитик и автор корректно не эскалировали
  ничего владельцу; ни один вопрос, вынесенный бы во владельцу, на самом
  деле не был продуктовым — сверено построчно, эскалаций нет вообще.
- **Трейлеры и класс файлов:** коммит `5f02dd3` — только `docs/specs/**`
  (класс C), `Issue: #113`, `User-Visible: no` — корректно для документа
  ТЗ; ссылка issue ↔ ТЗ двусторонняя (issue → комментарий со ссылкой на
  файл; `docs/specs/README.md:85` → issue).
- **Release-артефакты не выдуманы:** `docs/ARCHITECTURE.md` и
  `docs/TESTING.md`, которые §13 обязывает дополнить, существуют в
  репозитории.

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

- Не проверял реализуемость предложенного разделения `_spaceModel()` /
  `_spaceModelById()` как факта работающего TypeScript-кода — на этапе ТЗ
  реализации ещё нет, это предмет код-ревью.
- Не запускал автотесты, не собирал бандл и не проверял backend — на этапе
  `spec` продуктовый код не менялся (подтверждено `git show --stat`), гейты
  из §8 PROCESS.md здесь неприменимы.
- Не проверял полноту всех ~46 call sites `_spaceModel()` по отдельности —
  проверена корректность классификации (§5 ТЗ) на представительной выборке
  (lifecycle-хуки, default-parameter паттерн, explicit-id команды), а не
  построчный аудит всех вхождений; это ожидаемо станет предметом код-ревью,
  когда появится diff.
- Не проверял `docs/TESTING.md` на предмет того, легко ли туда встроить
  «empty-plan lifecycle matrix» — детали документации оставлены на
  усмотрение автора реализации (класс C, не влияет на продуктовый контракт).
- Не оценивал производительность предложенных изменений — ТЗ (§13) явно и
  обоснованно откладывает performance-гейт до случая, когда diff
  действительно заденет горячие render-пути; на этапе спецификации это не
  проверяется.

## Вердикт

Зелёный. High: 0, Medium: 1 (заведён отдельным issue, не блокирует), Low: 3
(отсутствие отдельных заголовков «Сценарий»/«Что человек увидит»; отсутствие
явной пометки доказательства у AC1…AC10; отсутствие буквальной touch-метки
— все три косметические, содержание по существу присутствует, не блокируют
приёмку). ТЗ решает заявленную проблему (#111-класс дефектов) для
lifecycle/render/cleanup путей полно и проверяемо; единственный содержательный
пробел (Medium-1, explicit-id command paths) не отменяет ценность и
корректность контракта для основного объёма из ~46 call sites, но должен
быть закрыт до или во время реализации — что и обеспечивает заведённый
issue.