@luanpdd/kit-mcp 1.10.0 → 1.11.0

package/kit/agents/verifier.md

@@ -55,6 +55,36 @@ A verificação reversa a partir do objetivo começa pelo resultado e trabalha d
 Depois verifique cada nível na codebase real.
 </core_principle>
 
+<legacy_refactor_verification>
+**Verificação especial para fases de refactor:**
+
+Se PLAN.md tem tasks com `kind=refactor` em arquivos flagged (> 500 linhas OR contrato externo), aplique verificação adicional baseada na skill [`pre-refactor-characterization`](../skills/pre-refactor-characterization/SKILL.md) e [`legacy-characterization-tests`](../skills/legacy-characterization-tests/SKILL.md):
+
+1. **Characterization tests existem?**
+   - Verificar `tests/characterization/<file_stem>/` ou equivalente
+   - Se ausente E refactor de risco aconteceu → **veredito: regressão indeterminável**
+   - Marca em VERIFICATION.md como gap crítico (não passa fase)
+
+2. **Characterization tests passam VERDE?**
+   - Rodar suite com framework adequado (Vitest, Pytest, etc.)
+   - Snapshot diff = 0 → comportamento preservado → ✓
+   - Snapshot diff > 0 → comportamento mudou → investigar:
+     - Se documentado como behavior change intencional → ✓ com nota
+     - Se não documentado → **regressão real** → falha de fase
+
+3. **Mutation kill score adequado?**
+   - Rodar mutation testing (Stryker / mutmut / Pitest)
+   - Kill ≥ 70% → safety net adequado
+   - Kill < 70% → warning (pode ter pontos cegos)
+
+4. **Modo override usado?**
+   - Verificar `.planning/REFACTOR-SAFETY.md` com seção `Aprovação manual`
+   - Se ticket linkado existe e é válido → ✓ (débito documentado)
+   - Se sem ticket OR ticket inválido → falha de auditoria
+
+Adicione resultados ao VERIFICATION.md em seção `## Legacy Refactor Verification`. Block phase close se characterization ausente em refactor de risco.
+</legacy_refactor_verification>
+
 <verification_process>
 
 ## Passo 0: Verificar Verificação Anterior

package/kit/commands/auditar-cascading.md

