diff --git a/.gitignore b/.gitignore
index a91d488..59f52dd 100644
--- a/.gitignore
+++ b/.gitignore
@@ -4,3 +4,4 @@
docs/_build
.vscode/
.idea/
+.worktrees/
diff --git a/hooks.toml b/.peter-hook.toml
similarity index 100%
rename from hooks.toml
rename to .peter-hook.toml
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 38cdede..cfa9b04 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,39 @@
All notable changes to this project will be documented in this file.
+## [5.0.0] - 2025-12-10
+
+### BREAKING CHANGES
+
+- **Configuration file renamed from `hooks.toml` to `.peter-hook.toml`**
+ - Peter-hook now searches for `.peter-hook.toml` instead of `hooks.toml`
+ - If `hooks.toml` files are detected, peter-hook will error and refuse to run
+ - Migration: Rename all `hooks.toml` files to `.peter-hook.toml`
+ - Commands affected: All commands except `version` and `license`
+
+**Migration guide:**
+
+For single configuration:
+```bash
+mv hooks.toml .peter-hook.toml
+```
+
+For monorepos with multiple configurations:
+```bash
+# Find all deprecated files
+find . -name "hooks.toml" -type f
+
+# Rename each one
+cd backend && mv hooks.toml .peter-hook.toml
+cd ../frontend && mv hooks.toml .peter-hook.toml
+```
+
+**Why this change:**
+- Follows dotfile conventions for tool configuration
+- Reduces visual clutter in repository root
+- Makes the file more discoverable as tool-specific config
+- Aligns with modern CLI tool practices
+
## [Unreleased]
### Added
diff --git a/CLAUDE.md b/CLAUDE.md
index 6220bde..57c0891 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -92,7 +92,7 @@ just bump-version patch # Bump version only (no release)
- **CLI Interface** (`src/cli/mod.rs`): Command-line interface
### Key Features
-- **Hierarchical Configuration**: Nearest `hooks.toml` file wins
+- **Hierarchical Configuration**: Nearest `.peter-hook.toml` file wins
- **Safe Parallel Execution**: Repository-modifying hooks run sequentially, read-only hooks run in parallel
- **Hook Groups**: Combine individual hooks with execution strategies
- **Cross-platform**: Rust implementation supporting macOS, Linux, Windows
@@ -333,7 +333,7 @@ Partial stderr: WARNING: Test database cleanup incomplete
### Multi-Config Group Execution Behavior
-When multiple config groups are involved (different `hooks.toml` files for different changed files), peter-hook executes them sequentially with fail-fast semantics:
+When multiple config groups are involved (different `.peter-hook.toml` files for different changed files), peter-hook executes them sequentially with fail-fast semantics:
**Execution Order:**
1. Groups are processed in the order they are resolved (typically by file path)
@@ -344,9 +344,9 @@ When multiple config groups are involved (different `hooks.toml` files for diffe
**Example Scenario:**
```
Changed files:
- - backend/api.rs → Config Group A (backend/hooks.toml)
- - frontend/app.tsx → Config Group B (frontend/hooks.toml)
- - docs/README.md → Config Group C (docs/hooks.toml)
+ - backend/api.rs → Config Group A (backend/.peter-hook.toml)
+ - frontend/app.tsx → Config Group B (frontend/.peter-hook.toml)
+ - docs/README.md → Config Group C (docs/.peter-hook.toml)
Execution flow:
Group A (backend): Run hooks → SUCCESS ✓
@@ -375,9 +375,9 @@ Template variables use `{VARIABLE_NAME}` syntax and can be used in:
- `workdir` field (working directory paths)
**Available template variables:**
-- `{HOOK_DIR}` - Directory containing the hooks.toml file
+- `{HOOK_DIR}` - Directory containing the .peter-hook.toml file
- `{REPO_ROOT}` - Git repository root directory
-- `{PROJECT_NAME}` - Name of the directory containing hooks.toml
+- `{PROJECT_NAME}` - Name of the directory containing .peter-hook.toml
- `{HOME_DIR}` - User's home directory (from $HOME)
- `{PATH}` - Current PATH environment variable
- `{WORKING_DIR}` - Current working directory
diff --git a/Cargo.lock b/Cargo.lock
index e420a19..538acec 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -377,7 +377,7 @@ version = "3.0.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "fde0e0ec90c9dfb3b4b1a0891a7dcd0e2bffde2f7efed5fe7c9bb00e5bfb915e"
dependencies = [
- "windows-sys 0.52.0",
+ "windows-sys 0.59.0",
]
[[package]]
@@ -624,7 +624,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
dependencies = [
"libc",
- "windows-sys 0.52.0",
+ "windows-sys 0.61.2",
]
[[package]]
@@ -797,6 +797,19 @@ version = "0.3.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0cc23270f6e1808e30a928bdc84dea0b9b4136a8bc82338574f23baf47bbd280"
+[[package]]
+name = "globset"
+version = "0.4.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "52dfc19153a48bde0cbd630453615c8151bce3a5adfac7a0aebfbf0a1e1f57e3"
+dependencies = [
+ "aho-corasick",
+ "bstr",
+ "log",
+ "regex-automata",
+ "regex-syntax",
+]
+
[[package]]
name = "h2"
version = "0.4.12"
@@ -1070,6 +1083,22 @@ dependencies = [
"icu_properties",
]
+[[package]]
+name = "ignore"
+version = "0.4.25"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d3d782a365a015e0f5c04902246139249abf769125006fbe7649e2ee88169b4a"
+dependencies = [
+ "crossbeam-deque",
+ "globset",
+ "log",
+ "memchr",
+ "regex-automata",
+ "same-file",
+ "walkdir",
+ "winapi-util",
+]
+
[[package]]
name = "indexmap"
version = "2.12.0"
@@ -1117,7 +1146,7 @@ checksum = "e04d7f318608d35d4b61ddd75cbdaee86b023ebe2bd5a66ee0915f0bf93095a9"
dependencies = [
"hermit-abi 0.5.2",
"libc",
- "windows-sys 0.52.0",
+ "windows-sys 0.59.0",
]
[[package]]
@@ -1379,7 +1408,7 @@ checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220"
[[package]]
name = "peter-hook"
-version = "4.0.3"
+version = "5.0.0"
dependencies = [
"anyhow",
"assert_cmd",
@@ -1390,6 +1419,7 @@ dependencies = [
"dirs",
"git2",
"glob",
+ "ignore",
"indicatif",
"mockito",
"once_cell",
@@ -1400,6 +1430,7 @@ dependencies = [
"tempfile",
"toml 0.9.8",
"wait-timeout",
+ "walkdir",
"workhelix-cli-common",
]
@@ -1542,7 +1573,7 @@ dependencies = [
"once_cell",
"socket2",
"tracing",
- "windows-sys 0.52.0",
+ "windows-sys 0.60.2",
]
[[package]]
@@ -1738,7 +1769,7 @@ dependencies = [
"errno",
"libc",
"linux-raw-sys",
- "windows-sys 0.52.0",
+ "windows-sys 0.61.2",
]
[[package]]
@@ -1800,6 +1831,15 @@ version = "1.0.20"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "28d3b2b1366ec20994f1fd18c3c594f05c5dd4bc44d8bb0c1c632c8d6829481f"
+[[package]]
+name = "same-file"
+version = "1.0.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "93fc1dc3aaa9bfed95e02e6eadabb4baf7e3078b0bd1b4d7b6b0b68378900502"
+dependencies = [
+ "winapi-util",
+]
+
[[package]]
name = "scc"
version = "2.4.0"
@@ -2139,7 +2179,7 @@ dependencies = [
"getrandom 0.3.4",
"once_cell",
"rustix",
- "windows-sys 0.52.0",
+ "windows-sys 0.61.2",
]
[[package]]
@@ -2515,6 +2555,16 @@ dependencies = [
"libc",
]
+[[package]]
+name = "walkdir"
+version = "2.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "29790946404f91d9c5d06f9874efddea1dc06c5efe94541a7d6863108e3a5e4b"
+dependencies = [
+ "same-file",
+ "winapi-util",
+]
+
[[package]]
name = "want"
version = "0.3.1"
@@ -2662,7 +2712,7 @@ version = "0.1.11"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c2a7b1c03c876122aa43f3020e6c3c3ee5c05081c9a00739faf7503aeba10d22"
dependencies = [
- "windows-sys 0.52.0",
+ "windows-sys 0.61.2",
]
[[package]]
diff --git a/Cargo.toml b/Cargo.toml
index 75e1c19..9160499 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,6 +1,6 @@
[package]
name = "peter-hook"
-version = "4.0.3"
+version = "5.0.0"
edition = "2024"
rust-version = "1.86.0"
authors = ["Peter Hook Contributors"]
@@ -27,6 +27,8 @@ serde = { version = "1.0", features = ["derive"] }
workhelix-cli-common = "0.4.1"
cargo-edit = "0.13.7"
wait-timeout = "0.2"
+walkdir = "2"
+ignore = "0.4"
diff --git a/README.md b/README.md
index 47d50a0..4602ce8 100644
--- a/README.md
+++ b/README.md
@@ -10,7 +10,7 @@ Peter Hook enables different paths within a monorepo to have their own custom gi
## Key Features
-- **🏗️ Per-File Hierarchical Resolution**: Each changed file finds its nearest `hooks.toml`, enabling true monorepo patterns with path-specific validation
+- **🏗️ Per-File Hierarchical Resolution**: Each changed file finds its nearest `.peter-hook.toml`, enabling true monorepo patterns with path-specific validation
- **⚡ Safe Parallel Execution**: Automatic parallelization of compatible hooks for 2-3x speed improvement
- **🔗 Hook Composition**: Combine individual hooks into reusable groups with dependency management
- **🛡️ Repository Safety**: File-modifying hooks never run simultaneously, preventing race conditions
@@ -88,7 +88,7 @@ install -m 0755 target/release/peter-hook ~/.local/bin/
### Basic Usage
-1. **Create a configuration file** (`hooks.toml`):
+1. **Create a configuration file** (`.peter-hook.toml`):
```toml
# Individual hooks
@@ -197,7 +197,7 @@ parallel = true # Use execution = "parallel" instead
Share and reuse hooks/groups across files, with local overrides.
```toml
-# hooks.toml (project)
+# .peter-hook.toml (project)
imports = ["../hooks.lib.toml", ".hooks/common.toml"]
[groups.pre-commit]
@@ -230,12 +230,12 @@ Peter Hook supports powerful template variables in commands, working directories
#### Built-in Variables
```toml
-{HOOK_DIR} # Directory containing the hooks.toml file
+{HOOK_DIR} # Directory containing the .peter-hook.toml file
{WORKING_DIR} # Current working directory when hook runs
{REPO_ROOT} # Git repository root directory
{HOOK_DIR_REL} # Relative path from repo root to hook directory
{WORKING_DIR_REL} # Relative path from repo root to working directory
-{PROJECT_NAME} # Name of the directory containing hooks.toml
+{PROJECT_NAME} # Name of the directory containing .peter-hook.toml
{HOME_DIR} # User's home directory
{IS_WORKTREE} # "true" or "false" - whether running in a worktree
{WORKTREE_NAME} # Name of current worktree (only available in worktrees)
@@ -345,7 +345,7 @@ Git worktrees in this repository:
Per-worktree configuration allows different branches to have different validation requirements:
```toml
-# Main repository hooks.toml - Strict validation
+# Main repository .peter-hook.toml - Strict validation
[hooks.full-test-suite]
command = "cargo test --all --release"
modifies_repository = false
@@ -362,7 +362,7 @@ execution = "parallel"
```
```toml
-# Feature branch worktree hooks.toml - Fast iteration
+# Feature branch worktree .peter-hook.toml - Fast iteration
[hooks.quick-test]
command = "cargo test --lib"
modifies_repository = false
@@ -661,7 +661,7 @@ Peter Hook implements **true per-file hierarchical resolution** where each chang
When you run a git hook (e.g., `pre-commit`), Peter Hook:
1. **Detects all changed files** from git (staged, working directory, or push range)
-2. **For each changed file**, walks up from that file's directory to find the nearest `hooks.toml`
+2. **For each changed file**, walks up from that file's directory to find the nearest `.peter-hook.toml`
3. **Checks if that config defines the requested event** (e.g., `pre-commit`)
4. **Falls back to parent configs** if the event isn't defined locally
5. **Groups files** that share the same configuration
@@ -672,23 +672,23 @@ When you run a git hook (e.g., `pre-commit`), Peter Hook:
```
/monorepo/
├── .git
-├── hooks.toml # Defines: pre-push
+├── .peter-hook.toml # Defines: pre-push
├── backend/
-│ ├── hooks.toml # Defines: pre-commit
+│ ├── .peter-hook.toml # Defines: pre-commit
│ └── api/
-│ ├── hooks.toml # Defines: pre-push
+│ ├── .peter-hook.toml # Defines: pre-push
│ └── server.rs # File A
└── frontend/
└── app.js # File B
```
**Scenario: Modify `backend/api/server.rs` (File A)**
-- **pre-commit hook**: Uses `/monorepo/backend/hooks.toml` (walks up, finds first config with pre-commit)
-- **pre-push hook**: Uses `/monorepo/backend/api/hooks.toml` (nearest config defines it)
+- **pre-commit hook**: Uses `/monorepo/backend/.peter-hook.toml` (walks up, finds first config with pre-commit)
+- **pre-push hook**: Uses `/monorepo/backend/api/.peter-hook.toml` (nearest config defines it)
**Scenario: Modify `frontend/app.js` (File B)**
-- **pre-commit hook**: Uses `/monorepo/hooks.toml` (no frontend/hooks.toml, falls back to root)
-- **pre-push hook**: Uses `/monorepo/hooks.toml` (defined at root)
+- **pre-commit hook**: Uses `/monorepo/.peter-hook.toml` (no frontend/.peter-hook.toml, falls back to root)
+- **pre-push hook**: Uses `/monorepo/.peter-hook.toml` (defined at root)
**Scenario: Modify both files simultaneously**
- Peter Hook executes hooks from **both** configs in the same commit:
@@ -702,17 +702,17 @@ If a config doesn't define the requested event, Peter Hook automatically searche
```
/monorepo/
-├── hooks.toml # Defines: pre-commit, pre-push
+├── .peter-hook.toml # Defines: pre-commit, pre-push
└── microservices/
- ├── hooks.toml # Defines: pre-commit only
+ ├── .peter-hook.toml # Defines: pre-commit only
└── auth/
└── src/
└── lib.rs
```
When `microservices/auth/src/lib.rs` is modified:
-- **pre-commit**: Uses `/monorepo/microservices/hooks.toml` (found locally)
-- **pre-push**: Uses `/monorepo/hooks.toml` (falls back to parent, `microservices/hooks.toml` doesn't define it)
+- **pre-commit**: Uses `/monorepo/microservices/.peter-hook.toml` (found locally)
+- **pre-push**: Uses `/monorepo/.peter-hook.toml` (falls back to parent, `microservices/.peter-hook.toml` doesn't define it)
### Benefits
@@ -740,25 +740,25 @@ When `microservices/auth/src/lib.rs` is modified:
### Real-World Example
```toml
-# /monorepo/hooks.toml - Repository-wide safety net
+# /monorepo/.peter-hook.toml - Repository-wide safety net
[groups.pre-push]
includes = ["security-scan", "secret-detection"]
execution = "parallel"
description = "Security checks for all code"
-# /monorepo/backend/hooks.toml - Backend quality standards
+# /monorepo/backend/.peter-hook.toml - Backend quality standards
[groups.pre-commit]
includes = ["rust-format", "rust-clippy", "rust-test"]
execution = "parallel"
description = "Rust validation pipeline"
-# /monorepo/frontend/hooks.toml - Frontend quality standards
+# /monorepo/frontend/.peter-hook.toml - Frontend quality standards
[groups.pre-commit]
includes = ["prettier", "eslint", "jest"]
execution = "parallel"
description = "JavaScript validation pipeline"
-# /monorepo/shared/hooks.toml - Library quality standards
+# /monorepo/shared/.peter-hook.toml - Library quality standards
[groups.pre-commit]
includes = ["format", "lint", "test", "doc-check", "api-compat"]
execution = "sequential"
diff --git a/VERSION b/VERSION
index aa31e71..28cbf7c 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-4.0.3
\ No newline at end of file
+5.0.0
\ No newline at end of file
diff --git a/docs/architecture.rst b/docs/architecture.rst
index 42c9e4f..7d81a0a 100644
--- a/docs/architecture.rst
+++ b/docs/architecture.rst
@@ -4,7 +4,7 @@ Architecture
Core Components
---------------
-- ``src/config/parser.rs``: Parse and validate ``hooks.toml``; supports string/array commands and execution strategies
+- ``src/config/parser.rs``: Parse and validate ``.peter-hook.toml``; supports string/array commands and execution strategies
- ``src/hooks/resolver.rs``: Find nearest config; resolve groups; apply file targeting
- ``src/hooks/dependencies.rs``: Topological sort and phase planning
- ``src/hooks/executor.rs``: Execute hooks with sequential/parallel/force-parallel strategies; enforce safety
@@ -16,7 +16,7 @@ Core Components
Execution Model
---------------
-- Resolve hooks for the requested event from the nearest ``hooks.toml``
+- Resolve hooks for the requested event from the nearest ``.peter-hook.toml``
- Compute changed files and filter hooks by ``files`` patterns (use ``--all-files`` to skip filtering)
- If dependencies exist, build an execution plan with parallel phases
- Execute hooks according to their ``execution_type`` (per-file, in-place, other)
diff --git a/docs/cli.rst b/docs/cli.rst
index d9001f3..73f971c 100644
--- a/docs/cli.rst
+++ b/docs/cli.rst
@@ -53,7 +53,7 @@ Options:
validate
^^^^^^^^
-Parse and validate the nearest ``hooks.toml``. Prints discovered hooks and groups.
+Parse and validate the nearest ``.peter-hook.toml``. Prints discovered hooks and groups.
Options:
@@ -121,7 +121,7 @@ Positional:
The generated scripts now include dynamic completions for key verbs:
- ``run`` suggests only git hook events that peter-hook knows how to install.
-- ``lint`` suggests hook and group names discovered from the nearest ``hooks.toml`` (placeholder groups are skipped).
+- ``lint`` suggests hook and group names discovered from the nearest ``.peter-hook.toml`` (placeholder groups are skipped).
.. note::
diff --git a/docs/configuration.rst b/docs/configuration.rst
index 1ca393a..c98ee75 100644
--- a/docs/configuration.rst
+++ b/docs/configuration.rst
@@ -1,7 +1,7 @@
Configuration
=============
-Peter Hook reads configuration from the nearest ``hooks.toml`` file to the current working directory. Child directories override parent configurations: the nearest file wins.
+Peter Hook reads configuration from the nearest ``.peter-hook.toml`` file to the current working directory. Child directories override parent configurations: the nearest file wins.
Hook Definition
---------------
@@ -74,7 +74,7 @@ The ``execution_type`` field controls how changed files are passed to hook comma
Working Directory Control
--------------------------
-By default, hooks run in the directory containing their ``hooks.toml`` file. Use ``run_at_root = true`` to override this and run at the repository root instead:
+By default, hooks run in the directory containing their ``.peter-hook.toml`` file. Use ``run_at_root = true`` to override this and run at the repository root instead:
.. code-block:: toml
@@ -89,11 +89,11 @@ Hook Groups
Imports (Hook Libraries)
------------------------
-You can split reusable hooks/groups into separate TOML files and import them into your project ``hooks.toml``. Use ``peter-hook validate --trace-imports`` to inspect how imports were resolved, any overrides, cycles that were skipped, and unused imports. Add ``--json`` to emit machine-readable diagnostics.
+You can split reusable hooks/groups into separate TOML files and import them into your project ``.peter-hook.toml``. Use ``peter-hook validate --trace-imports`` to inspect how imports were resolved, any overrides, cycles that were skipped, and unused imports. Add ``--json`` to emit machine-readable diagnostics.
.. code-block:: toml
- # hooks.toml
+ # .peter-hook.toml
imports = ["../hooks.lib.toml", ".hooks/common.toml"]
[groups.pre-commit]
diff --git a/docs/examples.rst b/docs/examples.rst
index 5558b9f..f85d82c 100644
--- a/docs/examples.rst
+++ b/docs/examples.rst
@@ -4,20 +4,20 @@ Examples
File Targeting
--------------
-.. literalinclude:: ../examples/file-targeting.toml
+.. literalinclude:: ../examples/.peter-hook-file-targeting.toml
:language: toml
- :caption: examples/file-targeting.toml
+ :caption: examples/.peter-hook-file-targeting.toml
Parallel Hooks
--------------
-.. literalinclude:: ../examples/parallel-hooks.toml
+.. literalinclude:: ../examples/.peter-hook-parallel.toml
:language: toml
- :caption: examples/parallel-hooks.toml
+ :caption: examples/.peter-hook-parallel.toml
Advanced Features
-----------------
-.. literalinclude:: ../examples/advanced-features.toml
+.. literalinclude:: ../examples/.peter-hook-advanced.toml
:language: toml
- :caption: examples/advanced-features.toml
+ :caption: examples/.peter-hook-advanced.toml
diff --git a/docs/file-list.md b/docs/file-list.md
index 0861686..a4fba72 100644
--- a/docs/file-list.md
+++ b/docs/file-list.md
@@ -136,7 +136,7 @@ Early validation prevents surprises at runtime. Users get immediate feedback dur
## Usage Example
```toml
-# hooks.toml
+# .peter-hook.toml
[hooks.pytest]
command = "pytest"
description = "Run Python tests only when Python files change"
diff --git a/docs/global_config.rst b/docs/global_config.rst
index c4fab12..d4c145e 100644
--- a/docs/global_config.rst
+++ b/docs/global_config.rst
@@ -48,8 +48,8 @@ With this setting enabled, you can create shared hooks in ``~/.local/peter-hook/
.. code-block:: toml
- # Any repository's hooks.toml
- imports = ["/home/user/.local/peter-hook/common-hooks.toml"]
+ # Any repository's .peter-hook.toml
+ imports = ["/home/user/.local/peter-hook/common-.peter-hook.toml"]
[hooks.format]
command = "cargo fmt"
@@ -117,11 +117,11 @@ When ``allow_local = true``, you can create a personal hook library in ``~/.loca
.. code-block:: text
~/.local/peter-hook/
- ├── rust-hooks.toml # Rust-specific hooks
- ├── python-hooks.toml # Python-specific hooks
- └── security-hooks.toml # Security scanning hooks
+ ├── rust-.peter-hook.toml # Rust-specific hooks
+ ├── python-.peter-hook.toml # Python-specific hooks
+ └── security-.peter-hook.toml # Security scanning hooks
-**Example shared hook library** (``~/.local/peter-hook/rust-hooks.toml``):
+**Example shared hook library** (``~/.local/peter-hook/rust-.peter-hook.toml``):
.. code-block:: toml
@@ -147,8 +147,8 @@ When ``allow_local = true``, you can create a personal hook library in ``~/.loca
.. code-block:: toml
- # hooks.toml in any Rust project
- imports = ["/home/user/.local/peter-hook/rust-hooks.toml"]
+ # .peter-hook.toml in any Rust project
+ imports = ["/home/user/.local/peter-hook/rust-.peter-hook.toml"]
[groups.pre-commit]
includes = ["rust-fmt", "rust-clippy", "rust-test"]
diff --git a/docs/overview.rst b/docs/overview.rst
index 6000dba..a23ed7a 100644
--- a/docs/overview.rst
+++ b/docs/overview.rst
@@ -6,7 +6,7 @@ Peter Hook enables different paths within a monorepo to have their own custom gi
Key Features
------------
-- Hierarchical configuration: nearest ``hooks.toml`` file wins
+- Hierarchical configuration: nearest ``.peter-hook.toml`` file wins
- Safe parallel execution: repository-modifying hooks never run concurrently
- Hook composition: reusable groups with execution strategies
- File targeting: run hooks only when matching files change
diff --git a/docs/plans/2025-12-10-config-rename-design.md b/docs/plans/2025-12-10-config-rename-design.md
new file mode 100644
index 0000000..13efecd
--- /dev/null
+++ b/docs/plans/2025-12-10-config-rename-design.md
@@ -0,0 +1,399 @@
+# Configuration File Rename: hooks.toml → .peter-hook.toml
+
+**Date:** 2025-12-10
+**Version:** 5.0.0 (Breaking Change)
+**Status:** Approved
+
+## Overview
+
+Rename the configuration file from `hooks.toml` to `.peter-hook.toml` as a breaking change in version 5.0.0.
+
+### Goal
+
+- Update configuration file discovery to use `.peter-hook.toml` instead of `hooks.toml`
+- Provide clear, actionable error messages when deprecated `hooks.toml` files are detected
+- Hard-fail immediately when deprecated files exist (no grace period)
+
+### Rationale
+
+The new name `.peter-hook.toml`:
+- Follows dotfile conventions for tool configuration
+- Reduces visual clutter in repository root
+- Makes the file more discoverable as tool-specific config
+- Aligns with modern CLI tool practices (e.g., `.prettierrc`, `.eslintrc`)
+
+## Implementation Strategy
+
+### 1. Core Changes
+
+**Update `find_config_file()` in `src/hooks/resolver.rs`:**
+
+```rust
+pub fn find_config_file(&self) -> Result