ZQK Knowledge Kernel Architecture Index

Welcome to the architectural specifications and design documents for the ZQK Knowledge Operating System (KOS). This index categorizes all core design documents, invariants, threat models, and subsystem specifications.

1. Storage & Membrane Architecture

Documents governing Content-Addressable Storage (CAS), append-only WAL streams, memory isolation, and privileged filesystem access.

Cellular Membrane Mode B Configuration: Mode A (developer standalone) vs Mode B (cellular membrane lockdown with isolated PrivilegedWriterDaemon and UNIX domain socket IPC).
Cellular Specialization Tiers & Rubber Room: Biological organ specialization tiers (Neuron, Muscle, Heart, Lung) and sandboxed side-effect execution in the Rubber Room (ModeShielded / ShadowSpine).
Tiered Storage and Archival Lifecycle: Three-tier storage hierarchy: hot active CAS, warm index layers, and cold compressed stream archives.
Storage Write Queue & Observer Governance: Non-blocking asynchronous event queues, observer fan-out, and memory hygiene.
Project-Scoped Reverse Reference Index: Caching and reverse referencing mechanisms.

2. Mutation & Data Integrity Governance

Documents governing state transitions, provenance enforcement, and fail-closed validation.

Membrane Mutation Governance & Integrity Specification: System provenance fields (created_at, cas_address, hash), directed state graph transitions, audited --override elevation, and interactive TTY friction controls.
Lifecycle State Machine Architecture: Formal lifecycle definitions, state transitions, and precondition verification engines.
Fail-Closed Error Propagation: Core error handling and propagation strategy.
Fail-Closed Error Propagation & Transaction Resilience: Fail-closed boundary guarantees across storage, networking, and validation boundaries.
Fail-Closed Panic Resilience: Subprocess and thread isolation preventing daemon crashes and unhandled panic propagation.

3. CLI Command Taxonomy & Ergonomics

Documents governing the Cobra CLI command surface, taxonomy standards, builders, and verb mappings.

CLI Command Taxonomy Standards: Canonical noun-verb command standards, grammar rules, YAML specification inventory, and regression guardrails.
Orphan Verbs Retirement & Canonical Domain Mapping: Ergonomic root shortcuts (zqk do, zqk inspect, zqk mutate) mapped to canonical domain commands (zqk workflow do, zqk object inspect, etc.).
Acronym Vocabulary Scheme & Progressive Disclosure: Glossary scheme for technical acronyms (CAS, VDS, DoD, BLI, REQ, CRIT) and cognitive load management.
Diagnostics Auto Remedy: Ergonomic flows for diagnosing and fixing issues.
Worktree Kernel Resolution: Resolving kernel locations within git worktrees.
ZQK Do Autonomous Execution: Guidelines for the zqk do capability.

4. Daemons, Schedulers & Concurrency

Documents governing persistent host processes, background watchers, and job concurrency.

Daemon Singleton Mutual Exclusion: Cross-platform PID lock acquisition, single-instance enforcement, and automatic recovery of dead daemon leases.
Seat Worker Supervisor Architecture: OS-level supervisor daemons (launchd on macOS, systemd on Linux) managing persistent 24/7 background agent seats.
Ambient Signal Action Rubric: Ambient filesystem watcher events, heuristics evaluation, and proactive maintenance signals.
Async Check Discovery Decoupling: Decoupling disk discovery from validation pipelines to prevent CLI timeout stalls.
Service Adapter Specification: Unified abstraction across macOS launchd, Linux systemd, and standalone foreground runners.

5. Swarms, Orchestration & Extensibility

Documents governing multi-agent coordination, bounded domain packages, and extensible modules.

Pack Composition & Extensibility Architecture: Architectural distinction between Go Code Packs (packs/<domain>) and Runtime Swarm Orchestration Packs (swarm.yaml), and composition rules.
Composite Execution Organizer Verification: End-to-end trace pipelines, deterministic goal hierarchy composition, and verification gates.
Adaptive Task Supervision Specification: Multi-agent supervisor coordination, heartbeat monitoring, and automated unsticking protocols.
Adaptive Agent Disambiguation: Persona resolution, skill linkage, and intent disambiguation for agent execution seats.
Orchestration Runtime Taxonomy: Classification of swarm coordinators, seat workers, and task queues.
Package Consolidation Governance: Package boundary hygiene, circular import prevention, and internal vs public API separation.
SpecBuilder CodeGen & Enum Consolidation: SpecBuilder code generation, AST pruning, and domain enum aggregation.
Synthetic Constant Eradication Governance: Elimination of stringly-typed magic constants in favor of canonical spec-derived constants.

6. Security, Sovereign Execution & Cryptography

Documents governing cryptographic provenance, keys, sovereign local execution, and execution isolation.

Sovereign Air-Gapped AI Engineering: Offline execution with local LLMs (Ollama / Apple Silicon), local CAS persistence, and deterministic AST verification.
Keystore Security & Fallback Specification: Ed25519 signing keys, fail-closed key discovery, and environment variable resolution.
Tray Command Cryptographic Security: Authenticated RPC protocol between background daemons and desktop tray applications.