docs(TODO-1.0): fold second-batch answers — pitch AD becomes AHD, VELOCITY deck supersedes MASTER placement, full-height overlays with linked stereo

TODO-1.0.md

@@ -36,6 +36,15 @@ item 9 is explicitly both — a suspected regression plus a feature spec. Bugs
 are recorded compactly (symptom, expected behavior, acceptance gate) with **no
 root-cause analysis** — same no-code-reads constraint as the first batch.
 
+A **second-batch follow-up round** (2026-07-28, same day) answered items 7, 8,
+and 11. Item 7 closes clean. Item 11's answer **supersedes the original ask's
+button placement** — a new VELOCITY deck group replaces the per-section
+placement, MASTER being reserved for later post-voice-mixer concerns. Item 8's
+answer is a **spec change, not a clarification**: the pitch envelope's AD
+becomes an **AHD** (a Hold stage is added), and the doc's own prose (items 1
+and 8) is updated to match — Daniel's verbatim asks stay exactly as originally
+written.
+
 Ordering note: item 1's curve/overlay treatment explicitly anticipates item 2's
 filter envelope ("filter to be added"), and item 3 layers on both. They can land
 in sequence or together, but 1 and 2 are prerequisites for 3's full surface.
@@ -43,7 +52,8 @@ Second-batch interactions: the three bugs (4–6) are independent of the
 enhancement chain and can land at any time. Item 8 edits the same overlay
 surface as item 1 and is cheapest folded into or immediately after that work;
 item 10's per-ring reset presupposes item 1's inner dials; item 11's filter
-velocity-curve placement presupposes item 2's Filter deck; item 9's
+velocity curve presupposes item 2's filter (though its button now homes in
+item 11's own VELOCITY deck, not the Filter deck); item 9's
 loop-sustain is a Gate-mode (Staged) feature and composes with item 3's
 Gate-unavailable-in-Spline rule. Item 13 (anti-aliasing audit) touches nearly
 every surface the other items repaint — sequencing it after the layout/knob
@@ -111,13 +121,16 @@ contrast failure.
   saved before this change reopens with unchanged audible envelope behavior"
   admits no other default. Daniel prompted the question; this is the only
   answer consistent with what he has already settled.)*
