checkpoint
Use when ending a work session, pausing, hitting a context limit, or before any handoff - captures a canonical stopping point so no context is lost. Also use when resuming, to recover the previous session. Replaces hand-written devlog/RESUME prose with typed, staleness-aware records.
- License 许可
- Apache-2.0
- 最近更新
- 2026-09-16
- Stars
- ★ 9
- Forks
- 4
01 前言 Front Matter
- name
- checkpoint
- description
- Use when ending a work session, pausing, hitting a context limit, or before any handoff - captures a canonical stopping point so no context is lost. Also use when resuming, to recover the previous session. Replaces hand-written devlog/RESUME prose with typed, staleness-aware records.
03 SKILL.md 正文
checkpoint — canonical session stopping point
A checkpoint is not a summary. A summary is prose someone must read and reconcile; this is typed records a machine can hand back verbatim, with every perishable claim carrying a computed freshness verdict.
The failure this exists to prevent, observed repeatedly: an agent resumes, reads a hand-written RESUME doc, and confidently quotes "13/13 tests green" that was measured hours and eleven commits earlier. The number was never wrong when written. It went stale, and flat prose cannot say so.
Store: .foreman/session.db (SQLite).
Tool: skills/foreman/scripts/fm-session.py.
Resuming — do this FIRST, before anything else
python3 skills/foreman/scripts/fm-session.py begin --note "what you are about to do"
This prints the canonical recovery and mints a session id. It is the only recovery you need — do not also go reading old RESUME files, and do not trust a number in any markdown file over what this prints.
Read the output in this order:
- STALE / unknown measurements. Each carries the exact command that produced it. Re-run them before quoting any of their numbers. This is the whole point of the checkpoint system; skipping it reintroduces the bug.
- Open obligations. This is your work queue.
- Facts. Durable context — what landed, with evidence.
Creating a checkpoint — when to do it
Do this when the user says checkpoint, when you are pausing or handing off, when you sense the context window filling, and before any long-running dispatch whose result you would otherwise have to remember.
Capture in this order. Everything is python3 skills/foreman/scripts/fm-session.py ….
1. Facts — durable, true by construction
Things that stay true: a commit landed, a decision was made, a package shipped. Always attach evidence (a SHA, a path, a command).
fm-session.py fact "vendor-preflight fixed: auth binds to probe content not exit status" --evidence "commit ad2366f"
fm-session.py fact "SQLite ontology replaced TerminusDB" --evidence "commit b3bbdc3"
2. Measurements — perishable, and the reason this system exists
Any number produced by running something: test counts, timings, benchmark results, pass/fail verdicts.
--scope is mandatory and the tool refuses without it. The scope is the set
of paths whose modification would invalidate the number. A measurement with no
scope can never be shown stale, which defeats the entire mechanism.
fm-session.py measure "tests/audit-verdict.bats pass count" 26 \
--command "flock /tmp/foreman-bats.lock bats tests/audit-verdict.bats" \
--scope tests/audit-verdict.bats \
--scope skills/foreman/scripts/audit-run.sh
Recovery then computes fresh|stale|unknown at read time via
git rev-list <measured_sha>..HEAD -- <scope>. You cannot receive the number
without its verdict.
Never record process liveness as a measurement. "Lane X is running" is false
seconds later. Ask the process; that is what tools/lanectl.sh ps is for.
3. Obligations — owed work and stated blockers
fm-session.py obligation "wt-merge.sh gate-to-merge TOCTOU needs its own package"
fm-session.py obligation "graph-context-builder T2-T10 unimplemented" --blocker "needs architect diagnosis; task lists do not dispatch"
fm-session.py close 3 --status done
A stated blocker is a good outcome. Record it rather than leaving it implied.
4. Supersede rather than edit
When a fact stops being true, do not delete it — link the replacement, so the history of what was believed stays intact:
fm-session.py supersede 4 "the suite is 41 files, not 33" --evidence "tests/run.sh output"
5. End the session
fm-session.py end
What belongs here versus elsewhere
| Goes in the checkpoint | Stays where it is |
|---|---|
| What landed, with evidence | Full narrative devlog prose |
| Numbers, with the command and scope that produced them | AGENT_TRAPS.md — standing rules that never go stale |
| Owed work and blockers | bugeventlog.md — incident post-mortems |
| Decisions and their reasons | Source code and its comments |
The checkpoint answers "what is true right now, and what of it can I still trust?" The other files answer "what happened" and "what must I never do again." Do not merge them.
Rules
- Recovery is exact SQL, never similarity search. Two resumes of the same tree must produce the same world. If recovery ever becomes fuzzy, it is no longer canonical and you are back to guessing.
- A measurement without
--scopeis refused. Do not work around it by recording numbers as facts — a fact cannot go stale, so that launders a perishable claim into a durable one. That is precisely the original bug. - Re-run stale measurements before quoting them. The recovery output hands you the command; there is no excuse.
- Checkpoint before the context window is critical, not after. A checkpoint you could not finish writing is worth nothing.
04 同仓库更多 Skills
foreman
暂无简介
writing-skills
Use when creating new skills, editing existing skills, or verifying skills work before deployment
writing-plans
Use when you have a spec or requirements for a multi-step task, before touching code
verification-before-completion
Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always
using-superpowers
Use when starting any conversation - establishes how to find and use skills, requiring skill invocation before ANY response including clarifying questions
using-git-worktrees
Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback