sysadmin
a6a2243aad
Address review 443 on PR #616: mandatory operator-guide/runbook cross-links, LLM vs operator restart/relaunch split, and sanctioned post-merge parity staleness response (stop, report, operator reload, re-verify). Add docs tests enforcing F1–F3. Refs: #615
2.6 KiB
2.6 KiB
Operator Guide
Navigation
- Home | Operator Guide | Repositories Map | Identity and Profiles | Workflow Model | Safety and Gates | MCP Tools Reference | Operator Runbooks | Open Decisions | Project History
Handbook for LLM operators and human developers using the Gitea-Tools MCP server.
Key rules
- Verify identity first — Run
gitea_whoamiand confirm the active profile before any mutation. - Resolve task capability — Call
gitea_resolve_task_capabilityfor the intended task before gated tools. - One unit of work per session — Implement one claimed issue or review/merge one PR; do not mix author and reviewer mutations in one session.
- No self-review / no self-merge — The authenticated Gitea user must not approve or merge a PR they authored.
- Follow the gates — Prompts express intent; MCP tools enforce safety. Never bypass gates via prompt instructions.
- Global LLM Worktree Rule — Main checkout stays on
master/main/dev; all mutations happen underbranches/. Prove project root,cwd, branch, stable main-checkout branch, and session worktree path before editing. No exceptions. - Stable control runtime — Real Gitea mutations use only the stable MCP control runtime. LLM sessions must not kill, restart, or relaunch MCP processes, edit the stable checkout, or use a dev MCP for production mutations. See the policy ADR: mcp-stable-control-runtime-policy-adr.md (#615).
Supported Gitea instances
| Remote | Host | Default org/repo |
|---|---|---|
dadeschools |
gitea.dadeschools.net |
Contractor / Timesheet |
prgs |
gitea.prgs.cc |
Scaled-Tech-Consulting / Timesheet |
Always pass remote explicitly on tool calls. The server default is dadeschools; forgetting remote on a prgs task hits the wrong host.
New session checklist
gitea_whoami— confirm authenticated user and profile.gitea_get_runtime_context— allowed/forbidden operations for this session.gitea_resolve_task_capability— prove the session may perform the planned task.- For reviewer work: dry-run validation (
gitea_dry_run_pr_review) before live review mutations. - Confirm master parity / runtime health when tools report stale or unhealthy control runtime — stop mutations and request an operator reload of the stable MCP (see stable control runtime ADR).