задачи: цель упразднена, у проекта появилась стадия

Тип goal и индекс ROADMAP.md убраны: цель — зонтик над параллельными
направлениями, а у проекта на одного человека список работ линеен. Роадмап
при этом наполовину дублировал беклог, а «что уже умеет» отвечают спеки и
git log индекса. Секция «Готово» удалена, а не перенесена.

Вместо цели — ось «стадия проекта»: build (беклог это план стройки, порядок
строк значит зависимость, секция одна) и support (очередь правок, порядок
значит важность, секции — полки домена). Стадия объявляется ключом
[tasks] stage, меняется командой stage, без неё check отказывает: порядок
строк нечем прочитать.

Ушли теги goal:/decomposed, поле «Секция», раздел «Завершение», флаги
--goal и edit --section. Версия раскладки 2 → 3, перевод проекта расписан
записью журнала.
This commit is contained in:
av
2026-08-13 14:26:21 +03:00
parent 0627199a1a
commit 3849f084be
26 changed files with 1128 additions and 1485 deletions
+48 -42
View File
@@ -1,7 +1,7 @@
# Адаптация каталога задач
Проект, где задачи уже как-то ведутся, и из имеющегося материала **выводится**
заполненный каталог задач: цели, задачи, кладбище, индексы. Операция разовая —
заполненный каталог задач: задачи, кладбище, индекс. Операция разовая —
после неё проект живёт скиллами `task-track` и `task-groom`.
**Это часть приведения проекта к канону.** Раскладку `docs/` целиком ведёт скилл
@@ -12,12 +12,12 @@
Вход какой угодно: старая раскладка `av-dev-backlog` (индекс `README.md`,
кладбище `CLOSED.md`, приоритеты секциями, транслитные слаги, файлы рядом с
индексом), `TODO.md`, россыпь заметок, раздел «планы» в `README.md`, список
шагов роадмапа проекта.
шагов плана проекта.
## Три правила, из которых всё следует
1. **Сперва карта, потом файлы.** Человеку показывается, что найдено, как
разложилось по целям и **что не разложилось**, — и только после подтверждения
1. **Сперва карта, потом файлы.** Человеку показывается, что найдено, в каком
порядке разложилось и **что не разложилось**, — и только после подтверждения
пишется хоть один файл. Это то же правило, что у интейка находок ревью:
массовое заведение записей без подтверждения — самый дорогой отказ, потому
что разгребает его потом переоценка.
@@ -38,7 +38,7 @@
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 # только чтение
--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 # запись
```
@@ -53,56 +53,60 @@ python3 $tk adopt apply --plan tasks-adopt-plan.json \
- **английские слаги.** Перевести `taj-brejk-pri-ravnoj-polnote` в
`tie-break-equal-completeness` может только тот, кто понимает смысл. `scan`
честно говорит: проверить надо **все** слаги, признаки транслита — эвристика;
- **цели.** Шаги роадмапа — готовые цели в **`Запланировано`** (очередь и
обоснование у них уже есть); тематические скопления задач — цели в
**`Направления`** («прочность слияния»,
«журнал и пересборка»). Предлагаешь ты, назначает человек;
- **стадия.** `--stage` называет, чем этот беклог будет: планом стройки или
очередью правок. Машине это не выводится — она видит список пунктов, а не то,
построено приложение или нет;
- **порядок.** Нумерованные шаги источника `scan` сохраняет по номерам, прочие
ставит следом. Дальше порядок — твоё суждение и подтверждение человека: на
стройке это зависимость, на доработке важность;
- **что вообще не задача.** Обоснование порядка шагов, абзац прозой, заголовок
раздела — это не пункты беклога, и они уходят в «не разложилось» с причиной.
## Порядок
1. **Осмотрись.** Где лежат задачи, роадмап, заметки. Каталог задач по канону —
всегда `tasks`. Секции беклога (`--sections`) — по умолчанию
`Ядро,Инфра`; если у проекта деление другое по существу, оно называется
здесь, а не подгоняется под умолчание, и становится **заголовками `##`
индекса** — их единственным домом. В `.av-dev.toml` секции не пишутся: там
версия формата и имена частей, а второй список секций разошёлся бы с
заголовками молча.
1. **Осмотрись и назови стадию.** Где лежат задачи, план, заметки; построено
приложение или строится. Каталог задач по канону — всегда `tasks`. Секции
беклога (`--sections`) — на стройке ровно одна (умолчание `План`), на
доработке сколько нужно (умолчание `Ядро,Инфра`); если у проекта деление
другое по существу, оно называется здесь, а не подгоняется под умолчание, и
становится **заголовками `##` индекса** — их единственным домом. В
`.av-dev.toml` секции не пишутся: там версия, стадия и имена частей, а второй
список секций разошёлся бы с заголовками молча.
2. **`adopt scan`** по всем источникам разом. Один прогон, одна карта: два
прохода дадут два несогласованных состояния.
3. **Заполни карту**: `slug` (английский), `section`, `goal` у каждой записи;
список `goals` — из шагов роадмапа и из тем. Закрытый шаг целью не
заводится. Пустой `goal` законен у `fix`, `chore` и `research` — они служат
работоспособности, а не направлению; у `feature` цель обязательна.
3. **Заполни карту**: `slug` (английский), `type` и `section` у каждой записи, и
**порядок `items`** — он уедет в индекс как есть. Пункт, помеченный
закрытым, не переносится вовсе.
4. **Покажи человеку карту** через `AskUserQuestion`, ≤3 вопроса за итерацию,
рекомендация первым вариантом. Показывается: сколько записей, предлагаемые
цели (порядок и темы) с обоснованием, спорные отнесения, список «не
разложилось». Массовые механические решения (слаги, порядок строк) не
выносятся — это механика.
рекомендация первым вариантом. Показывается: сколько записей, предлагаемый
порядок с обоснованием, спорные отнесения, список «не разложилось». Слаги не
выносятся — это механика; **порядок выносится всегда**, потому что механикой
он не является ни на одной стадии.
5. **`adopt apply`.** `--refs` перечисляет **всё**, где могут стоять ссылки на
слаги: документация, архив изменений, `CLAUDE.md`, `README.md`. Скрипт
посчитает и покажет, сколько ссылок поправлено и по каким слагам.
6. **`tasks.py check`** и доклад.
`apply` отказывается писать поверх живого каталога и проверяет карту целиком
**до** первой записи: неверная секция, дубль слага, цель, которой нет в карте —
всё это отказ до того, как на диске появился хотя бы один файл.
**до** первой записи: неверная секция, дубль слага, неназванный тип, две секции
при стадии `build`всё это отказ до того, как на диске появился хотя бы один
файл.
## Переходное состояние — объявляется, а не заминается
Сразу после адаптации задачи в большинстве своём **не готовы к взятию**: у них
нет критериев приёмки, а у части может не быть цели. Это нормально, но обязано
быть названо, иначе следующий агент примет пустой беклог за поломку.
нет критериев приёмки. Это нормально, но обязано быть названо, иначе следующий
агент примет пустой беклог за поломку.
`apply` печатает состояние по факту: сколько задач без цели (это **ошибки**
`check`) и сколько не собрало разделы своего типа (для `check` это не ошибка, а
строка здоровья, но `ready` такую задачу не пропустит). Закрывается это
**порциями груминга** — скилл
`groom`, 5–8 задач за порцию: проставить цели, превратить «готово, когда» в
критерии с оракулами, вынуть вопросы из прозы в раздел «Вопросы». Там же
беклогу впервые назначается **порядок**: после адаптации его нет вовсе, а
очередь и есть то, ради чего каталог заводят.
`apply` печатает состояние по факту: сколько задач не собрало разделы своего типа
(для `check` это не ошибка, а строка здоровья, но `ready` такую задачу не
пропустит). Закрывается это **порциями груминга** — скилл `groom`, 58 задач за
порцию: превратить «готово, когда» в критерии с оракулами, вынуть вопросы из
прозы в раздел «Вопросы».
**Порядок строк проверяется глазами отдельно.** На стройке он выведен из
нумерации источника, и там, где её не было, он случаен. На доработке машина
важности не знает вовсе — очередь расставляется первым же грумингом.
Готовность к первой задаче — не «`check` зелёный», а «`ready` пропускает хотя бы
верхние строки очереди».
@@ -113,18 +117,20 @@ python3 $tk adopt apply --plan tasks-adopt-plan.json \
дело человека, удалять чужое молча нельзя. В доклад идёт готовая команда.
- **Не переписывает подписи ссылок.** `[docs/backlog](tasks/BACKLOG.md)`
цель поправлена, текст остался; это правится глазами, и таких мест немного.
- **Не сочиняет критерии приёмки и не придумывает цели**, которых в материале
нет. Придуманная цель хуже отсутствующей: под неё заведут задачи.
- **Не сочиняет критерии приёмки** и не додумывает пользы, которой в материале
нет.
- **Не выводит стадию.** Список пунктов одинаково выглядит и планом стройки, и
очередью правок; отвечает `--stage`, а называет его человек.
- **Не трогает историю.** В коммитах старые слаги остаются, и это нормально.
## Доклад
- Источники и что в каждом распознано (раскладка, индекс, кладбище, секции).
- Сколько записей перенесено, сколько целей заведено (порядок / темы) и откуда
каждая выведена.
- Стадия и сколько записей перенесено; откуда взялся порядок (нумерация
источника или суждение).
- **Переименования**: сколько слагов, сколько ссылок поправлено и в скольких
файлах — числом, а не «поправлены ссылки».
- **Не разложилось**: поимённо, с причиной.
- Переходное состояние: сколько задач без цели, сколько без критериев, чем и за
сколько порций закрывается.
- Переходное состояние: сколько задач без критериев, чем и за сколько порций
закрывается.
- `tasks.py check` — результат строкой.