houseplan-card/docs/process/REVIEWER.md

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

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

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

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

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

Ревью ТЗ

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

Код-ревью

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

Объём гейтов

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

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

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

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

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

Трек show

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

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

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

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

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