@thedecipherist/claude-packs 0.0.0-stage → 1.0.0

package/packs/audio-core/hooks/param-id-lock.mjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+// Locks parameter IDs: once seen, an ID may never disappear from the source.
+//   node param-id-lock.mjs --init   create .claude/param-ids.lock.json from the current repo
+//   (as PostToolUse hook)           fail (exit 2) if a locked ID is gone; add new IDs to the lock. Every route that
+//                                   writes is judged (Write, Edit, MultiEdit, NotebookEdit, and the shell's >, >>, tee,
+//                                   sed -i, cp, mv, rm, a heredoc; lib/writes.mjs): an id deleted by `sed -i` is gone too.
+//   node param-id-lock.mjs --selftest  proves it
+// Where IDs are read: .claude/param-ids.config.json, else layout.json "paramIds", else JUCE
+// ParameterID / AudioParameter* string literals. Both forms: { "extensions": "<regex>", "patterns": ["<regex with one group>"] }.
+// A file is judged in its own checkout: an agent worktree is scanned, and keeps its lock, on its own.
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readLayout } from './lib/layout.mjs';
+import { checkoutRoot, claudeRoot, insideProject } from './lib/project.mjs';
+import { writesOf } from './lib/writes.mjs';
+import { put, runHook, scratchProject, verdicts, writeOf } from './lib/selftest.mjs';
+import { asHook, isMain } from './lib/hook-log.mjs';
+
+const ROOT = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+// .claude is skipped so the worktrees under .claude/worktrees/ never stand in for this checkout's code.
+const SKIP_DIRS = /(^|\/)(build|Builds|JuceLibraryCode|JUCE|node_modules|\.git|\.claude|cmake-build[^/]*)(\/|$)/;
+
+const DEFAULT_PATTERNS = [
+  'ParameterID\\s*(?:[A-Za-z_]\\w*\\s*)?[({]\\s*"([^"]+)"',
+  'AudioParameter(?:Float|Int|Bool|Choice)\\s*>?\\s*\\(\\s*"([^"]+)"',
+];
+
+function loadConfig(root) {
+  const file = join(root, '.claude', 'param-ids.config.json');
+  const cfg = existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : readLayout(root).paramIds ?? {};
+  return {
+    extensions: new RegExp(cfg.extensions ?? '\\.(cpp|h|hpp|cc|mm)$'),
+    patterns: (cfg.patterns ?? DEFAULT_PATTERNS).map((p) => new RegExp(p, 'g')),
+  };
+}
+
+function collectIds(root, { extensions, patterns }) {
+  const ids = new Set();
+  for (const entry of readdirSync(root, { recursive: true })) {
+    const rel = String(entry);
+    if (SKIP_DIRS.test(rel) || !extensions.test(rel)) continue;
+    const text = readFileSync(join(root, rel), 'utf8');
+    for (const re of patterns) {
+      re.lastIndex = 0;
+      let m;
+      while ((m = re.exec(text)) !== null) ids.add(m[1]);
+    }
+  }
+  return ids;
+}
+
+const lockFile = (root) => join(root, '.claude', 'param-ids.lock.json');
+const save = (root, ids) => writeFileSync(lockFile(root), JSON.stringify([...ids].sort(), null, 2) + '\n');
+
+function main(text) {
+  if (process.argv.includes('--init')) {
+    const ids = collectIds(ROOT, loadConfig(ROOT));
+    save(ROOT, ids);
+    console.log(`Locked ${ids.size} parameter IDs in ${relative(ROOT, lockFile(ROOT))}`);
+    return 0;
+  }
+
+  let payload = {};
+  try {
+    payload = JSON.parse(text || '{}');
+  } catch {
+    // run by hand without stdin
+  }
+  // Run by hand (no tool): the main checkout. Otherwise every checkout a write of an id file landed in.
+  const files = payload.tool_name ? writesOf(payload).map((w) => w.path).filter((f) => insideProject(f)) : [null];
+  const seen = new Set();
+  for (const file of files) {
+    const root = file ? checkoutRoot(file) : ROOT;
+    if (seen.has(root)) continue;
+    const config = loadConfig(file ? claudeRoot(file) : ROOT);
+    if (file && !config.extensions.test(file)) continue; // not a file ids are written in
+    seen.add(root);
+    const code = judge(root, config);
+    if (code) return code;
+  }
+  return 0;
+}
+
+// The checkout's own lock only: main's lock may hold ids a worktree branch never had.
+function judge(root, config) {
+  if (!existsSync(lockFile(root))) return 0;
+  const current = collectIds(root, config);
+
+  const locked = new Set(JSON.parse(readFileSync(lockFile(root), 'utf8')));
+  const missing = [...locked].filter((id) => !current.has(id));
+  if (missing.length > 0) {
+    process.stderr.write(
+      `Parameter IDs removed or renamed: ${missing.join(', ')}\n` +
+        'IDs never change once assigned (saved patches and host automation use them). ' +
+        'Restore them; if a control changed meaning, add a NEW ID and migrate old patches in setStateInformation. ' +
+        'See .claude/rules/parameter-ids-never-change.md\n',
+    );
+    return 2;
+  }
+
+  const added = [...current].filter((id) => !locked.has(id));
+  if (added.length > 0) save(root, new Set([...locked, ...added]));
+  return 0;
+}
+
+function selftest() {
+  const hook = fileURLToPath(import.meta.url);
+  const params = (...ids) => ids.map((id) => `auto p_${id} = juce::ParameterID { "${id}", 1 };`).join('\n') + '\n';
+  const dir = scratchProject({ 'src/params/Params.h': params('cutoff', 'res') }, { folders: {}, concepts: {} });
+  const unlocked = scratchProject({ 'src/params/Params.h': params('cutoff') });
+  const file = join(dir, 'src/params/Params.h');
+  const post = (text) => (put(file, text), runHook(hook, dir, writeOf(file, text)));
+  const initStatus = runHook(hook, dir, null, ['--init']);
+  const locked = () => JSON.parse(readFileSync(join(dir, '.claude/param-ids.lock.json'), 'utf8'));
+  const cases = [
+    ['--init writes the lock', initStatus === 0 && locked().join() === 'cutoff,res', true],
+    ['an id removed', post(params('cutoff')), 2],
+    ['an id renamed', post(params('cutoff', 'resonance')), 2],
+    ['an id added', post(params('cutoff', 'res', 'drive')), 0],
+    ['the new id joins the lock', locked().includes('drive'), true],
+    ['a project with no lock', runHook(hook, unlocked, writeOf(join(unlocked, 'src/params/Params.h'))), 0],
+    ['another project is not ours', runHook(hook, dir, writeOf(join(dirname(dir), 'elsewhere/Params.h'))), 0],
+  ];
+  return verdicts('param-id-lock', cases);
+}
+
+export const hook = main; // run-hooks.mjs calls it with the event's text (KWB-24)
+if (isMain(import.meta.url)) process.exit(process.argv.includes('--selftest') ? selftest() : process.argv.includes('--init') ? main('') : await asHook('param-id-lock', main));

