Code Quality Checker

Code Quality Checker

Analyzes Done implementation tasks with quantitative Code Quality Score based on metrics, MCP Ref validation, and issue penalties.

Purpose & Scope

• Load Story and Done implementation tasks (exclude test tasks)
• Calculate Code Quality Score using metrics and issue penalties
• MCP Ref validation: Verify optimality, best practices, and performance via external sources
• Check for DRY/​KISS/​YAGNI violations, architecture boundary breaks, security issues
• Produce quantitative verdict with structured issue list; never edits Linear or kanban

Code Metrics

Code Quality Score

Formula: Code Quality Score = 100 - metric_penalties - issue_penalties

Issue penalties by severity:

Score interpretation:

Issue Prefixes

PERF- subcategories:

MNT- subcategories:

When to Use

• Invoked by ln-500-story-quality-gate Pass 1 (first gate)
• All implementation tasks in Story status = Done
• Before regression testing (ln-503) and test planning (ln-510)

Workflow (concise)

1. Load Story (full) and Done implementation tasks (full descriptions) via Linear; skip tasks with label "tests".
2. Collect affected files from tasks (Affected Components/​Existing Code Impact) and recent commits/​diffs if noted.
3. Calculate code metrics:
   • Cyclomatic Complexity per function (target ≤10)
   • Function size (target ≤50 lines)
   • File size (target ≤500 lines)
   • Nesting depth (target ≤3)
   • Parameter count (target ≤4)

3.5) MCP Ref Validation (MANDATORY for code changes):

Level 1 — OPTIMALITY (OPT-):

• Extract goal from task (e.g., "user authentication", "caching", "API rate limiting")
• Research alternatives: ref_search_documentation("{goal} approaches comparison {tech_stack} 2026")
• Compare chosen approach vs alternatives for project context
• Flag suboptimal choices as OPT- issues

Level 2 — BEST PRACTICES (BP-):

• Research: ref_search_documentation("{chosen_approach} best practices {tech_stack} 2026")
• For libraries: query-docs(library_id, "best practices implementation patterns")
• Flag deviations from recommended patterns as BP- issues

Level 3 — PERFORMANCE (PERF-):

• PERF-ALG: Analyze algorithm complexity (detect O(n²)+, research optimal via MCP Ref)
• PERF-CFG: Check library configs (connection pooling, batch sizes, timeouts) via query-docs
• PERF-PTN: Research pattern pitfalls: ref_search_documentation("{pattern} performance bottlenecks")
• PERF-DB: Check for N+1, missing indexes via query-docs(orm_library_id, "query optimization")

Triggers for MCP Ref validation:

• New dependency added (package.json/​requirements.txt changed)
• New pattern/​library used
• API/​database changes
• Loops/​recursion in critical paths
• ORM queries added

1. Analyze code for static issues (assign prefixes):

   • SEC-: hardcoded creds, unvalidated input, SQL injection, race conditions
   • MNT-: DRY violations (MNT-DRY: duplicate logic), dead code (MNT-DC: per shared/​references/​clean_code_checklist.md — 4 categories: unreachable, unused, commented-out, backward-compat), complex conditionals, poor naming
   • ARCH-: layer violations, circular dependencies, guide non-compliance

2. Calculate Code Quality Score:

   • Start with 100
   • Subtract metric penalties (see Code Metrics table)
   • Subtract issue penalties (see Issue penalties table)

3. Output verdict with score and structured issues. Add Linear comment with findings.

4. Agent Review (Delegated to ln-502): Invoke Skill(skill="ln-502-agent-reviewer", args="{storyId}").

   • ln-502 loads Story/​Done Tasks from Linear, materializes content to .agent-review/ files, runs agents, cleans up.
   • Merge returned suggestions into issues list (same prefixes: SEC-, PERF-, MNT-, ARCH-, BP-, OPT-).
   • If verdict = SUGGESTIONS with area=security or area=correctness → escalate PASS → CONCERNS.
   • If verdict = SKIPPED → Self-Review fallback (native Claude reviews code).
   • Display: agent stats from ln-502 output.

Critical Rules

