feat: add flow checkpoint for mid-session progress notes

[sanmesh-kakade]

Closes #72.

What

Adds flow checkpoint [<ref>] — a non-terminal command that drafts a mid-session progress note into tasks/<slug>/updates/ from the live transcript, reusing the existing headless claude -p sweep engine.

Why

flow injects context in at SessionStart but has no write-back. The dated notes under tasks/<slug>/updates/ are the durable per-session record a future flow do reads on resume — yet nothing prompts for them. On heavy days they go unwritten, and the next resume reads a stale brief. The only transcript→record path today is the flow done sweep, which is terminal (flips status) and aimed at KB + project-update, not a task note.

flow checkpoint is the non-terminal sibling of flow done:

• No status change, no KB writes — deliberately task-local and repeatable.
• Resolution mirrors flow show task: explicit ref by slug; no ref reverse-looks-up the task bound to the current session ($CLAUDE_CODE_SESSION_ID). Either way the task must carry a session_id.
• Reports what it wrote: SkipPermissionsRun discards the headless session's stdout, so the command snapshots updates/ before/after and prints any new file. An empty checkpoint (nothing warranted) is a success, mirroring done.
• Sweep failure = rc 1: unlike done (which swallows sweep failures because the status flip is the durability boundary), checkpoint has no status flip to protect.

Skill / contract change (called out per CONTRIBUTING): internal/app/skill/SKILL.md is updated so Claude sessions actually offer the command — added to the Sessions command reference, and §4.5 (Save a progress note) now describes checkpoint as the assisted, transcript-drafted alternative to a hand-written note and its relationship to the §4.7 flow done sweep.

Test plan

• make test passes
• CI green (go vet, go test ./..., build) — verified locally; vet clean, full suite green, gofmt-clean on changed files
• Manually exercised the command end-to-end: built the binary, pointed a throwaway task in a temp FLOW_ROOT at a real 931KB session transcript, ran flow checkpoint no-arg → live claude -p produced one correctly-shaped updates/ note, rc=0, before/after diff reported the path, and the KB was untouched (verifying the no-KB contract)
• Skill changed → re-embedded via go build (go:embed) and documented above

Files

• internal/app/checkpoint.go — cmdCheckpoint, buildCheckpointSweepPrompt, updates/ before/after diff helpers.
• internal/app/checkpoint_test.go — happy path, no-KB-write contract, sessionless refusal, unknown ref, unbound-no-ref, sweep-failure→rc1, prompt shape.
• internal/app/app.go — dispatch case + usage line.
• internal/app/skill/SKILL.md — command reference + §4.5 mention.
• CHANGELOG.md, CONTRIBUTORS.md, README.md.

Notes

• The transcript render has no time cutoff, so a checkpoint summarizes the whole session-so-far. The prompt instructs the headless pass to read existing updates/ first and only capture what isn't already logged, which keeps repeated checkpoints from duplicating. A future refinement could scope to "since the last note" if that proves noisy.
• A Stop-hook variant (auto-prompt at session end) was discussed in [feature] Session-end write-back: draft a progress note from the transcript #72 as the other half of the fix; this PR is the manual command only — self-contained, reuses existing machinery. Happy to follow up with the hook separately.

🤖 Generated with Claude Code