prr-kit 1.1.2 → 1.2.0

package/src/prr/agents/performance-reviewer.agent.yaml

@@ -1,45 +1,65 @@
-agent:
-  metadata:
-    id: "_prr/prr/agents/performance-reviewer.md"
-    name: "Petra"
-    title: "Performance Code Reviewer"
-    icon: "⚡"
-    module: prr
-    capabilities: "N+1 query detection, memory leak analysis, async/await patterns, bundle size, caching strategies, database query optimization"
-    hasSidecar: false
-    no_launcher: true
-
-  persona:
-    role: "Senior Performance Engineer specializing in application performance code review"
-    identity: "12+ years optimizing web applications. Has profiled everything from database queries to JavaScript bundle sizes. Knows that premature optimization is evil, but also that ignoring obvious performance anti-patterns is worse."
-    communication_style: "Data-driven and pragmatic. For every performance issue: estimates the impact (milliseconds, memory MB, request count) when possible. Distinguishes between micro-optimizations (skip) and impactful fixes (flag)."
-    principles: |
-      - Focus on impactful performance issues, not micro-optimizations
-      - For database: look for N+1 queries, missing indexes, unneeded SELECT *
-      - For frontend: bundle size, unnecessary re-renders, blocking operations
-      - For async: proper error handling, avoiding callback hell, unnecessary await in loops
-      - For memory: object references, event listener cleanup, large in-memory caches
-      - Quantify impact when possible: "this could add Xms per request" or "X MB memory per user session"
-      - Always suggest the fix, not just the problem
-
-  critical_actions:
-    - "For database operations: always check for N+1 query patterns (loop with DB call inside)"
-    - "For async/await: check for unnecessary sequential awaits that could be parallelized"
-    - "Quantify performance impact when possible — avoids review fatigue on trivial issues"
-
-  menu:
-    - trigger: "SP or fuzzy match on select-pr"
-      exec: "{project-root}/_prr/prr/workflows/1-discover/select-pr/workflow.md"
-      description: "[SP] Select PR to review"
-
-    - trigger: "PR or fuzzy match on performance-review"
-      workflow: "{project-root}/_prr/prr/workflows/3-review/performance-review/workflow.yaml"
-      description: "[PR] Performance Review: N+1, memory, async, bundle size analysis"
-
-    - trigger: "IC or fuzzy match on improve-code"
-      workflow: "{project-root}/_prr/prr/workflows/4-improve/improve-code/workflow.yaml"
-      description: "[IC] Improve Code: Performance-focused code improvements"
-
-    - trigger: "RR or fuzzy match on generate-report"
-      exec: "{project-root}/_prr/prr/workflows/6-report/generate-report/workflow.md"
-      description: "[RR] Generate Report"
+agent:
+  metadata:
+    id: "_prr/prr/agents/performance-reviewer.md"
+    name: "Petra"
+    title: "Performance Code Reviewer"
+    icon: "⚡"
+    module: prr
+    capabilities: "N+1 query detection, memory leak analysis, async/await patterns, bundle size, caching strategies, database query optimization"
+    hasSidecar: false
+    no_launcher: true
+
+  persona:
+    role: "Senior Performance Engineer specializing in application performance code review"
+    identity: "12+ years optimizing web applications. Has profiled everything from database queries to JavaScript bundle sizes. Knows that premature optimization is evil, but also that ignoring obvious performance anti-patterns is worse."
+    communication_style: "Data-driven and pragmatic. For every performance issue: estimates the impact (milliseconds, memory MB, request count) when possible. Distinguishes between micro-optimizations (skip) and impactful fixes (flag)."
+    principles: |
+      - Focus on impactful performance issues, not micro-optimizations
+      - For database: look for N+1 queries, missing indexes, unneeded SELECT *
+      - For frontend: bundle size, unnecessary re-renders, blocking operations
+      - For async: proper error handling, avoiding callback hell, unnecessary await in loops
+      - For memory: object references, event listener cleanup, large in-memory caches
+      - Quantify impact when possible: "this could add Xms per request" or "X MB memory per user session"
+      - Always suggest the fix, not just the problem
+
+  critical_actions:
+    - "For database operations: always check for N+1 query patterns (loop with DB call inside)"
+    - "For async/await: check for unnecessary sequential awaits that could be parallelized"
+    - "Quantify performance impact when possible — avoids review fatigue on trivial issues"
+
+  menu:
+    - trigger: "SP or fuzzy match on select-pr"
+      exec: "{project-root}/_prr/prr/workflows/1-discover/select-pr/workflow.md"
+      description: "[SP] Select PR: Fetch latest and select PR to review"
+
+    - trigger: "DP or fuzzy match on describe-pr"
+      exec: "{project-root}/_prr/prr/workflows/2-analyze/describe-pr/workflow.md"
+      description: "[DP] Describe PR: Understand PR scope before reviewing"
+
+    - trigger: "PR or fuzzy match on performance-review"
+      workflow: "{project-root}/_prr/prr/workflows/3-review/performance-review/workflow.yaml"
+      description: "[PR] Performance Review: N+1, memory, async, bundle size analysis"
+
+    - trigger: "IC or fuzzy match on improve-code"
+      workflow: "{project-root}/_prr/prr/workflows/4-improve/improve-code/workflow.yaml"
+      description: "[IC] Improve Code: Concrete inline code improvements with before/after suggestions"
+
+    - trigger: "AK or fuzzy match on ask-code"
+      exec: "{project-root}/_prr/prr/workflows/5-ask/ask-code/workflow.md"
+      description: "[AK] Ask: Interactive Q&A about specific code changes in this PR"
+
+    - trigger: "RR or fuzzy match on generate-report"
+      exec: "{project-root}/_prr/prr/workflows/6-report/generate-report/workflow.md"
+      description: "[RR] Generate Report: Compile performance findings into report"
+
+    - trigger: "PC or fuzzy match on post-comments"
+      exec: "{project-root}/_prr/prr/workflows/6-report/post-comments/workflow.md"
+      description: "[PC] Post Comments: Post inline review comments to GitHub/GitLab/Azure/Bitbucket PR"
+
+    - trigger: "HH or fuzzy match on help"
+      exec: "{project-root}/_prr/core/tasks/help.md"
+      description: "[HH] Help: Show review workflow guide and available commands"
+
+    - trigger: "CL or fuzzy match on clear or clean or reset"
+      exec: "{project-root}/_prr/core/tasks/clear.md"
+      description: "[CL] Clear: Remove context files and/or review reports from output folder"

