@luanpdd/kit-mcp 1.17.0 → 1.19.0

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

@@ -1,47 +1,49 @@
 ---
 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]"
+description: Tabela de burn rate por SLO consumindo .planning/slos/*.yml + .planning/metrics/snapshots/. Calcula SLI atual, burn rate (% budget gasto/h), ETA exhaustão e ação (PAGE/TICKET/WARN/OK). Aplica skill burn-rate-alerting.
+argument-hint: "[<slo_name>] [--lookahead 4h] [--baseline 1h] [--format table|json]"
 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.
+Snapshot de burn rate para 1 SLO (se especificado) ou TODOS os SLOs definidos em `.planning/slos/*.yml`. Aplica skill [`burn-rate-alerting`](../skills/burn-rate-alerting/SKILL.md) — fórmula `burn_rate = error_rate / (1 - target)`, lookahead ≤ 4× baseline.
+
+**Lê:** `.planning/slos/*.yml` (definição) + `.planning/metrics/snapshots/*.json` (eventos persistidos via `metrics.persistSnapshot()` — Phase 99).
 
 **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.
+**Após:** o user vê tabela com status (PAGE / TICKET / WARN / OK) e pode escolher invocar `/investigar-producao` se há burn ativo, ou rodar mais carga e re-snapshotar via `metrics-snapshot` MCP tool se a janela está vazia.
 </objective>
 
 <context>
 **Argumentos:** `$ARGUMENTS` — opcional `<slo_name>` para 1 SLO; sem args = todos.
 
 **Flags:**
-- `--lookahead <duration>` — janela predictive (default: `4h` para short-term)
+- `--lookahead <duration>` — janela predictive (default: `4h` para short-term page-tier)
 - `--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
-```
+- short-term (page-tier): lookahead 4h, baseline 1h
+- long-term (ticket-tier): lookahead 3d, baseline 18h
+
+**Phase 99 wiring:** este comando consome dados persistidos pela API
+`persistSnapshot()` adicionada em `src/core/metrics.js` (Phase 99). Sem
+snapshots na janela, o comando emite "no_data" para o SLO em vez de
+inventar números. Para gerar dados, invoque o MCP tool `metrics-snapshot`
+durante uso normal — futura fase pode auto-persistir.
 </context>
 
 <process>
 
 ## 1. Parsear argumentos
 
+Bash:
 ```bash
-SLO_NAME=$(echo "$ARGUMENTS" | awk '{print $1}' | grep -v '^--' || true)
+SLO_NAME=$(echo "$ARGUMENTS" | awk '{for(i=1;i<=NF;i++) if($i !~ /^--/) {print $i; exit}}')
 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}')
@@ -51,90 +53,240 @@ FORMAT=$(echo "$ARGUMENTS" | grep -oE -- '--format [^ ]+' | awk '{print $2}')
 [ -z "$FORMAT" ] && FORMAT="table"
 ```
 
-## 2. Listar SLOs
+Convert duration to ms (helper):
+```bash
+to_ms() {
+  local d="$1"
+  case "$d" in
+    *h) echo $(( ${d%h} * 3600000 ));;
+    *m) echo $(( ${d%m} * 60000 ));;
+    *s) echo $(( ${d%s} * 1000 ));;
+    *d) echo $(( ${d%d} * 86400000 ));;
+    *) echo 0 ;;
+  esac
+}
+LOOKAHEAD_MS=$(to_ms "$LOOKAHEAD")
+BASELINE_MS=$(to_ms "$BASELINE")
+```
+
+## 2. Listar SLOs (FIX Phase 99: extension `.yml`, não `.md`)
 
 ```bash
 if [ -n "$SLO_NAME" ]; then
-  SLO_FILES=(".planning/slos/${SLO_NAME}.md")
+  SLO_FILES=(".planning/slos/${SLO_NAME}.yml")
 else
-  SLO_FILES=(.planning/slos/*.md)
+  SLO_FILES=(.planning/slos/*.yml)
 fi
 
-if [ ${#SLO_FILES[@]} -eq 0 ] || [ ! -f "${SLO_FILES[0]}" ]; then
-  echo "Nenhum SLO definido. Rode /definir-slo <feature> primeiro."
+# Filtra entradas inexistentes (caso o glob não tenha match).
+EXISTING_SLOS=()
+for f in "${SLO_FILES[@]}"; do
+  [ -f "$f" ] && EXISTING_SLOS+=("$f")
+done
+
+if [ ${#EXISTING_SLOS[@]} -eq 0 ]; then
+  echo "Nenhum SLO definido em .planning/slos/. Rode /definir-slo <feature> primeiro."
   exit 0
 fi
 ```
 
-## 3. Para cada SLO, dispatch para `burn-rate-forecaster`
+## 3. Para cada SLO, carregar metadata + calcular SLI
 
-Para cada `SLO_FILE`:
+Para cada `SLO_FILE` em `EXISTING_SLOS`:
+
+### 3.1 Extrair campos canônicos do YAML via regex
+
+Os SLOs do projeto seguem schema fixo (validado por `test/unit/slo-schema.test.js`). Sem `js-yaml` — regex sobre os keys conhecidos:
 
 ```bash
-SLO_NAME=$(basename "$SLO_FILE" .md)
-TARGET=$(grep -oE 'Target.*[0-9.]+' "$SLO_FILE" | head -1 | grep -oE '[0-9.]+')
+SLO_NAME=$(grep -oE '^\s+name:\s*\S+' "$SLO_FILE" | head -1 | awk '{print $2}')
+SERVICE=$(grep -oE '^\s+service:\s*\S+' "$SLO_FILE" | head -1 | awk '{print $2}')
+SLO_TYPE=$(grep -oE '^\s+type:\s*\S+' "$SLO_FILE" | head -1 | awk '{print $2}')
+
+# Availability SLO: target = ratio decimal (e.g. 0.995)
+TARGET_RATIO=$(grep -oE '^target:\s*[0-9.]+' "$SLO_FILE" | awk '{print $2}')
+# Latency SLO: target_ms + percentile
+TARGET_MS=$(grep -oE '^target_ms:\s*[0-9]+' "$SLO_FILE" | awk '{print $2}')
+PERCENTILE=$(grep -oE '^\s+percentile:\s*[0-9]+' "$SLO_FILE" | awk '{print $2}')
 ```
 
-```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.
-"
-)
+### 3.2 Carregar snapshots da janela baseline
+
+Use a API `loadSnapshots()` adicionada em Phase 99. Inline node script:
+
+```bash
+SNAPS_JSON=$(node --input-type=module -e "
+import { loadSnapshots } from './src/core/metrics.js';
+const snaps = await loadSnapshots(process.cwd(), $BASELINE_MS);
+console.log(JSON.stringify(snaps));
+")
+SNAPSHOT_COUNT=$(echo "$SNAPS_JSON" | node -e "console.log(JSON.parse(require('fs').readFileSync(0,'utf8')).length)")
 ```
 
-## 4. Agregar resultados em tabela
+Se `SNAPSHOT_COUNT < 2`, marcar SLO como `no_data`:
+```bash
+if [ "$SNAPSHOT_COUNT" -lt 2 ]; then
+  echo "SLO $SLO_NAME: insufficient snapshots in baseline window ($BASELINE) — got $SNAPSHOT_COUNT, need ≥2"
+  echo "Generate data: invoke 'metrics-snapshot' MCP tool during normal use."
+  STATUS="no_data"
+  continue  # pula para o próximo SLO
+fi
+```
 
+### 3.3 Calcular SLI por tipo de SLO
+
+**Availability (`type: event-based`):**
+
+Inline node — primeiro vs último snapshot dentro da janela. Delta de counters dá good/bad events na janela:
+
+```bash
+SLI_RESULT=$(node --input-type=module -e "
+import { loadSnapshots } from './src/core/metrics.js';
+const snaps = await loadSnapshots(process.cwd(), $BASELINE_MS);
+if (snaps.length < 2) { console.log(JSON.stringify({sli:null, error:'no_data'})); process.exit(0); }
+const first = snaps[0];
+const last = snaps[snaps.length - 1];
+let goodFirst = 0, goodLast = 0, totalFirst = 0, totalLast = 0;
+for (const [k,v] of Object.entries(first.counters)) {
+  if (k.endsWith(':ok')) goodFirst += v;
+  totalFirst += v;
+}
+for (const [k,v] of Object.entries(last.counters)) {
+  if (k.endsWith(':ok')) goodLast += v;
+  totalLast += v;
+}
+const good = goodLast - goodFirst;
+const total = totalLast - totalFirst;
+const sli = total > 0 ? good / total : null;
+const errorRate = total > 0 ? (total - good) / total : 0;
+console.log(JSON.stringify({sli, errorRate, good, total, totalFirst, totalLast}));
+")
 ```
+
+**Latency (`type: percentile`):**
+
+Para latency, usar o p95 do último snapshot na janela (cumulative — FIFO histogram dá p95 sobre as últimas 1000 amostras). SLI = fração de samples acima de target_ms é o budget consumido.
+
+```bash
+SLI_RESULT=$(node --input-type=module -e "
+import { loadSnapshots } from './src/core/metrics.js';
+const snaps = await loadSnapshots(process.cwd(), $BASELINE_MS);
+if (snaps.length < 1) { console.log(JSON.stringify({sli:null, error:'no_data'})); process.exit(0); }
+const last = snaps[snaps.length - 1];
+const target = $TARGET_MS;
+let totalSamples = 0, slowSamples = 0;
+for (const [tool, lat] of Object.entries(last.latency)) {
+  totalSamples += lat.count;
+  if (lat.p95 > target) slowSamples += Math.round(lat.count * 0.05); // approximation: p95 above target → ~5% slow
+}
+const sli = totalSamples > 0 ? 1 - (slowSamples / totalSamples) : null;
+const errorRate = totalSamples > 0 ? slowSamples / totalSamples : 0;
+console.log(JSON.stringify({sli, errorRate, totalSamples, slowSamples, p95Max: Math.max(0, ...Object.values(last.latency).map(l => l.p95 || 0))}));
+")
+```
+
+### 3.4 Calcular burn rate + status
+
+Aplicar fórmula canônica da skill `burn-rate-alerting`:
+
+```bash
+BURN_STATUS=$(node --input-type=module -e "
+const result = $SLI_RESULT;
+if (result.error) { console.log(JSON.stringify({status:'no_data'})); process.exit(0); }
+const target = $TARGET_RATIO || (1 - 0.05); // latency: 1 - ratio_above_target (5%)
+const errorRate = result.errorRate;
+const slack = 1 - target;  // budget = (1 - target)
+const burnRate = slack > 0 ? errorRate / slack : 0;
+
+let status, action;
+if (burnRate >= 14.4) {
+  status = 'PAGE';
+  action = 'Page on-call — invoke /investigar-producao';
+} else if (burnRate >= 6.0) {
+  status = 'TICKET';
+  action = 'Open ticket — investigate before budget exhausted';
+} else if (burnRate >= 1.0) {
+  status = 'WARN';
+  action = 'Monitor — burn rate sustained ≥1× exhausts budget in window';
+} else {
+  status = 'OK';
+  action = '—';
+}
+
+// ETA exhaustion (predictive). For burn_rate=0 (no errors), ETA is ∞.
+const baselineHours = $BASELINE_MS / 3600000;
+const eta = burnRate > 0 ? (1 / burnRate) * 30 * 24 / baselineHours : null; // hours until exhausted
+const etaStr = eta === null ? '—' : (eta < 24 ? eta.toFixed(1) + 'h' : (eta/24).toFixed(1) + 'd');
+
+console.log(JSON.stringify({status, action, burnRate: burnRate.toFixed(2), errorRate: (errorRate*100).toFixed(2), eta: etaStr}));
+")
+```
+
+### 3.5 Acumular linha da tabela
+
+```bash
+SLO_ROWS+=("| $SLO_NAME | ${TARGET_RATIO:-${TARGET_MS}ms p$PERCENTILE} | $BASELINE | ${ERROR_RATE}% | ${BURN_RATE}× | $ETA | **$STATUS** | $ACTION |")
+```
+
+## 4. Renderizar tabela mestra
+
+```text
 ═══════════════════════════════════════════════════════════
  framework ► BURN-RATE-STATUS ▸ {timestamp}
+ baseline=$BASELINE  lookahead=$LOOKAHEAD  snapshots=$TOTAL_SNAPS
 ═══════════════════════════════════════════════════════════
 
-| SLO | Target | Window | Budget gasto | Burn rate | ETA exhaustão | Status | Ação |
+| SLO | Target | Window | Error rate | 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 | — |
+{$SLO_ROWS}
 ```
 
 ## 5. Sugerir próximas ações
 
-Se algum SLO em status PAGE ou TICKET:
-
+```bash
+# Contar status counts
+PAGE_COUNT=$(echo "$SLO_ROWS" | grep -c "PAGE" || echo 0)
+TICKET_COUNT=$(echo "$SLO_ROWS" | grep -c "TICKET" || echo 0)
+WARN_COUNT=$(echo "$SLO_ROWS" | grep -c "WARN" || echo 0)
+NO_DATA_COUNT=$(echo "$SLO_ROWS" | grep -c "no_data" || echo 0)
 ```
-## ⚠ 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)
+Output:
+```text
+## Próximas ações
+
+{Se PAGE_COUNT > 0:}
+⚠ {PAGE_COUNT} SLO(s) em PAGE — invocar /investigar-producao "<slo_name> burn rate {burn_rate}×"
+
+{Se TICKET_COUNT > 0:}
+☐ {TICKET_COUNT} SLO(s) em TICKET — abrir issue, investigar antes do budget esgotar
+
+{Se WARN_COUNT > 0:}
+ⓘ {WARN_COUNT} SLO(s) em WARN — burn rate sustained ≥1× exhausts budget
 
-## SLOs OK:
-- 2 SLOs em compliance saudável
+{Se NO_DATA_COUNT > 0:}
+⊘ {NO_DATA_COUNT} SLO(s) sem dados na janela — invoque o MCP tool 'metrics-snapshot' periodicamente para popular .planning/metrics/snapshots/
 ```
 
-## 6. Modo `/loop`
+## 6. Modo `/loop` (idempotência)
 
 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)
+- Snapshot fresh em cada invocação (não acumular state).
+- Output curto se status não mudou (apenas linha-resumo; sem repetir tabela completa).
+- Acionar AskUserQuestion APENAS quando algum SLO transiciona OK → WARN/TICKET/PAGE.
 
 </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
+- [ ] $ARGUMENTS parseados (SLO opcional + flags --lookahead/--baseline/--format)
+- [ ] SLOs descobertos via glob `.planning/slos/*.yml` (FIX Phase 99: extension `.yml`, não `.md`)
+- [ ] Snapshots carregados via `loadSnapshots()` (Phase 99 — `src/core/metrics.js`)
+- [ ] SLI calculado por tipo (event-based ratio para availability, percentile para latency)
+- [ ] Burn rate calculado pela fórmula `error_rate / (1 - target)` (skill burn-rate-alerting)
+- [ ] Status enum: PAGE / TICKET / WARN / OK / no_data
+- [ ] ETA exhaustão computada (predictive forecast)
+- [ ] Tabela markdown agregada
 - [ ] Sugestões de próximas ações para SLOs em alerta
-- [ ] Idempotente (rodável em /loop sem acúmulo)
+- [ ] Idempotente em /loop (sem acúmulo de state)
+- [ ] no_data graceful — não inventa números, sugere `metrics-snapshot`
 </success_criteria>

package/kit/file-manifest.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.17.0",
-  "timestamp": "2026-05-09T15:58:57.716Z",
+  "version": "1.19.0",
+  "timestamp": "2026-05-09T17:53:53.960Z",
   "files": {
     "COMANDOS.md": "d24ec61a6ec35db314cc5f2ae287bfb927b794789c8f1d558c55862f5e6534b2",
     "COMPATIBILITY.md": "794e336a87045cdf0161785b9a7a0975a49abbd80bdd816b8852251fcc8126ca",
@@ -68,7 +68,7 @@
     "commands/auditar-uat.md": "83e9f21584938350ee96ef0f0bb870786537bf38220c7a8ec0e04d06659c6bda",
     "commands/autonomo.md": "ae5746a8b9cd63d9ac8cf2774b8b466789ccefec3d9e267dcb98d97481ede57f",
     "commands/branch-pr.md": "77866ec7ef8d65ad6cea9d17491b7c7605238b3a3505dd3e128f18cd150c9be4",
-    "commands/burn-rate-status.md": "d5316301d4ac576bf57dbd24a56b1c2063610819520af3f75026499c6525c438",
+    "commands/burn-rate-status.md": "040fcc64b00bf5bcb9b69b7d3c1ef729647ddf0060d232fe061ea70b242747cf",
     "commands/capturar-payloads.md": "507d009d9fb28fe12d18c3d3a599fbb23605254564e5753b056e0f32fb92f20b",
     "commands/caracterizar-prompt.md": "996b923d6c807d94be77d14dbfec3fdabf98d3bf111f6928932421b724847fb3",
     "commands/caracterizar.md": "994ce4136ba44b74890874f3274c26bcdc9f4feb5f4852cb0288687142ab1403",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luanpdd/kit-mcp",
-  "version": "1.17.0",
+  "version": "1.19.0",
   "description": "Generic infrastructure to ship YOUR personal kit of agents/commands/skills as an MCP server, with cross-IDE sync (Claude Code, Cursor, Codex, Gemini, Windsurf, Antigravity, Copilot, Trae).",
   "type": "module",
   "bin": {

package/src/core/metrics.js

@@ -0,0 +1,268 @@
+// OBS-18-01 / OBS-18-02 — in-memory golden signals for kit-mcp server.
+// OBS-19-01 / OBS-19-02 / OBS-19-03 — disk-persistent rolling snapshots.
+//
+// Phase 94: Eat Your Own Dog Food. The skill `four-golden-signals` says any
+// user-facing service worth its salt instruments Latency + Traffic + Errors
+// + Saturation. The MCP server qualifies — every tool call is a request from
+// an LLM client and tail latency / error rate are exactly the signals an
+// operator wants when something feels off.
+//
+// Scope decisions (see .planning/phases/94-golden-signals-mcp-server/94-CONTEXT.md):
+//   - Zero new dependencies. Phase 99 adds fs/promises + path from stdlib only —
+//     the 6-deps budget Phase 92.01 fought to maintain and Phase 93.01 enforces
+//     in CI is preserved.
+//   - In-memory primary, on-demand persistence. The Map+array core stays
+//     in-memory; persistSnapshot writes a JSON file under .planning/metrics/
+//     snapshots/ when called. No background timer, no implicit writes — the
+//     /burn-rate-status command and metrics-snapshot tool are the writers.
+//   - Bounded memory. Histograms cap at HISTOGRAM_CAP=1000 samples per tool
+//     with FIFO drop.
+//   - Bounded disk. cleanupOldSnapshots prunes files > 30 days old on every
+//     persistSnapshot call (rolling window, no separate retention job).
+//   - Snapshot is read-only. Returns a fresh plain-object copy so callers
+//     can JSON.stringify it without exposing internal Map references.
+//   - Persisted shape includes `ts` (epoch ms) inside the JSON. We do NOT
+//     parse the filename for windowing — filesystem-safe ISO encoding
+//     (`replace(/[:.]/g, '-')`) is one-way (cannot reliably round-trip back
+//     through Date.parse) and mtime is unreliable across copy/touch. The
+//     in-file ts is authoritative.
+//
+// API surface (5 exports + 2 async):
+//   incrementInvocation(tool, status)  — counter++ keyed `${tool}:${status}`
+//   recordLatency(tool, ms)            — push to histogram, FIFO at cap
+//   snapshot()                         — { counters, latency } plain object
+//   reset()                            — clear both maps; called on boot if
+//                                         KIT_MCP_METRICS_RESET=1
+//   persistSnapshot(rootDir)           — write {ts, counters, latency} to
+//                                         .planning/metrics/snapshots/<ts>.json
+//                                         + cleanup files > 30d
+//   loadSnapshots(rootDir, windowMs)   — read all snapshots whose in-file ts
+//                                         is within windowMs (default 30d),
+//                                         sorted ascending by ts
+//
+// Boot-time reset honors the env var by calling reset() at module load when
+// the flag is set. This keeps the signal "fresh" for a probe in tests or for
+// an operator who spawned the server with the flag for a clean comparison.
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const HISTOGRAM_CAP = 1000;
+const DEFAULT_RETENTION_MS = 30 * 86400 * 1000; // 30 days rolling.
+const SNAPSHOT_DIR_REL = path.join('.planning', 'metrics', 'snapshots');
+
+const counters = new Map();   // key: `${tool}:${status}` → count (number)
+const histograms = new Map(); // key: tool → number[] (length ≤ HISTOGRAM_CAP)
+
+/**
+ * Increment the invocation counter for a tool/status pair.
+ *
+ * @param {string} tool   Tool name as it appears in the MCP request payload.
+ * @param {'ok'|'error'} [status='ok']  Outcome of the dispatch.
+ * @returns {void}
+ */
+export function incrementInvocation(tool, status = 'ok') {
+  if (typeof tool !== 'string' || tool.length === 0) return;
+  const key = `${tool}:${status}`;
+  counters.set(key, (counters.get(key) ?? 0) + 1);
+}
+
+/**
+ * Record an observed latency for a tool. Drops the oldest sample (FIFO) once
+ * the per-tool histogram reaches HISTOGRAM_CAP, keeping memory bounded across
+ * long-lived MCP sessions.
+ *
+ * @param {string} tool   Tool name.
+ * @param {number} ms     Elapsed wall-clock time in milliseconds.
+ * @returns {void}
+ */
+export function recordLatency(tool, ms) {
+  if (typeof tool !== 'string' || tool.length === 0) return;
+  if (typeof ms !== 'number' || !Number.isFinite(ms) || ms < 0) return;
+  let arr = histograms.get(tool);
+  if (!arr) {
+    arr = [];
+    histograms.set(tool, arr);
+  }
+  arr.push(ms);
+  if (arr.length > HISTOGRAM_CAP) arr.shift(); // FIFO drop oldest sample
+}
+
+/**
+ * Compute a percentile over a sorted ascending array. Linear-interpolation
+ * variant matches the typical Prometheus / Datadog reading. For N≤1000
+ * (HISTOGRAM_CAP) the sort cost on snapshot is acceptable — snapshots are
+ * read on-demand by the metrics-snapshot tool, not on every dispatch.
+ *
+ * @param {number[]} sorted  Ascending-sorted samples.
+ * @param {number} p         Percentile in [0, 1].
+ * @returns {number}
+ */
+function percentile(sorted, p) {
+  if (sorted.length === 0) return 0;
+  if (sorted.length === 1) return sorted[0];
+  const rank = p * (sorted.length - 1);
+  const lo = Math.floor(rank);
+  const hi = Math.ceil(rank);
+  if (lo === hi) return sorted[lo];
+  const frac = rank - lo;
+  return sorted[lo] + (sorted[hi] - sorted[lo]) * frac;
+}
+
+/**
+ * Build a read-only snapshot of all metrics. Counters are returned as a plain
+ * object keyed `${tool}:${status}` → count. Latency is keyed by tool to a
+ * `{ p50, p95, p99, count }` triple so a single tool never appears split
+ * across status outcomes (latency observation point is a single line in the
+ * dispatcher, success and failure both record).
+ *
+ * @returns {{
+ *   counters: Record<string, number>,
+ *   latency:  Record<string, { p50: number, p95: number, p99: number, count: number }>
+ * }}
+ */
+export function snapshot() {
+  const out = { counters: {}, latency: {} };
+  for (const [key, val] of counters) out.counters[key] = val;
+  for (const [tool, samples] of histograms) {
+    if (samples.length === 0) continue;
+    const sorted = [...samples].sort((a, b) => a - b);
+    out.latency[tool] = {
+      p50: percentile(sorted, 0.50),
+      p95: percentile(sorted, 0.95),
+      p99: percentile(sorted, 0.99),
+      count: samples.length,
+    };
+  }
+  return out;
+}
+
+/**
+ * Clear both counters and histograms. Used by tests and by the boot-time
+ * KIT_MCP_METRICS_RESET=1 path so an operator can probe a fresh window.
+ *
+ * @returns {void}
+ */
+export function reset() {
+  counters.clear();
+  histograms.clear();
+}
+
+/**
+ * OBS-19-01 — Persist the current snapshot to disk under
+ * `<rootDir>/.planning/metrics/snapshots/<timestamp>.json`. Runs the rolling
+ * cleanup of files older than `retentionMs` (default 30d) on every call so
+ * callers don't need a separate retention job.
+ *
+ * The on-disk shape is `{ ts: <epoch_ms>, counters, latency }`. The `ts` field
+ * inside the JSON — NOT the filename — is the authoritative timestamp for
+ * loadSnapshots windowing. The filename uses an ISO encoding with `:` and `.`
+ * replaced by `-` for filesystem safety; that encoding is one-way (cannot
+ * round-trip back through Date.parse), so we never parse it for ordering.
+ *
+ * @param {string} [rootDir=process.cwd()]  Project root. Snapshots land under
+ *   `<rootDir>/.planning/metrics/snapshots/`.
+ * @param {object} [opts]
+ * @param {number} [opts.retentionMs]  Override the rolling-window age in ms.
+ *   Defaults to 30 days. Tests use shorter windows to drive the cleanup path.
+ * @returns {Promise<{file: string, snap: {ts: number, counters: object, latency: object}}>}
+ */
+export async function persistSnapshot(rootDir = process.cwd(), opts = {}) {
+  const retentionMs = Number.isFinite(opts.retentionMs) ? opts.retentionMs : DEFAULT_RETENTION_MS;
+  const dir = path.join(rootDir, SNAPSHOT_DIR_REL);
+  await fs.mkdir(dir, { recursive: true });
+  const ts = Date.now();
+  const snap = { ts, ...snapshot() };
+  // Filesystem-safe ISO encoding — Windows forbids `:` in paths and `.` is
+  // ambiguous with extension separators on shells with brace expansion.
+  const isoSafe = new Date(ts).toISOString().replace(/[:.]/g, '-');
+  const file = path.join(dir, `${isoSafe}.json`);
+  await fs.writeFile(file, JSON.stringify(snap, null, 2));
+  await cleanupOldSnapshots(dir, retentionMs);
+  return { file, snap };
+}
+
+/**
+ * OBS-19-02 — Load all snapshots from disk whose in-file `ts` is within the
+ * sliding window. Returns the array sorted ascending by `ts` so consumers
+ * (`/burn-rate-status`) can compute first-vs-last deltas without re-sorting.
+ *
+ * Defensive against malformed JSON: a corrupt file is skipped silently rather
+ * than aborting the whole load. The 30d window is rolling from "now" — pass a
+ * smaller value to drive recent-only views (e.g. `60 * 60 * 1000` for last
+ * hour) when computing burn rate over a baseline window.
+ *
+ * @param {string} [rootDir=process.cwd()]  Project root.
+ * @param {number} [windowMs]  Sliding window in ms. Defaults to 30 days.
+ * @returns {Promise<Array<{ts: number, counters: object, latency: object}>>}
+ *   Empty array if the snapshots directory does not exist.
+ */
+export async function loadSnapshots(rootDir = process.cwd(), windowMs = DEFAULT_RETENTION_MS) {
+  const dir = path.join(rootDir, SNAPSHOT_DIR_REL);
+  const cutoff = Date.now() - windowMs;
+  let files;
+  try {
+    files = await fs.readdir(dir);
+  } catch {
+    return []; // Dir absent on first run — not an error.
+  }
+  const results = [];
+  for (const f of files) {
+    if (!f.endsWith('.json')) continue;
+    try {
+      const raw = await fs.readFile(path.join(dir, f), 'utf-8');
+      const parsed = JSON.parse(raw);
+      if (Number.isFinite(parsed?.ts) && parsed.ts >= cutoff) {
+        results.push(parsed);
+      }
+    } catch {
+      // Corrupt file — skip silently rather than break the whole burn-rate
+      // calculation. A future phase can surface counts via a doctor probe.
+    }
+  }
+  return results.sort((a, b) => a.ts - b.ts);
+}
+
+/**
+ * OBS-19-03 — Internal helper: delete snapshot files older than `maxAgeMs`.
+ * Called from persistSnapshot on every write so retention is implicit.
+ * Uses fs.stat().mtimeMs as the age proxy; we accept the small drift versus
+ * the in-file `ts` because cleanup is best-effort eviction, not authoritative
+ * windowing (loadSnapshots reads the in-file ts).
+ *
+ * @param {string} dir         Absolute path to the snapshots directory.
+ * @param {number} maxAgeMs    Files with mtime older than this are unlinked.
+ * @returns {Promise<void>}
+ */
+async function cleanupOldSnapshots(dir, maxAgeMs) {
+  const cutoff = Date.now() - maxAgeMs;
+  let files;
+  try {
+    files = await fs.readdir(dir);
+  } catch {
+    return;
+  }
+  for (const f of files) {
+    if (!f.endsWith('.json')) continue;
+    const fp = path.join(dir, f);
+    try {
+      const stat = await fs.stat(fp);
+      if (stat.mtimeMs < cutoff) await fs.unlink(fp);
+    } catch {
+      // Unlink can race with concurrent cleanup; ignore ENOENT and friends.
+    }
+  }
+}
+
+// Boot-time reset honors KIT_MCP_METRICS_RESET=1. We call reset() instead of
+// merely skipping init because the maps are already empty at module load —
+// the call is a no-op today but documents the contract for any future module
+// that imports metrics.js after another module has already populated state.
+if (process.env.KIT_MCP_METRICS_RESET === '1') {
+  reset();
+}
+
+// Exported for tests only — keeps the API surface explicit while letting unit
+// tests assert on the FIFO behavior at the boundary.
+export const __TEST_HISTOGRAM_CAP = HISTOGRAM_CAP;
+export const __TEST_SNAPSHOT_DIR_REL = SNAPSHOT_DIR_REL;

package/src/mcp-server/index.js

@@ -1,10 +1,11 @@
-// kit-mcp server — exposes 5 tools, each with action-based dispatch.
+// kit-mcp server — exposes 7 tools, each with action-based dispatch (or none).
 //
-//   kit       action: list-agents | list-commands | list-skills | get | search
-//   sync      action: targets | status | install | remove
-//   gates     action: list | get | for-stage
-//   forensics action: collect | summarize | write-learnings | list-replays | record-replay | load-replay
-//   install   action: targets | install | dry-run                    (registers this MCP into an IDE)
+//   kit              action: list-agents | list-commands | list-skills | get | search
+//   sync             action: targets | status | install | remove
+//   gates            action: list | get | for-stage
+//   forensics        action: collect | summarize | write-learnings | list-replays | record-replay | load-replay
+//   install          action: targets | install | dry-run                    (registers this MCP into an IDE)
+//   metrics-snapshot (parameterless)                                          (OBS-18 four-golden-signals readout)
 //
 // Transport: stdio (MCP standard).
 
@@ -30,6 +31,7 @@ import { recordReplay, listReplays, loadReplay, annotateReplay } from '../core/r
 import { installMcp, listInstallTargets } from './install.js';
 import { ensureSidecar } from '../ui/auto-spawn.js';
 import { wrapProgressForUi } from '../ui/wrapper.js';
