@clipboard-health/ai-rules 1.6.44 → 1.7.1

package/backend/AGENTS.md

@@ -1,275 +1,676 @@
 <!-- Generated by Ruler -->
 
-<!-- Source: .ruler/backend/nestJsApis.md -->
+<!-- Source: .ruler/backend/architecture.md -->
+
+# Architecture
+
+## Three-Tier Architecture
+
+All NestJS microservices follow a three-tier layered architecture:
+
+```text
+┌─────────────────────────────────────────────────────────────────┐
+│  Entrypoints (Controllers, message consumers)                   │
+│  - HTTP request/response, JSON:API DTO translation, auth        │
+├─────────────────────────────────────────────────────────────────┤
+│  Logic (NestJS services, message publishers, background jobs)   │
+│  - ALL business logic; works with DOs only                      │
+│  - Knows nothing about HTTP or database specifics               │
+├─────────────────────────────────────────────────────────────────┤
+│  Data (Data repositories, gateways)                             │
+│  - Database via ORM (Prisma/Mongoose), DAO ↔ DO translation     │
+│  - External service integrations (Gateways)                     │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Module Structure:**
+
+```text
+modules/
+└── example/
+    ├── data/
+    │   ├── example.dao.mapper.ts
+    │   ├── example.repo.ts
+    │   └── notification.gateway.ts
+    ├── entrypoints/
+    │   ├── example.controller.ts
+    │   ├── example.consumer.ts
+    │   └── example.dto.mapper.ts
+    ├── logic/
+    │   ├── jobs/
+    │   │   └── exampleCreated.job.ts
+    │   ├── example.do.ts
+    │   └── example.service.ts
+    └── example.module.ts
+```
+
+**File Patterns:**
+
+```text
+*.controller.ts  - HTTP controllers (entrypoints)
+*.consumer.ts    - Message consumers (entrypoints)
+*.service.ts     - Business logic (logic)
+*.job.ts         - Background jobs (logic)
+*.repo.ts        - Database access (data)
+*.gateway.ts     - External services (data)
+*.do.ts          - Domain objects
+*.dto.mapper.ts  - DTO transformation
+*.dao.mapper.ts  - DAO transformation
+```
+
+**Tier Rules:**
+
+- Controllers → Services (never repos directly)
+- Services → Repos/Gateways within module (never controllers)
+- Repos → Database only (never services/repos/controllers)
+- Entry points are thin layers calling services
+- Enforce with `dependency-cruiser`
+
+**Microservices Principles:**
+
+- One domain = one module (bounded contexts)
+- Specific modules know about generic, not vice versa
+- Don't block Node.js thread—use background jobs for expensive operations
+
+<!-- Source: .ruler/backend/asyncMessagingBackgroundJobs.md -->
+
+# Async Messaging & Background Jobs
+
+## When to Use
+
+| Scenario                         | Solution          |
+| -------------------------------- | ----------------- |
+| Same service producer/consumer   | Background Jobs   |
+| Cross-service communication      | EventBridge + SQS |
+| Deferred work from API path      | Background Jobs   |
+| Replacing `void` fire-and-forget | Background Jobs   |
+| Scaling CRON jobs                | Background Jobs   |
+
+## Background Jobs
+
+**Creation with Transaction:**
+
+```typescript
+async function createLicense() {
+  await db.transaction(async (tx) => {
+    const license = await tx.license.create({ data });
+    await jobs.enqueue(VerificationJob, { licenseId: license.id }, { transaction: tx });
+  });
+}
+```
+
+**Handler Pattern:**
+
+```typescript
+class ShiftReminderJob implements Handler<ShiftReminderPayload> {
+  static queueName = "shift.reminder";
+
+  async perform(payload: ShiftReminderPayload, job: Job): Promise<string> {
+    const { shiftId } = payload;
+
+    // Fetch fresh data—don't trust stale payload
+    const shift = await this.shiftRepo.findById({ id: shiftId });
+
+    if (!shift || shift.isCancelled) {
+      return `Skipping: shift ${shiftId} not found or cancelled`;
+    }
+
+    try {
+      await this.notificationService.performSideEffect(shift);
+      return `Reminder sent for shift ${shiftId}`;
+    } catch (error) {
+      if (error instanceof KnownRecoverableError) throw error; // Retry
+      return `Skipping: ${error.message}`; // No retry
+    }
+  }
+}
+```
+
+**Key Practices:**
+
+- Pass minimal arguments (IDs, not objects)
+- Fetch fresh data in handler
+- Implement idempotency
+- Check state before action
+- Use Expand/Contract for job code updates
+
+**Avoid Circular Dependencies:**
+
+```typescript
+// Shared types file
+export const NOTIFICATION_JOB = "shift-notification";
+export interface NotificationJobPayload {
+  shiftId: string;
+}
+
+// Enqueue by string name
+await jobs.enqueue<NotificationJobPayload>(NOTIFICATION_JOB, { shiftId });
+```
+
+## SQS/EventBridge
+
+**Producer:** Single producer per message type, publish atomically (use jobs as outbox), deterministic message IDs, don't rely on strict ordering.
 
-# NestJS APIs
+**Consumer:** Own queue per consumer, must be idempotent, separate process from API, don't auto-consume DLQs.
 
-- Use a three-tier architecture:
-  - Controllers in the entrypoints tier translate from data transfer objects (DTOs) to domain objects (DOs) and call the logic tier.
-  - Logic tier services call other services in the logic tier and repos and gateways at the data tier. The logic tier operates only on DOs.
-  - Data tier repos translate from DOs to data access objects (DAOs), call the database using either Prisma for Postgres or Mongoose for MongoDB, and then translate from DAOs to DOs before returning to the logic tier.
-- Use ts-rest to define contracts using Zod schemas, one contract per resource.
-- A controller implements each ts-rest contract.
-- Requests and responses follow the JSON:API specification, including pagination for listings.
-- Use TypeDoc to document public functions, classes, methods, and complex code blocks.
+<!-- Source: .ruler/backend/databasePatterns.md -->
+
+# Database Patterns
+
+## MongoDB/Mongoose
+
+**ObjectId:**
+
+```typescript
+import mongoose, { Types, Schema } from "mongoose";
+
+const id = new Types.ObjectId();
+
+// In schemas
+const schema = new Schema({
+  authorId: { type: Schema.Types.ObjectId, ref: "User" },
+});
+
+// In interfaces
+interface Post {
+  authorId: Types.ObjectId;
+}
+
+// Validation
+if (mongoose.isObjectIdOrHexString(value)) {
+}
+```
+
+**Aggregations:**
+
+```typescript
+const result = await Users.aggregate<ResultType>()
+  .match({ active: true })
+  .group({ _id: "$department", count: { $sum: 1 } })
+  .project({ department: "$_id", count: 1 });
+```
+
+**Indexes:**
+
+- Add only when needed (slower writes tradeoff)
+- Apply via code only
+- Separate `indexes.ts` from `schema.ts`
+- Index definitions only in owning service
+- Set `autoIndex: false`
+- Design covering indexes for high-traffic queries
+
+```text
+models/User/
+├── schema.ts    # Schema only
+├── indexes.ts   # Indexes only
+└── index.ts     # Model export
+```
+
+**Verify query plans:**
+
+```typescript
+const explanation = await ShiftModel.find(query).explain("executionStats");
+// Check: totalDocsExamined ≈ totalDocsReturned
+// Good: stage 'IXSCAN'; Bad: stage 'COLLSCAN'
+```
+
+**Transactions:**
+
+```typescript
+const session = await mongoose.startSession();
+try {
+  session.startTransaction();
+  await Model.create([data], { session });
+  await session.commitTransaction();
+} catch (error) {
+  await session.abortTransaction();
+  throw error;
+} finally {
+  await session.endSession();
+}
+```
+
+## Repository Pattern
+
+```typescript
+class UserRepo {
+  // Named methods over generic CRUD
+  async findById(request: { id: UserId }): Promise<UserDo> {}
+  async findByEmail(request: { email: string }): Promise<UserDo> {}
+  async updateEmail(request: { id: UserId; email: string }): Promise<UserDo> {}
+}
+```
+
+<!-- Source: .ruler/backend/errorHandling.md -->
+
+# Error Handling
+
+## Service Errors
+
+```typescript
+import { ServiceError } from "@clipboard-health/util-ts";
+
+throw new ServiceError({
+  code: "SHIFT_NOT_FOUND",
+  message: `Shift ${shiftId} not found`,
+  httpStatus: 404,
+});
+```
+
+- Favor `Either` type for expected errors over `try/catch`
+- Guard clauses for preconditions
+- Early returns for error conditions
+- Happy path last
+
+## Controller Translation
+
+```typescript
+@UseFilters(HttpExceptionFilter)
+@Controller("shifts")
+export class ShiftController {}
+```
+
+## Background Job Errors
+
+```typescript
+async perform(payload: JobPayload): Promise<string> {
+  try {
+    // Main logic
+  } catch (error) {
+    if (error instanceof RecoverableError) throw error;  // Retry
+    return `Skipping: ${error.message}`;  // No retry
+  }
+}
+```
 
 <!-- Source: .ruler/backend/notifications.md -->
 
 # Notifications
 
-Send notifications through [Knock](https://docs.knock.app) using the `@clipboard-health/notifications` NPM library.
-
-## Usage
-
-<embedex source="packages/notifications/examples/usage.md">
-
-### `triggerChunked`
-
-`triggerChunked` stores the full, immutable trigger request at job enqueue time, eliminating issues with stale data, chunking requests to stay under provider limits, and idempotency key conflicts that can occur if the request is updated at job execution time.
-
-1. Search your service for `triggerNotification.constants.ts`, `triggerNotification.job.ts` and `notifications.service.ts`. If they don't exist, create them:
-
-   ```ts
-   // triggerNotification.constants.ts
-   export const TRIGGER_NOTIFICATION_JOB_NAME = "TriggerNotificationJob";
-   ```
-
-   ```ts
-   // triggerNotification.job.ts
-   import { type BaseHandler } from "@clipboard-health/background-jobs-adapter";
-   import {
-     type SerializableTriggerChunkedRequest,
-     toTriggerChunkedRequest,
-   } from "@clipboard-health/notifications";
-   import { isFailure } from "@clipboard-health/util-ts";
-
-   import { type NotificationsService } from "./notifications.service";
-   import { CBHLogger } from "./setup";
-   import { TRIGGER_NOTIFICATION_JOB_NAME } from "./triggerNotification.constants";
-
-   /**
-    * For @clipboard-health/mongo-jobs:
-    * 1. Implement `HandlerInterface<SerializableTriggerChunkedRequest>`.
-    * 2. The 10 default `maxAttempts` with exponential backoff of `2^attemptsCount` means ~17 minutes
-    *    of cumulative delay. If your notification could be stale before this, set
-    *    `SerializableTriggerChunkedRequest.expiresAt` when enqueueing.
-    *
-    * For @clipboard-health/background-jobs-postgres:
-    * 1. Implement `Handler<SerializableTriggerChunkedRequest>`.
-    * 2. The 20 default `maxRetryAttempts` with exponential backoff of `10s * 2^(attempt - 1)` means
-    *    ~121 days of cumulative delay. If your notification could be stale before this, set
-    *    `maxRetryAttempts` (and `SerializableTriggerChunkedRequest.expiresAt`) when enqueueing.
-    */
-   export class TriggerNotificationJob implements BaseHandler<SerializableTriggerChunkedRequest> {
-     // For background-jobs-postgres, use `public static queueName = TRIGGER_NOTIFICATION_JOB_NAME;`
-     public name = TRIGGER_NOTIFICATION_JOB_NAME;
-     private readonly logger = new CBHLogger({
-       defaultMeta: {
-         logContext: TRIGGER_NOTIFICATION_JOB_NAME,
-       },
-     });
-
-     public constructor(private readonly service: NotificationsService) {}
-
-     public async perform(
-       data: SerializableTriggerChunkedRequest,
-       /**
-        * For mongo-jobs, implement `BackgroundJobType<SerializableTriggerChunkedRequest>`, which has
-        *    `_id`, `attemptsCount`, and `uniqueKey`.
-        *
-        * For background-jobs-postgres, implement `Job<SerializableTriggerChunkedRequest>`, which has
-        *    `id`, `retryAttempts`, and `idempotencyKey`.
-        */
-       job: { _id: string; attemptsCount: number; uniqueKey?: string },
-     ) {
-       const metadata = {
-         // For background-jobs-postgres, this is called `retryAttempts`.
-         attempt: job.attemptsCount + 1,
-         jobId: job._id,
-         recipientCount: data.body.recipients.length,
-         workflowKey: data.workflowKey,
-       };
-       this.logger.info("TriggerNotificationJob processing", metadata);
-
-       try {
-         const request = toTriggerChunkedRequest(data, {
-           attempt: metadata.attempt,
-           idempotencyKey: job.uniqueKey ?? metadata.jobId,
-         });
-         const result = await this.service.triggerChunked(request);
-
-         if (isFailure(result)) {
-           throw result.error;
-         }
-
-         const success = "TriggerNotificationJob success";
-         this.logger.info(success, { ...metadata, response: result.value });
-         // For background-jobs-postgres, return the `success` string result.
-       } catch (error) {
-         this.logger.error("TriggerNotificationJob failure", { ...metadata, error });
-         throw error;
-       }
-     }
-   }
-   ```
-
-   ```ts
-   // notifications.service.ts
-   import { NotificationClient } from "@clipboard-health/notifications";
-
-   import { CBHLogger, toLogger, tracer } from "./setup";
-
-   export class NotificationsService {
-     private readonly client: NotificationClient;
-
-     constructor() {
-       this.client = new NotificationClient({
-         apiKey: "YOUR_KNOCK_API_KEY",
-         logger: toLogger(new CBHLogger()),
-         tracer,
-       });
-     }
-
-     async triggerChunked(
-       params: Parameters<NotificationClient["triggerChunked"]>[0],
-     ): ReturnType<NotificationClient["triggerChunked"]> {
-       return await this.client.triggerChunked(params);
-     }
-   }
-   ```
-
-2. Search the service for a constant that stores workflow keys. If there isn't one, create it:
-
-   ```ts
-   /* eslint sort-keys: "error" */
-
-   /**
-    * Alphabetical list of workflow keys.
-    */
-   export const WORKFLOW_KEYS = {
-     eventStartingReminder: "event-starting-reminder",
-   } as const;
-   ```
-
-3. Build your `SerializableTriggerChunkedRequest` and enqueue your job. Think of queuing `TriggerNotificationJob` as a function call to send notifications in a best practices way. You should NOT call `triggerChunked` directly. If, for example, your notification is delayed, create a background job that runs in the future, does any necessary checks to ensure you should notify, and then queue `TriggerNotificationJob`.
-
-   ```ts
-   import { type BackgroundJobsAdapter } from "@clipboard-health/background-jobs-adapter";
-   import { type SerializableTriggerChunkedRequest } from "@clipboard-health/notifications";
-
-   import { BackgroundJobsService } from "./setup";
-   import { TRIGGER_NOTIFICATION_JOB_NAME } from "./triggerNotification.constants";
-   import { WORKFLOW_KEYS } from "./workflowKeys";
-
-   /**
-    * Enqueue a notification job in the same database transaction as the changes it's notifying about.
-    * The `session` option is called `transaction` in `background-jobs-postgres`.
-    */
-   async function enqueueTriggerNotificationJob(adapter: BackgroundJobsAdapter) {
-     // Assume this comes from a database and are used as template variables...
-     const notificationData = {
-       favoriteColor: "blue",
-       // Use @clipboard-health/date-time's formatShortDateTime in your service for consistency.
-       favoriteAt: new Date().toISOString(),
-       secret: "2",
-     };
-
-     const jobData: SerializableTriggerChunkedRequest = {
-       // Important: Read the TypeDoc documentation for additional context.
-       body: {
-         recipients: ["userId-1", "userId-2"],
-         data: notificationData,
-       },
-       // Helpful when controlling notifications with feature flags.
-       dryRun: false,
-       // Set expiresAt at enqueue-time so it remains stable across job retries. Use date-fns in your
-       // service instead of this manual calculation.
-       expiresAt: new Date(Date.now() + 60 * 60_000).toISOString(),
-       // Keys to redact from logs
-       keysToRedact: ["secret"],
-       workflowKey: WORKFLOW_KEYS.eventStartingReminder,
-     };
-
-     // Option 1 (default): Automatically use background job ID as idempotency key.
-     await adapter.enqueue(TRIGGER_NOTIFICATION_JOB_NAME, jobData, { session: "..." });
-
-     // Option 2 (advanced): Provide custom idempotency key to job and notification libraries for more
-     // control. You'd use this to provide enqueue-time deduplication. For example, if you enqueue when
-     // a user clicks a button and only want them to receive one notification.
-     await adapter.enqueue(TRIGGER_NOTIFICATION_JOB_NAME, jobData, {
-       // Called `idempotencyKey` in `background-jobs-postgres`.
-       unique: `meeting-123-reminder`,
-       session: "...",
-     });
-   }
-
-   // eslint-disable-next-line unicorn/prefer-top-level-await
-   void enqueueTriggerNotificationJob(
-     // Use your instance of `@clipboard-health/mongo-jobs` or `@clipboard-health/background-jobs-postgres` here.
-     new BackgroundJobsService(),
-   );
-   ```
-
-</embedex>
-
-<!-- Source: .ruler/common/codeStyleAndStructure.md -->
-
-# Code style and structure
-
-- Write concise, technical TypeScript code with accurate examples.
-- Use functional and declarative programming patterns.
-- Prefer iteration and modularization over code duplication.
-- Use descriptive variable names with auxiliary verbs (e.g., isLoading, hasError).
-- Structure files: constants, types, exported functions, non-exported functions.
-- Avoid magic strings and numbers; define constants.
-- Use camelCase for files and directories (e.g., modules/shiftOffers.ts).
-- When declaring functions, use the `function` keyword, not `const`.
-- Files should read from top to bottom: `export`ed items live on top and the internal functions and methods they call go below them.
-- Prefer data immutability.
-
-# Commit messages
-
-- Follow the Conventional Commits 1.0 spec for commit messages and in pull request titles.
-
-<!-- Source: .ruler/common/errorHandlingAndValidation.md -->
-
-# Error handling and validation
-
-- Sanitize user input.
-- Handle errors and edge cases at the beginning of functions.
-- Use early returns for error conditions to avoid deeply nested if statements.
-- Place the happy path last in the function for improved readability.
-- Avoid unnecessary else statements; use the if-return pattern instead.
-- Use guard clauses to handle preconditions and invalid states early.
-- Implement proper error logging and user-friendly error messages.
-- Favor `@clipboard-health/util-ts`'s `Either` type for expected errors instead of `try`/`catch`.
+Send via [Knock](https://docs.knock.app) using `@clipboard-health/notifications`.
+
+Use `triggerChunked` to store full trigger request at job enqueue time. See package documentation for setup of `triggerNotification.job.ts`, `notifications.service.ts`, and workflow keys.
+
+**Job enqueue pattern:**
+
+```typescript
+const jobData: SerializableTriggerChunkedRequest = {
+  body: { recipients: ["userId-1"], data: notificationData },
+  expiresAt: new Date(Date.now() + 60 * 60_000).toISOString(),
+  keysToRedact: ["secret"],
+  workflowKey: WORKFLOW_KEYS.eventStartingReminder,
+};
+
+await adapter.enqueue(TRIGGER_NOTIFICATION_JOB_NAME, jobData, { session });
+```
+
+<!-- Source: .ruler/backend/restApiDesign.md -->
+
+# REST API Design
+
+## JSON:API Specification
+
+Follow [JSON:API spec](https://jsonapi.org/).
+
+```json
+{
+  "data": [
+    {
+      "id": "1",
+      "type": "worker",
+      "attributes": { "firstName": "Alex", "lastName": "Smith" }
+    }
+  ]
+}
+```
+
+- Singular `type` values: `"worker"` not `"workers"`
+- Links optional (use only for pagination)
+- Use `include` for related resources
+- Avoid `meta` unless necessary
+
+## URLs
+
+```text
+GET /urgent-shifts                    # lowercase kebab-case, plural nouns
+GET /workers/:workerId/shifts
+POST /workers/:workerId/referral-codes
+```
+
+## HTTP Methods
+
+| Method | Usage                              |
+| ------ | ---------------------------------- |
+| GET    | Retrieve (idempotent)              |
+| POST   | Create single resource, return DTO |
+| PATCH  | Update, return updated resource    |
+| DELETE | Remove                             |
+| PUT    | Not supported                      |
+
+## HTTP Status Codes
+
+| Code | Meaning                                                 |
+| ---- | ------------------------------------------------------- |
+| 200  | OK (GET, PATCH, DELETE)                                 |
+| 201  | Created (POST)                                          |
+| 202  | Accepted (async started)                                |
+| 400  | Bad Request (syntax error)                              |
+| 401  | Unauthorized (auth failed)                              |
+| 403  | Forbidden (authz failed)                                |
+| 404  | Not Found                                               |
+| 409  | Conflict (already exists)                               |
+| 422  | Unprocessable (semantic error, unsupported filter/sort) |
+| 429  | Rate limited                                            |
+| 500  | Server error                                            |
+
+## Filtering, Sorting, Pagination
+
+```text
+GET /shifts?filter[verified]=true&sort=startDate,-urgency&page[cursor]=abc&page[size]=50
+```
+
+- Cursor-based pagination only (not offset)
+- Avoid count totals (performance)
+- Only implement filters/sorts clients need
+
+## Contracts
+
+- Add contracts to `contract-<repo-name>` package
+- Use `ts-rest` with composable Zod schemas
+
+<!-- Source: .ruler/backend/serviceTests.md -->
+
+# Service Tests (Primary Testing Approach)
+
+Test the public contract (REST endpoints, events) with real local dependencies (Postgres, Mongo, Redis). Fake slow/external services (Zendesk, Stripe).
+
+```typescript
+describe("Documents", () => {
+  let tc: TestContext;
+
+  describe("GET /documents", () => {
+    it("returns existing documents for authenticated user", async () => {
+      // Arrange
+      const authToken = await tc.auth.createUser({ role: "employee" });
+      await tc.fixtures.createDocument({ name: "doc-1" });
+
+      // Act
+      const response = await tc.http.get("/documents", {
+        headers: { authorization: authToken },
+      });
+
+      // Assert
+      expect(response.statusCode).toBe(200);
+      expect(response.parsedBody.data).toHaveLength(1);
+    });
+  });
+});
+```
+
+**Qualities:** One behavior per test, no shared setup, no mocking, <1 second, parallelizable.
+
+<!-- Source: .ruler/common/commitMessages.md -->
+
+# Commit Messages
+
+Follow Conventional Commits 1.0 spec for commit messages and PR titles.
+
+<!-- Source: .ruler/common/configuration.md -->
+
+# Configuration
+
+```text
+Contains secrets?
+  └── Yes → SSM Parameter Store
+  └── No → Engineers-only, tolerate 1hr propagation?
+      └── Yes → Hardcode with @clipboard-health/config
+      └── No → 1:1 with DB entity OR needs custom UI?
+          └── Yes → Database
+          └── No → LaunchDarkly feature flag
+```
+
+<!-- Source: .ruler/common/featureFlags.md -->
+
+# Feature Flags
+
+**Naming:** `YYYY-MM-[kind]-[subject]` (e.g., `2024-03-release-new-booking-flow`)
+
+| Kind         | Purpose                  |
+| ------------ | ------------------------ |
+| `release`    | Gradual rollout to 100%  |
+| `enable`     | Kill switch              |
+| `experiment` | Trial for small audience |
+| `configure`  | Runtime config           |
+
+**Rules:**
+
+- "Off" = default/safer value
+- No permanent flags (except `configure`)
+- Create archival ticket when creating flag
+- Validate staging before production
+- Always provide default values in code
+- Clean up after full launch
+
+<!-- Source: .ruler/common/loggingObservability.md -->
+
+# Logging & Observability
+
+## Log Levels
+
+| Level | When                                       |
+| ----- | ------------------------------------------ |
+| ERROR | Required functionality broken (2am pager?) |
+| WARN  | Optional broken OR recovered from failure  |
+| INFO  | Informative, ignorable during normal ops   |
+| DEBUG | Local only, not production                 |
+
+## Best Practices
+
+```typescript
+// Bad
+logger.error("Operation failed");
+logger.error(`Operation failed for workplace ${workplaceId}`);
+
+// Good—structured context
+logger.error("Exporting urgent shifts to CSV failed", {
+  workplaceId,
+  startDate,
+  endDate,
+});
+```
+
+**Never log:** PII, PHI, tokens, secrets, SSN, account numbers, entire request/response/headers.
+
+Use metrics for counting:
+
+```typescript
+datadogMetrics.increment("negotiation.errors", { state: "New York" });
+```
+
+<!-- Source: .ruler/common/pullRequests.md -->
+
+# Pull Requests
+
+**Requirements:**
+
+1. Clear title: change summary + ticket; Conventional Commits 1.0
+2. Thorough description: why, not just what
+3. Small & focused: single concept
+4. Tested: service tests + validation proof
+5. Passing CI
+
+**Description:** Link ticket, context, reasoning, areas of concern.
+
+<!-- Source: .ruler/common/security.md -->
+
+# Security
+
+**Secrets:**
+
+- `.env` locally (gitignored)
+- Production: AWS SSM Parameter Store
+- Prefer short-lived tokens
+
+**Naming:** `[ENV]_[VENDOR]_[TYPE]_usedBy_[CLIENT]_[SCOPE]_[CREATED_AT]_[OWNER]`
+
+<!-- Source: .ruler/common/structuredConcurrency.md -->
+
+# Structured Concurrency
+
+```typescript
+// Cancellation propagation
+async function fetchWithTimeout(url: string, timeoutMs: number): Promise<Response> {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await fetch(url, { signal: controller.signal });
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+
+// All results regardless of failures
+const results = await Promise.allSettled(operations);
+const succeeded = results.filter((r) => r.status === "fulfilled");
+const failed = results.filter((r) => r.status === "rejected");
+```
 
 <!-- Source: .ruler/common/testing.md -->
 
 # Testing
 
-- Follow the Arrange-Act-Assert convention for tests with newlines between each section.
-- Name test variables using the `mockX`, `input`, `expected`, `actual` convention.
-- Aim for high test coverage, writing both positive and negative test cases.
-- Prefer `it.each` for multiple test cases.
-- Avoid conditional logic in tests.
+## Unit Tests
+
+Use when: error handling hard to trigger black-box, concurrency scenarios, >5 variations, pure function logic.
+
+## Conventions
+
+- Use `it` not `test`; `describe` for grouping
+- Arrange-Act-Assert with newlines between
+- Variables: `mockX`, `input`, `expected`, `actual`
+- Prefer `it.each` for multiple cases
+- No conditional logic in tests
 
 <!-- Source: .ruler/common/typeScript.md -->
 
-# TypeScript usage
-
-- Use strict-mode TypeScript for all code; prefer interfaces over types.
-- Avoid enums; use const maps instead.
-- Strive for precise types. Look for type definitions in the codebase and create your own if none exist.
-- Avoid using type assertions like `as` or `!` unless absolutely necessary.
-- Use the `unknown` type instead of `any` when the type is truly unknown.
-- Use an object to pass multiple function params and to return results.
-- Leverage union types, intersection types, and conditional types for complex type definitions.
-- Use mapped types and utility types (e.g., `Partial<T>`, `Pick<T>`, `Omit<T>`) to transform existing types.
-- Implement generic types to create reusable, flexible type definitions.
-- Utilize the `keyof` operator and index access types for dynamic property access.
-- Implement discriminated unions for type-safe handling of different object shapes where appropriate.
-- Use the `infer` keyword in conditional types for type inference.
-- Leverage `readonly` properties for function parameter immutability.
-- Prefer narrow types whenever possible with `as const` assertions, `typeof`, `instanceof`, `satisfies`, and custom type guards.
-- Implement exhaustiveness checking using `never`.
+# TypeScript
+
+## Naming Conventions
+
+| Element               | Convention            | Example                      |
+| --------------------- | --------------------- | ---------------------------- |
+| File-scope constants  | UPPER_SNAKE_CASE      | `MAX_RETRY_COUNT`            |
+| Acronyms in camelCase | Lowercase after first | `httpRequest`, `gpsPosition` |
+| Files                 | Singular, dotted      | `user.service.ts`            |
+
+## Core Rules
+
+- Strict-mode TypeScript; prefer interfaces over types
+- Avoid enums—use const maps
+- NEVER use `any`—use `unknown` or generics
+- Avoid type assertions (`as`, `!`) unless absolutely necessary
+- Use `function` keyword for declarations, not `const`
+- Prefer `undefined` over `null`
+- Explicit return types on functions
+- Files read top-to-bottom: exports first, internal helpers below
+- Boolean props: `is*`, `has*`, `should*`, `can*`
+- Use const assertions for constants: `as const`
+
+## Types
+
+```typescript
+// Strong typing
+function process(arg: unknown) {} // Better than any
+function process<T>(arg: T) {} // Best
+
+// Nullable checks
+if (foo == null) {
+} // Clear intent
+if (isDefined(foo)) {
+} // Better with utility
+
+// Quantity values—always unambiguous
+const money = { amountInMinorUnits: 500, currencyCode: "USD" };
+const durationMinutes = 30;
+```
+
+**Type Techniques:**
+
+- Union, intersection, conditional types for complex definitions
+- Mapped types: `Partial<T>`, `Pick<T>`, `Omit<T>`
+- `keyof`, index access types, discriminated unions
+- `as const`, `typeof`, `instanceof`, `satisfies`, type guards
+- Exhaustiveness checking with `never`
+- `readonly` for parameter immutability
+
+## Functions
+
+```typescript
+// Object arguments with interfaces
+interface CreateUserRequest {
+  email: string;
+  name?: string;
+}
+
+function createUser(request: CreateUserRequest): User {
+  const { email, name } = request; // Destructure inside
+  // ...
+}
+
+// Guard clauses for early returns
+function processOrder(order: Order): Result {
+  if (!order.isValid) {
+    return { error: "Invalid order" };
+  }
+  // Main logic
+}
+```
+
+## Objects & Arrays
+
+```typescript
+// Spread over Object.assign
+const updated = { ...original, name: "New Name" };
+
+// Array methods over loops (unless breaking early)
+const doubled = items.map((item) => item * 2);
+const sorted = items.toSorted((a, b) => a - b); // Immutable
+
+// For early exit
+for (const item of items) {
+  if (condition) break;
+}
+```
+
+## Async
+
+```typescript
+// async/await over .then()
+async function fetchData(): Promise<Data> {
+  const response = await api.get("/data");
+  return response.data;
+}
+
+// Parallel
+const results = await Promise.all(items.map(processItem));
+
+// Sequential (when needed)
+for (const item of items) {
+  // eslint-disable-next-line no-await-in-loop
+  await processItem(item);
+}
+```
+
+## Classes
+
+```typescript
+class UserService {
+  public async findById(request: FindByIdRequest): Promise<User> {}
+  private validateUser(user: User): boolean {}
+}
+
+// Extract pure functions outside classes
+function formatUserName(first: string, last: string): string {
+  return `${first} ${last}`;
+}
+```