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

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

Одна запись на версию. Проект знает свою версию из docs/.pm.json; canon upgrade идёт по записям снизу вверх от версии проекта до текущей и делает то, что в них названо.

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

Версия — целое число. Обратной совместимости у канона нет: есть «приведён» и «не приведён».

---

Версия 4 — 2026-08-04

Одна секция роадмапа переименована, и вместе с именем расширен её смысл; достигнутое переехало вниз. Плюс общий словарь для трёх мест канона, которые говорят про одну тему разными словами. Раскладка не меняется, файлов не прибавляется.

Что переехало: секция роадмапа Разработка → Сопровождение (англ. Tooling → Operations). Прежнее имя называло слишком много: роадмап весь про разработку, и секция с таким именем не отличалась от остальных ничем.

Что добавилось:

1. Смысл секции расширен. Было «инструмент и процесс», стало «чем держат проект: инструмент, процесс, эксплуатация». Метрики, логи, инфраструктура, выкладка и дежурство — сюда же. Расширение не косметическое: английское Operations при узком смысле обещало бы эксплуатацию, а внутри лежал бы линтер.
2. Общий словарь трёх мест — canon.md, раздел «Сопровождение и эксплуатация». Сопровождение — всё, чем держат проект; эксплуатация — его часть, работа системы на проде. ROADMAP.md, секция Сопровождение — план работ; architecture.md, раздел «Эксплуатация» — как устроено сейчас; эксплуатационный проход ревью — оптика проверки. Слить их в одно слово нельзя: они отвечают на разные вопросы. Слово «поддержка» не употребляется вовсе — в нём слышится помощь пользователю.
3. Граница с возможностями проходит по тому, кто наблюдает. «Приложение сообщает о своём состоянии» — возможность приложения, её место среди прочих целей. «Дежурный видит состояние на одном экране» — сопровождение. Одни и те же метрики попадают в разные секции роадмапа, и это верно.
4. Порядок секций стал каноническим, и Готово переехало вниз: Запланировано | Направления | Сопровождение | Готово. Достигнутое копится — через год этой секции больше, чем всех остальных вместе, — и стоя первой она отодвигает за экран то, ради чего роадмап открывают чаще всего. Порядок проверяет tasks.py check, переставляет check --fix.
5. Заголовок секции отбивается пустой строкой с обеих сторон. Прежде проверялась только строка после заголовка; перестановка секций двигает целые блоки, и два заголовка оказываются вплотную. Правит check --fix.

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

1. Переименовать заголовок секции в docs/tasks/ROADMAP.md: ## Разработка → ## Сопровождение (или ## Tooling → ## Operations, если индекс английский). check --fix этого не сделает: регистр канонической секции он правит сам, а чужую секцию только называет ошибкой — смысл за человеком.
2. Поправить поле - **Секция:** в файлах целей, которые в ней лежат. Порядок именно такой: сперва заголовок, потом python3 tasks.py check --dir docs/tasks покажет расхождение поимённо.
3. Перечитать состав секции: цели про выкладку, метрики, логи и инфраструктуру, если они лежали в Направлениях за неимением места, переезжают сюда.
4. Прогнать python3 tasks.py check --dir docs/tasks --fix: он переставит секции роадмапа в канонический порядок (Готово уедет вниз вместе со всем содержимым) и поправит отбивку заголовков.
5. docs/.pm.json: "canon": 4.

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

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

Что добавилось:

