From 2890b9a1ab35e7305c8af10b14617e337ab2b83f Mon Sep 17 00:00:00 2001 From: "claude[bot]" <209825114+claude[bot]@users.noreply.github.com> Date: Fri, 28 Aug 2026 20:01:24 +0000 Subject: [PATCH] docs: review document for #209 Issue: #209 User-Visible: no --- docs/reviews/SPEC-REVIEW-209-r1.md | 145 +++++++++++++++++++++++++++++ 1 file changed, 145 insertions(+) create mode 100644 docs/reviews/SPEC-REVIEW-209-r1.md diff --git a/docs/reviews/SPEC-REVIEW-209-r1.md b/docs/reviews/SPEC-REVIEW-209-r1.md new file mode 100644 index 00000000..4c9ec721 --- /dev/null +++ b/docs/reviews/SPEC-REVIEW-209-r1.md @@ -0,0 +1,145 @@ +# SPEC-REVIEW — issue #209 · заход r1 + +- Этап: spec (PROCESS.md §2.4) +- Артефакт ТЗ: `docs/specs/209-vacuum-trail-smoothing.md` (SHA `43516cc1`, ветка `issue/209-vacuum-trail-smoothing`) +- Вердикт: **зелёный** +- Блокирующих циклов израсходовано: 0 из 4 + +## Скоуп ревью + +Первый раунд, дельта не применяется (§2.9 — правило дельты действует только +для r2+). Разобрано полностью: + +1. Тело issue #209 и все 3 комментария (анализ Codex, два решения владельца, + финальная передача на ревью). +2. Полный текст `docs/specs/209-vacuum-trail-smoothing.md`. +3. `docs/SCOPE.md` — соответствие Core user jobs. +4. `PROCESS.md` §2.4, §7.1 — обязательные разделы ТЗ и порог продуктовых + вопросов. +5. `docs/VACUUM.md`, `docs/USER-GUIDE.ru.md` (раздел «Позиция и путь»), + `docs/USER-GUIDE.md` (раздел «Robot vacuums»), `docs/ARCHITECTURE.md` — как + канонические источники терминологии и текущего контракта. +6. Исходный код `src/houseplan-card.ts` (`_renderVacuums`, ~11819–11905) и + `src/vacuum.ts` (`normalizeVacPath`, `resolveCurrentVacPath`, + `trimVacPathTarget`, `VAC_PATH_MAX_SEGMENTS/POINTS`, `TRAIL_MAX`) и + `custom_components/houseplan/trails.py` (`TRAIL_CAP`) — сверка каждого + факта, на который ссылается ТЗ. +7. `docs/TESTING.md` — существование `scripts/mutation-gate.mjs` и практики + мутационных гвардов, на которые ссылается план автотестов ТЗ. + +## Как проверялось + +Продуктовая часть (docs/SCOPE.md, персона, сценарий) читалась первой и +отдельно от технической, как требует §7.1. Технические утверждения ТЗ +(номера строк, имена функций, константы лимитов, порядок affine → build → +`_scenePoint()`) верифицированы построчным чтением текущего кода, а не +доверием тексту ТЗ. Отдельно перепроверено математическое обоснование предела +17,5 см в §6.2 (см. ниже) — это не тривиальное утверждение, и ложное +доказательство было бы поводом для High. + +## Находки + +Находок нет — ни High, ни Medium, ни Low. + +Разобранные кандидаты, которые не подтвердились как дефект: + +- **Отсутствие docs/USER-GUIDE.md (EN) в списке release-артефактов §13.** + Проверено: `docs/USER-GUIDE.md` раздел «16. Robot vacuums» не описывает + форму линии следа (M/L vs кривая) — он делегирует детали в `VACUUM.md` + одной фразой. `VACUUM.md` (канонический для этого контракта, EN) в списке + §13 присутствует. Правки нечего вносить в `USER-GUIDE.md`, значит его + отсутствие в перечне не является пропуском. +- **Утверждение issue-body про поверхность «статический рендер».** Тело issue + перечисляет «View, киоск, статический рендер» как поверхности показа следа. + Проверено: `src/space-card.ts` и `src/space-render.ts` (инертная + `houseplan-space-card`) не содержат ни одного упоминания vacuum/trail — + сейчас след там не рисуется. Само ТЗ, однако, этой ошибки не наследует: §1 + описывает только View/киоск/редакторы, а §4 Scope формулирует охват как + «поверхности, где след уже рисуется» — не перечисляя конкретный список. + §5 Non-scope прямо запрещает «добавление следа ... на поверхности, которые + его сейчас не имеют». Формулировка ТЗ самодостаточно корректна независимо + от неточности в исходном issue-анализе. +- **Математика предела в §6.2.** Проверено: для точки на `conv{P, B, Q}` + расстояние до `B` ограничено `r = min(17.5см, |AB|/2, |BC|/2)` в силу + выпуклости нормы (максимум выпуклой функции на симплексе достигается в + вершине); P и Q лежат на исходных отрезках, поэтому граница до исходной + ломаной действительно ≤ r ≤ 17,5 см. Отдельно проверено недопущение + наложения соседних скруглений: раз `r_B2 ≤ |s2|/2` и `r_B3 ≤ |s2|/2` для + общего отрезка `s2`, точка `Q` вершины `B2` не может оказаться дальше по + отрезку, чем точка `P` вершины `B3` — соседние скругления не меняются + местами. Довод в тексте ТЗ корректен, не голословен. +- **Эпсилон разворота ~180°.** Помечен явно как техническое решение автора + реализации, фиксируемое unit-тестом (§14 п.3), а не выдан за факт — это + ровно то отличие «предположения» от «незамеченной догадки», которое требует + проверять инструкция ревью. + +## Что проверено и корректно + +- **Персона/сценарий/до-после** — первые два раздела (§7.1) заполнены + корректно и без терминов реализации; соответствуют J1 (`docs/SCOPE.md`: + «Show the whole home and what's happening right now»). +- **Продуктовые вопросы владельцу** заданы по существу (граница сглаживания, + вкл/выкл, previous run) — все три ровно того типа, что разрешён §7.1 + («что видно», «объём видимых изменений»), без технических вопросов, + вынесенных наружу. Ответы получены и зафиксированы в issue до отправки ТЗ + на ревью — блокировка снята в срок. +- **Все обязательные разделы §7.1 присутствуют**: сценарий, до/после, + проблема, scope/non-scope, контракт поведения, UX/a11y/touch/i18n, модель + данных и совместимость, AC1–AC11 с методом доказательства для каждого, + план автотестов, риски, release-артефакты, откат. +- **AC однозначны и проверяемы**: каждый сформулирован как измеримое + утверждение (endpoints совпадают, отклонение ≤17,5 см, число команд ≤2N, + таблица режимов не меняется и т.д.), не «сделать нормально»/«работает как + ожидается». +- **Факты о коде подтверждены построчно**: `VAC_PATH_MAX_SEGMENTS = 64`, + `VAC_PATH_MAX_POINTS = 4000` (`src/vacuum.ts:14-15`), `TRAIL_MAX = 600` + (`src/vacuum.ts:477`), `TRAIL_CAP = 2000` + (`custom_components/houseplan/trails.py:27`), `resolveCurrentVacPath`, + `trimVacPathTarget`, `normalizeVacPath` (`src/vacuum.ts:169,201,222`) — + все совпадают с ТЗ. Текущий рендер (`_renderVacuums`, + `src/houseplan-card.ts:11819-11905`) действительно строит current как + единый `path` с `M`/`L` по подпутям и previous — отдельным `polyline` + (`:11855`), обе ветки применяют affine и затем `_scenePoint()` на каждую + точку — план ТЗ перенести этот порядок на «affine всего подпути → builder → + проекция» архитектурно согласован с существующим кодом, не выдумка. + `src/vacuum.ts` уже существует и уже владеет `normalizeVacPath`/ + `resolveCurrentVacPath`/`trimVacPathTarget` — ровно тот модуль, куда ТЗ + просит добавить pure builder (§9), это не новый файл и не смена владения. +- **Non-scope согласован со scope**: явно исключены изменения хранения, + лимитов, arbitration, trail modes, добавление следа туда, где его нет — + ни один пункт scope не противоречит этому списку. +- **Терминология согласована** с `docs/USER-GUIDE.ru.md` («Никогда/Во время + уборки/Всегда», «текущий путь»/«последний завершённый путь») — таблица + §6.4 ТЗ не меняет и не путает этот контракт. +- **i18n/touch/миграция/откат** — по каждому пункту явное «нет изменений» с + обоснованием, а не молчание. +- **Track = полный** обоснован верно: видимый контракт подачи меняется, + задействовано несколько поверхностей и golden-эталоны — критерий `small` + не проходит. +- **Продуктовая оценка (польза/сложность/риск)** реалистична и не + противоречит `docs/SCOPE.md`: ценность признана косметической (4/10), что + корректно для P3-полировки, не блокирующей и не требующей ускоренного + трека. + +## Чего не проверял + +- Реализацию — её не существует, стадия spec. +- `npx tsc --noEmit` / `npm test` / `npm run build` — не прогонял: гейт не + применим к этапу ревью ТЗ (нет кода для компиляции), а не пропущен по + экономии. +- Golden/смоки/инварианты модели — не прогонял: задача геометрию модели + (рёбра, `layout`, `marker.space`, `open_spans`) не трогает (явный + non-scope), это этап spec, инструментальные гейты этого раунда не + применимы. +- Не проверял, действительно ли выбранный владельцем способ (quadratic + Bézier по хордам) — лучший вариант из трёх предложенных в issue + (Catmull-Rom/Chaikin/Безье): ТЗ прямо отдаёт выбор техники автору + реализации, зафиксировав только измеримую границу (17,5 см) и семантику + (endpoints, gaps, no bridge) — это корректная граница ответственности + spec-ревью, а не пробел. + +## Итог + +ТЗ полное, однозначное, без выданных за факт догадок, предметно +верифицировано по коду и документам. Продуктовые вопросы владельцу заданы и +закрыты до отправки на ревью. Готово к статусу «Готово к разработке».