конфиг: одна версия и один служебный файл, .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
+24 -16
View File
@@ -117,7 +117,7 @@
со строкой «запись лежит сжатой и распаковывается целиком».
```
Нет БД — файла нет, и в `docs/.docs.json` нет ключа `migrations`.
Нет БД — файла нет, и в `.av-dev.toml` нет ключа `[docs] migrations`.
## `docs/security.md`
@@ -440,24 +440,32 @@ severity стоит здесь, а не выводится каждым прох
говорит (единственный дом, а не форма) — [canon.md](canon.md), раздел
`openspec/config.yaml`.
## `docs/.docs.json`
## `.av-dev.toml`
```json
{
"canon": <текущая версия>
}
```toml
# Раскладка av-dev в этом проекте: версия и настройки проверок.
version = <текущая версия>
[docs]
# migrations = "<путь>" — появится, когда появится БД
[tasks]
dir = "tasks"
```
`<текущая версия>` подставляет `init` или `adopt`, целым числом; берётся она из
`docs.py version` (строка «канон скрипта»), а не из памяти. Литерал здесь
протухает при каждом повышении канона, поэтому его тут и нет: незамещённый
плейсхолдер ломает разбор JSON громко, а отставшее число дало бы дрейф молча.
`docs.py version` (строка «раскладка скрипта»), а не из памяти. Литерал здесь
протухает при каждом повышении, поэтому его тут и нет: незамещённый плейсхолдер
ломает разбор TOML громко, а отставшее число дало бы дрейф молча.
Плюс `"migrations": "<путь>"`, если есть БД. Ключа `"tasks"` здесь **нет**:
настройки каталога задач и версия их формата переехали в свой файл `<каталог
задач>/.tasks.json`, потому что ведёт их другой плагин. Состав ключей —
[canon.md](canon.md).
Комментарии в файле — не украшение, а причина, по которой взят TOML: файл живёт
в чужом репозитории, и назначение числа читают из него самого. Скрипты это
учитывают и правят строку, а не переписывают файл. Состав ключей —
[canon.md](canon.md), раздел `.av-dev.toml`.
Имя файла — по плагину-владельцу, `av-dev-docs`. До версии 13 он звался
`.pm.json`, по распавшемуся `av-dev-pm`; проект с прежним именем `docs.py check`
называет отдельной строкой и зовёт переименовать.
Файл лежит **в корне репозитория**, а не в `docs/`: версия одна на всю
раскладку, и нужна она в том числе проекту, который канон документов ещё не
завёл. Прежние `docs/.docs.json` и `<каталог задач>/.tasks.json` остались от
трёх плагинов, слившихся в один; увидев их, `docs.py check` называет это прежней
раскладкой и зовёт `upgrade`.