@deftai/directive-content 0.55.0

package/languages/csharp.md

@@ -0,0 +1,259 @@
+# C# Standards
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**⚠️ See also**: [main.md](../../main.md) | [PROJECT.md](../../PROJECT.md) | [telemetry.md](../tools/telemetry.md)
+
+**Stack**: C# 12+/.NET 8+ (LTS), SDK-style projects; Web: ASP.NET Core/Minimal APIs; Testing: xUnit + NSubstitute + FluentAssertions; Analysis: Roslyn Analyzers, StyleCop.Analyzers
+
+## Standards
+
+### Documentation
+- ! XML documentation comments (`///`) on all public types, methods, properties, and constants
+- ! Document `<param>`, `<returns>`, `<exception>`, `<summary>` for public/protected members
+- ~ Use `<see cref=""/>` and `<inheritdoc/>` to reduce duplication
+- ~ Use `<remarks>` for complex behaviors or threading considerations
+
+### Testing
+See [testing.md](../coding/testing.md).
+
+- ! Use xUnit (`[Fact]`, `[Theory]`, `[InlineData]`)
+- ! Use NSubstitute or Moq for mocking; FluentAssertions for readable assertions
+- ≉ Use MSTest or NUnit for new code (maintain existing suites only)
+- Files: `*Tests.cs` in a parallel `*.Tests` project
+
+### Coverage
+- ! ≥85% coverage
+- ! Count src/\*
+- ! Exclude entry points, generated code, migrations, program bootstrapping
+
+### Style
+- ! Use `.editorconfig` for code style (project root, checked in)
+- ! Enable Roslyn analyzers and StyleCop.Analyzers as project dependencies
+- ! Follow [Microsoft C# Coding Conventions](https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/coding-style/coding-conventions)
+- ! SDK-style `.csproj` with `<Nullable>enable</Nullable>` and `<ImplicitUsings>enable</ImplicitUsings>`
+- ! `<TreatWarningsAsErrors>true</TreatWarningsAsErrors>` in CI builds
+
+### Naming Conventions
+- ! `PascalCase` for types, methods, properties, events, namespaces, public fields
+- ! `camelCase` for parameters, local variables
+- ! `_camelCase` for private fields: `private readonly ILogger _logger;`
+- ! `IPascalCase` for interfaces: `IRepository`, `ILogger`
+- ! `UPPER_SNAKE_CASE` only for interop constants; otherwise `PascalCase` for const
+- ! Async methods suffixed with `Async`: `GetUserAsync()`, `SaveAsync()`
+- ⊗ Hungarian notation or type prefixes (`strName`, `intCount`)
+
+### Modern Language Features (C# 12+)
+- ! Use records for immutable data carriers: `record UserDto(long Id, string Name);`
+- ! Use `required` properties for mandatory init-only data
+- ! Use primary constructors for simple DI and parameter capture
+- ! Use `init` accessors for immutable-after-construction properties
+- ! Use pattern matching (`is`, `switch` expressions, list patterns)
+- ! Use raw string literals (`"""`) for multi-line strings
+- ~ Use `file`-scoped types for implementation-only helpers
+- ~ Use collection expressions (`[1, 2, 3]`) where supported (C# 12+)
+- ≉ Use verbose constructors + field assignments when primary constructors suffice
+
+### Nullable Reference Types
+- ! Enable `<Nullable>enable</Nullable>` in all projects
+- ! Annotate API boundaries with `?` for nullable; treat non-nullable as contract
+- ! Handle `null` at system boundaries (deserialization, DB, external APIs)
+- ⊗ Use `null!` (null-forgiving operator) except as last resort with documented reason
+- ⊗ Return `null` from methods typed as non-nullable
+
+### Resource Management
+- ! Use `using` declarations or `using` blocks for all `IDisposable` resources
+- ! Implement `IAsyncDisposable` for types holding async resources
+- ! Use `await using` for async disposal
+- ⊗ Call `.Dispose()` manually in a `finally` block (use `using` instead)
+- ⊗ Implement finalizers unless wrapping unmanaged resources directly
+
+### Error Handling
+- ! Throw specific exception types: `ArgumentNullException`, `InvalidOperationException`, etc.
+- ! Use `ArgumentNullException.ThrowIfNull()` (C# 10+) for guard clauses
+- ! Include context in exception messages (what failed, relevant IDs)
+- ⊗ Catch `Exception` or `SystemException` broadly — catch the most specific type
+- ⊗ Swallow exceptions (empty catch blocks)
+- ⊗ Use exceptions for flow control
+- ~ Use Result/OneOf patterns for expected failures in domain logic
+- ~ Log at the handling boundary, not at every catch-and-rethrow
+
+### Async/Await
+- ! Use `async`/`await` for all I/O-bound operations
+- ! Return `Task`/`ValueTask` — never `async void` (except event handlers)
+- ! Use `CancellationToken` in all async public APIs
+- ! Pass `CancellationToken` through the entire call chain
+- ⊗ Use `.Result` or `.Wait()` on tasks (deadlock risk)
+- ⊗ Use `Task.Run()` to wrap sync-over-async (hides problems)
+- ~ Use `ValueTask` for hot-path methods that often complete synchronously
+- ~ Use `ConfigureAwait(false)` in library code (not in app/UI code)
+
+### Dependency Injection
+- ! Use constructor injection; ⊗ service locator pattern (`IServiceProvider.GetService`)
+- ! Register services with appropriate lifetimes: `Singleton`, `Scoped`, `Transient`
+- ! Inject interfaces, not implementations
+- ⊗ Inject `IServiceProvider` into business logic classes
+- ~ Use `IOptions<T>` / `IOptionsSnapshot<T>` for configuration binding
+- ≉ Use `static` helper classes for behavior that should be injected
+
+### Collections & LINQ
+- ! Prefer immutable collections for shared/public data: `IReadOnlyList<T>`, `IReadOnlyDictionary<K,V>`
+- ! Use LINQ for declarative transforms; ⊗ for side-effectful iterations
+- ~ Materialize queries early to avoid multiple enumeration (`.ToList()`, `.ToArray()`)
+- ~ Use `Span<T>` / `ReadOnlySpan<T>` for performance-critical slicing
+- ⊗ Return `IEnumerable<T>` backed by a deferred query from public APIs without documentation
+
+### Database (EF Core)
+- ! Use parameterized queries (EF Core does this automatically)
+- ! Use `AsNoTracking()` for read-only queries
+- ! Use explicit transactions for multi-step writes
+- ~ Use repository pattern or query objects; ≉ scatter `DbContext` calls across controllers
+- ~ Use migrations for schema evolution
+- ⊗ Use raw SQL with string interpolation (SQL injection risk — use `FromSqlInterpolated`)
+
+### Telemetry
+- See [telemetry.md](../tools/telemetry.md)
+- ~ Structured logging (Serilog or Microsoft.Extensions.Logging) for production
+- ~ Sentry.io for error tracking
+- ~ Prometheus/Grafana or Application Insights for metrics
+- ? OpenTelemetry .NET for distributed tracing
+
+### Safety
+- ⊗ Hardcode secrets, keys, or credentials in source
+- ! Use User Secrets (dev), environment variables, or Azure Key Vault (prod)
+- ! Validate all external input (model binding validation, FluentValidation)
+- ~ Scan dependencies with `dotnet list package --vulnerable` or Snyk/OWASP
+
+## Commands
+
+See [commands.md](./commands.md).
+
+## Patterns
+
+### Testing (xUnit + FluentAssertions + NSubstitute)
+```csharp
+public class CalculatorTests {
+    private readonly Calculator _sut = new();
+
+    [Fact] public void Add_ReturnsSum() => _sut.Add(2, 3).Should().Be(5);
+
+    [Theory] [InlineData(0,1,1)] [InlineData(-1,1,0)]
+    public void Add_Parameterized(int a, int b, int expected) =>
+        _sut.Add(a, b).Should().Be(expected);
+
+    [Fact] public void Divide_ByZero_Throws() =>
+        ((Action)(() => _sut.Divide(10, 0))).Should().Throw<DivideByZeroException>();
+}
+
+public class UserServiceTests {
+    private readonly IUserRepository _repo = Substitute.For<IUserRepository>();
+    private readonly UserService _sut;
+    public UserServiceTests() => _sut = new UserService(_repo);
+
+    [Fact] public async Task GetByIdAsync_ExistingUser_ReturnsUser() {
+        var expected = new User(1, "Alice");
+        _repo.GetByIdAsync(1).Returns(expected);
+        (await _sut.GetByIdAsync(1)).Should().Be(expected);
+        await _repo.Received(1).GetByIdAsync(1);
+    }
+}
+```
+
+### Records, Primary Constructors & Pattern Matching
+```csharp
+public record UserDto(long Id, string Name, string Email);
+
+public class CreateOrderRequest {
+    public required string ProductId { get; init; }
+    public required int Quantity { get; init; }
+    public string? Notes { get; init; }
+}
+
+public abstract record Result<T>;
+public record Success<T>(T Value) : Result<T>;
+public record Failure<T>(string Error, Exception? Cause = null) : Result<T>;
+
+string Describe<T>(Result<T> r) => r switch {
+    Success<T> s => $"OK: {s.Value}", Failure<T> f => $"Error: {f.Error}", _ => "Unknown"
+};
+
+// Primary constructor DI (C# 12)
+public class UserService(IUserRepository repo, ILogger<UserService> logger) {
+    public async Task<User?> GetByIdAsync(long id, CancellationToken ct = default) =>
+        await repo.GetByIdAsync(id, ct);
+}
+```
+
+### Async/Await & Resources
+```csharp
+// CancellationToken through entire chain
+public async Task<IReadOnlyList<Order>> GetOrdersAsync(long userId, CancellationToken ct = default) {
+    await using var conn = await _dataSource.OpenConnectionAsync(ct);
+    return await conn.QueryAsync<Order>("SELECT * FROM orders WHERE user_id = @Id",
+        new { Id = userId }).ToListAsync(ct);
+}
+
+// using declarations for IDisposable/IAsyncDisposable
+await using var stream = File.OpenRead(path);
+using var reader = new StreamReader(stream);
+var content = await reader.ReadToEndAsync();
+
+// Minimal API
+var app = WebApplication.CreateBuilder(args).Build();
+app.MapGet("/users/{id}", async (long id, IUserService svc, CancellationToken ct) =>
+    await svc.GetByIdAsync(id, ct) is { } user ? Results.Ok(user) : Results.NotFound());
+app.Run();
+```
+
+## Build Configuration
+
+**`.csproj` key settings**:
+- ! `<TargetFramework>net8.0</TargetFramework>`
+- ! `<Nullable>enable</Nullable>`, `<ImplicitUsings>enable</ImplicitUsings>`
+- ! `<TreatWarningsAsErrors>true</TreatWarningsAsErrors>`
+- ! `<AnalysisLevel>latest-recommended</AnalysisLevel>`
+- ! `StyleCop.Analyzers` as `PrivateAssets="all"` PackageReference
+
+**Test project deps**: `Microsoft.NET.Test.Sdk`, `xunit`, `xunit.runner.visualstudio`, `NSubstitute`, `FluentAssertions`, `coverlet.collector`
+
+**`.editorconfig` key rules**: `indent_size = 4`, `file_scoped` namespaces, `simple_using_statement`, `require_accessibility_modifiers = always`, `_camelCase` private fields
+
+## Anti-Patterns
+
+Items marked ⊗ in Standards above are not repeated here.
+
+- ≉ **Verbose constructors**: Use primary constructors (C# 12) or records
+- ≉ **Manual null guards**: Use `ArgumentNullException.ThrowIfNull()`
+- ≉ **`IEnumerable<T>` as public return**: Materialize or use `IReadOnlyList<T>`
+- ≉ **God classes**: Keep <500 lines; extract services/handlers
+- ≉ **`static` utility classes**: Inject via DI for testability
+
+## Hygiene
+
+**Types:**
+- ⊗ `object` as parameter or return type where a concrete or generic type is knowable
+- ⊗ `dynamic` outside genuine late-binding scenarios (COM interop, DLR, legacy)
+- ⊗ `null!` (null-forgiving operator) to suppress nullable warnings without a documented invariant
+- ⊗ `#pragma warning disable` without an inline comment explaining why it is safe
+
+**Error handling:**
+- ⊗ Empty `catch {}` or `catch (Exception) { }` — handle or re-throw
+- ⊗ `catch (Exception e) { }` that swallows without logging — use structured logging and propagate
+- ⊗ Returning `null` or a default value from a public method to mask an exception
+
+**Dead code:**
+- ~ Roslyn IDE analyzers report unused private members; treat `IDE0051` as a warning-as-error in CI
+- ~ Run `dotnet-unused` for projects with large public APIs to detect unreferenced symbols
+- ⊗ `#pragma warning disable IDE0051` to hide dead code from analysis instead of deleting it
+
+## Compliance Checklist
+
+- ! XML doc comments on all public APIs
+- ! See [testing.md](../coding/testing.md) for testing requirements
+- ! Use xUnit + FluentAssertions + NSubstitute
+- ! Nullable reference types enabled; `TreatWarningsAsErrors` in CI
+- ! Records for data carriers; primary constructors for simple DI
+- ! `async`/`await` with `CancellationToken` for all I/O
+- ! `using` declarations for all `IDisposable`/`IAsyncDisposable`
+- ⊗ `async void`, `.Result`/`.Wait()`, service locator, null-forgiving `null!`
+- ! Run `task check` before commit

package/languages/dart.md

@@ -0,0 +1,183 @@
+# Dart Standards
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**⚠️ See also**: [main.md](../../main.md) | [PROJECT.md](../../PROJECT.md)
+
+**Stack**: Dart 3.x+; Framework: Flutter (mobile/web) or standalone; Testing: `package:test` / `flutter_test`; Lint: `analysis_options.yaml` + custom_lint; Format: `dart format`; Docs: dartdoc
+
+## Standards
+
+### Documentation
+- ! dartdoc comments (`///`) on all public classes, functions, properties, and libraries
+- ! Document parameters, return values, and exceptions for public API
+- ! Library-level doc comments (`/// {@category ...}`) for package organization
+- ~ Use `[ClassName]` and `[methodName]` for cross-references in doc comments
+- ~ Include code examples in `/// ```dart` blocks
+
+### Testing
+See [testing.md](../coding/testing.md).
+
+- ! Use `package:test` (Dart) or `flutter_test` (Flutter) for unit tests
+- ! Place tests in `test/` directory mirroring `lib/` structure
+- ! Test widget trees with `testWidgets()` and `WidgetTester` (Flutter)
+- ~ Use `mockito` or `mocktail` for mocking dependencies
+- ~ Use golden tests for UI regression testing (Flutter)
+
+### Coverage
+- ! ≥80% coverage (measured via `dart test --coverage` or `flutter test --coverage`)
+- ! Count lib/**
+- ! Exclude generated files (`*.g.dart`, `*.freezed.dart`), entry points
+
+### Style
+- ! Follow [Effective Dart](https://dart.dev/effective-dart) guidelines
+- ! Use `analysis_options.yaml` with recommended lints enabled
+- ! Use `dart format` (or `flutter format`) for all code
+- ! 2-space indentation
+- ! Line length ≤80 characters
+- ! Enable `strict-casts`, `strict-inference`, `strict-raw-types` in analysis options
+
+### Naming Conventions
+- ! `lowerCamelCase` for variables, functions, parameters, named parameters
+- ! `UpperCamelCase` for classes, enums, typedefs, extensions, mixins
+- ! `lowerCamelCase` for library/package names and file names
+- ! `SCREAMING_SNAKE_CASE` for compile-time constants only when following Flutter convention
+- ! Prefix private members with `_`: `_internalState`
+- ! Prefix boolean variables/getters with `is`, `has`, `can`: `isLoading`, `hasError`
+- ⊗ Hungarian notation or type prefixes
+
+### Null Safety
+- ! Use sound null safety (Dart 3.x enforces this)
+- ! Use `?` for nullable types only when null is a valid state
+- ! Use `late` only when initialization is guaranteed before access
+- ! Prefer `??` (if-null) and `?.` (null-aware) over null checks
+- ⊗ Force-unwrap (`!`) without prior null check or assertion
+- ≉ `late` as a workaround for poor initialization design
+
+### Immutability
+- ! Use `final` for variables that are assigned once
+- ! Use `const` for compile-time constants and constructors
+- ! Prefer immutable data classes (use `freezed` or manual `copyWith`)
+- ≉ Mutable state where `final` + rebuild pattern suffices (esp. Flutter)
+
+### Classes & Types
+- ! Use `sealed class` (Dart 3) for exhaustive type hierarchies
+- ! Use `enum` with members for fixed sets of values
+- ! Use extension types for zero-cost wrappers
+- ! Use mixins for shared behavior across unrelated classes
+- ~ Use `typedef` for complex function signatures
+- ⊗ Deep inheritance hierarchies (>3 levels) — prefer composition
+
+### Async & Concurrency
+- ! Use `async`/`await` for asynchronous operations
+- ! Always handle errors from Futures (`try`/`catch` or `.catchError`)
+- ! Use `Stream` for reactive data flows; `StreamController` for custom streams
+- ! Close `StreamController` and cancel `StreamSubscription` to avoid leaks
+- ⊗ Fire-and-forget Futures without error handling
+- ~ Use `Isolate` for CPU-intensive work (keeps UI responsive in Flutter)
+- ~ Use `compute()` helper for simple isolate tasks in Flutter
+
+### State Management (Flutter)
+- ~ Choose one state management approach per project and document it
+- ~ Options: Riverpod, Bloc/Cubit, Provider, signals
+- ! Separate business logic from UI (no business logic in `build()`)
+- ! Dispose controllers, streams, and subscriptions in `dispose()`
+- ⊗ Calling `setState` from outside the widget or after disposal
+
+### Dependencies
+- ! Pin dependency versions in `pubspec.yaml` (use `^` for semver ranges)
+- ! Use `pubspec.lock` committed for applications (not for packages)
+- ! Minimize dependencies; prefer `dart:*` core libraries
+- ~ Use `dependency_overrides` only for testing, never in production
+- ~ Run `dart pub outdated` regularly
+
+### Code Generation
+- ! Use `build_runner` for code generation (`json_serializable`, `freezed`, etc.)
+- ! Commit generated files or document regeneration in task commands
+- ! Exclude generated files from lint and coverage
+
+### Security
+- ⊗ Hardcode secrets or credentials in source (esp. Flutter — compiled but extractable)
+- ! Validate all external inputs (user data, API responses, deep links)
+- ~ Use `flutter_secure_storage` for sensitive data on device
+- ~ Use certificate pinning for critical API connections
+
+### Telemetry
+- ~ Use `package:logging` or structured logger for backend Dart
+- ~ Use Firebase Crashlytics / Sentry for Flutter crash reporting
+- ? OpenTelemetry for backend Dart services
+
+## Commands
+
+See [commands.md](./commands.md).
+
+## Patterns
+
+### Sealed Class + Pattern Matching (Dart 3)
+```dart
+sealed class Result<T> { const Result(); }
+class Success<T> extends Result<T> { final T data; const Success(this.data); }
+class Failure<T> extends Result<T> { final String message; const Failure(this.message); }
+
+String display(Result<User> r) => switch (r) {
+  Success(data: final u) => 'Welcome, ${u.name}',
+  Failure(message: final m) => 'Error: $m',
+};
+```
+
+### Testing (Flutter Widget)
+```dart
+testWidgets('Counter increments', (tester) async {
+  await tester.pumpWidget(const MyApp());
+  expect(find.text('0'), findsOneWidget);
+  await tester.tap(find.byIcon(Icons.add));
+  await tester.pump();
+  expect(find.text('1'), findsOneWidget);
+});
+```
+
+### Repository Pattern
+```dart
+abstract interface class UserRepository {
+  Future<User?> findById(int id);
+  Future<List<User>> findAll({int limit = 20, int offset = 0});
+}
+
+class ApiUserRepository implements UserRepository {
+  final HttpClient _client;
+  ApiUserRepository(this._client);
+
+  @override
+  Future<User?> findById(int id) async {
+    final response = await _client.get(Uri.parse('/users/$id'));
+    if (response.statusCode == 404) return null;
+    return User.fromJson(jsonDecode(response.body));
+  }
+}
+```
+
+### Extension Types (Dart 3)
+```dart
+extension type UserId(int value) { factory UserId.parse(String s) => UserId(int.parse(s)); }
+extension type Email(String value) { bool get isValid => value.contains('@'); }
+```
+
+## Anti-Patterns
+
+Items marked ⊗ in Standards above are not repeated here.
+
+- ≉ **`late` as lazy init workaround**: Design proper initialization
+- ≉ **Deep inheritance (>3 levels)**: Prefer composition/mixins
+- ≉ **`dynamic` type**: Use specific types; `Object?` if truly unknown
+- ≉ **`print()` for logging**: Use `package:logging`
+
+## Compliance Checklist
+
+- ! dartdoc on all public API
+- ! See [testing.md](../coding/testing.md) for testing requirements
+- ! Unit + widget tests; ≥80% coverage
+- ! `dart format` + `dart analyze` with strict options enforced
+- ! Effective Dart conventions; sound null safety; `final`/`const` by default
+- ! Sealed classes for exhaustive hierarchies; pattern matching
+- ⊗ `!` without check, fire-and-forget Futures, `dynamic`, business logic in `build()`
+- ! Run `task check` before commit

package/languages/delphi.md

@@ -0,0 +1,218 @@
+# Delphi / Object Pascal Standards
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**⚠️ See also**: [main.md](../../main.md) | [PROJECT.md](../../PROJECT.md) | [telemetry.md](../tools/telemetry.md)
+
+**Stack**: Delphi 12+/Object Pascal, RAD Studio; GUI: VCL (Windows), FMX (cross-platform); DB: FireDAC; Testing: DUnitX
+
+## Standards
+
+### Documentation
+- ! XML documentation comments (`///`) for all public types, methods, and properties
+- ! Unit header comment: purpose, author, date, dependencies
+- ~ Document preconditions, postconditions, and exceptions on public methods
+- ~ Use `{$REGION}` / `{$ENDREGION}` to organize long units
+
+### Testing
+See [testing.md](../coding/testing.md).
+
+- ! Use DUnitX for all new test projects
+- ≉ Use legacy DUnit for new code (maintain existing DUnit suites only)
+- Files: `Test*.pas` or `*Tests.pas`
+
+### Coverage
+- ! ≥85% coverage
+- ! Count src/\*
+- ! Exclude entry points, generated code, DFM/FMX form logic
+
+### Style
+- ! Follow [Embarcadero Object Pascal Style Guide](https://docwiki.embarcadero.com/RADStudio/en/Delphi's_Object_Pascal_Style_Guide)
+- ! Use PascalCase (InfixCaps) for all identifiers; ⊗ underscores (except header translations)
+- ! Reserved words and keywords in lowercase (`begin`, `end`, `string`, `nil`)
+- ! Two-space indentation (no tabs)
+- ⊗ Hungarian notation (except header translations)
+- ~ Use [Pascal Analyzer](https://www.peganza.com/) or [FixInsight](https://www.yourkit.com/) for static analysis
+
+### Naming Conventions
+- ! Types prefixed with `T`: `TCustomer`, `TOrderStatus`
+- ! Interfaces prefixed with `I`: `IRepository`, `ILogger`
+- ! Exception types prefixed with `E`: `EInvalidArgument`, `ENotFound`
+- ! Private fields prefixed with `F`: `FName`, `FCount`
+- ! Enumeration members prefixed with 2–3 char mnemonic: `TColor = (clRed, clGreen, clBlue)`
+- ! Component variables prefixed by type abbreviation: `btnSubmit`, `edtName`, `lblTitle`
+- ~ Constants in PascalCase (not ALL_CAPS): `const MaxRetries = 3;`
+- ~ Descriptive names; prefer `ObjectPointer` over `ObjPtr`
+
+### Types
+- ! Use strong typing: enumerations, records, distinct types over raw integers/strings
+- ! Use generics (`TList<T>`, `TDictionary<K,V>`, `TObjectList<T>`) over untyped containers
+- ⊗ Use `Variant` / `OleVariant` except when required for COM interop
+- ⊗ Use untyped containers (`TList`, `TStringList` for non-string data)
+- ~ Use `TArray<T>` over dynamic array declarations
+- ~ Use `Double` for floating-point; ≉ use `Real` (backward compat only)
+- ~ Use `NativeInt`/`NativeUInt` for pointer-sized integers
+
+### Memory Management
+- ! Every object you create, you must free (clear ownership model)
+- ! Use `FreeAndNil` over bare `Free` for field cleanup in destructors
+- ! Override `Destroy` (not `Free`); always mark with `override`
+- ! Use `try..finally` to guarantee cleanup of locally created objects
+- ⊗ Call `Destroy` directly; always use `Free` or `FreeAndNil`
+- ~ Use TComponent ownership (`AOwner` parameter) for form/component lifecycles
+- ~ Use interfaces (reference counting) for shared/cross-boundary objects
+- ~ Use managed records (`class operator Initialize/Finalize`) for RAII patterns (Delphi 10.4+)
+- ≉ Use `GetMem`/`FreeMem` unless writing low-level or performance-critical code
+
+### Interfaces
+- ! Use interfaces for abstraction, testability, and dependency injection
+- ! Declare interfaces in a shared unit separate from implementations
+- ~ Use interface delegation (`implements` keyword) to compose behavior
+- ~ Prefer interface references over class references for cross-module boundaries
+- ⊗ Mix interface references and object references to the same instance (prevents double-free / ref-count issues)
+
+### Error Handling
+- ! Use exceptions for exceptional/unexpected errors
+- ! Derive custom exceptions from `Exception` or `EArgumentException`, etc.
+- ! Use `try..except` with specific exception types; ⊗ bare `except` without re-raise
+- ! Use `try..finally` for resource cleanup (separate from `try..except`)
+- ⊗ Silently swallow exceptions (empty `except` blocks)
+- ~ Use `EAbort` / `Abort` for non-error flow control (e.g., cancel operations)
+- ~ Log exceptions with context before re-raising
+
+### Concurrency
+- ! Use `TTask` / `TParallel` (Parallel Programming Library) for new async work
+- ! Never access VCL/FMX controls from background threads; use `TThread.Synchronize` or `TThread.Queue`
+- ~ Use `TThreadPool` for managing concurrent workloads
+- ~ Use `TMonitor` or `TCriticalSection` for shared state protection
+- ⊗ Use `Suspend`/`Resume` on threads (deprecated, unsafe)
+- ≉ Directly subclass `TThread` when PPL tasks suffice
+
+### Database (FireDAC)
+- ! Use parameterized queries; ⊗ string concatenation for SQL
+- ! Use `TFDConnection` with connection definitions (not hard-coded connection strings)
+- ~ Use `TFDQuery` over `TFDTable` for production code
+- ~ Wrap multi-step operations in explicit transactions
+- ⊗ Use BDE (Borland Database Engine) — fully deprecated
+
+### Telemetry
+- See [telemetry.md](../tools/telemetry.md)
+- ~ Structured logging (CodeSite, SmartInspect, or custom structured logger) for production
+- ~ Sentry.io (via REST) or equivalent for error tracking
+- ? OpenTelemetry (via REST integration) for distributed tracing
+
+### Safety
+- ⊗ Hardcode API keys or secrets in source or shipped binaries
+- ! Validate all external input (user input, file data, network responses)
+- ~ Use `{$WARN}` directives to treat warnings as errors in CI
+- ~ Enable range checking (`{$R+}`) and overflow checking (`{$Q+}`) in debug builds
+
+## Commands
+
+See [commands.md](./commands.md).
+
+## Patterns
+
+### Testing (DUnitX)
+```pascal
+unit TestCalculator;
+interface
+uses DUnitX.TestFramework, Calculator;
+type
+  [TestFixture]
+  TTestCalculator = class
+  private
+    FSut: TCalculator;
+  public
+    [Setup]    procedure Setup;
+    [TearDown] procedure TearDown;
+    [Test]     procedure Add_TwoPositiveNumbers_ReturnsSum;
+    [Test] [TestCase('Zero','0,1,1')] [TestCase('Neg','-1,1,0')]
+    procedure Add_Parameterized(const A, B, Expected: Integer);
+  end;
+implementation
+procedure TTestCalculator.Setup; begin FSut := TCalculator.Create end;
+procedure TTestCalculator.TearDown; begin FreeAndNil(FSut) end;
+procedure TTestCalculator.Add_TwoPositiveNumbers_ReturnsSum;
+begin Assert.AreEqual(5, FSut.Add(2, 3)) end;
+procedure TTestCalculator.Add_Parameterized(const A, B, Expected: Integer);
+begin Assert.AreEqual(Expected, FSut.Add(A, B)) end;
+initialization
+  TDUnitX.RegisterTestFixture(TTestCalculator);
+end.
+```
+
+### Interface-Based Design
+```pascal
+unit Services.Interfaces;
+interface
+type
+  ILogger = interface
+    ['{A1B2C3D4-E5F6-7890-ABCD-EF1234567890}']
+    procedure Info(const Msg: string);
+    procedure Error(const Msg: string; E: Exception = nil);
+  end;
+  IRepository<T: class> = interface
+    ['{B2C3D4E5-F6A7-8901-BCDE-F12345678901}']
+    function GetById(const Id: Integer): T;
+    function GetAll: TArray<T>;
+    procedure Save(const Entity: T);
+    procedure Delete(const Id: Integer);
+  end;
+implementation
+end.
+```
+
+### Resource Cleanup & Generics
+```pascal
+procedure ProcessFile(const FileName: string);
+var Stream: TFileStream; Reader: TStreamReader;
+begin
+  Stream := TFileStream.Create(FileName, fmOpenRead or fmShareDenyWrite);
+  try
+    Reader := TStreamReader.Create(Stream);
+    try while not Reader.EndOfStream do ProcessLine(Reader.ReadLine);
+    finally FreeAndNil(Reader) end;
+  finally FreeAndNil(Stream) end;
+end;
+
+var Customers: TObjectList<TCustomer>;
+begin
+  Customers := TObjectList<TCustomer>.Create(True); // OwnsObjects
+  try
+    for var C in Customers do DoWork(C);
+  finally Customers.Free end;
+end;
+```
+
+### Async with PPL
+```pascal
+procedure TMainForm.btnProcessClick(Sender: TObject);
+begin
+  btnProcess.Enabled := False;
+  TTask.Run(procedure var R: string; begin
+    R := PerformHeavyWork;
+    TThread.Queue(nil, procedure begin lblResult.Caption := R; btnProcess.Enabled := True end);
+  end);
+end;
+```
+
+## Anti-Patterns
+
+Items marked ⊗ in Standards above are not repeated here.
+
+- ≉ **`Application.ProcessMessages` in loops**: Use PPL/threads
+- ≉ **Published fields without properties**: Use properties
+- ≉ **Circular unit references**: Extract shared types to common unit
+
+## Compliance Checklist
+
+- ! Follow Embarcadero Object Pascal Style Guide
+- ! PascalCase identifiers; `T`/`I`/`E`/`F` prefixes
+- ! See [testing.md](../coding/testing.md) for testing requirements
+- ! Use DUnitX for unit tests
+- ! Use `try..finally` for resource cleanup; `FreeAndNil` in destructors
+- ! Use generics and interfaces for type safety and abstraction
+- ⊗ Use `Variant`, `with`, global state, or BDE
+- ⊗ Access UI from background threads
+- ! Run `task check` before commit