@luanpdd/kit-mcp 1.18.0 → 1.20.0

package/kit/commands/depurar.md

@@ -1,190 +1,190 @@
----
-name: depurar
-description: Depuração sistemática com estado persistente entre resets de contexto
-argument-hint: "[descrição do problema]"
-allowed-tools:
-  - Read
-  - Bash
-  - Task
-  - AskUserQuestion
----
-
-<objective>
-Depurar problemas usando o método científico com isolamento de subagente.
-
-**Papel do orquestrador:** Coletar sintomas, invocar agente debugger, tratar checkpoints, invocar continuações.
-
-**Por que subagente:** Investigação consome contexto rapidamente (ler arquivos, formar hipóteses, testar). Contexto fresco de 200k por investigação. Contexto principal permanece enxuto para interação com o usuário.
-</objective>
-
-<available_agent_types>
-Tipos de subagente framework válidos (usar nomes exatos — não usar 'general-purpose'):
-- debugger — Diagnostica e corrige problemas
-- schema-checker — Pré-validação de SQL (FK, JOIN, INSERT) contra schema real via Supabase MCP. Use quando o bug envolve migration que falhou em apply ou suspeita de drift entre comentário do dev e schema real.
-</available_agent_types>
-
-<supabase_pre_check>
-## Triagem rápida — bug envolve SQL/Supabase?
-
-Se o $ARGUMENTS ou sintomas mencionam algum destes patterns, faça **pre-validação com `schema-checker`** ANTES de invocar o `debugger` genérico:
-
-| Sintoma | Razão |
-|---|---|
-| "migration falhou em apply" | `schema-checker` valida FKs/colunas/tabelas — sintoma comum é referência a coluna/tabela inexistente |
-| "RLS quebrou query" ou "query lenta após RLS" | Provavelmente `auth.uid()` sem `(select)` wrapper; veja skill `supabase-rls-policies` |
-| "Edge Function quebrou em deploy" | Provavelmente bare specifier ou import sem versão; veja skill `supabase-edge-functions` |
-| "user_metadata em policy" | Privilege escalation; veja skill `supabase-rls-policies` (REGRA absoluta) |
-| "service_role exposto" | Vazamento via `NEXT_PUBLIC_*`; veja skill `supabase-auth-ssr` |
-
-Se aplicável: invoque `Task(subagent_type=schema-checker, prompt=...)` primeiro. Se schema-checker retorna GO mas o bug persiste, então invoque o `debugger`.
-</supabase_pre_check>
-
-<context>
-Problema do usuário: $ARGUMENTS
-
-Verificar sessões ativas:
-```bash
-ls .planning/debug/*.md 2>/dev/null | grep -v resolved | head -5
-```
-</context>
-
-<process>
-
-## 0. Inicializar Contexto
-
-```bash
-INIT=$(node "./.claude/framework/bin/tools.cjs" state load)
-if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
-```
-
-Extrair `commit_docs` do JSON de init. Resolver modelo do depurador:
-```bash
-debugger_model=$(node "./.claude/framework/bin/tools.cjs" resolve-model debugger --raw)
-```
-
-## 1. Verificar Sessões Ativas
-
-Se existirem sessões ativas E sem $ARGUMENTS:
-- Listar sessões com status, hipótese, próxima ação
-- Usuário escolhe número para retomar OU descreve novo problema
-
-Se $ARGUMENTS fornecido OU usuário descreve novo problema:
-- Continuar para coleta de sintomas
-
-## 2. Coletar Sintomas (se novo problema)
-
-Usar AskUserQuestion para cada:
-
-1. **Comportamento esperado** - O que deveria acontecer?
-2. **Comportamento atual** - O que acontece em vez disso?
-3. **Mensagens de erro** - Algum erro? (colar ou descrever)
-4. **Cronologia** - Quando isso começou? Já funcionou?
-5. **Reprodução** - Como você aciona o problema?
-
-Após todos coletados, confirmar pronto para investigar.
-
-## 3. Invocar Agente debugger
-
-Preencher prompt e invocar:
-
-```markdown
-<objective>
-Investigar problema: {slug}
-
-**Resumo:** {trigger}
-</objective>
-
-<symptoms>
-expected: {expected}
-actual: {actual}
-errors: {errors}
-reproduction: {reproduction}
-timeline: {timeline}
-</symptoms>
-
-<mode>
-symptoms_prefilled: true
-goal: find_and_fix
-</mode>
-
-<debug_file>
-Criar: .planning/debug/{slug}.md
-</debug_file>
-```
-
-```
-Task(
-  prompt=filled_prompt,
-  subagent_type="debugger",
-  model="{debugger_model}",
-  description="Depurar {slug}"
-)
-```
-
-## 4. Tratar Retorno do Agente
-
-**Se `## CAUSA RAIZ ENCONTRADA`:**
-- Exibir causa raiz e resumo de evidências
-- Oferecer opções:
-  - "Corrigir agora" - invocar subagente de correção
-  - "Planejar correção" - sugerir /planejar-fase --gaps
-  - "Correção manual" - concluído
-
-**Se `## CHECKPOINT ATINGIDO`:**
-- Apresentar detalhes do checkpoint ao usuário
-- Obter resposta do usuário
-- Se tipo de checkpoint for `human-verify`:
-  - Se usuário confirmar corrigido: continuar para o agente finalizar/resolver/arquivar
-  - Se usuário reportar problemas: continuar para o agente retornar à investigação/correção
-- Invocar agente de continuação (ver passo 5)
-
-**Se `## INVESTIGAÇÃO INCONCLUSIVA`:**
-- Mostrar o que foi verificado e eliminado
-- Oferecer opções:
-  - "Continuar investigando" - invocar novo agente com contexto adicional
-  - "Investigação manual" - concluído
-  - "Adicionar mais contexto" - coletar mais sintomas, invocar novamente
-
-## 5. Invocar Agente de Continuação (Após Checkpoint)
-
-Quando usuário responde ao checkpoint, invocar agente fresco:
-
-```markdown
-<objective>
-Continuar depuração de {slug}. Evidências estão no arquivo de depuração.
-</objective>
-
-<prior_state>
-<files_to_read>
-- .planning/debug/{slug}.md (Estado da sessão de depuração)
-</files_to_read>
-</prior_state>
-
-<checkpoint_response>
-**Tipo:** {checkpoint_type}
-**Resposta:** {user_response}
-</checkpoint_response>
-
-<mode>
-goal: find_and_fix
-</mode>
-```
-
-```
-Task(
-  prompt=continuation_prompt,
-  subagent_type="debugger",
-  model="{debugger_model}",
-  description="Continuar depuração {slug}"
-)
-```
-
-</process>
-
-<success_criteria>
-- [ ] Sessões ativas verificadas
-- [ ] Sintomas coletados (se novo)
-- [ ] debugger invocado com contexto
-- [ ] Checkpoints tratados corretamente
-- [ ] Causa raiz confirmada antes de corrigir
-</success_criteria>
+---
+name: depurar
+description: Depuração sistemática com estado persistente entre resets de contexto
+argument-hint: "[descrição do problema]"
+allowed-tools:
+  - Read
+  - Bash
+  - Task
+  - AskUserQuestion
+---
+
+<objective>
+Depurar problemas usando o método científico com isolamento de subagente.
+
+**Papel do orquestrador:** Coletar sintomas, invocar agente debugger, tratar checkpoints, invocar continuações.
+
+**Por que subagente:** Investigação consome contexto rapidamente (ler arquivos, formar hipóteses, testar). Contexto fresco de 200k por investigação. Contexto principal permanece enxuto para interação com o usuário.
+</objective>
+
+<available_agent_types>
+Tipos de subagente framework válidos (usar nomes exatos — não usar 'general-purpose'):
+- debugger — Diagnostica e corrige problemas
+- schema-checker — Pré-validação de SQL (FK, JOIN, INSERT) contra schema real via Supabase MCP. Use quando o bug envolve migration que falhou em apply ou suspeita de drift entre comentário do dev e schema real.
+</available_agent_types>
+
+<supabase_pre_check>
+## Triagem rápida — bug envolve SQL/Supabase?
+
+Se o $ARGUMENTS ou sintomas mencionam algum destes patterns, faça **pre-validação com `schema-checker`** ANTES de invocar o `debugger` genérico:
+
+| Sintoma | Razão |
+|---|---|
+| "migration falhou em apply" | `schema-checker` valida FKs/colunas/tabelas — sintoma comum é referência a coluna/tabela inexistente |
+| "RLS quebrou query" ou "query lenta após RLS" | Provavelmente `auth.uid()` sem `(select)` wrapper; veja skill `supabase-rls-policies` |
+| "Edge Function quebrou em deploy" | Provavelmente bare specifier ou import sem versão; veja skill `supabase-edge-functions` |
+| "user_metadata em policy" | Privilege escalation; veja skill `supabase-rls-policies` (REGRA absoluta) |
+| "service_role exposto" | Vazamento via `NEXT_PUBLIC_*`; veja skill `supabase-auth-ssr` |
+
+Se aplicável: invoque `Task(subagent_type=schema-checker, prompt=...)` primeiro. Se schema-checker retorna GO mas o bug persiste, então invoque o `debugger`.
+</supabase_pre_check>
+
+<context>
+Problema do usuário: $ARGUMENTS
+
+Verificar sessões ativas:
+```bash
+ls .planning/debug/*.md 2>/dev/null | grep -v resolved | head -5
+```
+</context>
+
+<process>
+
+## 0. Inicializar Contexto
+
+```bash
+INIT=$(node "./.claude/framework/bin/tools.cjs" state load)
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Extrair `commit_docs` do JSON de init. Resolver modelo do depurador:
+```bash
+debugger_model=$(node "./.claude/framework/bin/tools.cjs" resolve-model debugger --raw)
+```
+
+## 1. Verificar Sessões Ativas
+
+Se existirem sessões ativas E sem $ARGUMENTS:
+- Listar sessões com status, hipótese, próxima ação
+- Usuário escolhe número para retomar OU descreve novo problema
+
+Se $ARGUMENTS fornecido OU usuário descreve novo problema:
+- Continuar para coleta de sintomas
+
+## 2. Coletar Sintomas (se novo problema)
+
+Usar AskUserQuestion para cada:
+
+1. **Comportamento esperado** - O que deveria acontecer?
+2. **Comportamento atual** - O que acontece em vez disso?
+3. **Mensagens de erro** - Algum erro? (colar ou descrever)
+4. **Cronologia** - Quando isso começou? Já funcionou?
+5. **Reprodução** - Como você aciona o problema?
+
+Após todos coletados, confirmar pronto para investigar.
+
+## 3. Invocar Agente debugger
+
+Preencher prompt e invocar:
+
+```markdown
+<objective>
+Investigar problema: {slug}
+
+**Resumo:** {trigger}
+</objective>
+
+<symptoms>
+expected: {expected}
+actual: {actual}
+errors: {errors}
+reproduction: {reproduction}
+timeline: {timeline}
+</symptoms>
+
+<mode>
+symptoms_prefilled: true
+goal: find_and_fix
+</mode>
+
+<debug_file>
+Criar: .planning/debug/{slug}.md
+</debug_file>
+```
+
+```
+Task(
+  prompt=filled_prompt,
+  subagent_type="debugger",
+  model="{debugger_model}",
+  description="Depurar {slug}"
+)
+```
+
+## 4. Tratar Retorno do Agente
+
+**Se `## CAUSA RAIZ ENCONTRADA`:**
+- Exibir causa raiz e resumo de evidências
+- Oferecer opções:
+  - "Corrigir agora" - invocar subagente de correção
+  - "Planejar correção" - sugerir /planejar-fase --gaps
+  - "Correção manual" - concluído
+
+**Se `## CHECKPOINT ATINGIDO`:**
+- Apresentar detalhes do checkpoint ao usuário
+- Obter resposta do usuário
+- Se tipo de checkpoint for `human-verify`:
+  - Se usuário confirmar corrigido: continuar para o agente finalizar/resolver/arquivar
+  - Se usuário reportar problemas: continuar para o agente retornar à investigação/correção
+- Invocar agente de continuação (ver passo 5)
+
+**Se `## INVESTIGAÇÃO INCONCLUSIVA`:**
+- Mostrar o que foi verificado e eliminado
+- Oferecer opções:
+  - "Continuar investigando" - invocar novo agente com contexto adicional
+  - "Investigação manual" - concluído
+  - "Adicionar mais contexto" - coletar mais sintomas, invocar novamente
+
+## 5. Invocar Agente de Continuação (Após Checkpoint)
+
+Quando usuário responde ao checkpoint, invocar agente fresco:
+
+```markdown
+<objective>
+Continuar depuração de {slug}. Evidências estão no arquivo de depuração.
+</objective>
+
+<prior_state>
+<files_to_read>
+- .planning/debug/{slug}.md (Estado da sessão de depuração)
+</files_to_read>
+</prior_state>
+
+<checkpoint_response>
+**Tipo:** {checkpoint_type}
+**Resposta:** {user_response}
+</checkpoint_response>
+
+<mode>
+goal: find_and_fix
+</mode>
+```
+
+```
+Task(
+  prompt=continuation_prompt,
+  subagent_type="debugger",
+  model="{debugger_model}",
+  description="Continuar depuração {slug}"
+)
+```
+
+</process>
+
+<success_criteria>
+- [ ] Sessões ativas verificadas
+- [ ] Sintomas coletados (se novo)
+- [ ] debugger invocado com contexto
+- [ ] Checkpoints tratados corretamente
+- [ ] Causa raiz confirmada antes de corrigir
+</success_criteria>

