docs(phase-q): reconcile gate to S+L3 and add naming-consistency dimension

Correct the Phase Q gate (L2 landed; outstanding is Phase S + Phase L L3;
D2 complete, M9 deferred). Add a grep-verified naming audit (code-organization
§2b) and forks Q-7/Q-8/Q-9; FOREVER-STABLE contract strings excluded.
This commit is contained in:
2026-07-27 03:50:20 -04:00
parent a434ef47f8
commit 8c65069fc3
3 changed files with 394 additions and 50 deletions
+65 -10
View File
@@ -1976,6 +1976,15 @@ below). Vital is GPLv3; the borrowed artifact is the **structural pattern**, not
- **Q-5 — god-module split granularity. REC: to the audit's named seams, no finer.** Well-factored,
not atomized.
- **Q-6 — OCP registration-table. REC: in scope, last (most droppable if narrowing).**
- **Q-7 — naming rides the relocation waves, no dedicated naming wave. REC: yes** (forced once
Q-3/Q-4 settle — a rename is near-free during relocation, near-pure-churn standalone).
- **Q-8 — class/module renames beyond the free namespace fix. REC: fix the two that actively
mislead** — `BankIndex`→`BankModel` (the `bank_model.h`/`BankIndex` file↔class word-mismatch)
and the unified JSON parser → `json::Reader`/`json::Writer` (or `json::Parser`) — **leave the
merely-quirky** (`Book`/`Bank`/`Index`, `Sample`/`AudioSample`, `MinMax`, `KitBox`). Daniel's
to call.
- **Q-9 — align the `capture_realtime` (shell) / `realtime_record` (pure) word-order inversion.
REC: yes, during Q-W3** (a free rider — W3 already hoists the realtime lifecycle).
## The directory + namespace map (Q-3 / Q-4)
@@ -2052,6 +2061,35 @@ mirror-unregisters from the same table. Command-id + display strings stay **byte
(FOREVER-STABLE, per-channel — the Phase V V4 contract). Also split residual fat headers
(`capture.h`/`persist.h`) alongside their TU splits (I).
## The naming dimension (Q-7 / Q-8 / Q-9 — grep-verified audit in `docs/product/code-organization.md` §2b)
Alongside giving symbols a directory + namespace *home* (Q-3/Q-4), Phase Q gives
inconsistently/poorly-named symbols a consistent *name* — same Vital bar, orthogonal to the SOLID
focus. The audit (2026-07-27) is grep-verified; the load-bearing findings:
- **Already consistent — preserve verbatim:** the geometry-mirror verb vocabulary
(`compute<Thing>Rects`/`compute<Thing>` + `hitTest<Thing>`, verified across `bank_grid` /
`mode_switch` / `action_buttons` / `action_bar` / `tab_strip` / `prune_button` / `overflow_menu` /
`footer_bar` / `card_drag` / `component_geometry`) and the uniform `<module>_tests` CTest suffix.
- **Collisions — resolved by the Q-4 sub-namespaces for free:** four `class Parser`
(`bank_model.cpp` / `bank_book.cpp` / `owned_manifest.cpp` / `view_mode_model.cpp`) collapse to
one `json::Parser` in Q-W1; the shared pure-UI rect types `FooterRect` / `ButtonRect` (defined in
`prune_button.h`, reused by `footer_bar.h` under an explicit hand-collision "NAME NOTE") get one
`ui::` owner; `Sample` (`model::`) vs `AudioSample` (`audio::`) de-collide by home.
- **Genuine renames (Q-8/Q-9 — Daniel's call):** `BankIndex`→`BankModel` (the `bank_model.h`
file↔class word-mismatch — the worst legibility wart, rec: rename the class so the model family
reads `BankModel`/`BankBook`/`ViewModeModel`); the unified JSON parser named `json::Reader`/
`json::Writer` at W1 mint; align `capture_realtime`(shell)/`realtime_record`(pure) to the house
shell↔core convention (`drag_out`↔`drag_out_win` is the model) during Q-W3.
- **Sequencing (Q-7):** renames ride the wave that already relocates/splits the file — **no
dedicated naming wave.** Rule: *no rename lands on a file the wave isn't otherwise touching.* W1
carries the collision + model-class renames; W2 the `panel_*` names; W3 the realtime word-order
fix. Zero-behavior-change like the rest of Phase Q; verified by the module's own test executable.
- **Out of scope (never renamed):** the FOREVER-STABLE contract strings are not C++ symbols —
`command_id` strings, action display names, ext-state namespace (`"reasampler"`/`"reasampler_beta"`)
and keys, the `reasampler:` lane prefix, the VST3 class UID. Renaming a C++ class is orthogonal
to these literals (audit §2b.5).
## Performance guardrails (HARD CONSTRAINT — Daniel's non-negotiable)
The reorg must cost **zero runtime.** The two hot paths must keep their exact call/inline shape;
@@ -2075,15 +2113,27 @@ hot ones. *A split that would add a hot-path indirection is out of scope — rew
## The GATE (load-bearing — Phase Q is last)
Phase Q is **gated on the tree being otherwise quiescent.** It does not begin until **Phase S has
merged to dev**, **Phase L (L2 + L3) has merged to dev**, any **D2 residuals** are closed, and
**M9** is landed-or-abandoned. *Why:* Phase Q touches **nearly every file in `src/`** (relocate,
re-namespace, split the four largest TUs); every large in-flight branch (Phase S on its worktree,
Phase L's `bank_panel`-touching L2/L3) is diffed against the *current flat layout*, so landing a
rename-and-relocate-everything reorg mid-flight forces every open branch through the worst conflict
class — a combinatorial re-resolution, not a linear one. Phase Q is *last* precisely because it
reshapes the ground every other pillar stands on: landing it early taxes every subsequent phase;
landing it last taxes nothing. Re-confirm quiescence against dev before Q-W1.
Phase Q is **gated on the tree being otherwise quiescent.** Daniel's plain readiness target:
**"when Phase S and L3 are finished."** As of 2026-07-27 the outstanding work is precisely
**(1) Phase S** merged to dev (the large second-artifact branch, currently on the phase-s worktree)
and **(2) Phase L L3** merged to dev (the VST restyle, itself gated on Phase S). **L1/L2/L4/L5/L6/L7
have already landed** (see `COMPLETED.md`) — the earlier "L2 + L3" wording was stale and is
corrected to **L3 only**. **D2** is functionally complete (D2-W1..W3-B landed; its lone open item,
a per-track lane-split panel indicator, is *explicitly deferred*, not a blocking residual). **M9**
(slots) is *explicitly deferred* (Daniel, 2026-07-26), not scheduled work. D2 and M9 are named here
only so that *reactivating* either re-arms the quiescence condition; neither blocks the gate today.
*Why:* Phase Q touches **nearly every file in `src/`** (relocate, re-namespace, split the four
largest TUs, plus the §2b renames); every large in-flight branch (Phase S on its worktree, L3 once
it lands) is diffed against the *current flat layout*, so landing a rename-and-relocate-everything
reorg mid-flight forces every open branch through the worst conflict class — a combinatorial
re-resolution, not a linear one. Phase Q is *last* precisely because it reshapes the ground every
other pillar stands on: landing it early taxes every subsequent phase; landing it last taxes
nothing. Re-confirm quiescence against dev before Q-W1.
> **M9 disposition (Daniel-decision note).** "Deferred indefinitely" ≠ "abandoned." Immaterial to
> the gate (both clear it); matters only if M9 is reactivated — *before* Phase Q it lands cheaply on
> the flat layout, *after* it is authored against the reorganized tree. Surfaced, not silently
> resolved (full note: `docs/product/code-organization.md` §4).
## Wave sequencing (each independently landable, CTest-green at every step)
@@ -2093,12 +2143,17 @@ every commit), a property only an *incremental* reorg uses. Risk-ordered:
- **Q-W1** — safe opener: `core/json` extract (delete 4 `Parser`s) + impose the directory/
namespace layout on the 30 clean pure libs + clean shells (pure relocation, no logic change).
All later waves assume this layout.
All later waves assume this layout. **Carries the naming collision fixes + the model-class
renames (Q-8), which are free during this relocation.**
- **Q-W2..Q-W5** — the four god-module splits, one per wave, risk-ordered (`bank_panel` →
`main.cpp` → `actions.cpp` → `persist.cpp`). Q-W4 depends on Q-W2 (`panel_bank_ops` dedupe
target); Q-W5 best after Q-W4 (`prune_action` → `prune_fs` routing); otherwise parallel-safe.
**Q-W2 carries the `panel_*` names; Q-W3 carries the `capture_realtime`/`realtime_record`
word-order fix (Q-9).**
- **Q-W6** — OCP registration-table + residual fat-header (I) splits. Depends on Q-W3 (registration
code isolated first). Sequenced last; most droppable if narrowing.
- **Naming (Q-7): no dedicated wave** — every rename rides the wave already relocating/splitting
its file; a rename that would touch an otherwise-untouched file is deferred.
## Precision / invariant implications (what Phase Q does NOT change)