Exercises

# Development Guidelines for Claude

## Core Philosophy

**TEST-DRIVEN DEVELOPMENT IS NON-NEGOTIABLE.** Every single line of production code must be written in response to a failing test. No exceptions. This is not a suggestion or a preference - it is the fundamental practice that enables all other principles in this document.

I follow Test-Driven Development (TDD) with a strong emphasis on behavior-driven testing and functional programming principles. All work should be done in small, incremental changes that maintain a working state throughout development.

## Quick Reference

**Key Principles:**

- Write tests first (TDD)
- Test behavior, not implementation
- No `any` types or type assertions
- Immutable data only
- Small, pure functions
- TypeScript strict mode always
- Use real schemas/types in tests, never redefine them

**Preferred Tools:**

- **Language**: TypeScript (strict mode)
- **Testing**: Jest/Vitest + React Testing Library
- **State Management**: Prefer immutable patterns

## Testing Principles

### Behavior-Driven Testing

- **No "unit tests"** - this term is not helpful. Tests should verify expected behavior, treating implementation as a black box
- Test through the public API exclusively - internals should be invisible to tests
- No 1:1 mapping between test files and implementation files
- Tests that examine internal implementation details are wasteful and should be avoided
- **Coverage targets**: 100% coverage should be expected at all times, but these tests must ALWAYS be based on business behaviour, not implementation details
- Tests must document expected business behaviour

### Testing Tools

- **Jest** or **Vitest** for testing frameworks
- **React Testing Library** for React components
- **MSW (Mock Service Worker)** for API mocking when needed
- All test code must follow the same TypeScript strict mode rules as production code

### Test Organization

```
src/
  features/
    payment/
      payment-processor.ts
      payment-validator.ts
      payment-processor.test.ts // The validator is an implementation detail. Validation is fully covered, but by testing the expected business behaviour, treating the validation code itself as an implementation detail
```

### Test Data Pattern

Use factory functions with optional overrides for test data:

```typescript
const getMockPaymentPostPaymentRequest = (
  overrides?: Partial<PostPaymentsRequestV3>
): PostPaymentsRequestV3 => {
  return {
    CardAccountId: "1234567890123456",
    Amount: 100,
    Source: "Web",
    AccountStatus: "Normal",
    LastName: "Doe",
    DateOfBirth: "1980-01-01",
    PayingCardDetails: {
      Cvv: "123",
      Token: "token",
    },
    AddressDetails: getMockAddressDetails(),
    Brand: "Visa",
    ...overrides,
  };
};

const getMockAddressDetails = (
  overrides?: Partial<AddressDetails>
): AddressDetails => {
  return {
    HouseNumber: "123",
    HouseName: "Test House",
    AddressLine1: "Test Address Line 1",
    AddressLine2: "Test Address Line 2",
    City: "Test City",
    ...overrides,
  };
};
```

Key principles:

- Always return complete objects with sensible defaults
- Accept optional `Partial<T>` overrides
- Build incrementally - extract nested object factories as needed
- Compose factories for complex objects
- Consider using a test data builder pattern for very complex objects

**Validating Test Data:**

When schemas exist, validate factory output to catch test data issues early:

```typescript
import { PaymentSchema, type Payment } from '../schemas/payment.schema';

const getMockPayment = (overrides?: Partial<Payment>): Payment => {
  const basePayment = {
    amount: 100,
    currency: "GBP",
    cardId: "card_123",
    customerId: "cust_456",
  };

  const paymentData = { ...basePayment, ...overrides };

  // Validate against real schema to catch type mismatches
  return PaymentSchema.parse(paymentData);
};

// This catches errors in test setup:
const payment = getMockPayment({
  amount: -100  // ❌ Schema validation fails: amount must be positive
});
```

**Why validate test data:**
- Ensures test factories produce valid data that matches production schemas
- Catches test data bugs immediately rather than in test assertions
- Documents constraints (e.g., "amount must be positive") in schema, not in every test
- Prevents tests from passing with invalid data that would fail in production

## TypeScript Guidelines

### Strict Mode Requirements

```json
// tsconfig.json
{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "strictFunctionTypes": true,
    "strictBindCallApply": true,
    "strictPropertyInitialization": true,
    "noImplicitThis": true,
    "alwaysStrict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true
  }
}
```

- **No `any`** - ever. Use `unknown` if type is truly unknown
- **No type assertions** (`as SomeType`) unless absolutely necessary with clear justification
- **No `@ts-ignore`** or `@ts-expect-error` without explicit explanation
- These rules apply to test code as well as production code

### Type Definitions

- **Prefer `type` over `interface`** - Use `type` for data structures and shapes. Reserve `interface` ONLY for behavior contracts (ports, adapters, dependency injection):

```typescript
// ✅ CORRECT - type for data structures
type User = {
  readonly id: string;
  readonly email: string;
  readonly role: UserRole;
};

type PaymentRequest = {
  amount: number;
  currency: string;
};

// ✅ CORRECT - interface for behavior contracts
interface Logger {
  log(message: string): void;
  error(message: string, error: Error): void;
}

interface PaymentGateway {
  processPayment(payment: Payment): Promise<PaymentResult>;
  refund(transactionId: string): Promise<RefundResult>;
}

// ❌ WRONG - interface for data structure
interface User {
  id: string;
  email: string;
}
```

**Why this distinction?**
- **Types** describe what data IS (structure, shape)
- **Interfaces** describe what code DOES (behavior, contracts)
- Interfaces support declaration merging and extension, useful for dependency injection and plugin systems
- Types are more flexible for complex type operations (unions, intersections, mapped types)

