fix: scope the O3/fast-math pragma to each header instead of leaking it (#347)

Every algorithm header applied `#pragma GCC optimize("O3", "fast-math")` at
file scope with no pop, so including any of them switched every function
defined later in the translation unit to fast-math (folded NaN checks,
reassociation). Bracket each header with push_options/pop_options at the
same position the pragma used to be, so the library's own code generation is
preserved while consumer code after the include is compiled with the
consumer's flags.

- 98 headers: push_options + optimize ... pop_options (GCC only; clang never
  honoured the pragma and warns on it).
- ComplexNumber.hpp and TwiddleFactorsTable.hpp: add the scoped pragma; they
  previously only got fast-math by leaking from earlier headers.
- Remove the pragma from four controller test TUs.
- Update AGENTS.md, CLAUDE.md, copilot instructions, agent definitions,
  roadmap recipe and performance doc to the scoped pattern.

Closes #334


Claude-Session: https://claude.ai/code/session_01N4pngRiBqeb1xiseKXNLG6

Co-authored-by: Claude <noreply@anthropic.com>

Author: gabrielfrasantos

.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`.