kodelyth-ecc 1.7.0 → 1.7.1

package/.agent/rules/observability.md

@@ -1,390 +0,0 @@
----
-name: observability
-description: Production observability patterns — structured logging, distributed tracing, metrics, health checks, alerting, and error budgets. Build systems you can understand when they break. Powered by Kodelyth.
-origin: Kodelyth
----
-
-# Observability — See Everything in Production
-
-The three pillars of observability — Logs, Metrics, and Traces — plus health checks, alerting, and error budgets. Powered by Kodelyth.
-
-## When to Use
-
-- Setting up logging for a new service
-- Adding tracing to an API or background job
-- Designing a metrics + alerting strategy
-- Debugging a production issue you can't reproduce locally
-- Setting up health check endpoints
-- Building SLOs and error budgets
-
----
-
-## The Three Pillars
-
-```
-Logs    → What happened (events, errors, audit trail)
-Metrics → How much / how often (counts, rates, durations)
-Traces  → Why it was slow (request flow across services)
-```
-
-You need all three. Metrics tell you *something is wrong*. Traces tell you *where*. Logs tell you *why*.
-
----
-
-## Structured Logging
-
-### Never use console.log in production
-
-```typescript
-// BAD: Unstructured — impossible to query, filter, or alert on
-console.log("User logged in: " + userId)
-console.log("Error: " + error.message)
-
-// GOOD: Structured — every field is queryable
-logger.info("user.login", {
-  userId,
-  email: user.email,
-  ip: request.ip,
-  userAgent: request.headers["user-agent"],
-  durationMs: Date.now() - startTime,
-})
-
-logger.error("payment.charge.failed", {
-  userId,
-  orderId,
-  amount,
-  currency,
-  errorCode: error.code,
-  errorMessage: error.message,
-  stripeErrorType: error.type,
-})
-```
-
-### Log Levels — Use the Right Level
-
-```typescript
-logger.debug("cache.hit", { key, ttlRemaining })   // Dev only, verbose
-logger.info("order.created", { orderId, amount })  // Normal business events
-logger.warn("rate.limit.approaching", { userId, count, limit }) // Potential problem
-logger.error("db.query.failed", { query, error })  // Needs attention
-logger.fatal("service.crashed", { reason })        // Immediate action required
-```
-
-**Rule:** INFO is for things you'd want to search in production. DEBUG is noise you turn on temporarily.
-
-### TypeScript Logging Setup (Pino — fastest Node.js logger)
-
-```typescript
-// lib/logger.ts
-import pino from 'pino'
-
-export const logger = pino({
-  level: process.env.LOG_LEVEL ?? 'info',
-  base: {
-    service: 'api',
-    version: process.env.npm_package_version,
-    env: process.env.NODE_ENV,
-  },
-  // Pretty print in dev, JSON in production
-  transport: process.env.NODE_ENV === 'development'
-    ? { target: 'pino-pretty', options: { colorize: true } }
-    : undefined,
-})
-
-// Child logger with request context
-export function requestLogger(requestId: string, userId?: string) {
-  return logger.child({ requestId, userId })
-}
-```
-
-### Python Logging Setup (structlog)
-
-```python
-# lib/logging.py
-import structlog
-import logging
-
-structlog.configure(
-    processors=[
-        structlog.stdlib.filter_by_level,
-        structlog.stdlib.add_logger_name,
-        structlog.stdlib.add_log_level,
-        structlog.processors.TimeStamper(fmt="iso"),
-        structlog.processors.StackInfoRenderer(),
-        structlog.processors.format_exc_info,
-        structlog.processors.JSONRenderer(),
-    ],
-    wrapper_class=structlog.stdlib.BoundLogger,
-    context_class=dict,
-    logger_factory=structlog.stdlib.LoggerFactory(),
-)
-
-log = structlog.get_logger()
-
-# Usage:
-log.info("order.created", order_id=order_id, amount=amount, user_id=user_id)
-log.error("payment.failed", error=str(e), order_id=order_id)
-```
-
----
-
-## Metrics
-
-### Naming Convention
-
-```
-# Format: namespace_subsystem_name_unit
-http_requests_total              # counter
-http_request_duration_seconds    # histogram
-db_connections_active            # gauge
-cache_hits_total                 # counter
-cache_misses_total               # counter
-queue_depth_messages             # gauge
-payment_amount_dollars           # histogram
-```
-
-### Three Metric Types
-
-```typescript
-// Counter — only goes up (requests, errors, events)
-const requestsTotal = new Counter({
-  name: 'http_requests_total',
-  help: 'Total HTTP requests',
-  labelNames: ['method', 'route', 'status_code'],
-})
-requestsTotal.inc({ method: 'POST', route: '/api/orders', status_code: '201' })
-
-// Gauge — goes up and down (active connections, queue depth, memory)
-const activeConnections = new Gauge({
-  name: 'db_connections_active',
-  help: 'Active database connections',
-})
-activeConnections.set(pool.totalCount)
-
-// Histogram — distribution of values (latency, request size)
-const requestDuration = new Histogram({
-  name: 'http_request_duration_seconds',
-  help: 'HTTP request duration',
-  labelNames: ['method', 'route'],
-  buckets: [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5],
-})
-const end = requestDuration.startTimer({ method, route })
-// ... handle request ...
-end()  // records duration automatically
-```
-
-### The Four Golden Signals (Google SRE)
-
-```
-1. Latency    → How long do requests take? (p50, p95, p99)
-2. Traffic    → How many requests/sec?
-3. Errors     → What % of requests fail?
-4. Saturation → How full is the system? (CPU, memory, queue depth)
-```
-
-Alert on these four before anything else.
-
----
-
-## Distributed Tracing (OpenTelemetry)
-
-```typescript
-// setup/tracing.ts
-import { NodeSDK } from '@opentelemetry/sdk-node'
-import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
-import { Resource } from '@opentelemetry/resources'
-import { SEMRESATTRS_SERVICE_NAME } from '@opentelemetry/semantic-conventions'
-
-const sdk = new NodeSDK({
-  resource: new Resource({
-    [SEMRESATTRS_SERVICE_NAME]: 'payment-service',
-  }),
-  traceExporter: new OTLPTraceExporter({
-    url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT,
-  }),
-})
-
-sdk.start()  // call before importing anything else
-
-// Usage — spans are created automatically for HTTP requests
-// Add custom spans for important operations:
-import { trace } from '@opentelemetry/api'
-
-const tracer = trace.getTracer('payment-service')
-
-async function processPayment(orderId: string) {
-  const span = tracer.startSpan('payment.process')
-  span.setAttributes({ 'order.id': orderId })
-
-  try {
-    const result = await chargeCard(orderId)
-    span.setStatus({ code: SpanStatusCode.OK })
-    return result
-  } catch (error) {
-    span.setStatus({ code: SpanStatusCode.ERROR, message: error.message })
-    span.recordException(error)
-    throw error
-  } finally {
-    span.end()
-  }
-}
-```
-
----
-
-## Health Check Endpoints
-
-### Basic Structure
-
-```typescript
-// Every service must expose /health and /ready
-// /health  → is the process alive? (used by load balancer)
-// /ready   → is the process ready to serve traffic? (used by k8s)
-
-app.get('/health', (req, res) => {
-  res.json({ status: 'ok', uptime: process.uptime() })
-})
-
-app.get('/ready', async (req, res) => {
-  const checks = await Promise.allSettled([
-    checkDatabase(),
-    checkRedis(),
-    checkExternalApi(),
-  ])
-
-  const results = {
-    database: checks[0].status === 'fulfilled' ? 'ok' : 'error',
-    redis:    checks[1].status === 'fulfilled' ? 'ok' : 'error',
-    external: checks[2].status === 'fulfilled' ? 'ok' : 'error',
-  }
-
-  const allHealthy = Object.values(results).every(v => v === 'ok')
-
-  res.status(allHealthy ? 200 : 503).json({
-    status: allHealthy ? 'ready' : 'degraded',
-    checks: results,
-    timestamp: new Date().toISOString(),
-  })
-})
-```
-
----
-
-## Alerting — What to Alert On
-
-### Alert Design Rules
-
-```
-1. Alert on SYMPTOMS, not causes
-   BAD:  Alert when CPU > 80%
-   GOOD: Alert when p99 latency > 2s (the symptom users feel)
-
-2. Every alert must be actionable
-   BAD:  "High error rate" with no runbook
-   GOOD: "Error rate > 1% — check Datadog dashboard, likely DB issue"
-
-3. Alert on SLOs, not arbitrary thresholds
-   BAD:  Alert when error rate > 5% (where does 5% come from?)
-   GOOD: Alert when error budget burn rate > 2x (based on SLO math)
-
-4. Avoid alert fatigue
-   BAD:  50 alerts, most noise
-   GOOD: 5 alerts, all critical, all actionable
-```
-
-### The Four Alerts Every Service Needs
-
-```yaml
-# 1. High error rate
-alert: HighErrorRate
-expr: rate(http_requests_total{status_code=~"5.."}[5m]) /
-      rate(http_requests_total[5m]) > 0.01
-for: 2m
-annotations:
-  summary: "Error rate above 1% for 2 minutes"
-  runbook: "https://runbooks.example.com/high-error-rate"
-
-# 2. High latency
-alert: HighLatency
-expr: histogram_quantile(0.99, rate(http_request_duration_seconds_bucket[5m])) > 2
-for: 5m
-annotations:
-  summary: "p99 latency above 2s for 5 minutes"
-
-# 3. Service down
-alert: ServiceDown
-expr: up{job="my-service"} == 0
-for: 1m
-annotations:
-  summary: "Service has been down for 1 minute"
-
-# 4. High queue depth
-alert: QueueBacklog
-expr: queue_depth_messages > 10000
-for: 10m
-annotations:
-  summary: "Queue depth above 10k for 10 minutes — consumers may be stuck"
-```
-
----
-
-## Error Budgets & SLOs
-
-```
-SLO: Service Level Objective — the target you're trying to hit
-SLA: Service Level Agreement — the contract with consequences
-SLI: Service Level Indicator — the measurement
-
-Example:
-  SLO: 99.9% of requests succeed within 500ms over 30 days
-  SLI: (successful_requests_under_500ms / total_requests) over 30 days
-  Error budget: 0.1% of requests can fail = ~43 minutes of downtime/month
-```
-
-```typescript
-// Error budget calculation
-const sloTarget = 0.999           // 99.9%
-const errorBudget = 1 - sloTarget // 0.001 = 0.1%
-const minutesPerMonth = 30 * 24 * 60  // 43,200 minutes
-const allowedDowntime = errorBudget * minutesPerMonth  // 43.2 minutes
-
-// Burn rate alert: if you're consuming budget 2x faster than allowed
-const burnRateThreshold = 2
-// Alert if current_error_rate > burn_rate * (1 - slo_target)
-```
-
----
-
-## Correlation IDs — Connect Logs Across Services
-
-```typescript
-// Middleware: generate or propagate request ID
-app.use((req, res, next) => {
-  const requestId = req.headers['x-request-id'] as string
-    ?? crypto.randomUUID()
-
-  // Set on response so clients can reference it in support tickets
-  res.setHeader('x-request-id', requestId)
-
-  // Make available for the duration of the request
-  req.requestId = requestId
-  req.log = logger.child({ requestId })
-
-  next()
-})
-
-// Pass downstream to every service call
-async function callPaymentService(orderId: string, requestId: string) {
-  return fetch('https://payment-service/charge', {
-    headers: {
-      'x-request-id': requestId,  // ← propagate to child services
-      'Content-Type': 'application/json',
-    },
-    body: JSON.stringify({ orderId }),
-  })
-}
-```
-
----
-
-> Powered by Kodelyth — you can't fix what you can't see.

