jedarden e946d84dce docs(bf-1lghw6): add orphaned process verification documentation

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

2026-07-07 02:45:45 -04:00

2.4 KiB

Raw Blame History

Verification Note for bf-1lghw6

Task

Create orphaned process verification documentation file with basic structure.

Implementation Summary

Created comprehensive documentation at docs/test-hygiene/orphaned-process-verification.md that includes:

Overview Section

Explains what orphaned process verification is
References the test hygiene rules from CLAUDE.md
Describes the problem: tests spawning subprocesses can leave orphans

Usage Instructions

Shell script usage examples (./scripts/check-orphaned-processes.sh)
All command-line options: --json, --kill, --verbose, --pattern
Exit codes and their meanings
JSON output format specification

Rust Test Helpers

In-test verification using process_guard module
Code examples for RAII guards

Best Practices

RAII guards for process spawning
Verification at test boundaries
Using timeouts on all waits (never bare child.wait())
Using Stdio::null() for long-running servers

CI Integration

Example bash script for post-test checks
Exit code handling

Troubleshooting

How to identify and clean up orphaned processes
How to find leaking tests
Dependency requirements (pgrep)

Acceptance Criteria Status

PASS

✅ Documentation file exists at docs/test-hygiene/orphaned-process-verification.md
✅ Contains clear overview of orphaned process verification (Overview + Problem Statement sections)
✅ Includes basic usage instructions for the verification script (Verification Methods section with examples)
✅ References the verification script at scripts/check-orphaned-processes.sh (multiple references)
✅ Explains the purpose (test hygiene, preventing hung tests) - covered in Overview, Problem Statement, and Best Practices

Files Created

docs/test-hygiene/orphaned-process-verification.md (241 lines)

scripts/check-orphaned-processes.sh (verification script, already exists)
CLAUDE.md (test hygiene rules)
Bead bf-5xh7g: Orphaned process verification implementation
Bead bf-119ys: TH-03 process cleanup with RAII guards

Test Results

N/A - Documentation-only task, no executable code to test

Conclusion

The documentation successfully provides a comprehensive guide to orphaned process verification, meeting all acceptance criteria. The file is ready to be committed and pushed to the repository.

2.4 KiB Raw Blame History