hatch3r 1.0.0

package/rules/hatch3r-observability.md

@@ -0,0 +1,165 @@
+---
+description: Logging, metrics, and tracing conventions for the project
+alwaysApply: false
+---
+# Observability
+
+## Structured Logging
+
+- Use structured JSON logging. No `console.log` in production code.
+- Log levels: `error` (failures), `warn` (degraded), `info` (state changes), `debug` (dev only).
+- Every log entry includes `correlationId` and `userId` (if available).
+- Never log secrets, PII, tokens, passwords, or sensitive content.
+- Instrument key operations with timing metrics. Serverless functions log execution time and outcome.
+- Client-side: log errors to a sink (e.g., error reporting service), not just `console.error`.
+- Prefer event-based metrics over polling. Trace user flows end-to-end with `correlationId`.
+- Respect performance budgets: logging must not add > 10ms latency to hot paths.
+- Include `service`, `environment`, and `version` fields in every log entry for filtering.
+- Use log sampling for high-volume debug logs in production (e.g., 1% sample rate).
+
+## Distributed Tracing
+
+- Use OpenTelemetry SDK for all tracing instrumentation. Initialize the TracerProvider once at application startup before any instrumented libraries load.
+- Propagate trace context via W3C Trace Context headers (`traceparent`, `tracestate`) across all service boundaries, queues, and async workflows.
+- Span naming conventions:
+
+| Span Type   | Pattern                        | Example                     |
+| ----------- | ------------------------------ | --------------------------- |
+| HTTP server | `HTTP {method} {route}`       | `HTTP GET /api/users/:id`   |
+| HTTP client | `HTTP {method} {host}{path}`  | `HTTP POST api.stripe.com/` |
+| DB query    | `{db.system} {operation}`     | `firestore getDoc`          |
+| Queue       | `{queue} {operation}`         | `tasks-queue publish`       |
+| Internal    | `{module}.{function}`         | `auth.verifyToken`          |
+
+- Required span attributes: `service.name`, `service.version`, `deployment.environment`. Add domain-specific attributes (e.g., `user.id`, `tenant.id`) where relevant.
+- Parent-child span relationships: every outbound call (HTTP, DB, queue) creates a child span of the current context. Never create orphan spans.
+- Sampling strategies: use `ParentBased(TraceIdRatioBased(0.1))` in production (10% sample rate). Always sample errors and slow requests (> p95 latency) at 100%.
+- Use the OpenTelemetry Collector as a gateway between applications and backends to enable batching, retrying, and vendor-neutral export.
+- Keep span event count low (< 32 per span). For high-volume events, use correlated logs or `SpanLink` instead.
+
+## Metrics
+
+- Use OpenTelemetry Metrics SDK. Expose Prometheus-compatible `/metrics` endpoint for scraping where applicable.
+- Metric naming: `{service}.{domain}.{metric}_{unit}` in snake_case. Example: `api.auth.login_duration_ms`.
+- Instrument types and when to use:
+
+| Instrument  | Use Case                           | Example                          |
+| ----------- | ---------------------------------- | -------------------------------- |
+| Counter     | Monotonically increasing totals    | `http.requests_total`            |
+| Histogram   | Distributions (latency, size)      | `http.request_duration_ms`       |
+| Gauge       | Point-in-time values               | `db.connection_pool_active`      |
+| UpDownCounter | Values that increase and decrease | `queue.messages_pending`         |
+
+- Histogram buckets for latency: `[5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000]` ms.
+- Cardinality management: never use unbounded values (user IDs, request paths with params) as metric labels. Cap label cardinality to < 100 unique values per metric.
+- Custom business metrics: track domain-significant events (sign-ups, purchases, feature usage) as counters with relevant dimensions.
+
+## SLO / SLI Definitions
+
+- Define SLIs as ratios of good events to total events, measured from the user's perspective.
+- Standard SLIs:
+
+| SLI              | Definition                                    | Measurement Source       |
+| ---------------- | --------------------------------------------- | ------------------------ |
+| Availability     | Requests returning non-5xx / total requests   | Load balancer logs       |
+| Latency          | Requests completing < threshold / total        | Tracing p99              |
+| Error rate       | Failed operations / total operations           | Application metrics      |
+| Freshness        | Data updated within SLA / total records        | Background job metrics   |
+
+- SLO targets: set per-service. Typical starting points: 99.9% availability (43 min/month budget), p99 latency < 500ms.
+- Error budgets: `budget = 1 - SLO_target`. Track remaining budget on a rolling 30-day window.
+- Burn rate alerts: use multi-window approach (short + long window). Fast-burn alert: 2% budget consumed in 1 hour. Slow-burn alert: 5% consumed in 6 hours. Alert only when both windows confirm.
+
+## Alerting
+
+| Severity | Criteria                            | Response Time | Notification       |
+| -------- | ----------------------------------- | ------------- | ------------------- |
+| P1       | Service down, data loss risk        | 15 min        | Page on-call + Slack |
+| P2       | Degraded performance, SLO at risk   | 1 hour        | Page on-call        |
+| P3       | Non-critical issue, workaround exists | Next business day | Slack channel  |
+| P4       | Cosmetic / low-impact               | Sprint backlog | Ticket only         |
+
+- Every alert must link to a runbook with: symptoms, likely causes, diagnostic steps, remediation actions.
+- Alert fatigue prevention: tune thresholds to < 5 actionable alerts per on-call shift. Suppress duplicate alerts within a 10-minute dedup window.
+- Route alerts by service ownership. Use escalation policies: if P1/P2 unacknowledged in 15 min, escalate to secondary.
+- Review alert quality monthly: snooze/delete alerts with < 20% action rate.
+
+## Structured Error Reporting
+
+- Integrate Sentry (or equivalent) for automated error capture in both server and client environments.
+- Configure release tracking: tag errors with `release` (git SHA or semver) and upload source maps for readable stack traces.
+- Enable breadcrumbs: capture the last 50 user actions, network requests, and console messages leading to an error.
+- Error grouping: use custom fingerprints for domain-specific errors to prevent over-grouping. Default fingerprinting is acceptable for unhandled exceptions.
+- Enrich error context with `correlationId`, `userId`, environment, and relevant business state. Never attach PII or secrets.
+- Set sample rates: 100% for errors, 10% for transactions in production. Adjust based on volume and budget.
+
+## Dashboard Standards
+
+- Required dashboards per service:
+
+| Dashboard        | Contents                                                    |
+| ---------------- | ----------------------------------------------------------- |
+| Service Health   | Request rate, error rate, latency p50/p95/p99, saturation   |
+| Business Metrics | Key domain counters, conversion funnels, feature adoption   |
+| Dependencies     | Upstream/downstream latency, error rates, circuit breaker state |
+| Infrastructure   | CPU, memory, disk, connection pools, queue depth            |
+
+- Dashboard-as-code: define dashboards in version-controlled JSON/YAML (Grafana provisioning, Terraform, or equivalent). No manual dashboard creation in production.
+- Every dashboard panel includes: descriptive title, unit labels, threshold lines for SLO targets, and a link to the relevant runbook or alert.
+- Review dashboards quarterly: remove unused panels, update thresholds, verify data source accuracy.
+
+## OpenTelemetry Semantic Conventions
+
+Follow the [OpenTelemetry Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/) (v1.29+) for consistent attribute naming across all telemetry signals. Semantic conventions ensure interoperability between instrumentation libraries, collectors, and observability backends.
+
+### Standard Attribute Namespaces
+
+| Namespace | Scope | Key Attributes |
+|-----------|-------|----------------|
+| `http.*` | HTTP client and server spans | `http.request.method`, `http.response.status_code`, `http.route`, `url.full`, `url.scheme` |
+| `db.*` | Database client spans | `db.system` (e.g., `postgresql`, `mongodb`), `db.operation.name`, `db.collection.name`, `db.query.text` (sanitized) |
+| `rpc.*` | RPC client and server spans | `rpc.system` (e.g., `grpc`, `jsonrpc`), `rpc.service`, `rpc.method`, `rpc.grpc.status_code` |
+| `messaging.*` | Message queue spans | `messaging.system` (e.g., `kafka`, `rabbitmq`), `messaging.operation.type` (`publish`, `receive`, `process`), `messaging.destination.name` |
+| `faas.*` | Serverless/FaaS invocations | `faas.trigger` (`http`, `pubsub`, `timer`), `faas.invoked_name`, `faas.coldstart` |
+| `cloud.*` | Cloud provider context | `cloud.provider`, `cloud.region`, `cloud.availability_zone`, `cloud.account.id` |
+| `k8s.*` | Kubernetes context | `k8s.namespace.name`, `k8s.pod.name`, `k8s.deployment.name`, `k8s.container.name` |
+
+- Use the semantic convention attribute names exactly as specified. Do not invent custom alternatives for concepts already covered by the conventions.
+- When semantic conventions are marked "Experimental," prefer them over project-specific names to ease future migration to stable conventions.
+
+### Resource Semantic Conventions
+
+Every telemetry-producing service must declare resource attributes at startup:
+
+| Attribute | Stability | Requirement | Description |
+|-----------|-----------|-------------|-------------|
+| `service.name` | Stable | Required | Logical name of the service (e.g., `api-gateway`, `auth-service`) |
+| `service.version` | Stable | Recommended | Semantic version of the service (e.g., `1.4.2`) |
+| `deployment.environment.name` | Stable | Recommended | Deployment environment (e.g., `production`, `staging`, `development`) |
+| `service.instance.id` | Experimental | Recommended | Unique instance identifier (e.g., pod name, container ID) |
+| `service.namespace` | Experimental | Optional | Namespace for grouping related services |
+| `telemetry.sdk.name` | Stable | Auto | Set by the SDK (e.g., `opentelemetry`) |
+| `telemetry.sdk.language` | Stable | Auto | Set by the SDK (e.g., `nodejs`, `python`) |
+| `telemetry.sdk.version` | Stable | Auto | Set by the SDK |
+
+- Configure `service.name` and `service.version` via environment variables (`OTEL_SERVICE_NAME`, `OTEL_RESOURCE_ATTRIBUTES`) or programmatically at SDK initialization.
+- Do not use the default `unknown_service` value in any deployed environment. Every service must have an explicit name.
+
+### Span Status Codes
+
+| Code | When to Set |
+|------|-------------|
+| `UNSET` | Default. The span completed without the instrumentation indicating an error. |
+| `OK` | Explicitly set only when the application considers the operation successful and wants to override any lower-level error signal. Use sparingly. |
+| `ERROR` | The operation failed. Set when an exception is caught, an HTTP response is 5xx, or a business-logic error occurs that should be visible in error rate metrics. |
+
+- Set span status to `ERROR` for server-side errors (5xx) and unhandled exceptions. Do not set `ERROR` for client errors (4xx) on the server span — those are valid responses, not server failures.
+- Attach the exception to the span as a span event (`exception.type`, `exception.message`, `exception.stacktrace`) when setting status to `ERROR`.
+- Use `OK` only when you want to suppress error signals from child spans. In most cases, leaving status as `UNSET` is correct.
+
+### Attribute Naming Guidelines
+
+- Use dot-separated namespaces: `http.request.method`, not `httpRequestMethod` or `http_request_method`.
+- Attribute values should be low-cardinality. Never use unbounded values (full URLs with query params, raw SQL, user-generated content) as attribute values.
+- For high-cardinality identifiers (user IDs, request IDs), use span attributes sparingly and rely on correlated logs for detail.
+- Prefer semantic convention attributes over custom attributes. When custom attributes are necessary, prefix them with your organization or project namespace (e.g., `myapp.feature.flag_key`).

