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

# SPEC-REVIEW-492-r1

Issue: #492 «CI: проверять точный кандидат интеграции и полный набор зависимостей selection/reuse»
Этап: ТЗ на ревью (PROCESS.md §2.4). Трек: полный (не `small`) — ТЗ живёт в
`docs/specs/492-exact-candidate-and-input-manifest.md`.
Заход: r1 · блокирующих циклов израсходовано 0 из 4.

## Скоуп

Предмет ревью — файл `docs/specs/492-exact-candidate-and-input-manifest.md`
(174 строки) и обновление `docs/specs/README.md`, оба из коммита `941c7cff`
на ветке `issue/492-exact-candidate-and-input-manifest`. Материал не менялся
между заходами (r1, предыдущих раундов не было — единственный комментарий в
issue — аналитика S2, не вердикт ревью).

Класс задачи по AGENTS.md: issue заявлен `infra`/`P1`/`tech-debt`, ни одного
файла класса A ни в ТЗ, ни в перечне «Затронутых файлов» (§12 ТЗ). По
механическому признаку AGENTS.md такая задача могла бы идти вне S-флоу вовсе;
автор явно называет это в комментарии S2 и ведёт задачу по меткам ради
ревью конвейером, ссылаясь на прецедент того же рода — #472, #475, #481
(все — gate-инфраструктура, все проверены: #472 и #481 закрыты через полный
S1…S8, #475 — `small`, полный S1…S8 тоже пройден, класс файлов везде B/C/D).
Прецедент подтверждён напрямую (`gh issue view`), это корректная и уже
устоявшаяся практика репозитория, а не самовольное расширение флоу. Первый
вопрос «какую строку Core user jobs закрывает задача» здесь неприменим по
предмету: `docs/SCOPE.md` описывает продуктовые обязательства перед тремя
персонами, а #492 правит собственный процесс проверки (`PROCESS.md`,
`.github/workflows/**`), у которого пользователя-персоны в смысле SCOPE.md
нет — сценарий и адресаты корректно названы в §1.1 ТЗ как «автор задачи,
ревьюер, обслуживающий чат, владелец, читающий статусы».

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

- Прочитаны целиком `docs/SCOPE.md`, `AGENTS.md`, `PROCESS.md` (весь файл,
  включая §1–§10.4: классы файлов, лёгкий/полный трек, лимит циклов §4,
  обязательные разделы ТЗ §7.1, шаблоны вердиктов §7.2, гейты §8).
- Прочитано тело issue #492 и единственный комментарий (аналитика владельца,
  S2), где подтверждены источники аудита по SHA.
- **Каждое фактическое техническое утверждение §1 ТЗ проверено чтением кода на
  цитируемом SHA `ea6061e9`, а не принято на слово:**
  - п.1 (слияние): `.github/workflows/process.yml` на `ea6061e9` — шаг «Слить
    ветку в dev» действительно делает `git rebase origin/dev`, затем сразу
    `git push … HEAD:dev` без какой-либо проверки нового дерева между ребейзом
    и push; шаг «dev ушёл вперёд» только комментирует, не блокирует (строки
    ~917–969 файла на этом SHA). Подтверждено.
  - п.2 (реюз бэкенда): `scripts/gate-reuse.mjs` на `ea6061e9` —
    `HARNESS.backend.roots` = `['tests_backend', 'custom_components',
    'pytest.ini', 'scripts/backend-coverage-baseline.txt', 'pyproject.toml']`
    — не включает `scripts/support-relay/**`, `scripts/sh3d-convert/**`,
    `scripts/config-schema.json`, `scripts/dump-config-schema.py`; при этом
    `reuseKey` подмешивает `sourceFingerprint(root)` (полный `src/**`) во
    **все** job без исключения, включая `backend`. `scripts/classify-changes.mjs`
    на том же SHA: регэксп `backend` содержит `scripts/support-relay/`, но не
    `pyproject.toml` и не `scripts/sh3d-convert/`. Оба утверждения — и «relay
    классифицируется как backend, но не входит в ключ реюза», и «pyproject/
    sh3d-convert не классифицируются вовсе» — подтверждены буквально.
  - п.4 (мутанты): `scripts/backend-test-guard.mjs` на `ea6061e9` — третий
    аргумент (`testFile`) действительно опционален с дефолтом
    `tests_backend/test_ha_import_export.py`; `grep` по `mutation-gate.mjs`
    даёт 35 использований этого гарда, что согласуется с «10 из 35 без
    третьего аргумента» (точное число 10 не пересчитывалось построчно —
    порядок величины и факт существования дефолта подтверждены, этого
    достаточно для проверки формулировки проблемы на этапе ТЗ).
  - Ни одно техническое утверждение раздела «Проблема» не оказалось догадкой,
    выданной за факт — все проверяемые пункты подтвердились чтением
    процитированного SHA.