package/.agent/rules/patterns.md

@@ -1,50 +0,0 @@
----
-paths:
-  - "**/*.cs"
-  - "**/*.csx"
----
-# C# Patterns
-
-> This file extends [common/patterns.md](../common/patterns.md) with C#-specific content.
-
-## API Response Pattern
-
-```csharp
-public sealed record ApiResponse<T>(
-    bool Success,
-    T? Data = default,
-    string? Error = null,
-    object? Meta = null);
-```
-
-## Repository Pattern
-
-```csharp
-public interface IRepository<T>
-{
-    Task<IReadOnlyList<T>> FindAllAsync(CancellationToken cancellationToken);
-    Task<T?> FindByIdAsync(Guid id, CancellationToken cancellationToken);
-    Task<T> CreateAsync(T entity, CancellationToken cancellationToken);
-    Task<T> UpdateAsync(T entity, CancellationToken cancellationToken);
-    Task DeleteAsync(Guid id, CancellationToken cancellationToken);
-}
-```
-
-## Options Pattern
-
-Use strongly typed options for config instead of reading raw strings throughout the codebase.
-
-```csharp
-public sealed class PaymentsOptions
-{
-    public const string SectionName = "Payments";
-    public required string BaseUrl { get; init; }
-    public required string ApiKeySecretName { get; init; }
-}
-```
-
-## Dependency Injection
-
-- Depend on interfaces at service boundaries
-- Keep constructors focused; if a service needs too many dependencies, split responsibilities
-- Register lifetimes intentionally: singleton for stateless/shared services, scoped for request data, transient for lightweight pure workers

