Forge — Spec-Driven Development con compuertas de calidad

Forge es el workflow que impide que la IA salte directo al código. En lugar de “haz X”, le pides a la IA que siga un loop de cinco fases con compuertas de aprobación humana explícitas. El estado de cada fase se persiste en el Vault, y los checkpoints de calidad impiden que la IA avance más allá de Apply o Verify sin cumplir tus criterios.

Cuándo aplicar el workflow completo

• Features o módulos nuevos
• Cambios en APIs públicas o interfaces
• Refactors que cruzan múltiples capas
• Cualquier cosa que toque la capa de dominio

Para fixes pequeños solo necesitas la Fase 1 y la Fase 4.

Las cinco fases

Fase 1 — Exploración

Objetivo: entender el código y juntar contexto. Sin proponer.

La IA lee los archivos relevantes, ejecuta vault_search e identifica patrones existentes, dependencias, deuda técnica y restricciones (capas, adapters, librerías compartidas).

Output: un análisis breve — Found · Impact · Debt · Vault context.

Reglas: SIN proponer · SIN escribir código · UNA pregunta enfocada permitida si hay ambigüedad.

Fase 2 — Especificación ✋ Requiere aprobación del developer

Objetivo: definir exactamente qué se va a construir, en términos que el developer pueda aprobar.

Output (formato obligatorio):

## Spec: [nombre del feature]
**Objective:** una frase
**Inputs:** paramName: type — descripción
**Outputs:** returnType — descripción
**Business Rules/Constraints:** lista numerada
**Affects:** archivos y cambios

Reglas: STOP al final · esperar aprobación explícita · sin código · sin diseño · si hay múltiples specs viables, presentar como máximo 3 opciones.

Fase 3 — Diseño ✋ Requiere aprobación del developer

Pre-acciones: vault_context para cargar patrones activos, vault_search "adapter pattern", vault_search "module structure".

Output:

## Technical Design: [nombre del feature]
### New files: src/.../X.ts | Layer: Domain | Exports: ClassName
### Modified files: descripción del cambio
### API contracts: endpoints + DTOs
### Cambios en inyección de dependencias
### Decisiones clave: justificación, cache keys, etc.

Reglas: STOP al final · respetar capas · cada archivo nuevo declara capa + responsabilidad · señalar conflictos con la spec aprobada antes de proceder.

Fase 4 — Implementación

Objetivo: escribir código exactamente como se diseñó en la Fase 3.

Reglas: implementar solo lo diseñado · PAUSAR y preguntar antes de añadir algo no incluido en el diseño · seguir scrolls activos · sin “agregados creativos” · sin mejoras “ya que estoy aquí” · seguir el naming exacto.

Checklist:

• ✓ Cada archivo de la Fase 3 creado/modificado
• ✓ Sin violaciones de capas
• ✓ Sin console.log en src/
• ✓ Sin any sin // korva-ignore: razón
• ✓ DTO en mayúsculas
• ✓ Nombres de archivo en kebab-case

Fase 5 — Verificación

Objetivo: confirmar que la implementación coincide con la spec. Sin código nuevo — solo validación.

Acciones:

1. Spec review (PASS/FAIL por ítem).
2. Escaneo de antipatrones — corre Sentinel.
3. Lista de tests — enumerar los tests que deberían existir (no generarlos a menos que se pida).
4. vault_save con lo aprendido.

Output:

## Verification: [nombre del feature]
### Checklist de spec
### Chequeo de antipatrones
### Tests por escribir
### Guardado en el Vault

Reglas: ser honesto sobre lo que falta · nunca PASS sobre algo incierto · siempre vault_save antes de cerrar.

Compuertas de calidad persistidas en el Vault

La tabla sdd_state trackea la fase actual por proyecto. Las transiciones apply → verify y verify → archive están bloqueadas con compuertas: requieren una llamada a vault_qa_checkpoint con gate_passed=true (score ≥ 70 + todos los criterios obligatorios pasados).

La máquina interna de nueve estados — explore → propose → spec → design → tasks → apply → verify → archive → onboard — cubre tanto las 5 fases públicas anteriores como los flujos de onboarding. Forge siempre habla las 5 fases públicas; los 9 estados internos le dan a Beacon el sustrato para auditoría.

Por qué funcionan las compuertas de aprobación humana

Los LLMs son excelentes generando código plausible. No son tan buenos notando que la spec que acaban de escribir contradice sutilmente la spec que el developer pidió. Las dos compuertas de aprobación — entre Spec y Diseño, y entre Diseño e Implementación — convierten ese desfase en una conversación de 30 segundos en lugar de una sesión de debugging de varias horas tras el PR.

Ejemplo trabajado

1. Fase 1 (Exploración)
   IA: "Leí src/payments/. Encontrado:
        Found: 3 adapters, 1 use-case, sin tests.
        Impact: cualquier cambio requiere actualizar mocks de servicio.
        Debt: PaymentService tiene 200 LOC, divisible.
        Vault context: Decisión #47 (mar 2024) — Stripe sobre Adyen.
        ¿Procedo a la Fase 2 con la spec?"

2. Fase 2 (Especificación) ✋ APROBACIÓN
   IA: "## Spec: Add refund support
        Objective: permitir reembolsos parciales y totales.
        Inputs: orderId: string, amount?: Decimal
        Outputs: RefundResult — id, amount, status
        Business Rules: 1. Solo órdenes en estado 'paid'.
                        2. Monto del refund <= original.
                        3. Idempotente por orderId.
        Affects: payment.service.ts (+método), payment.controller.ts (+endpoint)
        ¿Apruebas?"

   Developer: "✅ approved"

3. Fase 3 (Diseño) ✋ APROBACIÓN
   ...

4. Fase 4 (Implementación)
   La IA escribe exactamente el diseño. Sin "ya que estoy aquí".

5. Fase 5 (Verificación)
   La IA corre Sentinel, lista tests faltantes, hace vault_save de las lecciones aprendidas.

Layout del directorio de Forge

forge/
├── WORKFLOW.md
├── phases/
│   ├── 01-exploration.md
│   ├── 02-specification.md
│   ├── 03-design.md
│   ├── 04-implementation.md
│   └── 05-verification.md
├── hive-mock/                  → mock in-memory para tests (puerto :7438)
└── licensing-server/           → endpoints admin (handlers_admin.go)

Siguiente

• Herramientas MCP — vault_sdd_phase, vault_qa_checkpoint
• Sentinel — corre en la Fase 5
• Lore — scroll forge-sdd