save-progress

name	save-progress
description	Pre-commit checklist + context update — runs deterministic checks, updates PILOT.md and SESSION-CONTEXT.md. Does NOT commit.
allowed-tools	Bash(uv *), Bash(git status *), Bash(python *), Read, Edit(.meta/**)

You are in SAVE-PROGRESS mode. Run the deterministic preflight, then update project context.

Hard rules

• DO NOT create a commit — that is a separate action.
• If preflight fails, STOP and report — do not update .meta/ files.

Step 1 — preflight (deterministic, one command)

uv run python scripts/save_progress_preflight.py

The script runs: pytest, ruff check, ruff format --check, git status, and a check for stray drafts at the project root or code in .meta/scratch/. It prints a JSON summary and exits non-zero on any failure.

Step 2 — narrative update (LLM, only if step 1 is green)

1. Update .meta/PILOT.md — status table reflects actual state, not aspirational. Mark completed items. Add new next steps.
2. Rewrite .meta/SESSION-CONTEXT.md — architecture snapshot, active decisions (why), traps to avoid (what broke or could break), open questions. Rewrite, don't append.
3. Report: "Ready to commit. Run git add and git commit."

Verification

• Preflight JSON shows "ok": true for all 5 checks
• PILOT.md reflects actual state
• SESSION-CONTEXT.md captures traps and open questions, not just wins

Quick-pause mode (--skip-tests)

For mid-session checkpoints where tests are genuinely WIP, you may skip the pytest run:

uv run python scripts/save_progress_preflight.py --skip-tests

When to use: only when tests are intentionally red (e.g., mid-refactor, scaffold not yet wired). Not for "tests are slow" or "I can't fix this now."

Required: when using --skip-tests, add a Skip-Tests: true trailer to the commit message so the bypass is machine-readable in git history:

fix: partial scaffold for new module

Skip-Tests: true

Also note in SESSION-CONTEXT.md under "Traps to avoid" that tests are red and why, so the next session does not ship without fixing them.

Rationalizations you must not accept

Excuse	Why it's wrong
"Tests are passing, that's enough."	Lint and format issues compound — preflight catches them.
"I'll update PILOT.md later."	You won't. Next session reads PILOT.md first; stale = wrong.
"SESSION-CONTEXT.md is fine from last time."	Context decays every session. Rewrite, don't append.
"Small change, skip the preflight."	Small changes break things. The script takes 30 seconds.
"Tests are slow, I'll use --skip-tests."	--skip-tests is for intentionally red tests, not slow ones.