robcsaszar/crucible

¿Qué hace crucible?

Reconocimiento paralelo por dominio → revisión adversarial → planificar → verificar → SPEC → implementar → PR.

Regla de Propiedad de Archivos

Los subagentes NUNCA escriben archivos. Devuelven resultados como texto. Tú (el orquestador) escribes cada artefacto. Los archivos son el mecanismo de transferencia entre fases — la memoria del subagente no lo es.

Configuración

Analiza la invocación para:

• Dominios (requerido) — áreas visibles para el usuario que auditar, por ejemplo, player, curator
• Indicación de alcance (opcional) — enfoque reducido dentro de un dominio, por ejemplo, lobby SSE, role selection

Determina el directorio de salida: .crucible/run-<N>/ donde N es el siguiente entero no utilizado.

Verificación de ejecuciones anteriores: escanea .crucible/ en busca de directorios de ejecución existentes. Lee cada findings.json. Introduce sus IDs confirmados como lista de omisión en los agentes de la Fase 1 — no redescubras problemas fijos conocidos; enfoca el esfuerzo en las brechas.

Archivos escritos en esta ejecución (todos por el orquestador):

Archivo	Fase	Función
codebase-map.md	1	Contexto inyectado textualmente en todos los agentes posteriores
recon-<domain>.json	1	Hallazgos brutos por dominio
findings.json	1→2→4	Hallazgos combinados; veredictos añadidos en cada fase
PLAN.md	3	Plan de corrección priorizado
SPEC.md	5	Código antes/después + casos de prueba por cada hallazgo

Fase 1 — Reconocimiento

LECTURA OBLIGATORIA de references/recon-phase.md antes de lanzar agentes.

Lanza un agente de investigación por cada dominio declarado, todos en paralelo. Alimenta a cada uno con: ruta del código base, nombre del dominio, indicación de alcance (si existe), IDs conocidos previos a omitir.

Los agentes devuelven texto JSON. Si un agente devuelve prosa en lugar de un arreglo JSON, vuelve a preguntar una vez con la forma exacta del esquema de assets/findings-schema.json. Si falla de nuevo, escribe un recon-<domain>.json vacío ([]) y anota la falla en codebase-map.md. Continúa — un dominio que falla es recuperable; no abortes la ejecución.

Recopila las respuestas válidas, luego:

1. Escribe recon-<domain>.json por cada respuesta del agente
2. Sintetiza codebase-map.md — rutas de archivos clave, límites de dominio, módulos compartidos, convenciones
3. Combina todos los hallazgos de dominio en findings.json

Criterio de finalización: cada dominio tiene un recon-<domain>.json, se ha escrito codebase-map.md, se ha escrito findings.json. NO cargues references/adversarial-phase.md hasta la Fase 2.

Fase 2 — Revisión Adversarial

LECTURA OBLIGATORIA de references/adversarial-phase.md antes de lanzar agentes.

Lanza un agente general por cada hallazgo (agrupando hallazgos del mismo dominio). Cada agente recibe el JSON del hallazgo y codebase-map.md — NO el razonamiento del agente de reconocimiento. El límite de independencia es la puerta de calidad.

Los agentes devuelven CONFIRMADO / RECHAZADO / REBAJADO con evidencia de código. Añade cada veredicto a la entrada correspondiente en findings.json. Ejecuta node scripts/validate-findings.cjs findings.json — corrige cualquier error de esquema antes de la Fase 3.

Cuando el validador no puede ejecutarse — node no está en el PATH, el script o su esquema faltan, un error de uso, o cualquier fallo antes de que comience la validación (Failed to load schema, Failed to parse JSON) — esto no es un pase. Anota ⚠ hallazgos no validados — validador no disponible: <razón> en la salida de hallazgos y al inicio del traspaso de SPEC, luego continúa. Un rechazo de esquema es el caso opuesto y siempre bloquea: corrige los hallazgos, vuelve a ejecutar, no continúes tras un rechazo. Ambos actualmente salen con 1, así que lee el texto del error, no el código de salida.

Criterio de finalización: cada hallazgo tiene un campo adversarial_verdict. La validación del esquema pasa. NO vuelvas a cargar references/recon-phase.md a partir de este punto.

Fase 3 — Síntesis del Plan

