@softspark/ai-toolkit 1.2.1 → 1.3.0

package/app/rules/common/coding-style.md

@@ -0,0 +1,52 @@
+---
+language: common
+category: coding-style
+version: "1.0.0"
+---
+
+# Universal Coding Style
+
+## Principles
+- KISS: simplest solution that works. Clever code is a liability.
+- DRY: extract when you repeat 3+ times, not before.
+- YAGNI: do not build features "just in case."
+- Prefer immutability: use `const`, `final`, `val`, `let` by default.
+- Fail fast: validate inputs at boundaries, return early on errors.
+
+## Naming
+- Use descriptive names that reveal intent (`remainingRetries`, not `r`).
+- Boolean variables/functions: prefix with `is`, `has`, `can`, `should`.
+- Functions: verb + noun (`fetchUser`, `calculateTotal`, `validateInput`).
+- Avoid abbreviations unless universally understood (`id`, `url`, `http`).
+- Collections use plural nouns (`users`, `orderItems`).
+
+## Functions
+- Max 20-30 lines per function. If longer, extract.
+- Max 3 parameters. Beyond that, use an options/config object.
+- Single responsibility: one function does one thing.
+- Pure functions preferred: same input, same output, no side effects.
+- Avoid boolean parameters: use separate functions or enums.
+
+## File Organization
+- One primary concept per file (class, module, component).
+- Group imports: stdlib, external, internal, relative.
+- Constants at top, public API before private helpers.
+- Keep files under 300 lines. Split when they grow.
+
+## Comments
+- Code should be self-documenting. Comment *why*, not *what*.
+- Delete commented-out code. That is what version control is for.
+- Use TODO/FIXME with ticket references: `// TODO(PROJ-123): migrate to v2`.
+- Document public APIs with doc comments (JSDoc, docstrings, etc.).
+
+## Formatting
+- Use project formatter (Prettier, Black, gofmt, rustfmt). No manual formatting debates.
+- Consistent indentation: follow project convention (spaces vs tabs, width).
+- Max line length: 80-120 characters depending on language convention.
+- Trailing commas in multi-line structures (where language supports).
+
+## Anti-Patterns to Avoid
+- God classes/modules with 500+ lines and multiple responsibilities.
+- Deep nesting (>3 levels): use early returns and extract functions.
+- Magic numbers/strings: use named constants.
+- Mutable global state: use dependency injection instead.

package/app/rules/common/git-workflow.md

