@luanpdd/kit-mcp 1.7.0 → 1.9.0

package/CHANGELOG.md

@@ -6,6 +6,107 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) · Versioning:
 
 ## [Unreleased]
 
+## [1.8.1] - 2026-05-06
+
+Patch de integração da Suíte Supabase v1.8.0 — fecha 7 lacunas onde o conteúdo novo não estava "wired" nos pontos de entrada existentes do framework.
+
+### Mudado — integração entre Suíte Supabase e fluxo padrão
+
+- **`/fazer`** (`kit/commands/fazer.md`) — adicionada linha "Tarefa Supabase → `/supabase`" na decision tree + parágrafo "Detecção de intenção Supabase" listando 7 categorias de termos (DB / Auth / Realtime / Edge / Storage / RAG / Background) que devem rotear para `/supabase` em vez de `/discutir-fase` ou `/expresso`.
+- **`planner` agent** (`kit/agents/planner.md`) — nova seção `<specialized_agents>` instrui o planner a delegar para `supabase-*` agents (architect, migration-writer, rls-writer, edge-fn-writer, realtime-implementer, auth-bootstrapper, storage-implementer) em fases Supabase em vez de gerar tasks genéricas para o `executor` resolver inline.
+- **`executor` agent** (`kit/agents/executor.md`) — nova tabela "Delegação para agents especializados" lista 8 patterns de task (migrations, schemas declarative, RLS, Edge Functions, Realtime, Auth bootstrap, Storage, schema-checker) com `Task(subagent_type=...)` correto. Princípio: agent especializado é mais barato + mais correto que o executor genérico em domínios cobertos.
+- **`/depurar`** (`kit/commands/depurar.md`) — `<available_agent_types>` agora inclui `schema-checker`. Nova seção `<supabase_pre_check>` faz triagem de bugs SQL/Supabase e pré-valida via `schema-checker` antes do `debugger` genérico (5 sintomas mapeados: migration falhou, RLS quebrou query, Edge Function quebrou, user_metadata em policy, service_role exposto).
+- **`discuss-phase` workflow** (`kit/framework/workflows/discuss-phase.md`) — nova seção `<supabase_detection>` antes da identificação de áreas cinzentas. Se a fase é Supabase, delega o questionamento para `supabase-architect` (que já tem template de perguntas Supabase-específicas) em vez de gerar gray areas genéricas.
+- **`plan-phase` workflow** (`kit/framework/workflows/plan-phase.md`) — `<available_agent_types>` agora inclui agents Supabase. Nova seção `<supabase_phase_detection>` no Step 1 — se fase é Supabase, usa `supabase-architect` em vez de `phase-researcher` genérico, e instrui o `planner` a marcar tasks com `subagent_type` apontando para o agent especializado correto (tabela com 7 patterns).
+- **CI** (`.github/workflows/ci.yml`) — novo step "Audit — v1.8 Supabase suite gates" que executa os 4 gates blocking (`budget-description`, `no-personal-uuid`, `agent-no-recursive-dispatch`, `skill-must-include`) extraindo o bash check de cada `gates/<name>.md` e rodando. Falha o CI se algum violar. Gate non-blocking `sync-idempotent` defer (exige CLI completo).
+
+### Adicionado — agentes existentes ganham awareness Supabase
+
+Sem novos arquivos. As 6 edições em arquivos de agent/workflow/command existentes integram o conteúdo da v1.8.0 nos pontos de entrada que LLMs usam, fechando o gap "conteúdo entregue mas não chamado".
+
+### Sem mudanças de API runtime
+
+Patch v1.8.1 continua content-only. Zero alterações em `src/core/`, `registry.js`, `sync.js`. Stable API v1.0+ preservada.
+
+### Tests
+
+Todos os 4 gates blocking continuam passing após o patch. CI agora os roda explicitamente — Phase 28 deixou os specs prontos mas sem step de execução.
+
+## [1.8.0] - 2026-05-06
+
+Milestone v1.8 — Suíte Supabase: primeira coleção especializada de skills+agents+command focada em um stack concreto. 31 REQs em 4 fases (Phases 25-28).
+
+### Adicionado — 11 skills Supabase canônicas (Phase 25)
+
+Cada skill é auto-contida (sem `references/` folder), com frontmatter `description ≤ 200 chars`, template fixo de 5 seções (Quando usar / Regras absolutas / Patterns canônicos / Anti-patterns / Ver também), code blocks EN com comentários PT-BR pedagógicos, e cross-refs via Markdown link relativo.
+
+- `supabase-realtime` — broadcast vs postgres_changes, `private: true` obrigatório, naming `scope:entity:id`, `realtime.broadcast_changes` triggers, `removeChannel` cleanup
+- `supabase-auth-ssr` — Next.js v16 + `@supabase/ssr` (NUNCA `auth-helpers-nextjs`), padrão `getAll`/`setAll` exclusivo, middleware com `getUser()` + redirects, single serverClient factory
+- `supabase-edge-functions` — Deno runtime, imports `npm:`/`jsr:` versionados, env vars pre-populadas, `Deno.serve`, `EdgeRuntime.waitUntil`, file writes apenas em `/tmp`, basePath `/<function-name>`
+- `supabase-declarative-schema` — workflow `supabase/schemas/` → `supabase stop` → `db diff -f` → revisar → apply, com caveats sobre views, RLS, partitions
+- `supabase-rls-policies` — REGRA #1 absoluta `(select auth.uid())` wrapper, WARNING `user_metadata` em autorização (privilege escalation), policies granulares por operação, `to authenticated`/`to anon` explícito, indexes obrigatórios, MFA via `aal2`
+- `supabase-database-functions` — `SECURITY INVOKER` por default, `set search_path = ''` SEMPRE (lint advisor 0011), schema-qualified names, `IMMUTABLE`/`STABLE` quando aplicável
+- `supabase-migrations` — naming `YYYYMMDDHHmmss_<name>.sql` UTC, header de metadados, RLS obrigatório em toda nova tabela, granular policies, comentários extensivos em comandos destrutivos
+- `supabase-postgres-style` — lowercase reserved, `snake_case`, plurais para tabelas/singular para colunas, `ISO 8601`, CTEs lineares para queries complexas
+- `supabase-storage` — buckets públicos vs privados, `signed URL` com expiration, RLS sobre `storage.objects` com multi-tenant path isolation, image transforms (Pro+), TUS para uploads > 6 MB, awareness de egress billing
+- `supabase-pgvector-rag` — `create extension vector`, dim consistente por modelo, `HNSW` (default 2026) vs `IVFFlat`, operadores `<=>`/`<#>`/`<->`, RAG with permissions via RLS, chunking 200-500 tokens
+- `supabase-cron-queues` — `pg_cron` + `pgmq` (Postgres 15.6.1.143+) + `pg_net` v0.10.0+, pattern canônico `cron → pgmq → Edge Function`, idempotência obrigatória em consumers
+
+Plus glossário compartilhado em `kit/skills/_shared-supabase/glossary.md` — termos PT-BR↔EN, comandos CLI canônicos, patterns canônicos consolidados (não-skill, arquivo de referência).
+
+### Adicionado — 7 agents Supabase + convenção universal (Phase 26)
+
+Cada agent inclui tabela `## Compatibilidade` por IDE (Full / Partial / Offline-only), preflight detection MCP no Step 0 (declara MODO OFFLINE explícito se MCP indisponível — NUNCA finge sucesso), output em layout canônico do CLI Supabase (`supabase/migrations/`, `supabase/schemas/`, `supabase/functions/<name>/`), e frontmatter `tools:` com nomes canônicos `mcp__supabase__*` (zero UUIDs).
+
+- `supabase-architect` (blue) — projeta schema + RLS + topologia realtime ANTES da implementação. Pergunta tier (Free/Pro/Team/Enterprise) upfront via `AskUserQuestion`. Alerta sobre Free pause + branch billing. NÃO escreve código.
+- `supabase-migration-writer` (yellow) — escreve migrations seguindo declarative schema + RLS obrigatório + style guide. Detecta layout `schemas/` vs `migrations/` no boot. Aplica via `mcp__supabase__apply_migration` se MCP disponível; modo offline gera SQL.
+- `supabase-rls-writer` (red) — gera 4 policies granulares por operação com `(select auth.uid())` wrapper + indexes recomendados. **ABORTA explicitamente** se input menciona `user_metadata` em policy de autorização.
+- `supabase-edge-fn-writer` (cyan) — escreve Edge Functions Deno com `npm:`/`jsr:` versionados, `Deno.serve`, env vars pre-populadas, file writes em `/tmp`, basePath em multi-rota. Alerta cold start em bundles grandes.
+- `supabase-realtime-implementer` (magenta) — configura 3 layers (RLS sobre `realtime.messages` + trigger DB via `realtime.broadcast_changes` + client subscribe com cleanup obrigatório). Migra `postgres_changes` para `broadcast`.
+- `supabase-auth-bootstrapper` (green) — bootstrap Next.js v16 com `@supabase/ssr` (browser client + server client + middleware completo). **Audita `.env*` files** e ABORTA se detectar `NEXT_PUBLIC_*SERVICE*` (service_role leak).
+- `supabase-storage-implementer` (orange) — configura bucket + RLS sobre `storage.objects` com multi-tenant path (`<auth.uid()>/<file>`) + client code (upload + signedURL). Suporta TUS para uploads grandes.
+
+### Adicionado — Command `/supabase` orquestrador único (Phase 27)
+
+`kit/commands/supabase.md` aceita 10 subcomandos com sinônimos PT-BR/EN: `arquiteto|architect`, `migration|migrar`, `rls`, `edge|edge-function|funcao`, `realtime|tempo-real`, `auth|autenticacao`, `storage|armazenamento`, `rag|pgvector|embeddings`, `cron|queues|pgmq|background`, `check|validar` (invoca `schema-checker` existente), `help|ajuda|?`.
+
+Detecta `supabase/config.toml` para extrair `project_id`. Dispatch via `Task(subagent_type=supabase-...)`. **É o único ponto de chain de agents Supabase** — agents permanecem função pura (anti-pitfall A10).
+
+### Adicionado — 5 audit gates novos (Phase 28)
+
+Markdown specs em `gates/` com `## Check` em bash:
+
+- `gates/budget-description.md` — valida `description ≤ 200 chars` em todo agent/command/skill (anti-pitfall A2 — CLAUDE.md inflation)
+- `gates/no-personal-uuid.md` — detecta UUIDs `[0-9a-f]{8}-...` em frontmatter ou body de `kit/{agents,commands,skills}/` (anti-pitfall A12)
+- `gates/agent-no-recursive-dispatch.md` — valida zero `Task(...subagent_type=...supabase-...)` em `kit/agents/supabase-*.md` (anti-pitfall A10)
+- `gates/skill-must-include.md` — valida strings obrigatórias por skill verbatim — `(select auth.uid())`, `set search_path = ''`, `getAll`/`setAll`, `private: true`, `Deno.serve`, etc. (anti-pitfall A7)
+- `gates/sync-idempotent.md` — valida que `kit sync claude-code` rodado 2× produz `.claude/` byte-idêntico (anti-pitfall A1, non-blocking warn)
+
+### Mudado — schema-checker.md UUID migration
+
+`kit/agents/schema-checker.md` migrado de `mcp__0a712001-6cbb-44ef-a5f4-a24ea40894fa__execute_sql` (UUID do projeto pessoal do mantenedor) para `mcp__supabase__execute_sql`/`__list_tables`/`__apply_migration` (canônico). **Breaking interno:** instaladores de versões anteriores tinham um UUID que não funcionava para eles; com v1.8 funciona com qualquer Supabase MCP server configurado. Mesma funcionalidade — apenas referência canônica.
+
+### Sem mudanças de API runtime
+
+v1.8 é **content-only por design** — zero alterações em `src/core/`, `registry.js`, `sync.js`. Stable API v1.0+ totalmente preservada. CI passa sem mudança em `.github/workflows/`. Deps budget mantido em 6/6 (zero deps novas — todo o conteúdo é markdown).
+
+### Tests
+
+Tests existentes (115 unit + 67 integration de v1.7) continuam verde. Novos gates não têm tests dedicados (são bash em markdown, executados via `runGate` no framework de gates já testado em `test/unit/gates.test.js`).
+
+### Decisões arquiteturais
+
+Validadas em `.planning/research/`:
+- **Naming flat** `kit/skills/supabase-*/SKILL.md` (não subárvore — quebraria `readSkillsDir`)
+- **MCP-first com fallback offline gracioso** — 5 dos 8 IDE targets não têm Supabase MCP; agents funcionam offline gerando SQL/código
+- **Cross-references via Markdown link relativo** (não `@-include` — quebraria lazy-load das skills)
+- **Outputs em layouts canônicos do CLI Supabase** — `supabase/migrations/`, `supabase/schemas/`, `supabase/functions/<name>/`
+- **Glossário compartilhado** em `_shared-supabase/` — não é skill (sem trigger), apenas referência cross-skill
+
+### Detalhes
+
+`.planning/milestones/v1.8.0/` (após `/concluir-marco`).
+
 ## [1.7.0] - 2026-05-06
 
 Milestone v1.7 — perf+lean part 2 + UX naming canonical: 10 REQs em 3 fases.

