@luanpdd/kit-mcp 1.10.0 → 1.12.0

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>

package/kit/commands/concluir-marco.md

@@ -205,4 +205,44 @@ Quando `workflow.complete_milestone_prr_gate = true` (default `false` — opt-in
 - "Gate ligado em projeto early stage" → bloco "Quando ligar gate" exige ≥ 2 sinais de production maturity
 
 **REQ:** INT-FW-V2-02.
-</sre_integration>
+</sre_integration>
+
+<sre_resilience_integration>
+**Release pipeline policy gate (v1.11 — INT-FW-V3-01):**
+
+Quando `workflow.complete_milestone_release_pipeline_gate = true` (default `false` — opt-in), o workflow inclui passo de validação de release pipeline **paralelo ao PRR gate**:
+
+1. Invocar `Task(subagent_type=release-pipeline-auditor, prompt="...")` para gerar `.planning/RELEASE-AUDIT.md` fresco
+2. Verificar score agregado:
+   - **ROBUST (≥ 25/30):** gate aprova — milestone arquivável
+   - **ADEQUATE (20-24):** warnings explícitos no archive; arquivável
+   - **FRAGILE (15-19):** BLOQUEIA — listar top 5 fixes; user resolve antes de re-tentar
+   - **BROKEN (< 15):** BLOQUEIA forte — escalation; pipeline não pode ser fonte de verdade
+3. Resultado salvo como anexo no `.planning/milestones/v<version>-MILESTONE.md` (audit trail)
+
+**Quando ligar gate (paralelo ao PRR):**
+
+- Projeto tem release frequency ≥ 1×/semana
+- Projeto tem deploys que afetam usuários externos (não só dogfooding)
+- Equipe quer disciplina release engineering (cap 8 livro Google SRE)
+- Projeto já tem PRR gate ligado (sinal de production maturity)
+
+**Quando manter desligado:**
+
+- Projeto < 6 meses (pipeline ainda imatura)
+- Solo dev sem CI/CD complexo
+- Releases mensais ou raros (overhead > valor)
+
+**Skills consultadas:** [hermetic-builds](../skills/hermetic-builds/SKILL.md), [release-engineering](../skills/release-engineering/SKILL.md) (cap 8 livro Google SRE).
+
+**Gate executável:** `gates/release-pipeline-policy.md` (criado em Phase 47 — QA-SRE2-04). Workflow `.claude/framework/workflows/complete-milestone.md` consulta esse gate quando flag `true`.
+
+**Anti-patterns prevenidos:**
+
+- "Release pipeline frágil porque historicamente funcionou" → gate força quantificação objetiva
+- "Build não-hermético com `npm install`" → gate Hermeticidade dimension catches
+- "Branch protection desligada para velocidade" → gate Policy Enforcement dimension catches
+- "Gate ligado em projeto early stage" → bloco "Quando ligar gate" exige sinais de maturity
+
+**REQ:** INT-FW-V3-01.
+</sre_resilience_integration>

package/kit/commands/detectar-duplicacao.md

@@ -0,0 +1,197 @@
+---
+name: detectar-duplicacao
+description: Invoca shotgun-surgery-detector — detecta duplicação sintática (jscpd/regex) + semântica (embeddings) cross-codebase, prioriza por size × frequency × extract feasibility. Modernização cap 21 Feathers.
+argument-hint: "<root_dir> [--threshold 0.85] [--min-cluster-size 3] [--mode syntactic|semantic|both] [--provider openai|pgvector|auto]"
+allowed-tools:
+  - Read
+  - Bash
+  - Grep
+  - Glob
+  - Task
+  - Write
+  - mcp__supabase__execute_sql
+---
+
+<objective>
+Detectar **shotgun surgery** (mesma mudança/lógica espalhada em N lugares) cross-codebase via:
+1. **Detecção sintática** — Feathers cap 21 original; jscpd/regex/AST
+2. **Detecção semântica** — modernização 2026; embeddings + cosine similarity
+
+Invoca o agente [`shotgun-surgery-detector`](../agents/shotgun-surgery-detector.md) que aplica a skill [`legacy-shotgun-surgery`](../skills/legacy-shotgun-surgery/SKILL.md). Output: clusters priorizados por (size × frequency × extract feasibility).
+
+**Cria/Atualiza:**
+- `.planning/SHOTGUN-SURGERY.md` — clusters detectados, top 10 priorizados, sugestões extract
+
+**Após:** o user tem lista acionável de candidates a extract method/class para reduzir change points. PR sequence canônica: extract first → modify second.
+</objective>
+
+<context>
+**Argumentos:**
+- `<root_dir>` — diretório raiz a analisar (default: `.`)
+- `--threshold 0.85` — cosine similarity mínima para semantic cluster (default: 0.85)
+- `--min-cluster-size 3` — Rule of 3 (default: 3)
+- `--min-block-lines 10` — tamanho mínimo de bloco para análise (default: 10)
+- `--mode syntactic|semantic|both` — modo (default: `both`)
+- `--provider openai|pgvector|auto` — embedding provider (default: auto-detect)
+- `--output PATH` — caminho do output (default: `.planning/SHOTGUN-SURGERY.md`)
+
+**Exemplos:**
+```
+/detectar-duplicacao src/                                              # both modes, defaults
+/detectar-duplicacao . --mode=syntactic                                # só Feathers original (sem custo IA)
+/detectar-duplicacao src/ --threshold 0.90                              # mais conservador
+/detectar-duplicacao src/ --min-cluster-size 5                         # só clusters grandes
+/detectar-duplicacao src/ --provider=pgvector                          # forçar self-hosted
+```
+
+**Pré-requisitos:**
+- jscpd disponível para sintática (`npm install -g jscpd` se não)
+- OPENAI_API_KEY OR pgvector setup para semântica (auto-detect)
+- Node.js 20+ no path para chamadas embeddings
+
+**Quando este comando é o caminho:**
+- Você sente "estou mudando isso em N lugares" — use detector pra confirmar/quantificar
+- Refactor proposto inclui extract method/class — detector confirma 3+ ocorrências
+- Code review onde reviewer suspeita de DRY violations
+- Pré-requisito para `/legacy refactor` quando shotgun é a real causa raiz
+</context>
+
+<process>
+
+## 1. Parsear argumentos
+
+```bash
+ROOT_DIR=$(echo "$ARGUMENTS" | awk '{print $1}')
+THRESHOLD=$(echo "$ARGUMENTS" | grep -oE -- '--threshold [0-9.]+' | awk '{print $2}')
+MIN_CLUSTER=$(echo "$ARGUMENTS" | grep -oE -- '--min-cluster-size [0-9]+' | awk '{print $2}')
+MIN_BLOCK=$(echo "$ARGUMENTS" | grep -oE -- '--min-block-lines [0-9]+' | awk '{print $2}')
+MODE=$(echo "$ARGUMENTS" | grep -oE -- '--mode[= ][^ ]+' | sed 's/--mode[= ]//')
+PROVIDER=$(echo "$ARGUMENTS" | grep -oE -- '--provider[= ][^ ]+' | sed 's/--provider[= ]//')
+OUTPUT_PATH=$(echo "$ARGUMENTS" | grep -oE -- '--output [^ ]+' | awk '{print $2}')
+
+[ -z "$ROOT_DIR" ]     && ROOT_DIR="."
+[ -z "$THRESHOLD" ]    && THRESHOLD="0.85"
+[ -z "$MIN_CLUSTER" ]  && MIN_CLUSTER=3
+[ -z "$MIN_BLOCK" ]    && MIN_BLOCK=10
+[ -z "$MODE" ]         && MODE="both"
+[ -z "$PROVIDER" ]     && PROVIDER="auto"
+[ -z "$OUTPUT_PATH" ]  && OUTPUT_PATH=".planning/SHOTGUN-SURGERY.md"
+
+if [ ! -d "$ROOT_DIR" ]; then
+  echo "ERROR: root_dir não encontrado: $ROOT_DIR"
+  exit 1
+fi
+
+mkdir -p "$(dirname "$OUTPUT_PATH")"
+```
+
+## 2. Detectar capabilities
+
+```bash
+HAS_JSCPD=false
+command -v npx >/dev/null && npx jscpd --version >/dev/null 2>&1 && HAS_JSCPD=true
+
+HAS_OPENAI=false
+[ -n "$OPENAI_API_KEY" ] && HAS_OPENAI=true
+
+HAS_PGVECTOR=false
+if command -v psql >/dev/null && psql -tc "select 1 from pg_extension where extname='vector'" 2>/dev/null | grep -q 1; then
+  HAS_PGVECTOR=true
+fi
+
+# adjust mode if needed
+if [ "$MODE" = "both" ] || [ "$MODE" = "semantic" ]; then
+  if [ "$HAS_OPENAI" = false ] && [ "$HAS_PGVECTOR" = false ]; then
+    echo "WARN: nenhum embedding provider disponível. Mode forçado para 'syntactic'."
+    MODE="syntactic"
+  fi
+fi
+```
+
+## 3. Dispatch para `shotgun-surgery-detector`
+
+```text
+Task(
+  subagent_type="shotgun-surgery-detector",
+  prompt="
+root_dir: ${ROOT_DIR}
+threshold: ${THRESHOLD}
+min_cluster_size: ${MIN_CLUSTER}
+min_block_lines: ${MIN_BLOCK}
+mode: ${MODE}
+embedding_provider: ${PROVIDER}
+output_path: ${OUTPUT_PATH}
+
+Aplicar skill legacy-shotgun-surgery. Etapas:
+1. Detecção sintática (sempre roda) — jscpd com min-lines + min-tokens
+2. Detecção semântica (se mode=semantic|both) — embeddings + cosine similarity
+3. Merge clusters (sintático + semântico); marker [SYNTACTIC] / [SEMANTIC] / [BOTH]
+4. Priorização canônica — score = (cluster_size × avg_block_lines × frequency_factor) / extract_feasibility
+5. Filter: cross-cutting noise (test files etc)
+6. Escrever .planning/SHOTGUN-SURGERY.md com:
+   - Resumo (X clusters totais)
+   - Top 10 priorizados com diff visual
+   - Sugestões de extract com nome canônico
+   - Esforço estimado por cluster
+"
+)
+```
+
+## 4. Pós-output
+
+```
+═══════════════════════════════════════════════════════════
+ framework ► DETECTAR-DUPLICACAO ▸ ${OUTPUT_PATH}
+═══════════════════════════════════════════════════════════
+
+[output do shotgun-surgery-detector]
+
+## ⚠ Validação obrigatória
+
+Cada cluster — especialmente semantic — precisa de **revisão humana**:
+- Falsos positivos comuns: 2 funções com nomes/comments similares mas implementações diferentes
+- Variations entre ocorrências podem ser INTENCIONAIS (rounding diferente, encoding diferente)
+- Extract uniformiza → mudança comportamental possível
+
+NÃO auto-extract. Cluster aprovado por humano vira PR.
+
+## Próximos passos por cluster aprovado
+
+1. **Caracterizar cada ocorrência** (capturar comportamento atual):
+   ```bash
+   /caracterizar <file-da-ocorrencia-1>
+   /caracterizar <file-da-ocorrencia-2>
+   ...
+   ```
+2. **Validar outputs idênticos** OU documentar diferenças intencionais
+3. **Escolher nome canônico** (resonates com TODAS as N localizações)
+4. **Extract para 1 lugar** (criar utility/módulo compartilhado)
+5. **Substituir cada ocorrência** (1 commit por substituição, revertível)
+6. **Re-rodar detector** após PRs para verificar redução de clusters
+
+## Custo (modo semantic)
+
+- ~$<cost>/run com OpenAI text-embedding-3-small
+- $0 com pgvector self-hosted
+- 0 com mode=syntactic only
+
+## Cross-suite
+
+- **/storytelling** (v1.12) — story dos módulos identifica clusters mais provável
+- **/caracterizar** (v1.12) — characterize cada ocorrência ANTES de extract
+- **/legacy refactor** (v1.12) — chain canônico para extract
+- **/auditar-marco** — rerodar shotgun detector trimestral revela acumulação de débito
+```
+
+</process>
+
+<success_criteria>
+- [ ] $ARGUMENTS parseados (root_dir opcional, defaults sensíveis)
+- [ ] Capabilities detectadas (jscpd, OpenAI, pgvector)
+- [ ] Mode degraded se provider de embedding indisponível
+- [ ] `shotgun-surgery-detector` invocado via Task
+- [ ] Output forwarded transparentemente
+- [ ] Warning de validação manual obrigatória
+- [ ] Próximos passos: characterize → validate → extract → substituir → re-detect
+- [ ] Cross-references com /storytelling, /caracterizar, /legacy refactor
+</success_criteria>

package/kit/commands/discutir-fase.md

@@ -88,3 +88,44 @@ O `plan-checker` invocado pelo `/planejar-fase` (Phase 33 — INT-FW-02) lê est
 
 **REQ:** INT-FW-01.
 </observability_integration>
+
+<legacy_refactor_integration>
+**Integração com Suíte Legacy Code (Feathers):**
+
+Quando o workflow detecta intent de **refactor** (palavras-chave em descrição da fase: "refator", "refactor", "extrair", "limpar", "reorganizar", "split", "quebrar classe/módulo"), inclui pergunta canônica:
+
+> "Esta fase envolve refactor de arquivo existente? Se sim, qual é o arquivo alvo?"
+
+Para cada arquivo identificado:
+1. Coleta line count + checa se path matches contrato externo (supabase/functions, src/api, webhooks, pages/api)
+2. Invoca [`refactor-safety-auditor`](../agents/refactor-safety-auditor.md) **em modo dry-run** para coletar evidências sem bloquear
+3. Resultado registrado em CONTEXT.md em seção `<refactor_safety>`:
+
+```markdown
+<refactor_safety>
+## Arquivos alvo de refactor
+
+| Arquivo | Linhas | Contrato externo | Cobertura | Char tests | Veredito do gate |
+|---|---|---|---|---|---|
+| src/orders/handler.ts | 724 | true | 12% | absent | BLOCK |
+| src/orders/utils.ts | 89 | false | 78% | absent | GO |
+
+## Recomendação
+
+Para `src/orders/handler.ts`:
+  - Caminho preferido: /caracterizar antes de refactor (custo: 8-16h)
+  - Alternativa: /refactor-seguro --mode=sprout (se mudança ADICIONA, não modifica)
+  - Para safe-extract: assinar checklist canônico de safe extraction
+  - Override possível com ticket + reason
+
+Para `src/orders/utils.ts`:
+  - Refactor pode prosseguir; cobertura adequada existe.
+</refactor_safety>
+```
+
+`plan-checker` consume essa seção. Se gate retorna BLOCK e mode=blocking, plano não é aprovado até user escolher caminho explícito.
+
+**Skill canônica:** [`pre-refactor-characterization`](../skills/pre-refactor-characterization/SKILL.md)
+
+**Quando skip:** fase puramente de infraestrutura (markdown, config, tooling), fase greenfield (sem arquivos existentes a modificar), OR `workflow.legacy_refactor_questions=false` em config.
+</legacy_refactor_integration>

package/kit/commands/encontrar-seams.md

@@ -0,0 +1,136 @@
+---
+name: encontrar-seams
+description: Invoca seam-finder — analisa código para identificar seams (object/link/preprocessing) e recomenda técnica do cap 25 Feathers para quebrar dependências bloqueantes. Pré-requisito quando deps externas impedem characterization.
+argument-hint: "<target_file> [--symbol <name>] [--prefer object|link|preprocessing] [--output PATH]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Grep
+  - Glob
+  - Task
+---
+
+<objective>
+Analisar código alvo para identificar **seams** (lugares onde se pode alterar comportamento sem editar lá) e recomendar **técnica do catálogo cap 25 Feathers** para quebrar dependências bloqueantes (DB real, HTTP, framework objects, singletons, clocks). Invoca o agente [`seam-finder`](../agents/seam-finder.md) que aplica a skill [`legacy-seams-and-test-harness`](../skills/legacy-seams-and-test-harness/SKILL.md) — decision tree por linguagem, prioridade pelo MENOR custo + MAIOR reversibilidade.
+
+**Cria/Atualiza:**
+- `.planning/SEAM-ANALYSIS.md` — relatório com deps bloqueantes, técnicas recomendadas, sequência canônica de commits
+
+**Após:** o user tem plano mecânico para tornar código testável antes de invocar `/caracterizar`. Tipicamente 5-30 minutos por dep bloqueante; sequência de pequenos commits revertíveis.
+</objective>
+
+<context>
+**Argumentos:**
+- `<target_file>` — caminho do arquivo a analisar (relativo ao project root) — OBRIGATÓRIO
+- `--symbol <name>` — analisar apenas símbolo específico (default: arquivo inteiro)
+- `--prefer object|link|preprocessing` — preferência de tipo de seam (default: object)
+- `--output PATH` — caminho do output (default: `.planning/SEAM-ANALYSIS.md`)
+
+**Exemplos:**
+```
+/encontrar-seams src/orders/OrderService.ts                        # análise completa
+/encontrar-seams src/orders/OrderService.ts --symbol charge        # método específico
+/encontrar-seams src/legacy/Client.cpp --prefer link               # forçar link seam (C++ legado)
+```
+
+**Quando este comando é o caminho certo:**
+- `/caracterizar` falhou porque deps externas impedem isolamento
+- Construtor faz I/O direto (cria conexão DB no constructor)
+- Usar singleton/global hardcoded no método a testar
+- Framework type complexo (HttpServletRequest, Express.Request) bloqueando teste
+- Código procedural (C, COBOL, Go) onde polimorfismo não está disponível
+
+**Quando NÃO é o caminho:**
+- Código já é testável (deps injetadas via DI) → usar `/caracterizar` direto
+- Código é puro (sem I/O) → não precisa break-dep
+- Mudança é safe-extraction (rename, IDE-extract) → usar `/refactor-seguro --mode=safe-extract`
+</context>
+
+<process>
+
+## 1. Parsear argumentos
+
+```bash
+TARGET_FILE=$(echo "$ARGUMENTS" | awk '{print $1}')
+SYMBOL=$(echo "$ARGUMENTS" | grep -oE -- '--symbol [^ ]+' | awk '{print $2}')
+PREFER=$(echo "$ARGUMENTS" | grep -oE -- '--prefer [^ ]+' | awk '{print $2}')
+OUTPUT_PATH=$(echo "$ARGUMENTS" | grep -oE -- '--output [^ ]+' | awk '{print $2}')
+
+[ -z "$OUTPUT_PATH" ] && OUTPUT_PATH=".planning/SEAM-ANALYSIS.md"
+[ -z "$PREFER" ]      && PREFER="object"
+
+if [ -z "$TARGET_FILE" ]; then
+  echo "ERROR: target_file é obrigatório."
+  echo "Uso: /encontrar-seams <target_file> [opções]"
+  exit 1
+fi
+
+if [ ! -f "$TARGET_FILE" ]; then
+  echo "ERROR: arquivo não encontrado: $TARGET_FILE"
+  exit 1
+fi
+
+mkdir -p "$(dirname "$OUTPUT_PATH")"
+```
+
+## 2. Dispatch para `seam-finder`
+
+```text
+Task(
+  subagent_type="seam-finder",
+  prompt="
+target_file: ${TARGET_FILE}
+${SYMBOL:+target_symbol: ${SYMBOL}}
+output_path: ${OUTPUT_PATH}
+prefer_technique: ${PREFER}
+
+Aplicar skill legacy-seams-and-test-harness. Etapas:
+1. Detectar linguagem + paradigma (OO vs procedural)
+2. Mapear deps externas (network/DB/FS/clock/random/UUID/global/framework-type/construtor-caro)
+3. Identificar tipos de seam disponíveis (object/link/preprocessing)
+4. Aplicar decision tree do cap 25 escolhendo técnica de menor custo + maior reversibilidade
+5. Gerar SEAM-ANALYSIS.md com:
+   - tabela de deps bloqueantes
+   - técnica recomendada por dep com custo + reversibilidade
+   - exemplo ANTES/DEPOIS por técnica
+   - sequência canônica de commits (mais seguro → mais arriscado)
+6. Output curto para caller: lista de N deps + custo total estimado
+"
+)
+```
+
+## 3. Pós-output: integração com fluxo
+
+```
+═══════════════════════════════════════════════════════════
+ framework ► ENCONTRAR-SEAMS ▸ ${OUTPUT_PATH}
+═══════════════════════════════════════════════════════════
+
+[output do seam-finder]
+
+## Próximos passos
+
+1. **Aplicar técnicas** — seguir sequência canônica em ${OUTPUT_PATH}
+   Cada commit é single-goal, mecânico, revertível
+2. **Rodar suite após cada commit** — compilação verde + tests verdes
+3. **/caracterizar <file>** — após break-deps complete, characterization fica viável
+4. **/auditar-refactor <file>** — gate deve retornar GO ou WARN agora (não mais BLOCK)
+
+## Cross-suite
+
+- Em projetos Supabase com Edge Functions: `supabase-edge-fn-writer` (v1.8) já segue patterns testáveis
+- Para skills de SOLID/DI: ver também `supabase-architect` (v1.8) — schema design considera testabilidade similarmente
+- Para mudança em código que afeta SLOs: `/instrumentar-fase` (v1.9) durante refactor preserva visibility
+```
+
+</process>
+
+<success_criteria>
+- [ ] $ARGUMENTS parseados (target_file obrigatório)
+- [ ] `seam-finder` invocado via `Task(subagent_type=...)` com prompt completo (6 etapas)
+- [ ] `.planning/SEAM-ANALYSIS.md` criado pelo agent com deps + técnicas + sequência de commits
+- [ ] Output forwarded transparentemente do agent
+- [ ] Próximos passos sugeridos: aplicar técnicas, rodar suite, /caracterizar, /auditar-refactor
+- [ ] Cross-references com Suíte Supabase (v1.8) e Observabilidade (v1.9) onde aplicável
+</success_criteria>