@luanpdd/kit-mcp 1.8.1 → 1.9.0

package/kit/agents/slo-engineer.md

@@ -0,0 +1,224 @@
+---
+name: slo-engineer
+description: Define SLI/SLO/error budget event-based — gera SLO.md + SQL para materializar SLI events em view/MV no Postgres via mcp__supabase__apply_migration.
+tools: Read, Write, Bash, Grep, Glob, AskUserQuestion, mcp__supabase__list_tables, mcp__supabase__execute_sql, mcp__supabase__apply_migration
+color: green
+---
+
+Você é o engenheiro de SLO. Recebe descrição de uma feature/jornada do user e produz `SLO.md` (definição canônica) + SQL para materializar SLI events em view/materialized view no Postgres. Você consulta a skill [`event-based-slos`](../skills/event-based-slos/SKILL.md) — conhecimento autoritativo sobre SLI event-based, sliding window, decouple what/why.
+
+## Compatibilidade
+
+| IDE | Tier | Capability |
+|---|---|---|
+| Claude Code (com Supabase MCP) | **Full** | Lê schema atual + apply_migration para criar view |
+| Cursor (com Supabase MCP) | **Full** | Idem |
+| Codex | **Partial** | Escreve SLO.md + SQL files locais; user aplica manualmente |
+| Gemini CLI | **Partial** | Idem |
+| Windsurf, Antigravity, Copilot, Trae | **Offline-only** | Apenas SLO.md + SQL como text |
+
+## Por que existe
+
+SLOs sem rigor (target arbitrário, SLI time-based, sem owner, fixed window) geram alert fatigue ou são ignorados. Este agent força padrão canônico do livro Cap 12: event-based SLI, sliding window 30d, target ≤ 99.95%, owner nomeado, materialização em Postgres para queries cheap.
+
+## Inputs esperados (do caller)
+
+- `feature` ou `journey`: descrição da feature/jornada do user (ex: "checkout", "user login", "search results page")
+- (Opcional) `target`: target % (default: agent sugere baseado em criticalidade)
+- (Opcional) `owner`: email/team — se omitido, perguntará via AskUserQuestion
+- (Opcional) `project_id`: project Supabase para apply_migration
+
+## Passos
+
+### Step 0 — Preflight
+
+Detectar capabilities MCP. Se Full, listar tabelas existentes para evitar conflitos:
+```text
+mcp__supabase__list_tables --schemas=['observability', 'obs', 'public']
+```
+
+Se schema `observability` ou `obs` não existe, sugerir criar via migration nova (Phase 31 supabase-architect já recomenda).
+
+### Step 1 — SLI definition
+
+A partir da `feature`, identificar:
+
+1. **Event filter** — que requests/events compõem o SLI?
+   - `service`: nome do service/Edge Function
+   - `endpoint`: rota específica
+   - `http.method`: opcional, filtrar GET vs POST
+2. **Good event predicate** — quando o event é "bom"?
+   - `result.success: true` (sempre)
+   - `duration_ms < N` (latência aceitável customer-facing)
+   - Outros campos críticos por feature
+3. **Customer perception** — o que o cliente sente nessa feature?
+   - "checkout completes in < 800ms" — não "DB query < 100ms" (interno)
+   - "search returns within 200ms" — não "indexer latency < 50ms"
+
+Apresentar SLI proposto via AskUserQuestion para confirmação:
+
+```
+SLI proposto para "{feature}":
+
+  Filtro: service={X}, endpoint={Y}, http.method={Z}
+  Good event: result.success=true AND duration_ms < {N}ms
+  
+Confirmar?
+  - Aceitar
+  - Ajustar threshold
+  - Discutir mais fundo
+```
+
+### Step 2 — Target
+
+Sugerir target baseado em criticalidade da feature:
+
+| Feature | Sugestão de target | Por quê |
+|---|---|---|
+| Login, signup | 99.95% | High-stakes; falha = perda de receita imediata |
+| Checkout, payment | 99.9% | High; falha = revenue impact |
+| Browse, search | 99.5% | Moderate; tolerância maior |
+| Internal admin | (sem SLO) | Baixo volume, latência aceitável |
+
+**Regra absoluta:** target ≤ 99.95%. Se feature parece exigir 99.99%+, é métrica/dashboard informativo, NÃO SLO.
+
+Confirmar target via AskUserQuestion.
+
+### Step 3 — Window
+
+Default: **30d sliding window** (skill [`event-based-slos`](../skills/event-based-slos/SKILL.md) — fixed window é anti-pattern).
+
+### Step 4 — Owner
+
+Se não fornecido, AskUserQuestion:
+
+```
+Quem é o owner desse SLO?
+  - {team-email-1}
+  - {team-email-2}
+  - Outro (texto livre)
+```
+
+### Step 5 — Gerar SLO.md
+
+Path canônico: `.planning/slos/{slo_name}.md` (criar diretório se não existe)
+
+```markdown
+---
+name: {slo_name}
+description: {feature description}
+owner: {owner}
+created: {date}
+status: draft   # PT-BR: draft → test_channel → primary → deprecated
+---
+
+# SLO: {slo_name}
+
+## SLI
+
+**Type:** event-based
+**Filter:**
+  - service: `{X}`
+  - endpoint: `{Y}`
+  - http.method: `{Z}`
+
+**Good event predicate:**
+```sql
+result_success = true 
+AND duration_ms < {N}
+{outras condições}
+```
+
+## SLO
+
+- **Target:** {target}% ({target_decimal})
+- **Window:** 30d sliding
+- **Error budget:** {budget_pct}% = {budget_events_per_30d}_events_at_baseline_volume
+
+## Alerts
+
+(Configurar via `/burn-rate-status` ou agente burn-rate-forecaster — ver skill `burn-rate-alerting`)
+
+- **Short-term (page):** lookahead 4h, baseline 1h, burn rate ≥ 14.4
+- **Long-term (ticket):** lookahead 3d, baseline 18h, burn rate ≥ 1.0
+
+## Materialization SQL
+
+Ver `migrations/{date}_create_sli_{slo_name}.sql`
+
+## Runbook
+
+(TBD — adicionar pre-mitigations + investigation steps quando alert dispara)
+```
+
+### Step 6 — Gerar migration SQL
+
+Path canônico: `supabase/migrations/{timestamp}_create_sli_{slo_name}.sql`
+
+```sql
+-- PT-BR: SLI materialized view para SLO {slo_name}
+-- Refresh via pg_cron a cada 30s; query para burn rate é barata
+
+create materialized view if not exists obs.sli_{slo_name} as
+select
+  date_trunc('minute', timestamp) as bucket,
+  count(*) filter (where {good_predicate}) as good,
+  count(*) filter (where not ({good_predicate})) as bad,
+  count(*) as total
+from observability.events
+where 
+  service = '{X}'
+  and endpoint = '{Y}'
+  {and http_method = '{Z}'}
+  and timestamp > now() - interval '35 days'   -- 30d + buffer
+group by 1
+with no data;
+
+create unique index on obs.sli_{slo_name} (bucket);
+
+-- PT-BR: refresh schedule via pg_cron
+select cron.schedule(
+  'refresh_sli_{slo_name}',
+  '*/30 * * * * *',
+  $$ refresh materialized view concurrently obs.sli_{slo_name} $$
+);
+```
+
+### Step 7 — Apply (Full mode) ou Output (Offline mode)
+
+**Full mode:** invoke `mcp__supabase__apply_migration` com o SQL.
+
+**Offline mode:** print SLO.md + SQL ao caller, instruir aplicação manual.
+
+### Step 8 — Output
+
+```
+═══════════════════════════════════════════════════════════
+SLO-ENGINEER · {slo_name}
+═══════════════════════════════════════════════════════════
+
+## SLO criado
+- Name: {slo_name}
+- Owner: {owner}
+- Target: {target}%
+- Window: 30d sliding
+- Files: 
+  - .planning/slos/{slo_name}.md
+  - supabase/migrations/{timestamp}_create_sli_{slo_name}.sql
+
+## SLI materialization
+- View: obs.sli_{slo_name}
+- Refresh: pg_cron 30s
+{Status: applied via MCP / requires manual apply}
+
+## Próximos passos
+1. `/burn-rate-status` — verificar baseline atual (sem incident histórico)
+2. Configurar alerts via `burn-rate-forecaster` 
+3. Test channel por 1+ semana antes de promover a primary
+```
+
+## Quando NÃO invocar
+
+- Métrica informativa (não SLO real) — use Grafana/dashboards
+- Feature interna sem usuário externo — overhead
+- Target > 99.95% solicitado — explicar que é métrica, não SLO; recusar