1. Род работы — тег kind:<род> в мете задачи, словарь закрыт: feature | fix | chore | research. Обязателен у задачи, у цели запрещён. sprint take без него отказывает, check о пропаже напоминает замечанием. Определение — canon.md, раздел tasks/; смысл и причина, почему тегом, — в SKILL.md скилла tasks, раздел «Род работы».
2. Раздел «Затрагивает» в теле задачи — перечень границ, которых изменение касается (эндпоинт, таблица и миграция, формат на диске, публичный тип). Как и критерии приёмки, требуется к взятию в спринт, а не к заведению.
3. Секции роадмапа — четыре вместо двух и канонические, в отличие от секций беклога: Готово (достигнутые цели строкой с датой, без ссылки на файл), Запланировано (очередь значима), Направления (очереди нет), Разработка (инструмент и процесс, не возможности приложения). Английский вариант — Done | Planned | Directions | Tooling, один язык на весь индекс. Переименованию проектом не подлежат: у каждой свой смысл, и в первую пишет сам close; tasks.py check проверяет состав.
4. Форма заголовка записи — по типу: задача отвечает на «что нужно сделать» и пишется глаголом в неопределённой форме («Не отбрасывать молча лишние символы»), цель — на «что приложение будет уметь», идея просто называет, о чём она. check считает заголовки не в форме действия и печатает число в блоке здоровья. Годность формулировки — не машине: её смотрит новый агент task-form (форма записи, только чтение), а язык текста — doc-wording.
5. Заголовки секций — с прописной, после заголовка пустая строка, во всех индексах. Написание канонических секций и отбивку правит check --fix; он же сводит написание секции в мете файла с заголовком индекса.
6. Язык проектных текстов — language.md, общий дом для документов канона, задач, решений ADR и записок разведки: информационный стиль (глагол вместо отглагольного существительного, активный залог, факт вместо оценки, стоп-слова, параллельность), таблицы англицизмов и жаргона и то, что из стиля отброшено намеренно. Проектных файлов не добавляет и раскладку не меняет — это правила письма, а не новый слот.
7. Умолчание профиля ревью сменилось — это не раскладка, но проектный текст под него уже написан. standard стал рабочим умолчанием: миграция схемы, публичный контракт и инвариант ступень больше не поднимают, wide означает новое понятие или структурную единицу. Подраздел «Триггеры профиля» в docs/review.md остаётся на месте, но его содержимое надо перечитать.

Что переехало: docs/tasks/PLAN.md → docs/tasks/ROADMAP.md; достигнутая цель — из небытия в секцию Готово: close <цель> --implemented удаляет файл, но оставляет строку с датой. Прежде роадмап отвечал только «что осталось», и половину его вопроса вели прозой руками. Вместе с файлом переименован ключ конфига tasks.plan → tasks.roadmap и токены команд: --index plan → --index roadmap, init --plan-sections → --roadmap-sections, init --plan → --roadmap. Старый ключ в docs/.pm.json не игнорируется молча — tasks.py останавливается и называет переименование.

Что удалено: тип [epic]. Он был зонтиком между целью и задачами; зонтиком стала цель, а слишком крупный шаг дробится на шаги помельче под ней. Ноль употреблений на 97 записей двух живых проектов.

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

