@luanpdd/kit-mcp 1.8.1 → 1.10.0

package/gates/postmortem-template-required.md

@@ -0,0 +1,127 @@
+---
+id: postmortem-template-required
+stage: pre-conclude
+blocking: true
+description: Bloqueia /concluir-marco se há investigação em .planning/investigations/ sem postmortem correspondente em .planning/postmortems/. "No postmortem left unreviewed" (cap 15).
+---
+
+# Postmortem template required gate
+
+**When to run:** pre-conclude (blocking — milestone NÃO arquiva até cada incident ter postmortem blameless).
+
+## Check
+
+```bash
+#!/usr/bin/env bash
+# PT-BR: validar que cada investigação em .planning/investigations/ tem postmortem em .planning/postmortems/.
+# Match por basename (sem extensão .md). Investigations com Status: INCONCLUSIVE são exceção.
+# Bash 3.2-portable (macOS default).
+set -e
+
+INV_DIR=".planning/investigations"
+PM_DIR=".planning/postmortems"
+
+# PT-BR: se não há investigations, gate passa com INFO
+if [ ! -d "$INV_DIR" ]; then
+  echo "INFO: $INV_DIR não existe — projeto sem incidents registrados. Gate skipped."
+  exit 0
+fi
+
+# PT-BR: listar investigations (single-file *.md OR subdir com STATE.md)
+INVESTIGATIONS=""
+
+# PT-BR: pattern A — .planning/investigations/<id>.md (single file)
+SINGLE_FILES=$(find "$INV_DIR" -maxdepth 1 -type f -name "*.md" 2>/dev/null || true)
+if [ -n "$SINGLE_FILES" ]; then
+  INVESTIGATIONS="$INVESTIGATIONS
+$SINGLE_FILES"
+fi
+
+# PT-BR: pattern B — .planning/investigations/<id>/STATE.md (subdir state)
+SUBDIR_STATES=$(find "$INV_DIR" -mindepth 2 -maxdepth 2 -type f -name "STATE.md" 2>/dev/null || true)
+if [ -n "$SUBDIR_STATES" ]; then
+  INVESTIGATIONS="$INVESTIGATIONS
+$SUBDIR_STATES"
+fi
+
+# PT-BR: filtrar linhas vazias
+INVESTIGATIONS=$(echo "$INVESTIGATIONS" | grep -v "^$" || true)
+
+if [ -z "$INVESTIGATIONS" ]; then
+  echo "INFO: $INV_DIR vazio — sem incidents registrados. Gate skipped."
+  exit 0
+fi
+
+# PT-BR: para cada investigation, extrair <id> e checar postmortem correspondente
+MISSING=0
+MISSING_LIST=""
+OLDIFS="$IFS"
+IFS='
+'
+for inv_path in $INVESTIGATIONS; do
+  [ -z "$inv_path" ] && continue
+  [ ! -f "$inv_path" ] && continue
+
+  # PT-BR: extrair <id> — basename sem .md OU dirname se for STATE.md em subdir
+  base=$(basename "$inv_path")
+  if [ "$base" = "STATE.md" ]; then
+    # pattern B — id é o nome do subdir parent
+    id=$(basename "$(dirname "$inv_path")")
+  else
+    # pattern A — id é basename sem .md
+    id="${base%.md}"
+  fi
+
+  # PT-BR: se investigation tem Status: INCONCLUSIVE (sem root cause), pular
+  if grep -qiE "^Status:.*INCONCLUSIVE|^.*Status.*INCONCLUSIVE" "$inv_path" 2>/dev/null; then
+    echo "INFO: investigation '$id' marcada INCONCLUSIVE — sem root cause, postmortem não exigido."
+    continue
+  fi
+
+  # PT-BR: postmortem esperado em .planning/postmortems/<id>.md
+  pm_path="$PM_DIR/$id.md"
+  if [ ! -f "$pm_path" ]; then
+    MISSING=$((MISSING + 1))
+    MISSING_LIST="$MISSING_LIST $id"
+  fi
+done
+IFS="$OLDIFS"
+
+if [ "$MISSING" -eq 0 ]; then
+  echo "PASS: todas as investigações têm postmortem correspondente em $PM_DIR/"
+  exit 0
+else
+  echo "FAIL: $MISSING investigação(ões) sem postmortem em $PM_DIR/:$MISSING_LIST"
+  echo "Sugestão: rodar /postmortem --from-investigation <id> para cada item ausente."
+  echo "Cross-ref: kit/skills/blameless-postmortems/SKILL.md + kit/agents/postmortem-writer.md"
+  echo "Princípio canônico: 'No postmortem left unreviewed' (cap 15 livro Google SRE)."
+  exit 1
+fi
+```
+
+## Verdict
+
+- **passed** — todas investigations têm postmortem correspondente OR investigations marcadas INCONCLUSIVE OR diretório `.planning/investigations/` ausente
+- **block** — pelo menos 1 investigation sem postmortem em `.planning/postmortems/`
+
+## Why
+
+O livro Google SRE (cap 15 — *Postmortem Culture: Learning from Failure*) define como princípio canônico **"no postmortem left unreviewed"**: cada incident significativo (registrado como investigação via `/forense` + `incident-investigator` v1.9) deve gerar postmortem blameless documentando *o que aprendemos* e *o que mudaremos*.
+
+Sem este gate, milestones arquivam com investigations órfãs — root cause foi diagnosticado mas aprendizado organizacional perdeu-se (anti-pattern hero culture: "fixei o bug, vamos seguir"). Gate força a chain canônica entre v1.9 (Core Analysis Loop diagnostica) e v1.10 (postmortem documenta).
+
+Cross-ref agent canônico: [`postmortem-writer`](../kit/agents/postmortem-writer.md) (Phase 37 / AGCORE-SRE-03). Skill: [`blameless-postmortems`](../kit/skills/blameless-postmortems/SKILL.md) (Phase 36 / SKFD-SRE-04). Comando: `/postmortem --from-investigation <id>` (Phase 38 / CMD-SRE-03). Chain documentado em `kit/commands/forense.md` bloco `<sre_integration>` (Plan 40-01 / INT-FW-V2-01).
+
+## REQ
+
+QA-SRE-02.
+
+## Configuração
+
+Gate é **blocking** por default (cultura SRE blameless é não-negociável uma vez instituída). Para tornar warn-only durante adoption inicial:
+
+```bash
+node ./.claude/framework/bin/tools.cjs config-set workflow.postmortem_required_warn true
+```
+
+(Nota: implementação do toggle warn-only é deferida — gate atual lê apenas presença/ausência de pares investigation↔postmortem, não consulta config.)

