конфиг: одна версия и один служебный файл, .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
+18 -16
View File
@@ -27,7 +27,8 @@ description: Привести проект к канону документов
записок разведки, и дом у них общий — `shared/language.md` в репозитории
плагинов, а этот файл его копия. Вычитывают их два прохода по охвату:
документы — `doc-wording`, записи каталога задач — `task-wording`.
- [references/changelog.md](references/changelog.md) — журнал версий канона.
- [references/changelog.md](references/changelog.md) — журнал версий раскладки;
закрытые журналы до слияния плагинов лежат рядом.
## Три правила, из которых всё следует
@@ -184,7 +185,8 @@ capability), `openspec/config.yaml`.
Порядок важен — он минимизирует окно, в котором ссылки битые:
1. `docs/.docs.json` с `{"canon": <текущая версия>}` и путём миграций, если БД есть;
1. `.av-dev.toml` в корне: `version = <текущая версия>` и путь миграций в
`[docs]`, если БД есть;
2. каталоги канона и скелет **по [references/skeletons.md](references/skeletons.md)**:
незаполненное — одной честной информативной строкой, а не «TBD»;
3. **OpenSpec, если его нет или `config.yaml` остался примером** — **вызови
@@ -209,10 +211,10 @@ capability), `openspec/config.yaml`.
**Шагов в гейте три, и они независимы.** `docs.py check` не тянет за собой
ни задачи, ни конвейер: без своих строк дрейф каталога задач и формы
`openspec/config.yaml` перестаёт ловиться совсем. Ставь соседские шаги по
следу присутствия — `<каталог задач>/.tasks.json` есть, значит ставится
`openspec/config.yaml` перестаёт ловиться совсем. Ставь соседние шаги по
следу присутствия — каталог задач с индексом на месте, значит ставится
`tasks.py check --dir <каталог задач>`; `openspec/config.yaml` есть, значит
ставится `openspec.py check`. Следа нет — плагина в проекте нет, шаг не
ставится `openspec.py check`. Следа нет — этой части в проекте нет, шаг не
ставится, и это **строка доклада**, а не поломка: назови, чего теперь не
проверяет никто. У каждого шага своя переменная пути с тем же умолчанием на
канонический путь маркетплейса; `$CLAUDE_PLUGIN_ROOT` в гейт не подставляй —
@@ -273,7 +275,8 @@ capability), `openspec/config.yaml`.
3. Иначе иди по [changelog.md](references/changelog.md) снизу вверх от версии
проекта до текущей и делай названное в каждой записи. Записи независимы и
применяются по порядку.
4. Подними `canon` в `docs/.docs.json` до текущей.
4. Подними `version` в `.av-dev.toml` до текущей — правь **строку**, а не
переписывай файл: комментарии в нём принадлежат проекту.
5. `docs.py check`.
6. **Позови судей** — Skill `av-dev:doc-healthcheck`.
7. **Позови вычитку** — агент `doc-wording`, но **только по тем документам,
@@ -284,17 +287,16 @@ capability), `openspec/config.yaml`.
Записи журнала описывают **что сделать проекту**. Если запись этого не говорит —
это дефект журнала, и о нём надо сказать, а не догадываться.
**Каталог задач повышается своим журналом, а не этим.** У него своя версия
формата — ключ `tasks` в `<каталог задач>/.tasks.json`, — и двигает её плагин
`av-dev-tasks`. Запись канона вправе сказать «позови соседа», но не вправе
двигать чужое число: две версии, которые ходят по одному журналу, разъезжаются
на первом же проекте, поставившем один плагин без другого. Отстал каталог
задач — это скажет `tasks.py check` своей строкой гейта, а повысит скилл
`av-dev:task-track`.
**Каталог задач повышается этим же журналом.** Версия одна на всю раскладку —
`version` в `.av-dev.toml`, — и записи журнала говорят про обе половины: и про
документы, и про каталог задач. Порознь версии жили, пока плагинов было три и
проект мог взять одну половину без другой; с одним плагином два числа означали
бы только вопрос, по какому журналу повышать. Что каталог задач отстал, скажет
`tasks.py check` своей строкой гейта — той же версией, что и `docs.py`.
**Шаг 6 обязателен, и вот почему.** `check` сверяет **число** в `.docs.json` с
версией скрипта — и только его. Применена ли запись журнала **по существу**, он
не знает: проект несёт `"canon": 6` и может не иметь того, чего требовала любая
**Шаг 6 обязателен, и вот почему.** `check` сверяет **число** в `.av-dev.toml`
с версией скрипта — и только его. Применена ли запись журнала **по существу**,
он не знает: проект несёт `version = 6` и может не иметь того, чего требовала любая
из пройденных версий. Записи применяются руками (переименовать секцию, проставить
типы, дописать раздел каждому `fix`), а ручной проход по нескольким записям
подряд — ровно то место, где половина шага делается и забывается. Судьи и есть