package/rules/hatch3r-observability.mdc

@@ -0,0 +1,165 @@
+---
+description: Logging, metrics, and tracing conventions for the project
+alwaysApply: false
+---
+# Observability
+
+## Structured Logging
+
+- Use structured JSON logging. No `console.log` in production code.
+- Log levels: `error` (failures), `warn` (degraded), `info` (state changes), `debug` (dev only).
+- Every log entry includes `correlationId` and `userId` (if available).
+- Never log secrets, PII, tokens, passwords, or sensitive content.
+- Instrument key operations with timing metrics. Serverless functions log execution time and outcome.
+- Client-side: log errors to a sink (e.g., error reporting service), not just `console.error`.
+- Prefer event-based metrics over polling. Trace user flows end-to-end with `correlationId`.
+- Respect performance budgets: logging must not add > 10ms latency to hot paths.
+- Include `service`, `environment`, and `version` fields in every log entry for filtering.
+- Use log sampling for high-volume debug logs in production (e.g., 1% sample rate).
+
+## Distributed Tracing
+
+- Use OpenTelemetry SDK for all tracing instrumentation. Initialize the TracerProvider once at application startup before any instrumented libraries load.
+- Propagate trace context via W3C Trace Context headers (`traceparent`, `tracestate`) across all service boundaries, queues, and async workflows.
+- Span naming conventions:
+
+| Span Type   | Pattern                        | Example                     |
+| ----------- | ------------------------------ | --------------------------- |
+| HTTP server | `HTTP {method} {route}`       | `HTTP GET /api/users/:id`   |
+| HTTP client | `HTTP {method} {host}{path}`  | `HTTP POST api.stripe.com/` |
+| DB query    | `{db.system} {operation}`     | `firestore getDoc`          |
+| Queue       | `{queue} {operation}`         | `tasks-queue publish`       |
+| Internal    | `{module}.{function}`         | `auth.verifyToken`          |
+
+- Required span attributes: `service.name`, `service.version`, `deployment.environment`. Add domain-specific attributes (e.g., `user.id`, `tenant.id`) where relevant.
+- Parent-child span relationships: every outbound call (HTTP, DB, queue) creates a child span of the current context. Never create orphan spans.
+- Sampling strategies: use `ParentBased(TraceIdRatioBased(0.1))` in production (10% sample rate). Always sample errors and slow requests (> p95 latency) at 100%.
+- Use the OpenTelemetry Collector as a gateway between applications and backends to enable batching, retrying, and vendor-neutral export.
+- Keep span event count low (< 32 per span). For high-volume events, use correlated logs or `SpanLink` instead.
+
+## Metrics
+
+- Use OpenTelemetry Metrics SDK. Expose Prometheus-compatible `/metrics` endpoint for scraping where applicable.
+- Metric naming: `{service}.{domain}.{metric}_{unit}` in snake_case. Example: `api.auth.login_duration_ms`.
+- Instrument types and when to use:
+
+| Instrument  | Use Case                           | Example                          |
+| ----------- | ---------------------------------- | -------------------------------- |
+| Counter     | Monotonically increasing totals    | `http.requests_total`            |
+| Histogram   | Distributions (latency, size)      | `http.request_duration_ms`       |
+| Gauge       | Point-in-time values               | `db.connection_pool_active`      |
+| UpDownCounter | Values that increase and decrease | `queue.messages_pending`         |
+
+- Histogram buckets for latency: `[5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000]` ms.
+- Cardinality management: never use unbounded values (user IDs, request paths with params) as metric labels. Cap label cardinality to < 100 unique values per metric.
+- Custom business metrics: track domain-significant events (sign-ups, purchases, feature usage) as counters with relevant dimensions.
+
+## SLO / SLI Definitions
+
+- Define SLIs as ratios of good events to total events, measured from the user's perspective.
+- Standard SLIs:
+
+| SLI              | Definition                                    | Measurement Source       |
+| ---------------- | --------------------------------------------- | ------------------------ |
+| Availability     | Requests returning non-5xx / total requests   | Load balancer logs       |
+| Latency          | Requests completing < threshold / total        | Tracing p99              |
+| Error rate       | Failed operations / total operations           | Application metrics      |
+| Freshness        | Data updated within SLA / total records        | Background job metrics   |
+
+- SLO targets: set per-service. Typical starting points: 99.9% availability (43 min/month budget), p99 latency < 500ms.
+- Error budgets: `budget = 1 - SLO_target`. Track remaining budget on a rolling 30-day window.
+- Burn rate alerts: use multi-window approach (short + long window). Fast-burn alert: 2% budget consumed in 1 hour. Slow-burn alert: 5% consumed in 6 hours. Alert only when both windows confirm.
+
+## Alerting
+
+| Severity | Criteria                            | Response Time | Notification       |
+| -------- | ----------------------------------- | ------------- | ------------------- |
+| P1       | Service down, data loss risk        | 15 min        | Page on-call + Slack |
+| P2       | Degraded performance, SLO at risk   | 1 hour        | Page on-call        |
+| P3       | Non-critical issue, workaround exists | Next business day | Slack channel  |
+| P4       | Cosmetic / low-impact               | Sprint backlog | Ticket only         |
+
+- Every alert must link to a runbook with: symptoms, likely causes, diagnostic steps, remediation actions.
+- Alert fatigue prevention: tune thresholds to < 5 actionable alerts per on-call shift. Suppress duplicate alerts within a 10-minute dedup window.
+- Route alerts by service ownership. Use escalation policies: if P1/P2 unacknowledged in 15 min, escalate to secondary.
+- Review alert quality monthly: snooze/delete alerts with < 20% action rate.
+
+## Structured Error Reporting
+
+- Integrate Sentry (or equivalent) for automated error capture in both server and client environments.
+- Configure release tracking: tag errors with `release` (git SHA or semver) and upload source maps for readable stack traces.
+- Enable breadcrumbs: capture the last 50 user actions, network requests, and console messages leading to an error.
+- Error grouping: use custom fingerprints for domain-specific errors to prevent over-grouping. Default fingerprinting is acceptable for unhandled exceptions.
+- Enrich error context with `correlationId`, `userId`, environment, and relevant business state. Never attach PII or secrets.
+- Set sample rates: 100% for errors, 10% for transactions in production. Adjust based on volume and budget.
+
+## Dashboard Standards
+
+- Required dashboards per service:
+
+| Dashboard        | Contents                                                    |
+| ---------------- | ----------------------------------------------------------- |
+| Service Health   | Request rate, error rate, latency p50/p95/p99, saturation   |
+| Business Metrics | Key domain counters, conversion funnels, feature adoption   |
+| Dependencies     | Upstream/downstream latency, error rates, circuit breaker state |
+| Infrastructure   | CPU, memory, disk, connection pools, queue depth            |
+
+- Dashboard-as-code: define dashboards in version-controlled JSON/YAML (Grafana provisioning, Terraform, or equivalent). No manual dashboard creation in production.
+- Every dashboard panel includes: descriptive title, unit labels, threshold lines for SLO targets, and a link to the relevant runbook or alert.
+- Review dashboards quarterly: remove unused panels, update thresholds, verify data source accuracy.
+
+## OpenTelemetry Semantic Conventions
+
+Follow the [OpenTelemetry Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/) (v1.29+) for consistent attribute naming across all telemetry signals. Semantic conventions ensure interoperability between instrumentation libraries, collectors, and observability backends.
+
+### Standard Attribute Namespaces
+
+| Namespace | Scope | Key Attributes |
+|-----------|-------|----------------|
+| `http.*` | HTTP client and server spans | `http.request.method`, `http.response.status_code`, `http.route`, `url.full`, `url.scheme` |
+| `db.*` | Database client spans | `db.system` (e.g., `postgresql`, `mongodb`), `db.operation.name`, `db.collection.name`, `db.query.text` (sanitized) |
+| `rpc.*` | RPC client and server spans | `rpc.system` (e.g., `grpc`, `jsonrpc`), `rpc.service`, `rpc.method`, `rpc.grpc.status_code` |
+| `messaging.*` | Message queue spans | `messaging.system` (e.g., `kafka`, `rabbitmq`), `messaging.operation.type` (`publish`, `receive`, `process`), `messaging.destination.name` |
+| `faas.*` | Serverless/FaaS invocations | `faas.trigger` (`http`, `pubsub`, `timer`), `faas.invoked_name`, `faas.coldstart` |
+| `cloud.*` | Cloud provider context | `cloud.provider`, `cloud.region`, `cloud.availability_zone`, `cloud.account.id` |
+| `k8s.*` | Kubernetes context | `k8s.namespace.name`, `k8s.pod.name`, `k8s.deployment.name`, `k8s.container.name` |
+
+- Use the semantic convention attribute names exactly as specified. Do not invent custom alternatives for concepts already covered by the conventions.
+- When semantic conventions are marked "Experimental," prefer them over project-specific names to ease future migration to stable conventions.
+
+### Resource Semantic Conventions
+
+Every telemetry-producing service must declare resource attributes at startup:
+
+| Attribute | Stability | Requirement | Description |
+|-----------|-----------|-------------|-------------|
+| `service.name` | Stable | Required | Logical name of the service (e.g., `api-gateway`, `auth-service`) |
+| `service.version` | Stable | Recommended | Semantic version of the service (e.g., `1.4.2`) |
+| `deployment.environment.name` | Stable | Recommended | Deployment environment (e.g., `production`, `staging`, `development`) |
+| `service.instance.id` | Experimental | Recommended | Unique instance identifier (e.g., pod name, container ID) |
+| `service.namespace` | Experimental | Optional | Namespace for grouping related services |
+| `telemetry.sdk.name` | Stable | Auto | Set by the SDK (e.g., `opentelemetry`) |
+| `telemetry.sdk.language` | Stable | Auto | Set by the SDK (e.g., `nodejs`, `python`) |
+| `telemetry.sdk.version` | Stable | Auto | Set by the SDK |
+
+- Configure `service.name` and `service.version` via environment variables (`OTEL_SERVICE_NAME`, `OTEL_RESOURCE_ATTRIBUTES`) or programmatically at SDK initialization.
+- Do not use the default `unknown_service` value in any deployed environment. Every service must have an explicit name.
+
+### Span Status Codes
+
+| Code | When to Set |
+|------|-------------|
+| `UNSET` | Default. The span completed without the instrumentation indicating an error. |
+| `OK` | Explicitly set only when the application considers the operation successful and wants to override any lower-level error signal. Use sparingly. |
+| `ERROR` | The operation failed. Set when an exception is caught, an HTTP response is 5xx, or a business-logic error occurs that should be visible in error rate metrics. |
+
+- Set span status to `ERROR` for server-side errors (5xx) and unhandled exceptions. Do not set `ERROR` for client errors (4xx) on the server span — those are valid responses, not server failures.
+- Attach the exception to the span as a span event (`exception.type`, `exception.message`, `exception.stacktrace`) when setting status to `ERROR`.
+- Use `OK` only when you want to suppress error signals from child spans. In most cases, leaving status as `UNSET` is correct.
+
+### Attribute Naming Guidelines
+
+- Use dot-separated namespaces: `http.request.method`, not `httpRequestMethod` or `http_request_method`.
+- Attribute values should be low-cardinality. Never use unbounded values (full URLs with query params, raw SQL, user-generated content) as attribute values.
+- For high-cardinality identifiers (user IDs, request IDs), use span attributes sparingly and rely on correlated logs for detail.
+- Prefer semantic convention attributes over custom attributes. When custom attributes are necessary, prefix them with your organization or project namespace (e.g., `myapp.feature.flag_key`).

