@luanpdd/kit-mcp 1.7.0 → 1.9.0

package/kit/commands/depurar.md

@@ -20,8 +20,25 @@ Depurar problemas usando o método científico com isolamento de subagente.
 <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
 

package/kit/commands/discutir-fase.md

@@ -62,3 +62,29 @@ Se `DISCUSS_MODE` for `"discuss"` (ou não definido, ou qualquer outro valor): L
 - 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>

package/kit/commands/fazer.md

@@ -19,10 +19,25 @@ allowed-tools:
 | Tarefa **trivial** (rename, ajuste pontual) | **`/rapido`** | Sem necessidade de plano formal; commit atômico, sem subagentes |
 | Tarefa **rápida com garantias** (commit limpo, rastreamento de estado) | **`/expresso`** | Algo concreto mas pequeno; pula agentes opcionais mas mantém disciplina |
 | Trabalho **estruturado** (multi-arquivo, requer planejamento) | **`/discutir-fase` → `/planejar-fase` → `/executar-fase`** | Fase real de milestone; usa agentes completos |
+| **Tarefa Supabase** (DB/Auth/Realtime/Edge/Storage/RLS/migration) | **`/supabase <subcomando>`** | Roteia para agent especializado: arquiteto / migration / rls / edge / realtime / auth / storage / rag / cron / check |
 | **Próximo passo** ambíguo no fluxo atual | **`/proximo`** | Avança no roadmap automaticamente |
 | **Capturar ideia** sem agir agora | **`/nota`** ou **`/adicionar-tarefa`** | Salva pra depois sem interromper o foco |
 | **Investigar bug** com método científico | **`/depurar`** | Hipótese → teste → fix com checkpoints |
 
+## Detecção de intenção Supabase
+
+Se a descrição do user menciona qualquer destes termos, considere rotear para `/supabase` em vez de `/discutir-fase` ou `/expresso`:
+
+- **DB:** "migration", "RLS", "policy", "schema", "tabela Postgres", "supabase/migrations", "supabase/schemas"
+- **Auth:** "Supabase auth", "Next.js auth", "@supabase/ssr", "magic link", "OAuth", "MFA TOTP"
+- **Realtime:** "broadcast Supabase", "presence", "postgres_changes", "channel"
+- **Edge Functions:** "Edge Function", "Deno + Supabase", "supabase/functions"
+- **Storage:** "bucket", "signed URL", "upload Supabase"
+- **AI/RAG:** "pgvector", "embeddings + Supabase", "RAG with permissions"
+- **Background:** "pg_cron", "pgmq", "scheduled job Supabase"
+
+Para contexto sobre o que cada subcomando faz, leia [`/supabase`](./supabase.md) ou as 11 skills em `kit/skills/supabase-*/`.
+
 ## Aliases (continuam funcionando)
 
 `/rapido`, `/expresso`, `/proximo`, `/depurar`, `/discutir-fase`, `/planejar-fase`, `/executar-fase` — todos continuam executando direto, sem passar pelo `/fazer`. Use `/fazer` quando estiver em dúvida sobre qual escolher.

package/kit/commands/forense.md

@@ -53,4 +53,23 @@ Ler e executar o workflow forensics de @./.claude/framework/workflows/forensics.
 - **Redigir dados sensíveis:** Remover caminhos absolutos, chaves de API, tokens de relatórios e issues.
 - **Fundamentar descobertas em evidências:** Toda anomalia deve citar commits, arquivos ou dados de estado específicos.
 - **Sem especulação sem evidência:** Se os dados forem insuficientes, diga isso — não fabrique causas raiz.
-</critical_rules>
+</critical_rules>
+
+<observability_integration>
+**Integração com Core Analysis Loop (v1.9):**
+
+Forense usa skill [`core-analysis-loop`](../skills/core-analysis-loop/SKILL.md) — método científico iterativo (sintoma → hipótese de dados → validação → próxima iteração) em vez de inspeção ad hoc.
+
+Cada anomalia detectada vira hipótese com query de validação:
+
+| Tipo de anomalia | Hipótese formada | Query de validação |
+|---|---|---|
+| Loop travado | "phase X stuck há Yh" | `git log --since="Yh ago" --grep=phase` para confirmar zero commits |
+| Artefatos ausentes | "PLAN.md ausente em phase X" | `ls .planning/phases/X-*/X-PLAN-*.md` |
+| Trabalho abandonado | "branch sem merge nem commit recente" | `git log -1 <branch>` + `git status` |
+| Crash/interrupção | "executor falhou em meio a fase" | grep no STATE.md por "in_progress" sem update recente |
+
+**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>

package/kit/commands/instrumentar-fase.md

@@ -0,0 +1,200 @@
+---
+name: instrumentar-fase
+description: Após /planejar-fase, gera INSTRUMENTATION.md por plano (spans, atributos canônicos, eventos, validação ODD). Aplica skill observability-driven-development.
+argument-hint: "[fase] [plano]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Grep
+  - Glob
+  - Task
+---
+
+<objective>
+Após `/planejar-fase` produzir PLAN.md, este comando gera `INSTRUMENTATION.md` para cada plano da fase. Aplica a skill [observability-driven-development](../skills/observability-driven-development/SKILL.md) — bundle telemetria com a feature, valide as 4 perguntas pré-PR.
+
+**Cria/Atualiza:**
+- `.planning/phases/<N>/<padded>-PLAN-<NN>-INSTRUMENTATION.md` por plano
+
+**Após:** o user tem o contrato de instrumentação que o `executor` (e o `observability-instrumenter`) devem cumprir durante `/executar-fase`.
+</objective>
+
+<context>
+**Argumentos:** `$ARGUMENTS` — primeiro token é número da fase (ex.: `30`); segundo opcional é número do plano (ex.: `01`); se omitido, processa todos os planos da fase.
+
+**Pré-requisito:** `/planejar-fase <N>` já rodou. Existem `<padded>-PLAN-<NN>-*.md` em `.planning/phases/<N>/`.
+
+**Skill consultada:** [`observability-driven-development`](../skills/observability-driven-development/SKILL.md) — 4 perguntas pré-PR canônicas.
+</context>
+
+<process>
+
+## 1. Parsear argumentos
+
+```bash
+PHASE_NUM=$(echo "$ARGUMENTS" | awk '{print $1}')
+PLAN_NUM=$(echo "$ARGUMENTS" | awk '{print $2}')
+
+if [ -z "$PHASE_NUM" ]; then
+  echo "Uso: /instrumentar-fase <N> [<NN>]"
+  echo "Ex.: /instrumentar-fase 30        # todos os planos da Phase 30"
+  echo "Ex.: /instrumentar-fase 30 01     # só Plano 01 da Phase 30"
+  exit 1
+fi
+```
+
+## 2. Detectar phase_dir + planos
+
+```bash
+PHASE_STATE=$(node "./.claude/framework/bin/tools.cjs" init phase-op "$PHASE_NUM")
+PHASE_DIR=$(echo "$PHASE_STATE" | jq -r .phase_dir)
+
+if [ "$PHASE_DIR" = "null" ] || [ ! -d "$PHASE_DIR" ]; then
+  echo "Fase $PHASE_NUM ainda não foi planejada. Rode /planejar-fase $PHASE_NUM primeiro."
+  exit 1
+fi
+
+# PT-BR: descobrir PLAN.md(s) — exclui já-instrumentados
+if [ -n "$PLAN_NUM" ]; then
+  PLANS=("$PHASE_DIR"/*-PLAN-${PLAN_NUM}-*.md)
+else
+  PLANS=("$PHASE_DIR"/*-PLAN-*.md)
+fi
+```
+
+## 3. Para cada plano, gerar INSTRUMENTATION.md
+
+Para cada `PLAN_FILE`:
+
+```bash
+PADDED=$(basename "$PLAN_FILE" | grep -oE '^[0-9]+')
+NN=$(basename "$PLAN_FILE" | grep -oE 'PLAN-[0-9]+' | grep -oE '[0-9]+')
+OUT_FILE="$PHASE_DIR/${PADDED}-PLAN-${NN}-INSTRUMENTATION.md"
+
+# PT-BR: não sobrescrever se já existe
+if [ -f "$OUT_FILE" ]; then
+  echo "Já existe: $OUT_FILE — pulando"
+  continue
+fi
+```
+
+Ler `PLAN_FILE` para extrair:
+- Goal/objetivo
+- Tarefas (especialmente as que adicionam novos handlers/funções/endpoints)
+- Componentes/serviços tocados
+
+Gerar `INSTRUMENTATION.md` com seções canônicas (consultar [`observability-driven-development`](../skills/observability-driven-development/SKILL.md)):
+
+```markdown
+---
+phase: {N}
+plan: {NN}
+title: Instrumentation Plan for Plan {NN}
+status: pending
+---
+
+# Instrumentation Plan — Phase {N}, Plan {NN}: {plan_title}
+
+## Spans
+
+Spans a adicionar em arquivos modificados/criados pelo plano.
+
+| Name | Kind | Service | Atributos canônicos | Notas |
+|------|------|---------|---------------------|-------|
+| `{handler_name}` | SERVER | `{service}` | `user.id`, `tenant_id`, `request.id`, `endpoint`, `http.method`, `result.success`, `error.type`, `build_id` | inbound HTTP |
+
+## Eventos críticos
+
+Eventos com semantic significance que merecem `result.success` discreto.
+
+| Event | Quando emitir | result.success | error.type enum (catch) |
+|-------|---------------|----------------|--------------------------|
+| `{event_name}` | {momento} | true se {happy path} | `validation` \| `auth` \| `rate_limit` \| `timeout` \| `unknown` |
+
+## Métricas (opcional, se há valores numéricos críticos)
+
+| Name | Type | Unit | Labels |
+|------|------|------|--------|
+| `{metric_name}` | counter \| histogram | `ms` \| `bytes` \| `count` | `tenant_id`, `endpoint` |
+
+## Validação ODD — 4 perguntas pré-PR
+
+| # | Pergunta | Como verificar |
+|---|----------|----------------|
+| 1 | **Faz o que esperei?** | Span tem `result.success = true` no happy path. Smoke: enviar request, query `WHERE result_success = true` retorna |
+| 2 | **Compara à versão anterior?** | `build_id` setado em todo span. Query: `SELECT build_id, ..., AVG(duration_ms) GROUP BY build_id` |
+| 3 | **Usuários estão usando?** | `user.id` ou `tenant_id` ou `customer.tier` em todo span. Query: `SELECT customer.tier, COUNT(*) GROUP BY 1` |
+| 4 | **Anomalias emergem?** | Cada `catch` emite `error.type` enum (não message livre). Cada if/else significativo emite `branch_taken`. Query: `SELECT error.type, COUNT(*) GROUP BY 1` |
+
+## Sampling (head-based, default)
+
+```ts
+// PT-BR: errors sempre, success sample 10% — ajuste conforme volume
+const shouldSample = (event: SpanLike): boolean => {
+  if (event.attributes['result.success'] === false) return true   // 100% errors
+  if (event.attributes['customer.tier'] === 'enterprise') return true  // 100% enterprise
+  return Math.random() < 0.1   // 10% baseline
+}
+```
+
+## Referências cruzadas
+
+- Skill [`structured-events`](../../../../kit/skills/structured-events/SKILL.md) — campos canônicos
+- Skill [`distributed-tracing`](../../../../kit/skills/distributed-tracing/SKILL.md) — propagação cross-service
+- Skill [`opentelemetry-standard`](../../../../kit/skills/opentelemetry-standard/SKILL.md) — SDK setup
+- Skill [`observability-driven-development`](../../../../kit/skills/observability-driven-development/SKILL.md) — 4 perguntas
+- Agente [`observability-instrumenter`](../../../../kit/agents/observability-instrumenter.md) — gera os patches durante `/executar-fase`
+
+## Aceitação
+
+- [ ] Cada handler do plano tem span com 8 atributos canônicos mínimos
+- [ ] Cada `catch` emite `error.type` enum
+- [ ] Cada branch significativo emite `branch_taken`
+- [ ] Outbound calls propagam contexto via `propagation.inject`
+- [ ] Smoke: 100 requests sintéticos → spans queryables com filtragem por `tenant_id`/`user.id`
+```
+
+## 4. Plan-checker hook
+
+Se `plan-checker` está ativo no fluxo, este comando atualiza checkpoint do plan-checker:
+
+```bash
+# PT-BR: registrar que plano agora tem ODD-spec acoplada
+echo "instrumentation:$NN:ready" >> "$PHASE_DIR/.plan-checker-state"
+```
+
+## 5. Output
+
+```
+═══════════════════════════════════════════════════════════
+ framework ► INSTRUMENTAR-FASE ▸ Phase {N}
+═══════════════════════════════════════════════════════════
+
+Planos processados: {count}
+INSTRUMENTATION.md gerados:
+  - {padded}-PLAN-01-INSTRUMENTATION.md
+  - {padded}-PLAN-02-INSTRUMENTATION.md
+  ...
+
+Próximo passo:
+  - `/executar-fase {N}` — executor invocará observability-instrumenter automaticamente para aplicar os spans descritos
+  - `/auditar-uat` antes do PR — valida que as 4 perguntas ODD têm resposta executável
+```
+
+## 6. Commit
+
+```bash
+node "./.claude/framework/bin/tools.cjs" commit "docs(${PHASE_NUM}): instrumentation plans" --files "${PHASE_DIR}"/*-INSTRUMENTATION.md
+```
+
+</process>
+
+<success_criteria>
+- [ ] Para cada `PLAN-NN-*.md` da fase, existe `PLAN-NN-INSTRUMENTATION.md`
+- [ ] INSTRUMENTATION.md tem 4 seções: Spans, Eventos críticos, Métricas, Validação ODD
+- [ ] Validação ODD com 4 perguntas explicitamente respondidas
+- [ ] Cross-references para skills `structured-events`, `distributed-tracing`, `opentelemetry-standard`, `observability-driven-development`
+- [ ] Não sobrescreve INSTRUMENTATION.md já existente (idempotente)
+- [ ] Commit atômico após geração
+</success_criteria>

