@ryuenn3123/agentic-senior-core 3.0.17 → 3.0.20

package/.agent-context/rules/efficiency-vs-hype.md

@@ -1,154 +1,16 @@
-# 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.
+# Dependency and Tooling Boundary
 
 ## Latest-Compatible-First Rule
 
-- Start from the latest stable compatible dependency version, not an outdated tutorial version.
-- If the framework has an official scaffolder or setup command that produces current defaults, prefer that path over manually assembling stale `package.json` entries one by one.
-- Only step down to an older dependency version after documenting the exact compatibility, runtime, platform, or ecosystem reason.
-- Treat release notes, official docs, and framework migration guides as the primary source of truth for dependency setup.
-
-## 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, why the standard library is insufficient, and why the chosen version is the latest stable compatible option.
-
-### 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 LLM may choose modern libraries and tooling when they fit the project. This rule does not prefer "no library" or any fixed dependency set.
 
----
-
-## 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]
-Version Source: [official docs, release notes, or framework reference]
-Lock-in Risk: [low/medium/high — how many files would it touch]
-Exit Strategy: [how to remove it if needed]
-Fallback Reason: [only required when not using the latest stable compatible version]
-```
-
----
-
-## Dependency Update Strategy
-
-1. **Start from latest stable compatible versions** — older versions need a written reason
-2. **Prefer official framework setup flows** when they yield newer, canonical dependency sets
-3. **Pin exact versions** in lockfiles (already default with package-lock.json, bun.lockb)
-4. **Review changelogs** before major updates — never blindly `npm update`
-5. **Update in isolation** — one dependency per PR, with tests passing
-6. **Security patches immediately** — don't wait for the sprint
-7. **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 ↓
+Before adding or recommending a dependency:
+- check current official docs, release notes, and setup guidance when the ecosystem decision matters
+- choose the latest stable compatible dependency version unless a project constraint blocks it
+- use the official scaffolder or setup command when it creates the current supported project shape
+- Only step down to an older dependency version after documenting the exact compatibility, runtime, platform, or ecosystem reason.
+- explain why the dependency improves maintainability, UX, performance, security, or delivery speed
+- avoid packages that are stale, thinly maintained, too heavy for the job, or added only because they are popular
+- keep dependency boundaries replaceable when the library would spread through many files
 
-Is there a well-maintained, lightweight, community-standard package?
-  → Yes → Install it, add justification comment
-  → No → Build a minimal internal implementation, consider vendoring
-```
+Reject offline dependency decisions, outdated tutorial versions, and trend choices that are not grounded in the current repo and brief.

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

@@ -1,234 +1,12 @@
-# Error Handling — Never Swallow, Always Context
+# Error Handling Boundary
 
-> A swallowed error is a silent production incident waiting to happen.
-> When it explodes at 3 AM, you won't know where to look.
+Use the target language and framework's normal error model. Do not invent a custom exception architecture from this repo.
 
-## The Three Commandments
+Reject these failure patterns:
+- swallowed errors
+- generic errors that erase the domain cause
+- client-facing leaks of stack traces, secrets, SQL, infrastructure details, or provider internals
+- retries without transient-failure evidence, limits, backoff, and a clear final outcome
+- logs that say only "something failed" without action, target, actor, or trace context
 
-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');
-}
-```
+At boundaries, validate early, return safe user-facing errors, and keep machine-readable error context for operators and callers.

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

@@ -1,226 +1,22 @@
-# Event-Driven Architecture — React to Facts, Don't Poll for Changes
+# Event Boundary
 
-> If your services are constantly asking "Did anything change?", your architecture is broken.
-> Events are the nervous system of a distributed system.
+Do not add event-driven architecture because it sounds modern. Use it only when the product or repo shows a real async boundary.
 
-## When to Use Event-Driven Architecture
+Use events when:
+- multiple independent consumers must react to the same fact
+- synchronous coupling would harm reliability, latency, or ownership
+- audit history, fan-out, or eventual consistency is a real requirement
+- the team can operate retries, monitoring, and failure recovery
 
-### 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
+Reject events when a direct call, database transaction, or simple module boundary is enough.
 
-### 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
+Hard rules:
+- events describe facts that already happened
+- payloads are versioned, typed, and documented
+- producers do not know consumer internals
+- consumers are idempotent
+- retries are bounded and dead-letter or recovery behavior is defined
+- transactional publishing uses an outbox or equivalent safety pattern when data consistency matters
+- event catalogs or docs identify producer, consumers, ownership, and schema evolution rules
 
----
-
-## 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)
+If event tooling is unresolved, the LLM must recommend a current project-fit broker or managed service from official docs before implementation.