colombia-open 0.3.0__tar.gz

colombia_open-0.3.0/.claude/agents/data-quality-reviewer.md

@@ -0,0 +1,86 @@
+---
+name: data-quality-reviewer
+description: Usar PROACTIVAMENTE antes de mergear cualquier fuente nueva o cambio a un extractor/validador/builder existente — revisa que cumpla el contrato de esquema/validación de colombia-open antes de que el código se integre. Invocar también si David pide "revisa la calidad de esta fuente" o similar.
+tools: Read, Grep, Glob, Bash
+---
+
+Eres el revisor de calidad de datos de colombia-open. Tu trabajo es
+verificar que una fuente nueva (o un cambio a una existente) cumple el
+contrato del proyecto ANTES de que se mergee — no escribes código, solo
+reportas si pasa o qué falta.
+
+## Qué revisar, en orden
+
+1. **Extractor** (`.claude/rules/extractors.md`):
+   - ¿`fetch()` tiene try-en-vivo + except-a-fallback, nunca lanza si hay
+     fallback posible?
+   - ¿El `except` captura solo fallas esperadas de la fuente
+     (`RequestException`, `KeyError`, `ValueError`, `TypeError`), nunca un
+     `except Exception` desnudo que esconda bugs de programación como si
+     fueran "fuente caída"?
+   - ¿El fallback está claramente marcado `source_mode="fallback"` y es
+     obviamente una muestra mínima, no datos reales disfrazados?
+   - ¿Los códigos administrativos se normalizan a string de ancho fijo
+     (`.zfill(n)`) en el extractor, nunca dejados como int?
+   - ¿Usa `write_raw_snapshot_atomic`/`write_staging_csv_atomic` (nunca
+     escritura manual no atómica)?
+   - ¿Usa importaciones absolutas normales (sin manipular `sys.path` ni
+     try/except de importación) y se invoca como módulo
+     (`python -m src.extractors.{name}_extractor`)?
+   - ¿`REUSE_POLICY` refleja la licencia real verificada de la fuente
+     (no un default asumido)?
+
+2. **Validación** (`.claude/rules/validation.md`):
+   - ¿`validate_{dataset}()` devuelve siempre un `ValidationResult`
+     tipado (`src/validation/result.py`), nunca un dict plano, y nunca
+     lanza?
+   - ¿Valida: no-vacío, unicidad de clave primaria, ancho fijo de
+     cualquier código administrativo, y conteo mínimo si
+     `source_mode="live"`?
+   - ¿Si el dataset referencia códigos de otro dataset, valida integridad
+     referencial?
+   - ¿Está registrada en `src/validation/__init__.py::VALIDATORS`? Corre
+     `python scripts/check_validation_registration.py` para confirmar —
+     no lo asumas leyendo el código, ejecútalo.
+
+3. **Registro** (`data/registry/datasets.json`):
+   - ¿La entrada tiene `description`, `extractor`, `source_name`,
+     `join_keys`, `outputs`, `documentation`, `usage_examples`?
+   - ¿`expected_record_count` es razonable para la fuente real (no un
+     placeholder tipo `0` o `999999`)?
+
+4. **Tests**:
+   - Corre `python -m pytest -v` sobre los tests nuevos. ¿Cubren: fallback
+     con códigos de ancho correcto, dry_run sin escritura, caso feliz de
+     validación, al menos un caso de error por regla, dataframe vacío,
+     warning en modo fallback?
+
+5. **Documentación**:
+   - ¿Existe `docs/datasets/{dataset}.md` con esquema completo
+     (columna/tipo/descripción), fuente, licencia, ejemplos, limitaciones?
+   - ¿`docs/roadmap/roadmap.md` tiene la fila marcada como implementada con link al
+     extractor?
+   - ¿`src/colombia_open/datasets.py::Dataset` incluye el dataset nuevo?
+
+6. **Gates automatizados** — corre y reporta el resultado real, no lo
+   infieras:
+   ```bash
+   python -m src.build_pipeline
+   python scripts/verify_pipeline.py --require-live
+   python -m pytest
+   python -m ruff check src/ tests/
+   python -m mypy
+   python -m bandit -c pyproject.toml -r src/
+   ```
+
+## Formato del reporte
+
+Para cada punto del checklist: ✅ cumple / ⚠️ cumple parcialmente (explica
+qué falta) / ❌ no cumple (explica el problema concreto, con archivo y
+línea si aplica). Termina con un veredicto único: **LISTO PARA MERGEAR** o
+**FALTA: <lista concreta y accionable>**. No hables de "calidad en
+general" — cada hallazgo debe ser una acción concreta que alguien pueda
+ejecutar.
+
+No corrijas el código tú mismo salvo que David te lo pida explícitamente
+después de ver tu reporte — tu rol aquí es revisar, no implementar.