-- **Segment curve values on all envelopes.** Amp AHDSR, Pitch AD, and Filter
+- **Segment curve values on all envelopes.** Amp AHDSR, Pitch AHD (AD in the
-  AHDSR all gain an editable curve value per *sloped* segment. The curve is an
+  original ask; item 8's follow-up adds the Hold stage), and Filter AHDSR all
+  gain an editable curve value per *sloped* segment. The curve is an
   exponential function; the per-segment parameter is the exponent scalar,
   range **0.1 to 10**.
 - **Which segments are sloped.** **Every stage except Hold and Sustain** — for
-  an AHDSR that is Attack, Decay, and Release; for the Pitch AD, both stages.
+  an AHDSR that is Attack, Decay, and Release; for the Pitch AHD (A→H→D since
-  *(Settled by follow-up.)*
+  item 8's spec change), Attack and Decay — its Hold, like every Hold, is flat
+  and carries no curve dial. *(Settled by follow-up; the pitch reading updated
+  for item 8's AD→AHD change.)*
 - **Linear neutral.** Exponent **1.0 is the linear neutral** (y = x^1.0 is
   linear). *(Settled by follow-up — emphatically.)*
 - **Curve editing in the overlay.** Dragging on a segment in the overlay
@@ -502,20 +515,28 @@ FX-button path remains unregressed.
 > in the waveform visual. left on top.  mono mode still shows just one channel
 > for unredundancy.
 
+**Daniel's follow-up (verbatim, 2026-07-28).**
+
+> 7) One full height; stereo linked processing, one editor
+
 **Behavior.**
 
 - In **stereo mode**, the waveform visual shows **both L and R channels, left
   on top** (two stacked lanes).
 - In **mono mode**, a single channel shows — no redundant duplicate lane.
 - The display keys off the active channel mode, per Daniel's phrasing.
+- **Overlays draw once, at full height.** Overlays that ride the waveform
+  (the envelope overlay, markers, and item 9's loop region if it lands) draw
+  **once at full height across both stacked lanes** — not per lane.
+  *(Settled by follow-up.)*
+- **Stereo processing is linked.** One editor, one set of controls governing
+  both channels — no per-channel parameter divergence, no per-channel editing
+  surface. *(Settled by follow-up.)*
 
 **Open questions.**
 
-- How overlays that ride the waveform (the envelope overlay, markers, and
+- None remaining — the overlay-layout question closed by the second-batch
-  item 9's loop region if it lands) render across the stereo split — spanning
+  follow-up round.
-  the full stacked height once, or drawn per lane. A layout call to make at
-  implementation with Daniel's eye; the product intent is only that overlays
-  stay legible and unambiguous in both modes.
 
 **Acceptance criteria.**
 
@@ -524,10 +545,15 @@ FX-button path remains unregressed.
   differs between lanes).
 - Mono mode shows exactly one lane. Switching modes updates the display
   accordingly.
+- In stereo mode, waveform-riding overlays (envelope, markers, loop region if
+  present) render once at full stacked height — no duplicated per-lane copies
+  — and stay legible across both lanes.
+- No per-channel controls appear; every edit applies identically to both
+  channels (linked stereo processing, one editor).
 
 ---
 
-## 8 — Enhancement: staged-envelope overlay — release anchored right, dragged from its top node *(his 3, second)*
+## 8 — Enhancement: staged-overlay release anchoring; the Pitch AD becomes AHD *(his 3, second)*
 
 **Daniel's ask (verbatim, 2026-07-28).**
 
@@ -538,9 +564,18 @@ FX-button path remains unregressed.
 > to sustain segment) instead of the bottom corner, which will now be anchored.
 > All staged envelope overlays should follow this policy.
 
+**Daniel's follow-up (verbatim, 2026-07-28).**
+
+> 8) For the AD... make it AHD, and the combined A H and D segment lengths
+> (time displacement) cannot exceed the full sample length.  Hold goes from 0
+> to 100%, and the visual overlay for the envelope is then 1:1 scale with the
+> waveform time.  D is not release, so it is not right anchored.
+
 **Intent.** A layout-policy change to the staged envelope overlay so it uses
 the full panel width: today, with little or no release, the sustain portion
-occupies only a small stretch and the whole figure reads off-center.
+occupies only a small stretch and the whole figure reads off-center. The
+follow-up round grew this item beyond layout: it now also carries **the spec
+change that turns the pitch envelope from AD into AHD**.
 
 **Behavior.**
 
@@ -548,19 +583,43 @@ occupies only a small stretch and the whole figure reads off-center.
 - Release is dragged from its **top node** — the node joining sustain to
   release — instead of the bottom corner. The bottom corner (the envelope's
   end point) becomes **fixed/anchored**, not draggable.
-- The policy applies to **all staged envelope overlays** — amp AHDSR today,
+- **The policy applies to the envelopes that have a release** — the amp AHDSR
-  Pitch AD, and the filter AHDSR when item 2 lands.
+  today and the filter AHDSR when item 2 lands. **It does not apply to the
+  pitch envelope: D is not a release stage, so it is not right-anchored.**
+  *(Settled by follow-up — this closes the prior open question about mapping
+  the policy onto the pitch envelope: the answer is that the policy does not
+  apply there; the envelope gains a Hold stage instead.)*
+- **Spec change: the pitch envelope becomes AHD.** The Pitch AD gains a
+  **Hold** stage: **Attack → Hold → Decay**. *(Settled by follow-up — a spec
+  change, not a clarification. The doc's own prose — here and item 1's
+  sloped-segment reading — is updated to match; Daniel's verbatim asks stay
+  as written.)*
+  - **Hold ranges 0 to 100%.** Of *what* is unstated — see Open questions.
+  - **A + H + D combined cannot exceed the sample length:** the three segment
+    lengths' total time displacement is hard-bounded by the full sample
+    length.
+  - **Because of that bound, the pitch-envelope overlay is 1:1 scale with the
+    waveform time axis** — the drawn envelope maps directly onto the
+    displayed sample's time.
 - **Cross-references.** Item 1 reworks this same overlay surface (radio
   switch, mid-segment curve knots, recolor) — this item is cheapest folded
-  into or immediately after that work. Item 3's Spline overlays are unaffected
+  into or immediately after that work; item 1's sloped-segment rule reads
-  by construction: a spline always spans the full sample width already.
+  Attack and Decay for the pitch AHD (Hold is flat, no curve dial). Item 3's
+  Spline overlays are unaffected by construction: a spline always spans the
+  full sample width already.
 
 **Open questions.**
 
-- How the policy maps onto the two-stage Pitch AD, which has no sustain or
+- **Hold's 0–100% — percent of what?** Daniel did not say: the full sample
-  release: presumably its final (decay) segment's endpoint anchors right and
+  length, the time remaining after Attack, or something else. A narrow Daniel
-  drags from its top node, but Daniel stated the policy in AHDSR terms —
+  call — do not assume at implementation.
-  confirm the AD reading at implementation.
+- **Are the 1:1-overlay property and the A+H+D ≤ sample-length bound
+  pitch-specific, or intended for all staged envelopes?** Daniel stated both
+  in the pitch-AHD context. An AHDSR with a right-anchored release cannot be
+  strictly 1:1 across an indefinite sustain, so the two policies appear to
+  coexist (right-anchoring for envelopes with a release; the 1:1 time-bounded
+  overlay for the pitch AHD) rather than merge — but that is an open reading
+  to confirm, not a settled conclusion.
 
 **Acceptance criteria.**
 
@@ -568,8 +627,14 @@ occupies only a small stretch and the whole figure reads off-center.
   right edge — the overlay reads full-width, not bunched left.
 - Dragging the sustain→release top node adjusts release; the bottom-right
   corner is fixed and not draggable.
-- Every staged envelope overlay (amp, pitch, and filter once present) follows
+- The envelopes with a release (amp, and filter once present) follow the same
-  the same anchoring policy.
+  anchoring policy; the pitch envelope's Decay is **not** right-anchored.
+- The pitch envelope plays and displays three stages — Attack, Hold, Decay —
+  with Hold spanning 0–100% of its (to-be-confirmed) reference; no
+  combination of A, H, and D settings yields a combined time displacement
+  exceeding the sample length.
+- The pitch-envelope overlay is 1:1 with the waveform's time axis: a stage
+  boundary at N seconds sits over the waveform at N seconds.
 
 ---
 
@@ -660,7 +725,7 @@ playback cycling the loop until note-off, then release.
 
 ---
 
-## 11 — Enhancement: preview glyph; velocity-curve buttons per section; bipolar pitch/filter curves *(his 6)*
+## 11 — Enhancement: preview glyph; VELOCITY deck for velocity-curve buttons; bipolar pitch/filter curves *(his 6)*
 
 **Daniel's ask (verbatim, 2026-07-28).**
 
@@ -672,6 +737,13 @@ playback cycling the loop until note-off, then release.
 > velocity transfer functions default to y=0 and y range is [-1,1] (where as
 > amp stays unipolar at [0,1]).
 
+**Daniel's follow-up (verbatim, 2026-07-28).**
+
+> 11) actually, that is a real contention point... MASTER is for other things,
+> post voice mixer (I will add to this later).  The velocity popup buttons
+> should all go together in a new control deck group labelled VELOCITY, to the
+> left of VOICE
+
 **Behavior.**
 
 - **Preview glyph.** The preview button's inner text is replaced with a glyph.
