@luanpdd/kit-mcp 1.8.1 → 1.9.0

package/kit/commands/burn-rate-status.md

@@ -0,0 +1,140 @@
+---
+name: burn-rate-status
+description: Tabela de burn rate por SLO — % budget gasto, ETA exhaustão, ação (page/ticket/warn/ok). Rodável manualmente ou em /loop. Aplica skill burn-rate-alerting.
+argument-hint: "[<slo_name>] [--lookahead 4h] [--baseline 1h]"
+allowed-tools:
+  - Read
+  - Bash
+  - Task
+  - Glob
+---
+
+<objective>
+Snapshot de burn rate para 1 SLO (se especificado) ou TODOS os SLOs definidos. Aplica skill [`burn-rate-alerting`](../skills/burn-rate-alerting/SKILL.md) — fórmula `burn_rate = error_rate / (1 - target)`, lookahead ≤ 4× baseline.
+
+**Cria/Atualiza:** nada — comando read-only.
+
+**Após:** o user vê tabela com status (PAGE / TICKET / WARN / OK) e pode escolher invocar `/investigar-producao` se há burn ativo.
+</objective>
+
+<context>
+**Argumentos:** `$ARGUMENTS` — opcional `<slo_name>` para 1 SLO; sem args = todos.
+
+**Flags:**
+- `--lookahead <duration>` — janela predictive (default: `4h` para short-term)
+- `--baseline <duration>` — janela base (default: `1h`)
+- `--format <table|json>` — output format (default: `table`)
+
+**Combinações canônicas:**
+- short-term: lookahead 4h, baseline 1h (page-tier)
+- long-term: lookahead 3d, baseline 18h (ticket-tier)
+
+**Loop pattern:** rodar este comando via skill `loop` com intervalo 5min para monitoramento contínuo.
+
+```text
+/loop 5m /burn-rate-status
+```
+</context>
+
+<process>
+
+## 1. Parsear argumentos
+
+```bash
+SLO_NAME=$(echo "$ARGUMENTS" | awk '{print $1}' | grep -v '^--' || true)
+LOOKAHEAD=$(echo "$ARGUMENTS" | grep -oE -- '--lookahead [^ ]+' | awk '{print $2}')
+BASELINE=$(echo "$ARGUMENTS" | grep -oE -- '--baseline [^ ]+' | awk '{print $2}')
+FORMAT=$(echo "$ARGUMENTS" | grep -oE -- '--format [^ ]+' | awk '{print $2}')
+
+[ -z "$LOOKAHEAD" ] && LOOKAHEAD="4h"
+[ -z "$BASELINE" ] && BASELINE="1h"
+[ -z "$FORMAT" ] && FORMAT="table"
+```
+
+## 2. Listar SLOs
+
+```bash
+if [ -n "$SLO_NAME" ]; then
+  SLO_FILES=(".planning/slos/${SLO_NAME}.md")
+else
+  SLO_FILES=(.planning/slos/*.md)
+fi
+
+if [ ${#SLO_FILES[@]} -eq 0 ] || [ ! -f "${SLO_FILES[0]}" ]; then
+  echo "Nenhum SLO definido. Rode /definir-slo <feature> primeiro."
+  exit 0
+fi
+```
+
+## 3. Para cada SLO, dispatch para `burn-rate-forecaster`
+
+Para cada `SLO_FILE`:
+
+```bash
+SLO_NAME=$(basename "$SLO_FILE" .md)
+TARGET=$(grep -oE 'Target.*[0-9.]+' "$SLO_FILE" | head -1 | grep -oE '[0-9.]+')
+```
+
+```text
+Task(
+  subagent_type="burn-rate-forecaster",
+  prompt="
+slo_name: ${SLO_NAME}
+target: ${TARGET}
+lookahead: ${LOOKAHEAD}
+baseline: ${BASELINE}
+
+Calcular burn rate atual + ETA + status (PAGE/TICKET/WARN/OK).
+Output formato compatível com tabela mestra.
+"
+)
+```
+
+## 4. Agregar resultados em tabela
+
+```
+═══════════════════════════════════════════════════════════
+ framework ► BURN-RATE-STATUS ▸ {timestamp}
+═══════════════════════════════════════════════════════════
+
+| SLO | Target | Window | Budget gasto | Burn rate | ETA exhaustão | Status | Ação |
+|---|---|---|---|---|---|---|---|
+| checkout_success | 99.9% | 30d | 23% | 1.4× | 12d | OK | informativo |
+| login_success | 99.95% | 30d | 78% | 8.0× | 4h | **PAGE** | invocar /investigar-producao |
+| search_latency | 99% | 30d | 15% | 0.7× | — | OK | — |
+```
+
+## 5. Sugerir próximas ações
+
+Se algum SLO em status PAGE ou TICKET:
+
+```
+## ⚠ SLOs em alerta:
+1. login_success — burn rate 8.0×, ETA 4h
+   → /investigar-producao "login_success burn rate = 8.0× às {timestamp}"
+
+## SLOs em WARN (>= 80% gasto):
+- (nenhum)
+
+## SLOs OK:
+- 2 SLOs em compliance saudável
+```
+
+## 6. Modo `/loop`
+
+Se chamado dentro de `/loop`, comportamento idempotente:
+- Não acumular state entre invocações (snapshot fresh)
+- Output curto se nada mudou (apenas status; sem repetir tabela completa em todo loop)
+- Acionar AskUserQuestion APENAS quando status muda de OK → WARN/TICKET/PAGE (transição)
+
+</process>
+
+<success_criteria>
+- [ ] $ARGUMENTS parseados (SLO opcional + flags)
+- [ ] SLOs descobertos via glob `.planning/slos/*.md`
+- [ ] `burn-rate-forecaster` invocado para cada SLO
+- [ ] Tabela agregada em formato consistente
+- [ ] Status enum: PAGE / TICKET / WARN / OK
+- [ ] Sugestões de próximas ações para SLOs em alerta
+- [ ] Idempotente (rodável em /loop sem acúmulo)
+</success_criteria>

