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

# SPEC-REVIEW-399-r2

- Issue: https://github.com/Matysh/houseplan-card/issues/399
- ТЗ: `docs/specs/399-backend-gate-honesty.md`
- Материал: SHA `6d229c66f1e25460b6cc7efcbb67a88a723a3acb` (ветка
  `issue/399-backend-gate-honesty`, ревизия 2 поверх `dev`)
- Заход: **r2**, не r1 — см. «Расхождение с заданием раунда» ниже
- Блокирующих циклов израсходовано: 1/4 (израсходован r1, жёлтый; зелёный
  цикла не тратит, #227)
- Трек: полный (не изменился, наследуется из r1)
- Вердикт: **жёлтый**

## Расхождение с заданием раунда (нужно проговорить явно)

Задание на этот прогон присвоило заходу номер r1 и указало
«блокирующих циклов израсходовано 0 из 4». Это не соответствует
фактическому состоянию:

- `docs/reviews/SPEC-REVIEW-399-r1.md` уже существует в репозитории
  (коммит `627a5359`) — это реальный, опубликованный документ ревью, а не
  черновик;
- на issue #399 уже есть комментарий-вердикт `Вердикт: жёлтый · заход r1 ·
  блокирующих циклов 0/4 · High: 0 · Medium: 1 → в задаче`, оставленный
  ревьюером;
- автор ответил на этот вердикт комментарием «Ревизия 2 — Medium закрыт» и
  запушил `6d229c66 docs: #399 spec revision 2 per SPEC-REVIEW-399-r1`,
  который редактирует ровно ту находку, которую назвал r1.

То есть цикл r1 реально состоялся и стоил бюджета (жёлтый, 1/4). Присвоение
этому прогону имени `r1` создало бы `docs/reviews/SPEC-REVIEW-399-r1.md` поверх
уже существующего документа — ровно тот сценарий, от которого предостерегает
инструкция «два документа с одинаковым номером затёрли бы друг друга».
Поэтому документ и вердикт этого прогона используют номер **r2**, полученный
из фактического состояния issue и репозитория, а не из присланного
заголовка задания. Далее применяется процедура §2.9/§2.10 для «не первого»
цикла: делта, закрытие r1, наследование.

## Дельта, которая является предметом этого раунда

`git diff a1d7e0da..6d229c66 -- docs/specs/399-backend-gate-honesty.md`
— ровно три хунка:

1. строка «Ревизия» в шапке (2, с указанием, что правка отвечает на
   SPEC-REVIEW-399-r1);
2. абзац контракта в разделе «(3) Low «в»» — добавлено явное описание
   «второй половины дыры» (жёстко заданный массив `['validate.yml',
   'mutation-gate.yml']`) и переформулирован контракт: перебор идёт по
   **каталогу** `.github/workflows/*.yml`, для каждого файла ровно два
   исхода (ставит зависимости бэкенда → пины; не ставит → доказывается явно,
   не через отсутствие подстроки);
3. **AC5** переписан под тот же контракт: доказательство — тест на
   синтетическом каталоге, где новый (третий) workflow ставит `pip install
   pytest` без версий и обязан краснеть; плюс зафиксирован факт «сегодня в
   репозитории девять workflow, установку python-зависимостей делают два».

Ничего за пределами этих трёх хунков не менялось: разделы про M3 (пин
фронтенда) и Low «а» (скоуп ruff), скоуп/не-скоуп, AC1–AC4/AC6, риски,
откат, release-артефакты — байт в байт те же, что видел r1.

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

| Находка r1 | Чем закрыта | Где видно |
|---|---|---|
| Medium: AC5 не фиксирует, перебор по каталогу `.github/workflows/*.yml` или по жёстко заданному списку из двух имён — обе версии формально проходят AC4/AC5, но только первая закрывает цель issue буквально | Контракт п.(3) и AC5 переписаны: явно требуется перебор **каталога**, а не списка; для каждого файла — либо пины, либо явное («не ставит») доказательство отсутствия установки, не через отсутствие подстроки; доказательство AC5 теперь называет синтетический каталог с **третьим** workflow, которого в старом списке из двух не было бы | `docs/specs/399-backend-gate-honesty.md:82-94` (контракт), `:136-144` (AC5), SHA `6d229c66` |

Находка закрыта по существу: слабое прочтение (а) из r1 (список из двух
файлов, замена implicit `continue` на explicit skip-list **внутри тех же
двух**) текстом контракта теперь прямо исключено — новый p.(3) требует
перебора каталога, а не редактирования списка. Это единственная версия,
которую r1 признавал закрывающей issue буквально.

## Унаследовано из r1 (без повторной проверки)

Со ссылкой на `docs/reviews/SPEC-REVIEW-399-r1.md`, SHA `a1d7e0da`:

- §7.1: все обязательные разделы на месте (сценарий, что увидит человек,
  проблема по пунктам, скоуп/не-скоуп, UX/данные/i18n — н/п обоснованно,
  AC с доказательствами, план автотестов, риски, откат, release-артефакты)
  — делта их не трогает, кроме плана автотестов (см. новую находку ниже).
- Классификация трека (полный, класс B, три несвязанные поверхности) —
  делта не меняет ни поверхности, ни причину.
- Технические утверждения о разделах (1) M3 и (2) Low «а» — номера строк,
  содержимое `tests_backend/requirements.txt:29`, `pyproject.toml:5`,
  `.github/workflows/validate.yml:787-788` — делта их не касается, r1 их
  построчно сверил.
- AC1, AC2, AC3, AC4, AC6 — текст не менялся этой ревизией, доказательства
  оценены r1 как однозначные.
- Продуктовое обрамление и персоны SCOPE.md (задача инфраструктурная,
  J-строка не затронута) — не изменилось.
- «Чего не проверял» из r1 (сеть для `package_constraints.txt`, объём
  ruff-долга, аудит-документ вне репозитория) — остаётся в силе, делта
  этих вопросов не касается.

## Новая находка этого раунда

### Medium (в скоупе) — «План автотестов» (п.4) не обновлён вслед за AC5 и описывает как раз ту слабую версию, которую контракт теперь запрещает

**Файл**: `docs/specs/399-backend-gate-honesty.md:155` (раздел «План
автотестов», пункт 4 списка Unit-тестов).

**Текст сейчас**: «Явный список обходимых файлов зафиксирован; добавление
нового файла в workflows без обновления списка краснеет (AC5).»

**В чём разрыв**: это дословно формулировка **старой** (ревизия 1) версии
AC5 — «перечисление файлов, которые проверка обходит, зафиксировано в самом
тесте» — которую сам автор в этой же ревизии заменил на «перебор каталога, а
не фиксированного списка имён» (строка 137). Пункт 4 плана автотестов не
редактировался в этой ревизии (его нет в диффе), и он по-прежнему описывает
работу через **список**, который требуется вручную **обновлять** при
появлении нового файла — то есть ту самую конструкцию, о которой новый
контракт п.(3) говорит: «доказывается явно… а не выводится из отсутствия
подстроки [и не из членства в списке]».

Смысловая разница не косметическая. Реализация, которая берёт «План
автотестов» как техническое задание для теста (а не прозу AC5 несколькими
абзацами выше), может на законных основаниях построить: `readdirSync` +
хардкод-массив «эти N файлов не ставят python-зависимостей» + фейл, если имя
нового файла не найдено ни в списке пиновых, ни в списке-исключений. Такая
реализация проходит буквальный текст п.4 («список… краснеет при отсутствии
файла в нём»), но именно она возвращает эксплуатационную нагрузку —
необходимость вручную поддерживать список — которую контракт п.(3) и
переписанный AC5 сознательно убрали («доказывается явно… а не выводится из
отсутствия подстроки»). Расхождение между двумя разделами одного и того же
ТЗ — тот же класс дыры, что и находка r1: AC/раздел проходятся двумя
существенно разными реализациями, только на этот раз конфликт не внутри
одного AC, а между «Критериями приёмки» и «Планом автотестов».

Это не гипотетическая тонкость: п.4 — единственное место в документе, где
явно описано, ЧТО проверяет unit-тест для AC5, и оно противоречит только что
исправленному AC5 в этом же файле.

**Почему не High**: реализация всё равно проходит написанные тесты в любом
из двух прочтений, продуктового кода нет, откат тривиален. Это вопрос
формулировки одного ТЗ-раздела, а не невозможности выполнить задачу.

**Почему Medium, а не Low**: буквальный текст, на который будет смотреть
исполнитель при написании теста, указывает в сторону реализации, которую сам
документ (двумя разделами выше) явно отверг. Это создаёт тот же риск
«формально выполнено, но не решает то, из-за чего заведено», который r1 уже
один раз поймал в AC5 — здесь тот же риск переехал в соседний раздел
вследствие правки, а не был там с начала (в ревизии 1 AC5 и п.4 плана
автотестов формулировались одинаково слабо и не противоречили друг другу;
конфликт появился именно этой правкой). Правится в этой же задаче (#202 не
применяется — находка в скоупе).

**Как закрыть**: одна строка. Например: «4. Синтетический каталог
`.github/workflows/*.yml`, где один из файлов не входит в набор
`validate.yml`/`mutation-gate.yml`, ставит `pip install pytest` без версий и
не имеет явного маркера «не устанавливает python-зависимости» — тест
краснеет; никакого списка имён для ручного обновления в реализации нет
(AC5).» Дёшево: правка одного предложения, план автотестов приводится в
соответствие с уже переписанным AC5.

## Что проверено и корректно (в дополнение к унаследованному)

- Новый факт в AC5 «в репозитории девять workflow, установку
  python-зависимостей делают два» — перепроверен на текущем дереве:
  `ls .github/workflows/*.yml` даёт ровно 9 файлов; `git grep -l "pip
  install" .github/workflows/*.yml` даёт ровно `mutation-gate.yml` и
  `validate.yml`. Число и состав совпадают дословно.
- Переписанный контракт п.(3) и AC5 внутренне непротиворечивы друг другу
  (оба говорят про каталог, оба про «явное доказательство отсутствия
  установки», оба про мутанта с третьим workflow) — конфликт только с планом
  автотестов, описанным выше.
- Правка не меняет трек, скоуп/не-скоуп, риски и не переносит вопрос
  владельцу — расширение контракта («перебор каталога») лежит внутри уже
  согласованной цели issue («отсутствие обеих зацепок — отказ, а не
  пропуск»), это техническое уточнение, а не продуктовое решение (§7.1: не
  выносится владельцу).
- Заголовок «Ревизия 2» корректно ссылается на SPEC-REVIEW-399-r1 —
  трассировка причины правки на месте.

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

- Сетевое содержимое `package_constraints.txt` тега `2026.8.3`
  `home-assistant/core` (претензия M3) — как и в r1, недоступно в этой
  среде; не блокирует, AC1 требует доказательства без сети, число будет
  видно на код-ревью.
- Объём ruff-долга при исходе (2) для Low «а» — не факт, требующий проверки
  на этом этапе; делта его не касается.
- `npm test`/`npx tsc --noEmit`/`npm run build` — это ревью документа
  (ТЗ), а не кода; правка не трогает `src/**`/`custom_components/**`, гейты
  кода к этому этапу не относятся и будут прогнаны на код-ревью.
- Аудит-документ `AUDIT-2026-08-31-v1700beta1.md` вне репозитория — как и
  в r1, не найден локально, тело issue самодостаточно.

## Вердикт

Жёлтый: единственная блокирующая находка — Medium, без High. Прежняя
Medium-находка (AC5: список vs каталог) закрыта; ревизией 2 введена новая
Medium-находка того же семейства в соседнем разделе («План автотестов»,
п.4). Автор приводит формулировку п.4 в соответствие с переписанным AC5 и
проходит ещё один заход ревью ТЗ (полный трек, лимит 4 цикла, израсходован
1/4 после r1; после этого раунда — 2/4).