> **See also:** [ROADMAP.md](../ROADMAP.md)

## v1.6.0 — TUI Self-Monitoring Integration

**Status: Planned.** See [plans/ui/PLAN_TUI_PART_3.md](plans/ui/PLAN_TUI_PART_3.md) for the full design.

> **Release Theme**
> This release wires the v0.20.0 self-monitoring stream tables (`df_*`) into
> the TUI, giving operators live visibility into anomaly signals, CDC buffer
> trends, scheduling interference, and efficiency metrics — all driven by
> the same incremental refresh engine. Alongside the new views, the TUI
> architecture is refactored: `AppState` is split into 8 domain-scoped
> sub-structs, polling becomes subscription-based (only active-view data is
> fetched), and CLI/TUI command logic is unified into a shared domain layer.
> Four backend enhancements (`DF-21`–`DF-24`) and two new CLI subcommands
> complete the milestone.
>
> See [plans/ui/PLAN_TUI_PART_3.md](plans/ui/PLAN_TUI_PART_3.md) for the
> full architecture, feature specifications, and phased implementation plan.

### Phase 1 — Architecture Foundation (T15–T16)

| Item | Description | Effort | Ref |
|------|-------------|--------|-----|
| T15 | **AppState domain decomposition.** Split `AppState` into 8 domain structs: `StreamTableDomain`, `CdcDomain`, `DiagnosticsDomain`, `MonitoringDomain`, `SchedulingDomain`, `WatermarkDomain`, `ConfigDomain`, `DogFeedingDomain`. | 1d | [PLAN_TUI_PART_3.md](plans/ui/PLAN_TUI_PART_3.md) §T15 |
| T15 | **Selective polling.** `DataSubscriptions::for_view()` gates Phase 2 queries behind the active view; reduces wasted queries on average. | 0.5d | [PLAN_TUI_PART_3.md](plans/ui/PLAN_TUI_PART_3.md) §T15 |
| T15 | **Poller logic extraction.** Extract `poller/fetchers.rs` (21 `fetch_*()` functions) and `poller/updaters.rs` (21 `apply_*()` functions) for testability. | 1d | [PLAN_TUI_PART_3.md](plans/ui/PLAN_TUI_PART_3.md) §T15 |
| T15 | **CLI/TUI command unification.** Introduce `commands/domain.rs` with shared logic for refresh, pause, resume, fuse reset, repair, and gate/ungate. | 0.5d | [PLAN_TUI_PART_3.md](plans/ui/PLAN_TUI_PART_3.md) §T15 |
| T16 | **Dog-feeding data layer.** Add `DogFeedingDomain` state types, polling queries for all 5 `df_*` stream tables, fixture builders, and contract stubs. | 1d | [PLAN_TUI_PART_3.md](plans/ui/PLAN_TUI_PART_3.md) §T16 |

### Phase 2 — Self-Monitoring TUI Views (T17)