package/kit/commands/concluir-marco.md

@@ -133,4 +133,22 @@ Saída: Milestone arquivado (roadmap + requisitos), PROJECT.md evoluído, tag gi
 - **Resumo de uma linha:** Milestone colapsado no ROADMAP.md deve ser uma única linha com link
 - **Eficiência de contexto:** Arquivo mantém ROADMAP.md e REQUIREMENTS.md com tamanho constante por milestone
 - **Novos requisitos:** Próximo milestone começa com `/novo-marco` que inclui definição de requisitos
-  </critical_rules>
+  </critical_rules>
+
+<observability_integration>
+**OMM no-regression gate (v1.9 — INT-FW-05):**
+
+Quando `workflow.complete_milestone_omm_gate = true` (default), o workflow inclui passo OMM regression check antes de arquivar:
+
+1. Procurar `.planning/OMM-REPORT.md` atual. Se ausente: rodar `/auditar-observabilidade` primeiro.
+2. Comparar scores das 5 capacidades com `.planning/milestones/<previous>/OMM-REPORT.md`.
+3. Se alguma capacidade regrediu E `workflow.omm_no_regression = true`: BLOQUEAR conclusion.
+4. Se regression detectada mas `workflow.omm_no_regression = false`: WARN explícito; user decide entre aceitar ou pausar.
+5. OMM-REPORT.md final é arquivado em `.planning/milestones/v<version>/OMM-REPORT.md`.
+
+Gate executável: `gates/omm-no-regression.md`.
+
+Skill consultada: [`observability-maturity-model`](../skills/observability-maturity-model/SKILL.md).
+
+**REQ:** INT-FW-05.
+</observability_integration>

package/kit/commands/definir-slo.md

