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 listAliases:zqk spec ls. -
Structured JSON Stream:
bash zqk spec list --format jsonReturns a serialized catalog containingobjectsarray andmetasummary with total specification counts. -
Dual-Source Fallback Invariant: When executing against a file-based storage backend where
object_specentities are not yet stored in SQLite CAS,zqk spec listgracefully falls back to scanning.zqk/specs/objects/*.yamlto 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_itemAliases: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-widgetandzqk spec get WIDGETresolve towidget). -
Raw vs. Resolved Traits (
--raw): - By default,
zqk spec getresolves traits dynamically through the inheritance tree (spec.ResolvedTraits). -
Specifying
--rawbypasses 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 jsonEmits complete specification attributes:schema_version,ontology,extends,composes,visibility,storage_profile,id_prefixes,required_fields, andfields.
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_itemDisplays 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-onlyIsolates mandatory schema fields required for object origination and promotion. -
Structured Machine Output:
bash zqk spec fields goal --format jsonEmits a structured payload containingontology,total_count, and sortedfieldslist (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:
- Static Floor Invariant (
CRIT-001): Statement test coverage incmd/zqk/specelevates to \(\ge 90.0\%\) with all subcommands (list,get,fields,NewSpecCmd) exercising in-process execution paths across table, JSON, and YAML formats. - 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. - Negative Boundary & Architectural Conformance (
CRIT-001): Authoritative CLI guidedocs/guides/CLI_SPEC_SUBSYSTEM_AND_SCHEMA_REGISTRY_GUIDE.mdauthored, cataloging command taxonomy, operational examples, and relational schema registry invariants.