Session Wrap (encerramento com ciência do projeto)

O que Session Wrap (encerramento com ciência do projeto) faz?

Duas partes: §1 é universal; §2 roteia por projeto (tabelas de estado são por projeto — nunca escreva tabelas de um projeto para outro). §0 = heartbeat de meio de sessão (abaixo). <MEM> = o diretório de memória exibido por bash ~/.claude/hooks/session-resume.sh --dir.

Redigir antes de QUALQUER salvamento (heartbeat, memória de handoff, arquivos de regras/now, linhas de BD, prompt de retomada): remover chaves de API, tokens, senhas, chaves privadas, números e saldos de contas, dados pessoais, qualquer coisa que identifique contas reais. Escreva <REDACTED — see vault> ou parafraseie ("saldo verificado ao vivo, não registrado aqui"). Nomear ONDE o valor real está é aceitável; o valor em si não. Mesmo padrão da regra de paráfrase na guardrail em §2 — manter ambas.

0. Checkpoint de heartbeat — MEIO DA SESSÃO (somente memória de handoff)

Após cada subtarefa concluída, e ANTES de qualquer etapa longa/arriscada (grande refatoração, deploy, migração de BD), atualize APENAS o arquivo de handoff §1 do projeto atual (crie-o se não existir): um bloco ## LIVE STATE (heartbeat) — o que acabou de ser concluído, o que está em andamento, o próximo passo. Substitua o bloco anterior, nunca anexe; alvo <15 linhas escritas. Mantenha o cabeçalho exato: o hook corresponde a ele.

• NÃO remarcar MEMORY.md, tocar em qualquer banco de dados ou emitir o prompt de retomada — estes ficam para o fim da sessão (§1 tag, §2, §3). No wrap, incorpore o bloco no estado verificado e exclua-o.
• Uma falha a qualquer momento agora custa no máximo um passo de memória. session-resume.sh lista todo handoff que ainda contém o bloco como UNWRAPPED HEARTBEAT na próxima inicialização, portanto um arquivo de primeiro heartbeat não marcado ainda é encontrado.

1. Memória de handoff — SEMPRE (qualquer projeto)

Escreva/atualize <MEM>/project_<proj>_handoff_<YYYYMMDD>.md: estado verificado (SHAs principais, o que foi concluído, DECISÕES em aberto, próximo trabalho ordenado, mandatos). Em <MEM>/MEMORY.md, marque sua linha de índice como ★READ FIRST FOR <PROJECT> (current)★; marque a anterior como "(superseded)". Handoffs antigos permanecem em disco: a cadeia de substituídos é o histórico do projeto.

• O hook SessionStart ~/.claude/hooks/session-resume.sh é INDEPENDENTE DE PROJETO: ele injeta TODA linha que corresponde a READ FIRST FOR <ANY-PROJECT> que não esteja marcada como substituída → marcar a linha É a garantia de retomada para QUALQUER projeto (nenhum hook por projeto necessário). Mantenha o hook mesmo que MEMORY.md seja carregado automaticamente: ele adiciona a instrução "leia o handoff ANTES de trabalhar", funciona a partir de qualquer diretório e sobrevive ao MEMORY.md ultrapassar o limite de carga de 200 linhas. Ele também avisa quando um projeto tem dois ponteiros ativos ou um ponteiro para um arquivo ausente — corrija-os no wrap.

Regras são transferidas. Qualquer nova regra do proprietário, orientação permanente, comando funcional ou lição paga vai para o arquivo de regras sempre carregado do projeto no momento em que é fornecida, não apenas em um handoff. Arquivo de regras: <MEM>/<proj>_rules.md, carregado na íntegra pelo session-resume.sh para cada projeto listado em <MEM>/session-wrap.conf. Mantenha-o curto; substitua em vez de anexar. Verifique no wrap: qualquer coisa que o proprietário teve que repetir nesta sessão deve agora estar lá. Também reescreva <MEM>/<proj>_now.md (estado atual e próximos passos, mantido curto: o contexto do hook é cortado em cerca de 10.000 caracteres).

2. Sincronização do armazenamento de estado do projeto — ROTEAR primeiro

Detecte o projeto a partir do cwd / do trabalho desta sessão. Em seguida, siga a rota desse projeto. Adicione uma rota ### por projeto que você possui; as três abaixo são os padrões.

→ seu próprio banco de dados

