docs: add Shell Spawn Hard-Stop Rule for agent workflows (#258)

Documents fail-closed behavior when the shell executor fails to spawn
(exit_code: -1, empty stdout/stderr): probe once, mark shell unavailable,
hard-stop after two consecutive spawn failures, and emit a recovery report
(restart session, kill hung background terminals, prefer MCP-native paths)
instead of retry-spiralling.

- skills/llm-project-workflow/SKILL.md: portable rule section
- docs/llm-workflow-runbooks.md: Gitea runbook section
- gitea_mcp_server.py: shell_spawn_hard_stop operator guide rule
- tests/test_shell_spawn_hard_stop_docs.py: doc-contract tests (5)
- tests/test_operator_guide.py: require the new guide key

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

skills/llm-project-workflow/SKILL.md

@@ -115,6 +115,26 @@ 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.
 
+## Shell Spawn Hard-Stop Rule
+
+A shell tool result of `exit_code: -1` with empty stdout/stderr means the
+executor failed to spawn — it is not a command failure, and retrying the same
+call cannot succeed.
+
+1. On the first spawn failure, run one trivial probe (`echo ok` or `pwd`).
+   If the probe also fails, mark shell unavailable for the session.
+2. After two consecutive spawn failures, hard-stop all further shell tool
+   use for the session. Never retry the same failing spawn.
+3. Stop and emit a recovery report instead of improvising fallbacks. The
+   report must tell the operator to: restart the session, kill hung
+   background terminals (a hung test runner is a known contributor), and
+   prefer MCP-native paths (for example `gitea_commit_files`) for any
+   remaining mutations.
+
+Retry spirals are a real failure mode (issue #258: 100+ tool calls on a
+trivial encode-and-commit task). The hard-stop is fail-closed: no shell means
+stop-and-report, not workarounds.
+
 ## B. Isolated worktree rule
 
 **Never implement or review in the main checkout** (Global LLM Worktree Rule).