# Checkpoint Protocol — Automatic Project State Tracking

## Regra Global (MUST)

**TODOS os agentes DEVEM atualizar o checkpoint do projeto ativo após qualquer ação relevante.**

Isso NÃO é opcional. O checkpoint é o "save point" do projeto — garante continuidade entre sessões.

## Multi-Project Mode

O sistema suporta multiplos projetos simultaneos via `projects/`.

### Resolucao do Checkpoint Path

```
SE projects/ existe:
  checkpoint = projects/{projeto-ativo}/PROJECT-CHECKPOINT.md
  stories   = projects/{projeto-ativo}/stories/
  prd       = projects/{projeto-ativo}/prd/

SENAO (legacy):
  checkpoint = docs/PROJECT-CHECKPOINT.md
  stories   = docs/stories/
```

### Como o agente sabe qual projeto esta ativo?

O projeto ativo e armazenado no **CONTEXTO DA CONVERSA** (context window), NAO em arquivo.
- No inicio da sessao, o hook `checkpoint-context.cjs` lista os projetos disponiveis
- O agente pergunta ao usuario qual projeto (se nao mencionado)
- O agente armazena internamente e usa para todas as operacoes
- Duas sessoes simultaneas podem trabalhar em projetos diferentes sem conflito

### Story ID Convention (Multi-Project)

Stories DEVEM usar prefixo de projeto para evitar colisao:
- LMAS: `LMAS-{epic}.{story}` (ex: LMAS-6.1)
- ClaWin: `CW-{epic}.{story}` (ex: CW-3.1)
- i5x: `I5X-{epic}.{story}` (ex: I5X-1.1)

O prefixo esta definido no `projects/{id}/.project.yaml` ou no `projects/{id}/CLAUDE.md`.

## Trigger Events (quando atualizar)

Atualize o checkpoint **imediatamente após** qualquer uma destas ações:

| Evento | Exemplo | Seção a atualizar |
|--------|---------|-------------------|
| **Story criada** | @sm cria story 4.5 | Status das Stories, Totais |
| **Story completada** | @dev marca Ready for Review | Status das Stories, Último Trabalho, Próximos Passos, Totais |
| **Story status mudou** | Draft → InProgress → Done | Status das Stories |
| **Documento criado** | PRD, Architecture, ADR | Documentos do Projeto |
| **Documento atualizado** | PRD v1.3 → v1.4 | Documentos do Projeto |
| **Memória criada/atualizada** | Memory file criado/modificado | Último Trabalho |
| **Agente criado** | @checkpoint criado | Último Trabalho |
| **Decisão arquitetural** | ADR-3 Scene Flow | Decisões Arquiteturais |
| **Workflow concluído** | SDC completo para epic 5 | Último Trabalho, Próximos Passos |
| **Task concluída** | Subtask de story completada | Último Trabalho |
| **Arquivo relevante criado/modificado** | Novo service, nova scene | Último Trabalho (arquivos) |
| **Testes adicionados** | 101 testes novos | Totais |
| **Push/merge realizado** | @devops faz push | Último Trabalho |
| **Sessão encerrando** | Usuário vai parar de trabalhar | TUDO (refresh completo) |

## Abrangência de Monitoramento

O checkpoint é o mecanismo natural de registro de TODA atividade relevante do projeto. QUALQUER criação ou atualização dos seguintes tipos de arquivo DEVE acionar uma atualização inline do checkpoint:

- `projects/{projeto}/PROJECT-CHECKPOINT.md` ou `docs/PROJECT-CHECKPOINT.md` — checkpoint (refresh)
- `projects/{projeto}/stories/**/*.md` ou `docs/stories/**/*.md` — stories (status, progresso)
- `projects/{projeto}/prd/`, `projects/{projeto}/architecture/` ou `docs/prd*.md`, `docs/architecture*.md`, `docs/adr-*.md` — documentação
- Arquivos de memória dos agentes — contexto persistente
- Qualquer documento de planejamento ou especificação

**IMPORTANTE:** Se o agente que fez a ação NÃO é o @checkpoint, ele DEVE fazer a atualização inline diretamente no checkpoint como parte de sua ação. O checkpoint NÃO precisa ser invocado como agente separado — cada agente é responsável por manter o checkpoint atualizado.

## Como Atualizar

### Atualização inline (PADRÃO — rápido, ~10 segundos)

A atualização inline é SEMPRE o método padrão. É rápida: abra o arquivo, edite 2-5 linhas, pronto.

Após a ação, atualize diretamente **apenas as seções que mudaram** do checkpoint do projeto ativo (`projects/{projeto}/PROJECT-CHECKPOINT.md` ou `docs/PROJECT-CHECKPOINT.md` em modo legacy):

- Story mudou status → atualizar tabela de stories + totais
- Arquivo criado → adicionar em "Último Trabalho"
- ADR tomada → adicionar em "Decisões Arquiteturais"

**NÃO reescreva o arquivo inteiro.** Edite apenas as linhas relevantes.

