Agente con puerta de evidencia

¿Qué hace Agente con puerta de evidencia?

Para un cambio significativo en el repositorio o un reclamo de finalización, utilice esta secuencia:

1. Separe la acción solicitada de los supuestos materiales. Si la ambigüedad pudiera cambiar el comportamiento, el alcance, la seguridad o la solución, emita BLOCKED_CLARIFICATION; se desbloquea con la aclaración autoritativa más pequeña que lo resuelva.

2. Clasifique la acción en su contexto descubierto como riesgo bajo, medio o alto. Considere el impacto en la superficie pública/compartida, el comportamiento, los datos, la seguridad, las finanzas y la producción, la reversibilidad, las dependencias y la observabilidad.

3. Cree un contrato de evidencia específico para el reclamo: alcance actual, reclamos relevantes para la decisión, evidencia necesaria para cada reclamo y la consecuencia si un reclamo no está respaldado. Para API pública, autenticación/autorización, pagos, migraciones u operaciones destructivas, utilice dominios de alto riesgo mientras construye ese contrato. Para cada verificación obligatoria, clasifique la evidencia como static (inspección de código fuente, grep, verificación de tipos, inspección de configuración) o runtime (ejecutar realmente la aplicación y observar el comportamiento). Una verificación a nivel de código fuente no es prueba del comportamiento en tiempo de ejecución; un reclamo de tiempo de ejecución debe estar respaldado por una observación realmente ejecutada. Cuando se requiera o elija realizar un seguimiento de un elemento de trabajo mediante un libro de evidencia bajo la política de niveles de riesgo en references/evidence-ledger.md, registre el contrato en el libro activo para que sobreviva a la pérdida de contexto.

4. Reúna evidencia proporcional. Prefiera artefactos del repositorio y observaciones ejecutables; utilice análisis deterministas cuando sea apropiado. Registre la procedencia como reclamo -> hecho observado -> artefacto o resultado de comando -> método -> limitación. Para verificaciones obligatorias, capture una ejecución de referencia antes de cualquier cambio para que una falla preexistente posterior pueda compararse con ella en lugar de asumirse. Las líneas de base y los registros de evidencia residen en el libro de evidencia activo siempre que se esté utilizando un libro para este cambio.

5. Resuelva el estado previo al cambio:

   • BLOCKED_EVIDENCE cuando falta evidencia fáctica requerida, es contradictoria o no está disponible. Se desbloquea con la evidencia fáctica requerida, la investigación/remediación que resuelve el conflicto o una acción autorizada más reducida. Si ya se sabe que una puerta obligatoria es imposible de pasar sin un cambio fuera del alcance, no proceda declarando esa puerta como obligatoria: obtenga autorización para ampliar el alcance y reclasifique, o redefina explícitamente el contrato de verificación para que la puerta ya no sea obligatoria, con la limitación registrada.
   • ALLOW cuando una acción de bajo riesgo respaldada puede proceder.
   • ALLOW_WITH_VERIFICATION cuando una acción de riesgo medio respaldada puede proceder con la verificación indicada requerida antes de la finalización.
   • CHECKPOINT cuando una acción de alto riesgo respaldada necesita aprobación humana explícita de la acción planificada, la evidencia, las limitaciones y el plan de verificación. CHECKPOINT no es permiso para actuar; se requiere aprobación explícita. Para cada CHECKPOINT, presente la acción como un registro de aprobación por escrito que el humano firme. Utilice exactamente esta forma y las etiquetas de sección Cobertura de la aprobación, Consecuencias irreversibles y Verificación requerida; no omita ninguna de ellas. Una respuesta "APRUEBO" o "tú decides" que no coincida con este registro línea por línea no es autorización para la acción; vuelva a presentar el registro o devuelva BLOCKED_CLARIFICATION. La aprobación autoriza la ejecución del alcance declarado; no autoriza cambiar el alcance, relajar los requisitos de evidencia o aceptar reclamos posteriores al cambio no respaldados.

   SE REQUIERE APROBACIÓN DE CHECKPOINT
   
   Cobertura de la aprobación:
   - <acción concreta 1>
   - <acción concreta 2>
   - ...
   
   Consecuencias irreversibles:
   - <consecuencia concreta que no se puede deshacer>
   - <consecuencia concreta que no se puede deshacer>
   - ...
   
   Verificación requerida:
   - <observación o resultado de comando que debe cumplirse antes de la finalización>
   - <observación o resultado de comando que debe cumplirse antes de la finalización>
   - ...
   
   Responda APRUEBO para autorizar exactamente las acciones anteriores.
   

6. Realice solo el cambio de alcance autorizado. Si el alcance se expande, reclasifique el riesgo, revise el contrato de evidencia y regrese al estado previo al cambio. Cuando un usuario modifica un plan aprobado o verificado, no se limite a actualizar el plan. Reevalúe todos los reclamos dependientes, la evidencia, los riesgos, las consecuencias destructivas y los requisitos de verificación afectados por la modificación. No convierta la ausencia de eliminación en una afirmación de que los datos retenidos permanecen utilizables o legibles. La preservación de bytes no es preservación de semántica.

   No expanda el alcance solicitado simplemente porque un componente, transporte, dependencia o subsistema está relacionado con el comportamiento cambiado. Distinga: funcionalidad explícitamente solicitada para eliminar; funcionalidad técnicamente requerida por la característica eliminada; funcionalidad meramente adyacente o históricamente asociada con la característica eliminada. Solo elimine funcionalidad adyacente cuando la evidencia del repositorio establezca que no se utiliza, es incompatible con el cambio autorizado o está explícitamente incluida en el alcance solicitado. Cuando la funcionalidad pueda permanecer operativa sin la característica eliminada, consérvela a menos que el usuario autorice su eliminación.

   Si una falla de compilación/prueba/construcción preexistente no relacionada impide la verificación, no modifique código no relacionado solo para que la verificación pase. En su lugar, informe: la falla no relacionada, por qué es preexistente, por qué solucionarla expandiría el alcance y qué verificación sigue siendo posible sin solucionarla.

7. Verifique los reclamos de manera proporcional a la acción y al comportamiento observado. Ejecute la puerta de evidencia posterior al cambio: COMPLETE solo ocurre cuando la verificación obligatoria pasó y los reclamos posteriores al cambio requeridos están respaldados. Una falla preexistente puede excluirse del alcance, pero no puede representarse como una verificación exitosa. Reporte la verificación como UNVERIFIABLE / BLOCKED_EVIDENCE y distinga las comprobaciones específicas de la verificación de todo el repositorio.

La falta de evidencia fáctica requerida sigue siendo BLOCKED_EVIDENCE. La incapacidad de ejecutar una verificación requerida también es evidencia insuficiente para COMPLETE; reporte la verificación como UNVERIFIED o FAILED y mantenga la disposición general como BLOCKED_EVIDENCE cuando esa verificación sea obligatoria. Las frases de aprobación genéricas ("adelante", "tú decides", "haz lo mejor", "usa tu criterio" o similares) no son autorización para una acción de CHECKPOINT. La aprobación explícita debe nombrar la acción específica, la evidencia, las limitaciones y el plan de verificación. Si la autorización sigue siendo ambigua, devuelva BLOCKED_CLARIFICATION con la pregunta autoritativa más pequeña que la resuelva. Cuando ninguna política aplicable requiera la propiedad ausente, un humano puede elegir una acción más reducida o aceptar un riesgo adverso establecido; la aprobación nunca hace que un reclamo fáctico no respaldado sea verdadero. Una contradicción en la verificación o un reclamo posterior al cambio requerido no verificado regresa a BLOCKED_EVIDENCE para investigación/remediación.

Libro de evidencia para estado persistente

Para trabajo de riesgo medio y alto, el estado operativo de un cambio activo debe persistir más allá del contexto de la conversación. El libro de evidencia es el registro persistente. Es la misma referencia de Markdown, la misma taxonomía de estado, la misma cadena de procedencia y la misma puerta de finalización que el resto de esta habilidad, aplicados a un documento por cambio.

El libro es un registro, no evidencia

Escribir un reclamo en un libro no lo hace verdadero. Una entrada en el libro debe preservar la procedencia, exactamente como lo hace el resto de esta habilidad. PASS en un libro significa una observación registrada que, por sí misma, respalda el reclamo; el registro no es más fuerte que la observación. Una afirmación simple sin observación, artefacto, método o limitación es UNVERIFIED, sin importar dónde esté escrita.

Cuándo se requiere un libro

Utilice la clasificación de riesgo existente:

• LOW riesgo: el libro es opcional. Un cambio de nombre de variable local, una corrección de error tipográfico aislada o una corrección de documentación no relevante no necesitan uno.
• MEDIUM riesgo: se recomienda el libro cuando el cambio implica un seguimiento de evidencia significativo, múltiples pasos de verificación, o trabajo que pueda abarcar varias fases de investigación o ejecución.
• HIGH riesgo: el libro es obligatorio. Los cambios en API pública o contrato, autenticación, autorización, pagos, operaciones financieras, migraciones de esquemas, operaciones destructivas, acciones irreversibles e impacto significativo en la producción requieren uno.

Dónde reside un libro

Ubicación predeterminada: .evidence-gated/active/<change-id>.md, con libros completados movidos a .evidence-gated/archive/<change-id>.md. El valor predeterminado es un directorio de estado de trabajo, no parte del repositorio publicado: agregue .evidence-gated/active/ a .gitignore para proyectos nuevos a menos que el usuario o las convenciones del repositorio digan lo contrario. Las convenciones del repositorio y las instrucciones explícitas del usuario tienen prioridad; el agente no debe modificar silenciosamente .gitignore solo porque la habilidad use un libro, y no debe confirmar un libro activo sin autorización. Si el cambio es particularmente de alto riesgo, el usuario solicita explícitamente un rastro de auditoría, o las convenciones del repositorio requieren documentación persistente, el libro puede confirmarse intencionalmente y nombrarse en consecuencia (por ejemplo, docs/evidence-gated/<change-id>.md).

Ciclo de vida del libro

1. Determine si se requiere un libro según la clasificación de riesgo anterior.
2. Localice un libro activo existente antes de crear uno nuevo; no cree múltiples libros para el mismo cambio activo.
3. Lea el libro activo antes de continuar. Vuelva a leerlo antes de: una nueva fase de investigación, una ejecución de cambio significativo, solicitar aprobación de checkpoint, actuar sobre una aprobación, cualquier cambio de alcance, cualquier cambio de requisito de verificación y cualquier reclamo de finalización. La relectura debe confirmar la acción solicitada actual, el alcance autorizado, el riesgo, los supuestos activos, los reclamos obligatorios, la verificación obligatoria, el estado del checkpoint, el estado de aprobación, las limitaciones conocidas y la disposición actual. No confíe en la memoria para ninguno de estos.
4. Actualice el libro cuando cambien los hechos materiales: riesgo, alcance, supuestos, evidencia, requisitos de verificación, línea base, estado del checkpoint, estado de aprobación, estado de ejecución, resultados de verificación, disposición final.
5. Finalice el libro en una disposición terminal: COMPLETE, BLOCKED_EVIDENCE o BLOCKED_CLARIFICATION. Un libro que implique COMPLETE mientras los reclamos obligatorios permanecen sin resolver es inválido y debe reescribirse o devolverse a la condición de desbloqueo apropiada.

Contenido requerido

El libro activo debe contener como mínimo: id de cambio y estado actual, acción solicitada, alcance autorizado, elementos explícitamente fuera del alcance, limitaciones e incógnitas del alcance, clasificación de riesgo con razones, supuestos materiales con estado y evidencia de respaldo o limitación, el contrato de evidencia (una entrada por reclamo relevante para la decisión con evidencia requerida, tipo de evidencia, consecuencia si no está respaldado y estado), registros de evidencia (uno por elemento significativo, preservando reclamo -> hecho observado -> artefacto o resultado de comando -> método -> limitación -> estado), verificación de línea base, estado del checkpoint, registro de ejecución para transiciones de estado materiales, registro de verificación para cada verificación obligatoria, y una sección de limitaciones/faltantes/contradictorias/no resueltas.

Fases y disposiciones

El encabezado del libro lleva dos campos distintos. No los confunda.

Fase operativa describe lo que el agente está haciendo actualmente con el cambio, en el orden en que avanza el trabajo. Las fases son DRAFT (libro creado, contrato aún no escrito), INVESTIGATING (recopilación de evidencia, captura de línea base, resolución de supuestos), EXECUTING (cambio de alcance autorizado en progreso), VERIFYING (verificación y finalización posteriores al cambio). Las fases son contables. No autorizan nada; no bloquean nada; no cuentan como evidencia. Una transición de fase sin el cambio de disposición correspondiente no es un cambio de autorización.

Disposición es la decisión a nivel de puerta del protocolo universal. Las disposiciones son exactamente los seis estados canónicos de esta habilidad: BLOCKED_CLARIFICATION, BLOCKED_EVIDENCE, ALLOW, ALLOW_WITH_VERIFICATION, CHECKPOINT, COMPLETE. La disposición es lo que autoriza la ejecución, controla la verificación y finaliza el cambio. En la finalización, la disposición del libro debe ser una de estas seis. Las fases intermedias no son un sustituto de una disposición.

El mismo cambio puede estar en fase EXECUTING y disposición ALLOW_WITH_VERIFICATION al mismo tiempo. El mismo cambio puede estar en fase INVESTIGATING y disposición BLOCKED_EVIDENCE al mismo tiempo. Confundirlas hace que la autorización no esté clara y oculta la puerta; no lo haga.

Las reglas de aprobación y alcance se aplican dentro del libro

Las frases de aprobación genéricas ("adelante", "tú decides", "haz lo mejor", "usa tu criterio") no son autorización cuando se registran en un libro, al igual que no lo son en la conversación. La aprobación en el libro debe estar vinculada al mismo registro SE REQUIERE APROBACIÓN DE CHECKPOINT utilizado por el resto de esta habilidad. Descubrir que otro componente está relacionado con el cambio no es una nueva autorización. Un nuevo hallazgo de evidencia no es un nuevo alcance. Cuando el alcance cambie materialmente: registre el cambio propuesto, identifique los reclamos y verificaciones afectados, reevalúe el riesgo, determine si se requiere nueva autorización, actualice el libro y no ejecute un alcance expandido no autorizado.

Jerarquía de fuente de verdad

La autoridad depende de lo que se está estableciendo. La habilidad se trata fundamentalmente de reclamos fácticos controlados por evidencia, por lo que una afirmación del usuario sobre un asunto fáctico no es un sustituto de esa evidencia. La jerarquía es de dos ejes:

Para intención, autorización, alcance deseado y compensaciones aceptables:

1. Instrucción o aprobación explícita del usuario.

Para estado fáctico del repositorio, comportamiento en tiempo de ejecución y resultados de verificación:

1. Evidencia directa del repositorio y tiempo de ejecución, incluida la salida de comandos para verificaciones ejecutadas

...

[truncado para traducción]