openspec: fix review issues in performance-teaching-hardening change

- design.md: replace INTERFACE library guidance with simd_dispatch STATIC
  library target; simd_utils remains header-only
- design.md: add explicit GCC/Clang guard for __builtin_cpu_supports;
  document MSVC scalar-fallback constraint
- design.md: remove examples/02-memory-cache/README.md as benchmark
  regression docs target; keep benchmarks/README.md only
- design.md: resolve docs/ placeholders to exact paths
  (docs/en/guides/learning-path.md, docs/en/guides/validation.md)
- design.md: add Mermaid architecture/file-flow diagram
- tasks.md: align with design changes (STATIC lib, exact doc paths)
- specs/benchmark-framework/spec.md: absorb smoke-test scenario from
  ci-quality-assurance; add threshold-configurable scenario
- specs/ci-quality-assurance/spec.md: remove Benchmark Regression
  Script Testable requirement (owned by benchmark-framework)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: LessUp

openspec/changes/performance-teaching-hardening/design.md

@@ -4,16 +4,35 @@
 
 This change closes four teaching gaps on existing surfaces without introducing new modules. All work is bounded to `examples/04-simd-vectorization/`, `scripts/`, `docs/`, and module README files.
 
+## Architecture overview
+
+```mermaid
+graph TD
+    A[runtime_dispatch.cpp] -->|compiled into| B[simd_dispatch STATIC lib]
+    C[simd_utils INTERFACE lib<br/>header-only] -->|provides headers| B
+    B -->|linked by| D[dispatch_example executable]
+    B -->|linked by| E[simd_dispatch_test]
+    F[scripts/compare_benchmarks.py] -->|reads| G[baseline.json]
+    F -->|reads| H[candidate.json]
+    F -->|writes| I[regression table + exit code]
+    J[docs/en/guides/learning-path.md] -->|links to| K[examples/04-simd-vectorization/README.md]
+    J -->|links to| L[docs/en/guides/validation.md]
+    M[README.md] -->|cross-links| L
+    N[benchmarks/README.md] -->|documents| F
+```
+
 ## Design decisions
 
 ### 1. SIMD runtime dispatch
 
 **Goal**: Show readers how to select the fastest available instruction path at runtime rather than at compile time.
 
-**Approach**: Add `examples/04-simd-vectorization/src/runtime_dispatch.cpp` with a `dispatch_add_arrays` function that uses `cpuid` (via `__builtin_cpu_supports` on GCC/Clang) to select AVX2, SSE2, or scalar at runtime. Export the function through the existing `simd_utils` interface library so the existing test runner can reach it.
+**Approach**: Add `examples/04-simd-vectorization/src/runtime_dispatch.cpp` with a `dispatch_add_arrays` function that uses `cpuid` (via `__builtin_cpu_supports` on GCC/Clang) to select AVX2, SSE2, or scalar at runtime. The function is compiled into a new **`STATIC` library target `simd_dispatch`** (not the existing `simd_utils` INTERFACE target) that links `simd_utils` for headers. The example executable and the corresponding test both link `simd_dispatch`. `simd_utils` remains header-only.
 
 **Rationale**: `__builtin_cpu_supports` is available on GCC ≥ 4.8 and Clang ≥ 3.7, covers the C++17 baseline, and avoids a platform-specific CPUID wrapper. The function name stays within the `hpc::simd` namespace. A companion `tests/` entry validates correctness against the scalar reference.
 
+**Compiler guard**: `__builtin_cpu_supports` is a GCC/Clang extension. The implementation must wrap dispatch logic in `#if defined(__GNUC__) || defined(__clang__)`. On any other compiler (e.g., MSVC) the code falls through to the scalar path unconditionally. MSVC-specific CPUID dispatch is explicitly out of scope for this change.
+
 **Trade-off**: Does not use `ifunc` or a separate DSO; runtime dispatch is done once via a function pointer set at call site. This is simpler and sufficient for a teaching example.
 
 ### 2. Vectorization diagnostics workflow
@@ -36,7 +55,7 @@ This change closes four teaching gaps on existing surfaces without introducing n
 
 **Goal**: A maintainer can compare two benchmark JSON runs and see which benchmarks regressed.
 
-**Approach**: Add `scripts/compare_benchmarks.py` (Python 3, stdlib only — no third-party packages) that accepts two JSON files (baseline and candidate) and prints a table of benchmark name, baseline ns/iter, candidate ns/iter, and delta %. Exit code 1 if any benchmark regresses by more than a configurable threshold (default 10%). Add a "Regression Comparison" section to `examples/02-memory-cache/README.md` and the relevant benchmark docs entry showing the capture-and-compare workflow.
+**Approach**: Add `scripts/compare_benchmarks.py` (Python 3, stdlib only — no third-party packages) that accepts two JSON files (baseline and candidate) and prints a table of benchmark name, baseline ns/iter, candidate ns/iter, and delta %. Exit code 1 if any benchmark regresses by more than a configurable threshold (default 10%). Add a "Regression Comparison" section to `benchmarks/README.md` showing the capture-and-compare workflow.
 
 **Rationale**: stdlib-only ensures the script works without a virtualenv. The threshold flag makes it usable in CI without hardcoding expected values.
 
@@ -47,11 +66,11 @@ This change closes four teaching gaps on existing surfaces without introducing n
 | Path | Change |
 |------|--------|
 | `examples/04-simd-vectorization/src/runtime_dispatch.cpp` | New: runtime CPU dispatch example |