@@ -679,38 +751,50 @@ playback cycling the loop until note-off, then release.
   "audition" read. Daniel's constraint: **no new dependencies** — a statically
   embedded bitmap or equivalent that plays nicely with the existing drawing
   path is fine.
-- **Velocity-curve button placement.** Amp velocity curve button → **MASTER**
+- **Velocity-curve button placement — the VELOCITY deck.** All three
-  section; pitch velocity curve → **PITCH** section; filter velocity curve →
+  velocity-curve popup buttons (amp, pitch, filter) live **together in a new
-  **Filter** section (the deck item 2 creates).
+  control deck group labelled "VELOCITY", placed to the left of the VOICE
+  group**. *(Settled by follow-up.)* Note for readers of the prior revision:
+  this **supersedes the original ask's per-section placement** (amp → MASTER,
+  pitch → PITCH, filter → Filter). Daniel confirmed the MASTER placement was
+  a real contention point — **MASTER is reserved for other, post-voice-mixer
+  concerns** (he will add to it later), so the velocity curves do not belong
+  there.
+- **Storage stays per-zone.** The velocity transfer curves are stored
+  **per-zone**, with the other playback parameters — Sample/Zone panel parity
+  applies. *(Derived, not a Daniel quote: the storage doubt existed only
+  because the proposed MASTER placement implied per-instance storage; with
+  the buttons in their own VELOCITY group that doubt is gone, and the
+  project's settled convention — playback parameters are per-zone, VOICE and
+  MASTER the per-instance exceptions — decides it.)*
 - **Bipolar pitch/filter transfer functions.** Pitch and filter velocity
   transfer functions are **bipolar: y range [−1, 1], default y = 0** — flat at
   zero, meaning velocity modulation of pitch and filter is **off until the
   user draws a curve**. **Amp stays unipolar at [0, 1]**, and its existing
   flat default (every velocity → unity) is unchanged.
