dev-skills/av-dev-pm/skills/canon/SKILL.md

name, description

name

description

canon

Привести проект к канону документов av-dev и держать его в соответствии — три операции одной машиной сравнения. check — что разошлось с текущей версией канона; adopt — перевод проекта из любой прежней раскладки (docs/specs, drafts, backlog, BRIEF.md, review-brief) в канон с переносом файлов; upgrade — повышение проекта с версии канона N до текущей по журналу версий. Использовать, когда просят проверить документацию проекта, перевести проект на канон, обновить его под новую версию канона или когда пришли в старый проект и надо понять, что в нём не так. Заведение нового проекта с нуля — скилл init.

Приведение проекта к канону

Три операции, одна машина сравнения с разными исходами:

Операция	Когда	Исход
check	начало сессии, шаг синка, гейт	что разошлось
adopt	проект в чужой раскладке	перенос в канон
upgrade	канон вырос, проект отстал	по журналу версий

Определение канона — references/canon.md. Здесь оно не пересказывается: два описания одной раскладки разъедутся, и работать будет то, которое прочитали последним. Прочитай его до первой правки.

Журнал версий — references/changelog.md.

Три правила, из которых всё следует

1. Сперва карта, потом файлы. Человеку показывается, что найдено, как разложилось и что не разложилось, — и только после подтверждения переносится хоть один файл. Массовый перенос без подтверждения разгребать дороже, чем согласовать.
2. Ничего не терять. Содержимое переезжает целиком; ссылки чинятся тем же проходом, что и перенос. Старый файл удаляется только после того, как всё его содержимое нашло дом, и это названо поимённо.
3. Что не классифицировалось — назвать. Проглоченный абзац выглядит как «всё перенеслось». Список «не разложилось» идёт в доклад целиком, с причиной по каждому пункту.

Инструмент

ds="$CLAUDE_PLUGIN_ROOT/skills/canon/scripts/docs.py"

python3 $ds check --dir <корень> [--base <rev>]   # раскладка, ссылки, версия, сверки
python3 $ds version --dir <корень>                # версия канона скрипта и проекта

Коды выхода — тот же словарь, что у tasks.py: 0 сошлось, 1 дрейф, 2 ошибка употребления, 3 окружение, 4 внутренний сбой. Ветвись на коде, а не на тексте.

Различать 1 и 3 обязательно: «дрейф раскладки» — рабочая ситуация, «это не корень проекта» — нерабочая.

Граница механизируемого — объявляется вслух

Скрипт печатает её сам последним абзацем, и эту строку из доклада выбрасывать нельзя. check, отчитавшийся «канон соблюдён» на проекте, где из шести файлов три лишние, хуже отсутствующего.

Машина проверяет пути, лишние файлы, битые ссылки, версию, нетронутые плейсхолдеры, маркеры долга и две сверки с кодом. Ты судишь о том, чего она не умеет:

• смысловой дубль — docs/specs/recognition.md описывает то же, что capability recognition. Файлы разные, содержание одно;
• поведение, оставшееся в architecture.md — раздел на 900 строк с требованиями вместо обзора;
• достаточность честной строки — «внешних зависимостей нет» это факт, «TBD» — пробел;
• протухший факт — документ ссылается на то, чего в коде уже нет.

check

1. docs.py check, при наличии базы диффа — с --base.
2. Прочитай то, что скрипт проверить не может (список выше), по документам, которых касалась работа. Не «заодно по всему docs/».
3. Доклад: вывод скрипта строкой исхода, твои находки поимённо, граница покрытия — что смотрел и чего не смотрел.

Дрейф раскладки чинится переносом; смысловые находки — это либо правка документа, либо задача, если работы больше чем на абзац.

adopt — проект в чужой раскладке

1. Осмотрись

docs.py check — он уже назовёт упразднённые слоты с адресом, куда каждый уезжает. Плюс прочитай: CLAUDE.md, корневые *.md, openspec/specs/ (список capability), openspec/config.yaml.

