Ln 501 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

4. 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

5. Calculate Code Quality Score:

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

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

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