конфиг: одна версия и один служебный файл, .av-dev.toml в корне

Версий было две — канон 14 в docs/.docs.json и формат задач 1 в
<каталог задач>/.tasks.json, — и порознь они двигались потому, что плагины
ставились порознь. Плагин один, версия одна и начинается с 1; журналы обеих
прежних нумераций закрыты и лежат рядом непереписанными, действующий журнал
открывается записью о слиянии с перечнем шагов проекту.

Формат TOML взят ради комментариев: файл живёт в репозитории проекта, и
назначение числа читают из него самого. Отсюда правило записи — скрипты правят
строку, а не переписывают файл. Читатель общий, shared/config.py: два разбора
одной схемы были бы двумя домами.

Каталог задач перестал узнаваться служебным файлом и называется ключом
[tasks] dir; узнают его по индексу. Прежние файлы не читаются — увидев их,
docs.py и tasks.py называют прежнюю раскладку и зовут upgrade.
This commit is contained in:
av
2026-08-13 10:30:18 +03:00
parent 6b162c421d
commit 95c9499f06
16 changed files with 1450 additions and 1117 deletions
+36 -33
View File
@@ -45,8 +45,9 @@
CLAUDE.md памятка агенту: что это, стек, инварианты с
severity, команды, семантика гейта, запреты
AGENTS.md необязателен, лежит рядом; читается теми же
.av-dev.toml версия раскладки и настройки проверок; лежит
в корне, потому что нужен и без docs/
docs/
.docs.json версия канона и пути, нужные проверкам
passport.md | passport/ зачем и для кого; чем НЕ является; сценарии
architecture.md | architecture/ как сложено — обзор; окружение и эксплуатация
database.md | database/ схема хранилища; представление данных и настройки
@@ -100,7 +101,7 @@ openspec/
| `review.*` | процессный | — (настройка самого конвейера, слой **над** темами) |
| `adr.*` | процессный | — |
| `research.*` | процессный | — |
| `.docs.json` | процессный | — (служебный файл, не документ) |
| `.av-dev.toml` | процессный | — (служебный файл, не документ) |
**Список тем открытый, и это не послабление, а механизм.** Категории
`источник` и `процессный` **закрыты** — они перечислены здесь поимённо и
@@ -343,10 +344,10 @@ kebab-case.** Причина не эстетическая: имя файла с
### `tasks/`
**Каталог задач канону не принадлежит.** Его ведёт отдельный плагин
`av-dev-tasks` — своим скриптом, своим конфигом `<каталог>/.tasks.json`, своей
версией формата в нём же и своим журналом версий. Канон о том числе не
высказывается и его не двигает: повышает каталог задач тот, кто его ведёт.
**Каталог задач канону не принадлежит.** Его ведёт скилл `task-track` — своим
скриптом и своими проверками; где каталог лежит и как названы его части, говорит
секция `[tasks]` в `.av-dev.toml`. Версия там одна на всю раскладку: канон и
каталог задач двигаются вместе, потому что двигает их один плагин.
Канон **резервирует место** в `docs/` и внутрь не смотрит:
`docs.py` каталог не открывает, его отсутствия не считает дрейфом и согласованность
задач не проверяет. Проект, поставивший только канон документов, задач не ведёт
@@ -538,39 +539,41 @@ kebab-case.** Причина не эстетическая: имя файла с
архитектуру с кодом» задача без дна, и агент, которому её поставили, выдаёт
правдоподобную труху вместо находок.
## `docs/.docs.json`
## `.av-dev.toml`
```json
{
"canon": <текущая версия>,
"migrations": "internal/store/migrations"
}
```toml
# Раскладка av-dev в этом проекте: версия и настройки проверок.
version = 1 # версия раскладки
[docs]
migrations = "internal/store/migrations" # если БД есть
[tasks]
dir = "tasks" # каталог задач от корня репозитория
```
`canon` — версия канона, под которую проект приведён, целым числом: обратной
совместимости у канона нет, есть «приведён» и «не приведён». Число подставляет
`version` — версия раскладки, под которую проект приведён, целым числом:
обратной совместимости нет, есть «приведён» и «не приведён». Число подставляет
`init`, `adopt` или `upgrade`, и берётся оно из `docs.py version`, а не из
образца: литерал в образце протухает на первом же повышении канона.
`migrations` — путь каталога миграций, если БД есть; по нему `docs.py` делает
сверку с `database.md`.
образца: литерал в образце протухает на первом же повышении.
`[docs] migrations` — путь каталога миграций, если БД есть; по нему `docs.py`
делает сверку с `database.md`. `[tasks]` — где лежит каталог задач и как названы
его части; состав ключей описывает скилл `task-track`.
**Имя файла — имя плагина, который его завёл.** Канон документов ведёт
`av-dev-docs`, поэтому `.docs.json`; у каталога задач по тому же правилу
`.tasks.json`, у конвейера — `openspec/config.yaml`. До версии 13 файл звался
`.pm.json` — по плагину `av-dev-pm`, который распался на четыре и которого
больше нет; имя пережило владельца и указывало в пустоту. Прежнее имя `docs.py`
не читает: два дома для одной версии канона расходятся молча, а переименование
стоит одну команду (версия 13 журнала, и `check` называет её сам, когда видит
старый файл).
**Формат TOML взят ради комментариев.** Файл лежит в репозитории проекта, и
человек, открывший его через полгода, обязан прочитать в нём, что означает
число. JSON комментариев не знает, и объяснение приходилось держать в другом
файле. Отсюда же правило записи: скрипты правят **строку**, а не переписывают
файл — перезапись стёрла бы то, ради чего формат и выбран.
**Ключа `tasks` здесь больше нет.** Настройки каталога задач вернулись в свой
файл `<каталог задач>/.tasks.json`, потому что ведёт их другой плагин: конфиг,
лежащий в `docs/`, был бы домом, которого нет у проекта, поставившего учёт работ
без канона документов. Состав ключей описывает тот плагин, а не канон. Там же —
**версия формата задач**, и она своя: у проекта без `docs/` версии канона нет
вовсе, сверять её было бы не с чем. Прежний ключ читается, пока живы
непереехавшие проекты, и `tasks.py` говорит о нём замечанием на каждом
прогоне — версия 8 журнала просит его убрать.
**Файл один, и лежит он в корне.** До слияния плагинов их было два —
`docs/.docs.json` с версией канона и `<каталог задач>/.tasks.json` с версией
формата задач, — и версии двигались порознь, потому что плагины ставились
порознь. Плагин теперь один, версия одна, а корень выбран потому, что он есть и
у проекта без `docs/`, и у проекта без каталога задач. Прежние имена не
читаются: два дома для одной версии расходятся молча. Увидев их, `docs.py` и
`tasks.py` говорят «прежняя раскладка» и зовут `upgrade` — версия 1 журнала.
Ключей будет больше по мере роста проверок; неизвестный ключ `docs.py`
игнорирует, отсутствующий — считает «проверка неприменима» и говорит об этом