@softspark/ai-toolkit 1.2.1 → 1.3.0

package/app/rules/golang/security.md

@@ -0,0 +1,61 @@
+---
+language: golang
+category: security
+version: "1.0.0"
+---
+
+# Go Security
+
+## Input Validation
+- Validate all input at API boundaries. Use struct tags or manual validation.
+- Use `validator` package for struct validation: `validate:"required,email"`.
+- Parse and validate numeric IDs: `strconv.Atoi()` with error checking.
+- Limit request body size: `http.MaxBytesReader(w, r.Body, maxBytes)`.
+
+## SQL Injection
+- Always use parameterized queries: `db.Query("SELECT * FROM users WHERE id = $1", id)`.
+- Never concatenate user input into SQL strings.
+- Use `sqlx.In()` for safe dynamic IN clauses.
+- Use ORM query builders (GORM, Ent) for dynamic query construction.
+
+## Command Injection
+- Use `exec.Command("binary", args...)` with separate arguments, not shell strings.
+- Never use `exec.Command("sh", "-c", userInput)`.
+- Validate and sanitize file paths against traversal attacks.
+- Use `filepath.Clean()` and verify paths are within allowed directories.
+
+## Cryptography
+- Use `crypto/rand` for random values, never `math/rand` for security.
+- Use `bcrypt` or `argon2` for password hashing: `golang.org/x/crypto/bcrypt`.
+- Use `crypto/subtle.ConstantTimeCompare()` for timing-safe comparisons.
+- Use `crypto/tls` with `tls.Config{MinVersion: tls.VersionTLS12}`.
+
+## Secrets
+- Load secrets from environment variables: `os.Getenv("SECRET_KEY")`.
+- Never hardcode secrets, tokens, or API keys in source code.
+- Use `go-envconfig` or similar for validated env var loading.
+- Use Go build tags or ldflags for build-time configuration.
+
+## HTTP Security
+- Set `ReadTimeout`, `WriteTimeout`, `IdleTimeout` on `http.Server`.
+- Use `helmet`-equivalent headers: HSTS, X-Content-Type-Options, X-Frame-Options.
+- Implement rate limiting with `golang.org/x/time/rate` or middleware.
+- Use `net/http` with TLS. Never serve production HTTP without encryption.
+
+## Concurrency Safety
+- Use `sync.Mutex` or `sync.RWMutex` for shared mutable state.
+- Run `go test -race` in CI to detect data races.
+- Avoid shared state where possible. Prefer channels for communication.
+- Use `atomic` package for simple counters and flags.
+
+## Dependencies
+- Run `govulncheck ./...` in CI to check for known vulnerabilities.
+- Use `go mod tidy` to remove unused dependencies.
+- Pin dependencies via `go.sum`. Review dependency changes in PRs.
+- Audit transitive dependencies. Use `go mod graph` to inspect the tree.
+
+## Error Information Disclosure
+- Never expose internal error messages to clients.
+- Log detailed errors server-side, return generic messages to clients.
+- Use error codes for machine-readable error classification.
+- Do not include stack traces in production API responses.

package/app/rules/golang/testing.md

@@ -0,0 +1,54 @@
+---
+language: golang
+category: testing
+version: "1.0.0"
+---
+
+# Go Testing
+
+## Framework
+- Use the standard `testing` package. No external test frameworks required.
+- Use `testify/assert` and `testify/require` for readable assertions.
+- Use `testify/mock` or `mockgen` for generating mocks.
+- Use `go test -race` in CI to detect data races.
+
+## File Naming
+- Test files: `*_test.go` in the same package.
+- Black-box tests: use `package foo_test` to test only exported API.
+- White-box tests: use `package foo` to test internals.
+- Test helpers: `testutil_test.go` or `testdata/` directory.
+
+## Table-Driven Tests
+- Use table-driven tests for functions with multiple input/output cases.
+- Name each case: `{name: "empty input returns error", input: "", wantErr: true}`.
+- Use `t.Run(tc.name, func(t *testing.T) { ... })` for subtests.
+- Use `t.Parallel()` in subtests when tests are independent.
+
+## Test Helpers
+- Use `t.Helper()` in helper functions for correct line reporting.
+- Use `t.Cleanup()` for teardown instead of defer in test functions.
+- Use `testing.TB` interface to share helpers between tests and benchmarks.
+- Use `testdata/` directory for test fixtures (excluded from build).
+
+## Mocking
+- Define interfaces at the consumer, not the provider.
+- Use `mockgen` to auto-generate mocks from interfaces.
+- Use `httptest.NewServer()` for HTTP integration tests.
+- Use `httptest.NewRecorder()` for handler unit tests.
+
+## Integration Tests
+- Use build tags: `//go:build integration` to separate from unit tests.
+- Use `testcontainers-go` for database/service containers in tests.
+- Use `t.Setenv()` (Go 1.17+) for environment variable testing.
+
+## Benchmarks
+- Use `func BenchmarkXxx(b *testing.B)` with `b.N` loop.
+- Use `b.ResetTimer()` after expensive setup.
+- Use `b.ReportAllocs()` to track allocations.
+- Run: `go test -bench=. -benchmem`.
+
+## Coverage
+- Run: `go test -coverprofile=coverage.out ./...`.
+- View: `go tool cover -html=coverage.out`.
+- Set minimum coverage threshold in CI.
+- Focus coverage on business logic, not generated code.

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

