verification: add worked example with plots; loss.py FAIL exit code fixes

- Add 'Worked Example of Loss Tests' section to verification procedure,
  showing clip value selection with before/after loss plots
- Add automated pass/fail subsection using --compare/--delta for CI use
- loss.py: print FAIL and exit(1) for --compare failures; replace quit()
  with sys.exit(1) throughout for correct CI return codes

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: drowe67

doc/verification/loss_clipped.png

@@ -107,6 +107,120 @@ Connect Tx and Rx via coax with appropriate attenuators. Run the same test.
 
 Pass criterion: loss within ±10% of baseline.
 
+## Worked Example of Loss Tests
+
+The following example uses the rade_c WAV tools as the device under test
+to demonstrate the full loss measurement workflow, including how to identify
+and clip start/end transients. You may notice similar transients when testing
+your own application or radio — it is good practice to remove them, as they
+inflate the mean loss and can mask the true integration performance.
+
+Run a V2 software loopback from the `rade_c/build` directory, exporting
+feature vectors at both ends:
+
+```
+./src/rade_tx_wav --v2 -f features_tx.f32 ../wav/all.wav tx.wav
+./src/rade_rx_wav --v2 -f features_rx.f32 tx.wav decoded.wav
+```
+
+First pass — no clipping, `--plot` to inspect the loss curve:
+
+```
+python3 ~/radae/loss.py features_tx.f32 features_rx.f32 \
+    --plot --png loss_unclipped.png
+```
+
+![Loss before clipping](loss_unclipped.png)
+
+The spike at the start (~22) is the RADE acquisition transient; the smaller
+spike at the end (~3) is the end-of-over frame. Both are expected behaviour
+from the state machine. Clip them out and re-run:
+
+```
+python3 ~/radae/loss.py features_tx.f32 features_rx.f32 \
+    --clip_start 100 --clip_end 300 \
+    --plot --png loss_clipped.png
+```
+
+![Loss after clipping](loss_clipped.png)
+
+With transients removed, loss drops from 0.113 to 0.082 — consistent with
+the reference baseline. `--clip_start 100` (1 s) and `--clip_end 300` (3 s)
+are conservative defaults; your integration may need different values
+depending on acquisition time. Use `--plot` to check.
+
+## Worked Example of Loss Tests
+
+The following example uses the rade_c WAV tools as the device under test
+to demonstrate the full loss measurement workflow, including how to identify
+and clip start/end transients. You may notice similar transients when testing
+your own application or radio — it is good practice to remove them, as they
+inflate the mean loss and can mask the true integration performance.
+
+Run a V2 software loopback from the `rade_c/build` directory, exporting
+feature vectors at both ends:
+
+```
+./src/rade_tx_wav --v2 -f features_tx.f32 ../wav/all.wav tx.wav
+./src/rade_rx_wav --v2 -f features_rx.f32 tx.wav decoded.wav
+```
+
+First pass — no clipping, `--plot` to inspect the loss curve:
+
+```
+python3 ~/radae/loss.py features_tx.f32 features_rx.f32 \
+    --plot --png loss_unclipped.png
+```
+
+![Loss before clipping](loss_unclipped.png)
+
+The spike at the start (~22) is the RADE acquisition transient; the smaller
+spike at the end (~3) is the end-of-over frame. Both are expected behaviour
+from the state machine. Clip them out and re-run:
+
+```
+python3 ~/radae/loss.py features_tx.f32 features_rx.f32 \
+    --clip_start 100 --clip_end 300 \
+    --plot --png loss_clipped.png
+```
+
+![Loss after clipping](loss_clipped.png)
+
+With transients removed, loss drops from 0.113 to 0.082 — consistent with
+the reference baseline. `--clip_start 100` (1 s) and `--clip_end 300` (3 s)
+are conservative defaults; your integration may need different values
+depending on acquisition time. Use `--plot` to check.
+
+### Automated pass/fail
+
+To compare your application against the rade_c software reference without
+needing to record the baseline loss manually, use `--features_hat2` and
+`--compare`. First generate a software reference run:
+
+```
+./src/rade_rx_wav --v2 -f features_rx_ref.f32 tx.wav /dev/null
+```
+
+Then run your application (the DUT) on the same `tx.wav` to produce
+`features_rx_dut.f32`, and compare:
+
+```
+python3 ~/radae/loss.py features_tx.f32 features_rx_ref.f32 \
+    --features_hat2 features_rx_dut.f32 \
+    --compare --delta 0.008 \
+    --clip_start 100 --clip_end 300
+```
+
+Output:
+```
+loss1: 0.082 loss2: 0.082 delta: 0.000
+PASS
+```
+
+`loss.py` prints `PASS` or `FAIL` and exits with code 0 or 1 respectively,
+making it suitable for use in CI scripts. A `--delta` of 0.008 corresponds
+to approximately ±10% of the V2 software loopback baseline (0.082).
+
 ## Submitting Results
 
 Copy `doc/verification/template.md` to `doc/verification/<serial>-<application>.md`

doc/verification/loss_unclipped.png

@@ -30,6 +30,7 @@
 """
 
 import os
+import sys
 import argparse
 import numpy as np
 import torch
@@ -108,12 +109,12 @@ def find_loss(features_fn, features_hat_fn):
 if args.loss_test > 0.0:
    if min_loss > args.loss_test:
       print("FAIL")
-      quit()
+      sys.exit(1)
 if args.acq_time_test > 0:
    # one feature vector every 10ms
    if acq_time > args.acq_time_test:
       print("FAIL")
-      quit()
+      sys.exit(1)
 if args.loss_test > 0.0 or args.acq_time_test:
    print("PASS")
 
@@ -123,6 +124,9 @@ def find_loss(features_fn, features_hat_fn):
       print(f"loss1: {min_loss:5.3f} loss2: {min_loss2:5.3f} delta: {np.abs(min_loss-min_loss2):5.3f}")
       if np.abs(min_loss-min_loss2) < args.delta:
          print("PASS")
+      else:
+         print("FAIL")
+         sys.exit(1)
 
 if args.stats:
    def print_stats(loss_arr, label):