CLI Execution & Intent Intake Guide
Comprehensive guide to semantic intent ingestion (zqk intake), autonomous execution loop (zqk do), ambient LLM synthesis, and fail-closed CAS validation membranes within the ZQK Knowledge Kernel.
1. System Overview & Ingestion Architecture
The ZQK ingestion and execution layer bridges free-form human or agent intent with strictly-typed, immutable Knowledge Kernel objects. It operates through two primary CLI command surfaces:
zqk intake: The semantic ingestion pipeline that processes raw natural language, meeting transcripts, or task specs into typed ZQK entities (requirement,goal,technical_spec,strategic_plan).zqk do: The autonomous single-command execution engine that takes intent from capture through preflight, locking, dispatch, and verification.
flowchart TD
subgraph HumanOrAgent["Human / Agent Interface"]
RawIntent["Natural Language Context / Intent"]
end
subgraph IntakeSubsystem["zqk intake Pipeline"]
LLM["Ambient Semantic Engine (LLM)"]
Parser["JSON Membrane Parser"]
Gate["Fail-Closed CAS Intake Gate (BaseObject Description Enforcement)"]
Synthesizer["IntakeMembrane (Clustering & Concurrency Topology)"]
CASStore["CAS Object Storage (Dynamic Initial Status)"]
end
subgraph ExecutionSubsystem["zqk do Subsystem"]
Orchestrator["Single-Command Execution Loop"]
Verifier["AST Verification & Gate Evaluation"]
end
RawIntent -->|CLI args or stdin| IntakeSubsystem
IntakeSubsystem --> LLM
LLM --> Parser
Parser --> Gate
Gate -->|validated| Synthesizer
Synthesizer --> CASStore
CASStore --> Orchestrator
Orchestrator --> Verifier
2. Semantic Intake Pipeline (zqk intake)
2.1 The Fail-Closed CAS Intake Gate
Every object emitted by the semantic engine must satisfy core invariants before entering storage:
- Base Object Description Gate: Every synthesized object must have a non-empty
description. Missing or whitespace-only descriptions are rejected fail-closed to prevent malformed CAS entities. - Dynamic Initial Status Resolution: Objects are not hardcoded to a single status. Instead, the intake pipeline queries the object's canonical lifecycle (
GetOriginStatus) to assign the legitimate origin status (e.g.conceptualororiginatedfor requirements and goals,plannedfor backlog items).
2.2 Intake Membrane Clustering & Concurrency Topology
When multiple intents are ingested simultaneously (len(objects) >= 2 or --cluster/--concurrency flags), the IntakeMembrane executes two analysis passes:
- Semantic Clustering: Groups related requests sharing common path targets (e.g.,
pkg/storage/wal) into coherent thematic workstreams. - Concurrency Synthesis: Identifies dependencies between clusters to propose concurrent execution batches versus sequential stages.
- Strict Anti-Chaining: Rejects redundant 1:1 micro-chains that clutter the graph.
3. Command Usage & Recipes
3.1 Basic Intent Ingestion
# Ingest single intent string via CLI arguments
zqk intake "We need a new sqlite connection and a metrics exporter"
# Ingest multiline intent or meeting notes via stdin pipe
cat architecture_notes.md | zqk intake
3.2 Clustering & Concurrency Planning
# Cluster multiple related requests into unified workstreams
zqk intake --cluster "Add WAL atomic rollback and expand storage telemetry metrics"
# Generate concurrency vs sequential execution pipelines
zqk intake --concurrency "Refactor CLI flags and upgrade test matrix"
# Combine clustering with strict anti-chain invariant checks
zqk intake --cluster --concurrency --strict-anti-chain "Implement agent claim gates and session validators"
3.3 Executing Intent via zqk do
# Execute end-to-end intent with single-command autonomy
zqk do "elevate cmd/zqk/intake test coverage to 80%"
# Dry-run execution to preview planned steps without mutations
zqk do "elevate cmd/zqk/intake test coverage to 80%" --dry-run
4. Troubleshooting & Invariant Diagnostics
| Symptom | Root Cause | Remediation |
|---|---|---|
no intent context provided |
CLI invoked without arguments and stdin was a terminal (not a pipe) | Pass text arguments or pipe input via cat ... \| zqk intake |
fail-closed CAS intake gate rejected |
LLM synthesized an object with an empty description | Ensure intent text provides sufficient detail, or clarify via prompt |
intake membrane processing failed |
Requests formed a circular dependency or redundant 1:1 micro-chain | Pass distinct task domains or run without --strict-anti-chain |
status ... not found in lifecycle |
Object was created with an incompatible lifecycle status | Dynamic lifecycle resolution (resolveInitialStatusForKind) prevents this automatically |
5. Automated Verification
Verify the intake test suite and done-gates:
# Execute intake test suite
ZQK_ALLOW_FOREGROUND_GO_TEST=1 go test -v -cover ./cmd/zqk/intake
# Run the linked kernel test case
./bin/zqk test run TST-001