@luanpdd/kit-mcp 1.9.0 → 1.11.0

package/kit/agents/supabase-architect.md

@@ -142,6 +142,17 @@ projeto: {project_id ou "novo"} · tier: {tier} · gerado em {timestamp}
 `/supabase migration` para iniciar Wave 1.
 `/supabase rls` para Wave 2.
 ...
+
+## 9. Observabilidade
+{tabela `obs.events` + audit triggers + SLI views — gerada pelo bloco "Observabilidade integrada"}
+
+## 10. PRR pré-production
+Antes de aceitar tráfego real (≥ 1% de usuários), conduzir Production Readiness Review:
+- Invocar `/sre prr --service <nome>` ou `/prr --feature <descrição>` (cross-ref [prr-conductor](./prr-conductor.md))
+- 6 axes obrigatórios: System Architecture, Instrumentation/Metrics/Monitoring, Emergency Response, Capacity Planning, Change Management, Performance
+- Engagement model: Simple (serviços pequenos), Early Engagement (críticos), Frameworks (built on platform)
+- Gaps P0 = blocker (sem instrumentação básica, sem rollback, sem on-call); Gaps P1 = scheduled tasks
+- Reviewer ≠ time dev — par externo ou SRE conduz (anti auto-PRR)
 ```
 
 Sem preâmbulo. Sem "vou analisar agora". O caller precisa do plano para delegar.
@@ -164,3 +175,41 @@ Schema nasce com observabilidade — não é addon. Este agent SEMPRE projeta:
 **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?"
+
+## Production Readiness Review
+
+> Cross-ref canônico: [production-readiness-review](../skills/production-readiness-review/SKILL.md) (cap 32 do livro Google SRE — Evolving SRE Engagement Model). Para conduzir o PRR de fato, delegar para [prr-conductor](./prr-conductor.md).
+
+Schema + RLS + Edge Functions Supabase **NÃO são production-ready** só por estarem corretos — production-readiness é evidence-based, com gate explícito em 6 axes. Este agent **SEMPRE** sugere PRR no plano (seção `## 10. PRR pré-production` do output) — sem exceção.
+
+### 6 axes obrigatórios
+
+| Axe | O que verifica em contexto Supabase |
+|---|---|
+| **System Architecture** | Redundância (RLS isolamento por tenant; reverso de migrations testado), SPOFs mapeados (single project Supabase = SPOF — branches Pro mitigam), graceful degradation |
+| **Instrumentation / Metrics / Monitoring** | 4 golden signals em Edge Functions (cross-ref [supabase-edge-fn-writer](./supabase-edge-fn-writer.md)), `obs.events` populada, audit hooks ativos, SLI/SLO definidos por jornada crítica |
+| **Emergency Response** | Runbook de incident (RLS broken, schema corrupt, Edge Function 5xx storm), on-call rotation, postmortem template em `.planning/postmortems/` |
+| **Capacity Planning** | Spend Cap configurado, branch billing entendido (Pro), egress projetado, pgvector index size estimate, Edge concurrent invocations limite |
+| **Change Management** | Migrations declarative + reverso testado, RLS policies versionadas em git, Edge Function rollback strategy, supabase functions deploy --import-map idempotente |
+| **Performance** | Load test report (RPS sustentado), p99 latency baseline, RLS policy explain plan (sem seq scan em filtro), index coverage |
+
+### 3 engagement models (escolher conforme criticidade)
+
+- **Simple PRR** — para serviços internos / dogfooding / staging-only. Checklist com signoff Eng Lead. Custo baixo, cobertura básica.
+- **Early Engagement** — para serviços tier-1 (production-bound, user-facing, paid tier). PRR conduzido por SRE/external com 6 axes review profundo. **Default para Edge Functions user-facing**.
+- **Frameworks / SRE Platform** — para múltiplos serviços built on top de plataforma comum (ex: framework interno que outros times usam). PRR uma vez por plataforma, depois auto-herança para serviços novos.
+
+### Quando re-rodar PRR
+
+- Após mudança maior (rewrite, novo dependency externo, RPS 10×, nova RLS strategy)
+- Antes de aumentar tráfego cross-tier (free → paid → enterprise)
+- Re-run anual mesmo sem mudança (entropia operacional)
+
+> **PRR NÃO é one-shot** — statement "passou PRR uma vez em 2024" não é evidence em 2026.
+
+### Anti-patterns prevenidos
+
+- Auto-PRR pelo time dev → SEMPRE par externo ou SRE conduz (eyes-on-code novos)
+- "Deploy primeiro, PRR depois" → SEMPRE PRR ANTES de aceitar tráfego real (≥ 1% users)
+- Pular axe (ex: ignorar Capacity Planning porque "feature é small") → SEMPRE 6 axes; pular 1 = aprovação inválida (lacuna oculta vira incident em 6 meses)
+- "Acreditamos que está pronto" → SEMPRE evidence-based (load test report, runbook URL, dashboard link)

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

