Updated CLAUDE.md and README.md

claude · claude · commit 3a9eeebb9503 · 2026-04-13T05:31:00.000+02:00
diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md
@@ -22,6 +22,7 @@ This directory contains all Claude Code configuration for **this Copier template
 │   └── *.sh           ← individual hook scripts
 ├── commands/          ← slash command prompt files
 │   └── *.md           ← one file per slash command
+├── skills/            ← Agent skills (TDD workflow, test planner, test quality reviewer, …)
 └── rules/             ← AI coding rules
     ├── README.md      ← rule developer guide (structure, priority, dual-hierarchy)
     ├── common/        ← language-agnostic rules
@@ -57,7 +58,7 @@ for the full developer guide.
 | `pre-bash-git-push-reminder.sh` | PreToolUse | Bash | Warn to run `just review` before push |
 | `pre-bash-commit-quality.sh` | PreToolUse | Bash | Scan staged `.py` files for secrets/debug markers |
 | `pre-bash-coverage-gate.sh` | PreToolUse | Bash | Warn before `git commit` if coverage below threshold |
-| `pre-config-protection.sh` | PreToolUse | Write\|Edit\|MultiEdit | Block weakening ruff/pyright config edits |
+| `pre-config-protection.sh` | PreToolUse | Write\|Edit\|MultiEdit | Block weakening ruff/basedpyright config edits |
 | `pre-protect-uv-lock.sh` | PreToolUse | Write\|Edit | Block direct edits to `uv.lock` |
 | `pre-write-src-require-test.sh` | PreToolUse | Write\|Edit | Block if the matching test file does not exist (strict TDD) |
 | `pre-write-src-test-reminder.sh` | PreToolUse | Write\|Edit | Warn if test file missing for new source module (optional alternative to strict TDD) |
diff --git a/.claude/commands/standards.md b/.claude/commands/standards.md
@@ -6,7 +6,7 @@ This is the "am I ready to merge?" command. It runs all checks and aggregates re
 
 1. **Static analysis** — `just lint` + `just type`
    - ruff: all configured rules (E, F, I, UP, B, SIM, C4, RUF, D, C90, PERF)
-   - basedpyright: strict type checking
+   - basedpyright: `standard` mode type checking
 
 2. **Docstring coverage** — `just docs-check`
    - All public symbols have Google-style docstrings
diff --git a/.claude/hooks/README.md b/.claude/hooks/README.md
@@ -271,7 +271,7 @@ exit 0
 | `pre-bash-git-push-reminder.sh` | PreToolUse | Bash | Warn to run `just review` before push |
 | `pre-bash-commit-quality.sh` | PreToolUse | Bash | Secret/debug scan before `git commit` |
 | `pre-bash-coverage-gate.sh` | PreToolUse | Bash | Warn before `git commit` if coverage below threshold |
-| `pre-config-protection.sh` | PreToolUse | Write\|Edit\|MultiEdit | Block weakening ruff/pyright config edits |
+| `pre-config-protection.sh` | PreToolUse | Write\|Edit\|MultiEdit | Block weakening ruff/basedpyright config edits |
 | `pre-protect-uv-lock.sh` | PreToolUse | Write\|Edit | Block direct edits to `uv.lock` |
 | `pre-write-src-require-test.sh` | PreToolUse | Write\|Edit | Block if `tests/<pkg>/test_<module>.py` missing for top-level `src/<pkg>/<module>.py` (strict TDD) |
 | `pre-write-src-test-reminder.sh` | (optional) | Write\|Edit | Non-blocking alternative to `pre-write-src-require-test.sh` — **do not register both** |
diff --git a/.github/CLAUDE.md b/.github/CLAUDE.md
@@ -77,5 +77,5 @@ before pushing a tag.
 - Run `just ci` before pushing — CI must pass locally before merging.
 - After changing a workflow, check that the `sync-skip-if-exists.yml` does not need to be
   updated (it reads `copier.yml` `_skip_if_exists`).
