@thedecipherist/claude-packs 0.0.0-stage → 1.0.0

package/packs/audio-core/rules/ui-matches-reference-look.md

@@ -0,0 +1,21 @@
+---
+# concepts: ui, painter
+paths:
+  - "placeholder"
+---
+
+# A UI built from a reference matches its look, not only its layout
+
+Stellix's layers landed flat and without glow (B-161): the analysis measured positions, the side-by-sides compared positions, no gate measured the look, and the brief said "not widget details".
+
+<constraints>
+Always do:
+- Analyse the reference into numbers before drawing anything, with the `analyse-reference-look` skill: layout, colours sampled by script, type, glow and its colour and radius, surfaces and gradients, every control's parts (track, arc, pointer, ticks, value placement), and the gaps between elements.
+- Gate the look: render off-screen at the reference's size and compare region by region (glow, colour, contrast, position, overlap) against the analysis, with a stated tolerance per measure. A knob count differs or a knob moves past tolerance: the gate fails. Plant a fault (bloom off, a value overlapping a label) and show it fail.
+- Keep repeated components identical: one component, one size (cards, tabs, knobs). A component never shrinks to fit; the container scrolls.
+- Keep text readable: at least 4.5 : 1 contrast for small text, measured, on every fill it can sit on.
+- End every drawn page with the user's picture stop on the side by side. A page is not done before that.
+
+Never do:
+- Treat a reference drawing as "layout and control list only". Where a drawing is inconsistent with itself, the written spec picks the right version; it is never a reason to drop the look.
+- Report a side by side as passing from positions alone.

package/packs/audio-core/rules/undo-one-gesture-one-step.md

@@ -0,0 +1,21 @@
+---
+# concepts: ui, params
+paths:
+  - "placeholder"
+---
+
+# One gesture is one undo step; host automation never enters undo
+
+<constraints>
+Always do:
+- Call `UndoManager::beginNewTransaction()` on mouse-down only. During the drag, perform actions that coalesce on the same target (`UndoableAction::createCoalescedAction`), so a whole drag undoes in one step.
+- Make a patch load either clear the undo history or be one transaction of its own.
+- Tell user gestures and host automation apart: only changes made inside the editor during a gesture are undoable.
+
+Never do:
+- Create one undo step per mouse-move event.
+- Record host automation or modulation (pushes, orbits) as undo actions.
+</constraints>
+
+## Check
+Test: drag a moon across 500 values, undo once. Pass: the value is back exactly where it started, and the transaction holds one coalesced action.

package/packs/audio-core/rules/voice-steal-fades.md

@@ -0,0 +1,21 @@
+---
+# concepts: audio
+paths:
+  - "placeholder"
+---
+
+# A stolen voice fades out; it is never cut
+
+<constraints>
+Always do:
+- When every voice is busy, steal by a stated policy (released voices first, then the quietest, then the oldest), and fade the stolen voice over a short fixed ramp (about 1 to 5 ms) before restarting it.
+- Reset filter and envelope state cleanly when the voice restarts, after its fade completes.
+- Keep the voice count fixed and allocated in `prepareToPlay()`. Stealing never creates a voice.
+
+Never do:
+- Restart a sounding voice instantly at full level (a click on every steal).
+- Pick the voice to steal by array index alone.
+</constraints>
+
+## Check
+Test: fill all voices with held notes, play one more, and assert no sample-to-sample jump in the output exceeds the same threshold the smoothing test uses.

package/packs/audio-core/rules/voice-sum-headroom.md

@@ -0,0 +1,20 @@
+---
+# concepts: audio
+paths:
+  - "placeholder"
+---
+
+# 96 voices summed can never clip the output stage
+
+<constraints>
+Always do:
+- Scale per-voice output for the full voice count. 96 uncorrelated voices sum about +19.8 dB above one voice (√96); phase-reset, same-note voices can sum up to +39.6 dB.
+- Keep the gain staging before any post-sum nonlinearity independent of the number of voices playing, so the effects see the same level for one note or a chord.
+- End the signal chain with a soft clipper or limiter at a fixed ceiling, never hard clipping or wraparound.
+
+Never do:
+- Normalise by the *current* number of active voices (pumping as notes start and stop).
+</constraints>
+
+## Check
+Test: 96 voices, same note, phase reset, maximum resonance. Pass (house choice): the peak before the limiter is ≤ +6 dBFS and the output never exceeds the limiter ceiling.

