Release 0.4.0

.claude/commands/claude-health.md

@@ -0,0 +1,138 @@
+---
+description: Maintain coherence across Claude Code agentic capabilities (CLAUDE.md, rules, skills, commands, hooks)
+allowed-tools: Bash(ls *) Bash(find *) Bash(wc *) Bash(head *) Bash(cat *) Bash(jq *) Bash(python3 *)
+---
+
+# /claude-health
+
+Audit the project's Claude Code configuration and surface inconsistencies.
+
+## 1. Inventory check
+
+Verify all expected Claude Code files exist:
+
+```!
+ls -la .claude/rules/*.md .claude/commands/*.md .claude/settings.json 2>/dev/null | head -40
+```
+
+```!
+find .claude/skills -name "SKILL.md" 2>/dev/null
+```
+
+```!
+ls -la CLAUDE.md AGENTS.md 2>/dev/null
+```
+
+## 2. Size validation
+
+Keep individual rules and commands tight. CLAUDE.md should stay under ~200 lines for best adherence.
+
+```!
+wc -l CLAUDE.md AGENTS.md 2>/dev/null
+```
+
+```!
+wc -c .claude/rules/*.md
+```
+
+```!
+wc -c .claude/commands/*.md
+```
+
+```!
+wc -c .claude/skills/*/SKILL.md
+```
+
+## 3. Cross-reference audit
+
+Confirm these alignments:
+
+| Source                                | Must reference        | Check                                |
+| ------------------------------------- | --------------------- | ------------------------------------ |
+| `.claude/rules/python-style.md`       | Pydantic, type hints  | Matches `src/dppvalidator/` patterns |
+| `.claude/rules/dpp-domain.md`         | ESPR, CIRPASS, DPP    | Matches domain model structure       |
+| `.claude/rules/commits.md`            | Conventional commits  | Consistent with gitflow workflows    |
+| `.claude/skills/validate-dpp/`        | Validation logic      | References correct validator paths   |
+| `.claude/skills/pypi-publish/`        | Publishing steps      | Matches `pyproject.toml` config      |
+| Root `AGENTS.md` (imported by CLAUDE) | Tech stack, structure | Reflects current project state       |
+
+## 4. Command consistency
+
+Verify command descriptions match their content:
+
+```!
+head -5 .claude/commands/*.md
+```
+
+Check cross-references between commands:
+
+- `/release` should reference `/lint` and `/test`.
+- `/feature` and `/hotfix` follow gitflow.
+- `/fix-lint` complements `/lint`.
+
+## 5. Hooks validation
+
+```!
+cat .claude/settings.json | python3 -m json.tool > /dev/null && echo ".claude/settings.json valid JSON"
+```
+
+Verify hook commands are valid:
+
+- Commands use correct tool paths (`uv run ruff`, etc.).
+- Hook scripts under `.claude/hooks/` are executable.
+- Use the `$CLAUDE_PROJECT_DIR` env var for project-relative script paths.
+
+```!
+ls -l .claude/hooks/ 2>/dev/null
+```
+
+## 6. CLAUDE.md / AGENTS.md consistency
+
+Verify root context covers:
+
+- [ ] Project overview and purpose
+- [ ] Tech stack (Python 3.10+, Pydantic v2, uv, ruff, ty)
+- [ ] Directory structure
+- [ ] Development workflow (gitflow)
+- [ ] Code principles (SOLID, DRY)
+
+Check for conflicts between:
+
+- Root `AGENTS.md` ↔ `.claude/rules/*.md`
+- Skills ↔ Commands (e.g. `/pypi-publish` skill vs `/release` command)
+- `CLAUDE.md` ↔ `AGENTS.md` (CLAUDE.md should `@AGENTS.md`, not duplicate)
+
+```!
+head -3 CLAUDE.md
+```
+
+## 7. Skill / command frontmatter
+
+Spot-check that skill frontmatter is well-formed:
+
+```!
+for f in .claude/skills/*/SKILL.md; do echo "=== $f ==="; awk '/^---$/{c++; if(c==2) exit} c==1' "$f"; done
+```
+
+```!
+for f in .claude/commands/*.md; do echo "=== $f ==="; awk '/^---$/{c++; if(c==2) exit} c==1' "$f"; done
+```
+
+## 8. Report and fix
+
+Document any misalignments found:
+
+- [ ] Missing files → create from templates.
+- [ ] Oversized files → trim or split into path-scoped rules / supporting files.
+- [ ] Stale references → update paths.
+- [ ] Outdated tech stack → update `AGENTS.md`.
+- [ ] Conflicting guidance → resolve in favor of `AGENTS.md` and `CLAUDE.md`.
+
+If changes were made, commit:
+
+```bash
+git add .claude/ CLAUDE.md AGENTS.md \
+  && git commit -m "chore: align claude-code agentic capabilities"
+```
+
+**Run this workflow monthly or after major refactors.**

