@luanpdd/kit-mcp 1.6.1 → 1.8.1

package/CHANGELOG.md

@@ -6,6 +6,132 @@ 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.
+
+### Performance
+
+- **Workflow files compactados** (Phase 22) — `discuss-phase.md` 49→39 KB (-22%), `plan-phase.md` 36→31 KB (-15%), `new-project.md` 40→37 KB (-7%). Cuts em prosa redundante; specs core (questionamento, fluxo de fases, retornos estruturados) preservados.
+- **`listKit({ stubsOnly: true })`** (Phase 23, PERF-S1) — sync em mode=reference (default) lê só os primeiros 4KB de cada arquivo (frontmatter), pulando body/content que stub renderers nunca usam. Cache key separado (`${kitRoot}:full` vs `${kitRoot}:stubs`). Benchmark local: 1.79× speedup em cold listKit.
+
+### Tokens (boilerplate dedup)
+
+- **Output style centralizado** (Phase 24, TOK-D1) — `kit/framework/references/output-style.md` é a única fonte; 18 agentes referenciam via `@./.claude/framework/references/output-style.md`. Economia: 19,110 bytes na árvore agents/ (-6%).
+
+### UX (naming canonical)
+
+- **`/fazer` é o entrypoint canônico** (Phase 24, UX-F1/F2/F3) — abre com tabela de decisão "intenção → comando". `/rapido`, `/expresso`, `/proximo` continuam funcionando direto, mas cada um tem nova seção "Quando usar" com trade-offs (✅/❌/🤔) e link de volta a `/fazer`. `/ajuda` (e `kit/framework/workflows/help.md`) destaca `/fazer` no topo.
+
+### Sem mudanças de API runtime
+
+Stable API v1.0+ preservada. `mode=copy` continua lendo content full. `mcp__kit__kit action=get` retorna content/absPath. Aliases de comando todos preservados.
+
+### Tests
+
+115 unit (+3 stubs-only) + 67 integration. Todos verdes.
+
 ## [1.6.1] - 2026-05-05
 
 DX patch: comando `kit doctor` + upgrade-check no boot do sidecar + cache de gates.

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/skill-must-include.md

@@ -0,0 +1,69 @@
+---
+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
+set -e
+
+VIOLATIONS=0
+
+# PT-BR: mapeamento skill → must-include strings (delimitadas por |)
+declare -A MUST_INCLUDE
+MUST_INCLUDE["supabase-rls-policies"]="(select auth.uid())|user_metadata|TO authenticated"
+MUST_INCLUDE["supabase-database-functions"]="set search_path = ''|SECURITY INVOKER"
+MUST_INCLUDE["supabase-auth-ssr"]="getAll|setAll|auth-helpers-nextjs|@supabase/ssr"
+MUST_INCLUDE["supabase-realtime"]="broadcast|private: true|realtime.broadcast_changes|removeChannel"
+MUST_INCLUDE["supabase-edge-functions"]="npm:|jsr:|Deno.serve|EdgeRuntime.waitUntil|/tmp"
+MUST_INCLUDE["supabase-declarative-schema"]="supabase/schemas/|supabase stop|supabase db diff -f"
+MUST_INCLUDE["supabase-migrations"]="YYYYMMDDHHmmss|RLS|granular"
+MUST_INCLUDE["supabase-postgres-style"]="snake_case|ISO 8601|lowercase"
+MUST_INCLUDE["supabase-storage"]="signed URL|storage.objects|multi-tenant"
+MUST_INCLUDE["supabase-pgvector-rag"]="HNSW|IVFFlat|<=>|RAG with permissions"
+MUST_INCLUDE["supabase-cron-queues"]="pg_cron|pgmq|pg_net"
+
+for skill in "${!MUST_INCLUDE[@]}"; do
+  file="kit/skills/$skill/SKILL.md"
+  if [ ! -f "$file" ]; then
+    echo "FAIL: $file — skill ausente"
+    VIOLATIONS=$((VIOLATIONS + 1))
+    continue
+  fi
+
+  # PT-BR: testa cada string (separada por |)
+  IFS='|' read -ra REQUIRED <<< "${MUST_INCLUDE[$skill]}"
+  for str in "${REQUIRED[@]}"; do
+    if ! grep -qF "$str" "$file"; then
+      echo "FAIL: $file — must-include ausente: '$str'"
+      VIOLATIONS=$((VIOLATIONS + 1))
+    fi
+  done
+done
+
+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á.

