docs(phase-q): record Q-W4/Q-W5/Q-W6 landings — all seven waves structurally complete; remaining: DAW verification batch, CLAUDE.md refresh, dev merge
This commit is contained in:
@@ -313,6 +313,15 @@ panel adopts knob deck + curve popup, `param_slider` slider rows retired on that
|
||||
> a file move + namespace change is mechanically verifiable — `ctest --test-dir build` is green
|
||||
> or it isn't. **Green-CTest-at-every-point is an acceptance criterion.** Big-bang is rejected;
|
||||
> the reorg is risk-ordered waves (W1 safe opener → W2/W2v–W5 god-module splits → W6 OCP finish).
|
||||
>
|
||||
> **PHASE STATUS (2026-07-29): all seven waves (Q-W0..Q-W6 incl. Q-W2v) are structurally
|
||||
> COMPLETE.** Remaining before the phase closes and merges to `dev`: (1) Daniel's in-DAW
|
||||
> verification batch — the full deferred list across all waves (panel parity, editor/processor
|
||||
> parity, stereo Preserve listening, null test, bit-identical repeats, capture flows, action
|
||||
> families, one-op-one-Ctrl-Z, prune fail-safes, save/load/relocation) — now unblocked since the
|
||||
> tree is stable; (2) the phase-close CLAUDE.md architecture refresh (module map still describes
|
||||
> some pre-Q homes); (3) the phase-q → dev merge on Daniel's sign-off. See `COMPLETED.md` for
|
||||
> each wave's full landed narrative.
|
||||
|
||||
## Q-W0 — pre-restructure functional + DSP quality audit (runs FIRST; gates Q-W1)
|
||||
**STATUS (2026-07-29): audit COMPLETE, triage COMPLETE, sign-off COMPLETE, fix-now
|
||||
@@ -475,78 +484,67 @@ before/after listening or null check. **The gate to Q-W1 is: triage complete + D
|
||||
> by design, not yet performed.
|
||||
|
||||
## Q-W4 — split `actions.cpp` + dedupe bank verbs against `panel_bank_ops`
|
||||
**Goal:** Split the two unrelated command-id families in one TU (1016 LOC at the Q-W0 census —
|
||||
T4-03: the planned seams still land sub-600, no reshape) into
|
||||
`design_view_actions` / `bank_actions` / `prune_action`, and **dedupe** `actions.cpp`'s own
|
||||
`promptText`/`mintBankId` and bank verbs against the `panel_bank_ops` single-owner established in
|
||||
Q-W2. `prune_action` keeps the `doBankPruneFolder` deletion authority contract intact (routes to
|
||||
`persist`'s `prune_fs` after W5). CONTEXT.md §Phase Q (actions split seams; bank-verb dedupe).
|
||||
See `docs/product/code-organization.md` §2.1, §2.4.
|
||||
**Verify:** CTest green at every commit. Every action fires identically in DAW (Design View
|
||||
family; multi-bank create/rename/reorder/delete/evacuate/activate/move/copy/remove; prune). The
|
||||
bank-CRUD verbs have **one** implementation home (no `bank_panel`/`actions` duplication). Each
|
||||
bank verb still wraps its mutation in one batched undo point; the prune action still writes no
|
||||
ext state and opens no undo point. Command-id strings are **unchanged** (FOREVER-STABLE
|
||||
contract — a reorg must not touch a shipped command id).
|
||||
**Depends on:** Q-W2 (`panel_bank_ops` is the dedupe target). Independent of Q-W3.
|
||||
|
||||
- [ ] Split → `design_view_actions` (toggle/activate/tag/untag/showBoth/moveItems),
|
||||
`bank_actions` (bank CRUD family), `prune_action` (`doBankPruneFolder` — the single
|
||||
file-deletion action).
|
||||
- [ ] Dedupe `actions.cpp`'s `promptText`/`mintBankId` + bank verbs against `panel_bank_ops`
|
||||
(one owner); do **not** change any command-id string.
|
||||
- [ ] Verify in DAW: all action families fire unchanged; one bank op = one Ctrl-Z; prune still
|
||||
no-undo/no-ext-state; CTest green.
|
||||
> **Landed on `phase-q` (2026-07-29, merge of `pq-w4-actions`). Integrated suite 61/61 green,
|
||||
> reviewed-approved.** `actions.cpp` (1019 LOC) split into `design_view_actions` / `bank_actions`
|
||||
> / `prune_action`, plus a fourth shared `action_registry` TU, all under `shell/actions/`;
|
||||
> `promptText`/`mintBankId` deduped against `panel_bank_ops`; bank verbs reshaped to promptless
|
||||
> inner verbs (one mutation home, two UX skins — panel and actions each keep their exact prior
|
||||
> UX); command-id suffixes/display phrases verified byte-identical in review; `prune_action`
|
||||
> stays a clean deletion-authority isolate (no `Undo_*`, no ext-state writes);
|
||||
> `persistBankOp`/`persistBook` gain null-session guards; `promptText` renamed `promptBankName`.
|
||||
> See `COMPLETED.md` for the full narrative.
|
||||
>
|
||||
> **Review note (🟡, resolved in Q-W6):** two session pointers / a null-session-as-model-rejection
|
||||
> misreport (unreachable today) was resolved by Q-W6's `bank_ops` lift.
|
||||
>
|
||||
> **In-DAW verification (action families, one-op-one-Ctrl-Z, prune fail-safes) is PENDING on
|
||||
> `phase-q`** — deferred by design, not yet performed.
|
||||
|
||||
## Q-W5 — split `persist.cpp` (isolate the single file-deletion authority into `prune_fs`)
|
||||
**Goal:** Split `persist.cpp` (852 LOC at the Q-W0 census — T4-04: seams unchanged; the
|
||||
pS-usage growth landed exactly where this wave isolates it; 5 responsibilities) into `session`
|
||||
(lifecycle+poll, `BeginLoadProjectState` reload hook), `ext_state_io` (the ext-state ↔ JSON
|
||||
serialization bridge + GUID minting + folder relocation), and **`prune_fs`** (prune scanning +
|
||||
`deleteOrphanFile` via `SHFileOperationW`). The split **concentrates** the byte-deleting
|
||||
authority into one obvious module — it must never spread it. **Q-W0 rider (T2-04, SETTLED
|
||||
2026-07-28):** generalize the `GetProjExtState` grow-loop retry policy into `bridge_marshal`'s
|
||||
pure decode home (or its `core/` successor) and rewire all three hand-rolled copies —
|
||||
`usage_scan`'s prune-safety-adjacent copy included. CONTEXT.md §Phase Q (persist split seams;
|
||||
deletion-authority isolation). See `docs/product/code-organization.md` §2.1, §7.
|
||||
**Verify:** CTest green at every commit. Session save/load/undo-reload, ext-state round-trip,
|
||||
folder relocation, and prune deletion all behave identically in DAW. **File deletion lives in
|
||||
exactly one module (`prune_fs`)** — the single-file-deletion-authority invariant is *improved*
|
||||
(concentrated), never diluted. Relative-paths-only persistence is unchanged.
|
||||
**Depends on:** Q-W1. Best after Q-W4 (so `prune_action` routes cleanly to `prune_fs`), but
|
||||
independently landable.
|
||||
|
||||
- [ ] Split → `session` (lifecycle/poll + `projectconfig` reload hook), `ext_state_io`
|
||||
(serialization bridge + GUID minting + folder relocation).
|
||||
- [ ] Isolate prune scanning + `deleteOrphanFile` (`SHFileOperationW`) → **`prune_fs`** — the
|
||||
one file-deletion module; nothing else may delete bytes.
|
||||
- [ ] Dedupe the `GetProjExtState` grow-loop ×3 (T2-04): one retry policy generalized from
|
||||
`bridge_marshal`; rewire `usage_scan`'s prune-safety-adjacent copy with `sample_usage_tests`
|
||||
green.
|
||||
- [ ] Verify in DAW: save/load/undo-reload/relocation/prune unchanged; deletion authority is one
|
||||
module; relative-paths-only holds; CTest green.
|
||||
> **Landed on `phase-q` (2026-07-29, merge of `pq-w5-persist`). Integrated suite 61/61 green,
|
||||
> reviewed-approved.** `persist.cpp` (853 LOC) split into `session` / `ext_state_io` / `prune_fs`
|
||||
> under `shell/persist/` + `persist_internal.h`; the file-deletion authority is concentrated —
|
||||
> `SHFileOperationW`/orphan-remove lives in exactly one anonymous-namespace function in
|
||||
> `prune_fs.cpp`, verified tree-wide; the prune fail-safe chain stays byte-intact. T2-04's
|
||||
> `GetProjExtState` grow-loop is unified as a header-only template, with all three hand-rolled
|
||||
> copies rewired (`usage_scan`'s start cap raised 4KB→64KB, allocation-only, verified
|
||||
> equivalent). The Q-W1 `bank_book_json` residual lands via a private static `nameKey`
|
||||
> (Daniel-approved option a) — `bank_book.cpp` is now ~462 LOC. `persist.h` is kept as a compat
|
||||
> umbrella for parallel safety (retired in Q-W6); deletion-authority wording is scoped precisely
|
||||
> in headers; the grow-loop gains a defensive NUL. See `COMPLETED.md` for the full narrative.
|
||||
>
|
||||
> **In-DAW verification (save/load/undo-reload, ext-state round-trip, folder relocation, prune
|
||||
> deletion) is PENDING on `phase-q`** — deferred by design, not yet performed.
|
||||
|
||||
## Q-W6 — OCP registration-table + residual fat-header (I) splits
|
||||
**Goal:** Close the last SOLID wart: replace the ~350-line hand-written **non-table** action
|
||||
registration blocks (now isolated in `app/main.cpp` after Q-W3) with a **registration table**, so
|
||||
adding an action edits one place, not four parallel ones (OCP). Split any remaining fat headers
|
||||
(`capture.h`/`persist.h`) not already resolved by their TU splits (I). (Q-W0: no reshape —
|
||||
T4-02 notes the ~385-line registration residue left in `app/main.cpp` after Q-W3 shrinks
|
||||
further under the table.) CONTEXT.md §Phase Q (OCP
|
||||
registration-table). See `docs/product/code-organization.md` §2.3, §6 (Q-6).
|
||||
**Verify:** CTest green at every commit. Every action still registers, appears in the Actions
|
||||
list, and fires via `hookcommand` exactly as before; command-id + display strings unchanged
|
||||
(FOREVER-STABLE, per-channel); unload still mirror-unregisters everything. Adding a hypothetical
|
||||
new action now touches the table only (demonstrated in review, not shipped). Remaining fat
|
||||
headers are segmented.
|
||||
**Depends on:** Q-W3 (registration code must be isolated first). Sequenced last; the most
|
||||
droppable point if the phase needs narrowing (Q-6).
|
||||
|
||||
- [ ] Convert the hand-written `Register("command_id"/"gaccel"/"hookcommand")` blocks to a
|
||||
data-driven registration table; unload mirror-unregisters from the same table.
|
||||
- [ ] Split residual fat headers (`capture.h`/`persist.h` and any other) alongside their TUs (I).
|
||||
- [ ] Verify: all actions register/fire/unregister unchanged; command-id strings untouched; CTest
|
||||
green.
|
||||
> **Landed on `phase-q` (2026-07-29). Integrated suite 61/61 green, reviewed-approved.** Action
|
||||
> registration/gaccel/hookcommand-dispatch/mirror-unregister all iterate one `ActionTableRow`
|
||||
> table (flat function-pointer dispatch, no `std::function`/virtual); adding a new action now
|
||||
> touches one table row only; `main.cpp` shrinks 653→404. FOREVER-STABLE suffixes/phrases/
|
||||
> retired-ids verified byte-identical row-by-row in review; capture rows derive their
|
||||
> suffix+phrase from the pure `captureActionTable()` (the parallel-list risk is gone by
|
||||
> construction). See `COMPLETED.md` for the full narrative.
|
||||
>
|
||||
> **Phase-end cleanup riders (landed in this wave):** `bankOp*` verbs + `persistBankOp` lifted to
|
||||
> new `shell/bank_ops` taking `ReaSamplerSession&` (dissolves the Q-W4 🟡 review note);
|
||||
> `persist.h` umbrella retired (13 callers repointed); `capture.h`'s realtime seam moved to
|
||||
> `capture_realtime_shell.h`; the `wav_trim.h` shim + its INTERFACE target deleted;
|
||||
> **`core/namespaces.h` DELETED** (the interim Q-W1 shim's contract fulfilled — ~26 includers
|
||||
> rewired); the grow-loop rehomed to `core/wire/ext_state_read.h`; a stale-comment sweep
|
||||
> (`persist.cpp`/`bank_panel.cpp` refs); CLAUDE.md's persist/bank_book/actions/wav_codec bullets
|
||||
> corrected in-wave.
|
||||
>
|
||||
> **Review-noted follow-on (not landed, deferred):** extending the table pattern to the
|
||||
> design_view/bank/ingest families' hand-registration; `channelIdFor`'s shared string-store scan
|
||||
> is correct-by-prefix-disjointness — a suffix-keyed map would make it structural, but isn't
|
||||
> required; `view_mode_model.h` (748 LOC) remains the largest header (T4-06's planner split
|
||||
> stays optional/deferred).
|
||||
>
|
||||
> **In-DAW verification (all action families, registration/fire/unregister parity) is PENDING on
|
||||
> `phase-q`** — deferred by design, not yet performed.
|
||||
|
||||
## Phase Q — sequencing
|
||||
```
|
||||
@@ -554,25 +552,34 @@ GATE: Phase S + Phase L L3 merged to dev (D2 complete, M9 abandoned) — tree qu
|
||||
("when Phase S and L3 are finished" — L1/L2/L3/L4–L7 all landed — GATE SATISFIED)
|
||||
│
|
||||
▼
|
||||
Q-W0 (audit + triage + report — COMPLETE; all 59 dispositions signed off 2026-07-28)
|
||||
│ ── SUB-GATE: satisfied once the six approved fix-now remediations land ──
|
||||
▼ (T1-01 T1-03 T1-09 T2-01a T3-01 T3-03 — in flight on pq-w0-fixes)
|
||||
Q-W0 (audit + triage + report — COMPLETE; all 59 dispositions signed off 2026-07-28;
|
||||
│ fix-now remediations LANDED 2026-07-28)
|
||||
▼
|
||||
Q-W1 (safe opener: core/json ×5 + wire codec + rect unification + relocation incl. ~20 VST
|
||||
│ pure libs under core/instrument/{engine,map,ui} + riders)
|
||||
├─► Q-W2 (split bank_panel — 8 seams) ──► Q-W4 (split actions + dedupe vs panel_bank_ops)
|
||||
├─► Q-W2v (NEW: VST god-modules — editor 8 TUs / processor 3 TUs / component_state_io;
|
||||
│ sampler_core TU whole — documented exception) [parallel with Q-W2: zero overlap]
|
||||
│ pure libs under core/instrument/{engine,map,ui} + riders — LANDED 2026-07-29)
|
||||
├─► Q-W2 (split bank_panel — 8 seams — LANDED 2026-07-29)
|
||||
│ └─► Q-W4 (split actions + dedupe vs panel_bank_ops — LANDED 2026-07-29)
|
||||
├─► Q-W2v (VST god-modules — editor 8 TUs / processor 3 TUs / component_state_io;
|
||||
│ sampler_core TU whole — documented exception — LANDED 2026-07-29)
|
||||
│ [parallel with Q-W2: zero overlap]
|
||||
├─► Q-W3 (split main — 4 hoists incl. capture_batch; + wav_codec, ICaptureBackend deletion,
|
||||
│ stamp dedupe, T1-11, capture_realtime_finalize) ──► Q-W6 (OCP registration-table)
|
||||
└─► Q-W5 (split persist; + ext-state-loop dedupe) [best after Q-W4]
|
||||
│ stamp dedupe, T1-11, capture_realtime_finalize — LANDED 2026-07-29)
|
||||
│ └─► Q-W6 (OCP registration-table — LANDED 2026-07-29)
|
||||
└─► Q-W5 (split persist; + ext-state-loop dedupe — LANDED 2026-07-29) [best after Q-W4]
|
||||
|
||||
STATUS (2026-07-29): all seven waves (Q-W0..Q-W6 incl. Q-W2v) structurally COMPLETE, 61/61
|
||||
integrated suite green. Remaining: Daniel's in-DAW verification batch, the phase-close
|
||||
CLAUDE.md architecture refresh, and the phase-q → dev merge on sign-off.
|
||||
```
|
||||
Q-W0 has run and is signed off (2026-07-28); its sub-gate closes when the six fix-now
|
||||
remediations land. W1 is the safe, high-leverage structural opener (all later waves assume the
|
||||
layout — including the T4-18 `instrument/` placement — it establishes). The god-module splits
|
||||
(W2, W2v, W3, W5) are risk-ordered and mostly parallel-safe; **Q-W2v runs parallel with Q-W2**
|
||||
(different artifact, zero file overlap — audit §4f SETTLED); W4 depends on W2's
|
||||
`panel_bank_ops`, W6 depends on W3's isolated registration code. Big-bang is rejected — every
|
||||
wave is independently landable and CTest-green.
|
||||
Q-W0 ran and closed 2026-07-28 (its six fix-now remediations landed the same day). W1 was the
|
||||
safe, high-leverage structural opener (all later waves assumed the layout — including the T4-18
|
||||
`instrument/` placement — it establishes). The god-module splits (W2, W2v, W3, W5) were
|
||||
risk-ordered and mostly parallel-safe; **Q-W2v ran parallel with Q-W2** (different artifact, zero
|
||||
file overlap — audit §4f SETTLED); W4 depended on W2's `panel_bank_ops`, W6 depended on W3's
|
||||
isolated registration code. Big-bang was rejected — every wave landed independently,
|
||||
CTest-green throughout. **All seven waves landed on `phase-q` by 2026-07-29 — Phase Q is
|
||||
structurally complete** (see the phase preamble's PHASE STATUS block for what remains before the
|
||||
phase closes and merges to `dev`).
|
||||
|
||||
## Phase Q — must-verify-before-build
|
||||
- **Q-W0 closed before any structural point** — the functional/DSP audit's findings report exists,
|
||||
|
||||
Reference in New Issue
Block a user