@@ -0,0 +1,108 @@
+---
+name: definir-slo
+description: Invoca slo-engineer para gerar SLO.md + SQL materialização SLI events. Aplica skill event-based-slos. Default 30d sliding window, target ≤ 99.95%.
+argument-hint: "<feature> [--target 99.9] [--owner email]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Task
+  - AskUserQuestion
+---
+
+<objective>
+Definir um SLO event-based para uma feature/jornada do usuário. Invoca o agente [`slo-engineer`](../agents/slo-engineer.md) que aplica a skill [`event-based-slos`](../skills/event-based-slos/SKILL.md) — SLI event-based, sliding window 30d, target ≤ 99.95%, owner nomeado, materialização em Postgres.
+
+**Cria/Atualiza:**
+- `.planning/slos/<slo_name>.md` — definição canônica do SLO
+- `supabase/migrations/<timestamp>_create_sli_<slo_name>.sql` — view materializada SLI
+
+**Após:** SLO está em `draft` status. Próximo passo: `/burn-rate-status <slo_name>` para validar baseline; após 1+ semana, promover de `draft` → `test_channel` → `primary`.
+</objective>
+
+<context>
+**Argumentos:** `$ARGUMENTS` — primeiro token é a feature/jornada (ex: `checkout`, `login`, `bulk-orders`); restante são flags.
+
+**Flags:**
+- `--target <percent>` — target % do SLO (default: agent sugere baseado em criticality, sempre ≤ 99.95%)
+- `--owner <email>` — owner do SLO (default: AskUserQuestion)
+- `--window <duration>` — sliding window (default: `30d`)
+
+**Pré-requisito (Full mode):** projeto Supabase configurado, schema `observability` com tabela de events (Phase 31 supabase-architect projeta isso).
+</context>
+
+<process>
+
+## 1. Parsear argumentos
+
+```bash
+FEATURE=$(echo "$ARGUMENTS" | awk '{print $1}')
+TARGET=$(echo "$ARGUMENTS" | grep -oE -- '--target [0-9.]+' | awk '{print $2}')
+OWNER=$(echo "$ARGUMENTS" | grep -oE -- '--owner [^ ]+' | awk '{print $2}')
+WINDOW=$(echo "$ARGUMENTS" | grep -oE -- '--window [^ ]+' | awk '{print $2}')
+
+[ -z "$FEATURE" ] && {
+  echo "Uso: /definir-slo <feature> [--target N] [--owner email]"
+  exit 1
+}
+
+[ -z "$WINDOW" ] && WINDOW="30d"
+```
+
+## 2. Detectar `supabase/config.toml`
+
+```bash
+PROJECT_ID=""
+if [ -f supabase/config.toml ]; then
+  PROJECT_ID=$(grep -E '^project_id\s*=' supabase/config.toml | sed 's/.*= *"\(.*\)".*/\1/' | head -1)
+fi
+```
+
+## 3. Dispatch para `slo-engineer`
+
+```text
+Task(
+  subagent_type="slo-engineer",
+  prompt="
+feature: ${FEATURE}
+${TARGET:+target: ${TARGET}}
+${OWNER:+owner: ${OWNER}}
+window: ${WINDOW}
+${PROJECT_ID:+project_id: ${PROJECT_ID}}
+
+Aplicar skill event-based-slos. Gerar:
+1. .planning/slos/<slo_name>.md (SLO definition canônico)
+2. supabase/migrations/<timestamp>_create_sli_<slo_name>.sql (materialized view + pg_cron refresh)
+
+Se target > 99.95%, recusar e explicar — métrica informativa, não SLO.
+Se Full mode (mcp__supabase disponível), apply_migration; senão, output text.
+"
+)
+```
+
+## 4. Pós-output
+
+```
+═══════════════════════════════════════════════════════════
+ framework ► DEFINIR-SLO ▸ {slo_name}
+═══════════════════════════════════════════════════════════
+
+[output do slo-engineer — ver Step 8 do agent]
+
+## Próximos passos
+1. `/burn-rate-status {slo_name}` — checar baseline atual
+2. Após 1+ semana validando que SLO detecta incidents reais:
+   - Editar `.planning/slos/{slo_name}.md` → status: `test_channel` → `primary`
+3. Configurar alerts (page + ticket) — invocar `burn-rate-forecaster` ou config manual
+```
+
+</process>
+
+<success_criteria>
+- [ ] FEATURE parseado de $ARGUMENTS
+- [ ] `slo-engineer` invocado via Task
+- [ ] `.planning/slos/<slo_name>.md` criado
+- [ ] Migration SQL criada (Full mode applied; Offline mode escrita)
+- [ ] Target ≤ 99.95% enforced
+- [ ] Owner registrado (via flag ou AskUserQuestion)
+</success_criteria>

package/kit/commands/discutir-fase.md

@@ -62,3 +62,29 @@ Se `DISCUSS_MODE` for `"discuss"` (ou não definido, ou qualquer outro valor): L
 - CONTEXT.md captura decisões, não visão vaga
 - Usuário conhece os próximos passos
 </success_criteria>
