antigravity-ai-kit 3.2.0 → 3.4.0

package/.agent/skills/database-design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: database-design
-description: Database schema design and optimization patterns
+description: Database schema design, optimization patterns, distributed system consistency models, and zero-downtime migration strategies
 triggers: [context, database, schema, sql, prisma]
 ---
 
@@ -123,13 +123,13 @@ model User {
 ## Query Optimization
 
 ```typescript
-// ❌ N+1 Problem
+// N+1 Problem
 const users = await prisma.user.findMany();
 for (const user of users) {
   const orders = await prisma.order.findMany({ where: { userId: user.id } });
 }
 
-// ✅ Eager Loading
+// Eager Loading
 const users = await prisma.user.findMany({
   include: { orders: true },
 });
@@ -137,6 +137,155 @@ const users = await prisma.user.findMany({
 
 ---
 
+## CAP Theorem
+
+In a distributed system, you can guarantee at most two of three properties simultaneously:
+
+- **Consistency (C)**: Every read returns the most recent write
+- **Availability (A)**: Every request receives a response (no timeout)
+- **Partition Tolerance (P)**: The system continues operating despite network partitions
+
+Since network partitions are unavoidable in distributed systems, the real choice is between CP and AP.
+
+### Decision Matrix
+
+| Trade-off | Guarantees | Sacrifices | When to Choose | Example Systems |
+| :--- | :--- | :--- | :--- | :--- |
+| **CP** | Consistency + Partition Tolerance | Availability during partitions | Financial transactions, inventory counts, leader election | MongoDB (default), HBase, Zookeeper |
+| **AP** | Availability + Partition Tolerance | Consistency (eventual) | Social feeds, caching layers, DNS, session stores | Cassandra, DynamoDB, CouchDB |
+| **CA** | Consistency + Availability | Partition Tolerance | Single-node deployments only (no true distribution) | Traditional RDBMS (PostgreSQL, MySQL single-node) |
+
+---
+
+## ACID vs BASE
+
+### Property Comparison
+
+| Property | ACID | BASE |
+| :--- | :--- | :--- |
+| **Full name** | Atomicity, Consistency, Isolation, Durability | Basically Available, Soft state, Eventually consistent |
+| **Consistency** | Strong (immediate) | Eventual |
+| **Availability** | May block under contention | Prioritizes availability |
+| **Transactions** | Full multi-statement transactions | Single-record atomic ops; app-level sagas |
+| **Scaling** | Vertical first; horizontal is complex | Horizontal by design |
+| **Best for** | Financial systems, booking, inventory | Analytics, social, IoT, content delivery |
+
+### When to Use Each
+
+- **ACID**: Money movement, order processing, anything requiring rollback guarantees, regulatory compliance
+- **BASE**: High-throughput writes, geographically distributed reads, systems where stale reads are acceptable for seconds
+
+---
+
+## Consistency Models
+
+From strongest to weakest, choose the level your application actually needs:
+
+| Model | Guarantee | Latency Cost | Use Case |
+| :--- | :--- | :--- | :--- |
+| **Strict / Linearizable** | Reads always see the latest write globally | Highest (cross-region coordination) | Distributed locks, leader election |
+| **Sequential** | All nodes see operations in the same order | High | Replicated state machines |
+| **Causal** | Causally related operations are seen in order | Medium | Chat applications, collaborative editing |
+| **Read-your-writes** | A client always sees its own writes | Low-Medium | User profile updates, shopping carts |
+| **Monotonic reads** | Once a value is seen, older values are never returned | Low | Dashboard displays, reporting |
+| **Eventual** | All replicas converge given enough time | Lowest | DNS, CDN caches, social media likes |
+
+Choose the weakest model your application can tolerate to maximize performance and availability.
+
+---
+
+## Migration Safety
+
+### Zero-Downtime Migration Pattern
+
+Safe migrations follow a multi-phase approach that avoids locking tables or breaking running application code.
+
+**Phase 1 - Expand**: Add new structures alongside old ones
+**Phase 2 - Migrate**: Backfill data, dual-write to both structures
+**Phase 3 - Contract**: Remove old structures after all consumers have switched
+
+### Safe vs Unsafe Operations
+
+| Operation | Safe? | Zero-Downtime Alternative |
+| :--- | :--- | :--- |
+| **Add nullable column** | Safe | N/A (already safe) |
+| **Add column with default** | Safe (Postgres 11+) | For older versions, add nullable then backfill |
+| **Drop column** | Unsafe | Stop reading column in code first, then drop in next deploy |
+| **Rename column** | Unsafe | Add new column, dual-write, migrate reads, drop old |
+| **Change column type** | Unsafe | Add new column with new type, backfill, swap reads |
+| **Add NOT NULL constraint** | Unsafe | Add CHECK constraint as NOT VALID, then VALIDATE separately |
+| **Add index** | Unsafe (locks table) | Use `CREATE INDEX CONCURRENTLY` (Postgres) |
+| **Drop table** | Unsafe | Remove all references in code first, then drop |
+
+### Backfill Pattern
+
+```typescript
+// Backfill in batches to avoid long-running transactions
+async function backfillNewColumn(batchSize = 1000) {
+  let processed = 0;
+  let hasMore = true;
+
+  while (hasMore) {
+    const rows = await prisma.$executeRaw`
+      UPDATE users
+      SET display_name = first_name || ' ' || last_name
+      WHERE display_name IS NULL
+      LIMIT ${batchSize}
+    `;
+
+    processed += rows;
+    hasMore = rows === batchSize;
+
+    // Yield to other operations between batches
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+
+  return processed;
+}
+```
+
+---
+
+## Connection Pooling
+
+### Pool Size Guidance
+
+| Environment | Pool Size | Rationale |
+| :--- | :--- | :--- |
+| **Development** | 2-5 | Single developer, minimal concurrency |
+| **Production (server)** | 10-20 per instance | Balance between concurrency and DB connection limits |
+| **Production (serverless)** | 1-2 per function | Functions scale horizontally; too many connections exhaust DB limits |
+| **Staging / CI** | 3-5 | Mirrors production behavior without resource waste |
+
+### Sizing Formula
+
+```
+max_pool_size = (db_max_connections - reserved_superuser_connections) / number_of_app_instances
+```
+
+For PostgreSQL with `max_connections = 100`, 3 superuser slots reserved, and 4 app instances:
+`(100 - 3) / 4 = ~24 connections per instance`
+
+### Tool Recommendations
+
+| Tool | Best For | Notes |
+| :--- | :--- | :--- |
+| **PgBouncer** | External pooler for PostgreSQL | Transaction-mode pooling for serverless; sits between app and DB |
+| **Prisma built-in pool** | Prisma ORM users | Configure via `connection_limit` in datasource URL |
+| **Prisma Accelerate** | Serverless / edge | Managed connection pooling with global caching |
+| **RDS Proxy** | AWS deployments | Managed pooler; supports IAM auth and failover |
+| **Supabase Supavisor** | Supabase projects | Built-in pooler with transaction and session modes |
+
+```prisma
+// Prisma connection pool configuration
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL") // ?connection_limit=20&pool_timeout=10
+}
+```
+
+---
+
 ## Quick Reference
 
 | Pattern        | Usage               |
@@ -147,3 +296,8 @@ const users = await prisma.user.findMany({
 | Timestamps     | Always include      |
 | Indexes        | Frequent queries    |
 | Constraints    | Data integrity      |
+| CAP trade-off  | Distributed design  |
+| ACID           | Transactional data  |
+| BASE           | High-scale writes   |
+| Migrations     | Zero-downtime deploys |
+| Connection Pool | Right-size per env |

package/.agent/skills/plan-writing/domain-enhancers.md

@@ -12,11 +12,14 @@
 
 Include in plan:
 
-- **Accessibility (WCAG 2.1 AA)**: Identify components requiring ARIA labels, keyboard navigation, screen reader support, color contrast compliance
-- **Responsive Design**: Specify breakpoints to test (mobile 375px, tablet 768px, desktop 1280px), identify layout changes per breakpoint
-- **Bundle Size Impact**: Estimate size of new dependencies, identify tree-shaking opportunities, consider code splitting for new routes
-- **Core Web Vitals**: Assess impact on LCP (largest contentful paint), CLS (cumulative layout shift), INP (interaction to next paint)
-- **Component Composition**: Specify component hierarchy, prop interfaces, state management approach (local vs. global)
+- **Accessibility (WCAG 2.1 AA)**: Identify components requiring ARIA labels, keyboard navigation, screen reader support, color contrast compliance (minimum 4.5:1 normal text, 3:1 large text)
+- **Responsive Design**: Specify breakpoints to test (mobile 375px, tablet 768px, desktop 1280px), identify layout changes per breakpoint, verify touch targets (minimum 44x44px)
+- **Bundle Size Impact**: Estimate size of new dependencies, identify tree-shaking opportunities, consider code splitting for new routes, set bundle budget (initial JS < 200KB gzipped)
+- **Core Web Vitals**: Assess impact on LCP (< 2.5s), CLS (< 0.1), INP (< 200ms), identify render-blocking resources
+- **Component Composition**: Specify component hierarchy, prop interfaces, state management approach (local vs. global), identify shared components for extraction
+- **Rendering Strategy**: SSR vs CSR vs ISR decision for each route, hydration impact assessment, streaming SSR opportunities
+- **Design System Compliance**: Verify alignment with existing design tokens (colors, spacing, typography), identify new tokens required
+- **Error Boundaries**: Define error boundary placement, fallback UI for each failure mode, error reporting integration
 
 ---
 
@@ -26,11 +29,14 @@ Include in plan:
 
 Include in plan:
 
-- **API Contract**: Define request/response schemas (Zod validation), HTTP methods, status codes, error response format
-- **Error Handling**: Specify error response structure, error codes, client-facing messages vs. internal logging
-- **Rate Limiting**: Identify endpoints requiring rate limits, specify limits (requests/minute/user), throttling strategy
-- **Middleware Chain**: Document new middleware additions, execution order, impact on existing middleware stack
-- **Database Interaction**: Query patterns (parameterized), transaction boundaries, connection pooling impact
+- **API Contract**: Define request/response schemas (Zod validation), HTTP methods, status codes, error response format (RFC 7807 Problem Details), versioning strategy
+- **Error Handling**: Specify error response structure, error codes, client-facing messages vs. internal logging, error correlation IDs for tracing
+- **Rate Limiting**: Identify endpoints requiring rate limits, specify limits (requests/minute/user), throttling strategy (sliding window vs. token bucket), response headers (X-RateLimit-*)
+- **Middleware Chain**: Document new middleware additions, execution order, impact on existing middleware stack, short-circuit conditions
+- **Database Interaction**: Query patterns (parameterized), transaction boundaries, connection pooling impact, N+1 query prevention
+- **Input Validation**: Validation layer placement (controller vs. middleware), sanitization strategy, content-type enforcement, request size limits
+- **Idempotency**: Identify non-idempotent operations, implement idempotency keys for critical mutations, retry safety assessment
+- **Observability**: Structured logging format (JSON), request tracing headers (X-Request-ID propagation), health check endpoint specification
 
 ---
 
@@ -40,11 +46,14 @@ Include in plan:
 
 Include in plan:
 
-- **Migration Rollback**: Write both up and down migrations, test rollback procedure before deploying
-- **Index Impact Analysis**: Identify queries affected by schema changes, recommend index additions/removals, estimate query performance impact
-- **Data Integrity**: Define constraints (foreign keys, unique, not null, check), cascade behavior for deletions
-- **Backup Verification**: Verify backup exists before destructive migrations, test restore procedure for critical tables
-- **Query Performance**: Benchmark key queries before and after changes, set acceptable latency thresholds
+- **Migration Rollback**: Write both up and down migrations, test rollback procedure before deploying, zero-downtime migration pattern (expand-contract for schema changes)
+- **Index Impact Analysis**: Identify queries affected by schema changes, recommend index additions/removals, estimate query performance impact, verify composite index column order matches query patterns
+- **Data Integrity**: Define constraints (foreign keys, unique, not null, check), cascade behavior for deletions, domain invariant enforcement at database level
+- **Backup Verification**: Verify backup exists before destructive migrations, test restore procedure for critical tables, point-in-time recovery validation
+- **Query Performance**: Benchmark key queries before and after changes (EXPLAIN ANALYZE), set acceptable latency thresholds (p50 < 10ms, p99 < 100ms for OLTP), identify sequential scan risks
+- **Consistency Model**: Specify required consistency level (strong/eventual), transaction isolation level selection (Read Committed default, Serializable for financial), optimistic vs. pessimistic locking strategy
+- **Data Classification**: Identify PII columns requiring encryption at rest, data retention policy compliance, audit trail requirements for sensitive data mutations
+- **Connection Management**: Connection pool sizing for workload (pool_size = num_cores * 2 + disk_spindles), statement timeout configuration, idle connection cleanup
 
 ---
 
@@ -54,11 +63,14 @@ Include in plan:
 
 Include in plan:
 
-- **Infrastructure Changes**: Specify IaC modifications (Dockerfile, docker-compose, CI config), environment variable additions
-- **Monitoring & Alerting**: Define new metrics to track, alerting thresholds, dashboard updates
-- **Progressive Rollout**: Strategy for deployment (canary → staged → full), rollback triggers, health check endpoints
-- **Runbook Updates**: Document operational procedures for the new functionality, incident response steps
-- **Environment Parity**: Verify changes work across dev, staging, and production environments
+- **Infrastructure Changes**: Specify IaC modifications (Dockerfile, docker-compose, CI config), environment variable additions, 12-Factor App compliance check
+- **Monitoring & Alerting**: Define new metrics to track, alerting thresholds (SLO-derived), dashboard updates, golden signals coverage (latency, traffic, errors, saturation)
+- **Progressive Rollout**: Strategy for deployment (canary → staged → full), rollback triggers (error rate > 1%, latency p99 > 2x baseline), automated rollback criteria, health check endpoints
+- **Runbook Updates**: Document operational procedures for the new functionality, incident response steps, escalation paths
+- **Environment Parity**: Verify changes work across dev, staging, and production environments, configuration drift detection
+- **GitOps Compliance**: Infrastructure changes committed to version control, declarative configuration (desired state, not imperative scripts), automated drift reconciliation
+- **Container Security**: Base image selection (distroless/alpine preferred), multi-stage build optimization, no secrets in image layers, vulnerability scanning in CI
+- **Observability Pipeline**: Log aggregation configuration, trace sampling strategy, metric cardinality assessment, correlation between logs/traces/metrics
 
 ---
 
@@ -68,11 +80,14 @@ Include in plan:
 
 Include in plan (in addition to mandatory security considerations):
 
-- **Threat Model (STRIDE)**: Spoofing, Tampering, Repudiation, Information Disclosure, Denial of Service, Elevation of Privilege — assess each for the change
-- **Authentication Flow Impact**: How the change affects login, session management, token lifecycle
-- **Data Classification**: Identify data sensitivity levels (public, internal, confidential, restricted), storage and transmission requirements
-- **Compliance Requirements**: GDPR/CCPA implications (data minimization, consent, right to erasure)
-- **Secret Management**: New secrets required, rotation policy, storage mechanism (environment variables only)
+- **Threat Model (STRIDE)**: Spoofing, Tampering, Repudiation, Information Disclosure, Denial of Service, Elevation of Privilege — assess each for the change with severity rating
+- **Authentication Flow Impact**: How the change affects login, session management, token lifecycle, OAuth 2.0 flow selection (Authorization Code + PKCE for SPAs, Client Credentials for M2M)
+- **Data Classification**: Identify data sensitivity levels (public, internal, confidential, restricted), storage and transmission requirements per level
+- **Compliance Requirements**: GDPR/CCPA implications (data minimization, consent, right to erasure, breach notification within 72 hours)
+- **Secret Management**: New secrets required, rotation policy, storage mechanism (environment variables only), zero hardcoded credentials enforcement
+- **Zero Trust Assessment**: Authentication at every boundary (never trust, always verify), least privilege access for new endpoints/services, micro-segmentation for new network paths
+- **Supply Chain Security**: New dependency audit (license, maintainer, vulnerability scan), lockfile integrity verification, SRI hashes for CDN resources
+- **Input Boundary Defense**: All external inputs validated and sanitized, output encoding for context (HTML/URL/JS), parameterized queries only (no string concatenation)
 
 ---
 
@@ -82,11 +97,14 @@ Include in plan (in addition to mandatory security considerations):
 
 Include in plan:
 
-- **Performance Budget**: Define acceptable thresholds (page load time, API response time, memory usage)
-- **Profiling Strategy**: Tools and methods to measure before/after (Lighthouse, Chrome DevTools, load testing)
-- **Caching Strategy**: Cache layers (browser, CDN, application, database), TTL values, invalidation approach
-- **Lazy Loading**: Identify resources for deferred loading, intersection observer patterns, dynamic imports
-- **Benchmarking**: Define benchmark suite, baseline measurements, regression detection
+- **Performance Budget**: Define acceptable thresholds (LCP < 2.5s, FID < 100ms, page load < 3s, API p99 < 500ms, memory < 512MB per process)
+- **Profiling Strategy**: Tools and methods to measure before/after (Lighthouse, Chrome DevTools, load testing with k6/Artillery), baseline measurement requirements
+- **Caching Architecture**: Cache layers (browser → CDN → application → database), TTL values per layer, invalidation strategy (time-based, event-driven, version-key), cache stampede prevention (stale-while-revalidate, locking)
+- **Lazy Loading**: Identify resources for deferred loading, intersection observer patterns, dynamic imports for route-level code splitting, image loading strategy (responsive images, next-gen formats)
+- **Benchmarking**: Define benchmark suite, baseline measurements, regression detection thresholds, automated performance gates in CI
+- **Database Query Optimization**: EXPLAIN ANALYZE for new/modified queries, index coverage verification, N+1 detection, read replica routing for heavy reads
+- **Concurrency Model**: Event loop impact assessment, worker thread candidates for CPU-intensive operations, connection pool saturation risk
+- **CDN Strategy**: Edge caching rules for static assets, cache-control header specification, origin shield configuration, geographic distribution assessment
 
 ---
 
@@ -96,11 +114,61 @@ Include in plan:
 
 Include in plan:
 
-- **Platform Parity**: Identify iOS vs. Android differences in behavior, UI, or API access
-- **Offline Support**: Define offline behavior, data sync strategy, conflict resolution
-- **App Store Guidelines**: Compliance with Apple/Google review guidelines for the feature
-- **Native Modules**: Bridge requirements, native module dependencies, build configuration changes
-- **Device Testing**: Target device matrix, screen size variations, OS version compatibility
+- **Platform Parity**: Identify iOS vs. Android differences in behavior, UI, or API access, platform-specific code paths (#ifdef equivalent)
+- **Offline Support**: Define offline behavior, data sync strategy (optimistic vs. pessimistic), conflict resolution (last-write-wins, CRDT, manual merge), network-aware queries
+- **App Store Guidelines**: Compliance with Apple HIG and Material Design 3, review guideline risks, in-app purchase requirements
+- **Native Modules**: Bridge requirements, native module dependencies, build configuration changes (Podfile/build.gradle)
+- **Device Testing**: Target device matrix, screen size variations, OS version compatibility (minimum iOS 15 / Android API 26)
+- **Navigation Architecture**: Navigation pattern selection (stack, tab, drawer), deep linking support, back navigation handling per platform
+- **Mobile Performance Budget**: App startup time < 2s, frame rate 60fps minimum, memory usage < 150MB, APK/IPA size budget
+- **State Persistence**: Local storage strategy (AsyncStorage, SQLite, MMKV), state rehydration on app resume, background task handling
+
+---
+
+## Reliability Domain
+
+**Triggered when**: `reliability` domain matched (keywords: reliability, uptime, monitoring, sre, sla, slo, sli, etc.)
+
+Include in plan:
+
+- **SLO Definition**: Define Service Level Objectives for affected services (availability target, latency targets at p50/p95/p99, error rate budget)
+- **SLI Instrumentation**: Specify Service Level Indicators to measure (request success rate, request latency, system throughput), measurement method and data source
+- **Error Budget Impact**: Assess how the change affects existing error budgets, define acceptable error budget consumption for rollout
+- **Golden Signals**: Monitoring for all four golden signals (latency, traffic, errors, saturation) for new/modified services
+- **Resilience Patterns**: Circuit breaker placement, retry policy (exponential backoff with jitter), timeout configuration, bulkhead isolation for critical paths
+- **Incident Preparedness**: Runbook for new failure modes, alerting rules (page vs. ticket), escalation matrix, blast radius assessment
+- **Chaos Engineering**: Identify failure injection points for validation, steady-state hypothesis, abort conditions for chaos experiments
+- **Capacity Planning**: Resource requirements (CPU, memory, network, storage), scaling triggers (auto-scale thresholds), load testing validation for expected traffic growth
+
+---
+
+## Observability Domain
+
+**Triggered when**: `observability` domain matched (keywords: logging, tracing, metrics, monitoring, alerting, opentelemetry, etc.)
+
+Include in plan:
+
+- **Three Pillars Coverage**: Specify logging additions (structured JSON), metrics (counters, histograms, gauges), traces (span creation, context propagation)
+- **OpenTelemetry Integration**: SDK initialization, auto-instrumentation scope, manual span creation for business-critical paths, sampling strategy (head-based vs. tail-based)
+- **Log Architecture**: Log levels and when to use each (ERROR: actionable failures, WARN: degradation, INFO: business events, DEBUG: development only), structured fields, correlation ID propagation
+- **Alerting Strategy**: Alert conditions derived from SLOs, notification channels (PagerDuty/Slack), alert fatigue prevention (multi-window burn rate), silence/snooze policies
+- **Dashboard Design**: Key metrics visualization, RED method (Rate, Errors, Duration) per service, drill-down capability from overview to detail
+- **Cost Management**: Metric cardinality assessment, log volume projection, trace sampling rate optimization, retention policy per signal type
+
+---
+
+## Distributed Systems Domain
+
+**Triggered when**: `architecture` domain matched AND task involves multiple services, message queues, or event-driven patterns
+
+Include in plan:
+
+- **Consistency Strategy**: CAP theorem trade-off for the specific use case, consistency model selection (strong, eventual, causal), Saga pattern for distributed transactions (choreography vs. orchestration)
+- **Communication Pattern**: Synchronous (REST/gRPC) vs. asynchronous (message queue/event stream) decision per interaction, protocol selection criteria
+- **Fault Tolerance**: Failure mode analysis for each service interaction, fallback behavior, partial failure handling, data loss prevention
+- **Event-Driven Design**: Event schema definition (CloudEvents format), event ordering guarantees, idempotent consumers, dead letter queue strategy
+- **Service Discovery**: Registration mechanism, health check protocol, load balancing strategy (client-side vs. server-side), circuit breaker integration
+- **Data Sovereignty**: Which service owns which data, cross-service data access patterns (API calls, not shared databases), eventual consistency reconciliation
 
 ---
 
@@ -112,3 +180,5 @@ The planner reads this file when domain-specific sections are needed:
 2. For each matched domain, include the corresponding enhancer section
 3. Domain sections are added AFTER the base plan schema sections
 4. Multiple domains can be active simultaneously (e.g., frontend + backend for a full-stack feature)
+5. Each domain section contributes to the plan quality score (+2 bonus per matched domain section present, -2 penalty per missing)
+6. Domain enhancers leverage the specialized knowledge of their corresponding elevated agents (e.g., reliability domain draws from reliability-engineer's SRE Golden Signals framework)

package/.agent/skills/security-practices/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: security-practices
-description: Application security best practices and vulnerability prevention
+description: Application security best practices including Zero Trust principles, OAuth 2.0 / OpenID Connect flows, API security, supply chain security, and vulnerability prevention
 triggers: [context, security, auth, vulnerability]
 ---
 
@@ -21,7 +21,7 @@ This skill provides security guidelines following OWASP standards and industry b
 ### Password Security
 
 ```typescript
-// ✅ Use bcrypt with cost factor 12
+// Use bcrypt with cost factor 12
 import bcrypt from "bcrypt";
 
 const SALT_ROUNDS = 12;
@@ -55,20 +55,20 @@ const refreshToken = jwt.sign({ userId }, REFRESH_SECRET, { expiresIn: "7d" });
 ### Never Trust User Input
 
 ```typescript
-// ❌ SQL Injection vulnerable
+// SQL Injection vulnerable
 const query = `SELECT * FROM users WHERE id = ${userId}`;
 
-// ✅ Parameterized query
+// Parameterized query
 const user = await prisma.user.findUnique({ where: { id: userId } });
 ```
 
 ### Sanitize Output
 
 ```typescript
-// ❌ XSS vulnerable
+// XSS vulnerable
 element.innerHTML = userInput;
 
-// ✅ Escape HTML
+// Escape HTML
 import DOMPurify from "dompurify";
 element.innerHTML = DOMPurify.sanitize(userInput);
 ```
@@ -114,18 +114,194 @@ res.setHeader("Content-Security-Policy", "default-src 'self'");
 ## Secrets Management
 
 ```bash
-# ❌ Never commit secrets
+# Never commit secrets
 # .env file with API_KEY=sk-1234...
 
-# ✅ Use environment variables
+# Use environment variables
 export API_KEY=$(vault read secret/api-key)
 
-# ✅ Use secret managers
+# Use secret managers
 # AWS Secrets Manager, HashiCorp Vault, etc.
 ```
 
 ---
 
+## Zero Trust Principles
+
+Zero Trust assumes no implicit trust for any entity inside or outside the network perimeter. Every access request is fully authenticated, authorized, and encrypted before granting access.
+
+| Principle | Implementation | Verification |
+| :--- | :--- | :--- |
+| **Never trust, always verify** | Authenticate every request regardless of origin; treat internal traffic the same as external | Audit logs confirm no unauthenticated requests reach protected resources |
+| **Least privilege** | Grant minimum permissions required; use role-based and attribute-based access control | Periodic access reviews; automated permission drift detection |
+| **Assume breach** | Encrypt data at rest and in transit; segment blast radius; implement intrusion detection | Red team exercises; incident response drills validate containment |
+| **Micro-segmentation** | Isolate workloads with network policies; service mesh mTLS between microservices | Verify lateral movement is blocked between segments with penetration testing |
+| **Continuous validation** | Re-evaluate trust on every request; session tokens with short TTL; step-up auth for sensitive ops | Monitor for session hijacking; alert on anomalous access patterns |
+| **Device trust** | Require managed/compliant devices; verify device posture before granting access | Device compliance checks run at connection time and periodically |
+
+---
+
+## OAuth 2.0 / OpenID Connect Flows
+
+### Flow Selection Matrix
+
+| Client Type | Recommended Flow | Reason |
+| :--- | :--- | :--- |
+| **Web app (SPA)** | Authorization Code + PKCE | No client secret in browser; PKCE prevents interception |
+| **Web app (server)** | Authorization Code | Client secret stored server-side securely |
+| **Mobile / Desktop** | Authorization Code + PKCE | Public client; PKCE mandatory |
+| **Machine-to-Machine** | Client Credentials | No user interaction; service identity via client secret |
+| **Legacy (avoid)** | Implicit | Deprecated; tokens exposed in URL fragment |
+
+### Token Storage Requirements
+
+```typescript
+// NEVER store access tokens in localStorage (XSS-accessible)
+// NEVER store tokens in sessionStorage for long-lived sessions
+
+// Use httpOnly, Secure, SameSite cookies for refresh tokens
+res.cookie("refresh_token", token, {
+  httpOnly: true,
+  secure: true,
+  sameSite: "strict",
+  maxAge: 7 * 24 * 60 * 60 * 1000, // 7 days
+  path: "/api/auth/refresh",
+});
+
+// Keep access tokens in memory only (JS variable)
+// They are short-lived (15 min) and re-obtained via refresh
+```
+
+### PKCE Implementation
+
+```typescript
+import crypto from "crypto";
+
+// Generate code verifier (43-128 chars, unreserved URI characters)
+function generateCodeVerifier(): string {
+  return crypto.randomBytes(32).toString("base64url");
+}
+
+// Derive code challenge from verifier
+function generateCodeChallenge(verifier: string): string {
+  return crypto.createHash("sha256").update(verifier).digest("base64url");
+}
+
+// All public clients MUST use PKCE (RFC 7636)
+// Send code_challenge with authorization request
+// Send code_verifier with token exchange request
+```
+
+---
+
+## API Security
+
+### Rate Limiting Patterns
+
+| Strategy | Use Case | Example |
+| :--- | :--- | :--- |
+| **Per-endpoint** | Protect expensive operations | `/api/search`: 10 req/min |
+| **Per-user** | Fair usage enforcement | Authenticated: 1000 req/hr |
+| **Sliding window** | Smooth traffic spikes | Rolling 60s window, max 100 |
+| **Token bucket** | Burst tolerance | 10 tokens, refill 1/sec |
+| **IP-based** | Unauthenticated endpoints | Login: 5 attempts/15 min |
+
+```typescript
+import rateLimit from "express-rate-limit";
+
+const apiLimiter = rateLimit({
+  windowMs: 15 * 60 * 1000, // 15 minutes
+  max: 100,
+  standardHeaders: true,
+  legacyHeaders: false,
+  keyGenerator: (req) => req.user?.id ?? req.ip,
+});
+
+app.use("/api/", apiLimiter);
+```
+
+### API Key Management
+
+- **Rotate keys** on a regular schedule (90 days max) and immediately on suspected compromise
+- **Scope keys** to specific endpoints, methods, and IP ranges
+- **Never embed keys** in client-side code or version control
+- **Use separate keys** for each environment (dev, staging, production)
+- **Log key usage** to detect anomalous patterns
+
+### Request Signing
+
+```typescript
+// Sign requests with HMAC to prevent tampering
+import crypto from "crypto";
+
+function signRequest(payload: string, secret: string): string {
+  return crypto.createHmac("sha256", secret).update(payload).digest("hex");
+}
+
+// Verify on server side; reject requests with invalid or expired signatures
+// Include timestamp in signed payload to prevent replay attacks
+```
+
+### API Versioning Security
+
+- Deprecate and remove old API versions that lack current security controls
+- Apply the same authentication and authorization to all active versions
+- Monitor traffic to deprecated versions for potential abuse
+- Never maintain insecure legacy endpoints for backward compatibility
+
+---
+
+## Supply Chain Security
+
+### Dependency Auditing
+
+```bash
+# Run audit on every CI build
+npm audit --audit-level=high
+
+# Fix known vulnerabilities
+npm audit fix
+
+# Use lockfile-only installs in CI to prevent supply chain attacks
+npm ci
+```
+
+### Lockfile Integrity
+
+- **Always commit** `package-lock.json` to version control
+- **Use `npm ci`** in CI/CD pipelines (installs from lockfile exactly)
+- **Review lockfile diffs** in pull requests for unexpected changes
+- **Enable lockfile-lint** to enforce registry and integrity hash policies
+
+### Dependency Pinning
+
+```json
+{
+  "dependencies": {
+    "express": "4.18.2",
+    "prisma": "5.10.0"
+  }
+}
+```
+
+- Pin exact versions in production applications (no `^` or `~`)
+- Use Dependabot or Renovate for controlled, reviewed updates
+- Separate security patches from feature updates in dependency PRs
+
+### Typosquatting Detection
+
+| Technique | Example |
+| :--- | :--- |
+| **Character swap** | `expresss` instead of `express` |
+| **Hyphen confusion** | `lodash-utils` mimicking `lodash` |
+| **Scope squatting** | `@myorg/config` vs `@my-org/config` |
+
+- Verify package publisher and download counts before installing
+- Use `npm config set ignore-scripts true` for initial installs, then review scripts
+- Consider using Socket.dev or Snyk to detect malicious packages automatically
+
+---
+
 ## Quick Reference
 
 | Practice     | Implementation        |
@@ -138,3 +314,7 @@ export API_KEY=$(vault read secret/api-key)
 | Secrets      | Environment, vaults   |
 | Dependencies | npm audit, Snyk       |
 | Logging      | Audit trail, no PII   |
+| Zero Trust   | Verify every request  |
+| OAuth 2.0    | Auth Code + PKCE      |
+| API Keys     | Scoped, rotated       |
+| Supply Chain | Lockfile, pin deps    |

package/.agent/workflows/quality-gate.md

@@ -190,6 +190,7 @@ If any of these conditions are met, **REJECT** the task:
 
 ## Related Resources
 
+- **Rule**: `.agent/rules/quality-gate.md` (enforcement principles for this workflow)
 - **Previous**: `/brainstorm` (explore options before validation)
 - **Next**: `/plan` (implementation planning after approval)
 - **Related**: `/retrospective` (post-sprint audit applies similar rigor)