2. Составь карту

Каждый найденный файл получает строку: куда едет, целиком или разбирается, что делать с оригиналом. Разбор docs/specs/ — самое дорогое место, и он делается поимённо по capability:

Что в файле	Куда
требования, сценарии, поведение	openspec/specs/<capability>/spec.md — или уже там, тогда файл дубль
компоненты, транспорты, раскладка, деплой	docs/architecture.md
конвенции чужой системы, формат чужих данных	docs/research/
обоснование принятого решения	docs/adr/

Дубль удаляется только после поимённой сверки: открыть спеку capability, открыть файл, убедиться, что в файле нет ничего сверх спеки. Нашлось сверх — сперва переезжает в спеку дельтой, потом файл удаляется.

3. Покажи карту человеку

AskUserQuestion, не больше трёх вопросов за итерацию, рекомендация первым вариантом. Показывается: сколько файлов, куда каждый, спорные отнесения, список «не разложилось». Механику (порядок строк, имена файлов внутри research/) не выноси — это не развилка.

4. Перенеси

Порядок важен — он минимизирует окно, в котором ссылки битые:

1. docs/.pm.json с {"canon": <текущая версия>} и путём миграций, если БД есть;
2. каталоги канона и скелет: незаполненное — одной честной информативной строкой, а не «TBD» (см. canon.md, «Пустое называется пустым»);
3. переносы содержимого;
4. каталог задач — вызови скилл av-dev-pm:tasks, сценарий адаптации: он владеет форматом задач, включая переименование транслитных слагов в английские вместе с починкой перекрёстных ссылок;
5. починка ссылок на перенесённое во всём репозитории — docs/, openspec/, CLAUDE.md, README.md;
6. удаление оригиналов — только тех, чьё содержимое найдено в новом доме;
7. шаг docs.py check в гейт проекта;
8. docs.py check — до зелёного в механизируемой части.

5. Объяви переходное состояние

Сразу после переноса канон заполнен не весь, и это нормально, но обязано быть названо, иначе следующий агент примет скелет за поломку.

Печатается по факту: сколько документов стоят честной строкой вместо содержания, сколько маркеров долга в architecture.md, сколько задач без критериев приёмки. Закрывается порциями по ходу работы, а не одним заходом.

upgrade — канон вырос

1. docs.py version — версия проекта и версия скрипта.
2. Проект новее скрипта — обнови маркетплейс, а не проект: это отстал плагин.
3. Иначе иди по changelog.md снизу вверх от версии проекта до текущей и делай названное в каждой записи. Записи независимы и применяются по порядку.
4. Подними canon в docs/.pm.json до текущей.
5. docs.py check.

Записи журнала описывают что сделать проекту. Если запись этого не говорит — это дефект журнала, и о нём надо сказать, а не догадываться.

Чего этот скилл не делает

• Не сочиняет содержание. Пустой слот получает честную строку о том, что его наполнить пока нечем, а не выдуманный абзац. Придуманный периметр модели угроз хуже отсутствующего: по нему будут строиться находки.
• Не удаляет то, чьё содержимое не нашло дом. Оригинал живёт, пока не названо поимённо, куда переехал каждый его кусок.
• Не ведёт содержимое канона — это скилл docs. Здесь только раскладка.
• Не заводит проект с нуля — это скилл init.
• Не правит историю. В старых коммитах старые пути остаются, и это нормально.

Доклад

• Что нашёл docs.py: код выхода и число пунктов дрейфа.
• Что перенесено: файл → дом, числом и поимённо для спорного.
• Удалённые дубли — с указанием, против какой спеки сверялся каждый.
• Не разложилось — поимённо, с причиной.
• Переходное состояние числами: честных строк, маркеров долга, задач без критериев.
• Граница покрытия: что проверила машина, что судил ты, чего не смотрел никто.