package/packs/audio-core/skills/analyse-reference-look/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: analyse-reference-look
+description: Use before building or rebuilding a page, panel or layer from a reference picture or an existing panel image. Also /analyse-reference-look.
+---
+
+# Analyse a reference picture into numbers
+
+Write one analysis file per reference, beside it in the design reference folder. Measure by script, never by eye.
+
+First, separate the object from the photograph. You are learning a design, to draw it flat and straight on (`straight-on-and-aligned`). List what belongs to the photograph: the camera's angle, the lens, the lighting, bends, wear and missing parts. A bend moves everything near it. Start from what is known of the object: a panel is a flat rectangle, controls of a kind are one size, what looks like a row is a row, ears mirror each other, text sits level. A measurement that disagrees with those belongs to the photograph.
+
+1. **Layout:** every region and every control's centre and size as fractions of the picture. Then find the grid: which controls share a row or a column, which look grouped, and the one size of each kind. Snap to it, and record what the snap moved and why.
+2. **Colour:** sample background, panels, borders, text levels, accents, lit and unlit states.
+3. **Glow:** for every glowing part, the colour, radius and strength, measured from the falloff.
+4. **Surfaces:** gradients, edge glow, bevels, shadows, textures.
+5. **Type:** font, size, weight and letter spacing of every text style, and how they relate.
+6. **Controls:** each kind's parts (track ring, value arc, pointer, ticks, cap, skirt, scale numbers) and where its label and value sit.
+7. **Spacing:** the gaps between elements and rows, and the dividers.
+8. **Unclear:** what the picture leaves open, or shows damaged: decide from the object, and say so.
+
+Then list the tolerances the look gate will use for each measure, and mask what is damaged. The gate checks alignment, sizes and shared centres on their own, because a whole-picture score passes while every knob is wrong. Report the analysis file's path and the list of open items.

