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

- удалены скилл project-brief и контракт брифа; вместо них references/
  project-facts.md — карта «что нужно проходу → где лежит» и таблица
  поразрядной деградации по документам
- девять charter'ов, review-pipeline, task-pipeline и task-batch переписаны
  на пути канона; OpenSpec стал объявленной предпосылкой без ветки деградации
- шаг синка документации переписан в построчный доклад, закрытие задачи —
  вызовом скилла av-dev-pm:tasks вместо строки-слота из CLAUDE.md
- по находкам ревью: docs.py звал tasks.py из чужого каталога и выдавал его
  отказ окружения за дрейф; сверка миграций не видела рабочее дерево;
  плейсхолдер краснел вместо замечания; сверка capability проходила по
  совпадению с именем пакета; tasks.py не читал docs/.pm.json; скилл docs
  пересказывал канон в пяти местах
This commit is contained in:
av
2026-08-03 14:28:55 +03:00
parent ad1779b81f
commit 9cef45252c
26 changed files with 687 additions and 1232 deletions
+51 -52
View File
@@ -1,6 +1,6 @@
---
name: review-pipeline
description: Конвейер ревью изменения — детерминированный гейт, сверка с дельта-спеками в обе стороны, враждебные постановки и эксплуатационный постмортем, независимая реализация по триггеру, архитектура и обязательный триаж. Проходы гонятся последовательно; параллельно — только по явной просьбе и с явно названным набором. Проектная специфика приходит из файла-брифа. Вызывается из task-pipeline (чекпоинты ревью), из task-batch (финальная сверка) и отдельно — профилем design на предложении ДО кода.
description: Конвейер ревью изменения — детерминированный гейт, сверка с дельта-спеками в обе стороны, враждебные постановки и эксплуатационный постмортем, независимая реализация по триггеру, архитектура и обязательный триаж. Проходы гонятся последовательно; параллельно — только по явной просьбе и с явно названным набором. Проектная специфика приходит из документов канона av-dev-pm. Вызывается из task-pipeline (чекпоинты ревью), из task-batch (финальная сверка) и отдельно — профилем design на предложении ДО кода.
---
# Конвейер ревью
@@ -34,16 +34,17 @@ description: Конвейер ревью изменения — детермин
Конвейер опирается на внешнюю обвязку и без неё работает не целиком. Проверь это
один раз, при установке плагина в проект:
- **OpenSpec и скиллы `opsx:*`.** Профиль `design`, проход `review-specs` и
- **OpenSpec — жёсткая предпосылка, а не опция.** Профиль `design`, проход
`review-specs` и
вызывающий пайплайн задачи завязаны на дельта-спеки
(`openspec/changes/<id>/specs/*/spec.md`), на актуальные спеки
(`openspec/specs/`) и на `openspec validate --strict`. В проекте без OpenSpec
шаги, зовущие `opsx:explore` / `opsx:propose` / `opsx:apply` / `opsx:archive`,
упадут на «нет такого скилла», а `review-specs` останется без источника
требований. Такой проект либо подключает OpenSpec, либо сознательно не зовёт
`review-specs` и профиль `design` — и тогда это идёт строкой «не запускался» в
границы покрытия, как любой другой пропуск.
- **Бриф проекта** — см. следующий раздел. Заводится скиллом, а не руками.
требований. **Проект без OpenSpec этим конвейером не проверяется** — подключай
OpenSpec, а не понижай прогон: ветка деградации здесь не пишется, потому что
непроверенная ветка деградации хуже честного отказа.
- **Документы канона** — см. следующий раздел.
- **Проектные копии этих скиллов и агентов удаляются при установке.** Если в
проекте уже лежат свои `.claude/skills/review-pipeline`,
`.claude/skills/task-pipeline`, `.claude/skills/task-batch` или
@@ -51,39 +52,35 @@ description: Конвейер ревью изменения — детермин
в устаревшую проектную копию, молча и без признаков подмены. По той же причине
**скиллы этого плагина зовутся с пространством имён**:
`av-dev-pipeline:review-pipeline`, `av-dev-pipeline:task-pipeline`,
`av-dev-pipeline:task-batch`, `av-dev-pipeline:project-brief`.
`av-dev-pipeline:task-batch`.
## Что конвейер защищает — приходит из брифа
## Что конвейер защищает — приходит из документов проекта
Проходы общие, а нарушать нельзя проектное. Список инвариантов, команду гейта,
объёмы, прецеденты и модель угроз конвейер **не знает** — он читает их в брифе
проекта: [references/project-brief.md](references/project-brief.md) описывает
контракт, [references/brief-template.md](references/brief-template.md) — образец
заполнения.
Проходы общие, а нарушать нельзя проектное. Инварианты, команду гейта, объёмы,
прецеденты и модель угроз конвейер **не знает** — он читает их в документах
канона `av-dev-pm`, **напрямую и по жёстким путям**. Отдельного файла-брифа нет:
пути известны, посредник не нужен, а второй дом для тех же фактов разошёлся бы и
выглядел актуальным.
Разреши путь к брифу один раз, в начале прогона: путь из задания →
`docs/review-brief.md``.claude/review-brief.md`. Дальше передавай готовым.
Карта «что нужно проходу → где лежит» —
[references/project-facts.md](references/project-facts.md). Прочитай её до
раздачи заданий; там же таблица поразрядной деградации.
**Брифа нет по всем трём путям — заведи его, а не понижай прогон.** Вызови Skill
**`av-dev-pipeline:project-brief`**: он соберёт бриф из `CLAUDE.md`, архитектуры,
файла задач и конвенций, покажет человеку и вернёт путь. Это механика, а не
развилка: спрашивать разрешения не нужно, и остановка прогона тут не
предусмотрена. Заведение стоит одного шага один раз на проект — деградированный
режим платит на каждой задаче.
**Деградация поразрядная, а не всё-или-ничего.** Документа нет — деградирует то,
что из него читалось, и только оно: нет `docs/security.md` — слабеет
`adversary`; нет `docs/research/` — числа неизвестны трём проходам; нет
инвариантов в `CLAUDE.md``critical` по основанию «нарушен инвариант проекта»
не присваивается никем. Каждый проход пишет **свою** строку в границы покрытия, с
**причиной**; триаж сводит их и не сливает в одну.
**Деградированный режим — исход, а не умолчание.** Он включается ровно тогда,
когда бриф завести не удалось (репозиторий на чтение, человек прямо запретил,
инварианты вывести неоткуда): `critical` по основанию «нарушен инвариант
проекта» никем не присваивается, числа объёма не используются, и в границы
покрытия уезжает строка «брифа проекта нет, завести не удалось: <причина>».
Причина обязательна — без неё строка неотличима от «мы просто не стали».
**Документов канона нет вовсе** — проект не приведён к канону. Скажи это строкой
и предложи скилл `av-dev-pm:canon`: одна операция на проект против деградации на
каждой задаче. Прогон при этом не останавливается.
## Что получает каждый проход
Задание любому проходу состоит из шести вещей, и первая — главная: без брифа
проход теряет предмет проверки и уходит в деградированный режим.
Задание любому проходу состоит из пяти вещей:
- **бриф** — путь (разрешён или заведён на старте, см. выше);
- **контракт находок** — путь к
[references/finding-contract.md](references/finding-contract.md) (в
установленном плагине — `${CLAUDE_PLUGIN_ROOT}/skills/review-pipeline/references/`);
@@ -146,7 +143,7 @@ description: Конвейер ревью изменения — детермин
|---|---|---|---|
| `quick` | багфикс, локальная правка, доки | 0, 1, 5 | 4 |
| `standard` | новая функциональность в существующем пакете | 0, 1, 2, 5 | 6 |
| `deep` | новый пакет, изменение публичного контракта, миграция схемы, трогает инварианты брифа | 0, 1, 2, 3, 4, 5 | 78 |
| `deep` | новый пакет, изменение публичного контракта, миграция схемы, трогает инварианты проекта | 0, 1, 2, 3, 4, 5 | 78 |
| `design` | **до кода**, на предложении | specs + rubric + architecture (см. ниже) | 3 |
**Состав сверяется по этой таблице до коммита.** Реестр из трёх-восьми пунктов
@@ -168,8 +165,8 @@ description: Конвейер ревью изменения — детермин
- иначе → `quick`.
Что именно в этом проекте считается публичным контрактом и какие пути означают
`deep` — раздел `## Триггеры` брифа. Он **уточняет** правило, а не отменяет его:
если триггеров в брифе нет, работает список выше.
`deep`, проект может уточнить в `docs/review.md`, разделе настройки конвейера. Это
**уточнение**, а не отмена: не записано — работает список выше.
Профиль объявляется в отчёте. Понижение профиля — решение оркестратора, и оно
попадает в границы покрытия строкой «профиль понижен до X, потому что …».
@@ -207,8 +204,8 @@ description: Конвейер ревью изменения — детермин
роста файлов журнала, длительность транзакции. Два меряющих прохода на одной
машине соревнуются за диск, CPU и за саму СУБД и выдают числа, которые не
воспроизведутся. Это не гипотеза: правило выведено из находок, целиком
державшихся на таких замерах, — у каждого проекта они свои и лежат в разделе
`## Прецеденты` его брифа. Число, снятое под конкурентную нагрузку от соседнего
державшихся на таких замерах, — у каждого проекта они свои и лежат в журнале
`docs/review.md`. Число, снятое под конкурентную нагрузку от соседнего
прохода, — это находка с испорченным оракулом, а её опровержение стоит дороже
всего выигрыша от параллельности.
- **Машина одна.** Рядом идёт задача, поднят сервис, гоняется гейт или дорогая
@@ -251,7 +248,7 @@ description: Конвейер ревью изменения — детермин
## Стадия 0 — Gate (обязательна во всех профилях)
Агент `review-gate`. Запускает команду гейта из раздела `## Гейт` брифа и
Агент `review-gate`. Запускает команду гейта из семантики гейта в `CLAUDE.md` и
интерпретирует вывод.
**Пока гейт красный — опиниативные проходы не запускаются.** Оркестратор чинит и
@@ -267,7 +264,7 @@ description: Конвейер ревью изменения — детермин
линтеры и детектор гонок. Пропуск при этом не молчит — он виден в сводке с
причиной и уезжает в границы покрытия, как и любой другой `SKIP`.
Шаги, которые красят гейт безусловно, перечислены в брифе с причиной. Проходу
Шаги, которые красят гейт безусловно, перечислены в `CLAUDE.md` с причиной. Проходу
запрещено списывать такой отказ в мелочь.
## Стадия 1 — Conformance (обязательна во всех профилях)
@@ -279,11 +276,10 @@ description: Конвейер ревью изменения — детермин
- `review-specs` — критерий взят из **дельта-спек предлагаемого изменения**, а не
из proposal, сообщения коммита или описания задачи. Сверка двунаправленная;
направление `code → spec` важнее.
- `review-code` — критерий взят из конвенций проекта: файла или каталога файлов,
путь — раздел `## Карта` брифа. Берётся только та их часть, которая **не
выражается правилом**:
механизируемое уже проверила стадия 0. Что именно механизировано, тот же раздел
брифа перечисляет — повторять это проходом вредно.
- `review-code` — критерий взят из конвенций проекта, каталог
`docs/conventions/`. Берётся только та их часть, которая **не выражается
правилом**: механизируемое уже проверила стадия 0. Что именно механизировано,
перечисляет `conventions/README.md` повторять это проходом вредно.
Recall обоих равен длине их источника — это и есть предел applicative-проходов,
ради которого существует стадия 2.
@@ -309,15 +305,17 @@ Recall обоих равен длине их источника — это и е
**прогнать**, второй смотрит ось времени и эксплуатации, которую не смотрит
никто другой.
Материал обоим даёт бриф: `## Модель угроз` — враждебному, `## Прод и поток`
эксплуатационному. Без этих разделов стадия вырождается в общие места.
Материал берётся из документов: `docs/security.md` — враждебному,
`docs/architecture.md` плюс **`docs/research/` и `docs/database.md` вместе** —
эксплуатационному. Последние два сшивает сам проход: число без настройки не с чем
сравнить. Без этих документов стадия вырождается в общие места.
## Стадия 3 — Independent reimplementation (`deep`, по триггеру)
- `review-reimpl` — пишет свою реализацию, не открывая существующую, затем
диффит по решениям. **Запускается по триггеру, а не всегда:** изменение вводит
новое правило идентичности, слияния или разбора (проектная формулировка
триггера — в разделе `## Триггеры` брифа). Это самый дорогой проход конвейера
триггера — в `docs/review.md`, если записана). Это самый дорогой проход конвейера
(его счёт определяется объёмом вывода — он пишет реализацию целиком), а вне
этого триггера независимый взгляд в значительной мере уже дал профиль `design`:
код писался под его находки. Триггер выбран по факту: единственный раз, когда
@@ -328,7 +326,7 @@ Recall обоих равен длине их источника — это и е
Агент `review-architecture`. Получает **вход шире диффа**: дерево пакетов с
назначением, граф внутренних зависимостей, инвентарь существующих концепций.
Команду, которая это готовит, даёт раздел `## Команды` брифа; нет команды —
Команду, которая это готовит, даёт раздел команд `CLAUDE.md`; нет команды —
проход собирает карту сам и говорит об этом в границах покрытия.
Главный вопрос — концептуальная целостность и **второй способ** делать то, что
@@ -400,7 +398,7 @@ Recall обоих равен длине их источника — это и е
у него свой формат, своя нарезка и свои правила дублей. Мелочь класса `nit`
идёт в урожай одной пачкой, а не записью на находку.
- `Promote candidates` — по процедуре [references/promote.md](references/promote.md):
находка → конвенция → правило линтера → **удаление из конвенций и из брифа**.
находка → конвенция → правило линтера → **удаление формулировки из конвенций**.
Третий шаг обязателен.
- Дефект, проскочивший ревью и всплывший позже, идёт в журнал проекта
([references/review-journal.md](references/review-journal.md)) — сразу, не
@@ -421,8 +419,9 @@ Recall обоих равен длине их источника — это и е
Согласие нескольких проходов — **не подтверждение**: это один источник,
высказавшийся несколько раз. Совпадение повышает приоритет, но не `confidence`.
Что недоступно **этому** проекту принципиально — перечисляет раздел
`## Недоступно проверке` брифа, и он целиком уезжает в границы покрытия.
Что недоступно **этому** проекту принципиально — перечисляет «Недоступно
проверке» в `docs/review.md`, и оба его подраздела целиком уезжают в границы
покрытия.
Независимо от проекта недоступно:
- поведение внешних систем в их будущих версиях;
@@ -442,9 +441,9 @@ Recall обоих равен длине их источника — это и е
## Ссылки
- Skill `av-dev-pipeline:project-brief` — заведение и обновление брифа.
- [references/project-brief.md](references/project-brief.md) — контракт брифа проекта.
- [references/brief-template.md](references/brief-template.md) — шаблон брифа.
- [references/project-facts.md](references/project-facts.md) — что нужно проходу
и где это лежит в документах проекта; таблица поразрядной деградации.
- Skill `av-dev-pm:canon` — приведение проекта к канону документов.
- [references/finding-contract.md](references/finding-contract.md) — контракт находок.
- [references/promote.md](references/promote.md) — промоут находка → конвенция → правило → удаление.
- [references/calibration.md](references/calibration.md) — калибровка инъекцией, вердикты keep/retune/drop.