@@ -0,0 +1,111 @@
+---
+name: auditar-cascading
+description: Invoca cascading-failures-auditor — audita código de serviço para 5 triggers de cascade (sem timeout, retry sem jitter, sem circuit breaker, sem deadline propagation, queue unbounded); gera CASCADING-AUDIT.md priorizado P0/P1/P2.
+argument-hint: "[target_path] [--dimensions ...] [--severity P0|P1|P2|all]"
+allowed-tools:
+  - Read
+  - Bash
+  - Grep
+  - Glob
+  - Task
+  - Write
+---
+
+<objective>
+Auditar código de serviço (Edge Function, handler HTTP, ou repo inteiro) para os 5 triggers canônicos de cascading failure (cap 22 livro Google SRE). Invoca o agente [`cascading-failures-auditor`](../agents/cascading-failures-auditor.md) que aplica a skill [`cascading-failures`](../skills/cascading-failures/SKILL.md) — defesa em camadas (timeout + retry com jitter + circuit breaker + deadline propagation + saturation gauge).
+
+**Cria/Atualiza:**
+- `.planning/CASCADING-AUDIT.md` — relatório priorizado P0/P1/P2 com diff sugerido por finding
+
+**Após:** o user tem fila acionável de patches para prevenir cascade. Cap 22 — prevenção custa 1×, recuperação custa 100×.
+</objective>
+
+<context>
+**Argumentos:**
+- `[target_path]` — arquivo, diretório ou repo (default: `.`)
+- `--dimensions <list>` — subset de `[timeouts, retry-jitter, circuit-breaker, deadline-prop, queue-bound, health-check, saturation-gauge]` (default: todas)
+- `--severity P0|P1|P2|all` — filtro (default: all)
+- `--output PATH` — caminho do output (default: `.planning/CASCADING-AUDIT.md`)
+
+**Exemplos:**
+```
+/auditar-cascading                                      # repo inteiro
+/auditar-cascading supabase/functions/                  # só Edge Functions
+/auditar-cascading src/orders/handler.ts                # arquivo específico
+/auditar-cascading --severity P0                        # só fix imediato
+/auditar-cascading --dimensions timeouts,retry-jitter   # foco em duas dims
+```
+</context>
+
+<process>
+
+## 1. Parsear argumentos
+
+```bash
+TARGET_PATH=$(echo "$ARGUMENTS" | awk '{print $1}')
+[ -z "$TARGET_PATH" ] || [ "${TARGET_PATH:0:2}" = "--" ] && TARGET_PATH="."
+DIMENSIONS=$(echo "$ARGUMENTS" | grep -oE -- '--dimensions [^ ]+' | awk '{print $2}')
+SEVERITY=$(echo "$ARGUMENTS" | grep -oE -- '--severity [^ ]+' | awk '{print $2}')
+OUTPUT_PATH=$(echo "$ARGUMENTS" | grep -oE -- '--output [^ ]+' | awk '{print $2}')
+
+[ -z "$OUTPUT_PATH" ] && OUTPUT_PATH=".planning/CASCADING-AUDIT.md"
+mkdir -p "$(dirname "$OUTPUT_PATH")"
+```
+
+## 2. Dispatch para `cascading-failures-auditor`
+
+```text
+Task(
+  subagent_type="cascading-failures-auditor",
+  prompt="
+target_path: ${TARGET_PATH}
+output_path: ${OUTPUT_PATH}
+${DIMENSIONS:+dimensions: ${DIMENSIONS}}
+${SEVERITY:+severity_filter: ${SEVERITY}}
+
+Aplicar skill cascading-failures + retry-strategies + load-shedding-graceful-degradation. Detectar 5 triggers canônicos:
+1. Sem timeout em chamadas externas (fetch/axios/http sem AbortSignal/timeout)
+2. Retry sem jitter (setTimeout exponencial sem Math.random)
+3. Sem circuit breaker em deps externas
+4. Sem deadline propagation (handler sem header x-deadline)
+5. Queue unbounded sem drop policy
+
+Priorizar P0 (fix imediato) / P1 (próximo sprint) / P2 (best practice). Gerar diff sugerido para cada P0/P1.
+"
+)
+```
+
+## 3. Pós-output
+
+```
+═══════════════════════════════════════════════════════════
+ framework ► AUDITAR-CASCADING ▸ ${OUTPUT_PATH}
+═══════════════════════════════════════════════════════════
+
+[output do agent]
+
+## Próximos passos
+
+1. **Aplicar P0 imediato** — patches são pequenos (5-15 min cada)
+2. **/load-shedding <fn>** — adicionar defesas server-side complementares
+3. **/golden-signals <fn>** (v1.10) — adicionar Saturation gauge (early warning de cascade)
+4. **/prr <service>** (v1.10) — Axe 4 (Capacity Planning) consume este audit
+5. **Game day exercise** mensal — validar resilience em staging
+
+## Cross-suite
+
+- v1.9 Observability — Saturation alert dispara load shed antes de cascade
+- v1.10 SRE — PRR Axe 4 + Axe 5 consume
+- v1.11 SRE Resilience — esse audit
+- v1.12 Legacy — refactor pode introduzir/remover defesas; pre-refactor-characterization gate
+```
+
+</process>
+
+<success_criteria>
+- [ ] $ARGUMENTS parseados (target_path opcional, default cwd)
+- [ ] `cascading-failures-auditor` invocado via Task
+- [ ] CASCADING-AUDIT.md criado pelo agent
+- [ ] Output forwarded transparentemente
+- [ ] Cross-references com /load-shedding, /golden-signals, /prr
+</success_criteria>

