@luanpdd/kit-mcp 1.28.0 → 1.30.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 luanpdd
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 luanpdd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,168 +1,168 @@
-# kit-mcp
-
-[![npm version](https://img.shields.io/npm/v/@luanpdd/kit-mcp.svg)](https://www.npmjs.com/package/@luanpdd/kit-mcp)
-[![npm downloads](https://img.shields.io/npm/dm/@luanpdd/kit-mcp.svg)](https://www.npmjs.com/package/@luanpdd/kit-mcp)
-[![CI](https://github.com/luanpdd/kit-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/luanpdd/kit-mcp/actions/workflows/ci.yml)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-> Um kit de **agentes, comandos e skills** prontos para Claude Code, Cursor, Codex, Gemini CLI, Windsurf e outros — destilado da documentação oficial do Supabase, livros canônicos de engenharia, e técnicas comprovadas de orquestração agêntica.
->
-> Entregue como **MCP server**. Você usa direto via `npx`, sem instalar nada.
-
-<!-- AUTOGEN-COUNTS-START -->
-**Bundled workflow:** 66 agents · 89 commands · 76 skills · 23 gates
-<!-- AUTOGEN-COUNTS-END -->
-
----
-
-## O que é
-
-Quando você usa LLMs em projetos reais, o problema raramente é o modelo — é o **contexto**. Skills, agents e slash-commands são o jeito moderno de injetar processo, padrões canônicos e guard-rails no Claude Code (e similares) sem reescrever cada prompt.
-
-`kit-mcp` é um **kit curado** que materializa isso em três fontes de verdade:
-
-- **Documentação oficial do Supabase** — RLS, branching, Edge Functions, migrations, pgTAP, Custom Claims, Postgres Roles, Storage, Realtime, Cron, pgvector e todas as outras camadas, com anti-pitfalls explícitos.
-- **Livros canônicos** — *Working Effectively with Legacy Code* (Feathers), *Designing Data-Intensive Applications* (Kleppmann), *Observability Engineering* (Majors/Fong-Jones/Miranda) e *Google SRE Book* viraram skills aplicáveis (characterization tests, consistency models, golden signals, eliminating toil).
-- **Técnicas de harness agêntico** — orquestração via slash-commands (`/discutir-fase`, `/planejar-fase`, `/executar-fase`), handoff cooperativo entre agents, gates de pre-verify, replay determinístico, observabilidade do próprio fluxo agêntico.
-
-Tudo escrito em **PT-BR**, com tabelas, fluxogramas, exemplos rodáveis e referências cruzadas.
-
----
-
-## Instalar (sem instalar)
-
-Adicione ao `.mcp.json` do seu projeto (ou config global do IDE):
-
-```json
-{
-  "mcpServers": {
-    "kit-mcp": {
-      "command": "npx",
-      "args": ["-y", "@luanpdd/kit-mcp"]
-    }
-  }
-}
-```
-
-Pronto. Na próxima sessão, o IDE faz `npx` e expõe os 7 tools do kit-mcp. Nada instalado globalmente, sem `npm install`.
-
-### Registrar automaticamente
-
-```bash
-npx -y @luanpdd/kit-mcp install claude-code
-# ou: cursor, codex, gemini-cli, windsurf, antigravity, copilot, trae
-```
-
-### Projetar skills/agents/commands para o IDE ler
-
-```bash
-npx -y @luanpdd/kit-mcp sync claude-code
-```
-
-Isso escreve markdown em `.claude/agents/`, `.claude/skills/`, etc. O IDE lê do disco — não precisa do server vivo.
-
-### Fluxo completo de primeiro uso
-
-```bash
-npx -y @luanpdd/kit-mcp init
-# 1. registra MCP server no IDE
-# 2. projeta o kit
-# 3. roda diagnóstico
-# 4. confirma: "✓ Claude Code agora vê N skills, M agents, K commands"
-```
-
----
-
-## Comandos diários
-
-| Comando | Para quê |
-|---|---|
-| `kit-mcp logs --tail --follow` | Ver tool calls do servidor em tempo real (JSONL em `~/.kit-mcp/logs/`) |
-| `kit-mcp status` | p50/p95/p99 + error rate + sidecar status |
-| `kit-mcp doctor` | Diagnóstico completo (versão, sidecar, hooks, IDE config, log dir) |
-| `kit-mcp inspect` | TUI live mostrando request/response do MCP |
-| `kit-mcp replay list \| show <id>` | Inspecionar payloads de agents gravados |
-
----
-
-## O que a comunidade precisa saber
-
-### Dois fluxos diferentes, mesma origem
-
-```
-┌─────────────┐  kit sync     ┌──────────────────┐
-│ kit/        │ ──────────▶   │ .claude/agents/  │   IDE lê do disco
-│ (npm pkg)   │  (offline,    │ .claude/skills/  │   na inicialização
-│             │   one-shot)   │ .claude/commands/│
-└─────────────┘               └──────────────────┘
-
-┌──────────────┐  spawns       ┌──────────────────┐
-│ Claude Code  │ ────────────▶ │ kit-mcp (stdio)  │   tools live via
-│  (IDE host)  │  stdin/stdout │  7 tools         │   JSON-RPC
-└──────────────┘ ◀──────────── └──────────────────┘
-```
-
-- **`kit sync`** projeta o conteúdo no formato nativo do IDE — funciona offline e o IDE só precisa dos arquivos.
-- **`kit-mcp` (MCP server)** roda como subprocess do IDE e expõe 7 tools (`kit`, `sync`, `gates`, `forensics`, `install`, `metrics-snapshot`, `reverse-sync`).
-
-**Sem output no terminal ao rodar `kit-mcp`?** Não é bug. A spec MCP proíbe stdout fora do JSON-RPC. Use `kit-mcp logs --follow` ou o sidecar UI em `http://localhost:7878`.
-
-### Stable API v1.0+ desde v1.13
-
-16 releases sem breaking changes na superfície MCP. Sua config `.mcp.json` continua funcionando.
-
-### Princípio canônico do handoff cooperativo (v1.23+)
-
-Agents não-Supabase **planejam**, agents Supabase **materializam/hardenam**, ninguém descarta upstream. `BLOCK` rígido é anti-pattern — verdicts são `GO` / `STRENGTHEN` / `REWRITE com confirmação`.
-
-### Defense-in-depth em 10 camadas (Supabase)
-
-RLS + Column-Level + Custom Claims + Postgres Roles + Audit Log + LGPD + Super-admin + Realtime auth + Branching + CI/CD. Cada camada documentada com pattern canônico e anti-patterns.
-
-### Convenção PT-BR
-
-Skills, agents e commands são em PT-BR. Termos técnicos canônicos (RLS, SLO, characterization tests) ficam em EN para preservar busca e referências.
-
-### Configuração via env vars
-
-| Var | Default | O que faz |
-|---|---|---|
-| `KIT_MCP_NO_UI` | unset | `=1` desabilita sidecar UI auto-spawn |
-| `KIT_MCP_LOG_DIR` | `~/.kit-mcp/logs` | Override do log dir |
-| `KIT_MCP_LOG_RETENTION_DAYS` | `7` | Retention (0 = forever) |
-| `KIT_MCP_INSPECT` | unset | `=1` anexa args/result aos eventos log |
-| `KIT_MCP_NOTIFY` | unset | `=1` OS notification em cada tool call |
-
-### Estrutura do kit
-
-```
-kit/
-├── agents/      66 agents executáveis (planner, executor, debugger, supabase-rls-hardener, …)
-├── commands/    89 slash-commands (/discutir-fase, /planejar-fase, /executar-fase, …)
-├── skills/      76 skills consultáveis (supabase-rls-policies, structured-events, legacy-characterization-tests, …)
-├── framework/   workflows e templates que os agents delegam
-└── hooks/       PostToolUse hooks (sidecar-tool-publisher, etc)
-```
-
-### Contribuindo
-
-- Issues e PRs: [github.com/luanpdd/kit-mcp](https://github.com/luanpdd/kit-mcp)
-- Skills/agents são markdown puro com frontmatter YAML — editar e abrir PR
-- Antes de mexer em código `src/`, leia o `.planning/` (workflow framework)
-
-### Quando NÃO usar
-
-- Você não usa Supabase, Claude Code/Cursor, nem trabalha com agents — provavelmente outro kit serve melhor
-- Você quer um framework genérico tipo LangChain — kit-mcp é opinionated, em PT-BR, focado no fluxo Supabase + agêntico
-
----
-
-## Licença
-
-[MIT](LICENSE) — use, modifique, fork à vontade.
-
----
-
-**Criado por [Luan PDD](https://github.com/luanpdd)** — engenharia, curadoria de conteúdo e direção do projeto.
-
-Inspirado pelo [vinilana/dotcontext](https://github.com/vinilana/dotcontext).
+# kit-mcp
+
+[![npm version](https://img.shields.io/npm/v/@luanpdd/kit-mcp.svg)](https://www.npmjs.com/package/@luanpdd/kit-mcp)
+[![npm downloads](https://img.shields.io/npm/dm/@luanpdd/kit-mcp.svg)](https://www.npmjs.com/package/@luanpdd/kit-mcp)
+[![CI](https://github.com/luanpdd/kit-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/luanpdd/kit-mcp/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+> Um kit de **agentes, comandos e skills** prontos para Claude Code, Cursor, Codex, Gemini CLI, Windsurf e outros — destilado da documentação oficial do Supabase, livros canônicos de engenharia, e técnicas comprovadas de orquestração agêntica.
+>
+> Entregue como **MCP server**. Você usa direto via `npx`, sem instalar nada.
+
+<!-- AUTOGEN-COUNTS-START -->
+**Bundled workflow:** 67 agents · 89 commands · 81 skills · 23 gates
+<!-- AUTOGEN-COUNTS-END -->
+
+---
+
+## O que é
+
+Quando você usa LLMs em projetos reais, o problema raramente é o modelo — é o **contexto**. Skills, agents e slash-commands são o jeito moderno de injetar processo, padrões canônicos e guard-rails no Claude Code (e similares) sem reescrever cada prompt.
+
+`kit-mcp` é um **kit curado** que materializa isso em três fontes de verdade:
+
+- **Documentação oficial do Supabase** — RLS, branching, Edge Functions, migrations, pgTAP, Custom Claims, Postgres Roles, Storage, Realtime, Cron, pgvector e todas as outras camadas, com anti-pitfalls explícitos.
+- **Livros canônicos** — *Working Effectively with Legacy Code* (Feathers), *Designing Data-Intensive Applications* (Kleppmann), *Observability Engineering* (Majors/Fong-Jones/Miranda) e *Google SRE Book* viraram skills aplicáveis (characterization tests, consistency models, golden signals, eliminating toil).
+- **Técnicas de harness agêntico** — orquestração via slash-commands (`/discutir-fase`, `/planejar-fase`, `/executar-fase`), handoff cooperativo entre agents, gates de pre-verify, replay determinístico, observabilidade do próprio fluxo agêntico.
+
+Tudo escrito em **PT-BR**, com tabelas, fluxogramas, exemplos rodáveis e referências cruzadas.
+
+---
+
+## Instalar (sem instalar)
+
+Adicione ao `.mcp.json` do seu projeto (ou config global do IDE):
+
+```json
+{
+  "mcpServers": {
+    "kit-mcp": {
+      "command": "npx",
+      "args": ["-y", "@luanpdd/kit-mcp"]
+    }
+  }
+}
+```
+
+Pronto. Na próxima sessão, o IDE faz `npx` e expõe os 7 tools do kit-mcp. Nada instalado globalmente, sem `npm install`.
+
+### Registrar automaticamente
+
+```bash
+npx -y @luanpdd/kit-mcp install claude-code
+# ou: cursor, codex, gemini-cli, windsurf, antigravity, copilot, trae
+```
+
+### Projetar skills/agents/commands para o IDE ler
+
+```bash
+npx -y @luanpdd/kit-mcp sync claude-code
+```
+
+Isso escreve markdown em `.claude/agents/`, `.claude/skills/`, etc. O IDE lê do disco — não precisa do server vivo.
+
+### Fluxo completo de primeiro uso
+
+```bash
+npx -y @luanpdd/kit-mcp init
+# 1. registra MCP server no IDE
+# 2. projeta o kit
+# 3. roda diagnóstico
+# 4. confirma: "✓ Claude Code agora vê N skills, M agents, K commands"
+```
+
+---
+
+## Comandos diários
+
+| Comando | Para quê |
+|---|---|
+| `kit-mcp logs --tail --follow` | Ver tool calls do servidor em tempo real (JSONL em `~/.kit-mcp/logs/`) |
+| `kit-mcp status` | p50/p95/p99 + error rate + sidecar status |
+| `kit-mcp doctor` | Diagnóstico completo (versão, sidecar, hooks, IDE config, log dir) |
+| `kit-mcp inspect` | TUI live mostrando request/response do MCP |
+| `kit-mcp replay list \| show <id>` | Inspecionar payloads de agents gravados |
+
+---
+
+## O que a comunidade precisa saber
+
+### Dois fluxos diferentes, mesma origem
+
+```
+┌─────────────┐  kit sync     ┌──────────────────┐
+│ kit/        │ ──────────▶   │ .claude/agents/  │   IDE lê do disco
+│ (npm pkg)   │  (offline,    │ .claude/skills/  │   na inicialização
+│             │   one-shot)   │ .claude/commands/│
+└─────────────┘               └──────────────────┘
+
+┌──────────────┐  spawns       ┌──────────────────┐
+│ Claude Code  │ ────────────▶ │ kit-mcp (stdio)  │   tools live via
+│  (IDE host)  │  stdin/stdout │  7 tools         │   JSON-RPC
+└──────────────┘ ◀──────────── └──────────────────┘
+```
+
+- **`kit sync`** projeta o conteúdo no formato nativo do IDE — funciona offline e o IDE só precisa dos arquivos.
+- **`kit-mcp` (MCP server)** roda como subprocess do IDE e expõe 7 tools (`kit`, `sync`, `gates`, `forensics`, `install`, `metrics-snapshot`, `reverse-sync`).
+
+**Sem output no terminal ao rodar `kit-mcp`?** Não é bug. A spec MCP proíbe stdout fora do JSON-RPC. Use `kit-mcp logs --follow` ou o sidecar UI em `http://localhost:7878`.
+
+### Stable API v1.0+ desde v1.13
+
+16 releases sem breaking changes na superfície MCP. Sua config `.mcp.json` continua funcionando.
+
+### Princípio canônico do handoff cooperativo (v1.23+)
+
+Agents não-Supabase **planejam**, agents Supabase **materializam/hardenam**, ninguém descarta upstream. `BLOCK` rígido é anti-pattern — verdicts são `GO` / `STRENGTHEN` / `REWRITE com confirmação`.
+
+### Defense-in-depth em 10 camadas (Supabase)
+
+RLS + Column-Level + Custom Claims + Postgres Roles + Audit Log + LGPD + Super-admin + Realtime auth + Branching + CI/CD. Cada camada documentada com pattern canônico e anti-patterns.
+
+### Convenção PT-BR
+
+Skills, agents e commands são em PT-BR. Termos técnicos canônicos (RLS, SLO, characterization tests) ficam em EN para preservar busca e referências.
+
+### Configuração via env vars
+
+| Var | Default | O que faz |
+|---|---|---|
+| `KIT_MCP_NO_UI` | unset | `=1` desabilita sidecar UI auto-spawn |
+| `KIT_MCP_LOG_DIR` | `~/.kit-mcp/logs` | Override do log dir |
+| `KIT_MCP_LOG_RETENTION_DAYS` | `7` | Retention (0 = forever) |
+| `KIT_MCP_INSPECT` | unset | `=1` anexa args/result aos eventos log |
+| `KIT_MCP_NOTIFY` | unset | `=1` OS notification em cada tool call |
+
+### Estrutura do kit
+
+```
+kit/
+├── agents/      67 agents executáveis (planner, executor, debugger, supabase-rls-hardener, supabase-edge-fn-tester, …)
+├── commands/    89 slash-commands (/discutir-fase, /planejar-fase, /executar-fase, …)
+├── skills/      81 skills consultáveis (supabase-rls-policies, supabase-edge-functions-auth, supabase-edge-runtime-builtins, …)
+├── framework/   workflows e templates que os agents delegam
+└── hooks/       PostToolUse hooks (sidecar-tool-publisher, etc)
+```
+
+### Contribuindo
+
+- Issues e PRs: [github.com/luanpdd/kit-mcp](https://github.com/luanpdd/kit-mcp)
+- Skills/agents são markdown puro com frontmatter YAML — editar e abrir PR
+- Antes de mexer em código `src/`, leia o `.planning/` (workflow framework)
+
+### Quando NÃO usar
+
+- Você não usa Supabase, Claude Code/Cursor, nem trabalha com agents — provavelmente outro kit serve melhor
+- Você quer um framework genérico tipo LangChain — kit-mcp é opinionated, em PT-BR, focado no fluxo Supabase + agêntico
+
+---
+
+## Licença
+
+[MIT](LICENSE) — use, modifique, fork à vontade.
+
+---
+
+**Criado por [Luan PDD](https://github.com/luanpdd)** — engenharia, curadoria de conteúdo e direção do projeto.
+
+Inspirado pelo [vinilana/dotcontext](https://github.com/vinilana/dotcontext).

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

@@ -1,82 +1,82 @@
----
-id: agent-no-recursive-dispatch
-stage: pre-verify
-blocking: true
-description: Valida que agents Supabase não montam ciclos via Task(). DAGs cooperativos v1.23+ (hardener/implementer pattern) são permitidos.
----
-
-# Agent no recursive dispatch gate
-
-**When to run:** pre-verify.
-
-## Context
-
-A v1.8 introduziu este gate para prevenir o anti-pitfall A10: tentação de `supabase-architect` invocar `supabase-migration-writer` que re-invocaria architect → **ciclo** lógico + custo LLM multiplicado.
-
-A v1.23+ introduziu o pattern de **handoff cooperativo** (princípio canônico): agents não-Supabase planejam, agents Supabase materializam/hardenam, ninguém descarta upstream. Isso significa que **dispatches DAG entre agents Supabase são legítimos** (ex: `supabase-rls-writer` → `supabase-rls-hardener`). Apenas **ciclos** são proibidos.
-
-Este gate, portanto, valida o conjunto **proibido** (ciclos) e o conjunto **permitido** (handoffs DAG canônicos da hierarquia hardener/implementer).
-
-## Allowlist canônica de handoffs DAG (downstream-only)
-
-- `supabase-rls-hardener` (v1.23) — canonical handoff target
-- `supabase-rls-writer` (v1.8) — pode invocar hardener; hardener nunca invoca writer de volta
-- `supabase-column-privileges-writer` (v1.24)
-- `supabase-rbac-implementer` (v1.25)
-- `supabase-roles-implementer` (v1.26)
-- `supabase-migration-writer` (cross-suite SQL handoff)
-- `supabase-branching-architect` (v1.27)
-- `supabase-cicd-pipeline-implementer` (v1.27)
-
-Dispatches para esses targets são **permitidos** mesmo quando o caller é também um agent Supabase.
-
-## Check
-
-```bash
-#!/usr/bin/env bash
-# PT-BR: agents Supabase podem invocar peers via DAG canônico (hardener/implementer pattern v1.23+).
-# Proibido: ciclos. Permitido: dispatches downstream para a allowlist da hierarquia cooperativa.
-set -e
-
-VIOLATIONS=0
-
-# Allowlist canônica (downstream-only): cada um destes é leaf na DAG cooperativa
-ALLOWLIST='supabase-(rls-hardener|rls-writer|column-privileges-writer|rbac-implementer|roles-implementer|migration-writer|branching-architect|cicd-pipeline-implementer)'
-
-for f in kit/agents/supabase-*.md; do
-  [ -f "$f" ] || continue
-  # 1. Match raw: linha contém Task(...subagent_type=...supabase-...)
-  # 2. Excluir allowlist (handoffs DAG legítimos v1.23+)
-  # 3. Excluir linhas de auto-documentação ("Este agent é invocável via Task" / "Cross-suite handoff: invocar via")
-  matches=$(grep -nE 'Task\([^)]*subagent_type[^)]*supabase-' "$f" \
-    | grep -vE "subagent_type[^)]*${ALLOWLIST}" \
-    | grep -vE 'Este agent é invocável via|Cross-suite handoff: invocar via|invocável via .?Task' \
-    || true)
-  if [ -n "$matches" ]; then
-    echo "FAIL: $f — dispatch fora da allowlist canônica (potencial ciclo):"
-    echo "$matches"
-    VIOLATIONS=$((VIOLATIONS + 1))
-  fi
-done
-
-if [ "$VIOLATIONS" -gt 0 ]; then
-  echo "Total violations: $VIOLATIONS"
-  echo "Agents Supabase podem invocar a allowlist canônica (hardener/implementer pattern v1.23+)."
-  echo "Dispatches fora dessa lista correm risco de ciclo (anti-pitfall A10)."
-  exit 1
-fi
-
-echo "✓ Zero recursive dispatch fora da allowlist canônica"
-exit 0
-```
-
-## Verdict
-
-- **passed** — zero dispatches fora da allowlist DAG canônica
-- **block** — dispatch para target não-allowlist detectado (potencial ciclo)
-
-## Notes
-
-- Anti-pitfall A10 (v1.8) ainda válido para targets **não-allowlist** (ex: architect → migration-writer fora do flow cooperativo)
-- Allowlist v1.23-v1.27 reflete o princípio canônico: agents Supabase materializam/hardenam via DAG; ciclos continuam proibidos
-- Para adicionar novo handoff target: incluir em `ALLOWLIST` acima e documentar a justificativa cross-suite
+---
+id: agent-no-recursive-dispatch
+stage: pre-verify
+blocking: true
+description: Valida que agents Supabase não montam ciclos via Task(). DAGs cooperativos v1.23+ (hardener/implementer pattern) são permitidos.
+---
+
+# Agent no recursive dispatch gate
+
+**When to run:** pre-verify.
+
+## Context
+
+A v1.8 introduziu este gate para prevenir o anti-pitfall A10: tentação de `supabase-architect` invocar `supabase-migration-writer` que re-invocaria architect → **ciclo** lógico + custo LLM multiplicado.
+
+A v1.23+ introduziu o pattern de **handoff cooperativo** (princípio canônico): agents não-Supabase planejam, agents Supabase materializam/hardenam, ninguém descarta upstream. Isso significa que **dispatches DAG entre agents Supabase são legítimos** (ex: `supabase-rls-writer` → `supabase-rls-hardener`). Apenas **ciclos** são proibidos.
+
+Este gate, portanto, valida o conjunto **proibido** (ciclos) e o conjunto **permitido** (handoffs DAG canônicos da hierarquia hardener/implementer).
+
+## Allowlist canônica de handoffs DAG (downstream-only)
+
+- `supabase-rls-hardener` (v1.23) — canonical handoff target
+- `supabase-rls-writer` (v1.8) — pode invocar hardener; hardener nunca invoca writer de volta
+- `supabase-column-privileges-writer` (v1.24)
+- `supabase-rbac-implementer` (v1.25)
+- `supabase-roles-implementer` (v1.26)
+- `supabase-migration-writer` (cross-suite SQL handoff)
+- `supabase-branching-architect` (v1.27)
+- `supabase-cicd-pipeline-implementer` (v1.27)
+
+Dispatches para esses targets são **permitidos** mesmo quando o caller é também um agent Supabase.
+
+## Check
+
+```bash
+#!/usr/bin/env bash
+# PT-BR: agents Supabase podem invocar peers via DAG canônico (hardener/implementer pattern v1.23+).
+# Proibido: ciclos. Permitido: dispatches downstream para a allowlist da hierarquia cooperativa.
+set -e
+
+VIOLATIONS=0
+
+# Allowlist canônica (downstream-only): cada um destes é leaf na DAG cooperativa
+ALLOWLIST='supabase-(rls-hardener|rls-writer|column-privileges-writer|rbac-implementer|roles-implementer|migration-writer|branching-architect|cicd-pipeline-implementer)'
+
+for f in kit/agents/supabase-*.md; do
+  [ -f "$f" ] || continue
+  # 1. Match raw: linha contém Task(...subagent_type=...supabase-...)
+  # 2. Excluir allowlist (handoffs DAG legítimos v1.23+)
+  # 3. Excluir linhas de auto-documentação ("Este agent é invocável via Task" / "Cross-suite handoff: invocar via")
+  matches=$(grep -nE 'Task\([^)]*subagent_type[^)]*supabase-' "$f" \
+    | grep -vE "subagent_type[^)]*${ALLOWLIST}" \
+    | grep -vE 'Este agent é invocável via|Cross-suite handoff: invocar via|invocável via .?Task' \
+    || true)
+  if [ -n "$matches" ]; then
+    echo "FAIL: $f — dispatch fora da allowlist canônica (potencial ciclo):"
+    echo "$matches"
+    VIOLATIONS=$((VIOLATIONS + 1))
+  fi
+done
+
+if [ "$VIOLATIONS" -gt 0 ]; then
+  echo "Total violations: $VIOLATIONS"
+  echo "Agents Supabase podem invocar a allowlist canônica (hardener/implementer pattern v1.23+)."
+  echo "Dispatches fora dessa lista correm risco de ciclo (anti-pitfall A10)."
+  exit 1
+fi
+
+echo "✓ Zero recursive dispatch fora da allowlist canônica"
+exit 0
+```
+
+## Verdict
+
+- **passed** — zero dispatches fora da allowlist DAG canônica
+- **block** — dispatch para target não-allowlist detectado (potencial ciclo)
+
+## Notes
+
+- Anti-pitfall A10 (v1.8) ainda válido para targets **não-allowlist** (ex: architect → migration-writer fora do flow cooperativo)
+- Allowlist v1.23-v1.27 reflete o princípio canônico: agents Supabase materializam/hardenam via DAG; ciclos continuam proibidos
+- Para adicionar novo handoff target: incluir em `ALLOWLIST` acima e documentar a justificativa cross-suite