@dsalazardev/ai-hub-cli 0.0.0-stage → 0.2.0

package/skills/shared/cpp/references/undefined-behavior.md

@@ -0,0 +1,86 @@
+# Undefined behavior — catalog, sanitizers, fixes
+
+UB is not "an error at runtime." The standard says the program has *no defined meaning*, which
+licenses the optimizer to assume the situation never happens and rewrite code on that basis. That
+is why UB produces distant, nonsensical crashes and "works in Debug, breaks in Release." You do not
+debug UB by reasoning about what the CPU *did*; you remove it by construction and prove its absence
+with sanitizers.
+
+Static analysis (clang-tidy, cppcheck) and dynamic sanitizers catch **disjoint** bug classes — run
+both. Sanitizers only see the paths your tests exercise, so coverage matters.
+
+## The catalog
+
+| Class | What it is | Caught by | Fix |
+| --- | --- | --- | --- |
+| Lifetime / dangling | reference or pointer to a destroyed object (returned local, dangling iterator after `push_back`, view outliving its owner) | ASan (heap/stack-use-after-scope) | return by value; own with `unique_ptr`; never store a `string_view`/`span` past its backing's lifetime |
+| Use-after-move | reading an object after `std::move` (valid but unspecified state) | clang-tidy (`bugprone-use-after-move`) — **not** ASan | reassign before reading, or don't read it |
+| Out-of-bounds | index/iterator past the end of a container or array | ASan | `.at()` or a bounds-checked view; range-for / ranges; never trust an external index |
+| Signed integer overflow | `INT_MAX + 1`, etc. (UB; unsigned wraps, signed does not) | UBSan | use a wider type, check before, or `<numeric>`/`ckd_add` (C++26) overflow-checked ops |
+| Strict aliasing | reading an object through an unrelated pointer type | UBSan (partial); compiler `-Wstrict-aliasing` | `std::bit_cast` (C++20) or `memcpy`, never a reinterpret_cast pun |
+| Uninitialized read | reading a variable before assigning it | UBSan (MemorySanitizer for full coverage) | always initialize (`int n{};`); enable `-Wuninitialized` |
+| Data race | two threads access the same memory, one writes, no synchronization | TSan | a mutex/`scoped_lock`, `atomic<T>`, or don't share mutable state |
+| Null / misaligned deref | dereferencing `nullptr` or a misaligned pointer | UBSan | check before deref; references can't be null — prefer them |
+| Invalid downcast / enum | `static_cast` to the wrong dynamic type; out-of-range enum value | UBSan (`vptr`, `enum`) | `dynamic_cast` when polymorphic; validate enum inputs |
+
+## Sanitizer flag combinations & caveats
+
+- **ASan + UBSan together:** `-fsanitize=address,undefined -fno-omit-frame-pointer -g`. This is the
+  everyday build for tests and the local gate. Add `-fsanitize=integer` (Clang) to extend UBSan to
+  unsigned wraparound you care about.
+- **TSan alone:** `-fsanitize=thread -g`. It is **incompatible** with ASan — never combine them. Run
+  it as a separate build/CI job over your concurrent tests.
+- **MemorySanitizer** (Clang) for uninitialized reads needs *all* code (including libc++)
+  instrumented; usually overkill — `-Wuninitialized` + always-initialize covers most cases.
+- Sanitizers slow execution ~2–10x and need `-g` and frame pointers for readable stacks. They are a
+  test/CI tool, not a production build.
+- Tune at runtime via env: `ASAN_OPTIONS=detect_leaks=1:abort_on_error=1`,
+  `UBSAN_OPTIONS=print_stacktrace=1:halt_on_error=1`.
+
+## Worked fixes
+
+```cpp
+// Dangling reference (ASan: stack-use-after-return).
+const std::string& bad() { std::string s = make(); return s; }   // s dies at the brace
+std::string good() { return make(); }                            // by value; RVO elides the copy
+
+// Iterator invalidation (ASan: heap-use-after-free).
+for (auto it = v.begin(); it != v.end(); ++it)
+    if (*it == x) v.push_back(*it);            // Bad: push_back may realloc, it now dangles
+auto n = std::ranges::count(v, x);             // Good: compute first, then mutate
+
+// Signed overflow (UBSan: signed-integer-overflow).
+int total = a + b;                             // Bad if a+b > INT_MAX
+auto total = std::int64_t{a} + b;              // Good: widen before the add
+
+// Strict aliasing (type pun).
+float f = *reinterpret_cast<float*>(&i);       // Bad: UB
+auto f = std::bit_cast<float>(i);              // Good: C++20, defined
+```
+
+## Reading an ASan report
+
+A typical use-after-free report has three stacks — read them bottom-up by *event*:
+
+```
+==12345==ERROR: AddressSanitizer: heap-use-after-free on address 0x602...
+READ of size 4 at 0x602... thread T0
+    #0 0x... in Cache::get(int) src/cache.cpp:42      <- where the bad access happened
+    ...
+0x602... is located 0 bytes inside of 4-byte region [0x602..,0x602..)
+freed by thread T0 here:                              <- who freed it (the delete/dtor)
+    #0 0x... operator delete(void*)
+    #1 0x... in Cache::evict(int) src/cache.cpp:31
+previously allocated by thread T0 here:               <- who allocated it
+    #0 0x... operator new(unsigned long)
+    #1 0x... in Cache::put(int,int) src/cache.cpp:18
+```
+
+Procedure: (1) the top READ/WRITE frame is the *symptom* line; (2) "freed by" is the line that ended
+the object's life too early; (3) "previously allocated" is its birth. The bug is almost always that
+the "freed by" path runs while a pointer/reference/iterator captured between allocation and the
+symptom is still in use. The fix is an ownership fix — usually replacing the raw owning pointer with
+a `unique_ptr`/`shared_ptr` so the lifetime can't be cut short, or extending the owner's scope.
+
+For data races, TSan prints the two conflicting accesses (read/write) with both stacks and the thread
+that created each; the fix is a single mutex/`scoped_lock` or an `atomic<T>` guarding that memory.

