Part 7: Quality Automation & Git Workflow

Part of: [SOP-0.1: AI-Accelerated Workflow] (see project documentation) Sections: 22, 23, 24, 25, 26

22. AI Pitfalls & Prevention

The Duplication Problem

AI's biggest pitfall: Creating new implementations of things that already exist

Why it happens:

AI doesn't see full codebase context
Similar names in different locations
Patterns exist but aren't obvious
AI defaults to "create new" vs "find existing"

Cost:

Duplicate logic (maintenance nightmare)
Inconsistent behavior (different implementations)
Wasted effort (reimplementing existing)
Confused codebase (which one to use?)

Prevention Strategy: Audit Before Implement

Before implementing ANY feature:

Step 1: Name & Pattern Audit

# Search for similar names
grep -r "ClassName" --include="*.ts" --include="*.js"
grep -r "functionName" --include="*.ts" --include="*.js"
grep -r "interface.*Name" --include="*.ts" --include="*.js"

# Search for similar patterns
grep -r "authentication\|auth\|login" --include="*.ts"
grep -r "validation\|validate\|validator" --include="*.ts"

Ask AI:

"Before implementing [feature], search the codebase for:
- Similar class names
- Similar function names
- Similar patterns or implementations
- Existing utilities we can reuse

Show me what already exists that might solve this problem."

Step 2: Location Verification

Common mistake: Creating in wrong location

Correct locations:

src/
├── services/        ← Business logic services
├── utils/           ← Utility functions
├── components/      ← UI components
├── hooks/           ← React hooks
├── lib/             ← Third-party integrations
├── types/           ← TypeScript types
├── constants/       ← Constants and enums
└── config/          ← Configuration

Before creating:

"Where should [ClassName] be located?
Check existing structure:
- Are there similar classes?
- Which directory do they live in?
- Should this be in the same location?

Show me the correct location based on existing patterns."

Step 3: Name Duplication Check

Run name collision check:

# Check if name already exists
find . -name "*AuthService*" -type f
find . -name "*Validator*" -type f
find . -name "*Helper*" -type f

# Check class/interface names in code
grep -r "class AuthService" --include="*.ts"
grep -r "interface IAuthService" --include="*.ts"
grep -r "export.*AuthService" --include="*.ts"

Ask AI:

"Is the name 'AuthService' already used?
Search for:
- class AuthService
- interface AuthService
- type AuthService
- export { AuthService }

If it exists, show me:
- Where it's defined
- What it does
- Should I reuse it or create a different name?"

Prevention Checklist

Before implementing, verify:

Searched for similar names (grep -r "ClassName")
Searched for similar functionality (grep -r "feature")
Checked correct location (matches existing patterns)
No name collisions (unique names)
Reviewed existing implementations (can reuse?)
Asked AI to find duplicates
Confirmed with team (if uncertain)

AI Prompt Pattern for Prevention

Use this pattern BEFORE generating code:

"I need to implement [feature/class/function].

BEFORE generating code, help me avoid duplication:

1. Search Analysis:
   - Search codebase for similar names
   - Search for similar functionality
   - Find existing implementations we can reuse

2. Location Analysis:
   - Where do similar classes/functions live?
   - What's the correct location for this?
   - Show me the directory structure

3. Duplication Check:
   - Does this name already exist?
   - Are there similar implementations?
   - Can we reuse or extend existing code?

4. Recommendation:
   - Should I create new or reuse existing?
   - If new, what name avoids collisions?
   - If reuse, which existing code?

ONLY generate code after this analysis."

Example: Preventing Duplication

❌ BAD (No audit):

Person: "Create a user validation service"
AI: [Generates new UserValidationService]
# Oops! UserValidator already exists in src/validators/

✅ GOOD (With audit):

Person: "Create a user validation service.

BEFORE generating:
1. Search for existing validation code
2. Check where validators are located
3. Find similar implementations"

AI: "Found existing code:
- src/validators/UserValidator.ts (handles user validation)
- src/validators/EmailValidator.ts (similar pattern)
- src/services/ValidationService.ts (orchestrates validators)

Recommendation: Extend existing UserValidator instead of creating new service."

Person: "Good catch! Extend UserValidator with [new feature]"
AI: [Extends existing code]

Linting & Validation Tools

We use ESLint (standard JavaScript/TypeScript linter):

Configuration:

Root: .eslintrc.js (project-wide rules)
Dashboard: apps/supernal-dashboard/.eslintrc.json (app-specific)

Run linting:

# Lint all files
npm run lint

# Lint specific files
npx eslint src/services/auth.service.ts

# Auto-fix issues
npm run lint -- --fix

Pre-commit hooks run ESLint automatically:

sc git-hooks install

# Now every commit automatically:
# ✅ ESLint checks code quality
# ✅ Prettier formats code
# ✅ TypeScript checks types

Name Collision Detection

Built-in TypeScript checks:

// TypeScript catches duplicate declarations
class AuthService {}
class AuthService {} // ❌ Error: Duplicate identifier

But doesn't catch across files:

// src/services/auth.service.ts
export class AuthService {}

// src/utils/auth.service.ts
export class AuthService {} // ⚠️ No error, but confusing!

Manual check required:

# Find all AuthService exports
grep -r "export.*AuthService" --include="*.ts"

# Find all AuthService classes
grep -r "class AuthService" --include="*.ts"

Pattern Analysis Tool

Use codebase search to find patterns:

# Find all service classes
grep -r "class.*Service" --include="*.ts"

# Find all validator classes
grep -r "class.*Validator" --include="*.ts"

# Find all hook implementations
find src/hooks -name "use*.ts"

# Find all API routes
find src/app/api -name "route.ts"

Ask AI to analyze patterns:

"Analyze the codebase structure:

1. How are services organized?
   - Find all *Service classes
   - Where are they located?
   - What's the naming pattern?

2. What's the pattern for validators?
   - Find all *Validator classes
   - How are they structured?
   - What conventions are used?

3. Where should I put my new [ClassName]?
   Based on existing patterns."

Real-World Prevention Example

Scenario: Need to implement email validation

Step 1: Search:

grep -r "email.*valid" --include="*.ts" -i

# Found:
# src/utils/emailValidator.ts
# src/validators/EmailValidator.ts
# src/lib/validation/email.ts

Step 2: Analyze:

Person: "Found 3 email validation implementations:
1. src/utils/emailValidator.ts
2. src/validators/EmailValidator.ts
3. src/lib/validation/email.ts

Which should I use? Are these duplicates?"

AI: [Analyzes each file]
"Analysis:
1. utils/emailValidator.ts - Old, deprecated
2. validators/EmailValidator.ts - Current, comprehensive
3. lib/validation/email.ts - Third-party wrapper

Recommendation: Use validators/EmailValidator.ts
Deprecate utils/emailValidator.ts"

Step 3: Clean up:

# Move old implementation to deprecated
git mv src/utils/emailValidator.ts src/utils/_deprecated_emailValidator.ts

# Update all imports to use canonical validator
# [Update references]

# Document canonical location
echo "Email validation: Use src/validators/EmailValidator.ts" >> docs/reference/validators.md

Documentation: Canonical Locations

Maintain a reference doc:

# Canonical Implementations

## Validation

- Email: `src/validators/EmailValidator.ts`
- Password: `src/validators/PasswordValidator.ts`
- User: `src/validators/UserValidator.ts`

## Services

- Auth: `src/services/auth/AuthService.ts`
- User: `src/services/user/UserService.ts`
- Email: `src/services/email/EmailService.ts`

## Utilities

- String: `src/utils/string.ts`
- Date: `src/utils/date.ts`
- Format: `src/utils/format.ts`

## When adding new code:

1. Check this list first
2. If similar exists, extend it
3. If new, add to this list
4. Update this doc with location

23. Automated Testing Strategy

Testing is Core to AI-Accelerated Development

Why testing matters MORE with AI:

AI generates code quickly
Humans can't manually verify everything
Automated tests catch AI mistakes
Enables fast iteration with confidence

Three Layers of Testing

1. Pre-commit hooks    ← Local, fast, prevent bad commits
2. Pre-push hooks       ← Local, comprehensive, prevent bad pushes
3. GitHub workflows     ← External, complete, prevent bad merges

Layer 1: Pre-Commit Hooks

Install once:

sc git-hooks install

What they do:

✅ Lint code (ESLint, Prettier)
✅ Type-check (TypeScript)
✅ Run fast unit tests (< 10 seconds)
✅ Validate commit message format
✅ Check for sensitive data (secrets, keys)

