claude-dev-env 2.0.2 → 2.2.0

package/hooks/validators/mypy_integration.py

@@ -1,10 +1,31 @@
 """Mypy integration for static type checking."""
 
+import contextlib
 import subprocess
+import sys
+import tempfile
 import tomllib
+from collections.abc import Iterator
 from dataclasses import dataclass
 from pathlib import Path
 
+_hooks_directory = str(Path(__file__).resolve().parent.parent)
+
+try:
+    from hooks_constants.mypy_integration_constants import (
+        GIT_DIRECTORY_NAME,
+        PYPROJECT_FILENAME,
+        PYTHON_SOURCE_SUFFIX,
+    )
+except ModuleNotFoundError:
+    if _hooks_directory not in sys.path:
+        sys.path.insert(0, _hooks_directory)
+    from hooks_constants.mypy_integration_constants import (
+        GIT_DIRECTORY_NAME,
+        PYPROJECT_FILENAME,
+        PYTHON_SOURCE_SUFFIX,
+    )
+
 
 @dataclass
 class MypyResult:
@@ -37,6 +58,28 @@ def _pyproject_contains_tool_mypy(pyproject_path: Path) -> bool:
     return isinstance(tool_table, dict) and "mypy" in tool_table
 
 
+def _ancestor_directories(starting_file: Path) -> list[Path]:
+    """Return *starting_file*'s directory and every parent, nearest first.
+
+    ::
+
+        repo/pkg/mod.py -> [repo/pkg, repo, ... , filesystem root]
+        repo/pkg/       -> [repo/pkg, repo, ... , filesystem root]
+
+    A file resolves to its containing directory; a directory resolves to
+    itself, so both ancestor walks below start from the same first candidate.
+
+    Args:
+        starting_file: The file (or directory) the walk begins from.
+
+    Returns:
+        The resolved starting directory followed by each of its parents.
+    """
+    resolved_starting_file = starting_file.resolve()
+    walk_origin = resolved_starting_file.parent if resolved_starting_file.is_file() else resolved_starting_file
+    return [walk_origin, *walk_origin.parents]
+
+
 def find_pyproject_with_mypy_config(starting_file: Path) -> Path | None:
     """Walk up from a starting file to locate a pyproject.toml that configures mypy.
 
@@ -54,16 +97,103 @@ def find_pyproject_with_mypy_config(starting_file: Path) -> Path | None:
         table, or ``None`` when no such file exists between ``starting_file``
         and the filesystem root.
     """
-    pyproject_filename_for_lookup = "pyproject.toml"
-    resolved_starting_file = starting_file.resolve()
-    current_directory = resolved_starting_file.parent if resolved_starting_file.is_file() else resolved_starting_file
-    for each_candidate_directory in [current_directory, *current_directory.parents]:
+    pyproject_filename_for_lookup = PYPROJECT_FILENAME
+    for each_candidate_directory in _ancestor_directories(starting_file):
         candidate_pyproject = each_candidate_directory / pyproject_filename_for_lookup
         if candidate_pyproject.is_file() and _pyproject_contains_tool_mypy(candidate_pyproject):
             return candidate_pyproject
     return None
 
 