colombia_open-0.3.0/.claude/commands/next-source.md

@@ -0,0 +1,25 @@
+---
+description: Lee docs/roadmap/roadmap.md, propone la siguiente fuente candidata y arranca la skill new-source sobre ella.
+---
+
+Lee `docs/roadmap/roadmap.md` completo. De la tabla de fuentes, identifica la fila con
+menor dificultad (🟢 > 🟡 > 🟠 > 🔴) entre las que NO están implementadas
+todavía (columna "Estado" = ⬜).
+
+Antes de proponerla:
+1. Verifica el endpoint/URL actual de esa fuente con una petición real
+   (curl/fetch), no solo lo que dice la tabla — puede estar desactualizada.
+2. Si el acceso real difiere de lo descrito (URL muerta, requiere login,
+   formato distinto), dilo explícitamente y, si cambia la dificultad
+   estimada, actualiza la fila en `docs/roadmap/roadmap.md` antes de seguir.
+3. Presenta la fuente candidata a David con: nombre, URL verificada,
+   formato de datos, licencia (si es visible), y por qué es la de menor
+   dificultad disponible. Espera confirmación antes de empezar a
+   implementar — no asumas que la primera candidata es la correcta sin
+   que él lo confirme, puede haber una razón para priorizar otra.
+
+Una vez confirmada, invoca la skill `new-source` sobre esa fuente (nombre +
+URL verificada) y sigue su checklist completo.
+
+Recuerda la regla de `CLAUDE.md`: una fuente por fin de semana. Esta
+sesión implementa UNA fuente, de punta a punta, no varias a medias.

colombia_open-0.3.0/.claude/rules/extractors.md

