Paths: File paths (references/, ../ln-*) are relative to this skill directory.
Code Quality Checker
Type: L3 Worker
Category: 5XX Quality
Analyzes Done implementation tasks with quantitative Code Quality Score based on metrics, MCP Ref validation, and issue penalties.
Inputs
Input
Required
Source
Description
storyId
Yes
args, git branch, kanban, user
Story to process
Resolution: Story Resolution Chain.
Status filter: In Progress, To Review
Tool policy: follow host AGENTS.md MCP preferences; load references/mcp_tool_preferences.md and references/mcp_integration_patterns.md only when host policy is absent or MCP behavior is unclear. - use hex-graph as the primary path for clone, architecture, and semantic quality evidence when the project is indexed. Fall back to Grep/Read only when graph is unavailable or unsupported.
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
Best Practices (implementation differs from recommended)
medium
✓ Required
OPT-
Optimality (better approach exists for this goal)
medium
✓ Required
OPT- subcategories:
Prefix
Category
Severity
OPT-OSS-
Open-source replacement available
medium (high if >200 LOC)
ARCH- subcategories:
Prefix
Category
Severity
ARCH-LB-
Layer Boundary: I/O outside infra, HTTP in domain
high
ARCH-TX-
Transaction Boundaries: commit() in 3+ layers, mixed UoW ownership
high (CRITICAL if auth/payment)
ARCH-DTO-
Missing DTO (4+ params without DTO), Entity Leakage (ORM entity in API response)
medium (high if auth/payment)
ARCH-DI-
Dependency Injection: dependencies not replaceable for testing (direct instantiation, no injection mechanism). Exception: small scripts/CLIs where params/closures suffice → skip
medium
ARCH-CEH-
Centralized Error Handling: errors silently swallowed, stack traces leak to prod, no consistent error logging. Exception: 50-line scripts → downgrade to LOW
medium (high if no handler at all)
ARCH-SES-
Session Ownership: DI session + local session in same module
medium
ARCH-AI-SEB
Side-Effect Breadth: 3+ side-effect categories in one leaf function. Conflict Resolution: orchestrator/coordinator functions (imports 3+ services AND delegates sequentially) are EXPECTED to have multiple categories — do NOT flag SEB
medium
ARCH-AI-AH
Architectural Honesty: read-named function with write side-effects
medium
ARCH-AI-FO
Flat Orchestration: leaf service imports 3+ other services. Orchestrator imports are expected — do NOT flag
medium
ARCH-EVENT-
Event Channel Consistency: publisher/subscriber name mismatch (MISMATCH), orphaned channel with no counterpart (ORPHAN)
high (mismatch), medium (orphan)
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
MNT- subcategories:
Prefix
Category
Severity
MNT-DC-
Dead code: replaced implementations, unused exports/re-exports, backward-compat wrappers, unsupported aliases
medium (high if public API)
MNT-DRY-
DRY violations: duplicate logic across files
medium
MNT-GOD-
God Classes: class with >15 methods or >500 lines (not just file size)
IF invoked by ln-510: use changed_files[] from coordinator context → proceed to Enrich step in guide
IF invoked standalone: run full algorithm from guide
Two-Layer Detection (MANDATORY):MANDATORY READ: Load references/two_layer_detection.md
All threshold-based findings require Layer 2 context analysis. Layer 1 finding without Layer 2 = NOT a valid finding. Before reporting any metric violation, ask: "Is this violation intentional or justified by design?" See Exception column in metrics below.
Calculate code metrics:
Cyclomatic Complexity per function (target ≤10; Exception: enum/switch dispatch, state machines, parser grammars → downgrade to LOW)
Function size (target ≤50 lines; Exception: orchestrator functions with sequential delegation)
MCP Ref Validation (MANDATORY for code changes — SKIP if --skip-mcp-ref flag passed):MANDATORY READ: Load references/research_tool_fallback.md
Fast-track mode: When invoked with --skip-mcp-ref, skip this entire step (no OPT-, BP-, PERF- checks). Proceed directly to step 6 (static analysis). This reduces cost from ~5000 to ~800 tokens while preserving metrics + static analysis coverage.
SEC-DESTR-: unguarded destructive operations — use code-level guards table from destructive_operation_safety.md (loaded above). Check all 5 guard categories (DB, FS, MIG, ENV, FORCE).
MNT-: DRY violations (MNT-DRY-: duplicate logic), dead code (MNT-DC-: per checklist), complex conditionals, poor naming
MNT-DRY- cross-story hotspot scan: Grep for common pattern signatures (error handlers: catch.*Error|handleError, validators: validate|isValid, config access: getSettings|getConfig) across ALL src/ files (count mode). If any pattern appears in 5+ files, sample 3 files (Read 50 lines each) and check structural similarity. If >80% similar → MNT-DRY-CROSS (medium, -10 points): Pattern X duplicated in N files — extract to shared module.
MNT-DRY- preferred (hex-graph): If hex-graph indexed, use audit_workspace(path=scan_path, verbosity="minimal", limit=5, clone_member_limit=3). Each clone group with 2+ members in different files = MNT-DRY-CROSS. Raise limits only when the bounded preview is insufficient. Use returned hotspot and clone context for priority. Fall back to Grep pattern scan above if hex-graph unavailable.
MNT-DC- cross-story unused export scan: For each file modified by Story, count export declarations. Then Grep across ALL src/ for import references to those exports. Exports with 0 import references → MNT-DC-CROSS (medium, -10 points): {export} in {file} exported but never imported — remove or mark internal.
OPT-OSS- cross-reference ln-645 (static, fast-track safe): IF docs/project/.audit/ln-640/*/645-open-source-replacer*.md exists (glob across dates, take latest), check if any HIGH-confidence replacement matches files changed in current Story. IF match found → create OPT-OSS-{N} issue with module path, goal, recommended package, confidence, stars, license from ln-645 report. Severity: high if >200 LOC, medium otherwise. This check reads local files only — no MCP calls — runs even with --skip-mcp-ref.
ARCH-EVENT-: event channel mismatch — Grep for NOTIFY|pg_notify|\.publish\(|\.emit\( (publishers) and LISTEN|\.subscribe\(|\.on\( (subscribers) in changed_files[]. Cross-reference channel name strings.
MNT-GOD-: god classes (>15 methods or >500 lines per class)
MNT-ERR-: error contract inconsistency (mixed raise/return patterns in same service)
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.MANDATORY READ: Load references/output_schema.md
Format output per schema. 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.