package/kit/commands/auditar-marco.md

@@ -134,4 +134,47 @@ Para esses casos: `workflow.audit_milestone_toil = false`. Para projetos team-ba
 - "Toil ≠ overhead" → overhead inclui meetings, planning, code review (necessário, não automatizável); toil é só o automatizable
 
 **REQ:** INT-FW-V2-03.
-</sre_integration>
+</sre_integration>
+
+<legacy_refactor_integration>
+**Legacy refactor safety audit (opt-in):**
+
+Quando `workflow.audit_milestone_legacy_refactor = true` (default: false em projetos < 50% OMM maturity, true acima), o workflow inclui passo de auditoria de refactor safety:
+
+```text
+Para cada arquivo modificado por tasks com kind=refactor no milestone:
+  Task(
+    subagent_type="refactor-safety-auditor",
+    prompt="
+target_file: <file>
+change_kind: refactor
+mode: blocking
+output_path: .planning/REFACTOR-SAFETY-<file_stem>.md
+
+Aplicar skill pre-refactor-characterization. Validar retroativamente que safety net foi aplicado.
+"
+  )
+```
+
+**Critérios de aprovação:**
+- Cada refactor de risco no milestone tem characterization tests linkados E pass verde
+- Cada `--mode=override` tem ticket linkado válido (ainda aberto OR resolvido com follow-up)
+- Mutation kill score ≥ 70% nos arquivos refatorados (warning se line cov OK mas mutation baixo)
+
+**Resultado de regression:**
+- 0 refactors sem char → audit aprovado
+- 1+ refactors sem char e sem override → audit fail; bloqueia close de milestone até resolução
+- 1+ overrides com tickets ainda abertos > 90 dias → warning explícito (débito técnico envelhecido)
+
+Skill canônica: [`pre-refactor-characterization`](../skills/pre-refactor-characterization/SKILL.md)
+Cross-ref ativo: `omm-auditor` Capacidade 1 (Resilience) score consulta REFACTOR-SAFETY summaries para fator "% refactors com safety net"; baixa adequação reduz score.
+
+**Quando desligar gate:**
+- Projeto greenfield com < 3 meses de idade (legacy code não existe ainda)
+- Solo dev side project sem stakes de produção (audit é overhead)
+- Toda codebase é < 50% código não-trivial (a maior parte é config/markdown/tests)
+
+Para esses casos: `workflow.audit_milestone_legacy_refactor = false`. Para projetos com stakes de produção e equipe ≥ 2 pessoas, **manter `true`**.
+
+**REQ:** INT-LEGACY-FW-01.
+</legacy_refactor_integration>

package/kit/commands/auditar-observabilidade-cobertura.md

