@clipboard-health/ai-rules 1.6.44 → 1.7.0

package/frontend/AGENTS.md

@@ -1,1039 +1,729 @@
 <!-- Generated by Ruler -->
 
-<!-- Source: .ruler/common/codeStyleAndStructure.md -->
+<!-- Source: .ruler/common/commitMessages.md -->
 
-# Code style and structure
+# Commit Messages
 
-- 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.
+Follow Conventional Commits 1.0 spec for commit messages and PR titles.
 
-# Commit messages
+<!-- Source: .ruler/common/configuration.md -->
 
-- Follow the Conventional Commits 1.0 spec for commit messages and in pull request titles.
+# Configuration
 
-<!-- Source: .ruler/common/errorHandlingAndValidation.md -->
+```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
+```
 
-# Error handling and validation
+<!-- Source: .ruler/common/featureFlags.md -->
 
-- 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`.
+# Feature Flags
 
-<!-- Source: .ruler/common/testing.md -->
+**Naming:** `YYYY-MM-[kind]-[subject]` (e.g., `2024-03-release-new-booking-flow`)
 
-# Testing
+| Kind         | Purpose                  |
+| ------------ | ------------------------ |
+| `release`    | Gradual rollout to 100%  |
+| `enable`     | Kill switch              |
+| `experiment` | Trial for small audience |
+| `configure`  | Runtime config           |
 
-- 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.
+**Rules:**
 
-<!-- Source: .ruler/common/typeScript.md -->
+- "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
 
-# TypeScript usage
+<!-- Source: .ruler/common/loggingObservability.md -->
 
-- 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`.
+# Logging & Observability
 
-<!-- Source: .ruler/frontend/custom-hooks.md -->
+## Log Levels
 
-# Custom Hook Standards
+| 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                 |
 
-## Hook Structure
+## Best Practices
 
 ```typescript
-export function useFeature(params: Params, options: UseFeatureOptions = {}) {
-  const query = useQuery(...);
-  const computed = useMemo(() => transformData(query.data), [query.data]);
-  const handleAction = useCallback(async () => { /* ... */ }, []);
+// Bad
+logger.error("Operation failed");
+logger.error(`Operation failed for workplace ${workplaceId}`);
 
-  return { data: computed, isLoading: query.isLoading, handleAction };
-}
+// Good—structured context
+logger.error("Exporting urgent shifts to CSV failed", {
+  workplaceId,
+  startDate,
+  endDate,
+});
 ```
 
-## Naming Rules
-
-- **Always** prefix with `use`
-- Boolean: Use `useIs*`, `useHas*`, or `useCan*` (e.g., `useIsEnabled`, `useHasPermission`, `useCanEdit`)
-- Data: `useGetUser`, `useFeatureData`
-- Actions: `useSubmitForm`
+**Never log:** PII, PHI, tokens, secrets, SSN, account numbers, entire request/response/headers.
 
-## Return Values
-
-- Return objects (not arrays) for complex hooks
-- Name clearly: `isLoading` not `loading`
-
-## State Management with Constate
-
-Use `constate` for shared state between components:
+Use metrics for counting:
 
 ```typescript
-import constate from "constate";
-
-function useFilters() {
-  const [filters, setFilters] = useState<Filters>({});
-  return { filters, setFilters };
-}
-
-export const [FiltersProvider, useFiltersContext] = constate(useFilters);
+datadogMetrics.increment("negotiation.errors", { state: "New York" });
 ```
 
-**When to use:** Sharing state between siblings, feature-level state
-**When NOT:** Server state (use React Query), simple parent-child (use props)
+<!-- Source: .ruler/common/pullRequests.md -->
 
-## Hook Patterns
+# Pull Requests
 
-```typescript
-// Boolean hooks
-export function useIsFeatureEnabled(): boolean {
-  return useFeatureFlags().includes("feature");
-}
+**Requirements:**
 
-// Data transformation
-export function useTransformedData() {
-  const { data, isLoading } = useGetRawData();
-  const transformed = useMemo(() => data?.map(format), [data]);
-  return { data: transformed, isLoading };
-}
+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
 
-// Composite hooks
-export function useBookingsData() {
-  const shifts = useGetShifts();
-  const invites = useGetInvites();
+**Description:** Link ticket, context, reasoning, areas of concern.
 
-  const combined = useMemo(
-    () => [...(shifts.data ?? []), ...(invites.data ?? [])],
-    [shifts.data, invites.data],
-  );
+<!-- Source: .ruler/common/security.md -->
 
-  return { data: combined, isLoading: shifts.isLoading || invites.isLoading };
-}
-```
+# Security
 
-## Best Practices
+**Secrets:**
 
-- Use options object for flexibility
-- Be explicit about dependencies
-- API hooks in `api/`, logic hooks in `hooks/`
-- Return stable references with `useCallback`/`useMemo`
+- `.env` locally (gitignored)
+- Production: AWS SSM Parameter Store
+- Prefer short-lived tokens
 
-<!-- Source: .ruler/frontend/data-fetching.md -->
+**Naming:** `[ENV]_[VENDOR]_[TYPE]_usedBy_[CLIENT]_[SCOPE]_[CREATED_AT]_[OWNER]`
 
-# Data Fetching Standards
+<!-- Source: .ruler/common/structuredConcurrency.md -->
 
