Skip to content
Taxon Docs

Worktrees & Verification Protocol

When external coding agents write software, unconstrained edits in the main repository can introduce merge conflicts, build breaks, and contract drift. Taxon enforces sandboxed execution and human-in-the-loop verification.

The Human + Agent Verification Cycle

sequenceDiagram
    autonumber
    actor Human as Human Developer
    participant GUI as Taxon GUI
    participant FS as .taxon/ Markdown
    actor Agent as Coding Agent


    Human->>GUI: Launch Terminal in Worktree Sandbox
    GUI->>Agent: Agent picks up task in sandbox
    Agent->>FS: Updates task markdown to status: "Need to Test"
    Human->>GUI: Opens Deliverables Diff Viewer
    alt Criteria Pass
        Human->>GUI: Clicks "Approve & Merge"
        GUI->>Human: Merges branch into main repo & sets "Done"
    else Defects Found
        Human->>GUI: Clicks "Request Revision"
        GUI->>FS: Appends ## Revision Request (Attempt N)
        Agent->>FS: Reads failures and applies surgical fixes
    end

Git Worktree Sandboxes

When a task enters execution, Taxon creates an isolated Git worktree:

/mnt/Linux/Projects/my-app/              <-- Primary Working Copy (Clean)
└── .worktrees/
    └── TASK-a1b2c3-auth-flow/          <-- Worktree Sandbox (Branch: feat/TASK-a1b2c3)
        ├── node_modules/ -> (symlinked) <-- Dependency Bridging
        └── src/

Dependency Bridging

Heavy project dependencies (such as node_modules or .venv) are automatically symlinked from the primary repository into the sandbox directory. Agents can run test suites immediately without multi-minute dependency installation overhead.

Native Sandbox Launchers

From the Task Detail panel in Taxon GUI:

  • Terminal: Launches your native terminal emulator (Kitty, Alacritty, GNOME Terminal) directly in the worktree directory.
  • Code Editor: Launches VS Code or your configured $EDITOR anchored in the sandbox directory.

Deliverables Diff Viewer

When an agent finishes work and sets status: Need to Test, open the Diff Viewer:

  • Task Baseline Comparison: Calculates git diffs against the baseCommit SHA captured when work began.
  • Two-Tier Classifier:
    • Declared Deliverables: Files declared in the contract’s outputs.
    • Collateral Changes: Unannounced modified files in the repository.
  • Split & Unified View: Toggle between side-by-side split view and compact unified diffs.
  • Inline Remediation: Reviewers can edit code directly in the diff editor and press Save (⌘S) to auto-save fixes to disk without opening an external IDE.

Revision Request Protocol & Circuit Breaker

If deliverables fail verification, click Request Revision:

  1. Select Failing Criteria: Check off specific acceptance criteria that failed.
  2. Defect Categorization: Select category (Runtime Error, Logic Regression, Contract Drift, Missing Test).
  3. Structured Context: Provide observed behavior, expected behavior, and paste terminal error logs.
  4. Queue Elevation: Taxon transitions the task to status: To Do and elevates its priority to the top of the unblocked queue.