@@ -0,0 +1,183 @@
+---
+name: auditar-observabilidade-cobertura
+description: Audita projeto Supabase mostrando X/N Edge Functions com 4 golden signals + Y/N com SLO + Z/N com burn alert + W/N com characterization tests. Top 5 críticas (por traffic 30d) sem cobertura. User-request explícito.
+argument-hint: "[--traffic-window 30d] [--top-n 5] [--dimensions signals,slo,burn-alert,characterization] [--output PATH]"
+allowed-tools:
+  - Read
+  - Bash
+  - Grep
+  - Glob
+  - Task
+  - Write
+  - mcp__supabase__list_edge_functions
+  - mcp__supabase__get_logs
+  - mcp__supabase__execute_sql
+---
+
+<objective>
+**O comando que você roda hoje pra ver o tamanho do buraco e priorizar.** Audit horizontal de cobertura cross-suite (Observabilidade v1.9 + SRE v1.10 + Legacy v1.12). Roda contra projeto Supabase, gera relatório:
+
+- Edge functions emitindo 4 golden signals: **X / N**
+- Edge functions com SLO definido: **Y / N**
+- Edge functions com burn rate alert: **Z / N**
+- Edge functions com characterization tests: **W / N**
+- **Top 5 funções mais críticas (por chamadas 30d) sem cobertura completa**
+
+Invoca o agente [`observability-coverage-auditor`](../agents/observability-coverage-auditor.md) que cross-references skills v1.9 + v1.10 + v1.12.
+
+**Cria/Atualiza:**
+- `.planning/OBSERVABILITY-COVERAGE.md` — relatório scored com tabela X/N por dimensão + top críticas + recomendações priorizadas
+
+**Após:** o user vê tamanho do buraco quantitativamente e tem fila ordenada por (traffic × missing dimensions). As 2 que ele instrumentou às pressas viram baseline; as outras N entram na fila ordenada.
+</objective>
+
+<context>
+**Argumentos:**
+- `--traffic-window 30d` — janela para criticidade (default: 30d)
+- `--top-n 5` — quantas críticas listar (default: 5)
+- `--dimensions <list>` — quais dimensões auditar (default: `signals,slo,burn-alert,characterization`)
+- `--output PATH` — caminho do output (default: `.planning/OBSERVABILITY-COVERAGE.md`)
+
+**Exemplos:**
+```
+/auditar-observabilidade-cobertura                                    # defaults
+/auditar-observabilidade-cobertura --top-n 10                         # listar top 10
+/auditar-observabilidade-cobertura --dimensions signals,slo           # só 2 dimensões
+/auditar-observabilidade-cobertura --traffic-window 7d                # janela menor
+```
+
+**Pré-requisitos:**
+- Projeto Supabase (`supabase/config.toml` presente)
+- MCP Supabase conectado para traffic data + Edge Functions list (recomendado)
+- Sem MCP: agent reverte para enumerate via filesystem (sem traffic data → top-N por filesystem only)
+
+**Quando este comando é o caminho:**
+- Você quer "ver o buraco" antes de priorizar instrumentação
+- Você instrumentou algumas Edge Functions ad-hoc; agora quer audit estruturado das outras
+- Audit trimestral cross-suite
+- Pré-requisito de `/concluir-marco` quando `workflow.observability_coverage_threshold` opt-in
+- `/auditar-marco` chain (audit milestone consume este)
+</context>
+
+<process>
+
+## 1. Parsear argumentos
+
+```bash
+TRAFFIC_WINDOW=$(echo "$ARGUMENTS" | grep -oE -- '--traffic-window [^ ]+' | awk '{print $2}')
+TOP_N=$(echo "$ARGUMENTS" | grep -oE -- '--top-n [0-9]+' | awk '{print $2}')
+DIMENSIONS=$(echo "$ARGUMENTS" | grep -oE -- '--dimensions [^ ]+' | awk '{print $2}')
+OUTPUT_PATH=$(echo "$ARGUMENTS" | grep -oE -- '--output [^ ]+' | awk '{print $2}')
+
+[ -z "$TRAFFIC_WINDOW" ] && TRAFFIC_WINDOW="30d"
+[ -z "$TOP_N" ]          && TOP_N=5
+[ -z "$DIMENSIONS" ]     && DIMENSIONS="signals,slo,burn-alert,characterization"
+[ -z "$OUTPUT_PATH" ]    && OUTPUT_PATH=".planning/OBSERVABILITY-COVERAGE.md"
+
+mkdir -p "$(dirname "$OUTPUT_PATH")"
+```
+
+## 2. Validar pré-requisitos
+
+```bash
+PROJECT_ID=""
+if [ -f "supabase/config.toml" ]; then
+  PROJECT_ID=$(grep -E '^project_id\s*=' supabase/config.toml | sed 's/.*= *"\(.*\)".*/\1/' | head -1)
+fi
+
+# Detectar tier (Full vs Partial)
+TIER="full"
+if [ -z "$PROJECT_ID" ]; then
+  TIER="partial"
+  echo "ℹ project_id não detectado em supabase/config.toml — degradando para tier partial (sem traffic data)"
+fi
+
+# Detectar Edge Functions via filesystem
+NUM_EDGE_FNS=$(find supabase/functions -mindepth 1 -maxdepth 1 -type d 2>/dev/null | wc -l)
+if [ "$NUM_EDGE_FNS" -eq 0 ]; then
+  echo "ERROR: nenhuma Edge Function detectada em supabase/functions/. Audit cancelado."
+  exit 1
+fi
+```
+
+## 3. Dispatch para `observability-coverage-auditor`
+
+```text
+Task(
+  subagent_type="observability-coverage-auditor",
+  prompt="
+project_root: .
+output_path: ${OUTPUT_PATH}
+traffic_window: ${TRAFFIC_WINDOW}
+top_n_critical: ${TOP_N}
+dimensions: ${DIMENSIONS}
+${PROJECT_ID:+project_id: ${PROJECT_ID}}
+tier: ${TIER}
+
+Aplicar skills (cross-suite v1.9+v1.10+v1.12). Etapas:
+1. Enumerar Edge Functions (via mcp__supabase__list_edge_functions ou filesystem fallback)
+2. Para cada Edge Function, auditar:
+   - 4 Golden Signals (grep por createHistogram/createCounter/createObservableGauge)
+   - SLO definido (.planning/slos/<name>.md ou .planning/SLO.md menção)
+   - Burn rate alert (config presente)
+   - Characterization tests (tests/characterization/<name>/ presente)
+3. Coletar traffic 30d via mcp__supabase__get_logs (Tier Full) ou skip (Tier Partial)
+4. Calcular criticality_score = traffic × missing_count
+5. Compilar matriz + top ${TOP_N} críticas + recomendações priorizadas
+6. Output: .planning/OBSERVABILITY-COVERAGE.md
+"
+)
+```
+
+## 4. Pós-output
+
+```
+═══════════════════════════════════════════════════════════
+ framework ► AUDITAR-OBSERVABILIDADE-COBERTURA ▸ ${OUTPUT_PATH}
+═══════════════════════════════════════════════════════════
+
+[output do observability-coverage-auditor]
+
+## Próximos passos priorizados
+
+1. **Atacar top 1 crítica primeiro** — comando direto:
+   - Se signals missing: `/golden-signals <function-path>`
+   - Se SLO missing: `/definir-slo <function-name>`
+   - Se char missing: `/caracterizar <function-path>`
+   - Se burn alert missing: configurar via `/burn-rate-status` + alert manager
+
+2. **Continuar pela ordem de criticality** (top 2, 3, ...)
+
+3. **Bulk approach** se há > 10 funções missing:
+   - Priorize SIGNALS primeiro (visibility é fundação)
+   - Depois SLO (define o que importa)
+   - Depois BURN ALERT (early warning)
+   - Depois CHARACTERIZATION (refactor safety)
+
+4. **Auto-completion** via:
+   - `/observabilidade audit-coverage` — sinônimo deste comando
+   - `/observabilidade omm` — OMM scoring v1.9 que consume este audit
+   - `/auditar-marco` — milestone audit que opt-in invoca este
+
+## Cross-suite
+
+Este audit é o **HUB** que conecta as 3 suítes:
+- v1.9 Observabilidade (golden signals + SLO + burn alert)
+- v1.10 SRE (PRR Axe 2 Instrumentation + Axe 4 Capacity)
+- v1.12 Legacy (characterization safety net)
+
+Re-rodar trimestralmente OR após cada milestone com novas Edge Functions.
+```
+
+</process>
+
+<success_criteria>
+- [ ] $ARGUMENTS parseados (todos opcionais, defaults razoáveis)
+- [ ] Project_id resolvido OU degradado para tier partial sem warning
+- [ ] Edge Functions enumeradas (≥ 1 detectada)
+- [ ] `observability-coverage-auditor` invocado via Task
+- [ ] Output forwarded transparentemente
+- [ ] Próximos passos PRIORIZADOS com comandos prontos para copy-paste
+- [ ] Cross-references com /observabilidade, /auditar-marco, /golden-signals, /caracterizar
+- [ ] Atende explicitamente ao user-request "comando que você roda hoje pra ver o tamanho do buraco"
+</success_criteria>