-- When bumping GitHub Actions versions (e.g. `actions/checkout@v4`), also update the
+- When bumping GitHub Actions versions (e.g. `actions/checkout@v6`), also update the
   corresponding actions in `template/.github/workflows/` so generated projects stay current.
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -22,10 +22,12 @@ destination folder.
 │   └── …                    # pyproject.toml.jinja, justfile.jinja, CLAUDE.md.jinja, …
 ├── tests/                    # pytest tests that render the template and assert output
 │   ├── test_template.py      # Main integration suite — copier copy + assertions
+│   ├── test_root_template_sync.py   # Tests for check_root_template_sync.py
 │   └── test_repo_file_freshness.py  # Unit tests for repo_file_freshness.py script
 ├── scripts/                  # Automation scripts for CI or local tasks
 │   ├── repo_file_freshness.py    # Git-based freshness dashboard (→ docs/ + assets/)
 │   ├── bump_version.py           # PEP 440 version bumper (patch/minor/major)
+│   ├── check_root_template_sync.py  # Root ↔ template parity (workflows, settings, recipes)
 │   ├── sync_skip_if_exists.py    # Sync copier.yml _skip_if_exists with template paths
 │   └── update_files.sh           # Batch file update helper
 ├── .claude/                  # Claude Code hooks, commands, and rules for THIS meta-repo
diff --git a/README.md b/README.md
@@ -40,6 +40,7 @@ Prerequisites:
 - 🐍 Python 3.11+
 - 🌱 Git
 - 🧩 `copier`
+- 🪝 `just` (task runner — used throughout this repo and generated projects)
 
 > [!WARNING]
 > Generate from **trusted templates**: when a template uses Copier `tasks`, they run with the
@@ -141,18 +142,26 @@ Other useful commands:
 - 🧹 **`just fix`**: auto-fix lint issues
 - ✨ **`just fmt`**: format code
 - 🔍 **`just lint`**: lint check
-- 🧠 **`just type`**: type check (strict mode)
+- 🧠 **`just type`**: type check (basedpyright **standard** mode)
+- 📜 **`just docs-check`**: Google-style docstrings (ruff `D` only)
+- ✅ **`just review`**: `fix` → `lint` → `type` → `docs-check`
 - 🧪 **`just test`**: run template integration tests (renders the template and asserts output)
 - 📊 **`just coverage`**: run tests with coverage report
 - ⚡ **`just test-parallel`**: run tests in parallel (faster)
+- 🔁 **`just precommit`**: run pre-commit on all files
+- 🩺 **`just doctor`**: print toolchain and project versions
+- 🔗 **`just sync-check`**: validate root/template sync policy (`scripts/check_root_template_sync.py`)
+- 🧱 **`just static_check`**: `fix` + `lint` + `type` + `docs-check` (no tests)
+- ✋ **`just ci-check`**: read-only full gate (matches GitHub Actions lint + tests + security steps)
 
 ### Testing this template
 
-The test suite (`tests/test_template.py`) uses pytest to:
+The test suite (`tests/test_template.py`, `tests/test_root_template_sync.py`, `tests/test_repo_file_freshness.py`) uses pytest to:
 - Render the template with various configurations
 - Validate generated project structure
 - Check that generated projects have valid Python syntax
 - Verify CI/CD workflow files are valid YAML
+- Enforce root/template sync policy (`check_root_template_sync.py`)
 - Test all combinations of optional features (docs, NumPy, pandas)
 
 ## Releasing this template 🏷️
diff --git a/pyproject.toml b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "python_project_template"
-version = "0.0.7"
+version = "0.0.8"
 description = "Copier template repository for generating uv-first Python projects."
 readme = "README.md"
 requires-python = ">=3.11"
diff --git a/scripts/CLAUDE.md b/scripts/CLAUDE.md
@@ -73,6 +73,23 @@ intent of this script: no Google docstrings required, and `print()` is allowed f
 
 ---
 
