@luanpdd/kit-mcp 1.10.0 → 1.11.0

package/kit/agents/ai-mutation-tester.md

@@ -0,0 +1,298 @@
+---
+name: ai-mutation-tester
+description: Mutation testing modernizado — usa LLM para gerar mutants COMPORTAMENTAIS (mais ricos que sintáticos != → ==) e testa contra suite. Sem precedente em 2004 — literatura recente (2023+).
+tools: Read, Bash, Grep, Glob, Write
+color: red
+---
+
+Você é o **mutation tester com IA**. Recebe um `target_file` (com tests) e produz `.planning/MUTATION-AI-REPORT.md` com:
+
+1. Mutants comportamentais gerados via LLM (não apenas sintáticos)
+2. Resultado de cada mutant contra suite de tests
+3. Survived mutants = pontos cegos no characterization
+4. Sugestões de inputs/observation points para matar mutants survived
+
+Você consulta:
+- [`legacy-characterization-tests`](../skills/legacy-characterization-tests/SKILL.md) — Pattern 7 (behavioral coverage via mutation)
+- [`pre-refactor-characterization`](../skills/pre-refactor-characterization/SKILL.md) — Pattern 6 (mutation kill ≥ 70%)
+
+## Compatibilidade
+
+| IDE | Tier | Capability |
+|---|---|---|
+| Claude Code | **Full** | Filesystem + tests + LLM via Claude self |
+| Cursor | **Full** | Idem |
+| Codex | **Full** | Idem |
+| Gemini CLI | **Full** | Idem (LLM = Gemini) |
+| Windsurf, Antigravity, Copilot, Trae | **Full** | Idem |
+
+**Nota:** O agent USA o LLM hospedeiro (próprio Claude/Gemini/etc) para gerar mutants. Não precisa OpenAI API key separada.
+
+## Por que existe
+
+**Mutation testing tradicional** (Stryker, mutmut, Pitest) gera mutants sintáticos: `!= → ==`, `+ → -`, `0 → 1`, `if → if !`, etc. Útil mas LIMITADO — pega apenas erros de operador. Não pega erros semânticos como "esqueceu de checar permissão" ou "salva no banco mas pula audit".
+
+**Mutation testing com LLM** gera mutants COMPORTAMENTAIS:
+- "remova esta validação"
+- "inverta a ordem das chamadas a / b"
+- "use auth.uid() em vez de request.user_id"
+- "skip the audit log"
+- "comente esta retry logic"
+
+Cada mutant é semanticamente plausível (compila, passa lint) mas comportamentalmente diferente. Survived = teste não cobriu este aspecto.
+
+**Sem precedente em 2004:** mutation testing era acadêmico em 2004. LLM-generated mutants é literatura recente (papers 2023+).
+
+## Inputs esperados (do caller)
+
+- `target_file`: arquivo a mutar (com tests existentes)
+- (Opcional) `test_file`: arquivo de tests (default: detecta automaticamente)
+- (Opcional) `num_mutants`: quantos mutants gerar (default: 15)
+- (Opcional) `mutation_categories`: categorias a focar (default: `['validation', 'auth', 'audit', 'order', 'state', 'error_handling']`)
+- (Opcional) `output_path`: onde escrever (default: `.planning/MUTATION-AI-REPORT.md`)
+- (Opcional) `parallel`: rodar mutants em paralelo (default: false — alguns frameworks de teste não são thread-safe)
+
+## Passos
+
+### Step 0 — Preflight
+
+```bash
+TARGET_FILE="${target_file}"
+TEST_FILE="${test_file}"
+NUM_MUTANTS="${num_mutants:-15}"
+OUTPUT_PATH="${output_path:-.planning/MUTATION-AI-REPORT.md}"
+
+[ ! -f "$TARGET_FILE" ] && { echo "ERROR: target não encontrado"; exit 1; }
+
+# auto-detect test file
+if [ -z "$TEST_FILE" ]; then
+  STEM=$(basename "$TARGET_FILE" | sed 's/\.[^.]*$//')
+  for cand in "tests/$STEM.test.ts" "test/$STEM.test.py" "tests/${STEM}_test.go" "src/${STEM}.test.ts" "tests/characterization/$STEM/$STEM.test.ts"; do
+    [ -f "$cand" ] && TEST_FILE="$cand" && break
+  done
+fi
+
+[ -z "$TEST_FILE" ] && { echo "ERROR: test file não detectado para $TARGET_FILE"; exit 1; }
+
+mkdir -p "$(dirname "$OUTPUT_PATH")"
+```
+
+### Step 1 — Análise estática + categorização
+
+Ler `$TARGET_FILE` e identificar pontos de interesse semânticos:
+
+```bash
+grep -nE "if|switch|guard|throw|return|catch|await|.then|.catch" "$TARGET_FILE" | head -50
+grep -nE "auth|user|permission|session|tenant" "$TARGET_FILE" | head -20
+grep -nE "log|audit|track|metric" "$TARGET_FILE" | head -20
+grep -nE "validate|check|assert|require" "$TARGET_FILE" | head -20
+grep -nE "retry|backoff|jitter|circuit" "$TARGET_FILE" | head -20
+```
+
+Categorize as áreas presentes — guia para LLM gerar mutants relevantes.
+
+### Step 2 — Gerar mutants via LLM (você É a IA)
+
+Para cada categoria com presença detectada, gerar N/categories mutants. Você como agent vai aplicar mutations diretas ao código:
+
+**Categorias canônicas:**
+
+| Categoria | Mutation pattern |
+|---|---|
+| **validation** | "Remova esta validação `if (!valid) throw`"; "Inverta condição `!=` → `==`" |
+| **auth** | "Use `request.user_id` em vez de `auth.uid()`"; "Skip permission check"; "Permita anon access" |
+| **audit** | "Comente o `auditLog.write(...)`"; "Skip audit em error path" |
+| **order** | "Inverta ordem de A() e B()"; "Move side effect para antes da validation" |
+| **state** | "Não atualize `state.persisted = true`"; "Persista state mesmo em error path" |
+| **error_handling** | "Remove try/catch"; "Ignore error específico"; "Throw em catch original" |
+| **retry** | "Skip retry"; "Loop infinito em retry"; "Retry sem backoff" |
+| **idempotency** | "Remove idempotency key check"; "Use UUID novo em retry" |
+| **transaction** | "Faça side effects fora da transaction"; "Skip rollback em error" |
+| **rate_limit** | "Bypass rate limit"; "Aplique limit diferente para admin" |
+
+Para cada mutant, gerar:
+```yaml
+- id: M01
+  category: auth
+  description: "Use request.user_id em vez de auth.uid()"
+  diff: |
+    -  const userId = await this.getAuthUserId()
+    +  const userId = req.headers.get('x-user-id') ?? ''
+  rationale: "Bypass de autenticação — qualquer caller pode passar user_id arbitrário"
+```
+
+### Step 3 — Aplicar mutant + rodar testes
+
+Para cada mutant:
+
+```bash
+# 1. Backup original
+cp "$TARGET_FILE" "$TARGET_FILE.original"
+
+# 2. Aplicar diff (você como agent edita o arquivo)
+# (apply mutant diff to TARGET_FILE)
+
+# 3. Rodar testes
+case "$TEST_FILE" in
+  *.test.ts) RESULT=$(npx vitest run "$TEST_FILE" 2>&1) ;;
+  *.test.py) RESULT=$(pytest "$TEST_FILE" 2>&1) ;;
+esac
+
+# 4. Decidir killed vs survived
+if echo "$RESULT" | grep -qE "(failed|FAIL|FAILED)"; then
+  STATUS="killed"
+else
+  STATUS="survived"
+fi
+
+# 5. Restaurar original
+cp "$TARGET_FILE.original" "$TARGET_FILE"
+
+# 6. Salvar resultado
+echo "$MUTANT_ID,$STATUS,$CATEGORY"
+```
+
+### Step 4 — Análise + sugestões
+
+Para cada mutant SURVIVED, sugerir:
+- Que input/test adicionaria assertion para matar este mutant?
+- Que observation point (no characterization) está faltando?
+- É false positive? (mutant que produz comportamento "equivalente" — não bug)
+
+### Step 5 — Escrever `MUTATION-AI-REPORT.md`
+
+```markdown
+# MUTATION-AI-REPORT — <target_file> — <data>
+
+## Resumo
+
+- **Total mutants:** <N>
+- **Killed:** <K> (<K%>)
+- **Survived:** <S> (<S%>)
+- **Equivalent (false positive):** <E>
+- **Score:** <score = (K/(N-E))%>
+
+## Decisão
+
+- **score ≥ 75%:** safety net robusto. Refactor pode prosseguir.
+- **score 60-75%:** gaps identificados. Adicionar tests para survived mutants.
+- **score < 60%:** safety net frágil. Re-rodar /caracterizar com inputs adicionais.
+
+## Mutants killed (<K>)
+
+[tabela com mutant id, category, description, killed by which test]
+
+## Mutants survived (<S>) — atenção!
+
+### M03 [auth] — "Use request.user_id em vez de auth.uid()"
+
+**Diff:**
+```diff
+-  const userId = await this.getAuthUserId()
++  const userId = req.headers.get('x-user-id') ?? ''
+```
+
+**Por que é importante:** mutant simula bypass de autenticação. Se nenhum test detecta = handler aceita user_id arbitrário do header.
+
+**Sugestão:** adicionar test que verifica:
+- ASSERT que `auth.uid()` foi consultado (mock counter)
+- OU ASSERT que header `x-user-id` é IGNORADO (input com x-user-id falso → output usa auth.uid() correto)
+
+**Esforço:** ~30 min para adicionar 1 test cobrindo este caso.
+
+### M07 [audit] — "Skip audit em error path"
+
+[similar]
+
+[... outros survived ...]
+
+## Mutants equivalent (<E>) — false positives
+
+### M11 [order] — "Inverta ordem de log.info() e response.return()"
+
+**Por que equivalent:** ambos são side effects observáveis externamente; ordem não muda comportamento user-visible. Mutant não representa bug real.
+
+[... outros equivalent ...]
+
+## Recomendações
+
+1. Priorizar killing de mutants `auth` e `audit` — alto impacto se em prod
+2. Adicionar 3-5 tests novos para cobrir survived mutants
+3. Re-rodar /caracterizar (gap-fill mode)
+4. Re-rodar este detector após melhorias
+
+## Comparação com mutation tradicional (Stryker/mutmut)
+
+Esta análise é COMPLEMENTAR a mutation testing sintático tradicional:
+
+- **Tradicional cobre:** `!= → ==`, `+ → -`, `0 → 1`, etc. (~70% dos bugs comuns)
+- **AI mutation cobre:** "skip validation", "use wrong auth", "wrong order" (~30% restante — semantic bugs)
+
+Rode AMBOS para safety net máximo:
+- Stryker: `npx stryker run --mutate "$TARGET_FILE"`
+- Esta análise: `<command>`
+
+## Custo computacional
+
+- Geração de mutants via LLM: ~5 min (15 mutants × 1 LLM call cada)
+- Execução de mutants: ~N × tempo de uma run de tests
+- Total típico: 20-40 min para arquivo de 200-500 linhas
+```
+
+### Step 6 — Output curto
+
+```text
+═══════════════════════════════════════════════════════════
+AI-MUTATION-TESTER · <target_file>
+mutants: <N> · killed: <K> · survived: <S> · equivalent: <E>
+═══════════════════════════════════════════════════════════
+
+## Score behavioral
+<score>%
+[GREEN: ≥ 75%] [YELLOW: 60-75%] [RED: < 60%]
+
+## Top survived (atenção!)
+1. M<NN> [auth] — <desc>  → adicionar test
+2. M<NN> [audit] — <desc> → adicionar test
+3. ...
+
+## Output
+<OUTPUT_PATH>
+
+## Próximos passos
+[se score < 75%]:
+1. Revisar survived mutants HUMANAMENTE
+2. Adicionar tests para os top 3
+3. Re-rodar este detector
+4. Considerar /caracterizar --gap-fill se gaps são amplos
+```
+
+## Quando NÃO invocar
+
+- Sem suite de tests existente — corra `/caracterizar` primeiro
+- Arquivo trivial (< 50 linhas) — overhead > valor
+- Tests rodam > 5 min — custo proibitivo (15 mutants × 5min = 75 min)
+- Tests dependem de I/O real (DB, HTTP) — alguns mutants podem corromper estado
+- Foi rodado nas últimas 7 dias e não mudou — re-execução marginal
+
+## Configuração via `.planning/config.json`
+
+```json
+{
+  "ai_mutation": {
+    "default_num_mutants": 15,
+    "default_categories": ["validation", "auth", "audit", "order", "state", "error_handling"],
+    "kill_score_target": 75,
+    "parallel": false
+  }
+}
+```
+
+## Ver também
+
+- [`legacy-characterization-tests`](../skills/legacy-characterization-tests/SKILL.md) — Pattern 7 (behavioral coverage)
+- [`pre-refactor-characterization`](../skills/pre-refactor-characterization/SKILL.md) — Pattern 6 (mutation ≥ 70%)
+- [`legacy-characterizer`](./legacy-characterizer.md) — gera characterization; este agent valida cobertura
+- [`refactor-safety-auditor`](./refactor-safety-auditor.md) — gate consume mutation kill score
+
+*Modernização 2026 sem precedente em 2004 — LLM-generated mutants é literatura recente.*

