vgxness 1.13.0 → 1.14.0

package/docs/sdd-flow.es.md

@@ -0,0 +1,403 @@
+# Flujo SDD
+
+> Versión en inglés: [SDD Flow](./sdd-flow.md).
+
+> **Alcance:** este documento explica el flujo SDD completo en VGXNESS: desde una intención humana, pasando por artefactos de planeación, progreso de implementación, verificación y archivo. Es una guía práctica para operadores y acompaña a [Architecture](./architecture.md), [Safety](./safety.md), [CLI](./cli.md) y [MCP tools](./mcp.md).
+
+VGXNESS trata SDD como estado real del producto, no solo como instrucciones para agentes. Cada fase produce un artefacto guardado localmente en SQLite, y el avance entre fases se controla mediante readiness explícito y, cuando aplica, aceptación humana explícita.
+
+Las fases canónicas de SDD son:
+
+```text
+explore → proposal → spec → design → tasks → apply-progress → verify → archive
+```
+
+## Modelo mental
+
+```text
+Intención humana
+  ↓
+Conversación en OpenCode / acción del operador por CLI
+  ↓
+Superficie VGXNESS MCP o CLI
+  ↓
+Servicios del control plane
+  ↓
+Artefactos SDD, runs, memoria y checkpoints en SQLite
+```
+
+La separación importante es:
+
+```text
+Conversación ≠ estado
+Draft ≠ aceptación
+Plan ≠ ejecución
+Preflight ≠ permiso automático
+Provider status ≠ escritura de config del provider
+CLI/MCP ≠ reglas de negocio duplicadas
+```
+
+## 1. Intención humana
+
+El flujo empieza cuando el humano expresa un objetivo, normalmente dentro de OpenCode después de instalar el MCP de VGXNESS.
+
+Ejemplo:
+
+```text
+Mejorar el flujo de recuperación de runs interrumpidos para que VGXNESS sugiera cómo continuar de forma segura.
+```
+
+Para cambios sustanciales, VGXNESS no debería saltar directo al código. El camino seguro es inspeccionar el estado SDD actual y elegir la siguiente fase válida.
+
+Superficies útiles:
+
+```text
+sdd_status
+sdd_next
+sdd_continue
+agent_resolve
+agent_activate
+```
+
+Equivalentes por CLI para setup, diagnóstico, recuperación y scripting:
+
+```bash
+vgxness sdd status --project <project> --change <change>
+vgxness sdd next --project <project> --change <change>
+vgxness sdd continue --project <project> --change <change>
+```
+
+## 2. `explore`: entender antes de elegir solución
+
+Objetivo: investigar el problema, los límites actuales del código, decisiones previas, riesgos y posibles enfoques sin comprometerse todavía con una implementación.
+
+Preguntas típicas:
+
+- ¿Dónde vive la lógica relevante?
+- ¿Qué herramientas CLI y MCP ya existen?
+- ¿Qué servicio es dueño de la regla de dominio?
+- ¿Qué restricciones de safety o storage aplican?
+- ¿Qué riesgos harían difícil revisar el cambio?
+
+Para recuperación de runs interrumpidos, la exploración podría revisar:
+
+```text
+src/runs/*
+src/sdd/*
+src/mcp/control-plane.ts
+src/cli/commands/*
+docs/*
+test/*
+```
+
+El artefacto de fase se guarda con el topic key canónico:
+
+```text
+sdd/{change}/explore
+```
+
+Un agente puede marcar el artefacto como ready, pero readiness no es aceptación.
+
+## 3. Aceptación humana de `explore`
+
+VGXNESS separa deliberadamente contenido generado y aprobación humana:
+
+```text
+draft / ready ≠ accepted
+```
+
+Solo una decisión humana de aceptación debería avanzar trabajo posterior que esté gobernado por gates. Esto evita que un agente apruebe silenciosamente su propia dirección.
+
+Ejemplo CLI:
+
+```bash
+vgxness sdd accept-artifact --project <project> --change <change> --phase explore
+```
+
+## 4. `proposal`: elegir dirección de producto
+
+Objetivo: definir qué cambio debe hacerse y por qué.
+
+Una buena propuesta responde:
+
+- ¿Qué problema estamos resolviendo?
+- ¿Quién se beneficia?
+- ¿Qué está dentro del alcance?
+- ¿Qué queda explícitamente fuera del alcance?
+- ¿Qué riesgos o tradeoffs existen?
+- ¿Cómo sabremos que funcionó?
+
+Ejemplo de resumen de propuesta:
+
+```text
+Agregar una superficie read-only de continuación para runs interrumpidos que combine runs failed/blocked/needs-human, el último checkpoint, la fase SDD asociada y una siguiente acción recomendada segura.
+```
+
+Esto sigue siendo definición de dirección, no implementación.
+
+## 5. Aceptación humana de `proposal`
+
+La propuesta es el contrato principal de alcance. Si es demasiado amplia, la implementación y la revisión se vuelven riesgosas.
+
+Pregunta recomendada para revisión:
+
+```text
+¿Esto puede revisarse como un slice coherente o deberíamos dividirlo?
+```
+
+Por ejemplo, un primer slice más seguro puede ser:
+
+```text
+Diagnóstico read-only de runs interrumpidos antes de cualquier recuperación automática o ejecución de provider.
+```
+
+Después de aceptar exactamente la propuesta, se pueden generar borradores downstream de planeación, pero esos artefactos siguen siendo drafts hasta que se revisen y acepten según la gobernanza.
+
+## 6. `spec`: definir comportamiento observable
+
+Objetivo: especificar qué debe hacer el sistema sin sobreadaptarse a detalles de implementación.
+
+Para recuperación de runs interrumpidos, una spec podría requerir:
+
+- Runs con estado `failed`, `blocked` o `needs-human` aparecen como candidatos de recuperación.
+- Cada candidato incluye run id, proyecto, workflow, fase, estado, último checkpoint, razón de fallo o bloqueo y siguiente acción recomendada.
+- El estado vacío es explícito cuando no existen runs interrumpidos.
+- La superficie es read-only y no reanuda providers ni muta estado de runs.
+
+La spec debe incluir casos límite, por ejemplo:
+
+- muchos runs interrumpidos;
+- runs sin checkpoints;
+- runs de otro proyecto;
+- runs ligados a fases SDD ya aceptadas;
+- metadata incompleta o inconsistente.
+
+## 7. `design`: decidir cómo construirlo
+
+Objetivo: conectar la spec con la arquitectura existente.
+
+Un buen diseño identifica:
+
+- límites de servicio;
+- cambios de repository/query;
+- superficies CLI y MCP;
+- agregados de schema;
+- comportamiento de renderers;
+- tests;
+- necesidad de migraciones, si aplica;
+- invariantes de safety.
+
+Ejemplo de diseño:
+
+```text
+Agregar un servicio de candidatos de resume respaldado por el repositorio de runs.
+Exponer herramientas MCP read-only para listar e inspeccionar candidatos.
+Exponer un comando CLI de recuperación/status que use el mismo servicio.
+Mantener la generación de recomendaciones como no-mutante.
+```
+
+Reglas arquitectónicas que preservar:
+
+- CLI y MCP deben compartir servicios de dominio.
+- Los renderers no deben reimplementar reglas de negocio.
+- Las herramientas read-only deben seguir siendo no-mutantes.
+- Las escrituras de configuración de provider requieren consentimiento humano explícito.
+- Los artefactos SDD siguen respaldados por SQLite; no crear `openspec/`.
+
+## 8. `tasks`: hacer el diseño revisable
+
+Objetivo: dividir el diseño en pasos pequeños de implementación.
+
+Ejemplo de desglose:
+
+```text
+1. Agregar query de repositorio para runs interrumpidos.
+2. Agregar servicio de candidatos de resume.
+3. Agregar schema MCP y herramientas read-only.
+4. Agregar comando CLI o extender la superficie existente de recovery/status.
+5. Agregar salida de renderer para estados vacío, único candidato y múltiples candidatos.
+6. Agregar tests enfocados de servicio.
+7. Agregar tests de contrato CLI/MCP.
+8. Actualizar docs si cambia comportamiento visible para el usuario.
+```
+
+Buenas tasks son pequeñas, testeables y fáciles de revisar.
+
+## 9. `apply-progress`: implementar con progreso trazable
+
+Objetivo: hacer el cambio de código mientras se registra qué cambió, qué falta y qué evidencia existe.
+
+Antes de implementar, revisar tamaño y riesgo:
+
+- ¿El cambio toca varios subsistemas?
+- ¿Altera storage o migraciones?
+- ¿Cambia schemas MCP?
+- ¿Cambia comportamiento de safety?
+- ¿El diff es demasiado grande para una sola revisión?
+
+Si el cambio es demasiado amplio, hay que dividirlo antes de implementar.
+
+Durante la implementación, `apply-progress` debería capturar:
+
+- trabajo completado;
+- archivos o módulos modificados;
+- tareas pendientes;
+- resultados de tests;
+- blockers conocidos;
+- desviaciones del diseño aceptado.
+
+`apply-progress` es un registro de progreso, no prueba de que la implementación sea correcta.
+
+## 10. Preflight para operaciones riesgosas
+
+VGXNESS usa preflight checks para mantener explícitas las operaciones riesgosas.
+
+Ejemplos de categorías riesgosas:
+
+```text
+implementation-edit
+shell
+test-run
+install
+git-write
+provider-tool
+secrets
+external-directory
+```
+
+Ejemplo conceptual MCP:
+
+```text
+run_preflight({
+  category: "test-run",
+  operation: "bun run verify:test",
+  workflow: "sdd",
+  phase: "apply-progress"
+})
+```
+
+Preflight es control consultivo/de planeación. No significa que la operación esté automáticamente aprobada o ejecutada.
+
+## 11. `verify`: comprobar la implementación independientemente
+
+Objetivo: verificar la implementación contra la spec y el design aceptados, idealmente con contexto fresco de revisor/agente para cambios no triviales.
+
+La verificación debe revisar:
+
+- que la spec se cumpla;
+- que los límites del diseño se respeten o las desviaciones estén justificadas;
+- que los tests relevantes pasen;
+- que superficies read-only no se hayan vuelto mutantes;
+- que setup/config de providers sigan requiriendo consentimiento explícito;
+- que storage, CLI y MCP sigan siendo consistentes.
+
+Comandos típicos de verificación del repo:
+
+```bash
+bun run verify:typecheck
+bun run verify:test
+bun run verify:bun-sqlite
+bun run package:bun:evidence
+```
+
+No todo cambio pequeño de docs o copy necesita la suite completa. Cambios de storage, schema CLI/MCP, setup de providers o packaging merecen verificación más estricta.
+
+## 12. `archive`: cerrar el cambio con contexto durable
+
+Objetivo: preservar qué ocurrió para que trabajo futuro pueda recuperar contexto sin releer todo el hilo o diff.
+
+Un artefacto de archive debería incluir:
+
+- resultado final;
+- comportamiento visible que cambió;
+- archivos o módulos clave tocados;
+- verificación realizada;
+- riesgos residuales;
+- trabajo de seguimiento;
+- notas de rollback o recuperación, si aplica.
+
+Ejemplo de resumen archive:
+
+```text
+Change: recover-runs
+Outcome: implemented a read-only interrupted-run recovery surface.
+Verification: typecheck and focused service/CLI tests passed.
+Residual risk: full package evidence was not run locally.
+Follow-up: consider TUI integration after the CLI/MCP flow stabilizes.
+```
+
+## Boceto del flujo de herramientas
+
+Dentro de OpenCode, el flujo normalmente se ve así conceptualmente:
+
+```text
+sdd_status
+  ↓
+sdd_continue
+  ↓
+agent_activate(explore)
+  ↓
+sdd_save_artifact(explore)
+  ↓
+sdd_ready(explore)
+  ↓
+humano acepta explore
+  ↓
+agent_activate(proposal)
+  ↓
+sdd_save_artifact(proposal)
+  ↓
+sdd_ready(proposal)
+  ↓
+humano acepta proposal
+  ↓
+agent_activate(spec)
+  ↓
+agent_activate(design)
+  ↓
+agent_activate(tasks)
+  ↓
+humano revisa/acepta artefactos con gate
+  ↓
+agent_activate(apply)
+  ↓
+run_preflight(...)
+  ↓
+sdd_save_artifact(apply-progress)
+  ↓
+agent_activate(verify)
+  ↓
+sdd_save_artifact(verify)
+  ↓
+archive
+```
+
+## Por qué existe este flujo
+
+Un flujo agentic ingenuo sería:
+
+```text
+leer código → editar código → correr tests → decir terminado
+```
+
+VGXNESS usa SDD para hacerlo más seguro:
+
+```text
+entender objetivo
+  ↓
+elegir alcance
+  ↓
+especificar comportamiento
+  ↓
+diseñar el cambio
+  ↓
+dividir en tareas
+  ↓
+implementar con preflight y tracking de progreso
+  ↓
+verificar independientemente
+  ↓
+archivar contexto durable
+```
+
+La estructura inicial cuesta un poco de tiempo, pero reduce scope creep oculto, diffs imposibles de revisar, automatización insegura y pérdida de contexto.