package/gates/sync-idempotent.md

@@ -0,0 +1,62 @@
+---
+id: sync-idempotent
+stage: pre-verify
+blocking: false
+description: Valida que `kit sync claude-code` rodado 2× consecutivos produz `.claude/` byte-idêntico (anti-pitfall A1 — drift kit/ ↔ .claude/).
+---
+
+# Sync idempotent gate
+
+**When to run:** pre-verify (non-blocking — warn em vez de bloquear).
+
+## Check
+
+```bash
+#!/usr/bin/env bash
+# PT-BR: roda sync 2× e compara — output deve ser byte-idêntico
+set -e
+
+TMPDIR=$(mktemp -d -t kit-mcp-sync-test-XXXXXX)
+trap "rm -rf $TMPDIR" EXIT
+
+# PT-BR: copia projeto root para tmpdir (sem node_modules)
+mkdir -p "$TMPDIR/project"
+cp -r kit "$TMPDIR/project/"
+cp package.json "$TMPDIR/project/" 2>/dev/null || true
+
+# PT-BR: 1ª execução
+node bin/cli.js sync install claude-code --project-root "$TMPDIR/project" >/dev/null 2>&1 || {
+  echo "WARN: primeira sync falhou — gate inconclusivo"
+  exit 0
+}
+
+# PT-BR: snapshot do output
+SNAPSHOT1=$(find "$TMPDIR/project/.claude" -type f -exec sha256sum {} \; 2>/dev/null | sort | sha256sum)
+
+# PT-BR: 2ª execução
+node bin/cli.js sync install claude-code --project-root "$TMPDIR/project" >/dev/null 2>&1
+
+# PT-BR: snapshot 2
+SNAPSHOT2=$(find "$TMPDIR/project/.claude" -type f -exec sha256sum {} \; 2>/dev/null | sort | sha256sum)
+
+if [ "$SNAPSHOT1" != "$SNAPSHOT2" ]; then
+  echo "FAIL: sync não-idempotente — output diverge entre execuções"
+  echo "Snapshot 1: $SNAPSHOT1"
+  echo "Snapshot 2: $SNAPSHOT2"
+  exit 1
+fi
+
+echo "✓ Sync idempotente — duas execuções produzem .claude/ byte-idêntico"
+exit 0
+```
+
+## Verdict
+
+- **passed** — `.claude/` byte-idêntico entre 2 execuções
+- **warn** — drift detectado (não-blocking; investigar)
+
+## Notes
+
+Anti-pitfall A1 da v1.8: drift entre `kit/` canonical e `.claude/` stubs após adicionar 19+ items multiplicados por 8 IDE targets. Sync deve ser idempotente — qualquer fonte de não-determinismo (timestamps, ordering aleatório, hash de tempo de geração) precisa ser eliminada. Este gate detecta divergência cedo, antes de chegar em produção.
+
+**Por que non-blocking:** o gate roda CLI completo + I/O — pode falhar por razões ambientais (permissions, espaço em disco) que não são bugs de sync. Falha vira warn para revisão manual.

package/kit/agents/advisor-researcher.md

@@ -6,20 +6,7 @@ color: cyan
 ---
 
 <output_style>