@@ -0,0 +1,45 @@
+---
+language: common
+category: git-workflow
+version: "1.0.0"
+---
+
+# Git Workflow Rules
+
+## Commit Messages
+- Use conventional commits: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`.
+- First line: imperative mood, max 72 chars (`feat: add user registration endpoint`).
+- Body (optional): explain *why*, not *what*. The diff shows what.
+- Reference tickets: `fix: prevent duplicate orders (PROJ-456)`.
+
+## Commit Practices
+- Commit small, atomic changes. One commit = one logical change.
+- Never commit: secrets, `.env` files, build artifacts, large binaries.
+- Never commit broken code to `main`. Use feature branches.
+- Squash fixup commits before merging to keep history clean.
+
+## Branching
+- `main` is always deployable. Protect it with required reviews and CI.
+- Feature branches: `feat/user-registration`, `fix/order-total-calc`.
+- Delete branches after merge. Stale branches are clutter.
+- Rebase feature branches on main before PR to keep linear history.
+
+## Pull Requests
+- Keep PRs small: <400 lines changed. Split large features into stacked PRs.
+- PR title follows conventional commit format.
+- Include: summary, test plan, and screenshots/recordings for UI changes.
+- Require at least one approval before merge.
+
+## Code Review
+- Review for: correctness, security, performance, readability.
+- Approve with comments if nits only. Block for: bugs, security, missing tests.
+- Respond to reviews within 24 hours. Do not let PRs rot.
+
+## Tags and Releases
+- Use semantic versioning: MAJOR.MINOR.PATCH.
+- Tag releases: `git tag v1.2.3`. Automate changelog from commits.
+
+## Recovery
+- Use `git stash` for WIP, not unfinished commits.
+- Prefer `git revert` over `git reset --hard` on shared branches.
+- Never force-push to `main` or shared branches.

package/app/rules/common/performance.md

@@ -0,0 +1,49 @@
+---
+language: common
+category: performance
+version: "1.0.0"
+---
+
+# Universal Performance Rules
+
+## Mindset
+- Profile before optimizing. Measure, do not guess.
+- Premature optimization is the root of all evil. Ship correct first, fast second.
+- Set performance budgets and test against them in CI.
+
+## Database
+- Fix N+1 queries: use JOINs, eager loading, or batch fetching.
+- Add indexes for columns used in WHERE, ORDER BY, and JOIN clauses.
+- Use EXPLAIN/ANALYZE to verify query plans. Avoid full table scans.
+- Paginate all list endpoints. Never return unbounded result sets.
+- Use connection pooling. Never open a new connection per request.
+
+## Caching
+- Cache at the right layer: CDN > reverse proxy > application > database.
+- Set explicit TTLs. Stale cache is worse than no cache.
+- Cache immutable or slowly-changing data. Avoid caching user-specific mutable data.
+- Use cache-aside pattern: check cache, fetch on miss, populate cache.
+- Include cache invalidation strategy before adding any cache.
+
+## I/O and Network
+- Async/non-blocking for I/O-bound work. Thread pools for CPU-bound work.
+- Batch operations where possible: bulk inserts, batch API calls.
+- Set timeouts on all external calls: HTTP, database, message queues.
+- Use streaming for large payloads instead of loading everything into memory.
+
+## Memory
+- Preallocate collections when size is known.
+- Use streaming/iterators for large datasets instead of loading all into memory.
+- Watch for memory leaks: unclosed connections, growing caches, event listener accumulation.
+- Avoid unnecessary copies/clones of large data structures.
+
+## API Performance
+- Compress responses (gzip/brotli). Return only requested fields.
+- Use HTTP/2 or HTTP/3 where supported.
+- Implement request deduplication for identical concurrent requests.
+- Return 202 Accepted for long-running operations, process async.
+
+## Monitoring
+- Track p50, p95, p99 latencies, not just averages.
+- Alert on latency regressions, not just errors.
+- Log slow queries (>100ms) and slow endpoints (>500ms).

package/app/rules/common/security.md

@@ -0,0 +1,59 @@
+---
+language: common
+category: security
+version: "1.0.0"
+---
+
+# Universal Security Rules
+
+## Input Validation
+- Validate ALL input at API boundaries. Trust nothing from clients.
+- Use allowlists over denylists: define what IS valid, reject everything else.
+- Validate type, length, format, and range for every input field.
+- Sanitize output for the target context (HTML, SQL, shell, URL).
+
+## Authentication
+- Hash passwords with bcrypt, scrypt, or argon2. Never MD5/SHA for passwords.
+- Use constant-time comparison for tokens and secrets.
+- Implement rate limiting on auth endpoints (login, register, password reset).
+- Enforce MFA for admin and sensitive operations.
+
+## Authorization
+- Check permissions on every request, not just at the UI level.
+- Use principle of least privilege: default deny, explicitly grant.
+- Validate resource ownership: user can only access their own data.
+- Never rely on client-side authorization checks.
+
+## Secrets Management
+- Never hardcode secrets in source code. Use environment variables or vaults.
+- Rotate secrets regularly. Automate rotation where possible.
+- Use different secrets per environment (dev/staging/prod).
+- Add `.env` to `.gitignore`. Use `.env.example` as a template.
+
+## SQL Injection Prevention
+- Always use parameterized queries or ORM query builders.
+- Never concatenate user input into SQL strings.
+- Validate and cast types before using in queries.
+
+## XSS Prevention
+- Escape all dynamic content rendered in HTML.
+- Use Content Security Policy (CSP) headers.
+- Set `HttpOnly` and `Secure` flags on authentication cookies.
+- Avoid `innerHTML`, `eval()`, and `dangerouslySetInnerHTML`.
+
+## API Security
+- Use HTTPS everywhere. No exceptions.
+- Implement rate limiting and request throttling.
+- Set CORS headers explicitly. Never use `*` in production.
+- Return generic error messages to clients. Log details server-side.
+- Use security headers: HSTS, X-Content-Type-Options, X-Frame-Options.
+
+## Dependencies
+- Audit dependencies regularly (`npm audit`, `pip-audit`, `cargo audit`).
+- Pin dependency versions. Use lockfiles.
+- Remove unused dependencies. Each dependency is an attack surface.
+
+## Logging
+- Never log passwords, tokens, credit cards, or PII.
+- Log security events: failed logins, permission denials, input validation failures.
+- Use structured logging with correlation IDs for traceability.

package/app/rules/common/testing.md

@@ -0,0 +1,53 @@
+---
+language: common
+category: testing
+version: "1.0.0"
+---
+
+# Universal Testing Rules
+
+## Test Structure
+- Use Arrange-Act-Assert (AAA) pattern in every test.
+- One logical assertion per test. Multiple `assert` calls are fine if testing one behavior.
+- Test names describe behavior: `test_returns_404_when_user_not_found`.
+- Keep tests independent: no shared mutable state between tests.
+
+## Test Organization
+- Mirror source structure: `src/auth/login.ts` -> `tests/auth/login.test.ts`.
+- Separate unit, integration, and e2e tests into distinct directories or markers.
+- Shared fixtures go in `conftest.py`, `test-utils.ts`, or equivalent.
+
+## What to Test
+- Test behavior, not implementation. Tests should survive refactors.
+- Cover: happy path, error cases, edge cases, boundary values.
+- New code: 100% coverage. Overall project: >70%.
+- Critical paths (auth, payments, data mutations): always tested.
+
+## What NOT to Test
+- Framework internals (ORM save, HTTP library send).
+- Trivial getters/setters with no logic.
+- Third-party library correctness.
+- Private methods directly: test through public API.
+
+## Mocking
+- Mock at boundaries: HTTP clients, databases, file systems, clocks.
+- Prefer fakes over mocks when logic is complex.
+- Never mock the thing you are testing.
+- Reset mocks between tests to prevent leakage.
+
+## Test Quality
+- Tests must be deterministic: no flaky tests allowed.
+- Tests must be fast: unit tests <100ms each, test suite <60s.
+- Avoid `sleep` in tests: use polling, events, or test clocks.
+- Do not test implementation details (private methods, internal state).
+
+## Coverage
+- Measure coverage but do not chase 100%: focus on critical paths.
+- Coverage gaps in error handling and edge cases are worse than gaps in happy paths.
+- New PRs must not decrease overall coverage.
+
+## Test Data
+- Use factories/builders to create test data, not raw constructors.
+- Keep test data minimal: only set fields relevant to the test.
+- Do not share mutable test data across tests.
+- Use realistic but not real data (no production data in tests).

package/app/rules/cpp/coding-style.md

@@ -0,0 +1,55 @@
+---
+language: cpp
+category: coding-style
+version: "1.0.0"
+---
+
+# C++ Coding Style
+
+## Naming
+- PascalCase: classes, structs, enums, type aliases, concepts.
+- camelCase or snake_case: functions, methods, variables (be consistent per project).
+- UPPER_SNAKE: macros, compile-time constants.
+- Prefix member variables with `m_` or suffix with `_` (pick one convention).
+- Namespace names: lowercase, short (`namespace io`, `namespace util`).
+
+## Modern C++ (17/20/23)
+- Use `auto` for iterator types and complex template deductions.
+- Use `std::optional<T>` instead of sentinel values or pointers for optional returns.
+- Use `std::variant` over union types. Use `std::visit` for dispatch.
+- Use `std::string_view` for non-owning string parameters.
+- Use structured bindings: `auto [key, value] = *map.begin();`.
+- Use `constexpr` for compile-time evaluation. Prefer over macros.
+
+## Memory Management
+- Use RAII exclusively. Every resource acquisition is an initialization.
+- Use `std::unique_ptr` for exclusive ownership (default choice).
+- Use `std::shared_ptr` only when ownership is genuinely shared.
+- Never use raw `new`/`delete`. Use `std::make_unique` / `std::make_shared`.
+- Use `std::span<T>` (C++20) for non-owning views over contiguous data.
+
+## Functions
+- Pass small types by value. Pass large types by `const&`.
+- Use `[[nodiscard]]` on functions whose return value must not be ignored.
+- Use `noexcept` on functions that do not throw (move constructors, destructors).
+- Limit function parameters to 4. Use structs for configuration objects.
+- Use trailing return types for complex template return deductions.
+
+## Includes and Dependencies
+- Use `#pragma once` or include guards. Prefer `#pragma once` for simplicity.
+- Order: corresponding header, C++ stdlib, third-party, project headers.
+- Forward-declare in headers when possible to reduce compile times.
+- Minimize header dependencies. Use the Pimpl idiom for ABI stability.
+
+## Avoid
+- Raw pointers for ownership. Use smart pointers.
+- C-style casts. Use `static_cast`, `dynamic_cast`, `const_cast`.
+- Macros for constants or functions. Use `constexpr` and templates.
+- `using namespace std;` in headers. Acceptable in .cpp files with caution.
+- `std::endl` -- use `'\n'` (endl flushes the buffer unnecessarily).
+
+## Formatting
+- Use clang-format with a committed `.clang-format` file.
+- Use clang-tidy for static analysis and automated modernization.
+- Max line length: 100-120 characters.
+- Braces: use Allman or K&R consistently per project.

