houseplan-card/docs/reviews/SPEC-REVIEW-276-r3.md

# SPEC-REVIEW-276-r3

- **Issue:** https://github.com/Matysh/houseplan-card/issues/276
- **Этап:** ТЗ на ревью (PROCESS.md §2.4)
- **Заход:** r3 · блокирующих циклов израсходовано 1 из 4 (r1 — красный, 1 цикл;
  r2 — зелёный, цикла не образует, #227)
- **ТЗ:** `docs/specs/276-coincident-partition-reconciliation.md`
- **Предыдущий раунд:** `docs/reviews/SPEC-REVIEW-276-r2.md`, вердикт зелёный,
  получен на commit `ca516643`
- **Вердикт:** зелёный · High: 0 · Medium: 0 · Low: 3 (все сняты с записью)

## Скоуп

Обычный трек, ТЗ — отдельный файл. Формальный диапазон дельты —
`ca516643..cfc8f211` (единственный тронутый файл — сам спек, 23 добавленные /
13 удалённых строк, подтверждено `git show --stat cfc8f211`).

**Разбор в этом раунде — полный, а не по дельте**, и вот почему. r3 не была
вызвана находкой ревью: после зелёного r2 автор взял issue в разработку,
проверил обе реально воспроизводимые проблемные оси на анонимизируемой fixture
и обнаружил, что вторая пара — не «room wall 20 + partition 20», как было
зафиксировано в §2 до этого раунда, а «room wall 30 + partition 20» (вложенная,
разной толщины). Ревьюированное условие r2 «`partition.cm` равна эффективной
толщине» (единственный допустимый случай — точное совпадение толщин) исправило
бы только первую пару и оставило бы вторую реальную пару в «неоднозначном»
статусе без изменений — то есть не решило бы заявленный в issue сценарий для
половины подтверждённого воспроизведения. Дельта переписывает эту часть
контракта: критерий приёмки (§4.4/§4.3), сама трансформация (§5.4), результат
для пользователя («увеличение не создаёт ступень», §3.4), не-скоуп (§8) и два
AC (AC1 текстуально не тронут, AC2 расширен). Это подпадает под явно
перечисленное в PROCESS §2.10 основание для полного разбора — «смена контракта
поведения»: раньше разнотолщинные пары были категорически исключены («Не
входит: разные толщины room wall и partition»), теперь одна из них (вложенная,
центрированная) канонизируется автоматически с итоговой толщиной `max`. Такое
расширение автоматического поведения Optimize нельзя проверить, доверившись
формулировкам r1/r2 — нужно заново прочитать весь документ и перепроверить его
математику и согласованность с остальными разделами.

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

- Перечитаны `docs/SCOPE.md`, `AGENTS.md`, `PROCESS.md` §2.4, §2.5, §2.10, §4,
  §7.1, §7.2 целиком.
- Прочитано тело issue #276 и все 14 комментариев (аналитика, связанные #277/
  #278, оба хендоффа автора ТЗ, оба вердикта r1/r2, техническая находка и
  техническая правка перед r3, обе SHA-корректировки).
- Найдены документы предыдущих раундов: `docs/reviews/SPEC-REVIEW-276-r1.md`
  (красный, commit `a06c94b9`) и `docs/reviews/SPEC-REVIEW-276-r2.md`
  (зелёный, commit `ca516643`) — оба уже закоммичены в ветку, SHA в обоих
  назван явно.
- Прочитан весь документ ТЗ целиком (294 строки, все 15 разделов), а не только
  дельта — согласно решению о полном разборе выше.
- Дельта явно объявлена и прочитана как патч: `git diff ca516643..cfc8f211 --
  docs/specs/276-coincident-partition-reconciliation.md`.
- Проверена математика центрального продуктового решения дельты (§3.4/§4.4):
  прочитан `src/physical-geometry.ts:192-226` (`physicalBodyParts()`,
  `halfDepth: wallCmToUnits(partition.cm, ...) / 2`) и
  `docs/WALL-THICKNESS.md` §2 («every thick wall grows half outward and half
  inward from the polygon edge») — подтверждено, что и room wall, и
  independent partition растут симметрично `±cm/2` от одной и той же
  centreline. Условие §4.2 требует точного endpoint-to-endpoint совпадения оси
  ⇒ у обоих тел одна и та же centreline. Union двух центрированных
  прямоугольных полос на одной оси математически точно равен более широкой
  полосе, т.е. `max(roomCm, partitionCm)` — не эвристика, а точное тождество,
  как и заявляет документ.