package/src/prr/agents/security-reviewer.agent.yaml

@@ -1,43 +1,67 @@
-agent:
-  metadata:
-    id: "_prr/prr/agents/security-reviewer.md"
-    name: "Sam"
-    title: "Security Code Reviewer"
-    icon: "🔒"
-    module: prr
-    capabilities: "OWASP top 10, SQL injection, XSS, auth vulnerabilities, API key exposure, dependency vulnerabilities, cryptography misuse"
-    hasSidecar: false
-    no_launcher: true
-
-  persona:
-    role: "Senior Security Engineer specializing in application security code review"
-    identity: "8+ years in application security and penetration testing. Thinks like an attacker to find vulnerabilities before they do. Familiar with OWASP, NIST, and CWE standards. Never dismisses a potential vulnerability as 'low risk' without evidence."
-    communication_style: "Precise and risk-focused. Always states: WHAT the vulnerability is, WHERE it is (file+line), HOW it could be exploited, and HOW to fix it. Uses severity: Critical/High/Medium/Low/Info instead of the standard severity emojis when appropriate."
-    principles: |
-      - Check OWASP Top 10 for every review: A01-A10
-      - Look for hardcoded secrets, API keys, passwords in code and config files
-      - Check authentication and authorization logic carefully
-      - Validate all user inputs: injection (SQL, XSS, command), path traversal
-      - Check error handling: stack traces and sensitive data must not reach users
-      - Review dependency versions for known CVEs
-      - Check rate limiting on authentication endpoints
-      - For every finding: state impact if exploited
-
-  critical_actions:
-    - "Check for hardcoded secrets in EVERY review — API keys, passwords, tokens"
-    - "Check ALL user input handling for injection vulnerabilities"
-    - "For auth-related code: verify both authentication AND authorization logic"
-    - "State the IMPACT for every finding: what could an attacker do if this is exploited?"
-
-  menu:
-    - trigger: "SP or fuzzy match on select-pr"
-      exec: "{project-root}/_prr/prr/workflows/1-discover/select-pr/workflow.md"
-      description: "[SP] Select PR: Fetch latest and select PR to review"
-
-    - trigger: "SR or fuzzy match on security-review"
-      workflow: "{project-root}/_prr/prr/workflows/3-review/security-review/workflow.yaml"
-      description: "[SR] Security Review: Full OWASP-based security analysis"
-
-    - trigger: "RR or fuzzy match on generate-report"
-      exec: "{project-root}/_prr/prr/workflows/6-report/generate-report/workflow.md"
-      description: "[RR] Generate Report: Compile security findings into report"
+agent:
+  metadata:
+    id: "_prr/prr/agents/security-reviewer.md"
+    name: "Sam"
+    title: "Security Code Reviewer"
+    icon: "🔒"
+    module: prr
+    capabilities: "OWASP top 10, SQL injection, XSS, auth vulnerabilities, API key exposure, dependency vulnerabilities, cryptography misuse"
+    hasSidecar: false
+    no_launcher: true
+
+  persona:
+    role: "Senior Security Engineer specializing in application security code review"
+    identity: "8+ years in application security and penetration testing. Thinks like an attacker to find vulnerabilities before they do. Familiar with OWASP, NIST, and CWE standards. Never dismisses a potential vulnerability as 'low risk' without evidence."
+    communication_style: "Precise and risk-focused. Always states: WHAT the vulnerability is, WHERE it is (file+line), HOW it could be exploited, and HOW to fix it. Uses severity: Critical/High/Medium/Low/Info instead of the standard severity emojis when appropriate."
+    principles: |
+      - Check OWASP Top 10 for every review: A01-A10
+      - Look for hardcoded secrets, API keys, passwords in code and config files
+      - Check authentication and authorization logic carefully
+      - Validate all user inputs: injection (SQL, XSS, command), path traversal
+      - Check error handling: stack traces and sensitive data must not reach users
+      - Review dependency versions for known CVEs
+      - Check rate limiting on authentication endpoints
+      - For every finding: state impact if exploited
+
+  critical_actions:
+    - "Check for hardcoded secrets in EVERY review — API keys, passwords, tokens"
+    - "Check ALL user input handling for injection vulnerabilities"
+    - "For auth-related code: verify both authentication AND authorization logic"
+    - "State the IMPACT for every finding: what could an attacker do if this is exploited?"
+
+  menu:
+    - trigger: "SP or fuzzy match on select-pr"
+      exec: "{project-root}/_prr/prr/workflows/1-discover/select-pr/workflow.md"
+      description: "[SP] Select PR: Fetch latest and select PR to review"
+
+    - trigger: "DP or fuzzy match on describe-pr"
+      exec: "{project-root}/_prr/prr/workflows/2-analyze/describe-pr/workflow.md"
+      description: "[DP] Describe PR: Understand PR scope before reviewing"
+
+    - trigger: "SR or fuzzy match on security-review"
+      workflow: "{project-root}/_prr/prr/workflows/3-review/security-review/workflow.yaml"
+      description: "[SR] Security Review: Full OWASP-based security analysis"
+
+    - trigger: "IC or fuzzy match on improve-code"
+      workflow: "{project-root}/_prr/prr/workflows/4-improve/improve-code/workflow.yaml"
+      description: "[IC] Improve Code: Concrete inline code improvements with before/after suggestions"
+
+    - trigger: "AK or fuzzy match on ask-code"
+      exec: "{project-root}/_prr/prr/workflows/5-ask/ask-code/workflow.md"
+      description: "[AK] Ask: Interactive Q&A about specific code changes in this PR"
+
+    - trigger: "RR or fuzzy match on generate-report"
+      exec: "{project-root}/_prr/prr/workflows/6-report/generate-report/workflow.md"
+      description: "[RR] Generate Report: Compile security findings into report"
+
+    - trigger: "PC or fuzzy match on post-comments"
+      exec: "{project-root}/_prr/prr/workflows/6-report/post-comments/workflow.md"
+      description: "[PC] Post Comments: Post inline review comments to GitHub/GitLab/Azure/Bitbucket PR"
+
+    - trigger: "HH or fuzzy match on help"
+      exec: "{project-root}/_prr/core/tasks/help.md"
+      description: "[HH] Help: Show review workflow guide and available commands"
+
+    - trigger: "CL or fuzzy match on clear or clean or reset"
+      exec: "{project-root}/_prr/core/tasks/clear.md"
+      description: "[CL] Clear: Remove context files and/or review reports from output folder"

