fix: scope the O3/fast-math pragma per header instead of leaking it into the TU

.claude/agents/algo-implementer.md

@@ -28,5 +28,5 @@ from its `roadmap/<domain>/<Name>/` spec into the codebase, following both exact
 - **No comments** (except license/`NOLINT`). Allman braces, brace-init.
 - **Tests**: `TEST_F` on `float`, `StrictMock` only, anonymous-namespace fixture; implement EXACTLY
   the spec's cases — no redundant or extra tests.
-- **Embedded**: `#pragma GCC optimize` + `OPTIMIZE_FOR_SPEED` on hot paths.
+- **Embedded**: scoped `#pragma GCC push_options`/`optimize`/`pop_options` + `OPTIMIZE_FOR_SPEED` on hot paths.
 - **Terse**: no preamble/postamble, no plan restatement, no narration; don't re-read files; batch reads.

.claude/agents/planner.md

@@ -25,7 +25,7 @@ Canonical rules: `AGENTS.md`. Produce plans only — no code edits.
    - [ ] No heap; no recursion; tests too
    - [ ] `template<typename T>` + `static_assert(std::is_floating_point_v<T>)`; `float` only
    - [ ] `TEST_F` on `float` — no `TYPED_TEST`; `StrictMock` only; never plain `TEST()`
-   - [ ] `#pragma GCC optimize` + `OPTIMIZE_FOR_SPEED` on hot paths
+   - [ ] scoped `#pragma GCC push_options`/`optimize`/`pop_options` + `OPTIMIZE_FOR_SPEED` on hot paths
    - [ ] `doc/` update planned
 
 **Terse**: no preamble/postamble, no plan restatement; don't re-read files; batch reads.

.claude/agents/reviewer.md

@@ -35,7 +35,7 @@ End with totals + verdict: APPROVE / REQUEST CHANGES.
 - [ ] `extern template` guarded by `#ifdef NUMERICAL_TOOLBOX_COVERAGE_BUILD`.
 
 **Embedded optimizations (WARNING)**
-- [ ] `#pragma GCC optimize("O3","fast-math")` after `#pragma once` in algorithm headers.
+- [ ] `#pragma GCC push_options` + `optimize("O3","fast-math")` after `#pragma once`, matching `pop_options` at end of algorithm headers (no TU leak; none in test `.cpp`).
 - [ ] `OPTIMIZE_FOR_SPEED` on `Filter/Compute/Update/Solve/Step`.
 
 **Namespaces (WARNING)**

.github/agents/algo-implementer.agent.md

@@ -31,5 +31,5 @@ Authoritative rules: `AGENTS.md`. Recipe: `roadmap/DEPLOYMENT.md`. Follow both e
 - **No comments** (except license/`NOLINT`). Allman braces, brace-init.
 - **Tests**: `TEST_F` on `float`, `StrictMock` only, anonymous-namespace fixture; implement EXACTLY
   the spec's cases — no redundant or extra tests.
-- **Embedded**: `#pragma GCC optimize` + `OPTIMIZE_FOR_SPEED` on hot paths.
+- **Embedded**: scoped `#pragma GCC push_options`/`optimize`/`pop_options` + `OPTIMIZE_FOR_SPEED` on hot paths.
 - **Terse**: no preamble/postamble, no plan restatement, no narration; don't re-read files; batch reads.

.github/agents/planner.agent.md

@@ -28,7 +28,7 @@ Canonical rules: `AGENTS.md`. Produce plans only — no code edits.
    - [ ] No heap; no recursion; tests too
    - [ ] `template<typename T>` + `static_assert(std::is_floating_point_v<T>)`; `float` only
    - [ ] `TEST_F` on `float` — no `TYPED_TEST`; `StrictMock` only; never plain `TEST()`
