python-version-control

Audita y reporta la coherencia de versión de Python declarada en distintos lugares de un repositorio. Resuelve el problema típico:

"El CI corre 3.10, el Dockerfile usa 3.11, ruff apunta a py310, pero la documentación dice 'Python 3.12+'."

Drift así rompe en silencio: la clase enseña features de 3.12, el CI con 3.10 las rechaza, el contenedor de prod corre 3.11 con bugs específicos.

Cuándo usar este skill

• El usuario dice: "audita la versión de python", "revisa python version", "drift python", "coherencia python", "qué versión usa este repo", "python version control".
• Proactivamente: cuando en la sesión actual se editó pyproject.toml, Dockerfile*, compose*.y*ml, .github/workflows/*.yml con setup-python, .python-version, runtime.txt, tox.ini, noxfile.py, o .pre-commit-config.yaml.
• Antes de bumpear la versión de Python en algún archivo (para entender qué más hay que tocar).
• Después de un fallo de CI por sintaxis incompatible (SyntaxError que solo aparece en una versión del matrix).

Cómo se invoca

Sin argumentos: corre el scan sobre Path.cwd() y reporta drift.

python ~/.agents/skills/python-version-control/scan.py

Con argumento --fix <version> (e.g. --fix 3.12): muestra qué cambios haría para alinear todo a esa versión, sin escribir. Aplica cambios solo si el usuario confirma explícitamente.

python ~/.agents/skills/python-version-control/scan.py --fix 3.12

Argumento --json: salida estructurada (útil para integrarlo en otros skills como pre-push-guard).

Qué detecta (fuentes de verdad)

Output

Tabla con cada source, versión(es) declarada(s), y flag de drift:

Fuente                                       Versión          Estado
─────────────────────────────────────────────────────────────────────
pyproject.toml  requires-python              >=3.10           ⚠ floor 3.10
pyproject.toml  ruff target-version          py310            ⚠ desfasado vs Docker
pyproject.toml  classifiers                  3.10, 3.11, 3.12 OK rango
Dockerfile      FROM                         3.11.10          ⚠ no es el target
.github/workflows/ci.yml matrix              3.10, 3.11, 3.12 OK
.github/workflows/deploy-pages.yml           3.12             OK (script run)
.github/workflows/security.yml               3.11             ⚠ inconsistente
.python-version                              (no existe)      —
README.md menciones                          3.12+            ⚠ pyproject permite 3.10

VERDICT: drift detectado (5 fuentes consistentes, 4 desalineadas)
Sugerencia: alinear a 3.12 (la más reciente declarada como soportada en
            README/clases) o a 3.10 (la mínima común). Revisa qué features
            usas para decidir.

Cómo aplicar fixes

Importante: cero auto-fix sin confirmación del usuario. El skill puede proponer el diff exacto que aplicaría, pero el usuario debe decir "aplica" antes de tocar archivos.

Flow:

1. Skill detecta drift → reporta tabla.
2. Usuario dice "alinea a 3.12" o --fix 3.12.
3. Skill genera diff propuesto (sin aplicar).
4. Usuario confirma → aplicar.
5. Reporte de qué se cambió + recomendación de re-correr CI.

Reglas para el target:

• requires-python se actualiza a >=X.Y (mantiene operador >=)
• classifiers se sincronizan al rango entre el min de requires-python y la última versión del CI matrix
• target-version de ruff/mypy/black se alinea al mínimo declarado (no al target ideal, sino al piso, para que el formateo no use features no disponibles)
• Dockerfile FROM usa la major.minor del target principal (no patch, deja al runtime resolver el patch más reciente)
• workflows setup-python se alinean según rol:
  • CI matrix: rango del min al max declarado en requires-python/classifiers
  • Deploy/Security: una sola versión, la del target principal

Cuándo NO usar este skill

• Repos non-Python (sin pyproject.toml, setup.py, ni requirements.txt)
• Cuando el usuario está activamente bumpeando una sola versión y sabe lo que hace
• Para temas de dependencias específicas (eso lo cubre security-audit o un dep-check separado)

Integración con otros skills

• pre-push-guard: puede invocar este skill (modo --json) si el diff toca archivos relevantes.
• security-audit: complementario — security-audit revisa CVEs de dependencias, este skill revisa la versión del intérprete.
• yaml-control: si los workflows tienen drift, este skill lo detecta; yaml-control valida sintaxis. Ortogonales.