# Issue tracker: Gitea

Issues and specs for this repo live in Gitea Issues. Use the `tea` CLI from this clone. Authenticate to `https://git.bongbetic.com` with `tea login add` before using it.

## Conventions

- Create: `tea issues create --title "..." --description "..."`
- Read an issue and its comments: `tea issues <number> --comments`
- List open issues: `tea issues --state open`
- List all issues: `tea issues --state all`
- Get machine-readable output: `tea issues --output json`
- List comments: `tea comments list <number>`
- Add a comment: `tea comments add <number> "..."`
- Add/remove labels: `tea issues edit <number> --add-labels "..."` / `--remove-labels "..."`
- Assign: `tea issues edit <number> --add-assignees "<username>"`
- Close: `tea issues close <number>`

Use `--remote origin` if `tea` needs to select the Gitea login associated with this repo's remote.

## Pull requests as a triage surface

**PRs as a request surface: no.** Triage applies to Gitea issues only.

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

Create a Gitea issue.

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

Run `tea issues <number> --comments`.

## Wayfinding operations

The **map** is a Gitea issue with the Notes / Decisions-so-far / Fog sections.

- **Map**: create one issue labelled `wayfinder:map`.
- **Child ticket**: create one issue per ticket, with `Part of [<map title>](<map URL>)` at the top of its description, an HTML comment `<!-- wayfinder-map: <map number> -->` for exact membership filtering, and a `wayfinder:<type>` label (`research`/`prototype`/`grilling`/`task`). Refer to maps and tickets by linked titles in human-facing text.
- **Blocking**: use Gitea's native issue dependencies, enabled on this repository. Add a blocker with `tea api --remote origin --method POST -f owner=xavierk -f repo=odin -F index=<blocker number> repos/xavierk/odin/issues/<ticket number>/dependencies`. Inspect blockers with a GET to the same endpoint. A ticket is unblocked when every blocker is closed. Fall back to a body convention only on an instance where native dependencies are unavailable.
- **Frontier**: list open issues through `tea api`, paginating until exhausted, and filter by the map's membership marker. Skip any with an open native dependency or an assignee; first by issue creation order wins. Never claim an assigned issue.
- **Claim**: assign yourself to the issue with `tea issues edit <number> --add-assignees "<username>"`. This is the session's first tracker write.
- **Resolve**: add the answer with `tea comments add <number> "..."`, close the issue, then add a context pointer to the map's Decisions-so-far.

For multiline issue bodies and comments, send JSON through `tea api --data @<file>` or `--data @-`; preserve literal text and newlines. For map edits, read the latest issue and PATCH its body with the returned `content_version`. On HTTP 409, reread and merge so another session's updates are preserved.