Conceitos fundamentais

O AWR mantém os fatos de trabalho de um projeto fora de qualquer conversa individual de agente, para que o trabalho sobreviva à perda de contexto, à troca de agentes e a reinícios. Este artigo explica as cinco ideias por trás desse modelo; os comandos do Quickstart e as rotinas do Fluxo de trabalho diário então se leem naturalmente.

O princípio central: seus arquivos-fonte (ledgers, planos) são a autoridade, e tudo o que o runtime armazena — sessões, claims, evidências — é uma projeção verificável desses fatos. O AWR nunca inventa intenção ausente e nunca deixa uma transcrição de conversa substituir um fato registrado.

Fatos do projeto: o ledger de origem

O ledger de origem do AWR é um pequeno contrato de trabalho que você mantém em arquivos comuns do projeto: um ledger YAML como work-ledger.yaml, ou um ledger Markdown existente (*-ledger.md) que permanece somente leitura para o AWR e é editado no seu arquivo original. Um ledger registra dois tipos de fatos:

Objetivos — o que o projeto está tentando alcançar, com critérios de sucesso. Objetivos podem ser draft, candidate ou needs_confirmation quando incertos, e active ou confirmed quando respaldados por material de origem ou instrução do usuário. O AWR verifica a declaração; ele não certifica que o objetivo corresponde ao que um humano quis dizer.
Itens de trabalho — as tarefas, descritas abaixo.

Um ledger mínimo se parece com isto:

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

Você coloca esses arquivos sob a gestão do AWR com o init. Nada é escrito até você aceitar a prévia:

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

O init nunca sobrescreve arquivos existentes, e a inspeção apenas atualiza um cache de projeção reconstruível — nunca os seus objetivos, arquivos de tarefas ou estado de execução.

Tarefas: itens de trabalho

Um item de trabalho é uma tarefa no ledger. Seus campos-chave são os que o AWR realmente consegue verificar:

acceptance — os critérios de conclusão: o que deve ser observavelmente verdadeiro quando a tarefa estiver pronta. Um relatório de conclusão é depois verificado contra exatamente esses critérios.
next_action — o próximo passo persistido, e o campo mais valioso para a recuperação: permite que uma sessão nova continue sem reler o histórico.
Campos de apoio: summary, goal, kind, paths, tags, priority, depends_on, owner e milestone.

Você cria uma tarefa a partir de um rascunho JSON que declara apenas fatos explicitamente conhecidos:

awr work create --input draft.json

A criação sempre produz um rascunho. Objetivos ausentes ou fatos obrigatórios faltantes permanecem visíveis, e um rascunho não concede permissão para executar ou concluir nada; aplicá-lo é um passo separado e explícito.

O AWR também reporta estados de organização no nível do projeto, como not_initialized, needs_organization, ready, blocked, awaiting_verification, completed e closed_without_completion. Dois importam mais no dia a dia: ready significa que pelo menos uma tarefa tem um objetivo declarado na fonte, critérios de aceitação, uma próxima ação e pré-requisitos resolvidos; awaiting_verification significa que o ledger diz que as tarefas estão prontas, mas seus relatórios de aceitação ainda não foram todos verificados.

Checkpoints e sessões

Uma sessão é o vínculo de trabalho de um agente a um item de trabalho. Um checkpoint é o registro durável de onde essa sessão está: a próxima ação persistida, os pontos em aberto e o delta real de eventos e fontes do AWR — não uma cópia da conversa.

Quando uma sessão de cliente inicia ou retoma após uma compactação, o AWR retorna contexto de recuperação construído a partir do checkpoint. Quando o turno para ou termina, a próxima ação alterada e os pontos em aberto são salvos antes que possam se perder:

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

Eventos duplicados com trabalho inalterado reutilizam o seu checkpoint; um turno continuado com progresso alterado cria um novo. Um limite honesto: o adaptador de hooks nativos que automatiza isso está atualmente instalado apenas para o Codex. Outros hosts usam o vinculador L0 (--client generic), que anexa uma conversa do host a uma sessão AWR ativa sem instalar hooks. O adaptador nunca lê o corpo das transcrições — ele registra o que você diz a ele, não o que um modelo disse.

Claims e handoff

Um claim é a trava explícita que uma sessão detém antes de executar uma tarefa. O AWR exige que você adquira o claim da sessão antes da execução, e a conclusão o verifica de novo — é assim que dois agentes evitam trabalhar silenciosamente na mesma tarefa.

Um handoff move o trabalho de uma sessão ou cliente para um sucessor. Você retoma uma sessão explicitamente, com verificações de revisão e uma transição de sucessão:

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

Ou vincule uma nova conversa de cliente à sua predecessora:

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

O handoff move fatos registrados — estado do ledger, checkpoints, histórico de execução — não memória de processo. Hooks de desligamento são apenas consultivos: eles nunca liberam claims nem encerram sessões, o que continua sendo sua responsabilidade explícita no handoff.

Entrega e aceitação

A aceitação é onde o AWR é deliberadamente rigoroso. Uma tarefa não está pronta porque alguém escreveu status: completed em um ledger. Ela está pronta quando um relatório de conclusão registrado é verificado contra os critérios de aceitação atuais do ledger.

Um relatório de conclusão registra o comando realmente executado, o escopo realmente verificado, o horário e verificações nomeadas — cada uma mapeando para um critério de aceitação exato e descrevendo o resultado observado, não o 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 concluir, você faz o preflight do relatório:

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

O preflight não executa nenhum comando, não registra nenhuma evidência e não conclui nenhuma tarefa — ele lê os bytes do relatório e retorna os argumentos de evidência e o mapeamento de aceitação. A conclusão em si é uma escrita separada que reverifica claims, dependências, frescor da fonte e os bytes do relatório; alterar um relatório depois do preflight invalida o seu digest. A conclusão declarada na fonte sozinha nunca fornece um recibo verificado, e source_completed e verified_completed continuam sendo contagens separadas nos relatórios de status.

Uma tarefa, de ponta a ponta

Amarre tudo com a tarefa de busca do ledger acima:

Fatos. Você roda awr --project /absolute/project init --accept; o ledger com o objetivo search e o item de trabalho search-api passa a ser a autoridade.
Tarefa. O item de trabalho carrega critérios de aceitação e uma próxima ação, então o projeto reporta ready.
Sessão e claim. Você prepara o trabalho a partir de um snapshot e depois adquire o claim da sessão antes de tocar no código:

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

Checkpoint. Enquanto trabalha, você salva o progresso com awr client progress, para que a próxima ação e os pontos em aberto sobrevivam a uma falha ou compactação.
Handoff (se necessário). Um sucessor retoma com awr session resume --from-session … e recebe os mesmos fatos, sem nenhum histórico de chat ser reproduzido.
Entrega. Você escreve um relatório cujas verificações mapeiam para o critério de aceitação exato, faz o preflight com awr work prepare-completion e só então registra a conclusão. O status agora mostra a tarefa como verificada contra o SHA da fonte, não apenas marcada como pronta.

Para onde ir a seguir

Quickstart — execute estes conceitos pela primeira vez.
Fluxo de trabalho diário — o ciclo rotineiro de preparar, fazer claim, checkpoint e concluir.