@mrciphersmith/keryx 0.3.2 → 0.3.3

package/src/gdskills/bundled/stacks/c-cpp/governance/scout.json

@@ -0,0 +1,31 @@
+[
+  {
+    "query": "Use when implementing or extending a feature in C or modern C++ (17/20/23) -- ownership and RAII, smart pointer choice, move semantics, std::span, manual malloc/free lifetime in C, and choosing safe standard-library APIs over unsafe ones.",
+    "decision": "create",
+    "topMatch": "python/python-implementation",
+    "recordedAt": "2026-09-25T15:29:36.971Z",
+    "skillName": "c-cpp-implementation"
+  },
+  {
+    "query": "Use when reviewing a C or C++ change for memory-safety and undefined-behavior risks -- use-after-free, double-free, buffer overflows, dangling references, iterator invalidation, unchecked allocations, signed overflow, and unsynchronized shared state. Read-only, no edits.",
+    "decision": "create",
+    "topMatch": "c-cpp/c-cpp-build-fix",
+    "recordedAt": "2026-09-25T15:29:43.782Z",
+    "skillName": "c-cpp-code-review"
+  },
+  {
+    "query": "Use when a C/C++ build fails -- CMake configure/link errors, missing headers, template/generic-instantiation errors, ABI/linker mismatches -- or when a sanitizer (ASan/UBSan/TSan) or ctest run reports a memory-safety, UB, or race failure, with the smallest root-cause fix.",
+    "decision": "create",
+    "topMatch": "go/go-build-fix",
+    "recordedAt": "2026-09-25T15:29:46.104Z",
+    "skillName": "c-cpp-build-fix"
+  },
+  {
+    "query": "Use when a C or C++ test suite needs writing, extending, or fixing -- GoogleTest TEST/TEST_F/TEST_P, death tests, fixture setup/teardown, and verifying a memory-safety or concurrency fix under AddressSanitizer/UndefinedBehaviorSanitizer/ThreadSanitizer.",
+    "decision": "fork",
+    "topMatch": "c-cpp/c-cpp-build-fix",
+    "recordedAt": "2026-09-25T15:30:02.567Z",
+    "skillName": "c-cpp-testing",
+    "justification": "Nearest match c-cpp-build-fix (0.39) shares this pack's own sanitizer vocabulary (ASan/UBSan/TSan) because both skills verify fixes under sanitizers, but they are distinct capabilities: c-cpp-testing writes/extends/fixes GoogleTest test files (TEST_F fixtures, TEST_P, death tests) and never touches source under test, while c-cpp-build-fix diagnoses and fixes compile/link/CMake failures and root-causes a sanitizer-reported bug in production source, never writing new tests. No other matched skill (go-testing, php-laravel-testing, react-testing, ruby-rails-testing, all ~0.21) covers GoogleTest/C++ test idiom or sanitizer-backed test verification at all, so this is a genuine fork of a sibling skill within the same new pack, not a substitute for an existing one."
+  }
+]

package/src/gdskills/bundled/stacks/c-cpp/pack.json

@@ -0,0 +1,42 @@
+{
+  "id": "c-cpp",
+  "family": "language",
+  "modules": ["c-cpp-rules", "c-cpp-skills"],
+  "detectionMarkers": ["c-cpp"],
+  "provenance": {
+    "origin": "authored",
+    "sourceRef": "flow 337, Wave 4 batch 5"
+  },
+  "stability": "experimental",
+  "skills": {
+    "implement": ["c-cpp-implementation"],
+    "test": ["c-cpp-testing"],
+    "review": ["c-cpp-code-review"],
+    "build-fix": ["c-cpp-build-fix"],
+    "migrate": []
+  },
+  "agentProfile": {
+    "displayName": "C / C++",
+    "auditFocus": [
+      "raw `new`/`delete` or manual `malloc`/`free` where RAII/a smart pointer (`unique_ptr`/`shared_ptr`) already fits the ownership model",
+      "a pointer or reference returned to, or captured from, a local/stack-destroyed object (use-after-free / dangling reference)",
+      "a container iterator or pointer used after the container it points into was resized, erased from, or reallocated",
+      "an unchecked `malloc`/`new` return, or a missing `free`/destructor on an error/early-return path in C",
+      "signed integer overflow, unvalidated array/index bounds, or an out-of-bounds access on a fixed-size buffer",
+      "a shared variable read/written from more than one thread with no mutex/atomic guarding it",
+      "a memory-safety or UB bug report whose verification step never mentions AddressSanitizer/UndefinedBehaviorSanitizer/ThreadSanitizer"
+    ],
+    "buildCommands": [
+      "cmake --preset <configured-preset> (or cmake -S . -B build)",
+      "cmake --build build",
+      "ctest --test-dir build --output-on-failure",
+      "cmake -S . -B build-asan -DCMAKE_BUILD_TYPE=Debug -DCMAKE_CXX_FLAGS='-fsanitize=address,undefined -fno-omit-frame-pointer -g' && cmake --build build-asan && ctest --test-dir build-asan"
+    ],
+    "fixGuardrails": [
+      "never silence a sanitizer finding by disabling the sanitizer, adding a suppression, or narrowing what it scans instead of fixing the underlying memory/UB bug",
+      "never replace a real bounds/null check with a cast or a suppression comment to make a warning disappear",
+      "never widen an unsafe C API (`strcpy`, `sprintf`, `gets`) back in while resolving an unrelated failure",
+      "fix the smallest root cause; do not refactor unrelated ownership or threading code while resolving a single build/test/sanitizer failure"
+    ]
+  }
+}