package/kit/commands/discutir-fase.md

@@ -1,131 +1,131 @@
----
-name: discutir-fase
-description: Reúne contexto da fase por questionamento adaptativo antes do planejamento. Use --auto para pular perguntas interativas (Claude escolhe os padrões recomendados).
-argument-hint: "<phase> [--auto] [--batch] [--analyze] [--text]"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - AskUserQuestion
-  - Task
-  - mcp__context7__resolve-library-id
-  - mcp__context7__query-docs
----
-
-<objective>
-Extrair decisões de implementação que os agentes subsequentes precisam — o pesquisador e o planejador usarão o CONTEXT.md para saber o que investigar e quais escolhas estão travadas.
-
-**Como funciona:**
-1. Carregar contexto anterior (PROJECT.md, REQUIREMENTS.md, STATE.md, arquivos CONTEXT.md anteriores)
-2. Explorar base de código em busca de recursos e padrões reutilizáveis
-3. Analisar a fase — pular áreas cinzentas já decididas em fases anteriores
-4. Apresentar áreas cinzentas restantes — usuário seleciona quais discutir
-5. Aprofundar cada área selecionada até satisfação
-6. Criar CONTEXT.md com decisões que guiam pesquisa e planejamento
-
-**Saída:** `{phase_num}-CONTEXT.md` — decisões claras o suficiente para que agentes subsequentes possam agir sem perguntar ao usuário novamente
-</objective>
-
-<execution_context>
-@./.claude/framework/workflows/discuss-phase.md
-@./.claude/framework/workflows/discuss-phase-assumptions.md
-@./.claude/framework/templates/context.md
-</execution_context>
-
-<context>
-Número da fase: $ARGUMENTS (obrigatório)
-
-Arquivos de contexto são resolvidos no workflow usando `init phase-op` e chamadas de ferramentas de roadmap/estado.
-</context>
-
-<process>
-**Roteamento de modo:**
-```bash
-DISCUSS_MODE=$(node "./.claude/framework/bin/tools.cjs" config-get workflow.discuss_mode 2>/dev/null || echo "discuss")
-```
-
-Se `DISCUSS_MODE` for `"assumptions"`: Ler e executar @./.claude/framework/workflows/discuss-phase-assumptions.md do início ao fim.
-
-Se `DISCUSS_MODE` for `"discuss"` (ou não definido, ou qualquer outro valor): Ler e executar @./.claude/framework/workflows/discuss-phase.md do início ao fim.
-
-**OBRIGATÓRIO:** Os arquivos execution_context listados acima SÃO as instruções. Ler o arquivo de workflow ANTES de tomar qualquer ação. As seções de objective e success_criteria neste arquivo de comando são resumos — o arquivo de workflow contém o processo completo passo a passo com todos os comportamentos obrigatórios, verificações de configuração e padrões de interação. Não improvisar a partir do resumo.
-</process>
-
-<success_criteria>
-- Contexto anterior carregado e aplicado (sem re-perguntar questões já decididas)
-- Áreas cinzentas identificadas através de análise inteligente
-- Usuário escolheu quais áreas discutir
-- Cada área selecionada explorada até satisfação
-- Expansão de escopo redirecionada para ideias adiadas
-- CONTEXT.md captura decisões, não visão vaga
-- Usuário conhece os próximos passos
-</success_criteria>
-
-<observability_integration>
-**Integração com Observability-Driven Development (v1.9):**
-
-Quando o workflow.observability_phase_questions = true (default), o workflow inclui pergunta canônica de ODD na sessão de discussão:
-
-> "Quais SLIs essa fase impacta? O que precisa ser instrumentado para responder às 4 perguntas pré-PR?"
-
-A pergunta é resolvida consultando a skill [`observability-driven-development`](../skills/observability-driven-development/SKILL.md) e o resultado é registrado na seção `<observability>` do CONTEXT.md gerado:
-
-```markdown
-<observability>
-## SLIs impactados
-- [SLI ou "nenhum — fase puramente interna"]
-
-## Instrumentação necessária
-- Spans novos: [lista]
-- Atributos canônicos: [user.id, tenant_id, ...]
-- error.type enum esperado: [validation, timeout, ...]
-</observability>
-```
-
-O `plan-checker` invocado pelo `/planejar-fase` (Phase 33 — INT-FW-02) lê esta seção e bloqueia o plano se ODD ausente para fases voltadas ao usuário (skip silenciosamente para fases de infraestrutura — ver detecção em `discuss-phase.md`).
-
-**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>
+---
+name: discutir-fase
+description: Reúne contexto da fase por questionamento adaptativo antes do planejamento. Use --auto para pular perguntas interativas (Claude escolhe os padrões recomendados).
+argument-hint: "<phase> [--auto] [--batch] [--analyze] [--text]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+  - Task
+  - mcp__context7__resolve-library-id
+  - mcp__context7__query-docs
+---
+
+<objective>
+Extrair decisões de implementação que os agentes subsequentes precisam — o pesquisador e o planejador usarão o CONTEXT.md para saber o que investigar e quais escolhas estão travadas.
+
+**Como funciona:**
+1. Carregar contexto anterior (PROJECT.md, REQUIREMENTS.md, STATE.md, arquivos CONTEXT.md anteriores)
+2. Explorar base de código em busca de recursos e padrões reutilizáveis
+3. Analisar a fase — pular áreas cinzentas já decididas em fases anteriores
+4. Apresentar áreas cinzentas restantes — usuário seleciona quais discutir
+5. Aprofundar cada área selecionada até satisfação
+6. Criar CONTEXT.md com decisões que guiam pesquisa e planejamento
+
+**Saída:** `{phase_num}-CONTEXT.md` — decisões claras o suficiente para que agentes subsequentes possam agir sem perguntar ao usuário novamente
+</objective>
+
+<execution_context>
+@./.claude/framework/workflows/discuss-phase.md
+@./.claude/framework/workflows/discuss-phase-assumptions.md
+@./.claude/framework/templates/context.md
+</execution_context>
+
+<context>
+Número da fase: $ARGUMENTS (obrigatório)
+
+Arquivos de contexto são resolvidos no workflow usando `init phase-op` e chamadas de ferramentas de roadmap/estado.
+</context>
+
+<process>
+**Roteamento de modo:**
+```bash
+DISCUSS_MODE=$(node "./.claude/framework/bin/tools.cjs" config-get workflow.discuss_mode 2>/dev/null || echo "discuss")
+```
+
+Se `DISCUSS_MODE` for `"assumptions"`: Ler e executar @./.claude/framework/workflows/discuss-phase-assumptions.md do início ao fim.
+
+Se `DISCUSS_MODE` for `"discuss"` (ou não definido, ou qualquer outro valor): Ler e executar @./.claude/framework/workflows/discuss-phase.md do início ao fim.
+
+**OBRIGATÓRIO:** Os arquivos execution_context listados acima SÃO as instruções. Ler o arquivo de workflow ANTES de tomar qualquer ação. As seções de objective e success_criteria neste arquivo de comando são resumos — o arquivo de workflow contém o processo completo passo a passo com todos os comportamentos obrigatórios, verificações de configuração e padrões de interação. Não improvisar a partir do resumo.
+</process>
+
+<success_criteria>
+- Contexto anterior carregado e aplicado (sem re-perguntar questões já decididas)
+- Áreas cinzentas identificadas através de análise inteligente
+- Usuário escolheu quais áreas discutir
+- Cada área selecionada explorada até satisfação
+- Expansão de escopo redirecionada para ideias adiadas
+- CONTEXT.md captura decisões, não visão vaga
+- Usuário conhece os próximos passos
+</success_criteria>
+
+<observability_integration>
+**Integração com Observability-Driven Development (v1.9):**
+
+Quando o workflow.observability_phase_questions = true (default), o workflow inclui pergunta canônica de ODD na sessão de discussão:
+
+> "Quais SLIs essa fase impacta? O que precisa ser instrumentado para responder às 4 perguntas pré-PR?"
+
+A pergunta é resolvida consultando a skill [`observability-driven-development`](../skills/observability-driven-development/SKILL.md) e o resultado é registrado na seção `<observability>` do CONTEXT.md gerado:
+
+```markdown
+<observability>
+## SLIs impactados
+- [SLI ou "nenhum — fase puramente interna"]
+
+## Instrumentação necessária
+- Spans novos: [lista]
+- Atributos canônicos: [user.id, tenant_id, ...]
+- error.type enum esperado: [validation, timeout, ...]
+</observability>
+```
+
+O `plan-checker` invocado pelo `/planejar-fase` (Phase 33 — INT-FW-02) lê esta seção e bloqueia o plano se ODD ausente para fases voltadas ao usuário (skip silenciosamente para fases de infraestrutura — ver detecção em `discuss-phase.md`).
+
+**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>