package/kit/commands/auditar-refactor.md

@@ -0,0 +1,219 @@
+---
+name: auditar-refactor
+description: Invoca refactor-safety-auditor — gate canônico antes de qualquer refactor. Coleta evidências (linhas, contrato externo, coverage, mutation) e retorna veredito GO/BLOCK/WARN/GO-OVERRIDE. Bloqueia refactor de risco sem characterization.
+argument-hint: "<target_file> [--change-kind refactor|sprout|safe-extract|override] [--mode blocking|consultive] [--ticket REQ-N] [--reason \"...\"]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Grep
+  - Glob
+  - Task
+---
+
+<objective>
+Auditar arquivo alvo de refactor ANTES da execução para decidir se safety net (characterization tests) é adequado. Invoca o agente [`refactor-safety-auditor`](../agents/refactor-safety-auditor.md) que aplica a skill [`pre-refactor-characterization`](../skills/pre-refactor-characterization/SKILL.md) — 3 critérios de risco canônicos (tamanho > 500 linhas, contrato externo, cobertura < 60%) + matriz de decisão.
+
+**Cria/Atualiza:**
+- `.planning/REFACTOR-SAFETY.md` — relatório com evidências, veredito, caminhos recomendados, audit trail
+
+**Após:** o user tem decisão **objetiva** (não gut-feeling) sobre se refactor pode prosseguir. Se BLOCK, oferece 4 caminhos concretos. Se GO-OVERRIDE, registra ticket + reason para débito técnico.
+</objective>
+
+<context>
+**Argumentos:**
+- `<target_file>` — caminho do arquivo a auditar — OBRIGATÓRIO
+- `--change-kind <kind>` — tipo da mudança (default: `refactor`):
+  - `refactor` — mudança comportamental (gate roda completo)
+  - `sprout` — adiciona via sprout method/class (legado intocado, gate libera com 100% no novo)
+  - `safe-extract` — refactor mecânico (rename, IDE-extract bloco contíguo, sem mudar control flow)
+  - `override` — bypass com justificativa (requer --ticket + --reason)
+- `--mode blocking|consultive` — força modo do gate (default: lido de `.planning/config.json`)
+- `--ticket REQ-N` — ticket linkado (obrigatório com --change-kind=override)
+- `--reason "<texto>"` — justificativa (obrigatória com --change-kind=override)
+- `--output PATH` — caminho do output (default: `.planning/REFACTOR-SAFETY.md`)
+
+**Exemplos:**
+```
+/auditar-refactor src/orders/handler.ts                                  # default refactor
+/auditar-refactor src/orders/handler.ts --change-kind sprout             # libera (sprout)
+/auditar-refactor src/orders/handler.ts --change-kind safe-extract       # libera (mecânico)
+/auditar-refactor src/orders/handler.ts \
+  --change-kind override --ticket REQ-2026-Q2-1234 \
+  --reason "hot fix de SEV1, char será adicionado em REQ-2026-Q2-1235"   # bypass com audit trail
+/auditar-refactor src/orders/handler.ts --mode consultive                # warning em vez de block
+```
+
+**Fluxo típico:**
+1. `/discutir-fase` detecta refactor intent → automaticamente invoca este comando
+2. Veredito BLOCK → user escolhe um dos 4 caminhos (caracterizar, sprout, safe-extract, override)
+3. Aplicar caminho + re-rodar este comando até veredito GO
+4. Refactor executado com confiança
+
+**Quando invocar manualmente:**
+- Antes de planejar fase de refactor
+- Antes de PR de refactor de arquivo grande
+- Periodicamente em milestones para identificar gaps de coverage
+- Como parte de `/auditar-marco` quando `workflow.audit_milestone_legacy_refactor=true`
+</context>
+
+<process>
+
+## 1. Parsear argumentos
+
+```bash
+TARGET_FILE=$(echo "$ARGUMENTS" | awk '{print $1}')
+CHANGE_KIND=$(echo "$ARGUMENTS" | grep -oE -- '--change-kind [^ ]+' | awk '{print $2}')
+MODE=$(echo "$ARGUMENTS" | grep -oE -- '--mode [^ ]+' | awk '{print $2}')
+TICKET=$(echo "$ARGUMENTS" | grep -oE -- '--ticket [^ ]+' | awk '{print $2}')
+REASON=$(echo "$ARGUMENTS" | grep -oE -- '--reason "[^"]+"' | sed 's/--reason "\(.*\)"/\1/')
+OUTPUT_PATH=$(echo "$ARGUMENTS" | grep -oE -- '--output [^ ]+' | awk '{print $2}')
+
+[ -z "$CHANGE_KIND" ] && CHANGE_KIND="refactor"
+[ -z "$OUTPUT_PATH" ] && OUTPUT_PATH=".planning/REFACTOR-SAFETY.md"
+
+if [ -z "$TARGET_FILE" ]; then
+  echo "ERROR: target_file é obrigatório."
+  echo "Uso: /auditar-refactor <target_file> [opções]"
+  exit 1
+fi
+
+if [ ! -f "$TARGET_FILE" ]; then
+  echo "ERROR: arquivo não encontrado: $TARGET_FILE"
+  exit 1
+fi
+
+# PT-BR: validar override → exige ticket + reason
+if [ "$CHANGE_KIND" = "override" ]; then
+  if [ -z "$TICKET" ] || [ -z "$REASON" ]; then
+    echo "ERROR: --change-kind=override requer --ticket REQ-N E --reason \"<texto>\"."
+    echo "Sem audit trail, override é proibido."
+    exit 1
+  fi
+fi
+
+mkdir -p "$(dirname "$OUTPUT_PATH")"
+```
+
+## 2. Detectar mode default via config + omm
+
+```bash
+# PT-BR: ler config para mode default
+CONFIG_MODE=""
+if [ -f ".planning/config.json" ] && command -v jq >/dev/null; then
+  GATE_BLOCKING=$(jq -r '.workflow.legacy_refactor_gate_blocking // empty' .planning/config.json)
+  if [ "$GATE_BLOCKING" = "true" ]; then
+    CONFIG_MODE="blocking"
+  elif [ "$GATE_BLOCKING" = "false" ]; then
+    CONFIG_MODE="consultive"
+  fi
+fi
+
+# PT-BR: integração com omm-auditor — Capacidade 1 (Resilience) calibra mode
+if [ -z "$MODE" ] && [ -z "$CONFIG_MODE" ]; then
+  if [ -f ".planning/OMM-REPORT.md" ]; then
+    OMM_RESILIENCE=$(grep -oE 'Capacidade 1.*Resilience.*[0-9]/5' .planning/OMM-REPORT.md | grep -oE '[0-9]/5' | head -1 | sed 's|/5||')
+    if [ -n "$OMM_RESILIENCE" ] && [ "$OMM_RESILIENCE" -ge 3 ]; then
+      MODE="blocking"
+    else
+      MODE="consultive"
+    fi
+  fi
+fi
+
+[ -z "$MODE" ] && MODE="${CONFIG_MODE:-blocking}"
+```
+
+## 3. Dispatch para `refactor-safety-auditor`
+
+```text
+Task(
+  subagent_type="refactor-safety-auditor",
+  prompt="
+target_file: ${TARGET_FILE}
+change_kind: ${CHANGE_KIND}
+output_path: ${OUTPUT_PATH}
+mode: ${MODE}
+${TICKET:+ticket: ${TICKET}}
+${REASON:+reason: ${REASON}}
+
+Aplicar skill pre-refactor-characterization. Etapas:
+1. Preflight: detectar linguagem, validar input
+2. Coletar evidências:
+   - line count + heurística de aninhamento
+   - external contract (path patterns, content markers, cross-package refs)
+   - coverage atual (line coverage como proxy)
+   - characterization tests existentes
+   - mutation kill score (se disponível)
+3. Aplicar matriz de decisão (3 critérios canônicos)
+4. Determinar caminho recomendado (caracterizar/sprout/safe-extract/override)
+5. Escrever REFACTOR-SAFETY.md com evidências, veredito, paths, audit trail
+6. Output curto para caller (veredito + custo + próximos passos)
+"
+)
+```
+
+## 4. Pós-output
+
+```
+═══════════════════════════════════════════════════════════
+ framework ► AUDITAR-REFACTOR ▸ ${OUTPUT_PATH}
+═══════════════════════════════════════════════════════════
+
+[output do refactor-safety-auditor]
+
+## Decision matrix referência
+
+| Veredito | Significado | Próxima ação |
+|---|---|---|
+| **GO** | Safety net adequado | Refactor pode prosseguir |
+| **GO-OVERRIDE** | Bypass com audit trail | Refactor pode prosseguir, débito documentado em ticket |
+| **WARN** | Risco médio | Considere `/caracterizar --gap-fill` antes; ou prosseguir + monitor |
+| **BLOCK** | Risco alto sem safety net | Escolha um dos 4 caminhos abaixo |
+
+## Caminhos quando BLOCK (em ordem de preferência)
+
+1. **Caracterizar primeiro** (recomendado para refactor real)
+   ```
+   /caracterizar <file>
+   ```
+   Custo: 8-16h. Cobertura behavioral ≥ 70%. Gate retorna GO após.
+
+2. **Sprout/Wrap** (não toca legado, ADICIONA comportamento)
+   ```
+   /refactor-seguro --mode=sprout <file>
+   ```
+   Custo: 0.5-4h. Legado intocado, novo testado isolado.
+
+3. **Safe extraction** (mecânico — rename, IDE-extract)
+   ```
+   /refactor-seguro --mode=safe-extract <file>
+   ```
+   Custo: 1-2h. Apenas refactor sem mudança comportamental.
+
+4. **Override** (último recurso, audit trail)
+   ```
+   /refactor-seguro --mode=override --ticket REQ-N --reason "<texto>" <file>
+   ```
+   Custo: 0h refactor + custo do débito. Aprovação humana obrigatória.
+
+## Cross-suite
+
+- **/instrumentar-fase** (v1.9) — durante refactor com BLOCK→GO via override, instrumentar para detecção precoce de regressão via golden signals
+- **/burn-rate-status** (v1.9) — refactor pode regredir SLO; monitor budget pós-deploy
+- **/prr** (v1.10) — Production Readiness Review Axe 5 (Change Management) consume veredito deste gate
+- **/postmortem** (v1.10) — postmortems de regression em refactor sem char referenciam essa auditoria como lesson learned
+```
+
+</process>
+
+<success_criteria>
+- [ ] $ARGUMENTS parseados (target_file obrigatório, --change-kind=override exige ticket + reason)
+- [ ] Mode resolvido: argument explícito > config.json > omm-auditor (Capacidade 1) > default blocking
+- [ ] `refactor-safety-auditor` invocado via `Task(subagent_type=...)` com prompt completo (6 etapas)
+- [ ] `.planning/REFACTOR-SAFETY.md` criado pelo agent
+- [ ] Output forwarded transparentemente
+- [ ] Decision matrix exibida para referência
+- [ ] 4 caminhos oferecidos quando BLOCK (com comandos prontos para copy-paste)
+- [ ] Cross-references com Suíte Observabilidade + SRE
+</success_criteria>