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 (alias zqk zparql): High-performance, in-memory graph pattern matching engine executing ZPARQL queries (MATCH ... WHERE ... RETURN ...). Includes an interactive REPL console (--interactive or repl) and ASCII graph path visualizer (--visualize or --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