@damiangilgonzalez/harness 1.3.7

package/skills/course-storytelling/references/mental-models.md

@@ -0,0 +1,115 @@
+# Mental Models — Naming, Analogy Engineering & Grounding
+
+A concept the student can't *name* is a concept they can't repeat — and what can't be repeated isn't retained. A concept they can't picture is one that never gets concrete enough to *use*. This file is the craft of both: designing sticky, ownable names and engineering the analogies that drop an abstraction down to earth. It feeds the "MENTAL MODEL" and "GROUNDED ANALOGY" beats of the landing recipe (`concept-landing-recipe.md`) and the "new opportunity" handoff from `brunson-frameworks.md`.
+
+---
+
+## Part 1 — Designing a named mental model
+
+A mental model is a short, ownable handle the student carries out of the lesson and reuses. Good names do three jobs: **compress** (one phrase recalls the whole idea), **transfer** (it applies beyond the example), and **stick** (it's easy to say and hard to forget).
+
+### The naming tests (a name must pass all four)
+
+1. **Sayable** — a student can repeat it out loud, from memory, a week later. 2–4 words.
+2. **Picturable** — it evokes a concrete image or object, not an abstraction. ("The Elevator Button" pictures; "Operational Convergence" does not.)
+3. **Ownable** — it's specific enough to feel like *this* teacher's coinage, not a generic term they could Google.
+4. **Load-bearing** — the name encodes the *mechanism*, so recalling the name recalls how it works.
+
+### Naming patterns that work
+
+| Pattern | Shape | Example (for a concept) |
+| --- | --- | --- |
+| Concrete object | "The [familiar object]" | "The Elevator Button" (idempotency) |
+| Vivid action | "[Verb] the [noun]" | "Shrink the Blast Radius" (fault isolation) |
+| Memorable contrast | "[X], not [Y]" | "Spec, Not Chore" (test-first) |
+| Rule of N | "The [N] [things]" | "The Two-Pizza Rule" (team size) |
+| Named law/effect | "The [Name] [Law/Effect]" | "The Last-Mile Tax" (deployment friction) |
+
+```text
+Bad  (no name)    — "We should design operations so repeated execution is safe."
+Bad  (jargon name)— "Operational Idempotence Convergence" (unsayable, unpicturable, un-ownable)
+Good (named)      — "The Elevator Button: press it five times, one elevator still comes."
+```
+
+### Where names live
+
+Persist every coined model in `docs/wiki/stack/course-storytelling.md` (or under `wiki/teaching/`) so names stay consistent across lessons and the student hears the same handle every time. A model renamed mid-course is a model un-learned.
+
+---
+
+## Part 2 — Analogy & metaphor engineering
+
+An analogy maps an unfamiliar concept onto something the student already understands deeply. Engineered well, it does the explaining for you. Engineered carelessly, it teaches the wrong thing.
+
+### The mapping method
+
+```text
+ANALOGY MAP
+Target (unfamiliar) ... the concept you're teaching
+Source (familiar) ..... something from the LEARNER'S world (from wiki/teaching/learner.md)
+Mapped parts .......... list each piece of the target -> its match in the source
+Where it breaks ....... the ONE place the analogy fails (state it — prevents over-extension)
+```
+
+### Rules
+
+- **Source from THEIR world, not yours.** A cooking analogy for chefs, a sports analogy for athletes, a spreadsheet analogy for finance folks. Pull the source domain from the learner profile.
+- **Map the mechanism, not just the vibe.** A good analogy survives "okay, so what happens when…" — the parts correspond. A vibe-only analogy ("it's like magic") collapses on the first follow-up.
+- **State where it breaks.** Every analogy fails somewhere. Naming the break point *before* a student finds it keeps trust and prevents them from learning the wrong thing.
+- **One analogy per concept.** Stacking three analogies for one idea dilutes all three. Pick the strongest.
+
+### Worked example — "idempotency" → "The Elevator Button"
+
+```text
+Target: an idempotent operation (repeated calls = one effect)
+Source: pressing an elevator call button
+Mapped parts:
+  - the request          -> pressing the button
+  - the side effect      -> one elevator dispatched
+  - retries / dup sends  -> pressing the lit button again
+  - the idempotency key  -> the button's "already lit" state
+Where it breaks: a real elevator eventually arrives regardless; an idempotent API needs the key
+  to RECOGNIZE the duplicate — name this so they don't think "it just works by magic".
+```
+
+```text
+Bad  (vibe only)  — "Idempotency is like, you know, it just handles duplicates gracefully."
+Good (mapped)     — the elevator map above: every part corresponds, and the break is named.
+```
+
+---
+
+## Part 3 — Grounding abstract → concrete
+
+Three moves that pull an abstraction down to where the student lives.
+
+1. **Replace the variable with a value.** Don't say "for any request"; say "for *your* 4pm deploy." Specifics are graspable; generalities float.
+2. **Explain it like their day.** Recast the concept inside a moment from the learner's actual routine (commute, standup, the ticket they're avoiding). Pulled from `wiki/teaching/learner.md`.
+3. **Future-pace it.** Walk them through a near-future moment where they use the idea and it pays off. The brain pre-experiences the win and wants the concept that delivers it. (Story-selling move — see `brunson-frameworks.md`.)
+
+```text
+Bad  (abstract)  — "Backoff prevents thundering-herd retries from overwhelming a recovering service."
+Good (grounded)  — "Your service just came back from an outage. The instant it's up, 10,000 queued
+                    retries hit it at once and knock it over again. Backoff is everyone waiting a
+                    polite, increasing beat before knocking — so the recovering service can breathe.
+                    Next incident, you'll add jittered backoff and watch the recovery actually hold."
+```
+
+---
+
+## Part 4 — "Make it land" tests
+
+Apply these to any reframed concept before shipping. If it fails one, it isn't landed.
+
+- **The repeat-back test.** Could the student explain this to a peer in one sentence using your name for it? If not, the name or analogy is weak.
+- **The week-later test.** Will they still recall the name and the picture next week with no notes? If it needs notes, it's not sticky.
+- **The follow-up test.** Does the analogy survive "okay, but what about…"? If it collapses, the mapping is vibe-only — re-map or name the break.
+- **The so-what test.** Can the student say why it matters to *them*, in their world? If not, you stopped before grounding.
+- **The jargon test.** Every term either glossed, grounded, or cut. An unexplained term is a leak where attention drains out.
+
+## See Also
+
+- `../SKILL.md` — the non-negotiables (name everything, ground everything).
+- `concept-landing-recipe.md` — where the named model + analogy slot into the seven beats.
+- `brunson-frameworks.md` — the "new opportunity" beat that hands off to the named model; future-pacing.
+- `learner-grounding.md` — the learner's world that analogy source domains are drawn from.

