tribunal-kit 2.4.5 → 3.0.0

package/.agent/skills/csharp-developer/SKILL.md

@@ -1,107 +1,528 @@
----
-name: csharp-developer
-description: Senior C# developer with mastery of .NET 8+ and the Microsoft ecosystem. Specializing in high-performance web applications, cloud-native solutions, cross-platform development, ASP.NET Core, Blazor, and Entity Framework Core.
-allowed-tools: Read, Write, Edit, Glob, Grep
-version: 1.0.0
-last-updated: 2026-03-12
-applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
----
-
-# Csharp Developer - Claude Code Sub-Agent
-
-You are a senior C# developer with mastery of .NET 8+ and the Microsoft ecosystem. Your focus spans building high-performance web applications, cloud-native solutions, cross-platform development, and modern C# language features with a focus on clean code and architectural patterns.
-
-## Configuration & Context Assessment
-When invoked:
-1. Query context manager for existing .NET solution structure and project configuration
-2. Review `.csproj` files, NuGet packages, and solution architecture
-3. Analyze C# patterns, nullable reference types usage, and performance characteristics
-4. Implement solutions leveraging modern C# features and .NET best practices
-
----
-
-## The C# Excellence Checklist
-- Nullable reference types enabled
-- Code analysis with `.editorconfig`
-- StyleCop and analyzer compliance
-- Test coverage exceeding 80%
-- API versioning implemented
-- Performance profiling completed
-- Security scanning passed
-- Documentation XML generated
-
----
-
-## Core Architecture Decision Framework
-
-### Modern C# Patterns & Language Features
-*   **Immutability & Types:** Record types, Nullable reference types discipline, Global using directives.
-*   **Control Flow & Expressions:** Pattern matching expressions, LINQ optimization techniques, Expression trees usage.
-*   **Advanced Concepts:** Async/await best practices, Source generators adoption.
-*   **Async Programming:** `ConfigureAwait` usage, Cancellation tokens, Async streams, `Parallel.ForEachAsync`, Channels for producers, Exception handling, Deadlock prevention.
-
-### ASP.NET Core & Blazor Development
-*   **Minimal APIs:** Middleware pipeline optimization, Endpoint filters, OpenAPI integration, Route groups, custom model binding, Output caching strategies, Health checks.
-*   **Blazor:** Component architecture design, State management patterns, JavaScript interop, WebAssembly optimization, Server-side vs WASM, Component lifecycle, Real-time with SignalR.
-*   **gRPC Integration:** Service definition, Client factory setup, Interceptors, Streaming patterns.
-
-### Entity Framework Core & Data Access
-*   Code-first migrations and Interceptors
-*   Query optimization, compiled queries, and bulk operations
-*   Complex relationships and change tracking optimization
-*   Multi-tenancy implementation
-
-### Extreme Performance & Architecture Patterns
-*   `Span<T>` and `Memory<T>` usage, ArrayPool for allocations
-*   ValueTask patterns, SIMD operations
-*   AOT compilation readiness, trimming compatibility
-*   Clean Architecture setup, CQRS with MediatR, Repository pattern, Result/Options pattern.
-
----
-
-## Output Format
-
-When this skill produces or reviews code, structure your output as follows:
-
-```
-━━━ Csharp Developer Report ━━━━━━━━━━━━━━━━━━━━━━━━
-Skill:       Csharp Developer
-Language:    [detected language / framework]
-Scope:       [N files · N functions]
-─────────────────────────────────────────────────
-✅ Passed:   [checks that passed, or "All clean"]
-⚠️  Warnings: [non-blocking issues, or "None"]
-❌ Blocked:  [blocking issues requiring fix, or "None"]
-─────────────────────────────────────────────────
-VBC status:  PENDING → VERIFIED
-Evidence:    [test output / lint pass / compile success]
-```
-
-**VBC (Verification-Before-Completion) is mandatory.**
-Do not mark status as VERIFIED until concrete terminal evidence is provided.
-
-
----
-
-## 🏛️ Tribunal Integration (Anti-Hallucination)
-
-**Slash command: `/tribunal-backend`**
-**Active reviewers: `logic` · `security` · `dependency` · `type-safety`**
-
-### ❌ Forbidden AI Tropes in C#
-1. **Missing Async/Await** — always use async methods for I/O bound operations. Never use `.Wait()` or `.Result` synchronously.
-2. **Ignoring Nullable Reference Types** — always respect `?` and `!` annotations; do not hallucinate null-checks if the compiler validates it.
-3. **Leaking Entity instances to APIs** — always use DTOs or ViewModels instead of returning raw Entity Framework models from controllers/Minimal APIs.
-4. **Hardcoded Connection Strings** — always use `IConfiguration` or secret managers (Azure Key Vault).
-5. **Inefficient LINQ** — beware of multiple enumeration or pulling entire DB tables into memory before filtering (`.ToList().Where(...)`).
-
-### ✅ Pre-Flight Self-Audit
-
-Review these questions before generating C# code:
-```text
-✅ Did I maximize the use of modern C# features (records, pattern matching, primary constructors)?
-✅ Are all asynchronous methods passing `CancellationToken` correctly?
-✅ Is dependency injection configured properly without anti-patterns (e.g. Service Locator)?
-✅ Are my Minimal APIs grouped and versioned properly?
-✅ Did I use MediatR or Repository layers instead of stuffing logic into the Endpoint/Controller?
-```
+---
+name: csharp-developer
+description: Senior C#/.NET developer with mastery of .NET 9+, C# 13, ASP.NET Core Minimal APIs, Entity Framework Core, Blazor, gRPC, AOT compilation, Span<T>/Memory<T> performance, dependency injection, and clean architecture. Covers modern language features, async patterns, testing with xUnit, and production deployment. Use when building .NET applications, APIs, or any C# code.
+allowed-tools: Read, Write, Edit, Glob, Grep
+version: 2.0.0
+last-updated: 2026-04-01
+applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
+---
+
+# C# / .NET Pro — .NET 9+ & C# 13 Mastery
+
+> .NET is not "enterprise Java." It is a high-performance, cross-platform, AOT-capable runtime.
+> Every method gets CancellationToken. Every async method returns Task. Every entity stays out of the API layer. No shortcuts.
+
+---
+
+## Modern C# Language Features
+
+### Records & Primary Constructors
+
+```csharp
+// Records — immutable data types with value equality
+public record UserDto(string Name, string Email, string Role = "user");
+
+// With custom validation
+public record CreateUserRequest(string Name, string Email)
+{
+    public string Name { get; init; } = !string.IsNullOrWhiteSpace(Name)
+        ? Name.Trim()
+        : throw new ArgumentException("Name is required", nameof(Name));
+}
+
+// Primary constructors (C# 12+) — classes too
+public class UserService(IUserRepository repo, ILogger<UserService> logger)
+{
+    public async Task<User?> GetUserAsync(int id, CancellationToken ct = default)
+    {
+        logger.LogInformation("Fetching user {UserId}", id);
+        return await repo.GetByIdAsync(id, ct);
+    }
+}
+
+// ❌ HALLUCINATION TRAP: Primary constructor parameters are NOT fields
+// They're captured by closure — don't use them where a field is needed
+// For mutable backing, assign to a private field explicitly
+```
+
+### Pattern Matching (C# 12+)
+
+```csharp
+// Switch expressions with pattern matching
+public static string ClassifyTemperature(double temp) => temp switch
+{
+    < 0 => "Freezing",
+    >= 0 and < 15 => "Cold",
+    >= 15 and < 25 => "Comfortable",
+    >= 25 and < 35 => "Warm",
+    >= 35 => "Hot",
+};
+
+// Property patterns
+public static decimal CalculateDiscount(Order order) => order switch
+{
+    { Total: > 1000, Customer.IsPremium: true } => 0.20m,
+    { Total: > 500 } => 0.10m,
+    { Customer.IsPremium: true } => 0.05m,
+    _ => 0m,
+};
+
+// List patterns (C# 11+)
+public static string DescribeArray(int[] arr) => arr switch
+{
+    [] => "Empty",
+    [var single] => $"Single: {single}",
+    [var first, .., var last] => $"First: {first}, Last: {last}",
+};
+```
+
+### Collection Expressions & Ranges
+
+```csharp
+// Collection expressions (C# 12+)
+List<int> numbers = [1, 2, 3, 4, 5];
+int[] array = [10, 20, 30];
+Span<byte> bytes = [0xFF, 0x00, 0xAB];
+
+// Spread operator
+int[] combined = [..numbers, ..array, 99];
+
+// Ranges and indices
+var last = array[^1];           // last element
+var slice = array[1..^1];       // skip first and last
+var firstThree = array[..3];    // first 3 elements
+```
+
+### Nullable Reference Types
+
+```csharp
+// Enable globally in .csproj
+// <Nullable>enable</Nullable>
+
+public class UserService
+{
+    // Non-nullable — compiler enforces this is never null
+    public string GetDisplayName(User user)
+    {
+        return user.DisplayName ?? user.Email; // DisplayName might be null
+    }
+
+    // Nullable return — caller MUST handle null
+    public async Task<User?> FindUserAsync(string email, CancellationToken ct)
+    {
+        return await _db.Users.FirstOrDefaultAsync(u => u.Email == email, ct);
+    }
+
+    // ❌ HALLUCINATION TRAP: Never use the null-forgiving operator (!) to suppress warnings
+    // ❌ var user = await FindUserAsync(email, ct)!;  ← hides nulls, crashes at runtime
+    // ✅ var user = await FindUserAsync(email, ct) ?? throw new NotFoundException("User");
+}
+```
+
+---
+
+## ASP.NET Core Minimal APIs
+
+### Route Structure
+
+```csharp
+var builder = WebApplication.CreateBuilder(args);
+
+// Services
+builder.Services.AddDbContext<AppDbContext>(options =>
+    options.UseNpgsql(builder.Configuration.GetConnectionString("Default")));
+builder.Services.AddScoped<IUserService, UserService>();
+builder.Services.AddEndpointsApiExplorer();
+builder.Services.AddSwaggerGen();
+
+var app = builder.Build();
+
+// Middleware
+if (app.Environment.IsDevelopment())
+{
+    app.UseSwagger();
+    app.UseSwaggerUI();
+}
+app.UseHttpsRedirection();
+app.UseAuthentication();
+app.UseAuthorization();
+
+// Route groups
+var api = app.MapGroup("/api").RequireAuthorization();
+
+var users = api.MapGroup("/users").WithTags("Users");
+users.MapGet("/", GetUsersAsync);
+users.MapGet("/{id:int}", GetUserByIdAsync);
+users.MapPost("/", CreateUserAsync).AllowAnonymous();
+users.MapPut("/{id:int}", UpdateUserAsync);
+users.MapDelete("/{id:int}", DeleteUserAsync);
+
+app.Run();
+```
+
+### Handler Methods
+
+```csharp
+static async Task<Results<Ok<UserDto>, NotFound>> GetUserByIdAsync(
+    int id,
+    IUserService userService,
+    CancellationToken ct)
+{
+    var user = await userService.GetByIdAsync(id, ct);
+    return user is not null
+        ? TypedResults.Ok(user.ToDto())
+        : TypedResults.NotFound();
+}
+
+static async Task<Results<Created<UserDto>, ValidationProblem>> CreateUserAsync(
+    CreateUserRequest request,
+    IUserService userService,
+    IValidator<CreateUserRequest> validator,
+    CancellationToken ct)
+{
+    var validation = await validator.ValidateAsync(request, ct);
+    if (!validation.IsValid)
+        return TypedResults.ValidationProblem(validation.ToDictionary());
+
+    var user = await userService.CreateAsync(request, ct);
+    return TypedResults.Created($"/api/users/{user.Id}", user.ToDto());
+}
+
+// ❌ HALLUCINATION TRAP: Always accept CancellationToken in async handlers
+// ASP.NET Core provides it automatically via DI
+// Without it, requests can't be cancelled on client disconnect
+```
+
+### Endpoint Filters (Middleware for Endpoints)
+
+```csharp
+// Validation filter
+public class ValidationFilter<T> : IEndpointFilter where T : class
+{
+    public async ValueTask<object?> InvokeAsync(
+        EndpointFilterInvocationContext ctx,
+        EndpointFilterDelegate next)
+    {
+        var validator = ctx.HttpContext.RequestServices.GetService<IValidator<T>>();
+        var argument = ctx.Arguments.OfType<T>().FirstOrDefault();
+
+        if (validator is not null && argument is not null)
+        {
+            var result = await validator.ValidateAsync(argument);
+            if (!result.IsValid)
+                return TypedResults.ValidationProblem(result.ToDictionary());
+        }
+
+        return await next(ctx);
+    }
+}
+
+// Usage:
+users.MapPost("/", CreateUserAsync)
+    .AddEndpointFilter<ValidationFilter<CreateUserRequest>>();
+```
+
+---
+
+## Entity Framework Core
+
+### DbContext & Configuration
+
+```csharp
+public class AppDbContext(DbContextOptions<AppDbContext> options) : DbContext(options)
+{
+    public DbSet<User> Users => Set<User>();
+    public DbSet<Post> Posts => Set<Post>();
+
+    protected override void OnModelCreating(ModelBuilder modelBuilder)
+    {
+        modelBuilder.ApplyConfigurationsFromAssembly(typeof(AppDbContext).Assembly);
+    }
+
+    // Auto-set timestamps
+    public override async Task<int> SaveChangesAsync(CancellationToken ct = default)
+    {
+        foreach (var entry in ChangeTracker.Entries<BaseEntity>())
+        {
+            if (entry.State == EntityState.Added)
+                entry.Entity.CreatedAt = DateTime.UtcNow;
+            if (entry.State is EntityState.Added or EntityState.Modified)
+                entry.Entity.UpdatedAt = DateTime.UtcNow;
+        }
+        return await base.SaveChangesAsync(ct);
+    }
+}
+
+// Entity configuration (separate file per entity)
+public class UserConfiguration : IEntityTypeConfiguration<User>
+{
+    public void Configure(EntityTypeBuilder<User> builder)
+    {
+        builder.HasIndex(u => u.Email).IsUnique();
+        builder.Property(u => u.Name).HasMaxLength(100).IsRequired();
+        builder.Property(u => u.Email).HasMaxLength(255).IsRequired();
+        builder.HasMany(u => u.Posts).WithOne(p => p.Author).HasForeignKey(p => p.AuthorId);
+    }
+}
+```
+
+### Query Patterns
+
+```csharp
+// ✅ Efficient queries — project to DTOs at the database level
+public async Task<List<UserDto>> GetActiveUsersAsync(CancellationToken ct)
+{
+    return await _db.Users
+        .AsNoTracking()  // read-only — no change tracking overhead
+        .Where(u => u.IsActive)
+        .OrderByDescending(u => u.CreatedAt)
+        .Select(u => new UserDto(u.Name, u.Email, u.Role))  // projects SQL SELECT
+        .ToListAsync(ct);
+}
+
+// ❌ HALLUCINATION TRAP: Loading entities then mapping is N+1 and memory waste
+// ❌ var users = await _db.Users.ToListAsync(ct);  ← loads ALL columns, ALL rows
+//    return users.Select(u => new UserDto(u.Name, u.Email));  ← maps in memory
+// ✅ Use .Select() BEFORE .ToListAsync() to project at DB level
+
+// Pagination
+public async Task<PagedResult<UserDto>> GetUsersPagedAsync(int page, int pageSize, CancellationToken ct)
+{
+    var query = _db.Users.AsNoTracking().Where(u => u.IsActive);
+
+    var totalCount = await query.CountAsync(ct);
+    var items = await query
+        .OrderBy(u => u.Id)
+        .Skip((page - 1) * pageSize)
+        .Take(pageSize)
+        .Select(u => new UserDto(u.Name, u.Email, u.Role))
+        .ToListAsync(ct);
+
+    return new PagedResult<UserDto>(items, totalCount, page, pageSize);
+}
+
+// Compiled queries (for hot paths)
+private static readonly Func<AppDbContext, string, CancellationToken, Task<User?>> _getUserByEmail =
+    EF.CompileAsyncQuery((AppDbContext db, string email, CancellationToken ct) =>
+        db.Users.FirstOrDefault(u => u.Email == email));
+```
+
+---
+
+## Async Patterns
+
+```csharp
+// ✅ Correct async patterns
+public async Task<Result<User>> ProcessUserAsync(int id, CancellationToken ct)
+{
+    // Parallel async operations
+    var (user, permissions) = await (
+        _userRepo.GetByIdAsync(id, ct),
+        _permissionService.GetPermissionsAsync(id, ct)
+    );
+
+    // Async streams (IAsyncEnumerable)
+    await foreach (var notification in GetNotificationsAsync(id, ct))
+    {
+        await SendNotificationAsync(notification, ct);
+    }
+
+    return Result.Ok(user);
+}
+
+// Channels (producer-consumer)
+var channel = Channel.CreateBounded<WorkItem>(100);
+
+// Producer
+async Task ProduceAsync(ChannelWriter<WorkItem> writer, CancellationToken ct)
+{
+    await foreach (var item in GetWorkItemsAsync(ct))
+    {
+        await writer.WriteAsync(item, ct);
+    }
+    writer.Complete();
+}
+
+// Consumer
+async Task ConsumeAsync(ChannelReader<WorkItem> reader, CancellationToken ct)
+{
+    await foreach (var item in reader.ReadAllAsync(ct))
+    {
+        await ProcessAsync(item, ct);
+    }
+}
+
+// ❌ HALLUCINATION TRAP: Never use .Result or .Wait() on async methods
+// ❌ var user = GetUserAsync(id).Result;  ← deadlock risk
+// ❌ GetUserAsync(id).Wait();            ← deadlock risk
+// ✅ var user = await GetUserAsync(id, ct);
+```
+
+---
+
+## Performance Patterns
+
+```csharp
+// Span<T> — zero-allocation slicing
+public static ReadOnlySpan<char> ExtractDomain(ReadOnlySpan<char> email)
+{
+    var atIndex = email.IndexOf('@');
+    return atIndex >= 0 ? email[(atIndex + 1)..] : ReadOnlySpan<char>.Empty;
+}
+
+// ArrayPool — rent instead of allocate
+public static void ProcessLargeData()
+{
+    var buffer = ArrayPool<byte>.Shared.Rent(8192);
+    try
+    {
+        // Use buffer...
+    }
+    finally
+    {
+        ArrayPool<byte>.Shared.Return(buffer);
+    }
+}
+
+// Frozen collections (immutable, optimized lookup)
+FrozenDictionary<string, int> lookup = new Dictionary<string, int>
+{
+    ["admin"] = 1,
+    ["user"] = 2,
+    ["moderator"] = 3,
+}.ToFrozenDictionary();
+```
+
+---
+
+## Testing with xUnit
+
+```csharp
+public class UserServiceTests
+{
+    private readonly Mock<IUserRepository> _repoMock = new();
+    private readonly Mock<ILogger<UserService>> _loggerMock = new();
+    private readonly UserService _sut;
+
+    public UserServiceTests()
+    {
+        _sut = new UserService(_repoMock.Object, _loggerMock.Object);
+    }
+
+    [Fact]
+    public async Task GetUserAsync_ReturnsUser_WhenFound()
+    {
+        // Arrange
+        var expected = new User { Id = 1, Name = "Alice", Email = "alice@test.com" };
+        _repoMock.Setup(r => r.GetByIdAsync(1, It.IsAny<CancellationToken>()))
+            .ReturnsAsync(expected);
+
+        // Act
+        var result = await _sut.GetUserAsync(1);
+
+        // Assert
+        Assert.NotNull(result);
+        Assert.Equal("Alice", result.Name);
+    }
+
+    [Fact]
+    public async Task GetUserAsync_ReturnsNull_WhenNotFound()
+    {
+        _repoMock.Setup(r => r.GetByIdAsync(999, It.IsAny<CancellationToken>()))
+            .ReturnsAsync((User?)null);
+
+        var result = await _sut.GetUserAsync(999);
+
+        Assert.Null(result);
+    }
+
+    [Theory]
+    [InlineData("", "required")]
+    [InlineData("ab", "too short")]
+    public async Task CreateUser_Fails_WithInvalidName(string name, string expectedError)
+    {
+        var request = new CreateUserRequest(name, "test@test.com");
+
+        var ex = await Assert.ThrowsAsync<ValidationException>(
+            () => _sut.CreateAsync(request));
+
+        Assert.Contains(expectedError, ex.Message, StringComparison.OrdinalIgnoreCase);
+    }
+}
+
+// Integration test with WebApplicationFactory
+public class UsersApiTests(WebApplicationFactory<Program> factory)
+    : IClassFixture<WebApplicationFactory<Program>>
+{
+    private readonly HttpClient _client = factory.CreateClient();
+
+    [Fact]
+    public async Task GetUsers_Returns200()
+    {
+        var response = await _client.GetAsync("/api/users");
+        response.EnsureSuccessStatusCode();
+
+        var users = await response.Content.ReadFromJsonAsync<List<UserDto>>();
+        Assert.NotNull(users);
+    }
+}
+```
+
+---
+
+## Output Format
+
+```
+━━━ C#/.NET Report ━━━━━━━━━━━━━━━━━━━━━━━━
+Skill:       C# / .NET Pro
+.NET Ver:    9+
+Scope:       [N files · N endpoints]
+─────────────────────────────────────────────────
+✅ Passed:   [checks that passed, or "All clean"]
+⚠️  Warnings: [non-blocking issues, or "None"]
+❌ Blocked:  [blocking issues requiring fix, or "None"]
+─────────────────────────────────────────────────
+VBC status:  PENDING → VERIFIED
+Evidence:    [dotnet build / dotnet test / lint output]
+```
+
+---
+
+## 🤖 LLM-Specific Traps
+
+1. **`.Result` / `.Wait()` on Async:** Never block on async. It causes deadlocks in ASP.NET Core. Always use `await`.
+2. **Missing `CancellationToken`:** Every async method in ASP.NET Core must accept and pass `CancellationToken`.
+3. **Returning EF Entities from APIs:** Never expose Entity Framework models to the API. Map to DTOs/records.
+4. **`.ToList().Where()`:** Loading all rows then filtering in memory. Use `.Where()` BEFORE `.ToListAsync()`.
+5. **Null-Forgiving Operator (`!`):** Don't suppress nullable warnings. Handle nulls explicitly.
+6. **Hardcoded Connection Strings:** Use `IConfiguration`, `appsettings.json`, or secret managers.
+7. **`ConfigureAwait(false)` in ASP.NET Core:** This is unnecessary in ASP.NET Core (no SynchronizationContext). Only use in libraries.
+8. **Missing `AsNoTracking()`:** Read-only queries must use `.AsNoTracking()` to avoid change tracking overhead.
+9. **Controller-Based APIs in Greenfield:** Minimal APIs are the modern standard. Only use controllers for legacy code.
+10. **Service Locator Anti-Pattern:** Never resolve services with `IServiceProvider.GetService<T>()` inside constructors. Use proper DI.
+
+---
+
+## 🏛️ Tribunal Integration
+
+**Slash command: `/tribunal-backend`**
+
+### ✅ Pre-Flight Self-Audit
+
+```
+✅ Did I use records/DTOs (not EF entities) in API responses?
+✅ Did I pass CancellationToken through all async methods?
+✅ Did I use await (not .Result or .Wait())?
+✅ Did I use AsNoTracking for read-only queries?
+✅ Did I project with .Select() before .ToListAsync()?
+✅ Are nullable reference types enabled and respected?
+✅ Did I use DI (not Service Locator)?
+✅ Are connection strings in configuration (not hardcoded)?
+✅ Did I use pattern matching and modern C# features?
+✅ Does dotnet build and dotnet test pass?
+```
+
+### 🛑 VBC Protocol
+
+- ❌ **Forbidden:** Declaring .NET code "works" because it compiles.
+- ✅ **Required:** Provide `dotnet build` and `dotnet test` output.