@ryuenn3123/agentic-senior-core 3.0.17 → 3.0.20

package/.agent-context/rules/performance.md

@@ -1,178 +1,12 @@
-# Performance — Measure Before You Optimize
+# Performance Boundary
 
-> Premature optimization is the root of all evil.
-> But ignoring obvious performance traps is just incompetence.
+Do not over-optimize by habit. Do reject obvious scale and runtime failures.
 
-## The Performance Prime Directive
+Hard rejections:
+- repeated network, database, filesystem, or model calls inside loops without batching, limits, or caching rationale
+- unbounded reads, renders, exports, or searches when the data can grow
+- shipping large client/runtime payloads without a reason, split point, or loading strategy
+- synchronous blocking work in request, UI, worker, or async paths where it can stall the product
+- caches without invalidation, expiry, ownership, and staleness trade-offs
 
-**Do NOT optimize without evidence.** CPU time is cheap. Developer time is expensive.
-
-## Context-Triggered Strict Audit Mode
-
-Strict performance audits must activate automatically for:
-- review requests
-- PR-intent workflows (pull request preparation and merge readiness)
-- major feature completion
-
-Small edits stay in lightweight mode by default to avoid unnecessary heavy checks.
-Users can always force strict performance mode manually.
-
-BUT — there are patterns so obviously bad that they don't need benchmarks to reject.
-Those are listed below as **Death Penalties**.
-
----
-
-## Death Penalties (Always Reject)
-
-### 1. N+1 Queries
-```
-❌ INSTANT REJECTION:
-const users = await db.query('SELECT * FROM users');
-for (const user of users) {
-  user.orders = await db.query('SELECT * FROM orders WHERE user_id = ?', [user.id]);
-  // This runs 1 + N queries. For 1000 users = 1001 database round trips.
-}
-
-✅ REQUIRED:
-const users = await db.query('SELECT * FROM users');
-const userIds = users.map(u => u.id);
-const orders = await db.query('SELECT * FROM orders WHERE user_id = ANY($1)', [userIds]);
-// 2 queries total, regardless of user count
-// Or use ORM eager loading / DataLoader pattern
-```
-
-**Rule:** If you see a query inside a loop, it is almost certainly an N+1 bug. Fix it with JOINs, batch queries, or DataLoader.
-
-### 2. Unbounded Queries
-```
-❌ INSTANT REJECTION:
-const allUsers = await db.query('SELECT * FROM users');
-// In production, "users" table has 2 million rows. Enjoy your OOM.
-
-✅ REQUIRED:
-const users = await db.query('SELECT * FROM users LIMIT $1 OFFSET $2', [pageSize, offset]);
-// Or use cursor-based pagination for large datasets
-```
-
-**Rule:** EVERY query that returns a list MUST have a LIMIT. APIs MUST support pagination. Default page size: 20-50.
-
-### 3. SELECT * in Production
-```
-❌ BANNED:
-SELECT * FROM users;  -- Fetches 30 columns when you need 3
-
-✅ REQUIRED:
-SELECT id, email, display_name FROM users;
-```
-
-**Rule:** Select only the columns you need. `SELECT *` wastes bandwidth, memory, and makes schema changes dangerous.
-
-### 4. Synchronous I/O in Async Context
-```
-❌ BANNED:
-// In an async Node.js server
-const data = fs.readFileSync('/path/to/file');
-const result = execSync('some-command');
-
-✅ REQUIRED:
-const data = await fs.promises.readFile('/path/to/file');
-const result = await exec('some-command');
-```
-
-**Rule:** In async environments (Node.js, Python asyncio), NEVER block the event loop with synchronous I/O.
-
----
-
-## Optimize Only With Evidence
-
-For everything else, follow this protocol:
-
-### Step 1: Measure
-```
-// Use profiling tools, not guesses
-console.time('operation');
-await heavyOperation();
-console.timeEnd('operation');
-
-// Use proper APM: Datadog, New Relic, OpenTelemetry
-```
-
-### Step 2: Identify the Bottleneck
-- Is it CPU? Memory? I/O? Network?
-- Don't optimize CPU when the bottleneck is a slow database query
-
-### Step 3: Optimize the Bottleneck (Not Everything Else)
-- Fix the slowest thing first
-- Re-measure after each change
-- Stop when performance meets requirements
-
----
-
-## Caching Rules
-
-### When to Cache
-- Data that is read frequently, written rarely
-- Expensive computations that produce the same result for same inputs
-- External API responses (respect their cache headers)
-
-### When NOT to Cache
-- Data that changes every request
-- Small, fast queries (cache overhead > query time)
-- When you can't define a clear invalidation strategy
-
-### The Caching Devil's Triangle
-You can have 2 of 3:
-1. **Fresh data** (always up-to-date)
-2. **Fast reads** (sub-millisecond)
-3. **Simple code** (no cache layer)
-
-Pick your 2 and document the trade-off.
-
-### Invalidation Strategy (MANDATORY)
-```
-❌ BANNED:
-cache.set('users', data);  // When does this expire? Who invalidates it? Nobody knows.
-
-✅ REQUIRED:
-cache.set('users:active', data, { ttl: 300 });  // 5 min TTL, explicit key
-// AND document: "Invalidated on user.created, user.deleted, user.deactivated events"
-```
-
-**Rule:** NEVER add a cache without documenting the invalidation strategy. "We'll figure it out later" means "we'll have stale data in production."
-
----
-
-## Connection Management
-
-1. **Use connection pools** — never open/close connections per request
-2. **Set pool limits** — max connections based on infrastructure, not infinity
-3. **Implement timeouts** — connection timeout, query timeout, request timeout
-4. **Handle pool exhaustion** — fail fast with clear error, don't queue forever
-
----
-
-## Frontend Performance (When Applicable)
-
-1. **Lazy load** routes and heavy components
-2. **Debounce** search inputs and scroll handlers (300ms minimum)
-3. **Virtualize** long lists (don't render 10,000 DOM nodes)
-4. **Optimize images** — WebP/AVIF, responsive sizes, lazy loading
-5. **Bundle analysis** — if your JS bundle exceeds 200KB gzipped, investigate
-
----
-
-## The Performance Decision Framework
-
-```
-Is it a known Death Penalty pattern (N+1, unbounded, SELECT *, sync I/O)?
-  → Yes → Fix it now, no measurement needed
-  → No ↓
-
-Is there a measurable performance problem?
-  → No → Don't optimize. Ship it.
-  → Yes ↓
-
-Have you identified the specific bottleneck?
-  → No → Profile first
-  → Yes → Optimize ONLY that bottleneck, re-measure, stop when sufficient
-```
+When performance matters, measure the real bottleneck, change the smallest useful thing, and verify the result.

package/.agent-context/rules/realtime.md

@@ -1,47 +1,14 @@
-# Real-time & WebSockets Architecture
+# Realtime Boundary
 
-> WebSockets are stateful tcp connections in a stateless HTTP world. Treat them with extreme caution.
+Use realtime only when the user experience needs live state, collaboration, streaming progress, notifications, or low-latency feedback. Do not add sockets by habit.
 
-## 1. Connection Management & Scaling
-WebSockets hold a persistent connection, consuming file descriptors and memory on the server.
-- **Rule:** NEVER scale WebSockets using a standard load balancer without sticky sessions (unless utilizing an external Pub/Sub service).
-- **Architecture:** Use a dedicated external Pub/Sub layer to broadcast messages across multiple WebSocket server instances.
-  - **Standard:** Redis Pub/Sub (Socket.io-redis, any standard Redis adapter).
-  - **Enterprise:** NATS, Apache Kafka, or managed services like AWS API Gateway WebSockets / Pusher / Socket.io / Soketi.
-- **Goal:** Any user can connect to Server A, and receive a message published by a background job running on Server B.
+Hard rules:
+- choose the transport from product needs and current official docs: polling, server-sent events, WebSockets, WebRTC, managed realtime, or queue-backed push
+- authenticate every connection or subscription at a trusted boundary
+- validate every inbound message and keep message contracts typed
+- keep business logic out of transport callbacks
+- define reconnect, heartbeat, backpressure, rate-limit, and abuse behavior
+- plan horizontal scaling before relying on in-memory connection state
+- document ordering, delivery guarantees, offline behavior, and failure recovery
 
-## 2. Authentication Context
-WebSockets cannot rely on traditional HTTP Authorization headers during the handshake in browser environments (as the WebSocket API does not allow setting custom headers).
-- **Rule:** Authenticate connections explicitly.
-  - **Method A (Cookies):** If the application uses HTTPOnly cookies, authentication happens naturally during the initial HTTP upgrade request.
-  - **Method B (Tickets/Tokens):** Pass the JWT or an ephemeral ticket in the connection URL query string (`?token=xyz`) or immediately after connecting via a dedicated `auth` JSON payload.
-- **BANNED:** Never trust a client simply because they know the WebSocket URL.
-
-## 3. The "No Business Logic in Sockets" Rule
-A WebSocket controller should be treated exactly like an HTTP controller.
-- **Rule:** The WebSocket handler's **only** responsibility is parsing the incoming message, validating the payload schema, and routing it to a Service/Application layer orchestrator.
-- **BANNED:** Directly writing to databases, executing complex business logic, or calling external APIs directly inside the WebSocket event callback.
-
-## 4. Heartbeats & Dead Connections
-TCP connections drop silently (e.g., when a user drives through a tunnel).
-- **Rule:** Implement Ping/Pong heartbeats. The server MUST periodically ping the client. If the client fails to respond within the expected window (e.g., 30s), the server MUST forcefully sever the connection to free resources (`ws.terminate()`, not `ws.close()`).
-
-## 5. Event Design & Typing
-Treat WebSocket events like a strongly typed REST API.
-- **Rule:** Every WebSocket message MUST have a mandatory `type` or `event` field, and a strongly typed `payload` field defined by a schema (e.g., Zod, JSON Schema).
-- **BANNED:** Emitting arbitrary strings or untyped JSON objects like `{ user_id: 1, message: "hi" }`.
-- **REQUIRED:**
-  ```json
-  {
-    "event": "message.created",
-    "payload": {
-      "id": "msg_123",
-      "text": "Hello World",
-      "timestamp": "2026-03-01T12:00:00Z"
-    }
-  }
-  ```
-
-## 6. Rate Limiting & Abuse Prevention
-WebSockets are heavily susceptible to DoS attacks because an open connection bypasses traditional WAF rate limiters.
-- **Rule:** You MUST implement message rate limiting at the application logic layer (e.g., maximum 5 messages per second per connection/user). Violators should be instantly disconnected and IP-banned temporarily.
+If realtime infrastructure is unresolved, the LLM must recommend the smallest current project-fit option instead of assuming WebSockets.

package/.agent-context/rules/security.md

@@ -1,298 +1,14 @@
-# Security — Trust Nothing, Validate Everything
+# Security Boundary
 
-> Every user is a potential attacker. Every input is a potential exploit.
-> You are not paranoid — you are professional.
+Use the security model and libraries already present in the project. If security tooling is unresolved, the LLM must recommend current, maintained options from official docs and OWASP-aligned guidance before implementation.
 
-## The Zero Trust Input Rule
-
-**ALL data crossing a system boundary is untrusted until validated.**
-
-## Context-Triggered Strict Audit Mode
-
-Strict security audits must activate automatically for:
-- review requests
-- PR-intent workflows (pull request preparation and merge readiness)
-- major feature completion
-
-Small edits stay in lightweight mode by default to avoid unnecessary heavy checks.
-Users can always force strict security mode manually.
-
-System boundaries include:
-- HTTP request bodies, query params, headers, cookies
-- URL path parameters
-- File uploads
-- WebSocket messages
-- Queue/event payloads
-- Environment variables (at startup)
-- Database query results (yes, even these — data could be corrupted)
-- Third-party API responses
-
-### Validation Protocol
-```
-External Input → Schema Validation (Zod/Pydantic/Bean Validation) → Typed Internal Object
-
-NEVER:
-External Input → Direct use in business logic
-External Input → Direct use in database query
-External Input → Direct interpolation into strings
-```
-
----
-
-## Injection Prevention
-
-### SQL Injection — Parameterized Queries Only
-```
-❌ DEATH PENALTY:
-const query = `SELECT * FROM users WHERE id = ${userId}`;
-const query = "SELECT * FROM users WHERE name = '" + name + "'";
-
-✅ ALWAYS:
-const user = await db.query('SELECT * FROM users WHERE id = $1', [userId]);
-const user = await prisma.user.findUnique({ where: { id: userId } });
-```
-
-**Rule:** NEVER concatenate or interpolate user input into SQL strings. Use parameterized queries or ORMs. No exceptions. Not even "just for testing."
-
-### Command Injection
-```
-❌ DEATH PENALTY:
-exec(`convert ${filename} output.png`);
-
-✅ ALWAYS:
-execFile('convert', [filename, 'output.png']);
-```
-
-**Rule:** Never pass user input to shell commands via string interpolation. Use argument arrays.
-
-### XSS Prevention
-```
-❌ BANNED:
-element.innerHTML = userInput;
-dangerouslySetInnerHTML={{ __html: userInput }};
-
-✅ REQUIRED:
-element.textContent = userInput;
-// Or sanitize with DOMPurify if HTML is absolutely needed
-```
-
-**Rule:** Default to text content. Only use HTML injection with explicit sanitization AND a code comment explaining WHY.
-
----
-
-## Secret Management
-
-### Rule: ZERO Secrets in Code
-
-```
-❌ INSTANT REJECTION:
-const API_KEY = "sk-abc123def456";
-const DB_PASSWORD = "supersecret";
-const JWT_SECRET = "my-jwt-secret";
-// Even in .env.example with real values
-
-✅ REQUIRED:
-const API_KEY = process.env.API_KEY;      // Read from environment
-const DB_URL = process.env.DATABASE_URL;   // Injected at runtime
-```
-
-### .env Files
-- `.env` → NEVER committed (must be in `.gitignore`)
-- `.env.example` → Committed with placeholder values ONLY (`API_KEY=your-api-key-here`)
-- `.env.local` → NEVER committed
-- `.env.test` → May be committed with TEST-ONLY non-secret values
-
-### Secret Rotation
-If a secret is accidentally committed:
-1. Rotate the secret IMMEDIATELY (not after the PR is merged — NOW)
-2. Remove from git history (`git filter-branch` or BFG)
-3. Add to `.gitignore`
-4. Document the incident
-
----
-
-## Authentication & Authorization
-
-### Authentication Rules
-1. Never implement custom auth crypto — use established libraries (argon2, bcrypt, Passport, NextAuth)
-2. Hash passwords with **argon2id** (OWASP primary recommendation) — bcrypt only for legacy systems
-   - Argon2id: minimum 19 MiB memory, 2 iterations, 1 parallelism
-   - bcrypt: minimum cost 12 (legacy systems only — limited to 72 bytes, no memory-hardness)
-   - NEVER: MD5, SHA1, plain SHA256, or PBKDF2 without FIPS requirement
-3. Use constant-time comparison for tokens and hashes
-4. Implement rate limiting on auth endpoints (max 5 attempts per minute per IP)
-5. Session tokens must be cryptographically random (≥ 256 bits)
-
-### Authorization Rules
-1. **Default deny** — if no rule grants access, deny
-2. **Server-side only** — NEVER trust client-side role checks for security
-3. Check authorization at the service layer, not just the controller
-4. Log all authorization failures with context (userId, resource, action)
-
-```
-❌ BANNED: Client-side only authorization
-if (user.role === 'admin') { showDeleteButton(); }
-// Attacker just changes user.role in devtools
-
-✅ REQUIRED: Server-side enforcement
-// Controller checks auth, service enforces business rules
-async deleteUser(requesterId: string, targetUserId: string) {
-  const requester = await this.userRepo.findById(requesterId);
-  if (!requester || requester.role !== Role.ADMIN) {
-    throw new ForbiddenError('Insufficient permissions');
-  }
-  // ... proceed with deletion
-}
-```
-
----
-
-## HTTP Security Headers
-
-Every web application MUST include:
-```
-Strict-Transport-Security: max-age=31536000; includeSubDomains
-Content-Security-Policy: default-src 'self'; script-src 'self'
-X-Content-Type-Options: nosniff
-X-Frame-Options: DENY
-Referrer-Policy: strict-origin-when-cross-origin
-Permissions-Policy: camera=(), microphone=(), geolocation=()
-```
-
-### CORS
-- NEVER use `Access-Control-Allow-Origin: *` in production
-- Whitelist specific origins
-- Be explicit about allowed methods and headers
-
----
-
-## File Upload Security
-
-1. Validate MIME type server-side (not just file extension)
-2. Set maximum file size limits
-3. Generate random filenames — never use user-provided filenames
-4. Store uploads outside the web root
-5. Scan for malware if accepting documents
-
----
-
-## Supply Chain Security (OWASP 2025 A03)
-
-1. **Pin all dependency versions** — use lockfiles, never `*` ranges in production
-2. **Audit dependencies regularly** — `npm audit`, `pip audit`, `composer audit`
-3. **Verify package integrity** — check checksums, use signed packages where available
-4. **Minimize dependency trees** — fewer transitive dependencies = smaller attack surface
-5. **Monitor for CVEs** — automate vulnerability scanning in CI (Dependabot, Snyk, Trivy)
-6. **Review new dependencies** — check maintainer history, download trends, and bus factor before adding
-
----
-
-## .gitignore Enforcement (Mandatory)
-
-**If the user's INTENT is to create a new project, push to GitHub, or initialize source control, you MUST generate or verify a `.gitignore` file exists.**
-
-### Minimum Required Entries
-```gitignore
-# ── Secrets & Environment ──
-.env
-.env.local
-.env.*.local
-.env.production
-.env.staging
-
-# ── Dependencies ──
-node_modules/
-vendor/
-venv/
-.venv/
-__pycache__/
-.gradle/
-target/
-bin/  # Go binaries
-pkg/
-
-# ── Build Output ──
-dist/
-build/
-out/
-*.min.js
-*.min.css
-.next/
-.nuxt/
-.output/
-
-# ── IDE & Editor ──
-.idea/
-.vscode/settings.json
-.vscode/launch.json
-*.swp
-*.swo
-*~
-
-# ── OS Artifacts ──
-.DS_Store
-Thumbs.db
-Desktop.ini
-*.lnk
-
-# ── Logs ──
-*.log
-npm-debug.log*
-yarn-debug.log*
-pnpm-debug.log*
-
-# ── Testing & Coverage ──
-coverage/
-.nyc_output/
-*.lcov
-
-# ── Runtime & Backup Data ──
-*.pid
-*.seed
-*.pid.lock
-.agentic-backup/
-
-# ── Secrets & Keys ──
-*.pem
-*.key
-*.p12
-*.jks
-*.keystore
-```
-
-### Rules
-1. **NEVER commit `.env`** — only `.env.example` with placeholder values
-2. **Check for leaks before push** — `git diff --cached --name-only | grep -E '\.(env|pem|key)$'` should return empty
-3. **If the project has NO `.gitignore`**, create one immediately before any `git add`
-4. **Extend per-stack** — add language-specific patterns (e.g., `__pycache__/` for Python, `target/` for Java/Rust, `.gradle/` for Kotlin)
-5. **Reference**: See `.agent-context/rules/git-workflow.md` for the full `.gitignore Standards` section
-
-### MUST Commit (Whitelist)
-```
-.env.example           # Template with placeholder values ONLY
-.editorconfig          # Consistent formatting across IDEs
-.gitignore             # This file itself
-docker-compose.yml     # Dev environment definition
-Makefile / Taskfile    # Standard dev commands
-```
-
----
-
-## The Security Checklist (Quick Reference)
-
-Before any code is "done", verify:
-
-- [ ] All inputs validated at boundaries with schemas
-- [ ] No string concatenation in queries/commands
-- [ ] No secrets in source code
-- [ ] `.gitignore` exists and covers `.env`, `node_modules/`, build output, and IDE files
-- [ ] Authentication uses established libraries
-- [ ] Password hashing uses argon2id (or bcrypt for legacy)
-- [ ] Authorization enforced server-side
-- [ ] Security headers configured
-- [ ] CORS properly restricted
-- [ ] Rate limiting on sensitive endpoints
-- [ ] Error responses don't leak internal details
-- [ ] Logging includes security events (login failures, permission denials)
-- [ ] Dependencies audited for known vulnerabilities
+Hard rules:
+- validate and normalize all data crossing a trust boundary
+- never interpolate untrusted input into queries, shell commands, file paths, templates, logs, or HTML
+- never commit secrets, tokens, credentials, private keys, or production identifiers
+- never invent custom crypto, session, token, or password handling when maintained standards exist
+- enforce authorization at the server or trusted boundary, not only in UI state
+- return safe client-facing errors and keep sensitive detail in protected logs
+- document auth, permission, data exposure, rate-limit, and abuse assumptions before changing sensitive flows
 
+For high-risk changes, check current framework security docs and record the relevant source or assumption in the implementation notes.