hatch3r 1.0.0

package/rules/hatch3r-feature-flags.md

@@ -0,0 +1,112 @@
+---
+description: Feature flag patterns and lifecycle for the project
+alwaysApply: false
+---
+# Feature Flags
+
+- Use flags for gradual rollout of user-facing changes. Not for A/B experiments without tracking.
+- Naming: `FF_{AREA}_{FEATURE}` (e.g., `FF_PET_NEW_CELEBRATION`).
+- Store flags in remote config or user document in your backend.
+- Client: evaluate with composable/hook. Server: evaluate before processing.
+- Every flag has an owner and cleanup deadline (max 30 days after full rollout).
+- Remove flag code when feature is fully rolled out. No dead branches.
+- Default to disabled. Safe fallback when flag evaluation fails.
+- Flags must not gate security or privacy features. Those are always on.
+- Document active flags in a tracking table (e.g., `.cursor/rules` or project specs).
+
+## Gradual Rollout Strategies
+
+- Percentage-based rollout: `1% → 5% → 25% → 50% → 100%`. Pause and monitor error rates at each step.
+- Cohort-based rollout: internal team → beta users → general availability. Define cohorts by user attribute, not random sampling.
+- Canary deployment: route a small traffic slice to the new code path. Promote only after health metrics stabilize.
+- Geographic rollout: enable by region when latency, compliance, or locale behavior varies.
+- Device-type targeting: roll out to web before mobile (or vice versa) when platform stability differs.
+- Never skip straight from 1% to 100%. Each step must hold for a minimum observation window (e.g., 24 hours).
+- Automate rollout progression when metrics (error rate, latency p99, crash-free rate) stay within thresholds.
+
+## Flag Dependencies
+
+- Model parent-child relationships when a feature flag gates a prerequisite for another flag.
+- Prerequisite flags must be enabled before dependents. Enforce at evaluation time—return disabled if any prerequisite is off.
+- Define mutual exclusion groups for flags that must not be active simultaneously (e.g., competing UI variants).
+- Validate the dependency graph on flag creation or update. Reject cycles and orphaned references.
+- Document dependencies in the flag tracking table so cleanup cascades are visible.
+- When removing a parent flag, verify all dependent flags are also cleaned up or re-parented.
+
+## Kill Switches
+
+- Every user-facing feature with a flag must have a corresponding kill switch that disables it instantly.
+- Kill switch naming: `KS_{AREA}_{FEATURE}`. Distinguish from rollout flags to avoid confusion.
+- Kill switches are permanent operational flags—they do not follow the 30-day cleanup deadline.
+- Integrate kill switches with circuit breakers: auto-disable when error rate or latency exceeds a threshold.
+- Define automatic rollback triggers in monitoring (e.g., 5xx rate > 2% for 5 minutes → disable flag).
+- Test kill switch behavior: verify the feature degrades gracefully and no data corruption occurs on disable.
+- Include kill switch activation in the incident response runbook. On-call must know which flags to toggle.
+
+## Stale Flag Detection
+
+- Automate alerts when a flag exceeds its cleanup deadline. Notify the flag owner and their team lead.
+- Track flag evaluation frequency. A flag evaluated zero times in 14 days is likely stale—investigate.
+- Detect always-on flags (100% rollout for > 30 days) and always-off flags (never enabled) via scheduled scans.
+- Lint for flag references in code. Flag identifiers with no code references are dead—remove from the config.
+- Maintain a cleanup workflow: alert → owner acknowledges → PR to remove flag code → config deletion → verify.
+- Enforce a hard cap on active flags per service (e.g., 30). Block new flag creation if the cap is reached until stale flags are cleaned up.
+
+## Flag Audit & Compliance
+
+- Log every flag state change with: who changed it, when, previous value, new value, and reason.
+- Require approval workflows for flags in production environments. No direct toggle without review.
+- Tag compliance-sensitive flags (e.g., flags affecting data collection, consent, or PII handling) for stricter review.
+- Retain audit logs for the project's required compliance period (minimum 90 days).
+- Maintain rollback history: store the last N states so a flag can be reverted to any prior configuration.
+- Review flag audit logs during incident post-mortems to correlate flag changes with outages.
+
+## Testing with Flags
+
+- Test both flag states (`on` and `off`) for every flag-gated code path. Include the default/fallback state.
+- Use parameterized tests to cover flag combinations without duplicating test logic.
+- CI runs a flag matrix for critical flags: each PR verifies the feature works in both states.
+- Integration tests must not depend on remote flag config. Use local overrides or test fixtures.
+- After full rollout, verify in production that the flag-off code path is unreachable before removing it.
+- Test kill switch activation in staging: simulate the disable and confirm graceful degradation.
+- Flag-related test failures block deployment. Treat them with the same severity as regular test failures.
+
+## OpenFeature Standard
+
+Use the [OpenFeature](https://openfeature.dev) SDK for provider-agnostic feature flag evaluation. OpenFeature defines a vendor-neutral API so application code is decoupled from the flag management backend.
+
+### Provider Interface
+
+- Implement the OpenFeature Provider interface to connect to your flag backend (LaunchDarkly, Flagsmith, CloudBees, environment variables, or a custom solution).
+- The provider must implement typed resolution methods: `resolveBooleanEvaluation`, `resolveStringEvaluation`, `resolveNumberEvaluation`, and `resolveObjectEvaluation`.
+- Each resolution returns a `ResolutionDetails` object containing the resolved `value`, an optional `variant` name, and a `reason` (e.g., `TARGETING_MATCH`, `DEFAULT`, `DISABLED`).
+- Register the provider at application startup: `OpenFeature.setProvider(new YourProvider())`. Only one provider is active at a time per client.
+- For testing, use the in-memory provider shipped with the SDK. Seed flag values in test setup without needing a real backend.
+
+### Evaluation Context
+
+- Evaluation context carries ambient information used for targeting and rule evaluation. Set it at three levels:
+  - **API-level (global):** Environment, application version, deployment region.
+  - **Client-level:** Service name, module identifier.
+  - **Invocation-level:** User ID, user role, tenant ID, request-specific attributes.
+- Contexts merge with invocation > client > API precedence. Invocation context overrides client, which overrides API.
+- Include a `targetingKey` in the context for consistent user-level targeting (e.g., user ID or session ID).
+- Keep context attributes minimal and non-sensitive. Never include passwords, tokens, or PII beyond what is necessary for targeting.
+
+### Hooks
+
+- Use OpenFeature hooks to add cross-cutting behavior at four lifecycle stages:
+  - **Before:** Enrich or validate evaluation context before the provider resolves the flag. Use for injecting common attributes.
+  - **After:** Log flag evaluation results, emit metrics, or trigger side effects after successful resolution.
+  - **Error:** Handle provider failures, log errors, and fall back to default values gracefully.
+  - **Finally:** Clean up resources or emit telemetry regardless of evaluation outcome.
+- Hook execution order: API hooks → client hooks → invocation hooks (for before/after). Reverse order for error/finally.
+- Use hooks for observability: emit a metric or structured log entry for every flag evaluation, including flag key, variant, and reason. This enables flag usage tracking and stale flag detection.
+- Use hooks for validation: enforce naming conventions, flag key format, or context completeness before evaluation.
+
+### Migration from Direct Provider SDKs
+
+- Replace direct provider SDK calls (e.g., `ldClient.variation()`) with OpenFeature client calls (`client.getBooleanValue()`).
+- Implement the OpenFeature Provider interface as a thin adapter around your existing provider SDK.
+- This enables switching providers (e.g., LaunchDarkly → Flagsmith) by swapping the provider implementation without changing application code.
+- During migration, both direct SDK calls and OpenFeature calls can coexist. Migrate incrementally by module.

package/rules/hatch3r-feature-flags.mdc

@@ -0,0 +1,112 @@
+---
+description: Feature flag patterns and lifecycle for the project
+alwaysApply: false
+---
+# Feature Flags
+
+- Use flags for gradual rollout of user-facing changes. Not for A/B experiments without tracking.
+- Naming: `FF_{AREA}_{FEATURE}` (e.g., `FF_PET_NEW_CELEBRATION`).
+- Store flags in remote config or user document in your backend.
+- Client: evaluate with composable/hook. Server: evaluate before processing.
+- Every flag has an owner and cleanup deadline (max 30 days after full rollout).
+- Remove flag code when feature is fully rolled out. No dead branches.
+- Default to disabled. Safe fallback when flag evaluation fails.
+- Flags must not gate security or privacy features. Those are always on.
+- Document active flags in a tracking table (e.g., `.cursor/rules` or project specs).
+
+## Gradual Rollout Strategies
+
+- Percentage-based rollout: `1% → 5% → 25% → 50% → 100%`. Pause and monitor error rates at each step.
+- Cohort-based rollout: internal team → beta users → general availability. Define cohorts by user attribute, not random sampling.
+- Canary deployment: route a small traffic slice to the new code path. Promote only after health metrics stabilize.
+- Geographic rollout: enable by region when latency, compliance, or locale behavior varies.
+- Device-type targeting: roll out to web before mobile (or vice versa) when platform stability differs.
+- Never skip straight from 1% to 100%. Each step must hold for a minimum observation window (e.g., 24 hours).
+- Automate rollout progression when metrics (error rate, latency p99, crash-free rate) stay within thresholds.
+
+## Flag Dependencies
+
+- Model parent-child relationships when a feature flag gates a prerequisite for another flag.
+- Prerequisite flags must be enabled before dependents. Enforce at evaluation time—return disabled if any prerequisite is off.
+- Define mutual exclusion groups for flags that must not be active simultaneously (e.g., competing UI variants).
+- Validate the dependency graph on flag creation or update. Reject cycles and orphaned references.
+- Document dependencies in the flag tracking table so cleanup cascades are visible.
+- When removing a parent flag, verify all dependent flags are also cleaned up or re-parented.
+
+## Kill Switches
+
+- Every user-facing feature with a flag must have a corresponding kill switch that disables it instantly.
+- Kill switch naming: `KS_{AREA}_{FEATURE}`. Distinguish from rollout flags to avoid confusion.
+- Kill switches are permanent operational flags—they do not follow the 30-day cleanup deadline.
+- Integrate kill switches with circuit breakers: auto-disable when error rate or latency exceeds a threshold.
+- Define automatic rollback triggers in monitoring (e.g., 5xx rate > 2% for 5 minutes → disable flag).
+- Test kill switch behavior: verify the feature degrades gracefully and no data corruption occurs on disable.
+- Include kill switch activation in the incident response runbook. On-call must know which flags to toggle.
+
+## Stale Flag Detection
+
+- Automate alerts when a flag exceeds its cleanup deadline. Notify the flag owner and their team lead.
+- Track flag evaluation frequency. A flag evaluated zero times in 14 days is likely stale—investigate.
+- Detect always-on flags (100% rollout for > 30 days) and always-off flags (never enabled) via scheduled scans.
+- Lint for flag references in code. Flag identifiers with no code references are dead—remove from the config.
+- Maintain a cleanup workflow: alert → owner acknowledges → PR to remove flag code → config deletion → verify.
+- Enforce a hard cap on active flags per service (e.g., 30). Block new flag creation if the cap is reached until stale flags are cleaned up.
+
+## Flag Audit & Compliance
+
+- Log every flag state change with: who changed it, when, previous value, new value, and reason.
+- Require approval workflows for flags in production environments. No direct toggle without review.
+- Tag compliance-sensitive flags (e.g., flags affecting data collection, consent, or PII handling) for stricter review.
+- Retain audit logs for the project's required compliance period (minimum 90 days).
+- Maintain rollback history: store the last N states so a flag can be reverted to any prior configuration.
+- Review flag audit logs during incident post-mortems to correlate flag changes with outages.
+
+## Testing with Flags
+
+- Test both flag states (`on` and `off`) for every flag-gated code path. Include the default/fallback state.
+- Use parameterized tests to cover flag combinations without duplicating test logic.
+- CI runs a flag matrix for critical flags: each PR verifies the feature works in both states.
+- Integration tests must not depend on remote flag config. Use local overrides or test fixtures.
+- After full rollout, verify in production that the flag-off code path is unreachable before removing it.
+- Test kill switch activation in staging: simulate the disable and confirm graceful degradation.
+- Flag-related test failures block deployment. Treat them with the same severity as regular test failures.
+
+## OpenFeature Standard
+
+Use the [OpenFeature](https://openfeature.dev) SDK for provider-agnostic feature flag evaluation. OpenFeature defines a vendor-neutral API so application code is decoupled from the flag management backend.
+
+### Provider Interface
+
+- Implement the OpenFeature Provider interface to connect to your flag backend (LaunchDarkly, Flagsmith, CloudBees, environment variables, or a custom solution).
+- The provider must implement typed resolution methods: `resolveBooleanEvaluation`, `resolveStringEvaluation`, `resolveNumberEvaluation`, and `resolveObjectEvaluation`.
+- Each resolution returns a `ResolutionDetails` object containing the resolved `value`, an optional `variant` name, and a `reason` (e.g., `TARGETING_MATCH`, `DEFAULT`, `DISABLED`).
+- Register the provider at application startup: `OpenFeature.setProvider(new YourProvider())`. Only one provider is active at a time per client.
+- For testing, use the in-memory provider shipped with the SDK. Seed flag values in test setup without needing a real backend.
+
+### Evaluation Context
+
+- Evaluation context carries ambient information used for targeting and rule evaluation. Set it at three levels:
+  - **API-level (global):** Environment, application version, deployment region.
+  - **Client-level:** Service name, module identifier.
+  - **Invocation-level:** User ID, user role, tenant ID, request-specific attributes.
+- Contexts merge with invocation > client > API precedence. Invocation context overrides client, which overrides API.
+- Include a `targetingKey` in the context for consistent user-level targeting (e.g., user ID or session ID).
+- Keep context attributes minimal and non-sensitive. Never include passwords, tokens, or PII beyond what is necessary for targeting.
+
+### Hooks
+
+- Use OpenFeature hooks to add cross-cutting behavior at four lifecycle stages:
+  - **Before:** Enrich or validate evaluation context before the provider resolves the flag. Use for injecting common attributes.
+  - **After:** Log flag evaluation results, emit metrics, or trigger side effects after successful resolution.
+  - **Error:** Handle provider failures, log errors, and fall back to default values gracefully.
+  - **Finally:** Clean up resources or emit telemetry regardless of evaluation outcome.
+- Hook execution order: API hooks → client hooks → invocation hooks (for before/after). Reverse order for error/finally.
+- Use hooks for observability: emit a metric or structured log entry for every flag evaluation, including flag key, variant, and reason. This enables flag usage tracking and stale flag detection.
+- Use hooks for validation: enforce naming conventions, flag key format, or context completeness before evaluation.
+
+### Migration from Direct Provider SDKs
+
+- Replace direct provider SDK calls (e.g., `ldClient.variation()`) with OpenFeature client calls (`client.getBooleanValue()`).
+- Implement the OpenFeature Provider interface as a thin adapter around your existing provider SDK.
+- This enables switching providers (e.g., LaunchDarkly → Flagsmith) by swapping the provider implementation without changing application code.
+- During migration, both direct SDK calls and OpenFeature calls can coexist. Migrate incrementally by module.

package/rules/hatch3r-git-conventions.md

@@ -0,0 +1,47 @@
+---
+id: hatch3r-git-conventions
+type: rule
+description: Git commit message and branching conventions
+scope: always
+---
+# Git Conventions
+
+## Commit Messages
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+type(scope)?: description
+
+[optional body]
+
+[optional footer(s)]
+```
+
+### Types
+- `feat` — new feature (triggers minor version bump)
+- `fix` — bug fix (triggers patch version bump)
+- `chore` — maintenance, dependencies, config
+- `docs` — documentation only
+- `refactor` — code change that neither fixes a bug nor adds a feature
+- `test` — adding or updating tests
+- `ci` — CI/CD configuration changes
+- `perf` — performance improvement
+- `build` — build system changes
+- `style` — formatting, whitespace (no logic change)
+
+### Rules
+- Subject line: imperative mood, lowercase, no period, max 72 characters
+- Body: wrap at 80 characters, explain what and why (not how)
+- Breaking changes: add `!` after type/scope and `BREAKING CHANGE:` footer
+- Reference issues: `Closes #123`, `Fixes #456`
+
+## Branch Naming
+
+Format: `{type}/{short-description}`
+
+Examples:
+- `feat/user-authentication`
+- `fix/null-pointer-on-login`
+- `chore/update-dependencies`
+- `refactor/extract-adapter-base`

package/rules/hatch3r-git-conventions.mdc

@@ -0,0 +1,45 @@
+---
+description: Git commit message and branching conventions
+alwaysApply: true
+---
+# Git Conventions
+
+## Commit Messages
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+type(scope)?: description
+
+[optional body]
+
+[optional footer(s)]
+```
+
+### Types
+- `feat` — new feature (triggers minor version bump)
+- `fix` — bug fix (triggers patch version bump)
+- `chore` — maintenance, dependencies, config
+- `docs` — documentation only
+- `refactor` — code change that neither fixes a bug nor adds a feature
+- `test` — adding or updating tests
+- `ci` — CI/CD configuration changes
+- `perf` — performance improvement
+- `build` — build system changes
+- `style` — formatting, whitespace (no logic change)
+
+### Rules
+- Subject line: imperative mood, lowercase, no period, max 72 characters
+- Body: wrap at 80 characters, explain what and why (not how)
+- Breaking changes: add `!` after type/scope and `BREAKING CHANGE:` footer
+- Reference issues: `Closes #123`, `Fixes #456`
+
+## Branch Naming
+
+Format: `{type}/{short-description}`
+
+Examples:
+- `feat/user-authentication`
+- `fix/null-pointer-on-login`
+- `chore/update-dependencies`
+- `refactor/extract-adapter-base`

package/rules/hatch3r-i18n.md

@@ -0,0 +1,90 @@
+---
+description: Internationalization, localization, and RTL support conventions for the project
+globs: src/**/*.vue, src/**/*.tsx, src/**/*.jsx, src/**/*.ts
+alwaysApply: false
+---
+# Internationalization & RTL
+
+## Locale Management
+
+- Detect locale via resolution chain: explicit user preference → `Accept-Language` header (server) → `navigator.language` (client) → default locale.
+- Define a fallback chain per locale (e.g., `fr-CA` → `fr` → `en`) and always resolve to a supported locale.
+- Persist user locale choice in user settings or `localStorage`; pass locale via URL segment or header — never infer from IP alone.
+- Load only the active locale's translations at runtime; lazy-load additional locales on demand.
+
+## Text & Translation
+
+- Use ICU MessageFormat syntax for plurals, gender, and select patterns (`{count, plural, one {# item} other {# items}}`).
+- Never embed HTML markup inside translation strings — pass components or slots as interpolation values instead.
+- Translation keys: use dot-separated, hierarchical namespaces matching feature structure (`settings.profile.title`, `cart.empty.message`).
+- Never concatenate translated fragments to build sentences — each complete sentence is a single translation key.
+- Maintain a string extraction workflow (e.g., `i18next-parser`, `vue-i18n-extract`) that runs in CI to flag unused and missing keys.
+
+## RTL Support
+
+- Use CSS logical properties exclusively: `margin-inline-start` (not `margin-left`), `padding-inline-end` (not `padding-right`), `inset-inline-start` (not `left`), `text-align: start` (not `text-align: left`).
+- Set `dir` and `lang` attributes on `<html>` dynamically based on active locale (`<html dir="rtl" lang="ar">`).
+- Use `dir="auto"` on user-generated content elements to let the Unicode Bidirectional Algorithm determine direction.
+- Mirror directional icons (arrows, chevrons, navigation cues) in RTL; do not mirror semantic icons (checkmarks, search, external link).
+- Use `logical` keyword for `resize`, `overflow`, and `float` where supported; provide fallbacks with `[dir="rtl"]` overrides where needed.
+
+## Number & Date Formatting
+
+- Format all numbers with `Intl.NumberFormat` — never manually insert thousands separators or decimal points.
+- Format all dates with `Intl.DateTimeFormat`; use relative time with `Intl.RelativeTimeFormat` for recent timestamps.
+- Format currency with `Intl.NumberFormat` using `style: 'currency'` and the correct currency code — never hard-code symbols.
+- Sort locale-sensitive strings with `Intl.Collator` — never use raw `String.prototype.localeCompare` without options.
+- Always pass the active locale to all `Intl` constructors.
+
+## Layout Accommodations
+
+- 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`.
+- 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.
+
+## Testing
+
+- Enable pseudo-localization (e.g., `[Ḿéššàĝé]`) during development to surface hardcoded strings and layout overflow.
+- Run RTL visual tests: render key pages with `dir="rtl"` and compare screenshots for layout correctness.
+- Add a CI check that verifies translation completeness: every key in the default locale exists in all target locales.
+- Compare screenshots across locales (especially German for expansion, Arabic for RTL, Japanese for CJK) at key viewport sizes.
+- Validate that all `Intl` formatting output is correct for edge-case locales (e.g., `ar-SA` for Hindu-Arabic numerals, `de-DE` for comma decimals).
+
+## ICU MessageFormat 2.0 (MF2)
+
+ICU MessageFormat 2.0 reached Final Candidate status in CLDR 46.1 (January 2025). MF2 is a significant evolution from MessageFormat 1.0, designed as a platform-independent specification with improved extensibility.
+
+### Key Syntax Changes from MF1
+
+- **Variable references** use `$` prefix: `{$userName}` instead of positional `{0}` arguments.
+- **Declarations** use `.input` and `.local` for explicit variable binding:
+  ```
+  .input {$count :number}
+  .local $formattedDate = {$date :datetime dateStyle=medium}
+  ```
+- **Selection** uses `.match` instead of nested `{value, select, ...}` / `{value, plural, ...}`:
+  ```
+  .input {$count :number}
+  .match $count
+  0   {{No items}}
+  one {{1 item}}
+  *   {{{$count} items}}
+  ```
+- **Functions** are invoked with `:functionName` syntax inside placeholders: `{$date :datetime dateStyle=long}`, `{$amount :number style=currency currency=USD}`.
+- **Markup** elements use `{#tag}` open, `{/tag}` close, and `{#tag /}` self-closing syntax for embedding structural elements without leaking HTML into translation strings.
+
+### Custom Function Registry
+
+- MF2 supports user-defined functions for domain-specific formatting. Register custom functions (e.g., `:relativeTime`, `:fileSize`, `:userName`) in the formatter's function registry.
+- Custom functions receive the resolved value and a map of named options. They must return a formatted string.
+- Document all custom functions in the project's i18n guide. Include: function name, accepted options, example usage, and expected output.
+
+### Adoption Guidance
+
+- **Runtime support:** As of early 2025, native browser/runtime support for MF2 is limited. Use the `messageformat` 4.0 npm package (or equivalent polyfill) for JavaScript/TypeScript.
+- **ICU libraries:** Java (ICU4J 76+) and C/C++ (ICU4C 76+) include tech preview MF2 implementations.
+- **Migration strategy:** New translation keys should use MF2 syntax. Existing MF1 keys can be migrated incrementally — both syntaxes can coexist during transition.
+- **Tooling:** Verify that your translation management system (TMS) supports MF2 syntax before migrating. Test with a small key set first.
+- **Stability:** The MF2 specification has stability guarantees post-approval (mid-2025). Syntax and semantics will not change incompatibly after that point.

package/rules/hatch3r-i18n.mdc

@@ -0,0 +1,90 @@
+---
+description: Internationalization, localization, and RTL support conventions for the project
+globs: src/**/*.vue, src/**/*.tsx, src/**/*.jsx, src/**/*.ts
+alwaysApply: false
+---
+# Internationalization & RTL
+
+## Locale Management
+
+- Detect locale via resolution chain: explicit user preference → `Accept-Language` header (server) → `navigator.language` (client) → default locale.
+- Define a fallback chain per locale (e.g., `fr-CA` → `fr` → `en`) and always resolve to a supported locale.
+- Persist user locale choice in user settings or `localStorage`; pass locale via URL segment or header — never infer from IP alone.
+- Load only the active locale's translations at runtime; lazy-load additional locales on demand.
+
+## Text & Translation
+
+- Use ICU MessageFormat syntax for plurals, gender, and select patterns (`{count, plural, one {# item} other {# items}}`).
+- Never embed HTML markup inside translation strings — pass components or slots as interpolation values instead.
+- Translation keys: use dot-separated, hierarchical namespaces matching feature structure (`settings.profile.title`, `cart.empty.message`).
+- Never concatenate translated fragments to build sentences — each complete sentence is a single translation key.
+- Maintain a string extraction workflow (e.g., `i18next-parser`, `vue-i18n-extract`) that runs in CI to flag unused and missing keys.
+
+## RTL Support
+
+- Use CSS logical properties exclusively: `margin-inline-start` (not `margin-left`), `padding-inline-end` (not `padding-right`), `inset-inline-start` (not `left`), `text-align: start` (not `text-align: left`).
+- Set `dir` and `lang` attributes on `<html>` dynamically based on active locale (`<html dir="rtl" lang="ar">`).
+- Use `dir="auto"` on user-generated content elements to let the Unicode Bidirectional Algorithm determine direction.
+- Mirror directional icons (arrows, chevrons, navigation cues) in RTL; do not mirror semantic icons (checkmarks, search, external link).
+- Use `logical` keyword for `resize`, `overflow`, and `float` where supported; provide fallbacks with `[dir="rtl"]` overrides where needed.
+
+## Number & Date Formatting
+
+- Format all numbers with `Intl.NumberFormat` — never manually insert thousands separators or decimal points.
+- Format all dates with `Intl.DateTimeFormat`; use relative time with `Intl.RelativeTimeFormat` for recent timestamps.
+- Format currency with `Intl.NumberFormat` using `style: 'currency'` and the correct currency code — never hard-code symbols.
+- Sort locale-sensitive strings with `Intl.Collator` — never use raw `String.prototype.localeCompare` without options.
+- Always pass the active locale to all `Intl` constructors.
+
+## Layout Accommodations
+
+- 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`.
+- 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.
+
+## Testing
+
+- Enable pseudo-localization (e.g., `[Ḿéššàĝé]`) during development to surface hardcoded strings and layout overflow.
+- Run RTL visual tests: render key pages with `dir="rtl"` and compare screenshots for layout correctness.
+- Add a CI check that verifies translation completeness: every key in the default locale exists in all target locales.
+- Compare screenshots across locales (especially German for expansion, Arabic for RTL, Japanese for CJK) at key viewport sizes.
+- Validate that all `Intl` formatting output is correct for edge-case locales (e.g., `ar-SA` for Hindu-Arabic numerals, `de-DE` for comma decimals).
+
+## ICU MessageFormat 2.0 (MF2)
+
+ICU MessageFormat 2.0 reached Final Candidate status in CLDR 46.1 (January 2025). MF2 is a significant evolution from MessageFormat 1.0, designed as a platform-independent specification with improved extensibility.
+
+### Key Syntax Changes from MF1
+
+- **Variable references** use `$` prefix: `{$userName}` instead of positional `{0}` arguments.
+- **Declarations** use `.input` and `.local` for explicit variable binding:
+  ```
+  .input {$count :number}
+  .local $formattedDate = {$date :datetime dateStyle=medium}
+  ```
+- **Selection** uses `.match` instead of nested `{value, select, ...}` / `{value, plural, ...}`:
+  ```
+  .input {$count :number}
+  .match $count
+  0   {{No items}}
+  one {{1 item}}
+  *   {{{$count} items}}
+  ```
+- **Functions** are invoked with `:functionName` syntax inside placeholders: `{$date :datetime dateStyle=long}`, `{$amount :number style=currency currency=USD}`.
+- **Markup** elements use `{#tag}` open, `{/tag}` close, and `{#tag /}` self-closing syntax for embedding structural elements without leaking HTML into translation strings.
+
+### Custom Function Registry
+
+- MF2 supports user-defined functions for domain-specific formatting. Register custom functions (e.g., `:relativeTime`, `:fileSize`, `:userName`) in the formatter's function registry.
+- Custom functions receive the resolved value and a map of named options. They must return a formatted string.
+- Document all custom functions in the project's i18n guide. Include: function name, accepted options, example usage, and expected output.
+
+### Adoption Guidance
+
+- **Runtime support:** As of early 2025, native browser/runtime support for MF2 is limited. Use the `messageformat` 4.0 npm package (or equivalent polyfill) for JavaScript/TypeScript.
+- **ICU libraries:** Java (ICU4J 76+) and C/C++ (ICU4C 76+) include tech preview MF2 implementations.
+- **Migration strategy:** New translation keys should use MF2 syntax. Existing MF1 keys can be migrated incrementally — both syntaxes can coexist during transition.
+- **Tooling:** Verify that your translation management system (TMS) supports MF2 syntax before migrating. Test with a small key set first.
+- **Stability:** The MF2 specification has stability guarantees post-approval (mid-2025). Syntax and semantics will not change incompatibly after that point.

package/rules/hatch3r-learning-consult.md

@@ -0,0 +1,29 @@
+---
+id: hatch3r-learning-consult
+type: rule
+description: Auto-consult project learnings before implementation
+scope: always
+---
+# Learning Consultation
+
+Before implementing any task, check `/.agents/learnings/` for relevant past learnings.
+
+## Consultation Process
+
+1. If `/.agents/learnings/` exists and contains files:
+   - Scan learning file frontmatter for matching `tags` or `area` that overlap with the current task.
+   - Read the `## Applies When` section of potential matches.
+   - Surface relevant learnings to the developer/agent before implementation begins.
+2. If no learnings directory exists, skip silently.
+
+## Integration Points
+
+- During `hatch3r-board-pickup` Step 6: consult learnings before implementation delegation.
+- During `hatch3r-board-fill` Step 4: consult learnings when scoping and estimating issues.
+- During any skill execution: check for relevant pitfalls before coding.
+
+## Learning Priority
+
+- **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.

package/rules/hatch3r-learning-consult.mdc

@@ -0,0 +1,27 @@
+---
+description: Auto-consult project learnings before implementation
+alwaysApply: true
+---
+# Learning Consultation
+
+Before implementing any task, check `/.agents/learnings/` for relevant past learnings.
+
+## Consultation Process
+
+1. If `/.agents/learnings/` exists and contains files:
+   - Scan learning file frontmatter for matching `tags` or `area` that overlap with the current task.
+   - Read the `## Applies When` section of potential matches.
+   - Surface relevant learnings to the developer/agent before implementation begins.
+2. If no learnings directory exists, skip silently.
+
+## Integration Points
+
+- During `hatch3r-board-pickup` Step 6: consult learnings before implementation delegation.
+- During `hatch3r-board-fill` Step 4: consult learnings when scoping and estimating issues.
+- During any skill execution: check for relevant pitfalls before coding.
+
+## Learning Priority
+
+- **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.

package/rules/hatch3r-migrations.md

@@ -0,0 +1,17 @@
+---
+id: hatch3r-migrations
+type: rule
+description: Database migration and schema change patterns for the project
+scope: always
+---
+# Migrations
+
+- Schema changes must be backward-compatible. Add fields with defaults; never remove or rename without migration.
+- Migration scripts live in a dedicated `migrations/` directory. One script per migration.
+- Every migration is idempotent. Safe to re-run. Use document version or `migratedAt` to skip.
+- Migration functions log progress and are resumable. Handle partial failures.
+- Test migrations against emulator or staging before deploying. Verify data integrity.
+- Order: deploy new code (handles old + new schema) → run migration → remove old schema handling.
+- 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.

package/rules/hatch3r-migrations.mdc

@@ -0,0 +1,15 @@
+---
+description: Database migration and schema change patterns for the project
+alwaysApply: false
+---
+# Migrations
+
+- Schema changes must be backward-compatible. Add fields with defaults; never remove or rename without migration.
+- Migration scripts live in a dedicated `migrations/` directory. One script per migration.
+- Every migration is idempotent. Safe to re-run. Use document version or `migratedAt` to skip.
+- Migration functions log progress and are resumable. Handle partial failures.
+- Test migrations against emulator or staging before deploying. Verify data integrity.
+- Order: deploy new code (handles old + new schema) → run migration → remove old schema handling.
+- 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.