-## Technology Stack
-
-- **React Query** (@tanstack/react-query) for all API calls
-- **Zod** for response validation
-
-## Core Principles
-
-1. **Use URL and query parameters in query keys** - Makes cache invalidation predictable
-2. **Define Zod schemas** for all API requests/responses
-3. **Rely on React Query state** - Use `isLoading`, `isError`, `isSuccess`
-4. **Use `enabled` for conditional fetching**
-5. **Use `invalidateQueries` for disabled queries** - Not `refetch()` which ignores enabled state
-
-## Hook Patterns
+# Structured Concurrency
 
 ```typescript
-// Simple query
-export function useGetUser(userId: string) {
-  return useQuery({
-    queryKey: ["users", userId],
-    queryFn: () => api.get(`/users/${userId}`),
-    responseSchema: userSchema,
-    enabled: !!userId,
-  });
-}
-
-// Paginated query
-export function usePaginatedItems(params: Params) {
-  return useInfiniteQuery({
-    queryKey: ["items", params],
-    queryFn: ({ pageParam }) => api.get("/items", { cursor: pageParam, ...params }),
-    getNextPageParam: (lastPage) => lastPage.nextCursor,
-  });
+// 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);
+  }
 }
 
-// Mutations
-export function useCreateItem() {
-  const queryClient = useQueryClient();
-  return useMutation({
-    mutationFn: (data: CreateItemRequest) => api.post("/items", data),
-    onSuccess: () => queryClient.invalidateQueries(["items"]),
-  });
-}
+// 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");
 ```
 
-## Error Handling
-
-For detailed error handling strategies, see `error-handling.md`.
+<!-- Source: .ruler/common/testing.md -->
 
-```typescript
-useQuery({
-  queryKey: ["resource"],
-  queryFn: fetchResource,
-  useErrorBoundary: (error) => {
-    // Show error boundary for 500s, not 404s
-    return !(axios.isAxiosError(error) && error.response?.status === 404);
-  },
-  retry: (failureCount, error) => {
-    // Don't retry 4xx errors
-    if (axios.isAxiosError(error) && error.response?.status < 500) return false;
-    return failureCount < 3;
-  },
-});
-```
+# Testing
 
-## Query Keys
+## Unit Tests
 
-```typescript
-// Include URL and params for predictable cache invalidation
-export const queryKeys = {
-  users: ["users"] as const,
-  user: (id: string) => ["users", id] as const,
-  userPosts: (id: string) => ["users", id, "posts"] as const,
-};
-```
+Use when: error handling hard to trigger black-box, concurrency scenarios, >5 variations, pure function logic.
 
-## Conditional Fetching
+## Conventions
 
-```typescript
-const { data } = useQuery({
-  queryKey: ["resource", id],
-  queryFn: () => fetchResource(id),
-  enabled: !!id, // Only fetch when id exists
-});
-```
+- 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
 
-## Naming Conventions
+<!-- Source: .ruler/common/typeScript.md -->
 
-- `useGetX` - Simple queries
-- `usePaginatedX` - Infinite queries
-- `useCreateX`, `useUpdateX`, `useDeleteX` - Mutations
+# TypeScript
 
-## Hook Location
+## Naming Conventions
 
-Place in `api/` folder within feature directory. One endpoint = one hook.
+| 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`            |
 
-<!-- Source: .ruler/frontend/error-handling.md -->
+## Core Rules
 
-# Error Handling Standards
+- 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`
 
-## React Query Error Handling
+## Types
 
 ```typescript
-useQuery({
-  queryKey: ["resource"],
-  queryFn: fetchResource,
-  useErrorBoundary: (error) => {
-    // Show error boundary for 500s, not 404s
-    return !(axios.isAxiosError(error) && error.response?.status === 404);
-  },
-  retry: (failureCount, error) => {
-    // Don't retry 4xx errors
-    if (axios.isAxiosError(error) && error.response?.status < 500) return false;
-    return failureCount < 3;
-  },
-});
-```
+// Strong typing
+function process(arg: unknown) {} // Better than any
+function process<T>(arg: T) {} // Best
 
-## Component Error States
+// Nullable checks
+if (foo == null) {
+} // Clear intent
+if (isDefined(foo)) {
+} // Better with utility
 
-```typescript
-export function DataComponent() {
-  const { data, isLoading, isError, refetch } = useGetData();
+// Quantity values—always unambiguous
+const money = { amountInMinorUnits: 500, currencyCode: "USD" };
+const durationMinutes = 30;
+```
 
-  if (isLoading) return <LoadingState />;
-  if (isError) return <ErrorState onRetry={refetch} />;
+**Type Techniques:**
 
-  return <DataDisplay data={data} />;
-}
-```
+- 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
 
-## Mutation Error Handling
+## Functions
 
 ```typescript