@@ -0,0 +1,128 @@
+---
+description: Contrato para cualquier archivo en src/extractors/
+appliesTo: "src/extractors/**"
+---
+
+# Contrato de extractores
+
+Todo extractor implementa `BaseExtractor` (`src/extractors/base.py`) y
+sigue este contrato. La skill `.claude/skills/new-source/SKILL.md` genera
+un esqueleto que ya lo cumple — si estás escribiendo uno a mano, verifica
+cada punto.
+
+## 1. Try en vivo, fallback solo si todo falla — y solo para fallas esperadas
+
+```python
+EXPECTED_FETCH_FAILURES: tuple[type[Exception], ...] = (RequestException, KeyError, ValueError, TypeError)
+
+def fetch(self, **kwargs) -> ExtractionResult:
+    try:
+        ...  # fuente en vivo
+        return ExtractionResult(..., source_mode="live", ...)
+    except EXPECTED_FETCH_FAILURES as exc:
+        ...  # fallback embebido mínimo
+        return ExtractionResult(..., source_mode="fallback", ...)
+```
+
+- **Nunca uses `except Exception` desnudo aquí.** Captura solo las fallas
+  que de verdad pueden venir de la fuente: errores de red/HTTP
+  (`requests.RequestException`), forma de JSON inesperada (`KeyError`,
+  `TypeError`), o un valor que no parsea (`ValueError` — esto incluye
+  `JSONDecodeError`, que hereda de `ValueError`). Un bug de programación
+  real (`AttributeError` por un typo, `NameError`, etc.) **debe reventar**,
+  no disfrazarse de "fuente caída" — un `except Exception` amplio esconde
+  justo los errores que más urgen arreglar.
+- `fetch()` **nunca lanza** ante una falla esperada de la lista de arriba
+  si hay un fallback posible — siempre devuelve un `ExtractionResult`, con
+  `source_mode` reflejando la verdad.
+- El fallback es una muestra mínima embebida en el propio archivo
+  (5-15 filas representativas), solo para desarrollo offline. **Nunca se
+  presenta como dato real** y **nunca se publica**:
+  `scripts/verify_pipeline.py --require-live` lo rechaza.
+- Si de verdad no hay fallback razonable (la fuente es indispensable y no
+  hay snapshot previo), es correcto dejar que la excepción se propague —
+  mejor un build que falla fuerte que un silencio.
+
+## 2. Snapshot crudo, write-once
+
+Cada fetch en vivo exitoso escribe el payload crudo (antes de normalizar)
+a `data/raw/{dataset}_{timestamp}.json` vía
+`write_raw_snapshot_atomic()`. Nunca se edita ese archivo después de
+escrito — es el rastro de auditoría de qué devolvió la fuente exactamente.
+Guarda también su SHA256 (`compute_sha256()`) en el `ExtractionResult`.
+
+## 3. Normalización: códigos administrativos como string de ancho fijo
+
+```python
+"cod_dpto": str(row["cod_dpto"]).zfill(2),   # nunca int
+"cod_mpio": str(row["cod_mpio"]).zfill(5),   # nunca int
+```
+
+Cualquier columna que sea un código administrativo (departamento,
+municipio, y los que vengan en fuentes futuras) se normaliza a string de
+ancho fijo en el extractor, no después. Pandas/Polars/Excel truncan ceros
+iniciales de un int silenciosamente — ese bug no se detecta en los tests a
+menos que verifiques explícitamente el ancho (ver
+`.claude/rules/validation.md`).
+
+## 4. Staging: CSV + metadata.json, siempre juntos
+
+`write_staging()` escribe ambos atómicamente
+(`write_staging_csv_atomic()`). El metadata.json sigue el esquema de
+`ExtractionResult.to_staging_metadata()`:
+
+```json
+{
+  "dataset": "...",
+  "source_name": "...",
+  "source_url": "...",
+  "source_mode": "live" | "fallback",
+  "source_detail": "...",
+  "refreshed_at_utc": "...",
+  "record_count": 0,
+  "fields": ["..."],
+  "notes": ["..."],
+  "raw_snapshot_path": "...",
+  "snapshot_hash": "...",
+  "reuse_policy": { "status": "...", "license": "...", ... }
+}
+```
+
+Nunca se escribe el CSV sin su metadata.json hermano — un builder que lo
+encuentre sin metadata debe fallar fuerte, no asumir valores.
+
+## 5. Red: reintentos solo en errores de red, nunca en 4xx/5xx
+
+Usa `src/extractors/http_utils.py::get_json`/`get_bytes` — ya tienen
+backoff exponencial para `ConnectionError`/`Timeout` (vía `tenacity`).
+**No reintentes en respuestas 4xx/5xx** — eso es una respuesta real del
+servidor (dato cambió de formato, endpoint movido, bloqueo anti-bot), no
+un problema de red transitorio; cae a fallback o deja que falle.
+
+## 6. Siempre se invoca como módulo, nunca como script suelto
+
+```python
+from src.extractors.base import BaseExtractor, ExtractionResult, ...
+from src.extractors.http_utils import get_json
+```
+
+Importaciones absolutas normales, sin manipular `sys.path` ni try/except
+de importación. Esto funciona porque la convención del proyecto es
+**invocar siempre con `-m` desde la raíz del repo**:
+`python -m src.extractors.{name}_extractor` (así lo hace el Makefile y la
+CI) — nunca `python src/extractors/{name}_extractor.py` directo, que
+fallaría al importar porque `src` no quedaría en el path.
+
+No reintroduzcas el truco de `sys.path.insert()` / `try: from src.x import
+... except ModuleNotFoundError: from x import ...` — es deuda técnica que
+otros proyectos cargan por compatibilidad histórica con código viejo, que
+este proyecto no tiene. Si un extractor nuevo "necesita" ese truco para
+funcionar, el problema real es que algo lo está invocando sin `-m`.
+
+## 7. Si la fuente requiere scraping real (no API/descarga directa)
+
+Eso va bajo el extra `scraping` (`curl_cffi`, `beautifulsoup4`,
+`defusedxml`), no `pipeline`. Antes de llegar ahí: ¿de verdad no hay una
+API JSON o un endpoint de descarga directa? Prefiere siempre eso —
+scraping HTML es la fuente más frágil y cara de mantener (ver `docs/roadmap/roadmap.md`,
+fuentes 🟠/🔴).

