@deftai/directive-content 0.55.0

package/languages/r.md

@@ -0,0 +1,163 @@
+# R Standards
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**⚠️ See also**: [main.md](../../main.md) | [PROJECT.md](../../PROJECT.md)
+
+**Stack**: R 4.3+, tidyverse; Packages: devtools/usethis; Testing: testthat 3; Docs: roxygen2; Lint: lintr; Style: styler
+
+## Standards
+
+### Documentation
+- ! roxygen2 comments (`#'`) for all exported functions, classes, and datasets
+- ! Document `@param`, `@return`, `@examples`, `@export` for public functions
+- ! Include a `README.Rmd` or `README.md` for packages
+- ~ Use `@seealso` and `@family` to cross-reference related functions
+
+### Testing
+See [testing.md](../coding/testing.md).
+
+- ! Use testthat 3 (`test_that()`, `expect_*()`)
+- ! Place tests in `tests/testthat/`; files: `test-*.R`
+- ~ Use snapshot tests (`expect_snapshot()`) for complex output
+
+### Coverage
+- ! ≥85% coverage (measured via covr)
+- ! Count R/\*
+- ! Exclude entry points, generated files, vignettes
+
+### Style
+- ! Follow [Tidyverse Style Guide](https://style.tidyverse.org/)
+- ! Use lintr for static analysis (project `.lintr` config checked in)
+- ! Use styler for auto-formatting
+- ! 2-space indentation, no tabs
+- ! Line length ≤80 characters
+
+### Naming Conventions
+- ! `snake_case` for functions, variables, and file names: `read_data()`, `user_count`
+- ! `PascalCase` for R6/S4 class names: `DataProcessor`, `ModelConfig`
+- ! `UPPER_SNAKE_CASE` for true constants
+- ! Prefix internal/non-exported functions with `.`: `.validate_input()`
+- ⊗ Dots in function names for new code (`read.csv` style): use `snake_case`
+- ⊗ Single-letter variable names except in math/formula contexts (`x`, `y`, `n`)
+
+### Types & Data
+- ! Use tibbles (`tibble`/`data.frame`) over lists for tabular data
+- ! Use explicit types: `integer(1)`, `character(0)`, `logical(1)` for scalars
+- ~ Use `rlang::check_required()` / `rlang::abort()` for argument validation
+- ~ Use named lists or S3/R6 classes for structured non-tabular data
+- ⊗ Use `T`/`F` — always spell out `TRUE`/`FALSE`
+- ⊗ Rely on partial argument matching
+
+### Functions
+- ! Pure functions preferred: same inputs → same outputs, no side effects
+- ! One function per purpose; keep under 50 lines where practical
+- ! Use `...` (dots) deliberately; document what they pass to
+- ⊗ Modify global state from inside functions (`<<-`, `assign()` to `.GlobalEnv`)
+- ~ Use `invisible()` for functions called for side effects that return invisibly
+- ~ Use `tryCatch()` / `withCallingHandlers()` for error handling
+
+### Dependencies
+- ! Minimize dependencies; use `Imports` not `Depends` in DESCRIPTION
+- ! Pin major versions in `renv.lock` for reproducibility
+- ! Use `renv` for project-level dependency isolation
+- ⊗ Use `library()` inside package code — use `::` or `@importFrom`
+- ~ Use `Suggests` for test/vignette-only dependencies
+
+### Vectorization & Performance
+- ! Prefer vectorized operations over explicit loops
+- ~ Use `purrr::map()` family for functional iteration
+- ~ Use `data.table` or `dplyr` for data manipulation (not base `for` loops on data frames)
+- ≉ Use `apply()` family when `purrr` or vectorized alternatives exist
+- ≉ Grow vectors in a loop (`c(vec, new_elem)`) — pre-allocate instead
+
+### Pipelines
+- ! Use native pipe `|>` (R 4.1+) or `%>%` from magrittr
+- ! Keep pipe chains readable (one operation per line)
+- ≉ Pipe chains longer than 10 steps — extract into named intermediate variables or functions
+- ~ Use `.data` and `.env` pronouns in tidy evaluation for clarity
+
+### Reproducibility
+- ! Use `renv` for project dependency snapshots
+- ! Set `set.seed()` before any stochastic operation; document seed in reports
+- ! Use relative paths; ⊗ absolute paths or `setwd()`
+- ~ Use `here::here()` for project-relative paths
+- ~ Use Quarto or R Markdown for reproducible reports
+
+### Security
+- ⊗ Hardcode secrets or credentials in source
+- ! Validate/sanitize all external inputs (file paths, user data, API responses)
+- ~ Use `.Renviron` for secrets; load via `Sys.getenv()`
+
+### Telemetry
+- ~ Structured logging (logger, futile.logger) for production
+- ? OpenTelemetry (via REST/Python bridge) for distributed tracing
+
+## Commands
+
+See [commands.md](./commands.md).
+
+## Patterns
+
+### Testing (testthat 3)
+```r
+test_that("calculate_mean returns correct mean", {
+  expect_equal(calculate_mean(c(1, 2, 3)), 2)
+  expect_equal(calculate_mean(c(10, 20)), 15)
+})
+
+test_that("calculate_mean errors on non-numeric input", {
+  expect_error(calculate_mean("abc"), "must be numeric")
+})
+
+test_that("calculate_mean handles NA with na.rm", {
+  expect_equal(calculate_mean(c(1, NA, 3), na.rm = TRUE), 2)
+  expect_equal(calculate_mean(c(1, NA, 3), na.rm = FALSE), NA_real_)
+})
+```
+
+### roxygen2 Documentation
+```r
+#' @param x Numeric vector. @param weights Numeric vector (same length). @param na.rm Remove NAs?
+#' @return Single numeric. @export
+weighted_mean <- function(x, weights, na.rm = FALSE) {
+  stopifnot(is.numeric(x), is.numeric(weights), length(x) == length(weights))
+  if (na.rm) { keep <- !is.na(x) & !is.na(weights); x <- x[keep]; weights <- weights[keep] }
+  sum(x * weights) / sum(weights)
+}
+```
+
+### Tidy Pipeline
+```r
+summary_by_group <- raw_data |>
+  filter(!is.na(value)) |> group_by(category) |>
+  summarise(mean_val = mean(value), n = n(), .groups = "drop") |>
+  arrange(desc(mean_val))
+```
+
+### Error Handling (rlang)
+```r
+read_config <- function(path) {
+  if (!file.exists(path)) rlang::abort(paste0("Config not found: ", path), class = "config_not_found_error")
+  tryCatch(yaml::read_yaml(path), error = function(e) rlang::abort("Failed to parse config", parent = e))
+}
+```
+
+## Anti-Patterns
+
+Items marked ⊗ in Standards above are not repeated here.
+
+- ≉ **Dot-separated names** (`my.function`): Use `snake_case`
+- ≉ **`sapply()`**: Use `vapply()` or `purrr::map_*()`
+- ≉ **Pipe chains >10 steps**: Extract named intermediates
+
+## Compliance Checklist
+
+- ! roxygen2 docs on all exported functions
+- ! See [testing.md](../coding/testing.md) for testing requirements
+- ! testthat 3 for unit tests; ≥85% coverage via covr
+- ! lintr + styler configured and enforced
+- ! Tidyverse style; `snake_case` naming; `TRUE`/`FALSE` spelled out
+- ! `renv` for dependency reproducibility
+- ⊗ `T`/`F`, `<<-`, `setwd()`, `library()` in packages, absolute paths
+- ! Run `task check` before commit

package/languages/rust.md

@@ -0,0 +1,216 @@
+# Rust Standards
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**⚠️ See also**: [main.md](../../main.md) | [PROJECT.md](../../PROJECT.md)
+
+**Stack**: Rust (latest stable); Build: Cargo; Testing: built-in `#[test]` + proptest; Lint: clippy; Format: rustfmt; Docs: rustdoc
+
+## Standards
+
+### Documentation
+- ! rustdoc comments (`///`) on all public items (functions, structs, enums, traits, modules)
+- ! Include `# Examples` section with runnable doc-tests for public API
+- ! Module-level docs (`//!`) explaining purpose and usage
+- ~ Use `# Errors`, `# Panics`, `# Safety` sections where applicable
+- ⊗ `#[allow(missing_docs)]` on public items without justification
+
+### Testing
+See [testing.md](../coding/testing.md).
+
+- ! Unit tests in `#[cfg(test)] mod tests` at bottom of each module
+- ! Integration tests in `tests/` directory for public API
+- ! Use `#[should_panic]` or `assert!(result.is_err())` for error cases
+- ~ Use proptest or quickcheck for property-based testing
+- ~ Use doc-tests as living examples (they run during `cargo test`)
+
+### Coverage
+- ! ≥80% coverage (measured via cargo-tarpaulin or llvm-cov)
+- ! Count src/**
+- ! Exclude main.rs entry points, generated code, build scripts
+
+### Style
+- ! Run rustfmt on all code (project `rustfmt.toml` checked in)
+- ! Run clippy with `#![deny(clippy::all)]` at crate level
+- ! `#![deny(clippy::pedantic)]` for library crates
+- ! 4-space indentation (rustfmt default)
+- ! Line length ≤100 characters
+- ~ Use `#![warn(clippy::nursery)]` for additional catches
+
+### Naming Conventions
+- ! `snake_case` for functions, methods, variables, modules, crate names
+- ! `PascalCase` for types (structs, enums, traits), type parameters
+- ! `SCREAMING_SNAKE_CASE` for constants and statics
+- ! Prefix lifetime parameters with `'`: `'a`, `'input`
+- ! Trait names: prefer adjective/verb forms: `Display`, `Iterator`, `Send`
+- ⊗ Hungarian notation or type prefixes
+- ~ Getter methods: use field name directly (`fn name(&self)` not `fn get_name`)
+
+### Ownership & Borrowing
+- ! Prefer borrowing (`&T`, `&mut T`) over cloning
+- ! Use `Clone` only when ownership transfer is truly needed
+- ! Prefer `&str` over `String` in function parameters
+- ! Prefer `&[T]` over `Vec<T>` in function parameters
+- ⊗ `.unwrap()` or `.expect()` in library code — return `Result` or `Option`
+- ~ Use `Cow<'_, str>` when a function may or may not need to allocate
+- ≉ Excessive `.clone()` to appease the borrow checker — redesign ownership
+
+### Error Handling
+- ! Use `Result<T, E>` for recoverable errors; define custom error types
+- ! Use `thiserror` for library error types; `anyhow` for application error types
+- ! Implement `std::error::Error` for all custom error types
+- ! Use `?` operator for error propagation
+- ⊗ `.unwrap()` in production code (except after infallible checks with comments)
+- ⊗ `panic!()` for expected error conditions
+- ~ Use `#[must_use]` on functions returning `Result` or important values
+
+### Concurrency
+- ! Use `Send` + `Sync` bounds correctly; understand their implications
+- ! Prefer channels (`mpsc`, `crossbeam`) over shared mutable state
+- ! Use `Arc<Mutex<T>>` or `Arc<RwLock<T>>` when shared state is necessary
+- ⊗ `unsafe` to circumvent Send/Sync bounds
+- ~ Use `tokio` or `async-std` for async I/O; avoid mixing runtimes
+- ~ Prefer `RwLock` over `Mutex` for read-heavy workloads
+
+### Unsafe Code
+- ! Minimize `unsafe` blocks; isolate behind safe abstractions
+- ! Document `# Safety` section explaining invariants for every `unsafe fn`
+- ! Document `// SAFETY:` comment on every `unsafe` block explaining why it's sound
+- ⊗ `unsafe` without clear justification and safety proof
+- ~ Use `#![forbid(unsafe_code)]` for crates that don't need it
+
+### Dependencies
+- ! Pin dependencies in `Cargo.lock` (always commit for binaries)
+- ! Audit dependencies with `cargo-audit`
+- ! Minimize dependency count; prefer `std` library functionality
+- ~ Use `cargo-deny` to enforce license and duplicate dependency policies
+- ≉ `*` version specifiers in `Cargo.toml`
+
+### Performance
+- ! Use iterators and zero-cost abstractions over manual loops where idiomatic
+- ! Prefer stack allocation; use `Box<T>` only when heap is necessary
+- ~ Use `#[inline]` sparingly and only with benchmarks to justify
+- ~ Profile with `criterion` for benchmarks; `perf` or `flamegraph` for profiling
+- ≉ Premature optimization over readability
+
+### Macros
+- ~ Prefer functions and generics over macros when possible
+- ! Document all `macro_rules!` with examples
+- ! Keep macro complexity minimal; extract logic into functions
+- ⊗ Macros that generate non-obvious control flow
+
+### Security
+- ⊗ Hardcode secrets or credentials in source
+- ! Validate all external inputs (file paths, network data, user input)
+- ! Use `secrecy` crate for sensitive values (keys, tokens)
+- ~ Use `zeroize` for clearing secrets from memory
+
+### Telemetry
+- ~ Use `tracing` crate for structured, async-aware logging
+- ~ Use `tracing-opentelemetry` for distributed tracing
+- ? Use `metrics` crate for Prometheus-compatible metrics
+
+## Commands
+
+See [commands.md](./commands.md).
+
+## Patterns
+
+### Error Handling (thiserror)
+```rust
+#[derive(Debug, thiserror::Error)]
+pub enum AppError {
+    #[error("config not found: {path}")] ConfigNotFound { path: String },
+    #[error("invalid config: {0}")] InvalidConfig(String),
+    #[error(transparent)] Io(#[from] std::io::Error),
+}
+
+pub fn load_config(path: &str) -> Result<Config, AppError> {
+    if !std::path::Path::new(path).exists() {
+        return Err(AppError::ConfigNotFound { path: path.to_string() });
+    }
+    let content = std::fs::read_to_string(path)?;
+    parse_config(&content).map_err(AppError::InvalidConfig)
+}
+```
+
+### Testing (Table-Driven)
+```rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+    #[test]
+    fn test_parse_amount() {
+        let cases = [("100", Ok(100)), ("0", Ok(0)), ("-5", Err("negative")), ("abc", Err("invalid"))];
+        for (input, expected) in cases {
+            match expected {
+                Ok(val) => assert_eq!(parse_amount(input).unwrap(), val, "{input}"),
+                Err(msg) => assert!(parse_amount(input).unwrap_err().to_string().contains(msg), "{input}"),
+            }
+        }
+    }
+}
+```
+
+### Builder Pattern
+```rust
+#[derive(Debug, Default)]
+pub struct RequestBuilder { url: String, timeout: Option<u64>, headers: Vec<(String, String)> }
+
+impl RequestBuilder {
+    pub fn new(url: impl Into<String>) -> Self { Self { url: url.into(), ..Default::default() } }
+    pub fn timeout(mut self, secs: u64) -> Self { self.timeout = Some(secs); self }
+    pub fn header(mut self, k: impl Into<String>, v: impl Into<String>) -> Self {
+        self.headers.push((k.into(), v.into())); self
+    }
+    pub fn build(self) -> Result<Request, BuildError> { Ok(Request { /* ... */ }) }
+}
+```
+
+### Structured Logging (tracing)
+```rust
+#[instrument(skip(db), fields(user_id = %user_id))]
+pub async fn get_user(db: &Pool, user_id: i64) -> Result<User, AppError> {
+    info!("fetching user");
+    let user = db.query_one("SELECT ...", &[&user_id]).await?;
+    if user.is_inactive() { warn!("inactive user accessed"); }
+    Ok(user)
+}
+```
+
+## Anti-Patterns
+
+Items marked ⊗ in Standards above are not repeated here.
+
+- ≉ **`Arc<Mutex<T>>` as first resort**: Consider channels/message passing
+- ≉ **Stringly-typed errors**: Use `thiserror`
+- ≉ **God-struct with many `Option` fields**: Use builder pattern or state types
+- ≉ **`Box<dyn Error>` in libraries**: Define specific error enums
+
+## Hygiene
+
+**Types:**
+- ⊗ `dyn Any` or `Box<dyn Any>` where a concrete type or typed trait object is knowable
+- ⊗ `#[allow(unused)]` or `#[allow(dead_code)]` attributes to suppress rather than remove dead code
+
+**Error handling:**
+- ⊗ `.unwrap()` or `.expect()` outside test code — use `?` or explicit match
+- ⊗ `let _ = result` to silently ignore a `Result` or `Option` — handle or document why safe
+- ⊗ Match arms `_ => {}` or `Err(_) => {}` that swallow errors without logging or propagating
+
+**Dead code:**
+- ~ `cargo check` warns on unused items; `cargo clippy` detects dead helpers and unreachable branches
+- ~ Use `cargo +nightly udeps` to detect unused dependencies in `Cargo.toml`
+- ⊗ Commented-out code — delete; version control preserves history
+
+## Compliance Checklist
+
+- ! rustdoc on all public items with examples
+- ! See [testing.md](../coding/testing.md) for testing requirements
+- ! Unit + integration tests; ≥80% coverage
+- ! rustfmt + clippy (pedantic for libs) enforced
+- ! Custom error types via thiserror/anyhow; no `.unwrap()` in production
+- ! `unsafe` minimized, documented, and justified
+- ! `Cargo.lock` committed (binaries); `cargo-audit` clean
+- ⊗ `.unwrap()`, `panic!()`, unguarded `unsafe`, excessive `.clone()`
+- ! Run `task check` before commit

