hatch3r 1.0.0

package/rules/hatch3r-code-standards.md

@@ -0,0 +1,102 @@
+---
+id: hatch3r-code-standards
+type: rule
+description: Code quality and file naming conventions for the project
+scope: always
+---
+# Code Standards
+
+## Core Conventions
+
+- 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` (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.
+- Use design tokens for colors, spacing, typography. No ad-hoc styling.
+- All animations must respect `prefers-reduced-motion`.
+- Run lint and typecheck before committing.
+
+## TypeScript-Specific Patterns
+
+### `satisfies` Over `as`
+
+- Use `satisfies` to validate a value conforms to a type while preserving its narrower inferred type. Prefer `satisfies Config` over `as Config` because `as` silences type errors and loses narrowing.
+- Use `as const` for literal types in configuration objects, action types, and discriminant values. Combine with `satisfies` when both literal inference and shape validation are needed: `const config = { ... } as const satisfies Config`.
+
+### 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.
+
+### Branded Types
+
+- Use branded types for domain identifiers that must not be accidentally interchanged (e.g., `UserId`, `OrderId`, `Currency`). Implement via intersection with a unique symbol: `type UserId = string & { readonly __brand: unique symbol }`.
+- Provide factory functions (`createUserId(raw: string): UserId`) that validate the input before branding. Never brand raw values without validation.
+
+### Strict Utility Types
+
+- Prefer `Readonly<T>` for function parameters and return types that should not be mutated by the caller.
+- Use `Record<string, never>` instead of `{}` to represent an empty object type. `{}` matches any non-nullish value.
+- Avoid `Omit` with string literals that do not exist on the source type — use `satisfies` or a helper type that enforces key existence.
+
+## Architecture Patterns
+
+### Barrel Exports
+
+- Use barrel files (`index.ts`) at module boundaries to define the public API of a module. Re-export only the types and functions intended for external consumption.
+- Never import from a module's internal files directly — import from the barrel. Enforce with ESLint `no-restricted-imports` or equivalent.
+- Keep barrel files thin — only re-exports, no logic. A barrel with logic is a code smell.
+
+### Module Boundaries
+
+- Define clear module boundaries: each module owns its types, logic, and tests. Cross-module imports go through barrel exports.
+- Circular imports between modules are forbidden. Use dependency inversion (interfaces at the boundary) to break cycles.
+- Shared types used across modules live in a `types/` or `shared/` directory, not duplicated in each module.
+
+### Dependency Injection
+
+- Inject dependencies through constructor parameters or factory function arguments — not through global imports of concrete implementations.
+- Define dependencies as interfaces at the module boundary. Concrete implementations live inside the module.
+- This enables testability (inject fakes in tests) and flexibility (swap implementations without changing consumers).
+
+## Error Handling Patterns
+
+### Result Types
+
+- For operations that can fail in expected ways (validation, parsing, external calls), prefer returning a `Result<T, E>` discriminated union over throwing exceptions. Exceptions are for unexpected/unrecoverable failures.
+- Define a project-wide `Result` type: `type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E }`.
+- Callers must handle both variants — the type system enforces exhaustive error handling.
+
+### Custom Error Classes
+
+- Define domain-specific error classes extending a base `AppError` class. Include a machine-readable `code` field (string enum) for programmatic handling, separate from the human-readable `message`.
+- Error hierarchy example: `AppError` → `ValidationError`, `AuthError`, `NotFoundError`, `ConflictError`. Map error classes to HTTP status codes in the API layer.
+- Never throw raw `Error("message")` — always use a domain error class so error handlers can distinguish error types.
+
+### Error Boundaries
+
+- Catch errors at architectural boundaries: API route handlers, event handlers, background job processors, UI component error boundaries.
+- Log the full error (including stack trace) at the boundary. Return a safe, sanitized error response to the caller — no internal details.
+- Let errors propagate naturally within a module. Catching errors mid-flow and re-throwing obscures the stack trace. Handle at the boundary.
+
+## Import Ordering
+
+Enforce consistent import ordering via linter rules (e.g., `eslint-plugin-import`). The canonical order:
+
+1. **Built-in modules** — `node:fs`, `node:path`, etc.
+2. **External packages** — `zod`, `express`, etc.
+3. **Internal aliases** — `@/utils`, `@/types`, etc.
+4. **Relative imports** — `./sibling`, `../parent`, etc.
+5. **Type-only imports** — `import type { ... }` (grouped separately where the linter supports it)
+
+Separate each group with a blank line. Sort alphabetically within each group.
+
+## Dead Code Prevention
+
+- Remove unused imports, variables, functions, and type definitions immediately. Do not comment them out "for later."
+- Use the TypeScript compiler (`noUnusedLocals`, `noUnusedParameters`) and ESLint (`no-unused-vars`) to catch dead code automatically.
+- After removing a feature or completing a refactor, search for all references to the removed code. Delete orphaned tests, fixtures, and documentation.
+- Feature-flagged code that has been fully rolled out (flag removed) must have the flag-off branch deleted in the same PR.
+- Commented-out code is never acceptable in committed code. Use version control history to retrieve old implementations.

package/rules/hatch3r-code-standards.mdc

@@ -0,0 +1,100 @@
+---
+description: TypeScript and file naming conventions for the project
+alwaysApply: true
+---
+# Code Standards
+
+## Core Conventions
+
+- TypeScript strict mode. No `any`. No `@ts-ignore` without a linked issue.
+- Functions: `camelCase`. Types/Interfaces: `PascalCase`. Constants: `SCREAMING_SNAKE`.
+- Component files: `PascalCase` (match framework convention). Logic files: `camelCase.ts`.
+- 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.
+- Use design tokens for colors, spacing, typography. No ad-hoc styling.
+- All animations must respect `prefers-reduced-motion`.
+- Run lint and typecheck before committing.
+
+## TypeScript-Specific Patterns
+
+### `satisfies` Over `as`
+
+- Use `satisfies` to validate a value conforms to a type while preserving its narrower inferred type. Prefer `satisfies Config` over `as Config` because `as` silences type errors and loses narrowing.
+- Use `as const` for literal types in configuration objects, action types, and discriminant values. Combine with `satisfies` when both literal inference and shape validation are needed: `const config = { ... } as const satisfies Config`.
+
+### 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.
+
+### Branded Types
+
+- Use branded types for domain identifiers that must not be accidentally interchanged (e.g., `UserId`, `OrderId`, `Currency`). Implement via intersection with a unique symbol: `type UserId = string & { readonly __brand: unique symbol }`.
+- Provide factory functions (`createUserId(raw: string): UserId`) that validate the input before branding. Never brand raw values without validation.
+
+### Strict Utility Types
+
+- Prefer `Readonly<T>` for function parameters and return types that should not be mutated by the caller.
+- Use `Record<string, never>` instead of `{}` to represent an empty object type. `{}` matches any non-nullish value.
+- Avoid `Omit` with string literals that do not exist on the source type — use `satisfies` or a helper type that enforces key existence.
+
+## Architecture Patterns
+
+### Barrel Exports
+
+- Use barrel files (`index.ts`) at module boundaries to define the public API of a module. Re-export only the types and functions intended for external consumption.
+- Never import from a module's internal files directly — import from the barrel. Enforce with ESLint `no-restricted-imports` or equivalent.
+- Keep barrel files thin — only re-exports, no logic. A barrel with logic is a code smell.
+
+### Module Boundaries
+
+- Define clear module boundaries: each module owns its types, logic, and tests. Cross-module imports go through barrel exports.
+- Circular imports between modules are forbidden. Use dependency inversion (interfaces at the boundary) to break cycles.
+- Shared types used across modules live in a `types/` or `shared/` directory, not duplicated in each module.
+
+### Dependency Injection
+
+- Inject dependencies through constructor parameters or factory function arguments — not through global imports of concrete implementations.
+- Define dependencies as interfaces at the module boundary. Concrete implementations live inside the module.
+- This enables testability (inject fakes in tests) and flexibility (swap implementations without changing consumers).
+
+## Error Handling Patterns
+
+### Result Types
+
+- For operations that can fail in expected ways (validation, parsing, external calls), prefer returning a `Result<T, E>` discriminated union over throwing exceptions. Exceptions are for unexpected/unrecoverable failures.
+- Define a project-wide `Result` type: `type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E }`.
+- Callers must handle both variants — the type system enforces exhaustive error handling.
+
+### Custom Error Classes
+
+- Define domain-specific error classes extending a base `AppError` class. Include a machine-readable `code` field (string enum) for programmatic handling, separate from the human-readable `message`.
+- Error hierarchy example: `AppError` → `ValidationError`, `AuthError`, `NotFoundError`, `ConflictError`. Map error classes to HTTP status codes in the API layer.
+- Never throw raw `Error("message")` — always use a domain error class so error handlers can distinguish error types.
+
+### Error Boundaries
+
+- Catch errors at architectural boundaries: API route handlers, event handlers, background job processors, UI component error boundaries.
+- Log the full error (including stack trace) at the boundary. Return a safe, sanitized error response to the caller — no internal details.
+- Let errors propagate naturally within a module. Catching errors mid-flow and re-throwing obscures the stack trace. Handle at the boundary.
+
+## Import Ordering
+
+Enforce consistent import ordering via linter rules (e.g., `eslint-plugin-import`). The canonical order:
+
+1. **Built-in modules** — `node:fs`, `node:path`, etc.
+2. **External packages** — `zod`, `express`, etc.
+3. **Internal aliases** — `@/utils`, `@/types`, etc.
+4. **Relative imports** — `./sibling`, `../parent`, etc.
+5. **Type-only imports** — `import type { ... }` (grouped separately where the linter supports it)
+
+Separate each group with a blank line. Sort alphabetically within each group.
+
+## Dead Code Prevention
+
+- Remove unused imports, variables, functions, and type definitions immediately. Do not comment them out "for later."
+- Use the TypeScript compiler (`noUnusedLocals`, `noUnusedParameters`) and ESLint (`no-unused-vars`) to catch dead code automatically.
+- After removing a feature or completing a refactor, search for all references to the removed code. Delete orphaned tests, fixtures, and documentation.
+- Feature-flagged code that has been fully rolled out (flag removed) must have the flag-off branch deleted in the same PR.
+- Commented-out code is never acceptable in committed code. Use version control history to retrieve old implementations.

package/rules/hatch3r-component-conventions.md

@@ -0,0 +1,102 @@
+---
+description: Rules for component development in web applications
+globs: src/**/*.vue, src/**/*.tsx, src/**/*.jsx
+alwaysApply: false
+---
+# Component Conventions
+
+## Structure
+
+- Use framework-recommended component syntax (e.g., `<script setup>` for Vue).
+- Define props with typed interfaces.
+- Define emits/events with typed interfaces.
+- Use composables/hooks from project composables directory — never mixins.
+- Use stores or equivalent for shared state.
+
+## Naming
+
+- Component files: PascalCase (e.g., `PetWidget.vue`, `QuestPanel.vue`).
+- Component names match file names.
+- Props: camelCase. Events: kebab-case.
+
+## Styling
+
+- Use the project's design tokens for colors, spacing, typography.
+- Prefer utility classes or scoped CSS with BEM naming.
+- No inline styles except for dynamic values that can't be expressed as classes.
+- No hardcoded color values — use tokens.
+
+## Accessibility (Required)
+
+- All animations: wrap in `prefers-reduced-motion` media query AND check user's `reducedMotion` setting.
+- Color contrast: ≥ 4.5:1 for text (WCAG AA).
+- Interactive elements: keyboard focusable with visible focus indicator.
+- Dynamic content changes: use `aria-live` regions.
+- Support high contrast mode.
+
+## State Patterns (Required)
+
+### Loading States
+- Use skeleton screens (not spinners) for content areas — match the layout shape of the loaded content.
+- Apply a shimmer/pulse CSS animation on skeletons to indicate activity.
+- Load content progressively: show available data immediately, fill remaining sections as they resolve.
+- Buttons that trigger async actions must show an inline loading indicator (spinner + disabled state) and prevent double-click.
+
+### Error States
+- Wrap route-level components in an error boundary that catches render failures and displays a fallback UI.
+- Show inline error messages directly below the failed content area with a retry action button.
+- Use toast/notification for non-blocking errors (network hiccups, background sync failures) — auto-dismiss after 5–8 seconds with a manual dismiss option.
+- Failed components must never render a blank space — always show a fallback with a brief explanation and recovery action.
+
+### Empty States
+- Display an illustration or icon with a concise, helpful message explaining why the area is empty.
+- Include a primary action CTA that guides the user toward populating the area (e.g., "Create your first project").
+- Provide contextual guidance or links to documentation when relevant.
+- Differentiate "no data yet" (first-time experience) from "no results found" (active filter/search with a clear-filters action).
+
+### Transition States
+- Apply optimistic updates for mutations: reflect the expected outcome immediately, roll back on failure with an error toast.
+- Show a pending/saving indicator for in-flight mutations (e.g., subtle progress bar or "Saving..." text).
+- Use stale-while-revalidate patterns: display cached data immediately, update in the background, and indicate when a refresh is available.
+
+## Form UX (Required)
+
+### Validation Timing
+- Validate on blur for the user's initial input into a field.
+- After the first validation error, switch to validate on change so the user sees corrections in real time.
+- Always run full form validation on submit as a fallback.
+
+### Error Display
+- Show inline error messages directly below the field, linked via `aria-errormessage` and `aria-invalid="true"`.
+- Provide an error summary at the top of the form (linked to individual fields) for screen reader users.
+- Use a clear visual error indicator: red border + error icon + descriptive text — never rely on color alone.
+
+### Field Patterns
+- 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.
+
+### Submit Behavior
+- Disable the submit button when the form has known validation errors (but keep it focusable for screen readers).
+- Show a loading indicator on the submit button during submission.
+- Provide clear success feedback: redirect to the result page or display a success toast.
+- Prevent double submission by disabling the button and ignoring duplicate submit events during pending requests.
+
+### Accessible Labels
+- Every `<input>`, `<select>`, and `<textarea>` must have a visible `<label>` element with a matching `for`/`id` pair.
+- Mark required fields with a visual asterisk (`*`) and screen-reader-only text ("required").
+- Associate help text or format hints with the field via `aria-describedby`.
+
+## Performance
+
+- UI must render at 60fps (≤ 16ms per frame).
+- Prefer CSS animations/transitions over JavaScript animations.
+- Use conditional visibility (e.g., `v-show`) over conditional mount (e.g., `v-if`) for frequently toggled elements.
+- Lazy-load panels that aren't immediately visible.
+
+## Testing
+
+- Snapshot tests for all visual states.
+- Component tests for interactive behavior.
+- Verify reduced-motion behavior in tests.

package/rules/hatch3r-component-conventions.mdc

@@ -0,0 +1,102 @@
+---
+description: Rules for component development in web applications
+globs: src/**/*.vue, src/**/*.tsx, src/**/*.jsx
+alwaysApply: false
+---
+# Component Conventions
+
+## Structure
+
+- Use framework-recommended component syntax (e.g., `<script setup>` for Vue).
+- Define props with typed interfaces.
+- Define emits/events with typed interfaces.
+- Use composables/hooks from project composables directory — never mixins.
+- Use stores or equivalent for shared state.
+
+## Naming
+
+- Component files: PascalCase (e.g., `PetWidget.vue`, `QuestPanel.vue`).
+- Component names match file names.
+- Props: camelCase. Events: kebab-case.
+
+## Styling
+
+- Use the project's design tokens for colors, spacing, typography.
+- Prefer utility classes or scoped CSS with BEM naming.
+- No inline styles except for dynamic values that can't be expressed as classes.
+- No hardcoded color values — use tokens.
+
+## Accessibility (Required)
+
+- All animations: wrap in `prefers-reduced-motion` media query AND check user's `reducedMotion` setting.
+- Color contrast: ≥ 4.5:1 for text (WCAG AA).
+- Interactive elements: keyboard focusable with visible focus indicator.
+- Dynamic content changes: use `aria-live` regions.
+- Support high contrast mode.
+
+## State Patterns (Required)
+
+### Loading States
+- Use skeleton screens (not spinners) for content areas — match the layout shape of the loaded content.
+- Apply a shimmer/pulse CSS animation on skeletons to indicate activity.
+- Load content progressively: show available data immediately, fill remaining sections as they resolve.
+- Buttons that trigger async actions must show an inline loading indicator (spinner + disabled state) and prevent double-click.
+
+### Error States
+- Wrap route-level components in an error boundary that catches render failures and displays a fallback UI.
+- Show inline error messages directly below the failed content area with a retry action button.
+- Use toast/notification for non-blocking errors (network hiccups, background sync failures) — auto-dismiss after 5–8 seconds with a manual dismiss option.
+- Failed components must never render a blank space — always show a fallback with a brief explanation and recovery action.
+
+### Empty States
+- Display an illustration or icon with a concise, helpful message explaining why the area is empty.
+- Include a primary action CTA that guides the user toward populating the area (e.g., "Create your first project").
+- Provide contextual guidance or links to documentation when relevant.
+- Differentiate "no data yet" (first-time experience) from "no results found" (active filter/search with a clear-filters action).
+
+### Transition States
+- Apply optimistic updates for mutations: reflect the expected outcome immediately, roll back on failure with an error toast.
+- Show a pending/saving indicator for in-flight mutations (e.g., subtle progress bar or "Saving..." text).
+- Use stale-while-revalidate patterns: display cached data immediately, update in the background, and indicate when a refresh is available.
+
+## Form UX (Required)
+
+### Validation Timing
+- Validate on blur for the user's initial input into a field.
+- After the first validation error, switch to validate on change so the user sees corrections in real time.
+- Always run full form validation on submit as a fallback.
+
+### Error Display
+- Show inline error messages directly below the field, linked via `aria-errormessage` and `aria-invalid="true"`.
+- Provide an error summary at the top of the form (linked to individual fields) for screen reader users.
+- Use a clear visual error indicator: red border + error icon + descriptive text — never rely on color alone.
+
+### Field Patterns
+- 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.
+
+### Submit Behavior
+- Disable the submit button when the form has known validation errors (but keep it focusable for screen readers).
+- Show a loading indicator on the submit button during submission.
+- Provide clear success feedback: redirect to the result page or display a success toast.
+- Prevent double submission by disabling the button and ignoring duplicate submit events during pending requests.
+
+### Accessible Labels
+- Every `<input>`, `<select>`, and `<textarea>` must have a visible `<label>` element with a matching `for`/`id` pair.
+- Mark required fields with a visual asterisk (`*`) and screen-reader-only text ("required").
+- Associate help text or format hints with the field via `aria-describedby`.
+
+## Performance
+
+- UI must render at 60fps (≤ 16ms per frame).
+- Prefer CSS animations/transitions over JavaScript animations.
+- Use conditional visibility (e.g., `v-show`) over conditional mount (e.g., `v-if`) for frequently toggled elements.
+- Lazy-load panels that aren't immediately visible.
+
+## Testing
+
+- Snapshot tests for all visual states.
+- Component tests for interactive behavior.
+- Verify reduced-motion behavior in tests.

package/rules/hatch3r-data-classification.md

@@ -0,0 +1,85 @@
+---
+id: hatch3r-data-classification
+type: rule
+description: Data classification standards covering PII handling, encryption, retention policies, and regulatory compliance
+scope: always
+---
+# Data Classification Standards
+
+## Classification Levels
+
+| Level | Label | Examples | Handling |
+|-------|-------|----------|----------|
+| 1 | **Public** | Marketing content, open-source code, public docs | No restrictions |
+| 2 | **Internal** | Internal docs, non-sensitive configs, aggregated metrics | Access-controlled, no external sharing |
+| 3 | **Confidential** | PII, financial data, API keys, credentials | Encrypted at rest and in transit, audit-logged |
+| 4 | **Restricted** | SSN, payment card data, health records, biometrics | All Level 3 controls + additional access approval, data masking in non-production |
+
+## PII Handling
+
+- Identify and inventory all PII fields in the data model. Maintain a data map.
+- Minimize PII collection — only collect what's necessary for the stated purpose.
+- PII fields must be marked in the schema (annotation, decorator, or comment convention).
+- Never log PII. Use structured logging with PII fields explicitly excluded or masked.
+- Pseudonymize PII in analytics and reporting. Use irreversible hashing for identifiers.
+- Provide data export and deletion endpoints for data subject requests (GDPR Article 15/17, CCPA).
+
+## Encryption
+
+### At Rest
+- All Level 3+ data must be encrypted at rest using AES-256 or equivalent.
+- Use the cloud provider's managed encryption service (AWS KMS, GCP KMS, Azure Key Vault).
+- Database-level encryption is the minimum. Column-level encryption for highly sensitive fields.
+- Encryption keys must be rotated at least annually.
+
+### In Transit
+- All network communication uses TLS 1.2+ (prefer TLS 1.3).
+- Internal service-to-service communication also uses TLS — no plaintext even on private networks.
+- Certificate pinning for mobile and critical API clients.
+- HSTS headers on all web responses with a minimum max-age of 1 year.
+
+## Data Retention
+
+- Define retention periods per data category. Document in the data retention schedule.
+- Default retention: 90 days for logs, 1 year for transactional data, 3 years for financial records.
+- Implement automated deletion for data past its retention period.
+- Retention exceptions require written justification and legal review.
+- Backup retention aligns with source data retention — don't keep backups longer than the data policy allows.
+
+## Access Controls
+
+- Apply least-privilege access to all data stores.
+- Use role-based access control (RBAC) with named roles matching business functions.
+- Level 3+ data access requires multi-factor authentication.
+- Level 4 data access requires explicit per-request approval with audit trail.
+- Service accounts accessing Level 3+ data must use short-lived credentials (< 1 hour).
+- Review and recertify data access permissions quarterly.
+
+## Audit Logging
+
+- Log all access to Level 3+ data: who, what, when, from where.
+- Audit logs are immutable — write to append-only storage.
+- Retain audit logs for at least 1 year (or as required by applicable regulation).
+- Alert on anomalous access patterns: bulk reads, off-hours access, new IP addresses.
+- Audit log entries must include: timestamp, user/service identity, action, resource, result (success/failure).
+
+## Regulatory Compliance
+
+### GDPR
+- Maintain Records of Processing Activities (ROPA).
+- Implement consent management with granular per-purpose consent.
+- Support data portability (machine-readable export format).
+- 72-hour breach notification procedure documented and tested.
+
+### CCPA
+- Honor Do Not Sell requests.
+- Provide a clear privacy policy with data collection categories.
+- Support opt-out mechanisms for data sale/sharing.
+- Verify consumer identity before processing deletion or access requests.
+
+## Non-Production Environments
+
+- Never use production data in development or staging without anonymization.
+- Use synthetic data generators or anonymization pipelines for test data.
+- Level 4 data is never present in non-production environments under any circumstances.
+- Access to non-production environments follows the same RBAC model as production.

package/rules/hatch3r-data-classification.mdc

@@ -0,0 +1,83 @@
+---
+description: Data classification standards covering PII handling, encryption, retention policies, and regulatory compliance
+alwaysApply: true
+---
+# Data Classification Standards
+
+## Classification Levels
+
+| Level | Label | Examples | Handling |
+|-------|-------|----------|----------|
+| 1 | **Public** | Marketing content, open-source code, public docs | No restrictions |
+| 2 | **Internal** | Internal docs, non-sensitive configs, aggregated metrics | Access-controlled, no external sharing |
+| 3 | **Confidential** | PII, financial data, API keys, credentials | Encrypted at rest and in transit, audit-logged |
+| 4 | **Restricted** | SSN, payment card data, health records, biometrics | All Level 3 controls + additional access approval, data masking in non-production |
+
+## PII Handling
+
+- Identify and inventory all PII fields in the data model. Maintain a data map.
+- Minimize PII collection — only collect what's necessary for the stated purpose.
+- PII fields must be marked in the schema (annotation, decorator, or comment convention).
+- Never log PII. Use structured logging with PII fields explicitly excluded or masked.
+- Pseudonymize PII in analytics and reporting. Use irreversible hashing for identifiers.
+- Provide data export and deletion endpoints for data subject requests (GDPR Article 15/17, CCPA).
+
+## Encryption
+
+### At Rest
+- All Level 3+ data must be encrypted at rest using AES-256 or equivalent.
+- Use the cloud provider's managed encryption service (AWS KMS, GCP KMS, Azure Key Vault).
+- Database-level encryption is the minimum. Column-level encryption for highly sensitive fields.
+- Encryption keys must be rotated at least annually.
+
+### In Transit
+- All network communication uses TLS 1.2+ (prefer TLS 1.3).
+- Internal service-to-service communication also uses TLS — no plaintext even on private networks.
+- Certificate pinning for mobile and critical API clients.
+- HSTS headers on all web responses with a minimum max-age of 1 year.
+
+## Data Retention
+
+- Define retention periods per data category. Document in the data retention schedule.
+- Default retention: 90 days for logs, 1 year for transactional data, 3 years for financial records.
+- Implement automated deletion for data past its retention period.
+- Retention exceptions require written justification and legal review.
+- Backup retention aligns with source data retention — don't keep backups longer than the data policy allows.
+
+## Access Controls
+
+- Apply least-privilege access to all data stores.
+- Use role-based access control (RBAC) with named roles matching business functions.
+- Level 3+ data access requires multi-factor authentication.
+- Level 4 data access requires explicit per-request approval with audit trail.
+- Service accounts accessing Level 3+ data must use short-lived credentials (< 1 hour).
+- Review and recertify data access permissions quarterly.
+
+## Audit Logging
+
+- Log all access to Level 3+ data: who, what, when, from where.
+- Audit logs are immutable — write to append-only storage.
+- Retain audit logs for at least 1 year (or as required by applicable regulation).
+- Alert on anomalous access patterns: bulk reads, off-hours access, new IP addresses.
+- Audit log entries must include: timestamp, user/service identity, action, resource, result (success/failure).
+
+## Regulatory Compliance
+
+### GDPR
+- Maintain Records of Processing Activities (ROPA).
+- Implement consent management with granular per-purpose consent.
+- Support data portability (machine-readable export format).
+- 72-hour breach notification procedure documented and tested.
+
+### CCPA
+- Honor Do Not Sell requests.
+- Provide a clear privacy policy with data collection categories.
+- Support opt-out mechanisms for data sale/sharing.
+- Verify consumer identity before processing deletion or access requests.
+
+## Non-Production Environments
+
+- Never use production data in development or staging without anonymization.
+- Use synthetic data generators or anonymization pipelines for test data.
+- Level 4 data is never present in non-production environments under any circumstances.
+- Access to non-production environments follows the same RBAC model as production.

package/rules/hatch3r-dependency-management.md

@@ -0,0 +1,17 @@
+---
+id: hatch3r-dependency-management
+type: rule
+description: Rules for managing project dependencies
+scope: always
+---
+# Dependency Management
+
+- 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 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.

package/rules/hatch3r-dependency-management.mdc

@@ -0,0 +1,15 @@
+---
+description: Rules for managing npm dependencies in the project
+alwaysApply: false
+---
+# Dependency Management
+
+- Always commit `package-lock.json`. Never use `npm install --no-save`.
+- 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.
+- 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.

package/rules/hatch3r-error-handling.md

@@ -0,0 +1,17 @@
+---
+id: hatch3r-error-handling
+type: rule
+description: Error handling patterns and conventions for the project
+scope: always
+---
+# Error Handling
+
+- Define a structured error hierarchy: base error class with `code`, `message`, `cause`.
+- Never swallow errors silently. Always re-throw or log with context.
+- Use typed error codes (not raw strings). Reference codes in project glossary when applicable.
+- User-facing errors are separate from internal errors. Never expose internal details to clients.
+- Retry with exponential backoff for transient failures (network, rate limits). Honor `Retry-After` on 429.
+- API endpoints return structured error responses `{ code, message, details? }`. Never return stack traces.
+- Use framework error boundaries for UI components. Surface user-friendly fallback UI.
+- Include `correlationId` in all error logs for tracing across client and server.
+- Security: no secrets, tokens, or PII in error messages or logs.

package/rules/hatch3r-error-handling.mdc

@@ -0,0 +1,15 @@
+---
+description: Error handling patterns and conventions for the project
+alwaysApply: false
+---
+# Error Handling
+
+- Define a structured error hierarchy: base error class with `code`, `message`, `cause`.
+- Never swallow errors silently. Always re-throw or log with context.
+- Use typed error codes (not raw strings). Reference codes in project glossary when applicable.
+- User-facing errors are separate from internal errors. Never expose internal details to clients.
+- Retry with exponential backoff for transient failures (network, rate limits). Honor `Retry-After` on 429.
+- API endpoints return structured error responses `{ code, message, details? }`. Never return stack traces.
+- Use framework error boundaries for UI components. Surface user-friendly fallback UI.
+- Include `correlationId` in all error logs for tracing across client and server.
+- Security: no secrets, tokens, or PII in error messages or logs.