# Issue tracker: Forgejo

Issues and PRDs for this repository live as Forgejo issues at
`git.s1q.dev/phg/fuse-mail-dir-by-tag`.

Use this base command for all operations:

`fgj --hostname git.s1q.dev issue <command> -R phg/fuse-mail-dir-by-tag`

## Conventions

- **Create an issue**:
  `fgj --hostname git.s1q.dev issue create -R phg/fuse-mail-dir-by-tag --title "..." --body "..."`
- **Read an issue**:
  `fgj --hostname git.s1q.dev issue view <number> -R phg/fuse-mail-dir-by-tag`
- **Read an issue as JSON**:
  `fgj --hostname git.s1q.dev issue view <number> -R phg/fuse-mail-dir-by-tag --json`
- **List issues**:
  `fgj --hostname git.s1q.dev issue list -R phg/fuse-mail-dir-by-tag --state open`
- **List issues as JSON**:
  `fgj --hostname git.s1q.dev issue list -R phg/fuse-mail-dir-by-tag --state open --json`
- **Comment on an issue**:
  `fgj --hostname git.s1q.dev issue comment <number> -R phg/fuse-mail-dir-by-tag --body "..."`
- **Apply a label**:
  `fgj --hostname git.s1q.dev issue edit <number> -R phg/fuse-mail-dir-by-tag --add-label "..."`
- **Remove a label**:
  `fgj --hostname git.s1q.dev issue edit <number> -R phg/fuse-mail-dir-by-tag --remove-label "..."`
- **Close an issue with a comment**:
  `fgj --hostname git.s1q.dev issue close <number> -R phg/fuse-mail-dir-by-tag --comment "..."`

Pull requests are not part of the triage request surface.

## When a skill says “publish to the issue tracker”

Create a Forgejo issue with `fgj issue create` using the hostname and repository arguments above.

## When a skill says “fetch the relevant ticket”

Read it with `fgj issue view <number>` using the hostname and repository arguments above.

## Wayfinding operations

The **map** is a single Forgejo issue with child issues represented by links in its body.

- **Map**: an issue labelled `wayfinder:map`, containing the Notes, Decisions-so-far, and Fog sections.
- **Child ticket**: an issue with `Part of #<map>` at the top of its body and a `wayfinder:<type>` label, where the type is `research`, `prototype`, `grilling`, or `task`.
- **Blocking**: record `Blocked by: #<number>, #<number>` at the top of the child issue body. A ticket is unblocked when every referenced blocker is closed.
- **Frontier**: inspect the map’s open child issues, discard blocked or already claimed tickets, and take the first remaining ticket in map order.
- **Claim**: record the acting developer or agent in a comment before starting work.
- **Resolve**: comment with the answer, close the child issue, and append a pointer to the result under the map’s Decisions-so-far section.