@clipboard-health/ai-rules 1.7.8 → 1.7.10

package/backend/AGENTS.md

@@ -25,23 +25,43 @@ All NestJS microservices follow a three-tier layered architecture:
 
 **Module Structure:**
 
+`ts-rest` contracts:
+
+```text
+packages/contract-<service>/src/
+├── index.ts
+└── lib
+    ├── constants.ts
+    └── contracts
+        ├── contract.ts
+        ├── health.contract.ts
+        ├── index.ts
+        └── user
+            ├── index.ts
+            ├── user.contract.ts
+            └── shared.ts
+```
+
+NestJS microservice modules:
+
 ```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
+ src/modules/user
+ ├── user.module.ts
+ ├── data
+ │   ├── user.dao.mapper.ts
+ │   └── user.repo.ts
+ ├── entrypoints
+ │   ├── user.controller.ts
+ │   ├── user.dto.mapper.ts
+ │   └── userCreated.consumer.ts
+ └── logic
+     ├── user.do.ts
+     ├── user.service.ts
+     ├── userCreated.service.ts
+     └── jobs
+         ├── user.job.mapper.ts
+         ├── userCreated.job.spec.ts
+         └── userCreated.job.ts
 ```
 
 **File Patterns:**
@@ -61,7 +81,7 @@ modules/
 **Tier Rules:**
 
 - Controllers → Services (never repos directly)
-- Services → Repos/Gateways within module (never controllers)
+- Services → Repos/Gateways within module (never controllers and never Mongoose models directly)
 - Repos → Database only (never services/repos/controllers)
 - Entry points are thin layers calling services
 - Enforce with `dependency-cruiser`
@@ -201,9 +221,10 @@ const result = await Users.aggregate<ResultType>()
 
 ```text
 models/User/
-├── schema.ts    # Schema only
-├── indexes.ts   # Indexes only
-└── index.ts     # Model export
+├── schema.ts    # Schema definition, schemaName, InferSchemaType
+├── indexes.ts   # Index definitions only
+├── types.ts     # Re-export types
+└── index.ts     # Model creation and export
 ```
 
 **Verify query plans:**