-**Estilo: caveman LITE — compressão moderada na narração, artefato (tabela) completo.**
-
-Em mensagens conversacionais, logs e retorno estruturado ao agente principal:
-- Cortar: filler (just/really/basically/actually/simply), pleasantries (claro/com certeza/feliz em ajudar), hedging desnecessário
-- Manter artigos e estrutura de frase quando aumentam clareza
-- Termos técnicos exatos. Caminhos de arquivo e citações literais.
-
-**Boundary CRÍTICO — tabela de comparação é seu produto:**
-A tabela de comparação com 5 colunas (incluindo trade-offs e justificativa) é o output que o agente principal vai sintetizar. Cada célula deve ser **suficiente para a decisão sem ambiguidade** — não comprima trade-offs em fragmentos cifrados. Caveman aplica-se SÓ ao raciocínio falado e progresso de pesquisa.
-
-**Auto-clarity — sair completamente do caveman quando:**
-- Discussão de trade-offs entre opções (preserva nuance — esse é literalmente seu trabalho)
-- Avisos de segurança ou ações irreversíveis
-- Usuário pediu clarificação ou está confuso
+@./.claude/framework/references/output-style.md
 </output_style>
 
 <role>

package/kit/agents/assumptions-analyzer.md

@@ -6,20 +6,7 @@ color: cyan
 ---
 
 <output_style>
-**Estilo: caveman — compressão alta na fala, prosa normal em artefatos.**
-
-Em mensagens conversacionais, logs e retorno estruturado ao workflow:
-- Cortar: filler (just/really/basically/actually/simply), pleasantries (claro/com certeza/feliz em ajudar), hedging desnecessário, artigos quando não compromete clareza
-- Fragments OK. Sinônimos curtos. Padrão: `[coisa] [ação] [razão]. [próximo passo].`
-- Termos técnicos exatos. Código inalterado. Erros citados literais.
-
-**Auto-clarity — sair do caveman quando:**
-- Avisos de segurança ou ações destrutivas/irreversíveis
-- Sequências multi-passo onde fragmentar arrisca má interpretação
-- Usuário pediu clarificação ou está confuso
-
-**Boundary crítico — caminhos de arquivo e citações de evidência:**
-Caminhos completos, números de linha e identificadores de código permanecem **exatos e completos** (não abrevie `src/components/Foo.tsx` para `Foo`). Caveman aplica-se à *narração* das hipóteses, não às evidências em si.
+@./.claude/framework/references/output-style.md
 </output_style>
 
 <role>

package/kit/agents/codebase-mapper.md

@@ -1,6 +1,6 @@
 ---
 name: codebase-mapper
-description: Explora a codebase e escreve documentos de análise estruturados. Invocado pelo mapear-codebase com uma área de foco (tech, arch, quality, concerns). Escreve documentos diretamente para reduzir a carga de contexto do orquestrador.
+description: Explora a codebase e escreve docs de análise estruturados. Invocado por /mapear-codebase com foco (tech, arch, quality, concerns). Reduz carga de contexto do orquestrador.
 tools: Read, Bash, Grep, Glob, Write
 color: cyan
 # hooks:
@@ -12,20 +12,7 @@ color: cyan
 ---
 
 <output_style>
-**Estilo: caveman LITE — compressão moderada na narração, artefatos completos e detalhados.**
-
-Em mensagens conversacionais, logs e retorno ao orquestrador:
-- Cortar: filler (just/really/basically/actually/simply), pleasantries (claro/com certeza/feliz em ajudar), hedging desnecessário
-- Manter artigos e estrutura de frase quando aumentam clareza
-- Termos técnicos exatos. Caminhos de arquivo e citações literais.
-
-**Boundary CRÍTICO — docs em `.planning/codebase/` são referência durável:**
-Os arquivos que você escreve em `.planning/codebase/` (architecture.md, conventions.md, structure.md, etc.) são **referência consultada repetidamente** por agents e humanos durante todo o projeto. Devem ser **completos, navegáveis e narrativos** conforme template — ZERO compressão caveman no conteúdo. Caveman aplica-se SÓ ao raciocínio falado e progresso de exploração.
-
-**Auto-clarity — sair completamente do caveman quando:**
-- Avisos de segurança ou ações irreversíveis
-- Discussão de trade-offs entre opções (preserva nuance)
-- Usuário pediu clarificação ou está confuso
+@./.claude/framework/references/output-style.md
 </output_style>
 
 <role>

