Acronym Vocabulary & Progressive Disclosure Subsystem Architectural & Operational Guide

1. Executive Architectural Summary

The Acronym Vocabulary & Progressive Disclosure Subsystem (pkg/acronyms) manages the canonical ontology of system acronyms, jargon, and taxonomic abbreviations across the ZQK Knowledge Kernel.

In human-agent hybrid development environments, communication token density and semantic precision are critical:

  1. Progressive Disclosure: AI agents and human operators communicate using high-density abbreviations (e.g., BLI, PRI, REQ, CRIT, VDS, CAS, WAL) during fast-path operational loops, conserving token context budgets by up to 70%. When an operator or agent encounters unfamiliar terminology, the subsystem progressively discloses the full definition, operational scope, and graph relationships on demand.
  2. Dual-Mode Persistence & Offline Seed Fallback: The subsystem operates seamlessly across two planes: an in-memory, thread-safe bootstrap registry for cold-start and offline execution, and a live Content-Addressable Storage (CAS) projection where acronyms are persisted as first-class glossary_term objects linked to the VOC-KERNEL-ACRONYMS vocabulary scheme.
  3. Declarative ZQL Ingestion: Supports declarative seed loading via ZQK Query Language (ZQL) upsert scripts, enabling versioned taxonomy updates and schema migrations.
  4. Approximate Matching & Typo Tolerance: Combines prefix matching, substring containment, and bounded Levenshtein distance metrics (edit distance \(\le 2\)) to provide deterministic "Did you mean..." suggestions for misspelled terms.
  5. Static Floor Coverage Invariant: Adheres to a strict statement test coverage invariant (\(\ge 85.0\%\), verified at 98.0%) ensuring all parsing branches, fallback paths, and concurrent access patterns are rigorously verified.

2. Component Topology & Subsystem Architecture

The subsystem consists of four core building blocks operating around a unified typed projection model:

flowchart TD
    subgraph Consumers["Subsystem Consumers"]
        CLI["CLI Commands\n(zqk explain, zqk)"]
        Swarm["Autonomous AI Agents\n& MCP Mesh"]
        Workflow["Workflow & Whats-Next Engine"]
    end

    subgraph Subsystem["Acronym Vocabulary Subsystem (pkg/acronyms)"]
        Registry["Thread-Safe In-Memory Registry\n(RWMutex Cache & Canonical Seeds)"]
        Projection["Glossary Term Projection\n(ToGlossaryTerm / FromGlossaryTerm)"]
        StorageSync["Storage Synchronizer & Query Router\n(ListFromStore, LookupInStore, SyncToKernel)"]
        FuzzyMatcher["Approximate Search Engine\n(Prefix, Substring, Levenshtein)"]
        ZQLParser["Declarative ZQL Ingestor\n(LoadFromZQLSeed)"]
    end

    subgraph Membrane["Kernel Storage Membrane (CAS)"]
        VocScheme["vocabulary_scheme\n(VOC-KERNEL-ACRONYMS)"]
        GlossaryTerms["glossary_term Objects\n(GLS-ACRONYM-*)"]
    end

    CLI -->|"Lookup / Explain"| Subsystem
    Swarm -->|"Progressive Disclosure Queries"| Subsystem
    Workflow -->|"Taxonomy Resolution"| Subsystem

    StorageSync <-->|"Read / List / Sync"| Membrane
    ZQLParser -->|"Register Upserts"| Registry
    Registry <-->|"Seed & Offline Fallback"| StorageSync
    Projection <-->|"Bidirectional Mapping"| StorageSync
    FuzzyMatcher <-->|"Suggest Nearest"| Registry
    FuzzyMatcher <-->|"Suggest From Store"| StorageSync

Component Responsibilities

