rsc-universal 0.1.1

package/skills/cpp/SKILL.md

@@ -0,0 +1,349 @@
+---
+name: cpp
+description: "Use when writing, reviewing, modernizing, building, or debugging C++ - RAII and resource lifetime, smart-pointer ownership (unique_ptr/shared_ptr/weak_ptr), move semantics and the Rule of Zero/Five, target-based CMake with FetchContent, and killing undefined behavior with ASan/UBSan/TSan plus clang-tidy. Triggers: \"modernize this C++\", \"who owns this pointer\", \"use-after-free\", \"double free\", \"dangling reference\", \"segfault under load\", \"should this move be noexcept\", \"write a CMakeLists with FetchContent\", .cpp/.hpp/.ixx files, \"revisa este código C++\", \"tengo un segfault\", \"fuga de memoria\". NOT borrow-checker / Result-Option / cargo memory-safety (that is rust)."
+tags: [cpp, c++, modern-cpp, raii, cmake]
+recommends: [rust, secure-coding, deployment]
+origin: risco
+---
+
+# Modern C++
+
+Write, review, modernize, build, and debug C++ the way the C++ Core Guidelines intend:
+RAII for every resource, ownership made explicit through smart pointers and values, no
+undefined behavior by construction, and a target-based CMake build proven clean under
+sanitizers.
+
+Targets **C++20/23** for production today. C++23 is ISO/IEC 14882:2024; WG21 froze C++26's
+technical content on **2026-03-28** (ISO publication follows) — adopt C++26 features only
+behind confirmed compiler support. Compiler matrix:
+
+| Compiler | C++23 | C++26 | Flag |
+| --- | --- | --- | --- |
+| GCC | since 11 | since 14 (GCC 16.1 covers most of C++26) | `-std=c++23` / `-std=c++26` |
+| Clang | 13–18 progressively | in progress (Clang 23 dev) | `-std=c++23` / `-std=c++2c` |
+| MSVC | latest | partial | `/std:c++23` / `/std:c++latest` |
+
+## When to use / When NOT to use
+
+**Use when:**
+
+- Authoring or reviewing any `.cpp` / `.cc` / `.hpp` / `.h` / `.ixx` (module) file.
+- Deciding ownership: value / `unique_ptr` / `shared_ptr` / `weak_ptr` / borrowed `span` / `string_view` / `const&`.
+- Modernizing legacy C++: ripping out `new`/`delete`, owning raw pointers, manual loops, C-style casts.
+- Writing or fixing a **CMake** build (target-based, `FetchContent`, presets).
+- Hunting UB: enabling ASan/UBSan/TSan, reading the report, applying the lifetime/bounds/overflow/race fix.
+- Move semantics / Rule of Zero/Five / value-category and `noexcept` questions.
+
+**When NOT to use (delegate):**
+
+- Rust borrow-checker, `Result`/`Option`, cargo, ownership-via-compiler -> [`rust`](../rust/SKILL.md).
+  C++ buys safety with discipline (RAII + smart pointers + sanitizers); do not conflate the mechanisms.
+- Language-agnostic threat modeling, authz, OWASP-class review -> [`secure-coding`](../secure-coding/SKILL.md)
+  (this skill keeps the C++-specific controls: bounds, lifetime, integer overflow, format-string, sanitizers).
+- Containerizing/shipping the binary (Dockerfile, GitHub Actions) -> [`deployment`](../deployment/SKILL.md)
+  (this skill stops at the CMake build + a sanitizer-CI note).
+- Recording per-project C++ conventions in a workspace wiki -> [`harness`](../harness/SKILL.md)
+  (see "Project grounding" below).
+
+The C++-specific memory/UB controls — sanitizers, bounds, lifetime, signed overflow — live
+**here**, not in `secure-coding`.
+
+## Decision rules
+
+Apply these on every C++ edit:
+
+1. **Rule of Zero first.** Manage resources with members that already do it (`vector`, `string`,
+   `unique_ptr`); write no destructor/copy/move at all. Why: hand-written special members are the
+   #1 source of leaks and double-frees.
+2. **Value by default.** Pass and return by value for small/copyable types; reach for the heap
+   only when you need polymorphism, shared lifetime, or a large/stable address. Why: values can't dangle.
+3. **Name the owner.** Exactly one type owns each resource; everyone else borrows. Why: ambiguous
+   ownership is how use-after-free is born.
+4. **`make_unique`/`make_shared`, never `new`.** Why: no naked owning pointer ever exists, so there
+   is nothing to forget to `delete`, and it's exception-safe.
+5. **Never an owning raw pointer.** Raw pointers/references are non-owning borrows only. Why: a raw
+   pointer that owns is a leak or a double-free waiting on the next early `return`/throw.
+6. **Borrow with `span` / `string_view` / `const T&`.** Pass a view, not a copy or an owner, for
+   read access. Why: zero-copy and the callee provably can't free what it doesn't own.
+7. **`const` and `constexpr` by default.** Make everything you can immutable and compile-time. Why:
+   the compiler enforces what you don't mutate and moves work off the hot path.
+8. **No UB by construction.** No use-after-move, OOB index, signed overflow, uninitialized read, or
+   data race. Why: UB is not a runtime error — the optimizer is licensed to do anything.
+9. **Sanitizers + warnings-as-errors in CI.** Build and test under `-fsanitize=address,undefined`
+   with `-Werror`. Why: most C++ bugs are invisible until a sanitizer or a warning surfaces them.
+10. **Target-based CMake only.** `target_link_libraries` / `target_compile_features`, never
+    directory-level `include_directories`/`link_libraries`. Why: directory commands leak flags globally and break composition.
+
+## Ownership & smart pointers
+
+Pick the type from the *need*, not from habit:
+
+| Need | Use |
+| --- | --- |
+| Exclusive owner, one place frees it | `std::unique_ptr<T>` |
+| Genuinely shared lifetime (multiple owners, last one frees) | `std::shared_ptr<T>` |
+| Observe / break a `shared_ptr` cycle, no ownership | `std::weak_ptr<T>` (`.lock()` to use) |
+| Read-only borrow of contiguous range / string | `std::span<const T>` / `std::string_view` |
+| Borrow a single object, non-owning | `const T&` / `T&` / `T*` (never owning) |
+| Small, copyable, value-like | the value itself — no heap |
+
+Default to `unique_ptr`; only escalate to `shared_ptr` when ownership is *actually* shared, and
+prove the shared case isn't a disguised single owner first — `shared_ptr` is not "the safe default."
+
+```cpp
+// Bad: naked owning pointer; leaks on the throw, double-frees if you copy the handle.
+Widget* w = new Widget(cfg);
+configure(w);            // if this throws, w leaks
+delete w;
+
+// Good: ownership is the type; freed exactly once, exception-safe, no delete to forget.
+auto w = std::make_unique<Widget>(cfg);
+configure(*w);
+```
+
+```cpp
+// Bad: parent <-> child shared_ptr cycle -> neither refcount hits zero -> leak forever.
+struct Node { std::shared_ptr<Node> parent, child; };
+
+// Good: child owns down, parent observes up. Cycle broken; lock() before use.
+struct Node {
+    std::shared_ptr<Node> child;   // owns
+    std::weak_ptr<Node>   parent;  // observes
+};
+if (auto p = node.parent.lock()) { /* p is a valid shared_ptr here */ }
+```
+
+When an object must hand out a `shared_ptr` to itself, derive from
+`std::enable_shared_from_this<T>` and call `shared_from_this()` — never wrap `this` in a fresh
+`shared_ptr` (that creates a second, independent refcount and a guaranteed double-free).
+
+Deeper ownership/move reasoning -> `references/move-and-templates.md`.
+
+## RAII
+
+Tie every resource — heap memory, file, socket, mutex, OS handle — to an object's lifetime; the
+destructor releases it. Why: cleanup then happens on *every* exit path (return, exception, break)
+for free, with no GC and no `finally`.
+
+Use the standard guards before writing your own:
+
+```cpp
+std::lock_guard  lock(mtx_);            // locks now, unlocks at scope end (C++17 CTAD)
+std::scoped_lock locks(a_mtx, b_mtx);   // multiple mutexes, deadlock-free acquisition
+std::unique_lock lk(mtx_);              // movable / deferrable, for condition_variable
+std::ifstream    in("data.txt");        // closes in its destructor
+```
+
+When you wrap a C resource yourself, make the destructor release and disable copies (Rule of Five
+or `unique_ptr` with a custom deleter):
+
+```cpp
+// RAII wrapper for a FILE*: closes once, can't leak, can't double-close.
+class File {
+public:
+    explicit File(const char* path, const char* mode) : f_(std::fopen(path, mode)) {
+        if (!f_) throw std::runtime_error("open failed");
+    }
+    ~File() { if (f_) std::fclose(f_); }
+    File(const File&) = delete;                 // not copyable
+    File& operator=(const File&) = delete;
+    File(File&& o) noexcept : f_(std::exchange(o.f_, nullptr)) {}        // move = steal
+    File& operator=(File&& o) noexcept { std::swap(f_, o.f_); return *this; }
+    FILE* get() const noexcept { return f_; }
+private:
+    FILE* f_{};
+};
+// Even simpler when a deleter suffices — let unique_ptr own it (Rule of Zero):
+auto fp = std::unique_ptr<FILE, decltype(&std::fclose)>(std::fopen("d", "r"), &std::fclose);
+```
+
+## Move semantics & Rule of Zero/Five
+
+Every expression is an *lvalue* (has a name, persists) or an *rvalue* (a temporary, about to die).
+`std::move` does not move anything — it casts an lvalue to an rvalue so a move constructor/assignment
+can *steal* its guts instead of copying. After you move from an object, it is valid but unspecified:
+only assign to it or destroy it; reading it is **use-after-move** (a real bug ASan/UBSan won't catch — clang-tidy will).
+
+- **Rule of Zero** (default): manage nothing by hand; let the compiler generate all five special
+  members. This is correct for the vast majority of types.
+- **Rule of Five**: the moment you write *one* of destructor / copy-ctor / copy-assign / move-ctor /
+  move-assign, you must reason about all five. If you're writing them, you probably should have used
+  a `unique_ptr`/`vector` member and gone back to Rule of Zero.
+- **Move ops must be `noexcept`.** Why: `std::vector` reallocation only *moves* elements instead of
+  copying them when the move is `noexcept` — otherwise it silently falls back to copies for the
+  strong exception guarantee.
+
+```cpp
+std::vector<std::string> v;
+v.push_back(std::move(name));   // transfers the buffer; `name` is now empty-but-valid
+// Bad: use-after-move — `name` holds an unspecified state here.
+log(name);                      // don't. Reassign name first, or just don't read it.
+```
+
+Return local objects by value and let **RVO / copy elision** remove the copy — do *not* `return
+std::move(local)`, which pessimizes by blocking elision. Take a forwarding reference `T&&` plus
+`std::forward<T>(x)` only in generic code that must preserve value category.
+
+Worked Rule-of-Five, perfect forwarding, CTAD, and C++20 concepts -> `references/move-and-templates.md`.
+
+## Avoiding UB (essentials)
+
+Undefined behavior is the compiler's permission to assume the bug can't happen and optimize on that
+assumption — so the symptom is often a *distant* crash or a "works in Debug, breaks in Release." Pair
+static analysis (clang-tidy, cppcheck) with dynamic sanitizers; they catch disjoint bug classes.
+
+| Sanitizer | Flag | Catches |
+| --- | --- | --- |
+| AddressSanitizer | `-fsanitize=address` | use-after-free, heap/stack buffer overflow, double-free |
+| UndefinedBehaviorSanitizer | `-fsanitize=undefined` | signed overflow, null/misaligned deref, bad shifts, invalid enum |
+| ThreadSanitizer | `-fsanitize=thread` | data races |
+
+Combine **ASan + UBSan** in one build (`-fsanitize=address,undefined`); run **TSan alone** (it's
+incompatible with ASan). Always add `-fno-omit-frame-pointer -g` for readable reports.
+
+```cpp
+// Bad: returns a dangling reference into a destroyed temporary -> use-after-free, ASan fires.
+const std::string& name() { std::string s = build(); return s; }   // s dies at return
+
+// Good: return by value; RVO makes it free.
+std::string name() { return build(); }
+```
+
+The full catalog (lifetime, OOB, signed overflow, strict-aliasing, uninitialized, data races,
+use-after-move), which sanitizer surfaces each, the canonical fix, and a "reading an ASan report"
+walkthrough -> `references/undefined-behavior.md`.
+
+## Modern CMake (essentials)
+
+Target-based only. State requirements on the *target*, never globally:
+
+```cmake
+cmake_minimum_required(VERSION 3.21)
+project(app LANGUAGES CXX)
+
+set(CMAKE_EXPORT_COMPILE_COMMANDS ON)   # feeds clang-tidy / clangd
+
+include(FetchContent)                   # FetchContent ships with CMake since 3.11
+FetchContent_Declare(Catch2
+    GIT_REPOSITORY https://github.com/catchorg/Catch2.git
+    GIT_TAG        v3.7.1)
+FetchContent_MakeAvailable(Catch2)      # its targets work just like find_package targets
+
+add_executable(app src/main.cpp)
+target_compile_features(app PRIVATE cxx_std_23)     # request the standard on the target
+target_compile_options(app PRIVATE -Wall -Wextra -Wpedantic -Werror)
+target_link_libraries(app PRIVATE Catch2::Catch2WithMain)
+```
+
+Full template (src/include/tests layout, `CMakePresets.json` with debug/asan/release presets,
+fmt + GoogleTest via FetchContent, per-compiler warning + sanitizer flags, install/export) ->
+`references/cmake.md`.
+
+## Standard-library idioms
+
+Reach for the library before hand-rolling:
+
+```cpp
+#include <algorithm>
+#include <ranges>
+#include <expected>   // C++23
+#include <format>     // C++20
+
+// Ranges over raw index loops — no off-by-one, no manual bounds.
+auto evens = nums | std::views::filter([](int n){ return n % 2 == 0; });
+std::ranges::sort(v);
+
+// std::expected (C++23) over out-params / sentinel returns / exceptions for expected failure.
+std::expected<Config, std::string> load(std::string_view path);
+if (auto cfg = load(p)) use(*cfg); else log(cfg.error());
+
+std::optional<User> find(int id);            // "maybe absent", not a magic -1 / nullptr
+std::span<const int> view(v);                // borrow a contiguous range, no copy, no owner
+auto [it, inserted] = m.try_emplace(k, val); // structured bindings
+enum class Color { Red, Green };             // scoped, no implicit int conversions
+std::string msg = std::format("{} of {}", i, n);  // type-safe, no printf format-string UB
+```
+
+Prefer `at()` or a range-checked view when the index isn't provably in bounds; `operator[]` on a
+bad index is UB, not an exception.
+
+## Testing & tooling
+
+- **Tests:** Catch2 or GoogleTest pulled via `FetchContent` (above); run them with `ctest`.
+- **Static analysis:** `clang-tidy -p build` (reads `compile_commands.json`) and `cppcheck` —
+  they catch use-after-move, missing `noexcept`, and lifetime bugs the compiler won't.
+- **Dynamic analysis:** run the test target under ASan+UBSan so tests *prove* no UB on covered paths.
+- **Format:** `clang-format -i` with a checked-in `.clang-format`.
+- **Local gate:** `./scripts/verify.sh` from the project root runs format + an ASan/UBSan,
+  warnings-as-errors build + `ctest` + optional tidy/cppcheck. Missing tools are skipped, not failed.
+
+## Anti-patterns / rationalizations -> STOP
+
+| Rationalization | Reality / Do instead |
+| --- | --- |
+| "I'll just `new`/`delete` carefully" | One early return or throw and you leak/double-free. `make_unique`, always. |
+| "A raw owning pointer is faster" | `unique_ptr` is zero-overhead; the cost is imaginary, the leak is real. |
+| "`shared_ptr` everywhere is the safe default" | Shared ownership invites cycles + atomic refcount cost. Default `unique_ptr`; share only when truly shared. |
+| "The C-style cast is fine, I know the type" | Use `static_cast`/`dynamic_cast`; C casts silently reinterpret and hide bugs. |
+| "Skip `noexcept` on the move ctor" | `vector` then copies instead of moving on realloc. Mark moves `noexcept`. |
+| "UB won't happen on my compiler" | UB lets the optimizer delete your checks; "works in Debug" proves nothing. |
+| "No sanitizers, it ran fine" | It ran; it wasn't *correct*. Build+test under ASan+UBSan. |
+| "A hand-rolled Makefile is simpler" | It rots and leaks flags. Target-based CMake is the contract. |
+| "`v[i]` is in range, I checked" | If it's not provable, use `.at()` or a checked view; OOB is UB. |
+| "`return std::move(local)` to be fast" | It blocks RVO and is slower. Return the local by value. |
+| "`using namespace std;` in a header" | Pollutes every includer; ODR/ambiguity bugs. Never in a header. |
+| "An out-param instead of returning the value" | Return by value (RVO) or `optional`/`expected`; out-params hide aliasing and UB. |
+| "A global / singleton is simpler" | It's hidden shared mutable state -> data races + untestable. Inject it. |
+
+## Quick reference
+
+| Task | Command / idiom |
+| --- | --- |
+| Configure + build | `cmake -S . -B build && cmake --build build` |
+| Configure with sanitizers | `cmake -S . -B build -DCMAKE_CXX_FLAGS="-fsanitize=address,undefined -g"` |
+| Test | `ctest --test-dir build --output-on-failure` |
+| ASan + UBSan | `-fsanitize=address,undefined -fno-omit-frame-pointer -g` |
+| ThreadSanitizer (alone) | `-fsanitize=thread -g` |
+| Format | `clang-format -i src/*.cpp` |
+| Static analysis | `clang-tidy -p build src/*.cpp` · `cppcheck --enable=warning src/` |
+| Std flag | GCC/Clang `-std=c++23` (C++26: GCC `-std=c++26`, Clang `-std=c++2c`), MSVC `/std:c++23` |
+| Own a resource | `auto p = std::make_unique<T>(...);` |
+| Borrow a range | `std::span<const T>` / `std::string_view` |
+| Local gate | `./scripts/verify.sh` (run in your project root) |
+
+## Project grounding (02-DOCS + CLAUDE.md)
+
+When this skill runs in a project with a `02-DOCS/` layer (the [`harness`](../harness/SKILL.md)
+Karpathy wiki), record this project's C++ decisions there and index them from the root `CLAUDE.md`,
+so the next agent inherits them instead of re-deriving them.
+
+1. **Find the article** `02-DOCS/wiki/stack/cpp.md`, linked from a `## Knowledge map` section in
+   the root `CLAUDE.md`.
+2. **If missing or stale**, create/update it with the project's real choices — std version and
+   compiler matrix, CMake layout and presets, the sanitizer/warning policy, and the ownership/error
+   conventions — then add/refresh the `CLAUDE.md` link (create the `## Knowledge map` section, and
+   `CLAUDE.md` itself, if absent).
+3. **Read it first on every use** and stay consistent; when a convention changes, update the article
+   (bump its `Updated` date) in the same change.
+
+No `02-DOCS/` layer? Skip silently (optionally suggest `harness`). Technical conventions are
+*recorded, not gated* — never block the task on this.
+
+## See Also
+
+Sibling skills (all resolve under `skills/`):
+
+- [`rust`](../rust/SKILL.md) - the other systems language; compiler-enforced ownership instead of
+  RAII discipline. Any borrow-checker / `Result`-`Option` / cargo question goes there.
+- [`secure-coding`](../secure-coding/SKILL.md) - language-agnostic threat modeling and authz/abuse
+  review (this skill keeps the C++-specific memory/UB controls).
+- [`deployment`](../deployment/SKILL.md) - containerizing and shipping the built binary (this skill
+  stops at the CMake build + a sanitizer-CI note).
+- [`harness`](../harness/SKILL.md) - the `02-DOCS/` workspace wiki where per-project C++ conventions
+  are recorded (see "Project grounding").
+
+Local references (read when):
+
+- `references/cmake.md` - full target-based CMake template, presets, FetchContent, sanitizer/warning flags.
+- `references/undefined-behavior.md` - the UB catalog, which sanitizer catches each, fixes, ASan-report walkthrough.
+- `references/move-and-templates.md` - value categories, Rule of Five, perfect forwarding, CTAD, C++20 concepts.

package/skills/cpp/evals/README.md

@@ -0,0 +1,14 @@
+# Eval harness — `cpp` skill
+
+These cases are run by the rsc skill-eval harness (a Claude agent with the full skill catalog
+loaded), or read manually. They measure two things: **triggering** — that the `cpp` skill's
+description fires on each `should_trigger` prompt and stays quiet on the `should_not_trigger`
+near-misses, routing each of those to the named real sibling (`rust`, `secure-coding`,
+`deployment`, `go`, `harness`) instead; and **capability** — that, with `SKILL.md` and its
+references loaded, a graded model's generated C++ satisfies the `capability.must_include` rubric
+(RAII over raw resources, smart-pointer ownership, no `new`/`delete`, target-based CMake with
+warnings-as-errors, an ASan+UBSan build) and beats the no-skill baseline by a clear margin. Run
+3–5 trials per prompt since LLM routing is non-deterministic; a prompt passes on a majority. No
+network is needed — the capability rubric is judged by reading the output against the points, and
+the verify.sh gate (compile under sanitizers + ctest) is exercised separately against a real
+project, not as part of these cases.

package/skills/cpp/evals/cases.yaml

@@ -0,0 +1,44 @@
+skill: cpp
+
+should_trigger:
+  - prompt: "Modernize this C++ — it's full of new/delete and raw owning pointers, manual for loops, and C-style casts."
+    why: "Modernizing legacy C++ (RAII, smart pointers, ranges, static_cast) is the skill's core use case."
+  - prompt: "Who should own this object — a unique_ptr, a shared_ptr, or just a value? It gets passed around a lot."
+    why: "Ownership design via the smart-pointer/value decision table is explicitly owned here."
+  - prompt: "I'm getting a use-after-free and an occasional segfault under load. Find it."
+    why: "Non-obvious, symptom-only trigger: the user never says 'smart pointer' or 'C++ idiom', but this routes here via the ASan + lifetime workflow."
+  - prompt: "Write a CMakeLists.txt that pulls in Catch2 with FetchContent and turns on AddressSanitizer."
+    why: "Target-based CMake with FetchContent + sanitizer build is a named trigger."
+  - prompt: "Revisa este código C++ y dime si tengo una fuga de memoria."
+    why: "Spanish review + memory-leak trigger; the description carries the Spanish phrasing 'fuga de memoria'."
+  - prompt: "Should this move constructor be noexcept, and is my Rule of Five correct here?"
+    why: "Move semantics / Rule of Five / noexcept-move is a core decision this skill makes."
+  - prompt: "My program is fine in Debug but crashes in Release — is this undefined behavior, and how do I prove it with sanitizers?"
+    why: "Non-obvious UB symptom ('works in Debug, breaks in Release'); routes here for the ASan/UBSan workflow, not a generic debugger."
+
+should_not_trigger:
+  - prompt: "Fix this borrow-checker error and return a Result instead of panicking."
+    route_to: "rust"
+    why: "Borrow checker + Result/Option is Rust's compiler-enforced ownership, a different mechanism than C++ RAII discipline."
+  - prompt: "Do a threat model and authz review of my service's permission boundaries and OWASP exposure."
+    route_to: "secure-coding"
+    why: "Language-agnostic threat modeling and authz/abuse review is delegated to secure-coding; only C++-specific memory/UB controls stay here."
+  - prompt: "Write a multi-stage Dockerfile and GitHub Actions CI to build and ship my compiled binary."
+    route_to: "deployment"
+    why: "Containerizing and shipping the binary is delegated to deployment; this skill stops at the CMake build plus a sanitizer-CI note."
+  - prompt: "Record our team's chosen C++ compiler flags and conventions in the project wiki and index them from CLAUDE.md."
+    route_to: "harness"
+    why: "Authoring/indexing the 02-DOCS workspace wiki is the harness skill's job; this skill only writes its own stack article when that layer already exists."
+  - prompt: "Build a Go HTTP service with graceful shutdown and table-driven tests."
+    route_to: "go"
+    why: "A different sibling systems language; Go service work has no overlap with C++ mechanics."
+
+capability:
+  - scenario: "Modernize a C++ class that owns a heap buffer via new[]/delete[] and a raw FILE*, and give it a sane CMake build."
+    must_include:
+      - "Replaces the owning raw buffer with std::unique_ptr or std::vector under Rule of Zero, OR keeps a hand-managed resource only via a correct Rule of Five with noexcept move operations"
+      - "Wraps the FILE* in an RAII type whose destructor closes it (or uses std::fstream / unique_ptr with a custom deleter), so it closes on every exit path"
+      - "Contains no new/delete and no owning raw pointers that escape; uses std::make_unique where heap is needed"
+      - "CMake is target-based (target_compile_features(... cxx_std_23), target_link_libraries), not directory-level include_directories/link_libraries, and sets warnings-as-errors (-Werror / /WX)"
+      - "Mentions building and testing under ASan+UBSan (-fsanitize=address,undefined) to prove no UB on covered paths"
+      - "Uses const / value semantics and standard containers and algorithms over manual index loops where natural"

package/skills/cpp/references/cmake.md

@@ -0,0 +1,167 @@
+# Modern CMake — full template
+
+Target-based, presets-driven, FetchContent for dependencies. CMake's current docs track 4.x;
+`FetchContent` has shipped since 3.11, and its imported targets are used with
+`target_link_libraries` exactly like `find_package` targets. The rule throughout: state
+requirements on the **target**, never globally.
+
+## Layout
+
+```text
+myproj/
+  CMakeLists.txt
+  CMakePresets.json
+  include/myproj/widget.hpp
+  src/widget.cpp
+  src/main.cpp
+  tests/widget_test.cpp
+  .clang-format
+  .clang-tidy
+```
+
+## Root CMakeLists.txt
+
+```cmake
+cmake_minimum_required(VERSION 3.21)        # 3.21+ for presets v3 and modern target features
+project(myproj VERSION 0.1.0 LANGUAGES CXX)
+
+# Export compile_commands.json so clang-tidy / clangd see exact flags.
+set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
+
+# A reusable warnings interface target — link it into everything you own.
+add_library(myproj_warnings INTERFACE)
+if(MSVC)
+  target_compile_options(myproj_warnings INTERFACE /W4 /permissive- /WX)
+else()
+  target_compile_options(myproj_warnings INTERFACE
+    -Wall -Wextra -Wpedantic -Wshadow -Wconversion -Wsign-conversion -Werror)
+endif()
+
+# --- library target ---
+add_library(widget src/widget.cpp)
+target_include_directories(widget PUBLIC
+  $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+  $<INSTALL_INTERFACE:include>)
+target_compile_features(widget PUBLIC cxx_std_23)         # the standard is a target property
+target_link_libraries(widget PRIVATE myproj_warnings)
+
+# --- executable target ---
+add_executable(app src/main.cpp)
+target_link_libraries(app PRIVATE widget myproj_warnings)
+
+# --- dependencies via FetchContent ---
+include(FetchContent)
+FetchContent_Declare(fmt
+  GIT_REPOSITORY https://github.com/fmtlib/fmt.git
+  GIT_TAG        11.0.2)
+FetchContent_Declare(Catch2
+  GIT_REPOSITORY https://github.com/catchorg/Catch2.git
+  GIT_TAG        v3.7.1)
+FetchContent_MakeAvailable(fmt Catch2)
+target_link_libraries(widget PUBLIC fmt::fmt)
+
+# --- tests ---
+enable_testing()
+add_executable(widget_test tests/widget_test.cpp)
+target_link_libraries(widget_test PRIVATE widget Catch2::Catch2WithMain myproj_warnings)
+
+include(Catch)                 # provided by Catch2; registers each TEST_CASE with ctest
+catch_discover_tests(widget_test)
+```
+
+Use GoogleTest instead of Catch2 by declaring `googletest` (GIT_TAG `v1.15.2`) and linking
+`GTest::gtest_main`; register with `include(GoogleTest)` + `gtest_discover_tests(...)`.
+
+## CMakePresets.json
+
+Presets give every developer (and CI) identical, named configurations — no remembered flag
+soup. `debug` for day-to-day, `asan` for the sanitizer build the local gate uses, `release` for
+optimized output.
+
+```json
+{
+  "version": 3,
+  "cmakeMinimumRequired": { "major": 3, "minor": 21, "patch": 0 },
+  "configurePresets": [
+    {
+      "name": "debug",
+      "binaryDir": "${sourceDir}/build/debug",
+      "generator": "Ninja",
+      "cacheVariables": { "CMAKE_BUILD_TYPE": "Debug" }
+    },
+    {
+      "name": "asan",
+      "inherits": "debug",
+      "binaryDir": "${sourceDir}/build/asan",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Debug",
+        "CMAKE_CXX_FLAGS": "-fsanitize=address,undefined -fno-omit-frame-pointer -g"
+      }
+    },
+    {
+      "name": "release",
+      "binaryDir": "${sourceDir}/build/release",
+      "generator": "Ninja",
+      "cacheVariables": { "CMAKE_BUILD_TYPE": "RelWithDebInfo" }
+    }
+  ],
+  "buildPresets": [
+    { "name": "debug", "configurePreset": "debug" },
+    { "name": "asan", "configurePreset": "asan" },
+    { "name": "release", "configurePreset": "release" }
+  ],
+  "testPresets": [
+    { "name": "asan", "configurePreset": "asan", "output": { "outputOnFailure": true } }
+  ]
+}
+```
+
+Drive it:
+
+```bash
+cmake --preset asan          # configure
+cmake --build --preset asan  # build
+ctest --preset asan          # test under ASan+UBSan
+```
+
+## Sanitizer & warning flags per compiler
+
+| | GCC / Clang | MSVC |
+| --- | --- | --- |
+| Warnings-as-errors | `-Wall -Wextra -Wpedantic -Werror` | `/W4 /WX` |
+| ASan + UBSan | `-fsanitize=address,undefined -fno-omit-frame-pointer -g` | `/fsanitize=address` (no UBSan) |
+| TSan (run alone) | `-fsanitize=thread -g` | — |
+| Std | `-std=c++23` (`-std=c++26`/`-std=c++2c`) | `/std:c++23` (`/std:c++latest`) |
+
+Inject sanitizers per-config (the `asan` preset's `CMAKE_CXX_FLAGS`), not unconditionally — a
+release build must not carry them.
+
+## clang-tidy / cppcheck
+
+With `CMAKE_EXPORT_COMPILE_COMMANDS=ON`, both tools read the exact per-file flags:
+
+```bash
+clang-tidy -p build/debug src/widget.cpp src/main.cpp
+cppcheck --enable=warning,performance --project=build/debug/compile_commands.json
+```
+
+A minimal `.clang-tidy`:
+
+```yaml
+Checks: 'clang-analyzer-*,bugprone-*,modernize-*,performance-*,cppcoreguidelines-*'
+WarningsAsErrors: 'clang-analyzer-*,bugprone-use-after-move'
+```
+
+## Install / export (when you ship a library)
+
+```cmake
+include(GNUInstallDirs)
+install(TARGETS widget EXPORT widgetTargets
+  ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
+  LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
+  RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
+install(DIRECTORY include/ DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})
+install(EXPORT widgetTargets NAMESPACE myproj:: DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/myproj)
+```
+
+Containerizing the resulting binary and CI pipelines -> `deployment`.