-export function useCreateDocument() {
-  return useMutation({
-    mutationFn: createDocumentApi,
-    onSuccess: () => {
-      queryClient.invalidateQueries(["documents"]);
-      showSuccessToast("Document created");
-    },
-    onError: (error) => {
-      logError("CREATE_DOCUMENT_FAILURE", error);
-      showErrorToast("Failed to create document");
-    },
-  });
+// Object arguments with interfaces
+interface CreateUserRequest {
+  email: string;
+  name?: string;
 }
-```
-
-## Validation Errors
 
-```typescript
-// Zod validation
-const formSchema = z.object({
-  email: z.string().email("Invalid email"),
-  age: z.number().min(18, "Must be 18+"),
-});
+function createUser(request: CreateUserRequest): User {
+  const { email, name } = request; // Destructure inside
+  // ...
+}
 
-try {
-  const validated = formSchema.parse(formData);
-} catch (error) {
-  if (error instanceof z.ZodError) {
-    error.errors.forEach((err) => showFieldError(err.path.join("."), err.message));
+// Guard clauses for early returns
+function processOrder(order: Order): Result {
+  if (!order.isValid) {
+    return { error: "Invalid order" };
   }
+  // Main logic
 }
 ```
 
-## Error Boundaries
+## Objects & Arrays
 
 ```typescript
-export class ErrorBoundary extends Component<Props, State> {
-  state = { hasError: false };
+// Spread over Object.assign
+const updated = { ...original, name: "New Name" };
 
-  static getDerivedStateFromError(error: Error) {
-    return { hasError: true, error };
-  }
-
-  componentDidCatch(error: Error, errorInfo: ErrorInfo) {
-    logEvent("ERROR_BOUNDARY", { error: error.message });
-  }
+// Array methods over loops (unless breaking early)
+const doubled = items.map((item) => item * 2);
+const sorted = items.toSorted((a, b) => a - b); // Immutable
 
-  render() {
-    return this.state.hasError ? <ErrorFallback /> : this.props.children;
-  }
+// For early exit
+for (const item of items) {
+  if (condition) break;
 }
 ```
 
-## Best Practices
-
-- **Always handle errors** - Check `isError` state
-- **User-friendly messages** - Don't show technical errors
-- **Log for debugging** - Include context
-- **Provide recovery actions** - Retry, dismiss, navigate
-- **Different strategies** - Error boundary vs inline vs retry
+## Async
 
-<!-- Source: .ruler/frontend/file-organization.md -->
-
-# File Organization Standards
+```typescript
+// async/await over .then()
+async function fetchData(): Promise<Data> {
+  const response = await api.get("/data");
+  return response.data;
+}
 
-## Feature-based Structure
+// Parallel
+const results = await Promise.all(items.map(processItem));
 
-```text
-FeatureName/
-├── api/                          # Data fetching hooks
-│   ├── useGetFeature.ts
-│   ├── useUpdateFeature.ts
-│   └── useDeleteFeature.ts
-├── components/                   # Feature-specific components
-│   ├── FeatureCard.tsx
-│   ├── FeatureList.tsx
-│   └── FeatureHeader.tsx
-├── hooks/                        # Feature-specific hooks (non-API)
-│   ├── useFeatureLogic.ts
-│   └── useFeatureState.ts
-├── utils/                        # Feature utilities
-│   ├── formatFeature.ts
-│   ├── formatFeature.test.ts
-│   └── validateFeature.ts
-├── __tests__/                    # Integration tests (optional)
-│   └── FeatureFlow.test.tsx
-├── Page.tsx                      # Main page component
-├── Router.tsx                    # Feature routes
-├── paths.ts                      # Route paths
-├── types.ts                      # Shared types
-├── constants.ts                  # Constants
-└── README.md                     # Feature documentation (optional)
+// Sequential (when needed)
+for (const item of items) {
+  // eslint-disable-next-line no-await-in-loop
+  await processItem(item);
+}
 ```
 
-## Naming Conventions
-
-- Components: `PascalCase.tsx` (`UserProfile.tsx`)
-- Hooks: `camelCase.ts` (`useUserProfile.ts`)
-- Utils: `camelCase.ts` (`formatDate.ts`)
-- Types: `camelCase.types.ts` (`user.types.ts`)
-- Tests: `ComponentName.test.tsx`
-
-<!-- Source: .ruler/frontend/react-patterns.md -->
-
-# React Component Patterns
-
-## Component Structure
+## Classes
 
 ```typescript
-interface Props {
-  userId: string;
-  onUpdate?: (user: User) => void;
+class UserService {
+  public async findById(request: FindByIdRequest): Promise<User> {}
+  private validateUser(user: User): boolean {}
 }
 
-export function UserProfile({ userId, onUpdate }: Props) {
-  // 1. Hooks
-  const { data, isLoading, error } = useGetUser(userId);
-  const [isEditing, setIsEditing] = useState(false);
-
-  // 2. Derived state (avoid useMemo for inexpensive operations)
-  const displayName = formatName(data);
-
-  // 3. Event handlers
-  const handleSave = useCallback(async () => {
-    await saveUser(data);
-    onUpdate?.(data);
-  }, [data, onUpdate]);
-
-  // 4. Early returns
-  if (isLoading) return <Loading />;
-  if (error) return <Error message={error.message} />;
-  if (!data) return <NotFound />;
-
-  // 5. Main render
-  return (
-    <Card>
-      <Typography>{displayName}</Typography>
-      <Button onClick={handleSave}>Save</Button>
-    </Card>
-  );
+// Extract pure functions outside classes
+function formatUserName(first: string, last: string): string {
+  return `${first} ${last}`;
 }
 ```
 
-## Naming Conventions
+<!-- Source: .ruler/frontend/customHooks.md -->
 
-- Components: `PascalCase` (`UserProfile`)
-- Props interface: `Props` (co-located with component) or `ComponentNameProps` (exported/shared)
-- Event handlers: `handle*` (`handleClick`, `handleSubmit`)
-- Boolean props: `is*`, `has*`, `should*`
+# Custom Hooks
 
-## Props Patterns
+## Naming
 
-```typescript
-// Simple props
-interface Props {
-  title: string;
-  count: number;
-  onAction: () => void;
-}
+- Prefix with `use`
+- Boolean: `useIs*`, `useHas*`, `useCan*`
+- Data: `useGet*`, `use*Data`
+- Actions: `useSubmit*`, `useCreate*`
 
-// Discriminated unions for variants
-type ButtonProps = { variant: "link"; href: string } | { variant: "button"; onClick: () => void };
+## Structure
 
-// Optional callbacks
-interface Props {
-  onSuccess?: (data: Data) => void;
-  onError?: (error: Error) => void;
+```typescript
+export function useFeature(params: Params, options: Options = {}) {
+  const query = useQuery(...);
+  const computed = useMemo(() => transform(query.data), [query.data]);
+  const handleAction = useCallback(async () => { ... }, []);
+
+  return { data: computed, isLoading: query.isLoading, handleAction };
 }
 ```
 
-## Composition Patterns
+## Shared State with Constate
 
 ```typescript
-// Container/Presentational
-export function UserListContainer() {
-  const { data, isLoading, error } = useUsers();
-  if (isLoading) return <Loading />;
-  if (error) return <Error />;
-  return <UserList users={data} />;
+import constate from "constate";
+
+function useFilters() {
+  const [filters, setFilters] = useState<Filters>({});
+  return { filters, setFilters };
 }
 
-// Compound components
-<Card>
-  <Card.Header title="User" />
-  <Card.Body>Content</Card.Body>
-  <Card.Actions>
-    <Button>Save</Button>
-  </Card.Actions>
-</Card>
-
-// Render props
-<DataProvider>
-  {({ data, isLoading }) => (
-    isLoading ? <Loading /> : <Display data={data} />
-  )}
-</DataProvider>
+export const [FiltersProvider, useFiltersContext] = constate(useFilters);
 ```
 
-## Children Patterns
+Use constate for: sharing state between siblings, feature-level state.
+Don't use for: server state (use React Query), simple parent-child (use props).
 
-```typescript
-// Typed children
-interface Props {
-  children: ReactNode;
-}
+<!-- Source: .ruler/frontend/dataFetching.md -->
 
-// Render prop pattern
-interface Props {
-  children: (data: Data) => ReactNode;
-}
+# Data Fetching
 
-// Element restrictions
-interface Props {
-  children: ReactElement<ButtonProps>;
-}
-```
+## Core Rules
 
-## List Rendering
+1. Use React Query for all API calls
+2. Define Zod schemas for all request/response types
+3. Use `isLoading`, `isError`, `isSuccess`—don't create custom state
+4. Use `enabled` option for conditional fetching
+5. Use `invalidateQueries` (not `refetch`) for disabled queries
+
+## Hook Pattern
 
 ```typescript
-// ✅ Proper keys
-{users.map((user) => <UserCard key={user.id} user={user} />)}
+// Define in: FeatureName/api/useGetFeature.ts
+const responseSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+});
 
-// ✅ Empty states
-{users.length === 0 ? <EmptyState /> : users.map(...)}
+export type FeatureResponse = z.infer<typeof responseSchema>;
 
-// ❌ Never use index as key when list can change
-{items.map((item, index) => <Item key={index} />)} // Wrong!
+export function useGetFeature(id: string, options = {}) {
+  return useGetQuery({
+    url: `feature/${id}`,
+    responseSchema,
+    enabled: !!id,
+    meta: { logErrorMessage: APP_EVENTS.GET_FEATURE_FAILURE },
+    ...options,
+  });
+}
 ```
 
-## Conditional Rendering
+## Query Keys
 
-```typescript
-// Simple conditional
-{isLoading && <Spinner />}
+Include URL and params for predictable cache invalidation:
 
-// If-else
-{isError ? <Error /> : <Success />}
+```typescript
+queryKey: ["users", userId];
+queryKey: ["users", userId, "posts"];
+```
 
-// Multiple conditions
-{isLoading ? <Loading /> : isError ? <Error /> : <Data />}
+## Conditional Fetching
 
-// With early returns (preferred for complex logic)
-if (isLoading) return <Loading />;
-if (isError) return <Error />;
-return <Data />;
+```typescript
+const { data } = useGetFeature(
+  { id: dependencyData?.id },
+  { enabled: isDefined(dependencyData?.id) },
+);
 ```
 
-## Performance
+## Mutations
 
 ```typescript
-// Memoize expensive components
-const MemoItem = memo(({ item }: Props) => <div>{item.name}</div>);
-
-// Split state to avoid re-renders
-function Parent() {
-  const [count, setCount] = useState(0);
-  const [text, setText] = useState("");
-
-  // Only CountDisplay re-renders when count changes
-  return (
-    <>
-      <CountDisplay count={count} />
-      <TextInput value={text} onChange={setText} />
-    </>
-  );
+export function useCreateItem() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: (data: CreateItemRequest) => api.post("/items", data),
+    onSuccess: () => queryClient.invalidateQueries(["items"]),
+    onError: (error) => logError("CREATE_ITEM_FAILURE", error),
+  });
 }
 ```
 
-## Best Practices
+<!-- Source: .ruler/frontend/e2eTesting.md -->
 
-- **Single Responsibility** - One component, one purpose
-- **Composition over Props** - Use children and compound components
-- **Colocate State** - Keep state close to where it's used
-- **Type Everything** - Full TypeScript coverage
-- **Test Behavior** - Test user interactions, not implementation
+# E2E Testing (Playwright)
 
-<!-- Source: .ruler/frontend/react.md -->
+## Core Rules
 
-# React
+- Test critical user flows only—not exhaustive scenarios
+- Each test sets up its own data (no shared state between tests)
+- Mock feature flags and third-party services
+- Use user-centric locators (role, label, text)—avoid CSS selectors
 
-- Destructure props in function body (improves readability and prop documentation)
-- Prefer inline JSX over extracted variables
-- Use custom hooks to encapsulate and reuse stateful logic
-- Use Zod for request/response schemas in data-fetching hooks
-- Use react-hook-form with Zod resolver for forms
-- Use date-fns for date operations
+## Locator Priority
 
-<!-- Source: .ruler/frontend/styling.md -->
+1. `page.getByRole()`
+2. `page.getByLabel()`
+3. `page.getByPlaceholder()`
+4. `page.getByText()`
+5. `page.getByTestId()` (last resort)
 
-# Styling Standards
+## Assertions
 
-## Core Principles
+```typescript
+// ✅ Assert visibility
+await expect(page.getByText("Submit")).toBeVisible();
 
-1. **Always use `sx` prop** - Never CSS/SCSS/SASS files
-2. **Use theme tokens** - Never hardcode colors/spacing
-3. **Type-safe theme access** - Use `sx={(theme) => ({...})}`
-4. **Use semantic names** - `theme.palette.text.primary`, not `common.white`
-5. **Check Storybook first** - It's the single source of truth
+// ❌ Don't assert DOM attachment
+await expect(page.getByText("Submit")).toBeAttached();
+```
 
-## Restricted Patterns
+## Avoid
 
-❌ **DO NOT USE:**
+- Hard-coded timeouts (`page.waitForTimeout`)
+- Testing loading states (non-deterministic)
+- Shared data between tests
+- CSS/XPath selectors
 
-- `styled()` or `makeStyles()` from MUI
-- CSS/SCSS/SASS files
-- Inline `style` prop (use `sx` instead)
-- String paths for theme (`"text.secondary"` - not type-safe)
+<!-- Source: .ruler/frontend/errorHandling.md -->
 
-## Type-Safe Theme Access
+# Error Handling
 
-```typescript
-// ✅ Always use function form for type safety
-<Box sx={(theme) => ({
-  backgroundColor: theme.palette.background.primary,
-  color: theme.palette.text.secondary,
-  padding: theme.spacing(4), // or just: 4
-})} />
-
-// ❌ Never hardcode
-<Box sx={{
-  backgroundColor: "red", // ❌ Raw color
-  padding: "16px", // ❌ Raw size
-  color: "text.secondary", // ❌ String path
-}} />
-```
-
-## Spacing System
-
-Use indices 1-12 (4px-64px):
+## Component Level
 
 ```typescript
-<Box sx={{ padding: 5 }} />    // → 16px
-<Box sx={{ marginX: 4 }} />    // → 12px left and right
-<Box sx={{ gap: 3 }} />        // → 8px
-```
+export function DataComponent() {
+  const { data, isLoading, isError, refetch } = useGetData();
 
-**Use `rem` for fonts/heights (scales with user zoom), `px` for spacing:**
+  if (isLoading) return <LoadingState />;
+  if (isError) return <ErrorState onRetry={refetch} />;
 
-```typescript
-<Box sx={(theme) => ({
-  height: "3rem", // ✅ Scales
-  fontSize: theme.typography.body1.fontSize,
-  padding: 5, // ✅ Prevents overflow
-})} />
+  return <DataDisplay data={data} />;
+}
 ```
 
-## Responsive Styles
+## Mutation Level
 
 ```typescript
-<Box sx={{
-  width: { xs: "100%", md: "50%" },
-  padding: { xs: 1, md: 3 },
-}} />
+useMutation({
+  mutationFn: createItem,
+  onSuccess: () => showSuccessToast("Created"),
+  onError: (error) => {
+    logError("CREATE_FAILURE", error);
+    showErrorToast("Failed to create");
+  },
+});
 ```
 
-## Pseudo-classes
+## Validation
 
 ```typescript
-<Box sx={(theme) => ({
-  "&:hover": { backgroundColor: theme.palette.primary.dark },
-  "&:disabled": { opacity: 0.5 },
-  "& .child": { color: theme.palette.text.secondary },
-})} />
+try {
+  const validated = formSchema.parse(formData);
+} catch (error) {
+  if (error instanceof z.ZodError) {
+    error.errors.forEach((err) => showFieldError(err.path.join("."), err.message));
+  }
+}
 ```
 
-## Shorthand Properties
-
-✅ Use full names: `padding`, `paddingX`, `marginY`
-❌ Avoid abbreviations: `p`, `px`, `my`
-
-## Layout Components
+<!-- Source: .ruler/frontend/fileOrganization.md -->
 
-Safe to import directly from MUI:
+# File Organization
 
-```typescript
-import { Box, Stack, Container, Grid } from "@mui/material";
+```text
+FeatureName/
+├── api/                    # Data fetching hooks
+│   └── useGetFeature.ts
+├── components/             # Feature-specific components
+│   └── FeatureCard.tsx
+├── hooks/                  # Non-API hooks
+│   └── useFeatureLogic.ts
+├── utils/                  # Utilities + tests
+│   ├── formatFeature.ts
+│   └── formatFeature.test.ts
+├── Page.tsx                # Main page
+├── Router.tsx              # Routes
+├── paths.ts                # Route constants
+└── types.ts                # Shared types
 ```
 
-## Best Practices
+## Naming
 
-- Type-safe access with `sx={(theme) => ({...})}`
-- Use semantic token names
-- Full property names, not abbreviations
+- Components: `PascalCase.tsx`
+- Hooks: `camelCase.ts` (prefixed with `use`)
+- Utils: `camelCase.ts`
+- Tests: `*.test.tsx`
 
-<!-- Source: .ruler/frontend/testing.md -->
+<!-- Source: .ruler/frontend/frontendTechnologyStack.md -->
 
-# Testing Standards
+# Frontend Technology Stack
 
-## Testing Trophy Philosophy
+- **React** with TypeScript (strict mode)
+- **MUI** for UI components
+- **React Query** (@tanstack/react-query) for data fetching
+- **Zod** for runtime validation
+- **Vitest** + **@testing-library/react** for testing
+- **MSW** for API mocking
+- **Playwright** for E2E tests
+- **constate** for shared state
 
-Focus on **Integration tests** - test how components work together as users experience them.
+<!-- Source: .ruler/frontend/interactiveElements.md -->
 
-**Investment Priority:**
+# Interactive Elements
 
-1. **Static** (TypeScript/ESLint) - Free confidence
-2. **Integration** - Most valuable, test features not isolated components
-3. **Unit** - For pure helpers/utilities only
-4. **E2E** - Critical flows only
+Never add `onClick` to `div` or `span`. Use:
 
-**Key Principle:** Test as close to how users interact with your app as possible.
+- `<button>` for actions
+- `<a>` (Link) for navigation
+- MUI interactive components (`Button`, `IconButton`, `ListItemButton`)
 
-## Technology Stack
+This ensures proper accessibility: focus states, keyboard navigation, ARIA roles.
 
-- **Vitest** for test runner
-- **@testing-library/react** for component testing
-- **@testing-library/user-event** for user interactions
-- **Mock Service Worker (MSW)** for API mocking
+<!-- Source: .ruler/frontend/modalRoutes.md -->
 
-## Test Structure
+# Modal Routes
 
-```typescript
-describe("ComponentName", () => {
-  it("should render correctly", () => {
-    render(<Component />);
-    expect(screen.getByText("Expected")).toBeInTheDocument();
-  });
+Modal visibility is driven by URL, not local state:
 
-  it("should handle user interaction", async () => {
-    const user = userEvent.setup();
-    render(<Component />);
-    await user.click(screen.getByRole("button", { name: "Submit" }));
-    await waitFor(() => expect(screen.getByText("Success")).toBeInTheDocument());
-  });
-});
+```typescript
+<ModalRoute
+  path={`${basePath}/confirm`}
+  closeModalPath={basePath}
+  render={({ modalState }) => (
+    <ConfirmDialog modalState={modalState} />
+  )}
+/>
 ```
 
-## Test Naming
+Use `history.replace` (not `push`) when navigating between modals to avoid awkward back-button behavior.
 
-Pattern: `should [behavior] when [condition]`
+<!-- Source: .ruler/frontend/reactComponents.md -->
 
-## Querying Elements - Priority Order
+# React Components
 
-1. `getByRole` - Best for accessibility
-2. `getByLabelText` - For form fields
-3. `getByText` - For non-interactive content
-4. `getByTestId` - ⚠️ **LAST RESORT**
+## Type vs Interface
 
 ```typescript
-// ✅ Prefer
-screen.getByRole("button", { name: /submit/i });
-screen.getByLabelText("Email");
-
-// ❌ Avoid
-screen.getByClassName("user-card");
-screen.getByTestId("element");
+// Use interface for: props, object shapes, extensible types
+interface UserCardProps {
+  user: User;
+  onSelect: (id: string) => void;
+}
 ```
 
-## User Interactions
+## Structure Order
 
 ```typescript
-it("should handle form submission", async () => {
-  const user = userEvent.setup();
-  const onSubmit = vi.fn();
-  render(<Form onSubmit={onSubmit} />);
+export function Component({ userId, onUpdate }: Props) {
+  // 1. Hooks
+  const { data, isLoading } = useGetUser(userId);
+  const [isEditing, setIsEditing] = useState(false);
 
-  await user.type(screen.getByLabelText("Name"), "John");
-  await user.click(screen.getByRole("button", { name: "Submit" }));
+  // 2. Derived state (no useMemo for cheap operations)
+  const displayName = formatName(data);
 
-  expect(onSubmit).toHaveBeenCalledWith({ name: "John" });
-});
-```
+  // 3. Event handlers
+  const handleSave = useCallback(async () => { ... }, [deps]);
 
-## Hook Testing
+  // 4. Early returns for loading/error/empty
+  if (isLoading) return <Loading />;
+  if (!data) return <NotFound />;
 
-```typescript
-describe("useCustomHook", () => {
-  it("should return data after loading", async () => {
-    const { result } = renderHook(() => useCustomHook());
-    await waitFor(() => expect(result.current.isLoading).toBe(false));
-    expect(result.current.data).toEqual(expectedData);
-  });
-});
+  // 5. Main render
+  return <Card>...</Card>;
+}
 ```
 
-## MSW Pattern
+## Naming Conventions
 
-**Always export factory functions, not static handlers:**
+- Components: `PascalCase`
+- Event handlers: `handle*` (e.g., `handleClick`)
+- Props interface: `Props` (co-located) or `ComponentNameProps` (exported)
 
-```typescript
-// ✅ Good - flexible per test
-export const createTestHandler = (data: Data[]) =>
-  rest.get(`/api/resource`, (req, res, ctx) => res(ctx.json(data)));
+## Component Guidelines
 
-// Usage
-mockServer.use(createTestHandler(customData));
-```
-
-## Mocking
+- **One file per component**—never extract JSX into local variables
+- **Composition over configuration**—prefer `children` over many props
+- **Presentational components**: stateless, UI-focused, no API calls
+- **Container components**: feature logic, data fetching, state management
+- Pass primitives as props, not entire API response objects
 
 ```typescript
-vi.mock("@/lib/api", () => ({
-  get: vi.fn().mockResolvedValue({ data: { id: "1" } }),
-}));
-```
-
-## What to Test
-
-**✅ Do Test:**
-
-- Integration tests for features
-- Unit tests for utilities
-- All states (loading, success, error)
-- User interactions
-
-**❌ Don't Test:**
-
-- Implementation details
-- Third-party libraries
-- Styles/CSS
-
-<!-- Source: .ruler/frontend/typeScript.md -->
-
-# TypeScript Standards
+// ❌ Bad—coupled to API shape
+interface Props {
+  shift: ShiftApiResponse;
+}
 
-## Core Principles
+// ✅ Good—only required fields
+interface Props {
+  shiftId: string;
+  shiftPay: number;
+  workplaceId: string;
+}
+```
 
-- **Strict mode enabled** - Avoid `any`
-- **Prefer type inference** - Let TypeScript infer when possible
-- **Explicit return types** for exported functions
-- **Zod for runtime validation** - Single source of truth
-- **No type assertions** unless unavoidable
-
-## Type vs Interface
+## Inline JSX and Handlers
 
 ```typescript
-// ✅ Use interface for: props, object shapes, extensible types
-interface UserCardProps {
-  user: User;
-  onSelect: (id: string) => void;
-}
+// ❌ Don't extract JSX to variables
+const content = <p>Content</p>;
+return <>{content}</>;
 
-interface BaseEntity {
-  id: string;
-  createdAt: string;
-}
+// ✅ Keep inline or extract to new component file
+return <p>Content</p>;
 
-interface User extends BaseEntity {
-  name: string;
-}
+// ❌ Don't extract handlers unnecessarily
+const handleChange = (e) => { ... };
+return <Input onChange={handleChange} />;
 
-// ✅ Use type for: unions, intersections, tuples, derived types
-type Status = "pending" | "active" | "completed";
-type UserWithRoles = User & { roles: string[] };
-type Coordinate = [number, number];
-type UserKeys = keyof User;
+// ✅ Keep inline
+return <Input onChange={(e) => { ... }} />;
 ```
 
-## Naming Conventions
+## List Rendering
 
 ```typescript
-// ✅ Suffix with purpose (no I or T prefix)
-interface ButtonProps { ... }
-type ApiResponse = { ... };
-type UserOptions = { ... };
-
-// ✅ Boolean properties
-interface User {
-  isActive: boolean;
-  hasPermission: boolean;
-  shouldNotify: boolean;
-}
+// ✅ Always use stable keys
+{users.map((user) => <UserCard key={user.id} user={user} />)}
+
+// ❌ Never use index as key for dynamic lists
+{items.map((item, i) => <Item key={i} />)}
 ```
 
-## Zod Integration
+<!-- Source: .ruler/frontend/styling.md -->
 
-```typescript
-// Define schema, infer type
-const userSchema = z.object({
-  id: z.string(),
-  name: z.string(),
-});
+# Styling
 
-export type User = z.infer<typeof userSchema>;
+## Core Rules
 
-// Validate API responses
-const response = await get({
-  url: "/api/users",
-  responseSchema: userSchema,
-});
-```
+1. **Always use `sx` prop**—never CSS/SCSS/SASS/styled()/makeStyles()
+2. **Use theme tokens**—never use raw string values for colors/spacing
+3. **Type-safe theme access**—use `sx={(theme) => ({...})}`
+4. **Use semantic token names**—`theme.palette.text.primary`, not `common.white`
 
-## Type Guards
+## Patterns
 
 ```typescript
-export function isUser(value: unknown): value is User {
-  return userSchema.safeParse(value).success;
-}
+// ✅ Correct
+<Box sx={(theme) => ({
+  backgroundColor: theme.palette.background.primary,
+  color: theme.palette.text.secondary,
+  padding: theme.spacing(4), // or just: padding: 4
+})} />
 
-// Usage
-if (isUser(data)) {
-  console.log(data.name); // TypeScript knows data is User
-}
+// ❌ Wrong
+<Box sx={{
+  backgroundColor: "red",      // raw color
+  padding: "16px",             // raw size
+  color: "text.secondary",     // string path (not type-safe)
+}} />
 ```
 
-## Constants
-
-```typescript
-// Use const assertions
-export const STATUSES = {
-  DRAFT: "draft",
-  PUBLISHED: "published",
-} as const;
-
-export type Status = (typeof STATUSES)[keyof typeof STATUSES];
-```
+## Spacing
 
-## Utility Types
+Use theme spacing indices 1-12:
 
 ```typescript
-// Built-in utilities
-type PartialUser = Partial<User>;
-type RequiredUser = Required<User>;
-type ReadonlyUser = Readonly<User>;
-type UserIdOnly = Pick<User, "id" | "name">;
-type UserWithoutPassword = Omit<User, "password">;
-type UserMap = Record<string, User>;
-type DefinedString = NonNullable<string | null>;
-
-// Function utilities
-type GetUserResult = ReturnType<typeof getUser>;
-type UpdateUserParams = Parameters<typeof updateUser>;
+<Box sx={{ padding: 5 }} />
+<Box sx={{ marginX: 4 }} />
 ```
 
-## Avoiding `any`
+Use `rem` for fonts/heights (scales with user zoom), spacing indices for padding/margin.
 
-```typescript
-// ❌ Bad - Loses type safety
-function process(data: any) { ... }
+## Property Names
 
-// ✅ Use unknown for truly unknown types
-function process(data: unknown) {
-  if (typeof data === "object" && data !== null) {
-    // Type guard
-  }
-}
+- ✅ Use full names: `padding`, `paddingX`, `marginY`
+- ❌ Avoid abbreviations: `p`, `px`, `my`
 
-// ✅ Better - Use generics
-function process<T extends { value: string }>(data: T) {
-  return data.value;
-}
+## Pseudo-classes
 
-// ✅ Best - Use Zod
-const dataSchema = z.object({ value: z.string() });
-function process(data: unknown) {
-  const parsed = dataSchema.parse(data);
-  return parsed.value;
-}
+```typescript
+<Box sx={(theme) => ({
+  "&:hover": { backgroundColor: theme.palette.primary.dark },
+  "&:disabled": { opacity: 0.5 },
+  "& .MuiTypography-root": { color: theme.palette.text.secondary },
+})} />
 ```
 
-## Generics
+<!-- Source: .ruler/frontend/testing.md -->
 
-```typescript
-// Generic function
-function getFirst<T>(array: T[]): T | undefined {
-  return array[0];
-}
+# Testing
 
-// Generic component
-interface ListProps<T> {
-  items: T[];
-  renderItem: (item: T) => ReactNode;
-}
+## Philosophy
 
-export function List<T>({ items, renderItem }: ListProps<T>) {
-  return <>{items.map((item) => renderItem(item))}</>;
-}
+Focus on integration tests—test how components work together as users experience them.
 
-// Constrained generics
-function findById<T extends { id: string }>(items: T[], id: string): T | undefined {
-  return items.find((item) => item.id === id);
-}
-```
+**Priority:** Static (TS/ESLint) → Integration → Unit (pure utilities only) → E2E (critical flows only)
 
-## Discriminated Unions
+## Test Structure
 
 ```typescript
-// State machine
-type QueryState<T> =
-  | { status: "idle" }
-  | { status: "loading" }
-  | { status: "success"; data: T }
-  | { status: "error"; error: Error };
-
-// Automatic type narrowing
-if (state.status === "success") {
-  console.log(state.data); // TypeScript knows data exists
-}
+describe("ComponentName", () => {
+  it("should [behavior] when [condition]", async () => {
+    const user = userEvent.setup();
+    render(<Component />);
 
-// Actions
-type Action = { type: "SET_USER"; payload: User } | { type: "CLEAR_USER" };
+    await user.click(screen.getByRole("button", { name: "Submit" }));
 
-function reducer(state: State, action: Action) {
-  switch (action.type) {
-    case "SET_USER":
-      return { ...state, user: action.payload };
-    case "CLEAR_USER":
-      return { ...state, user: null };
-  }
-}
+    await waitFor(() => {
+      expect(screen.getByText("Success")).toBeInTheDocument();
+    });
+  });
+});
 ```
 
-## Type Narrowing
+## Query Priority
 
-```typescript
-// typeof
-function format(value: string | number) {
-  if (typeof value === "string") {
-    return value.toUpperCase();
-  }
-  return value.toFixed(2);
-}
+1. `getByRole` (best for accessibility)
+2. `getByLabelText` (form fields)
+3. `getByText` (non-interactive content)
+4. `getByTestId` (last resort only)
 
-// in operator
-function move(animal: Fish | Bird) {
-  if ("swim" in animal) {
-    animal.swim();
-  } else {
-    animal.fly();
-  }
-}
+```typescript
+// ✅ Prefer
+screen.getByRole("button", { name: /submit/i });
+screen.getByLabelText("Email");
 
-// instanceof
-function handleError(error: unknown) {
-  if (error instanceof Error) {
-    console.log(error.message);
-  }
-}
+// ❌ Avoid
+screen.getByTestId("submit-button");
 ```
 
-## Common Patterns
-
-```typescript
-// Optional chaining
-const userName = user?.profile?.name;
+## MSW Handlers
 
-// Nullish coalescing
-const displayName = userName ?? "Anonymous";
+Export factory functions, not static handlers:
 
-// Non-null assertion (use sparingly)
-const user = getUser()!;
+```typescript
+// ✅ Good—flexible per test
+export const createUserHandler = (userData: User) =>
+  rest.get("/api/user", (req, res, ctx) => res(ctx.json(userData)));
 
-// Template literal types
-type Route = `/users/${string}` | `/posts/${string}`;
-type EventHandler = `on${Capitalize<string>}`;
+// Usage
+mockServer.use(createUserHandler(customData));
 ```
 
-## Best Practices
+## What to Test
 
-- **Never use `any`** - Use `unknown` or generics
-- **Discriminated unions** for state machines
-- **Zod** for runtime validation
-- **Type guards** over type assertions
-- **Const assertions** for readonly values
-- **Utility types** to transform existing types
+✅ Test: user interactions, all states (loading/success/error), integration between components
+❌ Don't test: implementation details, third-party libraries, styles