-   - [ ] `#pragma GCC optimize` + `OPTIMIZE_FOR_SPEED` on hot paths
+   - [ ] scoped `#pragma GCC push_options`/`optimize`/`pop_options` + `OPTIMIZE_FOR_SPEED` on hot paths
    - [ ] `doc/` update planned
 
 **Terse**: no preamble/postamble, no plan restatement; don't re-read files; batch reads.

.github/agents/reviewer.agent.md

@@ -41,7 +41,7 @@ End with totals + verdict: APPROVE / REQUEST CHANGES.
 - [ ] `extern template` guarded by `#ifdef NUMERICAL_TOOLBOX_COVERAGE_BUILD`.
 
 **Embedded optimizations (WARNING)**
-- [ ] `#pragma GCC optimize("O3","fast-math")` after `#pragma once` in algorithm headers.
+- [ ] `#pragma GCC push_options` + `optimize("O3","fast-math")` after `#pragma once`, matching `pop_options` at end of algorithm headers (no TU leak; none in test `.cpp`).
 - [ ] `OPTIMIZE_FOR_SPEED` on `Filter/Compute/Update/Solve/Step`.
 
 **Namespaces (WARNING)**

.github/copilot-instructions.md

@@ -6,7 +6,7 @@ Code-file specifics: `.github/instructions/` (applyTo-scoped). Deployment recipe
 Essentials (full detail in AGENTS.md):
 - **No heap** — bounded containers / `std::array` / `std::optional`; no recursion; tests too.
 - **Float-only** — generic `template<typename T>` + `static_assert(std::is_floating_point_v<T>)`; instantiate/test `float`; no Q15/Q31.
-- **Embedded** — `#pragma GCC optimize("O3","fast-math")` + `OPTIMIZE_FOR_SPEED` on hot paths.
+- **Embedded** — scoped `#pragma GCC push_options` / `optimize("O3","fast-math")` … `pop_options` (never leak to the TU) + `OPTIMIZE_FOR_SPEED` on hot paths.
 - **No comments** (except license/NOLINT). Allman braces, brace-init, PascalCase/camelCase.
 - **Tests** — `TEST_F` on `float`, `StrictMock` only, never plain `TEST()`, no redundant cases.
 - **No exceptions** — `std::optional`/status enums; interfaces `virtual ~I() = default`.

.github/instructions/numerical-cpp.instructions.md

@@ -41,16 +41,25 @@ To replace a function with a platform-specific implementation, define the corres
 
 ## Embedded Optimizations
 
-Every algorithm header MUST include:
+Every algorithm header MUST bracket its body with a scoped pragma, so the options never leak into the including translation unit:
 
 ```cpp
 #pragma once
 
-#if defined(__GNUC__) || defined(__clang__)
+#if defined(__GNUC__) && !defined(__clang__)
+#pragma GCC push_options
 #pragma GCC optimize("O3", "fast-math")
 #endif
+
+// ... includes and header body ...
+
+#if defined(__GNUC__) && !defined(__clang__)
+#pragma GCC pop_options
+#endif
 ```
 
+The `pop_options` block is the last thing in the header. Never use the pragma in test `.cpp` files.
+
 Apply `OPTIMIZE_FOR_SPEED` (from `numerical/math/CompilerOptimizations.hpp`) on hot-path methods: `Compute()`, `Filter()`, `Calculate()`, `Solve()`, `Update()`, `Step()`.
 
 ## Naming

AGENTS.md

@@ -26,12 +26,24 @@ resource-constrained embedded systems. Real-time, deterministic, no heap.
 
 ```cpp
 #pragma once
-#if defined(__GNUC__) || defined(__clang__)
+#if defined(__GNUC__) && !defined(__clang__)
+#pragma GCC push_options
 #pragma GCC optimize("O3", "fast-math")
 #endif
 #include "numerical/math/CompilerOptimizations.hpp"
+
+// ... header body ...
+
+#if defined(__GNUC__) && !defined(__clang__)
+#pragma GCC pop_options
+#endif
 ```
 
