prr-kit 1.1.2 → 1.2.0

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.

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

@@ -0,0 +1,55 @@
+# Fiber — Stack-Specific Review Rules
+
+> Applies to: GR · SR · PR · AR · BR
+> Detection signals: "github.com/gofiber/fiber", fiber.New(), app.Get(, c.JSON(, c.BodyParser(, fiber.Config{
+
+---
+
+## Security
+- **[HIGH]** Missing `helmet` middleware (`github.com/gofiber/helmet`) → no security headers sent, leaving app vulnerable to clickjacking, MIME sniffing, and XSS. Register helmet middleware globally before route handlers.
+- **[HIGH]** CSRF middleware not configured on state-mutating routes → cross-site form submissions processed without token validation. Enable CSRF protection for all POST/PUT/PATCH/DELETE routes.
+- **[HIGH]** `c.BodyParser` used without a body size limit → large payloads exhaust memory. Configure `fiber.Config{ BodyLimit: 4 * 1024 * 1024 }` to enforce a maximum request body size.
+- **[HIGH]** Wildcard CORS configured in production (origin: "*") → cross-origin requests accepted from any domain. Set explicit allowed origins in `cors.Config{ AllowOrigins: "https://yourdomain.com" }`.
+- **[CRITICAL]** Path traversal via `c.Params()` values used in file operations → attacker crafts a path to read or overwrite arbitrary files. Sanitize and validate all path parameters before using them in file system calls.
+- **[MEDIUM]** Missing authentication middleware on protected route groups → unauthenticated requests reach protected handlers. Use `app.Use()` on route groups to enforce auth before handler execution.
+- **[MEDIUM]** Not validating struct fields after `c.BodyParser` → business logic receives zero-value or malformed data. Integrate a validation library (e.g., `go-playground/validator`) after parsing.
+- **[MEDIUM]** Sensitive error details returned in HTTP responses → internal paths or DB errors exposed to clients. Return generic error messages and log detailed errors server-side only.
+
+---
+
+## Performance
+- **[CRITICAL]** Fiber reuses `*fiber.Ctx` across requests → capturing ctx in a goroutine causes data races and use-after-free bugs. Never pass ctx to goroutines; extract all needed values before launching.
+- **[MEDIUM]** Missing compress middleware for large responses → uncompressed JSON or HTML payloads increase bandwidth and client load time. Add `github.com/gofiber/fiber/middleware/compress`.
+- **[MEDIUM]** `c.JSON()` marshaling large structs without streaming → entire response buffered in memory. For large datasets, use streaming responses or pagination.
+- **[LOW]** `Prefork: true` not used on multi-core servers handling CPU-bound workloads → single process cannot fully utilize available CPU cores. Enable prefork in production environments and test for compatibility.
+- **[HIGH]** Synchronous blocking calls (file I/O, external HTTP) inside handlers → Fiber's event loop stalls, degrading all concurrent requests. Use goroutines with proper synchronization for blocking operations.
+- **[MEDIUM]** Not using `app.Static()` for serving static files → static assets served through application handlers with unnecessary overhead. Configure the built-in static file middleware for asset serving.
+
+---
+
+## Architecture
+- **[MEDIUM]** Not using `app.Group()` for route organization → all routes defined at the top level, making the router file unmanageable as the app grows. Group related routes with common prefixes and middleware.
+- **[HIGH]** Business logic implemented directly in handler functions → handlers become untestable and hard to maintain. Extract domain logic into service types with clear interfaces.
+- **[MEDIUM]** Custom error handler not set via `app.Use(errorHandler)` → default Fiber error format inconsistent with the application API contract. Define a custom error handler returning the standard error shape.
+- **[MEDIUM]** Database connections not managed via dependency injection → global DB instances make testing difficult and hide coupling. Pass DB and service dependencies through closure or a custom handler struct.
+- **[LOW]** No middleware for request ID generation → distributed tracing and log correlation are difficult without request IDs. Add a request-ID middleware and propagate it through context and response headers.
+
+---
+
+## Code Quality
+- **[HIGH]** Missing input validation after `c.BodyParser` → raw parsed data used without field-level validation, allowing missing or malformed data into business logic. Integrate `go-playground/validator` or equivalent after parsing.
+- **[MEDIUM]** `c.Locals()` used as a typed store without type assertions → values retrieved as `interface{}` cause silent nil panics when the type is wrong. Define typed accessor helpers for context locals.
+- **[HIGH]** Not handling `c.BodyParser` errors explicitly → parse failures pass a zero-value struct to the handler, corrupting business logic. Always check and return the error from BodyParser.
+- **[MEDIUM]** No logging middleware configured → requests and errors go untracked, making production debugging difficult. Add the built-in logger middleware or a structured logging middleware.
+- **[LOW]** Not using fiber's built-in timeout middleware → slow handlers hold connections indefinitely. Configure `middleware/timeout` to enforce handler deadlines.
+- **[MEDIUM]** Using `fiber.Map` for all responses instead of typed structs → response shape is untyped and prone to field name typos. Define response structs to enforce a stable contract.
+
+---
+
+## Common Bugs & Pitfalls
+- **[CRITICAL]** `*fiber.Ctx` captured in a goroutine without copying → ctx is recycled after handler returns, causing reads of garbage data or panics. Use `c.Context().Copy()` or extract needed values before the goroutine.
+- **[MEDIUM]** `c.JSON()` called after `c.Next()` in middleware → response already committed by an inner handler, causing "response already sent" errors. Check if response is committed before writing in middleware.
+- **[MEDIUM]** Path parameters overlapping between route definitions → ambiguous routes cause the wrong handler to be called. Order routes from most specific to most general and use explicit path segments.
+- **[HIGH]** Not handling panics in goroutines spawned from handlers → goroutine panics crash the process and take down all active requests. Recover from panics in goroutines and log or report the error.
+- **[MEDIUM]** `app.Listen()` without graceful shutdown → in-flight requests dropped when process exits. Implement signal handling and `app.Shutdown()` for graceful termination.
+- **[HIGH]** Not setting `ReadTimeout` and `WriteTimeout` in `fiber.Config` → slow or malicious clients hold connections open indefinitely, exhausting connection slots. Set appropriate timeouts in the Fiber config.

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

@@ -0,0 +1,43 @@
+# Firebase — Stack-Specific Review Rules
+
+> Applies to: GR · SR · PR · AR · BR
+> Detection signals: `firebase` in deps · `initializeApp(` · `getFirestore(` · `getAuth(` · `collection(` · `import 'firebase/` · `firebase.json` · `.firebaserc`
+
+---
+
+## Security
+
+- **[CRITICAL]** Firestore / Realtime Database security rules contain `allow read, write: if true` → anyone on the internet can read, write, or delete your entire database.
+- **[CRITICAL]** Firebase Admin SDK service account JSON committed to version control → full administrative access to your Firebase project, bypasses all security rules.
+- **[HIGH]** Firestore security rules not validating incoming data shape or field types → client can write documents with any structure, including oversized fields or unexpected types. Add `request.resource.data` validation.
+- **[HIGH]** Authorization logic in client-side code only: `if (user.uid === doc.ownerId)` → client code can be bypassed. Enforce ownership and access control in Firestore security rules.
+- **[MEDIUM]** Firebase API key visible in client-side code → expected (it's a public identifier), BUT ensure domain restrictions are configured in Firebase Console to prevent use from unauthorized domains.
+
+---
+
+## Performance
+
+- **[HIGH]** `onSnapshot` listener not unsubscribed on component unmount → each mount adds a new listener; stale listeners fire callbacks on unmounted components, causing memory leaks and potential state updates after unmount.
+- **[HIGH]** Fetching entire collection without a `where()` query → every read costs money; full collection scans on large datasets will exhaust quota and budget.
+- **[MEDIUM]** Missing `limit()` on Firestore queries → unbounded reads; a growing collection causes increasing cost and latency over time.
+- **[MEDIUM]** Real-time `onSnapshot` listener used where a one-time `getDoc()` / `getDocs()` suffices → continuous WebSocket connection maintained unnecessarily.
+- **[LOW]** Not using `enableIndexedDbPersistence()` for offline support → queries fail when offline; consider offline capability for mobile-like use cases.
+
+---
+
+## Architecture
+
+- **[HIGH]** Business logic placed in Firestore security rules (complex calculations, multi-step workflows) → rules are for access control only; complex logic belongs in Cloud Functions or the application layer.
+- **[MEDIUM]** Deeply nested Firestore sub-collections more than 2 levels → Firestore cannot query across parent documents for sub-collections. Flatten the data model or use root-level collections with foreign key fields.
+- **[MEDIUM]** `set()` used without `{ merge: true }` when partial update is intended → overwrites entire document, deletes unspecified fields. Use `update()` for partial updates.
+- **[LOW]** Storing large blobs or images directly in Firestore documents → Firestore is optimized for structured data; store binaries in Firebase Storage and keep URLs/metadata in Firestore.
+
+---
+
+## Common Bugs & Pitfalls
+
+- **[HIGH]** Direct array write instead of `arrayUnion` / `arrayRemove` for concurrent updates → two simultaneous writes both read the array, modify it, and write back; one write overwrites the other (last-write-wins). Use atomic array operations.
+- **[HIGH]** `Timestamp.now()` used for ordering instead of `serverTimestamp()` → client clock may be wrong (wrong timezone, wrong time). Use `serverTimestamp()` for ordering and audit trails.
+- **[MEDIUM]** Querying with `where('field', '!=', value)` without a composite index → Firestore throws an error at runtime pointing to the missing index. Check the Firebase Console for required indexes.
+- **[MEDIUM]** `auth.currentUser` accessed synchronously on app load before auth state is initialized → may be `null` even if user is logged in. Always use `onAuthStateChanged` to react to auth state.
+- **[LOW]** Firestore `where` inequality filter (`<`, `>`, `!=`) on a field combined with `orderBy` on a different field → requires a composite index and may throw a runtime error.

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

@@ -0,0 +1,46 @@
+# Flask — Stack-Specific Review Rules
+
+> Applies to: GR · SR · PR · AR · BR
+> Detection signals: `from flask import`, `@app.route`, `Flask(__name__)`, `Blueprint`, `flask` in requirements.txt
+
+---
+
+## Security
+
+- **[CRITICAL]** `render_template_string()` with user-controlled input → Server-Side Template Injection (SSTI). Never use with user data.
+- **[CRITICAL]** SQL query with f-string / `.format()` of user input → SQL injection. Use parameterized queries.
+- **[HIGH]** Missing `@login_required` / auth check on protected routes.
+- **[HIGH]** `SECRET_KEY` hardcoded in app code → session forgery. Load from environment.
+- **[HIGH]** `Markup()` used to mark user content as safe → XSS. Jinja2 escapes by default; don't bypass it.
+- **[HIGH]** Debug mode enabled in production (`app.run(debug=True)`) → interactive debugger accessible to users, RCE risk.
+- **[MEDIUM]** `send_file()` / `send_from_directory()` with user-controlled path → path traversal. Validate and sanitize paths.
+- **[MEDIUM]** Missing CSRF protection (Flask-WTF or manual token) on state-changing forms.
+- **[MEDIUM]** Allowing all origins in CORS configuration for APIs with auth.
+
+---
+
+## Performance
+
+- **[HIGH]** Synchronous DB calls blocking Flask worker — use async frameworks (Quart) or offload to Celery.
+- **[HIGH]** N+1 ORM queries in view function — load relations eagerly.
+- **[MEDIUM]** `session` object used to store large data → stored in cookie, 4KB limit, sent on every request.
+- **[MEDIUM]** No pagination on list endpoints.
+- **[LOW]** Flask development server (`app.run()`) used in production instead of Gunicorn/uWSGI → single-threaded.
+
+---
+
+## Architecture
+
+- **[HIGH]** All routes in single `app.py` → use Blueprints to organize by domain.
+- **[MEDIUM]** Application factory pattern (`create_app()`) not used → hard to test with different configs.
+- **[MEDIUM]** Business logic directly in route function → move to service/model layer.
+- **[LOW]** `current_app` accessed outside application context → `RuntimeError`.
+
+---
+
+## Common Bugs & Pitfalls
+
+- **[HIGH]** Mutable default in route function or SQLAlchemy model → shared state across requests.
+- **[HIGH]** `g` object used to store request-scoped data but not cleaned up → leaks between requests in some WSGI setups.
+- **[MEDIUM]** `redirect(request.referrer)` without validation → open redirect.
+- **[MEDIUM]** `jsonify()` not used for JSON responses → missing Content-Type header.