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:

  1. If the input ends with "s", the trailing suffix is stripped to produce the candidate singular form.
  2. The singular form is evaluated against canonicalMap and synonymToKind.
  3. If a match is detected, the corresponding canonical kind is returned.
  4. 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:

  1. Stateless Default Invocations: Package-level entrypoints (ResolveKind, ResolveKindStrict, NormalizeKind, DefaultKindAliasEntries) invoke a thread-safe singleton pre-warmed via sync.Once.
  2. 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.
  3. Defensive Slice Copies: Aliases returned via DefaultKindAliasesForKind or AliasesForKind return fresh slice clones, preserving immutable internal tables against caller mutation.
  4. 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 with goroutinelabels.NewGoroutine.