RFC-0007: TUI v2 read-only cockpit

Version: 0.2.0 | Status: normative | Phase: test

References: RFC-0003, RFC-0006, RFC-0002

1. Summary

[RFC-0007:C-SUMMARY] Summary (Informative)

This RFC defines TUI v2 as a human-first, read-only cockpit for understanding a governed project.

TUI v2 builds on the baseline browsing behavior in RFC-0003, the global search contract in RFC-0002:C-SEARCH-COMMAND, and the loop state model in RFC-0006. It focuses on project overview, artifact discovery, loop state visualization, diagnostics, and readable navigation.

Scope: This RFC covers externally visible TUI behavior and interaction constraints. It does not specify private Rust module layout, ratatui widget internals, or a full interactive artifact editor.

Rationale: The existing TUI is useful for browsing RFCs, ADRs, and work items, but it does not expose newer governance concepts such as search, loop local state, dependency DAGs, guards, releases, or check diagnostics. TUI v2 should help a human understand project state quickly without creating a second mutation surface parallel to the CLI.

Since: v0.1.0

2. Specification

[RFC-0007:C-READ-ONLY] Read-only cockpit boundary (Normative)

TUI v2 MUST be read-only for governed project state in its first implementation phase.

TUI v2 MUST NOT create, edit, delete, move, finalize, accept, reject, supersede, deprecate, render, or otherwise mutate governed artifacts.

TUI v2 MUST NOT mutate persisted loop state or round artifacts under .govctl/loops/.

TUI v2 MAY refresh disposable derived local indexes under .govctl/ only when doing so follows the freshness and local-state rules defined by RFC-0002:C-SEARCH-COMMAND.

When TUI v2 presents an operation that would mutate state, it MUST present it as a suggested CLI command or help text rather than executing it.

Rationale: The CLI already owns mutation semantics, dry-run behavior, diagnostics, lock handling, and lifecycle gates. Keeping the first TUI v2 phase read-only gives humans a richer project cockpit without creating a second, weaker edit model.

Since: v0.1.0

[RFC-0007:C-RESPONSIBILITY-BOUNDARIES] TUI responsibility boundaries (Normative)

TUI v2 MUST keep terminal I/O, input dispatch, data loading, and rendering as separate responsibilities.

The terminal adapter MUST be limited to terminal lifecycle, event polling, event reading, frame drawing, and shutdown handling.

Input dispatch MUST translate keyboard input into in-memory TUI state transitions.

Input dispatch MUST NOT perform filesystem I/O, database access, command execution, terminal drawing, or governed artifact mutation.

Renderers MUST read already-loaded TUI state and draw frames.

Renderers MUST NOT load project artifacts, refresh indexes, execute commands, mutate governed state, or mutate persisted loop state.

Data-loading code MUST convert filesystem, schema, search-index, and loop-state failures into visible diagnostic state rather than hiding them from the cockpit.

New primary views or key-routing behavior SHOULD be covered by focused state-transition tests, renderer tests using a terminal test backend, or both.

Rationale: These boundaries keep TUI v2 human-facing, read-only, and testable without creating a second hidden execution model beside the CLI.

Since: v0.2.0

[RFC-0007:C-COCKPIT-VIEWS] Cockpit view model (Normative)

TUI v2 MUST provide a top-level human navigation model with visible entry points for overview, artifact browsing, search, loops, and diagnostics.

The overview view MUST summarize at least RFCs, ADRs, work items, and verification guards when those artifacts are available.

The artifact browsing views MUST preserve the existing RFC, ADR, and Work Item browsing capabilities required by RFC-0003.

The artifact browsing views SHOULD include verification guards, clauses, releases, and tags when those data sources can be loaded without violating RFC-0007:C-READ-ONLY.

The current view, selection context, active filter or query, and primary key bindings MUST remain visible or discoverable without leaving the TUI.

Rationale: A cockpit should orient a human before asking them to drill into details. The top-level model makes newer governance concepts discoverable while preserving the older RFC/ADR/Work browsing workflows.

Since: v0.1.0

[RFC-0007:C-LOOP-VIEWS] Loop state views (Normative)

TUI v2 MUST provide a loop list view that discovers persisted loop states according to RFC-0006:C-LOOP-LISTING.

Each listed loop MUST show the loop ID, lifecycle state, editable work roots, resolved work item count, aggregate round count, and next action when those values are present in valid loop state.

TUI v2 MUST provide a loop inspector for a selected loop.

