WS3

Author: tzanko-matev

README.md

@@ -41,12 +41,13 @@ All subclasses carry the same attributes, so existing handlers can migrate by ca
 
 `python -m codetracer_python_recorder` returns:
 
-- `0` when tracing and the target script succeed.
-- The script's own exit code when it calls `sys.exit()`.
-- `1` when a `RecorderError` bubbles out of startup or shutdown.
-- `2` when the CLI arguments are incomplete.
+- `0` when the recorder finishes cleanly, even if the traced script exits non-zero. The script's status is still recorded in `trace_metadata.json`, and a warning on stderr highlights the suppressed status.
+- `1` when a `RecorderError` bubbles out of startup or shutdown (policy failures, `require_trace`, flush/stop issues).
+- `2` when the CLI arguments are incomplete or invalid.
 
-Pass `--codetracer-json-errors` (or set the policy via `configure_policy(json_errors=True)`) to stream a one-line JSON trailer on stderr. The payload includes `run_id`, `trace_id`, `error_code`, `error_kind`, `message`, and the `context` map so downstream tooling can log failures without scraping text.
+Opt into mirroring the script's exit code with `--propagate-script-exit` (or `CODETRACER_PROPAGATE_SCRIPT_EXIT=true`). Use `--no-propagate-script-exit` to force suppression, even if the environment enables mirroring.
+
+Pass `--json-errors` (or set the policy via `configure_policy(json_errors=True)`) to stream a one-line JSON trailer on stderr. The payload includes `run_id`, `trace_id`, `error_code`, `error_kind`, `message`, and the `context` map so downstream tooling can log failures without scraping text.
 
 ### IO capture configuration
 

codetracer-python-recorder/CHANGELOG.md

@@ -10,6 +10,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 
 ### Changed
 - Module-level call events now prefer the frame's `__name__`, fall back to filter hints, `sys.path`, and package markers, and no longer depend on the legacy resolver/cache. The globals-derived naming flag now defaults to enabled so direct scripts record `<__main__>` while package imports emit `<pkg.mod>`, with CLI and environment overrides available for the legacy resolver.
+- The CLI now exits with `0` when recording succeeds regardless of the traced script’s status, records a warning when suppressing non-zero script exits, and exposes `--propagate-script-exit` / `CODETRACER_PROPAGATE_SCRIPT_EXIT` / `configure_policy(propagate_script_exit=True)` to restore passthrough semantics.
 
 ## [0.2.0] - 2025-10-17
 ### Added

design-docs/recorder-exit-code-policy-implementation-plan.status.md

@@ -7,7 +7,7 @@
 ## Workstream Progress
 - ✅ **WS1 – Policy & Configuration Plumbing:** Added `propagate_script_exit` across `RecorderPolicy`, `PolicyUpdate`, PyO3 bindings, env parsing, and Python helpers; introduced `CODETRACER_PROPAGATE_SCRIPT_EXIT`; updated Rust + Python unit coverage; rebuilt the dev wheel (`maturin develop --features integration-test`) and verified via `just test`.
 - ✅ **WS2 – CLI Behaviour & Warning Surface:** CLI now defaults to returning `0` on successful recordings, exposes `--propagate-script-exit`/`--no-propagate-script-exit`, emits a warning when suppressing non-zero script exits, and preserves non-zero statuses for recorder failures; added regression coverage (`test_exit_payloads.py`) and executed `just dev test`.
-- ☐ **WS3 – Documentation, Tooling, and Release Notes:** _Not started._
+- ✅ **WS3 – Documentation, Tooling, and Release Notes:** README and onboarding docs describe the new default, flags, and env overrides; changelog notes the behavioural change; `just dev test` re-run after docs to confirm tooling.
 
 ## Current Focus
-- Plan WS3 documentation updates and release notes covering the new default exit behaviour and configuration surfaces.
+- Monitor downstream consumers for feedback on the new default and capture any follow-up doc gaps or migration notes.

docs/onboarding/error-handling.md

@@ -29,9 +29,10 @@ else:
 - Calling `start` twice raises `RuntimeError` from a thin Python guard. Everything after the guard uses `RecorderError`.
 
 ## CLI workflow and JSON trailers
-- Run `python -m codetracer_python_recorder --codetracer-format=json app.py` to trace a script.
-- Exit codes: `0` for success, script exit code when the script stops itself, `1` when a `RecorderError` escapes startup/shutdown, `2` on CLI misuse.
-- Pass `--codetracer-json-errors` (or `configure_policy(json_errors=True)`) to mirror each failure as a one-line JSON object on stderr.
+- Run `python -m codetracer_python_recorder --format=json app.py` to trace a script.
+- Exit codes: `0` when the recorder completes without errors (default even if the script exits non-zero, warning emitted), `1` when a `RecorderError` escapes startup/shutdown, `2` on CLI misuse.
+- Use `--propagate-script-exit` (or set `CODETRACER_PROPAGATE_SCRIPT_EXIT=true`, `configure_policy(propagate_script_exit=True)`) when wrappers must mirror the script status.
+- Pass `--json-errors` (or `configure_policy(json_errors=True)`) to mirror each failure as a one-line JSON object on stderr.
 - JSON fields: `run_id`, optional `trace_id`, `error_code`, `error_kind`, `message`, `context`.
 
 ## Migration checklist for existing clients