CLI Reports Subsystem Architectural & Operational Guide

Executive Summary

The ZQK CLI Reports Subsystem (cmd/zqk/reports) provides real-time, AI-augmented telemetry, predictive metrics, and lifecycle triage across the persistent Knowledge Kernel. Rather than relying on transient LLM approximations or subjective estimations, the Reports Subsystem computes deterministic and git-correlated telemetry directly against Content Addressable Storage (CAS) objects, relational graph dependencies, and Git version control history.

Key capabilities delivered by the Reports Subsystem include:

  • Project Confidence Score (pcs): A normalized 0–100 index measuring delivery health, completion rates, and development momentum.
  • Effort Distribution Discrepancy (edd): A variance metric comparing estimated effort against actual work-item commit distribution.
  • Dependencies & Blockers (blockers): An automated graph and co-change analyzer identifying critical blockers, architecture co-dependencies, and prioritized action items.
  • Quick Lifecycle Triage (quick): Fast lifecycle review presets (questions, milestones-overdue) with strict SLA fail-closed exit options for CI/CD pipelines.

1. Architectural Taxonomy & Core File Layout

The reports subsystem is located in cmd/zqk/reports/ and integrates with pkg/metrics, pkg/storage, pkg/cliapp, and pkg/objects:

cmd/zqk/reports/
├── reports.go                           # Subsystem entrypoint, command builder, and shared metric calculator
├── pcs.go                               # Project Confidence Score command, interpretation, and formatters
├── edd.go                               # Effort Distribution Discrepancy command, variance analysis, and formatters
├── blockers.go                          # Dependencies & Blockers command, table/JSON formatters, and risk items
├── quick.go                             # Fast lifecycle query runner, preset dispatcher, and strict SLA handler
├── quick_constants.go                   # Standardized status, kind, and priority constants
├── quick_test.go                        # Unit and integration test suite for quick lifecycle presets
├── reports_test.go                      # Core metrics integration test suite with synthetic commit data
├── reports_cli_test.go                  # CLI invocation and output format test suite
└── reports_coverage_elevation_test.go   # Bounded unit tests for boundary values, error paths, and flags

2. Subsystem Architecture & Data Flow

The Reports Subsystem connects command-line invocations through the CLI application host to the storage plane and metrics calculator:

flowchart TD
    subgraph CLI ["CLI Command Host (cmd/zqk/reports)"]
        CMD["zqk reports"]
        CMD_PCS["pcs"]
        CMD_EDD["edd"]
        CMD_BLOCKERS["blockers"]
        CMD_QUICK["quick --preset ..."]
    end

    subgraph ENGINE ["Reporting Engine & Calculation Core"]
        CALC["calculateReportMetrics()"]
        METRICS_PKG["pkg/metrics (CalculateProjectMetrics)"]
        PROC["cli.Processor (pkg/cliapp)"]
    end

    subgraph DATA ["Kernel & Git Storage Plane"]
        STORAGE["CAS Object Storage (.zqk/process/)"]
        GIT["Git Commit History & Co-Change Analysis"]
        OBJECTS["Backlog Items, Criteria, Milestones, Questions"]
    end

    subgraph OUTPUT ["Presentation & Formats"]
        TABLE["Formatted Console Table"]
        JSON_OUT["Structured JSON"]
        YAML_OUT["Structured YAML"]
        STRICT_EXIT["Non-zero Exit Code (SLA Exceeded)"]
    end

    CMD --> CMD_PCS
    CMD --> CMD_EDD
    CMD --> CMD_BLOCKERS
    CMD --> CMD_QUICK

    CMD_PCS --> CALC
    CMD_EDD --> CALC
    CMD_BLOCKERS --> CALC
    CMD_QUICK --> PROC

    CALC --> METRICS_PKG
    METRICS_PKG --> STORAGE
    METRICS_PKG --> GIT
    PROC --> STORAGE

    STORAGE --> OBJECTS

    CMD_PCS --> TABLE
    CMD_PCS --> JSON_OUT
    CMD_PCS --> YAML_OUT

    CMD_EDD --> TABLE
    CMD_EDD --> JSON_OUT
    CMD_EDD --> YAML_OUT

    CMD_BLOCKERS --> TABLE
    CMD_BLOCKERS --> JSON_OUT
    CMD_BLOCKERS --> YAML_OUT

    CMD_QUICK --> JSON_OUT
    CMD_QUICK --> STRICT_EXIT