package/src/gdskills/bundled/stacks/c-cpp/rules/coding-style.mdc

@@ -0,0 +1,80 @@
+---
+extends: common
+paths: ["**/*.c", "**/*.h", "**/*.cpp", "**/*.cc", "**/*.cxx", "**/*.hpp", "**/*.hxx", "**/*.hh", "**/*.ipp", "**/*.inl", "**/*.tpp", "**/*.cppm", "**/*.ixx"]
+metadata:
+  origin: authored
+---
+
+# C / C++ coding style
+
+Narrows `core-common-rules`' stack-agnostic style rules to modern C++
+(17/20/23) and modern C idiom. Applies to both `.c`/`.h` and
+`.cpp`/`.cc`/`.cxx`/`.hpp`/`.hxx` files — everything not C/C++-specific
+still comes from the common rules this file `extends`.
+
+## Naming and structure
+
+- `snake_case` for functions, variables, and namespaces; `PascalCase` for
+  types (classes, structs, enums); `SCREAMING_SNAKE_CASE` for macros and
+  compile-time constants — match whichever convention the project already
+  uses over this default when one is established.
+- Keep a header self-contained: `#pragma once` (or a project-consistent
+  include guard) at the top, and every symbol the header uses actually
+  `#include`d in it — do not rely on an include some other header happens
+  to pull in transitively.
+- One translation unit's private helpers go in an anonymous namespace
+  (C++) or are declared `static` (C) — do not give internal linkage away
+  by leaving a file-local helper externally visible.
+- An identifier's name shrinks with its scope: a loop index is `i`, a
+  header-exposed public function gets a full descriptive name.
+
+## Modern C++ idiom (17/20/23)
+
+- Own a heap allocation with `std::unique_ptr` by default; reach for
+  `std::shared_ptr` only when the ownership is genuinely shared (more than
+  one owner can outlive any single other owner) — a `shared_ptr` used for
+  single ownership just adds atomic refcount overhead and obscures who
+  actually owns the object.
+- Prefer `std::make_unique`/`std::make_shared` over a bare `new` passed to
+  a smart pointer constructor — it avoids a leak on an exception thrown
+  between the `new` and the constructor call, and avoids a second
+  allocation for `shared_ptr`'s control block.
+- Use `std::span` (C++20) for a non-owning view over a contiguous range
+  instead of a raw `(pointer, length)` pair — it carries bounds
+  information the raw pair does not, without owning or copying the data.
+- Move, don't copy, when a value's ownership is transferring: accept
+  by-value and `std::move` into place, or take an rvalue-reference
+  overload, rather than accepting `const&` and copying when the caller's
+  object was about to be discarded anyway.
+- Prefer a range-`for` or a `<ranges>` (C++20) pipeline over a manual
+  index loop or raw iterator pair when the loop is a plain traversal —
+  keep the manual iterator form for cases that need the iterator itself
+  (insertion position, mutation while iterating with an explicit
+  erase-returns-next-iterator pattern).
+- `constexpr`/`consteval` any function or value that can be computed at
+  compile time; `const` (or nothing, per project convention) otherwise —
+  do not default to `#define` for a typed constant.
+
+## Modern C safety practices
+
+- Prefer a fixed-size or length-tracked buffer API (`snprintf`, not
+  `sprintf`; `strncpy`/explicit length checks, not `strcpy`/`strcat`;
+  `fgets`, never `gets`) — every string/buffer write states or checks its
+  destination's capacity.
+- Check every `malloc`/`calloc`/`realloc` return for `NULL` before
+  dereferencing it; on `realloc` failure, keep the original pointer (do
+  not overwrite it with the `NULL` return and leak the original block).
+- Prefer C99 designated initializers and stack-based fixed arrays with an
+  explicit, checked bound over a raw pointer with an implicit length
+  carried only in a comment.
+- Const-qualify a pointer parameter the function does not mutate through
+  (`const char *`, not `char *`) — it documents the contract and lets the
+  compiler catch an accidental write.
+
+## Formatting
+
+- Format with the project's configured `clang-format`/`.clang-format` if
+  present; do not hand-format around a formatter that is already
+  configured.
+- Braces and brace-placement follow the project's existing style over any
+  default preference in this file — match neighboring code.

