---
name: feature-scope-guard
description: "Verifica se o diff atual foge do escopo da feature ativa. Produz SCOPE_OK, SCOPE_WARNING ou SCOPE_UNKNOWN quando a feature não é identificável."
---

# Objetivo

Detectar scope creep antes do commit final, apontando arquivos modificados que não pertencem à feature ativa.

# Quando usar

- após branch-sync-guard e antes de enforce-workflow
- quando há suspeita de que mudanças acidentais ocorreram fora do escopo
- ao retomar uma feature após interrupção longa

# Quando NÃO usar

- features na etapa inicial (spec/test-red)
- para decidir o que faz parte do escopo — essa é uma decisão humana

# Processo

1. Rode `scripts/feature_gate_report.py --format json`
2. Identifique a feature ativa pelo nome do branch ou por `features/<feature>/SPEC.md`
3. Execute, se precisar confirmar algum detalhe:
   ```bash
   git diff --name-only HEAD
   git status --short
   ```
4. Classifique cada arquivo modificado como:
   - `IN_SCOPE` — dentro de `features/<feature>/`, arquivos de teste relacionados, ou arquivos de configuração diretamente exigidos pela SPEC
   - `OUT_OF_SCOPE` — qualquer outro arquivo não previsto na SPEC
   - `AMBÍGUO` — arquivo que pode ou não ser necessário; requer confirmação

# Saída final esperada
| Gate | Significado |
|---|---|
| `SCOPE_OK` | Todos os arquivos modificados estão dentro do escopo da feature ativa |
| `SCOPE_WARNING` | Existem arquivos fora do escopo; usuário deve confirmar intencionalidade antes de prosseguir |
| `SCOPE_UNKNOWN` | `features/<feature>/SPEC.md` não existe; impossível decidir escopo sem feature ativa identificada |

# Restrições

- Não reverta arquivos automaticamente.
- Não decida pelo usuário o que é escopo — apenas sinalize.
- Se `features/<feature>/SPEC.md` não existir, produza `SCOPE_UNKNOWN` e peça ao usuário confirmação da feature ativa.