@luanpdd/kit-mcp 1.35.0 → 1.36.0

package/gates/golden-signals-coverage.md

@@ -1,133 +1,133 @@
----
-id: golden-signals-coverage
-stage: pre-verify
-blocking: true
-description: Valida que código de serviço/Edge Function tocado em fase contém os 4 golden signals (Latency=histogram, Traffic=counter, Errors=counter, Saturation=gauge). Skip se fase só toca markdown.
----
-
-# Golden signals coverage gate
-
-**When to run:** pre-verify (blocking — fase não verifica até cobertura completa).
-
-## Check
-
-```bash
-#!/usr/bin/env bash
-# PT-BR: validar que código de serviço/Edge Function tocado em fase tem 4 golden signals.
-# Estratégia: descobrir arquivos tocados (supabase/functions/** ou STATE.md current_phase code paths),
-# rodar grep por histogram/counter/gauge/saturation, contar matches por sinal.
-# Bash 3.2-portable (macOS default).
-set -e
-
-# PT-BR: identificar fase atual via STATE.md
-STATE_FILE=".planning/STATE.md"
-CURRENT_PHASE=""
-if [ -f "$STATE_FILE" ]; then
-  CURRENT_PHASE=$(grep -E "^Fase:" "$STATE_FILE" 2>/dev/null | head -1 | sed -E 's/^Fase: *([0-9]+).*/\1/')
-fi
-
-# PT-BR: candidatos a arquivos de código tocados — escopo principal Supabase Edge + qualquer .ts/.js/.py
-# em paths declarados pela fase (heurística: supabase/functions/** SEMPRE inspecionado).
-CODE_FILES=""
-if [ -d "supabase/functions" ]; then
-  CODE_FILES=$(find supabase/functions -type f \( -name "*.ts" -o -name "*.js" -o -name "*.mjs" \) 2>/dev/null)
-fi
-
-# PT-BR: também inspecionar lib/ e src/ se existirem (apps Node/Deno fora de Supabase)
-if [ -d "src" ]; then
-  ADDITIONAL=$(find src -type f \( -name "*.ts" -o -name "*.js" -o -name "*.mjs" -o -name "*.py" \) 2>/dev/null)
-  CODE_FILES="$CODE_FILES
-$ADDITIONAL"
-fi
-if [ -d "lib" ]; then
-  ADDITIONAL=$(find lib -type f \( -name "*.ts" -o -name "*.js" -o -name "*.mjs" -o -name "*.py" \) 2>/dev/null)
-  CODE_FILES="$CODE_FILES
-$ADDITIONAL"
-fi
-
-# PT-BR: filtrar linhas vazias
-CODE_FILES=$(echo "$CODE_FILES" | grep -v "^$" || true)
-
-# PT-BR: se fase não toca código (só markdown/docs), pular gate
-if [ -z "$CODE_FILES" ]; then
-  echo "INFO: nenhum arquivo de código (.ts/.js/.py) encontrado em supabase/functions/** | src/** | lib/** — fase parece content-only. Gate skipped."
-  exit 0
-fi
-
-# PT-BR: contar matches por signal
-LATENCY_HITS=0
-TRAFFIC_HITS=0
-ERRORS_HITS=0
-SATURATION_HITS=0
-
-# PT-BR: process file list line-by-line para portabilidade bash 3.2
-OLDIFS="$IFS"
-IFS='
-'
-for f in $CODE_FILES; do
-  [ -z "$f" ] && continue
-  [ ! -f "$f" ] && continue
-
-  # PT-BR: Latency = histogram (createHistogram, recordHistogram, histogram.record)
-  if grep -qE "histogram|Histogram" "$f" 2>/dev/null; then
-    LATENCY_HITS=$((LATENCY_HITS + 1))
-  fi
-
-  # PT-BR: Traffic + Errors = counter (Errors counter dimensionado por error.type)
-  if grep -qE "counter|Counter|createCounter" "$f" 2>/dev/null; then
-    TRAFFIC_HITS=$((TRAFFIC_HITS + 1))
-    ERRORS_HITS=$((ERRORS_HITS + 1))
-  fi
-
-  # PT-BR: Saturation = gauge (createObservableGauge, gauge.record) ou string saturation
-  if grep -qE "gauge|Gauge|saturation|Saturation" "$f" 2>/dev/null; then
-    SATURATION_HITS=$((SATURATION_HITS + 1))
-  fi
-done
-IFS="$OLDIFS"
-
-# PT-BR: gate passa se TODOS os 4 signals têm pelo menos 1 hit em algum arquivo de código
-MISSING=""
-[ "$LATENCY_HITS" -eq 0 ] && MISSING="$MISSING Latency(histogram)"
-[ "$TRAFFIC_HITS" -eq 0 ] && MISSING="$MISSING Traffic(counter)"
-[ "$ERRORS_HITS" -eq 0 ] && MISSING="$MISSING Errors(counter)"
-[ "$SATURATION_HITS" -eq 0 ] && MISSING="$MISSING Saturation(gauge)"
-
-if [ -z "$MISSING" ]; then
-  echo "PASS: 4 golden signals cobertos em código (Latency=$LATENCY_HITS files / Traffic=$TRAFFIC_HITS / Errors=$ERRORS_HITS / Saturation=$SATURATION_HITS)"
-  exit 0
-else
-  echo "FAIL: golden signals ausentes em código tocado:$MISSING"
-  echo "Sugestão: rodar /sre golden-signals <service> ou /golden-signals para gerar instrumentação OTel canônica."
-  echo "Cross-ref: kit/skills/four-golden-signals/SKILL.md + kit/agents/golden-signals-instrumenter.md"
-  exit 1
-fi
-```
-
-## Verdict
-
-- **passed** — todos 4 signals (Latency / Traffic / Errors / Saturation) presentes em pelo menos 1 arquivo de código no projeto
-- **passed (skip)** — projeto não tem código (apenas markdown / docs); gate não aplicável
-- **block** — pelo menos 1 signal ausente em código tocado pela fase
-
-## Why
-
-O livro Google SRE (cap 6 — *Monitoring Distributed Systems*) define os **4 golden signals** como cobertura mínima universal de saúde operacional para serviços user-facing — Latency (histogram com percentis, success vs error separados), Traffic (counter por endpoint × method), Errors (counter por `error.type` enum 5-15 valores, NUNCA `error.message`), Saturation (gauge do recurso mais escasso identificado explicitamente).
-
-Sem esse gate, fases entregam Edge Functions / serviços sem instrumentação básica e dashboards crescem ad-hoc (CPU, memory, threads — *causes* não *symptoms*). Gate força padrão canônico: cada PR de código deve cobrir os 4 signals, ou explicar a ausência via skip (fase só altera markdown).
-
-Cross-ref agent canônico: [`golden-signals-instrumenter`](../kit/agents/golden-signals-instrumenter.md) (Phase 37 / AGCORE-SRE-01). Skill: [`four-golden-signals`](../kit/skills/four-golden-signals/SKILL.md) (Phase 36 / SKFD-SRE-02).
-
-## REQ
-
-QA-SRE-01.
-
-## Configuração
-
-Gate é **blocking** por default. Para tornar warn-only (durante adoption inicial em legado):
-
-```bash
-node ./.claude/framework/bin/tools.cjs config-set workflow.golden_signals_coverage_warn true
-```
-
-(Nota: implementação do toggle warn-only é deferida — gate atual lê apenas presença/ausência de regex, não consulta config.)
+---
+id: golden-signals-coverage
+stage: pre-verify
+blocking: true
+description: Valida que código de serviço/Edge Function tocado em fase contém os 4 golden signals (Latency=histogram, Traffic=counter, Errors=counter, Saturation=gauge). Skip se fase só toca markdown.
+---
+
+# Golden signals coverage gate
+
+**When to run:** pre-verify (blocking — fase não verifica até cobertura completa).
+
+## Check
+
+```bash
+#!/usr/bin/env bash
+# PT-BR: validar que código de serviço/Edge Function tocado em fase tem 4 golden signals.
+# Estratégia: descobrir arquivos tocados (supabase/functions/** ou STATE.md current_phase code paths),
+# rodar grep por histogram/counter/gauge/saturation, contar matches por sinal.
+# Bash 3.2-portable (macOS default).
+set -e
+
+# PT-BR: identificar fase atual via STATE.md
+STATE_FILE=".planning/STATE.md"
+CURRENT_PHASE=""
+if [ -f "$STATE_FILE" ]; then
+  CURRENT_PHASE=$(grep -E "^Fase:" "$STATE_FILE" 2>/dev/null | head -1 | sed -E 's/^Fase: *([0-9]+).*/\1/')
+fi
+
+# PT-BR: candidatos a arquivos de código tocados — escopo principal Supabase Edge + qualquer .ts/.js/.py
+# em paths declarados pela fase (heurística: supabase/functions/** SEMPRE inspecionado).
+CODE_FILES=""
+if [ -d "supabase/functions" ]; then
+  CODE_FILES=$(find supabase/functions -type f \( -name "*.ts" -o -name "*.js" -o -name "*.mjs" \) 2>/dev/null)
+fi
+
+# PT-BR: também inspecionar lib/ e src/ se existirem (apps Node/Deno fora de Supabase)
+if [ -d "src" ]; then
+  ADDITIONAL=$(find src -type f \( -name "*.ts" -o -name "*.js" -o -name "*.mjs" -o -name "*.py" \) 2>/dev/null)
+  CODE_FILES="$CODE_FILES
+$ADDITIONAL"
+fi
+if [ -d "lib" ]; then
+  ADDITIONAL=$(find lib -type f \( -name "*.ts" -o -name "*.js" -o -name "*.mjs" -o -name "*.py" \) 2>/dev/null)
+  CODE_FILES="$CODE_FILES
+$ADDITIONAL"
+fi
+
+# PT-BR: filtrar linhas vazias
+CODE_FILES=$(echo "$CODE_FILES" | grep -v "^$" || true)
+
+# PT-BR: se fase não toca código (só markdown/docs), pular gate
+if [ -z "$CODE_FILES" ]; then
+  echo "INFO: nenhum arquivo de código (.ts/.js/.py) encontrado em supabase/functions/** | src/** | lib/** — fase parece content-only. Gate skipped."
+  exit 0
+fi
+
+# PT-BR: contar matches por signal
+LATENCY_HITS=0
+TRAFFIC_HITS=0
+ERRORS_HITS=0
+SATURATION_HITS=0
+
+# PT-BR: process file list line-by-line para portabilidade bash 3.2
+OLDIFS="$IFS"
+IFS='
+'
+for f in $CODE_FILES; do
+  [ -z "$f" ] && continue
+  [ ! -f "$f" ] && continue
+
+  # PT-BR: Latency = histogram (createHistogram, recordHistogram, histogram.record)
+  if grep -qE "histogram|Histogram" "$f" 2>/dev/null; then
+    LATENCY_HITS=$((LATENCY_HITS + 1))
+  fi
+
+  # PT-BR: Traffic + Errors = counter (Errors counter dimensionado por error.type)
+  if grep -qE "counter|Counter|createCounter" "$f" 2>/dev/null; then
+    TRAFFIC_HITS=$((TRAFFIC_HITS + 1))
+    ERRORS_HITS=$((ERRORS_HITS + 1))
+  fi
+
+  # PT-BR: Saturation = gauge (createObservableGauge, gauge.record) ou string saturation
+  if grep -qE "gauge|Gauge|saturation|Saturation" "$f" 2>/dev/null; then
+    SATURATION_HITS=$((SATURATION_HITS + 1))
+  fi
+done
+IFS="$OLDIFS"
+
+# PT-BR: gate passa se TODOS os 4 signals têm pelo menos 1 hit em algum arquivo de código
+MISSING=""
+[ "$LATENCY_HITS" -eq 0 ] && MISSING="$MISSING Latency(histogram)"
+[ "$TRAFFIC_HITS" -eq 0 ] && MISSING="$MISSING Traffic(counter)"
+[ "$ERRORS_HITS" -eq 0 ] && MISSING="$MISSING Errors(counter)"
+[ "$SATURATION_HITS" -eq 0 ] && MISSING="$MISSING Saturation(gauge)"
+
+if [ -z "$MISSING" ]; then
+  echo "PASS: 4 golden signals cobertos em código (Latency=$LATENCY_HITS files / Traffic=$TRAFFIC_HITS / Errors=$ERRORS_HITS / Saturation=$SATURATION_HITS)"
+  exit 0
+else
+  echo "FAIL: golden signals ausentes em código tocado:$MISSING"
+  echo "Sugestão: rodar /sre golden-signals <service> ou /golden-signals para gerar instrumentação OTel canônica."
+  echo "Cross-ref: kit/skills/four-golden-signals/SKILL.md + kit/agents/golden-signals-instrumenter.md"
+  exit 1
+fi
+```
+
+## Verdict
+
+- **passed** — todos 4 signals (Latency / Traffic / Errors / Saturation) presentes em pelo menos 1 arquivo de código no projeto
+- **passed (skip)** — projeto não tem código (apenas markdown / docs); gate não aplicável
+- **block** — pelo menos 1 signal ausente em código tocado pela fase
+
+## Why
+
+O livro Google SRE (cap 6 — *Monitoring Distributed Systems*) define os **4 golden signals** como cobertura mínima universal de saúde operacional para serviços user-facing — Latency (histogram com percentis, success vs error separados), Traffic (counter por endpoint × method), Errors (counter por `error.type` enum 5-15 valores, NUNCA `error.message`), Saturation (gauge do recurso mais escasso identificado explicitamente).
+
+Sem esse gate, fases entregam Edge Functions / serviços sem instrumentação básica e dashboards crescem ad-hoc (CPU, memory, threads — *causes* não *symptoms*). Gate força padrão canônico: cada PR de código deve cobrir os 4 signals, ou explicar a ausência via skip (fase só altera markdown).
+
+Cross-ref agent canônico: [`golden-signals-instrumenter`](../kit/agents/golden-signals-instrumenter.md) (Phase 37 / AGCORE-SRE-01). Skill: [`four-golden-signals`](../kit/skills/four-golden-signals/SKILL.md) (Phase 36 / SKFD-SRE-02).
+
+## REQ
+
+QA-SRE-01.
+
+## Configuração
+
+Gate é **blocking** por default. Para tornar warn-only (durante adoption inicial em legado):
+
+```bash
+node ./.claude/framework/bin/tools.cjs config-set workflow.golden_signals_coverage_warn true
+```
+
+(Nota: implementação do toggle warn-only é deferida — gate atual lê apenas presença/ausência de regex, não consulta config.)