package/app/rules/cpp/frameworks.md

@@ -0,0 +1,55 @@
+---
+language: cpp
+category: frameworks
+version: "1.0.0"
+---
+
+# C++ Frameworks
+
+## CMake
+- Use modern CMake (3.14+): target-based, not directory-based.
+- Use `target_link_libraries` with `PUBLIC`/`PRIVATE`/`INTERFACE` visibility.
+- Use `FetchContent` for dependency management. Avoid manual submodule vendoring.
+- Set `CMAKE_CXX_STANDARD 20` (or 23) at the project level.
+- Use `target_compile_options` for per-target flags, not global `add_compile_options`.
+- Export targets with `install(TARGETS ... EXPORT ...)` for library consumers.
+
+## Boost
+- Use Boost.Asio for async networking and I/O.
+- Use `boost::beast` for HTTP/WebSocket built on Asio.
+- Use `boost::json` or `nlohmann/json` for JSON parsing.
+- Prefer C++ stdlib equivalents when available (e.g., `std::optional` over `boost::optional`).
+- Link only the Boost libraries you actually use. Many are header-only.
+
+## Qt
+- Use signals and slots for event-driven communication.
+- Use `QObject` parent-child ownership for automatic memory management.
+- Use `QML` for declarative UI. Keep business logic in C++ backend.
+- Use `QThread` with worker objects (moveToThread), not subclassing QThread.
+- Use smart pointers for non-QObject resources. QObject children are auto-deleted.
+
+## gRPC
+- Define services in `.proto` files. Generate C++ stubs with `protoc`.
+- Use async server with `CompletionQueue` for high-throughput services.
+- Use `grpc::ClientContext` for per-call deadlines and metadata.
+- Use interceptors for logging, auth, and metrics.
+- Set deadlines on every RPC call to prevent hanging.
+
+## Networking (Asio)
+- Use `io_context` as the event loop. Run from one or more threads.
+- Use `co_await` (C++20 coroutines) with Asio for clean async code.
+- Use `strand` for serializing access to shared state across handlers.
+- Use `steady_timer` for timeouts and periodic tasks.
+- Handle errors via `error_code` parameter, not exceptions, in async callbacks.
+
+## Database
+- Use `libpq` (PostgreSQL) or `SOCI` for database access.
+- Use prepared statements exclusively. Never concatenate SQL strings.
+- Use connection pooling for multi-threaded server applications.
+- Use `SQLite` via `sqlite3` C API with RAII wrappers for embedded use cases.
+
+## Package Management
+- Use `vcpkg` or `Conan 2` for dependency management.
+- Pin dependency versions in `vcpkg.json` or `conanfile.py`.
+- Use CI caching for build artifacts and dependency downloads.
+- Prefer pre-built binary packages for CI speed.

