@deftai/directive-content 0.55.0

package/languages/elixir.md

@@ -0,0 +1,208 @@
+# Elixir Standards
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**⚠️ See also**: [main.md](../../main.md) | [PROJECT.md](../../PROJECT.md)
+
+**Stack**: Elixir 1.16+ / OTP 26+; Build: Mix; Testing: ExUnit; Lint: Credo; Format: `mix format`; Docs: ExDoc; Types: Dialyxir
+
+## Standards
+
+### Documentation
+- ! `@doc` and `@moduledoc` on all public modules and functions
+- ! `@spec` typespecs on all public functions
+- ! Include `## Examples` with `iex>` doctest blocks for public API
+- ~ Use `@doc false` to explicitly hide internal public functions
+- ~ Cross-reference with `{:link, module}` or backtick syntax
+
+### Testing
+See [testing.md](../coding/testing.md).
+
+- ! Use ExUnit (`test`, `describe`, `assert`, `refute`)
+- ! Place tests in `test/` mirroring `lib/` structure; files: `*_test.exs`
+- ! Test happy paths, error cases, and edge cases
+- ~ Use doctests (`doctest Module`) for example-based testing
+- ~ Use `Mox` for mocking via behaviours (not concrete implementations)
+- ~ Use property-based testing via `StreamData`
+
+### Coverage
+- ! ≥80% coverage (measured via `mix test --cover` or excoveralls)
+- ! Count lib/**
+- ! Exclude generated code, migrations, Phoenix boilerplate
+
+### Style
+- ! Run `mix format` on all code (project `.formatter.exs` checked in)
+- ! Use Credo for static analysis (`mix credo --strict`)
+- ! 2-space indentation
+- ! Line length ≤98 characters (Elixir formatter default)
+- ! Follow [Elixir Style Guide](https://github.com/christopheradams/elixir_style_guide)
+
+### Naming Conventions
+- ! `snake_case` for functions, variables, atoms, and file names
+- ! `PascalCase` (CamelCase) for module names: `MyApp.UserService`
+- ! `snake_case` for module file paths matching module name: `my_app/user_service.ex`
+- ! Predicate functions end with `?`: `valid?`, `empty?`, `admin?`
+- ! Dangerous/raising functions end with `!`: `fetch!`, `decode!`
+- ! `SCREAMING_SNAKE_CASE` for module attributes used as constants (convention, not enforced)
+- ⊗ Atoms with spaces or special characters unless protocol requires it
+
+### Pattern Matching
+- ! Use pattern matching for control flow (function heads, `case`, `with`)
+- ! Prefer multi-clause functions over `if`/`cond` for type/shape dispatch
+- ! Use `with` for chaining fallible operations with clear pattern matching
+- ! Destructure in function arguments when possible
+- ⊗ Nested `case` statements >2 levels deep — refactor into functions
+- ≉ `if`/`else` when pattern matching is clearer
+
+### Data & Immutability
+- ! All data is immutable — embrace transformation pipelines
+- ! Use structs (`%MyStruct{}`) for domain entities with enforced keys
+- ! Use `@enforce_keys` for required struct fields
+- ! Use maps for unstructured/dynamic data; keyword lists for options
+- ~ Use Ecto embedded schemas for validated data structures
+- ⊗ Atoms from user input (`String.to_atom/1`) — atom table is not garbage collected
+
+### Pipe Operator
+- ! Use `|>` for data transformation chains (≥2 steps)
+- ! First argument flows through the pipe; design functions pipe-friendly
+- ! One transformation per line in pipe chains
+- ≉ Pipe chains >10 steps — extract named intermediate functions
+- ≉ Pipes with anonymous functions — extract to named functions
+
+### OTP & Concurrency
+- ! Use OTP behaviours: `GenServer`, `Supervisor`, `Agent`, `Task`
+- ! Supervision trees for all long-running processes
+- ! Use `Task.async` / `Task.await` for concurrent one-off work
+- ! Trap exits explicitly when needed; document why
+- ! Design processes for "let it crash" — supervisors restart
+- ⊗ Spawning bare processes without supervision in production
+- ⊗ Shared mutable state outside of OTP processes
+- ~ Use `Registry` for dynamic process naming
+- ~ Use `GenStage` / `Broadway` for back-pressure and data pipelines
+
+### Error Handling
+- ! Use `{:ok, value}` / `{:error, reason}` tuples for expected failures
+- ! Use `!` function variants that raise for unexpected/unrecoverable errors
+- ! Use `with` for composing multiple `{:ok, _}` / `{:error, _}` chains
+- ! Let processes crash on unexpected errors; supervisors handle recovery
+- ⊗ Catching broad exceptions (`rescue Exception`) in normal flow
+- ⊗ Returning bare `:error` without a reason
+
+### Behaviours & Protocols
+- ! Define `@callback` specs in behaviour modules
+- ! Use behaviours for dependency injection / mocking boundaries
+- ! Use protocols for polymorphic dispatch on data types
+- ~ Use `defimpl` in the data type's module or in the protocol module (be consistent)
+
+### Dependencies
+- ! Manage via Mix (`mix.exs` deps); specify version constraints
+- ! Use `mix.lock` committed for applications
+- ! Minimize dependencies; prefer standard library and OTP
+- ~ Run `mix hex.audit` for security advisories
+- ~ Use `mix deps.audit` for outdated dependencies
+
+### Phoenix (Web)
+- ~ Follow Phoenix conventions: contexts for business logic, schemas for data
+- ! Validate all inputs via Ecto changesets
+- ! Use parameterized queries (Ecto handles this by default)
+- ~ Use LiveView for real-time UI; channels for custom WebSocket protocols
+- ⊗ Business logic in controllers — delegate to context modules
+
+### Security
+- ⊗ Hardcode secrets or credentials in source
+- ! Use `Application.get_env` or `System.get_env` for secrets (runtime config)
+- ! Validate all external inputs
+- ⊗ `String.to_atom/1` on user input (denial-of-service vector)
+- ~ Use `Plug.CSRFProtection` for web applications
+
+### Telemetry
+- ! Use `:telemetry` for instrumentation (Erlang standard)
+- ~ Use `telemetry_metrics` + `telemetry_poller` for metrics collection
+- ~ Use `Logger` with structured metadata
+- ? OpenTelemetry via `opentelemetry_api` + `opentelemetry_exporter`
+
+## Commands
+
+See [commands.md](./commands.md).
+
+## Patterns
+
+### Pattern Matching & Pipelines
+```elixir
+defmodule MyApp.Parser do
+  @spec parse_value(String.t(), atom()) :: {:ok, term()} | {:error, atom()}
+  def parse_value(raw, :integer) do
+    case Integer.parse(raw) do
+      {val, ""} -> {:ok, val}
+      _ -> {:error, :invalid_integer}
+    end
+  end
+  def parse_value("true", :boolean), do: {:ok, true}
+  def parse_value("false", :boolean), do: {:ok, false}
+  def parse_value(_, :boolean), do: {:error, :invalid_boolean}
+  def parse_value(raw, :string) when is_binary(raw), do: {:ok, raw}
+  def parse_value(_, _), do: {:error, :unsupported_type}
+end
+
+# with pipeline for composed operations
+def create_user(params) do
+  with {:ok, v} <- validate_params(params),
+       {:ok, user} <- Repo.insert(User.changeset(%User{}, v)),
+       {:ok, _} <- Mailer.send_welcome(user) do
+    {:ok, user}
+  end
+end
+```
+
+### GenServer
+```elixir
+defmodule MyApp.Counter do
+  use GenServer
+  def start_link(opts \\ []), do: GenServer.start_link(__MODULE__, Keyword.get(opts, :initial, 0), name: __MODULE__)
+  def increment, do: GenServer.call(__MODULE__, :increment)
+  def value, do: GenServer.call(__MODULE__, :value)
+  @impl true
+  def init(initial), do: {:ok, initial}
+  @impl true
+  def handle_call(:increment, _from, n), do: {:reply, n + 1, n + 1}
+  def handle_call(:value, _from, n), do: {:reply, n, n}
+end
+```
+
+### Testing (ExUnit)
+```elixir
+defmodule MyApp.ParserTest do
+  use ExUnit.Case, async: true
+  doctest MyApp.Parser
+
+  describe "parse_value/2" do
+    test "parses integer" do assert {:ok, 42} = MyApp.Parser.parse_value("42", :integer) end
+    test "rejects invalid" do assert {:error, _} = MyApp.Parser.parse_value("abc", :integer) end
+    test "parses booleans" do
+      assert {:ok, true} = MyApp.Parser.parse_value("true", :boolean)
+      assert {:error, _} = MyApp.Parser.parse_value("yes", :boolean)
+    end
+  end
+end
+```
+
+## Anti-Patterns
+
+Items marked ⊗ in Standards above are not repeated here.
+
+- ≉ **`if`/`else` over pattern matching**: Use multi-clause functions or `case`
+- ≉ **Nested `case` >2 deep**: Refactor into named functions
+- ≉ **Anonymous functions in pipes**: Extract to named functions
+- ≉ **Long `with` chains (>5 clauses)**: Break into smaller functions
+
+## Compliance Checklist
+
+- ! `@doc`, `@moduledoc`, `@spec` on all public API
+- ! See [testing.md](../coding/testing.md) for testing requirements
+- ! ExUnit + doctests; ≥80% coverage
+- ! `mix format` + Credo (strict) + Dialyxir enforced
+- ! Pattern matching and pipes for control flow; OTP for concurrency
+- ! `{:ok, _}` / `{:error, reason}` tuples; `!` variants for raising
+- ! Supervision trees for all production processes
+- ⊗ Bare `spawn`, `String.to_atom/1` on input, broad `rescue`, logic in controllers
+- ! Run `task check` before commit

package/languages/go.md

@@ -0,0 +1,78 @@
+# Go 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)
+
+## Standards
+
+### Documentation
+- ! Follow [go.dev/doc/comment](https://go.dev/doc/comment)
+- ! All exported symbols have doc comments (complete sentences)
+
+### Testing
+See [testing.md](../coding/testing.md).
+
+- ! Use Testify (assert/require)
+- Files: `*_test.go`, functions: `TestFuncName(t *testing.T)`
+
+### Coverage
+- ! ≥85% coverage
+- ! Count internal/\* + pkg/\*
+- ! Exclude entry points, utilities, generated code
+
+### Telemetry
+- See [telemetry.md](../tools/telemetry.md)
+- ~ Structured logging (zerolog) for production
+- ~ Sentry.io for error tracking
+- ? OpenTelemetry for distributed tracing
+
+## Commands
+
+See [commands.md](./commands.md).
+
+## 🔧 Patterns
+
+**Table-Driven Tests**:
+
+```go
+tests := []struct{name string; input, want Type; wantErr bool}{
+    {"case1", input1, want1, false},
+    {"error", input2, want2, true},
+}
+for _, tt := range tests {
+    t.Run(tt.name, func(t *testing.T) {
+        got, err := Fn(tt.input)
+        if tt.wantErr { assert.Error(t, err); return }
+        assert.NoError(t, err)
+        assert.Equal(t, tt.want, got)
+    })
+}
+```
+
+**HTTP**: `w := httptest.NewRecorder(); req, _ := http.NewRequest("GET", "/path", nil); handler.ServeHTTP(w, req); assert.Equal(t, http.StatusOK, w.Code)`
+
+**Interface**: Define consumer-side, mock with function fields
+
+## Hygiene
+
+**Types:**
+- ⊗ `any` (empty interface) where a concrete type or typed interface is knowable; use generics or explicit interfaces
+
+**Error handling:**
+- ⊗ Ignore errors with `_` — every error MUST be checked or explicitly propagated with a reason
+- ⊗ Empty `recover` blocks that swallow panics silently
+
+**Dead code:**
+- ~ Run `staticcheck` (detects unused code, unreachable branches) and `deadcode` (golang.org/x/tools/cmd/deadcode) before releases
+- ⊗ Unexported functions that are never called anywhere in the package
+
+**Circular dependencies:**
+- The Go compiler rejects import cycles — treat them as build failures, not warnings
+- ! Resolve by extracting shared types to a lower-level package; do not re-order imports
+
+## Compliance Checklist
+
+- ! Follow go.dev/doc/comment for all exported symbols
+- ! See [testing.md](../coding/testing.md) for testing requirements
+- ! Run `task check` before commit

package/languages/java.md

@@ -0,0 +1,278 @@
+# Java 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**: Java 21+ (LTS), Maven/Gradle; Web: Spring Boot 3+; Testing: JUnit 5 + Mockito + AssertJ; Analysis: Checkstyle, SpotBugs, Error Prone
+
+## Standards
+
+### Documentation
+- ! Javadoc on all public classes, interfaces, methods, and constants
+- ! Document `@param`, `@return`, `@throws` for public/protected methods
+- ~ Use `@since` tags when adding public API to existing libraries
+- ~ Use `{@code}` and `{@link}` for inline references
+
+### Testing
+See [testing.md](../coding/testing.md).
+
+- ! Use JUnit 5 (`@Test`, `@ParameterizedTest`, `@Nested`)
+- ! Use Mockito for mocking; AssertJ for fluent assertions
+- ≉ Use JUnit 4 for new code (maintain existing suites only)
+- Files: `*Test.java` or `*Tests.java` in `src/test/java`
+
+### Coverage
+- ! ≥85% coverage
+- ! Count src/main/\*
+- ! Exclude entry points, generated code, framework config
+
+### Style
+- ! Follow [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html)
+- ! Use Checkstyle (project `checkstyle.xml` required)
+- ! Use SpotBugs or Error Prone for static analysis
+- ! Column limit: 100 characters
+- ! 2 or 4 space indentation (pick one, enforce via formatter)
+
+### Naming Conventions
+- ! `PascalCase` for classes, interfaces, enums, records, annotations
+- ! `camelCase` for methods, fields, local variables, parameters
+- ! `UPPER_SNAKE_CASE` for `static final` constants
+- ! Package names all lowercase: `com.example.myapp.service`
+- ! Test classes named `{ClassName}Test`: `UserServiceTest`
+- ~ Interfaces without `I` prefix; use nouns/adjectives: `Repository`, `Serializable`
+- ⊗ Hungarian notation or type prefixes
+
+### Modern Language Features (Java 21+)
+- ! Use `record` for immutable data carriers (DTOs, value objects)
+- ! Use `sealed` classes/interfaces for restricted type hierarchies
+- ! Use pattern matching in `switch` and `instanceof`
+- ! Use text blocks (`"""`) for multi-line strings (SQL, JSON, etc.)
+- ~ Use `var` for local variables when type is obvious from context
+- ~ Use virtual threads (`Executors.newVirtualThreadPerTaskExecutor()`) for I/O-bound concurrency
+- ≉ Use `var` when it obscures the type or reduces readability
+
+### Types & Null Safety
+- ! Use `Optional<T>` for return types that may be absent; ⊗ return `null` from public methods
+- ! Use `@Nullable`/`@NonNull` annotations (JSpecify or JSR 305) on API boundaries
+- ⊗ Use raw generic types (`List` instead of `List<String>`)
+- ⊗ Use `Object` where a specific type or generic is appropriate
+- ~ Prefer immutable collections (`List.of()`, `Map.of()`, `Set.of()`, `Collections.unmodifiable*`)
+- ~ Use `enum` for fixed sets of constants; ⊗ string/int constants for enumerable values
+
+### Records & Sealed Types
+- ! Use `record` instead of manual POJO/DTO boilerplate
+- ! Use `sealed` for closed hierarchies (event types, result types, AST nodes)
+- ~ Use compact constructors in records for validation
+- ⊗ Add mutable state to records (they are immutable by design)
+
+### Resource Management
+- ! Use try-with-resources for all `AutoCloseable` resources
+- ⊗ Manually call `.close()` in a `finally` block (use try-with-resources instead)
+- ! Close streams, connections, readers/writers on all code paths
+- ~ Use `Cleaner` or `PhantomReference` for native resource cleanup (not `finalize()`)
+- ⊗ Override `finalize()` — deprecated and removed in Java 18+
+
+### Error Handling
+- ! Use checked exceptions for recoverable errors; unchecked for programming bugs
+- ! Catch the most specific exception type, not `Exception` or `Throwable`
+- ! Include context in exception messages (what failed, relevant IDs/values)
+- ⊗ Swallow exceptions (empty catch blocks)
+- ⊗ Use exceptions for flow control
+- ~ Create domain-specific exception hierarchies extending `RuntimeException`
+- ~ Use `Optional` instead of throwing for "not found" scenarios in query methods
+- ~ Log exceptions at the boundary where they are handled, not where they are caught and rethrown
+
+### Collections & Streams
+- ! Prefer `List.of()`, `Map.of()`, `Set.of()` for immutable collections
+- ! Use Streams for transformation pipelines; ⊗ for simple iterations with side effects
+- ~ Prefer `Stream.toList()` (Java 16+) over `Collectors.toList()` for unmodifiable results
+- ≉ Modify collections during iteration; use `Iterator.remove()` or build a new collection
+- ⊗ Use `Vector`, `Hashtable`, `Stack` — use `ArrayList`, `HashMap`, `ArrayDeque` instead
+
+### Concurrency
+- ! Use virtual threads (Java 21+) for I/O-bound workloads
+- ! Use `ReentrantLock` over `synchronized` when using virtual threads (avoids carrier thread pinning)
+- ! Use `ExecutorService` with try-with-resources; ⊗ create raw `Thread` instances
+- ~ Use `CompletableFuture` for async composition when virtual threads are not appropriate
+- ~ Use `ConcurrentHashMap`, `CopyOnWriteArrayList` for concurrent data structures
+- ⊗ Use `Thread.stop()`, `Thread.suspend()`, `Thread.resume()` — all deprecated/removed
+- ≉ Use `ThreadLocal` heavily with virtual threads (high memory overhead at scale)
+
+### Dependency Injection
+- ! Use constructor injection; ⊗ field injection (untestable, hides dependencies)
+- ! Keep constructors focused — inject interfaces, not implementations
+- ~ Use `@Qualifier` or custom annotations to disambiguate beans
+- ≉ Use `@Autowired` on fields; prefer `final` fields with constructor injection
+
+### Database
+- ! Use parameterized queries / prepared statements; ⊗ string concatenation for SQL
+- ! Use connection pooling (HikariCP)
+- ~ Use Spring Data JPA or jOOQ; ≉ raw JDBC for application code
+- ~ Wrap multi-step operations in explicit `@Transactional` boundaries
+- ⊗ Use `Statement` with user-supplied input (SQL injection risk)
+
+### Telemetry
+- See [telemetry.md](../tools/telemetry.md)
+- ~ Structured logging (SLF4J + Logback/Log4j2) for production
+- ~ Sentry.io for error tracking
+- ~ Micrometer for metrics
+- ? OpenTelemetry Java for distributed tracing
+
+### Safety
+- ⊗ Hardcode secrets, keys, or credentials in source
+- ! Validate all external input (user, file, network)
+- ! Use `SecurityManager`-independent security practices (removed in Java 24)
+- ~ Keep dependencies up to date; scan with OWASP Dependency-Check or Snyk
+
+## Commands
+
+See [commands.md](./commands.md).
+
+## Patterns
+
+### Testing (JUnit 5 + AssertJ + Mockito)
+```java
+class CalculatorTest {
+    private Calculator sut;
+    @BeforeEach void setUp() { sut = new Calculator(); }
+
+    @Test void addPositiveNumbers() { assertThat(sut.add(2, 3)).isEqualTo(5); }
+
+    @ParameterizedTest @CsvSource({"0,1,1", "-1,1,0", "100,200,300"})
+    void addParameterized(int a, int b, int expected) {
+        assertThat(sut.add(a, b)).isEqualTo(expected);
+    }
+
+    @Nested class WhenDividingByZero {
+        @Test void throwsArithmeticException() {
+            assertThatThrownBy(() -> sut.divide(10, 0))
+                .isInstanceOf(ArithmeticException.class);
+        }
+    }
+}
+
+@ExtendWith(MockitoExtension.class)
+class UserServiceTest {
+    @Mock UserRepository userRepository;
+    @InjectMocks UserService userService;
+
+    @Test void findById_existingUser_returnsUser() {
+        var expected = new User(1L, "alice");
+        when(userRepository.findById(1L)).thenReturn(Optional.of(expected));
+        assertThat(userService.findById(1L)).isPresent().contains(expected);
+        verify(userRepository).findById(1L);
+    }
+}
+```
+
+### Records, Sealed Types & Pattern Matching
+```java
+public record UserDto(long id, String name, String email) {
+    public UserDto {
+        if (name == null || name.isBlank()) throw new IllegalArgumentException("name required");
+    }
+}
+
+public sealed interface Result<T> permits Success, Failure {
+    record Success<T>(T value) implements Result<T> {}
+    record Failure<T>(String error, Exception cause) implements Result<T> {}
+}
+
+String describe(Result<?> r) { return switch (r) {
+    case Result.Success<?> s -> "OK: " + s.value();
+    case Result.Failure<?> f -> "Error: " + f.error();
+}; }
+
+// instanceof pattern matching
+if (shape instanceof Circle c) return Math.PI * c.radius() * c.radius();
+
+// switch pattern matching (Java 21+)
+return switch (obj) {
+    case Integer i when i < 0 -> "Negative: " + i;
+    case Integer i -> "Integer: " + i;
+    case String s -> "String: " + s.toUpperCase();
+    case null -> "null";
+    default -> "Unknown: " + obj;
+};
+```
+
+### Virtual Threads & Resources
+```java
+try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
+    var futures = urls.stream().map(url -> executor.submit(() -> fetchUrl(url))).toList();
+    for (var f : futures) process(f.get());
+}
+
+// ReentrantLock (not synchronized) with virtual threads
+private final ReentrantLock lock = new ReentrantLock();
+void safeUpdate() { lock.lock(); try { /* critical */ } finally { lock.unlock(); } }
+
+// try-with-resources
+try (var conn = ds.getConnection();
+     var stmt = conn.prepareStatement("SELECT * FROM users WHERE id = ?")) {
+    stmt.setLong(1, userId);
+    try (var rs = stmt.executeQuery()) { if (rs.next()) return Optional.of(mapUser(rs)); }
+}
+return Optional.empty();
+```
+
+## Build Configuration
+
+**Key requirements** (Maven or Gradle):
+- ! Java 21+ toolchain, UTF-8 encoding
+- ! Test deps: `junit-jupiter`, `assertj-core`, `mockito-junit-jupiter`
+- ! JaCoCo with `minimum = 0.85` line coverage
+- ! SpotBugs plugin for static analysis
+
+**Gradle** (`build.gradle.kts`):
+```kotlin
+plugins { java; jacoco; id("com.github.spotbugs") version "6.0.0" }
+java { toolchain { languageVersion = JavaLanguageVersion.of(21) } }
+dependencies {
+    testImplementation("org.junit.jupiter:junit-jupiter:5.11.0")
+    testImplementation("org.assertj:assertj-core:3.26.0")
+    testImplementation("org.mockito:mockito-junit-jupiter:5.14.0")
+}
+tasks.test { useJUnitPlatform() }
+tasks.jacocoTestCoverageVerification {
+    violationRules { rule { limit { minimum = "0.85".toBigDecimal() } } }
+}
+```
+
+## Anti-Patterns
+
+Items marked ⊗ in Standards above are not repeated here.
+
+- ≉ **Checked exceptions for everything**: Reserve for truly recoverable conditions
+- ≉ **God classes**: Keep <500 lines; extract service/strategy/helper
+- ≉ **`Collectors.toList()`**: Prefer `Stream.toList()` (Java 16+)
+
+## Hygiene
+
+**Types:**
+- ⊗ Raw types (`List`, `Map`, `Optional`) without type parameters — always parameterize
+- ⊗ `Object` as parameter or return type where a concrete type or bounded wildcard is knowable
+- ⊗ `@SuppressWarnings("unchecked")` without an inline comment proving the cast is safe
+
+**Error handling:**
+- ⊗ Empty `catch (Exception e) {}` — handle, log with context, or re-throw as a typed exception
+- ⊗ `e.printStackTrace()` as the sole handler — use structured logging and propagate or wrap
+- ⊗ Returning `null` from public methods to signal failure — use `Optional<T>` or throw
+
+**Dead code:**
+- ~ SpotBugs (in build config) detects `DLS_DEAD_LOCAL_STORE` and unreachable code
+- ~ PMD rules `UnusedPrivateMethod` and `UnusedPrivateField` catch dead private symbols
+- ~ Run `gradle dependencies --configuration runtimeClasspath` to audit unused dependencies
+
+## Compliance Checklist
+
+- ! Javadoc on all public APIs
+- ! See [testing.md](../coding/testing.md) for testing requirements
+- ! Use JUnit 5 + AssertJ + Mockito
+- ! Use records for data carriers; sealed types for closed hierarchies
+- ! Use virtual threads for I/O-bound concurrency (Java 21+)
+- ! Try-with-resources for all `AutoCloseable`; ⊗ manual `.close()`
+- ⊗ Return `null` from public methods; raw types; field injection
+- ⊗ `synchronized` with virtual threads
+- ! Run `task check` before commit