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

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

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

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

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

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

---

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

Тип записи goal и индекс ROADMAP.md упразднены; у проекта появилась стадия — build (беклог это план стройки, порядок строк значит зависимость) или support (очередь правок, порядок значит важность).

Цель была зонтиком над параллельными направлениями — она нужна там, где список работ нельзя выстроить в один порядок. У проекта, который ведёт один человек, такого не бывает, и роадмап при этом наполовину дублировал беклог («чего ещё не умеет» = «что осталось в списке»), а вторую половину («что уже умеет») отвечают openspec/specs/ и git log индекса.

Что переехало. Индекс остался один — BACKLOG.md. Поле меты Секция стало Категория; теги goal:<слаг>, decomposed и раздел Завершение упразднены; команды list --goal, edit --goal, edit --section и ключи [tasks] roadmap, [tasks] completion_heading — тоже. Появились ключ [tasks] stage, команда tasks.py stage и флаги init --stage, adopt scan --stage.

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

1. Разобрать цели. У каждой записи типа goal в tasks/items/ два исхода, и выбирает человек: она становится обычной задачей (edit <слаг> --type feature|fix|chore|research) либо уходит (close <слаг> --reason …). Задачи, носившие её тег, живут дальше сами по себе. Скрипт этого не решает и говорит НЕОДНОЗНАЧНО.
2. Перенести содержимое ROADMAP.md. Секция Готово удаляется: «что приложение умеет» отвечают спеки, «когда это появилось» — git log. Строки Запланировано, Направления и Сопровождение — это цели, и они разбираются шагом 1. Затем удалить сам файл и ключ roadmap из .av-dev.toml, если он там был.
3. Объявить стадию — tasks.py stage build или tasks.py stage support. Приложение ещё строится и список работ линеен по зависимости — build; работает и правится точечно — support. Без ключа check отказывает: порядок строк нечем прочитать. На build секция беклога обязана остаться одна — слить полки надо руками, порядок строк в слитом списке знает только человек.
4. Поднять версию — docs.py bump. Последним шагом.
5. docs.py check и tasks.py check --dir <каталог задач> — до отсутствия дрейфа. Теги goal: и decomposed, поле Секция и старую форму меты снимет tasks.py check --fix.

---

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

Скилл doc-canon стал canon: префикс называл материал (doc-), а скилл занят не материалом, а формой — раскладкой всех частей проекта и общим повышением версии. Ни один файл проекта от этого не переехал; сменились путь к скрипту и имя вызова, а оба живут в проекте: первый — строкой гейта, второй — в CLAUDE.md и в записях задач.

Что переехало в вызовах. av-dev:doc-canon → av-dev:canon. Прочие имена не тронуты.

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

1. Поправить шаг гейта. Путь к docs.py сменился вместе с именем каталога скилла: skills/doc-canon/scripts/docs.py → skills/canon/scripts/docs.py. Шаг, который не нашёл скрипт, обязан краснеть, а не пропускаться, — проверь, что он краснеет.
2. Поправить свои вызовы скилла — grep -rn "doc-canon" --exclude-dir=.git . по проекту целиком: имя встречается в CLAUDE.md, в Taskfile, в записях задач и в документах канона. Прежнее полное имя не разрешится вовсе.
3. Поднять версию — docs.py bump. Последним шагом.
4. docs.py check и tasks.py check --dir <каталог задач> — до отсутствия дрейфа.

Проект, не прошедший запись 1, переименовывает дважды подряд — skills/canon/ → skills/doc-canon/ записью 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 <каталог задач> — до отсутствия дрейфа.

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