dev-skills/av-dev/skills/doc-canon/references/changelog.md

Журнал версий раскладки

Одна запись на версию. Проект знает свою версию из ключа version в .av-dev.toml; операция upgrade скилла av-dev:doc-canon идёт по записям снизу вверх от версии проекта до текущей и делает то, что в них названо.

Правило записи: что добавилось, что переехало, что удалено, что сделать проекту. Без последнего пункта запись бесполезна — по ней и работает upgrade.

Версия — целое число. Обратной совместимости нет: есть «приведён» и «не приведён». Версия одна на всю раскладку — и на документы канона, и на каталог задач: ведёт их один плагин, и второе число означало бы только вопрос, по какому журналу повышать.

До слияния журналов было два, и нумерация в них своя: changelog-before-merge.md — канон документов, версии 1–14; changelog-tasks-before-merge.md — формат задач, версия 1. Оба закрыты и не переписаны: адрес, верный на день записи, там и остался. Проект, отставший от канона 14, идёт сперва по ним, а потом по этому журналу — порядок назван в записи 1.

---

Версия 1 — 2026-08-13

Три плагина — av-dev-docs, av-dev-tasks и av-dev-code — слились в один, av-dev. Раскол делался под раздельную установку: проект мог взять учёт работ без документов канона или конвейер без обоих. Практика посылку не подтвердила — подмножество не понадобилось ни разу, — а платился раскол помеченными копиями общих правил и веткой «плагина нет» на каждый вызов соседа.

Что переехало в проекте. Служебных файла было два, стал один:

Было	Стало
docs/.docs.json, ключ canon	.av-dev.toml в корне, ключ version
docs/.docs.json, ключ migrations	.av-dev.toml, секция [docs]
<каталог задач>/.tasks.json, ключ tasks	тот же version: версия теперь одна
<каталог задач>/.tasks.json, имена частей	.av-dev.toml, секция [tasks]

Корень выбран потому, что он есть у обоих: и у проекта без docs/, и у проекта без каталога задач. Формат TOML — ради комментариев: файл лежит в репозитории проекта, и назначение числа читают из него самого, а не из документации плагина.

Что переехало в вызовах. Имена скиллов сменили пространство имён и получили префикс по прежнему плагину: av-dev-docs:canon → av-dev:doc-canon, av-dev-docs:init → av-dev:doc-init, av-dev-docs:docs → av-dev:doc-sync, av-dev-docs:healthcheck → av-dev:doc-healthcheck, av-dev-tasks:tasks → av-dev:task-track, av-dev-tasks:groom → av-dev:task-groom, av-dev-code:openspec → av-dev:code-openspec, av-dev-code:resolve → av-dev:code-resolve, av-dev-code:review → av-dev:code-review.

Что сделать проекту.

1. Отставшим сперва прежние журналы. Версия канона в docs/.docs.json меньше 14 — пройди записи до 14 по changelog-before-merge.md, и только потом эту. Иначе повышение объявит приведённым то, чего никто не делал.
2. Завести .av-dev.toml в корне репозитория: version = 1, секция [docs] с migrations, если ключ был, секция [tasks] с dir и теми именами частей, которые в .tasks.json отличались от умолчаний. Комментарии пиши свои — файл читает человек.
3. Удалить docs/.docs.json и <каталог задач>/.tasks.json. Прежние имена не читаются: два дома для одной версии расходятся молча. Пока старые файлы на месте, docs.py check и tasks.py check называют это прежней раскладкой.
4. Переставить плагины. av-dev-docs, av-dev-tasks и av-dev-code удалить, av-dev поставить — команды в README репозитория плагинов.
5. Поправить гейт проекта. Пути к docs.py, tasks.py и openspec.py сменились вместе с именами каталогов скиллов: skills/canon/ → skills/doc-canon/, skills/tasks/ → skills/task-track/, skills/openspec/ → skills/code-openspec/. Шаг, который не нашёл скрипт, обязан краснеть, а не пропускаться, — проверь, что он краснеет.
6. Поправить свои вызовы скиллов — в CLAUDE.md, в Taskfile, в записях задач: короткое имя разрешится в проектную копию, а прежнее полное не разрешится вовсе.
7. Найти, где проект читает служебный файл сам. Шаг гейта, скрипт, шаблон — что угодно, что брало значение из docs/.docs.json, чтобы не заводить факту второй дом. Такое чтение переезжает на .av-dev.toml и на tomllib вместо json: python3 -c 'import tomllib; print(tomllib.load(open(".av-dev.toml","rb"))["docs"]["migrations"])'. Ищется командой grep -rn "\.docs\.json\|\.tasks\.json" --exclude-dir=.git . — по проекту целиком, а не по документам: на первом же живом переезде это нашлось в Taskfile.yml, и нашёл это гейт, а не человек.
8. Поднять версию — docs.py bump. Последним шагом: число объявляет пройденными шаги журнала, и раньше времени поднятое врёт.
9. docs.py check и tasks.py check --dir <каталог задач> — до отсутствия дрейфа.

Чего делать не надо. Переписывать прошлые записи журналов под новые имена. Они описывают состояния, которые были, и адрес, верный на день записи, остаётся верным как свидетельство.