docs(spec): #84 sync §3.1 steps 1–4 with post-M14 preprocessing (#94)

* docs(spec): #84 sync §3.1 steps 1-4 with post-M14 preprocessing

§3.1 still described the pre-M14 pipeline (SoX/torchaudio resample, 7.5 kHz
low-pass, on-by-default Wiener) — anyone reading spec.md to understand the
pipeline got pre-M14 information. PR #48 (M14, 2026-05-01) replaced step 3
with an 80 Hz high-pass and made step 4 (Wiener) opt-in by default; step 5
(loudness) was already synced by #78/#82.

Rewrote steps 1-4 to match `synthbanshee/augment/preprocessing.py:preprocess()`
and added a one-liner pointing readers at the code as the authoritative
source so future drift surfaces faster.

Closes #84.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* docs(spec): #84 review revisions — drop M14 narrative, implementation refs, drift disclaimer

Self-review of the first commit on this PR identified three structural
problems that recreated the kind of drift the issue was about:

1. The "if this section disagrees with the code, the code wins" sentence
   licensed future drift instead of forbidding it. Replaced with a
   non-absolving pointer plus an explicit constraint that PRs touching
   either side MUST update the other in the same change.
2. Embedded M14 changelog narrative ("Note: M14 (PR #48, 2026-05-01)
   removed the legacy 7,500 Hz low-pass filter ...") — specs describe
   current contracts, not their evolution. The full rationale already
   lives in wiki/topics/research-synthesis.md (cited from preprocessing.py
   line 4) and in the M14 PR description; duplicating it here would rot
   on the next pipeline change. Removed.
3. Implementation references (scipy.signal.resample_poly,
   PreprocessingConfig.wiener_denoise, "torchaudio is forbidden, see
   AGENTS.md") couple the spec to library and field-name choices —
   exactly the drift coupling #84 was about. Replaced library-name with
   "polyphase filter"; replaced field name with "Configuration:
   `PreprocessingConfig`"; removed the agent-rule reference (belongs
   in AGENTS.md, not in the audio contract spec).

Other small fixes: relabelled step 4 as "Conditional Wiener denoising"
since "optional" inside an "(ordered)" pipeline is a contradiction;
documented the resample-skip behaviour (preprocessing.py line 221);
fixed inaccurate HPF rationale ("small phone microphones cannot
capture" — they over-represent sub-bass, not fail to capture it);
restored the "16,000 Hz" unit convention from §3 line 97.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* docs(spec): #84 review revisions v2 — Copilot suggestions on §3.1

Three constructive style suggestions from copilot-pull-request-reviewer
on PR #94, all valid. Applied as suggested with one twist on the third.

1. Header line was packing 4 logical statements into one paragraph
   (pipeline requirement + dirty-file retention + implementation pointer
   + drift constraint). Split into a lead sentence and a bolded
   "Implementation:" block on its own line. Also clarified "either" by
   spelling out "the implementation or this section".
2. Step 3: expanded "sos form" → "in second-order-sections (SOS) form"
   so a non-DSP reader can parse the spec without external lookup.
3. Step 4: replaced the underspecified "applied only when explicitly
   enabled" with the concrete handle "toggle via a boolean flag on
   PreprocessingConfig". Subsumes the trailing "Configuration:
   PreprocessingConfig" sentence (the same information now reads
   inline). Still avoids naming the field, preserving the
   implementation-decoupling from the v1 revision.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: shaypal5

docs/spec.md

@@ -107,10 +107,12 @@ Project codes: `SP` (She-Proves) · `EL` (Elephant in the Room)
 
 All clips must pass through this pipeline before delivery. The "dirty" pre-pipeline file must be retained in `assets/` for robustness testing.
 
-1. **Resample** — convert to 16,000 Hz (SoX `rate` with VHQ quality, or `torchaudio.functional.resample`)
-2. **Downmix** — stereo → mono (average channels)
-3. **Spectral filter** — low-pass at 7,500 Hz to remove irrelevant high-frequency noise from budget sensors (Butterworth order 4)
-4. **Denoising** — spectral subtraction (Wiener filtering) to remove electrical hum; parameterize noise profile from silent leading segment
+**Implementation:** `synthbanshee/augment/preprocessing.py:preprocess()`. PRs that change either the implementation or this section MUST update the other in the same change.
+
+1. **Resample** — convert to 16,000 Hz using a polyphase filter. Skipped when the input is already at 16,000 Hz.
+2. **Downmix** — stereo → mono via channel averaging.
+3. **High-pass filter at 80 Hz** (Butterworth order 2, in second-order-sections (SOS) form) to remove DC and sub-bass rumble.
+4. **Conditional Wiener denoising** — off by default; toggle via a boolean flag on `PreprocessingConfig`. Used for Tier B/C clips with real added noise after acoustic augmentation.
 5. **Loudness normalization** (#78) — two stages:
    - **5a. Peak-normalize to target.** Apply a single global gain so the absolute peak lands at `PreprocessingConfig.target_peak_dbfs` (default −2.0 dBFS). A *single* gain preserves per-turn RMS *ratios* exactly, so the within-scene loudness trajectory established by per-turn RMS gain (M3a) survives — only the absolute level shifts. This step replaces the M3b "limiter only, never scale up" behaviour: pre-#78 the spec had only an upper bound on peak, leaving the absolute level unspecified; two clips could legitimately sit 6 dB apart and both be in-spec.
    - **5b. Safety limiter.** Attenuate any sample exceeding −1.0 dBFS. For in-spec target values (`target_peak_dbfs ∈ [−12.0, −1.5]`) this is a guaranteed no-op (0.5 dB margin); it remains as defence-in-depth against upstream over-range samples.