docs(agents): описаны операции карты wayfinder в Gitea

- Зачем:
  - навык wayfinder ожидает раздел про операции карты в документе трекера, а
    в Gitea 1.27 нет подзадач, поэтому конвенции надо было зафиксировать явно.
- Что:
  - описана принадлежность тикета карте через метку и ссылку в теле, поскольку
    родительских связей в API нет.
  - блокировки заведены на нативные зависимости Gitea, добавлены запросы фронтира.
  - зафиксированы три особенности tea api: путь без ведущего слэша, обязательные
    owner и repo в теле зависимости, нулевой код возврата при HTTP 404.
- Проверка:
  - tea issues list --remote origin --labels wayfinder:map
  - tea api --remote origin repos/ddmitry/local-transcriber/issues/14/dependencies

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Dmitriy Dementiev
2026-08-12 15:23:16 +03:00
co-authored by Claude Opus 5
parent 7e348e400f
commit a65cb74d88
+52
View File
@@ -64,3 +64,55 @@ tea labels list --remote origin
За пределами рабочего дерева явно указывать репозиторий За пределами рабочего дерева явно указывать репозиторий
`ddmitry/local-transcriber` и настроенный Gitea login. `ddmitry/local-transcriber` и настроенный Gitea login.
## Wayfinding operations
Навык `wayfinder` ведёт карту как issue с меткой `wayfinder:map`, а её тикеты —
как отдельные issue с метками `wayfinder:research`, `wayfinder:prototype`,
`wayfinder:grilling` и `wayfinder:task`.
### Принадлежность карте
Gitea 1.27 не имеет подзадач в API: среди эндпоинтов `issues/{index}` есть
`dependencies` и `blocks`, но родительских связей нет. Поэтому принадлежность
тикета карте выражается двумя способами сразу: меткой `wayfinder:<тип>` и первой
строкой тела со ссылкой на карту.
```markdown
Часть карты: [<заголовок карты>](<url>) (#<номер>)
```
### Блокировки
Блокировки — нативные зависимости Gitea, они отображаются в интерфейсе. Тикет
разблокирован, когда закрыты все блокирующие его тикеты.
```powershell
tea api --remote origin -X POST `
repos/ddmitry/local-transcriber/issues/<блокируемый>/dependencies `
-d '{"index": <блокирующий>, "owner": "ddmitry", "repo": "local-transcriber"}'
```
### Запросы фронтира
Фронтир — открытые, разблокированные и никому не назначенные тикеты карты.
Заявка на тикет — назначение его на себя до начала работы.
```powershell
tea issues list --remote origin --labels wayfinder:map
tea issues list --remote origin --labels wayfinder:research,wayfinder:prototype,wayfinder:grilling,wayfinder:task
tea api --remote origin repos/ddmitry/local-transcriber/issues/<номер>/dependencies
```
### Особенности `tea api`
Три вещи, на которых легко потерять время:
- **Путь без ведущего слэша.** `repos/{owner}/{repo}/...` работает,
`/repos/...` возвращает `404 page not found`. Подстановка `{owner}` и `{repo}`
из контекста репозитория при этом не срабатывает — писать владельца и имя явно.
- **Тело зависимости требует `owner` и `repo`.** Только `{"index": N}` даёт
`repository does not exist [id: 0, uid: 0, owner_name: , name: ]`.
- **Код возврата не отражает HTTP-статус.** `tea api` завершается с нулевым
кодом даже на 404, поэтому скрипты должны запрашивать `-i` и разбирать строку
`HTTP/...` из stderr, иначе ошибки пройдут незамеченными.