Add comprehensive "Common Issues and Resolutions" section documenting
5 frequently encountered orphaned process scenarios with step-by-step
resolution procedures:
1. Address Already in Use Error - Port conflicts from stale servers
2. Test Suite Hangs Indefinitely - Pipe buffer blocking wait()
3. Multiple Orphaned Processes After CI Timeout - Fuzz harness interruption
4. Zombie Process Accumulation - Unreaped children
5. Permission Denied on Verification Script - Missing execute bit
Each issue includes:
- Clear symptom description
- Root cause analysis
- Step-by-step resolution commands
- Code examples for fixes
- Prevention strategies
Resolves bead bf-58z9ib acceptance criteria:
- Lists at least 3 common issues with resolutions ✅ (5 documented)
- File is committed to git ✅
Process pattern explanations (pdftract mcp, TH-0, TH_0) already exist
in docs/test-hygiene/orphaned-process-verification.md lines 110-251.
Co-Authored-By: Claude <noreply@anthropic.com>
Added cross-reference in the References section of the orphaned process
verification guide to link to the post-test integration documentation for
CI workflow integration details.
Acceptance criteria:
- File exists at docs/test-hygiene/orphaned-process-verification.md ✓
- Contains clear introduction to orphaned process verification ✓
- Documents basic verification script usage ✓
- References the post-test integration documentation ✓
Verification: docs/test-hygiene/orphaned-process-verification.md
Added comprehensive documentation for orphaned process verification:
- Detailed explanations for three default process patterns:
* pdftract mcp (MCP server subprocess)
* TH-0 (test harness - hyphen variant)
* TH_0 (test harness - underscore variant)
- Each pattern includes:
* What it is and when it appears
* Typical spawn patterns
* Why it orphans (root causes)
* Detection examples with expected output
* Manual cleanup commands
- Manual verification walkthrough with 4 scenarios:
* After a test run (normal workflow)
* Before starting a test run (pre-flight check)
* Investigating a leaking test (binary search)
* CI post-test verification (automation)
- 5 common orphan scenarios with symptoms, verification, and fixes:
* Test timeout leaves children alive
* Panic before cleanup
* Undrained Stdio::piped() blocks wait()
* Port already in use from previous run
* Fuzz harness leaves target processes
All examples include realistic command-line output and reference existing
cleanup patterns (OrphanedProcessGuard, RAII).
Verification: notes/bf-vnx45a.md
Closes bf-vnx45a
Create comprehensive documentation for orphaned process verification
system at docs/test-hygiene/orphaned-process-verification.md
The documentation includes:
- Overview of orphaned process verification and why it matters
- Usage instructions for scripts/check-orphaned-processes.sh
- Verification methods (shell script, Rust helpers, CI integration)
- Best practices for RAII guards and process cleanup
- CI integration examples
- Troubleshooting guide
Closes bf-1lghw6. Verification: notes/bf-1lghw6.md