package/kit/commands/investigar-producao.md

@@ -0,0 +1,162 @@
+---
+name: investigar-producao
+description: Lança Core Analysis Loop guiado em incidente real — agente incident-investigator usa MCP Supabase, mantém estado em .planning/investigations/, retoma entre resets de contexto.
+argument-hint: "<sintoma em texto livre> [--id <investigation_id>]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Grep
+  - Glob
+  - Task
+  - AskUserQuestion
+---
+
+<objective>
+Lança o agente [`incident-investigator`](../agents/incident-investigator.md) para aplicar o [Core Analysis Loop](../skills/core-analysis-loop/SKILL.md) sobre um incidente. Estado iterativo de hipóteses fica em `.planning/investigations/<id>.md` — permite retomar entre resets de contexto (precedente: `/depurar`).
+
+**Cria/Atualiza:**
+- `.planning/investigations/<investigation_id>.md` — trilha de hipóteses validadas/refutadas
+
+**Após:** root cause documentado + action items + estado salvo para próxima sessão.
+</objective>
+
+<context>
+**Argumentos:** `$ARGUMENTS` — texto livre do sintoma + flags opcionais.
+
+**Flags:**
+- `--id <investigation_id>` — retoma investigação existente (pula criação de novo arquivo)
+- `--time-window <Nh|Nd>` — janela de busca (default: 1h)
+
+**Exemplos:**
+```
+/investigar-producao "checkout SLO burn rate = 8 às 14:32"
+/investigar-producao --id incident-2026-05-06-1432-checkout-burn  # retomar
+/investigar-producao "tenant acme reportou erros 5xx" --time-window 6h
+```
+
+**Pré-requisito (Full mode):** projeto Supabase configurado, `mcp__supabase__*` disponível.
+</context>
+
+<process>
+
+## 1. Parsear argumentos
+
+```bash
+INV_ID=$(echo "$ARGUMENTS" | grep -oE -- '--id [^ ]+' | awk '{print $2}')
+TIME_WINDOW=$(echo "$ARGUMENTS" | grep -oE -- '--time-window [^ ]+' | awk '{print $2}')
+SYMPTOM=$(echo "$ARGUMENTS" | sed -E 's/--(id|time-window) [^ ]+//g' | xargs)
+
+[ -z "$TIME_WINDOW" ] && TIME_WINDOW="1h"
+```
+
+## 2. Validar pré-requisitos
+
+```bash
+mkdir -p .planning/investigations
+
+# PT-BR: se --id fornecido, validar arquivo existe
+if [ -n "$INV_ID" ]; then
+  INV_FILE=".planning/investigations/${INV_ID}.md"
+  if [ ! -f "$INV_FILE" ]; then
+    echo "Investigation $INV_ID não existe. Liste com: ls .planning/investigations/"
+    exit 1
+  fi
+  echo "Retomando investigação: $INV_ID"
+fi
+
+# PT-BR: se SYMPTOM vazio + sem --id → erro
+if [ -z "$SYMPTOM" ] && [ -z "$INV_ID" ]; then
+  echo "Erro: forneça sintoma OU --id <investigation_id>"
+  echo "Exemplos:"
+  echo "  /investigar-producao \"checkout SLO burn rate = 8\""
+  echo "  /investigar-producao --id incident-2026-05-06-1432-foo"
+  exit 1
+fi
+```
+
+## 3. Detectar `supabase/config.toml`
+
+```bash
+PROJECT_ID=""
+if [ -f supabase/config.toml ]; then
+  PROJECT_ID=$(grep -E '^project_id\s*=' supabase/config.toml | sed 's/.*= *"\(.*\)".*/\1/' | head -1)
+fi
+```
+
+## 4. Listar investigações em aberto (UX)
+
+Antes de lançar agente, mostrar contexto de investigações ativas:
+
+```bash
+ls -t .planning/investigations/*.md 2>/dev/null | head -5 | while read f; do
+  ID=$(basename "$f" .md)
+  STARTED=$(grep '**Started:**' "$f" | head -1 | sed 's/.*Started:\*\* //')
+  STATUS=$(grep -E '^## (Root Cause|Status:)' "$f" | head -1)
+  printf "  %s — %s — %s\n" "$ID" "$STARTED" "$STATUS"
+done
+```
+
+## 5. Dispatch para `incident-investigator`
+
+```text
+Task(
+  subagent_type="incident-investigator",
+  prompt="
+${SYMPTOM:-(retomando $INV_ID)}
+
+${INV_ID:+investigation_id: $INV_ID}
+${PROJECT_ID:+project_id: $PROJECT_ID}
+time_window: ${TIME_WINDOW}
+
+Aplicar Core Analysis Loop até root cause OU lacuna intransponível.
+Salvar estado iterativo em .planning/investigations/{id}.md.
+Documentar todas as hipóteses (validated/refuted/inconclusive) com query + resultado citado.
+"
+)
+```
+
+## 6. Após retorno do agente
+
+Apresentar resumo curto + caminho do arquivo de estado:
+
+```
+═══════════════════════════════════════════════════════════
+ framework ► INVESTIGAR-PRODUCAO ▸ ${INV_ID}
+═══════════════════════════════════════════════════════════
+
+[output do agente — ver agente incident-investigator Step 7]
+
+## Estado salvo
+.planning/investigations/${INV_ID}.md
+
+## Próximos passos
+- Action items listados no Root Cause acima
+- Para abrir loop separado (ex.: "por que tenant acelerou?"):
+  /investigar-producao "<novo sintoma>"
+- Para retomar mais tarde:
+  /investigar-producao --id ${INV_ID}
+```
+
+## 7. Pause AskUserQuestion (opcional)
+
+Se agente reportou status `INCONCLUSIVE` ou `gaps_found`, perguntar via AskUserQuestion:
+
+- header: "Próximo?"
+- question: "Investigation incompleta. O que fazer?"
+- options:
+  - "Continuar com hipótese específica" — pede texto livre da hipótese
+  - "Pausar — retomar depois" — sai mantendo state
+  - "Fechar como inconclusiva" — marca arquivo como `## Status: INCONCLUSIVE` e sai
+
+</process>
+
+<success_criteria>
+- [ ] Sintoma + investigation_id (novo ou existente) parseados corretamente
+- [ ] Arquivo `.planning/investigations/<id>.md` criado/atualizado
+- [ ] `mcp__supabase__*` invocados em ≥ 1 hipótese (Full mode); ou modo offline declarado
+- [ ] Cada hipótese documentada com Query + Resultado citado
+- [ ] Root cause tem 4 dimensões (WHO/WHERE/WHEN/WHAT) OU status INCONCLUSIVE explícito
+- [ ] Action items concretos listados
+- [ ] Estado retomável: `/investigar-producao --id <id>` recarrega trilha
+</success_criteria>

