@luanpdd/kit-mcp 1.9.0 → 1.11.0

package/kit/commands/capturar-payloads.md

@@ -0,0 +1,193 @@
+---
+name: capturar-payloads
+description: Invoca payload-capture-instrumenter — instrumenta Edge Function Supabase para captura via mcp__supabase__get_logs por N dias, sanitiza PII, gera fixtures para legacy-characterizer. Modernização 2026.
+argument-hint: "<edge_function_path> [--days N] [--max-payloads N] [--mode instrument|drain|full] [--sanitize-keys k1,k2,...]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Grep
+  - Glob
+  - Task
+  - mcp__supabase__execute_sql
+  - mcp__supabase__get_logs
+---
+
+<objective>
+Instrumentar Edge Function Supabase para capturar **payloads reais** de produção, drenar logs após janela de captura via `mcp__supabase__get_logs`, sanitizar PII deterministicamente, e gerar fixtures prontos para alimentar `/caracterizar`. Invoca o agente [`payload-capture-instrumenter`](../agents/payload-capture-instrumenter.md) que aplica a skill [`legacy-characterization-tests`](../skills/legacy-characterization-tests/SKILL.md) Pattern 7.
+
+**Cria/Atualiza:**
+- Patch na Edge Function adicionando log dedicado controlado por env `CAPTURE_PAYLOADS=true`
+- `supabase/functions/_shared/payload-capture.ts` — sanitização canônica
+- `tests/characterization/<edge-fn>/fixtures/payload-NN.json` — fixtures sanitizados após drenagem
+
+**Após:** o user tem fixtures BASEADOS EM DISTRIBUIÇÃO REAL de produção, não em sintéticos. Cobertura comportamental cresce significativamente.
+</objective>
+
+<context>
+**Argumentos:**
+- `<edge_function_path>` — path da Edge Function (e.g., `supabase/functions/process-orders/index.ts`) — OBRIGATÓRIO
+- `--days N` — janela de captura em dias (default: 7)
+- `--max-payloads N` — máximo de fixtures a salvar (default: 100)
+- `--mode instrument|drain|full` — fase do workflow:
+  - `instrument` — só aplica patch (você faz deploy + aguarda)
+  - `drain` — só drena logs (após capture já rodou em prod)
+  - `full` — patch + aguarda + drena (default — orquestra tudo)
+- `--sanitize-keys k1,k2,k3` — keys adicionais a redact
+
+**Workflow esperado:**
+
+```
+Dia 0:  /capturar-payloads <fn> --mode=instrument
+Dia 0:  Você faz deploy + setar CAPTURE_PAYLOADS=true em env
+Dia 1-7: produção captura naturalmente
+Dia 7:  /capturar-payloads <fn> --mode=drain
+Dia 7:  Fixtures criados em tests/characterization/<fn>/fixtures/
+Dia 7:  /caracterizar <fn> --fixtures-dir tests/characterization/<fn>/fixtures
+```
+
+**Exemplos:**
+```
+/capturar-payloads supabase/functions/webhook-stripe/index.ts                  # full mode 7 dias
+/capturar-payloads supabase/functions/process-orders/index.ts --days 14        # janela maior
+/capturar-payloads supabase/functions/process-orders/index.ts --mode=instrument  # só patch
+/capturar-payloads supabase/functions/process-orders/index.ts --mode=drain      # só drenagem
+```
+
+**Pré-requisitos:**
+- Edge Function deployada em Supabase (modo drain depende de logs em prod)
+- MCP Supabase conectado para drenagem automatizada (alternativa: `supabase functions logs` CLI)
+- Tier full em IDEs com MCP; tier partial degrada para instrumentação only
+
+**Quando preferir este comando vs `/caracterizar` direto:**
+- Edge Function tem alto traffic (≥ 100 req/dia) — distribuição real cobre edge cases que sintético não pega
+- Edge Function tem contrato externo crítico (webhook de Stripe/GitHub) — fidelidade absoluta requer payloads reais
+- Equipe quer baseline empírico antes de refactor — payloads reais > inputs sintéticos
+</context>
+
+<process>
+
+## 1. Parsear argumentos
+
+```bash
+EDGE_FN_PATH=$(echo "$ARGUMENTS" | awk '{print $1}')
+CAPTURE_DAYS=$(echo "$ARGUMENTS" | grep -oE -- '--days [0-9]+' | awk '{print $2}')
+MAX_PAYLOADS=$(echo "$ARGUMENTS" | grep -oE -- '--max-payloads [0-9]+' | awk '{print $2}')
+MODE=$(echo "$ARGUMENTS" | grep -oE -- '--mode[= ][^ ]+' | sed 's/--mode[= ]//')
+SANITIZE_KEYS=$(echo "$ARGUMENTS" | grep -oE -- '--sanitize-keys [^ ]+' | awk '{print $2}')
+
+[ -z "$CAPTURE_DAYS" ]  && CAPTURE_DAYS=7
+[ -z "$MAX_PAYLOADS" ]  && MAX_PAYLOADS=100
+[ -z "$MODE" ]          && MODE="full"
+
+if [ -z "$EDGE_FN_PATH" ]; then
+  echo "ERROR: edge_function_path obrigatório"
+  echo "Uso: /capturar-payloads <path> [opções]"
+  exit 1
+fi
+
+if [ ! -f "$EDGE_FN_PATH" ]; then
+  echo "ERROR: arquivo não encontrado: $EDGE_FN_PATH"
+  exit 1
+fi
+```
+
+## 2. Validar pré-requisitos
+
+```bash
+# verificar Edge Function (Deno + Deno.serve)
+if ! grep -q "Deno.serve" "$EDGE_FN_PATH"; then
+  echo "ERROR: $EDGE_FN_PATH não parece Edge Function (sem Deno.serve)"
+  exit 1
+fi
+
+# detectar projeto Supabase
+PROJECT_ID=""
+if [ -f "supabase/config.toml" ]; then
+  PROJECT_ID=$(grep -E '^project_id\s*=' supabase/config.toml | sed 's/.*= *"\(.*\)".*/\1/' | head -1)
+fi
+
+if [ -z "$PROJECT_ID" ] && [ "$MODE" != "instrument" ]; then
+  echo "WARN: PROJECT_ID não detectado em supabase/config.toml — drenagem pode falhar"
+fi
+```
+
+## 3. Dispatch para `payload-capture-instrumenter`
+
+```text
+Task(
+  subagent_type="payload-capture-instrumenter",
+  prompt="
+edge_function_path: ${EDGE_FN_PATH}
+capture_days: ${CAPTURE_DAYS}
+max_payloads: ${MAX_PAYLOADS}
+mode: ${MODE}
+${SANITIZE_KEYS:+sanitize_keys: ${SANITIZE_KEYS}}
+${PROJECT_ID:+project_id: ${PROJECT_ID}}
+
+Aplicar skill legacy-characterization-tests Pattern 7. Etapas:
+1. Preflight: validar Edge Function, detectar project_id
+2. (mode=instrument|full) Patch Edge Function adicionando log dedicado
+3. (mode=instrument) Output mensagem para fazer deploy + setar CAPTURE_PAYLOADS=true
+4. (mode=drain|full após delay) Drenar logs via mcp__supabase__get_logs
+5. Para cada log entry com kind=payload-capture:
+   - Parse payload sanitized
+   - Salvar em tests/characterization/<fn>/fixtures/payload-NN.json
+6. Pós-processamento: validar nenhum unredacted, sanitização adicional
+7. Output curto + recomendações (review fixtures, /caracterizar, remove flag)
+"
+)
+```
+
+## 4. Pós-output
+
+```
+═══════════════════════════════════════════════════════════
+ framework ► CAPTURAR-PAYLOADS ▸ ${EDGE_FN_PATH}
+═══════════════════════════════════════════════════════════
+
+[output do payload-capture-instrumenter]
+
+## Próximos passos por mode
+
+### Após mode=instrument
+1. Deploy: `supabase functions deploy <name>`
+2. Setar env var: `supabase secrets set CAPTURE_PAYLOADS=true`
+3. Aguardar ${CAPTURE_DAYS} dias
+4. Rodar: `/capturar-payloads ${EDGE_FN_PATH} --mode=drain`
+
+### Após mode=drain ou full
+1. **REVISAR fixtures** manualmente — sample 5-10 arquivos
+2. **VALIDAR no PII vaza:**
+   ```bash
+   grep -E "([0-9]{3}\.[0-9]{3}\.[0-9]{3}-?[0-9]{2}|@.*\..*\.com)" tests/characterization/*/fixtures/*.json
+   ```
+3. **Alimentar legacy-characterizer:**
+   ```bash
+   /caracterizar ${EDGE_FN_PATH} --fixtures-dir tests/characterization/$(basename $(dirname ${EDGE_FN_PATH}))/fixtures
+   ```
+4. **Após characterization gerada:** REMOVE flag CAPTURE_PAYLOADS:
+   ```bash
+   supabase secrets unset CAPTURE_PAYLOADS
+   git revert <commit-instrument>
+   ```
+
+## Cross-suite
+
+- **/caracterizar** (v1.12) — consome fixtures gerados aqui
+- **/instrumentar-fase** (v1.9) — captura é instrumentação shift-left aplicada
+- **/golden-signals** (v1.10) — captura E golden signals podem coexistir mesma Edge Function
+```
+
+</process>
+
+<success_criteria>
+- [ ] $ARGUMENTS parseados (edge_function_path obrigatório, 4 flags opcionais)
+- [ ] Pré-requisitos validados (Deno.serve presente; supabase/config.toml para project_id)
+- [ ] `payload-capture-instrumenter` invocado via Task com mode resolvido
+- [ ] Tier degradation correto (Full = MCP drain; Partial = instrument-only)
+- [ ] Output forwarded transparentemente
+- [ ] Próximos passos específicos por mode (instrument vs drain vs full)
+- [ ] Cross-references com /caracterizar, /instrumentar-fase, /golden-signals
+</success_criteria>

package/kit/commands/caracterizar-prompt.md

@@ -0,0 +1,195 @@
+---
+name: caracterizar-prompt
+description: Characterization de prompts/tools LLM em produção — temperature=0 + seed fixo + sanitização específica. Trata prompts como código legacy. Modernização 2026 sem precedente em 2004.
+argument-hint: "<prompt_file> [--inputs-dir PATH] [--provider openai|anthropic] [--seed N] [--max-tokens N] [--num-intents N]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Grep
+  - Glob
+  - Task
+---
+
+<objective>
+Caracterizar **prompt LLM ou tool definition** capturando outputs determinísticos como golden snapshots. Aplica skill [`ai-prompt-characterization`](../skills/ai-prompt-characterization/SKILL.md) — `temperature=0`, `seed` fixo, sanitização de timestamps/UUIDs/datas relativas, 5+ intents distintas. Trata prompt como **código legacy também** — versionado, testado, code-reviewed.
+
+**Cria/Atualiza:**
+- `tests/characterization/prompts/<prompt-stem>.test.ts` (ou `.py`/`.go` conforme runtime)
+- `tests/characterization/prompts/__snapshots__/<prompt-stem>.test.ts.snap`
+- `tests/characterization/prompts/<prompt-stem>/inputs/<intent>.json` — inputs canônicos por intent
+
+**Após:** mudança em prompt deve manter snapshot diff = 0 (ou mudança documentada). Detecta drift de model upstream automaticamente.
+</objective>
+
+<context>
+**Argumentos:**
+- `<prompt_file>` — arquivo do prompt (e.g., `prompts/generate-summary.md`) — OBRIGATÓRIO
+- `--inputs-dir <path>` — diretório com inputs canônicos por intent (default: agent gera 5 sintéticos cobrindo concise/detailed/code/edge/adversarial)
+- `--provider openai|anthropic` — provider de LLM (default: detecta via deps)
+- `--seed N` — seed para determinismo (default: 42)
+- `--max-tokens N` — limite output (default: 500)
+- `--num-intents N` — número de intents a cobrir (default: 5; mínimo: 5)
+- `--system-prompt <text>` — system prompt se aplicável
+
+**Exemplos:**
+```
+/caracterizar-prompt prompts/generate-summary.md
+/caracterizar-prompt prompts/code-reviewer.md --num-intents 7 --max-tokens 1000
+/caracterizar-prompt prompts/intent-classifier.md --inputs-dir test-data/classifier-intents
+/caracterizar-prompt prompts/customer-support.md --provider anthropic --seed 123
+```
+
+**Pré-requisitos:**
+- ANTHROPIC_API_KEY ou OPENAI_API_KEY em env
+- Test framework (Vitest, Jest, pytest, ...)
+- Provider escolhido suporta `temperature=0` + `seed`
+
+**Quando este comando é o caminho:**
+- Prompt em produção > 50 linhas
+- Mudanças em prompt quebraram silenciosamente no passado
+- Equipe quer baseline antes de refactor de prompt
+- CI deve detectar drift de model upstream (Claude 4.7 → 4.8)
+</context>
+
+<process>
+
+## 1. Parsear argumentos
+
+```bash
+PROMPT_FILE=$(echo "$ARGUMENTS" | awk '{print $1}')
+INPUTS_DIR=$(echo "$ARGUMENTS" | grep -oE -- '--inputs-dir [^ ]+' | awk '{print $2}')
+PROVIDER=$(echo "$ARGUMENTS" | grep -oE -- '--provider [^ ]+' | awk '{print $2}')
+SEED=$(echo "$ARGUMENTS" | grep -oE -- '--seed [0-9]+' | awk '{print $2}')
+MAX_TOKENS=$(echo "$ARGUMENTS" | grep -oE -- '--max-tokens [0-9]+' | awk '{print $2}')
+NUM_INTENTS=$(echo "$ARGUMENTS" | grep -oE -- '--num-intents [0-9]+' | awk '{print $2}')
+
+[ -z "$SEED" ]         && SEED=42
+[ -z "$MAX_TOKENS" ]   && MAX_TOKENS=500
+[ -z "$NUM_INTENTS" ]  && NUM_INTENTS=5
+
+if [ -z "$PROMPT_FILE" ]; then
+  echo "ERROR: prompt_file obrigatório"
+  exit 1
+fi
+
+if [ ! -f "$PROMPT_FILE" ]; then
+  echo "ERROR: arquivo não encontrado: $PROMPT_FILE"
+  exit 1
+fi
+```
+
+## 2. Detectar provider + framework
+
+```bash
+# auto-detect provider
+if [ -z "$PROVIDER" ]; then
+  if [ -n "$ANTHROPIC_API_KEY" ]; then
+    PROVIDER="anthropic"
+  elif [ -n "$OPENAI_API_KEY" ]; then
+    PROVIDER="openai"
+  else
+    echo "ERROR: nenhum provider detectado. Setar ANTHROPIC_API_KEY ou OPENAI_API_KEY"
+    exit 1
+  fi
+fi
+
+# detectar test framework
+FRAMEWORK=""
+if [ -f "package.json" ]; then
+  if jq -re '.devDependencies.vitest' package.json >/dev/null 2>&1; then FRAMEWORK="vitest"
+  elif jq -re '.devDependencies.jest' package.json >/dev/null 2>&1; then FRAMEWORK="jest"
+  fi
+elif [ -f "pyproject.toml" ]; then
+  FRAMEWORK="pytest"
+fi
+
+[ -z "$FRAMEWORK" ] && FRAMEWORK="vitest"  # default sane
+```
+
+## 3. Dispatch para `legacy-characterizer` (modo prompt)
+
+```text
+Task(
+  subagent_type="legacy-characterizer",
+  prompt="
+target_file: ${PROMPT_FILE}
+target_kind: prompt
+provider: ${PROVIDER}
+seed: ${SEED}
+max_tokens: ${MAX_TOKENS}
+num_intents: ${NUM_INTENTS}
+${INPUTS_DIR:+inputs_dir: ${INPUTS_DIR}}
+framework: ${FRAMEWORK}
+
+Aplicar skill ai-prompt-characterization. Etapas:
+1. Ler prompt + identificar inputs esperados (system prompt? user message format? tools?)
+2. Gerar (ou ler de inputs-dir) ${NUM_INTENTS}+ inputs cobrindo intents distintas:
+   - concise: pedido curto, output esperado curto
+   - detailed: pedido elaborado, output esperado longo
+   - code-heavy: input/output com código
+   - edge case: input ambíguo
+   - adversarial: prompt injection attempt
+3. Para cada intent: rodar LLM com temperature=0 + seed=${SEED}
+4. Capturar text + finishReason + toolCalls (se function calling) + inputTokens + outputTokens + modelVersion
+5. Sanitizar: timestamps, UUIDs, datas relativas, valores monetários, versões
+6. Salvar como snapshot tests usando ${FRAMEWORK}
+7. Cobertura behavioral = % intents cobertas (não % linhas)
+"
+)
+```
+
+## 4. Pós-output
+
+```
+═══════════════════════════════════════════════════════════
+ framework ► CARACTERIZAR-PROMPT ▸ tests/characterization/prompts/...
+═══════════════════════════════════════════════════════════
+
+[output do legacy-characterizer em modo prompt]
+
+## ⚠ REVISÃO MANUAL OBRIGATÓRIA
+
+Snapshots gerados — leia cada um antes de commit:
+1. Verificar nenhum PII/secret persiste pós-sanitização
+2. Verificar nenhum timestamp/UUID/data relativa unredacted
+3. Confirmar finishReason esperado (stop vs length vs tool_use)
+4. Para tool_uses: confirmar tool name + input shape
+
+## Próximos passos
+
+1. **Revisar snapshots** manualmente
+2. **Rodar suite local:**
+   - JS/TS: `npm test -- tests/characterization/prompts`
+   - Python: `pytest tests/characterization/prompts`
+3. **Commit** como `chore: characterize <prompt-name>`
+4. **Configurar CI:**
+   - `tests/characterization/prompts/**` rodam em PR que toca `prompts/**`
+   - Diff vermelho = mudança comportamental detectada → review humano
+5. **Configurar nightly** para detectar drift de model upstream:
+   - Anthropic publica Claude 4.8 → re-run characterization → snapshot diff
+6. **Custo:** ~${NUM_INTENTS} × ($0.015/1k input tokens × 2k = $0.03 + output) ≈ $0.10-0.50/run
+
+## Cross-suite
+
+- **/caracterizar** (v1.12) — characterization de código (não prompt) — análogo
+- **`llm-as-dependency`** skill — fakear LLM em business logic tests (não esses tests)
+- **`legacy-api-only-applications`** skill — LLM provider é caso especial de API external
+- **/instrumentar-fase** (v1.9) — instrumenta consumer de prompt (latency, tokens)
+```
+
+</process>
+
+<success_criteria>
+- [ ] $ARGUMENTS parseados
+- [ ] Provider detectado automaticamente OU especificado
+- [ ] Framework de teste detectado
+- [ ] `legacy-characterizer` invocado em modo prompt
+- [ ] ≥ 5 intents cobrindo grupos canônicos (concise/detailed/code/edge/adversarial)
+- [ ] temperature=0 + seed=fixo aplicado
+- [ ] Sanitização específica para outputs LLM aplicada
+- [ ] Tests rodam contra LLM real apenas em characterization (não em business logic tests)
+- [ ] Próximos passos: review, commit, CI config, nightly drift detection
+- [ ] Cross-suite com llm-as-dependency e legacy-api-only-applications
+</success_criteria>

package/kit/commands/caracterizar.md

@@ -0,0 +1,212 @@
+---
+name: caracterizar
+description: Invoca legacy-characterizer — gera characterization tests (cap 13 Feathers) capturando comportamento atual como golden snapshots; cobre 5+ grupos de equivalência canônicos; valida cobertura via mutation testing.
+argument-hint: "<target_file> [--symbol <name>] [--min-inputs N] [--gap-fill] [--fixtures-dir <path>] [--no-mutation]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Grep
+  - Glob
+  - Task
+---
+
+<objective>
+Caracterizar arquivo de código legado (sem testes) gerando suite de characterization tests que congelam comportamento atual como oracle imutável durante refactor. Invoca o agente [`legacy-characterizer`](../agents/legacy-characterizer.md) que aplica a skill [`legacy-characterization-tests`](../skills/legacy-characterization-tests/SKILL.md) — 7 grupos canônicos de equivalência (empty/typical/boundary-low/boundary-up/recoverable-invalid/fatal-invalid/side-effect-heavy), golden snapshots com sanitização de PII, validação behavioral via mutation testing.
+
+**Cria/Atualiza:**
+- `tests/characterization/<file_stem>/` — suite de testes + snapshots + fakes auxiliares
+- `tests/characterization/<file_stem>/README.md` — anotações de bugs preservados, fonte do oracle
+
+**Após:** o user tem safety net que detecta regressão imediata em refactor. Gate `refactor-safety-auditor` muda de BLOCK → GO. Refactor pode prosseguir com `cover-and-modify` em vez de `edit-and-pray`.
+</objective>
+
+<context>
+**Argumentos:**
+- `<target_file>` — caminho do arquivo a caracterizar (relativo ao project root) — OBRIGATÓRIO
+- `--symbol <name>` — caracterizar apenas símbolo específico (default: todos os exports)
+- `--min-inputs N` — número mínimo de inputs (default: 8)
+- `--gap-fill` — modo gap-fill: caracterizar APENAS o que falta para atingir 70% behavioral coverage (não recriar o que existe)
+- `--fixtures-dir <path>` — diretório de payloads reais capturados (substitui inputs sintéticos por reais)
+- `--no-mutation` — skip mutation testing após geração (default: roda se ferramenta detectada)
+- `--output-dir <path>` — diretório base de output (default: `tests/characterization/<file_stem>/`)
+
+**Exemplos:**
+```
+/caracterizar src/orders/handler.ts                        # caracterização completa, defaults
+/caracterizar src/orders/handler.ts --symbol processOrder  # só um método
+/caracterizar src/orders/handler.ts --gap-fill             # só preenche lacunas (re-rodar pós-refactor)
+/caracterizar supabase/functions/webhook/index.ts \
+  --fixtures-dir .planning/captured-payloads/webhook        # usa payloads reais
+```
+
+**Pré-requisitos:**
+- Arquivo deve compilar/parsear no projeto atual
+- Test framework instalado (Vitest, Jest, pytest, JUnit, go-test, etc.)
+- (Recomendado) ferramenta de mutation testing instalada — Stryker (JS/TS), mutmut (Py), Pitest (Java)
+- (Opcional) coverage tool com summary acessível (Istanbul/c8 para JS, coverage.py, JaCoCo)
+
+**Quando este comando é o caminho certo:**
+- Arquivo > 200 linhas com cobertura < 60% e mudança comportamental planejada
+- Webhook/edge function/API pública sendo modificada
+- Gate `refactor-safety-auditor` retornou BLOCK
+- Refactor de monster method (cap 22) iniciando
+
+**Quando NÃO é o caminho:**
+- Arquivo trivial (< 50 linhas, sem branches significativas) — testes diretos sem ceremonial
+- Mudança é apenas adicionar comportamento (sprout/wrap) — usar `/refactor-seguro --mode=sprout`
+- Mudança é apenas mecânica (rename, extract-contiguous-block) — usar `/refactor-seguro --mode=safe-extract`
+- Bug fix com TDD — TDD test do COMPORTAMENTO CORRETO é o caminho, não characterization
+</context>
+
+<process>
+
+## 1. Parsear argumentos
+
+```bash
+# PT-BR: extrair primeiro positional como target_file
+TARGET_FILE=$(echo "$ARGUMENTS" | awk '{print $1}')
+SYMBOL=$(echo "$ARGUMENTS" | grep -oE -- '--symbol [^ ]+' | awk '{print $2}')
+MIN_INPUTS=$(echo "$ARGUMENTS" | grep -oE -- '--min-inputs [0-9]+' | awk '{print $2}')
+FIXTURES_DIR=$(echo "$ARGUMENTS" | grep -oE -- '--fixtures-dir [^ ]+' | awk '{print $2}')
+OUTPUT_DIR=$(echo "$ARGUMENTS" | grep -oE -- '--output-dir [^ ]+' | awk '{print $2}')
+GAP_FILL=false
+NO_MUTATION=false
+
+echo "$ARGUMENTS" | grep -qE -- '--gap-fill'     && GAP_FILL=true
+echo "$ARGUMENTS" | grep -qE -- '--no-mutation'  && NO_MUTATION=true
+
+[ -z "$MIN_INPUTS" ] && MIN_INPUTS=8
+
+if [ -z "$TARGET_FILE" ]; then
+  echo "ERROR: target_file é obrigatório."
+  echo "Uso: /caracterizar <target_file> [opções]"
+  exit 1
+fi
+
+if [ ! -f "$TARGET_FILE" ]; then
+  echo "ERROR: arquivo não encontrado: $TARGET_FILE"
+  exit 1
+fi
+```
+
+## 2. Validar pré-requisitos
+
+```bash
+# PT-BR: detectar test framework + alertar se ausente
+FRAMEWORK_OK=false
+case "$TARGET_FILE" in
+  *.ts|*.tsx|*.js|*.jsx|*.mjs)
+    if [ -f "package.json" ]; then
+      jq -re '.devDependencies | (.vitest // .jest)' package.json >/dev/null 2>&1 && FRAMEWORK_OK=true
+    fi
+    ;;
+  *.py)
+    pip show pytest >/dev/null 2>&1 && FRAMEWORK_OK=true
+    ;;
+  *.java)
+    [ -f pom.xml ] || [ -f build.gradle ] && FRAMEWORK_OK=true
+    ;;
+  *.go)
+    [ -f go.mod ] && FRAMEWORK_OK=true
+    ;;
+esac
+
+if [ "$FRAMEWORK_OK" = false ]; then
+  echo "⚠ Test framework não detectado. Agent pode gerar testes mas execução exigirá setup."
+fi
+
+# PT-BR: avisar se gap-fill mas não há characterization existente
+if [ "$GAP_FILL" = true ]; then
+  STEM=$(basename "$TARGET_FILE" | sed 's/\.[^.]*$//')
+  if ! find tests test __tests__ -path "*characterization*$STEM*" 2>/dev/null | head -1 | grep -q .; then
+    echo "⚠ --gap-fill solicitado mas nenhum characterization existente encontrado."
+    echo "  Caindo em modo full-characterization."
+    GAP_FILL=false
+  fi
+fi
+```
+
+## 3. Dispatch para `legacy-characterizer`
+
+```text
+Task(
+  subagent_type="legacy-characterizer",
+  prompt="
+target_file: ${TARGET_FILE}
+${SYMBOL:+target_symbol: ${SYMBOL}}
+min_inputs: ${MIN_INPUTS}
+${FIXTURES_DIR:+payload_fixtures_dir: ${FIXTURES_DIR}}
+${OUTPUT_DIR:+output_dir: ${OUTPUT_DIR}}
+mutation_check: $([ "$NO_MUTATION" = true ] && echo false || echo true)
+mode: $([ "$GAP_FILL" = true ] && echo gap-fill || echo full)
+
+Aplicar skill legacy-characterization-tests. Etapas canônicas:
+1. Análise estática: identificar exports, parâmetros, deps de I/O, side effects, branches
+2. Aplicar 7 grupos de equivalência canônicos (ou substituir por payloads reais se fixtures-dir fornecido)
+3. Construir fakes mínimos para deps de I/O (DB, HTTP, FS, clock, random, UUID)
+4. Executar código real com cada input + fakes; capturar return + sideEffects
+5. Sanitizar (PII, secrets, UUIDs voláteis) antes de salvar como snapshot
+6. Imprimir warning de revisão obrigatória dos snapshots
+7. Validar cobertura behavioral via mutation testing (Stryker/mutmut/Pitest)
+8. Output: tests/characterization/<file_stem>/ + README.md
+
+Modo gap-fill (se aplicável): caracterizar APENAS branches/paths não cobertos pela suite existente; NÃO recriar tests existentes.
+"
+)
+```
+
+## 4. Pós-output: revisão obrigatória + integração com gate
+
+Após o agent completar:
+
+```
+═══════════════════════════════════════════════════════════
+ framework ► CARACTERIZAR ▸ tests/characterization/<file_stem>/
+═══════════════════════════════════════════════════════════
+
+[output do legacy-characterizer]
+
+## ⚠ REVISÃO MANUAL OBRIGATÓRIA dos snapshots
+
+Localização: tests/characterization/<file_stem>/__snapshots__/
+
+Steps antes de commit:
+  1. Ler cada snapshot linha por linha
+  2. Marcar bugs conhecidos como comments inline (// BUG #X: ...)
+  3. Verificar redaction de PII/secrets adicional
+  4. Confirmar zero secrets/UUIDs locais expostos
+
+Não commitar como `chore: characterize <file>` sem revisão.
+
+## Próximos passos
+
+1. **Revisar snapshots** — manualmente, todos os arquivos em __snapshots__/
+2. **Rodar suite** — verificar todos verdes:
+   - JS/TS: `npm test -- tests/characterization/<file_stem>`
+   - Python: `pytest tests/characterization/<file_stem>`
+   - Java: `mvn test -Dtest='Characterization*'`
+3. **Commit** — `chore: characterize <file_stem>` (PR separado, NÃO misturar com refactor)
+4. **Re-auditar gate** — `/auditar-refactor <file>` deve agora retornar GO
+5. **Iniciar refactor** — `/refactor-seguro <file>` (ou diretamente PR de refactor)
+
+## Cross-suite
+
+- Para sprout/wrap em vez de full characterization: `/refactor-seguro --mode=sprout <file>`
+- Para safe-extract em vez de behavioral change: `/refactor-seguro --mode=safe-extract <file>`
+- Para SLO protection durante refactor: `/instrumentar-fase` (v1.9 — captura behavioral diff)
+```
+
+</process>
+
+<success_criteria>
+- [ ] $ARGUMENTS parseados (target_file obrigatório, 7 flags opcionais)
+- [ ] Pré-requisitos validados (framework de teste detectado; warning se não)
+- [ ] `legacy-characterizer` invocado via `Task(subagent_type=...)` com prompt completo (8 etapas)
+- [ ] `tests/characterization/<file_stem>/` criado com tests + snapshots + fakes + README
+- [ ] Output forwarded transparentemente do agent
+- [ ] Warning de revisão manual emitido (snapshots NÃO são committed automaticamente)
+- [ ] Próximos passos sugeridos: revisar, rodar, commitar, re-auditar gate, iniciar refactor
+- [ ] Modo gap-fill respeitado se solicitado e characterization existente encontrada
+</success_criteria>