@@ -0,0 +1,56 @@
+---
+language: java
+category: coding-style
+version: "1.0.0"
+---
+
+# Java Coding Style
+
+## Naming
+- PascalCase: classes, interfaces, enums, records, annotations.
+- camelCase: methods, variables, parameters.
+- UPPER_SNAKE: constants (`static final`).
+- Package names: lowercase, dot-separated, reverse domain (`com.company.project`).
+- No Hungarian notation. No `I` prefix on interfaces.
+
+## Modern Java (17+)
+- Use `record` for immutable data carriers. No need for Lombok in most cases.
+- Use `sealed` classes/interfaces for restricted hierarchies.
+- Use pattern matching: `if (obj instanceof String s)` instead of cast.
+- Use `switch` expressions with arrow syntax and exhaustiveness.
+- Use text blocks (`"""`) for multiline strings (SQL, JSON, HTML).
+
+## Types
+- Use `var` for local variables when the type is obvious from the right-hand side.
+- Use `Optional<T>` for return types that may be absent. Never for fields or params.
+- Prefer `List.of()`, `Map.of()`, `Set.of()` for immutable collections.
+- Use `Stream` for collection transformations. Avoid streams for simple iterations.
+
+## Classes
+- Prefer composition over inheritance. Use interfaces for abstraction.
+- Keep classes focused: single responsibility.
+- Use `final` on classes not designed for extension.
+- Use `private` constructors + static factory methods for controlled instantiation.
+- Records over POJOs for value types. Lombok only if records are insufficient.
+
+## Methods
+- Max 20-30 lines per method. Extract when longer.
+- Use `@Override` on every overridden method.
+- Return empty collections over `null`. Use `Collections.emptyList()` or `List.of()`.
+- Avoid checked exceptions for programming errors. Use runtime exceptions.
+
+## Formatting
+- Use project formatter (Google Java Format or IDE-configured).
+- Use `@SuppressWarnings` sparingly and with specific warning names.
+- Use `final` for parameters and local variables where practical.
+
+## Nullability
+- Annotate with `@Nullable` / `@NonNull` from JSpecify or JetBrains.
+- Use `Objects.requireNonNull()` at public API boundaries.
+- Never return `null` from collections or arrays. Return empty.
+- Use `Optional` for genuinely optional return values.
+
+## Documentation
+- Javadoc on all public classes and methods.
+- Use `@param`, `@return`, `@throws` tags for public API methods.
+- Skip Javadoc for obvious getters, `toString()`, and `equals()`.

package/app/rules/java/frameworks.md