- Сверены оба направления связи issue ↔ ТЗ: issue #492 не содержит прямой
  ссылки на файл ТЗ в теле (обычно это делает владелец/автор отдельной правкой
  либо ссылка остаётся в `docs/specs/README.md` — она на месте), сам файл ТЗ
  ссылается на issue первой строкой; `docs/specs/README.md` содержит строку
  `#492` → `492-exact-candidate-and-input-manifest.md`. Связь двусторонняя по
  факту (README + текст ТЗ), проверено чтением диффа коммита `941c7cff`.
- Проверено соответствие обязательных разделов §7.1 PROCESS.md: сценарий
  (§1.1), что человек увидит до/после (§1.2), проблема (§1), скоуп/не-скоуп
  (§2/§3), контракт поведения (§4–§8), UX/модель данных/i18n (§10.1, явное
  «не затрагиваются» — корректно для infra), критерии приёмки (§10, AC1–AC10),
  риски (§10.2), откат (§9), release-артефакты (§11) — все присутствуют.
  Отдельного раздела «план автотестов» под таким заголовком нет, но по
  содержанию план распределён по §8 (пять групп отрицательных тестов с
  конкретными представителями и файлами) и §12 (перечень новых/правимых
  `test/*.test.mjs`) — это не пропуск, а другая раскладка того же
  содержания; не самостоятельная находка.
- Проверена внутренняя согласуемость: таблица категорий манифеста (§5.1)
  сверена построчно со списком представителей §8.1 — каждая категория
  (`source`/`tests`/`fixtures`/`config`/`toolchain`/`protocol`) имеет хотя бы
  один представитель в негативных тестах, кроме `tests` (уже покрыта
  существующим корнем `tests_backend` в текущем `HARNESS`, поэтому не входит
  в список **новых** гарантий). Список из «шести мутантов на протокол» в §13
  и §8.5 совпадает поимённо (6 пунктов).
- По каждому AC1–AC10 отдельно проверено, к какому пункту §8 (или §7) он
  привязан как доказательство — см. находку ниже, единственный разрыв на
  AC6.
- Дешёвые гейты не прогонялись отдельно: Validate на `941c7cff` зелёный
  (ссылка дана в постановке задачи), а класс изменений — только `docs/**`
  (класса C), код не менялся. `typecheck`/`test`/`build`/`check-docs`
  нерелевантны этапу ТЗ и этому диффу.

## Находки

### Medium (в скоупе задачи) — AC6 не называет способ доказательства

**Файл:** `docs/specs/492-exact-candidate-and-input-manifest.md`, AC6 (раздел
10) и §5.3.

AC6 формулирует защитное утверждение: «`backend` не зависит от `src/**` —
включено последним коммитом после AC4–AC5». Это ровно тот тип критерия,
для которого PROCESS.md §2.5 требует явно назвать способ доказательства
(`unit`/`backend`/`smoke`/`golden`/«ревью кода»), а последующее код-ревью
(§2.7) потребует таблицу «AC · чем доказан · чем краснеет» — но в
доступном виде оно уже должно быть заложено на этапе ТЗ, как это сделано
для AC1–AC5, AC7–AC9 через §8.1–§8.5.

Для AC1–AC5 и AC7–AC10 каждое утверждение имеет прямую привязку к
конкретному пункту §8 (представитель, отрицательный тест или таблица
случаев). Для AC6 такой привязки нет: §8.1 перечисляет представителей всех
шести проверок (`frontend` через `src/**` там не фигурирует ни разу как
объект отрицательного теста), а §5.3 лишь описывает механизм («ключ = хеш
`inputsOf(job)`, `sourceFingerprint` уходит») без утверждения, что где-то
проверяется обратное: что правка файла из `src/**` **не** меняет ключ
`backend` после финального коммита.

**Сценарий отказа:** реализация выполняет AC1–AC5, AC7–AC10 с тестами, но
финальный коммит AC6 сводится к удалению строки `source:
sourceFingerprint(root)` из вычисления ключа `backend` без теста. Регресс
(кто-то по невнимательности вернёт эту строку в будущей правке
`check-inputs.mjs`, или `inputsOf('backend')` по ошибке продолжит включать
`src/**` через общий `source`-манифест) не поймает ни один автотест —
ровно то поведение, которое всё ТЗ ставит целью исключить («Зелёный вердикт
обязан означать, что именно этот код проверен»), окажется непроверенным
для собственного шестого критерия.

**Почему это Medium, а не High:** AC6 не блокирует остальные девять
критериев и не делает ТЗ невыполнимым — пробел локален и дёшево чинится:
одна строка в §8.1 (представитель — файл `src/**`, например
`src/houseplan-card.ts`; ожидание — ключ `backend` **не** меняется, ключ
`frontend`/`smoke` меняется) плюс одноимённый пункт в перечне тестов §12
(`test/gate-reuse.test.mjs`). Находка в скоупе задачи (сам AC6 уже в §10) —
чинится в этом же ТЗ, отдельный issue не заводится.

## Что проверено и корректно

- Все пять пунктов раздела «Проблема» (§1) фактически подтверждены чтением
  кода на процитированном SHA `ea6061e9` — ни одно не оказалось домыслом
  (детали — выше, «Как проверялось»).
