diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index f158892..9079d3a 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -18,7 +18,7 @@ { "name": "av-dev-pipeline", "source": "./av-dev-pipeline", - "description": "Проведение задачи через цикл SDD и конвейер ревью с обязательным триажем. Требует OpenSpec. Задача принимается и обычным текстом; плагины av-dev-docs и av-dev-tasks опциональны — первый даёт документы канона для проходов ревью, второй учёт задач, без них прогон деградирует поразрядно и говорит об этом." + "description": "Решение одной задачи от постановки до закрытия: цикл SDD с чекпоинтом объяснения после ревью дизайна, у исследовательской задачи — ещё и чекпоинт вариантов до первого требования. Конвейер ревью с обязательным триажем. Требует OpenSpec. Задача принимается и обычным текстом; плагины av-dev-docs и av-dev-tasks опциональны — первый даёт документы канона для проходов ревью, второй учёт задач, без них прогон деградирует поразрядно и говорит об этом." }, { "name": "av-dev-git", diff --git a/DECISIONS.md b/DECISIONS.md index 25b4cb1..be15298 100644 --- a/DECISIONS.md +++ b/DECISIONS.md @@ -3392,3 +3392,71 @@ JJJ): у профиля обязан быть один правильный от через месяц неотличимо от подогнанного под один случай. Обе стороны разрыва названы (0.64 и 0.91) — и видно не только, что порог верен, но и насколько он не на грани. + +## 55. `task-pipeline` стал `resolve`: два плановых стопа вместо полной автономии (2026-08-09) + +**АЕАКН. Автоматическое решение задач агентом признано утопией — «работает, но +работает плохо», — и хуже того, автор перестал ориентироваться в собственном +процессе.** Отсюда разворот: задачи решаются по одной, а в цикл возвращается +человек. `task-batch` удалён целиком; `task-pipeline` переписан в `resolve`. + +**Прежняя доктрина звучала «умолчание — делать, а не спрашивать», и она не +отменена, а ограничена.** Полностью автономный прогон плох не тем, что ошибается, +а тем, что ошибку видно на готовом коде: развилка, стоившая бы абзаца до +`propose`, стоит переписывания после `apply`. Постоянное же согласование +возвращает ту цену, ради ухода от которой пайплайн и писался. Разрез поэтому по +**месту**, а не по важности решения: развилка, найденная до ближайшего чекпоинта, +копится в него; найденная после последнего — по-прежнему уходит вопросом в запись, +и задача доводится в объявленных границах. + +**Чекпоинтов два, и второй обязателен всегда.** + +- **«варианты»** — у исследовательской задачи, до первого требования. Признак + ветки не объём работы, а **отсутствие одного очевидного способа решения**: + обсуждать варианты после `propose` поздно, предложение уже воплотило один из + них, и разговор пойдёт не о выборе, а о переделке. Форма ограничена сверху — + 2–4 варианта: больше четырёх человек не сравнивает, а признаёт неспособность + сравнить и просит рекомендацию. +- **«объяснение»** — у всякой задачи, **после** ревью дизайна. Порядок обоснован: + человек читает то, что уже просеяла машина, и не тратит внимание на выловимое + `review-specs`. Внимание здесь самый дорогой ресурс процесса. + +**Объяснение не стало новым артефактом, и это главная правка первоначального +замысла.** Задумывалось отдельным разделом в `design.md`; при разборе оказалось, +что оно там было бы **третьим домом** одного и того же: в `proposal.md` уже есть +`## Why` («в чём проблема»), в `design.md` — рассмотренные варианты. Поэтому +объяснение **собирается из двух существующих артефактов**, а требование к их +форме уехало в `openspec/config.yaml` — `rules.proposal` и `rules.design`. Это +единственное место, применяющееся **в момент написания**, а не после. +Побочная выгода: `design.md` с названными причинами отказа — половина будущего +ADR, а промоут ADR читает именно архивный `design.md`. + +**Закрыт вопрос, висевший в плане открытым: что делает автоматический участок, +когда ревью кода спорит с одобренным дизайном.** Признак проверяемый — +**меняются ли дельта-спеки**. Не меняются: находка внутри дизайна, дожимается +сама. Меняются: решение стало другим, а одобрено было прежнее — разметка +пересчитывается (правило уже было) и **чекпоинт повторяется**. Чекпоинт, который +можно обойти находкой ревью, не значит ничего, и хуже того — человек уверен, что +одобрил именно то, что уехало в коммит. + +**Удаление `task-batch` обошлось дороже своего каталога.** На нём держались: +третий режим `review-specs` (стык после слияния) вместе с исключением «живого +change нет — берём источником актуальные спеки»; единственное исключение из +правила `review-triage` «плана нет — не запускаюсь»; и обоснование имени основной +ветки в каноне — «в неё вливает батч». Первые два — послабления, существовавшие +только ради батча, и с ним они исчезли, сделав оба правила строже. + +### Что из этого следует + +184. **Автономность ограничивается местом, а не важностью решения.** «Спрашивать + о важном» неисполнимо: важность оценивает тот же, кто хочет закончить. + «Копить до ближайшего планового стопа» проверяемо и не требует суждения. +185. **Чекпоинт ставится после машинной проверки, а не до неё.** Внимание + человека тратится только на то, чего машина не ловит; порядок наоборот + сжигает его на выловимом и обесценивает саму остановку. +186. **Объяснение для человека не заводит своего артефакта.** Если оно + собирается из уже существующих, оно не может с ними разойтись; отдельный + текст «то же, но понятнее» — третий дом, и расходится он молча. +187. **Послабление, введённое ради одного потребителя, уходит вместе с ним.** + Исключение переживает своего заказчика и выглядит общим правилом; удаляя + потребителя, ищи его исключения — они и есть настоящий хвост. diff --git a/README.md b/README.md index a989a22..03989e9 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,12 @@ формы, скрипт `openspec.py` (форма файла + сверка слепка с живой версией инструмента). Каталог принадлежит конвейеру, а не канону: без конвейера он проекту не нужен, и `docs.py` о нём молчит; - - `task-pipeline` — задача через полный цикл SDD, от постановки до коммита; + - `resolve` — одна задача от постановки до закрытия. Обычная идёт циклом SDD + с **чекпоинтом после ревью дизайна**: объяснение человеческим языком, повод + скорректировать ход решения. Исследовательская начинается с `opsx:explore` и + **чекпоинта вариантов** — способы решить, цена каждого, рекомендация; выбор + оседает по адресу, который назвала сама задача. Между чекпоинтами — без + согласований; - `review-pipeline` — конвейер ревью **по темам**: документ проекта либо заводит тему проверки, либо питает чужую тему источником, либо процессный и в ревью не читается вовсе. Разметка идёт **один раз на задачу**, сразу после @@ -54,7 +59,7 @@ flowchart TB subgraph pipe["av-dev-pipeline — исполнение, требует OpenSpec"] direction LR - tp["task-pipeline"] --> rp["review-pipeline
10 агентов-проходов"] + tp["resolve
2 чекпоинта человеку"] --> rp["review-pipeline
10 агентов-проходов"] osp["openspec
заводит и проверяет openspec/"] end subgraph docsp["av-dev-docs — документация, владеет docs/"] diff --git a/TODO.md b/TODO.md index 4397f9e..a57a15c 100644 --- a/TODO.md +++ b/TODO.md @@ -74,8 +74,10 @@ лежит задача, знают индексы» - [ ] **перевесить гейт готовности.** Схема типа (обязательные разделы, ≥2 критерия, границы) проверяется на `sprint take`. Спринта нет — момента нет; - нужен `tasks.py ready <слаг>` или `check --task <слаг>` на входе пайплайна, - иначе задача уедет в работу без критериев приёмки + нужен `tasks.py ready <слаг>` или `check --task <слаг>`, иначе задача уедет + в работу без критериев приёмки. Сейчас `resolve` держит это глазами: он + отказывает сырью (`research` без «Вопроса») и называет строкой невыполненную + схему у прочих типов — то есть **машина в этом месте не участвует** - [ ] `check --fix`: восстановленная строка индекса теряет позицию, а позиция теперь и есть приоритет. Класть в конец категории и печатать пометкой, что приоритет назначен не человеком @@ -91,27 +93,22 @@ канонизация в транзакции, `-1 >= -1`. Цена и ожидаемый исход — REMAINING, «Главный незакрытый риск» -## 4. Пайплайн одной задачи — три этапа +## 4. Пайплайн: что осталось после `resolve` -Обкатывается на healthlog после разделов 1 и 2. Пайплайн нескольких задач на -паузе намеренно. +Сам скилл написан (`av-dev-pipeline:resolve`, два чекпоинта, ветка разведки), +`task-batch` удалён. Осталось то, что на бумаге не проверяется: -- [ ] **этап 1** — первичный ресерч и смысл задачи. Заканчивается дешёвым - подтверждением: две строки «понял так, собираюсь делать это». Без него - проверка «то ли я делаю» приходит после готового дизайна, то есть когда - ошибка стоит дороже всего -- [ ] **этап 2** — propose, дизайн, ревью дизайна, краткое объяснение решения. - Заканчивается полноценным чекпоинтом -- [ ] **этап 3** — код, ревью, архивация. Автоматически: дизайн уже согласован. - Решить, что делает этап, когда ревью находит расхождение **с утверждённым - дизайном**: находка внутри дизайна дожимается сама, находка, отменяющая - дизайн, отменяет и чекпоинт и обязана всплыть к человеку - [ ] перемерить `review-pipeline` тем же вопросом, что и проект целиком: - сколько из пяти стадий реально смотрятся глазами. 1028 строк, и весь - автоматический этап держится на них + сколько из его стадий реально смотрятся глазами. Тысяча строк, и весь + автоматический участок между чекпоинтами держится на них +- [ ] чекпоинт «объяснение» собирается из `proposal.md` и `design.md`, а + требования к их форме уехали в `openspec/config.yaml` (`rules.proposal`, + `rules.design`). **На живом проекте это ни разу не работало:** неизвестно, + хватает ли двух артефактов, чтобы объяснение не пришлось дописывать руками ## 5. Обкатка -- [ ] один-два цикла healthlog на новом процессе; наблюдение к первой обкатке — - не выродились ли «границы покрытия» в шаблон (REMAINING, «Открытые - вопросы») +- [ ] один-два цикла healthlog на новом процессе. Наблюдения к первой обкатке + два: не выродились ли «границы покрытия» в шаблон (REMAINING, «Открытые + вопросы») и **не превратился ли чекпоинт в ритуал одобрения** — признак + тот же, дословно повторяющийся текст и согласие без единой правки diff --git a/av-dev-pipeline/.claude-plugin/plugin.json b/av-dev-pipeline/.claude-plugin/plugin.json index 21c9b2b..a6f2e41 100644 --- a/av-dev-pipeline/.claude-plugin/plugin.json +++ b/av-dev-pipeline/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "av-dev-pipeline", - "description": "Проведение задачи через полный цикл Spec Driven Development и конвейер ревью с детерминированным гейтом, сверкой со спеками, враждебными постановками, эксплуатационным постмортемом, независимой реализацией и обязательным триажем. Требует OpenSpec и сам его заводит скиллом openspec. Задача принимается и обычным текстом. Плагины av-dev-docs и av-dev-tasks опциональны: первый даёт документы канона, из которых проходы читают проектную конкретику, второй — учёт задач; без них прогон деградирует поразрядно и называет это строкой.", + "description": "Решение одной задачи от постановки до закрытия скиллом resolve — полный цикл Spec Driven Development с двумя плановыми остановками: чекпоинт вариантов у исследовательской задачи и чекпоинт с объяснением человеческим языком после ревью дизайна у всякой. Между ними работа идёт без согласований. Плюс конвейер ревью с детерминированным гейтом, сверкой со спеками, враждебными постановками, эксплуатационным постмортемом, независимой реализацией и обязательным триажем. Требует OpenSpec и сам его заводит скиллом openspec. Задача принимается и обычным текстом. Плагины av-dev-docs и av-dev-tasks опциональны: первый даёт документы канона, из которых проходы читают проектную конкретику, второй — учёт задач; без них прогон деградирует поразрядно и называет это строкой.", "author": { "name": "Anton Vakhrushev", "email": "anwinged@gmail.com" diff --git a/av-dev-pipeline/skills/openspec/SKILL.md b/av-dev-pipeline/skills/openspec/SKILL.md index 085d76a..052295b 100644 --- a/av-dev-pipeline/skills/openspec/SKILL.md +++ b/av-dev-pipeline/skills/openspec/SKILL.md @@ -43,6 +43,11 @@ openspec init --tools claude правила именования capability, придирки валидатора и **адреса** документов проекта. +Сюда же — **требования к форме `proposal` и `design`**, на которых стоит чекпоинт +скилла `av-dev-pipeline:resolve`: объяснение человеку собирается из этих двух +артефактов, и требование к ним обязано применяться в момент, когда их пишут, а не +вспоминаться шагом позже. Образец их содержит. + Пересказ паспорта, инвариантов, конвенций и правил ревью сюда **не переносится**. Место для второго дома здесь самое частое: `context` читается при порождении каждого артефакта, туда удобно дописать «чтобы агент знал», и так заводятся копии diff --git a/av-dev-pipeline/skills/openspec/references/config-skeleton.md b/av-dev-pipeline/skills/openspec/references/config-skeleton.md index 8933f28..65ac7e7 100644 --- a/av-dev-pipeline/skills/openspec/references/config-skeleton.md +++ b/av-dev-pipeline/skills/openspec/references/config-skeleton.md @@ -57,6 +57,10 @@ context: | rules: proposal: - Capabilities называй по поведению или домену системы, не по пакету кода + - "Why и What Changes — языком домена из docs/passport.md: без SHALL, без имён модулей и функций там, где вещь называется по-русски" + design: + - "Назови рассмотренные варианты и причину отказа от каждого — из них потом пишется ADR" + - "Решение объясняется через то, что человек увидит иначе, а не через устройство кода" specs: # Кавычки обязательны: без них YAML обрежет строку на первом '#'. - "Каждое ### Requirement обязано содержать SHALL или MUST (иначе валидация падает)" @@ -67,7 +71,15 @@ rules: **Четыре правила для `specs` сняты отказами валидатора, а не выведены из документации** — потому и записаны дословно: без них каждое второе предложение -узнаёт их падением `openspec validate --strict`. Блок `context` проект +узнаёт их падением `openspec validate --strict`. + +**Правила для `proposal` и `design` держат чекпоинт скилла +`av-dev-pipeline:resolve`.** Там работа останавливается и человеку объясняют, в +чём проблема и как её решают, — а объяснение **собирается из этих двух +артефактов**, а не сочиняется заново: третий пересказ одного и того же разошёлся +бы с обоими. Требование поэтому стоит здесь, в момент порождения артефакта, а не +в скилле, который спохватится позже. `design.md` при этом ещё и **сырьё для +ADR** — отвергнутый вариант с названной причиной и есть половина будущей записи. Блок `context` проект дополняет своим (стек, разведка, особенности домена), но **адреса паспорта и `CLAUDE.md` обязательны** — отсутствие адреса к существующему документу `openspec.py check` называет отказом. diff --git a/av-dev-pipeline/skills/resolve/SKILL.md b/av-dev-pipeline/skills/resolve/SKILL.md new file mode 100644 index 0000000..126b3e4 --- /dev/null +++ b/av-dev-pipeline/skills/resolve/SKILL.md @@ -0,0 +1,630 @@ +--- +name: resolve +description: "Решить одну задачу от постановки до закрытия. На входе путь к файлу задачи, её слаг или просто текст. Обычная задача идёт циклом Spec Driven Development: opsx propose → разметка → ревью дизайна → чекпоинт с объяснением человеческим языком → opsx apply → ревью кода → archive → синк документации → коммит → закрытие. Исследовательская (тип research, сырая идея, мутная постановка) начинается раньше: opsx explore и чекпоинт вариантов — два-четыре способа решить, с ценой каждого и рекомендацией; выбор оседает по адресу, который назвала сама задача. Между чекпоинтами работа идёт без согласований. Использовать, когда просят взять, сделать или решить задачу, довести идею до реализации, разобраться с записью из беклога." +--- + +# Решение одной задачи + +Проводит **одну** задачу от постановки до закрытия. Между плановыми +остановками — без согласований: механику не обсуждаем, делаем. + +Тонкая обёртка над каноническими скиллами `opsx:explore` / `opsx:propose` / +`opsx:apply` / `opsx:archive` — зови их через Skill, не переизобретай их шаги. +Ревью — скилл `av-dev-pipeline:review-pipeline`; он же держит правило выбора +метки, а называет её агент `review-scope` — один раз на задачу, для обеих стадий +ревью. + +## Предпосылки + +- **OpenSpec и скиллы `opsx:*` — жёсткая предпосылка, а не опция.** На них стоят + шаги 2, 6 и 8, проход `review-specs` и ревью дизайна (они завязаны на + `openspec/changes//specs/*/spec.md` и на `openspec validate --strict`). + **Проект без OpenSpec этим скиллом не ведётся** — подключай OpenSpec, а не + вырождай цикл: ветка деградации здесь не пишется, потому что непроверенная + ветка деградации хуже честного отказа. +- **Проектные копии этих скиллов и агентов удаляются при установке плагина** + (`.claude/skills/` — и голые имена `resolve`, `task-pipeline`, + `review-pipeline`, и с префиксом проекта: `<проект>-task-pipeline`, + `<проект>-review-pipeline`; `.claude/agents/<проект>-review-*.md`). Две копии + одного скилла расходятся, и побеждает та, что короче названа. + +### Обращение к соседним плагинам + +**Копия.** Дом — `shared/plugin-boundary.md` в репозитории плагинов: правило +общее для всех, кто зовёт чужое, и ни один плагин им не владеет. Правится дом, а +не этот файл. + + + +Плагины `av-dev` ставятся порознь, и ни один не вправе считать, что сосед на +месте. + +**Чужой скилл зовётся полным именем** — `av-dev-docs:canon`, +`av-dev-tasks:tasks`, `av-dev-pipeline:review-pipeline`. Короткое имя может +разрешиться в устаревшую проектную копию из `.claude/skills/`, и подмены не будет +видно ни в докладе, ни в поведении. + +**Путь в дерево чужого плагина не пишется никогда.** `$CLAUDE_PLUGIN_ROOT` ведёт +только в свой плагин; вычисленный от него путь к соседу либо не откроется, либо +откроет чужую установку. Нужен чужой справочник — зови владеющий им скилл, он +прочитает его сам. + +**Вызов не разрешился — плагина в проекте нет.** Это исход, а не поломка: назови +строкой доклада, чего теперь не делает никто, и продолжай работу. Молчать нельзя, +пропуск неотличим от сделанного; выдумывать обходной путь нельзя тоже. + +**Присутствие узнаётся вызовом или следом в проекте, но не объявлением.** Перечня +установленных плагинов проект не ведёт — он разошёлся бы с действительностью +молча. Что сосед здесь работал, видно по заведённому им файлу: `docs/.pm.json` — +канон, `<каталог задач>/.tasks.json` — задачи, `openspec/config.yaml` — конвейер. + + + +Скилл зовёт `av-dev-pipeline:review-pipeline`, `av-dev-docs:docs` и +`av-dev-tasks:tasks`. Чем оборачивается отсутствие каждого — на самих шагах и в +разделе «Границы». + +Перед стартом прочитай `CLAUDE.md` проекта и то, на что он ссылается, если ещё +не в контексте. Проектные факты, нужные ревью — инварианты, семантика гейта, +объёмы, модель угроз, прецеденты, — живут в **документах канона** `av-dev-docs`; +карта «что где» — `references/project-facts.md` конвейера ревью. + +**Документов канона нет — проект к нему не приведён.** Скажи это строкой и +предложи скилл `av-dev-docs:canon`: одна операция на проект против поразрядной +деградации на каждой задаче. Работу при этом не останавливай. + +## Вход + +Задача задаётся **путём к файлу, именем файла, слагом или просто текстом**. +Ничего из этого не задано — попроси у вызывающего и остановись; сам в беклог не +лезь и приоритеты не интерпретируй: что делать дальше, решает не этот скилл. + +**Запись, не готовая к работе, в работу не берётся.** У типа `research` это +проверяемо и потому обязательно: нет непустого раздела **«Вопрос»** — это не +разведка, а сырьё, и его сперва доводят до вопроса. Скажи это исходом и назови, +чего не хватает; штурмовать сырьё за автора — не работа этого скилла. + +У остальных типов схему держит `av-dev-tasks` (обязательные разделы, не меньше +двух критериев приёмки). Прочитай запись и, если видно, что схема не выполнена, +скажи это строкой — но работу не останавливай: у типов действия пробел лечится +по ходу, а у разведки без вопроса лечить нечего. + +## Две ветки + +Развилка одна и стоит на входе: + +- **обычная задача** — что делать, понятно; спорно только как. Идёт с шага 1; +- **исследовательская** — тип `research`, сырая идея, новое и незнакомое, мутная + постановка. Идёт с шага Р1, и там её ждёт **свой** чекпоинт: варианты решения + обсуждаются **до** того, как написано первое требование. + +Признак не в объёме работы, а в том, **есть ли у задачи один очевидный способ +решения**. Его нет — обсуждать варианты после `propose` поздно: предложение уже +воплотило один из них, и разговор пойдёт не о выборе, а о переделке. + +```mermaid +flowchart TD + in["вход: файл, слаг или текст"] + fork{"есть очевидный
способ решения?"} + r1["Р1. понять вопрос
сырьё без «Вопроса» — отказ"] + r2["Р2. opsx:explore — груминг"] + r3(["Р3. ЧЕКПОИНТ: варианты
2–4 способа, цена каждого,
рекомендация"]) + rout["исход без кода:
ответ записан / отказ / родились задачи"] + s1["1. прочитать задачу
критерии приёмки выписать сразу"] + s2["2. opsx:propose — change, дельта-спеки, tasks.md"] + s3["3. разметка — review-scope:
размер, сложность, метка, план тем"] + s4["4. ревью дизайна, состав по метке
+ отработка замечаний"] + s5(["5. ЧЕКПОИНТ: объяснение
в чём проблема, как решаем,
чем рискуем"]) + s6["6. opsx:apply — код, гейт,
поведенческая верификация"] + s7["7. ревью кода, та же метка
+ отработка замечаний"] + s8["8. opsx:archive"] + s9["9. синк документации — av-dev-docs:docs"] + s10["10. коммит работы — av-dev-git:commit"] + s11["11. закрыть задачу — av-dev-tasks:tasks,
вторым коммитом учёта"] + + in --> fork + fork -->|"да"| s1 + fork -->|"нет"| r1 + r1 --> r2 --> r3 + r3 -->|"выбран способ"| s1 + r3 -.->|"кода не будет"| rout + s1 --> s2 --> s3 --> s4 --> s5 --> s6 --> s7 --> s8 --> s9 --> s10 --> s11 + s3 -.->|"план задачи: та же метка"| s7 + s7 -.->|"находка отменяет дизайн"| s5 +``` + +Схема — **сводка**: содержание каждого шага в его разделе ниже, и при +расхождении прав текст. + +## Автономность и два плановых стопа + +**Между чекпоинтами умолчание прежнее — делать, а не спрашивать.** Чекпоинты не +отменяют автономность, они дают развилкам плановое место, куда копиться. + +Разрез простой: + +- развилка найдена **до** ближайшего чекпоинта — она его и ждёт. Не спрашивай + отдельно: чекпоинт рядом и стоит дёшево, а три вопроса подряд стоят дороже + одного разговора; +- развилка найдена **после** последнего чекпоинта — старое правило: **запиши + вопрос и доведи остаток**, не останавливаясь. + +Запись вопроса устроена так: + +1. **Запиши там, где проект держит вопросы** (секция беклога, файл задачи, + трекер — это знает проект). Проект не сказал, куда, — отдельной секцией + `Вопросы` в своём докладе, и это тоже исход. Тело отвечает на три вещи: **что + именно решить**, **какие есть варианты и цена каждого**, **что стоит, пока + решения нет**. Плюс твоя рекомендация — человек чаще соглашается, чем выбирает + заново, и готовое суждение экономит ему весь контекст. +2. **Переформулируй задачу на остаток** — то, что делается без этого решения. + Назови границу: докуда доводим сейчас. +3. Доведи остаток до конца и закоммить. Задача не «висит на вопросе», она сделана + в объявленных границах. + +**Что остатком не является — правило живёт не здесь.** Канонический текст с обеими +оговорками — в плагине `av-dev-tasks`, скилл `av-dev-tasks:session`, раздел +`## Вопрос, блокер, необратимое`, подраздел «Отличать вопрос от застревания». +Правило принадлежит управлению задачами, потому что решает **сделана задача или +вышла**, — это исход планирования, а не исполнения. **Ссылайся, не +пересказывай:** копия, заведённая здесь, уже однажды разошлась с оригиналом и +потеряла из перечня самое необратимое — запись **наружу**. + +Коротко, чтобы знать, когда идти читать: остаток проверяется двумя порогами — +**материализация нерешённого** (запись состояния, зависящего от неотвеченного +вопроса) и **пол по пользе** (из остатка пропала польза, названная в постановке). +Оба порога — стоп: первый поднимает решение до начала записи, второй даёт исход +«не доведена». + +Плагин `av-dev-tasks` не подключён — правило не отменяется, а становится +осторожнее: прежде чем записать зависящее от нерешённого куда бы то ни было — +в хранилище, в журнал, в витрину или наружу, — спрашивай человека. + +Нет полезного остатка — задача заканчивается исходом «не доведена», вопрос +записан, ничего не коммитится наполовину. + +### Когда спрашивать вне чекпоинтов + +По другому основанию — не «сложное решение», а **необратимое действие**: + +- деплой, выкладка наружу, смена публичного адреса или токенов; +- удаление или перезапись рабочих данных, включая подрезку архивов; +- всё, что уходит за пределы машины. + +Здесь ошибка не откатывается коммитом, поэтому спрашиваем даже когда решение +кажется очевидным. + +Стиль правок — заточка под проект и конвенции, right-size, без золочения. + +## Границы: чем этот скилл не владеет + +- **Беклогом, целями и приоритетами.** Задача приходит извне. Скилл её не + выбирает, не приоритизирует, не заводит и не переоценивает. +- **Форматом задач.** Индексы руками не правятся, путь к скрипту учёта не + выдумывается: этим владеет `av-dev-tasks:tasks` (шаг 11). Закрытие — работа + этого скилла, и это осознанное решение с названной ценой: **приёмщик и + исполнитель совпали**. Закрытие поэтому **не окончательно** — человек на сессии + возвращает задачу `reopen` с причиной, а доклад по критериям приёмки становится + единственным, по чему приёмка вообще возможна. +- **Заведением задач из урожая ревью.** Отложенные находки отдаются **списком**; + превращать их в задачи — работа того, кто ведёт задачи проекта. +- **Определением ценности.** «Нужна ли эта функциональность» — не вопрос этого + скилла ни на одном шаге. Чекпоинт спрашивает «так ли решаем», а не «надо ли». + +## Наблюдаемые исходы + +Ровно четыре, и каждый обязан быть назван в докладе прямо: + +- **сделана** — определение готовности выполнено целиком; +- **не доведена** — с причиной и с записанным вопросом; что именно сделано и до + какой границы, названо явно. Сюда же попадает чекпоинт, на котором человек + решение не одобрил; +- **оказалась крупнее задачи** — распознаётся **до заведения change**, иначе его + придётся выбрасывать. Дальше — декомпозиция, и это не работа этого скилла; +- **знание вместо изменения** — только у исследовательской ветки: ответ записан + по названному адресу, кода задача не потребовала. Это полноправный исход, а не + недоведённая работа. + +## Определение готовности + +Задача сделана, когда верно всё: + +1. гейт проекта зелёный; +2. ревью проведено, **план прогона сверен с исходом по каждой теме**, темы без + отчёта и без дома названы в границах покрытия; +3. решение прошло чекпоинт и не разошлось с одобренным — либо разошлось, и + чекпоинт был пройден заново; +4. change заархивирован, дельты влиты в актуальные спеки; +5. коммит сделан в текущую ветку; +6. **критерии приёмки, если проект их дал, выписаны поимённо, и по каждому назван + оракул и наблюдаемый исход** — «прогнал вот это, увидел вот то». Это **доклад, + а не сертификация: приёмка — не работа этого скилла.** Исполнитель, ставящий + себе галочку «принято», проверяет свою работу своим же взглядом — по границе + это может делать только приёмщик, разведённый с исполнителем. Критерии приходят + снаружи; скилл их не сочиняет и не занижает. Расхождение «по каждому критерию + исход есть, а суть задачи не достигнута» — дефект критериев, и о нём + сообщается, а не молча дорабатывается. + +У разведки, кончившейся знанием, определение своё и короткое: **ответ записан по +адресу, который назвала задача**, и в нём есть провенанс у каждого числа. + +## Исследовательская ветка + +### Р1. Понять вопрос + +Прочитай запись. У типа `research` в ней два обязательных раздела, и оба нужны +тебе прямо сейчас: **«Вопрос»** — на что отвечаем, **«Куда ляжет ответ»** — по +какому адресу он ляжет. Адрес назван заранее не из аккуратности: ответ, не +имеющий дома, остаётся в переписке, и через квартал разведку заказывают заново. + +Вопроса нет — исход «не доведена» с причиной «запись это сырьё»: назови, что +нужно дописать, и остановись. Адреса нет, а вопрос есть — назначь адрес сам и +скажи об этом строкой: разведка без дома для ответа хуже несделанной. + +Задача не из каталога (пришла текстом) — адреса у неё нет по построению. Тогда +дом ответа — `design.md` того change, который родится дальше; кода не будет — +`docs/research/`, и это тоже говорится строкой. + +### Р2. Груминг — `opsx:explore` + +Вызови Skill `opsx:explore`. Читай документы проекта, а не только запись: +граница домена и «чем проект **не** является» из паспорта отсекают половину +вариантов до того, как их начнут сравнивать. **В explore не пишем код.** + +Развилку грумминга **не записывай вопросом** — она и есть предмет следующего +шага. Это отличие от обычной ветки: там развилка уходит в запись, здесь она +копится в чекпоинт. + +### Р3. Чекпоинт: варианты + +**Остановись и покажи человеку способы решить.** Это первый из двух плановых +стопов, и он существует потому, что после `propose` выбор уже сделан +предложением. + +Форма — короткая, экран текста: + +- **вопрос**, на который отвечаем, одной фразой (он уже есть в записи); +- **2–4 варианта**, не больше. Больше четырёх — это не выбор, а список: человек + не сравнит, а признает свою неспособность сравнить и попросит рекомендацию. + У каждого варианта: в чём суть простыми словами, **что даёт**, **чего стоит**, + **что становится невозможным** (это ловится хуже всего и стоит дороже всего); +- **рекомендация с причиной**. Человек чаще соглашается, чем выбирает заново; +- что известно **недостоверно** и как это проверить, если проверять дёшево. + +Что нельзя: приносить варианты, различающиеся только реализацией; прятать +отвергнутое (отвергнутый вариант с названной причиной — половина будущего ADR); +приносить один вариант и называть это выбором. + +**Выбор оседает по адресу.** У `research` это раздел «Куда ляжет ответ». У +остальных — `design.md` change, который родится на шаге 2, разделом +«рассмотренные варианты». Не в переписку: разговор, из которого ничего не +записано, повторяется через месяц целиком. + +Три исхода чекпоинта: + +- **выбран способ** — идёшь на шаг 1 общей ветки; +- **ответ и есть исход** — работа кончается знанием: запиши ответ по адресу, + доложи исход «знание вместо изменения» и закрой задачу (шаг 11). Провенанс у + каждого числа обязателен: число без источника проход ревью обязан читать как + условие, а не как замер; +- **разведка родила задачи** — исход «оказалась крупнее задачи». Нарезка не твоя + работа: отдай список формулировками и остановись. + +## Шаги + +### 1. Прочитать задачу + +Прочитай запись и связанные спеки и черновики. + +Проект даёт задаче **критерии приёмки** — выпиши их сразу: на шаге 2 они уезжают +в `tasks.md` change. Файл задачи может быть удалён до коммита, а критерии обязаны +его пережить. + +Здесь же проверка на «крупнее задачи»: видно, что одним заходом это не +мерджится, — объявляй исход **до** заведения change. + +### 2. Завести change — `opsx:propose` + +Вызови Skill `opsx:propose`. Получаем `proposal.md`, дизайн, дельта-спеки +(`ADDED`/`MODIFIED`/`REMOVED Requirements`), `tasks.md`. Каждое `### Requirement` +содержит `SHALL`/`MUST`; структурные заголовки английские, сценарии +`GIVEN/WHEN/THEN`. Прогони `openspec validate --strict `. + +Критерии приёмки задачи, если они были, копируются в `tasks.md` отдельным блоком. +Варианты, разобранные на чекпоинте Р3, — в `design.md`, с причиной отказа по +каждому отвергнутому. + +**`proposal.md` пишется так, чтобы его понял человек, не читавший спек.** Это не +стилистическое пожелание: из него собирается чекпоинт шага 5, и переписывать его +там заново значит завести второй дом для одного объяснения. Требование стоит в +`openspec/config.yaml`, `rules.proposal` — то есть применяется в момент +порождения артефакта, а не вспоминается после. + +### 3. Разметка задачи — агент `review-scope` + +**Один запуск на всю задачу, и он обслуживает оба чекпоинта ревью.** Запусти +агента `review-scope`, дав ему корень проекта, идентификатор change, базу диффа и +запись задачи. Кода на этот момент нет, и это условие его работы, а не помеха. + +Он возвращает **план задачи**: + +- **размер** (малое / среднее / крупное) и **сложность** (знакомое / + незнакомое), каждое с обоснованием по факту; +- **метку** как максимум по двум осям: `small`, `medium` или `large`; +- **состав ревью дизайна** — что звать на шаге 4; +- **таблицу тем** «тема → дом → глубина → кто закрывает» — для шага 7; +- разнесение документов проекта по трём категориям и строку про директивы. + +**Метку выбираешь не ты.** Раньше состав ревью дизайна называл сам оркестратор — +то есть тот, кто только что довёл предложение до `propose`. Разведённости с +автором в этой точке не было вовсе; теперь есть. + +**План держи в контексте до конца задачи.** На диск он не пишется: файл-план стал +бы четвёртым артефактом рядом с `proposal.md`, `tasks.md` и `design.md`, пережил +бы задачу и разошёлся бы с ней молча. Прервался прогон — повтори шаг 3, это самый +дешёвый его проход. + +**Разметка повторяется ровно в одном случае** — если правки изменили сами +**дельта-спеки**: план выведен из них, и план по отменённым требованиям назовёт +не те темы. Во всех прочих случаях, включая переделку формы кода на шаге 7, +метка остаётся прежней. + +### 4. Ревью дизайна — ДО кода, состав по метке + +Вызови Skill **`av-dev-pipeline:review-pipeline`**, дав ссылку на change ``, +**план разметки с шага 3** и указание, что это ревью дизайна. + +Состав приходит планом, а не решается здесь: + +| Метка | Проходы на предложении | +|---|---| +| `small` | `specs` | +| `medium` | `specs`, `rubric` | +| `large` | `specs`, `rubric`, `architecture` + вопрос автору о трёх формах решения | + +`review-specs` в режиме «дизайн ДО кода» идёт **на каждой задаче**: это самый +дешёвый чекпоинт конвейера, и он ловит то, что на готовом коде уже не чинят. +Остальные включаются меткой, потому что стадия стоит на каждой задаче и каждый +лишний проход здесь умножается на число задач. + +Смысл стадии: архитектурная находка на готовом коде стоит переписывания и потому +игнорируется — та же находка здесь стоит абзаца обсуждения. Если `review-rubric` +запускался, перенеси его рубрику в `tasks.md` как приёмочные критерии; там же уже +лежат критерии от постановки, если они были. + +**Отработка замечаний, и она идёт до чекпоинта, а не после:** + +- мелочь и явные улучшения — правь сам в спеках и дизайне; +- развилки (компромисс, scope, инвариант) — **не в запись, а в чекпоинт**: он + следующим шагом, и это ровно то, ради чего он поставлен здесь; +- после правок перепрогони `openspec validate --strict `. + +### 5. Чекпоинт: объяснение + +**Остановись и объясни человеку, что происходит.** Второй плановый стоп и +единственный обязательный для всех задач. + +Он стоит **после** ревью дизайна намеренно. Человек читает объяснение, уже +просеянное машиной: то, что поймал бы `review-specs`, до него не доходит, а +внимание — самый дорогой ресурс процесса, и тратить его на выловимое машиной +нельзя. + +**Объяснение не сочиняется заново — оно собирается из артефактов**, `proposal.md` +и `design.md`. Третий пересказ был бы третьим домом одного и того же и разошёлся +бы с обоими. Что показываешь: + +- **в чём проблема** — словами домена из паспорта, без имён модулей и функций; +- **как решаем** — суть одним абзацем. Не пересказ дельта-спек: спека нормирует, + а здесь объясняют; +- **что человек увидит иначе**, когда это будет сделано; +- **чего мы намеренно не делаем** и почему — граница scope ловится хуже всего; +- **чем рискуем и что осталось нерешённым** — сюда съезжаются развилки, + накопленные до этого места, и находки ревью с пометкой `развилка`; +- **что дальше**, если возражений нет. + +Проверка на «простой язык» одна и механическая: **в тексте нет `SHALL`, нет имён +файлов и функций там, где вещь называется по-русски, и нет слов, которых нет в +паспорте проекта.** Не проходит — переписывай, а не объясняй, почему иначе +нельзя. + +Длина — экран. Длинное объяснение не читают, а пролистывают, и чекпоинт +превращается в ритуал одобрения. + +Три исхода: + +- **согласен** — идёшь на шаг 6; +- **скорректировать** — правишь спеки и дизайн по сказанному. Изменились + **дельта-спеки** — повтори шаг 3 (разметка выведена из них) и ту часть ревью + дизайна, которой касается правка; затем чекпоинт **заново**. Правка внутри + дизайна без спек — повтори только чекпоинт; +- **не одобрено** — исход «не доведена» с причиной. Change остаётся + незаархивированным, задача не закрывается, ничего не коммитится наполовину. + +### 6. Написать код — `opsx:apply` + +Вызови Skill `opsx:apply` для реализации `tasks.md`. Код — по конвенциям проекта +(каталог `docs/conventions/`). Меняешь схему — обнови её описание в документации +тем же change, если проект этого требует: гейт обычно это проверяет. + +Прогони гейт и добейся зелёного — он же гейт следующего шага. + +**Поведенческая верификация.** Если задача меняет реальное поведение (новый +эндпоинт, разбор входа, схема, форма ответа) — зелёных юнит-тестов мало. Подними +изменение вживую командой из раздела команд `CLAUDE.md` и прогони сценарий. +Пропусти только для чисто внутренних правок без наблюдаемого рантайма. + +**Сервис не оставляем лежать.** Если запуск упал — почини или откати до конца +шага. + +### 7. Ревью кода — та же метка + +Вызови Skill **`av-dev-pipeline:review-pipeline`**, дав ссылку на change ``, +базу диффа, **план разметки с шага 3** и режим запуска. + +**Метку ты не выбираешь, и это правило, а не упрощение.** Её назвал +`review-scope` ещё на шаге 3 — по размеру и сложности, с обоснованием по каждой +оси. Причина в разведённости: ты только что написал этот код, и решать, насколько +глубоко его проверять, тебе нельзя — под давлением «я почти закончил» решение +известно заранее. Правило выбора живёт в скилле конвейера — +`av-dev-pipeline:review-pipeline`, `references/review-levels.md`; проектные +триггеры — в `docs/review.*`, подраздел «Триггеры метки». + +**Метка не пересматривается по факту диффа.** Дифф может выйти крупнее, чем +ожидалось при разметке, — это не повод её поднимать: пересмотр означал бы второй +запуск разметчика, ровно то, ради устранения чего он и переехал на шаг 3. + +**Считаешь метку заниженной — скажи это в докладе строкой, а не переспорь.** +Разметчик вправе и поднять, и понизить; твоё несогласие это факт для человека, а +не команда конвейеру. Место, где такое несогласие превращается в изменение +правил, — журнал дефектов `docs/review.md`, и только постфактум. + +**Плана нет — ревью кода не запускается.** Триаж требует план обязательным +входом: без него он не может сверить, все ли размеченные темы вернули отчёт, а +эта сверка — единственная защита от молчащего пропуска. Потерял план (прервалась +сессия, ушёл контекст) — повтори шаг 3, а не гони прогон без него. + +**Режим по умолчанию — `по графу`, и обосновывать его не надо.** Конвейер сам +знает свои рёбра: гейт открывает опиниативные проходы, проходы с пометкой «держит +машину» идут цепочкой (иначе замеры портят друг друга и находка выглядит +доказанной), триаж — сток. Просить **`линейно`** нужно только по причине, и она +называется строкой: так сказал оператор; машина занята чем-то ещё; идёт разбор +самого конвейера. + +Скилл сам гоняет гейт, нужные проходы и обязательный триаж. Возвращает отчёт с +потолком 7 пунктов, разметкой `Действие: инлайн | развилка` и секцией границ +покрытия. + +**Сверь план прогона с исходом, прежде чем коммитить.** Отчёт начинается планом +разметчика — таблицей «тема → дом → глубина → кто закрывает», — и против каждой +темы обязан стоять исход. Тема без отчёта и тема без дома — разные вещи, и обе +должны быть названы. Реестр короткий (шесть тем ядра плюс свои) — сверка стоит +одного взгляда. + +#### Отработка, и здесь появляется одно новое правило + +Помеченное `инлайн` чини сам и не логируй. `развилка` — вопросом в запись (он уже +сформулирован триажем, его остаётся перенести). После правок — снова гейт. + +**Находка, отменяющая одобренный дизайн, отменяет и одобрение.** Признак +проверяемый: **меняются ли дельта-спеки**. + +- не меняются — находка внутри дизайна, дожимай сам, это обычная отработка; +- меняются — решение стало другим, а одобрено было прежнее. Повтори шаг 3 + (разметка выведена из дельта-спек) и **вернись на чекпоинт шага 5** с тем, что + изменилось и почему. + +Тихо переделать утверждённое нельзя. Чекпоинт, который можно обойти находкой +ревью, не значит ничего, а человек при этом уверен, что одобрил именно то, что +уехало в коммит. + +**Урожай — списком, не задачами.** Отложенные находки (реальный `major` не для +этого мерджа, развилка, решённая «потом», пачка `nit`) собери в секцию доклада +`Урожай`: формулировка, оракул, провенанс. Задачи из него **заводит не этот +скилл** — у того, кто ведёт задачи проекта, своя нарезка, свой формат и свои +правила дублей. Твоя обязанность — не потерять и передать. + +**Границы покрытия из отчёта не выбрасывай** — они уезжают в финальный доклад +сжатой строкой. Отчёт, из которого исчезло «что проверить было невозможно», +превращается в ложное ощущение проверенности. + +**Отчёт триажа сохрани вместе с change (`openspec/changes//review/`; шаг 8 +унесёт его в архив вместе с change) — это обязательно, а не «если удобно».** По +нему потом видно, что было найдено и что из этого осталось в урожае. И это +единственный **независимый** артефакт о составе прогона: своей прозе здесь верить +нельзя — она написана тем же, кто мог проход и пропустить. + +### 8. Архивировать — `opsx:archive` + +Вызови Skill `opsx:archive`: change уезжает в архив, дельты вливаются в +актуальные спеки. Не пропускай `openspec validate --strict` перед этим. + +### 9. Синк документации + +**Вызови Skill `av-dev-docs:docs`**: он владеет содержимым документов канона и +ведёт чек-лист синка. + +**Правило одно и оно жёсткое: принуждённое отрицание.** Доклад обязан назвать +**каждый** документ канона — либо чем он обновлён, либо «не требуется, потому +что…». Нетронутые группируются одной строкой с общей причиной. Список триггеров +прозой уже проверен на живом проекте и дал 6 записей ADR на 43 изменения; +работает только обязательное отрицание. + +**Список документов и их триггеров здесь не дублируется** — он в чек-листе скилла +`av-dev-docs:docs`, и копия уже однажды разошлась с оригиналом, потеряв два +триггера. + +**Плагина `av-dev-docs` в проекте нет** — путь в его дерево не разрешится ниоткуда, +поэтому за списком иди в **свой** reference: +[references/project-facts.md](../review-pipeline/references/project-facts.md) +конвейера ревью перечисляет все документы канона с их предметом. Пройди по этому +перечню — каждый документ получает строку, отрицание остаётся обязательным. +Триггеры при этом ты знаешь хуже, и это называется в докладе строкой: «синк +сделан по перечню документов, без списка триггеров — плагина `av-dev-docs` нет». +Канона в проекте тоже нет — назови это исходом и предложи `av-dev-docs:canon`. + +### 10. Коммит + +Коммить **в текущую ветку** (`git rev-parse --abbrev-ref HEAD`), сам ветку не +создавай и не переключай, ничего не пушь. + +Сообщение — по-русски, скиллом `av-dev-git:commit`, если он подключён (первая +строка «что сделано», тело списком 1–3 пункта, без трейлеров). Одна задача — один +осмысленный коммит. + +### 11. Закрыть задачу — **после коммита, не раньше** + +**Вызови Skill `av-dev-tasks:tasks`** и попроси закрыть задачу как реализованную — +он владеет форматом и двигает строку индекса сам. Путь к его скрипту не выясняй и +индексы руками не правь: мост между плагинами — вызов скилла, а не путь. + +**Порядок обязателен.** Закрытие удаляет файл задачи; сделанное до коммита оно +оставило бы задачу закрытой без единого следа работы, если шаг 10 упадёт. + +**Закрытие тоже коммитится — вторым коммитом, тут же.** Удаление файла задачи и +правка индексов (их имена знает `av-dev-tasks`, не ты) — это правки в рабочем +дереве, и оставить их незакоммиченными нельзя: закрытие, не доехавшее до основной +ветки, оставит задачу открытой молча, а опора «индексы под git показывают, что и +когда закрыто» без коммита — пустые слова. Сообщение короткое, про учёт, а не про +работу: `закрыта задача `. Это второй коммит осознанно: правило «одна задача +— один осмысленный коммит» про работу, а учёт — не работа. + +Разведка, кончившаяся знанием, закрывается так же — но перед этим убедись, что +ответ **записан по названному адресу и закоммичен**. Закрытая разведка без +записанного ответа не оставляет следа вообще: файл задачи удалён, ответ был в +переписке. + +Плагина в проекте нет — вызов не разрешится. Тогда **ничего не выдумывай**: скажи +в докладе, что учёт задач остаётся за владельцем, и назови исход. + +## Доклад + +Коротко, и в нём обязательно: + +- **исход** одним из четырёх слов и, если не «сделана», чем ограничен результат; +- что сделано, какие вопросы записаны и куда; +- **что было одобрено на чекпоинте и совпало ли с тем, что уехало в коммит** — + расхождение здесь называется прямо, даже если оно мелкое; +- ссылка на архивный change и хеш коммита; +- по каждому критерию приёмки, если они были: **оракул и наблюдаемый исход** — + это доклад приёмщику, а не отметка «принято»; +- **`Урожай`** — отложенные находки списком (формулировка, оракул, провенанс); +- **одна строка границ покрытия**: какая метка и режим гонялись, какие проходы не + запускались и что проверить было невозможно. Доклад без неё сообщает + «проверено», не сообщая, что именно. + +## Тонкости + +- **Не завязывайся на основную ветку и корень репозитория.** Скилл работает в + текущем worktree и на текущей ветке: не делай `git checkout`/`switch`, не + создавай веток, не пушь. +- Обычная задача с очевидным решением проходит **один** чекпоинт, и это норма, а + не упрощение. Два чекпоинта — цена незнания, а не признак серьёзности задачи. +- Гейт блокирует: пока он красный, опиниативные проходы не запускаются. Чинить и + перезапускать, а не «посмотреть заодно». +- Держи вызывающего в цикле короткими репликами на переходах фаз, но не проси + подтверждать механику: чекпоинты — единственные места, где ждут ответа. +- **Занизить метку ревью, пропустить тему или проскочить чекпоинт — самый дешёвый + способ «ускориться», и он же самый дорогой по последствиям.** Защита устроена + так, что регулятора у тебя нет: метку выбирает разметчик **до того**, как ты + написал код, план сверяется по темам, непокрытое называется строкой, а + расхождение с одобренным — отдельным пунктом доклада. diff --git a/av-dev-pipeline/skills/review-pipeline/SKILL.md b/av-dev-pipeline/skills/review-pipeline/SKILL.md index 48dfca5..1b8a571 100644 --- a/av-dev-pipeline/skills/review-pipeline/SKILL.md +++ b/av-dev-pipeline/skills/review-pipeline/SKILL.md @@ -848,8 +848,8 @@ Recall темы `conventions` равен длине конвенций прое ## Ревью дизайна — до кода -Запускается на первом чекпоинте ревью (шаг 5 скилла -`av-dev-pipeline:task-pipeline`), когда change уже имеет `proposal.md` и +Запускается на первом чекпоинте ревью (шаг 4 скилла +`av-dev-pipeline:resolve`), когда change уже имеет `proposal.md` и дельта-спеки, но кода ещё нет. Разметка задачи к этому моменту уже прошла — она шагом раньше, и метка известна. diff --git a/av-dev-pipeline/skills/task-pipeline/SKILL.md b/av-dev-pipeline/skills/task-pipeline/SKILL.md deleted file mode 100644 index 99498df..0000000 --- a/av-dev-pipeline/skills/task-pipeline/SKILL.md +++ /dev/null @@ -1,511 +0,0 @@ ---- -name: task-pipeline -description: "Автономно проводит одну задачу через полный цикл Spec Driven Development — от постановки до коммита (opsx explore→propose→разметка задачи→ревью дизайна→apply→ревью кода→archive→коммит), с обязательными чекпоинтами ревью и докладом об исходе. Разметка идёт один раз, сразу после propose: она называет размер, сложность и метка, и её план определяет состав обеих стадий ревью. Использовать, когда просят взять/сделать задачу или довести идею до реализации." ---- - -# Пайплайн задачи - -Оркестратор **одной** задачи по Spec Driven Development: проводит её от -постановки до коммита максимально автономно. Механику не согласовываем — делаем. - -Это тонкая обёртка над каноническими скиллами `opsx:explore` / `opsx:propose` / -`opsx:apply` / `opsx:archive` — вызывай их через Skill, не переизобретай их шаги. -Ревью — скилл `av-dev-pipeline:review-pipeline`; он же держит правило выбора -метки, а называет её агент `review-scope` на шаге 4 — один раз на задачу, для -обеих стадий ревью. - -## Предпосылки - -- **OpenSpec и скиллы `opsx:*` — жёсткая предпосылка, а не опция.** На них стоят - шаги 2, 3, 7 и 9, проход `review-specs` и ревью дизайна (они завязаны на - `openspec/changes//specs/*/spec.md` и на `openspec validate --strict`). - **Проект без OpenSpec этим пайплайном не ведётся** — подключай OpenSpec, а не - вырождай цикл: ветка деградации здесь не пишется, потому что непроверенная - ветка деградации хуже честного отказа. -- **Проектные копии этих скиллов и агентов удаляются при установке плагина** - (`.claude/skills/` — и голые имена `task-pipeline`, `review-pipeline`, - `task-batch`, и с префиксом проекта: `<проект>-task-pipeline`, - `<проект>-review-pipeline`; - `.claude/agents/<проект>-review-*.md`). Две копии одного скилла расходятся, и - побеждает та, что короче названа. - -### Обращение к соседним плагинам - -**Копия.** Дом — `shared/plugin-boundary.md` в репозитории плагинов: правило -общее для всех семи скиллов, зовущих чужое, и ни один плагин им не владеет. -Правится дом, а не этот файл. - - - -Плагины `av-dev` ставятся порознь, и ни один не вправе считать, что сосед на -месте. - -**Чужой скилл зовётся полным именем** — `av-dev-docs:canon`, -`av-dev-tasks:tasks`, `av-dev-pipeline:review-pipeline`. Короткое имя может -разрешиться в устаревшую проектную копию из `.claude/skills/`, и подмены не будет -видно ни в докладе, ни в поведении. - -**Путь в дерево чужого плагина не пишется никогда.** `$CLAUDE_PLUGIN_ROOT` ведёт -только в свой плагин; вычисленный от него путь к соседу либо не откроется, либо -откроет чужую установку. Нужен чужой справочник — зови владеющий им скилл, он -прочитает его сам. - -**Вызов не разрешился — плагина в проекте нет.** Это исход, а не поломка: назови -строкой доклада, чего теперь не делает никто, и продолжай работу. Молчать нельзя, -пропуск неотличим от сделанного; выдумывать обходной путь нельзя тоже. - -**Присутствие узнаётся вызовом или следом в проекте, но не объявлением.** Перечня -установленных плагинов проект не ведёт — он разошёлся бы с действительностью -молча. Что сосед здесь работал, видно по заведённому им файлу: `docs/.pm.json` — -канон, `<каталог задач>/.tasks.json` — задачи, `openspec/config.yaml` — конвейер. - - - -Пайплайн зовёт `av-dev-pipeline:review-pipeline`, `av-dev-docs:docs` и -`av-dev-tasks:tasks`. Чем оборачивается отсутствие каждого — на самих шагах и в -разделе «Границы». - -Перед стартом прочитай `CLAUDE.md` проекта и то, на что он ссылается, если ещё -не в контексте. Проектные факты, нужные ревью — инварианты, семантика гейта, -объёмы, модель угроз, прецеденты, — живут в **документах канона** `av-dev-docs`; -карта «что где» — `references/project-facts.md` конвейера ревью. - -**Документов канона нет — проект к нему не приведён.** Скажи это строкой и -предложи скилл `av-dev-docs:canon`: одна операция на проект против поразрядной -деградации на каждой задаче. Работу при этом не останавливай. - -## Границы: чем пайплайн не владеет - -- **Беклогом, спринтом, целями и приоритетами.** Задача приходит извне. Пайплайн - её не выбирает, не приоритизирует, не заводит и не переоценивает; если в - проекте есть свой процесс управления задачами — он и решает, что брать. -- **Форматом задач.** Пайплайн **не правит индексы руками и не выдумывает путь - к скрипту учёта**: он зовёт Skill `av-dev-tasks:tasks`, который этим владеет - (шаг 12). Закрытие как таковое — его работа, и это осознанное решение с - названной ценой: **приёмщик и исполнитель совпали**. Закрытие поэтому **не - окончательно** — человек на сессии возвращает задачу `reopen` с причиной, а - доклад по критериям приёмки становится единственным, по чему приёмка вообще - возможна. Плагина `av-dev-tasks` в проекте нет — вызов не разрешится, и тогда - учёт остаётся владельцу, о чём говорится в докладе. -- **Заведением задач из урожая ревью.** Отложенные находки отдаются **списком** - (см. шаг 8); превращать их в задачи — работа того, кто ведёт задачи проекта. -- **Определением ценности.** «Нужна ли эта функциональность» — не вопрос - пайплайна ни на одном шаге. - -Пайплайн владеет **своим** определением готовности (ниже) и **сообщает -наблюдаемый исход**. Что с исходом делать дальше — не его дело. - -## Наблюдаемые исходы - -Ровно три, и каждый обязан быть назван в докладе прямо: - -- **сделана** — определение готовности выполнено целиком; -- **не доведена** — с причиной и с записанным вопросом; что именно сделано и до - какой границы, названо явно; -- **оказалась крупнее задачи** — распознаётся **до заведения change**, иначе его - придётся выбрасывать. Дальше — декомпозиция, и это не работа пайплайна. - -## Определение готовности - -Задача сделана, когда верно всё: - -1. гейт проекта зелёный; -2. ревью проведено, **план прогона сверен с исходом по каждой теме**, темы без - отчёта и без дома названы в границах покрытия; -3. change заархивирован, дельты влиты в актуальные спеки; -4. коммит сделан в текущую ветку; -5. **критерии приёмки, если проект их дал, выписаны поимённо, и по каждому назван - оракул и наблюдаемый исход** — «прогнал вот это, увидел вот то». Это **доклад, - а не сертификация: приёмка — не работа пайплайна.** Исполнитель, ставящий себе - галочку «принято», проверяет свою работу своим же взглядом — по границе это - может делать только приёмщик, разведённый с исполнителем. Критерии приходят снаружи; - пайплайн их не сочиняет и не занижает. Расхождение «по каждому критерию исход - есть, а суть задачи не достигнута» — дефект критериев, и о нём сообщается, а - не молча дорабатывается. - -Пункты 1–4 — своё. Пункт 5 — внешнее: пайплайн доводит его до наблюдаемого -исхода и передаёт дальше. - -## Принцип автономности - -**Умолчание — делать, а не спрашивать.** Задача доводится до коммита без участия -человека; предполагается, что так пройдёт большинство задач. - -Наткнулся на вопрос, который решать не тебе, — **не останавливайся и не -спрашивай**. Запиши его и продолжай: - -1. **Запиши вопрос там, где проект держит вопросы** (секция беклога, файл - задачи, трекер — это знает проект). Если проект не сказал, куда, — отдельной - секцией `Вопросы` в своём докладе, и это тоже исход. Тело отвечает на три - вещи: **что именно решить**, **какие есть варианты и цена каждого**, **что - стоит, пока решения нет**. Плюс твоя рекомендация — человек чаще соглашается, - чем выбирает заново, и готовое суждение экономит ему весь контекст. -2. **Переформулируй задачу на остаток** — то, что делается без этого решения. - Назови границу: докуда доводим сейчас. -3. Доведи остаток до конца и закоммить. Задача не «висит на вопросе», она сделана - в объявленных границах. - -**Что остатком не является — правило живёт не здесь.** Канонический текст с обеими -оговорками — в плагине `av-dev-tasks`, скилл `av-dev-tasks:session`, раздел -`## Вопрос, блокер, необратимое`, подраздел «Отличать вопрос от застревания». -Правило принадлежит управлению задачами, потому что решает **сделана задача или -вышла**, — это исход планирования, а не исполнения. **Ссылайся, не -пересказывай:** копия, заведённая здесь, уже однажды разошлась с оригиналом и -потеряла из перечня самое необратимое — запись **наружу**. - -Коротко, чтобы знать, когда идти читать: остаток проверяется двумя порогами — -**материализация нерешённого** (запись состояния, зависящего от неотвеченного -вопроса) и **пол по пользе** (из остатка пропала польза, названная в постановке). -Оба порога — стоп: первый поднимает решение до начала записи, второй даёт исход -«не доведена». - -Плагин `av-dev-tasks` не подключён — правило не отменяется, а становится -осторожнее: прежде чем записать зависящее от нерешённого куда бы то ни было — -в хранилище, в журнал, в витрину или наружу, — спрашивай человека. - -Нет полезного остатка — задача заканчивается исходом «не доведена», вопрос -записан, ничего не коммитится наполовину. - -### Когда всё-таки спрашивать - -Узко и по другому основанию — не «сложное решение», а **необратимое действие**: - -- деплой, выкладка наружу, смена публичного адреса или токенов; -- удаление или перезапись рабочих данных, включая подрезку архивов; -- всё, что уходит за пределы машины. - -Здесь ошибка не откатывается коммитом, поэтому спрашиваем даже когда решение -кажется очевидным. Развилка в дизайне — вопрос в запись; необратимое действие — -вопрос человеку сейчас. - -Стиль правок — заточка под проект и конвенции, right-size, без золочения. - -## Шаги - -Двенадцать шагов с одной развилкой и одним досрочным исходом: - -```mermaid -flowchart TD - s1["1. Прочитать задачу
критерии приёмки выписать сразу"] - triv{"тривиальная?"} - big["исход «оказалась крупнее задачи»
объявляется ДО заведения change"] - s2["2. opsx:explore — груминг идеи"] - s3["3. opsx:propose — change, дельта-спеки, tasks.md"] - s4["4. разметка задачи — review-scope:
размер, сложность, метка, план тем"] - s5["5. ревью дизайна, состав по метке"] - s6["6. отработать замечания + validate --strict"] - s7["7. opsx:apply — код, гейт, поведенческая верификация"] - s8["8. ревью кода, состав по той же метки"] - s9["9. opsx:archive"] - s10["10. синк документации — av-dev-docs:docs"] - s11["11. коммит работы — av-dev-git:commit"] - s12["12. закрыть задачу — av-dev-tasks:tasks,
вторым коммитом учёта"] - - s1 --> triv - s1 -.-> big - triv -->|"нет: идея или мутная постановка"| s2 - s2 --> s3 - triv -->|"да: шаг 2 пропускается"| s3 - s3 --> s4 --> s5 --> s6 --> s7 --> s8 --> s9 --> s10 --> s11 --> s12 - s4 -.->|"план задачи: та же метка"| s8 -``` - -**Разметка стоит одна и обслуживает обе стадии ревью** — шаги 5 и 8. Это и есть -пунктирное ребро на схеме: план, посчитанный на шаге 4, доезжает до ревью кода -без пересчёта. Раньше разметка была первым проходом внутри шага ревью кода, а -состав ревью дизайна называл сам пайплайн — то есть одна и та же величина -считалась дважды, и один из двух раз тем, кто только что написал предложение. - -Два чекпоинта ревью — шаги 5 и 8 — единственные места, где зовётся конвейер; -порядок «сперва коммит работы, потом коммит учёта» на схеме тоже ребро, и оно -обязательное (шаг 12). - -Схема — **сводка**: содержание каждого шага в его разделе ниже, и при -расхождении прав текст. - -### 1. Прочитать задачу - -Задача задана извне (slug, файл, ссылка, описание) — прочитай её и связанные -спеки и черновики. Не задана — попроси у вызывающего; сам в беклог не лезь и -приоритеты не интерпретируй. - -Если проект даёт задаче **критерии приёмки**, выпиши их сразу: на шаге 3 они -уезжают в `tasks.md` change. Файл задачи может быть удалён до коммита, а -критерии обязаны его пережить. - -Оцени тривиальность — **теперь она влияет ровно на один шаг, второй**: - -- **тривиальная** — локальная правка без изменения поведения, спек и схемы, - решение очевидно. Explore пропускается; -- **нетривиальная** — новое или изменённое поведение, дизайн-развилки, задеты - инварианты, схема или несколько capability. Полный цикл. - -**На состав ревью тривиальность больше не влияет** — это работа шага 4. Раньше -она решала и то, звать ли ревью предложения вовсе; теперь глубину обеих стадий -называет метку, и тривиальная задача просто получает `small`. Разница -существенная: «пропустить ревью дизайна» и «пройти его одним самым дешёвым -проходом» — не одно и то же, а сверка дельта-спек стоит меньше, чем разбор того, -что она поймала бы. - -Здесь же — проверка на «крупнее задачи»: если видно, что одним заходом это не -мерджится, объявляй исход **до** заведения change. - -### 2. (Опц.) Груммить идею — `opsx:explore` - -Только для идей и мутных постановок. Вызови Skill `opsx:explore`. Развилку -грумминга не выноси на человека — запиши вопросом и груми остаток. Выход: ясная -постановка, готовая к propose. **В explore не пишем код.** - -### 3. Завести change — `opsx:propose` - -Вызови Skill `opsx:propose`. Получаем `proposal.md`, дизайн (для нетривиальных), -дельта-спеки (`ADDED`/`MODIFIED`/`REMOVED Requirements`), `tasks.md`. Каждое -`### Requirement` содержит `SHALL`/`MUST`; структурные заголовки английские, -сценарии `GIVEN/WHEN/THEN`. Прогони `openspec validate --strict `. - -Критерии приёмки задачи, если они были, копируются в `tasks.md` отдельным блоком. - -### 4. Разметка задачи — агент `review-scope` - -**Один запуск на всю задачу, и он обслуживает оба чекпоинта ревью.** Запусти -агента `review-scope`, дав ему корень проекта, идентификатор change, базу диффа и -запись задачи. Кода на этот момент нет, и это условие его работы, а не помеха. - -Он возвращает **план задачи**: - -- **размер** (малое / среднее / крупное) и **сложность** (знакомое / - незнакомое), каждое с обоснованием по факту; -- **метка** как максимум по двум осям: `small`, `medium` или `large`; -- **состав ревью дизайна** — что звать на шаге 5; -- **таблицу тем** «тема → дом → глубина → кто закрывает» — для шага 8; -- разнесение документов проекта по трём категориям и строку про директивы. - -**Метка выбираешь не ты.** Раньше состав ревью дизайна называл этот пайплайн -(«крупное или незнакомое?»), то есть тот же оркестратор, который только что -довёл предложение до `propose`. Разведённости с автором в этой точке не было -вовсе; теперь есть. - -**План держи в контексте до конца задачи.** На диск он не пишется: файл-план стал -бы четвёртым артефактом рядом с `proposal.md`, `tasks.md` и `design.md`, пережил -бы задачу и разошёлся бы с ней молча. Прервался пайплайн — повтори шаг 4, это -самый дешёвый его проход. - -**Разметка повторяется ровно в одном случае** — если на шаге 6 правки изменили -сами **дельта-спеки**: план выведен из них, и план по отменённым требованиям -назовёт не те темы. Во всех прочих случаях, включая переделку формы кода на шаге -8, метка остаётся прежней. - -### 5. Ревью предложения — ДО кода, состав по метке - -Первый чекпоинт. Вызови Skill **`av-dev-pipeline:review-pipeline`**, дав ссылку на -change ``, **план разметки с шага 4** и указание, что это ревью дизайна. - -Состав приходит планом, а не решается здесь: - -| Метка | Проходы на предложении | -|---|---| -| `small` | `specs` | -| `medium` | `specs`, `rubric` | -| `large` | `specs`, `rubric`, `architecture` + вопрос автору о трёх формах решения | - -`review-specs` в режиме «дизайн ДО кода» идёт **на каждой задаче**: это самый -дешёвый чекпоинт конвейера, и он ловит то, что на готовом коде уже не чинят. -Остальные включаются меткой, потому что чекпоинт стоит на каждой задаче и -каждый лишний проход здесь умножается на число задач. - -Смысл стадии: архитектурная находка на готовом коде стоит переписывания и -потому игнорируется — та же находка здесь стоит абзаца обсуждения. Если -`review-rubric` запускался, перенеси его рубрику в `tasks.md` как приёмочные -критерии; там же уже лежат критерии от постановки, если они были. - -### 6. Отработать замечания ревью предложения - -- Мелочь и явные улучшения — правь сам в спеках и дизайне. -- Развилки (компромисс, scope, инвариант) — вопросом в запись, спеки урезаются на - остаток. -- После правок перепрогони `openspec validate --strict `. - -### 7. Написать код — `opsx:apply` - -Вызови Skill `opsx:apply` для реализации `tasks.md`. Код — по конвенциям проекта -(каталог `docs/conventions/`). Меняешь схему — обнови её описание в -документации тем же change, если проект этого требует: гейт обычно это проверяет. - -Прогони гейт и добейся зелёного — он же гейт следующего шага. - -**Поведенческая верификация.** Если задача меняет реальное поведение (новый -эндпоинт, разбор входа, схема, форма ответа) — зелёных юнит-тестов мало. Подними -изменение вживую командой из раздела команд `CLAUDE.md` и прогони сценарий. -Пропусти только для чисто внутренних правок без наблюдаемого рантайма. - -**Сервис не оставляем лежать.** Если запуск упал — почини или откати до конца -шага. - -### 8. Ревью кода — Skill `av-dev-pipeline:review-pipeline` - -Второй чекпоинт. Вызови Skill **`av-dev-pipeline:review-pipeline`**, дав ссылку -на change ``, базу диффа, **план разметки с шага 4** и режим запуска. - -**Метка ты не выбираешь, и это правило, а не упрощение.** Её назвал -`review-scope` ещё на шаге 4 — по размеру и сложности, с обоснованием по каждой -оси. Причина в разведённости: ты только что написал этот код, и решать, насколько -глубоко его проверять, тебе нельзя — под давлением «я почти закончил» решение -известно заранее. Правило выбора живёт в скилле конвейера — -`av-dev-pipeline:review-pipeline`, `references/review-levels.md`; проектные -триггеры — в `docs/review.*`, подраздел «Триггеры метки». - -**Метка не пересматривается по факту диффа.** Дифф может выйти крупнее, чем -ожидалось при разметке, — это не повод её поднимать: пересмотр означал бы второй -запуск разметчика, ровно то, ради устранения чего он и переехал на шаг 4. - -**Считаешь метку заниженной — скажи это в докладе строкой, а не переспорь.** -Разметчик вправе и поднять, и понизить; твоё несогласие это факт для человека, а -не команда конвейеру. Место, где такое несогласие превращается в изменение -правил, — журнал дефектов `docs/review.md`, и только постфактум. - -**Плана нет — ревью кода не запускается.** Триаж требует план обязательным -входом: без него он не может сверить, все ли размеченные темы вернули отчёт, а -эта сверка — единственная защита от молчащего пропуска. Потерял план (прервалась -сессия, ушёл контекст) — повтори шаг 4, а не гони прогон без него. - -**Режим по умолчанию — `по графу`, и обосновывать его не надо.** Конвейер сам -знает свои рёбра: гейт открывает опиниативные проходы, проходы с пометкой «держит -машину» идут цепочкой (иначе замеры портят друг друга и находка выглядит -доказанной), триаж — сток. Твоего участия это не требует. - -Просить **`линейно`** нужно только по причине, и она называется строкой: так -сказал оператор; машина занята чем-то ещё (в том числе соседней задачей батча); -идёт разбор самого конвейера. - -Скилл сам гоняет гейт, нужные проходы и обязательный триаж. Возвращает отчёт с -потолком 7 пунктов, разметкой `Действие: инлайн | развилка` и секцией границ -покрытия. - -**Сверь план прогона с исходом, прежде чем коммитить.** Отчёт начинается планом -разметчика — таблицей «тема → дом → глубина → кто закрывает», — и против каждой -темы обязан стоять исход. Тема без отчёта и тема без дома — разные вещи, и обе -должны быть названы. Реестр короткий (шесть тем ядра плюс свои) — сверка стоит -одного взгляда. Почему это правило существует, объясняет раздел «Метки» скилла -конвейера; здесь — само требование. - -Отработай так же, как шаг 6: помеченное `инлайн` чини сам и не логируй, -`развилка` — вопросом в запись (он уже сформулирован триажем, его остаётся -перенести). После правок — снова гейт. - -**Урожай — списком, не задачами.** Отложенные находки (реальный `major` не для -этого мерджа, развилка, решённая «потом», пачка `nit`) собери в секцию доклада -`Урожай`: формулировка, оракул, провенанс. Задачи из него **заводит не пайплайн** -— у того, кто ведёт задачи проекта, своя нарезка, свой формат и свои правила -дублей. Твоя обязанность — не потерять и передать. - -**Границы покрытия из отчёта не выбрасывай** — они уезжают в финальный доклад -сжатой строкой. Отчёт, из которого исчезло «что проверить было невозможно», -превращается в ложное ощущение проверенности. - -**Отчёт триажа сохрани вместе с change (`openspec/changes//review/`; шаг 9 -унесёт его в `openspec/changes/archive//review/` вместе с change) — это -обязательно, а не «если удобно».** По нему потом видно, что было найдено и что из -этого осталось в урожае. И это единственный **независимый** артефакт о составе -прогона: под оркестратором `task-batch` именно по нему сверяют полноту ревью -ветки, а не по твоей прозе — она написана тем же, кто мог проход и пропустить. - -### 9. Архивировать — `opsx:archive` - -Вызови Skill `opsx:archive`: change уезжает в архив, дельты вливаются в -актуальные спеки. - -### 10. Синк документации - -Ревью выполненного — до этого шага. Затем **вызови Skill `av-dev-docs:docs`**: он -владеет содержимым документов канона и ведёт чек-лист синка. Плагина нет — шаг -всё равно делается, см. ниже. - -**Правило одно и оно жёсткое: принуждённое отрицание.** Доклад обязан назвать -**каждый** документ канона — либо чем он обновлён, либо «не требуется, потому -что…». Нетронутые группируются одной строкой с общей причиной. Список триггеров -прозой уже проверен на живом проекте и дал 6 записей ADR на 43 изменения; -работает только обязательное отрицание. - -**Список документов и их триггеров здесь не дублируется** — он в чек-листе -скилла `av-dev-docs:docs`, и копия уже однажды разошлась с оригиналом, потеряв два -триггера. - -**Плагина `av-dev-docs` в проекте нет** — путь в его дерево не разрешится ниоткуда, -поэтому за списком иди в **свой** reference: -[references/project-facts.md](../review-pipeline/references/project-facts.md) -конвейера ревью перечисляет все документы канона с их предметом. Пройди по этому -перечню — каждый документ получает строку, отрицание остаётся обязательным. -Триггеры при этом ты знаешь хуже, и это называется в докладе строкой: «синк -сделан по перечню документов, без списка триггеров — плагина `av-dev-docs` нет». -Канона в проекте тоже нет — назови это исходом и предложи `av-dev-docs:canon`. - -### 11. Коммит - -Коммить **в текущую ветку** (`git rev-parse --abbrev-ref HEAD`), сам ветку не -создавай и не переключай, ничего не пушь. При ручном запуске HEAD обычно на -основной ветке — коммит идёт прямо в неё; под оркестратором `task-batch` HEAD на -ветке задачи в изолированном worktree, и делать дополнительно ничего не нужно. - -Сообщение — по-русски, скиллом `av-dev-git:commit`, если он подключён (первая строка «что -сделано», тело списком 1–3 пункта, без трейлеров). Одна задача — один осмысленный -коммит. - -### 12. Закрыть задачу — **после коммита, не раньше** - -**Вызови Skill `av-dev-tasks:tasks`** и попроси закрыть задачу как реализованную — -он владеет форматом и двигает строку из набора спринта сам. Путь к его скрипту не -выясняй и индексы руками не правь: мост между плагинами — вызов скилла, а не -путь. - -**Порядок обязателен.** Закрытие удаляет файл задачи; сделанное до коммита оно -оставило бы задачу закрытой без единого следа работы, если шаг 11 упадёт. - -**Закрытие тоже коммитится — вторым коммитом, тут же.** Удаление файла задачи и -правка индексов (их имена знает `av-dev-tasks`, не ты) — это правки в рабочем -дереве, и оставить их незакоммиченными нельзя по трём причинам: `task-batch` следом делает `rebase` -и `worktree remove`, а те откажут на грязном дереве; закрытие, не доехавшее до -основной ветки, оставит задачу открытой молча; и опора «набор спринта под git -показывает, что и когда закрыто» без коммита — пустые слова. Сообщение короткое, -про учёт, а не про работу: `закрыта задача `. Это второй коммит осознанно: -правило «одна задача — один осмысленный коммит» про работу, а учёт — не работа. - -Плагина в проекте нет — вызов не разрешится. Тогда **ничего не выдумывай**: -скажи в докладе, что учёт задач остаётся за владельцем, и назови исход. - -**Приёмщик и исполнитель здесь совпадают**, и закрытие не окончательно: человек -на сессии может вернуть задачу (`reopen` с причиной). Поэтому доклад по критериям -приёмки — не формальность, а единственное, по чему приёмка вообще возможна. - -Готово — доложи кратко. - -- **исход** задачи одним из трёх слов и, если не «сделана», чем ограничен - результат; -- что сделано, какие вопросы записаны и куда; -- ссылка на архивный change и хеш коммита; -- по каждому критерию приёмки, если они были: **оракул и наблюдаемый исход** — - это доклад приёмщику, а не отметка «принято»; -- **`Урожай`** — отложенные находки списком (формулировка, оракул, провенанс). - Задачи из него заводит тот, кто ведёт задачи проекта; -- **одна строка границ покрытия**: какая метка и режим гонялись, какие проходы - не запускались и что проверить было невозможно. Доклад без неё сообщает - «проверено», не сообщая, что именно. - -## Тонкости - -- **Не завязывайся на основную ветку и корень репозитория.** Скилл работает в - текущем worktree и на текущей ветке: не делай `git checkout`/`switch`, не - создавай веток, не пушь. -- Не пропускай `openspec validate --strict` перед архивацией. -- Тривиальная задача: пропускается только шаг 2. Обе стадии ревью остаются, но - с меткой `small` — один проход на дизайне и четыре на коде, а при своих темах - проекта пять: приёмник тем запускается, если ему есть что принимать. -- Гейт блокирует: пока он красный, опиниативные проходы не запускаются. Чинить и - перезапускать, а не «посмотреть заодно». -- Если ревью предлагает крупную переработку — это развилка: не правь молча и не - спрашивай, запиши вопросом и доведи остаток. -- Держи вызывающего в цикле короткими репликами на переходах фаз, но не проси - подтверждать механику. -- **Занизить метка ревью или пропустить тему — самый дешёвый способ - «ускориться», и он же самый дорогой по последствиям.** Защита устроена так, - что регулятора у тебя нет: метку выбирает разметчик **до того**, как ты - написал код, план сверяется по темам, непокрытое называется в отчёте строкой.