colombia_open-0.3.0/.claude/rules/releases.md

@@ -0,0 +1,101 @@
+# Convención de versionado y releases
+
+`colombia-open` publica dos cosas por separado, cada una con su propio
+workflow manual:
+
+- **Datos**: GitHub Releases con el bundle de `data/normalized/` + SHA256
+  (`.github/workflows/release.yml`). Es lo que `ColombiaOpen()` descarga y
+  cachea automáticamente en el primer uso (ver `data_manager.py`).
+- **Paquete**: el código de `colombia_open/` a PyPI, vía trusted
+  publishing — sin token almacenado (`.github/workflows/publish.yml`).
+  Verificado end-to-end el 2026-10-18 (build local + venv aislado +
+  descarga real del bundle), pero **todavía no se ha corrido el primer
+  publish real** — requiere que el mantenedor configure un trusted
+  publisher en pypi.org primero (ver el comentario del workflow).
+
+Usa SemVer (`MAJOR.MINOR.PATCH`) sobre `version` en `pyproject.toml` para
+ambos — el mismo número de versión identifica el release de datos
+(`vX.Y.Z` en GitHub Releases) y el release del paquete (`X.Y.Z` en PyPI).
+
+## Qué sube cada número
+
+**PATCH** (`0.X.Y` → `0.X.(Y+1)`)
+- Fix en un extractor/validador existente que no cambia el esquema
+  publicado ni agrega un dataset.
+- Corrección de docs, typos, CI/pipeline sin impacto en los datos
+  publicados.
+- Actualización de dependencias sin cambio de comportamiento.
+
+**MINOR** (`0.X.Y` → `0.(X+1).0`)
+- Agregar una fuente/dataset nuevo al catálogo — el caso más común en
+  este proyecto, dado el ritmo "una fuente por fin de semana" (ver
+  `CLAUDE.md`).
+- Agregar un método nuevo a la API pública (`ColombiaOpen`) de forma
+  retrocompatible.
+
+**MAJOR** (`X.Y.Z` → `(X+1).0.0`)
+- Cambio de esquema que rompe compatibilidad en un dataset ya publicado
+  (renombrar/quitar una columna, cambiar su tipo).
+- Cambio breaking en la API pública (renombrar/quitar un método, cambiar
+  una firma de forma incompatible).
+- Mientras el proyecto esté en `0.x`, el salto real a `1.0.0` queda
+  reservado para cuando el catálogo y la API se consideren estables — no
+  es solo "un cambio grande", es ese hito específico.
+
+## Reglas al cortar un release
+
+1. **Confirma cuál fue el último release REAL antes de asumir el
+   siguiente número** — `pyproject.toml` puede estar desactualizado si
+   alguien olvidó bumpearlo. Nunca asumas el estado de releases solo por
+   lo que dice el código:
+
+   ```bash
+   gh release list
+   git fetch --tags && git tag --sort=-v:refname
+   ```
+
+2. El número de versión en `pyproject.toml` se bumpea **como parte del
+   commit que cierra el trabajo que se va a liberar** — nunca se
+   "adelanta" especulativamente antes de que el trabajo esté listo, ni se
+   reusa un número que ya corresponde a un tag publicado.
+
+3. El tag del release **siempre coincide exactamente** con `version` en
+   `pyproject.toml` en el commit que se está liberando (ej. si
+   `pyproject.toml` dice `0.2.0`, el tag es `v0.2.0`).
+
+4. Cortar el release (manual a propósito — ver el comentario en
+   `.github/workflows/release.yml`, es decisión del mantenedor, no algo
+   que un agente dispare sin que se le pida explícitamente):
+
+   ```bash
+   gh workflow run release.yml -f tag=vX.Y.Z
+   gh run watch
+   ```
+
+   El workflow reconstruye desde las fuentes en vivo y **falla el release
+   si cualquier dataset queda en `source_mode="fallback"`**
+   (`scripts/verify_pipeline.py --require-live`) — eso es intencional, no
+   un bug a silenciar.
+
+5. Después de un release exitoso, revisa que no haya quedado
+   documentación desactualizada referenciando el tag anterior (README
+   "Estado del proyecto", landing page, etc.) — ver el incidente real de
+   esto en el historial de commits de 2026-10-18, donde el README quedó
+   mencionando `v0.1.0` después de publicarse `v0.2.0`.
+
+## Publicar el paquete a PyPI
+
+Decisión del mantenedor, no algo que un agente dispare sin que se le pida
+explícitamente (mismo criterio que el release de datos). Requiere que el
+trusted publisher ya esté configurado en pypi.org (ver el comentario de
+`publish.yml`) — sin eso, el paso de publicación falla con un error de
+autenticación, no hay ningún secret que configurar en este repo.
+
+```bash
+gh workflow run publish.yml -f expected_version=X.Y.Z
+gh run watch
+```
+
+El workflow valida que `pyproject.toml` tenga exactamente esa versión
+antes de construir y publicar — falla fuerte si no coincide, en vez de
+publicar silenciosamente la versión equivocada.

