@polderlabs/bizar 10.7.2 → 10.10.0

package/.claude/skills/cpp-coding-standards/references/memory-safety.md

@@ -1,216 +0,0 @@
-# Memory Safety in Modern C++
-
-This reference covers RAII, smart pointers, and the Rule of Five/Zero.
-
-## RAII — Resource Acquisition Is Initialization
-
-Every resource (heap memory, file handle, mutex, socket, etc.) must be owned by an object whose destructor performs cleanup. This guarantees cleanup even when exceptions are thrown.
-
-```cpp
-// GOOD — file closes automatically at scope exit
-void read_file(const std::string& path) {
-    std::ifstream in(path);
-    std::string line;
-    while (std::getline(in, line)) {
-        process(line);
-    }
-} // destructor closes file, no matter how we exit
-
-// BAD — manual cleanup, error-prone
-void read_file_bad(const std::string& path) {
-    std::ifstream* in = new std::ifstream(path);
-    std::string line;
-    while (std::getline(*in, line)) {  // throws? leaks *in
-        process(line);
-    }
-    delete in;
-}
-```
-
-### Common RAII Types in the Standard Library
-
-| Type | Resource |
-|---|---|
-| `std::unique_ptr` | Heap memory (single owner) |
-| `std::shared_ptr` | Heap memory (shared owner) |
-| `std::ifstream` / `std::ofstream` | File handles |
-| `std::lock_guard` / `std::scoped_lock` | Mutex lock |
-| `std::jthread` (C++20) | Thread join on destruction |
-
-## Smart Pointers
-
-### `std::unique_ptr<T>`
-
-Exclusive ownership. The default choice. Zero overhead over raw pointer.
-
-```cpp
-#include <memory>
-
-// Creation
-auto p1 = std::make_unique<int>(42);
-auto p2 = std::make_unique<std::vector<int>>(10, 0);
-
-// Custom deleter (rare — only when type needs special cleanup)
-auto file_deleter = [](FILE* f) { if (f) fclose(f); };
-std::unique_ptr<FILE, decltype(file_deleter)> fp(fopen("data.txt", "r"), file_deleter);
-
-// Transfer ownership
-std::unique_ptr<int> source = std::make_unique<int>(1);
-std::unique_ptr<int> dest = std::move(source);  // source is now nullptr
-assert(!source);
-assert(*dest == 1);
-
-// Release the raw pointer (rare — only for C interop)
-int* raw = p1.release();
-delete raw;  // you now own it — avoid this
-```
-
-### `std::shared_ptr<T>`
-
-Shared ownership via reference counting. Use **only** when ownership genuinely must be shared. Prefer `unique_ptr` otherwise.
-
-```cpp
-auto shared = std::make_shared<int>(100);
-
-// Copy increases ref count
-auto shared2 = shared;  // ref count = 2
-
-// shared_ptr can be created from unique_ptr
-auto unique = std::make_unique<double>(3.14);
-std::shared_ptr<double> from_unique = std::move(unique);
-
-// Weak pointer — breaks cycles
-std::weak_ptr<int> weak = shared;
-if (auto locked = weak.lock()) {
-    // use *locked safely
-}  // locked goes out of scope, ref count unchanged
-
-// Custom deleter — stored separately from the control block
-auto deleter = [](FILE* f) { fclose(f); };
-std::shared_ptr<FILE> f(fopen("x.txt", "r"), deleter);
-```
-
-**Performance notes:**
-- `shared_ptr` is twice the size of a raw pointer (control block + pointer)
-- Atomic reference count increments/decrements on copy/destroy
-- `make_shared` allocates the object and control block in one allocation (preferred)
-
-### `std::weak_ptr<T>`
-
-Non-owning observer of a `shared_ptr`. Use to break reference cycles (A owns B, B observes A without owning).
-
-```cpp
-class Observer;
-class Subject {
-    std::vector<std::weak_ptr<Observer>> observers_;
-public:
-    void notify() {
-        for (auto& w : observers_) {
-            if (auto o = w.lock()) o->on_update();
-        }
-    }
-};
-```
-
-## Rule of Five
-
-If you define **any one** of the five special member functions below, you likely need to define **all five**:
-
-1. Destructor
-2. Copy constructor
-3. Copy assignment operator
-4. Move constructor
-5. Move assignment operator
-
-```cpp
-class Buffer {
-    int* data_ = nullptr;
-    size_t size_ = 0;
-public:
-    explicit Buffer(size_t n) : data_(new int[n]), size_(n) {}
-
-    ~Buffer() { delete[] data_; }
-
-    // Copy constructor
-    Buffer(const Buffer& o) : data_(new int[o.size_]), size_(o.size_) {
-        std::copy(o.data_, o.data_ + o.size_, data_);
-    }
-
-    // Copy assignment operator
-    Buffer& operator=(const Buffer& o) {
-        if (this != &o) {
-            delete[] data_;
-            data_ = new int[o.size_];
-            size_ = o.size_;
-            std::copy(o.data_, o.data_ + o.size_, data_);
-        }
-        return *this;
-    }
-
-    // Move constructor
-    Buffer(Buffer&& o) noexcept : data_(std::exchange(o.data_, nullptr)), size_(std::exchange(o.size_, 0)) {}
-
-    // Move assignment operator
-    Buffer& operator=(Buffer&& o) noexcept {
-        if (this != &o) {
-            delete[] data_;
-            data_ = std::exchange(o.data_, nullptr);
-            size_ = std::exchange(o.size_, 0);
-        }
-        return *this;
-    }
-};
-```
-
-## Rule of Zero
-
-Prefer **not** defining any special members and letting the compiler generate them correctly. Use standard library containers and smart pointers to manage resources.
-
-```cpp
-// Rule of Zero — no manual resource management needed
-class Point {
-    double x_ = 0, y_ = 0;
-public:
-    Point() = default;
-    Point(double x, double y) : x_(x), y_(y) {}
-    double distance_to(const Point& o) const {
-        double dx = x_ - o.x_, dy = y_ - o.y_;
-        return std::sqrt(dx*dx + dy*dy);
-    }
-};
-// Compiler-generated copy/move/dtor are all correct here
-```
-
-## Common Mistakes
-
-```cpp
-// WRONG: Shared ownership where unique ownership suffices
-auto widget = std::make_shared<Widget>();
-process(std::shared_ptr<Widget>(widget));  // unnecessary ref count bump
-
-// WRONG: Memory leak via raw new in container
-std::vector<int*> v;
-v.push_back(new int(1));  // who deletes these?
-
-// RIGHT: Smart pointers in containers
-std::vector<std::unique_ptr<int>> v;
-v.push_back(std::make_unique<int>(1));  // auto-deleted
-
-// WRONG: Missing virtual destructor in base class
-struct Base {
-    virtual void foo() {}
-    // Missing virtual destructor — deleting through base pointer is UB
-};
-struct Derived : Base {
-    std::vector<int> data;
-};
-
-Base* b = new Derived;
-delete b;  // UB: Derived's destructor not called
-
-// RIGHT: Virtual destructor
-struct Base {
-    virtual ~Base() = default;  // polymorphic bases need virtual dtor
-    virtual void foo() {}
-};
-```

