# SPEC-REVIEW-295-r2

Issue: #295
ТЗ: `docs/specs/295-preflight-diagnostics.md`
Ветка: `issue/295-preflight-diagnostics`, SHA материала ревью: `c3b4e3124e65a17693b44bb7fb02cbe291ea6633`
Заход: r2 · трек: обычный · лимит циклов 4 · блокирующих циклов израсходовано до этого ревью: 1/4

## Предыдущий раунд

Вердикт r1: жёлтый, High: 1 (H1), Medium: 1 (M1), Low: 2 (L1, L2).
Документ: `docs/reviews/SPEC-REVIEW-295-r1.md`.
SHA материала r1 в самом документе назван — `c1b5ceb6b42b5ef506c5c625037334fca6ddf877`
(коммит `c1b5ceb6 docs: spec for #295 preflight failure diagnostics`); в тексте
вердикта, оставленном в issue, SHA не приведён — это несоответствие отмечаю
здесь, само по себе не находка нового раунда (SHA был доступен в документе, на
который вердикт ссылался).

## Скоуп разбора r2

Правки r2 — точечные, диапазон `git diff c1b5ceb6..c3b4e312 -- docs/specs/295-preflight-diagnostics.md`:
изменения ограничены §1.1 (природа `detail`), частью §1.4 (пример JSON + разведение undefined/null),
§1.5 (канал версии интеграции), §2 (скоуп: добавлен `websocket_api.py`), новым пунктом
риска №4 в §4, и строкой статуса в шапке. Остальные разделы (§0, §1.2, §1.3, §3, §5, §6, §7, §8)
байт-в-байт совпадают с ревизией 1. Дельта локальна (правки по замечаниям одного раунда, без
ребейза, без смены подсистемы, без изменения контракта поведения за пределами того, что
просили H1/M1/L1/L2) — разбор по PROCESS.md §2.9 сужен до дельты и её последствий.

## Как проверялось

1. `git diff c1b5ceb6..c3b4e312 -- docs/specs/295-preflight-diagnostics.md` — построчно, что именно изменилось.
2. Проверка закрытия H1: перечитан барьер #199 в коде (`src/plan-geometry-preflight.ts:312-397` —
   актуальные номера строк на HEAD, включая тело `checkOptimizeGeometry` целиком) и три существующих
   privacy-теста (`test/plan-geometry-preflight.test.mjs:110-146`) — прогнал их логику вручную против
   нового дизайна (`detail = error.name`), не изменяя код.
3. Проверка закрытия M1: `custom_components/houseplan/websocket_api.py` — текущий ответ
   `ws_config_get` (`:1114-1161`) и блок импортов (`:21-68`, `VERSION` там не импортирован);
   `custom_components/houseplan/const.py:49` (`VERSION = "1.68.0-beta.1"`); `import_export.py:526`
   (то же поле в бэкапе) — подтвердил, что предложенное решение (добавить `integration_version`
   в `houseplan/config/get`, импортировав `VERSION` из `.const`) технически осуществимо тем же
   паттерном, что уже применён для бэкапов. `src/houseplan-card.ts:320` — `CARD_VERSION` существует
   на фронте, есть с чем сравнивать.
4. Проверка L1/L2 — текстовая сверка новой формулировки §1.4 и нового пункта риска №4 с тем, что
   просил r1.
5. Побочная проверка: не бросает ли что-то в `src` не-`Error` значение, что имело бы значение для
   ветки «typeof error» в §1.1 — `grep 'throw ['"'"'"`]'` по `src/` → 0 совпадений, ветка не критична
   для текущего кода, но не создаёт проблемы.
6. Проверил, что governing docs (`docs/SCOPE.md`, `AGENTS.md`, `PROCESS.md`, `docs/CANVAS.md`,
   `docs/ARCHITECTURE.md`) не менялись между SHA r1 и SHA r2 (`git log -1 -- <файл>` даёт более
   ранние коммиты, чем `c1b5ceb6`) — основания вывода r1 по этим документам не протухли,
   наследую без повторного чтения содержимого.

Тяжёлые гейты (typecheck/test/build/смоки) не гонялись — этап ревью ТЗ, кода нет.

## Закрытие раунда r1

