bug: --debug pytest flag conflicts with built-in pytest flag and can overwrite test files

[drewdrewthis]

Summary

The pytest plugin documents --debug as a way to enable step-by-step scenario debugging, but --debug is a built-in pytest flag that writes debug information to a file path.

Problem

When running:

pytest --debug examples/test_context_window_exceeded.py

Pytest interprets this as "write debug info to examples/test_context_window_exceeded.py", which overwrites the test file with pytest internal debug data.

The scenario plugin checks for --debug via config.getoption("--debug") but never registers it with parser.addoption(), so it accidentally hijacks pytest's built-in behavior.

Impact

• Data loss: Test files can be overwritten with pytest debug output
• Documentation mismatch: Docs say to use --debug but it causes destructive behavior

Reproduction

pytest --debug examples/test_weather_agent.py
# File is now overwritten with pytest debug info

Proposed Fix

1. Rename to --scenario-debug (avoid conflict)
2. Register it properly with parser.addoption("--scenario-debug", action="store_true")
3. Update documentation

References

• python/scenario/pytest_plugin.py lines 202-243