From 25c77a5de3976b6956979c82782077565cd7d025 Mon Sep 17 00:00:00 2001 From: daniel-c-harvey Date: Mon, 27 Jul 2026 14:36:57 -0400 Subject: [PATCH] docs(phase-q): settle Q-10 (audit-report home) and Q-11 (pitch-remediation depth) --- CONTEXT.md | 18 ++++++++--- PLAN.md | 22 ++++++++++--- docs/product/code-organization.md | 52 +++++++++++++++++++------------ 3 files changed, 62 insertions(+), 30 deletions(-) diff --git a/CONTEXT.md b/CONTEXT.md index 039d9b9..36c90d0 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -3280,11 +3280,19 @@ Q-W1..Q-W6 points (e.g. an algorithm rewrite that changes a module's shape, or a that changes a payload). Those reshapes are folded in before Q-W1 begins. Q-W0 is thus both the entry point and a scoping input to the rest of the phase. -**Report home (fork — Daniel's call):** whether the findings report lives as a committed doc under -`docs/product/` (e.g. `code-quality-audit.md`, alongside the SOLID/naming audit that already lives in -`docs/product/code-organization.md`) or as a tracked issue list is Daniel's call — see the fork note -in `docs/product/code-organization.md` §2c. The recommendation is a committed doc: it sits beside the -existing audit, travels with the tree, and each finding's disposition is reviewable in one place. +**Report home (Q-10 — SETTLED, Daniel 2026-07-27): a committed doc.** The findings report lives as a +committed doc under `docs/product/` — `code-quality-audit.md`, alongside the SOLID/naming audit that +already lives in `docs/product/code-organization.md`. It sits beside the existing audit, travels with +the tree, and each finding's disposition is reviewable in one place. A tracked issue list was set +aside — the audit is a one-shot pre-reorg sweep, not an ongoing backlog. The Q-W0 "Triage + report" +step writes this file. See `docs/product/code-organization.md` §2c.3. + +**Pitch-remediation depth (Q-11 — SETTLED, Daniel 2026-07-27): defer to findings.** How deep the OLA +pitch-preserve remediation goes is decided by what Q-W0 finds, not pre-committed. Default is +**document-and-defer**; only if the audit surfaces artifacts that matter is a **bounded fix** (tune +window/overlap/edge handling) weighed **before** a **technique replacement** (phase-vocoder / WSOLA). +A technique replacement reshapes `pitch_shift`, would spill a downstream Q-wave point, and is +therefore **a Daniel decision at triage time, not an automatic Q-W0 action**. See §2c.4. ## The quality bar — Vital (read from its actual `src/` tree) diff --git a/PLAN.md b/PLAN.md index f12172c..3fb5395 100644 --- a/PLAN.md +++ b/PLAN.md @@ -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. diff --git a/docs/product/code-organization.md b/docs/product/code-organization.md index 5790852..bde8a7b 100644 --- a/docs/product/code-organization.md +++ b/docs/product/code-organization.md @@ -16,8 +16,9 @@ reference, and the numbered fork decisions. **Status:** framed by product-designer (2026-07-26); gate reconciled + naming dimension added (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. +§2c, forks Q-10/Q-11). Forks Q-1 … Q-11 below are the decision record; **Q-1 (namespace letter), +Q-10 (audit-report home), and Q-11 (pitch-remediation depth) are SETTLED (Daniel, 2026-07-27)**; the +remaining forks (Q-2…Q-9) 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). @@ -361,7 +362,8 @@ audits. ### 2c.2 Deliverable, triage, and the sub-gate -- **Deliverable:** a **written findings report** over the surfaces above. +- **Deliverable:** a **written findings report** over the surfaces above — a committed doc, + `docs/product/code-quality-audit.md` (Q-10, settled §2c.3), beside this framing. - **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). @@ -375,24 +377,34 @@ audits. - **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) +### 2c.3 Q-10 — where the findings report lives. SETTLED (Daniel, 2026-07-27): a committed doc. -- **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). +The Q-W0 findings report is a **committed doc under `docs/product/`** — `code-quality-audit.md`, +beside the SOLID/naming audit this doc already holds. 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. The Q-W0 "Triage + report" step writes *this* file — the report's home is +explicit, not a placeholder. + +- **Considered and set aside:** a tracked **issue list** (one issue per finding). Would fit if each + finding needed independent lifecycle state (assignee, open/closed) driving work item by item. Set + aside 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. + +### 2c.4 Q-11 — how deep pitch remediation goes. SETTLED (Daniel, 2026-07-27): defer to findings. + +The remediation depth is **not pre-committed** — it is decided by what the Q-W0 audit actually +finds in the OLA pitch-preserve engine (`src/vst/pitch_shift`). The settled rule: + +- **Default: document-and-defer.** Absent findings that matter, record the artifacts/limits as a + known, documented trade-off and change nothing now — this keeps Phase Q a reorg. +- **Escalation, in order, only if the audit surfaces artifacts that matter for the tool's use:** + weigh a **bounded fix** (tune window/overlap/edge handling within the existing OLA approach — no + new dependency, no new module shape) **before** a **technique replacement**. +- **Technique replacement is a Daniel decision at triage time, not an automatic Q-W0 action.** + Swapping in a stronger method (phase-vocoder / WSOLA) is a real DSP change that reshapes + `pitch_shift` and would **spill a downstream Q-wave point** — so if the audit's findings point that + way, Q-W0 surfaces the recommendation and Daniel makes the call; Q-W0 does not perform a technique + replacement on its own authority. ---