Saltar al contenido principal

Validación y Cierre de Sprint 4

Este documento registra formalmente la auditoría técnica, la cobertura pedagógica y la verificación determinista del Sprint 4: Hands-on Tutorials, Reproducible Labs & Coding Harness Integration de la plataforma documental de RAPID OS v3.0.0.

1. Alcance y Objetivos del Sprint 4​

El Sprint 4 tuvo como objetivo primordial transformar el conocimiento teórico y normativo de RAPID OS v3 en experiencias de aprendizaje prácticas, reproducibles y directamente ejecutables por ingenieros de software y agentes de IA:

  1. Laboratorios Prácticos Canónicos: Crear 6 tutoriales completos guiados que cubren el espectro de modos de ingeniería (first-governed-project, feature, bugfix, refactor, hardening, research).
  2. Proyectos de Ejemplo Reproducibles: Proveer 6 directorios en examples/ con estructura canónica (starter/, solution/, tests/, README.md) utilizando únicamente la biblioteca estándar de Python (cero dependencias externas).
  3. Guías de Integración con Coding Harnesses: Diseñar guías operativas realistas para los 5 principales entornos de ejecución (Claude Code, Codex / OpenAI CLI, Cursor, VS Code, Google Antigravity).
  4. Frontera de Ejecución Externa Rigurosa: Establecer sin ambigüedades la separación entre el plano de gobernanza (RAPID OS) y el plano de ejecución externa (desarrollador / coding harness).
  5. Product Truth y Automatización E2E: Validar cada tutorial, ejemplo, comando de CLI y JSON authoring contract mediante pruebas automatizadas (tests/test_documentation_labs.py).

2. Matriz de Archivos Entregados​

2.1 Documentación Canónica (docs/)​

CategoríaRuta del DocumentoDescripción / Propósito
Tutorialesdocs/tutorials/index.mdCatálogo de laboratorios, progresión recomendada y requisitos previos.
Tutorialesdocs/tutorials/first-governed-project.mdLab 1: First Governed Project (Task Tracker CLI, Governance Loop completo).
Tutorialesdocs/tutorials/feature-lab.mdLab 2: Feature Lab (Booking Service, prevención de reservas duplicadas).
Tutorialesdocs/tutorials/bugfix-lab.mdLab 3: Bugfix Lab (Discount Calculator, división por cero, regression tests obligatorios).
Tutorialesdocs/tutorials/refactor-lab.mdLab 4: Refactor Lab (Payroll Processor, deduplicación de impuestos con baseline estricto).
Tutorialesdocs/tutorials/hardening-lab.mdLab 5: Hardening Lab (Auth Token Manager, remediación de timing attacks y SAST).
Tutorialesdocs/tutorials/research-lab.mdLab 6: Research Lab (Cache Eviction Spike, benchmark LRU vs FIFO y artefacto de decisión).
Troubleshootingdocs/troubleshooting/tutorials.mdGuía de diagnóstico y resolución de errores comunes en laboratorios.
Integracionesdocs/integrations/index.mdVisión general de integración con coding harnesses y frontera de ejecución.
Integracionesdocs/integrations/claude-code.mdIntegración operativa con Claude Code (terminal interactiva, hooks de gobernanza).
Integracionesdocs/integrations/codex.mdIntegración con OpenAI Codex CLI (ejecución no interactiva por lotes).
Integracionesdocs/integrations/cursor.mdIntegración con Cursor AI IDE (Agent mode, prompts de contexto compilado).
Integracionesdocs/integrations/vscode.mdIntegración con VS Code y GitHub Copilot (extensiones y terminal integrada).
Integracionesdocs/integrations/antigravity.mdIntegración con Google Antigravity (Advanced Agentic Coding, subagents).
Auditoríadocs/audit/sprint-4-validation.mdEste documento de validación, matriz de cobertura y DoD.

2.2 Proyectos de Ejemplo Reproducibles (examples/)​