+import { incrementInvocation, recordLatency, snapshot as metricsSnapshot } from '../core/metrics.js';
 
 const TOOLS = [
   {
@@ -130,6 +132,17 @@ const TOOLS = [
       required: ['action'],
     },
   },
+  {
+    // OBS-18 (Phase 94.01): expose four-golden-signals data for the MCP server itself.
+    // Read-only (no auth needed beyond the underlying transport): returns counters
+    // keyed `${tool}:${status}` and per-tool latency p50/p95/p99/count.
+    name: 'metrics-snapshot',
+    description: 'Read in-memory golden-signals metrics for this MCP server (counters + latency p50/p95/p99 per tool).',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+    },
+  },
 ];
 
 // DRIFT-13-03: read version from package.json at module load (NOT inside
@@ -292,13 +305,21 @@ async function handleInstall(args) {
   }
 }
 
+// OBS-18 (Phase 94.01): metrics-snapshot is parameterless and read-only.
+// Returns the live snapshot synchronously — no auth, no projectRoot guard
+// (no disk reads, no shell). Wraps in an async fn for handler-API uniformity.
+async function handleMetricsSnapshot() {
+  return metricsSnapshot();
+}
+
 const HANDLERS = {
-  kit:           handleKit,
-  sync:          handleSync,
-  'reverse-sync':handleReverseSync,
-  gates:         handleGates,
-  forensics:     handleForensics,
-  install:       handleInstall,
+  kit:               handleKit,
+  sync:              handleSync,
+  'reverse-sync':    handleReverseSync,
+  gates:             handleGates,
+  forensics:         handleForensics,
+  install:           handleInstall,
+  'metrics-snapshot': handleMetricsSnapshot,
 };
 
 function slim(x) {
@@ -330,12 +351,30 @@ export async function createServer() {
     const { name, arguments: args } = req.params;
     const handler = HANDLERS[name];
     if (!handler) {
+      // OBS-18 (Phase 94.01): unknown-tool path counts as an error against
+      // the unknown name itself — useful signal if a client is mis-spelling
+      // a tool name in production. No latency observation (handler never ran).
+      incrementInvocation(name || 'unknown', 'error');
       return { content: [{ type: 'text', text: JSON.stringify({ error: `Unknown tool: ${name}` }) }], isError: true };
     }
+    // OBS-18 (Phase 94.01): timestamp the dispatch boundary. The four-golden-signals
+    // skill cares about the *user-facing* latency, which for the MCP server is the
+    // time from request receipt (we are inside the SDK callback) to the JSON envelope
+    // being ready. Date.now() is sub-millisecond-cheap and aligns with the bucket
+    // granularity we report (50/100/250/500ms thresholds in CONTEXT.md).
+    const start = Date.now();
     try {
       const result = await handler(args ?? {});
+      recordLatency(name, Date.now() - start);
+      incrementInvocation(name, 'ok');
       return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
     } catch (e) {
+      // OBS-18: still record latency on the error path — half the value of a
+      // latency histogram is catching tail-latency-then-fail patterns. Status
+      // 'error' covers any thrown exception, including Phase 79.01 gates guard
+      // and the validateProjectRoot rejection (Phase 83.01).
+      recordLatency(name, Date.now() - start);
+      incrementInvocation(name, 'error');
       // SEC-14-06: full stack stays in stderr for operator debug; client envelope is sanitized.
       // sanitizeMcpError redacts secrets/paths from e.message, preserves e.code (Phase 83
       // EMANIFESTMISMATCH invariant), and emits NO stack field.