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

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

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

**Это часть приведения проекта к канону.** Раскладку `docs/` целиком ведёт скилл
`av-dev:canon`; он же зовёт этот сценарий на шаге «каталог задач», потому что
форматом задач владеет `task-track`, а не `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 \
        --stage build --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`
  честно говорит: проверить надо **все** слаги, признаки транслита — эвристика;
- **стадия.** `--stage` называет, чем этот беклог будет: планом стройки или
  очередью правок. Машине это не выводится — она видит список пунктов, а не то,
  построено приложение или нет;
- **порядок.** Нумерованные шаги источника `scan` сохраняет по номерам, прочие
  ставит следом. Дальше порядок — твоё суждение и подтверждение человека: на
  стройке это зависимость, на доработке важность;
- **что вообще не задача.** Обоснование порядка шагов, абзац прозой, заголовок
  раздела — это не пункты беклога, и они уходят в «не разложилось» с причиной.

## Порядок

1. **Осмотрись и назови стадию.** Где лежат задачи, план, заметки; построено
   приложение или строится. Каталог задач по канону — всегда `tasks`. Секции
   беклога (`--sections`) — на стройке ровно одна (умолчание `План`), на
   доработке сколько нужно (умолчание `Ядро,Инфра`); если у проекта деление
   другое по существу, оно называется здесь, а не подгоняется под умолчание, и
   становится **заголовками `##` индекса** — их единственным домом. В
   `.av-dev.toml` секции не пишутся: там версия, стадия и имена частей, а второй
   список секций разошёлся бы с заголовками молча.
2. **`adopt scan`** по всем источникам разом. Один прогон, одна карта: два
   прохода дадут два несогласованных состояния.
3. **Заполни карту**: `slug` (английский), `type` и `section` у каждой записи, и
   **порядок `items`** — он уедет в индекс как есть. Пункт, помеченный
   закрытым, не переносится вовсе.
4. **Покажи человеку карту** через `AskUserQuestion`, ≤3 вопроса за итерацию,
   рекомендация первым вариантом. Показывается: сколько записей, предлагаемый
   порядок с обоснованием, спорные отнесения, список «не разложилось». Слаги не
   выносятся — это механика; **порядок выносится всегда**, потому что механикой
   он не является ни на одной стадии.
5. **`adopt apply`.** `--refs` перечисляет **всё**, где могут стоять ссылки на
   слаги: документация, архив изменений, `CLAUDE.md`, `README.md`. Скрипт
   посчитает и покажет, сколько ссылок поправлено и по каким слагам.
6. **`tasks.py check`** и доклад.

`apply` отказывается писать поверх живого каталога и проверяет карту целиком
**до** первой записи: неверная секция, дубль слага, неназванный тип, две секции
при стадии `build` — всё это отказ до того, как на диске появился хотя бы один
файл.

## Переходное состояние — объявляется, а не заминается

Сразу после адаптации задачи в большинстве своём **не готовы к взятию**: у них
нет критериев приёмки. Это нормально, но обязано быть названо, иначе следующий
агент примет пустой беклог за поломку.

`apply` печатает состояние по факту: сколько задач не собрало разделы своего типа
(для `check` это не ошибка, а строка здоровья, но `ready` такую задачу не
пропустит). Закрывается это **порциями по 5–8 задач**: превратить «готово,
когда» в критерии с оракулами, вынуть вопросы из прозы в раздел «Вопросы». На
доработке это груминг (скилл `av-dev:task-groom`), на стройке — гигиена полей
этого скилла: груминга там нет.

**Порядок строк проверяется глазами отдельно.** На стройке он выведен из
нумерации источника, и там, где её не было, он случаен. На доработке машина
важности не знает вовсе — очередь расставляется первым же грумингом.

Готовность к первой задаче — не «`check` зелёный», а «`ready` пропускает хотя бы
верхние строки очереди».

## Чего адаптация не делает

- **Не удаляет источники.** Старый каталог остаётся на месте: сверить и убрать —
  дело человека, удалять чужое молча нельзя. В доклад идёт готовая команда.
- **Не переписывает подписи ссылок.** `[docs/backlog](tasks/BACKLOG.md)` —
  цель поправлена, текст остался; это правится глазами, и таких мест немного.
- **Не сочиняет критерии приёмки** и не додумывает пользы, которой в материале
  нет.
- **Не выводит стадию.** Список пунктов одинаково выглядит и планом стройки, и
  очередью правок; отвечает `--stage`, а называет его человек.
- **Не трогает историю.** В коммитах старые слаги остаются, и это нормально.

## Доклад

- Источники и что в каждом распознано (раскладка, индекс, кладбище, секции).
- Стадия и сколько записей перенесено; откуда взялся порядок (нумерация
  источника или суждение).
- **Переименования**: сколько слагов, сколько ссылок поправлено и в скольких
  файлах — числом, а не «поправлены ссылки».
- **Не разложилось**: поимённо, с причиной.
- Переходное состояние: сколько задач без критериев, чем и за сколько порций
  закрывается.
- `tasks.py check` — результат строкой.