+
+<observability_integration>
+**Integração com Observability-Driven Development (v1.9):**
+
+Quando o workflow.observability_phase_questions = true (default), o workflow inclui pergunta canônica de ODD na sessão de discussão:
+
+> "Quais SLIs essa fase impacta? O que precisa ser instrumentado para responder às 4 perguntas pré-PR?"
+
+A pergunta é resolvida consultando a skill [`observability-driven-development`](../skills/observability-driven-development/SKILL.md) e o resultado é registrado na seção `<observability>` do CONTEXT.md gerado:
+
+```markdown
+<observability>
+## SLIs impactados
+- [SLI ou "nenhum — fase puramente interna"]
+
+## Instrumentação necessária
+- Spans novos: [lista]
+- Atributos canônicos: [user.id, tenant_id, ...]
+- error.type enum esperado: [validation, timeout, ...]
+</observability>
+```
+
+O `plan-checker` invocado pelo `/planejar-fase` (Phase 33 — INT-FW-02) lê esta seção e bloqueia o plano se ODD ausente para fases voltadas ao usuário (skip silenciosamente para fases de infraestrutura — ver detecção em `discuss-phase.md`).
+
+**REQ:** INT-FW-01.
+</observability_integration>

package/kit/commands/forense.md

@@ -53,4 +53,23 @@ Ler e executar o workflow forensics de @./.claude/framework/workflows/forensics.
 - **Redigir dados sensíveis:** Remover caminhos absolutos, chaves de API, tokens de relatórios e issues.
 - **Fundamentar descobertas em evidências:** Toda anomalia deve citar commits, arquivos ou dados de estado específicos.
 - **Sem especulação sem evidência:** Se os dados forem insuficientes, diga isso — não fabrique causas raiz.
-</critical_rules>
+</critical_rules>
+
+<observability_integration>
+**Integração com Core Analysis Loop (v1.9):**
+
+Forense usa skill [`core-analysis-loop`](../skills/core-analysis-loop/SKILL.md) — método científico iterativo (sintoma → hipótese de dados → validação → próxima iteração) em vez de inspeção ad hoc.
+
+Cada anomalia detectada vira hipótese com query de validação:
+
+| Tipo de anomalia | Hipótese formada | Query de validação |
+|---|---|---|
+| Loop travado | "phase X stuck há Yh" | `git log --since="Yh ago" --grep=phase` para confirmar zero commits |
+| Artefatos ausentes | "PLAN.md ausente em phase X" | `ls .planning/phases/X-*/X-PLAN-*.md` |
+| Trabalho abandonado | "branch sem merge nem commit recente" | `git log -1 <branch>` + `git status` |
+| Crash/interrupção | "executor falhou em meio a fase" | grep no STATE.md por "in_progress" sem update recente |
+
+**Skill consultada explicitamente:** abrir o arquivo `kit/skills/core-analysis-loop/SKILL.md` para padrão "documentação da trilha (formato canônico)" — o relatório forense em `.planning/forensics/report-<ts>.md` segue esse formato com cada hipótese tendo "Query / Resultado / Status (VALIDATED / REFUTED / INCONCLUSIVE)".
+
+**REQ:** INT-FW-06.
+</observability_integration>

package/kit/commands/instrumentar-fase.md

