Checkpointing

Checkpointing

Capture durable session context without growing the always-loaded root AGENTS.md. Canonical state and artifacts live under .claude/.

Owned Paths

• .claude/checkpoints/: full timestamped checkpoints; never deleted by the compact phase.
• .claude/checkpoints/INDEX.md: generated catalog of every checkpoint.
• PROGRESS.md: latest five checkpoint summaries.
• .claude/STATE.md: one Progress Tracker link and current working blocks.
• .claude/logs/: drafts, previews, work logs, and CLI activity.
• .claude/docs/research/: research notes; inactive notes may be archived only after user approval.

Both scripts write nothing without --apply. Every default run produces preview files under .claude/logs/ and leaves PROGRESS.md and .claude/STATE.md untouched.

Full Checkpoint

1. Determine the time window from the newest checkpoint, or use all available history when none exists.

2. Gather the user requests and decisions from the current conversation, git changes, CLI logs, team work logs, and relevant design changes.

3. Write a Japanese five-part summary containing: 何をしたのか, どういうやり取りをユーザーと行ったのか, どうやったのか, 途中でどういう課題が起こったのか, and 将来のアクション. This is the irreducible judgment in the skill and is never generated: a missing, empty, stale, or incomplete summary aborts the run with exit 2.

4. Save the summary to .claude/logs/pending-summary.md, then preview:

   python3 .claude/skills/checkpointing/checkpoint.py \
     --summary-file .claude/logs/pending-summary.md

   Exit 0 reports result: preview and four preview files (checkpoint-preview-*, index-preview-*, progress-preview-*, state-preview-* under .claude/logs/). Exit 1 is a bad --since / --now; exit 2 is a summary or shared-state contract violation; exit 3 is a timestamp collision, a concurrent modification, or a write failure.

   Add --label <slug> when the session's commit messages would not name it well; the label becomes the checkpoint's slug in the frontmatter and the index.

5. Review the four previews, then write for real:

   python3 .claude/skills/checkpointing/checkpoint.py \
     --summary-file .claude/logs/pending-summary.md \
     --apply --consume-summary --json

   --consume-summary deletes the draft on success, so the next session cannot silently embed this session's summary. --json emits the single payload {ok, result, checkpoint_path, prompt_path, index_path, slug, tags, progress_path, progress_entries, state_path, state_updated, summary_validated, summary_consumed, commits, files_changed, cli_consultations, agent_teams, work_logs, collector_errors, skipped_records, warnings, artifacts}; without it the same facts are printed as prose. Quote collector_errors and warnings verbatim when reporting — a failed collector is not an empty session.

6. Confirm the shared-state invariant mechanically rather than by reading:

   python3 .claude/skills/checkpointing/refresh_guard.py --mode check

   Exit 0 means exactly one # Agent State and one ## Progress Tracker heading; exit 2 means the structure is invalid.

7. Review whether durable architecture decisions belong in .claude/docs/DESIGN.md; use /design-tracker when warranted.

8. Run the Compact Phase below.

Finding a Past Checkpoint

Three layers make retrieval cheap, so a past session is found without reading the directory file by file:

1. .claude/checkpoints/INDEX.md — one table, newest first, with the branch, tags, counts, and headline for every checkpoint. Read this first and scan the tags and summary columns.
2. YAML frontmatter — each checkpoint opens with id, timestamp, branch, slug, summary, tags, and the session counts. Reading the first ~14 lines settles relevance without parsing the document.
3. PROGRESS.md — the five most recent summaries in full, for the common case of "what happened lately".

INDEX.md is regenerated from the checkpoints' frontmatter on every --apply, so a deleted or hand-edited checkpoint is reflected on the next run rather than advertised forever. Checkpoint filenames stay YYYY-MM-DD-HHMMSS.md: the slug lives in the metadata, not the path, so PROGRESS.md links and collect_repo_state.py keep working. Do not hand-edit INDEX.md.