@ryuenn3123/agentic-senior-core 1.8.0

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

@@ -0,0 +1,47 @@
+# 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.

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

@@ -0,0 +1,195 @@
+# 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
+
+---
+
+## 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
+- [ ] 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

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

@@ -0,0 +1,178 @@
+# 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.

package/.agent-context/stacks/csharp.md

@@ -0,0 +1,149 @@
+# C# / .NET Stack Profile — Modern C#, Minimal Ceremony
+
+> C# has evolved massively. Use the modern features.
+> If your code looks like it's from 2015, it's wrong.
+
+## Language Version: C# 14+ / .NET 10 LTS
+
+.NET 10 is the latest LTS release (November 2025, 3 years support). C# 14 ships with .NET 10. Use modern features: records, primary constructors, extension members, nullable reference types.
+
+### Nullable Reference Types (Mandatory)
+```xml
+<!-- In .csproj — ALWAYS enabled -->
+<PropertyGroup>
+    <Nullable>enable</Nullable>
+    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+</PropertyGroup>
+```
+
+### Records for DTOs and Value Objects
+```csharp
+// BANNED: Mutable class with manual properties
+public class UserDto {
+    public string Name { get; set; }
+    public string Email { get; set; }
+}
+
+// REQUIRED: Immutable record
+public record CreateUserRequest(string Name, string Email, int Age);
+public record UserResponse(Guid Id, string Name, string Email, DateTime CreatedAt);
+```
+
+### Primary Constructors (C# 12+)
+```csharp
+// Clean dependency injection
+public class UserService(IUserRepository userRepository, ILogger<UserService> logger)
+{
+    public async Task<UserResponse> CreateAsync(CreateUserRequest request)
+    {
+        logger.LogInformation("Creating user {Email}", request.Email);
+        var user = await userRepository.CreateAsync(request);
+        return user.ToResponse();
+    }
+}
+```
+
+---
+
+## Validation at Boundaries
+
+### Minimal API with FluentValidation
+```csharp
+public class CreateUserValidator : AbstractValidator<CreateUserRequest>
+{
+    public CreateUserValidator()
+    {
+        RuleFor(x => x.Name).NotEmpty().MaximumLength(100);
+        RuleFor(x => x.Email).NotEmpty().EmailAddress();
+        RuleFor(x => x.Age).InclusiveBetween(13, 150);
+    }
+}
+
+app.MapPost("/users", async (CreateUserRequest request, IValidator<CreateUserRequest> validator,
+    UserService userService) =>
+{
+    var validation = await validator.ValidateAsync(request);
+    if (!validation.IsValid)
+        return Results.ValidationProblem(validation.ToDictionary());
+
+    var user = await userService.CreateAsync(request);
+    return Results.Created($"/users/{user.Id}", user);
+});
+```
+
+---
+
+## Project Structure
+
+```
+ProjectName/
+├── src/
+│   ├── ProjectName.Api/                    # Presentation/Transport layer
+│   │   ├── Program.cs                      # Entry point + DI setup
+│   │   ├── Endpoints/
+│   │   │   ├── UserEndpoints.cs            # Minimal API route definitions
+│   │   │   └── OrderEndpoints.cs
+│   │   ├── Middleware/
+│   │   │   └── ExceptionMiddleware.cs
+│   │   └── appsettings.json
+│   │
+│   ├── ProjectName.Application/            # Business logic layer
+│   │   ├── Users/
+│   │   │   ├── UserService.cs
+│   │   │   ├── CreateUserRequest.cs        # DTOs / records
+│   │   │   └── UserResponse.cs
+│   │   └── Common/
+│   │       ├── AppError.cs
+│   │       └── IUnitOfWork.cs
+│   │
+│   ├── ProjectName.Domain/                 # Domain entities (no dependencies)
+│   │   ├── Entities/
+│   │   │   └── User.cs
+│   │   └── Interfaces/
+│   │       └── IUserRepository.cs          # Repository contracts
+│   │
+│   └── ProjectName.Infrastructure/         # Data access, external services
+│       ├── Persistence/
+│       │   ├── AppDbContext.cs              # EF Core DbContext
+│       │   └── UserRepository.cs           # Repository implementation
+│       ├── Migrations/
+│       └── DependencyInjection.cs          # Extension methods for DI
+│
+└── tests/
+    ├── ProjectName.UnitTests/
+    └── ProjectName.IntegrationTests/
+```
+
+---
+
+## Preferred Libraries
+
+| Need | Library | Why |
+|------|---------|-----|
+| Framework | ASP.NET Core 10 Minimal APIs | LTS, lightweight, OpenAPI 3.1, passkey auth |
+| ORM | EF Core 10 | LINQ, migrations, vector search, JSON types |
+| Validation | FluentValidation | Expressive, testable, separates concerns |
+| Testing | xUnit + NSubstitute + Testcontainers | Industry standard for .NET |
+| Logging | Serilog + structured sinks | Best structured logging for .NET |
+| API docs | Swashbuckle / NSwag | OpenAPI auto-generation |
+| Mapping | Mapster or manual extension methods | Mapster faster than AutoMapper |
+| HTTP client | `IHttpClientFactory` | Pooled, resilient, built-in |
+| Configuration | Options pattern + `IOptions<T>` | Type-safe, validated config |
+| Auth | ASP.NET Core Identity / JWT / Passkeys | Built-in passkey support in .NET 10 |
+| Cloud-native | .NET Aspire | Orchestration, observability, service defaults |
+
+---
+
+## Banned Patterns
+
+| Pattern | Why | Alternative |
+|---------|-----|-------------|
+| `Nullable` disabled | NRE everywhere | Always `<Nullable>enable</Nullable>` |
+| `dynamic` type | No compile-time safety | Generics or strong types |
+| Service Locator | Hidden dependencies | Constructor injection |
+| `async void` | Unhandled exceptions crash the app | `async Task` always |
+| `string.Format` for SQL | SQL injection | EF Core LINQ or parameterized |
+| AutoMapper overuse | Magic mapping hides bugs | Manual mapping or Mapster |
+| Throw in constructor | Breaks DI container | Factory methods or validation |
+| `static` classes for services | Untestable, no DI | Interface + DI registration |
+| Controllers with business logic | Layer leak | Thin controllers, services layer |