Packages Directory

Status: Active
Last Updated: AUTO-GENERATED - Do not edit manually

This directory contains Go packages for the ZQK project. Each package is a modular component with a defined boundary and contract.

⚠️ This README is auto-generated. To update it, run:

./scripts/open-core/generate-code-readme-index.sh pkg

Packages Index

Package Structure

pkg/
├── accumulator/          # Aggregation and time-windowed rollups for execution metrics,
├── acronyms/          # Acronyms component and domain abstractions for ZQK Core.
├── adapters/          # The vendor-neutral factory for host/IDE message delivery. Ke
│   └── antigravity/
│   └── gemini/
│   └── golang/
│   └── macos/
│   └── ollama/
│   └── openai/
│   └── qwen/
│   └── sync/
├── agent/          # Cryptographic utilities, key management, and security identi
├── agentclaim/          # Agent work claiming, cadence check-ins, lease acquisition, a
├── agentdelivery/          # Host-neutral delivery of messages, steers, and task notifica
│   └── adapter/
├── agentfeed/          # Bidirectional agent message feed, event streaming, human-in-
│   └── bridge/
│   └── httpapi/
├── agentidle/          # Agent idle state detection, persistence, sleep management, a
├── agentonboard/          # Workspace-to-kernel synchronization and agent seating for fi
├── agentpack/          # Domain object pack loader and runtime registration for agent
├── agentprompt/          # Prompt assembly, template rendering, and contextual prompt i
├── agentrules/          # Parsing, validation, and enforcement of agent behavioral rul
├── aliases/          # Command and object alias resolution, shorthand mapping, and 
├── ambience/          # Background ambient intelligence, contextual awareness, and e
├── ambient/          # Filesystem watcher daemon, ambient change detection, and rea
├── appledouble/          # Sanitization and handling of AppleDouble and macOS resource 
├── architecture/          # Codebase architectural boundaries, layering rules, and stati
├── audit/          # High-volume audit log streaming, event persistence, and vali
├── authcred/          # Secure credential storage, token management, and authenticat
├── batchaf/          # Batch aggregation and resolution for orphaned requirements, 
├── bootstrap/          # Embedded bootstrap archive for zqk system init.
├── brand/          # Product branding, executable names, channel flags, and envir
│   └── substitution/
├── bridge/          # Bidirectional communication bridge connecting IDEs and exter
│   └── engine/
│   └── impl/
├── bufferpool/          # Reusable memory buffer pools for high-throughput zero-alloca
├── cef/          # Critical Evidence Framework (CEF) evaluation, evidence lift 
├── circuitbreaker/          # Fault tolerance circuit breaker pattern preventing cascade f
├── cleanup/          # Workspace cleanup, orphaned temp file purging, and transient
├── cli/          # This package provides the command-line interface infrastruct
│   └── bldr_cli_cmd_v1/
│   └── commands/
│   └── flagutil/
│   └── printer/
│   └── ux/
├── cliapp/          # Import path: github.com/zqk-os/zqk/pkg/cliapp.
│   └── context/
│   └── errorsuggest/
│   └── flagutil/
├── clihooks/          # CLI execution hooks, pre/post-command intercepts, and teleme
├── closureevidence/          # Evidence collection and cryptographic verification for backl
├── community/          # Open-source community distribution, telemetry anonymization,
├── concurrency/          # This package provides standardized concurrency primitives an
├── config/          # Kernel configuration loading, YAML parsing, environment over
├── context/          # Context management, security principal propagation, and requ
├── contextevents/          # Event dispatching and subscription scoped to execution conte
├── contractchange/          # Tracking and auditing schema and contract mutations across k
├── convergence/          # Target state convergence controllers, admission checks, and 
├── convergerollup/          # Rollup reporting and outcome aggregation for convergence eva
├── coordination/          # The coordination package provides the central event coordina
├── crypto/          # Ed25519 cryptographic signing, token validation, and artifac
├── daemon/          # Background daemon supervisor, process lifecycle management, 
│   └── overseer/
│   └── singleton/
├── datacell/          # Data cell coordinator membrane around stream storage and con
├── datacellregistry/          # Registry and discovery catalog for active project data cells
├── decisionpack/          # Decision domain pack registering decision object lifecycles,
├── diagnostics/          # Runtime diagnostics, stack dumps, memory profiling, and syst
├── diskusage/          # Storage footprint calculation, quota monitoring, and disk ca
├── dispatch/          # Thread-safe execution dispatching, worker routing, and conte
├── displaypack/          # Display and visual formatting pack for terminal rendering an
├── dna/          # Dna component and domain abstractions for ZQK Core.
│   └── pm/
├── docman/          # Documentation discovery, frontmatter verification, and index
├── domain/          # Domain-driven design entity models, value objects, and organ
│   └── organizational/
├── drifthotspots/          # Detection and heatmapping of code and specification drift ac
├── economy/          # Agent token economy, resource budgeting, compute metering, a
├── entitlements/          # Role-based feature access control, license entitlement gates
├── envelope/          # Standardized message envelope format for inter-process and n
├── errfmt/          # Structured error formatting, actionable error reporting, and
├── events/          # Event bus, overlay event streams, and asynchronous event pub
├── evolution/          # Schema migration, data model version evolution, and compatib
├── evolutionpack/          # Model evolution pack managing version upgrade chains and dep
├── execwrap/          # Context-aware, safe execution wrappers around operating syst
├── featureflags/          # Dynamic runtime feature toggles and progressive rollout swit
├── federation/          # Cross-kernel mesh federation, remote project peering, and di
│   └── meshbroker/
├── filter/          # Lexical filter expressions, object predicate evaluation, and
├── fitness/          # Architecture fitness functions and automated compliance scor
├── functional/          # A fluent, functional-style Go API for monadic error handling
├── gantt/          # Gantt timeline generation, SVG visual rendering, and roadmap
├── git/          # Git operations wrapper, branch inspection, worktree manageme
├── gitconstants/          # Centralized Git command, subcommand, flag, and option consta
├── gitevidence/          # Git commit evidence verification, trunk tip freshness, and b
├── gitplumbing/          # Gitplumbing component and domain abstractions for ZQK Core.
├── goroutinelabels/          # The GoroutineBuilder provides a fluent API for creating goro
├── gotestparse/          # Streaming parser and event normalizer for go test terminal o
├── graph/          # This package implements the pluggable graph backend interfac
│   └── databook/
│   └── memgraph/
│   └── provider/
│   └── rpcpool/
│   └── schema/
│   └── sync/
├── grooming/          # Automated backlog grooming, criteria validation, and orphane
├── handslapper/          # Path containment enforcement, directory traversal prevention
├── healthcheck/          # Subsystem health monitors, liveness/readiness probes, and di
│   └── monitors/
├── hive/          # Multi-agent hive primitives, shared memory structures, and c
│   └── capability/
│   └── inbox/
│   └── media/
├── hivemind/          # Distributed agent knowledge graph, activity logging, and sha
│   └── bridge/
│   └── indexer/
│   └── providers/
│   └── sync/
├── hostload/          # Host machine CPU, memory, and I/O load monitoring for dynami
├── httpheaders/          # HTTP header constants, canonical header names, and utility p
├── idebridge/          # IDE communication protocol bridge, editor command integratio
├── idehooks/          # IDE lifecycle event hooks, workspace notification triggers, 
├── infrastructure/          # Core infrastructure components, hardware abstraction, and cr
│   └── crypto/
│   └── hts/
├── ingestion/          # Data ingestion pipeline, file format adapters, and document 
│   └── adapters/
├── integrity/          # Kernel state integrity verification, hash validation, and ta
├── interactionpolicy/          # User-agent interaction constraints, confirmation prompts, an
├── interactive/          # Interactive terminal UI components, prompts, select menus, a
├── interfacepack/          # Interface contract and API boundary specifications pack.
├── kernel/          # Knowledge Kernel bootstrap sequence, runtime lifecycle, and 
│   └── intake/
│   └── mutation/
│   └── steward/
│   └── verification/
├── kernelcas/          # Kernel Content-Addressable Storage (CAS) integration and obj
│   └── compose/
├── kindnames/          # Canonical naming constants and normalization rules for kerne
├── kindsynonyms/          # Synonym mapping, alias resolution, and plural-to-singular ki
├── librarypack/          # Reusable component library pack registering shared traits an
├── license/          # Open-source license compliance, copyright header verificatio
├── lifecycle/          # Kernel object lifecycle state machine, phase transitions, an
├── llm/          # LLM client abstractions, prompt completion handlers, and mod
│   └── semanticcache/
├── loader/          # Abstract **component loader** pattern: shared state as atomi
├── localci/          # Studio-local CI checkout and demote in pure Go. Production m
├── lockhealth/          # Verified stale-lock cleanup primitives with fail-closed sema
├── logging/          # This package provides structured logging with context-aware 
├── maintenance/          # Scheduled maintenance tasks, garbage collection, and databas
├── mcp/          # This package provides a complete MCP server implementation t
│   └── ideadapter/
│   └── mcp_helpers/
│   └── testing/
├── mesh/          # Peer-to-peer agent mesh networking, ambient signal exchange,
│   └── multimodal/
├── metricpack/          # System and agent metric definitions pack for performance tra
├── metrics/          # Lock operation names for RunInLockWithLogger / RunInRLockWit
│   └── tsdb/
├── metricsrecording/          # Centralizes whether test runs should record metrics (storage
├── migration/          # This package implements the file-based to graph backend migr
│   └── detector/
│   └── exporter/
│   └── parser/
│   └── reporter/
│   └── resolver/
│   └── scanner/
│   └── validator/
│   └── writer/
├── mutation/          # Atomic kernel object mutation, version incrementing, and cha
├── nildecode/          # Generic helpers for type assertions with non-zero checks. Ke
├── objectcreate/          # Knowledge Kernel object creation helpers and schema validati
├── objectget/          # Object retrieval, lazy loading, dereferencing, and relations
├── objectidcache/          # The ObjectIDCache implementation extracted from cmd/zqk/syst
├── objectrecord/          # Objectrecord component and domain abstractions for ZQK Core.
├── objects/          # Kernel object graph repository, schema registration, and per
│   └── koi/
├── observability/          # Telemetry, distributed tracing spans, and operational visibi
├── observer/          # Lock operation names for RunInLockWithLogger / RunInRLockWit
├── ontology/          # Ontological relationship validation, semantic modeling, and 
├── opencore/          # Open core boundary enforcement, feature segregation, and ope
├── operational/          # Operational congruence reporting: disk vs index vs internal 
├── orchestration/          # Orchestration component and domain abstractions for ZQK Core
│   └── adversarial/
│   └── intent/
│   └── monitor/
│   └── reporting/
│   └── service/
│   └── ticker/
├── orgpack/          # Organizational hierarchy and team structure pack.
├── osmosis/          # Bi-directional state osmosis between local workspace and Kno
│   └── github/
├── osslaunch/          # Open-source launch automation, release readiness gates, and 
├── outputtypes/          # Standardized CLI output format types, table formatters, and 
├── packrecord/          # Verifies an uploaded spec pack and records its specs so thos
├── paths/          # Canonical project directory paths, file location resolvers, 
├── pipeline/          # This package provides a robust builder and runtime for the s
│   └── plugins/
├── pipelinepack/          # Pipeline and task workflow step pack.
├── pm/          # Program and project management models, milestones, and deliv
├── policy/          # Kernel policy definitions, enforcement hooks, and rule evalu
├── policyinterrupt/          # Emergency policy interrupts, execution halting, and safety i
├── precommit/          # Types and logic for the pre-commit hook that reads backgroun
├── predicate/          # Predicate component and domain abstractions for ZQK Core.
├── primaryorch/          # Primary agent orchestration engine, session coordination, an
├── process/          # Operating system process management, PID tracking, and grace
├── processhygiene/          # Workspace hygiene auditing, dead-code detection, and reposit
├── processing/          # Processing component and domain abstractions for ZQK Core.
├── projecttemp/          # Hosts isolated temp-project teardown helpers that must not i
├── qapack/          # Quality assurance, test coverage, and verification pack.
├── quality/          # Quality component and domain abstractions for ZQK Core.
├── quick/          # Parsing and helpers for one-click creation of system objects
├── relay/          # Message relay, inter-process communication, and agent event 
├── releasegate/          # Verification gates and multi-platform compilation tests for 
├── releasepack/          # Release gates, artifact generation, and deployment pack.
├── reports/          # Reports component and domain abstractions for ZQK Core.
├── reqharness/          # The test-requirements verification harness. It closes the lo
├── resourcehygiene/          # Resourcehygiene component and domain abstractions for ZQK Co
├── rollback/          # A reusable snapshot-and-rollback pattern for lifecycle trans
├── rollup/          # Rollup component and domain abstractions for ZQK Core.
├── runtime/          # Runtime environment detection, OS capabilities, and hardware
├── safepath/          # Builds filesystem paths confined under a root directory to m
├── scenario/          # Convergence lifecycle end-to-end tests (storage-backed CVS u
├── scheduler/          # Distributed job scheduler, cron execution, maintenance tasks
│   └── clusterstatus/
│   └── hostservice/
│   └── transceiver/
├── screencap/          # pkg/screencap provides headless and interactive terminal aut
├── search/          # pkg/search provides an in-process, pure-Go code search engin
├── seatworker/          # pkg/seatworker provides OS supervisor installation and lifec
├── security/          # Security policies, credential isolation, and capability veri
│   └── secretpatterns/
├── semantic/          # Semantic component and domain abstractions for ZQK Core.
│   └── graph/
│   └── translator/
├── service/          # Core service lifecycle, daemon startup, and background worke
├── shellcmd/          # pkg/shellcmd converts configured command strings into safe, 
├── shockwave/          # Event shockwave propagation, reactive state invalidation, an
├── shovelready/          # Shovel-ready work discovery, execution scoring, and backlog 
├── skill/          # Agent skill model definitions, capability declarations, and 
├── skills/          # This package tree (pkg/skills) implements autonomous agent s
│   └── breeding/
│   └── mutation/
├── specbuilder/          # This package provides the core infrastructure for the Spec-D
│   └── adapters/
│   └── api_builders/
│   └── bldr_config_v1/
│   └── bldr_instance_v1/
│   └── bldr_lifecycle_v1/
│   └── bldr_profile_v1/
│   └── bldr_routing_v1/
│   └── bldr_trait_v1/
│   └── bldr_v2/
│   └── bootstrap/
│   └── builders/
│   └── cli_builders/
│   └── config_builders/
│   └── core/
│   └── generators/
│   └── instance_builders/
│   └── lifecycle_builders/
│   └── profile_builders/
│   └── registry/
│   └── routing_builders/
│   └── trait_builders/
│   └── yaml/
├── specialization/          # pkg/specialization governs horizontal node segregation, comp
├── specorigination/          # Stable stage names for spec origination pipelines. Wire thes
├── stampmemo/          # A stamp-invalidated memo: the key is a stable identity, the 
├── stewardbase/          # Base interfaces and common abstractions for stream storage s
├── storage/          # This package provides a unified storage abstraction layer fo
│   └── audit/
│   └── binary/
│   └── cas/
│   └── crud/
│   └── file/
│   └── filecas/
│   └── graph/
│   └── id_generation/
│   └── locknames/
│   └── migration/
│   └── signedurl/
│   └── systemcheck/
│   └── wal/
├── storagetesting/          # Holds the minimal interfaces and option structs shared by [g
├── strutil/          # String manipulation, token extraction, and text formatting u
├── studio/          # Visual Studio Web UI backend, asset serving, and interactive
│   └── components/
├── supervision/          # Process supervision trees, worker restarts, and crash resili
├── supply/          # Dependency supply chain validation, vendor verification, and
├── swarm/          # Multi-agent swarm coordination, task allocation, and consens
│   └── metabolism/
│   └── pack/
│   └── remote/
├── swarminit/          # Runs configurable mesh bring-up recipes stored as kernel pip
├── system/          # System-level diagnostics, host environment inspection, and O
├── systemcheck/          # Holds shared types and helpers for zqk system check / valida
│   └── asynccheck/
│   └── autofix/
│   └── congruence/
│   └── integrity/
│   └── policy/
│   └── snapshot/
├── systemcheckwake/          # Evaluates system-check summaries and optionally wakes a mesh
├── systempeel/          # Layered system abstraction peeling and kernel introspection 
├── tde/          # Tde component and domain abstractions for ZQK Core.
├── tdval/          # Test-driven validation engines, acceptance criteria gates, a
├── telemetry/          # This package provides telemetry tracking, diagnostics hooks,
├── testdiscovery/          # Import ( "context" "os" "path/filepath" "strings" "testing" 
├── testenvroot/          # A minimal test project layout (.zqk/process + test-settings)
├── testing/          # This package provides test configuration support to isolate 
├── testkit/          # Reusable test helpers intended for extraction into a shared 
│   └── dummy_policy/
├── testpackageconcurrency/          # Concurrency test fixtures, race detection harnesses, and syn
├── testrunner/          # Automated test runner execution, timeout management, and rep
├── testservices/          # Manages optional test-side services (e.g. MemGraph via Docke
├── tpm/          # Technical Program Management scheduling, Gantt tracking, and
├── tracing/          # OpenTelemetry and distributed trace context propagation.
├── translation/          # Translates imported ontology/schema formats (RDF/OWL, JSON S
├── transport/          # Transport component and domain abstractions for ZQK Core.
├── traversal/          # Knowledge graph traversal algorithms, depth-bounded search, 
├── tray/          # Loads named shortcuts ("Tray") that expand to zqk argv lists
├── tui/          # Tui component and domain abstractions for ZQK Core.
│   └── tds/
├── utils/          # Generic cross-cutting utility functions and data structures.
│   └── chunking/
│   └── fileutil/
│   └── mcp_harness/
│   └── sortutil/
│   └── syscallutil/
├── validation/          # This package provides object validation for zqk: instance va
│   └── qa/
│   └── scenario/
├── vds/          # Verifiable Decomposition Spine (VDS) verification, traceabil
├── verification/          # Formal verification of kernel constraints, schemas, and inva
├── vet/          # Code quality vetting, static analysis rules, and repository 
├── vocabularypack/          # Canonical domain terminology and glossary definitions pack.
├── walutil/          # Walutil component and domain abstractions for ZQK Core.
├── when/          # When component and domain abstractions for ZQK Core.
├── workflow/          # Workflow execution engine, what's next recommendation, and s
│   └── whatsnext/
├── workflowpack/          # Standard workflow step execution and sequence pack.
├── workpack/          # The included planning and verification pack. The composition
├── wsobs/          # Wsobs component and domain abstractions for ZQK Core.
├── zqkcli/          # Cobra command integration, flag binding, and CLI command dis
├── zqkdev/          # Developer tooling, local test fixtures, and environment setu
├── zqkenv/          # Environment variable configuration, test mode detection, and
│   └── agentguard/
├── zqksession/          # Manages persisted ZQK session lifecycle state. p
├── zqktime/          # Deterministic UTC time helpers and RFC3339 compliance enforc

Usage

Import packages using their canonical import path:

import "github.com/zqk-os/zqk/pkg/agentfeed"

Related Documentation

• Project README - Project overview
• Architecture Docs - System architecture
• Verifiable Decomposition Spine - Done-gates and contracts

---

This README was auto-generated. Packages are discovered dynamically from the file system.