+def find_module_resolution_root(starting_file: Path) -> Path | None:
+    """Return the nearest ancestor directory that roots a project, else None.
+
+    A project root is the first ancestor holding a ``.git`` entry or a
+    ``pyproject.toml``. Mypy resolves a first-party import against its working
+    directory, so anchoring there binds ``config.*`` to the target file's own
+    project and keeps a foreign ``config`` in the caller's directory out of scope.
+
+    ::
+
+        target_repo/.git + target_repo/tools/x.py -> target_repo
+        /tmp/detached/x.py (no marker up-tree)      -> None
+
+    Args:
+        starting_file: The file (or directory) the walk begins from.
+
+    Returns:
+        The nearest ancestor Path that holds ``.git`` or ``pyproject.toml``,
+        or ``None`` when no such ancestor exists.
+    """
+    git_entry_name = GIT_DIRECTORY_NAME
+    pyproject_filename = PYPROJECT_FILENAME
+    for each_candidate_directory in _ancestor_directories(starting_file):
+        has_git_entry = (each_candidate_directory / git_entry_name).exists()
+        has_pyproject = (each_candidate_directory / pyproject_filename).is_file()
+        if has_git_entry or has_pyproject:
+            return each_candidate_directory
+    return None
+
+
+def _first_module_resolution_root(all_py_files: list[str]) -> Path | None:
+    """Return the project root of the first rooted target file, or None."""
+    for each_py_file in all_py_files:
+        resolution_root = find_module_resolution_root(Path(each_py_file))
+        if resolution_root is not None:
+            return resolution_root
+    return None
+
+
+@contextlib.contextmanager
+def mypy_working_directory(all_py_files: list[str]) -> Iterator[str]:
+    """Yield the working directory mypy resolves first-party imports from.
+
+    ::
+
+        target_repo/tools/serialize_tool.py -> yields target_repo
+        /tmp/detached/serialize_tool.py       -> yields a fresh empty temp dir
+
+    A rooted file yields its project root so ``config.constants`` binds to the
+    target repo's own package; a detached file yields an isolated directory so
+    no foreign top-level package leaks in.
+
+    Args:
+        all_py_files: Absolute or relative paths of the Python files under check.
+
+    Yields:
+        A directory path string mypy should use as its working directory.
+    """
+    resolution_root = _first_module_resolution_root(all_py_files)
+    if resolution_root is not None:
+        yield str(resolution_root)
+        return
+    with tempfile.TemporaryDirectory() as isolated_directory:
+        yield isolated_directory
+
+
+def _mypy_config_argument(all_py_files: list[str]) -> list[str]:
+    """Return the ``--config-file`` argument for the first file with a mypy config."""
+    for each_py_file in all_py_files:
+        discovered_pyproject = find_pyproject_with_mypy_config(Path(each_py_file))
+        if discovered_pyproject is not None:
+            return ["--config-file", str(discovered_pyproject)]
+    return []
+
+
+def _run_mypy_subprocess(all_py_files: list[str]) -> subprocess.CompletedProcess[str]:
+    """Run mypy over *all_py_files* from each file's own project root."""
+    config_argument = _mypy_config_argument(all_py_files)
+    with mypy_working_directory(all_py_files) as working_directory:
+        return subprocess.run(
+            ["mypy", *config_argument, "--ignore-missing-imports", "--no-error-summary"]
+            + all_py_files,
+            check=False,
+            capture_output=True,
+            text=True,
+            cwd=working_directory,
+        )
+
+
 def run_mypy_check(files: list[Path]) -> MypyResult:
     """Run mypy on files."""
     if not files:
@@ -72,29 +202,20 @@ def run_mypy_check(files: list[Path]) -> MypyResult:
     if not check_mypy_available():
         return MypyResult(passed=True, output="Mypy not installed - skipping", error_count=0)
 
-    py_files = [str(f) for f in files if f.suffix == ".py"]
-    if not py_files:
+    python_source_suffix = PYTHON_SOURCE_SUFFIX
+    all_py_files = [
+        str(each_file.resolve())
+        for each_file in files
+        if each_file.suffix == python_source_suffix
+    ]
+    if not all_py_files:
         return MypyResult(passed=True, output="No Python files", error_count=0)
 
