# Issue workflow

## Source of truth

Gitea Issues are the source of truth for tasks, discussions, labels, milestones, and status.

Do not copy the full backlog into git.

Repository documents may define:

- issue templates
- triage rules
- Codex task format
- verification rules
- release checklist

## Labels

Recommended labels:

- `P0`
- `P1`
- `P2`
- `P3`
- `security`
- `data-integrity`
- `backend`
- `frontend`
- `wiki`
- `tags`
- `materials`
- `theatre`
- `codex-ready`
- `needs-design`
- `blocked`
- `good-first-codex-task`

## Codex-ready criteria

An issue can be labeled `codex-ready` only when it has:

- clear background
- target area
- concrete tasks
- acceptance criteria
- verification commands
- explicit non-goals
- no unresolved architecture decision

## Workflow

1. Create or refine the issue in Gitea.
2. Add labels and milestone.
3. If design is unclear, label `needs-design`.
4. Discuss design before implementation.
5. When scoped enough, label `codex-ready`.
6. Give Codex the issue URL or copied issue body.
7. Codex creates a branch.
8. Codex implements a small patch.
9. Codex runs verification commands.
10. Human reviews the diff.
11. Merge.
12. Close the issue from the PR/commit message.

## Commit message

Use issue references when possible:

```txt
fix: prevent preview SSRF

Refs: #123
```
or
```
fix: prevent preview SSRF

Closes: #123
```
depending on whether the change fully resolves the issue.