# Global Development Rules

## Code Generation Rules

1. Never modify files outside your assigned module directory.
2. Prefer extending existing code over creating new abstractions.
3. Avoid introducing new dependencies without explicit developer approval.
4. All generated functions must include corresponding unit tests.
5. Avoid refactoring unrelated files.
6. If a change impacts another module, create an interface in `shared/` and request human review.
7. Keep functions under 40 lines.
8. Keep files under 400 lines.
9. Use strict typing — no `any` types, no implicit casts.

## Commit Rules

10. Each commit represents a single logical change.
11. Commit messages follow: `<type>(<module>): <description>`
12. Allowed types: feat, fix, test, refactor, docs, chore

## Documentation Rules

13. Documentation is limited to:
    - Module README.md (updated when public API changes)
    - Inline code comments for complex logic only
    - API contract files in `shared/interfaces/`
14. Do NOT generate verbose design documents or architecture overviews.
15. Do NOT generate changelog entries — CI handles this.

## Architecture Rules

16. Business logic belongs in services.
17. Persistence logic belongs in repositories.
18. Controllers must remain thin — validation and routing only.
19. No circular dependencies between modules.
20. Cross-module communication through interfaces defined in `shared/`.

# Testing Rules

## Mandatory Testing

1. Every code modification MUST include unit tests.
2. No PR will be merged without passing tests.
3. Test coverage target: 80% minimum per module.

## Test Structure

4. Tests are located in `tests/<module>/` mirroring `src/<module>/`.
5. Test file naming: `<source-file>.test.ts` (or equivalent).
6. Each test file tests one source file.

## Test Quality

7. Tests must be deterministic — no random data, no time-dependent assertions.
8. Mock external dependencies (databases, APIs, third-party services).
9. Cover edge cases: null inputs, empty collections, boundary values.
10. Test both success and error paths.

## Test Generation Behavior

11. When generating a new function, immediately generate its test file.
12. When modifying an existing function, update its existing tests.
13. When deleting a function, delete its tests.
14. Never generate tests that depend on other modules' internals.

---
inclusion: fileMatch
fileMatchPattern: "src/auth/**"
---

# Auth Module Rules

## Ownership
- Allowed directories: `src/auth/*`, `tests/auth/*`
- Forbidden directories: all other `src/` modules, `infra/`

## Architecture
- Authentication uses stateless JWT tokens
- Refresh token rotation is mandatory
- Password hashing uses bcrypt with minimum 12 rounds
- Sessions are NOT stored server-side

## Security
- Never log tokens or passwords
- Never return password hashes in API responses
- Token expiry: access = 15 min, refresh = 7 days
- Rate limit login attempts

---
inclusion: fileMatch
fileMatchPattern: "src/billing/**"
---

# Billing Module Rules

## Ownership
- Allowed directories: `src/billing/*`, `tests/billing/*`
- Forbidden directories: all other `src/` modules, `infra/`

## Architecture
- All monetary values use integer cents (no floating point)
- Currency is always explicit (no default currency assumption)
- Payment provider integration is abstracted behind an interface
- Invoice generation is idempotent

## Security
- Never log credit card numbers or payment tokens
- PCI compliance: no card data stored in application database

---
inclusion: fileMatch
fileMatchPattern: "src/orders/**"
---

# Orders Module Rules

## Ownership
- Allowed directories: `src/orders/*`, `tests/orders/*`
- Forbidden directories: all other `src/` modules, `infra/`

## Architecture
- Orders follow a state machine: created → confirmed → shipped → delivered → completed
- State transitions are validated — no skipping states
- Order totals are recalculated server-side (never trust client values)
- Inventory checks happen at confirmation time

---
inclusion: fileMatch
fileMatchPattern: "infra/**"
---

# Infrastructure Rules

## Terraform
- All resources must be in Terraform modules — no inline resources
- Use remote state (S3 + DynamoDB locking)
- Tag all resources with: project, environment, module, managed-by
- No hardcoded values — use variables with defaults

## Security
- No secrets in Terraform files — use AWS Secrets Manager or SSM Parameter Store
- IAM policies follow least privilege
- Security groups default to deny-all inbound

## Naming Convention
- Resources: `{project}-{environment}-{module}-{resource-type}`
- Example: `myapp-prod-auth-ecs-service`