-    config_argument: list[str] = []
-    for each_py_file in py_files:
-        discovered_pyproject = find_pyproject_with_mypy_config(Path(each_py_file))
-        if discovered_pyproject is not None:
-            config_argument = ["--config-file", str(discovered_pyproject)]
-            break
-
-    result = subprocess.run(
-        ["mypy", *config_argument, "--ignore-missing-imports", "--no-error-summary"]
-        + py_files,
-        check=False,
-        capture_output=True,
-        text=True,
-    )
-
-    error_count = result.stdout.count(": error:")
+    completed_process = _run_mypy_subprocess(all_py_files)
+    error_count = completed_process.stdout.count(": error:")
 
     return MypyResult(
-        passed=result.returncode == 0,
-        output=result.stdout or result.stderr or "No type errors",
+        passed=completed_process.returncode == 0,
+        output=completed_process.stdout or completed_process.stderr or "No type errors",
         error_count=error_count,
     )

package/hooks/validators/python_antipattern_checks.py

@@ -13,6 +13,15 @@ from typing import List
 
 from .validator_base import Violation
 
+_hooks_directory = str(Path(__file__).resolve().parent.parent)
+
+try:
+    from hooks_constants.code_rules_enforcer_constants import ALL_CLI_FILE_PATH_MARKERS
+except ModuleNotFoundError:
+    if _hooks_directory not in sys.path:
+        sys.path.insert(0, _hooks_directory)
+    from hooks_constants.code_rules_enforcer_constants import ALL_CLI_FILE_PATH_MARKERS
+
 
 def check_mutable_default_args(tree: ast.AST, filename: str) -> List[Violation]:
     violations: List[Violation] = []
@@ -55,6 +64,13 @@ def check_print_in_production(tree: ast.AST, filename: str) -> List[Violation]:
     if "test" in filename.lower():
         return violations
 
+    normalized_path = filename.lower().replace("\\", "/")
+    is_cli_entry_point = any(
+        marker.replace("\\", "/") in normalized_path for marker in ALL_CLI_FILE_PATH_MARKERS
+    )
+    if is_cli_entry_point:
+        return violations
+
     for node in ast.walk(tree):
         if isinstance(node, ast.Call):
             if isinstance(node.func, ast.Name) and node.func.id == "print":

package/hooks/validators/run_all_validators.py

@@ -32,6 +32,7 @@ _hooks_directory_on_path = str(hooks_dir.resolve())
 if _hooks_directory_on_path not in sys.path:
     sys.path.insert(0, _hooks_directory_on_path)
 