LaboratorioDirectorioDescripción del ProblemaSuites de Tests
Lab 1examples/first-governed-project/Task Tracker CLI: agregado de prioridad high/medium/low.tests/test_app.py
Lab 2examples/feature-lab/Booking Service: validación de colisión de franjas horarias.tests/test_booking.py
Lab 3examples/bugfix-lab/Discount Calculator: corrección de división por cero y prueba de regresión.tests/test_discount.py
Lab 4examples/refactor-lab/Payroll Processor: extracción de cálculo de deducciones fiscales sin alterar baseline.tests/test_payroll.py
Lab 5examples/hardening-lab/Auth Token Manager: uso de hmac.compare_digest para neutralizar timing attacks.tests/test_auth.py
Lab 6examples/research-lab/Cache Eviction Spike: benchmark determinista comparando hits/misses entre LRU y FIFO.tests/test_cache.py
Catálogoexamples/README.mdÍndice de ejemplos, guía de ejecución y verificación reproducible.—

Todos los proyectos incluyen carpetas independientes starter/ (con el estado inicial o tests que fallan) y solution/ (con la solución completa y tests en verde), además de __init__.py para descubrimiento estándar con unittest.

3. Verificación de Product Truth y Restricciones Arquitectónicas​

En estricta consonancia con los principios rectores de RAPID OS y las lecciones aprendidas del Issue #40:

3.1 Cero Modificaciones en el Runtime (rapid_os/)​

  • No se alteró ningún archivo en rapid_os/cli/, rapid_os/domain/, rapid_os/adapters/ o rapid_os/core/.
  • Toda la funcionalidad probada en los laboratorios utiliza el comportamiento real de la versión 3.0.0 ya implementada.

3.2 Formato de Autoría de Evidencia (Evidence Authoring vs RunEvidence)​

  • Se respeta rigurosamente que los inputs para rapid evidence add --input <file> representan un archivo de autoría, por lo cual NO deben contener id, schema_version, o run_id. El CLI y el dominio asignan secuencialmente el ID (E001, E002, etc.) y vinculan la evidencia al contrato del Run activo.
  • Todos los payloads documentados contienen únicamente las claves permitidas por cada EvidenceKind canónico.

3.3 Orden Determinista de Reconocimiento de Gates​

  • Se documenta y verifica que compuertas posteriores a la ejecución (gate.tests, gate.final-verification) requieren que las tareas del Run hayan alcanzado el estado done (rapid run task update ... --status done). Reconocer gates antes de completar tareas dispara RAPID1014 (Precondition failed).
  • Se documenta que compuertas como gate.baseline y gate.tests requieren evidencia con lista no vacía de artefactos (artifacts: ["..."]).

3.4 Frontera de Ejecución Externa​

  • Se enfatiza en todos los tutoriales e integraciones que RAPID OS no es un ejecutor de modelos ni un runner de código.
  • El desarrollador o el coding harness es el único actor responsable de crear archivos, ejecutar python -m unittest, generar logs de salida y luego invocar al CLI de RAPID OS para registrar la evidencia producida.

4. Matriz de Pruebas Automatizadas (tests/test_documentation_labs.py)​

Se implementó una suite integral de 6 pruebas automatizadas que verifican la integridad total del material del Sprint 4:

  1. test_sprint4_mandatory_documents_exist:
    • Verifica la existencia física en disco de los 6 tutoriales, las 5 guías de integración, el troubleshooting, el README de ejemplos y el documento de auditoría.
  2. test_all_tutorial_labs_follow_canonical_pedagogical_template:
    • Valida que los 6 laboratorios contengan todas las secciones pedagógicas obligatorias.
  3. test_all_example_labs_starters_and_solutions_pass_tests:
    • Comprueba la ejecución exacta de las suites de los 6 ejemplos: verifica deliberadamente que bugfix-lab/starter falle con exit code 1 aislando la regresión en test_regression_expected_discount, y que bugfix-lab/solution junto con el resto de starters y soluciones aprueben limpiamente con exit code 0.
  4. test_documented_cli_commands_in_tutorials_match_argparse:
    • Extrae mediante regex todos los bloques de código bash en los tutoriales y valida que cada comando y subcomando invocado exista formalmente en el árbol de parsers argparse del CLI de RAPID OS.
  5. test_governance_e2e_full_lifecycle_in_temp_project:
    • Ejecuta un proceso E2E real en un directorio temporal (tempfile.TemporaryDirectory) capturando logs auténticos mediante subprocesos (base.log y tests.log) con salida y contadores reales, verificando la ingesta de evidencias, finalización de tareas y evaluación con veredicto determinista PASS.
  6. test_bugfix_lifecycle_and_gate_order_e2e:
    • Ejecuta el ciclo de vida completo de modo Bugfix en directorio temporal: valida que intentar transicionar a active antes de reconocer gate.baseline falle con RAPID1014, captura logs auténticos de baseline, reconoce gate.baseline en estado prepared, transiciona a active, implementa el fix, valida que intentar reconocer gates POST_EXECUTION antes de marcar la tarea como done falle con RAPID1014, y concluye con evaluación determinista PASS y validación íntegra.

