houseplan-card/docs/process/AUTHOR.md

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

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

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

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

• Изменение продуктового кода без issue запрещено. Код меняется только из S5-ready или дальше (§1, §3 п.1–2). Исключение — локальный черновик на track:ask во время ревью ТЗ (§11.8).
• Классы: 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).
• Трек подтверждает только владелец — строкой Трек: <ship|show|ask> — решение владельца в начале строки комментария. Метка без такой строки — предложение. Агент эту строку не пишет никогда. Несколько трековых меток — действует строжайшая (§5).
• Рискованный участок (геометрия, touch, миграция, устройства, perf, новый UX-ключ) в ship без подтверждения владельца конвейер повышает до show при S7; на show ревьюер спросит, где поведение зафиксировано, — нет ссылки, повысь трек до ask до S7. Классы и следствие печатает пакет задачи (§5).
• Вердикт код-ревью show с route: reclassify конвейер исполняет сам: track:ask, S3-spec и комментарий с критерием §5 (#726). Дальше — полное ТЗ по §7.1 в теле issue под ## ТЗ и ревью ТЗ; код остаётся в ветке, код класса A не пушить до S5. Бюджет код-ревью не обнуляется, лимит — 4. Подтверждённый владельцем show получает blocked и вопрос владельцу (§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:golden ставится по сигналу — визуальный риск в пути отрисовки плана, — а риск сам полного набора не включает; прежние 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).
• Дефект растра, резкости или композитинга: до кода нужен свидетель, красный на старом коде именно по симптому владельца; в AC — подтверждение владельца в реальном GPU-браузере. Headless-доказательства мало (урок #685 → #689, §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 цикла код-ревью; зелёный вердикт цикла не тратит; бюджет этапа один на все треки задачи; вердикт, исчерпавший бюджет, сразу ставит review-4; исчерпание — решение владельца: разделить, отклонить, арбитраж (§4).

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

• Черновик — возможность, а не обязанность: только track:ask, только после того, как ТЗ отправлено и стоит S4-spec-review; под blocked и review-4 не ведётся. Цена — код по непринятому тексту, который после жёлтого или красного вердикта переделывается (§11.8).
• Один checkout, одна локальная ветка issue/<NN>-<slug>; до S5 не пушится ни ветка, ни коммиты; статус остаётся S4. Комментарий «Черновик:» по шаблону, черновик занимает слот WIP (§11.8, §7.2, §2.6).
• Каждый черновой коммит несёт ровно один трейлер Spec-Draft: sha256:<хеш> — строку печатает пакет задачи в разделе «Черновик» (§11.8).
• Жёлтый или красный вердикт — черновик остановить: коммиты по прежнему тексту гейт не примет, переписывать дату автора запрещено; новый черновик — в следующей эпохе S4 с новым хешем (§11.8, §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, §10.2).

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

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

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

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