package/packs/audio-core/hooks/realtime-guard.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+// PreToolUse hook (Write|Edit|MultiEdit|NotebookEdit|Bash, every route: lib/writes.mjs): blocks writes that ADD realtime-unsafe code to
+// audio-thread functions in C++ files. Exit 2 = block, stderr goes back to Claude. `--selftest` proves it.
+import { readFileSync } from 'node:fs';
+import { writesOf } from './lib/writes.mjs';
+import { findViolations, violationKey } from './lib/realtime-checks.mjs';
+import { insideProject } from './lib/project.mjs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { editOf, runHook, scratchProject, verdicts, writeOf } from './lib/selftest.mjs';
+import { asHook, isMain } from './lib/hook-log.mjs';
+
+const CPP = /\.(cpp|cc|cxx|h|hh|hpp|mm)$/;
+
+function main(text) {
+  let payload;
+  try {
+    payload = JSON.parse(text);
+  } catch {
+    return 0;
+  }
+  for (const w of writesOf(payload)) {
+    if (w.after === null || !CPP.test(w.path) || !insideProject(w.path)) continue;
+    const code = judge(w.path, w);
+    if (code) return code;
+  }
+  return 0;
+}
+
+function judge(file, result) {
+  const input = { file_path: file };
+
+  const existing = new Set(findViolations(result.before).map(violationKey));
+  const added = findViolations(result.after).filter((v) => !existing.has(violationKey(v)));
+  if (added.length === 0) return 0;
+
+  const lines = added.slice(0, 12).map((v) => `  line ${v.line} in ${v.func}(): ${v.why}\n      ${v.text}`);
+  const more = added.length > 12 ? `\n  ...and ${added.length - 12} more` : '';
+  process.stderr.write(
+    `BLOCKED by realtime-guard: this edit adds realtime-unsafe code to audio-thread functions in ${input.file_path}\n` +
+      `${lines.join('\n')}${more}\n\n` +
+      'Fix: pre-allocate in prepareToPlay(), cache parameter pointers in the constructor, hand data to the UI via atomics/AbstractFifo + Timer.\n' +
+      'If a line is a deliberate safe exception, end it with `// rt-ok: <reason>`.\n' +
+      'See .claude/rules/audio-thread-realtime-safe.md.\n',
+  );
+  return 2;
+}
+
+function selftest() {
+  const hook = fileURLToPath(import.meta.url);
+  const block = (body) => `void Voice::processBlock (juce::AudioBuffer<float>& b, juce::MidiBuffer& m)\n{\n    juce::ScopedNoDenormals nd;\n${body}\n}\n`;
+  const old = block('    auto* x = new float[64]; // legacy');
+  const dir = scratchProject({ 'src/audio/Old.cpp': old });
+  const w = (file, body) => runHook(hook, dir, writeOf(join(dir, file), block(body)));
+  return verdicts('realtime-guard', [
+    ['new in processBlock', w('src/audio/Voice.cpp', '    auto* x = new float[64];'), 2],
+    ['a lock in processBlock', w('src/audio/Voice.cpp', '    const juce::ScopedLock sl (lock);'), 2],
+    ['plain arithmetic', w('src/audio/Voice.cpp', '    b.applyGain (0.5f);'), 0],
+    ['an rt-ok exception', w('src/audio/Voice.cpp', '    auto* x = new float[64]; // rt-ok: test only'), 0],
+    ['a fault already there is not added', runHook(hook, dir, editOf(join(dir, 'src/audio/Old.cpp'), 'ScopedNoDenormals nd;', 'ScopedNoDenormals noDenormals;')), 0],
+    ['not C++', runHook(hook, dir, writeOf(join(dir, 'tools/x.py'), 'x = [1]\n')), 0],
+    ['another project is not ours', runHook(hook, dir, writeOf(join(dirname(dir), 'elsewhere/Voice.cpp'), block('    auto* x = new float[64];'))), 0],
+  ]);
+}
+
+export const hook = main; // run-hooks.mjs calls it with the event's text (KWB-24)
+if (isMain(import.meta.url)) process.exit(process.argv.includes('--selftest') ? selftest() : await asHook('realtime-guard', main));