Conecte com credenciais do ambiente (psql "$PROJECT_DB_URL"), nunca um literal no comando. Tabelas de exemplo em examples/state-store.sql:

INSERT INTO session_handoff (session_id, handoff_prompt, created_at) VALUES ('<sid>','<resume>',now());
INSERT INTO decisions (title,rationale,applies_to,status,session,"timestamp",decided_at)
  VALUES ('<d>','<why>','<project>','implemented','<sid>',now()::text,now());   -- um INSERT por linha
INSERT INTO code_map (module,path,lines,purpose,bounded_context) VALUES (...);  -- DELETE o path primeiro se não houver constraint unique

ARMADILHAS (escreva as do seu armazenamento aqui; estas são do tipo que custam uma sessão cada): cite colunas com nomes de palavras-chave (decisions."timestamp"; obrigatório para palavras reservadas como "order", inofensivo caso contrário) e observe seu tipo (esta é text + NOT NULL, portanto now()::text); uma coluna com constraint CHECK aceita APENAS seus valores listados (pending|implemented|superseded|deferred|rejected); não assuma que uma tabela existe — faça \d primeiro; VALUES multi-linha é atômico, então uma linha ruim derruba todas → faça por linha com -v ON_ERROR_STOP=off. Falso positivo de guardrail: um hook PreToolUse que bloqueia comandos perigosos busca o comando Bash INTEIRO — se seu texto SQL contiver um padrão bloqueado literal (reset --hard, git push, git clean), todo o comando é BLOQUEADO. Parafraseie tais strings no texto do handoff/decisão (ex.: "git destrutivo" não o literal).

→ seu próprio armazenamento (NÃO de outro projeto)

VERIFIQUE o esquema antes de escrever; anotações sobre ele ficam obsoletas. Infraestrutura ao vivo — o sistema de registro externo (provedor de pagamento, BD de produção, o serviço em execução) é a verdade, não o handoff; nunca altere uma flag ou configuração ao vivo como parte de um wrap.

→ somente memória

Nenhum armazenamento de estado em BD — a memória de handoff §1 É o registro. Anote isso; não escreva tabelas de nenhum outro projeto.

3. Emitir o PROMPT DE RETOMADA (o último artefato — o que o usuário cola no próximo Claude)

Após salvar, GERE uma cópia pronta para colar do prompt para a próxima sessão. O hook SessionStart já injeta o ponteiro do handoff, portanto este prompt adiciona apenas: checks de recarga + a(s) decisão(ões) ABERTA(S) que o usuário deve tomar. Modelo:

Resume <projeto>. Leia a memória <arquivo-handoff> primeiro, depois skill /<skill-mapa-projeto>.
Estado verificado: <1 linha: SHA principal + o que está ao vivo + a coisa travada/bloqueada>.
Primeiro: 1) /context — <qualquer check de recarga, ex.: medir custo do plugin recém-carregado>; 2) <check confirmado-carregado>.
Em seguida, minha decisão sobre <FORK ABERTO>: [ESCOLHA UM] (a) <rec> (b) … (c) …
<suas instruções permanentes por sessão, ex.: verificar antes de declarar concluído>

Mantenha CURTO — ponteiros + decisões, não um despejo de estado (o estado vive na memória de handoff + BD; não duplique → poluição de contexto). Cole também este prompt na memória de handoff sob um cabeçalho ## RESUME PROMPT para que seja consultável, não perdido no chat.

Conclusão (verificar, citar resultados)

• Portão de reconciliação — execute PRIMEIRO, obrigatório. Escaneie toda a conversa (não apenas a memória) e liste cada decisão, item em aberto, correção do proprietário e mandato desta sessão. Para CADA, cite-o + onde foi registrado (linha da memória de handoff, linha do arquivo de regras ou linha do BD) ou marque DROPPED: <motivo de uma linha>. "Acho que está coberto" não é permitido — aponte para a linha ou marque como dropped. Qualquer coisa não contabilizada → escreva agora (atualize §3 se uma decisão ABERTA mudou), depois reliste.
• §1: a linha MEMORY.md da memória de handoff carrega (current); a anterior marcada como substituída; grep -c 'LIVE STATE (heartbeat)' <handoff> = 0.
• §2: para um projeto com BD, SELECT max(created_at) FROM session_handoff; ≈ agora + as contagens de linhas que você escreveu. Para somente memória, informe isso.
• §3: o prompt de retomada é emitido E salvo na memória de handoff.