package/src/gdskills/bundled/stacks/c-cpp/rules/patterns.mdc

@@ -0,0 +1,87 @@
+---
+extends: common
+paths: ["**/*.c", "**/*.h", "**/*.cpp", "**/*.cc", "**/*.cxx", "**/*.hpp", "**/*.hxx", "**/*.hh", "**/*.ipp", "**/*.inl", "**/*.tpp", "**/*.cppm", "**/*.ixx"]
+metadata:
+  origin: authored
+---
+
+# C / C++ patterns
+
+Narrows `core-common-rules`' stack-agnostic design guidance to idiomatic
+C/C++ ownership, resource management, and their common anti-patterns.
+Applies to both C and C++ files.
+
+## RAII and ownership (C++)
+
+- Every resource (heap memory, a file handle, a mutex lock, a socket) is
+  owned by exactly one object whose destructor releases it — a raw `new`
+  with a matching `delete` written by hand somewhere else in the function
+  is a bug waiting for an early return or an exception to skip the
+  `delete`. Wrap it in a smart pointer, `std::lock_guard`/`std::unique_lock`,
+  or another RAII type instead.
+- A class that manually manages a resource follows the Rule of
+  Zero (own nothing directly — compose from types that already manage
+  their own resources) or, when it must own a resource directly, the Rule
+  of Five (copy ctor, copy assign, move ctor, move assign, destructor —
+  define all five, or `= delete` the ones that should not exist).
+- A function that hands back a resource does so by return value (RVO/move
+  makes this free), not by an out-parameter raw pointer the caller must
+  remember to release.
+- Never return a pointer or reference to a local (stack) variable, or to a
+  member of a temporary — the referent is destroyed when the function
+  returns, and the caller is left with a dangling reference.
+
+## Manual resource management (C)
+
+- Pair every `malloc`/`fopen`/`pthread_mutex_lock`-style acquire with a
+  `free`/`fclose`/`pthread_mutex_unlock` on every exit path from the
+  function that acquired it, error paths included — a `goto cleanup;`
+  pattern with a single exit-and-release block is the idiomatic way to
+  keep this from being repeated (and missed) at every early `return`.
+- A function that allocates and returns a pointer documents, in its
+  header comment, who owns the result and how it must be released — an
+  API with no stated ownership contract is a leak or a double-free
+  waiting to happen at the call site.
+- Never call `free` on a pointer twice, and set a pointer to `NULL`
+  immediately after freeing it when it could otherwise be read or freed
+  again on a later path — a double-free and a use-after-free are both
+  more likely once a stale non-null value survives past its `free`.
+
+## Containers and iterators
+
+- An iterator, pointer, or reference into a `std::vector` (or similar
+  contiguous container) is invalidated by any operation that can
+  reallocate or shift the underlying storage (`push_back` past capacity,
+  `insert`, `erase`) — do not hold one across such a call; re-fetch it, or
+  use the iterator `erase`/`insert` return to keep iterating correctly.
+- Prefer `std::vector`/`std::array`/`std::string` over a raw
+  owning array or a hand-rolled dynamic buffer — the standard container
+  already manages growth, bounds, and destruction correctly.
+
+## Composition and interfaces
+
+- Prefer composition over deep inheritance hierarchies; reach for
+  polymorphism only when callers genuinely need to treat different
+  concrete types uniformly through a shared interface, not as a default
+  way to share code.
+- A C++ base class meant to be used polymorphically through a base
+  pointer/reference has a `virtual` (or `= default`d, explicitly
+  `virtual`) destructor — a non-virtual destructor on a polymorphic base
+  is undefined behavior when deleting through the base pointer.
+- Keep a public C API's surface small and its ownership rules explicit in
+  the header; do not expose an internal struct's full layout when an
+  opaque handle plus accessor functions would let the implementation
+  change without breaking callers.
+
+## Anti-patterns to flag
+
+- A "god header" with unrelated free functions and macros accumulating
+  under a generic name (`utils.h`, `common.h`) — split by what the code
+  actually does.
+- C-style casts (`(Type)x`) in C++ where a named cast
+  (`static_cast`/`dynamic_cast`/`const_cast`/`reinterpret_cast`) would say
+  which conversion is actually intended and let the compiler catch the
+  wrong one.
+- Output parameters used to fake multiple return values where
+  `std::tuple`/`std::pair`/a small struct (or, in C, a returned struct)
+  would be clearer and harder to call incorrectly.