package/kit/commands/observabilidade.md

@@ -0,0 +1,116 @@
+---
+name: observabilidade
+description: Orquestrador da Suíte Observabilidade — dispatch para agents (instrumenter, investigator, slo-engineer, burn-rate-forecaster, omm-auditor) com sinônimos PT/EN.
+argument-hint: "<subcomando> [args...]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Grep
+  - Glob
+  - Task
+  - AskUserQuestion
+---
+
+<objective>
+Orquestrador único da Suíte Observabilidade (v1.9). Recebe subcomando e args, faz dispatch via `Task(subagent_type=...)` para o agent especializado correto. **Único ponto de chain de agents observability** (precedente: `/supabase` em v1.8 — anti-pitfall A10 mantido).
+
+**Cria/Atualiza:** o que cada agent invocado cria.
+
+**Após:** o usuário tem o output do agent (patches, SLO.md, snapshot OMM, investigation trail, etc.).
+</objective>
+
+<execution_context>
+Skills consultadas pelos agents: `kit/skills/_shared-observability/glossary.md` (Phase 29) + `kit/skills/observability-*/SKILL.md` + `kit/skills/structured-events/SKILL.md` + `kit/skills/distributed-tracing/SKILL.md` + `kit/skills/opentelemetry-standard/SKILL.md` + `kit/skills/core-analysis-loop/SKILL.md` + `kit/skills/event-based-slos/SKILL.md` + `kit/skills/burn-rate-alerting/SKILL.md` + `kit/skills/telemetry-sampling/SKILL.md` + `kit/skills/telemetry-pipelines/SKILL.md`.
+
+Agents disponíveis: `kit/agents/observability-instrumenter.md` (Phase 30), `kit/agents/incident-investigator.md` (Phase 30), `kit/agents/slo-engineer.md` (Phase 32), `kit/agents/burn-rate-forecaster.md` (Phase 32), `kit/agents/omm-auditor.md` (Phase 34).
+</execution_context>
+
+<context>
+**Argumentos:** `$ARGUMENTS` — primeiro token é o subcomando; restante é passado para o agent como prompt.
+
+**Subcomandos suportados (sinônimos PT-BR/EN):**
+
+| Subcomando | Sinônimos | Agent dispatched |
+|---|---|---|
+| `instrumentar` | `instrument`, `inst` | `observability-instrumenter` |
+| `investigar` | `investigate`, `incident` | `incident-investigator` |
+| `slo` | `definir-slo`, `slo-engineer` | `slo-engineer` |
+| `burn-rate` | `burn`, `burn-rate-forecaster`, `forecast` | `burn-rate-forecaster` |
+| `omm` | `auditar`, `audit`, `maturity` | `omm-auditor` |
+| `help` | `ajuda`, `?` | exibe esta tabela inline |
+</context>
+
+<process>
+
+## 1. Parsear subcomando
+
+```bash
+SUBCMD=$(echo "$ARGUMENTS" | awk '{print $1}')
+ARGS=$(echo "$ARGUMENTS" | cut -d' ' -f2-)
+```
+
+**Se `$ARGUMENTS` for vazio ou `SUBCMD` for `help`/`ajuda`/`?`:** exibir tabela de subcomandos inline + exemplo. Sair.
+
+## 2. Resolver sinônimos
+
+```text
+instrumentar, instrument, inst                      → observability-instrumenter
+investigar, investigate, incident                   → incident-investigator
+slo, definir-slo, slo-engineer                      → slo-engineer
+burn-rate, burn, burn-rate-forecaster, forecast     → burn-rate-forecaster
+omm, auditar, audit, maturity                       → omm-auditor
+```
+
+**Se subcomando não resolve:** exibir erro inline com lista de subcomandos válidos. Sair.
+
+```
+✗ Subcomando desconhecido: '<SUBCMD>'
+
+Subcomandos válidos:
+  instrumentar / instrument        → instrumentar código com OTel + atributos canônicos
+  investigar / investigate         → Core Analysis Loop em incident
+  slo / definir-slo                → criar SLO.md + SQL materializar SLI
+  burn-rate / forecast             → calcular burn rate atual + ETA exhaustão
+  omm / auditar                    → OMM scored 5 capacidades
+
+Uso: /observabilidade <subcomando> <args...>
+Exemplo: /observabilidade investigar "checkout SLO burn rate = 8 às 14:32"
+```
+
+## 3. Detectar `supabase/config.toml` (para agents que usam MCP Supabase)
+
+```bash
+PROJECT_ID=""
+if [ -f supabase/config.toml ]; then
+  PROJECT_ID=$(grep -E '^project_id\s*=' supabase/config.toml | sed 's/.*= *"\(.*\)".*/\1/' | head -1)
+fi
+```
+
+## 4. Dispatch
+
+Invocar `Task(subagent_type=<agent_name>, prompt=<built_prompt>)`.
+
+**Prompt construído:**
+
+```
+{ARGS}
+
+{Se project_id detectado:}
+project_id: {PROJECT_ID}
+```
+
+## 5. Output
+
+Output do agent é o output do command. Sem post-processing — agent já formata estruturado.
+
+</process>
+
+<success_criteria>
+- [ ] Subcomando resolvido para agent canônico (5 subcomandos × seus sinônimos)
+- [ ] `project_id` extraído de `supabase/config.toml` se presente
+- [ ] Dispatch via `Task(subagent_type=...)` — único ponto de chain
+- [ ] Subcomando inválido → mensagem clara com lista
+- [ ] Subcomando `help`/`ajuda`/`?` → exibe tabela inline
+- [ ] Args após subcomando passam transparentemente para o agent
+</success_criteria>