package/packs/audio-core/pack.json

@@ -0,0 +1,187 @@
+{
+  "name": "audio-core",
+  "version": "1.0.0",
+  "description": "Any JUCE synth or effect: realtime safety, DSP quality, state, parameters, performance.",
+  "type": "stock",
+  "author": "claude-packs",
+  "license": "MIT",
+  "homepage": "https://github.com/TheDecipherist/claude-packs",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TheDecipherist/claude-packs.git",
+    "directory": "packs/audio-core"
+  },
+  "keywords": [
+    "juce",
+    "audio",
+    "dsp"
+  ],
+  "engines": {
+    "claude-packs": ">=0.19.0"
+  },
+  "synth": true,
+  "folders": {
+    "app": {
+      "path": "src/app",
+      "purpose": "plugin and standalone entry, processor shell, editor shell"
+    },
+    "audio": {
+      "path": "src/audio",
+      "purpose": "audio-thread code: block processing, voices, note ledger, parameter snapshot"
+    },
+    "engines": {
+      "path": "src/engines",
+      "purpose": "sound engines (one folder per oscillator kind)"
+    },
+    "dsp": {
+      "path": "src/dsp",
+      "purpose": "filters, effects, dynamics and shared DSP blocks"
+    },
+    "params": {
+      "path": "src/params",
+      "purpose": "parameter definitions, IDs, patches, presets, state load and save"
+    },
+    "bench": {
+      "path": "bench",
+      "purpose": "benchmarks (release build, worst block)"
+    },
+    "data": {
+      "path": "data",
+      "purpose": "factory bank (factory.csv), params.csv, records and derived tables"
+    },
+    "panel": {
+      "path": "panel",
+      "purpose": "panel.json, bindings.json and the theme (rendered by synthpanel-creator)"
+    }
+  },
+  "concepts": {
+    "audio": [
+      "audio",
+      "app"
+    ],
+    "dsp": [
+      "dsp",
+      "engines"
+    ],
+    "params": [
+      "params"
+    ],
+    "ui": [
+      "app"
+    ],
+    "bench": [
+      "bench"
+    ],
+    "presets": [
+      "data/factory.csv",
+      "data/params.csv",
+      "presets/**",
+      "banks/**"
+    ],
+    "panel-spec": [
+      "panel",
+      "**/bindings.json"
+    ]
+  },
+  "skillsIn": null,
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit|NotebookEdit|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/realtime-guard.mjs\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit|NotebookEdit|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/param-id-lock.mjs\"",
+            "timeout": 20
+          }
+        ]
+      }
+    ]
+  },
+  "kinds": {
+    "audio-entry": {
+      "what": "processBlock, voices, voice allocation, the note ledger, the parameter snapshot",
+      "in": "audio",
+      "concepts": [
+        "audio",
+        "dsp",
+        "tests"
+      ],
+      "content": "\\b(processBlock|renderNextBlock|getNextAudioBlock)\\s*\\("
+    },
+    "dsp-block": {
+      "what": "a filter, effect, dynamics stage or shared DSP block (one folder per block)",
+      "in": "dsp"
+    },
+    "engine": {
+      "what": "an oscillator or sound engine (one folder per kind)",
+      "in": "engines"
+    },
+    "params": {
+      "what": "parameter IDs and layout, patch and state load/save",
+      "in": "params",
+      "concepts": [
+        "params"
+      ],
+      "files": [
+        "**/*ParameterIDs.*",
+        "**/*Params.h",
+        "**/*Params.cpp",
+        "**/*Parameters.h",
+        "**/*Parameters.cpp"
+      ]
+    },
+    "editor": {
+      "what": "the plugin and standalone entry, processor shell, editor and UI components",
+      "in": "app",
+      "concepts": [
+        "ui",
+        "painter",
+        "app",
+        "tests"
+      ],
+      "content": "\\bvoid\\s+(?:\\w+::)*paint\\s*\\(\\s*(?:juce::)?Graphics\\b",
+      "contentWas": [
+        "\\bvoid\\s+paint\\s*\\(\\s*(juce::)?Graphics\\b"
+      ]
+    },
+    "bank": {
+      "what": "the factory bank and the parameter table",
+      "in": "data",
+      "concepts": [
+        "presets"
+      ],
+      "files": [
+        "**/factory.csv",
+        "**/params.csv"
+      ]
+    },
+    "panel": {
+      "what": "the panel spec, bindings and theme",
+      "in": "panel",
+      "concepts": [
+        "panel-spec"
+      ],
+      "files": [
+        "**/panel.json",
+        "**/bindings.json"
+      ]
+    },
+    "bench": {
+      "what": "benchmarks (Release, worst block)",
+      "in": "bench"
+    }
+  }
+}

