THE REPOSITORY'S OWN DOCUMENT · OPERANT

Autonomous mode — the self-directed loop

autonomous coding mode

Repository
agentic-harness/operant/docs/library
Commit
fbe90019
Date
2026-11-01
Length
60 lines · 2 min

Read the source on GitHub This page renders that file; it is not a summary of it.

Autonomous mode — the self-directed loop

Owns: autonomous coding mode — the TODO.md ledger loop, the workspace snapshot gate, the publish path, and failure-pause state. Not for: the agent loop it drives (agent-loop.md), ESTOP (verification.md §estop), the iteration protocol agents follow (AGENTS.md).

Source: crates/operant-cli/src/autonomous.rs, launched by operant autonomous or operant run --autonomous (crates/operant-cli/src/main.rs).

The loop

run_autonomous builds an AutonomousRunner over the current repo and cycles: snapshot the workspace → pick the next task from the ledger → run an agent turn on it → publish the change → repeat. Failure at any step is recorded and the loop adapts rather than dying.

The ledger: TODO.md

The repo-root TODO.md is the task ledger, parsed into Implemented / Pending / Review sections (WorkspaceSnapshot::implemented_items / pending_items). Autonomous behavior changes must keep those sections accurate — the loop reads them as its queue.

The workspace snapshot gate

Before doing anything the runner hashes the workspace state (workspace_key = hash of todo contents + HEAD + worktree status). A task's completion is judged against the snapshot it started from, and the publish decision (below) compares what actually changed.

The publish path

PublishOutcome is Failed | Skipped(WorkspaceSnapshot) | Pushed(WorkspaceSnapshot, StatusPublishSummary). The staging scope is deliberately constrained (AD-027): the tick computes its OWN touched paths and passes them to git add -- <paths> / commit — an owner's file left dirty is never committed by a tick (regression test a_tick_does_not_commit_a_file_the_owner_left_dirty).

State across restarts

The runtime writes repo-local autonomous-status.toml state and RELOADS repeated-failure pause state across restarts — a task that failed N times before the restart is still paused after it. Keep that workflow documented when changing autonomous behavior.

Intention

Autonomous mode is the operator's delegation endpoint: the ledger is the contract (the operator seeds it, the loop consumes it), the snapshot gate is the honesty check (publish what actually changed, not what the model claims), and the pause-state persistence exists because a crash-looping task must not become a crash-looping machine after a restart. The live Pending and Review rows (derive them from TODO.md at read time — never carry a count here, RG-008) are tracked in docs/handoff/STATE.md.

Other published documents in operant

Back to the operant case study 23 of this study's documents are published on the site; the repository holds the rest.