package/gates/legacy-refactor-safety.md

@@ -1,178 +1,178 @@
----
-id: legacy-refactor-safety
-stage: pre-execute
-blocking: false
-description: Valida que tasks com kind=refactor em arquivos > 500 linhas OU com contrato externo têm characterization tests linkados. Skip se fase só toca markdown OR fase é greenfield. Opt-in via workflow.legacy_refactor_gate_blocking=true.
----
-
-# Legacy refactor safety gate
-
-**When to run:** pre-execute (consultive por default; blocking se `workflow.legacy_refactor_gate_blocking=true` E `omm.capacidade_1_resilience >= 3`).
-
-**Skill canônica:** [`pre-refactor-characterization`](../kit/skills/pre-refactor-characterization/SKILL.md)
-
-**Agent invocado:** [`refactor-safety-auditor`](../kit/agents/refactor-safety-auditor.md)
-
-## Check
-
-```bash
-#!/usr/bin/env bash
-# PT-BR: validar que tasks com kind=refactor em arquivos arriscados têm safety net.
-# Estratégia: descobrir tasks da fase atual, identificar refactor + arquivos flagged,
-# verificar characterization tests linkados, gerar warning ou block conforme mode.
-# Bash 3.2-portable (macOS default).
-set -e
-
-# PT-BR: identificar fase atual via STATE.md
-STATE_FILE=".planning/STATE.md"
-CURRENT_PHASE=""
-if [ -f "$STATE_FILE" ]; then
-  CURRENT_PHASE=$(grep -E "^Fase:" "$STATE_FILE" 2>/dev/null | head -1 | sed -E 's/^Fase: *([0-9]+).*/\1/')
-fi
-
-if [ -z "$CURRENT_PHASE" ]; then
-  echo "INFO: nenhuma fase ativa — gate skip."
-  exit 0
-fi
-
-PHASE_DIR=".planning/phases/phase-${CURRENT_PHASE}"
-[ ! -d "$PHASE_DIR" ] && exit 0
-
-# PT-BR: ler config para mode
-GATE_BLOCKING=false
-if [ -f ".planning/config.json" ] && command -v jq >/dev/null; then
-  CFG=$(jq -r '.workflow.legacy_refactor_gate_blocking // empty' .planning/config.json 2>/dev/null)
-  [ "$CFG" = "true" ] && GATE_BLOCKING=true
-fi
-
-# PT-BR: ler omm — Capacidade 1 (Resilience) calibra mode default
-if [ "$GATE_BLOCKING" = "false" ] && [ -f ".planning/OMM-REPORT.md" ]; then
-  OMM_RES=$(grep -oE 'Capacidade 1.*Resilience.*[0-9]/5' .planning/OMM-REPORT.md 2>/dev/null \
-    | grep -oE '[0-9]/5' | head -1 | sed 's|/5||')
-  if [ -n "$OMM_RES" ] && [ "$OMM_RES" -ge 3 ]; then
-    GATE_BLOCKING=true
-  fi
-fi
-
-# PT-BR: identificar PLAN.md da fase atual
-PLAN_FILES=$(find "$PHASE_DIR" -name "PLAN.md" 2>/dev/null)
-
-REFACTOR_TASKS_RISKY=()
-REFACTOR_TASKS_OK=()
-TOTAL_REFACTOR=0
-
-for plan_file in $PLAN_FILES; do
-  # PT-BR: detectar tasks com kind=refactor (heurística — frase canônica)
-  if grep -qiE "(refactor|refator|extract method|extract class|move method|reorganizar|limpar)" "$plan_file"; then
-    # extrair arquivos mencionados em tasks de refactor
-    AFFECTED_FILES=$(grep -oE "(src|lib|app|supabase|tests)/[a-zA-Z0-9_./-]+\.(ts|tsx|js|jsx|mjs|py|java|go|rb|cs|rs|cpp|c|h)" "$plan_file" 2>/dev/null | sort -u)
-
-    for f in $AFFECTED_FILES; do
-      [ ! -f "$f" ] && continue
-
-      # PT-BR: critérios de risco
-      LINES=$(wc -l < "$f" 2>/dev/null | tr -d ' ')
-      EXTERNAL=false
-      if echo "$f" | grep -qE "(supabase/functions|src/api|/handlers/webhooks|pages/api|integrations)"; then
-        EXTERNAL=true
-      fi
-
-      RISK_HIGH=false
-      [ "${LINES:-0}" -gt 500 ] && RISK_HIGH=true
-      [ "$EXTERNAL" = "true" ] && RISK_HIGH=true
-
-      if [ "$RISK_HIGH" = "true" ]; then
-        TOTAL_REFACTOR=$((TOTAL_REFACTOR + 1))
-
-        # PT-BR: verificar characterization tests linkados
-        STEM=$(basename "$f" | sed 's/\.[^.]*$//')
-        HAS_CHAR=false
-        for chardir in tests test __tests__; do
-          if find "$chardir" -path "*characterization*$STEM*" 2>/dev/null | head -1 | grep -q . ; then
-            HAS_CHAR=true
-            break
-          fi
-        done
-
-        if [ "$HAS_CHAR" = "true" ]; then
-          REFACTOR_TASKS_OK+=("$f")
-        else
-          REFACTOR_TASKS_RISKY+=("$f (lines=$LINES, external=$EXTERNAL)")
-        fi
-      fi
-    done
-  fi
-done
-
-# PT-BR: relatório
-if [ ${#REFACTOR_TASKS_RISKY[@]} -eq 0 ]; then
-  echo "✓ legacy-refactor-safety — sem refactors arriscados sem characterization."
-  if [ ${#REFACTOR_TASKS_OK[@]} -gt 0 ]; then
-    echo "   ${#REFACTOR_TASKS_OK[@]} refactor(s) com characterization linkados."
-  fi
-  exit 0
-fi
-
-# PT-BR: há refactors arriscados sem char
-echo ""
-echo "⚠ legacy-refactor-safety — refactor(s) sem characterization detectado(s):"
-echo ""
-for item in "${REFACTOR_TASKS_RISKY[@]}"; do
-  echo "  - $item"
-done
-echo ""
-echo "Skill canônica: kit/skills/pre-refactor-characterization/SKILL.md"
-echo ""
-echo "Caminhos para resolver:"
-echo "  1. /caracterizar <file>                    (full chain — preferido)"
-echo "  2. /refactor-seguro --mode=sprout <file>  (não toca legado, ADICIONA via sprout)"
-echo "  3. /refactor-seguro --mode=safe-extract <file>  (apenas refactor mecânico)"
-echo "  4. /refactor-seguro --mode=override --ticket REQ-N --reason \"...\"  (último recurso)"
-echo ""
-
-if [ "$GATE_BLOCKING" = "true" ]; then
-  echo "MODE: blocking (workflow.legacy_refactor_gate_blocking=true OR OMM Capacidade 1 ≥ 3)"
-  echo "Resolve antes de prosseguir com /executar-fase."
-  exit 1
-else
-  echo "MODE: consultive (warning apenas)"
-  echo "Para tornar blocking: setar workflow.legacy_refactor_gate_blocking=true em .planning/config.json"
-  exit 0
-fi
-```
-
-## Configuração
-
-```json
-// .planning/config.json
-{
-  "workflow": {
-    "legacy_refactor_gate_blocking": true,
-    "legacy_refactor_min_lines": 500,
-    "legacy_refactor_external_paths": [
-      "supabase/functions/**",
-      "src/api/**",
-      "src/handlers/webhooks/**",
-      "pages/api/**"
-    ]
-  }
-}
-```
-
-**Default:** `legacy_refactor_gate_blocking` = false (consultive). Auto-promove para `true` se `omm-auditor` (v1.9) reportar Capacidade 1 (Resilience) ≥ 3 — sinal de que projeto tem maturity de safety.
-
-## Quando NÃO rodar
-
-- Fase só toca markdown/docs — sem código a refactor
-- Projeto < 1 mês de idade — código novo não é "legacy" no sentido Feathers
-- Projeto sem `omm-auditor` rodado E sem flag explícita — skip silencioso (consultive)
-- Tasks são `bug-fix` ou `feature` (não refactor) — gate só roda em refactor
-
-## Ver também
-
-- [`pre-refactor-characterization`](../kit/skills/pre-refactor-characterization/SKILL.md) — knowledge base do gate
-- [`refactor-safety-auditor`](../kit/agents/refactor-safety-auditor.md) — agent invocado em runtime
-- [`legacy-characterizer`](../kit/agents/legacy-characterizer.md) — agent que gera safety net
-- [`golden-signals-coverage`](./golden-signals-coverage.md) — gate análogo da Suíte SRE
-- [`prr-checklist-coverage`](./prr-checklist-coverage.md) — gate análogo da Suíte SRE para PRR
-- [`omm-no-regression`](./omm-no-regression.md) — gate análogo da Suíte Observabilidade para OMM
+---
+id: legacy-refactor-safety
+stage: pre-execute
+blocking: false
+description: Valida que tasks com kind=refactor em arquivos > 500 linhas OU com contrato externo têm characterization tests linkados. Skip se fase só toca markdown OR fase é greenfield. Opt-in via workflow.legacy_refactor_gate_blocking=true.
+---
+
+# Legacy refactor safety gate
+
+**When to run:** pre-execute (consultive por default; blocking se `workflow.legacy_refactor_gate_blocking=true` E `omm.capacidade_1_resilience >= 3`).
+
+**Skill canônica:** [`pre-refactor-characterization`](../kit/skills/pre-refactor-characterization/SKILL.md)
+
+**Agent invocado:** [`refactor-safety-auditor`](../kit/agents/refactor-safety-auditor.md)
+
+## Check
+
+```bash
+#!/usr/bin/env bash
+# PT-BR: validar que tasks com kind=refactor em arquivos arriscados têm safety net.
+# Estratégia: descobrir tasks da fase atual, identificar refactor + arquivos flagged,
+# verificar characterization tests linkados, gerar warning ou block conforme mode.
+# Bash 3.2-portable (macOS default).
+set -e
+
+# PT-BR: identificar fase atual via STATE.md
+STATE_FILE=".planning/STATE.md"
+CURRENT_PHASE=""
+if [ -f "$STATE_FILE" ]; then
+  CURRENT_PHASE=$(grep -E "^Fase:" "$STATE_FILE" 2>/dev/null | head -1 | sed -E 's/^Fase: *([0-9]+).*/\1/')
+fi
+
+if [ -z "$CURRENT_PHASE" ]; then
+  echo "INFO: nenhuma fase ativa — gate skip."
+  exit 0
+fi
+
+PHASE_DIR=".planning/phases/phase-${CURRENT_PHASE}"
+[ ! -d "$PHASE_DIR" ] && exit 0
+
+# PT-BR: ler config para mode
+GATE_BLOCKING=false
+if [ -f ".planning/config.json" ] && command -v jq >/dev/null; then
+  CFG=$(jq -r '.workflow.legacy_refactor_gate_blocking // empty' .planning/config.json 2>/dev/null)
+  [ "$CFG" = "true" ] && GATE_BLOCKING=true
+fi
+
+# PT-BR: ler omm — Capacidade 1 (Resilience) calibra mode default
+if [ "$GATE_BLOCKING" = "false" ] && [ -f ".planning/OMM-REPORT.md" ]; then
+  OMM_RES=$(grep -oE 'Capacidade 1.*Resilience.*[0-9]/5' .planning/OMM-REPORT.md 2>/dev/null \
+    | grep -oE '[0-9]/5' | head -1 | sed 's|/5||')
+  if [ -n "$OMM_RES" ] && [ "$OMM_RES" -ge 3 ]; then
+    GATE_BLOCKING=true
+  fi
+fi
+
+# PT-BR: identificar PLAN.md da fase atual
+PLAN_FILES=$(find "$PHASE_DIR" -name "PLAN.md" 2>/dev/null)
+
+REFACTOR_TASKS_RISKY=()
+REFACTOR_TASKS_OK=()
+TOTAL_REFACTOR=0
+
+for plan_file in $PLAN_FILES; do
+  # PT-BR: detectar tasks com kind=refactor (heurística — frase canônica)
+  if grep -qiE "(refactor|refator|extract method|extract class|move method|reorganizar|limpar)" "$plan_file"; then
+    # extrair arquivos mencionados em tasks de refactor
+    AFFECTED_FILES=$(grep -oE "(src|lib|app|supabase|tests)/[a-zA-Z0-9_./-]+\.(ts|tsx|js|jsx|mjs|py|java|go|rb|cs|rs|cpp|c|h)" "$plan_file" 2>/dev/null | sort -u)
+
+    for f in $AFFECTED_FILES; do
+      [ ! -f "$f" ] && continue
+
+      # PT-BR: critérios de risco
+      LINES=$(wc -l < "$f" 2>/dev/null | tr -d ' ')
+      EXTERNAL=false
+      if echo "$f" | grep -qE "(supabase/functions|src/api|/handlers/webhooks|pages/api|integrations)"; then
+        EXTERNAL=true
+      fi
+
+      RISK_HIGH=false
+      [ "${LINES:-0}" -gt 500 ] && RISK_HIGH=true
+      [ "$EXTERNAL" = "true" ] && RISK_HIGH=true
+
+      if [ "$RISK_HIGH" = "true" ]; then
+        TOTAL_REFACTOR=$((TOTAL_REFACTOR + 1))
+
+        # PT-BR: verificar characterization tests linkados
+        STEM=$(basename "$f" | sed 's/\.[^.]*$//')
+        HAS_CHAR=false
+        for chardir in tests test __tests__; do
+          if find "$chardir" -path "*characterization*$STEM*" 2>/dev/null | head -1 | grep -q . ; then
+            HAS_CHAR=true
+            break
+          fi
+        done
+
+        if [ "$HAS_CHAR" = "true" ]; then
+          REFACTOR_TASKS_OK+=("$f")
+        else
+          REFACTOR_TASKS_RISKY+=("$f (lines=$LINES, external=$EXTERNAL)")
+        fi
+      fi
+    done
+  fi
+done
+
+# PT-BR: relatório
+if [ ${#REFACTOR_TASKS_RISKY[@]} -eq 0 ]; then
+  echo "✓ legacy-refactor-safety — sem refactors arriscados sem characterization."
+  if [ ${#REFACTOR_TASKS_OK[@]} -gt 0 ]; then
+    echo "   ${#REFACTOR_TASKS_OK[@]} refactor(s) com characterization linkados."
+  fi
+  exit 0
+fi
+
+# PT-BR: há refactors arriscados sem char
+echo ""
+echo "⚠ legacy-refactor-safety — refactor(s) sem characterization detectado(s):"
+echo ""
+for item in "${REFACTOR_TASKS_RISKY[@]}"; do
+  echo "  - $item"
+done
+echo ""
+echo "Skill canônica: kit/skills/pre-refactor-characterization/SKILL.md"
+echo ""
+echo "Caminhos para resolver:"
+echo "  1. /caracterizar <file>                    (full chain — preferido)"
+echo "  2. /refactor-seguro --mode=sprout <file>  (não toca legado, ADICIONA via sprout)"
+echo "  3. /refactor-seguro --mode=safe-extract <file>  (apenas refactor mecânico)"
+echo "  4. /refactor-seguro --mode=override --ticket REQ-N --reason \"...\"  (último recurso)"
+echo ""
+
+if [ "$GATE_BLOCKING" = "true" ]; then
+  echo "MODE: blocking (workflow.legacy_refactor_gate_blocking=true OR OMM Capacidade 1 ≥ 3)"
+  echo "Resolve antes de prosseguir com /executar-fase."
+  exit 1
+else
+  echo "MODE: consultive (warning apenas)"
+  echo "Para tornar blocking: setar workflow.legacy_refactor_gate_blocking=true em .planning/config.json"
+  exit 0
+fi
+```
+
+## Configuração
+
+```json
+// .planning/config.json
+{
+  "workflow": {
+    "legacy_refactor_gate_blocking": true,
+    "legacy_refactor_min_lines": 500,
+    "legacy_refactor_external_paths": [
+      "supabase/functions/**",
+      "src/api/**",
+      "src/handlers/webhooks/**",
+      "pages/api/**"
+    ]
+  }
+}
+```
+
+**Default:** `legacy_refactor_gate_blocking` = false (consultive). Auto-promove para `true` se `omm-auditor` (v1.9) reportar Capacidade 1 (Resilience) ≥ 3 — sinal de que projeto tem maturity de safety.
+
+## Quando NÃO rodar
+
+- Fase só toca markdown/docs — sem código a refactor
+- Projeto < 1 mês de idade — código novo não é "legacy" no sentido Feathers
+- Projeto sem `omm-auditor` rodado E sem flag explícita — skip silencioso (consultive)
+- Tasks são `bug-fix` ou `feature` (não refactor) — gate só roda em refactor
+
+## Ver também
+
+- [`pre-refactor-characterization`](../kit/skills/pre-refactor-characterization/SKILL.md) — knowledge base do gate
+- [`refactor-safety-auditor`](../kit/agents/refactor-safety-auditor.md) — agent invocado em runtime
+- [`legacy-characterizer`](../kit/agents/legacy-characterizer.md) — agent que gera safety net
+- [`golden-signals-coverage`](./golden-signals-coverage.md) — gate análogo da Suíte SRE
+- [`prr-checklist-coverage`](./prr-checklist-coverage.md) — gate análogo da Suíte SRE para PRR
+- [`omm-no-regression`](./omm-no-regression.md) — gate análogo da Suíte Observabilidade para OMM