package/rules/hatch3r-performance-budgets.md

@@ -0,0 +1,109 @@
+---
+description: Performance budgets and targets for the project
+alwaysApply: false
+---
+# Performance Budgets
+
+## Application Budgets
+
+| Metric                            | Budget               |
+| --------------------------------- | -------------------- |
+| UI render                         | 60fps (16ms/frame)   |
+| Cold start to interactive         | 1.5 seconds          |
+| Idle CPU usage                    | 1%                   |
+| Memory footprint                  | 30 MB                |
+| Event processing latency          | 10ms per event       |
+| Bundle size (initial, gzipped)    | 500 KB               |
+| Backend reads per session start   | ≤ 5 documents        |
+| Serverless warm execution         | 500ms                |
+| Serverless cold start             | 3 seconds            |
+| Main thread long tasks            | 0 tasks > 50ms       |
+
+## Core Web Vitals
+
+Targets align with Google's "Good" thresholds (measured at p75 from real user data):
+
+| Metric | Good        | Needs Improvement | Poor       | What It Measures            |
+| ------ | ----------- | ----------------- | ---------- | --------------------------- |
+| LCP    | ≤ 2.5s     | 2.5–4.0s          | > 4.0s     | Loading — largest visible element render time |
+| INP    | ≤ 200ms    | 200–500ms         | > 500ms    | Responsiveness — worst interaction latency across full session |
+| CLS    | ≤ 0.1      | 0.1–0.25          | > 0.25     | Visual stability — cumulative unexpected layout shifts |
+
+- **LCP optimization**: preload hero images/fonts, inline critical CSS, use `fetchpriority="high"` on LCP elements, server-side render above-the-fold content.
+- **INP optimization**: break long tasks with `scheduler.yield()`, defer non-critical event handlers, avoid layout thrashing in input handlers, keep interaction callbacks < 100ms.
+- **CLS optimization**: set explicit `width`/`height` on images and embeds, reserve space for dynamic content, avoid inserting content above the viewport after load.
+
+## API Response Time Budgets
+
+| Endpoint Type  | p50     | p95     | p99     | Timeout |
+| -------------- | ------- | ------- | ------- | ------- |
+| Read (single)  | 50ms    | 150ms   | 300ms   | 5s      |
+| Read (list)    | 100ms   | 300ms   | 500ms   | 10s     |
+| Write (create) | 100ms   | 250ms   | 500ms   | 10s     |
+| Write (update) | 75ms    | 200ms   | 400ms   | 10s     |
+| Search         | 150ms   | 500ms   | 1000ms  | 15s     |
+| Aggregation    | 200ms   | 800ms   | 2000ms  | 30s     |
+| Auth flow      | 100ms   | 300ms   | 500ms   | 10s     |
+
+- All endpoints must return within their timeout or abort with a structured error.
+- Client-side: set `AbortController` timeouts matching the table above. Show loading indicators after 300ms.
+
+## Database Query Budgets
+
+| Constraint                        | Budget / Rule                        |
+| --------------------------------- | ------------------------------------ |
+| Single query execution            | < 100ms                              |
+| N+1 detection                     | 0 N+1 patterns (enforced via lint/review) |
+| Queries per request               | ≤ 10                                 |
+| Connection pool size              | 10–20 per service instance           |
+| Index coverage                    | Every query in hot paths must hit an index |
+| Full collection scans             | Forbidden in production code         |
+| Batch read size                   | ≤ 100 documents per batch            |
+
+- Use query explain plans during code review for new or modified queries.
+- Log slow queries (> 200ms) with the query pattern and execution plan.
+
+## Network Budgets
+
+| Constraint                        | Budget                               |
+| --------------------------------- | ------------------------------------ |
+| Requests per page load            | ≤ 30                                 |
+| Total transfer size (initial)     | ≤ 1.5 MB                            |
+| Image payload per page            | ≤ 500 KB                            |
+| Individual API response           | ≤ 100 KB (gzipped)                  |
+| WebSocket message size            | ≤ 10 KB                             |
+| Font files loaded                 | ≤ 2 families, WOFF2 only            |
+| Third-party script budget         | ≤ 100 KB (gzipped)                  |
+
+- Images: serve WebP/AVIF with responsive `srcset`. Lazy-load below-the-fold images.
+- Fonts: use `font-display: swap`, preload critical fonts, subset to used character ranges.
+- Enable Brotli or gzip compression on all text responses. Set `Cache-Control` headers per resource type.
+
+## Enforcement Mechanisms
+
+| Gate                   | Tool / Method              | Trigger          | Threshold                    |
+| ---------------------- | -------------------------- | ---------------- | ---------------------------- |
+| Bundle size            | `size-limit` in CI         | Every PR         | Fail if > 500 KB gzipped    |
+| Lighthouse score       | Lighthouse CI assertions   | Every PR         | Performance ≥ 90            |
+| Core Web Vitals        | Lighthouse CI + CrUX       | PR + weekly      | All metrics in "Good" range  |
+| API latency            | Integration test assertions | Every PR        | p95 within budget table      |
+| DB query count         | Test-level query counter   | Every PR         | ≤ 10 per request             |
+| Runtime regression     | RUM dashboards + alerts    | Continuous       | Alert on p75 regression > 10% |
+| Synthetic monitoring   | Scheduled Lighthouse runs  | Hourly/daily     | Slack alert on score drop    |
+
+- CI must block merge if any enforcement gate fails. No manual overrides without tech-lead approval.
+- Track budget trends over time: plot bundle size, LCP, and INP per release on the performance dashboard.
+
+## Measurement Tooling
+
+| Metric Category    | Lab / CI Tool                      | Field / Production Tool          |
+| ------------------ | ---------------------------------- | -------------------------------- |
+| Core Web Vitals    | Lighthouse CI, WebPageTest         | CrUX, `web-vitals` library (RUM) |
+| Bundle size        | `size-limit`, `webpack-bundle-analyzer` | N/A                         |
+| API latency        | Integration tests, k6              | OpenTelemetry histograms         |
+| DB performance     | Query explain, test query counters | Slow query logs, APM traces      |
+| Memory / CPU       | Chrome DevTools, profiler          | Infrastructure metrics (Prometheus) |
+| Visual regression  | Playwright screenshot diffing      | RUM CLS tracking                 |
+
+- Automated regression detection: compare each PR's metrics against the `main` branch baseline. Flag regressions > 5% in any budget metric.
+- Review performance budgets quarterly and tighten thresholds as the application matures.