@@ -0,0 +1,54 @@
+---
+language: java
+category: frameworks
+version: "1.0.0"
+---
+
+# Java Frameworks
+
+## Spring Boot
+- Use Spring Boot 3+ with Java 17+ minimum.
+- Use `@RestController` for REST APIs. Return `ResponseEntity` for status control.
+- Use `@Valid` + Jakarta Bean Validation for request validation.
+- Use profiles (`@Profile`) for environment-specific configuration.
+- Use `application.yml` over `application.properties` for readability.
+- Externalize config: env vars > config files > hardcoded defaults.
+
+## Spring Data JPA
+- Use repository interfaces extending `JpaRepository`.
+- Use `@Query` with JPQL for custom queries. Use native queries only when needed.
+- Use `@EntityGraph` to prevent N+1 queries in associations.
+- Use `Specification` for dynamic query building.
+- Always use `@Transactional` at the service layer, not repository.
+
+## Spring Security
+- Use `SecurityFilterChain` bean configuration (not `WebSecurityConfigurerAdapter`).
+- Use `@PreAuthorize` / `@Secured` for method-level authorization.
+- Use BCrypt for password encoding: `new BCryptPasswordEncoder()`.
+- Configure CORS, CSRF, and session management explicitly.
+- Use OAuth2 Resource Server for JWT validation in APIs.
+
+## Hibernate / JPA
+- Use `FetchType.LAZY` by default on all associations.
+- Use `@BatchSize` or `@Fetch(FetchMode.SUBSELECT)` to avoid N+1.
+- Use `@Version` for optimistic locking on entities.
+- Use DTOs (records) for read queries. Do not expose entities in APIs.
+- Use Flyway or Liquibase for schema migrations.
+
+## Quarkus / Micronaut
+- Use for microservices and serverless where startup time matters.
+- Use compile-time DI (Micronaut) or build-time optimization (Quarkus).
+- Use reactive patterns with Mutiny (Quarkus) or Reactor (Micronaut).
+- Use native image builds with GraalVM for production deployments.
+
+## Build Tools
+- Use Gradle (Kotlin DSL) for new projects. Maven for enterprise legacy.
+- Use dependency management to unify versions across modules.
+- Use Bill of Materials (BOM) imports for consistent Spring versions.
+- Use Spotless or Checkstyle for enforced code formatting.
+
+## Logging
+- Use SLF4J facade with Logback or Log4j2 backend.
+- Use structured logging with MDC for correlation IDs.
+- Use parameterized logging: `log.info("User {} created", userId)`.
+- Never log sensitive data (passwords, tokens, PII).

package/app/rules/java/patterns.md

@@ -0,0 +1,59 @@
+---
+language: java
+category: patterns
+version: "1.0.0"
+---
+
+# Java Patterns
+
+## Error Handling
+- Use unchecked exceptions for programming errors (`IllegalArgumentException`).
+- Use checked exceptions only for recoverable conditions the caller must handle.
+- Create domain exception hierarchy: `AppException` -> `NotFoundException`, etc.
+- Never catch `Exception` or `Throwable` broadly. Catch specific types.
+- Use `try-with-resources` for all `AutoCloseable` resources.
+
+## Immutability
+- Use `record` for immutable value objects (Java 16+).
+- Use `List.copyOf()`, `Map.copyOf()` to create unmodifiable copies.
+- Make fields `private final`. No setters unless mutation is required.
+- Return defensive copies of mutable collections from getters.
+- Use builder pattern for constructing immutable objects with many fields.
+
+## Optional
+- Use `Optional<T>` as return type for methods that may not return a value.
+- Chain: `optional.map(...).orElseThrow(...)`. Avoid `isPresent()` + `get()`.
+- Never use `Optional` for fields, method parameters, or collection elements.
+- Use `Optional.empty()` over `null`. Use `Optional.ofNullable()` at boundaries.
+
+## Streams
+- Use streams for transformations: `filter`, `map`, `collect`.
+- Avoid side effects in stream operations. Keep them pure.
+- Use `Collectors.toUnmodifiableList()` for immutable results.
+- Prefer `for` loop for simple iterations that do not transform data.
+- Use `Stream.of()` or `IntStream.range()` for generating sequences.
+
+## Dependency Injection
+- Use constructor injection exclusively. No field or setter injection.
+- Accept interfaces in constructors, not implementations.
+- Use `@Component`, `@Service`, `@Repository` for Spring-managed beans.
+- Keep the number of constructor dependencies under 5. Split if more.
+
+## Concurrency
+- Use `ExecutorService` and `CompletableFuture` for async operations.
+- Use `virtual threads` (Java 21+) for I/O-bound concurrent work.
+- Use `ConcurrentHashMap`, `AtomicInteger` for thread-safe operations.
+- Avoid `synchronized` blocks when possible -- use higher-level concurrency.
+- Use `ReentrantReadWriteLock` for read-heavy shared state.
+
+## Design Patterns
+- Use Strategy pattern (via interfaces) over switch/if-else chains.
+- Use Factory methods for flexible object creation.
+- Use Decorator pattern for composable behavior augmentation.
+- Avoid Singleton pattern -- use DI container for lifecycle management.
+
+## Anti-Patterns
+- Returning `null` from methods -- use `Optional` or empty collections.
+- Mutable DTOs with getters/setters -- use records.
+- God classes with 20+ dependencies -- split by responsibility.
+- String typing for domain values -- use types, enums, or value objects.

