modern-python-guidance 0.4.4__tar.gz → 0.5.0__tar.gz

{modern_python_guidance-0.4.4 → modern_python_guidance-0.5.0}/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.5.0] — 2026-06-06
+
+### Changed
+
+- Rules file (`rules/modern-python.md`) rewritten from full content (70 lines) to thin format (~30 lines): category index with all 41 guide IDs, top-5 high-frequency one-liner patterns, and MCP/CLI call-to-action. When the Rules file freezes as a static copy in git-tracked workspaces (symlink-to-file degradation), the thin format causes minimal stale-content damage — guide IDs rarely change. Run `mpg setup` to update the Rules file. (closes #109)
+
+### Added
+
+- `mpg hook claude-post-tool-use` subcommand: PostToolUse hook that reads stdin JSON from Claude Code, checks `.py` files for outdated patterns via `check_file()`, and surfaces findings as stderr feedback (exit 2). Non-Python files, missing files, and clean files produce no output (exit 0). No jq or shell wrapper required.
+- `mpg check --quiet` flag: suppresses "No outdated patterns found." output on clean files in human format. JSON format is unaffected.
+- `mpg setup` now prints a PostToolUse hook hint after successful setup.
+- README: new "Recommended hooks" section with copy-pasteable `.claude/settings.json` example.
+- 29 new tests (1028 total).
+
+## [0.4.5] — 2026-06-06
+
+### Fixed
+
+- MCP `retrieve_guides` maxItems hardcoded to 41: replaced with `_guide_limit()` that derives the limit from actual guide count at runtime. `_get_tools()` dynamically injects `maxItems` and description into the `tools/list` schema. Adding new guides no longer requires updating `mcp_server.py`. (closes #98)
+- `docs/design.md` out of sync with v0.4.4 implementation: consolidated overlapping non-goals, added `check`/`setup`/`uninstall` to CLI architecture diagram, added `check.py`, `setup_cmd.py`, `uninstall_cmd.py`, `mcp_server.py` to module responsibility table, fixed Layer 1 guide count from 16 to 18. (closes #99)
+
+### Added
+
+- 1 new test (1000 total).
+
 ## [0.4.4] — 2026-06-05
 
 ### Added

{modern_python_guidance-0.4.4 → modern_python_guidance-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modern-python-guidance
-Version: 0.4.4
+Version: 0.5.0
 Summary: Version-aware BAD/GOOD pattern guides that help AI coding agents generate modern Python
 Project-URL: Homepage, https://github.com/yottayoshida/modern-python-guidance
 Project-URL: Repository, https://github.com/yottayoshida/modern-python-guidance
@@ -176,6 +176,34 @@ mpg list --python-version 3.9
 # Excludes: TaskGroup (3.11+), match/case (3.10+), etc.
 ```
 
+## Recommended hooks
+
+Add a [PostToolUse hook](https://docs.anthropic.com/en/docs/claude-code/hooks) to auto-check Python files whenever Claude edits them. Create or update `.claude/settings.json` in your project:
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "tool == \"Edit\" || tool == \"Write\" || tool == \"MultiEdit\"",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "mpg hook claude-post-tool-use"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+The hook reads stdin from Claude Code, checks any `.py` file for outdated patterns, and surfaces findings as inline feedback. Non-Python files and clean files produce no output.
+
+Verify with `/hooks` in Claude Code to confirm the hook is active.
+
+For manual CLI use, `mpg check --quiet <file>` provides the same check without the "no patterns found" message.
+
 ## Development
 
 ```bash

{modern_python_guidance-0.4.4 → modern_python_guidance-0.5.0}/README.md

@@ -144,6 +144,34 @@ mpg list --python-version 3.9
 # Excludes: TaskGroup (3.11+), match/case (3.10+), etc.
 ```
 
+## Recommended hooks
+
+Add a [PostToolUse hook](https://docs.anthropic.com/en/docs/claude-code/hooks) to auto-check Python files whenever Claude edits them. Create or update `.claude/settings.json` in your project:
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "tool == \"Edit\" || tool == \"Write\" || tool == \"MultiEdit\"",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "mpg hook claude-post-tool-use"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+The hook reads stdin from Claude Code, checks any `.py` file for outdated patterns, and surfaces findings as inline feedback. Non-Python files and clean files produce no output.
+
+Verify with `/hooks` in Claude Code to confirm the hook is active.
+
+For manual CLI use, `mpg check --quiet <file>` provides the same check without the "no patterns found" message.
+
 ## Development
 
 ```bash

{modern_python_guidance-0.4.4 → modern_python_guidance-0.5.0}/docs/design.md

@@ -14,16 +14,16 @@ LLMs frequently generate outdated Python patterns: `typing.List` instead of `lis
 
 ## Non-goals
 
-- Automated code transformation (this is a reference tool, not a codemod)
+- Automated code transformation / codemod (the `check` command scans for outdated patterns via regex + tokenize, but does not rewrite code)
 - Language Server Protocol integration
-- Pattern detection in source code (no AST analysis)
 
 ## Architecture
 
 ```
 ┌─────────────────────────────────────────────────────────┐
 │ CLI (cli.py)                                            │
-│  search │ retrieve │ list │ detect-version              │
+│  search │ retrieve │ list │ detect-version │ check      │
+│  setup │ uninstall                                      │
 ├─────────┴──────────┴──────┴─────────────────────────────┤
 │                                                         │
 │  ┌──────────────┐  ┌──────────────┐  ┌───────────────┐  │
@@ -67,6 +67,10 @@ LLMs frequently generate outdated Python patterns: `typing.List` instead of `lis
 | `retrieve.py` | Renders guide content as JSON with version-match flag and token estimate |
 | `version_detect.py` | Detects target Python version from `--python-version` flag, `pyproject.toml` (`requires-python`), `.python-version` file, or default (3.11) |
 | `compat.py` | `version_compatible()` using `packaging.specifiers` and `token_estimate()` (chars / 4) |
+| `check.py` | Scan a Python file for outdated patterns against guide definitions (regex + tokenize, not AST) |
+| `setup_cmd.py` | Automate MCP server registration and Agent Skills symlink creation |
+| `uninstall_cmd.py` | Reverse `mpg setup`: deregister the MCP server and remove the Skills symlink |
+| `mcp_server.py` | MCP server — JSON-RPC 2.0 over stdio, zero external dependencies |
 
 ## Guide format
 
@@ -197,7 +201,7 @@ The CLI defaults to JSON when piped and human-readable when attached to a TTY. T
 
 | Layer | Scope | Categories | Count |
 |-------|-------|-----------|-------|
-| 1 — stdlib | Python standard library | typing, async, stdlib, data-structures | 16 |
+| 1 — stdlib | Python standard library | typing, async, stdlib, data-structures | 18 |
 | 2 — frameworks | Third-party frameworks | pydantic, fastapi, httpx, django, sqlalchemy, pytest | 18 |
 | 3 — toolchain | Development tools | toolchain | 5 |
 

{modern_python_guidance-0.4.4 → modern_python_guidance-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "modern-python-guidance"
-version = "0.4.4"
+version = "0.5.0"
 description = "Version-aware BAD/GOOD pattern guides that help AI coding agents generate modern Python"
 readme = "README.md"
 license = "Apache-2.0 OR MIT"
@@ -65,6 +65,7 @@ select = ["E", "F", "W", "I", "UP", "FURB", "B", "SIM", "RUF"]
 
 [tool.ruff.lint.per-file-ignores]
 "bench/*.py" = ["SIM102", "SIM110"]
+"src/modern_python_guidance/setup_cmd.py" = ["E501"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

modern_python_guidance-0.5.0/rules/modern-python.md

@@ -0,0 +1,31 @@
+---
+paths: ["**/*.py", "*.py", "**/pyproject.toml", "**/requirements*.txt", "**/setup.py", "**/setup.cfg", "**/.python-version", "**/Pipfile"]
+---
+
+# Modern Python Guidance
+
+Pre-generation design patterns that Ruff cannot auto-fix. Apply these transformations when writing or reviewing Python code.
+
+## Embedded patterns (high-frequency, Ruff-uncovered)
+
+- `from typing import List, Dict` → `list[str]`, `dict[str, int]` (>=3.9)
+- `@validator("f")` → `@field_validator("f")` (Pydantic V2)
+- `datetime.utcnow()` → `datetime.now(UTC)` (>=3.11)
+- `session.query(User).filter()` → `session.execute(select(User).where())` (SQLAlchemy 2.0)
+- `subprocess.run(f"cmd {arg}", shell=True)` → `subprocess.run(["cmd", arg], check=True)`
+
+## All 41 guides by category
+
+- **async** (3): `async-timeout-context`, `exception-groups`, `taskgroup-over-gather`
+- **data-structures** (3): `dataclass-modern`, `dict-merge-operator`, `match-case-patterns`
+- **django** (3): `django-async-views`, `django-check-constraints`, `django-json-field`
+- **fastapi** (3): `fastapi-annotated-depends`, `fastapi-lifespan`, `fastapi-typed-state`
+- **httpx** (2): `httpx-async-client-reuse`, `httpx-streaming`
+- **pydantic** (4): `pydantic-v2-config`, `pydantic-v2-model-api`, `pydantic-v2-serialization`, `pydantic-v2-validators`
+- **pytest** (3): `pytest-parametrize`, `pytest-raises-match`, `pytest-tmp-path`
+- **sqlalchemy** (3): `sqlalchemy-2-style`, `sqlalchemy-async-session`, `sqlalchemy-mapped-column`
+- **stdlib** (5): `datetime-utc`, `pathlib-over-os-path`, `removeprefix-removesuffix`, `template-strings`, `tomllib-builtin`
+- **toolchain** (5): `no-pickle`, `pyproject-toml-over-setup`, `ruff-over-flake8`, `safe-subprocess`, `uv-over-pip`
+- **typing** (7): `deferred-annotations`, `override-decorator`, `paramspec-decorators`, `type-parameter-syntax`, `typeis-vs-typeguard`, `union-syntax`, `use-builtin-generics`
+
+For full code examples, use `mpg retrieve <guide-id>` or MCP tool `retrieve_guides`.

{modern_python_guidance-0.4.4 → modern_python_guidance-0.5.0}/src/modern_python_guidance/__init__.py

@@ -1,3 +1,3 @@
 """Modern Python Guidance — version-aware BAD/GOOD pattern guides for AI coding agents."""
 
-__version__ = "0.4.4"
+__version__ = "0.5.0"

{modern_python_guidance-0.4.4 → modern_python_guidance-0.5.0}/src/modern_python_guidance/cli.py

@@ -130,6 +130,22 @@ def main(argv: list[str] | None = None) -> None:
         action="store_true",
         help="Always exit 0 even when patterns are found",
     )
+    p_check.add_argument(
+        "--quiet",
+        action="store_true",
+        help="Suppress output when no patterns are found (human format only)",
+    )
+
+    # hook
+    p_hook = subparsers.add_parser(
+        "hook",
+        help="Claude Code hook subcommands",
+    )
+    hook_sub = p_hook.add_subparsers(dest="hook_name")
+    hook_sub.add_parser(
+        "claude-post-tool-use",
+        help="PostToolUse hook: check .py files from stdin JSON",
+    )
 
     args = parser.parse_args(argv)
 
@@ -158,6 +174,8 @@ def main(argv: list[str] | None = None) -> None:
             _cmd_uninstall(args)
         elif args.command == "check":
             _cmd_check(args)
+        elif args.command == "hook":
+            _cmd_hook(args)
     except BrokenPipeError:
         sys.exit(0)
 
@@ -341,7 +359,7 @@ def _cmd_check(args: argparse.Namespace) -> None:
 
     if fmt == "json":
         _check_json(matches, args.file)
-    else:
+    elif not (args.quiet and not matches):
         _check_human(matches)
 
     if matches and not args.exit_zero:
@@ -395,3 +413,58 @@ def _check_human(matches: list[CheckMatch]) -> None:
         f"\n{len(matches)} outdated pattern{ps} found ({unique} guide{gs}). "
         f"Run `mpg retrieve {ids}` for details."
     )
+
+
+def _cmd_hook(args: argparse.Namespace) -> None:
+    if not args.hook_name:
+        print("usage: modern-python-guidance hook <name>", file=sys.stderr)
+        print("available hooks: claude-post-tool-use", file=sys.stderr)
+        sys.exit(2)
+    if args.hook_name == "claude-post-tool-use":
+        _hook_post_tool_use()
+    else:
+        print(f"unknown hook: {args.hook_name}", file=sys.stderr)
+        print("available hooks: claude-post-tool-use", file=sys.stderr)
+        sys.exit(2)
+
+
+def _hook_post_tool_use() -> None:
+    try:
+        data = json.load(sys.stdin)
+    except (json.JSONDecodeError, ValueError):
+        sys.exit(0)
+
+    try:
+        file_path = data["tool_input"]["file_path"]
+    except (KeyError, TypeError):
+        sys.exit(0)
+
+    if not isinstance(file_path, str) or not file_path.lower().endswith(".py"):
+        sys.exit(0)
+
+    path = Path(file_path)
+    if not path.is_file():
+        sys.exit(0)
+
+    index = build_index()
+    try:
+        matches = check_file(path, index)
+    except CheckError:
+        sys.exit(0)
+
+    if not matches:
+        sys.exit(0)
+
+    for m in matches:
+        src = sanitize_line(m.source_line.strip())
+        print(
+            f"mpg: {m.guide_id} (line {m.line}): {src}",
+            file=sys.stderr,
+        )
+    guide_ids = sorted({m.guide_id for m in matches})
+    print(
+        f"mpg: {len(matches)} outdated pattern(s). "
+        f"Run `mpg retrieve {','.join(guide_ids)}` for modern alternatives.",
+        file=sys.stderr,
+    )
+    sys.exit(2)

{modern_python_guidance-0.4.4 → modern_python_guidance-0.5.0}/src/modern_python_guidance/mcp_server.py

@@ -26,6 +26,30 @@ def _get_index() -> GuideIndex:
     return _index
 
 
+def _guide_limit() -> int:
+    return len(_get_index())
+
+
+def _get_tools() -> list[dict]:
+    n = _guide_limit()
+    tools = list(TOOLS)
+    tools[1] = {
+        **TOOLS[1],
+        "inputSchema": {
+            **TOOLS[1]["inputSchema"],
+            "properties": {
+                **TOOLS[1]["inputSchema"]["properties"],
+                "guide_ids": {
+                    **TOOLS[1]["inputSchema"]["properties"]["guide_ids"],
+                    "maxItems": n,
+                    "description": f"Guide IDs to retrieve (max {n})",
+                },
+            },
+        },
+    }
+    return tools
+
+
 # --- JSON-RPC framing (newline-delimited JSON) ---
 
 
@@ -122,8 +146,7 @@ TOOLS = [
                 "guide_ids": {
                     "type": "array",
                     "items": {"type": "string"},
-                    "description": "Guide IDs to retrieve (max 41)",
-                    "maxItems": 41,
+                    "description": "Guide IDs to retrieve",
                 },
                 "python_version": {
                     "type": "string",
@@ -270,8 +293,9 @@ def _tool_retrieve(arguments: dict) -> dict:
     guide_ids = arguments.get("guide_ids", [])
     if not guide_ids:
         return _tool_result("guide_ids is required and must not be empty", is_error=True)
-    if len(guide_ids) > 41:
-        return _tool_result("guide_ids exceeds maximum of 41", is_error=True)
+    limit = _guide_limit()
+    if len(guide_ids) > limit:
+        return _tool_result(f"guide_ids exceeds maximum of {limit}", is_error=True)
 
     pv = arguments.get("python_version")
     err = _validate_python_version(pv)
@@ -371,7 +395,7 @@ def _handle_request(msg: dict) -> dict | None:
         return None if is_notification else result
 
     if method == "tools/list":
-        result = _result_response(req_id, {"tools": TOOLS})
+        result = _result_response(req_id, {"tools": _get_tools()})
         return None if is_notification else result
 
     if method == "tools/call":

{modern_python_guidance-0.4.4 → modern_python_guidance-0.5.0}/src/modern_python_guidance/setup_cmd.py

@@ -95,18 +95,40 @@ def _rules_file_path(project_dir: Path | None = None) -> Path:
     return root / ".claude" / "rules" / RULE_FILE_NAME
 
 
-def _build_rule_text() -> str:
-    """Generate rule file content from SKILL.md body with rule-specific frontmatter.
+_THIN_RULE_BODY = """\
+# Modern Python Guidance
 
-    Used by CI sync tests to verify the bundled ``rules/modern-python.md`` matches
-    what would be generated from SKILL.md. Strips SKILL.md frontmatter and prepends
-    rule-only frontmatter (no name/description keys).
-    """
-    skills_dir = _find_skills_dir()
-    skill_md = (skills_dir / "SKILL.md").read_text(encoding="utf-8")
-    parts = skill_md.split("---", 2)
-    body = parts[2].lstrip("\n")
-    return RULE_FRONTMATTER + "\n\n" + body
+Pre-generation design patterns that Ruff cannot auto-fix. Apply these transformations when writing or reviewing Python code.
+
+## Embedded patterns (high-frequency, Ruff-uncovered)
+
+- `from typing import List, Dict` → `list[str]`, `dict[str, int]` (>=3.9)
+- `@validator("f")` → `@field_validator("f")` (Pydantic V2)
+- `datetime.utcnow()` → `datetime.now(UTC)` (>=3.11)
+- `session.query(User).filter()` → `session.execute(select(User).where())` (SQLAlchemy 2.0)
+- `subprocess.run(f"cmd {arg}", shell=True)` → `subprocess.run(["cmd", arg], check=True)`
+
+## All 41 guides by category
+
+- **async** (3): `async-timeout-context`, `exception-groups`, `taskgroup-over-gather`
+- **data-structures** (3): `dataclass-modern`, `dict-merge-operator`, `match-case-patterns`
+- **django** (3): `django-async-views`, `django-check-constraints`, `django-json-field`
+- **fastapi** (3): `fastapi-annotated-depends`, `fastapi-lifespan`, `fastapi-typed-state`
+- **httpx** (2): `httpx-async-client-reuse`, `httpx-streaming`
+- **pydantic** (4): `pydantic-v2-config`, `pydantic-v2-model-api`, `pydantic-v2-serialization`, `pydantic-v2-validators`
+- **pytest** (3): `pytest-parametrize`, `pytest-raises-match`, `pytest-tmp-path`
+- **sqlalchemy** (3): `sqlalchemy-2-style`, `sqlalchemy-async-session`, `sqlalchemy-mapped-column`
+- **stdlib** (5): `datetime-utc`, `pathlib-over-os-path`, `removeprefix-removesuffix`, `template-strings`, `tomllib-builtin`
+- **toolchain** (5): `no-pickle`, `pyproject-toml-over-setup`, `ruff-over-flake8`, `safe-subprocess`, `uv-over-pip`
+- **typing** (7): `deferred-annotations`, `override-decorator`, `paramspec-decorators`, `type-parameter-syntax`, `typeis-vs-typeguard`, `union-syntax`, `use-builtin-generics`
+
+For full code examples, use `mpg retrieve <guide-id>` or MCP tool `retrieve_guides`.
+"""
+
+
+def _build_rule_text() -> str:
+    """Generate thin rule file content with category index and MCP pointer."""
+    return RULE_FRONTMATTER + "\n\n" + _THIN_RULE_BODY
 
 
 def setup_mcp(
@@ -285,8 +307,11 @@ def run_setup(
         rules_ok = setup_rules(project_dir=project_dir, dry_run=dry_run)
 
     if mcp_ok and skills_ok and rules_ok:
-        if not dry_run and do_mcp and do_skills:
-            print("Ready. Start Claude Code to use mpg guides.")
+        if not dry_run:
+            if do_mcp and do_skills:
+                print("Ready. Start Claude Code to use mpg guides.")
+            print("Tip: Add a PostToolUse hook to auto-check Python files.")
+            print("See: https://github.com/yottayoshida/modern-python-guidance#recommended-hooks")
         return 0
 
     return 1

{modern_python_guidance-0.4.4 → modern_python_guidance-0.5.0}/tests/test_cli_integration.py

@@ -250,6 +250,89 @@ class TestCheck:
         old_matches = json.loads(r_old.stdout)["summary"]["total_matches"]
         assert old_matches <= all_matches
 
+    def test_check_quiet_clean_file(self, tmp_path):
+        p = tmp_path / "clean.py"
+        p.write_text("x: list[str] = []\n")
+        r = run_cli("check", str(p), "--quiet", "--format", "human")
+        assert r.returncode == 0
+        assert r.stdout == ""
+        assert r.stderr == ""
+
+    def test_check_quiet_with_matches(self, tmp_path):
+        p = tmp_path / "bad.py"
+        p.write_text("from typing import List\n")
+        r = run_cli("check", str(p), "--quiet", "--format", "human")
+        assert r.returncode == 1
+        assert "outdated pattern" in r.stdout
+
+
+class TestHook:
+    def _run_hook(self, stdin_data: str) -> subprocess.CompletedProcess[str]:
+        return subprocess.run(
+            [*BIN, "hook", "claude-post-tool-use"],
+            input=stdin_data,
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+
+    def test_hook_py_with_matches(self, tmp_path):
+        p = tmp_path / "bad.py"
+        p.write_text("from typing import List\n")
+        stdin = json.dumps({"tool_input": {"file_path": str(p)}})
+        r = self._run_hook(stdin)
+        assert r.returncode == 2
+        assert "mpg:" in r.stderr
+        assert r.stdout == ""
+
+    def test_hook_py_clean(self, tmp_path):
+        p = tmp_path / "clean.py"
+        p.write_text("x: list[str] = []\n")
+        stdin = json.dumps({"tool_input": {"file_path": str(p)}})
+        r = self._run_hook(stdin)
+        assert r.returncode == 0
+        assert r.stdout == ""
+        assert r.stderr == ""
+
+    def test_hook_non_py(self, tmp_path):
+        p = tmp_path / "file.js"
+        p.write_text("const x = 1;\n")
+        stdin = json.dumps({"tool_input": {"file_path": str(p)}})
+        r = self._run_hook(stdin)
+        assert r.returncode == 0
+
+    def test_hook_missing_file(self):
+        stdin = json.dumps({"tool_input": {"file_path": "/nonexistent/test.py"}})
+        r = self._run_hook(stdin)
+        assert r.returncode == 0
+
+    def test_hook_malformed_json(self):
+        r = self._run_hook("{bad json")
+        assert r.returncode == 0
+
+    def test_hook_missing_keys(self):
+        r = self._run_hook(json.dumps({"other": "data"}))
+        assert r.returncode == 0
+
+    def test_hook_uppercase_py(self, tmp_path):
+        p = tmp_path / "bad.PY"
+        p.write_text("from typing import List\n")
+        stdin = json.dumps({"tool_input": {"file_path": str(p)}})
+        r = self._run_hook(stdin)
+        assert r.returncode == 2
+        assert "mpg:" in r.stderr
+
+    def test_hook_bare_no_subcommand(self):
+        r = subprocess.run(
+            [*BIN, "hook"],
+            input="",
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        assert r.returncode == 2
+        assert "available hooks" in r.stderr
+
 
 class TestVersion:
     def test_version_flag(self):

{modern_python_guidance-0.4.4 → modern_python_guidance-0.5.0}/tests/test_cli_unit.py

@@ -223,6 +223,110 @@ class TestCmdDetectVersion:
         assert out  # should return some version string
 
 
+class TestCmdCheck:
+    def test_json_output(self, tmp_path, capsys):
+        p = tmp_path / "bad.py"
+        p.write_text("from typing import List\n")
+        with pytest.raises(SystemExit, match="1"):
+            main(argv=["check", str(p), "--format", "json"])
+        data = json.loads(capsys.readouterr().out)
+        assert data["summary"]["total_matches"] >= 1
+
+    def test_human_output(self, tmp_path, capsys):
+        p = tmp_path / "bad.py"
+        p.write_text("from typing import List\n")
+        with pytest.raises(SystemExit, match="1"):
+            main(argv=["check", str(p), "--format", "human"])
+        assert "outdated pattern" in capsys.readouterr().out
+
+    def test_clean_file(self, tmp_path, capsys):
+        p = tmp_path / "clean.py"
+        p.write_text("x: list[str] = []\n")
+        main(argv=["check", str(p), "--format", "human"])
+        assert "No outdated patterns" in capsys.readouterr().out
+
+    def test_file_not_found(self, tmp_path, capsys):
+        with pytest.raises(SystemExit, match="2"):
+            main(argv=["check", str(tmp_path / "gone.py"), "--format", "json"])
+
+    def test_quiet_suppresses_clean(self, tmp_path, capsys):
+        p = tmp_path / "clean.py"
+        p.write_text("x: list[str] = []\n")
+        main(argv=["check", str(p), "--quiet", "--format", "human"])
+        captured = capsys.readouterr()
+        assert captured.out == ""
+
+    def test_exit_zero(self, tmp_path, capsys):
+        p = tmp_path / "bad.py"
+        p.write_text("from typing import List\n")
+        main(argv=["check", str(p), "--exit-zero", "--format", "json"])
+        data = json.loads(capsys.readouterr().out)
+        assert data["summary"]["total_matches"] >= 1
+
+
+class TestCmdHook:
+    def test_bare_hook_exits_2(self, capsys):
+        with pytest.raises(SystemExit, match="2"):
+            main(argv=["hook"])
+        assert "available hooks" in capsys.readouterr().err
+
+    def test_unknown_hook_exits_2(self, capsys):
+        with pytest.raises(SystemExit, match="2"):
+            main(argv=["hook", "nonexistent"])
+        assert "invalid choice" in capsys.readouterr().err
+
+    def test_post_tool_use_py_match(self, tmp_path, capsys, monkeypatch):
+        p = tmp_path / "bad.py"
+        p.write_text("from typing import List\n")
+        import io
+
+        stdin_data = json.dumps({"tool_input": {"file_path": str(p)}})
+        monkeypatch.setattr("sys.stdin", io.StringIO(stdin_data))
+        with pytest.raises(SystemExit, match="2"):
+            main(argv=["hook", "claude-post-tool-use"])
+        assert "mpg:" in capsys.readouterr().err
+
+    def test_post_tool_use_py_clean(self, tmp_path, monkeypatch):
+        p = tmp_path / "clean.py"
+        p.write_text("x: list[str] = []\n")
+        import io
+
+        stdin_data = json.dumps({"tool_input": {"file_path": str(p)}})
+        monkeypatch.setattr("sys.stdin", io.StringIO(stdin_data))
+        with pytest.raises(SystemExit, match="0"):
+            main(argv=["hook", "claude-post-tool-use"])
+
+    def test_post_tool_use_non_py(self, monkeypatch):
+        import io
+
+        stdin_data = json.dumps({"tool_input": {"file_path": "/tmp/x.js"}})
+        monkeypatch.setattr("sys.stdin", io.StringIO(stdin_data))
+        with pytest.raises(SystemExit, match="0"):
+            main(argv=["hook", "claude-post-tool-use"])
+
+    def test_post_tool_use_malformed(self, monkeypatch):
+        import io
+
+        monkeypatch.setattr("sys.stdin", io.StringIO("{bad"))
+        with pytest.raises(SystemExit, match="0"):
+            main(argv=["hook", "claude-post-tool-use"])
+
+    def test_post_tool_use_missing_keys(self, monkeypatch):
+        import io
+
+        monkeypatch.setattr("sys.stdin", io.StringIO(json.dumps({"x": 1})))
+        with pytest.raises(SystemExit, match="0"):
+            main(argv=["hook", "claude-post-tool-use"])
+
+    def test_post_tool_use_missing_file(self, monkeypatch):
+        import io
+
+        stdin_data = json.dumps({"tool_input": {"file_path": "/nonexistent/z.py"}})
+        monkeypatch.setattr("sys.stdin", io.StringIO(stdin_data))
+        with pytest.raises(SystemExit, match="0"):
+            main(argv=["hook", "claude-post-tool-use"])
+
+
 class TestCmdSetupUninstall:
     def test_setup_dispatch(self):
         with patch("modern_python_guidance.setup_cmd.run_setup", return_value=0) as mock: