Converge - Retroescritura de Especificación tras QA

¿Qué hace Converge - Retroescritura de Especificación tras QA?

Cierra el bucle de ejecución: una tarea que pasó QA se convierte en parte de la especificación viva. Este skill representa el rol ConvergeTool en el ciclo de vida. Define el proceso; las reglas del agente del repositorio aún poseen los permisos, y este skill nunca otorga acceso adicional.

Posición en el pipeline: dev -> qa -> converge -> paquete archivado + especificación actualizada.

Usar cuando

• El archivo 03-qa-verification.md de un paquete de tarea registra un veredicto QA_PASSED verificado.
• 02-dev-workspace.md contiene la tabla congelada de Desviaciones de Implementación (filas o una fila explícita de None).
• El comportamiento confirmado de la tarea debe ser plegado en .specs/02-tech-spec.md, el paquete archivado y la propuesta de cambio original cerrada.

No usar cuando

• La implementación o QA aún están en ejecución, el marcador de transferencia no está verificado, o REWORK_REQUIRED está activo: espera un veredicto QA_PASSED estable.
• El registro de desviaciones está en blanco o falta: envía la tarea de vuelta a Dev en lugar de adivinar.
• Tendrías que inventar contenido de la especificación o reescribir prosa existente de la especificación; eso es un cambio de planificación, no una convergencia.

Entradas

• tasks/<task-id>/01-contract.md - título, anclajes de trazabilidad, change_id opcional.
• tasks/<task-id>/02-dev-workspace.md - la tabla de Desviaciones de Implementación (formato congelado).
• tasks/<task-id>/03-qa-verification.md - el veredicto QA_PASSED verificado y la evidencia.
• tasks/<task-id>/04-process.md - tarjeta de estado derivada y registro de eventos.
• .specs/02-tech-spec.md - la especificación técnica viva.
• .specs/changes/<change-id>/proposal.md - la propuesta de cambio original, cuando existe.

Salidas

• Una entrada por tarea, fechada y atribuida, dentro de la sección Cambios convergidos de la especificación.
• Un marcador de convergencia por tarea: <!-- converged: <task-id> sha256:<hash> -->.
• 04-process.md con macro_status: "CONVERGED" y una fila de evento TASK_CONVERGED (actor ConvergeTool).
• El paquete de la tarea movido (nunca eliminado) a tasks/archive/<task-id>/.
• .specs/changes/<change-id>/convergence.md más el estado de la propuesta archived, cuando existe una propuesta.

Verificar -> aplicar -> verificar

1. Verificar. Clasifica los paquetes antes de escribir cualquier cosa: python .agents/skills/converge/scripts/converge.py check --tasks-dir ./tasks --json Un paquete está listo para converger solo cuando QA ha pasado, no hay retrabajo activo, la tabla de desviaciones tiene al menos una fila o una fila explícita de None, y la especificación aún no tiene su marcador.
2. Aplicar. Convierge un paquete: python .agents/skills/converge/scripts/converge.py apply --task tasks/<task-id> Usa --dry-run primero para inspeccionar las escrituras planeadas. El ayudante se niega con código de salida 1 cuando el paquete no está listo para converger, y rechaza un destino de archivo existente a menos que se use --force.
3. Verificar. Vuelve a ejecutar check, confirma que el marcador esté presente, que 04-process.md diga CONVERGED, que el paquete esté archivado, y que --spec-sha256 coincida con el valor CI esperado: python .agents/skills/converge/scripts/converge.py --spec .specs/02-tech-spec.md --spec-sha256

Respaldo manual (sin Python)

Cuando el ayudante no esté disponible, realiza los mismos pasos manualmente y mantén los marcadores exactos:

1. Confirma que QA_PASSED esté verificado en 03 y que no haya REWORK_REQUIRED activo.
2. Lee las filas de desviación de 02; rechaza un registro en blanco.
3. Agrega (no edites) una entrada a la sección Cambios convergidos de la especificación: un encabezado ### <task-id>, la tabla de desviaciones, y el marcador <!-- converged: <task-id> sha256:<hash> -->. Calcula el hash con cualquier herramienta SHA-256 sobre el ID de tarea normalizado y las filas.
4. Establece macro_status a CONVERGED en 04 y agrega la fila TASK_CONVERGED / ConvergeTool.
5. Mueve, nunca elimines, el paquete a tasks/archive/<task-id>/; archiva la propuesta y escribe convergence.md cuando exista una propuesta de cambio.
6. Vuelve a ejecutar el paso de verificación y registra la evidencia.

Condiciones de rechazo

Detente e informa en lugar de converger cuando cualquiera de estas sea verdadera:

• QA no aprobado - 03 no tiene QA_PASSED verificado, o REWORK_REQUIRED aún está activo.
• Retrabajo no resuelto - la evidencia de reintento muestra que la tarea está en medio de retrabajo; espera un nuevo veredicto.
• Registro de desviaciones en blanco - la tabla de Desviaciones de Implementación falta o no tiene ninguna fila DEV y ninguna fila explícita de None.
• Deriva de especificación - una desviación de modify/remove apunta a un anclaje #sec-* que la especificación no contiene; la especificación y el registro de desviaciones discrepan. Ejecuta check/apply con --strict en CI para convertir esta advertencia en un rechazo.
• Colisión de archivo - tasks/archive/<task-id>/ ya existe y no se dio --force.

Las desviaciones estructurales (nuevos módulos, límites cambiados, nuevas decisiones a nivel ADR) deben escalar a spec-generator; nunca se convergen silenciosamente.

Historial y atribución

La convergencia nunca reescribe el historial: agrega una sección fechada y atribuida en lugar de editar la prosa existente de la especificación. Las entradas existentes permanecen byte por byte estables, y cada entrada nombra la tarea fuente, el veredicto QA y el actor ConvergeTool. Nunca edites una entrada de convergencia antigua para que encaje una nueva tarea; agrega una nueva entrada y registra el conflicto.

Referencias

• references/convergence-protocol.md - máquina de estados, quién escribe qué, diseño del archivo, marcadores de idempotencia, reglas de conflicto y escalación estructural.
• Límites de roles: references/role-boundaries.md — alcance de escritura, invariantes y el modelo de cumplimiento honesto (empaquetado; no se necesitan archivos externos).
• Formato del paquete de tarea y ciclo de vida de roles: skill task-decomposition (cuando esté instalado).
• Entrada de transferencia: skill dev; entrada de veredicto: skill qa.
• Reglas del repositorio: lee AGENTS.md y cualquier archivo de reglas de roles cuando el proyecto adoptante los defina; pueden agregar requisitos pero no son necesarios para este skill.

Límites honestos

Este skill no otorga acceso de escritura y no puede hacer cumplir el aislamiento de roles. Donde el repositorio tenga CI (por ejemplo, una auditoría de roles basada en git) o protección de ramas, esa es la capa autoritaria. El ayudante empaquetado es un asistente determinista opcional; los marcadores y la evidencia escrita son el contrato.