@luanpdd/kit-mcp 1.9.0 → 1.11.0

package/kit/commands/concluir-marco.md

@@ -151,4 +151,98 @@ Gate executável: `gates/omm-no-regression.md`.
 Skill consultada: [`observability-maturity-model`](../skills/observability-maturity-model/SKILL.md).
 
 **REQ:** INT-FW-05.
-</observability_integration>
+</observability_integration>
+
+<sre_integration>
+**PRR gate opcional para features production-bound (v1.10 — INT-FW-V2-02):**
+
+Quando `workflow.complete_milestone_prr_gate = true` (default `false` — opt-in até maturidade SRE Engagement do projeto), o workflow inclui passo PRR coverage check **antes de arquivar** o milestone:
+
+1. Listar features production-bound do milestone (heurística: features com Edge Functions deployed, features com SLO definido em `.planning/slos/`, features marcadas explicitamente `production: true` em ROADMAP.md ou em `.planning/phases/<N>-CONTEXT.md`)
+2. Para cada feature production-bound, procurar `.planning/prr/<feature-id>-PRR-REPORT.md` (cross-ref [prr-conductor](../agents/prr-conductor.md) — agent que produz o relatório scored em 6 axes do cap 32)
+3. Verificar status do PRR-REPORT.md:
+   - Se ausente: BLOQUEAR conclusion — sugerir `/prr --feature "<descrição>"` ou `/sre prr --feature "..."` antes de re-rodar `/concluir-marco`
+   - Se presente mas status `failed` (≥ 1 axe P0 reprovado): BLOQUEAR conclusion — listar axes P0 reprovados e exigir remediation
+   - Se presente com status `passed`: incluir `PRR-REPORT.md` como anexo no `.planning/milestones/v<version>-MILESTONE.md` (audit trail)
+4. Quando todos os PRRs de features production-bound forem `passed`: prosseguir para passo 7 (commit + tag) do workflow `complete-milestone.md`
+
+**Distinção `passed` vs `failed`:**
+
+| Status | Definição | Resultado em /concluir-marco |
+|---|---|---|
+| `passed` | Todos os 6 axes scored ≥ 3/5 (cap 32 — System Architecture / Instrumentation / Emergency Response / Capacity Planning / Change Management / Performance) | Milestone arquivável (gate aprova) |
+| `passed-with-warnings` | 6/6 axes ≥ 3/5 mas ≥ 1 axe com action items P1 não resolvidos | Milestone arquivável; warnings explícitos no archive |
+| `failed` | ≥ 1 axe < 3/5 OU ≥ 1 action item P0 não resolvido | Gate BLOQUEIA — exige remediation antes de arquivar |
+
+**Default `false` por design:**
+
+`workflow.complete_milestone_prr_gate` default `false` (≠ `complete_milestone_omm_gate` que é `true`) — PRR Engagement Model do livro Google SRE assume **maturidade organizacional** (SRE team, on-call rotation, incident response). Para projetos em early stage / dogfooding, gate `false` é o correto. Quando o projeto atinge tier-1 (production-user-facing, paid tier, SLA contratual), user explicitamente liga setando `workflow.complete_milestone_prr_gate=true` no config.
+
+**Quando ligar gate:**
+
+- Projeto tem feature user-facing pagante (≥ 1 jornada crítica monetizada)
+- Projeto tem SLO definido em `.planning/slos/` com error budget tracking
+- Projeto tem on-call rotation documentada em runbook
+- Projeto tem postmortem culture estabelecida (≥ 1 postmortem blameless escrito em `.planning/postmortems/`)
+- **Pelo menos 2 dos 4 acima** = liga gate (sinal de production maturity)
+
+**Quando manter gate desligado:**
+
+- Projeto early stage / dogfooding interno (sem usuário pagante)
+- Solo developer side project sem on-call
+- Pesquisa / POC / experimento (não production-bound por design)
+- Equipe ainda construindo SRE muscle (PRR vira teatro se não há cultura de remediation)
+
+**Skill consultada:** [production-readiness-review](../skills/production-readiness-review/SKILL.md) (cap 32 livro Google SRE — *Evolving SRE Engagement Model* — define os 6 axes + 3 engagement models: Simple, Early Engagement, Frameworks/SRE Platform).
+
+**Gate executável:** `gates/prr-checklist-coverage.md` (criado em Phase 41 — QA-SRE-03). Workflow `.claude/framework/workflows/complete-milestone.md` consulta esse gate quando flag `true`.
+
+**Anti-patterns prevenidos:**
+
+- "Marcar feature como production-bound mas pular PRR" → gate exige PRR-REPORT.md presente
+- "PRR-REPORT.md gerado mas status `failed`" → gate exige `passed` (não basta existir)
+- "Auto-PRR pelo time dev" → cross-ref [prr-conductor](../agents/prr-conductor.md) reforça que `prr-conductor` agent é par externo (não o mesmo agent que escreveu a feature)
+- "Gate ligado em projeto early stage" → bloco "Quando ligar gate" exige ≥ 2 sinais de production maturity
+
+**REQ:** INT-FW-V2-02.
+</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>

