merge: resolve master conflicts for #259 subagent tool-budget docs

Integrate split-workflow router SKILL.md (#333) with subagent tool-budget
guardrails (#259). Keep shell spawn hard-stop (#258) and subagent
delegation (#266) operator-guide rules alongside subagent_tool_budget.

docs/llm-workflow-runbooks.md

@@ -285,6 +285,33 @@ explicit control-checkout repair.
 
 Portable wording: [`skills/llm-project-workflow/SKILL.md`](../skills/llm-project-workflow/SKILL.md).
 
+## Shell Spawn Hard-Stop Rule
+
+Symptom: a shell tool call returns `exit_code: -1` with empty stdout/stderr.
+That is an executor spawn failure, not a command failure — the command never
+ran, and retrying the identical call cannot succeed.
+
+Required behavior (fail closed, issue #258):
+
+1. **Probe once.** On the first spawn failure, run one trivial probe
+   (`echo ok` or `pwd`). If the probe also returns `exit_code: -1`, mark
+   shell unavailable for the session.
+2. **Hard-stop at two.** After two consecutive spawn failures, stop all
+   further shell tool use for the session; never retry the same failing
+   spawn. A hundred retries produce a hundred identical failures (session
+   `019f382e`: 100+ tool calls stalled on a trivial encode-and-commit task).
+3. **Emit a recovery report.** The report must direct the operator to:
+   - restart the session,
+   - kill hung background terminals (a hung test runner holding the
+     executor is a known contributor),
+   - prefer MCP-native paths for remaining mutations (for example
+     `gitea_commit_files` under `gitea.repo.commit`) instead of shell.
+4. **No improvised fallbacks.** Shell unavailability never authorizes
+   WebFetch/browser/manual-encoding workarounds (see #260). No shell means
+   stop-and-report.
+
+Doc-contract tests: `tests/test_shell_spawn_hard_stop_docs.py`.
+
 ## Subagent Tool-Budget Guardrails
 
 General-purpose subagents tasked with **deterministic MCP work** (for example a
@@ -349,6 +376,30 @@ may edit another issue's branch folder unless explicitly assigned to that issue.
 No LLM may clean another issue's branch folder unless the PR is merged or closed
 and cleanup is explicitly part of the task.
 
+## Agent temp artifact cleanup (#261)
+
+Failed or aborted MCP commit attempts sometimes leave throwaway helper scripts in
+the **repository root**. These are not part of any issue scope and pollute
+`git status`, which can break `gitea_lock_issue` and preflight checks.
+
+**Patterns (repo root only, untracked):**
+
+- `_encode_*.py` — base64 payload encoders
+- `_emit_*.py` — commit payload emitters
+- `_inline_*.py` — inline encoding helpers
+
+**Required cleanup (after MCP commit completes or aborts):**
+
+1. Delete any matching files at the repo root (`rm ./_encode_*.py` etc.).
+2. Confirm `git status` is clean on the orchestration checkout before
+   `gitea_lock_issue`.
+3. Prefer native `gitea_commit_files` / gated commit paths — do not leave shell
+   encoding fallbacks behind.
+
+Root-level matches are listed in `.gitignore` so they never get committed.
+`gitea_get_runtime_context` and `gitea_lock_issue` surface **warnings** (not
+hard blocks) when these artifacts are still present.
+
 Implementation work and review work must use separate branch folders. For
 example, an implementation branch might live under
 `branches/fix-issue-123-example`, while a review branch for the resulting PR
@@ -403,6 +454,36 @@ git branch -d fix/issue-123-example
 All three helpers accept `--dry-run` to print the exact commands/paths without
 touching anything.
 
+### MCP-native commit path (#260)
+
+When the active author profile allows **`gitea.repo.commit`** and
+**`gitea_commit_files`** is visible in the client, that is the **only** approved
+path for committing files to the tracked repository. Do not improvise alternate
+encoding or transport when MCP commit is available.
+
+**Required before commit:**
+
+1. Call `gitea_resolve_task_capability` for `commit_files` or
+   `gitea_commit_files` and confirm `allowed_in_current_session` is true.
+2. Use `gitea_commit_files` with file payloads prepared in the author worktree.
+3. Stage only issue-scoped paths; never commit throwaway `_encode_*` /
+   `_emit_*` / `_inline_*` helpers.
+
+**Explicitly forbidden workarounds** when MCP commit is reachable:
+
+- `WebFetch` / HTTP calls to external decode sites (for example httpbin base64
+  endpoints)
+- Playwright or other browser automation to bypass MCP
+- Manual LLM-generated base64 pasted into ad-hoc scripts
+- Delegating commit authority to a subagent while the main session has
+  `gitea.repo.commit` on an author profile
+
+**If shell encoding is unavailable** (spawn failure, hung terminal) **and** MCP
+commit cannot run: **stop** with a recovery report. Mention restarting the
+session, clearing hung background terminals, switching to MCP-native commit, and
+the agent temp artifact cleanup checklist. Do **not** retry shell encoding in a
+loop and do **not** substitute WebFetch/Playwright/manual base64.
+
 ### Create an issue / child issues
 
 - **Profile:** issue-manager or author (any profile allowed to create issues).

docs/safety-model.md

@@ -28,3 +28,21 @@ Any mutating action (e.g., Gitea issue creation from GlitchTip, or Jenkins build
   No default profile carries trigger capability (#152 / mcp-control-plane #56).
 - **GlitchTip to Gitea issue filing** is a library-only orchestrator in
   mcp-control-plane (not on `glitchtip-mcp`). See #153 / mcp-control-plane #57.
+
+## 6. Agent Commit Path (no improvised fallbacks)
+
+When an author execution profile allows **`gitea.repo.commit`** and the
+**`gitea_commit_files`** tool is visible, agents must use that MCP path for
+repository commits. Fail closed instead of improvising alternate transports.
+
+Forbidden when MCP commit is available:
+
+- WebFetch or other HTTP calls to external base64/decode services
+- Playwright or browser automation used to work around MCP commit
+- Manual LLM-generated base64 embedded in throwaway scripts as the primary
+  commit transport
+
+If shell helpers are unavailable and MCP commit cannot run, stop with a recovery
+report (restart session, clear hung terminals, use MCP-native commit). See
+[`llm-workflow-runbooks.md`](llm-workflow-runbooks.md) § MCP-native commit path
+(#260) and agent temp artifact cleanup (#261).