# Issue tracker: Gitea (via tea CLI)

Issues and specs for this repo live as Gitea issues on
`git.arthurerlich.de/haylan/mattpocock-skills-opencode`. Use the `tea` CLI for all operations;
the `gitea-tea` skill has command recipes. `tea` infers the repo from `git remote` inside this clone.

**One-time human step (not done yet):** `tea logins add` for `https://git.arthurerlich.de`
(token from the web UI: Settings → Applications). Until then, tracker operations fail.

## Conventions

- **Create an issue**: `tea issues create -t "<title>" --description-file -` (stdin for
  multi-line bodies). Labels: `-L needs-triage,bug` (comma-separated; must exist — see Labels).
- **Read an issue**: `tea issues <number> --comments`.
- **List issues**: `tea issues list --state open -f index,title,state,labels,assignees`
  (add `body,comments` to `--fields` when a skill needs full content).
- **Comment**: `tea comments <number> "<body>"`.
- **Apply / remove labels**: `tea issues edit <number> -L "<label>"` / `--remove-labels "<label>"`.
- **Assign**: `tea issues edit <number> -a <username>`.
- **Close**: comment the reason, then `tea issues close <number>`.

Gitea has **no sub-issues and no native blocked-by links**. Relations are body conventions:

- **Parent/child**: `Part of #<parent>` as the first line of the child body, plus a task list of
  children in the parent body.
- **Blocking**: `Blocked by: #<n>, #<n>` near the top of the child body. A ticket is unblocked
  when every listed blocker is closed.

### Labels

The five triage labels plus `wayfinder:map` and `wayfinder:research|prototype|grilling|task` must
exist before first use. After login, create missing ones with `tea labels create`; check with
`tea labels list`.

## Pull requests as a triage surface

**PRs as a request surface: no.** _(Set to `yes` if this repo treats external PRs as feature
requests; `triage` reads this flag.)_ Gitea shares one number space across issues and PRs: resolve
a bare `#42` with `tea issues 42`, falling back to `tea prs 42`.

## When a skill says "publish to the issue tracker"

Create a Gitea issue as above.

## When a skill says "fetch the relevant ticket"

Read it with `tea issues <number> --comments`.

## Wayfinding operations

Used by `wayfinder`. The **map** is a single issue with **child** issues as tickets.

- **Map**: issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body.
- **Child ticket**: `Part of #<map>` first body line, listed in the map's task list. Labels:
  `wayfinder:<type>` (`research`/`prototype`/`grilling`/`task`). Once claimed, assigned to the
  driving dev.
- **Blocking**: `Blocked by: #<n>` line (no native equivalent).
- **Frontier query**: list the map's open children (`tea issues list --state open`), drop any
  whose `Blocked by:` names an open issue or that has an assignee; first in map order wins.
- **Claim**: `tea issues edit <n> -a <username>`, the session's first write.
- **Resolve**: `tea comments <n> "<answer>"`, then `tea issues close <n>`, then append a context
  pointer to the map's Decisions-so-far (edit the map body).