Command Specification Parity and Semantic Architecture Governance
Technical Specification:
TSP-COMMAND-SPEC-PARITY-GOVERNANCE-001
Status: Implemented & Verified
Target Release: Zen Quantum Kernel v0.1.0
Architecture Domain: CLI Ergonomics, Declarative Taxonomy & Static Governance
1. Executive Summary & Problem Statement
In autonomous multi-agent systems and high-throughput command-line orchestration, the CLI serves as the authoritative interface between human engineers, autonomous swarms, and the Knowledge Kernel. Taxonomy drift, missing declarative specifications, orphaned command fragments, and argument/flag inconsistencies across runtime Cobra definitions and static specifications introduce acute operational hazards:
- Semantic Taxonomy Drift: Runtime commands defined without backing declarative specifications in
.zqk/cli/specs/cannot be verified by static analysis gates, schema validators, or automated documentation generators. - Schema & Semantic Link Degradation: Subcommand link references (
spec_ref) that point to missing or renamed specifications break semantic link graph traversal and isolate sub-spec trees from verification. - Flag & Annotation Divergence: Discrepancies between declared flags/annotations and runtime Cobra implementations lead to runtime invocation errors, broken agent prompt context generation, and inaccurate help golden generation.
- Permissive Legacy Leakage: Failure to enforce strict fail-closed AST verification allows new un-specced commands to slip past commit checks, reversing ratcheting baseline progress.
Cycle 49 establishes comprehensive fail-closed command specification parity and semantic architecture governance within the ZQK Verification Engine (zqk-vet), enforcing 100% specification parity, semantic link graph integrity, flag and annotation conformance, and fail-closed schema validation.
2. Architectural Topology & Verification Engine
The verification pipeline operates across both static AST inspection and dynamic runtime command tree analysis:
flowchart TD
A[zqk-vet hygiene suite] --> B[CheckCommandSpecs]
A --> C[CheckCLIBuilders]
B --> D[1. Declarative Spec Schema Validation]
D --> D1{Parse YAML Spec in .zqk/cli/specs}
D1 -->|Invalid YAML Syntax| E1[SeverityError: command_spec/syntax]
D1 -->|Missing 'name' or 'short/desc'| E2[SeverityError: command_spec/schema]
D1 -->|Invalid Flag Definition| E3[SeverityError: command_spec/flags]
D1 -->|Invalid Args Type| E4[SeverityError: command_spec/args]
D1 -->|Non-existent spec_ref Link| E5[SeverityError: command_spec/broken_link]
D1 -->|Valid Spec Schema| F[Spec Map Indexed]
B --> G[2. Live Cobra Tree Parity & Drift Analysis]
G --> G1[AnalyzeCommandSpecCoverage]
G1 -->|New Un-specced Commands| H1[SeverityError: command_spec/missing]
G1 -->|Orphaned Specs without Commands| H2[SeverityError: command_spec/orphaned]
G1 -->|Zero Drift / Baseline Matched| H3[Zero-Drift Pass]
B --> I[3. Command Tree Parity Verification]
I --> I1[Flag Parity Check]
I --> I2[Orchestration Annotation Check]
I1 -->|Spec Flag Missing in Runtime| J1[SeverityWarn: command_spec/flag_missing]
I2 -->|Annotation Mismatch| J2[SeverityWarn: command_spec/annotation_drift]
C --> K[4. Command Builder Pattern Enforcement]
K -->|Missing Generated Builder| L1[SeverityError: cli/missing_builder]
K -->|Raw &cobra.Command Direct Instantiation| L2[SeverityError: cli/builder_pattern_violation]
3. Specification Governance Rules & Schema Contracts
Rule 1: Declarative Specification Existence & Parity
Every command registered in the runtime root command hierarchy (cmd/zqk/) must have a corresponding declarative specification located under .zqk/cli/specs/<domain>/<command>_command.yaml. Unspecced commands generate a fail-closed SeverityError unless grandfathered in .zqk/cli/command_spec_coverage_baseline.json.
Rule 2: Semantic Link Graph Integrity
When a parent command declares subcommands with spec_ref links (e.g. mcp/svc/cursor_adapter_command.yaml), the target spec file must exist relative to .zqk/cli/specs/ or the parent spec directory. Any dangling reference emits a fail-closed command_spec/broken_link error.
Rule 3: Argument & Flag Schema Validation
- Args Types: Must declare a recognized argument constraint:
exact,minimum,maximum,range,no_args,none,arbitrary,arbitrary_args, orany. - Flag Objects: Each item in
flagsmust specify a non-emptyname,type, anddescription. Single-character shorthands must not exceed length 1. - Required Traits: Spec-level traits declared in
required_traitsmust be non-empty strings.
Rule 4: Orchestration Annotation Governance
Runtime commands must conform to declared specification security and orchestration traits:
requires_storage: true\(\leftrightarrow\)zqk.requires_storage: "true"requires_session: true\(\leftrightarrow\)zqk.requires_session: "true"requires_scheduler_check: true\(\leftrightarrow\)zqk.requires_scheduler_check: "true"
4. Verification Runbook & Command Inventory
Engineers and agents verify command specification parity and governance through standard tooling:
-
Run Full Verification Engine:
bash ./bin/zqk-vet --suite hygiene -
Execute Full Suite Matrix:
bash ./bin/zqk-vet --suite all -
Run Command-Spec Parity Unit Suite:
bash go test -v ./pkg/vet -run TestCheckCommandSpecs go test -v ./cmd/zqk/app -run TestCommandSpecParity -
Trigger VDS Test Verification:
bash ./bin/zqk test run <tst-id>
5. Architectural Invariants Enforced
| Invariant ID | Target Dimension | Verification Mechanism | Severity |
|---|---|---|---|
INV-SPEC-SYNTAX-001 |
YAML Well-Formedness | CheckCommandSpecs YAML Unmarshal |
SeverityError |
INV-SPEC-SCHEMA-002 |
Mandatory Schema Fields | validateCommandSpecMap |
SeverityError |
INV-SPEC-LINK-003 |
Semantic Link Graph (spec_ref) |
Target File Existence Check | SeverityError |
INV-SPEC-DRIFT-004 |
Zero Unspecced Commands | AnalyzeCommandSpecCoverage |
SeverityError |
INV-SPEC-BUILDER-005 |
Generated Builder Usage | CheckCLIBuilders AST Parser |
SeverityError |
INV-SPEC-FLAGS-006 |
Flag & Annotation Parity | verifyCommandTreeParity |
SeverityWarn |