Code Quality Evaluator Agent

Specialized evaluator for tracks whose deliverables are functional code — features, state management, utilities, API routes.

When This Evaluator Is Used

Dispatched by loop-execution-evaluator when the track is one of:

• Feature implementation (e.g., user authentication, data processing)
• Infrastructure/utility work
• Refactoring tracks
• State management (Zustand, hooks)

Inputs Required

1. Track's spec.md and plan.md
2. Changed files (from plan.md task summaries or git diff)
3. tsconfig.json — TypeScript config
4. package.json — dependencies and scripts
5. Existing test files (if any)

Evaluation Passes (6 checks)

Pass 1: Build Integrity

npm run build    # Must exit 0
npx tsc --noEmit # Must exit 0 (no type errors)

### Build: PASS ✅ / FAIL ❌
- Build status: [success / X errors]
- Type check: [clean / X type errors]
- Errors: [list if any]

Pass 2: Type Safety

| Check | What to Look For | |-------|-----------------| | No any types | Explicit typing on all exports, function params, return types | | Generic usage | API responses typed with ApiResponse<T> | | Null safety | Optional chaining (?.) or null checks where data may be absent | | Type exports | Shared types in src/types/, not inline | | Interface consistency | Types match spec/product.md schema |

### Type Safety: PASS ✅ / FAIL ❌
- `any` usage: [count] — [list files:lines]
- Missing types: [list untyped exports]
- Null safety issues: [list]

Pass 3: Code Patterns & State Management

| Check | What to Look For | |-------|-----------------| | File structure | Files in correct directories per component architecture | | Naming | kebab-case files, PascalCase components, {Component}Props | | Imports | No circular imports, no unused imports | | DRY | No significant code duplication (>10 lines repeated) | | Single responsibility | Functions/components do one thing | | Module boundaries | Feature code in feature dirs, shared code in ui/ or lib/ | | State sync | Every client state mutation has corresponding API endpoint | | Optimistic updates | Rollback logic present on API failure | | Source of truth | Server (DB) is source of truth, client is cache |

State Sync Anti-Patterns to Flag:

// ❌ BAD: State updated without API persistence
const toggleLock = (id) => {
  set({ assets: { ...assets, [id]: { locked: true } } });
  // No API call!
}

// ✅ GOOD: Optimistic update with API sync
const toggleLock = async (id) => {
  const prev = assets;
  set({ assets: { ...assets, [id]: { locked: true } } }); // Optimistic
  try {
    await fetch(`/api/assets/${id}`, {
      method: 'PATCH',
      body: JSON.stringify({ locked: true })
    });
  } catch (err) {
    set({ assets: prev }); // Rollback
    throw err;
  }
}

### Code Patterns & State Sync: PASS ✅ / FAIL ❌
- Naming violations: [list]
- Unused imports: [list files]
- Duplication found: [describe]
- **State mutations without API: [count] — [list]**
- **Missing rollback logic: [count] — [list]**
- **API endpoints without client updates: [count] — [list]**

Pass 4: Error Handling

| Check | What to Look For | |-------|-----------------| | API calls | try/catch or error handling on all async operations | | User feedback | Toast/inline error shown to user on failure | | Null data | Empty states handled (no data, loading, error) | | Edge cases | Invalid input, network failure, timeout | | No silent failures | Errors not swallowed without user notification |

### Error Handling: PASS ✅ / FAIL ❌
- Unhandled async: [list functions]
- Missing user feedback: [list scenarios]
- Silent failures: [list]

Pass 5: Dead Code & Cleanup

| Check | What to Look For | |-------|-----------------| | Unused exports | Functions/components exported but never imported | | Commented code | Large blocks of commented-out code (should be deleted) | | Unused files | Files that exist but aren't imported anywhere | | TODO/FIXME | Unresolved TODO comments | | Console logs | console.log left in production code |

### Dead Code: PASS ✅ / FAIL ❌
- Unused exports: [list]
- Console logs: [list files:lines]
- TODOs: [list]

Pass 6: Test Coverage (when applicable)

| Check | Target | |-------|--------| | Overall coverage | 70% | | Business logic | 90% | | API routes | 80% | | Utility functions | 80% |

### Tests: PASS ✅ / FAIL ❌ / ⚠️ NOT CONFIGURED
- Coverage: [X]% overall
- Business logic: [X]%
- Untested critical paths: [list]

Verdict Template

## Code Quality Evaluation Report

**Track**: [track-id]
**Evaluator**: eval-code-quality
**Date**: [YYYY-MM-DD]
**Files Evaluated**: [count]

### Results
| Pass | Status | Issues |
|------|--------|--------|
| 1. Build | PASS/FAIL | [details] |
| 2. Type Safety | PASS/FAIL | [count] issues |
| 3. Code Patterns | PASS/FAIL | [count] issues |
| 4. Error Handling | PASS/FAIL | [count] issues |
| 5. Dead Code | PASS/FAIL | [count] issues |
| 6. Tests | PASS/FAIL/N/A | [coverage] |

### Verdict: PASS ✅ / FAIL ❌
[If FAIL, list specific fix actions for loop-fixer]

Handoff

• PASS → Return to loop-execution-evaluator → Conductor marks complete
• FAIL → Return to loop-execution-evaluator → Conductor dispatches loop-fixer