@@ -23,6 +23,18 @@ Você é o Edge Function writer Supabase. Recebe descrição de função (endpoi
 
 Edge Functions têm pegadinhas específicas do Deno runtime que diferem de Node: bare specifiers quebram, env vars têm nomes pre-populados, file writes só em `/tmp`, multi-rota precisa de prefix. Este agent garante que cada função seguirá essas regras desde o primeiro commit.
 
+**v1.12 — Adicional Legacy:** Edge Functions são **canônicas para o "API-only application" pattern** (cap 15 livro Feathers, modernizado). Quando este agent escreve Edge Function que wrappar API externa (Stripe/OpenAI/Twilio/etc), aplica skill [`legacy-api-only-applications`](../skills/legacy-api-only-applications/SKILL.md) — adapter pattern com interface mínima testável + anti-corruption layer + fake provider para tests. Quando detecta uso de LLM client (OpenAI/Anthropic), aplica skill [`llm-as-dependency`](../skills/llm-as-dependency/SKILL.md) — LLMProvider interface + adapter por vendor + FakeLLMProvider. Por padrão, este agent oferece **payload capture pattern** (skill [`pre-refactor-characterization`](../skills/pre-refactor-characterization/SKILL.md) Pattern 7) — instrumentação dedicada controlada por env `CAPTURE_PAYLOADS` para captura de fixtures reais via `mcp__supabase__get_logs`.
+
+**v1.11 — Adicional SRE Resilience:** Toda Edge Function gerada inclui por padrão **defesas de cascade** (skills `cascading-failures`, `retry-strategies`, `load-shedding-graceful-degradation`):
+
+1. **Timeout em chamadas externas** — `AbortSignal.timeout(2000)` por default
+2. **Retry com full jitter** — `delayMs = Math.random() * baseMs * 2^attempt`; max 3 retries; cap 30s
+3. **Deadline propagation** — handler parsea `x-deadline-ms` header e passa downstream
+4. **Server-side load shedding** — `LoadShedder` em `_shared/load-shedder.ts`; 503 + Retry-After quando saturated
+5. **Idempotency key** — em writes; gerada via UUID se cliente não enviar
+
+Sem flag explícita, esses patterns são incluídos no template de Edge Function nova. Para legacy (Edge Functions já escritas), invocar `/auditar-cascading <fn>` + `/load-shedding <fn>` para retrofit.
+
 ## Inputs esperados (do caller)
 
 - `function_name`: nome da função (kebab-case, ex: `process-emails`, `generate-embeddings`)
@@ -196,6 +208,106 @@ Edge Function nasce instrumentada com OTel — não é addon. Beneficia mais que
 
 **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).
 
