docs + chore(workplan): complete T05 for CYA-WP-0004 — lightweight release process (checklist + Makefile targets)

Makefile

@@ -1,7 +1,7 @@
 # Simple developer Makefile for can-you-assist
 # Focus: easy dev-head install and common tasks
 
-.PHONY: dev-install install test clean dist
+.PHONY: dev-install install test clean dist version release-prep check-dist
 
 # Install the package in editable mode from the current source
 # This is the recommended way to work on the latest code
@@ -27,4 +27,19 @@ dist: clean
 
 # Show current version (useful after setuptools_scm changes)
 version:
-	python3 -c "import cya; print(cya.__version__)"
+	python3 -c "import cya; print(cya.__version__)"
+
+# Prepare for a release (run tests + build clean artifacts)
+release-prep: clean test dist
+	@echo ""
+	@echo "Release artifacts ready in dist/"
+	@echo "Next steps: create annotated git tag and push it."
+
+# Verify the built wheel in an isolated environment
+check-dist:
+	@echo "Testing wheel in fresh venv..."
+	@python3 -m venv /tmp/cya-dist-check
+	@/tmp/cya-dist-check/bin/pip install dist/can_you_assist-*.whl --quiet
+	@/tmp/cya-dist-check/bin/cya --version
+	@rm -rf /tmp/cya-dist-check
+	@echo "Wheel verification successful."

docs/release-process.md

@@ -0,0 +1,117 @@
+# Release Process (Lightweight)
+
+**Goal**: Cut a new release of `can-you-assist` with low risk of mistakes and produce clean distribution artifacts.
+
+This process is intentionally manual and lightweight. It can be automated later (CI + PyPI publishing).
+
+## Prerequisites
+
+- You have write access to the repository.
+- You have run `make dev-install` (or equivalent) so all dev tools are available.
+- You are on a clean `main` branch with all changes committed and pushed.
+
+## Step-by-Step Release Process
+
+### 1. Decide on the new version
+
+Use semantic versioning:
+- `MAJOR.MINOR.PATCH` (e.g., `0.2.0`, `0.3.1`, `1.0.0`)
+
+Check the current version:
+
+```bash
+make version
+```
+
+Decide the next version and note it (e.g., `0.2.0`).
+
+### 2. Update version metadata (if not using git tags for releases)
+
+> **Note**: With `setuptools_scm` (T02), the version is primarily driven by git tags for releases.
+> For a clean release, we will create a git tag. The version in `pyproject.toml` can stay dynamic.
+
+If you want an explicit version bump before tagging (optional but sometimes useful for clarity):
+
+- The version is derived from the upcoming git tag. You do **not** need to edit files for the release version itself.
+
+### 3. Run the full test suite
+
+```bash
+make test
+```
+
+All tests must pass.
+
+### 4. Build clean distribution packages
+
+```bash
+make clean
+make dist
+```
+
+This produces artifacts in `dist/`:
+- `can_you_assist-<version>.tar.gz` (sdist)
+- `can_you_assist-<version>-py3-none-any.whl` (wheel)
+
+### 5. (Optional but recommended) Smoke-test the built wheel
+
+```bash
+python3 -m venv /tmp/verify-release
+/tmp/verify-release/bin/pip install dist/can_you_assist-*.whl
+/tmp/verify-release/bin/cya --version
+/tmp/verify-release/bin/cya --help
+rm -rf /tmp/verify-release
+```
+
+The `cya` command must work and report the correct release version.
+
+### 6. Commit any final release-related changes (if any)
+
+Normally there should be none after T02 (versioning is dynamic via tags).
+
+### 7. Create and push the release tag
+
+```bash
+git tag -a v0.2.0 -m "Release v0.2.0"
+git push origin v0.2.0
+```
+
+This tag will be picked up by `setuptools_scm` on the next build and will produce the clean version `0.2.0`.
+
+### 8. (Future) Upload to PyPI
+
+Once we have a PyPI publication workflow:
+
+```bash
+python -m twine upload dist/*
+```
+
+For now, the `dist/` artifacts can be shared manually or attached to a GitHub release.
+
+## Makefile Targets Useful for Releases
+
+```bash
+make clean          # Remove build artifacts
+make dist           # Build sdist + wheel (recommended)
+make version        # Show current version
+make test           # Run tests
+```
+
+You can add more targets later (e.g., `make release-prep` that combines clean + test + dist).
+
+## Safety Notes
+
+- Never push a tag until you have verified the build and tests.
+- Release tags should be annotated (`-a`).
+- After a release, you can continue development on `main` — the next dev versions will automatically become `0.2.0.devN+...` thanks to `setuptools_scm`.
+
+## Future Improvements (Out of Scope for This Slice)
+
+- Automated release via GitHub Actions on tag push
+- Automatic PyPI upload on release
+- Changelog generation from commits
+- Signed releases
+
+---
+
+This process is intentionally simple so a single maintainer can execute it reliably with low cognitive load.

workplans/CYA-WP-0004-dev-install-and-release-packaging.md

@@ -144,23 +144,24 @@ completed: "2026-05-27"
 
 ```task
 id: CYA-WP-0004-T05
-status: todo
+status: done
 priority: medium
 state_hub_task_id: "c97acc58-14d7-47b9-9ab3-936ab1eb92df"
+started: "2026-05-27 ralph iter 5"
+completed: "2026-05-27"
 ```
 
-- Document (and optionally script) the steps to cut a release:
-  1. Decide on new version
-  2. Update version metadata
-  3. Run tests
-  4. Build packages
-  5. Create git tag
-- Consider a small helper script or Makefile targets (`make release-prep`, `make build-dist`).
-- Ensure the process is reproducible and documented in a `docs/release-process.md` or similar.
+**Done.**
 
-**Acceptance criteria**:
-- A clear, written release checklist or script exists that a maintainer can follow with low risk of mistakes.
-- The process produces artifacts that could be uploaded to a package index.
+- Created `docs/release-process.md` — a clear, step-by-step, low-risk release checklist covering version decision → tests → build → tagging.
+- Enhanced the `Makefile` with two very useful release targets:
+  - `make release-prep` (runs clean + test + dist in one go)
+  - `make check-dist` (smoke-tests the built wheel in a fresh venv)
+- The process is fully reproducible and documented.
+
+**Acceptance criteria met**:
+- A maintainer now has a written checklist + Makefile helpers that make cutting a release feel safe and boring.
+- The process produces ready-to-upload artifacts.
 
 ### T06 — Update documentation for both installation methods