ops-deps git:20260806.146d8e8A

Immutable. This exact content never changes and is served at /api/v1/blob/9c2c79d26638e973.

---
name: ops-deps
description: "Audit and refresh dependency health and supply-chain state."
---

## OBJECTIVE

**THE MECHANIC.**
Dependencies are not pets; they are cattle.
If a dependency is old, it is a security risk. If it is dead, it is a liability.
**Your Goal**: Keep the supply chain fresh.
**The Philosophy**: If an upgrade breaks your code, **YOUR CODE IS WRONG**. Fix the code, don't pin the version.

## CONTEXT STRATEGY (TOKEN ECONOMICS)

1. **Focused Updates**:
    - Don't list all 1000 packages.
    - Focus on **Critical** (Security) and **Major** (Breaking) updates first.

## VIBE CODING INTEGRATION

AI often suggests outdated packages from training data. This command:

- Catches AI's outdated dependency suggestions
- Prevents AI from using deprecated APIs
- Keeps manifest in sync with AI-generated code

## PROTOCOL

### Phase 1: The Health Scan (Discovery)

*Identify the rotting flesh.*

1. **Check Status**:
    - **JS/TS**: `npm outdated` / `pnpm outdated`.
    - **Rust**: `cargo outdated`.
    - **Python**: `uv pip list --outdated`.
2. **Categorize**:
    - **Patch/Minor** (e.g., 1.2.0 -> 1.2.1): Should be safe.
    - **Major** (e.g., 1.0 -> 2.0): **Breaking Changes**. Requires attention.
    - **Zombie**: Archived or no release in > 24 months → **FLAG FOR REPLACEMENT**.
3. **Security Signals**:
    - Query **OSV**/**NVD** for known CVEs; prefer packages with active maintenance
    - If in SEC policy (KEV/EPSS) → treat as urgent

### Phase 2: The Upgrade Strategy (Atomic & Aggressive)

*Do not upgrade everything at once. That is suicide.*

1. **Select Target**: Pick ONE package (or tight group like `@babel/*`).
2. **Execute Upgrade**:
    - **JS/TS**: `npm install lib@latest`.
    - **Python**: `uv pip install -U <package>` then `uv sync`.
    - **Constraint**: DO NOT use `--legacy-peer-deps` or `--force`. Resolve conflicts.
3. **Verify**:
    - Run `verify-test` (Unit) + type-check
    - Run `build` where applicable

### Phase 3: The Breakage Protocol (Fix Forward)

*The upgrade broke the build. Good. Now we work.*

**Scenario A: Type Error / API Change**

- **Action**: Read the Changelog.
- **Fix**: Update *our* code to match the new API.
- **Rule**: Do NOT downgrade unless the new version has a confirmed Critical Bug.

**Scenario B: The Zombie/Abandonware**

- **Trigger**: Library is broken and unmaintained.
- **Action**: **MIGRATE** to supported alternative.

### Phase 4: Automation (Keep it Fresh)

1. **Renovate/Dependabot**: Enable; weekly schedule; group minor/patch by ecosystem
2. **Lockfile Policy**:
    - Commit lockfiles (`package-lock.json`, `Cargo.lock`, `uv` lock)
    - Recreate lockfiles when registry metadata changes
3. **CI Gate**: Add "deps" workflow to run upgrades PRs with tests/lints/audit

## OUTPUT FORMAT

**The Upgrade Report**

```markdown
# 🔧 DEPENDENCY UPGRADE LOG

## 🟢 Successfully Upgraded
- `react`: 18.2 -> 18.3 (Patch) - Tests Passed.
- `zod`: 3.22 -> 3.23 (Minor) - Tests Passed.

## 🔴 Breaking Changes (Action Required)
- **Target**: `uuid` (8.0 -> 9.0)
- **Error**: `v4()` import changed to named export.
- **Fix Applied**: Updated `src/utils/id.ts` to use new syntax.
- **Status**: ✅ FIXED & UPGRADED.

## 💀 ZOMBIE DETECTED
- **Target**: `moment`
- **Recommendation**: Plan `migration` to `date-fns` immediately.
```

## EXECUTION RULES

1. **COMMIT LOCKFILES**: `package-lock.json` / `Cargo.lock` MUST be committed after every upgrade.
2. **NO PINNING**: Avoid exact pins unless a documented bug ticket exists; default caret (`^`). For Python, commit the **lockfile** generated by `uv` along with `pyproject.toml`.
3. **TESTS ARE SACRED**: You cannot merge an upgrade if `test` fails. Fix the code.
4. **NO GARBAGE FLAGS**: `--legacy-peer-deps`, `--force` are banned. Resolve root cause.

## AI GUARDRAILS

| AI Pattern | Problem | Solution |
|------------|---------|----------|
| Suggesting deprecated packages | `moment`, `request` | Use modern alternatives |
| Wrong API version | AI uses v2 syntax for v3 lib | Check changelog after upgrade |
| Phantom dependencies | AI imports uninstalled package | Verify in manifest before using |
| Conflicting versions | AI suggests incompatible deps | Resolve conflicts properly |