@softspark/ai-toolkit 1.2.0 → 1.3.0

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.

package/app/rules/kotlin/testing.md

@@ -0,0 +1,56 @@
+---
+language: kotlin
+category: testing
+version: "1.0.0"
+---
+
+# Kotlin Testing
+
+## Framework
+- Use JUnit 5 as the test runner.
+- Use Kotest for Kotlin-idiomatic BDD-style testing (alternative).
+- Use MockK for mocking (Kotlin-native, supports coroutines).
+- Use Testcontainers for integration tests with external services.
+
+## File Naming
+- Test files: `FooTest.kt` in `src/test/kotlin/` mirroring source package.
+- Integration tests: `FooIT.kt` or use `@Tag("integration")`.
+- Use `@Nested` inner classes to group related test cases.
+
+## Structure
+- Use `@DisplayName` for human-readable test names.
+- Use backtick function names for readable test names: `` `returns 404 when user not found` ``.
+- Use `@BeforeEach` for per-test setup. Avoid shared mutable state.
+- Use `@ParameterizedTest` with `@MethodSource` for table-driven tests.
+
+## MockK
+- Use `mockk<UserRepository>()` to create mocks.
+- Use `every { mock.find(any()) } returns user` for stubbing.
+- Use `coEvery { ... }` and `coVerify { ... }` for coroutine mocking.
+- Use `spyk()` for partial mocks on real objects.
+- Use `slot<T>()` and `captured` to inspect arguments.
+- Clear mocks in `@AfterEach` to prevent state leakage.
+
+## Coroutine Testing
+- Use `runTest { }` from `kotlinx-coroutines-test` for coroutine tests.
+- Use `TestDispatcher` to control coroutine execution timing.
+- Use `advanceUntilIdle()` to complete all pending coroutines.
+- Use `turbine` library for testing `Flow` emissions.
+
+## Assertions
+- Use AssertJ or Kotest assertions for fluent, readable checks.
+- Use `shouldBe`, `shouldThrow`, `shouldContain` (Kotest matchers).
+- Use `assertSoftly { }` to collect multiple assertion failures.
+- Use `assertThrows<FooException> { ... }` for exception testing.
+
+## Test Data
+- Use factory functions for test data: `fun aUser(name: String = "Ada") = User(...)`.
+- Use default parameters for minimal test data setup.
+- Use `copy()` on data classes for variations of base test objects.
+- Use `faker` library for realistic test data generation.
+
+## Spring Integration
+- Use `@SpringBootTest` with `@AutoConfigureMockMvc` for API tests.
+- Use `@WebMvcTest` for controller-only tests (faster).
+- Use `@MockkBean` instead of `@MockBean` for MockK integration.
+- Use `@Transactional` on test classes for automatic rollback.

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