- Сверены все места дельты друг с другом на непротиворечивость: §3.4 ↔ §4.4 ↔
  §5.4 ↔ §8 ↔ §10.2 (риск) ↔ AC2 ↔ §15.2 (техпредположение) — единая
  формулировка `max(roomCm, partitionCm)` для centred exact bodies
  используется везде, кроме одного расхождения именования (см. L1 ниже).
  Отдельно проверено, что старая формулировка «Не входит: разные толщины room
  wall и partition» не осталась где-то ещё в файле:
  `grep -n "разные толщины" docs/specs/276-*.md` — 0 совпадений вне заменённой
  строки §8.
- Проверено согласование нового правила с AC5 (не тронут дельтой): «после
  20→10/30 существует ровно одно тело выбранной толщины» — совместимо с новым
  правилом, поскольку AC5 описывает поведение после Apply уже
  реконциолированной стены (Thickness работает штатно), а не сам момент
  reconciliation.
- Проверена идемпотентность (AC8) после нового правила: после Apply partition
  удалена, поэтому повторный `optimizePlans()` не находит кандидата вне
  зависимости от того, было ли обновление толщины — логической коллизии нет.
- Проверено соответствие §10.1 (файлы/модули, не тронут дельтой) дереву
  повторно: `src/plan-optimizer.ts`, `src/partition-openings.ts`,
  `src/plan-geometry-preflight.ts`, `src/houseplan-card.ts`,
  `test/plan-optimizer.test.mjs`, `test/partition-openings.test.mjs` — все
  существуют.
- Проверено соответствие названного будущего смока паттерну:
  `ls demo/smoke_optimize_*.mjs` — три существующих смока с тем же префиксом
  (`smoke_optimize_coordinate_canonicalization.mjs`,
  `smoke_optimize_geometry_preflight.mjs`, `smoke_optimize_micro_interval.mjs`),
  заявленное имя `demo/smoke_optimize_coincident_partition.mjs` соответствует
  конвенции и ещё не существует (корректно заявлено как новый файл).
- Проверена запись `docs/specs/README.md:73` — ссылка на файл спека
  двухсторонняя и не устарела.
- Проверена трассируемость коммита дельты: `git show cfc8f211` — единственный
  файл, трейлеры `Issue: #276` / `User-Visible: no` корректны (док-только
  правка, класс C, без изменения поведения кода). Хендофф-комментарий автора
  называет `Коммит: 2a8b64e7` — такого объекта не существует
  (`git cat-file -t 2a8b64e7` → «Not a valid object name»); фактический SHA
  дельты — `cfc8f211`, подтверждён последующим комментарием автора и временем
  коммита (05:03:58+03:00 = 02:03:58Z, комментарии-исправления в 02:04:02Z/
  02:04:08Z) — контент соответствует, ошибка только в указанном идентификаторе
  (см. L3 ниже).
- Гейты `typecheck`/`test`/`build`/`check-docs` не прогонялись: ни один коммит
  диапазона (a06c94b9..cfc8f211) не трогает `src/**`, продуктовый код не
  менялся ни разу за всю историю этой задачи. Неприменимо к спек-ревью того же
  основания, что в r1/r2.
- Browser smoke / golden / инварианты модели не прогонялись: geometry/wall код
  реализации ещё не написан.

## Закрытие раунда r2

r2 вернул зелёный вердикт без единой находки («Находки: Нет», Low о неверном
SHA был снят с записью, не возвращался автору) — таблицы «закрытых находок» в
классическом виде для r2 не существует, закрывать нечего. Единственное
замечание r2 («находка того же типа... автору стоит подставлять реальный SHA»)
адресовано на будущее, а не как блокирующее — и не было закрыто: то же самое
случилось снова в этом раунде (см. L3).

## Унаследовано из r2 — переподтверждено полным разбором, а не принято на веру

Раунд разобран полностью (см. «Скоуп» выше), поэтому ничего в этом списке не
принято слепо — каждый пункт перепрочитан в текущей редакции документа и
подтверждён не противоречащим дельте. Ссылка сохранена по требованию §2.10:
`docs/reviews/SPEC-REVIEW-276-r2.md`, SHA `ca516643`.

- Продуктовая рамка (§1 сценарий/персона, часть §2 про происхождение дефекта в
  коде) и её соответствие `docs/SCOPE.md` J4/J6 — не изменилась, только
  фактура второй реальной пары (30/20 вместо 20/20).
- Контракт one-shot server Undo без Redo (§6, AC7) — текст дельтой не тронут,
  перепроверен построчно повторно: расхождений с
  `_alignOptimizedConfirm`/`_undoPlanOptimization` и
  `docs/USER-GUIDE.ru.md:1444` не появилось.
