relayview-skills/docs/agents/issue-tracker.md

# Issue tracker: Gitea

Issues, specs, and pull requests for this repo live on its Gitea host. Use the
deterministic helpers from the `gitea-issues` skill for every operation — never
hand-write API calls. Resolve `<gitea-issues>` from the installed skill path.

## Conventions

- **Read an issue**: `python <gitea-issues>/scripts/gitea.py issue read --issue <number> --comments`
- **Rename an issue**: `issue update-title --issue <number> --title "New title"` (optionally `--expected-title "Old title"` or `--expected-content-version <version>`)
- **List issues**: `python <gitea-issues>/scripts/gitea.py issue list --state open` (add `--label` / `--exclude-label` filters, `--output json` for structure)
- **Create an issue**: `issue create --title "..." --body-file - --label status/ready-for-agent` with the body on standard input, using the `## Problem` / `## Scope` / `## Acceptance Criteria` structure
- **Comment**: `issue comment --issue <number> --body "..."`
- **Change status**: `issue set-status --issue <number> --status status/<role>`
- **Edit classification**: `issue edit-labels --issue <number> --add <label> --remove <label>` (repeat either flag; omit either when unused)
- **Start implementation**: `issue start --issue <number>` — creates the `ISSUE-<number>` branch in a dedicated worktree and prints the path every later command must use
- **Close reviewed work**: `pr cleanup` merges the reviewed pull request and reconciles the issue; `issue close --status status/done` closes an explicitly authorized resolved decision, and `--status status/wontfix` closes declined non-implementation work with a short marker-backed explanation
- **Clean up a merged worktree**: `issue remove-worktree --issue <number> --pull <number>` — fast-forwards local `main` to the fetched remote tip (stopping with resolution commands before any deletion when it cannot) and removes the worktree and its branch

Repository identity comes from the `origin` remote or the resolved credentials;
the helpers never need a token pasted into chat.

`issue update-title` sends a title-only edit with Gitea's preflight
`content_version` check and verifies a fresh readback. Gitea does not provide
an atomic title compare-and-swap, so a concurrent edit can still race. The
command directs a check of the actual owning roadmap or epic entry and reports
child `Parent:` lines that need separate guarded repair. Its own `Parent:` line
is only a hint; preserve entry order and checkboxes.

Read-only commands (`issue list`, `queue roadmap|inspect|next`, `epic
next-ready`/`start-next` selection) reuse unchanged reads through a
conditional cache that never touches mutation preflights or read-after-write
verification. Disable it with `GITEA_READ_CACHE=off`, inspect it with
`read-cache status`, and clear it with `read-cache clear`; see the skill's
`references/read-cache.md` for the freshness contract.

## Label vocabulary

Status labels are the agent-writeable source of truth. When a status Project is
configured in `docs/agents/issue-board.toml`, successful lifecycle commands
request card reconciliation through `issue-project-board`. The board displays
status and prerequisites; the roadmap remains the priority source:

`status/needs-triage`, `status/needs-info`, `status/ready-for-agent`,
`status/ready-for-human`, `status/in-progress`, `status/review`,
`status/done`, `status/wontfix`, plus `priority/P0` as an exceptional interrupt
indicator. Type labels (`type/epic`, `type/feature`, `type/bug`, …) and area
labels classify work. Install missing names idempotently with
`labels setup --dry-run` then `labels setup`; existing labels are preserved.
`board/archived` is a non-status label for a closed `status/done` or
`status/wontfix` issue kept searchable outside the status board. Initial board
migration and later selected archival require reviewed previews in
`issue-project-board`; ordinary closure still adds a Done or Won't Fix card.
`board/finalizing` marks an in-progress epic whose listed children are closed
`status/done` while final gates are checked. Other in-progress epics appear in
Active Epics; individual work stays in In Progress. Existing eight-column
boards use the reviewed `issue-project-board` migration.
See `docs/agents/triage-labels.md` for the triage-role mapping and
`docs/agents/queue.md` for the roadmap contract.