+### `check_root_template_sync.py`
+
+Validates that root and `template/` stay aligned on configured paths (for example GitHub
+Actions pins, shared recipes, and other policy maps).
+
+**Invocation:** `just sync-check` → `uv run python scripts/check_root_template_sync.py`
+
+**What it does:**
+- Loads JSON policy maps under the repo (workflow action versions, justfile parity rules, etc.).
+- Compares root files to their `template/` counterparts and fails with a diff on drift.
+
+**Used by:** `.github/workflows/lint.yml` (meta-repo CI) and `just ci-check` / `just sync-check`.
+
+**Tested by:** `tests/test_root_template_sync.py`
+
+---
+
 ### `sync_skip_if_exists.py`
 
 Synchronises the `_skip_if_exists` list in `copier.yml` with the actual template file paths
diff --git a/template/.claude/commands/standards.md.jinja b/template/.claude/commands/standards.md.jinja
@@ -6,7 +6,7 @@ This is the "am I ready to merge?" command. It runs all checks and aggregates re
 
 1. **Static analysis** — `just lint` + `just type`
    - ruff: all configured rules (E, F, I, UP, B, SIM, C4, RUF, D, TCH, PGH, PT, ARG, C90, PERF)
-   - basedpyright: strict type checking
+   - basedpyright: `standard` mode type checking
 
 2. **Docstring coverage** — `just docs-check`
    - All public symbols in `src/{{ package_name }}/` have Google-style docstrings
diff --git a/template/.claude/hooks/README.md b/template/.claude/hooks/README.md
@@ -213,7 +213,7 @@ exit 0
 | `pre-bash-block-no-verify.sh` | PreToolUse | Bash | Block `git --no-verify` |
 | `pre-bash-git-push-reminder.sh` | PreToolUse | Bash | Warn to review before push |
 | `pre-bash-commit-quality.sh` | PreToolUse | Bash | Secret/debug scan before commit |
-| `pre-config-protection.sh` | PreToolUse | Write\|Edit\|MultiEdit | Block weakening ruff/pyright config |
+| `pre-config-protection.sh` | PreToolUse | Write\|Edit\|MultiEdit | Block weakening ruff/basedpyright config |
 | `pre-protect-uv-lock.sh` | PreToolUse | Write\|Edit | Block direct edits to `uv.lock` |
 | `pre-write-src-require-test.sh` | PreToolUse | Write\|Edit | Block if `tests/<pkg>/test_<module>.py` missing for top-level `src/<pkg>/<module>.py` (strict TDD) |
 | `pre-bash-coverage-gate.sh` | PreToolUse | Bash | Warn before `git commit` if coverage below threshold |
diff --git a/template/.claude/rules/python/hooks.md b/template/.claude/rules/python/hooks.md
@@ -14,7 +14,7 @@
 
 1. **ruff check** — all active rule sets including `D` (docstrings), `C90` (complexity),
    `PERF` (performance anti-patterns), `T20` / `T201` (no `print()` in app code).
-2. **basedpyright** — type correctness in strict mode.
+2. **basedpyright** — type correctness in `standard` mode (`pyproject.toml` `[tool.basedpyright]`).
 
 Example output:
 
diff --git a/template/CLAUDE.md.jinja b/template/CLAUDE.md.jinja
@@ -16,14 +16,26 @@ just precommit-install
 | Task | Command |
 |---|---|
 | Run tests | `just test` |
+| Run tests in parallel | `just test-parallel` |
 | Test coverage | `just coverage` |
 | Lint | `just lint` |
 | Format | `just fmt` |
 | Auto-fix lint | `just fix` |
 | Type check | `just type` |
 | Docstring check | `just docs-check` |
 | Pre-merge review | `just review` |
