docs(plan): add Phase Q pre-restructure functional+DSP audit wave (Q-W0)

docs/product/code-organization.md

@@ -15,15 +15,24 @@ Its build roadmap lives in **PLAN.md §Phase Q** and its authoritative spec in
 reference, and the numbered fork decisions.
 
 **Status:** framed by product-designer (2026-07-26); gate reconciled + naming dimension added
-(2026-07-27). Forks Q-1 … Q-9 below are the decision record; **Q-1 (namespace letter) is settled
-by this doc**; the remaining forks carry a leading recommendation and are Daniel's to call. Two
-grep-verified audits ground every claim: a **SOLID audit** (§2) and a **naming/symbol-consistency
-audit** (§2b) — both staff-engineer-rigor analyses of the actual `src/` tree.
+(2026-07-27); **pre-restructure functional + DSP audit wave (Q-W0) added 2026-07-27** (Daniel's ask —
+§2c, forks Q-10/Q-11). Forks Q-1 … Q-11 below are the decision record; **Q-1 (namespace letter) is
+settled by this doc**; the remaining forks carry a leading recommendation and are Daniel's to call.
+Three audits ground the phase: the two structural, grep-verified ones — a **SOLID audit** (§2) and a
+**naming/symbol-consistency audit** (§2b) — plus the **functional + DSP audit** defined as Q-W0 (§2c),
+which runs *first* and is *executed* in-phase (this doc scopes it, staff-engineer performs it).
 
 ---
 
 ## 0. TL;DR
 
+- **Phase Q opens with a pre-restructure audit (Q-W0), then does the structural reorg.** Before a
+  single file moves, a **functional + DSP quality audit** (§2c) runs first — a close-eyed pass over
+  the DSP paths (**pitch especially**), duplicate code / reinvented wheels, and env-coupled-constant
+  domain-modeling smells — producing a triaged findings report. **Q-W1 (the first structural wave)
+  is gated on that triage being complete and Daniel signing off on each finding's disposition.**
+  Fixes classified fix-now are eliminated in Q-W0 (or folded into the wave that opens the file), not
+  carried untouched into the reorg. Everything below §2c is the structural reorg that follows.
 - **This is not a feature phase — it is a quality phase.** The code works. The pure-core /
   shell split is real and healthy (30 pure static libs, each with its own CTest executable,
   the discipline CMake-enforces). What Phase Q fixes is that the *shape* of the code doesn't
@@ -298,6 +307,95 @@ is the same guardrail §7 states for the reorg, restated for the naming dimensio
 
 ---
 
