Conceptos básicos

AWR mantiene los hechos de trabajo de un proyecto fuera de cualquier conversación individual de un agente, de modo que el trabajo sobrevive a la pérdida de contexto, a los cambios de agente y a los reinicios. Este artículo explica las cinco ideas detrás de ese modelo; los comandos del Inicio rápido y las rutinas del Flujo de trabajo diario se leen entonces con naturalidad.

El principio central: tus archivos fuente (registros, planes) son la autoridad, y todo lo que el runtime almacena — sesiones, reservas, evidencia — es una proyección comprobable de esos hechos. AWR nunca inventa la intención que falta, y nunca permite que una transcripción de conversación sustituya a un hecho registrado.

Hechos del proyecto: el registro de origen

El registro de origen de AWR es un pequeño contrato de trabajo que mantienes en archivos normales del proyecto: un registro YAML como work-ledger.yaml, o un registro Markdown existente (*-ledger.md) que permanece de solo lectura a través de AWR y se edita en su archivo original. Un registro guarda dos tipos de hechos:

• Objetivos — lo que el proyecto intenta lograr, con criterios de éxito. Los objetivos pueden ser draft, candidate o needs_confirmation cuando hay incertidumbre, y active o confirmed cuando están respaldados por material fuente o una instrucción del usuario. AWR comprueba la declaración; no certifica que el objetivo coincida con lo que un humano quiso decir.
• Elementos de trabajo — las tareas, descritas a continuación.

Un registro mínimo tiene este aspecto:

goals:
  - id: search
    title: Let readers find documents
    status: active
    summary: The user requested search in the existing portal; see README.md.
    success_criteria: [Readers find a requested document]
work_items:
  - id: search-api
    title: Add document search
    status: ready
    goal: search
    acceptance: [A matching query returns the requested document]
    next_action: Implement the search handler using the current document index

Pones estos archivos bajo la gestión de AWR con init. Nada se escribe hasta que aceptas la vista previa:

awr --project /absolute/project init
awr --project /absolute/project init --accept
awr --project /absolute/project intake inspect --json

Init nunca sobrescribe archivos existentes, y la inspección solo actualiza una caché de proyección reconstruible: nunca tus objetivos, tus archivos de tareas ni tu estado de ejecución.

Tareas: elementos de trabajo

Un elemento de trabajo es una tarea del registro. Sus campos clave son los que AWR realmente puede comprobar:

• acceptance — los criterios de finalización: qué debe ser observablemente cierto cuando la tarea esté terminada. Más tarde, un informe de finalización se comprueba contra estos criterios exactos.
• next_action — el siguiente paso persistido, y el campo más valioso para la recuperación: permite que una sesión nueva continúe sin releer el historial.
• Campos de apoyo: summary, goal, kind, paths, tags, priority, depends_on, owner y milestone.

Creas una tarea a partir de un borrador JSON que declara solo hechos explícitamente conocidos:

awr work create --input draft.json

La creación siempre produce un borrador. Los objetivos o hechos requeridos que falten quedan visibles, y un borrador no concede permiso para ejecutar ni completar nada; aplicarlo es un paso separado y explícito.

AWR también informa de estados de organización a nivel de proyecto como not_initialized, needs_organization, ready, blocked, awaiting_verification, completed y closed_without_completion. Dos importan sobre todo en el día a día: ready significa que al menos una tarea tiene un objetivo declarado en la fuente, criterios de aceptación, una acción siguiente y prerrequisitos resueltos; awaiting_verification significa que el registro dice que las tareas están terminadas pero sus informes de aceptación aún no han sido todos verificados.

Puntos de control y sesiones

Una sesión es la vinculación de trabajo de un agente a un elemento de trabajo. Un punto de control es el registro duradero de dónde se encuentra esa sesión: la acción siguiente persistida, los cabos abiertos y el delta real de eventos AWR y de fuentes, no una copia de la conversación.

Cuando una sesión de cliente se inicia o se reanuda tras una compactación, AWR devuelve contexto de recuperación construido a partir del punto de control. Cuando el turno se detiene o termina, la acción siguiente y los cabos abiertos modificados se guardan antes de que puedan perderse:

awr client progress --client codex --external-session CLIENT_ID \
  --next-action "Apply the reviewer corrections" --open-loop "Independent review remains"

