Rule Files Sync

.actual/rules/cross-cutting-aggregate-queries-select-3889.md

@@ -0,0 +1,43 @@
+# Use PostgreSQL with Connection Pooling for Data Access: Aggregate Queries Select
+
+These rules are ALWAYS ACTIVE for all Node.js/Express application code that performs database operations against PostgreSQL, particularly code in `server/src/` that initializes database connections or executes queries.
+
+### Rules
+
+- **R-PG-001** MUST: Use the pg library's Pool class for connection management, initialized once at module level with DATABASE_URL from environment variables.
+- **R-PG-002** MUST: All queries containing user-supplied data, request parameters, or external data MUST use parameterized queries with positional placeholders ($1, $2, $3, etc.).
+- **R-PG-003** MUST: SSL configuration MUST be explicitly defined in Pool initialization options with appropriate certificate handling for the deployment environment.
+- **R-PG-004** SHOULD: Aggregate queries (SELECT SUM) SHOULD be used for computing derived metrics across the dataset rather than fetching and aggregating in application code.
+- **R-PG-005** SHOULD: All pool.query() calls SHOULD be wrapped in try-catch blocks with appropriate error responses for database failures.
+- **R-PG-006** MAY: Connection pool event listeners (pool.on('error')) MAY be added to log connection issues and monitor pool health.
+
+### Verify
+
+```bash
+# Verify Pool initialization with DATABASE_URL
+grep -r 'new Pool' server/src/ | grep -q 'connectionString.*DATABASE_URL' && echo 'Pool initialization found'
+
+# Verify parameterized queries are used
+grep -r 'pool.query' server/src/ | grep -E '\$[0-9]' && echo 'Parameterized queries detected'
+
+# Verify SSL configuration is present
+grep -r 'ssl.*rejectUnauthorized' server/src/ && echo 'SSL configuration present'
+
+# Verify no direct Client connections are used
+! grep -r 'new Client' server/src/ | grep -v 'Pool' && echo 'No direct Client connections found'
+
+# Verify no raw SQL concatenation patterns
+! grep -r "query.*\+.*process\.env" server/src/ && echo 'No raw SQL concatenation detected'
+```
+
+**Accept when:**
+- All database queries use the Pool instance rather than direct Client connections
+- All queries containing user-supplied data use parameterized queries with positional placeholders ($1, $2, etc.)
+- SSL configuration is explicitly defined in Pool initialization options
+- Aggregate queries (SELECT SUM) are used for computing derived metrics across the dataset
+- All pool.query() calls are wrapped in try-catch blocks or equivalent error handling
+- No raw SQL string concatenation patterns are present in the codebase
+
+<enforcement>
+Claude Code MUST NOT skip or defer verification. All R-PG-00X rules marked MUST are non-negotiable and must pass verification before code is accepted. SHOULD rules represent best practices that should be followed unless explicitly documented exceptions exist with security review approval.
+</enforcement>

.actual/rules/cross-cutting-allowlist-not-include-b4a6.md

@@ -0,0 +1,33 @@
+# Configure CORS Middleware with Explicit Origin Allowlist for Cross-Origin API Access: Allowlist Not Include
+
+These rules are ALWAYS ACTIVE for all HTTP endpoints exposed by the Express.js application, cross-origin requests from browser-based clients, and middleware stack initialization in server/src/index.ts.
+
+### Rules
+
+- **R-CORS-001** MUST_NOT: The allowlist MUST NOT include origins that are not under organizational control or explicitly trusted.
+
+### Verify
+
+```bash
+# Check for explicit CORS configuration with origin parameter (not wildcard)
+grep -r "cors({" server/src/ | grep -E "(origin|allowedHeaders)" | grep -v "\*"
+
+# Verify Access-Control-Allow-Origin headers are set correctly for allowed origins
+curl -H "Origin: https://suraj-gov.github.io/sorter" -I http://localhost:${PORT:-3000}/ | grep -i "access-control-allow-origin"
+
+# Check for localhost in CORS config (should not be in production)
+grep -r "localhost" server/src/ | grep -i cors && echo "WARNING: localhost found in CORS config"
+```
+
+**Accept when:**
+- CORS middleware is configured with explicit origin allowlist (not wildcard) and registered before route handlers in the Express.js middleware stack
+- Verification commands confirm that Access-Control-Allow-Origin headers are set correctly for allowed origins and requests from unauthorized origins are blocked
+- Production configuration excludes development origins (localhost) and all allowed origins use HTTPS protocol
+- The cors middleware configuration uses the 'origin' parameter rather than 'allowedHeaders' for origin validation
+- Origin allowlist is extracted to environment variables (e.g., CORS_ALLOWED_ORIGINS) with comma-separated values
+- Separate configuration files exist for development and production environments, with localhost origins excluded from production builds
+- Integration tests verify CORS headers are correctly set for allowed origins and blocked for unauthorized origins
+
+<enforcement>
+Claude Code MUST NOT skip or defer verification of CORS configuration. All verification commands MUST be executed before accepting changes to CORS middleware. Code review MUST validate CORS configuration against security requirements. Security team MUST review any changes to CORS allowlist or middleware configuration.
+</enforcement>