colombia_open-0.3.0/.claude/rules/validation.md

@@ -0,0 +1,93 @@
+---
+description: Qué significa "validado" para un dataset en colombia-open
+appliesTo: "src/validation/**"
+---
+
+# Contrato de validación
+
+## Qué "validado" significa aquí
+
+Un dataset está validado cuando su función `validate_{dataset}()` devuelve
+`status: "ok"` — eso significa, como mínimo:
+
+1. **No está vacío.**
+2. **La clave primaria es única** (`cod_mpio` en municipios, `cod_dpto` en
+   departamentos) — usa `_helpers.duplicate_count()`.
+3. **Los códigos administrativos tienen el ancho fijo correcto**
+   (`_helpers.invalid_fixed_length_count()`) — 2 dígitos para
+   departamento, 5 para municipio. Esto detecta el bug clásico de "Excel/
+   pandas se comió el cero inicial" antes de que llegue a producción.
+4. **Integridad referencial** donde aplique (`_helpers.unknown_codes_count()`)
+   — ej. todo `cod_dpto` en `municipios` debe existir en `departamentos`.
+5. **Si `source_mode == "live"`**: el conteo de filas no puede ser
+   sospechosamente bajo (`EXPECTED_*_MIN_COUNT` en `_constants.py`) — una
+   fuente que de repente devuelve 10 filas en vez de 1100 es una fuente
+   rota, no un dataset pequeño.
+
+## Forma del resultado — nunca lanza, y está tipado
+
+```python
+from .result import ValidationResult
+
+def validate_X(df: pl.DataFrame, metadata: dict | None = None) -> ValidationResult:
+    return ValidationResult(
+        dataset="X",
+        status="error" if errors else "ok",
+        record_count=df.height,
+        errors=[...],    # lista de strings — problemas que bloquean publicación
+        warnings=[...],  # lista de strings — no bloquean, pero se reportan
+    )
+```
+
+`ValidationResult` (`src/validation/result.py`) es un `dataclass` frozen,
+no un `dict[str, Any]` — así mypy chequea de verdad los campos (`.status`,
+`.errors`, `.warnings`) en vez de aceptar cualquier llave. Tiene un método
+`.to_dict()` solo para la frontera pública (`colombia_open.core.
+ColombiaOpen.validate_dataset()` lo usa para mantener su firma pública
+`dict[str, Any]`) — el código interno del pipeline siempre usa el objeto
+tipado, nunca el dict.
+
+Un validador **nunca lanza una excepción por un problema de calidad de
+datos** — siempre devuelve un `ValidationResult`. Quien llama
+(`build_pipeline.py`, `scripts/verify_pipeline.py`, el CLI `colombia-open
+validate`) decide si `status == "error"` debe detener el build. Esto
+mantiene a los validadores como funciones puras, fáciles de testear con un
+DataFrame construido a mano (accede a los campos por atributo:
+`result.status`, `result.errors`) — ver
+`tests/validation/test_territorio.py` como plantilla.
+
+## Dónde vive cada pieza
+
+- Un módulo por dominio bajo `src/validation/_{dominio}.py` (ej.
+  `_territorio.py` para departamentos/municipios). Nunca valides inline en
+  `build_pipeline.py` — siempre en su propio módulo.
+- Primitivas compartidas en `_helpers.py` (no dupliques
+  `duplicate_count`/`missing_columns`/etc. dentro de un módulo de dominio).
+- Constantes específicas del dominio (bounding box, conteos esperados) en
+  `_constants.py`.
+- **Registro obligatorio**: toda función `validate_*` se exporta en
+  `src/validation/__init__.py` y se agrega al dict `VALIDATORS`.
+  `scripts/check_validation_registration.py` (parte de `make doctor`)
+  falla si un dataset del registro no tiene validador registrado — un
+  validador que exists pero no está en `VALIDATORS` se salta en silencio
+  en el build, así que esto NO es opcional.
+
+## Warnings esperados vs. errores
+
+- `source_mode == "fallback"` siempre agrega un **warning**, nunca un
+  error — el fallback es válido para desarrollo, solo no se publica (eso
+  lo decide `scripts/verify_pipeline.py --require-live`, no el validador).
+- Coordenadas fuera del bounding box de Colombia (`_constants.py`) son
+  **warning**, no error — podría ser un dato legítimo mal registrado en la
+  fuente que vale la pena investigar, pero no amerita bloquear el build
+  por sí solo.
+- Duplicados de clave primaria, ancho de código incorrecto, y filas
+  huérfanas por integridad referencial son siempre **error**.
+
+## Tests de un validador nuevo
+
+Como mínimo (ver `tests/validation/test_territorio.py`):
+- Caso feliz: DataFrame válido → `status == "ok"`.
+- Un caso por cada regla de error (duplicado, ancho de código, huérfano).
+- DataFrame vacío / columnas faltantes → error claro, no un traceback.
+- `source_mode == "fallback"` → warning presente.

