# Issue tracker: Forgejo

Issues and PRDs for this repository live as Forgejo issues in
`git.s1q.dev/phg/hosts`. Use `fgj` for all operations.

Every repository-scoped command must use the hostname `git.s1q.dev` and
repository `phg/hosts`.

## Conventions

- **Create an issue**:
  `fgj --hostname git.s1q.dev issue create -R phg/hosts --title "..." --body "..."`
- **Read an issue**:
  `fgj --hostname git.s1q.dev issue view <number> -R phg/hosts`
- **Read an issue as JSON**:
  `fgj --hostname git.s1q.dev issue view <number> -R phg/hosts --json`
- **List issues**:
  `fgj --hostname git.s1q.dev issue list -R phg/hosts --state open --json`
- **Comment on an issue**:
  `fgj --hostname git.s1q.dev issue comment <number> -R phg/hosts --body "..."`
- **Apply or remove labels**:
  `fgj --hostname git.s1q.dev issue edit <number> -R phg/hosts --add-label "..."`
  or `--remove-label "..."`
- **Close an issue**:
  `fgj --hostname git.s1q.dev issue close <number> -R phg/hosts --comment "..."`
- **List repository labels**:
  `fgj --hostname git.s1q.dev label list -R phg/hosts --json`

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

Create a Forgejo issue with `fgj issue create`.

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

Run `fgj issue view <number>` with the configured hostname and repository.

## Wayfinding operations

The map is a Forgejo issue with one child issue per ticket.

- **Map**: an issue labelled `wayfinder:map` containing Notes,
  Decisions-so-far, and Fog sections.
- **Child ticket**: an issue whose body starts with `Part of #<map>` and whose
  type is recorded with a `wayfinder:<type>` label (`research`, `prototype`,
  `grilling`, or `task`).
- **Blocking**: put `Blocked by: #<number>, #<number>` at the top of the child
  issue body. A ticket is unblocked when every listed issue is closed.
- **Frontier**: inspect the map's open child issues and choose the first issue
  that has no open blocker and has not been claimed.
- **Claim**: apply the `wayfinder:claimed` label before beginning work.
- **Resolve**: comment with the answer, close the child issue, then append a
  context pointer to the map's Decisions-so-far section.