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

# SPEC-REVIEW-292-r1

- **Issue:** https://github.com/Matysh/houseplan-card/issues/292
- **Этап:** ревью ТЗ (PROCESS.md §2.4)
- **Артефакт ТЗ:** `docs/specs/292-resize-availability-audit.md`, commit `52ad67e7`
- **Заход:** r1 · блокирующих циклов израсходовано 0 из 4 (до этого вердикта)
- **Ревьюер:** Claude (роль ревьюер ТЗ, PROCESS.md §6)

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

Единственный документ на ревью — `docs/specs/292-resize-availability-audit.md`
(HEAD detached at `origin/issue/292-resize-availability-audit`, файл введён
коммитом `52ad67e7 docs: specify resize availability audit`). Issue не
помечен `small`, поэтому наличие отдельного файла в `docs/specs/` обязательно
и подтверждено. Первый раунд — деление на дельту (§2.10) не применяется,
разбор полный.

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

1. Прочитан `docs/SCOPE.md` — задача закрывает job J6 («Keep the plan true as
   the home evolves» — drag/resize), ограничитель не нарушен.
2. Прочитаны `PROCESS.md` (целиком, включая §7.1 обязательные разделы ТЗ,
   §2.5 чек-лист DoR, §4 лимит циклов) и `AGENTS.md`.
3. Прочитано тело issue #292 и все три комментария (уточнение про #293,
   «Аналитика подтверждена», ссылка на ТЗ).
4. Прочитан `docs/RESIZE.md` — канонический контракт Resize, куда #292 обязан
   вписаться без изменения архитектуры пайплайна.
5. Прочитан `docs/USER-GUIDE.ru.md` (термины «Resize», «Оптимизировать
   планы») — терминология ТЗ совпадает.
6. Сверены статусы связанных issue: `gh issue view` для #276 (CLOSED, слит —
   commit `a6056111 fix: reconcile coincident partitions during Optimize`),
   #289 (OPEN, `S3-spec`), #290 (OPEN, `S3-spec`), #293 (OPEN,
   `S4-spec-review`), #277 (CLOSED), #284 (CLOSED).
7. Прочитан текущий код: `src/resize.ts` (тип `SafeResizeReason`, 9 значений,
   без параметров контекста), `src/houseplan-card.ts` (`_rszReasonText`,
   `_rszDisabledActivate`, `_rszDisabledKey`, разметка `_renderResizeLayer`) —
   чтобы проверить, что декларируемый в ТЗ контракт технически достижим на
   существующей архитектуре.
8. Сверены i18n-ключи `resize.disabled.*` в `src/i18n/ru.json` с §5 ТЗ.
9. Для сравнения формата прочитаны структуры разделов трёх смежных ТЗ той же
   подсистемы: `docs/specs/276-coincident-partition-reconciliation.md`,
   `docs/specs/277-safe-resize.md` (прямой предок контракта Resize),
   `docs/specs/281-resize-zero-range.md`.
10. Проверено наличие обеих реальных фикстур,
    `test/fixtures/real-plan-{first,second}-floor.json` — существуют.
11. Проверено происхождение термина «mixed-role»: не изобретён автором ТЗ —
    это существующий инвариант `checkMixedRoleRecords`
    (`scripts/model-invariants.mjs`, `test/model-invariants.test.mjs`),
    закреплённый только что смежным коммитом `523190d8`.

Код не менялся, продуктовый код не оценивался за пределами чтения контракта
для проверки реализуемости ТЗ.

## Находки

### Medium (в скоупе задачи) — обещание в §5 не имеет технической опоры и не проверяется ни одним AC

**Файл:** `docs/specs/292-resize-availability-audit.md`, раздел 5 «Тексты
причин», строка «angled / side angle» и абзац после таблицы.

**Формулировка ТЗ:**

> angled / side angle — …; предложить Optimize, только если кандидат #290
> существует
> …
> Если Optimize не способен исправить конкретную стену, текст не должен
> обещать, что Optimize её исправит.

Это не пожелание, а нормативное требование к пользовательскому тексту —
ровно то, ради чего заведена задача (§29 issue: «пользователь не знает, что
виноват невидимый уступ… и что его можно выпрямить через „Оптимизировать“»,
но алгоритм не должен врать про стены, которые Optimize не чинит).

**Почему это дефект, а не мелочь.** Текущая архитектура даёт ровно один
текст на одно значение `SafeResizeReason`, без контекста:

```ts
// src/houseplan-card.ts:8567
private _rszReasonText(reason: SafeResizeReason): string {
  return this._t(`resize.disabled.${reason}` as I18nKey);
}
```

`SafeResizeReason` (`src/resize.ts:33-42`) — плоский union из 9 значений,
без поля «есть ли кандидат на исправление». Два ребра с одинаковым
`reason: 'side-angle'` — одно из-за настоящего уступа в один шаг (чинится
Optimize), другое из-за принципиально диагональной стены (не чинится) —
сегодня физически не различимы на уровне текста. Чтобы выполнить требование
§5, нужен один из двух путей:

