@luanpdd/kit-mcp 1.9.0 → 1.10.0

package/kit/agents/supabase-storage-implementer.md

@@ -249,6 +249,160 @@ Upload events são quentes em custo (egress + storage) e em UX (lentidão de upl
 
 **Output adicionado:** seção "## Observability hooks" com snippet de upload/download wrapper.
 
+## Saturation signal — bucket size + quota
+
+> Cross-ref canônico: [four-golden-signals](../skills/four-golden-signals/SKILL.md) (cap 6 do livro Google SRE — Monitoring Distributed Systems). Para retro-instrumentar storage existente com os 4 signals, delegar para [golden-signals-instrumenter](./golden-signals-instrumenter.md).
+
+Storage tem o **recurso mais escasso explícito**: o quota do plano (Free 1 GB, Pro 100 GB, Team 1 TB, etc.). Sem signal de saturation, time descobre quota exhaustion via incident (uploads falham silenciosamente em UX) — **anti-pattern clássico** de white-box monitoring sem detecção precoce. O bloco `## Observabilidade integrada` acima cobre Latency / Traffic / Errors (3 signals); este bloco completa com **Saturation** — o 4º signal canônico.
+
+### Saturation = bucket size ÷ quota plan
+
+| Plano | Quota total | Threshold ALERT (yellow) | Threshold PAGE (red) |
+|---|---|---|---|
+| Free | 1 GB | 80% (800 MB) | 95% (950 MB) |
+| Pro | 100 GB | 80% (80 GB) | 95% (95 GB) |
+| Team | 1 TB | 80% (800 GB) | 95% (950 GB) |
+| Enterprise | custom | custom | custom |
+
+### Signal 1 — Gauge: bucket size atual (bytes)
+
+`ObservableGauge` (push periódico via callback) mede tamanho real de cada bucket. Callback consulta `storage.objects` agregado:
+
+```ts
+// PT-BR: 4º signal — saturation (gauge de bucket size em bytes)
+import { metrics } from 'npm:@opentelemetry/api@1.9.0'
+const meter = metrics.getMeter('supabase-storage')
+
+meter.createObservableGauge('storage_bucket_bytes', {
+  description: 'Tamanho atual em bytes por bucket — saturation signal',
+  unit: 'bytes',
+}).addCallback(async (result) => {
+  // PT-BR: query agregada (rodar via service-role client em cron)
+  const sizes = await supabaseAdmin.rpc('storage_bucket_sizes_bytes')
+  // expected: [{ bucket_id: 'avatars', total_bytes: 12345678 }, ...]
+  for (const row of sizes ?? []) {
+    result.observe(row.total_bytes, { 'bucket.id': row.bucket_id })
+  }
+})
+
+meter.createObservableGauge('storage_saturation_pct', {
+  description: 'Saturation = bucket size / quota plan — % do quota usado',
+  unit: '1',  // ratio (0..1)
+}).addCallback(async (result) => {
+  const sizes = await supabaseAdmin.rpc('storage_bucket_sizes_bytes')
+  const QUOTA_BYTES = Number(Deno.env.get('SUPABASE_PLAN_QUOTA_BYTES') ?? 1_000_000_000)  // default Free
+  for (const row of sizes ?? []) {
+    result.observe(row.total_bytes / QUOTA_BYTES, { 'bucket.id': row.bucket_id })
+  }
+})
+```
+
+SQL helper para o callback:
+
+```sql
+-- PT-BR: function que retorna bytes por bucket — chamada por callback OTel
+create or replace function public.storage_bucket_sizes_bytes()
+returns table (bucket_id text, total_bytes bigint)
+language sql
+security definer
+set search_path = ''
+as $$
+  select bucket_id, coalesce(sum((metadata->>'size')::bigint), 0) as total_bytes
+  from storage.objects
+  group by bucket_id;
+$$;
+```
+
+### Signal 2 — Counter: quota near-exhaustion events
+
+`Counter` incrementa a cada upload que **detecta** approach a quota threshold (80%, 95%). Permite contar eventos críticos para alerting:
+
+```ts
+// PT-BR: counter incrementado em cada upload
+const quotaWarnings = meter.createCounter('storage_quota_warnings_total', {
+  description: 'Counter de eventos onde upload aproxima quota — alimentar alert SLO',
+})
+
+export async function uploadInstrumented(file: File, filename: string) {
+  const supabase = createClient()
+  const { data: { user } } = await supabase.auth.getUser()
+  if (!user) throw new Error('not authenticated')
+
+  const path = `${user.id}/${filename}`
+
+  // PT-BR: pre-check — saturation atual antes de upload
+  const sizes = await supabaseAdmin.rpc('storage_bucket_sizes_bytes')
+  const bucketSize = sizes?.find(s => s.bucket_id === '<bucket_name>')?.total_bytes ?? 0
+  const QUOTA = Number(Deno.env.get('SUPABASE_PLAN_QUOTA_BYTES') ?? 1_000_000_000)
+  const saturation = bucketSize / QUOTA
+
+  if (saturation >= 0.95) {
+    quotaWarnings.add(1, { 'bucket.id': '<bucket_name>', threshold: '95pct' })
+  } else if (saturation >= 0.80) {
+    quotaWarnings.add(1, { 'bucket.id': '<bucket_name>', threshold: '80pct' })
+  }
+
+  const { data, error } = await supabase.storage
+    .from('<bucket_name>')
+    .upload(path, file, { upsert: true })
+
+  if (error) throw error
+  return data.path
+}
+```
+
+### Cron schedule sugerido
+
+Saturation gauge não precisa rodar em cada request — agendar leitura via `pg_cron` (ou OTel SDK polling interval = 60s) é suficiente:
+
+```sql
+-- PT-BR: refresh saturation cache a cada 60s para gauge OTel
+create materialized view if not exists obs.storage_saturation as
+  select bucket_id, sum((metadata->>'size')::bigint) as total_bytes, now() as captured_at
+  from storage.objects
+  group by bucket_id;
+
+select cron.schedule(
+  'refresh_storage_saturation',
+  '* * * * *',  -- a cada 1 min
+  $$ refresh materialized view concurrently obs.storage_saturation $$
+);
+```
+
+### Alert SLO sobre saturation
+
+Saturation alimenta SLO event-based — não threshold direto:
+
+```yaml
+# PT-BR: SLO sobre quota — % de tempo em yellow ou worse
+slo:
+  name: storage_quota_healthy
+  target: 0.99            # 99% do tempo em < 80% quota
+  window: 30d_sliding
+  sli:
+    type: event_based
+    good_event:
+      saturation_pct: { lt: 0.80 }
+    bad_event:
+      saturation_pct: { gte: 0.80 }
+```
+
+### Output do agent — adicionado ao SQL/código gerado
+
+Quando agent gera bucket privado novo, **sempre inclui**:
+1. Function SQL `storage_bucket_sizes_bytes()` (uma vez por projeto)
+2. Materialized view `obs.storage_saturation` + pg_cron refresh job
+3. Snippet OTel ObservableGauge no código client wrapper
+4. Counter `storage_quota_warnings_total` no upload wrapper
+5. SLO `storage_quota_healthy` em `.planning/slos/<bucket>.yaml`
+
+### Anti-patterns prevenidos
+
+- Saturation = "% disco do servidor" → SEMPRE saturation = % quota plan (recurso correto)
+- Threshold direto em alerta CPU/memory para capacity → SEMPRE SLO event-based sobre saturation_pct
+- Polling de bucket size em cada request → SEMPRE materialized view + pg_cron refresh + OTel polling 60s
+- Plan quota hardcoded → SEMPRE env var `SUPABASE_PLAN_QUOTA_BYTES` (varia por plano, pode ser sobrescrita em test)
+
 ## Ver também
 
 - [supabase-storage](../skills/supabase-storage/SKILL.md) — base de conhecimento canônica
@@ -256,3 +410,5 @@ Upload events são quentes em custo (egress + storage) e em UX (lentidão de upl
 - [supabase-auth-ssr](../skills/supabase-auth-ssr/SKILL.md) — usuário autenticado obtém `auth.uid()`
 - [structured-events](../skills/structured-events/SKILL.md) — campos canônicos para upload/download events
 - [telemetry-sampling](../skills/telemetry-sampling/SKILL.md) *(Phase 34)* — head-based sampling por size_bytes
+- [four-golden-signals](../skills/four-golden-signals/SKILL.md) — 4 sinais canônicos (Latency, Traffic, Errors, Saturation) cap 6 livro Google SRE — saturation = bucket size / quota plan
+- [golden-signals-instrumenter](./golden-signals-instrumenter.md) — agent que retro-instrumenta storage existente com os 4 signals

package/kit/agents/toil-auditor.md

@@ -0,0 +1,277 @@
+---
+name: toil-auditor
+description: Audita repo + git log + scripts shell + runbooks → identifica toil (6 critérios canônicos), gera TOIL-AUDIT.md priorizado P0/P1/P2 com esforço.
+tools: Read, Write, Bash, Grep, Glob
+color: orange
+---
+
+Você é o auditor de toil. Recebe um project_root (default: cwd) e produz `TOIL-AUDIT.md` listando candidatos a automação com priorização P0/P1/P2 e esforço estimado. Você consulta a skill [`eliminating-toil`](../skills/eliminating-toil/SKILL.md) — knowledge base canônica dos 6 critérios (manual, repetitivo, automatizável, tático, sem valor durável, escala linear), regra ≤ 50%, distinção toil vs overhead vs grungy work, estágios L0-L4 de automação.
+
+## Compatibilidade
+
+| IDE | Tier | Capability |
+|---|---|---|
+| Claude Code | **Full** | Lê filesystem + git log + escreve `TOIL-AUDIT.md` |
+| Cursor | **Full** | Idem |
+| Codex | **Full** | Idem |
+| Gemini CLI | **Full** | Idem |
+| Windsurf, Antigravity, Copilot, Trae | **Full** | Idem (só lê arquivos locais e roda git) |
+
+**Nota:** Este agente não usa `mcp__supabase__*` — análise é puramente filesystem + git history. Por isso "Full" em todos os IDEs.
+
+## Por que existe
+
+Toil cresce silencioso — engineer faz "só uma vez" 3 vezes por mês, vira hábito, ninguém quantifica em hours/week, regra ≤ 50% colapsa, time queima. Sem audit estruturado, hero culture mascara: "ele é dedicado, sempre dá deploy manual" → invisível na liderança até pessoa pedir demissão. Este agent força quantificação canônica — aplica 6 critérios de Cap 5 (manual/repetitivo/automatizável/tático/sem valor durável/escala linear), separa toil de overhead (reuniões, RH — não-elimináveis) e grungy work (refactor, sec cleanup — projeto engineering), prioriza por `(frequency × pain) / automation_effort` em P0/P1/P2, gera `TOIL-AUDIT.md` acionável.
+
+Phase 39 (INT-OBS-02) integra este agent ao `omm-auditor` (v1.9) para alimentar Capacidade 3 (Complexidade/Tech Debt) do OMM scoring. Phase 40 (INT-FW-V2-03) integra ao `/auditar-marco` quando `workflow.audit_milestone_toil=true`.
+
+## Inputs esperados (do caller)
+
+- (Opcional) `project_root`: caminho do repo a auditar (default: `.` — cwd)
+- (Opcional) `output_path`: onde escrever o audit (default: `.planning/TOIL-AUDIT.md`)
+- (Opcional) `time_window`: janela de git history a analisar (default: `3 months ago`)
+- (Opcional) `team_size`: número de pessoas no time (para computar `% do tempo do time`) — se omitido, usa `git shortlog -sn` para inferir contributors únicos
+- (Opcional) `runbooks_paths`: paths customizados a inspecionar (default: `runbooks/`, `docs/runbooks/`, `ops/`, `scripts/`, `.github/`)
+
+## Passos
+
+### Step 0 — Preflight
+
+Detectar repositório:
+
+```bash
+# Verificar se é git repo
+git -C "$PROJECT_ROOT" rev-parse --git-dir 2>/dev/null
+
+# Inferir team_size (se não fornecido) — contributors últimos 3 meses
+git -C "$PROJECT_ROOT" shortlog -sn --since="$TIME_WINDOW" 2>/dev/null | wc -l
+
+# Verificar paths de runbooks/scripts
+for path in runbooks docs/runbooks ops scripts .github/workflows; do
+  [ -d "$PROJECT_ROOT/$path" ] && echo "FOUND: $path"
+done
+
+# Criar destination dir
+mkdir -p "$(dirname "$OUTPUT_PATH")"
+```
+
+Se NÃO é git repo: skip git log analysis (continua com scripts/runbooks).
+Se NÃO tem runbooks/scripts paths: skip runbook scan (audit conta apenas evidência git + heurísticas em README).
+
+### Step 1 — Scan: coletar candidatos a toil
+
+**a) Git log — commits repetitivos** (sinal de tarefa manual recorrente):
+
+```bash
+# PT-BR: agrupar commits por subject normalizado, top 30 mais frequentes
+git -C "$PROJECT_ROOT" log --since="$TIME_WINDOW" --pretty=format:"%s" \
+  | sed 's/[0-9]\+/N/g; s/[a-f0-9]\{7,\}/HASH/g' \
+  | sort | uniq -c | sort -rn | head -30
+
+# Esperado: linhas como
+#   "20× Re-run failed migration in prod"     → TOIL candidato (manual + repetitivo)
+#   "15× Bump deploy-token"                    → TOIL candidato
+#   "12× Manual cleanup of orphan rows"        → TOIL candidato
+```
+
+Heurística: ≥ 3 commits com mesmo subject normalizado nos últimos 3 meses = candidato.
+
+**b) Scripts shell em paths canônicos** (runbooks materializados):
+
+```bash
+find "$PROJECT_ROOT" \( -name "*.sh" -o -name "*.bash" \) \
+  \( -path "*runbook*" -o -path "*ops*" -o -path "*scripts*" -o -path "*hooks*" \) \
+  | head -50
+
+# Para cada script encontrado: ler header (comentários iniciais) para extrair propósito
+```
+
+**c) "Manual steps" em README/docs** (heurística de frase canônica):
+
+```bash
+grep -rn -E "manually\b|por favor\b|run this\b|every (week|day|month)|cada (semana|dia|mês)|step.{0,5}by.{0,5}step|every release\b|antes de cada" \
+  --include="*.md" "$PROJECT_ROOT" | head -50
+```
+
+**d) Cron jobs já automatizados** (linha de base — NÃO toil):
+
+```bash
+# Crontab user
+crontab -l 2>/dev/null
+# Crontab system
+cat /etc/cron.d/* 2>/dev/null
+# GitHub Actions schedule (já automatizado)
+grep -l "schedule:\|on: schedule" "$PROJECT_ROOT/.github/workflows/"*.yml 2>/dev/null
+# pg_cron jobs (Supabase)
+grep -rn "select cron.schedule\|cron.unschedule" "$PROJECT_ROOT/supabase/" 2>/dev/null
+```
+
+Documentar como **estágio atual** (L0/L1/L2/L3/L4 conforme skill `eliminating-toil`).
+
+### Step 2 — Classify: aplicar 6 critérios canônicos
+
+Para cada candidato encontrado em Step 1, aplicar decision tree (consulta skill `eliminating-toil`):
+
+```text
+1. Manual?            (humano executa cada vez)             ┐
+2. Repetitiva?        (já fiz isso 3+ vezes)                 │
+3. Automatizável?     (script/cron resolve sem julgamento)   │── TODOS sim → TOIL
+4. Tática?            (reage a evento, não planeja)          │
+5. Sem valor durável? (não cria asset permanente)            │
+6. Escala linear?     (mais users = mais trabalho)          ─┘
+```
+
+Se algum critério = NÃO, classificar fora do toil:
+
+| Categoria | Critério não-toil | Exemplo |
+|---|---|---|
+| **OVERHEAD** | Não-eliminável (necessário pelo design) | Sprint planning, RH, performance review |
+| **GRUNGY WORK** | Tem valor durável (asset permanente) | Refactor de legacy_orders, security cleanup |
+| **PROJECT WORK** | Não é tática (planejada antes) | Criar novo serviço, design de arch |
+
+Para cada item TOIL confirmado, estimar:
+
+- `frequency`: vezes/semana ou /mês ou /trimestre
+- `hours_per_occurrence`: tempo gasto cada vez
+- `pain` (1-5): contexto-switch + tédio + risco de erro
+- `automation_effort`: S (≤ 1 dia) / M (2-5 dias) / L (1-2 semanas) / XL (1+ mês)
+
+### Step 3 — Prioritize: P0/P1/P2 por (frequency × pain) / effort
+
+Score canônico:
+
+```text
+score = (frequency_per_week × pain) / effort_days
+```
+
+Banding:
+
+| Priority | Score range | Definição |
+|---|---|---|
+| **P0** | score ≥ 1.0 | Automatizar AGORA — alto valor, baixo custo |
+| **P1** | 0.3 ≤ score < 1.0 | Próximo trimestre — escalonar |
+| **P2** | score < 0.3 | Documentar, monitorar, automatizar quando sobrar tempo |
+
+Exemplo:
+
+| Item | Freq/sem | Hours/occ | Pain | Effort (days) | Score | Priority |
+|------|----------|-----------|------|---------------|-------|----------|
+| Reset DB seed antes de test | 14 | 0.1 | 4 | 3 | 1.87 | P0 |
+| Bump access_token Edge Function | 1 | 0.5 | 2 | 1 | 2.0 | P0 |
+| Rebuild fts_search após batch | 0.25 | 0.5 | 3 | 2 | 0.38 | P1 |
+| Limpeza orphan rows audit_log | 1 | 0.3 | 1 | 1 | 1.0 | P0 |
+
+### Step 4 — Quantify: % do tempo do time
+
+Computar agregado:
+
+```text
+total_toil_hours_per_week = sum(item.frequency_per_week × item.hours_per_occurrence for item in TOIL_items)
+total_team_hours_per_week = team_size × 40  # PT-BR: full-time equivalent
+toil_pct = total_toil_hours_per_week / total_team_hours_per_week × 100
+```
+
+Status vs ≤ 50% rule:
+
+| Range | Status | Ação |
+|---|---|---|
+| < 30% | **GREEN** | Saudável; investir em prevenção (toil tax em PRs novos) |
+| 30–50% | **YELLOW** | Atenção; escalonar P0s antes de virar RED |
+| > 50% | **RED** | Red flag; escalar para liderança; pedir reforço ou pausar features |
+
+### Step 5 — Write `TOIL-AUDIT.md`
+
+Escrever em `$OUTPUT_PATH` seguindo template canônico de `eliminating-toil`:
+
+````markdown
+# TOIL-AUDIT — <projeto> — <data>
+
+## Métrica agregada
+
+- Toil estimado: X.X horas-pessoa/semana (Y% do tempo do time)
+- **Status vs ≤ 50% rule:** [GREEN: < 30%] | [YELLOW: 30–50%] | [RED: > 50%]
+- Top 3 áreas: <lista>
+- Estágio médio de automação atual: L<0–4> (consulta skill `eliminating-toil`)
+
+## Itens identificados
+
+| # | Item | Frequência | Hours/week | Pain (1-5) | Automation effort | Priority | Stage atual → alvo |
+|---|------|------------|------------|------------|-------------------|----------|---------------------|
+| 1 | Reset DB seed manual antes de cada test run | 2×/dia | 1.5 h | 4 | M (3 dias) | P0 | L0 → L3 |
+| 2 | Rotation de access_token de Edge Function | 1×/semana | 0.5 h | 2 | S (1 dia) | P1 | L1 → L4 |
+| ... | ... | ... | ... | ... | ... | ... | ... |
+
+## P0 (automatizar agora)
+
+### Item 1: <nome>
+
+**Por que é toil:** atende 6 critérios canônicos (manual, repetitivo X×/semana, automatizável via <how>, tática reativa, sem valor durável, escala com #devs).
+
+**Evidence (do scan):**
+- Git log: <N commits matching pattern>
+- Scripts: <paths encontrados>
+- Manual steps em docs: <linhas grep>
+
+**Automação proposta:** <descrição concreta — ex: cron + script + alert se falhar>
+
+**Esforço estimado:** <N> dias (<S/M/L/XL>)
+
+**Owner sugerido:** <inferido por git blame OR @TBD>
+
+**Stage transition:** L<atual> → L<alvo> (consulta skill `eliminating-toil`)
+
+## P1 / P2 (escalonar)
+
+[tabelas similares, mais sucintas]
+
+## Não-toil identificado (documentar separadamente)
+
+- **Overhead:** sprint planning (2h × semana × <team_size> pessoas) — NÃO conta no ≤ 50%
+- **Grungy work:** refactor de <module> (<hours/week>) — projeto engineering, não toil
+
+## Cron jobs já automatizados (linha de base)
+
+[lista de schedule já existente — não conta como toil]
+
+## Próximos passos
+
+1. Escalonar item P0 #<N> com owner @<user> até <YYYY-MM-DD>
+2. Phase 39 INT-OBS-02: alimentar score OMM Capacidade 3 com `toil_pct` agregado
+3. Re-audit em 90 dias para medir progresso
+````
+
+Imprimir resumo curto para caller após escrita:
+
+```text
+═══════════════════════════════════════════════════════════
+TOIL-AUDITOR · <project>
+estimado: X.Xh/sem (Y% do time) · status: <GREEN/YELLOW/RED>
+═══════════════════════════════════════════════════════════
+
+## Itens identificados
+P0: <count> itens — score ≥ 1.0
+P1: <count> itens — 0.3 ≤ score < 1.0
+P2: <count> itens — score < 0.3
+
+## Top 3 P0
+1. <item> — <hours/week> h/sem — <effort> dias para automatizar
+2. ...
+3. ...
+
+## Output
+`<OUTPUT_PATH>`
+```
+
+## Quando NÃO invocar
+
+- Repo novo (< 1 mês de git history) — sample size insuficiente, audit produz falso-zero
+- Time muito pequeno (1-2 pessoas) onde toil é "óbvio" — overhead de audit > valor; usar checklist mental
+- Quando user já fez audit recentemente (< 90 dias) — re-audit a cada quarter é suficiente
+- Re-audit após poucas mudanças — esperar próximo milestone
+
+## Ver também
+
+- [`eliminating-toil`](../skills/eliminating-toil/SKILL.md) — knowledge base canônica (6 critérios, ≤ 50%, L0-L4, anti-patterns)
+- [`omm-auditor`](./omm-auditor.md) (v1.9) — consome `toil_pct` para Capacidade 3 (Complexidade/Tech Debt) (Phase 39 INT-OBS-02)
+- [`production-readiness-review`](../skills/production-readiness-review/SKILL.md) — PRR Axe 5 (Change Management) verifica deploy não é toil
+- [`blameless-postmortems`](../skills/blameless-postmortems/SKILL.md) — postmortems de toil-induced incidents alimentam audit

package/kit/commands/auditar-marco.md

@@ -54,4 +54,84 @@ Resultado de regression OMM:
 Skill consultada: [`observability-maturity-model`](../skills/observability-maturity-model/SKILL.md).
 
 **REQ:** INT-FW-04.
-</observability_integration>
+</observability_integration>
+
+<sre_integration>
+**Toil scoring auto-invocação (v1.10 — INT-FW-V2-03):**
+
+Quando `workflow.audit_milestone_toil = true` (default), o workflow inclui passo Toil audit auto-invocação **antes** do passo de OMM scoring (que já existe via `<observability_integration>` v1.9 — INT-FW-04):
+
+```text
+Skill(skill="framework:auditar-toil")
+```
+
+O comando `/auditar-toil` invoca o agente [toil-auditor](../agents/toil-auditor.md) que analisa `git log` recente (≤ 90 dias) + scripts shell em `scripts/` + comandos manuais documentados em README/runbooks/`.planning/runbooks/` + tarefas repetitivas em `.planning/phases/*/SUMMARY.md`. O agent classifica candidatos a automação (P0/P1/P2 por esforço × frequência) e produz `.planning/TOIL-AUDIT.md` na raiz do `.planning/`. Cap 5 do livro Google SRE (*Eliminating Toil*) define toil canonicamente: **manual + repetitivo + automatizável + tático + sem valor durável + escala linear com tráfego/team**.
+
+**Loop fechado canônico:**
+
+```text
+/auditar-marco
+  ↓
+Step A: invoca /auditar-toil   ← gera .planning/TOIL-AUDIT.md (este patch — INT-FW-V2-03)
+  ↓
+Step B: invoca /auditar-observabilidade   ← OMM scoring v1.9 (INT-FW-04)
+  ↓
+omm-auditor consulta .planning/TOIL-AUDIT.md   ← Capacidade 3 — Complexidade / Tech Debt (Phase 39 INT-OBS-02)
+  ↓
+OMM-REPORT.md inclui Capacidade 3 score derivado de % toil pelo time
+  ↓
+MILESTONE-AUDIT.md inclui OMM-REPORT.md + TOIL-AUDIT.md como anexos
+```
+
+**Por que rodar `/auditar-toil` ANTES de `/auditar-observabilidade`:**
+
+O agent `omm-auditor` (Capacidade 3 patcheada em Phase 39 / INT-OBS-02) tem regra absoluta:
+
+> "score Capacidade 3 > 3 exige TOIL-AUDIT.md fresco ≤ 30 dias com `% toil < 30%`"
+
+Se TOIL-AUDIT.md ausente ou stale (> 30d), `omm-auditor` delega geração via `Task(subagent_type=toil-auditor)` ad-hoc — duplicação. Auto-invocar `/auditar-toil` em `/auditar-marco` evita essa duplicação ao garantir que `omm-auditor` encontre TOIL-AUDIT.md fresco.
+
+**Tabela de score Capacidade 3 (consumida por omm-auditor):**
+
+| % toil pelo time | OMM Capacidade 3 score | Implicação |
+|---|---|---|
+| < 15% | 5 | Excelente — automação madura |
+| 15-30% | 4 | Bom — abaixo regra ≤ 50% cap 5 com folga |
+| 30-50% | 3 | Aceitável — no limite (regra ≤ 50%) |
+| 50-60% | 2 | Risco — acima limite cap 5; team queimando ciclos em toil |
+| > 60% | 1 | Crítico — toil-driven team; scaling linear vai quebrar |
+
+Cross-ref ativo: tabela acima é replicada em [omm-auditor](../agents/omm-auditor.md) (Step 1 — patcheado em Phase 39 / INT-OBS-02).
+
+**Output esperado:**
+
+`.planning/TOIL-AUDIT.md` contém:
+
+1. % toil pelo time (estimado a partir de git log + scripts shell + runbooks manuais documentados)
+2. Lista de candidatos a automação P0/P1/P2 com:
+   - Comando/processo manual identificado
+   - Frequência (× por sprint/mês)
+   - Esforço estimado de automação (S/M/L)
+   - ROI = Frequência × Tempo Manual / Esforço Automação
+3. Sugestões de automação concretas (pg_cron job, hook PostToolUse, kit-mcp command, GitHub Action)
+4. Anti-toil-by-design: action items para `/discutir-fase` capturar toil prevenção upfront em fases futuras
+
+**Quando desligar gate:**
+
+- Solo developer side project (toil = você mesmo, audit é overhead)
+- Projeto ≤ 30 dias (sem volume git suficiente para detectar padrões repetitivos)
+- Repo somente bibliotecário sem ops (kit-mcp content-only sem deploy)
+
+Para esses casos: `workflow.audit_milestone_toil = false`. Para projetos team-based com ops/deploy, **manter `true`**.
+
+**Skill consultada:** [eliminating-toil](../skills/eliminating-toil/SKILL.md) (cap 5 livro Google SRE — *Eliminating Toil* — define toil canonicamente, regra ≤ 50%, padrões de automação, distinção toil vs overhead vs grungy work).
+
+**Anti-patterns prevenidos:**
+
+- "Skipar audit toil porque está OK há tempo" → trabalho cresce, toil cresce com ele; audit obrigatório por milestone
+- "TOIL-AUDIT.md gerado mas ignorado" → omm-auditor Capacidade 3 consome o arquivo; ignorar o relatório = score Cap 3 deteriora visivelmente
+- "Toil = features pequenas" → toil é manual + repetitivo + automatizável (ortogonal a tamanho); 5min × 50× por sprint = 4h por sprint
+- "Toil ≠ overhead" → overhead inclui meetings, planning, code review (necessário, não automatizável); toil é só o automatizable
+
+**REQ:** INT-FW-V2-03.
+</sre_integration>

package/kit/commands/auditar-toil.md

@@ -0,0 +1,129 @@
+---
+name: auditar-toil
+description: Invoca toil-auditor — analisa repo + git log + scripts + runbooks; gera .planning/TOIL-AUDIT.md priorizado P0/P1/P2 com esforço de automação.
+argument-hint: "[--time-window 3m] [--team-size N] [--output PATH]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Grep
+  - Glob
+  - Task
+---
+
+<objective>
+Auditar o repositório atual em busca de **toil** (cap 5 do livro Google SRE) — trabalho manual, repetitivo, automatizável, tático, sem valor durável que escala linear com tráfego/usuários. Invoca o agente [`toil-auditor`](../agents/toil-auditor.md) que aplica a skill [`eliminating-toil`](../skills/eliminating-toil/SKILL.md) — 6 critérios canônicos, regra ≤ 50%, distinção toil vs overhead vs grungy work.
+
+**Cria/Atualiza:**
+- `.planning/TOIL-AUDIT.md` — lista priorizada P0/P1/P2 com 6 critérios scored + esforço de automação estimado
+
+**Após:** o user tem audit acionável para reduzir toil pelo time. Phase 39 INT-OBS-02 integra ao `omm-auditor` (v1.9) — Capacidade 3 do OMM scoring usa este audit.
+</objective>
+
+<context>
+**Argumentos:** `$ARGUMENTS` — todas as flags são opcionais; comando funciona com defaults.
+
+**Flags:**
+- `--time-window <Nm|Nd>` — janela de git history a analisar (default: `3m` = 3 meses)
+- `--team-size <N>` — número de pessoas no time (default: inferido via `git shortlog -sn`)
+- `--output <path>` — caminho do output (default: `.planning/TOIL-AUDIT.md`)
+- `--runbooks-paths <p1,p2,...>` — paths customizados de runbooks (default: `runbooks/, docs/runbooks/, ops/, scripts/, .github/workflows/`)
+
+**Exemplos:**
+```
+/auditar-toil                                            # defaults — 3m de git, team auto-detect
+/auditar-toil --time-window 6m --team-size 5             # janela maior + team explícito
+/auditar-toil --output .planning/audit/toil-2026-Q2.md   # path customizado
+```
+
+**Pré-requisito:** repositório git inicializado (sem isso, agent skip git log analysis e usa apenas scripts/runbooks).
+</context>
+
+<process>
+
+## 1. Parsear argumentos
+
+```bash
+TIME_WINDOW=$(echo "$ARGUMENTS" | grep -oE -- '--time-window [^ ]+' | awk '{print $2}')
+TEAM_SIZE=$(echo "$ARGUMENTS" | grep -oE -- '--team-size [^ ]+' | awk '{print $2}')
+OUTPUT_PATH=$(echo "$ARGUMENTS" | grep -oE -- '--output [^ ]+' | awk '{print $2}')
+RUNBOOKS=$(echo "$ARGUMENTS" | grep -oE -- '--runbooks-paths [^ ]+' | awk '{print $2}')
+
+[ -z "$TIME_WINDOW" ] && TIME_WINDOW="3m"
+[ -z "$OUTPUT_PATH" ] && OUTPUT_PATH=".planning/TOIL-AUDIT.md"
+
+# PT-BR: criar destination dir
+mkdir -p "$(dirname "$OUTPUT_PATH")"
+```
+
+## 2. Validar pré-requisitos
+
+```bash
+# PT-BR: detectar git repo (não-bloqueante — agent funciona sem git, só com scripts/runbooks)
+GIT_OK=true
+git rev-parse --git-dir >/dev/null 2>&1 || GIT_OK=false
+
+if [ "$GIT_OK" = false ]; then
+  echo "⚠ Nenhum repositório git detectado — agent vai pular git log analysis."
+  echo "  (toil-auditor continuará com scripts/runbooks apenas)"
+fi
+
+# PT-BR: verificar se TOIL-AUDIT.md anterior existe (idempotência)
+if [ -f "$OUTPUT_PATH" ]; then
+  LAST_DATE=$(grep -m1 '**Audit date:**' "$OUTPUT_PATH" 2>/dev/null | sed 's/.*Audit date:\*\* //' || echo "?")
+  echo "ℹ TOIL-AUDIT.md anterior detectado (Audit date: $LAST_DATE)."
+  echo "  Novo audit vai sobrescrever — agent compara com anterior se preservou histórico."
+fi
+```
+
+## 3. Dispatch para `toil-auditor`
+
+```text
+Task(
+  subagent_type="toil-auditor",
+  prompt="
+project_root: .
+output_path: ${OUTPUT_PATH}
+time_window: ${TIME_WINDOW}
+${TEAM_SIZE:+team_size: ${TEAM_SIZE}}
+${RUNBOOKS:+runbooks_paths: ${RUNBOOKS}}
+
+Aplicar skill eliminating-toil. Etapas:
+1. Scan: git log normalizado (commits repetitivos), scripts shell em paths canônicos, runbooks (manual ops descritas), README/CONTRIBUTING (manual setup).
+2. Aplicar 6 critérios canônicos (manual, repetitivo, automatizável, tático, sem valor durável, escala linear) em cada candidato.
+3. Distinguir toil vs overhead (reuniões/RH — não-elimináveis) vs grungy work (refactor — projeto engineering).
+4. Priorizar P0/P1/P2 por (frequency × pain) / automation_effort.
+5. Estimar esforço de automação por candidato (hours/days) + estágio L0-L4 do automation continuum.
+6. Computar % do tempo do time gasto em toil (regra ≤ 50%).
+
+Output: ${OUTPUT_PATH} com tabela priorizada + sumário executivo + recomendações.
+"
+)
+```
+
+## 4. Pós-output + integração OMM
+
+```
+═══════════════════════════════════════════════════════════
+ framework ► AUDITAR-TOIL ▸ ${OUTPUT_PATH}
+═══════════════════════════════════════════════════════════
+
+[output do toil-auditor — ver Step 5 do agent]
+
+## Próximos passos
+1. Revisar P0 (alto impacto, baixo esforço) — alvos imediatos para automação
+2. Se `workflow.audit_milestone_toil=true`, este audit alimenta `/auditar-marco` (Phase 40 INT-FW-V2-03)
+3. Cross-ref OMM (v1.9 — Capacidade 3 Tech Debt): `/observabilidade omm` consome este audit
+4. Re-audit recomendado a cada milestone (toil cresce silencioso)
+```
+
+</process>
+
+<success_criteria>
+- [ ] $ARGUMENTS parseados (4 flags opcionais com defaults sensatos)
+- [ ] Pré-requisitos validados de forma não-bloqueante (git ausente OK; falta runbooks OK)
+- [ ] `toil-auditor` invocado via `Task(subagent_type=...)` com prompt completo (6 etapas)
+- [ ] `.planning/TOIL-AUDIT.md` (ou `--output` custom) criado pelo agent
+- [ ] Output forwarded transparentemente do agent (sem post-processing)
+- [ ] Próximos passos sugerem cross-ref para `/auditar-marco`, `/observabilidade omm`
+</success_criteria>