Merge branch 'docs/gitea-issues': задачи в Gitea через tea

2026-09-28 11:09:59 -04:00
commit eaa81f4f8b
@@ -52,27 +52,27 @@ This repository contains personal dotfiles and configurations for a highly produ

 Внутренние рассуждения и промежуточные пометки по ходу работы веди на английском — он экономнее по токенам (кириллица занимает примерно в 1,5–2 раза больше). На русском остаётся всё, что видит и хранит проект: итоговые ответы пользователю, документы, комментарии в коде и сообщения коммитов.

-## Agent skills
+## Навыки агентов

-### Issue tracker
+### Хранилище задач

-Задачи хранятся локальными Markdown-файлами под `.scratch/`. См. `docs/agents/issue-tracker.md`.
+Задачи хранятся в Gitea Issues (`git.dementev.space`), работа с ними — через CLI `tea`. См. `docs/agents/issue-tracker.md`.

-### Triage labels
+### Состояния triage

-Используются стандартные названия состояний triage. См. `docs/agents/triage-labels.md`.
+Состояния triage — метки Gitea со стандартными названиями. См. `docs/agents/triage-labels.md`.

-### Domain docs
+### Документы предметной области

-Используется схема single-context: корневой `CONTEXT.md` и общие ADR в `docs/adr/`. См. `docs/agents/domain.md`.
+Одна предметная область на весь репозиторий: корневой `CONTEXT.md` и общие ADR в `docs/adr/`. См. `docs/agents/domain.md`.

-### Handoffs
+### Записки для передачи работы

 Записки для продолжения работы в новой сессии — `.scratch/handoffs/YYYYMMDD-HHMM-<slug>.md` (одноразовые, уборка best-effort; скилл `/handoff` пишет сюда).

 ### `.scratch/` — локальная рабочая зона

-Весь `.scratch/` — заметки по ходу дела: handoffs, PRD фич, нарезка задач. Каталог в `.gitignore`: он живёт только на этой машине и в Git не попадает.
+Весь `.scratch/` — заметки по ходу дела: handoffs и черновики (задачи живут в Gitea). Каталог в `.gitignore`: он живёт только на этой машине и в Git не попадает.

 Долговечное знание держим **вне** `.scratch/` (в `docs/`, `CONTEXT.md`) и коммитим вместе с работой. Прежде чем сливать фиче-ветку, убедись, что долговечная часть уже вынесена туда: остальное из `.scratch/` потом не восстановить.

@@ -1,6 +1,6 @@
 # Документы предметной области

-Репозиторий использует схему single-context.
+В репозитории одна предметная область: один `CONTEXT.md` в корне и общие ADR.

 ## Что читать перед изучением репозитория

@@ -1,47 +1,62 @@
-# Хранилище задач: локальные Markdown-файлы
+# Хранилище задач: Gitea

-Задачи и спецификации этого репозитория хранятся в `.scratch/`.
+Задачи и спецификации этого репозитория хранятся в Gitea Issues на
+`git.dementev.space` (репозиторий `ddmitry/dotfiles`). Все операции — через
+CLI `tea`. Внутри клона `tea` сам находит репозиторий и учётную запись по
+`git remote`; если не нашёл, добавь `--repo ddmitry/dotfiles`.

-## Структура
+GitVerse — только зеркало, задачи там не ведём.

- Одна возможность на каталог: `.scratch/<feature-slug>/`.
- Спецификация: `.scratch/<feature-slug>/spec.md`.
- Каждая задача хранится в отдельном файле:
-  `.scratch/<feature-slug>/issues/<NN>-<slug>.md`.
- Нумерация задач начинается с `01`.
- Состояние triage записывается строкой `Status:` в начале файла.
- Обсуждение дописывается в конец файла под заголовком `## Comments`.
+Заголовки, описания и комментарии задач пишутся по-русски.

-## Жизненный цикл
+## Команды