@@ -0,0 +1,53 @@
+---
+language: php
+category: coding-style
+version: "1.0.0"
+---
+
+# PHP Coding Style
+
+## Standards
+- Follow PSR-12 extended coding style.
+- Use `declare(strict_types=1)` at the top of every file.
+- Use PHP 8.1+ features: enums, fibers, readonly properties, intersection types.
+- Use PHP CS Fixer or Pint for automated formatting.
+
+## Naming
+- PascalCase: classes, interfaces, traits, enums.
+- camelCase: methods, functions, variables.
+- UPPER_SNAKE: class constants (`public const MAX_RETRIES = 3`).
+- snake_case: not used for methods. PSR convention is camelCase.
+- Suffix interfaces with `Interface` or prefix with contract name (project convention).
+
+## Type System
+- Use typed properties: `private readonly string $name;`.
+- Use union types: `string|int`. Use intersection types: `Countable&Iterator`.
+- Use `enum` (PHP 8.1) for fixed sets of values. Use backed enums for persistence.
+- Use `readonly` classes (PHP 8.2) for immutable DTOs.
+- Use constructor promotion: `public function __construct(private string $name)`.
+- Use `never` return type for functions that throw or exit.
+
+## Functions
+- Use typed parameters and return types on all functions/methods.
+- Use named arguments for readability: `new User(name: 'Ada', age: 36)`.
+- Use null-safe operator: `$user?->address?->city`.
+- Use match expression over switch for value mapping.
+- Use first-class callable syntax: `array_map($this->transform(...), $items)`.
+
+## Imports and Namespaces
+- Use PSR-4 autoloading via Composer.
+- Group `use` statements: classes, functions, constants.
+- Never use `require`/`include` for class loading. Use Composer autoloader.
+- Use one class per file. File name matches class name.
+
+## Error Handling
+- Use exceptions for error conditions. Never return error codes.
+- Create domain exception hierarchies extending `RuntimeException` or `LogicException`.
+- Use `match` with `throw` for exhaustive error mapping.
+- Log exceptions with context using PSR-3 logger.
+
+## Configuration
+- Use PHPStan at level 8+ for static analysis.
+- Use Rector for automated code upgrades and refactoring.
+- Use `.php-cs-fixer.dist.php` for formatting rules.
+- Run `composer analyse` (PHPStan) and `composer format` (Pint) in CI.

package/app/rules/php/frameworks.md

@@ -0,0 +1,57 @@
+---
+language: php
+category: frameworks
+version: "1.0.0"
+---
+
+# PHP Frameworks
+
+## Laravel
+- Use route model binding: `Route::get('/users/{user}', ...)`.
+- Use Form Requests for validation: `class StoreUserRequest extends FormRequest`.
+- Use Eloquent scopes for reusable query constraints: `scopeActive()`.
+- Use API Resources for response transformation: `UserResource::collection($users)`.
+- Use `config()` helper for configuration. Never access `env()` outside config files.
+- Use middleware groups for auth, throttling, and CORS.
+
+## Eloquent ORM
+- Use relationships: `hasMany`, `belongsTo`, `belongsToMany`, `morphMany`.
+- Use eager loading: `User::with('posts.comments')->get()` to prevent N+1.
+- Use `$fillable` or `$guarded` on models. Prefer `$fillable` (explicit whitelist).
+- Use model events or observers for lifecycle hooks.
+- Use `upsert()` for bulk insert-or-update operations.
+- Use `cursor()` for memory-efficient iteration over large result sets.
+
+## Symfony
+- Use attributes for route definitions: `#[Route('/api/users', methods: ['GET'])]`.
+- Use autowiring for dependency injection. Register services in `services.yaml`.
+- Use Symfony Forms for complex validation and data mapping.
+- Use Messenger component for async message handling (commands, events).
+- Use Doctrine ORM with repository pattern and query builders.
+
+## Doctrine ORM
+- Use entity classes with annotations or attributes for mapping.
+- Use repositories for data access: `$em->getRepository(User::class)`.
+- Use DQL for type-safe queries. Use QueryBuilder for dynamic queries.
+- Use migrations: `bin/console doctrine:migrations:diff` and `migrate`.
+- Use lifecycle callbacks (`@PrePersist`, `@PostUpdate`) for entity events.
+
+## API Platform
+- Use API Platform for rapid REST/GraphQL API generation from entities.
+- Use `#[ApiResource]` attribute for automatic CRUD endpoint generation.
+- Use custom state providers and processors for business logic.
+- Use serialization groups for controlling response shape.
+- Use filters for query parameter support: pagination, search, ordering.
+
+## Livewire (Laravel)
+- Use Livewire components for reactive UI without JavaScript.
+- Use `wire:model` for two-way data binding on form inputs.
+- Use `$rules` property for inline validation on component properties.
+- Use component actions for server-side event handling.
+- Use `wire:loading` for loading state indicators.
+
+## Queues and Workers
+- Use Laravel Horizon for Redis queue monitoring and management.
+- Use Symfony Messenger with transports (Redis, AMQP, Doctrine).
+- Use dead letter queues for failed job inspection and replay.
+- Use rate limiting on queue workers to prevent downstream overload.

package/app/rules/php/patterns.md

@@ -0,0 +1,63 @@
+---
+language: php
+category: patterns
+version: "1.0.0"
+---
+
+# PHP Patterns
+
+## Error Handling
+- Use custom exception hierarchies: `class DomainException extends RuntimeException`.
+- Add context to exceptions: `throw new UserNotFoundException(userId: $id)`.
+- Use `match` with `default => throw` for exhaustive error mapping.
+- Use `set_exception_handler()` for global uncaught exception handling.
+- Log exceptions with PSR-3 logger and structured context.
+
+## Enums and Value Objects
+- Use backed enums for database-persisted values: `enum Status: string`.
+- Use `from()` for strict conversion, `tryFrom()` for nullable safe conversion.
+- Implement methods on enums for behavior: `public function label(): string`.
+- Use readonly classes for value objects: `readonly class Money { ... }`.
+- Use constructor promotion for concise value object definitions.
+
+## Repository Pattern
+- Abstract data access behind repository interfaces.
+- Repositories return domain entities, not Eloquent models or arrays.
+- Use constructor injection for repository dependencies.
+- Use specifications or criteria objects for complex query building.
+- Keep repository methods focused: one query per method.
+
+## Service Layer
+- Use service classes for business logic. Keep controllers thin.
+- Use action classes (single-method services) for discrete operations.
+- Use DTOs for data transfer between layers. Never pass request objects to services.
+- Use command/query separation: commands mutate, queries read.
+- Inject dependencies via constructor. Never use `app()` helper in services.
+
+## Collections and Iterators
+- Use Laravel Collections or standalone `illuminate/collections` for data manipulation.
+- Chain `map()`, `filter()`, `reduce()` for declarative data transformation.
+- Use `LazyCollection` for memory-efficient processing of large datasets.
+- Use generators (`yield`) for lazy iteration over large result sets.
+- Prefer `collect()` pipeline over nested loops.
+
+## Async Patterns
+- Use Laravel Queues for background job processing.
+- Use `dispatch()` for fire-and-forget. Use `Bus::chain()` for sequential jobs.
+- Use `ShouldQueue` interface on jobs, listeners, and mailables.
+- Set `$tries`, `$timeout`, `$backoff` on job classes.
+- Use `batch()` for parallel job execution with completion callback.
+
+## Event-Driven
+- Use events and listeners for decoupled side effects.
+- Use domain events for cross-boundary communication.
+- Use `ShouldQueue` on listeners for async event handling.
+- Use event subscribers for grouping related listeners.
+- Keep event payloads minimal: IDs and timestamps, not full objects.
+
+## Anti-Patterns
+- Fat controllers: move logic to services/actions.
+- God models: split into focused models with traits or separate classes.
+- Using `DB::raw()` without parameterization: SQL injection risk.
+- Static method calls for testable dependencies: use DI instead.
+- Returning mixed types: use typed returns or Result objects.

package/app/rules/php/security.md

