классификация задачи: три категории документов и метка вместо ступени

Канон 5 объявил «каждый документ docs/ — тема ревью». Правило верно ровно
наполовину и потому вредно целиком. Паспорт и схему хранилища ревью читает, но
темами они не являются: по ним нельзя сказать «в этом изменении сделано не так»,
они задают границу, по которой судит чужая тема. Журнал решений и журнал
наблюдений ревью изменения не нужны вовсе — ADR объясняет прошлое, а не
предъявляет требование. Разметчик, применявший правило буквально, обязан был
либо завести фантомные темы passport, adr, database, research и продублировать
ими работу architecture и operations, либо потерять четыре документа молча;
случались обе ветки, и в собственном образце плана docs/passport.md не попадал
ни строкой, а обязательная арифметика покрытия при этом не сходилась.

Категорий теперь три, разрез проверяемый. Тема — да, прямо: conventions,
security, architecture и любой свой документ проекта. Источник темы — нет, но он
задаёт границу для чужой: passport, database, CLAUDE.md, openspec/specs.
Процессный — нет, он про то, как мы работаем: tasks, review, adr, research,
.pm.json. Открыта одна категория из трёх, две другие перечислены поимённо, так
что документ вне раскладки — однозначно своя тема. adr и research прогон больше
не открывает ни одним проходом; docs/review остаётся читаемым, но как настройка
конвейера, а не критерий. Цена записана и стала обязательной строкой границ
покрытия: расхождение с записанным решением ловит теперь только сверка
документации, а число под находкой обязано быть снято на этом прогоне, с
приложенной командой.

Классификация выдаёт задаче метку — small, medium, large. Прежние quick,
standard и wide назывались ступенью и описывали ревью: как глубоко смотрим.
Классифицируется же задача, и пока величина называлась свойством прогона, её
естественно было пересчитывать на каждом прогоне — что конвейер и делал. Слово
«ступень» удалено, а не оставлено синонимом: два имени одной вещи расходятся.
Выводится метка из двух разведённых осей — размер (малое, среднее, крупное) и
сложность (знакомое, незнакомое), — и равна максимуму по ним. Метка не синоним
размера: малое незнакомое изменение получает large, трогая один узел, поэтому
план печатает три строки с обоснованием каждая и выводить одну из другой
запрещено. Оси остались русскими словами — это суждение прозой; метка
английская — это идентификатор, который проходы сравнивают.

Разметка переехала из ревью кода в шаг 4 пайплайна, сразу после propose. Она
шла первым проходом каждого ревью кода, а перед ревью дизайна ту же величину
называл сам пайплайн — то есть оркестратор, который только что довёл
предложение до propose. Одно и то же измерялось дважды, и один из двух раз без
разведённости с автором, ровно в той точке, ради которой разметчик заведён.
Теперь запуск один на задачу, диффа он не видит, план обслуживает обе стадии, и
метка после кода не пересматривается: расхождение факта с разметкой ловит журнал
дефектов постфактум, как и всякую другую ошибку выбора. На диск план не пишется —
четвёртый артефакт рядом с proposal, tasks и design пережил бы задачу и разошёлся
бы с ней молча.

Ревью дизайна тоже растёт меткой: small — specs, medium — плюс rubric, large —
плюс architecture и вопрос автору о трёх формах решения. Раньше rubric и
architecture включались одним условием, и medium получал ровно один проход, то
есть не отличался от quick ничем. Разведены они потому, что зарабатывают на
разном: рубрика порождает свойства узла и окупается уже на среднем изменении,
её выход уезжает приёмочными критериями в tasks.md; архитектура отвечает на
вопрос про второй способ, а он на среднем знакомом изменении отвечается «нет»
ещё до запуска.

small подешевел тремя способами сразу. Составом: приёмник тем не запускается,
три темы ядра переходят к code сверкой по записанным инвариантам CLAUDE.md с
потолком в одну находку, и это не «глубина ниже», а другой дом темы. Входом:
specs читает только дельта-спеку, code — только индекс конвенций. Потолком: он
появился у каждого опиниативного прохода, а не у одного basics, и у половин code
он раздельный, потому что конвенционных находок больше по построению и в общем
списке они вытеснили бы техническую половину. Сработавший потолок обязан быть
объявлен строкой — молчащий срез неотличим от «больше не нашлось». Отрицательный
тест small от этого стал жёстче, а не мягче: вопросы про обратимость миграции
задавал приёмник тем, и на этой метке их не задаст никто.

Пайплайн задачи вырос до двенадцати шагов. Тривиальность перестала решать состав
ревью — она влияет только на explore; глубину обеих стадий называет метка.

Проверено прогоном ревьюверов по готовому результату: девять расхождений найдено
и починено — контракт находок печатал старый перечень проходов вместо плана по
темам, три ссылки в task-batch указывали на шаг коммита вместо закрытия, запись
changelog не переводила вопросы, адресованные passport и database, ops и
adversary утверждали, что на нижних метках их вопросы задаёт basics, шаблон
покрытия в review-code зашивал потолки small намертво, триггеры метки рассыпались
на два списка против трёх, тема из директивы CLAUDE.md могла остаться без запуска
исполнителя. Гейт зелёный: фронтматтеры, копии, одиннадцать диаграмм, ruff,
pyrefly; docs.py прогнан на живом фикстуре и печатает категорию в отказе.