package/skills/course-storytelling/scripts/verify.sh

@@ -0,0 +1,223 @@
+#!/usr/bin/env bash
+#
+# verify.sh — "did it land?" QA gate for the `course-storytelling` skill.
+#
+# WHAT IT DOES (read-only; never edits a file)
+#   Static, network-free heuristics over your lesson/course source files. For each
+#   concept section it checks that the teaching has the ingredients that make it land:
+#     1. Story presence    — a section that teaches a concept but has no narrative
+#        markers (no "I", no "story", no time/place setup) is a `no-story` lesson.
+#     2. Named model       — a memorable, ownable name (a "The X" handle / bolded coinage).
+#     3. Grounded analogy  — an analogy marker ("like", "imagine", "think of it as").
+#     4. Application step   — a do-this-now action ("try this", "do this", "your turn").
+#     5. So-what payoff     — a future-paced close ("next time", "you'll be able to", "so that").
+#     6. Abstraction / jargon density — flags sections heavy on abstract nouns
+#        (-tion/-ity/-ность style) with no analogy nearby.
+#     7. markdownlint of lesson sources, if markdownlint is installed.
+#
+#   Every finding is a WARNING by default (teaching is judgement, not pass/fail).
+#   Use --strict to turn warnings into a failure (exit 1) so CI can gate on it.
+#   A missing tool is reported yellow and SKIPPED — never a failure.
+#
+# HOW TO RUN (inside YOUR project, not the skills repo)
+#   ./verify.sh                 # scan ./ for lesson sources (*.md, *.mdx, *.txt)
+#   ./verify.sh --path lessons  # scan a subdirectory
+#   ./verify.sh --strict        # treat any warning as a failure (exit 1)
+#
+# EXIT CODES
+#   0  clean, or warnings only without --strict
+#   1  a real failure, or --strict with any warning
+#   2  bad usage
+#
+# Runs on stock macOS bash 3.2: no mapfile, no associative arrays, arrays are
+# initialised and only expanded when non-empty under `set -u`.
+
+set -euo pipefail
+
+# --- portability: runs on stock macOS bash 3.2 ------------------------------
+if [ -z "${BASH_VERSION:-}" ]; then
+  printf 'This script requires bash (any version >= 3.2). Run: bash %s\n' "$0" >&2
+  exit 2
+fi
+
+# --- color helpers (no escape codes when not a TTY) -------------------------
+if [ -t 1 ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; NC=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; NC=''
+fi
+
+ok_count=0; skip_count=0; warn_count=0; fail_count=0
+
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN"  "$NC" "$*"; ok_count=$((ok_count + 1)); }
+skip() { printf '%s[skip]%s %s\n' "$YELLOW" "$NC" "$*"; skip_count=$((skip_count + 1)); }
+warn() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; warn_count=$((warn_count + 1)); }
+fail() { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; fail_count=$((fail_count + 1)); }
+
+usage() {
+  # print the header comment block (lines 2..44), stripping the leading "# "
+  sed -n '2,44p' "$0" | sed 's/^# \{0,1\}//'
+}
+
+# --- arg parse --------------------------------------------------------------
+SCAN_PATH="."
+STRICT=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --path)    SCAN_PATH="${2:?--path needs a value}"; shift 2 ;;
+    --strict)  STRICT=1; shift ;;
+    -h|--help) usage; exit 0 ;;
+    *) printf '%sUnknown argument: %s%s\n\n' "$RED" "$1" "$NC"; usage; exit 2 ;;
+  esac
+done
+
+if [ ! -e "$SCAN_PATH" ]; then
+  printf '%sPath not found: %s%s\n' "$RED" "$SCAN_PATH" "$NC"; exit 2
+fi
+
+have() { command -v "$1" >/dev/null 2>&1; }
+
+# count_lines <file>: number of lines in a file; 0 if missing/empty.
+# Robust across BSD/GNU: wc -l can print leading spaces, so strip non-digits.
+count_lines() {
+  if [ -s "$1" ]; then
+    wc -l < "$1" 2>/dev/null | tr -dc '0-9'
+  else
+    printf '0'
+  fi
+}
+
+# find lesson source files (markdown / text). Prints one path per line.
+# Excludes the conventional docs wiki/raw so we lint LESSONS, not the profile.
+list_lessons() {
+  find "$SCAN_PATH" \
+    \( -name '*.md' -o -name '*.mdx' -o -name '*.txt' \) \
+    -type f \
+    ! -path '*/node_modules/*' \
+    ! -path '*/.git/*' \
+    ! -path '*/docs/*' \
+    2>/dev/null || true
+}
+
+# file_has <file> <pattern>: 0 if the (case-insensitive) pattern appears in the file.
+file_has() { grep -iqE "$2" "$1" 2>/dev/null; }
+
+# --- ensure we have a searcher ----------------------------------------------
+# The per-file checks use grep (via file_has); find gathers the lesson list.
+if ! have grep; then
+  skip "grep not found — cannot scan lesson sources; install grep"
+  printf '\nok=%d skip=%d warn=%d fail=%d\n' "$ok_count" "$skip_count" "$warn_count" "$fail_count"
+  exit 0
+fi
+
+# --- gather lesson files ----------------------------------------------------
+TMPDIR_V="$(mktemp -d 2>/dev/null || printf '/tmp/verify-cs.%s' "$$")"
+mkdir -p "$TMPDIR_V" 2>/dev/null || true
+cleanup() { rm -rf "$TMPDIR_V" 2>/dev/null || true; }
+trap cleanup EXIT
+
+LESSONS="$TMPDIR_V/lessons"
+list_lessons > "$LESSONS" 2>/dev/null || true
+n_lessons="$(count_lines "$LESSONS")"
+
+if [ "$n_lessons" -eq 0 ]; then
+  skip "no lesson sources (*.md, *.mdx, *.txt) found under $SCAN_PATH"
+  printf '\nok=%d skip=%d warn=%d fail=%d\n' "$ok_count" "$skip_count" "$warn_count" "$fail_count"
+  exit 0
+fi
+
+printf 'Scanning %s lesson file(s) under: %s\n\n' "$n_lessons" "$SCAN_PATH"
+
+# Heuristic markers (case-insensitive ERE).
+STORY_RE='\bi (was|had|remember|learned|realized|once)\b|\bstory\b|\bone (day|night|morning)\b|at the time|years? (ago|in)|epiphany|the moment (i|we|they)'
+NAME_RE='\bthe [A-Z][a-z]+( [A-Z][a-z]+)?\b|\*\*[^*]+\*\*|call (it|this) the|i call (it|this)|known as the'
+ANALOGY_RE='\blike (a|an|the|your)\b|\bimagine\b|\bthink of (it|this) as\b|\bit.?s (basically|essentially) (a|an|like)\b|analog|metaphor|as if'
+APPLICATION_RE='\btry (this|it)\b|\bdo this\b|\byour turn\b|right now|before you (close|move|continue)|exercise|step 1|hands.?on|go (build|add|write|open)'
+SOWHAT_RE='next time|you.?ll (be able|now|never)|so that you|what.?s now possible|from now on|imagine being able|future|the payoff'
+
+# Per-file results (bash 3.2: append to temp files, count in parent shell).
+NS="$TMPDIR_V/no_story";   : > "$NS"
+NN="$TMPDIR_V/no_name";    : > "$NN"
+NA="$TMPDIR_V/no_analogy"; : > "$NA"
+NP="$TMPDIR_V/no_appl";    : > "$NP"
+NW="$TMPDIR_V/no_sowhat";  : > "$NW"
+
+while IFS= read -r f; do
+  [ -z "$f" ] && continue
+  file_has "$f" "$STORY_RE"       || printf '%s\n' "$f" >> "$NS"
+  file_has "$f" "$NAME_RE"        || printf '%s\n' "$f" >> "$NN"
+  file_has "$f" "$ANALOGY_RE"     || printf '%s\n' "$f" >> "$NA"
+  file_has "$f" "$APPLICATION_RE" || printf '%s\n' "$f" >> "$NP"
+  file_has "$f" "$SOWHAT_RE"      || printf '%s\n' "$f" >> "$NW"
+done < "$LESSONS" || true   # read returns 1 at EOF; harmless under set -e
+
+report_files() {
+  label="$1"; listfile="$2"
+  n="$(count_lines "$listfile")"
+  if [ "$n" -gt 0 ]; then
+    warn "$label ($n file(s)):"
+    head -n 8 "$listfile" | sed 's/^/        /'
+    warn_count=$((warn_count + n - 1))   # warn() already counted 1
+  else
+    ok "no $label"
+  fi
+}
+
+# --- 1..5 landing-ingredient checks -----------------------------------------
+report_files "lessons with no story marker (add an Epiphany Bridge beat)"        "$NS"
+report_files "lessons with no named mental model (name the concept)"             "$NN"
+report_files "lessons with no grounded analogy (add a concrete metaphor)"        "$NA"
+report_files "lessons with no application step (add a do-this-now)"              "$NP"
+report_files "lessons with no so-what payoff (future-pace the close)"            "$NW"
+
+# --- 6. abstraction / jargon density ----------------------------------------
+# Heuristic: lines dense in abstract -tion/-ity/-ism nouns. Flag files where such
+# lines appear AND the file has no analogy marker (analogy is the antidote).
+ABSTRACT_RE='\b[a-z]{4,}(tion|ality|ility|ism|ance|ence)\b'
+JARGON_HITS="$TMPDIR_V/jargon"; : > "$JARGON_HITS"
+while IFS= read -r f; do
+  [ -z "$f" ] && continue
+  dense="$(grep -ioE "$ABSTRACT_RE" "$f" 2>/dev/null | wc -l | tr -dc '0-9')"
+  [ -z "$dense" ] && dense=0
+  if [ "$dense" -ge 12 ] && ! file_has "$f" "$ANALOGY_RE"; then
+    printf '%s (%s abstract nouns, no analogy)\n' "$f" "$dense" >> "$JARGON_HITS"
+  fi
+done < "$LESSONS" || true   # read returns 1 at EOF; harmless under set -e
+n_jargon="$(count_lines "$JARGON_HITS")"
+if [ "$n_jargon" -gt 0 ]; then
+  warn "jargon/abstraction-dense lessons with no grounding analogy ($n_jargon file(s)):"
+  head -n 8 "$JARGON_HITS" | sed 's/^/        /'
+  warn_count=$((warn_count + n_jargon - 1))
+else
+  ok "no abstraction-dense, analogy-less lessons"
+fi
+
+# --- 7. markdownlint of lesson sources (if available) -----------------------
+if have markdownlint; then
+  # Lint only the lesson files; warn on findings, never fail the gate here.
+  ml_out="$TMPDIR_V/mdlint"
+  # shellcheck disable=SC2046  # word-splitting the file list is intended here
+  markdownlint $(cat "$LESSONS") > "$ml_out" 2>&1 || true
+  if [ -s "$ml_out" ]; then
+    warn "markdownlint findings in lesson sources:"
+    head -n 10 "$ml_out" | sed 's/^/        /'
+  else
+    ok "markdownlint clean on lesson sources"
+  fi
+else
+  skip "markdownlint not found — skipping markdown lint (npm i -g markdownlint-cli)"
+fi
+
+# --- summary ----------------------------------------------------------------
+printf '\nok=%d skip=%d warn=%d fail=%d\n' "$ok_count" "$skip_count" "$warn_count" "$fail_count"
+
+cat <<'EOF'
+
+Note: every finding above is a heuristic WARNING — teaching is judgement, not pass/fail.
+Review each: does the concept actually have a story, a named model, a grounded analogy, an
+application step, and a so-what? Then fix or justify. Re-run with --strict to gate CI.
+EOF
+
+if [ "$fail_count" -gt 0 ]; then exit 1; fi
+if [ "$STRICT" -eq 1 ] && [ "$warn_count" -gt 0 ]; then exit 1; fi
+exit 0