package/app/rules/java/security.md

@@ -0,0 +1,60 @@
+---
+language: java
+category: security
+version: "1.0.0"
+---
+
+# Java Security
+
+## Input Validation
+- Validate all input with Jakarta Bean Validation (`@NotNull`, `@Size`, `@Email`).
+- Use `@Valid` on controller parameters to trigger validation automatically.
+- Create custom validators for domain-specific rules.
+- Never trust client-provided IDs. Verify resource ownership server-side.
+
+## SQL Injection
+- Use JPA/Hibernate parameterized queries. Never concatenate input into JPQL/SQL.
+- Use `CriteriaBuilder` or Specifications for dynamic queries.
+- For native queries, use named parameters: `@Query(value = "... WHERE id = :id", nativeQuery = true)`.
+- Use `PreparedStatement` if using JDBC directly. Never `Statement` with concatenation.
+
+## Authentication
+- Use Spring Security with BCrypt (`BCryptPasswordEncoder`) for password hashing.
+- Use JWT with short expiration (15 min) + refresh tokens for APIs.
+- Implement account lockout after N failed attempts.
+- Use `@AuthenticationPrincipal` to access the current user in controllers.
+
+## Authorization
+- Use `@PreAuthorize("hasRole('ADMIN')")` for role-based access control.
+- Use method security for fine-grained authorization.
+- Check resource ownership in service layer, not just role membership.
+- Default deny: require explicit authorization for every endpoint.
+
+## XSS and CSRF
+- Spring auto-escapes Thymeleaf output. Do not use `th:utext` with user data.
+- Enable CSRF protection for session-based auth. Disable only for stateless JWT APIs.
+- Set `Content-Type` headers explicitly on responses.
+- Use CSP headers to restrict script sources.
+
+## Serialization
+- Do not deserialize untrusted data with `ObjectInputStream` (RCE risk).
+- Use Jackson with `@JsonIgnoreProperties(ignoreUnknown = true)`.
+- Disable default typing in Jackson: never use `enableDefaultTyping()`.
+- Validate deserialized objects with Bean Validation after parsing.
+
+## Dependencies
+- Run OWASP Dependency-Check in CI: `mvn verify -P owasp-check`.
+- Update Spring Boot regularly -- security patches are frequent.
+- Use `dependencyManagement` to control transitive dependency versions.
+- Audit `mvn dependency:tree` for unexpected transitive dependencies.
+
+## Secrets
+- Use Spring Cloud Config or Vault for secrets management.
+- Use `@Value("${secret}")` with env var placeholders, not hardcoded values.
+- Never log request headers containing `Authorization` or session tokens.
+- Use separate config profiles for dev/staging/prod with different secrets.
+
+## Logging Security
+- Use parameterized logging to prevent log injection.
+- Sanitize user input before logging: remove newlines and control characters.
+- Never log stack traces to API responses. Return generic error messages.

package/app/rules/java/testing.md

