ZQK Core Architecture

ZQK Core is the foundational system kernel for sovereign human-agent software engineering. It provides an offline-first, mathematically auditable operating system designed to orchestrate autonomous AI agents alongside human developers.

Architectural Foundations

The architecture is built on four core pillars:

Knowledge Kernel & Graph System of Record: - Process states, roadmaps, workstreams, requirements, acceptance criteria, and backlog items are represented as first-class, semantically typed system objects. - Objects maintain explicit cryptographic integrity and lineage tracking via Content-Addressable Storage (CAS).
The Cellular Membrane: - Enforces isolation between autonomous agent operations and persistent system state. - Mutations pass through the Semantic Intake Reasoner (zqk intake / zqk object create) to guarantee schema validation and prevent unauthorized state drift.
Deterministic Scheduler & Task DAG: - High-performance, concurrent scheduler daemon (zqk scheduler) manages background loops, maintenance tasks, and automated test-bundle sweeps. - Fail-closed execution semantics ensure tasks cannot silently fail or corrupt system state.
Native Agent Mesh & MCP Integration: - Implements native Model Context Protocol (MCP) server endpoints (zqk mcp) for seamless bidirectional pairing with IDE agents (Cursor, Claude Code, Cline, Windsurf). - Agent seating, role specialization, and workspace directive synchronization (zqk system agent-onboard) bridge local workspaces and kernel memory.

Architectural Specifications

Cellular Membrane Configuration: Privileged Writer barrier and UNIX domain socket intake topology.
CLI Command Taxonomy & Standards: Unified CLI taxonomy, argument validation, and automated spec verification.
Tiered Storage & Capsule Archival: 4-tier lifecycle (Hot → Warm → Cold → Abyss) and immutable Semantic Capsules.
Tray Cryptographic Security: P-256 ECDSA mutual handshake and HMAC-SHA256 authentication for privileged operations.
Polyglot AST Code Search Roadmap: In-process Tree-sitter architecture, cross-language symbol taxonomy, and token budgeting for zqk grep.

Deterministic Testing & Race Verification

Race Detection & Teardown Safety: All background test workers run with explicit lifecycle synchronization (sync.WaitGroup, channels, or goroutinelabels.Pool) rather than arbitrary sleeps.
Race Gate Verification: Native verification via zqk test run ensures test suites execute cleanly under -race without memory races or orphaned goroutine leaks.

Next Steps

First-Run Guide: Get started with installation and local configuration.
First-Run Object Tutorial: Walk through creating, inspecting, and updating kernel objects.