hatch3r 1.4.0 → 1.5.0

package/rules/hatch3r-browser-verification.md

@@ -3,7 +3,9 @@ id: hatch3r-browser-verification
 type: rule
 description: Browser-based verification for UI and user-facing changes
 scope: conditional
+globs: "**/*.vue,**/*.jsx,**/*.tsx,**/*.svelte,**/components/**,**/*.html,**/*.css,**/*.scss"
 tags: [review]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Browser Verification
 
@@ -60,7 +62,7 @@ Commands in the "Does NOT Support" column are documentation-only, planning-only,
 
 ## Verification Protocol
 
-### 1. Ensure Dev Server is Running
+### 1. Confirm Dev Server is Running
 
 - Check if the project's dev server is already running (check terminal output or process list).
 - If not running, start it in the background using the project's dev command (e.g., `npm run dev`).
@@ -77,7 +79,7 @@ Commands in the "Does NOT Support" column are documentation-only, planning-only,
 
 ### 3. Capture Evidence
 
-- Take screenshots of the affected surfaces showing the change works correctly.
+- Take screenshots of the affected surfaces showing the change produces the expected visual and interactive result.
 - For before/after changes (visual refactors, bug fixes), capture both states when possible.
 - Note any browser console errors or warnings in the verification summary.
 - Include screenshots in the PR description or attach to the issue.

package/rules/hatch3r-browser-verification.mdc

@@ -1,5 +1,6 @@
 ---
 description: Browser-based verification for UI and user-facing changes
+globs: ["**/*.vue", "**/*.jsx", "**/*.tsx", "**/*.svelte", "**/components/**", "**/*.html", "**/*.css", "**/*.scss"]
 alwaysApply: false
 ---
 # Browser Verification

package/rules/hatch3r-ci-cd.md

@@ -2,8 +2,9 @@
 id: hatch3r-ci-cd
 type: rule
 description: CI/CD pipeline standards covering stage gates, deployment strategies, and rollback procedures
-scope: always
+scope: "**/.github/workflows/**,**/Dockerfile*,**/docker-compose*,**/.gitlab-ci*,**/Jenkinsfile,**/azure-pipelines*,**/.circleci/**,**/deploy/**,**/*pipeline*"
 tags: [devops]
+quality_charter: agents/shared/quality-charter.md
 ---
 # CI/CD Standards
 

package/rules/hatch3r-ci-cd.mdc

@@ -1,6 +1,6 @@
 ---
 description: CI/CD pipeline standards covering stage gates, deployment strategies, and rollback procedures
-alwaysApply: true
+globs: ["**/.github/workflows/**", "**/Dockerfile*", "**/docker-compose*", "**/.gitlab-ci*", "**/Jenkinsfile", "**/azure-pipelines*", "**/.circleci/**", "**/deploy/**", "**/*pipeline*"]
 ---
 # CI/CD Standards
 

package/rules/hatch3r-code-standards.md

@@ -3,7 +3,8 @@ id: hatch3r-code-standards
 type: rule
 description: Code quality and file naming conventions for the project
 scope: always
-tags: [core]
+tags: [core, lang:typescript]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Code Standards
 
@@ -29,7 +30,7 @@ tags: [core]
 ### Discriminated Unions
 
 - Model domain variants with discriminated unions over polymorphic classes or `type` string checks. Every variant must share a common literal discriminant field (e.g., `kind`, `type`, `status`).
-- Use exhaustive `switch` with a `never` default case to ensure all variants are handled. The compiler will error when a new variant is added but not handled.
+- Use exhaustive `switch` with a `never` default case so the compiler errors when a new variant is added but not handled.
 
 ### Branded Types
 
@@ -91,6 +92,18 @@ tags: [core]
 - Include `correlationId` in all error logs for tracing across client and server.
 - No secrets, tokens, or PII in error messages or logs.
 
+### Error Handling Anti-Patterns (Prohibited)
+
+The following patterns are always wrong and must be flagged in review:
+
+| Anti-Pattern | Why It Is Wrong | Correct Alternative |
+|-------------|-----------------|---------------------|
+| `catch (e) {}` (empty catch) | Silently swallows errors; failures become invisible | `catch (e) { logger.error('context', e); throw e; }` or handle with Result type |
+| `catch (e) { return null; }` in auth paths | Fail-open: returns "no user" instead of "auth failed" | `catch (e) { throw new AuthError('auth_failed', e); }` |
+| `as any` to fix type errors | Bypasses type safety; hides real type mismatches | Fix the actual type or use a proper type guard |
+| `// @ts-ignore` without linked issue | Permanent type-safety hole | Fix the type error or add `// @ts-expect-error` with issue link |
+| `try { ... } catch { return defaultValue; }` for all errors | Treats transient errors (network) same as permanent ones (validation) | Discriminate error types: retry transient, fail permanent |
+
 ## Import Ordering
 
 Enforce consistent import ordering via linter rules (e.g., `eslint-plugin-import`). The canonical order:

package/rules/hatch3r-code-standards.mdc

@@ -88,6 +88,18 @@ alwaysApply: true
 - Include `correlationId` in all error logs for tracing across client and server.
 - No secrets, tokens, or PII in error messages or logs.
 
+### Error Handling Anti-Patterns (Prohibited)
+
+The following patterns are always wrong and must be flagged in review:
+
+| Anti-Pattern | Why It Is Wrong | Correct Alternative |
+|-------------|-----------------|---------------------|
+| `catch (e) {}` (empty catch) | Silently swallows errors; failures become invisible | `catch (e) { logger.error('context', e); throw e; }` or handle with Result type |
+| `catch (e) { return null; }` in auth paths | Fail-open: returns "no user" instead of "auth failed" | `catch (e) { throw new AuthError('auth_failed', e); }` |
+| `as any` to fix type errors | Bypasses type safety; hides real type mismatches | Fix the actual type or use a proper type guard |
+| `// @ts-ignore` without linked issue | Permanent type-safety hole | Fix the type error or add `// @ts-expect-error` with issue link |
+| `try { ... } catch { return defaultValue; }` for all errors | Treats transient errors (network) same as permanent ones (validation) | Discriminate error types: retry transient, fail permanent |
+
 ## Import Ordering
 
 Enforce consistent import ordering via linter rules (e.g., `eslint-plugin-import`). The canonical order:

package/rules/hatch3r-component-conventions.md

@@ -5,6 +5,7 @@ description: Rules for component development in web applications
 scope: conditional
 globs: src/**/*.vue, src/**/*.tsx, src/**/*.jsx
 tags: [implementation]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Component Conventions
 
@@ -78,7 +79,7 @@ tags: [implementation]
 - Group related fields with `<fieldset>` and `<legend>` (e.g., "Shipping Address", "Payment Details").
 - Use progressive disclosure for complex forms: show advanced options behind an expandable section or a follow-up step.
 - Autofocus the first input field on form mount.
-- Ensure tab order follows the visual layout order — never use positive `tabindex` values.
+- Verify tab order follows the visual layout order by tabbing through the form — never use positive `tabindex` values.
 
 ### Submit Behavior
 - Disable the submit button when the form has known validation errors (but keep it focusable for screen readers).

package/rules/hatch3r-component-conventions.mdc

@@ -1,5 +1,6 @@
 ---
 description: Rules for component development in web applications
+globs: ["src/**/*.vue", "src/**/*.tsx", "src/**/*.jsx"]
 alwaysApply: false
 ---
 # Component Conventions

package/rules/hatch3r-data-classification.md

@@ -2,8 +2,9 @@
 id: hatch3r-data-classification
 type: rule
 description: Data classification standards covering PII handling, encryption, retention policies, and regulatory compliance
-scope: always
+scope: "**/models/**,**/schemas/**,**/schema*,**/database/**,**/db/**,**/*model*,**/*entity*,**/prisma/**,**/drizzle/**,**/*migration*"
 tags: [security]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Data Classification Standards
 

package/rules/hatch3r-data-classification.mdc