.actual/rules/cross-cutting-applications-disable-ssl-2364.md

@@ -0,0 +1,42 @@
+# Configure PostgreSQL Connection Pooling with SSL for Primary Datastore: Applications Disable Ssl
+
+These rules are ALWAYS ACTIVE for all Node.js/TypeScript applications using PostgreSQL as the primary datastore through the 'pg' library with connection pooling.
+
+### Rules
+
+- **R-PGSSL-001** MAY: Applications MAY disable SSL certificate validation (rejectUnauthorized: false) only when connecting to managed database services that use self-signed certificates.
+- **R-PGSSL-002** MUST: All PostgreSQL Pool instantiations include an ssl configuration object with explicit rejectUnauthorized setting.
+- **R-PGSSL-003** MUST: All database queries with dynamic values use parameterized queries (text and values properties) with no string concatenation.
+- **R-PGSSL-004** MUST: DATABASE_URL is sourced from process.env and not hardcoded in any source files.
+- **R-PGSSL-005** MUST: Initialize the Pool instance once at application startup and reuse it across all request handlers to avoid creating multiple pools.
+- **R-PGSSL-006** MUST: Implement graceful shutdown by calling pool.end() to drain connections before process termination.
+- **R-PGSSL-007** SHOULD: Configure pool size using environment variables (e.g., PGMAXCONNECTIONS) to tune for specific deployment environments and database limits.
+- **R-PGSSL-008** SHOULD: For managed database services requiring rejectUnauthorized: false, add inline comments explaining the hosting provider's certificate configuration.
+
+### Verify
+
+```bash
+# Verify all PostgreSQL Pool instantiations include ssl configuration
+grep -r 'new Pool' --include='*.ts' --include='*.js' | grep -E 'ssl.*rejectUnauthorized'
+
+# Count parameterized queries using text/values pattern
+grep -r 'pool\.query.*\$[0-9]' --include='*.ts' --include='*.js' | wc -l
+
+# Verify DATABASE_URL is sourced from process.env
+grep -r 'process\.env\.DATABASE_URL' --include='*.ts' --include='*.js'
+
+# Verify no hardcoded connection strings
+grep -r 'postgresql://' --include='*.ts' --include='*.js' | grep -v 'process.env'
+```
+
+**Accept when:**
+- All PostgreSQL Pool instantiations include ssl configuration object with explicit rejectUnauthorized setting
+- All database queries with dynamic values use parameterized queries (text and values properties) with no string concatenation
+- DATABASE_URL is sourced from process.env and not hardcoded in any source files
+- Pool is initialized once at application startup and reused across all request handlers
+- Graceful shutdown calls pool.end() before process termination
+- For managed database services requiring rejectUnauthorized: false, inline comments document the hosting provider's certificate configuration
+
+<enforcement>
+Claude Code MUST NOT skip or defer verification. All rules in this file are mandatory for PostgreSQL connection implementations unless an approved exception (EXC-001 or EXC-002) is documented in code comments.
+</enforcement>

.actual/rules/cross-cutting-applications-expose-runtime-7f14.md

