документация: README, TODO и журнал решений знают про один плагин

README переписан под два плагина: состав скиллов с префиксами, диаграмма одним
контуром, команды установки и обновления, раздел версий про .av-dev.toml. Правка
про копии сказала главное — копия была платой за неразрешимый путь, а не за
важность правила, и внутри одного дерева остаётся только там, где текст обязан
лежать в промпте.

DECISIONS: тема 64 с замером цены раскола и четырьмя следствиями. Довод «а вдруг
понадобится» снят наблюдением: режим, ради которого раскол держали, покрыт
сценарием обслуживания.
This commit is contained in:
av
2026-08-13 10:33:44 +03:00
parent 95c9499f06
commit a00e132f29
3 changed files with 227 additions and 147 deletions
+61
View File
@@ -3919,3 +3919,64 @@ change по нему не будет никогда, — и такое реше
когда весь материал для неё у исполнителя. Стоп обязан принести названный
тип, объяснение и закрытый список решений — иначе выбор делается вслепую или
не делается вовсе, и работа доезжает до коммита не тем процессом.
## 64. Три плагина слились в один: раскол платили, а не пользовались (2026-08-13)
Плагинов было три — `av-dev-docs`, `av-dev-tasks`, `av-dev-code`, — и разрез
между ними шёл по признаку «ставится порознь» (решение 51). Признак был выбран
верно, но **посылка под ним не проверялась**: за всё время подмножество не
понадобилось ни разу, а платился раскол постоянно.
Цена измерена, а не оценена: шестьдесят с лишним кросс-вызовов при цикле
зависимостей `docs → code → docs`, язык проектных текстов четырьмя помеченными
копиями по 213 строк, словарь сопровождения двумя, правило границы семью,
дюжина веток «плагина нет» — и `copies.py`, заведённый ровно затем, чтобы это
не разъезжалось молча.
**Довод «а вдруг понадобится» снят наблюдением владельца, а не спором.** Ждали
случая «документы и задачи без OpenSpec» — например, ansible-репозиторий. Он
уже покрыт: сценарий обслуживания в `resolve` OpenSpec не требует по
построению, а `docs.py` считает отсутствие `openspec/` неприменимостью, а не
отказом. То есть режим, ради которого держали раскол, работает и в слитом
плагине.
**Слияние оказалось дешевле, чем выглядело, потому что граница была сделана
правильно.** Присутствие соседа узнавалось **следом в проекте**
(`.docs.json`, `.tasks.json`, `openspec/config.yaml`), а не перечнем
установленных плагинов. Значит мягкость поведения держалась на состоянии
проекта и пережила слияние без единой правки логики: сменилась упаковка, а не
механика. Дом правила переехал из `plugin-boundary.md` в `absence.md` и стал
говорить о том, чем он и был на деле, — о частях раскладки, которых может не
быть.
**Версия стала одна и начинается с 1.** Две версии — канон 14 и формат задач 1 —
двигались порознь, потому что порознь ставились плагины; с одним плагином два
числа означали бы только вопрос, по какому журналу повышать. Прежние журналы
закрыты и не переписаны: адрес, верный на день записи, остаётся свидетельством.
Служебный файл один, `.av-dev.toml` в корне репозитория, и **формат выбран ради
комментариев** — файл живёт в чужом репозитории, и назначение числа должно
читаться из него самого, а не из документации плагина. Отсюда правило записи:
скрипт правит строку, а не переписывает файл.
**Опцион не потерян.** Понадобится инфраструктурный плагин — расколоть обратно
будет переименованием пространства имён, а не переделкой: граница по-прежнему
держится на следе в проекте. Платить за этот опцион копиями сегодня незачем.
### Что из этого следует
218. **Разрез, оправданный сценарием, обязан этот сценарий однажды увидеть.**
«Ставится порознь» — проверяемое утверждение, и проверяется оно не
рассуждением, а тем, поставил ли кто-нибудь половину. Пока не поставил,
разрез оплачивается копиями за случай, которого нет.
219. **Механика, привязанная к состоянию проекта, переживает перестановку
плагинов; привязанная к их составу — нет.** Это и есть практическая разница
между «узнаём следом» и «узнаём перечнем», и обнаруживается она только на
слиянии или расколе.
220. **Копия дословного текста — плата за неразрешимый путь, а не за важность
правила.** Путь разрешился — копия становится вторым домом без причины.
Остаётся она там, где текст обязан лежать внутри промпта: устав агента и
скелет, уезжающий в проект.
221. **Формат служебного файла выбирается по тому, кто его читает.** Читает
человек в чужом репозитории через полгода — значит комментарии, значит
TOML, значит построчная правка вместо перезаписи.