prr-kit 1.1.3 → 1.2.1

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

@@ -0,0 +1,89 @@
+# Kotlin — Stack-Specific Review Rules
+
+> Applies to: GR · SR · PR · AR · BR
+> Detection signals: `*.kt` files · `fun main()` · `import kotlin.` · `build.gradle.kts` · `@Composable` · `ViewModel` · `suspend fun` · `Flow` · `Coroutine`
+
+---
+
+## Security
+
+- **[CRITICAL]** SQL injection via string interpolation in Room queries: `@Query("SELECT * WHERE name = '$userInput'")` → use bound parameters `(:name)`.
+- **[HIGH]** `WebView.settings.javaScriptEnabled = true` without overriding `WebViewClient.shouldOverrideUrlLoading()` → XSS from loaded content.
+- **[HIGH]** `WebView.addJavascriptInterface()` with reflection access → native code callable from JS.
+- **[HIGH]** Sensitive data (tokens, passwords) stored in `SharedPreferences` plaintext → use `EncryptedSharedPreferences`.
+- **[HIGH]** Intent with user-controlled `action` or `data` without validation → intent injection from other apps.
+- **[HIGH]** Exported `Activity`/`BroadcastReceiver` without permission in `AndroidManifest.xml` → any app can invoke.
+- **[HIGH]** Hardcoded API keys in source code → extracted from APK with `apktool`.
+- **[HIGH]** Certificate validation disabled via custom `TrustManager` → MITM.
+- **[MEDIUM]** `Log.d` / `Log.v` logging sensitive data → visible in ADB LogCat.
+- **[MEDIUM]** Missing `FLAG_SECURE` on Activity showing PINs, payment info → screenshots capture sensitive content.
+- **[MEDIUM]** `Parcelable` deserialization of untrusted data → class loading attacks.
+- **[LOW]** ProGuard/R8 not configured → class/method names readable in reverse-engineered APK.
+
+---
+
+## Performance
+
+- **[HIGH]** `runBlocking` on main thread → blocks UI thread, causes ANR if >5 seconds.
+- **[HIGH]** `GlobalScope.launch` → coroutine not bound to lifecycle, continues after component destroyed → leak.
+- **[HIGH]** `Dispatchers.IO` used for CPU-bound work → I/O thread pool exhausted. Use `Dispatchers.Default`.
+- **[HIGH]** Jetpack Compose: heavy computation inside `@Composable` function body → runs on every recomposition.
+- **[HIGH]** `remember { }` missing for expensive objects in Compose → recreated on every recomposition.
+- **[HIGH]** `StateFlow` / `LiveData` collected without `repeatOnLifecycle(STARTED)` in Fragment → collects in background.
+- **[HIGH]** Bitmap not recycled or sampled down for display size → OOM crash.
+- **[HIGH]** Main thread network call (pre-Android 9 workarounds) → NetworkOnMainThreadException or ANR.
+- **[MEDIUM]** `Flow` not collected with `flowOn(Dispatchers.IO)` for I/O-bound upstream → runs on collector's dispatcher.
+- **[MEDIUM]** `viewModelScope.launch` inside `init {}` block → not cancelled if ViewModel immediately replaced.
+- **[MEDIUM]** RecyclerView without `DiffUtil` → full list rebind on any data change.
+- **[MEDIUM]** `suspend fun` doing CPU-heavy work on `Dispatchers.Main` → UI jank.
+- **[LOW]** `withContext` wrapping already-correct-dispatcher suspend function → unnecessary context switch overhead.
+
+---
+
+## Architecture
+
+- **[HIGH]** `ViewModel` holding reference to `Activity` / `Fragment` Context → memory leak after rotation. Use `applicationContext`.
+- **[HIGH]** `LiveData` / `StateFlow` observed in `onCreate` without `lifecycleScope.repeatOnLifecycle` → multiple observers accumulate on back-stack.
+- **[HIGH]** Business logic in Activity / Fragment → violates MVVM; move to ViewModel + UseCase.
+- **[HIGH]** Repository missing → ViewModel directly calls data source → not testable.
+- **[HIGH]** Mutable `MutableStateFlow` / `MutableLiveData` exposed directly from ViewModel → external mutation bypasses state management.
+- **[HIGH]** `StateFlow` vs `SharedFlow` wrong choice: `SharedFlow` for events (one-shot), `StateFlow` for UI state.
+- **[HIGH]** Not using Hilt/Koin for DI → manual DI at scale becomes maintenance nightmare.
+- **[MEDIUM]** `data class` with `var` fields used as ViewModel state → unintentional mutation bypasses reactive update.
+- **[MEDIUM]** `CoroutineScope` created manually in Activity/Fragment instead of using `lifecycleScope`.
+- **[MEDIUM]** Navigation Component not used → manual fragment transactions → back stack management bugs.
+- **[MEDIUM]** `Event` wrapper pattern for `LiveData` one-shot events → use `Channel` or `SharedFlow` instead.
+- **[LOW]** Not using `sealed class`/`sealed interface` for UI state → exhaustive `when` not enforced.
+- **[LOW]** Not separating domain layer (Use Cases) from data layer.
+
+---
+
+## Code Quality
+
+- **[HIGH]** `!!` (non-null assertion) without preceding null check → `NullPointerException` at runtime. Use `?.`, `?:`, `requireNotNull()`.
+- **[HIGH]** `async { }.await()` sequential pattern → defeats concurrency. Use `async { }` + deferred, await all at end.
+- **[HIGH]** Missing `CoroutineExceptionHandler` on `launch` → unhandled exception silently swallowed.
+- **[MEDIUM]** `object` (singleton) holding Android `Context` reference → leaked context. Use `WeakReference` or restructure.
+- **[MEDIUM]** Extension function on `Any?` or too-broad type → pollutes autocomplete.
+- **[MEDIUM]** Not using Kotlin's `sealed` result types for domain errors instead of exceptions.
+- **[MEDIUM]** `apply` / `also` / `let` / `run` scope functions misused → confusion about `this` vs `it`.
+- **[MEDIUM]** `data class` used for entities with identity (DB rows) → `equals`/`hashCode` on all fields, not just ID.
+- **[MEDIUM]** Not using `by lazy` for expensive one-time property initialization.
+- **[LOW]** Companion object holding non-constant data → shared across all instances.
+- **[LOW]** Not using `typealias` for complex function types → unreadable parameter types.
+
+---
+
+## Common Bugs & Pitfalls
+
+- **[HIGH]** `viewLifecycleOwner` vs `this` in Fragment → using `this` causes multiple LiveData callbacks on back navigation.
+- **[HIGH]** `launch` exception without handler → silently swallowed (unlike `async`). Add `CoroutineExceptionHandler`.
+- **[HIGH]** `Flow.collect` in `lifecycleScope.launch {}` → collects in background when UI paused. Use `repeatOnLifecycle`.
+- **[HIGH]** Coroutine cancelled by `CancellationException` caught with `catch (e: Exception)` → coroutine can't cancel.
+- **[HIGH]** `Channel.send()` in one coroutine, `receive()` in another → deadlock if sender cancelled before receiver ready.
+- **[MEDIUM]** `stateIn(scope, SharingStarted.Eagerly, ...)` → starts collecting even when no subscribers → wasted resources.
+- **[MEDIUM]** `withContext(Dispatchers.IO)` wrapping a `suspend` function that already switches context → redundant overhead.
+- **[MEDIUM]** `MutableList` shared between coroutines without synchronization → concurrent modification.
+- **[MEDIUM]** `by viewModels()` delegate used in `Fragment` before `onAttach()` → crash.
+- **[LOW]** `companion object` initialization order misunderstood → `const val` vs `val` differs.
+- **[LOW]** `inline fun` with `reified T` used without understanding runtime overhead of inlining.

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

