codex-genesis-harness 0.1.0 → 0.1.4

package/.codex/skills/genesis-performance-profiling/templates/load-test-config-template.md

@@ -0,0 +1,428 @@
+# Load Test Config Template
+
+Copy and customize this template for each new service or endpoint group. All three tools (k6, Artillery, Locust) are provided — use the one that matches your team's toolchain preference.
+
+---
+
+## k6 Load Test Script Template
+
+```javascript
+// load-test.js
+// Generated by genesis-performance-profiling
+// Service: [SERVICE_NAME]
+// Version: [APP_VERSION]
+// Generated: [DATE]
+
+import http from 'k6/http';
+import { sleep, check, group } from 'k6';
+import { Counter, Rate, Trend, Gauge } from 'k6/metrics';
+import { randomIntBetween, randomItem } from 'https://jslib.k6.io/k6-utils/1.4.0/index.js';
+
+// ─── Custom metrics ────────────────────────────────────────────────────────
+const customErrorRate   = new Rate('custom_errors');
+const endpointLatency   = new Trend('endpoint_latency', true);
+const activeUsers       = new Gauge('active_users');
+const requestsCompleted = new Counter('requests_completed');
+
+// ─── Configuration ─────────────────────────────────────────────────────────
+export const options = {
+  // MODIFY THESE VALUES to match your service's SLO targets
+  stages: [
+    { duration: '1m',  target: 1   },  // Smoke: validate connectivity
+    { duration: '2m',  target: 100 },  // Ramp-up to target concurrency
+    { duration: '10m', target: 100 },  // Peak: steady state at target
+    { duration: '2m',  target: 150 },  // Stress: push beyond target
+    { duration: '1m',  target: 0   },  // Ramp-down
+  ],
+
+  thresholds: {
+    // MODIFY THESE THRESHOLDS to match your SLO definitions
+    'http_req_duration':                     ['p(50)<50', 'p(95)<200', 'p(99)<500'],
+    'http_req_failed':                       ['rate<0.01'],
+    'custom_errors':                         ['rate<0.005'],
+    // Per-endpoint thresholds (add one per critical endpoint):
+    'http_req_duration{name:users-list}':    ['p(95)<150'],
+    'http_req_duration{name:user-detail}':   ['p(95)<100'],
+    'http_req_duration{name:create-order}':  ['p(95)<300'],
+    'http_req_duration{name:health}':        ['p(95)<50'],
+  },
+
+  // Global tags applied to all metrics (enables filtering in Grafana/Datadog)
+  tags: {
+    service:     __ENV.SERVICE_NAME     || 'unknown-service',
+    environment: __ENV.ENVIRONMENT      || 'staging',
+    version:     __ENV.APP_VERSION      || 'unknown',
+    test_type:   __ENV.TEST_TYPE        || 'load',
+    test_run_id: __ENV.TEST_RUN_ID      || `run-${Date.now()}`,
+  },
+
+  // Graceful stop: allow in-flight requests to complete before shutdown
+  gracefulStop: '30s',
+};
+
+// ─── Environment configuration ─────────────────────────────────────────────
+const CONFIG = {
+  baseUrl:   __ENV.BASE_URL   || 'https://api.staging.example.com',
+  authToken: __ENV.AUTH_TOKEN || '',
+  timeout:   __ENV.TIMEOUT    || '10s',
+};
+
+const DEFAULT_HEADERS = {
+  'Content-Type':  'application/json',
+  'Accept':        'application/json',
+  'Authorization': `Bearer ${CONFIG.authToken}`,
+};
+
+// ─── Test data sets ─────────────────────────────────────────────────────────
+// CUSTOMIZE: Replace with realistic test data for your service
+const USER_STATUSES = ['active', 'inactive', 'pending'];
+const PAGE_SIZES    = [10, 20, 50];
+const PRODUCT_IDS   = ['prod-001', 'prod-002', 'prod-003', 'prod-004', 'prod-005'];
+
+// ─── Setup ─────────────────────────────────────────────────────────────────
+export function setup() {
+  // Verify connectivity and get any dynamic test data
+  const res = http.get(`${CONFIG.baseUrl}/health`, { timeout: '5s' });
+  if (res.status !== 200) {
+    throw new Error(`Service not reachable. Status: ${res.status}. URL: ${CONFIG.baseUrl}/health`);
+  }
+  console.log(`✅ Service healthy. Starting load test against ${CONFIG.baseUrl}`);
+  
+  return {
+    baseUrl:   CONFIG.baseUrl,
+    startTime: Date.now(),
+  };
+}
+
+// ─── Main VU function ──────────────────────────────────────────────────────
+export default function(data) {
+  activeUsers.add(1);
+
+  group('User browsing journey', function() {
+    // Step 1: List users
+    const listStatus = randomItem(USER_STATUSES);
+    const listLimit  = randomItem(PAGE_SIZES);
+    
+    const listRes = http.get(
+      `${data.baseUrl}/api/users?status=${listStatus}&page=1&limit=${listLimit}`,
+      {
+        headers: DEFAULT_HEADERS,
+        tags:    { name: 'users-list' },
+        timeout: CONFIG.timeout,
+      }
+    );
+    
+    endpointLatency.add(listRes.timings.duration, { endpoint: 'users-list' });
+    requestsCompleted.add(1);
+
+    const listChecks = check(listRes, {
+      'users-list: status 200':     (r) => r.status === 200,
+      'users-list: has data array': (r) => {
+        try   { return Array.isArray(JSON.parse(r.body).data); }
+        catch { return false; }
+      },
+      'users-list: latency < 200ms': (r) => r.timings.duration < 200,
+    });
+    customErrorRate.add(!listChecks);
+
+    sleep(randomIntBetween(1, 2));
+
+    // Step 2: View user detail (if list returned results)
+    if (listRes.status === 200) {
+      try {
+        const body  = JSON.parse(listRes.body);
+        const users = body.data;
+        if (users && users.length > 0) {
+          const userId  = randomItem(users).id;
+          const detailRes = http.get(
+            `${data.baseUrl}/api/users/${userId}`,
+            {
+              headers: DEFAULT_HEADERS,
+              tags:    { name: 'user-detail' },
+              timeout: CONFIG.timeout,
+            }
+          );
+
+          endpointLatency.add(detailRes.timings.duration, { endpoint: 'user-detail' });
+          requestsCompleted.add(1);
+
+          check(detailRes, {
+            'user-detail: status 200':   (r) => r.status === 200,
+            'user-detail: latency < 100ms': (r) => r.timings.duration < 100,
+          });
+        }
+      } catch(e) {
+        console.error(`Failed to parse users list: ${e.message}`);
+      }
+    }
+
+    sleep(randomIntBetween(1, 3));
+  });
+
+  // Only 20% of VUs create orders (matches production traffic distribution)
+  if (Math.random() < 0.2) {
+    group('Order creation journey', function() {
+      const createRes = http.post(
+        `${data.baseUrl}/api/orders`,
+        JSON.stringify({
+          product_id: randomItem(PRODUCT_IDS),
+          quantity:   randomIntBetween(1, 5),
+        }),
+        {
+          headers: DEFAULT_HEADERS,
+          tags:    { name: 'create-order' },
+          timeout: CONFIG.timeout,
+        }
+      );
+
+      endpointLatency.add(createRes.timings.duration, { endpoint: 'create-order' });
+      requestsCompleted.add(1);
+
+      check(createRes, {
+        'create-order: status 201':       (r) => r.status === 201,
+        'create-order: has id':           (r) => {
+          try   { return !!JSON.parse(r.body).id; }
+          catch { return false; }
+        },
+        'create-order: latency < 300ms': (r) => r.timings.duration < 300,
+      });
+
+      sleep(2);
+    });
+  }
+
+  activeUsers.add(-1);
+}
+
+// ─── Teardown ──────────────────────────────────────────────────────────────
+export function teardown(data) {
+  const duration = (Date.now() - data.startTime) / 1000;
+  console.log(`Load test complete. Duration: ${duration.toFixed(0)}s`);
+}
+```
+
+---
+
+## Artillery YAML Config Template
+
+```yaml
+# artillery-config.yml
+# Generated by genesis-performance-profiling
+# Service: [SERVICE_NAME]
+# Generated: [DATE]
+
+config:
+  target: "https://api.staging.example.com"
+  
+  environments:
+    staging:
+      target: "https://api.staging.example.com"
+      phases:
+        - name: "Smoke"
+          duration: 60
+          arrivalRate: 1
+        - name: "Ramp-up"
+          duration: 120
+          arrivalRate: 1
+          rampTo: 50
+        - name: "Peak"
+          duration: 600
+          arrivalRate: 50
+        - name: "Ramp-down"
+          duration: 60
+          arrivalRate: 50
+          rampTo: 0
+          
+    production-canary:
+      target: "https://api.example.com"
+      phases:
+        - name: "Conservative canary"
+          duration: 300
+          arrivalRate: 5
+          
+  # Common phases (used when no environment specified)
+  phases:
+    - name: "Load test"
+      duration: 300
+      arrivalRate: 50
+
+  http:
+    timeout: 10
+    pool: 50
+    
+  defaults:
+    headers:
+      Content-Type: "application/json"
+      Accept: "application/json"
+      Authorization: "Bearer {{ $env.AUTH_TOKEN }}"
+
+  plugins:
+    expect: {}
+
+  ensure:
+    p95: 200
+    p99: 500
+    maxErrorRate: 1
+
+  # Variables available in scenarios
+  variables:
+    userStatuses:
+      - "active"
+      - "inactive"
+    pageSizes:
+      - 10
+      - 20
+      - 50
+
+scenarios:
+  - name: "Browse users"
+    weight: 40
+    flow:
+      - get:
+          url: "/api/users?status={{ userStatuses | random }}&page=1&limit={{ pageSizes | random }}"
+          expect:
+            - statusCode: 200
+            - contentType: json
+          capture:
+            - json: "$.data[0].id"
+              as: "firstUserId"
+      - think: 1
+      - get:
+          url: "/api/users/{{ firstUserId }}"
+          ifTrue: "firstUserId"
+          expect:
+            - statusCode: 200
+      - think: 2
+
+  - name: "Create and retrieve order"
+    weight: 20
+    flow:
+      - post:
+          url: "/api/orders"
+          json:
+            product_id: "prod-{{ $randomInt(1, 100) }}"
+            quantity: "{{ $randomInt(1, 5) }}"
+          expect:
+            - statusCode: 201
+          capture:
+            - json: "$.id"
+              as: "orderId"
+      - think: 1
+      - get:
+          url: "/api/orders/{{ orderId }}"
+          ifTrue: "orderId"
+          expect:
+            - statusCode: 200
+
+  - name: "Health check"
+    weight: 40
+    flow:
+      - get:
+          url: "/health"
+          expect:
+            - statusCode: 200
+```
+
+---
+
+## Environment-Specific Config Overrides
+
+```javascript
+// k6/configs/env-overrides.js
+// Import and spread into your main options object
+
+export const ENV_CONFIGS = {
+  local: {
+    baseUrl: 'http://localhost:3000',
+    stages: [
+      { duration: '30s', target: 5 },
+      { duration: '2m',  target: 5 },
+      { duration: '30s', target: 0 },
+    ],
+    thresholds: {
+      'http_req_duration': ['p(95)<500'],  // relaxed for local
+      'http_req_failed':   ['rate<0.05'],
+    },
+  },
+
+  staging: {
+    baseUrl: 'https://api.staging.example.com',
+    stages: [
+      { duration: '1m',  target: 1   },
+      { duration: '2m',  target: 100 },
+      { duration: '10m', target: 100 },
+      { duration: '1m',  target: 0   },
+    ],
+    thresholds: {
+      'http_req_duration': ['p(95)<250'],  // slightly relaxed vs prod
+      'http_req_failed':   ['rate<0.02'],
+    },
+  },
+
+  production: {
+    baseUrl: 'https://api.example.com',
+    stages: [
+      { duration: '2m',  target: 10  },  // Very conservative
+      { duration: '5m',  target: 10  },
+      { duration: '1m',  target: 0   },
+    ],
+    thresholds: {
+      'http_req_duration': ['p(95)<200'],
+      'http_req_failed':   ['rate<0.001'],  // strictest for production
+    },
+  },
+};
+
+// Usage in main script:
+// import { ENV_CONFIGS } from './configs/env-overrides.js';
+// const envName = __ENV.ENVIRONMENT || 'staging';
+// export const options = { ...ENV_CONFIGS[envName] };
+```
+
+---
+
+## CI/CD Integration
+
+```yaml
+# .github/workflows/perf-test.yml
+name: Performance Regression Test
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+jobs:
+  load-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Install k6
+        run: |
+          curl https://github.com/grafana/k6/releases/download/v0.50.0/k6-v0.50.0-linux-amd64.tar.gz -L | tar xvz --strip-components 1
+          sudo mv k6 /usr/local/bin/
+
+      - name: Run performance regression test
+        env:
+          BASE_URL:    ${{ vars.STAGING_URL }}
+          AUTH_TOKEN:  ${{ secrets.STAGING_AUTH_TOKEN }}
+          ENVIRONMENT: staging
+          APP_VERSION: ${{ github.sha }}
+        run: |
+          k6 run \
+            --out json=perf-results.json \
+            --env BASE_URL=$BASE_URL \
+            --env AUTH_TOKEN=$AUTH_TOKEN \
+            --env ENVIRONMENT=$ENVIRONMENT \
+            --env APP_VERSION=$APP_VERSION \
+            .codex/skills/genesis-performance-profiling/templates/load-test-script.js
+
+      - name: Upload results
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: perf-results-${{ github.sha }}
+          path: perf-results.json
+```

