av
863769406f
Имя `.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` отвергался как указатель путей: отвергнут был указатель, а не имя
131 lines
11 KiB
Markdown
131 lines
11 KiB
Markdown
# Адаптация каталога задач
|
||
|
||
Проект, где задачи уже как-то ведутся, и из имеющегося материала **выводится**
|
||
заполненный каталог задач: цели, задачи, кладбище, индексы. Операция разовая —
|
||
после неё проект живёт скиллами `tasks` и `groom`.
|
||
|
||
**Это часть приведения проекта к канону.** Раскладку `docs/` целиком ведёт скилл
|
||
`av-dev-docs:canon`; он же зовёт этот сценарий на шаге «каталог задач», потому что
|
||
форматом задач владеет `tasks`, а не `canon`. Отдельно сценарий вызывается,
|
||
когда переводить надо **только** задачи.
|
||
|
||
Вход какой угодно: старая раскладка `av-dev-backlog` (индекс `README.md`,
|
||
кладбище `CLOSED.md`, приоритеты секциями, транслитные слаги, файлы рядом с
|
||
индексом), `TODO.md`, россыпь заметок, раздел «планы» в `README.md`, список
|
||
шагов роадмапа проекта.
|
||
|
||
## Три правила, из которых всё следует
|
||
|
||
1. **Сперва карта, потом файлы.** Человеку показывается, что найдено, как
|
||
разложилось по целям и **что не разложилось**, — и только после подтверждения
|
||
пишется хоть один файл. Это то же правило, что у интейка находок ревью:
|
||
массовое заведение записей без подтверждения — самый дорогой отказ, потому
|
||
что разгребает его потом переоценка.
|
||
2. **Ничего не терять.** Исходный текст переезжает в тело, «зачем» и причина
|
||
сохраняются, кладбище переносится строка в строку. Переименование слага —
|
||
не правка, а **перенос ссылок**: он делается одним проходом вместе с
|
||
переименованием, иначе останутся битые ссылки, которых никто не проверяет.
|
||
3. **Что не классифицировалось — назвать поимённо.** Проглоченный пункт
|
||
выглядит как «всё перенеслось». Список «не разложилось» идёт в доклад
|
||
целиком, с причиной по каждому пункту.
|
||
|
||
## Форма: карта — суждение — запись
|
||
|
||
Механику несёт `tasks.py adopt`, суждение — ты. Разделено ровно по границе
|
||
«машина умеет / не умеет»:
|
||
|
||
```
|
||
tk="$CLAUDE_PLUGIN_ROOT/skills/tasks/scripts/tasks.py"
|
||
|
||
python3 $tk adopt scan --from docs/backlog docs/plan.md TODO.md \
|
||
--target tasks --out tasks-adopt-plan.json # только чтение
|
||
python3 $tk adopt apply --plan tasks-adopt-plan.json \
|
||
--refs docs openspec CLAUDE.md README.md # запись
|
||
```
|
||
|
||
`scan` ничего не пишет, кроме карты: он распознаёт раскладку, собирает записи,
|
||
поля «зачем», причины, кладбище, помечает похожее на транслит и на открытый вопрос в
|
||
прозе, и **называет поимённо** то, что не разложилось. `apply` пишет каталог
|
||
целиком одним проходом и чинит перекрёстные ссылки.
|
||
|
||
Между ними — твоя работа, которую машина не сделает:
|
||
|
||
- **английские слаги.** Перевести `taj-brejk-pri-ravnoj-polnote` в
|
||
`tie-break-equal-completeness` может только тот, кто понимает смысл. `scan`
|
||
честно говорит: проверить надо **все** слаги, признаки транслита — эвристика;
|
||
- **цели.** Шаги роадмапа — готовые цели в **`Запланировано`** (очередь и
|
||
обоснование у них уже есть); тематические скопления задач — цели в
|
||
**`Направления`** («прочность слияния»,
|
||
«журнал и пересборка»). Предлагаешь ты, назначает человек;
|
||
- **что вообще не задача.** Обоснование порядка шагов, абзац прозой, заголовок
|
||
раздела — это не пункты беклога, и они уходят в «не разложилось» с причиной.
|
||
|
||
## Порядок
|
||
|
||
1. **Осмотрись.** Где лежат задачи, роадмап, заметки. Каталог задач по канону —
|
||
всегда `tasks`. Секции беклога (`--sections`) — по умолчанию
|
||
`Ядро,Инфра`; если у проекта деление другое по существу, оно называется
|
||
здесь, а не подгоняется под умолчание, и становится **заголовками `##`
|
||
индекса** — их единственным домом. В `.tasks.json` секции не пишутся: там
|
||
версия формата и имена частей, а второй список секций разошёлся бы с
|
||
заголовками молча.
|
||
2. **`adopt scan`** по всем источникам разом. Один прогон, одна карта: два
|
||
прохода дадут два несогласованных состояния.
|
||
3. **Заполни карту**: `slug` (английский), `section`, `goal` у каждой записи;
|
||
список `goals` — из шагов роадмапа и из тем. Закрытый шаг целью не
|
||
заводится. Пустой `goal` законен у `fix`, `chore` и `research` — они служат
|
||
работоспособности, а не направлению; у `feature` цель обязательна.
|
||
4. **Покажи человеку карту** через `AskUserQuestion`, ≤3 вопроса за итерацию,
|
||
рекомендация первым вариантом. Показывается: сколько записей, предлагаемые
|
||
цели (порядок и темы) с обоснованием, спорные отнесения, список «не
|
||
разложилось». Массовые механические решения (слаги, порядок строк) не
|
||
выносятся — это механика.
|
||
5. **`adopt apply`.** `--refs` перечисляет **всё**, где могут стоять ссылки на
|
||
слаги: документация, архив изменений, `CLAUDE.md`, `README.md`. Скрипт
|
||
посчитает и покажет, сколько ссылок поправлено и по каким слагам.
|
||
6. **`tasks.py check`** и доклад.
|
||
|
||
`apply` отказывается писать поверх живого каталога и проверяет карту целиком
|
||
**до** первой записи: неверная секция, дубль слага, цель, которой нет в карте —
|
||
всё это отказ до того, как на диске появился хотя бы один файл.
|
||
|
||
## Переходное состояние — объявляется, а не заминается
|
||
|
||
Сразу после адаптации задачи в большинстве своём **не готовы к взятию**: у них
|
||
нет критериев приёмки, а у части может не быть цели. Это нормально, но обязано
|
||
быть названо, иначе следующий агент примет пустой беклог за поломку.
|
||
|
||
`apply` печатает состояние по факту: сколько задач без цели (это **ошибки**
|
||
`check`) и сколько не собрало разделы своего типа (для `check` это не ошибка, а
|
||
строка здоровья, но `ready` такую задачу не пропустит). Закрывается это
|
||
**порциями груминга** — скилл
|
||
`groom`, 5–8 задач за порцию: проставить цели, превратить «готово, когда» в
|
||
критерии с оракулами, вынуть вопросы из прозы в раздел «Вопросы». Там же
|
||
беклогу впервые назначается **порядок**: после адаптации его нет вовсе, а
|
||
очередь и есть то, ради чего каталог заводят.
|
||
|
||
Готовность к первой задаче — не «`check` зелёный», а «`ready` пропускает хотя бы
|
||
верхние строки очереди».
|
||
|
||
## Чего адаптация не делает
|
||
|
||
- **Не удаляет источники.** Старый каталог остаётся на месте: сверить и убрать —
|
||
дело человека, удалять чужое молча нельзя. В доклад идёт готовая команда.
|
||
- **Не переписывает подписи ссылок.** `[docs/backlog](tasks/BACKLOG.md)` —
|
||
цель поправлена, текст остался; это правится глазами, и таких мест немного.
|
||
- **Не сочиняет критерии приёмки и не придумывает цели**, которых в материале
|
||
нет. Придуманная цель хуже отсутствующей: под неё заведут задачи.
|
||
- **Не трогает историю.** В коммитах старые слаги остаются, и это нормально.
|
||
|
||
## Доклад
|
||
|
||
- Источники и что в каждом распознано (раскладка, индекс, кладбище, секции).
|
||
- Сколько записей перенесено, сколько целей заведено (порядок / темы) и откуда
|
||
каждая выведена.
|
||
- **Переименования**: сколько слагов, сколько ссылок поправлено и в скольких
|
||
файлах — числом, а не «поправлены ссылки».
|
||
- **Не разложилось**: поимённо, с причиной.
|
||
- Переходное состояние: сколько задач без цели, сколько без критериев, чем и за
|
||
сколько порций закрывается.
|
||
- `tasks.py check` — результат строкой.
|