@@ -0,0 +1,40 @@
+# Use PostgreSQL Connection Pooling with SSL for Primary Datastore Access: Applications Expose Runtime
+
+These rules are ALWAYS ACTIVE for all Node.js/TypeScript server applications using PostgreSQL as the primary datastore, particularly those handling concurrent HTTP requests with visitor tracking and stateful data persistence operations.
+
+### Rules
+
+- **R-POOL-001** MUST: Initialize PostgreSQL Pool instances at module level before defining route handlers to ensure single pool reuse across all database operations.
+- **R-POOL-002** MUST: Source database connection credentials from runtime environment variables (process.env.DATABASE_URL) rather than hardcoded configuration files.
+- **R-POOL-003** MUST: Configure SSL for all PostgreSQL connections with explicit rejectUnauthorized setting in Pool initialization.
+- **R-POOL-004** MUST: Use parameterized queries with separate text and values properties for all database operations to prevent SQL injection vulnerabilities.
+- **R-POOL-005** MUST: Configure explicit pool size limits using max and min parameters based on expected concurrent request volume and database connection limits.
+- **R-POOL-006** SHOULD: Implement graceful shutdown handling to close the pool on application termination using pool.end() in process signal handlers.
+- **R-POOL-007** SHOULD: Add startup validation to verify DATABASE_URL is set and test database connectivity before binding to PORT to fail fast on misconfiguration.
+- **R-POOL-008** MAY: Applications MAY expose runtime configuration through environment variables including PORT for service binding.
+
+### Verify
+
+```bash
+# Verify Pool instances use connectionString from process.env.DATABASE_URL
+grep -r 'new Pool' server/src --include='*.ts' | grep -q 'connectionString.*process.env.DATABASE_URL'
+
+# Verify all database queries use parameterized statements
+grep -r 'pool.query' server/src --include='*.ts' | grep -q 'text:.*values:'
+
+# Verify SSL configuration is present in Pool initialization
+grep -r 'new Pool' server/src --include='*.ts' | grep -q 'ssl.*rejectUnauthorized'
+```
+
+**Accept when:**
+- All PostgreSQL connections use Pool instances with connectionString sourced from process.env.DATABASE_URL
+- All database queries use parameterized statements with separate text and values properties
+- SSL configuration is present in Pool initialization with rejectUnauthorized explicitly set
+- Pool is initialized at module level before route handler definitions
+- Explicit pool size limits (max and min parameters) are configured
+- Startup validation checks for required environment variables before attempting database connection
+- Graceful shutdown handling is implemented for pool.end() on process termination
+
+<enforcement>
+Claude Code MUST NOT skip or defer verification of these rules. All R-POOL-001 through R-POOL-008 requirements MUST be validated before accepting code changes affecting PostgreSQL connection management.
+</enforcement>

.actual/rules/cross-cutting-applications-provide-default-7b0b.md

@@ -0,0 +1,38 @@
+# Use Environment Variables for Runtime Database Configuration: Applications Provide Default
+
+These rules are ALWAYS ACTIVE for all TypeScript and JavaScript source files in the application that handle database connectivity and server configuration.
+
+### Rules
+
+- **R-ENV-001** MUST: Source all database connection strings from `process.env.DATABASE_URL` with no hardcoded credentials in source files.
+- **R-ENV-002** MUST: Source server port configuration from `process.env.PORT`.
+- **R-ENV-003** MAY: Applications MAY provide default values for PORT when the environment variable is not set.
+- **R-ENV-004** MUST: Implement startup validation that checks for required environment variables and provides clear error messages indicating which variables are missing.
+- **R-ENV-005** MUST: Implement logging filters to redact environment variable values and avoid echoing configuration in error responses.
+- **R-ENV-006** SHOULD: Use a .env file with dotenv library for local development to avoid manually setting environment variables in each shell session.
+- **R-ENV-007** SHOULD: Document all required environment variables in README.md with example values using placeholder credentials, not real ones.
+- **R-ENV-008** SHOULD: Consider using a configuration validation library like joi or zod to validate environment variables at startup with clear error messages.
+
+### Verify
+
+```bash
+# Check for DATABASE_URL sourced from environment
+grep -r 'process\.env\.DATABASE_URL' server/src/ | grep -v 'node_modules'
+
+# Check for PORT sourced from environment
+grep -r 'process\.env\.PORT' server/src/ | grep -v 'node_modules'
+
+# Verify no hardcoded PostgreSQL connection strings with credentials
+grep -rE '(postgresql://|postgres://).*@.*:.*/' server/src/ --include='*.ts' --include='*.js' | grep -v process.env || echo 'No hardcoded connection strings found'
+```
+
+**Accept when:**
+- All database connection strings are sourced from `process.env.DATABASE_URL` with no hardcoded credentials in source files
+- Server port configuration is sourced from `process.env.PORT`
+- No grep matches for hardcoded PostgreSQL connection strings containing credentials in TypeScript or JavaScript source files
+- Startup validation is implemented for required environment variables
+- Logging filters are in place to redact sensitive configuration values
+
+<enforcement>
+Claude Code MUST NOT skip or defer verification. All database and port configuration MUST be externalized to environment variables. Pull requests containing hardcoded credentials are automatically flagged and blocked from merging.
+</enforcement>

