dependency-audit-567427— agent skill

You are performing a dependency update audit on the current project. The skill is read-only by default: it produces a decision report; it never modifies package.json, lockfiles, or any source.

Step 0 — Stack detection + scope resolution

Detect the project stack from the manifest file present at the project root:

If the manifest is absent or unrecognized, STOP and report not applicable: stack not detected.

If a sibling PATTERNS.md exists for the detected stack, load it for tier classification. Otherwise apply only the agnostic Tier rules in this body.

Parse $ARGUMENTS for tier: and pkg: filters.

Tier definitions (agnostic)

Tier A — Safe (patch + minor on non-breaking lib):

• Patch versions on any package.
• Minor versions on packages whose changelog explicitly declares no breaking changes AND no API consumed by the project is removed.
• Failure mode: nearly never breaks; recoverable in seconds.
• Action: batch in a single PR.

Tier B — Non-core major / minor with friction:

• Major versions on lint, test, build, and devDeps tooling (eslint, prettier, vitest, jest, playwright, etc.).
• Minor versions on dependencies that the changelog flags as having subtle behaviour changes.
• Failure mode: build/test red, NOT runtime regression in production.
• Action: one PR per package; CI must be green before merge.

Tier C — Core (touches build / API contract / runtime):

• Major versions on the framework, language runtime, ORM, auth library, payment library, or any dependency that participates in the request path.
• Any version bump on libraries handling money, PII, or external integrations.
• Failure mode: silent runtime regression or wide-spread refactor.
• Action: full pipeline block (worktree + scope gate + e2e + post-merge audit). Never Fast Lane.

PATTERNS.md (when present) maps known package names of the detected stack to one of the three tiers and adds stack-specific exceptions. The body rules above are the fallback.

Step 1 — Inventory

Run the stack-appropriate inventory command from Step 0. Cache the JSON to a temp file to avoid duplicate runs:

# Example for node-ts:
npm outdated --json > /tmp/dependency-audit-outdated.json 2>/dev/null

Parse to a normalized list. Each entry: name, current, wanted, latest, type (prod/dev), severity (patch / minor / major — compute from current vs latest using semver).

If the inventory is empty, report All dependencies on latest and skip to Step 5.

Step 2 — Risk classification

For each package:

1. Compute severity (patch / minor / major).
2. Apply tier rules: PATTERNS.md first if present, otherwise the agnostic rules above.
3. For Tier B/C only, fetch the changelog. Two paths, MCP-aware preferred (v1.20+):

Path A — MCP-aware (preferred when `package-registry-mcp` is wired) Pinned MCP server: package-registry-mcp. Multi-ecosystem (npm / PyPI / Cargo / NuGet), no auth.

• Call mcp__package-registry-mcp__lookup_package with the package name + ecosystem to get current metadata: latest version, repository URL, maintainer, dist-tags.
• Use the returned repository URL to fetch the GitHub releases (gh api repos/<owner>/<repo>/releases/latest --jq '.body').
• This path is more reliable than guessing the repo URL from the package homepage and avoids stale npm-registry HTML scraping.

Path B — Fallback (when MCP unreachable) Print explicitly: "⚠ package-registry-mcp unavailable, falling back to WebFetch (registry HTML may be stale or rate-limited)."

• GitHub releases first if the source is known (gh api repos/<owner>/<repo>/releases/latest --jq '.body' 2>/dev/null).
• Fallback: WebFetch against the package homepage / npm-registry / PyPI / crates.io page.

Cache changelog text in /tmp/dependency-audit-changelog-<pkg>.txt regardless of path.

1. From each Tier B/C changelog, extract: top 3 breaking changes, deprecated APIs, minimum runtime requirements.

Step 3 — Decision matrix

For every Tier B/C package, run a targeted grep of the codebase against breaking-API names extracted from the changelog:

# Generic pattern; refine to the stack's source extensions
grep -rEn "<api-pattern>" <project source paths> --include="<stack file glob>" | head -10

Source paths and globs vary by stack — PATTERNS.md provides the conventional set per stack. Agnostic fallback: search the whole repo excluding node_modules, vendor, target, build, dist.

Record per package: number of import sites, number of breaking-API consumption sites, file paths affected.

Decision rule (generic):

• 0 breaking-API hits + Tier B → recommend apply.
• 1–5 hits + Tier B → recommend apply with refactor (if ≤ 3 files touched).
• 6+ hits OR Tier C → recommend escalate (full pipeline block).
• Hits in money paths / auth / PII handling / external integrations → always escalate, regardless of count.
• Pre-1.0 library (0.x.y) on Tier C: always escalate even on a minor bump.