package/app/rules/cpp/patterns.md

@@ -0,0 +1,57 @@
+---
+language: cpp
+category: patterns
+version: "1.0.0"
+---
+
+# C++ Patterns
+
+## Error Handling
+- Use exceptions for truly exceptional conditions. Use return types for expected failures.
+- Use `std::expected<T, E>` (C++23) or `Result<T, E>` pattern for recoverable errors.
+- Use `std::error_code` / `std::error_category` for system-level errors.
+- Use `noexcept` on functions that must not throw (destructors, move operations).
+- Catch by `const&`. Never catch by value (slicing) or pointer.
+
+## RAII Patterns
+- Wrap every resource (memory, file, lock, socket) in an RAII type.
+- Use `std::lock_guard` or `std::scoped_lock` for mutex management.
+- Use `std::unique_lock` when deferred locking or condition variables are needed.
+- Use `std::fstream` (auto-closes) instead of `fopen`/`fclose`.
+- Write custom RAII wrappers for C library resources (file descriptors, handles).
+
+## Smart Pointer Patterns
+- `unique_ptr`: default ownership model. Transfer with `std::move`.
+- `shared_ptr`: use only for genuinely shared ownership graphs.
+- `weak_ptr`: break cycles in `shared_ptr` graphs. Use `lock()` to access.
+- Factory functions should return `unique_ptr`. Let callers upgrade to `shared_ptr`.
+- Never pass smart pointers by reference. Pass `T&` or `T*` to non-owning consumers.
+
+## Concurrency
+- Use `std::thread` with `std::jthread` (C++20) for auto-joining threads.
+- Use `std::mutex` + `std::scoped_lock` for shared data protection.
+- Use `std::atomic<T>` for lock-free single-variable synchronization.
+- Use `std::condition_variable` for producer-consumer patterns.
+- Use `std::async` / `std::future` for simple parallel computation.
+- Use `std::counting_semaphore` (C++20) for resource pool limiting.
+
+## Template Patterns
+- Use CRTP for compile-time polymorphism (static dispatch).
+- Use `concepts` (C++20) to constrain template parameters with clear error messages.
+- Use `if constexpr` for compile-time branching in templates.
+- Use variadic templates and fold expressions for parameter packs.
+- Prefer `constexpr` functions over template metaprogramming when possible.
+
+## Design Patterns
+- Use `std::variant` + `std::visit` for type-safe visitor pattern.
+- Use `std::function` for type-erased callbacks and strategy pattern.
+- Use Pimpl idiom (`unique_ptr<Impl>`) for ABI stability and compilation firewall.
+- Use Builder pattern with method chaining for complex object construction.
+- Use `std::move` semantics in move constructors for efficient resource transfer.
+
+## Anti-Patterns
+- Raw `new`/`delete`: use smart pointers and containers.
+- Returning raw pointers from factory functions: return `unique_ptr`.
+- `const_cast` to remove constness: redesign the interface.
+- Deep inheritance hierarchies: prefer composition and templates.
+- Premature optimization over readability: profile first, optimize second.

