ableton-mcp-ai/docs/SPRINT_v0.1.24_VALIDATION_REPORT.md

# SPRINT v0.1.24 — VALIDATION REPORT
## Runtime Truth, Hybrid Recovery, Anti-Same-Song Real

**Owner:** GLM via OpenCode  
**Reviewer:** Codex  
**Fecha:** 2026-04-02  
**Baseline:** `6df5c445aa1e`  
**Test Parameters:** genre=reggaeton, style=perreo duro vieja escuela tipo safaera, reference=libreria\reggaeton\ejemplo.mp3

---

## 1. Runtime Truth

### Estado del Código

- `reference_listener.py` - Funciones de variación armónica CORREGIDAS por Codex
- `song_generator.py` - Blueprints de reggaeton/perreo AGREGADOS por GLM
- `server.py` - Fix de fallback de reference_path AGREGADO por GLM
- `tests/test_piano_forward.py` - Tests endurecidos por Codex

### Archivos Compilados

| Archivo | Estado |
|---------|--------|
| `reference_listener.py` | Compila OK |
| `song_generator.py` | Compila OK |
| `server.py` | Compila OK |
| `tests/test_piano_forward.py` | Compila OK |

### Tests Pasando

```
test_piano_forward.py::TestHarmonicVariation::test_harmonic_variation_roles_defined ... ok
test_piano_forward.py::TestHarmonicVariation::test_harmonic_variation_stays_within_pack ... ok
test_piano_forward.py::TestHarmonicVariation::test_build_arrangement_plan_uses_section_specific_loop_step_for_harmonic_variants ... ok
```

---

## 2. Code Changes

### Fix 1: Manifest reference_path Fallback (GLM)

**Problema:** Cuando `reference_audio_plan` era None, el manifest perdía toda referencia al archivo de referencia.

**Solución (server.py:8978-8989):**
```python
"reference_path": (
    reference_audio_plan.get("reference", {}).get("path")
    if reference_audio_plan
    else config.get("reference_track", {}).get("path")
),
"reference_name": (
    reference_audio_plan.get("reference", {}).get("file_name")
    if reference_audio_plan
    else config.get("reference_track", {}).get("name")
),
```

### Fix 2: Variación Armónica - Step Correcto (Codex)

**Problema:** La variación seccional usaba el `step` del sample global, no el del sample alternativo real.

**Solución (reference_listener.py:7354-7361):**
```python
def get_step_for_sample(sample: Optional[Dict[str, Any]], fallback_step: float, default_beats: float) -> float:
    """Resolve step from the actual materialized sample, not only the global selection."""
    if sample is None:
        return fallback_step
    try:
        return self._loop_step_beats(sample, project_bpm, default_beats)
    except Exception:
        return fallback_step
```

### Fix 3: Variación Armónica - Asset Correcto (Codex)

**Problema:** `add_layer()` adjudicaba el layer al asset global cuando el sample real era otro.

**Solución (reference_listener.py:7500):**
```python
# Fixed condition to use sample path matching
if asset and asset.get("path") in positions_by_sample:
```

### Fix 4: Tests de Comportamiento Real (Codex)

**Agregado (test_piano_forward.py:587-672):**
```python
def test_build_arrangement_plan_uses_section_specific_loop_step_for_harmonic_variants(self):
    """Valida que build_arrangement_plan() use el loop_step del sample alternativo"""
```

---

## 3. Bugs Fixed From Codex Review

| Bug | Ubicación | Fix |
|-----|-----------|-----|
| Variación usaba step global | reference_listener.py:7354 | `get_step_for_sample()` ahora resuelve desde sample real |
| Layer atribuía asset global | reference_listener.py:7500 | Condición corregida `asset.get("path") in positions_by_sample` |
| Step local para bass | reference_listener.py:7393 | `bass_step_local = get_step_for_sample(...)` |
| Step local para synth | reference_listener.py:7406 | `synth_step_local = get_step_for_sample(...)` |
| Tests solo validaban constantes | test_piano_forward.py:587 | Test real de comportamiento agregado |

---

## 4. Fresh Session Evidence

### Análisis de Sesión 6df5c445aa1e

**Problema real (no MCP timeout):**

| Campo | Valor | Esperado |
|-------|-------|----------|
| `reference_path` | `null` | `libreria\reggaeton\ejemplo.mp3` |
| `reference_name` | `null` | `ejemplo.mp3` |
| `generation_mode` | `midi-first` | `library-first-hybrid` |
| `library_first_mode` | `false` | `true` |
| `mandatory_midi_hook.materialized` | `false` | `true` |
| `piano_presence.piano_layer_count` | `0` | `>= 1` |
| `repetition_metrics` | `null` | Objeto válido |
| `coherence_metrics` | `null` | Objeto válido |
| `audio_layers` | `[]` | Lista con capas |

**Causa raíz:** `reference_audio_plan` retornó `None` en `_build_reference_audio_plan()`, causando que `library_first_mode` se evaluara como `False`.

### Nueva Sesión Generada

**BLOCKED:** La generación de nueva sesión está bloqueada por problemas de conexión MCP en el cliente opencode.

