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]>

gitea_mcp_server.py

@@ -3483,6 +3483,16 @@ _GUIDE_RULES = {
         "small fixes, review fixes, conflicts, emergencies). Main checkout: "
         "read-only inspect, fetch, create worktrees, post-merge stable "
         "update, explicit repair only."),
+    "shell_spawn_hard_stop": (
+        "A shell result of exit_code: -1 with empty stdout/stderr is an "
+        "executor spawn failure, not a command failure. Probe once (echo/pwd); "
+        "if the probe fails, mark shell unavailable for the session. After "
+        "two consecutive spawn failures, hard-stop all shell use — never "
+        "retry the same failing spawn — and emit a recovery report: restart "
+        "the session, kill hung background terminals, prefer MCP-native "
+        "paths (e.g. gitea_commit_files) for remaining mutations. Shell "
+        "unavailability never authorizes WebFetch/browser/manual-encoding "
+        "fallbacks (#258)."),
 }
 
 _COMMON_WORKFLOWS = [