package/.claude/skills/cpp-coding-standards/references/modern-idioms.md

@@ -1,282 +0,0 @@
-# Modern C++17/20 Idioms
-
-This reference covers the most impactful modern C++ features with minimal examples.
-
-## Structured Bindings
-
-Unpack tuples, pairs, structs, and arrays into named variables.
-
-```cpp
-#include <tuple>
-#include <map>
-
-// Pair/tuple
-auto [key, value] = std::pair{1, std::string("hello")};
-
-// Array
-auto [a, b, c] = std::array{1, 2, 3};
-
-// Struct — works if all members are public
-struct Point { double x, y, z; };
-Point p{1.0, 2.0, 3.0};
-auto [px, py, pz] = p;
-
-// Map iteration
-std::map<std::string, int> ages{{"Alice", 30}, {"Bob", 25}};
-for (const auto& [name, age] : ages) {
-    std::cout << name << ": " << age << '\n';
-}
-
-// Multiple return values
-std::tuple<int, std::string, double> compute() { return {42, "answer", 3.14}; }
-auto [code, label, score] = compute();
-```
-
-## `if constexpr`
-
-Compile-time conditional code execution — the unselected branch is not instantiated.
-
-```cpp
-#include <type_traits>
-
-template <typename T>
-auto inspect(const T& val) {
-    if constexpr (std::is_integral_v<T>) {
-        return "integer";
-    } else if constexpr (std::is_floating_point_v<T>) {
-        return "floating-point";
-    } else {
-        return "other";
-    }
-}
-
-// Works where SFINAE would require complex enable_if
-template <typename T>
-T doubled(T x) {
-    if constexpr (std::is_integral_v<T>) {
-        return x + x;  // valid only for integral T
-    } else {
-        return x * 2.0;  // valid only for floating-point T
-    }
-}
-```
-
-## `std::optional`
-
-Represents a value that may or may not be present. Alternative to pointer-returning APIs.
-
-```cpp
-#include <optional>
-
-// Return optional
-std::optional<int> find_index(const std::vector<int>& v, int target) {
-    for (auto it = v.begin(); it != v.end(); ++it) {
-        if (*it == target)
-            return {static_cast<int>(std::distance(v.begin(), it))};
-    }
-    return std::nullopt;
-}
-
-// Check and use
-if (auto idx = find_index(vec, 42)) {
-    std::cout << "Found at " << *idx << '\n';
-} else {
-    std::cout << "Not found\n";
-}
-
-// Transform an optional without unwrapping
-std::optional<std::string> name = /* ... */;
-auto greeting = name.transform([](const std::string& n) { return "Hello, " + n; });
-```
-
-## `std::string_view`
-
-Non-owning view into a string. Use for read-only string operations without copying.
-
-```cpp
-#include <string_view>
-
-// Function takes a view — no ownership, no allocation
-bool ends_with(std::string_view s, std::string_view suffix) {
-    return s.size() >= suffix.size() && s.substr(s.size() - suffix.size()) == suffix;
-}
-
-// Calling with different string types — no conversion/copy
-std::string s = "filename.txt";
-std::string_view sv = s;
-ends_with(sv, ".txt");           // string_view
-ends_with("literal", ".txt");    // const char* converts to string_view
-ends_with(sv, std::string(".log"));  // string converts to string_view
-
-// AVOID: storing string_view as a class member — it doesn't own the data
-// (only safe if another owning string keeps the data alive)
-```
-
-## `std::variant` (C++17)
-
-Type-safe union — an object that holds one of several specified types.
-
-```cpp
-#include <variant>
-
-std::variant<int, std::string, double> v = 42;
-
-// Check and access
-if (std::holds_alternative<int>(v)) {
-    int i = std::get<int>(v);
-}
-
-// Visitor pattern
-std::visit([](const auto& val) {
-    std::cout << val << '\n';
-}, v);
-
-// Overload helper (C++17 doesn't have std::visit overload; use this pattern)
-template <class... Ts> struct overload : Ts... { using Ts::operator()...; };
-template <class... Ts> overload(Ts...) -> overload<Ts...>;
-
-std::visit(overload{
-    [](int i) { std::cout << "int: " << i << '\n'; },
-    [](const std::string& s) { std::cout << "string: " << s << '\n'; },
-    [](double d) { std::cout << "double: " << d << '\n'; }
-}, v);
-```
-
-## `std::any` (C++17)
-
-Holds any single value of any type. Use when the set of possible types is open-ended.
-
-```cpp
-#include <any>
-
-std::any a = 42;
-a = std::string("hello");
-a = 3.14;
-
-if (a.type() == typeid(double)) {
-    double d = std::any_cast<double>(a);
-}
-
-// Safer: check before cast
-if (auto* pd = std::any_cast<double>(&a)) {
-    std::cout << *pd << '\n';
-}
-```
-
-## Ranges (C++20)
-
-```cpp
-#include <ranges>
-#include <algorithm>
-
-std::vector<int> v = {1, 2, 3, 4, 5, 6};
-
-// Filter and transform lazily — no new vector allocation
-auto evens = v | std::views::filter([](int x) { return x % 2 == 0; });
-auto doubled = evens | std::views::transform([](int x) { return x * 2; });
-
-for (int x : doubled) std::cout << x << ' ';  // 4 8 12
-
-// Range-based sort (C++20 — simpler than iterators)
-std::ranges::sort(v);
-
-// Find
-auto it = std::ranges::find(v, 3);
-
-// All / any / none
-bool has_negative = std::ranges::any_of(v, [](int x) { return x < 0; });
-
-// Projections — sort by member without lambda boilerplate
-struct Employee { std::string name; int level; };
-std::vector<Employee> emps{{"Bob", 3}, {"Alice", 1}, {"Carol", 2}};
-std::ranges::sort(emps, {}, &Employee::level);  // sort by .level
-```
-
-## Concepts (C++20)
-
-Explicit, named constraints on template parameters. Replace SFINAE with readable syntax.
-
-```cpp
-#include <concepts>
-#include <type_traits>
-
-// Define a concept
-template <typename T>
-concept Numeric = std::integral<T> || std::floating_point<T>;
-
-// Use in template parameters
-template <Numeric T>
-T add(T a, T b) { return a + b; }
-
-static_assert(add(1, 2) == 3);
-static_assert(add(1.5, 2.5) == 4.0);
-// add("a", "b") — fails to instantiate: const char* is not Numeric
-
-// Built-in concepts
-static_assert(std::ranges::range<std::vector<int>>);
-static_assert(std::copyable<int>);
-
-// Combining concepts
-template <typename T>
-concept Comparable = requires(T a, T b) {
-    { a < b } -> std::convertible_to<bool>;
-    { a == b } -> std::convertible_to<bool>;
-};
-```
-
-## `std::format` (C++20)
-
-Type-safe, Python-style string formatting.
-
-```cpp
-#include <format>
-#include <chrono>
-
-// Instead of printf/sprintf/cout combos
-std::string s = std::format("{} + {} = {}", 1, 2, 3);  // "1 + 2 = 3"
-std::string t = std::format("{:>10}", 42);              // right-aligned, width 10
-std::string u = std::format("{:.2f}", 3.14159);        // "3.14"
-std::string v = std::format("{:02x}", 255);            // "ff"
-
-// Named arguments
-std::cout << std::format("Hello, {name}! You are {age} years old.\n",
-                         std::format_args::arg("name", "Alice"), /* arg */);
-```
-
-## `std::span` (C++20)
-
-Non-owning view into a contiguous sequence — replacement for pointer+length pairs.
-
-```cpp
-#include <span>
-
-// Instead of (T* ptr, size_t count)
-void print_all(std::span<const int> data) {
-    for (int x : data) std::cout << x << ' ';
-}
-
-std::vector<int> vec{1, 2, 3};
-std::array<int, 3> arr{4, 5, 6};
-int raw[] = {7, 8, 9};
-
-print_all(vec);   // works
-print_all(arr);  // works
-print_all(raw);  // works — decays to span<int, 3>
-print_all({raw, 2});  // explicit length
-```
-
-## `[[likely]]` / `[[unlikely]]` (C++20)
-
-Branch prediction hints for performance-critical paths.
-
-```cpp
-bool process(int x) {
-    if (x > 0) [[likely]] {
-        // compiler may rearrange code for the common case
-        return do_positive(x);
-    }
-    [[unlikely]] {
-        return do_non_positive(x);
-    }
-}
-```