+The `pop_options` block is the **last thing in the header**: the pragma must never leak into the
+including translation unit (it would silently apply fast-math, e.g. folded NaN checks and
+reassociation, to unrelated code). Use `math::IsFinite` for finiteness checks. Test `.cpp` files
+never use the pragma.
+
 `OPTIMIZE_FOR_SPEED` on hot paths (`Filter/Compute/Update/Solve/Step`). Pure interfaces exempt.
 
 ## Style

CLAUDE.md

@@ -6,7 +6,7 @@ Code-file specifics: `.github/instructions/`. Deployment recipe: `roadmap/DEPLOY
 Essentials (full detail in AGENTS.md):
 - **No heap** — bounded containers / `std::array` / `std::optional`; no recursion; tests too.
 - **Float-only** — generic `template<typename T>` + `static_assert(std::is_floating_point_v<T>)`; instantiate/test `float`; no Q15/Q31.
-- **Embedded** — `#pragma GCC optimize("O3","fast-math")` + `OPTIMIZE_FOR_SPEED` on hot paths.
+- **Embedded** — scoped `#pragma GCC push_options` / `optimize("O3","fast-math")` … `pop_options` (never leak to the TU) + `OPTIMIZE_FOR_SPEED` on hot paths.
 - **No comments** (except license/NOLINT). Allman braces, brace-init, PascalCase/camelCase.
 - **Tests** — `TEST_F` on `float`, `StrictMock` only, never plain `TEST()`, no redundant cases.
 - **No exceptions** — `std::optional`/status enums; interfaces `virtual ~I() = default`.

ROADMAP.md

@@ -52,7 +52,7 @@ on bounded `math::Vector`/`math::Matrix` inputs; tests are `TEST_F` on `float`.
 Every new component should follow the established repository conventions:
 
 - [ ] Header-only template supporting `float` / `math::Q15` / `math::Q31` (or *float-first* where noted)
-- [ ] `#pragma GCC optimize("O3", "fast-math")` after `#pragma once`; `OPTIMIZE_FOR_SPEED` on hot paths
+- [ ] Scoped `#pragma GCC push_options` / `optimize("O3", "fast-math")` after `#pragma once`, `pop_options` at end of file; `OPTIMIZE_FOR_SPEED` on hot paths
 - [ ] No heap, no recursion, bounded containers (`infra::BoundedVector`, `std::array`)
 - [ ] `static_assert` on supported types and dimensions
 - [ ] Typed tests (`TYPED_TEST`) for multi-type components; `TEST_F` for single-type; `StrictMock` only

doc/performance-optimization/README.md

@@ -207,12 +207,17 @@ set(CMAKE_CXX_FLAGS_DEBUG "-Og -g" CACHE STRING "Debug flags" FORCE)
 ### Solution 2: Per-File Optimization Pragmas
 
 ```cpp
-// At the top of performance-critical .cpp files
-#if defined(__GNUC__) || defined(__clang__)
+// Bracket the performance-critical code; never leave the options active for the rest of the TU
+#if defined(__GNUC__) && !defined(__clang__)
+#pragma GCC push_options
 #pragma GCC optimize("O3", "fast-math")
 #endif
 
-// Rest of implementation...
+// Performance-critical implementation...
+
+#if defined(__GNUC__) && !defined(__clang__)
+#pragma GCC pop_options
+#endif
 ```
 
 ### Solution 3: Per-Function Attributes

numerical/analysis/ConvolutionCorrelation.hpp

@@ -1,6 +1,7 @@
 #pragma once
 
-#if defined(__GNUC__) || defined(__clang__)
+#if defined(__GNUC__) && !defined(__clang__)
+#pragma GCC push_options
 #pragma GCC optimize("O3", "fast-math")
 #endif
 
@@ -158,3 +159,7 @@ namespace analysis
         FastFourierTransform<float>&);
 #endif
 }
+
+#if defined(__GNUC__) && !defined(__clang__)
+#pragma GCC pop_options
+#endif

numerical/analysis/Decibels.hpp

