Files

T

канон 13: файл версии зовётся по владельцу, у задач появилась своя версия формата

Имя `.pm.json` пережило плагин `av-dev-pm` на два месяца и указывало в пустоту.
Правило, которое из этого вынуто: имя служебного файла — имя плагина, который
его завёл, и по нему же владельца узнают.

- `docs/.pm.json` → `docs/.docs.json`, запись 13 журнала. Прежнее имя docs.py
  не читает намеренно: по этому числу upgrade решает, какие записи применять,
  и два дома разъехались бы молча ровно там, где это дороже всего. Вместо
  совместимости — узнавание: check видит старый файл и печатает готовую git mv
- у каталога задач появилась своя версия формата — ключ `tasks` в
  `.tasks.json`, свой журнал версий и своё повышение. До сих пор её не было
  вовсе, хотя docs.py в комментарии уверенно на неё ссылался: описание
  опережало механику ровно так, как сказано в решении 195
- число своё, а не копия канонического: плагин ставится в одиночку, и у
  проекта без docs/ версии канона нет — сверять было бы не с чем
- конфиг задач стал обязательным (init и adopt apply пишут его всегда), check
  сверяет число, `check --fix` его не приписывает: приписанное объявляло бы
  каталог приведённым к формату, шагов которого никто не делал
- переезды 11 и 12 в новый журнал задним числом не переписаны — версия 1
  велит догнать формат по журналу канона, называя признаки отставания
  поимённо (каталог в docs/tasks/, живой SPRINT.md)
- запись 60 в DECISIONS со следствиями 200–203; отдельно разведено с решением
  F, где `.docs.json` отвергался как указатель путей: отвергнут был указатель,
  а не имя

2026-08-11 10:35:39 +03:00

5.2 KiB

Raw Blame History

Журнал версий формата задач

Одна запись на версию. Проект знает свою версию из ключа tasks в <каталог задач>/.tasks.json; повышение (upgrade в SKILL.md, раздел «Версия формата») идёт по записям снизу вверх от версии проекта до текущей и делает то, что в них названо.

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

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

Это журнал формата задач, а не канона документов. Числа у них разные и двигаются порознь: плагин av-dev-tasks ставится в одиночку, и у проекта без av-dev-docs версии канона нет вовсе. Журнал канона — references/changelog.md скилла av-dev-docs:canon.

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

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

Что появилось. Ключ tasks в <каталог задач>/.tasks.json — целое число, версия формата. Сам файл стал обязательным: до сих пор он заводился только ради имён, отличных от умолчания, и проект с умолчаниями жил без него. Версия — не настройка, от которой можно отказаться, поэтому init и adopt apply теперь пишут файл всегда, а check требует числа и сверяет его со своим.

Что версия значит, а что нет. Она отвечает на один вопрос — «по какой записи журнала повышать каталог». Что записи применены по существу, из числа не следует: двигают его руками, и соврать им так же легко, как любой другой строкой. check --fix недостающее число не приписывает намеренно — это было бы объявлением каталога приведённым к формату, шагов которого никто не делал.

Чего в этой записи нет. Переезды, случившиеся до появления числа, — каталог из docs/ в корень (канон 11) и отмена спринтов (канон 12) — задним числом сюда не переписаны. Они уже названы журналом канона, и второй перечень тех же шагов разошёлся бы с первым. Версия 1 — это формат на день её появления, что бы проекту ни пришлось пройти до неё.

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

Догнать формат по журналу канона, если каталог отстал. Признаки известны поимённо: каталог лежит в docs/tasks/ (канон 11 велит git mv docs/tasks tasks и починку относительных ссылок внутри записей), в нём есть SPRINT.md или теги sprint:<слаг> (канон 12 велит снести файл, вернуть строки в беклог через check --fix и расставить порядок грумингом). Ничего из этого нет — каталог уже в сегодняшнем формате, и шаг пропускается.
Завести <каталог задач>/.tasks.json, если его нет. Имена частей в него не переписываются: там только то, что отличается от умолчания.
Записать версию: "tasks": 1 первым ключом.
tasks.py check --dir <каталог задач> — до отсутствия расхождений.

Что при этом не трогается. Записи в items/, индексы и REJECTED.md не меняются ни строкой: версия 1 объявляет то, что уже есть, а не переделывает его.

5.2 KiB Raw Blame History

Журнал версий формата задач

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

5.2 KiB

Raw Blame History