eval-code-quality

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

### 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

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

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

Pass 5: Dead Code & Cleanup

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

Pass 6: Test Coverage (when applicable)

### 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