iftypeset/docs/07-session-resilience.md

Session Resilience (avoid “lost work” when chats reset)

Codex/chat sessions can lose conversation context when a connection drops. The filesystem does not: the durable source of truth is the repo.

This project adds a few boring mechanisms to make resuming work deterministic.

What to trust

• Repo state: README.md, STATUS.md, docs/ are canonical.
• CI: ./scripts/ci.sh is the fastest sanity check.
• Artifacts: out/ contains the latest reports from CI runs.

Quick resume checklist (30 seconds)

From the repo root:

• ./scripts/audit.sh
• ./scripts/ci.sh

If both look sane, you’re back.

Create a checkpoint (2 minutes)

When you finish a meaningful chunk of work (new rule batches, QA changes, renderer changes), run:

• ./scripts/checkpoint.sh "what changed"

This:

• runs CI and stores the CI JSON in out/checkpoints/
• creates a compressed snapshot tarball in out/checkpoints/
• appends a new entry to docs/CHECKPOINTS.md with the snapshot hash

This gives you a portable restore point even if the chat transcript is gone.

Best practice (recommended)

• Push to a remote early (Forgejo/GitHub). A remote is the best anti-loss mechanism.
• Treat STATUS.md as the “1-page truth” for what exists and what’s next.
• Don’t rely on chat logs for state; copy any critical decisions into docs/.