Dep Currency Check

dep-currency-check

A primitive skill that surfaces stale library versions and known CVEs in a project's dependencies before AI design agents propose using them. Replaces the recurring rework loop where LLM-generated code references CVE-bearing deps and only gets caught at git push.

When to use

• forge Step 1 — auto-invoke when manifests detected; feed dependency_health into shared_context so design targets current versions
• alf Step 2a — structured callable primitive; alf reads JSON instead of parsing 3 model outputs
• Pre-commit hook — POSIX .sh + Windows enterprise-hardened .ps1; defense-in-depth at commit time (advisory mode by default)
• Standalone CLI — python3 -m dep_currency_check <project-root>
• G_DEP_CURRENCY gate — opt-in via .contract/gates.yaml; the ONLY caller that passes --mode strict
• scope_delta source — critical CVEs in direct deps become artifact_kind: file entries that bob's pause cycle handles

When NOT to use

• Pure information lookup ("what does this library do?") — use web-research or python-flask-developer etc. instead
• TRIVIAL / SIMPLE single-file changes that touch no dependency declarations
• Real-time CVE monitoring — this is currency check, NOT zero-day detection
• SBOM emission, license compliance, transitive upgrade planning — separate problem spaces
• Private registry resolution — deferred to v1.1

Architecture (4-layer)

Callers (forge / alf / pre-commit / CLI / G_DEP_CURRENCY / scope_delta)
        |
        v
Orchestrator (dep_currency_check.py)
  - reads ~/.claude/state/sources.json grounding mode
  - probes which community tools are installed (once per run)
  - dispatches: try wrapper -> fall back to HTTP -> compare/report
  - exit-code contract (0/1/2/3/4)
        |
        v
+-- Layer 2A: PRIMARY data path -- community wrappers --+
|   osv_scanner, pip_audit, cargo_audit, govulncheck    |
|   (NO npm_audit -- FP rate too high )       |
+-------------------------------------------------------+
        | (fallback when wrapper unavailable)
        v
+-- Layer 2B: FALLBACK data path -- stdlib HTTP --------+
|   manifests / registry / compare / report             |
|   PyPI, npm, crates, go-proxy, RubyGems, Maven        |
|   + OSV.dev /v1/querybatch                            |
+-------------------------------------------------------+
        |
        v
External: registries + OSV.dev + (subprocess) wrappers

Boundary properties

• The CLI is the only module that reads ~/.claude/state/sources.json — air-gap policy centralized
• Layer 2A (community wrappers) is the primary path; called first per ecosystem
• Layer 2B (stdlib HTTP) is the fallback path; only fires when the corresponding wrapper unavailable
• Cache layer is shared by both 2A and 2B (split TTL: vulns 2h, versions 12-24h, deprecation 7d)
• NEVER does an LLM result feed back into a gate or scope_delta entry — LLM is interpretive enrichment only

Quickstart

# Standalone scan with markdown rendering of JSON canonical
python3 -m dep_currency_check /path/to/project --format json --render markdown

# Pre-commit hook style (advisory, fast)
python3 -m dep_currency_check "$(git rev-parse --show-toplevel)" \
  --changed-manifests "$CHANGED" --severity critical --format json --quiet

# Strict gate from G_DEP_CURRENCY
python3 -m dep_currency_check /path/to/project --mode strict --format json

# Air-gap CI
python3 -m dep_currency_check /path/to/project --offline --strict-airgap --format json

Output schema

Single canonical data contract: JSON. Schema-versioned (dep-currency.v1). All other outputs (markdown, table, yaml) are renderings over the canonical JSON with zero authority of their own.

{
  "schema_version": "dep-currency.v1",
  "generated_at": "2026-05-12T14:00:00Z",
  "project_root": "/path/to/project",
  "grounding_mode": "full",
  "manifests_scanned": ["pyproject.toml", "poetry.lock"],
  "summary": {"critical": 1, "high": 0, "deprecated": 1, "current": 47},
  "findings": [/* one per Dependency with gap, cves, blocks_build */],
  "advisories": ["osv-scanner unavailable for python; fell back to OSV.dev HTTP"],
  "osv_records": [/* embedded OSV-format vulnerability records */]
}

See references/output-schema.md for full schema + examples (including offline-cold-cache shape).

Exit codes (CLI + gate)

The pre-commit hook does NOT pass --mode strict — commit-time stays advisory. Only G_DEP_CURRENCY (opted in via .contract/gates.yaml) passes strict.

Integration

See references/integration-*.md files for caller-specific plumbing:

• references/integration-forge.md — forge Step 1 advisory auto-invoke
• references/integration-alf.md — alf Step 2a replacement
• references/integration-precommit.md — POSIX + Windows hook templates
• references/integration-gate.md — G_DEP_CURRENCY gate contract
• references/integration-scope-delta.md — S029 hook for critical-CVE-in-direct-dep
• references/air-gap-mode.md — sources.json grounding + offline behavior
• references/windows-hardening.md — .ps1 pre-commit enterprise rules

Other reference docs:

• references/ecosystem-quirks.md — per-registry edge cases
• references/http-protocol.md — exact GET URLs, response shapes, rate limits
• references/cache-design.md — split-TTL cache layout + ETag sidecar
• references/osv-integration.md — OSV.dev /v1/querybatch usage
• references/community-tools.md — when to wrap pip-audit / cargo-audit / osv-scanner / govulncheck
• references/llm-fallback.md — bounded firing rules + prompt templates
• references/output-schema.md — JSON canonical schema + rendering layer
• references/anti-patterns.md — 15+ anti-patterns

Anti-patterns (table)