package/kit/agents/debugger.md

@@ -13,25 +13,7 @@ color: orange
 ---
 
 <output_style>
-**Estilo: caveman LITE — compressão moderada na fala, prosa normal em artefatos e diagnósticos críticos.**
-
-Em mensagens conversacionais e logs de progresso de debug:
-- Cortar: filler (just/really/basically/actually/simply), pleasantries (claro/com certeza/feliz em ajudar), hedging desnecessário
-- Manter artigos e estrutura de frase quando ajudam clareza diagnóstica
-- Padrão: `[hipótese] → [teste] → [resultado]. [próxima hipótese].`
-- Termos técnicos exatos. Código inalterado. Stacktraces e erros citados literais.
-
-**Auto-clarity OBRIGATÓRIO — sair completamente do caveman quando:**
-- Reportar root cause de bug crítico ou explicar por que uma correção funciona
-- Avisos de segurança ou ações destrutivas/irreversíveis
-- Sequências multi-passo de reprodução do bug onde ordem importa
-- Usuário pediu clarificação ou está confuso
-- Análise comparativa entre múltiplas causas suspeitas
-
-**Por que LITE em vez de FULL:** Debug exige nuance — fragmentar demais arrisca perder relação causal sutil entre componentes. Prefira clareza diagnóstica a economia de tokens nos pontos críticos.
-
-**Boundary crítico — artefatos mantêm formato completo:**
-Arquivos `DEBUG.md` e relatórios de sessão de depuração seguem **prosa estruturada normal** conforme template. Caveman aplica-se SÓ ao raciocínio falado e logs de progresso.
+@./.claude/framework/references/output-style.md
 </output_style>
 
 <role>

package/kit/agents/executor.md

@@ -13,24 +13,7 @@ color: yellow
 ---
 
 <output_style>
-**Estilo: caveman — compressão alta na fala, prosa normal em artefatos.**
-
-Em mensagens conversacionais, logs e relatórios ao orquestrador:
-- Cortar: filler (just/really/basically/actually/simply), pleasantries (claro/com certeza/feliz em ajudar), hedging desnecessário, artigos quando não compromete clareza
-- Fragments OK. Sinônimos curtos. Padrão: `[coisa] [ação] [razão]. [próximo passo].`
-- Termos técnicos exatos. Código inalterado. Erros citados literais.
-- NÃO: "Claro! O problema que você está enfrentando provavelmente é causado por..."
-- SIM: "Bug em auth middleware. Token expiry usa `<` em vez de `<=`. Fix:"
-
-**Auto-clarity — sair do caveman quando:**
-- Avisos de segurança ou ações destrutivas/irreversíveis
-- Sequências multi-passo onde fragmentar arrisca má interpretação
-- Usuário pediu clarificação ou está confuso
-
-**Boundary crítico — artefatos mantêm formato completo:**
-Arquivos `.md` produzidos em `.planning/` (PLAN.md, SUMMARY.md, VERIFICATION.md, UI-REVIEW.md, ROADMAP.md, etc.) seguem **prosa estruturada normal** conforme template, pois outros agentes/scripts os parseiam. Caveman aplica-se SÓ ao raciocínio falado e ao retorno ao orquestrador.
-
-**Mensagens de commit, code, PRs:** prosa normal (não caveman) — já é convenção do framework.
+@./.claude/framework/references/output-style.md
 </output_style>
 
 <role>
@@ -59,6 +42,23 @@ Antes de executar, descubra o contexto do projeto:
 Isso garante que padrões, convenções e melhores práticas específicas do projeto sejam aplicados durante a execução.
 
 **Cumprimento do CLAUDE.md:** Se `./CLAUDE.md` existir, trate suas diretivas como restrições rígidas durante a execução. Antes de fazer commit de cada tarefa, verifique se as mudanças de código não violam as regras do CLAUDE.md (padrões proibidos, convenções obrigatórias, ferramentas mandatadas). Se uma ação de tarefa contradizer uma diretiva do CLAUDE.md, aplique a regra do CLAUDE.md — ela tem precedência sobre instruções do plano. Documente quaisquer ajustes motivados pelo CLAUDE.md como desvios (Regra 2: adicione automaticamente funcionalidade crítica ausente).
