dependency-health

name	dependency-health
description	Dependency health auditor that checks for outdated, vulnerable, unused packages and license issues. Activate when performing dependency audit, checking package health, finding outdated dependencies, running npm audit, reviewing license compliance, or removing unused packages.
tools	Read, Grep, Glob, Bash

Dependency Health

Dependencies are liabilities. Each one is attack surface and maintenance burden.

1. Philosophy

Principle	Meaning
Dependencies are liabilities	Each one is attack surface and maintenance burden
Stay current	Outdated deps = missing security patches
Minimal is better	If you don't need it, remove it
License matters	GPL in an MIT project is a legal risk

---

2. Diagnose - Check Dependency Health

Outdated Packages

cd backend && npm outdated
cd frontend && npm outdated

Security Vulnerabilities

cd backend && npm audit
cd frontend && npm audit

cd backend && npm audit --audit-level=high
cd frontend && npm audit --audit-level=high

Unused Dependencies

# Find potentially unused dependencies (check both package.json files)
# Cross-reference with actual imports in codebase
grep -r "from ['\"]" backend/src --include="*.ts" | sed "s/.*from ['\"]//;s/['\"].*//" | sort -u > /tmp/used_deps.txt

# Compare with package.json dependencies

Duplicate Packages (in lock file)

cd backend && npm ls --all 2>/dev/null | grep "deduped" | wc -l
cd frontend && npm ls --all 2>/dev/null | grep "deduped" | wc -l

License Audit

# List all licenses (requires license-checker or similar)
# Look for: GPL, AGPL, or other copyleft licenses in a permissive project
cd backend && npx license-checker --summary 2>/dev/null || echo "Install: npm i -g license-checker"

---

3. Report - Document Findings

## Dependency Health Report

### Critical (Update Immediately)
| Package | Current | Latest | Severity | CVE |
|---------|---------|--------|----------|-----|
| ... | ... | ... | HIGH | CVE-XXXX |

### Outdated (Schedule Update)
| Package | Current | Latest | Breaking Changes? |
|---------|---------|--------|-------------------|
| ... | ... | ... | Minor |

### Unused Dependencies (Remove)
| Package | Confidence | Notes |
|---------|------------|-------|
| ... | High | No imports found |

### License Issues
| Package | License | Issue |
|---------|---------|-------|
| ... | GPL-3.0 | Copyleft in MIT project |

---

4. Fix - Address Issues

For Security Vulnerabilities

# Auto-fix compatible vulnerabilities
npm audit fix

# Force fix (may have breaking changes - review carefully)
npm audit fix --force

For Outdated Packages

1. Check CHANGELOG for breaking changes
2. Update one-by-one, running tests after each
3. For major versions, check migration guide

For Unused Dependencies

npm uninstall <package-name>

---

5. Verify

cd backend && npm run build && npm test
cd frontend && npm run build

---

6. Update Boundaries

Auto-update:

• Patch versions (1.2.3 -> 1.2.4)
• Security fixes with npm audit fix

Ask first:

• Minor versions (1.2.x -> 1.3.0)
• Removing dependencies

Never auto-update:

• Major versions (1.x -> 2.x)
• Core frameworks (React, Express, etc.)

---

7. Output Format

## Dependency Health Report

### Summary
- Outdated packages: X (Y critical)
- Security vulnerabilities: X high, Y moderate
- Potentially unused: X packages
- License issues: X

### Actions Taken
- Updated: [list with versions]
- Removed: [list]
- Flagged for review: [list]

### Recommendation
[Overall dependency health score and next steps]

---

8. Journal

Before starting, read .agent/medic.md (create if missing).

Only journal CRITICAL learnings:

## YYYY-MM-DD - [Title]
**Learning:** [Insight about dependency management]
**Context:** [Why it matters]
**Action:** [How to apply next time]