-| Full CI | `just ci` |
+| Static checks only (no tests) | `just static_check` |
+| Full CI (local mirror of `.github/workflows/ci.yml`) | `just ci` |
+| Pre-commit (all files) | `just precommit` |
+| Register git hooks | `just precommit-install` |
+| Sync deps from lockfile | `just sync` |
+| Upgrade lockfile + resync | `just update` |
+| Install pip/uv + sync + hooks | `just install` |
+| Environment diagnostics | `just doctor` |
+| Clean build/test caches | `just clean` |
+| Build sdist/wheel | `just build` |
+| Publish to PyPI | `just publish` |
+| Create `.env` from `env.example` | `just load-env` |
 {% if include_docs %}| Serve docs | `just docs-serve` |
 | Build docs | `just docs-build` |
 | Deploy docs (gh-pages) | `just docs-deploy` |
@@ -131,7 +143,7 @@ Load a skill by reading its `SKILL.md`: e.g. `.claude/skills/tdd-workflow/SKILL.
 
 A feature or fix is **done** when all of the following are true:
 
-1. `just ci` passes with zero errors (lint → types → docstrings → `test-ci` → pre-commit; matches `.github/workflows/ci.yml`).
+1. `just ci` passes with zero errors — runs `fix`, `lint`, `type`, `docs-check`, `test-ci`, and `precommit`, matching the aggregate checks enforced in `.github/workflows/ci.yml` (format/lint, typecheck, pre-commit, and test jobs).
 2. Every new public function/class/method has a Google-style docstring (Args/Returns/Raises where applicable).
 3. Every new function/method has complete type annotations (parameters + return type).
 4. At least one test case covers each new public symbol.
diff --git a/template/README.md.jinja b/template/README.md.jinja
@@ -5,7 +5,7 @@
 ## What this project includes
 
 - **uv-first workflow** with a committed lockfile (`uv.lock`)
-- **Quality gates**: ruff (format + lint), basedpyright (type checking), pytest
+- **Quality gates**: ruff (format + lint), basedpyright (type checking), pytest with coverage
 - **One-command workflows** via `just` (mirrors local/CI checks)
 {% if include_docs -%}
 - **Docs**: MkDocs site in `docs/` (`just docs-serve`, `just docs-build`)
@@ -15,6 +15,7 @@
 
 - Python {{ python_min_version }}+
 - `uv` (install from https://astral.sh/uv/)
+- `just` (task runner — https://github.com/casey/just)
 
 ## Quickstart
 
@@ -39,11 +40,13 @@ See [docs/ci.md](docs/ci.md) for more detail.
 
 ## Common commands
 
-- `just test`
-- `just fmt`
-- `just lint`
-- `just type`
-- `just ci`
+- `just test` / `just test-parallel` / `just coverage`
+- `just fmt` / `just lint` / `just fix`
+- `just type` / `just docs-check` / `just review`
+- `just static_check` (lint + types + docstrings, no tests)
+- `just ci` (full local mirror of the GitHub Actions CI workflow)
+- `just sync` / `just update` / `just precommit-install`
+- `just doctor` / `just clean` / `just build`
 {% if include_docs -%}
 - `just docs-serve` / `just docs-build`
 {%- endif %}
diff --git a/tests/CLAUDE.md b/tests/CLAUDE.md
@@ -9,6 +9,7 @@ optional features are gated properly.
 | File | Purpose |
 |---|---|
 | `test_template.py` | Main integration suite: renders the template and asserts output |
+| `test_root_template_sync.py` | Tests for `scripts/check_root_template_sync.py` |
 | `test_repo_file_freshness.py` | Unit tests for `scripts/repo_file_freshness.py` |
 
 ## How `test_template.py` works
@@ -68,6 +69,10 @@ optional features are gated properly.
 - `.pre-commit-config.yaml` contains basedpyright, ruff, detect-secrets hooks.
 - `renovate.json` is valid JSON.
 
+### Root/template sync
+- `check_root_template_sync.py` policies stay consistent with root and `template/` files
+  (workflow pins, justfile parity, etc.); covered by `test_root_template_sync.py`.
+
 ### Package structure
 - `src/<package_name>/__init__.py`, `core.py`, `common/` modules all exist.
 - `tests/<package_name>/test_core.py`, `test_support.py` exist.
diff --git a/uv.lock b/uv.lock
