Developer & Agent Guides

Practical, battle-tested execution guides for human software engineers and autonomous AI agents working within the ZQK Knowledge Kernel.


Overview

While the Reference Manual details comprehensive subsystem APIs and Specifications formalize architectural grammar, these Guides provide step-by-step, actionable recipes for common engineering disciplines, graph operations, and multi-agent coordination patterns.

Every guide is structured to serve both human pair programmers using the interactive CLI/TUI and autonomous AI agents operating via headless interfaces or Model Context Protocol (MCP) tools.


Operational Guide Directory

1. Knowledge Graph & Data Plane Operations

Guide Focus Area Target Audience Primary CLI & MCP Commands
Knowledge Kernel Object Model & Usage Guide Canonical taxonomy across all 14 ontological domains and packs (70+ object kinds), standard envelopes, VDS cascade, and copy-pasteable CLI recipes. All Engineers & Agents zqk object create, zqk object list, zqk object ref add, zqk object promote
CLI Kind Alias Parity Guide Specification of canonical kind shorthand aliases (tst, tc, crit, req, pri, bli, mil, goal) across zqk new and object new CLI entrypoints. All Engineers & Agents zqk new, zqk object new, pkg/kindsynonyms
Object Scaffolding Hygiene and Reference Field Initialization Guide Reference field initialization invariants across CLI scaffolding templates, omission of optional references, empty array typing, and strict validation. All Engineers & Agents zqk object template, zqk new, pkg/validation
Kernel Subsystem Operational & Architectural Guide Cellular microkernel architecture, KnowledgeKernel lifecycle, relational graph membrane, adjacency engine, plane boundary enforcer, extension registry, and >=85.0% coverage invariant. Kernel Architects & Agents pkg/kernel
Knowledge Management, Vocabularies & Semantic Recall Operational glossaries, lens taxonomies, composable libraries, docman CAS verification, and on-demand recall protocols. AI Agents, Architects, SREs zqk docman register, zqk docman verify, zqk object list glossary_term
Declarative Graph Queries (ZPARQL) & Atomic Mutations (ZQL) Multi-hop graph traversals, Cypher-like pattern queries, and atomic multi-object ACID transactions. AI Agents, Backend Devs zqk query, zqk mutate, query_zparql, mutate_zql
Object Lifecycle, State Machines & CAS Storage Schema contracts, Content-Addressed Storage (CAS) membrane, two-phase draft/authoritative isolation, and DoD criteria binding. All Engineers & Agents zqk object create, zqk object inspect, zqk object promote
Objects & Specs Subsystem Operational & Architectural Guide Ontological schema contracts, spec roots, meta-schema compilation, trait normalization, and shockwave propagation. Kernel Architects & Agents pkg/objects
Spec Origination, Pipeline Triggers & Validation Subsystem Operational Architecture Guide Subsystem architecture, spec origination pipeline stages, idempotent trigger coordination, config membrane synchronization, validation scoping, and >=85.0% statement coverage invariant. Kernel Architects, Ontologists & AI Agents pkg/specorigination
Data Cell Registry & Read Model Cache Operational Architecture Guide Subsystem architecture, spec-to-runtime decoupling bridge, CellKindDescriptor lifecycle, in-memory read model memoization, cache revision tracking, and 98.5% statement coverage invariant. Kernel Architects, Storage Engineers & Autonomous AI Agents pkg/datacellregistry
System Ontology & Object Classification Subsystem Operational & Architectural Guide Semantic schema projection, 14 planning kinds, typed edge directional occupancy, thread-safe manager, data plane contextualizer, and >=85.0% coverage invariant. Kernel Architects & AI Agents pkg/ontology
Semantic Graph, AST Parsing & Inference Engine Subsystem Operational Architecture Guide Subsystem architecture, ontological translation, semantic maturity assessment (Levels 0-4), dynamic rule inference, drift reconciliation, and >=85.0% statement coverage invariant. Kernel Architects, AI Agents & Ontologists pkg/semantic
Schema Translation, Multi-Format Serialization & Cross-Model Converter Subsystem Operational Architecture Guide Subsystem architecture, TranslatorRegistry, multi-format deserialization and AST mapping (RDF/OWL, Turtle, RDF/XML, JSON-LD, Cypher, JSON Schema, OpenAPI), domain registry and object spec synthesis, thread-safe registry, and 98.9% statement coverage. Kernel Architects, Ontologists & Autonomous AI Agents pkg/translation
CLI Object Subsystem Operational Guide Subsystem command taxonomy, CAS storage membrane, two-phase draft plane isolation, and relational query pipelines. All Engineers & Agents zqk object create, zqk object get, zqk object list, zqk object update, zqk object delete, zqk object promote, zqk object demote, zqk object ref
CLI Command Taxonomy & Internal Operations Guide Subsystem architecture, internal command taxonomy, administrative role gates, bulk mutation engine, write-behind durability flushes, query-time grouping, and batch reference pipelines. All Engineers & Autonomous AI Agents zqk internal, pkg/zqkcli
Storage Subsystem Operational & Architectural Guide Foundational persistence engine, Content Addressable Storage (CAS), write-behind audit event buffering, transaction safety, and TSDB engine. Storage Engineers & Agents pkg/storage
Real-Time State Accumulator Subsystem Architectural Guide Subsystem architecture, Zero Hot-Path Scan Invariant (<5ms reads), dual-format deserialization, quiescent WAL detection, and asynchronous non-blocking recovery with >=85.0% statement coverage. All Engineers & Autonomous AI Agents pkg/accumulator
Write-Ahead Log Utilities Subsystem Architectural & Operational Guide Subsystem architecture, append-only line-delimited JSON log streams, dual-coordinate ReplayCursor checkpoints, hot-path sequence skipping, corrupted tail quarantine, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/walutil
High-Performance Buffer Pool Subsystem Operational & Architectural Guide Subsystem architecture, sync.Pool byte buffer recycling, 1MB retention ceiling, zero-allocation serialization, 64KB chunked streaming readers, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/bufferpool
Lifecycle Subsystem Operational & Architectural Guide Subsystem architecture, state machine transitions, event WAL persistence, reactive listener rules, waker registry, updater synchronization, shockwave dependency cascades, remaining open counting, and >=85.0% coverage invariant. Kernel Architects & Agents pkg/lifecycle
Lifecycle Rollback, Transaction Boundaries & Snapshot Management Subsystem Architectural & Operational Guide Subsystem architecture, transactional snapshot capture, WAL-backed rollback points, quick vs reconstruct restore pathways, multi-entity graph state reversion, lock operation boundaries, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/rollback
Contract Change, Outbox Dispatch & Mutation Lifecycle Subsystem Operational Architecture Guide Subsystem architecture, SPEC_ORIGIN to kernel shockwave outbox, stay-in-status invariant verification, lifecycle demotions, replay safety, corrupted record recovery, and 98.2% statement coverage. Kernel Architects, Distributed Systems Engineers & Autonomous AI Agents pkg/contractchange
Migration Subsystem & Schema Evolution Operational Architecture Guide Subsystem architecture, declarative migration specifications, composable step engine, snapshot-backed rollback points, lifecycle and UUID transformations, and >=85.0% statement coverage invariant. Kernel Architects, Storage Engineers & Autonomous AI Agents pkg/migration, pkg/migration/detector
Release Pack Composition, Object Kind Bindings & Spec Mapping Subsystem Architectural & Operational Guide Subsystem architecture, release pack composition root integration, object kind bindings, instance and lifecycle builder registrations, spec and lifecycle path mapping, and 100.0% statement coverage invariant. Kernel Architects, Release Engineers & Autonomous AI Agents pkg/releasepack
Decision Ontology Pack & Impact Analysis Subsystem Architectural & Operational Guide Subsystem architecture, decision pack composition root integration, owned kinds (decision, impact_analysis, question), spec and lifecycle state machines, blast-radius graph evaluation, and 100.0% statement coverage invariant. Kernel Architects, Governance Stewards & Autonomous AI Agents pkg/decisionpack
Vocabulary Pack, Ontology Dictionary & Domain Terminology Subsystem Architectural & Operational Guide Subsystem architecture, domain terminology, ontology dictionary schema, glossary terms, relations, vocabulary schemes, import tracking, pack composition root integration, and 100.0% statement coverage invariant. Kernel Architects, Ontologists & Autonomous AI Agents pkg/vocabularypack
Workflow Pack & Process Composition Subsystem Architectural & Operational Guide Subsystem architecture, workflow orchestration taxonomy, schema definitions, stages, role and account scoping, MCP tool configuration, pack composition root integration, and 100.0% statement coverage invariant. Kernel Architects, Process Engineers & Autonomous AI Agents pkg/workflowpack
Workpack Composition, Redundancy Analysis & Verification Engine Subsystem Operational Architecture Guide Subsystem architecture, 22 planning and verification kinds, workpack composition root integration, fail-closed spec and lifecycle verification, schema normalization, redundancy analysis algorithms, and 99.3% statement coverage. Kernel Architects, Quality Engineers & Autonomous AI Agents pkg/workpack
Metric Pack Subsystem & Telemetry Pipeline Operational Architecture Guide Subsystem architecture, metric pack composition root integration, 12 registered metric entity kinds, telemetry collection lifecycle, aggregation windows, ring buffers, memory limits, exporters (Prometheus/OpenTelemetry/stdout), backpressure handling, and 100.0% statement coverage invariant. Kernel Architects, SREs & Autonomous AI Agents pkg/metricpack, pkg/telemetry, pkg/metrics
Metrics Subsystem & Telemetry Pipeline Operational Architecture Guide Subsystem architecture, component taxonomy (counters, gauges, histograms, samplers, registry), thread-safe atomic update invariants, timeseries chunk storage, telemetry export pipeline integration, failure mode mitigation, and >=85.0% statement coverage invariant. Kernel Architects, SREs & Autonomous AI Agents pkg/metrics, pkg/telemetry, pkg/metricpack
Event Streaming & Action Router Subsystem Guide Subsystem architecture, bitmask event routing, localized policy inspectors, cascading overlay propagation, non-blocking delivery channels, and >=85.0% coverage invariant. All Engineers & Autonomous AI Agents pkg/events
Pipeline Subsystem Operational & Architectural Guide Composable execution stages, DAG executor, monotonic process mutation pipeline, multi-agent orchestrator state machine, git worktree isolation, TPM rate limiting, and >=85.0% coverage invariant. Kernel Architects & Agents pkg/pipeline
Shockwave Propagation, Event Accumulation & Pipeline Dispatch Subsystem Guide Subsystem architecture, shockwave ripples, decoupled pub/sub event pipeline, dynamic batch accumulation, gateway dispatching with reduce strategies, bounded worker neurons, and >=85.0% statement coverage invariant. Kernel Architects, Distributed Systems Engineers & Autonomous AI Agents pkg/shockwave
CLI Organizational Subsystem Architectural Guide Subsystem command taxonomy, domain modeling, impact analysis cascade, propagation lifecycle, and declarative structure sync. All Engineers & Agents zqk organizational record-change, zqk organizational analyze-impact, zqk organizational propagate, zqk organizational sync
CLI Application Subsystem Architectural & Operational Guide Root application bootstrap, command tree composition, execution context propagation, runtime diagnostics, and authentication middleware. All Engineers & Agents zqk, cmd/zqk/app
CLI Code Search Subsystem Operational & Architectural Guide Subsystem command taxonomy, pure-Go in-process search, trigram indexing, Go AST structural queries, and token-budgeted AI agent output. All Engineers & Agents zqk grep, zgrep
CLI Documentation Management Subsystem Operational & Architectural Guide Subsystem taxonomy, markdown metadata extraction, doc_entry registration pipeline, cryptographic drift verification, and auto-sealing. All Engineers & Agents zqk docman register, zqk docman verify
Docman Documentation Registry & Cryptographic Verifier Architecture Guide Subsystem architecture, document discovery hierarchy, Markdown AST parser integration, frontmatter extraction, doc_entry graph registry, read model caching, cryptographic drift verification, and auto-sealing. Kernel Architects, Documentation Engineers & Autonomous AI Agents pkg/docman, zqk docman
Paths & Directory Topology Subsystem Operational & Architectural Guide Subsystem filesystem topology, 4-tier project root discovery, runtime layout (.zqk/), ephemeral worktree isolation, trunk lock eviction, path resolver, and >=85.0% coverage invariant. Kernel Architects, SREs & Agents pkg/paths
CLI Query Subsystem Architectural & Operational Guide Subsystem command taxonomy, declarative ZPARQL pattern queries, interactive REPL console, graph edge path visualization, and >=85.0% coverage invariant. All Engineers & Agents zqk query, zqk query -i, zqk query --visualize
Knowledge Graph Traversal & Query Execution Subsystem Guide Subsystem architecture, ZPARQL pattern grammar, AST compilation, cost-based physical planner, cycle-safe DFS traversal, bounded streaming joins, and >=85.0% statement coverage invariant. Graph Engineers & AI Agents pkg/traversal, zqk query
Graph Mutation, Preflight Validation & Transaction Engine Subsystem Guide Subsystem architecture, ZQL grammar compilation, Draft 2020-12 AST, preflight invariant validation, atomic ACID transactions, multi-engine write isolation, rollback unwinding, and >=85.0% statement coverage invariant. Kernel Architects, Database Engineers & AI Agents pkg/mutation, zqk mutate
Expression Filtering & Time Parser Subsystem Architectural & Operational Guide Subsystem architecture, lexical filter parsing, comparison operators, pipe-separated sets, schema validation with fuzzy Levenshtein suggestions, relative time token resolution, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/filter
Time Standardization & Deterministic Simulation Subsystem Guide Subsystem architecture, UTC timestamp invariants, RFC3339/RFC3339Nano formatting, deterministic simulation and WAL replay, nil pointer safety, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/zqktime
Acronym Vocabulary & Progressive Disclosure Subsystem Guide Subsystem architecture, canonical acronym registry, VOC-KERNEL-ACRONYMS vocabulary scheme, live storage projection, approximate search, progressive disclosure, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/acronyms, zqk explain
Canonical Kind Synonyms & CLI Workflow Aliases Subsystem Operational Architecture Guide Subsystem architecture, canonical kind lookup, synonym dictionary mapping, plural normalization, whitespace and case-folding, concurrency-safe registry, and 100.0% statement coverage. All Engineers & Autonomous AI Agents pkg/kindsynonyms
Library Pack Composition, Object Kind Bindings & Spec Mapping Operational Architecture Guide Subsystem architecture, library pack composition root, spec and lifecycle directory bindings, kind registrations, omission build tags, and 100.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/librarypack
Display Pack and UI Specification Registry Operational Architecture Guide Subsystem architecture, display pack composition root, spec and lifecycle directory bindings, UI component/display kind registrations, omission build tags, and 100.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/displaypack
Evolution Pack and Migration Management Operational Architecture Guide Subsystem architecture, evolution pack composition root, spec and lifecycle directory bindings, evolution management kind registrations, omission build tags, and 100.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/evolutionpack
Interface Pack and API Command Contract Operational Architecture Guide Subsystem architecture, interface pack composition root, spec and lifecycle directory bindings, API and CLI command spec kind registrations, omission build tags, and 100.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/interfacepack
Organization Pack and Team Topology Registry Operational Architecture Guide Subsystem architecture, organization pack composition root, spec and lifecycle directory bindings, enterprise structure and team topology kind registrations, omission build tags, and 100.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/orgpack
Pipeline Pack and Stage Execution Engine Operational Architecture Guide Subsystem architecture, pipeline pack composition root, spec and lifecycle directory bindings, pipeline definition and stage kind registrations, omission build tags, and 100.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/pipelinepack
QA Pack and Quality Assurance Rules Operational Architecture Guide Subsystem architecture, QA pack composition root, spec and lifecycle directory bindings, quality metrics and validation rule kind registrations, omission build tags, and 100.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/qapack
Batch AF (Aggregation & Orphaned Processing) Subsystem Architectural & Operational Guide Subsystem architecture, dual-trigger batch aggregation, bounded worker pool execution, exponential backoff retries, orphaned batch reclamation, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/batchaf
Stamp Memoization & Generation Tracking Subsystem Guide Subsystem architecture, stamp-invalidated memoization, generation tracking, zero-copy view projections, non-blocking peek, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/stampmemo
Metric Rollup, State Convergence & Hierarchical Aggregation Subsystem Operational Architecture Guide Subsystem architecture, hierarchical progress aggregation, effort statistics distributions, multi-tier parent-child resolution, cycle-safe graph traversal, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/rollup
Convergence Rollup, BFS Tree Traversal & Reference Cycle Detection Subsystem Operational Architecture Guide Subsystem architecture, BFS tree traversal, cycle detection gates, parent-child nesting hierarchies, status aggregation invariants, and 98.8% statement coverage. Kernel Architects, Swarm Engineers & Autonomous AI Agents pkg/convergerollup, zqk scheduler convergence measure
Object Steward Base, Ingestion Enqueuer & Work Delivery Subsystem Architectural & Operational Guide Subsystem architecture, decoupled maintenance enqueuing, storage profile validation, bounded detail truncation, atomic JSONL queue persistence, structured logging, and 100.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/stewardbase
Storage Testing, Isolation Contracts & Decoupling Seams Architectural & Operational Guide Subsystem architecture, storage test isolation contracts, decoupling seams, test harness factory hooks, thread-safe mock isolation factory, and 100.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/storagetesting
Network Transport, Multiplexing & Connection Lifecycle Subsystem Operational Architecture Guide Subsystem architecture, transport protocol handlers, FTP/RPC transport wrappers, protocol multiplexing, connection lifecycle management, telemetry integration, and 100.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/transport
Developer Tooling, Spec Code Generation & Engineering Pipelines Subsystem Operational Architecture Guide Subsystem architecture, code generation pipelines (builders, field keys, spec index, lifecycle IDs), trait synthesis, AST-driven generation, concurrent worker dispatch, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/zqkdev, zqk system generate-*
Environment Variables, Secret Masking & Agent Execution Guards Subsystem Operational Architecture Guide Subsystem architecture, strongly-typed EnvVar descriptors, dynamic brand key resolution, cryptographic secret masking, agent execution guards (agentguard), subprocess isolation, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/zqkenv
Session Lifecycle, Worker Context & Identity Engine Subsystem Operational Architecture Guide Subsystem architecture, CLI session state persistence and reuse, worker context propagation, file lock synchronization, idle timeout invalidation, identity prefix validation, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/zqksession
LLM Provider Adapters, Streaming Protocol & Multi-Engine Dispatch Subsystem Operational Architecture Guide Subsystem architecture, vendor-neutral provider adapters (Antigravity, Gemini, OpenAI, Qwen, Ollama, Golang, MacOS, Sync), streaming delivery protocols, message normalization, execution gates, error recovery, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/adapters
LLM Client Abstraction & Provider Adapters Operational Architecture Guide Subsystem architecture, unified Client contracts, OpenAI and Gemini adapters, ResilientClient failover, StaticMockClient offline fallback, ToolBudget message token governance, prompt injection sanitization, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/llm
LLM Client Abstraction & Structured Tool Budget Operational Architecture Guide Subsystem architecture, unified Client contracts, structured tool calling, ToolBudget token estimation and message trimming, negative adversarial boundary resilience, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/llm
Agent Pack Architecture, Kind Registry & Lifecycle Schemas Operational Architecture Guide Subsystem architecture, pack metadata schemas, bundle registration, validation boundaries, kind taxonomy integration, lifecycle hooks, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/agentpack
Ambient EventMesh, Anticipatory Evaluation & In-Memory Dispatch Subsystem Operational Architecture Guide Subsystem architecture, in-memory event bus, async audit dispatch, subscription filters, anticipatory rule engine, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/ambience
Metrics Recording Policy, In-Memory Sampler & Sampling Invariants Operational Architecture Guide Subsystem architecture, metric recording policies, in-memory ring buffers, sampling invariants, rate limit governance, telemetry integration, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/metricsrecording
Metrics Recording Subsystem & Recorder Pipeline Operational Architecture Guide Subsystem architecture, recording policy gates, hot-path suppression circuit breaker, kind filtering, storage sink integration, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/metricsrecording
Kernel Bootstrap, Template Extraction & Greenfield Project Initialization Operational Architecture Guide Subsystem architecture, dual-path archive extraction (embedded vs source fallback), prefix routing, path jail containment, decompression bomb mitigations, community denylist filtering, and >=85.0% statement coverage invariant. Kernel Architects, Release Engineers & Autonomous AI Agents pkg/bootstrap, zqk system init
Component Loader Pattern, Atomic State Transitions & Timeout Envelope Subsystem Guide Subsystem architecture, Runner single-flight execution, atomic state transitions, multi-stage timeout envelopes (wait, publish, load), stamp memoized configuration, profile overrides, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/loader
Git Plumbing & VCS Snapshot Engine Operational Architecture Guide Subsystem architecture, isolated Git plumbing refs (refs/zqk/*), tree creation, snapshot capture, tar archive restoration, directory escape mitigation, remote synchronization (push/fetch), and >=85.0% statement coverage invariant. Kernel Architects, VCS Engineers & Autonomous AI Agents pkg/gitplumbing

2. Governance, Security & Policy DSL

Guide Focus Area Target Audience Primary CLI & MCP Commands
Validation Subsystem Architectural & Operational Guide Multi-layer validation architecture (Layers 0–4), AST invariant checks, async priority queue execution, automated remediation engine, and >=85.0% statement coverage invariant. All Engineers & Agents pkg/validation, zqk system check, zqk object inspect
Static AST Linting, Code Vetting Engine & Policy Rule Suite Subsystem Operational Architecture Guide Subsystem architecture, VetRunner orchestration, declarative GatesConfig, AST check suites (command specs, CLI builders, concurrency, duplication, paths/perms, tree police, payload guard), fail-fast thresholds, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/vet, zqk-vet
Architectural Drift Hotspots, AST Metric Barrel & Field Key Literal Fixer Subsystem Operational Architecture Guide Subsystem architecture, AST interval inspection, constant barrels and data catalog boundaries, 13 drift hotspot categories, automated field key literal AST rewriter, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/drifthotspots
System Check, Validator Registration & Violation Resolution Subsystem Operational Architecture Guide Subsystem architecture, ValidatorRegistry, bounded worker pool execution, spec-informed violation resolution, auto-remedy strategies, TPM feedback telemetry, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/systemcheck, zqk system check, zqk system telemetry
CLI Test Subsystem Architectural & Operational Guide Subsystem command taxonomy, 3-Fold Proof verification, test execution pipeline, AST contamination detector, parallel test runner, WAL event streaming, TUI test dashboard, and >=85.0% coverage invariant. All Engineers & Agents zqk test run, zqk test discover, zqk test dashboard, zqk test bind, zqk test check-contamination, zqk test identify-parallel, zqk test stream
Test Runner Execution, Parallel Safety, Race Gate & Event Streaming Subsystem Operational Architecture Guide Subsystem architecture, TestRunnerEngine, ParallelSafetyGovernor, RaceConditionGate, ContaminationSentinel, EventStreamMultiplexer, process group sandboxing, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/testrunner, zqk test run, zqk test stream
Polyglot Test Discovery, Engine Registry & Cache Subsystem Operational Architecture Guide Subsystem architecture, static AST/source parsing across Go, Python, TypeScript, and Rust, DiscoveryEngine, EngineRegistry, SHA-256 mtime incremental cache, zero-execution security boundaries, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/testdiscovery, zqk test discover
Hermetic Test Environment & Repo Mutation Guard Subsystem Operational Architecture Guide Subsystem architecture, isolated test root materialization, repo write protection, state modtime snapshotting, asset replication without repository contamination, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/testenvroot
Test-Requirements Verification Harness & Predicate Evidence Engine Operational Architecture Guide Subsystem architecture, POL-WORKFLOW-VDS evidence engine, scope:Name predicate grammar, verification lifecycle, prescriptive next actions remediation, sync.RWMutex registry, and 100.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/reqharness
Verifiable Delivery Standard (VDS), Chunk Evaluation & Predicate Evidence Engine Subsystem Operational Architecture Guide Subsystem architecture, Verifiable Decomposition Spine (POL-WORKFLOW-VDS), five rigid delivery stages, chunk evaluation engine, predicate DSL assertion matrix, vendor instruction projections, and >=85.0% statement coverage invariant. Kernel Architects, Quality Engineers & Autonomous AI Agents pkg/vds, zqk workflow vds
Continuous Verification Engine, Matrix Scorecard & Evidence Classification Subsystem Operational Architecture Guide Subsystem architecture, Universal Verification DSL strategies, content-addressed verification matrix, evidence classification, multi-language file profiling, diamond quality scoring, and >=85.0% statement coverage invariant. Kernel Architects, Quality Engineers & Autonomous AI Agents pkg/verification, pkg/verification/matrix
Object Closure Gate, Machine-Checkable Evidence Validation & Scheduler Health Fingerprinting Subsystem Operational Architecture Guide Subsystem architecture, fail-closed closure gate (machine_checkable_closure_evidence), bundle log disk verification, scheduler health.jsonl fingerprint matching, grandfathering transitions, and 100.0% statement coverage invariant. Kernel Architects, Quality Engineers & Autonomous AI Agents pkg/closureevidence
Scenario Testing, Behavioral Simulation & Convergence Playback Subsystem Operational Architecture Guide Subsystem architecture, scenario bundle application, doc convergence, traceability matrix resolution, creation order topological sorting, draft bundle authoring, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/scenario
Kernel Test Scaffolding, Deterministic Waiting & Scenario Test Harness Subsystem Operational Architecture Guide Subsystem architecture, TestEnvironment setup, deterministic condition waiting, scenario environment sandboxing, callback synchronization, snapshot verification, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/testing
Universal Testkit, Leak Detection & Hermetic Project Isolation Subsystem Operational Architecture Guide Subsystem architecture, hermetic project isolation, goroutine and subprocess leak profiling, managed subprocess groups, LIFO teardown pipelines, condition polling, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/testkit
Test Services Lifecycle, Fixture Management & Ephemeral Environment Subsystem Operational Architecture Guide Subsystem architecture, ServiceManager, ServiceConfig, HealthCheckEngine, PortPublisherSentinel, ContainerLifecycleGovernor, shared listener reuse, Docker orchestration, and 100.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/testservices
Custom Validation Policy Creation & Rule DSL Composing declarative Validation Rule DSL expressions, live population dry-run audits, grandfathering, and check-valve registration. Tech Leads, Governance Stewards zqk object inspect --policy-studio, zqk system check-policy
Agent Execution Rules & Manifest Governance Subsystem Guide Subsystem architecture, rule definition (*.mdc), manifest registry, candidate directory resolution hierarchy, diff engine, pre-commit enforcement, auto-healing, and >=85.0% coverage invariant. All Engineers & Autonomous AI Agents pkg/agentrules, zqk system validate-agent-rules
Predicate DSL & AST Evaluation Engine Subsystem Architectural & Operational Guide Subsystem architecture, formal EBNF grammar, tokenization, AST parser construction, truth table evaluation, built-in predicates, legacy prose overlay compilation, keyword salience engine, goroutinelabels concurrency, and >=85.0% statement coverage invariant. Kernel Architects, Governance Stewards & AI Agents pkg/predicate
Conditional Evaluation & Fluent Predicate Chains Subsystem Architectural & Operational Guide Subsystem architecture, fluent conditional chains, short-circuit evaluation, Try/Catch monadic containers, error preservation, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/when
Functional Programming Primitives & Result Monad Subsystem Architectural & Operational Guide Subsystem architecture, Result[T] monadic container, fluent combinators, collection transformations, telemetry-integrated execution, pure functions, immutability guarantees, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/functional
Generic Payload Decoding, Type Assertion & Nil-Safety Subsystem Operational Architecture Guide Subsystem architecture, generic type assertions, zero-value guards, Go typed-nil interface trap elimination, collection decoding, pure function concurrency invariants, and >=85.0% statement coverage. All Engineers & Autonomous AI Agents pkg/nildecode
Domain-Specific String Aliases & Canonical Normalization Subsystem Guide Subsystem architecture, domain-isolated static alias resolution, case-folding, whitespace normalization, cross-domain collision prevention, and 100.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/aliases
String Utilities & Distance Metrics Subsystem Architectural & Operational Guide Subsystem architecture, Levenshtein distance metrics, default fallback resolution, escape rune decoding, line-delimited token extraction, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/strutil
Safe Path Manipulation & Traversal Protection Subsystem Operational & Architectural Guide Subsystem architecture, JoinUnderRoot containment validator, lexical cleaner, relative resolver, symlink evaluation gate (F-SEC-006), Gosec G703 mitigation, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/safepath
Security Primitives, Path Traversal Defense & Release Security Subsystem Architectural & Operational Guide Subsystem architecture, path sanitization, root jail containment, release security verification, tool name validation, error taxonomy, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/security
AppleDouble Resource-Fork Sidecar & Filesystem Hygiene Subsystem Architectural & Operational Guide Subsystem architecture, macOS Finder/SMB resource fork sidecar detection, segment-aware path filtering, tree walk pruning, cross-platform path normalization, and 100.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/appledouble
Error Formatting, Actionable Diagnostics & Poison Pill Protection Subsystem Guide Subsystem architecture, Errorf wrapper, ErrorStringBuilder, poison pill electrocution defense, actionable diagnostics engine, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/errfmt
HandSlapper Drift Interceptor Subsystem Architectural & Operational Guide Subsystem architecture, pre-OS command inspection, tokenization, forbidden tool bypass detection, namespace containment (.zqk), strict electrocution sentinel, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/handslapper
Cryptographic Primitives & Key Management Subsystem Operational & Architectural Guide Subsystem architecture, Ed25519 digital signatures, JWT cryptographic stamps, public/private key management, tamper and replay defense, algorithm confusion mitigations, and >=85.0% statement coverage invariant. Kernel Architects, Security Engineers & Autonomous AI Agents pkg/crypto
Authentication Credential, RBAC Account Resolution & Seat Security Subsystem Operational Architecture Guide Subsystem architecture, credentials resolution, keystore caching, CAS listing index memoization, Account RBAC binding, Persona vocabulary schema, Discovery Membrane lane filtering, Prototype Rejection invariant, Seating directory isolation, and >=85.0% statement coverage. Kernel Architects, Security Engineers & Autonomous AI Agents pkg/authcred, zqk agent seat-worker
Role Entitlements, Capability Matrix & Object Elevation Operational Architecture Guide Subsystem architecture, dual-tier platform governance (Community vs Enterprise), offline Ed25519 cryptographic license verification, fail-closed fallback invariant, RBAC capability matrix, object elevation lifecycle, and 100.0% statement coverage. Kernel Architects, Security Engineers & Autonomous AI Agents pkg/entitlements, zqk object --internal
HTTP Headers Standardization & Canonicalization Subsystem Architectural & Operational Guide Subsystem architecture, RFC 7230/9110 canonicalization, CRLF injection defense, W3C trace context propagation, robust auth parsers, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/httpheaders
Task Decision Envelope, Decision Log & WAL Subsystem Guide Subsystem architecture, Time-Delayed Execution (TDE), cognitive governance, staging WAL, Crystalline Fortress hard-block, background commit daemon, and 100.0% statement coverage invariant. Kernel Architects, Security Stewards & AI Agents pkg/tde
Traceable Data Envelope Validator, Schema Integrity & Skill Seal Subsystem Guide Subsystem architecture, Traceable Data Envelope (TDE) validation, schema integrity checking, Skill Seal cryptographic verification, tamper detection, error taxonomy, and >=85.0% statement coverage invariant. Kernel Architects, Security Stewards & AI Agents pkg/tdval
Audit Policy Engine, Stream Multiplexing & Subscription Lifecycle Subsystem Operational Architecture Guide Subsystem architecture, PolicyEngine parallel evaluation, PolicyViolationError taxonomy, AuditStream multiplexing, slow subscriber backpressure drops, disk-backed JSONL WAL, and >=85.0% statement coverage invariant. Kernel Architects, Security Stewards & Autonomous AI Agents pkg/audit
Offline Cryptographic License Verification, Ed25519 Signatures & Feature Entitlements Architecture Guide Subsystem architecture, offline Ed25519 JWT verification, algorithm downgrade defense (strict EdDSA), fail-closed entitlement checks, and >=85.0% statement coverage invariant. Kernel Architects, Security Stewards & Autonomous AI Agents pkg/license

3. Autonomous Execution & Continuous Loops

Guide Focus Area Target Audience Primary CLI & MCP Commands
Single-Command Execution Loop (zqk do) 5-phase execution engine (Intent ➔ Preflight ➔ Locks ➔ Dispatch ➔ Verification), fail-closed invariant guards, and anti-thrashing discipline. Autonomous AI Agents zqk do <intent>, zqk workflow whats-next
CLI Do Subsystem Architectural & Operational Guide Subsystem command taxonomy, single-command autonomous execution loop, five-stage cycle (discover, claim, context-prepare, verify, latch), token conservation, and >=85.0% coverage invariant. All Engineers & Autonomous AI Agents zqk do, zqk auto-exec, zqk auto-do
CLI Application Subsystem Architectural & Operational Guide Subsystem lifecycle, execution topology, session persistence, runtime diagnostics, profiling, shell completions, and failure isolation. All Engineers & Agents zqk, cmd/zqk/app, zqk completion
CLI Workflow Subsystem Architectural & Operational Guide Subsystem command taxonomy, composite ambient routing, deterministic next-action resolution, gate preconditions, and VDS verification. All Engineers & Agents zqk workflow whats-next, zqk workflow next, zqk workflow check, zqk workflow add
Workflow Engine & Continuous Autonomy Subsystem Guide Ontological anti-superficiality linter, Three-Fold Proof validation, Whats-Next decision engine, CAP flywheel state machine, and >=85.0% coverage invariant. All Engineers & Autonomous AI Agents pkg/workflow, zqk workflow whats-next, zqk workflow lint
TPM Strategic Readiness, Three-Fold Phi Metrics & Gantt Matrix View Subsystem Operational Architecture Guide Subsystem architecture, Three-Fold Phi metrics (specification, traceability, execution fuel), domain clustering, runway depth evaluation, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/tpm
Shovel-Ready Backlog Evaluation, Dependency Topology & Batching Subsystem Guide Subsystem architecture, Definition of Ready (DoR) gates, CRI-SHOVEL-READY criteria, acyclic dependency topology validation, blocked ancestor resolution, readiness scoring, batch allocation, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/shovelready, zqk workflow whats-next, zqk do
CLI Ambient Compute Subsystem Architectural & Operational Guide Subsystem command taxonomy, singleton daemon supervision, background wave scheduling, automerge synchronization, and HTTP event ingestion. All Engineers & Agents zqk ambient, zqk ambient status, zqk ambient wave, zqk ambient automerge, zqk ambient ingest
Ambient Compute, EventMesh & Anticipatory Intent Subsystem Operational Architecture Guide Subsystem architecture, InMemoryEventMesh router, sliding-window and count-bounded SignalAggregator, FSEventsEngine anticipatory intent heuristics, audit event sourcing, deterministic teardown synchronization, and 100.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/ambience
CLI Scheduler Subsystem Architectural & Operational Guide Subsystem command taxonomy, singleton daemon supervision, keep-alive heartbeat, WAL event streaming, dead-letter escalation, maintenance skip windows, and >=85.0% coverage invariant. All Engineers & Agents zqk scheduler start, zqk scheduler stop, zqk scheduler status, zqk scheduler health-check, zqk scheduler submit, zqk scheduler dump, zqk scheduler escalate, zqk scheduler test-failures
Scheduler Subsystem Operational & Architectural Guide Embedded job queue, CAP loop orchestrator, transient retry membranes, atomic job state registry, retention cleanup, and watchdog monitoring. Kernel Engineers & Agents pkg/scheduler, zqk scheduler
Shell Command Parsing, Metacharacter Inspection & Cross-Platform Execution Subsystem Architectural & Operational Guide Subsystem architecture, command tokenization, metacharacter inspection, cross-platform POSIX/Windows shell delegation, fail-closed empty argv handling, concurrency guarantees, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/shellcmd
Process Execution, Group Isolation & Subprocess Management Subsystem Architectural & Operational Guide Subsystem architecture, hardened process lifecycle management, process group isolation, timeout enforcement, stream buffering, transient ETXTBSY exponential backoff retry, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/execwrap
OS Service Management & Adapter Subsystem Architectural & Operational Guide Subsystem architecture, cross-platform service supervision, launchd/systemd adapters, process lifecycle state machines, dual-path fallbacks, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/service
Circuit Breaker & Concurrency Throttling Subsystem Architectural Guide Three-state circuit breaker automaton, sliding-window failure decay, per-package semaphore concurrency limits, and token-bucket TPM rate limiting. All Engineers & Autonomous AI Agents pkg/circuitbreaker
Host Load Sampling & Adaptive Concurrency Subsystem Architectural Guide Subsystem architecture, dynamic CPU saturation telemetry, EMA low-pass filtering, three-tier pressure classification, self-heat compensation, fail-open guarantees, cross-platform sensors, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/hostload
Concurrency Primitives Subsystem Architectural & Operational Guide Synchronization primitives, deadlock prevention, TimeoutMutex invariants, adaptive GoroutineCeiling token pools, context-aware waits, named WaitGroupManager, and >=85.0% coverage invariant. All Engineers & Agents pkg/concurrency
Goroutine Identity & Concurrency Labels Subsystem Operational Architecture Guide Subsystem architecture, named goroutines and runtime categorization, bounded worker pool lifecycle, CPU/concurrency budget tracking, panic recovery telemetry, test fixtures, and >=85.0% statement coverage invariant. Kernel Architects, Concurrency Engineers & Agents pkg/goroutinelabels
Test Package Concurrency Limits & Parallel Execution Throttling Subsystem Guide Subsystem architecture, package path normalization, on-disk policy loading, conservative multi-source limit merging, parallel runner throttling, and 100.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/testpackageconcurrency
Runtime Subsystem Architectural & Operational Guide Centralized supervision tree, goroutine lifecycle governance, leak detection heuristics, graceful drain coordination, and >=85.0% coverage invariant. All Engineers & Agents pkg/runtime
Branding & Identity Subsystem Architectural & Operational Guide Subsystem architecture, dynamic brand discovery, channel suffix stripping, environment variable prefix resolution, role differentiators, multi-tenant isolation, and >=85.0% statement coverage invariant. All Engineers & Agents pkg/brand
Pipeline Execution Subsystem Operational & Architectural Guide Multi-stage pipeline composition, DAG execution engine, pipeline router, context hydration, token budget enforcement, graph ownership, native swarm dispatchers, and >=85.0% coverage invariant. All Engineers & Autonomous AI Agents pkg/pipeline, zqk agent orchestrate, zqk do
Local CI Engine, Worktree Isolation & Git Fast-Forward Subsystem Operational Architecture Guide Subsystem architecture, pure Go CI checkout, fail-closed dirty studio verification, detached worktree isolation, atomic symlink workdir swinging, cryptographic tarball archiving, and 98.3% statement coverage. All Engineers & Autonomous AI Agents pkg/localci, zqk local-ci
Event Coordination Subsystem Architectural & Operational Guide Subsystem architecture, central event spinal cord, TRIGGER stage pipelines, multi-channel routing (logging, audit, metrics, operational), subscriber topologies, progress reporting, CLI notifier adapters, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/coordination
Feature Flags, Dynamic Toggles & Runtime Organism Subsystem Architectural & Operational Guide Subsystem architecture, dynamic runtime feature toggles, progressive rollout switches, thread-safe synchronization, stamp memoization caching, defaults initialization, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/featureflags

4. Multi-Agent Swarm Collaboration

Guide Focus Area Target Audience Primary CLI & MCP Commands
Atomic Work Claiming & Session Checkin Subsystem Guide Subsystem architecture, CAS lock acquisition, heartbeat renewal, write lock gate evaluation, write queue serialization, provenance tracking, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/agentclaim, zqk agent claim, zqk agent release
Agent Feed & Peer Mesh Subsystem Architecture Guide Core agent feed event ledger, peer seat liveness tracking, asynchronous await wakes, in-flight steering, deterministic COMMS-CHECK protocols, and >=85.0% coverage invariant. All Engineers & Autonomous AI Agents pkg/agentfeed, zqk feed, zqk agent seat-worker
Agent Idle Detection & Resource Conservation Subsystem Guide Subsystem architecture, FileStore accumulator, StoreDocument schema (2.0.0), CVS snapshot telemetry, in-memory caching, atomic temp rename, and >=85.0% statement coverage invariant. Swarm Engineers & Autonomous AI Agents pkg/agentidle
Core Orchestration Subsystem Architectural & Operational Guide Multi-agent convergence sessions, SubagentRunner with sentinel rollbacks, ephemeral worktree pool and sweeper, IdleWatchdog, PredictiveSpawner heuristics, PolicyNegotiator schema reconciliation, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/orchestration, zqk agent orchestrate, zqk do
CLI Agent Subsystem Architectural & Operational Guide Subsystem command taxonomy, context-bound prompt generation, atomic work claim gates, AST verification, and multi-agent coordination mesh with >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents zqk agent orchestrate, zqk agent claim, zqk agent prepare-context, zqk agent deliver, zqk agent seat-worker, zqk agent recover, zqk agent status
Multi-Agent Swarm Orchestration & Mesh Collaboration Agent seating, append-only agent feeds, conflict-free single-claimant work leases, and ambient signal interpretation rubrics. Swarm Engineers, Multi-Agent Setups zqk system agent-onboard, zqk agent feed, zqk agent claim-work
CLI Agent Feed Subsystem Architectural & Operational Guide Subsystem command taxonomy, agent coordination mesh, heartbeat mechanisms, proof-of-life leases, interrupt handling, streaming JSON lines, and >=85.0% statement coverage invariant. Swarm Engineers, Multi-Agent Setups zqk feed ack, zqk feed steer, zqk feed emit-status, zqk feed watch, zqk feed wake, zqk feed serve, zqk feed pending, zqk feed proof-of-life, zqk feed doctor, zqk feed bridge-ingest
Multi-Transport Agent Delivery & Protocol Adapters Subsystem Guide Subsystem architecture, DeliveryRouter, HTTP/MCP transports, in-process subagent invocation, trust-domain envelope enforcement, delivery audit logging, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/agentdelivery, zqk agent deliver
Task Decision Envelope & Ingestion Subsystem Operational Architecture Guide Subsystem architecture, Task Decision Envelope (TDE) schema contracts, robust ingestion parsing, status state machine, zero shared-memory mutation invariants, and 100.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/envelope
Agent Onboarding & Environment Seeding Subsystem Guide Subsystem architecture, first contact detection, universal AGENTS.md directives, vendor rule projection, skill hydration, headless execution vector B, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/agentonboard, zqk system agent-onboard
Agent Prompt Engineering & Dynamic Context Assembly Subsystem Guide Subsystem architecture, dynamic prompt builder pipeline, envelope hydration, policy and skill injection, token budget compaction, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/agentprompt, zqk agent prepare-context, zqk do
Skill Drift Audit, Integrity Sealing & Evolution Tracking Subsystem Guide Subsystem architecture, dual-directory drift detection, SHA-256 cryptographic sealing, frontmatter tamper detection, evolutionary lineage tracking, and 100.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/skill
CLI MCP-Simple Subsystem Architectural Guide Minimal footprint Model Context Protocol (MCP) server, stdio & mTLS transports, diagnostic tools, and isolated client execution. AI Agents, Swarm Integrators zqk mcp-simple, zqk mcp-simple -mtls-addr
Model Context Protocol (MCP) Subsystem & Tool Execution Architecture Guide Subsystem architecture, JSON-RPC 2.0 protocol lifecycle, in-process CLI bridge, role-based tool catalog, path traversal guards, session leases, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/mcp, zqk mcp
MCP Auto-Configuration & Host Integration Guide Single-command auto-configuration (zqk mcp install, zqk mcp ensure), multi-host IDE discovery (Cursor, Claude Code, Cline, Windsurf), stdio and TCP proxy architectures, and manual configuration recipes. All Engineers & Autonomous AI Agents zqk mcp install, zqk mcp ensure, zqk mcp proxy
Cellular Specialization & Organism Roles Subsystem Architectural & Operational Guide Subsystem architecture, biological organ tiers (Neuron, Muscle, Heart, Lung, All), normal vs shielded (Rubber Room) modes, PCS vitality telemetry, and >=85.0% statement coverage invariant. Kernel Architects, Swarm Engineers & Autonomous AI Agents pkg/specialization, zqk scheduler daemon, zqk system status
Semantic Model, Tool & Gradient Routing Subsystem Operational Architecture Guide Subsystem architecture, model gradient dispatch, tool scope isolation, adaptive timeout envelopes, model tier classification, telemetry counters, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/router
Swarm Initialization & Mesh Recipe Pipeline Runner Subsystem Operational Architecture Guide Subsystem architecture, mesh recipe parsing, step executors, runner orchestration, registry lookup, recipe failure modes, conversation wiring errors, timeout handling, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/swarminit, zqk swarminit run
Swarm Execution Engine & Multi-Agent Orchestration Subsystem Operational Architecture Guide Subsystem architecture, deterministic cognitive loop lifecycle, task scheduling, tool guarding, MCP client integration, token tracking, prompt synthesis, error recovery, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/swarm, zqk do, zqk agent orchestrate
Mesh Networking, State Sync & ToolPod Subsystem Operational Architecture Guide Subsystem architecture, UDP gossip protocol, cryptographic trust verification, dynamic ToolPod coordination, async priority queue dispatch, backpressure flow control, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/mesh
Token Broker, Agent Resource Marketplace & Economic Exchange Subsystem Guide Subsystem architecture, EconomicBroker credit enforcement, AgentMarketplace skill broadcasting and leasing, quota rate limits, balance updates, and 100.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/economy

5. Diagnostics, Self-Healing & Telemetry

Guide Focus Area Target Audience Primary CLI & MCP Commands
Diagnostics, Auto-Remedies & Self-Healing 4-layer health checks, automated resolution of stale locks and orphaned temp buffers, and CAS quarantine recovery. SREs, Operators, CI/CD zqk system check --auto-remedy, zqk system doctor
CLI System Subsystem & Health Operations Guide Multi-layer validation, automated remediation engine, strategic alignment scoring, and service lifecycle management. SREs, Operators, Swarm Engineers zqk system check, zqk system align, zqk system status
CLI Visual Studio & Interactive TUI Subsystem Operational Architecture Guide Interactive full-screen terminal mission control, headless model projection, embedded Web Visual Studio, port auto-scanning, and >=85.0% coverage invariant. All Engineers & Agents zqk ui, zqk dashboard, zqk console
Web Studio & Visual Graph Explorer Operational Architecture Guide Embedded local web server (zqk ui -w), HTTP/WebSocket endpoints, real-time DAG streaming, Gantt matrix visualization, and headless CI export. All Engineers & Autonomous AI Agents zqk ui -w, zqk ui --web, pkg/studio
TUI Engine & Terminal Interface Subsystem Architectural & Operational Guide High-performance terminal UI engine, Elm architecture in Go (Model-Update-View), TDS styling invariants, headless fallback, and >=85.0% coverage invariant. All Engineers & Agents pkg/tui, zqk ui
Screen Capture & Window Automation Subsystem Architectural & Operational Guide Subsystem architecture, TerminalAutomator session orchestration, native window & region capture, cross-platform adapters, timeline tracing, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/screencap
Desktop System Tray, Menu Schema Validation & Action Security Subsystem Guide Subsystem architecture, native desktop tray integration, menu schema validation, cryptographic action security membrane, stamp memoization, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/tray, zqk tray
CLI Utility Subsystem Architectural Guide Subsystem command taxonomy, scenario synthesis, hash fix, registration repair, YAML validation, migration engine, config file watcher, and >=85.0% coverage invariant. All Engineers & Agents zqk utility, zqk utility fix-hashes, zqk utility fix-registration, zqk utility validate-yaml, zqk utility scenario-builder, zqk utility migrate
Stale Lock Health & Cleanup Subsystem Architectural & Operational Guide Subsystem architecture, fail-closed directory discovery, stale lock sweep heuristics, owner-verified removal, advisory flock probing, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/lockhealth
Disk Usage & Storage Capacity Telemetry Subsystem Architectural Guide Subsystem architecture, pure-Go filesystem tree traversal, size rollups, binary byte formatting, capacity telemetry, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/diskusage, zqk system disk-usage
Config-Driven Cleanup & Maintenance Subsystem Architectural & Operational Guide Subsystem architecture, single-track YAML cleanup configuration, polymorphic step unmarshaling, stamp memoization caching, scheduled task pruning, safe deletion safeguards, and 100.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/cleanup, zqk scheduler submit --job-type cleanup
I/O Resource Hygiene, File Descriptor Leak Detection & Storage Telemetry Subsystem Architectural & Operational Guide Subsystem architecture, resource reaper, file descriptor tracking, orphaned temp file cleanup, stale lock purging, storage telemetry inspection, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/resourcehygiene
System Modularity Inspection & Codebase Peeling Subsystem Operational Architecture Guide Subsystem architecture, codebase structural inspection, dynamic command peeling, LOC metrics engine, threshold sentinels, thread-safe component registry, and 100.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/systempeel
Sovereign Relay Tunnel & Inbound Webhook Bridge Subsystem Architectural & Operational Guide Subsystem architecture, persistent outbound TLS/WSS tunnels, Ed25519 JWT verification, inbound webhook ingress routing, token bucket rate limiting, TTL buffer queues, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/relay
Release Gate, Multi-Platform Compilation & Public Payload Verification Subsystem Architectural & Operational Guide Subsystem architecture, hermetic cross-compilation matrix, SHA-256 manifest verification, archive stream inspection, path traversal sentinels, secret quarantine, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/releasegate
Diagnostic Reports & System Vitality Telemetry Subsystem Architectural & Operational Guide Subsystem architecture, lifecycle maturation metrics, system vitality health scores, QA test telemetry, cross-system summaries, MCP tool integration, and 100.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/reports, report_maturation, report_vitality, report_qa_success
Diagnostic Capture, Stagnation Detection & Runtime Profile Subsystem Architectural & Operational Guide Subsystem architecture, failure envelope schema, deterministic cryptographic signatures, loop stagnation detection, progressive disambiguation, SIGUSR1/SIGUSR2 signal profiling, embedded pprof server, and >=85.0% statement coverage invariant. SREs, Kernel Architects & Autonomous AI Agents pkg/diagnostics
Process Supervision, Engine Registry & Metrics Extractor Subsystem Architectural & Operational Guide Subsystem architecture, failure diagnostic extraction, contrastive retry prompt formatting, negative hypothesis pruning, canonical exemplar registry, and 100.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/supervision
Supply Chain Integrity, SBOM Generation & Secret Scanning Subsystem Architectural & Operational Guide Subsystem architecture, OpenVEX attestation validation, SHA-256 manifest verification, secret pattern scanning, fail-closed release gates, and 100.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/supply, scripts/open-core, scripts/scan-secrets.sh
System Check Wake, Threshold Evaluation & Seat Notification Subsystem Operational Architecture Guide Subsystem architecture, threshold evaluation engine, primary seat resolution, agent feed wake dispatch, Proof of Life toasts, and 100.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/systemcheckwake, zqk system check --notify
System Auto-Remedy, Anomaly Healing & Remediation Engine Subsystem Operational Architecture Guide Subsystem architecture, DiagnosticsRemedyEngine, stale lock/temp remediation, precondition seeding, boundary guards, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/system, zqk system check --auto-fix
Telemetry Pipeline, Metric Export & Observability Subsystem Architectural & Operational Guide Subsystem architecture, telemetry intake, anonymization pipeline, drift detection, memory cap RSS protection, hook propagation, throughput aggregation, daemon lifecycle, and >=85.0% statement coverage invariant. SREs, Kernel Architects & Autonomous AI Agents pkg/telemetry
Distributed Tracing, Requirement-to-Backlog Binding & Span Correlation Subsystem Operational Architecture Guide Subsystem architecture, requirement-to-backlog binding, active lifecycle evaluation, orphan parking with no_covering_bli, stateless concurrency safety, and 100.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/tracing
Workstream Observability, Metric Sets & Heuristic Snapshot Subsystem Operational Architecture Guide Subsystem architecture, point-in-time metric snapshots, tagged metric sets, multi-type heuristic bounds checking, snapshot isolation, workspace thresholds, and 100.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/wsobs
Context Events Pipeline, Wire Event Serialization & JSON Codec Multiplexing Subsystem Operational Architecture Guide Subsystem architecture, append-only context_events.jsonl pipeline, wire protocol specification, JSON codec multiplexing, backwards-compatible schema fallbacks, 64KB payload bounds, and 100.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/contextevents, zqk system emit-context-event
Logging & Structured Event Dispatch Subsystem Operational Architecture Guide Subsystem architecture, context-aware event routing, MCP protocol stream protection, zero-allocation fluent builder pooling, shared background flush loop, size-based rolling, and >=85.0% statement coverage invariant. All Engineers & Autonomous AI Agents pkg/logging

Human Engineer Onboarding Path:
[Community First-Run] ──► [Object Lifecycle Guide] ──► [Mission Control Visual Guide] ──► [Policy Studio Guide]
      (docs/onboarding)            (docs/guides)                 (docs/manual)                 (docs/guides)

Autonomous AI Agent Onboarding Path:
[Agent Boot Protocol] ──► [Agent Onboarding Guide] ──► [ZQL & ZPARQL Guide] ──► [Single-Command Execution Loop]
     (AGENTS.md)                  (docs/onboarding)             (docs/guides)                  (docs/guides)