@thedecipherist/claude-packs 0.0.0-stage → 1.0.0

package/packs/audio-core/rules/filters-stable-under-modulation.md

@@ -0,0 +1,29 @@
+---
+# concepts: dsp
+paths:
+  - "placeholder"
+---
+
+# Modulated filters stay stable and accurate under audio-rate modulation
+
+<constraints>
+Always do:
+- Use a structure that stays stable under fast modulation for any filter the matrix, envelopes or LFOs can move: a trapezoidal (TPT/ZDF) SVF or ladder. Morph LP > BP > HP > notch by interpolating the *output mix* of one structure.
+- Prewarp: `g = tan(π · fc / fs)`. Clamp `fc ≤ 0.49 · fs` before the `tan`.
+- Recompute coefficients per sample when the cutoff is modulated (a fast `tan` approximation is fine if its error is ≤ 0.1% up to 0.45 · fs).
+- Clamp resonance to its documented self-oscillation range. Give any zero-delay-feedback solver a fixed maximum iteration count and a fallback to the last estimate.
+
+- Count anything a push, comet, note or thread can move as modulated. That includes Stellix's floor EQ handles (spec 7.2), which comets and notes bend by formula, so the EQ needs a modulation-safe structure (e.g. Cytomic SVF bell and shelf responses), not static biquads.
+
+Never do:
+- Use direct-form biquads for modulated filters. They're fine for static EQ only.
+- Change filter type by switching or crossfading between different filter structures.
+</constraints>
+
+## Why
+Cytomic's trapezoidal SVF stays stable and smooth when cutoff, Q and mix move at audio rate. In float32 its error on a 20 Hz bell is about −111 dB, against about −59 dB for a direct-form biquad (Cytomic, "SVF vs DF1"). Direct-form coefficients are most sensitive at low cutoff, where the poles crowd near z = 1.
+
+## Check
+- Sweep the cutoff 20 Hz ↔ 18 kHz with a 2 kHz sine LFO at maximum resonance for 10 s. Pass: every sample finite, peak ≤ +24 dBFS (house choice).
+- Set fc = 0.4 · fs and measure the peak or −3 dB frequency. Pass: within ±1%. Passing fc = fs/2 and fc = 2 · fs gives finite coefficients.
+- If an existing proven filter (such as Solera's) passes these, it stays as it is. The tests are the law, not a particular structure.

package/packs/audio-core/rules/host-parameters-at-scale.md

@@ -0,0 +1,24 @@
+---
+# concepts: params
+paths:
+  - "placeholder"
+---
+
+# Host parameters stay bounded, collision-free, and recorded as gestures
+
+<constraints>
+Always do:
+- Keep the exported parameter count bounded (house cap: about 2048). For Stellix, export generic slot parameters (4 slots × a fixed number of moon slots, with meaning taken from the planet's kind) rather than the union of every kind's moons. IDs stay fixed and the count stays bounded.
+- Test that no two parameter IDs collide after hashing. JUCE's VST3 ID is `String::hashCode() & 0x7fffffff` (with Studio One compatibility); the AU ID is the unmasked hash. Both wrappers only `jassert` on a collision.
+- Wrap every drag: `beginChangeGesture()` on mouse-down, `setValueNotifyingHost()` while dragging, `endChangeGesture()` on mouse-up, so hosts record automation cleanly.
+- Mark internal or derived values non-automatable, or keep them out of host parameters entirely.
+- Put parameters in groups (`AudioProcessorParameterGroup`) by slot and planet, so host lists stay navigable.
+
+Never do:
+- Change an exported ID string after release (the `parameter-ids-never-change` lock guards this).
+- Export per-kind moons whose existence depends on the slot's current kind.
+</constraints>
+
+## Check
+- Test: every exported ID's VST3 and AU hash is unique, and the count is within the cap.
+- pluginval at strictness 10, and `auval -v` finishing in under 30 s (VST time).

package/packs/audio-core/rules/house-control-behaviours.md

@@ -0,0 +1,34 @@
+---
+# concepts: ui, painter
+paths:
+  - "placeholder"
+---
+
+# Every control behaves the house way
+
+Taken from Solera and MegaSynth. Stellix shipped without double-click reset (B-163) because no list said what a control must do, and
+later with dropdowns that stepped instead of opening and a page where only one control worked (B-210, B-211), because the gates walked
+INIT and never pressed a dropdown.
+
+<constraints>
+Always do:
+- Give every control (knob, slider, switch, segmented button, drag handle, and any on-screen object that holds a value) all of these, built once in the shared control piece:
+  1. Double click returns it to its parameter's default, the value INIT gives it.
+  2. Fine drag with a modifier key (Shift on Mac and Windows) for small steps.
+  3. The mouse wheel moves it by a fixed step.
+  4. Its value is readable while it is moved, in the parameter's own value-to-text.
+  5. It never takes keyboard focus, so the computer keyboard keeps playing notes.
+  6. One gesture is one undo step.
+- Give every choice control (dropdown, select, menu, any control drawn with a chevron or that holds one of a list of values) a real list:
+  a press opens the list with every choice and the current one marked; choosing one sets it, and Escape or a press outside closes it.
+  It never steps to the next value on a press. The ‹ › arrows beside a list may step, as their own controls.
+- Check a new or changed control against this list with the `new-panel-control` skill, and walk one control of each template through the real window in the behaviour gate.
+- Walk one control of each template in the real window, on a loaded patch and not only on INIT: it moves its value and the sound or
+  the picture, and a choice control opens its list. Prove the rest by a read, not a walk (`test-the-template-once`): a table check that every
+  control is built from its template and its binding reaches a live parameter, which is what catches a control wired to nothing. The gate is red on a planted control that does nothing and on a planted dropdown
+  that steps instead of opening.
+- When a project's reference synth (Solera, MegaSynth) does a behaviour differently, copy it and write down what was copied.
+
+Never do:
+- Draw a control by hand on one page instead of using the shared piece.
+- Give one page a behaviour the others lack.

package/packs/audio-core/rules/math-domain-guards.md

@@ -0,0 +1,19 @@
+---
+# concepts: dsp, world
+paths:
+  - "placeholder"
+---
+
+# Math functions are only ever given values inside their domain
+
+<constraints>
+Always do:
+- `sqrt(std::max(0.0, x))`, `std::log(std::max(x, tiny))`, `acos` and `asin` on `std::clamp(x, -1, 1)`, and `x / d` only when `|d| > eps`, with a defined result otherwise.
+- Handle the 0/0 cases explicitly: `sinc(0) = 1`, limiter or compressor gain after silence, RMS of an empty window.
+
+Never do:
+- Feed a parameter-derived value straight into `log`, `sqrt`, `pow` with a negative base, or a division.
+</constraints>
+
+## Check
+Test: sweep every parameter to its extremes (cutoff 1 Hz and Nyquist − 1, gain +24 dB, resonance max, time 0) with silence, full-scale noise, a 1 Hz sine and a Nyquist-rate sine as input. Pass: all output finite.

package/packs/audio-core/rules/modulated-delay-interpolation.md

@@ -0,0 +1,22 @@
+---
+# concepts: dsp
+paths:
+  - "placeholder"
+---
+
+# Modulated delays read with a proper interpolator
+
+<constraints>
+Always do:
+- Read chorus, flanger, vibrato and modulated delay taps with cubic or Lagrange-3 interpolation, or better.
+- Inside reverb tanks, allpass interpolation is allowed, since the pitch change there is tiny.
+- Add the interpolator's own latency to the delay time. Signalsmith's figures: linear 0, cubic 1, Lagrange-n (n−1)/2.
+- Size every delay line for its maximum time plus the interpolator's extra taps, at the highest sample rate, in `prepareToPlay`.
+
+Never do:
+- Read a moving tap with nearest-sample lookup (zipper noise).
+- Use linear interpolation where its high-frequency loss matters: it adds time-varying low-pass filtering (Dattorro 1997, §1.3.7).
+</constraints>
+
+## Check
+Delay a 10 kHz sine at 48 kHz by 10.5 samples. Linear interpolation loses about 2.0 dB; 4-point Lagrange or Catmull-Rom about 0.54 dB. Pass (house choice): ≤ 0.6 dB loss for chorus and flanger.

package/packs/audio-core/rules/multiband-phase-coherent.md

@@ -0,0 +1,22 @@
+---
+# concepts: dsp
+paths:
+  - "placeholder"
+---
+
+# Multiband splits sum back flat, and dynamics detect in the log domain
+
+<constraints>
+Always do:
+- Split bands with 4th-order Linkwitz-Riley crossovers (two cascaded 2nd-order Butterworth sections). With 3 bands, run the low band through the second split's allpass, so the bands sum back flat in magnitude and coherent in phase.
+- Detect level in dB: peak or RMS (about 10 ms), with attack and release one-pole smoothing applied in the dB domain and a soft knee (Giannoulis, Massberg & Reiss, JAES 2012).
+- Move crossover points with the same modulation-safe rules as filters, since crossover moons can be pushed.
+
+Never do:
+- Split bands with plain Butterworth or first-order filters whose sum isn't flat.
+- Smooth gain in the linear domain (uneven attack and release across levels).
+</constraints>
+
+## Check
+- Test: with zero gain in every band, the summed output is flat within ±0.01 dB from 20 Hz to 20 kHz.
+- Test: sweep a crossover point 10 octaves per second. No clicks (no sample jump over the smoothing threshold) and no NaN.

package/packs/audio-core/rules/nonlinear-stages-antialiased.md

@@ -0,0 +1,28 @@
+---
+# concepts: dsp
+paths:
+  - "placeholder"
+---
+
+# Nonlinear stages are antialiased, except deliberate crushers
+
+<constraints>
+Always do:
+- Give every static nonlinearity (drive, tanh, clipper, wavefolder, HEAT-style saturation) first-order ADAA, `(F(x[n]) − F(x[n−1])) / (x[n] − x[n−1])` with antiderivative F chosen so F(0) = 0, plus at least 2x oversampling. Use more oversampling where measurement says so.
+- Handle the ill-conditioned case: when `|x[n] − x[n−1]| < eps`, use `f((x[n] + x[n−1]) / 2)`.
+- Oversample only the nonlinear "island", not the whole chain. Pick the smallest factor the measurement allows: host rate, then 2x, then 4x, then 8x only with evidence.
+- Use ADAA only on memoryless curves (tanh, soft clip, folder). Stages with memory (envelopes, feedback) need oversampling instead.
+- Count ADAA's half-sample delay in the latency of that path. Inside a filter feedback loop, absorb it structurally (Parker, Zavalishin & Le Bivic, DAFx-16 §6.1). Never drop ADAA into a loop as-is.
+- Treat bit reduction and sample-rate reduction (FireBloom's BITS, the BIT effect) as *intended* aliasing: run them at host rate without oversampling, feed them an already band-limited signal, and follow them with a DC blocker.
+
+Never do:
+- Run a hard clipper or folder at the base rate with no ADAA or oversampling.
+</constraints>
+
+## Why
+In DAFx-16 Table 1, a hard clipper at gain 10 needs 12x oversampling alone to reach about 46.7 dB SNR; first-order ADAA gets there at about 4x.
+
+## Check
+- `tone-report` on sine probes at 1, 3, 5 and 7 kHz (plus 10 kHz at 96 kHz) through the stage at gain 10. A 1 kHz probe alone hides aliasing. Pass (house choice): SNR ≥ 45 dB at every probe.
+- Unit test: constant input, and x[n] == x[n−1], give finite output equal to f(x) within 1e−6.
+- Crushers: golden-file test per sample rate, and full resolution at rate 1 returns the input unchanged.

package/packs/audio-core/rules/note-ledger-and-pedals.md

@@ -0,0 +1,22 @@
+---
+# concepts: audio
+paths:
+  - "placeholder"
+---
+
+# Every note-on owes a note-off: one ledger tracks them all
+
+<constraints>
+Always do:
+- Keep one note ledger with a state per voice: held, sustained, sostenuto, releasing. Every note started by anyone (keys, DOUBLE/TRIPLE extras, arp, HARMONY answers, BEATS) is entered in it.
+- Sustain (CC64 ≥ 64 down): a note-off while the pedal is down marks the note sustained, and pedal-up releases it. Sostenuto (CC66) latches only the notes down at the moment it's pressed.
+- Flush the ledger (release every voice) on CC123 all-notes-off, CC120 all-sound-off, transport stop, `releaseResources`, patch load, reset and bypass.
+- Use JUCE's `MPEInstrument` only as the parser and note tracker for MPE; keep the house 96-voice allocator. Smooth per-note pressure and slide (about 5 ms one-pole per note).
+
+Never do:
+- Start a note anywhere without going through the ledger.
+- Let a generated note (arp, harmony, double) outlive the key or event that started it without a scheduled note-off.
+</constraints>
+
+## Check
+Fuzz test: random streams of notes, CC64/CC66, CC120/CC123 and patch loads. At the end, every voice is idle and the ledger is empty. With MPE input, each voice's pressure follows only its own channel.

package/packs/audio-core/rules/one-formula-per-value.md

@@ -0,0 +1,20 @@
+---
+# concepts: dsp, params, ui
+paths:
+  - "placeholder"
+---
+
+# A value the user sees and the sound uses comes from one formula
+
+<constraints>
+Always do:
+- Put each mapping (normalized value to Hz, dB, ms, ratio, semitones, note name, tempo-synced time) in one function, and call that same function from the DSP, the display text and the host's value-to-text.
+- When a mapping changes, change it in that one place, and add a test that checks DSP and display agree at the ends and in the middle of the range.
+
+Never do:
+- Re-derive a display value in the editor ("cutoff = 20 * pow(1000, v)") next to a different formula in the DSP.
+- Round or clamp differently in the display than in the sound.
+</constraints>
+
+## Check
+`trace-parameter` reports any second formula it finds for the same value.

package/packs/audio-core/rules/optimisations-are-null-tested.md

@@ -0,0 +1,23 @@
+---
+# concepts: dsp, tests, bench
+paths:
+  - "placeholder"
+---
+
+# Every optimisation and refactor of DSP is proven by a null test
+
+<constraints>
+Always do:
+- Before changing DSP code for speed or structure, save reference renders (golden files) of fixed test patches: notes, sweeps, every row of the matrix moving.
+- After the change, render again and require a bit-identical result. If an exact match is impossible, report the maximum difference in dBFS and accept it only below a stated threshold (house choice: ≤ −120 dBFS for a pure refactor).
+- Build DSP blocks so they don't depend on the parameter tree: they take a plain parameter struct, so the same sources compile into the plugin, the test executable and the Release benchmark target.
+- Keep a "sound revision" string that changes only when the sound changes, separate from the state schema version. A changed sound gets new golden files *on purpose*, logged in the bugs/changes file.
+
+Never do:
+- Call a change "faster" or "the same sound" without both a benchmark and a null test.
+- Regenerate golden files to make a failing null test pass, unless the sound change was intended and is logged.
+</constraints>
+
+## Check
+- A CTest render-diff test compares against the golden files.
+- `.claude/checks/dsp-without-apvts.json` blocks DSP folders from reaching into the parameter tree.

package/packs/audio-core/rules/oscillators-bandlimited.md

@@ -0,0 +1,23 @@
+---
+# concepts: dsp
+paths:
+  - "placeholder"
+---
+
+# Oscillator edges are band-limited
+
+<constraints>
+Always do:
+- Correct every discontinuity (saw reset, pulse edge, hard-sync reset, and each of a supersaw's stacked saws) with a band-limiting method: PolyBLEP at minimum; 4th-order B-spline polyBLEP, minBLEP or mipmapped wavetables for the top octaves.
+- Keep the phase accumulator and its increment in `double`.
+- It depends on what is being built. On an original design, the default stays clean. On a reproduction (`guards.instrument.kind`), the machine is the spec: a naive saw is the instrument, with its source cited and a golden-file test.
+
+Never do:
+- Write a naive `phase * 2 - 1` saw or `phase < pw` pulse straight to the output.
+</constraints>
+
+## Why
+Välimäki, Pekonen & Nam (JASA 2012) measured how far up each method stays alias-free at 44.1 kHz: 2nd-order PolyBLEP to about 2.1 kHz fundamental, 4th-order Lagrange to about 5.1 kHz, 4th-order B-spline to about 7.8 kHz. Above that, a better method or oversampling is needed.
+
+## Check
+Render 2 s of the oscillator at 48 kHz with f0 = 110, 1000, 2000 and 4186 Hz, then run `node .claude/tools/tone-report.mjs <wav> <f0>`. Pass (thresholds are a house choice): the largest non-harmonic peak is below −60 dB re the fundamental up to 2 kHz, and below −40 dB at 4186 Hz.

package/packs/audio-core/rules/output-limiter.md

@@ -0,0 +1,23 @@
+---
+# concepts: dsp
+paths:
+  - "placeholder"
+---
+
+# The output limiter never lets a sample past its ceiling and reports its latency
+
+<constraints>
+Always do:
+- Compute gain as the minimum over the look-ahead window with a sliding-window minimum (monotonic deque, O(1) per sample), then smooth the release.
+- Link stereo: detect on max(|L|, |R|).
+- Report the latency once, as a constant: `setLatencySamples(round(0.001 · fs) + oversamplerLatency)` in `prepareToPlay`.
+- If the ceiling is ever advertised as dBTP, detect true peak with 4x oversampling (ITU-R BS.1770). A sample-peak limiter can overshoot by about 0.5 dB between samples.
+
+Never do:
+- Make the ceiling or look-ahead user controls (house law: −0.3 dBFS, 1 ms).
+- Change the reported latency while running.
+</constraints>
+
+## Check
+- Test: a sweep plus an inter-sample-peak signal (fs/4 sine at 45° phase). Max sample ≤ −0.3 dBFS; if dBTP is claimed, true peak at 4x ≤ the ceiling.
+- Null test: with the limiter idle, output minus input delayed by the reported latency is silent.

package/packs/audio-core/rules/parameter-ids-never-change.md

@@ -0,0 +1,20 @@
+---
+# concepts: params
+paths:
+  - "placeholder"
+---
+
+# Parameter and control IDs never change once assigned
+
+<constraints>
+Always do:
+- Give every parameter a `juce::ParameterID { "id", versionHint }`. A newly added parameter gets the current version hint.
+- Store and recall everything by ID, never by position or index, so lists can be reordered or sorted without breaking patches.
+- When a control's meaning changes, add a new ID and migrate old patches in `setStateInformation`. The old ID stays readable.
+
+Never do:
+- Rename, reuse or delete an existing ID. Saved patches, host automation and every preset bank refer to it.
+</constraints>
+
+## Check
+`.claude/hooks/param-id-lock.mjs` (PostToolUse) collects every parameter ID in the repo and compares it with `.claude/param-ids.lock.json`. A locked ID that disappeared fails the edit with the list of missing IDs. New IDs are added to the lock automatically. Run `node .claude/hooks/param-id-lock.mjs --init` once per repo to create the lock. It reads `juce::ParameterID` and `AudioParameter*` declarations in C++ by default. If control IDs also live in `panel.json`, add `.claude/param-ids.config.json` with `"extensions"` and `"patterns"` (regexes with one capture group) to cover them.

package/packs/audio-core/rules/params-and-state-thread-safe.md

@@ -0,0 +1,19 @@
+---
+# concepts: params
+paths:
+  - "placeholder"
+---
+
+# Parameters and state are safe to touch from any host thread
+
+<constraints>
+Always do:
+- Assume hosts call `setValue` on parameters from background threads while audio runs, and call `getStateInformation`/`setStateInformation` off the message thread.
+- Make every value shared between those paths atomic, or copy it through the lock-free handoff.
+
+Never do:
+- Change the process locale (`setlocale`, `std::locale::global`). It breaks number formatting inside the host. (`.claude/checks/no-locale-change.json` blocks it.)
+</constraints>
+
+## Check
+ThreadSanitizer test: N threads set parameters and save state in a loop while the audio thread renders. Pass: no TSan reports, and `setlocale(LC_ALL, nullptr)` is unchanged after plugin init.

package/packs/audio-core/rules/params-snapshot-per-block.md

@@ -0,0 +1,21 @@
+---
+# concepts: audio
+paths:
+  - "placeholder"
+---
+
+# Each block reads its parameters once, into a plain snapshot
+
+<constraints>
+Always do:
+- At the start of each block, copy the parameters into a plain-data snapshot with relaxed atomic loads. Use a dirty bitset set by `parameterValueChanged`, so only changed values are copied when there are thousands.
+- Make the world, the voices and the DSP read only from that snapshot within the block, so every value is consistent for the whole block and the world stays deterministic.
+- Ramp continuous values inside the block with the per-sample smoothers.
+
+Never do:
+- Read parameter atomics directly in the middle of the world tick or a voice loop. A host write mid-block makes one block see two values.
+</constraints>
+
+## Check
+- ThreadSanitizer stress test: the UI and host automation write 4k parameters while audio renders. No races.
+- `juce-realtime-audit` reports no parameter reads outside the snapshot step.

package/packs/audio-core/rules/patch-excludes-performance-controls.md

@@ -0,0 +1,18 @@
+---
+# concepts: params
+paths:
+  - "placeholder"
+---
+
+# A patch stores every setting except the performance controls
+
+<constraints>
+Always do:
+- Store every sound setting in a patch, effect choices included (reverb room, delay program, routing).
+
+Never do:
+- Store MAIN volume, octave, the mod wheel or the pitch wheel in a patch. Those belong to the player and the session, not the sound, so loading a patch never changes them.
+</constraints>
+
+## Check
+Test: set MAIN volume, octave, mod wheel and pitch wheel to non-default values, save a patch, change all four again, and load the patch. Assert all four kept their current values and that none of the four IDs appear in the saved data.

package/packs/audio-core/rules/per-sample-code-inlinable.md

@@ -0,0 +1,22 @@
+---
+# concepts: dsp, audio
+paths:
+  - "placeholder"
+---
+
+# Per-sample code can be inlined: no virtual calls per sample
+
+<constraints>
+Always do:
+- Dispatch by type once per block (or once per voice per block), then run a tight, non-virtual per-sample loop. Oscillator type, filter mode and effect choice are switched at block level.
+- Use templates, `final` classes, or a `switch` over a small enum hoisted outside the sample loop when one interface has several implementations.
+- Keep per-voice state contiguous (struct-of-arrays or one array of voice structs), not pointers to separately allocated objects.
+
+Never do:
+- Call a `virtual` function, a `std::function`, or through a function pointer inside the per-sample loop of 96 voices.
+- Use `-march=native` in a build you ship. Users' CPUs differ from yours. (`.claude/checks/no-march-native.json` blocks it.)
+</constraints>
+
+## Check
+- The benchmark from `cpu-worst-case-per-block.md` shows the gain when the loop is restructured; keep the faster version only if its null test passes.
+- Manual review: grep the per-sample loops for `->` calls on interface pointers.

package/packs/audio-core/rules/prepare-is-repeatable.md

@@ -0,0 +1,23 @@
+---
+# concepts: audio, dsp
+paths:
+  - "placeholder"
+---
+
+# `prepareToPlay` can run any number of times and always leaves a clean state
+
+<constraints>
+Always do:
+- Treat `prepareToPlay` as callable repeatedly, with or without `releaseResources` in between, and with a new sample rate or block size each time.
+- Re-prepare and reset every DSP object unconditionally: filters, delay lines, reverb tanks, smoothers (`reset(sampleRate, ramp)`), voices and oversamplers.
+- Size scratch buffers with margin for blocks larger than announced, and split larger blocks internally.
+
+Never do:
+- Skip work because "already prepared". A changed rate must rebuild everything rate-dependent.
+- Leak or double-allocate when `prepareToPlay` is called twice without `releaseResources`.
+</constraints>
+
+## Check
+Tests:
+1. Prepare at 48 kHz/512, then 96 kHz/64, then 44.1 kHz/1024 with no release in between. Render each time; pass when the output matches a freshly constructed processor and ASan reports no leaks.
+2. Prepare at N, process blocks of 2N under ASan. Pass: no reports.

package/packs/audio-core/rules/recursive-state-nan-guard.md

@@ -0,0 +1,20 @@
+---
+# concepts: dsp
+paths:
+  - "placeholder"
+---
+
+# A NaN or Inf can never live in recursive state
+
+<constraints>
+Always do:
+- Once per block, check the state of every recursive structure (filter integrators, delay feedback, reverb tank, ZDF solver) with `std::isfinite`. On failure, reset that state (or the whole voice) to zero, and bump a debug counter.
+- Debug builds: `jassert(std::isfinite(x))` after each stage of a voice.
+
+Never do:
+- Rely on `std::clamp`, `jlimit` or a soft clipper to remove a NaN. They pass NaN through unchanged.
+- Zero only the output while a NaN stays in a filter state. It keeps re-emerging forever.
+</constraints>
+
+## Check
+Test: inject a NaN into a filter state mid-block. Pass: the next block's output is finite and the reset counter went up by one.

package/packs/audio-core/rules/reverb-loop-gain-bounded.md

@@ -0,0 +1,24 @@
+---
+# concepts: dsp
+paths:
+  - "placeholder"
+---
+
+# Reverb feedback can never exceed unity gain
+
+<constraints>
+Always do:
+- Make FDN mixing matrices orthogonal (unitary). Keep per-line gains below 1, computed from RT60 per line length: `g = 10^(−3 · L / (fs · T60))`. Damping filters have |H| ≤ 1 at every frequency.
+- Keep allpass and lattice coefficients within [0, 0.9999999].
+- Use mutually prime delay lengths, scaled by sample rate.
+- Modulate tank delays slowly (around 1 Hz, quadrature LFOs) with small excursion. Dattorro's plate uses 16 samples at 29761 Hz, scaled to fs.
+- Make freeze/infinite mode exactly unity gain with the unitary check, never "slightly above 1".
+
+Never do:
+- Tune a "bigger" hall by raising feedback toward or past 1. Lengthen the lines or change the damping.
+</constraints>
+
+## Check
+- Unit test: for random vectors x, the norm of M·x equals the norm of x to within 1e-6.
+- At maximum decay, impulse-response energy in successive 100 ms windows must never rise after 200 ms.
+- Measured RT60 within ±10% of the setting (house choice).

package/packs/audio-core/rules/sample-accurate-midi.md

@@ -0,0 +1,22 @@
+---
+# concepts: audio
+paths:
+  - "placeholder"
+---
+
+# MIDI events land on their exact sample
+
+<constraints>
+Always do:
+- Render the block in segments split at each MIDI event's `samplePosition`: render up to the event, apply it, continue. (`juce::Synthesiser::renderNextBlock` does this; a custom voice manager must do the same.)
+- Apply note-on, note-off, pitch bend, mod wheel, aftertouch and CC at their offset, not at the block start.
+
+- Generate MIDI (arp, WaveArp, matrix notes) into a member `MidiBuffer` pre-sized with `ensureSize()` in `prepareToPlay`, then `swapWith` the host buffer.
+
+Never do:
+- Add to a `MidiBuffer` while iterating over it.
+- Loop over the `MidiBuffer` first and then render the whole block. Every note then snaps to the block start, so timing jitter grows with buffer size and arps or matrix retriggers drift.
+</constraints>
+
+## Check
+Test: send a note-on at sample offset 100 in a 512-sample block, and assert the first non-zero output sample is at index 100 (± the voice's known attack latency). Repeat at block sizes 64 and 2048.

package/packs/audio-core/rules/sample-rate-and-block-size-from-host.md

@@ -0,0 +1,23 @@
+---
+# concepts: audio, dsp
+paths:
+  - "placeholder"
+---
+
+# Sample rate and block size always come from the host
+
+<constraints>
+Always do:
+- Derive every time-based value (delay samples, LFO increments, envelope coefficients, smoothing ramps, tempo-synced rates) from the `sampleRate` given to `prepareToPlay()`, and recompute it there.
+- Handle any `buffer.getNumSamples()`, including 0, and blocks of varying size on every call.
+- Program defensively for a block *larger* than `maximumExpectedSamplesPerBlock`: process it in chunks no bigger than what you prepared. JUCE's own docs warn that buggy hosts can exceed it.
+- Test at 44.1, 48, 96 and 192 kHz.
+
+Never do:
+- Write `44100`, `48000`, `96000` (or `44100.0f` etc.) in DSP code as a rate.
+- Assume the block size equals the prepared maximum, or is a power of two.
+</constraints>
+
+## Check
+- The realtime-guard hook flags literal sample rates inside audio-thread bodies.
+- Test: render the same patch at 44.1 and 96 kHz and assert that the delay time in milliseconds and the LFO period in milliseconds match. Render with block sizes 1, 7, 64 and 4096 and assert identical output.

package/packs/audio-core/rules/scoped-no-denormals.md

@@ -0,0 +1,26 @@
+---
+# concepts: audio
+paths:
+  - "placeholder"
+---
+
+# Every `processBlock` starts with `ScopedNoDenormals`
+
+<constraints>
+Always do:
+- Make `juce::ScopedNoDenormals noDenormals;` the first line of every `processBlock` (and `processBlockBypassed` if it processes audio).
+
+- Use `ScopedNoDenormals` on *every* thread that runs DSP: worker threads that render voices, offline renders, and test and benchmark executables. The flag belongs to one thread only.
+- Define `JUCE_DSP_ENABLE_SNAP_TO_ZERO=0` in CMake. JUCE's `JUCE_SNAP_TO_ZERO` only does anything on Intel (it's a no-op on Arm), so `juce::dsp` filters otherwise give block-size-dependent output on x86 and not on Apple Silicon.
+
+Never do:
+- Rely on calling `FloatVectorOperations::disableDenormalisedNumberSupport()` in `prepareToPlay()`. It sets the flush-to-zero flags of the CPU register on the *calling* thread (JUCE source: MXCSR on Intel, FPCR on Arm), and hosts may call `prepareToPlay` on a different thread from the audio callback.
+- Add tiny DC offsets (`+ 1e-20f`) as the denormal fix in new code. Use the scoped flag; it covers every filter, reverb tank and feedback path at once.
+</constraints>
+
+## Why
+Decaying feedback (reverb tails, filter states, delay feedback after the note stops) drifts into denormal range, and on some CPUs each denormal operation is many times slower. The symptom is a CPU spike when the sound goes *quiet*.
+
+## Check
+- The realtime-guard hook blocks any edit that leaves a `processBlock` body without `ScopedNoDenormals`.
+- `.claude/checks/juce-snap-to-zero-off.json` blocks removing the define once it's in `CMakeLists.txt`.

package/packs/audio-core/rules/smooth-continuous-parameters.md

@@ -0,0 +1,22 @@
+---
+# concepts: dsp, audio
+paths:
+  - "placeholder"
+---
+
+# Every continuous parameter is smoothed per sample
+
+<constraints>
+Always do:
+- Give each continuous control (gain, cutoff, resonance, mix, pan, drive, matrix-driven values) a `juce::SmoothedValue` or an equivalent one-pole smoother.
+- Call `reset(sampleRate, rampSeconds)` in `prepareToPlay()`, `setTargetValue()` once per block, and `getNextValue()` per sample.
+- Use multiplicative smoothing (`ValueSmoothingTypes::Multiplicative`) for frequency and gain in dB, where linear ramps sound uneven.
+- Call `setCurrentAndTargetValue()` when a patch loads, so a preset change doesn't sweep.
+
+Never do:
+- Apply a new parameter value as a step at the block boundary (zipper noise, clicks).
+- Smooth stepped controls (waveform choice, on/off, octave). Crossfade those instead when switching causes a click.
+</constraints>
+
+## Check
+Test: hold a sine, jump a parameter from minimum to maximum, and assert the largest sample-to-sample difference in the output stays under a set threshold.

package/packs/audio-core/rules/state-load-versioned-and-safe.md

@@ -0,0 +1,22 @@
+---
+# concepts: params
+paths:
+  - "placeholder"
+---
+
+# Loading state is versioned and can never crash
+
+<constraints>
+Always do:
+- Write a `version` attribute on the root of every saved state and patch.
+- In `setStateInformation` and patch loading: null-check the XML or JSON, check the root tag, read the version, migrate older versions forward step by step, then apply.
+- Ignore unknown IDs (from a newer build), and keep defaults for IDs missing in old data.
+- Load on the message thread, then hand values to the engine through the parameter system.
+
+Never do:
+- Dereference the result of `getXmlFromBinary()` or a JSON parse without checking it.
+- Assume the saved data was written by the current build.
+</constraints>
+
+## Check
+Test: load an empty block, random bytes, a v1 patch and a patch with an unknown extra ID, and assert no crash, sane defaults, and the known values restored.

package/packs/audio-core/rules/straight-on-and-aligned.md

@@ -0,0 +1,21 @@
+---
+# concepts: ui
+---
+
+# A UI is drawn straight on, and everything aligns: basic UX comes before the picture
+
+<constraints>
+Always do:
+- Draw the object straight on and flat, as if from infinitely far away. Depth comes from shading under one light, never from shifted shapes.
+- Align everything horizontally and vertically. Controls in a row share one centre line, and controls in a column share one centre line.
+- Treat whatever looks grouped as a group: the same size, the same spacing, shared edges, and even gaps.
+- Give a control its size from its kind, never its instance. A table row holds position and parameter.
+- Give a round control's parts one centre: cap, skirt, pointer and ticks.
+- Keep text level, and mirror what is symmetrical: rack ears, slots, screw holes.
+- Treat a photograph as evidence of the design, not as the design. Start from what is known of the object: a panel is a flat rectangle. Snap what you measure to the grid it implies.
+
+Never do:
+- Copy what belongs to the photograph: the camera's angle, the lens, the lighting, a bend, wear, a missing part. One bend moves everything near it.
+- Keep a measured offset as design when it is smaller than the design's own spacing. It is error.
+- Let a look gate reward a flaw. Mask what is damaged, and check alignment, sizes and centres on their own: a whole-picture score passes while every knob is wrong.
+</constraints>