Checkpoints and rollback

Every passing test, build or run takes a snapshot of the project into a private store. Rollback restores the last one that was known to work. Your .git is never involved.

Where they live

.orstrum/shadow/ is a bare git repository whose work tree is your project. Orstrum runs git with GIT_DIR pointed there, so nothing it does can reach your own .git, your index, your branches or your .gitignore. The snapshot excludes .git, .orstrum/, node_modules/ and whatever your .gitignore excludes. Requires git on your PATH.

When they are taken

• Automatically, at the end of a turn whose last shell command was a test, build or run with a trustworthy exit status (not piped) that passed.
• On request, when the agent calls orstrum_checkpoint before a risky change, or when you ask it to.
• Before every rollback, so a rollback can itself be undone.

A checkpoint is marked working only if the check that triggered it passed, and not if the pass followed edits to test files alone (see test tampering).

Checkpoint cp-4 saved (3 files changed; marked working: `npm test` passed).
Checkpoint cp-5 saved (1 files changed; not marked working: `npm test` failed).
No changes since cp-4; nothing new to save.

Rollback

orstrum_rollback restores the last working checkpoint by default, or a named one (cp-4). Modified and deleted files come back; files created since are removed; ignored files are never touched. The result names the undo:

Rolled back to cp-4 (Oct 14, 3:05 PM, after `npm test` passed): 2 restored, 0 brought back, 1 removed.
Undo with orstrum_rollback cp-7.

When nothing has passed yet, rollback refuses rather than guessing: No working checkpoint yet: none was taken after a passing test, build or run.