скиллы: doc-canon стал canon, версия раскладки поднята до 2

- каталог скилла и все вызовы переименованы: префикс `doc-` называл материал,
  а скилл занят формой — раскладкой всех частей проекта и общим повышением
  версии, включая каталог задач;
- README перестроен: `canon` вынесен из семейства документов отдельным блоком
  и отдельным узлом графа, правило префиксов переформулировано, у документов
  уточнено владение — содержимым, а не раскладкой;
- заведена запись 2 журнала версий: в проекте ничего не переехало, но путь к
  `docs.py` и имя вызова живут в гейте и в `CLAUDE.md` проекта и сломаются
  молча;
- прежние адреса в записи 1 и в журнале решений оставлены как есть: журнал
  описывает состояния, которые были, и задним числом не переписывается.
This commit is contained in:
av
2026-08-13 12:53:12 +03:00
parent 3529cd8425
commit dff05ad097
34 changed files with 149 additions and 102 deletions
+122
View File
@@ -0,0 +1,122 @@
# Журнал версий раскладки
Одна запись на версию. Проект знает свою версию из ключа `version` в
`.av-dev.toml`; операция `upgrade` скилла `av-dev:canon` идёт по записям
снизу вверх от версии проекта до текущей и делает то, что в них названо.
Правило записи: **что добавилось, что переехало, что удалено, что сделать
проекту**. Без последнего пункта запись бесполезна — по ней и работает
`upgrade`.
Версия — целое число. Обратной совместимости нет: есть «приведён» и «не
приведён». Версия **одна на всю раскладку** — и на документы канона, и на
каталог задач: ведёт их один плагин, и второе число означало бы только вопрос,
по какому журналу повышать.
**До слияния журналов было два**, и нумерация в них своя:
[changelog-before-merge.md](changelog-before-merge.md) — канон документов,
версии 114; [changelog-tasks-before-merge.md](changelog-tasks-before-merge.md) —
формат задач, версия 1. Оба **закрыты и не переписаны**: адрес, верный на день
записи, там и остался. Проект, отставший от канона 14, идёт сперва по ним, а
потом по этому журналу — порядок назван в записи 1.
---
## Версия 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](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 <каталог задач>` — до отсутствия
дрейфа.
**Чего делать не надо.** Переписывать прошлые записи журналов под новые имена.
Они описывают состояния, которые были, и адрес, верный на день записи, остаётся
верным как свидетельство.