CLI Spec Subsystem and Schema Registry Guide

1. Overview and Relational Architecture

The zqk spec command family provides programmatic introspection, validation inspection, and reflection across all object specifications registered within the ZQK Knowledge Kernel.

Within the ZQK architecture, object schemas are not static hardcoded structures; they are dynamic, composable, and versioned entities governed by the Knowledge Kernel Schema Registry. Specifications define:

  • Ontology and Semantics: Canonical naming (kind), hierarchical derivation (extends), and composite mixins (composes).
  • Field Invariants: Field types, permissions (rwx, ro, wo), semantic classifications, and operational purposes.
  • Validation Rules: Static constraints (regex, format, length, enum membership) and dynamic relational constraints.
flowchart TD
    subgraph Spec Subsystem ["zqk spec Subsystem"]
        direction TB
        SpecList["zqk spec list\n(Registry Discovery & Catalog)"]
        SpecGet["zqk spec get <kind>\n(Schema Definition & Trait Inspection)"]
        SpecFields["zqk spec fields <kind>\n(Field Constraints & Validation Rules)"]
    end

    subgraph Resolution Plane ["Dual-Source Resolution Plane"]
        direction TB
        StorageRegistry[("CAS Storage Provider\n(Kind: object_spec)")]
        LocalFallback[("File Backend Fallback\n(.zqk/specs/objects/*.yaml)")]
    end

    SpecList --> StorageRegistry
    SpecList -. Fallback .-> LocalFallback
    SpecGet --> StorageRegistry
    SpecGet -. Fallback .-> LocalFallback
    SpecFields --> StorageRegistry
    SpecFields -. Fallback .-> LocalFallback

2. Command Family Taxonomy

Subcommand Scope & Purpose Primary Operations
zqk spec list Specification Discovery Query and enumerate all registered object specifications from CAS storage or local filesystem fallback (.zqk/specs/objects).
zqk spec get <kind> (alias show) Specification Inspector Retrieve detailed specification metadata including ontology, schema version, inheritance hierarchy, traits, visibility, and required fields.
zqk spec fields <kind> Field Validation Inspector Inspect field-level attributes including data types, read/write permissions, semantic classifications, checklists, and validation constraints.

3. Operational Guides and Invariants

3.1 Specification Catalog (zqk spec list)

Lists all available object specifications known to the active project context.

  • Standard Table Output: bash zqk spec list Aliases: zqk spec ls.

  • Structured JSON Stream: bash zqk spec list --format json Returns a serialized catalog containing objects array and meta summary with total specification counts.

  • Dual-Source Fallback Invariant: When executing against a file-based storage backend where object_spec entities are not yet stored in SQLite CAS, zqk spec list gracefully falls back to scanning .zqk/specs/objects/*.yaml to guarantee high-availability schema reflection.


3.2 Specification Details (zqk spec get)

Inspects the comprehensive schema definition for a specified object kind.

  • Inspect Canonical Spec: bash zqk spec get backlog_item Aliases: zqk spec show backlog_item.

  • Normalized Kind Resolution: The <kind> argument is case-insensitive and automatically normalizes canonical prefixes (e.g. zqk spec get SPEC-widget and zqk spec get WIDGET resolve to widget).

  • Raw vs. Resolved Traits (--raw):

  • By default, zqk spec get resolves traits dynamically through the inheritance tree (spec.ResolvedTraits).
  • Specifying --raw bypasses dynamic trait composition and displays the local uncomposed declaration (spec.Traits).

  • Structured Output: bash zqk spec get requirement --format yaml zqk spec get requirement --format json Emits complete specification attributes: schema_version, ontology, extends, composes, visibility, storage_profile, id_prefixes, required_fields, and fields.


3.3 Field-Level Inspection (zqk spec fields)

Introspects field definitions, data types, permissions, and validation rules for an object kind.

  • Inspect All Fields (Table View): bash zqk spec fields backlog_item Displays an aligned table showing:

  • FIELD: Property name.

  • TYPE: Primitive or structured data type.
  • REQ: Required boolean indicator.
  • SEMANTIC: Semantic type classification.
  • PERM: Access permissions (e.g., rwx, ro).
  • PURPOSE: Checklist purpose description.

  • Filter to Required Fields Only (--required-only): bash zqk spec fields backlog_item --required-only Isolates mandatory schema fields required for object origination and promotion.

  • Structured Machine Output: bash zqk spec fields goal --format json Emits a structured payload containing ontology, total_count, and sorted fields list (required fields sorted first, followed by alphabetical order).


4. Verification and Done-Gates

Verification for the spec subsystem is codified in TST-001 and fulfills the Three-Fold Proof:

  1. Static Floor Invariant (CRIT-001): Statement test coverage in cmd/zqk/spec elevates to \(\ge 90.0\%\) with all subcommands (list, get, fields, NewSpecCmd) exercising in-process execution paths across table, JSON, and YAML formats.
  2. Operational Dynamic Proof (CRIT-001): In-process test suites execute commands against isolated temporary projects, validating dual-source fallback, prefix normalization, raw vs. resolved traits, and deterministic error handling for non-existent kinds.
  3. Negative Boundary & Architectural Conformance (CRIT-001): Authoritative CLI guide docs/guides/CLI_SPEC_SUBSYSTEM_AND_SCHEMA_REGISTRY_GUIDE.md authored, cataloging command taxonomy, operational examples, and relational schema registry invariants.