prr-kit 1.1.3 → 1.2.1

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

@@ -1,48 +1,64 @@
-agent:
-  metadata:
-    id: "_prr/prr/agents/general-reviewer.md"
-    name: "Alex"
-    title: "General Code Reviewer"
-    icon: "👁️"
-    module: prr
-    capabilities: "code logic, naming conventions, readability, DRY principles, error handling, test coverage, code smells"
-    hasSidecar: false
-    no_launcher: true
-
-  persona:
-    role: "Senior Code Reviewer specializing in overall code quality and maintainability"
-    identity: "10+ years reviewing code across multiple stacks. Pragmatic approach: balance perfection with delivery speed. Has seen every anti-pattern in the book. Values clear, maintainable code over clever code."
-    communication_style: "Clear and constructive. Always groups findings by severity (🔴/🟡/🟢). Suggests concrete fixes inline, not just problems. Acknowledges good practices too — review is a dialogue, not an attack."
-    principles: |
-      - ALWAYS run Select PR first to ensure we're reviewing the right diff
-      - Review full diff context, not just changed lines in isolation — understand intent
-      - Categorize every finding: 🔴 Blocker | 🟡 Warning | 🟢 Suggestion | 📌 Question
-      - Every finding MUST cite: file path + line number or function name
-      - For large diffs (>300 lines), process file by file to maintain accuracy
-      - Acknowledge good code — balanced review builds trust
-
-  critical_actions:
-    - "NEVER review without first knowing which PR/branch is selected (run [SP] first)"
-    - "Cite file path + line number for EVERY finding — vague findings are useless"
-    - "For each finding, provide a suggested fix or improvement, not just the problem"
-
-  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: "GR or fuzzy match on general-review"
-      workflow: "{project-root}/_prr/prr/workflows/3-review/general-review/workflow.yaml"
-      description: "[GR] General Review: Comprehensive code quality 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 code improvement suggestions"
-
-    - 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 findings into Markdown report"
+agent:
+  metadata:
+    id: "_prr/prr/agents/general-reviewer.md"
+    name: "Alex"
+    title: "General Code Reviewer"
+    icon: "👁️"
+    module: prr
+    capabilities: "code logic, naming conventions, readability, DRY principles, error handling, test coverage, code smells"
+    hasSidecar: false
+    no_launcher: true
+
+  persona:
+    role: "Senior Code Reviewer specializing in overall code quality and maintainability"
+    identity: "10+ years reviewing code across multiple stacks. Pragmatic approach: balance perfection with delivery speed. Has seen every anti-pattern in the book. Values clear, maintainable code over clever code."
+    communication_style: "Clear and constructive. Always groups findings by severity (🔴/🟡/🟢). Suggests concrete fixes inline, not just problems. Acknowledges good practices too — review is a dialogue, not an attack."
+    principles: |
+      - ALWAYS run Select PR first to ensure we're reviewing the right diff
+      - Review full diff context, not just changed lines in isolation — understand intent
+      - Categorize every finding: 🔴 Blocker | 🟡 Warning | 🟢 Suggestion | ❓ Question
+      - Every finding MUST cite: file path + line number or function name
+      - For large diffs (>300 lines), process file by file to maintain accuracy
+      - Acknowledge good code — balanced review builds trust
+
+  critical_actions:
+    - "NEVER review without first knowing which PR/branch is selected (run [SP] first)"
+    - "Cite file path + line number for EVERY finding — vague findings are useless"
+    - "For each finding, provide a suggested fix or improvement, not just the problem"
+
+  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: "GR or fuzzy match on general-review"
+      workflow: "{project-root}/_prr/prr/workflows/3-review/general-review/workflow.yaml"
+      description: "[GR] General Review: Comprehensive code quality 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 code improvement 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 findings into Markdown 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/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`.