CLI Object Subsystem Operational Guide
Overview
The ZQK Object Subsystem (cmd/zqk/object) provides the primary command-line interface and programmatic entrypoint for creating, inspecting, updating, traversing, and retiring knowledge graph objects within the Zen Quantum Kernel.
Unlike ephemeral chat-based programming harnesses where context, decisions, and criteria are lost across conversation turns, ZQK treats goals, requirements, criteria, test cases, and backlog items as first-class, cryptographically validated graph entities. Every object conforms to a declarative JSON/YAML schema, is stored in Content Addressable Storage (CAS), and transitions across formal lifecycle state machines.
The Object Subsystem operates as the user-facing and agentic boundary over the Knowledge Kernel data plane, enforcing schema integrity, referential invariants, and two-phase transactional isolation.
Subsystem Command Taxonomy
The zqk object command hierarchy is partitioned into distinct functional groups: core verbs, relationship traversals, batch import/export, and schema discovery:
| Command | Group | Purpose | Primary Flags & Arguments |
|---|---|---|---|
zqk object create <kind> |
Core Verbs | Mints a new kernel object from CLI data or schema file | --data <json>, --file <path>, --dry-run, --cas, --promote |
zqk object get <id> |
Core Verbs | Retrieves an object by ID with projection and overlays | --format json\|yaml\|table, --fields, --view |
zqk object list <kind> |
Core Verbs | Lists objects of a specific kind or all kinds | --filter <expr>, --sort-by <field>, --group-by <field>, --count |
zqk object update <id> |
Core Verbs | Applies granular mutations and optimistic locking | --field <k=v>, --add-ref, --remove-ref, --expected-updated-at |
zqk object delete <id> |
Core Verbs | Deletes objects with referential integrity check-valves | --unlink-references, --cascade, --dry-run, --reason-code |
zqk object promote <id> |
Core Verbs | Advances object status forward along lifecycle edges | --dry-run, --skip-hooks, --relaxed |
zqk object demote <id> |
Core Verbs | Retreats object status backward to earlier stages | None |
zqk object park <id> |
Core Verbs | Lateral sequencing exit along authorized transitions | --to deferred\|roadmap\|archived |
zqk object move <id> |
Core Verbs | Reorganizes object across kind or namespace boundary | --kind <target>, --update-references, --relaxed |
zqk object rename <old> <new> |
Core Verbs | Updates object ID and propagates reference rewrites | --update-references, --dry-run |
zqk object count <kind> |
Core Verbs | Reports count of stored instances by kind or filter | --filter <expr>, --group-by <field> |
zqk object template <kind> |
Core Verbs | Generates schema-compliant skeleton template | --format json\|yaml, --output <path> |
zqk object fields [kind] |
Discovery | Explores field metadata, traits, and registered kinds | --list-kinds, --filterable, --sortable, --groupable |
zqk object ref <add\|rm\|list> |
Graph | Manages explicit graph relationships between objects | <source_id> <target_id>, --kind <relationship> |
zqk object path <from> <to> |
Graph | Finds shortest directional path between two objects | <from_id> <to_id> |
zqk object neighbors <id> |
Graph | Queries immediate graph neighbors | --direction incoming\|outgoing\|both |
zqk object related <id> |
Graph | Discovers connected graph subtrees | --depth <int>, --relationship <type> |
zqk object bulk <op> |
Batch | Executes bulk create, update, get, or delete | create, update, get, delete, --file, --ids |
zqk object export <kind> |
Batch | Exports kernel objects to stdout or external file | -o <path>, --format json\|yaml, --filter <expr> |
zqk object import |
Batch | Ingests objects from external file with deduplication | --file <path>, --mode create_only\|upsert, --dry-run |
zqk object draft <sweep\|promote> |
Shortcuts | Operates on preliminary draft plane objects | sweep, promote, --dry-run, --force |
Core Architecture
flowchart TD
CLI["CLI / Agent Subsystem (cmd/zqk/object)"]
subgraph Isolation["Two-Phase Storage Membrane"]
Draft["Draft Plane (.zqk/object_drafts/)<br/>Preliminary Objects (status: exploring / draft)"]
Authoritative["Authoritative CAS (.zqk/process/)<br/>Content Addressable Storage (SHA-256)"]
end
subgraph LifecycleEngine["Lifecycle State Machine"]
SM["Validator & Transition Evaluator"]
L0["Exploring"] --> L1["Planned"] --> L2["In Progress"] --> L3["Complete"]
L0 -. Lateral .-> L4["Deferred / Roadmap / Archived"]
end
subgraph GraphValidation["Relational Integrity Layer"]
Invariants["Acyclic DAG & Reference Checks"]
ThreeFold["Three-Fold Proof Invariant"]
end
CLI -->|Minting Preliminary| Draft
CLI -->|Mints Direct / Promotes| SM
SM -->|Promoted Objects| Authoritative
CLI -->|Traversals & Projections| GraphValidation
GraphValidation <--> Authoritative
1. Two-Phase Transactional Plane Isolation
To prevent unvetted, work-in-progress, or half-specified ideas from contaminating authoritative system state, ZQK enforces strict transactional plane isolation:
-
The Draft Plane (
.zqk/object_drafts): - Objects minted in preliminary lifecycle statuses (exploring,draft) initially reside in the isolated draft plane. - Draft objects are visible for interactive authoring and refinement, but are ignored by execution schedulers, gate verifiers, and production scoreboards. - Batch cleanup and promotion are mediated viazqk object draft sweepandzqk object draft promote. -
The Authoritative CAS Plane (
.zqk/process): - Shovel-ready and active objects reside in Content Addressable Storage. - Content is indexed by canonical IDs and cryptographically fingerprinted with SHA-256 digests. - Direct mutations to authoritative objects trigger Write-Ahead Log (WAL) recording and synchronous index updates.
2. Content Addressable Storage (CAS) Membrane
Authoritative storage is organized by ontological kind directories under .zqk/process/ (e.g., goals/, requirements/, criteria/, backlog/, priority_plans/).
- Atomic File Writing: All updates are written to temporary staging files on the same filesystem and atomically moved into position using POSIX
rename(2). - Deduplication & Immutability: Objects carry immutable provenance headers (
id,kind,created_at,created_by,schema_version) that are locked against tampering. - Optimistic Concurrency Control: The CLI supports
--expected-updated-atflags to guarantee that parallel agent workers never overwrite concurrent updates without detection.
3. Relational Graph Validation & Referential Check-Valves
Objects in the knowledge kernel form a strongly typed, directed property graph. The Object Subsystem enforces referential integrity at every mutation point:
- Ghost Reference Prevention: Objects cannot be deleted if inbound references exist, unless
--unlink-references(which strips inbound pointers atomically) or--cascadeis explicitly provided. - Core Kernel Object Break-Glass Guard: Hard-deleting core entities (
goal,requirement,criteria,priority_plan) requires a deliberate justification via--reason-codecontaining at least 30 characters, preventing accidental erasure of organizational memory. - The Three-Fold Proof: Requirements must declare at least 3 criteria satisfying: 1. Static Floor Invariant: Architectural and schema floor constraints. 2. Operational Dynamic Proof: Executable unit, functional, or integration test assertion. 3. Negative Adversarial Boundary: Error handling, fuzzing, or boundary rejection check.
Operational Recipes & Command Examples
1. Scaffolding and Minting Shovel-Ready Objects
# Generate a template for a backlog item
zqk object template backlog_item --format yaml > /tmp/item.yaml
# Mint an object directly via inline JSON data
zqk object create backlog_item --data '{
"id": "BLI-001",
"title": "Implement Resilient Cache Invalidation",
"description": "Ensure CAS cache entries are evicted deterministically on object mutation.",
"problem_statement": "Stale CAS indexes cause transient read misses during rapid multi-agent updates.",
"acceptance_considerations": "Zero stale read anomalies observed during swarm stress runs.",
"priority": "high",
"priority_tier": "P1"
}'
# Validate object creation without persisting (Dry-Run)
zqk object create backlog_item --file /tmp/item.yaml --dry-run
2. Lifecycle State Progression (Promote, Demote, Park)
# Advance object status forward through the lifecycle state machine
zqk object promote BLI-001
# Move object to deferred or roadmap status along valid lateral transitions
zqk object park BLI-001 --to deferred
# Retreat object status backward if prerequisites were prematurely declared
zqk object demote BLI-001
3. Relationship Traversal & Graph Inspection
# Find directional dependency path between requirement and parent goal
zqk object path REQ-001 GOAL-001
# Inspect immediate inbound and outbound neighbors
zqk object neighbors REQ-001 --direction both
# Traverse related graph objects to depth 2
zqk object related REQ-001 --depth 2
# Link two objects with a typed relationship
zqk object ref add BLI-001 REQ-001
4. Bulk Operations & Migrations
# Batch retrieve multiple objects with JSON formatting
zqk object bulk get --ids BLI-001,BLI-002,BLI-003 --format json
# Export a collection of objects matching a filter
zqk object export backlog_item --filter "status=planned" -o /tmp/planned_blis.yaml
# Ingest and validate external items without mutating storage
zqk object import --file /tmp/planned_blis.yaml --dry-run
# Execute atomic bulk delete with automatic reference unlinking
zqk object bulk delete --ids BLI-001,BLI-002 --unlink-references
Verification & Statement Coverage Invariant
As part of core quality governance, the Object Subsystem CLI implementation (cmd/zqk/object) enforces a statement test coverage invariant of \(\ge 80.0\%\).
Unit and integration test suites for this package are implemented in:
cmd/zqk/object/object_coverage_elevation_cycle121_test.gocmd/zqk/object/object_inprocess_comprehensive_test.gocmd/zqk/object/object_coverage_elevation_test.go
Test Suite Execution Guidelines
To prevent long-running integration suites from triggering process timeouts during CI/CD or local agent runs, always execute targeted test runs with explicit package bounds:
# Execute focused test suite
ZQK_ALLOW_FOREGROUND_GO_TEST=1 go test -v -timeout 30s ./cmd/zqk/object -run 'TestCycle121'
# Measure statement coverage
ZQK_ALLOW_FOREGROUND_GO_TEST=1 go test -timeout 30s -coverprofile=coverage.out ./cmd/zqk/object -run 'TestCycle121'
go tool cover -func=coverage.out
All test cases adhere to the following invariants:
- Strict Bounded Execution: Every test completes within allocated micro-benchmarks (\(\le 15\text{s}\) package ceiling).
- Environment Isolation: Tests create temporary projects via
testkit.PrepareIsolatedTempProjectand clean up storage handles upon completion. - Zero Swallowed Errors: Error returns are asserted with
require.NoError,assert.NoError, orassert.Error. - AST Size Ceilings: Test functions are partitioned into modular helper functions \(\le 100\) lines.