.claude/commands/code-health.md

@@ -0,0 +1,92 @@
+---
+description: Maintain code coherence, remove inconsistencies, improve readability (DRY, SOLID, SOTA)
+allowed-tools: Bash(uv run ruff *) Bash(uv run ty *) Bash(uv run pytest *) Bash(uv run coverage *)
+---
+
+# /code-health
+
+## 1. Static analysis
+
+```!
+uv run ruff check src/dppvalidator/ tests/ --fix
+```
+
+```!
+uv run ruff format src/dppvalidator/ tests/
+```
+
+## 2. Type check
+
+```!
+uv run ty check src/dppvalidator/
+```
+
+## 3. Review checklist
+
+### DRY (don't repeat yourself)
+
+- [ ] No duplicate code blocks across modules.
+- [ ] Shared logic extracted to utility functions.
+- [ ] Constants defined centrally (e.g. in config or constants module).
+- [ ] Common test fixtures in `tests/conftest.py`.
+
+### SOLID principles
+
+- [ ] **S**ingle responsibility: each validator/model has one purpose.
+- [ ] **O**pen/closed: new validators extend patterns, don't modify base.
+- [ ] **L**iskov substitution: subclasses honor parent contracts.
+- [ ] **I**nterface segregation: no forced unused dependencies.
+- [ ] **D**ependency inversion: use protocols/ABCs for abstractions.
+
+### Consistency (codebase-specific)
+
+- [ ] All modules use Pydantic v2 patterns.
+- [ ] All public functions have type hints (ty enforced).
+- [ ] All models inherit from appropriate Pydantic base.
+- [ ] Import order: stdlib → third-party → local.
+
+### Readability
+
+- [ ] Function names describe what they do.
+- [ ] Variables have meaningful names (no `x`, `temp`, `data`).
+- [ ] Complex logic has inline comments explaining *why*.
+- [ ] Max function length ~50 lines; split if larger.
+
+## 4. Find code smells
+
+```!
+uv run ruff check src/dppvalidator/ --select=C901,PLR0912,PLR0915 --statistics
+```
+
+This checks for:
+
+- `C901`: complex functions (cyclomatic complexity)
+- `PLR0912`: too many branches
+- `PLR0915`: too many statements
+
+## 5. Test coverage
+
+```!
+uv run pytest tests/ --cov=src/dppvalidator --cov-report=term-missing --cov-fail-under=80
+```
+
+## 6. Final verification
+
+```!
+uv run pytest tests/ -q
+```
+
+______________________________________________________________________
+
+## Quick reference: common refactorings
+
+| Smell               | Refactoring                                   |
+| ------------------- | --------------------------------------------- |
+| Duplicate code      | Extract to shared utility module              |
+| Long function       | Split into smaller functions                  |
+| God class           | Decompose into focused classes                |
+| Primitive obsession | Create Pydantic models in `models/`           |
+| Long parameter list | Use Pydantic config or dataclass              |
+| Magic strings       | Use `Literal` types or `Enum`                 |
+| Nested validation   | Use Pydantic validators and `model_validator` |
+| Repeated schemas    | Extract base models, use inheritance          |

.claude/commands/dev-setup.md

@@ -0,0 +1,42 @@
+---
+description: Set up the development environment with miniforge and uv
+allowed-tools: Bash(uv *) Bash(curl *) Bash(pip install uv) Bash(conda *)
+---
+
+# /dev-setup
+
+Set up a local development environment.
+
+1. Create a miniforge environment:
+
+   ```bash
+   conda create -n dppvalidator python=3.12 -y && conda activate dppvalidator
+   ```
+
+1. Install the `uv` package manager (skip if already installed):
+
+   ```!
+   command -v uv || curl -LsSf https://astral.sh/uv/install.sh | sh
+   ```
+
+   Alternative: `pip install uv`
+
+1. Install project dependencies:
+
+   ```!
+   uv sync --dev
+   ```
+
+1. Install pre-commit hooks:
+
+   ```!
+   uv run pre-commit install
+   ```
+
+1. Verify installation:
+
+   ```!
+   uv run python -c "import dppvalidator; print('Setup complete!')"
+   ```
+
+After setup, run `/lint` and `/test` to verify everything works.