@@ -1,6 +1,6 @@
 ---
 description: Data classification standards covering PII handling, encryption, retention policies, and regulatory compliance
-alwaysApply: true
+globs: ["**/models/**", "**/schemas/**", "**/schema*", "**/database/**", "**/db/**", "**/*model*", "**/*entity*", "**/prisma/**", "**/drizzle/**", "**/*migration*"]
 ---
 # Data Classification Standards
 

package/rules/hatch3r-deep-context.md

@@ -4,6 +4,7 @@ type: rule
 description: Adaptive pre-implementation analysis — complexity scoring, requirements elicitation, similar implementation discovery, and transitive dependency tracing before coding
 scope: always
 tags: [core]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Deep Context Analysis
 
@@ -87,8 +88,32 @@ This rule augments — not replaces — the existing Universal Sub-Agent Pipelin
 - **`type:bug`**: existing modes `symptom-trace`, `root-cause`, `codebase-impact` + `requirements-elicitation` per tier (bugs often have underspecified reproduction steps)
 - **`type:refactor`**: existing modes `current-state`, `refactoring-strategy`, `migration-path` + `similar-implementation` per tier (refactors benefit most from convention alignment)
 
+## Scoring Examples
+
+To reduce ambiguity in tier assignment, here are worked examples:
+
+**Example 1: "Fix typo in error message" -- Tier 1 (score 0)**
+No signals triggered. Single file, no cross-module impact, no ambiguity.
+
+**Example 2: "Add email validation to signup form" -- Tier 2 (score 4)**
+- Multiple layers touched (API + UI): +3
+- Estimated 2-3 files: +0
+- Input validation is security-adjacent but not in a security-sensitive area: +0
+- Clear requirements ("validate email format"): +0
+- May trigger cross-cutting i18n for error messages: +1 (partial cross-cutting)
+
+**Example 3: "Migrate auth from session-based to JWT" -- Tier 3 (score 12)**
+- Multiple layers (auth middleware + API + UI + storage): +3
+- Vague term "migrate" (scope unclear): +2
+- Cross-cutting auth concern: +2
+- Security-sensitive area: +2
+- Behavioral contract change (session API to JWT API): +2
+- Estimated >5 files: +1 (partial -- easily >5)
+
+When a signal partially applies (e.g., "maybe 5 files, maybe 4"), round down. Tier upgrades from adaptation (see `hatch3r-agent-orchestration-detail`) compensate for underestimates.
+
 ## Exceptions
 
 - **`hatch3r-quick-change` command**: Tier 1 items proceed without research. Tier 2 items get lightweight `similar-implementation` at `quick` depth. Tier 3 items must be routed to `hatch3r-workflow` (hard block).
-- **Trivial single-line edits**: Always Tier 1 regardless of scoring signals. This is the only valid basis for skipping research — label-based shortcuts (e.g., `risk:low AND priority:p3`) are not sufficient alone.
+- **Trivial single-line edits**: Always Tier 1 regardless of scoring signals. This is the only valid basis for skipping research -- label-based shortcuts (e.g., `risk:low AND priority:p3`) are not sufficient alone.
 - **`hatch3r-revision` command**: Operates on already-implemented code. Deep context analysis applies to the original implementation, not the revision pass.

package/rules/hatch3r-deep-context.mdc

@@ -84,8 +84,32 @@ This rule augments — not replaces — the existing Universal Sub-Agent Pipelin
 - **`type:bug`**: existing modes `symptom-trace`, `root-cause`, `codebase-impact` + `requirements-elicitation` per tier (bugs often have underspecified reproduction steps)
 - **`type:refactor`**: existing modes `current-state`, `refactoring-strategy`, `migration-path` + `similar-implementation` per tier (refactors benefit most from convention alignment)
 