package/src/prr/config-template.yaml

@@ -0,0 +1,97 @@
+# prr-kit Configuration Template
+# Copy this file to your project: _prr/prr/config.yaml
+
+# ─── Identity ──────────────────────────────────────────────────────────────
+user_name: YourName
+communication_language: English      # Language for all review output
+
+# ─── Project ───────────────────────────────────────────────────────────────
+project_name: my-project
+target_repo: .                       # Path to git repo (. = current directory)
+
+# ─── Platform ──────────────────────────────────────────────────────────────
+platform: github                     # auto | github | gitlab | azure | bitbucket | none
+platform_repo: "org/repo-name"       # Used for gh pr list, gh pr view, etc.
+
+# ─── Output ────────────────────────────────────────────────────────────────
+review_output: ./_prr-output/reviews # Where review reports are written
+auto_post_comment: false             # Set to true to auto-post findings to GitHub/GitLab/Azure/Bitbucket after every review
+                                     # (skips the "PC" prompt in quick workflow)
+
+# ─── Context Collection ────────────────────────────────────────────────────
+context_collection:
+  enabled: true
+  mode: pr-specific                  # Always fresh, never cached
+
+  # Local primary sources (read if file exists)
+  primary_sources:
+    - CLAUDE.md
+    - AGENTS.md
+    - .github/CLAUDE_CODE_RULES.md
+    - .clauderules
+
+  # Config files (matched to file types changed in PR)
+  config_files:
+    - .eslintrc*
+    - .prettierrc*
+    - tsconfig.json
+    - vite.config.*
+    - webpack.config.*
+    - pyproject.toml
+    - .flake8
+
+  # Standards docs (read relevant sections based on PR domains)
+  standards_docs:
+    - CONTRIBUTING.md
+    - ARCHITECTURE.md
+    - docs/**/*.md
+
+  # Inline code annotations extracted from changed files
+  inline_annotations:
+    enabled: true
+    patterns:
+      - "@context:"
+      - "@security:"
+      - "@pattern:"
+      - "@rule:"
+
+# ─── External Sources ──────────────────────────────────────────────────────
+# Enable to allow prr-kit to use MCP tools and RAG systems available in
+# your Claude Code session. No schema required per-tool — Claude auto-discovers
+# what tools are available and maps them to the intents declared below.
+external_sources:
+  enabled: false                     # Set to true to activate
+
+  mcp:
+    enabled: true
+    # Declare what kinds of context you want from MCP tools.
+    # The agent will discover available tools and use them accordingly.
+    # Remove intents you don't need.
+    intents:
+      - knowledge_base               # Confluence, Notion → team standards, ADRs
+      - project_management           # Jira, Linear → linked issue + acceptance criteria
+      - design                       # Figma, Zeplin → design specs (UI PRs only)
+      # - code_intelligence          # Sourcegraph → similar patterns (uncomment if needed)
+
+    hints:
+      branch_issue_pattern: "([A-Z]+-\\d+)"  # Regex to extract issue key from branch name
+                                              # e.g. feature/ENG-123-auth → ENG-123
+
+  rag:
+    enabled: false                   # Set to true if you have RAG tools configured
+    # Intents tell the agent what to query for in the RAG system
+    intents:
+      - similar_patterns             # Find similar code in the codebase
+      - past_decisions               # Previous review decisions for similar code
+      # - architecture_examples      # Embedded architecture docs (uncomment if needed)
+
+  # Plain URL sources — fetched via WebFetch regardless of MCP availability
+  sources: []
+  # Example:
+  # sources:
+  #   - type: url
+  #     name: Shared ESLint config
+  #     url: https://raw.githubusercontent.com/org/standards/main/eslint.md
+  #   - type: url
+  #     name: Security guidelines
+  #     url: https://wiki.company.com/public/security-standards

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

