dev-skills/av-dev/skills/task-track/references/adopt.md

# Адаптация каталога задач

Проект, где задачи уже как-то ведутся, и из имеющегося материала **выводится**
заполненный каталог задач: цели, задачи, кладбище, индексы. Операция разовая —
после неё проект живёт скиллами `task-track` и `task-groom`.

**Это часть приведения проекта к канону.** Раскладку `docs/` целиком ведёт скилл
`av-dev:doc-canon`; он же зовёт этот сценарий на шаге «каталог задач», потому что
форматом задач владеет `task-track`, а не `doc-canon`. Отдельно сценарий вызывается,
когда переводить надо **только** задачи.

Вход какой угодно: старая раскладка `av-dev-backlog` (индекс `README.md`,
кладбище `CLOSED.md`, приоритеты секциями, транслитные слаги, файлы рядом с
индексом), `TODO.md`, россыпь заметок, раздел «планы» в `README.md`, список
шагов роадмапа проекта.

## Три правила, из которых всё следует

1. **Сперва карта, потом файлы.** Человеку показывается, что найдено, как
   разложилось по целям и **что не разложилось**, — и только после подтверждения
   пишется хоть один файл. Это то же правило, что у интейка находок ревью:
   массовое заведение записей без подтверждения — самый дорогой отказ, потому
   что разгребает его потом переоценка.
2. **Ничего не терять.** Исходный текст переезжает в тело, «зачем» и причина
   сохраняются, кладбище переносится строка в строку. Переименование слага —
   не правка, а **перенос ссылок**: он делается одним проходом вместе с
   переименованием, иначе останутся битые ссылки, которых никто не проверяет.
3. **Что не классифицировалось — назвать поимённо.** Проглоченный пункт
   выглядит как «всё перенеслось». Список «не разложилось» идёт в доклад
   целиком, с причиной по каждому пункту.

## Форма: карта — суждение — запись

Механику несёт `tasks.py adopt`, суждение — ты. Разделено ровно по границе
«машина умеет / не умеет»:

```
tk="$CLAUDE_PLUGIN_ROOT/skills/task-track/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`) — по умолчанию
   `Ядро,Инфра`; если у проекта деление другое по существу, оно называется
   здесь, а не подгоняется под умолчание, и становится **заголовками `##`
   индекса** — их единственным домом. В `.av-dev.toml` секции не пишутся: там
   версия формата и имена частей, а второй список секций разошёлся бы с
   заголовками молча.
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` — результат строкой.