docs: add uv package management documentation

- Add "Package management (uv)" section to root AGENTS.md
- Update all test commands in tests/AGENTS.md to use uv run
- Update .envrc to unset VIRTUAL_ENV and show uv commands
- Add auto-sync for uv dependencies when .venv is stale

Author: CybotTM

.envrc

@@ -2,17 +2,31 @@
 
 export PROJECT_NAME="${PROJECT_NAME:-$(basename "$PWD")}"
 
+# Clear any conflicting VIRTUAL_ENV from other projects
+# This project uses uv with its own .venv/
+unset VIRTUAL_ENV
+
 echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 echo "direnv: Loaded $PROJECT_NAME"
 echo ""
+echo "Package management: uv (always use 'uv run' for Python commands)"
+echo ""
 echo "Quick start:"
-echo "  make help      - Show available targets"
-echo "  make update    - Collect tool versions (requires network)"
-echo "  make audit     - Run audit from snapshot (fast, offline)"
+echo "  uv sync --extra dev           - Install/sync dependencies"
+echo "  uv run python -m pytest       - Run all tests"
+echo "  uv run python audit.py --help - Show CLI options"
 echo ""
-echo "First time? Run: make update && make audit"
+echo "First time? Run: uv sync --extra dev"
 echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 
+# Auto-sync uv dependencies if .venv is missing or stale
+if command -v uv &> /dev/null; then
+    if [ ! -d ".venv" ] || [ "pyproject.toml" -nt ".venv" ]; then
+        echo "→ Running uv sync --extra dev..."
+        uv sync --extra dev --quiet
+    fi
+fi
+
 # Load environment files if they exist (Makefile handles this too)
 # Uncomment if you want direnv to export these variables
 # use dotenv .env.default

AGENTS.md

@@ -13,13 +13,30 @@
 - Ask before: heavy deps, full rewrites, breaking changes
 - Never commit secrets, PII, or credentials
 
