Retornatus

Gates

Gates are mechanical brakes. Non-zero exit = STOP.

They do not replace judgment; they prevent pretending success when structure or proof is missing.

--json on verify and on every gate subcommand prints the same pass or fail as text mode, as a versioned document on stdout. See JSON output. The GitHub Action posts that result as one sticky pull-request comment.

Gate catalog

CommandStops when
retornatus gate contract <C-id>No active Contract, empty WHAT, or no DONE criteria
retornatus gate skill-research <S-id>RESEARCH lacks sources / PROCEDURE blank
retornatus gate evidence <C-id>No Evidence artifacts for the Change
retornatus gate assurance <C-id>Assurance is not SATISFIED
retornatus gate policy <A-id>Policy is DENY or REQUIRE_HUMAN
retornatus gate budget <A-id>Action attempt_count reached max_attempts
retornatus gate suppressionsAdded lines introduce a suppression or skip marker. With no flag, untracked non-ignored files count as added
retornatus gate scope <C-id>The diff leaves Task resources, hits a denied path, or touches a sensitive path without a satisfied review/security claim
retornatus gate omissionCode changed (src/, tests/, scripts/, templates/, root pyproject.toml, or root uv.lock) and the diff touches no Change. A configured dependency bot can pass this gate; the pass prints a warning
retornatus verify <C-id>Same family as assurance over Contract DONE Claims

Related:

retornatus policy check --action <A-id>
retornatus policy check --effect "…"
retornatus run <A-id> --strict-policy
retornatus action budget <A-id> --max 5
retornatus receipt keygen            # public key in-repo; private key outside it
retornatus verify <C-id> --receipt   # Ed25519 receipt (needs the private key)
retornatus receipt verify path/to/receipt.json   # public key only

Assurance verdicts

VerdictMeaning
SATISFIEDEach required Claim has bound, fresh, type-appropriate Evidence. Execution types must be executed with exit code 0
NOT_SATISFIEDEvidence exists but is wrong, failing, stale, or only self-reported for an execution type
INCONCLUSIVERequired Evidence missing or unbound

Claim results may also say UNVERIFIED: a test_result, security_test, build_result, or lint_result was self-reported (evidence add) instead of produced by evidence run. That claim does not yield overall SATISFIED (exit 0).

verify prints one line per Evidence (provenance=… status=…) before the JSON. Narrative types stay acceptable and are labeled status=self-reported.

Migration opt-out: verify --allow-self-reported, or in .retornatus/config.toml:

[assurance]
allow_self_reported = true

If executed Evidence recorded a git commit and HEAD has moved, verify prints WARN … stale snapshot; not a failure. That warning does not change the verdict, unless required checks are configured (below). Freshness that uses subject_state of the form commit:<sha> (--git-state) can still mark Evidence stale and fail the claim.

Uncommitted or untracked edits to a claim subject path are visible to verify. Execution-type claims fail (the evidence is stale). Narrative claims warn. Override with:

[assurance]
uncommitted_changes = "fail"  # or "warn"

Required checks

The agent chooses the command for evidence run, so evidence run -- true would otherwise be a passing test. The owner names the commands that count:

[assurance]
required_checks = [
  { name = "tests", run = ["pytest", "-q"] },
  { name = "lint", run = ["ruff", "check", "src"], types = ["lint_result"] },
]

types (alias claim_types) is optional. Empty means the argv may satisfy any execution type (test_result, security_test, build_result, lint_result). For those claims, verify then requires:

Evidence files Retornatus just wrote under .retornatus/changes/ do not, by themselves, count as a dirty tree. Any other uncommitted path does. Committing those files does not stale the check either, when the commits after the recorded SHA change only .retornatus/changes/, .retornatus/index/, or .retornatus/runtime/. The same rule applies to a commit:<sha> subject state. A later commit that changes any other path does. allow_self_reported does not bypass a configured check.

retornatus checks run -c C-0001
retornatus verify C-0001 --run-checks

Both execute the declared argv through the same capture path as evidence run and record the Evidence.

Ship and AI surfaces

The python-platform preset adds [surfaces]. verify requires extra Evidence only when a Task resource or a git worktree path matches that table's globs. Otherwise the rule is not required (see surfaces on verify --json). A match needs an executed command — the suggested infra check, or the configured eval command — plus a narrative rollback or fallback note. The checks parse config and templates. They do not review a Terraform plan, and they do not grade eval quality. Globs and commands are overridden in config.toml. Full page: Presets.

Suppression gate

retornatus gate suppressions
retornatus gate suppressions --staged
retornatus gate suppressions --base main