+## 2c. The pre-restructure functional + DSP quality audit (Q-W0 — runs FIRST)
+
+The §2 SOLID audit and §2b naming audit are **structural** analyses — they ground *where
+responsibilities live* and *what things are called*. Daniel asked (2026-07-27) for a **third audit
+that runs before the reorg begins**, on a different axis: *does the code do the right thing, and does
+it do it well.* That is **Q-W0** — a thorough functional + DSP static analysis producing a written,
+triaged findings report, complementary to (not a repeat of) §2/§2b. Its rationale: the structural
+reorg is the wrong moment to discover a bad algorithm. A reinvented wheel or a numerically-fragile
+DSP path should be eliminated — or consciously documented — **before** it is relocated,
+re-namespaced, and split, not carried forward untouched into a tidier tree. "Something I can stand to
+look at" is partly shape (§2/§2b) and partly *functional soundness* (§2c).
+
+Q-W0 is **not executed by product-designer** — this doc *defines the wave and its scope*; the audit
+itself is staff-engineer/DSP work. The authoritative wave definition lives in **PLAN.md §Q-W0** and
+its spec framing in **CONTEXT.md §"The pre-restructure audit wave (Q-W0)"**; this section is the
+evidence-doc framing (the *why* and the smell taxonomy), matching how §2/§2b frame the structural
+audits.
+
+### 2c.1 Audit surfaces (the named targets)
+
+1. **DSP / audio — a close eye on pitch** (Daniel's verbatim emphasis). Assess *algorithm quality* —
+   correctness, artifacts, numerical robustness, interpolation quality, reinvented-wheel vs.
+   established DSP technique — across:
+   - **`src/vst/pitch_shift`** — the **hand-rolled OLA pitch-preserve** engine. Highest priority.
+     Look at window function + overlap factor choice, phase coherence between frames, transient
+     smearing and formant behavior, and buffer-edge handling. A hand-rolled OLA shifter is exactly
+     the class of "reinvented wheel / poor-quality algorithm" Daniel wants scrutinized: is the
+     technique sound, are the artifacts acceptable, is a better-established method (e.g. a
+     phase-vocoder or WSOLA variant) warranted — and if the current approach is kept, is that a
+     *documented* decision?
+   - **`sampler_core`** — repitch ratio math, interpolation order/quality (linear vs. higher-order),
+     loop-point-aware sustain crossfade behavior, and voice-stealing correctness (clicks or
+     discontinuities on steal).
+   - **`peaks`** — envelope min/max binning correctness.
+   - **`wav_trim`** — the realtime-tail decay-scan threshold + truncate plan (numerical edge cases).
+   - **capture / tail paths** — DSP-adjacent arithmetic in range/tail handling.
+2. **Architecture smells (functional lens).** Duplicate code, reinvented wheels, poor abstractions,
+   and leaky pure/shell boundaries — overlapping §2/§2b's territory but reporting the *functional*
+   smell those audits did not target (a duplicated *algorithm*, not merely a duplicated
+   *responsibility*; a `core/` module reaching a host type; algorithm math stranded untestable in a
+   shell).
+3. **Env-coupled-constant domain-modeling smells — a first-class category.** ANY value stored in a
+   **frame / rate / DPI / tick-coupled** domain that should instead be stored **rate-free and
+   resolved at the point of use** is a domain-modeling smell. The correct framing is *store rate-free,
+   resolve at use* — **not** "rescale by the rate at the boundary." This is grounded in the
+   load-bearing invariant that wall-clock times are stored as **rate-free SECONDS** resolved against
+   the live project rate (`sample_map`), with **NO hardcoded sample rates in `src/`** (Daniel's
+   standing ruling). **There was a prior incident on exactly this** — envelope times stored in the
+   frame domain — which is why it is called out as its own smell category and not folded into
+   "architecture smells." Sweep at least: envelope times, loop points, fade lengths, tail lengths,
+   and any UI geometry constant that silently bakes in a DPI or a rate.
+
+### 2c.2 Deliverable, triage, and the sub-gate
+
+- **Deliverable:** a **written findings report** over the surfaces above.
+- **Triage:** every finding is classified **eliminate-before-restructure** (fix-now) or
+  **document-and-defer** (with a one-line rationale, so a deferral is a recorded decision, never a
+  silent omission).
+- **Where fixes land:** fix-now findings are remediated **in Q-W0**, or folded into the downstream
+  wave that already opens the file (recorded per finding). They are **not** silently deferred into the
+  structural waves — eliminations happen here or as folded-in remediation, so Q-W1+ inherits a
+  functionally-sound tree.
+- **Reshaping downstream:** Q-W0's findings may **add or reshape** Q-W1..Q-W6 points (an algorithm
+  rewrite that changes a module's shape; a domain-modeling fix that changes a payload). Those reshapes
+  are folded in before Q-W1 begins.
+- **The sub-gate:** Q-W1 does not begin until Q-W0's **triage is complete and Daniel has signed off**
+  on every finding's disposition. This is the entry gate to the whole structural reorg.
+
+### 2c.3 Fork — Q-10: where does the findings report live? (Daniel's call)
+
+- **Recommendation:** a **committed doc under `docs/product/`** (e.g. `code-quality-audit.md`),
+  beside the SOLID/naming audit this doc already holds. Reasons: it travels with the tree, each
+  finding's disposition is reviewable in one place, and it matches the precedent set by §2/§2b living
+  as committed framing.
+- **Alternative:** a tracked **issue list** (one issue per finding). Better if Daniel wants each
+  finding to carry independent lifecycle state (assignee, open/closed) and to drive work item by item.
+  Reasonable; rejected as the lead only because the audit is a one-shot pre-reorg sweep, not an ongoing
+  backlog, and a single reviewable doc reads better against the "stand to look at" bar.
+- **Fork — Q-11: how deep does pitch remediation go, if the audit finds the OLA shifter wanting?**
+  Three shapes, Daniel's call at triage time: **(a) document-and-defer** — record the artifacts/limits
+  as a known trade-off, change nothing now (lowest risk; keeps Phase Q a reorg); **(b) bounded fix** —
+  tune window/overlap/edge handling within the existing OLA approach (medium; no new dependency, no
+  new module shape); **(c) replace the technique** — swap in a stronger method (phase-vocoder / WSOLA),
+  a real DSP change that reshapes `pitch_shift` and likely spills a downstream Q-wave point. The
+  recommendation is to **defer this decision to the audit's findings** rather than pre-commit: pick (a)
+  unless the audit shows audible artifacts that matter for the tool's use, then weigh (b) before (c).
+
+---
+
 ## 3. Performance is a hard constraint (the guardrail, carried verbatim-in-spirit)
 
 Daniel's stated non-negotiable: reorganize **without sacrificing actual performance.** The