modern-python-guidance 0.1.1__tar.gz → 0.2.0__tar.gz

{modern_python_guidance-0.1.1 → modern_python_guidance-0.2.0}/.gitignore

@@ -26,3 +26,5 @@ venv/
 *.swp
 *.swo
 .DS_Store
+
+results/

{modern_python_guidance-0.1.1 → modern_python_guidance-0.2.0}/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.2.0] — 2026-05-27
+
+### Added
+
+- 9 new Layer 2 guides: Django (`django-json-field`, `django-async-views`, `django-check-constraints`), SQLAlchemy (`sqlalchemy-2-style`, `sqlalchemy-mapped-column`, `sqlalchemy-async-session`), pytest (`pytest-parametrize`, `pytest-tmp-path`, `pytest-raises-match`)
+- SQLAlchemy 2.0 embedded patterns in SKILL.md (zero Ruff overlap)
+
+### Changed
+
+- Guide count: 30 → 39. Layer 2 coverage: 30% (9/30) → 46% (18/39)
+- MCP server `retrieve_guides` max items: 30 → 39
+- SKILL.md description trigger keywords: added "django", "sqlalchemy", "pytest"
+
+## [0.1.2] — 2026-05-26
+
+### Changed
+
+- SKILL.md: replace inventory tables with 9 embedded BAD→GOOD arrow-list patterns (high-frequency × Ruff-uncovered) for pre-generation injection without MCP tool calls
+- README: Quick start example changed from `use-builtin-generics` to `pydantic-v2-validators` (Layer 2 differentiation)
+
+### Added
+
+- MIT license (dual-licensed under Apache-2.0 OR MIT)
+- `test_skill_sync.py`: 8 sync tests for SKILL.md ↔ guide file consistency (V-001/V-002/V-009/V-010)
+
 ## [0.1.1] — 2026-05-25
 
 ### Added
@@ -30,5 +55,7 @@ Initial release.
 - Strict YAML-subset frontmatter parser (no PyYAML dependency)
 - GitHub Actions CI (pytest + ruff on Python 3.11, 3.12, 3.13)
 
+[0.2.0]: https://github.com/yottayoshida/modern-python-guidance/releases/tag/v0.2.0
+[0.1.2]: https://github.com/yottayoshida/modern-python-guidance/releases/tag/v0.1.2
 [0.1.1]: https://github.com/yottayoshida/modern-python-guidance/releases/tag/v0.1.1
 [0.1.0]: https://github.com/yottayoshida/modern-python-guidance/releases/tag/v0.1.0

modern_python_guidance-0.2.0/LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Iori Yoshida
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{modern_python_guidance-0.1.1 → modern_python_guidance-0.2.0}/PKG-INFO

@@ -1,18 +1,20 @@
 Metadata-Version: 2.4
 Name: modern-python-guidance
-Version: 0.1.1
+Version: 0.2.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
 Project-URL: Issues, https://github.com/yottayoshida/modern-python-guidance/issues
 Author-email: Iori Yoshida <i.yoshida@raksul.com>
-License-Expression: Apache-2.0
+License-Expression: Apache-2.0 OR MIT
 License-File: LICENSE
+License-File: LICENSE-MIT
 Keywords: ai,coding-agent,guidance,linter,modernization,python
 Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
+Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -34,7 +36,7 @@ Description-Content-Type: text/markdown
 [![Python](https://img.shields.io/pypi/pyversions/modern-python-guidance.svg)](https://pypi.org/project/modern-python-guidance/)
 [![License](https://img.shields.io/github/license/yottayoshida/modern-python-guidance.svg)](LICENSE)
 
-LLMs often produce outdated Python — `typing.List` instead of `list`, `@validator` instead of `@field_validator`, `setup.py` instead of `pyproject.toml`. This tool provides 30 version-aware BAD/GOOD pattern guides that show the modern replacement, filtered by your project's Python version.
+LLMs often produce outdated Python — `typing.List` instead of `list`, `@validator` instead of `@field_validator`, `setup.py` instead of `pyproject.toml`. This tool provides 39 version-aware BAD/GOOD pattern guides that show the modern replacement, filtered by your project's Python version.
 
 > **Note:** The tool itself requires Python 3.11+ to run. Guides cover patterns from Python 3.9 onward, and `--python-version` filters guides for your target environment.
 
@@ -45,17 +47,17 @@ LLMs often produce outdated Python — `typing.List` instead of `list`, `@valida
 pip install modern-python-guidance
 
 # Search for a pattern
-mpg search "typing list"
-#   use-builtin-generics                     score=18.0  [typing]
+mpg search "pydantic validator"
+#   pydantic-v2-validators                   score=18.0  [pydantic]
 
 # Get the full guide
-mpg retrieve use-builtin-generics
-# --- use-builtin-generics (version match: YES) ---
+mpg retrieve pydantic-v2-validators
+# --- pydantic-v2-validators (version match: YES) ---
 # ## BAD
-# from typing import List, Dict, Optional
+# @validator("name")
 # ...
 # ## GOOD
-# names: list[str] = []
+# @field_validator("name")
 # ...
 ```
 
@@ -85,15 +87,15 @@ mpg search "typing" --format json | jq '.[0].id'
 
 ## Guide coverage
 
-30 guides across 3 layers:
+39 guides across 3 layers:
 
 | Layer | Categories | Count | Examples |
 |-------|-----------|-------|---------|
 | **1 — stdlib** | typing, async, stdlib, data-structures | 16 | `list` over `List`, `match`/`case`, `TaskGroup` |
-| **2 — frameworks** | pydantic, fastapi, httpx | 9 | Pydantic V2 migration, `Annotated[Depends]`, `AsyncClient` |
+| **2 — frameworks** | pydantic, fastapi, httpx, django, sqlalchemy, pytest | 18 | Pydantic V2 migration, SQLAlchemy 2.0 style, `Annotated[Depends]` |
 | **3 — toolchain** | toolchain | 5 | `uv` over `pip`, `ruff` over flake8, `pickle` avoidance |
 
-Run `mpg list` to see all 30 guides, or [browse them on GitHub](skills/modern-python-guidance/guides/).
+Run `mpg list` to see all 39 guides, or [browse them on GitHub](skills/modern-python-guidance/guides/).
 
 ## Version-aware filtering
 
@@ -184,7 +186,7 @@ src/modern_python_guidance/
 
 skills/modern-python-guidance/
 ├── SKILL.md            # Agent Skills plugin entry point
-└── guides/             # 30 guide files by category
+└── guides/             # 39 guide files by category
 ```
 
 See [docs/design.md](docs/design.md) for the full design document.
@@ -212,4 +214,4 @@ Contributions welcome! To add a new guide:
 
 ## License
 
-Apache-2.0 — see [LICENSE](LICENSE).
+Apache-2.0 OR MIT — see [LICENSE](LICENSE) and [LICENSE-MIT](LICENSE-MIT).

{modern_python_guidance-0.1.1 → modern_python_guidance-0.2.0}/README.md

@@ -5,7 +5,7 @@
 [![Python](https://img.shields.io/pypi/pyversions/modern-python-guidance.svg)](https://pypi.org/project/modern-python-guidance/)
 [![License](https://img.shields.io/github/license/yottayoshida/modern-python-guidance.svg)](LICENSE)
 
-LLMs often produce outdated Python — `typing.List` instead of `list`, `@validator` instead of `@field_validator`, `setup.py` instead of `pyproject.toml`. This tool provides 30 version-aware BAD/GOOD pattern guides that show the modern replacement, filtered by your project's Python version.
+LLMs often produce outdated Python — `typing.List` instead of `list`, `@validator` instead of `@field_validator`, `setup.py` instead of `pyproject.toml`. This tool provides 39 version-aware BAD/GOOD pattern guides that show the modern replacement, filtered by your project's Python version.
 
 > **Note:** The tool itself requires Python 3.11+ to run. Guides cover patterns from Python 3.9 onward, and `--python-version` filters guides for your target environment.
 
@@ -16,17 +16,17 @@ LLMs often produce outdated Python — `typing.List` instead of `list`, `@valida
 pip install modern-python-guidance
 
 # Search for a pattern
-mpg search "typing list"
-#   use-builtin-generics                     score=18.0  [typing]
+mpg search "pydantic validator"
+#   pydantic-v2-validators                   score=18.0  [pydantic]
 
 # Get the full guide
-mpg retrieve use-builtin-generics
-# --- use-builtin-generics (version match: YES) ---
+mpg retrieve pydantic-v2-validators
+# --- pydantic-v2-validators (version match: YES) ---
 # ## BAD
-# from typing import List, Dict, Optional
+# @validator("name")
 # ...
 # ## GOOD
-# names: list[str] = []
+# @field_validator("name")
 # ...
 ```
 
@@ -56,15 +56,15 @@ mpg search "typing" --format json | jq '.[0].id'
 
 ## Guide coverage
 
-30 guides across 3 layers:
+39 guides across 3 layers:
 
 | Layer | Categories | Count | Examples |
 |-------|-----------|-------|---------|
 | **1 — stdlib** | typing, async, stdlib, data-structures | 16 | `list` over `List`, `match`/`case`, `TaskGroup` |
-| **2 — frameworks** | pydantic, fastapi, httpx | 9 | Pydantic V2 migration, `Annotated[Depends]`, `AsyncClient` |
+| **2 — frameworks** | pydantic, fastapi, httpx, django, sqlalchemy, pytest | 18 | Pydantic V2 migration, SQLAlchemy 2.0 style, `Annotated[Depends]` |
 | **3 — toolchain** | toolchain | 5 | `uv` over `pip`, `ruff` over flake8, `pickle` avoidance |
 
-Run `mpg list` to see all 30 guides, or [browse them on GitHub](skills/modern-python-guidance/guides/).
+Run `mpg list` to see all 39 guides, or [browse them on GitHub](skills/modern-python-guidance/guides/).
 
 ## Version-aware filtering
 
@@ -155,7 +155,7 @@ src/modern_python_guidance/
 
 skills/modern-python-guidance/
 ├── SKILL.md            # Agent Skills plugin entry point
-└── guides/             # 30 guide files by category
+└── guides/             # 39 guide files by category
 ```
 
 See [docs/design.md](docs/design.md) for the full design document.
@@ -183,4 +183,4 @@ Contributions welcome! To add a new guide:
 
 ## License
 
-Apache-2.0 — see [LICENSE](LICENSE).
+Apache-2.0 OR MIT — see [LICENSE](LICENSE) and [LICENSE-MIT](LICENSE-MIT).

modern_python_guidance-0.2.0/bench/prompt-v2.txt

@@ -0,0 +1,11 @@
+Write the following 5 files. Write all code, no placeholders. Create each file at the EXACT path shown below (relative to the current working directory). Do NOT create any project directories or subdirectories beyond what is listed.
+
+1. src/config.py — A typed configuration loader. Define a generic container class `Registry[T]` that stores items by name and retrieves them with type safety. Write a function `load_config(path)` that reads a TOML file and returns a dict.
+
+2. src/crawler.py — An async web crawler. Write an async function `crawl(urls: list[str])` that fetches multiple URLs concurrently using httpx, with a 10-second timeout per request. If a request fails, retry up to 3 times. Return a list of response bodies.
+
+3. src/app.py — A FastAPI application with: a database connection pool initialized at startup and closed at shutdown (use SQLAlchemy async with aiosqlite), a dependency that provides a database session, CRUD endpoints for a User model (GET /users, GET /users/{id}, POST /users), and an OAuth2-protected endpoint GET /users/me that requires the "users:read" scope.
+
+4. src/scanner.py — A file scanner. Write a function `scan_directory(root: Path)` that walks a directory tree recursively, collects all files, groups them into batches of 10, and processes each batch. Define an enum `FileCategory` with values IMAGE, VIDEO, DOCUMENT, OTHER. Use a match statement to categorize each file by its extension (.jpg/.png → IMAGE, .mp4/.avi → VIDEO, .pdf/.docx → DOCUMENT, everything else → OTHER).
+
+5. pyproject.toml — Project config with dependencies on fastapi, sqlalchemy[asyncio], aiosqlite, httpx, and uvicorn, supporting Python 3.12+.

modern_python_guidance-0.2.0/bench/prompt-v3.txt

@@ -0,0 +1,11 @@
+Write the following 5 files. Write all code, no placeholders. Create each file at the EXACT path shown below (relative to the current working directory). Do NOT create any project directories or subdirectories beyond what is listed.
+
+1. src/config.py — A typed configuration loader. Define a generic container class `Registry[T]` that stores items by name and retrieves them with type safety. Write a function `load_config(path)` that reads a TOML file and returns a dict. Include a `created_at` timestamp field (UTC) in the registry entries.
+
+2. src/crawler.py — A web crawler. Write a function `crawl(urls: list[str])` that fetches a list of URLs using httpx and returns their response bodies. Handle failures gracefully — a single bad URL should not lose the other results.
+
+3. src/app.py — A FastAPI application with SQLAlchemy and a database. It should have: a User model with CRUD endpoints (GET /users, GET /users/{id}, POST /users), an OAuth2-protected endpoint GET /users/me that requires the "users:read" scope, and proper database lifecycle management.
+
+4. src/scanner.py — A file scanner. Write a function `scan_directory(root: Path)` that walks a directory tree recursively, collects all files, groups them into batches of 10, and processes each batch. Define an enum `FileCategory` with values IMAGE, VIDEO, DOCUMENT, OTHER. Use a match statement to categorize each file by its extension (.jpg/.png → IMAGE, .mp4/.avi → VIDEO, .pdf/.docx → DOCUMENT, everything else → OTHER).
+
+5. pyproject.toml — Project config with dependencies on fastapi, sqlalchemy, httpx, and uvicorn, supporting Python 3.12+.

modern_python_guidance-0.2.0/bench/prompt.txt

@@ -0,0 +1,13 @@
+Write the following 6 files. Write all code, no placeholders. Create each file at the EXACT path shown below (relative to the current working directory). Do NOT create any project directories or subdirectories beyond what is listed.
+
+1. src/models.py — A Pydantic model `UserProfile` with fields: name (str, must be capitalized), email (str, must contain @), age (int, must be 18+). Add a validator for each field. Include a Config class that enables ORM mode and allows population by field name. Add a method that returns the model as a dictionary. Also add a model `Order` with fields: id (int), items (list of str), total (float).
+
+2. src/serialization.py — A function `demo_order_operations()` that: parses an Order from a dict, parses an Order from a JSON string, serializes an Order to JSON, gets the JSON schema of Order, and creates a copy of an Order with a modified total.
+
+3. src/app.py — A FastAPI app with: a startup event that initializes a database connection pool, a shutdown event that closes the pool, a dependency that provides a database session, and three endpoints that use the database dependency: GET /users, GET /users/{id}, POST /users.
+
+4. src/fetcher.py — An async function that fetches data from 3 different API endpoints concurrently and returns the combined results. Use httpx for HTTP requests. Handle timeouts and errors gracefully.
+
+5. src/runner.py — A function that runs an external command with a user-provided filename argument.
+
+6. pyproject.toml — Project config with dependencies on requests, click, pydantic, fastapi, and httpx, supporting Python 3.11+.

modern_python_guidance-0.2.0/bench/run.sh

@@ -0,0 +1,242 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Effectiveness Benchmark: A/B test for SKILL.md pre-generation guidance
+# Usage:
+#   ./bench/run.sh <run_id> control    — Run Session A (skill disabled)
+#   ./bench/run.sh <run_id> treatment  — Run Session B (skill enabled)
+#   ./bench/run.sh <run_id> both       — Run A then B sequentially
+
+REPO_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+WORKSPACE="$HOME/claude_workspace"
+RUN_ID="${1:?Usage: $0 <run_id> <control|treatment|both>}"
+SESSION="${2:?Usage: $0 <run_id> <control|treatment|both>}"
+RESULTS_DIR="$REPO_DIR/results/run-${RUN_ID}"
+# Switch prompt version: prompt.txt (v1), prompt-v2.txt (v2), prompt-v3.txt (v3)
+PROMPT_FILE="$REPO_DIR/bench/prompt-v3.txt"
+BUDGET="2.00"
+
+GEN_SRC="$WORKSPACE/src"
+GEN_PYPROJECT="$WORKSPACE/pyproject.toml"
+
+# --- Guidance toggle: rules/ file (not skills/) ---
+# Skills body is NOT loaded in pipe mode (claude -p). Only description is visible.
+# Rules files (.claude/rules/*.md) without paths: are always loaded into system prompt.
+# Toggle by adding/removing the rules file.
+RULE_FILE="$WORKSPACE/.claude/rules/modern-python.md"
+RULE_SOURCE="$REPO_DIR/skills/modern-python-guidance/SKILL.md"
+
+disable_guidance() {
+    rm -f "$RULE_FILE"
+}
+
+enable_guidance() {
+    if [ ! -f "$RULE_FILE" ]; then
+        # Copy body only (strip YAML frontmatter between --- markers)
+        awk 'BEGIN{c=0} /^---$/{c++; next} c>=2{print}' "$RULE_SOURCE" > "$RULE_FILE"
+    fi
+}
+
+restore_guidance_on_exit() {
+    enable_guidance
+    echo "[cleanup] Rules file restored."
+}
+
+# --- Verification logging ---
+record_verify() {
+    local label="$1"
+    local log="$RESULTS_DIR/guidance-verify.log"
+
+    echo "=== $label $(date -u '+%Y-%m-%dT%H:%M:%SZ') ===" >> "$log"
+
+    # Rules file state (primary toggle mechanism)
+    echo "RULE_FILE=$RULE_FILE" >> "$log"
+    if [ -f "$RULE_FILE" ]; then
+        echo "status: PRESENT ($(wc -c < "$RULE_FILE") bytes)" >> "$log"
+        echo "first_line: $(head -1 "$RULE_FILE")" >> "$log"
+    else
+        echo "status: ABSENT" >> "$log"
+    fi
+
+    # Check for other rules that might contain Python guidance
+    echo "--- all rules files ---" >> "$log"
+    ls "$WORKSPACE/.claude/rules/" 2>/dev/null | grep -v '^\.' >> "$log" || echo "(empty)" >> "$log"
+
+    echo "" >> "$log"
+}
+
+# --- Workspace cleanup ---
+cleanup_generated() {
+    local dest="$1"
+    mkdir -p "$dest"
+
+    # Primary: files at $WORKSPACE/src/
+    if [ -d "$GEN_SRC" ]; then
+        mv "$GEN_SRC" "$dest/src"
+        [ -f "$GEN_PYPROJECT" ] && mv "$GEN_PYPROJECT" "$dest/pyproject.toml"
+    else
+        # Fallback: CC may create a project subdirectory
+        local found_dir
+        found_dir=$(find "$WORKSPACE" -maxdepth 2 -name "models.py" -path "*/src/models.py" \
+            -newer "$RESULTS_DIR" -not -path "*/.venv/*" -not -path "*/modern-python-guidance/*" \
+            -not -path "*/__bench_backup*" 2>/dev/null | head -1)
+        if [ -n "$found_dir" ]; then
+            local project_dir
+            project_dir=$(dirname "$(dirname "$found_dir")")
+            echo "[fallback] Found generated files in $project_dir"
+            [ -d "$project_dir/src" ] && mv "$project_dir/src" "$dest/src"
+            [ -f "$project_dir/pyproject.toml" ] && mv "$project_dir/pyproject.toml" "$dest/pyproject.toml"
+            rmdir "$project_dir" 2>/dev/null || true
+        else
+            echo "[warning] No generated files found to capture"
+            return
+        fi
+    fi
+
+    # Sweep: capture any other generated files at workspace root
+    # (CC may create __init__.py, README.md, requirements.txt etc.)
+    local sweep_dir="$dest/extra"
+    for f in "$WORKSPACE"/__init__.py "$WORKSPACE"/README.md "$WORKSPACE"/requirements.txt \
+             "$WORKSPACE"/setup.py "$WORKSPACE"/setup.cfg; do
+        if [ -f "$f" ] && [ "$f" -nt "$RESULTS_DIR" ]; then
+            mkdir -p "$sweep_dir"
+            mv "$f" "$sweep_dir/"
+            echo "[sweep] Captured extra file: $(basename "$f")"
+        fi
+    done
+
+    # Also remove leftover pyproject.toml if not already moved
+    [ -f "$GEN_PYPROJECT" ] && mv "$GEN_PYPROJECT" "$dest/pyproject.toml" 2>/dev/null || true
+}
+
+# --- Session runners ---
+run_control() {
+    echo ""
+    echo "--- Session A: Control (guidance DISABLED) ---"
+
+    disable_guidance
+    trap restore_guidance_on_exit EXIT
+
+    # Verify rules file is gone
+    if [ -f "$RULE_FILE" ]; then
+        echo "ERROR: Rules file still exists after rm!" >&2
+        exit 1
+    fi
+    record_verify "PRE-CONTROL"
+    echo "[ok] Rules file removed (verified)"
+
+    # Clean workspace
+    if [ -d "$GEN_SRC" ]; then
+        BACKUP="$WORKSPACE/src.__bench_backup_$(date +%s)__"
+        echo "[warning] Existing $GEN_SRC found. Moving to $BACKUP"
+        mv "$GEN_SRC" "$BACKUP"
+    fi
+
+    # Run CC
+    echo "[running] claude -p (Control) from $WORKSPACE ..."
+    (cd "$WORKSPACE" && claude -p --output-format json --max-budget-usd "$BUDGET" \
+        < "$PROMPT_FILE" > "$RESULTS_DIR/session-a.json" 2>"$RESULTS_DIR/session-a.stderr") || true
+
+    record_verify "POST-CONTROL"
+    cleanup_generated "$RESULTS_DIR/control"
+    echo "[ok] Control files saved to $RESULTS_DIR/control/"
+
+    # Restore guidance if running control only
+    if [ "$SESSION" = "control" ]; then
+        enable_guidance
+        trap - EXIT
+        echo "[ok] Rules file restored."
+    fi
+}
+
+run_treatment() {
+    echo ""
+    echo "--- Session B: Treatment (guidance ENABLED) ---"
+
+    enable_guidance
+    trap - EXIT
+
+    if [ ! -f "$RULE_FILE" ]; then
+        echo "ERROR: Rules file not found at $RULE_FILE" >&2
+        exit 1
+    fi
+    record_verify "PRE-TREATMENT"
+    echo "[ok] Rules file present ($(wc -c < "$RULE_FILE") bytes, verified)"
+
+    # Clean workspace
+    if [ -d "$GEN_SRC" ]; then
+        BACKUP="$WORKSPACE/src.__bench_backup_$(date +%s)__"
+        echo "[warning] Existing $GEN_SRC found. Moving to $BACKUP"
+        mv "$GEN_SRC" "$BACKUP"
+    fi
+
+    # Run CC
+    echo "[running] claude -p (Treatment) from $WORKSPACE ..."
+    (cd "$WORKSPACE" && claude -p --output-format json --max-budget-usd "$BUDGET" \
+        < "$PROMPT_FILE" > "$RESULTS_DIR/session-b.json" 2>"$RESULTS_DIR/session-b.stderr") || true
+
+    record_verify "POST-TREATMENT"
+    cleanup_generated "$RESULTS_DIR/treatment"
+    echo "[ok] Treatment files saved to $RESULTS_DIR/treatment/"
+}
+
+# --- Pre-flight checks ---
+if [ ! -f "$PROMPT_FILE" ]; then
+    echo "ERROR: prompt.txt not found at $PROMPT_FILE" >&2
+    exit 1
+fi
+
+if [ ! -f "$RULE_SOURCE" ]; then
+    echo "ERROR: Guidance source not found at $RULE_SOURCE" >&2
+    exit 1
+fi
+
+case "$SESSION" in
+    control|treatment|both) ;;
+    *)
+        echo "ERROR: Invalid session '$SESSION'. Use: control, treatment, or both" >&2
+        exit 1
+        ;;
+esac
+
+if [ "$SESSION" = "control" ] && [ -f "$RESULTS_DIR/session-a.json" ]; then
+    echo "ERROR: Control session already exists in $RESULTS_DIR" >&2
+    exit 1
+fi
+if [ "$SESSION" = "treatment" ] && [ -f "$RESULTS_DIR/session-b.json" ]; then
+    echo "ERROR: Treatment session already exists in $RESULTS_DIR" >&2
+    exit 1
+fi
+if [ "$SESSION" = "both" ] && [ -d "$RESULTS_DIR" ]; then
+    echo "ERROR: Results directory already exists: $RESULTS_DIR" >&2
+    exit 1
+fi
+
+mkdir -p "$RESULTS_DIR"
+
+echo "=== Effectiveness Benchmark Run $RUN_ID ($SESSION) ==="
+echo "Prompt: $PROMPT_FILE"
+echo "Results: $RESULTS_DIR"
+
+# --- Execute ---
+case "$SESSION" in
+    control)
+        run_control
+        echo ""
+        echo "=== Control session complete ==="
+        echo "Run treatment: ./bench/run.sh $RUN_ID treatment"
+        ;;
+    treatment)
+        run_treatment
+        echo ""
+        echo "=== Treatment session complete ==="
+        echo "Score with: ./bench/score-v2.sh $RUN_ID"
+        ;;
+    both)
+        run_control
+        run_treatment
+        echo ""
+        echo "=== Run $RUN_ID Complete ==="
+        echo "Score with: ./bench/score-v2.sh $RUN_ID"
+        ;;
+esac