package/README.md

@@ -59,10 +59,48 @@ kit-mcp/
 
 ### About the bundled workflow
 
-The bundled `kit/` is an opinionated **brownfield planning workflow** in Portuguese — milestones, phases, requirements, planning, execution with atomic commits and checkpoints, retrospective auditing. Installing `@luanpdd/kit-mcp` and syncing into your IDE gives you all 60 slash-commands, 19 agents, plus the framework templates that they delegate into.
+The bundled `kit/` is an opinionated **brownfield planning workflow** in Portuguese — milestones, phases, requirements, planning, execution with atomic commits and checkpoints, retrospective auditing. Installing `@luanpdd/kit-mcp` and syncing into your IDE gives you all 60+ slash-commands, 24+ agents, plus the framework templates that they delegate into.
 
 If that's not what you want, point `--kit-root` at your own folder and ignore everything under `kit/` — the infrastructure (registry, sync, gates, forensics, MCP server) works the same regardless of what kit you load.
 
+### Observability suite (v1.9)
+
+A complete observability layer derived from *Observability Engineering* (Charity Majors, Liz Fong-Jones, George Miranda — O'Reilly, 2022) ships in the kit. It integrates deeply with the Supabase suite (v1.8) — every Supabase agent now consults observability skills, and the new `incident-investigator` agent uses `mcp__supabase__get_logs` / `execute_sql` / `get_advisors` to apply the **Core Analysis Loop** on real incidents.
+
+**11 skills** in `kit/skills/`:
+- `_shared-observability/glossary.md` — canonical bilingual vocabulary (PT-BR↔EN)
+- `structured-events`, `distributed-tracing`, `opentelemetry-standard`, `core-analysis-loop` — foundationals
+- `observability-driven-development` — the 4 pre-PR questions ("Does it do what I expected? Compare to previous version? Are users using? Anomalies emerge?")
+- `event-based-slos`, `burn-rate-alerting` — SLO definition + predictive burn alerts
+- `telemetry-sampling`, `telemetry-pipelines`, `observability-maturity-model` — scale + culture
+
+**5 agents** in `kit/agents/`:
+- `observability-instrumenter` — generates OTel + canonical attribute patches
+- `incident-investigator` — Core Analysis Loop with persistent state in `.planning/investigations/`
+- `slo-engineer` — generates `SLO.md` + SQL migrations to materialize SLI events
+- `burn-rate-forecaster` — calculates burn rate, ETA exhaustion, alert config
+- `omm-auditor` — scores 5 OMM capabilities (resilience, code quality, complexity, release cadence, user behavior)
+
+**6 commands**:
+- `/observabilidade <subcommand>` — single orchestrator (analog to `/supabase`) — dispatches to the 5 agents above with PT/EN synonyms
+- `/instrumentar-fase` — generates `INSTRUMENTATION.md` per plan after `/planejar-fase`
+- `/investigar-producao` — guided Core Analysis Loop with persistent state
+- `/definir-slo` — creates SLO definition + SQL materialized view
+- `/burn-rate-status` — table `[SLO | budget burned | ETA | action]`, also runnable in `/loop`
+- `/auditar-observabilidade` — generates OMM-REPORT.md scored
+
+**Quick start example:**
+```bash
+# Define an SLO for a critical journey
+/observabilidade slo "checkout"
+
+# Investigate a production incident with Core Analysis Loop
+/observabilidade investigar "checkout SLO burn rate = 8 às 14:32"
+
+# Score project against Observability Maturity Model
+/observabilidade omm
+```
+
 ---
 
 ## Prerequisites

package/gates/agent-no-recursive-dispatch.md

@@ -0,0 +1,48 @@
+---
+id: agent-no-recursive-dispatch
+stage: pre-verify
+blocking: true
+description: Valida que agents Supabase NÃO contêm Task(subagent_type=supabase-...). Orquestração só via /supabase command (anti-pitfall A10 — recursive dispatch).
+---
+
+# Agent no recursive dispatch gate
+
+**When to run:** pre-verify.
+
+## Check
+
+```bash
+#!/usr/bin/env bash
+# PT-BR: agents Supabase não devem invocar outros agents Supabase via Task()
+# Orquestração centralizada no command /supabase (anti-pitfall A10)
+set -e
+
+VIOLATIONS=0
+
+for f in kit/agents/supabase-*.md; do
+  [ -f "$f" ] || continue
+  # PT-BR: busca por Task(...subagent_type=...supabase-... ou Task(... 'supabase-...
+  if grep -nE 'Task\([^)]*subagent_type[^)]*supabase-' "$f"; then
+    echo "FAIL: $f — agent Supabase invocando outro agent Supabase via Task()"
+    VIOLATIONS=$((VIOLATIONS + 1))
+  fi
+done
+
+if [ "$VIOLATIONS" -gt 0 ]; then
+  echo "Total violations: $VIOLATIONS"
+  echo "Agents Supabase devem ser função pura. Orquestração apenas via /supabase command."
+  exit 1
+fi
+
+echo "✓ Zero recursive dispatch entre agents Supabase"
+exit 0
+```
+
+## Verdict
+
+- **passed** — zero `Task(subagent_type=supabase-...)` em `kit/agents/supabase-*.md`
+- **block** — recursive dispatch detectado
+
+## Notes
+
+Anti-pitfall A10 da v1.8: tentação de `supabase-architect` invocar `supabase-migration-writer` que re-invoca architect → stack overflow lógico + custo LLM multiplicado. Solução: agents permanecem função pura; chain via `/supabase` command (Phase 27 — único orquestrador autorizado).

package/gates/budget-description.md

@@ -0,0 +1,68 @@
+---
+id: budget-description
+stage: pre-verify
+blocking: true
+description: Valida que cada agent/command/skill tem `description:` ≤ 200 chars no frontmatter (anti-pitfall A2 — CLAUDE.md inflation).
+---
+
+# Budget description gate
+
+**When to run:** pre-verify, antes de commit final do milestone.
+
+## Check
+
+```bash
+#!/usr/bin/env bash
+# PT-BR: itera por todos os agent/command/skill, valida frontmatter description ≤ 200 chars
+set -e
+
+VIOLATIONS=0
+
+# function que extrai description do YAML frontmatter
+check_description() {
+  local file="$1"
+  local desc
+  desc=$(awk '/^description:/{sub(/^description: ?/, ""); print; exit}' "$file" 2>/dev/null || true)
+  if [ -z "$desc" ]; then
+    echo "WARN: $file — sem description: no frontmatter"
+    return 0
+  fi
+  local len=${#desc}
+  if [ "$len" -gt 200 ]; then
+    echo "FAIL: $file — description tem $len chars (max 200)"
+    VIOLATIONS=$((VIOLATIONS + 1))
+  fi
+}
+
+# itera agents
+for f in kit/agents/*.md; do
+  [ -f "$f" ] && check_description "$f"
+done
+
+# itera commands
+for f in kit/commands/*.md; do
+  [ -f "$f" ] && check_description "$f"
+done
+
+# itera skills (SKILL.md em subdirs)
+for f in kit/skills/*/SKILL.md; do
+  [ -f "$f" ] && check_description "$f"
+done
+
+if [ "$VIOLATIONS" -gt 0 ]; then
+  echo "Total violations: $VIOLATIONS (max description length 200 chars)"
+  exit 1
+fi
+
+echo "✓ Todos os agents/commands/skills têm description ≤ 200 chars"
+exit 0
+```
+
+## Verdict
+
+- **passed** — todas as descriptions ≤ 200 chars
+- **block** — pelo menos uma description > 200 chars (CLAUDE.md inflation)
+
+## Notes
+
+Anti-pitfall A2 da v1.8: cluster `supabase-*` adiciona 19+ entradas em CLAUDE.md. Sem este budget, descriptions verbosas inflam CLAUDE.md em ~3-4 KB+ — desfaz otimização de v1.6/v1.7.

package/gates/no-personal-uuid.md

@@ -0,0 +1,72 @@
+---
+id: no-personal-uuid
+stage: pre-verify
+blocking: true
+description: Detecta UUIDs no formato [0-9a-f]{8}-[0-9a-f]{4}-... em frontmatter `tools:` ou body de skills/agents/commands. UUID pessoal quebra para outros instaladores (anti-pitfall A12).
+---
+
+# No personal UUID gate
+
+**When to run:** pre-verify.
+
+## Check
+
+```bash
+#!/usr/bin/env bash
+# PT-BR: detecta UUID em formato [0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}
+# em frontmatter tools: ou body de kit/{agents,commands,skills}/
+set -e
+
+# allowlist: glossário menciona patterns mas não usa UUID em tools
+ALLOWLIST_FILES=(
+  "kit/skills/_shared-supabase/glossary.md"
+)
+
+VIOLATIONS=0
+
+is_allowlisted() {
+  local file="$1"
+  for af in "${ALLOWLIST_FILES[@]}"; do
+    [ "$file" = "$af" ] && return 0
+  done
+  return 1
+}
+
+check_uuid() {
+  local file="$1"
+  is_allowlisted "$file" && return 0
+
+  # PT-BR: extrair frontmatter (entre --- ... ---)
+  local frontmatter
+  frontmatter=$(awk '/^---$/{i++; next} i==1' "$file" 2>/dev/null || true)
+
+  # PT-BR: buscar UUID em frontmatter (linhas com tools: ou abaixo)
+  if echo "$frontmatter" | grep -qE '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'; then
+    echo "FAIL (frontmatter): $file"
+    grep -nE '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}' "$file" | head -3
+    VIOLATIONS=$((VIOLATIONS + 1))
+  fi
+}
+
+for f in kit/agents/*.md; do [ -f "$f" ] && check_uuid "$f"; done
+for f in kit/commands/*.md; do [ -f "$f" ] && check_uuid "$f"; done
+for f in kit/skills/*/SKILL.md; do [ -f "$f" ] && check_uuid "$f"; done
+
+if [ "$VIOLATIONS" -gt 0 ]; then
+  echo "Total violations: $VIOLATIONS"
+  echo "UUIDs pessoais quebram para outros instaladores. Use mcp__supabase__* canônico."
+  exit 1
+fi
+
+echo "✓ Zero UUIDs pessoais em kit/{agents,commands,skills}/"
+exit 0
+```
+
+## Verdict
+
+- **passed** — zero UUIDs em frontmatter ou body
+- **block** — pelo menos um UUID pessoal detectado (quebra para outros users)
+
+## Notes
+
+Anti-pitfall A12 da v1.8: `schema-checker.md` originalmente usava `mcp__0a712001-6cbb-44ef-a5f4-a24ea40894fa__execute_sql` (UUID do projeto pessoal do user). Distribuído via `@luanpdd/kit-mcp`, isso quebra para qualquer outro instalador. Phase 28 migra para `mcp__supabase__*` canônico. Este gate previne regressão.

package/gates/obs-agents-mcp-supabase.md

@@ -0,0 +1,86 @@
+---
+id: obs-agents-mcp-supabase
+stage: pre-verify
+blocking: true
+description: Valida que agents observability que precisam de MCP Supabase declaram tools mcp__supabase__* no frontmatter (incident-investigator, slo-engineer, burn-rate-forecaster, omm-auditor).
+---
+
+# Observability agents MCP Supabase declaration gate
+
+**When to run:** pre-verify.
+
+## Check
+
+```bash
+#!/usr/bin/env bash
+# PT-BR: agents que usam MCP Supabase devem declarar tools mcp__supabase__* no frontmatter.
+# Anti-pitfall: declaração ausente faz Claude Code não autorizar tool, agent falha em runtime.
+set -e
+
+VIOLATIONS=0
+
+# PT-BR: agents que DEVEM declarar mcp__supabase__*
+declare_required() {
+  local agent="$1"
+  local required_tools="$2"   # tools separados por |
+  local file="kit/agents/$agent.md"
+
+  if [ ! -f "$file" ]; then
+    echo "FAIL: $file — agent ausente"
+    VIOLATIONS=$((VIOLATIONS + 1))
+    return
+  fi
+
+  # PT-BR: extrair frontmatter tools field (multi-line possível)
+  local in_frontmatter=0
+  local in_tools=0
+  local tools_block=""
+  while IFS= read -r line; do
+    if [ "$line" = "---" ]; then
+      if [ "$in_frontmatter" -eq 0 ]; then
+        in_frontmatter=1
+      else
+        break
+      fi
+    elif [ "$in_frontmatter" -eq 1 ]; then
+      tools_block="$tools_block $line"
+    fi
+  done < "$file"
+
+  local IFS='|'
+  for tool in $required_tools; do
+    if ! echo "$tools_block" | grep -qF "$tool"; then
+      echo "FAIL: $file — não declara '$tool' em frontmatter tools"
+      VIOLATIONS=$((VIOLATIONS + 1))
+    fi
+  done
+}
+
+# PT-BR: incident-investigator usa get_logs/execute_sql/get_advisors
+declare_required "incident-investigator" "mcp__supabase__get_logs|mcp__supabase__execute_sql|mcp__supabase__get_advisors"
+
+# PT-BR: slo-engineer usa execute_sql + apply_migration
+declare_required "slo-engineer" "mcp__supabase__execute_sql|mcp__supabase__apply_migration"
+
+# PT-BR: burn-rate-forecaster usa execute_sql
+declare_required "burn-rate-forecaster" "mcp__supabase__execute_sql"
+
+# PT-BR: omm-auditor usa execute_sql (queries SLI)
+declare_required "omm-auditor" "mcp__supabase__execute_sql"
+
+if [ "$VIOLATIONS" -eq 0 ]; then
+  echo "PASS: 4 agents observability declaram mcp__supabase__* corretamente"
+  exit 0
+else
+  echo "FAIL: $VIOLATIONS violação(ões)"
+  exit 1
+fi
+```
+
+## Why
+
+Agents observability que aplicam Core Analysis Loop ou queries SLI dependem de `mcp__supabase__*`. Sem declaração no frontmatter `tools`, Claude Code não autoriza o tool em runtime e o agent falha (precedente: anti-pitfall identificado em v1.8 com supabase-* agents).
+
+## REQ
+
+QA-02.

package/gates/obs-skills-frontmatter.md

@@ -0,0 +1,76 @@
+---
+id: obs-skills-frontmatter
+stage: pre-verify
+blocking: true
+description: Valida que skills observability têm frontmatter completo (name + description ≤ 200 chars) e seções obrigatórias do template.
+---
+
+# Observability skills frontmatter gate
+
+**When to run:** pre-verify.
+
+## Check
+
+```bash
+#!/usr/bin/env bash
+# PT-BR: validar que cada skill em kit/skills/{structured-events,distributed-tracing,opentelemetry-standard,core-analysis-loop,observability-driven-development,event-based-slos,burn-rate-alerting,telemetry-sampling,telemetry-pipelines,observability-maturity-model}/SKILL.md
+# tem frontmatter completo + seções obrigatórias.
+# Portable bash 3.2+ (macOS default).
+set -e
+
+VIOLATIONS=0
+SKILLS="structured-events distributed-tracing opentelemetry-standard core-analysis-loop observability-driven-development event-based-slos burn-rate-alerting telemetry-sampling telemetry-pipelines observability-maturity-model"
+
+for skill in $SKILLS; do
+  file="kit/skills/$skill/SKILL.md"
+  if [ ! -f "$file" ]; then
+    echo "FAIL: $file — skill ausente"
+    VIOLATIONS=$((VIOLATIONS + 1))
+    continue
+  fi
+
+  # PT-BR: frontmatter name presente
+  if ! grep -qE '^name:' "$file"; then
+    echo "FAIL: $file — frontmatter 'name:' ausente"
+    VIOLATIONS=$((VIOLATIONS + 1))
+  fi
+
+  # PT-BR: frontmatter description presente
+  if ! grep -qE '^description:' "$file"; then
+    echo "FAIL: $file — frontmatter 'description:' ausente"
+    VIOLATIONS=$((VIOLATIONS + 1))
+  else
+    desc=$(grep -E '^description:' "$file" | head -1 | sed 's/description: //')
+    len=${#desc}
+    if [ "$len" -gt 200 ]; then
+      echo "FAIL: $file — description=$len chars (limite 200, anti-pitfall A2)"
+      VIOLATIONS=$((VIOLATIONS + 1))
+    fi
+  fi
+
+  # PT-BR: 4+ seções H2 (Quando usar, Regras absolutas, Patterns canônicos, Anti-patterns OU Verificação)
+  h2_count=$(grep -cE '^## ' "$file")
+  if [ "$h2_count" -lt 4 ]; then
+    echo "FAIL: $file — só $h2_count seções H2 (mínimo 4 — Quando usar, Regras absolutas, Patterns canônicos, Anti-patterns/Verificação)"
+    VIOLATIONS=$((VIOLATIONS + 1))
+  fi
+done
+
+if [ "$VIOLATIONS" -eq 0 ]; then
+  echo "PASS: 10 skills observability com frontmatter completo + 4+ seções H2"
+  exit 0
+else
+  echo "FAIL: $VIOLATIONS violação(ões)"
+  exit 1
+fi
+```
+
+## Why
+
+- Skills sem `description` não aparecem em `listKit` (LLM não acha o trigger)
+- `description > 200 chars` infla CLAUDE.md desnecessariamente (anti-pitfall A2)
+- Skills sem template fixo geram outputs inconsistentes — gate força padrão.
+
+## REQ
+
+QA-01.

package/gates/omm-no-regression.md

@@ -0,0 +1,83 @@
+---
+id: omm-no-regression
+stage: pre-conclude
+blocking: false
+description: Valida que nenhuma das 5 capacidades OMM regrediu vs marco anterior. Rodável em /concluir-marco. Não-bloqueante (warn) por default; configurável via workflow.omm_no_regression.
+---
+
+# OMM no-regression gate
+
+**When to run:** pre-conclude (antes de `/concluir-marco` arquivar marco).
+
+## Check
+
+```bash
+#!/usr/bin/env bash
+# PT-BR: validar que OMM-REPORT.md atual não tem capacidade regredida vs marco anterior.
+# Estratégia: comparar scores no OMM-REPORT.md atual vs último arquivado.
+set -e
+
+CURRENT=".planning/OMM-REPORT.md"
+
+if [ ! -f "$CURRENT" ]; then
+  echo "WARN: $CURRENT ausente — rodar /auditar-observabilidade primeiro. Pulando gate."
+  exit 0
+fi
+
+# PT-BR: encontrar OMM-REPORT.md anterior em milestones arquivados
+PREVIOUS=$(find .planning/milestones -name "OMM-REPORT.md" -type f 2>/dev/null | sort -r | head -1)
+
+if [ -z "$PREVIOUS" ] || [ ! -f "$PREVIOUS" ]; then
+  echo "INFO: sem OMM-REPORT anterior arquivado (primeiro marco com OMM). Pulando regression check."
+  exit 0
+fi
+
+# PT-BR: extrair scores do OMM-REPORT.md atual e anterior
+# Formato esperado: "| 1 | Resiliência | 3 | ... |"
+
+REGRESSIONS=0
+for cap in 1 2 3 4 5; do
+  current_score=$(grep -E "^\| $cap \| " "$CURRENT" 2>/dev/null | awk -F'|' '{print $4}' | tr -d ' ' | head -1)
+  previous_score=$(grep -E "^\| $cap \| " "$PREVIOUS" 2>/dev/null | awk -F'|' '{print $4}' | tr -d ' ' | head -1)
+
+  if [ -z "$current_score" ] || [ -z "$previous_score" ]; then
+    continue
+  fi
+
+  if [ "$current_score" -lt "$previous_score" ]; then
+    cap_name=$(grep -E "^\| $cap \| " "$CURRENT" | awk -F'|' '{print $3}' | xargs)
+    echo "REGRESSION: Capacidade $cap ($cap_name) regrediu de $previous_score → $current_score"
+    REGRESSIONS=$((REGRESSIONS + 1))
+  fi
+done
+
+if [ "$REGRESSIONS" -eq 0 ]; then
+  echo "PASS: nenhuma das 5 capacidades OMM regrediu vs $PREVIOUS"
+  exit 0
+else
+  echo "WARN: $REGRESSIONS capacidade(s) regredida(s)"
+  # PT-BR: blocking=false por default. Para tornar bloqueante:
+  #   workflow.omm_no_regression=true
+  if [ "$(node ./.claude/framework/bin/tools.cjs config-get workflow.omm_no_regression 2>/dev/null || echo false)" = "true" ]; then
+    exit 1
+  fi
+  exit 0
+fi
+```
+
+## Why
+
+OMM regression alerta o time que algo deteriorou apesar do esforço do marco. Sem este gate, regressions silenciam e accumulate como tech debt invisível.
+
+Default não-bloqueante para evitar ruído inicial; flag `workflow.omm_no_regression=true` opt-in quando time confiante.
+
+## REQ
+
+QA-03 + INT-FW-04 + INT-FW-05.
+
+## Configuração
+
+```bash
+# PT-BR: tornar bloqueante (recomendado depois de 2-3 marcos consecutivos sem regression)
+node ./.claude/framework/bin/tools.cjs config-set workflow.omm_no_regression true
+```

package/gates/skill-must-include.md

@@ -0,0 +1,71 @@
+---
+id: skill-must-include
+stage: pre-verify
+blocking: true
+description: Valida que skills supabase-* contêm strings obrigatórias verbatim — anti-pattern prevention (RLS (select), search_path, getAll/setAll, etc.).
+---
+
+# Skill must-include gate
+
+**When to run:** pre-verify.
+
+## Check
+
+```bash
+#!/usr/bin/env bash
+# PT-BR: cada skill deve incluir strings obrigatórias verbatim para prevenir anti-patterns
+# Portable: bash 3.2+ (macOS default), sem associative arrays
+set -e
+
+VIOLATIONS=0
+
+check_skill() {
+  local skill="$1"
+  local required="$2"   # strings separadas por |
+  local file="kit/skills/$skill/SKILL.md"
+
+  if [ ! -f "$file" ]; then
+    echo "FAIL: $file — skill ausente"
+    VIOLATIONS=$((VIOLATIONS + 1))
+    return
+  fi
+
+  # PT-BR: testa cada string (separada por |)
+  local IFS='|'
+  for str in $required; do
+    if ! grep -qF "$str" "$file"; then
+      echo "FAIL: $file — must-include ausente: '$str'"
+      VIOLATIONS=$((VIOLATIONS + 1))
+    fi
+  done
+}
+
+check_skill "supabase-rls-policies"        "(select auth.uid())|user_metadata|TO authenticated"
+check_skill "supabase-database-functions"  "set search_path = ''|SECURITY INVOKER"
+check_skill "supabase-auth-ssr"            "getAll|setAll|auth-helpers-nextjs|@supabase/ssr"
+check_skill "supabase-realtime"            "broadcast|private: true|realtime.broadcast_changes|removeChannel"
+check_skill "supabase-edge-functions"      "npm:|jsr:|Deno.serve|EdgeRuntime.waitUntil|/tmp"
+check_skill "supabase-declarative-schema"  "supabase/schemas/|supabase stop|supabase db diff -f"
+check_skill "supabase-migrations"          "YYYYMMDDHHmmss|RLS|granular"
+check_skill "supabase-postgres-style"      "snake_case|ISO 8601|lowercase"
+check_skill "supabase-storage"             "signed URL|storage.objects|multi-tenant"
+check_skill "supabase-pgvector-rag"        "HNSW|IVFFlat|<=>|RAG with permissions"
+check_skill "supabase-cron-queues"         "pg_cron|pgmq|pg_net"
+
+if [ "$VIOLATIONS" -gt 0 ]; then
+  echo "Total violations: $VIOLATIONS"
+  exit 1
+fi
+
+echo "✓ Todas as skills supabase-* contêm must-include strings"
+exit 0
+```
+
+## Verdict
+
+- **passed** — todas as 11 skills têm strings obrigatórias
+- **block** — pelo menos uma skill faltando string crítica (anti-pattern prevention quebrada)
+
+## Notes
+
+Anti-pitfall A7 da v1.8: skills devem prevenir ativamente os anti-patterns Supabase mais críticos. Sem este gate, refator de skill pode acidentalmente remover a regra principal (ex: `(select auth.uid())` wrapper que previne 1000× degradação). Strings como `WARNING user_metadata`, `set search_path = ''`, `NEVER use auth-helpers-nextjs` são as primeiras coisas que LLM lê — devem estar lá.