av-dev-pipeline: починены находки ревью, бриф заводится скиллом

- скилл project-brief: бриф собирается из CLAUDE.md, архитектуры, Taskfile
  и конвенций и показывается человеку. Раньше единственная инструкция по
  его созданию лежала внутри шаблона, поэтому деградированный режим был не
  аварийным, а единственным: critical по основанию «нарушен инвариант»
  недостижим ни на одной задаче
- rebase перенесён внутрь worktree задачи: прежняя форма падала на занятой
  ветке, и агент уводил весь батч в провалившиеся с ложной причиной
- контракт брифа дополнен восемью слотами; проверен заполнением на обоих
  проектах, незаполнимых нет. Прецедент healthlog вынут из общего charter'а
  в бриф — там он вмёрз вместе с числами
- шов: пайплайн задачу не закрывает и записи учёта не трогает, урожай
  отдаёт списком, правило остатка — ссылкой на av-dev-tasks
- деградированный абзац во всех девяти проходах, вопрос 9 в ops,
  пространство имён в вызовах, раздел предпосылок
This commit is contained in:
av
2026-08-03 11:45:40 +03:00
parent 20dca29add
commit 0eca206460
18 changed files with 1021 additions and 214 deletions
+104 -44
View File
@@ -10,18 +10,48 @@ description: Автономно проводит одну задачу чере
Это тонкая обёртка над каноническими скиллами `opsx:explore` / `opsx:propose` /
`opsx:apply` / `opsx:archive` — вызывай их через Skill, не переизобретай их шаги.
Ревью — скилл `review-pipeline`, он же держит правило выбора профиля.
Ревью — скилл `av-dev-pipeline:review-pipeline`, он же держит правило выбора
профиля.
## Предпосылки
- **OpenSpec и скиллы `opsx:*`** — внешняя обвязка, на которой стоят шаги 2, 3, 6
и 8, а также проход `review-specs` и профиль `design` (они завязаны на
`openspec/changes/<id>/specs/*/spec.md` и на `openspec validate --strict`). В
проекте без OpenSpec эти шаги упадут на «нет такого скилла»: либо подключаем
OpenSpec, либо цикл вырождается в «прочитать задачу → код → ревью кода →
коммит», и об отсутствии спекового контура говорится в докладе.
- **Скиллы зовутся с пространством имён** — `av-dev-pipeline:review-pipeline`,
`av-dev-pipeline:project-brief`. Короткое имя может разрешиться в устаревшую
проектную копию, и это произойдёт молча.
- **Проектные копии этих скиллов и агентов удаляются при установке плагина**
(`.claude/skills/{task-pipeline,review-pipeline,task-batch}`,
`.claude/agents/<проект>-review-*.md`). Две копии одного скилла расходятся, и
побеждает та, что короче названа.
Перед стартом прочитай `CLAUDE.md` проекта и то, на что он ссылается
(архитектура, конвенции), если ещё не в контексте. Проектные факты, нужные ревью
— инварианты, команда гейта, объёмы, модель угроз, — живут в брифе
— инварианты, команда гейта, объёмы, модель угроз, прецеденты, — живут в брифе
(`docs/review-brief.md`, контракт — в references конвейера ревью).
**Брифа нет ни по одному пути — заведи его, а не работай в деградированном
режиме.** Вызови Skill **`av-dev-pipeline:project-brief`**: он соберёт бриф из
`CLAUDE.md`, архитектуры, файла задач и конвенций, покажет человеку и вернёт
путь, который дальше передаётся ревью. Это механика: спрашивать разрешения не
нужно. Один шаг один раз на проект — против деградации на каждой задаче.
## Границы: чем пайплайн не владеет
- **Беклогом, спринтом, целями и приоритетами.** Задача приходит извне. Пайплайн
её не выбирает, не приоритизирует, не заводит и не переоценивает; если в
проекте есть свой процесс управления задачами — он и решает, что брать.
- **Записями учёта.** Пайплайн **не закрывает задачу**, не двигает её по
статусам, не правит индекс и не зовёт скриптов учёта. Он сообщает исход;
закрытие — акт владельца спринта **после приёмки**, и оно происходит снаружи.
Закрыть задачу самому — значит закрыть её до коммита и до всякой приёмки, то
есть заверить собственную работу.
- **Заведением задач из урожая ревью.** Отложенные находки отдаются **списком**
(см. шаг 7); превращать их в задачи — работа того, кто ведёт задачи проекта.
- **Определением ценности.** «Нужна ли эта функциональность» — не вопрос
пайплайна ни на одном шаге.
@@ -47,12 +77,17 @@ description: Автономно проводит одну задачу чере
поимённо, непущенные проходы названы в границах покрытия;
3. change заархивирован, дельты влиты в актуальные спеки;
4. коммит сделан в текущую ветку;
5. **критерии приёмки, если проект их дал**, проверены поимённо, у каждого назван
оракул и исход. Критерии приходят снаружи; пайплайн их не сочиняет и не
занижает. Расхождение «критерии закрыты, а суть задачи не достигнута» — дефект
критериев, и о нём сообщается, а не молча дорабатывается.
5. **критерии приёмки, если проект их дал, выписаны поимённо, и по каждому назван
оракул и наблюдаемый исход** — «прогнал вот это, увидел вот то». Это **доклад,
а не сертификация: приёмка — не работа пайплайна.** Исполнитель, ставящий себе
галочку «принято», проверяет свою работу своим же взглядом — по границе это
может делать только декоррелированный приёмщик. Критерии приходят снаружи;
пайплайн их не сочиняет и не занижает. Расхождение «по каждому критерию исход
есть, а суть задачи не достигнута» — дефект критериев, и о нём сообщается, а
не молча дорабатывается.
Пункты 1–4 — своё. Пункт 5 — внешнее, и проверяется только если оно дано.
Пункты 1–4 — своё. Пункт 5 — внешнее: пайплайн доводит его до наблюдаемого
исхода и передаёт дальше.
## Принцип автономности
@@ -73,13 +108,23 @@ description: Автономно проводит одну задачу чере
3. Доведи остаток до конца и закоммить. Задача не «висит на вопросе», она сделана
в объявленных границах.
**Что остатком не является** — две оговорки, без которых правило вредит:
**Что остатком не является — правило живёт не здесь.** Канонический текст с обеими
оговорками — в плагине `av-dev-tasks`, скилл `av-dev-tasks:session`, раздел
`## Вопрос, блокер, необратимое`, подраздел «Отличать вопрос от застревания».
Правило принадлежит управлению задачами, потому что решает **сделана задача или
вышла**, — это исход планирования, а не исполнения. **Ссылайся, не
пересказывай:** копия, заведённая здесь, уже однажды разошлась с оригиналом и
потеряла из перечня самое необратимое — запись **наружу**.
- **остаток, который записывает в хранилище или в журнал состояние, зависящее от
нерешённого, — не остаток.** Решение поднимается до начала записи. Иначе
нерешённое материализуется в данные, а данные переживают решение;
- **остаток, из которого пропала польза, названная в постановке, — не остаток.**
Это исход «не доведена», а не «сделана в границах».
Коротко, чтобы знать, когда идти читать: остаток проверяется двумя порогами —
**материализация нерешённого** (запись состояния, зависящего от неотвеченного
вопроса) и **пол по пользе** (из остатка пропала польза, названная в постановке).
Оба порога — стоп: первый поднимает решение до начала записи, второй даёт исход
«не доведена».
Плагин `av-dev-tasks` не подключён — правило не отменяется, а становится
осторожнее: прежде чем записать зависящее от нерешённого куда бы то ни было —
в хранилище, в журнал, в витрину или наружу, — спрашивай человека.
Нет полезного остатка — задача заканчивается исходом «не доведена», вопрос
записан, ничего не коммитится наполовину.
@@ -137,10 +182,10 @@ description: Автономно проводит одну задачу чере
### 4. (Нетривиальная) Ревью предложения — профиль `design`, ДО кода
Первый чекпоинт. Вызови Skill **`review-pipeline`** с профилем `design`, ссылкой
на change `<id>` и путём к брифу. Он запустит `review-specs` (режим «дизайн ДО
кода»), `review-rubric` (фаза 1: приёмочные критерии для задуманного узла) и
`review-architecture` по предложению.
Первый чекпоинт. Вызови Skill **`av-dev-pipeline:review-pipeline`** с профилем
`design`, ссылкой на change `<id>` и путём к брифу. Он запустит `review-specs`
(режим «дизайн ДО кода»), `review-rubric` (фаза 1: приёмочные критерии для
задуманного узла) и `review-architecture` по предложению.
Смысл профиля: архитектурная находка на готовом коде стоит переписывания и
потому игнорируется — та же находка здесь стоит абзаца обсуждения. Рубрику из
@@ -170,17 +215,16 @@ description: Автономно проводит одну задачу чере
**Сервис не оставляем лежать.** Если запуск упал — почини или откати до конца
шага.
### 7. Ревью кода — Skill `review-pipeline`
### 7. Ревью кода — Skill `av-dev-pipeline:review-pipeline`
Второй чекпоинт. Вызови Skill **`review-pipeline`**, дав ссылку на change `<id>`,
базу диффа, путь к брифу, профиль **и режим запуска**. Профиль выбирается по
факту изменения, а не по ощущению важности; общее правило — в скилле, проектные
триггеры — в брифе:
Второй чекпоинт. Вызови Skill **`av-dev-pipeline:review-pipeline`**, дав ссылку
на change `<id>`, базу диффа, путь к брифу, профиль **и режим запуска**.
- миграция схемы, новый пакет, публичный контракт, правило идентичности или
слияния данных → `deep`;
- иначе меняется поведение, видимое снаружи → `standard`;
- иначе (багфикс, локальная правка, доки) → `quick`.
**Правило выбора профиля живёт в скилле конвейера** (раздел «Профили»), проектные
триггеры — в разделе `## Триггеры` брифа. Здесь оно не пересказывается: три
копии одного правила расходятся, и работать будет та, которую прочитали
последней. Помни ровно одно — **профиль выбирается по факту изменения, а не по
ощущению важности**, и посмотри таблицу перед вызовом.
**Режим по умолчанию последовательный, и обосновывать его не надо.** Параллельно
гоняем только тогда, когда об этом попросили явно **и назвали набор** — какие
@@ -195,41 +239,54 @@ description: Автономно проводит одну задачу чере
покрытия.
**Сверь состав прогона с таблицей профилей в скилле, прежде чем коммитить.**
Пропуск прохода не отличим от прохода без находок: гейт зелёный, спеки сошлись,
отчёт выглядит полным. Единственный, кто мог бы заметить пропуск, — триаж, а он
заполняется тем, что ему подали. Отчёт обязан называть запущенные проходы
**поимённо и с исходом**; непущенный идёт строкой «не запускался» в границы
покрытия. Реестр короткий (4–8 проходов) — сверка стоит одного взгляда, а
молчащий пропуск уже стоил семи находок и отдельной задачи на их дозакрытие.
Отчёт обязан называть запущенные проходы **поимённо и с исходом**; непущенный
идёт строкой «не запускался» в границы покрытия. Реестр короткий (4–8 проходов) —
сверка стоит одного взгляда. Почему это правило существует, объясняет раздел
«Профили» скилла конвейера; здесь — само требование.
Отработай так же, как шаг 5: помеченное `инлайн` чини сам и не логируй,
`развилка` — вопросом в запись (он уже сформулирован триажем, его остаётся
перенести). После правок — снова гейт.
**Урожай — списком, не задачами.** Отложенные находки (реальный `major` не для
этого мерджа, развилка, решённая «потом», пачка `nit`) собери в секцию доклада
`Урожай`: формулировка, оракул, провенанс. Задачи из него **заводит не пайплайн**
— у того, кто ведёт задачи проекта, своя нарезка, свой формат и свои правила
дублей. Твоя обязанность — не потерять и передать.
**Границы покрытия из отчёта не выбрасывай** — они уезжают в финальный доклад
сжатой строкой. Отчёт, из которого исчезло «что проверить было невозможно»,
превращается в ложное ощущение проверенности.
Отчёт триажа сохрани вместе с change (`openspec/changes/<id>/review/`): по нему
потом видно, что было найдено и что из этого осталось незаведённым.
**Отчёт триажа сохрани вместе с change (`openspec/changes/<id>/review/`) — это
обязательно, а не «если удобно».** По нему потом видно, что было найдено и что из
этого осталось в урожае. И это единственный **независимый** артефакт о составе
прогона: под оркестратором `task-batch` именно по нему сверяют полноту ревью
ветки, а не по твоей прозе — она написана тем же, кто мог проход и пропустить.
### 8. Архивировать — `opsx:archive`
Вызови Skill `opsx:archive`: change уезжает в архив, дельты вливаются в
актуальные спеки.
### 9. Синк документации и закрытие задачи
### 9. Синк документации
Ревью выполненного — **до** закрытия. Затем:
Ревью выполненного — до этого шага. Затем:
- суть переехавшего решения — в документацию проекта (архитектура, журнал
решений), если её там ещё нет;
- менялась схема — её описание обновлено тем же change;
- новое, узнанное о внешнем формате или о данных, — в тот файл проекта, который
это накапливает; такой файл обычно ценнее кода;
- **задача закрывается процедурой проекта** — своей у пайплайна нет. Есть скилл
или скрипт беклога — вызови его; нет — скажи в докладе, что задача сделана и
закрытие остаётся за вызывающим. Не выдумывай формат чужого индекса.
- воспроизведённый дефект (свой или чужой) — в раздел `## Прецеденты` брифа:
класс, симптом, чем воспроизведён, чем закончилось. Это единственный артефакт,
который делает следующее ревью умнее.
**Задачу пайплайн не закрывает.** Записи учёта — индекс, статус, спринт — он не
трогает вовсе: закрытие происходит **после приёмки** и делается владельцем
спринта, а пайплайн на этом шаге стоит до коммита и до всякой приёмки. Скриптов
и скиллов учёта не зови — их у тебя и нет: пути между плагинами не разрешаются, и
моста здесь намеренно не проложено. Твоё дело — назвать исход в докладе.
### 10. Коммит
@@ -242,13 +299,17 @@ description: Автономно проводит одну задачу чере
сделано», тело списком 1–3 пункта, без трейлеров). Одна задача — один осмысленный
коммит.
Готово — доложи кратко:
Готово — доложи кратко. Доклад и есть выход пайплайна: **задача остаётся
открытой**, её закрывает владелец спринта после приёмки.
- **исход** задачи одним из трёх слов и, если не «сделана», чем ограничен
результат;
- что сделано, какие вопросы записаны и куда;
- ссылка на архивный change;
- исход по каждому критерию приёмки, если они были;
- ссылка на архивный change и хеш коммита;
- по каждому критерию приёмки, если они были: **оракул и наблюдаемый исход**
это доклад приёмщику, а не отметка «принято»;
- **`Урожай`** — отложенные находки списком (формулировка, оракул, провенанс).
Задачи из него заводит тот, кто ведёт задачи проекта;
- **одна строка границ покрытия**: какой профиль и режим гонялись, какие проходы
не запускались и что проверить было невозможно. Доклад без неё сообщает
«проверено», не сообщая, что именно.
@@ -270,5 +331,4 @@ description: Автономно проводит одну задачу чере
- **Занизить профиль ревью или пропустить проход — самый дешёвый способ
«ускориться», и он же самый дорогой по последствиям.** Защита одна: профиль
выбирается по факту изменения, состав сверяется поимённо, а непущенное
называется в отчёте. Пропуск, названный строкой, стоит строки; пропуск молчащий
стоил семи находок.
называется в отчёте строкой.