CLI Workflow Execution & Autonomous Progression Engine Guide
Executive Summary
The ZQK CLI Workflow subsystem (zqk workflow) coordinates autonomous progression, deterministic task selection, prescriptive lifecycle execution, and verifiable decomposition across the Knowledge Kernel.
- Autonomous Progression Engine (
zqk workflow whats-next | next): Computes the deterministic next strategic and tactical actions for agents and swarms using sub-5ms materialized view caching, seated persona heuristics, hunger cues, and convergence session context. - 5-Layer Relational Cascade (
zqk workflow add | link | gen-trace-pipeline): Enforces ontological graph integrity and unbroken traceability from high-level intent down to atomic backlog items and automated test suites. - Verifiable Decomposition Spine (
zqk workflow vds init | checklist | evaluate | project): Enforces POL-WORKFLOW-VDS gate contracts across intent capture, design, implementation, and verification stages with executable machine predicates and independent verification. - Workflow Adherence & Gatekeeper (
zqk workflow check | coach): Evaluates git repository hygiene, branch naming adherence, priority plan alignment, and dynamically surfaces context-aware observer coaching tips.
1. System Architecture & Topology
flowchart TD
subgraph CLIControlPlane["CLI Workflow Control Plane (cmd/zqk/workflow)"]
CmdWhatsNext["zqk workflow whats-next"]
CmdNext["zqk workflow next"]
CmdCheck["zqk workflow check"]
CmdVDS["zqk workflow vds"]
CmdAdd["zqk workflow add"]
CmdCoach["zqk workflow coach"]
CmdLink["zqk workflow link"]
CmdGenTrace["zqk workflow gen-trace-pipeline"]
end
subgraph ProgressionEngine["Autonomous Progression Engine (pkg/workflow/whatsnext)"]
MaterializedView["Zero-Cost Materialized View (.zqk/cache/whats_next.json)"]
PlanSelector["Priority Plan Selection Heuristics & Seated Persona Match"]
DriveCompiler["Stratplan Drive & Swarm Hunger State Accumulator"]
CorrespondenceEngine["Agent Feed & Correspondence Mesh (Inbox/Outbox)"]
end
subgraph RelationalKernel["5-Layer Ontological Cascade (pkg/objects, pkg/storage)"]
VisionGoal["Vision & Goals (Strategic Compass)"]
PriorityPlan["Priority Plans (Time-Bounded Execution Cycles)"]
Requirement["Requirements & Criteria (Timeless Feature Contracts)"]
BacklogItem["Backlog Items (Atomic Units of Effort)"]
TestCase["Test Cases & Verification Evidence"]
end
subgraph VDSSpine["Verifiable Decomposition Spine (VDS) Engine"]
VDSChunks["docs/quality/vds_chunks.yaml"]
DSLPredicates["DSL Machine Predicates (path_exists, regex, etc.)"]
StageGates["Stage Gate Evaluations (intent_capture -> design -> impl)"]
VendorExporters["IDE & Vendor Rule Exporters (.ide/rules/)"]
end
CmdWhatsNext --> MaterializedView
CmdWhatsNext --> PlanSelector
CmdNext --> DriveCompiler
CmdNext --> CorrespondenceEngine
PlanSelector --> PriorityPlan
DriveCompiler --> BacklogItem
CmdAdd --> PriorityPlan
CmdAdd --> BacklogItem
CmdLink --> Requirement
CmdGenTrace --> TestCase
CmdVDS --> VDSChunks
VDSChunks --> DSLPredicates
DSLPredicates --> StageGates
StageGates --> VendorExporters
2. The 5-Layer Relational Cascade
The Knowledge Kernel strictly distinguishes between timeless strategic contracts and time-bounded chronological execution cycles:
Layer 1: Vision / Mission ───► Timeless High-Level Purpose
│
Layer 2: Goal ───► Timeless Strategic Anchor (Decomposes into 3-5 Requirements)
│
Layer 3: Priority Plan ───► Time-Bounded Batch (1 Sprint/Kanban cycle, 2-5 BLIs)
│
Layer 4: Requirement ───► Timeless Functional Contract (Declares >=3 Criteria)
│ │
│ ├──► Test Case ───► 1:1 Unified Verification Group
│
Layer 5: Backlog Item ───► Atomic Unit of Effort (Satisfies 1-3 Criteria)
Relational Model Invariants
goal(Timeless Strategic Compass): - Must decompose into 3–5requirementcontracts (requirement.goal_refs). - Strictly NOcriteria_refsorpriority_plan_refsongoal.requirement(Timeless Whole Feature Contract): - Ownscriteria_refs. - Must declare at least 3 criteria satisfying the Three-Fold Proof:- Static Floor Invariant (e.g., schema, AST structure, types).
- Operational Dynamic Proof (e.g., execution, latency, happy path).
- Negative Adversarial Boundary (e.g., bad inputs, errors, idempotence).
- Requirements exist outside of time and MUST NOT declare
priority_plan_reforpriority_plan_refs.
test_case(Unified Verification Group): - Linked 1:1 to arequirementviarequirement_refs. - Wraps and verifies all criteria for that requirement in a single execution (zqk test run <tst_id>).priority_plan(Time-Bounded Execution Cycle): - Groups exactly 1 cycle of work (sprint/kanban batch, 2–5 BLIs) aiming toward amilestone. - Scope-locked upon enteringin_progressto guarantee completion.backlog_item(Atomic Unit of Effort): - Satisfies 1 to 3 specific criteria (criteria_refs). - Links to exactly one activepriority_plan(priority_plan_ref).
3. Deterministic Autonomous Progression (whats-next & next)
The workflow engine delivers predictable next-step orchestration for both human operators and autonomous swarms.
Hot Path & Materialized View (<5ms SLA)
zqk workflow whats-nextdefaults to querying the cached zero-cost projection generated during storage mutations.- When staleness is detected, it non-blockingly triggers re-computation while immediately serving current state with a degraded status notice.
- Passing
--sync-sweepforces an in-line synchronous graph crawl and storage re-indexing.
Priority Plan Selection Hierarchy
When resolving the active priority plan:
- Explicit Request:
--priority-plan <id>flag always takes immediate precedence. - Seated Persona Alignment: If the invoking agent has a specific persona (e.g. software engineer vs. QA auditor), plans seated for that persona with available work are prioritized.
- Execution Status Bonus:
-
in_progress(+1000 weight) -active(+500 weight) -grooming/planned(+100 weight) - Active Order Penalty: Lower active orders receive preferential precedence (
-10 * activeOrder).
Continuous Autonomous Loop Discipline
In the autonomous CAP loop, reaching a summary, merging a PR, or passing all tests is a milestone transition, not a stopping condition:
- Fast-forward local
maintoorigin/main. - Rebuild product binary & update MCP mesh (
go build -o bin/zqk ./cmd/zqk && ./bin/zqk mcp ensure). - Query
zqk workflow whats-next. - Create/checkout the next integration branch (
integration/<pri-id>). - Claim the lead BLI and proceed immediately into execution.
4. Verifiable Decomposition Spine (VDS)
The VDS engine (zqk workflow vds) guarantees that speed comes from small, honest chunks with re-runnable evidence rather than subjective narrative claims.
VDS Chunks Contract
Every verified chunk in docs/quality/vds_chunks.yaml adheres to a strict schema:
chunks:
- chunk_id: CHK-001
stage: intent_capture
claim: Core capability and functional delivery
rubric_ref: docs/rubric.md
dsl_checks:
- path_exists:cmd/zqk/workflow/whats_next.go
- git_clean:true
evidence_refs:
- BLI-001
independent_verify: yes
Stage Gates
intent_capture: Confirms durable persistence of vision, goals, and priority plans in the kernel graph.design: Confirms requirements, rubrics, and criteria decomposition before code authoring.implementation: Confirms source code mutation, AST hygiene, and unit test pass rates.verification: Executes three-fold proof test cases and VDS done-gate assertions.
5. Command Reference & Operator Runbook
| Command | Primary Use Case | Output Formats |
|---|---|---|
zqk workflow whats-next |
Identify lead priority plan, open BLIs, hunger cues, and remedies | Table (default), JSON, YAML |
zqk workflow next |
Evaluate policy-driven next action, active tasks, or unsealed items | Table, JSON |
zqk workflow check |
Validate git branch name, status cleanliness, and plan alignment | Formatted text report |
zqk workflow vds evaluate |
Verify all machine predicates and stage gates in vds_chunks.yaml |
JSON, agent-prompt |
zqk workflow vds checklist |
Inspect active stages, chunk contracts, and VDS culture | Text, JSON |
zqk workflow add <BLI-ID> [PLAN-ID] |
Associate backlog items with a priority plan and milestone | Formatted text |
zqk workflow link <OBJ-ID> <TARGET-ID> |
Link loosely attached orphan items into the criteria graph | Formatted text |
zqk workflow coach [--update-tips] |
Surface real-time observer tips and recommendations | JSON, text |
zqk workflow gen-trace-pipeline <REQ-ID> |
Scaffold missing criteria, test cases, and BLIs automatically | Formatted text |