+from blocking.code_rules_shared import is_ephemeral_path  # noqa: E402
 from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
 from hooks_constants.multi_edit_reconstruction import (  # noqa: E402
     apply_edits,
@@ -821,9 +822,12 @@ def _evaluate_pre_tool_use_payload() -> None:
     """Read the PreToolUse payload from stdin and deny a violating file write.
 
     Reconstructs the proposed post-edit content of the one target file and runs
-    the file-scoped validators against it. Emits a deny decision naming each
-    failing validator when any fires; writes nothing for a clean file, an
-    unparseable payload, or a payload no validator covers.
+    the file-scoped validators against it. The path-based exemption decision runs
+    against the real target path from the payload, so an ephemeral scratch or
+    session scratchpad target passes without validation even though the content
+    is validated through a temporary copy. Emits a deny decision naming each
+    failing validator when any fires; writes nothing for a clean file, an exempt
+    target, an unparseable payload, or a payload no validator covers.
     """
     pre_tool_use_payload = json.load(sys.stdin)
     if not isinstance(pre_tool_use_payload, dict):
@@ -835,6 +839,8 @@ def _evaluate_pre_tool_use_payload() -> None:
     file_path = tool_input.get("file_path", "")
     if not isinstance(file_path, str) or not file_path:
         return
+    if is_ephemeral_path(file_path, pre_tool_use_payload):
+        return
     proposed_content = reconstruct_proposed_content(tool_name, tool_input)
     if not proposed_content:
         return

package/hooks/validators/test_mypy_integration.py

@@ -3,14 +3,168 @@
 from pathlib import Path
 from unittest.mock import patch
 
+import pytest
+
 from .mypy_integration import (
     MypyResult,
     check_mypy_available,
+    find_module_resolution_root,
     find_pyproject_with_mypy_config,
     run_mypy_check,
 )
 
 
+def _write_config_package(package_parent: Path, constants_body: str) -> None:
+    config_package = package_parent / "config"
+    config_package.mkdir(parents=True)
+    (config_package / "__init__.py").write_text("", encoding="utf-8")
+    (config_package / "constants.py").write_text(constants_body, encoding="utf-8")
+
+
+def _write_config_importer(script_path: Path) -> None:
+    script_path.parent.mkdir(parents=True, exist_ok=True)
+    script_path.write_text(
+        "from config.constants import SERIALIZED_INDENT_WIDTH\n\n"
+        "indent_width: int = SERIALIZED_INDENT_WIDTH\n",
+        encoding="utf-8",
+    )
+
+
+def test_find_module_resolution_root_returns_git_marked_ancestor(tmp_path: Path) -> None:
+    target_repo = tmp_path / "git_repo"
+    nested_directory = target_repo / "src" / "deep"
+    nested_directory.mkdir(parents=True)
+    (target_repo / ".git").mkdir()
+    nested_file = nested_directory / "module.py"
+    nested_file.write_text("sample_number: int = 1\n", encoding="utf-8")
+    assert find_module_resolution_root(nested_file) == target_repo
+
+
+def test_find_module_resolution_root_returns_nearest_pyproject_ancestor(
+    tmp_path: Path,
+) -> None:
+    outer_repo = tmp_path / "outer"
+    inner_project = outer_repo / "inner"
+    inner_project.mkdir(parents=True)
+    (outer_repo / ".git").mkdir()
+    (inner_project / "pyproject.toml").write_text(
+        "[project]\nname = 'inner'\n", encoding="utf-8"
+    )
+    nested_file = inner_project / "module.py"
+    nested_file.write_text("sample_number: int = 1\n", encoding="utf-8")
+    assert find_module_resolution_root(nested_file) == inner_project
+
+
+def test_run_mypy_check_resolves_config_against_target_repo_not_session_cwd(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """A target file's ``config`` import binds to its own repo, not the session cwd.
+
+    ::
+
+        cwd=session_worktree, whose config/ lacks SERIALIZED_INDENT_WIDTH
+        target_repo/tools/serialize_tool.py imports it from target_repo/config/
+        flag (defect): binds config to session_worktree -> attr-defined denial
+        ok  (fixed):   binds config to target_repo       -> passes
+    """
+    session_worktree = tmp_path / "session_worktree"
+    _write_config_package(session_worktree, "UNRELATED_SESSION_SETTING: int = 9\n")
+
+    target_repo = tmp_path / "target_repo"
+    _write_config_package(target_repo, "SERIALIZED_INDENT_WIDTH: int = 4\n")
+    (target_repo / "pyproject.toml").write_text(
+        "[project]\nname = 'synthetic-target'\n", encoding="utf-8"
+    )
+    target_script = target_repo / "tools" / "serialize_tool.py"
+    _write_config_importer(target_script)
+
+    monkeypatch.chdir(session_worktree)
+    mypy_result = run_mypy_check([target_script])
+
+    assert mypy_result.passed, mypy_result.output
+
+
+def test_run_mypy_check_ignores_session_config_for_detached_gate_file(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """A detached gate temp file does not bind ``config`` to the session cwd.
+
+    ::
+
+        cwd=session_worktree, whose config/ lacks SERIALIZED_INDENT_WIDTH
+        detached_gate_dir/serialize_tool.py (no repo ancestor) imports it
+        flag (defect): binds config to session_worktree -> attr-defined denial
+        ok  (fixed):   isolated cwd -> import ignored    -> passes
+    """
+    session_worktree = tmp_path / "session_worktree"
+    _write_config_package(session_worktree, "UNRELATED_SESSION_SETTING: int = 9\n")
+
+    detached_file = tmp_path / "detached_gate_dir" / "serialize_tool.py"
+    _write_config_importer(detached_file)
+
+    monkeypatch.chdir(session_worktree)
+    mypy_result = run_mypy_check([detached_file])
+
+    assert mypy_result.passed, mypy_result.output
+
+
+def test_run_mypy_check_still_flags_genuine_type_error(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """A real type error inside the target file is still reported.
+
+    ::
+
+        typed_repo/pkg/widths.py -> wrong_width: int = 'not an integer'
+        flag: assigning str to an int annotation -> mypy error, passed is False
+    """
+    typed_repo = tmp_path / "typed_repo"
+    package_directory = typed_repo / "pkg"
+    package_directory.mkdir(parents=True)
+    (typed_repo / "pyproject.toml").write_text(
+        "[project]\nname = 'typed-target'\n", encoding="utf-8"
+    )
+    faulty_script = package_directory / "widths.py"
+    faulty_script.write_text("wrong_width: int = 'not an integer'\n", encoding="utf-8")
+
+    monkeypatch.chdir(tmp_path)
+    mypy_result = run_mypy_check([faulty_script])
+
+    assert not mypy_result.passed
+    assert mypy_result.error_count >= 1
+
+
+def test_run_mypy_check_accepts_relative_path_under_nested_root(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """A repo-relative target under a nested project root is still readable.
+
+    ::
+
+        cwd=repo_root; changed file listed as repo-relative pkg/tool.py
+        pkg/ holds its own pyproject.toml -> resolution root is repo_root/pkg
+        flag (defect): mypy runs from repo_root/pkg with the repo-relative arg
+                       -> "can't read file", spurious failure
+        ok  (fixed):   arg resolved to an absolute path -> mypy reads it
+    """
+    repo_root = tmp_path / "repo_root"
+    nested_package = repo_root / "pkg"
+    nested_package.mkdir(parents=True)
+    (repo_root / ".git").mkdir()
+    (nested_package / "pyproject.toml").write_text(
+        "[project]\nname = 'nested'\n", encoding="utf-8"
+    )
+    (nested_package / "module.py").write_text(
+        "sample_number: int = 1\n", encoding="utf-8"
+    )
+
+    monkeypatch.chdir(repo_root)
+    relative_target = Path("pkg") / "module.py"
+    mypy_result = run_mypy_check([relative_target])
+
+    assert mypy_result.passed, mypy_result.output
+
+
 def test_mypy_result_dataclass() -> None:
     """Test MypyResult dataclass creation."""
     result = MypyResult(passed=True, output="test", error_count=0)

package/hooks/validators/test_python_antipattern_checks.py

@@ -1,6 +1,8 @@
 """Tests for Python anti-pattern detection."""
 
 import ast
+import sys
+from pathlib import Path
 
 import pytest
 
@@ -8,8 +10,17 @@ from .python_antipattern_checks import (
     check_mutable_default_args,
     check_bare_except,
     check_print_in_production,
+    validate_file,
 )
-from .validator_base import Violation
+from .run_all_validators import ValidatorResult, validate_proposed_file
+
+_HOOKS_DIRECTORY = str(Path(__file__).resolve().parent.parent)
+_BLOCKING_DIRECTORY = str(Path(__file__).resolve().parent.parent / "blocking")
+for each_candidate_directory in (_HOOKS_DIRECTORY, _BLOCKING_DIRECTORY):
+    if each_candidate_directory not in sys.path:
+        sys.path.insert(0, each_candidate_directory)
+
+from code_rules_imports_logging import check_library_print  # noqa: E402
 
 
 GOOD_NONE_DEFAULT = '''
@@ -111,3 +122,103 @@ class TestPrintInProduction:
         tree = ast.parse(TEST_FILE_WITH_PRINT)
         violations = check_print_in_production(tree, "test_utils.py")
         assert violations == []
+
+
+CLI_ENTRY_POINT_WITH_PRINTS = '''
+def main():
+    print("line one")
+    print("line two")
+    print("line three")
+    print("line four")
+    print("line five")
+'''
+
+NEAR_MISS_WITH_PRINT = '''
+def render():
+    print("output")
+'''
+
+
+class TestPrintInCliEntryPoint:
+    def test_cli_py_path_allows_print(self) -> None:
+        tree = ast.parse(CLI_ENTRY_POINT_WITH_PRINTS)
+        assert check_print_in_production(tree, "stp_preview/cli.py") == []
+
+    def test_cli_suffix_path_allows_print(self) -> None:
+        tree = ast.parse(CLI_ENTRY_POINT_WITH_PRINTS)
+        assert check_print_in_production(tree, "stp_preview/report_cli.py") == []
+
+    def test_scripts_path_allows_print(self) -> None:
+        tree = ast.parse(CLI_ENTRY_POINT_WITH_PRINTS)
+        assert check_print_in_production(tree, "packages/foo/scripts/run_job.py") == []
+
+    def test_near_miss_name_still_flagged(self) -> None:
+        tree = ast.parse(NEAR_MISS_WITH_PRINT)
+        assert len(check_print_in_production(tree, "publicli.py")) == 1
+
+    def test_non_cli_production_file_still_flagged(self) -> None:
+        tree = ast.parse(NEAR_MISS_WITH_PRINT)
+        assert len(check_print_in_production(tree, "stp_preview/renderer.py")) == 1
+
+
+class TestValidateFile:
+    def test_validate_file_flags_bare_except(self, tmp_path: Path) -> None:
+        source_file = tmp_path / "worker.py"
+        source_file.write_text(
+            "def run():\n    try:\n        do_work()\n    except:\n        pass\n",
+            encoding="utf-8",
+        )
+        violations = validate_file(source_file)
+        assert len(violations) == 1
+        assert "except" in violations[0].message.lower()
+
+
+class TestCrossSurfaceConsistency:
+    def test_matches_library_print_surface(self) -> None:
+        source = "def main():\n    print('x')\n"
+        tree = ast.parse(source)
+        for path in (
+            "stp_preview/cli.py",
+            "stp_preview/renderer.py",
+            "publicli.py",
+            "packages/foo/scripts/run_job.py",
+        ):
+            production_allows = check_print_in_production(tree, path) == []
+            library_allows = check_library_print(source, path) == []
+            assert production_allows == library_allows
+
+
+CLI_BASENAME = "cli.py"
+ANTIPATTERN_VALIDATOR_NAME = "Python Anti-patterns"
+PRINT_FINDING_FRAGMENT = "print() in production"
+
+PIPELINE_PRINT_SOURCE = '''
+def emit_status(message):
+    print(message)
+'''
+
+
+def _antipattern_result_for(file_path: str, content: str) -> ValidatorResult:
+    """Return the Python Anti-patterns result for content proposed at file_path."""
+    all_results = validate_proposed_file(file_path, content)
+    return next(
+        each_result
+        for each_result in all_results
+        if each_result.name == ANTIPATTERN_VALIDATOR_NAME
+    )
+
+
+class TestPrintCliExemptionThroughPipeline:
+    """Pin the CLI-marker print exemption through the validate_proposed_file pipeline.
+
+    A basename of cli.py lands in the system temp dir as .../cli.py, so the
+    marker /cli.py matches and the print check stays silent. Near-miss basenames
+    (publicli.py) are covered at the unit surface; the pipeline stages under a
+    temp root that often contains the substring 'test', which short-circuits the
+    print check before the CLI-marker path runs.
+    """
+
+    def test_pins_cli_basename_allows_print_through_pipeline(self) -> None:
+        antipattern_result = _antipattern_result_for(CLI_BASENAME, PIPELINE_PRINT_SOURCE)
+        assert antipattern_result.passed
+        assert PRINT_FINDING_FRAGMENT not in antipattern_result.output

package/hooks/validators/test_run_all_validators_pretooluse.py

@@ -44,6 +44,22 @@ class TestPreToolUseGate:
         assert '"permissionDecision": "deny"' in completed.stdout
         assert "Magic Values" in completed.stdout
 
+    def test_write_violating_content_to_ephemeral_scratch_path_is_allowed(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        monkeypatch.delenv("CLAUDE_CODE_RULES_DISABLE_EPHEMERAL_EXEMPT", raising=False)
+        completed = run_gate(
+            {
+                "tool_name": "Write",
+                "tool_input": {
+                    "file_path": "/tmp/scratch_calculate.py",
+                    "content": VIOLATING_PYTHON_SOURCE,
+                },
+            }
+        )
+        assert completed.returncode == 0, completed.stderr
+        assert "deny" not in completed.stdout
+
     def test_write_with_clean_content_allows(self) -> None:
         completed = run_gate(
             {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "2.0.2",
+    "version": "2.2.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/rules/CLAUDE.md

@@ -53,6 +53,7 @@ Rule files installed into `~/.claude/rules/` by `bin/install.mjs`. A rule withou
 | `tdd.md` | Test-driven development: red → green → refactor, no production code before a failing test |
 | `testing.md` | Test quality and infrastructure standards |
 | `vault-context.md` | Search Obsidian vault for prior sessions and decisions before substantive project work |
+| `verified-commit-gate-skip.md` | The `# verify-skip` marker on a blocked commit/push is allowed only when the branch surface is the same code a code-verifier already passed clean; any real change since that verdict runs a fresh verification |
 | `verify-before-asking.md` | Answer questions by inspecting files or running tools before asking; recalled facts expire until re-checked this session |
 | `verify-runtime-state.md` | A "component is fine / not at fault" verdict rests on a live probe this session, never code reading or prior-session memory |
 | `windows-filesystem-safe.md` | Use safe `rmtree` patterns on Windows; `mkdirSync` with `recursive: true` on possibly-existing paths |

package/rules/verified-commit-gate-skip.md

@@ -0,0 +1,28 @@
+# Verified-Commit-Gate Skip Marker
+
+**When this applies:** A `git commit` or `git push` through the Bash tool is blocked by the `verified_commit_gate` hook.
+
+## The marker
+
+Appending the comment `# verify-skip` as a trailing shell comment to the Bash command exempts that single commit or push from the gate. The hook (`hooks/blocking/verified_commit_gate.py`, marker constant `VERIFICATION_BYPASS_MARKER`) recognizes the marker only when its leading `#` sits at a word boundary and outside every quoted region — a genuine comment, not a data-only mention inside a quoted commit message or `gh` body — and lets the command run without a minted verdict.
+
+## When the marker is allowed
+
+Use it only when both hold:
+
+1. The gate is blocking the command, and
+2. The branch surface content is the same code a `code-verifier` already passed clean — nothing effectively changed since that clean verdict.
+
+That situation arises when the verdict fails to cover the current surface even though the code is the same: a clean verdict that never minted (the verifier's fenced block ran in a resumed turn, so the SubagentStop minter never fired), a surface hash perturbed by index-only staging churn, or a concurrent worktree write that was fully reverted back to the verified content. Before using the marker, confirm the match yourself: the test suite the verifier ran still passes, and the diff holds no content beyond what the clean verdict covered.
+
+## When the marker is not allowed
+
+Every other case runs the verification: spawn the `code-verifier` agent and let the SubagentStop hook mint the verdict. In particular, never use the marker to:
+
+- Skip a branch's first verification.
+- Commit or push after any real code change since the last clean verdict — one changed line means a fresh verification.
+- Work around a verifier that reported findings; findings get repaired and re-verified.
+
+## One command, one exemption
+
+The marker exempts only the command that carries it. The next commit or push on the branch faces the gate again, so a follow-up change still verifies before it lands.