| Находка | Чем закрыта | Где это видно |
|---|---|---|
| H1 (High) — контракт тихо отменял барьер #199 (`detail` = сырой `error.message`) | Выбран вариант (а) из r1 с усилением: `detail` = класс исключения (`error.name`, для не-`Error` — `typeof`), только для причин `*-exception`. Barrier-текст «exception text never escapes» не задет: класс — не содержимое. Три существующих privacy-теста (`test/plan-geometry-preflight.test.mjs:123-145`) продолжат проходить без изменений — все используют `new Error(...)`, значит `detail` станет `'Error'`, что не матчится ни с одним `assert.doesNotMatch` (`/secret/`, `/private floor detail/`, `/private preparation detail/`). Проверено чтением: логику подставил вручную, не исполняя. | `docs/specs/295-preflight-diagnostics.md:18` (§1.1, новая формулировка) |
| M1 (Medium) — предикат версии ссылался на несуществующий канал | Явное решение: бэкенд `websocket_api.py` добавляет `integration_version` в ответ `houseplan/config/get`, зеркально `import_export.py:526`; `websocket_api.py` внесён в затронутые файлы (+ тест). Технически чисто: `VERSION` уже есть в `const.py:49`, паттерн `"integration_version": VERSION` уже применяется в `import_export.py:526`, нужен только импорт в `websocket_api.py`. Фронт имеет `CARD_VERSION` (`src/houseplan-card.ts:320`) для сравнения. | `docs/specs/295-preflight-diagnostics.md:61` (§1.5), `:65` (§2, скоуп) |
| L1 (Low) — `detail: null` пример расходился с «поле не заполняется» | Разведено прямо текстом: в результате preflight — `undefined` (поле отсутствует), в JSON-блоке диагностики — явный `null` через `failure.detail ?? null`. | `docs/specs/295-preflight-diagnostics.md:51,57` |
| L2 (Low) — не было явного пункта о производительности | Добавлен риск №4 в §4: «не затрагивается» с обоснованием (ok-путь без новых операций, лог дедуплицирован). | `docs/specs/295-preflight-diagnostics.md:77` |

Все четыре находки r1 закрыты фактическим текстом ТЗ, а не заявлением автора — сверено построчно
против диффа и против кода, который эти формулировки описывают.

## Унаследовано из r1

Без повторной проверки в этом раунде — дельта их не касается, взято из
`docs/reviews/SPEC-REVIEW-295-r1.md` (материал на SHA `c1b5ceb6b42b5ef506c5c625037334fca6ddf877`):

- Обязательные разделы §7.1 PROCESS.md присутствуют и не тронуты правкой (сценарий/До-После,
  скоуп/не-скоуп, UX/данные/i18n/touch, AC с доказательствами, план тестов, откат,
  release-артефакты) — раздел за разделом сверен в r1 «Что проверено и корректно».
- Фактическая база о текущем коде (7 значений `OptimizeGeometryFailureReason`, отсутствие
  i18n-ключей `preflight_reason_*`, диалог печатает только имена, две точки вычисления preflight,
  шесть потребителей `checkSpacePhysicalGeometry` читают только `.ok`) — подтверждена в r1 чтением
  кода на той же ветке; правка r2 эти места не трогала.
- Соответствие docs/SCOPE.md (задача не создаёт нового Core user job, делает диагностируемым
  существующий административный инструмент, ближе к J6) — оценка из r1, скоуп задачи в r2 не
  расширился за пределы одного дополнительного backend-файла, уже находкой M1 предусмотренного.
- Откат (§8) — один revert, без модели/миграций — раздел байт-в-байт не менялся.
- Мутанты §5.7 используют существующий паттерн `mutation-gate.test.mjs`, клипборд-фолбэк повторяет
  существующий UI-паттерн того же диалога — оценка из r1, разделы не менялись.
- Замечание r1 про нестандартный вид ключей i18n (дефис в хвосте `preflight_reason_wall-degraded-extra`) —
  оставлено как не блокирующее в r1, раздел §1.2 в r2 не менялся, вывод не пересматриваю.

## Новые находки r2

Нет. Правки r1→r2 закрывают все четыре находки предыдущего раунда корректно по существу, не
привнося нового расхождения с кодом или документами. Отдельно проверил, не сломала ли правка
что-то, ранее признанное верным (риск регрессии вроде #102): пример из §1.4 и текст §1.1
взаимно согласованы, задетые тесты (`plan-geometry-preflight.test.mjs`) остаются зелёными по
приведённой выше логике, governing docs не требуют правки — и это явно, а не по умолчанию,
подтверждено самим текстом ревизии 2, а не только заявлено.

## Чего не проверял

- Реализацию (кода ещё нет) — этап ревью ТЗ.
- Разделы §0, §1.2, §1.3, §3, §5, §6, §7, §8 заново — не изменились в дельте r1→r2, унаследованы
  из r1 без повторного построчного чтения кода, который они описывают (только сверил, что текст
  файла в этих местах идентичен ревизии 1 через diff).
- `docs/USER-GUIDE.ru.md` текущую формулировку раздела «Оптимизировать» — как и в r1, финальный
  текст является предметом код-ревью, не блокирует спеку.
- Не гонял тяжёлые гейты (typecheck/test/build/смоки/инварианты) — кода нет, гонять нечего.

## Вывод

Обе блокирующие/скоупные находки r1 (H1, M1) закрыты по существу и подтверждены по коду, а не
только текстом автора. Low-находки устранены. Новых находок в дельте r2 нет. Разбор был сужен до
дельты по PROCESS.md §2.9, так как дельта локальна: правки точечные, ответ на конкретные замечания
предыдущего раунда, без ребейза и без смены подсистемы.

**Вердикт: зелёный · заход r2 · блокирующих циклов 1/4 · High: 0 · Medium: 0**