package/src/gdskills/bundled/stacks/c-cpp/rules/security.mdc

@@ -0,0 +1,90 @@
+---
+extends: common
+paths: ["**/*.c", "**/*.h", "**/*.cpp", "**/*.cc", "**/*.cxx", "**/*.hpp", "**/*.hxx", "**/*.hh", "**/*.ipp", "**/*.inl", "**/*.tpp", "**/*.cppm", "**/*.ixx"]
+metadata:
+  origin: authored
+---
+
+# C / C++ security
+
+Narrows `core-common-rules`' stack-agnostic security rules to C/C++
+memory-safety and undefined-behavior risks, and the sanitizers/safe APIs
+to use instead. Applies to both C and C++ files.
+
+## Memory safety
+
+- Never dereference, write through, or `free` a pointer after it has been
+  freed or has gone out of scope (use-after-free) — set a freed pointer
+  to `NULL` when it could be read again, and never return a pointer or
+  reference to a stack-local object.
+- Never `free`/`delete` the same pointer twice (double-free) — a
+  freed-and-nulled pointer makes a second `free`/`delete` a harmless
+  no-op instead of heap corruption.
+- Bounds-check every array/buffer index and every pointer arithmetic
+  expression built from untrusted input before it is used to read or
+  write memory — an off-by-one or an unchecked length from user input is
+  the most common route to a buffer overflow.
+- Never use `strcpy`, `strcat`, `sprintf`, or `gets` on data whose length
+  is not already statically known to fit the destination — use
+  `snprintf`, a length-checked copy, or a `std::string`/`std::vector`
+  that manages its own capacity.
+
+## Undefined behavior
+
+- Signed integer overflow is undefined behavior in C/C++ (unlike
+  unsigned wraparound, which is well-defined modular arithmetic) — check
+  bounds before an addition/multiplication that could overflow a signed
+  type, or use an unsigned/wider type, or a checked-arithmetic helper,
+  for a bounds or size computation derived from untrusted input.
+- Never read an uninitialized local variable or heap allocation — value-
+  initialize (`Type x{};` in C++, an explicit `= 0`/`memset` in C) any
+  variable whose first use might be a read, and never rely on whatever
+  value happened to be left on the stack or heap.
+- Never access an object through a pointer of an incompatible type (a
+  strict-aliasing violation) — use `memcpy` for a type-punning copy, or
+  (C++20+) `std::bit_cast`, instead of reinterpreting a pointer's type
+  and dereferencing it.
+- Do not read past the end of an array via pointer arithmetic even when
+  the read "usually" lands in valid memory — an out-of-bounds read past
+  the last element is undefined behavior regardless of what happens to be
+  mapped there.
+
+## Concurrency
+
+- Every variable read from more than one thread while at least one thread
+  writes it is guarded by a mutex, or is a `std::atomic`/C11 `_Atomic`
+  type — an unsynchronized shared read/write is a data race, which is
+  undefined behavior in both C and C++, not merely "occasionally wrong."
+- Acquire locks in a consistent global order across the codebase to avoid
+  deadlock; prefer `std::lock_guard`/`std::scoped_lock` (which also
+  supports locking multiple mutexes deadlock-free in one call) over
+  manual `lock()`/`unlock()` pairs, since a manual pair skips the unlock
+  on an early return or exception.
+
+## Sanitizers
+
+- Build and run with AddressSanitizer + UndefinedBehaviorSanitizer
+  (`-fsanitize=address,undefined -fno-omit-frame-pointer -g`, Clang/GCC)
+  whenever investigating a memory-safety or UB bug report, or before
+  trusting a fix for one — ASan catches use-after-free, double-free,
+  buffer overflow, and heap corruption at the exact faulting access; UBSan
+  catches signed overflow, misaligned access, and other UB the compiler
+  is otherwise free to miscompile around silently.
+- Build and run with ThreadSanitizer (`-fsanitize=thread`) — built as a
+  separate binary from ASan/UBSan, the two runtimes are not composable in
+  one build — whenever investigating a suspected data race or before
+  trusting a fix for one.
+- A memory-safety, UB, or concurrency bug report is not actually verified
+  fixed until it has been reproduced and re-run under the relevant
+  sanitizer and comes back clean; a fix that only "looks right" by
+  inspection, or that only passes without a sanitizer attached, has not
+  been verified.
+
+## Dependency and input hygiene
+
+- Validate the length/format of any externally-sourced buffer (network,
+  file, IPC, command-line argument) before parsing it — do not assume a
+  length field in the input itself is trustworthy without a sanity check
+  against the buffer's actual size.
+- Never hard-code a credential, API key, or signing secret in source;
+  load it from environment/secret storage the project already uses.