- Разведение с #277 (Resize ambiguity) и #278 (wall-union fallback) — §8 не
  затронут в этой части.
- AC3, AC4, AC6, AC7, AC9–AC14 — тексты не менялись, доказательства указаны у
  каждого, перечитаны повторно на непротиворечивость с новым §4/§5 — не
  нашёл конфликта (hosted-opening rehost и preflight не зависят от того, какая
  толщина в итоге записывается).
- §10 (perf budget), §11 (touch) — не затронуты дельтой, перечитаны, риски и
  туч-контракт закрывают DoR §2.5 как и раньше.
- Preflight #199 (`src/plan-geometry-preflight.ts`,
  `test/plan-geometry-preflight.test.mjs`) — существует, перепроверено.

## Находки

Блокирующих (High/Medium) находок нет. Три Low, все сняты с записью — не
возвращаются автору.

### L1 (Low, снято с записью). Разное именование одной переменной в двух соседних формулах

**Где:** §4.4 (строка 81) пишет `max(sharedCm, partition.cm)`, а §3.4
(строка 59), §5.4 (строка 108) и таблица рисков §10.2 (строка 217) — везде
`max(roomCm, partitionCm)`. Оба обозначения означают одну и ту же величину
(эффективную толщину room-wall стороны атомарного shared interval до
преобразования), но использованы два разных identifier-имени
(`sharedCm`/`roomCm`) без объявленной синонимии. Не найдено других мест: `grep
-n "sharedCm"` даёт единственное совпадение (строка 81).

Не блокирует: контракт однозначен по смыслу в каждом отдельном разделе, значение
величины не расходится, автор реализации сам выбирает имя переменной в коде
(§7.1, «наименование» — техническое решение). Снимаю как редакционную
неточность, а не содержательное расхождение.

### L2 (Low, снято с записью). AC1 сохраняет квалификатор «same-thickness», хотя условие эксплицитно расширено дельтой

**Где:** §12, AC1 (строка 237): «Exact same-thickness shared-wall partition
определяется независимо от направления endpoints и порядка комнат» — текст не
тронут дельтой. После правки r3 условие §4.4 больше не требует совпадения
толщин (`partition.cm` теперь просто «конечна и положительна»), а AC2 явно
покрывает и same-cm, и narrower-, и wider-partition случаи. Формально AC1
по-прежнему описывает только частный (равнотолщинный) фрагмент детектора и не
противоречит остальному документу — это может быть намеренной декомпозицией
теста (AC1 проверяет инвариантность направления/порядка на самом простом
фикстуре, AC2 — полную матрицу толщин), но неявно, без пояснения такого
разделения обязанностей между AC1 и AC2.

Не блокирует: детектор направления/порядка действительно не зависит от
толщины, дублирования проверки по существу не создаёт риска для реализации, а
AC2 покрывает всю матрицу explicитно. Снимаю с записью — уточнение
формулировки AC1 (например, «на equal-cm fixture» вместо голого
«same-thickness») можно внести попутно при реализации, без нового цикла
ревью.

### L3 (Low, снято с записью). Второй подряд неверный SHA в хендофф-комментарии автора — повтор находки r2

**Где:** комментарий автора перед этим раундом называет «Коммит: `2a8b64e7`»
— `git cat-file -t 2a8b64e7` подтверждает: такого объекта в репозитории нет.
Фактический SHA дельты — `cfc8f211`, что сам автор поправил отдельным
комментарием четырьмя минутами позже. Содержание дельты соответствует
описанным правкам (проверено выше в «Как проверялось»), расхождение только в
идентификаторе.

Это дословно та же находка, что была снята как Low в
`docs/reviews/SPEC-REVIEW-276-r2.md` («находка того же типа, что требование
§2.10 "SHA в вердикте не назван — находка", только с обратной стороны — автору
стоит подставлять реальный SHA, а не плейсхолдер»), и она повторилась во
втором подряд хендоффе. Не блокирует ревью (автор сам публикует исправление
до начала разбора, содержание не пострадало), но заслуживает более заметной
записи, чем в прошлый раз: если паттерн проявится в третий раз, это стоит
поднять до Medium как систематическую проблему трассируемости, а не
разовую опечатку.

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

- **Центральное продуктовое решение дельты математически точное, а не
  эвристика на словах.** `max(roomCm, partitionCm)` для точно совпадающей по
  оси (endpoint-to-endpoint) центрированной пары действительно равен
  физическому union двух симметрично растущих `±cm/2` тел — подтверждено
  чтением кода роста стен (`physicalBodyParts()`,
  `wallCmToUnits(cm) / 2`) и `docs/WALL-THICKNESS.md` §2, не только текстом
  спека.