@@ -0,0 +1,55 @@
+---
+language: java
+category: testing
+version: "1.0.0"
+---
+
+# Java Testing
+
+## Framework
+- Use JUnit 5 (Jupiter) for all new tests. No JUnit 4.
+- Use AssertJ for fluent, readable assertions.
+- Use Mockito for mocking dependencies.
+- Use Testcontainers for integration tests with databases/services.
+
+## File Naming
+- Test classes: `FooTest.java` in `src/test/java/` mirroring source package.
+- Integration tests: `FooIT.java` or use `@Tag("integration")`.
+- Test utilities: `src/test/java/.../support/` or `TestUtils.java`.
+
+## Structure
+- Use `@Nested` classes to group related tests within a test class.
+- Use `@DisplayName` for human-readable test descriptions.
+- Use `@BeforeEach` for setup, `@AfterEach` for cleanup.
+- Use `@ParameterizedTest` with `@ValueSource`, `@CsvSource`, `@MethodSource`.
+
+## Assertions (AssertJ)
+- Use `assertThat(actual).isEqualTo(expected)` over JUnit assertions.
+- Use `assertThatThrownBy(() -> ...).isInstanceOf(FooException.class)`.
+- Use `assertThat(list).hasSize(3).extracting("name").contains("Ada")`.
+- Chain assertions for readable, self-documenting tests.
+
+## Mocking (Mockito)
+- Use `@Mock` + `@ExtendWith(MockitoExtension.class)` for injection.
+- Use `when().thenReturn()` for stubbing. `verify()` for interaction checking.
+- Use `@InjectMocks` to auto-inject mocks into the class under test.
+- Prefer constructor injection in production code for testability.
+- Use `ArgumentCaptor` to inspect complex arguments.
+
+## Integration Testing
+- Use Testcontainers for PostgreSQL, Redis, Kafka, etc.
+- Use `@SpringBootTest` sparingly -- it starts the full context. Prefer slices.
+- Use `@WebMvcTest` for controller tests, `@DataJpaTest` for repository tests.
+- Use `@TestConfiguration` for test-specific bean overrides.
+
+## Test Data
+- Use test builders or factory methods for creating test objects.
+- Use `@Sql` annotation to load test data from SQL files.
+- Keep test data minimal. Only set fields relevant to the behavior under test.
+- Use random UUIDs for IDs in tests to avoid collision.
+
+## Performance
+- Run tests in parallel: configure `junit.jupiter.execution.parallel.enabled=true`.
+- Use `@SpringBootTest` only when integration context is needed.
+- Mock external dependencies in unit tests for speed.
+- Keep the full test suite under 5 minutes.

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

@@ -0,0 +1,56 @@
+---
+language: kotlin
+category: coding-style
+version: "1.0.0"
+---
+
+# Kotlin Coding Style
+
+## Naming
+- PascalCase: classes, interfaces, objects, type aliases, enum entries.
+- camelCase: functions, properties, local variables, parameters.
+- UPPER_SNAKE: compile-time constants (`const val`), top-level `val` constants.
+- Backing properties: prefix with `_` (`private val _items`, `val items: List<T>`).
+- Package names: lowercase, no underscores (`com.company.project.feature`).
+
+## Null Safety
+- Use nullable types only when nullability is semantically meaningful.
+- Prefer `?.let { }`, `?:` (Elvis), and safe calls over `!!`.
+- Never use `!!` except in tests or when null is truly impossible.
+- Use `requireNotNull()` and `require()` for preconditions at public API boundaries.
+- Use `checkNotNull()` and `check()` for state assertions.
+
+## Data Classes
+- Use `data class` for DTOs, value objects, and state containers.
+- Use `copy()` for immutable updates. Avoid mutable `var` in data classes.
+- Use `sealed class` / `sealed interface` for restricted hierarchies.
+- Use `value class` (inline class) for type-safe wrappers with zero overhead.
+- Use `object` for singletons and namespace-like utility groupings.
+
+## Functions
+- Use expression body (`= expr`) for single-expression functions.
+- Use named arguments for functions with >2 parameters of the same type.
+- Use default parameter values instead of overloaded functions.
+- Use extension functions to add behavior without inheritance.
+- Use `suspend` functions for async operations, not callbacks.
+
+## Collections
+- Prefer `listOf`, `mapOf`, `setOf` (immutable) over `mutableListOf`.
+- Use collection operators: `map`, `filter`, `groupBy`, `associate`.
+- Use `sequence {}` for lazy evaluation on large collections.
+- Prefer `firstOrNull()` over `first()` for safe access.
+- Use destructuring: `val (name, age) = user`.
+
+## Scope Functions
+- `let`: null-safe chaining and local scoping.
+- `apply`: configure object after creation.
+- `also`: side effects (logging, validation) in chains.
+- `run`: compute a result using receiver's context.
+- `with`: multiple operations on an object without chaining.
+- Avoid nesting scope functions more than 1 level deep.
+
+## Formatting
+- Use ktlint or detekt for automated formatting and linting.
+- Use trailing commas in multi-line parameter/argument lists.
+- Max line length: 120 characters (Kotlin convention).
+- Use `when` expression over if-else chains for 3+ branches.

package/app/rules/kotlin/frameworks.md

