av-dev-tasks: починены находки ревью, добавлена адаптация чужого репозитория

- атомарность: sprint drop и move собирают план правок целиком и пишут
  одним проходом; раньше отказ на втором слаге оставлял первый файл
  переписанным при нетронутом индексе
- хук переехал в мета-строку файла: индекс стал производным, и check --fix
  больше не теряет текст, восстанавливая строку
- механизировано то, что было записано, но не проверялось: слаг спринта и
  автотег, отказ по факту непустого раздела вопросов, число критериев,
  пометка decomposed, покрытие причин
- reopen возвращает закрытую задачу: без него порядок «пайплайн доложил →
  приёмщик судит → владелец закрывает» был односторонним
- скилл adopt: приходит в чужой репозиторий и выводит заполненный каталог
  задач. На копии беклога healthlog — 12 целей, 38 задач, 36 переименований,
  86 ссылок в 36 файлах, check зелёный
This commit is contained in:
av
2026-08-03 11:45:23 +03:00
parent 9219f4a5cd
commit 20dca29add
8 changed files with 1768 additions and 329 deletions
+122
View File
@@ -0,0 +1,122 @@
---
name: adopt
description: Прийти в чужой репозиторий и вывести каталог задач из того, что там уже есть — старая раскладка беклога (README-индекс, CLOSED-кладбище, транслитные слаги), TODO.md, россыпь заметок, раздел «планы» в README, список шагов в плане проекта. Сперва карта находок и целей человеку, запись только после подтверждения; слаги переименовываются в английские вместе с починкой перекрёстных ссылок. Использовать, когда просят перевести проект на этот формат задач, перенести беклог, адаптировать существующие заметки под цели и спринты. Разовая операция: дальше проект ведут скиллы tasks и session.
---
# Адаптация чужого репозитория
Плагин приходит в проект, где задачи уже как-то ведутся, и **выводит** из
имеющегося материала заполненный каталог задач: цели, задачи, кладбище, индексы.
Операция разовая — после неё проект живёт скиллами `tasks` и `session`.
Вход какой угодно: старая раскладка `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 docs/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. **Осмотрись.** Где лежат задачи, план, заметки; читается ли `CLAUDE.md`
проекта — там может быть указатель на каталог. Секции беклога проекта
(`--sections`) — по умолчанию `ядро,инфра`; если у проекта деление другое по
существу, оно называется здесь, а не подгоняется под умолчание.
2. **`adopt scan`** по всем источникам разом. Один прогон, одна карта: два
прохода дадут два несогласованных состояния.
3. **Заполни карту**: `slug` (английский), `section`, `goal` у каждой записи;
список `goals` — из шагов плана и из кустов. Закрытый шаг плана целью не
заводится. Пустой `goal` — законный исход только у идеи.
4. **Покажи человеку карту** через `AskUserQuestion`, ≤3 вопроса за итерацию,
рекомендация первым вариантом. Показывается: сколько записей, предлагаемые
цели (линия и кусты) с обоснованием, спорные отнесения, список «не
разложилось». Массовые механические решения (слаги, порядок строк) не
выносятся — это механика.
5. **`adopt apply`.** `--refs` перечисляет **всё**, где могут стоять ссылки на
слаги: документация, архив изменений, `CLAUDE.md`, `README.md`. Скрипт
посчитает и покажет, сколько ссылок поправлено и по каким слагам.
6. **`tasks.py check`** и доклад.
`apply` отказывается писать поверх живого каталога и проверяет карту целиком
**до** первой записи: неверная секция, дубль слага, цель, которой нет в карте —
всё это отказ до того, как на диске появился хотя бы один файл.
## Переходное состояние — объявляется, а не заминается
Сразу после адаптации задачи в большинстве своём **не готовы к взятию**: у них
нет критериев приёмки, а у части может не быть цели. Это нормально, но обязано
быть названо, иначе следующий агент примет пустой беклог за поломку.
`apply` печатает состояние по факту: сколько задач без цели (это **ошибки**
`check`) и сколько без критериев (`check` их ошибкой не считает, но `sprint
take` такую задачу не возьмёт). Закрывается это **порциями переоценки** — шаг 3
скилла `session`, 5–8 задач за порцию: проставить цели, превратить «готово,
когда» в критерии с оракулами, вынуть вопросы из прозы в раздел «Вопросы».
Готовность к первому спринту — не «`check` зелёный», а «есть 2–5 критериев хотя
бы у набора под одну цель».
## Чего адаптация не делает
- **Не удаляет источники.** Старый каталог остаётся на месте: сверить и убрать —
дело человека, удалять чужое молча нельзя. В доклад идёт готовая команда.
- **Не переписывает подписи ссылок.** `[docs/backlog](docs/tasks/BACKLOG.md)`
цель поправлена, текст остался; это правится глазами, и таких мест немного.
- **Не сочиняет критерии приёмки и не придумывает цели**, которых в материале
нет. Придуманная цель хуже отсутствующей: под неё соберут спринт.
- **Не трогает историю.** В коммитах старые слаги остаются, и это нормально.
## Доклад
- Источники и что в каждом распознано (раскладка, индекс, кладбище, секции).
- Сколько записей перенесено, сколько целей заведено (линия / кусты) и откуда
каждая выведена.
- **Переименования**: сколько слагов, сколько ссылок поправлено и в скольких
файлах — числом, а не «поправлены ссылки».
- **Не разложилось**: поимённо, с причиной.
- Переходное состояние: сколько задач без цели, сколько без критериев, чем и за
сколько порций закрывается.
- `tasks.py check` — результат строкой.