-| `examples/04-simd-vectorization/CMakeLists.txt` | Extend: wire `runtime_dispatch` target |
+| `examples/04-simd-vectorization/CMakeLists.txt` | Extend: add `simd_dispatch` STATIC library target |
 | `tests/` (simd subdir) | New: correctness test for `dispatch_add_arrays` |
 | `examples/04-simd-vectorization/README.md` | Extend: vectorization diagnostics section |
-| `docs/` (SIMD learning path entry) | Extend: vectorization diagnostics, sanitizer link |
-| `docs/` (validation/safety page or section) | New or extend: sanitizer preset workflow |
+| `docs/en/guides/learning-path.md` | Extend: vectorization diagnostics, sanitizer cross-link |
+| `docs/en/guides/validation.md` | New: sanitizer preset workflow (asan/tsan/ubsan) |
 | `README.md` | Extend: cross-link to sanitizer docs |
 | `scripts/compare_benchmarks.py` | New: benchmark regression comparison script |
-| `benchmarks/` README or docs entry | Extend: capture-and-compare workflow |
+| `benchmarks/README.md` | New: capture-and-compare workflow section |

openspec/changes/performance-teaching-hardening/specs/benchmark-framework/spec.md

@@ -20,3 +20,8 @@ THE HPC_Guide SHALL provide a script to compare two Google Benchmark JSON output
 
 - **WHEN** the script is invoked with `--threshold N`
 - **THEN** the regression threshold is set to N percent rather than the default 10 percent
+
+#### Scenario: Script smoke test passes
+
+- **WHEN** `scripts/compare_benchmarks.py` is invoked with two synthesised JSON inputs (one stable, one regressed)
+- **THEN** it exits 0 for the stable case and exits 1 for the regressed case, confirming the script is functional

openspec/changes/performance-teaching-hardening/specs/ci-quality-assurance/spec.md

@@ -1,12 +1,3 @@
 # CI and Quality Assurance
 
-## ADDED Requirements
-
-### Requirement: Benchmark Regression Script Testable
-
-THE Build_System SHALL allow the benchmark regression comparison script to be smoke-tested without a full benchmark run.
-
-#### Scenario: Script smoke test passes
-
-- **WHEN** `scripts/compare_benchmarks.py` is invoked with two synthesised JSON inputs (one stable, one regressed)
-- **THEN** it exits 0 for the stable case and exits 1 for the regressed case, confirming the script is functional
+No new requirements added in this change. The benchmark regression script smoke-test requirement is owned by the `benchmark-framework` capability.

openspec/changes/performance-teaching-hardening/tasks.md

@@ -3,22 +3,22 @@
 ## 1. SIMD runtime dispatch
 
 - [ ] 1.1 Add `examples/04-simd-vectorization/src/runtime_dispatch.cpp` with `hpc::simd::dispatch_add_arrays` using `__builtin_cpu_supports` for AVX2/SSE2/scalar selection
-- [ ] 1.2 Register `runtime_dispatch` target in `examples/04-simd-vectorization/CMakeLists.txt` via `hpc_add_example`
+- [ ] 1.2 Add a `simd_dispatch` STATIC library target in `examples/04-simd-vectorization/CMakeLists.txt` (separate from the INTERFACE `simd_utils` target) that compiles `runtime_dispatch.cpp` and links `simd_utils` for headers
 - [ ] 1.3 Add a correctness test under `tests/` that calls `dispatch_add_arrays` and validates results against the scalar reference
 - [ ] 1.4 Verify `cmake --preset=debug && cmake --build build/debug && ctest --preset=debug` passes with the new target and test
 
 ## 2. Vectorization diagnostics documentation
 
 - [ ] 2.1 Add a "Vectorization Diagnostics" section to `examples/04-simd-vectorization/README.md` with GCC (`-fopt-info-vec`) and Clang (`-Rpass=loop-vectorize`) flag examples and sample output
-- [ ] 2.2 Add or extend a docs site page for the SIMD module to surface the vectorization diagnostics workflow for readers
+- [ ] 2.2 Extend `docs/en/guides/learning-path.md` (SIMD section) to surface the vectorization diagnostics workflow for readers
 
 ## 3. Sanitizer workflow documentation
 
-- [ ] 3.1 Add a "Validation and Safety" section to the VitePress docs site documenting the `asan`, `tsan`, and `ubsan` presets with copy-pasteable commands
+- [ ] 3.1 Add `docs/en/guides/validation.md` documenting the `asan`, `tsan`, and `ubsan` presets with copy-pasteable commands; add entry to VitePress nav
 - [ ] 3.2 Cross-link the sanitizer section from the root `README.md` quick-start
 
 ## 4. Benchmark regression comparison
 
 - [ ] 4.1 Add `scripts/compare_benchmarks.py`: accepts two Google Benchmark JSON files, prints a regression table (name, baseline, candidate, delta%), exits 1 if any benchmark exceeds the threshold (default 10%, configurable via `--threshold`)
-- [ ] 4.2 Add a "Regression Comparison" section to the benchmarks docs entry or `benchmarks/` README showing the capture-and-compare workflow
+- [ ] 4.2 Add a "Regression Comparison" section to `benchmarks/README.md` showing the capture-and-compare workflow
 - [ ] 4.3 Smoke-test the script with two synthesised JSON inputs to confirm it exits 0 on stable and 1 on a regressed run