.actual/rules/cross-cutting-applications-provide-default-fc7e.md

@@ -0,0 +1,40 @@
+# Source Runtime Configuration from Environment Variables for Database and Service Binding: Applications Provide Default
+
+These rules are ALWAYS ACTIVE for all application code that requires runtime configuration for database connections, service bindings, and environment-specific parameters.
+
+### Rules
+
+- **R-ENV-001** MAY: Applications MAY provide default values for non-sensitive configuration when environment variables are absent.
+- **R-ENV-002** MUST: All database connection strings and credentials MUST be sourced from environment variables, never hardcoded in source code.
+- **R-ENV-003** MUST: All service port bindings and host addresses MUST be sourced from environment variables at application initialization.
+- **R-ENV-004** MUST: Application startup code MUST validate the presence and format of required environment variables before initializing database pools or HTTP servers.
+- **R-ENV-005** SHOULD: Applications SHOULD use a configuration validation library to enforce required variables and type constraints at startup.
+- **R-ENV-006** SHOULD: All required environment variables SHOULD be documented in README or deployment documentation with .env.example templates provided.
+
+### Verify
+
+```bash
+# Verify environment variable usage for database and port configuration
+grep -r 'process\.env\.' server/src/ | grep -E '(DATABASE_URL|PORT)'
+
+# Confirm database connection uses environment variables
+grep -r 'connectionString.*process\.env' server/src/
+
+# Ensure no hardcoded connection strings in source files
+! grep -r 'postgresql://.*:.*@' server/src/ --include='*.ts' --include='*.js'
+
+# Verify no hardcoded credentials patterns
+git-secrets --scan
+truffleHog filesystem . --json
+```
+
+**Accept when:**
+- All database connection strings and service ports are sourced from process.env variables in application initialization code
+- No hardcoded credentials or connection strings appear in TypeScript or JavaScript source files
+- Application startup code validates presence of required environment variables before initializing database pools or HTTP servers
+- Static analysis tools (git-secrets, truffleHog) detect no credential patterns in source code
+- Configuration management follows twelve-factor application principles
+
+<enforcement>
+Claude Code MUST NOT skip or defer verification. All database and service binding configuration MUST be externalized to environment variables. Hardcoded credentials or connection strings are a critical security violation and MUST trigger CI pipeline failure and security team notification.
+</enforcement>

.actual/rules/cross-cutting-applications-use-express-6034.md

@@ -0,0 +1,34 @@
+# Adopt Express Middleware Stack with CORS and JSON Parsing for HTTP Request Processing: Applications Use Express
+
+These rules are ALWAYS ACTIVE for all Node.js/Express application files that configure HTTP request processing middleware, particularly `server/src/index.ts` and equivalent entry points.
+
+### Rules
+
+- **R-EX-001** MUST: Applications MUST use express.json() middleware via app.use(express.json()) to parse JSON request bodies before route handlers execute.
+- **R-EX-002** MUST: CORS middleware MUST be configured using app.use(cors()) before any route definitions (app.get, app.post, etc.) to ensure preprocessing occurs for all requests.
+- **R-EX-003** MUST: All middleware registrations MUST appear before the first route handler definition in the source file.
+- **R-EX-004** SHOULD: CORS configuration SHOULD use the 'origin' option rather than 'allowedHeaders' to properly restrict cross-origin access: cors({ origin: ['https://suraj-gov.github.io/sorter', 'http://localhost:3000'] }).
+- **R-EX-005** SHOULD: Document the middleware execution order and the purpose of each middleware component for future maintainers.
+
+### Verify
+
+```bash
+# Verify CORS middleware is configured
+grep -n 'app\.use(cors(' server/src/index.ts
+
+# Verify JSON parsing middleware is configured
+grep -n 'app\.use(express\.json())' server/src/index.ts
+
+# Verify middleware appears before route definitions
+grep -B5 'app\.get\|app\.post' server/src/index.ts | grep -c 'app\.use'
+```
+
+**Accept when:**
+- CORS middleware is configured using app.use(cors()) before route definitions
+- JSON parsing middleware is configured using app.use(express.json()) before route definitions
+- All middleware registrations appear before the first route handler definition in the source file
+- CORS configuration uses the 'origin' option to restrict allowed origins
+
+<enforcement>
+Claude Code MUST NOT skip or defer verification. All R-EX rules must be validated before approving Express application middleware configuration.
+</enforcement>