chore: contributor workflow — templates, git-cliff, gitea-workflow doc (closes #31) (#38)

docs/gitea-workflow.md

@@ -0,0 +1,52 @@
+# Working with Gitea: issues, milestones, PRs
+
+Gitea is the **system of record** (CLAUDE.md §7). `BACKLOG.md` is a human-readable
+mirror of the active milestone — when they disagree, Gitea wins.
+
+## Issues
+
+- Open issues from the templates in `.gitea/ISSUE_TEMPLATE/`:
+  - **Slice** — a backlog user story (`S-NN · …`), encodes the Definition of Done.
+  - **Bug** — a defect.
+  - **ADR proposal** — a decision to record before coding (CLAUDE.md §14).
+- Every issue gets `type:*` plus the relevant `area:*` label(s), and is assigned to
+  its iteration **milestone** (`Iteration N — …`).
+- Splitting a slice that grew too big: see CLAUDE.md §13 and the "How to split a
+  slice" section of `BACKLOG.md`.
+
+## Branches & commits
+
+- Trunk-based: short-lived branches off `main`, squash-merged. Never push to `main`.
+- Branch name: `<type>/<issue-number>-<slug>`, e.g. `feat/28-bff-health`.
+- Conventional Commits, each referencing its issue: `feat(bff): … (refs #28)`.
+- TDD order: the `test(...)` red commit precedes the `feat(...)` green commit.
+
+## Pull requests
+
+- Open with `tea pr create` (the Gitea CLI) or the web UI; the body uses
+  `.gitea/PULL_REQUEST_TEMPLATE.md` and its DoD checklist.
+- The merging PR closes its issue via `closes #NN` in the squash-commit body.
+  Work that isn't finished (e.g. CI green pending a runner) uses `refs #NN` and the
+  issue stays open.
+- A PR needs a linked issue. Don't open one without it.
+
+## CI gate
+
+Until a self-hosted `respellion-linux` runner is registered, `make ci` is the gate
+(it runs the same checks the workflow does). See [runbooks/ci.md](runbooks/ci.md).
+
+## CLI cheatsheet (`tea`)
+
+```bash
+tea issues list --state open          # backlog
+tea issue create --title "S-NN · …" --labels type:slice,area:bff --milestone "Iteration 1 — Walking Skeleton"
+tea pr create --base main --head <branch> --title "…" --description "… closes #NN"
+tea pr list                           # open PRs
+tea pr merge <n> --style squash       # merge (after review)
+```
+
+## Changelog & releases
+
+`CHANGELOG.md` is generated from commits by `git-cliff` (`make changelog`), refreshed
+on tag. Versioning is **CalVer** `YYYY.MM.PATCH`; releases are published via Gitea
+Releases.