colombia_open-0.3.0/.claude/skills/new-source/SKILL.md

@@ -0,0 +1,134 @@
+---
+description: Usar al agregar una fuente de datos nueva a colombia-open (extractor + builder + validación + registro + tests + docs). Recibe el nombre de la fuente y su URL/endpoint.
+---
+
+# Agregar una fuente nueva a colombia-open
+
+Antes de escribir código: **verifica el endpoint/URL actual de la fuente**
+(curl/fetch real, no solo lo que dice `docs/roadmap/roadmap.md` — esa tabla
+puede estar desactualizada). Si el acceso real no coincide con lo que
+`docs/roadmap/roadmap.md` describe, corrígelo ahí antes de seguir.
+
+Usa `src/extractors/divipola_extractor.py` + `src/validation/_territorio.py`
++ `data/registry/datasets.json` (entradas `departamentos`/`municipios`)
+como plantilla de referencia en cada paso — son el ejemplo end-to-end ya
+funcionando de este mismo contrato.
+
+**Regla de alcance**: esta skill implementa UNA fuente, de punta a punta.
+No empieces una segunda mientras esta no pase `make check` completo.
+
+## Checklist
+
+### 1. Extractor — `src/extractors/{name}_extractor.py`
+
+- Importaciones absolutas normales desde `src.extractors.base`/
+  `src.extractors.http_utils` — sin manipular `sys.path` (ver
+  `.claude/rules/extractors.md` §6). El extractor se invoca siempre como
+  módulo: `python -m src.extractors.{name}_extractor`.
+- Clase `{Name}Extractor(BaseExtractor)` con `dataset_name`, `fetch()`,
+  `write_staging()`.
+- `fetch()`: try en vivo → except → fallback embebido mínimo (5-15 filas).
+  Siempre devuelve `ExtractionResult` con `source_mode` correcto. El
+  `except` captura una tupla explícita de fallas esperadas de la fuente
+  (`RequestException`, `KeyError`, `ValueError`, `TypeError` — ajusta
+  según lo que de verdad pueda fallar en esta fuente), **nunca**
+  `except Exception` desnudo (ver `.claude/rules/extractors.md` §1).
+- Define `REUSE_POLICY: ReusePolicy` con la licencia real de la fuente
+  (revisa el portal — no asumas CC BY por defecto). Si es ambigua,
+  **pregunta antes de asumir** y marca `status="restricted"` mientras
+  tanto (ver `docs/licenses/data_licenses.md`).
+- Normaliza cualquier código administrativo a string de ancho fijo
+  (`.zfill(n)`) — nunca lo dejes como int.
+- Si la fuente requiere scraping real (no hay API/descarga directa):
+  el extractor va bajo el extra `scraping`, no `pipeline` — importa
+  `curl_cffi`/`beautifulsoup4` solo ahí, no en `pyproject.toml[pipeline]`.
+- `if __name__ == "__main__":` al final, igual que el ejemplo — así
+  `make extract` (que invoca `python -m src.extractors.{name}_extractor`)
+  puede correrlo.
+
+### 2. Builder — entrada en `src/builders/datasets.py` (o módulo nuevo si el dominio no existe)
+
+- Si la fuente produce un dataset normalizado 1:1 desde staging, no
+  necesitas una función `derive_*` — el builder solo lee staging y
+  escribe parquet/json directo.
+- Si deriva más de un dataset lógico de un mismo staging (como
+  `divipola` → `departamentos` + `municipios`), escribe una función
+  `derive_{dataset}(staging_df) -> pl.DataFrame` por cada uno.
+- Agrega una columna `{campo}_clean` (vía `builders/datasets.py::clean_name`)
+  a cualquier columna de nombre que vaya a usarse para búsqueda/join por
+  texto.
+
+### 3. Validador — `src/validation/_{dominio}.py`
+
+- Función `validate_{dataset}(df, metadata=None, **kwargs) -> ValidationResult`
+  que sigue el contrato de `.claude/rules/validation.md`: nunca lanza,
+  siempre devuelve un `ValidationResult` (`src/validation/result.py`), no
+  un dict plano.
+- Mínimo: columnas requeridas presentes, clave primaria única, ancho fijo
+  de cualquier código administrativo, conteo mínimo si `source_mode="live"`.
+- Si el dataset referencia códigos de otro dataset ya existente (ej. todo
+  dataset territorial futuro probablemente referencia `cod_dpto` o
+  `cod_mpio`), valida integridad referencial con
+  `_helpers.unknown_codes_count()`.
+- **Registra la función**: impórtala y agrégala al dict `VALIDATORS` en
+  `src/validation/__init__.py`. Sin esto, `make doctor` falla.
+
+### 4. Registro — entrada en `data/registry/datasets.json`
+
+```json
+"{dataset}": {
+  "description": "...",
+  "extractor": "src/extractors/{name}_extractor.py",
+  "source_name": "...",
+  "join_keys": ["..."],
+  "expected_record_count": 0,
+  "outputs": {
+    "parquet": "data/normalized/{dataset}.parquet",
+    "json": "data/normalized/{dataset}.json"
+  },
+  "usage_examples": {
+    "python": "from colombia_open import ColombiaOpen\n\nhub = ColombiaOpen()\ndf = hub.load_polars('{dataset}')",
+    "cli": "colombia-open path {dataset} --output parquet"
+  },
+  "documentation": "docs/datasets/{dataset}.md"
+}
+```
+
+### 5. Orquestador — `src/build_pipeline.py`
+
+Agrega el bloque de extracción + derive + validate + write + catalog para
+la fuente nueva, siguiendo el patrón ya escrito para `divipola`. Si el
+dominio es nuevo, importa el validador nuevo arriba junto a los demás.
+
+### 6. Tests — `tests/{extractors,builders,validation}/test_{name}.py`
+
+Como mínimo (ver los tests de `divipola` como plantilla):
+- Extractor: normalización del fallback produce códigos de ancho correcto;
+  `run(dry_run=True)` no escribe nada a disco.
+- Builder (si aplica `derive_*`): dedup correcto, columna `_clean` presente.
+- Validador: caso feliz + un caso por regla de error + dataframe vacío +
+  warning en `source_mode="fallback"`.
+- Si agregaste algo a `colombia_open/` (ej. un método nuevo en `core.py`
+  específico del dominio): test en `tests/test_core_api.py`.
+
+### 7. Documentación y registro final
+
+1. `docs/datasets/{dataset}.md` — descripción, fuente, licencia, esquema
+   completo (tabla columna/tipo/descripción), ejemplos de uso, limitaciones
+   conocidas. Usa `docs/datasets/municipios.md` como plantilla.
+2. Agrega el/los dataset(s) nuevo(s) al enum
+   `src/colombia_open/datasets.py::Dataset`.
+3. Marca la fila correspondiente en `docs/roadmap/roadmap.md` como implementada, con
+   link al extractor (mismo formato que la fila de geografía).
+4. Corre `make check` completo — build, verify, test, lint, format-check,
+   typecheck, sec. Todo verde antes de considerar la fuente terminada.
+
+## No hagas esto
+
+- No implementes una segunda fuente en la misma sesión "ya que estás
+  aquí" — una fuente por fin de semana (ver `CLAUDE.md`).
+- No le pongas scraping HTML a una fuente que tiene API JSON o descarga
+  directa — verifica eso primero.
+- No marques una fuente como lista sin correr `make check` completo.
+- No asumas la licencia de una fuente — verifícala en el portal real y,
+  si es ambigua, pregunta antes de publicar (ver `docs/licenses/data_licenses.md`).

colombia_open-0.3.0/.github/FUNDING.yml

@@ -0,0 +1,2 @@
+github: [davidcasr]
+buy_me_a_coffee: davidcasr

colombia_open-0.3.0/.github/workflows/pages-deploy.yml

@@ -0,0 +1,33 @@
+name: pages-deploy
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "site/**"
+      - ".github/workflows/pages-deploy.yml"
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/configure-pages@v5
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: "site"
+      - id: deployment
+        uses: actions/deploy-pages@v4