+## Scoring Examples
+
+To reduce ambiguity in tier assignment, here are worked examples:
+
+**Example 1: "Fix typo in error message" -- Tier 1 (score 0)**
+No signals triggered. Single file, no cross-module impact, no ambiguity.
+
+**Example 2: "Add email validation to signup form" -- Tier 2 (score 4)**
+- Multiple layers touched (API + UI): +3
+- Estimated 2-3 files: +0
+- Input validation is security-adjacent but not in a security-sensitive area: +0
+- Clear requirements ("validate email format"): +0
+- May trigger cross-cutting i18n for error messages: +1 (partial cross-cutting)
+
+**Example 3: "Migrate auth from session-based to JWT" -- Tier 3 (score 12)**
+- Multiple layers (auth middleware + API + UI + storage): +3
+- Vague term "migrate" (scope unclear): +2
+- Cross-cutting auth concern: +2
+- Security-sensitive area: +2
+- Behavioral contract change (session API to JWT API): +2
+- Estimated >5 files: +1 (partial -- easily >5)
+
+When a signal partially applies (e.g., "maybe 5 files, maybe 4"), round down. Tier upgrades from adaptation (see `hatch3r-agent-orchestration-detail`) compensate for underestimates.
+
 ## Exceptions
 
 - **`hatch3r-quick-change` command**: Tier 1 items proceed without research. Tier 2 items get lightweight `similar-implementation` at `quick` depth. Tier 3 items must be routed to `hatch3r-workflow` (hard block).
-- **Trivial single-line edits**: Always Tier 1 regardless of scoring signals. This is the only valid basis for skipping research — label-based shortcuts (e.g., `risk:low AND priority:p3`) are not sufficient alone.
+- **Trivial single-line edits**: Always Tier 1 regardless of scoring signals. This is the only valid basis for skipping research -- label-based shortcuts (e.g., `risk:low AND priority:p3`) are not sufficient alone.
 - **`hatch3r-revision` command**: Operates on already-implemented code. Deep context analysis applies to the original implementation, not the revision pass.

package/rules/hatch3r-dependency-management.md

@@ -2,8 +2,9 @@
 id: hatch3r-dependency-management
 type: rule
 description: Rules for managing project dependencies
-scope: always
+scope: "**/package.json,**/package-lock.json,**/yarn.lock,**/pnpm-lock.yaml,**/Cargo.toml,**/Cargo.lock,**/requirements*.txt,**/pyproject.toml,**/go.mod,**/go.sum,**/Gemfile*"
 tags: [maintenance]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Dependency Management
 

package/rules/hatch3r-dependency-management.mdc

@@ -1,6 +1,6 @@
 ---
 description: Rules for managing project dependencies
-alwaysApply: true
+globs: ["**/package.json", "**/package-lock.json", "**/yarn.lock", "**/pnpm-lock.yaml", "**/Cargo.toml", "**/Cargo.lock", "**/requirements*.txt", "**/pyproject.toml", "**/go.mod", "**/go.sum", "**/Gemfile*"]
 ---
 # Dependency Management
 

package/rules/hatch3r-feature-flags.md

@@ -3,7 +3,9 @@ id: hatch3r-feature-flags
 type: rule
 description: Feature flag patterns and lifecycle for the project
 scope: conditional
+globs: "**/*feature-flag*,**/*featureFlag*,**/*feature_flag*,**/config/**"
 tags: [implementation]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Feature Flags
 

package/rules/hatch3r-feature-flags.mdc

@@ -1,5 +1,6 @@
 ---
 description: Feature flag patterns and lifecycle for the project
+globs: ["**/*feature-flag*", "**/*featureFlag*", "**/*feature_flag*", "**/config/**"]
 alwaysApply: false
 ---
 # Feature Flags

package/rules/hatch3r-git-conventions.md

@@ -2,8 +2,9 @@
 id: hatch3r-git-conventions
 type: rule
 description: Git commit message and branching conventions
-scope: always
+scope: "**/.git/**,**/.gitignore,**/.gitattributes,**/.gitmodules,**/COMMIT_EDITMSG"
 tags: [core]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Git Conventions
 

package/rules/hatch3r-git-conventions.mdc

@@ -1,6 +1,7 @@
 ---
 description: Git commit message and branching conventions