| Item | Description | Effort | Ref |
|------|-------------|--------|-----|
| TUI-1 | **Anomaly Detection view (`a` key).** New view showing `df_anomaly_signals` with severity colors, anomaly type, count, and first/last-seen timestamps. | 4h | [PLAN_TUI_PART_3.md](plans/ui/PLAN_TUI_PART_3.md) §TUI-1 |
| TUI-2 | **Dashboard anomaly badge.** Status ribbon shows active anomaly count in red when `df_anomaly_signals` is non-empty. | 1h | [PLAN_TUI_PART_3.md](plans/ui/PLAN_TUI_PART_3.md) §TUI-2 |
| TUI-3 | **CDC Health sparkline column.** Braille sparkline in CDC Health view showing buffer row-count trend from `df_cdc_buffer_trends`. | 3h | [PLAN_TUI_PART_3.md](plans/ui/PLAN_TUI_PART_3.md) §TUI-3 |
| TUI-4 | **CDC Health spill-risk badge.** `⚠ spill` badge when `df_cdc_buffer_trends` growth rate extrapolates to a breach within 2 cycles. | 1h | [PLAN_TUI_PART_3.md](plans/ui/PLAN_TUI_PART_3.md) §TUI-4 |
| TUI-5 | **Workers Interference sub-tab.** Second tab in Workers view showing `df_scheduling_interference` overlap pairs. | 3h | [PLAN_TUI_PART_3.md](plans/ui/PLAN_TUI_PART_3.md) §TUI-5 |
| TUI-6 | **Workers scheduler overhead bar.** Busy-time ratio bar from `scheduler_overhead()` in the Workers view. | 1h | [PLAN_TUI_PART_3.md](plans/ui/PLAN_TUI_PART_3.md) §TUI-6 |
| TUI-7 | **Dependencies Mermaid/DOT export (`x` key).** Scrollable overlay showing `explain_dag()` Mermaid output; `Ctrl+E` writes to file. | 2h | [PLAN_TUI_PART_3.md](plans/ui/PLAN_TUI_PART_3.md) §TUI-7 |
| TUI-8 | **Header self-monitoring status badge.** `df:N/M` pill in the TUI header bar; turns amber on retention warning. | 1h | [PLAN_TUI_PART_3.md](plans/ui/PLAN_TUI_PART_3.md) §TUI-8 |
| TUI-9 | **Command palette self-monitoring commands.** `self-monitoring enable / disable / status` in palette with confirmation dialogs. | 2h | [PLAN_TUI_PART_3.md](plans/ui/PLAN_TUI_PART_3.md) §TUI-9 |
| TUI-10 | **Detail view anomaly summary.** Active anomaly count row in the Properties section of the detail overlay. | 1h | [PLAN_TUI_PART_3.md](plans/ui/PLAN_TUI_PART_3.md) §TUI-10 |
| TUI-11 | **Refresh Log `[auto]` tag.** Annotate rows with `initiated_by = 'SELF_MONITOR'` in the Refresh Log view. | 1h | [PLAN_TUI_PART_3.md](plans/ui/PLAN_TUI_PART_3.md) §TUI-11 |
| TUI-12 | **First-launch self-monitoring toast.** 10-second hint toast on first launch when self-monitoring is not set up. | 1h | [PLAN_TUI_PART_3.md](plans/ui/PLAN_TUI_PART_3.md) §TUI-12 |
| TUI-13 | **Anomaly signals as Issues.** `detect_issues()` maps active anomaly signals to the Issues view with category "Anomaly". | 1h | [PLAN_TUI_PART_3.md](plans/ui/PLAN_TUI_PART_3.md) §TUI-13 |
| TUI-14 | **`self_monitor_anomaly` alert styling.** Cyan `🔍` icon for anomaly alert type in the Alerts view. | 0.5h | [PLAN_TUI_PART_3.md](plans/ui/PLAN_TUI_PART_3.md) §TUI-14 |
| TUI-15 | **Dashboard snapshot tests.** 5 snapshot branches: standard, wide, empty, anomalies-present, narrow. | 2h | [PLAN_TUI_PART_3.md](plans/ui/PLAN_TUI_PART_3.md) §TUI-15 |
| TUI-16 | **Diagnostics `df_efficiency_rolling` panel.** Aggregate speedup ratio and DIFF/FULL counts from `df_efficiency_rolling`. | 2h | [PLAN_TUI_PART_3.md](plans/ui/PLAN_TUI_PART_3.md) §TUI-16 |
| TUI-D1 | **`docs/TUI.md` documentation update.** Document Anomaly view, CDC sparklines, Workers interference tab, Mermaid export, header badge, and command palette additions. | 2h | [PLAN_TUI_PART_3.md](plans/ui/PLAN_TUI_PART_3.md) §T20 |

### Phase 3 — Backend Enhancements (T18)

| Item | Description | Effort | Ref |
|------|-------------|--------|-----|
| DF-21 | **`sla_breach_risk` column in `df_threshold_advice`.** Boolean: `true` when `avg_diff_ms > freshness_deadline_ms`. | 2h | [PLAN_TUI_PART_3.md](plans/ui/PLAN_TUI_PART_3.md) §DF-21 |
| DF-22 | **`self_monitoring_auto_apply = 'full'` mode.** Widen dispatch interval when `df_scheduling_interference` detects high overlap. | 4h | [PLAN_TUI_PART_3.md](plans/ui/PLAN_TUI_PART_3.md) §DF-22 |
| DF-23 | **`self_monitoring_status()` retention warning.** `retention_warning` column when `history_retention_days` is below the minimum window. | 2h | [PLAN_TUI_PART_3.md](plans/ui/PLAN_TUI_PART_3.md) §DF-23 |
| DF-24 | **`recommend_refresh_mode()` reads from `df_threshold_advice`.** Returns consistent results with the incremental view when self-monitoring is active. | 3h | [PLAN_TUI_PART_3.md](plans/ui/PLAN_TUI_PART_3.md) §DF-24 |
| TEST-21 | **Proptest for `df_threshold_advice` bounds.** 10,000 cases verifying `[0.01, 0.80]` clamping invariant. | 2h | [PLAN_TUI_PART_3.md](plans/ui/PLAN_TUI_PART_3.md) §TEST-21 |

### Phase 4 — CLI Integration (T19)

| Item | Description | Effort | Ref |
|------|-------------|--------|-----|
| CLI-1 | **`pgtrickle self-monitoring` subcommand group.** `enable / disable / status` subcommands with `--format json\|table\|csv` for status. | 4h | [PLAN_TUI_PART_3.md](plans/ui/PLAN_TUI_PART_3.md) §CLI-1 |
| CLI-2 | **`pgtrickle graph --format` flag.** `ascii` (existing) / `mermaid` / `dot` format options for the graph subcommand. | 2h | [PLAN_TUI_PART_3.md](plans/ui/PLAN_TUI_PART_3.md) §CLI-2 |