package/.claude/skills/cpp-coding-standards/references/review-checklist.md

@@ -1,96 +0,0 @@
-# C++ Code Review Checklist
-
-Use this checklist when reviewing C++ pull requests or before committing.
-
-## Memory Safety
-
-- [ ] No raw `new` or `delete` — use `std::unique_ptr` / `std::make_unique`
-- [ ] No owning raw pointers as class members (prefer `std::unique_ptr`)
-- [ ] Shared ownership genuinely needed? Consider if `unique_ptr` suffices
-- [ ] `shared_ptr` cycles broken with `weak_ptr`?
-- [ ] Virtual destructor declared on any polymorphic base class
-- [ ] All special member functions (Rule of Five) declared if needed
-- [ ] No use-after-free: references/pointers outlive the data they refer to
-- [ ] Arrays allocated with `new Type[n]` are `delete[]`d (or better, use `vector`)
-
-## RAII and Resource Management
-
-- [ ] File handles, mutexes, sockets use RAII wrappers (destructor cleans up)
-- [ ] `std::lock_guard` / `std::scoped_lock` used for mutex locking — not raw `.lock()/.unlock()`
-- [ ] Every `std::thread` has `.join()` or `.detach()` called before destruction
-- [ ] Prefer `std::jthread` (C++20) for automatic stop and join
-
-## Const Correctness
-
-- [ ] Member functions that don't modify state are marked `const`
-- [ ] Non-modifying parameters passed by `const&` (or by value if cheap-to-copy)
-- [ ] `const` variables used where data doesn't change after init
-- [ ] `const_iterator` used when iteration doesn't modify
-
-## Modern C++ Usage
-
-- [ ] Uses C++17/20 features where appropriate (structured bindings, `if constexpr`, `std::optional`, `string_view`)
-- [ ] No C-style casts — uses `static_cast`, `reinterpret_cast`, `const_cast`
-- [ ] `[[nodiscard]]` on functions returning values that must not be ignored
-- [ ] `override` used on all virtual method overrides
-- [ ] `noexcept` used correctly (only on functions that truly cannot throw)
-- [ ] `std::make_unique` / `std::make_shared` used instead of direct `new`
-
-## Headers and Includes
-
-- [ ] No `using namespace std;` in header files
-- [ ] No unused `#include` directives
-- [ ] Include order: related header first, then standard library, then external libs
-- [ ] Header is self-contained (includes everything it uses)
-
-## Containers and Types
-
-- [ ] `std::vector` preferred over raw arrays for dynamic sequences
-- [ ] `std::vector::reserve()` called when size is known ahead of time
-- [ ] `std::array` used for fixed-size compile-time-known arrays
-- [ ] `std::string_view` used for read-only string params (no ownership)
-- [ ] `std::optional` used instead of sentinel values (e.g., `-1`, `nullptr`) for optional values
-- [ ] No `std::endl` in hot paths (flushes the stream)
-
-## Error Handling
-
-- [ ] Expected failures (not found, invalid input) handled without exceptions
-- [ ] Exceptions used only for truly exceptional/unrecoverable conditions
-- [ ] No exception thrown from destructors (use `noexcept` and `std::terminate` instead if needed)
-- [ ] Exception safety level appropriate for the function (at minimum: no resource leaks)
-- [ ] `std::expected<T, E>` (C++23) or error codes used in library/API code
-
-## Concurrency
-
-- [ ] Shared mutable state protected by `std::mutex` / `std::lock_guard`
-- [ ] No data races on shared variables
-- [ ] `std::atomic` used for simple shared counters and flags
-- [ ] Thread lifecycle managed correctly (`join()`/`detach()` or `jthread`)
-- [ ] No passing of references to locals into detached threads
-
-## Performance Considerations
-
-- [ ] No unnecessary copies (pass by `const&`, use `std::move`, prefer move over copy)
-- [ ] No hidden allocations in hot paths (e.g., `s + "text"` inside a loop)
-- [ ] Vector `reserve()` before known-size loops
-- [ ] Emplacement used when inserting into containers: `vec.emplace_back(args...)` over `vec.push_back(Type(args...))`
-
-## Initialization
-
-- [ ] All variables initialized before use
-- [ ] Member variables initialized in initializer list or with default member initializers
-- [ ] No use of default-initialized built-in types without assignment
-
-## Code Quality
-
-- [ ] No `goto` statements
-- [ ] No macros for anything that can be a `constexpr`, `inline`, or template
-- [ ] Template code in headers uses explicit `typename T` or `class T`
-- [ ] No hardcoded magic numbers — use named constants or `constexpr`
-- [ ] `auto` used appropriately (not hiding intent)
-
-## Testing
-
-- [ ] New code has corresponding unit tests
-- [ ] Edge cases covered: empty containers, zero/negative values, boundary conditions
-- [ ] No commented-out test code committed