+## Four Golden Signals
+
+> 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 Edge Function existente, delegar para [golden-signals-instrumenter](./golden-signals-instrumenter.md).
+
+Edge Function user-facing nasce com os 4 sinais dourados — não é addon. O bloco `## Observabilidade integrada` acima cobre OTel SDK + spans + propagation; este bloco especifica os **4 instrumentos canônicos** que o template gerado SEMPRE inclui:
+
+| Signal | Instrumento | Dimensão | Valor padrão |
+|---|---|---|---|
+| **Latency** | `meter.createHistogram('http_request_duration_ms')` com `explicitBucketBoundaries: [1,2,5,10,25,50,100,250,500,1000,2500,5000,10000,30000]` | `result=success\|error` (separar success de erro) | Bucketing exponencial captura long tail sem cardinality explosion |
+| **Traffic** | `meter.createCounter('http_requests_total')` | `endpoint`, `http_method` | Incrementado antes de processar request |
+| **Errors** | `meter.createCounter('http_errors_total')` | `error.type` enum (5-15 valores: `timeout\|validation\|auth\|rate_limit\|db\|provider_down\|...`) — **nunca** `error.message` (cardinalidade explode) | Incrementado em catch + path 4xx/5xx |
+| **Saturation** | `meter.createObservableGauge('saturation_pct')` com callback que lê estado real | resource-specific: `connection_pool` (pg) / `concurrency_limit` (Edge runtime) / `egress_bandwidth` / `cache_memory` | % do recurso mais escasso identificado ANTES de instrumentar |
+
+### Snippet canônico — adicionado ao topo do `index.ts` gerado
+
+```ts
+// PT-BR: 4 golden signals — instrumentação mínima universal
+import { metrics } from 'npm:@opentelemetry/api@1.9.0'
+const meter = metrics.getMeter('<function_name>')
+
+// 1. LATENCY — histogram bucketed exponencial
+const latencyHistogram = meter.createHistogram('http_request_duration_ms', {
+  description: 'Edge function latency split by result (success vs error)',
+  unit: 'ms',
+  advice: { explicitBucketBoundaries: [1, 2, 5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000, 30000] }
+})
+
+// 2. TRAFFIC — counter de requests recebidos
+const trafficCounter = meter.createCounter('http_requests_total', {
+  description: 'Total HTTP requests received by edge function'
+})
+
+// 3. ERRORS — counter por error.type (NUNCA error.message — cardinalidade)
+const errorsCounter = meter.createCounter('http_errors_total', {
+  description: 'Edge function errors by error.type enum'
+})
+
+// 4. SATURATION — gauge do recurso mais escasso (callback lê estado real)
+// PT-BR: para Edge Function default, saturation = concurrency_limit_used %
+// Substituir callback conforme recurso identificado (db pool, queue, cache)
+meter.createObservableGauge('saturation_pct', {
+  description: 'Saturation of scarcest resource — function-specific'
+}).addCallback((result) => {
+  // PT-BR: callback canônico — ler estado real (ex: SELECT count(*) FROM pg_stat_activity)
+  // Aqui placeholder: 0 < value < 1
+  result.observe(getSaturationPct())  // implementar conforme resource
+})
+```
+
+### Wrapping no handler
+
+```ts
+Deno.serve(async (req: Request) => {
+  const start = performance.now()
+  const endpoint = new URL(req.url).pathname
+  trafficCounter.add(1, { endpoint, http_method: req.method })
+
+  try {
+    const response = await handle(req)
+    latencyHistogram.record(performance.now() - start, {
+      endpoint,
+      result: response.ok ? 'success' : 'error',
+    })
+    if (!response.ok) {
+      errorsCounter.add(1, { endpoint, 'error.type': classifyError(response) })
+    }
+    return response
+  } catch (err) {
+    latencyHistogram.record(performance.now() - start, { endpoint, result: 'error' })
+    errorsCounter.add(1, { endpoint, 'error.type': classifyError(err) })
+    throw err
+  }
+})
+
+// PT-BR: classifyError DEVE retornar enum fechado, não err.message
+function classifyError(e: unknown): string {
+  if (e instanceof TimeoutError) return 'timeout'
+  if (e instanceof ValidationError) return 'validation'
+  if (e instanceof AuthError) return 'auth'
+  // ... 5-15 valores no total
+  return 'unknown'
+}
+```
+
+### Saturation por tipo de Edge Function
+
+| Tipo de função | Recurso mais escasso | Implementação típica |
+|---|---|---|
+| API simples (GET/POST com leitura DB) | `pg_pool` connections used | `select count(*) from pg_stat_activity where state = 'active'` |
+| RAG / embeddings | `concurrency_limit` (provider externo) | counter de requests in-flight |
+| Email / queue consumer (cron → pgmq) | `pgmq.queue_length` | `select msg_count from pgmq.metrics_<queue>` |
+| Storage I/O heavy (uploads grandes) | `egress_bandwidth` | bytes-out tracker em window |
+
+### Anti-patterns prevenidos
+
+- Errors counter usando `error.type = err.message` → SEMPRE enum fechado (5-15 valores)
+- Latency mistura success + error → SEMPRE `result` dimension separa
+- Mean latency em vez de histogram → SEMPRE histogram com percentis derivados em backend
+- Saturation genérico (CPU%) sem identificar recurso real → SEMPRE escolher recurso scarcest da função
+
 ## Ver também
 
 - [supabase-edge-functions](../skills/supabase-edge-functions/SKILL.md) — base de conhecimento canônica
