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 4-score model (compliance, completeness, quality, implementation).
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.
Specialized worker auditing API contracts, method signatures at service boundaries, and DTO usage patterns.
Out of Scope (owned by ln-623-code-principles-auditor):
- 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"
# 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)
MANDATORY READ: Load references/detection_patterns.md — language-specific Grep patterns for all 5 rules.
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
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 |
Scope boundary: SKIP DUPLICATION findings (owned by ln-623), REPORT only ARCHITECTURE BOUNDARY findings.
Compliance Score (0-100):
| Criterion | Points |
|---|---|
| No layer leakage (HTTP types in service) | +35 |
| Consistent error handling pattern | +25 |
| Follows project naming conventions | +20 |
| 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 | +25 |
| 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 |
MANDATORY READ: Load shared/templates/audit_worker_report_template.md for file format (ln-640 section: 4-score AUDIT-META + DATA-EXTENDED).
# Build markdown report in memory with:
# - AUDIT-META (4-score variant: score + 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
Report written: docs/project/.audit/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)
{output_dir}/643-api-contract[-{domain}].md (atomic single Write call)shared/templates/audit_worker_report_template.mdreferences/detection_patterns.md../ln-640-pattern-evolution-auditor/references/scoring_rules.md../ln-640-pattern-evolution-auditor/references/pattern_library.mdVersion: 2.0.0 Last Updated: 2026-02-08