docs: agent temp artifact cleanup guidance and detection (#261)

Add runbook section, root-level .gitignore patterns, and detection helper
for _encode_/_emit_/_inline_ throwaway scripts. Surface non-blocking
warnings from assess_preflight_status and gitea_lock_issue.

Closes #261

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

gitea_mcp_server.py

@@ -260,9 +260,19 @@ def assess_preflight_status() -> dict:
             "Reviewer profile modified tracked workspace files after capability resolution "
             f"(offending files: {_format_preflight_files(_preflight_reviewer_violation_files)})"
         )
+    warnings: list[str] = []
+    agent_artifacts = agent_temp_artifacts.find_agent_temp_artifacts_from_porcelain(
+        _get_workspace_porcelain()
+    )
+    if agent_artifacts:
+        warnings.append(
+            "Agent temp artifacts detected at repo root (delete before mutations): "
+            f"{_format_preflight_files(agent_artifacts)}"
+        )
     return {
         "preflight_ready": not reasons,
         "preflight_block_reasons": reasons,
+        "preflight_warnings": warnings,
         "preflight_whoami_verified": _preflight_whoami_called,
         "preflight_capability_resolved": _preflight_capability_called,
         "preflight_whoami_violation_files": list(_preflight_whoami_violation_files),
@@ -373,6 +383,7 @@ import role_session_router  # noqa: E402
 import role_namespace_gate  # noqa: E402
 import task_capability_map  # noqa: E402
 import review_proofs  # noqa: E402
+import agent_temp_artifacts
 import issue_lock_worktree  # noqa: E402
 
 
@@ -877,7 +888,10 @@ def gitea_lock_issue(
     except Exception as e:
         raise RuntimeError(f"Could not write issue lock file: {e}")
 
-    return {
+    agent_artifacts = agent_temp_artifacts.find_agent_temp_artifacts_from_porcelain(
+        git_state.get("porcelain_status") or ""
+    )
+    result = {
         "success": True,
         "message": (
             f"Successfully locked issue #{issue_number} to branch '{branch_name}' "
@@ -887,6 +901,12 @@ def gitea_lock_issue(
         "branch_name": branch_name,
         "worktree_path": resolved_worktree,
     }
+    if agent_artifacts:
+        result["warnings"] = [
+            "Agent temp artifacts at repo root (delete before implementation): "
+            + ", ".join(agent_artifacts)
+        ]
+    return result
 
 
 @mcp.tool()