# Project Continuity Handoff Checklist

Use this when a user is about to reset/start a new session and wants no project context lost.

## Durable files to update

- `SESSION_HANDOFF.md`: current phase, verified state, commit, architecture rules, exact commands, known gaps, next steps.
- `docs/PROJECT_CONTEXT.md`: stable project purpose, module map, standards, data model, security rules, verification workflow.
- `docs/NEXT_SESSION_START.md`: first commands/files to read after reset, expected outputs, clean-state check.
- `docs/plans/<NEXT_PHASE>_PLAN.md`: continuation plan with bite-sized tasks and verification.
- `README.md`: keep project overview and pointers current.

## Staleness sweep before writing

Before editing, gather live facts with tools instead of trusting the chat summary:

```bash
date -u +'%Y-%m-%d %H:%M UTC'
git status --short
git log --oneline -8
```

Then update every handoff surface consistently. Search for stale phase names, commit SHAs, expected test counts, source-file counts, and "next task" pointers across `README.md`, `SESSION_HANDOFF.md`, `docs/PROJECT_CONTEXT.md`, `docs/NEXT_SESSION_START.md`, and plan files. A reset handoff is only useful if all surfaces agree.

## Verification before handoff commit

Adapt to the project, but include all configured gates and documentation whitespace checks:

```bash
git diff --check
ruff check app tests alembic
mypy app
pytest -q
alembic upgrade head --sql >/tmp/project-alembic.sql && tail -20 /tmp/project-alembic.sql  # if Alembic is configured
git status --short
```

If `git diff --check` reports Markdown trailing whitespace from hard line breaks, remove it unless the project intentionally uses that Markdown style.

## Git checkpoint

If no git repo exists and the project should be preserved, initialize one after confirming `.gitignore` excludes caches, virtualenvs, secrets, and generated artifacts:

```bash
git init
git branch -m main
git add -A
git commit -m "Initial project baseline"
```

For documentation-only handoff updates:

```bash
git add README.md SESSION_HANDOFF.md docs
git commit -m "docs: add reset handoff and next-phase plan"
```

## Compact memory

Save only a short pointer to the project path and durable docs. Do not store detailed task history in memory.