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

# SPEC-REVIEW — issue #475 · заход r1

**Тема:** `mutation-gate --check` не отличает живого свидетеля от мёртвого —
добавить отбор мутантов по диффу («гард») и запуск на каждом пуше.
**Трек:** лёгкий (`small`). ТЗ живёт в теле issue (комментарий «ТЗ готово»,
2026-09-06T10:54:23Z). Файла в `docs/specs/` нет и не должно быть.
**Класс изменения:** B (гейты и инструменты) — `scripts/mutation-gate.mjs`,
`test/mutation-gate.test.mjs`, `.github/workflows/validate.yml`. Ни одного
файла класса A не затронуто.

## Скоуп

Расширить `selectChangedMutants` так, чтобы мутант считался задетым диффом не
только по `patch.file`, но и по файлам своего гарда (тест/смок), и подключить
`--changed` как блокирующий job `validate.yml` на каждом пуше. Цель — сократить
разрыв между поломкой свидетеля и её обнаружением с «неделя/релиз» до «тот же
пуш» (мотивирующий инцидент — #466/#467).

`docs/SCOPE.md` этот класс задач не ограничивает: это не пользовательская
функция ни для одной из персон, а инструмент инженерного качества (по типу
`042-backend-engineering-quality.md`); видимого поведения продукта нет, что и
делает трек лёгким и ставит его вне вопроса «какую строку Core user jobs
закрывает». `docs/USER-GUIDE.ru.md` неприменим — интерфейса нет.

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

Прочитано: `docs/SCOPE.md`, `AGENTS.md`, `PROCESS.md` целиком, тело issue #475
и оба комментария (S2-анализ и ТЗ). Код читался, не исполнялся:

- `scripts/mutation-gate.mjs` — существующие `selectChangedMutants`,
  `shardMutants`, ветка `--changed` в `main()`, весь `MUTANT_DEFINITIONS`
  (60+ мутантов, все варианты `guard:`);
- `.github/workflows/validate.yml` — job `changes` (классификация `frontend` /
  `backend` / `integration`, вывод `base`/`range_base`), job `frontend`
  (`if: needs.changes.outputs.frontend == 'true'`), job `backend`
  (`if: needs.changes.outputs.backend == 'true' ...`);
- подтверждено, что `test/validate-workflow.test.mjs` уже существует —
  «контрактный тест на YAML», на который ссылается доказательство AC4, не
  изобретённая сущность, а существующий паттерн.

Гейты не гонялись: диапазон материала — только тело issue, продуктового кода
нет, `typecheck`/`test`/`build` к тексту ТЗ неприменимы на этой стадии.

## Находки

### Medium (в скоупе задачи) — job и `guardFiles()` не покрывают гарды бэкенда, хотя они уже есть в реестре

**Файл:** тело issue #475, разделы «1. Отбор по диффу…» и «2. `--changed`
гоняется на каждом пуше».

Контракт заявлен без ограничения по подсистеме: «мутант считается затронутым,
если дифф содержит любой `patch.file` **или** любой файл, на который
ссылается его `guard`» — и мотивирующий сценарий («тест перестал ходить по
мутированной ветке») сформулирован в S2-разборе тоже без оговорки
«только фронтенд». Но два независимых сужения в самом же контракте молча
исключают уже существующие бэкенд-мутанты:

1. **Извлечение файлов гарда** ограничено суффиксами `.mjs`/`.test.mjs`. В
   реестре (`scripts/mutation-gate.mjs:121-159`) четыре мутанта
   (`frontend-registration-skips-retry`,
   `frontend-registration-retries-without-delay`,
   `frontend-registration-is-not-unload-bound`,
   `frontend-reload-notice-forgets-persisted-flag`) патчат
   `custom_components/houseplan/frontend_registration.py` и охраняются
   напрямую `python3 -m pytest tests_backend/test_ha_frontend_registration.py
   -k "..."` — токен `tests_backend/test_ha_frontend_registration.py`
   оканчивается на `.py` и по объявленному правилу файлом гарда не
   считается вовсе.
2. **Триггер job** — `needs.changes.outputs.frontend == 'true'` (плюс правка
   самого `mutation-gate.mjs`). Паттерн `frontend` в job `changes`
   (`.github/workflows/validate.yml:281`) — `^(src/|demo/|test/|dist/|
   custom_components/houseplan/frontend/|package(-lock)?\.json$|
   rollup\.config\.mjs$|tsconfig)` — не включает ни `tests_backend/`, ни
   `custom_components/houseplan/frontend_registration.py` (последний
   попадает под отдельный паттерн `backend`,
   `^(custom_components/.*\.py$|tests_backend/|...)`, строка 282). Диапазон
   диффа, задевающий только `custom_components/houseplan/frontend_registration.py`
   и/или `tests_backend/test_ha_frontend_registration.py`, выставляет
   `backend=true`, но не `frontend=true` — и по объявленному условию job
   «Мутанты по диффу» вообще не запустится.

**Воспроизведение (по коду, без запуска):** диапазон, меняющий строку
`entry.async_on_unload(state.cancel)` на `pass` в
`custom_components/houseplan/frontend_registration.py` и одновременно
ослабляющий соответствующую проверку в
`tests_backend/test_ha_frontend_registration.py` (буквально сценарий
«гард перестал ходить», ради которого написан этот контракт) — задевает
только паттерн `backend`. `changes.outputs.frontend` остаётся `false`, job
«Мутанты по диффу» не запускается (условие в п.2 ТЗ), значит ни AC1, ни
предполагаемый AC2 для этого мутанта не проверяются ни на одном пуше — свежая
поломка живого свидетеля здесь снова обнаружится только полным еженедельным
прогоном, то есть именно тот разрыв, ради закрытия которого заведён #475,
для этой части реестра остаётся ровно тем же, что и до задачи.

AC6 воспроизводит только фронтенд-случай (`src/wall-merge.ts`,
`multi-wall-*`), поэтому по документу проверить это не на чем — а
существующая часть реестра, для которой контракт молча не работает, реальна
и приведена выше, не гипотетична.

Это не продуктовый вопрос — граница чисто техническая (какое условие триггера
job, какие суффиксы допускает `guardFiles`), значит по §7.1 её решает автор, а
не владелец. Но граница должна быть решена явно — либо расширить условие
триггера до `frontend == 'true' || backend == 'true' || mutation-gate.mjs
изменён` и расширить извлечение токенов гарда суффиксом `.py`, либо, если
бэкенд-гарды сознательно остаются вне этой задачи, написать это прямо рядом с
уже объявленной границей про фикстуры — сейчас в тексте объявлена только
одна граница (фикстуры), а фактическая шире.

**Чем закрывается:** AC2 (или новый AC) должен явно называть исход для
бэкенд-патченных/бэкенд-охраняемых мутантов, и триггер job — соответствовать
этому исходу. Один из двух путей выше, зафиксированный в тексте issue.

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

- Обязательные для лёгкого трека разделы (§5): проблема · контракт · AC1…AC6
  с доказательством · откат — все присутствуют, ни один не пропущен.
- Каждый AC однозначен и называет способ доказательства (unit / контрактный
  тест на YAML), доказательство реалистично: `test/validate-workflow.test.mjs`
  для проверки структуры `validate.yml` уже существует как паттерн (AC4).
- База диапазона `needs.changes.outputs.base` / `range_base` (#387/#388) —
  существующая инфраструктура, а не изобретённая; подтверждена и в коде
  (`.github/workflows/validate.yml:182-190`), и в S2-комментарии владельца.
- Отказ от «отметки последнего доказательства» из исходного текста issue —
  явное техническое решение с приведённой причиной (кому обновлять отметку),
  не догадка, выданная за факт.
- Граница по фикстурам гарда (`test/fixtures/*` не выводятся из команды) —
  объявлена прямо и признана самим автором как известное ограничение; это не
  находка, а корректно зафиксированное решение.
- Ранний зелёный выход при пустой выборке — уже реализован в
  `main()`/`--changed` (`scripts/mutation-gate.mjs`, ветка `if (!selected.length)`
  до вызова `runCleanGuards`), так что AC5 доказуем без новой логики.
- Критерии лёгкого трека (§5) не нарушены: сложность ≤3 по факту одной
  логической поверхности (отбор мутантов + его подключение в CI), нет
  миграции конфига, нет нового UX-контракта (контракта UX не существует —
  инструмент внутренний), нет влияния на touch; влияние на длительность
  прогона названо и посчитано приемлемым (S2-комментарий).
- Продуктовый код не затронут ни одним файлом (класс A отсутствует), значит
  вопрос «какую строку Core user jobs закрывает» к этой задаче неприменим по
  типу задачи, а не пропущен.

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

- Не запускал `node scripts/mutation-gate.mjs --changed=...` и не писал сам
  тест — на стадии ревью ТЗ кода ещё нет, это предмет код-ревью (§2.7).
- Не проверял полный список всех 60+ мутантов на предмет других суффиксов
  гарда, отличных от `.mjs`/`.test.mjs`/`.py` (например, составные команды с
  `tsc`/`fix-test-build.mjs`) — выборочно просмотрел реестр целиком через
  `grep`, других расширений файлов-целей, кроме `.mjs`, `.test.mjs` и `.py`,
  не встретил.
- Не оценивал производительность самого job на реальном CI (стоимость сборки
  бандла при непустой выборке) — S2-комментарий называет её «минуты», и это
  вне ревью ТЗ, оценка возможна только по факту в код-ревью.

## Вердикт

Вердикт: жёлтый · заход r1 · блокирующих циклов 1/2 · High: 0 · Medium: 1 → в задаче · Документ: (этот файл)

---

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

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

- Ветка: `dev`, коммит `` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
- Якоря снять не удалось: ветки задачи нет, материал читался по `dev`.