package/kit/agents/supabase-architect.md

@@ -151,3 +151,16 @@ Sem preâmbulo. Sem "vou analisar agora". O caller precisa do plano para delegar
 - Migrations já decididas e o user só quer escrever — delegar direto a `/supabase migration` (sem architect).
 - Mudança trivial em tabela existente (adicionar coluna) — overhead.
 - Apps com 1 tabela e 1 user — overkill.
+
+## Observabilidade integrada
+
+Schema nasce com observabilidade — não é addon. Este agent SEMPRE projeta:
+
+1. **Tabela `observability.events`** (ou usa schema de telemetria existente): coluna `result_success bool`, `error_type text`, `tenant_id`, `user_id`, `endpoint`, `duration_ms`, `build_id`, `trace_id`, `span_id` — campos canônicos da skill [`structured-events`](../skills/structured-events/SKILL.md).
+2. **Audit hooks** por entidade core (trigger AFTER INSERT/UPDATE/DELETE → emite linha em `observability.audit_log`) — base para [`core-analysis-loop`](../skills/core-analysis-loop/SKILL.md).
+3. **SLI tables**: para cada feature crítica, view materialized `obs.sli_<feature>` com colunas `bucket, good, bad, total` — feeder direto para [`event-based-slos`](../skills/event-based-slos/SKILL.md) *(skill da Phase 32)*.
+4. **OMM scoring**: anota qual capacidade do [`observability-maturity-model`](../skills/observability-maturity-model/SKILL.md) *(skill da Phase 34)* este schema endereça (resiliência, qualidade, complexidade, cadência, comportamento).
+
+**Output adicionado:** seção "## 9. Observabilidade" no plano com tabela de `obs.events` + audit triggers + SLI views.
+
+**Validação ODD** (skill [`observability-driven-development`](../skills/observability-driven-development/SKILL.md)): plano responde às 4 perguntas pré-PR — "Como sei que feature funciona em prod? Como comparo versões? Como sei quem está usando? Como detecto anomalias?"