@@ -1,6 +1,7 @@
 #pragma once
 
-#if defined(__GNUC__) || defined(__clang__)
+#if defined(__GNUC__) && !defined(__clang__)
+#pragma GCC push_options
 #pragma GCC optimize("O3", "fast-math")
 #endif
 
@@ -48,3 +49,7 @@ namespace analysis
         return ToDecibels(maxRatio) - ToDecibels(minRatio);
     }
 }
+
+#if defined(__GNUC__) && !defined(__clang__)
+#pragma GCC pop_options
+#endif

numerical/analysis/DiscreteCosineTransform.hpp

@@ -1,6 +1,7 @@
 #pragma once
 
-#if defined(__GNUC__) || defined(__clang__)
+#if defined(__GNUC__) && !defined(__clang__)
+#pragma GCC push_options
 #pragma GCC optimize("O3", "fast-math")
 #endif
 
@@ -112,3 +113,7 @@ namespace analysis
     extern template class DiscreteCosineTransform<float, 8>;
 #endif
 }
+
+#if defined(__GNUC__) && !defined(__clang__)
+#pragma GCC pop_options
+#endif

numerical/analysis/DiscreteWaveletTransform.hpp

@@ -1,6 +1,7 @@
 #pragma once
 
-#if defined(__GNUC__) || defined(__clang__)
+#if defined(__GNUC__) && !defined(__clang__)
+#pragma GCC push_options
 #pragma GCC optimize("O3", "fast-math")
 #endif
 
@@ -260,3 +261,7 @@ namespace analysis
     extern template class DiscreteWaveletTransform<float, 16, 3, 4>;
 #endif
 }
+
+#if defined(__GNUC__) && !defined(__clang__)
+#pragma GCC pop_options
+#endif

numerical/analysis/FastFourierTransformRadix2Impl.hpp

@@ -1,6 +1,7 @@
 #pragma once
 
-#if defined(__GNUC__) || defined(__clang__)
+#if defined(__GNUC__) && !defined(__clang__)
+#pragma GCC push_options
 #pragma GCC optimize("O3", "fast-math")
 #endif
 
@@ -143,3 +144,7 @@ namespace analysis
     extern template class FastFourierTransformRadix2Impl<math::Q31, 8>;
 #endif
 }
+
+#if defined(__GNUC__) && !defined(__clang__)
+#pragma GCC pop_options
+#endif

numerical/analysis/GoertzelAlgorithm.hpp

@@ -1,6 +1,7 @@
 #pragma once
 
-#if defined(__GNUC__) || defined(__clang__)
+#if defined(__GNUC__) && !defined(__clang__)
+#pragma GCC push_options
 #pragma GCC optimize("O3", "fast-math")
 #endif
 
@@ -123,3 +124,7 @@ namespace analysis
     extern template class GoertzelAlgorithm<float>;
 }
 #endif
+
+#if defined(__GNUC__) && !defined(__clang__)
+#pragma GCC pop_options
+#endif

numerical/analysis/HilbertTransform.hpp

@@ -1,6 +1,7 @@
 #pragma once
 
-#if defined(__GNUC__) || defined(__clang__)
+#if defined(__GNUC__) && !defined(__clang__)
+#pragma GCC push_options
 #pragma GCC optimize("O3", "fast-math")
 #endif
 
@@ -164,3 +165,7 @@ namespace analysis
     extern template class HilbertFir<float, 31>;
 #endif
 }
+
+#if defined(__GNUC__) && !defined(__clang__)
+#pragma GCC pop_options
+#endif

numerical/analysis/PowerDensitySpectrum.hpp

@@ -1,6 +1,7 @@
 #pragma once
 
-#if defined(__GNUC__) || defined(__clang__)
+#if defined(__GNUC__) && !defined(__clang__)
+#pragma GCC push_options
 #pragma GCC optimize("O3", "fast-math")
 #endif
 
