auditar-refactor

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.

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

1. Parsear argumentos

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")"