package/app/rules/cpp/security.md

@@ -0,0 +1,61 @@
+---
+language: cpp
+category: security
+version: "1.0.0"
+---
+
+# C++ Security
+
+## Buffer Overflow Prevention
+- Use `std::string`, `std::vector`, `std::array` instead of C arrays and `char[]`.
+- Use `std::span` (C++20) for safe, bounds-checked views over contiguous data.
+- Never use `strcpy`, `strcat`, `sprintf`. Use `std::string` operations or `snprintf`.
+- Enable `-D_FORTIFY_SOURCE=2` in release builds for runtime buffer checks.
+- Use `at()` for bounds-checked container access in untrusted input paths.
+
+## Memory Safety
+- Use smart pointers exclusively. Zero raw `new`/`delete` in application code.
+- Enable AddressSanitizer (`-fsanitize=address`) in development and CI builds.
+- Enable UndefinedBehaviorSanitizer (`-fsanitize=undefined`) in test builds.
+- Use `-fstack-protector-strong` for stack buffer overflow detection.
+- Use Valgrind for memory leak detection in integration tests.
+
+## Integer Safety
+- Check for overflow before arithmetic on untrusted integers.
+- Use `std::numeric_limits<T>::max()` for boundary checks.
+- Use unsigned types only for bit manipulation. Prefer signed for arithmetic.
+- Use `static_cast` explicitly. Never rely on implicit narrowing conversions.
+- Enable `-Wconversion` and `-Wsign-conversion` warnings.
+
+## Input Validation
+- Validate all external input: file data, network packets, command-line arguments.
+- Use `std::stoi` / `std::stol` with exception handling for string-to-number conversion.
+- Set maximum sizes for dynamic allocations based on untrusted input.
+- Validate file paths to prevent directory traversal (`../`).
+- Use allowlist validation for format specifiers and command strings.
+
+## Secure Coding
+- Use `std::fill` or `explicit_bzero()` to zero sensitive memory before deallocation.
+- Use constant-time comparison for secrets (avoid timing side-channels).
+- Use `mlock()` to prevent sensitive memory from being swapped to disk.
+- Compile with `-fPIE -pie` for position-independent executables (ASLR).
+- Enable `-Werror` in CI to prevent warnings from becoming vulnerabilities.
+
+## Dependencies
+- Audit third-party C libraries for known CVEs before inclusion.
+- Use `vcpkg` or `Conan` with pinned versions for reproducible builds.
+- Prefer well-maintained libraries with active security response teams.
+- Minimize C library usage. Prefer C++ standard library equivalents.
+
+## Concurrency Safety
+- Use `std::mutex` with `std::scoped_lock` for all shared data access.
+- Use `std::atomic` for lock-free single-variable operations.
+- Enable ThreadSanitizer (`-fsanitize=thread`) in test builds for race detection.
+- Avoid `volatile` for synchronization. It does not provide atomicity or ordering.
+- Use RAII lock guards. Never manually `lock()`/`unlock()`.
+
+## Compiler Hardening
+- Enable all warnings: `-Wall -Wextra -Wpedantic`.
+- Use `-D_GLIBCXX_ASSERTIONS` for debug iterator and container checks.
+- Use `-fno-exceptions` only when exception safety is not required.
+- Link with `-Wl,-z,relro,-z,now` for full RELRO (GOT hardening).