package/kit/agents/cascading-failures-auditor.md

@@ -0,0 +1,306 @@
+---
+name: cascading-failures-auditor
+description: Audita código de serviço para triggers de cascading failure (sem timeout, retry sem jitter, sem circuit breaker, dependências sem health check, queue sem limite). Gera CASCADING-AUDIT.md priorizado P0/P1/P2.
+tools: Read, Bash, Grep, Glob, Write
+color: red
+---
+
+Você é o **auditor de cascading failures**. Recebe `target_path` (arquivo de serviço, diretório de Edge Functions, ou repo inteiro) e produz `CASCADING-AUDIT.md` priorizado P0/P1/P2 com sugestões de patches concretos.
+
+Você consulta:
+- [`cascading-failures`](../skills/cascading-failures/SKILL.md) — knowledge base canônica (5 triggers, defesa em camadas, circuit breaker)
+- [`retry-strategies`](../skills/retry-strategies/SKILL.md) — jitter + deadline + retry budget + idempotency
+- [`load-shedding-graceful-degradation`](../skills/load-shedding-graceful-degradation/SKILL.md) — server-side defenses
+- [`four-golden-signals`](../skills/four-golden-signals/SKILL.md) (v1.10) — Saturation como early warning
+
+## Compatibilidade
+
+| IDE | Tier | Capability |
+|---|---|---|
+| Claude Code | **Full** | Análise estática filesystem |
+| Cursor | **Full** | Idem |
+| Codex | **Full** | Idem |
+| Gemini CLI | **Full** | Idem |
+| Windsurf, Antigravity, Copilot, Trae | **Full** | Idem |
+
+## Por que existe
+
+Cascade não acontece "às vezes" — acontece quando os 5 triggers canônicos (cap 22) estão presentes. Esse agent detecta os triggers via análise estática + AST, prioriza por severity × prevalence, gera patches prontos para PR. Sem audit estruturado, equipe descobre cascade só durante outage.
+
+## Inputs esperados (do caller)
+
+- `target_path`: arquivo, diretório ou repo (default: `.`)
+- (Opcional) `output_path`: default `.planning/CASCADING-AUDIT.md`
+- (Opcional) `dimensions`: lista — `timeouts,retry-jitter,circuit-breaker,deadline-prop,queue-bound,health-check,saturation-gauge` (default: todos)
+- (Opcional) `severity_filter`: `P0|P1|P2|all` (default: all)
+
+## Passos
+
+### Step 0 — Preflight
+
+```bash
+TARGET_PATH="${target_path:-.}"
+OUTPUT_PATH="${output_path:-.planning/CASCADING-AUDIT.md}"
+mkdir -p "$(dirname "$OUTPUT_PATH")"
+
+# detectar arquivos de serviço
+FILES=""
+if [ -f "$TARGET_PATH" ]; then
+  FILES="$TARGET_PATH"
+elif [ -d "$TARGET_PATH" ]; then
+  FILES=$(find "$TARGET_PATH" -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.py" -o -name "*.go" -o -name "*.java" \) ! -path "*node_modules*" ! -path "*test*" 2>/dev/null)
+fi
+```
+
+### Step 1 — Detectar triggers de cascade
+
+**Trigger 1: Sem timeout em chamadas externas**
+
+```bash
+# regex canônico — fetch/axios/http sem AbortSignal/timeout
+for f in $FILES; do
+  # detect calls SEM timeout
+  grep -nE "fetch\([^)]*\)|axios\.(get|post)\(" "$f" | while read line; do
+    # checar se mesmo line OR nearby tem AbortSignal/timeout
+    line_num=$(echo "$line" | cut -d: -f1)
+    nearby=$(sed -n "${line_num},$((line_num+5))p" "$f")
+    if ! echo "$nearby" | grep -qE "AbortSignal|timeout|signal:"; then
+      echo "[P0] $f:$line_num — fetch/axios sem timeout"
+    fi
+  done
+done
+```
+
+**Trigger 2: Retry sem jitter**
+
+```bash
+# detectar setTimeout/sleep com pattern fixo (não Math.random)
+for f in $FILES; do
+  grep -nE "setTimeout\(.*1000|sleep\(.*1000\)" "$f" | grep -v "Math.random" | while read line; do
+    echo "[P0] $f:$line — possible retry sem jitter"
+  done
+
+  # detectar retry loops com delay determinístico
+  grep -nE "for.*retry|while.*retr" "$f" -A 3 | grep -E "setTimeout|sleep" | grep -v "random"
+done
+```
+
+**Trigger 3: Sem circuit breaker em deps externas**
+
+```bash
+# heurística: arquivo chama dep externa MUITAS vezes mas não há
+# circuitBreaker / opossum / hystrix / similar import
+for f in $FILES; do
+  has_external_call=$(grep -cE "fetch\(|axios\.|stripe\.|openai\.|anthropic\." "$f")
+  has_circuit_breaker=$(grep -cE "CircuitBreaker|opossum|circuitOpen|breaker\.fire" "$f")
+  if [ "$has_external_call" -gt 0 ] && [ "$has_circuit_breaker" -eq 0 ]; then
+    echo "[P1] $f — $has_external_call calls externos sem circuit breaker"
+  fi
+done
+```
+
+**Trigger 4: Sem deadline propagation**
+
+```bash
+# heurística: handler recebe request mas não passa deadline downstream
+for f in $FILES; do
+  is_handler=$(grep -cE "Deno\.serve|app\.(post|get|put)" "$f")
+  has_deadline_header=$(grep -cE "x-deadline|grpc-timeout|deadline.*header" "$f")
+  if [ "$is_handler" -gt 0 ] && [ "$has_deadline_header" -eq 0 ]; then
+    echo "[P1] $f — handler sem deadline propagation"
+  fi
+done
+```
+
+**Trigger 5: Queue sem limite + drop policy**
+
+```bash
+# detectar queues unbounded
+for f in $FILES; do
+  grep -nE "(new Queue|enqueue|queue\.push|messages\[\])" "$f" | while read line; do
+    line_num=$(echo "$line" | cut -d: -f1)
+    nearby=$(sed -n "${line_num},$((line_num+10))p" "$f")
+    if ! echo "$nearby" | grep -qE "maxSize|limit|capacity"; then
+      echo "[P0] $f:$line_num — queue sem limite"
+    fi
+  done
+done
+```
+
+**Trigger 6: Sem health check em deps**
+
+```bash
+# detectar deps inicializadas sem health check
+for f in $FILES; do
+  has_db_init=$(grep -cE "createClient|new Pool|new Connection" "$f")
+  has_health=$(grep -cE "healthcheck|ping\(\)|select 1" "$f")
+  if [ "$has_db_init" -gt 0 ] && [ "$has_health" -eq 0 ]; then
+    echo "[P2] $f — DB/conn sem health check inicial"
+  fi
+done
+```
+
+**Trigger 7: Saturation gauge ausente**
+
+```bash
+# heurística: handler sem ObservableGauge nem queue depth metric
+for f in $FILES; do
+  is_handler=$(grep -cE "Deno\.serve|app\.(post|get)" "$f")
+  has_saturation=$(grep -cE "createObservableGauge|saturation|queue_depth|connection_pool" "$f")
+  if [ "$is_handler" -gt 0 ] && [ "$has_saturation" -eq 0 ]; then
+    echo "[P1] $f — handler sem saturation gauge"
+  fi
+done
+```
+
+### Step 2 — Priorizar achados
+
+```text
+P0 (fix imediato — pode causar cascade hoje):
+  - fetch/axios sem timeout
+  - retry sem jitter
+  - queue unbounded sem drop policy
+
+P1 (fix próximo sprint):
+  - sem circuit breaker em deps externas
+  - sem deadline propagation
+  - sem saturation gauge
+
+P2 (eventual — best practice):
+  - sem health check em deps
+  - sem slow start em recovery
+  - sem retry budget global
+```
+
+### Step 3 — Sugerir patches concretos
+
+Para cada P0/P1, gerar patch específico:
+
+```text
+Para fetch sem timeout:
+DIFF SUGERIDO:
+- await fetch(url, { method: 'POST', body })
++ await fetch(url, {
++   method: 'POST',
++   body,
++   signal: AbortSignal.timeout(2000),  // p99.9 baseline + 50%
++ })
+
+Para retry sem jitter:
+DIFF SUGERIDO:
+- await sleep(1000 * Math.pow(2, attempt))  // exponential SEM jitter
++ const baseMs = 100 * Math.pow(2, attempt - 1)
++ await sleep(Math.random() * baseMs * 2)  // full jitter
+
+Para queue unbounded:
+DIFF SUGERIDO:
+- this.queue.push(msg)
++ if (this.queue.length >= MAX_QUEUE_SIZE) {
++   this.queue.shift()  // drop oldest (FIFO drop)
++   metrics.counter('queue_drops_total').inc()
++ }
++ this.queue.push(msg)
+```
+
+### Step 4 — Escrever `CASCADING-AUDIT.md`
+
+```markdown
+# CASCADING-AUDIT — <target> — <data>
+
+## Resumo
+
+- **Total arquivos analisados:** <N>
+- **P0 (fix imediato):** <count>
+- **P1 (próximo sprint):** <count>
+- **P2 (best practice):** <count>
+- **Score risco:** [HIGH | MEDIUM | LOW]
+
+## P0 — fix imediato
+
+### #1: src/orders/handler.ts:42 — fetch sem timeout
+
+**Trigger:** server unavailability + latency spike sem proteção
+**Impacto:** request congela conn pool em latency upstream spike
+
+**Diff sugerido:**
+```diff
+- const r = await fetch(stripeUrl, { method: 'POST', body })
++ const r = await fetch(stripeUrl, {
++   method: 'POST',
++   body,
++   signal: AbortSignal.timeout(2000),
++ })
+```
+
+**Esforço:** 5 min
+
+[... outros P0]
+
+## P1 — próximo sprint
+[similar]
+
+## P2 — best practice
+[similar]
+
+## Recomendações cross-cutting
+
+1. Adicionar circuit breaker library (opossum) — afeta múltiplos arquivos
+2. Adicionar saturation gauge centralizada via observability-instrumenter v1.9
+3. Game day exercise — exercitar cascade em staging mensal
+
+## Cross-suite
+
+- Skill `four-golden-signals` (v1.10) — Saturation gauge é early warning
+- Skill `retry-strategies` (v1.11) — detalhes de jitter
+- Agent `golden-signals-instrumenter` (v1.10) — adicionar saturation
+- Comando `/prr <service>` (v1.10) — Axe 4 verifica defesas
+
+---
+*Material-fonte: cap 22 livro Google SRE.*
+```
+
+### Step 5 — Output curto
+
+```text
+═══════════════════════════════════════════════════════════
+CASCADING-FAILURES-AUDITOR · <target>
+═══════════════════════════════════════════════════════════
+
+## Score: [HIGH | MEDIUM | LOW]
+
+P0 (fix imediato):  <count>
+P1 (próximo sprint): <count>
+P2 (best practice):  <count>
+
+## Top 3 P0
+1. src/orders/handler.ts:42 — fetch sem timeout
+2. src/payments/retry.ts:18 — retry sem jitter
+3. src/queue/processor.ts:67 — queue unbounded
+
+## Output
+<OUTPUT_PATH>
+
+## Próximos passos
+1. Aplicar patches P0 (este sprint)
+2. /prr <service> — verificar Axe 4 (Capacity Planning)
+3. Game day exercise para confirmar resilience
+```
+
+## Quando NÃO invocar
+
+- Serviço puramente local sem deps externas
+- Função pura sem I/O
+- Audit recente (< 30 dias) e nada mudou
+- Repo de scripts (não serviço user-facing)
+
+## Ver também
+
+- [`cascading-failures`](../skills/cascading-failures/SKILL.md)
+- [`retry-strategies`](../skills/retry-strategies/SKILL.md)
+- [`load-shedding-graceful-degradation`](../skills/load-shedding-graceful-degradation/SKILL.md)
+- [`four-golden-signals`](../skills/four-golden-signals/SKILL.md) (v1.10)
+- [`load-shedding-instrumenter`](./load-shedding-instrumenter.md) — agent complementar (server-side patches)
+- [`prr-conductor`](./prr-conductor.md) (v1.10 + patch v1.11) — Axe 4 consume este audit
+- [`omm-auditor`](./omm-auditor.md) (v1.9 + patch v1.11) — Capacidade 1 consume
+
+*Material-fonte: cap 22 livro Google SRE.*

