From b411d4edb88c7da85a59f0c4991e83f2525ebb8c Mon Sep 17 00:00:00 2001 From: Anton Vakhrushev Date: Thu, 13 Aug 2026 12:16:38 +0300 Subject: [PATCH] =?UTF-8?q?=D0=BE=D1=81=D0=B8:=20=D0=BF=D0=B5=D1=80=D0=B5?= =?UTF-8?q?=D1=87=D0=B5=D0=BD=D1=8C=20=D0=BF=D0=BE=D0=BB=D1=83=D1=87=D0=B8?= =?UTF-8?q?=D0=BB=20=D0=B4=D0=BE=D0=BC,=20=D0=B4=D0=B2=D0=B5=20=D0=B1?= =?UTF-8?q?=D0=B5=D0=B7=D0=B4=D0=BE=D0=BC=D0=BD=D1=8B=D0=B5=20=D0=BE=D1=81?= =?UTF-8?q?=D0=B8=20=D0=BF=D0=B5=D1=80=D0=B5=D0=B5=D1=85=D0=B0=D0=BB=D0=B8?= =?UTF-8?q?=20=D0=B2=20shared?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Слияние ничего из идей не тронуло, но сделало дешёвым дом для правила, натянутого между скиллами. Заведён shared/axes.md — дом перечня, а не значений: девять осей, их адреса и чего каждая не решает. Механика остаётся у владельца. Целиком сюда переехали две оси, у которых владельца не было. Коды выхода объявлялись общим словарём в одиннадцати местах, и каждое объявление называло свой набор соседей; машина их не сверяла, потому что copies.py смотрит markdown, а перечни лежали в docstring'ах. Теперь дом один, скрипты держат указатель, а три SKILL.md — помеченную копию, потому что на кодах они ветвятся. Режим прогона (с меткой, без метки) был размазан по четырём файлам и осью назван не был, хотя в уставе review-basics задаёт саму возможность запуска. Разведены два значения слова «стадия»: ступени 1-5 внутри прогона кода, стадии дизайна и кода снаружи. Карта нашла ошибку в себе: клетка «категория документа × метка» пустой не была — review-basics приёмник проектных тем при любой метке. Пустой оказалась соседняя: на прогоне без метки план фиксирован, и своих тем проекта в нём нет вовсе. Обе оставшиеся пустоты названы вслух, а не заполнены наугад. --- DECISIONS.md | 55 +++++++++ README.md | 8 +- av-dev/shared/axes.md | 108 ++++++++++++++++++ av-dev/skills/code-openspec/SKILL.md | 28 ++++- .../skills/code-openspec/scripts/openspec.py | 8 +- av-dev/skills/code-resolve/SKILL.md | 3 + av-dev/skills/code-review/SKILL.md | 53 +++++++-- .../references/finding-contract.md | 2 + av-dev/skills/doc-canon/SKILL.md | 27 ++++- av-dev/skills/doc-canon/references/canon.md | 3 + av-dev/skills/doc-canon/scripts/docs.py | 8 +- av-dev/skills/task-track/SKILL.md | 37 ++++-- av-dev/skills/task-track/scripts/tasks.py | 12 +- scripts/addresses.py | 8 +- scripts/copies.py | 8 +- scripts/diagrams.py | 8 +- scripts/frontmatter.py | 8 +- scripts/resync.py | 7 +- 18 files changed, 308 insertions(+), 83 deletions(-) create mode 100644 av-dev/shared/axes.md diff --git a/DECISIONS.md b/DECISIONS.md index 20c47e7..6483b37 100644 --- a/DECISIONS.md +++ b/DECISIONS.md @@ -3983,3 +3983,58 @@ change по нему не будет никогда, — и такое реше 221. **Формат служебного файла выбирается по тому, кто его читает.** Читает человек в чужом репозитории через полгода — значит комментарии, значит TOML, значит построчная правка вместо перезаписи. + + +## 65. Перечень осей получил дом; две оси жили без владельца (2026-08-13) + +Слияние плагинов не тронуло ни одной идеи процесса — типы записей, метки, три +сценария, категории документов, severity находок остались как были. Но оно +сделало дешёвым то, что раньше было дорого: правило, натянутое между задачами и +ревью, теперь имеет достижимый дом, а не помеченную копию через границу. + +**Ось — закрытый перечень значений, по которому что-то ветвится.** Признак +проверяемый, и он отсекает похожее: темы ревью и документы проекта — списки +**открытые**, их пополняет проект. Модель прохода — не ось, а цена прогона. +Осей по этому признаку девять, и дом теперь у каждой. + +**АЕАКЛ. Две оси были бездомными, и обе машинные.** Коды выхода объявлялись +«общим словарём» в **одиннадцати** местах, и каждое объявление перечисляло свой +набор соседей: «тот же, что у `tasks.py`», «тот же, что у `tasks.py`, `docs.py` и +`copies.py`». Ни одно не было домом — все списки по памяти, и машина их не +сверяла, потому что `copies.py` смотрит markdown, а перечни лежали в docstring'ах +скриптов. Режим прогона (с меткой · без метки) завёлся накануне слияния и разошёлся +по четырём файлам, ни в одном не будучи назван осью, — при том что в уставе +`review-basics` он задаёт **саму возможность запуска** прохода. + +**АЕАКМ. Слово «стадия» значило в одном файле две разные вещи.** «Стадия 1 — +Автотесты … Стадия 5 — Triage» — ступени внутри прогона кода, наружу не +выходящие; «метка правит обе стадии ревью» — дизайн и код, то есть членение, +которое видит вызывающий скилл. Разведено: ступени внутри, стадии снаружи. + +**АЕАКН. Дом перечня — не дом значений.** `shared/axes.md` держит только сами +оси, их адреса и **чего каждая не решает**. Механика остаётся у владельца: +второй пересказ разошёлся бы с первым, а вот перечень нужен целиком и в одном +месте — вопрос «а не задаёт ли это метку» задают из скилла, который метку не +ведёт. Целиком сюда переехали ровно две оси, у которых владельца нет. + +**Карта нашла ошибку в самой себе, и это её главный довод.** Первая редакция +объявила пустой клетку «категория документа × метка»: якобы проект вправе +завести тему, под которую ни одна метка не отряжает прохода. Проверка показала +обратное — `review-basics` приёмник проектных тем при **любой** метке. Пустой +оказалась соседняя клетка: на прогоне **без метки** план фиксирован сценарием, и +своих тем проекта в нём нет вовсе. Найти это можно было только сведя оси в одну +таблицу. + +### Что из этого следует + +222. **Словарь, объявленный «общим» в каждом потребителе, — это перечень по + памяти, а не дом.** Признак вырожденности проверяемый: каждое объявление + называет свой набор соседей, и ни одно не называет владельца. +223. **Копия в docstring'е скрипта машиной не сверяется, потому что `copies.py` + смотрит markdown.** Значит, прозе в коде дом нужнее, чем прозе в документах: + там расхождение ловит гейт, здесь — никто. +224. **Пустая клетка в таблице осей — находка, а не пробел оформления.** Она + называет случай, для которого процесс не сказал ничего, и до сведения осей + в таблицу такой случай неотличим от продуманного умолчания. +225. **Слово, занятое дважды в одном файле, дороже неточного слова.** Читатель, + пришедший за термином, получает два ответа и не знает, что их два. diff --git a/README.md b/README.md index 4f6b9be..d082686 100644 --- a/README.md +++ b/README.md @@ -152,9 +152,11 @@ flowchart TB `docs/`, каталог задач, `openspec/`. Тогда вызывающий называет строкой, чего теперь не делает никто, и работу не останавливает. Правило целиком — [shared/absence.md](av-dev/shared/absence.md): оно нужно почти каждому скиллу, и -ни один им не владеет. Там же, в `shared/`, живут язык проектных текстов и -словарь сопровождения; скиллы читают их по ссылке, а дословной копией они -уезжают только в уставы вычитки — туда, где текст обязан лежать внутри промпта. +ни один им не владеет. Там же, в `shared/`, живут язык проектных текстов, +словарь сопровождения и **перечень осей процесса** +[axes.md](av-dev/shared/axes.md) — какие закрытые словари правят ходом работы, +где дом каждого и чего он **не** решает. Скиллы читают эти дома по ссылке, а +дословной копией оттуда уезжает лишь то, что обязано лежать внутри промпта. ## Канон документов проекта diff --git a/av-dev/shared/axes.md b/av-dev/shared/axes.md new file mode 100644 index 0000000..d42c92a --- /dev/null +++ b/av-dev/shared/axes.md @@ -0,0 +1,108 @@ +# Оси процесса + +**Это дом перечня, а не значений.** Что означает каждое значение и как оно +работает, знает владелец оси — здесь только сама ось, её дом и **чего она не +решает**. Второй пересказ механики разошёлся бы с первым; перечень же нужен +целиком и в одном месте, потому что вопрос «а не задаёт ли это метку» задают из +скилла, который метку не ведёт. + +**Ось — это закрытый перечень значений, по которому что-то ветвится.** Признак +проверяемый, и он отсекает похожее: темы ревью и документы проекта — списки +**открытые**, их пополняет проект, и перечень в плагине протух бы на первом же +своём документе. Модель прохода — не ось, а цена прогона; её дом — «Модель по +проходу» в `code-review`, механизация — `frontmatter.py`. + +## Перечень + +| Ось | Значения | Дом | +| --- | --- | --- | +| тип записи | `goal` `feature` `fix` `chore` `research` | `task-track/SKILL.md`, «Тип записи» | +| сценарий | решение · обслуживание · разведка | `code-resolve/SKILL.md`, «Развилка» | +| метка | `small` `medium` `large` | `code-review/SKILL.md`, «Метки» | +| режим прогона | с меткой · без метки | здесь, ниже | +| стадия ревью | дизайн · код | `code-review/SKILL.md`, «Ревью дизайна» | +| категория документа | тема · источник темы · процессный | `doc-canon/references/canon.md` | +| severity находки | `critical` `major` `minor` `nit` | `code-review/references/finding-contract.md` | +| коды выхода | 0 1 2 3 4 | здесь, ниже | + +Две оси стоят домом **здесь**, и обе по одной причине: владельца у них нет. +Коды выхода делят семь скриптов и три скилла, режим прогона — конвейер, сценарий +обслуживания и два устава. + +## Что на что влияет + +Клетка называет **место**, где связка описана; сама связка живёт там. + +| Влияет | На что | Где описано | +| --- | --- | --- | +| тип записи | сценарий — **предлагает**, подтверждает предмет работы | `task-track/SKILL.md`, «Тип записи» | +| тип записи | метку и глубину — **не влияет, и это записано явно** | там же | +| сценарий | режим прогона: обслуживание идёт без метки | `code-resolve/references/maintain.md` | +| метка | состав проходов обеих стадий | `code-review/SKILL.md`, «Метки» | +| метка | глубину темы: против чего смотрят и как | там же | +| режим прогона | состав проходов и саму возможность запуска прохода | `code-review/SKILL.md`, «Прогон без change» | +| категория документа | заводит ли документ направление проверки | `canon.md`, «Три категории» | +| severity | что с находкой делают дальше | `code-review/SKILL.md`, «Что происходит с находками» | + +**Две клетки пусты, и это сказано намеренно, а не забыто.** + +**Категория документа × режим прогона.** На прогоне **с меткой** своя тема +проекта закрыта при любом значении: `review-basics` — приёмник проектных тем и +при `small`, и при `large`, и при `medium`. На прогоне **без метки** план +фиксирован сценарием — `autotests`, `operations`, `conventions`, — и своих тем +проекта в нём нет. Значит, документ, заведённый проектом как тема, на +обслуживании не смотрит никто, и строкой это нигде не называется. + +**Режим прогона × severity.** Триаж обязателен всегда, в том числе без метки. Но +часть оснований `critical` — построенный путь к отказу, замер — добывается +проходами, которые без метки не запускаются. Значит ли это, что `critical` на +прогоне обслуживания не бывает, или что его основания там другие, не сказано. + +## Режим прогона + + + +**Прогон ревью идёт в одном из двух режимов, и режим — не глубина.** + +- **С меткой** — обычный прогон по change: разметку сделал `review-scope`, состав + обеих стадий выведен из метки. +- **Без метки** — прогон сценария обслуживания: change нет, размечать нечего, + план фиксирован и назван сценарием. Разметчик не запускается вовсе. + +**Без метки — не то же самое, что `small`.** `small` — это суждение о размере и +сложности, снятое с изменения; отсутствие метки — утверждение, что снимать её +не с чего. Проход, подставивший себе `small` там, где метки нет, вывел бы +глубину из ничего. + +**Режим правит не только состав, но и саму возможность запуска.** Проход, у +которого запуск задан меткой, без метки не имеет ответа на вопрос «запускаться +ли» — и ответ ему даёт план сценария, а не умолчание. + + + +## Коды выхода + + + +**Коды выхода — общий словарь всех скриптов `av-dev`. Ветвись на коде, а не на +тексте вывода.** + +| Код | Что случилось | +| --- | --- | +| 0 | сошлось | +| 1 | дрейф: рабочая ситуация, чинится | +| 2 | ошибка употребления: аргументы или нарушенное правило | +| 3 | окружение: не тот каталог, битый конфиг, нет инструмента | +| 4 | внутренний сбой — дефект скрипта, доложить | + +**Различать 1 и 3 обязательно.** «Дрейф» — рабочая ситуация, и чинится она +правкой предмета; «окружение» — нерабочая, и повтор той же командой не поможет. +Одинаковая реакция на них неверна в обоих случаях. + + + +Словарь был объявлен «общим» в одиннадцати местах, и каждое объявление +перечисляло **свой** набор соседей: «тот же, что у `tasks.py`», «тот же, что у +`tasks.py`, `docs.py` и `copies.py`», «общий словарь скриптов av-dev». Ни одно из +них не было домом, все — списки по памяти. Отсюда дом здесь: у словаря семь +скриптов-потребителей и ни одного владельца. diff --git a/av-dev/skills/code-openspec/SKILL.md b/av-dev/skills/code-openspec/SKILL.md index 6eaaa71..112f5c2 100644 --- a/av-dev/skills/code-openspec/SKILL.md +++ b/av-dev/skills/code-openspec/SKILL.md @@ -74,10 +74,30 @@ python3 $os check --dir <корень> # форма config.yaml в проек python3 $os form # слепок формы против живого OpenSpec ``` -**Коды выхода — общий словарь скриптов av-dev:** 0 сошлось, 1 дрейф, 2 ошибка -употребления, 3 окружение, 4 внутренний сбой. Ветвись на коде, а не на тексте. -Различать 1 и 3 обязательно: «форма разошлась» — рабочая ситуация, «openspec не -отвечает» — нерабочая. +**Копия.** Дом словаря — `shared/axes.md` в репозитории плагина: словарь общий +для всех скриптов, и ни один скилл им не владеет. Правится дом, а не этот файл. + + + +**Коды выхода — общий словарь всех скриптов `av-dev`. Ветвись на коде, а не на +тексте вывода.** + +| Код | Что случилось | +| --- | --- | +| 0 | сошлось | +| 1 | дрейф: рабочая ситуация, чинится | +| 2 | ошибка употребления: аргументы или нарушенное правило | +| 3 | окружение: не тот каталог, битый конфиг, нет инструмента | +| 4 | внутренний сбой — дефект скрипта, доложить | + +**Различать 1 и 3 обязательно.** «Дрейф» — рабочая ситуация, и чинится она +правкой предмета; «окружение» — нерабочая, и повтор той же командой не поможет. +Одинаковая реакция на них неверна в обоих случаях. + + + +Здесь это значит: «форма разошлась» — рабочая ситуация, «openspec не отвечает» — +нерабочая. `check` проверяет форму, и каждая проверка — про молчащий пробел, а не про вкус: каталог есть; имя именно `config.yaml` (`config.yml` OpenSpec не читает и об этом diff --git a/av-dev/skills/code-openspec/scripts/openspec.py b/av-dev/skills/code-openspec/scripts/openspec.py index 713a992..072fc9e 100644 --- a/av-dev/skills/code-openspec/scripts/openspec.py +++ b/av-dev/skills/code-openspec/scripts/openspec.py @@ -16,12 +16,8 @@ PyYAML в стандартной библиотеке нет. Всё проверяемое различимо построчно, комментарии отброшены, ключи верхнего уровня стоят в первой колонке. -Коды выхода — общий словарь скриптов av-dev: - 0 сошлось - 1 дрейф: форма разошлась с ожидаемой - 2 ошибка употребления: аргументы - 3 окружение: не тот каталог, инструмент не отвечает - 4 внутренний сбой +Коды выхода — общий словарь скриптов av-dev; дом словаря и разбор «дрейф +против окружения» — av-dev/shared/axes.md. Значения — в константах ниже. """ from __future__ import annotations diff --git a/av-dev/skills/code-resolve/SKILL.md b/av-dev/skills/code-resolve/SKILL.md index a6cf1a9..c155915 100644 --- a/av-dev/skills/code-resolve/SKILL.md +++ b/av-dev/skills/code-resolve/SKILL.md @@ -126,6 +126,9 @@ description: "Взять одну задачу и довести её до за ## Развилка: какой сценарий +Сценарий — ось процесса; перечень осей и их границ — +[shared/axes.md](../../shared/axes.md). + Она в два вопроса, и оба стоят до всякой работы. **Первый: есть ли у задачи один очевидный способ решения?** diff --git a/av-dev/skills/code-review/SKILL.md b/av-dev/skills/code-review/SKILL.md index ddcb355..718e1cd 100644 --- a/av-dev/skills/code-review/SKILL.md +++ b/av-dev/skills/code-review/SKILL.md @@ -313,6 +313,11 @@ charter'а, а модель потом двигает калибровка, и ## Метки +**«Стадия» и «ступень» — разные членения, и путать их нельзя.** Стадий ревью +две — дизайна и кода, — и они видны снаружи: их зовёт `av-dev:code-resolve` в +разных точках цикла. Ступеней внутри прогона кода пять, они нумерованы и наружу +не выходят. Перечень осей процесса целиком — [shared/axes.md](../../shared/axes.md). + **Классификация задачи выдаёт ровно одно значение — метку**: `small`, `medium` или `large`. Это **единственный вход, по которому конвейер выбирает исполнителей**: и на дизайне, и на коде состав читается из неё, а не из класса @@ -402,7 +407,7 @@ flowchart TD Отсюда состав обеих стадий: -| Метка | Когда | Ревью дизайна | Ревью кода: стадии | Проходов всего | Доля задач | +| Метка | Когда | Ревью дизайна | Ревью кода: ступени | Проходов всего | Доля задач | |---|---|---|---|---|---| | `small` | малое **и** знакомое: багфикс, локальная правка, доки | `specs` | 1, 2, 5 (+3 при своих темах) | **5–6** | **до трети, и меньше, чем `medium`** | | `medium` | **рабочее умолчание**: среднее и знакомое | `specs`, `rubric` | 1, 2, 3, 5 | **7** | **большинство** | @@ -463,7 +468,7 @@ flowchart TD ```mermaid flowchart TD plan[/"план разметки задачи
(готов до ревью кода)"/] - autotests["autotests
(стадия 1, держит машину)"] + autotests["autotests
(ступень 1, держит машину)"] specs["specs"] code["code"] basics["basics
(medium: темы ядра и свои;
small, large: только свои темы проекта)"] @@ -513,7 +518,7 @@ flowchart TD Ресурс один и неделимый: **машина** — тесты, поднятый сервис, СУБД, порты, диск. Проходы, заявившие его, сериализуются между собой при любой метке и на любой -стадии; порядок внутри цепочки произволен. +ступени; порядок внутри цепочки произволен. | Проход | Держит машину | Почему | |---|---|---| @@ -653,6 +658,30 @@ flowchart TD (тулчейн и сборка, зависимости, гит-хуки, перенос, чистка). Он приходит **без change**: у работы, не меняющей поведения, дельта-спек нет по построению. +**Копия.** Дом оси — `shared/axes.md` в репозитории плагина: режим делят конвейер, +сценарий обслуживания и два устава, и ни один из них им не владеет. Правится дом, +а не этот файл. + + + +**Прогон ревью идёт в одном из двух режимов, и режим — не глубина.** + +- **С меткой** — обычный прогон по change: разметку сделал `review-scope`, состав + обеих стадий выведен из метки. +- **Без метки** — прогон сценария обслуживания: change нет, размечать нечего, + план фиксирован и назван сценарием. Разметчик не запускается вовсе. + +**Без метки — не то же самое, что `small`.** `small` — это суждение о размере и +сложности, снятое с изменения; отсутствие метки — утверждение, что снимать её +не с чего. Проход, подставивший себе `small` там, где метки нет, вывел бы +глубину из ничего. + +**Режим правит не только состав, но и саму возможность запуска.** Проход, у +которого запуск задан меткой, без метки не имеет ответа на вопрос «запускаться +ли» — и ответ ему даёт план сценария, а не умолчание. + + + **Метка на таком прогоне не назначается, и разметчик не зовётся.** Обе его оси здесь не определены: размер он выводит из `proposal.md`, `design.md`, `tasks.md` и дельта-спек, а сложность — из формы решения, которая у обслуживания либо @@ -687,7 +716,7 @@ change**: у работы, не меняющей поведения, дельт проект семантикой гейта в `CLAUDE.md`; не объявил — это строка границ покрытия, а не догадка прохода. -## Стадия 1 — Автотесты (обязательна при любой метке) +## Ступень 1 — Автотесты (обязательна при любой метке) Агент `review-autotests`, тема `autotests`. Запускает команду гейта из семантики гейта в `CLAUDE.md` и интерпретирует вывод. @@ -714,7 +743,7 @@ change**: у работы, не меняющей поведения, дельт Шаги, которые красят гейт безусловно, перечислены в `CLAUDE.md` с причиной. Проходу запрещено списывать такой отказ в мелочь. -## Стадия 2 — Сверка (обязательна при любой метке) +## Ступень 2 — Сверка (обязательна при любой метке) Два прохода, оба против **записанного** критерия. Машину не держат ни один, ребра между ними нет — уходят одним сообщением сразу после зелёного гейта, вместе со @@ -728,7 +757,7 @@ change**: у работы, не меняющей поведения, дельт обычном входе: необработанная ветка отказа, пустое значение, граница диапазона, перепутанный операнд, неосвобождённый ресурс, неверно применённый интерфейс библиотеки. Вторая сверяет с конвенциями проекта, беря только ту их часть, - которая **не выражается правилом**: механизируемое уже проверила стадия 1. + которая **не выражается правилом**: механизируемое уже проверила ступень 1. **На `small` у него есть третья, узкая обязанность** — сверить дифф с записанными инвариантами `CLAUDE.md` по темам `security`, `operations` и `architecture`, потому что с этой меткой `basics` не идёт. Потолок 1 находка @@ -756,7 +785,7 @@ change**: у работы, не меняющей поведения, дельт недосмотренной темы. Recall темы `conventions` равен длине конвенций проекта — это предел любой -сверки, и ровно ради него существуют стадии 3 и 4. +сверки, и ровно ради него существуют ступени 3 и 4. **Оба прохода на верхней модели, и по одной причине — цене пропуска.** У `specs` это направление `code → spec`: надо заметить **отсутствие** — тихий фолбэк, @@ -765,7 +794,7 @@ Recall темы `conventions` равен длине конвенций прое границах покрытия; прочие проходы с мнением держат `opus` из-за цены **ложных** находок, эти двое — из-за цены пропущенных. -## Стадия 3 — Темы (`medium` целиком; `small` и `large` — только свои темы проекта) +## Ступень 3 — Темы (`medium` целиком; `small` и `large` — только свои темы проекта) Агент `review-basics`. Один проход, машину не держит, ничего не запускает и не меряет — уходит одним сообщением вместе со стадией 2, сразу после зелёного гейта. @@ -802,7 +831,7 @@ Recall темы `conventions` равен длине конвенций прое взгляда на ось времени — значит изменение, которое не откатывается обратной правкой, на `small` не идёт вовсе, каким бы малым оно ни было. -## Стадия 4 — Доказательство (только `large`) +## Ступень 4 — Доказательство (только `large`) Три прохода, и все три уходят сразу после зелёного гейта, в одном ряду со стадией 2. Каждый берёт свою тему и доводит её до **доказательства**: @@ -831,7 +860,7 @@ Recall темы `conventions` равен длине конвенций прое ось времени и эксплуатации. Ровно поэтому они и стоят денег: оракул добывается запуском, а запуск — это машина, цепочка и часы. -Раньше эта пара стояла в `medium`, то есть на большинстве задач. Стадия +Раньше эта пара стояла в `medium`, то есть на большинстве задач. Ступень переехала в `large` **сознательно и по цене, а не потому, что перестала находить**: она осталась самой ценной, но её ценность оплачивается на каждой задаче, а получается — на немногих. Что из-за этого перестало проверяться на младших метках, названо в «Честном пределе» и обязано идти строкой в границы покрытия @@ -849,7 +878,7 @@ Recall темы `conventions` равен длине конвенций прое записки; для архитектурного — что граница домена берётся из `passport.*`, а не из истории решений. Обе потери названы в «Честном пределе». -**Условие стадии и есть условие метки `large`:** изменение крупное **или** +**Условие ступени и есть условие метки `large`:** изменение крупное **или** незнакомое — любая из двух осей. Разведены они не для красоты: у архитектурного прохода работа появляется от **размера** (трогается несколько слоёв разом или в проекте становится больше сущностей, чем было), у меряющей пары — от @@ -870,7 +899,7 @@ Recall темы `conventions` равен длине конвенций прое конфигурируемость, подстраховка поверх подстраховки. Потолок — 3 находки плюс секция «дешевле переделать до мерджа». -## Стадия 5 — Triage (обязательна) +## Ступень 5 — Triage (обязательна) Агент `review-triage`. **Единственный сток графа и единственный, кто агрегирует.** Входящие рёбра — все запущенные проходы: пока хоть один не вернул отчёт, триаж не diff --git a/av-dev/skills/code-review/references/finding-contract.md b/av-dev/skills/code-review/references/finding-contract.md index e8f36be..88e1429 100644 --- a/av-dev/skills/code-review/references/finding-contract.md +++ b/av-dev/skills/code-review/references/finding-contract.md @@ -43,6 +43,8 @@ ## Шкала severity +Severity — ось процесса; перечень осей — [shared/axes.md](../../../shared/axes.md). + | Severity | Что это | Пример | |---|---|---| | `critical` | нарушение инварианта проекта, потеря или порча данных, утечка секрета, построенный путь к отказу | запись потеряна при слиянии; тело пользовательской выгрузки в поле лога | diff --git a/av-dev/skills/doc-canon/SKILL.md b/av-dev/skills/doc-canon/SKILL.md index b49ec57..f1ce87f 100644 --- a/av-dev/skills/doc-canon/SKILL.md +++ b/av-dev/skills/doc-canon/SKILL.md @@ -58,11 +58,30 @@ python3 $ds bump --dir <корень> # поднять вер не проверяет никто, и это надо сказать строкой доклада, а не считать, что она верна. -**Коды выхода — тот же словарь, что у `tasks.py`:** 0 сошлось, 1 дрейф, 2 ошибка -употребления, 3 окружение, 4 внутренний сбой. Ветвись на коде, а не на тексте. +**Копия.** Дом словаря — `shared/axes.md` в репозитории плагина: словарь общий +для всех скриптов, и ни один скилл им не владеет. Правится дом, а не этот файл. -Различать 1 и 3 обязательно: «дрейф раскладки» — рабочая ситуация, «это не -корень проекта» — нерабочая. + + +**Коды выхода — общий словарь всех скриптов `av-dev`. Ветвись на коде, а не на +тексте вывода.** + +| Код | Что случилось | +| --- | --- | +| 0 | сошлось | +| 1 | дрейф: рабочая ситуация, чинится | +| 2 | ошибка употребления: аргументы или нарушенное правило | +| 3 | окружение: не тот каталог, битый конфиг, нет инструмента | +| 4 | внутренний сбой — дефект скрипта, доложить | + +**Различать 1 и 3 обязательно.** «Дрейф» — рабочая ситуация, и чинится она +правкой предмета; «окружение» — нерабочая, и повтор той же командой не поможет. +Одинаковая реакция на них неверна в обоих случаях. + + + +Здесь это значит: «дрейф раскладки» — рабочая ситуация, «это не корень проекта» — +нерабочая. ### Граница механизируемого — объявляется вслух diff --git a/av-dev/skills/doc-canon/references/canon.md b/av-dev/skills/doc-canon/references/canon.md index 0884da4..96727c1 100644 --- a/av-dev/skills/doc-canon/references/canon.md +++ b/av-dev/skills/doc-canon/references/canon.md @@ -71,6 +71,9 @@ openspec/ ## Три категории документов +Категория документа — ось процесса; перечень осей и того, чего каждая **не** +решает, — [shared/axes.md](../../../shared/axes.md). + Раньше здесь стояло плоское правило «каждый документ `docs/` — тема ревью». Оно неверно ровно наполовину: паспорт и схема хранилища ревью нужны, но темами не являются, а журнал решений и журнал наблюдений ревью изменения не нужны вовсе. diff --git a/av-dev/skills/doc-canon/scripts/docs.py b/av-dev/skills/doc-canon/scripts/docs.py index 73e66ae..7e33a02 100644 --- a/av-dev/skills/doc-canon/scripts/docs.py +++ b/av-dev/skills/doc-canon/scripts/docs.py @@ -6,12 +6,8 @@ маркеры долга и две сверки с кодом. Смысловые дубли и оставшееся в архитектуре поведение судит агент — скрипт об этом говорит вслух в конце отчёта. -Коды выхода — тот же словарь, что у tasks.py: - 0 сошлось - 1 дрейф раскладки (рабочая ситуация, чинится) - 2 ошибка употребления - 3 окружение: не тот каталог, битый конфиг - 4 внутренний сбой +Коды выхода — общий словарь скриптов av-dev; дом словаря и разбор «дрейф +против окружения» — av-dev/shared/axes.md. Значения — в константах ниже. """ from __future__ import annotations diff --git a/av-dev/skills/task-track/SKILL.md b/av-dev/skills/task-track/SKILL.md index eabc8b1..373edc4 100644 --- a/av-dev/skills/task-track/SKILL.md +++ b/av-dev/skills/task-track/SKILL.md @@ -256,7 +256,9 @@ stateDiagram-v2 ## Тип записи -**Тип — единственная ось, и он решает, что с записью можно делать.** Дом типа — +**Тип — единственная ось этого скилла, и он решает, что с записью можно делать.** +Перечень осей всего процесса и того, чего каждая **не** решает, — +[shared/axes.md](../../shared/axes.md). Дом типа — **поле меты `Тип` первой строкой**; эмодзи в заголовке H1 от него производна, её ставит `add` и чинит `check --fix`. @@ -398,18 +400,31 @@ python3 $tk init --dir D [--sections …] [--items …] [--backlog …] … python3 $tk adopt scan --from … | apply --plan … # разовая адаптация, references/adopt.md ``` -**Коды выхода — единый словарь; на нём ветвятся скиллы, а не на тексте вывода:** +**Копия.** Дом словаря — `shared/axes.md` в репозитории плагина: словарь общий +для всех скриптов, и ни один скилл им не владеет. Правится дом, а не этот файл. -| Код | Что случилось | Что делать | -| --- | --- | --- | -| 0 | сошлось / сделано | дальше по сценарию | -| 1 | **только `check`:** найден дрейф индексов и файлов | `check --fix`, остаток разобрать | -| 2 | ошибка употребления: аргументы или нарушенное правило | читать сообщение, это отказ по существу | -| 3 | окружение: каталог не найден, конфиг битый или мимо диска | чинится путём или `.av-dev.toml` в корне, повтор не поможет | -| 4 | внутренний сбой | дефект скрипта, доложить | + -Различать 1 и 3 обязательно: «дрейф в беклоге» — рабочая ситуация, «каталога -нет» — нерабочая, и одинаковая реакция на них была бы неверна в обоих случаях. +**Коды выхода — общий словарь всех скриптов `av-dev`. Ветвись на коде, а не на +тексте вывода.** + +| Код | Что случилось | +| --- | --- | +| 0 | сошлось | +| 1 | дрейф: рабочая ситуация, чинится | +| 2 | ошибка употребления: аргументы или нарушенное правило | +| 3 | окружение: не тот каталог, битый конфиг, нет инструмента | +| 4 | внутренний сбой — дефект скрипта, доложить | + +**Различать 1 и 3 обязательно.** «Дрейф» — рабочая ситуация, и чинится она +правкой предмета; «окружение» — нерабочая, и повтор той же командой не поможет. +Одинаковая реакция на них неверна в обоих случаях. + + + +Здесь это значит: код 1 приходит **только от `check`** — найден дрейф индексов и +файлов, чинится `check --fix`, остаток разбирается руками. Код 3 — каталог не +найден, конфиг битый или мимо диска: чинится путём или `.av-dev.toml` в корне. Тип — английское ключевое слово `goal` / `feature` / `fix` / `chore` / `research` (как и прочие токены команд), у `add` **обязательное**: без него diff --git a/av-dev/skills/task-track/scripts/tasks.py b/av-dev/skills/task-track/scripts/tasks.py index 33ad2df..4096b82 100755 --- a/av-dev/skills/task-track/scripts/tasks.py +++ b/av-dev/skills/task-track/scripts/tasks.py @@ -77,15 +77,11 @@ goal | feature | fix | chore | research, по-английски, как и пр Каталог задач: `--dir` (обязан быть внутри рабочего каталога) → `tasks/` вверх от текущего каталога. Прежние раскладки (`docs/tasks`, `doc/tasks`) читаются, -пока живы непереехавшие проекты; переезд — запись 11 журнала версий канона. +пока живы непереехавшие проекты; переезд — запись 11 закрытого журнала канона (changelog-before-merge.md). -Коды выхода (единый словарь, на нём ветвятся скиллы): - - 0 всё сошлось / операция выполнена - 1 расхождения найдены (только check: дрейф индексов и файлов) - 2 ошибка употребления: неверные аргументы, нарушенное правило процесса - 3 окружение: каталог задач не найден, конфиг битый или указывает в никуда - 4 внутренний сбой (непойманное исключение) — это дефект скрипта +Коды выхода — общий словарь скриптов av-dev; дом словаря и разбор «дрейф +против окружения» — av-dev/shared/axes.md. Значения — в константах ниже; здесь +код 1 приходит только от check. Тело задачи (контекст, критерии, вопросы, ссылки) остаётся агенту — add кладёт заголовок, мета-блок и шаблон-плейсхолдер; агент дописывает редактором. diff --git a/scripts/addresses.py b/scripts/addresses.py index 12b76e3..aa6a717 100644 --- a/scripts/addresses.py +++ b/scripts/addresses.py @@ -26,12 +26,8 @@ addresses.py [корень] -Коды выхода — общий словарь скриптов av-dev: - 0 сошлось - 1 дрейф: неизвестный или упразднённый адрес - 2 ошибка употребления - 3 окружение: не тот каталог, перечень владельца недоступен - 4 внутренний сбой +Коды выхода — общий словарь скриптов av-dev; дом словаря и разбор «дрейф +против окружения» — av-dev/shared/axes.md. Значения — в константах ниже. """ from __future__ import annotations diff --git a/scripts/copies.py b/scripts/copies.py index b1eac9f..1d6950c 100644 --- a/scripts/copies.py +++ b/scripts/copies.py @@ -29,12 +29,8 @@ повелительное наклонение, соседние разделы — принадлежит месту, а не дому, и сверке не подлежит. -Коды выхода — тот же словарь, что у tasks.py и docs.py: - 0 сошлось - 1 копия разошлась с домом (или дом остался без копий) - 2 ошибка употребления: незакрытый маркер, дубль id, копия без дома - 3 окружение: не тот каталог - 4 внутренний сбой +Коды выхода — общий словарь скриптов av-dev; дом словаря и разбор «дрейф +против окружения» — av-dev/shared/axes.md. Значения — в константах ниже. """ from __future__ import annotations diff --git a/scripts/diagrams.py b/scripts/diagrams.py index 780d3d4..2f4e0dc 100644 --- a/scripts/diagrams.py +++ b/scripts/diagrams.py @@ -41,12 +41,8 @@ mermaid-cli со своим chromium, секунда с лишним. Отсюд путь.md …` смотрит только их — так гейт платит за диаграммы ровно того файла, который правят. Без аргументов обходится весь репозиторий, как и раньше. -Коды выхода — тот же словарь, что у tasks.py, docs.py и copies.py: - 0 все диаграммы рендерятся - 1 диаграмма не рендерится - 2 ошибка употребления: аргументы - 3 окружение: не тот каталог, нет mermaid-cli - 4 внутренний сбой +Коды выхода — общий словарь скриптов av-dev; дом словаря и разбор «дрейф +против окружения» — av-dev/shared/axes.md. Значения — в константах ниже. """ from __future__ import annotations diff --git a/scripts/frontmatter.py b/scripts/frontmatter.py index 6574bed..46606db 100644 --- a/scripts/frontmatter.py +++ b/scripts/frontmatter.py @@ -32,12 +32,8 @@ Правят обычно один, и разойтись они успели уже трижды из четырёх. `copies.py` этот класс не берёт: он смотрит markdown, а манифест — json. -Коды выхода — тот же словарь, что у tasks.py, docs.py, copies.py и diagrams.py: - 0 все фронтматтеры и описания в порядке - 1 расхождение - 2 ошибка употребления: аргументы - 3 окружение: не тот каталог - 4 внутренний сбой +Коды выхода — общий словарь скриптов av-dev; дом словаря и разбор «дрейф +против окружения» — av-dev/shared/axes.md. Значения — в константах ниже. """ from __future__ import annotations diff --git a/scripts/resync.py b/scripts/resync.py index eff67aa..2021e78 100644 --- a/scripts/resync.py +++ b/scripts/resync.py @@ -22,11 +22,8 @@ resync.py [корень] -Коды выхода — общий словарь скриптов av-dev: - 0 готово (в том числе «нечего пересобирать») - 2 ошибка употребления: незакрытый маркер, дубль id, копия без дома - 3 окружение: не тот каталог - 4 внутренний сбой +Коды выхода — общий словарь скриптов av-dev; дом словаря и разбор «дрейф +против окружения» — av-dev/shared/axes.md. Значения — в константах ниже. """ from __future__ import annotations