# Ratchet for scripts/check_wfmgen_flag_docs.py's exercise rule.
#
# One wfmgen flag per line that the docs DOCUMENT but never RUN: no `wfmgen`
# command line anywhere under docs/ passes it, so no reader can copy a line
# that uses it and no gate demonstrates what it does.
#
# THIS LIST MAY ONLY SHRINK, and it is checked in BOTH directions:
#
#   * a flag that is unexercised and NOT listed here fails -- that is a new
#     capability shipped with nothing running it;
#   * a flag listed here that IS now exercised also fails -- a waiver that
#     outlives its defect silently covers the next one, which is the rule
#     `.example-arity-ratchet` and `.private-rng-ratchet` already keep.
#
# Why this exists. `docs/design/wfmgen.md`'s first design goal admits the
# hole in prose -- "nothing states the intended coverage, so a missing
# capability is a gap nobody's gate can see" -- and the gate has been
# printing the measurement as its SECOND line, which nobody read, since it
# was written: "(53 of 67 flags exercised)". doppler#1143 is that sentence
# with a number attached.
#
# doppler#1149 PAID THE DEBT DOWN. All thirteen real capabilities now have a
# runnable line on the page that was already explaining them, and 66 of 67
# flags are exercised. What each one got:
#
#   --clip-report / --clip-error  the clipping section of waveforms.md, as
#       the sequence a reader actually performs: measure (42.41% of I/Q
#       components clipped, peak +13.4 dB over full scale), then make it an
#       exit status, then take the remedy the report named and pass.
#   --level         beside it, against --headroom -- per-source placement
#       versus one common gain on the way to the wire.
#   --pn-poly       forcing the tap set, shown byte-identical to the
#       auto-selected one for length 7 (0x60), which is how you CHECK a
#       polynomial you were handed.
#   --rrc-span      the deeper-stopband / more-filter-delay trade.
#   --gap-noise     measured in the gap: 0.1036 power at 10 dB SNR, or 0.0.
#   --randomize     the US spelling, run and byte-compared against
#       --randomise. An alias exists to be typed; this proves it is real.
#   --acq-code-gen / --data-code-gen  one DSSS burst with BOTH codes
#       generated, beside the --sync-gen line that was already there.
#   --data          the same continuous DSSS stream with the data switched
#       off -- the pure code, what you correlate against.
#   --fc            the SigMF sidecar it writes, read back.
#   --repeat / --realtime-resync  the scenes page's looping and live-stream
#       fences. Both loop forever by design, so they are parse-validated
#       rather than executed -- which the gate's own rules already handle.
#
# WHAT IS LEFT, and it is not debt.
#
#   -o  cannot be retired by writing anything. It is ALREADY used in a
#       `wfmgen` command line under docs/ -- the "30-second version" on the
#       guide index opens with `-o capture.cf32` -- but the gate tokenises
#       LONG flags only (`_TOKEN` matches `--[A-Za-z]...`), so a short flag
#       can never land in `seen` and is therefore unexercised BY
#       CONSTRUCTION. This entry is a fact about the checker, not a gap in
#       the docs, and it must stay until the checker learns short flags.
#       Do NOT add a doc line for it: there is no line that would work, and
#       writing documentation to tick a gate is the wrong direction anyway.
#
-o
