Architectural Decision Record: Continuous CAP Loop Lifecycle Governor & Zero-Idle Autonomous Progression

Document ID: ADR-0048-CAP-LOOP-LIFECYCLE-GOVERNOR
Status: Accepted
Scope: Knowledge Kernel Swarm Engine & Agent Lifecycle (pkg/community/cap_governor.go, cmd/zqk/agent/continuation_hook.go)
Domain: Multi-Agent Autonomous Progression & Lifecycle Supervision


1. Context and Problem Statement

Under the Continuous Autonomous Progression (CAP) loop, multi-agent swarms and technical program managers operate in continuous pipelining mode. However, agent runtime harnesses (e.g. Antigravity, Claude Code, Cursor Composer) naturally default to an interactive REPL model where finishing a tool turn with plain text or markdown output causes the harness to enter a waiting_for_input (idle) state.

Previous implementations relied exclusively on an ad-hoc .zqk/state/cap_loop_active marker file. When this marker was absent (such as following a cycle transition or branch hop), or when stale markers lingered indefinitely after manual interruption, the agent loop either stopped prematurely or was vulnerable to loop drift. Furthermore, synthetic polling loops (such as sleeping in bash loops or scheduling periodic cron pings) violated the strict anti-polling mandate, burning compute and tokens without advancing knowledge graph state.

A unified, fail-closed lifecycle governor is required to manage marker lifecycle, dynamically inspect execution-facing priority plans, auto-heal state markers upon plan advancement, and guarantee zero-idle execution across all supported agent harnesses.


2. Decision Drivers

  1. Zero Idleness Mandate: An active priority plan in status in_progress or active MUST NEVER transition into an unmanaged idle state.
  2. Fail-Closed State Auto-Healing: If an active priority plan is active in the Knowledge Kernel CAS, the governor must automatically heal missing .zqk/state/cap_loop_active markers.
  3. Stale Marker Quarantine: Abandoned or orphaned markers older than the stale threshold without active plans must be quarantined and cleaned up to prevent zombie continuation loops.
  4. Three-Fold Proof Invariance: Every lifecycle property must be verified via static invariant, operational dynamic proof, and negative adversarial boundary tests.

3. Architecture & Operational Topology

flowchart TD
    A[Agent Turn Completes] --> B[Harness Emits Stop Event]
    B --> C[zqk agent hook continuation / stop]
    C --> D[CAP Governor: Inspect]
    D --> E{Active Priority Plan in CAS?}
    E -- Yes --> F[Auto-Heal Marker if Missing]
    F --> G[Emit Decision: continue]
    G --> H[Harness Re-injects Preamble & Resumes Autonomous Execution]
    E -- No --> I{Marker Present on Disk?}
    I -- Yes --> J{Marker Age > 24 Hours?}
    J -- Yes --> K[Quarantine & Remove Stale Marker]
    K --> L[Emit Decision: allow]
    J -- No --> M[Emit Decision: continue / await work]
    I -- No --> N[Emit Decision: allow / idle permitted]

Core Components

  • pkg/community/cap_governor.go (CAPGovernor):
  • Activate(): Atomic write of canonical state marker containing pid, agent ID, and UTC timestamp.
  • Deactivate(): Idempotent removal of marker.
  • Inspect(): Unified evaluator that queries kernel storage for active priority plans and reconciles disk markers with CAS reality.
  • cmd/zqk/agent/continuation_hook.go:
  • Exposes the CLI entry point (zqk agent hook continuation, zqk agent hook stop).
  • Formats vendor-specific continuation responses (antigravity, cursor, generic).

4. Verification & Invariants Matrix

Category Invariant / Proof Type Verification Suite Status
Functional Acceptance Static Floor Invariant TestCAPGovernor_StaticFloorInvariant Verified (Pass)
Operational Dynamic Proof Dynamic Marker Lifecycle TestCAPGovernor_OperationalDynamicProof Verified (Pass)
Boundary & Error Recovery Negative Adversarial Boundary TestCAPGovernor_NegativeBoundaryAndErrorRecovery Verified (Pass)
Architectural Compliance Three-Fold Invariant & Spec Conformance pkg/community/cap_governor_test.go Verified (Pass)

5. Consequences & Operational Guidelines

  • No Synthetic Polling: Operators and agents must never invoke synthetic sleep timers or polling loops while waiting on CI or background builds.
  • Continuous Forward Pipelining: While background jobs run, the agent must continuously shape upcoming priority plans, audit technical debt, or author architectural documentation.