@@ -128,3 +129,7 @@ namespace analysis
     extern template class PowerSpectralDensity<float, 512, test::FftStub<float, 512>, test::TwiddleFactorsStub<float, 256>, 0>;
 #endif
 }
+
+#if defined(__GNUC__) && !defined(__clang__)
+#pragma GCC pop_options
+#endif

numerical/analysis/RealFastFourierTransform.hpp

@@ -1,6 +1,7 @@
 #pragma once
 
-#if defined(__GNUC__) || defined(__clang__)
+#if defined(__GNUC__) && !defined(__clang__)
+#pragma GCC push_options
 #pragma GCC optimize("O3", "fast-math")
 #endif
 
@@ -123,3 +124,7 @@ namespace analysis
     extern template class RealFastFourierTransform<float, 16>;
 #endif
 }
+
+#if defined(__GNUC__) && !defined(__clang__)
+#pragma GCC pop_options
+#endif

numerical/analysis/SignalDetectors.hpp

@@ -1,6 +1,7 @@
 #pragma once
 
-#if defined(__GNUC__) || defined(__clang__)
+#if defined(__GNUC__) && !defined(__clang__)
+#pragma GCC push_options
 #pragma GCC optimize("O3", "fast-math")
 #endif
 
@@ -134,3 +135,7 @@ namespace analysis
     extern template class RmsEnvelope<float>;
 #endif
 }
+
+#if defined(__GNUC__) && !defined(__clang__)
+#pragma GCC pop_options
+#endif

numerical/analysis/TwiddleFactorsTable.hpp

@@ -5,6 +5,11 @@
 #include <cmath>
 #include <numbers>
 
+#if defined(__GNUC__) && !defined(__clang__)
+#pragma GCC push_options
+#pragma GCC optimize("O3", "fast-math")
+#endif
+
 namespace analysis
 {
     template<typename QNumberType, std::size_t Length>
@@ -37,3 +42,7 @@ namespace analysis
     extern template class TwiddleFactorsTable<float, 8>;
 }
 #endif
+
+#if defined(__GNUC__) && !defined(__clang__)
+#pragma GCC pop_options
+#endif

numerical/analysis/windowing/Windowing.hpp

@@ -1,6 +1,7 @@
 #pragma once
 
-#if defined(__GNUC__) || defined(__clang__)
+#if defined(__GNUC__) && !defined(__clang__)
+#pragma GCC push_options
 #pragma GCC optimize("O3", "fast-math")
 #endif
 
@@ -126,3 +127,7 @@ namespace windowing
     extern template class RectangularWindow<math::Q31>;
 #endif
 }
+
+#if defined(__GNUC__) && !defined(__clang__)
+#pragma GCC pop_options
+#endif

numerical/control_analysis/ContinuousToDiscrete.hpp

@@ -1,5 +1,6 @@
 #pragma once
-#if defined(__GNUC__) || defined(__clang__)
+#if defined(__GNUC__) && !defined(__clang__)
+#pragma GCC push_options
 #pragma GCC optimize("O3", "fast-math")
 #endif
 #include "numerical/math/CompilerOptimizations.hpp"
@@ -178,3 +179,7 @@ namespace control_analysis
     extern template class ContinuousToDiscrete<float, 2, 1, 1>;
 #endif
 }
+
+#if defined(__GNUC__) && !defined(__clang__)
+#pragma GCC pop_options
+#endif

numerical/control_analysis/ControllabilityObservability.hpp

@@ -1,6 +1,7 @@
 #pragma once
 
-#if defined(__GNUC__) || defined(__clang__)
+#if defined(__GNUC__) && !defined(__clang__)
+#pragma GCC push_options
 #pragma GCC optimize("O3", "fast-math")
 #endif
 
@@ -242,3 +243,7 @@ namespace control_analysis
         math::Matrix<float, 2, 2>&, std::size_t, std::size_t, float);
 #endif
 }
+
+#if defined(__GNUC__) && !defined(__clang__)
+#pragma GCC pop_options
+#endif