docs(process): ролевые конспекты, замер входа, Snapshot генерируется, TESTING.md разделён

Вход агента до первого файла кода стоил ≈ 26 700 слов (аудит 22.09).

- docs/process/AUTHOR.md и REVIEWER.md — выжимки PROCESS.md: каждый пункт
  ссылается на раздел канона, ключевые формулировки дословные;
  test/process-digests.test.mjs сверяет якоря, ссылки и правила.
- scripts/entry-cost.mjs — маршрут чтения по роли и бюджет (автор ≤ 12 000
  слов, AC1); AGENTS.md «Read this first» называет те же маршруты.
- docs/STATUS.md: блок Snapshot генерирует scripts/status-snapshot.mjs
  (версии — release-contract, счётчики — inventory, теги — git); feature
  surface и ранние milestones перенесены дословно в docs/STATUS-FEATURES.md.
- docs/TESTING.md — действующая инструкция (684 строки, AC3); ручные
  чек-листы и приложения по issue перенесены дословно в docs/testing-notes/
  с индексом и тестом на полноту.
- Промпт ревьюера в process.yml читает конспект вместо пересказа правил;
  машинные требования (строка вердикта, REVIEW_DOC, запрет fetch, таблица
  «чем краснеет», разделы повторного раунда) сохранены и закреплены тестом.
- PROCESS.md: правила не менялись; добавлены ссылка на конспекты в шапке и
  уточнение в §10.4, что ревьюер конвейера читает конспект.
- 7 мутантов в реестре.