Verificación de cero hallazgos: antes de sintetizar, cuenta las entradas confirmadas y rebajadas en findings.json. Si es cero, escribe .crucible/run-<N>/REPORT.md con la única línea "No se encontraron hallazgos procesables tras la revisión adversarial." Detente — no abras un PR.

Sintetiza los hallazgos confirmados y rebajados de findings.json en PLAN.md:

• P1 (crítico/alto): flujos principales rotos, pérdida de datos, desconexión permanente
• P2 (medio): errores visibles para el usuario, rutas de recuperación faltantes
• P3 (bajo): pulido, desviación en documentación, problemas de texto

Agrupa los hallazgos que comparten una causa raíz — una corrección puede eliminar varios. Al agrupar: la severidad más alta entre los hallazgos agrupados establece la prioridad del grupo. Si los hallazgos agrupados tienen enfoques de corrección conflictivos, divídelos — una causa raíz compartida no requiere una corrección compartida. Declara el orden de corrección donde existan dependencias. Los hallazgos rechazados se excluyen por completo.

Criterio de finalización: se ha escrito PLAN.md; cada hallazgo confirmado aparece exactamente una vez.

Fase 4 — Verificación Independiente

Lanza un agente de investigación por cada hallazgo P1 + P2, todos en paralelo. A cada agente se le dice: "NO escribiste este hallazgo. Verifica cada afirmación fáctica contra el código fuente actual."

Cada agente comprueba: el archivo existe en la ruta, el número de línea coincide con el código descrito, el nombre del ámbito es correcto, el patrón descrito realmente aparece. Devuelve VERIFICADO / CORREGIDO [campo: incorrecto → correcto] / RECHAZADO [razón].

Aplica todas las correcciones a PLAN.md y findings.json. Ejecuta la validación del esquema de nuevo. PLAN.md y findings.json deben concordar — sin discrepancia entre los entregables.

Criterio de finalización: todos los hallazgos P1+P2 verificados. Todas las correcciones aplicadas. El esquema pasa.

Fase 5 — SPEC

Escribe SPEC.md con una sección por cada hallazgo confirmado (orden P1 → P2 → P3):

• Ruta exacta del archivo + rango de líneas (verificado)
• Código anterior (fuente real, no pseudocódigo)
• Código posterior (corrección concreta)
• Casos de prueba: una frase por cada comportamiento que la prueba debe verificar

Ejecuta node scripts/validate-findings.cjs findings.json como comprobación final.

Criterio de finalización: cada entrada de PLAN.md tiene una sección en SPEC. La validación pasa.

Fase 6 — Traspaso

1. Actualiza la documentación de flujos (docs/flows/) para cualquier hallazgo que cambie un comportamiento visible para el usuario
2. Invoca la habilidad implement con SPEC.md
3. Abre un PR — esta es la puerta de revisión humana; no se solicita aprobación intermedia

Cuerpo del PR: enlace a PLAN.md, recuento de hallazgos por severidad, enlace a SPEC.md, lista de documentos de flujo actualizados.

NUNCA

• NUNCA pidas a un subagente que escriba un archivo En su lugar: Haz que el agente devuelva el contenido como texto; escribe el archivo tú mismo. Por qué: El estado entre fases reside en los archivos. Si un agente escribe directamente, el orquestador pierde la copia canónica y no puede conciliar los entregables después de las correcciones de la Fase 4.

• NUNCA des a un agente adversarial la cadena de razonamiento del agente de reconocimiento En su lugar: Pasa solo el hallazgo estructurado (JSON) y codebase-map.md. Por qué: Ver la lógica del agente de reconocimiento ancla al agente adversarial a los mismos supuestos — el límite de independencia es lo que elimina los falsos positivos.

• NUNCA avances más allá de la Fase 2 con fallos de validación del esquema En su lugar: Corrige los campos que fallan en findings.json antes de sintetizar el plan. Por qué: Un PLAN construido sobre hallazgos malformados produce una SPEC con rutas de archivo y números de línea incorrectos que la habilidad de implementación no puede usar.

• NUNCA escribas SPEC.md mientras algún hallazgo P1/P2 tenga verification: "pending" En su lugar: Ejecuta node scripts/validate-findings.cjs findings.json --pre-spec y resuelve todos los fallos antes de la Fase 5. Por qué: La protección --pre-spec existe en el script validador pero es invisible a menos que se invoque — un agente que omita esta llamada generará una SPEC con rutas de archivo no verificadas y pasará silenciosamente números de línea incorrectos a la implementación.