@@ -0,0 +1,148 @@
+# Kubernetes Stack Rules
+
+## Detection Signals
+`*.yaml` with `apiVersion:` + `kind: Deployment/Service/Pod` · `kubectl` · `helm` charts · `kustomization.yaml` · `.k8s/` directory · `Dockerfile` + k8s manifests
+
+---
+
+## Security
+
+**[CRITICAL]** Container running as root (`runAsUser: 0` or missing `securityContext`) → privilege escalation on container escape. Set `runAsNonRoot: true`, `runAsUser: 1000+` in pod securityContext.
+
+**[CRITICAL]** `privileged: true` in container securityContext → equivalent to root on host node, full kernel access. Never use in production; remove the flag entirely.
+
+**[CRITICAL]** `hostPID: true` / `hostNetwork: true` / `hostIPC: true` on pod → shares host namespaces, full host process/network visibility. Restrict to specific system workloads only.
+
+**[HIGH]** Secrets stored in ConfigMap instead of Secret → ConfigMaps readable by anyone with namespace read access. Use Secret with encryption at rest via KMS provider.
+
+**[HIGH]** Secrets passed as environment variables → visible in `kubectl describe pod`, `/proc/environ`, and crash dumps. Mount secrets as volumes with `secretKeyRef` instead.
+
+**[HIGH]** Missing NetworkPolicy → all pods communicate freely by default, unrestricted east-west traffic. Define ingress/egress rules for least-privilege per workload.
+
+**[HIGH]** RBAC ClusterRole with wildcard (`*`) verbs or resources → over-privileged service accounts that can read/write anything. Use minimal Role scoped to the specific namespace and resources needed.
+
+**[HIGH]** `automountServiceAccountToken: true` (default) on pods not needing API access → service account token is a lateral movement vector. Set `automountServiceAccountToken: false` on the service account and pod spec.
+
+**[HIGH]** `allowPrivilegeEscalation: true` (default) → child processes can gain more privileges than the parent. Set `allowPrivilegeEscalation: false` in container securityContext.
+
+**[MEDIUM]** `readOnlyRootFilesystem: false` → malicious process can write to container filesystem and install tools. Set `readOnlyRootFilesystem: true` and use emptyDir volumes for writable paths.
+
+**[MEDIUM]** Image pulled from public registry without digest pinning → image tag can be silently replaced (supply chain attack). Use `@sha256:` digest instead of mutable tags.
+
+**[MEDIUM]** Ingress without TLS termination → traffic travels in plaintext from ingress controller to pod. Add cert-manager TLS annotation and configure HTTPS redirect.
+
+**[LOW]** Namespaces without ResourceQuota → a single namespace can starve others of CPU/memory. Set CPU and memory quotas per namespace.
+
+**[LOW]** Missing PodSecurityStandard policy (restricted/baseline) → pods can request dangerous capabilities without enforcement. Enable via namespace label pod-security.kubernetes.io/enforce: restricted.
+
+---
+
+## Performance
+
+**[CRITICAL]** Missing resource requests → scheduler cannot place pods optimally, nodes become oversubscribed and unstable. Always set `requests.cpu` and `requests.memory` for every container.
+
+**[CRITICAL]** Missing resource limits → pod can consume all node memory causing OOM kills of neighbouring pods. Set `limits.memory` always; consider omitting CPU limit to avoid throttling.
+
+**[HIGH]** Single replica (`replicas: 1`) for stateless service → rolling update causes downtime, node failure kills service entirely. Use at minimum 2 replicas for any production workload.
+
+**[HIGH]** Missing PodDisruptionBudget → `kubectl drain` terminates all replicas simultaneously during node maintenance. Define `minAvailable` or `maxUnavailable` for every critical deployment.
+
+**[HIGH]** HPA without VPA for right-sizing → pods scale horizontally but individual pod requests are too large or too small. Combine HPA for horizontal scaling with VPA recommendations for request tuning.
+
+**[HIGH]** `imagePullPolicy: Always` on every pod start → extra registry latency on each restart, deployment fails if registry is unreachable. Use `IfNotPresent` with immutable tags or digest pins.
+
+**[HIGH]** Missing preStop hook and insufficient `terminationGracePeriodSeconds` → in-flight requests dropped when pod receives SIGTERM during rolling update. Add a preStop sleep hook and increase grace period to cover longest request duration.
+
+**[MEDIUM]** CPU limit set too low (CPU throttling) → container is throttled even when node has available CPU, causing latency spikes. Set CPU limit 2-4x the request, or remove CPU limit and rely on node-level fairness.
+
+**[MEDIUM]** Not using Cluster Autoscaler or Karpenter → nodes are under- or over-provisioned regardless of pod demand. Enable node autoscaling based on pending pod scheduling pressure.
+
+**[MEDIUM]** JVM or Node.js container without heap size flags → runtime uses host memory detection and exceeds container memory limit, causing OOMKill. Set -Xmx to approximately 75% of limits.memory for JVM; set --max-old-space-size for Node.js.
+
+**[MEDIUM]** Liveness probe too aggressive (short timeout + low failureThreshold) → healthy pods restarted during GC pause or slow startup. Increase `initialDelaySeconds`, `timeoutSeconds`, and `failureThreshold`.
+
+**[LOW]** Not using `topologySpreadConstraints` → all pods scheduled on same node or availability zone, single point of failure. Define spread constraints by topology.kubernetes.io/zone.
+
+**[LOW]** Pods without `priorityClassName` → low-priority batch jobs not evicted first during resource pressure, starving critical services. Assign priority classes: critical, default, low.
+
+---
+
+## Architecture
+
+**[HIGH]** Stateful data written to pod local filesystem or emptyDir → data lost permanently when pod restarts or is rescheduled. Use PersistentVolumeClaim with appropriate StorageClass.
+
+**[HIGH]** Image tag `:latest` → tag changes silently, deployments are non-reproducible, rollback is unreliable. Use semantic version tags or `@sha256:` digest pinning.
+
+**[HIGH]** Missing readinessProbe → pod receives live traffic before the application finishes initialization, causing errors during startup. Define an HTTP or exec readinessProbe for every container.
+
+**[HIGH]** Missing livenessProbe → Kubernetes cannot detect a deadlocked application and will never restart it automatically. Define a livenessProbe that checks only internal process health, not external dependencies.
+
+**[HIGH]** ConfigMap or Secret not versioned or referenced by hash annotation → config changes do not trigger pod restart; app runs stale configuration. Use a checksum annotation or the Reloader operator to trigger rollouts on config change.
+
+**[HIGH]** All microservices deployed to the default namespace → no RBAC or NetworkPolicy isolation between teams or environments. Use per-team or per-environment namespaces with dedicated service accounts.
+
+**[MEDIUM]** Hardcoded registry URLs in manifests → migrating to a new registry requires mass find-and-replace across all manifests. Use Kustomize image transformers or Helm values for registry configuration.
+
+**[MEDIUM]** Resources missing explicit `namespace` field → resources created in default namespace, mixing environments unpredictably. Always specify `metadata.namespace` in every manifest.
+
+**[MEDIUM]** Direct Pod manifests instead of Deployments → bare pods are not rescheduled on node failure and cannot be rolled back. Always use Deployment, StatefulSet, or DaemonSet.
+
+**[MEDIUM]** Helm chart values hardcoded in `values.yaml` without environment overrides → chart is not reusable across dev, staging, and production. Use environment-specific value files or Helmfile for per-environment configuration.
+
+**[MEDIUM]** Not using Kustomize overlays for environment differences → manifests duplicated across environments, diverging over time. Use base + overlay structure with patches for per-environment differences.
+
+**[LOW]** Missing Prometheus scrape annotations → metrics not collected by Prometheus Operator, no visibility into pod performance. Add prometheus.io/scrape and prometheus.io/port annotations or create a ServiceMonitor resource.
+
+**[LOW]** Not using init containers for database migration → application starts before migration runs, causing schema mismatch errors at startup. Use an init container that runs migrations and exits before the main container starts.
+
+---
+
+## Code Quality
+
+**[HIGH]** `kubectl apply` with generated manifests not tracked in git → configuration drift, no audit trail, no reliable rollback. Use GitOps (ArgoCD or Flux) to reconcile cluster state from a git repository.
+
+**[HIGH]** Missing `namespace` field in manifest → resources created in wrong namespace, label selectors do not match, hard to diagnose. Always specify `metadata.namespace` on every resource.
+
+**[HIGH]** Service selector labels not matching Deployment pod template labels → zero pods selected, all connections refused with no obvious error message. Cross-check spec.selector.matchLabels against spec.template.metadata.labels.
+
+**[HIGH]** Not running `helm lint` or `kubectl --dry-run=client` before applying → invalid manifests deployed, misconfigured fields silently ignored. Add lint and dry-run steps to the CI pipeline before every apply.
+
+**[MEDIUM]** YAML indentation errors → Kubernetes silently ignores misconfigured fields rather than rejecting them. Enforce yamllint in CI and use a schema validator such as kubeconform.
+
+**[MEDIUM]** Not using `kubectl rollout status` to verify deployment success → deployment assumed complete when only submitted to API server. Add `kubectl rollout status deployment/name --timeout=120s` after every apply.
+
+**[MEDIUM]** ConfigMap keys containing periods → keys with periods cannot be used as environment variable names. Use underscores for keys intended to be consumed as env vars.
+
+**[MEDIUM]** Resource names exceeding 63 characters → DNS label limit exceeded; Service and Ingress creation fails with cryptic errors. Keep all resource names under 63 characters.
+
+**[MEDIUM]** Resources not tagged with standard labels (app, version, component) → hard to query, filter, and correlate resources across the cluster. Apply app.kubernetes.io/* labels consistently to all resources.
+
+**[LOW]** Not using Strategic Merge Patch for Kustomize overlay values → Kustomize performs full replacement instead of merge for some fields. Use Strategic Merge Patch type for lists (containers, volumes) in patches.
+
+**[LOW]** Missing owner references on child resources → orphaned resources not garbage collected when parent is deleted, accumulating over time. Set ownerReferences on dynamically created child resources.
+
+---
+
+## Common Bugs & Pitfalls
+
+**[HIGH]** Service selector mismatch with Pod template labels → traffic routes to zero pods, connection refused with no helpful error message. Compare Service.spec.selector with Deployment.spec.template.metadata.labels character by character.
+
+**[HIGH]** PersistentVolumeClaim with `ReadWriteOnce` on a multi-node Deployment → second pod stays permanently Pending because volume can only be mounted by one node at a time. Use `ReadWriteMany` (NFS, EFS) or `ReadWriteOncePod` for single-pod guarantee.
+
+**[HIGH]** HPA `targetCPUUtilizationPercentage` misunderstood as percentage of limit → HPA calculates utilization against requests, not limits; HPA never fires if limit is much larger than request. Set requests accurately to reflect typical load.
+
+**[HIGH]** Deployment with `maxSurge: 0` and `maxUnavailable: 0` → rolling update deadlocks immediately, never terminates old pods or creates new ones. Set at least one of these to a non-zero value.
+
+**[MEDIUM]** `kubectl apply` on manifest using `generateName` → creates a new resource on every apply instead of updating the existing one. Use a fixed `name` field for resources managed declaratively.
+
+**[MEDIUM]** Init container failure not visible in main container logs → kubectl logs shows only the main container; init failure is invisible. Use kubectl logs with the --container flag specifying the init container name.
+
+**[MEDIUM]** Secret value not base64 encoded in YAML manifest → Kubernetes rejects the manifest with a decode error. Base64-encode all values under `data:`, or use `stringData:` which accepts plaintext and encodes automatically.
+
+**[MEDIUM]** Liveness probe hitting an endpoint that queries the database → cascading pod restarts during database slowdown kills all replicas simultaneously. Liveness probe should check only internal process health with no external dependency calls.
+
+**[MEDIUM]** Using `kubectl replace` without specifying resourceVersion → concurrent replace loses changes made between read and write. Use `kubectl apply` for idempotent declarative updates.
+
+**[LOW]** NodePort service unintentionally exposing an internal service externally → port accessible from outside the cluster without authentication. Use ClusterIP for internal services; front external access with an Ingress or LoadBalancer Service.
+
+**[LOW]** CronJob without `concurrencyPolicy: Forbid` → jobs pile up when a previous run has not finished, exhausting cluster resources. Set `concurrencyPolicy: Forbid` or `Replace` depending on the desired behaviour.

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

@@ -0,0 +1,56 @@
+# LangChain — Stack-Specific Review Rules
+
+> Applies to: GR · SR · PR · AR · BR
+> Detection signals: `from 'langchain'`, `from '@langchain/`, `langchain`, `LLMChain`, `ChatOpenAI`, `PromptTemplate`, `AgentExecutor`, `VectorStore`
+
+---
+
+## Security
+- **[CRITICAL]** User input inserted directly into a system prompt or template without sanitization → prompt injection allows the user to override system instructions or extract confidential prompt content. Treat all user input as untrusted data; use structured output parsers instead of raw string insertion.
+- **[CRITICAL]** Agent configured with `PythonREPLTool`, `BashTool`, or other arbitrary code execution tools → a prompt injection attack causes the agent to execute malicious code on the server. Disable code-execution tools in production; use sandboxed environments with strict allowlists if required.
+- **[HIGH]** LLM-generated output used directly in code execution paths, SQL queries, or shell commands without validation → second-order injection. Always validate and escape LLM output before using it in downstream operations.
+- **[HIGH]** Vector store containing sensitive or multi-tenant data queried without per-user access control → user A retrieves user B's embedded documents. Partition vector stores by user/tenant or apply metadata filters on every retrieval query.
+- **[HIGH]** LLM provider API keys stored in environment variables without rotation or access auditing → stolen key results in unbounded API cost. Use a secrets manager with automatic rotation; monitor API usage for anomalies.
+- **[MEDIUM]** Conversation history persisted in a database with user PII and no encryption or retention policy → privacy regulation violation. Encrypt conversation records at rest and enforce a retention/deletion policy.
+- **[MEDIUM]** Agent given a web search or HTTP request tool without restrictions → SSRF attack causes agent to probe internal network services. Restrict tool-accessible URLs to an allowlist and block private IP ranges.
+
+---
+
+## Performance
+- **[HIGH]** LLM responses not streamed for long-running generation → end-user sees a blank UI until the full response arrives. Use `stream: true` or `astream()` and emit tokens progressively to the client.
+- **[HIGH]** Full conversation history sent to the LLM on every turn without summarisation → context window fills up, responses degrade, and costs scale linearly with conversation length. Apply `ConversationSummaryBufferMemory` or trim history to a rolling window.
+- **[HIGH]** No caching configured for identical or similar prompts → every request hits the LLM API, inflating cost and latency. Enable `langchain.cache` with an in-memory, Redis, or SQLite backend for deterministic prompts.
+- **[MEDIUM]** Sequential LLM calls that are independent of each other → total latency is the sum of all calls. Use `RunnableParallel` to execute independent chains concurrently.
+- **[MEDIUM]** Entire large document embedded as a single chunk → exceeds context window limits and retrieval quality degrades. Use `RecursiveCharacterTextSplitter` with appropriate `chunk_size` and `chunk_overlap`.
+- **[MEDIUM]** Synchronous LangChain APIs used inside an async application framework → event loop blocked during LLM calls. Use async chain methods (`ainvoke`, `astream`) throughout async code.
+- **[LOW]** Embeddings recomputed for the same documents on every application restart → unnecessary API cost and startup latency. Persist embeddings to a vector store with disk or database backing.
+
+---
+
+## Architecture
+- **[HIGH]** Prompt text hardcoded as inline string literals → prompts not version controlled, reviewed, or A/B testable. Store prompts as `PromptTemplate` objects in dedicated files or manage them via LangChain Hub.
+- **[HIGH]** Agent tools not explicitly scoped with descriptions and parameter schemas → agent misuses tools or attempts to call non-existent capabilities. Define each tool with a precise description and use `args_schema` with Pydantic models.
+- **[MEDIUM]** LangSmith tracing not enabled in production → no observability into chain execution, token usage, or latency. Set `LANGCHAIN_TRACING_V2=true` and configure the LangSmith API key for all environments.
+- **[MEDIUM]** Retrieval and generation tightly coupled in one chain → cannot optimise, test, or swap retrieval independently. Separate the retrieval step (query transformation, vector search, reranking) from the generation step.
+- **[MEDIUM]** `ConversationChain` or `LLMChain` used instead of LCEL (LangChain Expression Language) → legacy API with limited composability. Migrate to `Runnable` pipes (`chain = prompt | llm | parser`) for maintainability.
+- **[LOW]** Prompt versions not tracked in LangChain Hub or a version control system → impossible to roll back a prompt regression. Commit prompts to version control and tag releases.
+
+---
+
+## Code Quality
+- **[HIGH]** LLM response parsed with string splitting or regex instead of output parsers → brittle parsing breaks on minor format variation. Use `PydanticOutputParser`, `JsonOutputParser`, or `StructuredOutputParser` with format instructions in the prompt.
+- **[HIGH]** No retry or fallback logic for LLM API rate limit or transient errors → single request failure surfaces directly to the user. Wrap chain invocations with `.with_retry()` or a try/except with exponential backoff, and configure `with_fallbacks()` for model failover.
+- **[MEDIUM]** Chain not tested with adversarial or edge-case inputs → prompt injection and malformed output not caught before production. Write unit tests with mocked LLMs and integration tests with boundary inputs.
+- **[MEDIUM]** Conversation history not managed with `RunnableWithMessageHistory` → manual history threading is error-prone and inconsistent. Use `RunnableWithMessageHistory` with a `BaseChatMessageHistory` backend.
+- **[MEDIUM]** `AgentExecutor` `verbose=True` left on in production → internal chain reasoning and tool calls logged to stdout. Set `verbose=False` in production and route structured logs to an observability platform.
+- **[LOW]** LangChain version pinned with a broad range (`>=0.1`) → breaking API changes introduced silently. Pin to an exact minor version and review the changelog before upgrading.
+
+---
+
+## Common Bugs & Pitfalls
+- **[HIGH]** `AgentExecutor` created without `max_iterations` or `max_execution_time` → agent enters an infinite reasoning loop, generating unbounded API costs. Always set `max_iterations` (e.g., 10) and `max_execution_time` as safeguards.
+- **[HIGH]** Vector store not persisted to disk or a database → all embeddings lost on application restart and must be recomputed. Use a persistent backend (Chroma with `persist_directory`, Pinecone, pgvector) and load on startup.
+- **[MEDIUM]** Token count not validated before sending to the LLM → request exceeds the model's context window and the API returns an error. Count tokens with the model's tokenizer before each request and truncate or summarise if needed.
+- **[MEDIUM]** `ConversationBufferMemory` used without a maximum token or turn limit → memory grows without bound until the context window is exceeded. Replace with `ConversationBufferWindowMemory` or `ConversationSummaryBufferMemory`.
+- **[MEDIUM]** Tool `description` is vague or overlaps with another tool → agent calls the wrong tool or oscillates between tools. Write unambiguous, action-oriented descriptions that clearly distinguish each tool's purpose.
+- **[LOW]** Chain inputs not validated with Pydantic before invocation → malformed inputs produce confusing internal errors. Define input schemas with Pydantic and validate at the chain entry point.

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

@@ -0,0 +1,56 @@
+# Laravel — Stack-Specific Review Rules
+
+> Applies to: GR · SR · PR · AR · BR
+> Detection signals: `*.php` files, `artisan`, `Eloquent`, `routes/web.php`, `app/Http/Controllers`, `composer.json` with laravel/framework
+
+---
+
+## Security
+
+- **[CRITICAL]** Raw DB query with user input: `DB::select("SELECT * WHERE id = $id")` → SQL injection. Use Eloquent or query builder with bindings.
+- **[CRITICAL]** Missing CSRF token on POST/PUT/DELETE forms (`@csrf` blade directive) → CSRF attack.
+- **[HIGH]** Missing `Auth::check()` / `auth()` middleware on protected routes → unauthenticated access.
+- **[HIGH]** `{!! $variable !!}` in Blade with user-controlled content → XSS. Use `{{ }}` which auto-escapes.
+- **[HIGH]** Mass assignment without `$fillable` or `$guarded` → attacker sets arbitrary model fields (e.g., `is_admin`).
+- **[HIGH]** Secrets in `.env` committed or hardcoded in config → use `.env` + `.gitignore`.
+- **[MEDIUM]** Authorization policy missing — `Gate::allows()` / Policy not checked before sensitive operation.
+- **[MEDIUM]** `Storage::disk('public')` used for private files → files directly accessible via URL.
+
+---
+
+## Performance
+
+- **[HIGH]** N+1 Eloquent queries — accessing relationship in loop without eager loading (`with()`).
+- **[HIGH]** `Model::all()` on large tables without pagination → loads entire table.
+- **[MEDIUM]** Missing database indexes on columns used in `where()`, `orderBy()`, `join()`.
+- **[MEDIUM]** `count()` on Eloquent collection (`$collection->count()`) after loading vs `Model::count()` DB query.
+- **[MEDIUM]** Missing `chunk()` for large dataset operations → memory exhaustion.
+- **[LOW]** No query result caching for expensive, stable reads (Laravel Cache).
+
+---
+
+## Architecture
+
+- **[HIGH]** Business logic in Controller → move to Service classes or Action classes.
+- **[HIGH]** Direct Eloquent queries in Controller bypassing Repository/Service layer.
+- **[MEDIUM]** Fat Eloquent models (>500 lines) violating SRP → extract traits or services.
+- **[MEDIUM]** Event/Listener used for critical synchronous business logic → timing and error handling become opaque.
+- **[LOW]** Missing Form Request classes for complex validation → validation logic inline in controller.
+
+---
+
+## Code Quality
+
+- **[HIGH]** Missing validation before using `$request->input()` → unvalidated data in business logic.
+- **[MEDIUM]** `dd()` / `dump()` left in code → debugging output in production.
+- **[MEDIUM]** Hardcoded strings for status/type values instead of Enums (PHP 8.1+) or constants.
+- **[LOW]** Missing resource classes for API responses → inconsistent JSON structure.
+
+---
+
+## Common Bugs & Pitfalls
+
+- **[HIGH]** `firstOrCreate` / `updateOrCreate` not atomic → race condition in high-concurrency scenarios.
+- **[HIGH]** Queue job not idempotent → retried jobs cause duplicate side effects.
+- **[MEDIUM]** `Carbon` timezone not set → date comparison bugs in non-UTC deployments.
+- **[MEDIUM]** Relationship `->get()` called instead of `->first()` → returns Collection when single model expected.

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

@@ -0,0 +1,46 @@
+# LibGDX — Stack-Specific Review Rules
+
+> Applies to: GR · SR · PR · AR · BR
+> Detection signals: `com.badlogicgames`, `Gdx.`, `ApplicationAdapter`, `SpriteBatch`, `AssetManager`, `Box2D`, `*.gdx`, `libgdx`
+
+---
+
+## Security
+- **[MEDIUM]** User-provided level or save files loaded and parsed without validation → malformed data causes crashes or exploits memory parsers. Validate all external data against a schema before processing; reject files that fail validation.
+- **[MEDIUM]** Reflection-based serialization (`Json.fromJson()`) with untrusted input → arbitrary class instantiation or field injection. Restrict JSON deserialization to a known set of types using a whitelist or switch to a safer format (e.g., Protocol Buffers).
+- **[LOW]** Server endpoints for online features hardcoded in the binary → man-in-the-middle or reverse-engineering of API endpoints. Fetch endpoints from a signed configuration loaded at startup; pin SSL certificates for sensitive requests.
+
+---
+
+## Performance
+- **[CRITICAL]** Object allocation (`new`, `ArrayList()`, etc.) inside `render()` → triggers Android GC, causing frame-rate spikes and jank. Pre-allocate all objects before game loop; use `com.badlogic.gdx.utils.Pool` for recycling frequently created/destroyed objects.
+- **[HIGH]** Not using `AssetManager` → textures, sounds, and models loaded synchronously, blocking the render thread for seconds. Use `AssetManager.load()` with an async loading screen; check `AssetManager.isFinished()` each frame.
+- **[HIGH]** Not using texture atlases (TexturePacker) → individual texture binds per sprite cause excessive GPU state changes and draw calls. Pack all sprites into atlases with `gdx-tools` TexturePacker; use `TextureAtlas` and `AtlasRegion` for lookups.
+- **[HIGH]** Box2D physics step not using a fixed timestep → simulation becomes non-deterministic and unstable at varying frame rates. Accumulate delta time and step the world in fixed increments (`1/60f`); interpolate rendering between steps.
+- **[MEDIUM]** `SpriteBatch.begin()`/`end()` called too frequently or interrupted by texture switches → extra flush calls reduce batching efficiency. Sort sprites by texture region; batch all draws for the same atlas region before flushing.
+- **[LOW]** Not using `Pools` (`com.badlogic.gdx.utils.Pools`) for frequently created objects (e.g., `Vector2`, `Rectangle`) → unnecessary GC pressure from short-lived heap objects. Obtain from `Pools.obtain(Vector2.class)` and `Pools.free(v)` after use.
+
+---
+
+## Architecture
+- **[HIGH]** All game logic implemented directly inside `ApplicationAdapter` or `ApplicationListener` → untestable, unmaintainable as game grows. Use the `Game` + `Screen` pattern; separate update logic into domain classes that are independent of LibGDX lifecycle.
+- **[HIGH]** Not using the `Game`/`Screen` interface for managing game states → ad hoc state flags proliferate in the main class. Implement `Screen` for each game state (menu, gameplay, pause, game-over) and use `Game.setScreen()` to transition.
+- **[MEDIUM]** Rendering and game logic update not separated → logic tied to frame rate causes speed variations on slower devices. Call `update(delta)` before `render()` and cap or accumulate delta to decouple simulation from frame rate.
+- **[LOW]** Platform-specific differences (desktop vs Android vs HTML5 vs iOS) not abstracted behind interfaces → platform-conditional code scattered through game logic. Define platform interfaces and inject the appropriate implementation via the LibGDX `ApplicationListener` factory pattern.
+
+---
+
+## Code Quality
+- **[HIGH]** `Texture`, `SpriteBatch`, `BitmapFont`, `AssetManager`, `Sound`, `Music`, or `ShaderProgram` not disposed when no longer needed → native OpenGL/OpenAL resources leak, causing OOM or driver instability. Implement `Disposable` on all resource-holding classes and call `dispose()` in `Screen.dispose()` and `ApplicationListener.dispose()`.
+- **[MEDIUM]** Not using `gdx-tools` TexturePacker at build time → manually managed sprite sheets become out of sync with source art. Integrate TexturePacker into the build pipeline so atlases are regenerated on asset changes.
+- **[MEDIUM]** `Gdx.app.log()` / `Gdx.app.error()` calls left unrestricted in production builds → log spam on end-user devices and potential information disclosure. Gate verbose logging behind a `BuildConfig.DEBUG` flag or a runtime log level setting.
+- **[LOW]** GWT (HTML5) backend constraints not considered during development → classes not supported by GWT (reflection, some `java.util` features) cause HTML build failures. Test HTML5 target in CI; avoid GWT-incompatible APIs unless the HTML5 backend is explicitly excluded.
+
+---
+
+## Common Bugs & Pitfalls
+- **[HIGH]** Texture or OpenGL resource created on a background thread → OpenGL context is thread-local on Android/desktop; creating resources off the render thread causes `GLException`. Always create GL resources on the render thread; post work to the render thread with `Gdx.app.postRunnable()`.
+- **[HIGH]** `AssetManager.finishLoading()` called on the render thread as a blocking wait → freezes the render loop for the full load duration. Use the async pattern: call `update()` each frame and check `isFinished()` to proceed.
+- **[MEDIUM]** `Vector2.tmp` or `Vector3.tmp` static scratch fields used in nested or multi-threaded calls → the same temporary object overwritten mid-calculation. Create local `Vector2` instances or use `Pools`; never rely on static tmp fields across method boundaries.
+- **[MEDIUM]** `BitmapFont` created directly from a TTF or not disposed → underlying `Texture` leaks native memory. Create fonts via `AssetManager` with `FreetypeFontLoader` and let the manager handle disposal.
+- **[LOW]** Android back button not handled (`Gdx.input.setCatchKey(Input.Keys.BACK, true)` not set) → app exits abruptly without saving state or showing a confirmation dialog. Catch the back key explicitly and implement the intended behavior (pause menu, confirm quit, etc.).

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

@@ -0,0 +1,49 @@
+# Lit (Web Components) — Stack-Specific Review Rules
+
+> Applies to: GR · SR · PR · AR · BR
+> Detection signals: `from 'lit'`, `from 'lit/decorators'`, `LitElement`, `@customElement`, `` html` ``, `` css` ``, `*.ts` with `customElements.define`
+
+---
+
+## Security
+- **[CRITICAL]** `unsafeHTML()` directive used with user-controlled content → XSS allowing arbitrary script injection into shadow DOM. Sanitize with DOMPurify before passing to `unsafeHTML()`, or use safe text interpolation `${userContent}`.
+- **[HIGH]** `unsafeCSS()` used with user-supplied style strings → CSS injection enabling UI redressing or data exfiltration via CSS selectors. Only use `unsafeCSS()` with static developer-controlled strings; never with user input.
+- **[HIGH]** Event listeners added to `window` or `document` in `connectedCallback` without removal in `disconnectedCallback` → memory leak and ghost event handlers after element removal. Always mirror `addEventListener` in `connectedCallback` with `removeEventListener` in `disconnectedCallback`.
+- **[MEDIUM]** Sensitive data reflected to HTML attributes via `@property({ reflect: true })` → PII exposed in DOM and queryable by third-party scripts. Set `reflect: false` (the default) for sensitive properties; only reflect non-sensitive state needed for CSS selectors.
+- **[MEDIUM]** Missing Content Security Policy allowing inline scripts in pages with custom elements → CSP bypass via attribute injection. Define a strict CSP and use nonce-based script allowlisting.
+
+---
+
+## Performance
+- **[HIGH]** Entire template re-rendered when only one property changes due to no `guard()` directive on expensive subtrees → unnecessary DOM diffing. Wrap expensive static subtrees with the `guard(deps, () => html\`...\`)` directive.
+- **[MEDIUM]** `@state` not used for internal reactive properties; `@property` used instead → unnecessary attribute serialization and reflection on every change. Use `@state()` for properties that are internal implementation details not needed as attributes.
+- **[MEDIUM]** Heavy DOM trees in `render()` without using `repeat()` directive for lists → full list re-render instead of efficient keyed updates. Use `repeat(items, item => item.id, item => html\`...\`)` for keyed list rendering.
+- **[MEDIUM]** `willUpdate` / `updated` lifecycle hooks not used to avoid redundant computations triggered per property change → computed values recalculated on every render. Derive expensive computations in `willUpdate` only when relevant properties change.
+- **[LOW]** Full `lit` package imported instead of specific entry points (`lit/html.js`, `lit/decorators.js`) → larger-than-necessary bundle. Import from specific Lit subpaths to enable tree-shaking.
+
+---
+
+## Architecture
+- **[HIGH]** Business logic (API calls, data transformation) placed directly inside `LitElement` class methods → components become fat controllers, untestable in isolation. Extract to service classes or plain functions; inject via constructor or properties.
+- **[HIGH]** Deep shadow DOM nesting (custom elements inside custom elements, 4+ levels) makes CSS theming require many CSS custom properties → hard to maintain design tokens. Flatten component hierarchy where possible; define a comprehensive set of CSS custom properties at component boundaries.
+- **[MEDIUM]** Content projection not used via `<slot>`; instead content is passed as properties → tight coupling between parent and child markup. Use named `<slot>` elements for flexible content composition.
+- **[MEDIUM]** Custom events not typed with `CustomEvent<TDetail>` and not documented → consumers have no type safety for event payloads. Type all dispatched events and document them in the component's API surface.
+- **[MEDIUM]** `@property({ reflect: true })` on boolean attributes not using the `type: Boolean` converter → `false` reflected as the string `"false"` which is truthy in CSS attribute selectors. Always include `type: Boolean` for boolean properties that reflect.
+
+---
+
+## Code Quality
+- **[HIGH]** Properties updated reactively without declaring them with `@property` or `@state` → Lit does not schedule re-render, UI goes stale. Every reactive property must be declared with `@property()` or `@state()`.
+- **[MEDIUM]** `this.shadowRoot.querySelector(...)` used instead of `@query` decorator → verbose, non-typed DOM reference. Use `@query('#my-input') input!: HTMLInputElement` for typed, cached element references.
+- **[MEDIUM]** `@customElement('my-el')` decorator and manual `customElements.define('my-el', MyEl)` both present → double registration error. Use only one registration method; prefer `@customElement` decorator.
+- **[MEDIUM]** `:host` CSS incorrectly used for internal element styling instead of targeting internal selectors → styles leak or don't apply as expected. Use `:host` only for the host element itself; use internal class/element selectors for children.
+- **[LOW]** `static styles` defined per instance using `css\`\`` inside a function → styles recreated every instantiation. Define `static styles` as a static class field evaluated once.
+
+---
+
+## Common Bugs & Pitfalls
+- **[HIGH]** DOM-dependent initialization code placed in `connectedCallback` before first render completes → element not yet in DOM, `this.shadowRoot` children may not exist. Use `firstUpdated()` for code that needs the rendered shadow DOM.
+- **[HIGH]** `@property` type converter mismatch — string attribute `"false"` not converting to boolean `false` → attribute is truthy when component expects `false`. Declare `type: Boolean` and use presence/absence of attribute rather than its value.
+- **[HIGH]** Custom events not dispatched with `composed: true` → events don't cross shadow DOM boundaries and parent listeners never fire. Dispatch cross-boundary events with `new CustomEvent('name', { bubbles: true, composed: true })`.
+- **[MEDIUM]** Shadow DOM breaking third-party CSS libraries (Bootstrap, Tailwind) that style by global class → styles not applied inside shadow root. Use CSS custom properties for theming or `adoptedStyleSheets` to share styles; document the limitation.
+- **[MEDIUM]** Lit template caching with keyed `repeat()` using non-stable keys (array index) → DOM nodes reused incorrectly on list reorder. Always use stable, unique identifiers (IDs) as keys in `repeat()`.

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

@@ -0,0 +1,51 @@
+# LÖVE 2D — Stack-Specific Review Rules
+
+> Applies to: GR · SR · PR · AR · BR
+> Detection signals: `main.lua` with `love.`, `love.load`, `love.update`, `love.draw`, `love.graphics`, `love.keypressed`, `*.love`
+
+---
+
+## Security
+- **[HIGH]** `love.filesystem.load()` called with a path derived from user input → executes arbitrary Lua code from the loaded file; never load and execute files from untrusted paths, and restrict file loading to the game's save directory or fused archive.
+- **[MEDIUM]** Sensitive data (auth tokens, player credentials, purchase state) written with `love.filesystem.write()` in plaintext → readable by any process with filesystem access; encrypt sensitive data before writing, or store server-side.
+- **[MEDIUM]** Network multiplayer receiving game action messages without server-side authority → cheating via crafted UDP/TCP packets; treat all received client inputs as untrusted and validate legality on the server.
+- **[LOW]** Third-party Lua libraries loaded from user-writable directories → malicious library substitution; load libraries only from the fused game archive and verify file integrity where possible.
+
+---
+
+## Performance
+- **[HIGH]** New Lua tables, strings, or closures created inside `love.draw()` every frame → triggers the Lua garbage collector during rendering, causing periodic hitches; pre-allocate tables and strings before the game loop and reuse them.
+- **[HIGH]** Large, uncompressed PNG images loaded without enabling GPU-side compression → excessive VRAM usage and slower texture sampling; use `love.graphics.newImage(path, {compress = true})` or pre-convert to compressed formats (DXT, ETC).
+- **[HIGH]** `love.graphics.draw()` called individually for hundreds of identical images → one draw call per image; use `love.graphics.newSpriteBatch()` to batch all instances of the same image into a single draw call.
+- **[MEDIUM]** Physics world `world:update(dt)` using variable `dt` directly → non-deterministic simulation that diverges between clients in multiplayer; use a fixed timestep accumulator: accumulate `dt` and step with a fixed interval until the accumulator is exhausted.
+- **[MEDIUM]** Off-screen rendering results (UI panels, static backgrounds) redrawn from scratch every frame → wasted GPU work; render static or infrequently changing content to a `love.graphics.newCanvas()` and redraw the canvas only when the content changes.
+- **[LOW]** `love.graphics.setFont()` called every frame when the font does not change → redundant state change; set the font once in `love.load()` and only call `setFont()` when switching between different fonts.
+
+---
+
+## Architecture
+- **[HIGH]** All game code (input, physics, rendering, AI, UI) in a single `main.lua` → monolithic and unmaintainable; split into Lua modules using `require()`: `src/player.lua`, `src/world.lua`, `src/ui.lua`, with clear interfaces between them.
+- **[MEDIUM]** Lua `require()` module system not used → global functions and tables defined in `main.lua` polluting the global namespace; organize code into module files that return a table of functions and use `local M = {}; return M` pattern.
+- **[MEDIUM]** All game state stored in global Lua variables → implicit dependencies and namespace collisions; use module-local state or pass state explicitly through function arguments.
+- **[MEDIUM]** No state management for game screens (main menu, gameplay, pause, game over) → ad-hoc `if currentState == "menu"` branches throughout `love.update` and `love.draw`; implement a `GameState` module with `enter()`, `update(dt)`, `draw()`, and `exit()` callbacks.
+- **[LOW]** Third-party state/scene libraries (hump.gamestate, knife.system) not considered for complex games → reinventing patterns already solved by the LÖVE ecosystem; evaluate established libraries before writing a custom state manager.
+
+---
+
+## Code Quality
+- **[HIGH]** `love.update(dt)` received but `dt` not used for movement, animation, or timer updates → frame-rate-dependent behavior that runs differently at 30 FPS vs 144 FPS; always multiply all per-frame changes by `dt` to produce time-based values.
+- **[MEDIUM]** Magic numbers for entity positions, sprite dimensions, tile sizes, and speed constants scattered throughout update and draw functions → changing one value requires a global search; extract all tuning constants into a top-level `conf` or `constants` module.
+- **[MEDIUM]** `love.keyboard.isDown()` used for discrete single-press actions (pause, jump, menu select) instead of `love.keypressed()` callback → `isDown` returns true every frame the key is held; use the `love.keypressed(key)` callback for one-shot actions and `isDown` only for continuous held input.
+- **[MEDIUM]** `love.graphics.print()` called with concatenated strings every frame → string allocation GC pressure; pre-format strings and cache them, updating only when the displayed value changes.
+- **[LOW]** `love.resize(w, h)` callback not implemented for resizable windows → layout and camera coordinates not updated on window resize; implement `love.resize` and update any coordinate systems that depend on window dimensions.
+
+---
+
+## Common Bugs & Pitfalls
+- **[HIGH]** `love.graphics.*` functions called outside of `love.draw()` (e.g., in `love.update()` or `love.load()`) → LÖVE requires all drawing to happen in `love.draw()`; calling graphics functions elsewhere raises an error; restrict all draw calls to the `love.draw()` callback.
+- **[HIGH]** `love.load()` not releasing resources (canvases, images, physics worlds) before a game restart → memory leak on repeated restarts; explicitly set resource variables to `nil` and call `:release()` on LÖVE objects before reinitializing.
+- **[MEDIUM]** Lua `#table` operator used on non-sequence tables (tables with nil holes or non-integer keys) → `#` returns undefined length for non-sequences; use an explicit `count` field or `table.maxn()` for sparse tables, and only use `#` on pure sequence tables.
+- **[MEDIUM]** Box2D physics body not destroyed with `body:destroy()` when the associated game object is removed → the physics body remains in the world, consuming memory and participating in collisions invisibly; always call `body:destroy()` when removing a physics-enabled entity.
+- **[MEDIUM]** `love.audio.newSource()` called inside `love.update()` or a frequently called function → each call loads and decodes the audio file; call `newSource()` once in `love.load()` and reuse the source, calling `source:seek(0); source:play()` to replay.
+- **[LOW]** `love.filesystem` save directory not accessible on all platforms in the same way as the game directory → attempting to load from the source directory on a fused build fails; use `love.filesystem.getSourceBaseDirectory()` and `love.filesystem.getSaveDirectory()` and understand which is appropriate for each file type.
+- **[LOW]** Floating-point `dt` accumulated over many frames in timers without resetting → floating-point drift causes timers to fire slightly off-schedule over long sessions; use integer millisecond counters or reset accumulators after each trigger.

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

@@ -0,0 +1,51 @@
+# Lua — Stack-Specific Review Rules
+
+> Applies to: GR · SR · PR · AR · BR
+> Detection signals: `*.lua`, `require(`, `local function`, `love.`, `--[[`, `ngx.`, `redis.call(`, `luarocks`
+
+---
+
+## Security
+- **[CRITICAL]** `load()` / `loadstring()` with user input → arbitrary Lua code execution. Never pass user-controlled strings to `load()`; validate and whitelist all dynamic code paths.
+- **[CRITICAL]** `os.execute()` with user-controlled strings → command injection. Use a whitelist of allowed commands or avoid `os.execute()` entirely for user input.
+- **[HIGH]** `io.open()` with user-controlled paths → path traversal. Canonicalize and validate paths against an allowed root before opening.
+- **[HIGH]** `require()` with user-controlled module names → arbitrary module loading. Never construct module names from user input; use a static allowlist.
+- **[MEDIUM]** Lua metatables manipulated to bypass access control → sandbox escape. Lock metatables with `__newindex` guards and freeze sensitive tables.
+- **[MEDIUM]** Globals not sandboxed in embedded Lua environments → host process exposure. Set a restricted `_ENV` sandbox for all user-provided scripts.
+
+---
+
+## Performance
+- **[HIGH]** String concatenation with `..` in loops → O(n²) garbage collection pressure. Collect strings in a table and use `table.concat()` at the end.
+- **[HIGH]** Global variable access in hot loops → globals are ~30% slower than locals due to hash lookups. Cache globals as locals at function top (`local sin = math.sin`).
+- **[HIGH]** Not caching table field lookups in hot loops → repeated hash traversal. Assign frequently accessed fields to locals before the loop.
+- **[MEDIUM]** Creating tables or closures inside inner loops → excessive GC pressure. Pre-allocate and reuse tables; move closure creation outside the loop.
+- **[MEDIUM]** Recursive functions without tail call optimization → stack growth. Rewrite as `return f()` (true tail call) or convert to iterative form.
+- **[LOW]** Not using LuaJIT for performance-critical applications → leaving significant JIT speedups on the table. Evaluate LuaJIT compatibility for the deployment target.
+
+---
+
+## Architecture
+- **[HIGH]** Module pattern not used → global namespace pollution and load-order dependencies. Wrap every module in `local M = {} … return M` and `require()` it explicitly.
+- **[HIGH]** Metatables used for OOP without a consistent class pattern → fragile inheritance chains. Adopt one pattern (e.g., `__index`-based prototype) and enforce it across the codebase.
+- **[MEDIUM]** Circular `require()` dependencies → partially-initialized module tables at require time. Refactor shared state into a third module or use lazy loading.
+- **[MEDIUM]** Error handling not using `pcall`/`xpcall` → unhandled errors crash the running coroutine silently. Wrap all external calls and IO in `pcall`; use `xpcall` with a traceback handler for top-level boundaries.
+- **[LOW]** Coroutines not used for cooperative multitasking where appropriate → blocking code in event-driven hosts (e.g., OpenResty). Yield at IO boundaries using coroutine-based async patterns.
+
+---
+
+## Code Quality
+- **[HIGH]** `local` not used for variables → accidental globals silently pollute `_G` and persist across calls. Declare every variable `local`; use `luacheck` to catch globals.
+- **[HIGH]** Missing `pcall` around risky operations (file IO, network, `require`) → unhandled errors propagate and crash callers. Wrap with `pcall`/`xpcall` and return structured error values.
+- **[MEDIUM]** Magic numbers instead of named constants → intent unclear and values duplicated. Lua has no `const`; define constants as module-level locals with UPPER_SNAKE naming.
+- **[MEDIUM]** Tables used as arrays with mixed integer/string keys → the `#` length operator only counts the integer sequence and gives undefined results for sparse or mixed tables. Use purely integer-keyed tables for arrays and track length explicitly if needed.
+- **[LOW]** Inconsistent use of `:` vs `.` for method calls → runtime errors when `self` is missing or an extra argument is passed. Establish a convention and enforce it in code review.
+
+---
+
+## Common Bugs & Pitfalls
+- **[HIGH]** Array indexing starts at 1, not 0 → off-by-one errors when porting algorithms or interfacing with C. Audit all index arithmetic and document the convention explicitly.
+- **[HIGH]** `nil` in an array breaks the `#` length operator → iterating with `ipairs` stops early; `#` returns an unpredictable value. Track array length in a separate field or avoid `nil` holes.
+- **[MEDIUM]** `and`/`or` used as a ternary expression → `false or default` evaluates to `default` even when the intended value is `false`. Use an explicit `if` expression or helper function.
+- **[MEDIUM]** `==` on tables compares references, not content → two structurally identical tables are never equal. Implement a deep-equality function for value comparison.
+- **[LOW]** Multiple return values silently truncated when assigned to a single variable → data loss with no error. Capture all return values explicitly or use `select('#', ...)` to verify count.