audit-coverage-check

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; a downstream deployment may register additional route roots), 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)