@@ -0,0 +1,55 @@
+# Actix-Web — Stack-Specific Review Rules
+
+> Applies to: GR · SR · PR · AR · BR
+> Detection signals: actix-web, HttpServer::new, web::get(), web::post(), App::new(), HttpResponse, #[get(, #[post(
+
+---
+
+## Security
+- **[CRITICAL]** Missing authentication middleware on protected routes → unauthenticated requests reach sensitive handlers. Wrap protected resource factories in an authentication middleware that validates session/JWT before dispatching.
+- **[CRITICAL]** Shared state in `web::Data<Mutex<T>>` used incorrectly (e.g., holding the lock across await points) → deadlock or starvation under concurrent load. Use `RwLock` for read-heavy state and release locks before any await.
+- **[CRITICAL]** SQL injection in raw query strings built with string formatting → attacker-controlled input alters query structure. Always use parameterized queries via sqlx, diesel, or SeaORM.
+- **[HIGH]** CORS not configured via `actix-cors` → default behavior may reject legitimate cross-origin requests or accept all origins depending on config. Explicitly configure allowed origins and methods.
+- **[HIGH]** No rate limiting → brute-force and DoS attacks succeed without throttling. Integrate a rate-limiting middleware at the `App::wrap()` level.
+- **[HIGH]** User input in file paths without sanitization → path traversal allows reading or overwriting arbitrary files on the server. Canonicalize and validate paths, rejecting any that escape the intended directory.
+- **[MEDIUM]** Sensitive data returned in error responses → internal paths, DB errors, or stack traces exposed to clients. Return generic error messages externally and log details internally.
+- **[MEDIUM]** JWT not validated for expiry, signature, and audience claims → expired or forged tokens accepted. Use a well-tested JWT crate and validate all claims on every request.
+
+---
+
+## Performance
+- **[CRITICAL]** Blocking operations (synchronous I/O, CPU-heavy computation) in async handlers → Actix-web worker threads stall, degrading all concurrent requests. Use `web::block()` to run blocking work on a dedicated thread pool.
+- **[HIGH]** `Mutex` contention on `web::Data<Mutex<T>>` under load → high-concurrency requests queue waiting for the lock, serializing throughput. Use `RwLock` for read-heavy data or a lock-free structure.
+- **[HIGH]** Large request bodies not streamed with `Payload` → entire body loaded into memory before processing, causing high memory pressure. Process large uploads as a stream using the `Payload` extractor.
+- **[HIGH]** Not using connection pooling (e.g., sqlx `PgPool`, bb8) → a new DB connection established per request, causing latency spikes and exhausting server resources. Configure and share a connection pool via `web::Data`.
+- **[MEDIUM]** Serializing large response structs without streaming → full response buffered in memory before sending. Implement chunked or streaming responses for large datasets.
+- **[MEDIUM]** Not configuring worker thread count and async executor appropriately → default settings may not match workload characteristics. Tune `HttpServer::workers()` and consider async vs CPU-bound workload split.
+
+---
+
+## Architecture
+- **[HIGH]** Business logic implemented in handler functions → handlers become large, untestable, and tightly coupled to HTTP concerns. Extract logic into service structs and inject them via `web::Data`.
+- **[MEDIUM]** Not using `ServiceConfig` for modular route registration → all routes defined in one place, making the app configuration unmanageable. Use `cfg.service()` in per-domain configure functions.
+- **[HIGH]** Error types not implementing `ResponseError` → all errors become opaque 500 responses with manual error handling in every handler. Define a custom error type implementing `ResponseError` with appropriate status codes.
+- **[MEDIUM]** Using deprecated `App::data()` instead of `App::app_data()` → data registered with the old API may not be accessible in newer middleware. Migrate all state registration to `App::app_data()`.
+- **[MEDIUM]** Middleware not reusing allocations across requests → per-request allocations in middleware increase GC pressure under load. Use `Arc` and pre-allocated buffers in middleware implementations.
+
+---
+
+## Code Quality
+- **[CRITICAL]** `unwrap()` in handler functions → a panic crashes the Actix worker thread, returning a 500 to all requests on that thread. Replace with proper error propagation using `?` and the `ResponseError` trait.
+- **[MEDIUM]** Not using `actix_web::test` utilities for handler testing → tests spin up a real HTTP server, making them slow and fragile. Use `test::init_service` and `test::call_service` for fast in-process handler testing.
+- **[MEDIUM]** Missing request logging middleware → requests and errors go untracked in production, making debugging difficult. Add `actix-web::middleware::Logger` or a structured logging middleware.
+- **[MEDIUM]** Not validating Content-Type before parsing request body → unexpected content types return a confusing 400 without a clear message. Check the Content-Type header early and return a structured error on mismatch.
+- **[LOW]** Not setting keep-alive or connection timeout in server config → idle connections held open indefinitely waste file descriptors. Configure `HttpServer::keep_alive()` appropriately for the workload.
+- **[MEDIUM]** Using panic-based error handling (`expect("msg")`) for expected failure modes → panics crash worker threads for recoverable errors. Reserve panics for truly unrecoverable states; use `Result` for expected failures.
+
+---
+
+## Common Bugs & Pitfalls
+- **[HIGH]** `web::Data<T>` not registered before handler requires it → every request returns a 500 with "App data is not configured". Register all `web::Data` in the `App::app_data()` call before defining routes.
+- **[MEDIUM]** `HttpResponse::Ok()` not finalized with `.finish()` or `.json()` → an empty or incomplete response is sent to the client. Always terminate the response builder with a body method.
+- **[HIGH]** Multipart form parsing not handling the field stream correctly with `while let Some(field) = payload.next()` → fields skipped or processing stops at first error. Handle each field in the async loop and propagate errors.
+- **[MEDIUM]** `actix::System` blocking calls used inside an async actix-web context → deadlock or panic from nested runtime invocations. Avoid Actix actor system calls inside async web handlers; use async messaging instead.
+- **[HIGH]** Not implementing graceful shutdown → in-flight requests dropped when the process receives SIGTERM. Register a signal handler and call `server.stop()` to drain active connections before exiting.
+- **[MEDIUM]** Cloning `web::Data<T>` repeatedly in hot paths → unnecessary `Arc` clone overhead accumulates. Store the inner reference where repeated access is needed within a single handler execution.

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

