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 — результат строкой.