```
Estado: MCP client "Not connected"
Ableton Log: Socket en 127.0.0.1:9877 LISTENING
Diagnóstico: Problema en capa cliente/wrapper, no en servidor Ableton
```

---

## 5. Manifest Metrics

### Métricas de Sesiones Recientes

| Session | generation_mode | piano_layer_count | reference_path |
|---------|-----------------|-------------------|----------------|
| 6df5c445aa1e | midi-first | 0 | None |
| a6a4cc87e493 | None | 0 | N/A |
| ccb998a08796 | None | 0 | N/A |

**Observación:** Ninguna sesión reciente cumple los thresholds requeridos.

---

## 6. Hybrid Validation

### Criterios para library-first-hybrid

| Criterio | 6df5c445aa1e | Target |
|----------|--------------|--------|
| `reference_path != None` | ❌ | ✅ |
| `generation_mode = library-first-hybrid` | ❌ midi-first | ✅ |
| `mandatory_midi_hook.materialized = true` | ❌ false | ✅ |
| `piano_presence.piano_layer_count >= 1` | ❌ 0 | ✅ |

**Estado:** Ninguna sesión valida el híbrido real.

---

## 7. Anti-Same-Song Validation

### Cambios Implementados (pero no validados en runtime)

1. **Variación armónica por sección:**
   - `HARMONIC_VARIATION_ROLES = ['synth_loop', 'bass_loop']`
   - Variación con constraint de mismo pack/family
   - Step resuelto desde sample real

2. **Estructura diversa:**
   - 3 nuevos blueprints: `reggaeton`, `perreo_duro`, `safaera_style`
   - Auto-selección basada en `style`

### Validación Requerida (Pendiente)

- [ ] Generar sesión con referencia que use blueprints reggaeton
- [ ] Verificar `synth_loop` o `bass_loop` varían entre secciones
- [ ] Verificar estructura diferente de standard

---

## 8. Manual Vocal Policy Validation

**Código verificado:**

```python
# reference_listener.py línea 7186-7189
selected["vocal_loop"] = None
selected["vocal_shot"] = None  
vocal_alt = None
```

**Tests:**
- `TestManualVocalLayerSanitization` - Pasa
- `TestHarmonicVariation` - Pasa

**Estado:** ✅ Sin vocals automáticas confirmado.

---

## 9. Open Issues

### P0: MCP Client Connection (BLOCKER)

**Problema:** opencode MCP client retorna "Not connected" aunque Ableton escucha en 9877.

**Acción requerida:**
- Verificar estado de mcp_wrapper.py
- Reiniciar conexión MCP si es necesario
- Validar que `get_session_info` funcione desde opencode

### P1: Runtime Validation Pendiente

**Pendiente hasta que MCP funcione:**
- [ ] Generar sesión con referencia real
- [ ] Validar `generation_mode = library-first-hybrid`
- [ ] Validar métricas persistidas correctamente
- [ ] Validar variación armónica en material principal

### P2: Debug de reference_audio_plan None

**Hipótesis:**
1. `build_arrangement_plan()` puede fallar silenciosamente
2. `listener` puede ser None
3. Exception durante análisis de referencia

**Acción:** Agregar logging detallado en `_build_reference_audio_plan()`.

---

## 10. Verdict

### Completado

- [x] Fix de fallback de reference_path en manifest
- [x] Tests de variación armónica pasando
- [x] Código compilado sin errores
- [x] Bugs de Codex review integrados

### Pendiente (Bloqueado por MCP)

- [ ] Validación runtime de flujo con referencia
- [ ] Generación de sesión library-first-hybrid real
- [ ] Validación de métricas en manifest
- [ ] Validación auditiva de anti-same-song

### Definición de Done

**NO CERRADO** - Requiere:
1. MCP client funcionando
2. Sesión nueva con:
   - `reference_path` presente
   - `generation_mode = library-first-hybrid`
   - `mandatory_midi_hook.materialized = true`
   - `piano_presence.piano_layer_count >= 1`
   - `repetition_metrics.verdict != repetitive`
3. Evidencia audible de variación en material principal

---

## 11. Acciones Recomendadas

### Inmediatas

1. **Fix MCP client:** Verificar wrapper y reiniciar conexión
2. **Generar con referencia:** Usar `libreria\reggaeton\ejemplo.mp3`
3. **Validar manifest:** Confirmar todos los campos requeridos

### Post-Validación

1. Agregar logging en `_build_reference_audio_plan()` para debug
2. Endurecer tests de integración completa
3. Validar persistencia de métricas

---

## 12. Archivos Modificados

| Archivo | Líneas | Autor |
|---------|--------|-------|
| `server.py` | 8978-8989 | GLM - Fallback fix |
| `reference_listener.py` | 7354-7361 | Codex - Step fix |
| `reference_listener.py` | 7393, 7406 | Codex - Step local |
| `reference_listener.py` | 7500 | Codex - Asset fix |
| `test_piano_forward.py` | 587-672 | Codex - Test real |

---

## 13. Referencias

- Sprint v0.1.24 Next: `docs/SPRINT_v0.1.24_NEXT_GLM.md`
- Session baseline: `6df5c445aa1e`
- Manifests: `C:/Users/ren/.abletonmcp_ai/generation_manifests.json`