houseplan-card/docs/reviews/SPEC-REVIEW-209-r1.md

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-ревью, а не пробел.

Итог

ТЗ полное, однозначное, без выданных за факт догадок, предметно верифицировано по коду и документам. Продуктовые вопросы владельцу заданы и закрыты до отправки на ревью. Готово к статусу «Готово к разработке».