@luanpdd/kit-mcp 1.8.1 → 1.9.0

package/README.md

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

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

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

package/gates/obs-skills-frontmatter.md

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

package/gates/omm-no-regression.md

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

package/gates/skill-must-include.md

@@ -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