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

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

@@ -2,6 +2,20 @@
 
 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modern-python-guidance
-Version: 0.4.5
+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.5 → 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.5 → modern_python_guidance-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "modern-python-guidance"
-version = "0.4.5"
+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.5 → 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.5"
+__version__ = "0.5.0"

{modern_python_guidance-0.4.5 → 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.5 → 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.5 → 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.5 → 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:

{modern_python_guidance-0.4.5 → modern_python_guidance-0.5.0}/tests/test_guide_structure.py

@@ -18,7 +18,7 @@ from pathlib import Path
 import pytest
 
 from modern_python_guidance.frontmatter import parse_frontmatter
-from modern_python_guidance.guide_index import _code_lines, _find_guides_dir
+from modern_python_guidance.guide_index import _code_lines, _find_guides_dir, build_index
 from modern_python_guidance.setup_cmd import _build_rule_text
 
 GUIDES_DIR = _find_guides_dir()
@@ -115,12 +115,7 @@ class TestGuideStructure:
 
 
 class TestRuleFileSync:
-    """CI sync tests: rules/modern-python.md body matches SKILL.md body."""
-
-    def _skill_body(self) -> str:
-        skill_md = (GUIDES_DIR.parent / "SKILL.md").read_text(encoding="utf-8")
-        parts = skill_md.split("---", 2)
-        return parts[2].lstrip("\n")
+    """CI sync tests: rules/modern-python.md is thin and matches _build_rule_text()."""
 
     def _rule_path(self) -> Path:
         return GUIDES_DIR.parent.parent.parent / "rules" / "modern-python.md"
@@ -130,12 +125,6 @@ class TestRuleFileSync:
         parts = text.split("---", 2)
         return parts[1].strip(), parts[2].lstrip("\n")
 
-    def test_body_matches_skill(self):
-        """rules/modern-python.md body == SKILL.md body (content sync)."""
-        skill_body = self._skill_body()
-        _, rule_body = self._rule_parts()
-        assert rule_body == skill_body
-
     def test_matches_build_rule_text(self):
         """rules/modern-python.md == _build_rule_text() output (SoT enforcement)."""
         actual = self._rule_path().read_text(encoding="utf-8")
@@ -163,6 +152,23 @@ class TestRuleFileSync:
         assert "name:" not in fm
         assert "description:" not in fm
 
+    def test_thin_rule_has_guide_count(self):
+        """Thin Rules body contains correct guide count."""
+        _, body = self._rule_parts()
+        assert f"All {EXPECTED_GUIDE_COUNT} guides" in body
+
+    def test_thin_rule_has_mcp_pointer(self):
+        """Thin Rules body references MCP tool or CLI retrieve."""
+        _, body = self._rule_parts()
+        assert "retrieve_guides" in body or "mpg retrieve" in body
+
+    def test_thin_rule_has_all_guide_ids(self):
+        """Every guide ID from the registry appears in thin Rules category index."""
+        _, body = self._rule_parts()
+        index = build_index()
+        for guide_id in index.guides:
+            assert f"`{guide_id}`" in body, f"guide ID missing from thin Rules: {guide_id}"
+
 
 class TestDetectPatterns:
     def test_field_present(self, guide_file: Path):

{modern_python_guidance-0.4.5 → modern_python_guidance-0.5.0}/tests/test_setup.py

@@ -577,6 +577,21 @@ class TestRunSetup:
             assert run_setup(dry_run=True) == 0
         assert "Ready" not in capsys.readouterr().out
 
+    def test_success_shows_hook_hint(self, capsys: pytest.CaptureFixture[str]):
+        p_mcp, p_skills, p_rules = self._patch_all()
+        with p_mcp, p_skills, p_rules:
+            assert run_setup() == 0
+        out = capsys.readouterr().out
+        assert "PostToolUse" in out
+
+    def test_skills_only_shows_hook_hint(self, capsys: pytest.CaptureFixture[str]):
+        p_mcp, p_skills, p_rules = self._patch_all()
+        with p_mcp, p_skills, p_rules:
+            assert run_setup(skills_only=True) == 0
+        out = capsys.readouterr().out
+        assert "PostToolUse" in out
+        assert "Ready" not in out
+
     def test_mutual_exclusion(self, capsys: pytest.CaptureFixture[str]):
         code = run_setup(mcp_only=True, skills_only=True)
         assert code == 1

modern_python_guidance-0.4.5/rules/modern-python.md

@@ -1,70 +0,0 @@
----
-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.
-
-## When to use
-
-- Writing new Python code (use modern patterns from the start)
-- Reviewing Python code (flag outdated patterns)
-- Migrating from Pydantic V1 to V2
-- Upgrading Python version (check which new features are available)
-- Replacing legacy tooling (setup.py, flake8, pip)
-
-## Embedded patterns (high-frequency, Ruff-uncovered)
-
-### Pydantic V2 (>=3.9)
-
-- `@validator("f")` → `@field_validator("f")`
-- `@root_validator` → `@model_validator(mode="after")`
-- `class Config:` → `model_config = ConfigDict(...)`
-- `orm_mode` → `from_attributes`, `allow_population_by_field_name` → `populate_by_name`
-- `.parse_obj(d)` → `.model_validate(d)`, `.parse_raw(j)` → `.model_validate_json(j)`
-- `.dict()` → `.model_dump()`, `.json()` → `.model_dump_json()`
-- `.schema()` → `.model_json_schema()`, `.copy()` → `.model_copy()`
-
-### FastAPI (>=3.9)
-
-- `@app.on_event("startup")`/`"shutdown"` → `@asynccontextmanager` lifespan + `FastAPI(lifespan=lifespan)`; yield dict becomes `request.state`
-- `db: Session = Depends(get_db)` → `DbDep = Annotated[Session, Depends(get_db)]`; reusable type alias per PEP 593
-
-### httpx
-
-- Per-request `async with httpx.AsyncClient()` → shared `AsyncClient` with `base_url`
-  - Caveat: shared client must be closed via `async with` or lifespan management
-
-### asyncio (>=3.11)
-
-- `await asyncio.gather(a(), b())` → `async with asyncio.TaskGroup() as tg:` + `tg.create_task()`; access results via `task.result()`
-  - Caveat: 3.11+ only. `TaskGroup` cancels siblings on error and raises `ExceptionGroup`; `gather` preserves return order and supports `return_exceptions=True`
-
-### SQLAlchemy 2.0 (>=3.9)
-
-- `session.query(User).filter()` → `session.execute(select(User).where())`; use `session.scalars()` for ORM results
-- `Column(Integer)` → `Mapped[int] = mapped_column()`; type inferred from annotation, nullability from `Optional`/`| None`
-- Sync `Session` with `asyncio.to_thread` → `AsyncSession` + `create_async_engine` + `async_sessionmaker`
-
-### Toolchain
-
-- `setup.py` / `setup.cfg` → `pyproject.toml` with `[build-system]` + `[project]` (PEP 621)
-- `subprocess.run(f"cmd {arg}", shell=True)` → `subprocess.run(["cmd", arg], check=True)`
-  - Caveat: `shell=True` is valid when pipes/globs are needed; use `shlex.quote()` for user input
-
-## All 41 guides by category
-
-- **typing** (7): `use-builtin-generics`, `union-syntax`, `type-parameter-syntax`, `override-decorator`, `typeis-vs-typeguard`, `paramspec-decorators`, `deferred-annotations`
-- **async** (3): `taskgroup-over-gather`, `exception-groups`, `async-timeout-context`
-- **stdlib** (5): `datetime-utc`, `pathlib-over-os-path`, `tomllib-builtin`, `removeprefix-removesuffix`, `template-strings`
-- **data-structures** (3): `dict-merge-operator`, `match-case-patterns`, `dataclass-modern`
-- **pydantic** (4): `pydantic-v2-validators`, `pydantic-v2-config`, `pydantic-v2-model-api`, `pydantic-v2-serialization`
-- **fastapi** (3): `fastapi-lifespan`, `fastapi-annotated-depends`, `fastapi-typed-state`
-- **httpx** (2): `httpx-async-client-reuse`, `httpx-streaming`
-- **django** (3): `django-json-field`, `django-async-views`, `django-check-constraints`
-- **sqlalchemy** (3): `sqlalchemy-2-style`, `sqlalchemy-mapped-column`, `sqlalchemy-async-session`
-- **pytest** (3): `pytest-parametrize`, `pytest-tmp-path`, `pytest-raises-match`
-- **toolchain** (5): `pyproject-toml-over-setup`, `uv-over-pip`, `ruff-over-flake8`, `no-pickle`, `safe-subprocess`
-
-For full code examples, use `mpg retrieve <guide-id>` or MCP tool `retrieve_guides`.