Los eventos duplicados con trabajo sin cambios reutilizan su punto de control; un turno continuado con progreso modificado crea uno nuevo. Un límite honesto: el adaptador de hooks nativos que automatiza esto está instalado actualmente solo para Codex. Los demás hosts usan el vinculador L0 (--client generic), que asocia una conversación de host a una sesión AWR activa sin instalar hooks. El adaptador nunca lee los cuerpos de las transcripciones: registra lo que tú le dices, no lo que un modelo dijo.

Reservas y traspaso

Una reserva es el bloqueo explícito que una sesión mantiene antes de ejecutar una tarea. AWR exige que adquieras la reserva de sesión antes de la ejecución, y la finalización la vuelve a comprobar: así es como dos agentes evitan trabajar silenciosamente en la misma tarea.

Un traspaso mueve el trabajo de una sesión o cliente a un sucesor. Reanudas una sesión explícitamente, con comprobaciones de revisión y una transición de sucesor:

awr session resume --from-session AWR_SESSION_ID --agent successor \
  --provider generic --model selected-model --no-claim --expected-revision REVISION

O vinculas una conversación de cliente nueva a su predecesora:

awr client bind --client generic --external-session NEW_CLIENT_ID \
  --work INTAKE-001 --from-session AWR_PREDECESSOR_ID

El traspaso mueve hechos registrados — estado del registro, puntos de control, historial de ejecución — no memoria de proceso. Los hooks de apagado son informativos: nunca liberan reservas ni terminan sesiones, lo que sigue siendo tu responsabilidad explícita en el traspaso.

Entrega y aceptación

La aceptación es donde AWR es deliberadamente estricto. Una tarea no está terminada porque alguien escribió status: completed en un registro. Está terminada cuando un informe de finalización registrado se verifica contra los criterios de aceptación actuales del registro.

Un informe de finalización registra el comando realmente ejecutado, el alcance realmente verificado, la hora y comprobaciones con nombre — cada una correspondiente a un criterio de aceptación exacto y describiendo el resultado observado, no el resultado pretendido:

{
  "version": 1,
  "work_item": "WORK",
  "source_sha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "command": "the command or verification procedure actually executed",
  "scope": ["the scope actually verified"],
  "verified_at": 1,
  "checks": [{
    "name": "independent check name",
    "passed": true,
    "details": "the observed outcome, not an intended result",
    "criteria": ["an exact current source acceptance criterion"]
  }]
}

Antes de completar, haces una comprobación previa del informe:

awr work prepare-completion WORK --report report.json --evidence-key KEY \
  --source-sha FULL_SHA --level locally_verified

La comprobación previa no ejecuta ningún comando, no registra evidencia y no completa ninguna tarea: lee los bytes del informe y devuelve los argumentos de evidencia y el mapeo de aceptación. La finalización en sí es una escritura separada que vuelve a comprobar reservas, dependencias, frescura de la fuente y bytes del informe; cambiar un informe después de la comprobación previa invalida su resumen. La finalización declarada en la fuente por sí sola nunca proporciona un recibo verificado, y source_completed y verified_completed siguen siendo recuentos separados en los informes de estado.

Una tarea, de principio a fin

Unámoslo todo con la tarea de búsqueda del registro anterior:

1. Hechos. Ejecutas awr --project /absolute/project init --accept; el registro con el objetivo search y el elemento de trabajo search-api se convierte en la autoridad.
2. Tarea. El elemento de trabajo lleva criterios de aceptación y una acción siguiente, así que el proyecto informa ready.
3. Sesión y reserva. Preparas el trabajo desde una instantánea y luego adquieres la reserva de sesión antes de tocar código:

   awr work prepare search-api --session AWR_SESSION_ID --source-sha FULL_SHA

4. Punto de control. Mientras trabajas, guardas el progreso con awr client progress, de modo que la acción siguiente y los cabos abiertos sobrevivan a un fallo o una compactación.
5. Traspaso (si hace falta). Un sucesor reanuda con awr session resume --from-session … y obtiene los mismos hechos, sin que se reproduzca ningún historial de chat.
6. Entrega. Escribes un informe cuyas comprobaciones corresponden al criterio de aceptación exacto, lo verificas previamente con awr work prepare-completion y solo entonces registras la finalización. El estado ahora muestra la tarea como verificada contra el SHA de la fuente, no simplemente marcada como hecha.

A dónde ir después

• Inicio rápido — ejecuta estos conceptos por primera vez.
• Flujo de trabajo diario — el bucle rutinario de preparar, reservar, guardar puntos de control y completar.