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

2026-07-06T13:53:23-05:00

jcwalker3 commented

2026-07-06 13:53:23 -05:00

Closes #258

Summary

Documents the fail-closed hard-stop behavior for shell executor spawn failures (exit_code: -1 with empty stdout/stderr): probe once, mark shell unavailable, hard-stop after two consecutive spawn failures, and emit a recovery report (restart the session, kill hung background terminals, prefer MCP-native paths such as gitea_commit_files) instead of retry-spiralling. Explicitly forbids improvised fallbacks, cross-linking the #260 rule.

Changes

skills/llm-project-workflow/SKILL.md — portable "Shell Spawn Hard-Stop Rule" section
docs/llm-workflow-runbooks.md — Gitea runbook section with symptom, required behavior, recovery report contents
gitea_mcp_server.py — shell_spawn_hard_stop rule in the operator guide (mcp_get_control_plane_guide)
tests/test_shell_spawn_hard_stop_docs.py — 5 doc-contract tests (whitespace-normalized phrase checks)
tests/test_operator_guide.py — shell_spawn_hard_stop added to required guide keys

Validation

pytest tests/test_shell_spawn_hard_stop_docs.py tests/test_operator_guide.py -q — 29 passed
Full suite in issue worktree — 1012 passed, 0 failed
git diff --check — clean
Branch proofs: commit and push both from docs/issue-258-shell-spawn-hard-stop (matches issue lock; not a protected branch); validated at head cf292e4

Scope note

This is the documentation + doc-contract slice of #258. Runtime enforcement in agent harnesses (automatic spawn-failure counters) stays out of scope for this repository's docs; the operator guide rule is the enforcement surface MCP clients consume.

Closes #258 ## Summary Documents the fail-closed hard-stop behavior for shell executor spawn failures (`exit_code: -1` with empty stdout/stderr): probe once, mark shell unavailable, hard-stop after two consecutive spawn failures, and emit a recovery report (restart the session, kill hung background terminals, prefer MCP-native paths such as `gitea_commit_files`) instead of retry-spiralling. Explicitly forbids improvised fallbacks, cross-linking the #260 rule. ## Changes - `skills/llm-project-workflow/SKILL.md` — portable "Shell Spawn Hard-Stop Rule" section - `docs/llm-workflow-runbooks.md` — Gitea runbook section with symptom, required behavior, recovery report contents - `gitea_mcp_server.py` — `shell_spawn_hard_stop` rule in the operator guide (`mcp_get_control_plane_guide`) - `tests/test_shell_spawn_hard_stop_docs.py` — 5 doc-contract tests (whitespace-normalized phrase checks) - `tests/test_operator_guide.py` — `shell_spawn_hard_stop` added to required guide keys ## Validation - `pytest tests/test_shell_spawn_hard_stop_docs.py tests/test_operator_guide.py -q` — 29 passed - Full suite in issue worktree — 1012 passed, 0 failed - `git diff --check` — clean - Branch proofs: commit and push both from `docs/issue-258-shell-spawn-hard-stop` (matches issue lock; not a protected branch); validated at head `cf292e4` ## Scope note This is the documentation + doc-contract slice of #258. Runtime enforcement in agent harnesses (automatic spawn-failure counters) stays out of scope for this repository's docs; the operator guide rule is the enforcement surface MCP clients consume.

jcwalker3 added 1 commit 2026-07-06 13:53:24 -05:00

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

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

jcwalker3 referenced this pull request

2026-07-06 23:29:33 -05:00

feat: add fail-closed subagent delegation gates (Closes #266) #291

sysadmin added 1 commit 2026-07-07 01:00:08 -05:00

Merge branch 'master' into docs/issue-258-shell-spawn-hard-stop 3354da1973

sysadmin approved these changes 2026-07-07 01:18:34 -05:00

sysadmin left a comment

Review of PR 281: Documentation, runbook rules, and test cases for shell spawn hard-stop are correct. All tests pass successfully. Approved.

sysadmin merged commit 2a28fee7f2 into master

2026-07-07 01:18:51 -05:00

jcwalker3 referenced this pull request

2026-07-07 01:23:13 -05:00