Added lines (+, not file headers) are scanned for markers such as noqa, type: ignore, pragma: no cover, pytest.mark.skip, pytest.mark.xfail, unittest.skip, eslint-disable, @ts-ignore, @ts-expect-error, .only(, it.skip, describe.skip, pylint: disable, and --no-verify.

Markdown (.md, .markdown, .mdx, .mdc) skips a match that sits inside a fenced code block or an inline code span. Naming ` --no-verify in a sentence is documentation of the marker, not a suppression added to executable code. The same marker outside a code span still fails the gate. allow_paths and allow_patterns` still apply to every file.

[governance.suppressions]
extra_patterns = ["\\bHACK\\b"]
allow_patterns = ["type:\\s*ignore\\[override\\]"]
allow_paths = ["vendor/**"]

allow_patterns skip a whole added line. allow_paths skip a file. With no flag, the scan is git diff HEAD (staged and unstaged tracked changes) plus every line of each untracked file from git ls-files --others --exclude-standard. A file that has not been git added is treated like an added file. Gitignored paths are not scanned. --staged is the index only. --base is base...HEAD only, so a clean CI checkout still scans just that committed range.

Scope gate

retornatus gate scope C-0001 --base main
retornatus gate scope C-0001            # staged + unstaged + untracked
retornatus gate scope C-0001 --staged

Changed paths must sit in the union of the change’s Task.resources and .retornatus/**. A resource is an exact path, a directory prefix when it ends with /, or a glob when it contains *, ?, or [.

These globs always fail (override with [governance.scope] denied_globs):

/.env, /.env.*, /secrets/, **/*.pem, **/*.key

Sensitive paths (infra, auth, migrations, CI workflows — override with sensitive_globs) fail unless the change has a satisfied review_result or security_test claim backed by evidence of that type.

Subject matching is exact after strip, case-fold, and trailing-slash normalization (/Health/ matches /health). A shorter evidence subject is not treated as contained in the claim (/ does not match /health). A longer evidence path may end with the claim's path token (docs/health.md matches claim /health.md); the reverse does not.

> Agent conclusion ≠ Evidence. A green test suite is evidence of tests — not automatic proof of every Claim unless bound correctly and actually executed by the harness.

Omission gate

retornatus gate omission --base main
retornatus gate omission --base main --pr-author "dependabot[bot]"

The GitHub Action runs this gate on every pull request. It fails when the diff changes code and does not touch a Change under .retornatus/changes/. Code paths are src/, tests/, scripts/, templates/ (including nested files), and the root files pyproject.toml and uv.lock. Docs, README, and other paths do not trigger it by themselves.

Dependency bots cannot commit a Change. When the exemption is enabled, the author is on the author list, and every changed file matches the path list, the gate passes and prints a WARN line that names the author and the files. That warning is the notice. It is not a silent pass. One file outside the list, or an author that is not listed, leaves the failure unchanged. A bot that edits src/ still fails.

The author is an argument. The Action sets it from pull_request.user.login. gate omission --pr-author is the same value for a local run. The gate does not read the pull request title, body, or commit messages, so a human cannot opt in by writing a bot's name there. Comparison is exact after stripping surrounding whitespace (dependabot is not dependabot[bot]).

The table is [governance.omission.bot_exemption], next to the other governance tables. A missing table is enabled with these defaults. authors and paths replace the defaults when set. They are not appended.

KeyDefault
enabledtrue
authorsdependabot[bot], renovate[bot]
paths/pyproject.toml, /uv.lock, /poetry.lock, /requirements.txt, /package.json, /package-lock.json, /pnpm-lock.yaml, /yarn.lock, /Cargo.toml, /Cargo.lock, /go.mod, /go.sum, .github/workflows/.yml, .github/workflows/*.yaml

Globs are the same matcher as gate scope. ** crosses directories, so apps/api/pyproject.toml and requirements-dev.txt match. A single * does not cross /, so .github/workflows/ci.yml matches and .github/workflows/nested/ci.yml does not. requirements.txt.bak and src/app.py do not match.

Turn the exemption off:

[governance.omission.bot_exemption]
enabled = false

A replacement list:

[governance.omission.bot_exemption]
authors = ["my-org-bot"]
paths = ["pyproject.toml", "uv.lock"]

RETORNATUS_OMISSION=warn in the Action still turns a real omission failure into a warning. It does not grant the exemption. An exempted pull request passes with fail or warn.

Process vs brakes

Process (hub skill)Brakes (gates)
Who checksAgent follows the skillCLI exit codes
Incomplete workAgent should stopAgent cannot claim success via gate
Best forLearning the methodTeams that need proof between approvals

Governed bypass

Some gates can be skipped only as a recorded decision, e.g.:

retornatus skill activate S-0001 --force --reason "Emergency hotfix; research deferred"

Bypass without reason/authority is rejected. See Governance.

Guarantees (product level)

GuaranteeMechanism
Contract before buildgate contract + Situation sufficiency
Research before specialized executiongate skill-research
Evidence before doneClaim-bound Evidence + verify
Continuity after crashCanonical files + wake
No silent Rule authorityHuman Decision required
Policy visibilitygate policy / --strict-policy
← Docs hub Product site →