diff --git a/BACKLOG.md b/BACKLOG.md index ca44c1d3..814fb16c 100644 --- a/BACKLOG.md +++ b/BACKLOG.md @@ -34,8 +34,11 @@ f8fd260) — those are RETRO candidates once live-QA'd. Remaining: `lastGlobalSequence()` read as a responsiveness heartbeat (DEGRADED on throw or over `event_store_latency_warn_ms`); read-only by design (no probe writes into the log). QA gate in §F → `docs/qa/QA-event-store-health-probe.md`. -- [ ] **§4/§3 live health TUI pane** — deferred to follow the metrics cadence - (projection + CLI first, then pane). `correx health` CLI already exists. +- [~] **§4/§3 live health TUI pane** — **SHIPPED (pending live-QA)** `fd67a6c`. `OverlayHealth` (key `H` / + palette "health checks") mirrors the stats pane: pull-based fetch over WS + (`GetHealthChecks` → `health.checks`/`HealthReport`), per-subject status with degraded loud, visible + fallback when disabled. QA gate in §F → `docs/qa/QA-health-tui-pane.md`. **With all three probes + + this pane, §4 health-checks is feature-complete in code** — retire as a unit once the QA gates pass. - [ ] **§3 tier-2 stats** — full session-completion summary pane polish (basic pane shipped). - 🚫 **§3 tier-3 Prometheus/Grafana export** — spec says "deferred indefinitely". **Do not build.** @@ -130,6 +133,8 @@ These are SHIPPED in code but prompt-/server-/network-dependent and not yet live restart hysteresis, replay independence). - [ ] **EVENT_STORE health probe live-QA** — `7a1362c`. Plan: `docs/qa/QA-event-store-health-probe.md` (responsive→HEALTHY, no-log-pollution, slow/throw→DEGRADED, restore hysteresis, replay independence). +- [ ] **Health TUI pane live-QA** — `fd67a6c`. Plan: `docs/qa/QA-health-tui-pane.md` (`H` opens/fetches, + matches `correx health`, degraded loud, disabled fallback, resize, live wire-contract values). - [ ] **TUI kernel-steering + AMD gauge fresh live-QA** — approve+note actually revising the *same* stage's output; AMD VRAM/RAM gauge on the real box. - [ ] **Unit-tested-only fixes, not live-verified:** `1a7eb05` (verdict-edge rejection), diff --git a/docs/qa/QA-health-tui-pane.md b/docs/qa/QA-health-tui-pane.md new file mode 100644 index 00000000..ac6ede16 --- /dev/null +++ b/docs/qa/QA-health-tui-pane.md @@ -0,0 +1,51 @@ +# QA Plan: health-checks TUI pane — fd67a6c + +Observability spec §4 / §3-tier-2. Drafted from the diff (commit `fd67a6c`) per the BACKLOG QA rule. + +**Status:** DRAFT +**Run date / operator:** +**BACKLOG item:** §A "§4/§3 live health TUI pane". + +--- + +## Preconditions + +- [ ] **server build/branch:** master @ `fd67a6c` (or later); TUI rebuilt from `apps/tui-go`. +- [ ] **config:** `[health].enabled = true` so probes actually run and emit (else the pane should show the disabled fallback — that's check 5). +- [ ] **at least one probe able to flip:** easiest is the EVENT_STORE or DISK probe (lower `event_store_latency_warn_ms` / `disk_warn_bytes` to force a DEGRADED), or stop llama-server for the LLAMA_SERVER probe. +- [ ] TUI connected to the server over WS. + +## Acceptance gate (one sentence) + +> The pane is correct **iff** pressing `H` fetches and renders the current per-subject health +> (LLAMA_SERVER / EVENT_STORE / DISK) with HEALTHY/DEGRADED matching `correx health`, degraded +> rows visually loud, and an empty/disabled report shows a visible fallback (never blank). + +## Checks + +| # | Action | Expected observable evidence | Result | +|---|--------|------------------------------|--------| +| 1 | In a session (or idle), press `H` | Health pane opens; brief loading state, then per-subject rows render. Footer/palette lists `H health` / "health checks" | | +| 2 | Compare pane to CLI | Pane's subjects + statuses match `correx health` / `GET /health/checks` exactly (same overall + per-subject status/metric/value/detail) | | +| 3 | Force a DEGRADED (e.g. stop llama-server, or lower a threshold), reopen `H` | The affected subject shows DEGRADED in the loud/red color; detail string matches the probe's; healthy subjects stay in the OK color | | +| 4 | Restore, reopen `H` | Subject back to HEALTHY; pane reflects the restored state (fresh fetch each open — no stale cache) | | +| 5 | Set `[health].enabled=false` (or fresh log w/ no health events), reopen `H` | Visible fallback line ("no health probes recorded — health monitoring may be disabled"), never a blank pane | | +| 6 | Press `H` again / `esc` | Pane closes cleanly; no stuck loading state; returns to prior view | | +| 7 | Resize terminal with the pane open | No corruption; rows reflow; footer hint present in both wide and narrow layouts | | +| 8 | (wire contract, live) Confirm values aren't silently zeroed | observedValue / metric / detail / since all populated (not 0/empty) for a real subject — proves the Go↔Kotlin field names match at runtime, not just in golden tests | | + +Evidence sources: the TUI render, `correx health` / `GET /health/checks` for cross-check, server WS logs +(`GetHealthChecks` → `health.checks`). + +## Out of scope (NOT covered this pass) + +- The probes themselves (separate plans: `QA-llama-health-probe.md`, `QA-event-store-health-probe.md`; + disk probe shipped earlier in f8fd260). +- Live-push of health (pane is pull-on-open by design, mirroring the stats pane). + +## Disposition + +- **PASS** → MOVE the §A "live health TUI pane" entry into `RETRO.md` (cite `fd67a6c`, run date, evidence). + With all three probes + the pane QA'd, the §4 health-checks feature can be retired from BACKLOG as a unit. +- **FAIL** → file each failure as a numbered finding back into `BACKLOG.md` (action + repro + wrong/missing + signal), fix, re-run only the failed checks. Set Status: FAILED until green.