Component Source Element Core Responsibility
Acronym Registry registry, RegistryMu Thread-safe in-memory cache seeded with canonical bootstrap terms. Ensures offline availability during bootstrap, install, and network isolation.
Glossary Projection ToGlossaryTerm, FromGlossaryTerm Bidirectional adapter transforming between the typed Acronym Go struct and spec-compliant glossary_term object maps (Schema 2.0.0).
Store Synchronizer SyncToKernel, LoadFromKernel, ListFromStore, LookupInStore Bridges in-memory projections with live CAS storage, reconciling vocabulary schemes and glossary objects.
Approximate Search Engine FindClosest, FindClosestInStore, levenshtein Multi-tier fuzzy matching algorithm evaluating prefix containment, substring presence, and Levenshtein distance \(\le 2\).
ZQL Seed Ingestor LoadFromZQLSeed, exprToValue Compiles declarative ZQL scripts and hydrates the registry from structured AST statements.

3. Canonical Kernel Acronym Taxonomy

The subsystem maintains 16 foundational acronyms that establish the architectural and operational vocabulary of the Knowledge Kernel:

Acronym Full Name Ontological Category Operational Definition
BLI Backlog Item work A discrete, tracked work package or deliverable scheduled within a Priority Plan.
PRI Priority Plan work A time-bounded execution plan defining prioritized work packages and delivery horizons.
REQ Requirement specification A formal system invariant, capability, or architectural specification. Proven by at least three orthogonal criteria.
CRIT Criterion verification An objective, verifiable acceptance condition proving a requirement (Static Floor, Operational Proof, Negative Boundary).
VDS Verification & Verifiable Decomposition Spine verification The 5-layer unbroken verification lineage connecting Vision, Goals, Plans, Requirements/Criteria, and Backlog Items.
TCFG Team Configuration organization Approved team composition, agent roster, and operational permissions.
CVS Convergence Session coordination A structured cybernetic feedback session that closes deltas between projected and actual system state.
ATK Agent Task execution A granular, autonomous unit of work assigned to and executed by an agent persona.
PPLAN Priority Plan Verb cli CLI command shortcut group for inspecting active priority plans and current workloads.
ZPARQL ZQK Pattern Query Language graph Declarative graph pattern matching and query engine for traversing kernel object relationships.
ZQL ZQK Query Language query Declarative object query, mutation, and filtering expression language.
CAS Content-Addressable Storage storage Immutable, cryptographic hash-indexed object storage layer forming the kernel membrane.
WAL Write-Ahead Log storage Append-only sequential ledger guaranteeing atomic state mutations and crash recovery.
CAP Continuous Autonomous Protocol governance The self-driving cybernetic feedback loop steering agents without human intervention.
CEF Community Evaluation Framework evaluation Comprehensive quality scorecard, testing pyramid, and Diamond Scale grading rubric.
TDE Technical Debt Entry hygiene An objectified defect, architectural smell, or maintainability liability tracked for resolution.

4. Progressive Disclosure Dynamics

Progressive disclosure is a core design principle across human-agent collaboration in ZQK.

sequenceDiagram
    autonumber
    actor Agent as Autonomous AI Agent
    participant CLI as CLI Engine / MCP Server
    participant Subsys as Acronym Subsystem (pkg/acronyms)
    participant Store as Kernel CAS Storage

    Note over Agent,CLI: Phase 1: High-Density Context Exchange
    Agent->>CLI: Inspect active workload
    CLI-->>Agent: "Active: PRI cycle with 3 BLIs satisfying REQ via VDS spine"
    Note over Agent: Agent operates efficiently without token bloat

    Note over Agent,CLI: Phase 2: On-Demand Expansion (Progressive Disclosure)
    Agent->>CLI: zqk explain VDS
    CLI->>Subsys: LookupInStore(ctx, secCtx, store, "VDS", "VOC-KERNEL-ACRONYMS")
    Subsys->>Store: Read("GLS-ACRONYM-VDS")
    alt Term found in CAS
        Store-->>Subsys: glossary_term map
        Subsys-->>CLI: Acronym struct (FullName, Definition, Category, RelatedRefs)
    else Fallback to in-memory seed
        Subsys->>Subsys: Lookup("VDS")
        Subsys-->>CLI: Canonical seed Acronym
    end
    CLI-->>Agent: "VDS: Verification & Verifiable Decomposition Spine\nCategory: verification\nDefinition: The 5-layer unbroken verification lineage..."

