CLI Kind Alias Parity Guide
Executive Summary
The CLI Kind Alias Parity Specification defines the canonical kind shorthand aliases supported across the ZQK CLI, specifically unifying zqk new <kind>, zqk new object <kind>, and zqk object new <kind> (an alias of zqk object create).
Under CRIT-001 (POL-DOC-001 Documentation Invariant for CLI Kind Aliases), this document formalizes the canonical shorthand alias mappings to ensure seamless developer and autonomous agent ergonomics across all entrypoints.
Supported Shorthand Kind Aliases
The table below delineates the canonical kinds and their standard shorthand aliases across CLI entrypoints:
| Canonical Kind | Shorthand Aliases | Domain / Ontology Role | CLI Invocations |
|---|---|---|---|
test_case |
tst, tc |
Unified Verification Group | zqk new tst, zqk new tc, zqk new object tst, zqk object new tc |
criteria |
crit |
Atomic Verification Proof | zqk new crit, zqk new object crit, zqk object new crit |
requirement |
req |
Timeless Feature Contract | zqk new req, zqk new object req, zqk object new req |
priority_plan |
pri, plan |
Time-Bounded Execution Cycle | zqk new pri, zqk new plan, zqk new object pri, zqk object new pri |
backlog_item |
bli |
Atomic Unit of Effort | zqk new bli, zqk new object bli, zqk object new bli |
milestone |
mil |
Chronological Boundary Anchor | zqk new mil, zqk new object mil, zqk object new mil |
goal |
goal |
Timeless Strategic Compass | zqk new goal, zqk new object goal, zqk object new goal |
Architectural Mechanics & Resolution Pipeline
Kind alias resolution operates through three synchronized layers:
-
Config & Default Synonyms Layer (
pkg/validation/id_prefixes_config.go&.zqk/specs/configs/id_prefixes_config.yaml): - Declares explicitkind_to_synonymsmappings. - Externalized configuration enables standardized alias resolution without hardcoding in command parsers. - Feeds theSynonymProviderAdapterintoobjects.GetGlobalSynonymResolver(). -
Semantic Synonyms Engine (
pkg/kindsynonyms&pkg/objects): - Provides deterministic mapping from shorthand aliases (e.g.,tst,tc,pri,req,crit,bli,mil) to canonical kind identifiers (test_case,priority_plan, etc.). -objects.GetCanonicalKind(raw)resolves any alias or canonical name to its canonical identifier. -
CLI Command Routing Layer (
cmd/zqk/new/&cmd/zqk/object/): - Direct Convenience Commands (zqk new <alias>): Subcommands underzqk newconfigured with alias arrays (e.g.test_casewithAliases: []string{"tst", "tc"};priority_planwithAliases: []string{"plan", "pri"}). - Positional Validation (zqk new object <kind>/zqk object new <kind>): Usescli.ValidateAnnotatedKindandobjects.ResolveAndValidateKindForProjectto resolve aliases prior to object construction and validation against the project spec index.
Negative Adversarial Boundary
When an unrecognized kind or alias is supplied (such as zqk new object unknown_alias or objects.ResolveAndValidateKindForProject(root, "invalid_kind")), the system fails closed with an informative error message:
unknown kind "invalid_kind": not in this project's object spec index (update specs or use a registered kind name; valid canonical kinds include: goal, requirement, test_case, criteria, priority_plan, backlog_item, milestone; valid aliases include: req, tst, tc, crit, pri, bli, mil, goal)
This error guides operators directly to valid canonical kinds and supported shorthand aliases.