`issue edit-labels` changes only named existing non-status labels, preserving
unrelated labels. It validates every requested name before writing, adds before
removing, and verifies the requested result with a fresh read. A satisfied
replay writes nothing. Use `issue set-status` for `status/*` transitions.
Writes are incremental: after a write or verification failure, reconcile with
`issue read` before retrying. Changing `type/epic` does not create child order,
blocking edges, or roadmap placement; use their separate helper operations.

## The repository work queue

Exactly one open issue labelled `type/roadmap` holds the
`## Work Queue In Priority Order` section that defines repository priority;
epics order children the same way. Each list entry uses `- [ ] #123 Title` or
`- [x] #123 Title`; checkboxes display closed `status/done` progress and do
not change workflow state. `queue inspect` reports disagreements. Convert
numbered lists only through reviewed `checklist preview` and guarded
`checklist apply`. Dependencies gate execution; they never define priority.

- **Inspect**: `queue inspect` (health, skipped entries, tree-invariant violations, selected leaf)
- **Read placement state**: `queue roadmap` (top-level order and content version)
- **Select read-only**: `queue next`
- **Maintain**: `queue init` (idempotent), `queue insert --issue <n> --position <p> --expected-content-version <v>`, `queue reorder`, `queue link-children preview` / `apply --confirm` (direct-child blocking edges)
- **Move to `independent` mode**: the reviewed edge migration — `migration preview --history --write-plan <file>`, `migration freeze`, `migration apply --plan <file>`, `migration readiness`, then a reviewed configuration commit (see the gitea-issues `references/repository-queue.md`)

Only top-level delivery epics and explicitly standalone issues
(`--allow-standalone`) enter the roadmap. When the user has not stated a
priority, new work enters at the default position from the gitea-issues
queue-placement contract — the highest its dependencies allow — and an
explicit statement always wins. The queue tree carries one
invariant — every open issue except the roadmap itself sits on exactly one
priority list and blocks that parent — specified in full in the gitea-issues
`references/repository-queue.md` reference. Inserting an open entry — epic or
standalone — links it as blocking the roadmap, so the Gitea UI **Blocks**
section links each level to the root; the roadmap never takes dependency
edges beyond its direct children (its queue entries). `queue link-children`
repairs missing direct-child edges.

## 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`, external PRs run through the same status labels as issues:
read them with `issue read --issue <number> --comments`, label with
`issue set-status`, and triage contributor PRs (not owner/maintainer work)
through `/triage`.

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

Create a Gitea issue with `issue create`, then place it explicitly: group
implementation work under a delivery epic (children linked with
`epic add-dependency --parent <epic> --child <child>`, the legacy alias of
`prerequisite add --issue <epic> --requires <child>`, and ordered in the epic's
`## Child Issues In Priority Order` section) and insert only the epic — or an
explicitly standalone issue — into the roadmap with `queue insert`. Creation
and placement stay two separate, reconcilable operations; when the user gave
no priority, apply the default-placement rule from that contract and say so
with the proposal, and publish unqueued only when placement is genuinely
unresolved.

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

Run `issue read --issue <number> --comments`.

## Wayfinding operations

Used by `/wayfinder`. The **map** is a single issue labelled `wayfinder:map`;
its **child tickets** are plain issues that block the map.

- **Map**: `issue create --title "..." --label wayfinder:map` holding the Notes / Decisions-so-far / Fog body.
- **Child ticket**: an issue labelled `wayfinder:<type>` (`research`/`prototype`/`grilling`/`task`) with `Part of #<map>` at the top of its body, linked to the map with `prerequisite add --issue <map> --requires <n>` (the map waits for each ticket).
- **Blocking**: Gitea dependency links — the map is blocked by every child. `issue read` reports open blockers, which are the live gate.
- **Frontier query**: `issue list --state open --label wayfinder:map`-scoped children (list open issues, keep those mentioning `Part of #<map>`), drop any with an open blocker or `status/in-progress`; first in map order wins.
- **Claim**: move the ticket to `status/in-progress` with `issue set-status`.
- **Resolve**: `issue comment --issue <n> --body "<answer>"`, then use `issue close --issue <n> --status status/done --comment "Decision accepted; see the resolution comment."` for an explicitly authorized accepted decision; use `status/wontfix` for declined work and `pr cleanup` for PR-backed implementation. Gist the decision into the map's Decisions-so-far.