package/rules/hatch3r-performance-budgets.mdc

@@ -0,0 +1,109 @@
+---
+description: Performance budgets and targets for the project
+alwaysApply: false
+---
+# Performance Budgets
+
+## Application Budgets
+
+| Metric                            | Budget               |
+| --------------------------------- | -------------------- |
+| UI render                         | 60fps (16ms/frame)   |
+| Cold start to interactive         | 1.5 seconds          |
+| Idle CPU usage                    | 1%                   |
+| Memory footprint                  | 30 MB                |
+| Event processing latency          | 10ms per event       |
+| Bundle size (initial, gzipped)    | 500 KB               |
+| Backend reads per session start   | ≤ 5 documents        |
+| Serverless warm execution         | 500ms                |
+| Serverless cold start             | 3 seconds            |
+| Main thread long tasks            | 0 tasks > 50ms       |
+
+## Core Web Vitals
+
+Targets align with Google's "Good" thresholds (measured at p75 from real user data):
+
+| Metric | Good        | Needs Improvement | Poor       | What It Measures            |
+| ------ | ----------- | ----------------- | ---------- | --------------------------- |
+| LCP    | ≤ 2.5s     | 2.5–4.0s          | > 4.0s     | Loading — largest visible element render time |
+| INP    | ≤ 200ms    | 200–500ms         | > 500ms    | Responsiveness — worst interaction latency across full session |
+| CLS    | ≤ 0.1      | 0.1–0.25          | > 0.25     | Visual stability — cumulative unexpected layout shifts |
+
+- **LCP optimization**: preload hero images/fonts, inline critical CSS, use `fetchpriority="high"` on LCP elements, server-side render above-the-fold content.
+- **INP optimization**: break long tasks with `scheduler.yield()`, defer non-critical event handlers, avoid layout thrashing in input handlers, keep interaction callbacks < 100ms.
+- **CLS optimization**: set explicit `width`/`height` on images and embeds, reserve space for dynamic content, avoid inserting content above the viewport after load.
+
+## API Response Time Budgets
+
+| Endpoint Type  | p50     | p95     | p99     | Timeout |
+| -------------- | ------- | ------- | ------- | ------- |
+| Read (single)  | 50ms    | 150ms   | 300ms   | 5s      |
+| Read (list)    | 100ms   | 300ms   | 500ms   | 10s     |
+| Write (create) | 100ms   | 250ms   | 500ms   | 10s     |
+| Write (update) | 75ms    | 200ms   | 400ms   | 10s     |
+| Search         | 150ms   | 500ms   | 1000ms  | 15s     |
+| Aggregation    | 200ms   | 800ms   | 2000ms  | 30s     |
+| Auth flow      | 100ms   | 300ms   | 500ms   | 10s     |
+
+- All endpoints must return within their timeout or abort with a structured error.
+- Client-side: set `AbortController` timeouts matching the table above. Show loading indicators after 300ms.
+
+## Database Query Budgets
+
+| Constraint                        | Budget / Rule                        |
+| --------------------------------- | ------------------------------------ |
+| Single query execution            | < 100ms                              |
+| N+1 detection                     | 0 N+1 patterns (enforced via lint/review) |
+| Queries per request               | ≤ 10                                 |
+| Connection pool size              | 10–20 per service instance           |
+| Index coverage                    | Every query in hot paths must hit an index |
+| Full collection scans             | Forbidden in production code         |
+| Batch read size                   | ≤ 100 documents per batch            |
+
+- Use query explain plans during code review for new or modified queries.
+- Log slow queries (> 200ms) with the query pattern and execution plan.
+
+## Network Budgets
+
+| Constraint                        | Budget                               |
+| --------------------------------- | ------------------------------------ |
+| Requests per page load            | ≤ 30                                 |
+| Total transfer size (initial)     | ≤ 1.5 MB                            |
+| Image payload per page            | ≤ 500 KB                            |
+| Individual API response           | ≤ 100 KB (gzipped)                  |
+| WebSocket message size            | ≤ 10 KB                             |
+| Font files loaded                 | ≤ 2 families, WOFF2 only            |
+| Third-party script budget         | ≤ 100 KB (gzipped)                  |
+
+- Images: serve WebP/AVIF with responsive `srcset`. Lazy-load below-the-fold images.
+- Fonts: use `font-display: swap`, preload critical fonts, subset to used character ranges.
+- Enable Brotli or gzip compression on all text responses. Set `Cache-Control` headers per resource type.
+
+## Enforcement Mechanisms
+
+| Gate                   | Tool / Method              | Trigger          | Threshold                    |
+| ---------------------- | -------------------------- | ---------------- | ---------------------------- |
+| Bundle size            | `size-limit` in CI         | Every PR         | Fail if > 500 KB gzipped    |
+| Lighthouse score       | Lighthouse CI assertions   | Every PR         | Performance ≥ 90            |
+| Core Web Vitals        | Lighthouse CI + CrUX       | PR + weekly      | All metrics in "Good" range  |
+| API latency            | Integration test assertions | Every PR        | p95 within budget table      |
+| DB query count         | Test-level query counter   | Every PR         | ≤ 10 per request             |
+| Runtime regression     | RUM dashboards + alerts    | Continuous       | Alert on p75 regression > 10% |
+| Synthetic monitoring   | Scheduled Lighthouse runs  | Hourly/daily     | Slack alert on score drop    |
+
+- CI must block merge if any enforcement gate fails. No manual overrides without tech-lead approval.
+- Track budget trends over time: plot bundle size, LCP, and INP per release on the performance dashboard.
+
+## Measurement Tooling
+
+| Metric Category    | Lab / CI Tool                      | Field / Production Tool          |
+| ------------------ | ---------------------------------- | -------------------------------- |
+| Core Web Vitals    | Lighthouse CI, WebPageTest         | CrUX, `web-vitals` library (RUM) |
+| Bundle size        | `size-limit`, `webpack-bundle-analyzer` | N/A                         |
+| API latency        | Integration tests, k6              | OpenTelemetry histograms         |
+| DB performance     | Query explain, test query counters | Slow query logs, APM traces      |
+| Memory / CPU       | Chrome DevTools, profiler          | Infrastructure metrics (Prometheus) |
+| Visual regression  | Playwright screenshot diffing      | RUM CLS tracking                 |
+
+- Automated regression detection: compare each PR's metrics against the `main` branch baseline. Flag regressions > 5% in any budget metric.
+- Review performance budgets quarterly and tighten thresholds as the application matures.

