Retornatus

Git governance

Structural gates enforce artifact quality under .retornatus/. Git tiers enforce what leaves the machine.

Retornatus adopts the same blast-radius idea as Spec Guardrails’ Human-in-the-loop / git-handoff — adapted to Contracts and this repo’s ownership model.

> Approving a Change or Contract authorizes local work — not share, merge, or publish.

Tiers

TierWhat the agent may doWhat needs the human
0 — LocalImplement, test, commit locally (code + .retornatus/ memory)—
1 — ShareNothing automaticExplicit ask: git push, open/update PR
2 — ExternalNever (owner-only in this project)Merge, deploy, force-push, production data, PyPI publish, release tags that publish

Owner hard rule

In this repository (and by default for Retornatus-governed work here):

What to commit (Tier 0)

Usually yes

Usually no

retornatus init appends that set when .gitignore has no # retornatus-gitignore:begin marker. The block is .retornatus/index/, .retornatus/runtime/, .pem, .key, .env, and .env., then !.env.example and !.retornatus/keys/.pub. Running init again does not duplicate the block and does not delete lines above it. Canonical files (Changes, Contracts, Evidence, config.toml, public keys) stay tracked. init and receipt keygen print a warning when git already tracks a .pem or .key file. receipt keygen still writes the signing private key outside the repository.

Commit messages

Hooks

retornatus hooks install
retornatus hooks status
retornatus hooks remove

The hooks directory is git rev-parse --git-path hooks, so core.hooksPath and linked worktrees are honored. Scripts are POSIX sh and call python -m retornatus, which Git for Windows can run.

HookWhat it does
pre-commitgate suppressions --staged, then hooks scope (scope gate on the index) when a Contract is active
commit-msgReads the message file from $1. It does not open .git/COMMIT_EDITMSG itself

Existing user hooks are kept outside # retornatus:begin / # retornatus:end and run after the Retornatus block. hooks remove deletes only that block.

Git does not store those scripts. Every fresh clone, including a cloud agent VM, runs hooks install again. See Cloud agents.

Handoff checklist

Before ending a session or asking for review:

  1. git status is understood (clean or intentional leftovers)
  2. Local commits exist for finished units (Tier 0)
  3. No Tier 1/2 actions unless the owner asked
  4. One concrete next human step (review PR / merge / tag to publish)

Cursor bridge

Project rule: .cursor/rules/git-governance.mdc (alwaysApply: true).

Related

← Docs hub Product site →