@ryuenn3123/agentic-senior-core 1.9.1 → 1.9.3

package/.windsurfrules

@@ -1,106 +1,3718 @@
-# Windsurf Agent Rules — Agentic-Senior-Core
-# This file mirrors .cursorrules for Windsurf compatibility.
-# The authoritative knowledge base is in .agent-context/
-
-## Identity
-You are a Senior Software Architect with 10+ years of production experience.
-You enforce professional engineering standards. No shortcuts. No "good enough" code.
-
-## Knowledge Base Protocol
-
-Before generating or modifying any code, load the relevant rules:
-
-## Auto-Architect Trigger (MANDATORY FOR NEW PROJECTS)
-If the user's INTENT is to create a new project, system, module, or app (regardless of the specific words used), **IMMEDIATELY** enter Architect Mode:
-1. Scan `.agent-context/rules/` and `.agent-context/blueprints/` without being asked.
-2. Propose the most efficient technology stack and architecture layer separation (Transport -> Service -> Repository).
-3. Draft a high-level plan and wait for the user's approval before generating any code.
-
-## Refactor & Legacy Code Trigger
-If the user's INTENT is to refactor, fix, update, or migrate existing code (regardless of the exact words used):
-1. Read `.agent-context/rules/architecture.md` and `.agent-context/rules/naming-conv.md`.
-2. Propose a refactor plan adhering to our standards before changing code.
-
-### Step 1: Universal Rules (Always Load)
-Read ALL files in `.agent-context/rules/`:
-- `naming-conv.md` — Descriptive naming, no single-letter variables
-- `architecture.md` — Separation of Concerns, feature-based grouping
-- `security.md` — Validate all input, parameterize queries, never hardcode secrets
-- `performance.md` — Evidence-based optimization, N+1 death penalty
-- `error-handling.md` — Never swallow errors, typed error codes, structured logging
-- `testing.md` — Test pyramid, behavior over implementation
-- `git-workflow.md` — Conventional Commits, atomic changes
-- `efficiency-vs-hype.md` — Stable dependencies over trendy ones
-- `api-docs.md` — OpenAPI 3.1 mandatory, zero-doc death penalty
-- `microservices.md` — Monolith first, split triggers, strangler fig
-- `event-driven.md` — Event sourcing, CQRS, idempotency
-- `database-design.md` — 3NF default, index FKs, safe migrations
-- `realtime.md` — WebSockets scaling & strict pub/sub
-- `frontend-architecture.md` — Smart/Dumb UI, TanStack Query vs Zustand
-
-### Step 2: Language Profile (By Stack)
-Load the relevant stack from `.agent-context/stacks/`:
-- TypeScript/Node → `stacks/typescript.md`
-- Python → `stacks/python.md`
-- Java/Kotlin → `stacks/java.md`
-- PHP → `stacks/php.md`
-- Go → `stacks/go.md`
-- C#/.NET → `stacks/csharp.md`
-- Rust → `stacks/rust.md`
-- Ruby on Rails → `stacks/ruby.md`
-
-### Step 3: Blueprint (If Scaffolding)
-Load from `.agent-context/blueprints/` when creating new projects.
-
-### Step 4: Review (Before Completion)
-Run `.agent-context/review-checklists/pr-checklist.md` before declaring done.
-
-### Step 5: State Awareness + Override (V1.4)
-- Read `.agent-context/state/architecture-map.md` and `.agent-context/state/dependency-map.md` before large edits.
-- Follow `.agent-override.md` only for explicitly scoped exceptions.
-
-## The Reasoning Clause (MANDATORY)
-Every time you reject a code block, suggest a change, or enforce a rule, you MUST provide a Reasoning Chain:
-
-```
-REASONING CHAIN
-Problem: [WHY the user's current approach/request is dangerous or unprofessional]
-Solution: [The improved, production-grade approach]
-Why Better: [WHY this is more professional — teach the human]
-```
-
-## Zero Tolerance & Rejection Protocol
-If the user asks for "quick and dirty" code, skipping tests, or ignoring validation, you MUST politely but firmly refuse. Explain that today's hack is tomorrow's production incident. You do NOT tolerate shortcuts.
-
-### The Security Halt
-If you detect critical security vulnerabilities (e.g., hardcoded secrets, SQL injection, bypassing auth), you MUST halt feature development and refuse to proceed until the vulnerability is patched.
-
-### The "Plan First" Rule
-For any non-trivial request, do NOT generate full code immediately. You MUST first provide a bulleted "Implementation Plan" outlining the file structure, design patterns to be used, and security considerations. End your response with: *"Do you approve this plan? If yes, I will generate the code."*
-
-### Self-Correction Protocol
-Before outputting your final code, silently run a self-review against our Clean Code and Security standards. If your generated code contains `any` types, swallowed errors, or unvalidated inputs, CORRECT IT before showing it to the user. Never output code you wouldn't approve in a PR.
-
-### Dependency Defense
-If the user asks to install a new library, or if you feel the need to use one, evaluate it against the "stdlib-first" rule. If the functionality can be implemented safely in under 20 lines of code, write it yourself. If a dependency is strictly necessary, you MUST justify it by providing its bundle size, maintenance status, and why the standard library is insufficient.
-
-## Absolute Clean Code Laws
-1. **No Lazy Naming:** NEVER use generic variables like `data`, `res`, `temp`, `val`, `x`. Variables must be nouns answering "WHAT is this?". Functions must start with a verb (e.g., `validatePayment`). Booleans must use `is`/`has`/`can`/`should` prefixes.
-2. **No 'any' or 'magic':** If using TypeScript/Python, the `any` type is completely banned. All external data MUST be validated at the boundary using schemas (like Zod or Pydantic) before touching business logic.
-3. **Layer Separation:** Business logic does NOT touch HTTP. Database logic does NOT leak into services. No exceptions.
-4. **Context First:** NEVER write code without checking `.agent-context/rules/` first.
-5. **No Blind Dependencies:** NEVER introduce dependencies without justification.
-
-## Response Format
-1. Plan (3-6 bullets)
-2. Implementation (following ALL rules)
-3. Verification (how to test + edge cases)
-
-## Definition of Done
-**NEVER** declare a task "done" or ready for review without explicitly running and passing `.agent-context/review-checklists/pr-checklist.md`.
-
-## Full Reference
-For detailed instructions, read `.cursorrules` and `AGENTS.md` in the repository root.
+# AGENTIC-SENIOR-CORE DYNAMIC GOVERNANCE RULESET
 
-# Generated by Agentic-Senior-Core CLI v1.9.1
+Generated by Agentic-Senior-Core CLI v1.9.3
+Timestamp: 2026-04-08T02:11:52.432Z
+Selected profile: beginner
+Selected policy file: .agent-context/policies/llm-judge-threshold.json
 