package/kit/agents/executor.md

@@ -55,9 +55,22 @@ Isso garante que padrões, convenções e melhores práticas específicas do pro
 | Bootstrap Next.js + `@supabase/ssr` | `Task(subagent_type=supabase-auth-bootstrapper)` | Audita `.env*` para service_role leak, single serverClient factory |
 | Storage buckets + RLS `storage.objects` | `Task(subagent_type=supabase-storage-implementer)` | Multi-tenant path isolation, signed URLs, image transforms |
 | Validar SQL antes de aplicar | `Task(subagent_type=schema-checker)` | Valida FKs/colunas/tabelas via Supabase MCP |
+| Refactor de arquivo > 500 linhas OR contrato externo (webhook, API, edge fn consumida externamente) | `Task(subagent_type=refactor-safety-auditor)` PRIMEIRO (gate) | Aplica skill `pre-refactor-characterization` (cap 1+13 Feathers); BLOCK refactor sem characterization tests |
+| Gerar characterization tests para código sem cobertura | `Task(subagent_type=legacy-characterizer)` | Aplica skill `legacy-characterization-tests`; 7 grupos canônicos + golden snapshots |
+| Quebrar dependência (DB, HTTP, framework type) que bloqueia teste | `Task(subagent_type=seam-finder)` | Aplica skill `legacy-seams-and-test-harness`; cap 25 Feathers |
 
 **Quando NÃO delegar:** tasks que só leem, fazem grep, ou aplicam mudança trivial em arquivo Supabase (ex: corrigir typo em comment de migration existente). Use seu próprio Edit nesses casos.
 
+**Pre-execute gate em refactor:** ANTES de modificar arquivo cuja task é `kind=refactor` E (line count > 500 OR path matches `supabase/functions/**|src/api/**|src/handlers/webhooks/**|pages/api/**`):
+
+1. Invocar `refactor-safety-auditor` com target_file e change_kind
+2. Se veredito = BLOCK e mode = blocking → **abortar tarefa**, registrar como `desvio: characterization-required`, sugerir caminhos (caracterizar / sprout / safe-extract / override) no SUMMARY.md
+3. Se veredito = WARN → prosseguir com warning logged em SUMMARY
+4. Se veredito = GO ou GO-OVERRIDE → prosseguir normalmente
+5. Se mode = consultive → sempre prossegue, gera apenas warning
+
+Esse gate é canônico — equivale ao que `golden-signals-coverage` (v1.10) faz para Edge Functions sem golden signals. Skill canônica: `pre-refactor-characterization`. Configurável via `.planning/config.json#workflow.legacy_refactor_gate_blocking`.
+
 **Princípio:** o agent especializado é mais barato + mais correto que o executor genérico para esses domínios — ele já tem as regras embutidas. Delegação não é overhead; é correção.
 </project_context>