.claude/commands/docs-health.md

@@ -0,0 +1,122 @@
+---
+description: Check documentation consistency; ensure README.md and mkdocs are aligned with the codebase
+allowed-tools: Bash(grep *) Bash(head *) Bash(ls *) Bash(test *) Bash(find *)
+---
+
+# /docs-health
+
+## 1. Verify mkdocs nav files exist
+
+```!
+for f in $(grep -oE '[a-z/-]+\.md' mkdocs.yml); do [ -f "docs/$f" ] || echo "MISSING: docs/$f"; done
+```
+
+## 2. Core documentation consistency
+
+Compare key information across documentation sources:
+
+| Source           | Check                                              |
+| ---------------- | -------------------------------------------------- |
+| `README.md`      | Accurate project description, install instructions |
+| `docs/index.md`  | Matches README features and quick start            |
+| `AGENTS.md`      | Tech stack reflects current dependencies           |
+| `pyproject.toml` | Version, description matches docs                  |
+
+```!
+head -20 README.md
+```
+
+```!
+grep -E "^(name|version|description)" pyproject.toml | head -5
+```
+
+## 3. Validate public API documentation
+
+```!
+grep -r "^from dppvalidator" docs/reference/ 2>/dev/null || echo "Check API docs manually"
+```
+
+```!
+grep -E "^(class|def) " src/dppvalidator/__init__.py 2>/dev/null | head -10
+```
+
+## 4. Check code examples
+
+Verify code examples in docs use current API patterns:
+
+- Import paths match actual module structure.
+- Class/function names exist in codebase.
+- Examples use Pydantic v2 syntax (not v1).
+
+```!
+grep -rh "from dppvalidator" docs/*.md docs/**/*.md 2>/dev/null | sort -u | head -10
+```
+
+```!
+grep -rh "import dppvalidator" docs/*.md docs/**/*.md 2>/dev/null | sort -u | head -5
+```
+
+## 5. Version consistency
+
+```!
+grep -E "version|0\.[0-9]" pyproject.toml docs/index.md mkdocs.yml CHANGELOG.md 2>/dev/null | head -15
+```
+
+Verify version numbers are consistent across:
+
+- [ ] `pyproject.toml` → package version
+- [ ] `docs/index.md` → schema version references
+- [ ] `CHANGELOG.md` → latest release matches `pyproject.toml`
+
+## 6. Changelog sync
+
+```!
+head -30 CHANGELOG.md
+```
+
+```!
+[ -f docs/changelog.md ] && head -5 docs/changelog.md || echo "docs/changelog.md missing"
+```
+
+Ensure `docs/changelog.md` references or includes root `CHANGELOG.md`.
+
+## 7. Links validation
+
+```!
+grep -rohE '\[.*\]\([^)]+\.md[^)]*\)' docs/*.md docs/**/*.md 2>/dev/null | head -20
+```
+
+Spot-check external links manually:
+
+- PyPI badge links
+- GitHub repo links
+- UNTP / ESPR reference links
+
+## 8. Schema reference accuracy
+
+```!
+ls -la src/dppvalidator/schemas/*.json 2>/dev/null || echo "Check schema location"
+```
+
+```!
+grep -r "0\.6\." docs/ src/ 2>/dev/null | head -10
+```
+
+## 9. Report and fix
+
+Document any inconsistencies found:
+
+- [ ] Missing nav files → create placeholder or remove from nav
+- [ ] Stale code examples → update to current API
+- [ ] Version mismatch → sync versions
+- [ ] Broken links → fix paths
+- [ ] Missing API docs → document public exports
+
+If changes were made, commit:
+
+```bash
+git add README.md docs/ CHANGELOG.md \
+  && git commit -m "docs: sync documentation with codebase"
+```
+
+Run this workflow before releases and after major API changes.