audit-deps

name	audit-deps
description	Audit or evaluate dependency and runtime upgrades in an existing codebase using real usage and primary sources. Use for outdated dependencies, end-of-life support, security advisories, deprecated APIs, upgrade plans, in-place modernization, or an outcome review after a completed upgrade without changing the stack or architecture.

Audit Dependencies

Route First

Choose one path before doing any other work:

• Completed upgrade: if an upgrade has just been completed or the user asks to evaluate its outcome, read and follow POST-UPGRADE-EVALUATION.md. Stop after its ## Upgrade Effect report; do not run the audit path or test a speculative next upgrade.
• Upgrade needed: otherwise, build an evidence chain from the installed version to real repository usage, official support facts, the smallest safe upgrade action, and a command that verifies it using the audit path below.

Produce either path in the user's language. If an audited upgrade is completed later in the same task, run the completed-upgrade path automatically. A completed-upgrade response is incomplete without an ## Upgrade Effect section, one defined outcome, and a line explicitly stating that performance was not measured.

Guardrails

• Keep the audit read-only. Show upgrade commands without running them or changing files unless the user separately requests implementation.
• Preserve the existing languages, frameworks, libraries, package managers, databases, and architecture.
• Target the latest stable release reachable in place. Include intermediate versions when official guidance requires staged upgrades. Use prereleases only when requested.
• Use installed, ecosystem-native read-only commands. Inspect manifests manually when tooling is unavailable; do not install audit tools.
• Support deprecation, compatibility, end-of-life, and security claims with primary sources. Mark claims that cannot be verified as Unverified.
• Mark an abandoned dependency with no in-place path as Blocked, state the decision required, and leave replacement selection to the user.
• Keep both paths benchmark-free. Report performance as unmeasured rather than inferring it from versions, release notes, or build duration.

1. Establish the Baseline

Read repository instructions, then find every project, manifest, lockfile, runtime version file, compiler or build config, container definition, and CI or deployment workflow.

For each project, record:

• language, runtime, package manager, and exact resolved versions;
• direct, development, and actionable transitive dependencies;
• frameworks and peer-coupled packages that must move together;
• runtime, operating-system, deployment, database, and compiler constraints.

Prefer lockfiles and resolved-version commands over manifest ranges. Capture the repository's initial status so the final read-only check can compare against it.

Complete this step when every detected project, manifest, lockfile, and execution environment is accounted for.

2. Trace Real Impact

Run the ecosystem's existing read-only version and advisory checks, then search source, config, scripts, tests, and CI for each candidate dependency or API.

• Distinguish direct, transitive, runtime, build-time, and test-only dependencies.
• Locate affected imports, calls, config keys, command flags, and generated-code contracts.
• Record exact file and line locations for deprecated or removed usage.
• Trace shared helpers and all callers before recommending a source change.
• Label each finding precisely:
  • Stale: a newer release exists, but the installed release remains supported.
  • Deprecated: official guidance discourages the version, API, or config but it still works.
  • Removed: the target release no longer supports observed usage.
  • End-of-life: the vendor no longer supports the installed runtime or dependency line.
  • Vulnerable: an official advisory affects the resolved version.

Complete this step when every code-change recommendation points to observed usage and every dependency-only recommendation is labeled as such.

3. Verify Primary Sources

Check official registries, release notes, migration guides, API docs, support policies, and security advisories. For every finding, verify:

• exact installed version, latest stable version, and proposed target;
• required intermediate releases and minimum runtime, compiler, package-manager, database, or operating-system versions;
• breaking changes that affect observed repository usage;
• documented replacements for deprecated APIs or config;
• affected and fixed versions for security advisories.

Link time-sensitive claims directly to the source that owns them. Prefer an explicit Unverified item over an inference presented as fact.

Complete this step when every finding has a primary source or an Unverified label.

4. Build the Upgrade Path

Group the smallest reversible batches in dependency order:

1. runtime and toolchain prerequisites;
2. core frameworks and peer-coupled packages;
3. independent direct dependencies;
4. source and configuration changes proven necessary by usage;
5. lockfile regeneration and the repository's existing checks.

For each batch, provide:

• its scope and reason;
• exact commands for the detected package manager and target versions;
• only the source or config edits required by observed usage and official guidance;
• compatibility risks and a rollback boundary;
• the existing install, format, lint, type, test, build, or smoke-test commands that prove the batch works.

Map every finding to one batch or to Blocked or Unverified.

5. Report

Use this structure and omit empty sections:

# Project Upgrade Audit

## Summary
Current state, highest risks, and recommended upgrade order.

## Findings
| Priority | Component | Current → Target | Status | Impact | Evidence |

## Deprecated or Removed Usage
| Location | Current Usage | Required Change | Target Version | Evidence |

## Upgrade Batches
1. Scope, reason, exact commands, required edits, risks, rollback point, and verification.

## Blocked or Unverified
Missing evidence, unsupported dependencies, and decisions that require the user.

Rank vulnerable dependencies, end-of-life runtimes, and removed APIs first; then blockers, deprecated usage, supported-but-stale dependencies, and optional cleanup.

Before returning the report, compare the repository's final status with the captured baseline. Confirm that every project is covered, every finding has a target and action, every command matches the existing toolchain, every factual claim has evidence or an Unverified label, and the audit changed no project files.