канон 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` отвергался как указатель путей: отвергнут был указатель, а не имя
This commit is contained in:
@@ -3647,3 +3647,69 @@ change нет — берём источником актуальные спек
|
||||
которую никто не набрал, может не существовать вовсе — и именно так и было.
|
||||
199. **Два дома у факта расходятся не когда-нибудь, а сразу.** Из четырёх пар
|
||||
описаний плагина совпала одна — та, которую с момента заведения не правили.
|
||||
|
||||
## 60. Служебный файл зовётся по плагину-владельцу; у задач появилась своя версия формата (2026-08-11)
|
||||
|
||||
Файл версии канона звался `docs/.pm.json` — по плагину `av-dev-pm`, который
|
||||
распался на четыре ещё в решении 56 и которого больше нет. Имя пережило
|
||||
владельца на два месяца и указывало в пустоту: читающий его искал плагин, о
|
||||
котором в репозитории не осталось ни строки. Переименован в `docs/.docs.json`
|
||||
записью 13 журнала канона.
|
||||
|
||||
**Правило, которое из этого вынуто и теперь держит все три файла:** имя
|
||||
служебного файла — имя плагина, который его завёл. `.docs.json` — канон,
|
||||
`.tasks.json` — задачи, `openspec/config.yaml` — конвейер. По этому же следу
|
||||
скиллы узнают, что сосед в проекте работал, и правило перестало быть просто
|
||||
перечнем — оно выводимо.
|
||||
|
||||
**Прежнее имя `docs.py` не читает.** Соблазн «прочитать оба и не мешать людям»
|
||||
здесь стоит дороже, чем везде: по этому числу `upgrade` решает, какие записи
|
||||
журнала применять, и два дома для него разъехались бы молча в том самом месте,
|
||||
где расхождение и вредно. Вместо совместимости — узнавание: `check` видит файл
|
||||
под старым именем и печатает готовую команду `git mv`.
|
||||
|
||||
**У каталога задач появилась своя версия формата** — ключ `tasks` в
|
||||
`<каталог задач>/.tasks.json` и свой журнал версий в скилле `av-dev-tasks:tasks`.
|
||||
До сих пор её не было вовсе, хотя `docs.py` в комментарии уверенно ссылался на
|
||||
«свою версию формата» соседа: описание опережало механику ровно так, как описано
|
||||
в решении 195. Формат задач при этом менялся — записями 8, 11 и 12 чужого
|
||||
журнала.
|
||||
|
||||
**Число именно своё, а не копия канонического.** Плагин ставится в одиночку:
|
||||
проект, взявший учёт работ без канона документов, каталога `docs/` не имеет
|
||||
вовсе, а значит не имеет и версии канона — сверять было бы не с чем. Копия
|
||||
чужого числа в `tasks.py` была бы вторым домом одной версии и разъехалась бы при
|
||||
первом же обновлении одного плагина без другого.
|
||||
|
||||
**Переезды, случившиеся до появления числа, задним числом в новый журнал не
|
||||
переписаны.** Версия 1 — это формат на день её появления; что проекту нужно было
|
||||
пройти до неё, названо шагом «догнать формат по журналу канона» с поимёнными
|
||||
признаками отставания (каталог в `docs/tasks/`, живой `SPRINT.md`). Второй
|
||||
перечень тех же шагов разошёлся бы с первым — это ровно та ошибка, из-за которой
|
||||
план однажды повторял записи версий 3, 4 и 5 построчно.
|
||||
|
||||
**Конфиг задач стал обязательным.** Раньше он заводился только ради имён,
|
||||
отличных от умолчания, и проект с умолчаниями жил без файла вовсе. Версия — не
|
||||
настройка, от которой можно отказаться, поэтому `init` и `adopt apply` пишут его
|
||||
всегда, а `check` требует числа.
|
||||
|
||||
Отдельно стоит сказать, чтобы не спутали при чтении журнала: `.docs.json`
|
||||
однажды уже был отвергнут — решением F, но **как указатель путей**. Отвергнут
|
||||
был указатель, а не имя; сегодняшний файл путями проекта не распоряжается, он
|
||||
объявляет версию и называет то немногое, чего из раскладки не вывести.
|
||||
|
||||
### Что из этого следует
|
||||
|
||||
200. **Имя служебного файла — часть границы плагинов, а не деталь.** Оно
|
||||
называет владельца, и по нему же владельца узнают. Пережившее владельца имя
|
||||
врёт дважды: указывает на несуществующее и прячет того, кто файл ведёт на
|
||||
самом деле.
|
||||
201. **Версия нужна каждому формату, который живёт в чужом репозитории.** Без
|
||||
числа «приведён ли проект» не имеет определённого ответа, и отставший
|
||||
каталог выглядит здоровым до первой команды, которая об него споткнётся.
|
||||
202. **Своя версия — у своего плагина, всегда.** Общее число на два плагина
|
||||
переживает ровно до первого проекта, где поставлен один из них.
|
||||
203. **Версию двигают руками, и это не слабость проверки.** Число отвечает
|
||||
на вопрос «по какой записи повышать», а не «сделаны ли шаги по существу».
|
||||
Машина, приписывающая недостающее число сама, объявляет проект приведённым
|
||||
к формату, которого никто не проходил.
|
||||
|
||||
Reference in New Issue
Block a user