5. Resultados de Quality Gates​

Quality GateHerramienta / ComandoResultadoEstado
Python Unit & Contract Testspython -m unittest discover tests322 tests pasados, 0 fallos, 0 errores (37.6s)✅ PASS
Docusaurus TypeScript Typesnpm run typecheck en website/0 errores TypeScript✅ PASS
Docusaurus Static Buildnpm run build en website/Compilación HTML exitosa, 0 enlaces rotos✅ PASS
Git Working Tree Hygienegit status --shortSolo archivos de docs, examples, sidebars y tests de Sprint 4✅ PASS

6. Remediación de Hallazgos PR #43​

Se resolvieron de manera exhaustiva los cuatro hallazgos técnicos identificados:

  1. P0 — Evidencia E2E auténtica: En tests/test_documentation_labs.py se eliminaron todos los textos fijos simulados (Ran 2 tests, OK). Se capturó directamente la salida de subprocess.run (incluyendo stdout, stderr, returncode y contadores reales) en base.log y tests.log, verificando su contenido antes de vincularlos como artefactos en las evidencias.
  2. P0 — Orden correcto de gates Bugfix: En docs/tutorials/bugfix-lab.md se actualizó la secuencia de ejecución para reflejar fielmente las restricciones del dominio: la compuerta gate.baseline (PRE_EXECUTION) se reconoce mientras el Run está en estado prepared antes de pasar a active (evitando RAPID1014). Posteriormente, las compuertas POST_EXECUTION (gate.tests, gate.final-verification) se reconocen tras completar la tarea contractual (T001 -> done).
  3. P1 — Regresión real en Starter Bugfix: En examples/bugfix-lab/ se separó la caracterización del defecto (test_defect_characterization, que documenta el comportamiento anómalo actual) de la prueba de regresión (test_regression_expected_discount, que falla deliberadamente comprobando la existencia genuina del error). La suite de CI en test_documentation_labs.py verifica explícitamente el fallo con exit code 1 en el starter y la aprobación limpia al 100% en la solución.
  4. P1 — JSON canónico de Antigravity: En docs/integrations/antigravity.md se limpió el bloque JSON de evidencia delegation, eliminando campos de estado interno persistido (schema_version, id, run_id) para conformar estrictamente un documento de autoría válido para rapid evidence add --input.

7. Definition of Done (DoD) Checklist​

  • Los 6 tutoriales prácticos implementados siguiendo la estructura pedagógica canónica.
  • Los 6 proyectos de ejemplo implementados con starter/, solution/, tests/ y README.md.
  • Todos los ejemplos utilizan exclusivamente Python estándar sin librerías externas.
  • Las 5 guías de integración con coding harnesses completadas con delimitación clara de responsabilidades.
  • Troubleshooting específico para laboratorios documentado en docs/troubleshooting/tutorials.md.
  • Navegación Docusaurus actualizada en website/sidebars.ts con categorías intuitivas.
  • Cero modificaciones funcionales en el runtime rapid_os/.
  • Suite de pruebas automatizadas tests/test_documentation_labs.py incorporada y aprobada al 100% (6 tests exhaustivos, 322 tests totales en repo).
  • Ciclos E2E de Feature y Bugfix validados en entorno real con veredicto determinista PASS.
  • Documento de auditoría docs/audit/sprint-4-validation.md actualizado con remediación de hallazgos.
  • Ningún secreto, API key o dato privado expuesto en documentación o código.
  • Rama docs/sprint-4-hands-on-tutorials lista para Pull Request hacia develop.