# Issue tracker: Gitea

Issues and specs for this repo live as Gitea issues. Use the official [`tea`](https://gitea.com/gitea/tea) CLI for all operations.

## Conventions

- **Create an issue**: `tea issues create --title "..." --description "..."`.
- **Read an issue**: `tea issues <number>`.
- **List issues**: `tea issues`; use `tea issues --state all` for all states and `tea issues --output json` for machine-readable output.
- **Comment on an issue**: `tea comments add <number> "<body>"`.
- **Apply / remove labels**: `tea issues edit <number> --add-labels "..."` / `--remove-labels "..."`.
- **Close**: `tea issues close <number>`.
- **Pull requests**: use `tea pulls create`, `tea pulls <number>`, and `tea pulls checkout <number>`.

Configure the Gitea instance with `tea login add`. `tea` uses repository context from the current clone when available.

## Merge requests as a triage surface

**Pull requests as a request surface: no.**

## 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>`.

## Wayfinding operations

The current project is `xavierk/voidkontrol`, with configured tea login
`xavierk`. Pass `--login xavierk --repo xavierk/voidkontrol` when repository
context is unavailable. Use `tea api` for API operations not exposed by a
dedicated command; read the server's `/swagger.v1.json` for its current schema.

- **Map**: the issue labelled `wayfinder:map`. Start by reading its body.
- **Children**: Gitea 1.27.1 exposes issue dependencies but no parent/subissue
  endpoint in this server's schema. Give each child `wayfinder:child-of-<map
  index>` plus its `wayfinder:research`, `wayfinder:task`,
  `wayfinder:grilling`, or `wayfinder:prototype` label. Its body ends with a
  named `Parent map` link. This membership convention does not replace native
  blocking.
- **Claim**: assign the driving user before work:
  `tea issues edit --add-assignees xavierk <index>`. An open issue with an
  assignee is claimed. If work stops incomplete, leave an evidence/progress
  comment and release the claim with an API PATCH containing `{"assignees":[]}`.
- **Blocking**: POST `{"owner":"xavierk","repo":"voidkontrol","index":<blocker>}`
  to `repos/xavierk/voidkontrol/issues/<blocked>/dependencies` using `tea api`.
  Create all tickets before adding these relationships. Verify by GET on that
  endpoint; each returned issue blocks the issue in the URL.
- **Frontier**: list open issues with the map-membership label, paginate through
  all results, discard assigned issues, and GET each candidate's dependencies.
  A candidate is takeable when every dependency is closed. Order by issue
  creation/index ascending. Use names, with links, when presenting this result.
- **Resolution**: publish the answer as a comment, link any committed research
  or prototype asset, close the child, then append one named link and a short
  gist to the map's `Decisions so far`. Read the latest map before editing so
  concurrent additions survive. The full decision stays on the child.

Canonical starting map:
[Find the way to VoidKontrol v1: complete verified Swarm75 control on Void Linux](https://git.bongbetic.com/xavierk/voidkontrol/issues/1).