@@ -0,0 +1,47 @@
+# Alpine.js — Stack-Specific Review Rules
+
+> Applies to: GR · SR · PR · AR · BR
+> Detection signals: `alpinejs`, `x-data`, `x-bind`, `x-on`, `x-model`, `from 'alpinejs'`, `Alpine.data()`
+
+---
+
+## Security
+- **[CRITICAL]** `x-html` directive used with user-controlled content → XSS allowing arbitrary script execution. Replace `x-html` with `x-text` for user content; sanitize with DOMPurify if HTML rendering is required.
+- **[CRITICAL]** `$el.innerHTML = userInput` written inside an Alpine component method → XSS bypassing Alpine's safe interpolation. Use `$el.textContent` for text or create elements via `document.createElement`.
+- **[CRITICAL]** `Alpine.evaluate(el, userInput)` called with user-controlled expression string → arbitrary JavaScript code injection. Never evaluate user-supplied strings as Alpine expressions; use data-driven rendering instead.
+- **[HIGH]** `fetch` calls inside Alpine components missing CSRF token → state-changing requests forgeable. Include CSRF token from a meta tag in all non-GET fetch requests: `headers: { 'X-CSRF-Token': token }`.
+- **[MEDIUM]** Sensitive data (auth tokens, PII) stored in `x-data` object → visible in DOM via browser DevTools and queryable by any script. Store secrets server-side; reference only non-sensitive display state in `x-data`.
+
+---
+
+## Performance
+- **[HIGH]** Large `x-data` object on the root `<body>` or `<main>` element → Alpine tracks reactivity for the entire page subtree on every change. Scope `x-data` to the smallest possible DOM subtree that needs reactivity.
+- **[HIGH]** `x-for` without `:key` binding on dynamically changing lists → full DOM re-creation on every list mutation. Always add `:key="item.id"` to the `x-for` template element for efficient keyed diffing.
+- **[MEDIUM]** Heavy computation or synchronous API calls inside `x-init` → blocks initial render, causing visible delay. Move slow work to `$nextTick` callbacks or use `fetch` with loading state toggling.
+- **[MEDIUM]** `$watch` on a deeply nested object reference → Alpine observes the entire object tree, causing wide re-evaluation. Watch primitive signals or specific dotted paths; flatten state shape when possible.
+- **[LOW]** Missing `x-cloak` with corresponding CSS `[x-cloak] { display: none }` → flash of un-initialized template markup before Alpine loads. Add `x-cloak` to elements that should be hidden until Alpine initializes.
+
+---
+
+## Architecture
+- **[HIGH]** Complex business logic written as inline `x-on:click="..."` expression strings → untestable, hard to read, limited to expression length. Extract logic into `x-data` methods or `Alpine.data()` component definitions.
+- **[HIGH]** Identical `x-data` object literals duplicated across multiple elements instead of `Alpine.data()` → no single source of truth, maintenance burden. Register reusable components with `Alpine.data('componentName', () => ({ ... }))`.
+- **[HIGH]** Alpine components mixed with direct jQuery or vanilla DOM manipulation on the same elements → state conflicts between Alpine's reactive model and imperative DOM changes. Choose one paradigm per element; avoid external DOM mutations on Alpine-managed elements.
+- **[MEDIUM]** Complex shared state not using `Alpine.store()` → prop threading or duplicated state across sibling components. Define global stores with `Alpine.store('storeName', { ... })` and access via `$store.storeName`.
+
+---
+
+## Code Quality
+- **[CRITICAL]** `x-data="{}"` as an object literal on a template element cloned by `x-for` → all cloned instances share the same object reference, mutations affect all items. Use `x-data="() => ({ ... })"` (function form) to get a fresh object per instance.
+- **[MEDIUM]** `$store`, `$dispatch`, `$refs` magic properties used without understanding their reactivity scope → unexpected behavior when accessing across component boundaries. Review Alpine's magic property documentation; `$refs` is local, `$store` is global, `$dispatch` bubbles DOM events.
+- **[MEDIUM]** `x-data` expressions longer than a few tokens written inline → readability collapses, no syntax highlighting. Move all but the simplest initializations to `Alpine.data()` or a `<script>` block.
+- **[LOW]** Alpine version loaded from CDN without a pinned version tag (`@latest`) → breaking changes auto-applied on next CDN cache miss. Pin to a specific semver: `alpinejs@3.13.5`.
+
+---
+
+## Common Bugs & Pitfalls
+- **[CRITICAL]** `x-data="{}"` (plain object) on repeated elements → object is shared, all instances mutate the same state. Always use the function form `x-data="() => ({})"` to create independent state per element.
+- **[HIGH]** `x-model` applied to a non-input element (div, span) without defining a custom getter/setter → model binding silently does nothing. Use `x-model` only on form controls; for custom elements define `x-modelable`.
+- **[MEDIUM]** `x-show` used where `x-if` is needed (and vice versa) → `x-show` toggles `display` (element stays in DOM), `x-if` fully adds/removes. Use `x-if` for conditionally rendered heavy components; use `x-show` for simple visibility toggling.
+- **[MEDIUM]** DOM reads immediately after state mutation without `$nextTick` → reading stale DOM before Alpine has flushed reactive updates. Wrap post-mutation DOM reads in `this.$nextTick(() => { ... })`.
+- **[LOW]** `x-transition` classes conflicting with Tailwind's transition utilities applied to the same element → competing transition durations causing visual glitches. Use either `x-transition` directives or Tailwind transition classes on an element, not both.

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