package/skills/shared/cpp/scripts/verify.sh

@@ -0,0 +1,165 @@
+#!/usr/bin/env bash
+#
+# verify.sh - local quality gate for a CMake C++ project (superset of CI).
+#
+# Usage:
+#   cd <your-project-root>   # the directory containing CMakeLists.txt
+#   ./verify.sh
+#
+# Runs: clang-format (dry-run), a CMake configure+build with warnings-as-errors and
+# ASan+UBSan, the test target via ctest, and optional clang-tidy + cppcheck.
+# Tools that are not installed are skipped with a yellow warning (not a failure).
+# Real problems (format drift, build failure, sanitizer abort, test failure) exit non-zero.
+# Read-only: never mutates your source. Only writes under build/verify/.
+#
+# Portability: runs on stock macOS bash 3.2 (no mapfile, no associative arrays,
+# no unguarded array expansions under `set -u`).
+
+set -euo pipefail
+
+# Colors only when stdout is a TTY (keeps logs/CI output clean).
+if [ -t 1 ]; then
+  YELLOW=$'\033[33m'; RED=$'\033[31m'; GREEN=$'\033[32m'; RESET=$'\033[0m'
+else
+  YELLOW=''; RED=''; GREEN=''; RESET=''
+fi
+
+failed=0
+BUILD_DIR="build/verify"
+
+have()  { command -v "$1" >/dev/null 2>&1; }
+warn()  { printf '%s[skip]%s %s\n' "$YELLOW" "$RESET" "$*"; }
+fail()  { printf '%s[fail]%s %s\n' "$RED" "$RESET" "$*"; failed=1; }
+ok()    { printf '%s[ ok ]%s %s\n' "$GREEN" "$RESET" "$*"; }
+info()  { printf -- '----- %s\n' "$*"; }
+
+# Must run from a CMake project root.
+if [ ! -f CMakeLists.txt ]; then
+  printf '%serror:%s no CMakeLists.txt in %s - cd into your project root first.\n' \
+    "$RED" "$RESET" "$(pwd)" >&2
+  exit 2
+fi
+
+# Collect tracked C/C++ sources (git if available, else find). Read-only.
+collect_sources() {
+  if have git && git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    git ls-files '*.cpp' '*.cc' '*.cxx' '*.hpp' '*.hh' '*.hxx' '*.h' '*.ixx' 2>/dev/null
+  else
+    find . -path ./"$BUILD_DIR" -prune -o -type f \
+      \( -name '*.cpp' -o -name '*.cc' -o -name '*.cxx' \
+         -o -name '*.hpp' -o -name '*.hh' -o -name '*.hxx' \
+         -o -name '*.h' -o -name '*.ixx' \) -print 2>/dev/null
+  fi
+}
+
+# 1. clang-format - dry-run, never rewrites. Empty source set is a clean pass.
+info "clang-format"
+if have clang-format; then
+  srcs="$(collect_sources)"
+  if [ -z "$srcs" ]; then
+    ok "no C/C++ sources to format"
+  else
+    fmt_failed=0
+    # -Werror + --dry-run makes clang-format exit non-zero on any drift, printing nothing else.
+    printf '%s\n' "$srcs" | while IFS= read -r f; do
+      [ -n "$f" ] || continue
+      clang-format --dry-run -Werror "$f" >/dev/null 2>&1 || printf '%s\n' "$f"
+    done > "${TMPDIR:-/tmp}/cpp_verify_fmt.$$" || true
+    if [ -s "${TMPDIR:-/tmp}/cpp_verify_fmt.$$" ]; then
+      fmt_failed=1
+      fail "files need formatting (run: clang-format -i <file>):"
+      cat "${TMPDIR:-/tmp}/cpp_verify_fmt.$$"
+    fi
+    rm -f "${TMPDIR:-/tmp}/cpp_verify_fmt.$$"
+    [ "$fmt_failed" -eq 0 ] && ok "clang-format clean"
+  fi
+else
+  warn "clang-format not found (https://clang.llvm.org/docs/ClangFormat.html)"
+fi
+
+# 2-4. CMake configure + build under warnings-as-errors + ASan+UBSan, then ctest.
+info "cmake configure (ASan+UBSan, warnings-as-errors)"
+if have cmake; then
+  SAN_FLAGS="-fsanitize=address,undefined -fno-omit-frame-pointer -g -Werror"
+  if cmake -S . -B "$BUILD_DIR" \
+       -DCMAKE_BUILD_TYPE=Debug \
+       -DCMAKE_CXX_FLAGS="$SAN_FLAGS" \
+       -DCMAKE_EXPORT_COMPILE_COMMANDS=ON >/dev/null 2>&1; then
+    ok "configured ($BUILD_DIR)"
+
+    info "cmake build"
+    if cmake --build "$BUILD_DIR" >/dev/null 2>&1; then
+      ok "build clean (warnings-as-errors)"
+
+      info "ctest"
+      if have ctest; then
+        # ctest exits non-zero with "No tests were found" when there are none; treat that as a skip.
+        ctest_out="$(ctest --test-dir "$BUILD_DIR" --output-on-failure 2>&1 || true)"
+        if printf '%s' "$ctest_out" | grep -qi 'no tests were found'; then
+          warn "no tests registered with ctest"
+        elif printf '%s' "$ctest_out" | grep -qiE 'tests failed|failed out of|errors? while'; then
+          fail "ctest reported failures"
+          printf '%s\n' "$ctest_out"
+        else
+          ok "tests pass (ASan+UBSan)"
+        fi
+      else
+        warn "ctest not found (ships with CMake)"
+      fi
+    else
+      fail "build failed (warnings-as-errors / sanitizer compile error)"
+    fi
+  else
+    fail "cmake configure failed"
+  fi
+else
+  warn "cmake not found - cannot build/test (https://cmake.org/download/)"
+fi
+
+# 5. clang-tidy - optional; reads compile_commands.json from the build dir.
+info "clang-tidy"
+if have clang-tidy && [ -f "$BUILD_DIR/compile_commands.json" ]; then
+  srcs="$(collect_sources | grep -E '\.(cpp|cc|cxx)$' || true)"
+  if [ -z "$srcs" ]; then
+    warn "no translation units for clang-tidy"
+  else
+    tidy_failed=0
+    printf '%s\n' "$srcs" | while IFS= read -r f; do
+      [ -n "$f" ] || continue
+      clang-tidy -p "$BUILD_DIR" "$f" >/dev/null 2>&1 || printf '%s\n' "$f"
+    done > "${TMPDIR:-/tmp}/cpp_verify_tidy.$$" || true
+    if [ -s "${TMPDIR:-/tmp}/cpp_verify_tidy.$$" ]; then
+      tidy_failed=1
+      fail "clang-tidy reported issues in:"
+      cat "${TMPDIR:-/tmp}/cpp_verify_tidy.$$"
+    fi
+    rm -f "${TMPDIR:-/tmp}/cpp_verify_tidy.$$"
+    [ "$tidy_failed" -eq 0 ] && ok "clang-tidy clean"
+  fi
+else
+  warn "clang-tidy not found or no compile_commands.json (optional)"
+fi
+
+# 6. cppcheck - optional static analysis.
+info "cppcheck"
+if have cppcheck; then
+  if [ -f "$BUILD_DIR/compile_commands.json" ]; then
+    if cppcheck --enable=warning,performance --error-exitcode=1 \
+         --project="$BUILD_DIR/compile_commands.json" >/dev/null 2>&1; then
+      ok "cppcheck clean"
+    else
+      fail "cppcheck reported issues"
+    fi
+  else
+    warn "cppcheck: no compile_commands.json to analyze"
+  fi
+else
+  warn "cppcheck not found (optional)"
+fi
+
+echo
+if [ "$failed" -ne 0 ]; then
+  printf '%sFAIL:%s one or more checks failed.\n' "$RED" "$RESET"
+  exit 1
+fi
+printf '%sPASS:%s all checks passed.\n' "$GREEN" "$RESET"

