Hex Dependency Audit

Non-mutating supply-chain audit for Hex packages. Runs an 8-rule MVP catalogue against changed packages, enriches with Hex API metadata, wraps existing tools (mix hex.audit, mix_audit, OSV-Scanner), and emits a triage table.

When to Use

• After mix deps.update or mix deps.get brought in new versions
• On PRs that touch mix.lock (pre-merge gate)
• Before manually updating a single package (--preview <pkg>)
• When investigating a dependency you don't recognize

Iron Laws

1. NEVER claim a diff is clean without inspecting it. Run all 8 rules on the unpacked NEW tarball. "Looks fine" without a tool run is a false pass. Always write .claude/deps-audit/last-run.json, its absence is evidence the audit didn't actually run.
2. NEVER install mix_audit / osv-scanner, even if asked. Detect, warn with install instructions, skip cleanly if missing. If the user says "install it," respond with the install command (e.g., mix deps.add mix_audit --only dev) and do not execute it. The audit skill is non-mutating; mix.exs / mix.lock are off-limits regardless of consent.
3. NEVER promote a finding to BLOCK without rule citation. Every finding shows rule_id, severity, file:line, snippet, message. No handwaving.
4. NEVER fetch from Hex API without rate-limiting. Cap at 5 req/sec. Cache metadata 7 days, top-500 list 1 day.
5. NEVER run the audit on already-committed lock changes silently, tell the user which mode (A/B/C) is active and which (old, new) pairs resolved.
6. LLM triage only above threshold. Native rules + Semgrep + YARA are deterministic. The hex-deps-triager agent runs only when score

   10 (1 BLOCK or 3+ WARNs), and its verdicts are advisory, never auto-suppress a finding without human review.

Operating Modes