### Phase 5 — Documentation & Polish (T20)

| Item | Description | Effort | Ref |
|------|-------------|--------|-----|
| DOC-21 | **`docs/GETTING_STARTED.md` Day 2 update.** Document self-monitoring CLI and TUI integration for new users. | 1h | [PLAN_TUI_PART_3.md](plans/ui/PLAN_TUI_PART_3.md) §T20 |
| DOC-22 | **`docs/SQL_REFERENCE.md` update.** Document `df_threshold_advice.sla_breach_risk` column. | 0.5h | [PLAN_TUI_PART_3.md](plans/ui/PLAN_TUI_PART_3.md) §T20 |

### Phase 6 — TUI/CLI Visualization Polish

TUI/CLI visualization enhancement for the self-monitoring views. Recommended from [PLAN_OVERALL_ASSESSMENT.md](plans/PLAN_OVERALL_ASSESSMENT.md) §9.11.

| Item | Description | Effort | Ref |
|------|-------------|--------|-----|
| OP-1 | **DAG runtime overlay in `explain_dag()`.** Colour nodes by p95 latency, width by rows/refresh using `pgt_refresh_history`. Enhances `explain_dag()` visualization for TUI/CLI. | XS (2d) | [PLAN_OVERALL_ASSESSMENT.md](plans/PLAN_OVERALL_ASSESSMENT.md) §9.11 |

### Implementation Phases

| Phase | Description | Duration |
|-------|-------------|----------|
| T15 | Architecture Foundation — AppState decomp, selective polling, poller extraction, CLI unification | Days 1–3 |
| T16 | Self-Monitoring Data Layer — types, polling queries, fixtures, contract stubs | Days 3–5 |
| T17 | Self-Monitoring TUI Views — all 16 TUI items, snapshot + unit tests | Days 5–9 |
| T18 | Backend Enhancements — DF-21 through DF-24, proptest, upgrade SQL | Days 9–12 |
| T19 | CLI Integration — `pgtrickle self-monitoring`, `pgtrickle graph --format` | Days 12–13 |
| T20 | Documentation, Polish & Final Testing — docs, cross-cutting tests, coverage audit | Days 13–15 |
| T21 (OP) | TUI/CLI Polish — DAG runtime overlay in `explain_dag()` | Days 15–16 (parallel or interleaved) |

> **v1.6.0 total: ~3–4 weeks** (TUI self-monitoring integration + DAG visualization polish: architecture + 16 views + 4 backend items + 2 CLI commands + tests + docs)

**Exit criteria:**
- [ ] T15: `AppState` uses 8 domain structs; all existing tests pass; `just lint` clean
- [ ] T15: Selective polling reduces Phase 2 query count for non-subscribed views
- [ ] TUI-1: Anomaly Detection view renders; severity colors correct; empty-state hint shown
- [ ] TUI-2: Dashboard ribbon shows anomaly count; turns red when anomalies present
- [ ] TUI-3: CDC Health sparkline column renders for all sources with trend data
- [ ] TUI-4: Spill-risk badge appears when `df_cdc_buffer_trends` growth rate extrapolates to breach
- [ ] TUI-5: Workers view has Interference sub-tab; overlap pairs render
- [ ] TUI-6: Scheduler overhead bar visible in Workers view after ≥ 5 refresh cycles
- [ ] TUI-7: `x` key on Dependencies view opens Mermaid overlay; `Ctrl+E` exports to file
- [ ] TUI-8: Header `df:N/M` badge reflects active self-monitoring stream tables
- [ ] TUI-9: Command palette `self-monitoring enable/disable` completes with confirmation
- [ ] TUI-15/TUI-T1: All new snapshot tests pass; dashboard snapshots cover 5 branches
- [ ] DF-21: `sla_breach_risk = true` when `avg_diff_ms > freshness_deadline_ms`
- [ ] DF-22: Dispatch interval widens after synthetic interference insertion
- [ ] DF-23: `retention_warning` column non-null when retention below minimum
- [ ] DF-24: `recommend_refresh_mode()` consistent with `df_threshold_advice` when self-monitoring active
- [ ] TEST-21: Proptest passes 10,000 iterations
- [ ] CLI-1: `pgtrickle self-monitoring enable/disable/status` functional
- [ ] CLI-2: `pgtrickle graph --format mermaid` outputs valid Mermaid
- [ ] TUI-D1/DOC-21/DOC-22: Documentation updated
- [ ] Extension upgrade path tested (`1.5.0 → 1.6.0`)
- [ ] `just check-version-sync` passes

---