+## Package management (uv)
+
+**This project uses [uv](https://docs.astral.sh/uv/) for package management.** Always use `uv run` to execute Python commands.
+
+```bash
+# Sync dependencies (run after clone or when pyproject.toml changes)
+uv sync --extra dev
+
+# Run any Python command
+uv run python -m pytest          # Run tests
+uv run python audit.py ripgrep   # Run audit script
+uv run python -m flake8          # Run linter
+```
+
+**Why uv?** Fast dependency resolution, proper lockfile support, and isolated environments without manual venv activation.
+
 ## Minimal pre-commit checks
 
 ```bash
-make lint                    # flake8 (required)
-make lint-types              # mypy (optional)
-./scripts/test_smoke.sh      # Smoke tests (required)
-make audit                   # Verify core workflows
+uv run python -m pytest          # All tests (required)
+uv run python -m flake8 cli_audit tests  # flake8 (required)
+uv run python -m mypy cli_audit  # mypy (optional)
+./scripts/test_smoke.sh          # Smoke tests (required)
+uv run python audit.py --help    # Verify CLI works
 ```
 
 ## Index of scoped AGENTS.md
@@ -32,11 +49,13 @@ make audit                   # Verify core workflows
 
 | Command | Purpose |
 |---------|---------|
+| `uv run python -m pytest` | Run all tests |
+| `uv run python -m pytest -x` | Run tests, stop on first failure |
+| `uv run python audit.py ripgrep` | Single tool audit |
+| `uv run python audit.py --help` | Show CLI options |
 | `make audit` | Render from snapshot (<100ms) |
 | `make update` | Collect fresh versions (~7s) |
 | `make upgrade` | Interactive upgrade guide |
-| `make upgrade-all` | Complete 5-stage system upgrade |
-| `python3 audit.py ripgrep` | Single tool audit |
 
 ## Project overview
 

tests/AGENTS.md

@@ -35,19 +35,19 @@ tests/
 
 **Requirements:**
 ```bash
-# Python 3.10+ with pytest
-python3 --version  # 3.10, 3.11, 3.12, 3.14 tested
+# Python 3.14+ with uv package manager
+python3 --version  # 3.14 required
+uv --version       # uv required
 
-# Install test dependencies
-pip install -e ".[dev]"
-# OR
-uv pip install -e ".[dev]"
+# Sync all dependencies (including dev)
+uv sync --extra dev
 ```
 
 **Test dependencies (from pyproject.toml):**
 - pytest — Test framework
 - pytest-cov — Coverage reporting
-- pytest-mock — Mocking utilities (if used)
+- pytest-mock — Mocking utilities
+- pytest-xdist — Parallel test execution
 
 **Test environment variables:**
 ```bash
@@ -58,33 +58,36 @@ CLI_AUDIT_TIMEOUT_SECONDS=1 # Fast timeout for tests
 
 ## Build & tests
 
-**Run all tests:**
+**Run all tests (use uv run):**
 ```bash
-# From project root
-python3 -m pytest tests/ -v
+# From project root - ALWAYS use uv run
+uv run python -m pytest
+
+# Verbose output
+uv run python -m pytest -v
 
 # With coverage
-python3 -m pytest tests/ -v --cov=cli_audit --cov-report=html
+uv run python -m pytest --cov=cli_audit --cov-report=html
 
-# Parallel execution
-python3 -m pytest tests/ -v -n auto
+# Parallel execution (fast)
+uv run python -m pytest -n auto
 ```
 
 **Run specific test files:**
 ```bash
 # Single test file
-python3 -m pytest tests/test_config.py -v
+uv run python -m pytest tests/test_config.py -v
 
 # Single test class
-python3 -m pytest tests/test_config.py::TestToolConfig -v
+uv run python -m pytest tests/test_config.py::TestToolConfig -v
 
 # Single test function
-python3 -m pytest tests/test_config.py::TestToolConfig::test_tool_config_defaults -v
+uv run python -m pytest tests/test_config.py::TestToolConfig::test_tool_config_defaults -v
 ```
 
 **Run integration tests:**
 ```bash
-python3 -m pytest tests/integration/ -v
+uv run python -m pytest tests/integration/ -v
 ```
 
 **Smoke test (quick validation):**
@@ -95,13 +98,13 @@ python3 -m pytest tests/integration/ -v
 **Filter tests by marker:**
 ```bash
 # Run only slow tests
-python3 -m pytest -m slow
+uv run python -m pytest -m slow
 
 # Skip slow tests
-python3 -m pytest -m "not slow"
+uv run python -m pytest -m "not slow"
 
 # Run only unit tests
-python3 -m pytest -m unit
+uv run python -m pytest -m unit
 ```
 
 ## Code style & conventions
@@ -206,7 +209,7 @@ def test_tool_execution(mock_run):
 
 Before committing test changes:
 
-- [ ] **All tests pass:** `pytest tests/ -v` succeeds
+- [ ] **All tests pass:** `uv run python -m pytest` succeeds
 - [ ] **No skipped tests:** Fix or document skipped tests
 - [ ] **Coverage maintained:** New code has corresponding tests
 - [ ] **Isolation:** Tests don't depend on execution order
@@ -217,7 +220,7 @@ Before committing test changes:
 - [ ] **Documentation:** Complex test logic has comments
 
 **Integration test checklist:**
-- [ ] E2E tests pass: `pytest tests/integration/ -v`
+- [ ] E2E tests pass: `uv run python -m pytest tests/integration/ -v`
 - [ ] Real environment tested: Not just mocks
 - [ ] Idempotent: Can run multiple times safely
 - [ ] Reasonable timeout: Integration tests <30s each
@@ -330,38 +333,39 @@ def test_snapshot_write(tmp_path):
 **Debugging failing tests:**
 ```bash
 # Run with verbose output
-python3 -m pytest tests/test_config.py -vv
+uv run python -m pytest tests/test_config.py -vv
 
 # Show print statements
-python3 -m pytest tests/test_config.py -s
+uv run python -m pytest tests/test_config.py -s
 
 # Stop on first failure
-python3 -m pytest tests/ -x
+uv run python -m pytest -x
 
 # Enter debugger on failure
-python3 -m pytest tests/ --pdb
+uv run python -m pytest --pdb
 
 # Show last failed tests
-python3 -m pytest --lf
+uv run python -m pytest --lf
 ```
 
 **Common issues:**
-- **Import errors:** Run from project root, check PYTHONPATH
+- **Import errors:** Run `uv sync --extra dev` first, ensure uv run is used
 - **Fixture not found:** Check fixture scope and location
 - **Test order dependency:** Tests should be independent, fix test isolation
 - **Slow tests:** Mock external calls, use tmp_path, check for real network/subprocess
 - **Flaky tests:** Usually timing issues, mock time-dependent operations
+- **VIRTUAL_ENV warning:** Run `deactivate` first if another venv is active
 
 **Test coverage:**
 ```bash
 # Generate coverage report
-python3 -m pytest tests/ --cov=cli_audit --cov-report=html
+uv run python -m pytest --cov=cli_audit --cov-report=html
 
 # View report
 open htmlcov/index.html
 
 # Show missing lines
-python3 -m pytest tests/ --cov=cli_audit --cov-report=term-missing
+uv run python -m pytest --cov=cli_audit --cov-report=term-missing
 ```
 
 ## House rules