docs: review document for #276

Issue: #276
User-Visible: no

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

@@ -0,0 +1,276 @@
+# 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`.