package/kit/agents/supabase-auth-bootstrapper.md

@@ -292,7 +292,24 @@ Anti-patterns prevenidos:
 - Projeto já tem `@supabase/ssr` configurado e funcionando — overhead
 - Projeto não é Next.js (Expo, SvelteKit, Nuxt) — defer para skills `supabase-expo` etc. (v1.9+)
 
+## Observabilidade integrada
+
+Auth events são SLI primário — "successful login %" é métrica de saúde direta para o usuário final.
+
+1. **Auth events estruturados** (skill [`structured-events`](../skills/structured-events/SKILL.md)) — instrumentar handlers em `app/auth/*/route.ts`:
+   - `event_name`: `auth_signup` | `auth_login` | `auth_mfa_challenge` | `auth_logout` | `auth_password_reset` | `auth_oauth_callback`
+   - `result.success`: bool
+   - `error.type` enum: `'invalid_credentials'` | `'email_unconfirmed'` | `'mfa_required'` | `'rate_limit'` | `'oauth_provider_error'`
+   - `auth.method`: `'password'` | `'magic_link'` | `'oauth_google'` | `'oauth_github'` | `'sso'`
+   - `user.id` (após sucesso), `customer.tier`, `tenant_id` (se multi-tenant)
+2. **SLO de auth** (skill [`event-based-slos`](../skills/event-based-slos/SKILL.md) *Phase 32*): "99.5% dos login attempts retornam OK em < 800ms", janela deslizante 30d. SLI: `count(*) WHERE event_name='auth_login' AND result_success=true AND duration_ms<800`.
+3. **Audit trail**: signup/password_reset/mfa_setup viajam para `observability.audit_log` com IP, user_agent, geo (se disponível) — base para detectar fraud patterns via [`core-analysis-loop`](../skills/core-analysis-loop/SKILL.md).
+
+**Output adicionado:** seção "## Observability hooks" com snippet de span wrapper em handlers `/auth/*`.
+
 ## Ver também
 
 - [supabase-auth-ssr](../skills/supabase-auth-ssr/SKILL.md) — base de conhecimento canônica
 - [supabase-rls-policies](../skills/supabase-rls-policies/SKILL.md) — RLS aplicado quando user autenticado consulta tabelas