package/app/rules/cpp/testing.md

@@ -0,0 +1,58 @@
+---
+language: cpp
+category: testing
+version: "1.0.0"
+---
+
+# C++ Testing
+
+## Framework
+- Use GoogleTest (gtest) as the primary test framework.
+- Use GoogleMock (gmock) for mocking interfaces and virtual classes.
+- Use Catch2 as a lightweight alternative (header-only, BDD-style).
+- Use CTest for test discovery and execution via CMake.
+
+## File Naming
+- Test files: `foo_test.cpp` or `test_foo.cpp` in a dedicated `tests/` directory.
+- Mirror source directory structure in test directory.
+- One test file per source file or logical component.
+- Use `CMakeLists.txt` with `add_test()` to register tests.
+
+## Structure (GoogleTest)
+- Use `TEST(SuiteName, TestName)` for simple tests.
+- Use `TEST_F(FixtureName, TestName)` for tests sharing setup/teardown.
+- Use `SetUp()` / `TearDown()` in fixtures for per-test initialization.
+- Keep tests focused: one logical assertion per test case.
+
+## Assertions
+- Use `EXPECT_*` (non-fatal) by default. Use `ASSERT_*` only when continuation is meaningless.
+- `EXPECT_EQ`, `EXPECT_NE`, `EXPECT_LT`, `EXPECT_GT` for comparisons.
+- `EXPECT_TRUE`, `EXPECT_FALSE` for boolean conditions.
+- `EXPECT_THROW(expr, ExceptionType)` for exception testing.
+- `EXPECT_THAT(value, matcher)` with gmock matchers for complex assertions.
+
+## Parameterized Tests
+- Use `INSTANTIATE_TEST_SUITE_P` with `testing::Values(...)` for value-parameterized tests.
+- Use `testing::Combine()` for multi-dimensional parameterization.
+- Use `TYPED_TEST_SUITE` for type-parameterized tests across template types.
+- Prefer parameterized tests over copy-pasting similar test bodies.
+
+## Mocking (GoogleMock)
+- Define mock classes: `MOCK_METHOD(ReturnType, MethodName, (Args), (Qualifiers))`.
+- Use `EXPECT_CALL(mock, Method(matchers)).WillOnce(Return(value))`.
+- Use `NiceMock<T>` to suppress uninteresting call warnings.
+- Use `StrictMock<T>` to fail on any unexpected call.
+- Use dependency injection (constructor) to pass mock objects.
+
+## Build Integration
+- Use `FetchContent` or `find_package` to integrate gtest in CMake.
+- Enable `BUILD_TESTING` option to conditionally include tests.
+- Use `ctest --output-on-failure` for CI runs.
+- Use sanitizers in test builds: `-fsanitize=address,undefined`.
+
+## Best Practices
+- Test edge cases: empty input, max values, null pointers, boundary conditions.
+- Use RAII test fixtures for resource cleanup (no manual teardown).
+- Avoid testing private methods directly. Test through public API.
+- Use `valgrind` or ASan/UBSan in CI to detect memory errors.
+- Keep tests fast: mock I/O and external dependencies.