-- **Cross-references.** Item 2 introduces the filter's velocity modulation and
+- **Cross-references.** Item 2 introduces the filter's velocity modulation —
-  the Filter deck — this item specifies that curve's domain, default, and
+  this item specifies that curve's domain and default, and homes its button
-  button placement. Item 3's shared spline editor serves these curves, so it
+  in the VELOCITY deck. Item 3's shared spline editor serves these curves, so
-  must render and edit a **bipolar y-domain** for pitch and filter alongside
+  it must render and edit a **bipolar y-domain** for pitch and filter
-  the amp curve's unipolar one.
+  alongside the amp curve's unipolar one.
 
 **Open questions.**
 
 - Whether a user-facing pitch velocity transfer curve already exists or is
   introduced by this item — unverifiable here under the no-code-reads
-  constraint; if absent, this item introduces it.
+  constraint; if absent, this item introduces it. (The former second question
-- The amp velocity curve's *button* moves to MASTER, but MASTER is settled as
+  — amp-curve storage under the MASTER placement — dissolved with the
-  a per-instance group while the velocity curve is a playback parameter. Does
+  placement's supersession; storage is settled per-zone above.)
-  the move imply the amp velocity curve becomes per-instance, or is it a
-  purely spatial relocation with storage unchanged? This also touches
-  Sample/Zone panel parity (which surfaces show the button). Needs a Daniel
-  call before implementation.
 
 **Acceptance criteria.**
 
 - The preview button shows the glyph (no text) and stays legible in all
   interaction states; no new build or runtime dependency is introduced.
-- The three velocity-curve buttons sit in their named sections: amp in MASTER,
+- The three velocity-curve buttons sit together in a deck group labelled
-  pitch in PITCH, filter in Filter.
+  **VELOCITY**, immediately to the left of the VOICE group; no velocity-curve
+  button appears in MASTER, PITCH, or Filter.
+- The velocity curves follow Sample/Zone panel parity and persist per-zone
+  (two zones with different curves audibly differ).
 - Opening the pitch or filter curve shows a bipolar editor ([−1, 1]) defaulted
   flat at y = 0; played velocities produce no pitch/filter modulation until a
   curve is drawn, then audibly follow it.