конфиг: одна версия и один служебный файл, .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
+26 -42
View File
@@ -407,7 +407,7 @@ python3 $tk adopt scan --from … | apply --plan … # разовая адап
| 0 | сошлось / сделано | дальше по сценарию |
| 1 | **только `check`:** найден дрейф индексов и файлов | `check --fix`, остаток разобрать |
| 2 | ошибка употребления: аргументы или нарушенное правило | читать сообщение, это отказ по существу |
| 3 | окружение: каталог не найден, конфиг битый или мимо диска | чинится путём или `<каталог задач>/.tasks.json`, повтор не поможет |
| 3 | окружение: каталог не найден, конфиг битый или мимо диска | чинится путём или `.av-dev.toml` в корне, повтор не поможет |
| 4 | внутренний сбой | дефект скрипта, доложить |
Различать 1 и 3 обязательно: «дрейф в беклоге» — рабочая ситуация, «каталога
@@ -494,38 +494,24 @@ python3 $tk adopt scan --from … | apply --plan … # разовая адап
[fix](references/task-fix.md) · [chore](references/task-chore.md) ·
[research](references/task-research.md).
## Версия формата
## Версия раскладки
Формат каталога задач меняется, и проект должен знать, к какой его версии
приведён. Число живёт ключом `tasks` в `<каталог задач>/.tasks.json`, журнал
версий — [references/changelog.md](references/changelog.md), сверяет их
`tasks.py check`: отстало — строка расхождения, ушло вперёд — устарел плагин.
Формат каталога задач меняется, и проект должен знать, к какой версии он
приведён. Число живёт ключом `version` в `.av-dev.toml` в корне репозитория,
журнал версий — [журнал скилла `doc-canon`](../doc-canon/references/changelog.md),
сверяет их `tasks.py check`: отстало — строка расхождения, ушло вперёд — устарел
плагин. Обратной совместимости нет: есть «приведён» и «не приведён».
**Версия своя, а не канона документов.** Плагин ставится в одиночку: проект,
взявший учёт работ без `av-dev-docs`, каталога `docs/` не имеет вовсе, а значит
не имеет и версии канона — сверять было бы не с чем. Обратной совместимости у
формата нет: есть «приведён» и «не приведён».
**Версия одна на всю раскладку — и на документы, и на задачи.** Своя у каталога
задач была, пока плагинов было три и ставились они порознь: проект мог взять
учёт работ без канона документов, и общее число оказалось бы домом, которого у
половины проектов нет. Плагин один — довод ушёл, а два числа оставляли бы
вопрос, по какому журналу повышать.
**`upgrade` — повысить каталог до текущего формата:**
1. `python3 $tk check --dir D` — первая же строка расхождений называет версию
проекта и версию скрипта. Проект новее скрипта — **обнови маркетплейс**, а не
проект: это отстал плагин.
2. Иди по [журналу](references/changelog.md) снизу вверх от версии проекта до
текущей и делай названное в каждой записи. Записи независимы и применяются по
порядку.
3. Подними `tasks` в `.tasks.json` до текущей — руками, последним шагом. Раньше
времени поднятое число объявляет каталог приведённым к формату, шагов
которого никто не делал; `check --fix` этого не пишет намеренно.
4. `check --dir D` ещё раз — до отсутствия расхождений.
Записи журнала описывают **что сделать проекту**. Если запись этого не говорит —
это дефект журнала, и о нём надо сказать, а не догадываться.
**Канон документов сюда не вмешивается.** Его журнал двигает своё число в
`docs/.docs.json` и вправе сказать «позови этот скилл», но не двигать версию
формата задач: две версии, ходящие по одному журналу, разъедутся на первом же
проекте, где стоит один плагин без другого.
**Повышает проект скилл `av-dev:doc-canon`, операция `upgrade`** — он идёт по
журналу, двигает число и зовёт этот скилл там, где запись касается задач. Здесь
повышения нет намеренно: две операции, двигающие одно число, разъезжаются на
первом же проекте, где прошла только одна из них.
## Сценарии
@@ -689,19 +675,17 @@ python3 $tk adopt scan --from … | apply --plan … # разовая адап
действительно новый, а перевод чужой раскладки делает `av-dev:doc-canon`.
У скрипта поиск вверх по дереву ещё жив — он для непереведённых проектов, и
полагаться на него скилл не должен: молча найденный чужой каталог это дрейф.
- **Версия формата и настройки живут в `<каталог задач>/.tasks.json`** — свой
файл у своего плагина: ключ `tasks` с версией формата плюс **имена** файлов и
заголовков, и последние только если отличаются от умолчания. Неизвестный
ключ — код 3 на любой команде, так что лишнее слово в этом объекте
останавливает работу с задачами целиком.
- **Версия и настройки живут в `.av-dev.toml` в корне репозитория** — версия
ключом `version`, настройки каталога секцией `[tasks]`: `dir` — где каталог
лежит, плюс **имена** файлов и заголовков, и последние только если отличаются
от умолчания. Неизвестный ключ в секции — код 3 на любой команде, так что
лишнее слово останавливает работу с задачами целиком.
Дом именно свой, а не `docs/.docs.json`, потому что `docs/` принадлежит
плагину канона: проект, поставивший учёт работ без него, каталога `docs/` не
имеет вовсе. Прежний ключ `tasks` в `docs/.pm.json` читается, **только когда
своего файла нет** — для проектов, заведённых до раскола плагинов; скрипт при
этом говорит замечанием, куда его перенести. Есть оба — побеждает свой, и об
этом тоже говорится вслух: молча выбранный из двух конфиг это дрейф. Версию
прежний дом не знает и знать не может — она читается только из своего файла.
Дом в корне, а не внутри каталога задач, по двум причинам: настройка, лежащая
внутри настраиваемого каталога, не смогла бы сказать, **где он**; и версия
одна на весь плагин, а корень есть и у проекта без `docs/`. Прежние
`<каталог задач>/.tasks.json` и `docs/.docs.json` не читаются — увидев их,
скрипт говорит «прежняя раскладка» и зовёт `upgrade`.
- **Секции беклога** берутся из заголовков `##` индекса как есть; их количество
и названия — дело проекта (умолчание `Ядро` / `Инфра`). **В конфиге их нет** —
второй список разошёлся бы с заголовками молча.