docs: add subagent tool-budget guardrails for MCP tasks (Closes #259)

Document default tool-call and wall-time budgets for deterministic MCP
work, forbid subagent commit delegation when gitea_commit_files is
available, and pin the rules in runbooks, portable skill, operator guide,
and doc-contract tests.

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

skills/llm-project-workflow/SKILL.md

@@ -115,6 +115,31 @@ The main checkout may only be used for read-only inspection, fetching,
 stable-branch update after merged PRs, creating `branches/` worktrees, or
 explicit control-checkout repair.
 
+## Subagent Tool-Budget Guardrails
+
+General-purpose subagents on **single-step MCP tasks** (for example
+`gitea_commit_files`) must not expand into 100+ tool-call retry spirals with
+WebFetch/Playwright/manual-encoding fallbacks (issue #259).
+
+Default budgets (stop when exceeded):
+
+- **Single-step MCP mutation** (`commit_files`, `create_pr`, `lock_issue`):
+  15 tool calls, 5 minutes wall time.
+- **Review / merge queue inspection**: 40 tool calls, 15 minutes.
+- **Non-mutating exploration**: 60 tool calls, 20 minutes.
+
+Rules:
+
+1. When the main session has `gitea.repo.commit`, call `gitea_commit_files`
+   directly — do not delegate commit to a subagent (#260).
+2. After shell spawn failure (#258), attempt the native MCP tool once before
+   any fallback; shell unavailability never authorizes WebFetch/Playwright/
+   manual base64.
+3. Never resume a failed subagent into a larger retry loop or spawn a second
+   subagent for the same deterministic step — stop and report.
+4. When `gitea_commit_files` is available, forbid WebFetch, Playwright,
+   manual encoding, and ad-hoc `_encode_*` / `_emit_*` helpers in the repo.
+
 ## B. Isolated worktree rule
 
 **Never implement or review in the main checkout** (Global LLM Worktree Rule).