package/kit/commands/planejar-fase.md

@@ -45,3 +45,23 @@ Normalizar entrada da fase no passo 2 antes de qualquer pesquisa de diretório.
 Execute o workflow plan-phase de @./.claude/framework/workflows/plan-phase.md do início ao fim.
 Preserve todos os checkpoints do workflow (validação, pesquisa, planejamento, loop de verificação, roteamento).
 </process>
+
+<observability_integration>
+**Integração com ODD plan-checker gate (v1.9):**
+
+Quando `workflow.observability_plan_gate = true` (default para fases voltadas ao usuário), o `plan-checker` invocado neste workflow inclui uma checagem extra:
+
+1. Lê `<observability>` section do CONTEXT.md (criado por `/discutir-fase` ou `/instrumentar-fase`)
+2. Verifica que as 4 perguntas pré-PR estão respondidas (consulta skill [`observability-driven-development`](../skills/observability-driven-development/SKILL.md)):
+   - Faz o que esperei? → INSTRUMENTATION.md tem `result.success` documentado?
+   - Compara à versão anterior? → `build_id` em todo span planejado?
+   - Usuários estão usando? → identidade (`user.id`/`tenant_id`/`customer.tier`) presente?
+   - Anomalias emergem? → `error.type` enum + `branch_taken` planejados?
+3. Se alguma pergunta ausente: VERIFICATION.md status = `gaps_found`, sugerindo invocar `/instrumentar-fase` para gerar INSTRUMENTATION.md.
+
+**Fases de infraestrutura pura** (skip discuss already detectou): pula gate silenciosamente.
+
+**Quando há observability gate enabled e gap encontrado:** o user pode (a) `/instrumentar-fase` antes de prosseguir; ou (b) editar manualmente CONTEXT.md `<observability>` section; ou (c) override via `--skip-observability-gate`.
+
+**REQ:** INT-FW-02.
+</observability_integration>