chore: release v0.3.1 — CHANGELOG + política de versiones en CLAUDE.md

- CHANGELOG.md: historial completo desde v0.1.0 hasta v0.3.1
- CLAUDE.md: sección 'Gestión de versiones' con reglas semver,
  tabla MAJOR/MINOR/PATCH, proceso de release copy-paste
- Scope y archivos del proyecto actualizados al estado real (v0.3.1)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

CLAUDE.md

@@ -6,19 +6,21 @@ Pedrito Hechakuaa: un bot de Telegram que monitorea notificaciones pendientes
 en el sistema judicial de Paraguay (`apps.csj.gov.py`) y avisa cuando aparece
 algo nuevo. Uso propio de un solo abogado (single-tenant).
 
-**Scope estricto de la v0:**
-- Login al PJ + polling de notificaciones pendientes
-- Diff vs snapshot anterior → solo notifica lo nuevo
-- Telegram como canal de salida
-- Correr en local o VPS con docker-compose
+**Versión actual: v0.3.1** — ver historial completo en `CHANGELOG.md`.
 
-**Fuera del scope de v0 (no agregar sin consulta explícita):**
+**Scope implementado:**
+- Login al PJ + polling de notificaciones pendientes (multi-tenant)
+- Diff vs snapshot por tenant → solo notifica lo nuevo
+- Telegram como canal de salida con onboarding, tono personalizable y timezone
+- Búsqueda de expedientes y descarga de PDFs
+- Infraestructura: Docker, health check HTTP, schema migrations, webhook opt-in
+
+**Fuera del scope actual (no agregar sin consulta explícita):**
 - Motor de reglas de plazos
 - LLM / conversación libre
-- Multi-tenant
 - Web de onboarding
 - Actuaciones de expedientes (es v1)
-- Acuse de notificaciones (nunca en MVP)
+- Acuse de notificaciones (nunca — efecto procesal irreversible)
 
 ---
 
@@ -253,9 +255,54 @@ Ante cambio de schema del PJ: actualizar `csj_client.py` y documentar en
 | Archivo | Propósito |
 |---------|-----------|
 | `CLAUDE.md` | Este archivo — reglas para Claude Code |
-| `OBSERVATIONS.md` | Hallazgos durante el desarrollo (crear si no existe) |
-| `TECH_DEBT.md` | Deuda técnica anotada (crear si no existe) |
-| `data/snapshot.json` | Estado persistido del poller |
+| `CHANGELOG.md` | Historial de versiones — actualizar antes de cada release |
+| `DEPLOY.md` | Guía de despliegue en VPS: Docker, Nginx, SSL, DNS |
+| `OBSERVATIONS.md` | Hallazgos durante el desarrollo (schema real del PJ, etc.) |
+| `TECH_DEBT.md` | Deuda técnica anotada |
+| `migrations/` | Archivos `.sql` de schema — nunca editar los ya aplicados |
+| `data/pasante.db` | Base de datos SQLite (tenants, audit_log, invite_codes) |
+| `data/snapshot_*.json` | Estado del diff de notificaciones por tenant |
+
+---
+
+## Gestión de versiones
+
+### Esquema: Semantic Versioning (semver 2.0)
+
+`MAJOR.MINOR.PATCH` — tags git con prefijo `v` (ej: `v0.3.1`).
+
+| Número | Incrementar cuando... | Ejemplos |
+|--------|----------------------|---------|
+| `MAJOR` | Cambio incompatible con versiones anteriores: migración de DB no retrocompatible, cambio de protocolo del PJ, rediseño de arquitectura | `v1.0.0` (migración a Postgres) |
+| `MINOR` | Feature nuevo sin romper lo existente: comando nuevo, integración nueva, mejora visible al usuario | `/recordatorio`, modo silencioso |
+| `PATCH` | Bug fix, security patch, mejora interna, documentación operacional | corrección de campo del PJ, hardening |
+
+### Reglas que Claude Code sigue siempre
+
+1. **Cada release requiere entrada en `CHANGELOG.md`** con fecha y secciones
+   `Added / Changed / Fixed / Security` según corresponda.
+2. **El tag se crea después del commit de changelog**, no antes.
+3. **`[Unreleased]`** acumula todos los cambios hasta que Marcos decide liberar.
+4. **Claude propone el número de versión** basándose en las reglas de arriba;
+   Marcos lo aprueba antes de tagear.
+5. **`git tag` y `git push --tags` los ejecuta Claude solo cuando Marcos lo confirma** —
+   son acciones externas (modifican el remoto) que requieren aprobación explícita.
+6. **Tags retroactivos** son válidos para dar historia a commits anteriores;
+   se crean con `git tag -a vX.Y.Z <hash>`.
+
+### Proceso de release (copy-paste)
+
+```bash
+# 1. CHANGELOG.md ya actualizado (mover [Unreleased] → [X.Y.Z] con fecha)
+git add CHANGELOG.md
+git commit -m "chore: release vX.Y.Z"
+
+# 2. Tag anotado
+git tag -a vX.Y.Z -m "vX.Y.Z — resumen en una línea"
+
+# 3. Push incluyendo el tag
+git push origin main --tags
+```
 
 ---