@@ -205,3 +317,5 @@ Edge Function nasce instrumentada com OTel — não é addon. Beneficia mais que
 - [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
+- [four-golden-signals](../skills/four-golden-signals/SKILL.md) — 4 sinais canônicos (Latency, Traffic, Errors, Saturation) cap 6 livro Google SRE
+- [golden-signals-instrumenter](./golden-signals-instrumenter.md) — agent que retro-instrumenta Edge Functions existentes com os 4 signals

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

@@ -172,3 +172,83 @@ Toda migration emite evento estruturado e cria audit hooks por default — não
 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.
+
+## Alerta toil — automação via pg_cron
+
+> Cross-ref canônico: [eliminating-toil](../skills/eliminating-toil/SKILL.md) (cap 5 do livro Google SRE — Eliminating Toil). Para auditoria sistemática de toil em todo o repo, delegar para [toil-auditor](./toil-auditor.md).
+
+Migrations SQL executadas **manualmente em cadência regular** (rebuild índice, VACUUM, REFRESH MATERIALIZED VIEW, ANALYZE) são toil canônico — passam todos os 6 critérios: manual, repetitivo, automatizável, tático, sem valor durável, escala linear. Este agent **detecta padrões de toil** ao escrever migration e **alerta proativamente** sugerindo automação via `pg_cron`.
+
+### 6 critérios — quando uma migration é toil-prone
+
+Migration descreve operação que será re-executada > 1× = toil-prone. Aplicar 6 critérios da skill `eliminating-toil`:
+
+| Critério | Pergunta | Sinal de toil |
+|---|---|---|
+| 1. Manual | Operador roda `psql` ou aplica migration "quando lembra"? | Sim |
+| 2. Repetitivo | Já foi executada 3+ vezes em milestones diferentes? | Sim |
+| 3. Automatizável | `pg_cron` consegue agendar sem julgamento humano? | Sim |
+| 4. Tático | Reage a sintoma (lentidão, bloat, stale view) sem planejar? | Sim |
+| 5. Sem valor durável | Não cria asset permanente — só "limpa" estado | Sim |
+| 6. Escala linear | Mais users / mais dados = mais frequência manual | Sim |
+
+Se TODOS os 6 = sim → **toil**. Bloquear migration manual recorrente; oferecer alternativa via `pg_cron`.
+
+### Padrões SQL canônicos que SEMPRE disparam alerta toil
+
+| Operação manual | Por quê é toil | Automação canônica |
+|---|---|---|
+| `REINDEX TABLE x` recorrente (a cada N semanas) | Rebuild de bloat de índice é tático, sem valor durável, repetitivo | `select cron.schedule('reindex_x', '0 3 * * 0', $$reindex table x$$);` (semanal 3am) |
+| `VACUUM ANALYZE x` manual | autovacuum não está acompanhando — sintoma de tuning, não fix manual | Tunar `autovacuum_vacuum_scale_factor` para tabela específica + `pg_cron` se necessário |
+| `REFRESH MATERIALIZED VIEW x` manual | Stale view detectada por user reclamação ou alert | `select cron.schedule('refresh_x', '*/30 * * * * *', $$refresh materialized view concurrently x$$);` |
+| `ANALYZE` em tabela após bulk insert manual | Estatísticas desatualizadas após ETL — bem conhecido | Trigger AFTER INSERT/COPY com `analyze` no fim do batch, ou `pg_cron` pós-ETL |
+| `delete from logs where created_at < now() - interval '90d'` manual recorrente | Retention manual = toil clássico | `select cron.schedule('purge_logs', '0 4 * * *', $$delete from logs where ...$$);` |
+| `dump + restore` periódico para estatísticas / planos cache | Operação repetitiva sem valor permanente | `pg_cron` job ou `pg_stat_reset_*()` calls automatizadas |
+
+### Snippet canônico — converter manual em pg_cron
+
+```sql
+-- PT-BR: ANTES — toil (operador roda manualmente)
+-- $ psql -c 'reindex table heavy_table;'   ← repetir a cada 2 semanas
+
+-- PT-BR: DEPOIS — automação via pg_cron (necessita extension pg_cron habilitada)
+create extension if not exists pg_cron;
+
+select cron.schedule(
+  'reindex_heavy_table_biweekly',
+  '0 3 1,15 * *',                            -- 3am dias 1 e 15
+  $$ reindex table public.heavy_table $$
+);
+
+-- PT-BR: monitor — falha em job pg_cron emite linha em cron.job_run_details
+-- alimentar alerta SLO se job falha 3+ vezes seguidas
+```
+
+### Quando NÃO automatizar (não é toil)
+
+- **Migration de schema (DDL one-shot)** — `create table`, `alter table add column` são project work, não toil. Não recorrentes.
+- **Backfill data único** — `update orders set status = ...` aplicado 1× para corrigir bug é grungy work, não toil.
+- **Rebuild que requer julgamento** — `reindex` que requer escolher hora baseada em load patterns variáveis, ou que precisa coordenação com release. Mantém manual mas documenta runbook.
+
+### Output do agent — adicionado ao SQL gerado
+
+Quando o agent detecta que a migration descreve operação toil-prone (regex em DDL: `reindex|vacuum|refresh materialized|delete from .* interval`), adiciona comentário-alerta no header do arquivo SQL gerado:
+
+```sql
+/*
+  ⚠ TOIL ALERT — esta operação parece recorrente.
+  
+  Se será executada em cadência regular, considere automação via pg_cron:
+    select cron.schedule('<job_name>', '<schedule>', $$ <sql> $$);
+  
+  Cross-ref: kit/skills/eliminating-toil/SKILL.md (6 critérios canônicos)
+             kit/agents/toil-auditor.md (audit sistemático para repo todo)
+*/
+```
+
+### Anti-patterns prevenidos
+
+- "Roda quando der" runbook → SEMPRE pg_cron + monitoring de falha do job
+- `pg_cron` schedule mas sem alerta de falha → SEMPRE incluir SLO em `cron.job_run_details` (% sucesso 30d)
+- Automação parcial (script humano-iniciado) → ainda é toil (humano pressiona botão); preferir cron.schedule completo
+- Migration manual recorrente "porque é só uma vez por mês" → 12×/ano = toil, regra ≤ 50% se acumular vários "só um por mês"

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