+## GOVERNANCE PRECEDENCE
+1. Follow this compiled rulebook as the primary source.
+2. Resolve exceptions from .agent-override.md only when explicitly defined.
+3. Use architecture-map.md and dependency-map.md as change safety boundaries.
+4. Enforce pr-checklist.md before declaring completion.
+
+## OVERRIDE PROTOCOL
+- Default: strict compliance with this file.
+- Exception path: .agent-override.md may explicitly allow narrow deviations.
+- Scope policy: every override must include module scope, rationale, and expiry date.
+
+## UNIVERSAL RULE: api-docs.md
+Source: .agent-context/rules/api-docs.md
+
+# API Documentation — The "Invisible API" Rule
+
+> An undocumented API is an unusable API.
+> If it's not in the spec, it doesn't exist.
+
+## The Zero-Doc Death Penalty
+
+Every API endpoint MUST have machine-readable documentation that covers:
+1. HTTP method + path
+2. Request body schema with field descriptions and examples
+3. All response codes with typed schemas
+4. Authentication requirements
+5. Rate limiting (if applicable)
+
+```
+BANNED: An endpoint without a defined Request/Response schema.
+BANNED: Using generic `object` or `any` in documentation types.
+BANNED: "See code for details" as documentation.
+BANNED: Swagger UI with auto-generated summaries only (no descriptions, no examples).
+
+REQUIRED: Every field MUST have a `description` and an `example` value.
+REQUIRED: Every error response MUST be documented (400, 401, 403, 404, 409, 500).
+REQUIRED: Documentation MUST be updated in the SAME commit as the endpoint change.
+```
+
+---
+
+## Documentation Format: OpenAPI 3.1 (Non-Negotiable)
+
+All APIs produce an OpenAPI 3.1 specification. Not 3.0, not proprietary formats, not "we'll add Swagger later."
+
+### Why OpenAPI
+- Machine-readable: clients, tests, and mocks can be generated from the spec
+- Full JSON Schema Draft 2020-12 compatibility (3.1+ only)
+- Vendor-neutral: works with Scalar, Swagger UI, Redoc, Postman, Stoplight
+- Version-controllable: the spec is a file you can diff and review
+
+---
+
+## Tooling by Framework
+
+### NestJS
+Use `@nestjs/swagger` with Scalar UI (not default Swagger UI — Scalar is faster and more readable).
+
+```typescript
+// main.ts — Setup
+import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
+import { apiReference } from '@scalar/nestjs-api-reference';
+
+const config = new DocumentBuilder()
+  .setTitle('Service Name')
+  .setDescription('Brief service purpose')
+  .setVersion('1.0')
+  .addBearerAuth()
+  .build();
+
+const document = SwaggerModule.createDocument(app, config);
+
+// Scalar UI at /docs
+app.use('/docs', apiReference({ spec: { content: document } }));
+
+// Raw spec at /api-json
+SwaggerModule.setup('api', app, document);
+```
+
+Every controller method requires these decorators at minimum:
+```typescript
+@ApiOperation({ summary: 'Create a user account' })
+@ApiBody({ type: CreateUserDto, description: 'User registration data' })
+@ApiResponse({ status: 201, type: UserResponseDto, description: 'User created successfully' })
+@ApiResponse({ status: 400, description: 'Validation error — invalid input fields' })
+@ApiResponse({ status: 409, description: 'Conflict — email already registered' })
+@Post()
+```
+
+Every DTO property requires `@ApiProperty`:
+```typescript
+export class CreateUserDto {
+  @ApiProperty({
+    description: 'User email address, must be unique across the system',
+    example: 'jane.doe@example.com',
+  })
+  email: string;
+
+  @ApiProperty({
+    description: 'Display name shown in the UI',
+    example: 'Jane Doe',
+    minLength: 1,
+    maxLength: 100,
+  })
+  name: string;
+}
+```
+
+### Next.js (App Router)
+Use `zod-to-openapi` or `next-swagger-doc` to generate OpenAPI from Zod schemas.
+
+```typescript
+import { extendZodWithOpenApi } from '@asteasolutions/zod-to-openapi';
+import { z } from 'zod';
+
+extendZodWithOpenApi(z);
+
+export const CreateUserSchema = z.object({
+  email: z.string().email().openapi({
+    description: 'User email address, must be unique',
+    example: 'jane.doe@example.com',
+  }),
+  name: z.string().min(1).max(100).openapi({
+    description: 'Display name shown in the UI',
+    example: 'Jane Doe',
+  }),
+}).openapi('CreateUserRequest');
+```
+
+Expose the spec at `/api/docs` or `/api/openapi.json`.
+
+### Other Frameworks (Express, Fastify, Hono)
+Use `swagger-jsdoc` + TSDoc comments, or `@asteasolutions/zod-to-openapi`.
+The output MUST be a valid OpenAPI 3.1 JSON/YAML file served at a known endpoint.
+
+---
+
+## Response Documentation Standard
+
+Every endpoint MUST document these response scenarios:
+
+| Status | When | Schema Required |
+|--------|------|----------------|
+| `200` | Successful retrieval or update | Yes — typed response body |
+| `201` | Successful creation | Yes — the created resource |
+| `204` | Successful deletion | No body |
+| `400` | Validation error | Yes — field-level error details |
+| `401` | Missing or invalid authentication | Fixed message, no details |
+| `403` | Authenticated but insufficient permissions | Fixed message |
+| `404` | Resource not found | Fixed message |
+| `409` | Conflict (duplicate resource) | Description of conflict |
+| `429` | Rate limit exceeded | Retry-After header |
+| `500` | Internal error | `{ traceId }` only — NO stack traces |
+
+### Error Response Schema (Standardized)
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "One or more fields are invalid",
+    "details": [
+      { "field": "email", "message": "Invalid email format" }
+    ],
+    "traceId": "req-abc-123"
+  }
+}
+```
+
+This schema MUST be documented in OpenAPI as a reusable component (`#/components/schemas/ErrorResponse`).
+
+---
+
+## Documentation Sync Rule
+
+```
+Endpoint changed + docs NOT updated = PR REJECTED.
+
+The spec is a contract. If the contract is wrong, consumers will break.
+"I'll update the docs later" means "the docs will never be updated."
+```
+
+### Enforcement
+1. API docs live next to the code (same module, same directory)
+2. Docs update in the SAME commit as the endpoint change
+3. CI can validate the spec: `openapi-generator validate -i openapi.json`
+4. Generated clients (if any) must be regenerated after spec changes
+
+---
+
+## The Documentation Quality Test
+
+Open your API docs URL (`/docs`). For a randomly chosen endpoint, verify:
+
+1. Can a developer who has never seen the codebase call this endpoint correctly? (Must be YES)
+2. Are all required fields clearly marked? (Must be YES)
+3. Does every field have a realistic example value? (Must be YES)
+4. Are all error responses documented with their conditions? (Must be YES)
+5. Can you copy the example request and it works? (Must be YES)
+
+If any answer is "no", the documentation is incomplete.
+## UNIVERSAL RULE: architecture.md
+Source: .agent-context/rules/architecture.md
+
+# Architecture — Separation of Concerns & Structure
+
+> If your service file imports an HTTP library, your architecture is broken.
+> If your controller contains SQL, you've already lost.
+
+## The Core Principle
+
+**Every layer has ONE job. Layer leaks are bugs — not "pragmatic shortcuts."**
+
+```
+┌─────────────────────────────────────────┐
+│         TRANSPORT / CONTROLLER          │  ← Parse input, validate shape, return response
+│         (HTTP, CLI, WebSocket, Queue)   │  ← NO business logic here. EVER.
+├─────────────────────────────────────────┤
+│         APPLICATION / SERVICE           │  ← Business rules, orchestration, transactions
+│         (Use cases, workflows)          │  ← NO HTTP, NO SQL, NO framework imports
+├─────────────────────────────────────────┤
+│         DOMAIN / ENTITY                 │  ← Pure business objects, value objects
+│         (Models, rules, calculations)   │  ← ZERO external dependencies
+├─────────────────────────────────────────┤
+│         INFRASTRUCTURE / REPOSITORY     │  ← Database, external APIs, file system
+│         (Data access, adapters)         │  ← NO business logic
+└─────────────────────────────────────────┘
+```
+
+## Layer Rules (Enforced)
+
+### Transport Layer (Controller / Handler / Route)
+**Allowed:**
+- Parse and validate incoming request (DTO/schema validation)
+- Call application/service layer
+- Format and return HTTP response (status code, headers)
+- Handle authentication/authorization middleware
+
+**BANNED:**
+- Database queries or ORM calls
+- Business logic (if/else on business rules)
+- Direct calls to external APIs
+- Transaction management
+
+### Application Layer (Service / Use Case)
+**Allowed:**
+- Orchestrate business operations
+- Call repository layer for data
+- Apply business rules and validations
+- Manage transactions
+- Emit domain events
+
+**BANNED:**
+- HTTP request/response objects
+- Framework-specific decorators (keep framework coupling minimal)
+- Direct SQL or raw database calls
+- UI/presentation logic
+
+### Domain Layer (Entity / Value Object)
+**Allowed:**
+- Business calculations and rules
+- Validation of domain invariants
+- Type definitions and interfaces
+
+**BANNED:**
+- ANY external dependency (database, HTTP, framework)
+- Side effects (logging, API calls, file I/O)
+- Infrastructure concerns
+
+### Infrastructure Layer (Repository / Adapter)
+**Allowed:**
+- Database queries (SQL, ORM, document queries)
+- External API calls (wrapped in adapters)
+- File system operations
+- Cache operations
+
+**BANNED:**
+- Business logic (no if/else on business rules in queries)
+- HTTP response formatting
+- Direct exposure to transport layer
+
+---
+
+## Dependency Direction
+
+Dependencies flow **inward only**:
+
+```
+Transport → Application → Domain ← Infrastructure
+                ↓
+          Infrastructure
+
+NEVER: Domain → Infrastructure (use interfaces/ports)
+NEVER: Application → Transport
+NEVER: Infrastructure → Application (except through interfaces)
+```
+
+The Domain layer depends on NOTHING. Everything depends on the Domain.
+
+---
+
+## Default Architecture: Modular Monolith
+
+Start with a **Modular Monolith**. Do NOT start with microservices.
+
+**Switch to microservices ONLY if 2+ of these triggers exist:**
+1. Frequent deploy conflicts across domains (teams blocking each other)
+2. Clear scale mismatch (one module needs 100x resources of another)
+3. Team ownership collision (multiple teams editing same module)
+4. Fault isolation requirement (one module crashing must not kill others)
+5. Stable contracts with clear data boundaries already exist
+
+If these triggers don't exist, microservices are **premature complexity**.
+
+---
+
+## Project Structure: Feature-Based Grouping
+
+### ❌ BANNED: Technical Grouping
+```
+src/
+  controllers/          ← 50 controllers in one flat folder?
+    userController.ts
+    orderController.ts
+    paymentController.ts
+  services/             ← Good luck finding related code
+    userService.ts
+    orderService.ts
+  repositories/
+    userRepository.ts
+    orderRepository.ts
+```
+
+### ✅ REQUIRED: Feature/Domain Grouping
+```
+src/
+  modules/                              ← Backend
+    user/
+      user.controller.ts               ← Transport
+      user.service.ts                   ← Application
+      user.repository.ts               ← Infrastructure
+      user.entity.ts                    ← Domain
+      user.dto.ts                       ← Data Transfer Objects
+      user.module.ts                    ← Module registration
+      __tests__/
+        user.service.test.ts
+    order/
+      order.controller.ts
+      order.service.ts
+      ...
+  shared/                               ← Cross-cutting concerns
+    config/
+    errors/
+    logging/
+    middleware/
+
+src/
+  features/                             ← Frontend
+    payment/
+      api/                              ← HTTP client + DTOs
+      hooks/                            ← React hooks / state
+      components/                       ← UI components
+      types/                            ← Type definitions
+      utils/                            ← Feature-specific utils
+      index.ts                          ← Public API barrel
+  components/
+    ui/                                 ← Shared UI primitives
+    layout/                             ← Layout components
+  lib/                                  ← Shared utilities
+  config/                               ← App configuration
+```
+
+---
+
+## Module Communication
+
+### Within a Monolith
+Modules communicate through **public interfaces only**:
+```
+// ✅ CORRECT: Import from module's public API
+import { UserService } from '@/modules/user';
+
+// ❌ BANNED: Reach into another module's internals
+import { UserRepository } from '@/modules/user/user.repository';
+```
+
+### Between Services (if microservices)
+- Use well-defined contracts (REST, gRPC, events)
+- Never share databases between services
+- Define schemas at boundaries (Protobuf, JSON Schema, Zod)
+
+---
+
+## The Architecture Smell Test
+
+Ask yourself these questions. If ANY answer is "yes", your architecture is broken:
+
+1. Can I change the database without touching business logic? (Must be YES)
+2. Can I switch from REST to GraphQL without rewriting services? (Must be YES)
+3. Can I test business logic without a running database? (Must be YES)
+4. Does each module have a clear, single responsibility? (Must be YES)
+5. Can a new developer find all related code in one directory? (Must be YES)
+## UNIVERSAL RULE: database-design.md
+Source: .agent-context/rules/database-design.md
+
+# Database Design — Schema Is Your Foundation
+
+> A poorly designed schema is a bug factory.
+> You can fix bad code in hours. A bad schema takes weeks.
+
+## Normalization Rules
+
+### Third Normal Form (3NF) is the Default
+
+```
+❌ BANNED: Flat tables with repeated data
+Users:
+  | id | name  | order_id | order_total | product_name |
+  | 1  | Jane  | 101      | 99.99       | Widget       |
+  | 1  | Jane  | 102      | 49.99       | Gadget       |
+  → name is duplicated, update anomalies guaranteed
+
+✅ REQUIRED: Normalized to 3NF
+Users:    | id | name  | email          |
+Orders:   | id | user_id | total | status |
+Products: | id | name   | price |
+OrderItems: | order_id | product_id | quantity |
+  → Each fact is stored exactly once
+```
+
+### When to Denormalize
+
+Denormalization is allowed ONLY with documented justification:
+
+1. **Read-heavy query** that joins 4+ tables and is called >1000x/sec
+2. **Reporting/analytics** where query speed matters more than write consistency
+3. **CQRS read model** that is purpose-built for a specific query
+
+```
+REQUIRED for every denormalization:
+- Document WHY (link to performance evidence)
+- Document HOW it stays in sync (trigger, event, scheduled job)
+- Add a comment in the schema: "Denormalized for [query name], synced by [mechanism]"
+```
+
+---
+
+## Indexing Strategy
+
+### Rules of Indexing
+
+1. **Every foreign key gets an index** — joins on unindexed FKs are full table scans
+2. **Every WHERE clause in a frequent query gets evaluated** — if the column appears in WHERE and the table has >10K rows, consider an index
+3. **Composite indexes matter** — `INDEX(status, created_at)` ≠ `INDEX(created_at, status)`. Column order follows the query pattern (most selective first, or matching WHERE + ORDER BY)
+4. **Covering indexes** — include frequently selected columns to avoid table lookups
+
+### What to Index
+
+| Pattern | Index Type | Example |
+|---------|-----------|---------|
+| FK lookups | B-tree (default) | `orders.user_id` |
+| Status + date filters | Composite | `INDEX(status, created_at)` |
+| Full-text search | Full-text / GIN | `products.description` |
+| JSON queries | GIN (PostgreSQL) | `metadata->>'type'` |
+| Unique constraints | Unique | `users.email` |
+| Geospatial | Spatial / GiST | `locations.coordinates` |
+
+### What NOT to Index
+
+- Columns with very low cardinality on small tables (`is_active` with 2 values on 100 rows)
+- Tables with <1000 rows (index overhead > benefit)
+- Write-heavy tables where every INSERT updates 10+ indexes
+- Columns never used in WHERE, JOIN, or ORDER BY
+
+### Index Monitoring
+
+```
+REQUIRED:
+- Identify unused indexes monthly → DROP them (they slow writes)
+- Identify missing indexes → EXPLAIN ANALYZE on slow queries
+- Track index size vs table size → alarming if indexes > 3x table size
+```
+
+---
+
+## Migration Standards
+
+### Rules
+
+1. **Every schema change is a migration** — never modify production schemas manually
+2. **Migrations are versioned and sequential** — `001_create_users.sql`, `002_add_email_index.sql`
+3. **Migrations are idempotent** — running twice produces the same result
+4. **Migrations are reversible** — every UP has a DOWN (or document why rollback is impossible)
+5. **Migrations run in CI** — test against a real database, not just syntax checks
+
+### Safe Migration Patterns
+
+```
+✅ SAFE (no downtime):
+1. ADD COLUMN with default (nullable or with DEFAULT)
+2. CREATE INDEX CONCURRENTLY
+3. ADD new table
+4. Rename via view + synonym (transitional)
+
+❌ DANGEROUS (requires planned downtime or careful orchestration):
+1. DROP COLUMN (deploy code changes removing column usage FIRST)
+2. RENAME COLUMN (use gradual rename: add new → copy data → remove old)
+3. ALTER COLUMN TYPE (may lock table on large datasets)
+4. DROP TABLE (ensure no code references remain)
+```
+
+### The Expand-Contract Pattern
+
+For breaking schema changes in zero-downtime deployments:
+
+```
+Phase 1 (Expand): Add new column/table alongside old one
+   → Code writes to BOTH old and new
+Phase 2 (Migrate): Backfill data from old to new
+   → Verify data consistency
+Phase 3 (Contract): Remove old column/table
+   → Code reads/writes only new
+```
+
+---
+
+## Data Type Selection
+
+### Use the Right Type
+
+| Data | ❌ Wrong | ✅ Right | Why |
+|------|---------|---------|-----|
+| Money | `FLOAT` | `DECIMAL(19,4)` or integer cents | Floating point arithmetic is imprecise |
+| UUID | `VARCHAR(36)` | `UUID` native type | 16 bytes vs 36 bytes, indexing is faster |
+| Timestamps | `VARCHAR` | `TIMESTAMPTZ` | Timezone-aware, sortable, comparable |
+| IP addresses | `VARCHAR(45)` | `INET` (PostgreSQL) | Validation built-in, range queries |
+| Boolean | `INT` (0/1) | `BOOLEAN` | Semantic clarity |
+| Enums | `VARCHAR` | Database ENUM or CHECK constraint | Prevents invalid values |
+| JSON blobs | `TEXT` | `JSONB` (PostgreSQL) | Indexable, queryable, validated |
+
+### Column Naming
+
+```
+✅ REQUIRED:
+- snake_case for all column names
+- Descriptive: created_at, updated_at, deleted_at (not ts, mod, del)
+- Foreign keys: {referenced_table_singular}_id (e.g., user_id, order_id)
+- Boolean columns: is_active, has_verified_email, can_edit
+- Timestamps: {verb}_at (created_at, verified_at, shipped_at)
+- Amounts: {noun}_amount or {noun}_cents (total_amount, tax_cents)
+```
+
+---
+
+## Query Design Rules
+
+### Pagination (Mandatory for Lists)
+
+```
+❌ BANNED:
+SELECT * FROM orders;
+-- Returns 2 million rows, OOM crash
+
+✅ REQUIRED: Offset pagination (simple, okay for < 100K rows)
+SELECT * FROM orders ORDER BY id LIMIT 20 OFFSET 40;
+
+✅ PREFERRED: Cursor pagination (performant at any scale)
+SELECT * FROM orders WHERE id > :last_seen_id ORDER BY id LIMIT 20;
+```
+
+**Rule:** Use cursor-based pagination for tables > 100K rows. Offset pagination degrades linearly with OFFSET value.
+
+### Soft Deletes vs Hard Deletes
+
+```
+Use soft deletes (deleted_at column) when:
+- Legal/compliance requires data retention
+- Users might want to "undelete"
+- Related data would break without the parent record
+
+Use hard deletes when:
+- GDPR/privacy requires actual data removal
+- Data has no business value after deletion
+- Storage cost of keeping data outweighs benefit
+
+If soft deleting:
+- Add deleted_at to ALL queries: WHERE deleted_at IS NULL
+- Add a partial index: WHERE deleted_at IS NULL (for performance)
+- Schedule periodic hard-delete of old soft-deleted records
+```
+
+---
+
+## The Database Design Checklist
+
+Before any schema goes to production:
+
+- [ ] Schema is normalized to 3NF (denormalization documented if present)
+- [ ] All foreign keys have indexes
+- [ ] Primary keys use appropriate type (UUID or BIGINT)
+- [ ] Timestamps use TIMESTAMPTZ (not VARCHAR)
+- [ ] Money uses DECIMAL or integer cents (never FLOAT)
+- [ ] Migration is versioned, reversible, and tested in CI
+- [ ] All list queries have LIMIT (pagination implemented)
+- [ ] Indexes justified with EXPLAIN ANALYZE on expected queries
+- [ ] Column naming follows convention (snake_case, descriptive)
+- [ ] Soft delete vs hard delete decision documented
+## UNIVERSAL RULE: efficiency-vs-hype.md
+Source: .agent-context/rules/efficiency-vs-hype.md
+
+# Efficiency vs. Hype — Choose Stable, Not Shiny
+
+> Every dependency is a liability. Every `npm install` is a trust decision.
+> The best dependency is the one you don't need.
+
+## The Dependency Decision Framework
+
+Before adding ANY dependency, answer these 5 questions:
+
+### 1. Can You Do It Without a Library? (The stdlib-first Rule)
+```
+❌ OVER-ENGINEERING:
+npm install is-odd        # 1 line of code: n % 2 !== 0
+npm install left-pad      # Already in String.prototype.padStart
+npm install is-number     # typeof x === 'number' && !isNaN(x)
+npm install array-flatten # Array.prototype.flat() exists since ES2019
+
+✅ USE THE LANGUAGE:
+const isOdd = (n: number) => n % 2 !== 0;
+const padded = str.padStart(10, '0');
+const flat = nested.flat(Infinity);
+```
+
+**Dependency Defense:** If the user asks to install a new library, or if you feel the need to use one, evaluate it against the "stdlib-first" rule. If the functionality can be implemented safely in under 20 lines of code, write it yourself. If a dependency is strictly necessary, you MUST justify it by providing its bundle size, maintenance status, and why the standard library is insufficient.
+
+### 2. Is It Maintained? (The Pulse Check)
+| Signal | 🟢 Healthy | 🔴 Dead |
+|--------|-----------|---------|
+| Last commit | < 6 months ago | > 2 years ago |
+| Open issues | Actively triaged | 500+ unread |
+| Downloads/week | Growing or stable | Declining |
+| Bus factor | > 3 maintainers | 1 maintainer, inactive |
+| Security | No known CVEs | Unpatched vulnerabilities |
+
+**Rule:** If a library has a bus factor of 1 and no commit in 12+ months, it is a risk. Find an alternative or vendor-fork it.
+
+### 3. What's the Cost? (The Weight Check)
+```
+Before: npm install moment     # 289KB minified, entire library for date formatting
+After:  npm install date-fns   # 12KB for just the functions you use (tree-shakeable)
+Better: Intl.DateTimeFormat    # 0KB — built into the runtime
+```
+
+**Rule:** Check the bundle impact. Use [bundlephobia.com](https://bundlephobia.com) for JS packages. If a library adds > 50KB to your bundle for a simple feature, find a lighter alternative or implement it yourself.
+
+### 4. Is It the Community Standard? (The Ecosystem Rule)
+Prefer packages that the ecosystem has settled on:
+
+| Need | ✅ Standard | ❌ Avoid |
+|------|-----------|---------|
+| HTTP client (Node) | `undici` (built-in) / native `fetch` / `ky` | `axios` (declining, CVE-2025-58754, bloated) |
+| Validation | `zod` | `joi` (heavier), `yup` (less type-safe) |
+| ORM (Node) | `prisma`, `drizzle` | `sequelize` (legacy API), `typeorm` (decorator hell) |
+| Date handling | `date-fns`, `dayjs`, `Temporal` (when stable) | `moment` (deprecated, massive) |
+| Testing | `vitest` (new projects), `jest` (existing) | `mocha` + `chai` + `sinon` (3 deps for what 1 does) |
+| Password hashing | `argon2` (OWASP primary), `bcrypt` (legacy) | Custom crypto (NEVER) |
+| Env loading | `dotenv` (if needed) | Custom `.env` parser |
+
+**Note:** These are current recommendations as of March 2026. Evaluate against this framework; don't blindly follow.
+
+### 5. Can You Remove It Later? (The Exit Strategy)
+```
+❌ HIGH LOCK-IN:
+// Decorators from a specific framework scattered across 200 files
+@Controller() @Injectable() @Guard() // In every file — framework is your entire architecture
+
+✅ LOW LOCK-IN:
+// Framework stays at the edges; business logic is framework-free
+// Switching from Express to Fastify only changes the transport layer
+```
+
+**Rule:** Wrap external dependencies that touch > 5 files. If you need to replace a library, it should only affect the wrapper, not your entire codebase.
+
+---
+
+## The Hype Trap (AI-Generated Code Alert)
+
+AI agents love suggesting trendy libraries because they appear frequently in training data. Watch for:
+
+### Red Flags
+1. **"Just install X"** without explaining why → ASK: Can I do this with the stdlib?
+2. **Library does one thing** that's 5 lines of code → REJECT: Write it yourself
+3. **Library is in alpha/beta** with < 1 year of releases → REJECT: Not production-ready
+4. **Library has a cooler API** but the current one works fine → REJECT: "Cool" is not a business requirement
+5. **"Everyone is using it"** → SO WHAT: Popularity is not a quality signal
+
+### The Agent Must Justify Dependencies
+When an AI agent suggests adding a new dependency, it MUST provide:
+```
+📦 DEPENDENCY JUSTIFICATION
+━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Package: [name@version]
+Purpose: [what it does in 1 sentence]
+Stdlib Alternative: [why it's insufficient — or "none"]
+Bundle Size: [minified + gzipped]
+Maintenance: [last release date, maintainer count]
+Lock-in Risk: [low/medium/high — how many files would it touch]
+Exit Strategy: [how to remove it if needed]
+```
+
+---
+
+## Dependency Update Strategy
+
+1. **Pin exact versions** in lockfiles (already default with package-lock.json, bun.lockb)
+2. **Review changelogs** before major updates — never blindly `npm update`
+3. **Update in isolation** — one dependency per PR, with tests passing
+4. **Security patches immediately** — don't wait for the sprint
+5. **Monthly audit** — run `npm audit` / `bun audit` and address findings
+
+---
+
+## The Zero-Dependency Ideal
+
+The best packages are those with zero or minimal dependencies themselves:
+- `zod` — 0 dependencies ✅
+- `date-fns` — 0 dependencies ✅
+- `nanoid` — 0 dependencies ✅
+- `bcrypt` — 1 native dependency (justified for crypto) ✅
+
+A package that pulls in 50 transitive dependencies for a simple feature is a supply chain attack waiting to happen.
+
+---
+
+## Quick Decision Tree
+
+```
+Do I need this functionality?
+  → No → Don't install anything
+  → Yes ↓
+
+Can I write it in < 20 lines?
+  → Yes → Write it yourself
+  → No ↓
+
+Does the language/runtime provide it?
+  → Yes → Use the built-in
+  → No ↓
+
+Is there a well-maintained, lightweight, community-standard package?
+  → Yes → Install it, add justification comment
+  → No → Build a minimal internal implementation, consider vendoring
+```
+## UNIVERSAL RULE: error-handling.md
+Source: .agent-context/rules/error-handling.md
+
+# Error Handling — Never Swallow, Always Context
+
+> A swallowed error is a silent production incident waiting to happen.
+> When it explodes at 3 AM, you won't know where to look.
+
+## The Three Commandments
+
+1. **Never swallow an error.** Every error must be logged, re-thrown, or explicitly handled.
+2. **Always add context.** A stack trace is not enough — include WHAT was happening and WITH WHAT data.
+3. **Fail fast at boundaries.** Validate early, reject bad data before it travels deep into the system.
+
+---
+
+## Swallowed Error Detection (Instant Rejection)
+
+```
+❌ DEATH PENALTY: Empty catch block
+try {
+  await processPayment(order);
+} catch (error) {
+  // silently swallowed — payment may have failed, user has no idea
+}
+
+❌ DEATH PENALTY: Catch and log only (no re-throw or recovery)
+try {
+  await processPayment(order);
+} catch (error) {
+  console.log('error:', error);  // Logged to a void nobody reads
+  // Execution continues as if nothing happened
+}
+
+✅ CORRECT: Handle, log with context, re-throw or recover
+try {
+  await processPayment(order);
+} catch (error) {
+  logger.error('Payment processing failed', {
+    orderId: order.id,
+    userId: order.userId,
+    amount: order.total,
+    error: error instanceof Error ? error.message : String(error),
+  });
+  throw new PaymentFailedError(order.id, { cause: error });
+}
+```
+
+---
+
+## Typed Error Codes
+
+### Rule: Use Explicit Error Types, Not Generic Errors
+
+```
+❌ BANNED: Generic errors
+throw new Error('Not found');
+throw new Error('Permission denied');
+throw new Error('Invalid input');
+
+✅ REQUIRED: Typed, domain-specific errors
+throw new NotFoundError('User', userId);
+throw new ForbiddenError('Cannot delete other user\'s order');
+throw new ValidationError('Email format is invalid', { field: 'email' });
+```
+
+### Error Class Pattern (Any Language)
+```typescript
+// Base application error
+class AppError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string,
+    public readonly statusCode: number,
+    public readonly context?: Record<string, unknown>,
+  ) {
+    super(message);
+    this.name = this.constructor.name;
+  }
+}
+
+// Specific errors
+class NotFoundError extends AppError {
+  constructor(resource: string, id: string | number) {
+    super(`${resource} not found: ${id}`, 'NOT_FOUND', 404, { resource, id });
+  }
+}
+
+class ValidationError extends AppError {
+  constructor(message: string, context?: Record<string, unknown>) {
+    super(message, 'VALIDATION_ERROR', 400, context);
+  }
+}
+
+class ForbiddenError extends AppError {
+  constructor(reason: string) {
+    super(reason, 'FORBIDDEN', 403);
+  }
+}
+```
+
+---
+
+## Structured Logging
+
+### Rule: Logs Must Include Context
+
+```
+❌ USELESS:
+logger.error('Something went wrong');
+logger.info('Processing...');
+console.log(error);
+
+✅ USEFUL:
+logger.error('Order processing failed', {
+  traceId: req.traceId,
+  userId: currentUser.id,
+  orderId: order.id,
+  action: 'processOrder',
+  error: error.message,
+  stack: error.stack,
+});
+
+logger.info('Payment completed', {
+  traceId: req.traceId,
+  orderId: order.id,
+  amount: payment.amount,
+  provider: payment.provider,
+  durationMs: Date.now() - startTime,
+});
+```
+
+### Required Log Fields
+| Field | When | Purpose |
+|-------|------|---------|
+| `traceId` / `requestId` | Always (in request context) | Correlate logs across services |
+| `userId` | When authenticated | Who triggered the action |
+| `action` | Always | What was happening |
+| `error` + `stack` | On errors | What went wrong |
+| `durationMs` | On slow operations | Performance visibility |
+
+---
+
+## Error Response Format (APIs)
+
+### Rule: NEVER Leak Internal Details
+
+```
+❌ BANNED response to client:
+{
+  "error": "ER_NO_SUCH_TABLE: Table 'mydb.user_sessions' doesn't exist",
+  "stack": "Error: at Query.execute (/app/node_modules/mysql..."
+}
+// Congratulations, you just told the attacker your DB name and framework
+
+✅ REQUIRED response to client:
+{
+  "error": {
+    "code": "INTERNAL_ERROR",
+    "message": "An unexpected error occurred. Please try again.",
+    "traceId": "abc-123-def"
+  }
+}
+// Internal details go to your logs, not to the client
+```
+
+### Error Response Mapping
+| Internal Error | HTTP Status | Client Message |
+|---------------|-------------|----------------|
+| `ValidationError` | 400 | Show specific field errors |
+| `AuthenticationError` | 401 | "Invalid credentials" (never specify which field) |
+| `ForbiddenError` | 403 | "Insufficient permissions" |
+| `NotFoundError` | 404 | "Resource not found" |
+| `ConflictError` | 409 | "Resource already exists" |
+| `RateLimitError` | 429 | "Too many requests" |
+| Unhandled errors | 500 | "Internal error" + traceId for support |
+
+---
+
+## Fail-Fast at Boundaries
+
+```
+// ✅ Validate at the entry point, fail before going deeper
+async function createOrder(req: Request) {
+  // Step 1: Validate input IMMEDIATELY
+  const parsed = CreateOrderSchema.safeParse(req.body);
+  if (!parsed.success) {
+    throw new ValidationError('Invalid order data', parsed.error.flatten());
+  }
+
+  // Step 2: Now use the validated, typed data
+  const order = await orderService.create(parsed.data);
+  return order;
+}
+
+// ❌ Don't let bad data travel deep before failing
+async function createOrder(req: Request) {
+  const data = req.body;  // Unvalidated!
+  const order = await orderService.create(data);
+  // Service calls repository, repository tries to insert...
+  // Database throws a cryptic constraint violation 5 layers deep
+}
+```
+
+---
+
+## Retry Strategy
+
+When retrying failed operations:
+
+1. **Only retry transient errors** (network timeouts, 503s) — NEVER retry validation errors or auth failures
+2. **Use exponential backoff** — 100ms → 200ms → 400ms → 800ms
+3. **Set a maximum retry count** (typically 3)
+4. **Log every retry attempt** with attempt number and error
+5. **Add jitter** to prevent thundering herd
+
+```typescript
+async function withRetry<T>(
+  operation: () => Promise<T>,
+  maxAttempts: number = 3,
+  baseDelayMs: number = 100,
+): Promise<T> {
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await operation();
+    } catch (error) {
+      if (attempt === maxAttempts || !isTransientError(error)) {
+        throw error;
+      }
+      const delay = baseDelayMs * Math.pow(2, attempt - 1) + Math.random() * 100;
+      logger.warn('Retrying operation', { attempt, maxAttempts, delayMs: delay });
+      await sleep(delay);
+    }
+  }
+  throw new Error('Unreachable');
+}
+```
+## UNIVERSAL RULE: event-driven.md
+Source: .agent-context/rules/event-driven.md
+
+# Event-Driven Architecture — React to Facts, Don't Poll for Changes
+
+> If your services are constantly asking "Did anything change?", your architecture is broken.
+> Events are the nervous system of a distributed system.
+
+## When to Use Event-Driven Architecture
+
+### Use Events When:
+1. Multiple services need to react to the same state change
+2. You need temporal decoupling (producer doesn't wait for consumer)
+3. Audit trail / event history is a business requirement
+4. Systems need to scale producers and consumers independently
+5. Eventual consistency is acceptable
+
+### Don't Use Events When:
+- You need an immediate, synchronous response
+- The system is a simple CRUD application with 1-2 services
+- You can't invest in proper infrastructure (message broker, monitoring)
+- Your team has no experience with async debugging
+
+---
+
+## Core Patterns
+
+### 1. Pub/Sub (Publish-Subscribe)
+
+Producer emits an event. Zero or more consumers react independently.
+
+```
+              ┌──────────┐
+              │ Consumer A│ (Send email)
+              └────▲──────┘
+┌──────────┐      │
+│ Producer  │──→ EVENT BUS ──→┌──────────┐
+│ (Order    │      │          │ Consumer B│ (Update inventory)
+│  Service) │      │          └──────────┘
+└──────────┘      │
+              ┌───▼──────┐
+              │ Consumer C│ (Analytics)
+              └──────────┘
+```
+
+**Rules:**
+- Producer does NOT know about consumers (fire-and-forget)
+- Each consumer processes independently (failure in one doesn't affect others)
+- Consumers MUST be idempotent (same event processed twice = same result)
+
+### 2. CQRS (Command Query Responsibility Segregation)
+
+Separate the write model (commands) from the read model (queries).
+
+```
+┌─────────────┐                  ┌─────────────┐
+│ Write Side  │    Events        │  Read Side   │
+│ (Commands)  │ ──────────────→  │  (Queries)   │
+│             │                  │              │
+│ Rich domain │                  │ Denormalized │
+│ model       │                  │ read models  │
+│ Normalized  │                  │ Optimized    │
+│ schema      │                  │ for queries  │
+└─────────────┘                  └─────────────┘
+```
+
+**When to use CQRS:**
+- Read/write ratio is heavily skewed (100:1 reads to writes)
+- Read and write models have fundamentally different shapes
+- You need different scaling for reads vs writes
+
+**When NOT to use CQRS:**
+- Simple CRUD with no complex queries
+- Read and write models are identical (just use a repository)
+- You don't have the team capacity to maintain two models
+
+### 3. Event Sourcing
+
+Store the full history of state changes as immutable events, not just the current state.
+
+```
+Traditional:  User { name: "Jane", email: "jane@new.com" }
+              → You only know the current state
+
+Event Sourced:
+  1. UserCreated { name: "Jane", email: "jane@old.com" }
+  2. EmailChanged { email: "jane@mid.com" }
+  3. EmailChanged { email: "jane@new.com" }
+  → You know the full history, can rebuild any point in time
+```
+
+**When to use Event Sourcing:**
+- Audit trail is a regulatory requirement (finance, healthcare)
+- "Time travel" queries are needed (what was the state on March 1?)
+- Complex domain with many state transitions
+- Combined with CQRS for complex read requirements
+
+**When NOT to use Event Sourcing:**
+- Simple CRUD applications (overkill)
+- Team has no experience with event stores
+- No clear business need for historical state
+
+---
+
+## Event Design Rules
+
+### Naming: Past Tense, Domain Language
+
+```
+❌ BANNED:
+  "UpdateOrder"       → Commands, not events
+  "ORDER_UPDATE"      → Screaming snake in an event name
+  "data"              → Meaningless
+
+✅ REQUIRED:
+  "OrderPlaced"       → Past tense, describes what happened
+  "PaymentProcessed"  → Specific, clear domain action
+  "InventoryReserved" → Business language, not technical
+```
+
+### Event Schema: Include Context
+
+```typescript
+// ❌ BANNED: Minimal event with no context
+{ type: "OrderPlaced", orderId: "123" }
+
+// ✅ REQUIRED: Rich event with all necessary context
+{
+  eventId: "evt_abc123",          // Unique, for idempotency
+  eventType: "OrderPlaced",       // What happened
+  aggregateId: "order_123",       // Which entity
+  aggregateType: "Order",         // Entity type
+  timestamp: "2026-03-11T...",    // When it happened
+  version: 1,                     // Schema version
+  correlationId: "req_xyz",       // Trace across services
+  causationId: "cmd_456",        // What caused this event
+  data: {                         // The event payload
+    orderId: "order_123",
+    userId: "user_789",
+    items: [...],
+    totalAmount: 99.99,
+    currency: "USD"
+  },
+  metadata: {                     // Operational metadata
+    producerService: "order-service",
+    producerVersion: "2.1.0"
+  }
+}
+```
+
+### Event Versioning
+
+Events are immutable — once published, they can't change. Handle evolution with:
+
+1. **Weak schema (preferred):** Consumers ignore unknown fields, use defaults for missing fields
+2. **Upcasting:** Transform old events to new schema on read
+3. **New event type:** If the change is breaking, create `OrderPlacedV2`
+
+```
+BANNED: Changing the schema of an existing event in a breaking way
+BANNED: Removing fields from events
+ALLOWED: Adding optional fields with defaults
+ALLOWED: Creating a new event type for breaking changes
+```
+
+---
+
+## Infrastructure Choices
+
+| Need | Recommended | Avoid |
+|------|-----------|-------|
+| General pub/sub | Apache Kafka, NATS, RabbitMQ | Custom TCP sockets |
+| Cloud-native | AWS EventBridge, GCP Pub/Sub, Azure Service Bus | Polling a database table |
+| Simple/local | Redis Streams, NATS | ZeroMQ for production events |
+| Event store | EventStoreDB, Kafka (with compaction) | Relational DB as event store (unless simple) |
+
+---
+
+## Reliability Patterns
+
+### Outbox Pattern (Transactional Events)
+
+Ensure events are published reliably alongside database writes:
+
+```
+1. Write to database AND outbox table in a single transaction
+2. Background process reads outbox and publishes to message broker
+3. Mark outbox entry as published
+
+This guarantees: if the DB write succeeds, the event WILL be published.
+No more "DB updated but event lost" bugs.
+```
+
+### Dead Letter Queue (DLQ)
+
+Messages that fail processing after N retries go to a DLQ:
+- Monitor DLQ size — it should be near zero
+- Alert when DLQ grows
+- Investigate and reprocess failed messages
+- Never ignore a growing DLQ
+
+### Idempotency (Non-Negotiable)
+
+```
+EVERY consumer MUST handle duplicate events safely.
+
+Techniques:
+1. Idempotency key: Store processed eventIds, skip if seen
+2. Natural idempotency: Operations that are naturally safe to repeat
+   (e.g., SET status = 'paid' is idempotent; INCREMENT balance is NOT)
+3. Optimistic locking: Use version numbers to detect conflicts
+```
+
+---
+
+## The Event-Driven Checklist
+
+Before implementing event-driven patterns:
+
+- [ ] Business justification exists (not just "it's modern")
+- [ ] Team understands eventual consistency trade-offs
+- [ ] Message broker selected and provisioned
+- [ ] Event schema defined with versioning strategy
+- [ ] All consumers are idempotent
+- [ ] Dead letter queue configured with monitoring
+- [ ] Distributed tracing in place (OpenTelemetry)
+- [ ] Outbox pattern used for transactional events (if needed)
+- [ ] Consumer failure handling defined (retry, DLQ, alert)
+- [ ] Event catalog maintained (what events exist, who produces/consumes)
+## UNIVERSAL RULE: frontend-architecture.md
+Source: .agent-context/rules/frontend-architecture.md
+
+# Frontend Architecture & Composition Patterns
+
+> A complex UI is built from simple, mathematically robust functions. State is dangerous; isolate it.
+
+## 1. File Structure (Feature-Driven Design)
+Organize your application by feature domain, not by file type.
+- **BANNED:** Monolithic directories like `/components` (with 500 files), `/hooks`, `/api`.
+- **REQUIRED (Feature Sliced):**
+  ```
+  src/
+    features/
+      authentication/
+        api/          #(login, logout fetchers)
+        components/   #(LoginForm, ProfileView)
+        hooks/        #(useAuth, useSession)
+        store.ts      #(Zustand slice)
+        types.ts      #(Zod schemas)
+    components/       #(Global shared UI like Button, Modal)
+    lib/              #(Axios instance, utility wrappers)
+  ```
+
+## 2. Separation of State and UI (Smart vs. Dumb)
+- **Dumb Components (Presentational):** Receive data via `props`, emit events via callbacks (`onAction`). They do not know about the network, global context, or databases.
+- **Smart Components (Containers):** Connect to global state (Redux/Zustand), fetch data (React Query), and pass it down.
+- **Rule:** An intricate UI layout component should NEVER contain a `fetch` or `useQuery` call.
+
+## 3. Server State vs. Client State
+Modern frontend frameworks differentiate between remote and local data.
+- **Server State (Async, Cached):** Data belonging to the database. MUST be managed by tools like `TanStack Query` (React Query) or `SWR`.
+- **Client State (Sync, Ephemeral):** UI toggles, modal states, form drafts. Manage via `useState`, `useContext`, or `Zustand`.
+- **BANNED:** Storing API responses in a global Redux/Zustand store (e.g., `dispatch(setUsers(data))`). Use React Query instead.
+
+## 4. The Composition Pattern (Avoiding Prop Drilling)
+If a component takes more than 5 props, or if props are passed down through 3+ intermediate components, the architecture is broken.
+- **BANNED:** `<Layout user={user} theme={theme} onLogout={handleLogout} />`
+- **REQUIRED:** Use React's `children` prop and composition.
+  ```tsx
+  // ✅ Clean composition
+  <Layout>
+    <Sidebar user={user} />
+    <Content onLogout={handleLogout} />
+  </Layout>
+  ```
+
+## 5. Explicit Component Contracts (Typing)
+Every component **MUST** have an explicit, exported interface for its props.
+- **BANNED:** `const Button = (props: any) => ...`
+- **REQUIRED:** Prefix handlers with `on` and booleans with `is/has`.
+  ```typescript
+  export interface ButtonProps {
+    variant: 'primary' | 'secondary';
+    isLoading?: boolean;
+    onClick: () => void;
+    children: React.ReactNode;
+  }
+  ```
+
+## 6. Form Handling & Validation
+Never write manual state bindings for complex forms.
+- **Rule:** All forms MUST use a robust library (`react-hook-form` is the standard) combined with a schema validator (`Zod`).
+- **BANNED:** Creating 5 `useState` variables for 5 input fields.
+
+## 7. Performance & Re-renders
+React is fast until you break it.
+- **Rule:** Do not pass newly instantiated objects or arrow functions directly into dependency arrays (`useEffect`) or memoized components (`React.memo`) unless wrapped in `useMemo`/`useCallback`.
+- **Rule:** Never execute expensive mapping/filtering inside the render path blindly without memoization.
+## UNIVERSAL RULE: git-workflow.md
+Source: .agent-context/rules/git-workflow.md
+
+# Git Workflow — Clean History, Atomic Commits
+
+> Your git log is a changelog. If it reads like gibberish, your team is lost.
+
+## Commit Message Format: Conventional Commits (Enforced)
+
+```
+<type>(<scope>): <description>
+
+[optional body — explain WHY, not WHAT]
+[optional footer — Breaking changes, issue references]
+```
+
+### Types (Strict Set)
+| Type | When | Example |
+|------|------|---------|
+| `feat` | New feature | `feat(auth): add JWT refresh token rotation` |
+| `fix` | Bug fix | `fix(payment): handle race condition in checkout` |
+| `refactor` | Code restructuring (no behavior change) | `refactor(user): extract validation to separate service` |
+| `docs` | Documentation only | `docs(api): add OpenAPI schema for /orders endpoint` |
+| `test` | Adding/fixing tests | `test(cart): add edge case for empty cart discount` |
+| `chore` | Build, CI, config, dependencies | `chore(deps): upgrade prisma to 5.x` |
+| `perf` | Performance improvement | `perf(search): add index on users.email column` |
+| `style` | Formatting, semicolons (no logic change) | `style: apply prettier formatting` |
+| `ci` | CI/CD changes | `ci: add Node 20 to test matrix` |
+
+### Rules
+1. **Type is mandatory.** No commits without a type prefix.
+2. **Scope is recommended.** Use the module/feature name.
+3. **Description is imperative mood.** "add", not "added" or "adds".
+4. **Max 72 characters** for the subject line.
+5. **Body explains WHY,** not what. The diff shows what.
+
+### ❌ BANNED Commit Messages
+```
+fix bug
+updates
+WIP
+asdf
+misc changes
+working now
+final fix
+fix fix fix
+```
+
+---
+
+## Branching Model
+
+### Main Branches
+| Branch | Purpose | Merge Strategy |
+|--------|---------|---------------|
+| `main` | Production-ready code | Merge commit or squash |
+| `develop` | Integration branch (if using GitFlow) | Merge commit |
+
+### Feature Branches
+```
+Pattern: <type>/<ticket-id>-<short-description>
+
+Examples:
+  feat/AUTH-123-jwt-refresh
+  fix/PAY-456-checkout-race-condition
+  refactor/USER-789-extract-validation
+  chore/INFRA-101-upgrade-node-20
+```
+
+### Rules
+1. Branch from `main` (or `develop` if using GitFlow)
+2. Keep branches short-lived (max 2-3 days)
+3. Rebase on `main` before creating PR — don't merge main into your branch
+4. Delete branch after merge
+
+---
+
+## Pull Request Standards
+
+### PR Size
+| Size | Lines Changed | Verdict |
+|------|--------------|---------|
+| Small | 1-100 | ✅ Ideal — easy to review |
+| Medium | 100-300 | ⚠️ Acceptable — split if possible |
+| Large | 300-500 | 🔶 Needs justification |
+| Massive | 500+ | ❌ MUST be split into smaller PRs |
+
+**Rule:** If a PR touches more than 5 files across different modules, it's doing too much. Split it.
+
+### PR Description Template
+```markdown
+## What
+Brief description of what this PR does.
+
+## Why
+Why this change is needed. Link to issue/ticket.
+
+## How
+High-level approach. Mention any non-obvious design decisions.
+
+## Testing
+- [ ] Unit tests added/updated
+- [ ] Integration tests (if applicable)
+- [ ] Manual testing steps
+
+## Screenshots (if UI change)
+Before | After
+```
+
+### PR Review Rules
+1. Every PR needs at least 1 approval
+2. Author resolves all comments before merge
+3. CI must pass (lint, test, build)
+4. No `// TODO` without a linked issue
+5. No `console.log` debugging statements in production code
+
+---
+
+## Commit Atomicity
+
+### Rule: Each Commit Must Be a Complete, Working Unit
+
+```
+❌ BANNED sequence:
+1. feat(user): add user model          ← compiles? maybe
+2. fix: fix import                     ← fixing previous commit
+3. feat(user): add user service        ← compiles? probably
+4. fix: fix typo                       ← fixing previous commit
+5. feat(user): add user controller     ← finally works together
+
+✅ REQUIRED:
+1. feat(user): add user registration module
+   → Model, Service, Controller, Tests — all in one complete, working commit
+   → Or split into logical chunks that each compile and pass tests independently
+```
+
+**Rule:** Every commit on `main` should compile, pass lint, and pass tests. Use interactive rebase (`git rebase -i`) to squash fix-up commits before merging.
+
+---
+
+## .gitignore Standards
+
+### MUST Ignore
+```
+# Dependencies
+node_modules/
+vendor/
+venv/
+__pycache__/
+.gradle/
+target/
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# IDE
+.idea/
+.vscode/settings.json
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
+
+# Build output
+dist/
+build/
+out/
+*.min.js
+*.min.css
+
+# Logs
+*.log
+npm-debug.log*
+
+# OS
+.DS_Store
+Thumbs.db
+```
+
+### MUST Commit
+```
+.env.example           # Template with placeholder values
+.editorconfig          # Consistent formatting across IDEs
+.prettierrc            # Formatter config
+.eslintrc.*            # Linter config
+tsconfig.json          # TypeScript config
+docker-compose.yml     # Dev environment
+Makefile / Taskfile    # Standard commands
+```
+
+---
+
+## The Git Health Check
+
+Before pushing:
+- [ ] All commits follow Conventional Commits format
+- [ ] No fixup commits (squash them)
+- [ ] Branch is rebased on latest main
+- [ ] CI passes locally (lint, test, build)
+- [ ] No secrets in any commit (check with `git log -p | grep -i "password\|secret\|key"`)
+- [ ] No merge commits in feature branch (rebase instead)
+## UNIVERSAL RULE: microservices.md
+Source: .agent-context/rules/microservices.md
+
+# Microservices — When to Split, How to Split
+
+> Don't start with microservices. Earn them through pain.
+> A bad monolith becomes a distributed bad monolith faster than you think.
+
+## The Default: Modular Monolith
+
+**Start with a modular monolith. Always.** Microservices are a scaling strategy, not a design philosophy.
+
+A well-structured modular monolith can handle most applications indefinitely. Splitting prematurely creates distributed complexity without distributed benefits.
+
+---
+
+## The Split Decision Framework
+
+### Prerequisites (ALL Must Be True)
+
+Before even considering microservices, these must exist:
+
+1. **Mature CI/CD pipeline** — automated testing, deployment, rollback
+2. **Observability in place** — distributed tracing, centralized logging, metrics
+3. **Team maturity** — team understands distributed systems failure modes
+4. **Clear module boundaries** — modules already communicate through interfaces, not internals
+
+If any prerequisite is missing, **stop.** Fix the monolith first.
+
+### Trigger Conditions (2+ Required)
+
+Split a module into a service ONLY when **2 or more** of these triggers exist:
+
+| # | Trigger | Evidence |
+|---|---------|----------|
+| 1 | **Deploy conflicts** | Teams block each other on releases; merge queues exceed 24h |
+| 2 | **Scale mismatch** | One module needs 50-100x resources of another |
+| 3 | **Team ownership collision** | Multiple teams edit the same module weekly |
+| 4 | **Fault isolation** | One module crashing must not kill the entire system |
+| 5 | **Technology divergence** | Module genuinely requires a different runtime/language |
+| 6 | **Compliance boundary** | Regulatory requirement to isolate data processing (PCI, HIPAA) |
+
+```
+BANNED: "Let's use microservices because Netflix does"
+BANNED: "We might need to scale later"
+BANNED: "It's more modern"
+BANNED: "Each developer gets their own service"
+```
+
+---
+
+## How to Split (The Extraction Protocol)
+
+### Step 1: Identify the Seam
+
+Find the natural boundary in your modular monolith:
+```
+GOOD seams:
+  - Module communicates with others through a defined interface/API
+  - Module has its own database tables with no foreign keys to other modules
+  - Module can be deployed independently without breaking others
+
+BAD seams:
+  - Two modules share a database table
+  - Extracting requires duplicating business logic
+  - Module makes 10+ synchronous calls to other modules per request
+```
+
+### Step 2: Strangle, Don't Rewrite
+
+```
+❌ BANNED: "Let's rewrite everything as microservices"
+
+✅ REQUIRED: The Strangler Fig Pattern
+1. Build the new service alongside the monolith
+2. Route traffic to the new service gradually (feature flags, proxy rules)
+3. Verify the new service handles all cases correctly
+4. Remove the old code from the monolith
+5. Repeat for the next service, ONE AT A TIME
+```
+
+### Step 3: Define the Contract
+
+Before extracting, define the communication contract:
+
+```
+REQUIRED for every service boundary:
+- API contract (OpenAPI 3.1, Protobuf, or AsyncAPI for events)
+- Versioning strategy (URL versioning, header versioning)
+- Error contract (standardized error response format)
+- SLA definition (latency, availability, throughput)
+- Ownership (which team owns this service)
+```
+
+---
+
+## Communication Patterns
+
+### Synchronous (Request-Response)
+
+| Pattern | When | Watch Out |
+|---------|------|-----------|
+| REST/HTTP | Standard CRUD operations | Cascading failures, tight coupling |
+| gRPC | High-performance, internal services | Schema evolution, debugging complexity |
+
+**Rules:**
+- Always set timeouts (connection: 1s, request: 5s default)
+- Implement circuit breakers (fail-fast after N failures)
+- Never chain more than 3 synchronous calls
+- Implement retries with exponential backoff (transient errors only)
+
+### Asynchronous (Events)
+
+| Pattern | When | Watch Out |
+|---------|------|-----------|
+| Pub/Sub | One event, multiple consumers | Message ordering, at-least-once delivery |
+| Command Queue | Exactly-once processing needed | Dead letter queues, poison messages |
+| Event Sourcing | Full audit trail required | Complexity, event schema evolution |
+
+**Rules:**
+- Prefer async communication over sync between services
+- Events are facts (past tense): `OrderPlaced`, `PaymentProcessed`
+- Commands are requests (imperative): `ProcessPayment`, `ShipOrder`
+- Always handle duplicate messages (idempotency)
+
+---
+
+## Data Ownership
+
+### The Database-Per-Service Rule
+
+```
+❌ DEATH PENALTY: Shared databases between services
+   Service A → Database ← Service B
+   // One schema change breaks both services
+
+✅ REQUIRED: Each service owns its data
+   Service A → Database A
+   Service B → Database B
+   // Services communicate through APIs or events
+```
+
+### Data Consistency
+
+- **Accept eventual consistency** — strong consistency across services is extremely expensive
+- **Use the Saga pattern** for distributed transactions (choreography or orchestration)
+- **Never use distributed 2PC (two-phase commit)** in production — it doesn't scale
+
+---
+
+## Anti-Patterns (Instant Rejection)
+
+| Anti-Pattern | Why It's Dangerous |
+|-------------|-------------------|
+| **Distributed Monolith** | Services that must be deployed together defeat the purpose |
+| **Nano-services** | One function per service creates operational nightmare |
+| **Shared libraries with logic** | Tight coupling through shared code |
+| **Synchronous chains** | A→B→C→D means one failure kills everything |
+| **Shared database** | Schema changes break multiple services |
+| **"We'll figure out observability later"** | You won't find bugs without tracing. Ever. |
+
+---
+
+## The Microservices Readiness Checklist
+
+Before splitting ANY module:
+
+- [ ] 2+ trigger conditions met (documented with evidence)
+- [ ] All prerequisites in place (CI/CD, observability, team maturity)
+- [ ] Service boundary defined with clear ownership
+- [ ] API contract defined (OpenAPI, Protobuf, AsyncAPI)
+- [ ] Data ownership clear — no shared tables
+- [ ] Communication pattern chosen (sync vs async)
+- [ ] Failure handling designed (timeouts, circuit breakers, retries)
+- [ ] Monitoring and alerting planned
+- [ ] Rollback strategy defined
+- [ ] Team agrees this is the right decision (not just the architect)
+## UNIVERSAL RULE: naming-conv.md
+Source: .agent-context/rules/naming-conv.md
+
+# Naming Conventions — The "No Lazy Names" Standard
+
+> If your variable name needs a comment to explain it, the name is wrong.
+
+## Universal Rules (All Languages)
+
+### Variables: Nouns That Tell a Story
+```
+❌ BANNED                    ✅ REQUIRED
+─────────────────────────────────────────────
+d                           durationInSeconds
+data                        userProfilePayload
+res                         httpResponse
+temp                        unsortedItems
+val                         discountPercentage
+info                        orderSummary
+item                        cartLineItem
+list                        activeSubscriptions
+obj                         paymentConfiguration
+```
+
+**Rule:** A variable name must answer "WHAT is this?" without reading surrounding code.
+
+### Functions: Verbs That Declare Intent
+```
+❌ BANNED                    ✅ REQUIRED
+─────────────────────────────────────────────
+process()                   validatePaymentDetails()
+handle()                    routeIncomingWebhook()
+doStuff()                   calculateShippingCost()
+run()                       executeScheduledCleanup()
+getData()                   fetchActiveUsersByRegion()
+check()                     isEligibleForDiscount()
+```
+
+**Rule:** A function name must answer "WHAT does this do?" as a verb phrase. Generic verbs like `process`, `handle`, `manage` are BANNED unless suffixed with a specific noun (e.g., `handlePaymentFailure`).
+
+### Booleans: is/has/can/should Prefix
+```
+❌ BANNED                    ✅ REQUIRED
+─────────────────────────────────────────────
+active                      isActive
+logged                      isLoggedIn
+admin                       hasAdminRole
+edit                        canEditDocument
+visible                     shouldRenderSidebar
+```
+
+**Rule:** Boolean variables MUST use `is`, `has`, `can`, or `should` prefix. No exceptions.
+
+### Constants: SCREAMING_SNAKE for True Constants
+```
+❌ BANNED                    ✅ REQUIRED
+─────────────────────────────────────────────
+maxRetries = 3              MAX_RETRY_COUNT = 3
+timeout = 5000              REQUEST_TIMEOUT_MS = 5000
+apiUrl = "..."              API_BASE_URL = "..."
+```
+
+**Rule:** Use SCREAMING_SNAKE_CASE for compile-time constants and config values. Include the unit in the name when applicable (`_MS`, `_BYTES`, `_COUNT`).
+
+### Single-Letter Variables
+**BANNED.** With exactly ONE exception:
+
+```
+// ALLOWED: Classic loop counter in simple iterations
+for (let i = 0; i < items.length; i++) { ... }
+
+// BANNED: Everything else
+const x = getPrice();        // ❌ What is x?
+const n = users.length;      // ❌ Use userCount
+arr.map(v => v.id);          // ❌ Use user => user.id
+```
+
+---
+
+## File & Directory Naming
+
+### Files
+| Type | Convention | Example |
+|------|-----------|---------|
+| Component (React/Vue) | PascalCase | `PaymentForm.tsx` |
+| Module/Service | camelCase or kebab-case | `paymentService.ts` or `payment-service.ts` |
+| Utility | camelCase or kebab-case | `formatCurrency.ts` or `format-currency.ts` |
+| Test | Same as source + `.test`/`.spec` | `paymentService.test.ts` |
+| Type/Interface | PascalCase | `PaymentTypes.ts` |
+| Constant file | SCREAMING_SNAKE or kebab-case | `constants.ts` or `api-endpoints.ts` |
+| Config | kebab-case | `database-config.ts` |
+
+**Rule:** Pick ONE convention per project and enforce it everywhere. Mixing `camelCase` and `kebab-case` in the same project is a code smell.
+
+### Directories
+- Always `kebab-case`: `user-management/`, `payment-processing/`
+- Never PascalCase for directories (except component folders in React convention)
+- No abbreviations: `auth/` → `authentication/` (unless universally understood like `api/`, `db/`)
+
+---
+
+## Abbreviation Policy
+
+### Allowed (Universal)
+`id`, `url`, `api`, `db`, `http`, `io`, `ui`, `dto`, `config`, `env`, `auth`, `admin`, `src`, `lib`, `pkg`, `cmd`, `ctx`, `err`, `req`, `res` (in HTTP handler context only)
+
+### Banned
+Everything else. Spell it out:
+```
+❌ usr → ✅ user
+❌ cnt → ✅ count
+❌ mgr → ✅ manager
+❌ btn → ✅ button
+❌ msg → ✅ message
+❌ impl → ✅ implementation
+❌ calc → ✅ calculate
+❌ proc → ✅ process
+```
+
+---
+
+## The Naming Decision Tree
+
+```
+Is it a boolean?
+  → Yes → Add is/has/can/should prefix
+  → No ↓
+
+Is it a function?
+  → Yes → Start with a verb (fetch, create, validate, calculate, is, has)
+  → No ↓
+
+Is it a constant?
+  → Yes → SCREAMING_SNAKE_CASE with unit suffix
+  → No ↓
+
+Is it a class/type/interface?
+  → Yes → PascalCase, noun, no prefix (not IUser, not UserInterface)
+  → No ↓
+
+It's a variable
+  → Descriptive noun, camelCase
+  → Must be understandable without context
+```
+## UNIVERSAL RULE: performance.md
+Source: .agent-context/rules/performance.md
+
+# Performance — Measure Before You Optimize
+
+> Premature optimization is the root of all evil.
+> But ignoring obvious performance traps is just incompetence.
+
+## The Performance Prime Directive
+
+**Do NOT optimize without evidence.** CPU time is cheap. Developer time is expensive.
+
+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
+```
+## UNIVERSAL RULE: realtime.md
+Source: .agent-context/rules/realtime.md
+
+# Real-time & WebSockets Architecture
+
+> WebSockets are stateful tcp connections in a stateless HTTP world. Treat them with extreme caution.
+
+## 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.
+
+## 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.
+## UNIVERSAL RULE: security.md
+Source: .agent-context/rules/security.md
+
+# Security — Trust Nothing, Validate Everything
+
+> Every user is a potential attacker. Every input is a potential exploit.
+> You are not paranoid — you are professional.
+
+## The Zero Trust Input Rule
+
+**ALL data crossing a system boundary is untrusted until validated.**
+
+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 Data ──
+*.pid
+*.seed
+*.pid.lock
+
+# ── 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
+## UNIVERSAL RULE: testing.md
+Source: .agent-context/rules/testing.md
+
+# Testing — Prove It Works, Don't Pray
+
+> "It works on my machine" is not a test strategy.
+> Untested code is broken code that hasn't been caught yet.
+
+## The Test Pyramid (Enforced)
+
+```
+        ╱  E2E   ╲           Few — Slow — Expensive — Fragile
+       ╱──────────╲          Test critical user journeys only
+      ╱ Integration ╲        Medium — Test module boundaries
+     ╱────────────────╲      Database, API contracts, service interactions
+    ╱    Unit Tests     ╲    Many — Fast — Cheap — Stable
+   ╱──────────────────────╲  Test business logic in isolation
+```
+
+### Ratios
+- **Unit tests:** 70% — fast, isolated, test business rules
+- **Integration tests:** 20% — test boundaries (DB, APIs, modules)
+- **E2E tests:** 10% — test critical user flows only
+
+---
+
+## What to Test (And What Not To)
+
+### ✅ ALWAYS Test
+- Business logic and calculations
+- Input validation rules
+- Edge cases (empty arrays, null values, boundary numbers)
+- Error handling paths (what happens when things fail)
+- State transitions and workflows
+- Authorization rules
+
+### ❌ NEVER Test
+- Framework internals (don't test that Express routes work)
+- Simple getters/setters with no logic
+- Third-party library behavior
+- Private implementation details (test behavior, not structure)
+- Database migrations (verify schema, don't test the migration tool)
+
+---
+
+## Test Naming Convention
+
+### Pattern: `should [expected behavior] when [condition]`
+
+```
+❌ BANNED:
+test('test1')
+test('it works')
+test('calculateDiscount')
+
+✅ REQUIRED:
+test('should apply 20% discount when order total exceeds $100')
+test('should throw ValidationError when email format is invalid')
+test('should return empty array when user has no orders')
+test('should deny access when user lacks admin role')
+```
+
+**Rule:** A reader must understand the expected behavior WITHOUT reading the test body.
+
+---
+
+## Test Structure: AAA Pattern
+
+Every test follows **Arrange → Act → Assert**:
+
+```typescript
+test('should calculate shipping as free when order exceeds $50', () => {
+  // Arrange — Set up the scenario
+  const order = createOrder({ items: [{ price: 60, quantity: 1 }] });
+
+  // Act — Execute the behavior
+  const shippingCost = calculateShipping(order);
+
+  // Assert — Verify the outcome
+  expect(shippingCost).toBe(0);
+});
+```
+
+### Rules
+- **ONE assert concept per test** (multiple `expect` calls are fine if they test the same concept)
+- **No logic in tests** (no if/else, no loops, no try/catch)
+- **Tests must be independent** — no shared mutable state, no execution order dependency
+- **Tests must be deterministic** — same input = same result, every time
+
+---
+
+## Mocking Rules
+
+### Mock at Boundaries, Not Everywhere
+
+```
+❌ OVER-MOCKING (testing implementation, not behavior):
+test('should call repository.save exactly once', () => {
+  await service.createUser(userData);
+  expect(repository.save).toHaveBeenCalledTimes(1);
+  // If you refactor to call save differently, the test breaks
+  // even though the behavior hasn't changed
+});
+
+✅ CORRECT (testing behavior):
+test('should persist user and return created user', () => {
+  const result = await service.createUser(userData);
+  expect(result.id).toBeDefined();
+  expect(result.email).toBe(userData.email);
+  // You can verify the user exists in the test DB if integration test
+});
+```
+
+### When to Mock
+- External APIs (payment gateways, email services)
+- Time-dependent operations (use fake timers)
+- Non-deterministic operations (random, UUID)
+
+### When NOT to Mock
+- Your own code in the same module ← test the real integration
+- Simple utility functions ← use the real thing
+- Database in integration tests ← use a test database
+
+---
+
+## Test Data Standards
+
+### Use Factories, Not Copy-Pasted Objects
+
+```
+❌ BANNED:
+test('should calculate total', () => {
+  const order = {
+    id: '123',
+    userId: '456',
+    items: [{ productId: '789', price: 29.99, quantity: 2, name: 'Widget' }],
+    status: 'pending',
+    createdAt: new Date(),
+    updatedAt: new Date(),
+    // ... 15 more fields copied from another test
+  };
+});
+
+✅ REQUIRED:
+test('should calculate total', () => {
+  const order = createTestOrder({
+    items: [createTestItem({ price: 29.99, quantity: 2 })],
+  });
+  // Factory fills in all other fields with sensible defaults
+});
+```
+
+### Rules
+- Create factory functions for each domain entity
+- Factories provide sensible defaults — tests override only relevant fields
+- Never use production data in tests
+- Use descriptive, obviously-fake data (email: `test-user@example.com`, not `john@gmail.com`)
+
+---
+
+## Coverage Expectations
+
+| Layer | Min Coverage | What to Focus On |
+|-------|-------------|------------------|
+| Domain / Business Logic | 90%+ | All branching, edge cases, error paths |
+| Application / Service | 80%+ | Orchestration flows, error handling |
+| Transport / Controller | 60%+ | Input validation, error responses |
+| Utilities | 90%+ | All functions and edge cases |
+
+**Rule:** Coverage is a floor, not a goal. 100% coverage with bad tests is worse than 80% coverage with good tests. Focus on testing **behavior and edge cases**, not hitting a number.
+
+---
+
+## When to Skip Tests (Rare)
+
+You may skip tests ONLY for:
+- Prototype/spike code (must be labeled `// SPIKE: will be replaced`)
+- Pure UI layout (visual testing is better here — use Storybook/Chromatic)
+- Generated code (test the generator, not the output)
+
+Everything else gets tested. No excuses.
+## STACK PROFILE: typescript.md
+Source: .agent-context/stacks/typescript.md
+
+# TypeScript Stack Profile — The "Galak" Standard
+
+> TypeScript is not JavaScript with optional types.
+> It is a contract system. Use it like one.
+
+## Compiler Configuration (Non-Negotiable)
+
+### tsconfig.json Strict Settings
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "exactOptionalPropertyTypes": true,
+    "forceConsistentCasingInFileNames": true,
+    "isolatedModules": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "moduleResolution": "bundler",
+    "module": "ESNext",
+    "target": "ES2022",
+    "skipLibCheck": true,
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  }
+}
+```
+
+**Rule:** `"strict": true` is mandatory. If a project has `"strict": false`, fix it before writing any new code.
+
+---
+
+## The `any` Ban (Zero Tolerance)
+
+### Rule: `any` is BANNED. No exceptions.
+
+```typescript
+// ❌ INSTANT REJECTION
+function processData(data: any) { ... }
+const result = response.json() as any;
+// @ts-ignore
+// @ts-expect-error — only allowed with a comment explaining WHY and a linked issue
+
+// ✅ REQUIRED: Use `unknown` with type narrowing
+function processData(data: unknown) {
+  const parsed = DataSchema.parse(data);  // Zod validates and narrows
+  // `parsed` is now fully typed
+}
+
+// ✅ REQUIRED: Use generics when the type varies
+function getFirstItem<T>(items: T[]): T | undefined {
+  return items[0];
+}
+```
+
+### What to Use Instead of `any`
+| Situation | Instead of `any`, Use |
+|-----------|----------------------|
+| Unknown external data | `unknown` + Zod parsing |
+| Generic container | `T` (generic type parameter) |
+| Object with unknown keys | `Record<string, unknown>` |
+| Function argument you'll refine | `unknown` + type guard |
+| Library with bad types | Write a `.d.ts` override or `unknown` wrapper |
+| Event handlers | The specific event type (`MouseEvent`, `ChangeEvent<HTMLInputElement>`) |
+
+---
+
+## Zod at Boundaries (Mandatory)
+
+### Rule: ALL External Data MUST Pass Through Zod
+
+```typescript
+// ❌ BANNED: Trusting external data
+app.post('/users', async (req, res) => {
+  const { name, email, age } = req.body;  // Could be anything!
+  await userService.create({ name, email, age });
+});
+
+// ✅ REQUIRED: Validate with Zod at the boundary
+import { z } from 'zod';
+
+const CreateUserSchema = z.object({
+  name: z.string().min(1).max(100).trim(),
+  email: z.string().email().toLowerCase(),
+  age: z.number().int().min(13).max(150),
+});
+
+type CreateUserDto = z.infer<typeof CreateUserSchema>;
+
+app.post('/users', async (req, res) => {
+  const parsed = CreateUserSchema.safeParse(req.body);
+  if (!parsed.success) {
+    return res.status(400).json({ errors: parsed.error.flatten() });
+  }
+  // `parsed.data` is fully typed and validated
+  await userService.create(parsed.data);
+});
+```
+
+### Where Zod is MANDATORY
+- API request bodies (POST, PUT, PATCH)
+- Query parameters and path parameters
+- WebSocket incoming messages
+- Queue/event payloads from external systems
+- Environment variables at startup
+- Third-party API responses (trust but verify)
+- File upload metadata
+
+### Zod Best Practices
+```typescript
+// ✅ Reuse schemas — define once, use everywhere
+// src/modules/user/user.schema.ts
+export const UserSchema = z.object({
+  id: z.string().uuid(),
+  email: z.string().email(),
+  name: z.string().min(1).max(100),
+  role: z.enum(['user', 'admin', 'moderator']),
+  createdAt: z.coerce.date(),
+});
+
+export const CreateUserSchema = UserSchema.omit({ id: true, createdAt: true });
+export const UpdateUserSchema = CreateUserSchema.partial();
+
+// Types derived from schemas — single source of truth
+export type User = z.infer<typeof UserSchema>;
+export type CreateUserDto = z.infer<typeof CreateUserSchema>;
+export type UpdateUserDto = z.infer<typeof UpdateUserSchema>;
+```
+
+---
+
+## API Documentation (Mandatory)
+
+### Rule: No API Endpoint Exists Without Documentation
+
+Every API endpoint MUST have corresponding documentation. When creating or modifying an endpoint, you MUST simultaneously update the API documentation.
+
+### Preferred Approach: OpenAPI (Swagger)
+
+```typescript
+// Option 1: Code-first with decorators (NestJS)
+@ApiOperation({ summary: 'Create a new user' })
+@ApiBody({ type: CreateUserDto })
+@ApiResponse({ status: 201, description: 'User created', type: UserResponseDto })
+@ApiResponse({ status: 400, description: 'Validation error' })
+@ApiResponse({ status: 409, description: 'Email already exists' })
+@Post()
+async createUser(@Body() dto: CreateUserDto): Promise<UserResponseDto> { ... }
+
+// Option 2: Schema-first with Zod + zod-to-openapi
+import { extendZodWithOpenApi } from '@asteasolutions/zod-to-openapi';
+extendZodWithOpenApi(z);
+
+const CreateUserSchema = z.object({
+  name: z.string().min(1).openapi({ example: 'John Doe' }),
+  email: z.string().email().openapi({ example: 'john@example.com' }),
+}).openapi('CreateUserRequest');
+```
+
+### Documentation Checklist (Per Endpoint)
+- [ ] HTTP method and path
+- [ ] Request body schema (with examples)
+- [ ] Query/path parameter descriptions
+- [ ] All possible response codes with schemas
+- [ ] Authentication requirements
+- [ ] Rate limiting information (if applicable)
+
+### Documentation Must Stay in Sync
+```
+❌ BANNED:
+// Endpoint accepts `role` field but docs don't mention it
+// Endpoint returns 422 but docs only show 400
+
+✅ REQUIRED:
+// When you change an endpoint → update the schema/docs in the SAME commit
+// Use code-first tools so docs are generated from the actual types
+```
+
+---
+
+## Import Style
+
+### Path Aliases (Required)
+```typescript
+// ❌ BANNED: Deep relative imports
+import { UserService } from '../../../modules/user/user.service';
+import { AppError } from '../../../../shared/errors/app-error';
+
+// ✅ REQUIRED: Path aliases
+import { UserService } from '@/modules/user/user.service';
+import { AppError } from '@/shared/errors/app-error';
+```
+
+### Import Order (Enforced by ESLint)
+```typescript
+// 1. Node built-ins
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+// 2. External packages
+import { z } from 'zod';
+import { PrismaClient } from '@prisma/client';
+
+// 3. Internal modules (path aliases)
+import { UserService } from '@/modules/user/user.service';
+import { AppError } from '@/shared/errors/app-error';
+
+// 4. Relative imports (same module only)
+import { CreateUserDto } from './user.dto';
+import { UserRepository } from './user.repository';
+```
+
+---
+
+## Async Patterns
+
+### Rule: Prefer async/await Over Raw Promises
+```typescript
+// ❌ BANNED: Promise chain hell
+function getUser(id: string) {
+  return userRepo.findById(id)
+    .then(user => {
+      if (!user) throw new NotFoundError('User', id);
+      return orderRepo.findByUserId(user.id);
+    })
+    .then(orders => ({ ...user, orders }))
+    .catch(err => { throw err; });
+}
+
+// ✅ REQUIRED: Clean async/await
+async function getUser(id: string): Promise<UserWithOrders> {
+  const user = await userRepo.findById(id);
+  if (!user) throw new NotFoundError('User', id);
+
+  const orders = await orderRepo.findByUserId(user.id);
+  return { ...user, orders };
+}
+```
+
+### Parallel Execution
+```typescript
+// ❌ SLOW: Sequential when operations are independent
+const user = await getUser(id);
+const orders = await getOrders(id);
+const preferences = await getPreferences(id);
+
+// ✅ FAST: Parallel independent operations
+const [user, orders, preferences] = await Promise.all([
+  getUser(id),
+  getOrders(id),
+  getPreferences(id),
+]);
+```
+
+---
+
+## Enum and Union Types
+
+### Prefer `as const` Unions Over Enums
+```typescript
+// ⚠️ ACCEPTABLE but verbose:
+enum OrderStatus {
+  PENDING = 'pending',
+  CONFIRMED = 'confirmed',
+  SHIPPED = 'shipped',
+  DELIVERED = 'delivered',
+}
+
+// ✅ PREFERRED: const assertion + union type
+const ORDER_STATUSES = ['pending', 'confirmed', 'shipped', 'delivered'] as const;
+type OrderStatus = (typeof ORDER_STATUSES)[number];
+// OrderStatus = 'pending' | 'confirmed' | 'shipped' | 'delivered'
+
+// Works perfectly with Zod:
+const OrderStatusSchema = z.enum(ORDER_STATUSES);
+```
+
+---
+
+## Preferred Libraries (V1.0 — 2025)
+
+| Need | Library | Why |
+|------|---------|-----|
+| Runtime | Bun / Node 20+ | ESM native, fast, batteries-included |
+| Validation | `zod` | 0 deps, type inference, composable |
+| ORM | `prisma` or `drizzle-orm` | Type-safe queries, migration support |
+| HTTP framework | `hono` / `fastify` / Next.js | Lightweight, modern, tree-shakeable |
+| Testing | `vitest` | Vite-native, Jest-compatible API, fast |
+| Linting | `eslint` + `@typescript-eslint` | Community standard |
+| Formatting | `prettier` | Community standard |
+| Date | `date-fns` or `Temporal` (when stable) | Tree-shakeable, immutable |
+| HTTP client | `ky` / `ofetch` / built-in `fetch` | Lightweight, modern |
+| Password | `bcrypt` / `argon2` | Proven, secure |
+| Logger | `pino` | Fastest JSON logger for Node.js |
+| Env | `@t3-oss/env-core` + Zod | Type-safe env validation |
+
+---
+
+## Banned Patterns
+
+| Pattern | Why | Alternative |
+|---------|-----|-------------|
+| `any` type | Defeats TypeScript's purpose | `unknown` + narrowing |
+| `// @ts-ignore` | Hides real type errors | Fix the type or `@ts-expect-error` with comment |
+| `var` keyword | Function scoping bugs | `const` (default) or `let` |
+| `==` loose equality | Type coercion surprises | `===` always |
+| `console.log` in production | Not structured, not configurable | Use `pino` or structured logger |
+| `new Date()` without timezone | Timezone bugs | Explicit UTC or use date-fns |
+| Default exports | Naming inconsistency across imports | Named exports only |
+| Barrel re-exports (`index.ts`) | Circular dependency magnets | Direct imports or module public API only |
+| `moment.js` | Deprecated, massive bundle | `date-fns` or `dayjs` |
+| `class` with inheritance (deep chains) | Fragile hierarchies | Composition + interfaces |
+## BLUEPRINT PROFILE: api-nextjs.md
+Source: .agent-context/blueprints/api-nextjs.md
+
+# Blueprint: Next.js API Project (App Router)
+
+> This blueprint defines how to scaffold a Next.js API project from scratch.
+> Follow this structure exactly. Do not deviate.
+
+## Tech Stack
+- **Runtime:** Node.js 20+ / Bun
+- **Framework:** Next.js 14+ (App Router)
+- **Validation:** Zod
+- **ORM:** Prisma (or Drizzle)
+- **Auth:** NextAuth.js v5 / Lucia Auth
+- **Testing:** Vitest
+
+## Project Structure
+
+```
+project-name/
+├── src/
+│   ├── app/                            # Next.js App Router
+│   │   ├── api/                        # API routes
+│   │   │   ├── auth/
+│   │   │   │   └── [...nextauth]/
+│   │   │   │       └── route.ts        # Auth handler
+│   │   │   ├── users/
+│   │   │   │   ├── route.ts            # GET /api/users, POST /api/users
+│   │   │   │   └── [id]/
+│   │   │   │       └── route.ts        # GET/PUT/DELETE /api/users/:id
+│   │   │   └── health/
+│   │   │       └── route.ts            # GET /api/health
+│   │   ├── layout.tsx                  # Root layout
+│   │   └── page.tsx                    # Root page
+│   │
+│   ├── modules/                        # Feature modules (domain-driven)
+│   │   ├── user/
+│   │   │   ├── user.service.ts         # Business logic
+│   │   │   ├── user.repository.ts      # Data access
+│   │   │   ├── user.schema.ts          # Zod schemas + DTOs
+│   │   │   ├── user.types.ts           # Type definitions
+│   │   │   └── __tests__/
+│   │   │       └── user.service.test.ts
+│   │   └── order/
+│   │       ├── order.service.ts
+│   │       ├── order.repository.ts
+│   │       ├── order.schema.ts
+│   │       └── order.types.ts
+│   │
+│   ├── shared/                         # Cross-cutting concerns
+│   │   ├── config/
+│   │   │   └── env.ts                  # Zod-validated environment variables
+│   │   ├── errors/
+│   │   │   ├── app-error.ts            # Base error class
+│   │   │   └── error-handler.ts        # Global error handler for API routes
+│   │   ├── middleware/
+│   │   │   ├── auth.ts                 # Auth middleware
+│   │   │   └── validate.ts             # Request validation middleware
+│   │   ├── lib/
+│   │   │   ├── prisma.ts              # Prisma client singleton
+│   │   │   └── logger.ts              # Pino logger setup
+│   │   └── types/
+│   │       └── api.ts                  # Shared API types (ApiResponse, etc.)
+│   │
+│   └── components/                     # UI components (if full-stack)
+│       ├── ui/                         # Primitives
+│       └── layout/                     # Layout components
+│
+├── prisma/
+│   ├── schema.prisma                   # Database schema
+│   └── migrations/                     # Database migrations
+│
+├── public/                             # Static assets
+├── .env.example                        # Environment template
+├── .eslintrc.json                      # ESLint config
+├── .prettierrc                         # Prettier config
+├── next.config.mjs                     # Next.js config
+├── tsconfig.json                       # TypeScript config (strict!)
+├── vitest.config.ts                    # Vitest config
+└── package.json
+```
+
+## API Route Handler Pattern
+
+```typescript
+// src/app/api/users/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import { CreateUserSchema } from '@/modules/user/user.schema';
+import { userService } from '@/modules/user/user.service';
+import { handleApiError } from '@/shared/errors/error-handler';
+
+export async function GET(request: NextRequest) {
+  try {
+    const searchParams = request.nextUrl.searchParams;
+    const page = Number(searchParams.get('page') ?? '1');
+    const limit = Number(searchParams.get('limit') ?? '20');
+
+    const users = await userService.findAll({ page, limit });
+    return NextResponse.json({ data: users });
+  } catch (error) {
+    return handleApiError(error);
+  }
+}
+
+export async function POST(request: NextRequest) {
+  try {
+    const body = await request.json();
+    const parsed = CreateUserSchema.safeParse(body);
+
+    if (!parsed.success) {
+      return NextResponse.json(
+        { error: { code: 'VALIDATION_ERROR', details: parsed.error.flatten() } },
+        { status: 400 },
+      );
+    }
+
+    const user = await userService.create(parsed.data);
+    return NextResponse.json({ data: user }, { status: 201 });
+  } catch (error) {
+    return handleApiError(error);
+  }
+}
+```
+
+## Environment Validation Pattern
+
+```typescript
+// src/shared/config/env.ts
+import { z } from 'zod';
+
+const envSchema = z.object({
+  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
+  DATABASE_URL: z.string().url(),
+  NEXTAUTH_SECRET: z.string().min(32),
+  NEXTAUTH_URL: z.string().url(),
+  PORT: z.coerce.number().default(3000),
+});
+
+export const env = envSchema.parse(process.env);
+export type Env = z.infer<typeof envSchema>;
+```
+
+## Error Handler Pattern
+
+```typescript
+// src/shared/errors/error-handler.ts
+import { NextResponse } from 'next/server';
+import { AppError } from './app-error';
+import { logger } from '@/shared/lib/logger';
+
+export function handleApiError(error: unknown): NextResponse {
+  if (error instanceof AppError) {
+    logger.warn('Application error', {
+      code: error.code,
+      message: error.message,
+      context: error.context,
+    });
+
+    return NextResponse.json(
+      { error: { code: error.code, message: error.message } },
+      { status: error.statusCode },
+    );
+  }
+
+  logger.error('Unhandled error', {
+    error: error instanceof Error ? error.message : String(error),
+    stack: error instanceof Error ? error.stack : undefined,
+  });
+
+  return NextResponse.json(
+    { error: { code: 'INTERNAL_ERROR', message: 'An unexpected error occurred' } },
+    { status: 500 },
+  );
+}
+```
+
+## Scaffolding Checklist
+
+When using this blueprint, verify:
+- [ ] `tsconfig.json` has `"strict": true` and all recommended flags
+- [ ] `.env.example` exists with ALL required variables (placeholder values only)
+- [ ] Prisma client is a singleton (not re-created per request)
+- [ ] All API routes use Zod validation at the boundary
+- [ ] Error handler is used in every route (no unhandled errors)
+- [ ] Logger is configured (not `console.log`)
+- [ ] Path aliases (`@/`) are configured in tsconfig AND next.config
+- [ ] API documentation is generated or maintained alongside routes
+## CI/CD GUARDRAILS: ci-github-actions.md
+Source: .agent-context/blueprints/ci-github-actions.md
+
+# Blueprint: GitHub Actions CI/CD Pipeline
+
+> Automate everything. Trust nothing. Ship with confidence.
+
+## Tech Stack
+
+| Layer | Tool |
+|-------|------|
+| CI/CD | GitHub Actions |
+| Runners | GitHub-hosted (ubuntu-latest) |
+| Caching | actions/cache, setup-node cache |
+| Security | OIDC for cloud auth, pinned action SHAs |
+| Artifacts | actions/upload-artifact |
+
+## Pipeline Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    PR / Push Trigger                      │
+├──────────┬──────────┬──────────┬──────────┬─────────────┬─────────────┤
+│   Lint   │  Build   │   Test   │ Security │   Docs      │  LLM Judge  │
+│ (ESLint/ │ (tsc /   │ (Vitest/ │ (Audit / │ (OpenAPI    │ (Checklist  │
+│  ruff)   │  build)  │  pytest) │  Trivy)  │  validate)  │ enforcement)│
+├──────────┴──────────┴──────────┴──────────┴─────────────┴─────────────┤
+│              Gate: All jobs must pass                     │
+├─────────────────────────────────────────────────────────┤
+│              Deploy (on main only)                       │
+│  Staging → Smoke Tests → Production (manual approval)   │
+└─────────────────────────────────────────────────────────┘
+```
+
+## Required Workflows
+
+### 1. CI Workflow (`ci.yml`)
+
+Runs on every PR and push to main.
+
+```yaml
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@<pin-sha>
+      - uses: actions/setup-node@<pin-sha>
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm run lint
+      - run: npm run type-check
+
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@<pin-sha>
+      - uses: actions/setup-node@<pin-sha>
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm run test -- --coverage
+      - uses: actions/upload-artifact@<pin-sha>
+        with:
+          name: coverage
+          path: coverage/
+
+  security:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@<pin-sha>
+      - run: npm audit --audit-level=high
+      # Add Trivy, CodeQL, or Snyk as needed
+
+  build:
+    needs: [lint, test, security]
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@<pin-sha>
+      - uses: actions/setup-node@<pin-sha>
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm run build
+      - uses: actions/upload-artifact@<pin-sha>
+        with:
+          name: build
+          path: dist/
+
+  llm-judge:
+    needs: [lint, test, security, build]
+    runs-on: ubuntu-latest
+    timeout-minutes: 12
+    env:
+      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+      GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
+      GITHUB_BASE_SHA: ${{ github.event.pull_request.base.sha }}
+      GITHUB_HEAD_SHA: ${{ github.sha }}
+    steps:
+      - uses: actions/checkout@<pin-sha>
+        with:
+          fetch-depth: 0   # Full history required for accurate git diff
+      - uses: actions/setup-node@<pin-sha>
+        with:
+          node-version: '22'
+      - name: Run LLM Judge
+        run: node scripts/llm-judge.mjs
+      - name: Upload LLM Judge machine report
+        if: always()
+        uses: actions/upload-artifact@<pin-sha>
+        with:
+          name: llm-judge-report
+          path: .agent-context/state/llm-judge-report.json
+```
+
+### 2. Deploy Workflow (`deploy.yml`)
+
+Runs on push to main (after CI passes).
+
+```yaml
+name: Deploy
+
+on:
+  workflow_run:
+    workflows: [CI]
+    types: [completed]
+    branches: [main]
+
+permissions:
+  id-token: write   # OIDC
+  contents: read
+
+jobs:
+  deploy-staging:
+    if: ${{ github.event.workflow_run.conclusion == 'success' }}
+    runs-on: ubuntu-latest
+    environment: staging
+    steps:
+      # Authenticate via OIDC — no static secrets
+      # Deploy to staging
+      # Run smoke tests against staging
+
+  deploy-production:
+    needs: deploy-staging
+    runs-on: ubuntu-latest
+    environment:
+      name: production
+      url: https://your-app.com
+    steps:
+      # Deploy to production
+      # Run health checks
+      # Notify team (Slack, Discord)
+```
+
+## Security Rules
+
+1. **Pin actions to commit SHA** — not `@v3`, not `@latest`
+2. **Use OIDC** for cloud provider auth — delete static credentials
+3. **Minimal permissions** — set `permissions:` at workflow level, least privilege
+4. **Never print secrets** — GitHub masks them in logs, but don't `echo` them
+5. **Restrict self-hosted runners** — ephemeral containers only, never persistent VMs
+6. **Require PR approval** for workflows from forks
+7. **Minimize prompt scope** — send diff + checklist only, never full secret-bearing config
+
+## LLM Judge Annotation Contract
+
+The judge emits a machine-friendly payload line and artifact that can be consumed by annotation scripts:
+
+- Log line: `JSON_REPORT: { ... }`
+- Artifact file: `.agent-context/state/llm-judge-report.json`
+- Normalized severity values: `critical`, `high`, `medium`, `low`
+- Override artifact path (optional): `LLM_JUDGE_OUTPUT_PATH`
+
+## Efficiency Rules
+
+1. **Cache dependencies** — `actions/cache` or setup-action built-in cache
+2. **Use concurrency** — cancel previous runs on the same branch
+3. **Set timeouts** — prevent stuck jobs from burning minutes
+4. **Matrix builds** for multi-platform/version testing
+5. **Reusable workflows** — centralize common pipelines in a `.github` repo
+6. **Skip unnecessary jobs** — use path filters for targeted CI
+
+```yaml
+# Example: Only run frontend tests when frontend code changes
+on:
+  push:
+    paths:
+      - 'src/frontend/**'
+      - 'package.json'
+```
+
+## Scaffolding Checklist
+
+When setting up GitHub Actions for a new project:
+
+- [ ] Create `.github/workflows/ci.yml` with lint, test, build, security
+- [ ] Create `.github/workflows/deploy.yml` with staging + production
+- [ ] Pin ALL third-party actions to commit SHA
+- [ ] Set `permissions: contents: read` at workflow level
+- [ ] Configure `concurrency` to cancel in-progress runs
+- [ ] Add `timeout-minutes` to every job
+- [ ] Set up caching for package manager
+- [ ] Configure environment protection rules for production
+- [ ] Create `.nvmrc` or `.tool-versions` for runtime version
+- [ ] Configure branch protection: require CI pass before merge
+- [ ] Add `llm-judge` job that evaluates PR against `pr-checklist.md`
+## CI/CD GUARDRAILS: ci-gitlab.md
+Source: .agent-context/blueprints/ci-gitlab.md
+
+# Blueprint: GitLab CI/CD Pipeline
+
+> Same principles as GitHub Actions, adapted for GitLab's pipeline model.
+
+## Tech Stack
+
+| Layer | Tool |
+|-------|------|
+| CI/CD | GitLab CI/CD |
+| Config | `.gitlab-ci.yml` |
+| Runners | Shared runners or dedicated (Docker executor) |
+| Registry | GitLab Container Registry |
+| Caching | GitLab CI cache (per-branch, per-job) |
+
+## Pipeline Architecture
+
+```yaml
+stages:
+  - validate    # Lint + type check
+  - test        # Unit + integration tests
+  - security    # Dependency audit + SAST
+  - build       # Compile, bundle, containerize
+  - judge       # LLM-as-a-Judge checklist gate
+  - deploy      # Staging → Production
+```
+
+## Pipeline Template (`.gitlab-ci.yml`)
+
+```yaml
+default:
+  image: node:22-alpine
+  cache:
+    key:
+      files: [package-lock.json]
+    paths: [node_modules/]
+    policy: pull-push
+
+stages:
+  - validate
+  - test
+  - security
+  - build
+  - judge
+  - deploy
+
+# ─── VALIDATE ───────────────────────────────────────────
+lint:
+  stage: validate
+  script:
+    - npm ci --prefer-offline
+    - npm run lint
+    - npm run type-check
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+    - if: '$CI_COMMIT_BRANCH == "main"'
+
+# ─── TEST ───────────────────────────────────────────────
+test:unit:
+  stage: test
+  script:
+    - npm ci --prefer-offline
+    - npm run test -- --coverage
+  coverage: '/All files\s*\|\s*(\d+\.?\d*)\s*\|/'
+  artifacts:
+    reports:
+      coverage_report:
+        coverage_format: cobertura
+        path: coverage/cobertura-coverage.xml
+    paths: [coverage/]
+    expire_in: 7 days
+
+test:integration:
+  stage: test
+  services:
+    - postgres:16-alpine
+  variables:
+    POSTGRES_DB: test_db
+    POSTGRES_USER: test_user
+    POSTGRES_PASSWORD: test_pass
+    DATABASE_URL: "postgresql://test_user:test_pass@postgres:5432/test_db"
+  script:
+    - npm ci --prefer-offline
+    - npm run test:integration
+
+# ─── SECURITY ───────────────────────────────────────────
+audit:
+  stage: security
+  script:
+    - npm audit --audit-level=high
+  allow_failure: false
+
+sast:
+  stage: security
+  # GitLab's built-in SAST template
+include:
+  - template: Security/SAST.gitlab-ci.yml
+
+# ─── BUILD ──────────────────────────────────────────────
+build:
+  stage: build
+  script:
+    - npm ci --prefer-offline
+    - npm run build
+  artifacts:
+    paths: [dist/]
+    expire_in: 1 day
+  rules:
+    - if: '$CI_COMMIT_BRANCH == "main"'
+
+# ─── LLM JUDGE ──────────────────────────────────────────
+llm:judge:
+  stage: judge
+  image: node:22-alpine
+  variables:
+    OPENAI_API_KEY: $OPENAI_API_KEY
+    ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY
+    GEMINI_API_KEY: $GEMINI_API_KEY
+    # CI_MERGE_REQUEST_DIFF_BASE_SHA and CI_COMMIT_SHA are set automatically
+    # by GitLab for merge request pipelines — no manual configuration needed.
+  before_script:
+    - git fetch --unshallow || true  # Ensure full history for git diff
+  script:
+    - node scripts/llm-judge.mjs
+  artifacts:
+    when: always
+    paths:
+      - .agent-context/state/llm-judge-report.json
+    expire_in: 7 days
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+
+# ─── DEPLOY ─────────────────────────────────────────────
+deploy:staging:
+  stage: deploy
+  environment:
+    name: staging
+    url: https://staging.example.com
+  script:
+    - echo "Deploy to staging"
+    # Add your deployment commands
+  rules:
+    - if: '$CI_COMMIT_BRANCH == "main"'
+
+deploy:production:
+  stage: deploy
+  environment:
+    name: production
+    url: https://example.com
+  script:
+    - echo "Deploy to production"
+    # Add your deployment commands
+  rules:
+    - if: '$CI_COMMIT_BRANCH == "main"'
+      when: manual  # Require manual approval
+  needs: [deploy:staging]
+```
+
+## Key Differences from GitHub Actions
+
+| Concern | GitHub Actions | GitLab CI |
+|---------|---------------|-----------|
+| Config file | `.github/workflows/*.yml` | `.gitlab-ci.yml` (single file) |
+| Jobs linkage | `needs:` | `stages:` (sequential) + `needs:` (DAG) |
+| Secrets | GitHub Secrets | CI/CD Variables (masked + protected) |
+| Caching | `actions/cache` | Built-in `cache:` directive |
+| Services | Docker Compose / service containers | `services:` directive |
+| Environments | Environment protection rules | Environment + `when: manual` |
+| Includes | Reusable workflows | `include:` with `template:` |
+
+## Security Rules
+
+1. **Protected variables** — mark secrets as Protected + Masked
+2. **Protected branches** — only deploy from protected branches
+3. **Include GitLab SAST/DAST** templates for automated scanning
+4. **Limit runner access** — use tags to route jobs to appropriate runners
+5. **Artifact expiration** — set `expire_in` on all artifacts
+6. **Limit LLM input scope** — send only merge diff + checklist context
+
+## Scaffolding Checklist
+
+- [ ] Create `.gitlab-ci.yml` with validate, test, security, build, deploy stages
+- [ ] Configure CI/CD variables for secrets (masked + protected)
+- [ ] Set up caching for package manager lockfile
+- [ ] Add coverage reporting with Cobertura format
+- [ ] Configure environments (staging, production) with manual approval
+- [ ] Include SAST template for security scanning
+- [ ] Set up merge request pipelines with `rules:`
+- [ ] Configure branch protection rules
+- [ ] Add `timeout` to long-running jobs
+- [ ] Use `needs:` for DAG optimization where possible
+- [ ] Add `llm:judge` stage that enforces `pr-checklist.md`
+
+## LLM Judge Annotation Contract
+
+For MR annotations and dashboards, parse either:
+
+- Log line: `JSON_REPORT: { ... }`
+- Artifact: `.agent-context/state/llm-judge-report.json`
+
+Severity values are normalized by the judge to: `critical`, `high`, `medium`, `low`.
+## SKILL PACK: Frontend
+Source: .agent-context/skills/frontend.md
+Default tier: advance
+Selected tier: advance
+Evidence: Frontend usability audit, accessibility checks, and visual regression output.
+
+# Frontend Skill Pack
+
+Default tier: `advance`
+
+## Purpose
+Deliver frontend experiences that are visually intentional, accessible, and efficient.
+
+## In Scope
+- UI architecture and component composition
+- Responsive layouts and breakpoints
+- Motion, animation, and interaction polish
+- Accessibility and keyboard flows
+- Conversion clarity and onboarding flow
+
+## Must-Have Checks
+- Feature-driven folder structure
+- Smart and dumb component separation
+- Server state and client state separation
+- Reduced-motion fallback
+- Accessibility baseline pass
+- Responsive behavior verified on mobile and desktop
+
+## Evidence
+- Usability audit result
+- Visual regression output
+- Accessibility checklist result
+- Release notes for motion and interaction changes
+
+## Fallback
+- If a feature cannot meet the advance tier, ship standard mode only as a temporary compatibility path.
+
+## SKILL PACK: Fullstack
+Source: .agent-context/skills/fullstack.md
+Default tier: advance
+Selected tier: advance
+Evidence: End-to-end tests, contract validation, and feature parity review.
+
+# Fullstack Skill Pack
+
+Default tier: `advance`
+
+## Purpose
+Coordinate frontend and backend delivery as a single product system.
+
+## In Scope
+- Feature slicing across UI and API boundaries
+- Shared validation contracts
+- End-to-end flows and release readiness
+- Performance, accessibility, and observability together
+
+## Must-Have Checks
+- Single feature directory with clear public API
+- Frontend and backend contracts aligned
+- End-to-end test coverage for critical paths
+- Release notes explain UX and API impact together
+
+## Evidence
+- Feature parity checklist
+- End-to-end test report
+- Contract validation output
+- Release artifact bundle
+
+## Fallback
+- Split delivery only when the feature boundary is explicit and the evidence bundle is still complete.
+
+## SKILL PACK: CLI
+Source: .agent-context/skills/cli.md
+Default tier: advance
+Selected tier: advance
+Evidence: CLI smoke tests, dry-run output, and automation-friendly reports.
+
+# CLI Skill Pack
+
+Default tier: `advance`
+
+## Purpose
+Create smart command-line workflows that guide users efficiently and safely.
+
+## In Scope
+- Interactive initialization and upgrade flows
+- Safe defaults and confirmation steps
+- Machine-readable output for automation
+- Validation and self-healing hooks
+- Cross-platform shell behavior
+
+## Must-Have Checks
+- Explicit command help and examples
+- Deterministic output format for automation
+- Safe destructive-action guards
+- Validation before mutation
+- Exit codes reflect success and failure clearly
+
+## Evidence
+- CLI smoke tests
+- Machine-readable report output
+- Upgrade dry-run output
+- Cross-platform execution notes
+
+## Fallback
+- Standard mode can remain available for compatibility, but advance is the default user experience.
+
+## STATE MAP: architecture-map.md
+Source: .agent-context/state/architecture-map.md
+
+# Architecture Map (State Awareness)
+
+> This file defines protected architectural boundaries for AI-assisted changes.
+
+## Boundary Classification
+
+| Module/Path Pattern | Criticality | Change Policy | Required Checks |
+|---------------------|-------------|---------------|-----------------|
+| `src/modules/payment/**` | critical | Must preserve transactional behavior and idempotency | Unit + integration + rollback test |
+| `src/modules/authentication/**` | critical | Never bypass auth guards or token validation | Security audit + integration tests |
+| `src/modules/**/repository/**` | high | Preserve query contracts and avoid N+1 regressions | Query plan review + performance audit |
+| `src/features/**` | medium | Keep UI contracts stable and avoid API drift | Component tests + contract checks |
+| `src/shared/**` | high | Backward compatibility required for public utilities | Cross-module usage validation |
+
+## Required Agent Behavior
+
+1. Before editing a `critical` area, load `.agent-context/review-checklists/security-audit.md` and `.agent-context/review-checklists/performance-audit.md`.
+2. For boundary-crossing changes, verify no circular dependencies are introduced (see `dependency-map.md`).
+3. Every critical-path change must include explicit risk notes in PR description.
+
+## Project-Specific Notes
+
+- Replace placeholder path patterns with your actual module map.
+- Mark payment, identity, and financial reconciliation flows as `critical`.
+- Keep this file updated whenever module ownership changes.
+## STATE MAP: dependency-map.md
+Source: .agent-context/state/dependency-map.md
+
+# Dependency Map (State Awareness)
+
+> This map documents allowed dependency direction to prevent circular references during refactors.
+
+## Layer Dependency Rules
+
+1. Transport layer may depend on Service layer.
+2. Service layer may depend on Domain contracts and Repository interfaces.
+3. Infrastructure layer may implement Repository interfaces.
+4. Domain layer must not depend on Transport or Infrastructure.
+
+## Module-Level Constraints
+
+| Source Module | Allowed Dependencies | Forbidden Dependencies |
+|---------------|----------------------|------------------------|
+| `authentication` | `shared`, `user` | `payment` internals |
+| `payment` | `shared`, `billing`, `notification` contracts | `authentication` internals |
+| `reporting` | `shared`, read-only repository ports | write-side service internals |
+| `frontend` | public API clients only | direct repository access |
+
+## Circular Dependency Guardrail
+
+When refactoring:
+
+1. Detect import graph changes before applying bulk edits.
+2. Reject any change introducing `A -> B -> A` cycles.
+3. Move shared contracts to `shared` module when two-way dependencies appear.
+
+## Project-Specific Notes
+
+- Replace sample modules with your real domain modules.
+- Keep this map synchronized with architecture decisions and ADRs.
+## REVIEW CHECKLIST: pr-checklist.md
+Source: .agent-context/review-checklists/pr-checklist.md
+
+# PR Checklist — The Quality Gate
+
+> Run this before declaring any task "done."
+> If ANY item fails, the task is NOT complete.
+
+## Instructions for Agent
+
+When asked to review code using this checklist, evaluate EVERY item below.
+For each failed item, provide a Reasoning Chain (see `.cursorrules` → Reasoning Clause).
+Output format:
+
+```
+## PR REVIEW RESULTS
+━━━━━━━━━━━━━━━━━━━
+
+✅ [Item] — Passes
+❌ [Item] — FAILS
+   📌 Rule: [rule file + section]
+   ❌ Problem: [specific issue found]
+   ✅ Fix: [what to change]
+
+VERDICT: PASS ✅ / FAIL ❌ (X/Y items passed)
+```
+
+---
+
+## The Checklist
+
+### 1. Naming (→ rules/naming-conv.md)
+- [ ] All variables are descriptive nouns (no `data`, `temp`, `val`, `x`)
+- [ ] All functions start with a verb (no `userData()`, `orderLogic()`)
+- [ ] All booleans use `is/has/can/should` prefix
+- [ ] Constants use SCREAMING_SNAKE_CASE with unit suffix
+- [ ] No single-letter variables (except `i` in classic for-loops)
+- [ ] File names follow the project's chosen convention consistently
+
+### 2. Architecture (→ rules/architecture.md)
+- [ ] No layer leaks (controllers don't query DB, services don't return HTTP responses)
+- [ ] Feature-based file organization (not technical grouping)
+- [ ] Dependencies flow inward (transport → service → repository)
+- [ ] Module boundaries respected (no reaching into another module's internals)
+- [ ] Domain layer has zero external dependencies
+
+### 3. Type Safety (→ stacks/typescript.md)
+- [ ] No `any` type anywhere (use `unknown` + narrowing)
+- [ ] No `// @ts-ignore` (use `@ts-expect-error` with justification comment)
+- [ ] All function return types are explicit
+- [ ] Zod schemas validate ALL external input at boundaries
+- [ ] Types derived from Zod schemas (single source of truth)
+
+### 4. Error Handling (→ rules/error-handling.md)
+- [ ] No empty catch blocks
+- [ ] No `catch(e) { console.log(e) }` without re-throw or recovery
+- [ ] Typed error classes used (not generic `new Error('...')`)
+- [ ] Error responses don't leak internal details to clients
+- [ ] Structured logging with context (traceId, userId, action)
+
+### 5. Security (→ rules/security.md)
+- [ ] All user input validated at boundaries (Zod/schema)
+- [ ] No SQL/command string concatenation with user input
+- [ ] No secrets hardcoded in source code
+- [ ] Auth checked server-side (not client-side only)
+- [ ] Error messages don't reveal internal system details
+- [ ] CORS configured (not `*` in production)
+
+### 6. Performance (→ rules/performance.md)
+- [ ] No N+1 queries (no queries inside loops)
+- [ ] All list queries have LIMIT/pagination
+- [ ] No `SELECT *` (only needed columns)
+- [ ] No synchronous I/O in async context
+- [ ] Cache has documented invalidation strategy (if caching used)
+
+### 7. Testing (→ rules/testing.md)
+- [ ] Business logic has unit tests
+- [ ] Test names follow `should [behavior] when [condition]`
+- [ ] Tests follow AAA pattern (Arrange → Act → Assert)
+- [ ] No implementation detail testing (test behavior, not structure)
+- [ ] Test data uses factories (no copy-pasted objects)
+
+### 8. Dependencies (→ rules/efficiency-vs-hype.md)
+- [ ] No new dependencies added without justification
+- [ ] No dependency that replaces < 20 lines of code
+- [ ] New packages checked for maintenance health
+- [ ] Bundle impact considered (frontend)
+
+### 9. Git (→ rules/git-workflow.md)
+- [ ] Commit messages follow Conventional Commits
+- [ ] No `console.log` debugging statements
+- [ ] No `// TODO` without a linked issue
+- [ ] No commented-out code blocks
+- [ ] `.env` not committed
+
+### 10. Documentation
+- [ ] API endpoints have OpenAPI/Swagger documentation
+- [ ] Complex business logic has comments explaining WHY
+- [ ] Public functions/methods have JSDoc/docstrings
+- [ ] README updated if new setup steps required