@@ -261,6 +282,8 @@ throw new ServiceError({
 - Guard clauses for preconditions
 - Early returns for error conditions
 - Happy path last
+- Use `toError(unknownTypedError)` from `@clipboard-health/util-ts` over hardcoded strings or type casting (`as Error`)
+- Use `ERROR_CODES` from `@clipboard-health/util-ts`, not `HttpStatus` from NestJS
 
 ## Controller Translation
 
@@ -317,14 +340,22 @@ Follow [JSON:API spec](https://jsonapi.org/).
   "data": [
     {
       "id": "1",
-      "type": "worker",
-      "attributes": { "firstName": "Alex", "lastName": "Smith" }
+      "type": "shift",
+      "attributes": { "qualification": "nurse" },
+      "relationships": {
+        "assignedWorker": {
+          "data": { "type": "worker", "id": "9" }
+        },
+        "location": {
+          "data": { "type": "workplace", "id": "17" }
+        }
+      }
     }
   ]
 }
 ```
 
-- Singular `type` values: `"worker"` not `"workers"`
+- Singular `type` values: `shift` not `shifts`
 - Links optional (use only for pagination)
 - Use `include` for related resources
 - Avoid `meta` unless necessary
@@ -390,16 +421,13 @@ describe("Documents", () => {
 
   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);
     });
@@ -409,6 +437,24 @@ describe("Documents", () => {
 
 **Qualities:** One behavior per test, no shared setup, no mocking, <1 second, parallelizable.
 
+**Testing Background Jobs:**
+
+Don't spy on job enqueuing. Instead, run the job and assert side effects:
+
+```typescript
+// Run the job
+await tc.jobs.drainQueues("shift.reminder");
+
+// Assert side effects
+const shift = await tc.http.get(`/shifts/${shiftId}`);
+expect(shift.reminderSent).toBe(true);
+
+// Or check fakes for external calls
+expect(tc.fakes.notifications.requests).toHaveLength(1);
+```
+
+Side effects to assert: database changes, published messages, external HTTP requests.
+
 <!-- Source: .ruler/common/commitMessages.md -->
 
 # Commit Messages
@@ -429,6 +475,8 @@ Contains secrets?
           └── No → LaunchDarkly feature flag
 ```
 
+**NPM package management**: Use exact versions: add `save-exact=true` to `.npmrc`
+
 <!-- Source: .ruler/common/featureFlags.md -->
 
 # Feature Flags
@@ -451,6 +499,8 @@ Contains secrets?
 - Always provide default values in code
 - Clean up after full launch
 
+**When making feature flag changes**: include LaunchDarkly link: `https://app.launchdarkly.com/projects/default/flags/{flag-key}`
+
 <!-- Source: .ruler/common/loggingObservability.md -->
 
 # Logging & Observability
@@ -479,13 +529,23 @@ logger.error("Exporting urgent shifts to CSV failed", {
 });
 ```
 
-**Never log:** PII, PHI, tokens, secrets, SSN, account numbers, entire request/response/headers.
+- **Never log:** PII, PHI, tokens, secrets, SSN, account numbers, entire request/response/headers.
+- Use metrics for counting:
 
-Use metrics for counting:
+  ```typescript
+  datadogMetrics.increment("negotiation.errors", { state: "New York" });
+  ```
 
-```typescript
-datadogMetrics.increment("negotiation.errors", { state: "New York" });
-```
+- Log IDs or specific fields instead of full objects:
+  - `workerId` (not `agent`, `hcp`, `worker`)
+  - `shiftId` (not `shift`)
+- When multiple log statements share context, create a reusable `logContext` object:
+
+  ```typescript
+  const logContext = { shiftId, workerId };
+  logger.info("Processing shift", logContext);
+  logger.info("Notification sent", logContext);
+  ```
 
 <!-- Source: .ruler/common/pullRequests.md -->
 
@@ -557,13 +617,11 @@ Use when: error handling hard to trigger black-box, concurrency scenarios, >5 va
 
 ## Naming Conventions
 
-- Avoid acronyms and abbreviations unless widely known
-
-| Element                            | Convention            | Example                      |
-| ---------------------------------- | --------------------- | ---------------------------- |
-| File-scope constants               | UPPER_SNAKE_CASE      | `MAX_RETRY_COUNT`            |
-| Widely known acronyms in camelCase | Lowercase after first | `httpRequest`, `gpsPosition` |
-| Files                              | Singular, dotted      | `user.service.ts`            |
+- Avoid acronyms and abbreviations; for those widely known, use camelCase: `httpRequest`, `gpsPosition`, `cliArguments`, `apiResponse`
+- File-scoped constants: `MAX_RETRY_COUNT`
+- Instead of `agentRequirement`, `agentReq`, `workerType`, use `qualification`
+- Instead of `agent`, `hcp`, `healthcareProvider`, use `worker`
+- Instead of `facility`, `hcf`, `healthcareFacility`, use `workplace`
 
 ## Core Rules
 
@@ -577,6 +635,26 @@ Use when: error handling hard to trigger black-box, concurrency scenarios, >5 va
 - Files read top-to-bottom: exports first, internal helpers below
 - Boolean props: `is*`, `has*`, `should*`, `can*`
 - Use const assertions for constants: `as const`
+- Use `date-fns` for date/time manipulation and `@clipboard-health/date-time` for formatting
+
+## Null/Undefined Checks
+
+Use `isDefined` helper from `@clipboard-health/util-ts`:
+
+```typescript
+// Bad: truthy check fails for 0, "", false
+if (shiftId && facilityId) {
+}
+// Bad: use utility instead
+if (shift === null) {
+}
+if (facility === undefined) {
+}
+
+// Good: explicit defined check
+if (isDefined(shiftId) && isDefined(facilityId)) {
+}
+```
 
 ## Types
 
@@ -585,12 +663,6 @@ Use when: error handling hard to trigger black-box, concurrency scenarios, >5 va
 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;

package/common/AGENTS.md

@@ -20,6 +20,8 @@ Contains secrets?
           └── No → LaunchDarkly feature flag
 ```
 
+**NPM package management**: Use exact versions: add `save-exact=true` to `.npmrc`
+
 <!-- Source: .ruler/common/featureFlags.md -->
 
 # Feature Flags
@@ -42,6 +44,8 @@ Contains secrets?
 - Always provide default values in code
 - Clean up after full launch
 
+**When making feature flag changes**: include LaunchDarkly link: `https://app.launchdarkly.com/projects/default/flags/{flag-key}`
+
 <!-- Source: .ruler/common/loggingObservability.md -->
 
 # Logging & Observability
@@ -70,13 +74,23 @@ logger.error("Exporting urgent shifts to CSV failed", {
 });
 ```
 
-**Never log:** PII, PHI, tokens, secrets, SSN, account numbers, entire request/response/headers.
+- **Never log:** PII, PHI, tokens, secrets, SSN, account numbers, entire request/response/headers.
+- Use metrics for counting:
 
-Use metrics for counting:
+  ```typescript
+  datadogMetrics.increment("negotiation.errors", { state: "New York" });
+  ```
 
-```typescript
-datadogMetrics.increment("negotiation.errors", { state: "New York" });
-```
+- Log IDs or specific fields instead of full objects:
+  - `workerId` (not `agent`, `hcp`, `worker`)
+  - `shiftId` (not `shift`)
+- When multiple log statements share context, create a reusable `logContext` object:
+
+  ```typescript
+  const logContext = { shiftId, workerId };
+  logger.info("Processing shift", logContext);
+  logger.info("Notification sent", logContext);
+  ```
 
 <!-- Source: .ruler/common/pullRequests.md -->
 
@@ -148,13 +162,11 @@ Use when: error handling hard to trigger black-box, concurrency scenarios, >5 va
 
 ## Naming Conventions
 
-- Avoid acronyms and abbreviations unless widely known
-
-| Element                            | Convention            | Example                      |
-| ---------------------------------- | --------------------- | ---------------------------- |
-| File-scope constants               | UPPER_SNAKE_CASE      | `MAX_RETRY_COUNT`            |
-| Widely known acronyms in camelCase | Lowercase after first | `httpRequest`, `gpsPosition` |
-| Files                              | Singular, dotted      | `user.service.ts`            |
+- Avoid acronyms and abbreviations; for those widely known, use camelCase: `httpRequest`, `gpsPosition`, `cliArguments`, `apiResponse`
+- File-scoped constants: `MAX_RETRY_COUNT`
+- Instead of `agentRequirement`, `agentReq`, `workerType`, use `qualification`
+- Instead of `agent`, `hcp`, `healthcareProvider`, use `worker`
+- Instead of `facility`, `hcf`, `healthcareFacility`, use `workplace`
 
 ## Core Rules
 
@@ -168,6 +180,26 @@ Use when: error handling hard to trigger black-box, concurrency scenarios, >5 va
 - Files read top-to-bottom: exports first, internal helpers below
 - Boolean props: `is*`, `has*`, `should*`, `can*`
 - Use const assertions for constants: `as const`
+- Use `date-fns` for date/time manipulation and `@clipboard-health/date-time` for formatting
+
+## Null/Undefined Checks
+
+Use `isDefined` helper from `@clipboard-health/util-ts`:
+
+```typescript
+// Bad: truthy check fails for 0, "", false
+if (shiftId && facilityId) {
+}
+// Bad: use utility instead
+if (shift === null) {
+}
+if (facility === undefined) {
+}
+
+// Good: explicit defined check
+if (isDefined(shiftId) && isDefined(facilityId)) {
+}
+```
 
 ## Types
 
@@ -176,12 +208,6 @@ Use when: error handling hard to trigger black-box, concurrency scenarios, >5 va
 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;

package/frontend/AGENTS.md

@@ -20,6 +20,8 @@ Contains secrets?
           └── No → LaunchDarkly feature flag
 ```
 
+**NPM package management**: Use exact versions: add `save-exact=true` to `.npmrc`
+
 <!-- Source: .ruler/common/featureFlags.md -->
 
 # Feature Flags
@@ -42,6 +44,8 @@ Contains secrets?
 - Always provide default values in code
 - Clean up after full launch
 
+**When making feature flag changes**: include LaunchDarkly link: `https://app.launchdarkly.com/projects/default/flags/{flag-key}`
+
 <!-- Source: .ruler/common/loggingObservability.md -->
 
 # Logging & Observability
@@ -70,13 +74,23 @@ logger.error("Exporting urgent shifts to CSV failed", {
 });
 ```
 
-**Never log:** PII, PHI, tokens, secrets, SSN, account numbers, entire request/response/headers.
+- **Never log:** PII, PHI, tokens, secrets, SSN, account numbers, entire request/response/headers.
+- Use metrics for counting:
 
-Use metrics for counting:
+  ```typescript
+  datadogMetrics.increment("negotiation.errors", { state: "New York" });
+  ```
 
-```typescript
-datadogMetrics.increment("negotiation.errors", { state: "New York" });
-```
+- Log IDs or specific fields instead of full objects:
+  - `workerId` (not `agent`, `hcp`, `worker`)
+  - `shiftId` (not `shift`)
+- When multiple log statements share context, create a reusable `logContext` object:
+
+  ```typescript
+  const logContext = { shiftId, workerId };
+  logger.info("Processing shift", logContext);
+  logger.info("Notification sent", logContext);
+  ```
 
 <!-- Source: .ruler/common/pullRequests.md -->
 
@@ -148,13 +162,11 @@ Use when: error handling hard to trigger black-box, concurrency scenarios, >5 va
 
 ## Naming Conventions
 
-- Avoid acronyms and abbreviations unless widely known
-
-| Element                            | Convention            | Example                      |
-| ---------------------------------- | --------------------- | ---------------------------- |
-| File-scope constants               | UPPER_SNAKE_CASE      | `MAX_RETRY_COUNT`            |
-| Widely known acronyms in camelCase | Lowercase after first | `httpRequest`, `gpsPosition` |
-| Files                              | Singular, dotted      | `user.service.ts`            |
+- Avoid acronyms and abbreviations; for those widely known, use camelCase: `httpRequest`, `gpsPosition`, `cliArguments`, `apiResponse`
+- File-scoped constants: `MAX_RETRY_COUNT`
+- Instead of `agentRequirement`, `agentReq`, `workerType`, use `qualification`
+- Instead of `agent`, `hcp`, `healthcareProvider`, use `worker`
+- Instead of `facility`, `hcf`, `healthcareFacility`, use `workplace`
 
 ## Core Rules
 
@@ -168,6 +180,26 @@ Use when: error handling hard to trigger black-box, concurrency scenarios, >5 va
 - Files read top-to-bottom: exports first, internal helpers below
 - Boolean props: `is*`, `has*`, `should*`, `can*`
 - Use const assertions for constants: `as const`
+- Use `date-fns` for date/time manipulation and `@clipboard-health/date-time` for formatting
+
+## Null/Undefined Checks
+
+Use `isDefined` helper from `@clipboard-health/util-ts`:
+
+```typescript
+// Bad: truthy check fails for 0, "", false
+if (shiftId && facilityId) {
+}
+// Bad: use utility instead
+if (shift === null) {
+}
+if (facility === undefined) {
+}
+
+// Good: explicit defined check
+if (isDefined(shiftId) && isDefined(facilityId)) {
+}
+```
 
 ## Types
 
@@ -176,12 +208,6 @@ Use when: error handling hard to trigger black-box, concurrency scenarios, >5 va
 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;
@@ -560,7 +586,6 @@ export function Component({ userId, onUpdate }: Props) {
 
 ## Naming Conventions
 
-- Components: `PascalCase`
 - Event handlers: `handle*` (e.g., `handleClick`)
 - Props interface: `Props` (co-located) or `ComponentNameProps` (exported)
 

package/fullstack/AGENTS.md

@@ -25,23 +25,43 @@ All NestJS microservices follow a three-tier layered architecture:
 
 **Module Structure:**
 
+`ts-rest` contracts:
+
+```text
+packages/contract-<service>/src/
+├── index.ts
+└── lib
+    ├── constants.ts
+    └── contracts
+        ├── contract.ts
+        ├── health.contract.ts
+        ├── index.ts
+        └── user
+            ├── index.ts
+            ├── user.contract.ts
+            └── shared.ts
+```
+
+NestJS microservice modules:
+
 ```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
+ src/modules/user
+ ├── user.module.ts
+ ├── data
+ │   ├── user.dao.mapper.ts
+ │   └── user.repo.ts
+ ├── entrypoints
+ │   ├── user.controller.ts
+ │   ├── user.dto.mapper.ts
+ │   └── userCreated.consumer.ts
+ └── logic
+     ├── user.do.ts
+     ├── user.service.ts
+     ├── userCreated.service.ts
+     └── jobs
+         ├── user.job.mapper.ts
+         ├── userCreated.job.spec.ts
+         └── userCreated.job.ts
 ```
 
 **File Patterns:**
@@ -61,7 +81,7 @@ modules/
 **Tier Rules:**
 
 - Controllers → Services (never repos directly)
-- Services → Repos/Gateways within module (never controllers)
+- Services → Repos/Gateways within module (never controllers and never Mongoose models directly)
 - Repos → Database only (never services/repos/controllers)
 - Entry points are thin layers calling services
 - Enforce with `dependency-cruiser`
@@ -201,9 +221,10 @@ const result = await Users.aggregate<ResultType>()
 
 ```text
 models/User/
-├── schema.ts    # Schema only
-├── indexes.ts   # Indexes only
-└── index.ts     # Model export
+├── schema.ts    # Schema definition, schemaName, InferSchemaType
+├── indexes.ts   # Index definitions only
+├── types.ts     # Re-export types
+└── index.ts     # Model creation and export
 ```
 
 **Verify query plans:**
@@ -261,6 +282,8 @@ throw new ServiceError({
 - Guard clauses for preconditions
 - Early returns for error conditions
 - Happy path last
+- Use `toError(unknownTypedError)` from `@clipboard-health/util-ts` over hardcoded strings or type casting (`as Error`)
+- Use `ERROR_CODES` from `@clipboard-health/util-ts`, not `HttpStatus` from NestJS
 
 ## Controller Translation
 
@@ -317,14 +340,22 @@ Follow [JSON:API spec](https://jsonapi.org/).
   "data": [
     {
       "id": "1",
-      "type": "worker",
-      "attributes": { "firstName": "Alex", "lastName": "Smith" }
+      "type": "shift",
+      "attributes": { "qualification": "nurse" },
+      "relationships": {
+        "assignedWorker": {
+          "data": { "type": "worker", "id": "9" }
+        },
+        "location": {
+          "data": { "type": "workplace", "id": "17" }
+        }
+      }
     }
   ]
 }
 ```
 
-- Singular `type` values: `"worker"` not `"workers"`
+- Singular `type` values: `shift` not `shifts`
 - Links optional (use only for pagination)
 - Use `include` for related resources
 - Avoid `meta` unless necessary
@@ -390,16 +421,13 @@ describe("Documents", () => {
 
   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);
     });
@@ -409,6 +437,24 @@ describe("Documents", () => {
 
 **Qualities:** One behavior per test, no shared setup, no mocking, <1 second, parallelizable.
 
+**Testing Background Jobs:**
+
+Don't spy on job enqueuing. Instead, run the job and assert side effects:
+
+```typescript
+// Run the job
+await tc.jobs.drainQueues("shift.reminder");
+
+// Assert side effects
+const shift = await tc.http.get(`/shifts/${shiftId}`);
+expect(shift.reminderSent).toBe(true);
+
+// Or check fakes for external calls
+expect(tc.fakes.notifications.requests).toHaveLength(1);
+```
+
+Side effects to assert: database changes, published messages, external HTTP requests.
+
 <!-- Source: .ruler/common/commitMessages.md -->
 
 # Commit Messages
@@ -429,6 +475,8 @@ Contains secrets?
           └── No → LaunchDarkly feature flag
 ```
 
+**NPM package management**: Use exact versions: add `save-exact=true` to `.npmrc`
+
 <!-- Source: .ruler/common/featureFlags.md -->
 
 # Feature Flags
@@ -451,6 +499,8 @@ Contains secrets?
 - Always provide default values in code
 - Clean up after full launch
 
+**When making feature flag changes**: include LaunchDarkly link: `https://app.launchdarkly.com/projects/default/flags/{flag-key}`
+
 <!-- Source: .ruler/common/loggingObservability.md -->
 
 # Logging & Observability
@@ -479,13 +529,23 @@ logger.error("Exporting urgent shifts to CSV failed", {
 });
 ```
 
-**Never log:** PII, PHI, tokens, secrets, SSN, account numbers, entire request/response/headers.
+- **Never log:** PII, PHI, tokens, secrets, SSN, account numbers, entire request/response/headers.
+- Use metrics for counting:
 
-Use metrics for counting:
+  ```typescript
+  datadogMetrics.increment("negotiation.errors", { state: "New York" });
+  ```
 
-```typescript
-datadogMetrics.increment("negotiation.errors", { state: "New York" });
-```
+- Log IDs or specific fields instead of full objects:
+  - `workerId` (not `agent`, `hcp`, `worker`)
+  - `shiftId` (not `shift`)
+- When multiple log statements share context, create a reusable `logContext` object:
+
+  ```typescript
+  const logContext = { shiftId, workerId };
+  logger.info("Processing shift", logContext);
+  logger.info("Notification sent", logContext);
+  ```
 
 <!-- Source: .ruler/common/pullRequests.md -->
 
@@ -557,13 +617,11 @@ Use when: error handling hard to trigger black-box, concurrency scenarios, >5 va
 
 ## Naming Conventions
 
-- Avoid acronyms and abbreviations unless widely known
-
-| Element                            | Convention            | Example                      |
-| ---------------------------------- | --------------------- | ---------------------------- |
-| File-scope constants               | UPPER_SNAKE_CASE      | `MAX_RETRY_COUNT`            |
-| Widely known acronyms in camelCase | Lowercase after first | `httpRequest`, `gpsPosition` |
-| Files                              | Singular, dotted      | `user.service.ts`            |
+- Avoid acronyms and abbreviations; for those widely known, use camelCase: `httpRequest`, `gpsPosition`, `cliArguments`, `apiResponse`
+- File-scoped constants: `MAX_RETRY_COUNT`
+- Instead of `agentRequirement`, `agentReq`, `workerType`, use `qualification`
+- Instead of `agent`, `hcp`, `healthcareProvider`, use `worker`
+- Instead of `facility`, `hcf`, `healthcareFacility`, use `workplace`
 
 ## Core Rules
 
@@ -577,6 +635,26 @@ Use when: error handling hard to trigger black-box, concurrency scenarios, >5 va
 - Files read top-to-bottom: exports first, internal helpers below
 - Boolean props: `is*`, `has*`, `should*`, `can*`
 - Use const assertions for constants: `as const`
+- Use `date-fns` for date/time manipulation and `@clipboard-health/date-time` for formatting
+
+## Null/Undefined Checks
+
+Use `isDefined` helper from `@clipboard-health/util-ts`:
+
+```typescript
+// Bad: truthy check fails for 0, "", false
+if (shiftId && facilityId) {
+}
+// Bad: use utility instead
+if (shift === null) {
+}
+if (facility === undefined) {
+}
+
+// Good: explicit defined check
+if (isDefined(shiftId) && isDefined(facilityId)) {
+}
+```
 
 ## Types
 
@@ -585,12 +663,6 @@ Use when: error handling hard to trigger black-box, concurrency scenarios, >5 va
 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;
@@ -969,7 +1041,6 @@ export function Component({ userId, onUpdate }: Props) {
 
 ## Naming Conventions
 
-- Components: `PascalCase`
 - Event handlers: `handle*` (e.g., `handleClick`)
 - Props interface: `Props` (co-located) or `ComponentNameProps` (exported)
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@clipboard-health/ai-rules",
   "description": "Pre-built AI agent rules for consistent coding standards.",
-  "version": "1.7.8",
+  "version": "1.7.10",
   "bugs": "https://github.com/ClipboardHealth/core-utils/issues",
   "devDependencies": {
     "@intellectronica/ruler": "0.3.24"