docs(phase-q): settle Q-10 (audit-report home) and Q-11 (pitch-remediation depth)

This commit is contained in:
2026-07-27 14:36:57 -04:00
parent bbfb033819
commit 25c77a5de3
3 changed files with 62 additions and 30 deletions
+17 -5
View File
@@ -474,6 +474,11 @@ L1, L2, L3, L4, L5, L6, and L7 have all landed. **Phase L is complete.**
>
> **Settled (Q-1, this-doc):** the phase is **`Q` (Quality)**; point-id family `Q1..Qn`, wave
> prefixes `Q-W0` (the pre-restructure audit) then `Q-W1..Q-W6` (the structural reorg).
> **Settled (Q-10/Q-11, Daniel 2026-07-27):** Q-10 audit-report home = a **committed doc**
> (`docs/product/code-quality-audit.md`, not a tracked issue list); Q-11 pitch-remediation depth =
> **defer to findings** (default document-and-defer; weigh a bounded OLA fix before a technique
> replacement; a technique replacement is a Daniel decision at triage time, not an automatic Q-W0
> action).
> **Recommended, Daniel's to call (Q-2..Q-9, see
> `docs/product/code-organization.md` §6):** Q-2 JSON extraction in scope + first (rec: yes);
> Q-3 directory shape `core/`/`shell/`/`app/` top-split with subsystem dirs beneath (rec: this
@@ -543,7 +548,12 @@ before/after listening or null check. **The gate to Q-W1 is: triage complete + D
phase handling, transient/formant behavior, buffer edges), `sampler_core` (repitch ratio math,
interpolation order/quality, loop-point crossfade, voice-stealing correctness/click behavior),
`peaks` (envelope min/max binning), `wav_trim` (decay-scan threshold + truncate plan), and the
capture/tail paths.
capture/tail paths. **Pitch-remediation depth (Q-11 SETTLED, Daniel 2026-07-27): defer to
findings** — default document-and-defer; only if the audit surfaces artifacts that matter, weigh a
bounded OLA fix (window/overlap/edge tuning) **before** a technique replacement. A technique
replacement (phase-vocoder / WSOLA) reshapes `pitch_shift`, spills a downstream Q-wave point, and is
a **Daniel decision at triage time, not an automatic Q-W0 action** — Q-W0 surfaces the
recommendation, Daniel calls it.
- [ ] **Architecture-smell audit.** Duplicate code, reinvented wheels, poor abstractions, and any
leaky pure/shell boundary (a `core/` module reaching a REAPER/host type, or geometry/algorithm
math living untestable in a shell). Cross-check against — but do not merely restate — the §2/§2b
@@ -556,10 +566,12 @@ before/after listening or null check. **The gate to Q-W1 is: triage complete + D
There was a prior incident here — envelope times stored in the frame domain — so this is a
first-class category, not a footnote. Sweep envelope times, loop points, fade lengths, tail
lengths, and any UI geometry constant that silently assumes a DPI/rate.
- [ ] **Triage + report.** Write the findings report; classify each finding fix-now vs.
document-and-defer with a one-line rationale; for each fix-now, note whether it is remediated in
Q-W0 or assigned to the downstream wave that already opens the file. Deferred findings carry a
documented rationale so they are a decision, not an omission.
- [ ] **Triage + report.** Write the findings report as a **committed doc,
`docs/product/code-quality-audit.md`** (Q-10 SETTLED, Daniel 2026-07-27 — beside the SOLID/naming
audit, not a tracked issue list); classify each finding fix-now vs. document-and-defer with a
one-line rationale; for each fix-now, note whether it is remediated in Q-W0 or assigned to the
downstream wave that already opens the file. Deferred findings carry a documented rationale so they
are a decision, not an omission.
- [ ] **Sign-off gate.** Daniel reviews the triage and signs off on each disposition. Q-W1 does not
begin until this is done; fold any new/reshaped downstream points the audit surfaces into
Q-W1..Q-W6 before starting them.