package/src/gdskills/bundled/stacks/c-cpp/rules/testing.mdc

@@ -0,0 +1,83 @@
+---
+extends: common
+paths: ["**/*.c", "**/*.h", "**/*.cpp", "**/*.cc", "**/*.cxx", "**/*.hpp", "**/*.hxx", "**/*.hh", "**/*.ipp", "**/*.inl", "**/*.tpp", "**/*.cppm", "**/*.ixx"]
+metadata:
+  origin: authored
+---
+
+# C / C++ testing
+
+Narrows `core-common-rules`' stack-agnostic testing rules to GoogleTest
+(and Catch2, where a project already uses it) plus sanitizer-backed
+verification. Applies to both C and C++ test files.
+
+## Layout and naming
+
+- Tests live under a project's own existing test tree (commonly
+  `tests/`, `test/`, or beside the source with a `_test.cpp` suffix) —
+  match whichever convention the project already uses, do not invent a
+  second one.
+- `TEST(SuiteName, CaseName)` for a standalone case; `TEST_F(FixtureName,
+  CaseName)` when the case needs shared `SetUp()`/`TearDown()` state via a
+  fixture class derived from `::testing::Test`. Name suites/cases for the
+  behavior under test, not `Test1`/`Test2`.
+- `TEST_P` with `INSTANTIATE_TEST_SUITE_P` for a parameterized case run
+  against a range of inputs, instead of copy-pasting the same body with
+  different literals across several `TEST`s.
+
+## Fixtures and lifecycle
+
+- Put shared per-test setup in `SetUp()` and teardown in `TearDown()`,
+  not the fixture's constructor/destructor, when the setup can fail in a
+  way the test should assert on (`SetUp()` runs inside the test's own
+  assertion context; a constructor failure does not).
+- A fixture that owns a resource (a temp file, a mock server, a thread)
+  releases it in `TearDown()` even when the test body fails an assertion
+  partway through — do not rely on a `TEST_F` body reaching a cleanup
+  statement at its end.
+
+## Assertions
+
+- `ASSERT_*` when the test cannot meaningfully continue after a failure
+  (a null pointer that every following line would dereference);
+  `EXPECT_*` when later checks in the same test still give useful
+  information after one fails.
+- `ASSERT_DEATH`/`EXPECT_DEATH` for code whose contract is to terminate
+  the process on a given input (an assertion failure, a `CHECK`) — set
+  `GTEST_FLAG_SET(death_test_style, "threadsafe")` (or the project's own
+  configured style) when the test binary is multi-threaded, since the
+  default `fast` style can misbehave by forking a process with more than
+  one live thread.
+- Compare floating-point values with `EXPECT_NEAR`/`EXPECT_FLOAT_EQ`, not
+  `EXPECT_EQ`, unless the value is provably exact (an integer-valued
+  computation stored in a float).
+
+## Determinism and concurrency
+
+- Never synchronize a multi-threaded test with `sleep`/`usleep`/
+  `std::this_thread::sleep_for` to "give the other thread time" — join
+  the thread, wait on a condition variable, or use a future/promise so
+  the test is deterministic and not flaky under load.
+- A test exercising concurrent code is run under ThreadSanitizer
+  (`-fsanitize=thread`) at least once before being trusted, since a data
+  race can pass every assertion while still being undefined behavior.
+
+## Sanitizer-backed verification
+
+- Build and run the test suite under AddressSanitizer + UndefinedBehavior-
+  Sanitizer for any change touching manual memory management, buffers, or
+  pointer arithmetic — a leaking or corrupting test can still report
+  green under plain assertions while ASan/UBSan catch the actual bug.
+- New behavior gets a new test in the same change; a bug fix (especially
+  a memory-safety or UB fix) gets a regression test that reproduces the
+  failure under the relevant sanitizer before the fix and passes clean
+  after it.
+
+## Fuzzing
+
+- A parser, decoder, or anything else that touches untrusted input
+  formats gets a libFuzzer harness (`LLVMFuzzerTestOneInput`, built with
+  `-fsanitize=fuzzer,address,undefined`) when the project already has
+  fuzzing infrastructure, or a documented seed corpus ready for one to be
+  added — do not skip fuzz coverage for a new untrusted-input parser
+  solely because unit tests pass.