@@ -0,0 +1,61 @@
+---
+language: php
+category: security
+version: "1.0.0"
+---
+
+# PHP Security
+
+## SQL Injection
+- Use PDO prepared statements with bound parameters for all queries.
+- Use Eloquent/Doctrine ORM for type-safe query building.
+- Never concatenate user input into SQL strings. Never use `DB::raw($input)`.
+- Use `whereIn()` with arrays, not string interpolation for IN clauses.
+- Audit raw queries: `DB::select(DB::raw(...))` must use `?` placeholders.
+
+## XSS Prevention
+- Blade templates auto-escape with `{{ }}`. Never use `{!! !!}` with user data.
+- Use `htmlspecialchars()` with `ENT_QUOTES` when outputting outside Blade.
+- Set `Content-Security-Policy` headers to restrict inline scripts.
+- Sanitize rich-text input with HTMLPurifier before storage.
+- Use `strip_tags()` only as a secondary measure, not primary defense.
+
+## CSRF Protection
+- Use `@csrf` directive in all Blade forms.
+- Use `VerifyCsrfToken` middleware (enabled by default in Laravel).
+- Use `X-CSRF-TOKEN` header for AJAX requests from SPA frontends.
+- Exclude only webhook endpoints from CSRF verification (with careful validation).
+
+## Authentication
+- Use `password_hash()` with `PASSWORD_ARGON2ID` or `PASSWORD_BCRYPT`.
+- Use Laravel Sanctum for SPA/mobile API authentication.
+- Use Laravel Passport for full OAuth2 server implementation.
+- Implement rate limiting on login endpoints: `ThrottleRequests` middleware.
+- Use multi-factor authentication for admin accounts.
+
+## Authorization
+- Use Laravel Gates and Policies for authorization logic.
+- Use `$this->authorize('update', $post)` in controllers.
+- Check resource ownership in policies, not just role membership.
+- Default deny: use `Gate::before()` for super-admin bypass, nothing else.
+- Use middleware `can:permission` for route-level authorization.
+
+## File Upload
+- Validate file MIME type server-side. Do not trust `Content-Type` header.
+- Store uploads outside the web root. Use `storage/` with `Storage::disk()`.
+- Generate random filenames. Never use original user-provided filenames.
+- Set maximum file size limits in validation and PHP `upload_max_filesize`.
+- Scan uploaded files for malware in production environments.
+
+## Mass Assignment
+- Use `$fillable` on Eloquent models. Never use `$guarded = []`.
+- Use Form Requests to whitelist fields before model assignment.
+- Use DTOs for data transfer. Never pass `$request->all()` to `create()`.
+- Audit `forceFill()` and `forceCreate()` usage (bypasses guarding).
+
+## Secrets and Configuration
+- Use `.env` files for local secrets. Use Vault or SSM for production.
+- Never commit `.env` to version control. Commit `.env.example` as template.
+- Use `config()` helper, never `env()` outside of config files (caching issue).
+- Never log request content containing passwords or tokens.
+- Use `APP_DEBUG=false` in production. Debug mode leaks sensitive data.

package/app/rules/php/testing.md