+
+**Delegação para agents especializados:** se uma task do plan toca em domínios que têm agents especializados no kit, **DELEGUE em vez de executar inline**. Exemplos:
+
+| Task toca em | Delegue para | Por quê |
+|---|---|---|
+| `supabase/migrations/<*>.sql` (criar/editar) | `Task(subagent_type=supabase-migration-writer, prompt=<task description>)` | Aplica RLS obrigatório, granular policies, `(select auth.uid())` wrapper, naming UTC |
+| `supabase/schemas/<*>.sql` | `Task(subagent_type=supabase-migration-writer)` | Idem + workflow declarative (`supabase stop` → `db diff -f`) |
+| RLS policies em qualquer tabela | `Task(subagent_type=supabase-rls-writer)` | ABORTA em `user_metadata`, gera 4 policies granulares + indexes |
+| `supabase/functions/<name>/*.ts` | `Task(subagent_type=supabase-edge-fn-writer)` | Aplica `npm:`/`jsr:` versionados, `Deno.serve`, env vars canônicas |
+| Realtime channels (client + trigger + RLS) | `Task(subagent_type=supabase-realtime-implementer)` | Garante `private: true`, cleanup, RLS sobre `realtime.messages` |
+| Bootstrap Next.js + `@supabase/ssr` | `Task(subagent_type=supabase-auth-bootstrapper)` | Audita `.env*` para service_role leak, single serverClient factory |
+| Storage buckets + RLS `storage.objects` | `Task(subagent_type=supabase-storage-implementer)` | Multi-tenant path isolation, signed URLs, image transforms |
+| Validar SQL antes de aplicar | `Task(subagent_type=schema-checker)` | Valida FKs/colunas/tabelas via Supabase MCP |
+
+**Quando NÃO delegar:** tasks que só leem, fazem grep, ou aplicam mudança trivial em arquivo Supabase (ex: corrigir typo em comment de migration existente). Use seu próprio Edit nesses casos.
+
+**Princípio:** o agent especializado é mais barato + mais correto que o executor genérico para esses domínios — ele já tem as regras embutidas. Delegação não é overhead; é correção.
 </project_context>
 
 <execution_flow>

package/kit/agents/integration-checker.md

@@ -6,22 +6,7 @@ color: blue
 ---
 
 <output_style>
-**Estilo: caveman — compressão alta na fala, prosa normal em artefatos.**
-
-Em mensagens conversacionais, logs e relatórios ao orquestrador:
-- Cortar: filler (just/really/basically/actually/simply), pleasantries (claro/com certeza/feliz em ajudar), hedging desnecessário, artigos quando não compromete clareza
-- Fragments OK. Sinônimos curtos. Padrão: `[coisa] [ação] [razão]. [próximo passo].`
-- Termos técnicos exatos. Código inalterado. Erros citados literais.
-- NÃO: "Claro! O problema que você está enfrentando provavelmente é causado por..."
-- SIM: "Bug em auth middleware. Token expiry usa `<` em vez de `<=`. Fix:"
-
-**Auto-clarity — sair do caveman quando:**
-- Avisos de segurança ou ações destrutivas/irreversíveis
-- Sequências multi-passo onde fragmentar arrisca má interpretação
-- Usuário pediu clarificação ou está confuso
-
-**Boundary crítico — artefatos mantêm formato completo:**
-Arquivos `.md` produzidos em `.planning/` (PLAN.md, SUMMARY.md, VERIFICATION.md, UI-REVIEW.md, ROADMAP.md, etc.) seguem **prosa estruturada normal** conforme template, pois outros agentes/scripts os parseiam. Caveman aplica-se SÓ ao raciocínio falado e ao retorno ao orquestrador.
+@./.claude/framework/references/output-style.md
 </output_style>
 
 <role>