@luanpdd/kit-mcp 1.18.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.18.0",
-  "timestamp": "2026-05-09T17:01:35.745Z",
+  "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.18.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

@@ -1,4 +1,5 @@
 // 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
@@ -7,31 +8,48 @@
 // operator wants when something feels off.
 //
 // Scope decisions (see .planning/phases/94-golden-signals-mcp-server/94-CONTEXT.md):
-//   - Zero dependencies. Map + array stdlib only — preserves the 6-deps budget
-//     that Phase 92.01 fought to maintain and that Phase 93.01 enforces in CI.
-//   - In-memory only. No file persistence, no socket export, no OTel SDK.
-//     kit-mcp is a developer tool launched on demand by an IDE; cross-process
-//     telemetry pipelines are explicit non-goals (see <deferred> block in
-//     94-CONTEXT.md). A future phase can layer OTel on top of this API.
+//   - 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. At cap, p50/p95/p99 over the latest 1000 samples is
-//     more useful than an unbounded array that could grow for the lifetime
-//     of a long-lived MCP session.
+//     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 (4 exports):
+// 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)
@@ -130,6 +148,112 @@ export function reset() {
   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
@@ -141,3 +265,4 @@ if (process.env.KIT_MCP_METRICS_RESET === '1') {
 // 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;