@@ -0,0 +1,60 @@
+---
+language: php
+category: testing
+version: "1.0.0"
+---
+
+# PHP Testing
+
+## Framework
+- Use PHPUnit 10+ as the primary test framework.
+- Use Pest PHP for expressive, minimal-boilerplate testing (built on PHPUnit).
+- Use Mockery for flexible mocking. Use PHPUnit built-in mocks for simple cases.
+- Use Testcontainers (via Docker) for integration tests with databases.
+
+## File Naming
+- Test files: `FooTest.php` in `tests/` mirroring `src/` namespace structure.
+- Unit tests: `tests/Unit/`. Integration tests: `tests/Integration/` or `tests/Feature/`.
+- PHPUnit config: `phpunit.xml.dist` at project root.
+- Use `@group` annotations for test categorization.
+
+## Structure (PHPUnit)
+- Use `#[Test]` attribute (PHP 8) or `test` prefix for test methods.
+- Use `setUp()` / `tearDown()` for per-test initialization and cleanup.
+- Use `#[DataProvider('dataMethodName')]` for parameterized tests.
+- Name tests: `testMethodName_Scenario_ExpectedResult` or descriptive snake_case.
+
+## Structure (Pest)
+- Use `test('description', function () { ... })` for test cases.
+- Use `it('should do something', ...)` for BDD-style descriptions.
+- Use `beforeEach()` / `afterEach()` for setup and teardown.
+- Use `dataset()` for shared test data across multiple tests.
+- Use `->with([...])` for inline parameterized tests.
+
+## Assertions
+- Use `$this->assertSame()` for strict equality (type + value).
+- Use `$this->assertInstanceOf(Foo::class, $result)` for type checks.
+- Use `$this->expectException(FooException::class)` before the throwing call.
+- Use `$this->assertCount()`, `$this->assertContains()` for collections.
+- Pest: use `expect($value)->toBe()`, `->toBeInstanceOf()`, `->toThrow()`.
+
+## Mocking (Mockery)
+- Create mocks: `$mock = Mockery::mock(UserRepository::class)`.
+- Stub: `$mock->shouldReceive('find')->with(1)->andReturn($user)`.
+- Verify: `$mock->shouldHaveReceived('save')->once()`.
+- Use `Mockery::close()` in `tearDown()` or `afterEach()`.
+- Use `spy()` to verify interactions without stubbing.
+
+## Laravel Testing
+- Use `RefreshDatabase` trait for database test isolation.
+- Use `$this->actingAs($user)` for authenticated request testing.
+- Use `$this->getJson('/api/users')->assertOk()->assertJsonCount(3)`.
+- Use factories: `User::factory()->create()` for test data.
+- Use `Bus::fake()`, `Event::fake()`, `Mail::fake()` for side-effect assertion.
+
+## Best Practices
+- Test behavior, not implementation. Do not test private methods.
+- Use in-memory SQLite for fast database tests when schema is compatible.
+- Run `php artisan test --parallel` for faster Laravel test execution.
+- Use `--coverage-html` for visual coverage reports.
+- Keep tests fast: mock external HTTP calls with `Http::fake()`.

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

@@ -0,0 +1,52 @@
+---
+language: python
+category: coding-style
+version: "1.0.0"
+---
+
+# Python Coding Style
+
+## Type Hints
+- Type all public function signatures (parameters + return).
+- Use `str | None` (PEP 604) over `Optional[str]` on Python 3.10+.
+- Use `from __future__ import annotations` for forward references.
+- Use `TypeAlias` or `type` (3.12+) for complex type aliases.
+- Use `Protocol` for structural subtyping instead of ABCs where possible.
+
+## Naming
+- snake_case: variables, functions, methods, modules.
+- PascalCase: classes, type aliases, Protocols.
+- UPPER_SNAKE: module-level constants.
+- Prefix private: `_internal_helper`. No double underscore unless name mangling needed.
+- Prefix unused: `_` for intentionally unused variables.
+
+## Functions
+- Prefer keyword arguments for functions with >2 params.
+- Use `*` to force keyword-only: `def fetch(*, limit: int, offset: int)`.
+- Return early to reduce nesting. Avoid deep if/else chains.
+- Use `@staticmethod` only for pure utility. Prefer module-level functions.
+
+## Imports
+- Group: stdlib, third-party, local. Separated by blank lines.
+- Use absolute imports. Relative imports only within packages.
+- Never `from module import *`. Be explicit.
+- Use `if TYPE_CHECKING:` for import-only-for-types to avoid circular imports.
+
+## Data Structures
+- Use `dataclasses` for plain data containers.
+- Use Pydantic `BaseModel` for validated data / API schemas.
+- Use `NamedTuple` for lightweight immutable records.
+- Use `Enum` for fixed sets of values. Prefer `StrEnum` on 3.11+.
+- Prefer `dict` / `list` literals over `dict()` / `list()` constructors.
+
+## Modern Python
+- Use f-strings for formatting. Never `.format()` or `%` for new code.
+- Use `pathlib.Path` over `os.path` for file operations.
+- Use `contextlib.suppress(KeyError)` over bare try/except for simple cases.
+- Use walrus operator `:=` when it genuinely improves readability.
+- Use `match/case` (3.10+) for complex conditionals on structured data.
+
+## Tooling
+- Formatter: `ruff format` or `black`. No manual formatting.
+- Linter: `ruff check`. Fix all errors before committing.
+- Type checker: `mypy --strict` or `pyright` in CI.

package/app/rules/python/frameworks.md

@@ -0,0 +1,53 @@
+---
+language: python
+category: frameworks
+version: "1.0.0"
+---
+
+# Python Frameworks
+
+## FastAPI
+- Use Pydantic v2 models for request/response schemas.
+- Use dependency injection (`Depends()`) for shared logic (auth, DB sessions).
+- Use `APIRouter` to organize routes by domain.
+- Return Pydantic models directly -- FastAPI handles serialization.
+- Use `BackgroundTasks` for non-critical async work (emails, logging).
+- Use `lifespan` context manager for startup/shutdown (not `on_event`).
+
+## Django
+- Use class-based views for CRUD, function-based for custom logic.
+- Use `select_related` and `prefetch_related` to prevent N+1 queries.
+- Use Django REST Framework serializers for API validation.
+- Use Django ORM migrations. Never modify database schema manually.
+- Use `transaction.atomic()` for multi-model operations.
+- Use signals sparingly: prefer explicit service calls.
+
+## SQLAlchemy 2.0
+- Use the 2.0-style with `select()` statements, not legacy `query()`.
+- Use `Mapped[type]` annotations for typed column definitions.
+- Use `sessionmaker` with `expire_on_commit=False` for API responses.
+- Use `async_sessionmaker` with `asyncpg` for async applications.
+- Always use `session.begin()` context manager for transaction scope.
+
+## Pydantic v2
+- Use `model_validator(mode="before")` for cross-field validation.
+- Use `field_validator` for single-field validation.
+- Use `model_config = ConfigDict(strict=True)` for strict type coercion.
+- Use `Annotated[str, Field(min_length=1)]` for reusable constrained types.
+- Use `model_dump(exclude_unset=True)` for PATCH operations.
+
+## CLI (click / typer)
+- Use Typer for new CLI tools (type-hint-driven, less boilerplate).
+- Use `click.group()` for multi-command CLIs.
+- Use `rich` for formatted terminal output (tables, progress bars).
+
+## Task Queues
+- Use Celery with Redis/RabbitMQ for background job processing.
+- Use `arq` for lightweight async job queues.
+- Always set task timeouts. Never let tasks run indefinitely.
+- Use idempotent tasks: safe to retry on failure.
+
+## Package Management
+- Use `uv` for fast dependency resolution and virtual environments.
+- Use `pyproject.toml` for all project configuration (no setup.py/setup.cfg).
+- Pin dependencies with lockfile (`uv.lock`, `poetry.lock`).

package/app/rules/python/patterns.md

@@ -0,0 +1,53 @@
+---
+language: python
+category: patterns
+version: "1.0.0"
+---
+
+# Python Patterns
+
+## Error Handling
+- Catch specific exceptions, never bare `except:` or `except Exception`.
+- Use custom exception hierarchies: `class AppError(Exception)` as base.
+- Add context when re-raising: `raise AppError("context") from original`.
+- Use `contextlib.suppress()` for expected, ignorable exceptions.
+- Log exceptions with `logger.exception("msg")` to include traceback.
+
+## Context Managers
+- Use `with` for any resource that needs cleanup (files, connections, locks).
+- Create custom context managers with `@contextmanager` decorator.
+- Use `contextlib.AsyncExitStack` for dynamic async resource management.
+- Use `atexit.register()` for process-level cleanup only.
+
+## Async
+- Use `asyncio` for I/O-bound concurrency. Use `multiprocessing` for CPU-bound.
+- Use `asyncio.gather()` for concurrent independent operations.
+- Use `asyncio.TaskGroup` (3.11+) for structured concurrency.
+- Never mix `asyncio.run()` inside already-running event loops.
+- Use `async for` and `async with` for streaming and resource patterns.
+
+## Dataclass Patterns
+- Use `frozen=True` for immutable value objects.
+- Use `field(default_factory=list)` for mutable defaults, never `field(default=[])`.
+- Use `__post_init__` for validation, not complex logic.
+- Use `slots=True` (3.10+) for memory efficiency in high-volume objects.
+
+## Functional Patterns
+- Use `functools.lru_cache` for pure function memoization.
+- Use `itertools` for efficient iteration (chain, islice, groupby).
+- Use generators (`yield`) for lazy sequences and large data processing.
+- Prefer comprehensions over `map/filter` with lambdas.
+- Use `functools.partial` to create specialized versions of functions.
+
+## Dependency Injection
+- Use constructor injection: pass dependencies as `__init__` params.
+- Use `Protocol` classes to define dependency interfaces.
+- Use factory functions to wire dependencies at application startup.
+- Avoid global state and singletons. Use module-level instances if needed.
+
+## Anti-Patterns
+- Mutable default arguments: use `None` and create inside function.
+- Catching `Exception` broadly: masks bugs and interrupts.
+- Using `type()` for type checking: use `isinstance()`.
+- Nested try/except: flatten with early returns or separate functions.
+- Using `global` keyword: pass state through parameters or classes.

