# DeepPluck Project Rules

These rules are binding for future Codex work in this repository.

- Before planning or implementing any milestone, read and follow `Docs/Sound/DeepPluck_Sound_Manifest_v1.0.md`.
- Treat the Sound Manifest as a normative product and design document for all sound, DSP, modulation, effects, preset, GUI, and audio-quality/CPU trade-off decisions.
- Every future milestone specification and master prompt must explicitly instruct Codex to read and follow the Sound Manifest before implementation.
- If an implementation decision conflicts with the Sound Manifest, the Sound Manifest takes precedence unless an explicitly approved milestone specification overrides it and documents the reason.
- Use C++20.
- Keep the project on the official JUCE 9 CMake API.
- Treat Windows 11 x64, Visual Studio 2026, MSVC 19.51, Windows SDK 10.0.26100.0, CMake 4.4.3, and JUCE 9.0.1 as the confirmed V0.13.0 reference environment. Other toolchain versions are untested.
- Do not create or use a Projucer project.
- Protect realtime safety in every audio-thread callback: no allocation, locks, file/network access, logging, or GUI access.
- Add no unnecessary dependencies or external files without an explicit requirement.
- Never modify files inside `JUCE/`.
- Never commit build directories or `Artifacts/`.
- Treat the V0.11.0 62-parameter manifest as a frozen public compatibility contract: index, ID, host name, type, version hint, range, interval/choice order, default, skew/mapping, raw unit/meaning, and text semantics may change only through an explicitly approved, documented, migrated, and fully tested compatibility milestone. Never insert a parameter into the frozen 0..61 prefix, rename/reuse an ID, or silently reinterpret persisted/automated raw data.
- Do not remove existing functionality without a concrete reason and documentation.
- Build both Debug and Release after source or build-system changes using the Visual Studio 18 2026 x64 CMake generator.
- Document behavioral, architectural, build, and workflow changes.
- Use English for class, variable, and function names. UI text may be English.
- Do not create a Git commit until required builds have succeeded.
- Do not implement features assigned to later milestones prematurely.
- Never install or copy plugins/applications into system directories automatically.
- Keep `COPY_PLUGIN_AFTER_BUILD` disabled; only project-local artifact copies are permitted.
- Preserve the no-input/stereo-output instrument contract unless a future specification explicitly changes it.
- Keep each DSP class focused on one primary responsibility; the processor orchestrates and the editor owns no DSP.
- Bind APVTS raw parameter pointers outside the audio hot path and use one validated, bounded snapshot per block; never perform APVTS string lookup in voice or sample processing.
- Keep exactly 16 preallocated voices until an explicit future milestone changes the polyphony contract.
- Keep all future global effects after the complete voice sum.
- Run the automated CTest suites in both Debug and Release after relevant engine, parameter, state, or build-system changes.
- Keep `project(... VERSION ...)` as the single authoritative current version and run the artifact-version consistency check for VST3, Standalone, and local copies in both configurations.
- Keep preset scanning, parsing, saving, deletion, and folder operations outside every audio callback; file-based preset identity must never be required to restore host state.
- Update behavior, architecture, tests, and workflow documentation together when their contracts change.
- Do not create an automatic milestone commit until the complete automatable Definition of Done has passed.
- Preserve a genuine unchanged audio reference before tone changes; keep raw renders, fixed-level A/B evidence and provenance outside Git. Technical Track-A completion is not listening approval. Do not retain unapproved Track-B drift, phase variation or saturation; follow `Tests/ToneVoicingAudit.md` for the V0.11.25 evidence contract.