package/kit/commands/forense.md

@@ -72,4 +72,106 @@ Cada anomalia detectada vira hipótese com query de validação:
 **Skill consultada explicitamente:** abrir o arquivo `kit/skills/core-analysis-loop/SKILL.md` para padrão "documentação da trilha (formato canônico)" — o relatório forense em `.planning/forensics/report-<ts>.md` segue esse formato com cada hipótese tendo "Query / Resultado / Status (VALIDATED / REFUTED / INCONCLUSIVE)".
 
 **REQ:** INT-FW-06.
-</observability_integration>
+</observability_integration>
+
+<sre_integration>
+**Chain `/postmortem` após Core Analysis Loop (v1.10 — INT-FW-V2-01):**
+
+Forense é diagnóstico evidence-based read-only — identifica o **o que** e o **como** via método científico (sintoma → hipótese → query → status `VALIDATED | REFUTED | INCONCLUSIVE`). Quando o Core Analysis Loop fecha com pelo menos uma hipótese `VALIDATED` apontando para root cause, o próximo passo canônico é **postmortem blameless** (cap 15 livro Google SRE — *Postmortem Culture: Learning from Failure*).
+
+Distinção fundamental:
+
+| Etapa | Pergunta respondida | Output | Audiência |
+|---|---|---|---|
+| Forense | "O que aconteceu? Onde está a evidência?" | `.planning/forensics/report-<ts>.md` | Investigador (você) |
+| Postmortem | "O que aprendemos? O que mudaremos?" | `.planning/postmortems/<id>.md` | Organização inteira (no postmortem left unreviewed) |
+
+Forense **diagnostica**; postmortem **transforma diagnóstico em aprendizado durável**. Pular postmortem = perder aprendizado organizacional (anti-pattern hero culture: "fixei o bug, vamos seguir").
+
+**Trigger automático sugerido (não-bloqueante):**
+
+Quando o relatório forense conclui com:
+- ≥ 1 hipótese `VALIDATED` apontando root cause acionável, OU
+- Incident impactou usuário (não apenas dev experience), OU
+- Workflow framework crashou em produção (não dogfooding)
+
+O comando `/forense` **sugere ao usuário** ao final do relatório:
+
+```text
+Próximo passo recomendado:
+  /postmortem --incident "<one-liner derivado do relatório forense>"
+Continua o blameless write-up com Summary + Impact + Root Causes + Action Items.
+Cross-ref canônico: [blameless-postmortems](../skills/blameless-postmortems/SKILL.md) skill + [postmortem-writer](../agents/postmortem-writer.md) agent.
+
+Nota: para incidents de produção SRE com investigação completa via /investigar-producao
+(que produz .planning/investigations/<id>.md), use `/postmortem --from-investigation <id>`.
+```
+
+**Chain de fluxo canônico:**
+
+```text
+Falha detectada
+  ↓
+/forense "<descrição>"   ← diagnóstico evidence-based (este comando, output: .planning/forensics/report-<ts>.md)
+  ↓ (Core Analysis Loop fecha com VALIDATED)
+/postmortem --incident "<one-liner>"   ← blameless write-up (chain sugerido — modo standalone)
+  ↓
+Action Items P0/P1 viram tarefas em milestone atual ou próximo
+  ↓
+Wheel of Misfortune: postmortem vira treino de novos engineers (cap 15)
+```
+
+**Distinção `/forense` vs `/investigar-producao`:**
+
+- `/forense` — diagnóstico de workflows framework com falha (post-mortem de processo). Output: `.planning/forensics/report-<ts>.md`. Chain: `--incident "<one-liner>"`.
+- `/investigar-producao` (v1.9) — Core Analysis Loop em incident produção SRE com MCP Supabase. Output: `.planning/investigations/<id>.md`. Chain: `--from-investigation <id>`.
+
+**Quando NÃO sugerir chain `/postmortem`:**
+
+- Forense `INCONCLUSIVE` em todas as hipóteses (root cause não identificada — sugerir nova investigação ao invés)
+- Falha trivial documentada (typo em `.gitignore`) sem impacto a usuário
+- Investigação cancelada pelo user antes do Core Analysis Loop fechar
+
+**Cultura blameless é não-negociável:** o postmortem foca em **sistema** (controles ausentes, signals não monitorados, escalation paths frágeis), nunca em **pessoas** ("dev X esqueceu de testar"). Anti-pattern blame culture é explicitamente prevenido pelo template de `postmortem-writer` (cap 15 — *No postmortem left unreviewed*).
+
+**REQ:** INT-FW-V2-01.
+</sre_integration>
+
+<legacy_refactor_integration>
+**Forensics em failure de refactor (Suíte Legacy):**
+
+Se o forense identifica root cause como "regressão silenciosa pós-refactor", consulta automaticamente artefatos da Suíte Legacy:
+
+```text
+Falha pós-refactor detectada
+  ↓
+/forense "<descrição>"   ← diagnóstico
+  ↓ se root cause = refactor regression
+forensics agent lê:
+  - .planning/REFACTOR-SAFETY.md (qual veredito do gate? GO? GO-OVERRIDE?)
+  - tests/characterization/<file_stem>/ (existia? rodou verde antes do refactor?)
+  - REFACTOR-SAFETY-<file_stem>.md (audit retroativo)
+  ↓
+/postmortem --incident "<one-liner>" --legacy-refactor   ← consulta extra
+```
+
+**Lessons learned canônicas para regression em refactor (cap 23 Feathers):**
+
+| Cause root | Lesson learned canônica |
+|---|---|
+| Refactor sem characterization tests | Aplicar gate `legacy-refactor-safety` em modo blocking; sem char = "edit and pray" |
+| Char tests existiam mas line cov apenas (não behavioral) | Habilitar mutation testing no gate; line cov 80% pode mascarar 30% mutation kill |
+| Override usado sem ticket válido | Validar tickets em `/auditar-marco` opt-in; tickets > 90 dias = bloquear novos overrides |
+| Snapshots não-revisados, congelaram bugs | `/caracterizar` deve emitir warning de revisão obrigatória; PR review verifica leitura |
+| Mudança comportamental misturada com refactor | Single-goal editing (cap 22 Feathers); separar PRs |
+
+Action items P0 sugeridos em postmortem de regression refactor:
+1. Habilitar `workflow.legacy_refactor_gate_blocking = true`
+2. Adicionar mutation testing à CI para arquivos legacy
+3. Auditar overrides ainda abertos via `/auditar-marco`
+4. Treinar equipe via Wheel of Misfortune com este caso
+
+**Skill canônica:** [`pre-refactor-characterization`](../skills/pre-refactor-characterization/SKILL.md), [`legacy-characterization-tests`](../skills/legacy-characterization-tests/SKILL.md)
+
+**REQ:** INT-LEGACY-FW-02.
+</legacy_refactor_integration>