From 4c512fa59f9ea79828303cfdebff81ecaad6dca5 Mon Sep 17 00:00:00 2001 From: "claude[bot]" <209825114+claude[bot]@users.noreply.github.com> Date: Thu, 20 Aug 2026 10:47:39 +0000 Subject: [PATCH] docs: review document for #218 Issue: #218 User-Visible: no --- docs/reviews/SPEC-REVIEW-218-r2.md | 166 +++++++++++++++++++++++++++++ 1 file changed, 166 insertions(+) create mode 100644 docs/reviews/SPEC-REVIEW-218-r2.md diff --git a/docs/reviews/SPEC-REVIEW-218-r2.md b/docs/reviews/SPEC-REVIEW-218-r2.md new file mode 100644 index 00000000..cbea889d --- /dev/null +++ b/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 и корректно помечена +как предположение там, где она делает утверждение о текущем поведении кода. +Готово к разработке.