ln-643-api-contract-auditor

name	ln-643-api-contract-auditor
description	API contract audit worker (L3). Checks layer leakage in method signatures, missing DTOs, entity leakage to API, inconsistent error contracts, redundant method overloads. Returns findings with penalty-based scoring + diagnostic sub-scores.
allowed-tools	Read, Grep, Glob, Bash

Paths: File paths (shared/, references/, ../ln-*) are relative to skills repo root. If not found at CWD, locate this SKILL.md directory and go up one level for repo root.

API Contract Auditor (L3 Worker)

Specialized worker auditing API contracts, method signatures at service boundaries, and DTO usage patterns.

Purpose & Scope

• Worker in ln-640 coordinator pipeline - invoked by ln-640-pattern-evolution-auditor
• Audit API contracts at architecture level (service boundaries, layer separation)
• Check layer leakage, DTO patterns, error contract consistency
• Return structured analysis with 4 scores (compliance, completeness, quality, implementation)

Out of Scope (owned by ln-623-code-principles-auditor):

• Code duplication (same DTO shape repeated, same mapping logic, same validation)
• Report only ARCHITECTURE BOUNDARY findings (wrong layer, missing contract)

Input (from ln-640 coordinator)

- pattern: "API Contracts"     # Pattern name
- locations: string[]          # Service/API directories
- adr_reference: string        # Path to related ADR
- bestPractices: object        # Best practices from MCP Ref/Context7
- output_dir: string           # e.g., "docs/project/.audit/ln-640/{YYYY-MM-DD}"

# Domain-aware (optional, from coordinator)
- domain_mode: "global" | "domain-aware"   # Default: "global"
- current_domain: string                   # e.g., "users", "billing" (only if domain-aware)
- scan_path: string                        # e.g., "src/users/" (only if domain-aware)

Workflow

Phase 0: Load References

MANDATORY READ: Load references/detection_patterns.md — language-specific Grep patterns for all 5 rules.

Phase 1: Discover Service Boundaries

scan_root = scan_path IF domain_mode == "domain-aware" ELSE codebase_root

1. Find API layer: Glob("**/api/**/*.py", "**/routes/**/*.ts", "**/controllers/**/*.ts", root=scan_root)
2. Find service layer: Glob("**/services/**/*.py", "**/services/**/*.ts", root=scan_root)
3. Find domain layer: Glob("**/domain/**/*.py", "**/models/**/*.py", root=scan_root)
4. Map: which services are called by which API endpoints

Phase 2: Analyze Contracts (5 Rules)

MANDATORY READ: Use detection_patterns.md for language-specific Grep patterns per rule.

#	Rule	Severity	What to Check
1	Layer Leakage	HIGH/MEDIUM	Service/domain accepts HTTP types (Request, parsed_body, headers)
2	Missing DTO	MEDIUM/LOW	4+ params repeated in 2+ methods without grouping DTO
3	Entity Leakage	HIGH/MEDIUM	ORM entity returned from API without response DTO
4	Error Contracts	MEDIUM/LOW	Mixed error patterns (raise + return None) in same service
5	Redundant Overloads	LOW/MEDIUM	Method pairs with _with_/_and_ suffix differing by 1-2 params
6	Architectural Honesty	HIGH/MEDIUM	Read-named function (get_/find_/check_/validate_/is_/has_) body contains write side-effects. Exclusions per shared/references/ai_ready_architecture.md

Scope boundary: SKIP DUPLICATION findings (owned by ln-623), REPORT only ARCHITECTURE BOUNDARY findings.

Phase 3: Calculate 4 Scores

Compliance Score (0-100):

Criterion	Points
No layer leakage (HTTP types in service)	+35
Consistent error handling pattern	+25
Follows project naming conventions	+10
No hidden side-effects in read-named functions	+10
No entity leakage to API	+20

Completeness Score (0-100):

Criterion	Points
All service methods have typed params	+30
All service methods have typed returns	+30
DTOs defined for complex data	+20
Error types documented/typed	+20

Quality Score (0-100):

Criterion	Points
No boolean flag params in service methods	+15
No opaque return types hiding write actions	+10
No methods with >5 params without DTO	+25
Consistent naming across module	+25
No redundant overloads	+25

Implementation Score (0-100):

Criterion	Points
DTOs/schemas exist and are used	+30
Type annotations present	+25
Validation at boundaries (Pydantic, Zod)	+25
API response DTOs separate from domain	+20

Phase 3.5: Calculate Score

MANDATORY READ: Load shared/references/audit_scoring.md for unified scoring formula.

Primary score uses penalty formula (same as all workers):

penalty = (critical × 2.0) + (high × 1.0) + (medium × 0.5) + (low × 0.2)
score = max(0, 10 - penalty)

Diagnostic sub-scores (0-100 each) are calculated separately and reported in AUDIT-META for diagnostic purposes only.

Phase 4: Write Report

MANDATORY READ: Load shared/templates/audit_worker_report_template.md for file format (ln-640 section: extended AUDIT-META + DATA-EXTENDED).

# Build markdown report in memory with:
# - AUDIT-META (extended: score [penalty-based] + diagnostic score_compliance/completeness/quality/implementation)
# - Checks table (layer_leakage, missing_dto, entity_leakage, error_contracts, redundant_overloads)
# - Findings table (issues sorted by severity)
# - DATA-EXTENDED: issues array with principle + domain fields (for cross-domain aggregation)

IF domain_mode == "domain-aware":
  Write to {output_dir}/643-api-contract-{current_domain}.md
ELSE:
  Write to {output_dir}/643-api-contract.md

Phase 5: Return Summary

Report written: docs/project/.audit/ln-640/{YYYY-MM-DD}/643-api-contract-users.md
Score: 6.75/10 (C:65 K:70 Q:55 I:80) | Issues: 4 (H:2 M:1 L:1)

Critical Rules

• Architecture-level only: Focus on service boundaries, not internal implementation
• Read before score: Never score without reading actual service code
• Scope boundary: SKIP duplication findings (owned by ln-623)
• Detection patterns: Use language-specific Grep from detection_patterns.md
• Domain-aware: When domain_mode="domain-aware", scan only scan_path, tag findings with domain

Definition of Done

• Service boundaries discovered (API, service, domain layers)
• Method signatures extracted and analyzed
• All 5 rules checked using detection_patterns.md
• Scope boundary applied (no duplication with ln-623)
• 4 scores calculated with justification
• Issues identified with severity, location, suggestion, effort
• If domain-aware: findings tagged with domain field
• Report written to {output_dir}/643-api-contract[-{domain}].md (atomic single Write call)
• Summary returned to coordinator

Reference Files

• Worker report template: shared/templates/audit_worker_report_template.md
• Detection patterns: references/detection_patterns.md
• Scoring rules: ../ln-640-pattern-evolution-auditor/references/scoring_rules.md
• Pattern library: ../ln-640-pattern-evolution-auditor/references/pattern_library.md

---

Version: 2.0.0 Last Updated: 2026-02-08