Scaffold gitea-review-bot: thin matrix-nio PR-review bot (auto-map, threaded review, subagent panel, merge/reject/deploy)

AGENTS.md

@@ -0,0 +1,91 @@
+# gitea-review-bot: AGENTS.md
+
+gitea-review-bot is a **thin Matrix bot that runs an AI PR-review-and-merge workflow for your Gitea
+repos**, one review room per repo. It is a *separate* bot from `matrix-bridge` (which turns Matrix
+messages into interactive Claude Code sessions): this one's single responsibility is **reviewing
+pull requests** — so every room it's in is a review room and there is no manual "ignore this room"
+wiring. Invite it to a room, it auto-joins and maps the room to a repo by name, then for that repo
+it polls Gitea PRs, posts a headless `claude -p` review as a Matrix thread, and lets you merge/reject
+from the thread.
+
+> **Inbox check:** At session start, if `~/Projects/standards/INBOX.md` exists, scan it for items
+> tagged `(gitea-review-bot)` and surface them before proposing next steps; triage with `/triage`.
+
+## Stack
+
+Python + **matrix-nio**, one thin Docker container on the Spark (same shape as `matrix-bridge` and
+the `ten31-database` intake bot). No framework (Maubot rejected — see Decisions). The heavy work —
+the `claude -p` review and any deploy — runs **on the Mac over SSH**, reusing matrix-bridge's proven
+wrappers (`scripts/ask-claude.sh` for the review, `scripts/deploy-site.sh` for publish). State is
+flat JSON in a writable `state/` mount.
+
+## Placement
+
+| Dimension | Call |
+|---|---|
+| Host | **Spark**, plain Docker container (NOT Start9/s9pk) |
+| Runtime | Long-running service: matrix-nio sync + a Gitea poll loop over mapped repos |
+| Model routing | `claude -p` on the Mac via the Spark→Mac SSH seam (subscription); the review session spawns subagents (reviewer / adjudicator / security-auditor) |
+| Data layer | Flat JSON in `state/` (room→repo map + enabled agents + reviewed-PR heads + thread roots) |
+| Interface | Matrix — one review room per repo (+ phone) |
+| Repo home | Local + Gitea (`ssh://git@immense-voyage.local:59916/grant/gitea-review-bot.git`) |
+| Sensitivity | Sends PR diffs to `claude -p` (subscription). Fine for code review; flag the boundary before pointing it at a sensitive repo. |
+
+## Commands
+
+- **Run (container, on the Spark):** from `~/gitea-review-bot`, `docker compose up -d --build`
+  (host networking, `restart: unless-stopped`; read-only mounts of `.env`/`config.toml`/SSH key,
+  read-write `state/`). Logs: `docker compose logs -f`.
+- **Deploy:** the Spark's `~/gitea-review-bot` is a Gitea clone tracking `master`; deploy =
+  `git fetch && git reset --hard origin/master && docker compose up -d --build` (or a Spark Control
+  Update tile, once added — captured in the inbox). `config.toml` is gitignored — refresh it on the
+  Spark separately (scp) like matrix-bridge.
+- **Onboard a repo:** create a Matrix room named like the repo, invite this bot → it auto-joins,
+  maps the room to `<owner>/<roomname>` (+ `~/Projects/<roomname>` on the Mac), and posts an
+  onboarding message. Pick review agents in-chat: `agents +reviewer +security -adjudicator`.
+- **In a review room:** `merge` / `reject` (inside a PR's thread, or `merge <n>` by number), `yes`/`no`
+  to confirm a merge, `agents …` to toggle the subagent panel.
+
+## Layout
+
+- `src/bot.py` — the bot: matrix-nio sync; auto-join + in-room auto-map (room→repo by name); a Gitea
+  poll loop per mapped repo; threaded `claude -p` review (subagent panel); merge/reject/deploy
+  in-thread; whole-thread redaction on resolve (server-enumerated, restart-proof).
+- `config.example.toml` — homeserver, `[mac]` (ssh alias + the reused matrix-bridge wrapper paths),
+  `[gitea]` (api_base/owner/verify_tls), `[defaults]`, optional `[repo.<name>]` deploy overrides.
+- `.env.example` — `MATRIX_*` + `GITEA_TOKEN` (real `.env` gitignored).
+- `Dockerfile` · `docker-compose.yml` · `docker-entrypoint.sh` — the Spark container (generic image;
+  secrets/config via read-only mounts; entrypoint writes `~/.ssh/config` for the Mac alias).
+- `state/` — gitignored runtime JSON (`rooms.json`: room map + agents + heads + thread roots).
+
+## Decisions
+
+- **Separate bot from matrix-bridge** (single responsibility = PR review). Beat: extending
+  matrix-bridge with review-room special-casing. Reopens if the two bots' logic heavily overlaps.
+- **Thin matrix-nio container, NOT Maubot.** Reevaluated 2026-06-28: Maubot helps with the Matrix
+  plumbing we've already solved, not the SSH/`claude -p`/poll logic that's the actual weight, and it
+  reintroduces a web-UI/management layer (Spark Control is the dashboard). Reopens at ~6+ bots or a
+  non-developer web-management need; the lighter step first is a shared "bot kit" library.
+- **Subagent panel (Option B):** the lead `claude -p` session spawns subagents and presents each
+  output + its own overall recommendation. Beat: bot-orchestrated separate `claude -p` runs (more
+  deterministic but 3× the sessions + more bot code). Reopens if headless subagent spawning is flaky.
+- **Panel composition is per-room, set in chat** (onboarding message + `agents +/-`), not config.
+- **Reuse matrix-bridge's Mac wrappers + Spark→Mac SSH key** (don't duplicate the seam).
+- **Auto-map by name:** room `<x>` → Gitea `<owner>/<x>` + `~/Projects/<x>`; mapping persists to
+  `state/` (mirrors matrix-bridge D14). One room per repo.
+
+## Sovereignty
+
+Reviews send PR diffs to `claude -p` (the subscription), not a frontier API on payload data; that's
+acceptable for code review of these repos. Before pointing the bot at a repo with sensitive content,
+revisit this — local inference via Spark Control would be the path.
+
+## Current state
+
+**Scaffolded + initial bot built 2026-06-28.** First milestone: invite the bot to a room named
+`<repo>` → it auto-joins, maps to `grant/<repo>`, and within ~60s of a new PR posts a threaded
+`claude -p` review; `merge` + `yes` in that thread merges it on Gitea and redacts the thread. Core
+flow ported from matrix-bridge (D15–D19), generalized to multi-repo + the subagent panel.
+**Not yet run** — needs the bot's `.env` (Matrix creds + `GITEA_TOKEN`) + `config.toml` on the
+Spark, then `docker compose up -d --build`; then onboard the first repo and validate the panel +
+in-chat agent toggles. A Spark Control tile is captured in the cross-project inbox.