How it works
A complete Change from demand to continuity.
1. Continuity first
retornatus wake
# or: retornatus wake --bridges
Wake reconstructs Environment capabilities, Change ids, Rules, Learnings, and rebuilds the disposable SQLite index from files.
2. Demand and Situation (requirements analysis)
A Demand is the human intent. Situation is the requirements-analysis step: enough understanding to formalize a Contract — not a full design doc.
retornatus change elicit --demand "…" --what "…" --done "…"
# When questions remain (exit 1), ask them in chat, then record:
retornatus change elicit --demand "…" --answer "scope=…" --answer "actors=…" --write situation-draft.md
Exit 0 means Situation looks sufficient; exit 1 means focused questions remain (at most five, with suggested options). The agent should ask those in chat before inventing a Contract. Repo signals (stack, tests, CI) and kickoff files (prd.md, docs/brief.md, …) feed elicitation — do not re-ask what they already answer.
3. Contract
An active Contract is the authoritative obligation: WHAT, constraints, DONE.
retornatus change create … # activates when Situation is sufficient
retornatus change create … --draft-contract
retornatus change activate C-0001 # later
retornatus gate contract C-0001 # must exit 0
Material changes archive the prior version (change reopen) — Contracts are not silently mutated.
4. Action and Tasks
An Action is a bounded unit of work under Authority. Tasks appear when decomposition helps; declaration order is not an automatic dependency chain.
retornatus change create … --task "Implement" --task "Test" --depends "1:0"
retornatus loop next C-0001
retornatus task start C-0001/T-001
loop next never returns BLOCKED work as “next”.
5. Specialization (optional — as soon as needed)
# From a chat prompt, before Action exists:
retornatus skill need --prompt "…"
retornatus skill create --need "…"
# Or once an Action exists:
retornatus skill need --action C-0001/A-001
retornatus skill create --need "…" --action C-0001/A-001
# agent researches current docs → fills RESEARCH + PROCEDURE
retornatus gate skill-research S-0001
retornatus skill activate S-0001
retornatus skill export S-0001
Governed bypass: skill activate --force --reason "…" records Bypass + Decision.
6. Execution context
retornatus run C-0001/A-001
retornatus run C-0001/A-001 --strict-policy
Retornatus assembles Rules, Learnings, Skills, Boundaries, and Policy — it does not run the model. The host agent implements.
7. Evidence and Assurance
retornatus evidence run -c C-0001 -t test_result -s "/health" \
--claim C-0001/claim-done-1 -- python -m pytest -q
# claim-done-2 DONE: docs/health.md documents GET /health
retornatus evidence add -c C-0001 -t repository_observation -s "docs/health.md" \
--source filesystem --claim C-0001/claim-done-2
retornatus gate evidence C-0001
retornatus verify C-0001
evidence run executes the command itself (no shell, cwd = project root, --timeout optional) and stores argv, exit code, start/end, duration, SHA-256 of combined stdout/stderr, a truncated tail, the full output file next to the Evidence JSON, and git HEAD plus dirty state when the directory is a repository. Provenance is executed. A non-zero exit or a timeout is failing Evidence.
evidence add stores provenance self_reported. For test_result, security_test, build_result, and lint_result that does not satisfy verify (the claim is UNVERIFIED, exit code is not 0). Pass --allow-self-reported or set [assurance] allow_self_reported = true while migrating. Review notes and repository observations stay self-reportable and are labeled as such.
When [assurance] required_checks is set, only those argv lists can satisfy execution claims, and only if the exit code is 0, the recorded commit is still HEAD, and the worktree is clean of source edits. verify --run-checks (or checks run) runs the declared commands itself. Uncommitted edits to a subject path mark evidence stale (fail for execution types by default). gate suppressions and gate scope look at the real diff; hooks install runs them on commit. See Gates.
Verdicts: SATISFIED · NOT_SATISFIED · INCONCLUSIVE. Evidence must bind to Claims. Subject match is exact after normalization, plus a one-way path suffix (docs/health.md can satisfy claim /health.md; / does not satisfy /health). subject_state of the form commit:<sha> still fails freshness when the subject moves. A mismatch between the recorded execution commit and current HEAD is only a warning.
Independent review when needed: assurance plan / assurance review / run --assurance.
8. Problems become structure
retornatus finding add --change C-0001 --observation "…"
retornatus question open --change C-0001 --statement "…" --finding C-0001/F-001
retornatus question resolve C-0001/Q-001 --summary "…" --evidence C-0001/E-001
retornatus question reopen C-0001/Q-001 # if the condition returns
Verifiable Questions require Evidence — a summary alone is not establishment.
9. Adaptation
retornatus change learn --title "…" --body "…"
retornatus skill evolve S-0001 --note "…"
retornatus rule propose --statement "Do not …" --applicability "…"
retornatus decision record --kind APPROVE_RULE_ACTIVATION \
--subject R-0001 --summary "…" --confirm R-0001
retornatus rule activate R-0001 --decision D-0001
Learning informs; Rules constrain. Activation always needs a Human Decision.
10. Restart
Delete .retornatus/index/retornatus.db and run wake — semantic history in files remains; the index rebuilds.
Full acceptance narrative: PRD §69.