вычитка ревью: пережитки трёх плагинов и язык слияния
Восемнадцать веток «плагина нет» описывали недостижимое: скиллы и агенты теперь в одном плагине и разрешаются всегда. Где предмет всё же может отсутствовать — ветка переписана на след в проекте (нет docs/, нет каталога задач, нет openspec/); где отсутствовать нечему — снята. Туда же анонсы, обещавшие ветку, которой в разделе больше нет. Правило копий и его применение разъезжались в одном коммите: правило называло два законных случая, а absence.md разослан семью копиями по SKILL.md. Назван третий случай, и разрез проверяемый — файл, который модель получает целиком, против файла, за которым она идёт отдельным чтением. Заодно сняты объявления копий там, где копию сменила ссылка, и довод у карты домов в doc-consistency: он ссылался на отсутствие плагина, хотя устав едет вместе с плагином. Описания скиллов во фронтматтерах звали снятые короткие имена — по ним скилл не находится. task-track перестал обещать повышение: версию двигает doc-canon. Язык: сняты кросс-вызов, опцион и деградация, конверсия и «читатель» в config.py, charter'ы против уставов, замер против подсчёта, страдательный залог в журнале. Строка «настройки av-dev» в таблице отсутствия — слово «раскладка» называло и целое, и его часть. Мелкое: тема 52 в README была 64, транслит в task-wording машина не проверяет, мёртвая ветка REQUIRED в addresses.py, ссылки на язык в закрытом журнале.
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: doc-canon
|
||||
description: Привести проект к канону документов av-dev и держать его в соответствии — три операции одной машиной сравнения. check — что разошлось с текущей версией канона; adopt — перевод проекта из любой прежней раскладки (docs/specs, drafts, backlog, BRIEF.md, review-brief) в канон с переносом файлов; upgrade — повышение проекта с версии канона N до текущей по журналу версий. Использовать, когда просят проверить документацию проекта, перевести проект на канон, обновить его под новую версию канона или когда пришли в старый проект и надо понять, что в нём не так. Заведение нового проекта с нуля — скилл init.
|
||||
description: Привести проект к канону документов av-dev и держать его в соответствии — три операции одной машиной сравнения. check — что разошлось с текущей версией канона; adopt — перевод проекта из любой прежней раскладки (docs/specs, drafts, backlog, BRIEF.md, review-brief) в канон с переносом файлов; upgrade — повышение проекта с версии канона N до текущей по журналу версий. Использовать, когда просят проверить документацию проекта, перевести проект на канон, обновить его под новую версию канона или когда пришли в старый проект и надо понять, что в нём не так. Заведение нового проекта с нуля — скилл av-dev:doc-init.
|
||||
---
|
||||
|
||||
# Приведение проекта к канону
|
||||
@@ -48,7 +48,8 @@ description: Привести проект к канону документов
|
||||
ds="$CLAUDE_PLUGIN_ROOT/skills/doc-canon/scripts/docs.py"
|
||||
|
||||
python3 $ds check --dir <корень> [--base <rev>] # раскладка, ссылки, версия, сверки
|
||||
python3 $ds version --dir <корень> # версия канона скрипта и проекта
|
||||
python3 $ds version --dir <корень> # версия раскладки: скрипта и проекта
|
||||
python3 $ds bump --dir <корень> # поднять версию проекта до версии скрипта
|
||||
```
|
||||
|
||||
**Формы `openspec/config.yaml` здесь больше нет.** Каталог принадлежит конвейеру,
|
||||
@@ -103,7 +104,7 @@ capability: незаполненный канон это переходное с
|
||||
|
||||
| Чего нет | Как видно | Чего теперь не делает никто |
|
||||
| --- | --- | --- |
|
||||
| раскладка av-dev | нет `.av-dev.toml` в корне | проект под процесс не заводился; версии нет, настроек нет |
|
||||
| настройки av-dev | нет `.av-dev.toml` в корне | проект под процесс не заводился; версии нет, настроек нет |
|
||||
| документы канона | нет `docs/` | проектную конкретику брать неоткуда — темы, инварианты, прецеденты |
|
||||
| учёт работ | нет каталога задач | запись остаётся владельцу: назови её текстом в докладе |
|
||||
| источник требований | нет `openspec/config.yaml` | цикл SDD не запускается: спеки не с чем сверять |
|
||||
@@ -141,7 +142,7 @@ capability: незаполненный канон это переходное с
|
||||
форма», `doc-healthcheck` — на «не разошлись ли утверждения».
|
||||
3. Доклад: вывод скрипта строкой исхода и **граница покрытия** — что смотрели и
|
||||
чего не смотрели. Если суждение здесь нужно, скажи это строкой и предложи
|
||||
`healthcheck`, а не зови агентов сам.
|
||||
`doc-healthcheck`, а не зови агентов сам.
|
||||
|
||||
Дрейф раскладки чинится переносом; смысловые находки — это либо правка
|
||||
документа, либо задача, если работы больше чем на абзац.
|
||||
@@ -192,8 +193,9 @@ capability), `openspec/config.yaml`.
|
||||
Skill `av-dev:code-openspec`**. Каталог принадлежит конвейеру, и команда
|
||||
заведения с формой файла живут там. Пересказ инвариантов, конвенций и правил
|
||||
ревью из `context` вычисти ссылкой на дом — на переводимом проекте он там
|
||||
почти наверняка есть. Вызов не разрешился — `docs.py` о каталоге тогда тоже
|
||||
молчит, и форму `config.yaml` не проверяет никто; скажи это строкой;
|
||||
почти наверняка есть. Проект решил жить без OpenSpec — `docs.py` о каталоге
|
||||
тогда тоже молчит, и форму `config.yaml` не проверяет никто; скажи это
|
||||
строкой;
|
||||
4. переносы содержимого;
|
||||
5. каталог задач — **вызови скилл `av-dev:task-track`**, сценарий адаптации: он
|
||||
владеет форматом задач. Он же переименует транслитные слаги в английские и
|
||||
@@ -274,8 +276,9 @@ capability), `openspec/config.yaml`.
|
||||
3. Иначе иди по [changelog.md](references/changelog.md) снизу вверх от версии
|
||||
проекта до текущей и делай названное в каждой записи. Записи независимы и
|
||||
применяются по порядку.
|
||||
4. Подними `version` в `.av-dev.toml` до текущей — правь **строку**, а не
|
||||
переписывай файл: комментарии в нём принадлежат проекту.
|
||||
4. Подними версию — `docs.py bump`. Он правит **строку**, а не переписывает
|
||||
файл: комментарии в нём принадлежат проекту. Последним шагом, потому что
|
||||
число объявляет пройденными записи журнала.
|
||||
5. `docs.py check`.
|
||||
6. **Позови судей** — Skill `av-dev:doc-healthcheck`.
|
||||
7. **Позови вычитку** — агент `doc-wording`, но **только по тем документам,
|
||||
@@ -295,7 +298,7 @@ capability), `openspec/config.yaml`.
|
||||
|
||||
**Шаг 6 обязателен, и вот почему.** `check` сверяет **число** в `.av-dev.toml`
|
||||
с версией скрипта — и только его. Применена ли запись журнала **по существу**,
|
||||
он не знает: проект несёт `version = 6` и может не иметь того, чего требовала любая
|
||||
он не знает: проект несёт `version` текущей версии и может не иметь того, чего требовала любая
|
||||
из пройденных версий. Записи применяются руками (переименовать секцию, проставить
|
||||
типы, дописать раздел каждому `fix`), а ручной проход по нескольким записям
|
||||
подряд — ровно то место, где половина шага делается и забывается. Судьи и есть
|
||||
|
||||
@@ -347,10 +347,10 @@ kebab-case.** Причина не эстетическая: имя файла с
|
||||
**Каталог задач канону не принадлежит.** Его ведёт скилл `task-track` — своим
|
||||
скриптом и своими проверками; где каталог лежит и как названы его части, говорит
|
||||
секция `[tasks]` в `.av-dev.toml`. Версия там одна на всю раскладку: канон и
|
||||
каталог задач двигаются вместе, потому что двигает их один плагин.
|
||||
каталог задач двигаются вместе, потому что ведёт их один плагин.
|
||||
Канон **резервирует место** в `docs/` и внутрь не смотрит:
|
||||
`docs.py` каталог не открывает, его отсутствия не считает дрейфом и согласованность
|
||||
задач не проверяет. Проект, поставивший только канон документов, задач не ведёт
|
||||
задач не проверяет. Проект, не заведший каталог задач, их не ведёт
|
||||
вовсе, и отказом это быть не может.
|
||||
|
||||
Раскладку, форму записи и команды держит скилл `av-dev:task-track`. Ниже — то,
|
||||
@@ -379,9 +379,8 @@ kebab-case.** Причина не эстетическая: имя файла с
|
||||
|
||||
**Схемы записи здесь нет намеренно.** Какие разделы тип требует, нужна ли ему
|
||||
цель и берётся ли он в работу — скилл `av-dev:task-track`, раздел «Тип
|
||||
записи», подробно — по файлу на тип в его `references/task-<тип>.md`. Ссылки в
|
||||
дерево того плагина здесь нет намеренно: он ставится отдельно, и путь наружу
|
||||
разрешился бы не всегда. Канон фиксирует **словарь**, потому что
|
||||
записи», подробно — по файлу на тип в его `references/task-<тип>.md`. Канон
|
||||
фиксирует **словарь**, потому что
|
||||
от него зависит, читается ли проект как продукт; схема — механика ведения задач,
|
||||
и второй её экземпляр разошёлся бы с первым (он и разошёлся: канон успел
|
||||
объявить цель у `fix` запрещённой, хотя она там необязательна).
|
||||
@@ -525,7 +524,7 @@ kebab-case.** Причина не эстетическая: имя файла с
|
||||
разрез, что между `task-form` и `task-wording`.
|
||||
|
||||
**Зовутся оба одинаково и одним скиллом — `av-dev:doc-healthcheck`, на весь
|
||||
канон разом; шагом `adopt` и шагом `upgrade` его зовёт `canon`.** Не на синке
|
||||
канон разом; шагом `adopt` и шагом `upgrade` его зовёт `doc-canon`.** Не на синке
|
||||
документации: `doc-consistency` на
|
||||
`opus` по каждой сделанной задаче не окупается, а расхождение между двумя документами по
|
||||
определению требует двух, и на большинстве задач синк правит один. Пачка,
|
||||
|
||||
@@ -646,7 +646,7 @@ ADR объясняет прошлое решение, а не предъявля
|
||||
5. **Заголовки секций — с прописной, после заголовка пустая строка**, во всех
|
||||
индексах. Написание канонических секций и отбивку правит `check --fix`; он
|
||||
же сводит написание секции в мете файла с заголовком индекса.
|
||||
6. **Язык проектных текстов** — [language.md](language.md), общий дом для
|
||||
6. **Язык проектных текстов** — [language.md](../../../shared/language.md), общий дом для
|
||||
документов канона, задач, решений ADR и записок разведки: информационный
|
||||
стиль (глагол вместо отглагольного существительного, активный залог, факт
|
||||
вместо оценки, стоп-слова, параллельность), таблицы англицизмов и жаргона и
|
||||
@@ -711,7 +711,7 @@ ADR объясняет прошлое решение, а не предъявля
|
||||
11. Переписать заголовки задач в форму действия — по мере того, как задача
|
||||
попадает в работу, а не «заодно»: `check` печатает их число, а `task-form`
|
||||
предложит формулировки на замену пачкой.
|
||||
12. Прочитать [language.md](language.md) — и **ничего не переписывать задним
|
||||
12. Прочитать [language.md](../../../shared/language.md) — и **ничего не переписывать задним
|
||||
числом**. Правила языка применяются к тому, что пишется и правится сейчас;
|
||||
сплошная вычитка старых документов стоит дороже, чем даёт.
|
||||
13. `docs/.pm.json`: `"canon": 3`.
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# Журнал версий формата задач до слияния плагинов
|
||||
|
||||
**Журнал закрыт.** У каталога задач была своя версия, пока плагином его ведал
|
||||
`av-dev-tasks` и ставился он отдельно. Версия теперь одна на всю раскладку —
|
||||
**Журнал закрыт.** У каталога задач была своя версия, пока его вёл отдельный
|
||||
плагин `av-dev-tasks`. Версия теперь одна на всю раскладку —
|
||||
действующий журнал [changelog.md](changelog.md), и переезд числа описан его
|
||||
записью 1.
|
||||
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
# Журнал версий раскладки
|
||||
|
||||
Одна запись на версию. Проект знает свою версию из ключа `version` в
|
||||
`.av-dev.toml`; `canon upgrade` идёт по записям снизу вверх от версии проекта до
|
||||
текущей и делает то, что в них названо.
|
||||
`.av-dev.toml`; операция `upgrade` скилла `av-dev:doc-canon` идёт по записям
|
||||
снизу вверх от версии проекта до текущей и делает то, что в них названо.
|
||||
|
||||
Правило записи: **что добавилось, что переехало, что удалено, что сделать
|
||||
проекту**. Без последнего пункта запись бесполезна — по ней и работает
|
||||
@@ -26,9 +26,9 @@
|
||||
|
||||
Три плагина — `av-dev-docs`, `av-dev-tasks` и `av-dev-code` — слились в один,
|
||||
`av-dev`. Раскол делался под раздельную установку: проект мог взять учёт работ
|
||||
без документов канона или конвейер без обоих. Практикой посылка не подтвердилась
|
||||
— подмножество не понадобилось ни разу, — а платился раскол помеченными копиями
|
||||
общих правил и ветками деградации на каждый вызов соседа.
|
||||
без документов канона или конвейер без обоих. Практика посылку не подтвердила —
|
||||
подмножество не понадобилось ни разу, — а платился раскол помеченными копиями
|
||||
общих правил и веткой «плагина нет» на каждый вызов соседа.
|
||||
|
||||
**Что переехало в проекте.** Служебных файла было два, стал один:
|
||||
|
||||
@@ -74,7 +74,9 @@
|
||||
6. **Поправить свои вызовы скиллов** — в `CLAUDE.md`, в `Taskfile`, в записях
|
||||
задач: короткое имя разрешится в проектную копию, а прежнее полное не
|
||||
разрешится вовсе.
|
||||
7. `docs.py check` и `tasks.py check --dir <каталог задач>` — до отсутствия
|
||||
7. **Поднять версию** — `docs.py bump`. Последним шагом: число объявляет
|
||||
пройденными шаги журнала, и раньше времени поднятое врёт.
|
||||
8. `docs.py check` и `tasks.py check --dir <каталог задач>` — до отсутствия
|
||||
дрейфа.
|
||||
|
||||
**Чего делать не надо.** Переписывать прошлые записи журналов под новые имена.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Скелеты документов канона
|
||||
|
||||
Что кладут `init` и `canon adopt` в незаполненный слот. Правило одно:
|
||||
Что кладут `init` и `doc-canon adopt` в незаполненный слот. Правило одно:
|
||||
**честная информативная строка вместо заглушки**. Проход читает строку как факт;
|
||||
`<!-- заполнить: … -->` он читает как пробел, и `docs.py check` о таком
|
||||
плейсхолдере напоминает.
|
||||
@@ -428,9 +428,10 @@ severity стоит здесь, а не выводится каждым прох
|
||||
|
||||
## `openspec/config.yaml`
|
||||
|
||||
**Образец переехал.** Файл заводит и заполняет конвейер — скилл
|
||||
**Образец переехал.** Файл заводит и заполняет скилл
|
||||
`av-dev:code-openspec`, — потому что по OpenSpec работает он, а не канон
|
||||
документов. Проект без конвейера каталога `openspec/` не имеет вовсе, и образец
|
||||
документов. Проект, не ведущий задачи циклом SDD, каталога `openspec/` не имеет
|
||||
вовсе, и образец
|
||||
файла, которого у него нет, в скелетах канона лежал бы мёртвым грузом.
|
||||
|
||||
**Форму не проверяет и `docs.py`** — с канона 10 он о файле молчит вовсе.
|
||||
@@ -455,7 +456,7 @@ dir = "tasks"
|
||||
```
|
||||
|
||||
`<текущая версия>` подставляет `init` или `adopt`, целым числом; берётся она из
|
||||
`docs.py version` (строка «раскладка скрипта»), а не из памяти. Литерал здесь
|
||||
`docs.py version` (строка «версия раскладки, скрипт»), а не из памяти. Литерал здесь
|
||||
протухает при каждом повышении, поэтому его тут и нет: незамещённый плейсхолдер
|
||||
ломает разбор TOML громко, а отставшее число дало бы дрейф молча.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user