Canonical Kind Synonyms & CLI Workflow Aliases Subsystem Operational Architecture Guide
Executive Summary
The Canonical Kind Synonyms & CLI Workflow Aliases Subsystem (pkg/kindsynonyms) provides deterministic, zero-allocation semantic resolution and normalization for ontological object kinds across the ZQK Knowledge Kernel. In human-interactive CLI commands, developer automation, and autonomous multi-agent swarm workflows, users and agents frequently supply colloquial shorthands, abbreviations, and plurals (e.g., req, crits, bli, pplan, tasks, journal) rather than rigid canonical identifiers (requirement, criteria, backlog_item, priority_plan, change_journal_entry).
Under POL-DEFAULT-a5e2f78b19c36d0e, the subsystem establishes an immutable, thread-safe resolution membrane that normalizes casing and whitespace, resolves plural forms, enforces bidirectional alias dictionaries, and translates raw CLI tokens to canonical ontology kinds with zero lock contention and 100.0% statement test coverage.
Architectural Overview
Within the ZQK Knowledge Kernel, all planning artifacts, specifications, audit logs, and governance policies exist as typed graph objects indexed by canonical kind names defined in pkg/kindnames. Without an alias resolution layer, strict input requirements would force operators to repeatedly type verbose canonical identifiers or trigger validation errors on common plurals.
pkg/kindsynonyms decouples human ergonomics from strict schema ontology:
- Ergonomic Ingestion: Accepts shorthand abbreviations, acronyms, and pluralized forms.
- Fail-Safe Normalization: Strips leading/trailing whitespace, folds unicode casing to lowercase, and evaluates suffix heuristics.
- Ontological Consistency: Transparently bridges CLI commands, query parsers, and storage bucketing strategies to the unified canonical ontology schema.
- Thread Safety & Immutability: Pre-computes deterministic lookup tables during initialization, guaranteeing safe concurrent reads without mutex bottlenecks during hot-path command routing.
+-----------------------------------------------------------------------+
| CLI / Swarm / API Input |
| e.g., " REQ ", "blis", "crits", "pplan", "journal" |
+-----------------------------------------------------------------------+
|
v
+-----------------------------------------------------------------------+
| Normalizer (pkg/kindsynonyms) |
| strings.ToLower(strings.TrimSpace(raw)) |
+-----------------------------------------------------------------------+
|
v
+-----------------------------------------------------------------------+
| Canonical Kind Resolver & Registry |
| +---------------------------------------------------------------+ |
| | 1. Exact Canonical Match --> Return Kind | |
| | 2. Synonym Dictionary Map --> Return Canonical Mapping | |
| | 3. Plural Suffix Heuristics ('s' strip) --> Match / Return | |
| | 4. Unknown Kind Fallback --> Pass-Through / Error on Strict | |
| +---------------------------------------------------------------+ |
+-----------------------------------------------------------------------+
|
v
+-----------------------------------------------------------------------+
| Canonical Kernel Kind |
| "requirement", "backlog_item", "criteria", "priority_plan" |
+-----------------------------------------------------------------------+
Component Topology
The subsystem is structured into three core architectural components:
graph TD
A["Raw CLI Input / Agent Parameter"] --> B["Normalizer (NormalizeKind)"]
B --> C["Canonical Kind Resolver (Resolver)"]
subgraph "pkg/kindsynonyms Subsystem Membrane"
D["Kind Synonym Table (defaults.go)"] --> C
E["Dynamic Registration Store (Register)"] --> C
C --> F{"Resolution Pipeline"}
F -->|"Direct Canonical"| G["Canonical Kind Output"]
F -->|"Synonym Match"| G
F -->|"Plural Fallback"| G
F -->|"Unknown Kind"| H["Normalized Pass-Through / Strict Error"]
end
G --> I["Downstream Subsystems (cli, objects, storage, validation)"]
1. Kind Synonym Table (defaults.go)
Maintains static, deterministic mappings from canonical kinds to their accepted aliases, plurals, and abbreviations. It defines the standard ontology vocabulary recognized across all core CLI subcommands.
2. Normalizer (resolver.go: NormalizeKind)
A stateless transformer that sanitizes raw input by trimming leading/trailing whitespace and converting all runes to lowercase. This ensures casing discrepancies (e.g., REQ, Req, req) are handled uniformly.
3. Canonical Kind Resolver (resolver.go: Resolver)
A concurrency-safe registry that indexes:
synonymToKind: Bidirectional reverse lookup table mapping every synonym to its canonical ontology name.canonicalMap: Fast boolean set indicating whether a given string is already an authoritative canonical kind.kindToAliases: Forward lookup index providing all known synonyms for a canonical kind.
Normalization & Resolution Lifecycle
The following sequence diagram illustrates the lifecycle of kind resolution during a CLI command invocation:
sequenceDiagram
autonumber
actor User as Operator / Swarm Agent
participant CLI as CLI Layer (cmd/zqk)
participant Res as kindsynonyms.Resolver
participant Kernel as Knowledge Kernel Engine
User->>CLI: Invoke command (e.g., zqk object list " reqs ")
CLI->>Res: ResolveKind(" reqs ")
Note over Res: Step 1: NormalizeKind trims spaces & lowercases -> "reqs"
Note over Res: Step 2: Check canonicalMap["reqs"] -> False
Note over Res: Step 3: Check synonymToKind["reqs"] -> Found "requirement"
Res-->>CLI: Return canonical "requirement"
CLI->>Kernel: Query objects of kind "requirement"
Kernel-->>CLI: Return matching requirement records
CLI-->>User: Render formatted table to console
Fallback & Dynamic Plural Heuristics
When an incoming kind token is neither directly canonical nor present in the static alias dictionary, the resolver applies dynamic plural trimming:
- If the input ends with
"s", the trailing suffix is stripped to produce the candidate singular form. - The singular form is evaluated against
canonicalMapandsynonymToKind. - If a match is detected, the corresponding canonical kind is returned.
- If no match is found, standard resolution (
ResolveKind) falls back to returning the normalized input string, whereas strict resolution (ResolveKindStrict) yields an explicit error.
Kind Taxonomy & Alias Mapping Matrix
The canonical kind alias dictionary covers all primary planning, governance, and operational ontology domains in ZQK:
| Canonical Kind | Short Aliases | Plural Forms | Acronyms & Colloquials | Domain Category |
|---|---|---|---|---|
backlog_item |
task, item, story |
tasks, items, stories, blis |
bli, work_item, backlog |
Execution Units |
requirement |
req, spec |
reqs, specs |
specification |
Functional Contracts |
goal |
aim, target |
goals, objectives |
objective |
Strategic Compass |
milestone |
checkpoint, phase |
milestones, checkpoints, mils |
mil |
Chronological Boundary |
criteria |
acceptance, criterion |
crits, acceptance_criteria |
crit, test_criteria |
Verification Proofs |
test_case |
test, testcase, tc |
tests, testcases, tcs, tsts |
tst |
Verification Harness |
priority_plan |
plan, priority, pplan |
priorities, pplans, pris |
pri |
Execution Cycles |
epic |
epic |
epics |
epic |
Thematic Initiative |
decision |
adr |
adrs |
arch_decision_record, architectural_decision |
Architectural Records |
workstream |
stream |
streams |
work_stream, initiative |
Workflow Streams |
component |
comp, part |
components, modules |
module |
System Architecture |
prompt_template |
prompt, prompt_tpl |
prompts |
prompt_tpl |
Agent Instructions |
policy |
policy |
policies |
policy |
Governance & Rules |
change_journal_entry |
journal, change_journal |
journal_entries |
journal_entry |
Audit & Journaling |
strategic_plan |
splan, strategic |
splans |
strat_plan |
Long-term Planning |
workstream_transition |
wstrans |
wstrans |
ws_trans |
State Transitions |
evolution_management |
evoman |
evoman |
evo_man |
Ontological Evolution |
vocabulary_scheme |
vocab |
vocabularies |
vocabulary |
Semantic Recalls |
Concurrency & Thread-Safety Invariants
The pkg/kindsynonyms subsystem satisfies strict high-concurrency invariants:
- Stateless Default Invocations: Package-level entrypoints (
ResolveKind,ResolveKindStrict,NormalizeKind,DefaultKindAliasEntries) invoke a thread-safe singleton pre-warmed viasync.Once. - Reader-Writer Synchronization: Dynamic registrations (
Register) acquire an exclusive write lock (mu.Lock()), while lookups acquire a shared read lock (mu.RLock()), preventing data races during concurrent queries. - Defensive Slice Copies: Aliases returned via
DefaultKindAliasesForKindorAliasesForKindreturn fresh slice clones, preserving immutable internal tables against caller mutation. - Zero Race Hazards: Validated through concurrent stress testing spawning multiple workers via
goroutinelabels.NewGoroutine.
Verification & Coverage Invariant
Statement test coverage for pkg/kindsynonyms is maintained under strict fail-closed automation:
- Static Floor Invariant: Statement test coverage strictly \(\ge 85.0\%\).
- Target & Achieved Coverage: 100.0% of statements verified across all routines and edge branches.
- Verification Command:
bash ZQK_ALLOW_FOREGROUND_GO_TEST=1 go test -v -timeout 30s -cover ./pkg/kindsynonyms
Test Suite Matrix (kindsynonyms_coverage_elevation_cycle192_test.go)
TestDefaultKindAliasesForKind_FoundAndNotFound: Validates alias slicing and missing kind fallback.TestNormalizeKind: Validates trimming, lowercasing, and empty string resilience.TestCanonicalKindResolution_DefaultMappedKinds: Validates identity resolution for all default kinds.TestSynonymAndAbbreviationResolution: Exercises every abbreviation, plural, and alias mapping.TestResolveKind_CasingAndWhitespaceNormalization: Verifies robustness against malformed input whitespace.TestResolveKind_PluralNormalizationFallback: Tests dynamic plural suffix stripping for custom kinds.TestResolveKindStrict: Verifies fail-closed error handling on unknown kinds and empty arguments.TestCustomSynonymRegistration: Verifies dynamic registration, idempotency, and collision rejection.TestAliasesForKindAndAllCanonicalKinds: Tests forward lookup and canonical inventory inspection.TestConcurrentResolverOperations: Multi-threaded stress testing withgoroutinelabels.NewGoroutine.