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

# SPEC-REVIEW-299-r1

- **Issue:** https://github.com/Matysh/houseplan-card/issues/299
- **Этап:** ревью ТЗ (PROCESS.md §2.4)
- **Документ ТЗ:** `docs/specs/299-mixed-role-wall-records.md`
- **SHA на котором получен вердикт:** `10f000dc47c391e5d6c18ba6e9b5b46ed4df67a3`
  (ветка `issue/299-mixed-role-thickness`, коммит «docs: specify role-aware
  wall compaction»)
- **Заход:** r1 · блокирующих циклов израсходовано 0 из 4 (первый заход, §4
  бюджет ещё не тратился)

## Скоуп проверки

Первый раунд — разбор полный (PROCESS.md §2.10 применяется только со второго
раунда). Проверено:

1. `docs/SCOPE.md` — задача закрывает J6 («Keep the plan true as the home
   evolves»); ADR #282 явно оставляет открытые P1 на живой репрезентации
   (строка 135: «None of this cancels an open P1»), так что точечная починка
   в обход стадий ADR легитимна, а не самовольное расширение скоупа.
2. `AGENTS.md`, `PROCESS.md` §2.4/§2.10/§7.1/§5 — трек не `small` (сложность
   8/10, риск 9/10, две продуктовые операции, real-plan regression), поэтому
   файл ТЗ обязателен и он есть; комментарий аналитика подтверждает трек
   «обычный» и что продуктовых вопросов нет.
3. Тело issue #299 и три комментария (аналитика → занятие → «ТЗ готово»).
4. `docs/USER-GUIDE.ru.md` не проверялся отдельно текстом, т.к. ТЗ прямо
   заявляет «новых кнопок, диалогов, предупреждений и терминов UI нет» (§2) —
   термины Optimize/«Удалить комнату, оставить стены» уже существующие и не
   переименовываются.
5. Канонический документ подсистемы: `docs/WALL-THICKNESS.md` — прочитан
   целиком, модель, компакция и контракт удаления комнаты сверены построчно.
6. Связанные закрытые issue #287 (диагностика `checkMixedRoleRecords`, есть в
   репозитории) и #289 (safe Resize eligibility) — оба `CLOSED`, содержимое их
   спек (`docs/specs/289-no-mixed-role-resize.md`) явно исключает «исправление
   уже сохранённых mixed-role records через Optimize» из своего скоупа, что
   подтверждает отсутствие дублирования с #299. #298 сейчас в `S4-spec-review`
   (параллельно) — ТЗ #299 корректно называет эту зависимость и требует, чтобы
   автор перед кодом ребейзился и держал контракт независимым от порядка
   слияния (принятое предположение №5, §15).

## Как проверялось (техническая верификация утверждений ТЗ)

ТЗ делает несколько фактических утверждений о текущем поведении кода —
согласно инструкции ревью, догадка, выданная за факт, является находкой. Все
проверены чтением исходников на SHA выше, не исполнением:

| Утверждение ТЗ | Где проверено | Результат |
|---|---|---|
| §3: `normalizeWallIntervals()` группирует соседние атомы только по `cm` и «сплошной», не сравнивая владельцев | `src/wall-thickness.ts:1927-2005`, ключевая проверка `pr.cms[next] !== cm` на строке 1966 — владелец/роль нигде не сравнивается | подтверждено |
| §3: `checkMixedRoleRecords()` — существующий диагностический инвариант из #287, не product-фикс | `scripts/model-invariants.mjs:518-543` | подтверждено, вызывается только в `main()` отчёта, не в write-пути |
| §4.4 / #228: exclusive positive-solid intervals удаляемой комнаты → partitions, shared/virtual/zero не материализуются | `src/room-deletion.ts:73-112`, фильтр `interval.kind === 'outer' && !interval.open && interval.cm > 0` | подтверждено |
| §4.4: Keep walls и Optimize сходятся в одном канонизаторе | `src/houseplan-card.ts:11456` (`this._normalizeWalls(materializedWalls, …)` после удаления комнаты) и `src/plan-optimizer.ts:580` (`normalizeWallIntervals(...)`) — оба вызывают одну и ту же функцию `src/wall-thickness.ts:1927` | подтверждено, один enforcement point действительно один |
| §15 предположение №1: роль выводится из `WallInterval.roomId`/`kind` ('shared'\|'outer'), пары владельцев ещё не готовы как поле | `src/wall-thickness.ts:1535-1545` (`WallKind = 'shared'\|'outer'`, без id второго владельца) | подтверждено техническое допущение реалистично: пару владельцев для `shared(A,B)` придётся строить геометрическим сопоставлением reversed-копий, а не читать готовое поле — это именно то, что ТЗ явно отдаёт на усмотрение автора/ревьюера в §15.1, а не выдаёт за уже существующее |
| ADR #282 исключение для P1 | `docs/adr/282-wall-geometry-representation.md:135-137` | подтверждено дословно |
| Комментарий кода `KNOWN` (`demo/smoke_edit_walk.mjs`) действительно содержит долг `mixed_role_record` на `real-plan-first-floor.json` seed 1 и 3 | `demo/smoke_edit_walk.mjs:82,86` | подтверждено, ссылка «Класс #287/#289» соответствует истории |
| Фикстура/тестовые файлы, названные в AC, существуют | `test/fixtures/real-plan-first-floor.json`, `test/wall-thickness.test.mjs`, `test/plan-optimizer.test.mjs`, `test/room-deletion.test.mjs` | все существуют |
| Инфраструктура для AC8 (targeted mutation) реально существует | `scripts/mutation-gate.mjs` (issue #85) | подтверждено, не изобретённый инструмент |

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

## §7.1: обязательные разделы

Все обязательные разделы присутствуют и в правильном порядке: сценарий (§1) ·
что человек увидит (§2) · проблема/причина (§3) · контракт поведения (§4) ·
scope и не-scope (§5) · модель данных/миграция (§6) · UX/i18n/touch/security
(§7) · AC1…AC9 с доказательством (§8) · план автотестов (§9) · производительность
(§10) · риски (§11) · откат (§12) · ожидаемые файлы (§13) · release-артефакты
(§14) · явный блок принятых технических предположений (§15). Дополнительные
продуктовые разделы AGENTS.md (персона/поверхность/момент; что человек видит
одной фразой без терминов реализации) — оба на месте и написаны без терминов
реализации.

## Находки

Блокирующих (High) находок нет. Medium в скоупе или вне скоупа — нет.

Отмечено, но не является находкой (Low, снято без правки): §15 сознательно
оставляет способ построения пары владельцев `shared(A,B)` на усмотрение
реализации («может быть заменено ревьюером на эквивалентное без изменения
UX») — это ровно тот класс технического решения, который PROCESS.md §7.1
явно не выносит на продуктовый вопрос владельцу. Снимаю без правки: граница
между «непроверяемая догадка» и «явно объявленное техническое допущение»
соблюдена.

## Продуктовые вопросы владельцу

Отсутствуют, и это корректно: единственный продуктовый вопрос («ожидает ли
пользователь, что кнопка Optimize/Keep walls чинит толщину, а не портит её»)
уже отвечен самим фактом происхождения задачи — она заведена как P1-баг
против уже согласованного поведения (J6), а не как новый UX-контракт. Ни один
технический вопрос не был замаскирован под продуктовый и не был переадресован
владельцу — оба спорных технических места (owner-signature representation,
порядок интеграции с #298) явно решены в §15 как «принято предположительно,
поменять свободно», что и требуется вместо вопроса.

## AC — проверяемость и доказательство

AC1–AC9 однозначны, у каждого назван способ доказательства (unit table-driven,
real-plan regression, production-bundle smoke, targeted mutation, локальные
гейты). AC8 (мутационный тест на сам guard) — сильная защита от неполной
реализации, убивающая как «слишком мягкий» (не сравнивает владельцев), так и
«слишком строгий» (blanket-disable всей компакции) уклон; вместе с
позитивными assertions AC2 это заранее закрывает риск того, что фикс превратит
нормализацию в отключение слияния вообще (см. риск §11 и `AC2`).

## Что не проверялось

- Само исполнение тестов/гейтов — на этапе спек-ревью кода ещё нет, это
  предмет код-ревью (§2.7); проверка ограничена чтением ТЗ и сверкой с
  текущим состоянием репозитория.
- Полнота geometry-инвариантов (`npm run invariants`) не прогонялась — нет
  ещё изменения геометрии для прогона; будет предметом код-ревью.
- Не проверялся сам ADR #282 целиком построчно за пределами цитируемого
  исключения — прочитан фрагмент, относящийся к заявленному основанию.
- Актуальность `docs/USER-GUIDE.ru.md`/`CANVAS.md`/`UX-MODES.md` не сверялась
  построчно, так как ТЗ не меняет видимую поверхность/термины (§2, §7); при
  расхождении это всплывёт на код-ревью, когда будет реальный diff
  документации.

## Вердикт

Зелёный. ТЗ полно, каждый AC проверяем и привязан к способу доказательства,
технические предположения явно помечены и не выданы за факт, продуктовых
вопросов нет и не должно быть, скоуп и не-скоуп чётко разграничены и не
пересекаются с закрытыми #287/#289 и параллельным #298.