- новое поле в `SafeResizeResolution`/новый вариант `SafeResizeReason`,
  несущий признак «есть кандидат ремонта», плюс отдельные i18n-ключи для двух
  вариантов сообщения — либо
- явный отказ от дифференциации сообщения и смягчение формулировки §5.

Ни то, ни другое в ТЗ не решено. При этом:

- **AC6** требует «один resolver и один reason type» между audit и render —
  то есть удвоения/новой ветки `SafeResizeReason` ТЗ прямо не предполагает,
  а альтернативы не называет;
- ни один AC (1–9) не проверяет само разделение «текст обещает Optimize» vs
  «текст не обещает Optimize» для двух геометрически разных `side-angle`;
- раздел 9 «Ожидаемые файлы» называет `src/i18n/en.json`, `src/i18n/ru.json`
  без единого перечисленного ключа — DoR (`PROCESS.md` §2.5) требует «i18n:
  ключи en + ru перечислены», здесь их нет вовсе, что при данном пробеле
  особенно чувствительно: неизвестно, один ключ на reason останется или
  появится второй;
- источник признака «кандидат #290 существует» зависит от #290, который сам
  ещё в `S3-spec` и не определил свой интерфейс — то есть #292 обещает
  использовать сигнал, которого пока не существует даже как контракт.

**Как воспроизвести последствие, если оставить как есть.** Реализатор,
получив ТЗ, либо (а) молча добавит новое поле/вариант reason — незапланированное
техническое решение без фиксации в ТЗ, которое ревью кода будет разбирать
без опоры на контракт, либо (b) оставит один статический текст на
`side-angle`/`diagonal`, и тогда либо утверждение §5 не выполнено (текст
всегда одинаковый и либо всегда предлагает Optimize — включая случаи, где
это не поможет, — либо никогда не предлагает, обесценивая саму находку
issue про «предложить действие»).

**Что нужно поправить в ТЗ:** добавить явный технический контракт (новое
поле контекста reason или отдельный `SafeResizeReason`-вариант с
перечисленными i18n-ключами для обоих языков) и минимум один AC, который
прямо проверяет «на fixture, где `side-angle` вызван настоящим уступом,
текст предлагает Optimize; на fixture, где `side-angle` — не устранимая
геометрия, текст этого не предлагает». Либо снять обязательство «текст не
должен обещать» из §5 и явно пометить дифференциацию сообщений как
предположение вне скоупа/будущей работы после #290.

### Low — отсутствуют разделы, обязательные по PROCESS.md §7.1 и принятые в соседних ТЗ той же подсистемы

Обязательный список §7.1: «сценарий · что человек увидит до и после ·
проблема · скоуп и не-скоуп · контракт поведения · UX · модель данных и
миграция · i18n · AC с доказательством · план автотестов · риски · откат ·
release-артефакты».

В `292-resize-availability-audit.md` отсутствуют как отдельные разделы:

- **«Сценарий и персона»** — кто, на какой поверхности, в какой момент
  встречает это поведение. Восстановимо из контекста (админ, десктоп, Plan →
  Resize), но не написано явно, как в `277-safe-resize.md` §1 и
  `276-coincident-partition-reconciliation.md` §1.
- **«Риски и меры»** — ни одного явного риска не названо отдельным
  разделом (только «Принятые предположения», которые не то же самое: риск
  требует меры, предположение — нет). Реальный риск здесь есть и не назван
  формально: AC1 и AC3 требуют «после rebase поверх #276/#289/#290», а #289 и
  #290 сейчас оба в `S3-spec` — то есть их собственные ТЗ ещё не прошли
  ревью. Задача корректно может стоять в очереди `S5-ready` (§2.5: «не
  работа, а очередь»), и это не блокирует зелёный вердикт ТЗ, но риск
  «баланс чисел заведомо не финализируется, пока не landed #289/#290»
  заслуживает отдельной строки, а не одной фразы в предположении №2.
- **«Откат»** — DoR (§2.5) требует явно: «как выключить или вернуть назад».
  У `277-safe-resize.md` и `276-...md` есть выделенный раздел
  «Release-артефакты и rollback» (например: «Rollback — revert
  implementation commit»). В ТЗ #292 такого раздела нет вовсе — раздел 10
  «Release» говорит только про трейлеры и закрытие issue, не про откат.

Ни одно из этих трёх упущений не меняет технический контракт и не создаёт
риска для реализации — это дефект полноты документа относительно
зафиксированного формата, а не двусмысленность поведения. Снимается
рекомендацией: добавить короткие явные разделы (по 2–4 строки достаточно,
как в `281-resize-zero-range.md`, который тоже лаконичен) при следующей
правке ТЗ по Medium-находке.

### Low — AC1–AC8 не помечают явно способ доказательства

