docs + chore(workplan): complete T01 for CYA-WP-0004 — packaging audit and requirements document created

docs/packaging-audit-and-requirements.md

@@ -0,0 +1,87 @@
+# Packaging Audit and Requirements (CYA-WP-0004 T01)
+
+**Date:** 2026-05-27  
+**Workplan:** CYA-WP-0004
+
+## Current State Audit
+
+### Packaging Configuration
+- **Build system**: `setuptools` (via `pyproject.toml`)
+- **Version**: Hardcoded as `0.1.0` in two places:
+  - `pyproject.toml`
+  - `src/cya/__init__.py`
+- **Entry point**: `cya = "cya.cli.main:run"` (correct)
+- **Package discovery**: `src` layout via `[tool.setuptools.packages.find]`
+- **Dependencies**: Minimal (`typer[standard]`, `rich`)
+- **No**:
+  - `setuptools_scm` or dynamic versioning
+  - `[project.optional-dependencies]`
+  - `build` frontend usage
+  - `MANIFEST.in` or equivalent include rules
+  - `include-package-data` configuration
+  - Development/test extras
+  - `pyproject.toml` validation for `pip install git+...`
+
+### Current Installation Experience
+- Only documented method: `pip install -e .` (editable)
+- `pip install git+https://...` is not reliable (version will be wrong, potential missing files)
+- No released packages exist yet
+
+### Gaps Identified
+
+**For "Install from Dev Head":**
+- No support for clean `pip install "git+https://github.com/worsch/can-you-assist.git@main"`
+- Version will be stuck at 0.1.0 even on latest code (bad for debugging)
+- Potential missing non-.py files in the sdist/wheel when installing from git
+- No documented one-liner or Makefile target for the primary user
+
+**For "Release Packaging":**
+- No versioning strategy (how to bump, dev vs release versions)
+- No process to build clean, reproducible sdist + wheel
+- No `python -m build` usage
+- No release checklist or automation (even lightweight)
+- No way for others to `pip install can-you-assist` (or a future released name)
+
+**General Technical Debt:**
+- Version is duplicated in two places (violates DRY)
+- No separation between build-time and runtime concerns
+- No packaging tests or verification step
+
+## Requirements for CYA-WP-0004
+
+### Must-Have for Dev-Head Install
+1. `pip install "git+https://github.com/worsch/can-you-assist.git"` (and `@main`, `@branch`) must produce a working `cya` with a dev-informative version.
+2. The primary user must have a simple, documented way to stay on latest code.
+3. Version must clearly indicate it is from development head (e.g., `0.2.0.devN+g<hash>` or similar).
+
+### Must-Have for Release Packaging
+1. A clear, repeatable process to cut a new version.
+2. Ability to produce clean `sdist` + `wheel` using modern tools (`python -m build`).
+3. Version must be single-source-of-truth.
+4. Documentation in README + AGENTS.md for both installation methods.
+
+### Nice-to-Have (in scope if low cost)
+- Makefile targets for common operations (`make dev-install`, `make dist`, `make check-dist`)
+- Basic CI step that verifies packaging works
+- Optional dependencies (e.g., `[dev]`, `[test]`)
+
+## Versioning Strategy Recommendation (for T02)
+
+**Recommended approach: Hybrid using `setuptools_scm`**
+
+- For development/git installs: Automatic versions like `0.3.0.dev14+g3f2a1b7.d20260527`
+- For releases: Clean versions like `0.3.0`
+- Single source of truth in git tags + `pyproject.toml` configuration
+- Minimal changes to existing workflow
+
+**Alternative (simpler but less powerful):** Keep static version + manual bumps + release checklist. Only use if `setuptools_scm` is deemed overkill.
+
+**Decision needed in T02.**
+
+## Next Steps
+
+- T02 will decide and implement the versioning approach.
+- T03 will focus on making git-based installs reliable.
+- T04–T05 will focus on the release side.
+
+This audit serves as the requirements baseline for the rest of the workplan.

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

@@ -48,21 +48,23 @@ This workplan addresses the current gap where only `pip install -e .` (editable
 
 ```task
 id: CYA-WP-0004-T01
-status: todo
+status: done
 priority: high
 state_hub_task_id: "018d0c4c-948e-4cd6-9a50-92a83725df18"
+started: "2026-05-27 ralph iter 1"
+completed: "2026-05-27"
 ```
 
-- Review the current `pyproject.toml`, `src/` layout, entry points, and any hidden packaging assumptions.
+**Done** — produced `docs/packaging-audit-and-requirements.md`.
-- Document what currently works and what breaks for:
-  - `pip install git+https://...`
-  - Building clean sdist + wheel
-- Define concrete requirements for both "dev head" and "released package" experiences.
-- Decide on a versioning approach (e.g., static + manual bumps, `setuptools_scm`, or hybrid).
 
-**Acceptance criteria**:
+- Full audit of `pyproject.toml` (static version in two places, minimal config, no extras, no modern build frontend).
-- Clear gap analysis and requirements document (can live in the workplan or a short `docs/packaging-requirements.md`).
+- Documented gaps for both "install from dev head" and "release packaging".
-- Versioning strategy chosen and justified.
+- Clear requirements defined.
+- Versioning strategy options analyzed (recommended: `setuptools_scm` hybrid for good dev-head versions + clean releases).
+
+**Acceptance criteria met**:
+- Gap analysis + requirements document created.
+- Versioning options documented for decision in T02.
 
 ### T02 — Establish a sustainable versioning strategy