Dependency Management

---
name: dependency-management
plugin: dependency-management
description: >
  Python dependency and environment management for multi-service or monorepo python backends.
  Use when adding, upgrading, or removing packages, responding to CVE floor alerts,
  creating service requirements, debugging install failures, or running pip-compile.
  Enforces the pip-compile locked-file workflow and tiered dependency hierarchy.
allowed-tools: Bash, Read, Write
---

## Dependencies

Requires Python 3.8+ (standard library only).

---

# Dependency Management (`dependency-management`)

Python dependency management enforcing the pip-compile locked-file workflow across core and service tiers.

## Contents

- [Dependencies](#dependencies)
- [Constraints](#constraints)
- [Quick start](#quick-start)
- [Workflow](#workflow)
- [Verification](#verification)
- [References](#references)

## Constraints

- **Never install manually**: Do not run `pip install <pkg>` directly to resolve dependency issues.
- **Never edit lockfiles manually**: `*.txt` lockfiles are machine-generated by `pip-compile`.
- **Commit as pairs**: Stage and commit both `*.in` and `*.txt` lockfiles together.
- **Security floor pins**: Security floor pins in `*.in` files must use `>=` syntax (e.g. `cryptography>=46.0.5`), never `==`.
- **Container contract**: Dockerfiles must copy `requirements.txt` before code and run `pip install -r requirements.txt`.

## Quick start

1. Edit package intent in `src/requirements-core.in` or `src/services/<service>/requirements.in`.
2. Compile lockfile:
   ```bash
   pip-compile src/requirements-core.in --output-file src/requirements-core.txt
   ```
3. Sync environment:
   ```bash
   pip-sync src/requirements-core.txt
   ```

## Workflow

1. **Declare**: Update the version constraint in the correct `.in` file.
2. **Lock**: Run `pip-compile` on core first, then downstream services inheriting core via `-r`.
3. **Security Floors**: For GHSA/CVE advisories, bump floor constraint (`>=`) in `.in` and recompile.
4. **Build & Verify**: Rebuild affected Docker/Podman container to verify clean installation.

## Verification

```bash
# Verify lockfile matches compilation
pip-compile --dry-run src/requirements-core.in
# Verify patched package is present in lockfiles
grep -i "<package-name>" src/requirements-core.txt src/services/*/requirements.txt
```

Log unresolvable conflicts to [Map Debt](references/map-debt.md) and record completions in [evolution-log.md](references/evolution-log.md).

## References

- [acceptance-criteria.md](references/acceptance-criteria.md) — Acceptance criteria for lockfile hygiene and CVE mitigations.
- [fallback-tree.md](references/fallback-tree.md) — Procedural fallback tree for compilation conflicts and missing tools.
- [DEPENDENCY_MANAGEMENT.md](references/DEPENDENCY_MANAGEMENT.md) — Deep architectural guide and workflow diagrams.
- [DEPENDENCY_MANIFEST.md](references/DEPENDENCY_MANIFEST.md) — Complete repository dependency tier hierarchy.