CLI Command Aliases, Auto-Fix Recipes, and Template Nullability
Overview
This guide documents CLI ergonomics standards, command alias parity, auto-fix recipe syntax conventions, and template reference field nullability rules across the Knowledge Kernel CLI and tooling runtime.
1. Object Minting Aliases (zqk new <kind>)
The Knowledge Kernel CLI provides ergonomic short aliases for common core kinds under zqk new:
| Kind | Aliases | Example Usage |
|---|---|---|
priority_plan |
plan, pri |
zqk new pri --title "Storage Elevation Plan" |
requirement |
req |
zqk new req --title "Fast Search" |
criteria |
crit |
zqk new crit --title "Sub-15ms Latency" |
test_case |
tst, tc |
zqk new tst --title "Verify Latency" |
backlog_item |
bli |
zqk new bli --title "Index optimization" |
milestone |
mil |
zqk new mil --title "v0.4 Release" |
technical_debt |
td, techdebt |
zqk new td --title "Refactor cache lock" |
vision |
vis |
zqk new vis --title "Autonomous Dev" |
mission |
mis |
zqk new mis --title "Reliable Swarms" |
workstream |
ws |
zqk new ws --title "Core Subsystems" |
question |
que |
zqk new que --title "Architecture Decision" |
decision |
dec |
zqk new dec --title "CAS Storage Model" |
All aliases support identical relational and descriptor flags (--title, --description, --content, --plan, --req, --goal, --bli, --criteria, --cas, --promote).
2. Auto-Fix Recipe Command Syntax
When zqk system check identifies recoverable schema, reference, or lifecycle issues, deterministic remedy recipes provide actionable CLI commands to repair the anomaly.
Positional ID Convention
Commands output canonical positional arguments for single-object mutations rather than legacy or invalid --ids flags:
- Object Update:
zqk object update <ID> --field <FIELD>=<VALUE> - Object Deletion:
zqk object delete <ID> --unlink-references - System Check Auto-Fix:
zqk system check --auto-fix <ID>
The auto-fix engine sanitizes generated recipe strings, stripping any extraneous --ids flags to prevent execution failures when operators copy-paste remedy recipes.
3. Template Scaffolding & Reference Field Nullability
Problem Statement
In earlier iterations, object templates and draft-plane merges populated optional reference attributes (e.g., release_ref: "", team_configuration_ref: "", priority_plan_ref: "") with empty string scalars (""). Because the ontology defines references as non-empty entity pointers, empty string values violated ontology invariants during subsequent draft validation.
Clean Scaffolding Protocol (GH-944)
- Omission on Draft Land: Optional reference fields (
field.Type == "reference"orfield.SemanticType == "reference", and scalar*_ref/*_id) are omitted from initial draft skeletons unless explicitly provided by the operator. - Explicit Nullability (
null): Where placeholders are required for lifecycle progression (such aspriority_plan_refonbacklog_item), templates scaffold explicitnull(nil) rather than empty strings"". - Validator Permissiveness: Core schema and ontology validators (
GoValidator,InstanceValidator, andOntologyRegistry) treatnulland omitted attributes as valid unpopulated states for optional reference fields, eliminating false-positive validation rejections.
4. Object Discovery Symmetry & Traceability Alignment
Object List Flag and Argument Parity
zqk object list supports both positional kinds and the --kind flag interchangeably:
- Positional kind:
zqk object list requirement - Flag kind:
zqk object list --kind requirement
The CLI validates kinds strictly against the ontology registry before dispatching storage queries, ensuring early, helpful errors on typos.
Strategic Traceability Propagation
When generating execution spines via zqk workflow gen-trace-pipeline <REQ-ID>, the generator automatically extracts all goal_refs from the parent requirement and propagates them to all child backlog_item objects. This guarantees end-to-end strategic alignment across the 5-layer cascade without manual reference linking.