package/.agent/rules/performance.md

@@ -1,178 +0,0 @@
-# Performance & Cost Optimization
-
-## Budget-First Principle (CRITICAL)
-
-**Every token costs money. Every agent invocation costs money. Treat both as finite resources.**
-
-Match the model to the task complexity. Do not default to the heaviest model — that wastes money. Do not default to the lightest model on complex work — that wastes time and produces worse output. Pick the right tier for the actual task in front of you.
-
----
-
-## Model Selection by Platform
-
-### Claude Code (Anthropic Models)
-
-| Tier | Model | Task Examples |
-|---|---|---|
-| **Trivial** | Claude Haiku | Rename, format, autocomplete, write a single test, update a comment |
-| **Standard** | Claude Sonnet 4.6 | Build a component, write an API route, debug a bug, refactor a module — **most real coding work** |
-| **Maximum** | Claude Opus 4.6 | Architect a system, plan a large migration, analyze cross-cutting security issues, hardest problems |
-
-**Most sessions run on Sonnet 4.6.** Haiku is for genuinely trivial edits. Opus 4.6 is for decisions that would take a senior engineer an hour of deep thinking.
-
----
-
-### Google Antigravity — Approved Model Stack
-
-The approved stack is 4 models. **Gemini 3 Flash and GPT-OSS 120B are not used** — they are insufficient for production-grade, multi-language, 300B-scale work.
-
-| Tier | Model | Task Examples |
-|---|---|---|
-| **Standard** | Gemini 3.1 Pro (Low) | Build components, write API routes, server actions, debug rendering issues, write tests, everyday refactoring — **most real coding work** |
-| **Complex** | Gemini 3.1 Pro (High) | Deep multi-file reasoning, architecture decisions, hard bugs spanning many files, security audits, migration planning |
-| **Claude Standard** | Claude Sonnet 4.6 (Thinking) | When Claude agent behavior is needed, extended thinking on difficult problems, complex agent orchestration |
-| **Claude Maximum** | Claude Opus 4.6 (Thinking) | Hardest architectural decisions, maximum reasoning — use when Pro (High) and Sonnet both fall short |
-
-**Do not use:**
-- Gemini 3 Flash — insufficient depth for production work
-- GPT-OSS 120B (Medium) — not part of the Kodelyth ECC stack
-
----
-
-### Antigravity Task Mapping — Any Language, Any Scale
-
-| What you are doing | Right model |
-|---|---|
-| Building a React/Next.js component | Gemini 3.1 Pro (Low) |
-| Writing an API route or server action | Gemini 3.1 Pro (Low) |
-| Writing tests | Gemini 3.1 Pro (Low) |
-| Debugging a rendering or logic bug | Gemini 3.1 Pro (Low) |
-| Go service implementation | Gemini 3.1 Pro (Low) |
-| Python API endpoint | Gemini 3.1 Pro (Low) |
-| Kotlin Android feature | Gemini 3.1 Pro (Low) |
-| Rust systems code | Gemini 3.1 Pro (Low) |
-| Java Spring Boot service | Gemini 3.1 Pro (Low) |
-| Hard bug spanning 8+ files | Gemini 3.1 Pro (High) |
-| Auth system architecture | Gemini 3.1 Pro (High) |
-| Security audit across codebase | Gemini 3.1 Pro (High) |
-| Cross-service debugging | Gemini 3.1 Pro (High) |
-| Database schema and query design | Gemini 3.1 Pro (High) |
-| Migration planning (framework, language) | Gemini 3.1 Pro (High) |
-| Deep agent reasoning needed | Claude Sonnet 4.6 (Thinking) |
-| Complex multi-agent orchestration | Claude Sonnet 4.6 (Thinking) |
-| Hardest architectural decisions | Claude Opus 4.6 (Thinking) |
-| Problem that Pro (High) could not solve | Claude Opus 4.6 (Thinking) |
-
-**Gemini 3.1 Pro (High) vs (Low) — choose High when:**
-- Task spans 10+ files and requires cross-file reasoning
-- A bug has resisted Pro (Low)'s analysis
-- Security or compliance audit needs full codebase context
-- Architecture decision has significant long-term trade-offs
-- Migration involves complex dependency trees across the project
-
-**Claude Sonnet 4.6 (Thinking) — choose when:**
-- You need Claude-specific agent behaviors from ECC
-- The problem requires extended thinking beyond Gemini's reasoning
-- You are orchestrating multiple agents and need deep coordination logic
-
-**Claude Opus 4.6 (Thinking) — last resort:**
-- Only when Gemini 3.1 Pro (High) and Claude Sonnet 4.6 have both been tried and fallen short
-- Maximum reasoning on the hardest architectural problems
-- Never open with Opus on a task Pro (Low) can handle
-
----
-
-## Token Efficiency Rules
-
-### Keep Context Lean
-
-- Read only the function or section needed — never feed entire files when a targeted read works
-- Summarize long conversations before continuing deep sessions (`/compact` in Claude Code)
-- Avoid the last 20% of the context window for large operations — start a fresh session instead
-- Clear context between unrelated tasks — stale context adds noise and cost
-
-### Low-Context Tasks — safe at any point in a session
-
-- Single-file edits
-- Standalone utility creation
-- Documentation updates
-- Simple bug fixes
-- Writing a test for a function that already exists
-
-### High-Context Tasks — start fresh or compact first
-
-- Large-scale refactoring across many files
-- Feature implementation spanning multiple modules
-- Debugging complex multi-service interactions
-- Any task requiring reading 10+ files simultaneously
-
----
-
-## Agent Invocation Cost Discipline
-
-- **Don't spawn agents for trivial tasks** — a one-liner fix does not need a code-reviewer agent
-- **Batch related changes** before invoking a reviewer — review once after a logical unit of work, not after every single edit
-- **Use `async: true` for all non-blocking hooks** — never let a hook add latency to tool execution (Claude Code)
-- **Set hook timeouts aggressively** — hooks must complete in under 5 seconds; anything longer gets killed
-- **Disable hooks you don't use** (Claude Code):
-  ```bash
-  export ECC_DISABLED_HOOKS=kodelyth:smart-suggest,kodelyth:test-reminder
-  ```
-
----
-
-## Thinking Mode — Use Surgically
-
-Claude Sonnet 4.6 (Thinking) and Claude Opus 4.6 (Thinking) reserve large token budgets for internal reasoning. Gemini 3.1 Pro (High) activates deep reasoning mode. Both are expensive. Use deliberately.
-
-**Enable thinking / Pro (High) for:**
-- Architectural decisions with significant trade-offs
-- Security analysis of sensitive code paths
-- Debugging that has resisted standard analysis
-- Migration planning across a large, complex codebase
-
-**Stay on Pro (Low) for:**
-- Routine code generation
-- Documentation and comment updates
-- Standard refactoring with a clear path
-- Any task where the answer is immediately obvious from context
-
-**Claude Code — cap thinking budget to control cost:**
-```bash
-export MAX_THINKING_TOKENS=5000
-
-# Toggle extended thinking: Option+T (macOS) / Alt+T (Windows/Linux)
-```
-
-**Antigravity — select at model picker:**
-- Gemini 3.1 Pro (Low) = fast, capable, handles most work
-- Gemini 3.1 Pro (High) = deep reasoning mode, costs more
-- Claude Sonnet 4.6 (Thinking) = Claude agent behavior + thinking
-- Claude Opus 4.6 (Thinking) = maximum, last resort
-
----
-
-## Cost Tracking (Claude Code)
-
-The cost-tracker hook logs token usage per session to `~/.claude/logs/token-usage.jsonl`.
-
-```bash
-# Top 10 most expensive sessions
-cat ~/.claude/logs/token-usage.jsonl | jq -s 'sort_by(.tokens) | reverse | .[0:10]'
-
-# Average tokens per session
-cat ~/.claude/logs/token-usage.jsonl | jq -s '[.[].tokens] | add / length'
-```
-
-High-cost sessions signal one of three problems: wrong model selection, poor context hygiene, or over-spawning agents. Fix the habit, not just the session.
-
----
-
-## Build Troubleshooting
-
-Build errors are pattern-matching tasks, not deep reasoning tasks.
-
-1. Use **build-error-resolver** agent — Pro (Low) or Sonnet tier, not Opus
-2. Feed the exact error message, not the entire build log
-3. Fix one error at a time
-4. Verify after each fix before continuing

