From 81817672af2f24897443406f12783032d89cd4cd Mon Sep 17 00:00:00 2001
From: Scott Jennings <scott.jennings+CIGINT@cloudimperiumgames.com>
Date: Wed, 10 Dec 2025 19:06:24 -0600
Subject: [PATCH] fix: mandate killing background shells before code review

Change cleanup logic from "check and maybe kill" to "kill unconditionally".
The previous approach allowed agents to read stale output from lingering
external agent processes, causing context pollution and reuse of old data.

New behavior:
- Kill ALL background shells as the FIRST action
- Do NOT read output from stale shells (BashOutput forbidden)
- Do NOT check what processes are doing - just terminate them
- Only proceed to Step 1 after all shells are dead
---
 .../code-review/instructions.xml              | 26 ++++++++++++-------
 1 file changed, 17 insertions(+), 9 deletions(-)

diff --git a/src/modules/bmm/workflows/4-implementation/code-review/instructions.xml b/src/modules/bmm/workflows/4-implementation/code-review/instructions.xml
index 6373ae04..28453411 100644
--- a/src/modules/bmm/workflows/4-implementation/code-review/instructions.xml
+++ b/src/modules/bmm/workflows/4-implementation/code-review/instructions.xml
@@ -5,17 +5,25 @@
   <critical>Generate all documents in {document_output_language}</critical>
 
   <!-- ================================================================ -->
-  <!-- CLAUDE CODE CLEANUP - KILL LINGERING EXTERNAL AGENT PROCESSES   -->
+  <!-- CLAUDE CODE CLEANUP - MANDATORY KILL OF ALL BACKGROUND SHELLS   -->
   <!-- ================================================================ -->
-  <!-- If BMAD is running as Claude Code (not the external agent), clean up
-       any terminal processes from previous external agent code reviews.
-       This prevents context pollution from stale review sessions. -->
-  <check if="BMAD is running as Claude Code (detected via KillShell tool availability or CLAUDE_CODE env)">
-    <action>Check for any running background shells/terminals from previous external agent reviews</action>
-    <action>If any `claude -p` or similar external agent processes are found running, use KillShell to terminate them</action>
-    <action>This ensures a clean slate for the new code review session</action>
-    <output>🧹 Cleaned up previous external agent review processes (if any)</output>
+  <!-- CRITICAL: Stale external agent processes cause context pollution.
+       You MUST kill ALL background shells BEFORE doing ANYTHING else.
+       DO NOT read their output. DO NOT check what they're doing.
+       Just KILL them unconditionally. -->
+  <critical>🚨 FIRST ACTION REQUIRED: Kill all background shells 🚨</critical>
+  <critical>Before ANY other workflow step, you MUST terminate all background processes.</critical>
+  <critical>DO NOT use BashOutput to read from stale shells - this causes context pollution.</critical>
+  <critical>DO NOT try to "check what they're doing" - just kill them.</critical>
+
+  <check if="BMAD is running as Claude Code (KillShell tool is available)">
+    <action>IMMEDIATELY use KillShell to terminate ALL background shells - no exceptions</action>
+    <action>Do NOT read output from these shells first - kill them blind</action>
+    <action>Do NOT rationalize keeping them alive - they contain stale data</action>
+    <action>If multiple shells exist, kill ALL of them one by one</action>
+    <output>🔪 Killed all background shells to prevent stale data contamination</output>
   </check>
+  <critical>Only proceed to Step 1 AFTER all background shells are terminated.</critical>
 
   <!-- ================================================================ -->
   <!-- EXTERNAL AGENT MANDATE - THIS IS THE MOST IMPORTANT RULE        -->