Repo Hygiene: Step Order + Informe Dividido

Resumen

Tarea de mantenimiento del repositorio enfocada en restaurar la coherencia del sistema de documentación. Se reorganizó el informe dividido (`docs/informe_fase_2/`) para cumplir con los rangos declarados de Steps, se eliminaron archivos duplicados/obsoletos, y se resolvieron stashes pendientes que contenían código obsoleto. Este Step es exclusivamente de documentación (docs-only), sin cambios en código fuente.

Problema identificado: El archivo `parte_00_steps_0370_0412.md` indicaba en su nombre un rango hasta Step 0412, pero contenía Steps hasta 0417. El índice (`index.md`) declaraba "370-416" pero el archivo real tenía hasta 0417. Además, existían 4 versiones duplicadas del mismo archivo (0378, 0379, 0401, 0412) sin limpiar.

Solución aplicada: Creación de nueva parte (`parte_01_steps_0412_0450.md`) para Steps 0412+, corrección de la parte 00 para contener solo Steps 0370-0411, renumeración de todas las partes subsecuentes, eliminación de duplicados, y descarte de stashes con código obsoleto. ✅ Build exitoso. ✅ Tests CPU pasando (6/6). ⚠️ Tests ALU fallando (10/27 - pre-existentes).

Concepto: Gestión de Documentación en Proyectos Grandes

En proyectos de larga duración con cientos de Steps de desarrollo, mantener la documentación organizada es crítico para la productividad del equipo y la claridad del historial del proyecto.

Principios aplicados:

• Informe Dividido: Archivos de documentación con límite de tamaño (~2000 líneas) para facilitar lectura por humanos y agentes de IA
• Rangos Explícitos: Nombres de archivo indican claramente el rango de contenido (ej: `parte_01_steps_0412_0450.md`)
• Índice Central: Archivo `index.md` que lista todas las partes con sus rangos actualizados
• No Duplicación: Un Step debe aparecer en exactamente una parte del informe
• Orden Cronológico: Steps más recientes primero dentro de cada parte

Gestión de Stashes:

Los stashes de Git son útiles para trabajo temporal, pero pueden acumularse y crear confusión. En este Step se aplicó la siguiente estrategia:

• Clasificación: Tipo A (docs-only) vs Tipo B (incluye código)
• Análisis: Comparar contenido del stash con HEAD actual usando `git diff stash@{N}`
• Decisión: Aplicar (si es docs-only relevante), Aparcar en rama WIP (si es código no mergeado), o Descartar (si es código obsoleto/revertido)
• Documentación: Registrar la decisión tomada para cada stash

Implementación

T1: Auditoría

Se verificó el estado actual del repositorio:

• HEAD: `7da1360` en rama `develop-v0.0.2` (limpio, sincronizado)
• Working tree: Limpio (solo archivo de plan sin seguimiento)
• Stashes: 2 identificados (ambos Tipo B con código)
• Informe dividido: Archivo `parte_00_steps_0370_0412.md` con 5365 líneas conteniendo Steps hasta 0417
• Duplicados: 4 versiones obsoletas (0378, 0379, 0401, 0412)

T2: Reorganización del Informe Dividido

Pasos ejecutados:

1. Extracción de Steps 0412-0417 del archivo original usando `git show` y comandos de línea
2. Creación de `parte_01_steps_0412_0450.md` (535 líneas, 6 Steps: 0412-0417)
3. Corrección de `parte_00_steps_0370_0411.md` (4863 líneas, 42 Steps: 0370-0411)
4. Renumeración de partes subsecuentes: 01→02, 02→03, 03→04, 04→05, 05→06, 06→07
5. Eliminación de archivos duplicados usando `rm -f`
6. Actualización de `index.md` con rangos correctos

T3: Resolución de Stashes

Ambos stashes fueron clasificados como Tipo B (código) y analizados:

• stash@{0}: "WIP before STEP0417A diag" - Contenía cambios de Step 0416 en `PPU.cpp` (código revertido) → DESCARTADO
• stash@{1}: "WIP preflight baseline" - Contenía cambios de Step 0415 en `MMU.cpp`, `PPU.cpp`, `renderer.py` (código revertido) → DESCARTADO

Decisión: Ambos stashes contenían código obsoleto de Steps que fueron marcados como [REVERTIDO] en el informe. Se descartaron usando `git stash drop`.

T4: Verificación

Comandos ejecutados con salida redirigida a `/tmp`:

python3 setup.py build_ext --inplace > /tmp/viboy_step0418_build.log 2>&1
python3 test_build.py > /tmp/viboy_step0418_test_build.log 2>&1
pytest -q > /tmp/viboy_step0418_pytest.log 2>&1
pytest -q tests/test_core_cpu.py > /tmp/viboy_step0418_pytest_cpu.log 2>&1

Resultados (exit codes):

• BUILD: EXIT 0 (compilación exitosa)
• TEST_BUILD: EXIT 0 (checkpoint OK)
• PYTEST: EXIT 1 (10 failed, 17 passed - tests ALU pre-existentes)
• PYTEST_CPU: EXIT 0 (6/6 passed)

Archivos Afectados

Creados:

• docs/informe_fase_2/parte_01_steps_0412_0450.md - Nueva parte para Steps 0412+
• docs/bitacora/entries/2026-01-02__0418__repo-hygiene-step-order-informe-dividido.html - Esta entrada

Modificados:

• docs/informe_fase_2/parte_00_steps_0370_0411.md - Corregido para contener solo Steps 0370-0411
• docs/informe_fase_2/index.md - Actualizado con nueva estructura
• docs/bitacora/index.html - Añadida entrada 0418

Renombrados:

• parte_01_steps_0308_0334.md → parte_02_steps_0308_0369.md
• parte_02_steps_0267_0307.md → parte_03_steps_0267_0307.md
• parte_03_steps_0219_0266.md → parte_04_steps_0219_0266.md
• parte_04_steps_0194_0218.md → parte_05_steps_0194_0218.md
• parte_05_steps_0152_0193.md → parte_06_steps_0152_0193.md
• parte_06_steps_0101_0151.md → parte_07_steps_0101_0151.md

Eliminados:

• docs/informe_fase_2/parte_00_steps_0370_0378.md - Duplicado obsoleto
• docs/informe_fase_2/parte_00_steps_0370_0379.md - Duplicado obsoleto
• docs/informe_fase_2/parte_00_steps_0370_0401.md - Duplicado obsoleto
• docs/informe_fase_2/parte_00_steps_0370_0412.md - Versión antigua

Verificación Post-Reorganización

Comandos de verificación:

# Verificar que parte_00 no contiene Steps 0413+
grep "^### 2026.*- Step 041[3-9]" docs/informe_fase_2/parte_00_steps_0370_0411.md
# Resultado: Sin coincidencias ✅

# Verificar que parte_01 contiene Steps 0415-0417
grep -n "^### 2026.*- Step 041[5-7]" docs/informe_fase_2/parte_01_steps_0412_0450.md
# Resultado:
# 35:### 2026-01-02 - Step 0417
# 115:### 2026-01-02 - Step 0416
# 158:### 2026-01-02 - Step 0415 ✅

# Verificar estructura final
ls -1 docs/informe_fase_2/*.md | sort
# Resultado: index.md, parte_00 a parte_07 ✅

Tabla de verificación: Steps 0414-0418

Próximos Pasos

• Step 0419: Continuar con investigación de PPU/Zelda-DX (problema de framebuffer blanco identificado en Step 0416)
• Mantener el sistema de informe dividido actualizado a medida que se añadan nuevos Steps
• Crear nueva parte cuando `parte_01_steps_0412_0450.md` exceda 2000 líneas
• Resolver tests ALU fallantes (10/27 - issue pre-existente, no causado por este Step)