The loop inspector MUST show the selected loop’s lifecycle state, current round, next action, editable work roots, resolved work set, loop-level item statuses, round counts, and dependency information.

If a loop state file is invalid, TUI v2 MUST present a readable diagnostic for that loop and MUST NOT treat invalid loop state as authoritative.

TUI v2 MUST NOT repair, replan, resume, run, or otherwise mutate loop state while rendering loop views.

Rationale: Loop state is local but highly useful to humans resuming or auditing work. The TUI should expose this state directly while preserving RFC-0006 ownership of loop execution semantics.

Since: v0.1.0

[RFC-0007:C-LOOP-DAG] Loop dependency DAG visualization (Normative)

TUI v2 MUST render a selected loop’s dependency graph as a visual DAG derived from the loop state’s dependencies table.

The DAG view MUST represent every work item in the loop state’s resolved work set unless viewport constraints require an explicit neighborhood or layer-limited fallback.

The DAG view MUST distinguish loop-level item statuses such as pending, active, done, failed, blocked, and cancelled using readable text and semantic styling.

The DAG view MUST make the selected work item visually distinct and MUST show its direct dependencies and direct dependents when that information is available.

The DAG layout MUST be deterministic for the same loop state.

When the graph is too large or the terminal viewport is too small for a full DAG, TUI v2 MUST degrade to a readable representation that still exposes ordering, dependencies, selected item context, and hidden item counts.

Rationale: A plain topological list is not enough for humans to understand batch execution. A visual DAG exposes why work is ready, blocked, or downstream of another item while still allowing terminal-size fallbacks.

Since: v0.1.0

[RFC-0007:C-SEARCH] TUI search (Normative)

TUI v2 MUST provide a search view for governed artifacts.

The search view MUST interpret query text according to RFC-0002:C-SEARCH-COMMAND rather than exposing backend-specific raw query syntax.

The search view SHOULD support artifact type filtering and tag filtering when the terminal interaction model can expose those filters clearly.

Search results MUST show at least artifact kind, ID, title, and enough snippet or metadata context for a human to choose a result.

Selecting a search result MUST navigate to the corresponding TUI detail view when that artifact kind is supported by TUI v2.

Search result loading MUST follow the read-only boundary in RFC-0007:C-READ-ONLY.

Rationale: Search is the fastest way for humans to recover context in a large governed repository. Reusing the CLI search contract prevents TUI search from drifting into a separate discovery model.

Since: v0.1.0

[RFC-0007:C-DIAGNOSTICS] Diagnostics view (Normative)

TUI v2 MUST provide a diagnostics view that presents project check diagnostics to a human.

The diagnostics view MUST show diagnostic severity, code, message, and target context when those fields are available.

The diagnostics view SHOULD group or filter diagnostics by severity and artifact target.

When a diagnostic target corresponds to an artifact that TUI v2 can display, selecting the diagnostic SHOULD navigate to that artifact’s detail view or an equivalent contextual view.

The diagnostics view MUST NOT automatically apply migrations, edit artifacts, render documents, or run mutation commands to resolve diagnostics.

Rationale: govctl check is the central safety signal for governed work. TUI v2 should make those diagnostics easier for a human to triage without turning validation into an implicit repair workflow.

Since: v0.1.0

[RFC-0007:C-HUMAN-UX] Human-first terminal UX (Normative)

TUI v2 MUST optimize rendered screens for human comprehension rather than machine parsing.

TUI v2 MUST use consistent semantic styling for artifact kind, lifecycle status, phase, diagnostic severity, loop item status, selection, and muted secondary information.

TUI v2 MUST preserve keyboard-only navigation across all primary views.

TUI v2 MUST expose view-specific key bindings through persistent footer text, help overlay, or an equivalent discoverable mechanism.

TUI v2 MUST avoid layouts where essential text overlaps, truncates without context, or becomes unreadable on common narrow terminal widths.

When a terminal is too small for the preferred layout, TUI v2 MUST fall back to a simpler readable layout rather than preserving a broken multi-pane layout.

Rationale: A human-facing terminal UI succeeds when state, hierarchy, and next steps are quickly legible. Visual polish should come from semantic consistency and resilient layout, not from decorative complexity.

Since: v0.1.0

Changelog

v0.2.0 (2026-06-07)

Specify TUI responsibility boundaries

Added

• Require terminal I/O, input dispatch, data loading, and rendering to remain separate testable responsibilities

v0.1.0 (2026-06-06)

Initial draft