3. Command Taxonomy

The reports command group organizes project health reporting into four primary subcommands:

Subcommand Description MCP Permission Formats Supported
zqk reports pcs Computes Project Confidence Score (0–100) read:metrics Table (default), JSON, YAML
zqk reports edd Computes Effort Distribution Discrepancy (%) read:metrics Table (default), JSON, YAML
zqk reports blockers Identifies active blockers, co-changes, and action items read:metrics Table (default), JSON, YAML
zqk reports quick Executes fast lifecycle review presets read:objects JSON (default), Table

Common Flags

All commands under zqk reports support:

  • --include-commit-data: Explicitly forces Git commit history ingestion into metric calculations (auto-detected when git history is present).
  • --format, -f: Output formatting (table, json, yaml, jsonl).
  • --strict: (Quick reports only) Causes the process to exit with non-zero exit code 1 if critical items (e.g. P0 questions or overdue milestones) violate SLAs.

4. Algorithmic Definitions & Interpretation Thresholds

4.1 Project Confidence Score (PCS)

Definition: The Project Confidence Score measures overall project delivery confidence on a normalized 0.00 to 100.00 scale.

The base score evaluates work item completion weights across active items in complete, in_progress, validated, and planned states:

  • complete items contribute a weight factor of 1.0.
  • validated items contribute a weight factor of 0.5.
  • Items in preliminary or unverified states (exploring) are excluded from positive weight calculation.

When commit telemetry is enabled, the score is augmented with Git velocity metrics:

  • Commit Frequency & Regularity: Checks commit consistency across 7-day and 30-day windows.
  • Code Momentum: Evaluates trend direction (increasing, stable, declining).
  • Recent Activity: Rewards active progress in current cycles.

Interpretation Thresholds:

Score Range Status Code Human Label Operational Significance
>= 80.00 excellent Excellent High delivery confidence; on track for milestone completion.
60.00 – 79.99 good Good Healthy delivery momentum; minor concerns or isolated delays.
40.00 – 59.99 fair Fair Elevated risks or declining commit momentum; monitor closely.
20.00 – 39.99 poor Poor Significant delivery impediments; schedule slip probable.
< 20.00 critical Critical Immediate TPM intervention mandated; high failure probability.

4.2 Effort Distribution Discrepancy (EDD)

Definition: Effort Distribution Discrepancy indicates the variance percentage between estimated work item effort and observed effort distribution.

\[\text{EDD} = \left(\frac{\text{Actual Effort}}{\text{Estimated Effort}} - 1\right) \times 100\%\]

When commit telemetry is linked, actual effort is evaluated using commit-to-work-item ratios:

  • Optimal commit-to-work-item ratio is typically between 2 and 5 commits per backlog item.
  • Ratios below 2 indicate potential under-scoping or sparse commits.
  • Ratios above 5 indicate scope expansion, churning refactors, or underestimated complexity.

Interpretation Thresholds:

Discrepancy Range Status Code Human Label Root Cause & Corrective Action
> +20.00% significant_underestimation Significant Underestimation Items consistently require more effort than estimated; re-evaluate estimation baselines.
+5.01% to +20.00% moderate_underestimation Moderate Underestimation Mild under-scoping; monitor backlog item slicing and complexity drift.
-5.00% to +5.00% good_accuracy Good Estimation Accuracy Estimated effort strongly aligns with delivery reality; reliable sizing.
-19.99% to -5.01% moderate_overestimation Moderate Overestimation Work items required less effort than reserved; consider tighter sprint commitments.
<= -20.00% significant_overestimation Significant Overestimation Consistent over-allocation of time/points; capacity underutilized.

4.3 Dependencies & Blockers (D&B)

Definition: The Dependencies & Blockers analyzer discovers potential project friction points across multiple analytical dimensions:

  1. Code Co-Change Dependencies: Analyzes Git commit co-occurrences. Files that frequently change together in the same commits (>= 3 times) suggest tight architectural coupling.
  2. Stale File Blockers: Detects files associated with active backlog items that have historical commits but zero activity over the last 30 days.
  3. Graph Relational Blockers: Traverses active blocked_by and blocking_milestone_refs relations on kernel objects.

Output Structure:

  • Summary: High-level textual synthesis of overall blocker risk.
  • Dependencies: Categorized by type (code, work_item, external) and severity (low, medium, high, critical).
  • Blockers: Critical impediments categorized by type and severity.
  • Action Items: Concrete remediation tasks tagged with priority (P0, P1, P2, high, medium, low).

5. Quick Report Lifecycle Queries & Operational Semantics

The zqk reports quick command provides rapid status queries for lifecycle reviews and automated quality gates without requiring complex metrics synthesis.

5.1 Preset: questions

Lists all unanswered questions in the project:

  • Filters out questions in terminal states (resolved, deferred, error).
  • Resolves owners via updated_by with fallback to owner_ref.
  • Truncates question text cleanly if exceeding 60 characters (summary[:57] + "...").
  • Flags whether any open question has priority_tier == "P0".
  • Populates meta.critical_exceeded: true if open P0 questions are found.
zqk reports quick --preset questions

5.2 Preset: milestones-overdue

Lists all milestones whose target completion date is in the past:

  • Evaluates target_date < today (UTC).
  • Filters out completed, deferred, or archived milestones (status $nin ["complete", "deferred", "archived"]).
  • Automatically sorts results chronologically ascending (sort_by: target_date).
  • Sets meta.critical_exceeded: true if one or more overdue milestones exist.
zqk reports quick --preset milestones-overdue

5.3 Strict SLA Gating (--strict)

When the --strict flag is supplied:

  • If meta.critical_exceeded is true, the command outputs the report and exits immediately with process exit code 1 (errExitCode: "critical SLA exceeded").
  • If no critical items exceed SLA, the command exits with code 0.

This makes zqk reports quick --preset ... --strict ideal for pre-commit hooks, CI/CD pipeline gates, and pull request check valves:

# Fail CI build if any open P0 questions remain unanswered
zqk reports quick --preset questions --strict || exit 1

# Fail release pipeline if any milestone target date has lapsed
zqk reports quick --preset milestones-overdue --strict || exit 1

6. Execution Examples

Checking Project Confidence Score

$ zqk reports pcs

Project Confidence Score (PCS)
=============================

Score: 84.50 / 100.00

Status: Excellent - High confidence in project delivery

Exporting Metrics to JSON for Dashboards

$ zqk reports edd --format json
{
  "edd": 3.25,
  "status": "good_accuracy"
}

Reviewing Active Blockers and Dependencies

$ zqk reports blockers

Dependencies & Blockers (D&B)
============================

Summary: 2 active dependencies and 1 critical blocker detected.

Dependencies (2):
-------------------
1. [high] code - co-change detected between pkg/auth/token.go and pkg/storage/cas.go
2. [medium] external - waiting for upstream schema verification

Blockers (1):
-------------
1. [critical] work_item - database migration BLI-402 incomplete

Action Items (1):
----------------
1. [P0] Finalize migration script before promoting release branch

7. Error Handling & Edge Recovery

Error Condition Cause Subsystem Behavior Resolution
failed to get context Command context is nil or CLI registry unregistered Returns error and halts execution Initialize command via standard CLI tree
project root not found Working directory does not contain .zqk and ZQK_PROJECT_ROOT is unset Returns fail-closed error Run command inside initialized ZQK repo or export ZQK_PROJECT_ROOT
failed to initialize storage Storage path unreadable, corrupted, or pointing to a regular file Wraps and returns filesystem/CAS error Verify directory permissions and disk integrity
unknown preset %q Specified --preset is not questions or milestones-overdue Displays error with allowed presets list Provide valid preset flag argument
critical SLA exceeded --strict enabled and open P0 question or overdue milestone detected Returns structured data and exits non-zero (code 1) Resolve P0 question or adjust milestone target date