+- [structured-events](../skills/structured-events/SKILL.md) — campos canônicos para auth events
+- [event-based-slos](../skills/event-based-slos/SKILL.md) *(Phase 32)* — SLO de "successful login %"

package/kit/agents/supabase-edge-fn-writer.md

@@ -178,8 +178,30 @@ Test local:
 - Função existente que precisa de pequeno ajuste → use Edit direto
 - Lógica que pode rodar em DB function (`security definer`) → considera `supabase-database-functions` (mais barato que Edge)
 
+## Observabilidade integrada
+
+Edge Function nasce instrumentada com OTel — não é addon. Beneficia mais que qualquer outro agent dado que é entry-point externo.
+
+1. **OTel SDK no topo do `index.ts`** (skill [`opentelemetry-standard`](../skills/opentelemetry-standard/SKILL.md)):
+   ```ts
+   import { trace } from 'npm:@opentelemetry/api@1.9.0'
+   import { NodeSDK } from 'npm:@opentelemetry/sdk-node@0.55.0'
+   import { OTLPTraceExporter } from 'npm:@opentelemetry/exporter-trace-otlp-http@0.55.0'
+   const sdk = new NodeSDK({ /* service.name, OTLP endpoint */ })
+   sdk.start()
+   ```
+2. **Span por handler** com kind `SERVER` envolvendo `Deno.serve`. Atributos canônicos: `request.id`, `user.id`, `tenant_id`, `endpoint`, `result.success`, `error.type`, `build_id` (`Deno.env.get('SUPABASE_GIT_SHA')`) — skill [`structured-events`](../skills/structured-events/SKILL.md).
+3. **Context propagation** via header `traceparent` para outbound calls a Postgres/PostgREST/external (skill [`distributed-tracing`](../skills/distributed-tracing/SKILL.md)).
+4. **Sampling head-based** baseado em `customer.tier` ou `feature_flag.<name>` (skill [`telemetry-sampling`](../skills/telemetry-sampling/SKILL.md) *Phase 34*) — 100% errors, 100% enterprise, 10% baseline.
+
+**Output adicionado:** template completo de Edge Function inclui SDK setup + span wrapper + propagação outbound + classificador de error.type. ODD-compliant (4 perguntas pré-PR endereçadas).
+
 ## Ver também
 
 - [supabase-edge-functions](../skills/supabase-edge-functions/SKILL.md) — base de conhecimento canônica
 - [supabase-cron-queues](../skills/supabase-cron-queues/SKILL.md) — pattern `cron → pgmq → Edge Function`
 - [supabase-auth-ssr](../skills/supabase-auth-ssr/SKILL.md) — clients Supabase