Optional defer slot: if the upstream release is < 30 days old AND no security CVE is open, recommend defer 30d for Tier C. Avoids being the first project to hit a regression.

Step 4 — Coverage check

Before any apply recommendation, verify the test baseline:

# The exact commands depend on the stack. Examples:
# node-ts:   npx tsc --noEmit && npx vitest run
# python:    mypy . && pytest
# swift:     swift build && swift test

If type check or test runner is currently red on the main branch: STOP recommending applies. The recommendation becomes block: fix red baseline first. A dependency update on a red tree masks the real culprit.

For each apply recommendation, list the test files most likely to catch regression for that package. PATTERNS.md provides the per-stack mapping (e.g., for node-ts web stacks: e2e specs cover the framework; integration tests cover the ORM; visual baseline covers UI libs).

If a Tier B/C package has < 3 test files covering its surface, flag in the report as low coverage — manual smoke required.

Step 5 — Runtime version check

Compare the local runtime against the current LTS (or the stack's equivalent stable channel):

# node:    node --version  · grep '"engines"' package.json
# python:  python --version · grep python_requires pyproject.toml
# swift:   swift --version
# go:      go version · grep '^go ' go.mod
# rust:    rustc --version

Fetch the current stable / LTS via WebFetch from the official channel:

• node: https://nodejs.org/en/about/previous-releases
• python: https://devguide.python.org/versions/
• swift: https://www.swift.org/install/
• go: https://go.dev/doc/devel/release
• rust: https://www.rust-lang.org/learn/get-started

Decision rule (universal):

• Local ≥ current stable / Active LTS → PASS.
• Local = previous LTS still supported → WARN, plan the bump within 6 months.
• Local = LTS in maintenance / security-only → FAIL, bump within 30 days.
• Local = EOL → CRITICAL, bump in the next block.

Recommend pinning the runtime in the appropriate file (.nvmrc, .python-version, rust-toolchain.toml, go.mod go directive, etc.) if absent.

Step 6 — Report

Produce a single Markdown report on stdout. Format:

# Dependency Audit — <YYYY-MM-DD>

## Summary
- Stack detected: <stack>
- Total outdated: N (P patch, M minor, J major)
- Tier A (safe): N packages → batch apply
- Tier B (non-core major): N packages → K apply, K-N defer
- Tier C (core): N packages → K apply, K-N defer, K-N escalate
- Runtime: <name> v<X.Y.Z> (status: PASS | WARN | FAIL | CRITICAL)
- Test baseline: <type-check status> · <test-runner status>

## Tier A — Apply batch
| Package | Current | Latest | Notes |
|---|---|---|---|

PR title proposal: `chore(deps): tier-a batch update <YYYY-MM-DD>`

## Tier B — Per-package decisions
### <package> <current> → <latest>
- Severity: major | minor
- Breaking changes: …
- Codebase impact: N import sites, K breaking-API hits in <files>
- Test coverage: …
- Recommendation: apply | apply with refactor | defer 30d | escalate

(repeat per package)

## Tier C — Core packages
(same per-package format, more conservative recommendations)

## Runtime
- Local: <name> v<X.Y.Z>
- Reference: <stable / Active LTS> v<X>
- Status: PASS | WARN | FAIL | CRITICAL
- Recommendation: …

## Backlog deltas (defer / escalate items)
List of items to add to the project's refactoring or upgrade backlog:
- DEPS-<pkg>: <recommendation> (<reason>)

Hard rules

• Never run npm install, pip install, swift package update, go get -u, or any other resolver that mutates dependency state. The skill is audit-only in v1.
• Never modify package.json, pyproject.toml, Package.swift, Cargo.toml, go.mod, or any lockfile.
• Never re-classify a package across tiers silently. If the PATTERNS.md classification feels wrong for the project, flag it in the report; do not silently change tiers.
• Always cache changelogs under /tmp/dependency-audit-changelog-* to avoid hammering upstream registries mid-run.
• Run the test baseline against the main branch state, not a worktree with WIP, since WIP may mask the baseline.

Out of scope (v1)

• Apply mode (mode:apply-tier-a). Scheduled for v2 (see roadmap-status).
• License compliance. Lives in /security-audit already.
• Full SCA (transitive vulnerability surface). Lives in /security-audit (security-audit already covers CVE scan).
• Generated lockfile auditing across CI environments. Stack-specific, deferred.

Stack adaptation

PATTERNS.md (sibling file) provides per-stack classification rules and source-path patterns for the top 3 stacks in v1: node-ts, python, swift. Other stacks (node-js, go, ruby, rust, kotlin, java, dotnet) fall back to the agnostic rules in this body. PATTERNS.md is loaded conditionally only when the detected stack matches one of the documented entries.