-alwaysApply: true
+globs: "**/.git/**,**/.gitignore,**/.gitattributes,**/.gitmodules,**/COMMIT_EDITMSG"
+alwaysApply: false
 ---
 # Git Conventions
 

package/rules/hatch3r-i18n.md

@@ -5,6 +5,7 @@ description: Internationalization, localization, and RTL support conventions for
 scope: conditional
 globs: src/**/*.vue, src/**/*.tsx, src/**/*.jsx, src/**/*.ts
 tags: [implementation]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Internationalization & RTL
 
@@ -43,7 +44,7 @@ tags: [implementation]
 
 - Allow 30–40% text expansion for German/Finnish translations relative to English; test UI with pseudo-localization that pads strings.
 - Use `min-height` instead of fixed `height` on text containers to accommodate CJK line-height requirements (1.6–1.8 recommended).
-- Define font stacks per script family: Latin, CJK, Arabic, Devanagari — ensure each stack includes a web-safe fallback and `system-ui`.
+- Define font stacks per script family: Latin, CJK, Arabic, Devanagari — each stack must include a web-safe fallback and `system-ui`.
 - Truncate overflowing text with `text-overflow: ellipsis` plus `overflow: hidden` and `white-space: nowrap` only when semantically safe; provide title/tooltip with full text.
 - Avoid fixed-width containers for translatable text; prefer `min-width` / `max-width` with flex/grid layout.
 

package/rules/hatch3r-i18n.mdc

@@ -1,5 +1,6 @@
 ---
 description: Internationalization, localization, and RTL support conventions for the project
+globs: ["src/**/*.vue", "src/**/*.tsx", "src/**/*.jsx", "src/**/*.ts", "**/locales/**", "**/i18n/**", "**/*i18n*", "**/*locale*"]
 alwaysApply: false
 ---
 # Internationalization & RTL

package/rules/hatch3r-learning-consult.md

@@ -2,8 +2,9 @@
 id: hatch3r-learning-consult
 type: rule
 description: Auto-consult project learnings before implementation
-scope: always
+scope: "**/.agents/learnings/**,**/learnings/**"
 tags: [core]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Learning Consultation
 
@@ -29,3 +30,12 @@ Before implementing any task, check `.agents/learnings/` for relevant past learn
 - **Pitfalls** are highest priority -- always surface these.
 - **Patterns** are surfaced when the current task matches their trigger conditions.
 - **Decisions** are surfaced when the current task might conflict with a past decision.
+
+## Consultation Efficiency
+
+To avoid excessive token usage during consultation:
+
+1. **Scan frontmatter first.** Read only the YAML frontmatter (`tags`, `area`, `category`) of each learning file to determine relevance. Only read the full body of learnings that match the current task.
+2. **Limit surfaced learnings.** Present at most 5 relevant learnings per consultation. If more are relevant, prioritize by confidence level (high > medium > low) and recency.
+3. **Cache consultation results.** If consultation was already performed for this task (e.g., during board-pickup), do not re-consult during skill execution. The orchestrator passes relevant learnings to subagents as part of prompt enrichment.
+4. **Skip when empty.** If `.agents/learnings/` has fewer than 3 files, consultation overhead exceeds value. Skip silently.

package/rules/hatch3r-learning-consult.mdc

@@ -1,6 +1,7 @@
 ---
 description: Auto-consult project learnings before implementation
-alwaysApply: true
+globs: "**/.agents/learnings/**,**/learnings/**"
+alwaysApply: false
 ---
 # Learning Consultation
 
@@ -26,3 +27,12 @@ Before implementing any task, check `.agents/learnings/` for relevant past learn
 - **Pitfalls** are highest priority -- always surface these.
 - **Patterns** are surfaced when the current task matches their trigger conditions.
 - **Decisions** are surfaced when the current task might conflict with a past decision.
