graph-execution

Graph-Planned Execution (Deterministic State Machine Protocol)

Provides a deterministic, graph-planned execution primitive for tasks requiring formal state tracking, non-negotiable human approval gates, isolated worktree sandboxing, and guaranteed safe rollback.

---

1. Overview: Loops vs. Graphs

While standard agent loops rely on conversational context to decide next steps, Graph Execution models tasks as a formal Directed Acyclic Graph (DAG) or finite state machine:

stateDiagram-v2
    [*] --> TRIAGE: Task / Error Trigger
    TRIAGE --> PLAN: 4-Box Automation Gate Passed
    PLAN --> AWAITING_APPROVAL: Transaction Manifest Formulated
    AWAITING_APPROVAL --> AUTHORIZED: User Explicit Approval ("Proceed")
    AUTHORIZED --> CREATE_WORKTREE: Worktree Sandbox Initialized
    CREATE_WORKTREE --> EXECUTE: Mutation Attempt (1-3)
    EXECUTE --> VERIFY_GATE: Objective Verifier Run
    VERIFY_GATE --> PRE_COMMIT_RECEIPT: Verifier Passed (exit 0)
    VERIFY_GATE --> PLAN: Verifier Failed (Attempts < 3)
    VERIFY_GATE --> ROLLBACK: Verifier Failed (Attempts == 3)
    PRE_COMMIT_RECEIPT --> COMMIT: Staged Tree Validated & Committed
    ROLLBACK --> FINAL_RECEIPT: Layer 2 Transferred & Worktree Removed
    COMMIT --> FINAL_RECEIPT: Local Cycle Successful
    FINAL_RECEIPT --> [*]: Terminal Receipt Logged

---

2. The Core Invariants

1. State in Files, Not Prompts: The active node, attempt count, and operation bounds are stored in .agent/learning/evolution_state.json and mediated by a deterministic controller script (e.g., evolution_state.py).
2. Proposal Mode Invariant (Read-Only Planning): Prior to explicit user approval (AWAITING_APPROVAL), the agent executes zero state-changing operations, creates no git worktrees, and runs no mutations.
3. Transactional Worktree Sandboxing: Mutations are executed inside an isolated git worktree (../worktree-evolution-<cid>), keeping the main checkout 100% clean during execution.
4. Verifier Sovereignty: The agent cannot modify the test scripts, holdout sets, or evaluation criteria that judge its own work. Pre-execution hashes of verifiers are locked.
5. Asymmetric Persistence: If a task fails after maximum retry attempts (e.g., 3 attempts):
   • Code changes are safely rolled back and the worktree is deleted.
   • Failure learnings, negative constraints, and reproduction notes are permanently preserved in Layer 2 Markdown playbooks and debt logs before worktree teardown.
6. Integrity Receipts: No commit is permitted without an Evolution Integrity Receipt (EVO-INTEGRITY-<cid>-<hash>) binding the exact staged git tree to the audit event sequence.