package/.agent/rules/security.md

@@ -1,58 +0,0 @@
----
-paths:
-  - "**/*.cs"
-  - "**/*.csx"
-  - "**/*.csproj"
-  - "**/appsettings*.json"
----
-# C# Security
-
-> This file extends [common/security.md](../common/security.md) with C#-specific content.
-
-## Secret Management
-
-- Never hardcode API keys, tokens, or connection strings in source code
-- Use environment variables, user secrets for local development, and a secret manager in production
-- Keep `appsettings.*.json` free of real credentials
-
-```csharp
-// BAD
-const string ApiKey = "sk-live-123";
-
-// GOOD
-var apiKey = builder.Configuration["OpenAI:ApiKey"]
-    ?? throw new InvalidOperationException("OpenAI:ApiKey is not configured.");
-```
-
-## SQL Injection Prevention
-
-- Always use parameterized queries with ADO.NET, Dapper, or EF Core
-- Never concatenate user input into SQL strings
-- Validate sort fields and filter operators before using dynamic query composition
-
-```csharp
-const string sql = "SELECT * FROM Orders WHERE CustomerId = @customerId";
-await connection.QueryAsync<Order>(sql, new { customerId });
-```
-
-## Input Validation
-
-- Validate DTOs at the application boundary
-- Use data annotations, FluentValidation, or explicit guard clauses
-- Reject invalid model state before running business logic
-
-## Authentication and Authorization
-
-- Prefer framework auth handlers instead of custom token parsing
-- Enforce authorization policies at endpoint or handler boundaries
-- Never log raw tokens, passwords, or PII
-
-## Error Handling
-
-- Return safe client-facing messages
-- Log detailed exceptions with structured context server-side
-- Do not expose stack traces, SQL text, or filesystem paths in API responses
-
-## References
-
-See skill: `security-review` for broader application security review checklists.