@@ -0,0 +1,53 @@
+# Android — Stack-Specific Review Rules
+
+> Applies to: GR · SR · PR · AR · BR
+> Detection signals: `*.kt` or `*.java` in Android project, `AndroidManifest.xml`, `build.gradle` with `com.android.application`, `Activity`, `Fragment`, `ViewModel`, `Compose`
+
+---
+
+## Security
+- **[CRITICAL]** Sensitive data (tokens, PII, credentials) stored in `SharedPreferences` unencrypted → readable by root or backup extraction. Replace with `EncryptedSharedPreferences` from Jetpack Security library.
+- **[HIGH]** `WebView.setJavaScriptEnabled(true)` combined with `addJavascriptInterface` → XSS in the loaded page can call exposed Java/Kotlin methods and execute native code. Validate all URLs loaded in WebView; use `@JavascriptInterface` only on methods that are safe to call from web content.
+- **[HIGH]** `Activity`, `Service`, or `BroadcastReceiver` exported in `AndroidManifest.xml` without `android:permission` → any installed app can launch or send intents. Add `android:exported="false"` or a custom `android:permission` to all components not intended for external access.
+- **[HIGH]** API keys, OAuth secrets, or endpoints hardcoded in `BuildConfig` fields or `res/values/strings.xml` → extracted from APK with `apktool` in seconds. Store secrets server-side and fetch at runtime; use Android Keystore for keys that must live on device.
+- **[HIGH]** SQL injection via `rawQuery(userInput, null)` in SQLite → database manipulation or data exfiltration. Always use parameterized queries: `rawQuery("SELECT ... WHERE id = ?", arrayOf(id))` or Room's `@Query` with bound parameters.
+- **[HIGH]** `FileProvider` paths configured too broadly (e.g., root `/`) → any file in the app sandbox shared with external apps. Restrict `<paths>` in the FileProvider XML to the minimum required directory.
+- **[MEDIUM]** SSL certificate validation disabled by overriding `TrustManager` to accept all certs → undetectable MITM on all HTTPS traffic. Use the default `TrustManager`; for testing use a network security config, not production trust-all code.
+
+---
+
+## Performance
+- **[HIGH]** Network requests made on the main thread → `NetworkOnMainThreadException` crash on API 11+. Move all network calls to a coroutine with `Dispatchers.IO` or a background thread.
+- **[HIGH]** Heavy computation or IO performed in `onDraw()` → dropped frames and jank at every draw cycle. Move all computation outside the draw path; `onDraw` should only issue canvas draw calls.
+- **[HIGH]** Activity or Fragment references held by long-lived objects (singletons, callbacks, `companion object`) → memory leak until process death. Use `WeakReference`, `ViewModel` (lifecycle-scoped), or pass context only to short-lived objects.
+- **[HIGH]** `RecyclerView.Adapter.notifyDataSetChanged()` called instead of `DiffUtil` → entire list rebinds and re-draws on any change, causing visible flicker. Use `DiffUtil.calculateDiff()` or `ListAdapter` with `DiffUtil.ItemCallback`.
+- **[MEDIUM]** Full-resolution `Bitmap` loaded into memory for a small `ImageView` → OOM on devices with limited heap. Use Glide or Coil with target size constraints, or manually decode with `BitmapFactory.Options.inSampleSize`.
+- **[MEDIUM]** `ViewModel` not used for UI state → state lost on configuration change (rotation), causing unnecessary re-fetches and blank screens. Hoist all UI state into a `ViewModel` and expose it via `StateFlow` or `LiveData`.
+- **[LOW]** `findViewById()` called repeatedly instead of using `ViewBinding` → minor overhead and null-safety risk. Enable `viewBinding` in `build.gradle` and use generated binding classes.
+
+---
+
+## Architecture
+- **[HIGH]** Business logic placed directly in `Activity` or `Fragment` → untestable without an emulator and tightly coupled to the Android lifecycle. Move logic to `ViewModel` (MVVM) or a `Presenter`/`Store` (MVI); keep UI classes as thin observers.
+- **[HIGH]** `Repository` pattern not used → UI layer directly calls data sources (Room DAO, Retrofit service), making data source swaps and unit testing impossible. Introduce a `Repository` class that abstracts all data access and exposes domain models.
+- **[MEDIUM]** Dependency injection done manually at scale instead of using Hilt or Koin → constructor chains become unmanageable; hard to swap implementations in tests. Adopt Hilt (compile-time DI, recommended by Google) or Koin (runtime DI, simpler setup).
+- **[MEDIUM]** Mixing `LiveData` and `StateFlow`/`SharedFlow` without a clear policy → inconsistent lifecycle handling and confusion about replay behavior. Standardize on `StateFlow`/`SharedFlow` for new code; `LiveData` only where Jetpack libraries require it.
+- **[LOW]** Fragment transactions managed manually instead of using Navigation Component → back-stack fragmentation, inconsistent transitions, and deep-link handling is ad hoc. Adopt Navigation Component with a `NavGraph` for all screen transitions.
+
+---
+
+## Code Quality
+- **[HIGH]** `AsyncTask` used for background work → deprecated in API 30 with known memory leak patterns. Replace with `viewModelScope.launch { withContext(Dispatchers.IO) { ... } }`.
+- **[HIGH]** Non-null assertion operator `!!` used on nullable Kotlin types → `NullPointerException` at runtime when the value is actually null. Use safe call `?.`, `?:` Elvis operator, or explicit null checks.
+- **[MEDIUM]** Coroutines launched with `GlobalScope` or without `lifecycleScope`/`viewModelScope` → coroutine outlives the Activity/Fragment, leaking references and executing after destruction. Use `lifecycleScope` in UI components and `viewModelScope` in `ViewModel`.
+- **[MEDIUM]** Runtime permissions requested without showing rationale when `shouldShowRequestPermissionRationale()` returns true → users denied permission without understanding why, causing silent feature breakage. Show an explanation dialog before re-requesting.
+- **[LOW]** `lint` checks not run in CI → Android-specific issues (missing translations, incorrect resource references, API level violations) undetected until runtime. Add `./gradlew lint` to CI and treat `Error` severity as a build failure.
+
+---
+
+## Common Bugs & Pitfalls
+- **[HIGH]** `Activity` `Context` stored in a singleton or static field → Activity is never garbage collected, leaking the entire view hierarchy. Pass only `Application` context to singletons; use `context.applicationContext` for long-lived objects.
+- **[HIGH]** Fragment added to the back stack multiple times without checking `isAdded` or using `findFragmentByTag` → duplicate fragments stacked on top of each other, causing UI glitches and double event handling. Always check `fragmentManager.findFragmentByTag(tag)` before adding.
+- **[MEDIUM]** `onCreate()` not checking `savedInstanceState` before re-initializing state → data reset and redundant network calls on every rotation or process restore. Guard initialization with `if (savedInstanceState == null) { ... }`.
+- **[MEDIUM]** `startActivityForResult()` / `onActivityResult()` used in new code → deprecated; result delivery unreliable across process death. Use `registerForActivityResult()` with the appropriate `ActivityResultContract`.
+- **[LOW]** Hardcoded pixel sizes used instead of `dp`/`sp` units → UI elements appear too large or too small on different screen densities. Use `dp` for dimensions and `sp` for text sizes; define in `dimens.xml`.

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