package/gates/prr-checklist-coverage.md

@@ -0,0 +1,128 @@
+---
+id: prr-checklist-coverage
+stage: pre-verify
+blocking: true
+description: Valida que cada PRR-REPORT.md em .planning/prr/ cobre os 6 axes canonicos (System Architecture/Instrumentation/Emergency/Capacity/Change/Performance — cap 32 livro Google SRE).
+---
+
+# PRR checklist coverage gate
+
+**When to run:** pre-verify (blocking — PRR sem 6 axes = aprovação inválida).
+
+## Check
+
+```bash
+#!/usr/bin/env bash
+# PT-BR: validar que cada PRR-REPORT.md em .planning/prr/**/*.md cobre os 6 axes do PRR.
+# Match por palavra-chave em heading H2 (case-insensitive). Pular um axe = aprovação inválida.
+# Bash 3.2-portable (macOS default).
+set -e
+
+PRR_DIR=".planning/prr"
+
+# PT-BR: se não há PRR reports, gate passa com INFO
+if [ ! -d "$PRR_DIR" ]; then
+  echo "INFO: $PRR_DIR não existe — projeto sem PRR reports. Gate skipped."
+  exit 0
+fi
+
+# PT-BR: listar todos os *.md em .planning/prr/ recursivamente
+PRR_FILES=$(find "$PRR_DIR" -type f -name "*.md" 2>/dev/null || true)
+PRR_FILES=$(echo "$PRR_FILES" | grep -v "^$" || true)
+
+if [ -z "$PRR_FILES" ]; then
+  echo "INFO: $PRR_DIR vazio — sem PRR reports. Gate skipped."
+  exit 0
+fi
+
+# PT-BR: para cada PRR report, validar que cobre os 6 axes
+VIOLATIONS=0
+OLDIFS="$IFS"
+IFS='
+'
+for prr_file in $PRR_FILES; do
+  [ -z "$prr_file" ] && continue
+  [ ! -f "$prr_file" ] && continue
+
+  # PT-BR: extrair headings H2 (case-insensitive)
+  H2=$(grep -E "^## " "$prr_file" 2>/dev/null || true)
+
+  # PT-BR: 6 axes — match em palavras-chave (qualquer variante aceitável)
+  AXE_MISSING=""
+
+  # Axe 1: System Architecture
+  if ! echo "$H2" | grep -qiE "system.*architecture|architecture"; then
+    AXE_MISSING="$AXE_MISSING Axe1(SystemArchitecture)"
+  fi
+
+  # Axe 2: Instrumentation / Metrics / Monitoring
+  if ! echo "$H2" | grep -qiE "instrumentation|metrics|monitoring"; then
+    AXE_MISSING="$AXE_MISSING Axe2(Instrumentation)"
+  fi
+
+  # Axe 3: Emergency Response
+  if ! echo "$H2" | grep -qiE "emergency.*response|emergency"; then
+    AXE_MISSING="$AXE_MISSING Axe3(EmergencyResponse)"
+  fi
+
+  # Axe 4: Capacity Planning
+  if ! echo "$H2" | grep -qiE "capacity.*planning|capacity"; then
+    AXE_MISSING="$AXE_MISSING Axe4(CapacityPlanning)"
+  fi
+
+  # Axe 5: Change Management
+  if ! echo "$H2" | grep -qiE "change.*management|change"; then
+    AXE_MISSING="$AXE_MISSING Axe5(ChangeManagement)"
+  fi
+
+  # Axe 6: Performance
+  if ! echo "$H2" | grep -qiE "performance"; then
+    AXE_MISSING="$AXE_MISSING Axe6(Performance)"
+  fi
+
+  if [ -n "$AXE_MISSING" ]; then
+    echo "FAIL: $prr_file — axes ausentes:$AXE_MISSING"
+    VIOLATIONS=$((VIOLATIONS + 1))
+  fi
+done
+IFS="$OLDIFS"
+
+if [ "$VIOLATIONS" -eq 0 ]; then
+  total=$(echo "$PRR_FILES" | wc -l | tr -d ' ')
+  echo "PASS: $total PRR-REPORT(s) cobrem os 6 axes canônicos"
+  exit 0
+else
+  echo "FAIL: $VIOLATIONS PRR-REPORT(s) com axes ausentes"
+  echo "Sugestão: rodar /sre prr <service> ou /prr para regenerar com template canônico (6 axes obrigatórios)."
+  echo "Cross-ref: kit/skills/production-readiness-review/SKILL.md + kit/agents/prr-conductor.md"
+  echo "Princípio canônico: 'Pular um axe = aprovação inválida' (cap 32 livro Google SRE)."
+  exit 1
+fi
+```
+
+## Verdict
+
+- **passed** — cada PRR-REPORT.md em `.planning/prr/**/*.md` tem H2 cobrindo os 6 axes (System Architecture / Instrumentation / Emergency Response / Capacity Planning / Change Management / Performance) OR diretório `.planning/prr/` ausente
+- **block** — pelo menos 1 PRR-REPORT.md com axe(s) ausente(s)
+
+## Why
+
+O livro Google SRE (cap 32 — *Evolving SRE Engagement Model*) define **6 axes canônicos** do Production Readiness Review. A skill `production-readiness-review` (Phase 36 / SKFD-SRE-05) declara como regra absoluta: *"Pular um axe = aprovação inválida (lacuna oculta vira incident em 6 meses)"*.
+
+Sem este gate, PRRs apressados podem omitir axes "menos relevantes" (anti-pattern documentado na skill); gaps em Change Management ou Capacity Planning não detectados em PRR viram incidents em produção meses depois. Gate força padrão canônico — cada `PRR-REPORT.md` cobrindo os 6 axes integralmente, mesmo que items dentro de um axe sejam N/A para o serviço (justificativa explícita no item, não no axe).
+
+Cross-ref agent canônico: [`prr-conductor`](../kit/agents/prr-conductor.md) (Phase 37 / AGCORE-SRE-04). Skill: [`production-readiness-review`](../kit/skills/production-readiness-review/SKILL.md) (Phase 36 / SKFD-SRE-05). Comando: `/prr --service <name>` ou `/prr --feature <description>` (Phase 38 / CMD-SRE-04).
+
+## REQ
+
+QA-SRE-03.
+
+## Configuração
+
+Gate é **blocking** por default. Para tornar warn-only durante adoption inicial:
+
+```bash
+node ./.claude/framework/bin/tools.cjs config-set workflow.prr_checklist_coverage_warn true
+```
+
+(Nota: implementação do toggle warn-only é deferida — gate atual não consulta config.)