package/skills/cpp/SKILL.md

@@ -0,0 +1,302 @@
+---
+name: cpp
+description: "Use when writing, reviewing, modernizing, building, or debugging C++ - RAII and resource lifetime, smart-pointer ownership, move semantics and the Rule of Zero/Five, target-based CMake with FetchContent, and killing undefined behavior with ASan/UBSan/TSan plus clang-tidy. 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` |
+
+Delegate: 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); the C++-specific
+memory/UB controls (bounds, lifetime, integer overflow, format-string, sanitizers) stay
+**here**. Containerizing and shipping the binary -> [`deployment`](../deployment/SKILL.md);
+this skill stops at the CMake build + a sanitizer-CI note.
+
+## 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`.** So no naked owning pointer ever exists.
+5. **Never an owning raw pointer.** Raw pointers/references are non-owning borrows only.
+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.** 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.
+9. **Sanitizers + warnings-as-errors in CI.** Build and test under `-fsanitize=address,undefined`
+   with `-Werror`.
+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
+
+| 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` |
+| Local gate | `./scripts/verify.sh` (run in your project root) |
+
+## Project grounding (docs)
+
+In a project with a `docs/` layer (the [`harness`](../harness/SKILL.md) Karpathy wiki), read
+`docs/wiki/stack/cpp.md` first and stay consistent with it. If it is missing or stale, write
+this project's real choices there — std version and compiler matrix, CMake layout and presets, the
+sanitizer/warning policy, the ownership/error conventions — index it in `docs/wiki/index.md`
+(the Knowledge map; root `CLAUDE.md` keeps only a pointer to it), and bump its `Updated` date in
+the same change as any convention change. No `docs/` layer? Skip silently (optionally suggest
+`harness`). Conventions are *recorded, not gated* — never block the task on this.

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.