Esta página es una traducción de la documentación en inglés. Los comandos, identificadores y ejemplos no cambian. Runtime 7.24.4 · SDK 2.6.7. Original en inglés

Aseguramiento de objetivos

Estado: Vigente Alcance: comprobaciones de aceptación de objetivos y frescura del código fuente Última revisión: 2026-09-14 Responsable: mantenedores del entorno de ejecución de AX Code

Los planes de cambio de código que produce el planificador de objetivos declaran comprobaciones de aceptación ejecutables. Cada comprobación nombra el resultado que cubre, su comando exacto, su propósito y el entorno previsto. AX Code registra la evidencia de ejecución cuando el agente ejecuta verify_project con el id goalCheck de la comprobación.

{ "goalCheck": "invoice-parity" }

El comando procede del plan de objetivo congelado. El agente no puede sustituirlo por un comando distinto mediante esta llamada. Los permisos de bash existentes siguen aplicándose. Completar el objetivo exige que el último intento de cada comprobación declarada pase con el objetivo, la sesión, el espacio de trabajo, el contrato y el contenido fuente coincidentes. La prosa de aceptación explica el resultado; no sustituye a las comprobaciones ejecutadas. Las ejecuciones ordinarias de shell y las comprobaciones omitidas por completo no pueden aportar esta evidencia.

Los planes de objetivo antiguos sin aseguramiento conservan sus reglas de finalización anteriores. Borra y vuelve a crear un objetivo antiguo cuando necesites el contrato nuevo; editar sus requisitos congelados en el sitio provoca un desajuste de contrato. Una bifurcación conserva el contrato, pero exige ejecuciones nuevas de las comprobaciones en la sesión nueva.

Preparar un proyecto de migración

Aporta la fuente heredada autorizada o las exportaciones con identificadores de revisión, un inventario de cobertura acotado y scripts de comprobación que fallen cuando las afirmaciones no se puedan verificar. Trata los comentarios y las implementaciones de migración anteriores como pistas que investigar. Registra los cambios de comportamiento aprobados aparte de los requisitos de paridad con lo heredado.

Elige comprobaciones para las capas que el cambio solicitado afecta de verdad:

Los scripts deben afirmar la identidad del destino antes de realizar sus comprobaciones. Guarda las credenciales en el mecanismo de credenciales ya existente del proyecto, nunca en el texto del plan, en los comandos ni en las descripciones del destino. Una comprobación debe devolver un código de salida distinto de cero ante una afirmación fallida, un entorno ausente o una afirmación exigida que se haya omitido. Evita envoltorios que oculten fallos. AX Code no puede inferir afirmaciones a partir de una salida de proceso correcta.

En migraciones grandes, organiza el trabajo en lotes acotados de flujo de negocio y mantén un inventario que enlace formularios, dependencias, referencias heredadas y comprobaciones de aceptación. Informa tanto del lote aceptado como de la cobertura restante. Superar un lote no completa toda la migración.

Qué registra un plan

El planificador aporta un objeto assurance. Este fragmento ilustrativo supone que el proyecto tiene la exportación de fuente y el script de comprobación a los que se hace referencia:

{
  "version": 1,
  "sourcePaths": ["src", "checks", "package.json"],
  "sources": [
    { "role": "legacy", "reference": "legacy/invoice-schema.sql at export-v1" },
    { "role": "requirement", "reference": "Invoice acceptance criteria supplied by the user" }
  ],
  "checks": [
    {
      "id": "invoice-parity",
      "acceptanceIds": ["AC1"],
      "command": "node checks/invoice-parity.cjs",
      "purpose": "Assert invoice behavior, database mappings and target identity",
      "environment": "Staging migration target, schema ERP"
    }
  ]
}

Todos los id de aceptación deben estar cubiertos. Los comandos se ejecutan desde la raíz del espacio de trabajo. El objeto de aseguramiento se congela con el contrato de aceptación. El agente recibe el alcance validado, las referencias de fuente, los id de comprobación y los destinos declarados en su contexto de objetivo en curso. Los contratos ausentes o alterados producen un aviso de restauración. Los resúmenes de conversación generados siguen siendo falibles; las referencias declaradas y las etiquetas de destino son requisitos, no hechos observados de forma independiente.

Los rangos de Git que miden lo que cambió este objetivo deben usar {BASELINE} como estado anterior. El planificador reescribe ese marcador al SHA de HEAD capturado cuando se envía el plan, de modo que los commits ya existentes por delante de origin/main o un árbol de trabajo sucio no puedan hacer que el objetivo sea incompletable. Las referencias de seguimiento remoto (origin/main, @{u}, refs/remotes/…) se rechazan como ese estado anterior salvo que el objetivo nombre el remoto. Registra las rutas ya divergentes o sucias bajo Riesgos; no congeles una comprobación de paso que ya esté fallando salvo que el objetivo sea corregir ese fallo.

Frescura y límites

Las huellas de fuente de Git incluyen los bytes reales de los archivos rastreados y de los no rastreados no ignorados dentro del sourcePaths declarado. Las rutas de archivo explícitas también incluyen archivos de configuración ignorados; las rutas de directorio conservan las reglas de ignorar de Git. Las listas de comprobación mutables del plan de objetivo quedan excluidas; sus requisitos congelados se comprueban mediante el resumen del contrato. Los proyectos que no son de Git toman la huella de forma recursiva de los sourcePaths declarados, incluidas las rutas ausentes. Incluye en ese alcance cada fuente relevante, cada archivo de configuración y cada script de comprobación.

La toma de huellas se limita a 20,000 entradas y 128 MiB de contenido de archivo. Una fuente enlazada, repositorios Git anidados, archivos especiales, rutas que escapan, archivos que cambian y lecturas no disponibles no pueden producir evidencia fresca. Esos fallos bloquean la finalización asegurada. Los artefactos de salida de las comprobaciones deben ir a una ubicación ignorada para que generar un informe no cambie la fuente que se verifica.

Los archivos ignorados que no se nombran de forma explícita, las dependencias fuera del alcance de la fuente, las bases de datos y los despliegues necesitan afirmaciones en el comando del proyecto. Un recibo registra una observación en el momento de su ejecución; no demuestra que el estado externo haya permanecido igual. Vuelve a ejecutar las comprobaciones afectadas después de cambiar la configuración, las bases de datos o los despliegues. AX Code no descubre de forma automática todo el comportamiento heredado ni certifica la paridad de la migración.

Cuándo se ejecuta la planificación

La planificación es optativa en ambas superficies. /goal <objective> y create_goal sin assure inician el objetivo de inmediato: no lleva criterios de aceptación congelados, y la finalización se juzga por el plan de trabajo (tareas pendientes) más una verificación superada después del último cambio. /goal --assure <objective> y create_goal con assure: true ejecutan primero el redactor del plan, que es lo que convierte los recibos de comprobación ejecutada de abajo en un requisito de finalización.

Un objetivo sin contrato lo dice allí donde se muestra (/goal view, el diálogo del objetivo, los mensajes de control), así que su compuerta de finalización nunca es algo que tengas que inferir. /goal replace conserva el aseguramiento cuando el objetivo que se sustituye tiene un contrato válido.

Contexto de planificación y selección de modelo

La planificación de objetivos hereda el modelo de sesión seleccionado tanto mediante /goal como mediante la herramienta create_goal. Se conservan las variantes compatibles de quien llama. El redactor de solo lectura recibe los requisitos originales recientes del usuario y las referencias de adjuntos, con un presupuesto de registro de 16 KiB. Un registro demasiado grande detiene la inclusión de registros más antiguos, con un aviso, para que los requisitos antiguos no puedan sustituir en silencio una corrección omitida; el contenido multimedia en línea no se trata como evidencia inspeccionada. Aporta archivos de fuente inspeccionables para los requisitos que solo están presentes en medios.

Progreso y bloqueos

get_goal incluye el estado actual de las comprobaciones (superada, fallida, obsoleta, en ejecución o ausente) y los ID recientes de evidencia de herramientas. La compuerta de finalización sigue exigiendo recibos correctos y vigentes. Una actualización bloqueada exige un tipo de bloqueo, un motivo, el cambio externo requerido, los ID de evidencia originales y la confirmación de que no queda trabajo independiente. Los motivos de bloqueo son declaraciones del modelo respaldadas por registros inspeccionables, no una certificación de que un servicio externo siga no disponible.

Los turnos terminados que, de forma repetida, no producen evidencia nueva y correcta de herramientas reciben orientación de recuperación y luego pausan el objetivo con el trabajo inacabado a la vista. Los resultados nuevos de investigación pueden contar sin ediciones de fuente; reescribir tareas pendientes y repetir resultados idénticos no cuenta. Es una heurística acotada, no una prueba de progreso semántico. /goal resume inicia otro intento. Las llamadas a herramientas generadas para un objetivo anterior no pueden terminar su sustituto. Un objetivo creado por una herramienta queda disponible para actualizaciones de estado después de que el modelo haya recibido el resultado de la creación en su paso siguiente.

Revisar un plan existente

Usa /goal revise <correction> para revisar de forma explícita un objetivo congelado activo, en pausa o bloqueado. El trabajo completado y los presupuestos agotados exigen un objetivo nuevo. El plan anterior y el resumen permanecen intactos. El plan revisado obtiene una identidad nueva y un registro local de revisión preparada que enlaza ambos resúmenes y la corrección. La identidad actual del objetivo determina qué candidato se instaló de verdad; los candidatos concurrentes fallidos pueden permanecer en disco para inspección. Los recibos antiguos permanecen en el historial y no pueden satisfacer la revisión nueva. El presupuesto de tokens y el uso acumulado se arrastran; la revisión no concede un presupuesto de gasto nuevo.

La revisión cancela la ejecución actual y pausa el objetivo mientras prepara el plan nuevo. Si la planificación falla, el contrato anterior sigue siendo reanudable; un objetivo que ya estaba bloqueado conserva ese estado. Una pausa o cancelación del usuario durante la planificación impide la activación. Una sustitución concurrente impide que el candidato tome el control. Las herramientas del modelo no pueden revisar en silencio los requisitos congelados. Revisa el plan resultante y sus criterios de aceptación; un comando ejecutable por sí solo no establece que sus afirmaciones cubran la solicitud corregida.

Resultados de revisión y cambios posteriores del código

Un registro de revisión no vacío no establece que la revisión haya tenido éxito. Para revisores externos exigidos, usa una comprobación propiedad del proyecto que valide el código de salida real, la finalización en la terminal, la identidad de la fuente o del diff, y los hallazgos finales o un veredicto explícito de ausencia de hallazgos. Los registros solo de avisos, el razonamiento parcial y los tiempos de espera deben fallar. Conserva los intentos fallidos aparte para el diagnóstico.

Los envíos nuevos de cambio de código rechazan las comprobaciones reconocidas de mera presencia de archivo y de inspección. Es una guarda de admisión estrecha, no una prueba semántica de comandos de shell arbitrarios. Los contratos congelados existentes conservan su esquema y su resumen; los puntos de control avisan cuando una comprobación más antigua tiene esta debilidad.

La frescura de las comprobaciones del objetivo también toma la huella de las rutas de archivo resueltas que informan las herramientas de edición de archivos correctas durante el objetivo actual, incluido cada resultado multiedit y las rutas omitidas de la lista de fuentes original. Las ediciones posteriores de esos archivos invalidan los recibos anteriores. El contrato congelado y el resumen no cambian. Este seguimiento usa metadatos del resultado de la herramienta de archivos; no infiere efectos secundarios arbitrarios del shell ni cobertura de pruebas. Siguen aplicándose los límites existentes de contención del sistema de archivos, de enlaces, de tamaño y de recuento de archivos.

La salida de las comprobaciones y los puntos de control del objetivo revelan rutas adicionales. Si un comando de prueba congelado omite regresiones necesarias, solicita /goal revise <correction> y ejecuta las comprobaciones revisadas. Incluir un archivo en una huella demuestra frescura, no que una prueba haya ejercitado ese archivo. Prefiere directorios de fuente acotados y comandos de prueba que incluyan regresiones nuevas al planificar un barrido abierto de errores.

Los alias del espacio de trabajo se normalizan para las rutas de archivo observadas. Los archivos temporales externos no se convierten en entradas de fuente del espacio de trabajo; los puntos de control revelan que el contenido externo no recibe huella. El estado externo exigido sigue necesitando una verificación propiedad del proyecto.

Evidencia del alcance del commit

Un git log <baseline>..HEAD -- <paths> no vacío solo demuestra que un commit coincide con el filtro. No excluye archivos ajenos de ese commit ni otros commits. Los planes nuevos de cambio de código rechazan las afirmaciones reconocidas e independientes de un registro de Git no vacío filtrado por ruta; las comprobaciones congeladas más antiguas reciben orientación de revisión sin cambiar su resumen ni la validación en tiempo de lectura.

Usa un verificador propiedad del proyecto que compruebe la ascendencia de la línea base, exija un rango no vacío e inspeccione cada ruta cambiada de cada commit sin filtros de ruta. Incluye los archivos eliminados y ambos lados de los renombrados, trata los commits de fusión de forma explícita y valida por separado cualquier propiedad exigida de rama o de mensaje. Usa /goal revise para reforzar un contrato existente; no edites requisitos congelados.

Tamaño del plan y reenvío completo

El plan representado, incluidos Markdown y el JSON de aseguramiento, debe caber en 8,192 bytes UTF-8. Procura quedar por debajo de 7,168 bytes. Si el envío supera el tope, acorta la prosa repetida y reenvía el objeto completo, incluidos kind y todos los campos exigidos. Conserva los id de aceptación y las comprobaciones; el entorno de ejecución no trunca requisitos ni eleva el límite del lector para aceptar un plan demasiado grande.

Recibos de revisión de animación de la CLI local

El packages/ax-code/script/verify-cli-review-receipts.ts propiedad del repositorio comprueba los artefactos round-* bajo la raíz de recibos elegida con --root. Cada ronda necesita revision.txt, y cada uno de grok, claude y codex necesita exit.txt con 0 y un veredicto final en stdout.jsonl (eventos de texto de Grok) o stdout.txt (Claude/Codex). Conserva los intentos fallidos fuera de los directorios de ronda completada; no conviertas los fallos en recibos de salida cero.

dispositions.json contiene una matriz findings. Cada entrada nombra round, cli, id, status (fixed o rejected) y evidence no vacío. Las entradas fijas exigen además un objeto regression con una ruta literal del repositorio file bajo packages/ax-code/test/cli/tui/ y el fullName exacto de Vitest. Las disposiciones duplicadas o varios veredictos ambiguos fallan.

El verificador ejecuta esos archivos con el Vitest instalado y el reintento global predeterminado en cero (las opciones de una prueba concreta pueden anular ese valor), y luego comprueba que cada afirmación referenciada haya pasado exactamente una vez. Las afirmaciones ausentes, omitidas, fallidas o ambiguas hacen fallar la verificación. Esto demuestra que esas pruebas referenciadas pasaron, no que sus afirmaciones cubran de forma semántica el hallazgo. Las disposiciones rechazadas siguen siendo juicios registrados. Una ronda final debe coincidir con el HEAD actual; los hallazgos marcados como corregidos exigen una revisión más nueva y otra ronda de revisión. Los cambios sin commit del código fuente, las pruebas o la configuración del paquete principal impiden la verificación. Mantén la configuración local ajena ax-code.json fuera de los commits.

En este repositorio, vitest run --dir test/cli/tui conserva las exclusiones del carril normal mientras explora el directorio de la TUI. Los ejecutores de grupo pueden seguir eligiendo archivos exactos con AX_TEST_FILES; elegir un directorio no desactiva las exclusiones.