data_drain 0.3.0 → 0.3.2

data/docs/execution/archive/v0.3.1.md

@@ -0,0 +1,842 @@
+# Plan de Ejecución — v0.3.1
+
+**Release objetivo:** v0.3.1 — Calidad, CI y DX (cierre del roadmap original)
+**Items del roadmap:** 12, 13, 14, 15, 16, 17, 18, 19, 22, 23, 24 ([ver IMPROVEMENT_PLAN.md](../IMPROVEMENT_PLAN.md))
+**Branch sugerido:** `feature/v0.3.1`
+**Base:** `main` (contiene v0.3.0)
+**Estado:** No iniciado
+**Última actualización:** 2026-04-15 (revisión incorporada)
+
+---
+
+## Contexto
+
+v0.3.0 cerró refactor core + observabilidad avanzada. v0.3.1 **cierra el roadmap original de 24 items** atacando deuda de calidad: RuboCop en specs, matrix de Ruby, YARD coverage, CI polish y cosméticos. Incluye 1 bug fix pre-existente del workflow (branch trigger).
+
+**Breaking:** `required_ruby_version` sube de `>= 3.0.0` a `>= 3.2` (Ruby 3.0/3.1 EOL oficialmente).
+
+---
+
+## Review de agentes — incorporado
+
+Revisión por **big-pickle** 2026-04-15 (`docs/execution/v0.3.1-OBSERVACIONES.md`). Baselines reales medidos + 6 issues del plan. Todas las observaciones incorporadas en esta revisión:
+
+### Baseline real vs plan original
+
+| Aspecto | Plan original estimaba | Realidad medida |
+|---------|----------------------|-----------------|
+| Ofensas RuboCop en `spec/` | ~48 | **37** (12 files) |
+| `COUNT(*)` en `lib/` | no cuantificado | **3** (engine.rb×2, file_ingestor.rb×1) |
+| `stub_const` en specs | 2 files (solo S3) | **2 files: S3 + GlueRunner** ← scope de item 19 ampliado |
+| Coverage threshold | 80% | **80%** (real 97.49%) |
+| CI branch trigger | main | **master** (bug pre-existente) ← fix en item 14 |
+| Matrix Ruby | 3.4.4 solo | **3.4.4 solo** |
+
+### Desglose de 37 ofensas en `spec/`
+
+```
+Metrics/BlockLength         29   ← describe/context blocks largos
+Layout/LineLength            5   ← safe auto-correct
+Naming/VariableNumber        2   ← test_1/test_2
+Style/MultilineBlockChain    1   ← auto-correct
+---
+Total                       37
+```
+
+### 3 decisiones tomadas
+
+1. **Ruby mínimo: `>= 3.2`** (Opción B de big-pickle).
+   - Razón: Ruby 3.0 EOL desde 2024-03-30, Ruby 3.1 EOL desde 2025-03-31. CI más corto (3 versiones vs 5). Alineado con `TargetRubyVersion: 3.2` de rubocop.
+   - BREAKING preventivo documentado en CHANGELOG.
+
+2. **Postgres en CI: mocks suficientes (Opción C).**
+   - Confirmado: tests de Engine usan `instance_double(PG::Connection)` y `instance_double(PG::Result)` (ver `engine_spec.rb` desde v0.2.0).
+   - NO se levanta Postgres como service container.
+   - Tests con PG real se mantendrán futuro como opcional integration tests (item out-of-scope v0.3.1, abrir en post-roadmap).
+
+3. **`rubocop-rspec`: descartado para v0.3.1.**
+   - Agregarlo ampliaría el scope (nuevas ofensas RSpec-específicas).
+   - Se documenta como ítem 25 (post-roadmap) si se necesita más adelante.
+
+### Issues del plan (resolución 1ra pasada)
+
+| # | Issue big-pickle | Resolución |
+|---|------------------|-----------|
+| 4.1 | `rubocop-rspec` opcional ambiguo | Descartado explícitamente (decisión 3) |
+| 4.2 | Items 14 y 17 con dependencia implícita | **Fusionados en Fase 1** |
+| 4.3 | Workflow CI en `master` no `main` | Incluido como parte del fix de Fase 1 |
+| 4.4 | DuckDB binary amd64-only | OK por ahora (runners amd64) |
+| 4.5 | Compatibilidad DuckDB + Ruby 3.2/3.3 | Verificación explícita en Fase 1.7 |
+| 4.6 | Postgres en CI | Decisión 2 resuelve (mocks) |
+
+### Issues 2da pasada de big-pickle (también incorporados)
+
+| # | Issue | Severidad | Resolución |
+|---|-------|-----------|-----------|
+| 6.1 | YAML de matrix ambiguo en plan | Material | Fase 1.5 reescrita con indentación explícita y nota "strategy NO contiene steps". Validación YAML sintáctica agregada |
+| 6.2 | Badge URL depende del nombre del workflow | Bajo | Fase 2.2 agrega step de verificación `ls .github/workflows/` + placeholder `<WORKFLOW_FILENAME>` |
+| 6.3 | Estimado YARD bajo (4-6h → 5-8h real) | Ajuste | Tabla total v0.3.1 actualizada a 15-21h. Fase 5.1 muestra desglose ~47 items × 3-5 min |
+| 6.4 | Bundler cache no se usa en CI | Mejora | Agregado como item 30 post-roadmap (ahorra ~6min/run matrix) |
+| 6.5 | Marcar items `[~]` antes de ejecutar | Operativa | Fase 0.2.1 nueva: editar `IMPROVEMENT_PLAN.md` marcando items 12-24 como `[~]` antes de arrancar |
+
+### Item 13 absorbido en Fase 0
+
+30min de warm-up inline. Ya no tiene fase propia.
+
+### Item 19 scope ampliado
+
+Incluye `glue_runner_spec.rb` además de `s3_spec.rb` (big-pickle encontró `stub_const` también ahí).
+
+---
+
+## Items del release (orden ejecución)
+
+| Fase | Items | Estimación |
+|------|-------|-----------|
+| 0 | Setup + **Item 13** (build_path_base inline) | 45min |
+| 1 | **Items 17 + 14 + 18** (fusionados: rubocop specs + workflow + matrix Ruby + branch fix) | 4-6h |
+| 2 | **Items 22 + 24** (cache rubocop + CI badge) | 40min |
+| 3 | **Item 19** (stub_responses migration: S3 + Glue) | 2h |
+| 4 | **Items 23 + 16** (bump coverage threshold + Friendly SQL) | 1-2h |
+| 5 | **Items 12 + 15** (YARD + docs DEBUG/tuning) | 7-10h |
+| 6 | Release | 30min |
+
+**Total revisado:** 15-21h (2-3 días). Menos que original (17-24h) gracias a la fusión de fases y baseline real más bajo. Subió ligeramente respecto al primer revisado (14-19h) por ajuste de YARD según observación 6.3 big-pickle.
+
+---
+
+## Pre-requisitos (Fase 0)
+
+### 0.1 Verificar entorno
+
+- [ ] `git checkout main && git pull`
+- [ ] Versión actual en `lib/data_drain/version.rb` = `"0.3.0"`
+- [ ] `bundle exec rspec` pasa (143 specs, coverage 97.49%)
+- [ ] `bundle exec rubocop lib/` sin ofensas
+- [ ] `bundle exec rubocop spec/ 2>&1 | tail -5` — reporta **37 ofensas** (confirmar)
+
+### 0.2 Crear branch
+
+- [ ] `git checkout -b feature/v0.3.1`
+
+### 0.2.1 Marcar items como en progreso (observación 6.5 big-pickle)
+
+Convención del `IMPROVEMENT_PLAN.md`: antes de arrancar un item, marcarlo `[~]` (en progreso). Esto mantiene la memoria del proyecto consistente si múltiples agentes trabajan en paralelo.
+
+- [ ] Editar `docs/IMPROVEMENT_PLAN.md`: cambiar estado de items 12, 13, 14, 15, 16, 17, 18, 19, 22, 23, 24 de `[ ]` a `[~]`.
+- [ ] Commit: `chore: marcar items v0.3.1 como en progreso`
+- [ ] Se marcarán `[x]` en Fase 6.4 al cerrar el release.
+
+### 0.3 Item 13 — Extraer `build_path_base` en `Storage::Base` (warm-up, 30min)
+
+**Contexto:** `Storage::Local#build_path` (local.rb:26-29) y `Storage::S3#build_path` (s3.rb:21-24) duplican lógica. `Storage::Base` existe sin lógica compartida — extraer ahí.
+
+- [ ] Editar `lib/data_drain/storage/base.rb`, agregar al final de la clase:
+  ```ruby
+  protected
+
+  # @param bucket [String]
+  # @param folder_name [String]
+  # @param partition_path [String, nil]
+  # @return [String] path sin prefix de protocolo ni sufijo glob
+  def build_path_base(bucket, folder_name, partition_path)
+    base = File.join(bucket, folder_name)
+    base = File.join(base, partition_path) if partition_path && !partition_path.empty?
+    base
+  end
+  ```
+
+- [ ] Refactor `lib/data_drain/storage/local.rb#build_path`:
+  ```ruby
+  def build_path(bucket, folder_name, partition_path)
+    "#{build_path_base(bucket, folder_name, partition_path)}/**/*.parquet"
+  end
+  ```
+
+- [ ] Refactor `lib/data_drain/storage/s3.rb#build_path`:
+  ```ruby
+  def build_path(bucket, folder_name, partition_path)
+    "s3://#{build_path_base(bucket, folder_name, partition_path)}/**/*.parquet"
+  end
+  ```
+
+- [ ] Validar: `bundle exec rspec spec/data_drain/storage/` y `bundle exec rubocop lib/data_drain/storage/`
+
+- [ ] Commit: `refactor(storage): extraer build_path_base a Base (item 13)`
+
+### Checkpoint Fase 0
+
+- [ ] Branch creado
+- [ ] Baseline: 37 ofensas specs confirmadas
+- [ ] Item 13 cerrado (commit + tests verdes)
+
+---
+
+## Fase 1 — Items 17 + 14 + 18: CI completo + matrix Ruby
+
+**Roadmap:**
+- [Item 17](../IMPROVEMENT_PLAN.md#item-17--arreglar-48-ofensas-rubocop-en-spec-y-re-habilitar-en-ci)
+- [Item 14](../IMPROVEMENT_PLAN.md#item-14--ci-con-github-actions)
+- [Item 18](../IMPROVEMENT_PLAN.md#item-18--matrix-ruby-en-ci-32-33-34)
+
+**Contexto:** fusionados (observación 4.2 de big-pickle). No mergear Item 17 sin 14 porque rubocop local pasa pero CI no lo corre. Más incluye fix del bug `master`→`main` (observación 4.3) y matrix Ruby (item 18).
+
+### 1.1 Quitar exclusión `spec/` de RuboCop
+
+- [ ] Editar `.rubocop.yml`:
+  - Quitar:
+    ```yaml
+    AllCops:
+      Exclude:
+        - spec/
+    ```
+  - Mantener `TargetRubyVersion: 3.2` y otras configs.
+- [ ] Verificar: `bundle exec rubocop spec/ 2>&1 | tail -3` — confirmar 37 ofensas.
+
+### 1.2 Auto-correct seguro
+
+- [ ] `bundle exec rubocop spec/ --autocorrect`
+  - Arregla automáticamente: 5 `Layout/LineLength`, 1 `Style/MultilineBlockChain`, parte de `Metrics/BlockLength` si cabe.
+- [ ] `bundle exec rspec` — verificar tests verdes tras auto-correct.
+- [ ] Commit: `style(spec): rubocop autocorrect safe (item 17)`
+
+### 1.3 Config para ofensas no auto-correctibles
+
+Las 29 `Metrics/BlockLength` no se auto-corrigen — son `describe`/`context` legítimamente largos. Excluir specs del límite:
+
+- [ ] Editar `.rubocop.yml`, agregar:
+  ```yaml
+  Metrics/BlockLength:
+    Exclude:
+      - spec/**/*_spec.rb
+      - data_drain.gemspec
+  ```
+
+- [ ] Para las 2 ofensas `Naming/VariableNumber` (ej. `test_1`/`test_2`): evaluar si renombrar o relajar cop.
+  - Opción A: renombrar a `first_test`, `second_test`
+  - Opción B: agregar config:
+    ```yaml
+    Naming/VariableNumber:
+      EnforcedStyle: normalcase
+    ```
+  - **Recomendación:** A (renombrar). Más claro, cambio trivial.
+
+- [ ] `bundle exec rubocop` — verificar 0 ofensas en todo el proyecto.
+- [ ] Commit: `chore(rubocop): config para Metrics/BlockLength + rename variables (item 17)`
+
+### 1.4 Fix workflow CI: `master` → `main`
+
+Observación 4.3 big-pickle: workflow trigger está en `master`, repo usa `main`. Bug pre-existente.
+
+- [ ] Editar `.github/workflows/main.yml`:
+  ```yaml
+  on:
+    push:
+      branches: [ main ]  # ← era master
+    pull_request:
+      branches: [ main ]  # ← era master
+  ```
+
+### 1.5 Matrix Ruby 3.2 / 3.3 / 3.4 (item 18)
+
+**Decisión:** `required_ruby_version = ">= 3.2"` (ver sección "Review incorporado" punto 1).
+
+- [ ] Editar `data_drain.gemspec`:
+  ```ruby
+  spec.required_ruby_version = ">= 3.2"
+  ```
+
+- [ ] Editar `.github/workflows/main.yml`. Reemplazar el contenido actual del workflow (solo la parte del job `build`, el `on:` trigger ya se fijó en 1.4) por:
+
+  ```yaml
+  # Indentación explícita: TODOS los atributos (runs-on, env, strategy, steps)
+  # son siblings bajo `build:`. `strategy:` NO contiene `steps:`.
+  # (Observación 6.1 big-pickle.)
+  jobs:
+    build:
+      runs-on: ubuntu-latest
+      name: Ruby ${{ matrix.ruby }}
+      env:
+        FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+      strategy:
+        fail-fast: false
+        matrix:
+          ruby: ["3.2", "3.3", "3.4"]
+      steps:
+        - uses: actions/checkout@v4
+        - uses: ruby/setup-ruby@v1
+          with:
+            ruby-version: ${{ matrix.ruby }}
+            bundler-cache: false
+        - name: Download DuckDB library
+          run: |
+            curl -sOL https://github.com/duckdb/duckdb/releases/download/v1.4.4/libduckdb-linux-amd64.zip
+            unzip -o libduckdb-linux-amd64.zip -d libduckdb
+        - name: Install DuckDB library
+          run: |
+            sudo cp libduckdb/libduckdb.so /usr/local/lib/
+            sudo cp libduckdb/duckdb.h /usr/local/include/
+            sudo ldconfig
+        - name: Install gems
+          run: bundle install --jobs 4 --retry 3
+        - name: Run tests
+          run: bundle exec rspec
+  ```
+
+- [ ] Validar sintaxis YAML antes de pushear: `yq eval '.' .github/workflows/main.yml` o `python -c "import yaml; yaml.safe_load(open('.github/workflows/main.yml'))"`.
+
+### 1.6 Agregar RuboCop al workflow (item 14)
+
+- [ ] Agregar step antes de "Run tests":
+  ```yaml
+        - name: Run RuboCop
+          run: bundle exec rubocop --no-color
+  ```
+
+### 1.7 Verificación local de compatibilidad Ruby (observación 4.5)
+
+Antes de pushear, verificar que el `duckdb` gem compila en Ruby 3.2 y 3.3:
+
+- [ ] Si hay chruby/rbenv/asdf disponible:
+  ```bash
+  chruby 3.2.x && bundle install && bundle exec rspec
+  chruby 3.3.x && bundle install && bundle exec rspec
+  ```
+- [ ] Si no hay Ruby 3.2/3.3 instalados localmente: confiar en CI y corregir si falla. Posibles problemas:
+  - Sintaxis post-3.3 usada por error (ej. `it` block parameter implícito es 3.4+)
+  - C extension del gem `duckdb` sin binario pre-compilado para alguna versión
+
+### 1.8 Commits Fase 1
+
+- [ ] (Si falta separar) `ci: agregar rubocop al workflow (item 14)`
+- [ ] `ci: matrix Ruby 3.2/3.3/3.4 + required_ruby_version bump (item 18)`
+- [ ] `fix(ci): branch trigger master → main (observación big-pickle)`
+
+Orden de commits flexible. Lo importante es que tras el último, `git push origin feature/v0.3.1` haga CI verde en 3 versiones Ruby.
+
+### 1.9 Push y verificar
+
+- [ ] `git push origin feature/v0.3.1`
+- [ ] Esperar CI. Verificar que los 3 jobs (Ruby 3.2/3.3/3.4) pasan.
+- [ ] Si 3.2 o 3.3 falla:
+  - Leer logs de compilación de `duckdb` gem
+  - Leer logs de rspec (sintaxis incompatible)
+  - Aplicar fixes y commit con prefijo `fix(ci):`
+
+### Checkpoint Fase 1
+
+- [ ] 0 ofensas rubocop en todo el proyecto
+- [ ] CI corre en las 3 versiones Ruby
+- [ ] RuboCop incluido en CI
+- [ ] Workflow dispara en `main` (no `master`)
+- [ ] `required_ruby_version = ">= 3.2"`
+
+---
+
+## Fase 2 — Items 22 + 24: Cache RuboCop + CI badge
+
+**Roadmap:**
+- [Item 22](../IMPROVEMENT_PLAN.md#item-22--cache-de-rubocop-en-ci)
+- [Item 24](../IMPROVEMENT_PLAN.md#item-24--ci-badge-en-readme)
+
+### 2.1 Cache RuboCop (item 22)
+
+- [ ] Editar `.github/workflows/main.yml`, agregar step antes de "Run RuboCop":
+  ```yaml
+        - uses: actions/cache@v4
+          with:
+            path: ~/.cache/rubocop_cache
+            key: rubocop-${{ matrix.ruby }}-${{ hashFiles('.rubocop.yml') }}
+            restore-keys: rubocop-${{ matrix.ruby }}-
+  ```
+- [ ] Push y verificar:
+  - Primera corrida: cache miss, tiempo rubocop normal.
+  - Segunda corrida (sin cambiar `.rubocop.yml`): cache hit, tiempo rubocop < 5s.
+
+### 2.2 CI badge (item 24)
+
+- [ ] **Verificar nombre real del workflow** (observación 6.2 big-pickle):
+  ```bash
+  ls .github/workflows/
+  ```
+  Si es `main.yml`, usar la URL de abajo. Si fue renombrado (ej. `ci.yml`), ajustar el path del badge.
+
+- [ ] Editar `README.md`. Insertar después del título:
+  ```markdown
+  # DataDrain
+
+  [![CI](https://github.com/gedera/data_drain/actions/workflows/<WORKFLOW_FILENAME>/badge.svg)](https://github.com/gedera/data_drain/actions/workflows/<WORKFLOW_FILENAME>)
+
+  Micro-framework Ruby para extraer...
+  ```
+  Reemplazar `<WORKFLOW_FILENAME>` con el nombre real verificado arriba (típicamente `main.yml`).
+
+### 2.3 Commits + push
+
+- [ ] Commit: `ci: cache rubocop por ruby version y config hash (item 22)`
+- [ ] Commit: `docs(readme): agregar CI badge (item 24)`
+- [ ] Push y verificar badge verde.
+
+### Checkpoint Fase 2
+
+- [ ] Cache rubocop activo (tiempo subsecuentes <5s)
+- [ ] Badge verde visible en README
+
+---
+
+## Fase 3 — Item 19: Migrar tests a `stub_responses`
+
+**Roadmap:** [Item 19](../IMPROVEMENT_PLAN.md#item-19--migrar-tests-s3-de-stub_const-a-aws_s3_client_stub_responses)
+
+**Observación big-pickle:** scope ampliado — no solo `s3_spec.rb` sino también `glue_runner_spec.rb` tienen `stub_const("Aws::...", ...)`.
+
+### 3.1 Migrar `spec/data_drain/storage/s3_spec.rb`
+
+- [ ] Reemplazar `stub_const("Aws::S3::Client", Class.new ...)` por:
+  ```ruby
+  let(:s3_client) { Aws::S3::Client.new(stub_responses: true, region: "us-east-1") }
+
+  before do
+    allow(Aws::S3::Client).to receive(:new).and_return(s3_client)
+  end
+  ```
+
+- [ ] Tests de `destroy_partitions`:
+  ```ruby
+  it "arma prefix con folder y primera partition key" do
+    s3_client.stub_responses(:list_objects_v2, ->(context) {
+      expect(context.params[:bucket]).to eq("my-bucket")
+      expect(context.params[:prefix]).to eq("versions/isp_id=42/")
+      { contents: [] }
+    })
+
+    adapter.destroy_partitions(
+      "my-bucket", "versions", %i[isp_id year month], { isp_id: 42 }
+    )
+  end
+
+  it "borra objetos matching pattern completo" do
+    s3_client.stub_responses(:list_objects_v2, {
+      contents: [
+        { key: "versions/isp_id=42/year=2026/month=3/data.parquet" },
+        { key: "versions/isp_id=42/year=2026/month=3/metadata.parquet" }
+      ]
+    })
+
+    deleted_keys = []
+    s3_client.stub_responses(:delete_objects, ->(context) {
+      deleted_keys.concat(context.params[:delete][:objects].map { |o| o[:key] })
+      { deleted: deleted_keys.map { |k| { key: k } } }
+    })
+
+    adapter.destroy_partitions(
+      "my-bucket", "versions", %i[isp_id year month], { isp_id: 42, year: 2026, month: 3 }
+    )
+
+    expect(deleted_keys).to include(
+      "versions/isp_id=42/year=2026/month=3/data.parquet",
+      "versions/isp_id=42/year=2026/month=3/metadata.parquet"
+    )
+  end
+  ```
+
+### 3.2 Migrar `spec/data_drain/glue_runner_spec.rb` (scope ampliado)
+
+- [ ] Reemplazar `stub_const("Aws::Glue::Client", Class.new ...)` por equivalente `stub_responses`:
+  ```ruby
+  let(:glue_client) { Aws::Glue::Client.new(stub_responses: true, region: "us-east-1") }
+
+  before do
+    allow(Aws::Glue::Client).to receive(:new).and_return(glue_client)
+  end
+  ```
+
+- [ ] Reescribir tests usando `stub_responses`:
+  ```ruby
+  it "retorna true cuando SUCCEEDED inmediato" do
+    glue_client.stub_responses(:start_job_run, { job_run_id: "run-123" })
+    glue_client.stub_responses(:get_job_run, {
+      job_run: { job_run_state: "SUCCEEDED", error_message: nil }
+    })
+
+    result = described_class.run_and_wait("my-job", { "--key" => "val" })
+    expect(result).to be true
+  end
+
+  it "hace polling hasta SUCCEEDED" do
+    glue_client.stub_responses(:start_job_run, { job_run_id: "run-123" })
+    glue_client.stub_responses(:get_job_run, [
+      { job_run: { job_run_state: "RUNNING", error_message: nil } },
+      { job_run: { job_run_state: "SUCCEEDED", error_message: nil } }
+    ])
+
+    allow(Kernel).to receive(:sleep)
+
+    result = described_class.run_and_wait("my-job", {}, polling_interval: 5)
+    expect(result).to be true
+  end
+  ```
+
+### 3.3 Validación
+
+- [ ] `bundle exec rspec spec/data_drain/storage/s3_spec.rb spec/data_drain/glue_runner_spec.rb`
+- [ ] `grep -rn "stub_const.*Aws::" spec/` — debe retornar vacío.
+- [ ] Coverage igual o superior.
+
+### 3.4 Commit
+
+- [ ] Commit: `refactor(spec): migrar stub_const a stub_responses en S3 y Glue (item 19)`
+
+### Checkpoint Fase 3
+
+- [ ] 0 `stub_const("Aws::...", ...)` en spec/
+- [ ] Tests S3 + Glue verdes
+
+---
+
+## Fase 4 — Items 23 + 16: Coverage threshold + Friendly SQL
+
+### 4.1 Item 23 — Bump coverage threshold a 90%
+
+Trivial. No se agregan tests nuevos (cobertura actual 97.49% > 90%).
+
+- [ ] Editar `spec/spec_helper.rb`:
+  ```ruby
+  SimpleCov.start do
+    add_filter "/spec/"
+    minimum_coverage 90  # era 80
+  end
+  ```
+
+- [ ] `bundle exec rspec` — debe pasar (97.49% > 90%).
+
+- [ ] Commit: `test: subir SimpleCov minimum_coverage a 90% (item 23)`
+
+### 4.2 Item 16 — DuckDB Friendly SQL (`count()`)
+
+**Observación big-pickle:** hay 3 `COUNT(*)` en `lib/`, reemplazar 2 y dejar 1.
+
+- [ ] Editar `lib/data_drain/engine.rb`:
+  - Línea ~163 (`get_postgres_count`): `SELECT COUNT(*) AS row_count` → `SELECT count() AS row_count` ✅
+  - Línea ~199 (`verify_integrity`): `SELECT COUNT(*) FROM read_parquet(...)` → `SELECT count() FROM read_parquet(...)` ✅
+  - Línea ~206 (`export_to_parquet` dentro del COPY): **DEJAR `SELECT *` como está**. El `SELECT *` dentro del `COPY (SELECT ... FROM postgres_query...) TO ...` es legibilidad estándar, cambiarlo no aporta.
+
+- [ ] Editar `lib/data_drain/file_ingestor.rb`:
+  - Línea ~53 (`source_count`): `SELECT COUNT(*) FROM #{reader_function}` → `SELECT count() FROM #{reader_function}` ✅
+
+- [ ] `grep -rn "COUNT(\*)" lib/` — verificar que solo queda el del COPY o (idealmente) ninguno si decidimos cambiar ese también.
+
+### 4.3 Validación
+
+- [ ] `bundle exec rspec` — tests verdes (count() es DuckDB-valid).
+
+### 4.4 Commits
+
+- [ ] Commit separado: `refactor(engine,file_ingestor): count() friendly SQL de DuckDB (item 16)`
+
+### Checkpoint Fase 4
+
+- [ ] Coverage threshold = 90
+- [ ] 2 de 3 `COUNT(*)` reemplazados por `count()`
+- [ ] Tests verdes
+
+---
+
+## Fase 5 — Items 12 + 15: Docs (YARD + DEBUG/tuning)
+
+### 5.1 Item 12 — YARD coverage 50% → 90%
+
+**Estimación revisada (observación 6.3 big-pickle):** 5-8h, no 4-6h. Scope real:
+
+| Componente | Items a documentar |
+|------------|-------------------|
+| Configuration | ~21 (18 attrs + 3 métodos) |
+| Observability | 3 |
+| Observability::Timing | 2 |
+| Storage::Base/Local/S3 | ~12 |
+| Errors | 4-5 |
+| Record | 5 |
+| **Total** | **~47 items × 3-5 min = 5-8h** |
+
+#### 5.1.1 Medir baseline
+
+- [ ] `yard stats --list-undoc`
+- [ ] Documentar:
+  > Métodos públicos sin documentar: _______________
+  > Cobertura actual: _______________%
+
+#### 5.1.2 Documentar por prioridad
+
+**Prioridad alta (high-visibility):**
+
+- [ ] **Configuration** — todos los atributos con YARD:
+  ```ruby
+  # @!attribute [rw] storage_mode
+  #   @return [Symbol] :local o :s3. Default :local.
+  # @!attribute [rw] aws_region
+  #   @return [String, nil] Obligatorio si storage_mode == :s3.
+  # @!attribute [rw] aws_access_key_id
+  #   @return [String, nil] Opcional — si nil usa AWS credential_chain (IAM role/env/~/.aws).
+  # @!attribute [rw] aws_secret_access_key
+  #   @return [String, nil] Opcional — ver aws_access_key_id.
+  # @!attribute [rw] db_host
+  #   @return [String] Host PostgreSQL. Default "127.0.0.1".
+  # @!attribute [rw] db_port
+  #   @return [Integer] Default 5432.
+  # @!attribute [rw] db_user
+  #   @return [String, nil] Obligatorio para Engine.
+  # @!attribute [rw] db_pass
+  #   @return [String, nil] Opcional (auth peer/trust/IAM puede tener nil).
+  # @!attribute [rw] db_name
+  #   @return [String, nil] Obligatorio para Engine.
+  # @!attribute [rw] batch_size
+  #   @return [Integer] Default 5000. Registros por DELETE en purga.
+  # @!attribute [rw] throttle_delay
+  #   @return [Float] Default 0.5. Segundos entre lotes.
+  # @!attribute [rw] idle_in_transaction_session_timeout
+  #   @return [Integer, nil] Ms. 0 = DESACTIVADO (default). nil = no setear.
+  # @!attribute [rw] limit_ram
+  #   @return [String, nil] Ej. "2GB". Límite memoria DuckDB.
+  # @!attribute [rw] tmp_directory
+  #   @return [String, nil] Spill-to-disk DuckDB.
+  # @!attribute [rw] logger
+  #   @return [Logger] Default Logger.new($stdout).
+  # @!attribute [rw] vacuum_after_purge
+  #   @return [Boolean] Default false. Si true ejecuta VACUUM ANALYZE post-purga.
+  # @!attribute [rw] slow_batch_threshold_s
+  #   @return [Integer] Default 30. Segundos por batch que disparan warning.
+  # @!attribute [rw] slow_batch_alert_after
+  #   @return [Integer] Default 5. Lotes lentos consecutivos antes de engine.purge_degraded.
+  class Configuration
+    attr_accessor :storage_mode, :aws_region, ...
+  end
+  ```
+
+- [ ] **Observability** (métodos privados):
+  ```ruby
+  # Emite un log estructurado de forma segura.
+  # Garantiza que el logging nunca interrumpa el proceso principal (Resilience).
+  #
+  # @param level [Symbol] :debug, :info, :warn, :error
+  # @param event [String] Ej. "engine.complete"
+  # @param metadata [Hash] Pares clave-valor de contexto
+  # @return [void]
+  def safe_log(level, event, metadata = {}); ...; end
+
+  # @param error [Exception]
+  # @return [Hash] :error_class y :error_message (truncado a 200 chars)
+  def exception_metadata(error); ...; end
+
+  # @return [String] Primer namespace de la clase en snake_case (ej. "data_drain")
+  def observability_name; ...; end
+  ```
+
+- [ ] **Observability::Timing** (mixin):
+  ```ruby
+  # @return [Float] Segundos del clock monotónico
+  def monotonic; ...; end
+
+  # Mide duración de un bloque y acumula en @durations.
+  # @param step_name [Symbol] Clave para @durations
+  # @yield Bloque a medir
+  # @return [Object] Resultado del bloque
+  def timed(step_name); ...; end
+  ```
+
+- [ ] **Storage::Base / Local / S3** — completar YARD donde falte.
+
+- [ ] **Errors** — documentar causa de cada uno:
+  ```ruby
+  # Levantado cuando la configuración es inválida o incompleta.
+  # @see Configuration#validate!
+  class ConfigurationError < Error; end
+
+  # Levantado cuando COUNT(*) Postgres != COUNT(*) Parquet.
+  # Nota: actualmente Engine#call retorna false en lugar de levantarlo.
+  class IntegrityError < Error; end
+
+  # Problemas interactuando con disco local, S3 o DuckDB.
+  class StorageError < Error; end
+  ```
+
+#### 5.1.3 Validar
+
+- [ ] `yard stats --list-undoc` — objetivo ≥ 90% coverage.
+- [ ] Generar docs local: `yard doc && open doc/index.html`
+
+#### 5.1.4 Commit
+
+- [ ] Commit: `docs(yard): coverage 50% → 90%+ (item 12)`
+
+#### 5.1.5 Fallback (Plan B)
+
+Si YARD toma > 6h:
+- Cubrir solo Configuration + Observability + Observability::Timing en v0.3.1
+- Diferir Storage::*, Errors detalles a post-roadmap v0.4.0
+
+### 5.2 Item 15 — DEBUG en bloque + tabla tuning
+
+#### 5.2.1 CLAUDE.md refuerzo DEBUG
+
+- [ ] Editar `CLAUDE.md` sección "Logging", agregar:
+  ```markdown
+  ### DEBUG en bloque (obligatorio)
+
+  Usar siempre forma de bloque para evitar costo de serialización cuando DEBUG está off:
+
+  ✅ Correcto:
+      logger.debug { "query=#{expensive_serialize(obj)}" }
+
+  ❌ Incorrecto — evalúa siempre aunque DEBUG esté off:
+      logger.debug("query=#{expensive_serialize(obj)}")
+  ```
+
+- [ ] Actualizar `skill/references/antipatrones.md` antipatrón 11 (DEBUG sin bloque) con ejemplo real de DataDrain (ej. debug del query de export completo).
+
+#### 5.2.2 postgres-tuning.md — tabla tuning parámetros
+
+- [ ] Editar `skill/references/postgres-tuning.md`, agregar sección:
+  ```markdown
+  ## Tuning de parámetros DataDrain por tamaño
+
+  | Filas tabla | `batch_size` | `throttle_delay` | `vacuum_after_purge` | `slow_batch_threshold_s` |
+  |------------|-------------|-----------------|---------------------|-------------------------|
+  | <1M | 5000 | 0.1 | false | 30 |
+  | 1M-100M | 5000 | 0.5 | true | 30 |
+  | 100M-1B | 10000 | 1.0 | true | 60 |
+  | >1B | migrar a particionamiento (ver arriba) | | | |
+
+  Contexto operacional:
+  - **OLTP concurrente**: throttle_delay alto (≥0.5s) para no saturar.
+  - **Tablas frías** (sin queries de usuarios): throttle_delay 0 OK.
+  - **slow_batch_threshold_s** alto en tablas grandes porque cada batch tarda más legítimamente.
+  ```
+
+#### 5.2.3 Commit
+
+- [ ] Commit: `docs: DEBUG en bloque + tabla tuning por tamaño (item 15)`
+
+### Checkpoint Fase 5
+
+- [ ] YARD ≥ 90% (o plan B aplicado)
+- [ ] CLAUDE.md con ejemplo DEBUG
+- [ ] postgres-tuning.md con tabla tuning
+
+---
+
+## Fase 6 — Release
+
+### 6.1 Lint + tests finales
+
+- [ ] `bundle exec rubocop` — 0 ofensas (lib + spec).
+- [ ] `bundle exec rspec` — coverage ≥ 90%.
+- [ ] CI verde en Ruby 3.2, 3.3, 3.4.
+
+### 6.2 CHANGELOG
+
+- [ ] Editar `CHANGELOG.md`, agregar al tope:
+  ```markdown
+  ## [0.3.1] - 2026-XX-XX
+
+  ### BREAKING (preventivo)
+  - `required_ruby_version` bumpeado a `">= 3.2"` (Ruby 3.0 y 3.1 están EOL).
+
+  ### Refactor
+  - Extraído `Storage::Base#build_path_base` para eliminar duplicación entre Local y S3. (item 13)
+  - Queries SQL internas adoptan `count()` friendly syntax de DuckDB (2 de 3 occurrences). (item 16)
+
+  ### Tests
+  - 37 ofensas RuboCop en `spec/` arregladas; RuboCop corre en todo el proyecto. (item 17)
+  - Tests S3 + GlueRunner migrados de `stub_const` a `Aws::*::Client.stub_responses` nativo. (item 19)
+  - SimpleCov `minimum_coverage` subido a 90% (cobertura actual 97.49%). (item 23)
+
+  ### CI
+  - Matrix Ruby 3.2 / 3.3 / 3.4. (item 18)
+  - RuboCop agregado al workflow. (item 14)
+  - Fix: workflow trigger corregido de `master` a `main`. (item 14)
+  - Cache de RuboCop por Ruby version + hash de config. (item 22)
+  - Badge de CI en README. (item 24)
+
+  ### Docs
+  - YARD coverage 50% → 90%+: Configuration, Observability, Observability::Timing, Errors, Storage::*. (item 12)
+  - CLAUDE.md refuerzo: DEBUG en bloque obligatorio con ejemplo. (item 15)
+  - skill/references/postgres-tuning.md: nueva tabla de tuning de parámetros DataDrain por tamaño de tabla. (item 15)
+
+  ### Roadmap
+  - **Roadmap original completado: 24/24 items cerrados.** Items post-roadmap migrados a sección "Follow-ups" en IMPROVEMENT_PLAN.md.
+  ```
+
+### 6.3 Bump versión
+
+- [ ] `lib/data_drain/version.rb`: `VERSION = "0.3.1"`
+- [ ] `bundle install`
+
+### 6.4 Actualizar roadmap
+
+- [ ] `docs/IMPROVEMENT_PLAN.md`:
+  - Items 12, 13, 14, 15, 16, 17, 18, 19, 22, 23, 24 → `[x]`
+  - Resumen ejecutivo: "Roadmap original 24/24 completado"
+  - Agregar sección "Follow-ups post-roadmap" con:
+    - Item 25: `fetch_dead_tuple_count` retorna `nil` en lugar de `-1` (cosmético logs)
+    - Item 26: documentar `lock_configuration` + httpfs comportamiento en skill
+    - Item 27: integration tests con Postgres real (service container en CI, tag `:integration`)
+    - Item 28: `rubocop-rspec` plugin + nuevas ofensas RSpec
+    - Item 29: particionamiento declarativo nativo en Engine (detectar y usar DROP PARTITION)
+    - Item 30: habilitar `bundler-cache: true` en CI tras setup DuckDB (observación 6.4 big-pickle) — ahorra ~6min/run matrix 3 versiones
+
+### 6.5 Commit release
+
+- [ ] Commit: `chore: release v0.3.1 — calidad, CI y DX (cierre roadmap 24/24)`
+
+### 6.6 PR + merge + tag
+
+- [ ] `git push origin feature/v0.3.1`
+- [ ] `gh pr create --title "v0.3.1: calidad, CI y DX (cierre roadmap 24/24)"` con body del CHANGELOG
+- [ ] Esperar CI verde (3 jobs Ruby)
+- [ ] Mergear
+- [ ] Tag: `git tag v0.3.1 && git push origin v0.3.1`
+
+### 6.7 Post-merge
+
+- [ ] Archivar: `git mv docs/execution/v0.3.1.md docs/execution/archive/v0.3.1.md`
+- [ ] Commit: `chore: archive v0.3.1 plan, roadmap 24/24 completado`
+- [ ] Actualizar memoria: marcar `project_data_drain.md` con estado "roadmap 24/24 completado, v0.3.1 latest".
+
+---
+
+## Validación final
+
+- [ ] CI verde en main Ruby 3.2/3.3/3.4
+- [ ] Coverage ≥ 90%
+- [ ] `bundle exec rubocop` sin ofensas
+- [ ] YARD ≥ 90%
+- [ ] Badge verde
+- [ ] Tag v0.3.1
+- [ ] 11 items marcados `[x]` (roadmap 24/24)
+- [ ] Plan archivado
+- [ ] CHANGELOG completo
+
+---
+
+## Plan B — escenarios de bloqueo
+
+| Si... | Entonces... |
+|-------|-------------|
+| Item 17 — ofensas reales > 37 al abrir un cop que estaba excluido | Evaluar cop por cop. Relajar config o fix manual según cost/benefit. |
+| Item 18 — CI falla en Ruby 3.2 o 3.3 por sintaxis | Diagnosticar error específico. Típicamente: reemplazar sintaxis post-3.3 incompatible. |
+| Item 18 — `duckdb` gem no compila en Ruby 3.2 | Actualizar gem a versión con binario prebuilt para 3.2 o subir `required_ruby_version` a `>= 3.3`. |
+| Item 19 — `stub_responses` no cubre algún método AWS SDK que usamos | Mantener `stub_const` para ese caso específico, migrar el resto. |
+| Item 12 — YARD toma > 6h | Aplicar Plan B: cubrir solo Configuration + Observability + Timing en v0.3.1. Diferir resto a v0.4.0. |
+| CI matrix > 10min | Usar `fail-fast: false` + paralelizar si hace falta. |
+| Item 23 — coverage baja de 90% tras auto-correct rubocop | Improbable (auto-correct no remueve código). Si pasa: agregar tests o bajar threshold a 85%. |
+
+---
+
+## Notas para el agente que ejecuta
+
+- **Fase 1 es la más invasiva.** Fusiona 3 items (17 + 14 + 18) + bug fix. Commits granulares dentro de la fase facilitan bisect.
+- **Cada fase cierra con verde:** rspec + rubocop + CI si la fase lo requiere.
+- **La observación 4.5 de big-pickle (DuckDB + Ruby compat)** requiere verificación real en la primera corrida de CI con matrix. Si falla, documentar en Plan B.
+- **`rubocop-rspec` NO se agrega en v0.3.1** (decisión 3). Documentar como ítem futuro post-roadmap.
+- **Roadmap 24/24:** al cerrar v0.3.1, el documento `IMPROVEMENT_PLAN.md` queda en estado "completo". Nuevos items van a "Follow-ups".
+- **Memoria del proyecto** se actualiza en Fase 6.7 para reflejar estado final.