@@ -0,0 +1,54 @@
+---
+language: kotlin
+category: frameworks
+version: "1.0.0"
+---
+
+# Kotlin Frameworks
+
+## Ktor (Server)
+- Use routing DSL: `routing { get("/users") { call.respond(users) } }`.
+- Use `install()` for plugins: ContentNegotiation, Authentication, CORS.
+- Use `call.receive<T>()` for typed request body parsing with kotlinx.serialization.
+- Use `StatusPages` plugin for centralized error handling.
+- Use `Routing` with nested `route("/api/v1") { }` blocks for URL grouping.
+
+## Ktor (Client)
+- Use `HttpClient` with engine configuration (CIO, OkHttp, Apache).
+- Use `install(ContentNegotiation) { json() }` for JSON serialization.
+- Use `client.get<T>()` with reified type for typed responses.
+- Use `HttpTimeout` plugin for connection and request timeouts.
+- Close `HttpClient` when done or use DI lifecycle management.
+
+## Spring Boot (Kotlin)
+- Use constructor injection (Kotlin classes are `final` by default).
+- Apply `kotlin-spring` plugin for open classes (required for proxying).
+- Use `@ConfigurationProperties` with data classes for typed config.
+- Use `WebFlux` with coroutines: `coRouter { }` and `suspend` handler functions.
+- Use `spring-boot-starter-validation` with `@Valid` on Kotlin data classes.
+
+## Exposed (ORM)
+- Use DSL API for type-safe queries: `Users.select { Users.name eq "Ada" }`.
+- Use DAO API for Active Record-style: `User.find { Users.age greaterEq 18 }`.
+- Wrap database operations in `transaction { }` blocks.
+- Use `SchemaUtils.create(Users)` for schema management in development.
+
+## kotlinx.serialization
+- Use `@Serializable` annotation on data classes for compile-time serialization.
+- Use `@SerialName("field_name")` for JSON field name mapping.
+- Use `Json { ignoreUnknownKeys = true }` for lenient deserialization.
+- Use polymorphic serialization with `sealed class` and `@Polymorphic`.
+- Prefer `kotlinx.serialization` over Jackson for pure Kotlin projects.
+
+## Koin (DI)
+- Define modules: `module { single { UserService(get()) } }`.
+- Use `by inject<T>()` for lazy injection in Android/Ktor.
+- Use `factory { }` for new instance per injection, `single { }` for singleton.
+- Use `checkModules()` in tests to verify DI graph completeness.
+
+## Compose (Multiplatform UI)
+- Use `@Composable` functions for UI components. Keep them stateless.
+- Use `remember { }` and `mutableStateOf()` for local state.
+- Hoist state to callers: pass state down, events up.
+- Use `LaunchedEffect` for side effects tied to composition lifecycle.
+- Use `ViewModel` with `StateFlow` for screen-level state management.

package/app/rules/kotlin/patterns.md

@@ -0,0 +1,54 @@
+---
+language: kotlin
+category: patterns
+version: "1.0.0"
+---
+
+# Kotlin Patterns
+
+## Error Handling
+- Use `Result<T>` for operations that can fail without exceptions.
+- Use `runCatching { }` to wrap exception-throwing code into `Result`.
+- Use `sealed class` hierarchies for domain errors: `sealed class AppError`.
+- Prefer `fold()`, `getOrElse()`, `getOrNull()` over `getOrThrow()`.
+- Use `require()` / `check()` for preconditions; they throw `IllegalArgumentException` / `IllegalStateException`.
+
+## Coroutines
+- Use `suspend` functions for sequential async operations.
+- Use `coroutineScope { }` for structured concurrency with parallel work.
+- Use `async { }` + `await()` for concurrent independent operations.
+- Use `supervisorScope { }` when child failures should not cancel siblings.
+- Use `withContext(Dispatchers.IO)` for blocking I/O in coroutine context.
+- Use `flow { }` for cold asynchronous streams. Collect in lifecycle-aware scope.
+
+## Flow Patterns
+- Use `stateIn()` and `shareIn()` to convert cold flows to hot shared state.
+- Use `combine()` to merge multiple flows into derived state.
+- Use `flatMapLatest` for search-as-you-type patterns (cancel previous).
+- Use `catch { }` operator for upstream error handling in flows.
+- Use `flowOn(Dispatchers.IO)` to shift upstream execution context.
+
+## Sealed Hierarchies
+- Use `sealed interface` over `sealed class` when no shared state is needed.
+- Use `when` expressions exhaustively on sealed types (compiler-enforced).
+- Combine sealed types with data classes for typed state machines.
+- Use sealed hierarchies for API responses: `Success<T>`, `Error`, `Loading`.
+
+## Delegation
+- Use `by lazy { }` for thread-safe lazy initialization.
+- Use `by map` for delegated properties backed by a `Map`.
+- Use class delegation (`class Foo : Bar by impl`) to favor composition.
+- Use `observable` / `vetoable` delegates for reactive property changes.
+
+## Builder Patterns
+- Use DSL-style builders with `@DslMarker` annotation to prevent scope leakage.
+- Use trailing lambda syntax for configuration blocks.
+- Use `apply { }` for inline object configuration without a dedicated builder.
+- Use `buildList { }`, `buildMap { }`, `buildString { }` for collection construction.
+
+## Anti-Patterns
+- Overusing `!!`: masks null-safety guarantees. Use safe calls or require.
+- Nesting scope functions: `foo.let { it.also { ... }.run { } }` -- flatten logic.
+- Blocking the main thread: use `withContext(Dispatchers.IO)` for I/O.
+- Using `GlobalScope.launch`: leaks coroutines. Use structured concurrency.
+- Mutable shared state without synchronization: use `Mutex` or `StateFlow`.