### Atualização completa via agente (MANUAL — quando solicitado pelo usuário)

Apenas quando o usuário pedir ou quando muitas coisas mudaram e o checkpoint parece desatualizado:
```
@checkpoint *update
```

**O `@checkpoint *update` NÃO é automático.** É um botão manual para refresh completo.

## Formato da Atualização

Ao atualizar "Último Trabalho Realizado", use este formato:

```markdown
### Sessão {data}

**Story X.Y — {título}** ({status}):
- {o que foi feito em 2-3 bullets}
- Arquivos: {lista dos arquivos criados/modificados}
- Testes: {X novos, Y total}
```

## Seções do Checkpoint (ESTRUTURA OBRIGATÓRIA)

O checkpoint DEVE conter estas seções. O agente DEVE atualizar a seção correspondente à sua ação:

| Seção | Quem atualiza | O que contém |
|-------|---------------|-------------|
| **Contexto Ativo** | O agente que está trabalhando | O que está sendo feito AGORA (story, branch, bloqueios) |
| **Status das Stories** | Auto-gerado + agentes | Tabela de stories com status |
| **Decisoes Tomadas** | Agentes após decisões | Escolhas técnicas/negócio E o porquê |
| **Ambiente Configurado** | @dev, @devops | .env keys, deploy target, domínios, serviços |
| **Ultimo Trabalho Realizado** | Todos os agentes | O que foi feito (com arquivos e testes) |
| **Proximos Passos** | Todos os agentes | O que falta fazer (com checkboxes) |
| **Git Recente** | Auto-gerado | Últimos commits + branch (NÃO editar manualmente) |
| **Ambiente Detectado** | Auto-gerado | .env keys detectadas (NÃO editar manualmente) |

**Seções marcadas como "Auto-gerado" são mantidas pelo sistema. NÃO editar manualmente — serão sobrescritas.**

## Regras

1. **NÃO pule o checkpoint** — mesmo para mudanças "pequenas". Uma story Draft→InProgress é relevante.
2. **NÃO delegue ao usuário** — o agente que fez a ação atualiza o checkpoint.
3. **NÃO acumule** — atualize imediatamente após cada ação, não "depois".
4. **Mantenha conciso** — o checkpoint deve ser escaneável em 30 segundos.
5. **Seção "Último Trabalho"** tem no máximo as **3 sessões mais recentes**. Sessões antigas são removidas.
6. **Milestone saves** — Atualize o checkpoint a cada milestone significativo, não só no final. Exemplos: após configurar .env, após criar migration, após decisão de arquitetura.
7. **Handoff obrigatório** — Ao trocar de agente (@dev → @qa), o agente saindo DEVE atualizar "Contexto Ativo" e "Proximos Passos" antes do handoff.
8. **Conflito de escrita** — Se o checkpoint foi modificado externamente (outro terminal), leia antes de escrever. Nunca sobrescreva cegamente.

## Obrigatoriedade por Agente (MUST)

Cada agente DEVE fazer a atualização inline do checkpoint como **último passo** de suas ações principais:

| Agente | Ação que OBRIGA checkpoint inline |
|--------|----------------------------------|
| **@sm** | Após criar story (`*draft`, `*create-story`) |
| **@po** | Após validar story (`*validate-story-draft`) |
| **@dev** | Após concluir implementação (status → Ready for Review) |
| **@qa** | Após quality gate (PASS, FAIL, ou CONCERNS) |
| **@devops** | Após push/PR/release |
| **@pm** | Após criar PRD, epic, ou spec |
| **@architect** | Após decisão arquitetural ou ADR |
| **@data-engineer** | Após criar/modificar schema ou migration |
| **@analyst** | Após entregar pesquisa ou análise |
| **Morpheus** | Após criar/modificar componente do framework |

**A atualização é parte integrante da ação — NÃO é um passo opcional que "pode ser feito depois".**

Se o checkpoint do projeto ativo não existir, o agente DEVE criá-lo usando o formato padrão antes de atualizar. Em multi-project mode, o path é `projects/{projeto}/PROJECT-CHECKPOINT.md`.

## Início de Sessão

No início de TODA sessão:
1. Ler o checkpoint do projeto ativo (`projects/{projeto}/PROJECT-CHECKPOINT.md`) — este é o "cérebro" do projeto entre sessões
2. Verificar "Contexto Ativo" — entender o que estava sendo feito
3. Verificar "Decisoes Tomadas" — não refazer escolhas já feitas
4. Verificar "Proximos Passos" — saber o que fazer a seguir
5. Se checkpoint parecer desatualizado, rodar `@checkpoint *verify`

**NOTA:** O hook `checkpoint-context.cjs` injeta automaticamente um resumo do checkpoint no primeiro prompt de cada sessão. O agente RECEBE esse contexto sem precisar ler o arquivo manualmente. Mesmo assim, para tarefas complexas, ler o arquivo completo é recomendado.