@@ -0,0 +1,200 @@
+---
+name: instrumentar-fase
+description: Após /planejar-fase, gera INSTRUMENTATION.md por plano (spans, atributos canônicos, eventos, validação ODD). Aplica skill observability-driven-development.
+argument-hint: "[fase] [plano]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Grep
+  - Glob
+  - Task
+---
+
+<objective>
+Após `/planejar-fase` produzir PLAN.md, este comando gera `INSTRUMENTATION.md` para cada plano da fase. Aplica a skill [observability-driven-development](../skills/observability-driven-development/SKILL.md) — bundle telemetria com a feature, valide as 4 perguntas pré-PR.
+
+**Cria/Atualiza:**
+- `.planning/phases/<N>/<padded>-PLAN-<NN>-INSTRUMENTATION.md` por plano
+
+**Após:** o user tem o contrato de instrumentação que o `executor` (e o `observability-instrumenter`) devem cumprir durante `/executar-fase`.
+</objective>
+
+<context>
+**Argumentos:** `$ARGUMENTS` — primeiro token é número da fase (ex.: `30`); segundo opcional é número do plano (ex.: `01`); se omitido, processa todos os planos da fase.
+
+**Pré-requisito:** `/planejar-fase <N>` já rodou. Existem `<padded>-PLAN-<NN>-*.md` em `.planning/phases/<N>/`.
+
+**Skill consultada:** [`observability-driven-development`](../skills/observability-driven-development/SKILL.md) — 4 perguntas pré-PR canônicas.
+</context>
+
+<process>
+
+## 1. Parsear argumentos
+
+```bash
+PHASE_NUM=$(echo "$ARGUMENTS" | awk '{print $1}')
+PLAN_NUM=$(echo "$ARGUMENTS" | awk '{print $2}')
+
+if [ -z "$PHASE_NUM" ]; then
+  echo "Uso: /instrumentar-fase <N> [<NN>]"
+  echo "Ex.: /instrumentar-fase 30        # todos os planos da Phase 30"
+  echo "Ex.: /instrumentar-fase 30 01     # só Plano 01 da Phase 30"
+  exit 1
+fi
+```
+
+## 2. Detectar phase_dir + planos
+
+```bash
+PHASE_STATE=$(node "./.claude/framework/bin/tools.cjs" init phase-op "$PHASE_NUM")
+PHASE_DIR=$(echo "$PHASE_STATE" | jq -r .phase_dir)
+
+if [ "$PHASE_DIR" = "null" ] || [ ! -d "$PHASE_DIR" ]; then
+  echo "Fase $PHASE_NUM ainda não foi planejada. Rode /planejar-fase $PHASE_NUM primeiro."
+  exit 1
+fi
+
+# PT-BR: descobrir PLAN.md(s) — exclui já-instrumentados
+if [ -n "$PLAN_NUM" ]; then
+  PLANS=("$PHASE_DIR"/*-PLAN-${PLAN_NUM}-*.md)
+else
+  PLANS=("$PHASE_DIR"/*-PLAN-*.md)
+fi
+```
+
+## 3. Para cada plano, gerar INSTRUMENTATION.md
+
+Para cada `PLAN_FILE`:
+
+```bash
+PADDED=$(basename "$PLAN_FILE" | grep -oE '^[0-9]+')
+NN=$(basename "$PLAN_FILE" | grep -oE 'PLAN-[0-9]+' | grep -oE '[0-9]+')
+OUT_FILE="$PHASE_DIR/${PADDED}-PLAN-${NN}-INSTRUMENTATION.md"
+
+# PT-BR: não sobrescrever se já existe
+if [ -f "$OUT_FILE" ]; then
+  echo "Já existe: $OUT_FILE — pulando"
+  continue
+fi
+```
+
+Ler `PLAN_FILE` para extrair:
+- Goal/objetivo
+- Tarefas (especialmente as que adicionam novos handlers/funções/endpoints)
+- Componentes/serviços tocados
+
+Gerar `INSTRUMENTATION.md` com seções canônicas (consultar [`observability-driven-development`](../skills/observability-driven-development/SKILL.md)):
+
+```markdown
+---
+phase: {N}
+plan: {NN}
+title: Instrumentation Plan for Plan {NN}
+status: pending
+---
+
+# Instrumentation Plan — Phase {N}, Plan {NN}: {plan_title}
+
+## Spans
+
+Spans a adicionar em arquivos modificados/criados pelo plano.
+
+| Name | Kind | Service | Atributos canônicos | Notas |
+|------|------|---------|---------------------|-------|
+| `{handler_name}` | SERVER | `{service}` | `user.id`, `tenant_id`, `request.id`, `endpoint`, `http.method`, `result.success`, `error.type`, `build_id` | inbound HTTP |
+
+## Eventos críticos
+
+Eventos com semantic significance que merecem `result.success` discreto.
+
+| Event | Quando emitir | result.success | error.type enum (catch) |
+|-------|---------------|----------------|--------------------------|
+| `{event_name}` | {momento} | true se {happy path} | `validation` \| `auth` \| `rate_limit` \| `timeout` \| `unknown` |
+
+## Métricas (opcional, se há valores numéricos críticos)
+
+| Name | Type | Unit | Labels |
+|------|------|------|--------|
+| `{metric_name}` | counter \| histogram | `ms` \| `bytes` \| `count` | `tenant_id`, `endpoint` |
+
+## Validação ODD — 4 perguntas pré-PR
+
+| # | Pergunta | Como verificar |
+|---|----------|----------------|
+| 1 | **Faz o que esperei?** | Span tem `result.success = true` no happy path. Smoke: enviar request, query `WHERE result_success = true` retorna |
+| 2 | **Compara à versão anterior?** | `build_id` setado em todo span. Query: `SELECT build_id, ..., AVG(duration_ms) GROUP BY build_id` |
+| 3 | **Usuários estão usando?** | `user.id` ou `tenant_id` ou `customer.tier` em todo span. Query: `SELECT customer.tier, COUNT(*) GROUP BY 1` |
+| 4 | **Anomalias emergem?** | Cada `catch` emite `error.type` enum (não message livre). Cada if/else significativo emite `branch_taken`. Query: `SELECT error.type, COUNT(*) GROUP BY 1` |
+
+## Sampling (head-based, default)
+
+```ts
+// PT-BR: errors sempre, success sample 10% — ajuste conforme volume
+const shouldSample = (event: SpanLike): boolean => {
+  if (event.attributes['result.success'] === false) return true   // 100% errors
+  if (event.attributes['customer.tier'] === 'enterprise') return true  // 100% enterprise
+  return Math.random() < 0.1   // 10% baseline
+}
+```
+
+## Referências cruzadas
+
+- Skill [`structured-events`](../../../../kit/skills/structured-events/SKILL.md) — campos canônicos
+- Skill [`distributed-tracing`](../../../../kit/skills/distributed-tracing/SKILL.md) — propagação cross-service
+- Skill [`opentelemetry-standard`](../../../../kit/skills/opentelemetry-standard/SKILL.md) — SDK setup
+- Skill [`observability-driven-development`](../../../../kit/skills/observability-driven-development/SKILL.md) — 4 perguntas
+- Agente [`observability-instrumenter`](../../../../kit/agents/observability-instrumenter.md) — gera os patches durante `/executar-fase`
+
+## Aceitação
+
+- [ ] Cada handler do plano tem span com 8 atributos canônicos mínimos
+- [ ] Cada `catch` emite `error.type` enum
+- [ ] Cada branch significativo emite `branch_taken`
+- [ ] Outbound calls propagam contexto via `propagation.inject`
+- [ ] Smoke: 100 requests sintéticos → spans queryables com filtragem por `tenant_id`/`user.id`
+```
+
+## 4. Plan-checker hook
+
+Se `plan-checker` está ativo no fluxo, este comando atualiza checkpoint do plan-checker:
+
+```bash
+# PT-BR: registrar que plano agora tem ODD-spec acoplada
+echo "instrumentation:$NN:ready" >> "$PHASE_DIR/.plan-checker-state"
+```
+
+## 5. Output
+
+```
+═══════════════════════════════════════════════════════════
+ framework ► INSTRUMENTAR-FASE ▸ Phase {N}
+═══════════════════════════════════════════════════════════
+
+Planos processados: {count}
+INSTRUMENTATION.md gerados:
+  - {padded}-PLAN-01-INSTRUMENTATION.md
+  - {padded}-PLAN-02-INSTRUMENTATION.md
+  ...
+
+Próximo passo:
+  - `/executar-fase {N}` — executor invocará observability-instrumenter automaticamente para aplicar os spans descritos
+  - `/auditar-uat` antes do PR — valida que as 4 perguntas ODD têm resposta executável
+```
+
+## 6. Commit
+
+```bash
+node "./.claude/framework/bin/tools.cjs" commit "docs(${PHASE_NUM}): instrumentation plans" --files "${PHASE_DIR}"/*-INSTRUMENTATION.md
+```
+
+</process>
+
+<success_criteria>
+- [ ] Para cada `PLAN-NN-*.md` da fase, existe `PLAN-NN-INSTRUMENTATION.md`
+- [ ] INSTRUMENTATION.md tem 4 seções: Spans, Eventos críticos, Métricas, Validação ODD
+- [ ] Validação ODD com 4 perguntas explicitamente respondidas
+- [ ] Cross-references para skills `structured-events`, `distributed-tracing`, `opentelemetry-standard`, `observability-driven-development`
+- [ ] Não sobrescreve INSTRUMENTATION.md já existente (idempotente)
+- [ ] Commit atômico após geração
+</success_criteria>