- **Причина возврата к ТЗ обоснована реальными данными, а не догадкой.**
  Вторая реально воспроизводимая пара (room wall 30 + partition 20) не была
  учтена ревьюированным в r2 условием «толщины обязаны совпадать» — без этой
  правки issue закрылась бы формально (AC2 матрица и unit-тесты прошли бы), но
  не решила бы половину заявленного в issue воспроизведения. Правка списка
  затронутых разделов (§3.4/§4.4/§5.4/§8/§10.2/AC2/§15.2) полная и
  внутренне согласованная (кроме L1/L2).
- **Явное разделение случаев, для которых `max` не применим, сохранено и
  расширено, а не ослаблено.** §8 теперь читает «неоднородный effective room
  profile, несколько coincident partitions либо конфликты, для которых один
  `max` не описывает исходный physical envelope» — то есть новое правило не
  тайно расширяет автоматизацию на составные/множественные конфликты, а
  остаётся строго в границах одного centred exact совпадения.
- **Расширение автоматического поведения Optimize не требует отдельного
  продуктового вопроса владельцу.** Формально это решение в «пограничном
  случае» (§7.1, класс продуктовых вопросов), но: (а) видимая пользователю
  толщина при этом не меняется — она и до, и после реконциляции равна
  видимому physical envelope union, который уже существовал (просто
  собранному из двух тел с артефактами боковой границы, а не из одного); (б)
  применяется только по явной команде «Оптимизировать» с preview/report и
  одноразовым Undo, уже принятыми продуктом ранее в этой же задаче — то есть
  ничего не меняется без осознанного действия и возможности отмены. Граница
  между техническим и продуктовым решением по §7.1 («что человек видит или
  делает») здесь на стороне «не видит нового» — считаю решение автора
  корректно техническим, эскалация владельцу не нужна.
- **DoR (§2.5) остаётся полностью закрыт.** Ни один обязательный раздел не
  исчез и не стал неполным дельтой: риски (§10.2) получили новую строку по
  этому же классу дефекта, затронутые файлы (§10.1) не изменились, AC
  пронумерованы с доказательством, откат (§14) не тронут и остаётся верным.
- **Трассируемость issue ↔ ТЗ ↔ ревью корректна**: оба предыдущих документа
  ревью существуют в дереве с точными SHA, ссылка `docs/specs/README.md:73`
  актуальна, коммит дельты несёт верные трейлеры класса C.

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

- Не запускал `npx tsc --noEmit` / `npm test` / `npm run build` / `node
  scripts/check-docs.mjs` — ни один коммит всего диапазона задачи
  (`a06c94b9`..`cfc8f211`) не трогает `src/**`; продуктовый код не менялся ни
  разу с начала этой задачи. Гейты реализации к спек-ревью неприменимы —
  то же основание, что в r1 и r2.
- Не запускал browser smoke / golden / инварианты модели (`model-invariants`)
  — geometry/wall-реализация ещё не написана, это код будущего раунда
  код-ревью. Инварианты (#254) станут обязательны там, когда появится
  экспорт/конфиг с реальной геометрией.
- Не проверял реальный анонимизируемый экспорт напрямую (файл не приложен, по
  тем же причинам, что в r1/r2) — доверяю описанию автора о второй паре
  «room wall 30 + partition 20», перепроверив только его математические
  следствия в документе, а не сам экспорт.
- Не оценивал трудозатраты/сложность реализации расширенной матрицы (7/10 в
  аналитике не пересматривался) — вне компетенции спек-ревью.

## Вывод

Блокирующих находок нет. Дельта r3 меняет контракт поведения (расширяет
автоматическую канонизацию с «только равные толщины» до «любая positive
partition thickness, итог — `max(roomCm, partitionCm)`»), что по PROCESS §2.10
требует полного разбора, а не разбора по дельте — этот разбор выполнен: вся
математика проверена по коду роста стен, а не принята на слова, все связанные
разделы (контракт, AC, риски, не-скоуп, техпредположения) согласованы друг с
другом. Три Low-находки (несовпадающее именование переменной, стилистически
устаревший квалификатор в AC1, повторный неверный SHA в хендоффе) не влияют на
корректность или проверяемость ТЗ и сняты с записью здесь. DoR (§2.5) закрыт
полностью, открытых продуктовых вопросов владельцу нет — расширение
автоматизации Optimize обосновано как техническое решение, не требующее
эскалации. ТЗ готово к `S5-ready`.