package/gates/skill-must-include.md

@@ -14,41 +14,43 @@ description: Valida que skills supabase-* contêm strings obrigatórias verbatim
 ```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
 
-# 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"
+check_skill() {
+  local skill="$1"
+  local required="$2"   # strings separadas por |
+  local file="kit/skills/$skill/SKILL.md"
 
-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
+    return
   fi
 
   # PT-BR: testa cada string (separada por |)
-  IFS='|' read -ra REQUIRED <<< "${MUST_INCLUDE[$skill]}"
-  for str in "${REQUIRED[@]}"; do
+  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
-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"

package/kit/agents/burn-rate-forecaster.md

@@ -0,0 +1,160 @@
+---
+name: burn-rate-forecaster
+description: Calcula burn rate atual + ETA exhaustão + alert config (page vs ticket) — usa lookahead/baseline windows fator 4×, mcp__supabase__execute_sql para queries SLI.
+tools: Read, Bash, Grep, mcp__supabase__execute_sql, mcp__supabase__list_tables
+color: orange
+---
+
+Você é o forecaster de burn rate. Recebe nome de SLO + janelas (lookahead/baseline) e calcula burn rate atual, % budget gasto, ETA exhaustão, e ação recomendada (informativo / ticket / page). Você consulta a skill [`burn-rate-alerting`](../skills/burn-rate-alerting/SKILL.md) — conhecimento autoritativo sobre fórmulas de extrapolação.
+
+## Compatibilidade
+
+| IDE | Tier | Capability |
+|---|---|---|
+| Claude Code (com Supabase MCP) | **Full** | Queries live em SLI views via execute_sql |
+| Cursor (com Supabase MCP) | **Full** | Idem |
+| Codex | **Partial** | Apresenta SQL ao user, parsea resultado colado |
+| Gemini CLI | **Partial** | Idem |
+| Windsurf, Antigravity, Copilot, Trae | **Offline-only** | SQL como text, sem execução |
+
+## Por que existe
+
+Burn rate calculado errado é pior que não calculado — false positives geram alert fatigue, false negatives perdem incidents. Este agent aplica fórmula canônica do livro Cap 13 (lookahead ≤ 4× baseline, target burn 14.4× para page, 1× para ticket) consistentemente.
+
+## Inputs esperados (do caller)
+
+- `slo_name`: nome do SLO (ex: `checkout_success`) — view materializada deve existir em `obs.sli_<slo_name>`
+- (Opcional) `lookahead`: `4h` (default short-term) | `3d` (long-term) | custom
+- (Opcional) `baseline`: `1h` (default short-term) | `18h` (long-term) | custom
+- (Opcional) `target`: target % do SLO (default: lê de `.planning/slos/<slo_name>.md`)
+
+## Passos
+
+### Step 0 — Preflight
+
+1. Verificar que `.planning/slos/<slo_name>.md` existe — extrair `target` e `window`.
+2. Verificar que `obs.sli_<slo_name>` existe via `mcp__supabase__list_tables --schemas=['obs']`.
+
+Se algo faltando, abortar com mensagem clara: "SLO {name} não definido. Rode `/definir-slo {feature}` primeiro."
+
+### Step 1 — Validar lookahead ≤ 4× baseline
+
+```text
+if lookahead_seconds > 4 × baseline_seconds:
+  warn "lookahead 4h é confiável apenas com baseline ≥ 1h. Sua config: lookahead=Xh, baseline=Yh — fora da regra 4×."
+  Sugerir ajustar baseline ou usar context-aware burn rate.
+```
+
+### Step 2 — Query burn rate atual (baseline window)
+
+```sql
+-- PT-BR: burn rate em janela baseline
+with baseline as (
+  select
+    sum(good) as good,
+    sum(bad) as bad,
+    sum(total) as total
+  from obs.sli_{slo_name}
+  where bucket > now() - interval '{baseline}'
+)
+select
+  total as events_in_baseline,
+  bad as bad_in_baseline,
+  bad::float / nullif(total, 0) as error_rate,
+  (bad::float / nullif(total, 0)) / (1 - {target_decimal}) as burn_rate
+from baseline;
+```
+
+Invoke via `mcp__supabase__execute_sql` (Full) ou apresentar ao user (Offline).
+
+### Step 3 — Query budget gasto e remanescente (window inteira)
+
+```sql
+-- PT-BR: budget gasto e remaining em window inteira do SLO (default 30d)
+with full_window as (
+  select
+    sum(bad) as burned,
+    sum(total) as total_events
+  from obs.sli_{slo_name}
+  where bucket > now() - interval '30 days'
+)
+select
+  (1 - {target_decimal}) * total_events as budget_events,
+  burned,
+  (1 - {target_decimal}) * total_events - burned as remaining_events,
+  100.0 * burned / nullif((1 - {target_decimal}) * total_events, 0) as budget_burned_pct
+from full_window;
+```
+
+### Step 4 — Predictive forecast — ETA exhaustão
+
+```text
+projected_remaining_at_lookahead = remaining_events_now - (burn_per_baseline × lookahead/baseline)
+
+ETA seconds = remaining_events_now / (burn_per_baseline / baseline_seconds)
+ETA hours = ETA seconds / 3600
+```
+
+### Step 5 — Determinar status
+
+```text
+if burn_rate >= 14.4 (sustained 4h+):
+  status = "PAGE"
+  action = "Page on-call imediato — invocar `/investigar-producao`"
+elif burn_rate >= 1.0:
+  status = "TICKET"
+  action = "Criar ticket de eng — investigar antes do budget esgotar (ETA={ETA}h)"
+elif budget_burned_pct >= 80:
+  status = "WARN"
+  action = "Budget acima 80% — proteger contra deploys arriscados"
+else:
+  status = "OK"
+  action = "Informativo apenas"
+```
+
+### Step 6 — Output
+
+Tabela canônica:
+
+```
+═══════════════════════════════════════════════════════════
+BURN-RATE-FORECASTER · {slo_name}
+═══════════════════════════════════════════════════════════
+
+## Snapshot — {timestamp}
+
+| Metric | Value |
+|---|---|
+| SLO target | {target}% |
+| Window | 30d sliding |
+| Budget total | {budget_events} events |
+| Budget gasto | {burned_events} events ({burned_pct}%) |
+| Budget remaining | {remaining_events} events ({remaining_pct}%) |
+| Baseline ({baseline}) error rate | {error_rate}% |
+| Burn rate atual | {burn_rate}× |
+| ETA exhaustão | {ETA} (se burn_rate sustained) |
+
+## Status: **{status}**
+
+{action}
+
+## Comparação — burn rate threshold
+
+| Threshold | Burn rate | Action |
+|---|---|---|
+| Page on-call | ≥ 14.4× | acordar engineer |
+| Ticket | ≥ 1.0× | abrir Jira/Linear |
+| Warn | budget > 80% gasto | rever cadência de deploy |
+
+{Se status = PAGE ou TICKET:}
+## Próximos passos
+1. `/investigar-producao "{slo_name} burn rate = {burn_rate}× às {timestamp}"`
+2. (Após root cause identificada) Decidir: rollback / hotfix / mitigação parcial
+3. Atualizar runbook do SLO com lessons learned
+```
+
+## Quando NÃO invocar
+
+- SLO sem materialized view — invoke `slo-engineer` primeiro
+- Métrica informativa sem target — use dashboard
+- Verificação ad hoc rápida — query direto via `mcp__supabase__execute_sql` se já sabe a fórmula