houseplan-card/docs/process/REVIEWER.md

# Конспект для ревьюера

Роли: ревьюер ТЗ и ревьюер кода ([§6](../../PROCESS.md#6-роли)). Штатный
ревьюер конвейера получает этот файл из промпта `.github/workflows/_process.yml`;
ручное ревью по просьбе владельца идёт по нему же.

> **Это выжимка, а не канон.** Канон процесса — [`PROCESS.md`](../../PROCESS.md);
> при расхождении побеждает он, а расхождение — issue с меткой `process`.
> Конспект правил не добавляет и не меняет: каждый пункт ссылается на раздел
> канона, где правило записано полностью, с причинами и прецедентами. Ссылки и
> ключевые формулировки сверяет `test/process-digests.test.mjs`.

## Позиция ревьюера

- Ревьюер ≠ исполнитель, свежая сессия без контекста реализации. Задача —
  не согласиться, а найти, где ТЗ не выполнимо или не проверяемо, где код не
  делает заявленного ([§2.4](../../PROCESS.md#24-тз-на-ревью),
  [§2.7](../../PROCESS.md#27-код-ревью), [§6](../../PROCESS.md#6-роли)).
- Ревьюер не правит ни ТЗ, ни продуктовый код; ревью своей работы запрещено
  ([§6](../../PROCESS.md#6-роли), [§12](../../PROCESS.md#12-запрещено)).
- Первый вопрос к задаче — какую работу из `docs/SCOPE.md` она обслуживает;
  для видимого поведения терминология берётся из `docs/USER-GUIDE.ru.md`
  ([§7.1](../../PROCESS.md#71-цепочка)).

## Ревью ТЗ

- Артефакт — `docs/reviews/SPEC-REVIEW-<NN>-r<N>.md`. Ревью ТЗ проходит только
  трек `ask` ([§2.4](../../PROCESS.md#24-тз-на-ревью)).
- ТЗ живёт в теле issue, раздел `## ТЗ`; `docs/specs/` — архив до 2026-09-10
  ([§2.3](../../PROCESS.md#23-тз-в-работе--написание-тз)).
- Проверить обязательные разделы, однозначность каждого AC и способ его
  доказательства; догадка, записанная как факт, — находка
  ([§7.1](../../PROCESS.md#71-цепочка),
  [§2.5](../../PROCESS.md#25-готово-к-разработке-dor)).
- Владельцу задаются только продуктовые вопросы; технический вопрос,
  вынесенный владельцу, ревьюер снимает и решает по существу. Технический
  спор автора и ревьюера решается вердиктом, а не владельцем
  ([§7.1](../../PROCESS.md#71-цепочка)).
- Черновик автора ревьюер ТЗ не читает и доводом не считает: судится тело
  issue ([§2.4](../../PROCESS.md#24-тз-на-ревью),
  [§11.8](../../PROCESS.md#118-черновик-кода-во-время-ревью-тз)).

## Код-ревью

- Артефакт — `docs/reviews/CODE-REVIEW-<tag|NN>-r<N>.md`: скоуп, как
  проверялось (таблица гейтов с результатами), находки High/Medium/Low с
  воспроизведением, что проверено и корректно, чего не проверял
  ([§2.7](../../PROCESS.md#27-код-ревью)).
- Ревьюер отвечает за полноту доказательств AC, а не заменяет их исполнение.
  Каждый AC либо доказан автотестом, и ревьюер убедился, что тест умеет
  падать, либо разобран с записью «проверено чтением, не исполнением».
  Применимые классы риска §2.6 сверяются отдельно
  ([§2.7](../../PROCESS.md#27-код-ревью),
  [§2.6](../../PROCESS.md#26-в-разработке--реализация)).
- Защитный AC доказывается таблицей «чем краснеет»: AC · чем доказан ·
  чем краснеет — мутант в реестре или отрицательный случай в самом тесте.
  Пустой третий столбец — находка Medium, а не примечание. «Тест умеет
  падать» без названной мутации доказательством не является
  ([§2.7](../../PROCESS.md#27-код-ревью)).
- Вердикт привязан к SHA (#312): числа и факты сверяются с
  `git rev-parse HEAD` перед итогом; более новый коммит, которого нет в
  материале, — находка, а не повод его подтянуть
  ([§2.7](../../PROCESS.md#27-код-ревью),
  [§10.4](../../PROCESS.md#104-событийный-конвейер-метка-как-триггер)).
- Контракты по монолиту — исполнением, не regex по тексту: список тестов,
  читающих монолит как текст, заморожен, и новое имя в нём — находка ревью, а
  не запись в список ([§2.7](../../PROCESS.md#27-код-ревью)).
- Трейлеры `Issue: #NN` и `User-Visible: yes|no` на каждом коммите класса A и
  B; при `yes` — оба changelog в том же коммите
  ([§3 п.10](../../PROCESS.md#3-правила)).
- Одно число — один источник: ревьюер отвечает на вопрос прямо: какое число в
  этом диффе видно дважды и один ли у него источник
  ([§8](../../PROCESS.md#8-гейты)).

## Объём гейтов

- Всегда: `typecheck`, `npm test`, `npm run build` + `bundle-policy --verify` (копии сверяются только на кандидате, #657).
  Свежесть скриншотов документации — не гейт задачи: отпечаток обновляет
  коммит бота на `dev` перед бетой. Зелёный Validate на SHA материала
  подтверждает дешёвые гейты ([§8](../../PROCESS.md#8-гейты)).
- По диффу и AC: смоки — названные в AC плюс вывод
  `node scripts/smoke-select.mjs --base <base> --head <head>` с решением по
  каждой строке; `golden:verify` при метке `ci:golden`; `pytest tests_backend`
  при правке Python; инварианты модели при правке геометрии; performance —
  если назван в AC. Полные наборы — предрелизный гейт, а не гейт ревью
  ([§8](../../PROCESS.md#8-гейты)).
- Три ответа `smoke-select` разные: прямое совпадение и зарегистрированная
  связь — прогон; «НЕОПРЕДЕЛЁННОСТЬ» — связь не доказана, и это не разрешение
  ничего не прогонять; слабая связь — повод посмотреть, а не обязанность
  прогонять ([`docs/TESTING.md`](../TESTING.md#локальный-набор-перед-пушем-343),
  [§8](../../PROCESS.md#8-гейты)).
- Инварианты модели — `npm run invariants -- --config <экспорт>` при правке
  геометрии или ссылок на неё (#254): задача меняет геометрию, а инварианты в
  отчёте не названы — это непрогнанный гейт, а не мелочь
  ([§8](../../PROCESS.md#8-гейты)).
- Условие честности сужения: ревьюер обязан перечислить, какие гейты прогнал,
  какие нет и почему ([§8](../../PROCESS.md#8-гейты)).
- Зелёный `pytest tests_backend` без Home Assistant `test_ha_*.py` не
  собирает вовсе — их нет ни в `passed`, ни в `skipped` (строка `HA harness NOT
  collected`), и такой прогон про HA ничего не доказывает — это «чего не
  проверял» (`docs/TESTING.md`; [§8](../../PROCESS.md#8-гейты)).

## Повторный раунд

- Предмет повторного раунда — дельта, а не задача целиком: найти вердикт и
  материал предыдущего раунда (блок «Материал раунда»), объявить
  `git diff <тот SHA>..HEAD` (для ТЗ — дифф тела issue или архивного файла ТЗ),
  по каждой находке показать, чем она закрыта — строкой кода или текста, а не
  заявлением автора, — заново проверить только AC, которые дельта задевает
  ([§2.10](../../PROCESS.md#210-повторный-раунд-ревью--объём-по-дельте)).
- Если SHA не резолвится — это не находка, а обычное дело: материал ищется по
  дереву и блобу. Находка — SHA, мёртвый уже в момент публикации отчёта
  ([§2.10](../../PROCESS.md#210-повторный-раунд-ревью--объём-по-дельте)).
- Обязателен раздел «Унаследовано из r<N−1>»: что принято без повторной
  проверки, с документом и материалом того раунда
  ([§2.10](../../PROCESS.md#210-повторный-раунд-ревью--объём-по-дельте)).
- Разбор остаётся полным, если дельта не локальна: ребейз на ушедший вперёд
  `dev`, смена контракта, новая подсистема, объём сопоставим с задачей.
  Сомнение в локальности — полный разбор с названной причиной. Сокращается
  объём разбора, а не строгость
  ([§2.10](../../PROCESS.md#210-повторный-раунд-ревью--объём-по-дельте)).
- Перед разбором подсистемы — её строки в `docs/reviews/INDEX.md`
  ([§2.10](../../PROCESS.md#210-повторный-раунд-ревью--объём-по-дельте)).

## Находки и вердикт

- High блокирует. Medium в скоупе чинится в текущем issue: без High это жёлтый
  вердикт и повторный цикл. Medium вне скоупа — отдельный issue со ссылкой.
  Low правится или снимается ревьюером с записью
  ([§3 п.8](../../PROCESS.md#3-правила),
  [§2.7](../../PROCESS.md#27-код-ревью)).
- Жёлтый вердикт допустим и при выполненных AC, если изменение не решает
  заявленный сценарий или ухудшает смежный; продуктовое рассуждение не
  отменяет AC и не меняет скоуп ([§2.7](../../PROCESS.md#27-код-ревью)).
- Строка вердикта, первой строкой комментария:
  `Вердикт: зелёный/жёлтый/красный · заход r<N> · блокирующих циклов K/<лимит> · High: N · Medium: N → в задаче | #… · Документ: docs/reviews/…`
  («→ #…» — только у Medium вне скоупа)
  ([§7.2](../../PROCESS.md#72-шаблоны-комментариев)).
- Вперёд двигает только зелёный вердикт; жёлтый и красный возвращают автору
  ([§7.2](../../PROCESS.md#72-шаблоны-комментариев)).
- Зелёный вердикт цикла не образует; лимит — 4 цикла, на `track:show` 2;
  бюджет считается по этапу и один на все треки задачи; вердикт, исчерпавший
  бюджет, сразу ставит `review-4`
  ([§4](../../PROCESS.md#4-лимит-циклов-ревью-4),
  [§10.4](../../PROCESS.md#104-событийный-конвейер-метка-как-триггер)).
- Запрещено: Medium-находки, оставленные как TODO в документе ревью;
  ревью-документы вне репозитория ([§12](../../PROCESS.md#12-запрещено)).

## Трек show

- Ревью `show` судит корректность и AC: Medium — дефект поведения, который
  увидит пользователь, или невыполненный AC; бухгалтерия — нет мутанта или
  записи в реестре, нечувствительный тест на побочный вызов — Low и цикла не
  открывает ([§10.4](../../PROCESS.md#104-событийный-конвейер-метка-как-триггер),
  [§5](../../PROCESS.md#5-треки-ship-show-ask--метка-владельца)).
- Мутанты в разработке не гоняются ни на каком треке — ревьюер их тоже не
  применяет; проверяет, что защита названа мутантом в реестре. Отсутствие прогона
  не находка: поимку проверяет ночь (#709,
  [§2.7](../../PROCESS.md#27-код-ревью)).
- Ветка `show` с чистым слиянием к `dev` до ревью не приводится: материал —
  ветка как есть, кандидат проверит Validate при слиянии
  ([§10.4](../../PROCESS.md#104-событийный-конвейер-метка-как-триггер)).
- Промпт несёт риск по изменённым участкам: по каждому классу назови документ
  или AC, где поведение уже зафиксировано; не нашёл — вердикт с
  `route: reclassify` и названным критерием. `show`, подтверждённый
  владельцем, конвейер не повышает — `blocked` и вопрос владельцу, вариант по
  умолчанию «повысить до `ask`»; на `ask` — сверить, что каждый класс покрыт
  AC ТЗ ([§5](../../PROCESS.md#5-треки-ship-show-ask--метка-владельца)).
- Поле `route` вердикта (#726): на код-ревью `show` — `reclassify` и
  `criterion` (`complexity`, `surfaces`, `migration`, `ux-contract`,
  `perf-touch`, `undocumented`), если задача не проходит критерий §5; иначе и
  на прочих этапах и треках — `fix`. `reclassify` — только не зелёный вердикт;
  трек и метки меняет конвейер, не ревьюер
  ([§5](../../PROCESS.md#5-треки-ship-show-ask--метка-владельца),
  [§10.4](../../PROCESS.md#104-событийный-конвейер-метка-как-триггер)).
- Визуальный риск в пути отрисовки плана без `ci:golden`: если задача меняет
  вид, нужен `ci:golden`; иначе — запись в «чего не проверял»
  ([§5.1](../../PROCESS.md#51-метки-тяжёлых-проверок-и-прежние-метки)).

## Пакетное ревью ship

- Задачи `track:ship` слиты без ревью модели; их код одной сессией читает
  `ship-review.yml` — ночью (`SHIP-REVIEW-<база>-dev-<sha12>.md`) и перед бетой
  то, что ночь не прочла (`SHIP-REVIEW-<тег>.md`): по строке ТЗ каждой задачи и
  её коммитам ([§11.7](../../PROCESS.md#117-пакетное-ревью-ship-перед-бетой)).
- Вопросы к задаче: делает ли код заявленное и только его, не ломает ли
  соседнее, не вышла ли правка из ship по смыслу
  ([§11.7](../../PROCESS.md#117-пакетное-ревью-ship-перед-бетой),
  [§5](../../PROCESS.md#5-треки-ship-show-ask--метка-владельца)).
- Строка «Риск по участкам» под задачей — рискованные участки ship,
  подтверждённого владельцем: конвейер их не повышал, пакетное ревью читает их
  первыми ([§11.7](../../PROCESS.md#117-пакетное-ревью-ship-перед-бетой)).
- Документ `docs/reviews/SHIP-REVIEW-<тег>.md` публикует детерминированный
  шаг; High не пускает бету, Medium и Low решает владелец
  ([§11.7](../../PROCESS.md#117-пакетное-ревью-ship-перед-бетой)).
- Ночной документ `docs/reviews/SHIP-REVIEW-<база>-dev-<sha12>.md` читает только
  непокрытые задачи — без документа или изменившиеся после ревью; бета читает
  только то, что ночь не прочла: гейт беты принимает ночной документ при том же
  патч-наборе ([§11.7](../../PROCESS.md#117-пакетное-ревью-ship-перед-бетой)).

## Независимое ревью линии

- Перед стабильным релизом `release-review.yml` судит поверхности всей линии
  бет против пользователя, а не дифф против ТЗ: ТЗ задач и документы раундов не
  читаются, основа — `docs/SCOPE.md` и `docs/USER-GUIDE.ru.md`
  ([§11.5](../../PROCESS.md#115-независимое-ревью-линии-перед-стабильным-релизом)).
- Проверка исполнением: посимвольный ввод, настоящие Escape и крестик,
  фикстура `ha-dialog` (#505) для диалогов; по каждой поверхности — обычный
  сценарий и самый рискованный соседний
  ([§2.6](../../PROCESS.md#26-в-разработке--реализация), [§11.5](../../PROCESS.md#115-независимое-ревью-линии-перед-стабильным-релизом)).
- Документ `docs/reviews/RELEASE-REVIEW-vX.Y.Z.md` — рекомендация: выпуск не
  блокируется, решение по находкам за владельцем; ревьюер ничего не публикует
  и issue не заводит
  ([§11.5](../../PROCESS.md#115-независимое-ревью-линии-перед-стабильным-релизом)).