Handoff de Sessão

Propósito

Janelas de contexto grandes degradam a aderência a instruções, a precisão do raciocínio e a exatidão das ferramentas conforme os contadores de tokens se acumulam. Sessões longas se preenchem com planos substituídos, rascunhos abortados e rastros de erros repetitivos. Reiniciar para uma sessão nova restaura o desempenho, mas descartar o contexto cegamente introduz perda de estado, progresso alucinado e erros repetidos.

A habilidade session-handoff padroniza como um agente salva o estado ativo. Ela traduz a memória de trabalho efêmera em um documento de ponte acionável e verificável para a próxima sessão.

Quando Usar Esta Habilidade

• O uso de contexto se aproxima da capacidade (aproximadamente >60%) e uma reinicialização está próxima.
• Antes de executar /clear ou /compact no Claude Code, Cursor ou Codex.
• Ao trocar de tarefas no meio da sessão, ou ao encerrar uma sessão de codificação que outra sessão (ou agente) continuará.

Fluxo de Trabalho: Encerrando uma Sessão (6 Passos)

Execute esta sequência quando uma sessão de agente atingir limites operacionais ou ao interromper o trabalho:

1. Auditar Estado do Git e do Workspace Execute git status -s e git diff --stat para estabelecer a realidade fundamentada. Nunca confie na memória do chat para saber o que foi modificado. Identifique arquivos modificados, não rastreados e preparados.

2. Capturar Estado do Objetivo vs. Realidade Implementada Defina o objetivo original em uma frase. Documente precisamente o que foi verificado como funcionando (com comandos de teste passando ou verificações em tempo de execução) versus o que permanece parcial ou não verificado.

3. Registrar Decisões Tomadas e Caminhos Descartados Liste as escolhas arquiteturais e de design comprometidas durante a sessão, juntamente com a justificativa concreta. Registre explicitamente decisões negativas (abordagens tentadas e descartadas) para impedir que o próximo agente tente novamente soluções falhas.

4. Catalogar Arquivos Tocados e Símbolos Relevantes Liste os caminhos de arquivos chave, funções, classes e definições de esquema modificados ou referenciados. Inclua referências de linha onde relevante.

5. Isolar Loops Abertos com Proprietários e Verificações Liste todos os casos de borda não abordados, testes falhando, tarefas adiadas e restrições de ambiente. Cada loop aberto deve especificar quem o resolve (Humano ou Agente) e como a conclusão é verificada.

6. Especificar a Ação Imediata Seguinte Escreva uma instrução única, atômica e inequívoca para o próximo agente executar no primeiro turno. Não forneça uma lista ampla; especifique o comando exato a ser executado ou o arquivo a ser editado primeiro.

Regras de Operação

• Separar Fatos de Especulação: Um teste que passou é um fato; assumir que o código funciona porque compilou é especulação. Rotule suposições não testadas explicitamente como [UNVERIFIED].
• Exigir Proprietários e Verificações para Loops Abertos: Cada loop aberto deve declarar um proprietário (Human ou Agent) e um critério de verificação determinístico (por exemplo, pytest tests/auth/test_token.py:test_refresh_rotation passes).
• Banir Continuações Vagas: Nunca escreva "continuar trabalhando em autenticação" ou "finalizar componentes de frontend". Declare o símbolo exato, arquivo e modo de falha.
• Referenciar Identificadores Reais do Workspace: Todas as referências a código devem usar caminhos de arquivo e nomes de símbolos exatos. Não use descrições generalizadas de pseudocódigo.

Exemplo Trabalhado: Nota de Handoff de Sessão

# Handoff de Sessão: Implementação de Rotação de JWT

### Objetivo e Estado Atual
- **Objetivo Alvo**: Implementar rotação e revogação de refresh token no serviço de autenticação FastAPI.
- **Estado Atual**: Migração do banco de dados de refresh token aplicada e endpoint de rotação criado. Geração de token e persistência no banco de dados funcionam. O cache da lista negra de revogação ainda não está conectado ao validador de dependência.
- **Verificação**: `pytest tests/test_auth_tokens.py` passa (4/4 testes).

### Decisões Tomadas (Com Razões)
- **Usado Redis para Lista de Revogação de Token**: Selecionado Redis em vez de consultas Postgres para tokens JTI revogados para manter a latência abaixo de 5ms em rotas protegidas.
- **Tokens de Refresh Stateless Rejeitados**: Inicialmente avaliamos a expiração deslizante em claims JWT sem persistência, mas a descartamos porque tokens comprometidos não poderiam ser revogados antes da expiração natural.
- **Formato do Token**: Escolhido UUIDv4 para a claim `jti` para manter a compatibilidade com esquemas de armazenamento de sessão existentes.

### Arquivos Alterados
- `src/services/auth.py`: Adicionada função `rotate_refresh_token(old_token: str)` e chamada de invalidação do Redis.
- `src/models/tokens.py`: Adicionada tabela `RefreshTokenRecord` SQLModel para rastrear famílias de tokens.
- `alembic/versions/20261005_add_token_families.py`: Migração criando a tabela `token_records`.

…