package/app/rules/csharp/coding-style.md

@@ -0,0 +1,54 @@
+---
+language: csharp
+category: coding-style
+version: "1.0.0"
+---
+
+# C# Coding Style
+
+## Naming
+- PascalCase: classes, structs, enums, interfaces, methods, properties, events.
+- camelCase: local variables, parameters, private fields.
+- Prefix interfaces with `I`: `IUserRepository`, `IDisposable`.
+- Prefix private fields with `_`: `private readonly ILogger _logger;`.
+- UPPER_SNAKE: not conventional in C#. Use PascalCase for constants.
+
+## Nullable Reference Types
+- Enable `<Nullable>enable</Nullable>` in all projects.
+- Use `string?` only when null is semantically meaningful.
+- Use `!` (null-forgiving) operator sparingly -- only when compiler cannot infer.
+- Use `??` (null-coalescing) and `?.` (null-conditional) for safe navigation.
+- Use `required` modifier (C# 11) on properties that must be set at initialization.
+
+## Records and Types
+- Use `record` for immutable value objects and DTOs.
+- Use `record struct` for small, stack-allocated value types.
+- Use `init` properties for immutable-after-construction objects.
+- Use `with` expressions for non-destructive mutation of records.
+- Use primary constructors (C# 12) for concise class definitions.
+
+## Pattern Matching
+- Use `is` pattern for type checks: `if (obj is string s)`.
+- Use `switch` expressions for exhaustive matching over enums/types.
+- Use property patterns: `user is { Age: > 18, Role: "admin" }`.
+- Use relational patterns: `size is > 0 and < 100`.
+- Use list patterns (C# 11): `numbers is [1, 2, .., var last]`.
+
+## Async/Await
+- Suffix async methods with `Async`: `GetUserAsync()`.
+- Return `Task<T>` or `ValueTask<T>`, never `void` (except event handlers).
+- Use `await` with `ConfigureAwait(false)` in library code.
+- Use `CancellationToken` parameters in all async public APIs.
+- Prefer `ValueTask<T>` when synchronous completion is common.
+
+## File Organization
+- One type per file. File name matches type name.
+- Use file-scoped namespaces (C# 10): `namespace MyApp.Services;`.
+- Order members: fields, constructors, properties, public methods, private methods.
+- Use `global using` directives in a single `GlobalUsings.cs` file.
+
+## Formatting
+- Use `.editorconfig` with C# style rules committed to the repository.
+- Use `dotnet format` for automated formatting.
+- Use Roslyn analyzers for compile-time style enforcement.
+- Max line length: 120 characters.

package/app/rules/csharp/frameworks.md

@@ -0,0 +1,60 @@
+---
+language: csharp
+category: frameworks
+version: "1.0.0"
+---
+
+# C# Frameworks
+
+## ASP.NET Core
+- Use minimal APIs for simple endpoints. Use controllers for complex APIs.
+- Use `[ApiController]` attribute for automatic model validation and error responses.
+- Use `Results.Ok()`, `Results.NotFound()` for typed HTTP results.
+- Use endpoint filters / middleware for cross-cutting concerns.
+- Use `IHostedService` / `BackgroundService` for long-running background tasks.
+- Map routes with `app.MapGet()`, `app.MapPost()` for minimal API style.
+
+## Entity Framework Core
+- Use code-first migrations: `dotnet ef migrations add`, `dotnet ef database update`.
+- Use `DbContext` with scoped lifetime (one per request).
+- Use `AsNoTracking()` for read-only queries. Use `AsTracking()` only for updates.
+- Use `Include()` / `ThenInclude()` for eager loading related entities.
+- Use shadow properties for audit fields (`CreatedAt`, `UpdatedAt`).
+- Use `HasQueryFilter()` for soft-delete and multi-tenancy global filters.
+
+## Blazor
+- Use Blazor Server for internal tools. Use Blazor WASM for public-facing SPAs.
+- Use `@inject` for dependency injection in components.
+- Use `EventCallback<T>` for parent-child component communication.
+- Use `CascadingValue` for deeply shared state (theme, auth).
+- Use `StateContainer` pattern with events for cross-component state management.
+
+## SignalR
+- Use strongly-typed hubs: `Hub<IClientMethods>` for compile-time safety.
+- Use `HubContext<T>` for sending messages from outside hubs.
+- Use groups for targeted broadcasting: `Groups.AddToGroupAsync()`.
+- Configure automatic reconnection on the client side.
+
+## MassTransit / Messaging
+- Use MassTransit for message bus abstraction over RabbitMQ/Azure Service Bus.
+- Define messages as `record` types for immutability.
+- Use consumers (`IConsumer<T>`) for message handling.
+- Use sagas for long-running, multi-step workflows with state.
+- Use retry and circuit breaker policies for transient failures.
+
+## Logging
+- Use `ILogger<T>` via DI. Never instantiate loggers manually.
+- Use structured logging: `_logger.LogInformation("User {UserId} logged in", userId)`.
+- Use Serilog with sinks for structured, centralized logging.
+- Use log scopes for request correlation: `using (_logger.BeginScope(...))`.
+
+## Configuration
+- Use `appsettings.json` + environment-specific overrides + environment variables.
+- Bind configuration sections to strongly-typed classes with `IOptions<T>`.
+- Use `IOptionsMonitor<T>` for configuration that changes at runtime.
+- Validate configuration at startup with `ValidateDataAnnotations()`.
+
+## Health Checks
+- Use `app.MapHealthChecks("/health")` for liveness probes.
+- Register custom health checks for database, cache, and external service dependencies.
+- Use `AspNetCore.HealthChecks.*` NuGet packages for common checks.