- `.scratch/` указан в `.gitignore`: задачи живут только на этой машине и в
-  Git не попадают.
- Они эфемерны: после завершения работы каталог можно удалить.
- Всё, что должно пережить задачу (решения, спецификации), до слияния
-  переносится в `docs/` и коммитится.
+- **Создать задачу**: `tea issues create --title "..." --description-file -`
+  с текстом через heredoc. Метки — `--labels "a,b"`.
+- **Прочитать задачу**: `tea issues <номер> --comments`.
+- **Список задач**: `tea issues list --state open --labels "..." --fields
+  index,title,labels,assignees --output json`.
+- **Комментарий**: `tea comment <номер> "..."`.
+- **Метки**: `tea issues edit <номер> --add-labels "..."` /
+  `--remove-labels "..."`. Если метки ещё нет в репозитории, создай её:
+  `tea labels create --name "..." --color "#..."`.
+- **Закрыть**: сначала комментарий с причиной, затем `tea issues close <номер>`.
+
+## PR как источник задач
+
+**PR как источник запросов: нет.** _(Поставь `да`, если внешние PR в этом
+репозитории нужно разбирать как запросы на доработку; `/triage` читает этот
+флаг.)_
+
+У задач и PR в Gitea общая нумерация: голый `#42` может оказаться и тем, и
+другим. Проверяй через `tea issues 42` или `tea pulls 42`.

 ## Публикация задачи

-Когда навык просит опубликовать задачу, нужно создать файл внутри
-`.scratch/<feature-slug>/`, при необходимости создав каталог.
+Когда навык просит опубликовать задачу, нужно создать задачу в Gitea.

 ## Получение задачи

-Нужно прочитать файл по переданному пути. Обычно пользователь указывает путь
-или номер задачи.
+Нужно выполнить `tea issues <номер> --comments`.

 ## Работа `/wayfinder`

-Карта работы хранится отдельно от дочерних задач:
+Карта — одна задача, дочерние задачи — отдельные задачи Gitea.

- Карта: `.scratch/<effort>/map.md`.
- Дочерняя задача: `.scratch/<effort>/issues/NN-<slug>.md`.
- Строка `Type:` содержит тип: `research`, `prototype`, `grilling` или `task`.
- Строка `Status:` содержит состояние `claimed` или `resolved`.
- Зависимости перечисляются строкой `Blocked by: NN, NN`.
- Задача свободна, если она открыта, не заблокирована и не занята.
- Из нескольких свободных задач первой выбирается задача с меньшим номером.
- При взятии задачи нужно установить `Status: claimed` и сохранить файл.
- При завершении нужно добавить ответ под заголовком `## Answer`, установить
-  `Status: resolved` и добавить краткий итог со ссылкой в раздел решений
-  файла `map.md`.
+- **Карта**: задача с меткой `wayfinder:map`; в описании — разделы
+  «Заметки», «Принятые решения» и «Неясности».
+- **Дочерняя задача**: первой строкой описания — `Часть #<карта>`; в
+  описании карты — список дочерних задач. Метка типа: `wayfinder:<тип>`
+  (`research`, `prototype`, `grilling` или `task`).
+- **Зависимости**: встроенные зависимости Gitea. Добавить блокирующую
+  задачу:
+  `tea api -X POST repos/ddmitry/dotfiles/issues/<дочерняя>/dependencies
+  -d '{"owner":"ddmitry","repo":"dotfiles","index":<блокирующая>}'`.
+  Посмотреть: `tea api repos/ddmitry/dotfiles/issues/<n>/dependencies`.
+  Задача свободна от блокировок, когда все блокирующие задачи закрыты.
+- **Свободные задачи**: открытые дочерние задачи карты без открытых
+  блокирующих и без исполнителя; первой берётся та, что раньше в списке карты.
+- **Взять задачу**: `tea issues edit <n> --add-assignees ddmitry` — первым
+  действием сессии.
+- **Завершить**: комментарий с ответом, `tea issues close <n>`, затем краткий
+  итог со ссылкой в раздел «Принятые решения» описания карты.
@@ -1,9 +1,10 @@
 # Состояния triage

-Навыки используют пять стандартных ролей. Для локального хранилища выбранное
-значение записывается в строке `Status:` файла задачи.
+Навыки используют пять стандартных ролей. В Gitea каждая роль — метка
+задачи с тем же названием. Если метки ещё нет в репозитории, её нужно
+создать (`tea labels create`), а не придумывать другое название.

-| Роль навыка | Значение `Status:` | Смысл |
+| Роль навыка | Метка в Gitea | Смысл |
 | --- | --- | --- |
 | `needs-triage` | `needs-triage` | Задачу должен оценить сопровождающий |
 | `needs-info` | `needs-info` | Нужна дополнительная информация от автора |
@@ -11,5 +12,5 @@
 | `ready-for-human` | `ready-for-human` | Задачу должен выполнить человек |
 | `wontfix` | `wontfix` | Задача не будет выполняться |

-Когда навык упоминает роль triage, нужно использовать соответствующее значение
+Когда навык упоминает роль triage, нужно использовать соответствующую метку
 из этой таблицы.