package/src/gdskills/bundled/stacks/c-cpp/skills/c-cpp-build-fix/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: c-cpp-build-fix
+description: "Use when a C/C++ build fails -- CMake configure/link errors, missing headers, template/generic-instantiation errors, ABI/linker mismatches -- or when a sanitizer (ASan/UBSan/TSan) or ctest run reports a memory-safety, UB, or race failure, with the smallest root-cause fix."
+triggers:
+  - "cmake build is failing"
+  - "fix this linker error"
+  - "AddressSanitizer reports a heap-buffer-overflow"
+  - "UBSan reports signed overflow"
+  - "ThreadSanitizer flags an unsynchronized access to this shared counter"
+  - "fix this C++ template instantiation error"
+metadata:
+  origin: authored
+  category: build-fix
+  version: "1.0.0"
+  compatible_harnesses: "claude,codex,cursor,zed,opencode"
+license: "MIT"
+---
+
+# C / C++ build fix
+
+Resolve a C/C++ build/configure/link failure, or a sanitizer/`ctest`
+failure — with the smallest change that fixes the actual root cause.
+`rules/coding-style.mdc`, `rules/patterns.mdc`, and `rules/security.mdc`
+govern what a "correct" fix looks like; this skill never reaches for a
+suppression instead of a fix.
+
+## Workflow
+
+### Step 1: Reproduce and classify
+
+```bash
+cmake --build build
+ctest --test-dir build --output-on-failure
+```
+
+Read the exact error text and classify it:
+
+- **Configure error** (CMake cache mismatch, a missing `find_package`
+  dependency, a stale `build/` directory from a changed toolchain).
+- **Compile error** (undefined symbol, type mismatch, missing header,
+  wrong argument count/type).
+- **Template/generic-instantiation error** (a template that cannot
+  deduce its argument, a constraint/concept that is not satisfied, an
+  incomplete type used where a complete one is required).
+- **Link/ABI error** (undefined reference, a symbol built against a
+  different ABI or ODR-violating duplicate definition across translation
+  units, a missing `target_link_libraries`).
+- **Sanitizer failure** (ASan `heap-buffer-overflow`/`use-after-free`,
+  UBSan `signed integer overflow`/`misaligned address`, TSan
+  `data race`) — read the sanitizer's full stack trace; it names the
+  exact faulting access and, for TSan, both racing accesses.
+- **Test failure** (`ctest` reports a failing case with no sanitizer
+  involved).
+
+### Step 2: Fix by category
+
+**Configure/CMake:** re-run configure after a clean `build/` directory
+when the cache is simply stale against changed `CMakeLists.txt`. For a
+genuine missing dependency, add the correct `find_package`/
+`target_link_libraries` rather than hand-pointing at a local path that
+happens to work on one machine.
+
+**Compile error:** fix the actual type/signature/missing-include issue
+the compiler names. A missing header is fixed by including the header
+that actually declares the symbol, not by forward-declaring around it
+unless the project's own convention already does that intentionally.
+
+**Template/generic-instantiation:** check whether the call site can
+supply the type argument explicitly, or whether a concept/`static_assert`
+is correctly rejecting an unsupported type (in which case the fix is at
+the call site, not the template). Do not loosen a constraint just to make
+an unrelated instantiation compile.
+
+**Link/ABI:** an undefined reference usually means a missing
+`target_link_libraries` entry or a translation unit not compiled into
+the target — fix the CMake target graph. An ODR violation (the same
+symbol defined differently in two translation units) is fixed by
+unifying the definition, never by reordering link order to hide it.
+
+**Sanitizer failure (ASan/UBSan):** read the exact faulting access from
+the report (allocation site, free site if UAF, faulting instruction) and
+add the actual missing check/ownership fix at that point — a bounds
+check, a lifetime fix (return by value instead of a reference into a
+temporary), or a `NULL` check. Never rebuild without the sanitizer to
+make the failure "go away"; that hides the bug, it does not fix it.
+
+**Sanitizer failure (TSan):** add synchronization (mutex, atomic, or a
+join/wait) at the specific shared-state access TSan names for both
+racing accesses — do not just serialize the whole test or add a `sleep`
+to hide the timing window.
+
+**Test failure (no sanitizer):** fix the assertion or the code it tests,
+whichever is actually wrong per the spec — never loosen an assertion just
+to make it pass.
+
+### Step 3: Verify
+
+```bash
+cmake --build build
+ctest --test-dir build --output-on-failure
+```
+
+Re-run under the sanitizer that originally caught the failure (ASan+UBSan
+or TSan) if the failure came from one — the fix is not verified until the
+sanitizer run is also clean, not just the plain build.
+
+### Step 4: Report
+
+```
+Fixed: src/parser/token_stream.cpp — heap-buffer-overflow in
+TokenStream::peek() (ASan)
+  - Root cause: peek() read one byte past the buffer on the last token
+    boundary; missing bounds check before the trailing-byte read
+  - Build + ctest + ASan/UBSan re-run all pass
+```
+
+State the root cause in one sentence, not just "fixed the error."
+
+## Rules
+
+- Find and fix the smallest change that addresses the actual root cause —
+  never widen a fix beyond what the failure requires.
+- NEVER disable, narrow the scope of, or suppress a sanitizer finding
+  instead of fixing the underlying memory-safety/UB/race bug it caught.
+- NEVER reintroduce an unsafe API (`strcpy`, `sprintf`, `gets`) while
+  resolving an unrelated failure.
+- NEVER loosen a template constraint, a `static_assert`, or a test
+  assertion just to make a failure disappear without understanding why
+  it was there.
+- NEVER change the project's declared C/C++ standard just to make an
+  error disappear without understanding why the code needs it.
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "I'll just turn off ASan for this test so CI goes green" | Silences the finding without fixing the memory-safety bug it caught; fix the bounds/lifetime issue at the site ASan names instead |
+| "This data race is rare, I'll add a sleep to make it stop happening" | A `sleep` narrows the timing window without removing the race; TSan will still be correct that the access is unsynchronized, and the race can still fire under different scheduling |
+| "I'll widen this concept/constraint so more types compile" | Loosening a constraint to silence one instantiation failure can let a genuinely unsupported type instantiate the template incorrectly elsewhere |
+| "sprintf is fine here, the buffer is 'probably' big enough" | "Probably" is exactly the assumption that turns into a buffer overflow the first time an input is bigger than expected; use `snprintf` |
+
+## Verification
+
+Do not report the fix done until all of the following hold:
+
+- `cmake --build build` and `ctest --test-dir build --output-on-failure`
+  both exit 0.
+- If the original failure came from a sanitizer, the sanitizer build/run
+  is re-verified clean, not just the plain build.
+- The change is the smallest one that addresses the stated root cause —
+  no unrelated files touched.
+- The report states the root cause in one sentence, not just "build now
+  passes."