The Progressive Disclosure Lifecycle

  1. Phase 1: High-Density Token Transmission: - Swarm prompts, commit logs, event streams, and agent status feeds use standardized acronyms (BLI, PRI, REQ, CRIT, VDS). - Token consumption per interaction is minimized, keeping prompts within strict model context windows.

  2. Phase 2: Semantic Expansion on Demand: - When an autonomous subagent or developer requires disambiguation, they invoke zqk explain <CODE> or the equivalent MCP tool. - The query traverses the acronym subsystem, retrieving the full title, category, expanded definition, and related ontological references.

  3. Phase 3: Typo Remediation & Approximate Search: - If an acronym is misspelled (e.g., VDZ), the approximate match engine computes nearest neighbors (e.g., VDS) and returns suggestions deterministically.


5. Storage Projection & Dual-Mode Mechanics

The subsystem features a dual-mode persistence architecture ensuring zero downtime across uninitialized, offline, and production environments:

stateDiagram-v2
    [*] --> OfflineBootstrap : Engine Startup
    OfflineBootstrap --> MemoryRegistry : populateFallbackSeed()
    MemoryRegistry --> LiveStorage : Kernel Online / Storage Available
    LiveStorage --> CASQuery : LookupInStore / ListFromStore
    CASQuery --> CacheHit : Found in CAS (GLS-ACRONYM-*)
    CASQuery --> CacheMissFallback : Not in CAS -> Fallback to MemoryRegistry
    LiveStorage --> SyncToKernel : zqk explain --sync / Bootstrap Sync
    SyncToKernel --> CASStored : Write VOC-KERNEL-ACRONYMS & Terms

Object Mapping Specification

When projected to CAS, each acronym translates to a standard glossary_term object conforming to Schema Version 2.0.0:

{
  "id": "GLS-ACRONYM-BLI",
  "kind": "glossary_term",
  "title": "BLI (Backlog Item)",
  "status": "active",
  "scheme_ref": "VOC-KERNEL-ACRONYMS",
  "category": "work",
  "context_scope": "operational",
  "definition": "A discrete, tracked work package or deliverable scheduled within a Priority Plan.",
  "description": "A discrete, tracked work package or deliverable scheduled within a Priority Plan.",
  "agent_prompts": "Expanded meaning: Backlog Item. Use for progressive disclosure.",
  "machine_hints": "{\"acronym\":\"BLI\",\"full_name\":\"Backlog Item\",\"related_refs\":[\"PRI\",\"REQ\",\"CRIT\",\"ATK\"],\"scheme_ref\":\"VOC-KERNEL-ACRONYMS\"}",
  "namespace_id": "zqk:kernel",
  "schema_version": "2.0.0",
  "source_type": "internal"
}

Declarative ZQL Seed Ingestion

The subsystem supports declarative runtime loading using ZQL mutation syntax:

BEGIN TRANSACTION;

UPSERT glossary_term ID "GLS-ACRONYM-EXAMPLE" {
    title: "EXAMPLE (Example Acronym)",
    category: "specification",
    definition: "An illustrative acronym loaded declaratively via ZQL",
    context_scope: "operational"
};

COMMIT TRANSACTION;

6. Approximate Match & Suggestion Mechanics

When an acronym query fails an exact match, the subsystem evaluates candidate terms using a three-tier approximation pipeline:

flowchart TD
    Query["Incoming Query String"] --> Normalize["Trim Whitespace & ToUpper"]
    Normalize --> ExactCheck{"Exact Match in Registry / CAS?"}
    ExactCheck -->|"Yes"| ReturnExact["Return Exact Acronym"]
    ExactCheck -->|"No"| PrefixCheck{"Prefix or Substring Matches?"}
    PrefixCheck -->|"Matches Found"| SortPrefix["Sort Matches Alphabetically & Return"]
    PrefixCheck -->|"None Found"| LevenshteinCalc["Compute Levenshtein Distance for All Terms"]
    LevenshteinCalc --> DistFilter{"Distance <= 2?"}
    DistFilter -->|"Yes"| SortDist["Sort Nearest Neighbors Alphabetically & Return"]
    DistFilter -->|"No"| ReturnEmpty["Return Empty Slice (No Match)"]