When they run: Every git commit

Why they matter: Catch issues BEFORE they enter history

Example:

git add src/auth.service.ts
git commit -m "Add login"

# Pre-commit hook runs:
# ✅ ESLint passed
# ✅ TypeScript check passed
# ✅ Unit tests passed (3 tests, 0.8s)
# ✅ Commit message OK
# Commit succeeded

Layer 2: Pre-Push Hooks

What they do:

✅ Run full test suite
✅ Integration tests
✅ Build verification
✅ Security checks (npm audit)
✅ Documentation validation

When they run: Every git push

Why they matter: Comprehensive validation before sharing code

Example:

git push origin feature/auth-login

# Pre-push hook runs:
# ✅ All tests passed (127 tests, 12.3s)
# ✅ Build successful
# ✅ No security vulnerabilities
# ✅ Documentation valid
# Push succeeded

Layer 3: GitHub Workflows (CI/CD)

What they do:

✅ Run tests in clean environment
✅ Multi-platform testing (Linux, macOS, Windows)
✅ Cross-version testing (Node 18, 20, 22)
✅ End-to-end tests
✅ Deploy to staging/preview
✅ Performance benchmarks
✅ Security scanning

When they run: Every push, every PR

Why they matter: External validation, no local environment issues

Example:

# .github/workflows/test.yml
name: Test Suite
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm test
      - run: npm run build

Never Bypass Hooks (Except Emergency)

❌ BAD:

git commit --no-verify  # Skips pre-commit hooks
git push --no-verify    # Skips pre-push hooks

Why: Bypassing hooks defeats automated quality

When to bypass (rare):

Emergency hotfix (fix production outage)
Hook is broken (fix the hook first)
Metadata-only commit (documentation, no code)

If you must bypass:

# Document WHY in commit message
git commit --no-verify -m "docs: Update README

BYPASS REASON: Documentation only, no code changes"

Test-Driven with AI

Pattern:

Write test (or have AI write test from requirements)
Run test (fails, as expected)
AI generates implementation
Run test (passes)
Refactor if needed
Commit when green

Example:

// 1. Test first (AI generates from requirement)
describe('AuthService.login', () => {
  it('should return token for valid credentials', async () => {
    const token = await authService.login('user@example.com', 'password');
    expect(token).toBeDefined();
    expect(token.expiresAt).toBeGreaterThan(Date.now());
  });
});

// 2. Run test (RED)
// ❌ Test failed: login method not implemented

// 3. AI implements
// 4. Run test (GREEN)
// ✅ Test passed

// 5. Commit
git add src/auth.service.ts tests/auth.service.test.ts
git commit -m "feat: Add AuthService.login method"

24. Git Branching & Commit Strategy

Branch Naming Convention (sc git-smart)

Feature branches:

feature/req-XXX-brief-description
feature/add-user-authentication
feature/implement-oauth-login

Epic branches (multiple features):

epic/epic-name-major-feature
epic/user-management-system
epic/payment-integration

Hotfix branches (production fixes):

hotfix/critical-issue-description
hotfix/fix-auth-token-expiry
hotfix/patch-security-vulnerability

Documentation branches:

docs/update-description
docs/add-api-reference
docs/update-sop-workflow

Why naming matters: Clear intent, easy filtering, requirement traceability

One Feature Per Commit (Preferred)

Good commit:

# Single feature, complete, tested
git add src/auth.service.ts tests/auth.service.test.ts
git commit -m "feat: Add login method with JWT tokens

- Implements email/password authentication
- Returns JWT access token + refresh token
- Includes rate limiting (5 attempts per minute)
- Adds comprehensive tests

REQ-042"

Why: Atomic changes, easy revert, clear history

Multiple Features Per Branch (Same System)

When appropriate:

Features are closely related
Share same domain/system
Logically grouped together
All part of same epic/milestone

Example:

# Branch: feature/epic-auth-complete
git commit -m "feat: Add login endpoint (REQ-042)"
git commit -m "feat: Add logout endpoint (REQ-043)"
git commit -m "feat: Add token refresh (REQ-044)"
git commit -m "feat: Add password reset (REQ-045)"

Why: Easier testing, integrated deployment, related features

Commit Message Format

Structure:

<type>: <subject>

<body>

<footer>

Types:

feat: - New feature
fix: - Bug fix
refactor: - Code restructuring
docs: - Documentation only
test: - Adding/updating tests
chore: - Maintenance (dependencies, config)

Example:

git commit -m "feat: Implement OAuth 2.0 login flow

Add Google and GitHub OAuth providers with PKCE flow.
Includes state validation and CSRF protection.

Changes:
- Add OAuthService with provider abstraction
- Implement callback handler with security checks
- Add OAuth configuration management
- Include comprehensive integration tests

REQ-038, REQ-039
Closes #123"

What to Commit Together

✅ DO commit together:

Implementation + tests for same feature
Code + related documentation updates
Multiple files for same logical change
Configuration + code that depends on it

❌ DON'T commit together:

Multiple unrelated features
Work-in-progress + complete features
Experimental code + production code
Code + unrelated documentation

25. Merge Strategy with sc git-smart

Using sc git-smart merge

Safe merge with automation:

# Check branch status first
sc git-smart check-branch

# Safe merge with validation
sc git-smart merge --push --delete-local

What sc git-smart merge does:

✅ Validates branch state
✅ Updates main branch
✅ Rebases feature branch on main
✅ Runs tests
✅ Merges with --no-ff
✅ Pushes to remote (if --push)
✅ Deletes local branch (if --delete-local)
✅ Updates requirement status

Pre-Merge Checklist

Before merging:

Merge Workflow

# 1. Final testing
npm test
npm run build

# 2. Check branch readiness
sc git-smart check-branch

# 3. Safe merge
sc git-smart merge --push --delete-local

# Output:
# ✅ Branch validated
# ✅ Main branch updated
# ✅ Rebase successful
# ✅ Tests passed
# ✅ Merge completed
# ✅ Pushed to remote
# ✅ Local branch deleted
# ✅ Requirement REQ-042 updated to 'merged'

Conflict Resolution

When conflicts occur:

Pause: Don't auto-resolve
Analyze: Understand both changes
Resolve: Manual edit to preserve intent
Test: Ensure merged code works
Document: Comment on complex resolutions

Example:

# Conflict during rebase
git rebase main

# CONFLICT in src/auth.service.ts
# <<<<<<< HEAD (main)
# Old implementation
# =======
# Your implementation
# >>>>>>> feature/auth-login

# 1. Edit file to resolve
# 2. Test resolution
npm test

# 3. Continue rebase
git add src/auth.service.ts
git rebase --continue

# 4. Complete merge
sc git-smart merge --push

26. Approval Workflows (Fast-Paced Collaboration)

The Approval Challenge

Problem: Multiple approvals slow down velocity

Solution: Tiered approval strategy

Approval Tiers

Tier 1: Technical Validation (Automated)

Always required (no bypass):

✅ Tests pass
✅ Lints clean
✅ Builds successfully
✅ Security checks pass
✅ Type-checks pass

Who approves: Automated (hooks + CI)

Blocks: Cannot merge if fails

Tier 2: Code Quality (AI + Human)

Required for:

Implementation code
Business logic
API changes

Who reviews:

AI review first (pattern check, security audit)
Human spot-check (sample review, critical paths)

Pattern:

# 1. AI review
Person: "Review this implementation for issues"
AI: [Provides feedback]
Person: [Addresses issues]

# 2. Human spot-check (async)
# Merge proceeds, human reviews post-merge
# Issues found → follow-up PR

# 3. Commit
git commit -m "feat: Add feature

AI-reviewed: Security, patterns, edge cases
Human-review: Deferred to post-merge"

Why: AI catches most issues, human review async

Tier 3: Architectural Decisions (Team Approval)

Required for:

System architecture changes
Major refactors
Breaking API changes
Security-critical code
New technology adoption

Who approves: Tech lead + relevant team members

Pattern:

# Architecture Decision Record (ADR)

## Status: Proposed → Under Review → Approved

## Decision

