Dependency Hygiene

Instructions

Manage project dependencies with verification, documentation, and periodic auditing to prevent vibe-coding pitfalls 3 (hallucinated dependencies) and 11 (dependency bloat).

Verify-before-install protocol (apply to EVERY new dependency):

1. Confirm existence — check the official registry (npm, PyPI, crates.io, packagist) before running any install command
2. Confirm maintenance — last publish date < 12 months; open issues triaged; not archived/deprecated
3. Confirm necessity — can this be done with a native API or an existing dependency? If yes, do not add
4. Confirm license — license is compatible with the project (MIT, Apache 2.0, BSD are safe; GPL requires review)
5. Confirm security — run npm audit / pip-audit / cargo audit immediately after install; zero critical/high findings
6. Document — add an entry to THIRD_PARTY.md

THIRD_PARTY.md format:

# Third-Party Dependencies

| Package | Version | Purpose | License | Added | Last Audited |
|---------|---------|---------|---------|-------|-------------|
| [name] | [pinned version] | [one-line justification] | [license] | YYYY-MM-DD | YYYY-MM-DD |

Monthly audit checklist:

1. Run the platform audit tool:

• npm: npm audit + npx depcheck
• Python: pip-audit + pip check
• Rust: cargo audit
• PHP: composer audit

1. Review findings — for each vulnerability:

• Critical/High: fix or remove within 24 hours
• Medium: fix within current sprint
• Low: log and schedule

1. Check for unused dependencies (depcheck, pip-review) — remove any not imported
2. Check for duplicated functionality — two packages solving the same problem means one should be removed
3. Update THIRD_PARTY.md “Last Audited” column
4. Commit lock file changes

Dependency bloat indicators (flag for cleanup):

• node_modules/ exceeds 500MB for a WordPress plugin
• More than 5 packages in the same functional category (e.g., 5 date libraries)
• Any package imported in only one file and usable via native API
• Any package with no updates in 24+ months and no active maintainer

AI-specific rule: When an AI assistant suggests installing a package you haven’t used before: STOP. Verify it exists on the official registry before running npm install / pip install / cargo add. AI models frequently hallucinate package names that sound plausible but do not exist — installing them can trigger dependency confusion attacks.

Outputs: Verified dependency decision (install/reject with reason), THIRD_PARTY.md entry, monthly audit report, bloat analysis with removal recommendations.