Release 1.0.2: migrate hooks to prek and docs fixes

README.md

@@ -10,30 +10,33 @@ If you are looking for notebook **best practices**, **assurance**, **validation*
 ## What this package is
 `pytest-notebook-policy` is a lightweight semantic checker for notebook workflows.
 
-It focuses on enforcing notebook patterns that are easy to miss in review, such as:
+It focuses on enforcing notebook patterns that are easy to miss in review.
+
+### Patterns checked
 - `on_change` callback usage where reactivity is clearer
 - cross-cell mutation of shared objects
 - non-idempotent cell behaviour
 - mixed test/helper cells and fixture placement conventions
 
 ## Why this package exists
-marimo already gives you:
+
+### What marimo already covers
 - native notebook testing with `pytest`
 - built-in notebook linting via `marimo check` ([announcement](https://marimo.io/blog/marimo-check))
 
 `pytest-notebook-policy` is designed to complement those tools with opinionated, team-level checks tailored to a stricter “production notebook” style.
 
-In practice:
+### In practice
 - use **Ruff** for general Python quality/security
 - use **marimo check** for core notebook validity and formatting rules
 - use **pytest-notebook-policy** for extra policy checks around reactive design and notebook maintainability
 
 ## Machine-assisted coding guardrails
 `pytest-notebook-policy` is especially useful as an automated quality gate when notebooks are generated or edited by coding agents (for example Claude, Warp, Codex, or similar tools).
 
-Adding it to pre-commit and CI helps catch marimo-specific issues immediately, so agents can self-correct before code reaches review.
+Adding it to prek hooks and CI helps catch marimo-specific issues immediately, so agents can self-correct before code reaches review.
 
-Example pre-commit hook:
+Example prek hook configuration:
 
 ```yaml
 repos:
@@ -46,9 +49,9 @@ repos:
         pass_filenames: false
 ```
 
-This keeps the feedback loop short:
+### Feedback loop
 - agent proposes notebook edits
-- pre-commit/CI runs Ruff + `pytest-notebook-policy` checks
+- prek/CI runs Ruff + `pytest-notebook-policy` checks
 - agent fixes violations and retries
 
 ## Current rules
@@ -74,16 +77,16 @@ Install in a project:
 uv add --dev pytest-notebook-policy
 ```
 
-Install pre-commit hooks:
+Install prek hooks:
 
 ```shell
-uv run --with pre-commit pre-commit install
+uv run prek install
 ```
 
 Run hooks across all files:
 
 ```shell
-uv run --with pre-commit pre-commit run --all-files
+uv run prek run --all-files
 ```
 
 CI runs on push/PR using `.github/workflows/ci.yml` and executes Ruff plus the test suite.

RELEASE_NOTES.md

@@ -5,6 +5,18 @@ This project follows Semantic Versioning (`MAJOR.MINOR.PATCH`).
 ### Changed
 - No unreleased entries yet.
 
+## [1.0.2] - Hook tooling migration and docs quality fixes
+### Release intent
+- Improve local quality-gate ergonomics and documentation reliability without changing runtime policy behaviour.
+
+### Highlights
+- Migrated local hook tooling from `pre-commit` to `prek` using a dedicated `prek.toml` configuration.
+- Added `prek` as a development dependency and updated project docs/commands to use `prek`.
+- Added `just` hook helper recipes for installing and running repository hooks with `prek`.
+- Fixed README section/list formatting so key guidance renders correctly in generated docs output.
+- Removed legacy `.pre-commit-config.yaml` from the repository to avoid dual-config ambiguity.
+- Confirmed GitHub Pages deployment now runs via workflow mode with successful docs publication from `main`.
+
 ## [1.0.0] - Stable baseline + Great Docs foundation
 ### Release intent
 - Mark the first stable major release and establish a modern runtime/docs baseline for ongoing development.

ROADMAP.md

@@ -16,7 +16,7 @@ This document captures likely next steps for `pytest-notebook-policy` after the
 ## Immediate easy wins (prioritised)
 1. Improve docs for report interpretation and policy tuning workflows.
    - Why first: highest user impact for lowest implementation effort.
-2. Tighten pre-commit and CI quality gates around report regressions.
+2. Tighten prek and CI quality gates around report regressions.
    - Why second: mostly workflow configuration with fast confidence gains.
 3. Expand example notebooks and fixture coverage for real-world edge cases.
    - Why third: incremental additions that improve trust and regression safety.
@@ -49,6 +49,6 @@ This document captures likely next steps for `pytest-notebook-policy` after the
   - complements deterministic rules with human-readable improvement suggestions
 
 ## Release and ecosystem readiness
-- Tighten pre-commit and CI quality gates around report regressions.
+- Tighten prek and CI quality gates around report regressions.
 - Publish and maintain clear release notes and upgrade guidance.
 - Expand example notebooks and fixture coverage for real-world edge cases.

docs/MANUAL_NOTEBOOK_VALIDATION.md

@@ -31,7 +31,7 @@ Run policy checks directly:
 uv run pytest-notebook-quality --skip-ruff manual_checks
 ```
 
-Optional pre-commit hook (local/manual usage):
+Optional prek hook (local/manual usage):
 
 ```yaml
 repos:
@@ -47,7 +47,8 @@ repos:
 Then run:
 
 ```shell
-uv run --with pre-commit pre-commit run notebook-policy-manual --all-files
+uv run prek install
+uv run prek run notebook-policy-manual --all-files
 ```
 
 ## 2) New notebook guide (`.ipynb` and `.py`)
@@ -164,10 +165,10 @@ When stable, run on the whole manual check area:
 uv run pytest-notebook-quality --skip-ruff manual_checks
 ```
 
-If using pre-commit:
+If using prek:
 
 ```shell
-uv run --with pre-commit pre-commit run notebook-policy-manual --all-files
+uv run prek run notebook-policy-manual --all-files
 ```
 
 ### Stage D: Compliance sign-off

docs/QUICKSTART.md

@@ -215,7 +215,7 @@ Enable optional sync tooling:
 uv add --dev 'pytest-notebook-policy[sync]'
 ```
 
-## 7) Optional: pre-commit hook
+## 7) Optional: prek hook
 Example local hook:
 
 ```yaml
@@ -229,6 +229,13 @@ repos:
         pass_filenames: false
 ```
 
+Install and run hooks:
+
+```shell
+uv run prek install
+uv run prek run pytest-notebook-quality --all-files
+```
+
 ## 8) Manual validation and remediation workflow
 For a full manual testing walkthrough (including complex notebook remediation and new notebook authoring guidance for both `.ipynb` and `.py`), see:
 

docs/README.md

@@ -2,7 +2,7 @@
 This directory contains focused documentation for `pytest-notebook-policy`.
 
 ## Available docs
-- [`QUICKSTART.md`](QUICKSTART.md): install, first run, and CI/pre-commit examples.
+- [`QUICKSTART.md`](QUICKSTART.md): install, first run, and CI/prek examples.
 - [`REPORT_INTERPRETATION.md`](REPORT_INTERPRETATION.md): interpreting markdown/NBOM outputs and tuning policy profiles proportionately.
 - [`JUST_SETUP.md`](JUST_SETUP.md): using the repository's `just` recipes and where to install Just.
 - [`MANUAL_NOTEBOOK_VALIDATION.md`](MANUAL_NOTEBOOK_VALIDATION.md): manual behaviour validation, second-stage remediation checklist, and authoring guide for new `.ipynb` and marimo `.py` notebooks.

docs/blog/announcing-pytest-notebook-policy.md

@@ -14,7 +14,7 @@ The goal is simple: preserve the agility that makes notebooks powerful, while re
 
 ## Fast with confidence, not fast and fragile
 This package is designed so policy does not become a drag on delivery.
-In the same way well-configured Ruff linting rules, enforced via pre-commit hooks, enable rapid high-quality code delivery, this package is the notebook equivalent: it guides and coaches users towards better outcomes while preserving notebook velocity.
+In the same way well-configured Ruff linting rules, enforced via prek hooks, enable rapid high-quality code delivery, this package is the notebook equivalent: it guides and coaches users towards better outcomes while preserving notebook velocity.
 
 The intent is to help you **move faster confidently**, not slow you down:
 

justfile

@@ -23,6 +23,12 @@ qa:
   uv run ruff check src tests scripts
   uv run python -m pytest tests
 
+hooks-install:
+  uv run prek install
+
+hooks-run:
+  uv run prek run --all-files
+
 docs-build:
   uv run great-docs build
 

prek.toml

@@ -0,0 +1,23 @@
+[[repos]]
+repo = "local"
+
+[[repos.hooks]]
+id = "ruff-check"
+name = "ruff-check"
+entry = "uv run ruff check src tests"
+language = "system"
+pass_filenames = false
+
+[[repos.hooks]]
+id = "pytest-tests"
+name = "pytest-tests"
+entry = "uv run python -m pytest tests"
+language = "system"
+pass_filenames = false
+
+[[repos.hooks]]
+id = "pytest-report-regressions"
+name = "pytest-report-regressions"
+entry = "uv run python -m pytest tests/test_quality.py tests/test_report_regressions.py"
+language = "system"
+pass_filenames = false

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pytest-notebook-policy"
-version = "1.0.0"
+version = "1.0.2"
 description = "Pytest plugin for notebook policy and quality checks"
 readme = "README.md"
 license = "MIT"
@@ -49,6 +49,7 @@ build-backend = "uv_build"
 dev = [
     "great-docs>=0.14.0",
     "jupytext>=1.16",
+    "prek>=0.4.5",
     "pytest>=8.0",
     "ruff>=0.14.0",
 ]