@luanpdd/kit-mcp 1.8.1 → 1.10.0

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

@@ -33,4 +33,105 @@ Glob: .planning/phases/*/*-VERIFICATION.md
 <process>
 Execute o workflow audit-milestone de @./.claude/framework/workflows/audit-milestone.md do início ao fim.
 Preserve todos os checkpoints do workflow (determinação de escopo, leitura de verificações, checagem de integração, cobertura de requisitos, roteamento).
-</process>
+</process>
+
+<observability_integration>
+**OMM scoring (v1.9 — INT-FW-04):**
+
+Quando `workflow.audit_milestone_omm = true` (default), o workflow inclui passo OMM scoring:
+
+```text
+Skill(skill="framework:auditar-observabilidade")
+```
+
+O comando `/auditar-observabilidade` invoca o agente [`omm-auditor`](../agents/omm-auditor.md) que pontua as 5 capacidades (resiliência, qualidade, complexidade, cadência, comportamento) contra o marco anterior. O OMM-REPORT.md gerado é incluído como anexo no MILESTONE-AUDIT.md.
+
+Resultado de regression OMM:
+- **0 regressions:** audit aprovado
+- **1+ regressions, blocking=false:** warn explícito; audit aprovado com nota
+- **1+ regressions, blocking=true (`workflow.omm_no_regression=true`):** audit fail → user escolha entre fix lacunas ou aceitar
+
+Skill consultada: [`observability-maturity-model`](../skills/observability-maturity-model/SKILL.md).
+
+**REQ:** INT-FW-04.
+</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-observabilidade.md

@@ -0,0 +1,103 @@
+---
+name: auditar-observabilidade
+description: Invoca omm-auditor para gerar OMM-REPORT.md scored. 5 capacidades com trend vs marco anterior. Action items priorizados P0-P3.
+argument-hint: "[--previous <marco>] [--ci]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Task
+---
+
+<objective>
+Gerar OMM-REPORT.md com snapshot scored das 5 capacidades de observabilidade. Aplica skill [`observability-maturity-model`](../skills/observability-maturity-model/SKILL.md) — sintomas qualitativos doing well/poorly por capacidade.
+
+**Cria/Atualiza:**
+- `.planning/OMM-REPORT.md` — snapshot atual
+- (Em `/concluir-marco`) `.planning/milestones/<v>/OMM-REPORT.md` — snapshot arquivado
+
+**Após:** time tem 5 scores + trend + action items priorizados.
+</objective>
+
+<context>
+**Argumentos:** `$ARGUMENTS`
+
+**Flags:**
+- `--previous <marco>` — comparar com marco específico (default: detecta automaticamente do MILESTONES.md)
+- `--ci` — modo CI: exit code 0 se OK, 1 se regression em qualquer capacidade
+
+**Quando rodar:**
+- Manualmente para snapshot informal
+- Em `/auditar-marco` (audit pre-conclusion) — Phase 35 INT-FW-04
+- Em `/concluir-marco` (gate de regression) — Phase 35 INT-FW-05
+</context>
+
+<process>
+
+## 1. Parsear argumentos
+
+```bash
+PREVIOUS=$(echo "$ARGUMENTS" | grep -oE -- '--previous [^ ]+' | awk '{print $2}')
+CI_MODE=$(echo "$ARGUMENTS" | grep -c -- '--ci' || true)
+```
+
+## 2. Detectar previous milestone
+
+```bash
+if [ -z "$PREVIOUS" ]; then
+  # PT-BR: extrair último concluído de MILESTONES.md
+  PREVIOUS=$(grep -E '^### v[0-9.]+\b' .planning/MILESTONES.md | head -2 | tail -1 | grep -oE 'v[0-9.]+')
+fi
+```
+
+## 3. Dispatch para `omm-auditor`
+
+```text
+Task(
+  subagent_type="omm-auditor",
+  prompt="
+${PREVIOUS:+previous_milestone: ${PREVIOUS}}
+mode: ${CI_MODE:+ci}snapshot
+
+Gerar OMM-REPORT.md com:
+1. Score 1-5 por capacidade (5 capacidades)
+2. Trend vs ${PREVIOUS:-último marco}
+3. Action items priorizados P0-P3
+4. Regression alerts (se alguma capacidade regrediu)
+5. Comparação por marco
+"
+)
+```
+
+## 4. Pós-output
+
+```
+═══════════════════════════════════════════════════════════
+ framework ► AUDITAR-OBSERVABILIDADE
+═══════════════════════════════════════════════════════════
+
+[output do omm-auditor — snapshot inline]
+
+OMM-REPORT.md: .planning/OMM-REPORT.md
+
+${CI_MODE:+## CI Mode}
+${CI_MODE:+Exit code: 0 (OK) / 1 (regression detectada)}
+```
+
+## 5. Modo `--ci`
+
+Se `--ci` setado:
+- Parse OMM-REPORT.md para detectar regression alerts
+- Se ≥ 1 regression → exit 1 (CI fails)
+- Senão → exit 0 (OK)
+
+</process>
+
+<success_criteria>
+- [ ] omm-auditor invocado via Task
+- [ ] OMM-REPORT.md gerado em `.planning/OMM-REPORT.md`
+- [ ] 5 capacidades scored
+- [ ] Trend calculado vs `--previous` ou auto-detectado
+- [ ] Action items P0-P3 listados
+- [ ] Modo `--ci` exit code apropriado se regression
+</success_criteria>

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>