DoR требует «у каждого [AC] указано, чем он доказывается: unit / backend /
smoke / golden / «ревью кода»». В тексте способ доказательства всегда
угадывается из формулировки (AC1/AC3/AC4/AC6/AC7/AC8 — очевидно `unit` по
fixture, AC2 — `unit`, AC5 — явно `production smoke`), противоречий не
найдено, но явной пометки нет ни у одного пункта, кроме сводного AC9
(гейты). Снимается с записью: смысл всюду однозначен, добавление явных
тегов — правка для аккуратности, не для устранения двусмысленности.

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

- **Сценарий и продуктовая рамка.** Задача явно закрывает job J6
  `docs/SCOPE.md` («keep the plan true» — drag/resize остаётся рабочим).
  Метрика 70% отключённых рукояток верно помечена диагностическим сигналом,
  а не целью «разрешить любой ценой» (раздел 11, п.1) — соответствует духу
  RESIZE.md, где часть запретов обязана оставаться.
- **Границы с #293 выдержаны.** ТЗ явно исключает починку «активной, но
  инертной» рукоятки (не входит, раздел 6) — комментарии issue подтверждают,
  что это разделение согласовано с владельцем 2026-08-24.
- **Термины грамотны и не изобретены.** «Оптимизировать планы» соответствует
  `docs/USER-GUIDE.ru.md:1396`; «mixed-role» соответствует существующему
  инварианту `checkMixedRoleRecords`; девять причин отказа (`diagonal` …
  `invalid-geometry`) дословно совпадают с уже описанным приоритетным
  списком в `docs/RESIZE.md` «Eligibility» — ТЗ не меняет порядок и не
  добавляет причин молча.
- **AC2 не выдумана.** Конкретная пара `room-a` edge 2 / `room-b` edge 2
  на второй реальной фикстуре подтверждена ранее эмпирически владельцем
  задачи в комментарии «Про стену между двумя детскими» — `resolveSafeResize`
  уже возвращал `enabled` на этой паре на момент issue.
- **Нет продуктовых вопросов владельцу, и это оправдано.** Комментарий
  «Аналитика подтверждена» прямо фиксирует «отдельных вопросов владельцу
  нет: критерии в issue однозначны» — согласуется с §7.1: оставшаяся
  неопределённость (см. Medium-находку) техническая, а не продуктовая, и её
  вправе решать автор с ревьюером без эскалации.
- **Не входит расширение safe-resize допусков.** Раздел 6 «Не входит»
  явно запрещает «ослабление safe-resize ограничений для
  partial/mixed/diagonal topology» — совпадает с предупреждением issue
  «сама доля запретов не является ошибкой».
- **Гейты названы соразмерно этапу.** Раздел 9 «Локальные гейты» верно
  ограничивается typecheck/test/build/check-docs/targeted-audit-smoke-mutation
  и явно откладывает полный golden/smoke/performance набор на пре-релиз —
  соответствует `PROCESS.md` §8.
- **AC8 верно привязан к существующему инвариантному инструменту** (wall
  keys, mixed-role records, references, opening host/fit, geometry preflight)
  — это тот же набор проверок, что и `scripts/model-invariants.mjs`; ТЗ не
  придумывает собственный параллельный набор.
- **Touch/compatibility не расширяются.** Раздел 8 корректно фиксирует
  «schema/storage не меняются», touch остаётся best effort с доступом к
  причине через tap — не создаёт нового UX-контракта сверх
  `TOUCH-SUPPORT.md`.

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

- Продуктовый код не читался за пределами трёх точек (`resize.ts` типы,
  `houseplan-card.ts` рендер рукояток и обработчики) — этого разбора
  достаточно для оценки реализуемости ТЗ, но это не код-ревью.
- Не запускались тесты/гейты — на этапе ревью ТЗ они не относятся к делу
  (код ещё не менялся, есть лишь файл документации класса C).
- Не проверялось состояние `docs/specs/README.md` (таблица issue ↔ ТЗ) —
  вне зоны ответственности ревью ТЗ, это гигиена репозитория.
- Не оценивалась связь с #293 на уровне кода — только на уровне
  формулировок ТЗ/issue, поскольку #293 не входит в скоуп #292.
- Точный будущий baseline AC1 не пересчитывался — он и не может быть
  пересчитан до слияния #289/#290, что сам документ признаёт (раздел 11,
  предположение 2).

## Вердикт

Medium-находка лежит строго в скоупе задачи (это её собственный раздел §5,
не соседняя подсистема) → по PROCESS.md §2.4/§4 без High это **жёлтый**
вердикт: автор правит ТЗ (либо задаёт технический контракт дифференциации
текста плюс AC, либо смягчает формулировку §5), фикс проходит второй заход
ревью по дельте (§2.10). Low-находки не блокируют переход, но должны быть
закрыты в той же правке, раз документ и так возвращается автору.

```
Вердикт: жёлтый · заход r1 · блокирующих циклов 1/4 · High: 0 · Medium: 1 → в задаче
Документ: docs/reviews/SPEC-REVIEW-292-r1.md
```