package/rules/hatch3r-secrets-management.md

@@ -0,0 +1,76 @@
+---
+id: hatch3r-secrets-management
+type: rule
+description: Secret management, rotation, and secure handling patterns for the project
+scope: always
+---
+# Secrets Management
+
+## Env Var Management
+
+- Store configuration and secrets in environment variables. Never hard-code secrets (API keys, tokens, passwords, connection strings) in source code, comments, or commit messages.
+- Maintain a `.env.example` file in the repository root listing every required environment variable with placeholder values and brief descriptions. Update it whenever a new env var is introduced.
+- Actual `.env` files must be in `.gitignore`. Verify `.gitignore` includes `.env`, `.env.local`, `.env.*.local`, and any other secret-bearing files before every commit.
+- Use a typed env loader (e.g., `@t3-oss/env-core`, `envalid`, `zod` schema) to validate and parse environment variables at application startup. Fail fast with a clear error message listing missing or invalid variables.
+- Separate secrets by environment: `.env.development`, `.env.staging`, `.env.production`. Never share production secrets with development environments.
+- Document the source of each secret (which service/provider generates it) in `.env.example` or an internal secrets inventory document.
+
+## Secret Rotation Policies
+
+| Secret Type | Rotation Frequency | Trigger for Immediate Rotation |
+|-------------|-------------------|-------------------------------|
+| API keys (third-party) | Every 90 days | Suspected compromise, employee departure |
+| Database credentials | Every 90 days | Credential exposure, personnel change |
+| JWT signing keys | Every 180 days | Algorithm upgrade, key compromise |
+| Webhook secrets | Every 180 days | Partner-side breach, integration change |
+| Service account tokens | Every 90 days | Scope change, compromise |
+| Encryption keys | Every 365 days (or per compliance) | Algorithm vulnerability, compliance audit |
+| OAuth client secrets | Every 180 days | Provider breach, app re-registration |
+
+- Implement dual-key (overlap) rotation: deploy the new secret, update all consumers, verify, then revoke the old secret. Never revoke before all consumers have migrated.
+- Automate rotation where the provider supports it (AWS Secrets Manager auto-rotation, GCP Secret Manager rotation schedules).
+- Log every rotation event: who initiated, when, which secret (by name, never by value), success/failure.
+
+## Cloud Secret Managers
+
+- **AWS Secrets Manager:** Store secrets as JSON key-value pairs. Use IAM policies to scope access per service/role. Enable automatic rotation with Lambda rotation functions. Use `aws-sdk` `GetSecretValue` at runtime — never bake secrets into container images or deployment artifacts.
+- **GCP Secret Manager:** Store each secret as a versioned resource. Grant `secretmanager.secretAccessor` role per service account with resource-level IAM. Access secrets via `@google-cloud/secret-manager` client library at startup. Use secret versions (not `latest` in production) for auditability.
+- **Azure Key Vault:** Store secrets, keys, and certificates. Use Managed Identity for authentication — no credentials needed to access the vault. Apply access policies per application identity. Enable soft-delete and purge protection.
+- **HashiCorp Vault:** Use dynamic secrets where possible (database credentials, cloud IAM). Implement AppRole or Kubernetes auth for machine identity. Set TTLs on all leases. Audit log every access.
+- **General:** Abstract the secret provider behind an interface so the application code is not coupled to a specific cloud provider. Inject the provider at startup via configuration.
+
+## CI/CD Secret Injection
+
+- **GitHub Actions:** Store secrets in repository or organization settings. Reference via `${{ secrets.SECRET_NAME }}`. Never echo secrets in workflow logs — use masking (`::add-mask::`). Use environment-scoped secrets for production deployments with required reviewers.
+- **GitLab CI:** Store in project or group CI/CD variables. Mark as "Protected" (only available on protected branches) and "Masked" (redacted from logs). Use file-type variables for multi-line secrets (certificates, keys).
+- **General CI principles:** Secrets must not appear in build logs, artifacts, or cached layers. Pin CI action versions by SHA (not tag) to prevent supply chain attacks on secret-accessing workflows. Rotate CI secrets on the same schedule as application secrets.
+- **Ephemeral secrets:** For CI jobs that need temporary cloud access, use OIDC federation (e.g., GitHub Actions `aws-actions/configure-aws-credentials` with OIDC) instead of long-lived credentials.
+
+## Application-Level Secret Handling
+
+- **Never log secrets.** Sanitize log output to redact any field matching known secret patterns (tokens, keys, passwords). Use structured logging with an explicit allowlist of loggable fields.
+- **Never serialize secrets** into JSON responses, error messages, stack traces, or client-side state. Treat secrets as write-only values: they go into the system but never come back out in any observable output.
+- **Memory safety:** Clear secret values from memory after use where the language/runtime permits (overwrite buffers, null references). Avoid storing secrets in global/static variables that persist for the application lifetime.
+- **Transport:** Transmit secrets only over TLS 1.2+. Never send secrets in URL query parameters (they appear in access logs and browser history). Use request headers or POST body.
+- **Principle of least privilege:** Each service/function should have access only to the secrets it needs. Avoid a single "master" secret store accessible to all services.
+- **Secret-bearing config objects:** Wrap secrets in a `Secret<T>` type that overrides `toString()` and `toJSON()` to return `"[REDACTED]"`. This prevents accidental exposure via logging or serialization.
+
+## Secret Scanning in CI
+
+- **gitleaks:** Run `gitleaks detect` in CI on every push and PR. Configure `.gitleaks.toml` with project-specific rules and allowlists for false positives (test fixtures, documentation examples).
+- **TruffleHog:** Use `trufflehog git` for historical scanning of the full repository. Run quarterly or on suspected compromise. Focus on high-entropy strings and known secret patterns.
+- **GitHub Secret Scanning:** Enable GitHub's built-in secret scanning and push protection. Configure custom patterns for project-specific secret formats.
+- **Pre-commit hooks:** Install a local pre-commit hook (e.g., `gitleaks protect --staged`) to catch secrets before they reach the remote. This is defense-in-depth — CI scanning is still required.
+- **Remediation SLA:** Secrets detected in CI must be rotated immediately (within 1 hour for production secrets). Assume any secret that reached a commit is compromised, even if the commit was force-pushed away — git history is recoverable.
+
+## Emergency Rotation Procedures
+
+When a secret is confirmed or suspected compromised:
+
+1. **Assess scope:** Identify which secret, which environments, and which services are affected. Check audit logs for unauthorized access.
+2. **Generate new secret:** Create a replacement via the appropriate provider (cloud console, API, or CLI). Do not reuse or derive from the compromised value.
+3. **Deploy new secret:** Update the secret in the secret manager and deploy affected services. Use blue-green or rolling deployment to avoid downtime.
+4. **Revoke old secret:** After confirming all services are using the new secret, revoke/delete the old one. Verify revocation by testing that the old value is rejected.
+5. **Audit impact:** Review access logs for the compromised secret's lifetime. Identify any unauthorized actions taken with the compromised credential.
+6. **Incident report:** Document the timeline, root cause (how the secret was exposed), blast radius, remediation steps, and preventive measures. File as a security incident per the project's incident response process.
+7. **Prevent recurrence:** Add scanning rules for the pattern that was missed, review access controls, and update rotation policies if the secret exceeded its rotation window.