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