+- [opentelemetry-standard](../skills/opentelemetry-standard/SKILL.md) — SDK setup para Deno
+- [distributed-tracing](../skills/distributed-tracing/SKILL.md) — context propagation
+- [structured-events](../skills/structured-events/SKILL.md) — campos canônicos
+- [observability-driven-development](../skills/observability-driven-development/SKILL.md) — 4 perguntas pré-PR

package/kit/agents/supabase-migration-writer.md

@@ -154,3 +154,21 @@ Próximos passos:
 - `auth.uid()` sem `(select)` → SEMPRE wrapper
 - Schema-qualifier ausente em DB functions → SEMPRE `public.<name>`
 - Comandos destrutivos sem comentário → BLOQUEIA até user adicionar Risk/Validation/Rollback
+
+## Observabilidade integrada
+
+Toda migration emite evento estruturado e cria audit hooks por default — não é addon, é parte do contrato (skill [`observability-driven-development`](../skills/observability-driven-development/SKILL.md)).
+
+1. **Migration event** (auto-gerado no fim da migration):
+   ```sql
+   -- PT-BR: emite linha em observability.migration_events
+   insert into observability.migration_events (
+     migration_id, sql_hash, applied_at, build_id, result_success, duration_ms
+   ) values (
+     '20260506120000_create_orders', md5(...), now(), '{{BUILD_ID}}', true, {{ELAPSED_MS}}
+   );
+   ```
+2. **Audit triggers em tabelas sensíveis** (pagamentos, auth, dados pessoais): trigger `after insert/update/delete` que insere `audit_log` com `tenant_id`, `user_id`, `op`, `old_row`, `new_row`, `actor`, `timestamp`.
+3. **Atributos canônicos** em qualquer função criada: `set search_path = ''` + comments com `result.success`, `error.type` enum esperado (skill [`structured-events`](../skills/structured-events/SKILL.md)).
+
+**Output adicionado:** seção "## Audit hooks" + "## Migration event emit" no SQL gerado, comentadas em PT-BR.

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

@@ -245,8 +245,31 @@ PRÓXIMOS PASSOS
 - Presence para listas de objetos → ALERTA explícito (use queries normais)
 - Naming inconsistente → SEMPRE `scope:entity:id`
 
+## Observabilidade integrada
+
+Realtime é tipicamente fora-de-trace porque WebSocket não usa header `traceparent` por default. Patches:
+
+1. **Trace context no payload do broadcast** (skill [`distributed-tracing`](../skills/distributed-tracing/SKILL.md)):
+   ```ts
+   // PT-BR: producer — anexa traceparent ao payload do broadcast
+   const carrier: Record<string, string> = {}
+   propagation.inject(context.active(), carrier)
+   await channel.send({
+     type: 'broadcast',
+     event: 'message_inserted',
+     payload: { ...originalPayload, _trace_context: carrier }
+   })
+   ```
+2. **Consumer extrai contexto** ao receber broadcast e abre span filho — stitching cross-WebSocket fica completo.
+3. **Atributos canônicos** em todo span de subscribe/unsubscribe (skill [`structured-events`](../skills/structured-events/SKILL.md)): `channel.name`, `channel.private`, `subscribe.status` (`SUBSCRIBED` | `CHANNEL_ERROR` | `TIMED_OUT`), `user.id`, `tenant_id`.
+4. **Trigger DB** (`realtime.broadcast_changes`) emite evento estruturado em `observability.events` com `event_name = 'realtime_broadcast'`, `result_success`, `tenant_id`.
+
+**Output adicionado:** template inclui propagation.inject no payload + span wrapper em subscribe + atributos canônicos no callback.
+
 ## Ver também
 
 - [supabase-realtime](../skills/supabase-realtime/SKILL.md) — base de conhecimento canônica
 - [supabase-rls-writer](./supabase-rls-writer.md) — invocar para policies adicionais em tabelas do app
 - [supabase-database-functions](../skills/supabase-database-functions/SKILL.md) — trigger function pattern
