O Projeto e o SPEC: Definição Antes do Código

# SPEC.md — pr-reviewer Plugin

## O que faz
Plugin Claude Code que revisa PRs de forma automatizada:
- Checkout isolado via git worktree (não contamina branch de trabalho)
- Loop de revisão com 3 personas: Author, Reviewer, Security
- Relatório estruturado com severidade CRITICAL/HIGH/MEDIUM/LOW
- Integração com GitHub via `gh pr comment`

## Ciclo de Vida
SETUP → REVIEWING (rounds 1-3) → SUMMARIZING → DONE

| Estado      | Quem Age          | Hook Faz                               |
|-------------|-------------------|----------------------------------------|
| SETUP       | Plugin cria worktree | CAS para REVIEWING → escreve runner  |
| REVIEWING   | Claude revisa diff   | Incrementa round ou vai SUMMARIZING  |
| SUMMARIZING | Claude consolida     | Gera relatório → CAS para DONE       |
| DONE        | Terminal             | Cleanup → APPROVE                    |

## Schema do Estado (state/review.yaml)
pr_number: int          # número do PR
worktree_path: string   # /tmp/pr-review-$PR_NUMBER
status: enum            # SETUP|REVIEWING|SUMMARIZING|DONE
round: int              # rodada atual (1-indexed)
max_rounds: int         # default 3, configurável
persona: string         # Author|Reviewer|Security
findings: list          # [{file, line, severity, description, suggestion}]
started_at: int         # epoch timestamp
version: int            # para CAS (incrementar a cada escrita)

## File Tree
pr-reviewer/
├── claude.json                   # manifest + hook registration
├── hooks/
│   └── stop-hook.sh             # Stop Hook com lifecycle completo
├── scripts/
│   ├── setup-worktree.sh        # git worktree add + idempotente
│   └── cleanup-worktree.sh      # git worktree remove --force
├── state/
│   └── review.yaml              # estado persistente
├── runners/                     # runner scripts por rodada
│   └── PR-NNN-round-N.sh       # gerado pelo hook
└── .claudex/reviews/            # artefatos finais
    └── PR-NNN.md                # relatório de revisão

## Invariantes de Segurança
1. FAIL-OPEN: stop-hook.sh retorna exit 0 em qualquer falha não tratada
2. ESCRITA ATÔMICA: toda escrita de estado via tmp + rename
3. CAS: toda modificação de estado verifica version antes de escrever
4. LOCKFILE: flock -n state/review.lock — apenas um revisor por repo
5. EXIT TRAP: cleanup-worktree.sh chamado sempre, mesmo em falha
6. PATH VALIDATION: worktree_path deve começar com /tmp/pr-review-

## Contrato dos Hooks
Stop Hook:
- Input: lê state/review.yaml
- BLOCK: {"decision":"block","reason":"..."} — reason é Markdown
- APPROVE: {"decision":"approve"}
- Nunca lança exceção para o chamador (ERR trap = fail-open)

## Configuração (.claude/review-config.yaml)
max_rounds: 3           # rodadas de revisão
min_severity: MEDIUM    # severidade mínima para comment no PR
ignore_paths: []        # paths a ignorar no diff
timeout_seconds: 120    # timeout por rodada de runner
post_to_github: true    # se false, só salva localmente