audit-coverage-check - SKILL.md Agent Skill

name: audit-coverage-check description: Scan route handlers for PHI-touching routes that don't inject or call AuditService. Use when the user asks to audit the HIPAA audit-logging guardrail, says "run /audit-coverage-check", or adds new routes under /patients, /sessions, /appointments, /notes, /transcript, /audio, /soap, /resolve-client, /import-clients. tools: [Read, Bash, Glob]

Audit Coverage Check

Enforces CLAUDE.md guardrail #1: every PHI-touching route handler must inject audit: AuditService = Depends(get_audit_service) AND call audit.<helper>(...) in its body.

How to run

python .claude/skills/audit-coverage-check/check.py

Single source of truth

This skill is a thin wrapper. The actual check lives in backend/scripts/check_route_audit.py — a pure-stdlib AST script with no app/DB/network dependency — and the same implementation backs four surfaces so they can't drift:

this on-demand skill (report-shaped, run mid-edit);
the CI gate backend/tests/test_route_audit_guardrails.py (delegates to it);
the pre-commit gate scripts/check_audit_params.py (delegates to it);
the PostToolUse hook in .claude/settings.json, which runs it on every edit to a route file and feeds violations straight back to the agent.

The engine auto-detects route roots (backend/app/routes/ in the OSS engine, backend/saas/**/ in the SaaS overlay), resolves each handler's full mounted path (router prefix + decorator path), and is fail-closed: EVERY handler must either inject+call the tenant AuditService OR be explicitly classified. A route at an unrecognized path is a violation, not a silent pass. It also flags the _audit / _http_request underscore bypass. Note the tenant AuditService is required — PlatformAuditService (the PHI-free ops stream) does not satisfy the check.

PHI markers (a path matching one of these may ONLY be exempted via the reviewed AUDIT_EXEMPT_PHI_ROUTES list, never the non-PHI one): /patients, /sessions, /appointments, /notes, /transcript, /audio, /soap, /resolve-client, /import-clients.

Output

Markdown list of violations plus a fix hint. Exits 0 when the tree is clean, 1 when anything is flagged.

What it ignores

__init__.py and __pycache__
Functions not decorated with @<router>.<http_method>(...)
Routes that inject+call the tenant AuditService
Routes explicitly classified non-PHI in AUDIT_EXEMPT_NON_PHI_ROUTES, and the reviewed metadata-only PHI-marker routes in AUDIT_EXEMPT_PHI_ROUTES (both in backend/scripts/check_route_audit.py, each with a reason)