Retornatus

Agents are fast — and optimistic. They ship code, summarize what they think they did, and move on. Retornatus keeps the finish line, the proof, and the notes in .retornatus/ inside git, so the next session does not start from zero. Your coding agent still writes the code.

Without Retornatus	With Retornatus
Jumps to code and says “done”	Written finish line first; “done” needs evidence
Each chat starts from zero	.retornatus/ survives sessions and handoffs
Same ceremony for a typo and a payment flow	Depth matches the risk
The whole manual pasted every turn	One short map each turn; extra guidance only when the task needs it
Agent invents a procedure from a vague prompt	You confirm before a new procedure is saved
The agent stops when it feels finished	Optional hooks carry the open goal into the session, the edit, and the end of the turn
Lessons vanish when the tab closes	Notes (and optional rules you accept) stay in the repo

Package 1.9.1 is on PyPI.

What it is · 30 seconds · What’s new · Quick start · Presets · How it works · What you get · Hooks · Docs

See it in 30 seconds

A Change for GET /health already has a self-reported test note. That note does not count. Record the command, then verify again. Trimmed from a real run:

$ retornatus verify C-0001
C-0001/E-001 type=test_result provenance=self_reported status=UNVERIFIED
{
  "verdict": "NOT_SATISFIED",
  "rationale": "Unverified claims (self-reported execution evidence does not satisfy): C-0001/claim-done-1. Re-record with `evidence run` or pass --allow-self-reported."
}

$ retornatus evidence run -c C-0001 -t test_result -s "/health" \
    --claim C-0001/claim-done-1 -- python3 -c 'print("ok")'
Recorded C-0001/E-002
provenance=executed exit_code=0 timed_out=false
git_commit=28be3be8c93e098080c9692e32a18c263b525f0e dirty=False

$ retornatus verify C-0001
C-0001/E-002 type=test_result provenance=executed exit_code=0 status=executed
{
  "verdict": "SATISFIED",
  "rationale": "All claims have matching attributable evidence"
}

What it is

A governance harness — not an IDE, not a model, and not an agent store. The host agent still writes code. Retornatus keeps the agreement, the proof, and the memory under .retornatus/.

Demand → Situation → Contract → Action → Evidence → Assurance → Learning

You approve the product intent. The agent implements. Push, merge, and publish stay on your terms (git governance).

What’s new

One block for the current release 1.9.1. From 1.5 through 1.9:

• Presets (1.5) — retornatus init --preset for python, python-platform, fastapi, django, rag, and worker
• Pull requests (1.5) — the GitHub Action comments the verdict on the PR
• Agent hooks — hook stop (1.6; 1.7 lets a real question end the turn), hook session-start (1.7), hook file-edit (1.8.0 scope warning; [hooks] scope_mode is warn, block, or off), and hook subagent-stop (shipped in 1.9.0). It reminds a Cursor, Claude Code, or Codex subagent when the active Change is not SATISFIED. [hooks] subagent_stop defaults to true.

Full notes: CHANGELOG.md.

Quick start

Python 3.11+. Install uv if you do not have it, then run this in your application repository (the project the agent should change):

uv tool install retornatus
cd /path/to/your-app
retornatus init && retornatus integrate && retornatus doctor

Command	What it does
uv tool install retornatus	Puts retornatus on your PATH
init	Creates .retornatus/. Optional --preset — see Presets
integrate	Installs the hub skill so the agent knows the loop
doctor	Readiness: healthy workflow versus hard stops

One-shot without a global install: uvx retornatus --help. You are ready when .retornatus/ exists, the hub skill is visible to the agent, and doctor is not stopping on “not initialized.” For a repo that already has history: retornatus project-init and retornatus wake --bridges.

Ask the agent for a written Change before code: Create a Retornatus Change for GET /health returning 200. Contract and gates before code.

Go deeper: Quick start · Environments · FAQ

Presets

init without --preset writes a minimal config. retornatus init --list-presets lists packaged configs. An existing config.toml stays unless you pass --force-config.

python (pytest, ruff, and mypy), python-platform (deploy files or model behavior), fastapi, django, rag, and worker (background jobs).

