@luanpdd/kit-mcp 1.10.0 → 1.11.0

package/kit/commands/auditar-release.md

@@ -0,0 +1,109 @@
+---
+name: auditar-release
+description: Invoca release-pipeline-auditor — audita CI/CD para hermeticidade (lockfile + frozen-install + image SHA + sem network), reprodutibilidade (versions pinned), policy enforcement (branch protection, signed commits, CODEOWNERS). Cap 8 livro Google SRE.
+argument-hint: "[--dimensions hermeticidade,reprodutibilidade,policy-enforcement] [--gh-repo OWNER/REPO]"
+allowed-tools:
+  - Read
+  - Bash
+  - Grep
+  - Glob
+  - Task
+  - Write
+---
+
+<objective>
+Auditar **release pipeline** (CI/CD + Dockerfile + branch protection) em 3 dimensões: hermeticidade, reprodutibilidade, policy enforcement. Invoca o agente [`release-pipeline-auditor`](../agents/release-pipeline-auditor.md) que aplica skills [`hermetic-builds`](../skills/hermetic-builds/SKILL.md) + [`release-engineering`](../skills/release-engineering/SKILL.md).
+
+**Cria/Atualiza:**
+- `.planning/RELEASE-AUDIT.md` — relatório scored 30 pontos com top 5 fixes priorizados
+
+**Após:** o user vê fragility quantificada (não opinião). Resultado feeds PRR Axe 5 (Change Management) v1.10 e gate `release-pipeline-policy` opt-in.
+</objective>
+
+<context>
+**Argumentos:**
+- `--dimensions <list>` — subset de `[hermeticidade, reprodutibilidade, policy-enforcement]` (default: todas)
+- `--gh-repo OWNER/REPO` — override de repo detection (default: `gh repo view`)
+- `--output PATH` — caminho do output (default: `.planning/RELEASE-AUDIT.md`)
+
+**Exemplos:**
+```
+/auditar-release                                          # full audit (3 dims)
+/auditar-release --dimensions hermeticidade               # só hermeticidade
+/auditar-release --gh-repo myorg/myrepo                   # override repo
+```
+
+**Pré-requisitos opcionais:**
+- `gh` CLI autenticado (`gh auth status`) — para checks de branch protection via API
+- Sem `gh`: agent skip dimension policy-enforcement parcialmente (filesystem only)
+</context>
+
+<process>
+
+## 1. Parsear argumentos
+
+```bash
+DIMENSIONS=$(echo "$ARGUMENTS" | grep -oE -- '--dimensions [^ ]+' | awk '{print $2}')
+GH_REPO=$(echo "$ARGUMENTS" | grep -oE -- '--gh-repo [^ ]+' | awk '{print $2}')
+OUTPUT_PATH=$(echo "$ARGUMENTS" | grep -oE -- '--output [^ ]+' | awk '{print $2}')
+
+[ -z "$OUTPUT_PATH" ] && OUTPUT_PATH=".planning/RELEASE-AUDIT.md"
+mkdir -p "$(dirname "$OUTPUT_PATH")"
+```
+
+## 2. Dispatch para `release-pipeline-auditor`
+
+```text
+Task(
+  subagent_type="release-pipeline-auditor",
+  prompt="
+project_root: .
+output_path: ${OUTPUT_PATH}
+${DIMENSIONS:+dimensions: ${DIMENSIONS}}
+${GH_REPO:+gh_repo: ${GH_REPO}}
+
+Aplicar skills hermetic-builds + release-engineering. Etapas:
+1. Detectar lockfile, CI files, Dockerfile
+2. Auditar Hermeticidade (10pts): lockfile commitado, frozen-install, image SHA, sem network, SLSA provenance
+3. Auditar Reprodutibilidade (10pts): actions pinned, node version pinned, package manager pinned, sem timestamps, build cache
+4. Auditar Policy Enforcement (10pts): branch protection, required PR + reviewers + status checks, CODEOWNERS, signed commits, workflow permissions, release via tag
+5. Score agregado (0-30) com veredito ROBUST/ADEQUATE/FRAGILE/BROKEN
+6. Top 5 fixes priorizados com esforço estimado
+"
+)
+```
+
+## 3. Pós-output
+
+```
+═══════════════════════════════════════════════════════════
+ framework ► AUDITAR-RELEASE ▸ ${OUTPUT_PATH}
+═══════════════════════════════════════════════════════════
+
+[output do agent]
+
+## Próximos passos
+
+1. **Aplicar top 5 fixes** do RELEASE-AUDIT.md (esforço total ~1-2h)
+2. **/prr <service>** (v1.10) — Axe 5 (Change Management) consume este audit
+3. **Re-audit em 30d** — verificar progresso
+4. **/concluir-marco** (framework + patch v1.11) — opt-in gate `release-pipeline-policy`
+
+## Cross-suite
+
+- v1.10 SRE — PRR Axe 5 (Change Management)
+- v1.11 SRE Resilience — esse audit
+- v1.12 Legacy — overrides de refactor têm audit trail aqui
+- Framework flow — /concluir-marco gate opt-in
+```
+
+</process>
+
+<success_criteria>
+- [ ] $ARGUMENTS parseados (todos opcionais)
+- [ ] `release-pipeline-auditor` invocado via Task
+- [ ] RELEASE-AUDIT.md scored 30 pts criado
+- [ ] Veredito ROBUST/ADEQUATE/FRAGILE/BROKEN
+- [ ] Top 5 fixes priorizados com esforço
+- [ ] Cross-references com /prr e /concluir-marco
+</success_criteria>