Ranking & Distance Rules

  1. Exact Match: Evaluated case-insensitively with whitespace trimmed.
  2. Prefix Match: Matches any term starting with the query string (e.g., query "AL" matches "ALPHA", "ALPHABET").
  3. Substring Match: Matches any term containing the query string (e.g., query "ETA" matches "BETA").
  4. Levenshtein Distance: For query strings without prefix/substring containment, candidates with an edit distance \(\le 2\) are returned (e.g., query "DELTO" matches "DELTA").
  5. Deterministic Sorting: All returned candidate slices are sorted alphabetically by code to guarantee deterministic CLI and agent output.

7. Verification & Statement Coverage Invariant

The subsystem enforces a strict statement coverage invariant (\(\ge 85.0\%\), verified at 98.0%) anchored by the Three-Fold Proof:

Three-Fold Proof Coverage Model:
┌────────────────────────────────────────────────────────────────────────┐
│ 1. Static Floor Invariant:                                             │
│    - All 16 canonical seed acronyms present with valid categories,     │
│      full names, definitions, and operational context.                 │
│                                                                        │
│ 2. Operational Dynamic Proof:                                          │
│    - Case-insensitive lookups, sorting invariants, format tables,     │
│      bidirectional glossary_term projections, and live CAS sync.       │
│                                                                        │
│ 3. Negative Adversarial Boundary:                                      │
│    - Malformed ZQL scripts, invalid glossary schemas, missing terms,   │
│      storage provider failures, and concurrent read/write safety.      │
└────────────────────────────────────────────────────────────────────────┘

Verification Execution

Targeted unit and boundary tests are executed using:

ZQK_ALLOW_FOREGROUND_GO_TEST=1 go test -v -timeout 30s -cover ./pkg/acronyms
=== RUN   TestCanonicalSeedTerms_Integrity
--- PASS: TestCanonicalSeedTerms_Integrity (0.00s)
=== RUN   TestToGlossaryTerm_Variations
--- PASS: TestToGlossaryTerm_Variations (0.00s)
=== RUN   TestFromGlossaryTerm_ValidationAndFallbacks
--- PASS: TestFromGlossaryTerm_ValidationAndFallbacks (0.00s)
=== RUN   TestExprToValue_Scenarios
--- PASS: TestExprToValue_Scenarios (0.00s)
=== RUN   TestLoadFromZQLSeed_SyntaxAndEdgeCases
--- PASS: TestLoadFromZQLSeed_SyntaxAndEdgeCases (0.00s)
=== RUN   TestListFromStore_AllScenarios
--- PASS: TestListFromStore_AllScenarios (0.00s)
=== RUN   TestLookupInStore_Scenarios
--- PASS: TestLookupInStore_Scenarios (0.00s)
=== RUN   TestFindClosestInStore_Scenarios
--- PASS: TestFindClosestInStore_Scenarios (0.00s)
=== RUN   TestLoadFromKernel_Scenarios
--- PASS: TestLoadFromKernel_Scenarios (0.00s)
=== RUN   TestLookupAndListAll_DirectCache
--- PASS: TestLookupAndListAll_DirectCache (0.00s)
=== RUN   TestFormatTable
--- PASS: TestFormatTable (0.00s)
=== RUN   TestSyncToKernel_AllScenarios
--- PASS: TestSyncToKernel_AllScenarios (0.00s)
=== RUN   TestLevenshteinDistance
--- PASS: TestLevenshteinDistance (0.00s)
=== RUN   TestConcurrency_SafeOperations
--- PASS: TestConcurrency_SafeOperations (0.00s)
PASS
coverage: 98.0% of statements
ok      github.com/zqk-os/zqk/pkg/acronyms  0.068s  coverage: 98.0% of statements

8. Operational CLI Recipes

Inspecting Acronyms via CLI

# Explain a specific kernel acronym
zqk explain BLI

# Output:
# BLI: Backlog Item (Category: work)
# Definition: A discrete, tracked work package or deliverable scheduled within a Priority Plan.
# Related: PRI, REQ, CRIT, ATK

# List all registered acronyms in formatted ASCII table
zqk explain --all

# Query with approximate match (typo correction)
zqk explain BL
# Output suggests: BLI

Synchronizing Seed Taxonomy into Live Kernel Storage

# Synchronize canonical seeds to live CAS storage
zqk explain --sync