houseplan-card/docs/process/REVIEWER.md at 4091d83af36df56cfecf98f90d2f024e53e0fa4d

mirror of https://github.com/Matysh/houseplan-card synced 2026-10-02 12:49:56 +00:00

Files

T

Claude 0e44f8a69f feat(process): a track:ask draft may be written during the spec review (#729 )

On track:ask every spec review round is 10-45 minutes of waiting, and
rule #1 kept the author idle for all of it. Rule 10 (#738) judges a
class A commit by its author date, so code written in the
S4-spec-review epoch was always refused: nothing told a draft written
against the reviewed text from a violation. The owner allowed changing
rule #1 for this (decision 2026-10-01).

A draft commit carries `Spec-Draft: sha256:<issueBodyDigest(body)>`,
the hash the pipeline already writes as "Тело issue" into the review
document anchor. Rule 10 accepts a class A commit written in S4 only
when its S4 epoch (a repeated S4 does not restart it) was closed by
S5-ready, the track at the author date was ask, and the trailer equals
the body of the green, High 0 SPEC-REVIEW added inside that epoch, read
from the range head or origin/dev. The first failing check is the one
finding: trailer format, track, how the epoch ended, the missing
document with a `git fetch origin dev` hint, or both hashes and the
document name. A trailer on a commit written in an allowed epoch is a
warn. Without the document reader rule 10 is exactly #738; main always
passes one, and it reads git only when the range holds a draft.

The task packet tells S4 on ask that a local draft is allowed while the
branch stays closed, prints the trailer line, and in S5/S6 names the
green spec review, whether the body changed since, and the --report
check before push. SPEC-REVIEW documents are a separate input
(specDocs) from the branch and origin/dev, so the previous verdict and
the AC witness keep their source.

PROCESS.md gets §11.8 and the points that refer to it (§1, §2.4-2.6,
§3 item 1, §7.2, §9, §10.2 item 10, §12); AUTHOR.md, REVIEWER.md and
AGENTS.md follow, with three new key rules in process-digests. The
pre-push hook fixture copies the modules process-gate now imports.

Issue: #729
User-Visible: no
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018qZfe7YS4rqEMKoVeS3GKd

2026-10-01 11:47:01 +03:00

203 lines

18 KiB

Markdown

Raw Blame History

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

 # Конспект для ревьюера
 Роли: ревьюер ТЗ и ревьюер кода ([§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-гейты)).
 - Условие честности сужения: ревьюер обязан перечислить, какие гейты прогнал,
   какие нет и почему ([§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`, по каждой находке показать, чем она закрыта,
   заново проверить только 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`
   читает их код одной сессией: по строке ТЗ каждой задачи и её коммитам
   ([§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-независимое-ревью-линии-перед-стабильным-релизом)).

203 lines 18 KiB Markdown Raw Blame History Unescape Escape

203 lines

18 KiB

Markdown

Raw Blame History