Skip to content

CLAUDE.md

Latest commit

 

History

History
50 lines (34 loc) · 4.91 KB

CLAUDE.md

File metadata and controls

50 lines (34 loc) · 4.91 KB
Raw

CLAUDE.md — Alforja

Cara interna del proyecto (Método §2): reentrada en 5 minutos.

Qué es

Motor de consulta de gobernanza de ingeniería sobre el portafolio público de Fabián Rubio (58 repos; 9 con SAD). Dos planos: semántico (Pinecone + Weaviate híbrido, fusión RRF) y estructural (registros ADR/AUD/fase parseados a Postgres, catálogo cerrado de herramientas — ADR-010). Fuente de verdad: SAD-alforja.md (v0.6.2) — cambia solo por ADR o enmienda. Gobernado por El Método v1.5.0 (frontera AUD/IDEAS vigente).

Stack y reglas duras

  • Python ≥3.12 (local: 3.13 vía py -3.13; ver TROUBLESHOOTING), FastAPI, Pydantic v2, SQLAlchemy, injector, FastMCP (molde Veredicto, RT-1).
  • RT-2: src/alforja/domain/ es stdlib-only. Hay un test que lo hace cumplir (test_rt2_dominio_stdlib_only). No agregar imports de frameworks al dominio, jamás.
  • RT-3: núcleo determinista. fusion.py usa math.fsum a propósito (la suma naïve de floats rompía la conmutatividad — lo encontró hypothesis). LLM y red solo en adaptadores tras puertos.
  • Método §3: ningún ajuste a chunker/parser/NER sin caso en docs/CASES.md (43 casos, 10 confirmados). Deuda → docs/AUDIT.md (abiertas: AUD-001/002/004; AUD-003 reclasificada a IDEAS.md por la frontera AUD/IDEAS — enmienda 0.6.1). El vocabulario de fases y estados AUD es cerrado (CASE-013/042).

Comandos

# Windows (sin make):
.venv/Scripts/python -m pytest            # batería (28 tests, verde)
.venv/Scripts/python -m ruff check src tests
GITHUB_TOKEN=$(gh auth token) .venv/Scripts/python scripts/censo.py   # G-7 reproducible

# WSL (venv propio en .venv/bin, creado 2026-07-20) y CI:
make test | lint | censo | up (postgres+weaviate)

Ojo: el .venv es por-entorno (Scripts/ en Windows, bin/ en WSL) — si cambias de lado, recréalo.

Estado del roadmap (Anexo A del SAD)

  • Publicado (2026-07-16): github.com/faborubio/alforja, público, CI verde desde el primer push, topics declarados (fase-desarrollo — obligatorio: sin él Alforja saldría en su propio informe de deriva y rompería el fixture de Q-030). README profesional subido (según RO-2, el README es el producto para quien evalúa).
  • Fase 0 — CERRADA (2026-07-20, DoD completo): los 7 gates ✓. G-1 (Pinecone Starter sobra ~×350), G-2 (token gh), G-3 (Colab T4 plan A, Kaggle 30 h/sem fallback — chequeo de 2 min la mañana del FDS 2), G-4 (autoría propia = derecho a redistribuir extractos), G-5 (embeddings locales intfloat/multilingual-e5-base, CPU, USD 0 — decisión del autor, medición en bitácora de AUDIT; fijar en PoliticaEvaluacion al implementarla en Fase 1), G-6 (nombre libre), G-7 (censo → 0.6.0). Dominio puro + 28 tests verdes (Windows y WSL) + gold set v1.1.0 (31 consultas). Enmienda 0.6.1: Método v1.5.0 adoptado, AUD-003 → IDEAS.
  • Fase 1 — P-1 resuelto (2026-07-20): MANIFIESTO publicado en github.com/faborubio/metodo (público, v1.5.0) — enmienda 0.6.2, Q-005 del gold set desbloqueada, ADR-007 ya no diferido. Sin bloqueos para arrancar: parser de registros (formatos reales ya censados), ingesta, adaptadores, matriz de ablación A1–A6 (§6.2).
  • Fase 2: agente + FastMCP + LoRA. Fase 3: solo con tracción.

Dónde vive cada cosa

  • Dominio puro: src/alforja/domain/ (entidades, fusion/scoring/citas).
  • Puertos: src/alforja/application/ports.py (incluye el catálogo cerrado GobernanzaPort).
  • Gold set: experiments/eval_queries.yaml — los TODO(ingesta) se completan tras la primera ingesta y ANTES de congelar embeddings.
  • Censo: scripts/censo.py (stdlib-only, corre sin instalar nada).

Próxima sesión

P-1 resuelto (2026-07-20): MANIFIESTO publicado en github.com/faborubio/metodo — ya no hay bloqueos para arrancar Fase 1.

  1. Primer bloque: infrastructure/registros_parser/ — parsear ## AUD-NNN — título (formato confirmado en faro/docs/AUDIT.md) y ADRs inline en SADs (CASE-039). Fixture de arranque: los propios docs de Alforja + los 9 SADs censados + el MANIFIESTO (ya público, entra al corpus). Ojo con CASE-002 (oteo no es arc42 canónico) y CASE-038 (docs en raíz vs docs/).
  2. Ingesta: agregar sentence-transformers como dependencia de infraestructura y materializar PoliticaEvaluacion con intfloat/multilingual-e5-base (revisión fijada — G-5); chunker arc42-aware + CorpusSnapshot (max_tokens ≤ 512 en PoliticaChunking — límite del modelo, medido en G-5); adaptadores Pinecone/Weaviate (BYO vectors); make reindex. Los vectores se embeben una vez por snapshot y se persisten (G-5: ~134 min de CPU el corpus completo — no re-embeber gratis).
  3. Cierre de Fase 1: completar los TODO(ingesta) del gold set ANTES de congelar embeddings (QR-1) — incluye fijar sección/permalink exactos de Q-005 (MANIFIESTO) y revisar Q-014/Q-024; matriz de ablación A1–A6 con tabla al README; go/no-go de R-10 (recall@5 ≥ 0.8 o se replanifica FDS 2 por enmienda).