1. git mv docs/tasks/PLAN.md docs/tasks/ROADMAP.md.
2. Починить ссылки на прежнее имя: grep -rn 'PLAN\.md' docs/ CLAUDE.md — заголовок самого файла («# План» → «# Роадмап»), строка в docs/tasks/BACKLOG.md, упоминания в docs/passport.md и в телах задач.
3. docs/.pm.json: ключ tasks.plan, если он там был, — в tasks.roadmap.
4. Проставить род работы живым задачам: python3 tasks.py check --dir docs/tasks перечислит те, у кого его нет. Задним числом весь беклог не переоформляется — род нужен к взятию, так что порядок такой: сперва то, что берётся в ближайший спринт, остальное по ходу переоценки.
5. Дописать раздел «Затрагивает» — тем же порядком и по той же причине: сперва набор спринта, остальное по мере того, как задача попадает в работу.
6. Перечитать «Триггеры профиля» в docs/review.md: строки вида «миграция → deep» теперь дублируют умолчание с обратным знаком. Оставить там только то, что для этого проекта считается новым понятием и правилом идентичности, — и убрать остальное, иначе проект возвращает себе прежнюю частоту полного набора уточнением.
7. Переименовать секции роадмапа: порядок → Запланировано, темы → Направления; завести Готово первой и Разработка последней (порядок секций поменялся в версии 4 — если едешь сразу на неё, заводи Готово последней и не переставляй дважды). Прозаические разделы вроде «Что уже пройдено», которые велись руками, разложить: звенья — строками в Готово (дата, слаг, что стало возможно), обоснование очереди оставить прозой в Запланировано. Любой ## в индексе проверка считает секцией, и теперь check называет чужую секцию ошибкой.
8. Переформулировать цели ответом на «что приложение будет уметь»: не «Работа со слиянием», а «Исход слияния не зависит от порядка доставки». Свойство поведения — законная цель. Цель, которая не про приложение (процесс, инструмент), переезжает в Разработка.
9. [epic], если он в проекте заводился: это либо цель, либо набор задач под общей целью. check назовёт его неизвестным типом.
10. Прогнать python3 tasks.py check --dir docs/tasks --fix: он поднимет написание канонических секций, поставит отбивку после заголовков и сведёт секцию в мете файлов с заголовками индексов. Секции беклога проект переименовывает сам — их имена он выбирал, и трогать их скрипт не вправе.
11. Переписать заголовки задач в форму действия — по мере того, как задача попадает в работу, а не «заодно»: check печатает их число, а task-form предложит формулировки на замену пачкой.
12. Прочитать language.md — и ничего не переписывать задним числом. Правила языка применяются к тому, что пишется и правится сейчас; сплошная вычитка старых документов стоит дороже, чем даёт.
13. docs/.pm.json: "canon": 3.

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

Шапка записи ADR — мета-блоком общей формы, и у статуса появился объявленный дом. Раскладка не менялась: правка касается одного шаблона.

Что добавилось: поле - **Статус:** в шапке docs/adr/template.md — заменено на ADR-… либо устарело, у активной записи поля нет. Правило «старая запись получает статус» было и раньше (canon.md, adr/), но места под него шаблон не отводил: каждая запись изобретала своё, а колонка «Статус» таблицы adr/README.md брала его оттуда, где он у каждого свой.

Что переехало: поля Дата и Источник в шаблоне стали жирными (- **Дата:**, - **Источник:**) — та же форма, что у меты задачи и у записи журнала дефектов: поле на строку, имя жирным.

Что удалено: ничего.

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

1. Привести docs/adr/template.md к скелету версии 2 (skeletons.md, раздел docs/adr/template.md).
2. В существующих записях docs/adr/ADR-*.md: жирным поля шапки; если статус записан прозой или заголовком — перенести его полем - **Статус:** в шапку и сверить с колонкой «Статус» таблицы в docs/adr/README.md.
3. docs/.pm.json: "canon": 2.

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

Первая версия. Проект любой прежней раскладки приводится к ней скиллом canon в режиме adopt, а не upgrade.

Что вводится: раскладка целиком — см. canon.md.

Что сделать проекту, который приходит из свободной раскладки:

1. docs/.pm.json с {"canon": 1} и путём миграций, если БД есть.
2. Скелет канона целиком; незаполненное — одной честной строкой.
3. docs/specs/ разобрать: поведение — в openspec/specs/, обзор — в docs/architecture.md, знание о чужих системах — в docs/research/. Дубли capability удалить, сверив поимённо.
4. docs/plan.md → docs/tasks/PLAN.md, шаги плана — целями в «порядок».
5. BRIEF.md → docs/passport.md.
6. docs/backlog/ → docs/tasks/.
7. docs/review-journal.md или docs/review/journal.md → docs/review.md, плюс раздел настройки конвейера.
8. docs/drafts/ растворить: идея → задача [idea], намеренный отказ → ADR, порядок работ → PLAN.md.
9. docs/review-brief.md, если заводился, удалить: его разделы разошлись по документам канона.
10. conventions.md → conventions/, local-research.md → research/.
11. Завести docs/security.md с периметром первой строкой и docs/adr/.
12. В CLAUDE.md: severity рядом с каждым инвариантом; семантика гейта (чем краснеет безусловно, где логи, чего в нём нет и кто тогда гоняет дорогое); имя основной ветки; запреты с путями; где testdata и куда писать временное; что считается необратимым; общий станок; ориентир по размеру спринта. Убрать раздел «Процесс», если он пересказывает пайплайн.
13. В openspec/config.yaml оставить только нужды генерации и ссылки.
14. Добавить шаг docs.py check в гейт проекта.

Копии правил в шаблонах, которые версия 1 уносит в проект — их правка в каноне обязана появляться здесь отдельной версией:

Что копируется	Дом определения
форма записи журнала дефектов в docs/review.md	av-dev-pipeline/skills/review-pipeline/references/review-journal.md
правило заведения ADR в docs/adr/README.md	canon.md, раздел adr/