prr-kit 1.1.3 → 1.2.1

package/src/prr/data/stacks/docker.md

@@ -0,0 +1,79 @@
+# Docker — Stack-Specific Review Rules
+
+> Applies to: GR · SR · PR · AR · BR
+> Detection signals: `Dockerfile*`, `docker-compose*.yml`, `.dockerignore`, `FROM `, `RUN `, `COPY `, `EXPOSE`, `docker` in CI, `compose.yml`
+
+---
+
+## Security
+
+- **[CRITICAL]** Container running as `root` (default) → container escape = root on host. Add `USER nonroot` after creating non-root user.
+- **[CRITICAL]** Secrets passed as `ENV` or `ARG` in Dockerfile → visible in image layers and `docker inspect`. Use Docker BuildKit secrets (`--secret`) or runtime env injection.
+- **[CRITICAL]** `.env` file copied into image via `COPY . .` without `.dockerignore` → secrets in image layer.
+- **[HIGH]** Base image tagged as `latest` → non-deterministic builds, unexpected CVEs from upstream updates. Use `node:20.11.1-alpine3.19`.
+- **[HIGH]** Outdated base image with known CVEs → scan with `docker scout cves` or Trivy.
+- **[HIGH]** `docker-compose.yml` with `privileged: true` without justification → container escapes host namespaces.
+- **[HIGH]** `volumes: /:/host` or similar host root mount → full filesystem access from container.
+- **[HIGH]** Ports bound to `0.0.0.0` for internal services → exposed to all interfaces. Use `127.0.0.1:port:port`.
+- **[HIGH]** Hardcoded credentials in `docker-compose.yml` committed to VCS → credential exposure.
+- **[MEDIUM]** `--cap-add SYS_ADMIN` or `--security-opt seccomp=unconfined` → elevated privileges.
+- **[MEDIUM]** No read-only filesystem (`--read-only`) for containers that don't need write access.
+- **[LOW]** Docker socket (`/var/run/docker.sock`) mounted in container → full Docker daemon access = host escape.
+
+---
+
+## Performance
+
+- **[HIGH]** Layer order wrong — source code copied before `package.json` + install → cache invalidated every code change. Copy lockfile + install first, then source.
+- **[HIGH]** No multi-stage build for compiled languages → dev deps and build tools in production image.
+- **[HIGH]** Large files/directories not in `.dockerignore` → slow build context transfer on every build.
+- **[MEDIUM]** `RUN apt-get install` without `--no-install-recommends` → bloated image with unnecessary packages.
+- **[MEDIUM]** Multiple separate `RUN` commands → extra layers. Chain with `&&` and `\`.
+- **[MEDIUM]** Not using `--mount=type=cache` for package manager cache in BuildKit → re-downloading packages.
+- **[MEDIUM]** Base image not using Alpine/distroless → unnecessarily large image.
+- **[MEDIUM]** `COPY . .` before `npm install` → code changes invalidate dependency cache.
+- **[LOW]** Not squashing layers in final image → history reveals sensitive intermediate steps.
+- **[LOW]** `apt-get` without `apt-get clean && rm -rf /var/lib/apt/lists/*` → package cache in layer.
+
+---
+
+## Architecture
+
+- **[HIGH]** Application state written to container filesystem → lost on restart. Use named volumes for persistent data.
+- **[HIGH]** Missing `HEALTHCHECK` → orchestrator can't detect unhealthy container, continues sending traffic.
+- **[HIGH]** Single container running multiple services → violates SRP, harder to scale, complicated restarts.
+- **[HIGH]** Secret rotation requires image rebuild → use runtime secret injection (Vault, K8s Secrets, AWS SSM).
+- **[MEDIUM]** `docker-compose.yml` used in production without orchestration → no auto-scaling, rolling updates.
+- **[MEDIUM]** Config hardcoded in Dockerfile → image not portable across environments. Use env vars + config files.
+- **[MEDIUM]** `depends_on` used without health check condition → service starts before dependency is ready.
+- **[MEDIUM]** Not using `restart: unless-stopped` / `restart: on-failure` → container doesn't recover from crashes.
+- **[LOW]** Missing `ENTRYPOINT` — only `CMD` → command accidentally overridden at runtime.
+- **[LOW]** Not pinning Docker Compose version in CI → behavior changes with compose updates.
+
+---
+
+## Code Quality
+
+- **[HIGH]** No `.dockerignore` file → unpredictable, large build context (`.git`, `node_modules`, `.env`).
+- **[HIGH]** `ADD url ./` instead of `RUN curl + COPY` → `ADD` fetches during build, no verification.
+- **[MEDIUM]** `ADD` used when `COPY` sufficient — `ADD` has implicit tar extraction and remote URL fetching; `COPY` is explicit.
+- **[MEDIUM]** `ENV` variables not documented → unclear what configuration is available.
+- **[MEDIUM]** `EXPOSE` port not matching actual application port → confusing, may break port mapping.
+- **[MEDIUM]** Non-deterministic `apt-get` package versions → builds differ over time. Pin package versions.
+- **[LOW]** Missing `LABEL` annotations (maintainer, version, description) → untracked images in registry.
+- **[LOW]** Long `RUN` command without line continuation `\` → unreadable Dockerfile.
+- **[LOW]** Not using `WORKDIR` → inconsistent working directory, fragile relative paths.
+
+---
+
+## Common Bugs & Pitfalls
+
+- **[HIGH]** Process not handling `SIGTERM` → container doesn't stop gracefully, killed after timeout. Use `exec` form `["node", "app.js"]` not shell form.
+- **[HIGH]** PID 1 not reaping zombie processes → memory leak. Use `--init` flag or `tini` as init process.
+- **[HIGH]** `CMD ["npm", "start"]` without shell → environment variables from `ENV` not available in some contexts. Test both.
+- **[MEDIUM]** Container timezone different from host → cron jobs run at wrong time. Set `TZ` env var.
+- **[MEDIUM]** `COPY --chown` not used → files owned by root inside container, non-root user can't write.
+- **[MEDIUM]** DNS resolution failing in container → missing `--dns` or network mode mismatch.
+- **[MEDIUM]** Build arg (`ARG`) vs environment variable (`ENV`) confusion — `ARG` only available during build, `ENV` persists.
+- **[LOW]** Port already in use on host → `docker run` fails with `bind: address already in use`.
+- **[LOW]** Volume mount overwriting container files → `node_modules` from host overlays container's installed deps.

package/src/prr/data/stacks/drizzle.md

@@ -0,0 +1,54 @@
+# Drizzle ORM — Stack-Specific Review Rules
+
+> Applies to: GR · SR · PR · AR · BR
+> Detection signals: `drizzle-orm`, `from 'drizzle-orm'`, `drizzle()`, `pgTable`, `mysqlTable`, `sqliteTable`, `migrate()`, `drizzle-kit`
+
+---
+
+## Security
+- **[CRITICAL]** Raw SQL via `sql` tagged template literal with user input not parameterized (e.g., `sql\`WHERE name = '${userInput}'\``) → SQL injection. Use Drizzle's query builder or pass user values as parameterized bindings: `sql\`WHERE name = ${userInput}\`` (Drizzle auto-parameterizes interpolated values in the `sql` tag).
+- **[HIGH]** Drizzle schema file imported and exposed via an API route response → internal table structure, column names, and types leaked to clients. Never serialize schema objects into HTTP responses; expose only shaped DTOs.
+- **[HIGH]** No row-level access control in query layer → any authenticated user can query any row by guessing IDs. Add a `WHERE userId = currentUserId` (or equivalent tenant filter) to every query that returns user-owned data.
+- **[MEDIUM]** Database credentials stored in `drizzle.config.ts` and committed to the repository → credentials exposed in version control history. Read credentials from environment variables (`process.env.DATABASE_URL`) in the config file.
+- **[MEDIUM]** Migrations run with superuser DB credentials in production CI/CD pipeline → accidental schema destruction possible. Use a migration-only role with `CREATE`, `ALTER`, `DROP` on the app schema; separate from the runtime role.
+
+---
+
+## Performance
+- **[HIGH]** N+1 queries from nested `.findMany()` calls without using `.with()` for relations → one query fired per parent row to load children. Switch to Drizzle's relational query API with `.with({ relation: true })` to load related data in a single query.
+- **[HIGH]** No `.limit()` on list queries → full table scan returned to application memory, OOM risk on large tables. Every `findMany` or `select` on an unbounded table must include `.limit(n)`.
+- **[HIGH]** `db.select()` without column projection (no `{ field: table.field }` shape) → all columns fetched; breaks index-only scans and sends unnecessary data over the wire. Pass a columns object to `db.select({ id: table.id, name: table.name })` for every query.
+- **[MEDIUM]** Multi-table mutations (insert + update across tables) not wrapped in a transaction → partial failure leaves data inconsistent. Use `db.transaction(async (tx) => { ... })` for all operations that must be atomic.
+- **[MEDIUM]** Indexes not defined in the Drizzle schema alongside the table → indexes exist only in migration SQL but not tracked in the schema, causing drift. Define all indexes using `.index()` or `.uniqueIndex()` in the same schema file as the table.
+- **[MEDIUM]** `drizzle-kit push` used in staging or production to apply schema changes → `push` may drop and recreate columns, causing data loss. Use `drizzle-kit generate` to produce migration SQL files, review them, then apply with `drizzle-kit migrate`.
+- **[LOW]** Connection not pooled (no PgBouncer or application-level pool like `pg-pool`) → new TCP connection opened per request; connection exhaustion under load. Configure a connection pool and pass the pooled client to `drizzle()`.
+
+---
+
+## Architecture
+- **[HIGH]** Database queries written directly in API route handlers or controllers → no separation of data access from transport layer, making queries untestable in isolation. Extract all DB queries into a repository or data-access layer; import the repository into route handlers.
+- **[MEDIUM]** Drizzle's relational query API not used when related data is needed → developers write complex manual JOINs that are harder to maintain and more error-prone. Use `.query.table.findMany({ with: { relation: {} } })` for relation traversal.
+- **[MEDIUM]** Schema spread across many files without a barrel `schema.ts` export → Drizzle relations and `db` instance require all schema tables; missing tables cause runtime errors. Collect all table definitions in a single `schema.ts` (or `schema/index.ts`) barrel export passed to `drizzle()`.
+- **[MEDIUM]** No seed script for development database → developers set up data manually, causing environment divergence. Provide a `seed.ts` script using Drizzle inserts that can be run with `npx tsx seed.ts`.
+- **[LOW]** Table names in schema not matching actual database table names (no `{ name: 'actual_table' }` option) → Drizzle generates incorrect SQL, causing "relation does not exist" errors. Set the explicit table name string in `pgTable('actual_table_name', ...)` when it differs from the variable name.
+
+---
+
+## Code Quality
+- **[HIGH]** Column types in Drizzle schema not aligned with application TypeScript types (e.g., `text()` for a column that only holds enum values) → invalid values accepted at DB level. Use `text('col', { enum: ['a', 'b', 'c'] })` or add a Zod/Valibot parse step at the boundary.
+- **[HIGH]** `.returning()` omitted after `.insert()` when the generated ID or defaults are needed → `result` is an empty array, causing `undefined` reference on the next line. Chain `.returning()` to every INSERT that the application reads back.
+- **[MEDIUM]** `.notNull()` missing on columns that are logically required → `null` values accumulate and cause unexpected `null` checks throughout the codebase. Add `.notNull()` to every column the application treats as mandatory.
+- **[MEDIUM]** `.$type<T>()` not used for columns that hold branded or opaque types (e.g., `UserId`, `OrderId`) → plain `string` or `number` types allow mixing IDs across entities. Use `text('user_id').$type<UserId>()` to brand column types and catch cross-entity ID bugs at compile time.
+- **[MEDIUM]** Drizzle TypeScript types not inferred with `typeof table.$inferSelect` / `.$inferInsert` → manual type duplication drifts from schema over time. Use Drizzle's inferred types everywhere instead of hand-written interfaces.
+- **[LOW]** Table naming inconsistency between Drizzle variable name and the DB table name passed as first arg → confusion when reading error messages or raw SQL logs. Keep Drizzle variable name and table name string identical (both snake_case).
+
+---
+
+## Common Bugs & Pitfalls
+- **[HIGH]** `.insert().values()` result used without `.returning()` → the return value is a result metadata object (rowCount), not the inserted row; accessing `.id` returns `undefined`. Always add `.returning({ id: table.id })` (or the needed fields) after `.insert().values()`.
+- **[HIGH]** Relations defined in the Drizzle schema with `relations()` but `.with()` not used in the actual query → N+1 still occurs because `relations()` only informs the query API; it does not automatically join. Use `db.query.table.findMany({ with: { relation: {} } })` to activate the relation.
+- **[MEDIUM]** `drizzle-kit push` used against a production database → push computes a diff and may drop columns or tables to match the schema, causing irreversible data loss. Enforce a CI policy that only `drizzle-kit migrate` (with reviewed migration files) runs in production.
+- **[MEDIUM]** Database connection created inside a request handler (e.g., `const db = drizzle(new Pool(...))` per request) → new pool created for every request, exhausting DB connections rapidly. Create the `db` instance once at module initialization and reuse it.
+- **[MEDIUM]** `eq(table.col, undefined)` passed to a WHERE clause when an optional filter is absent → Drizzle generates `WHERE col = NULL` (never matches). Guard optional filters: `...(value !== undefined ? [eq(table.col, value)] : [])` using `and()`.
+- **[LOW]** Drizzle type inference breaking on complex union or conditional columns → TypeScript errors cascade through the codebase. Pin Drizzle and `drizzle-kit` to the same exact semver version and upgrade them together.
+

package/src/prr/data/stacks/dynamodb.md

@@ -0,0 +1,55 @@
+# DynamoDB — Stack-Specific Review Rules
+
+> Applies to: GR · SR · PR · AR · BR
+> Detection signals: `@aws-sdk/client-dynamodb`, `dynamoose`, `from 'dynamodb'`, `DynamoDB.DocumentClient`, `aws-sdk` with DynamoDB, `PK`/`SK` table design
+
+---
+
+## Security
+- **[CRITICAL]** IAM role or user has `dynamodb:*` on `*` (all tables) → compromise grants full read/write/delete access to every table. Scope IAM policies to specific table ARNs and only the required actions (e.g., `dynamodb:GetItem`, `dynamodb:PutItem`).
+- **[HIGH]** User-controlled input in `FilterExpression` or `KeyConditionExpression` without validation → logical injection allows querying unintended data. Validate all filter values against an allowlist; use `ExpressionAttributeValues` for all values.
+- **[HIGH]** DynamoDB table name constructed from user input → attacker can target arbitrary tables. Hardcode all table names; read them from environment variables set at deployment time.
+- **[HIGH]** No VPC endpoint for DynamoDB → traffic traverses the public internet. Create a VPC gateway endpoint and restrict outbound security group rules accordingly.
+- **[MEDIUM]** Sensitive attributes (PII, tokens) not encrypted at the attribute level → storage-layer encryption alone is insufficient. Use AWS Encryption SDK to encrypt sensitive values before writing to DynamoDB.
+- **[MEDIUM]** CloudTrail not enabled or DynamoDB data events not logged → no audit trail of who read or wrote which items. Enable CloudTrail with DynamoDB data event logging for tables with sensitive data.
+
+---
+
+## Performance
+- **[CRITICAL]** `Scan` used instead of `Query` for data retrieval → reads every item in the table, consuming full provisioned read capacity proportional to table size. Use `Query` with a partition key; reserve `Scan` for one-off administrative operations.
+- **[HIGH]** Hot partition key routing all traffic to a single partition (e.g., current date, fixed status string, or single tenant ID) → partitions cap at 3,000 RCU / 1,000 WCU; throttling occurs. Add a random suffix or shard number to distribute load.
+- **[HIGH]** Missing GSI for access patterns not served by the primary key → every such query falls back to a full `Scan`. Define GSIs for all known access patterns before table creation.
+- **[HIGH]** `FilterExpression` applied to `Scan` or `Query` results → filter runs after reading; full RCU cost charged for all items scanned. Encode filter criteria into the partition or sort key design.
+- **[MEDIUM]** Item size consistently above 10 KB → RCU/WCU rounds up per 4 KB read / 1 KB write. Store large payloads in S3; keep only a reference key in DynamoDB.
+- **[MEDIUM]** `ProjectionExpression` not specified → `GetItem` and `Query` return all attributes, wasting bandwidth and read capacity. Specify only the attributes the application needs.
+- **[LOW]** On-demand capacity used for predictable steady traffic → on-demand costs more per request than provisioned at stable load. Switch to provisioned capacity with auto-scaling.
+
+---
+
+## Architecture
+- **[CRITICAL]** Table designed relationally with one table per entity type (Users, Orders, Products) → DynamoDB has no cross-table JOINs; relational queries require multiple round trips. Use single-table design with overloaded PK/SK values.
+- **[HIGH]** Access patterns not defined before table schema is finalized → retrofitting requires expensive table rebuilds. Document all query patterns (PK=X, SK starts-with Y) before writing any table creation code.
+- **[HIGH]** Single-table design not used when entity types share access patterns (e.g., fetch user plus orders in one request) → requires two separate calls. Collapse entities into one table; use `Query` with `PK=userId` to retrieve all related items.
+- **[MEDIUM]** TTL attribute not set on ephemeral items (sessions, OTP tokens, locks) → items accumulate indefinitely, increasing storage cost and scan time. Define a Unix-epoch numeric TTL attribute and enable DynamoDB TTL.
+- **[MEDIUM]** DynamoDB Streams not used for event-driven side effects (cache invalidation, notifications) → polling or synchronous calls used instead. Enable Streams and attach a Lambda trigger.
+- **[LOW]** No CloudWatch capacity alarms configured → throttling goes undetected until user-visible errors occur. Set alarms at 80% of provisioned `ConsumedWriteCapacityUnits` / `ConsumedReadCapacityUnits`.
+
+---
+
+## Code Quality
+- **[HIGH]** Table names hardcoded as string literals throughout the codebase → renaming requires a grep-and-replace across all files. Centralize in a constants module or read from `process.env.TABLE_NAME`.
+- **[HIGH]** No error handling for `ProvisionedThroughputExceededException` → throttled requests fail permanently. Use the AWS SDK `maxAttempts` retry config and add exponential backoff for throttling errors.
+- **[MEDIUM]** `TransactWriteItems` not used for multi-item atomic operations (e.g., decrement inventory and create order) → partial success possible if one write fails. Use `TransactWriteItems` (up to 100 items) for all-or-nothing mutations.
+- **[MEDIUM]** Raw `DynamoDB.DocumentClient` used without an abstraction layer → marshall/unmarshall logic scattered throughout. Use DynamoDB Toolbox, Dynamoose, or a thin repository class.
+- **[MEDIUM]** Attribute names conflicting with DynamoDB reserved words (`name`, `status`, `date`, `key`) → queries without `ExpressionAttributeNames` throw `ValidationException`. Map reserved-word attributes using ExpressionAttributeNames.
+- **[LOW]** No integration tests against a local DynamoDB (DynamoDB Local or LocalStack) → key condition expression bugs only caught in production. Add DynamoDB Local to the test environment.
+
+---
+
+## Common Bugs & Pitfalls
+- **[HIGH]** `BatchWriteItem` response not checked for `UnprocessedItems` → DynamoDB may partially fail a batch silently. Always check `response.UnprocessedItems` and retry unprocessed items with exponential backoff.
+- **[HIGH]** Optimistic locking via `ConditionExpression` not used for concurrent updates → two concurrent requests read the same version, both write the incremented version, and one silently overwrites the other. Use `ConditionExpression: "version = :expected"` and increment version on every write.
+- **[MEDIUM]** `ConsistentRead: true` not used when strong consistency is needed after a write → eventual consistency may return stale data within the roughly 1-second replication window. Set `ConsistentRead: true` for reads that must reflect a preceding write.
+- **[MEDIUM]** Global table replication lag not accounted for in cross-region reads → a write in us-east-1 may not be visible in eu-west-1 for several seconds. Route post-write reads to the write region.
+- **[MEDIUM]** `UpdateItem` with `SET attr = :val` replacing a list attribute instead of appending → entire list overwritten when intent is to add one element. Use `SET listAttr = list_append(listAttr, :newItems)` to append.
+- **[LOW]** Sort key not planned at design time → adding a sort key later requires creating a new table and migrating all data. Decide on composite vs. simple key before the first deployment.

package/src/prr/data/stacks/electron.md

@@ -0,0 +1,44 @@
+# Electron — Stack-Specific Review Rules
+
+> Applies to: GR · SR · PR · AR · BR
+> Detection signals: `electron` in `dependencies` · `BrowserWindow` · `ipcMain` · `ipcRenderer` · `app.whenReady()` · `main.js` / `main.ts` as Electron entry
+
+---
+
+## Security
+
+- **[CRITICAL]** `contextIsolation: false` in `webPreferences` → renderer process has direct access to Node.js APIs; XSS in renderer = full system compromise.
+- **[CRITICAL]** `nodeIntegration: true` in `webPreferences` → full Node.js API surface exposed to renderer; one XSS = RCE.
+- **[CRITICAL]** `webSecurity: false` → disables CORS, allows loading local files from remote pages, enables cross-origin attacks.
+- **[HIGH]** IPC handler executing user-controlled commands: `ipcMain.on('run', (e, cmd) => exec(cmd))` → arbitrary command execution from renderer or compromised web content.
+- **[HIGH]** Loading remote URLs in `BrowserWindow` without a strict Content Security Policy → XSS attack surface.
+- **[HIGH]** `shell.openExternal(url)` with user-controlled URL → opens `file://`, `smb://`, or other dangerous protocol URIs. Validate scheme and host allowlist.
+- **[MEDIUM]** Bundling application without code signing → OS security warnings, easier to tamper with by local attacker.
+
+---
+
+## Performance
+
+- **[HIGH]** Synchronous IPC `ipcRenderer.sendSync()` → blocks renderer's UI thread until main process responds. Use async `ipcRenderer.invoke()` / `ipcMain.handle()`.
+- **[HIGH]** Sending large data (images, buffers) over IPC as serialized JSON → full serialize/deserialize cost. Use `SharedArrayBuffer` or write to a temp file and pass the path.
+- **[MEDIUM]** Invisible `BrowserWindow` kept alive indefinitely → each window has a full Chromium renderer process (~80-150 MB). Destroy when not needed.
+- **[LOW]** Requiring all Node modules at startup in main process → slow cold start. Use lazy requires inside handlers.
+
+---
+
+## Architecture
+
+- **[HIGH]** Business logic placed in renderer process → should live in main process or a dedicated Node service; renderer should be a thin UI layer communicating via IPC.
+- **[HIGH]** `remote` module (deprecated in Electron 12, removed in 14) still in use → security risk, use `contextBridge` to expose specific APIs to renderer.
+- **[MEDIUM]** Entire `ipcRenderer` object exposed via `contextBridge.exposeInMainWorld` → expose a minimal typed API, not the full IPC surface.
+- **[MEDIUM]** No auto-update mechanism (e.g., `electron-updater`) → security patches can't reach users. Implement silent update with user notification.
+
+---
+
+## Common Bugs & Pitfalls
+
+- **[HIGH]** `app.quit()` not called after all windows close on Windows/Linux → process keeps running in background (tray icon or just CPU/memory waste). Add `app.on('window-all-closed', () => app.quit())` for non-macOS.
+- **[HIGH]** Accessing `document` / `window` in main process → these are browser globals, undefined in Node.js main process context.
+- **[MEDIUM]** Async operation started from IPC handler completes after `BrowserWindow` is destroyed → callback or `event.reply()` on destroyed window throws error.
+- **[MEDIUM]** Dev tools opened in production build → `webContents.openDevTools()` call not removed. Gate with `!app.isPackaged`.
+- **[LOW]** `process.resourcesPath` used to locate app files → use `path.join(__dirname, ...)` or `app.getAppPath()` for reliable cross-platform paths.

package/src/prr/data/stacks/elixir.md

@@ -0,0 +1,53 @@
+# Elixir / Phoenix — Stack-Specific Review Rules
+
+> Applies to: GR · SR · PR · AR · BR
+> Detection signals: `*.ex` / `*.exs` files · `mix.exs` · `defmodule` · `use Phoenix.` · `Repo.` · `Ecto.` · `defp` · `%{}` struct patterns
+
+---
+
+## Security
+
+- **[HIGH]** Raw SQL in Ecto: `Repo.query("SELECT * FROM users WHERE id = #{id}")` → SQL injection. Use `Ecto.Query` DSL or parameterized queries: `from(u in User, where: u.id == ^id)`.
+- **[HIGH]** `Phoenix.Token.verify` called without `max_age` option → tokens never expire. Always pass `max_age:` (e.g., 86400 seconds = 1 day).
+- **[HIGH]** `String.to_atom(user_input)` → atoms are never garbage collected; exhausting the atom table crashes the BEAM VM (DoS). Use `String.to_existing_atom/1` or keep as a string.
+- **[MEDIUM]** Missing CSRF protection on non-GET, non-API endpoints → Phoenix includes `Plug.CSRFProtection` by default; ensure it's not removed from the pipeline.
+- **[MEDIUM]** Mass assignment: `User.changeset(user, params)` without a field allowlist in the changeset → any client-supplied field (e.g., `role`, `admin`) gets set. Always use `cast/3` with explicit allowed fields.
+
+---
+
+## Performance
+
+- **[HIGH]** N+1 query in Ecto: loading associations inside an `Enum.map` loop → generates N additional queries. Use `Repo.preload/2` or add `:preload` to the initial query.
+- **[HIGH]** `Enum` functions on a large `Stream` that could be composed → `Enum.filter |> Enum.map` creates an intermediate list. Chain `Stream.filter |> Stream.map |> Enum.to_list` for lazy evaluation.
+- **[MEDIUM]** `GenServer` using synchronous `call` for all operations including fire-and-forget mutations → serializes all operations through one process. Use `cast` for operations that don't need a return value.
+- **[MEDIUM]** `Repo.all` without pagination on a potentially large table → memory spike and slow response. Use `Repo.paginate` or `limit/offset` in the query.
+- **[LOW]** Pattern matching on entire map `%{field: val} = large_map` when only one field is needed → still works but is misleading; be explicit about what you're matching.
+
+---
+
+## Architecture
+
+- **[HIGH]** Business logic in Phoenix controller action → extract to a Context module (boundary pattern). Controllers should only translate HTTP ↔ context function calls.
+- **[HIGH]** Process state stored in `Agent` or `GenServer` without a persistence strategy → state is lost on process crash or node restart. Persist critical state to the database.
+- **[MEDIUM]** `Task.async` without a supervisor → unlinked task crash is not propagated to the caller; use `Task.Supervisor` for resilient async work.
+- **[MEDIUM]** Long-lived `GenServer` that receives unbounded messages without backpressure → mailbox grows indefinitely under load. Use `GenStage` or rate limiting.
+- **[LOW]** `use GenServer` for simple key-value storage → consider `ETS` (Erlang Term Storage) for concurrent read-heavy in-memory state.
+
+---
+
+## Code Quality
+
+- **[HIGH]** `with` expression without an `else` clause → if any clause returns a non-`{:ok, _}` value, it falls through as the return value of the `with` block. Always add `else` to handle errors explicitly.
+- **[MEDIUM]** Large `case` expression where pattern-matched function clauses would be idiomatic → Elixir's pattern matching on function heads is cleaner than `case` for multiple conditions.
+- **[MEDIUM]** `IO.inspect` / `IO.puts` debug statements left in production code → remove before merge. Use `Logger` for structured logging.
+- **[LOW]** Not using `@spec` on public functions → poor documentation, no Dialyzer type checking benefit.
+
+---
+
+## Common Bugs & Pitfalls
+
+- **[HIGH]** `Repo` operations outside a transaction when multiple operations must be atomic → partial write on failure leaves data inconsistent. Use `Repo.transaction/1` or `Ecto.Multi`.
+- **[HIGH]** Calling `Repo.update_all` / `Repo.delete_all` without a `where` clause → modifies or deletes all rows in the table. Always include a `where` condition.
+- **[MEDIUM]** `Map.get(map, key)` returns `nil` for missing keys, not an error → if the key is required, use `Map.fetch!(map, key)` which raises `KeyError` on missing key.
+- **[MEDIUM]** Atom comparison vs string comparison: `"active" == :active` is always `false` → be consistent with atom vs string types for status/enum fields. Ecto enums use atoms; JSON payloads use strings.
+- **[LOW]** `Enum.first(list)` returning `nil` for empty list treated as a valid value → check for `nil` or use pattern matching on the result.

package/src/prr/data/stacks/expo.md

@@ -0,0 +1,53 @@
+# Expo — Stack-Specific Review Rules
+
+> Applies to: GR · SR · PR · AR · BR
+> Detection signals: `expo`, `from 'expo'`, `app.json` with `expo`, `from 'expo-router'`, `eas.json`, `from 'expo-constants'`
+
+---
+
+## Security
+- **[CRITICAL]** API keys or secrets placed in `app.json`, `app.config.js`, or `Constants.expoConfig` → values are bundled into the app binary and extractable. Move secrets server-side; use `expo-constants` only for non-sensitive public config.
+- **[HIGH]** Sensitive data (tokens, user credentials) stored in `AsyncStorage` → unencrypted storage accessible on rooted/jailbroken devices. Use `expo-secure-store` which calls the OS keychain/keystore.
+- **[HIGH]** Deep link URI scheme not validated before acting on parameters → open redirect or parameter injection via crafted links. Validate the full URI and all parameters before using deep link data.
+- **[HIGH]** `expo-file-system` used to read/write paths constructed from user input → path traversal outside the app sandbox. Sanitize paths and restrict operations to `FileSystem.documentDirectory` or `cacheDirectory`.
+- **[MEDIUM]** EAS Update (OTA) not configured with code signing → unsigned JavaScript bundles can be injected by a network attacker. Enable `codeSigningCertificate` in `eas.json` for all update channels.
+- **[MEDIUM]** `__DEV__` check absent on verbose logging or debug screens → internal data and stack traces exposed in production builds. Guard all debug output with `if (__DEV__)`.
+
+---
+
+## Performance
+- **[HIGH]** Heavy computation (sorting, encryption, image processing) run on the JavaScript thread → UI freezes. Offload to `expo-task-manager` background tasks, `react-native-worklets-core`, or a native module.
+- **[HIGH]** Large images embedded at source resolution without optimization → bloated bundle and slow render on low-end devices. Use `expo-image-manipulator` to resize/compress assets; provide `@2x`/`@3x` variants.
+- **[HIGH]** React Native `Image` component used instead of `expo-image` → no built-in memory caching, blurhash placeholder support, or progressive loading. Replace with `expo-image` for all image rendering.
+- **[MEDIUM]** Data fetched in `useEffect` on every component mount without caching → repeated network calls on navigation. Use a caching layer (React Query, SWR, or Expo's `useCachedPromise`).
+- **[MEDIUM]** All screens eager-loaded at startup in navigator → slow time-to-interactive. Use `lazy` option in Expo Router or React Navigation to defer screen registration.
+- **[LOW]** `useFonts` from `expo-font` not awaited before rendering text → layout shift or missing glyphs on first frame. Hide the splash screen until fonts are ready with `SplashScreen.preventAutoHideAsync`.
+
+---
+
+## Architecture
+- **[HIGH]** Custom navigation logic reimplemented instead of using Expo Router's file-based routing → navigation state bugs and missed deep linking support. Migrate to the `app/` directory convention with Expo Router.
+- **[HIGH]** Platform-specific logic mixed inline with `Platform.OS === 'ios'` checks throughout components → hard to maintain. Use `.ios.tsx` / `.android.tsx` / `.web.tsx` file extensions for platform-specific implementations.
+- **[MEDIUM]** Production builds done locally with `expo build` (deprecated) instead of EAS Build → inconsistent build environment and toolchain. Switch to `eas build` with a defined build profile.
+- **[MEDIUM]** Static `app.json` used instead of `app.config.ts` → cannot inject environment variables or dynamic values at build time. Migrate to `app.config.ts` and read from `process.env`.
+- **[MEDIUM]** Expo managed workflow plugins not used for native module configuration → manual native code edits that break on `expo prebuild`. Use config plugins for all native configuration.
+- **[LOW]** Single `eas.json` profile for all environments → development, staging, and production share the same build configuration. Define separate `development`, `preview`, and `production` profiles.
+
+---
+
+## Code Quality
+- **[HIGH]** Expo SDK version not pinned or using a major version range → `expo upgrade` introduces breaking changes automatically. Pin to an exact Expo SDK version and upgrade intentionally.
+- **[MEDIUM]** `expo-constants` used for environment switching in runtime code instead of EAS build profiles → environment logic scattered and hard to audit. Centralize environment config in a single `config.ts` module populated at build time.
+- **[MEDIUM]** Permissions (camera, location, notifications) requested without a usage description or at startup → users deny preemptively. Request permissions at the point of use and provide a `PermissionsExplanation` component.
+- **[MEDIUM]** `babel.config.js` not using `babel-preset-expo` → Expo-specific transforms (SVG imports, module resolution) do not work. Ensure `presets: ['babel-preset-expo']` is the base config.
+- **[LOW]** TypeScript strict mode not enabled in `tsconfig.json` → type errors masked. Set `"strict": true` and extend from `expo/tsconfig.base`.
+
+---
+
+## Common Bugs & Pitfalls
+- **[HIGH]** Stale Metro bundler cache producing builds with old code after dependency changes → old module versions used at runtime. Run `expo start --clear` or `npx expo start -c` to clear the cache.
+- **[HIGH]** `expo-av` `Audio` or `Video` playback not stopped or unloaded on component unmount → audio continues playing in the background, leaking native resources. Call `sound.stopAsync()` and `sound.unloadAsync()` in the `useEffect` cleanup.
+- **[MEDIUM]** `KeyboardAvoidingView` using the same `behavior` for iOS and Android → input fields obscured by keyboard on one platform. Use `behavior="padding"` for iOS and `behavior="height"` for Android.
+- **[MEDIUM]** `StatusBar` style not set per screen → status bar text color wrong against the screen's background. Use `expo-status-bar` `StatusBar` component with `style` set in each screen.
+- **[MEDIUM]** `useCallback` and `useMemo` not applied to callbacks passed to `FlatList` `renderItem` → entire list re-renders on parent state change. Memoize `renderItem` and `keyExtractor` callbacks.
+- **[LOW]** `Platform.OS === 'web'` checks missing for Expo Web → components using native-only APIs crash in the browser. Add web guards or provide web-specific implementations for all native API usage.

package/src/prr/data/stacks/expressjs.md

@@ -0,0 +1,82 @@
+# Express.js — Stack-Specific Review Rules
+
+> Applies to: GR · SR · PR · AR · BR
+> Detection signals: `express()`, `app.use(`, `router.get/post/put/delete`, `from 'express'`, `require('express')`, `middleware`, `req.body`, `res.json`
+
+---
+
+## Security
+
+- **[CRITICAL]** Missing authentication middleware on protected routes → unauthenticated access.
+- **[CRITICAL]** SQL / NoSQL query built with `req.body`/`req.params` string interpolation → injection.
+- **[CRITICAL]** `res.send(req.body.input)` without sanitization → reflected XSS.
+- **[CRITICAL]** `eval(req.body.code)` or dynamic `require(req.body.module)` → arbitrary code execution.
+- **[HIGH]** Missing `helmet` middleware → no security headers (CSP, X-Frame-Options, HSTS).
+- **[HIGH]** `req.body` used without validation (express-validator, zod, joi) → arbitrary data reaches logic.
+- **[HIGH]** Error handler exposing stack trace: `res.json({ error: err.stack })` → info disclosure.
+- **[HIGH]** Missing rate limiting on auth/sensitive endpoints (`express-rate-limit`) → brute force.
+- **[HIGH]** File upload without MIME type/size validation → arbitrary file stored/executed.
+- **[HIGH]** `res.redirect(req.query.next)` without URL validation → open redirect.
+- **[HIGH]** Prototype pollution via `req.body` merged into objects without `Object.freeze(Object.prototype)`.
+- **[MEDIUM]** Session secret hardcoded or weak → session hijacking.
+- **[MEDIUM]** CORS `origin: '*'` with credentials in production → credential leakage.
+- **[MEDIUM]** JWT stored in localStorage instead of httpOnly cookie → XSS token theft.
+- **[LOW]** `express.static` serving files from root directory → source code exposure.
+
+---
+
+## Performance
+
+- **[HIGH]** Synchronous `fs.readFileSync` / `crypto.pbkdf2Sync` in route handler → blocks event loop.
+- **[HIGH]** `async` route handler without try/catch or `express-async-errors` → unhandled rejection crashes process.
+- **[HIGH]** N+1 DB queries per request — loading related data in loop inside route.
+- **[HIGH]** Missing response compression (`compression` middleware) for large JSON responses.
+- **[HIGH]** No connection pooling for DB → new connection per request → latency + exhaustion.
+- **[MEDIUM]** No response caching for idempotent, rarely-changing endpoints.
+- **[MEDIUM]** Missing `req.setTimeout()` → hanging requests hold server resources indefinitely.
+- **[MEDIUM]** `morgan` verbose logging in production → I/O overhead.
+- **[MEDIUM]** Middleware running on all routes including static assets → unnecessary overhead.
+- **[LOW]** `res.json` on large objects without streaming → buffering entire payload in memory.
+
+---
+
+## Architecture
+
+- **[HIGH]** Business logic inside route handler → extract to service/controller layer.
+- **[HIGH]** No centralized error handling middleware (`app.use((err, req, res, next) => {...})`) → inconsistent errors.
+- **[HIGH]** Middleware order wrong — auth middleware placed after route it should protect → never runs.
+- **[HIGH]** `next()` called after `res.send()` / `res.json()` → "Cannot set headers after they are sent" error.
+- **[HIGH]** Not using `express.Router` per domain → all routes in single file → unmaintainable.
+- **[MEDIUM]** Missing `app.set('trust proxy', 1)` behind load balancer → wrong `req.ip`, rate limiting broken.
+- **[MEDIUM]** `app.use(express.json())` with no size limit → large payload DoS. Set `{ limit: '1mb' }`.
+- **[MEDIUM]** Global state (module-level variables) used for request-scoped data → not isolated per request.
+- **[MEDIUM]** Not using `AsyncLocalStorage` for request context propagation → prop drilling `req` everywhere.
+- **[LOW]** Missing `404` catch-all handler at end of middleware chain.
+
+---
+
+## Code Quality
+
+- **[HIGH]** `next(err)` not called in catch block → error swallowed, request hangs.
+- **[HIGH]** Route params used directly as DB keys without type validation → `req.params.id` is always a string.
+- **[MEDIUM]** `res.status(200).json(...)` on errors → client can't distinguish success from failure.
+- **[MEDIUM]** Inconsistent response shape across routes → no standard `{ data, error }` envelope.
+- **[MEDIUM]** Missing `await` on async middleware → middleware completes without waiting for async work.
+- **[MEDIUM]** Not using TypeScript with `@types/express` → `req.body` is `any`.
+- **[LOW]** `res.send()` for JSON responses instead of `res.json()` → must manually set Content-Type.
+- **[LOW]** Not using environment-specific config (`dotenv` without validation).
+
+---
+
+## Common Bugs & Pitfalls
+
+- **[HIGH]** Async middleware not calling `next()` on error → request hangs indefinitely.
+- **[HIGH]** Route defined after `app.use(errorHandler)` → error handler intercepts all subsequent routes.
+- **[HIGH]** Error-handling middleware with only 3 params `(req, res, next)` → Express doesn't recognize as error handler (needs 4: `err, req, res, next`).
+- **[HIGH]** `app.use(express.json())` placed after route definition → `req.body` undefined.
+- **[MEDIUM]** Wildcard route `app.get('*', ...)` placed before specific routes → all specific routes shadowed.
+- **[MEDIUM]** `router.param()` not used for common param validation → repeated `parseInt(req.params.id)`.
+- **[MEDIUM]** Cookie options (`httpOnly`, `secure`, `sameSite`) not set → vulnerable session cookies.
+- **[MEDIUM]** `res.end()` vs `res.send()` vs `res.json()` confusion → wrong Content-Type header.
+- **[LOW]** `app.listen()` not storing returned server for graceful shutdown.
+- **[LOW]** `express-validator` errors not checked with `validationResult(req)` → validation runs but not enforced.

package/src/prr/data/stacks/fastapi.md

@@ -0,0 +1,88 @@
+# FastAPI — Stack-Specific Review Rules
+
+> Applies to: GR · SR · PR · AR · BR
+> Detection signals: `from fastapi`, `@app.get`, `@app.post`, `@router.`, `Depends(`, `BaseModel` (pydantic), `uvicorn`, `@asynccontextmanager`, `lifespan`
+
+---
+
+## Security
+
+- **[CRITICAL]** Route missing `Depends(get_current_user)` on protected endpoints → unauthenticated access.
+- **[CRITICAL]** SQL built with f-string/`.format()` with user data → injection. Use parameterized queries.
+- **[CRITICAL]** `eval()` / `exec()` with user-controlled input in any route or utility.
+- **[HIGH]** ORM model returned directly instead of Pydantic response schema → exposes passwords, internal IDs.
+- **[HIGH]** Missing `response_model` on endpoints → no output filtering, arbitrary data returned.
+- **[HIGH]** `allow_origins=["*"]` in production CORS config → any website makes credentialed requests.
+- **[HIGH]** Secrets loaded with `os.getenv("SECRET")` returning `None` silently → app runs without secrets.
+- **[HIGH]** File upload missing MIME type + size validation → arbitrary file upload.
+- **[HIGH]** Missing `HTTPSRedirectMiddleware` in production → tokens/cookies sent over HTTP.
+- **[HIGH]** JWT token not validated for expiry/signature in `get_current_user` dependency.
+- **[HIGH]** User-supplied `redirect_uri` in OAuth flow not validated → open redirect.
+- **[MEDIUM]** Missing rate limiting on auth endpoints → brute force on login.
+- **[MEDIUM]** `background_tasks.add_task()` running with request-scoped DB session that closes → session closed before task runs.
+- **[LOW]** OpenAPI docs (`/docs`, `/redoc`) accessible in production without auth → schema exposed.
+
+---
+
+## Performance
+
+- **[HIGH]** Synchronous I/O (`requests.get()`, blocking DB calls) inside `async def` route → blocks event loop. Use `httpx.AsyncClient`, async ORM.
+- **[HIGH]** N+1 ORM queries — loading relationships in loop. Use `selectinload`/`joinedload` with SQLAlchemy async.
+- **[HIGH]** Missing `async` on database session operations with async SQLAlchemy → sync in async context.
+- **[HIGH]** `await` inside `for` loop → sequential DB calls; batch with `asyncio.gather()`.
+- **[HIGH]** Missing pagination on list endpoints → unbounded query.
+- **[HIGH]** Sync function passed to `run_in_executor` without proper thread pool → blocking thread pool worker.
+- **[MEDIUM]** `background_tasks` used for critical path work → fires and forgets, no error handling.
+- **[MEDIUM]** Pydantic v1 `orm_mode` / v2 `from_attributes` missing → ORM objects not serializable.
+- **[MEDIUM]** DB connection not pooled → new connection per request.
+- **[MEDIUM]** Not using `ORJSONResponse` for large JSON payloads → default `JSONResponse` slower.
+- **[LOW]** Multiple middleware layers running on every request including static assets.
+- **[LOW]** `@lru_cache` on dependency returning DB session → sessions shared across requests.
+
+---
+
+## Architecture
+
+- **[HIGH]** Business logic inside route function → delegate to service/repository layer.
+- **[HIGH]** DB session directly in route (`db: Session = Depends(get_db)`) without proper lifecycle.
+- **[HIGH]** Not using `APIRouter` per domain → everything in `main.py` → unmaintainable.
+- **[HIGH]** No dependency injection for services → hardcoded globals, not testable.
+- **[MEDIUM]** Missing `lifespan` context manager → using deprecated `@app.on_event("startup")`.
+- **[MEDIUM]** Pydantic validators with side effects (DB queries in validators) → validators should be pure.
+- **[MEDIUM]** Not using `@asynccontextmanager` for resource management in dependencies.
+- **[MEDIUM]** Error handling missing global `@app.exception_handler` → default 500 for all errors.
+- **[MEDIUM]** Not using `HTTPException` with proper status codes → all errors return 200 or 500.
+- **[LOW]** Missing `tags`, `summary`, `description` on routers → poor OpenAPI docs.
+- **[LOW]** Schema inheritance >2 levels deep → confusing field origins.
+
+---
+
+## Code Quality
+
+- **[HIGH]** Missing type annotations on route parameters → FastAPI cannot parse/validate.
+- **[HIGH]** `except Exception` swallowing errors in route handlers.
+- **[HIGH]** Pydantic `field_validator` (v2) not raising `ValueError` → validation silently ignored.
+- **[MEDIUM]** `Optional[str]` vs `str | None` inconsistency (pick one per Python version).
+- **[MEDIUM]** `Query(None)` for optional params not using `Annotated` style (modern FastAPI).
+- **[MEDIUM]** Not using `Annotated[str, Query(min_length=1)]` for reusable param validation.
+- **[MEDIUM]** Status codes not semantically correct (201 for create, 204 for delete, etc.).
+- **[MEDIUM]** Missing `response_description` on endpoints → OpenAPI shows no response info.
+- **[LOW]** `Path()` / `Query()` missing `description` → undocumented parameters.
+- **[LOW]** Not using `model_config = ConfigDict(str_strip_whitespace=True)` on input models.
+
+---
+
+## Common Bugs & Pitfalls
+
+- **[HIGH]** Mutable default in Pydantic model (`field: list = []`) → shared across all instances.
+- **[HIGH]** Async generator dependency not properly closed on exception → DB session leak.
+- **[HIGH]** `HTTPException` raised inside `background_tasks` → silently swallowed, client got 200 already.
+- **[HIGH]** Route handler `async def` but calling sync-heavy function without `asyncio.to_thread()` → event loop blocked.
+- **[HIGH]** Pydantic v1 and v2 mixed in same project → validation behavior differences cause bugs.
+- **[MEDIUM]** `Form()` and `Body()` used together → FastAPI doesn't support mixing form + JSON.
+- **[MEDIUM]** `status_code=200` on POST creating resource → should be 201.
+- **[MEDIUM]** Dependency exception not propagating correctly when dependency raises inside generator after `yield`.
+- **[MEDIUM]** `PATCH` handler using `PUT` semantics (replacing entire object instead of partial update).
+- **[MEDIUM]** Not using `model.model_dump(exclude_unset=True)` for PATCH → overwriting unset fields with defaults.
+- **[LOW]** Not pinning pydantic version → v1/v2 breaking changes.
+- **[LOW]** `uvicorn --reload` used in production → file watcher overhead.

package/src/prr/data/stacks/fastify.md

@@ -0,0 +1,60 @@
+# Fastify — Stack-Specific Review Rules
+
+> Applies to: GR · SR · PR · AR · BR
+> Detection signals: from 'fastify', Fastify(), fastify.register(), fastify.route(), schema: with JSON Schema, @fastify/
+
+---
+
+## Security
+- **[HIGH]** Missing `@fastify/helmet` plugin → security headers (CSP, HSTS, X-Frame-Options) absent. Register it as a global plugin before routes.
+- **[HIGH]** No rate limiting via `@fastify/rate-limit` → brute-force and DoS succeed on public endpoints. Apply globally with per-route overrides.
+- **[CRITICAL]** JSON schema validation disabled or bypassed (`schema` omitted, AJV strict mode off) → prototype pollution and arbitrary data accepted. Always define request schemas.
+- **[HIGH]** Unvalidated file paths in `@fastify/multipart` → path traversal or overwrite attacks. Sanitize filenames and whitelist destination directories.
+- **[HIGH]** CORS wildcard origin with `credentials: true` in `@fastify/cors` → cookies accepted from any domain. Set explicit origins or disable credentials when using wildcard.
+- **[MEDIUM]** Response schema leaking internal fields (e.g., `password`, `internalId`) → sensitive data returned to clients. Define `schema.response` on every route.
+- **[HIGH]** String fields not sanitized beyond JSON schema type checks → stored XSS or injection when data rendered. Add `format` or `pattern` constraints and sanitize.
+- **[MEDIUM]** `fastify.register()` load order placing routes before auth plugin initialized → auth hooks absent. Register security plugins before route plugins.
+
+---
+
+## Performance
+- **[HIGH]** No `schema.response` defined → Fastify falls back to slow `JSON.stringify` instead of fast-json-stringify, reducing throughput 2-5x. Define response schemas on every route.
+- **[CRITICAL]** Missing `return` before `reply.send()` in async handlers → execution continues post-response, causing "Reply already sent" crashes. Always write `return reply.send(...)`.
+- **[HIGH]** Async handler not returning a value or promise → request left unresolved, client hangs. Return the promise or call `reply.send()` in every code path.
+- **[HIGH]** Synchronous CPU-heavy operations (crypto, regex, large JSON) inside handlers → event loop blocked, degrading concurrent requests. Offload to worker threads or async chunks.
+- **[MEDIUM]** Shared services not wrapped with `fastify-plugin` → each plugin scope re-instantiates the service, wasting memory and DB connections. Use `fp()` to share decorators.
+- **[MEDIUM]** Same plugin registered multiple times in nested scopes → duplicate middleware overhead per request. Use `fastify-plugin` where cross-scope sharing is intended.
+- **[MEDIUM]** Pino at `trace` or `debug` level in production → excessive log I/O overhead. Set `logger: { level: 'info' }` and use async pino transport.
+- **[LOW]** No content-type when sending pre-serialized JSON strings → Fastify may re-serialize. Use `reply.type('application/json').send(str)`.
+
+---
+
+## Architecture
+- **[HIGH]** Business logic in route handler functions → untestable monoliths mixing HTTP and domain concerns. Extract into service modules and inject via `fastify.decorate()`.
+- **[HIGH]** Shared services not registered via `fastify.decorate()` → services re-instantiated per module. Decorate the Fastify instance once at startup.
+- **[MEDIUM]** Plugins lacking proper encapsulation → decorators and hooks leak across boundaries, causing ordering bugs. Use `fastify-plugin` only for deliberate cross-scope sharing.
+- **[HIGH]** No `onRequest` or `preHandler` auth hooks on protected routes → routes accessible without a valid token. Scope an auth hook to protected route groups.
+- **[MEDIUM]** All routes defined in one file → codebase grows unmanageable as app scales. Organize into domain-scoped plugins with `fastify.register()` and logical prefixes.
+- **[MEDIUM]** No `fastify.addContentTypeParser()` for non-JSON request bodies → binary or form data silently rejected. Register parsers for all expected content types.
+- **[LOW]** Routes not versioned (`/v1/`, `/v2/`) → breaking changes force simultaneous client updates. Establish prefix-based versioning from the outset.
+
+---
+
+## Code Quality
+- **[MEDIUM]** No TypeScript type provider (`@fastify/type-provider-typebox` or `@fastify/type-provider-zod`) → handler params typed as `any`. Integrate a type provider and colocate schemas with routes.
+- **[MEDIUM]** Route schemas duplicated inline across routes → schema drift and maintenance burden. Register shared schemas with `fastify.addSchema()` and reference via ``.
+- **[HIGH]** No `fastify.setErrorHandler()` → inconsistent error shapes from per-handler try/catch. Define a global error handler normalizing errors to a standard envelope.
+- **[MEDIUM]** No custom `fastify.setNotFoundHandler()` → default 404 format breaks client error parsing. Register a not-found handler returning the standard error shape.
+- **[LOW]** Full request objects logged including auth headers → tokens appear in log aggregators. Configure pino `redact` paths to strip sensitive fields.
+- **[MEDIUM]** Not using `fastify.inject()` in tests → tests need a live port, causing EADDRINUSE conflicts. Use `fastify.inject()` for in-process HTTP testing.
+
+---
+
+## Common Bugs & Pitfalls
+- **[CRITICAL]** `reply.send()` without `return` in async callbacks → "Reply already sent" errors or double-send crashes. Always `return reply.send()`.
+- **[HIGH]** Plugin not awaited at top level → plugin uninitialized when requests arrive, missing decorator errors. Always await `fastify.register()` or use a ready hook.
+- **[HIGH]** Schema `` used before `fastify.addSchema()` → validation fails silently or throws at startup. Register all shared schemas before routes that reference them.
+- **[MEDIUM]** `fastify.close()` not called in tests → port stays bound, EADDRINUSE on next run. Call `fastify.close()` in `afterAll` or `afterEach`.
+- **[HIGH]** `fastify.listen()` without `host: '0.0.0.0'` in containers → server binds loopback only, unreachable externally. Set host based on deployment environment.
+- **[MEDIUM]** No `onError` hook or uncaught exception handler → errors in lifecycle hooks crash the process without diagnostics. Attach an `onError` hook and process-level handler.
+- **[MEDIUM]** Mixing async handlers with callback-style `reply.send()` → control-flow bugs where promise resolves before reply is sent. Pick one pattern and apply consistently.