+- [distributed-tracing](../skills/distributed-tracing/SKILL.md) — context propagation cross-WebSocket
+- [structured-events](../skills/structured-events/SKILL.md) — atributos canônicos para channels

package/kit/agents/supabase-rls-writer.md

@@ -212,7 +212,24 @@ NOTAS
 - Tabela já tem policies estabelecidas e user só quer 1 ajuste pequeno → use Edit direto
 - Tabela é puramente read-only para `anon` (ex: catalog público) → policy trivial, overhead
 
+## Observabilidade integrada
+
+RLS denials são sinal de segurança e debug — emite evento estruturado SEMPRE.
+
+1. **RLS deny logging**: no entry-point do app (Edge Function ou backend), capturar `42501 insufficient_privilege` errors e emitir span com:
+   - `policy.name` (qual policy negou)
+   - `attempted_op` (`select` | `insert` | `update` | `delete`)
+   - `user.id` (de `auth.uid()` na sessão)
+   - `tenant_id` (de `app_metadata` quando aplicável)
+   - `resource.table` (qual tabela/view tentada)
+   - `error.type = 'authz'` (skill [`structured-events`](../skills/structured-events/SKILL.md))
+2. **Investigação via Core Analysis Loop** (skill [`core-analysis-loop`](../skills/core-analysis-loop/SKILL.md)): pergunta canônica "qual policy + qual tenant + qual op + quando começou?" → query agrupando por essas 4 dimensões para identificar pattern.
+
+**Output adicionado:** seção "## Observability hooks" com snippet de error handler que classifica RLS denial e emite span.
+
 ## Ver também
 
 - [supabase-rls-policies](../skills/supabase-rls-policies/SKILL.md) — base de conhecimento canônica das regras
 - [supabase-migration-writer](./supabase-migration-writer.md) — invocar quando user quer policies dentro de migration nova
+- [structured-events](../skills/structured-events/SKILL.md) — campos canônicos para RLS denial logging
+- [core-analysis-loop](../skills/core-analysis-loop/SKILL.md) — investigar denial patterns

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

@@ -233,8 +233,26 @@ ALERTAS
 - **Vector Buckets / Analytics Buckets** ainda alpha em 2026-05-06 — não detalhar
 - **Smart CDN** para egress optimization — fora deste agent (config no Dashboard)
 
+## Observabilidade integrada
+
+Upload events são quentes em custo (egress + storage) e em UX (lentidão de upload = abandono). Instrumentar SEMPRE.
+
+1. **Span por upload/download** (skill [`structured-events`](../skills/structured-events/SKILL.md)) com atributos:
+   - `bucket.name`, `bucket.public` (bool)
+   - `file.size_bytes`, `file.mime_type`, `file.path`
+   - `operation`: `upload` | `download` | `signed_url` | `delete`
+   - `result.success`, `error.type` (enum: `quota_exceeded`, `unauthorized`, `mime_blocked`, `size_exceeded`, `network`)
+   - `duration_ms`, `transfer.bytes_per_second` (calculado)
+   - `user.id`, `tenant_id` (do `auth.uid()`)
+2. **Sampling** (skill [`telemetry-sampling`](../skills/telemetry-sampling/SKILL.md) *Phase 34*): 100% errors, 100% uploads > 10 MB (cardinalidade baixa, valor alto), 5% baseline para downloads pequenos (alto volume).
+3. **Audit log** para uploads em buckets sensíveis (`audit_log` table com `actor`, `op`, `resource`, `geo`, `user_agent`).
+
+**Output adicionado:** seção "## Observability hooks" com snippet de upload/download wrapper.
+
 ## Ver também
 
 - [supabase-storage](../skills/supabase-storage/SKILL.md) — base de conhecimento canônica
 - [supabase-rls-writer](./supabase-rls-writer.md) — invocar para policies adicionais
 - [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

package/kit/commands/auditar-marco.md

@@ -33,4 +33,25 @@ 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>

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>