claude-dev-env 1.58.0 → 1.60.0

package/bin/install.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, statSync, copyFileSync, unlinkSync, rmSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, statSync, copyFileSync, unlinkSync, rmSync, realpathSync } from 'node:fs';
 import { join, dirname, resolve, relative } from 'node:path';
 import { homedir } from 'node:os';
 import { execSync, execFileSync } from 'node:child_process';
@@ -188,14 +188,53 @@ export function pythonCandidatesForPlatform(platform) {
     return platform === 'win32' ? windowsOrder : defaultOrder;
 }
 
+/**
+ * Reports whether a resolved interpreter path belongs to the Microsoft Store
+ * Python, whose `python.exe` App Execution Alias reparse stub cannot be spawned
+ * as a hook subprocess. Both the alias under `Microsoft\WindowsApps` and the
+ * package executable under `Program Files\WindowsApps` sit beneath a
+ * `WindowsApps` directory, so the installer skips any candidate resolving there.
+ *
+ * @param {string} executablePath Absolute interpreter path from sys.executable.
+ * @returns {boolean} True when the path lives under a WindowsApps directory.
+ */
+export function isWindowsStorePythonStub(executablePath) {
+    return /[\\/]windowsapps[\\/]/i.test(executablePath);
+}
+
+/**
+ * Formats an absolute interpreter path as a settings.json hook command prefix:
+ * forward-slash separators, double-quoted when the path contains a space so the
+ * harness parses the interpreter as a single argument.
+ *
+ * @param {string} executablePath Absolute interpreter path from sys.executable.
+ * @returns {string} The command-prefix form of the interpreter path.
+ */
+export function interpreterCommandFromPath(executablePath) {
+    const forwardSlashedPath = executablePath.replace(/\\/g, '/');
+    return forwardSlashedPath.includes(' ') ? `"${forwardSlashedPath}"` : forwardSlashedPath;
+}
+
+/**
+ * Picks the interpreter command baked into every managed hook in settings.json.
+ * On win32 the first working candidate is resolved to its absolute
+ * sys.executable and that path is baked in, so a later PATH change or Microsoft
+ * Store update that re-points the `py`/`python` launcher cannot silently break
+ * the hooks; candidates resolving to the non-spawnable WindowsApps stub are
+ * skipped. Other platforms keep the bare command (e.g. `python3`).
+ *
+ * @returns {string|null} The interpreter command, or null when none is usable.
+ */
 function detectPython() {
     const candidates = pythonCandidatesForPlatform(process.platform);
     for (const { command, versionFlag } of candidates) {
         try {
             const version = execSync(`${command} ${versionFlag}`, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
-            if (version.includes('Python 3.')) {
-                return command;
-            }
+            if (!version.includes('Python 3.')) continue;
+            if (process.platform !== 'win32') return command;
+            const executablePath = execSync(`${command} -c "import sys; print(sys.executable)"`, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+            if (!executablePath || isWindowsStorePythonStub(executablePath)) continue;
+            return interpreterCommandFromPath(executablePath);
         } catch { /* try next */ }
     }
     return null;
@@ -501,7 +540,7 @@ function install(selectedGroups, options = {}) {
     abortWhenPackageSourceHasConflicts(PACKAGE_ROOT);
     const pythonCommand = detectPython();
     if (!pythonCommand) {
-        console.error('ERROR: Python 3 not found. Install Python 3.8+ and ensure python3, python, or py is on PATH.');
+        console.error('ERROR: No usable Python 3 found. Install Python 3.8+ from python.org and ensure py, python3, or python is on PATH. On Windows the Microsoft Store python.exe alias is rejected because it cannot run hooks.');
         process.exit(1);
     }
     console.log(`  Python: ${pythonCommand}`);
@@ -815,28 +854,62 @@ writes the previous contents to ~/.claude/backups/CLAUDE.md.<timestamp>.bak firs
 `);
 }
 
-const rawArgs = process.argv.slice(2);
-const args = rawArgs.filter((flag) => flag !== '--update');
-const isUpdateRefresh = rawArgs.includes('--update');
-if (args.includes('--help') || args.includes('-h')) {
-    printHelp();
-} else if (args.includes('--uninstall')) {
-    uninstall();
-} else {
-    const onlyIndex = args.indexOf('--only');
-    let selectedGroups = null;
-    if (onlyIndex !== -1) {
-        const onlyValue = args[onlyIndex + 1];
-        if (!onlyValue || onlyValue.startsWith('--')) {
-            console.error(`ERROR: --only requires a comma-separated list of groups.\nAvailable groups: ${Object.keys(INSTALL_GROUPS).join(', ')}`);
-            process.exit(1);
-        }
-        selectedGroups = onlyValue.split(',').map(name => name.trim());
-        const invalidGroups = selectedGroups.filter(name => !INSTALL_GROUPS[name]);
-        if (invalidGroups.length > 0) {
-            console.error(`ERROR: Unknown group(s): ${invalidGroups.join(', ')}\nAvailable groups: ${Object.keys(INSTALL_GROUPS).join(', ')}`);
-            process.exit(1);
+/**
+ * Reports whether this module is the process entry point (run as
+ * `node install.mjs`, or through a bin symlink such as the npm-installed
+ * `claude-dev-env` launcher) rather than imported by another module such as the
+ * test suite. The install/uninstall dispatch runs only when true, so importing
+ * the module carries no side effects.
+ *
+ * Both sides resolve to their real on-disk paths before comparison, so a
+ * symlinked launcher whose target is this module still counts as the entry
+ * point even though `process.argv[1]` keeps the symlink path while
+ * `import.meta.url` reports the resolved target. When either path cannot be
+ * resolved on disk (for example a synthetic path in a unit test), the raw
+ * paths are compared instead.
+ *
+ * @param {string} moduleUrl The module's import.meta.url.
+ * @param {string|undefined} entryScriptPath The invoked script path (process.argv[1]).
+ * @returns {boolean} True when the module is the process entry point.
+ */
+export function invokedAsEntryPoint(moduleUrl, entryScriptPath) {
+    if (!entryScriptPath) return false;
+    const modulePath = fileURLToPath(moduleUrl);
+    return realPathOrSelf(modulePath) === realPathOrSelf(entryScriptPath);
+}
+
+function realPathOrSelf(filesystemPath) {
+    try {
+        return realpathSync(filesystemPath);
+    } catch {
+        return filesystemPath;
+    }
+}
+
+if (invokedAsEntryPoint(import.meta.url, process.argv[1])) {
+    const rawArgs = process.argv.slice(2);
+    const args = rawArgs.filter((flag) => flag !== '--update');
+    const isUpdateRefresh = rawArgs.includes('--update');
+    if (args.includes('--help') || args.includes('-h')) {
+        printHelp();
+    } else if (args.includes('--uninstall')) {
+        uninstall();
+    } else {
+        const onlyIndex = args.indexOf('--only');
+        let selectedGroups = null;
+        if (onlyIndex !== -1) {
+            const onlyValue = args[onlyIndex + 1];
+            if (!onlyValue || onlyValue.startsWith('--')) {
+                console.error(`ERROR: --only requires a comma-separated list of groups.\nAvailable groups: ${Object.keys(INSTALL_GROUPS).join(', ')}`);
+                process.exit(1);
+            }
+            selectedGroups = onlyValue.split(',').map(name => name.trim());
+            const invalidGroups = selectedGroups.filter(name => !INSTALL_GROUPS[name]);
+            if (invalidGroups.length > 0) {
+                console.error(`ERROR: Unknown group(s): ${invalidGroups.join(', ')}\nAvailable groups: ${Object.keys(INSTALL_GROUPS).join(', ')}`);
+                process.exit(1);
+            }
         }
+        install(selectedGroups, { isUpdateRefresh });
     }
-    install(selectedGroups, { isUpdateRefresh });
 }

package/bin/install.test.mjs

@@ -1,14 +1,18 @@
 import { test } from 'node:test';
 import { strict as assert } from 'node:assert';
 import { execFileSync } from 'node:child_process';
-import { mkdtempSync, rmSync, mkdirSync, writeFileSync } from 'node:fs';
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync, symlinkSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
 
 import {
     collectPackageSourceConflicts,
     CONTENT_DIRECTORIES,
     pythonCandidatesForPlatform,
+    isWindowsStorePythonStub,
+    interpreterCommandFromPath,
+    invokedAsEntryPoint,
     managedHookScriptRelativePaths,
     managedHookScriptRelativePathsFromSourceRoots,
     commandReferencesManagedHook,
@@ -202,6 +206,134 @@ test('pythonCandidatesForPlatform still offers python as a win32 fallback when p
 });
 
 
+test('isWindowsStorePythonStub flags the Microsoft Store WindowsApps alias paths', () => {
+    assert.equal(
+        isWindowsStorePythonStub('C:\\Program Files\\WindowsApps\\PythonSoftwareFoundation.Python.3.13_3.13.3824.0_x64__qbz5n2kfra8p0\\python3.13.exe'),
+        true,
+    );
+    assert.equal(
+        isWindowsStorePythonStub('C:/Users/jon/AppData/Local/Microsoft/WindowsApps/python.exe'),
+        true,
+    );
+});
+
+
+test('isWindowsStorePythonStub does not flag a real interpreter install path', () => {
+    assert.equal(isWindowsStorePythonStub('C:\\Python313\\python.exe'), false);
+    assert.equal(isWindowsStorePythonStub('/usr/bin/python3'), false);
+});
+
+
+test('interpreterCommandFromPath forward-slashes a Windows interpreter path and leaves a space-free path unquoted', () => {
+    assert.equal(interpreterCommandFromPath('C:\\Python313\\python.exe'), 'C:/Python313/python.exe');
+});
+
+
+test('interpreterCommandFromPath quotes an interpreter path that contains a space', () => {
+    assert.equal(
+        interpreterCommandFromPath('C:\\Program Files\\Python313\\python.exe'),
+        '"C:/Program Files/Python313/python.exe"',
+    );
+});
+
+
+test('mergeHooksIntoSettings substitutes a quoted absolute interpreter path for the python3 prefix', () => {
+    const hooksConfig = {
+        hooks: {
+            PostToolUse: [
+                {
+                    matcher: 'Edit',
+                    hooks: [{ type: 'command', command: 'python3 ${CLAUDE_PLUGIN_ROOT}/hooks/workflow/auto_formatter.py' }],
+                },
+            ],
+        },
+    };
+    const settings = {};
+    mergeHooksIntoSettings(settings, hooksConfig, 'C:/Users/x/.claude', '"C:/Program Files/Python313/python.exe"');
+    assert.equal(
+        settings.hooks.PostToolUse[0].hooks[0].command,
+        '"C:/Program Files/Python313/python.exe" C:/Users/x/.claude/hooks/workflow/auto_formatter.py',
+    );
+});
+
+
+test('mergeHooksIntoSettings prunes a prior py -3 managed hook when reinstalling with an absolute interpreter path', () => {
+    const hooksConfig = {
+        hooks: {
+            PostToolUse: [
+                {
+                    matcher: 'Edit',
+                    hooks: [{ type: 'command', command: 'python3 ${CLAUDE_PLUGIN_ROOT}/hooks/workflow/auto_formatter.py' }],
+                },
+            ],
+        },
+    };
+    const settings = {
+        hooks: {
+            PostToolUse: [
+                {
+                    matcher: 'Edit',
+                    hooks: [{ type: 'command', command: 'py -3 C:/Users/x/.claude/hooks/workflow/auto_formatter.py' }],
+                },
+            ],
+        },
+    };
+    mergeHooksIntoSettings(settings, hooksConfig, 'C:/Users/x/.claude', 'C:/Python313/python.exe');
+    assert.deepEqual(
+        settings.hooks.PostToolUse[0].hooks.map(hook => hook.command),
+        ['C:/Python313/python.exe C:/Users/x/.claude/hooks/workflow/auto_formatter.py'],
+    );
+});
+
+
+test('invokedAsEntryPoint is true when the module url matches the invoked script path', () => {
+    const scriptPath = process.platform === 'win32' ? 'C:\\pkg\\bin\\install.mjs' : '/pkg/bin/install.mjs';
+    assert.equal(invokedAsEntryPoint(pathToFileURL(scriptPath).href, scriptPath), true);
+});
+
+
+test('invokedAsEntryPoint is false when the module is imported by another script', () => {
+    const modulePath = process.platform === 'win32' ? 'C:\\pkg\\bin\\install.mjs' : '/pkg/bin/install.mjs';
+    const entryScriptPath = process.platform === 'win32' ? 'C:\\pkg\\bin\\install.test.mjs' : '/pkg/bin/install.test.mjs';
+    assert.equal(invokedAsEntryPoint(pathToFileURL(modulePath).href, entryScriptPath), false);
+});
+
+
+test('invokedAsEntryPoint is false when there is no invoked script path', () => {
+    assert.equal(invokedAsEntryPoint('file:///pkg/bin/install.mjs', undefined), false);
+});
+
+
+test('invokedAsEntryPoint is true when the module is reached through a bin symlink', () => {
+    const linkRoot = mkdtempSync(join(tmpdir(), 'cdev-bin-symlink-'));
+    try {
+        const realModulePath = join(linkRoot, 'install.mjs');
+        const symlinkLauncherPath = join(linkRoot, 'claude-dev-env');
+        writeFileSync(realModulePath, 'export const sentinel = true;\n');
+        symlinkSync(realModulePath, symlinkLauncherPath);
+        const realModuleUrl = pathToFileURL(realModulePath).href;
+        assert.equal(invokedAsEntryPoint(realModuleUrl, symlinkLauncherPath), true);
+    } finally {
+        rmSync(linkRoot, { recursive: true, force: true });
+    }
+});
+
+
+test('invokedAsEntryPoint is false when a sibling script imports the real module', () => {
+    const importerRoot = mkdtempSync(join(tmpdir(), 'cdev-bin-importer-'));
+    try {
+        const realModulePath = join(importerRoot, 'install.mjs');
+        const importerScriptPath = join(importerRoot, 'install.test.mjs');
+        writeFileSync(realModulePath, 'export const sentinel = true;\n');
+        writeFileSync(importerScriptPath, 'import "./install.mjs";\n');
+        const realModuleUrl = pathToFileURL(realModulePath).href;
+        assert.equal(invokedAsEntryPoint(realModuleUrl, importerScriptPath), false);
+    } finally {
+        rmSync(importerRoot, { recursive: true, force: true });
+    }
+});
+
+
 const SAMPLE_HOOKS_CONFIG = {
     hooks: {
         Stop: [

package/docs/CODE_RULES.md

@@ -23,9 +23,9 @@ Compact reference for agents. ⚡ marks rules enforced by `code_rules_enforcer.p
 
 `code_rules_enforcer.py` blocks each of these at Write/Edit and explains the specific violation when it fires; exact patterns and exemption lists live in the hook:
 
-no new comments · imports at top · logging format args (`log_*("...", arg)`) · no magic values in production bodies (0, 1, -1 exempt) · UPPER_SNAKE constants only in `config/` (exempt: `config/*`, `/migrations/`, workflow registries `/workflow/` + `_tab.py` + `/states.py` + `/modules.py`, test files) · no hardcoded user home paths · guarded `sys.path.insert` · no unused module-level imports · banned identifiers (`ctx`, `cfg`, `msg`, `btn`, `idx`, `cnt`, `tmp`, `elem`, `val`) · banned function prefixes (`handle_`, `process_`, `manage_`, `do_`) · no type escape hatches (`Any` import, `cast()`, inline `Any`) outside boundary files · no bare/broad `except` · no `Any` in signatures or class attributes · no stub bodies (`pass`/`...`/`raise NotImplementedError`) outside abstract/Protocol · TypedDict `_encode_*`/`_decode_*` companions in the same module · no test-mode branching in production (use dependency injection) · no thin wrapper modules · Google-style docstrings on public functions with `Args:` matching the signature · boolean names prefixed `is_`/`has_`/`should_`/`can_`/`was_`/`did_` (assignments AND bool-typed parameters) · must-check returns (`find_and_click`, `write_outcome`) assigned and checked
+no new comments · imports at top · logging format args (`log_*("...", arg)`) · no magic values in production bodies (0, 1, -1 exempt) · UPPER_SNAKE constants only in `config/` (exempt: `config/*`, `/migrations/`, workflow registries `/workflow/` + `_tab.py` + `/states.py` + `/modules.py`, test files) · no hardcoded user home paths · guarded `sys.path.insert` · no unused module-level imports · banned identifiers (`ctx`, `cfg`, `msg`, `btn`, `idx`, `cnt`, `tmp`, `elem`, `val`) · banned function prefixes (`handle_`, `process_`, `manage_`, `do_`) · no type escape hatches (`Any` import, `cast()`, inline `Any`) outside boundary files · no bare/broad `except` · no `Any` in signatures or class attributes · no stub bodies (`pass`/`...`/`raise NotImplementedError`) outside abstract/Protocol · TypedDict `_encode_*`/`_decode_*` companions in the same module · no test-mode branching in production (use dependency injection) · no thin wrapper modules · Google-style docstrings on public functions with `Args:` matching the signature · boolean names prefixed `is_`/`has_`/`should_`/`can_`/`was_`/`did_` (assignments AND bool-typed parameters) · must-check returns (`find_and_click`, `write_outcome`) assigned and checked · known pytest fixture parameters in test files annotated with their single documented type (`tmp_path: Path`, `monkeypatch: pytest.MonkeyPatch`, `capsys`, `caplog`, `request`, …)
 
-Test files are exempt from most checks. See also the file-global constants use-count rule: [`rules/file-global-constants.md`](../rules/file-global-constants.md).
+Test files are exempt from most checks. The one annotation the test-file exemption does NOT cover is a known pytest builtin fixture parameter: `tmp_path`, `monkeypatch`, `capsys`, `capfd`, `caplog`, `request`, and `tmp_path_factory` each have a single documented injected type, so the gate requires that annotation (`tmp_path: Path`) even inside a test file. Ordinary test parameters stay exempt. See also the file-global constants use-count rule: [`rules/file-global-constants.md`](../rules/file-global-constants.md).
 
 ---
 
@@ -94,4 +94,4 @@ If you already have the data, don't fetch it again.
 
 ## 11. ENFORCEMENT SURFACES
 
-⚡ **Hooks** block pattern-matchable violations at Write/Edit time. 🤖 **Prompt context** carries judgment principles (SRP, Right-Sized Engineering, conservative-action, BDD discovery; the `/code` skill prepends strict mode for a session: no `Any`/`cast()`, immutable TypedDicts with `_encode_*`/`_decode_*` + `require_*` validation, per-module `_test_hooks.py` DI, 100% statement + branch coverage, zero mocks). 👥 **Audit rubrics** (`/check`, `packages/claude-dev-env/audit-rubrics/` categories A–P) cover cross-file architectural concerns. Rules with documented-but-pending hook coverage live in `~/.claude/rules/*.md` and `skills/code/SKILL.md`; each names its own promotion path.
+⚡ **Hooks** block pattern-matchable violations at Write/Edit time. 🤖 **Prompt context** carries judgment principles (SRP, Right-Sized Engineering, conservative-action, BDD discovery, docstring-prose-matches-implementation; the `/code` skill prepends strict mode for a session: no `Any`/`cast()`, immutable TypedDicts with `_encode_*`/`_decode_*` + `require_*` validation, per-module `_test_hooks.py` DI, 100% statement + branch coverage, zero mocks). 👥 **Audit rubrics** (`/check`, `packages/claude-dev-env/audit-rubrics/` categories A–P) cover cross-file architectural concerns. Rules with documented-but-pending hook coverage live in `~/.claude/rules/*.md` and `skills/code/SKILL.md`; each names its own promotion path. The docstring-prose standard (free-form enumerations match the body) lives in `packages/claude-dev-env/rules/docstring-prose-matches-implementation.md`, enforced via Category O6 audit.

package/hooks/blocking/code_rules_annotations_length.py

@@ -13,6 +13,7 @@ if _hooks_directory not in sys.path:
 
 from code_rules_shared import (  # noqa: E402
     _collect_annotated_arguments,
+    _collect_fixture_injection_arguments,
     _definition_docstring_line_span,
     _function_definition_line_span,
     _scope_violations_to_changed_lines,
@@ -24,8 +25,10 @@ from code_rules_shared import (  # noqa: E402
 
 from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
     ALL_SELF_AND_CLS_PARAMETER_NAMES,
+    ANNOTATION_BY_PYTEST_FIXTURE,
     FUNCTION_LENGTH_BLOCKING_MESSAGE_SUFFIX,
     FUNCTION_LENGTH_BLOCKING_THRESHOLD,
+    KNOWN_PYTEST_FIXTURE_ANNOTATION_MESSAGE_SUFFIX,
 )
 
 
@@ -52,6 +55,156 @@ def check_parameter_annotations(content: str, file_path: str) -> list[str]:
     return issues
 
 
+def _is_pytest_fixture_injection_site(
+    node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> bool:
+    """Return True when a function node is a valid pytest fixture injection site.
+
+    A function qualifies as a fixture injection site when either its name begins
+    with the ``test`` prefix (matching pytest's default ``python_functions = test*``
+    collection rule) or it carries a ``@pytest.fixture`` / ``@fixture`` decorator,
+    with or without call arguments.  Ordinary helper functions that happen to share
+    a parameter name with a known pytest fixture are excluded by this predicate so
+    that ``check_known_pytest_fixture_annotations`` only enforces annotation
+    requirements on the functions where pytest actually performs fixture injection.
+
+    Args:
+        node: The function definition AST node to inspect.
+
+    Returns:
+        True when the node is a pytest test function or a fixture-decorated
+        function; False otherwise.
+    """
+    if node.name.startswith("test"):
+        return True
+    for each_decorator in node.decorator_list:
+        unwrapped = each_decorator.func if isinstance(each_decorator, ast.Call) else each_decorator
+        if isinstance(unwrapped, ast.Name) and unwrapped.id == "fixture":
+            return True
+        if isinstance(unwrapped, ast.Attribute) and unwrapped.attr == "fixture":
+            return True
+    return False
+
+
+def _normalize_fixture_annotation_text(annotation_text: str) -> str:
+    """Strip forward-reference string quoting from an unparsed annotation.
+
+    ``ast.unparse`` renders a forward-reference annotation such as
+    ``tmp_path: "Path"`` as the quoted literal ``'Path'``. Removing the
+    surrounding quotes recovers the bare type name so the quoted spelling
+    compares equal to its unquoted form.
+
+    Args:
+        annotation_text: The annotation as rendered by ``ast.unparse``.
+
+    Returns:
+        The annotation text with any single surrounding quote pair removed.
+    """
+    if len(annotation_text) >= 2 and annotation_text[0] in {'"', "'"}:
+        if annotation_text[-1] == annotation_text[0]:
+            return annotation_text[1:-1]
+    return annotation_text
+
+
+def _fixture_annotation_matches_expected(
+    actual_annotation: str, expected_annotation: str
+) -> bool:
+    """Return True when an annotation matches its fixture's documented type.
+
+    The match accepts every equally-correct spelling of the documented type:
+    the exact text, a forward-reference string form, and either the bare
+    attribute tail or the fully-qualified dotted form. Both ``tmp_path: Path``
+    and ``tmp_path: pathlib.Path`` satisfy an expected ``Path``, and both
+    ``monkeypatch: pytest.MonkeyPatch`` and ``monkeypatch: MonkeyPatch``
+    satisfy an expected ``pytest.MonkeyPatch``.
+
+    Args:
+        actual_annotation: The annotation as rendered by ``ast.unparse``.
+        expected_annotation: The fixture's single documented type spelling.
+
+    Returns:
+        True when the actual annotation is an accepted spelling of the
+        expected type; False otherwise.
+    """
+    normalized_actual = _normalize_fixture_annotation_text(actual_annotation)
+    if normalized_actual == expected_annotation:
+        return True
+    return normalized_actual.rsplit(".", 1)[-1] == expected_annotation.rsplit(
+        ".", 1
+    )[-1]
+
+
+def check_known_pytest_fixture_annotations(content: str, file_path: str) -> list[str]:
+    """Flag well-known pytest fixture parameters lacking their type annotation.
+
+    The broad parameter-annotation rule exempts test files, so an ordinary
+    test parameter never needs a type hint. This narrower check restores
+    enforcement for exactly the pytest builtin fixtures whose injected type is
+    fixed and documented — ``tmp_path: Path``, ``monkeypatch:
+    pytest.MonkeyPatch``, and the rest of
+    ``ANNOTATION_BY_PYTEST_FIXTURE``. For these names the
+    correct annotation is unambiguous, so requiring it costs the author one
+    token and removes a recurring class of reviewer noise on test fixtures.
+    A non-test file produces no findings here: the broad check already covers
+    every parameter outside test files.
+
+    A known fixture parameter is flagged both when it carries no annotation and
+    when its annotation source differs from the fixture's single documented
+    type, so ``tmp_path: str`` is flagged exactly like ``tmp_path``. Only the
+    named injection slots pytest actually fills — undefaulted
+    positional-or-keyword and keyword-only parameters — are inspected. A
+    positional-only parameter is skipped because pytest passes fixtures by
+    keyword and can never bind one positionally; a defaulted parameter is
+    skipped because pytest leaves its default in place rather than injecting a
+    fixture; and a ``*args`` or ``**kwargs`` parameter that happens to share a
+    fixture name is never a fixture injection.
+
+    Args:
+        content: The Python source to analyze.
+        file_path: The path of the file being checked.
+
+    Returns:
+        One blocking issue per known fixture injection parameter whose
+        annotation is missing or differs from its single documented type,
+        naming the parameter and its expected type.
+    """
+    if not is_test_file(file_path):
+        return []
+    if is_workflow_registry_file(file_path) or is_migration_file(file_path):
+        return []
+    try:
+        tree = ast.parse(content)
+    except SyntaxError:
+        return []
+    issues: list[str] = []
+    for each_node in ast.walk(tree):
+        if not isinstance(each_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        if not _is_pytest_fixture_injection_site(each_node):
+            continue
+        for each_arg in _collect_fixture_injection_arguments(each_node):
+            expected_annotation = ANNOTATION_BY_PYTEST_FIXTURE.get(
+                each_arg.arg
+            )
+            if expected_annotation is None:
+                continue
+            actual_annotation = (
+                ast.unparse(each_arg.annotation)
+                if each_arg.annotation is not None
+                else None
+            )
+            if actual_annotation is not None and _fixture_annotation_matches_expected(
+                actual_annotation, expected_annotation
+            ):
+                continue
+            issues.append(
+                f"Line {each_arg.lineno}: parameter {each_arg.arg!r} on "
+                f"{each_node.name!r} - {KNOWN_PYTEST_FIXTURE_ANNOTATION_MESSAGE_SUFFIX} "
+                f"(annotate as {expected_annotation!r})"
+            )
+    return issues
+
+
 def check_return_annotations(content: str, file_path: str) -> list[str]:
     if is_test_file(file_path):
         return []