package/languages/sql.md

@@ -0,0 +1,216 @@
+# SQL Standards
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**⚠️ See also**: [main.md](../../main.md) | [PROJECT.md](../../PROJECT.md)
+
+**Stack**: ANSI SQL (dialect-agnostic defaults); Adapts to: PostgreSQL, MySQL/MariaDB, SQL Server, SQLite, Oracle; Migrations: Flyway / Liquibase / framework-native; Lint: sqlfluff
+
+## Standards
+
+### Documentation
+- ! Comment every non-trivial query, view, function, and stored procedure
+- ! Document purpose, parameters, and return values for stored procedures/functions
+- ! Include a data dictionary or schema docs for every database
+- ~ Use inline comments (`--`) for clause-level explanations in complex queries
+
+### Testing
+See [testing.md](../coding/testing.md).
+
+- ! Test migrations up and down (rollback)
+- ! Test stored procedures, functions, and triggers with known inputs/outputs
+- ~ Use test fixtures or seed data scripts for reproducible integration tests
+- ~ Test edge cases: NULLs, empty sets, boundary values, large datasets
+
+### Style & Formatting
+- ! UPPERCASE for SQL keywords: `SELECT`, `FROM`, `WHERE`, `JOIN`, `INSERT`, `UPDATE`
+- ! Lowercase for identifiers (tables, columns, aliases): `users`, `created_at`
+- ! One clause per line for readability (`SELECT`, `FROM`, `WHERE`, `JOIN` each on own line)
+- ! Indent continuation lines (subqueries, `AND`/`OR`, `CASE` branches)
+- ! Use sqlfluff (or equivalent) for automated linting
+- ! Line length ≤120 characters
+- ~ Align `ON` clauses vertically when multiple joins are present
+
+### Naming Conventions
+- ! `snake_case` for all identifiers: tables, columns, indexes, constraints
+- ! Singular nouns for table names: `user`, `order`, `product` (not `users`, `orders`)
+- ! Descriptive column names: `created_at`, `is_active`, `total_amount`
+- ! Prefix boolean columns with `is_`, `has_`, or `can_`: `is_active`, `has_shipped`
+- ! Name primary keys `id` or `{table}_id`; foreign keys `{referenced_table}_id`
+- ! Name indexes: `ix_{table}_{column(s)}`
+- ! Name constraints: `pk_{table}`, `fk_{table}_{ref_table}`, `uq_{table}_{column}`, `ck_{table}_{rule}`
+- ⊗ Reserved words as identifiers (even if quoted)
+- ⊗ Abbreviations in names unless universally understood (`id`, `url`, `ip`)
+
+### Queries
+- ! Use explicit column lists — ⊗ `SELECT *` in application code or views
+- ! Use explicit `JOIN` syntax — ⊗ implicit joins (comma-separated `FROM`)
+- ! Qualify column names with table aliases in multi-table queries
+- ! Use short, meaningful aliases: `u` for `user`, `o` for `order`
+- ! Use `COALESCE()` over vendor-specific null functions (`NVL`, `IFNULL`) where portable
+- ~ Use CTEs (`WITH`) for complex queries instead of deeply nested subqueries
+- ~ Use `EXISTS` over `IN` for correlated subqueries (better optimizer hints)
+- ≉ `SELECT DISTINCT` to mask duplicate-producing joins — fix the join instead
+- ≉ `ORDER BY` column position (`ORDER BY 1, 2`) — use column names
+
+### Parameterization & Security
+- ! Use parameterized queries / prepared statements for all dynamic values
+- ⊗ String concatenation for query building (SQL injection vector)
+- ⊗ Interpolating user input directly into SQL
+- ! Validate and sanitize inputs at the application layer before query execution
+- ! Apply least-privilege: application accounts get only required permissions
+- ~ Use row-level security (RLS) where supported for multi-tenant data
+
+### Schema Design
+- ! Every table has a primary key
+- ! Use appropriate data types: don't store dates as strings, money as floats, etc.
+- ! Define foreign key constraints for referential integrity
+- ! Add `NOT NULL` constraints where business logic requires a value
+- ! Add `CHECK` constraints for domain validation (e.g., `CHECK (quantity >= 0)`)
+- ~ Normalize to 3NF minimum; denormalize deliberately with documentation
+- ~ Add `created_at` and `updated_at` timestamps to mutable tables
+- ~ Use `UUID` or `BIGINT` for primary keys (prefer `UUID` for distributed systems)
+- ≉ Store JSON blobs where relational columns would serve better
+- ⊗ Use `FLOAT`/`DOUBLE` for monetary values — use `DECIMAL`/`NUMERIC`
+
+### Indexing
+- ! Index all foreign key columns
+- ! Index columns used in `WHERE`, `JOIN`, `ORDER BY` if query frequency justifies it
+- ! Review and document index strategy per table
+- ~ Use composite indexes that match query patterns (leftmost prefix rule)
+- ~ Use partial/filtered indexes for frequently queried subsets
+- ≉ Over-index: each index adds write overhead — justify with query patterns
+- ⊗ Index every column "just in case"
+
+### Migrations
+- ! Use versioned, sequential migration files (not ad-hoc DDL)
+- ! Every migration must be reversible (up + down)
+- ! Test migrations against a copy of production schema before deploying
+- ! Use transactions for DDL where supported (PostgreSQL)
+- ~ Use idempotent migrations (`IF NOT EXISTS`, `IF EXISTS`) for resilience
+- ⊗ Modify or delete previously applied migration files
+
+### Transactions & Concurrency
+- ! Use explicit transactions for multi-statement operations
+- ! Keep transactions as short as possible
+- ! Choose appropriate isolation level for the use case
+- ~ Use `SELECT ... FOR UPDATE` when reading rows that will be updated
+- ⊗ Long-running transactions that hold locks across user interactions
+- ⊗ Implicit autocommit for multi-step business operations
+
+### Performance
+- ! Use `EXPLAIN` / `EXPLAIN ANALYZE` to validate query plans for critical queries
+- ! Avoid N+1 query patterns — use joins or batch queries
+- ! Paginate large result sets (`LIMIT`/`OFFSET` or keyset pagination)
+- ~ Prefer keyset pagination (`WHERE id > ?`) over `OFFSET` for large tables
+- ~ Use materialized views or caching for expensive, infrequently-changing aggregations
+- ≉ Functions on indexed columns in `WHERE` clauses (defeats index usage)
+- ⊗ Cartesian joins (missing `ON` / `WHERE` clause)
+- ⊗ Unbounded `SELECT` without `LIMIT` on large tables in application code
+
+### Stored Procedures & Functions
+- ~ Keep business logic in the application layer; use procedures for data-intensive ops
+- ! Document parameters, return types, and side effects
+- ! Handle errors explicitly (`RAISE` / `SIGNAL` / `THROW`)
+- ⊗ Deeply nested stored procedure call chains (hard to debug and test)
+
+### Telemetry
+- ~ Log slow queries (configure slow query log threshold)
+- ~ Monitor index usage and table bloat
+- ? Use query tagging (comments with trace IDs) for distributed tracing
+
+## Commands
+
+```bash
+task db:migrate          # Run pending migrations
+task db:rollback         # Roll back last migration
+task db:seed             # Load seed/fixture data
+task db:reset            # Drop, create, migrate, seed
+task db:lint             # Lint SQL with sqlfluff (or `task sql:lint`)
+task db:format           # Format SQL with sqlfluff fix (or `task sql:fmt`)
+task db:schema           # Dump current schema
+task quality             # All quality checks
+```
+
+**Note**: Single-language projects ! use generic names. Multi-language projects ! use namespaced names. See [taskfile.md](../tools/taskfile.md#naming-conventions).
+
+## Patterns
+
+### Parameterized Query (Application Code)
+```sql
+-- CORRECT: parameterized
+SELECT id, email, created_at
+FROM user
+WHERE email = $1
+  AND is_active = TRUE;
+
+-- Framework equivalent (pseudocode):
+-- db.query("SELECT id, email FROM user WHERE email = $1", [user_email])
+```
+
+### CTE for Readability
+```sql
+WITH active_orders AS (
+    SELECT o.user_id, COUNT(*) AS order_count, SUM(o.total_amount) AS total_spent
+    FROM order AS o
+    WHERE o.status = 'active'
+      AND o.created_at >= CURRENT_DATE - INTERVAL '30 days'
+    GROUP BY o.user_id
+)
+SELECT u.id, u.email, ao.order_count, ao.total_spent
+FROM user AS u
+INNER JOIN active_orders AS ao ON ao.user_id = u.id
+WHERE ao.total_spent > 100.00
+ORDER BY ao.total_spent DESC;
+```
+
+### Migration (Flyway-style)
+```sql
+-- V2__add_user_preferences.sql
+
+-- Up
+CREATE TABLE IF NOT EXISTS user_preference (
+    id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    user_id     UUID NOT NULL REFERENCES user (id) ON DELETE CASCADE,
+    key         VARCHAR(100) NOT NULL,
+    value       TEXT,
+    created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    CONSTRAINT uq_user_preference_key UNIQUE (user_id, key)
+);
+
+CREATE INDEX ix_user_preference_user_id ON user_preference (user_id);
+
+-- Down (in separate file or rollback section)
+-- DROP TABLE IF EXISTS user_preference;
+```
+
+### Keyset Pagination
+```sql
+-- Efficient pagination for large tables (avoids OFFSET scan)
+SELECT id, email, created_at
+FROM user
+WHERE created_at < $1   -- last seen timestamp
+  AND id < $2            -- tiebreaker
+ORDER BY created_at DESC, id DESC
+LIMIT 25;
+```
+
+## Anti-Patterns
+
+Items marked ⊗ in Standards above are not repeated here.
+
+- ≉ **`HAVING` without `GROUP BY`**: Use `WHERE` for row-level filters
+- ≉ **Nested subqueries >2 levels deep**: Refactor with CTEs
+- ≉ **`NOT IN` with nullable columns**: Use `NOT EXISTS` instead (NULL semantics)
+
+## Compliance Checklist
+
+- ! Parameterized queries for all user-facing data access
+- ! Explicit column lists, explicit `JOIN` syntax, qualified column names
+- ! Primary key on every table; foreign keys with constraints
+- ! Versioned migrations; tested up and down
+- ! `EXPLAIN ANALYZE` reviewed for high-traffic queries
+- ! sqlfluff lint passes; keywords uppercase, identifiers lowercase `snake_case`
+- ⊗ `SELECT *`, implicit joins, string concatenation in queries, `FLOAT` for money
+- ! Run `task db:lint` before commit