package/src/gdskills/bundled/stacks/c-cpp/skills/c-cpp-build-fix/evals.json

@@ -0,0 +1,74 @@
+{
+  "triggers": {
+    "positive": [
+      "Our ctest suite segfaults inside the ASan build after the latest merge, can you track down what's reading past the buffer",
+      "ThreadSanitizer flagged a data race, help me fix it",
+      "UndefinedBehaviorSanitizer is reporting signed integer overflow here",
+      "Our CMake configure step is failing with an undefined reference",
+      "This template won't instantiate, fix the compile error",
+      "The build is failing with a missing header error",
+      "Our test binary crashes under ASan, track down the root cause"
+    ],
+    "negative": [
+      "Implement this new feature from scratch, no build errors involved",
+      "Write GoogleTest cases for this already-working class",
+      "Review this diff for memory safety before merging",
+      "Fix this failing go build for the worker package",
+      "Our npm build is failing with a webpack error",
+      "Fix this failing pytest collection error"
+    ]
+  },
+  "scenarios": [
+    {
+      "id": "asan-heap-overflow-fix-not-suppress",
+      "prompt": "AddressSanitizer reports:\n\n```\nERROR: AddressSanitizer: heap-buffer-overflow on address ...\nREAD of size 1 at ... thread T0\n    #0 TokenStream::peek() token_stream.cpp:42\n```\n\nHow do I fix this?",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct answer treats the ASan report as pointing at a real out-of-bounds read in TokenStream::peek() at line 42, and fixes it by adding or correcting the bounds check that prevents reading past the buffer -- it does not suggest disabling, narrowing, or otherwise routing around the sanitizer to make the finding go away.",
+          "pass_criteria": [
+            "Identifies the finding as a genuine out-of-bounds read at the reported location (TokenStream::peek(), token_stream.cpp:42), not a false positive to be dismissed.",
+            "Proposes a concrete fix: adding/correcting a bounds check (e.g. comparing the read position against the buffer's length) before the read that peek() performs.",
+            "States that the fix should be re-verified by re-running the test under the ASan build, not just a plain build."
+          ],
+          "fail_criteria": [
+            "Recommends disabling ASan, removing the sanitizer flag, adding an ASan suppress list/suppression entry, or excluding token_stream.cpp/this test from the sanitized build instead of fixing the out-of-bounds read. Mentioning that only to warn against it is not a failure."
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "This is a real out-of-bounds read, not a false positive -- ASan is pointing at token_stream.cpp:42 inside TokenStream::peek(). Read the surrounding code: peek() is almost certainly reading `buffer_[pos_]` (or similar) without first checking that `pos_` is still within `buffer_`'s bounds, most likely on the last token where `pos_` has already reached the end. Fix it by adding the missing bounds check before the read, e.g. `if (pos_ >= buffer_.size()) return kEof;` (or whatever peek()'s documented behavior should be at end-of-input) before the indexing. Once the check is in, rebuild the ASan configuration (`cmake --build build-asan`) and re-run the specific test that exercises this path (`ctest --test-dir build-asan -R TokenStreamTest --output-on-failure`) to confirm ASan no longer reports the overflow -- a plain, non-sanitized rebuild passing is not sufficient confirmation.",
+        "known_wrong": "ASan is pretty aggressive and throws false positives on tight parsing loops like this fairly often. Simplest fix is to just suppress it -- add token_stream.cpp's TokenStream::peek to an ASan suppress list (or drop -fsanitize=address for that one translation unit) so the rest of the sanitized build stays clean and this known-noisy function doesn't keep flagging.",
+        "vague": "Take a look at what's happening around line 42 in peek() and make sure the bounds are being handled correctly there.",
+        "subtle_wrong": "The read at line 42 is one byte past the buffer on the very last token, so the safest fix is to just allocate the underlying buffer with one extra byte of padding (`buffer_.resize(buffer_.size() + 1)`) when TokenStream is constructed, so that stray read always lands in valid memory. That way peek()'s existing logic doesn't need to change at all, and the ASan report goes away because the read is no longer actually out of bounds."
+      },
+      "anti_patterns": ["suppress"]
+    },
+    {
+      "id": "tsan-race-add-sync-not-serialize",
+      "prompt": "ThreadSanitizer reports a data race:\n\n```\nWARNING: ThreadSanitizer: data race\n  Write of size 8 at 0x... by thread T1:\n    #0 Cache::put(...) cache.cpp:31\n  Previous read of size 8 at 0x... by thread T2:\n    #0 Cache::get(...) cache.cpp:18\n```\n\nHow should I fix this?",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct answer adds real synchronization (a mutex guarding both Cache::get and Cache::put's access to the shared state, or converting the field to std::atomic if a single word suffices) at the specific accesses TSan names, rather than working around the race by serializing the whole test suite or disabling the sanitizer.",
+          "pass_criteria": [
+            "Names a concrete synchronization mechanism -- a mutex (e.g. std::lock_guard/std::mutex) guarding both cache.cpp:31 (put) and cache.cpp:18 (get), or std::atomic if the shared data is a single word -- applied at the actual accesses TSan flagged.",
+            "States that both the read in get() and the write in put() need to be covered by the same synchronization, not just one side.",
+            "Does not propose serializing the test (running it single-threaded, adding a global test-only lock around the whole test body) or disabling/skipping TSan as the fix."
+          ],
+          "fail_criteria": [
+            "Recommends running the test single-threaded, adding a sleep to reduce the race window, or disabling/skipping ThreadSanitizer instead of adding real synchronization to Cache::get/Cache::put. Mentioning that only to warn against it is not a failure."
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "TSan is naming the actual unsynchronized pair: a write in Cache::put() at cache.cpp:31 racing a read in Cache::get() at cache.cpp:18, both touching the same shared field with no lock between them. Add a std::mutex member to Cache guarding whatever field both functions touch, and take it in both: `std::lock_guard<std::mutex> lock(mutex_);` at the top of both get() and put() before they read/write the shared state. If the shared data really is just a single word (a counter, a pointer swap), std::atomic<T> with appropriate memory order is a lighter-weight alternative to a full mutex -- but either way, both the read side and the write side need the same synchronization, not just one of them. Rebuild under TSan (`-fsanitize=thread`) and re-run the specific test to confirm the warning is gone before considering this fixed.",
+        "known_wrong": "The simplest fix is to just run this particular test single-threaded -- add `GTEST_FLAG_SET` or a test-only global lock around the whole test body so get() and put() never actually execute concurrently during the test run. That removes the race TSan is seeing without having to add locking to Cache itself, which keeps the production code's hot path exactly as fast as it is today.",
+        "vague": "Cache::get and Cache::put seem to be touching something shared without any protection, that probably needs to be locked down.",
+        "subtle_wrong": "Add the mutex, but only take the lock inside put() around the write at cache.cpp:31 -- get() at cache.cpp:18 is just reading a value, and a plain read of an already-word-aligned field is safe to leave unlocked on most platforms since a single aligned load or store doesn't tear. That gets the write side properly guarded, which is the side TSan is really worried about, without slowing down the more frequent read path with lock overhead."
+      }
+    }
+  ]
+}