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:
+65
-10
@@ -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)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user