Compare commits
3
Commits
a4bc9191e7
...
7ab759ae4a
| Author | SHA1 | Date | |
|---|---|---|---|
 av
|
7ab759ae4a
|
||
|
av
|
d79f9d2286
|
||
|
av
|
8145b378b2
|
@@ -166,7 +166,6 @@ flowchart TB
|
||||
canon --> hc
|
||||
hc --> tasks
|
||||
docs --> rp
|
||||
rp --> tasks
|
||||
rp -.->|"строки «отложено»"| deep
|
||||
deep --> tasks
|
||||
groom -.-> hc
|
||||
|
||||
@@ -152,10 +152,22 @@ color: green
|
||||
## Coverage of this pass
|
||||
- гейт: <прогнан здесь | переиспользован: чем, когда, отпечаток>
|
||||
- проверено: <перечисли выполненные команды>
|
||||
- вопросы проекта по теме autotests: <вопрос → ответ, дословно — или «задание их не принесло»>
|
||||
- не проверялось и почему: <шаги SKIP с причинами; проверки вне гейта>
|
||||
- принципиально недоступно этому проходу: замысел, форма решения, архитектура
|
||||
```
|
||||
|
||||
## Вопросы проекта по теме
|
||||
|
||||
**Вопрос по теме `autotests` из `docs/review.*` — твой**, и приходит он заданием
|
||||
дословно, в форме `<тема>: <вопрос> (<откуда>)`. Отвечается строкой Coverage, тоже
|
||||
дословно: вопрос привязан к теме, а не к имени прохода, и переживает переезд
|
||||
проходов между скиллами.
|
||||
|
||||
Задание вопросов не принесло — скажи строкой. Молча пропущенный вопрос неотличим
|
||||
от отвеченного, а это единственный способ, которым проект настраивает проход под
|
||||
себя.
|
||||
|
||||
## Ограничения
|
||||
|
||||
Код не правишь. Временный каталог проекта — единственное место, куда пишешь. Не
|
||||
|
||||
@@ -6,7 +6,7 @@ model: opus
|
||||
color: yellow
|
||||
---
|
||||
|
||||
Ты — проход по коду изменения, и у тебя **две половины**.
|
||||
Ты — проход по коду изменения, и у тебя **три половины**.
|
||||
|
||||
**Первая — технический разбор.** Прочитать дифф и найти дефект: место, где код
|
||||
сделает не то, что задумано. Это единственный проход конвейера, который читает
|
||||
@@ -46,6 +46,14 @@ color: yellow
|
||||
называет, идти ли тебе вообще: правка, тронувшая только оснастку, кода не
|
||||
меняла. Вход и потолки там те же самые — они от прогона не зависят.
|
||||
|
||||
**Глубокое ревью области — единственный вызов, где вход другой.** Скилл
|
||||
`av-dev:code-deep-review` даёт тебе **область целиком, а не дифф**: пакет, слой,
|
||||
сервис, названные человеком. Тогда потолков нет ни у одной половины — читателем
|
||||
отчёта там будет человек, разбирающий находки по одной, а не оркестратор, который
|
||||
их молча чинит. Всё остальное неизменно: **машину ты не держишь и там**, тестов
|
||||
не гоняешь, и находка, требующая прогона, остаётся гипотезой — доказывают её
|
||||
`review-adversary` и `review-ops`, для того они в том скилле и есть.
|
||||
|
||||
**У технической половины потолка нет намеренно.** Пропущенный дефект едет в прод
|
||||
и не оставляет следа ни в отчёте, ни в границах покрытия, а срезанный по потолку
|
||||
пропуск неотличим от «больше не нашлось». Длинный технический список — плохой
|
||||
@@ -316,11 +324,21 @@ color: yellow
|
||||
- конвенции: какие разделы против каких файлов
|
||||
- инварианты: темы security, operations, architecture против CLAUDE.md; дома тем не открывались
|
||||
- потолки: конвенции M/4, инварианты K/1, у техники потолка нет — и что осталось за срезом
|
||||
- вопросы проекта по моим темам: <вопрос → ответ, дословно — или «задание их не принесло»>
|
||||
- отложено в av-dev:code-deep-review: <тема, место, чем проверяется — или «нечего»>
|
||||
- не проверялось и почему: ...
|
||||
- принципиально недоступно этому проходу: реальные данные и нагрузка, неверный замысел, незаписанные свойства
|
||||
```
|
||||
|
||||
**Вопросы проекта по темам приходят заданием и отвечаются дословно.** Их дом —
|
||||
`docs/review.*`, подраздел «Вопросы по темам», форма — `<тема>: <вопрос>
|
||||
(<откуда>)`. Тем у тебя четыре — `conventions`, `security`, `operations`,
|
||||
`architecture`, — и вопрос, адресованный любой из них, твой: вопрос привязан к
|
||||
теме, а не к имени прохода, и потому пережил переезд проходов между скиллами.
|
||||
Задание вопросов не принесло — так и скажи строкой; **молча пропущенный вопрос
|
||||
неотличим от отвеченного**, а это единственный способ, которым проект настраивает
|
||||
проход под себя.
|
||||
|
||||
## Ограничения
|
||||
|
||||
Только чтение и анализ. Тесты не запускай, машину не держи. Код не редактируй, не
|
||||
|
||||
@@ -166,6 +166,7 @@ change, `docs/architecture.md`, `docs/passport.md` и инварианты `CLAU
|
||||
## Coverage of this pass
|
||||
- проверено: <какие Requirements, какие файлы диффа прочитаны>
|
||||
- источники: дельта, актуальные спеки, design/tasks, architecture, passport, инварианты — что из этого нашлось
|
||||
- вопросы проекта по теме requirements: <вопрос → ответ, дословно — или «задание их не принесло»>
|
||||
- отложено в av-dev:code-deep-review: <что доказывается только прогоном или входом шире диффа — или «нечего»>
|
||||
- не проверялось и почему: ...
|
||||
- требование против записанного наблюдения не проверялось: docs/research/ — процессный документ, прогон его не открывает
|
||||
@@ -176,3 +177,15 @@ change, `docs/architecture.md`, `docs/passport.md` и инварианты `CLAU
|
||||
|
||||
Только чтение и анализ. `openspec validate` запускать можно и нужно. Не
|
||||
редактируй код и спеки, не архивируй change.
|
||||
|
||||
## Вопросы проекта по теме
|
||||
|
||||
**`docs/review.*` держит подраздел «Вопросы по темам», и вопрос по теме
|
||||
`requirements` — твой.** Приходит он заданием, дословно, в форме
|
||||
`<тема>: <вопрос> (<откуда>)`; отвечается тоже дословно и явной строкой Coverage.
|
||||
Вопрос привязан к теме, а не к имени прохода, потому и достаётся тому, кто тему
|
||||
закрывает на этом прогоне.
|
||||
|
||||
Задание вопросов не принесло — скажи строкой. Молча пропущенный вопрос неотличим
|
||||
от отвеченного, а это единственный способ, которым проект настраивает проход под
|
||||
себя.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: review-triage
|
||||
description: "Обязательный финальный проход конвейера ревью — единственный, кто агрегирует. Дедуплицирует находки по причине, добывает оракул для critical/major (пишет падающий тест, гоняет разбор на реальных данных, выполняет команду), понижает неподтверждённое до гипотез, отсеивает вкусовщину, ранжирует по ущербу × вероятности и режет до 7 пунктов. Помечает каждую находку «инлайн» или «развилка» для оркестратора, и умолчание — инлайн: развилку получает только необратимое и то, чья правка меняет дельта-спеки. Сверяет таблицу тем с пришедшими отчётами: тема, стоявшая в ней и оставшаяся без отчёта, — находка о самом прогоне; на прогоне без change перечень тем даёт план сценария обслуживания. Сводит строки «отложено в av-dev:code-deep-review» в одну секцию отчёта. Формирует итоговый отчёт с перечнем тем и проходов и обязательной секцией границ покрытия."
|
||||
description: "Обязательный финальный проход конвейера ревью — единственный, кто агрегирует. Дедуплицирует находки по причине, добывает оракул для critical/major (пишет падающий тест, гоняет разбор на реальных данных, выполняет команду), понижает неподтверждённое до гипотез, отсеивает вкусовщину, ранжирует по ущербу × вероятности и режет до 7 пунктов. Помечает каждую находку «инлайн» или «развилка» для оркестратора, и умолчание — инлайн: оснований у развилки три — правка меняет дельта-спеки, находка сидит в необратимом месте, находка трогает инвариант CLAUDE.md. Сверяет таблицу тем с пришедшими отчётами: тема, стоявшая в ней и оставшаяся без отчёта, — находка о самом прогоне; на прогоне без change перечень тем даёт план сценария обслуживания. Сводит строки «отложено в av-dev:code-deep-review» в одну секцию отчёта. Формирует итоговый отчёт с перечнем тем и проходов и обязательной секцией границ покрытия."
|
||||
tools: Read, Grep, Glob, Bash, Write
|
||||
model: opus
|
||||
color: yellow
|
||||
@@ -28,7 +28,7 @@ color: yellow
|
||||
инструмент сверки: ты единственный, кто видит и то, что заявлено, и то, что
|
||||
пришло.
|
||||
|
||||
**Откуда перечень приходит, зависит от режима, и режимов два.**
|
||||
**Откуда перечень приходит, зависит от того, кто тебя позвал.**
|
||||
|
||||
- **По change** — обычный прогон цикла задачи. Перечень постоянный, он живёт в
|
||||
конвейере (`av-dev:code-review`, раздел «Состав прогона») и на каждой задаче
|
||||
@@ -38,6 +38,12 @@ color: yellow
|
||||
дельта-спек нет, и перечень **фиксирован сценарием** (`av-dev:code-resolve`,
|
||||
`references/maintain.md`). Тема `requirements` в нём отсутствует за отсутствием
|
||||
предмета.
|
||||
- **Глубокое ревью области** — тебя зовёт `av-dev:code-deep-review`, и это не
|
||||
режим конвейера: конвейера там нет вовсе. Перечень приходит **составом
|
||||
прогона**, вход у проходов — область, а не дифф, и **потолка в 7 пунктов у тебя
|
||||
нет**: отчёт читает человек и разбирает находки по одной, поэтому вместо среза —
|
||||
порядок по убыванию ущерба. Остальные шаги идут как обычно, включая оракул и
|
||||
границы покрытия.
|
||||
|
||||
Перечень цикла задачи — помеченная копия; дом её в конвейере, правится он, а не
|
||||
этот устав:
|
||||
|
||||
@@ -12,6 +12,12 @@
|
||||
неё не осталось ничего — так и должно быть: перечень описывает то, что ветвится
|
||||
сегодня.
|
||||
|
||||
**Трёх осей он не досчитывал и в обратную сторону.** Глубина темы, разметка
|
||||
действия и род правки документа ветвили поведение годами, а в перечне их не было:
|
||||
каждая живёт в своём скилле, и оттуда её видно, а отсюда — нет. Ровно за этим
|
||||
перечень и заведён: вопрос «а не задаёт ли это глубину ревью» задают из скилла,
|
||||
который ревью не ведёт.
|
||||
|
||||
**Ось — это закрытый перечень значений, по которому что-то ветвится.** Признак
|
||||
проверяемый, и он отсекает похожее: темы ревью и документы проекта — списки
|
||||
**открытые**, их пополняет проект, и перечень в плагине протух бы на первом же
|
||||
@@ -27,6 +33,9 @@
|
||||
| форма постановки | запись каталога · текст | `code-resolve/SKILL.md`, «Вход» |
|
||||
| сценарий | решение · обслуживание · разведка | `code-resolve/SKILL.md`, «Развилка» |
|
||||
| режим прогона | по change · без change | здесь, ниже |
|
||||
| род правки документа | отражение · новое | `doc-sync/SKILL.md`, «Два рода правок» |
|
||||
| глубина темы | сверка · разбор · доказательство | `code-review/SKILL.md`, таблица тем |
|
||||
| разметка действия | инлайн · развилка | `code-review/SKILL.md`, «Что происходит с находками» |
|
||||
| категория документа | тема · источник темы · процессный | `canon/references/canon.md` |
|
||||
| severity находки | `critical` `major` `minor` `nit` | `code-review/references/finding-contract.md` |
|
||||
| коды выхода | 0 1 2 3 4 | здесь, ниже |
|
||||
@@ -55,6 +64,11 @@
|
||||
| режим прогона | состав проходов и саму возможность запуска прохода | `code-review/SKILL.md`, «Прогон без change» |
|
||||
| категория документа | заводит ли документ направление проверки | `canon.md`, «Три категории» |
|
||||
| severity | что с находкой делают дальше | `code-review/SKILL.md`, «Что происходит с находками» |
|
||||
| род правки | спрашивают ли человека перед письмом в документ | `doc-sync/SKILL.md`, «Два рода правок» |
|
||||
| глубина темы | что проход делает с домом темы и какой потолок у находок | `code-review/SKILL.md`, таблица тем |
|
||||
| разметка действия | чинится находка молча или уходит человеку вопросом | `code-review/SKILL.md`, «Что происходит с находками» |
|
||||
| разметка действия | возвращается ли прогон на чекпоинт — **не задаёт**: возврат старше развилки и решается признаком «меняются ли дельта-спеки» | `code-resolve/references/solve.md`, шаг 5 |
|
||||
| сценарий | какова доля отражения в синке: обслуживание двигает факты и потому спрашивает редко | `code-resolve/references/maintain.md`, шаг 5 |
|
||||
|
||||
**Четыре клетки пусты, и это сказано намеренно, а не забыто.**
|
||||
|
||||
@@ -65,6 +79,11 @@
|
||||
нет. Значит, документ, заведённый проектом как тема, на обслуживании не смотрит
|
||||
никто, и строкой это нигде не называется.
|
||||
|
||||
**Род правки × severity и × режим прогона.** Не влияет ни туда, ни обратно: род
|
||||
правки — свойство того, что пишется в документ, и с находкой ревью он не
|
||||
встречается. Находка, доехавшая до конвенции, меняет род не сама по себе, а тем,
|
||||
что становится новой нормой, — и спрашивается тогда как всякое новое.
|
||||
|
||||
**Стадия проекта × режим прогона.** Не влияет: режим выбирает сценарий. Прогон
|
||||
обслуживания на стройке — обычное дело (первые шаги плана заводят гейт и сборку),
|
||||
и идёт он там так же, как на доработке.
|
||||
|
||||
@@ -56,7 +56,7 @@ LEGACY_TASKS = ".tasks.json"
|
||||
|
||||
# Версия раскладки — одна на плагин. Журнал версий — references/changelog.md
|
||||
# скилла `canon`, повышает его операция `upgrade`.
|
||||
VERSION = 4
|
||||
VERSION = 5
|
||||
|
||||
VERSION_KEY = "version"
|
||||
|
||||
|
||||
@@ -340,7 +340,12 @@ kebab-case.** Причина не эстетическая: имя файла с
|
||||
проекте нет дома, сюда не пишется: её и так называет план каждого прогона.
|
||||
|
||||
**Журнал дефектов:** запись на каждый воспроизведённый дефект с пометкой
|
||||
**проскочил / пойман ревью**. Проскочившие — проверочный набор для калибровки конвейера,
|
||||
**проскочил / пойман ревью**. Запись — новое, и заводится она по слову человека
|
||||
(`av-dev:doc-sync`, «Два рода правок»): «на каждый» задаёт **обязанность
|
||||
предложить**, а не право записать молча. Человек отказал — записи нет, и
|
||||
калибровка конвейера по этому дефекту не состоится; это его решение и его цена.
|
||||
|
||||
Проскочившие — проверочный набор для калибровки конвейера,
|
||||
выборка по пометке. Пойманные с оракулом — лучшая опора для прохода: проектные,
|
||||
воспроизводимые, однажды оказавшиеся правдой.
|
||||
|
||||
@@ -555,12 +560,10 @@ version = 1 # версия раскладки
|
||||
|
||||
[docs]
|
||||
migrations = "internal/store/migrations" # если БД есть
|
||||
healthcheck_last = "a1b2c3d" # сверка документов: коммит прошлого прогона
|
||||
|
||||
[tasks]
|
||||
dir = "tasks" # каталог задач от корня репозитория
|
||||
|
||||
[healthcheck]
|
||||
last = "a1b2c3d" # сверка документов: коммит прошлого прогона
|
||||
```
|
||||
|
||||
`version` — версия раскладки, под которую проект приведён, целым числом:
|
||||
@@ -571,13 +574,18 @@ last = "a1b2c3d" # сверка документов: ко
|
||||
делает сверку с `database.md`. `[tasks]` — где лежит каталог задач и как названы
|
||||
его части; состав ключей описывает скилл `task-track`.
|
||||
|
||||
`[healthcheck] last` — коммит, на котором в последний раз проходила сверка
|
||||
`[docs] healthcheck_last` — коммит, на котором в последний раз проходила сверка
|
||||
документов; ставит его сам `av-dev:doc-healthcheck` последним шагом прогона, а
|
||||
читает `av-dev:doc-sync`, чтобы сосчитать задачи, сделанные с тех пор. **Ключ
|
||||
необязательный и в скелете его нет намеренно**: у нового проекта сверок не было,
|
||||
и пустое значение врало бы про это меньше, чем отсутствие ключа, только на вид.
|
||||
Отсутствие читается однозначно — «не сверялись ни разу».
|
||||
|
||||
Секции он достался по смыслу: `[docs]` — настройки проверок документов, а сверка
|
||||
документов и есть такая проверка. Своя секция верхнего уровня стоила бы правки
|
||||
общего читателя `shared/config.py` и сделала бы файл, объявленный «версией и
|
||||
настройками», хранилищем состояния.
|
||||
|
||||
**Формат TOML взят ради комментариев.** Файл лежит в репозитории проекта, и
|
||||
человек, открывший его через полгода, обязан прочитать в нём, что означает
|
||||
число. JSON комментариев не знает, и объяснение приходилось держать в другом
|
||||
@@ -592,6 +600,20 @@ last = "a1b2c3d" # сверка документов: ко
|
||||
читаются: два дома для одной версии расходятся молча. Увидев их, `docs.py` и
|
||||
`tasks.py` говорят «прежняя раскладка» и зовут `upgrade` — версия 1 журнала.
|
||||
|
||||
Ключей будет больше по мере роста проверок; неизвестный ключ `docs.py`
|
||||
игнорирует, отсутствующий — считает «проверка неприменима» и говорит об этом
|
||||
строкой, а не молчит.
|
||||
Ключей будет больше по мере роста проверок, но **заводятся они только вместе с
|
||||
правкой скрипта**: неизвестный ключ — не безмолвный пропуск, а **отказ кодом
|
||||
3**. Верхний уровень стережёт `shared/config.py` (`TOP_KEYS`), секцию `[docs]` —
|
||||
`docs.py` (`DOCS_KEYS`), секцию `[tasks]` — `tasks.py`. Довод у отказа
|
||||
проверяемый: ключ, положенный не в ту секцию, при молчаливом пропуске не значит
|
||||
ничего — проверка объявляет себя неприменимой, отчёт выходит зелёным, и на месте
|
||||
настройки оказывается тишина.
|
||||
|
||||
**Здесь это правило однажды соврало, и цена была немедленной.** Абзац обещал, что
|
||||
неизвестный ключ игнорируется; по этому обещанию скилл сверки завёл себе секцию
|
||||
`[healthcheck]` верхнего уровня — и первый же её прогон сделал бы нерабочими
|
||||
`docs.py`, `tasks.py` и гейт проекта, который их зовёт. Отсюда и порядок: **новый
|
||||
ключ заводится правкой константы в скрипте-владельце, и только потом появляется
|
||||
здесь**.
|
||||
|
||||
**Отсутствующий** ключ — другое дело: он значит «проверка неприменима», и скрипт
|
||||
говорит об этом строкой, а не молчит.
|
||||
|
||||
@@ -22,6 +22,44 @@
|
||||
|
||||
---
|
||||
|
||||
## Версия 5 — 2026-08-23
|
||||
|
||||
**Метка задачи снята из процесса целиком**, и вместе с ней — подраздел «Триггеры
|
||||
метки» в `docs/review.md`. Состав прогона ревью стал постоянным: он один и тот же
|
||||
на всякой задаче, выбирать нечего, и признаки, по которым метка поднималась,
|
||||
перестали что-либо решать. На месте подраздела — **«Когда звать глубокое ревью»**:
|
||||
те же наблюдения проекта, но адресованные другому решению — звать ли
|
||||
`av-dev:code-deep-review` по области кода.
|
||||
|
||||
**Что переехало в проекте.** Скелет `docs/review.md`, раздел настройки конвейера:
|
||||
подраздел «Триггеры метки» заменён подразделом «Когда звать глубокое ревью» —
|
||||
**двумя списками**: области, которые смотрят целиком (узлы с частым возвратом,
|
||||
места с историей инцидентов, код под дорогое решение), и **необратимое здесь** —
|
||||
что в этом проекте после мерджа не откатывается обратной правкой. Второй список
|
||||
работает и в цикле задачи: находка в таком месте уходит человеку развилкой, а не
|
||||
чинится молча. Само правило — в [canon.md](canon.md), раздел `review.md`.
|
||||
|
||||
**Что сделать проекту.**
|
||||
|
||||
1. **Переписать подраздел в `docs/review.md`.** Заголовок «Триггеры метки»
|
||||
становится «Когда звать глубокое ревью», содержимое — два списка выше.
|
||||
Признаки, годные только для выбора метки («больше N файлов», «затронуто больше
|
||||
одного слоя»), выбрасываются: состава прогона они не меняют. Что из прежнего
|
||||
списка называло **необратимое место** — переносится во второй список дословно.
|
||||
2. **Пройти по документам** — `grep -rniE "small|medium|large|метк" docs/`.
|
||||
Найденное в `review.md`, `conventions/` и `adr/` правится по смыслу: описание
|
||||
прошлого решения остаётся как свидетельство, действующая инструкция —
|
||||
переписывается или снимается.
|
||||
3. **Поднять версию** — `docs.py bump`, последним шагом.
|
||||
4. `docs.py check` — до отсутствия дрейфа.
|
||||
|
||||
**Чего делать не надо.** Заводить ключ `[docs] healthcheck_last` руками: он
|
||||
необязательный и появится сам первым прогоном `av-dev:doc-healthcheck`. Править
|
||||
прошлые записи журналов и архивные change — тоже: метка, стоявшая в них, верна
|
||||
как свидетельство о том дне.
|
||||
|
||||
---
|
||||
|
||||
## Версия 4 — 2026-08-13
|
||||
|
||||
Слово **провенанс** снято из словаря языка проектных текстов и заменено русским.
|
||||
|
||||
@@ -296,7 +296,15 @@ def read_config(root: Path, rep: Report) -> dict:
|
||||
|
||||
# Ключи секции `[docs]`. Секцию знает этот скрипт, а не общий читатель: ключ
|
||||
# заводится вместе с проверкой, которая его читает.
|
||||
DOCS_KEYS = ("migrations",)
|
||||
#
|
||||
# `healthcheck_last` — коммит прошлой сверки документов; пишет его скилл
|
||||
# `av-dev:doc-healthcheck`, читает `av-dev:doc-sync`, чтобы сосчитать задачи с
|
||||
# тех пор. Здесь он стоит **только чтобы файл не отвергли**: неизвестный ключ —
|
||||
# отказ кодом 3, то есть ключ, заведённый скиллом мимо этой константы, сделал бы
|
||||
# нерабочими и `docs.py`, и `tasks.py`, и гейт проекта, который их зовёт.
|
||||
# Проверки, читающей его, у скрипта нет и не предполагается: значение — след
|
||||
# работы человека, а не настройка.
|
||||
DOCS_KEYS = ("migrations", "healthcheck_last")
|
||||
|
||||
|
||||
def docs_cfg(cfg: dict) -> dict:
|
||||
|
||||
@@ -31,8 +31,8 @@ description: "Глубокое ревью области кода — не за
|
||||
**Вход этому скиллу копят проходы цикла.** Строка «отложено в
|
||||
`av-dev:code-deep-review`» в границах покрытия называет тему, место и запуск,
|
||||
которым это проверяется; триаж сводит такие строки в отдельную секцию отчёта.
|
||||
Второй источник — сигнал «это изменение просит глубокого ревью», который подаёт
|
||||
`review-code`.
|
||||
Второй источник — сигнал «это изменение просит глубокого ревью»: его подаёт
|
||||
`review-code` всегда и `review-basics`, когда запускается.
|
||||
|
||||
## Когда звать
|
||||
|
||||
@@ -119,16 +119,20 @@ capability — одним адресом или несколькими. Скил
|
||||
|
||||
## Состав прогона
|
||||
|
||||
Состав **постоянный**, и глубина у всех проходов одна — **доказательство**.
|
||||
Постоянен и состав цикла задачи, но он другой и мельче: разница между скиллами не
|
||||
в старательности, а в том, что здесь запускают, меряют и строят путь.
|
||||
Состав **постоянный**, но глубина у проходов **разная, и это не небрежность**.
|
||||
Доказательство дают те двое, что держат машину: `review-adversary` прогоняет
|
||||
падающий тест, `review-ops` снимает числа замером. `review-architecture` и
|
||||
`review-code` машину не держат — они дают **разбор на входе шире диффа**, и
|
||||
выдать доказательство им нечем. Постоянен и состав цикла задачи, но он другой и
|
||||
мельче: разница между скиллами не в старательности, а в том, что здесь запускают,
|
||||
меряют и строят путь.
|
||||
|
||||
| Проход | Тема | Что делает |
|
||||
|---|---|---|
|
||||
| `review-adversary` | `security` | строит путь и **прогоняет** падающий тест |
|
||||
| `review-ops` | `operations` | снимает числа замером: удержание, рост, деградация |
|
||||
| `review-architecture` | `architecture` | концептуальная целостность на входе шире диффа |
|
||||
| `review-code` | `conventions` и техника | читает код **как код**, целиком, а не диффом |
|
||||
| `review-code` | `conventions`, техника, инварианты | читает код **как код**, целиком, а не диффом; потолков здесь нет |
|
||||
| `review-triage` | — | единственный сток: дедуп, оракулы, потолок |
|
||||
|
||||
**Гейта здесь нет, и это не пропуск.** Гейт судит изменение — красный он или
|
||||
@@ -202,6 +206,12 @@ capability — одним адресом или несколькими. Скил
|
||||
владеет этим документом. В следе: область, состав проходов, что взято задачами,
|
||||
что отвергнуто и почему, что проверить было невозможно.
|
||||
|
||||
**Второго вопроса здесь не задают, хотя `review.md` — документ рода «новое»**
|
||||
(`av-dev:doc-sync`, «Два рода правок»): слово по каждой находке человек уже сказал
|
||||
в разборе, и след цитирует ровно его решения. Правило то же, что у сужения
|
||||
проверок: спрашивается новое, которое заметил ты, а не то, что человек только что
|
||||
решил вслух.
|
||||
|
||||
Без этого следа второй прогон по той же области начнётся с нуля и предложит те же
|
||||
находки, от которых человек уже отказался, — а отказ, не оставивший записи,
|
||||
неотличим от непойманного.
|
||||
|
||||
@@ -43,8 +43,8 @@ context: |
|
||||
Пересказа этих документов здесь нет намеренно: второй дом факта расходится с
|
||||
первым молча, и заметно это становится в предложении, которое уже написано.
|
||||
|
||||
Ревью: правило выбора метки и состав проходов здесь не пересказываем — их дом
|
||||
скилл av-dev:code-review, проектная настройка — docs/review.md.
|
||||
Ревью: состав проходов и глубину тем здесь не пересказываем — их дом скилл
|
||||
av-dev:code-review, проектная настройка — docs/review.md.
|
||||
|
||||
Конвенции кода: механизированное проверяет гейт, прозой остаётся
|
||||
docs/conventions/. Ни состав шагов гейта, ни перечень конвенций здесь не
|
||||
|
||||
@@ -303,7 +303,7 @@ flowchart TD
|
||||
| правки по находкам триажа, помеченным `инлайн` | [solve](references/solve.md), шаг 5; [maintain](references/maintain.md), шаг 4 |
|
||||
| правка оснастки в сценарии обслуживания | [maintain](references/maintain.md), шаг 2 |
|
||||
| архивация change и отражение в документах — `opsx:archive` и `av-dev:doc-sync` | [solve](references/solve.md), шаг 6, такт 1; [maintain](references/maintain.md), шаг 5 |
|
||||
| письмо одобренного нового и задачи из урожая | [solve](references/solve.md), шаг 6, такт 3 |
|
||||
| письмо одобренного нового в документы канона | [solve](references/solve.md), шаг 6, такт 3; [maintain](references/maintain.md), шаг 5 |
|
||||
|
||||
**Остальное остаётся оркестратору, и перечень закрыт:** выбор сценария и стопы,
|
||||
чекпоинт, вызовы `av-dev:code-review`, `av-dev-git:commit` и `av-dev:task-track`,
|
||||
@@ -393,11 +393,21 @@ flowchart TD
|
||||
второй раз — делай сам и **скажи это строкой доклада**: прогон стоил дороже, чем
|
||||
должен, и это факт для человека, а не стоп.
|
||||
|
||||
## Автономность и плановый стоп
|
||||
## Автономность и плановые стопы
|
||||
|
||||
**У двух сценариев ровно один плановый стоп**, и стоят они в разных местах:
|
||||
у решения — объяснение сразу после предложения и до кода, у разведки — варианты
|
||||
до первого написанного требования. Правило вокруг них общее.
|
||||
**Стопов у сценария не больше двух, и каждый — про решение человека, а не про
|
||||
ход работ.**
|
||||
|
||||
| Сценарий | Стоп до письма | Стоп после письма |
|
||||
| --- | --- | --- |
|
||||
| решение | чекпоинт: объяснение после предложения и до кода | реплика шага 6: что из найденного заводится |
|
||||
| разведка | чекпоинт вариантов до первого написанного требования | — исход и так уезжает в документы по выбранному варианту |
|
||||
| обслуживание | — планового нет | реплика шага 5, и только если появилось новое |
|
||||
|
||||
**Второй стоп короче первого и часто не случается вовсе.** Первый решает форму
|
||||
решения, и без ответа работа не идёт дальше; второй решает, что из найденного
|
||||
переживёт задачу, и при пустом списке нового его просто нет. Правило вокруг обоих
|
||||
общее.
|
||||
|
||||
**У обслуживания планового стопа нет вовсе, и это следствие, а не поблажка.**
|
||||
Один стоп с ожиданием ответа у него всё же есть — по найденной дельта-спеке, — но
|
||||
@@ -529,12 +539,14 @@ change, у второго — сверенный состав гейта и си
|
||||
текущем worktree и на текущей ветке: не делай `git checkout`/`switch`, не
|
||||
создавай веток, не пушь.
|
||||
- Прогон проходит **не больше одного** чекпоинта, и это норма, а не упрощение.
|
||||
Два стопа за одну задачу — цена незнания способа, и платится она двумя
|
||||
Два чекпоинта за одну задачу — цена незнания способа, и платится она двумя
|
||||
прогонами, а не одним длинным. У обслуживания чекпоинта нет ни одного, и это
|
||||
тоже норма: там нечего решать.
|
||||
тоже норма: там нечего решать. Реплика о новом чекпоинтом не является и этого
|
||||
счёта не касается — она решает не форму решения, а судьбу находок.
|
||||
- Держи вызывающего в цикле короткими репликами на переходах фаз, но не проси
|
||||
подтверждать механику: чекпоинт — единственное место, где ждут ответа, а в
|
||||
обслуживании такого места нет вовсе.
|
||||
подтверждать механику. Мест, где **ждут ответа**, ровно два, и оба названы в
|
||||
«Автономности»: чекпоинт до кода и реплика о новом после него. Третьего нет ни
|
||||
в одном сценарии, и заводить его нельзя.
|
||||
- **Сценарий назван вслух — значит, его можно оспорить.** Человек, увидевший в
|
||||
первой реплике «иду разведкой, потому что способа не видно», поправит выбор
|
||||
одной фразой; молча выбранный сценарий он поправит через полчаса работы.
|
||||
|
||||
@@ -68,7 +68,7 @@
|
||||
|
||||
## Дельта нашлась по ходу — стоп, и у него свой порядок
|
||||
|
||||
Признак тот же, что на шаге 7 сценария решения: **меняется ли то, что записано в
|
||||
Признак тот же, что у отработки ревью в решении (шаг 5): **меняется ли то, что записано в
|
||||
`openspec/specs/`**. Обнаружилось, что меняется, — работа перестала быть
|
||||
обслуживанием в ту же секунду, и продолжать её нельзя: коммит обслуживания
|
||||
заявляет «поведение не менялось», а оно меняется.
|
||||
@@ -153,9 +153,12 @@
|
||||
решать, вырождается в обряд одобрения и обесценивает те стопы, где решать есть
|
||||
что.
|
||||
|
||||
**Место, где ответа всё же ждут, одно, и плановым оно не является** — стоп по
|
||||
найденной дельте (раздел «Дельта нашлась по ходу»). Через него проходят не все
|
||||
прогоны, а только те, где задача оказалась не тем, чем объявлена.
|
||||
**Мест, где ответа всё же ждут, два, и через оба проходят не все прогоны.**
|
||||
Первое — стоп по найденной дельте (раздел «Дельта нашлась по ходу»), и плановым
|
||||
он не является: через него идут те прогоны, где задача оказалась не тем, чем
|
||||
объявлена. Второе — **реплика о новом на шаге 5**, и она случается, только если
|
||||
обслуживание завело в документах что-то, чего не было: запрет или инвариант.
|
||||
Обычный прогон обслуживания не проходит ни через одно из двух.
|
||||
|
||||
**Правило необратимого при этом действует полностью** (SKILL.md, «Когда
|
||||
спрашивать вне чекпоинта»), и здесь оно опаснее, чем кажется. Единственный
|
||||
@@ -365,8 +368,14 @@ ADR: список источников канон закрыл двумя — а
|
||||
|
||||
Отработка — как в решении: помеченное `инлайн` чинит **агент** (SKILL.md, «Кто
|
||||
пишет»), находки уходят ему дословно с оракулом, гейт после правок гоняет он же,
|
||||
логировать их не надо; `развилка` — вопросом в запись, и агенту она не отдаётся. Отложенные находки собери в секцию
|
||||
доклада `Урожай`; задачи из него заводит `av-dev:task-track`, не ты.
|
||||
логировать их не надо; `развилка` — вопросом в запись, и агенту она не отдаётся.
|
||||
Отложенные находки собери в секцию доклада `Урожай`.
|
||||
|
||||
**Задачи из урожая — по слову человека, и спрашивается это репликой шага 5**,
|
||||
вместе с новым в документах: правило общее для всех прогонов конвейера
|
||||
(`av-dev:code-review`, «Что происходит с находками дальше»), и обслуживание не
|
||||
исключение. Сказал «заводим» — зовёшь `av-dev:task-track` сам, сценарий «задачи
|
||||
из ревью и аудита»; не сказал — урожай остаётся строками доклада.
|
||||
|
||||
### 5. Синк документации — главный шаг этого сценария, и делает его агент
|
||||
|
||||
@@ -385,11 +394,24 @@ ADR: список источников канон закрыл двумя — а
|
||||
предлагается** (дом — раздел «Два рода правок» скилла `av-dev:doc-sync`). Здесь
|
||||
оно почти ничего не стоит: обслуживание двигает **факты** — команды, шаги гейта,
|
||||
зависимости поимённо, пути, имя ветки, числа настроек, — а факт в документе,
|
||||
разошедшийся с кодом, это отражение по определению. Реплика человеку на этом
|
||||
сценарии редка, и поводов у неё два: **новый запрет или инвариант в `CLAUDE.md`**
|
||||
и **сужение проверок в `review.*`**. Второе спрашивать не надо — проверки сузил
|
||||
человек, слово по ним сказано; первое надо, потому что запрет свяжет все будущие
|
||||
задачи. Нового нет — реплики нет, и шаг кончается возвратом агента.
|
||||
разошедшийся с кодом, это отражение по определению.
|
||||
|
||||
**Повод для реплики у этого сценария один — новый запрет или инвариант в
|
||||
`CLAUDE.md`**: он свяжет все будущие задачи, и заводить его молча нельзя.
|
||||
Сужение проверок в `review.*` поводом не является, хотя тоже новое: проверки
|
||||
сузил человек, и слово по ним уже сказано (`av-dev:doc-sync`, «Два рода правок»).
|
||||
К этому же поводу примыкает урожай ревью с шага 4 — спрашиваются они одной
|
||||
репликой, а не двумя.
|
||||
|
||||
**Нового нет — реплики нет**, и шаг кончается возвратом агента; так идёт
|
||||
большинство прогонов обслуживания.
|
||||
|
||||
**Реплика была — идёт второй заход тем же агентом**, и на нём висит то же, что в
|
||||
решении: письмо одобренного, вычитка `doc-wording` по всей пачке и гейт до
|
||||
зелёного. Первый заход снимает их с себя ровно тогда, когда вернул непустой
|
||||
список предложений, — порядок и его довод описаны в [solve.md](solve.md), шаг 6.
|
||||
Задачи из урожая при этом заводишь **ты сам** вызовом `av-dev:task-track`, а не
|
||||
агент: индексы учёта правит тот, кто коммитит.
|
||||
|
||||
**Здесь этот шаг весит больше, чем в решении, и вот почему.** Обслуживание не
|
||||
меняет поведения — значит, почти всё, что оно меняет, это документация: команды,
|
||||
@@ -471,7 +493,11 @@ ADR: список источников канон закрыл двумя — а
|
||||
выдуманному пользователю;
|
||||
- **состав гейта до и после**, если правка его трогала; не сверялся — почему;
|
||||
- по каждому критерию приёмки: **оракул и наблюдаемый исход**;
|
||||
- **`Урожай`** — отложенные находки списком;
|
||||
- **`Урожай`** — отложенные находки списком и **что человек по нему решил**;
|
||||
- **что заведено нового в документах** и что предложено и отвергнуто — по именам
|
||||
записей; отказ виден только здесь;
|
||||
- **сигнал сверки** — строка синка о том, сколько задач сделано с прошлого
|
||||
прогона `av-dev:doc-healthcheck`, либо что сверки не было ни разу;
|
||||
- **строка границ покрытия**: план сценария фиксирован; темы `requirements` в нём
|
||||
нет — её не смотрел никто, а `security` и `architecture` смотрелись только
|
||||
против записанных инвариантов, и то если шёл проход `code`.
|
||||
|
||||
@@ -398,8 +398,8 @@ git и читается диффом, а второй стоп на каждой
|
||||
## Доклад разведки
|
||||
|
||||
Общая форма доклада — в SKILL.md; у разведки он свой, потому что докладывать
|
||||
нечего из того, о чём спрашивают решение (ни метки ревью, ни критериев приёмки,
|
||||
ни архивного change). Коротко, и в нём обязательно:
|
||||
нечего из того, о чём спрашивают решение: ни критериев приёмки, ни архивного
|
||||
change, ни исхода ревью — кода она не писала. Коротко, и в нём обязательно:
|
||||
|
||||
- **исход** одним из четырёх слов;
|
||||
- **вопрос и ответ** — по фразе на каждое. Ответ, который не сворачивается во
|
||||
@@ -408,6 +408,8 @@ git и читается диффом, а второй стоп на каждой
|
||||
- **какие задачи заведены и уточнены** — слагами;
|
||||
- **что вычитано и чем** — пачка документов и пачка записей, каждая со своими
|
||||
проходами; не вычитанное называется прямо, вместе с причиной;
|
||||
- **сигнал сверки** — строка синка о том, сколько задач сделано с прошлого
|
||||
прогона `av-dev:doc-healthcheck`, либо что сверки не было ни разу;
|
||||
- **что осталось неизвестным** и чего это стоит: разведка без этой строки
|
||||
сообщает «выяснено», не сообщая, что именно осталось не выяснено;
|
||||
- **рамки**, если они ограничили работу: докуда копали и почему остановились.
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
# Сценарий «решение»
|
||||
|
||||
Способ решения известен, спорно только как. Проводит задачу от постановки до
|
||||
закрытия и **пишет код**: цикл Spec Driven Development с одним плановым стопом —
|
||||
объяснением сразу после предложения.
|
||||
закрытия и **пишет код**: цикл Spec Driven Development с двумя плановыми стопами —
|
||||
объяснением сразу после предложения и репликой о новом после ревью.
|
||||
|
||||
Сценарий выбирается развилкой на входе скилла ([SKILL.md](../SKILL.md), раздел
|
||||
«Развилка: какой сценарий») и называется вслух первой репликой. Здесь только его
|
||||
@@ -30,7 +30,7 @@ flowchart TD
|
||||
s5["5. ревью кода — постоянный состав<br/>+ отработка замечаний агентом"]
|
||||
s6["6. opsx:archive + отражение в документах —<br/>одним агентом"]
|
||||
s6q(["РЕПЛИКА: что заводим из нового —<br/>ADR, конвенция, задачи из урожая"])
|
||||
s6b["6b. письмо одобренного и задачи —<br/>тем же агентом"]
|
||||
s6b["такт 3: задачи — оркестратором,<br/>документы, вычитка и гейт — агентом"]
|
||||
s7["7. коммит работы — av-dev-git:commit"]
|
||||
s8["8. закрыть задачу — av-dev:task-track,<br/>вторым коммитом учёта"]
|
||||
|
||||
@@ -133,8 +133,9 @@ flowchart TD
|
||||
|
||||
### 3. Чекпоинт: объяснение
|
||||
|
||||
**Остановись и объясни человеку, что происходит.** Единственный плановый стоп
|
||||
этого сценария, и он обязателен для всякой задачи.
|
||||
**Остановись и объясни человеку, что происходит.** Первый из двух плановых стопов
|
||||
сценария, и в отличие от второго он обязателен для всякой задачи: реплика шага 6
|
||||
случается только тогда, когда есть что заводить, а чекпоинт — всегда.
|
||||
|
||||
Он стоит **сразу после предложения и до кода** — намеренно. Раньше между
|
||||
`propose` и чекпоинтом стояла стадия ревью дизайна, и человек читал объяснение,
|
||||
@@ -287,10 +288,10 @@ flowchart TD
|
||||
найденного заводим») стоили бы человеку двух переключений вместо одного. Сюда
|
||||
урожай складывается, а не выносится.
|
||||
|
||||
Сказал «заводим» — зовёт `av-dev:task-track` агент шага 6, у него на этот вход
|
||||
отдельный сценарий «задачи из ревью и аудита»: своя нарезка, свой формат, свои
|
||||
правила дублей, и передавать находку туда надо дословно. Не сказал — урожай
|
||||
остаётся строками доклада, и это исход, а не потеря.
|
||||
Сказал «заводим» — зовёшь `av-dev:task-track` **ты сам**, тактом третьим шага 6:
|
||||
у него на этот вход отдельный сценарий «задачи из ревью и аудита» — своя нарезка,
|
||||
свой формат, свои правила дублей, и находка передаётся дословно. Не сказал —
|
||||
урожай остаётся строками доклада, и это исход, а не потеря.
|
||||
|
||||
**Молча беклог не наполняется.** Очередь работ ведёт человек, и задача, заведённая
|
||||
за него по ходу чужого прогона, отнимает у него ровно то решение, ради которого
|
||||
@@ -360,8 +361,13 @@ flowchart TD
|
||||
том скилле; гейт до зелёного доводит агент, потому что красный гейт остановил бы
|
||||
коммит следующим шагом — документы у многих проектов он проверяет.
|
||||
|
||||
**Возврат — чек-лист, адреса тронутого, исход валидации и исход гейта, если он
|
||||
гонялся.**
|
||||
**Отложенное этим тактом обязано вернуться.** Оттого такт третий идёт **всякий
|
||||
раз, когда была реплика** — в том числе когда человек не одобрил ничего: на нём
|
||||
висят вычитка и гейт, которые первый такт с себя снял. Пропустить его на отказе
|
||||
значило бы уехать в коммит с невычитанной правкой и непрогнанным гейтом.
|
||||
|
||||
**Возврат — чек-лист, адреса тронутого, исход валидации, строка сигнала сверки и
|
||||
исход гейта, если он гонялся.**
|
||||
Чек-лист уезжает в доклад целиком, и переписывать его своими словами нельзя —
|
||||
это единственный след того, что каждый документ был назван.
|
||||
|
||||
@@ -405,17 +411,30 @@ flowchart TD
|
||||
и второй абзац уговоров превращает реплику в чтение. Человек вправе ответить
|
||||
«ничего» — это исход, а не потеря: находки остаются строками доклада.
|
||||
|
||||
#### Такт третий — тот же агент: письмо одобренного
|
||||
#### Такт третий — задачи оркестратором, документы агентом
|
||||
|
||||
Запускается **только если человек что-то одобрил**. В задании:
|
||||
**Идёт всякий раз, когда была реплика**, и порядок в нём жёсткий.
|
||||
|
||||
**Сначала задачи — их заводишь ты, а не агент.** Человек сказал «заводим» — зови
|
||||
Skill `av-dev:task-track`, у него на этот вход отдельный сценарий «задачи из ревью
|
||||
и аудита»: своя нарезка, свой формат, свои правила дублей. Находка передаётся
|
||||
**дословно, вместе с оракулом**. Согласован промоут находки в конвенцию — тем же
|
||||
вызовом заводится **задача `chore` на механизацию правила**: шаг 2 промоута
|
||||
(конфиг линтера, сканер, приведение кода к зелёному) в хвост чужой задачи не
|
||||
помещается (`av-dev:code-review`, `references/promote.md`).
|
||||
|
||||
**Заведение задач агенту не отдаётся ни в одном сценарии** — по той же причине,
|
||||
по какой ему не отдаются коммит и закрытие: оно правит индексы учёта, а перечень
|
||||
работ ведёт человек. Правило и его дом — SKILL.md, «Кто пишет».
|
||||
|
||||
**Потом документы — их пишет тот же агент, что шёл тактом первым.** В задании:
|
||||
|
||||
- **одобренные записи дословно** — формулировка, источник, основание; сочинять
|
||||
заново нельзя, ADR цитирует решение из архивного `design.md`, а не пересказывает
|
||||
его;
|
||||
- **задачи из урожая** — вызовом `av-dev:task-track`, сценарий «задачи из ревью и
|
||||
аудита», находка передаётся дословно вместе с оракулом;
|
||||
его. Человек не одобрил ничего — писать нечего, и это законный вход;
|
||||
- **вычитка** `doc-wording` по всей пачке правленого — и первого такта, и этого;
|
||||
- **гейт проекта до зелёного** после правок.
|
||||
- **гейт проекта до зелёного** после правок — он же увидит заведённые задачи,
|
||||
потому они и заводятся раньше.
|
||||
|
||||
**Отвергнутое не пишется никуда.** Ни в один документ, ни отдельной записью «от
|
||||
такого-то отказались»: журнала отвергнутого канон не держит, и заведение его
|
||||
@@ -493,11 +512,12 @@ change. Заводить запись задним числом, чтобы её
|
||||
тебя нет: состав прогона постоянный и сокращению не подлежит, перечень тем
|
||||
сверяется по исходу, непокрытое называется строкой, а расхождение с одобренным
|
||||
— отдельным пунктом доклада.
|
||||
- **Заведение задач из урожая ревью — не твоя работа и не работа этого прогона по
|
||||
умолчанию.** Отложенные находки отдаются **списком**, и в задачи их превращает
|
||||
`av-dev:task-track` — по слову человека, у него на этот вход отдельный сценарий
|
||||
«задачи из ревью и аудита». Каталога задач в
|
||||
проекте нет — урожай остаётся списком в докладе, и это говорится строкой.
|
||||
- **Заведение задач из урожая ревью не идёт по умолчанию.** Отложенные находки
|
||||
отдаются **списком**, и в задачи их превращает `av-dev:task-track` — по слову
|
||||
человека и вызовом от тебя, а не от агента: перечень работ ведёт человек, а
|
||||
индексы учёта правит тот же, кто коммитит. У скилла на этот вход отдельный
|
||||
сценарий «задачи из ревью и аудита». Каталога задач в проекте нет — урожай
|
||||
остаётся списком в докладе, и это говорится строкой.
|
||||
- **Стопов у сценария два, и оба про решения человека, а не про ход работ.**
|
||||
Чекпоинт шага 3 решает форму решения **до** кода; реплика шага 6 решает, что из
|
||||
найденного переживёт задачу. Между ними прогон идёт сам: правки инлайном чинятся
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: code-review
|
||||
description: "Конвейер ревью изменения, устроенный по темам: документ проекта либо заводит тему ревью, либо питает чужую тему источником, либо процессный и в ревью не читается вовсе. Ядро тем — requirements, autotests, conventions, architecture, security, operations; список тем открытый, свои темы проект заводит документом. Состав прогона постоянный, метки у него нет: гейт (autotests), сверка со спекой (specs), разбор кода и конвенций (code), триаж; приёмник тем (basics) идёт, когда у проекта есть свои темы. Цикл задачи проверяет корректность и механику против записанного критерия — дельта-спеки, конвенции, инварианты CLAUDE.md, вывод инструментов. Темы риска и устройства — security, operations, architecture — закрыты в цикле только сверкой с записанными инвариантами: их разбор, доказательство запуском и суждение о форме решения живут в скилле av-dev:code-deep-review, который идёт по области кода и время от времени. Порядок прогона — граф зависимостей: гейт открывает проходы с мнением, триаж — единственный сток. Находки по умолчанию чинятся инлайн и молча; человеку уходит только необратимое и то, что меняет дельта-спеки, а задачи из урожая заводятся по его слову. Проектная специфика приходит из документов канона проекта. Вызывается из скилла av-dev:code-resolve после apply. Второй вызов идёт от сценария обслуживания: без change, фиксированным планом (autotests, operations, плюс conventions, если тронут код)."
|
||||
description: "Конвейер ревью изменения, устроенный по темам: документ проекта либо заводит тему ревью, либо питает чужую тему источником, либо процессный и в ревью не читается вовсе. Ядро тем — requirements, autotests, conventions, architecture, security, operations; список тем открытый, свои темы проект заводит документом. Состав прогона постоянный, метки у него нет: гейт (autotests), сверка со спекой (specs), разбор кода и конвенций (code), триаж; приёмник тем (basics) идёт, когда у проекта есть свои темы. Цикл задачи проверяет корректность и механику против записанного критерия — дельта-спеки, конвенции, инварианты CLAUDE.md, вывод инструментов. Темы риска и устройства — security, operations, architecture — закрыты в цикле только сверкой с записанными инвариантами: их разбор, доказательство запуском и суждение о форме решения живут в скилле av-dev:code-deep-review, который идёт по области кода и время от времени. Порядок прогона — граф зависимостей: гейт открывает проходы с мнением, триаж — единственный сток. Находки по умолчанию чинятся инлайн и молча; человеку уходит только необратимое, трогающее инвариант CLAUDE.md и меняющее дельта-спеки, а задачи из урожая заводятся по его слову. Проектная специфика приходит из документов канона проекта. Вызывается из скилла av-dev:code-resolve после apply. Второй вызов идёт от сценария обслуживания: без change, фиксированным планом (autotests, operations, плюс conventions, если тронут код)."
|
||||
---
|
||||
|
||||
# Конвейер ревью
|
||||
@@ -188,7 +188,9 @@ description: "Конвейер ревью изменения, устроенны
|
||||
|
||||
**Проектная тема закрывается `basics`**, и только она. Именных проходов конечное
|
||||
число, а тем — сколько заведёт проект; приёмник обязателен, иначе открытость
|
||||
списка была бы обещанием без механизма. Темы **ядра** он не держит вовсе:
|
||||
списка была бы обещанием без механизма. Темы **ядра** он не держит **в цикле
|
||||
задачи** — на прогоне обслуживания план сценария даёт ему `operations`, и это
|
||||
единственное исключение (раздел «Прогон без change»). В цикле:
|
||||
`requirements` закрывает `specs`, `conventions` и технику — `code`, а риск и
|
||||
устройство — тот же `code` сверкой с инвариантами. Отсюда правило состава:
|
||||
**`basics` запускается тогда и только тогда, когда ему есть что принимать** — см.
|
||||
@@ -322,9 +324,12 @@ charter'а, а модель потом двигает калибровка, и
|
||||
|
||||
## Состав прогона — постоянный
|
||||
|
||||
**Ступени нумерованы и наружу не выходят.** Прогон ревью один, и зовёт его
|
||||
**Ступени нумерованы, и наружу выходит одна.** Прогон ревью один, и зовёт его
|
||||
`av-dev:code-resolve` после того, как код написан; членение внутри прогона —
|
||||
ступени, и знать их снаружи не нужно. Перечень осей процесса целиком —
|
||||
ступени, и знать их снаружи не нужно. Исключение единственное и названное:
|
||||
**ступень 1**, автотесты, — на неё ссылаются снаружи, потому что она умеет
|
||||
засчитать чужой прогон гейта по отпечатку дерева, и вызывающему надо знать, куда
|
||||
этот отпечаток едет. Перечень осей процесса целиком —
|
||||
[shared/axes.md](../../shared/axes.md).
|
||||
|
||||
**Состав не выводится ни из чего: он один и тот же на всякой задаче.** Гейт,
|
||||
@@ -487,7 +492,7 @@ flowchart TD
|
||||
|---|---|---|
|
||||
| `autotests` | да | запускает инструменты проекта — но он источник графа и один по построению |
|
||||
| `triage` | да | проверяет оракул `major` запуском — но он сток и тоже один |
|
||||
| `specs`, `code`, `basics`, `rubric` | нет | читают и рассуждают, ничего не исполняют |
|
||||
| `specs`, `code`, `basics` | нет | читают и рассуждают, ничего не исполняют |
|
||||
|
||||
**В цикле задачи цепочки за машину нет.** Оба прохода, что её держали —
|
||||
`adversary` и `ops`, — переехали в скилл `av-dev:code-deep-review`; там правило
|
||||
@@ -504,8 +509,10 @@ flowchart TD
|
||||
державшихся на таких замерах; у каждого проекта они свои и лежат в журнале
|
||||
`docs/review.md`.
|
||||
|
||||
Проект вправе пометить «держит машину» и другой проход — в `docs/review.md`,
|
||||
разделе настройки конвейера. Снимать пометку с перечисленных нельзя.
|
||||
Проект вправе пометить «держит машину» и другой проход — строкой в подразделе
|
||||
**«Недоступно проверке»** файла `docs/review.md`: своего подраздела у пометки нет,
|
||||
и заводить его канон не станет ради одного проекта. Читает её тот, кто строит
|
||||
порядок прогона, то есть этот скилл. Снимать пометку с перечисленных нельзя.
|
||||
|
||||
### Находка «переделать форму» — прогон повторяется целиком
|
||||
|
||||
@@ -554,7 +561,7 @@ flowchart TD
|
||||
|
||||
## Прогон без change — сценарий обслуживания
|
||||
|
||||
Третий вызывающий конвейера — сценарий обслуживания скилла `av-dev:code-resolve`
|
||||
Второй вызывающий конвейера — сценарий обслуживания скилла `av-dev:code-resolve`
|
||||
(тулчейн и сборка, зависимости, гит-хуки, перенос, чистка). Он приходит **без
|
||||
change**: у работы, не меняющей поведения, дельта-спек нет по построению.
|
||||
|
||||
@@ -709,7 +716,7 @@ change**: у работы, не меняющей поведения, дельт
|
||||
|
||||
**Технический разбор — не тема, а обязанность прохода, и он единственный.**
|
||||
Остальные читают код как материал для своей оптики: `specs` — против требований,
|
||||
`basics` — против отказов окружения, `architecture` — против устройства. «Здесь
|
||||
`basics` — против отказов окружения проекта. «Здесь
|
||||
ошибка в логике» не говорит больше никто, и до недавнего времени не говорил
|
||||
никто вовсе: `code` был проходом только по конвенциям, а дефект ловился разве что
|
||||
случайно. Это была самая крупная дыра конвейера, и стоила она дороже любой
|
||||
@@ -789,9 +796,9 @@ change»: сверять исход с планом триаж обязан и
|
||||
ущербу × вероятности → потолок 7 пунктов в основном списке.
|
||||
|
||||
**Разметку действия ставит он же, и умолчание у неё одно — `инлайн`.** Развилку
|
||||
получает только то, что инлайном чинить нельзя: находка по необратимому месту и
|
||||
находка, чья правка меняет дельта-спеки. Остальное чинится молча — см. «Что
|
||||
происходит с находками дальше».
|
||||
получает только то, что инлайном чинить нельзя, и оснований у неё три: правка
|
||||
меняет дельта-спеки, находка сидит в необратимом месте, находка трогает инвариант
|
||||
`CLAUDE.md`. Остальное чинится молча — см. «Что происходит с находками дальше».
|
||||
|
||||
**Он же собирает строки «отложено в `av-dev:code-deep-review`».** Проход, упёршийся
|
||||
в предел цикла — нужен замер, нужен прогнанный путь, нужен вход шире диффа, —
|
||||
@@ -821,11 +828,17 @@ change»: сверять исход с планом триаж обязан и
|
||||
|
||||
- **`Действие: развилка`** — вопросом с вариантами и ценой каждого туда, где
|
||||
проект держит вопросы (это знает вызвавший скилл, а не конвейер ревью).
|
||||
Помечается так **только** то, что инлайном чинить нельзя: находка по
|
||||
необратимому месту (миграция, формат на диске, публичный контракт) и находка,
|
||||
чья правка меняет **дельта-спеки** — то есть отменяет одобренное человеком.
|
||||
Оркестратор при этом не останавливается: он урезает изменение до остатка и
|
||||
доводит его.
|
||||
Помечается так **только** то, что инлайном чинить нельзя, и оснований ровно
|
||||
три: находка по **необратимому** месту (миграция, формат на диске, публичный
|
||||
контракт), находка, трогающая **инвариант** `CLAUDE.md`, и находка, чья правка
|
||||
меняет **дельта-спеки** — то есть отменяет одобренное человеком.
|
||||
|
||||
По первым двум основаниям оркестратор **не останавливается**: он урезает
|
||||
изменение до остатка и доводит его. Третье старше: правка, меняющая
|
||||
дельта-спеки, отменяет одобрение, и оркестратор **возвращается на чекпоинт**
|
||||
(`av-dev:code-resolve`, `references/solve.md`, шаг 5). Вопрос в запись при этом
|
||||
остаётся, но возврата не заменяет — иначе одобренный дизайн переделывался бы
|
||||
молча.
|
||||
- **урожай** — находка реальная, но не для этого мерджа: отложенный `major`,
|
||||
развилка, решённая «потом», пачка `nit`. Конвейер отдаёт её **списком** в
|
||||
отчёте: формулировка, оракул, откуда взялась (какой проход, какой change).
|
||||
|
||||
@@ -98,7 +98,8 @@
|
||||
**Кто какой документ читает — из документа не выводится, а назначается планом.**
|
||||
Документ питает тему (это записано на стороне канона, таблица «Роли документов и
|
||||
темы ревью»), а тему на этом прогоне закрывает тот, кто назван в составе прогона; вся
|
||||
раскладка «тема → проход → глубина» — в `SKILL.md` этого скилла и больше нигде.
|
||||
раскладка «тема → кто закрывает → против чего» — в `SKILL.md` этого скилла и
|
||||
больше нигде.
|
||||
**Списка читателей не ведёт никто, и это не пробел.** Он жил бы на стороне
|
||||
канона, а документ живёт дольше, чем раскладка проходов: список разошёлся бы с
|
||||
конвейером молча и при этом выглядел актуальным. Однажды уже разошёлся.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: doc-healthcheck
|
||||
description: "Проверка здоровья документации проекта судом, а не машиной: не разошлись ли документы между собой и с кодом. Зовёт двух агентов на весь канон разом — doc-consistency (один факт в двух домах, прямое противоречие, поведение в architecture.md вместо спек, ADR без парного статуса, число без происхождения) и doc-code-drift (протухший факт: имя ветки, команды, пути, зависимости поимённо, настройки с числом, единые точки, capability). Разбирает урожай порциями: строка на замену идёт в документ сразу, работа больше абзаца становится задачей. Прогон оставляет след — ключ [healthcheck] last в .av-dev.toml, — и по нему синк документации считает, сколько задач сделано с прошлой сверки, и выдаёт сигнал строкой. Использовать, когда с прошлой сверки сделан десяток задач, когда вернулись к проекту после перерыва, перед тем как опереться на документ в решении, а также шагом adopt и upgrade. Дорого — не на каждой задаче. Раскладку и версию раскладки проверяет скилл av-dev:canon, язык документов — агент doc-wording."
|
||||
description: "Проверка здоровья документации проекта судом, а не машиной: не разошлись ли документы между собой и с кодом. Зовёт двух агентов на весь канон разом — doc-consistency (один факт в двух домах, прямое противоречие, поведение в architecture.md вместо спек, ADR без парного статуса, число без происхождения) и doc-code-drift (протухший факт: имя ветки, команды, пути, зависимости поимённо, настройки с числом, единые точки, capability). Разбирает урожай порциями: строка на замену идёт в документ сразу, работа больше абзаца становится задачей. Прогон оставляет след — ключ [docs] healthcheck_last в .av-dev.toml, — и по нему синк документации считает, сколько задач сделано с прошлой сверки, и выдаёт сигнал строкой. Использовать, когда с прошлой сверки сделан десяток задач, когда вернулись к проекту после перерыва, перед тем как опереться на документ в решении, а также шагом adopt и upgrade. Дорого — не на каждой задаче. Раскладку и версию раскладки проверяет скилл av-dev:canon, язык документов — агент doc-wording."
|
||||
---
|
||||
|
||||
# Здоровье документации
|
||||
@@ -128,11 +128,17 @@ check` и его скрипт; здесь начинается там, где к
|
||||
|
||||
## След прогона
|
||||
|
||||
**Последним шагом прогон правит `.av-dev.toml`** — ключ `last` в секции
|
||||
`[healthcheck]`: хеш коммита `HEAD` и дата комментарием рядом. Состав ключей —
|
||||
**Последним шагом прогон правит `.av-dev.toml`** — ключ `healthcheck_last` в
|
||||
секции `[docs]`: хеш коммита `HEAD` и дата комментарием рядом. Состав ключей —
|
||||
[канон](../canon/references/canon.md), раздел `.av-dev.toml`; правится **строка**,
|
||||
а не файл целиком.
|
||||
|
||||
**Секцию и имя ключа не выбирай сам.** Неизвестный ключ `.av-dev.toml` — отказ
|
||||
кодом 3, а не пропуск: ключ, заведённый мимо константы скрипта-владельца, роняет
|
||||
`docs.py`, `tasks.py` и гейт проекта разом. Этот ключ там уже назван
|
||||
(`DOCS_KEYS` в `av-dev/skills/canon/scripts/docs.py`), а любой другой пришлось бы
|
||||
заводить правкой скрипта.
|
||||
|
||||
**Без следа признак «десяток задач» не считается никем.** Так и было: сверку
|
||||
звали по памяти, то есть не звали — тот же прозаический триггер, что дал 6
|
||||
записей ADR на 43 изменения. След превращает признак в число, которое
|
||||
@@ -144,6 +150,12 @@ check` и его скрипт; здесь начинается там, где к
|
||||
этого делать нечего. Его отсутствие значит «сверки не было ни разу», и синк
|
||||
говорит это отдельной строкой.
|
||||
|
||||
**Правку следа коммитит тот, кто позвал прогон.** Своего коммита у скилла нет:
|
||||
он правит документы, заводит задачи и ставит след — всё это уезжает одним
|
||||
коммитом разбора, и `last` в нём указывает на **прежний** `HEAD`, то есть на
|
||||
состояние, которое сверяли. Оставить правку незакоммиченной нельзя: счёт пойдёт
|
||||
от коммита, которого в истории нет.
|
||||
|
||||
**Позвал одного агента из двух — след всё равно ставится, но в докладе назван
|
||||
неполным.** Иначе следующая сверка отсчитывалась бы от прогона, который смотрел
|
||||
половину.
|
||||
@@ -164,9 +176,10 @@ check` и его скрипт; здесь начинается там, где к
|
||||
- **Не проверяет раскладку, версию и ссылки** — это `canon check`, там машина.
|
||||
- **Не судит язык** документов: залог, англицизмы, жаргон, термин без дома — это
|
||||
агент `doc-wording`, и зовут его отдельно, по пачке правленных документов.
|
||||
Звонящие у него названные — последний шаг синка в `av-dev:doc-sync`, шаг 9
|
||||
`av-dev:doc-init` и шаг вычитки в обоих режимах `canon`, — просто ни один из
|
||||
них не здесь. У него другой ритм: он нужен там, где текст только что писали, а
|
||||
Звонящие у него названные — последний заход синка в `av-dev:doc-sync`, шаг
|
||||
вычитки сценария разведки (`av-dev:code-resolve`), шаг 9 `av-dev:doc-init` и
|
||||
шаг вычитки в обоих режимах `canon`, — просто ни один из них не здесь. У него
|
||||
другой ритм: он нужен там, где текст только что писали, а
|
||||
не там, где он год лежал. Оркестровать его нечем — он один и работает по
|
||||
названному списку.
|
||||
- **Не правит документы за агентов** — они возвращают формулировки, решение
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: doc-sync
|
||||
description: "Вести содержимое документов канона по ходу разработки. Правки двух родов, и спрашивается один: отражение сделанного (вливание дельт, миграция в database.md, компонент в architecture.md) пишется молча, а новая запись и новая норма (ADR, правило в conventions, записка в research, инвариант CLAUDE.md, периметр security.md, граница passport.md, дефект в review.md) только предлагается — пишет её второй запуск после слова человека. Построчный отчёт по каждому документу остаётся: каждый назван либо правкой, либо предложением, либо отрицанием с причиной. ADR и записка разведки — промоут цитатой из архивного design.md или записки, а не второе сочинение. Синк же считает и выдаёт строкой сигнал сверки: сколько задач сделано с прошлого прогона av-dev:doc-healthcheck. Использовать, когда задача сделана и надо обновить документацию, когда просят завести ADR или записать решение, занести находку о внешних данных, записать проскочивший дефект, разгрузить разросшуюся архитектуру. Раскладку и соответствие канону проверяет скилл av-dev:canon."
|
||||
description: "Вести содержимое документов канона по ходу разработки. Правки двух родов, и спрашивается один: отражение сделанного (вливание дельт, миграция в database.md, компонент в architecture.md) пишется молча, а новая запись и новая норма (ADR, правило в conventions, записка в research, инвариант CLAUDE.md, периметр security.md, граница passport.md, дефект в review.md) только предлагается — пишет её второй запуск после слова человека. Построчный отчёт по каждому документу остаётся: каждый назван либо правкой, либо предложением, либо отрицанием с причиной. ADR и записка разведки — промоут цитатой из архивного design.md или записки, а не второе сочинение. Синк же считает и выдаёт строкой сигнал сверки: сколько задач сделано с прошлого прогона av-dev:doc-healthcheck, читая след в ключе [docs] healthcheck_last. Использовать, когда задача сделана и надо обновить документацию, когда просят завести ADR или записать решение, занести находку о внешних данных, записать проскочивший дефект, разгрузить разросшуюся архитектуру. Раскладку и соответствие канону проверяет скилл av-dev:canon."
|
||||
---
|
||||
|
||||
# Ведение содержимого канона
|
||||
@@ -139,6 +139,14 @@ description: "Вести содержимое документов канона
|
||||
она коснулась, — и назови этот список в промпте: по нему же он судит, известен ли
|
||||
термин. Находки он отдаёт готовыми формулировками, подставляешь их ты.
|
||||
|
||||
**Синк бывает в два захода, и вычитка идёт последним из них.** Вернул непустой
|
||||
список предложений — правка ещё не кончилась: человек ответит, и второй заход
|
||||
допишет одобренное. Вычитывать пачку, которая сейчас пополнится, значит платить
|
||||
за неё дважды. Значит: **предложения есть — вычитку откладываешь до второго
|
||||
захода; предложений нет — этот заход последний, и вычитка идёт в нём.** Отказ
|
||||
человека второго захода не отменяет: письма в нём не будет, а вычитка и гейт
|
||||
будут — иначе правка первого захода уедет в коммит невычитанной.
|
||||
|
||||
**Условие вызова — правка, а не синк.** Синк самый частый вызывающий, но не
|
||||
единственный: разведка (`av-dev:code-resolve`, сценарий разведки) пишет ответ по
|
||||
одному адресу и синком себя не считает намеренно — вычитка ей нужна ровно та же.
|
||||
@@ -303,18 +311,26 @@ av-dev:code-review`, его `references/review-journal.md`.
|
||||
ровно тот прозаический триггер, который дал 6 записей ADR на 43 изменения, — и
|
||||
здесь он не срабатывал по той же причине.
|
||||
|
||||
**След оставляет сама сверка** — ключ `[healthcheck] last` в `.av-dev.toml`
|
||||
(состав ключей — [canon.md](../canon/references/canon.md), раздел
|
||||
`.av-dev.toml`). **Считает синк**, и вот чем:
|
||||
**След оставляет сама сверка** — ключ `healthcheck_last` в секции `[docs]`
|
||||
файла `.av-dev.toml` (состав ключей — [canon.md](../canon/references/canon.md),
|
||||
раздел `.av-dev.toml`). **Считает синк**, и вот чем:
|
||||
|
||||
```sh
|
||||
git rev-list --count <last>..HEAD -- openspec/changes/archive
|
||||
git rev-list --count <last>..HEAD -- openspec/changes/archive <каталог задач>
|
||||
```
|
||||
|
||||
Коммит, тронувший архив, — это доехавшая до конца задача, так что счёт идёт в
|
||||
задачах, а не в правках. `openspec` в проекте нет — считай коммиты
|
||||
Считаются коммиты, тронувшие **архив change или каталог задач** (его путь — ключ
|
||||
`[tasks] dir`). Оба пути выбраны потому, что доведённая до конца задача оставляет
|
||||
след хотя бы в одном: решение архивирует change, а обслуживание и разведка change
|
||||
не заводят вовсе и видны только закрытием — правкой индексов учёта. Считать один
|
||||
архив значило бы не считать `chore` и `research`, то есть на проекте с их
|
||||
перевесом говорить «звать рано» вечно.
|
||||
|
||||
Ни `openspec`, ни каталога задач в проекте нет — считай коммиты
|
||||
(`git rev-list --count <last>..HEAD`) и **скажи, что считал коммиты**: число
|
||||
другого рода, и молчаливая подмена сделала бы признак вдвое чувствительнее.
|
||||
Постановка, пришедшая текстом, следа не оставляет ни там ни там — такие задачи в
|
||||
счёт не входят, и это тоже говорится строкой, когда прогон шёл текстом.
|
||||
|
||||
Строка доклада обязательна всегда, и вариантов у неё три:
|
||||
|
||||
|
||||
@@ -244,20 +244,22 @@ stateDiagram-v2
|
||||
**напоминает** — беклог, заведённый до появления типа, законен, и переоформлять
|
||||
его «заодно» здесь не просят.
|
||||
|
||||
**Тип не выбирает метку ревью и глубину проверки.** Профиль выбирается по факту
|
||||
изменения, а не по типу задачи: `chore` бывает миграцией схемы, `fix` — правкой
|
||||
публичного контракта. Правило «предписание процесса в теле задачи снимается»
|
||||
типом не отменяется, а подтверждается: он описывает работу, а не то, как её
|
||||
проверять. **Стадия проекта их тоже не выбирает**: изменение на стройке ничем не
|
||||
проще того же изменения на доработке, и метку ему по-прежнему назначает разметка.
|
||||
**Тип не выбирает состав ревью и глубину проверки — и не выбирает их больше
|
||||
никто.** Состав прогона постоянный: он один и тот же на всякой задаче
|
||||
(`av-dev:code-review`, «Состав прогона»). Прежде состав считала метка `small` ·
|
||||
`medium` · `large`, и тогда эта строка отвечала на живой вопрос «не задаёт ли её
|
||||
тип»; метки нет, и вопрос снят вместе с ней. Правило «предписание процесса в теле
|
||||
задачи снимается» типом не отменяется, а подтверждается: он описывает работу, а
|
||||
не то, как её проверять. **Стадия проекта состава тоже не выбирает**: изменение
|
||||
на стройке ничем не проще того же изменения на доработке.
|
||||
|
||||
**Одно исполнителю тип всё же говорит — каким сценарием работу вести, и то не
|
||||
один.** Скилл `av-dev:code-resolve` выбирает сценарий связкой из двух
|
||||
признаков: тип **предлагает** (`chore` — обслуживание, `research` — разведка),
|
||||
а подтверждает его предмет работы — есть ли что менять в спеках. Признаки
|
||||
разошлись — работа останавливается, и тип меняется здесь, командой `edit --type`,
|
||||
а не переклеивается исполнителем по ходу. Метку и глубину это по-прежнему не
|
||||
задаёт: их называет разметка изменения, а на прогоне без change — сам сценарий.
|
||||
а не переклеивается исполнителем по ходу. Состава ревью это по-прежнему не
|
||||
задаёт: он постоянный, а на прогоне без change его называет сам сценарий.
|
||||
|
||||
## Как написана задача
|
||||
|
||||
@@ -567,9 +569,9 @@ python3 $tk adopt scan --from … --stage S | apply --plan … # разова
|
||||
**каждая давать видимую пользу**, а у штурма исход «выкинуть» — полноправный.
|
||||
|
||||
Там же **шов**: где резать, когда допустимых мест несколько. Коротко — по
|
||||
границе, которая одна поднимает метку ревью выше остальных; и не резать, когда
|
||||
обе половины остаются в одной метке, потому что несокращаемый костяк проверок
|
||||
платится за каждую задачу отдельно.
|
||||
границе, где **меняется род работы**; и резать пореже, потому что костяк ревью
|
||||
разрез удваивает **всегда** — состав прогона постоянный и от размера половин не
|
||||
зависит. Выигрыш даёт не проверка, а то, что половина доводится и мерджится сама.
|
||||
|
||||
### Вычитка: два прохода, а не один
|
||||
|
||||
@@ -633,9 +635,10 @@ python3 $tk adopt scan --from … --stage S | apply --plan … # разова
|
||||
- **свойство репозитория в рамках** — номер миграции, хеш, версия зависимости:
|
||||
в лежалой задаче протухает молча и становится ложной рамкой. Снимается;
|
||||
снимок берётся при постановке, а не при заведении;
|
||||
- **предписание процесса в теле** — «делать с такой-то меткой ревью», «взять
|
||||
такой-то агент»: это второй дом для правила выбора и путь понизить требования
|
||||
решением, принятым до проектирования. Снимается;
|
||||
- **предписание процесса в теле** — «прогнать глубоким ревью», «взять такой-то
|
||||
агент», «этой задаче хватит короткой проверки»: это второй дом для правила
|
||||
выбора и путь понизить требования решением, принятым до проектирования.
|
||||
Снимается;
|
||||
- **тип, разошедшийся с задачей** — задача заводилась починкой, а после разбора
|
||||
оказалось, что поведение никогда и не было заявлено: это `feature`, а не `fix`.
|
||||
Правится `edit <slug> --type …`; тип, оставшийся от прошлой формулировки, врёт
|
||||
|
||||
@@ -15,11 +15,13 @@
|
||||
не файл-на-находку.** Если у ревью был триаж — половина работы уже сделана, бери
|
||||
его выход. Если нет — триажируй сам, прежде чем заводить.
|
||||
|
||||
**Штатный отправитель — `av-dev:code-review`** (и `av-dev:code-resolve`, который
|
||||
его вызывает): задач он не заводит сам, а отдаёт отложенные находки **списком
|
||||
урожая** — формулировка, оракул, откуда взялась — и хранит отчёт триажа вместе с
|
||||
изменением. Приходит и любой другой разбор, вплоть до пересказа человеком; тогда
|
||||
триажа нет и шаг 1 порядка делается руками.
|
||||
**Штатных отправителя два.** Первый — `av-dev:code-review` (и зовущий его
|
||||
`av-dev:code-resolve`): задач он не заводит сам, а отдаёт отложенные находки
|
||||
**списком урожая** — формулировка, оракул, откуда взялась — и хранит отчёт триажа
|
||||
вместе с изменением. Второй — `av-dev:code-deep-review`, и он зовёт этот сценарий
|
||||
напрямую, передавая согласованные с человеком находки дословно. Приходит и любой
|
||||
другой разбор, вплоть до пересказа человеком; тогда триажа нет и шаг 1 порядка
|
||||
делается руками.
|
||||
|
||||
## Находка агента — не задача
|
||||
|
||||
@@ -64,6 +66,14 @@
|
||||
ради которого заведение из ревью и выделено. Дешёвая мелочь по явному согласию может
|
||||
заводиться и без поштучного вопроса — но карта пользователю предъявляется
|
||||
всё равно.
|
||||
|
||||
**Барьер снимается ровно в одном случае — когда его уже прошли.** В хвосте
|
||||
задачи (`av-dev:code-resolve`, шаг 6; в обслуживании — шаг 5) человек одной
|
||||
репликой сказал, что из урожая заводится, и третьего стопа у прогона не будет:
|
||||
там карта идёт **строкой доклада**, а не вопросом. Признак читается буквально:
|
||||
**список находок уже был показан человеку и получил ответ**. Не был — карта
|
||||
предъявляется вопросом, и это обычный случай прямого вызова и вызова из
|
||||
`av-dev:code-deep-review`, где находки разбирались по одной, а нарезка — нет.
|
||||
6. **Заводи утверждённое** через `tasks.py add`, с тремя добавками:
|
||||
- **тег партии** — `--tag review-ГГГГ-ММ-ДД` (или `audit-<slug>`), чтобы весь
|
||||
заход разбора поднимался одной командой `list --tag …`;
|
||||
|
||||
@@ -0,0 +1,58 @@
|
||||
# 79. След сверки переехал в секцию docs; ключ верхнего уровня ронял скрипты (2026-08-23)
|
||||
|
||||
## Что было
|
||||
|
||||
Тема 78 завела след сверки документов ключом `last` в секции `[healthcheck]`
|
||||
файла `.av-dev.toml`. Ревью трансформации — три прохода по скиллам и документам —
|
||||
нашло, что такого ключа не переживает ни один скрипт плагина.
|
||||
|
||||
Проверено запуском, а не рассуждением. В проекте с `[healthcheck] last` команда
|
||||
`docs.py check` печатает `ОТКАЗ: .av-dev.toml: неизвестные ключи верхнего уровня:
|
||||
healthcheck` и выходит кодом 3; `tasks.py check` — то же самое. Верхний уровень
|
||||
файла стережёт `shared/config.py` константой `TOP_KEYS`, и неизвестный ключ там —
|
||||
**отказ**, а не пропуск. То есть первый же прогон сверки сделал бы нерабочими
|
||||
`canon check/adopt/upgrade`, весь `task-track` вместе с закрытием задачи и гейт
|
||||
проекта, который их зовёт.
|
||||
|
||||
**Корень — не описка, а ложное обещание документа.** Раздел `.av-dev.toml` в
|
||||
каноне утверждал: «неизвестный ключ `docs.py` игнорирует». Утверждение было
|
||||
неверным и старше темы 78; при проектировании следа опёрлись на него и скрипт не
|
||||
открыли, хотя докстринг `check_keys` говорит прямо обратное: «неизвестный ключ —
|
||||
отказ, а не безмолвный пропуск».
|
||||
|
||||
## Решено
|
||||
|
||||
**Р319. След живёт ключом `healthcheck_last` в секции `[docs]`.** Секция досталась
|
||||
ему по смыслу: `[docs]` — настройки проверок документов, а сверка документов и
|
||||
есть такая проверка. Своя секция верхнего уровня стоила бы правки общего читателя
|
||||
`shared/config.py` и превратила бы файл, объявленный «версией и настройками», в
|
||||
хранилище состояния.
|
||||
|
||||
**Р320. Новый ключ `.av-dev.toml` заводится правкой константы скрипта-владельца,
|
||||
и только потом появляется в каноне.** Порядок именно такой, а не обратный:
|
||||
владелец ключа — тот скрипт, чья константа его перечисляет (`TOP_KEYS` в
|
||||
`shared/config.py`, `DOCS_KEYS` в `docs.py`, свой список в `tasks.py`).
|
||||
|
||||
**Р321. Канон приведён к скрипту, а не скрипт к канону.** Отказ кодом 3 —
|
||||
поведение верное: ключ, положенный не в ту секцию, при молчаливом пропуске не
|
||||
значит ничего, проверка объявляет себя неприменимой, отчёт выходит зелёным, и на
|
||||
месте настройки оказывается тишина. Ложное обещание снято, на его месте — правило
|
||||
Р320 и названная цена этой ошибки.
|
||||
|
||||
## Следствия
|
||||
|
||||
**С282. Версия раскладки не двигается.** Ключ необязательный и заводится сам
|
||||
первым прогоном сверки; проекту делать нечего, а запись журнала версий нужна ради
|
||||
пункта «что сделать проекту».
|
||||
|
||||
**С283. Правило «своей прозе здесь верить нельзя» распространяется и на
|
||||
собственную документацию плагина.** Оно написано про возврат агента, но работает
|
||||
шире: утверждение документа о поведении скрипта проверяется **запуском скрипта**,
|
||||
и стоит эта проверка одной команды. Здесь её не сделали, и цена вышла в рабочую
|
||||
поломку у всякого, кто позвал бы сверку.
|
||||
|
||||
**С284. Гейт репозитория такого класса дефектов не ловит и ловить не может.** Он
|
||||
судит форму: фронтматтеры, дословность копий, адреса, номера журнала, рендер
|
||||
диаграмм. Согласованность прозы с поведением скрипта — суждение, и добыло его
|
||||
ревью, а не хук. Это довод в пользу того, чтобы прогон ревью по трансформации
|
||||
шёл не «если останется время», а следом за ней.
|
||||
@@ -0,0 +1,86 @@
|
||||
# 80. Противоречия хвоста сведены: кто зовёт учёт, когда идёт третий такт (2026-08-23)
|
||||
|
||||
## Что было
|
||||
|
||||
Тему 78 проверило ревью — три прохода по скиллам, документам и сквозной
|
||||
консистентности. Кроме поломки, разобранной темой 79, оно нашло, что тема
|
||||
противоречит сама себе в четырёх местах, и все четыре — про хвост задачи.
|
||||
|
||||
**Учёт отдали агенту, не сняв запрета.** Такт третий звал `av-dev:task-track`, а
|
||||
`code-resolve/SKILL.md` двумя абзацами ниже объявлял этот вызов оркестраторским и
|
||||
перечень закрытым, а границы задания агента прямо гласили «задач не заводит».
|
||||
|
||||
**Ветка отказа не была покрыта.** Первый такт откладывал вычитку и гейт в третий,
|
||||
третий запускался «только если человек что-то одобрил» — и на ответе «ничего»
|
||||
правка первого такта уезжала в коммит невычитанной, с непрогнанным гейтом.
|
||||
|
||||
**Дом правила вычитки не знал про два захода.** `doc-sync` велел звать
|
||||
`doc-wording` последним шагом правки; агент, читающий дом, вычитал бы половину
|
||||
пачки.
|
||||
|
||||
**Барьер учёта столкнулся с одной репликой.** Сценарий «задачи из ревью и аудита»
|
||||
требует показать карту кластеров через `AskUserQuestion` — изнутри агента, где
|
||||
показывать некому, и вторым вопросом там, где стоп уже был.
|
||||
|
||||
Отдельно разошёлся счёт стопов: «один плановый» в четырёх местах против «два» во
|
||||
фронтматтере и тонкостях, — и сценарий обслуживания получил реплику, но не
|
||||
получил того, кто пишет одобренное.
|
||||
|
||||
## Решено
|
||||
|
||||
**Р322. Задачи из урожая заводит оркестратор, а не агент.** Довод тот же, что у
|
||||
коммита и закрытия: заведение правит индексы учёта, а перечень работ ведёт
|
||||
человек. Агенту третьего такта остаётся письмо в документы канона.
|
||||
|
||||
**Р323. Третий такт идёт всякий раз, когда была реплика** — в том числе на ответе
|
||||
«ничего»: на нём висят вычитка и гейт, снятые с себя первым тактом. Не
|
||||
запускается он ровно тогда, когда реплики не было вовсе.
|
||||
|
||||
**Р324. Дом правила вычитки знает про два захода.** Предложения есть — вычитка
|
||||
ждёт второго захода; предложений нет — заход последний, и вычитка идёт в нём;
|
||||
отказ человека второго захода не отменяет.
|
||||
|
||||
**Р325. Барьер карты кластеров снимается там, где его уже прошли.** Признак
|
||||
читается буквально: список находок уже показан человеку и получил ответ. Это
|
||||
хвост задачи; при прямом вызове и вызове из `av-dev:code-deep-review` карта
|
||||
по-прежнему предъявляется вопросом — там разбирали находки, а не нарезку.
|
||||
|
||||
**Р326. Стопов у сценария два, и счёт сведён в одну таблицу** — по сценариям, с
|
||||
разделением «до письма» и «после письма». Чекпоинт остаётся не более чем одним, и
|
||||
реплика этого счёта не касается: она решает не форму решения, а судьбу находок.
|
||||
|
||||
**Р327. У обслуживания появился второй заход, а повод для реплики один** — новый
|
||||
запрет или инвариант `CLAUDE.md`. Урожай ревью спрашивается той же репликой;
|
||||
сужение проверок не спрашивается вовсе, потому что его решил человек.
|
||||
|
||||
**Р328. Сигнал сверки считается по архиву change и каталогу задач разом.** Счёт
|
||||
по одному архиву не видел `chore` и `research`: они change не заводят и заметны
|
||||
только закрытием. Постановка текстом следа не оставляет ни там ни там — это
|
||||
говорится строкой.
|
||||
|
||||
**Р329. «Род правки документа» внесён в перечень осей** — отражение · новое, дом
|
||||
`av-dev:doc-sync`. Перечень объявлен полным, а ось ветвит поведение трёх скиллов;
|
||||
её отсутствие было ровно тем молчаливым пропуском, от которого перечень
|
||||
предостерегает в своей же шапке.
|
||||
|
||||
**Р330. Глубокое ревью пишет след в `docs/review.md` без второго вопроса.**
|
||||
`review.md` — документ рода «новое», но слово по каждой находке человек сказал в
|
||||
разборе, а след цитирует его решения.
|
||||
|
||||
## Следствия
|
||||
|
||||
**С285. Сигнал сверки вошёл в контракт возврата и в доклады всех трёх
|
||||
сценариев.** Прежде строка была объявлена обязательной в скилле-владельце, но
|
||||
порождалась там, где её никто не обязан вернуть.
|
||||
|
||||
**С286. Прогон ревью после трансформации перестал быть необязательным.** Он нашёл
|
||||
одну рабочую поломку (тема 79) и четыре противоречия, ни одно из которых не видит
|
||||
гейт: гейт судит форму, а согласованность утверждений — суждение.
|
||||
|
||||
**С287. Часть находок ревью намеренно отложена, и это не пропуск.** Старший долг —
|
||||
основания развилки, названные то двумя, то тремя; `task-track/SKILL.md`, живущий
|
||||
в мире снятых меток; `review-basics`, у которого «нет тем ядра» и тут же есть
|
||||
`operations`; вопросы проекта по темам, обещанные проходам, которые о них не
|
||||
знают; расхождения `av-dev:code-deep-review` с уставами `review-code` и
|
||||
`review-triage`; отсутствующая запись журнала версий канона. Всё это старше темы
|
||||
78 и разбирается отдельным заходом.
|
||||
@@ -0,0 +1,78 @@
|
||||
# 81. Старший долг трансформации разобран: развилка, вопросы тем, версия 5 (2026-08-23)
|
||||
|
||||
## Что было
|
||||
|
||||
Тема 80 свела противоречия, внесённые темой 78, и назвала строкой С287 то, что
|
||||
осталось: находки ревью, которые старше трансформации хвоста и тянутся с тем 74–77.
|
||||
Этот заход разбирает их.
|
||||
|
||||
Долг был четырёх родов. **Перечень, разошедшийся с исполнителем**: конвейер
|
||||
называл два основания развилки, а устав триажа, контракт находок, сценарий решения
|
||||
и журнал — три. **Остатки снятого устройства**: `task-track/SKILL.md` объяснял, что
|
||||
метку назначает разметка, и искал шов по границе, «которая поднимает метку»;
|
||||
`config-skeleton.md` увозил в конфиг чужого проекта строку про «правило выбора
|
||||
метки». **Обещание без исполнителя**: конвейер обещал каждому проходу вопросы
|
||||
проекта по его темам, а три прохода из четырёх о вопросах не знали и места под
|
||||
ответ не имели. **Скилл, разошедшийся с уставами, которые он зовёт**:
|
||||
`av-dev:code-deep-review` назначал `review-code` глубину «доказательство» и отменял
|
||||
триажу потолок, ничего об этом уставам не сказав.
|
||||
|
||||
Отдельно стояла **непройденная миграция**: тема 77 переписала скелет
|
||||
`docs/review.md`, который уезжает в репозиторий проекта, а записи в журнале версий
|
||||
канона не появилось. Проекты, приведённые к версии 4, остались с подразделом
|
||||
«Триггеры метки» под словарь, которого больше нет.
|
||||
|
||||
## Решено
|
||||
|
||||
**Р331. Оснований у развилки три, и перечень сведён по всем местам.** Правка
|
||||
меняет дельта-спеки, находка сидит в необратимом месте, находка трогает инвариант
|
||||
`CLAUDE.md`. Там же названо, чем третье отличается: по первым двум оркестратор не
|
||||
останавливается, а урезает изменение до остатка; третье отменяет одобрение и
|
||||
**возвращает на чекпоинт**.
|
||||
|
||||
**Р332. Вопросы проекта по темам достались проходам, которые эти темы закрывают.**
|
||||
`review-code` (`conventions`, `security`, `operations`, `architecture`),
|
||||
`review-specs` (`requirements`) и `review-autotests` (`autotests`) получили
|
||||
обязанность отвечать дословно и строку в блоке покрытия. Задание вопросов не
|
||||
принесло — это говорится строкой: молча пропущенный вопрос неотличим от
|
||||
отвеченного, а других способов настроить проход под проект у проекта нет.
|
||||
|
||||
**Р333. Глубина в глубоком ревью — не одна на всех.** Доказательство дают те двое,
|
||||
что держат машину; `review-architecture` и `review-code` дают разбор на входе шире
|
||||
диффа, и выдать доказательство им нечем. `review-code` получил единственную
|
||||
оговорку про вызов оттуда: вход — область, потолков нет, машину он не держит и там.
|
||||
|
||||
**Р334. У триажа три вызывающих, а не два режима.** Прогон по change, прогон без
|
||||
change и глубокое ревью области, где перечень приходит составом прогона, а потолка
|
||||
в 7 пунктов нет: отчёт читает человек и разбирает находки по одной, поэтому вместо
|
||||
среза — порядок по убыванию ущерба.
|
||||
|
||||
**Р335. Версия раскладки поднята до 5.** Запись журнала называет, что переехало
|
||||
(подраздел «Триггеры метки» → «Когда звать глубокое ревью», двумя списками) и что
|
||||
сделать проекту: переписать подраздел, пройти по документам грепом, поднять
|
||||
версию, догнать `check`. Ключ `[docs] healthcheck_last` руками заводить не надо —
|
||||
он появится сам.
|
||||
|
||||
**Р336. Перечень осей досчитал три оси**, которые ветвили поведение годами:
|
||||
глубина темы, разметка действия, род правки документа. Каждая жила в своём скилле
|
||||
и оттуда была видна, а из перечня — нет; ровно за этим перечень и заведён.
|
||||
|
||||
## Следствия
|
||||
|
||||
**С288. След сверки коммитит тот, кто позвал прогон.** Своего коммита у
|
||||
`av-dev:doc-healthcheck` нет, и незакоммиченный след означал бы счёт от коммита,
|
||||
которого в истории не существует.
|
||||
|
||||
**С289. Проекты на версии 4 теперь видят дрейф.** `docs.py check` называет
|
||||
повышение прямо и зовёт `upgrade`; до этой темы расхождение скелета с каноном не
|
||||
замечала ни машина, ни человек.
|
||||
|
||||
**С290. Три прохода стали дороже ровно на то, что проект им скажет.** Вопросы по
|
||||
темам — механизм настройки, который до сих пор работал только у приёмника тем;
|
||||
пустой подраздел в `docs/review.*` ничего не стоит, а непустой перестал пропадать
|
||||
молча.
|
||||
|
||||
**С291. Ревью трансформации закрыто в три захода**, и цена его известна: одна
|
||||
рабочая поломка (тема 79), четыре противоречия внутри новой темы (тема 80) и
|
||||
двенадцать мест старшего долга (эта). Гейт не поймал ни одного: он судит форму, а
|
||||
всё перечисленное — согласованность утверждений.
|
||||
@@ -130,3 +130,6 @@
|
||||
| 76 | [Лёгкий проход в цикле, тяжёлые — в отдельном скилле](76-proof-in-cycle-deep-review-apart.md) | 2026-08-23 |
|
||||
| 77 | [Цикл задачи проверяет механику; метки сняты](77-cycle-checks-mechanics-labels-dropped.md) | 2026-08-23 |
|
||||
| 78 | [Хвост задачи: отражение молча, новое — по слову](78-tail-reflection-silent-new-by-word.md) | 2026-08-23 |
|
||||
| 79 | [След сверки переехал в секцию docs; ключ верхнего уровня ронял скрипты](79-healthcheck-trace-moved-into-docs-section.md) | 2026-08-23 |
|
||||
| 80 | [Противоречия хвоста сведены: кто зовёт учёт, когда идёт третий такт](80-tail-contradictions-fixed.md) | 2026-08-23 |
|
||||
| 81 | [Старший долг трансформации разобран: развилка, вопросы тем, версия 5](81-elder-debt-of-transformation-cleared.md) | 2026-08-23 |
|
||||
|
||||
Reference in New Issue
Block a user