package/packs/audio-core/rules/audio-thread-realtime-safe.md

@@ -0,0 +1,27 @@
+---
+# concepts: audio
+paths:
+  - "placeholder"
+---
+
+# The audio thread never allocates, locks, waits or does I/O
+
+<constraints>
+Always do:
+- Allocate every buffer, delay line, voice and table in `prepareToPlay()` (or the constructor), sized for the worst case.
+- Treat everything `processBlock()` calls (`renderNextBlock`, voice code, `processSample`, effect `process`) as audio-thread code too.
+- Mark audio-thread functions outside the standard names with `[[clang::nonblocking]]`, so both the hook and RealtimeSanitizer cover them.
+- Write `// rt-ok: <reason>` at the end of a line that is a deliberate, safe exception (e.g. `setSize(..., avoidReallocating = true)` within reserved capacity).
+
+Never do (inside audio-thread code):
+- `new`, `delete`, `malloc`, `free`, `make_unique`, `make_shared` (placement `new (ptr) T` is fine).
+- Container growth: `push_back`, `emplace_back`, `insert`, `resize`, `reserve`, `assign`.
+- Locks or waits: `ScopedLock`, `CriticalSection`, `std::mutex`, `lock_guard`, `unique_lock`, `scoped_lock`, condition variables, `sleep`.
+- I/O or logging: `File`, streams, `fopen`, `DBG`, `std::cout`, `printf`, `Logger`.
+- Building strings: `juce::String`, `std::string`, `std::to_string`.
+- `throw`.
+</constraints>
+
+## Check
+- **Hook (blocks the edit):** `.claude/hooks/realtime-guard.mjs` scans the bodies of `processBlock`, `processBlockBypassed`, `renderNextBlock`, `processSample` and every `[[clang::nonblocking]]` function. It blocks only violations the edit *adds*, so existing code doesn't stall unrelated work.
+- **Runtime (catches what grep can't, such as allocations inside called functions):** build a debug standalone with Clang's RealtimeSanitizer (`-fsanitize=realtime`, LLVM 20+). It aborts with a stack trace on any allocation or lock inside a `nonblocking` function. Xcode's Apple clang does not support it, so on macOS use Homebrew LLVM for that debug build (or the rtsan standalone library, which its authors describe as fragile).

package/packs/audio-core/rules/audio-ui-thread-handoff.md

@@ -0,0 +1,21 @@
+---
+# concepts: audio, ui
+paths:
+  - "placeholder"
+---
+
+# Audio and UI threads talk only through atomics and lock-free FIFOs
+
+<constraints>
+Always do:
+- UI → audio: write plain values to `std::atomic<T>` (with `is_always_lock_free` true), or go through the parameter system.
+- Audio → UI (meters, playheads, matrix position, scope data): the audio thread writes atomics or pushes into a pre-sized `juce::AbstractFifo` ring; a `juce::Timer` on the message thread polls and repaints.
+- Pass complex objects (a rebuilt wavetable, a new route list) by building them on the message thread and handing over a pointer through a lock-free swap or FIFO. Free the old one on the message thread.
+
+Never do:
+- Call `repaint()`, touch the editor, `getActiveEditor()`, `MessageManager`, `callAsync`, `sendChangeMessage()` or `triggerAsyncUpdate()` from the audio thread. `triggerAsyncUpdate()` posts to the OS message queue when an update isn't already pending, and that path isn't guaranteed lock- or allocation-free.
+- Share a `std::vector`, `juce::Array` or `ValueTree` between threads where one side may modify it.
+</constraints>
+
+## Check
+The realtime-guard hook flags these UI and message calls inside audio-thread bodies. For cross-thread container sharing, use ThreadSanitizer in a debug build (`-fsanitize=thread`), which reports the data race at runtime.

package/packs/audio-core/rules/boundary-tests-cross-the-boundary.md

@@ -0,0 +1,16 @@
+---
+# concepts: audio, ui
+paths:
+  - "placeholder"
+---
+
+# A thread or process boundary is tested from both sides at once
+
+<constraints>
+Always do:
+- For every handoff between the audio thread and the UI (lock-free FIFO, snapshot ring, atomics), write at least one test that runs both sides together: the audio side publishes, and the test asserts the UI side observes exactly that (value, order, no drops at the stated rate).
+- Do the same for anything that crosses a process (a render probe the test spawns, a plugin host): assert the parent sees what the child recorded.
+
+Never do:
+- Count two one-sided tests (the producer writes, the consumer reads a fake) as covering the boundary. That is how a flag set on one side never reaches the other.
+</constraints>

package/packs/audio-core/rules/build-flags-safe.md

@@ -0,0 +1,20 @@
+---
+# concepts: build
+paths:
+  - "placeholder"
+---
+
+# Build flags: warnings are errors, no fast-math
+
+<constraints>
+Always do:
+- Build your own targets with `-Wall -Wextra -Wpedantic -Werror` (not JUCE's modules, which aren't warning-clean). Use `juce::juce_recommended_warning_flags` plus `-Werror` on your own sources.
+- Keep sanitizer builds as presets: ASan + UBSan, TSan, and an RTSan debug standalone built with Homebrew LLVM 20+ (Apple clang has no RealtimeSanitizer).
+
+Never do:
+- Add `-ffast-math`, `-Ofast` or `/fp:fast`. They let the compiler assume NaN and Inf never happen, which silently deletes `isfinite` guards and breaks compensated sums.
+</constraints>
+
+## Check
+- `.claude/checks/no-fast-math.json` blocks fast-math flags being added.
+- `.claude/checks/keep-werror.json` blocks an edit that removes `-Werror` from a CMake file that had it.

package/packs/audio-core/rules/cached-parameter-pointers.md

@@ -0,0 +1,28 @@
+---
+# concepts: audio
+paths:
+  - "placeholder"
+---
+
+# Parameter pointers are looked up once, never per block
+
+<constraints>
+Always do:
+- In the processor constructor, cache `std::atomic<float>*` from `apvts.getRawParameterValue(id)` (or the typed `AudioParameterFloat*` etc.), and `jassert` that each one is non-null.
+- In audio code, read with `->load()` once per block, then smooth (see smooth-continuous-parameters).
+
+Never do:
+- Call `getRawParameterValue()`, `getParameter()` or any lookup by string ID inside `processBlock` or anything it calls. Those are string compares and map lookups, every block, on the audio thread.
+</constraints>
+
+```cpp
+// constructor
+cutoff = apvts.getRawParameterValue (ids::cutoff.getParamID());
+jassert (cutoff != nullptr);
+
+// processBlock
+const auto target = cutoff->load();
+```
+
+## Check
+The realtime-guard hook flags `getRawParameterValue(` and `getParameter(` inside audio-thread bodies.

package/packs/audio-core/rules/clang-tidy-core-guidelines.md

@@ -0,0 +1,21 @@
+---
+# concepts: cpp
+paths:
+  - "placeholder"
+---
+
+# General C++ hygiene is checked by clang-tidy, not by memory
+
+<constraints>
+Always do:
+- Keep the `.clang-tidy` from this pack at the repo root and run it on your own sources in CI and before merging (`run-clang-tidy -p build -header-filter='.*/(Source|src|lib|include)/.*'`). Export `compile_commands.json` from CMake.
+- Fix what it reports: C-style casts, narrowing conversions, `NULL`/`0` as a pointer, missing `override`, implicit single-argument constructors, Rule of Zero/Five violations, `using namespace` in headers, copying range-for loops, by-value parameters that should be `const&`, `std::move` that blocks return-value elision.
+- Mark leaf classes `final`.
+
+Never do:
+- Apply general C++ advice on locking, `shared_ptr` or exceptions to audio-thread code. The realtime rules win there (`audio-thread-realtime-safe.md`).
+- Run clang-tidy on JUCE's own modules or `JuceLibraryCode`.
+</constraints>
+
+## Check
+`run-clang-tidy` with `WarningsAsErrors: '*'` fails the build on any finding. Sources: the C++ Core Guidelines checklist (ECC cpp-coding-standards, jeffallan cpp-pro) and the efficient-code-cpp gotchas, turned into tool checks.

package/packs/audio-core/rules/control-reaches-every-surface.md

@@ -0,0 +1,23 @@
+---
+# concepts: params, ui
+paths:
+  - "placeholder"
+---
+
+# A new or changed control is proven at every surface it has
+
+<constraints>
+Always do:
+- For every control you add or change, prove each surface it has with a real invocation, not a unit call:
+  1. host automation: set the parameter by its ID, render, and the sound changes;
+  2. the editor widget moves the same parameter, and shows the value the host set;
+  3. patch save and load round-trips the exact value;
+  4. the init patch and the reset value match the spec;
+  5. MIDI CC or learn, if the control has one;
+  6. undo restores it, as one step per gesture.
+- Record the evidence for each surface in the step or bug log (command plus result). Use the `prove-control` skill.
+
+Never do:
+- Call a control done because the DSP function passes its unit test. "The function works" and "the knob reaches the function" are different claims.
+- Add a control that exists in the editor but not in the parameter tree, or the other way round, unless the spec says it's performance-only.
+</constraints>

package/packs/audio-core/rules/cpu-worst-case-per-block.md

@@ -0,0 +1,26 @@
+---
+# concepts: audio, bench
+paths:
+  - "placeholder"
+---
+
+# CPU is judged by the worst block, not the average
+
+<constraints>
+Always do:
+- Gate on p99, p99.9 and maximum block time, plus the count of blocks over their deadline (`numSamples / sampleRate`), at 1, 8, 32 and 96 voices, with the heaviest patch and every row of the matrix moving.
+- Include digital silence and "identical left and right" as their own cases. Silence can cost more than signal (denormals, gates).
+- Label every CPU figure with what it measures (callback duty, one core, or process CPU), sample rate, block size, and whether the editor was open.
+- Attribute cost before optimising: compare editor closed vs open, bypassed vs active, silence vs signal.
+- Build the benchmark with the plugin's exact compile and link flags (including LTO), constructing the engine the same way it ships (heap, not stack).
+- Touch every pre-allocated buffer once in `prepareToPlay` so the first callbacks don't stall on page faults.
+- Look at the curve across voice counts. Anything worse than linear growth is a bug.
+
+Never do:
+- Report average CPU as the performance figure.
+- Compare numbers from different benchmark-harness versions. When the harness changes, re-time the old build with the new harness.
+- Time code with anything that logs from inside `processBlock` (JUCE's `PerformanceCounter` writes to the logger).
+</constraints>
+
+## Check
+Benchmark test, offline render: 96 voices at 48 kHz with 64-sample blocks. Pass (house choice): p99.9 under 50% of the deadline, and zero overruns.

package/packs/audio-core/rules/dc-block-after-asymmetry.md

@@ -0,0 +1,22 @@
+---
+# concepts: dsp
+paths:
+  - "placeholder"
+---
+
+# Asymmetric stages are followed by a DC blocker
+
+<constraints>
+Always do:
+- Put a one-pole DC blocker (corner about 5–10 Hz, coefficient computed from the sample rate) after every asymmetric shaper, folder, rectifier or crusher, and inside any feedback loop that contains one.
+- Put a ~5 Hz high-pass after any integrator or leaky accumulator.
+
+Never do:
+- Hard-code the blocker's pole (e.g. `0.995`). It must follow the sample rate.
+</constraints>
+
+## Why
+Even-order distortion creates DC. It eats headroom, shifts the bias of the next nonlinearity, and clicks when the voice stops.
+
+## Check
+Feed a 1 kHz sine with +0.3 offset through the stage for 1 s. Pass (house choice): the mean of the output (`tone-report` prints it) is below −80 dBFS.

package/packs/audio-core/rules/discrete-params-snap.md

@@ -0,0 +1,19 @@
+---
+# concepts: params
+paths:
+  - "placeholder"
+---
+
+# Stepped parameters store the step, never the raw host value
+
+<constraints>
+Always do:
+- Make bool, choice and integer parameters snap any incoming normalised value to the nearest step, and store and report the snapped value. A host may send 0.37 to an on/off switch.
+- Restore exactly the stepped value from saved state.
+
+Never do:
+- Rely on `juce::AudioParameterBool` keeping the snapped value. pluginval 2.0's strict discrete-parameter test fails it because it keeps the raw value. Wrap or replace it.
+</constraints>
+
+## Check
+Unit test per stepped parameter: set normalised 0.37, save state, restore it. Pass: the value equals the stepped value both before and after the round trip.

package/packs/audio-core/rules/double-where-precision-matters.md

@@ -0,0 +1,20 @@
+---
+# concepts: dsp, world
+paths:
+  - "placeholder"
+---
+
+# Phase, sample rate and coefficients are computed in `double`
+
+<constraints>
+Always do:
+- Keep the sample rate, phase accumulators, phase increments and tempo/clock positions in `double`.
+- Compute filter coefficients in `double`. Store them as `float` only after they're normalised.
+- Use a `double` accumulator (or pairwise summation) for RMS, energy, metering and any long running sum.
+
+Never do:
+- Declare `float sampleRate`, `float phase` or `float phaseInc`. Float phase drifts audibly over long notes and slow LFOs; sixteen clocks synced to tempo need the precision.
+</constraints>
+
+## Check
+`.claude/checks/float-phase-or-rate.json` (lesson-checks hook) blocks new `float` declarations of sample rate, phase or phase increment.