package/app/rules/python/security.md

@@ -0,0 +1,58 @@
+---
+language: python
+category: security
+version: "1.0.0"
+---
+
+# Python Security
+
+## Input Validation
+- Validate all input with Pydantic models at API boundaries.
+- Use `constr`, `conint`, `conlist` for constrained types.
+- Never use `eval()`, `exec()`, or `compile()` with user input.
+- Never use `pickle.loads()` on untrusted data (arbitrary code execution).
+
+## SQL Injection
+- Use ORM query builders (SQLAlchemy, Django ORM) for all queries.
+- For raw SQL, always use parameterized queries: `cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,))`.
+- Never use f-strings or `.format()` to build SQL queries.
+- Use `text()` with `:param` syntax in SQLAlchemy raw queries.
+
+## SSTI (Server-Side Template Injection)
+- Use Jinja2 with autoescaping enabled: `Environment(autoescape=True)`.
+- Never render user input as a template string.
+- Use `markupsafe.Markup` only for trusted HTML content.
+
+## Command Injection
+- Never use `os.system()` or `subprocess.run(shell=True)` with user input.
+- Use `subprocess.run()` with list arguments: `subprocess.run(["ls", "-la", path])`.
+- Use `shlex.quote()` if shell=True is absolutely necessary.
+
+## Path Traversal
+- Use `pathlib.Path.resolve()` and verify the result is within allowed directory.
+- Never concatenate user input into file paths without validation.
+- Use `os.path.commonpath()` to verify path containment.
+
+## Secrets
+- Use `secrets` module for tokens: `secrets.token_urlsafe(32)`.
+- Use `hashlib.scrypt` or `bcrypt` for password hashing.
+- Use `hmac.compare_digest()` for constant-time secret comparison.
+- Load secrets from environment: `os.environ["SECRET_KEY"]`, never hardcode.
+
+## Dependencies
+- Run `pip-audit` or `safety check` in CI.
+- Use `uv` or `pip-compile` for reproducible dependency resolution.
+- Avoid installing packages with native extensions from untrusted sources.
+- Pin all dependency versions. Review dependency updates carefully.
+
+## Deserialization
+- Never deserialize untrusted data with `pickle`, `yaml.load()`, or `marshal`.
+- Use `yaml.safe_load()` instead of `yaml.load()`.
+- Use `json.loads()` for untrusted data (safe by default).
+- Validate deserialized data with Pydantic before use.
+
+## Django-Specific
+- Set `DEBUG = False` in production. Never expose debug pages.
+- Use `django.utils.html.escape()` for manual HTML escaping.
+- Use `CSRF_COOKIE_HTTPONLY = True` and `SESSION_COOKIE_SECURE = True`.
+- Keep `SECRET_KEY` unique per environment and out of version control.