CLI Test Subsystem Architectural & Operational Guide
Overview
The ZQK Test Subsystem (cmd/zqk/test) provides automated test execution, dynamic discovery, test-to-requirement lineage binding, real-time event streaming, parallel safety auditing, and schema plane contamination detection for the Zen Quantum Kernel.
Unlike traditional test runners that execute isolated unit suites and report ephemeral console summaries, the ZQK Test Subsystem integrates tests directly with the persistent Knowledge Kernel graph. Test cases (test_case) serve as verifiable, unified execution wrappers that satisfy timeless functional contracts (requirement) across three rigorous dimensions of proof. Through the Content Addressable Storage (CAS) layer, lifecycle Write-Ahead Log (WAL), and reactive TUI test dashboard, test executions emit shockwave events that automatically transition criteria and parent requirements from originated draft states to verifiable completion.
zqk test <subcommand> [flags]
Subsystem Command Taxonomy
The zqk test suite encompasses core verification commands, AST audits, interactive terminal dashboards, and relational repair assistants:
| Command / Invocation | Primary Mode | Description & Operational Behavior |
|---|---|---|
zqk test run [tc_ids...] |
Test Execution | Executes one or more specified test_case objects or passes --all to run the active working set. Evaluates mapped criteria, streams logs, and triggers state transitions. |
zqk test discover [paths...] / scan |
Dynamic Discovery | Scans Go ASTs, test files, and project directories to identify automated test targets, extracts criteria tags, and optionally synchronizes (--sync) them as CAS test_case objects. |
zqk test dashboard / matrix |
TUI Radar & Matrix | Renders an interactive or static criteria radar and test matrix projection. Displays active working sets, intact vs. broken lineage chains, and completion progress bars. |
zqk test dashboard --watch / watch |
Continuous Watch | Subscribes to the lifecycle WAL (lifecycle.LifecycleEvent) and updates the full-screen terminal radar in real time as criteria are satisfied. |
zqk test bind [tc_id] |
Lineage Assistant | Inspects broken or orphaned test cases lacking parent requirement or root goal bindings. Offers interactive recommended bindings and automated batch repair (--auto). |
zqk test check-contamination |
Schema Plane Guard | Executes a test command while snapshotting the schema plane (.zqk/process) before and after, asserting zero file modification or contamination during testing. |
zqk test identify-parallel |
Concurrency Audit | Analyzes Go AST test functions for parallel execution safety (t.Parallel()), detecting shared mutable state, environment manipulation (Setenv), or unsafe patterns. |
zqk test stream [pkg] |
Real-Time Runner | Runs Go test suites with live JSON/text streaming, sub-process timeout enforcement, and aggregate status reporting. |
zqk test flaky |
Flakiness Diagnostic | Inspects test run histories, quarantine statuses, and variance metrics to isolate non-deterministic test failures before release gating. |
Command Flags & Common Options
The test subsystem provides fine-grained control over execution, filtering, output formatting, and storage synchronization:
| Command | Flag | Short | Default | Description |
|---|---|---|---|---|
run |
--all |
-a |
false |
Execute all active and draft test cases discovered in the kernel. |
run |
--dry-run |
-n |
false |
Preview test commands and invocation mapping without executing processes. |
run |
--verbose |
-v |
false |
Stream full command stdout, stderr, and shockwave transition notices. |
run |
--timeout |
0 |
Per-test execution timeout duration (e.g. 30s, 2m). |
|
run |
--criteria |
-c |
[] |
Filter execution to specific criterion IDs within the test case. |
discover |
--lang |
-l |
"" |
Comma-separated language filters (e.g. go,python,ts). |
discover |
--sync |
-s |
false |
Materialize discovered targets as persistent test_case objects in CAS. |
discover |
--format |
-f |
text |
Output serialization format: text, json, yaml. |
dashboard |
--view |
active |
Working set view filter: active (in-flight), regression (complete), all. |
|
dashboard |
--watch |
-w |
"" |
Polling/streaming interval for live WAL updates (e.g. 2s). |
dashboard |
--check-dod |
false |
TPM Definition of Done gate: fails closed if any active lineage chain is broken. | |
dashboard |
--refresh |
-r |
false |
Bypass materialized lite-file cache and perform synchronous storage re-scan. |
bind |
--req |
"" |
Explicitly bind parent requirement ID to test case. | |
bind |
--goal |
"" |
Explicitly bind root goal ID to parent requirement. | |
bind |
--auto |
false |
Automatically resolve and bind best-match parent entities across all broken chains. |
Core Architecture & Execution Topology
The Test Subsystem bridges CLI user experience with ontological kernel storage (pkg/storage), lifecycle event logging (pkg/lifecycle), and AST analysis (pkg/testrunner, pkg/testdiscovery).
flowchart TD
subgraph CLI["CLI Ingestion Surface (cmd/zqk/test)"]
CmdRun["zqk test run"]
CmdDisc["zqk test discover / scan"]
CmdDash["zqk test dashboard / matrix"]
CmdBind["zqk test bind"]
CmdContam["zqk test check-contamination"]
CmdPar["zqk test identify-parallel"]
CmdStream["zqk test stream"]
end
subgraph Pipeline["Test Execution & Discovery Engine"]
Runner["testrunner.RunTestCase"]
Discovery["testdiscovery.Engine"]
SafetyScanner["testrunner.ScanParallelSafety"]
PlaneSnap["testrunner.SnapshotPlane"]
end
subgraph Kernel["Knowledge Kernel & Storage"]
CAS["Content Addressable Storage (CAS)"]
WAL["Lifecycle Write-Ahead Log (WAL)"]
Accumulator["Dashboard Lite Accumulator Engine"]
end
subgraph Verification["Three-Fold Proof Invariant"]
StaticFloor["1. Static Floor Invariant (Type & Schema Validation)"]
DynamicProof["2. Operational Dynamic Proof (Functional Behavior)"]
Adversarial["3. Negative Adversarial Boundary (Error & Boundary Proof)"]
end
CmdRun --> Runner
CmdDisc --> Discovery
CmdDash --> Accumulator
CmdBind --> CAS
CmdContam --> PlaneSnap
CmdPar --> SafetyScanner
CmdStream --> Runner
Runner --> CAS
Runner --> WAL
Discovery --> CAS
Accumulator --> WAL
Accumulator --> CAS
Runner --> Verification
Architectural Subsystem Components
1. The Three-Fold Proof Model
Every feature delivered within the Zen Quantum Kernel must declare a timeless requirement contract backed by at least three verifiable criteria:
- Static Floor Invariant: Enforces schema conformance, AST static types, AST zero-swallowed-error rules, and architectural boundary constraints.
- Operational Dynamic Proof: Validates that positive functional scenarios execute deterministically end-to-end under real conditions.
- Negative Adversarial Boundary: Asserts that malformed inputs, missing files, network splits, and boundary edge cases fail closed predictably with structured diagnostic errors.
The zqk test run command executes these criteria via unified test_case wrappers, capturing stdout, stderr, process exit codes, and execution duration.
2. Test Execution Pipeline (run.go & pkg/testrunner)
When zqk test run executes:
- Target Ingestion: Accepts explicit
test_caseIDs or inspects CAS for all active candidate objects. - Invocation Mapping: Parses
verification_suites(e.g.CRIT-001: go test -run TestFeature) or maps criterion IDs directly to discovered test routines. - Execution Isolation: Runs each command in a managed context, capturing execution time, standard output, and process return codes.
- State Machine Shockwaves: Upon passing all criteria, emits
EventTypeCriterionSatisfiedand triggers automatic graduation of thetest_caseand parentrequirementtocomplete.
3. Test Discovery & Kernel Synchronization (discover.go)
The discovery engine parses source trees to locate tests:
- AST Inspection: Traverses Go test files and function declarations, extracting docstring metadata, criterion linkage tags, and execution command hints.
- CAS Ingestion: When invoked with
--sync, automatically generates versionedtest_caseobjects and registers them into Content Addressable Storage, bridging raw code with the Knowledge Graph.
4. AST Contamination Guard (check_contamination.go)
Testing must never mutate canonical process assets:
- Pre-Run Snapshot: Calculates a cryptographic snapshot of the
.zqk/processschema plane before test suite execution. - Sandboxed Command Execution: Runs the target test suite under audit supervision.
- Post-Run Diff: Asserts zero modification across all
.yaml,.yml, and.jsonschema entities. Any unintended side effect halts execution with a detailed contamination report.
5. Parallel Safety Auditor (identify_parallel.go)
Enforces concurrency hygiene across the test suite:
- AST AST Traversal: Scans test functions for calls to
t.Parallel(), environment mutation (os.Setenv,t.Setenv), filesystem manipulation, and shared global state. - Classification & Advice: Labels each routine as
PARALLEL,SAFE,UNSAFE, orREVIEW, recommending concurrency conversions to optimize CI wall-clock time.
6. Reactive Dashboard & TUI Radar (dashboard.go)
Provides real-time visibility into project test health:
- Materialized Lite-File Accumulator: Employs an incremental accumulator (
.zqk/cache/test_dashboard_lite.json) for sub-millisecond command-line response times. - WAL Streaming: In
--watchmode, hooks into the lifecycle event log to reflect criteria updates instantaneously without full storage scans. - Lineage Traceability: Resolves multi-hop links from
test_case➔requirement/backlog_item➔goal/priority_plan/milestone, visualizing intact vs. broken chains. - TPM Definition of Done (DoD) Guard: Validates that 100% of active test cases have unbroken traceability to root strategic compass objects and zero unbound test criteria exist.
Operational Workflows & Recipes
1. Running Targeted Feature Test Cases
Execute specific test cases with verbose diagnostics:
# Run a single test case with detailed streaming output
zqk test run TST-001 --verbose
# Run all active test cases across the kernel with timeout guard
zqk test run --all --timeout 60s
# Perform dry-run invocation check without executing processes
zqk test run TST-001 --dry-run
2. Discovering and Synchronizing Tests to CAS
Scan codebase source files and register them into the Knowledge Kernel:
# Scan local directory for Go test routines
zqk test discover ./cmd/zqk/test
# Discover and synchronize directly into CAS
zqk test discover --lang go --sync ./pkg/...
# Output discovered test inventory as JSON
zqk test discover --format json .
3. Auditing Test Concurrency and Parallel Safety
Identify tests ready for t.Parallel() acceleration:
# Audit parallel safety across the command tree
zqk test identify-parallel ./cmd/...
# Filter strictly for safe conversion candidates
zqk test identify-parallel --safe-only ./pkg/storage
4. Guarding Against Schema Plane Contamination
Ensure test executions do not contaminate authoritative kernel metadata:
# Validate that a test suite does not modify the process plane
zqk test check-contamination --plane .zqk/process --command "go test ./pkg/storage"
5. Inspecting Lineage and Repairing Broken Chains
Resolve orphaned test cases with the TPM Binding Assistant:
# View interactive binding assistant recommendations
zqk test bind
# Explicitly bind a test case to requirement and root goal
zqk test bind TST-001 --req REQ-001 --goal GOAL-001
# Automatically bind all broken chains using heuristic matching
zqk test bind --auto
6. Continuous TUI Radar Monitoring
Launch the live terminal test matrix during development:
# Static active working set snapshot
zqk test dashboard
# Live WAL streaming watch mode
zqk test dashboard --watch 2s
# Verify TPM Definition of Done gate in CI
zqk test dashboard --check-dod
Verification & Statement Coverage Invariant
To preserve system reliability and prevent regression, the Test Subsystem enforces strict engineering invariants:
-
>=85.0% Statement Coverage Invariant: All source routines in
cmd/zqk/test(bind.go,check_contamination.go,dashboard.go,discover.go,identify_parallel.go,run.go,stream.go,test.go) must maintain statement coverage at or above 85.0%.bash ZQK_ALLOW_FOREGROUND_GO_TEST=1 go test -v -timeout 60s -cover ./cmd/zqk/test -
Deterministic Storage Teardown: Any test initializing a temporary project root or storage provider must register
cli.UnregisterStorageForProjectRoot(tmpDir)int.Cleanupto eliminate background timer races, lingering goroutines, and file locking flakes. -
AST Quality Invariants: - Zero Swallowed Errors: Error returns from functions must never be discarded using
_ = .... All errors must be explicitly validated withrequire.NoError,assert.Error, or descriptive handler branches. - Modular Function Length: Individual test and production functions must not exceed 100 lines of code. -
Open-Core Payload Hygiene: Public release documentation, guides, and example code must never embed private workspace references or nanosecond-timestamped internal IDs. Generic IDs (e.g.
TST-001,REQ-001,GOAL-001) must be used exclusively.
Related Documentation & Cross-References
- Validation Subsystem Architectural & Operational Guide: Details the multi-layer validation engine, schema invariants, and automated remediation.
- Object Lifecycle, State Machines & CAS Storage Guide: Deep dive into the Content Addressable Storage layer and state machine transitions.
- CLI Workflow Subsystem Architectural Guide: Details ambient routing, next-action discovery (
zqk workflow whats-next), and Definition of Done gates. - Single-Command Execution Loop Guide (
zqk do): Explains autonomous agent preflight, claim locks, dispatch, and AST verification loops.