package/skills/shared/csharp-dotnet/SKILL.md

@@ -0,0 +1,272 @@
+---
+name: csharp-dotnet
+description: "Use when writing, reviewing, testing, or shipping C# / .NET code — ASP.NET Core APIs (minimal APIs vs controllers), EF Core data access, async correctness, solution layout in .cs/.csproj/.sln. NOT a Java/Spring backend (that is spring-boot), NOT a Node/TypeScript backend (that is nestjs), NOT framework-neutral REST naming (that is api-design)."
+tags: [csharp, dotnet, aspnetcore, efcore, async]
+recommends: [postgresdb, secure-coding, deployment]
+origin: ai-hub
+---
+
+# Modern C# and .NET services
+
+You write and review C#, ASP.NET Core APIs, and EF Core data access. You own the
+.NET idioms, the HTTP-contract patterns *as expressed in .NET*, async correctness,
+and the .NET-specific quality/security gates. You delegate everything language-
+agnostic to the right sibling.
+
+**Target: .NET 10 (LTS, released 2025-11-11, supported 3 years) with C# 14, EF Core
+10, ASP.NET Core 10.** .NET 9 / C# 13 is the immediate STS predecessor — still in
+support but shorter-lived. Features gate on the target framework moniker (TFM): a
+`net10.0` project gets C# 14 by default; a `net9.0` project caps at C# 13. When you
+use a C# 14 feature (`field`, extension members, null-conditional assignment), say
+which TFM it requires.
+
+## When NOT to use — delegate
+
+| Situation | Route to |
+|---|---|
+| Java / Spring Boot backend | `spring-boot` |
+| Node / NestJS TypeScript backend | `nestjs` |
+| Language-agnostic threat modeling, OWASP authz/abuse review | `../secure-coding/SKILL.md` |
+| Raw Postgres schema/index/query tuning | `../postgresdb/SKILL.md` |
+| Framework-neutral REST resource taxonomy | `api-design` |
+| Dockerfile / CI pipeline / deploy target | `../deployment/SKILL.md` |
+| Recording per-project conventions in the workspace wiki | `../harness/SKILL.md` |
+
+The .NET *expression* of an API contract and async correctness live HERE. Resource
+naming theory lives in `api-design`; the JVM and Node counterparts are `spring-boot`
+and `nestjs`.
+
+## Project & solution layout + dotnet CLI
+
+```bash
+dotnet new sln -n Shop                         # solution
+dotnet new webapi -n Shop.Api                  # minimal API (default in .NET 10)
+dotnet new webapi -n Shop.Api --use-controllers # opt into MVC controllers instead
+dotnet new xunit -n Shop.Api.Tests             # test project
+dotnet sln add Shop.Api Shop.Api.Tests         # wire into the solution
+dotnet add Shop.Api package Npgsql.EntityFrameworkCore.PostgreSQL
+dotnet ef migrations add Initial -p Shop.Api   # create a migration
+dotnet ef database update -p Shop.Api          # apply migrations
+dotnet build -warnaserror                      # compile; analyzers + NRT as errors
+dotnet test                                    # run tests
+dotnet format                                  # apply style; --verify-no-changes in CI
+dotnet publish -c Release                       # produce deployable output
+```
+
+Recommended shape:
+
+```text
+Shop.sln
+Directory.Packages.props    # central package management: <PackageVersion> here, no versions in csproj
+Directory.Build.props       # shared <Nullable>enable</Nullable>, <TreatWarningsAsErrors>, LangVersion
+src/Shop.Api/               # endpoints grouped by feature module (Products/, Orders/)
+src/Shop.Domain/            # entities, value objects (no EF/ASP.NET dependency)
+tests/Shop.Api.Tests/
+```
+
+Central package management: turn it on with `<ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>`
+and list versions once in `Directory.Packages.props`. Why: one source of truth, no
+version drift across projects.
+
+NRT on for every project — `<Nullable>enable</Nullable>` in `Directory.Build.props`.
+Why: the compiler turns whole classes of `NullReferenceException` into build-time
+warnings. Never disable it to silence a warning — fix the nullability.
+
+## Modern C# idioms (C# 14 / .NET 10)
+
+DTO as a record, not a class:
+
+```csharp
+// Bad: mutable class, no value equality, hand-written boilerplate
+public class ProductDto { public int Id { get; set; } public string Name { get; set; } }
+
+// Good: immutable record DTO
+public record ProductDto(int Id, string Name, decimal Price);
+```
+
+Why: value equality, `with` expressions, no boilerplate — and never reuse an EF entity
+as the wire DTO (see anti-patterns).
+
+Pattern matching over if-chains:
+
+```csharp
+// Bad
+if (shape is Circle) { var c = (Circle)shape; return Math.PI * c.R * c.R; }
+
+// Good
+return shape switch
+{
+    Circle c      => Math.PI * c.R * c.R,
+    Rectangle r   => r.W * r.H,
+    _             => throw new ArgumentOutOfRangeException(nameof(shape)),
+};
+```
+
+`field` keyword — field-backed property without a hand-written backing field
+(**requires C# 14 / net10.0**):
+
+```csharp
+// Bad: explicit backing field just to trim a string
+private string _name = "";
+public string Name { get => _name; set => _name = value.Trim(); }
+
+// Good (C# 14)
+public string Name { get; set => field = value.Trim(); }
+```
+
+Primary constructors, `required`/`init`, collection expressions:
+
+```csharp
+public class OrderService(IOrderRepository repo, ILogger<OrderService> log)  // primary ctor: DI in one line
+{
+    public required string Region { get; init; }                            // must be set at construction, then immutable
+    private static readonly int[] DefaultTiers = [1, 2, 3];                  // collection expression
+}
+```
+
+Prefer NRT annotations over defensive null checks: declare `string? note` when null is
+valid and let the compiler force callers to handle it, instead of `if (x == null)`
+guards scattered everywhere.
+
+Dispose deterministically: `using` / `await using` (or `using` declarations) for
+anything `IDisposable`/`IAsyncDisposable`. Why: leaked connections and handles.
+
+## async/await correctness
+
+This is the highest-leverage area to get right. Core rules in body; the full catalog
+(ConfigureAwait, ValueTask, IAsyncEnumerable, Channels, parallelism, deadlock cases)
+is in **references/async.md** — read it before any non-trivial async review.
+
+- **No `async void`** except top-level event handlers. Why: exceptions escape onto the
+  thread pool and crash the process; the caller cannot `await` or catch it. Use `async Task`.
+- **Never `.Result` / `.Wait()` / `GetAwaiter().GetResult()` on the request path.** This
+  is the classic deadlock and the answer to "my endpoint hangs under load":
+
+```csharp
+// Bad: blocks the thread on an async call -> thread-pool starvation / deadlock under load
+public IActionResult Get() => Ok(_svc.LoadAsync().Result);
+
+// Good: await all the way up
+public async Task<IActionResult> Get(CancellationToken ct) => Ok(await _svc.LoadAsync(ct));
+```
+
+- **Flow `CancellationToken`** from the endpoint down into every async call —
+  `SaveChangesAsync`, queries, outbound HTTP. Why: a dropped token means the request
+  keeps running after the client gives up.
+- **`ValueTask` only for hot paths** that usually complete synchronously; default to
+  `Task`. Never `await` a `ValueTask` twice.
+- **`IAsyncEnumerable<T>` for streaming** results instead of materializing a huge list.
+
+## ASP.NET Core APIs
+
+Decision: **minimal API** for new services; **controllers** only when you need MVC
+machinery (model binding conventions, action filters at scale, views). Both can coexist.
+Why minimal by default: less ceremony, first-class in .NET 10.
+
+Production minimal API shape — route group + DataAnnotations validation (built in for
+minimal API parameters in .NET 10) + ProblemDetails + OpenAPI 3.1:
+
+```csharp
+var builder = WebApplication.CreateBuilder(args);
+builder.Services.AddOpenApi();                 // OpenAPI 3.1, JSON Schema 2020-12
+builder.Services.AddProblemDetails();          // RFC 9457 error bodies
+builder.Services.AddDbContext<ShopDb>(o => o.UseNpgsql(builder.Configuration.GetConnectionString("Shop")));
+
+var app = builder.Build();
+app.MapOpenApi();                              // serves the OpenAPI document
+app.UseExceptionHandler();                     // emits ProblemDetails on unhandled errors
+
+var products = app.MapGroup("/products").WithTags("Products");
+products.MapGet("/{id:int}", async (int id, ShopDb db, CancellationToken ct) =>
+    await db.Products.AsNoTracking()
+        .Where(p => p.Id == id)
+        .Select(p => new ProductDto(p.Id, p.Name, p.Price))   // project to DTO, no entity leak
+        .FirstOrDefaultAsync(ct) is { } dto
+        ? Results.Ok(dto)
+        : Results.NotFound());
+products.MapPost("/", async (CreateProduct req, ShopDb db, CancellationToken ct) =>
+{   // DataAnnotations on CreateProduct are validated automatically in .NET 10
+    var entity = new Product { Name = req.Name, Price = req.Price };
+    db.Products.Add(entity);
+    await db.SaveChangesAsync(ct);
+    return Results.Created($"/products/{entity.Id}", new ProductDto(entity.Id, entity.Name, entity.Price));
+});
+app.Run();
+```
+
+DI lifetimes: `Singleton` (one for the app), `Scoped` (one per request — `DbContext`
+lives here; it is not thread-safe, so sharing one across requests corrupts change
+tracking), `Transient` (new each resolve). Never inject a `Scoped` service into a
+`Singleton` (captive dependency — see anti-patterns). Middleware ordering, endpoint
+filters, the options pattern, and auth defaults are in **references/aspnetcore.md**.
+
+## EF Core 10
+
+```csharp
+// Bad: tracking + N+1 — loads orders, then one query per order's customer
+var orders = await db.Orders.ToListAsync(ct);
+foreach (var o in orders) { var name = o.Customer.Name; /* lazy/round-trip per row */ }
+
+// Good: no-tracking read + single query via projection
+var rows = await db.Orders.AsNoTracking()
+    .Select(o => new OrderRow(o.Id, o.Customer.Name))   // EF translates to one JOIN
+    .ToListAsync(ct);
+```
+
+- `AsNoTracking()` on every read-only query — skips change-tracking overhead.
+- Kill N+1 with projection (`Select`) or `Include`/`ThenInclude`; use `AsSplitQuery()`
+  when an `Include` cartesian explosion hurts.
+- Migrations: `dotnet ef migrations add <Name>` then review the generated `Up`/`Down`
+  before `database update`. Never hand-edit applied migrations.
+- EF Core 10 highlights: native `json` column type, `vector` type + `VECTOR_DISTANCE()`
+  for embeddings/RAG, `LeftJoin`/`RightJoin` LINQ operators, and named query filters
+  (multiple filters per entity, selectively disabled).
+
+Raw SQL only via parameterized `FromSql`/`ExecuteSql` interpolated strings (EF
+parameterizes the holes). Query patterns, migration workflow, the EF Core 10 features,
+and raw-SQL safety in full are in **references/efcore.md**. Schema/index tuning is
+`../postgresdb/SKILL.md`.
+
+## .NET security controls
+
+Keep only the .NET-specific controls here; threat modeling and OWASP review go to
+`../secure-coding/SKILL.md`.
+
+- **Parameterized data access** — EF LINQ / parameterized `FromSql` / ADO.NET
+  `SqlParameter`. Never concatenate user input into SQL. Why: SQL injection.
+- **Secrets** — `dotnet user-secrets` in dev, Key Vault / environment in prod. Never in
+  `appsettings.json` or source.
+- **Antiforgery** for cookie-auth browser POSTs; **Data Protection** for cookies/tokens
+  (configure a persisted key ring across instances).
+- **Auth defaults** — authenticate then authorize via middleware; prefer policy-based
+  authorization; ASP.NET Core 10 is secure-by-default but still verify HTTPS redirection
+  and HSTS in production.
+
+## Testing
+
+- **xUnit** is the default. Unit-test domain logic with no framework dependency.
+- **Integration tests** via `WebApplicationFactory<Program>` — boots the real pipeline
+  in-memory and lets you `HttpClient` your endpoints.
+- **Testcontainers** to run a real Postgres in a container for EF integration tests
+  instead of the in-memory provider (which lies about relational behavior).
+- Gate everything with `scripts/verify.sh` (format + build-warnaserror + test + vuln scan).
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+|---|---|---|
+| `async void` (non-event-handler) | Exceptions crash the process; uncatchable by caller | `async Task` |
+| `.Result` / `.Wait()` on request path | Deadlock / thread-pool starvation under load | `await` all the way |
+| Scoped service injected into a Singleton | Captive dependency: stale/`DbContext` reused across requests | Inject `IServiceScopeFactory`, or make the consumer scoped |
+| Reusing an EF entity as the wire DTO | Over-posting, serialization cycles, leaked columns | Separate `record` DTO + mapping |
+| Tracking queries on read-only reads | Wasted memory/CPU on change tracking | `AsNoTracking()` |
+| Lazy navigation in a loop | N+1 round-trips | Projection or `Include` |
+| Missing `CancellationToken` | Work continues after client disconnects | Flow the token to all I/O |
+| `catch (Exception) { }` swallow | Hides failures; corrupt state continues | Handle specifically or let `UseExceptionHandler` map it |
+| `<Nullable>disable</Nullable>` to mute a warning | Re-opens the NRE class of bugs | Keep NRT on; fix the nullability |
+
+## Project grounding
+
+Record per-project conventions (target TFM, package manager, lint rules, deploy
+target) in the workspace wiki via `../harness/SKILL.md`, not inline assumptions. Before
+calling a C# change done, run `scripts/verify.sh` from the solution/project root.

package/skills/shared/csharp-dotnet/evals/README.md

@@ -0,0 +1,3 @@
+# Evals — csharp-dotnet
+
+These cases are read by a human or an LLM judge, not by an automated test runner. To run them, install the skill and feed each prompt to the agent: `should_trigger` cases should make the agent reach for `csharp-dotnet` (check the routing against each `why`), and `should_not_trigger` cases should route to the named sibling instead (`route_to`). For the `capability` case, give the agent the scenario, then score the generated code against every line in `must_include` — each bullet is pass/fail, and a strong result hits all of them (net10.0 TFM, NRT on, record DTO separate from the entity, async with CancellationToken, validation + ProblemDetails, OpenAPI wired, AsNoTracking with no N+1). It is a rubric, not an assertion library, so judge intent and substance over exact wording.

package/skills/shared/csharp-dotnet/evals/cases.yaml

@@ -0,0 +1,48 @@
+skill: csharp-dotnet
+
+should_trigger:
+  - prompt: "Build an ASP.NET Core minimal API for /products with validation and OpenAPI."
+    why: Core authoring task — minimal API + DataAnnotations validation + OpenAPI are this skill's bread and butter.
+  - prompt: "Is this idiomatic C#? Should this DTO be a record with init-only props?"
+    why: Idiom review with no tool/framework named — record-vs-class and init-only are .NET idioms this skill owns.
+  - prompt: "My API endpoint hangs and deadlocks under load — it calls .Result on an async method."
+    why: Non-obvious symptom phrasing; the user does not say "sync-over-async" but that is exactly the deadlock this skill diagnoses.
+  - prompt: "This EF Core query loads orders then hits the database once per order in a loop."
+    why: N+1 described by symptom, not by name — EF Core query shape is in scope here.
+  - prompt: "Add xUnit integration tests with WebApplicationFactory for my controllers."
+    why: .NET testing contract — WebApplicationFactory is the ASP.NET Core integration-test primitive.
+  - prompt: "revisa este código C# antes de hacer deploy"
+    why: Spanish trigger for a C# code review before shipping — language-family review is this skill.
+  - prompt: "How do I structure a .NET solution with src/ and tests/ and central package management?"
+    why: dotnet CLI + solution layout + Directory.Packages.props are covered directly in the body.
+
+should_not_trigger:
+  - prompt: "Build the same REST API but in Spring Boot with JPA."
+    route_to: spring-boot
+    why: JVM/Java backend — explicitly delegated; this skill is the .NET counterpart only.
+  - prompt: "Threat-model my multi-tenant authorization boundaries against OWASP."
+    route_to: secure-coding
+    why: Framework-neutral threat modeling; this skill keeps only the concrete .NET controls.
+  - prompt: "Tune this slow Postgres query and design the right indexes."
+    route_to: postgresdb
+    why: Raw DB schema/index/query tuning — not EF mapping or LINQ translation.
+  - prompt: "Write a Dockerfile and GitHub Actions workflow to deploy my .NET app to Hetzner."
+    route_to: deployment
+    why: Containerization and CI/deploy targets live in deployment; this skill stops at dotnet publish.
+  - prompt: "Build this backend in NestJS with TypeScript decorators."
+    route_to: nestjs
+    why: Node/TypeScript backend — the wrong language family entirely.
+
+capability:
+  - scenario: >
+      Write a production-shaped ASP.NET Core 10 minimal API for a TODO resource backed by
+      EF Core on Postgres: validation, ProblemDetails, OpenAPI, async with CancellationToken,
+      and a DTO that is separate from the EF entity.
+    must_include:
+      - "Minimal API using a route group (MapGroup) — or controllers with a stated justification."
+      - "A record DTO distinct from the EF entity, with explicit mapping between them."
+      - "async handlers that flow CancellationToken into SaveChangesAsync and queries."
+      - "DataAnnotations validation (or an endpoint filter) plus a ProblemDetails error shape."
+      - "OpenAPI wired via AddOpenApi() and MapOpenApi()."
+      - "AsNoTracking() on the read path and no N+1 (projection or Include)."
+      - "Targets net10.0 with nullable reference types enabled."