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
| Metric | Threshold | Penalty |
|---|---|---|
| Cyclomatic Complexity | ≤10 OK, 11-20 warning, >20 fail | -5 (warning), -10 (fail) per function |
| Function size | ≤50 lines OK, >50 warning | -3 per function |
| File size | ≤500 lines OK, >500 warning | -5 per file |
| Nesting depth | ≤3 OK, >3 warning | -3 per instance |
| Parameter count | ≤4 OK, >4 warning | -2 per function |
Code Quality Score
Formula: Code Quality Score = 100 - metric_penalties - issue_penalties
Issue penalties by severity:
| Severity | Penalty | Examples |
|---|---|---|
| high | -20 | Security vulnerability, O(n²)+ algorithm, N+1 query |
| medium | -10 | DRY violation, suboptimal approach, missing config |
| low | -3 | Naming convention, minor code smell |
Score interpretation:
| Score | Status | Verdict |
|---|---|---|
| 90-100 | Excellent | PASS |
| 70-89 | Acceptable | CONCERNS |
| <70 | Below threshold | ISSUES_FOUND |
Issue Prefixes
| Prefix | Category | Default Severity | MCP Ref |
|---|---|---|---|
| SEC- | Security (auth, validation, secrets) | high | — |
| PERF- | Performance (algorithms, configs, bottlenecks) | medium/high | ✓ Required |
| MNT- | Maintainability (DRY, SOLID, complexity) | medium | — |
| ARCH- | Architecture (layers, boundaries, patterns) | medium | — |
| BP- | Best Practices (implementation differs from recommended) | medium | ✓ Required |
| OPT- | Optimality (better approach exists for this goal) | medium | ✓ Required |
PERF- subcategories:
| Prefix | Category | Severity |
|---|---|---|
| PERF-ALG- | Algorithm complexity (Big O) | high if O(n²)+ |
| PERF-CFG- | Package/library configuration | medium |
| PERF-PTN- | Architectural pattern performance | high |
| PERF-DB- | Database queries, indexes | high |
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-502) and test planning (ln-510)
Workflow (concise)
- Load Story (full) and Done implementation tasks (full descriptions) via Linear; skip tasks with label "tests".
- Collect affected files from tasks (Affected Components/Existing Code Impact) and recent commits/diffs if noted.
- 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
- Analyze code for static issues (assign prefixes):
- SEC-: hardcoded creds, unvalidated input, SQL injection, race conditions - MNT-: DRY violations, dead code, complex conditionals, poor naming - ARCH-: layer violations, circular dependencies, guide non-compliance
- Calculate Code Quality Score:
- Start with 100 - Subtract metric penalties (see Code Metrics table) - Subtract issue penalties (see Issue penalties table)
- Output verdict with score and structured issues. Add Linear comment with findings.
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.
- 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 - id: "MNT-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
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