CLI Query & Reporting Command Engine Guide
Executive Summary
The ZQK CLI Query and Reporting Command Engines provide real-time declarative graph querying and AI-augmented predictive telemetry across the persistent Knowledge Kernel:
zqk query(aliaszqk zparql): High-performance, in-memory graph pattern matching engine executing ZPARQL queries (MATCH ... WHERE ... RETURN ...). Includes an interactive REPL console (--interactiveorrepl) and ASCII graph path visualizer (--visualizeor--format visual).zqk reports: Real-time project telemetry engine calculating Project Confidence Score (PCS), Effort Distribution Discrepancy (EDD), and Dependencies & Blockers (D&B), enhanced with Git commit telemetry and quick lifecycle triage reports (quick).
1. Declarative Graph Queries (zqk query)
Overview & Grammar
The query command evaluates Cypher-like ZPARQL queries against indexed objects and relational edges in the Knowledge Kernel (.zqk/process/).
# Basic match on specific object kind
zqk query "MATCH (b:backlog_item) RETURN b.id, b.status LIMIT 10;"
# Relationship path traversal
zqk query "MATCH (p:priority_plan)-[:items]->(b:backlog_item) RETURN p.title, b.id;"
# Multi-hop relationship traversal
zqk query "MATCH (g:goal)-[:requirement_refs]->(r:requirement)-[:criteria_refs]->(c:criteria) RETURN g.id, r.id, c.id;"
# Wildcard node matching across all indexed kinds
zqk query "MATCH (n) WHERE n.status == 'in_progress' RETURN n.kind, n.id;"
Interactive REPL Console (zqk query --interactive)
Starting the console enters an interactive prompt (zparql>) with auto-indexing and meta-commands:
| Meta-Command | Description |
|---|---|
.help, .h |
Displays the interactive REPL guide and syntax examples |
.kinds |
Lists all indexed object kinds with total node counts |
.tables, .edges |
Lists all indexed graph relationships and common traversal edges |
.schema [kind] |
Inspects field definitions, types, and required markers for any kind |
.format [table\|json\|visual] |
Sets default output format for executed queries |
.visualize [on\|off] |
Toggles ASCII graph path visualization mode |
.refresh, .reload |
Re-indexes the Knowledge Kernel storage graph from disk |
.clear |
Clears the multi-line query input buffer |
.exit, .quit, .q |
Exits the interactive console session |
Graph Edge Visualizer (--visualize)
Visualizing query results outputs hierarchical graph trees showing incoming, outgoing, and undirected relationships:
=== ZPARQL Graph Path Visualization ===
[1] Path:
● (p:priority_plan PRI-001)
───[:items]──► (b:backlog_item BLI-001)
───[:criteria_refs]──► (c:criteria CRIT-001)
└─ Properties: p.title=Execution Plan Alpha, b.status=in_progress
(Visualized 1 path(s))
2. Predictive AI Metrics & Reports (zqk reports)
Project Confidence Score (zqk reports pcs)
Measures overall project health and delivery momentum on a normalized scale (0–100):
- >= 80 (Excellent): High delivery velocity, healthy commit frequency, minimal blockers.
- 60–79 (Good): Project on track with minor non-blocking risks.
- 40–59 (Fair): Velocity deceleration or elevated open technical debt; monitor closely.
- 20–39 (Poor): Significant delivery impediments; action required.
- < 20 (Critical): High failure risk; immediate TPM intervention mandated.
# Tabular summary output
zqk reports pcs
# Structured machine-readable output
zqk reports pcs --format json
zqk reports pcs --format yaml --include-commit-data
Effort Distribution Discrepancy (zqk reports edd)
Evaluates variance between estimated effort and actual delivered reality:
- Positive EDD (> 5%): Underestimation (work items took more effort/commits than projected).
- Near Zero (-5% to +5%): High estimation accuracy and reliable scoping.
- Negative EDD (< -5%): Overestimation (work items required less effort than reserved).
zqk reports edd --format json
Dependencies & Blockers (zqk reports blockers)
Aggregates code-level dependencies, architectural co-changes, stale file anomalies, and active risk blockers:
zqk reports blockers
Quick Lifecycle Reports (zqk reports quick)
Fast triage commands for immediate operational health:
# Unanswered questions
zqk reports quick --preset questions
# Overdue milestones
zqk reports quick --preset milestones-overdue