[What we're doing]

## Rationale

[Why we're doing it]

## Alternatives Considered

[What we didn't choose and why]

## Consequences

[Trade-offs]

## Approval

- [x] Tech Lead: @username (Approved 2024-11-22)
- [x] Backend Team: @team (Approved 2024-11-22)
- [ ] Security Team: @security (Pending)

Blocks: Implementation waits for approval

Tier 4: Business/Product Decisions (Stakeholder Approval)

Required for:

User-facing features
Data model changes
Workflow changes
Compliance requirements

Who approves: Product owner + stakeholders

Pattern: Gherkin scenarios + approval

Feature: User Authentication

  Scenario: User logs in with email
    Given I am on the login page
    When I enter valid credentials
    Then I should be logged in

Status: ✅ Approved by Product (2024-11-22)
Status: ✅ Approved by Security (2024-11-22)
Status: 🔄 Implementation in progress

Fast-Track Approval (Post-Facto)

When to use:

Low-risk changes (documentation, tests)
Urgent fixes (hotfix, production issue)
Experimental features (behind feature flag)
Internal tools (not user-facing)

Process:

Implement with AI review
Pass automated checks
Merge with notification
Team reviews post-merge
Follow-up PR if issues found

Example:

# 1. AI review
# [AI feedback, implementation]

# 2. Automated checks pass
npm test  # ✅
npm run build  # ✅

# 3. Merge with notification
git commit -m "feat: Add user profile caching

Tier 2 approval: AI-reviewed, post-facto human review requested
Low risk: Behind feature flag, fully tested
Notification: @team-backend for post-merge review"

sc git-smart merge --push

# 4. Notify team
# [Slack/Email: "New feature merged, please review when available"]

# 5. Follow-up if needed
# [Team reviews, creates follow-up PR if issues]

Fast-track checklist:

AI review completed
All automated checks pass
Low risk or behind feature flag
Team notified for post-merge review
Ready to revert if issues found

Balancing Speed vs Safety

High speed, lower risk: Post-facto approval

Documentation changes
Test additions
Internal tools
Feature-flagged experiments

High safety, may be slower: Pre-merge approval

Production database migrations
Security changes
Breaking API changes
Compliance-related code

Emergency Override Process

When: Production outage, critical security fix

Process:

Fix implemented
AI review (quick check)
Automated tests (if possible)
Merge with --no-verify (if hooks block)
Immediate post-deploy verification
Team notification
Retrospective (why emergency, how to prevent)

Example:

# Production auth service down
git checkout -b hotfix/auth-token-validation
# [Implement fix]

npm test  # ✅ Tests pass

git commit -m "hotfix: Fix auth token validation causing 500s

EMERGENCY: Production outage
Bypassing: Pre-push hooks (time-critical)
AI-reviewed: Security check passed
Deployed to: Production immediately
Notification: @team, @oncall

Retrospective: Scheduled for 2024-11-23"

git push origin hotfix/auth-token-validation --no-verify

# Deploy immediately
# [Deploy process]

# Notify team
# [Incident report, retrospective scheduled]

27. Documentation & Evaluation

Documentation as Part of Quality

Documentation is not optional in AI-accelerated development:

Code generates fast → Documentation must keep pace
Multiple people/AI agents → Need shared understanding
Future maintenance → Document decisions and patterns

What to Document

Level 1: Code Comments (Inline)

When to use:

Complex algorithms
Non-obvious decisions
Security-critical sections
Performance optimizations

Example:

// Using bcrypt with cost factor 12 (security team approved 2024-11)
// Higher cost = more secure but slower login (300ms acceptable)
const hashedPassword = await bcrypt.hash(password, 12);

Don't document:

Obvious code (i++ doesn't need comment)
What code does (code should be self-documenting)
Outdated information (remove or update)

Level 2: Function/Class Documentation (JSDoc)

Always document:

Public APIs
Complex functions
Reusable utilities
Type interfaces

Pattern:

/**
 * Authenticates user with email and password
 *
 * @param email - User's email address (validated)
 * @param password - Plain text password (will be hashed)
 * @returns JWT access token + refresh token
 * @throws AuthenticationError if credentials invalid
 * @throws RateLimitError if too many attempts
 *
 * @example
 * const tokens = await authService.login('user@example.com', 'password123');
 *
 * @security Rate limited to 5 attempts per minute per IP
 * @see {@link https://docs.example.com/auth|Authentication Guide}
 */
async login(email: string, password: string): Promise<AuthTokens> {
  // Implementation
}

AI can generate: Ask AI to add JSDoc to functions

"Add comprehensive JSDoc comments to this function:
- Parameter descriptions
- Return type description
- Possible errors/exceptions
- Usage example
- Security considerations"

Level 3: Architecture Decision Records (ADRs)

When to create:

Major architectural decisions
Technology choices
Design pattern selections
Significant refactors

Template (docs/architecture/decisions/ADR-NNN-title.md):

# ADR-042: Use JWT for Authentication

## Status

Accepted (2024-11-22)

## Context

Need secure, stateless authentication for API.
Requirements:

- Stateless (no server-side sessions)
- Scalable (multiple servers)
- Short-lived tokens with refresh capability

## Decision

Implement JWT-based authentication with:

- Access tokens (15 min expiry)
- Refresh tokens (7 day expiry, stored in database)
- HMAC SHA256 signing

## Alternatives Considered

1. **Session-based auth**: Rejected (requires server state, doesn't scale)
2. **OAuth only**: Rejected (overkill for first-party auth)
3. **API keys**: Rejected (no expiry, security risk)

## Consequences

**Positive**:

- Stateless, scales horizontally
- Industry standard
- Good library support

**Negative**:

- Token revocation requires database check
- Larger payload than session ID
- Must handle token rotation

**Mitigations**:

- Short-lived access tokens
- Refresh token rotation
- Token blacklist for revocation

## Implementation

- Library: `jsonwebtoken` (npm)
- Storage: Refresh tokens in PostgreSQL
- Security: Secret rotation every 90 days

## References

- [JWT Best Practices](https://tools.ietf.org/html/rfc8725)
- [OWASP JWT Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/JSON_Web_Token_for_Java_Cheat_Sheet.html)

AI can help: Generate ADR from conversation

"Create an ADR from our conversation about authentication:
- Decision: JWT tokens
- Context: Why we need this
- Alternatives: What we considered
- Consequences: Trade-offs"

Level 4: Feature Documentation

For each feature (docs/features/\{feature\}/README.md):

# Feature: User Authentication

## Overview

Email/password and OAuth authentication system

## User Flows

1. **Login**: Email + password → JWT tokens
2. **OAuth**: Redirect → callback → JWT tokens
3. **Refresh**: Expired access token → new access token

## Technical Design

- Auth Service: Handles login logic
- Token Service: Manages JWT generation/validation
- OAuth Service: Handles OAuth providers

## API Endpoints

- `POST /api/auth/login` - Email/password login
- `POST /api/auth/logout` - Logout (blacklist token)
- `POST /api/auth/refresh` - Refresh access token
- `GET /api/auth/oauth/:provider` - OAuth redirect
- `GET /api/auth/oauth/:provider/callback` - OAuth callback

## Security

- Rate limiting: 5 attempts per minute
- Password hashing: bcrypt cost 12
- Token expiry: 15 min access, 7 day refresh

## Testing

- Unit tests: `tests/services/auth.test.ts`
- Integration tests: `tests/api/auth.test.ts`
- E2E tests: `tests/e2e/auth.spec.ts`

## Deployment

- Environment variables: `JWT_SECRET`, `JWT_REFRESH_SECRET`
- Database migrations: `migrations/042-auth-tables.sql`

Evaluation Checklist

Before marking feature complete:

Code Quality Evaluation

ESLint passes (no warnings)
TypeScript types correct (no any)
Functions < 50 lines (complexity check)
No code duplication (DRY principle)
Follows project patterns
Comments where needed

Documentation Evaluation

Testing Evaluation

Security Evaluation

User Experience Evaluation

AI-Assisted Documentation

Pattern: Generate docs as you code

[After implementing feature]

Person: "Generate documentation for this authentication feature:

1. JSDoc for all public functions
2. Update README with:
   - Feature overview
   - API endpoints
   - Security details
   - Testing info
3. Create ADR for JWT decision
4. Add usage examples"

AI: [Generates comprehensive documentation]

Person: [Reviews, refines, commits with code]

Why this works: Documentation created while context fresh

Documentation Maintenance

Keep docs current:

Update docs in same commit as code
Review docs in code review
Mark outdated docs (add WARNING)
Remove obsolete docs (archive or delete)

Red flags:

⚠️ Code changed, docs didn't
⚠️ Comments contradict code
⚠️ Examples don't work
⚠️ Links broken

28. Playwright End-to-End Testing

Why E2E Testing Matters

Unit tests verify: Individual functions work
Integration tests verify: Services work together
E2E tests verify: Users can actually use the feature

AI-generated code needs E2E tests because:

AI doesn't see full user flow
Integration bugs happen
UI/UX issues aren't caught by unit tests

Playwright Setup

Install (already in supernal-dashboard):

// package.json
{
  "devDependencies": {
    "@playwright/test": "^1.53.0"
  },
  "scripts": {
    "test:e2e": "playwright test",
    "test:e2e:ui": "playwright test --ui",
    "test:e2e:headed": "playwright test --headed",
    "test:e2e:debug": "playwright test --debug"
  }
}

Run tests:

# Run all E2E tests (headless)
npm run test:e2e

# Run with UI (interactive)
npm run test:e2e:ui

# Run in headed mode (see browser)
npm run test:e2e:headed

# Debug specific test
npm run test:e2e:debug -- auth.spec.ts

Writing E2E Tests

Location: tests/e2e/\{feature\}.spec.ts

Basic test structure:

import { test, expect } from '@playwright/test';

test.describe('User Authentication', () => {
  test('should login with valid credentials', async ({ page }) => {
    // 1. Navigate to login page
    await page.goto('http://localhost:3000/login');

    // 2. Fill in form
    await page.fill('[data-testid="email-input"]', 'user@example.com');
    await page.fill('[data-testid="password-input"]', 'password123');

    // 3. Submit
    await page.click('[data-testid="login-button"]');

    // 4. Verify redirect to dashboard
    await expect(page).toHaveURL('http://localhost:3000/dashboard');

    // 5. Verify user is logged in
    await expect(page.locator('[data-testid="user-menu"]')).toBeVisible();
    await expect(page.locator('[data-testid="user-email"]')).toHaveText(
      'user@example.com'
    );
  });

  test('should show error for invalid credentials', async ({ page }) => {
    await page.goto('http://localhost:3000/login');

    await page.fill('[data-testid="email-input"]', 'user@example.com');
    await page.fill('[data-testid="password-input"]', 'wrongpassword');
    await page.click('[data-testid="login-button"]');

    // Should stay on login page
    await expect(page).toHaveURL('http://localhost:3000/login');

    // Should show error message
    await expect(page.locator('[data-testid="error-message"]')).toBeVisible();
    await expect(page.locator('[data-testid="error-message"]')).toContainText(
      'Invalid credentials'
    );
  });

  test('should logout successfully', async ({ page }) => {
    // Login first
    await page.goto('http://localhost:3000/login');
    await page.fill('[data-testid="email-input"]', 'user@example.com');
    await page.fill('[data-testid="password-input"]', 'password123');
    await page.click('[data-testid="login-button"]');
    await expect(page).toHaveURL('http://localhost:3000/dashboard');

    // Then logout
    await page.click('[data-testid="user-menu"]');
    await page.click('[data-testid="logout-button"]');

    // Verify redirected to login
    await expect(page).toHaveURL('http://localhost:3000/login');

    // Verify cannot access dashboard
    await page.goto('http://localhost:3000/dashboard');
    await expect(page).toHaveURL('http://localhost:3000/login');
  });
});

Test Data Attributes

Use data-testid for stable selectors:

// ✅ GOOD: Stable selector
<input data-testid="email-input" type="email" />
<button data-testid="login-button">Login</button>

// ❌ BAD: Fragile selectors
<input className="form-input" /> // Class might change
<button>Login</button> // Text might change

Why: Separates test selectors from styling/behavior

AI-Generated E2E Tests

Pattern: Ask AI to generate E2E tests from requirements

Person: "Generate Playwright E2E tests for user authentication:

Feature: User can login, logout, and access protected pages

Scenarios:
1. Login with valid credentials → redirected to dashboard
2. Login with invalid credentials → error message shown
3. Logout → redirected to login, cannot access dashboard
4. Access dashboard without login → redirected to login
5. OAuth login (Google) → redirected to Google → callback → dashboard

Use data-testid selectors.
Include happy path and error cases."

AI: [Generates comprehensive E2E test suite]

Person: [Reviews, adjusts selectors, runs tests]

E2E Test Best Practices

✅ DO:

Test user flows (end-to-end journeys)
Use data-testid for selectors
Test happy path + error cases
Verify visual feedback (loading, errors, success)
Test keyboard navigation
Test mobile responsive (if applicable)

❌ DON'T:

Test implementation details (leave to unit tests)
Use fragile selectors (classes, IDs)
Make tests too long (split into multiple tests)
Ignore test failures (fix or update test)

Running E2E in CI/CD

GitHub workflow (.github/workflows/e2e.yml):

name: E2E Tests
on: [push, pull_request]

jobs:
  e2e:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Install Playwright browsers
        run: npx playwright install --with-deps

      - name: Build application
        run: npm run build

      - name: Start server
        run: npm start &

      - name: Wait for server
        run: npx wait-on http://localhost:3000

      - name: Run E2E tests
        run: npm run test:e2e

      - name: Upload test results
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: playwright-report
          path: playwright-report/

E2E Testing Strategy

Test pyramid:

        E2E Tests (few, slow)
           ↑
    Integration Tests (some, medium)
           ↑
      Unit Tests (many, fast)

E2E test priorities:

Critical user flows (authentication, checkout, data submission)
Happy paths (everything works as expected)
Common error cases (invalid input, network errors)
Edge cases (if time permits)

Example test plan:

## E2E Test Plan: Authentication Feature

### High Priority (Must Have)

- [x] Login with valid credentials
- [x] Login with invalid credentials
- [x] Logout
- [x] Access protected page without auth → redirect

### Medium Priority (Should Have)

- [x] OAuth login (Google)
- [x] Password reset flow
- [ ] Remember me checkbox
- [ ] Rate limiting (too many attempts)

### Low Priority (Nice to Have)

- [ ] Biometric authentication
- [ ] Multiple device sessions
- [ ] Session timeout

Pre-Push E2E Tests

Add to pre-push hook:

# .husky/pre-push

#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

# Run E2E tests for critical flows only (fast subset)
npm run test:e2e -- --grep "@critical"

# If E2E tests fail, prevent push
if [ $? -ne 0 ]; then
  echo "❌ Critical E2E tests failed. Fix tests before pushing."
  exit 1
fi

Mark critical tests:

test('should login with valid credentials @critical', async ({ page }) => {
  // Test implementation
});

Notify team

[Incident report, retrospective scheduled]


---

## 29. Decision Documentation & Traceability

### The Documentation Problem

**Reality**: Decisions made during implementation are often lost
- Quick chat decisions → forgotten
- AI suggestions → not recorded
- Pairing sessions → no artifacts
- "Why did we do it this way?" → no answer

**Cost**:
- Future developers confused
- Same discussions repeated
- Technical debt accumulates
- Knowledge lost when people leave

### Decision Hierarchy

#### Level 1: Architecture Decision Records (ADRs)

**When to create**:
- Major architectural decisions
- Technology stack changes
- Infrastructure patterns
- Security architecture
- Data architecture
- Breaking changes to system design

**Location**: `docs/architecture/decisions/ADR-NNN-title.md`

**Template**:
```markdown
# ADR-042: Use JWT for Authentication

## Status
Proposed | Accepted | Superseded | Deprecated

## Date
2024-11-22

## Context
Why we need to make this decision. What problem are we solving?

Requirements:
- [List specific requirements]
- [Technical constraints]
- [Business drivers]

## Decision
What we decided to do. Be specific and actionable.

Implementation:
- [Specific choices made]
- [Libraries/services selected]
- [Configuration decisions]

## Alternatives Considered

### Option 1: [Alternative name]
**Pros**:
- [Advantage 1]
- [Advantage 2]

**Cons**:
- [Disadvantage 1]
- [Disadvantage 2]

**Why rejected**: [Specific reason]

### Option 2: [Alternative name]
[Same format]

## Consequences

### Positive
- ✅ [Benefit 1]
- ✅ [Benefit 2]
- ✅ [Benefit 3]

### Negative
- ⚠️ [Trade-off 1 + mitigation]
- ⚠️ [Trade-off 2 + mitigation]

### Neutral
- ℹ️ [Impact 1]
- ℹ️ [Impact 2]

## Implementation Notes
- Library: `jsonwebtoken` v9.0.0
- Token expiry: 15 minutes (access), 7 days (refresh)
- Storage: Refresh tokens in PostgreSQL
- Rotation: Secrets rotate every 90 days

## References
- [OWASP JWT Cheat Sheet](https://...)
- [RFC 8725: JWT Best Practices](https://...)
- Related: REQ-042, SEC-003

## Participants
- @architect - Proposed
- @tech-lead - Reviewed
- @security - Approved

## Supersedes
- None

## Superseded By
- None (current)

AI can help:

Person: "Create an ADR for our JWT authentication decision.

Context:
- Need stateless authentication
- Multiple servers
- Mobile app support

Decision: JWT with refresh tokens

Alternatives considered:
- Session-based: rejected (doesn't scale)
- OAuth only: rejected (overkill)

Generate complete ADR."

AI: [Generates structured ADR]

Person: [Reviews, refines, commits]

Level 2: Design Decision Documents (DDD)

When to create:

Feature-level design decisions
Component architecture
API design
Data model design
UI/UX patterns

Location: docs/features/\{feature\}/design/DDD-\{feature\}-\{topic\}.md

Template:

# DDD: User Authentication - Token Management

## Overview

How we handle JWT token lifecycle, refresh, and revocation.

## Design Decision

Use rotating refresh tokens with blacklist for revocation.

## Components

### TokenService

```typescript
class TokenService {
  generateAccessToken(user: User): string;
  generateRefreshToken(user: User): string;
  verifyAccessToken(token: string): User;
  refreshAccessToken(refreshToken: string): TokenPair;
  revokeRefreshToken(token: string): void;
}
```

TokenStore

PostgreSQL table: refresh_tokens
Redis cache: Blacklisted tokens
TTL: 7 days (refresh), 15 min (access)

Flow Diagrams

Token Refresh Flow

[Mermaid diagram]

Token Revocation Flow

[Mermaid diagram]

Security Considerations

Refresh token rotation on every use
Blacklist for immediate revocation
Short-lived access tokens
Secure storage (httpOnly cookies)

ADR-042: JWT Authentication
REQ-042: User Login
SEC-003: Rate Limiting

Status

Approved (2024-11-22)


#### Level 3: Micro-Decision Log

**When to create**:
- Daily implementation choices
- Library selections
- Pattern applications
- Refactoring decisions
- Quick technical choices

**Location**: `docs/features/\{feature\}/planning/decisions.md`

**Template**:
```markdown
# Decision Log: User Authentication

## Overview
Running log of implementation decisions made during feature development.

---

## 2024-11-22: Use Zod for Validation

**Decision ID**: DEC-001

**Context**: Need form validation for login/signup forms

**Options Considered**:
1. **Yup** - Older, more examples online
2. **Zod** - TypeScript-first, better DX
3. **Joi** - Node-focused, less React support

**Decision**: Use Zod

**Rationale**:
- Better TypeScript integration (type inference)
- Smaller bundle size (12KB vs 18KB for Yup)
- Better error messages
- Active maintenance

**Participants**: @dev1, @dev2, AI (Claude)

**Impact**:
- All form validation uses Zod schemas
- Type safety for validation rules
- Consistent validation errors

**Status**: ✅ Implemented

**Files Affected**:
- `src/lib/validation/auth.schema.ts`
- `src/components/LoginForm.tsx`
- `src/components/SignupForm.tsx`

---

## 2024-11-22: Component Organization Pattern

**Decision ID**: DEC-002

**Context**: How to organize React components for auth feature

**Decision**: Feature-based folders, not type-based

**Structure**:

src/features/auth/ ├── components/ ← All auth components ├── hooks/ ← Auth-specific hooks ├── services/ ← Auth API calls └── types/ ← Auth types


**Rationale**:
- Easier to find related files
- Better encapsulation
- Clearer boundaries
- Matches domain model

**Participants**: @dev1, AI

**Status**: ✅ Implemented

---

## 2024-11-23: Password Hashing Strategy

**Decision ID**: DEC-003

**Context**: Need secure password storage

**Options Considered**:
1. **bcrypt** - Industry standard, proven
2. **argon2** - Newer, more secure, slower
3. **scrypt** - Good, less common

**Decision**: bcrypt with cost factor 12

**Rationale**:
- Proven security (20+ years)
- Good library support (`bcryptjs`)
- Cost factor 12 = ~300ms (acceptable UX)
- Easy to increase cost factor later

**Participants**: @dev1, @security, AI

**References**:
- OWASP Password Storage Cheat Sheet
- Security requirement SEC-005

**Status**: ✅ Implemented

**Test Coverage**:
- Unit tests: `tests/services/auth.test.ts`
- Security tests: `tests/security/password.test.ts`

---

## Template for New Decisions

**Decision ID**: DEC-XXX

**Date**: YYYY-MM-DD

**Context**: [Why we need to decide]

**Options Considered**:
1. [Option 1] - [Brief description]
2. [Option 2] - [Brief description]

**Decision**: [What we chose]

**Rationale**: [Why we chose it]

**Participants**: [Who was involved]

**Impact**: [What this affects]

**Status**: 🔄 In Progress | ✅ Implemented | ❌ Rejected

**References**: [Links to related docs]

AI can help:

Person: "Document decision: We chose Zod over Yup for validation.

Context:
- Need form validation
- Considered Yup, Zod, Joi
- Chose Zod for TypeScript integration

Add to decision log."

AI: [Adds structured entry to decisions.md]

Co-Planning Artifacts

When to create: During pairing/mob sessions, design discussions, architecture planning

Location: docs/features/\{feature\}/planning/co-planning-YYYY-MM-DD.md

Template:

# Co-Planning Session: User Authentication

## Session Info

**Date**: 2024-11-22
**Duration**: 2 hours
**Participants**: @dev1, @dev2, @architect, AI (Claude)
**Goal**: Design authentication flow and token management

## Decisions Made

### Major Decisions

1. **JWT with refresh tokens** → ADR-042
2. **Token rotation on refresh** → DDD-auth-tokens
3. **NextAuth.js for OAuth** → DEC-004

### Minor Decisions

- bcrypt cost factor 12
- Access token expiry 15 min
- Refresh token expiry 7 days
- Store refresh tokens in PostgreSQL

## What We Tried

### ❌ Passport.js

**Why tried**: Popular authentication library
**What happened**: Too many dependencies (40+ packages), complex configuration
**Time spent**: 1 hour
**Outcome**: Abandoned

### ❌ Custom OAuth Implementation

**Why tried**: Full control, no dependencies
**What happened**: Security concerns, complex state management, CSRF protection tricky
**Time spent**: 45 minutes
**Outcome**: Too risky, abandoned

### ✅ NextAuth.js

**Why tried**: Built for Next.js, handles OAuth complexity
**What happened**: Quick setup, good docs, handles edge cases
**Time spent**: 30 minutes (proof of concept)
**Outcome**: **Selected!**

## AI Contributions

### What AI Did Well

- Generated initial JWT service structure
- Suggested token rotation pattern
- Created comprehensive E2E tests
- Identified security edge cases

### What AI Struggled With

- OAuth callback flow (needed human correction)
- Token blacklist implementation (AI suggested wrong approach)
- Session management (confused with JWT approach)

### AI Prompt That Worked

"Generate a JWT token service with:

Access token generation (15 min expiry)
Refresh token generation (7 day expiry)
Token verification
Refresh token rotation
Token revocation with blacklist

Use TypeScript. Follow our existing service patterns."


## Open Questions
- [ ] How to handle token revocation for mobile apps? (Assigned: @dev1)
- [ ] Should we support magic links? (Discuss with product)
- [ ] Rate limiting strategy? (Assigned: @security)

## Next Steps
- [x] Create ADR-042 (JWT Authentication)
- [x] Create DDD for token management
- [ ] Implement TokenService
- [ ] Add OAuth routes with NextAuth.js
- [ ] Write E2E tests for full auth flow
- [ ] Security review with @security

## Resources Referenced
- [OWASP JWT Cheat Sheet](https://...)
- [NextAuth.js Docs](https://...)
- [JWT RFC 8725](https://...)
- [Our existing auth patterns] (see project documentation)

## Artifacts Created
- `ADR-042-jwt-authentication.md`
- `DDD-auth-token-management.md`
- `decisions.md` (entries DEC-001 through DEC-004)
- `src/services/TokenService.ts` (initial implementation)

## Estimated vs Actual
- **Estimated time**: 3 hours
- **Actual time**: 2 hours
- **Why faster**: NextAuth.js eliminated OAuth complexity

Traceability Convention

Every artifact should reference related artifacts:

## References

- **Requirements**: REQ-042 (User Login), REQ-043 (User Logout)
- **Design**: DDD-auth-token-management
- **Decisions**: ADR-042, DEC-001, DEC-002, DEC-003
- **Security**: SEC-003 (Rate Limiting), SEC-005 (Password Storage)
- **Tests**: `tests/e2e/auth.spec.ts`, `tests/services/auth.test.ts`
- **Code**: `src/services/AuthService.ts`, `src/services/TokenService.ts`

In code, use comments:

/**
 * Authenticates user with email/password
 *
 * @implements REQ-042 (User Login)
 * @decision ADR-042 (JWT Authentication)
 * @decision DEC-003 (bcrypt cost factor 12)
 * @security SEC-005 (Password Storage)
 * @tests tests/e2e/auth.spec.ts
 * @see docs/features/auth/design/DDD-auth-token-management.md
 */
async function login(email: string, password: string): Promise<AuthTokens> {
  // Implementation
}

Documentation Index

Create: docs/INDEX.md

# Documentation Index

**Last Updated**: 2024-11-22

## Quick Links

- [All Architecture Decisions (ADRs)](#architecture-decisions)
- [All Features](#features)
- [All Requirements](#requirements)
- [All SOPs](#sops)

---

## Architecture Decisions

### Active ADRs

- [ADR-042: JWT Authentication] (see project documentation) (Accepted 2024-11-22)
- [ADR-041: PostgreSQL for Auth Storage] (see project documentation) (Accepted 2024-11-20)

### Superseded ADRs

- [ADR-035: Session-based Auth] (see project documentation) (Superseded by ADR-042)

---

## Features

### Active Development

- [User Authentication] (see project documentation) - Status: In Progress
  - Requirements: REQ-042, REQ-043, REQ-044
  - Design: DDD-auth-tokens, ADR-042
  - Lead: @dev1

### Completed

- [User Profile] (see project documentation) - Status: Deployed
  - Deployed: 2024-11-15
  - Requirements: REQ-035, REQ-036

---

## Requirements

### By Epic

- **Authentication** (REQ-040 through REQ-049)
  - [REQ-042: User Login] (see project documentation)
  - [REQ-043: User Logout] (see project documentation)

### By Status

- **Approved**: REQ-042, REQ-043, REQ-044
- **In Progress**: REQ-045, REQ-046
- **Backlog**: REQ-047, REQ-048, REQ-049

---

## SOPs

- [SOP-0: Complete Development Workflow] (see project documentation)
- [SOP-0.1: AI-Accelerated Workflow] (see project documentation)

30. Evaluation & Retrospectives

Post-Implementation Evaluation

When: After completing and deploying a feature

Location: docs/features/\{feature\}/evaluation.md

Template:

# Post-Implementation Evaluation: User Authentication

## Metadata

**Feature**: User Authentication
**Epic**: Authentication System
**Completion Date**: 2024-11-25
**Deployment Date**: 2024-11-26
**Evaluation Date**: 2024-11-27
**Participants**: @dev1, @dev2, @architect, @product

---

## What We Built

### Scope Delivered

- ✅ Email/password login
- ✅ OAuth (Google, GitHub)
- ✅ Token refresh flow
- ✅ Password reset
- ✅ Rate limiting
- ❌ Magic links (deferred to v2)
- ❌ Biometric auth (deferred to v2)

### Technical Implementation

- **Stack**: Next.js, NextAuth.js, PostgreSQL, Redis
- **Libraries**:
  - NextAuth.js v4 (OAuth)
  - bcryptjs (password hashing)
  - jsonwebtoken (JWT)
  - Zod (validation)
- **Architecture**: JWT with rotating refresh tokens
- **Storage**: PostgreSQL (users, refresh tokens), Redis (blacklist)

### Key Decisions

- ADR-042: JWT Authentication
- DEC-001: Zod for validation
- DEC-002: Feature-based component organization
- DEC-003: bcrypt cost factor 12
- DEC-004: NextAuth.js for OAuth

---

## What Worked Well ✅

### Technical

1. **NextAuth.js eliminated OAuth complexity**
   - Would have taken 2+ weeks custom
   - Took 2 days with NextAuth.js
   - Handles edge cases automatically

2. **Token rotation pattern**
   - Secure by default
   - Easy to implement
   - Good DX

3. **Test-first approach**
   - E2E tests written before implementation
   - Caught 5 bugs before production
   - Gave confidence to deploy

4. **Zod validation**
   - Type-safe
   - Good error messages
   - Easy to maintain

### Process

1. **Co-planning sessions**
   - 2-hour upfront design session saved days
   - Documented decisions avoided rework
   - AI partnership accelerated design

2. **AI-generated tests**
   - E2E tests generated from requirements
   - 90% of tests needed minimal changes
   - Comprehensive edge case coverage

3. **Continuous deployment**
   - Feature flags allowed incremental rollout
   - No big-bang release
   - Quick rollback capability

---

## What Didn't Work ⚠️

### Technical

1. **Initial OAuth configuration confusion**
   - **Problem**: OAuth callback URLs were confusing
   - **Impact**: Lost 4 hours debugging redirect issues
   - **Root cause**: Documentation unclear, AI gave wrong advice
   - **Fix**: Created clear documentation with examples
   - **Lesson**: Prototype OAuth flow in isolation first

2. **Token refresh logic took 3 attempts**
   - **Problem**: Race conditions with concurrent requests
   - **Impact**: Intermittent token expiry errors
   - **Root cause**: Didn't consider concurrent refresh
   - **Fix**: Added mutex lock on refresh token
   - **Lesson**: Load test token refresh early

3. **Underestimated rate limiting complexity**
   - **Problem**: Redis rate limiting needed tuning
   - **Impact**: Legitimate users blocked, attackers not blocked enough
   - **Root cause**: Used default limits without analysis
   - **Fix**: Analyzed usage patterns, tuned limits
   - **Lesson**: Rate limiting requires real-world data

### Process

1. **Inadequate staging testing**
   - **Problem**: Didn't test OAuth with real providers in staging
   - **Impact**: Production bug with GitHub OAuth
   - **Root cause**: Used mocks in staging
   - **Fix**: Set up real OAuth apps for staging
   - **Lesson**: Staging should mirror production exactly

2. **Test data management**
   - **Problem**: E2E tests used production OAuth, hit rate limits
   - **Impact**: Flaky tests, wasted debugging time
   - **Root cause**: No dedicated test accounts
   - **Fix**: Created test accounts with elevated limits
   - **Lesson**: Set up test infrastructure first

---

## Metrics

### Estimation Accuracy

| Metric         | Estimated | Actual | Variance |
| -------------- | --------- | ------ | -------- |
| Story Points   | 8         | 13     | +62%     |
| Calendar Days  | 5         | 8      | +60%     |
| Developer Days | 3         | 5      | +67%     |

### Quality Metrics

| Metric                       | Target | Actual | Status                 |
| ---------------------------- | ------ | ------ | ---------------------- |
| Test Coverage                | >80%   | 87%    | ✅ Met                 |
| E2E Test Pass Rate           | 100%   | 95%    | ⚠️ Below (flaky tests) |
| Production Bugs (first week) | 0      | 1      | ⚠️ Above (OAuth bug)   |
| Deployment Success           | 100%   | 100%   | ✅ Met                 |

### Performance Metrics

| Metric              | Target | Actual | Status |
| ------------------- | ------ | ------ | ------ |
| Login Response Time | <500ms | 380ms  | ✅ Met |
| Token Refresh Time  | <200ms | 150ms  | ✅ Met |
| OAuth Redirect Time | <2s    | 1.8s   | ✅ Met |

### User Metrics (First Week)

- **Registrations**: 127 users
- **Login Success Rate**: 96% (target: >95%)
- **OAuth Usage**: 68% (higher than expected!)
- **Password Reset Requests**: 8 (normal)
- **Support Tickets**: 2 (both for OAuth confusion)

---

## Lessons Learned

### Technical Lessons

1. **Prototype OAuth in isolation before integration**
   - Would have caught redirect issues early
   - Saves debugging time in full system

2. **Token refresh needs concurrent request handling**
   - Race conditions are subtle
   - Load test refresh flow specifically

3. **Rate limiting requires real-world data to tune**
   - Default limits are rarely correct
   - Monitor and adjust after launch

4. **NextAuth.js was the right choice**
   - Eliminated weeks of OAuth implementation
   - Worth learning curve

### Process Lessons

1. **Co-planning sessions have high ROI**
   - 2 hours upfront saved days of rework
   - Document decisions immediately

2. **Set up test infrastructure first**
   - Test accounts, OAuth apps, rate limit exemptions
   - Don't block E2E tests later

3. **Feature flags enable safer rollout**
   - Incremental release reduced risk
   - Easy rollback gave confidence

4. **AI is great for tests, mixed for OAuth**
   - E2E test generation worked well
   - OAuth configuration needed human expertise

### What to Replicate

- ✅ Design sessions with decision logging
- ✅ Test-first approach
- ✅ Feature flag rollout
- ✅ AI-generated E2E tests
- ✅ Continuous staging testing

### What to Change

- 🔄 Prototype tricky integrations early (OAuth, webhooks)
- 🔄 Set up test infrastructure before development
- 🔄 Load test performance-critical flows (token refresh)
- 🔄 Use real services in staging, not mocks
- 🔄 Add buffer to estimates for integration complexity

---

## Impact on Future Work

### Reusable Components

- `TokenService` - Can be used for API keys
- `RateLimiter` - Reusable for all endpoints
- `AuthMiddleware` - Pattern for other protected routes
- E2E test patterns - Template for other features

### Technical Debt Created

1. **OAuth provider management** - Hard-coded providers, should be configurable
   - Priority: Medium
   - Effort: 2 days
   - Plan: Configuration-driven provider registry

2. **Rate limiting tuning** - Needs ongoing adjustment
   - Priority: Low
   - Effort: Ongoing
   - Plan: Monitor and adjust quarterly

3. **Test flakiness** - 5% of E2E tests are flaky
   - Priority: High
   - Effort: 1 day
   - Plan: Fix race conditions in tests

### Recommendations for Similar Features

1. Use NextAuth.js (or similar) for OAuth - don't build custom
2. Prototype complex integrations in isolation first
3. Set up test infrastructure before development starts
4. Budget 50% buffer for integration complexity
5. Load test performance-critical flows early
6. Use feature flags for incremental rollout

---

## Team Feedback

### Developer Feedback

**@dev1**: "NextAuth.js saved us weeks. Co-planning session was valuable - we made better decisions upfront rather than refactoring later."

**@dev2**: "OAuth was trickier than expected, but the test-first approach gave confidence. Wish we had set up test accounts sooner - lost time to flaky tests."

### Product Feedback

**@product**: "68% OAuth adoption exceeded expectations. Users prefer social login over email/password. Consider expanding providers (Apple, Microsoft)."

### Security Feedback

**@security**: "Token rotation and rate limiting are solid. One concern: token blacklist uses TTL in Redis - if Redis fails, revoked tokens become valid. Consider backup mechanism."

---

## Action Items

### Immediate (This Sprint)

- [ ] Fix OAuth redirect bug in production (Assigned: @dev1, Due: 2024-11-28)
- [ ] Fix flaky E2E tests (Assigned: @dev2, Due: 2024-11-29)
- [ ] Document OAuth setup for other developers (Assigned: @dev1, Due: 2024-11-30)

### Short Term (Next Sprint)

- [ ] Add backup token blacklist mechanism (Assigned: @dev2)
- [ ] Tune rate limiting based on week 1 data (Assigned: @dev1)
- [ ] Expand OAuth providers (Apple, Microsoft) (Assigned: @dev2)

### Long Term (Next Quarter)

- [ ] Make OAuth providers configurable (Technical debt)
- [ ] Add biometric authentication support
- [ ] Add magic link support

---

## Artifacts Generated

- [ADR-042: JWT Authentication] (see project documentation)
- [DDD: Token Management] (see project documentation)
- [Decision Log] (see project documentation) (4 decisions)
- [Co-Planning Notes] (see project documentation)
- [Test Plan] (see project documentation)
- [Deployment Runbook] (see project documentation)

Sprint Retrospective

When: End of every sprint (weekly for us)

Location: docs/retrospectives/YYYY-MM-DD-sprint-N.md

Template:

# Sprint Retrospective: Sprint 23 (Nov 18-25, 2024)

## Sprint Overview

**Goal**: Complete user authentication feature
**Committed**: 21 story points
**Completed**: 18 story points
**Velocity**: 86% (below target of 95%)

## What Went Well ✅

1. Authentication feature shipped on time
2. Zero production incidents
3. Good pairing/mob sessions
4. AI-generated tests saved time

## What Didn't Go Well ⚠️

1. OAuth integration took longer than estimated (+3 days)
2. Flaky tests wasted debugging time
3. Underestimated rate limiting complexity
4. One story rolled to next sprint

## Action Items

- [ ] Add 50% buffer to integration tasks (Team)
- [ ] Set up test infrastructure before development (Dev team)
- [ ] Prototype complex integrations first (Architects)
- [ ] Improve estimation accuracy for OAuth/external services (Team)

## Metrics

- Velocity: 18/21 (86%)
- Bugs: 1 (production)
- Test pass rate: 95% (target: 100%)
- Deployment success: 100%

31. Change Control & Impact Analysis

When Change Control is Required

Always require change control for:

Breaking changes to APIs, data models, interfaces
Architecture changes affecting multiple components
Security changes affecting authentication, authorization, data protection
Infrastructure changes affecting deployment, scaling, performance
Database schema changes (migrations)
Third-party integrations (new services, API changes)
Compliance-related changes (data handling, logging, auditing)

Optional for:

Internal refactoring (no external impact)
Bug fixes (small, isolated)
Documentation updates
Test additions

Change Control Process

Step 1: Change Request

Create: docs/changes/CHG-YYYY-NNN-title.md

# CHG-2024-042: Migrate from Sessions to JWT Authentication

## Change Metadata

**ID**: CHG-2024-042
**Type**: Architecture Change
**Priority**: High
**Requested By**: @architect
**Date**: 2024-11-22
**Status**: Proposed | Approved | In Progress | Completed | Rejected

---

## Change Description

### What's Changing

Migrating from session-based authentication to JWT-based authentication with refresh tokens.

**Current State**:

- Session cookies stored in Redis
- Server-side session management
- Session expiry: 24 hours
- No token refresh

**Proposed State**:

- JWT access tokens (15 min expiry)
- Refresh tokens (7 days expiry)
- Stateless authentication
- Token rotation on refresh

### Why We're Changing

**Business Drivers**:

- Support mobile apps (sessions don't work well)
- Improve scalability (stateless)
- Enable API access for third parties

**Technical Drivers**:

- Redis sessions becoming bottleneck at scale
- Need cross-origin authentication
- Want to support multiple devices

**Requirements**:

- REQ-045: Mobile app support
- REQ-046: Third-party API access
- REQ-047: Multi-device sessions

---

## Impact Analysis

### System Impact Assessment

#### Components Affected

1. **Authentication Service** - MAJOR REWRITE
   - Current: `SessionService`
   - New: `TokenService`, `AuthService`
   - Effort: 5 days
   - Risk: High

2. **API Gateway** - BREAKING CHANGE
   - Current: Session cookie middleware
   - New: JWT bearer token middleware
   - Effort: 2 days
   - Risk: Medium

3. **Frontend (Web)** - MODERATE CHANGE
   - Current: Cookie-based auth
   - New: Token storage + refresh logic
   - Effort: 3 days
   - Risk: Medium

4. **Mobile App** - NEW FEATURE
   - Current: N/A
   - New: Token-based auth flow
   - Effort: 5 days
   - Risk: Low (new, not changing existing)

5. **Database** - SCHEMA CHANGE
   - Current: `sessions` table (Redis)
   - New: `refresh_tokens` table (PostgreSQL)
   - Migration: Required
   - Effort: 1 day
   - Risk: Medium

6. **Testing** - EXTENSIVE UPDATES
   - E2E tests: All auth tests need updates
   - Integration tests: Token flow tests needed
   - Unit tests: New token service tests
   - Effort: 4 days
   - Risk: Medium

#### Interfaces/APIs Affected

- ❌ `/api/auth/login` - Response format changes (breaking)
- ❌ `/api/auth/logout` - Token revocation replaces session destroy (breaking)
- ✅ `/api/auth/refresh` - NEW endpoint
- ⚠️ All protected endpoints - Authorization header required (breaking)

#### Data Impact

- **Session Migration**: 1,245 active sessions need migration
- **User Data**: No changes to user records
- **Audit Logs**: Need to log token issuance/refresh/revocation

#### Third-Party Integration Impact

- **OAuth Providers**: No impact (callback flow same)
- **Monitoring (DataDog)**: Update to track token metrics
- **Analytics**: Update to track token usage patterns

---

### Dependency Analysis

**Blocks**:

- REQ-045: Mobile app (waiting for this change)
- REQ-046: API access (waiting for this change)

**Blocked By**:

- None (can proceed)

**Related Changes**:

- CHG-2024-040: Rate limiting (should implement together)
- CHG-2024-041: Multi-device support (enabled by this)

---

### Risk Assessment

#### High Risks

1. **Session migration complexity**
   - **Risk**: Active users logged out during migration
   - **Probability**: High
   - **Impact**: High (bad UX)
   - **Mitigation**:
     - Implement parallel auth (sessions + tokens) during transition
     - Gradual rollout with feature flag
     - Allow 7-day overlap for migration

2. **Token revocation challenges**
   - **Risk**: Revoked tokens still valid if blacklist fails
   - **Probability**: Medium
   - **Impact**: High (security)
   - **Mitigation**:
     - Short-lived access tokens (15 min)
     - Redundant blacklist (Redis + PostgreSQL)
     - Monitoring and alerts

#### Medium Risks

1. **Frontend token refresh complexity**
   - **Risk**: Race conditions, infinite refresh loops
   - **Probability**: Medium
   - **Impact**: Medium (bugs)
   - **Mitigation**:
     - Use proven library (axios interceptors)
     - Comprehensive E2E tests
     - Monitoring for refresh failures

2. **Performance impact**
   - **Risk**: JWT verification slower than session lookup
   - **Probability**: Low
   - **Impact**: Medium (latency)
   - **Mitigation**:
     - Cache JWT public keys
     - Benchmark before/after
     - Optimize token verification

#### Low Risks

1. **Documentation debt**
   - **Risk**: Outdated docs cause confusion
   - **Probability**: High
   - **Impact**: Low (annoying)
   - **Mitigation**:
     - Update all docs as part of change
     - Add migration guide

---

### Effort Estimation

| Task                     | Owner      | Effort | Dependencies        |
| ------------------------ | ---------- | ------ | ------------------- |
| Design token system      | @architect | 1 day  | None                |
| Implement TokenService   | @dev1      | 3 days | Design complete     |
| Implement refresh logic  | @dev1      | 2 days | TokenService done   |
| Update API gateway       | @dev2      | 2 days | TokenService done   |
| Frontend token storage   | @dev3      | 2 days | API gateway done    |
| Frontend refresh logic   | @dev3      | 1 day  | Token storage done  |
| Database migration       | @dev2      | 1 day  | Design complete     |
| Update E2E tests         | @qa        | 3 days | Implementation done |
| Update integration tests | @dev1      | 1 day  | Implementation done |
| Session migration script | @dev2      | 1 day  | Parallel auth done  |
| Gradual rollout          | @ops       | 2 days | All testing done    |
| Monitoring & alerts      | @ops       | 1 day  | Deployment done     |
| Documentation            | @dev1      | 1 day  | All complete        |

**Total Effort**: 21 developer-days
**Calendar Time**: 15 days (with parallel work)
**Buffer (20%)**: +3 days
**Estimated Completion**: 18 days

---

### Rollback Plan

#### Rollback Trigger Conditions

- Token generation failure rate >1%
- Token verification failure rate >5%
- Login success rate drops below 90%
- Refresh token rotation failures >10%
- Production incidents related to auth

#### Rollback Procedure

1. **Immediate (< 5 minutes)**:
   - Toggle feature flag: `USE_JWT_AUTH=false`
   - System falls back to session auth
   - All users remain authenticated (parallel auth)

2. **Short-term (< 1 hour)**:
   - Investigate root cause
   - Decide: Fix forward or rollback completely

3. **Complete rollback (if needed)**:
   - Disable JWT endpoints
   - Keep session auth only
   - Run database rollback migration (if needed)
   - Update monitoring

#### Recovery Steps

- Active sessions preserved (parallel auth)
- No data loss (sessions + tokens both stored)
- Users may need to re-login (acceptable)

---

### Testing Strategy

#### Pre-Deployment Testing

- [ ] Unit tests (TokenService, AuthService)
- [ ] Integration tests (token flow)
- [ ] E2E tests (all auth flows)
- [ ] Load tests (1000 concurrent token refreshes)
- [ ] Security tests (token tampering, expiry)
- [ ] Migration tests (session → token)

#### Staging Validation

- [ ] Deploy to staging
- [ ] Run full test suite
- [ ] Manual testing (all browsers)
- [ ] Performance benchmarks
- [ ] Security scan
- [ ] Penetration testing

#### Production Rollout

- [ ] Deploy with feature flag OFF
- [ ] Enable for 1% of users
- [ ] Monitor for 24 hours
- [ ] Increase to 10%
- [ ] Monitor for 48 hours
- [ ] Increase to 50%
- [ ] Monitor for 72 hours
- [ ] Enable for 100%
- [ ] Remove feature flag after 1 week
- [ ] Remove parallel auth after 2 weeks

---

## Approval Workflow

### Required Approvals

- [ ] **Architect** (@architect) - Architecture design
- [ ] **Tech Lead** (@tech-lead) - Technical feasibility
- [ ] **Security** (@security) - Security implications
- [ ] **Product** (@product) - User impact
- [ ] **Operations** (@ops) - Deployment strategy

### Approval Status

#### Architect Review

**Reviewer**: @architect
**Date**: 2024-11-22
**Status**: ✅ Approved
**Comments**: "Design is sound. Token rotation pattern is correct. Parallel auth strategy mitigates risk."

#### Tech Lead Review

**Reviewer**: @tech-lead
**Date**: 2024-11-23
**Status**: ✅ Approved with conditions
**Comments**: "Approve if we add comprehensive E2E tests for race conditions in token refresh. Increase buffer to 30% for integration complexity."
**Conditions**:

- [ ] Add E2E tests for concurrent refresh
- [ ] Increase buffer to 30% (+6 days)

#### Security Review

**Reviewer**: @security
**Date**: 2024-11-23
**Status**: ⏸️ Pending
**Comments**: "Need clarification on token blacklist redundancy. How does PostgreSQL backup work?"
**Questions**:

- Token blacklist backup mechanism?
- Secret rotation strategy?
- Token signing algorithm? (Must be RS256, not HS256)

---

## Decision

**Final Decision**: [Pending Security Approval]
**Approved By**: [TBD]
**Date**: [TBD]
**Conditions**: [TBD]

---

## Implementation Tracking

### Artifacts to Create/Update

- [x] ADR-042: JWT Authentication
- [ ] DDD-auth-token-management.md
- [ ] Migration guide
- [ ] API documentation
- [ ] Frontend auth guide
- [ ] Deployment runbook
- [ ] Monitoring playbook

### Code Changes

- [ ] `src/services/TokenService.ts` (new)
- [ ] `src/services/AuthService.ts` (major rewrite)
- [ ] `src/middleware/jwt-auth.ts` (new)
- [ ] `src/api/auth/refresh.ts` (new)
- [ ] Database migration scripts
- [ ] E2E test updates

### Status Updates

**2024-11-22**: Change request created
**2024-11-23**: Architect approved, Tech Lead approved with conditions
**2024-11-24**: [Next update]

Impact Analysis Tool

AI can help analyze impact:

Person: "I want to migrate from sessions to JWT authentication.

Analyze impact:
1. Which files/components affected?
2. What APIs break?
3. What's the migration path?
4. What are the risks?
5. How long will this take?

Our codebase:
[Attach relevant files or describe architecture]"

AI: [Generates comprehensive impact analysis]
"I've analyzed your codebase. Here's what I found:

**Components Affected** (8 total):
1. SessionService → Needs complete rewrite
2. AuthMiddleware → Breaking change
3. LoginForm → Moderate change
[...]

**Breaking Changes** (5 APIs):
1. POST /api/auth/login - response format changes
[...]

**Migration Path**:
1. Implement parallel auth (sessions + JWT)
2. Gradual rollout with feature flag
[...]

**Estimated Effort**: 21 developer-days

Let me create the full impact analysis document?"

Person: "Yes, create CHG-2024-042 with all details."

AI: [Generates complete change request document]

← Previous: [Part 6] (see SOP-0.1.6-validation-quality) → Next: [Summary] (see project documentation)

[Back to Overview] (see project documentation)

Getting Started

Guides

Workflow

Tools

Examples

Compliance