package/packs/audio-core/skills/copy-and-prove/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: copy-and-prove
+description: Use when code is taken from another house synth (an engine, an effect, any part) into this one, when a fresh copy must be measured against its source, or when a ported part sounds different from where it came from. Also /copy-and-prove.
+---
+
+# Copy a part, prove it, then make it yours
+
+The canonical text is the target synth's `CLAUDE.md` (its sharing rule: which synth parts come from, and from which
+branch) and its `docs/licences.md`. This file is the operating summary; the repo wins.
+
+The rule: global components are LINKED (`synthcore`, `dspblocks`, `synthkit`, and the components
+in `synthkit/components`). Everything else that comes from another synth is COPIED and becomes the new synth's own. The
+source synth is not touched and nothing is shared with it. A project that links no global component copies those too,
+with a licence row, like any other part.
+
+Why the proof comes first: on MegaSynth, regrouping one multiply in a copied engine moved all 907 programs. Nobody could
+say whether the copy or the tidy-up did it, because the copy had never been measured by itself.
+
+## 0. Is it a copy at all?
+
+- Already a global component, or a block in `dspblocks`? Link it. This skill does not apply.
+- In `~/projects/synthcatalog`? Check before writing or copying a sound component.
+- Finished and wanted by more than one synth? It may be time to make it a global component.
+
+## 1. The licence row, before the first file moves
+
+Write the row in the target's `docs/licences.md`: what it is, where it came from (repo, path, commit hash), its licence,
+where it will be used. Read "the user's rulings" at the top of that file first; they say what is already allowed.
+
+What never comes across, whatever the source:
+
+- hardware, brand or machine names in program names, labels or strings that reach the product. Every preset and program
+  name is our own;
+- factory preset bodies, sample data, ROM bytes, vendor artwork;
+- anything from `~/firmware`.
+
+Tables and numbers derived from a hardware unit but written as our own code come across only where the user has ruled so in
+`docs/licences.md`. For any other such table, ask the user and record the answer.
+
+Search the part and everything it includes before copying:
+`grep -rniE "factory|firmware|korg|roland|lexicon|eventide|yamaha|\btc\b|re-201|h910|pcm ?[0-9]" <files>`
+
+## 2. Render the source first
+
+Build the SOURCE synth (its current trunk, read through git at a named commit) and render the part alone through its
+probe: one fixed setting, a fresh processor, a fixed seed, at least two notes away from middle C, long enough to hold the
+whole tail of an effect. Keep the WAV, its hash and the exact settings in the target's evidence folder. This is the
+baseline. Build it before theorising about anything.
+
+First assertion: render the source twice. If the two differ, find the un-reset state (grep for `static`, seeds, phases)
+before going on. Nothing can be compared with a source that does not match itself.
+
+## 3. Copy, changing nothing
+
+Copy every file the part needs (follow its includes; an envelope may be two files) into a COPY TREE: a folder declared in
+`.claude/layout.json` with `"kind": "copy"`, read-only from then on (`protect-vendor` refuses edits; only the project's
+copy tools in `guards.copy.tools` write there). Change only what is needed to compile: namespace, include paths. No
+renames, no tidying, no regrouped arithmetic. Give every file its origin (repo, path, commit, SHA-256, licence row). Save
+it as its own commit: "copy of <part> from <repo>@<hash>, unchanged".
+
+## 4. Prove it
+
+Render the copy in the new synth with the same settings and compare:
+
+```
+python3 tools/null_compare.py source.wav copy.wav
+```
+
+- `IDENTICAL` is the only pass. The tool prints the first sample that differs, the size of the difference and any level
+  change.
+- It refuses two silences. A control behind a closed switch is correctly silent: open the switch.
+- A clean 6 dB level change is nearly always a default hidden inside the module or a weight missing from a normaliser,
+  not the algorithm.
+- A difference only in the tail is un-reset state or a different block size.
+- `--allow-db` is for a difference the user has accepted, with the reason written in `docs/licences.md`. It is not for making
+  a red result green.
+
+Show the gate can fail: change one coefficient in the copy, see `DIFFERENT`, put it back.
+
+If it will not come out identical after an honest try, log it in `bugs.md` with both renders' numbers and ask. Do not
+start reworking a copy that has not matched.
+
+## 5. Only now, change it
+
+A file that measured identical is promoted out of the copy tree into the project's own code (a folder of kind `"own"`)
+with its origin record kept; only then is it changed. Rework in small saved commits (one parameter set per oscillator,
+the synth's own rate ladder for a time grid, our own program names). After each, measure what was meant to change and
+confirm what was not meant to change is still bit-identical. A time grid moved onto the synth's ladder is checked at 90,
+120 and 140 BPM against absolute times, changing the tempo, not only the division.
+
+Every module ships off, including every default inside it, and off is bit-identical to absent.
+
+## 6. Record
+
+- `docs/licences.md`: the row now says "measured identical on <date>, commit <hash>".
+- The synth's tempo audit, if the part has a time in it.
+- A lesson that would help the next synth: `~/projects/eproms/synth-design.md`.
+- If this is a step in `build.md`, it is on that step's branch: finish it with `build-step`.

package/packs/audio-core/skills/juce-realtime-audit/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: juce-realtime-audit
+description: Use for a realtime-safety audit, after a crackle, dropout, xrun or CPU spike, or before merging changes to anything reachable from processBlock.
+---
+
+# Realtime audit (one job: find what the audio thread can reach that it must not)
+
+The realtime-guard hook only sees the bodies of known audio functions. This audit follows the **call graph**, which is where most real violations hide.
+
+## Steps
+1. Find every audio-thread entry point: `processBlock`, `processBlockBypassed`, `renderNextBlock`, and any `[[clang::nonblocking]]` function.
+2. From each one, follow every call into the project's own code (voices, oscillators, filters, effects, matrix, arp). Record the chain, e.g. `processBlock → Matrix::tick → Row::advance`.
+3. In each reached function, look for what `.claude/rules/audio-thread-realtime-safe.md` and `audio-ui-thread-handoff.md` forbid. Also look for hidden allocations:
+   - `juce::Array` / `std::vector` growth, `MidiBuffer::addEvent` past its reserved size, `AudioBuffer::setSize` / `makeCopyOf` without `avoidReallocating`
+   - `std::function` assignment, lambdas capturing by value into containers, `shared_ptr` whose last reference drops on the audio thread
+   - `ValueTree` reads or writes, `var`, `DynamicObject`
+4. Stop at JUCE and std library calls. Judge them by the hidden-allocation list above rather than reading their source.
+
+## Report
+A table with columns Severity, File:line, Call chain, What, Fix. Sort it with blocking or allocating calls first. End with the list of functions that should get `[[clang::nonblocking]]`, so the hook and RealtimeSanitizer cover them from now on.
+
+Don't change code in this skill. The report is the output.

package/packs/audio-core/skills/measure-tone/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: measure-tone
+description: Use when an oscillator, shaper, HEAT/BIT stage, filter or effect is new or changed, or a sound is harsh, buzzy, metallic, thin or has DC.
+---
+
+# Measure a tone (one job: put numbers on how clean a sound path is)
+
+## Steps
+1. Render offline with the project's own render probe or test harness (CLAUDE.md, Project commands), not the live standalone: 2 s mono, 32-bit float WAV, 48 kHz.
+   - Oscillators: f0 = 110, 1000, 2000 and 4186 Hz.
+   - Nonlinear stages: sine probes at 1, 3, 5 and 7 kHz at the stated drive (add 10 kHz when rendering at 96 kHz).
+   - DC check: 1 kHz sine with +0.3 offset into the stage.
+2. For each file run `node .claude/tools/tone-report.mjs <wav> <f0> --max-freq 15000` with the threshold for that case:
+   - oscillator: `--nonharm-max -60` up to 2 kHz, `-40` at 4186 Hz
+   - nonlinear stage: `--snr-min 45`
+   - DC: `--dc-max -80`
+3. A deliberate crusher or vintage mode is exempt from the aliasing thresholds. Compare it against its golden file instead.
+
+## Report
+A table with columns Case, f0, Worst non-harmonic dB, SNR, THD, DC, and PASS/FAIL. For each FAIL, name the rule it breaks (`oscillators-bandlimited`, `nonlinear-stages-antialiased` or `dc-block-after-asymmetry`) and the likely fix. Don't change code in this skill.

package/packs/audio-core/skills/new-panel-control/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: new-panel-control
+description: Use when adding a control to a panel or page, or changing what an existing control does. Also /new-panel-control.
+---
+
+# Add a panel control
+
+1. **Use the shared piece.** Find the shared control component (knob, slider, switch, segmented button, handle) and place it. Never draw a control by hand.
+2. **Parameter.** Append the parameter at the end of the parameter table, with a new id that never changes (`parameter-ids-never-change`). Never insert, never reuse an id.
+3. **Wire all three links.** Drawn (on the page), bound (the control moves the parameter, and the parameter moves the control), carried (the sound changes). Check each one with `prove-control`.
+4. **House behaviours.** Double click to default, fine drag, wheel, value readout, no keyboard focus, one undo step (`house-control-behaviours`).
+5. **Look.** Match the page's reference: the control's parts, value placement and spacing (`ui-matches-reference-look`).
+6. **Gates.** Run the behaviour gate, the look gate and the silent-control gate. Each must pass and must still fail on its planted fault.
+
+Report: the parameter id, and the evidence from each step as command plus result.

package/packs/audio-core/skills/prove-control/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: prove-control
+description: Use after adding, renaming, re-ranging or removing a control, or before calling a control's step or bug done.
+---
+
+# Prove a control at every surface it has
+
+## Steps
+For the control's parameter ID, run each check through the real path and save the command plus its output as evidence. Use the project's own probes and tests (see CLAUDE.md, Project commands).
+
+1. **Host:** set the parameter by ID in an offline render, at its minimum, default and maximum. The render must change, and a null test against default must fail where it should and pass where it should.
+2. **Editor:** the widget is attached to that same ID. Moving it changes the parameter, and a host-set value shows in the widget with the same text as the host's value-to-text.
+3. **Patch:** save, load and compare. The value is bit-identical, and old patches without the ID load the spec default.
+4. **Init and reset:** the init patch and the reset action give the value the spec states.
+5. **MIDI** (if mapped): the CC or learn moves the parameter over its full range.
+6. **Undo:** one drag is one undo step, and host automation never enters undo.
+7. **In the real window:** press, drag, wheel and double click one control of this template on a loaded patch (not only INIT); a table
+   read proves the same control on the other slots is that template and is wired (`test-the-template-once`). The value and the sound or picture change. A choice control (dropdown, select, menu) opens its list on a press, shows every
+   choice with the current one marked, sets the one chosen, and closes on Escape or a press outside; it never steps on a press.
+8. **IDs:** the parameter ID list diff is empty except for the intended change (see `parameter-ids-never-change`).
+
+## Report
+A table with the columns Surface, Command, Result and PASS/FAIL. A surface the control doesn't have is marked N/A, with the reason. Change nothing in this skill. Fix through `bug-fix-starts-red`.

package/packs/audio-core/skills/trace-parameter/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: trace-parameter
+description: Use when a control sounds wrong, reads wrong, zips, jumps or does nothing; when the display and the sound disagree; or before changing how a parameter maps to its range.
+---
+
+# Trace one parameter from the host to the sound and the screen
+
+This skill is read-only: it reports, and changes nothing.
+
+## Steps
+1. Name the parameter by its ID. Find its definition (parameter layout, range, skew, default, value-to-text).
+2. Follow each hop and write down `file:line` and the exact transform at each:
+   1. host or automation value (normalized 0–1);
+   2. parameter tree, then the cached pointer (or the parameter snapshot for the block);
+   3. smoothing: which smoother, what ramp time, and is it reset in `prepareToPlay`;
+   4. the mapping to physical units (Hz, dB, ms…), and where that function lives;
+   5. per-voice or per-sample use in the DSP;
+   6. the audible result: render a short sweep of the parameter and run `measure-tone` if the sound itself is in question.
+3. Follow the other branch: parameter → editor attachment → widget → displayed text. Write down the mapping used there.
+4. Search for any second computation of the same value: `grep` for the parameter ID, its member name and its unit conversion.
+
+## Report
+A hop table with the columns Hop, `file:line`, Transform and Units. Then a list of findings, each tied to its rule:
+- a second formula (`one-formula-per-value`);
+- missing or wrong smoothing (`smooth-continuous-parameters`);
+- a stepped value not snapped (`discrete-params-snap`);
+- a lookup per block (`cached-parameter-pointers`);
+- a unit or range mismatch;
+- a hop that never runs.

package/packs/audio-core/tools/lib/spectrum.mjs

@@ -0,0 +1,112 @@
+// Blackman-Harris windowed FFT analysis of a steady tone.
+const MAX_N = 1 << 18;
+const LOBE = 6; // bins either side of a peak treated as part of it (BH-4 main lobe is ±4)
+const ENBW_BH4 = 2.0044; // equivalent noise bandwidth of the 4-term Blackman-Harris window, in bins
+
+function fft(re, im) {
+  const n = re.length;
+  for (let i = 1, j = 0; i < n; i += 1) {
+    let bit = n >> 1;
+    for (; j & bit; bit >>= 1) j ^= bit;
+    j ^= bit;
+    if (i < j) {
+      [re[i], re[j]] = [re[j], re[i]];
+      [im[i], im[j]] = [im[j], im[i]];
+    }
+  }
+  for (let len = 2; len <= n; len <<= 1) {
+    const ang = (-2 * Math.PI) / len;
+    for (let i = 0; i < n; i += len) {
+      for (let k = 0; k < len / 2; k += 1) {
+        const wr = Math.cos(ang * k);
+        const wi = Math.sin(ang * k);
+        const a = i + k;
+        const b = a + len / 2;
+        const tr = re[b] * wr - im[b] * wi;
+        const ti = re[b] * wi + im[b] * wr;
+        re[b] = re[a] - tr;
+        im[b] = im[a] - ti;
+        re[a] += tr;
+        im[a] += ti;
+      }
+    }
+  }
+}
+
+const db = (power) => 10 * Math.log10(Math.max(power, 1e-30));
+
+export function analyse(samples, sampleRate, f0, maxFreq) {
+  let nonFinite = 0;
+  let peak = 0;
+  let sum = 0;
+  for (const s of samples) {
+    if (!Number.isFinite(s)) nonFinite += 1;
+    else {
+      peak = Math.max(peak, Math.abs(s));
+      sum += s;
+    }
+  }
+  let n = 1;
+  while (n * 2 <= Math.min(samples.length, MAX_N)) n *= 2;
+  const start = Math.floor((samples.length - n) / 2); // skip the attack
+  const re = new Float64Array(n);
+  const im = new Float64Array(n);
+  let wsum = 0;
+  for (let i = 0; i < n; i += 1) {
+    const x = (2 * Math.PI * i) / (n - 1);
+    const w = 0.35875 - 0.48829 * Math.cos(x) + 0.14128 * Math.cos(2 * x) - 0.01168 * Math.cos(3 * x);
+    const s = samples[start + i];
+    re[i] = (Number.isFinite(s) ? s : 0) * w;
+    wsum += w;
+  }
+  fft(re, im);
+  const half = n / 2;
+  const scale = 2 / wsum;
+  const power = new Float64Array(half);
+  for (let k = 0; k < half; k += 1) power[k] = (re[k] * scale) ** 2 + (im[k] * scale) ** 2;
+
+  const binHz = sampleRate / n;
+  const lobePower = (centre) => {
+    let p = 0;
+    for (let k = Math.max(1, centre - LOBE); k <= Math.min(half - 1, centre + LOBE); k += 1) p += power[k];
+    return p;
+  };
+  const harmonicBins = [];
+  for (let h = 1; h * f0 < sampleRate / 2; h += 1) harmonicBins.push(Math.round((h * f0) / binHz));
+  const isHarmonic = new Uint8Array(half);
+  for (const b of harmonicBins) for (let k = b - LOBE; k <= b + LOBE; k += 1) if (k >= 0 && k < half) isHarmonic[k] = 1;
+  for (let k = 0; k <= LOBE; k += 1) isHarmonic[k] = 1; // DC region
+
+  const fund = lobePower(harmonicBins[0]);
+  let harmTotal = 0;
+  let thd = 0;
+  harmonicBins.forEach((b, i) => {
+    const p = lobePower(b);
+    harmTotal += p;
+    if (i >= 1 && i <= 9) thd += p;
+  });
+  let rest = 0;
+  let worst = 0;
+  let worstBin = 0;
+  const maxBin = Math.min(half - 1, Math.floor(maxFreq / binHz));
+  for (let k = 0; k < half; k += 1) {
+    if (isHarmonic[k]) continue;
+    rest += power[k];
+    if (k <= maxBin && power[k] > worst) {
+      worst = power[k];
+      worstBin = k;
+    }
+  }
+  return {
+    maxFreq,
+    nonFinite,
+    fundamentalDbfs: db(fund / ENBW_BH4), // summed lobe power over-reads by the window's noise bandwidth
+    thdDb: db(thd) - db(fund),
+    thdPercent: 100 * Math.sqrt(thd / Math.max(fund, 1e-30)),
+    worstNonHarmonicDb: db(worst) - db(power[harmonicBins[0]] ?? 0),
+    worstNonHarmonicHz: worstBin * binHz,
+    snrDb: db(harmTotal) - db(rest),
+    dcDbfs: 20 * Math.log10(Math.max(Math.abs(sum / Math.max(samples.length, 1)), 1e-15)),
+    peakDbfs: 20 * Math.log10(Math.max(peak, 1e-15)),
+  };
+}

package/packs/audio-core/tools/lib/wav.mjs

@@ -0,0 +1,41 @@
+// Minimal WAV reader: PCM 16/24/32-bit and IEEE float 32/64. Returns channel 0 as Float64Array.
+export function readWav(buf) {
+  if (buf.toString('ascii', 0, 4) !== 'RIFF' || buf.toString('ascii', 8, 12) !== 'WAVE') throw new Error('not a WAV file');
+  let off = 12;
+  let fmt = null;
+  while (off + 8 <= buf.length) {
+    const id = buf.toString('ascii', off, off + 4);
+    const size = buf.readUInt32LE(off + 4);
+    const body = off + 8;
+    if (id === 'fmt ') {
+      let format = buf.readUInt16LE(body);
+      if (format === 0xfffe) format = buf.readUInt16LE(body + 24); // WAVE_FORMAT_EXTENSIBLE sub-format
+      fmt = { format, channels: buf.readUInt16LE(body + 2), sampleRate: buf.readUInt32LE(body + 4), bits: buf.readUInt16LE(body + 14) };
+    } else if (id === 'data') {
+      if (!fmt) throw new Error('data chunk before fmt chunk');
+      return { sampleRate: fmt.sampleRate, samples: decode(buf, body, Math.min(size, buf.length - body), fmt) };
+    }
+    off = body + size + (size % 2);
+  }
+  throw new Error('no data chunk');
+}
+
+// One reader per sample encoding: format 3 is IEEE float (64 bit, else 32), any other is integer PCM by bit depth.
+const READERS = {
+  f32: (buf, p) => buf.readFloatLE(p),
+  f64: (buf, p) => buf.readDoubleLE(p),
+  i16: (buf, p) => buf.readInt16LE(p) / 32768,
+  i24: (buf, p) => buf.readIntLE(p, 3) / 8388608,
+  i32: (buf, p) => buf.readInt32LE(p) / 2147483648,
+};
+
+function decode(buf, start, size, { format, channels, bits }) {
+  const encoding = format === 3 ? (bits === 64 ? 'f64' : 'f32') : `i${bits}`;
+  if (!Object.hasOwn(READERS, encoding)) throw new Error(`unsupported bit depth ${bits}`);
+  const read = READERS[encoding]; // chosen once, not per sample
+  const bytes = bits / 8;
+  const frames = Math.floor(size / (bytes * channels));
+  const out = new Float64Array(frames);
+  for (let i = 0; i < frames; i += 1) out[i] = read(buf, start + i * bytes * channels);
+  return out;
+}

package/packs/audio-core/tools/tone-report.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+// Measures a rendered test tone: fundamental level, THD, worst non-harmonic peak (aliasing),
+// SNR, DC offset, peak, and non-finite samples. No dependencies.
+//   node tone-report.mjs <file.wav> <f0 Hz> [--max-freq 15000] [--nonharm-max -60] [--snr-min 45] [--dc-max -80] [--json]
+// Exit 1 when a given threshold fails, so it can run as a test.
+import { readFileSync } from 'node:fs';
+import { readWav } from './lib/wav.mjs';
+import { analyse } from './lib/spectrum.mjs';
+
+function arg(name, fallback) {
+  const i = process.argv.indexOf(name);
+  return i === -1 ? fallback : Number(process.argv[i + 1]);
+}
+
+function main() {
+  const [file, f0Text] = process.argv.slice(2);
+  if (!file || !f0Text) {
+    console.error('usage: tone-report.mjs <file.wav> <f0> [--max-freq Hz] [--nonharm-max dB] [--snr-min dB] [--dc-max dBFS] [--json]');
+    return 2;
+  }
+  const { sampleRate, samples } = readWav(readFileSync(file));
+  const r = analyse(samples, sampleRate, Number(f0Text), arg('--max-freq', sampleRate / 2));
+
+  const fails = [];
+  const nonharmMax = arg('--nonharm-max', null);
+  const snrMin = arg('--snr-min', null);
+  const dcMax = arg('--dc-max', null);
+  if (r.nonFinite > 0) fails.push(`${r.nonFinite} non-finite samples`);
+  if (nonharmMax !== null && r.worstNonHarmonicDb > nonharmMax) fails.push(`non-harmonic ${r.worstNonHarmonicDb.toFixed(1)} dB > ${nonharmMax}`);
+  if (snrMin !== null && r.snrDb < snrMin) fails.push(`SNR ${r.snrDb.toFixed(1)} dB < ${snrMin}`);
+  if (dcMax !== null && r.dcDbfs > dcMax) fails.push(`DC ${r.dcDbfs.toFixed(1)} dBFS > ${dcMax}`);
+
+  if (process.argv.includes('--json')) console.log(JSON.stringify({ ...r, pass: fails.length === 0, fails }));
+  else {
+    const f = (x) => (Number.isFinite(x) ? x.toFixed(1) : String(x));
+    console.log(`file            ${file} (${sampleRate} Hz, ${samples.length} samples)`);
+    console.log(`fundamental     ${f(r.fundamentalDbfs)} dBFS at ${f0Text} Hz`);
+    console.log(`THD (2-10)      ${f(r.thdDb)} dB  (${r.thdPercent.toFixed(3)} %)`);
+    console.log(`worst non-harm  ${f(r.worstNonHarmonicDb)} dB re fundamental at ${f(r.worstNonHarmonicHz)} Hz (below ${f(r.maxFreq)} Hz)`);
+    console.log(`SNR             ${f(r.snrDb)} dB (harmonic vs everything else)`);
+    console.log(`DC              ${f(r.dcDbfs)} dBFS   peak ${f(r.peakDbfs)} dBFS   non-finite ${r.nonFinite}`);
+    console.log(fails.length ? `FAIL: ${fails.join('; ')}` : 'PASS');
+  }
+  return fails.length ? 1 : 0;
+}
+
+process.exit(main());

package/packs/base/checks/field-map-over-if-runs.json

@@ -0,0 +1,25 @@
+{
+  "id": "field-map-over-if-runs",
+  "why": "Three or more ifs in a row on fields of the same object (if (args.filter?.flag !== undefined) filter.flags = \u2026) grow by one line per field forever. A field table plus one loop keeps every field in one place and makes the next field one table row.",
+  "rule": ".claude/rules/field-map-over-if-runs.md",
+  "concepts": [
+    "cpp",
+    "js"
+  ],
+  "globs": [],
+  "exclude": [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/*.min.js",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/test/**",
+    "**/tests/**",
+    "**/*_test.*"
+  ],
+  "code": true,
+  "pattern": "if\\s*\\(\\s*!?\\s*([A-Za-z_$][\\w$]*(?:(?:\\?\\.|\\.|->)[A-Za-z_$][\\w$]*)*)(?:\\?\\.|\\.|->)[A-Za-z_$][\\w$]*\\s*(?:(?:!==?|===?)\\s*(?:undefined|null|nullptr)\\s*)?\\)[^\\n]*\\n(?:[^\\n]*\\n){0,3}?\\s*if\\s*\\(\\s*!?\\s*\\1(?:\\?\\.|\\.|->)[A-Za-z_$][\\w$]*\\s*(?:(?:!==?|===?)\\s*(?:undefined|null|nullptr)\\s*)?\\)[^\\n]*\\n(?:[^\\n]*\\n){0,3}?\\s*if\\s*\\(\\s*!?\\s*\\1(?:\\?\\.|\\.|->)[A-Za-z_$][\\w$]*\\s*(?:(?:!==?|===?)\\s*(?:undefined|null|nullptr)\\s*)?\\)",
+  "bad": "  if (args.filter?.flag !== undefined) filter.flags = args.filter.flag;\n  if (args.filter?.kind !== undefined) filter.kind = args.filter.kind;\n  if (args.filter?.path !== undefined) filter.path = { $regex: escapeRe(args.filter.path) };\n",
+  "good": "const FILTER_FIELDS = {\n  flag: (v) => ({ flags: v }),\n  kind: (v) => ({ kind: v }),\n  path: (v) => ({ path: { $regex: escapeRe(v) } }),\n};\nfor (const [k, put] of Object.entries(FILTER_FIELDS)) if (args.filter?.[k] !== undefined) Object.assign(filter, put(args.filter[k]));\nif (a.x) f();\nif (b.y) g();\nif (c.z) h();\n"
+}

package/packs/base/checks/lookup-over-if-chains.json

@@ -0,0 +1,25 @@
+{
+  "id": "lookup-over-if-chains",
+  "why": "Three or more branches on one value (if/else if, or ifs in a row that each return) are a lookup table (JS/TS) or an object per kind (C++; an exhaustive switch over an enum class only in a hot inner loop): one place to add a case, and a missing case is a compile error. The chain hides a missing case and grows forever.",
+  "rule": ".claude/rules/lookup-over-if-chains.md",
+  "concepts": [
+    "cpp",
+    "js"
+  ],
+  "globs": [],
+  "exclude": [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/*.min.js",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/test/**",
+    "**/tests/**",
+    "**/*_test.*"
+  ],
+  "code": true,
+  "pattern": "if\\s*\\(\\s*(?![\\w.]*\\.length\\b)([A-Za-z_][\\w.]*(?:->\\w+)*(?:\\(\\))?)\\s*===?(?!=)(?!\\s*(?:null|undefined|nullptr)\\b)\\s*[^)&|]+\\)[\\s\\S]{0,600}?(?:else\\s+)?if\\s*\\(\\s*\\1\\s*===?(?!=)(?!\\s*(?:null|undefined|nullptr)\\b)\\s*[^)&|]+\\)[\\s\\S]{0,600}?(?:else\\s+)?if\\s*\\(\\s*\\1\\s*===?(?!=)(?!\\s*(?:null|undefined|nullptr)\\b)",
+  "bad": "if (row.kind === 'turn') return `<div>${turn(row)}</div>`;\nif (row.kind === 'system') return `<div>${note(row)}</div>`;\nif (row.kind === 'bash') return detailed(row);",
+  "good": "const RENDER = { turn: (row) => `<div>${turn(row)}</div>`, system: (row) => `<div>${note(row)}</div>`, bash: detailed };\nreturn (RENDER[row.kind] ?? unknownKind)(row);\nswitch (mode) {\n    case Mode::line: return drawLine (ctx);\n    case Mode::fill: return drawFill (ctx);\n    case Mode::text: return drawText (ctx);\n}\nif (score > 90) a(); else if (score > 80) b(); else if (score > 70) c();\nif (a == 1) x(); else if (b == 2) y(); else if (c == 3) z();\nif (row.kind === 'turn') return t(row);\nif (row.kind === 'system') return s(row);\nif (x === null) return a;\nif (x === undefined) return b;\nif (x === '') return c;\n"
+}

package/packs/base/checks/lookup-over-ternary-chains.json

@@ -0,0 +1,20 @@
+{
+  "id": "lookup-over-ternary-chains",
+  "why": "A ternary chain is a lookup table written as control flow: adding a kind means finding every chain, and the compiler checks none of them.",
+  "rule": ".claude/rules/lookup-over-if-chains.md",
+  "concepts": [
+    "cpp",
+    "js"
+  ],
+  "globs": [],
+  "exclude": [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/*.min.js"
+  ],
+  "code": true,
+  "pattern": "\\?(?:[^?:;,()\\n]|::|\\((?:[^()\\n]|\\([^()\\n]*\\))*\\))*:(?:[^?:;,()\\n]|::|\\((?:[^()\\n]|\\([^()\\n]*\\))*\\))*\\?(?:[^?:;,()\\n]|::|\\((?:[^()\\n]|\\([^()\\n]*\\))*\\))*:(?:[^?:;,()\\n]|::|\\((?:[^()\\n]|\\([^()\\n]*\\))*\\))*\\?",
+  "bad": "const char* n = s == a ? \"A\" : s == b ? \"B\" : s == c ? \"C\" : \"D\";",
+  "good": "const auto f = g ? h : i ? j : k;\nprint (a ? \"x\" : \"y\", b ? \"x\" : \"y\", c ? \"x\" : \"y\");"
+}

package/packs/base/checks/no-code-after-midline-comment.json

@@ -0,0 +1,12 @@
+{
+  "id": "no-code-after-midline-comment",
+  "why": "A // put in the middle of a line swallows every statement after it, and it still compiles (Stellix WB-25: five times in one step). A comment goes at the end of the line, after the code. The pattern stays within one line: a line ending in a comment, followed by a line of code, is fine (KWB-9).",
+  "concepts": [
+    "cpp",
+    "shaders"
+  ],
+  "pattern": "^(?!.*https?://)[ \\t]*[^\\s/][^\\n]*?[^\"\\n]//[^\\n]*?(?:[;{}:,]|\\)|[ \\t])[ \\t]*(?:[A-Za-z_]\\w*(?:\\.\\w+|->\\w+|\\[[^\\]\\n]*\\])*[ \\t]*[-+*/|&]?=[ \\t]*[^=\\s][^;\\n]*|return\\b[^;\\n]*|[A-Za-z_]\\w*(?:::\\w+)*\\([^;\\n]*\\))[ \\t]*;[ \\t]*}?[ \\t]*$",
+  "flags": "m",
+  "bad": "    c.power = p;   // its share c.pitch = t.pitch; c.energy = e;\n    const size_t i = d.trav;   // kicked after if (d.trav < 0 || !live) return;",
+  "good": "    c.power = p;   // its share: a = b in the text, never code\n    open(url);   // see https://x.y/a?b=c;\n// a = b; whole-line comments are prose\nlaunchNote(w, L, from, set); // fire( in a comment\n    x = f();   // the note\n    return y;\n    a();   // the note\n    go(x);"
+}