package/.claude/skills/cpp-testing/README.md

@@ -1,28 +0,0 @@
-# C++ Testing Skill
-
-C++ testing patterns for Claude Code. Covers unit, integration, and host-side tests, framework selection (GoogleTest / Catch2 / doctest), mocking strategies, TDD workflow, and the 80% coverage gate.
-
-## What it provides
-
-- **SKILL.md** — framework selection + 5 deep-dive references
-- **references/framework-compare.md** — GoogleTest vs Catch2 vs doctest with code samples
-- **references/host-test-for-embedded.md** — pure-CMake host test for firmware `.cpp` without `idf.py`/FreeRTOS
-- **references/mocking.md** — abstract interfaces, link-time seam, `std::function` injection, gmock
-- **references/tdd-workflow.md** — red-green-refactor in C++
-- **references/coverage.md** — gcov/lcov, 80% gate on `main/` and `components/`
-
-## When it triggers
-
-- Writing a new C++ unit or host test
-- Choosing a test framework
-- Setting up a host-side test binary that links firmware code without ESP-IDF
-- Running a test-gate before merging
-- Applying TDD to firmware policy/payload modules
-
-## Manual install
-
-```bash
-cp -R SKILL.md references ~/.claude/skills/cpp-testing/
-```
-
-The BizarHarness installer can also install this automatically — select the **C++ testing** component.