package/app/rules/kotlin/security.md

@@ -0,0 +1,62 @@
+---
+language: kotlin
+category: security
+version: "1.0.0"
+---
+
+# Kotlin Security
+
+## Input Validation
+- Validate all inputs at API boundaries using Bean Validation or manual checks.
+- Use `require()` for argument validation: `require(age > 0) { "Age must be positive" }`.
+- Use data class `init` blocks for domain validation on construction.
+- Never trust client-provided IDs. Verify resource ownership server-side.
+- Sanitize strings before using in HTML, SQL, or shell commands.
+
+## Null Safety as Security
+- Kotlin's null safety prevents null pointer exceptions. Do not circumvent with `!!`.
+- Use `?.` and `?:` chains for safe fallback values at boundaries.
+- Treat Java interop as untrusted: platform types can still be null.
+- Use `@Nullable` / `@NotNull` annotations on Java code consumed by Kotlin.
+
+## SQL Injection
+- Use Exposed DSL or JPA with parameterized queries. Never concatenate input.
+- Use `PreparedStatement` if writing raw JDBC.
+- Use `CriteriaBuilder` or Exposed conditions for dynamic query construction.
+- Audit `@Query(nativeQuery = true)` for parameter interpolation risks.
+
+## Serialization
+- Use `kotlinx.serialization` with `@Serializable` for compile-time safety.
+- Use `Json { ignoreUnknownKeys = true }` but validate after deserialization.
+- Never use Java `ObjectInputStream` for deserialization (RCE risk).
+- Restrict polymorphic deserialization to known sealed class subtypes.
+
+## Authentication
+- Use Spring Security or Ktor Authentication plugin. Do not roll your own.
+- Hash passwords with BCrypt or Argon2. Never store plaintext.
+- Use short-lived JWTs (15 min) with refresh token rotation.
+- Validate JWT signature, issuer, audience, and expiration on every request.
+
+## Coroutine Security
+- Use `withTimeout()` to prevent unbounded coroutine execution (DoS vector).
+- Use `Mutex` for critical sections. Do not use `synchronized` in suspend functions.
+- Propagate security context through `CoroutineContext` elements.
+- Cancel coroutine scopes on authentication failure or session expiry.
+
+## Secrets Management
+- Use environment variables or Vault for secrets. Never hardcode.
+- Use `@ConfigurationProperties` with injected secrets, not string literals.
+- Never log request headers containing Authorization tokens.
+- Use separate configuration profiles for dev/staging/prod secrets.
+
+## Dependencies
+- Use Dependabot or Renovate for automated dependency updates.
+- Run OWASP Dependency-Check or Gradle `dependencyCheckAnalyze`.
+- Audit transitive dependencies with `gradle dependencies`.
+- Pin dependency versions. Avoid dynamic versions like `1.+`.
+
+## Logging
+- Use parameterized logging: `logger.info("User {} logged in", userId)`.
+- Never log passwords, tokens, or PII.
+- Sanitize user input before logging to prevent log injection.
+- Use structured logging (JSON) for machine-parseable audit trails.