docs: file issues in the repo that owns the code, not a central tracker

The umbrella tracker cannot auto-close on merge, so completed work
accumulated as an open backlog (234 open, much of it already shipped).
Issues now live in the repo whose code must change; spikersoft-issues
keeps cross-repo epics only.

README.md

@@ -1107,15 +1107,44 @@ dotnet test                        # All tests
 dotnet test --filter "Category=Unit"  # Unit tests only
 ```
 
-### QA: Gitea issues and the AI agent (MCP)
+### Where issues live
 
-Product and engineering tickets for SpikerSoft are tracked in Gitea, including cross-cutting and roadmap items in the dedicated issues repo: **[`spikerj/spikersoft-issues`](https://git.spikersoft.com/spikerj/spikersoft-issues)** (e.g. future work that mirrors the [TODO / Future work](#todo--future-work) section).
+**File every ticket in the repo whose code has to change.** Not in a central tracker.
+
+| Kind of work | Where it goes |
+| --- | --- |
+| .NET services, API, GameServer, CQRS, EF/Mongo | `spikersoft-backend` |
+| Angular app, browser games, playgrounds, libs | `spikersoft-angular` |
+| Swarm stacks, Traefik, MinIO, Keycloak, OpenBao, registry, networking | `spikersoft-infrastructure` |
+| Python art pipeline, model backends, its Dockerfiles | `spikersoft-artpipe` |
+| Native mobile apps | `spikersoft-ios` / `spikersoft-android` |
+| Godot client | `spikersoft-games-godot` |
+| **Cross-repo epics only** | `spikersoft-issues` |
+
+The reason is mechanical: Gitea auto-closes an issue when a merged PR says `fixes #N`
+**only within the same repo**. A ticket filed in a central tracker can never close itself,
+so completed work silently accumulates as an open backlog. That is exactly what happened —
+the umbrella tracker reached 234 open issues, a large share of which were already shipped.
+
+Rules that follow from this:
+
+- A ticket must be **closeable by merging in one repo**. If it isn't, it's really several
+  tickets.
+- Work spanning repos becomes **one narrowly-scoped issue per repo**, cross-linked to its
+  siblings by full reference (`spikerj/spikersoft-backend#12`) and pointing at its epic.
+- **Epics live in [`spikerj/spikersoft-issues`](https://git.spikersoft.com/spikerj/spikersoft-issues)**
+  and hold no implementation work of their own — only a checklist of per-repo children.
+  They are the one thing that legitimately closes by hand.
+- Reference issues across repos with the **full `owner/repo#N` form**. A bare `#N` resolves
+  against the repo you're writing in, which silently points at an unrelated ticket.
+
+### QA: Gitea issues and the AI agent (MCP)
 
 **Using the Gitea MCP in Cursor** so QA (and devs) can work tickets through the AI agent without leaving the IDE:
 
 1. **Enable the integration** — In **Cursor Settings → MCP**, ensure the **Gitea** server is on and configured (Instance URL, access token, and path to the `gitea-mcp` command if you use the standalone binary). The token must have API scope to read and create issues in the org/repos you use.
 2. **Confirm the session** — The Gitea tools appear in the project only when the MCP is connected. If a chat reports that the Gitea server is missing, re-open MCP settings and toggle or reconnect, then start a new agent message.
-3. **What to ask the agent** — Natural-language requests map to the MCP, for example: *“List open issues in `spikerj/spikersoft-issues`”*, *“Create an issue for …”*, *“Add a comment on issue #5 summarizing the repro”*, *“Show details for issue #2”*, or *“Search repos named …”* (the exact tool surface depends on your `gitea-mcp` build; list/search/create/edit issues and comments are the usual workflows).
+3. **What to ask the agent** — Natural-language requests map to the MCP, for example: *“List open issues in `spikerj/spikersoft-backend`”*, *“Create an issue in the repo that owns this file for …”*, *“Add a comment on `spikerj/spikersoft-angular#12` summarizing the repro”*, or *“Search repos named …”* (the exact tool surface depends on your `gitea-mcp` build; list/search/create/edit issues and comments are the usual workflows). Per [Where issues live](#where-issues-live), name the target repo explicitly — the agent should not default to a central tracker.
 4. **Good practices** — Prefer filing reproduction steps, build or environment, and expected vs actual behavior in the issue body so the agent can quote them back accurately. For sensitive data, do not paste secrets into issues; use references to internal logs or redacted snippets.
 
 This complements manual use of the Gitea web UI: the same [https://git.spikersoft.com](https://git.spikersoft.com) data, with faster handoff from chat, terminal output, and code context while triaging or closing the loop on QA.