retornatus init --preset fastapi

These checks record that a command ran and exited 0. They do not review a Terraform plan or score retrieval quality. Full page: Presets.

How it works

Step	In plain words	Command
Understand	Clarify the ask before coding	change elicit
Agree	Write the finish line	gate contract
Build	Implement under that agreement	loop next / run
Prove	“Done” needs evidence	evidence run → verify
Learn	Keep what mattered	change learn

A fuzzy ask makes change elicit exit 1 and list questions. A prompt that might need a new procedure goes through intake analyze; nothing is saved until you answer CREATE=yes. How it works.

What you get — and why it helps

Requirements. Without a written situation, “add login” becomes three products in three chats. How it works.

Memory. Changes, proof, and lessons live in git. wake rebuilds continuity. Memory.

Proof. verify returns SATISFIED, NOT_SATISFIED, or INCONCLUSIVE. Test, build, and lint results count only when Retornatus ran the command. Required checks, freshness, and gate suppressions / gate scope: Gates. gate omission fails a code diff that touches no Change. A configured dependency bot (by default dependabot[bot] and renovate[bot]) passes when every changed file is an allowed manifest, and the pass prints a warning. Turn that off with [governance.omission.bot_exemption] enabled = false.

Depth. A typo stays small. Payments, security, or a new design get a deeper pass.

One map, then one extra guide. The hub skill is the short map every turn. A specialization Skill is an optional playbook for one kind of work — at most one, and only after you confirm it. Skills.

When the same evidence commands succeed on several Changes, Retornatus can queue a skill candidate. The agent may ask once. Nothing is written until you run retornatus skill accept. List the queue with retornatus skill candidates.

Agent hooks

retornatus integrate --hooks installs four opt-in hooks for Claude Code, Cursor, and Codex. hook session-start injects the active Change. hook file-edit warns when an edit leaves that Change’s scope ([hooks] scope_mode is warn by default, or block, or off). hook stop asks the agent to keep going when the Change is not SATISFIED, and lets a real question to you end the turn. hook subagent-stop sends that same reminder when a subagent finishes ([hooks] subagent_stop defaults to true). They fail open. The pull-request check stays the source of truth. Guide: Agent hooks.

Commands

Continuity: wake, doctor, status, init --preset, integrate. Finish line: change elicit, change create, gate contract. Proof: evidence run --claim … -- <command>, verify. Skills from repetition: skill candidates, skill accept, skill reject. Agent hooks: integrate --hooks, hook file-edit, hook session-start, hook stop, hook subagent-stop. Diff gates: gate suppressions, gate scope, gate omission, hooks install. Full map: CLI.

Verify receipts

verify --receipt writes an Ed25519 receipt for the verdict. The private key stays outside the repo; a clone checks the receipt with the committed public key. Keys, the CI signing step, and the threat model: CLI — Receipts.

Cloud and remote agents

A cloud agent starts from a clean machine. Install from PyPI. Git does not version hooks, so every fresh clone runs hooks install. Leave receipts unsigned.

pip install retornatus
# or
uv tool install retornatus
export PATH="$HOME/.local/bin:$PATH"
retornatus hooks install
retornatus hooks status
retornatus doctor

templates/ci/retornatus-pr.yml runs the GitHub Action (uses: luizssantiago92/retornatus@v1) and comments the verdict on the PR. Notes: Cloud agents.

Documentation

Website · Quick start · Docs hub · From Spec Guardrails · PRD.

Sources: docs/guide/. Pages builds the HTML. Local preview: python scripts/build_docs_html.py (output is gitignored).

Credits

Ideas are credited by influence. Spec Guardrails (MIT) is the direct predecessor: a separate successor, not a fork. Retornatus keeps the written plan, the gates, the proof, and the memory in a Python CLI under .retornatus/.

Provenance: credits · credits-and-lineage.md.

Contributing / Maintainers

Issues and pull requests: CONTRIBUTING.md. Maintainer release steps: CONTRIBUTING — Releases.

License

MIT — see LICENSE.