CLI Explainability & Health Check Registry Guide (zqk explain & zqk healthchk)
1. Overview & System Mission
The ZQK Knowledge Kernel pairs deterministic, fail-closed operations with rich operator telemetry and explainability. Two dedicated command surfaces enable agents and humans to understand system nomenclature and monitor subsystem vitality:
- Kernel Explainability & Acronyms (
zqk explain): Provides instantaneous disambiguation and definition lookup for core domain acronyms (BLI,PRI,REQ,CRIT,TST,ATK,EPC,MIL), dynamically discovers customglossary_termobjects registered in the kernel, provides Levenshtein-distance fuzzy suggestions on unrecognized terms, and synchronizes canonical taxonomies into kernel schemes (--sync). - Health Check Registry (
zqk healthchk): Manages and inspects pluggable health monitors (autonomy_inbox,object_volume,scheduler_events,stream_volume,wal_backlog), records historical execution journals into WAL change entries, and enables atomic runtime state updates (enable/disable/bulk).
┌────────────────────────────────────────────────────────────────────────────────────────┐
│ EXPLAINABILITY & HEALTH REGISTRY │
│ │
│ Operator / Agent Query Knowledge Kernel Vocabulary │
│ ┌────────────────────────┐ ┌─────────────────────────────┐ │
│ │ zqk explain BLI │ ──────────► │ Scheme: VOC-KERNEL-ACRONYMS │ │
│ └────────────────────────┘ │ Term: Backlog Item (BLI) │ │
│ └─────────────────────────────┘ │
│ │
│ Subsystem Telemetry Pluggable Health Registry │
│ ┌────────────────────────┐ ┌─────────────────────────────┐ │
│ │ zqk healthchk run │ ──────────► │ - autonomy_inbox │ │
│ └────────────────────────┘ │ - object_volume │ │
│ │ - scheduler_events │ │
│ │ - wal_backlog │ │
│ └─────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────────────────────────┘
2. Kernel Acronyms & Explainability (zqk explain)
2.1 Basic Usage & Discovery
# List all registered acronyms in a clean, aligned console table
zqk explain
# Explain a specific kernel term
zqk explain BLI
# Output definition in machine-readable JSON
zqk explain BLI -f json
# Sync canonical acronyms into kernel storage scheme VOC-KERNEL-ACRONYMS
zqk explain --sync
# Query against a specific vocabulary scheme
zqk explain --scheme VOC-CUSTOM-TERMINOLOGY
2.2 Term Resolution Hierarchy
When an operator queries a term (e.g. zqk explain <CODE>):
- Kernel Storage Lookup: Inspects active storage for
glossary_termobjects matching the code under the target scheme (VOC-KERNEL-ACRONYMS). Any term minted dynamically in storage is immediately queryable. - Built-in Fallback: If storage is unavailable or term is not yet synced, falls back to compiled-in static definitions.
- Fuzzy Did-You-Mean Hints: If the term is unknown, calculates closest Levenshtein distance matches and emits a structured hint:
text Error: unknown kernel acronym "BL". Did you mean: BLI? Run 'zqk explain' without arguments to see all registered acronyms
2.3 Output Formatting
Single item explain outputs all key facets:
ACRONYM : BLI
FULL NAME : Backlog Item
CATEGORY : work
DEFINITION : A discrete, tracked work package or deliverable scheduled within a Priority Plan.
CONTEXT : operational
RELATED : PRI, REQ, CRIT, ATK
3. Pluggable Health Check Registry (zqk healthchk)
3.1 Architecture & Monitor Suite
Health checks are modular Monitor interfaces registered in healthcheck.DefaultRegistry:
autonomy_inbox: Audits message queues and dispatch backlogs for unattended tasks.object_volume: Monitors CAS object counts and verifies storage capacity envelopes.scheduler_events: Evaluates scheduler loop health, heartbeat freshness, and dead-letter count.stream_volume: Tracks real-time event stream throughput and ingestion lag.wal_backlog: Ensures WAL journals are draining cleanly without uncommitted transaction leaks.
3.2 Command Surface
List Registered Monitors
zqk healthchk list
Outputs table of monitor ID, human-readable name, and enabled state (true/false).
Enable or Disable Monitors
# Disable a monitor
zqk healthchk update object_volume --enabled=false
# Re-enable monitor
zqk healthchk update object_volume --enabled=true
Execute Monitors
# Run all enabled monitors
zqk healthchk run
# Run a specific monitor
zqk healthchk run wal_backlog
# Run in JSON format
zqk healthchk run wal_backlog --format json
Single-monitor runs automatically record an audit entry via storage.CreateHealthCheckChangeJournalEntry, ensuring long-term health telemetry is preserved.
Bulk Disable
# Disable via comma-separated IDs
zqk healthchk bulk disable --ids "object_volume,stream_volume"
# Disable via configuration file (YAML list or newline-separated IDs)
zqk healthchk bulk disable --ids-file disabled_monitors.yaml
4. Verification & Testing Standards
All code and test suites supporting cmd/zqk/explain and cmd/zqk/healthchk adhere to:
- Statement Test Coverage Floor: Must meet or exceed >=80.0% statement coverage across both packages (
go test -v -cover ./cmd/zqk/explain ./cmd/zqk/healthchk). Current verification: cmd/zqk/explain: 90.3%cmd/zqk/healthchk: 90.6%- Test Isolation: All tests construct isolated project fixtures via
testkit.PrepareIsolatedTempProjectto prevent repository mutation and ensure reproducible test results. - Fail-Closed Verification: Validates negative boundaries, fuzzy suggestions, invalid monitor update handling, and error routing when required flags are omitted.