• Read guides mentioned in Story/​Tasks before judging compliance.
• MCP Ref validation: For ANY architectural change, MUST verify via ref_search_documentation before judging.
• Context7 for libraries: When reviewing library usage, query-docs to verify correct patterns.
• Language preservation in comments (EN/​RU).
• Do not create tasks or change statuses; caller decides next actions.

Definition of Done

• Story and Done implementation tasks loaded (test tasks excluded).
• Code metrics calculated (Cyclomatic Complexity, function/​file sizes).
• MCP Ref validation completed:
  • OPT-: Optimality checked (is chosen approach the best for the goal?)
  • BP-: Best practices verified (correct implementation of chosen approach?)
  • PERF-: Performance analyzed (algorithms, configs, patterns, DB)
• Issues identified with prefixes and severity, sources from MCP Ref/​Context7.
• Code Quality Score calculated.
• Agent review: ln-502 invoked; suggestions merged into issues (or SKIPPED/​Self-Review fallback).
• Output format:

  verdict: PASS | CONCERNS | ISSUES_FOUND
  code_quality_score: {0-100}
  metrics:
    avg_cyclomatic_complexity: {value}
    functions_over_50_lines: {count}
    files_over_500_lines: {count}
  issues:
    # OPTIMALITY
    - id: "OPT-001"
      severity: medium
      file: "src/​auth/​index.ts"
      goal: "User session management"
      finding: "Suboptimal approach for session management"
      chosen: "Custom JWT with localStorage"
      recommended: "httpOnly cookies + refresh token rotation"
      reason: "httpOnly cookies prevent XSS token theft"
      source: "ref://owasp-session-management"
  
    # BEST PRACTICES
    - id: "BP-001"
      severity: medium
      file: "src/​api/​routes.ts"
      finding: "POST for idempotent operation"
      best_practice: "Use PUT for idempotent updates (RFC 7231)"
      source: "ref://api-design-guide#idempotency"
  
    # PERFORMANCE - Algorithm
    - id: "PERF-ALG-001"
      severity: high
      file: "src/​utils/​search.ts:42"
      finding: "Nested loops cause O(n²) complexity"
      current: "O(n²) - nested filter().find()"
      optimal: "O(n) - use Map/​Set for lookup"
      source: "ref://javascript-performance#data-structures"
  
    # PERFORMANCE - Config
    - id: "PERF-CFG-001"
      severity: medium
      file: "src/​db/​connection.ts"
      finding: "Missing connection pool config"
      current_config: "default (pool: undefined)"
      recommended: "pool: { min: 2, max: 10 }"
      source: "context7://pg#connection-pooling"
  
    # PERFORMANCE - Database
    - id: "PERF-DB-001"
      severity: high
      file: "src/​repositories/​user.ts:89"
      finding: "N+1 query pattern detected"
      issue: "users.map(u => u.posts) triggers N queries"
      solution: "Use eager loading: include: { posts: true }"
      source: "context7://prisma#eager-loading"
  
    # MAINTAINABILITY - Dead Code
    - id: "MNT-DC-001"
      severity: medium
      file: "src/​auth/​legacy-adapter.ts"
      finding: "Backward-compatibility wrapper kept after migration"
      dead_code: "legacyLogin() wraps newLogin() — callers already migrated"
      action: "Delete legacy-adapter.ts, remove re-export from index.ts"
  
    # MAINTAINABILITY - DRY
    - id: "MNT-DRY-001"
      severity: medium
      file: "src/​service.ts:42"
      finding: "DRY violation: duplicate validation logic"
      suggested_action: "Extract to shared validator"
  

• Linear comment posted with findings.

Reference Files

• Code metrics: references/​code_metrics.md (thresholds and penalties)
• Guides: docs/​guides/
• Templates for context: shared/​templates/​task_template_implementation.md
• Agent review prompt: shared/​agents/​prompt_templates/​code_review.md
• Agent review schema: shared/​agents/​schemas/​code_review_schema.json
• Clean code checklist: shared/​references/​clean_code_checklist.md
• Agent delegation: shared/​references/​agent_delegation_pattern.md

---

Version: 5.0.0 (Added 3-level MCP Ref validation: Optimality, Best Practices, Performance with PERF-ALG/​CFG/​PTN/​DB subcategories) Last Updated: 2026-01-29