houseplan-card/docs/process/AUTHOR.md

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

Роли: аналитик, автор ТЗ, разработчик, автор инфраструктурной задачи (§6).

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

Вход в процесс

• Изменение продуктового кода без issue запрещено. Код меняется только из S5-ready или дальше (§1, §3 п.1–2).
• Классы: 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).
• Инфраструктурная задача — ни одного файла класса A: реализация сразу в issue/<NN>-<slug>, без аналитики и ТЗ; локальные гейты зелёные, ветка запушена — S7-code-review. «В основном инфраструктурная» не бывает (§1).
• Ровно одна метка статуса на issue; blocked дополняет статус, а не заменяет; инфраструктурная задача до первого S7 может быть без S* (§9, §3 п.5).
• Статус меняется до действия, а не после: взял — поставил метку (§3 п.4).
• Автор не ревьюит своё — ни ТЗ, ни код; автор и ревьюер — разные агенты/сессии (§3 п.6, §6).

Аналитика (S2-analysis)

• Чек-лист комментарием: дубликаты, скоуп по docs/SCOPE.md и docs/TOUCH-SUPPORT.md, ценность, сложность и риск, приоритет, тип, поверхности, трек. Оценки ставятся метками сразу; молчание владельца — согласие; дальше аналитик переводит сам: track:ask — в S3-spec, track:show — в S5-ready. Останавливается аналитика только на конфликте со SCOPE.md (§2.2).
• Шаблон: Оценка: ценность N/10 · сложность N/10 · P<1-3> · тип · поверхности: … · дубликаты: … · трек: ship/show/ask (причина) (§7.2).
• Трек задаёт метка track:ship, track:show или track:ask, по умолчанию track:show. Метка владельца главнее критериев; повысить трек может любой агент с причиной в комментарии, понизить — только владелец (§5).
• track:show: S2-analysis → S5-ready, до трёх AC автор пишет в теле issue до перехода; ревью ТЗ нет, лимит код-ревью 2. Уместен, когда всё сразу: сложность и риск ≤ 3, одна поверхность, нет миграции, нового UX-контракта, влияния на перф и touch, и ожидаемое поведение уже зафиксировано — решать нечего (§5).
• track:ship: S1-new → S5-ready, в теле issue строка «что меняется и чем проверить». Рамки: дифф src/** до 30 строк, без новых файлов, i18n, полей конфига и Python (§5).
• Тяжёлые проверки на любом треке — метками ci:full, ci:golden, ci:mutants; прежние small и trivial читаются как track:show (§5.1).

ТЗ (S3-spec)

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

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

• Занятие: Взял: <роль> · сессия <id> · ветка issue/NN-slug; WIP — одна задача в разработке на исполнителя (§2.6, §7.2).
• Ветка issue/<NN>-<slug>; каждый коммит несёт трейлеры Issue: #<NN> и User-Visible: yes|no. User-Visible: yes требует правок в обоих changelog в том же коммите. После cherry-pick -x трейлеры остаются последним блоком (§2.6, §3 п.10).
• Автотесты — часть реализации: каждый AC с пометкой unit / backend / smoke / golden получает проверку здесь же (§2.6).
• Приёмка проверяет результат для человека: обычный сценарий плюс самый рискованный соседний, у каждого наблюдаемый oracle. Шесть классов риска проходятся явно: async; данные и права; геометрия; визуал; объём и performance; host/input. Проверка имени метода или строки исходника oracle не считается (§2.6).
• Скоуп не расширяется: найденное по пути — новый issue; блокирующая находка — blocked со ссылкой (§2.6, §3 п.9).
• Документация — в том же коммите, что и поведение: changelog RU+EN, STATUS.md, DEVELOPMENT.md, ARCHITECTURE.md (§2.6, §3 п.11).
• Сгенерированное не коммитится само по себе; golden принимаются только npm run golden:accept -- --reviewed по полному Linux-артефакту или аттестованному WSL-артефакту (§3 п.12–13).
• Защитный AC доказывается таблицей «чем краснеет»: AC · чем доказан · чем краснеет (мутация, снятая защита или отрицательная проба с результатом). Пустой третий столбец — находка Medium. Мутант в реестре обязателен, когда защита в продуктовом коде и проверяется дорогим гейтом (§2.7).
• Контракты по монолиту — исполнением, не regex по тексту: экспорт функции и вызов в test-build; список текстовых якорей заморожен; npm run lint:unused красит рост метрик монолита (§2.7).
• Одно число — один источник: величина, которую пользователь видит дважды, считается в одном месте (§8).
• AC доказывает автотест или честное «проверено чтением, не исполнением» у ревьюера; «проверил локально» доказательством не является (§3 п.18).

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

• Минимальный набор по изменённым поверхностям: npx tsc --noEmit, npm test, npm run build + bundle-policy --verify, smoke-select и целевые смоки, no-new-any; по диффу — golden:verify, check-docs, model-invariants, pytest tests_backend, junction parity. Команды — в каноне (§8); npm run gate:small собирает обязательную часть (docs/TESTING.md, «Локальный набор перед пушем»).
• Бандл в коммит задачи не идёт: сборка переписывает отслеживаемый dist/, перед коммитом — npm run bundle:clean; хук commit-msg отклоняет пути бандла без трейлера Release: (#657, §1).
• Новый код не добавляет any: гейт судит добавленные строки; исключение — // any-ok: <конкретная причина> на той же строке (§8).
• Любая правка src/** требует node scripts/check-docs.mjs: отпечаток скриншотов считается по всему фронтенду. Скриншоты снимает только CI; без изменения кадров — npm run docs:accept -- --identical (§8).
• Полные наборы — предрелизный гейт, а не гейт ревью. Упавший предрелизный гейт автор чинит и повторно прогоняет; повторного код-ревью нет, если правка не меняет контракт, не задевает новую подсистему и не правит сам гейт (§8, §11.4).
• Хуки ставит npm ci: commit-msg проверяет трейлеры, pre-push гоняет scripts/process-gate.mjs (§10.1, §10.2).

Хендофф и ожидание вердикта

• Хендофф: Сделано: … · Файлы: … · Гейты: <команда → результат> · НЕ сделано: … · Риски: … · Следующий статус: … · Новые issue: #… (§7.2).
• Один хендофф — один пуш: материал пушится до метки, перед пушем node scripts/process-gate.mjs --issues; после S7-code-review в ветку не пушить до вердикта; S7 ставится один раз на заход (§10.4).
• Ревью не начинается на красном коде: конвейер сам гоняет Validate с мутантами и возвращает красный в S6-in-progress без траты цикла (§10.4).
• Ветка приводится к dev до ревью, а не после: конфликт — возврат в S6-in-progress до ревью (§10.4).
• Автор обязан дождаться вердикта, а не заканчивать сессию: node scripts/wait-verdict.mjs --issue NN, смотреть на метку, а не на комментарий; при blocked не ждать. После прогона ревью метка меняется всегда; не сменилась — упал сам прогон (§10.4).
• Вперёд двигает только зелёный вердикт; жёлтый и красный возвращают автору. Medium в скоупе чинится в текущем issue, вне скоупа — отдельный issue (§7.2, §3 п.8).
• Зелёное ревью с неудавшимся слиянием — S6-in-progress: остался ребейз, после него снова S7; S8-merged ставится только после push в dev (§10.4).
• Issue закрывает релиз-менеджер после выпуска беты, не исполнитель (§2.8, §3 п.14).

Запрещено

• Код без issue или из статуса раньше S5-ready; ТЗ после кода (кроме хотфикса); ревью своей работы; пятый цикл ревью; issue вместо возврата на правки (§12).
• Попутные правки «раз уж я здесь»; параллельные бэклоги в файлах; force-push в dev; закрытие issue до выпуска беты (§12, §3 п.17).
• Принятие golden-эталонов ради зелёного CI; Medium, оставленные как TODO в документе ревью (§12).
• Аварийный хотфикс — только решением владельца, с issue в той же сессии до коммита (§11.2).