package/packs/base/checks/one-walk-per-template.json

@@ -0,0 +1,23 @@
+{
+  "id": "one-walk-per-template",
+  "why": "A test that presses, clicks or drags every instance of one template repeats the same behaviour hundreds of times and proves nothing more than one press does. Walk one instance of each template and every one-off; prove the rest with a read of the table that each is built from its template and wired.",
+  "rule": ".claude/rules/test-the-template-once.md",
+  "globs": [
+    "**/gates/**",
+    "**/probes/**",
+    "**/tests/**",
+    "**/test/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/*_test.*",
+    "**/e2e/**"
+  ],
+  "exclude": [
+    "**/build/**",
+    "**/node_modules/**"
+  ],
+  "code": true,
+  "pattern": "(?:for\\s*\\([^;\\n]*?(?::|\\bof\\b|\\bin\\b)\\s*(?:await\\s+)?[^;\\n]*?(?:\\b(?:controls|ctls|kDefs|kPanel|widgets|knobs|sliders|buttons)\\b(?:\\(\\))?|\\.all\\(\\))\\s*\\)|for\\s*\\([^;\\n]*;[^;\\n]*<\\s*[\\w:.>-]*(?:kControls|kCount|(?:controls|ctls|kDefs|kPanel|widgets|knobs|sliders|buttons)\\.size\\(\\)|(?:controls|ctls|kDefs|kPanel|widgets|knobs|sliders|buttons)\\.length)[^;\\n]*;[^)\\n]*\\)|\\b(?:controls|ctls|kDefs|kPanel|widgets|knobs|sliders|buttons)\\.forEach\\()(?![^}\\n]{0,300}?\\.id\\s*===?(?!=))(?:\\s*\\{[^}]{0,300}?|[^;}]{0,300}?)\\b(?:press\\w*(?:\\.push_back|\\.push)?|click\\w*|drag\\w*|hover\\w*|tap)\\s*\\(",
+  "bad": "for (const auto& c : L.controls) if (c.visible) pressIds.push_back(c.id);\nfor (const b of buttons) {\n  await b.click();\n}\nfor (int i = 0; i < ctl::kCount; i++) pressAt (centreOf (i));\nbuttons.forEach((b) => b.hover());",
+  "good": "for (const auto& c : L.controls) if (c.id == id) pressAt (c.box.getCentre());\nfor (const d : kDefs) assert (d.bind != nullptr);\nawait buttons[0].click();\nfor (const row of table) expect(row.template).toBe('knob');"
+}