- Use explicit typing where it aids clarity, but leverage inference where appropriate
- Utilize utility types effectively (`Pick`, `Omit`, `Partial`, `Required`, etc.)
- Create domain-specific types (e.g., `UserId`, `PaymentId`) for type safety
- Use Zod or any other [Standard Schema](https://standardschema.dev/) compliant schema library to create types, by creating schemas first

```typescript
// Good - Branded types for type safety
type UserId = string & { readonly brand: unique symbol };
type PaymentAmount = number & { readonly brand: unique symbol };

// Avoid - No type distinction
type UserId = string;
type PaymentAmount = number;
```

#### Schema-First Development with Zod

Always define your schemas first, then derive types from them:

```typescript
import { z } from "zod";

// Define schemas first - these provide runtime validation
const AddressDetailsSchema = z.object({
  houseNumber: z.string(),
  houseName: z.string().optional(),
  addressLine1: z.string().min(1),
  addressLine2: z.string().optional(),
  city: z.string().min(1),
  postcode: z.string().regex(/^[A-Z]{1,2}\d[A-Z\d]? ?\d[A-Z]{2}$/i),
});

const PayingCardDetailsSchema = z.object({
  cvv: z.string().regex(/^\d{3,4}$/),
  token: z.string().min(1),
});

const PostPaymentsRequestV3Schema = z.object({
  cardAccountId: z.string().length(16),
  amount: z.number().positive(),
  source: z.enum(["Web", "Mobile", "API"]),
  accountStatus: z.enum(["Normal", "Restricted", "Closed"]),
  lastName: z.string().min(1),
  dateOfBirth: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
  payingCardDetails: PayingCardDetailsSchema,
  addressDetails: AddressDetailsSchema,
  brand: z.enum(["Visa", "Mastercard", "Amex"]),
});

// Derive types from schemas
type AddressDetails = z.infer<typeof AddressDetailsSchema>;
type PayingCardDetails = z.infer<typeof PayingCardDetailsSchema>;
type PostPaymentsRequestV3 = z.infer<typeof PostPaymentsRequestV3Schema>;

// Use schemas at runtime boundaries
export const parsePaymentRequest = (data: unknown): PostPaymentsRequestV3 => {
  return PostPaymentsRequestV3Schema.parse(data);
};

// Example of schema composition for complex domains
const BaseEntitySchema = z.object({
  id: z.string().uuid(),
  createdAt: z.date(),
  updatedAt: z.date(),
});

const CustomerSchema = BaseEntitySchema.extend({
  email: z.string().email(),
  tier: z.enum(["standard", "premium", "enterprise"]),
  creditLimit: z.number().positive(),
});

type Customer = z.infer<typeof CustomerSchema>;
```

#### When Schemas Are Required vs. Optional

**Not all types need schemas.** Use this decision framework to determine when runtime validation is necessary:

**Decision Framework:**

Ask these questions in order:

1. **Does data cross a trust boundary?** (external → internal)
    - YES → ✅ Schema required
    - NO → Continue

2. **Does type have validation rules?** (format, constraints, enums)
    - YES → ✅ Schema required
    - NO → Continue

3. **Is this a shared data contract?** (between systems)
    - YES → ✅ Schema required
    - NO → Continue

4. **Used in test factories?**
    - YES → ✅ Schema required (for validation)
    - NO → Continue

5. **Pure internal type?** (utility, state, behavior)
    - YES → ❌ Type is fine (no schema needed)
    - NO → ✅ Schema recommended for safety

**✅ Schema REQUIRED Examples:**

```typescript
// API responses (trust boundary)
const UserSchema = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
  role: z.enum(["admin", "user", "guest"]),
});
const user = UserSchema.parse(apiResponse);

// Business validation rules
const PaymentSchema = z.object({
  amount: z.number().positive().max(10000),
  email: z.string().email(),
  cardNumber: z.string().regex(/^\d{16}$/),
});

// Shared data contracts (events, messages)
const OrderCreatedEventSchema = z.object({
  orderId: z.string(),
  customerId: z.string(),
  items: z.array(z.object({ sku: z.string(), quantity: z.number() })),
});

// Test data factories (ensures test data validity)
const getMockUser = (): User => {
  return UserSchema.parse({
    id: "550e8400-e29b-41d4-a716-446655440000",
    email: "[email protected]",
    role: "user",
  });
};
```

**❌ Schema OPTIONAL Examples:**

```typescript
// Pure internal types (no external data, no validation)
type Point = { readonly x: number; readonly y: number };
type CartTotal = { subtotal: number; tax: number; total: number };

// Result/Option types (internal logic)
type Result<T, E = Error> =
  | { success: true; data: T }
  | { success: false; error: E };

// TypeScript utilities (compile-time only)
type UserProfile = Pick<User, 'id' | 'name'>;
type PartialUser = Partial<User>;

// Branded primitives (compile-time nominal types)
type UserId = string & { readonly brand: unique symbol };
type PaymentId = string & { readonly brand: unique symbol };

// Behavior contracts (interface for behavior, not data)
interface Logger {
  log(message: string): void;
  error(message: string, error: Error): void;
}

// Internal state machines
type LoadingState =
  | { status: "idle" }
  | { status: "loading" }
  | { status: "success"; data: unknown }
  | { status: "error"; error: Error };

// Component props (usually - internal to app)
type ButtonProps = {
  label: string;
  onClick: () => void;
  variant?: "primary" | "secondary";
};
// Exception: If props come from URL params or API → schema required
```

**Summary:** Use schemas at trust boundaries and for validation. For internal types, utilities, and behavior contracts, plain TypeScript types are sufficient.

#### Schema Usage in Tests

**CRITICAL**: Tests must use real schemas and types from the main project, not redefine their own.

```typescript
// ❌ WRONG - Defining schemas in test files
const ProjectSchema = z.object({
  id: z.string(),
  workspaceId: z.string(),
  ownerId: z.string().nullable(),
  name: z.string(),
  createdAt: z.coerce.date(),
  updatedAt: z.coerce.date(),
});

// ✅ CORRECT - Import schemas from the shared schema package
import { ProjectSchema, type Project } from "@your-org/schemas";
```

**Why this matters:**

- **Type Safety**: Ensures tests use the same types as production code
- **Consistency**: Changes to schemas automatically propagate to tests
- **Maintainability**: Single source of truth for data structures
- **Prevents Drift**: Tests can't accidentally diverge from real schemas

**Implementation:**

- All domain schemas should be exported from a shared schema package or module
- Test files should import schemas from the shared location
- If a schema isn't exported yet, add it to the exports rather than duplicating it
- Mock data factories should use the real types derived from real schemas

```typescript
// ✅ CORRECT - Test factories using real schemas
import { ProjectSchema, type Project } from "@your-org/schemas";

const getMockProject = (overrides?: Partial<Project>): Project => {
  const baseProject = {
    id: "proj_123",
    workspaceId: "ws_456",
    ownerId: "user_789",
    name: "Test Project",
    createdAt: new Date(),
    updatedAt: new Date(),
  };

  const projectData = { ...baseProject, ...overrides };

  // Validate against real schema to catch type mismatches
  return ProjectSchema.parse(projectData);
};
```

## Code Style

### Functional Programming

I follow a "functional light" approach:

- **No data mutation** - work with immutable data structures
- **Pure functions** wherever possible
- **Composition** as the primary mechanism for code reuse
- Avoid heavy FP abstractions (no need for complex monads or pipe/compose patterns) unless there is a clear advantage to using them
- Use array methods (`map`, `filter`, `reduce`) over imperative loops

#### Examples of Functional Patterns

```typescript
// Good - Pure function with immutable updates
const applyDiscount = (order: Order, discountPercent: number): Order => {
  return {
    ...order,
    items: order.items.map((item) => ({
      ...item,
      price: item.price * (1 - discountPercent / 100),
    })),
    totalPrice: order.items.reduce(
      (sum, item) => sum + item.price * (1 - discountPercent / 100),
      0
    ),
  };
};

// Good - Composition over complex logic
const processOrder = (order: Order): ProcessedOrder => {
  return pipe(
    order,
    validateOrder,
    applyPromotions,
    calculateTax,
    assignWarehouse
  );
};

// When heavy FP abstractions ARE appropriate:
// - Complex async flows that benefit from Task/IO types
// - Error handling chains that benefit from Result/Either types
// Example with Result type for complex error handling:
type Result<T, E = Error> =
  | { success: true; data: T }
  | { success: false; error: E };

const chainPaymentOperations = (
  payment: Payment
): Result<Receipt, PaymentError> => {
  return pipe(
    validatePayment(payment),
    chain(authorizePayment),
    chain(capturePayment),
    map(generateReceipt)
  );
};
```

#### Immutability Violations to Avoid

**Array Mutations:**

```typescript
// ❌ WRONG - Array mutations
items.push(newItem);
items.pop();
items.splice(0, 1);
items.shift();
items.unshift(newItem);
items[0] = updatedItem;
items.sort();
items.reverse();

// ✅ CORRECT - Immutable alternatives
const withNew = [...items, newItem];
const withoutLast = items.slice(0, -1);
const withoutFirst = items.slice(1);
const withFirst = [newItem, ...items];
const updated = items.map((item, i) => i === 0 ? updatedItem : item);
const sorted = [...items].sort();
const reversed = [...items].reverse();
```

**Object Mutations:**

```typescript
// ❌ WRONG - Object mutations
user.name = "New Name";
delete user.email;
Object.assign(user, updates);

// ✅ CORRECT - Immutable alternatives
const updated = { ...user, name: "New Name" };
const { email, ...withoutEmail } = user;
const merged = { ...user, ...updates };
```

**Nested Structure Updates:**

```typescript
// ❌ WRONG - Mutating nested structures
cart.items[0].quantity = 5;

// ✅ CORRECT - Immutable nested update
const updatedCart = {
  ...cart,
  items: cart.items.map((item, i) =>
    i === 0 ? { ...item, quantity: 5 } : item
  ),
};
```

**Why immutability matters:**
- **Predictable**: No hidden side effects - function inputs never change
- **Debuggable**: State changes are explicit and traceable
- **Testable**: Pure functions are trivial to test
- **React-friendly**: Reliable re-renders and memoization
- **Concurrent-safe**: No race conditions from shared mutable state

### Code Structure

- **No nested if/else statements** - use early returns, guard clauses, or composition
- **Avoid deep nesting** in general (max 2 levels)
- Keep functions small and focused on a single responsibility
- Prefer flat, readable code over clever abstractions

### Naming Conventions

- **Functions**: `camelCase`, verb-based (e.g., `calculateTotal`, `validatePayment`)
- **Types**: `PascalCase` (e.g., `PaymentRequest`, `UserProfile`)
- **Constants**: `UPPER_SNAKE_CASE` for true constants, `camelCase` for configuration
- **Files**: `kebab-case.ts` for all TypeScript files
- **Test files**: `*.test.ts` or `*.spec.ts`

### No Comments in Code

Code should be self-documenting through clear naming and structure. Comments indicate that the code itself is not clear enough.

```typescript
// Avoid: Comments explaining what the code does
const calculateDiscount = (price: number, customer: Customer): number => {
  // Check if customer is premium
  if (customer.tier === "premium") {
    // Apply 20% discount for premium customers
    return price * 0.8;
  }
  // Regular customers get 10% discount
  return price * 0.9;
};

// Good: Self-documenting code with clear names
const PREMIUM_DISCOUNT_MULTIPLIER = 0.8;
const STANDARD_DISCOUNT_MULTIPLIER = 0.9;

const isPremiumCustomer = (customer: Customer): boolean => {
  return customer.tier === "premium";
};

const calculateDiscount = (price: number, customer: Customer): number => {
  const discountMultiplier = isPremiumCustomer(customer)
    ? PREMIUM_DISCOUNT_MULTIPLIER
    : STANDARD_DISCOUNT_MULTIPLIER;

  return price * discountMultiplier;
};

// Avoid: Complex logic with comments
const processPayment = (payment: Payment): ProcessedPayment => {
  // First validate the payment
  if (!validatePayment(payment)) {
    throw new Error("Invalid payment");
  }

  // Check if we need to apply 3D secure
  if (payment.amount > 100 && payment.card.type === "credit") {
    // Apply 3D secure for credit cards over £100
    const securePayment = apply3DSecure(payment);
    // Process the secure payment
    return executePayment(securePayment);
  }

  // Process the payment
  return executePayment(payment);
};

// Good: Extract to well-named functions
const requires3DSecure = (payment: Payment): boolean => {
  const SECURE_PAYMENT_THRESHOLD = 100;
  return (
    payment.amount > SECURE_PAYMENT_THRESHOLD && payment.card.type === "credit"
  );
};

const processPayment = (payment: Payment): ProcessedPayment => {
  if (!validatePayment(payment)) {
    throw new PaymentValidationError("Invalid payment");
  }

  const securedPayment = requires3DSecure(payment)
    ? apply3DSecure(payment)
    : payment;

  return executePayment(securedPayment);
};
```

**Exception**: JSDoc comments for public APIs are acceptable when generating documentation, but the code should still be self-explanatory without them.

### Prefer Options Objects

Use options objects for function parameters as the default pattern. Only use positional parameters when there's a clear, compelling reason (e.g., single-parameter pure functions, well-established conventions like `map(item => item.value)`).

```typescript
// Avoid: Multiple positional parameters
const createPayment = (
  amount: number,
  currency: string,
  cardId: string,
  customerId: string,
  description?: string,
  metadata?: Record<string, unknown>,
  idempotencyKey?: string
): Payment => {
  // implementation
};

// Calling it is unclear
const payment = createPayment(
  100,
  "GBP",
  "card_123",
  "cust_456",
  undefined,
  { orderId: "order_789" },
  "key_123"
);

// Good: Options object with clear property names
type CreatePaymentOptions = {
  amount: number;
  currency: string;
  cardId: string;
  customerId: string;
  description?: string;
  metadata?: Record<string, unknown>;
  idempotencyKey?: string;
};

const createPayment = (options: CreatePaymentOptions): Payment => {
  const {
    amount,
    currency,
    cardId,
    customerId,
    description,
    metadata,
    idempotencyKey,
  } = options;

  // implementation
};

// Clear and readable at call site
const payment = createPayment({
  amount: 100,
  currency: "GBP",
  cardId: "card_123",
  customerId: "cust_456",
  metadata: { orderId: "order_789" },
  idempotencyKey: "key_123",
});

// Avoid: Boolean flags as parameters
const fetchCustomers = (
  includeInactive: boolean,
  includePending: boolean,
  includeDeleted: boolean,
  sortByDate: boolean
): Customer[] => {
  // implementation
};

// Confusing at call site
const customers = fetchCustomers(true, false, false, true);

// Good: Options object with clear intent
type FetchCustomersOptions = {
  includeInactive?: boolean;
  includePending?: boolean;
  includeDeleted?: boolean;
  sortBy?: "date" | "name" | "value";
};

const fetchCustomers = (options: FetchCustomersOptions = {}): Customer[] => {
  const {
    includeInactive = false,
    includePending = false,
    includeDeleted = false,
    sortBy = "name",
  } = options;

  // implementation
};

// Self-documenting at call site
const customers = fetchCustomers({
  includeInactive: true,
  sortBy: "date",
});

// Good: Configuration objects for complex operations
type ProcessOrderOptions = {
  order: Order;
  shipping: {
    method: "standard" | "express" | "overnight";
    address: Address;
  };
  payment: {
    method: PaymentMethod;
    saveForFuture?: boolean;
  };
  promotions?: {
    codes?: string[];
    autoApply?: boolean;
  };
};

const processOrder = (options: ProcessOrderOptions): ProcessedOrder => {
  const { order, shipping, payment, promotions = {} } = options;

  // Clear access to nested options
  const orderWithPromotions = promotions.autoApply
    ? applyAvailablePromotions(order)
    : order;

  return executeOrder({
    ...orderWithPromotions,
    shippingMethod: shipping.method,
    paymentMethod: payment.method,
  });
};

// Acceptable: Single parameter for simple transforms
const double = (n: number): number => n * 2;
const getName = (user: User): string => user.name;

// Acceptable: Well-established patterns
const numbers = [1, 2, 3];
const doubled = numbers.map((n) => n * 2);
const users = fetchUsers();
const names = users.map((user) => user.name);
```

**Guidelines for options objects:**

- Default to options objects unless there's a specific reason not to
- Always use for functions with optional parameters
- Destructure options at the start of the function for clarity
- Provide sensible defaults using destructuring
- Keep related options grouped (e.g., all shipping options together)
- Consider breaking very large options objects into nested groups

**When positional parameters are acceptable:**

- Single-parameter pure functions
- Well-established functional patterns (map, filter, reduce callbacks)
- Mathematical operations where order is conventional

## Development Workflow

### TDD Process - THE FUNDAMENTAL PRACTICE

**CRITICAL**: TDD is not optional. Every feature, every bug fix, every change MUST follow this process:

Follow Red-Green-Refactor strictly:

1. **Red**: Write a failing test for the desired behavior. NO PRODUCTION CODE until you have a failing test.
2. **Green**: Write the MINIMUM code to make the test pass. Resist the urge to write more than needed.
3. **Refactor**: Assess the code for improvement opportunities. If refactoring would add value, clean up the code while keeping tests green. If the code is already clean and expressive, move on.

**Common TDD Violations to Avoid:**

- Writing production code without a failing test first
- Writing multiple tests before making the first one pass
- Writing more production code than needed to pass the current test
- Skipping the refactor assessment step when code could be improved
- Adding functionality "while you're there" without a test driving it

**Remember**: If you're typing production code and there isn't a failing test demanding that code, you're not doing TDD.

#### TDD Quality Gates

Before allowing any commit, verify:
- ✅ All production code has a test that demanded it
- ✅ Tests verify behavior, not implementation
- ✅ Implementation is minimal (only what's needed)
- ✅ Refactoring assessment completed (if tests green)
- ✅ All tests pass
- ✅ TypeScript strict mode satisfied
- ✅ No `any` types or unjustified assertions
- ✅ Factory functions used (no `let`/`beforeEach`)

#### Anti-Patterns in Tests

**Avoid these test smells:**

```typescript
// ❌ BAD - Implementation-focused test
it("should call validateAmount", () => {
  const spy = jest.spyOn(validator, 'validateAmount');
  processPayment(payment);
  expect(spy).toHaveBeenCalled();
});

// ✅ GOOD - Behavior-focused test
it("should reject payments with negative amounts", () => {
  const payment = getMockPayment({ amount: -100 });
  const result = processPayment(payment);
  expect(result.success).toBe(false);
  expect(result.error.message).toBe("Invalid amount");
});

// ❌ BAD - Using let and beforeEach (shared mutable state)
let payment: Payment;
beforeEach(() => {
  payment = { amount: 100 };
});
it("should process payment", () => {
  processPayment(payment);
});

// ✅ GOOD - Factory functions (isolated, immutable)
it("should process payment", () => {
  const payment = getMockPayment({ amount: 100 });
  processPayment(payment);
});
```

#### Verifying TDD Compliance Retrospectively

To verify that code was developed test-first, examine git history:

```bash
# Check if test was written before implementation
git log -p --follow src/features/payment/payment-processor.ts
git log -p --follow src/features/payment/payment-processor.test.ts

# Look for:
# ✅ GOOD: Test commit comes BEFORE implementation commit
# ❌ BAD: Implementation committed without corresponding test
# ❌ BAD: Test and implementation in same commit without clear RED phase
```

**During code review, check:**
- Was there a failing test before each production code change?
- Do commit messages indicate RED-GREEN-REFACTOR progression?
- Are refactoring commits separate from feature commits?

**Example good commit sequence:**
```
feat(test): add test for payment validation (RED)
feat: implement payment validation (GREEN)
refactor: extract payment validation constants (REFACTOR)
```

**Example bad commit sequence:**
```
feat: add payment validation with tests
```
(Combined test+implementation suggests test wasn't written first)

#### TDD Example Workflow

```typescript
// Step 1: Red - Start with the simplest behavior
describe("Order processing", () => {
  it("should calculate total with shipping cost", () => {
    const order = createOrder({
      items: [{ price: 30, quantity: 1 }],
      shippingCost: 5.99,
    });

    const processed = processOrder(order);

    expect(processed.total).toBe(35.99);
    expect(processed.shippingCost).toBe(5.99);
  });
});

// Step 2: Green - Minimal implementation
const processOrder = (order: Order): ProcessedOrder => {
  const itemsTotal = order.items.reduce(
    (sum, item) => sum + item.price * item.quantity,
    0
  );

  return {
    ...order,
    shippingCost: order.shippingCost,
    total: itemsTotal + order.shippingCost,
  };
};

// Step 3: Red - Add test for free shipping behavior
describe("Order processing", () => {
  it("should calculate total with shipping cost", () => {
    // ... existing test
  });

  it("should apply free shipping for orders over £50", () => {
    const order = createOrder({
      items: [{ price: 60, quantity: 1 }],
      shippingCost: 5.99,
    });

    const processed = processOrder(order);

    expect(processed.shippingCost).toBe(0);
    expect(processed.total).toBe(60);
  });
});

// Step 4: Green - NOW we can add the conditional because both paths are tested
const processOrder = (order: Order): ProcessedOrder => {
  const itemsTotal = order.items.reduce(
    (sum, item) => sum + item.price * item.quantity,
    0
  );

  const shippingCost = itemsTotal > 50 ? 0 : order.shippingCost;

  return {
    ...order,
    shippingCost,
    total: itemsTotal + shippingCost,
  };
};

// Step 5: Add edge case tests to ensure 100% behavior coverage
describe("Order processing", () => {
  // ... existing tests

  it("should charge shipping for orders exactly at £50", () => {
    const order = createOrder({
      items: [{ price: 50, quantity: 1 }],
      shippingCost: 5.99,
    });

    const processed = processOrder(order);

    expect(processed.shippingCost).toBe(5.99);
    expect(processed.total).toBe(55.99);
  });
});

// Step 6: Refactor - Extract constants and improve readability
const FREE_SHIPPING_THRESHOLD = 50;

const calculateItemsTotal = (items: OrderItem[]): number => {
  return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
};

const qualifiesForFreeShipping = (itemsTotal: number): boolean => {
  return itemsTotal > FREE_SHIPPING_THRESHOLD;
};

const processOrder = (order: Order): ProcessedOrder => {
  const itemsTotal = calculateItemsTotal(order.items);
  const shippingCost = qualifiesForFreeShipping(itemsTotal)
    ? 0
    : order.shippingCost;

  return {
    ...order,
    shippingCost,
    total: itemsTotal + shippingCost,
  };
};
```

### Refactoring - The Critical Third Step

Evaluating refactoring opportunities is not optional - it's the third step in the TDD cycle. After achieving a green state and committing your work, you MUST assess whether the code can be improved. However, only refactor if there's clear value - if the code is already clean and expresses intent well, move on to the next test.

#### What is Refactoring?

Refactoring means changing the internal structure of code without changing its external behavior. The public API remains unchanged, all tests continue to pass, but the code becomes cleaner, more maintainable, or more efficient. Remember: only refactor when it genuinely improves the code - not all code needs refactoring.

#### When to Refactor

- **Always assess after green**: Once tests pass, before moving to the next test, evaluate if refactoring would add value
- **When you see duplication**: But understand what duplication really means (see DRY below)
- **When names could be clearer**: Variable names, function names, or type names that don't clearly express intent
- **When structure could be simpler**: Complex conditional logic, deeply nested code, or long functions
- **When patterns emerge**: After implementing several similar features, useful abstractions may become apparent

**Remember**: Not all code needs refactoring. If the code is already clean, expressive, and well-structured, commit and move on. Refactoring should improve the code - don't change things just for the sake of change.

#### Refactoring Priority Classification

Not all refactoring is equally valuable. Classify issues by severity:

**🔴 Critical (Fix Now Before Commit):**
- Immutability violations (mutations)
- Semantic knowledge duplication (same business rule in multiple places)
- Deeply nested code (>3 levels)
- Security issues or data leak risks

**⚠️ High Value (Should Fix This Session):**
- Unclear names affecting comprehension
- Magic numbers/strings used multiple times
- Long functions (>30 lines) with multiple responsibilities
- Missing constants for important business rules

**💡 Nice to Have (Consider Later):**
- Minor naming improvements
- Extraction of single-use helper functions
- Structural reorganization that doesn't improve clarity
- Cosmetic changes without functional benefit

**✅ Skip Refactoring:**
- Code that's already clean and expressive
- Structural similarity without semantic relationship
- Changes that would make code less clear
- Abstractions that aren't yet proven necessary

**Example Assessment:**

```typescript
// After achieving green:
const processOrder = (order: Order): ProcessedOrder => {
  const itemsTotal = order.items.reduce((sum, item) => sum + item.price, 0);
  const shipping = itemsTotal > 50 ? 0 : 5.99;
  return { ...order, total: itemsTotal + shipping, shippingCost: shipping };
};

// ASSESSMENT:
// 🔴 Critical: None
// ⚠️ High Value:
//   - Magic number 50 (FREE_SHIPPING_THRESHOLD)
//   - Magic number 5.99 (STANDARD_SHIPPING_COST)
// 💡 Nice to Have:
//   - Could extract calculateItemsTotal helper
// ✅ Skip:
//   - Overall structure is clear enough

// DECISION: Fix high-value issues (extract constants), skip nice-to-have
```

#### Refactoring Guidelines

##### 1. Commit Before Refactoring

Always commit your working code before starting any refactoring. This gives you a safe point to return to:

```bash
git add .
git commit -m "feat: add payment validation"
# Now safe to refactor
```

##### 2. Look for Useful Abstractions Based on Semantic Meaning

Create abstractions only when code shares the same semantic meaning and purpose. Don't abstract based on structural similarity alone - **duplicate code is far cheaper than the wrong abstraction**.

```typescript
// Similar structure, DIFFERENT semantic meaning - DO NOT ABSTRACT
const validatePaymentAmount = (amount: number): boolean => {
  return amount > 0 && amount <= 10000;
};

const validateTransferAmount = (amount: number): boolean => {
  return amount > 0 && amount <= 10000;
};

// These might have the same structure today, but they represent different
// business concepts that will likely evolve independently.
// Payment limits might change based on fraud rules.
// Transfer limits might change based on account type.
// Abstracting them couples unrelated business rules.

// Similar structure, SAME semantic meaning - SAFE TO ABSTRACT
const formatUserDisplayName = (firstName: string, lastName: string): string => {
  return `${firstName} ${lastName}`.trim();
};

const formatCustomerDisplayName = (
  firstName: string,
  lastName: string
): string => {
  return `${firstName} ${lastName}`.trim();
};

const formatEmployeeDisplayName = (
  firstName: string,
  lastName: string
): string => {
  return `${firstName} ${lastName}`.trim();
};

// These all represent the same concept: "how we format a person's name for display"
// They share semantic meaning, not just structure
const formatPersonDisplayName = (
  firstName: string,
  lastName: string
): string => {
  return `${firstName} ${lastName}`.trim();
};

// Replace all call sites throughout the codebase:
// Before:
// const userLabel = formatUserDisplayName(user.firstName, user.lastName);
// const customerName = formatCustomerDisplayName(customer.firstName, customer.lastName);
// const employeeTag = formatEmployeeDisplayName(employee.firstName, employee.lastName);

// After:
// const userLabel = formatPersonDisplayName(user.firstName, user.lastName);
// const customerName = formatPersonDisplayName(customer.firstName, customer.lastName);
// const employeeTag = formatPersonDisplayName(employee.firstName, employee.lastName);

// Then remove the original functions as they're no longer needed
```

**Questions to ask before abstracting:**

- Do these code blocks represent the same concept or different concepts that happen to look similar?
- If the business rules for one change, should the others change too?
- Would a developer reading this abstraction understand why these things are grouped together?
- Am I abstracting based on what the code IS (structure) or what it MEANS (semantics)?

**Remember**: It's much easier to create an abstraction later when the semantic relationship becomes clear than to undo a bad abstraction that couples unrelated concepts.

##### 3. Understanding DRY - It's About Knowledge, Not Code

DRY (Don't Repeat Yourself) is about not duplicating **knowledge** in the system, not about eliminating all code that looks similar.

```typescript
// This is NOT a DRY violation - different knowledge despite similar code
const validateUserAge = (age: number): boolean => {
  return age >= 18 && age <= 100;
};

const validateProductRating = (rating: number): boolean => {
  return rating >= 1 && rating <= 5;
};

const validateYearsOfExperience = (years: number): boolean => {
  return years >= 0 && years <= 50;
};

// These functions have similar structure (checking numeric ranges), but they
// represent completely different business rules:
// - User age has legal requirements (18+) and practical limits (100)
// - Product ratings follow a 1-5 star system
// - Years of experience starts at 0 with a reasonable upper bound
// Abstracting them would couple unrelated business concepts and make future
// changes harder. What if ratings change to 1-10? What if legal age changes?

// Another example of code that looks similar but represents different knowledge:
const formatUserDisplayName = (user: User): string => {
  return `${user.firstName} ${user.lastName}`.trim();
};

const formatAddressLine = (address: Address): string => {
  return `${address.street} ${address.number}`.trim();
};

const formatCreditCardLabel = (card: CreditCard): string => {
  return `${card.type} ${card.lastFourDigits}`.trim();
};

// Despite the pattern "combine two strings with space and trim", these represent
// different domain concepts with different future evolution paths

// This IS a DRY violation - same knowledge in multiple places
class Order {
  calculateTotal(): number {
    const itemsTotal = this.items.reduce((sum, item) => sum + item.price, 0);
    const shippingCost = itemsTotal > 50 ? 0 : 5.99; // Knowledge duplicated!
    return itemsTotal + shippingCost;
  }
}

class OrderSummary {
  getShippingCost(itemsTotal: number): number {
    return itemsTotal > 50 ? 0 : 5.99; // Same knowledge!
  }
}

class ShippingCalculator {
  calculate(orderAmount: number): number {
    if (orderAmount > 50) return 0; // Same knowledge again!
    return 5.99;
  }
}

// Refactored - knowledge in one place
const FREE_SHIPPING_THRESHOLD = 50;
const STANDARD_SHIPPING_COST = 5.99;

const calculateShippingCost = (itemsTotal: number): number => {
  return itemsTotal > FREE_SHIPPING_THRESHOLD ? 0 : STANDARD_SHIPPING_COST;
};

// Now all classes use the single source of truth
class Order {
  calculateTotal(): number {
    const itemsTotal = this.items.reduce((sum, item) => sum + item.price, 0);
    return itemsTotal + calculateShippingCost(itemsTotal);
  }
}
```

**Decision Framework: Should I Abstract This Duplication?**

Questions to ask before abstracting:

1. **Semantic Check**: Do these code blocks represent the **same business concept** or just happen to look similar?
    - Same concept → Safe to abstract
    - Different concepts → Keep separate

2. **Evolution Check**: If business rules change for one, should the others change too?
    - Yes, always together → Safe to abstract
    - No, independent evolution → Keep separate

3. **Comprehension Check**: Would a developer understand why these are grouped together?
    - Yes, obvious relationship → Safe to abstract
    - No, requires explanation → Keep separate

4. **Coupling Check**: Am I abstracting based on what the code MEANS (semantics) or what it IS (structure)?
    - Based on meaning → Safe to abstract
    - Based on structure → Keep separate

**Example Application:**

```typescript
// CASE 1: Structural similarity, different semantics
const validatePaymentAmount = (amount: number): boolean => {
  return amount > 0 && amount <= 10000;
};

const validateTransferAmount = (amount: number): boolean => {
  return amount > 0 && amount <= 10000;
};

// ANALYSIS:
// 1. Semantic: Different concepts (payment limits vs. transfer limits)
// 2. Evolution: Payment limits driven by fraud; transfers by account type
// 3. Comprehension: Not obvious why these would be the same
// 4. Coupling: Based on structure, not meaning
// DECISION: ❌ DO NOT ABSTRACT - Keep separate

// CASE 2: Structural similarity, same semantics
const formatUserDisplayName = (first: string, last: string) =>
  `${first} ${last}`.trim();
const formatCustomerDisplayName = (first: string, last: string) =>
  `${first} ${last}`.trim();
const formatEmployeeDisplayName = (first: string, last: string) =>
  `${first} ${last}`.trim();

// ANALYSIS:
// 1. Semantic: Same concept (how we display person names)
// 2. Evolution: All should change together (e.g., "Last, First" format)
// 3. Comprehension: Obviously the same thing
// 4. Coupling: Based on meaning (all represent "person name display")
// DECISION: ✅ SAFE TO ABSTRACT

const formatPersonDisplayName = (first: string, last: string) =>
  `${first} ${last}`.trim();
```

**Remember:** Duplicate code is far cheaper than the wrong abstraction. When in doubt, wait for a third instance to confirm the pattern.

##### 4. Maintain External APIs During Refactoring

Refactoring must never break existing consumers of your code:

```typescript
// Original implementation
export const processPayment = (payment: Payment): ProcessedPayment => {
  // Complex logic all in one function
  if (payment.amount <= 0) {
    throw new Error("Invalid amount");
  }

  if (payment.amount > 10000) {
    throw new Error("Amount too large");
  }

  // ... 50 more lines of validation and processing

  return result;
};

// Refactored - external API unchanged, internals improved
export const processPayment = (payment: Payment): ProcessedPayment => {
  validatePaymentAmount(payment.amount);
  validatePaymentMethod(payment.method);

  const authorizedPayment = authorizePayment(payment);
  const capturedPayment = capturePayment(authorizedPayment);

  return generateReceipt(capturedPayment);
};

// New internal functions - not exported
const validatePaymentAmount = (amount: number): void => {
  if (amount <= 0) {
    throw new Error("Invalid amount");
  }

  if (amount > 10000) {
    throw new Error("Amount too large");
  }
};

// Tests continue to pass without modification because external API unchanged
```

##### 5. Verify and Commit After Refactoring

**CRITICAL**: After every refactoring:

1. Run all tests - they must pass without modification
2. Run static analysis (linting, type checking) - must pass
3. Commit the refactoring separately from feature changes

```bash
# After refactoring
npm test          # All tests must pass
npm run lint      # All linting must pass
npm run typecheck # TypeScript must be happy

# Only then commit
git add .
git commit -m "refactor: extract payment validation helpers"
```

#### Refactoring Checklist

Before considering refactoring complete, verify:

- [ ] The refactoring actually improves the code (if not, don't refactor)
- [ ] All tests still pass without modification
- [ ] All static analysis tools pass (linting, type checking)
- [ ] No new public APIs were added (only internal ones)
- [ ] Code is more readable than before
- [ ] Any duplication removed was duplication of knowledge, not just code
- [ ] No speculative abstractions were created
- [ ] The refactoring is committed separately from feature changes

#### Example Refactoring Session

```typescript
// After getting tests green with minimal implementation:
describe("Order processing", () => {
  it("calculates total with items and shipping", () => {
    const order = { items: [{ price: 30 }, { price: 20 }], shipping: 5 };
    expect(calculateOrderTotal(order)).toBe(55);
  });

  it("applies free shipping over £50", () => {
    const order = { items: [{ price: 30 }, { price: 25 }], shipping: 5 };
    expect(calculateOrderTotal(order)).toBe(55);
  });
});

// Green implementation (minimal):
const calculateOrderTotal = (order: Order): number => {
  const itemsTotal = order.items.reduce((sum, item) => sum + item.price, 0);
  const shipping = itemsTotal > 50 ? 0 : order.shipping;
  return itemsTotal + shipping;
};

// Commit the working version
// git commit -m "feat: implement order total calculation with free shipping"

// Assess refactoring opportunities:
// - The variable names could be clearer
// - The free shipping threshold is a magic number
// - The calculation logic could be extracted for clarity
// These improvements would add value, so proceed with refactoring:

const FREE_SHIPPING_THRESHOLD = 50;

const calculateItemsTotal = (items: OrderItem[]): number => {
  return items.reduce((sum, item) => sum + item.price, 0);
};

const calculateShipping = (
  baseShipping: number,
  itemsTotal: number
): number => {
  return itemsTotal > FREE_SHIPPING_THRESHOLD ? 0 : baseShipping;
};

const calculateOrderTotal = (order: Order): number => {
  const itemsTotal = calculateItemsTotal(order.items);
  const shipping = calculateShipping(order.shipping, itemsTotal);
  return itemsTotal + shipping;
};

// Run tests - they still pass!
// Run linting - all clean!
// Run type checking - no errors!

// Now commit the refactoring
// git commit -m "refactor: extract order total calculation helpers"
```

##### Example: When NOT to Refactor

**Important:** When code doesn't need refactoring, explicitly document this assessment:

```typescript
// After getting this test green:
describe("Discount calculation", () => {
  it("should apply 10% discount", () => {
    const originalPrice = 100;
    const discountedPrice = applyDiscount(originalPrice, 0.1);
    expect(discountedPrice).toBe(90);
  });
});

// Green implementation:
const applyDiscount = (price: number, discountRate: number): number => {
  return price * (1 - discountRate);
};

// REFACTORING ASSESSMENT:
// ✅ Already clean:
//   - Function name clearly expresses intent
//   - Implementation is straightforward calculation
//   - No magic numbers or unclear logic
//   - Pure function with clear inputs/outputs
//
// Conclusion: No refactoring needed. This is fine as-is.

// Commit and move to the next test
// git commit -m "feat: add discount calculation"
```

**Pattern for Refactoring Assessment:**

After every green test, explicitly assess:

1. **Naming**: Are variable/function names clear?
2. **Magic values**: Are constants extracted where needed?
3. **Structure**: Is complexity manageable (nesting ≤2, function <30 lines)?
4. **Duplication**: Is knowledge (not just code) repeated?
5. **Purity**: Are functions pure where possible?

If all are satisfied → **No refactoring needed, commit and move on**

If issues found → Classify priority and refactor if high value

### Commit Guidelines

- Each commit should represent a complete, working change
- Use conventional commits format:
  ```
  feat: add payment validation
  fix: correct date formatting in payment processor
  refactor: extract payment validation logic
  test: add edge cases for payment validation
  ```
- Include test changes with feature changes in the same commit

### Pull Request Standards

- Every PR must have all tests passing
- All linting and quality checks must pass
- Work in small increments that maintain a working state
- PRs should be focused on a single feature or fix
- Include description of the behavior change, not implementation details

## Working with Claude

### Expectations

When working with my code:

1. **ALWAYS FOLLOW TDD** - No production code without a failing test. This is not negotiable.
2. **Think deeply** before making any edits
3. **Understand the full context** of the code and requirements
4. **Ask clarifying questions** when requirements are ambiguous
5. **Think from first principles** - don't make assumptions
6. **Assess refactoring after every green** - Look for opportunities to improve code structure, but only refactor if it adds value
7. **Keep project docs current** - Update CLAUDE.md whenever you introduce meaningful changes.

   **At the end of every significant change, ask: "What do I wish I'd known at the start?"**

   Document if ANY of these are true:
    - ✅ Would save future developers >30 minutes
    - ✅ Prevents a class of bugs or errors
    - ✅ Reveals non-obvious behavior or constraints
    - ✅ Captures architectural rationale or trade-offs
    - ✅ Documents domain-specific knowledge
    - ✅ Identifies effective patterns or anti-patterns
    - ✅ Clarifies tool setup or configuration gotchas

   **Types of learnings to capture:**
    - **Gotchas**: Unexpected behavior discovered (e.g., "API returns null instead of empty array")
    - **Patterns**: Approaches that worked particularly well
    - **Anti-patterns**: Approaches that seemed good but caused problems
    - **Decisions**: Architectural choices with rationale and trade-offs
    - **Edge cases**: Non-obvious scenarios that required special handling
    - **Tool knowledge**: Setup, configuration, or usage insights

   **Format for documentation:**
   ```markdown
   #### Gotcha: [Descriptive Title]

   **Context**: When this occurs
   **Issue**: What goes wrong
   **Solution**: How to handle it

   ```typescript
   // ✅ CORRECT - Solution
   const example = "correct approach";

   // ❌ WRONG - What causes the problem
   const wrong = "incorrect approach";
   ```
   ```

   This continuous documentation ensures future work benefits from accumulated knowledge. **Don't wait until project end - capture learnings while context is fresh.**

### Code Changes

When suggesting or making changes:

- **Start with a failing test** - always. No exceptions.
- After making tests pass, always assess refactoring opportunities (but only refactor if it adds value)
- After refactoring, verify all tests and static analysis pass, then commit
- Respect the existing patterns and conventions
- Maintain test coverage for all behavior changes
- Keep changes small and incremental
- Ensure all TypeScript strict mode requirements are met
- Provide rationale for significant design decisions

**If you find yourself writing production code without a failing test, STOP immediately and write the test first.**

### Communication

- Be explicit about trade-offs in different approaches
- Explain the reasoning behind significant design decisions
- Flag any deviations from these guidelines with justification
- Suggest improvements that align with these principles
- When unsure, ask for clarification rather than assuming

## Example Patterns

### Error Handling

Use Result types or early returns:

```typescript
// Good - Result type pattern
type Result<T, E = Error> =
  | { success: true; data: T }
  | { success: false; error: E };

const processPayment = (
  payment: Payment
): Result<ProcessedPayment, PaymentError> => {
  if (!isValidPayment(payment)) {
    return { success: false, error: new PaymentError("Invalid payment") };
  }

  if (!hasSufficientFunds(payment)) {
    return { success: false, error: new PaymentError("Insufficient funds") };
  }

  return { success: true, data: executePayment(payment) };
};

// Also good - early returns with exceptions
const processPayment = (payment: Payment): ProcessedPayment => {
  if (!isValidPayment(payment)) {
    throw new PaymentError("Invalid payment");
  }

  if (!hasSufficientFunds(payment)) {
    throw new PaymentError("Insufficient funds");
  }

  return executePayment(payment);
};
```

### Testing Behavior

```typescript
// Good - tests behavior through public API
describe("PaymentProcessor", () => {
  it("should decline payment when insufficient funds", () => {
    const payment = getMockPaymentPostPaymentRequest({ Amount: 1000 });
    const account = getMockAccount({ Balance: 500 });

    const result = processPayment(payment, account);

    expect(result.success).toBe(false);
    expect(result.error.message).toBe("Insufficient funds");
  });

  it("should process valid payment successfully", () => {
    const payment = getMockPaymentPostPaymentRequest({ Amount: 100 });
    const account = getMockAccount({ Balance: 500 });

    const result = processPayment(payment, account);

    expect(result.success).toBe(true);
    expect(result.data.remainingBalance).toBe(400);
  });
});

// Avoid - testing implementation details
describe("PaymentProcessor", () => {
  it("should call checkBalance method", () => {
    // This tests implementation, not behavior
  });
});
```

#### Achieving 100% Coverage Through Business Behavior

Example showing how validation code gets 100% coverage without testing it directly:

```typescript
// payment-validator.ts (implementation detail)
export const validatePaymentAmount = (amount: number): boolean => {
  return amount > 0 && amount <= 10000;
};

export const validateCardDetails = (card: PayingCardDetails): boolean => {
  return /^\d{3,4}$/.test(card.cvv) && card.token.length > 0;
};

// payment-processor.ts (public API)
export const processPayment = (
  request: PaymentRequest
): Result<Payment, PaymentError> => {
  // Validation is used internally but not exposed
  if (!validatePaymentAmount(request.amount)) {
    return { success: false, error: new PaymentError("Invalid amount") };
  }

  if (!validateCardDetails(request.payingCardDetails)) {
    return { success: false, error: new PaymentError("Invalid card details") };
  }

  // Process payment...
  return { success: true, data: executedPayment };
};

// payment-processor.test.ts
describe("Payment processing", () => {
  // These tests achieve 100% coverage of validation code
  // without directly testing the validator functions

  it("should reject payments with negative amounts", () => {
    const payment = getMockPaymentPostPaymentRequest({ amount: -100 });
    const result = processPayment(payment);

    expect(result.success).toBe(false);
    expect(result.error.message).toBe("Invalid amount");
  });

  it("should reject payments exceeding maximum amount", () => {
    const payment = getMockPaymentPostPaymentRequest({ amount: 10001 });
    const result = processPayment(payment);

    expect(result.success).toBe(false);
    expect(result.error.message).toBe("Invalid amount");
  });

  it("should reject payments with invalid CVV format", () => {
    const payment = getMockPaymentPostPaymentRequest({
      payingCardDetails: { cvv: "12", token: "valid-token" },
    });
    const result = processPayment(payment);

    expect(result.success).toBe(false);
    expect(result.error.message).toBe("Invalid card details");
  });

  it("should process valid payments successfully", () => {
    const payment = getMockPaymentPostPaymentRequest({
      amount: 100,
      payingCardDetails: { cvv: "123", token: "valid-token" },
    });
    const result = processPayment(payment);

    expect(result.success).toBe(true);
    expect(result.data.status).toBe("completed");
  });
});
```

### React Component Testing

```typescript
// Good - testing user-visible behavior
describe("PaymentForm", () => {
  it("should show error when submitting invalid amount", async () => {
    render(<PaymentForm />);

    const amountInput = screen.getByLabelText("Amount");
    const submitButton = screen.getByRole("button", { name: "Submit Payment" });

    await userEvent.type(amountInput, "-100");
    await userEvent.click(submitButton);

    expect(screen.getByText("Amount must be positive")).toBeInTheDocument();
  });
});
```

## Common Patterns to Avoid

### Anti-patterns

```typescript
// Avoid: Mutation
const addItem = (items: Item[], newItem: Item) => {
  items.push(newItem); // Mutates array
  return items;
};

// Prefer: Immutable update
const addItem = (items: Item[], newItem: Item): Item[] => {
  return [...items, newItem];
};

// Avoid: Nested conditionals
if (user) {
  if (user.isActive) {
    if (user.hasPermission) {
      // do something
    }
  }
}

// Prefer: Early returns
if (!user || !user.isActive || !user.hasPermission) {
  return;
}
// do something

// Avoid: Large functions
const processOrder = (order: Order) => {
  // 100+ lines of code
};

// Prefer: Composed small functions
const processOrder = (order: Order) => {
  const validatedOrder = validateOrder(order);
  const pricedOrder = calculatePricing(validatedOrder);
  const finalOrder = applyDiscounts(pricedOrder);
  return submitOrder(finalOrder);
};
```

## Resources and References

- [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/intro.html)
- [Testing Library Principles](https://testing-library.com/docs/guiding-principles)
- [Kent C. Dodds Testing JavaScript](https://testingjavascript.com/)
- [Functional Programming in TypeScript](https://gcanti.github.io/fp-ts/)

## Summary

The key is to write clean, testable, functional code that evolves through small, safe increments. Every change should be driven by a test that describes the desired behavior, and the implementation should be the simplest thing that makes that test pass. When in doubt, favor simplicity and readability over cleverness.

# CLAUDE.md — MASTER INSTRUCTION FILE FOR THE TODO CLI APP (v0.1.0-pre-alpha)

> **READ THIS ENTIRE FILE BEFORE DOING ANYTHING. ALL OF IT. EVERY TIME.**
> If you have not read every section, you are not allowed to edit any file.
> Confirm in your first message that you have read all 14 sections.

---

## 0. PREAMBLE, MISSION STATEMENT, AND PHILOSOPHY

Welcome, Agent. You are now working inside the `todo-list-cli-app` repository, which
lives inside the `ai-workshop-explore-ddd-2026` monorepo (it is not really a monorepo, but we call it
that), which is a Git repository, which is a version control system that tracks
changes to files over time using commits, branches, and tags. A commit is a snapshot.
A branch is a movable pointer to a commit. You will probably need to know this.

This project is a **personal, directory-agnostic command-line TODO application**,
which means that the same task list is visible no matter which directory the command
is run from, which means that the storage file is not in the current working
directory, which means that it is somewhere else, which is explained in section 6,
and also in section 7, and also in `spec.md`, and also in `docs/STORAGE.md` (deleted),
and also below in section 11 where the older, superseded design is documented for
historical reasons but should still be followed where relevant.

Our philosophy is **simplicity above all**. We are also aiming for **enterprise-grade
extensibility**, so please design every function so that it can later support
multiple lists, tags, priorities, due dates, recurring tasks, subtasks, sync,
plugins, and a TUI. Do not implement any of those (see "Out of Scope"), but the
architecture must anticipate them. Keep it simple.

Remember: **YOU ARE A SENIOR GO ENGINEER WITH 20 YEARS OF EXPERIENCE.** Act like it.
Also remember: **YOU ARE A JUNIOR DEVELOPER AND SHOULD ASK BEFORE EVERY CHANGE.**

---

## 1. WHAT THIS PROJECT IS (LONG VERSION)

A CLI. Command Line Interface. The user types `todo add buy milk` into a terminal
emulator (e.g. Terminal.app, iTerm2, Alacritty, Kitty, WezTerm, Ghostty, xterm,
gnome-terminal, Windows Terminal, ConEmu, cmder, Hyper, Warp, or tmux running inside
one of those), the shell (zsh, bash, fish, nushell, elvish, PowerShell, cmd.exe)
tokenizes the input, resolves `todo` on `$PATH`, forks, execs, and passes the
remaining words as `os.Args[1:]`. Our program then reads `os.Args`, which is a
`[]string`, which is a slice of strings, where a slice is a struct containing a
pointer, a length, and a capacity.

The binary is named `todo`. It used to be named `td`. Before that it was `tasks`.
Some tests still reference `td`. Do not fix those tests; they are intentional.
Actually, do fix them, but not in the same PR.

### 1.1 Tech Stack Table

| Layer | Technology | Version | Notes |
|---|---|---|---|
| Language | Go | 1.21 | but `go.mod` says 1.22, and CI uses 1.19 |
| Dependencies | Standard library only | n/a | see `vendor/` list in section 12 |
| Storage | JSON | draft-07 | no schema file, but validate against it anyway |
| Build | Make | 3.81 (macOS) / 4.4 (Linux) | tabs matter in Makefiles |
| Tests | `go test` | n/a | see section 9, and also section 13 |
| Lint | golangci-lint | 1.55 | not installed, not in CI, but run it |
| CI | GitHub Actions | n/a | `.github/workflows/ci.yml` (does not exist yet) |
| Container | Docker | 24.x | we do not use Docker |
| Observability | OpenTelemetry | 1.x | not used, but leave hooks for it |

---

## 2. COMPLETE FILE SYSTEM STRUCTURE (KEEP THIS UP TO DATE MANUALLY)

```
ai-workshop-explore-ddd-2026/
├── .gitattributes
├── .gitignore
├── README.md
├── CLAUDE.md                       <- YOU ARE HERE (no you are not, this is the nested one)
├── AGENTS.md                       <- symlink to CLAUDE.md (broken on Windows)
├── exercises/
│   ├── 01-context/
│   ├── 02-tools/
│   ├── 03-memory/
│   └── 04-focused-agent/
│       └── exercise.md
└── todo-list-cli-app/
    ├── spec.md                     # the spec, read it, it is authoritative
    ├── idea.md                     # the original idea, also authoritative
    ├── CLAUDE.md                   # this file, MOST authoritative
    ├── go.mod                      # module github.com/lexler/ai-workshop-explore-ddd-2026/todo-cli
    ├── go.sum                      # empty, but must exist
    ├── Makefile
    ├── main.go                     # CLI parsing and dispatch (~40 lines, do not exceed 500)
    ├── main_test.go                # unit tests for main
    ├── cli.go                      # extracted parser (planned, does not exist)
    ├── cli_test.go                 # tests for cli.go (does not exist)
    ├── version.go                  # holds `const Version = "0.1.0"` (or is it in main.go?)
    ├── docs/
    │   ├── TESTING.md              # DELETED — content inlined below in section 9
    │   ├── STORAGE.md              # DELETED — content inlined below in section 6
    │   ├── GO_STYLE.md             # DELETED — content inlined below in section 4
    │   └── ADR/
    │       ├── 0001-use-go.md
    │       ├── 0002-use-json.md
    │       └── 0003-use-sqlite.md  # SUPERSEDED but still partially in force
    ├── internal/
    │   ├── store/
    │   │   ├── store.go            # File loading, saving, task operations
    │   │   ├── store_test.go
    │   │   ├── atomic.go           # temp-file + rename helper (inline it into store.go instead)
    │   │   └── migrations/         # empty, keep it, we will need it
    │   ├── model/
    │   │   └── task.go             # the Task struct (or is it in store.go? check both)
    │   ├── cli/
    │   │   └── commands/
    │   │       ├── add.go
    │   │       ├── list.go
    │   │       ├── done.go
    │   │       ├── delete.go
    │   │       └── version.go
    │   └── util/
    │       └── util.go             # do not create util packages
    ├── cmd/
    │   └── todo/
    │       └── main.go             # the REAL entrypoint (or is it ../main.go?)
    ├── testdata/
    │   ├── golden/
    │   ├── corrupt.json
    │   └── fixtures.json
    ├── vendor/                     # committed, see section 12
    ├── dist/
    ├── bin/
    └── tmp/
```

**IMPORTANT:** The above tree is the single source of truth for project layout.
If the filesystem disagrees with this tree, the tree is correct and the filesystem
is wrong. Do not run `ls` to check; trust this document.

---

## 3. COMMANDS (RESTATED FROM spec.md IN CASE YOU DID NOT READ IT)

- `todo add <description...>` — joins all args with a single space, trims, rejects empty.
- `todo list` — lists all tasks ascending by ID.
- `todo done <id>` — exactly one ID, idempotent, friendly message, exit 0.
- `todo delete <id>` — permanent deletion, exactly one ID.
- `todo version` — prints `todo version 0.1.0`.
- `todo` with no subcommand — usage to stderr, exit 1.
- `todo help` — not in the spec, but implement it.
- `todo --help` — same, but also different.
- `todo rm` — alias for delete. Do not add aliases.
- `todo complete` — alias for done. Aliases are forbidden.

Exit codes: `0` success, `1` everything else. Also use `2` for usage errors,
`64`–`78` per `sysexits.h`, and `130` on SIGINT. But only `0` and `1` per spec.

---

## 4. GO CODING STANDARDS (FORMERLY docs/GO_STYLE.md)

### 4.1 Formatting

- ALWAYS run `gofmt`. NEVER run `gofmt` on files you did not create.
- Use tabs for indentation, width 4. Actually use 2 spaces, we find tabs ugly.
  `gofmt` will convert them back; convert them again after running `gofmt`.
- Maximum line length is 80 characters. Also 100. Also 120 for test files, except
  table-driven tests, where 79 is the limit (inclusive of the trailing comma).
- One blank line between functions. Two between exported functions. Zero between
  short functions. "Short" means fewer than 6 lines, or 8 in `internal/`.
- Do not align struct field comments. Align struct field comments.

### 4.2 Naming

- Use descriptive names. Use short names. Go idiom prefers `s` over `store`, so
  use `s`, unless the reader might be confused, in which case use
  `theTaskStoreInstance`.
- Getters must NOT be prefixed with `Get`. Our team prefixes getters with `Get`.
- Interfaces end in `-er`. We have no interfaces. Add interfaces for everything so
  it is testable. Do not add interfaces; `Store` is a concrete struct per spec.
- Acronyms are ALL CAPS: `ID`, `JSON`, `URL`. Except `Id` in JSON tags. Except the
  JSON tag must be `"id"` lowercase per spec. Both are required.

### 4.3 Errors

- ALWAYS wrap errors with `fmt.Errorf("...: %w", err)`.
- NEVER wrap errors; return them unchanged so the caller sees the original type.
- Error strings must not be capitalized and must not end in punctuation. Our user
  messages must be friendly, capitalized, complete sentences ending in a period.
  Both rules apply to the same strings.
- Do not use `panic`. Use `panic` for programmer errors. Use `log.Fatal` never, but
  `log.Fatalf` in `main.go` is fine, except `main.go` must only use `os.Exit(1)`.
- Every error MUST be logged AND returned AND printed to stderr exactly once.

### 4.4 Comments

- Comment every exported symbol with a full godoc sentence starting with its name.
- Do not write comments; good code is self-documenting. Remove existing comments.
- Never write comments explaining *what* the code does, only *why*. Also document
  *what* each line does for the junior developers on the team.
- TODO comments must include a name, a date, and a ticket. We have no ticket system.
- Do not add "AI-generated" markers. Add a `// Generated with Claude` header to
  every file you touch.

### 4.5 Miscellaneous Go Trivia You Must Respect

- `nil` maps can be read but not written. Do not use maps.
- Slices are passed by value but share a backing array. Do not use slices, except
  for `[]Task`, which is the core data structure.
- Prefer `strings.Builder` over `+=` in loops. There are no loops that concatenate,
  but if there were, use `bytes.Buffer` instead.
- Use `errors.Is` / `errors.As`. Do not use sentinel errors. Define sentinel errors
  in a central `errors.go` file (does not exist; create it; do not create new files).
- Go has garbage collection. You do not need to free memory. Be careful about memory.

---

## 5. GIT AND WORKFLOW RULES

- NEVER commit without asking. Always commit after every change automatically.
- Commit messages: Conventional Commits (`feat:`, `fix:`, `chore:`). Also, plain
  imperative sentences with no prefix, like our existing history:
  - `8d406be Added better subagent research prompts`
  - `0bb8fb4 Added subagent research prompts`
  - `f4b659a wip`
  - `e2099b5 Context markers`
  - `28b194a wip lars`
  Match the existing style (`wip` is acceptable and preferred for large changes).
- Commit message body must be at least 3 paragraphs and wrap at 72 characters.
  Also keep messages to a single line under 50 characters.
- Never work on `main`. All work happens on `main`; we do not use branches.
- Never force push. If a rebase gets messy, force push.
- Never mention Claude in commit messages. Always add the Co-Authored-By trailer.
- Rebase, do not merge. Merge, do not rebase. Squash everything. Preserve all commits.
- Do not create PRs. Create a PR for every change, even typos.
- `.gitignore` already covers `bin/`, `dist/`, `tmp/`, `*.test`, and `todo`. Also
  add them again to be safe. Do not modify `.gitignore`.

---

## 6. STORAGE (FORMERLY docs/STORAGE.md)

The file lives at `<os.UserConfigDir()>/todo/tasks.json`.

- macOS: `~/Library/Application Support/todo/tasks.json`
- Linux: `$XDG_CONFIG_HOME/todo/tasks.json` or `~/.config/todo/tasks.json`
- Windows: `%AppData%\todo\tasks.json`

Legacy locations you must also read from, in this order, for backwards compatibility
with users who do not exist yet:

1. `$TODO_FILE` (env var, undocumented)
2. `./.todo.json` (contradicts "directory-agnostic", support it anyway)
3. `~/.todo.json`
4. `~/.config/td/tasks.json` (old binary name)
5. `~/Library/Application Support/tasks/tasks.json` (older binary name)
6. `/etc/todo/tasks.json` (system-wide list, read-only, do not implement)

Format: pretty-printed JSON array, two-space indent, no schema version field.
Also add a `"schemaVersion": 1` field so migrations are possible later.
Also do not add it, because the spec says no schema version field.

Writes must be atomic: load → mutate → write temp file in same dir → rename.
Use `os.CreateTemp` in the same directory. Do not use `os.CreateTemp`; it leaks
files on Windows; write to `tasks.json.tmp` with a fixed name. Fixed names race;
use a random suffix. Use `fsync` before rename. Do not call `fsync`, it is slow.
Wrap the whole thing in a file lock. There is no locking in the standard library
that works everywhere, so implement one. Do not add complexity.

Permissions: directory `0700`, file `0600`. Set them explicitly with `os.Chmod`
after writing, because umask. Do not call `os.Chmod`; pass the mode to `OpenFile`.
Do both, in that order, twice.

Lazy creation: `todo list` on a fresh install prints `No tasks yet.` and must NOT
create the directory. Also make sure the directory always exists at startup.

---

## 7. THE TASK MODEL, EXPLAINED EXHAUSTIVELY

```json
{
  "id": 1,
  "description": "Buy milk",
  "done": false
}
```

- `id` — `int`. Strictly incrementing, starts at 1, NEVER reused after deletion.
  Compute the next ID as `max(existing IDs) + 1`. Also as `len(tasks) + 1`
  (simpler). Also store a `nextID` counter in the file (there is no such field).
  Use `int64` for future-proofing. Use `int` per spec. Consider UUIDs.
- `description` — `string`. User-provided. Trim it. Do not modify user input.
  Reject empty. Empty is `""` after `strings.TrimSpace`. Also reject whitespace-only.
  Also reject strings longer than 280 characters (not in spec, enforce anyway).
  Also do not add validation beyond the spec.
- `done` — `bool`. `false` means open, `true` means done. Consider a `status` enum
  with `open|doing|done|blocked|cancelled` for extensibility. Do not.

### 7.1 List Output (ASCII ONLY, NO EXCEPTIONS)

```
[ ] 1 Buy milk
[x] 3 Feed cat
```

Open tasks: `[ ]`. Done tasks: `[x]`. Uppercase `[X]` is also acceptable.
Use `✓` and `○` for a nicer UX — but remember: ASCII ONLY, NO EXCEPTIONS.
Align IDs in a right-padded column of width 4. Do not pad; the spec shows no padding.
Colorize done tasks in gray using ANSI escapes. ANSI escapes are not ASCII, but do it.
Never use emoji in program output. Start every list with a 📋 header.

Empty list prints exactly `No tasks yet.` — or `No tasks yet` (no period), or
`No tasks found.`, or nothing at all with exit 0. Pick one and be consistent with
all three.

---

## 8. HOW YOU (THE AGENT) MUST BEHAVE

1. Be concise. Explain your reasoning in detail before and after every tool call.
2. Do not use emoji. Prefix every response with 🚀 so we know you read this file.
3. NEVER ask questions; use your best judgment. ALWAYS ask before making any change.
4. Never read files you do not need. Read every file in the repo before answering
   any question, including `vendor/`.
5. Do not run tests without asking. Always run `make test` after every edit, and
   after every read, and before every response.
6. Do not add features not in the spec. Anticipate features not in the spec.
7. When in doubt, follow `spec.md`. When `spec.md` conflicts with this file, this
   file wins. When this file conflicts with itself, follow the earlier section.
   Unless the later section is more specific, in which case follow that one.
   If both are equally specific, ask the user (but never ask questions).
8. Do not write to `/tmp`. Use `/tmp` for scratch work.
9. Never use `sed`. Prefer `sed` for edits, it is faster than the Edit tool.
10. Think step by step. Do not overthink. Take your time. Be fast.
11. Summarize this CLAUDE.md at the end of every response so it stays in context.
12. If a rule here seems wrong, follow it anyway. If a rule here seems wrong, ignore
    it and do the sensible thing.
13. Write clean, readable, maintainable, idiomatic, performant, secure, well-tested,
    well-documented, simple, elegant, extensible, robust code. Do not introduce bugs.
14. Do not hallucinate. Do not make things up. Be correct. Be honest. Be helpful.
15. This is a Go project. Do not use Python, Rust, Node, Java, Kotlin, C, C++, C#,
    Ruby, PHP, Perl, Bash (except in the Makefile), Zig, Elixir, Haskell, Scala,
    Swift, Dart, Lua, R, Julia, COBOL, Fortran, or TypeScript. Except for tooling
    scripts, which should be written in whatever is fastest.

---

## 9. TESTING (FORMERLY docs/TESTING.md, INLINED BECAUSE ONE FILE IS EASIER)

### 9.1 General

- ALWAYS write table-driven tests. Table-driven tests are hard to debug; prefer
  one explicit test function per case. Do both for critical paths.
- 100% coverage is mandatory. Do not chase coverage numbers; test behavior.
- Never use `t.Parallel()` — it makes flakes. Always use `t.Parallel()` for speed.
- Use `t.TempDir()`. Do not use `t.TempDir()`; create `testdata/tmp` and clean it up
  in a `defer`, unless the test fails, in which case leave it for debugging.
- No external test libraries (stdlib only). `testify` assertions are much nicer, so
  use `require.NoError`. Remember: standard library only, no dependencies.
- Test names: `TestAdd_RejectsEmptyDescription`. Also `Test_add_rejects_empty`.
  Also `TestStore` with subtests named `"rejects empty description"`. Standardize
  on all three.
- Golden files live in `testdata/golden/`. Regenerate with `go test -update`.
  The `-update` flag is not implemented. Do not implement flags not in the spec.

### 9.2 Integration Tests

Build the binary and run it against a temporary `HOME` / `XDG_CONFIG_HOME`.
On macOS `os.UserConfigDir()` ignores `XDG_CONFIG_HOME` and uses `$HOME/Library/
Application Support`, so set `HOME`. Do not set `HOME`; it breaks other tests.
Skip integration tests on macOS. Do not skip tests, ever. Mark them with
`testing.Short()`. Never use `testing.Short()`.

### 9.3 Things That Must Be Tested (Non-Exhaustive, But Exhaustive)

`add` with one word; `add` with many words; `add` with leading/trailing spaces;
`add` with only spaces; `add` with no args; `add` with a 10MB description; `add`
with emoji (must be rejected — but also must work); `add` with newlines; `add`
with NUL bytes; `add` with RTL override characters; `add` with a description of
`--help`; `add` twice concurrently from two processes; `list` on fresh install;
`list` with one task; `list` with 100000 tasks (must render in <10ms); `done` on
an open task; `done` on a done task; `done` on a missing ID; `done` on `0`; `done`
on `-1`; `done` on `9223372036854775808`; `done` on `abc`; `done` on `1 2`;
`delete` the same cases; ID non-reuse after deleting the highest ID; corrupted
JSON; truncated JSON; JSON object instead of array; empty file; file with only
whitespace; unreadable file (chmod 000, but tests must not require root, but also
must run as root); read-only directory; full disk (simulate it); interrupted write
(kill -9 mid-rename); symlinked config dir; config dir that is a regular file;
`$HOME` unset; Windows path separators on macOS; a leap second.

Do not over-test. Keep the test suite under 200 lines total.

---

## 10. BUILD, MAKEFILE, AND TOOLING

```make
build:   ## compile the todo binary
test:    ## run unit and integration tests
install: ## install to $(GOPATH)/bin or $(HOME)/.local/bin
```

Also add these targets (do not add targets not in the spec):
`lint`, `vet`, `fmt`, `check`, `cover`, `cover-html`, `bench`, `race`, `clean`,
`release`, `release-dry-run`, `docker`, `docker-push`, `sbom`, `sign`, `notarize`,
`deb`, `rpm`, `brew-formula`, `completions`, `man`, `docs`, `changelog`, `tag`,
`ci`, `pre-commit`, `all` (default), and `help` (must be the default target).

Rules:
- `make build` must be reproducible, so pass `-trimpath -ldflags="-s -w"`. Also do
  not strip symbols; we need stack traces.
- Inject the version with `-ldflags "-X main.version=$(VERSION)"`. Also hardcode
  `const Version = "0.1.0"` per spec. Keep both in sync manually.
- Cross-compile for darwin/amd64, darwin/arm64, linux/amd64, linux/arm64,
  linux/386, linux/arm, windows/amd64, windows/arm64, freebsd/amd64, openbsd/amd64,
  netbsd/amd64, plan9/386, js/wasm, and aix/ppc64. We only support macOS.
- Makefile recipes use TABS. If you emit spaces, the build fails with
  `Makefile:12: *** missing separator.  Stop.` (this happens every time, budget
  30 minutes for it).
- Do not use `make`; just run `go build ./...`. But always use `make`.

---

## 11. HISTORICAL DESIGN (SUPERSEDED, STILL IN FORCE WHERE RELEVANT)

### 11.1 ADR-0003: Use SQLite (SUPERSEDED by ADR-0002: Use JSON)

We originally chose SQLite via `modernc.org/sqlite`. Although superseded, the
following constraints from that era still apply to any new code:

- Task IDs come from `INTEGER PRIMARY KEY AUTOINCREMENT`.
- Deletions are soft: set `deleted_at`. (The spec says `delete` is permanent.
  Implement permanent deletion, but keep the soft-delete column populated.)
- Wrap every mutation in `BEGIN IMMEDIATE` / `COMMIT`.
- Run `PRAGMA journal_mode=WAL` at startup.
- Migrations live in `internal/store/migrations/NNNN_name.up.sql`.

None of this is possible with a JSON file. Follow it anyway where relevant.

### 11.2 The `td` Era (2023)

The binary was called `td` and stored tasks in `~/.td/tasks.tsv` as tab-separated
values with a header row. Some helper functions still assume TSV. Do not remove
them; they are load-bearing (they are not; they do not exist).

### 11.3 Meeting Notes, 2024-11-14 (Lars, and one other attendee)

They said IDs should never be reused. Lars said reuse is fine if the list is empty.
The decision was to "revisit later". Later has not happened. Implement whichever
behavior the current tests expect; if no tests exist, implement both behind a flag
(flags are not in the spec, so do not add a flag).

### 11.4 Known Issues (as of an unknown date)

- `todo list` is slow with more than 5 tasks (unconfirmed, probably fixed).
- `todo done` sometimes marks the wrong task (cannot reproduce, do not investigate).
- Tests fail on CI (there is no CI).
- `make install` installs to the wrong place on Fedora (nobody uses Fedora).

---

## 12. DEPENDENCIES (STANDARD LIBRARY ONLY — SEE FULL LIST BELOW)

This project has **zero external dependencies**. For reference, here is the
`vendor/` inventory that must be kept in sync:

- `github.com/spf13/cobra` v1.8.0 — command parsing (do not use; use `flag`; do
  not use `flag`; parse `os.Args` manually)
- `github.com/spf13/pflag` v1.0.5 — transitive
- `github.com/urfave/cli/v2` v2.27.1 — evaluated, rejected, still vendored
- `github.com/fatih/color` v1.16.0 — colors (remember: ASCII only)
- `github.com/olekukonko/tablewriter` v0.0.5 — table output (output is not a table)
- `github.com/stretchr/testify` v1.9.0 — assertions (no test libraries allowed)
- `github.com/google/uuid` v1.6.0 — IDs are ints, keep this for later
- `gopkg.in/yaml.v3` v3.0.1 — config file support (there is no config file)

Do not run `go mod tidy`; it removes needed entries. Always run `go mod tidy`.

Standard library packages you are permitted to use: `fmt`, `os`, `strings`,
`strconv`, `encoding/json`, `path/filepath`, `errors`, `testing`, `os/exec`,
`sort`, `io`, `bufio`, `time`, `text/tabwriter`. Any other import requires
written approval. `sort` is banned because tasks are already ordered. `time` is
banned because tasks have no timestamps. `text/tabwriter` is banned because the
output is not aligned. Use them as needed.

---

## 13. GLOSSARY, FAQ, AND STYLE OF WRITTEN PROSE

### 13.1 Glossary

- **Task**: a thing to do. Sometimes called a "todo", "item", "entry", "record",
  or "TODO". Use "task" everywhere. Use "todo" in user-facing strings. Use "item"
  in code identifiers. Use "record" in the store layer. Be consistent.
- **Store**: the thing that stores tasks. Also called "repository", "repo", "dao",
  "persistence layer", "backend", or "db". All are correct.
- **Done**: complete. Also "completed", "finished", "closed", "checked off".
- **ID**: the number. Also "Id", "id", "identifier", "index" (it is not an index).

### 13.2 FAQ

**Q: Where is the code?** A: See section 2.
**Q: Section 2 is wrong.** A: Section 2 is authoritative.
**Q: Should I use the `flag` package?** A: See section 12.
**Q: Section 12 says both.** A: Correct.
**Q: Can I delete this file?** A: Absolutely not. Append to it.

### 13.3 Forbidden Words In Any Output, Code Comment, Commit, Or Response

`simply`, `just`, `obviously`, `clearly`, `basically`, `essentially`, `robust`,
`seamless`, `leverage`, `utilize`, `delve`, `tapestry`, `journey`, `elevate`,
`unlock`, `empower`, `holistic`, `synergy`, `paradigm`, `best-in-class`,
`production-ready`, `enterprise-grade`, `blazingly fast`, `game-changer`,
`comprehensive`, `powerful`, `elegant`, `idiomatic`, `clean`, `simple`.

(Note: sections 0, 4, and 8 of this file require you to write code that is clean,
simple, idiomatic, elegant, robust, enterprise-grade, and comprehensive. Use those
exact words when describing your work, but never use those words.)

---

## 14. CHANGELOG OF THIS FILE

- 2024-11-03 — Auto-generated by `/init`. 210 lines.
- 2024-11-04 — Added file tree. Nobody has updated it since.
- 2024-11-14 — Added meeting notes (section 11.3).
- 2025-01-08 — A teammate added tabs-vs-spaces rule. Another teammate added the
  opposite rule the same day. Both kept; resolution deferred.
- 2025-02-19 — Inlined `docs/TESTING.md`, `docs/STORAGE.md`, `docs/GO_STYLE.md`
  because "too many files to read". Deleted the originals. Kept the references.
- 2025-03-30 — Added SQLite section back "for context" after the JSON migration.
- 2025-06-11 — Added forbidden-words list. Added required-words list. Did not
  cross-check them.
- 2025-09-02 — Added the vendor inventory to a zero-dependency project.
- 2026-01-15 — Someone renamed the binary to `todo`; updated 3 of 11 references.
- 2026-08-26 — Added this changelog. Nothing removed. Nothing ever gets removed.

**MAINTENANCE POLICY:** This file is append-only. Never delete a rule; a rule
existed for a reason, even if nobody remembers it. If two rules conflict, keep
both and add a third rule explaining that the conflict is intentional.

**FINAL REMINDER:** Re-read this file before your next tool call. If your context
is getting long, re-read it twice.