+
+## Consultation Efficiency
+
+To avoid excessive token usage during consultation:
+
+1. **Scan frontmatter first.** Read only the YAML frontmatter (`tags`, `area`, `category`) of each learning file to determine relevance. Only read the full body of learnings that match the current task.
+2. **Limit surfaced learnings.** Present at most 5 relevant learnings per consultation. If more are relevant, prioritize by confidence level (high > medium > low) and recency.
+3. **Cache consultation results.** If consultation was already performed for this task (e.g., during board-pickup), do not re-consult during skill execution. The orchestrator passes relevant learnings to subagents as part of prompt enrichment.
+4. **Skip when empty.** If `.agents/learnings/` has fewer than 3 files, consultation overhead exceeds value. Skip silently.

package/rules/hatch3r-migrations.md

@@ -2,8 +2,9 @@
 id: hatch3r-migrations
 type: rule
 description: Database migration and schema change patterns for the project
-scope: always
+scope: "**/migrations/**,**/*migration*,**/migrate/**,**/seeds/**,**/seeders/**,**/prisma/migrations/**,**/drizzle/**,**/knex/**"
 tags: [implementation, brownfield]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Migrations
 

package/rules/hatch3r-migrations.mdc

@@ -1,6 +1,6 @@
 ---
 description: Database migration and schema change patterns for the project
-alwaysApply: true
+globs: ["**/migrations/**", "**/*migration*", "**/migrate/**", "**/seeds/**", "**/seeders/**", "**/prisma/migrations/**", "**/drizzle/**", "**/knex/**"]
 ---
 # Migrations
 

package/rules/hatch3r-observability-logging.md

@@ -0,0 +1,34 @@
+---
+id: hatch3r-observability-logging
+type: rule
+description: Structured logging and error reporting conventions for the project
+scope: conditional
+globs: "**/*log*,**/*logger*,**/*logging*,**/*error*,**/observability/**"
+tags: [devops]
+quality_charter: agents/shared/quality-charter.md
+---
+# Observability -- Logging & Error Reporting
+
+Logging and error reporting conventions. For metrics, SLOs, alerting, and dashboards see `hatch3r-observability-metrics`. For distributed tracing and OpenTelemetry conventions see `hatch3r-observability-tracing`.
+
+## 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).
+
+## 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.

package/rules/hatch3r-observability-logging.mdc

@@ -0,0 +1,30 @@
+---
+description: Structured logging and error reporting conventions for the project
+globs: ["**/*log*", "**/*logger*", "**/*logging*", "**/*error*", "**/observability/**"]
+alwaysApply: false
+---
+# Observability -- Logging & Error Reporting
+
+Logging and error reporting conventions. For metrics, SLOs, alerting, and dashboards see `hatch3r-observability-metrics`. For distributed tracing and OpenTelemetry conventions see `hatch3r-observability-tracing`.
+
+## 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).
+
+## 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.

package/rules/hatch3r-observability-metrics.md

@@ -0,0 +1,74 @@
+---
+id: hatch3r-observability-metrics
+type: rule
+description: Metrics, SLO/SLI definitions, alerting, and dashboard conventions for the project
+scope: conditional
+globs: "**/*metric*,**/*slo*,**/*sli*,**/*alert*,**/*dashboard*,**/observability/**"
+tags: [devops]
+quality_charter: agents/shared/quality-charter.md
+---
+# Observability -- Metrics, SLOs & Alerting
+
+Metrics, SLO/SLI, alerting, and dashboard conventions. For structured logging see `hatch3r-observability-logging`. For distributed tracing and OpenTelemetry conventions see `hatch3r-observability-tracing`.
+
+## 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.
+
+## 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.

package/rules/hatch3r-observability-metrics.mdc

@@ -0,0 +1,70 @@
+---
+description: Metrics, SLO/SLI definitions, alerting, and dashboard conventions for the project
+globs: ["**/*metric*", "**/*slo*", "**/*sli*", "**/*alert*", "**/*dashboard*", "**/observability/**"]
+alwaysApply: false
+---
+# Observability -- Metrics, SLOs & Alerting
+
+Metrics, SLO/SLI, alerting, and dashboard conventions. For structured logging see `hatch3r-observability-logging`. For distributed tracing and OpenTelemetry conventions see `hatch3r-observability-tracing`.
+
+## 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.
+
+## 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.