@ryuenn3123/agentic-senior-core 1.8.0

package/.agent-context/rules/error-handling.md

@@ -0,0 +1,234 @@
+# 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');
+}
+```

package/.agent-context/rules/event-driven.md

@@ -0,0 +1,226 @@
+# 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)

package/.agent-context/rules/frontend-architecture.md

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