assent — plan with AI, run unattended, approve as a human

Traditional Chinese

Assent turns an agreed AI plan into isolated, repeatable work. You first confirm requirements with an AI, then ask it to turn the agreed consensus into an Assent-format plan. Let assent run execute and verify the work, then review the evidence before explicitly accepting it.

The source remains ordinary Git. Assent keeps its plans and runtime evidence in the project's ignored .assent/ directory.

The workflow

DONE means the execution AI believes a task is finished. A passing receipt means the reconstructed result passed complete verification. Neither is human approval: only assent accept publishes the work.

Install

Assent requires Python 3.11+, Git, and an installed and authenticated supported AI CLI such as Claude or Codex. It uses only the Python standard library.

python -m pip install assent

To uninstall:

python -m pip uninstall assent

Uninstalling removes the package and CLI only. It does not delete ~/.assent, project .assent/ directories, worktrees, archives, or Git branches. Cleanup remains an explicit choice.

Quick start

Run these commands from an existing Git project:

assent init --test unittest

# First confirm requirements with the AI. After agreement, ask it to turn the
# consensus into an Assent-format plan under .assent/<PLAN>/.
assent check

# Try one task, then finish the plan unattended.
assent run --once
assent run

# Review before making the human decision.
assent report <PLAN>
assent accept <PLAN>

# Remove redundant worktrees or retire completed plan records when wanted.
assent clean <PLAN>
assent archive --all

assent init installs shared settings and three AI contracts under ~/.assent/, creates the project skeleton, and asks which full verifier the project uses. Review ~/.assent/assent.toml, AGENTS.md, and .assent/verify.py before the first run.

What happens during run

The configured [workflow] has three layers:

• task works on one task and uses focused_test as its mechanical gate;
• plan runs a focused_sweep over the completed plan and reviews cumulative behavior only after all tasks are done or skipped; and
• integration reconstructs the exact selected result and runs full_verify.

A passing action completes its layer immediately. A failure may open the next configured reviewer/fixer, whose repair is checked by the following action. The arrays are the complete repair budget: Assent never invents extra rounds. If automation cannot decide safely, it preserves all work and reports REVIEW UNRESOLVED, HUMAN DECISION for the acceptance meeting.

A task that reports BLOCKED remains in the task layer. Its task reviewer may repair a small planning omission, such as one missing scope path, in the same session. It does not spend the plan review budget. Plan review has a different job: checking whether the cumulative implementation matches the agreed plan.

Integration keeps the exact selected plans. On a Git conflict it repairs the conflict through a managed reconcile worktree, then rebuilds and verifies the same selection. It never quietly drops a plan, accepts a passing prefix, or calls accept.

Documentation

• Workflow: planning, unattended execution, and acceptance review.
• Commands: selection rules and command guide.
• Configuration: initialization, adapters, models, and workflow settings.
• Verification: focused/full checks, receipts, conflicts, and shared ignored inputs.
• Operations: worktrees, recovery, cleanup, and archive.

English documentation is canonical. Matching Traditional Chinese guides are provided for readers. The installed AI contracts are deliberately separate from these human guides: instructions.md gives session rules, format.md defines plan files, and workflow.md defines scheduler and acceptance behavior.

Safety boundaries

• Assent preserves failed and interrupted work instead of reverting it.
• Scope and ownership checks fail closed.
• Complete verification uses a temporary integration candidate and changes no target ref.
• Cleanup never traverses a junction or directory symlink target.
• A worktree isolates and records changes; it is not a security sandbox.
• reject is destructive and asks for confirmation; use rework when code should remain in place.
• Verification never implies acceptance. The final decision remains human.