Core Kernel Console UX & Responsive Feedback Audit
Subject: Console UX, Responsive Progress Feedback, and Zero-Stall User Experience
Auditor: Community CLI Ergonomics & Developer Experience
Standard: Responsive Visual Step Tracking with Structured Stream Suppression
Timestamp: 2026-10-06
1. Executive Summary
A critical dimension of developer ergonomics and autonomous agent usability is responsive progress feedback. When operators or orchestrators initiate multi-step, resource-intensive pipelines (such as system integrity checks, graph mutations, or batch validations), silent execution intervals leave users uncertain whether the process is progressing, stalled, or deadlocked.
This audit evaluated console feedback ergonomics across the ZQK CLI, diagnosed feedback gaps in asynchronous execution paths, and established a unified console progress architecture.
Key Accomplishments:
- Interactive Step Progress (
pkg/cli/ux): ImplementedStepTrackerproviding real-time stage updates, active spinner animation, and millisecond-accurate elapsed duration formatting[0.45s]upon stage completion or failure. - Seamless Async Pipeline Integration (
pkg/cliapp): Linkedux.StepTrackerintoRunWithAsyncProgress, instantly empowering over 50 CLI subcommands with interactive visual feedback without requiring per-command manual rewiring. - Strict Non-Interactive & Structured Log Suppression: Implemented robust suppression rules that disable ANSI spinners and escape codes whenever output is redirected to pipes, executed within CI environments (
CI=true), invoked under automated profiles (ai-agent,mcp), or formatted as structured data (--format json,--format yaml).
flowchart TD
subgraph CLI Execution
CMD[Command Invocations] --> BIND[cliapp.BindAsyncProgress]
end
subgraph Environment & Profile Detection
BIND --> DETECT{Evaluate UX Context}
DETECT -->|TTY + Human + Table/Text| INTERACTIVE[Interactive Mode]
DETECT -->|CI / Pipe / JSON / Agent Profile| HEADLESS[Structured Headless Mode]
end
subgraph Console Feedback Layer
INTERACTIVE --> SPINNER[Live Animated Spinner + Elapsed Timer]
SPINNER --> COMPLETE[✓ Step Completed Duration ms]
HEADLESS --> SILENT[Zero ANSI Codes / Pure JSON/YAML Stream]
end
2. Problem Diagnosis & Ergonomics Evaluation
Prior to this hardening cycle:
pkg/cli/ux/spinner.gocontained a basicStartSpinner/StopSpinnerwrapper aroundbriandowns/spinner, but lacked elapsed duration tracking, step lifecycle management, and integration with command runners.pkg/cliapp/async_progress.gohandled background heartbeat telemetry for coordinator events, but did not emit live console progress to the human terminal.- Terminal commands that executed longer than 200ms appeared completely silent to operators until final output rendering.
3. Implemented Architecture
3.1 StepTracker & High-Resolution Timing (pkg/cli/ux/spinner.go)
StepTracker manages sequential pipeline stages with microsecond precision:
type StepTracker struct {
mu sync.Mutex
stepName string
startTime time.Time
active bool
}
Update(detail string): Updates active spinner suffix in-flight.Complete(summary string): Halts spinner and renders green checkmark with elapsed time:✓ Schema validation [120ms].Fail(summary string, err error): Halts spinner and renders red cross with error details and duration:✗ Sync failed: connection reset [450ms].
3.2 Unified Integration via RunWithAsyncProgress (pkg/cliapp/async_progress.go)
By hooking StepTracker directly into RunWithAsyncProgress, all commands utilizing cli.BindAsyncProgress inherit responsive progress:
sequenceDiagram
autonumber
actor Operator as Human Operator / Agent
participant CLI as zqk CLI
participant UX as pkg/cli/ux
participant Backend as Storage / Validation Engine
Operator->>CLI: zqk system check BLI-001
CLI->>UX: NewStepTracker("Running system_check")
UX-->>Operator: ⠋ Running system_check...
Backend->>CLI: Progress Callback ("spec", "validating schema")
CLI->>UX: Update("spec: validating schema")
UX-->>Operator: ⠙ Running system_check (spec: validating schema)...
Backend-->>CLI: Complete
CLI->>UX: Complete("system_check completed")
UX-->>Operator: ✓ system_check completed [42ms]
3.3 Negative Boundary: Suppression Discipline
To ensure machine readability for LLM agents, CI pipelines, and piped consumers:
- TTY checks verify
term.IsTerminal(os.Stdout.Fd()). - Environment flags
CI,TERM=dumb, andZQK_NON_INTERACTIVEforce non-interactive mode. - Non-human context profiles (
ai-agent,mcp) and non-text formats (json,yaml,json-rpc) dynamically suppress visual spinners viaux.SetSuppressed(true):
flowchart LR
A["Caller Profile: ai-agent"] --> SUPPRESS["ux.SetSuppressed(true)"]
B["Flag: --format json"] --> SUPPRESS
C["Flag: --quiet"] --> SUPPRESS
D["Env: CI=true"] --> SUPPRESS
SUPPRESS --> OUT["Clean Stream Output (No ANSI Escape Codes)"]
4. Verification & Criteria Proofs
| Criteria Reference | Specification | Verification Result | Status |
|---|---|---|---|
CRIT-UX-PROGRESS-001 |
Static Floor: Commands >200ms bind unified console progress emitter | Verified: RunWithAsyncProgress wraps >50 CLI commands with StepTracker |
PASS |
CRIT-UX-ELAPSED-002 |
Operational Proof: Interactive sessions display active step name and elapsed timer | Verified: TestStepTracker_CompleteAndFail validates elapsed duration and step updates |
PASS |
CRIT-UX-SUPPRESSION-003 |
Negative Boundary: Non-interactive/JSON executions suppress ANSI codes | Verified: TestSuppressionControl proves zero ANSI codes on JSON, quiet, CI, and agent profiles |
PASS |
5. Traceability Architecture
flowchart LR
REQ["Requirement:<br/>Console UX & Zero-Stall User Experience"]
CRIT1["Criteria 1:<br/>Unified Console Progress Emitter"]
CRIT2["Criteria 2:<br/>Elapsed Timer & Step Display"]
CRIT3["Criteria 3:<br/>Clean Structured Log Suppression"]
TST["Verification Suite:<br/>pkg/cli/ux/spinner_test.go"]
IMPL["Implementation:<br/>StepTracker & cliapp Integration"]
REQ --> CRIT1
REQ --> CRIT2
REQ --> CRIT3
CRIT1 --> TST
CRIT2 --> TST
CRIT3 --> TST
TST --> IMPL