# Issue tracker: Gitea

Issues and specs for this repo live as issues on the self-hosted Gitea instance at https://tea.zendric.de, repo `Cedric/TagesByte`. Use the `tea` CLI for all operations.

`tea` infers the repo from the `origin` remote (`ssh://git@tea.zendric.de:2223/Cedric/TagesByte.git`). If inference fails, add `--repo Cedric/TagesByte`.

## Conventions

- **Create an issue**: `tea issues create --title "..." --description "..."`. For multi-line bodies, pipe a heredoc into `--description-file -`.
- **Read an issue**: `tea api repos/{owner}/{repo}/issues/<n>` for the issue as JSON, and `tea api repos/{owner}/{repo}/issues/<n>/comments` for its comments.
- **List issues**: `tea issues list --state open --fields index,title,body,labels -o json`, with `--labels "..."` / `--state` filters as needed.
- **Make an issue a child of a parent**: Gitea has no sub-issues. Put `Part of #<parent>` at the top of the child body, and add `- [ ] #<child>` to a task list in the parent body.
- **Comment on an issue**: `tea comment <n> "..."`
- **Apply / remove labels**: `tea issues edit <n> --add-labels "..."` / `--remove-labels "..."`
- **Close**: `tea comment <n> "..."`, then `tea issues close <n>`.

## 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.)_

When set to `yes`, PRs run through the same labels and states as issues, using `tea pulls` (`tea pulls list`, `tea pulls <n>`) and `tea api repos/{owner}/{repo}/pulls/<n>.diff` for the diff. Gitea shares one number space across issues and PRs.

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

Create a Gitea issue.

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

Read it as in **Read an issue** above.

## Wayfinding operations

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

- **Map**: a single issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. `tea issues create --labels wayfinder:map ...`.
- **Child ticket**: linked to the map as in **Make an issue a child of a parent**. Labels: `wayfinder:<type>` (`research`/`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev.
- **Blocking**: Gitea's native issue dependencies. Add an edge with `tea api -X POST repos/{owner}/{repo}/issues/<child>/dependencies -F index=<blocker> -f owner=Cedric -f repo=TagesByte`. List a ticket's blockers with `tea api repos/{owner}/{repo}/issues/<child>/dependencies`. A ticket is unblocked when every blocker is closed.
- **Frontier query**: list the map's open children (from its task list), drop any with an open blocker or an assignee; first in map order wins.
- **Claim**: `tea issues edit <n> --add-assignees Cedric`, the session's first write.
- **Resolve**: `tea comment <n> "<answer>"`, then `tea issues close <n>`, then append a context pointer (gist + link) to the map's Decisions-so-far.