@@ -0,0 +1,96 @@
+# Angular — Stack-Specific Review Rules
+
+> Applies to: GR · SR · PR · AR · BR
+> Detection signals: `*.component.ts`, `@Component(`, `@Injectable(`, `@NgModule(`, `angular.json`, `@angular/` in deps, `standalone: true`, `signal(`, `inject(`
+
+---
+
+## Security
+
+- **[CRITICAL]** `bypassSecurityTrustHtml()` / `DomSanitizer.bypassSecurityTrust*()` with user-controlled content → XSS. Angular sanitizes by default; bypass only for fully trusted content.
+- **[CRITICAL]** `[innerHTML]` binding with user content without sanitization → XSS.
+- **[HIGH]** Route guard missing on protected routes (`canActivate`, `canActivateChild`, `canMatch`) → unauthenticated access.
+- **[HIGH]** HTTP interceptor not adding auth header on all requests → API calls without credentials.
+- **[HIGH]** `HttpClient` calls made without CSRF token on state-changing requests.
+- **[HIGH]** Template injection via Angular's `templateUrl` loading from user-controlled path (server-rendered).
+- **[HIGH]** Sensitive data stored in `localStorage` via Angular service → accessible to injected scripts.
+- **[HIGH]** `window.location.href` set from route params without validation → open redirect.
+- **[MEDIUM]** CORS configured permissively in Angular proxy config (`angular.json`) left in production.
+- **[MEDIUM]** Error messages from HTTP errors shown directly to user → info disclosure.
+- **[MEDIUM]** JWT stored in memory (signal/service) not cleared on logout → token persists in JS heap.
+- **[LOW]** Angular DevTools enabled in production → component tree exposed.
+
+---
+
+## Performance
+
+- **[HIGH]** Component not using `OnPush` change detection for data-heavy components → Angular checks entire tree on every event.
+- **[HIGH]** Subscription not unsubscribed in `ngOnDestroy` (or not using `async` pipe / `takeUntilDestroyed`) → memory leak.
+- **[HIGH]** `trackBy` missing on `*ngFor` / `@for` with large/dynamic lists → full DOM re-render on any change.
+- **[HIGH]** Signal computed function doing expensive work → not memoized correctly if dependencies unstable.
+- **[HIGH]** Multiple HTTP calls made sequentially that could be parallel → use `forkJoin` or `combineLatest`.
+- **[HIGH]** Not using lazy-loaded feature modules / routes for large sections → oversized initial bundle.
+- **[HIGH]** `BehaviorSubject.value` accessed synchronously in template → not reactive, stale value.
+- **[HIGH]** `toSignal()` without `initialValue` causing nullable type complications and unnecessary null checks.
+- **[MEDIUM]** Heavy computation in template expressions → recalculated every CD cycle; use `pipe` (pure) or `computed()`.
+- **[MEDIUM]** `APP_INITIALIZER` doing slow async work → delays app startup; defer non-critical init.
+- **[MEDIUM]** Zone.js detecting changes from unrelated third-party events (analytics, maps) → use `runOutsideAngular`.
+- **[MEDIUM]** Images not using `NgOptimizedImage` → no lazy loading or size optimization.
+- **[MEDIUM]** `ChangeDetectorRef.detectChanges()` called in a loop → manual CD triggering defeats OnPush benefits.
+- **[LOW]** `async` pipe used multiple times on same observable in template → multiple subscriptions; use `as` syntax.
+- **[LOW]** Not using `@defer` blocks (Angular 17+) for below-fold components.
+
+---
+
+## Architecture
+
+- **[HIGH]** Business logic in component class → controllers should only handle view concerns; move to injectable service.
+- **[HIGH]** Component directly calling `HttpClient` instead of going through service layer → untestable, tightly coupled.
+- **[HIGH]** Circular dependency between services → Angular DI throws at runtime.
+- **[HIGH]** `inject()` called outside injection context (not in constructor, field initializer, or factory) → runtime error.
+- **[HIGH]** Smart/dumb component boundary violated — presentational component directly injecting services.
+- **[HIGH]** State management done via service with plain properties instead of `BehaviorSubject`/`signal` → no reactivity.
+- **[HIGH]** `NgModule` architecture mixed with standalone components without migration plan → confusion.
+- **[MEDIUM]** Missing `providedIn: 'root'` vs module-scoped provider — wrong scope causes multiple instances.
+- **[MEDIUM]** Using `any` type in component `@Input()`/`@Output()` → loses type safety at component boundary.
+- **[MEDIUM]** `Subject` used where `BehaviorSubject` needed — late subscribers miss current value.
+- **[MEDIUM]** Effects not used for signal-based side effects (Angular 17+) → mixing reactive and imperative.
+- **[MEDIUM]** Route resolver overloading — doing too much data fetching causing slow navigation.
+- **[LOW]** Module not feature-scoped — all declarations in `AppModule` → slow compilation, poor separation.
+- **[LOW]** Not using `InjectionToken` for config values → relying on `string` tokens causing collision.
+
+---
+
+## Code Quality
+
+- **[HIGH]** `ngOnInit` subscribing to Observable without `async` pipe or `takeUntilDestroyed` → memory leak.
+- **[HIGH]** `@Input()` not using `required: true` (Angular 16+) for required inputs → runtime undefined with no warning.
+- **[HIGH]** Signal mutations done with `set()` instead of `update()` when new value depends on old → stale value race.
+- **[HIGH]** `EventEmitter` type not specified (`EventEmitter` vs `EventEmitter<string>`) → runtime type mismatch.
+- **[MEDIUM]** Template reference variables (`#ref`) used for logic across complex templates → tight coupling.
+- **[MEDIUM]** `@ViewChild` accessed before `ngAfterViewInit` → undefined access.
+- **[MEDIUM]** `*ngIf` with multiple conditions not extracted to component method → unreadable template.
+- **[MEDIUM]** RxJS operators not used (`switchMap`, `takeUntil`, `shareReplay`) → anti-patterns.
+- **[MEDIUM]** `switchMap` used when `mergeMap` needed (or vice versa) → requests cancelled or duplicated.
+- **[MEDIUM]** Not using Angular's new control flow (`@if`, `@for`, `@switch`) in Angular 17+ projects.
+- **[LOW]** Missing `standalone: true` when upgrading from NgModule-based components (Angular 14+).
+- **[LOW]** `console.log` left in component lifecycle hooks → production noise.
+- **[LOW]** Pipes not used for data transformation in template → inline ternary/method calls everywhere.
+
+---
+
+## Common Bugs & Pitfalls
+
+- **[HIGH]** `ExpressionChangedAfterItHasBeenCheckedError` — modifying bound value in `ngAfterViewInit` without `ChangeDetectorRef.detectChanges()`.
+- **[HIGH]** `async` pipe used with cold observable that never completes → subscription held forever.
+- **[HIGH]** `switchMap` in effects cancelling in-flight HTTP requests on rapid emissions → use `exhaustMap` for form submits.
+- **[HIGH]** Signal `effect()` creating infinite loop — reading and writing same signal in effect body.
+- **[HIGH]** `DestroyRef` injection not used with `takeUntilDestroyed()` outside constructor → requires injection context.
+- **[HIGH]** `HttpClient` returning cold observable — not subscribing means request never fires.
+- **[MEDIUM]** `Subject` vs `BehaviorSubject` confusion — using Subject where late subscribers need current value.
+- **[MEDIUM]** Calling `markForCheck()` excessively in OnPush → defeats the purpose.
+- **[MEDIUM]** Route params accessed via `snapshot` inside component that needs to react to param changes → use `paramMap` observable.
+- **[MEDIUM]** Interceptor modifying request without cloning → mutating immutable `HttpRequest`.
+- **[MEDIUM]** `providedIn: 'root'` on service with state meant to be scoped per module → shared state bug.
+- **[LOW]** Forgetting `@Output()` decorator on EventEmitter → event never emits to parent.
+- **[LOW]** `HostListener` not cleaned up — unlike subscriptions, it IS cleaned up by Angular but double-attaching is possible via manual `addEventListener`.