docs: review document for #218

Issue: #218
User-Visible: no

docs/reviews/SPEC-REVIEW-218-r2.md

@@ -0,0 +1,166 @@
+# SPEC-REVIEW-218-r2
+
+- **Issue:** #218 — одна комната с floating-point шумом в координатах гасит
+  свечение во всём пространстве
+- **Артефакт ТЗ:** `docs/specs/218-glow-floor-geometry.md`
+- **Ветка/SHA:** `issue/218-glow-floor-geometry` @ `72275de`
+- **Предыдущий раунд:** SPEC-REVIEW-218-r1.md @ `c6ff34c` (SHA назван явно —
+  в r1 SHA тоже был указан, повторного нарушения нет)
+- **Цикл:** r2/4
+- **Вердикт:** зелёный · High: 0 · Medium: 0
+
+## Скоуп ревью r2
+
+Это второй цикл — разбор по дельте (PROCESS.md §2.9/§2.10). Дельта — правки
+после r1, объявленная явно: `git diff c6ff34c..72275de -- docs/specs/218-glow-floor-geometry.md`
+(commit `72275de`, "docs: add risk analysis for glow geometry"; коммит
+`f9accc1` между ними — публикация самого документа r1-ревью, ТЗ не меняет).
+
+Дельта состоит из трёх правок одного файла:
+
+1. новый раздел **§15 «Риски»** (таблица риск/последствие/снижение + строка
+   про откат);
+2. переномерация разделов §15–§19 → §16–§20 из-за вставки;
+3. точечная правка **AC1** (§16, было AC1 в §15 r1) и новый пункт **6** в
+   «Принятых предположениях» (§20).
+
+Дельта локальна: новая подсистема не задета, контракт поведения не изменился,
+ребейза на `dev` не было (issue-ветка стоит на актуальном `dev`, коммиты между
+раундами — только доки этого же issue). Объём дельты (34 добавленные / 12
+удалённых строк в разделах «Риски» и AC1) несопоставим с исходным ТЗ (337
+строк) — критерий «разбор полным» из §2.10 не наступает. Сокращённый разбор
+корректен.
+
+Единственная находка r1 была одна (Medium, «Риски»), поэтому раздел «дельта
+плюс всё, до чего она дотягивается» здесь совпадает с самой дельтой: правка
+AC1 — часть того же коммита, который автор прислал как ответ на замечание, и
+именно эта правка меняет доказательство AC1, поэтому AC1 разобран заново
+(п.4 §2.10 — «AC, чьё доказательство дельта задевает»). Остальные AC2–AC10 не
+затронуты дельтой ни текстуально, ни по цепочке зависимостей — унаследованы
+без повторной проверки (см. раздел ниже).
+
+## Как проверялось
+
+- `git diff c6ff34c..72275de -- docs/specs/218-glow-floor-geometry.md` —
+  построчно, весь diff воспроизведён и сверен с текущим файлом
+  (`docs/specs/218-glow-floor-geometry.md:222–235` — §15; `:239–245` — AC1;
+  `:357–359` — assumption 6).
+- Сверка нового §15 с явным списком «Что чинить» из SPEC-REVIEW-218-r1.md
+  (4 обязательных пункта) — см. таблицу закрытия ниже.
+- Сверка перенумерации: `grep -n "§\d+"` по всему файлу — оба оставшихся
+  внутренних якоря (`§9` в §14, `§19` в §15) указывают на корректные разделы
+  после сдвига («Диагностика» и «Откат» соответственно); битых ссылок нет.
+- `docs/specs/README.md` и структура остальных разделов (`§1–§14`, `§17–§20`)
+  сверены на отсутствие случайных побочных правок — diff их не касается,
+  наблюдение подтверждено самим diff (единственный изменённый файл —
+  `218-glow-floor-geometry.md`, единственные секции diff — новый блок и
+  окружение AC1).
+- Трейлеры коммита `72275de`: `Issue: #218`, `User-Visible: no` — корректно
+  для правки только ТЗ.
+- AC1 передумано по существу (не просто «текст добавлен»): сверено с
+  §17.3 «Mutation gate» (`union-quantization-removed` → guard «AC1/AC2 unit»)
+  и с §16 AC2 (регрессия шестикомнатной fixture, red-before-fix). Разделение
+  ответственности «AC1 доказывает normalization contract через мутационный
+  red, AC2 доказывает сам баг через red-before-fix» внутренне согласовано —
+  ни один из двух AC не потерял свою «умеющую падать» проверку, они её просто
+  по-разному помечают.
+- Новая формулировка AC1 и assumption 6 сверены друг с другом: assumption 6
+  прямо признаёт, что простая пара прямоугольников с 1 ULP, по всей
+  видимости, не воспроизводит реальный сбой polyclip на сегодняшнем коде (сбой
+  требует конфликтующей многокомнатной топологии — это же прямо описано в
+  теле issue: `union(Кухня + Туалет) → FAIL` относится к паре с координатами
+  из реального экспорта, а не к произвольной синтетической паре). Это
+  корректно помечено как предположение (§20 п.6), а не выдано за факт —
+  соответствует правилу «размытое место помечается, а не додумывается».
+  Технически декларация не проверялась исполнением (кода ещё нет на этом
+  этапе), это ожидаемо для стадии `spec` и совпадает с ограничением, уже
+  зафиксированным в r1.
+- PROCESS.md §2.5 (DoR), §2.9/§2.10 (дельта-раунды), §7.1 (обязательные
+  разделы ТЗ), §7.2 (формат вердикта) — перечитаны для проверки, что новый
+  §15 закрывает именно пункт DoR «риски перечислены», а не просто заголовок.
+
+## Закрытие раунда r1
+
+| Находка r1 | Чем закрыта | Где это видно |
+|---|---|---|
+| Medium — отсутствует обязательный раздел «Риски» (только заголовка не было, содержательного свода тоже) | Добавлен раздел §15 «Риски» — таблица из 6 строк (риск/последствие/снижение и доказательство) + отдельная строка про безопасность отката | `docs/specs/218-glow-floor-geometry.md:222–235` |
+| → требование 1: риск для соседних потребителей общего `unionBodies()` | Строка 1 таблицы: «Квантование находится в общем `unionBodies()`, а не только в Glow» → мера: существующие wall/floor/physical-geometry tests и golden обязаны остаться зелёными | `:226` |
+| → требование 2: легаси-планы с перекрывающимися комнатами | Строка 2 таблицы: fallback может дать иное evenodd-покрытие → мера: fast path сохраняется, добавлена overlap-fixture | `:227` |
+| → требование 3: наблюдение Glow-base может не воспроизвестись той же причиной | Строка 3 таблицы: смоук фиксирует результат, при иной причине — отдельный issue только после подтверждения | `:228` |
+| → требование 4: стоимость полного mutation-gate для review-цикла | Строка 4 таблицы: перед S7 обязательны `--check` и целевые мутанты, полный реестр — предрелизный гейт | `:229` |
+| Low (снята с записью, без цикла) — неточная конверсия `1e-6` единицы плана в метры в §8.1 | Не тронуто и не требовалось: ревьюер r1 явно снял находку без цикла («правки не требую») | SPEC-REVIEW-218-r1.md, раздел «Low» |
+
+Все четыре обязательных пункта Medium закрыты содержательно, не только по
+заголовку — проверено построчным сравнением с текстом самой находки r1, а не
+принято на слово автора.
+
+## Унаследовано из r1
+
+Следующее принято без повторной проверки в r2, основание — SPEC-REVIEW-218-r1.md
+@ `c6ff34c`, поскольку дельта их не касается:
+
+- диагноз причины (§3 ТЗ, цепочка `_renderGlowLayer → intersectionPaths →
+  unionBodies → polyclip`) — сверен построчно с кодом в r1
+  (`src/physical-geometry.ts:224–275`, `src/houseplan-card.ts:14880–15117`);
+  дельта r2 эти разделы не меняет;
+- соответствие обязательным разделам §7.1 PROCESS.md (сценарий, что увидит
+  человек, scope/не-scope, контракт поведения, UX/accessibility/touch,
+  данные/i18n, архитектура, performance/security, план автотестов,
+  release-артефакты, откат) — подтверждено в r1, диффом r2 не затронуто, кроме
+  самого раздела «Риски» (закрыт выше) и AC1 (разобран заново выше);
+  AC2–AC10 не изменились текстуально относительно `c6ff34c` — сверено тем же
+  `git diff`, где только блок AC1 внутри списка помечен как изменённый;
+- соответствие `docs/SCOPE.md` (Core user job J1, «живая пространственная
+  картина происходящего сейчас», не расширяет радиус/цвет/opacity/blend/
+  visibility-алгоритм) — привязка не менялась, скоуп/не-скоуп раздел (§6/§7
+  ТЗ) не в дельте;
+- согласованность с `docs/LIGHT.md` и прецедентом #197
+  (`docs/WALL-THICKNESS.md:125,198,213`, `docs/ARCHITECTURE.md:414`) —
+  подтверждено в r1, разделы §4/§8.2 ТЗ, на которые опирается эта сверка, не
+  в дельте;
+- существование `demo/smoke_glow*.mjs`, `demo/benchmark_glow.mjs`,
+  `scripts/mutation-gate.mjs` и их формат — подтверждено в r1, дельта их не
+  упоминает заново;
+- отсутствие открытых продуктовых вопросов владельцу — подтверждено в r1
+  (сценарий и приоритет уже решены аналитикой владельца), дельта чисто
+  техническая и продуктовых вопросов не добавляет.
+
+## Проверка «догадка выдана за факт» (по дельте)
+
+Единственное новое фактическое утверждение дельты — assumption 6 (простая
+1-ULP пара, вероятно, не падает на текущем polyclip). Оно явно оформлено как
+предположение в §20, а не как решённый факт, и согласовано с эмпирикой issue
+(бинарный поиск владельца ловил сбой только на реальных многокомнатных парах
+координат, а не на произвольной синтетической паре). Нарушения не найдено.
+Остальные новые строки (таблица рисков) — оценочные, не фактические
+утверждения о поведении кода, эта проверка к ним неприменима.
+
+## Соответствие SCOPE.md / TOUCH-SUPPORT.md / CONFIG-COMPATIBILITY.md
+
+Не переоценивалось — дельта не касается ни персоны, ни поверхности, ни
+touch-контракта, ни конфига/схемы; выводы r1 наследуются целиком (см. раздел
+выше).
+
+## Чего не проверял
+
+- Реальный код и его исполнение — не проверялись и не должны на этапе `spec`;
+  ТЗ по-прежнему описывает будущую реализацию, кода нет.
+- Гейты `npx tsc --noEmit` / `npm test` / `npm run build` не гонялись: правка
+  этого раунда — исключительно документ `docs/specs/218-glow-floor-geometry.md`,
+  продуктовый код не менялся ни в этом коммите, ни с момента r1. Прогон этих
+  команд не проверил бы дельту и был бы потраченным временем без сигнала.
+- Полный повторный разбор AC2–AC10 не выполнялся — дельта их не задевает
+  (см. «Унаследовано из r1»); по правилу §2.10 п.4 это корректное сужение, а
+  не пропуск.
+- Точная эмпирика assumption 6 (падает ли реально простая ULP-пара на текущем
+  polyclip) не воспроизводилась запуском — на этапе `spec` нет кода для
+  запуска; заявление корректно помечено как предположение, а не как
+  проверенный факт, поэтому дальнейшая проверка не требуется до кода.
+
+## Вердикт
+
+Зелёный: High 0, Medium 0. Единственная находка r1 закрыта содержательно
+(раздел «Риски» с полным составом требуемых пунктов), сопутствующая правка
+AC1 внутренне согласована с mutation-gate таблицей и AC2 и корректно помечена
+как предположение там, где она делает утверждение о текущем поведении кода.
+Готово к разработке.