dependency-compatibility-policy

Dependency Compatibility Policy

Purpose

Use current, compatible, secure, and maintainable technology choices without blindly chasing latest. Treat dependencies as supply chain risk that requires discipline.

Selection Rules

• Prefer latest compatible stable versions, not unverified latest versions.
• Check official docs, release notes, migration guides, compatibility matrices, and project constraints before changing technology or dependencies.
• Use rldyour-explore (tech-research + web-research) for technical research when compatibility or current best practice matters.
• Respect lockfiles and package manager conventions. Do not manually edit generated lockfile content unless that is the project-standard workflow.
• SemVer is a signal, not proof. Verify breaking changes against actual public API and runtime behavior.
• Major upgrades require an explicit migration plan, affected-scope analysis, and rollback or fix-forward strategy.
• New production dependencies must have a clear purpose, maintenance signal, license acceptability, security posture, and integration plan.
• Do not add dependencies to avoid writing small project-specific code unless the dependency materially reduces risk or complexity.

May 2026 Supply Chain Standards

• SBOM (Software Bill of Materials): attach SPDX or CycloneDX SBOM to every release artifact. Operational, not experimental.
• SLSA Level 2 is the minimum for new repositories: verifiable build provenance via GitHub Actions + cosign / slsa-github-generator. Achievable in one day.
• Sigstore / cosign for signing release artifacts. Verify upstream signatures when consuming critical dependencies.
• OWASP Top 10 2025 - A03 Software Supply Chain Failures is a top-tier concern (jumped to #3). Top threats: dependency confusion, upstream infrastructure compromise, code signing cert theft, CI/CD exploitation, typosquatting.
• Lockfile discipline: --frozen-lockfile / --immutable / npm ci in CI to enforce exact version matching.

Package Manager Defaults (May 2026)

• JavaScript/TypeScript: pnpm is the recommended default for new projects (faster, better disk usage, ecosystem support).
• Python: uv (Astral) for environments and dependency resolution; pip-tools or uv for lockfiles.
• Rust: cargo with Cargo.lock committed for binaries, optional for libraries.
• Go: go mod tidy, go.sum committed.
• Dart/Flutter: pubspec.lock committed for application projects.

Compatibility Checks

Check compatibility across runtime version, framework version, language version, build tool/bundler, type system + generated types, peer dependencies, plugin ecosystem, deployment environment, and security scanners.

Rejection Criteria

Reject or ask before using a dependency when:

• It is abandoned or poorly maintained (no commits in 12+ months without explanation).
• It duplicates a stable project utility.
• It requires broad architecture changes unrelated to the task.
• It hides critical behavior behind magic that is hard to debug.
• Its license or security posture is unclear.

Read ${CLAUDE_PLUGIN_ROOT}/references/dependency-policy.md for detailed dependency selection and upgrade rules.

Anti-patterns

• Использовать latest без verification compatibility (chasing unverified versions).
• Manually edit generated lockfile content (corrupts integrity).
• Mix unrelated dependency upgrades с feature work - separate commit/PR.
• Add dependency для exact 5 строк project-specific code когда self-write проще.
• Skip SLSA Level 2 / SBOM для new releases в 2026.
• Adopt prerelease/canary/0.x в production без explicit project acceptance.