docs(agents): трекер задач переведён на GitHub Issues

- Зачем: - пилот нативного трекера на фиче mentee-path: спека в git как источник истины, тонкий корневой issue, дочерние issues-постановки. - Что: - docs/agents/issue-tracker.md переписан с локального markdown на GitHub Issues (gh CLI, правило тонкого корневого issue, архив старых задач — в истории git, срез 0e312b3). - triage-метки стали настоящими метками GitHub (созданы в репозитории), AGENTS.md обновлён. - Проверка: - gh label list — пять канонических меток на месте.
2026-07-19 22:37:25 +03:00
parent de7f62cbab
commit 79a3d07cb1
3 changed files with 62 additions and 22 deletions
@@ -41,11 +41,11 @@

 ### Issue tracker

-Локальный markdown: задачи и PRD живут файлами в `.scratch/<feature>/` (коммитятся, `.scratch/` не в `.gitignore`). GitHub Issues не используются. См. `docs/agents/issue-tracker.md`.
+GitHub Issues (через CLI `gh`). Спека фичи — файлом в `docs/specs/` (источник истины), корневой issue — тонкий, со ссылкой на спеку и чек-листом дочерних issues. См. `docs/agents/issue-tracker.md`.

 ### Triage labels

-Пять канонических ролей, строки совпадают с именами (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`). См. `docs/agents/triage-labels.md`.
+Пять канонических ролей как метки GitHub, имена совпадают (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`). См. `docs/agents/triage-labels.md`.

 ### Domain docs

@@ -1,24 +1,63 @@
-# Issue tracker: локальный markdown
+# Issue tracker: GitHub

-Задачи и PRD этого репозитория живут markdown-файлами в `.scratch/`. GitHub Issues
-не используются — не вызывать `gh issue create`. Файлы в `.scratch/` коммитятся
-(`.scratch/` не в `.gitignore`).
+Задачи этого репозитория живут в GitHub Issues. Все операции — через CLI `gh`;
+репозиторий `gh` определяет сам по `git remote`.

-## Соглашения
+- **Создать issue**: `gh issue create --title "..." --body "..."` (многострочное
+  тело — heredoc'ом).
+- **Прочитать issue**: `gh issue view <номер> --comments`.
+- **Список**: `gh issue list --state open --json number,title,labels` с нужными
+  фильтрами `--label` / `--state`.
+- **Комментарий**: `gh issue comment <номер> --body "..."`.
+- **Метки**: `gh issue edit <номер> --add-label "..."` / `--remove-label "..."`.
+- **Закрыть**: `gh issue close <номер> --comment "..."`.

- Одна фича — один каталог: `.scratch/<feature-slug>/`
- PRD фичи — `.scratch/<feature-slug>/PRD.md` (по сути транзиентная спека: снимок
-  понимания на момент работы; долговечные решения идут в ADR — см. `docs/agents/domain.md`)
- Задачи реализации — `.scratch/<feature-slug>/issues/<NN>-<slug>.md`, нумерация с `01`
- Состояние триажа — строкой `Status:` у верха файла задачи (строки ролей — в `triage-labels.md`)
- Завершённая задача — `Status: done`: локальный аналог «закрыть issue» в GitHub.
-  Это состояние жизненного цикла трекера, а не роль триажа (в `triage-labels.md` его нет)
- Комментарии и история — в конец файла под заголовком `## Comments`
+## Спека — источник истины
+
+- Спецификация фичи — файл в `docs/specs/`, версионируется с кодом.
+- Корневой issue фичи — **тонкий**: ссылка на спеку + чек-лист дочерних issues
+  (`- [ ] #NN`). Содержание спеки в issue не дублируется — истина одна, в git.
+- Дочерние issues — полноценные самодостаточные постановки: цель, критерии
+  приёмки чекбоксами, границы («что трогать нельзя»), «сначала прочитать»,
+  команды проверки.
+- Итоговые резолюции и решения — в спеку/ADR тем же PR; issue — рабочая
+  переписка, она не обязана переживать фичу.

 ## Когда скилл говорит «опубликовать в issue tracker»

-Создать файл в `.scratch/<feature-slug>/` (каталог создать при необходимости).
+Создать GitHub issue.

 ## Когда скилл говорит «достать тикет»

-Прочитать файл по указанному пути. Обычно путь или номер задачи передаёт пользователь.
+`gh issue view <номер> --comments`.
+
+## PR как поверхность триажа
+
+**Нет** — одиночный учебный репозиторий, внешних PR не ждём. (Если включить —
+`/triage` начнёт гонять PR через те же метки и состояния командами `gh pr ...`.)
+
+## Wayfinding-операции
+
+Используются `/wayfinder`. Карта — один issue, тикеты — дочерние issues.
+
+- **Карта**: issue с меткой `wayfinder:map` (Notes / Decisions-so-far / Fog в теле).
+- **Дочерний тикет**: sub-issue карты (`gh api` на endpoint sub-issues); если
+  sub-issues недоступны — пункт task-list в теле карты + `Part of #<map>` в
+  начале тела тикета. Метки: `wayfinder:<type>` (`research`/`prototype`/
+  `grilling`/`task`).
+- **Блокировки**: нативные issue dependencies —
+  `gh api --method POST repos/<owner>/<repo>/issues/<child>/dependencies/blocked_by -F issue_id=<db-id блокера>`
+  (`<db-id>` — числовой database id: `gh api repos/<owner>/<repo>/issues/<n> --jq .id`,
+  не `#номер`). Fallback — строка `Blocked by: #<n>` в начале тела. Тикет
+  разблокирован, когда все блокеры закрыты.
+- **Фронтир**: открытые дети карты минус заблокированные и назначенные; первый
+  в порядке карты.
+- **Взять в работу**: `gh issue edit <n> --add-assignee @me`.
+- **Закрыть**: комментарий с ответом, `gh issue close`, указатель на контекст —
+  в Decisions-so-far карты.
+
+## Архив
+
+До 2026-07-19 задачи велись markdown-файлами в `.scratch/<feature>/issues/`
+(фичи `data-generator` и `generator-model-time-startup-history`, задачи 01–21).
+Не мигрированы; доступны в истории git — срез `0e312b3`.
@@ -1,14 +1,15 @@
 # Triage labels

-Скиллы оперируют пятью каноническими ролями триажа. Здесь они сопоставлены со
-строками, которые реально используются в этом репозитории (в строке `Status:` файла задачи).
+Скиллы оперируют пятью каноническими ролями триажа. Здесь они сопоставлены с
+метками GitHub Issues этого репозитория.

-| Роль в mattpocock/skills | Строка у нас      | Значение                                       |
+| Роль в mattpocock/skills | Метка GitHub      | Значение                                       |
 | ------------------------ | ----------------- | ---------------------------------------------- |
 | `needs-triage`           | `needs-triage`    | Мейнтейнеру нужно оценить задачу               |
 | `needs-info`             | `needs-info`      | Ждём от репортёра дополнительную информацию     |
 | `ready-for-agent`        | `ready-for-agent` | Полностью специфицировано, можно отдать агенту  |
 | `ready-for-human`        | `ready-for-human` | Нужна ручная реализация человеком               |
-| `wontfix`                | `wontfix`         | Не будет сделано                                |
+| `wontfix`                | `wontfix`         | Не будет сделано                               |

-Правый столбец можно поменять под свою лексику. Сейчас — дефолт (строка = имя роли).
+Правый столбец можно поменять под свою лексику. Сейчас — дефолт (метка = имя
+роли); метки созданы в репозитории GitHub.