package/kit/commands/capturar-payloads.md

@@ -0,0 +1,193 @@
+---
+name: capturar-payloads
+description: Invoca payload-capture-instrumenter — instrumenta Edge Function Supabase para captura via mcp__supabase__get_logs por N dias, sanitiza PII, gera fixtures para legacy-characterizer. Modernização 2026.
+argument-hint: "<edge_function_path> [--days N] [--max-payloads N] [--mode instrument|drain|full] [--sanitize-keys k1,k2,...]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Grep
+  - Glob
+  - Task
+  - mcp__supabase__execute_sql
+  - mcp__supabase__get_logs
+---
+
+<objective>
+Instrumentar Edge Function Supabase para capturar **payloads reais** de produção, drenar logs após janela de captura via `mcp__supabase__get_logs`, sanitizar PII deterministicamente, e gerar fixtures prontos para alimentar `/caracterizar`. Invoca o agente [`payload-capture-instrumenter`](../agents/payload-capture-instrumenter.md) que aplica a skill [`legacy-characterization-tests`](../skills/legacy-characterization-tests/SKILL.md) Pattern 7.
+
+**Cria/Atualiza:**
+- Patch na Edge Function adicionando log dedicado controlado por env `CAPTURE_PAYLOADS=true`
+- `supabase/functions/_shared/payload-capture.ts` — sanitização canônica
+- `tests/characterization/<edge-fn>/fixtures/payload-NN.json` — fixtures sanitizados após drenagem
+
+**Após:** o user tem fixtures BASEADOS EM DISTRIBUIÇÃO REAL de produção, não em sintéticos. Cobertura comportamental cresce significativamente.
+</objective>
+
+<context>
+**Argumentos:**
+- `<edge_function_path>` — path da Edge Function (e.g., `supabase/functions/process-orders/index.ts`) — OBRIGATÓRIO
+- `--days N` — janela de captura em dias (default: 7)
+- `--max-payloads N` — máximo de fixtures a salvar (default: 100)
+- `--mode instrument|drain|full` — fase do workflow:
+  - `instrument` — só aplica patch (você faz deploy + aguarda)
+  - `drain` — só drena logs (após capture já rodou em prod)
+  - `full` — patch + aguarda + drena (default — orquestra tudo)
+- `--sanitize-keys k1,k2,k3` — keys adicionais a redact
+
+**Workflow esperado:**
+
+```
+Dia 0:  /capturar-payloads <fn> --mode=instrument
+Dia 0:  Você faz deploy + setar CAPTURE_PAYLOADS=true em env
+Dia 1-7: produção captura naturalmente
+Dia 7:  /capturar-payloads <fn> --mode=drain
+Dia 7:  Fixtures criados em tests/characterization/<fn>/fixtures/
+Dia 7:  /caracterizar <fn> --fixtures-dir tests/characterization/<fn>/fixtures
+```
+
+**Exemplos:**
+```
+/capturar-payloads supabase/functions/webhook-stripe/index.ts                  # full mode 7 dias
+/capturar-payloads supabase/functions/process-orders/index.ts --days 14        # janela maior
+/capturar-payloads supabase/functions/process-orders/index.ts --mode=instrument  # só patch
+/capturar-payloads supabase/functions/process-orders/index.ts --mode=drain      # só drenagem
+```
+
+**Pré-requisitos:**
+- Edge Function deployada em Supabase (modo drain depende de logs em prod)
+- MCP Supabase conectado para drenagem automatizada (alternativa: `supabase functions logs` CLI)
+- Tier full em IDEs com MCP; tier partial degrada para instrumentação only
+
+**Quando preferir este comando vs `/caracterizar` direto:**
+- Edge Function tem alto traffic (≥ 100 req/dia) — distribuição real cobre edge cases que sintético não pega
+- Edge Function tem contrato externo crítico (webhook de Stripe/GitHub) — fidelidade absoluta requer payloads reais
+- Equipe quer baseline empírico antes de refactor — payloads reais > inputs sintéticos
+</context>
+
+<process>
+
+## 1. Parsear argumentos
+
+```bash
+EDGE_FN_PATH=$(echo "$ARGUMENTS" | awk '{print $1}')
+CAPTURE_DAYS=$(echo "$ARGUMENTS" | grep -oE -- '--days [0-9]+' | awk '{print $2}')
+MAX_PAYLOADS=$(echo "$ARGUMENTS" | grep -oE -- '--max-payloads [0-9]+' | awk '{print $2}')
+MODE=$(echo "$ARGUMENTS" | grep -oE -- '--mode[= ][^ ]+' | sed 's/--mode[= ]//')
+SANITIZE_KEYS=$(echo "$ARGUMENTS" | grep -oE -- '--sanitize-keys [^ ]+' | awk '{print $2}')
+
+[ -z "$CAPTURE_DAYS" ]  && CAPTURE_DAYS=7
+[ -z "$MAX_PAYLOADS" ]  && MAX_PAYLOADS=100
+[ -z "$MODE" ]          && MODE="full"
+
+if [ -z "$EDGE_FN_PATH" ]; then
+  echo "ERROR: edge_function_path obrigatório"
+  echo "Uso: /capturar-payloads <path> [opções]"
+  exit 1
+fi
+
+if [ ! -f "$EDGE_FN_PATH" ]; then
+  echo "ERROR: arquivo não encontrado: $EDGE_FN_PATH"
+  exit 1
+fi
+```
+
+## 2. Validar pré-requisitos
+
+```bash
+# verificar Edge Function (Deno + Deno.serve)
+if ! grep -q "Deno.serve" "$EDGE_FN_PATH"; then
+  echo "ERROR: $EDGE_FN_PATH não parece Edge Function (sem Deno.serve)"
+  exit 1
+fi
+
+# detectar projeto Supabase
+PROJECT_ID=""
+if [ -f "supabase/config.toml" ]; then
+  PROJECT_ID=$(grep -E '^project_id\s*=' supabase/config.toml | sed 's/.*= *"\(.*\)".*/\1/' | head -1)
+fi
+
+if [ -z "$PROJECT_ID" ] && [ "$MODE" != "instrument" ]; then
+  echo "WARN: PROJECT_ID não detectado em supabase/config.toml — drenagem pode falhar"
+fi
+```
+
+## 3. Dispatch para `payload-capture-instrumenter`
+
+```text
+Task(
+  subagent_type="payload-capture-instrumenter",
+  prompt="
+edge_function_path: ${EDGE_FN_PATH}
+capture_days: ${CAPTURE_DAYS}
+max_payloads: ${MAX_PAYLOADS}
+mode: ${MODE}
+${SANITIZE_KEYS:+sanitize_keys: ${SANITIZE_KEYS}}
+${PROJECT_ID:+project_id: ${PROJECT_ID}}
+
+Aplicar skill legacy-characterization-tests Pattern 7. Etapas:
+1. Preflight: validar Edge Function, detectar project_id
+2. (mode=instrument|full) Patch Edge Function adicionando log dedicado
+3. (mode=instrument) Output mensagem para fazer deploy + setar CAPTURE_PAYLOADS=true
+4. (mode=drain|full após delay) Drenar logs via mcp__supabase__get_logs
+5. Para cada log entry com kind=payload-capture:
+   - Parse payload sanitized
+   - Salvar em tests/characterization/<fn>/fixtures/payload-NN.json
+6. Pós-processamento: validar nenhum unredacted, sanitização adicional
+7. Output curto + recomendações (review fixtures, /caracterizar, remove flag)
+"
+)
+```
+
+## 4. Pós-output
+
+```
+═══════════════════════════════════════════════════════════
+ framework ► CAPTURAR-PAYLOADS ▸ ${EDGE_FN_PATH}
+═══════════════════════════════════════════════════════════
+
+[output do payload-capture-instrumenter]
+
+## Próximos passos por mode
+
+### Após mode=instrument
+1. Deploy: `supabase functions deploy <name>`
+2. Setar env var: `supabase secrets set CAPTURE_PAYLOADS=true`
+3. Aguardar ${CAPTURE_DAYS} dias
+4. Rodar: `/capturar-payloads ${EDGE_FN_PATH} --mode=drain`
+
+### Após mode=drain ou full
+1. **REVISAR fixtures** manualmente — sample 5-10 arquivos
+2. **VALIDAR no PII vaza:**
+   ```bash
+   grep -E "([0-9]{3}\.[0-9]{3}\.[0-9]{3}-?[0-9]{2}|@.*\..*\.com)" tests/characterization/*/fixtures/*.json
+   ```
+3. **Alimentar legacy-characterizer:**
+   ```bash
+   /caracterizar ${EDGE_FN_PATH} --fixtures-dir tests/characterization/$(basename $(dirname ${EDGE_FN_PATH}))/fixtures
+   ```
+4. **Após characterization gerada:** REMOVE flag CAPTURE_PAYLOADS:
+   ```bash
+   supabase secrets unset CAPTURE_PAYLOADS
+   git revert <commit-instrument>
+   ```
+
+## Cross-suite
+
+- **/caracterizar** (v1.12) — consome fixtures gerados aqui
+- **/instrumentar-fase** (v1.9) — captura é instrumentação shift-left aplicada
+- **/golden-signals** (v1.10) — captura E golden signals podem coexistir mesma Edge Function
+```
+
+</process>
+
+<success_criteria>
+- [ ] $ARGUMENTS parseados (edge_function_path obrigatório, 4 flags opcionais)
+- [ ] Pré-requisitos validados (Deno.serve presente; supabase/config.toml para project_id)
+- [ ] `payload-capture-instrumenter` invocado via Task com mode resolvido
+- [ ] Tier degradation correto (Full = MCP drain; Partial = instrument-only)
+- [ ] Output forwarded transparentemente
+- [ ] Próximos passos específicos por mode (instrument vs drain vs full)
+- [ ] Cross-references com /caracterizar, /instrumentar-fase, /golden-signals
+</success_criteria>

package/kit/commands/caracterizar-prompt.md

@@ -0,0 +1,195 @@
+---
+name: caracterizar-prompt
+description: Characterization de prompts/tools LLM em produção — temperature=0 + seed fixo + sanitização específica. Trata prompts como código legacy. Modernização 2026 sem precedente em 2004.
+argument-hint: "<prompt_file> [--inputs-dir PATH] [--provider openai|anthropic] [--seed N] [--max-tokens N] [--num-intents N]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Grep
+  - Glob
+  - Task
+---
+
+<objective>
+Caracterizar **prompt LLM ou tool definition** capturando outputs determinísticos como golden snapshots. Aplica skill [`ai-prompt-characterization`](../skills/ai-prompt-characterization/SKILL.md) — `temperature=0`, `seed` fixo, sanitização de timestamps/UUIDs/datas relativas, 5+ intents distintas. Trata prompt como **código legacy também** — versionado, testado, code-reviewed.
+
+**Cria/Atualiza:**
+- `tests/characterization/prompts/<prompt-stem>.test.ts` (ou `.py`/`.go` conforme runtime)
+- `tests/characterization/prompts/__snapshots__/<prompt-stem>.test.ts.snap`
+- `tests/characterization/prompts/<prompt-stem>/inputs/<intent>.json` — inputs canônicos por intent
+
+**Após:** mudança em prompt deve manter snapshot diff = 0 (ou mudança documentada). Detecta drift de model upstream automaticamente.
+</objective>
+
+<context>
+**Argumentos:**
+- `<prompt_file>` — arquivo do prompt (e.g., `prompts/generate-summary.md`) — OBRIGATÓRIO
+- `--inputs-dir <path>` — diretório com inputs canônicos por intent (default: agent gera 5 sintéticos cobrindo concise/detailed/code/edge/adversarial)
+- `--provider openai|anthropic` — provider de LLM (default: detecta via deps)
+- `--seed N` — seed para determinismo (default: 42)
+- `--max-tokens N` — limite output (default: 500)
+- `--num-intents N` — número de intents a cobrir (default: 5; mínimo: 5)
+- `--system-prompt <text>` — system prompt se aplicável
+
+**Exemplos:**
+```
+/caracterizar-prompt prompts/generate-summary.md
+/caracterizar-prompt prompts/code-reviewer.md --num-intents 7 --max-tokens 1000
+/caracterizar-prompt prompts/intent-classifier.md --inputs-dir test-data/classifier-intents
+/caracterizar-prompt prompts/customer-support.md --provider anthropic --seed 123
+```
+
+**Pré-requisitos:**
+- ANTHROPIC_API_KEY ou OPENAI_API_KEY em env
+- Test framework (Vitest, Jest, pytest, ...)
+- Provider escolhido suporta `temperature=0` + `seed`
+
+**Quando este comando é o caminho:**
+- Prompt em produção > 50 linhas
+- Mudanças em prompt quebraram silenciosamente no passado
+- Equipe quer baseline antes de refactor de prompt
+- CI deve detectar drift de model upstream (Claude 4.7 → 4.8)
+</context>
+
+<process>
+
+## 1. Parsear argumentos
+
+```bash
+PROMPT_FILE=$(echo "$ARGUMENTS" | awk '{print $1}')
+INPUTS_DIR=$(echo "$ARGUMENTS" | grep -oE -- '--inputs-dir [^ ]+' | awk '{print $2}')
+PROVIDER=$(echo "$ARGUMENTS" | grep -oE -- '--provider [^ ]+' | awk '{print $2}')
+SEED=$(echo "$ARGUMENTS" | grep -oE -- '--seed [0-9]+' | awk '{print $2}')
+MAX_TOKENS=$(echo "$ARGUMENTS" | grep -oE -- '--max-tokens [0-9]+' | awk '{print $2}')
+NUM_INTENTS=$(echo "$ARGUMENTS" | grep -oE -- '--num-intents [0-9]+' | awk '{print $2}')
+
+[ -z "$SEED" ]         && SEED=42
+[ -z "$MAX_TOKENS" ]   && MAX_TOKENS=500
+[ -z "$NUM_INTENTS" ]  && NUM_INTENTS=5
+
+if [ -z "$PROMPT_FILE" ]; then
+  echo "ERROR: prompt_file obrigatório"
+  exit 1
+fi
+
+if [ ! -f "$PROMPT_FILE" ]; then
+  echo "ERROR: arquivo não encontrado: $PROMPT_FILE"
+  exit 1
+fi
+```
+
+## 2. Detectar provider + framework
+
+```bash
+# auto-detect provider
+if [ -z "$PROVIDER" ]; then
+  if [ -n "$ANTHROPIC_API_KEY" ]; then
+    PROVIDER="anthropic"
+  elif [ -n "$OPENAI_API_KEY" ]; then
+    PROVIDER="openai"
+  else
+    echo "ERROR: nenhum provider detectado. Setar ANTHROPIC_API_KEY ou OPENAI_API_KEY"
+    exit 1
+  fi
+fi
+
+# detectar test framework
+FRAMEWORK=""
+if [ -f "package.json" ]; then
+  if jq -re '.devDependencies.vitest' package.json >/dev/null 2>&1; then FRAMEWORK="vitest"
+  elif jq -re '.devDependencies.jest' package.json >/dev/null 2>&1; then FRAMEWORK="jest"
+  fi
+elif [ -f "pyproject.toml" ]; then
+  FRAMEWORK="pytest"
+fi
+
+[ -z "$FRAMEWORK" ] && FRAMEWORK="vitest"  # default sane
+```
+
+## 3. Dispatch para `legacy-characterizer` (modo prompt)
+
+```text
+Task(
+  subagent_type="legacy-characterizer",
+  prompt="
+target_file: ${PROMPT_FILE}
+target_kind: prompt
+provider: ${PROVIDER}
+seed: ${SEED}
+max_tokens: ${MAX_TOKENS}
+num_intents: ${NUM_INTENTS}
+${INPUTS_DIR:+inputs_dir: ${INPUTS_DIR}}
+framework: ${FRAMEWORK}
+
+Aplicar skill ai-prompt-characterization. Etapas:
+1. Ler prompt + identificar inputs esperados (system prompt? user message format? tools?)
+2. Gerar (ou ler de inputs-dir) ${NUM_INTENTS}+ inputs cobrindo intents distintas:
+   - concise: pedido curto, output esperado curto
+   - detailed: pedido elaborado, output esperado longo
+   - code-heavy: input/output com código
+   - edge case: input ambíguo
+   - adversarial: prompt injection attempt
+3. Para cada intent: rodar LLM com temperature=0 + seed=${SEED}
+4. Capturar text + finishReason + toolCalls (se function calling) + inputTokens + outputTokens + modelVersion
+5. Sanitizar: timestamps, UUIDs, datas relativas, valores monetários, versões
+6. Salvar como snapshot tests usando ${FRAMEWORK}
+7. Cobertura behavioral = % intents cobertas (não % linhas)
+"
+)
+```
+
+## 4. Pós-output
+
+```
+═══════════════════════════════════════════════════════════
+ framework ► CARACTERIZAR-PROMPT ▸ tests/characterization/prompts/...
+═══════════════════════════════════════════════════════════
+
+[output do legacy-characterizer em modo prompt]
+
+## ⚠ REVISÃO MANUAL OBRIGATÓRIA
+
+Snapshots gerados — leia cada um antes de commit:
+1. Verificar nenhum PII/secret persiste pós-sanitização
+2. Verificar nenhum timestamp/UUID/data relativa unredacted
+3. Confirmar finishReason esperado (stop vs length vs tool_use)
+4. Para tool_uses: confirmar tool name + input shape
+
+## Próximos passos
+
+1. **Revisar snapshots** manualmente
+2. **Rodar suite local:**
+   - JS/TS: `npm test -- tests/characterization/prompts`
+   - Python: `pytest tests/characterization/prompts`
+3. **Commit** como `chore: characterize <prompt-name>`
+4. **Configurar CI:**
+   - `tests/characterization/prompts/**` rodam em PR que toca `prompts/**`
+   - Diff vermelho = mudança comportamental detectada → review humano
+5. **Configurar nightly** para detectar drift de model upstream:
+   - Anthropic publica Claude 4.8 → re-run characterization → snapshot diff
+6. **Custo:** ~${NUM_INTENTS} × ($0.015/1k input tokens × 2k = $0.03 + output) ≈ $0.10-0.50/run
+
+## Cross-suite
+
+- **/caracterizar** (v1.12) — characterization de código (não prompt) — análogo
+- **`llm-as-dependency`** skill — fakear LLM em business logic tests (não esses tests)
+- **`legacy-api-only-applications`** skill — LLM provider é caso especial de API external
+- **/instrumentar-fase** (v1.9) — instrumenta consumer de prompt (latency, tokens)
+```
+
+</process>
+
+<success_criteria>
+- [ ] $ARGUMENTS parseados
+- [ ] Provider detectado automaticamente OU especificado
+- [ ] Framework de teste detectado
+- [ ] `legacy-characterizer` invocado em modo prompt
+- [ ] ≥ 5 intents cobrindo grupos canônicos (concise/detailed/code/edge/adversarial)
+- [ ] temperature=0 + seed=fixo aplicado
+- [ ] Sanitização específica para outputs LLM aplicada
+- [ ] Tests rodam contra LLM real apenas em characterization (não em business logic tests)
+- [ ] Próximos passos: review, commit, CI config, nightly drift detection
+- [ ] Cross-suite com llm-as-dependency e legacy-api-only-applications
+</success_criteria>