- Скоуп/не-скоуп (§2/§3) чётко разграничивают протокол проверки от
  содержания самих проверок и от продуктового кода; при обнаружении
  продуктового дефекта явно предписан отдельный issue — соответствует
  правилу «Medium вне скоупа = новый issue» на будущее код-ревью.
- §4 (точный кандидат) корректно устраняет реальный, только что
  подтверждённый чтением дефект — push без проверки между ребейзом и push;
  алгоритм п.1–7 покрывает все ветвления (dev не двигался / двигался с
  равным patch-id / двигался с другим patch-id / Validate красный / lease
  отклонён / попытки исчерпаны), и каждое ветвление имеет счётчик выхода в
  статус (`S6`/`S7`/`S8`) без зависания.
- §6 (замыкание входов гарда) адресует ровно найденный технический дефект
  (10 из 35 гардов без третьего аргумента, `trail-resume-test-guard.mjs`
  скрывает пути тестов) явно объявляемым `GUARD_INPUTS` и статическим
  замыканием импортов — реализуемо без исполнения кода на этапе отбора.
  Точечность выбора по стороне патча внутри `src/**` явно вынесена в
  не-скоуп (§3, §6.4) — не оставлена недосказанной.
- §7 (ночной прогон) — минимальная точечная правка, устраняющая
  единственный названный дефект (успех в момент постановки в очередь).
- §9 (откат) корректен для infra-задачи без продуктового кода: revert
  коммитов, отдельно назван риск устаревания старых маркеров реюза (один
  лишний полный прогон, не сбой).
- Раздел «Принятые предположения» (§13) содержит только технические решения
  (эквивалентность Validate на ветке проверке дерева; PAT остаётся PAT;
  порядок реализации) и явно помечен как «принято предположительно,
  поменять свободно» — соответствует PROCESS.md §7.1: продуктовых вопросов
  к владельцу нет и не должно быть, поскольку задача не имеет
  пользовательской поверхности в смысле `docs/SCOPE.md`.
- AC1–AC5, AC7–AC10 однозначны и проверяемы, каждый имеет прямую привязку к
  конкретному отрицательному тесту или таблице случаев в §8.
- Формат ТЗ и связь issue ↔ ТЗ ↔ README соблюдены; трек (полный, не
  `small`) выбран верно — задача касается четырёх поверхностей протокола
  CI одновременно, что явно нарушает критерий «одна поверхность» лёгкого
  трека (сам ТЗ называет это прямо: «Трек: полный … без файлов класса A»).

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

- Реализацию по существу — на этом этапе её нет, в diff'е только
  `docs/specs/**` и `docs/specs/README.md` (оба класса C). Код-ревью
  впереди.
- Точный подсчёт «10 из 35» гардов без третьего аргумента (§1 п.4) — вручную
  не пересчитывал каждое из 35 вхождений `backend-test-guard.mjs` в
  `mutation-gate.mjs`; подтверждён факт существования дефолтного значения и
  порядок величины через `grep -c`, этого достаточно для проверки
  формулировки проблемы, но не является независимым пересчётом точного
  числа.
- Достижимость таймингов §10.2 (5–8 мин ожидания Validate внутри ревью-job,
  лимит 45 мин, «десятки минут в 3 шардах» для расширенного отбора
  мутантов) — это оценки автора на будущее, эксплуатационная проверка
  относится к пост-мержу/код-ревью, не к ТЗ.
- Тяжёлые гейты (`golden`, `smoke`, `performance_smoke`, backend pytest) —
  не прогонялись: diff класса C, изменений в `src/**`/`custom_components/**`
  нет, гейты нерелевантны этапу и типу изменений.
- Прецеденты #472/#475/#481 проверены только по метаданным issue
  (`gh issue view`: заголовок, метки, состояние) и списку файлов
  `docs/reviews/` — содержимое их спек-документов построчно не сверялось с
  #492, кроме одного (`SPEC-REVIEW-481-r1.md`), прочитанного как образец
  формата и калибровки серьёзности находок для infra-специфики.

## Вердикт

Жёлтый. High: 0, Medium: 1 (в скоупе задачи — чинится в этом же ТЗ, отдельный
issue не заводится). Пробел дешёвый: одна строка в §8.1 плюс один тестовый
файл в §12.

---

<!-- material-anchors: сгенерировано конвейером (#414) -->

## Материал раунда

- Ветка: `issue/492-exact-candidate-and-input-manifest`, коммит `941c7cff7a1b` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
- Дерево материала: `b9b9b1a2171c2cafd5f24cf83b1d6c5baa2fbb6b`
  ```
  git log --all --format='%H %T' | grep b9b9b1a2171c
  ```
- ТЗ `docs/specs/492-exact-candidate-and-input-manifest.md`, блоб `2fcaeb946e984a30e0188a15ebed904eb3d31b7d`
  ```
  git log --all --find-object=2fcaeb946e984a30e0188a15ebed904eb3d31b7d -- docs/specs/492-exact-candidate-and-input-manifest.md
  ```