Chore/repo cleanup standards remediation

.claude/rules/python/hooks.md

@@ -79,6 +79,18 @@ the same scope; running both would warn and then block on the same condition.
 Both source/test hooks only check top-level package modules (`src/<pkg>/<name>.py`,
 excluding `__init__.py`). Nested packages are skipped.
 
+### How to swap to the warn-only reminder
+
+The default strict hook (`pre-write-src-require-test.sh`) blocks any write to
+`src/<pkg>/<module>.py` when the matching test file is missing. If you prefer a non-blocking
+reminder, swap the registration in `.claude/settings.json`:
+
+1. Locate the `PreToolUse` entry whose `command` is
+   `bash .claude/hooks/pre-write-src-require-test.sh`.
+2. Replace `pre-write-src-require-test.sh` with `pre-write-src-test-reminder.sh` in that
+   entry.
+3. Register only one at a time. Registering both produces duplicate output on every write.
+
 ## Refactor test guard (PostToolUse)
 
 | Hook | Trigger | What it does |

.github/PULL_REQUEST_TEMPLATE.md

@@ -2,6 +2,10 @@
 Thank you for opening a pull request!
 Please provide clear and complete information to help reviewers
 understand, review, and merge your changes efficiently.
+
+Tip: run `just pr-draft` from the repo root to print a Conventional-Commits title
+(e.g. chore/foo-bar → chore: foo bar) and a body with *Changes introduced* filled
+from `git log`. Use `gh pr edit` to apply, or copy into the GitHub UI.
 -->
 
 ## Summary

.gitignore

@@ -1,6 +1,9 @@
-# Local ignores
+# --------------------------------------------------------------------------
+# Local developer ignores (not enforced in CI)
+# --------------------------------------------------------------------------
 runner.sh
 full_runner.sh
+
 # ==========================================================================
 # Python Core
 # ==========================================================================
@@ -75,23 +78,11 @@ instance/
 # Scrapy stuff:
 .scrapy
 
-# Sphinx documentation
+# Sphinx / built HTML under docs/
 docs/_build/
-docs/*
-
-# Allow the freshness dashboard report to be committed.
-!docs/
-!docs/repo_file_status_report.md
-!docs/git-history-maintenance.md
-!docs/root-template-sync-policy.md
-!docs/root-template-sync-map.yaml
 
-# Copier template ships MkDocs sources under template/docs/ (must not match the rule above).
-!template/docs/
-!template/docs/**
-
-# Repo freshness dashboard (generated + committed)
-!docs/repo_file_status_report.md
+# Local scratch / moved working copies (not committed)
+temp_docs/
 
 # PyBuilder
 target/
@@ -242,8 +233,5 @@ data/
 .claude/todos/
 .claude/.refactor-edit-count
 
-# Stray root file (accidental)
-/1
-
 # Cursor Related files
 .cursor/

.vscode/settings.json

@@ -90,5 +90,14 @@
     }
   },
   "python.languageServer": "None",
-  "python.analysis.typeCheckingMode": "off"
+  "python.analysis.typeCheckingMode": "off",
+  // ============================================================
+  // macOS: silence uv "Ignoring `SSL_CERT_DIR`" when the variable
+  // points at a directory with no PEM certs (e.g. /etc/ssl/certs).
+  // Empty value lets uv use its default trust store. If you rely on
+  // a custom bundle, prefer SSL_CERT_FILE to a single PEM file instead.
+  // ============================================================
+  "terminal.integrated.env.osx": {
+    "SSL_CERT_DIR": ""
+  }
 }

CLAUDE.md

@@ -23,13 +23,17 @@ destination folder.
 ├── 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
+│   ├── test_repo_file_freshness.py  # Unit tests for repo_file_freshness.py
+│   ├── test_pr_commit_policy.py     # PR body + conventional commit rules
+│   ├── test_bump_version.py         # Version bump + pyproject I/O
+│   ├── test_sync_skip_if_exists.py  # copier.yml _skip_if_exists helpers
+│   └── test_check_root_template_sync.py  # CLI smoke (see test_root_template_sync for scenarios)
+├── scripts/                  # Automation scripts for CI or local tasks (see scripts/CLAUDE.md)
 │   ├── 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
+│   ├── pr_commit_policy.py       # PR title/body + commit message policy (CI)
+│   └── sync_skip_if_exists.py    # Sync copier.yml _skip_if_exists with template paths
 ├── .claude/                  # Claude Code hooks, commands, and rules for THIS meta-repo
 │   ├── settings.json         # Hook registrations and permission allow/deny lists
 │   ├── hooks/                # Shell hook scripts (see hooks/README.md)
@@ -58,24 +62,38 @@ Prerequisites: Python 3.11+, `uv`, `just`, `git`.
 
 | Task | Command |
 |---|---|
+| List recipes (default) | `just` or `just default` |
 | Run all tests | `just test` |
 | Run tests in parallel | `just test-parallel` |
+| Run slow tests only | `just slow` |
+| Verbose tests | `just test-verbose` |
+| Full debug test output | `just test-debug` |
+| Re-run last failed tests | `just test-lf` |
+| Stop on first test failure | `just test-first-fail` |
+| CI-style tests + coverage XML | `just test-ci` |
 | Coverage report | `just coverage` |
 | Lint | `just lint` |
 | Format | `just fmt` |
+| Format check (read-only) | `just fmt-check` |
 | Auto-fix lint issues | `just fix` |
 | Type check | `just type` |
 | Docstring check | `just docs-check` |
+| MkDocs recipes (generated projects only) | `just docs-help` |
 | Pre-merge review | `just review` |
 | Full CI locally | `just ci` |
 | Read-only CI check (no auto-fix) | `just ci-check` |
 | Static checks only (fix+fmt+lint+type+docs) | `just static_check` |
+| Run pre-commit on all files | `just precommit` |
+| Register git hooks | `just precommit-install` |
+| Interactive conventional commit (Commitizen) | `just cz-commit` |
 | Sync deps after lockfile change | `just sync` |
 | Upgrade all deps | `just update` |
 | Dependency security audit | `just audit` |
 | Install all deps + pre-commit | `just install` |
 | Diagnose environment | `just doctor` |
 | Generate freshness dashboard | `just freshness` |
+| Root ↔ template sync validation | `just sync-check` |
+| Suggested PR title + body (PR policy) | `just pr-draft` |
 | Clean build artifacts | `just clean` |
 | Build distribution | `just build` |
 | Publish package | `just publish` |