hatch3r 1.3.0 → 1.5.0

package/rules/hatch3r-code-standards.mdc

@@ -6,9 +6,9 @@ alwaysApply: true
 
 ## Core Conventions
 
-- TypeScript strict mode. No `any`. No `@ts-ignore` without a linked issue.
+- Enable strict type checking. No type escape hatches (e.g., `any`, `@ts-ignore`, or equivalent) without a linked issue.
 - Functions: `camelCase`. Types/Interfaces: `PascalCase`. Constants: `SCREAMING_SNAKE`.
-- Component files: `PascalCase` (match framework convention). Logic files: `camelCase.ts`.
+- Component files: `PascalCase` (match framework convention). Logic files: `camelCase` (or language convention).
 - Max function length: 50 lines. Max file: 400 lines. Cyclomatic complexity: 10.
 - Use framework-recommended component patterns (e.g., typed props and emits).
 - Use stores or equivalent for shared state. Prefer composables/hooks over mixins.
@@ -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:
@@ -100,6 +112,14 @@ Enforce consistent import ordering via linter rules (e.g., `eslint-plugin-import
 
 Separate each group with a blank line. Sort alphabetically within each group.
 
+## Monorepo Conventions
+
+When working in a monorepo (multiple packages or apps in a single repository):
+
+- **Scope changes to a single package at a time.** A PR should touch one package unless the change requires a coordinated cross-package update (e.g., a shared type change and its consumers). Coordinated changes must be documented in the PR description.
+- **Run tests only for affected packages.** Use the monorepo tool's filtering (e.g., `--filter`, `--scope`, `--since`) to run tests, lint, and builds only for packages affected by the current change.
+- **Respect package boundaries — do not import across packages without explicit dependency.** If package A needs something from package B, B must be declared as a dependency in A's `package.json` (or equivalent manifest). Direct file-path imports across package boundaries are forbidden.
+
 ## Dead Code Prevention
 
 - Remove unused imports, variables, functions, and type definitions immediately. Do not comment them out "for later."

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,6 +1,6 @@
 ---
 description: Rules for component development in web applications
-globs: src/**/*.vue, src/**/*.tsx, src/**/*.jsx
+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

@@ -33,7 +33,9 @@ Score every task against these signals before implementation. Each signal adds w
 
 ### Tier 1 — Light
 
-Single-file changes, config tweaks, typo fixes, comment edits, constant value changes. No additional analysis required beyond existing researcher modes. Skip deep context analysis entirely.
+Single-file changes, config tweaks, typo fixes, comment edits, constant value changes. No additional analysis required beyond existing researcher modes.
+
+Skip deep context analysis entirely. Proceed with the standard pipeline.
 
 ### Tier 2 — Standard
 
@@ -42,7 +44,7 @@ Multi-file changes with clear scope. Run these researcher modes at `quick` depth
 1. **`requirements-elicitation`** at `quick` — scan for top ambiguities and ask 3–5 clarifying questions.
 2. **`similar-implementation`** at `quick` — find 1 reference implementation and extract top-level patterns.
 
-Present findings to the user inline. Proceed after answers are received.
+Present findings to the user inline. Proceed after answers are received — no separate confirmation checkpoint required.
 
 ### Tier 3 — Deep
 
@@ -52,18 +54,62 @@ Cross-module features, architectural changes, multi-layer implementations, or ta
 2. **`similar-implementation`** at `deep` — find 2–3 reference implementations, full convention extraction, divergence analysis.
 3. **`codebase-impact`** at `deep` — full transitive dependency tracing, API consumer map, blast radius summary.
 
-**Mandatory checkpoint:** Present a consolidated "Pre-Implementation Summary" to the user and ASK for confirmation before proceeding. Do NOT proceed until all unresolved questions are answered.
+**Mandatory checkpoint:** Present a consolidated "Pre-Implementation Summary" to the user and ASK for confirmation before proceeding to implementation:
+
+```
+Pre-Implementation Summary:
+  Complexity: Tier 3 (Deep) — score {N}
+  Resolved requirements: {N}/{M} dimensions addressed
+  Unresolved questions: {list — these MUST be answered before proceeding}
+  Reference implementation: {name} — conventions locked
+  Blast radius: {N} files directly affected, {M} transitively at risk
+  Cross-cutting concerns: {list with status}
+```
+
+Do NOT proceed to implementation until all unresolved questions are answered by the user.
 
 ## Passing Context to Implementer
 
-When the `similar-implementation` mode produces reference implementations, include them in the implementer sub-agent prompt as **"Reference Conventions"**. When the `requirements-elicitation` mode produces resolved requirements, include the user's answers as **"Resolved Requirements"**. When `codebase-impact` produces a blast radius summary, include it so the implementer knows which consumers and contracts must be preserved.
+When the `similar-implementation` mode produces reference implementations, include them in the implementer sub-agent prompt as **"Reference Conventions"**. The implementer's Convention Lock step (Step 1b) uses these to align its architectural decisions with established codebase patterns.
+
+When the `requirements-elicitation` mode produces resolved requirements, include the user's answers in the implementer sub-agent prompt as **"Resolved Requirements"** so the implementer has explicit answers to all ambiguities rather than guessing.
+
+When the enhanced `codebase-impact` mode produces a blast radius summary, include it in the implementer sub-agent prompt so the implementer knows which consumers and contracts must be preserved.
 
 ## Integration with Existing Pipeline
 
-This rule augments the existing Universal Sub-Agent Pipeline from `hatch3r-agent-orchestration`. The complexity scoring happens at the start of Phase 1 (Research), and the additional researcher modes run alongside the existing task-type modes.
+This rule augments — not replaces — the existing Universal Sub-Agent Pipeline from `hatch3r-agent-orchestration`. The complexity scoring happens at the start of Phase 1 (Research), and the additional researcher modes run alongside the existing task-type modes:
+
+- **`type:feature`**: existing modes `codebase-impact`, `feature-design`, `architecture` + new modes per tier
+- **`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`**: 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. 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`**: Operates on already-implemented code; deep context analysis applies to the original implementation.
+- **`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.
+- **`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,15 +1,27 @@
 ---
-description: Rules for managing npm dependencies in the project
-alwaysApply: false
+description: Rules for managing project dependencies
+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
 
-- Always commit `package-lock.json`. Never use `npm install --no-save`.
+- Always commit the lockfile. Never install without saving.
 - Justify new dependencies in PR description: what it does, why needed, alternatives considered, bundle size impact.
 - Prefer well-maintained packages: recent commits, active issues, no known CVEs.
-- Pin exact versions for production deps. Use `npm ci` in CI.
-- Run `npm audit` before merging dependency changes. Fix high/critical before merge.
+- Pin exact versions for production deps. Use clean install (e.g., `npm ci`, `pip install -r`, `cargo build`) in CI.
+- Run a dependency security scanner (e.g., `npm audit`, `pip-audit`, `cargo audit`) before merging dependency changes. Fix high/critical before merge.
 - No duplicate packages serving the same purpose. Consolidate on one.
 - Remove unused dependencies on every cleanup pass.
 - Security patches (CVEs) are P0/P1 priority. Patch within 48h for critical.
 - Check bundle size impact against budget. Reject deps that exceed.
+
+## Transitive Dependency Hygiene
+
+- Audit transitive dependencies, not just direct ones. A direct dependency with a compromised transitive dep is still a vulnerability. Use `npm ls`, `pip show`, or `cargo tree` to inspect the full dependency graph.
+- When a transitive dependency has a known CVE, determine whether the vulnerable code path is reachable from your project. If reachable, override or patch the transitive dep. If unreachable, document the finding with justification for deferral.
+- Avoid dependencies that pull in excessively large transitive trees for minimal functionality. If a package adds 50+ transitive deps for a single utility function, write the utility inline or find a lighter alternative.
+
+## Version Upgrade Strategy
+
+- Review changelogs and migration guides before upgrading major versions. Never blindly bump major versions and assume backward compatibility.
+- Run the full test suite after any dependency upgrade, including integration tests. A passing unit test suite does not guarantee compatibility with upgraded peer dependencies.
+- When upgrading a shared dependency used across multiple modules, upgrade all consumers in the same PR to avoid version skew within the monorepo or project.

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,6 +1,6 @@
 ---
 description: Internationalization, localization, and RTL support conventions for the project
-globs: src/**/*.vue, src/**/*.tsx, src/**/*.jsx, src/**/*.ts
+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: false
+globs: ["**/migrations/**", "**/*migration*", "**/migrate/**", "**/seeds/**", "**/seeders/**", "**/prisma/migrations/**", "**/drizzle/**", "**/knex/**"]
 ---
 # Migrations
 
@@ -13,3 +13,14 @@ alwaysApply: false
 - Document schema changes in project data model spec.
 - Rollback plan required for every migration. Never run destructive migrations without backup verification.
 - Hot documents must stay within size limits after migration.
+
+## Data Validation During Migration
+
+- Validate data integrity after each migration step, not just at the end. Check that migrated records match the expected schema, required fields are populated, and no data was silently dropped.
+- Include count checks: the number of records processed should match the number of records in the source collection. Log discrepancies as errors, not warnings.
+- For large datasets, migrate in batches with progress checkpoints. If a batch fails, resume from the last checkpoint rather than restarting the entire migration.
+
+## Migration Coordination in Multi-Service Environments
+
+- When a migration affects shared data (e.g., a schema used by multiple services), coordinate the migration order across services. The consuming services must be deployed with backward-compatible readers before the migration runs.
+- Never assume that all service instances will be running the same code version during a migration window. Design migrations to tolerate mixed-version reads and writes during the rollout period.

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.