Канон повышен до версии 6 с записью, выполнимой upgrade. Решения — 40–44.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
av
2026-08-07 10:57:15 +03:00
co-authored by Claude Opus 5
parent 61cd9fcd37
commit d5bee11a6b
31 changed files with 1809 additions and 689 deletions
File diff suppressed because it is too large Load Diff
@@ -27,7 +27,7 @@
```mermaid
stateDiagram-v2
state "проход в профиле" as live
state "проход в составе метки" as live
state "retune №1 — правка charter'а" as r1
state "retune №2 — последняя попытка" as r2
state "проход удалён" as dead
@@ -101,7 +101,7 @@ stateDiagram-v2
## Когда калибровать
- при заведении нового прохода — **до** включения в профиль по умолчанию;
- при заведении нового прохода — **до** включения в состав метки по умолчанию;
- при правке charter'а существующего — иначе непонятно, правка помогла или нет;
- при появлении записи в журнале проскочивших дефектов — калибруем тот проход,
который должен был поймать;
@@ -13,7 +13,7 @@
- Оракул: <падающий тест / команда с выводом / положение руководства / нет>
- Последствие: <что произойдёт и при каких условиях>
- Предложение: <конкретное изменение>
- Найдено проходом: <имя агента>
- Найдено проходом: <имя агента; у проходов с раздельными потолками — имя и половина, например `code/техника`>
```
## Правила
@@ -76,10 +76,16 @@
4. `Promote candidates` — кандидаты в конвенцию или правило линтера;
5. `Границы покрытия` — сводная, обязательная.
Перед секциями — сводка для человека: профиль и режим прогона, состояние гейта,
**перечень запущенных проходов поимённо с исходом каждого**, сколько находок
пришло на вход и сколько осталось. Перечень обязателен: пропуск прохода не
отличим от прохода без находок, и назвать его больше некому.
Перед секциями — сводка для человека: размер, сложность, метка и режим
прогона, состояние гейта, **план разметки задачи с исходом по каждой теме**,
сколько находок пришло на вход и сколько осталось.
**Реестр сводки — темы, а не проходы, и это не оформление.** Перечень запущенных
проходов отвечает «все, кто должен был, отработали» и молчит о том, что именно
осталось непроверенным: уехавший в старшую метку проход уносит тему с собой
беззвучно. План же называет тему, её дом, глубину и исполнителя — и тема,
оставшаяся без отчёта, видна сразу. Перечень проходов из сводки не исчезает, но
идёт **внутри** плана, колонкой «кто закрывает».
Каждая находка в секциях 1–2 несёт дополнительное поле:
@@ -15,7 +15,7 @@
## Карта тем
**Дом бывает файлом или каталогом**`docs/security.md` и `docs/security/`
называют одну и ту же тему. Форму дома называет план разметчика; проход её не
называют одну и ту же тему. Форму дома называет план разметки задачи; проход её не
угадывает.
| Тема | Дом | Что оттуда берётся |
@@ -24,13 +24,21 @@
| `autotests` | `CLAUDE.md`, семантика гейта | команда гейта, чем краснеет безусловно, чего в нём нет, кто гоняет дорогое |
| `conventions` | `docs/conventions.*` | конвенции прозой и **что уже механизировано** правилом |
| `architecture` | `docs/architecture.*` | компоненты и capability, единые точки проекта |
| | `docs/passport.*` | что система делает и **чего не делает**, граница домена |
| | `docs/adr/` | почему решено так, отвергнутые варианты |
| | источник `docs/passport.*` | что система делает и **чего не делает**, граница домена |
| `security` | `docs/security.*` | периметр, недоверенный вход, из чего строятся пути и ключи, что вне модели |
| `operations` | `docs/architecture.*`, раздел эксплуатации | окружение, внешние зависимости поимённо, наблюдатель, характер потока |
| | `docs/database.*` | чем физически лежит запись, что при чтении и записи, настройки с числовым значением |
| | `docs/research/` | измеренные числа **с провенансом**, поведение внешних систем на самом деле |
| *тема проекта* | её документ в `docs/` | то, что проект счёл нужным записать |
| | источник `docs/database.*` | чем физически лежит запись, что при чтении и записи, настройки с числовым значением |
| *тема проекта* | её **свой** документ в `docs/` | то, что проект счёл нужным записать |
**`docs/adr.*` и `docs/research.*` в этой карте нет намеренно.** Они процессные
документы: прогон ревью их не открывает. Раньше первый питал тему `architecture`,
второй — `operations` и `requirements`; обе строки убраны, и цена этого названа в
`SKILL.md`, раздел «Честный предел».
**Дом темы зависит ещё и от метки.** На `small` темы `security`, `operations` и
`architecture` смотрятся не против домов из этой таблицы, а против **инвариантов
`CLAUDE.md`**, и закрывает их `code`. Таблица описывает полный дом темы; сколько
из него открыто на этом прогоне, говорит план разметки задачи.
Сквозное, не привязанное к теме:
@@ -38,12 +46,12 @@
| --- | --- |
| инварианты **с severity рядом с формулировкой** | `CLAUDE.md``AGENTS.md`, если он рядом), раздел инвариантов |
| что запускать запрещено, с путями; `testdata`; куда писать временное; имя основной ветки | `CLAUDE.md` |
| типовые узлы, типовые ложноположительные, **вопросы по темам**, триггеры профиля, недоступно проверке | `docs/review.*`, раздел настройки |
| типовые узлы, типовые ложноположительные, **вопросы по темам**, триггеры метки, недоступно проверке | `docs/review.*`, раздел настройки |
| прецеденты: воспроизведённые дефекты с оракулом | `docs/review.*`, журнал |
**Вопросы проекта привязаны к теме, а не к имени прохода.** Раньше блок в
`docs/review.md` адресовался поимённо (`ops: <вопрос>`), и когда проход уехал в
верхнюю ступень, вопрос перестал задаваться молча. Тема переезд прохода
старшую метку, вопрос перестал задаваться молча. Тема переезд прохода
переживает.
## Сшивать обязаны проходы
@@ -57,8 +65,10 @@
- **замер + настройка.** «Пик 768 МиБ» — аномалия только рядом со строкой
«запись лежит сжатой и распаковывается целиком»; «блокировка удерживалась
5.019 с» — гарантированный отказ соседа только рядом с известным таймаутом
занятости. Числа в `docs/research/`, настройки в `docs/database.md`, и оба
читает `ops` и `adversary`.
занятости. **Число проход снимает сам, на этом прогоне**, настройки берёт из
`docs/database.md`, и сшивают их `ops` и `adversary`. Раньше числа брались из
`docs/research/`; теперь этот документ процессный, и замер неизвестной свежести
больше не выдаёт себя за оракул.
- **инвариант + обратимость.** severity берётся из `CLAUDE.md`; если её там
нет — она **выводится по обратимости последствия** и помечается «выведена по
обратимости», а не выдаётся за решение проекта.
@@ -67,7 +77,9 @@
с настройкой ему нечего; единственное его основание для `critical` — инвариант из
`CLAUDE.md`, всё остальное он формулирует условиями и оставляет гипотезой. Его
вход намеренно узкий: дома тем из плана плюс инварианты и журнал. Широкий вход —
это профиль `wide`, и там он есть у `architecture`.
это метка `large`, и там он есть у `architecture`. Греп по базе ему разрешён
точечный — «есть ли второй вызывающий», — но обход всей базы и инвентарь
концепций не его работа.
**У `scope` стыков нет по другой причине: он не читает содержимого.** Его дело —
найти дома и раздать темы, а не пересказать написанное. Пересказ сделал бы его
@@ -83,7 +95,7 @@
**Кто какой документ читает — из документа не выводится, а назначается планом.**
Документ питает тему (это записано на стороне канона, таблица «Роли документов и
темы ревью»), а тему на этом прогоне закрывает тот, кого назвал разметчик; вся
темы ревью»), а тему на этом прогоне закрывает тот, кого назвала разметка задачи; вся
раскладка «тема → проход → глубина» — в `SKILL.md` этого скилла и больше нигде.
**Списка читателей не ведёт никто, и это не пробел.** Он жил бы на стороне
канона, а документ живёт дольше, чем раскладка проходов: список разошёлся бы с
@@ -96,10 +108,8 @@
| --- | --- |
| `CLAUDE.md` без инвариантов | `critical` по основанию «нарушен инвариант проекта» не присваивается никем |
| `docs/security.*` | тема `security` остаётся без дома: вопросы задаются по коду, `critical` не ставится, периметр неизвестен |
| `docs/research/` | числа неизвестны темам `operations` и `requirements` — формулируют условиями, а `specs` теряет проверку «требование против наблюдения» |
| `docs/database.*` | замер не с чем сравнить: находка темы `operations` не поднимается выше гипотезы |
| `docs/passport.*` | тема `architecture` теряет границу домена и вырождается в общее мнение |
| `docs/adr/` | «не отменяет ли изменение записанное решение» не спрашивает никто |
| `docs/review.*` | `triage` отсеивает вслепую: типовых ложноположительных нет; вопросы проекта по темам не задаются |
| `docs/conventions.*` | вторая половина `code` идёт вхолостую: записанных конвенций нет |
| `docs/architecture.*` | «не появился ли второй способ» не проверяется — единых точек не знает никто; тема `operations` теряет перечень внешних зависимостей |
@@ -6,7 +6,7 @@
и один и тот же класс проскакивает второй раз.
Тот же файл держит **настройку конвейера под проект** — типовые узлы, типовые
ложноположительные, вопросы к проходам, недоступно проверке. Это не соседство по
ложноположительные, вопросы по темам, недоступно проверке. Это не соседство по
случаю: все четыре раздела — производные калибровки, а журнал им источник.
## Что туда попадает
@@ -29,7 +29,7 @@
и `docs/adr/`.
Отдельно сюда попадают **решения о составе прогонов**: перестали звать проход,
понизили профиль правилом, сузили класс проверяемого. Не потому, что это промах,
понизили метку правилом, сузили класс проверяемого. Не потому, что это промах,
а потому, что здесь лежит цена: если что-то теперь проскочит, первый вопрос —
«не тот ли это класс, который мы перестали проверять».
@@ -77,13 +77,13 @@
Три адреса, и выбор между ними — половина ценности журнала:
- **в документ проекта** — если проход не мог знать факта. Адрес зависит от рода
факта, и карта их всех — [project-facts.md](project-facts.md): объём и
измеренное число → `docs/research/`; настройка хранилища → `docs/database.md`;
факта, и карта их всех — [project-facts.md](project-facts.md):
настройка хранилища → `docs/database.md`;
что необратимо и какой шаг гейта красит безусловно → `CLAUDE.md`; периметр и
недоверенный вход → `docs/security.*`. **Вопрос по теме**, если промах лечится
не фактом, а заданным вопросом, → раздел «Вопросы по темам» того же
`docs/review.*`; адресуй теме, а не имени прохода — проход уедет между
ступенями, тема останется. Самый частый адрес и самый дешёвый. Прежде чем
метками, тема останется. Самый частый адрес и самый дешёвый. Прежде чем
править charter, проверь, не хватит ли факта или вопроса: charter общий для
всех проектов, документ — про этот.
- **в конвенции или в правило линтера** — если свойство выражается
+46 -21
View File
@@ -51,7 +51,7 @@ description: Проводит несколько задач разом — пл
- **Батч не владеет спринтом и целями.** Он сообщает исход по каждой задаче в тех
же трёх словах, что и `task-pipeline`: сделана / не доведена / оказалась крупнее
задачи.
- **Задачи закрывает пайплайн внутри каждого сабагента**, шагом 11 — после
- **Задачи закрывает пайплайн внутри каждого сабагента**, шагом 12 — после
коммита работы и **отдельным коммитом учёта**, вызовом Skill `av-dev-pm:tasks`.
Батч сам записей учёта не трогает: он не знает, чем кончилась приёмка, и
дублировать закрытие ему незачем. Но грязное дерево после сабагента — **его**
@@ -104,21 +104,20 @@ description: Проводит несколько задач разом — пл
параллельном она гонится в волне **одна** (обоснование — ниже, в шаге 4).
Помечается здесь, на планировании, а не во время прогона, и **независимо от
режима**: состав волны определяется сейчас, режим может смениться просьбой уже
после плана, а ступень ревью выберет разметчик уже внутри прогона — ключевать
волну на ещё не сделанный выбор нельзя. Триггеры — по фактам о задаче, каждый
после плана, а метка ревью назовёт разметчик уже внутри пайплайна задачи,
после `propose`, — ключевать волну на ещё не сделанный выбор нельзя. Триггеры — по фактам о задаче, каждый
сам по себе достаточен:
- трогает схему хранилища, миграцию, формат на диске или объём хранимого;
- трогает конкурентность: транзакции, блокировки, фоновые циклы, общее
состояние;
- трогает размер тела, буфер, память, сжатие, ретеншен, темп потока;
- её тема названа в `docs/research/` или в журнале `docs/review.md` как место,
где уже мерили или уже ломалось.
- её тема названа в журнале `docs/review.md` как место, где уже ломалось.
Ни один триггер не сработал — задача не замеряющая, даже если её ревью
окажется `wide`. Ступень про глубину проверки, замеряющая — про соревнование за
окажется `large`. Метка про глубину проверки, замеряющая — про соревнование за
железо; это разные вопросы, и совпадают они не всегда. Обратное тоже бывает и
тоже законно: помеченная задача, чьё ревью пошло профилем `quick` или
`standard`, машину не займёт вовсе — меряющие проходы живут только в `wide`.
тоже законно: помеченная задача, чьё ревью пошло меткой `small` или
`medium`, машину не займёт вовсе — меряющие проходы живут только в `large`.
Пометка от этого не снимается: она ставится **до** разметки, и перестраховка
здесь стоит одной волны, а ошибка — испорченных чисел;
- **нумерованные артефакты — номера раздаёт оркестратор заранее.** Если проект
@@ -238,8 +237,10 @@ flowchart TD
- прогони Skill **`av-dev-pipeline:task-pipeline`** ровно на этой задаче,
полный цикл SDD с обоими чекпоинтами ревью;
- если задаче назначен **номер артефакта** — используй строго его;
- **ступень ревью выбирает разметчик конвейера, а не ты и не сабагент.**
Профиль в вызов не передаётся вовсе. Батч не повод её понижать: «нас много и
- **метка ревью выбирает разметчик конвейера, а не ты и не сабагент.** Он
идёт внутри пайплайна задачи, шагом 4, сразу после `propose`, и его план
обслуживает оба чекпоинта. Метка в вызов не передаётся вовсе. Батч не
повод её понижать: «нас много и
мы спешим» — ровно тот стимул, из-за которого проходы пропускают, и он снят
тем, что регулятор не в руках у автора;
- **режим прогона проходов ревью — от режима батча**, и его называет charter,
@@ -249,15 +250,15 @@ flowchart TD
Внутренние рёбра графа — цепочку проходов, держащих машину — конвейер
соблюдает сам, в любом режиме;
- **если вложенные сабагенты недоступны** (движок не даёт запускать агентов из
агента) — не пропускай ревью и не понижай ступень: проведи его **инлайн** по
агента) — не пропускай ревью и не понижай метка: проведи его **инлайн** по
тем же charter'ам `av-dev-pipeline`, сохранив обязательное — разметку первой
(план с темами и ступенью), гейт до опиниативных проходов, состав по плану,
(план с темами и меткой), гейт до опиниативных проходов, состав по плану,
триаж последним. И **скажи в отчёте прямым текстом, что ревью шло инлайн**:
инлайновый проход видит контекст автора и потому разведён с ним слабее — а
инлайновая разметка вдобавок означает, что ступень выбрал автор, и это
инлайновая разметка вдобавок означает, что метка выбрал автор, и это
отдельная строка;
- **вернуть отчёт**, в котором обязательно: исход задачи одним из трёх слов;
**план прогона: ступень с обоснованием, темы и их глубины**, и режим; что сделано; какие вопросы
**план прогона: метка с обоснованием, темы и их глубины**, и режим; что сделано; какие вопросы
записаны и куда; изменённые файлы; добавлялся ли нумерованный артефакт и с
каким номером; затронутые capability; состояние гейта; **перечень
тем с исходом по каждой**; **путь к
@@ -284,9 +285,9 @@ flowchart TD
Сверка идёт в три шага, и порядок важен:
1. **Возьми план прогона** из отчёта задачи — таблицу «тема → дом → глубина → кто
закрывает» со ступенью и обоснованием; он затем и заказан в обязательных полях
закрывает» с меткой и обоснованием; он затем и заказан в обязательных полях
шага 4. Плана в отчёте нет — сверять не с чем; это само по себе основание не
вливать, пока сабагент не покажет план разметчика.
вливать, пока сабагент не покажет план разметки задачи.
2. **Сверяй с независимым артефактом, а не с прозой отчёта.** Перечень проходов
бери из **сохранённого отчёта триажа** (`openspec/changes/<id>/review/` или
`openspec/changes/archive/<id>/review/` — задача доведена, change заархивирован) —
@@ -294,13 +295,18 @@ flowchart TD
проход и пропустить: она подтверждает сама себя. Отчёта триажа на месте нет —
считай, что состав неизвестен, и дозапускай ревью целиком.
3. **Сверь план с исходом**: против каждой темы плана обязан стоять отчёт либо
названная причина его отсутствия. Раскладка «тема → кто закрывает на этой
ступени» — в скилле `av-dev-pipeline:review-pipeline`.
названная причина его отсутствия. Раскладка «тема → кто закрывает с этой меткой» — в скилле `av-dev-pipeline:review-pipeline`.
Расхождение — не повод отменять задачу: дозапусти недостающие проходы **на
ветке**, в её worktree, через `av-dev-pipeline:review-pipeline`, и только потом
интегрируй.
**Передай в дозапуск тот же план.** Триаж требует его обязательным входом — без
плана он не может сверить, все ли размеченные темы вернули отчёт, а эта сверка и
есть то, ради чего дозапуск затевается. Плана не осталось (сабагент не сохранил
его в отчёте) — пусть повторит разметку задачи: это самый дешёвый проход
конвейера, и он дешевле, чем прогон, который нечем сверить.
**Находки дозапуска — такие же находки, и зелёный гейт их не отменяет.** Правило
интеграции «вливаем только зелёные» смотрит на гейт, а дозапущенный `critical`
гейт не красит: он был бы пропущен молча, если это не сказать прямо. Поэтому:
@@ -337,7 +343,7 @@ rebase делается **внутри worktree задачи**, а ff-слиян
(`git -C <path> rebase --abort`), оставь ветку и worktree как есть, вынеси это
в доклад как нераспознанное пересечение;
- **дерево сабагента обязано быть чистым.** `git -C <path> status --porcelain`
до `rebase`: непусто — значит сабагент не довёл шаг 11 до коммита учёта (или
до `rebase`: непусто — значит сабагент не довёл шаг 12 до коммита учёта (или
оставил мусор). Не форсируй и не коммить за него: назови задачу в докладе
недоведённой и оставь ветку с worktree. Молчаливый `rebase` на грязном дереве
всё равно откажет, но с сообщением про unstaged changes — а причина другая;
@@ -395,7 +401,26 @@ rebase в файле X», а не «нераспознанное пересеч
- **заверши триажем.** Он единственный, кто агрегирует, и без него у находок нет
ни оракула, ни пометки `инлайн`/`развилка` — а следующий абзац на неё
опирается. Прогон из двух проходов без триажа — это сырые находки, выданные за
разобранные.
разобранные;
- **план триажу собери сам, здесь, — разметчика на этой сверке нет.** Триаж
требует план обязательным входом: он сверяет размеченное с пришедшим, и без
плана эта сверка не выполняется вовсе. Разметка задачи сюда не годится — она
описывала одну задачу, а сверка идёт по интегрированной ветке. План здесь
короткий и составляется по факту запуска:
```
метка: не применяется — сверка стыка, а не ревью изменения
тема дом глубина закрывает
requirements openspec/specs/<capability-1>/ разбор specs (стык)
requirements openspec/specs/<capability-2>/ разбор specs (стык)
architecture docs/architecture.md разбор architecture
+ источник docs/passport.md
```
Темы, которых в этом списке нет (`autotests`, `conventions`, `security`,
`operations`, свои темы проекта), назови строкой «не проверяется на сверке
стыка: закрыто прогонами отдельных задач». Это не формальность — без такой
строки отчёт сверки читается как полное ревью ветки.
Граф этой сверки — веер в один сток, и он такой же, как у обычного прогона:
@@ -421,7 +446,7 @@ flowchart TD
`git worktree prune`. Worktree и ветки **провалившихся** не трогай — они нужны
для ручного дожатия.
- **Записей учёта батч не трогает** — их правит пайплайн внутри сабагента на
шаге 11. Батч сообщает исход по каждой задаче; если какой-то сабагент дошёл до
шаге 12. Батч сообщает исход по каждой задаче; если какой-то сабагент дошёл до
коммита, но закрытия не сделал (плагина нет, вызов не разрешился), скажи это
строкой — иначе задача останется открытой молча.
- Доложи кратко:
+119 -56
View File
@@ -1,6 +1,6 @@
---
name: task-pipeline
description: Автономно проводит одну задачу через полный цикл Spec Driven Development — от постановки до коммита (opsx explore→propose→ревью спек профилем design→apply→ревью кода→archive→коммит), с обязательными чекпоинтами ревью и докладом об исходе. Использовать, когда просят взять/сделать задачу или довести идею до реализации.
description: "Автономно проводит одну задачу через полный цикл Spec Driven Development — от постановки до коммита (opsx explore→propose→разметка задачи→ревью дизайна→apply→ревью кода→archive→коммит), с обязательными чекпоинтами ревью и докладом об исходе. Разметка идёт один раз, сразу после propose: она называет размер, сложность и метка, и её план определяет состав обеих стадий ревью. Использовать, когда просят взять/сделать задачу или довести идею до реализации."
---
# Пайплайн задачи
@@ -11,12 +11,13 @@ description: Автономно проводит одну задачу чере
Это тонкая обёртка над каноническими скиллами `opsx:explore` / `opsx:propose` /
`opsx:apply` / `opsx:archive` — вызывай их через Skill, не переизобретай их шаги.
Ревью — скилл `av-dev-pipeline:review-pipeline`; он же держит правило выбора
ступени и **сам её выбирает**: ты профиль не передаёшь.
метки, а называет её агент `review-scope` на шаге 4 — один раз на задачу, для
обеих стадий ревью.
## Предпосылки
- **OpenSpec и скиллы `opsx:*` — жёсткая предпосылка, а не опция.** На них стоят
шаги 2, 3, 6 и 8, проход `review-specs` и профиль `design` (они завязаны на
шаги 2, 3, 7 и 9, проход `review-specs` и ревью дизайна (они завязаны на
`openspec/changes/<id>/specs/*/spec.md` и на `openspec validate --strict`).
**Проект без OpenSpec этим пайплайном не ведётся** — подключай OpenSpec, а не
вырождай цикл: ветка деградации здесь не пишется, потому что непроверенная
@@ -47,14 +48,14 @@ description: Автономно проводит одну задачу чере
проекте есть свой процесс управления задачами — он и решает, что брать.
- **Форматом задач.** Пайплайн **не правит индексы руками и не выдумывает путь
к скрипту учёта**: он зовёт Skill `av-dev-pm:tasks`, который этим владеет
(шаг 11). Закрытие как таковое — его работа, и это осознанное решение с
(шаг 12). Закрытие как таковое — его работа, и это осознанное решение с
названной ценой: **приёмщик и исполнитель совпали**. Закрытие поэтому **не
окончательно** — человек на сессии возвращает задачу `reopen` с причиной, а
доклад по критериям приёмки становится единственным, по чему приёмка вообще
возможна. Плагина `av-dev-pm` в проекте нет — вызов не разрешится, и тогда
учёт остаётся владельцу, о чём говорится в докладе.
- **Заведением задач из урожая ревью.** Отложенные находки отдаются **списком**
(см. шаг 7); превращать их в задачи — работа того, кто ведёт задачи проекта.
(см. шаг 8); превращать их в задачи — работа того, кто ведёт задачи проекта.
- **Определением ценности.** «Нужна ли эта функциональность» — не вопрос
пайплайна ни на одном шаге.
@@ -148,7 +149,7 @@ description: Автономно проводит одну задачу чере
## Шаги
Одиннадцать шагов с одной развилкой и одним досрочным исходом:
Двенадцать шагов с одной развилкой и одним досрочным исходом:
```mermaid
flowchart TD
@@ -157,26 +158,34 @@ flowchart TD
big["исход «оказалась крупнее задачи»<br/>объявляется ДО заведения change"]
s2["2. opsx:explore — груминг идеи"]
s3["3. opsx:propose — change, дельта-спеки, tasks.md"]
s4["4. ревью предложения, профиль design"]
s5["5. отработать замечания + validate --strict"]
s6["6. opsx:apply — код, гейт, поведенческая верификация"]
s7["7. ревью кода, ступень выбирает разметчик"]
s8["8. opsx:archive"]
s9["9. синк документации — av-dev-pm:docs"]
s10["10. коммит работы — av-dev-git:commit"]
s11["11. закрыть задачу — av-dev-pm:tasks,<br/>вторым коммитом учёта"]
s4["4. разметка задачи — review-scope:<br/>размер, сложность, метка, план тем"]
s5["5. ревью дизайна, состав по метке"]
s6["6. отработать замечания + validate --strict"]
s7["7. opsx:apply — код, гейт, поведенческая верификация"]
s8["8. ревью кода, состав по той же метки"]
s9["9. opsx:archive"]
s10["10. синк документации — av-dev-pm:docs"]
s11["11. коммит работы — av-dev-git:commit"]
s12["12. закрыть задачу — av-dev-pm:tasks,<br/>вторым коммитом учёта"]
s1 --> triv
s1 -.-> big
triv -->|"нет: идея или мутная постановка"| s2
s2 --> s3
triv -->|"да: шаги 2 и 4 пропускаются"| s3
s3 --> s4 --> s5 --> s6 --> s7 --> s8 --> s9 --> s10 --> s11
triv -->|"да: шаг 2 пропускается"| s3
s3 --> s4 --> s5 --> s6 --> s7 --> s8 --> s9 --> s10 --> s11 --> s12
s4 -.->|"план задачи: та же метка"| s8
```
Два чекпоинта ревью — шаги 4 и 7 — единственные места, где зовётся конвейер;
**Разметка стоит одна и обслуживает обе стадии ревью** — шаги 5 и 8. Это и есть
пунктирное ребро на схеме: план, посчитанный на шаге 4, доезжает до ревью кода
без пересчёта. Раньше разметка была первым проходом внутри шага ревью кода, а
состав ревью дизайна называл сам пайплайн — то есть одна и та же величина
считалась дважды, и один из двух раз тем, кто только что написал предложение.
Два чекпоинта ревью — шаги 5 и 8 — единственные места, где зовётся конвейер;
порядок «сперва коммит работы, потом коммит учёта» на схеме тоже ребро, и оно
обязательное (шаг 11).
обязательное (шаг 12).
Схема — **сводка**: содержание каждого шага в его разделе ниже, и при
расхождении прав текст.
@@ -191,13 +200,20 @@ flowchart TD
уезжают в `tasks.md` change. Файл задачи может быть удалён до коммита, а
критерии обязаны его пережить.
Оцени тривиальность (влияет на шаг 4):
Оцени тривиальность **теперь она влияет ровно на один шаг, второй**:
- **тривиальная** — локальная правка без изменения поведения, спек и схемы,
решение очевидно. Explore и ревью спек пропускаются;
решение очевидно. Explore пропускается;
- **нетривиальная** — новое или изменённое поведение, дизайн-развилки, задеты
инварианты, схема или несколько capability. Полный цикл.
**На состав ревью тривиальность больше не влияет** — это работа шага 4. Раньше
она решала и то, звать ли ревью предложения вовсе; теперь глубину обеих стадий
называет метку, и тривиальная задача просто получает `small`. Разница
существенная: «пропустить ревью дизайна» и «пройти его одним самым дешёвым
проходом» — не одно и то же, а сверка дельта-спек стоит меньше, чем разбор того,
что она поймала бы.
Здесь же — проверка на «крупнее задачи»: если видно, что одним заходом это не
мерджится, объявляй исход **до** заведения change.
@@ -216,31 +232,67 @@ flowchart TD
Критерии приёмки задачи, если они были, копируются в `tasks.md` отдельным блоком.
### 4. (Нетривиальная) Ревью предложения — профиль `design`, ДО кода
### 4. Разметка задачи — агент `review-scope`
Первый чекпоинт. Вызови Skill **`av-dev-pipeline:review-pipeline`** с профилем
`design` и ссылкой на change `<id>`.
**Один запуск на всю задачу, и он обслуживает оба чекпоинта ревью.** Запусти
агента `review-scope`, дав ему корень проекта, идентификатор change, базу диффа и
запись задачи. Кода на этот момент нет, и это условие его работы, а не помеха.
**Состав чекпоинта решает конвейер, а не ты**: `review-specs` в режиме «дизайн ДО
кода» идёт всегда, а `review-rubric` и `review-architecture` — только когда
изменение крупное или незнакомое (то же условие, что у ступени `wide`, и та же
доля — 5–10% задач). Причина в том, что чекпоинт стоит на **каждой** задаче: при
мелкой нарезке три прохода здесь умножаются на число задач и становятся самой
большой статьёй конвейера.
Он возвращает **план задачи**:
Смысл профиля: архитектурная находка на готовом коде стоит переписывания и
- **размер** (малое / среднее / крупное) и **сложность** (знакомое /
незнакомое), каждое с обоснованием по факту;
- **метка** как максимум по двум осям: `small`, `medium` или `large`;
- **состав ревью дизайна** — что звать на шаге 5;
- **таблицу тем** «тема → дом → глубина → кто закрывает» — для шага 8;
- разнесение документов проекта по трём категориям и строку про директивы.
**Метка выбираешь не ты.** Раньше состав ревью дизайна называл этот пайплайн
(«крупное или незнакомое?»), то есть тот же оркестратор, который только что
довёл предложение до `propose`. Разведённости с автором в этой точке не было
вовсе; теперь есть.
**План держи в контексте до конца задачи.** На диск он не пишется: файл-план стал
бы четвёртым артефактом рядом с `proposal.md`, `tasks.md` и `design.md`, пережил
бы задачу и разошёлся бы с ней молча. Прервался пайплайн — повтори шаг 4, это
самый дешёвый его проход.
**Разметка повторяется ровно в одном случае** — если на шаге 6 правки изменили
сами **дельта-спеки**: план выведен из них, и план по отменённым требованиям
назовёт не те темы. Во всех прочих случаях, включая переделку формы кода на шаге
8, метка остаётся прежней.
### 5. Ревью предложения — ДО кода, состав по метке
Первый чекпоинт. Вызови Skill **`av-dev-pipeline:review-pipeline`**, дав ссылку на
change `<id>`, **план разметки с шага 4** и указание, что это ревью дизайна.
Состав приходит планом, а не решается здесь:
| Метка | Проходы на предложении |
|---|---|
| `small` | `specs` |
| `medium` | `specs`, `rubric` |
| `large` | `specs`, `rubric`, `architecture` + вопрос автору о трёх формах решения |
`review-specs` в режиме «дизайн ДО кода» идёт **на каждой задаче**: это самый
дешёвый чекпоинт конвейера, и он ловит то, что на готовом коде уже не чинят.
Остальные включаются меткой, потому что чекпоинт стоит на каждой задаче и
каждый лишний проход здесь умножается на число задач.
Смысл стадии: архитектурная находка на готовом коде стоит переписывания и
потому игнорируется — та же находка здесь стоит абзаца обсуждения. Если
`review-rubric` запускался, перенеси его рубрику в `tasks.md` как приёмочные
критерии; там же уже лежат критерии от постановки, если они были.
### 5. Отработать замечания ревью предложения
### 6. Отработать замечания ревью предложения
- Мелочь и явные улучшения — правь сам в спеках и дизайне.
- Развилки (компромисс, scope, инвариант) — вопросом в запись, спеки урезаются на
остаток.
- После правок перепрогони `openspec validate --strict <id>`.
### 6. Написать код — `opsx:apply`
### 7. Написать код — `opsx:apply`
Вызови Skill `opsx:apply` для реализации `tasks.md`. Код — по конвенциям проекта
(каталог `docs/conventions/`). Меняешь схему — обнови её описание в
@@ -256,21 +308,31 @@ flowchart TD
**Сервис не оставляем лежать.** Если запуск упал — почини или откати до конца
шага.
### 7. Ревью кода — Skill `av-dev-pipeline:review-pipeline`
### 8. Ревью кода — Skill `av-dev-pipeline:review-pipeline`
Второй чекпоинт. Вызови Skill **`av-dev-pipeline:review-pipeline`**, дав ссылку
на change `<id>`, базу диффа **и режим запуска**.
на change `<id>`, базу диффа, **план разметки с шага 4** и режим запуска.
**Профиль ты не передаёшь, и это правило, а не упрощение.** Ступень выбирает
разметчик конвейера (`review-scope`, стадия 0) — по объёму и незнакомости
изменения, с обоснованием строкой. Причина в разведённости: ты только что написал
этот код, и решать, насколько глубоко его проверять, тебе нельзя — под давлением
«я почти закончил» решение известно заранее. Правило выбора живёт в скилле
конвейера, проектные триггеры — в `docs/review.*`.
**Метка ты не выбираешь, и это правило, а не упрощение.** Её назвал
`review-scope` ещё на шаге 4 — по размеру и сложности, с обоснованием по каждой
оси. Причина в разведённости: ты только что написал этот код, и решать, насколько
глубоко его проверять, тебе нельзя — под давлением «я почти закончил» решение
известно заранее. Правило выбора живёт в скилле конвейера, проектные триггеры — в
`docs/review.*`, подраздел «Триггеры метки».
**Считаешь ступень заниженной — скажи это в докладе строкой, а не переспорь.**
**Метка не пересматривается по факту диффа.** Дифф может выйти крупнее, чем
ожидалось при разметке, — это не повод её поднимать: пересмотр означал бы второй
запуск разметчика, ровно то, ради устранения чего он и переехал на шаг 4.
**Считаешь метку заниженной — скажи это в докладе строкой, а не переспорь.**
Разметчик вправе и поднять, и понизить; твоё несогласие это факт для человека, а
не команда конвейеру.
не команда конвейеру. Место, где такое несогласие превращается в изменение
правил, — журнал дефектов `docs/review.md`, и только постфактум.
**Плана нет — ревью кода не запускается.** Триаж требует план обязательным
входом: без него он не может сверить, все ли размеченные темы вернули отчёт, а
эта сверка — единственная защита от молчащего пропуска. Потерял план (прервалась
сессия, ушёл контекст) — повтори шаг 4, а не гони прогон без него.
**Режим по умолчанию — `по графу`, и обосновывать его не надо.** Конвейер сам
знает свои рёбра: гейт открывает опиниативные проходы, проходы с пометкой «держит
@@ -289,10 +351,10 @@ flowchart TD
разметчика — таблицей «тема → дом → глубина → кто закрывает», — и против каждой
темы обязан стоять исход. Тема без отчёта и тема без дома — разные вещи, и обе
должны быть названы. Реестр короткий (шесть тем ядра плюс свои) — сверка стоит
одного взгляда. Почему это правило существует, объясняет раздел «Профили» скилла
одного взгляда. Почему это правило существует, объясняет раздел «Метки» скилла
конвейера; здесь — само требование.
Отработай так же, как шаг 5: помеченное `инлайн` чини сам и не логируй,
Отработай так же, как шаг 6: помеченное `инлайн` чини сам и не логируй,
`развилка` — вопросом в запись (он уже сформулирован триажем, его остаётся
перенести). После правок — снова гейт.
@@ -306,19 +368,19 @@ flowchart TD
сжатой строкой. Отчёт, из которого исчезло «что проверить было невозможно»,
превращается в ложное ощущение проверенности.
**Отчёт триажа сохрани вместе с change (`openspec/changes/<id>/review/`; шаг 8
**Отчёт триажа сохрани вместе с change (`openspec/changes/<id>/review/`; шаг 9
унесёт его в `openspec/changes/archive/<id>/review/` вместе с change) — это
обязательно, а не «если удобно».** По нему потом видно, что было найдено и что из
этого осталось в урожае. И это единственный **независимый** артефакт о составе
прогона: под оркестратором `task-batch` именно по нему сверяют полноту ревью
ветки, а не по твоей прозе — она написана тем же, кто мог проход и пропустить.
### 8. Архивировать — `opsx:archive`
### 9. Архивировать — `opsx:archive`
Вызови Skill `opsx:archive`: change уезжает в архив, дельты вливаются в
актуальные спеки.
### 9. Синк документации
### 10. Синк документации
Ревью выполненного — до этого шага. Затем **вызови Skill `av-dev-pm:docs`**: он
владеет содержимым документов канона и ведёт чек-лист синка. Плагина нет — шаг
@@ -343,7 +405,7 @@ flowchart TD
сделан по перечню документов, без списка триггеров — плагина `av-dev-pm` нет».
Канона в проекте тоже нет — назови это исходом и предложи `av-dev-pm:canon`.
### 10. Коммит
### 11. Коммит
Коммить **в текущую ветку** (`git rev-parse --abbrev-ref HEAD`), сам ветку не
создавай и не переключай, ничего не пушь. При ручном запуске HEAD обычно на
@@ -354,7 +416,7 @@ flowchart TD
сделано», тело списком 1–3 пункта, без трейлеров). Одна задача — один осмысленный
коммит.
### 11. Закрыть задачу — **после коммита, не раньше**
### 12. Закрыть задачу — **после коммита, не раньше**
**Вызови Skill `av-dev-pm:tasks`** и попроси закрыть задачу как реализованную —
он владеет форматом и двигает строку из набора спринта сам. Путь к его скрипту не
@@ -362,7 +424,7 @@ flowchart TD
путь.
**Порядок обязателен.** Закрытие удаляет файл задачи; сделанное до коммита оно
оставило бы задачу закрытой без единого следа работы, если шаг 10 упадёт.
оставило бы задачу закрытой без единого следа работы, если шаг 11 упадёт.
**Закрытие тоже коммитится — вторым коммитом, тут же.** Удаление файла задачи и
правка индексов (их имена знает `av-dev-pm`, не ты) — это правки в рабочем
@@ -390,7 +452,7 @@ flowchart TD
это доклад приёмщику, а не отметка «принято»;
- **`Урожай`** — отложенные находки списком (формулировка, оракул, провенанс).
Задачи из него заводит тот, кто ведёт задачи проекта;
- **одна строка границ покрытия**: какая ступень и режим гонялись, какие проходы
- **одна строка границ покрытия**: какая метка и режим гонялись, какие проходы
не запускались и что проверить было невозможно. Доклад без неё сообщает
«проверено», не сообщая, что именно.
@@ -400,15 +462,16 @@ flowchart TD
текущем worktree и на текущей ветке: не делай `git checkout`/`switch`, не
создавай веток, не пушь.
- Не пропускай `openspec validate --strict` перед архивацией.
- Тривиальная задача: шаги 2 и 4 пропускаются; ревью кода (шаг 7) остаётся
всегда, но в профиле `quick`.
- Тривиальная задача: пропускается только шаг 2. Обе стадии ревью остаются, но
с меткой `small` — один проход на дизайне и четыре на коде, а при своих темах
проекта пять: приёмник тем запускается, если ему есть что принимать.
- Гейт блокирует: пока он красный, опиниативные проходы не запускаются. Чинить и
перезапускать, а не «посмотреть заодно».
- Если ревью предлагает крупную переработку — это развилка: не правь молча и не
спрашивай, запиши вопросом и доведи остаток.
- Держи вызывающего в цикле короткими репликами на переходах фаз, но не проси
подтверждать механику.
- **Занизить ступень ревью или пропустить тему — самый дешёвый способ
- **Занизить метка ревью или пропустить тему — самый дешёвый способ
«ускориться», и он же самый дорогой по последствиям.** Защита устроена так,
что регулятора у тебя нет: ступень выбирает разметчик, план сверяется по темам,
непокрытое называется в отчёте строкой.
что регулятора у тебя нет: метку выбирает разметчик **до того**, как ты
написал код, план сверяется по темам, непокрытое называется в отчёте строкой.