houseplan-card/docs/process/AUTHOR.md

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

Роли: аналитик, автор ТЗ, разработчик, автор инфраструктурной задачи
([§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-правила)). Исключение — локальный черновик на
  `track:ask` во время ревью ТЗ
  ([§11.8](../../PROCESS.md#118-черновик-кода-во-время-ревью-тз)).
- Классы: 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`, ценность, сложность и риск, приоритет, тип,
  поверхности, трек. Оценки ставятся метками сразу; молчание владельца —
  согласие; дальше аналитик переводит сам: `track:ask` — в `S3-spec`,
  `track:show` — в `S5-ready`. Останавливается аналитика
  только на конфликте со `SCOPE.md`
  ([§2.2](../../PROCESS.md#22-аналитика-и-оценка)).
- Шаблон: `Оценка: ценность N/10 · сложность N/10 · P<1-3> · тип ·
  поверхности: … · дубликаты: … · трек: ship/show/ask (причина)`
  ([§7.2](../../PROCESS.md#72-шаблоны-комментариев)).
- Трек задаёт метка `track:ship`, `track:show` или `track:ask`, по умолчанию
  `track:show`. Метка владельца главнее критериев; повысить трек может любой
  агент с причиной в комментарии, понизить — только владелец
  ([§5](../../PROCESS.md#5-треки-ship-show-ask--метка-владельца)).
- Трек подтверждает только владелец — строкой `Трек: <ship|show|ask> — решение
  владельца` в начале строки комментария. Метка без такой строки — предложение.
  Агент эту строку не пишет никогда. Несколько трековых меток — действует
  строжайшая ([§5](../../PROCESS.md#5-треки-ship-show-ask--метка-владельца)).
- Рискованный участок (геометрия, touch, миграция, устройства, perf, новый
  UX-ключ) в `ship` без подтверждения владельца конвейер повышает до `show` при
  `S7`; на `show` ревьюер спросит, где поведение зафиксировано, — нет ссылки,
  повысь трек до `ask` до `S7`. Классы и следствие печатает пакет задачи
  ([§5](../../PROCESS.md#5-треки-ship-show-ask--метка-владельца)).
- Вердикт код-ревью `show` с `route: reclassify` конвейер исполняет сам:
  `track:ask`, `S3-spec` и комментарий с критерием §5 (#726). Дальше — полное ТЗ
  по §7.1 в теле issue под `## ТЗ` и ревью ТЗ; код остаётся в ветке, код класса A
  не пушить до `S5`. Бюджет код-ревью не обнуляется, лимит — 4. Подтверждённый
  владельцем `show` получает `blocked` и вопрос владельцу
  ([§5](../../PROCESS.md#5-треки-ship-show-ask--метка-владельца)).
- `track:show`: `S2-analysis` → `S5-ready`, до трёх AC автор пишет в теле
  issue до перехода; ревью ТЗ нет, лимит код-ревью 2. Уместен, когда всё
  сразу: сложность и риск ≤ 3, одна поверхность, нет миграции, нового
  UX-контракта, влияния на перф и touch, и ожидаемое поведение уже
  зафиксировано — решать нечего ([§5](../../PROCESS.md#5-треки-ship-show-ask--метка-владельца)).
- `track:ship`: `S1-new` → `S5-ready`, в теле issue строка «что меняется и чем
  проверить». Рамки: дифф `src/**` до 30 строк, без новых файлов, i18n, полей
  конфига и Python ([§5](../../PROCESS.md#5-треки-ship-show-ask--метка-владельца)).
- Тяжёлые проверки на любом треке — метками `ci:full` и `ci:golden`;
  `ci:golden` ставится по сигналу — визуальный риск в пути отрисовки плана, —
  а риск сам полного набора не включает; прежние `small` и `trivial` читаются как
  `track:show` ([§5.1](../../PROCESS.md#51-метки-тяжёлых-проверок-и-прежние-метки)).

## ТЗ (`S3-spec`)

- ТЗ живёт в теле issue, раздел `## ТЗ`; файл в `docs/specs/` не создаётся
  ([§2.3](../../PROCESS.md#23-тз-в-работе--написание-тз)).
- Обязательные разделы: сценарий · что человек увидит до и после · проблема ·
  скоуп и не-скоуп · контракт поведения · UX · модель данных и миграция ·
  i18n · AC1…ACn с доказательством · план автотестов · риски · откат ·
  release-артефакты. На `track:show` — до трёх AC, на `track:ship` — одна
  строка ([§7.1](../../PROCESS.md#71-цепочка),
  [§5](../../PROCESS.md#5-треки-ship-show-ask--метка-владельца)).
- Размытое место не додумывается. Владельцу задаются только продуктовые
  вопросы — что человек видит или делает и какой объём видимых изменений
  входит в issue. Всё, чего пользователь не наблюдает, автор решает сам и
  записывает блоком «принято предположительно, поменять свободно». Смешанный
  вопрос делится ([§7.1](../../PROCESS.md#71-цепочка)).
- Дефект растра, резкости или композитинга: до кода нужен свидетель, красный
  на старом коде именно по симптому владельца; в AC — подтверждение владельца
  в реальном GPU-браузере. Headless-доказательства мало (урок #685 → #689,
  [§7.1](../../PROCESS.md#71-цепочка)).
- Вопросы — одним комментарием, пачкой: что неясно · что изменится от ответа ·
  вариант по умолчанию. Пока ждём ответа, issue остаётся в `S3-spec` и
  получает `blocked` ([§7.1](../../PROCESS.md#71-цепочка)).
- DoR перед `S5-ready`: на `track:ask` зелёное ревью ТЗ; пронумерованные AC со способом
  доказательства (`unit` / `backend` / `smoke` / `golden` / «ревью кода»);
  файлы и модули; ключи i18n en + ru; миграция по
  `docs/CONFIG-COMPATIBILITY.md`; перф; touch; release-артефакты; откат; нет
  открытых продуктовых вопросов. На `ship` и `show` пункты DoR закрываются
  словом «нет» ([§2.5](../../PROCESS.md#25-готово-к-разработке-dor)).
- Лимит — 4 цикла ревью, на `track:show` 2 цикла код-ревью; зелёный вердикт цикла
  не тратит; бюджет этапа один на все треки задачи; вердикт, исчерпавший
  бюджет, сразу ставит `review-4`; исчерпание — решение владельца: разделить,
  отклонить, арбитраж ([§4](../../PROCESS.md#4-лимит-циклов-ревью-4)).

## Черновик во время ревью ТЗ (`S4-spec-review`)

- Черновик — возможность, а не обязанность: только `track:ask`, только после
  того, как ТЗ отправлено и стоит `S4-spec-review`; под `blocked` и `review-4`
  не ведётся. Цена — код по непринятому тексту, который после жёлтого или
  красного вердикта переделывается
  ([§11.8](../../PROCESS.md#118-черновик-кода-во-время-ревью-тз)).
- Один checkout, одна локальная ветка `issue/<NN>-<slug>`; до `S5` не пушится
  ни ветка, ни коммиты; статус остаётся `S4`. Комментарий «Черновик:» по
  шаблону, черновик занимает слот WIP
  ([§11.8](../../PROCESS.md#118-черновик-кода-во-время-ревью-тз),
  [§7.2](../../PROCESS.md#72-шаблоны-комментариев),
  [§2.6](../../PROCESS.md#26-в-разработке--реализация)).
- Каждый черновой коммит несёт ровно один трейлер `Spec-Draft: sha256:<хеш>` —
  строку печатает пакет задачи в разделе «Черновик»
  ([§11.8](../../PROCESS.md#118-черновик-кода-во-время-ревью-тз)).
- Жёлтый или красный вердикт — черновик остановить: коммиты по прежнему тексту
  гейт не примет, переписывать дату автора запрещено; новый черновик — в
  следующей эпохе `S4` с новым хешем
  ([§11.8](../../PROCESS.md#118-черновик-кода-во-время-ревью-тз),
  [§12](../../PROCESS.md#12-запрещено)).
- В ветку черновик попадает только после зелёного ревью ТЗ: `S6-in-progress`,
  `git fetch`, ребейз на `origin/dev` (или на `origin/issue/<NN>-*`, если ветка
  уже была; без force-push), проверка
  `node scripts/process-gate.mjs --range origin/dev..HEAD --issues --report`,
  push ([§11.8](../../PROCESS.md#118-черновик-кода-во-время-ревью-тз),
  [§10.2](../../PROCESS.md#102-что-проверяет-process-gatemjs)).

## Реализация (`S6-in-progress`)

- Занятие: `Взял: <роль> · сессия <id> · ветка issue/NN-slug`; WIP — одна
  задача в разработке на исполнителя, не больше трёх на цикл релиза и двух в
  код-ревью
  ([§2.6](../../PROCESS.md#26-в-разработке--реализация),
  [§7.2](../../PROCESS.md#72-шаблоны-комментариев)).
- Ветка `issue/<NN>-<slug>`; каждый коммит с файлами классов A, B или D несёт
  трейлеры `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-правила)).

## Гейты перед хендоффом

- Обязательная часть — `npm run gate:small`: его состав живёт в
  `scripts/gate-small.mjs` и нигде не переписывается. По диффу и AC сверх
  него — целевые смоки из вывода `smoke-select` (связь не доказана — его
  визуальный минимум, `--smokes` гоняет его сам, #690), `model-invariants`,
  `pytest tests_backend`, junction parity; `golden:verify` — только с меткой
  `ci:golden` ([§8](../../PROCESS.md#8-гейты); `docs/TESTING.md`, «Локальный
  набор перед пушем»).
- Обязательные проверки с основаниями печатает пакет задачи: `gate:small`,
  смоки `smoke-select` с видом связи, invariants при `geometry`, pytest при
  Python, parity при зеркалах junction limits, `ci:golden` — только при
  визуальном риске в пути отрисовки плана ([§8](../../PROCESS.md#8-гейты)).
- Мутанты не гоняются ни локально, ни в CI: мутант своей защиты пишется в
  реестр, якорь сверяет `mutation-gate --check`, поимку — ночь (#709,
  [§2.7](../../PROCESS.md#27-код-ревью)).
- На `ship` и `show` сверх `gate:small` и названного в ТЗ ничего не гоняется:
  одно доказательство на пункт ТЗ; `--smokes` на `ship` не нужен; попутный флак —
  отдельное issue одной записью, без расследования в задаче
  ([§8](../../PROCESS.md#8-гейты)).
- Бандл в коммит задачи не идёт: сборка переписывает отслеживаемый `dist/`,
  перед коммитом — `npm run bundle:clean`; хук `commit-msg` отклоняет пути
  бандла без трейлера `Release:` (#657, [§1](../../PROCESS.md#1-основное-правило)).
- Новый код не добавляет `any`: гейт судит добавленные строки; исключение —
  `// any-ok: <конкретная причина>` на той же строке
  ([§8](../../PROCESS.md#8-гейты)).
- Ветка задачи не коммитит `docs/images/**` и `demo/golden/baselines/**`:
  отпечаток и кадры скриншотов, эталоны golden обновляет один коммит бота на
  `dev` перед бетой. Задача, которая меняет визуал намеренно, ставит
  `ci:golden` и принимает сдвинутые кадры сама
  ([§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` до ревью; `show`/`ship` с чистым слиянием ребейзятся один
  раз, при слиянии ([§10.4](../../PROCESS.md#104-событийный-конвейер-метка-как-триггер)).
- `ship` в рамках сливается без ревью модели; выход за рамки конвейер сам
  переводит в `track:show`. Код `ship` читает пакетное ревью перед бетой
  ([§10.4](../../PROCESS.md#104-событийный-конвейер-метка-как-триггер),
  [§11.7](../../PROCESS.md#117-пакетное-ревью-ship-перед-бетой)).
- Автор обязан дождаться вердикта, а не заканчивать сессию:
  `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` (кроме черновика
  `track:ask` по §11.8); ТЗ после кода (кроме хотфикса); ревью своей работы;
  пятый цикл ревью; issue вместо возврата на правки
  ([§12](../../PROCESS.md#12-запрещено)).
- Push черновика до `S5`; перенос черновика по устаревшему ТЗ коммитами с
  переписанной датой автора ([§12](../../PROCESS.md#12-запрещено),
  [§11.8](../../PROCESS.md#118-черновик-кода-во-время-ревью-тз)).
- Попутные правки «раз уж я здесь»; параллельные бэклоги в файлах;
  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-решение-владельца)).