Dep Check — Dependency Health Enforcement

Hook coverage check (run first): Before invoking dep_audit.sh, check whether the hook already ran the vulnerability scan for the current manifest in this session:

cat "$COVERAGE_FILE" 2>/dev/null   # COVERAGE_FILE = /tmp/codex-hook-coverage-<PROJECT_HASH>.jsonl

If the coverage file contains one or more records where "rule" is "DEP-1" and "file" matches the current manifest being reviewed, the DEP-1 vulnerability scan has already run this session. Skip straight to DEP-2 through DEP-5 analysis. Log: "Skipping DEP-1 vulnerability scan — already reported by hook this session."

If no matching DEP-1 coverage record exists, proceed with the full scan below.

For automated vulnerability scanning: invoke scripts/dep_audit.sh and parse its JSON output before performing manual checks. Requires Python 3.12+ (used by the internal normalizer).

Precedence in the overall system: SEC → TDD → ARCH/TYPE → DEP-1 (BLOCK) → DEP-2 through DEP-5.

---

Rules

DEP-1 — No Known Vulnerabilities in Production Dependencies

Severity: BLOCK | Languages: * | Source: CCC

What it prohibits: Shipping code that depends (directly or transitively) on a package with a published CVE or known security advisory at HIGH or CRITICAL severity.

Detection:

1. Run: scripts/dep_audit.sh
2. Parse JSON output — vulnerabilities array
3. Each entry: { "package": "...", "vulnerable_range": "...", "patched": "...", "cve": "...", "severity": "..." } Note: vulnerable_range is the affected semver range (e.g. <2.0.1). The installed version is not available from npm/yarn/pnpm audit JSON; omit the installed version from DEP-1 citations.
4. Flag all HIGH and CRITICAL severity findings

agent_action:

1. Cite: DEP-1 (BLOCK): Known vulnerability in '{package}' (affected range: {vulnerable_range}) — {cve} ({severity}). Patched in v{patched}.
2. STOP work that adds new features until addressed
3. Steps: a. Upgrade to the patched version: {upgrade_command} b. Run test suite to verify no breaking changes c. If breaking changes exist: document the migration path; do not downgrade
4. If no patched version exists: flag as DEP-1 (BLOCK): No patched version available — evaluate mitigation or replacement
5. MODERATE vulnerabilities: report as WARN (not BLOCK) unless the vulnerability is on an attack surface directly reachable from user input

Bypass prohibition: "We'll fix it next sprint", "it's a transitive dependency" → Refuse. Cite DEP-1. Transitive vulnerability is still a vulnerability.

---

DEP-2 — Dependencies Must Not Lag More Than 2 Major Versions Behind

Severity: WARN | Languages: * | Source: CCC

What it prohibits: Dependencies that are 2 or more major versions behind the current stable release. Major version lag accumulates breaking changes and unmaintained APIs, making future upgrades exponentially harder.

Threshold: Current stable major version − installed major version ≥ 2

Examples:

• react@16.x when react@18.x is current: lag = 2 → WARN
• django@2.x when django@4.x is current: lag = 2 → WARN
• express@3.x when express@4.x is current: lag = 1 → OK (INFO at most)

Detection:

1. Parse the manifest file (package.json, pyproject.toml, go.mod, Cargo.toml)
2. For each production dependency, fetch the current stable major version
3. Compare to the installed version
4. Flag where lag ≥ 2 major versions

agent_action:

1. Cite: DEP-2 (WARN): '{package}' is {current_major} — current stable is {latest_major} ({lag} major versions behind).
2. List breaking changes between installed and current (link to changelog if available)
3. Propose: create a migration ticket; prioritise upgrade before the gap widens
4. Do NOT auto-upgrade major versions with --fix — major upgrades require human review

---

DEP-3 — No Unused Dependencies

Severity: WARN | Languages: typescript, javascript, python | Source: CCC

What it prohibits: Packages listed in the manifest that are not imported anywhere in the project's source files. Unused dependencies inflate install size, widen attack surface, and mislead future developers.

Go note: Go's module system and go mod tidy handle this natively. DEP-3 does not apply to Go — use go mod tidy instead. Rust note: Cargo does not auto-detect unused crates. Use cargo machete or cargo udeps. DEP-3 applies.

Detection:

1. Parse declared dependencies from the manifest
2. For each package: grep all source files for an import/require of the package name
3. Flag packages with zero import references

agent_action:

1. Cite: DEP-3 (WARN): '{package}' is declared but never imported.
2. Confirm: is this a CLI tool, script runner, or type-only package (e.g., @types/*) that doesn't need an explicit import?
   • If yes: no action (type packages, eslint plugins, babel presets, etc.)
   • If no: remove from manifest
3. If --fix: remove the unused package entry (requires confirmation for ambiguous cases)

---

DEP-4 — devDependencies Must Not Bleed into Production

Severity: WARN | Languages: typescript, javascript, python | Source: CCC

What it prohibits: Packages that are only used in tests, build tooling, or linting being declared as production dependencies (not devDependencies / dev extras / optional dependencies). This bloats production images and deployment artifacts.

Applies to:

• package.json: test frameworks (jest, vitest, mocha), linters (eslint, prettier), type checkers, build tools (webpack, esbuild, vite) in dependencies instead of devDependencies
• pyproject.toml / setup.cfg: pytest, black, mypy, ruff in dependencies instead of [dev] or [tool.poetry.group.dev]

Detection:

1. Parse dependencies (production) section of the manifest
2. Identify packages whose names match known dev-only tool patterns:
   • Test: jest, vitest, mocha, pytest, hypothesis, unittest
   • Lint: eslint, prettier, ruff, mypy, black, pylint
   • Build: webpack, vite, esbuild, babel, tsc (standalone)
   • Types: @types/* packages
3. Flag each match

agent_action:

1. Cite: DEP-4 (WARN): '{package}' is a dev-only tool listed in production dependencies.
2. Propose: move to devDependencies / dev extras
3. If --fix: move the entry in the manifest (no version change)

---

DEP-5 — Production Dependencies Should Be Pinned

Severity: INFO | Languages: typescript, javascript, python | Source: CCC

What it monitors: Production dependencies (in dependencies, not devDependencies) declared with loose version ranges (^, ~, *, >=) rather than exact pinned versions. Loose ranges can pull in breaking patch releases or subtle behaviour changes between environments.

Recommended practice:

• Use exact pinning + a dedicated dependency update tool (Dependabot, Renovate) that creates PRs for version bumps. This gives you control without falling behind.
• Lock files (package-lock.json, yarn.lock, poetry.lock, Cargo.lock) provide runtime pinning, but manifest pins make intent explicit.

Detection:

1. Parse production dependency versions in the manifest
2. Flag versions using ^, ~, *, or bare range specifiers

agent_action:

1. Report: DEP-5 (INFO): '{package}' uses loose version range '{range}'. Consider pinning for reproducible builds.
2. Suggest: use Dependabot or Renovate to automate safe version bumps
3. Do NOT auto-pin without user instruction — pinning is a team policy decision
4. Never block on this metric alone; it is informational

---

Report schema: see skills/conductor/shared-contracts.md.