package/.codex/skills/genesis-performance-profiling/templates/performance-report-template.md

@@ -0,0 +1,238 @@
+# Performance Report Template
+
+Use this template to document every performance profiling cycle. Fill in every section — do not leave placeholders in a committed report. This document becomes the authoritative record of system performance at a point in time.
+
+---
+
+## Report Header
+
+```
+Performance Report
+==================
+Service:          [service name, e.g. "users-api"]
+Version:          [commit SHA or image tag, e.g. "abc1234"]
+Environment:      [environment name, e.g. "staging-isolated"]
+Test type:        [baseline | regression | optimization | incident]
+Report date:      [ISO 8601, e.g. "2026-05-31"]
+Report author:    [your name or "automated"]
+Baseline file:    [path to PERF_BASELINE.json, e.g. "observability/baselines/2026-05-31-v1.4.2.json"]
+Prior baseline:   [path to previous baseline if this is a comparison, or "N/A"]
+```
+
+---
+
+## Section 1: Baseline Capture Summary
+
+### Environment conditions at capture time
+
+| Condition | Value | Within normal? |
+|-----------|-------|----------------|
+| Background CPU utilization | X% | ✅ / ❌ (should be < 5%) |
+| Available memory | X MB | ✅ / ❌ (should be > 70% free) |
+| Database connection pool usage | X% | ✅ / ❌ (should be < 20% of max) |
+| Database row count (primary tables) | X rows | Reference only |
+| Cache state | warm / cold | Note if cold (first run after restart) |
+| Active background jobs | none / [list] | ✅ if none |
+| Network utilization (background) | X Mbps | ✅ / ❌ (should be < 10 Mbps) |
+| Number of instances / pods | X | Note for scaling context |
+
+### Run summary
+
+| Run # | p50 (ms) | p95 (ms) | p99 (ms) | RPS | Error rate | Status |
+|-------|---------|---------|---------|-----|-----------|--------|
+| Warm-up (discarded) | — | — | — | — | — | discarded |
+| Run 1 | | | | | | recorded |
+| Run 2 | | | | | | recorded |
+| Run 3 | | | | | | recorded |
+| Run 4 | | | | | | recorded |
+| Run 5 | | | | | | recorded |
+| **AVERAGE** | **XX** | **XX** | **XX** | **XX** | **XX%** | |
+| **VARIANCE (%)** | **X%** | **X%** | **X%** | **X%** | | ✅ if < 30% |
+
+### Per-endpoint baseline metrics
+
+| Endpoint | p50 (ms) | p95 (ms) | p99 (ms) | RPS | Error % | p95 SLA | SLA Status |
+|----------|---------|---------|---------|-----|---------|---------|-----------|
+| GET /api/users | | | | | | 200 ms | ✅/❌ |
+| GET /api/users/:id | | | | | | 200 ms | ✅/❌ |
+| POST /api/orders | | | | | | 300 ms | ✅/❌ |
+| GET /api/products | | | | | | 150 ms | ✅/❌ |
+| POST /auth/login | | | | | | 500 ms | ✅/❌ |
+
+### Memory profile
+
+| Measurement | Value |
+|-------------|-------|
+| Heap at test start (MB) | |
+| Heap at test end (MB) | |
+| Heap delta (MB) | |
+| RSS at test start (MB) | |
+| RSS at test end (MB) | |
+| Memory growth rate (MB/min) | |
+| Leak suspected? | YES / NO (threshold: > 5 MB/min = suspect) |
+
+---
+
+## Section 2: Test Results Analysis
+
+### Load test execution summary
+
+| Stage | Duration | Concurrency | Completed? | Notes |
+|-------|----------|-------------|-----------|-------|
+| Smoke | 1 min | 1 VU | YES/NO | |
+| Ramp-up | 2 min | 0 → X VUs | YES/NO | |
+| Peak | 5-30 min | X VUs | YES/NO | |
+| Stress (if run) | 5 min | 2X VUs | YES/NO | |
+| Ramp-down | 1 min | X → 0 VUs | YES/NO | |
+| Soak (if run) | 30 min | X VUs | YES/NO | |
+
+### Threshold results
+
+| Threshold | Configured | Actual | Result |
+|-----------|-----------|--------|--------|
+| `http_req_duration p(95)` | < 200 ms | X ms | ✅ PASS / ❌ FAIL |
+| `http_req_duration p(99)` | < 500 ms | X ms | ✅ PASS / ❌ FAIL |
+| `http_req_failed` | < 1% | X% | ✅ PASS / ❌ FAIL |
+| `http_reqs` (min throughput) | ≥ X RPS | X RPS | ✅ PASS / ❌ FAIL |
+
+### Observations during test
+
+Document any anomalies observed during the test execution:
+
+- **Latency spikes**: At [time into test], p95 spiked to X ms for approximately Y seconds. Cause: [known/unknown].
+- **Error bursts**: At [time into test], error rate spiked to X% for Y seconds. HTTP status codes observed: [list].
+- **Memory anomaly**: Memory grew from X MB to Y MB during [stage]. Drift rate: Z MB/min.
+- **Throughput drop**: RPS dropped from X to Y at [time]. Correlates with [event].
+- **External dependency issues**: [service] responded slowly / returned errors during [time period].
+
+---
+
+## Section 3: Before/After Comparison Table
+
+Use this section for regression detection reports. Fill in after running the after-baseline.
+
+### Summary
+
+```
+Before baseline: [path] captured [date] at version [X]
+After baseline:  [path] captured [date] at version [Y]
+Change context:  [description of what changed, e.g. "Added index on users.tenant_id, fixed N+1 query"]
+```
+
+### Metric delta table
+
+| Endpoint | Metric | Before | After | Delta | Delta % | Status |
+|----------|--------|--------|-------|-------|---------|--------|
+| GET /api/users | p50 ms | | | | | ✅/❌/⚠️ |
+| GET /api/users | p95 ms | | | | | ✅/❌/⚠️ |
+| GET /api/users | p99 ms | | | | | ✅/❌/⚠️ |
+| GET /api/users | RPS | | | | | ✅/❌/⚠️ |
+| GET /api/users | Error % | | | | | ✅/❌/⚠️ |
+| GET /api/users/:id | p50 ms | | | | | ✅/❌/⚠️ |
+| GET /api/users/:id | p95 ms | | | | | ✅/❌/⚠️ |
+| POST /api/orders | p95 ms | | | | | ✅/❌/⚠️ |
+
+**Legend:**
+- ✅ IMPROVEMENT: Latency decreased > 10% OR throughput increased > 10%
+- ❌ REGRESSION: Latency increased > 20% OR throughput decreased > 15% OR error rate increased
+- ⚠️ STABLE: Change within variance bounds (< 10% either direction)
+
+---
+
+## Section 4: Regression Flag Format
+
+For each regression detected, create one entry in this format:
+
+```
+REGRESSION DETECTED
+===================
+Endpoint:         GET /api/users
+Metric:           p95 latency
+Before value:     180 ms
+After value:      290 ms
+Delta:            +110 ms (+61.1%)
+Threshold:        +20% = REGRESSION
+Severity:         HIGH (exceeded SLA target of 200 ms)
+
+Root cause hypothesis:
+[Initial hypothesis — to be confirmed by profiling]
+Example: "Added full-text search query may be triggering seq scan on users table."
+
+Evidence:
+[What evidence supports this hypothesis?]
+Example: "pg_stat_statements shows new query with avg=110ms. Previous query avg=12ms."
+
+Recommended action:
+[Immediate recommended action]
+Example: "Add GIN index for full-text search. Revert or defer feature until index is in place."
+
+Blocking deployment? YES / NO
+[If YES, this must be resolved before the change can be merged/deployed]
+```
+
+---
+
+## Section 5: Optimization Recommendation Format
+
+For each identified bottleneck, create one entry:
+
+```
+OPTIMIZATION RECOMMENDATION
+============================
+ID:               PERF-2026-001
+Status:           OPEN / IN PROGRESS / IMPLEMENTED / CLOSED
+Priority:         P1 (Critical) / P2 (High) / P3 (Medium) / P4 (Low)
+
+Bottleneck:       [What is slow and where]
+Example: "N+1 query pattern in GET /api/users — executing 1 + N SELECT queries per request"
+
+Evidence:
+- pg_stat_statements: query "SELECT * FROM profiles WHERE user_id=$1" called 50× per /api/users request
+- EXPLAIN ANALYZE: Seq Scan on profiles table (50,000 rows per scan)
+- DB query time = 380 ms avg (84% of total response time of 450 ms)
+- Flame graph: 73% of CPU time in ORM hydration loop
+
+Recommended fix:
+[Specific, actionable fix]
+Example:
+1. Change ORM call from users.findAll() to users.findAll({ include: ['profile'] })
+   This replaces 1+N queries with a single LEFT JOIN query.
+2. Add index: CREATE INDEX CONCURRENTLY idx_profiles_user_id ON profiles(user_id);
+
+Estimated impact:       HIGH (expected p95 improvement: 300-370 ms, ~70-82% reduction)
+Implementation effort:  EASY (3 lines of ORM code + 1 migration)
+Risk:                   LOW (index creation is non-blocking with CONCURRENTLY)
+
+Validation method:
+1. Run after-baseline with this fix deployed.
+2. Confirm p95 ≤ 80 ms (well under 200 ms SLA).
+3. Confirm error rate unchanged.
+4. Check pg_stat_statements — N+1 query should no longer appear.
+
+Implemented in:   [PR # or commit SHA, filled in after implementation]
+After p95:        [measured after implementation]
+Improvement:      [% improvement achieved]
+Closed date:      [date when confirmed working in production]
+```
+
+---
+
+## Report Footer
+
+```
+OVERALL ASSESSMENT
+==================
+SLA compliance:   ALL PASS / X FAILS
+Regressions:      X detected (list IDs)
+Improvements:     X detected
+Open recommendations: X items (list IDs)
+Baseline updated: YES / NO (path: ...)
+PERF_LOG.md updated: YES / NO
+Next review:      [date, typically 1 sprint from now]
+
+Sign-off:
+[ ] Performance report reviewed by: ___________
+[ ] Regressions dispositioned (fixed or accepted): ___________
+[ ] PERF_LOG.md updated: ___________
+[ ] Recommendations assigned: ___________
+```