Ln 643 Api Contract Auditor

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"

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

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

Phase 3: Calculate 4 Scores

Compliance Score (0-100):

Completeness Score (0-100):

Quality Score (0-100):

Implementation Score (0-100):

Phase 4: Write Report

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

Phase 5: Return Summary

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)

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