Issue: #634
User-Visible: no
This commit is contained in:
Claude
2026-09-24 02:33:08 +00:00
committed by claude[bot]
parent fe92ce067a
commit 7dc7597260
30 changed files with 5590 additions and 4352 deletions
+196
View File
@@ -0,0 +1,196 @@
# Конспект для автора
Роли: аналитик, автор ТЗ, разработчик, автор инфраструктурной задачи
([§6](../../PROCESS.md#6-роли)).
> **Это выжимка, а не канон.** Канон процесса — [`PROCESS.md`](../../PROCESS.md);
> при расхождении побеждает он, а расхождение — issue с меткой `process`.
> Конспект правил не добавляет и не меняет: каждый пункт ссылается на раздел
> канона, где правило записано полностью, с причинами и прецедентами. Ссылки и
> ключевые формулировки сверяет `test/process-digests.test.mjs`. Читать
> раздел канона целиком, когда пункт касается текущего шага.
## Вход в процесс
- **Изменение продуктового кода без issue запрещено.** Код меняется только
из `S5-ready` или дальше ([§1](../../PROCESS.md#1-основное-правило),
[§3 п.1–2](../../PROCESS.md#3-правила)).
- Классы: A — продукт (`src/**`, `custom_components/houseplan/**/*.py`,
манифесты, i18n); B — гейты и инструменты (`test/**`, `tests_backend/**`,
`demo/**`, `scripts/**`, `.github/**`, конфиги сборки, `package*.json`);
C — документация; D — сгенерированное (`dist/**`,
`custom_components/houseplan/frontend/**`, `demo/golden/baselines/**`).
При пересечении путей D сильнее A ([§1](../../PROCESS.md#1-основное-правило)).
- Инфраструктурная задача — ни одного файла класса A: реализация сразу в
`issue/<NN>-<slug>`, без аналитики и ТЗ; локальные гейты зелёные, ветка
запушена — `S7-code-review`. «В основном инфраструктурная» не бывает
([§1](../../PROCESS.md#1-основное-правило)).
- Ровно одна метка статуса на issue; `blocked` дополняет статус, а не
заменяет; инфраструктурная задача до первого `S7` может быть без `S*`
([§9](../../PROCESS.md#9-метки--канонический-статус),
[§3 п.5](../../PROCESS.md#3-правила)).
- Статус меняется до действия, а не после: взял — поставил метку
([§3 п.4](../../PROCESS.md#3-правила)).
- Автор не ревьюит своё — ни ТЗ, ни код; автор и ревьюер — разные
агенты/сессии ([§3 п.6](../../PROCESS.md#3-правила),
[§6](../../PROCESS.md#6-роли)).
## Аналитика (`S2-analysis`)
- Чек-лист комментарием: дубликаты, скоуп по `docs/SCOPE.md` и
`docs/TOUCH-SUPPORT.md`, ценность, сложность и риск, приоритет, тип,
поверхности, трек. Оценки ставятся метками сразу; молчание владельца —
согласие; в `S3-spec` аналитик переводит сам. Останавливается аналитика
только на конфликте со `SCOPE.md`
([§2.2](../../PROCESS.md#22-аналитика-и-оценка)).
- Шаблон: `Оценка: ценность N/10 · сложность N/10 · P<1-3> · тип ·
поверхности: … · дубликаты: … · лёгкий трек: да/нет`
([§7.2](../../PROCESS.md#72-шаблоны-комментариев)).
- Лёгкий трек `small` — путь по умолчанию: обосновывается не выбор лёгкого
трека, а отказ от него — называется нарушенный критерий. Критерии, все
сразу: сложность и риск ≤ 3; одна поверхность; нет миграции конфига;
нет нового UX-контракта; нет влияния на перф и touch
([§5](../../PROCESS.md#5-лёгкий-трек-метка-small--путь-по-умолчанию)).
- Короткий трек `trivial`: `S2-analysis` → `S5-ready`, AC автор пишет в теле
issue до перехода. Тип `bug`, одна поверхность, без i18n, миграции, перфа и
touch, не больше трёх AC, и ожидаемое поведение уже зафиксировано — решать
нечего ([§5.1](../../PROCESS.md#51-короткий-трек-метка-trivial)).
## ТЗ (`S3-spec`)
- ТЗ живёт в теле issue, раздел `## ТЗ`; файл в `docs/specs/` не создаётся
([§2.3](../../PROCESS.md#23-тз-в-работе--написание-тз)).
- Обязательные разделы: сценарий · что человек увидит до и после · проблема ·
скоуп и не-скоуп · контракт поведения · UX · модель данных и миграция ·
i18n · AC1…ACn с доказательством · план автотестов · риски · откат ·
release-артефакты. На лёгком треке короче: проблема · контракт · AC · откат
([§7.1](../../PROCESS.md#71-цепочка),
[§5](../../PROCESS.md#5-лёгкий-трек-метка-small--путь-по-умолчанию)).
- Размытое место не додумывается. Владельцу задаются только продуктовые
вопросы — что человек видит или делает и какой объём видимых изменений
входит в issue. Всё, чего пользователь не наблюдает, автор решает сам и
записывает блоком «принято предположительно, поменять свободно». Смешанный
вопрос делится ([§7.1](../../PROCESS.md#71-цепочка)).
- Вопросы — одним комментарием, пачкой: что неясно · что изменится от ответа ·
вариант по умолчанию. Пока ждём ответа, issue остаётся в `S3-spec` и
получает `blocked` ([§7.1](../../PROCESS.md#71-цепочка)).
- DoR перед `S5-ready`: зелёное ревью ТЗ; пронумерованные AC со способом
доказательства (`unit` / `backend` / `smoke` / `golden` / «ревью кода»);
файлы и модули; ключи i18n en + ru; миграция по
`docs/CONFIG-COMPATIBILITY.md`; перф; touch; release-артефакты; откат; нет
открытых продуктовых вопросов
([§2.5](../../PROCESS.md#25-готово-к-разработке-dor)).
- Лимит — 4 цикла ревью, на лёгком и коротком треке 2; зелёный вердикт цикла
не тратит; исчерпание — решение владельца: разделить, отклонить, арбитраж
([§4](../../PROCESS.md#4-лимит-циклов-ревью-4)).
## Реализация (`S6-in-progress`)
- Занятие: `Взял: <роль> · сессия <id> · ветка issue/NN-slug`; WIP — одна
задача в разработке на исполнителя
([§2.6](../../PROCESS.md#26-в-разработке--реализация),
[§7.2](../../PROCESS.md#72-шаблоны-комментариев)).
- Ветка `issue/<NN>-<slug>`; каждый коммит несёт трейлеры `Issue: #<NN>` и
`User-Visible: yes|no`. `User-Visible: yes` требует правок в обоих changelog
в том же коммите. После `cherry-pick -x` трейлеры остаются последним блоком
([§2.6](../../PROCESS.md#26-в-разработке--реализация),
[§3 п.10](../../PROCESS.md#3-правила)).
- Автотесты — часть реализации: каждый AC с пометкой `unit` / `backend` /
`smoke` / `golden` получает проверку здесь же
([§2.6](../../PROCESS.md#26-в-разработке--реализация)).
- Приёмка проверяет результат для человека: обычный сценарий плюс самый
рискованный соседний, у каждого наблюдаемый oracle. Шесть классов риска
проходятся явно: async; данные и права; геометрия; визуал; объём и
performance; host/input. Проверка имени метода или строки исходника oracle
не считается ([§2.6](../../PROCESS.md#26-в-разработке--реализация)).
- Скоуп не расширяется: найденное по пути — новый issue; блокирующая находка —
`blocked` со ссылкой ([§2.6](../../PROCESS.md#26-в-разработке--реализация),
[§3 п.9](../../PROCESS.md#3-правила)).
- Документация — в том же коммите, что и поведение: changelog RU+EN,
`STATUS.md`, `DEVELOPMENT.md`, `ARCHITECTURE.md`
([§2.6](../../PROCESS.md#26-в-разработке--реализация),
[§3 п.11](../../PROCESS.md#3-правила)).
- Сгенерированное не коммитится само по себе; golden принимаются только
`npm run golden:accept -- --reviewed` по полному Linux-артефакту или
аттестованному WSL-артефакту ([§3 п.12–13](../../PROCESS.md#3-правила)).
- Защитный AC доказывается таблицей «чем краснеет»: AC · чем доказан · чем
краснеет (мутация, снятая защита или отрицательная проба с результатом).
Пустой третий столбец — находка Medium. Мутант в реестре обязателен, когда
защита в продуктовом коде и проверяется дорогим гейтом
([§2.7](../../PROCESS.md#27-код-ревью)).
- Контракты по монолиту — исполнением, не regex по тексту: экспорт функции и
вызов в `test-build`; список текстовых якорей заморожен; `npm run
lint:unused` красит рост метрик монолита
([§2.7](../../PROCESS.md#27-код-ревью)).
- Одно число — один источник: величина, которую пользователь видит дважды,
считается в одном месте ([§8](../../PROCESS.md#8-гейты)).
- AC доказывает автотест или честное «проверено чтением, не исполнением» у
ревьюера; «проверил локально» доказательством не является
([§3 п.18](../../PROCESS.md#3-правила)).
## Гейты перед хендоффом
- Минимальный набор по изменённым поверхностям: `npx tsc --noEmit`,
`npm test`, `npm run build` со сверкой копий бандла, `smoke-select` и
целевые смоки, `no-new-any`; по диффу — `golden:verify`, `check-docs`,
`model-invariants`, `pytest tests_backend`, junction parity. Команды —
в каноне ([§8](../../PROCESS.md#8-гейты)); `npm run gate:small` собирает
обязательную часть (`AGENTS.md`, «Gates»).
- Новый код не добавляет `any`: гейт судит добавленные строки; исключение —
`// any-ok: <конкретная причина>` на той же строке
([§8](../../PROCESS.md#8-гейты)).
- Любая правка `src/**` требует `node scripts/check-docs.mjs`: отпечаток
скриншотов считается по всему фронтенду. Скриншоты снимает только CI;
без изменения кадров — `npm run docs:accept -- --identical`
([§8](../../PROCESS.md#8-гейты)).
- Полные наборы — предрелизный гейт, а не гейт ревью. Упавший предрелизный
гейт автор чинит и повторно прогоняет; повторного код-ревью нет, если
правка не меняет контракт, не задевает новую подсистему и не правит сам
гейт ([§8](../../PROCESS.md#8-гейты),
[§11.4](../../PROCESS.md#114-починка-предрелизных-гейтов-без-повторного-код-ревью)).
- Хуки ставит `npm ci`: `commit-msg` проверяет трейлеры, `pre-push` гоняет
`scripts/process-gate.mjs` ([§10.1](../../PROCESS.md#101-хуки-которые-невозможно-забыть-поставить),
[§10.2](../../PROCESS.md#102-что-проверяет-process-gatemjs)).
## Хендофф и ожидание вердикта
- Хендофф: `Сделано: … · Файлы: … · Гейты: <команда → результат> ·
НЕ сделано: … · Риски: … · Следующий статус: … · Новые issue: #…`
([§7.2](../../PROCESS.md#72-шаблоны-комментариев)).
- Один хендофф — один пуш: материал пушится до метки, перед пушем
`node scripts/process-gate.mjs --issues`; после `S7-code-review` в ветку не
пушить до вердикта; `S7` ставится один раз на заход
([§10.4](../../PROCESS.md#104-событийный-конвейер-метка-как-триггер)).
- Ревью не начинается на красном коде: конвейер сам гоняет Validate с
мутантами и возвращает красный в `S6-in-progress` без траты цикла
([§10.4](../../PROCESS.md#104-событийный-конвейер-метка-как-триггер)).
- Ветка приводится к `dev` до ревью, а не после: конфликт — возврат в
`S6-in-progress` до ревью ([§10.4](../../PROCESS.md#104-событийный-конвейер-метка-как-триггер)).
- Автор обязан дождаться вердикта, а не заканчивать сессию:
`node scripts/wait-verdict.mjs --issue NN`, смотреть на метку, а не на
комментарий; при `blocked` не ждать. После прогона ревью метка меняется
всегда; не сменилась — упал сам прогон
([§10.4](../../PROCESS.md#104-событийный-конвейер-метка-как-триггер)).
- Вперёд двигает только зелёный вердикт; жёлтый и красный возвращают автору.
Medium в скоупе чинится в текущем issue, вне скоупа — отдельный issue
([§7.2](../../PROCESS.md#72-шаблоны-комментариев),
[§3 п.8](../../PROCESS.md#3-правила)).
- Зелёное ревью с неудавшимся слиянием — `S6-in-progress`: остался ребейз,
после него снова `S7`; `S8-merged` ставится только после push в `dev`
([§10.4](../../PROCESS.md#104-событийный-конвейер-метка-как-триггер)).
- Issue закрывает релиз-менеджер после выпуска беты, не исполнитель
([§2.8](../../PROCESS.md#28-закрытие-после-выпуска-беты),
[§3 п.14](../../PROCESS.md#3-правила)).
## Запрещено
- Код без issue или из статуса раньше `S5-ready`; ТЗ после кода (кроме
хотфикса); ревью своей работы; пятый цикл ревью; issue вместо возврата на
правки ([§12](../../PROCESS.md#12-запрещено)).
- Попутные правки «раз уж я здесь»; параллельные бэклоги в файлах;
force-push в `dev`; закрытие issue до выпуска беты
([§12](../../PROCESS.md#12-запрещено), [§3 п.17](../../PROCESS.md#3-правила)).
- Принятие golden-эталонов ради зелёного CI; Medium, оставленные как TODO в
документе ревью ([§12](../../PROCESS.md#12-запрещено)).
- Аварийный хотфикс — только решением владельца, с issue в той же сессии до
коммита ([§11.2](../../PROCESS.md#112-аварийный-хотфикс-метка-hotfix-решение-владельца)).
+130
View File
@@ -0,0 +1,130 @@
# Конспект для ревьюера
Роли: ревьюер ТЗ и ревьюер кода ([§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`, на лёгком треке —
комментарий ([§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-цепочка)).
## Код-ревью
- Артефакт — `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` со сверкой копий бандла; при
диффе по `src/**` — ещё `node scripts/check-docs.mjs`. Зелёный Validate на
SHA материала подтверждает дешёвые гейты ([§8](../../PROCESS.md#8-гейты)).
- По диффу и AC: смоки — названные в AC плюс вывод
`node scripts/smoke-select.mjs --base <base> --head <head>` с решением по
каждой строке; `golden:verify` при видимом изменении; `pytest tests_backend`
при правке Python; инварианты модели при правке геометрии; performance —
если назван в AC. Полные наборы — предрелизный гейт, а не гейт ревью
([§8](../../PROCESS.md#8-гейты)).
- Условие честности сужения: ревьюер обязан перечислить, какие гейты прогнал,
какие нет и почему ([§8](../../PROCESS.md#8-гейты)).
- Зелёный `pytest tests_backend` без Home Assistant скипает `test_ha_*.py` и
ничего не доказывает — это «чего не проверял» (`AGENTS.md`, «Gates»;
[§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 цикла, на лёгком и коротком
треке 2; бюджет считается по этапу
([§4](../../PROCESS.md#4-лимит-циклов-ревью-4),
[§10.4](../../PROCESS.md#104-событийный-конвейер-метка-как-триггер)).
- Запрещено: Medium-находки, оставленные как TODO в документе ревью;
ревью-документы вне репозитория ([§12](../../PROCESS.md#12-запрещено)).