refresh-cycle

name	refresh-cycle
description	Close the pipeline cycle: regenerate the living spec from current tests, summarize the carry-over cache files, regenerate source docstrings then strip all .py so the next cycle starts compact.

Refresh Cycle

1. Load [[methodology/simplicity-discipline]], [[software-craft/git-conventions]] — the derived-view rule and the commit form. You close the cycle; the next discovery pass inherits what you write.
2. Regenerate the living specification. Render docs/state.md from .templates/docs/state.md.template, substituting <name>, <version> (from pyproject.toml), <YYYY-MM-DD>, and <session_id>. Derive every field from the truth — the current test .pyi/.py, pending marks (uv run pytest --collect-only -m pending -q), cassettes, migrations, and docs/glossary.md — never from prose or memory. The contract-index intent column is read from each test body; the composition and data-flow lines are read from the e2e path the tests express. This file is a derived view; when prose and a test disagree, the test wins. Never hand-edit it.
3. Summarize the carry-over cache files. Rewrite each of .cache/<session_id>/interview-notes.md, .cache/<session_id>/external-contracts.md, .cache/<session_id>/data-model.md, and .cache/<session_id>/journal.md as a ~1000-word summary of this cycle — the decisions made, the contracts built, the gaps closed, the escalations resolved. Preserve the headers each template carries so the next pass appends in the right place; replace the body with the distilled record. Transient per-pass files (build-target.md, probe-target.md, probe-research.md) are NOT summarized — they are regenerated by the next pass.
4. Regenerate docstrings. Author faithful prose for every module, class, and public function/method across <package>/**/*.py — never a mechanical restatement of the signature; the why of an architectural decision lives in an ADR, not a docstring. Source only, never tests. Then run task lint-merge (ruff check --extend-select SIM,RUF . && ruff format .). Commit on dev as docs: regenerate docstrings + format.
5. Strip all .py docstrings. Run uv run python scripts/strip_docstrings.py $(find <package> tests -name '*.py' -type f) (many files, in place, line-range only; the glob skips .pyi). Commit on dev as chore: strip docstrings for next dev cycle.
6. Assert the gate evidence: spec-regenerated=true, cache-summarized=true, docstrings-regenerated=true, docstrings-stripped=true.