docs: add agent temp-artifact cleanup runbook and ignore patterns (closes #261)

Failed subagent runs left throwaway helpers (_encode_commit_payload.py,
_emit_payload.py) in the shared working tree, polluting git status and
tripping gitea_lock_issue / pre-flight purity gates.

Add an 'Agent temp artifact cleanup' runbook section requiring deletion
of _encode_*/_emit_*/_inline_* helpers when the MCP commit completes or
aborts, prefer scratchpad payload preparation, and document the cleanup
checklist. Back it with .gitignore patterns so strays cannot block
issue locks for later sessions, and pin both with doc-contract tests
(including a repo-root scan asserting the artifacts stay removed).

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
This commit is contained in:
2026-07-06 14:46:08 -04:00
co-authored by Claude Opus 4.8
parent d6f4f936e3
commit a55e93763b
3 changed files with 108 additions and 0 deletions
+27
View File
@@ -459,6 +459,33 @@ touching anything.
files, detected secret, or any production/deploy behavior — **stop, report the
blocker, and take no mutating action.** Fail closed; never work around a gate.
## Agent temp artifact cleanup (#261)
Failed or aborted subagent runs have left throwaway helper scripts in the
shared working tree — for example `_encode_commit_payload.py` and
`_emit_payload.py` from the #152 commit-recovery attempt. These artifacts are
never part of any issue scope. They pollute `git status`, which trips
fail-closed gates: `gitea_lock_issue` refuses to lock over tracked edits, and
the pre-flight purity checks attribute the dirt to the current session.
Rules:
- **Delete throwaway helpers as soon as the MCP commit completes or aborts.**
Any file matching `_encode_*`, `_emit_*`, or `_inline_*` created as a
scratch payload/encoding helper must be removed in the same session that
created it — success and failure paths alike.
- **Prefer the scratchpad.** Payload preparation belongs in the session
scratchpad or a temp directory, never inside the repository worktree
(see the shell-free commit payload work in #263).
- **`.gitignore` backstop.** The patterns `_encode_*.py`, `_emit_*.py`, and
`_inline_*.py` are ignored so a leftover helper cannot show up as an
untracked file and block issue locks for later sessions. Ignoring them is a
safety net, not permission to leave them behind.
- **Cleanup checklist before ending any author session:** run
`git status --porcelain` in the worktree you mutated; remove any
`_encode_*` / `_emit_*` / `_inline_*` files you created; report the removal
in the final run report like any other local mutation.
## Task/role alignment (#167)
The **requested task** decides what a session may do — not the credential it