claude-dev-env 1.26.4 → 1.27.0

package/hooks/git-hooks/test_pre_commit.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import pytest
+
+
+SCRIPT_DIRECTORY = Path(__file__).resolve().parent
+if str(SCRIPT_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIRECTORY))
+
+import pre_commit
+
+
+def make_gate_script_returning(exit_code: int, target_path: Path) -> Path:
+    target_path.write_text(
+        f"import sys\nsys.exit({exit_code})\n",
+        encoding="utf-8",
+    )
+    return target_path
+
+
+@pytest.fixture()
+def fake_gate_script_blocking(tmp_path: Path) -> Path:
+    return make_gate_script_returning(1, tmp_path / "fake_gate_blocking.py")
+
+
+@pytest.fixture()
+def fake_gate_script_passing(tmp_path: Path) -> Path:
+    return make_gate_script_returning(0, tmp_path / "fake_gate_passing.py")
+
+
+def test_main_exits_zero_when_gate_script_missing(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv(
+        "CODE_RULES_GATE_PATH",
+        str(tmp_path / "does_not_exist.py"),
+    )
+
+    exit_code = pre_commit.main()
+
+    assert exit_code == 0
+
+
+def test_main_propagates_blocking_exit_code_from_gate(
+    fake_gate_script_blocking: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("CODE_RULES_GATE_PATH", str(fake_gate_script_blocking))
+
+    exit_code = pre_commit.main()
+
+    assert exit_code == 1
+
+
+def test_main_propagates_passing_exit_code_from_gate(
+    fake_gate_script_passing: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("CODE_RULES_GATE_PATH", str(fake_gate_script_passing))
+
+    exit_code = pre_commit.main()
+
+    assert exit_code == 0
+
+
+def test_main_invokes_gate_with_staged_flag(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    recorded_arguments_path = tmp_path / "recorded_arguments.txt"
+    recording_gate_script_path = tmp_path / "recording_gate.py"
+    recording_gate_script_path.write_text(
+        "import sys, pathlib\n"
+        f'pathlib.Path(r"{recorded_arguments_path}").write_text('
+        "'\\n'.join(sys.argv[1:]), encoding='utf-8')\n"
+        "sys.exit(0)\n",
+        encoding="utf-8",
+    )
+    monkeypatch.setenv("CODE_RULES_GATE_PATH", str(recording_gate_script_path))
+
+    exit_code = pre_commit.main()
+
+    assert exit_code == 0
+    assert recorded_arguments_path.exists(), (
+        f"recording gate did not write to {recorded_arguments_path}"
+    )
+    recorded_arguments = recorded_arguments_path.read_text(
+        encoding="utf-8"
+    ).splitlines()
+    assert recorded_arguments == ["--staged"]
+
+
+def test_main_exits_two_when_invoke_gate_raises_oserror(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    existing_gate_path = tmp_path / "gate.py"
+    existing_gate_path.write_text("import sys\nsys.exit(0)\n", encoding="utf-8")
+    monkeypatch.setenv("CODE_RULES_GATE_PATH", str(existing_gate_path))
+
+    original_run = __import__("subprocess").run
+
+    def raising_run(*args: object, **kwargs: object) -> object:
+        raise OSError("no such file")
+
+    monkeypatch.setattr(__import__("subprocess"), "run", raising_run)
+
+    exit_code = pre_commit.main()
+
+    assert exit_code == 2
+
+
+def test_main_emits_stderr_warning_when_gate_script_missing(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    monkeypatch.setenv(
+        "CODE_RULES_GATE_PATH",
+        str(tmp_path / "does_not_exist.py"),
+    )
+
+    exit_code = pre_commit.main()
+
+    assert exit_code == 0
+    captured = capsys.readouterr()
+    assert "gate script not found" in captured.err
+
+
+def test_invoke_gate_returns_infrastructure_failure_when_strict_resolve_raises(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    missing_gate_path = tmp_path / "missing_gate.py"
+    monkeypatch.setenv("CODE_RULES_GATE_PATH", str(missing_gate_path))
+    missing_gate_path.write_text("import sys\nsys.exit(0)\n", encoding="utf-8")
+
+    original_resolve = Path.resolve
+
+    def raising_resolve(self: Path, strict: bool = False) -> Path:
+        if strict and self == missing_gate_path.resolve():
+            raise FileNotFoundError("not found")
+        return original_resolve(self, strict=strict)
+
+    monkeypatch.setattr(Path, "resolve", raising_resolve)
+
+    exit_code = pre_commit.invoke_gate(missing_gate_path)
+
+    assert exit_code == 2
+
+
+def test_invoke_gate_uses_resolved_path(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    real_gate_dir = tmp_path / "real"
+    real_gate_dir.mkdir()
+    real_gate_path = real_gate_dir / "gate.py"
+    recorded_path_file = tmp_path / "recorded_path.txt"
+    real_gate_path.write_text(
+        "import sys, pathlib\n"
+        f'pathlib.Path(r"{recorded_path_file}").write_text(sys.argv[0], encoding="utf-8")\n'
+        "sys.exit(0)\n",
+        encoding="utf-8",
+    )
+    symlink_gate_path = tmp_path / "link_gate.py"
+    symlink_gate_path.symlink_to(real_gate_path)
+    resolved_path = symlink_gate_path.resolve()
+    monkeypatch.setenv("CODE_RULES_GATE_PATH", str(symlink_gate_path))
+
+    exit_code = pre_commit.main()
+
+    assert exit_code == 0
+    executed_path = recorded_path_file.read_text(encoding="utf-8")
+    assert executed_path == str(resolved_path)

package/hooks/git-hooks/test_pre_push.py

@@ -0,0 +1,316 @@
+from __future__ import annotations
+
+import io
+import sys
+from pathlib import Path
+
+import pytest
+
+
+SCRIPT_DIRECTORY = Path(__file__).resolve().parent
+if str(SCRIPT_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIRECTORY))
+
+import pre_push
+import config
+
+
+ALL_ZEROS_OBJECT_NAME: str = "0" * 40
+NON_ZERO_LOCAL_SHA: str = "a" * 40
+NON_ZERO_REMOTE_SHA_ONE: str = "1" * 40
+NON_ZERO_REMOTE_SHA_TWO: str = "2" * 40
+
+
+def test_resolve_base_reference_uses_remote_object_when_non_zero() -> None:
+    stdin_text = (
+        f"refs/heads/feature {NON_ZERO_LOCAL_SHA} refs/heads/feature {NON_ZERO_REMOTE_SHA_ONE}\n"
+    )
+
+    base_reference = pre_push.resolve_base_reference_from_stdin(stdin_text)
+
+    assert base_reference == NON_ZERO_REMOTE_SHA_ONE
+
+
+def test_resolve_base_reference_falls_back_when_remote_is_all_zeros() -> None:
+    stdin_text = f"refs/heads/feature {NON_ZERO_LOCAL_SHA} refs/heads/feature {ALL_ZEROS_OBJECT_NAME}\n"
+
+    base_reference = pre_push.resolve_base_reference_from_stdin(stdin_text)
+
+    assert base_reference == pre_push.DEFAULT_REMOTE_BASE_REFERENCE
+
+
+def test_resolve_base_reference_falls_back_when_stdin_empty() -> None:
+    base_reference = pre_push.resolve_base_reference_from_stdin("")
+
+    assert base_reference == pre_push.DEFAULT_REMOTE_BASE_REFERENCE
+
+
+def test_resolve_base_reference_prefers_first_non_zero_remote_object_among_many() -> (
+    None
+):
+    stdin_text = (
+        f"refs/heads/new_branch {ALL_ZEROS_OBJECT_NAME} refs/heads/new_branch {ALL_ZEROS_OBJECT_NAME}\n"
+        f"refs/heads/existing {NON_ZERO_LOCAL_SHA} refs/heads/existing {NON_ZERO_REMOTE_SHA_TWO}\n"
+    )
+
+    base_reference = pre_push.resolve_base_reference_from_stdin(stdin_text)
+
+    assert base_reference == NON_ZERO_REMOTE_SHA_TWO
+
+
+def test_main_exits_zero_when_gate_script_missing(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv(
+        "CODE_RULES_GATE_PATH",
+        str(tmp_path / "does_not_exist.py"),
+    )
+    monkeypatch.setattr(sys, "stdin", io.StringIO(""))
+
+    exit_code = pre_push.main()
+
+    assert exit_code == 0
+
+
+def test_main_invokes_gate_with_resolved_base_reference(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    recorded_arguments_path = tmp_path / "recorded_arguments.txt"
+    recording_gate_script_path = tmp_path / "recording_gate.py"
+    recording_gate_script_path.write_text(
+        "import sys, pathlib\n"
+        f'pathlib.Path(r"{recorded_arguments_path}").write_text('
+        "'\\n'.join(sys.argv[1:]), encoding='utf-8')\n"
+        "sys.exit(0)\n",
+        encoding="utf-8",
+    )
+    monkeypatch.setenv("CODE_RULES_GATE_PATH", str(recording_gate_script_path))
+    remote_sha = "9" * 40
+    monkeypatch.setattr(
+        sys,
+        "stdin",
+        io.StringIO(f"refs/heads/feature {NON_ZERO_LOCAL_SHA} refs/heads/feature {remote_sha}\n"),
+    )
+
+    exit_code = pre_push.main()
+
+    assert exit_code == 0
+    assert recorded_arguments_path.exists(), (
+        f"recording gate did not write to {recorded_arguments_path}"
+    )
+    recorded_arguments = recorded_arguments_path.read_text(
+        encoding="utf-8"
+    ).splitlines()
+    assert recorded_arguments == ["--base", remote_sha]
+
+
+def test_main_propagates_blocking_exit_code_from_gate(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    blocking_gate_script_path = tmp_path / "blocking_gate.py"
+    blocking_gate_script_path.write_text(
+        "import sys\nsys.exit(1)\n",
+        encoding="utf-8",
+    )
+    monkeypatch.setenv("CODE_RULES_GATE_PATH", str(blocking_gate_script_path))
+    monkeypatch.setattr(sys, "stdin", io.StringIO(""))
+
+    exit_code = pre_push.main()
+
+    assert exit_code == 1
+
+
+def test_main_propagates_infrastructure_failure_exit_code_from_gate(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    infrastructure_failure_gate_path = tmp_path / "infrastructure_failure_gate.py"
+    infrastructure_failure_gate_path.write_text(
+        "import sys\nsys.exit(2)\n",
+        encoding="utf-8",
+    )
+    monkeypatch.setenv("CODE_RULES_GATE_PATH", str(infrastructure_failure_gate_path))
+    monkeypatch.setattr(sys, "stdin", io.StringIO(""))
+
+    exit_code = pre_push.main()
+
+    assert exit_code == 2
+
+
+def test_main_exits_two_when_stdin_raises_ioerror(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    gate_path = tmp_path / "gate.py"
+    gate_path.write_text("import sys\nsys.exit(0)\n", encoding="utf-8")
+    monkeypatch.setenv("CODE_RULES_GATE_PATH", str(gate_path))
+
+    class RaisingStdin:
+        def read(self) -> str:
+            raise IOError("broken pipe")
+
+    monkeypatch.setattr(sys, "stdin", RaisingStdin())
+
+    exit_code = pre_push.main()
+
+    assert exit_code == config.GATE_INFRASTRUCTURE_FAILURE_EXIT_CODE
+
+
+def test_main_exits_two_when_invoke_gate_raises_oserror(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    gate_path = tmp_path / "gate.py"
+    gate_path.write_text("import sys\nsys.exit(0)\n", encoding="utf-8")
+    monkeypatch.setenv("CODE_RULES_GATE_PATH", str(gate_path))
+    monkeypatch.setattr(sys, "stdin", io.StringIO(""))
+
+    def raising_run(*args: object, **kwargs: object) -> object:
+        raise OSError("no such file")
+
+    monkeypatch.setattr(__import__("subprocess"), "run", raising_run)
+
+    exit_code = pre_push.main()
+
+    assert exit_code == config.GATE_INFRASTRUCTURE_FAILURE_EXIT_CODE
+
+
+def test_resolve_base_reference_emits_warning_for_malformed_line(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    malformed_stdin_text = "only_one_field\n"
+
+    pre_push.resolve_base_reference_from_stdin(malformed_stdin_text)
+
+    captured = capsys.readouterr()
+    assert "malformed" in captured.err
+
+
+def test_resolve_base_reference_returns_none_when_local_sha_is_all_zeros() -> None:
+    stdin_text = f"refs/heads/feature {ALL_ZEROS_OBJECT_NAME} refs/heads/feature {ALL_ZEROS_OBJECT_NAME}\n"
+
+    base_reference = pre_push.resolve_base_reference_from_stdin(stdin_text)
+
+    assert base_reference is None
+
+
+def test_main_exits_zero_immediately_when_push_is_deletion(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    gate_path = tmp_path / "gate.py"
+    gate_path.write_text("import sys\nsys.exit(1)\n", encoding="utf-8")
+    monkeypatch.setenv("CODE_RULES_GATE_PATH", str(gate_path))
+    deletion_stdin = f"refs/heads/feature {ALL_ZEROS_OBJECT_NAME} refs/heads/feature {ALL_ZEROS_OBJECT_NAME}\n"
+    monkeypatch.setattr(sys, "stdin", io.StringIO(deletion_stdin))
+
+    exit_code = pre_push.main()
+
+    assert exit_code == 0
+
+
+def test_resolve_base_reference_returns_sentinel_when_only_malformed_lines_present(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    malformed_only_stdin = "one_field_only\nalso_malformed\n"
+
+    base_reference = pre_push.resolve_base_reference_from_stdin(malformed_only_stdin)
+
+    assert base_reference == config.NO_PARSEABLE_STDIN_LINES_SENTINEL
+
+
+def test_main_prints_stderr_when_gate_script_missing(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    monkeypatch.setenv(
+        "CODE_RULES_GATE_PATH",
+        str(tmp_path / "does_not_exist.py"),
+    )
+    monkeypatch.setattr(sys, "stdin", io.StringIO(""))
+
+    pre_push.main()
+
+    captured = capsys.readouterr()
+    assert captured.err != ""
+
+
+def test_resolve_base_reference_exits_two_when_only_malformed_lines_and_no_valid_lines(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    malformed_only_stdin = "one_field_only\nalso_malformed\n"
+
+    result = pre_push.resolve_base_reference_from_stdin(malformed_only_stdin)
+
+    assert result == config.NO_PARSEABLE_STDIN_LINES_SENTINEL
+
+
+def test_main_exits_two_when_all_stdin_lines_are_malformed(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    gate_path = tmp_path / "gate.py"
+    gate_path.write_text("import sys\nsys.exit(0)\n", encoding="utf-8")
+    monkeypatch.setenv("CODE_RULES_GATE_PATH", str(gate_path))
+    monkeypatch.setattr(sys, "stdin", io.StringIO("one_field_only\nalso_malformed\n"))
+
+    exit_code = pre_push.main()
+
+    assert exit_code == config.GATE_INFRASTRUCTURE_FAILURE_EXIT_CODE
+    captured = capsys.readouterr()
+    assert "no parseable stdin lines" in captured.err
+
+
+def test_invoke_gate_returns_infrastructure_failure_when_strict_resolve_raises(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    gate_path = tmp_path / "gate.py"
+    gate_path.write_text("import sys\nsys.exit(0)\n", encoding="utf-8")
+
+    original_resolve = Path.resolve
+
+    def raising_resolve(self: Path, strict: bool = False) -> Path:
+        if strict and self == gate_path.resolve():
+            raise FileNotFoundError("not found")
+        return original_resolve(self, strict=strict)
+
+    monkeypatch.setattr(Path, "resolve", raising_resolve)
+
+    exit_code = pre_push.invoke_gate(gate_path, "origin/main")
+
+    assert exit_code == 2
+
+
+def test_invoke_gate_uses_resolved_path(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    real_gate_dir = tmp_path / "real"
+    real_gate_dir.mkdir()
+    real_gate_path = real_gate_dir / "gate.py"
+    recorded_path_file = tmp_path / "recorded_path.txt"
+    real_gate_path.write_text(
+        "import sys, pathlib\n"
+        f'pathlib.Path(r"{recorded_path_file}").write_text(sys.argv[0], encoding="utf-8")\n'
+        "sys.exit(0)\n",
+        encoding="utf-8",
+    )
+    symlink_gate_path = tmp_path / "link_gate.py"
+    symlink_gate_path.symlink_to(real_gate_path)
+    resolved_path = symlink_gate_path.resolve()
+    monkeypatch.setenv("CODE_RULES_GATE_PATH", str(symlink_gate_path))
+    monkeypatch.setattr(sys, "stdin", io.StringIO(
+        f"refs/heads/feature {NON_ZERO_LOCAL_SHA} refs/heads/feature {NON_ZERO_REMOTE_SHA_ONE}\n"
+    ))
+
+    exit_code = pre_push.main()
+
+    assert exit_code == 0
+    executed_path = recorded_path_file.read_text(encoding="utf-8")
+    assert executed_path == str(resolved_path)

package/hooks/hooks.json

@@ -35,11 +35,6 @@
             "command": "python3 -c \"import sys; sys.path.insert(0, r'${CLAUDE_PLUGIN_ROOT}/hooks'); from validators.run_all_validators import main; sys.exit(main())\"",
             "timeout": 15
           },
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/code_rules_enforcer.py",
-            "timeout": 15
-          },
           {
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/tdd_enforcer.py",

package/package.json

@@ -1,11 +1,14 @@
 {
     "name": "claude-dev-env",
-    "version": "1.26.4",
+    "version": "1.27.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {
         "claude-dev-env": "bin/install.mjs"
     },
+    "scripts": {
+        "test": "node --test bin/*.test.mjs"
+    },
     "files": [
         "bin/",
         "rules/",

package/skills/bugteam/scripts/bugteam_code_rules_gate.py

@@ -89,6 +89,130 @@ def filter_paths_under_prefixes(
     return filtered
 
 
+def paths_from_git_staged(repository_root: Path) -> list[Path]:
+    name_result = subprocess.run(
+        ["git", "diff", "--cached", "--name-only", "-z"],
+        cwd=str(repository_root),
+        capture_output=True,
+        check=False,
+    )
+    if name_result.returncode != 0:
+        stderr_text = name_result.stderr.decode("utf-8", errors="replace")
+        print(
+            f"bugteam_code_rules_gate: git diff --cached --name-only -z failed:\n{stderr_text}",
+            file=sys.stderr,
+        )
+        raise SystemExit(2)
+    raw_paths = name_result.stdout.split(b"\x00")
+    resolved_paths = []
+    for each_raw_path in raw_paths:
+        if not each_raw_path:
+            continue
+        try:
+            relative_path = each_raw_path.decode("utf-8")
+        except UnicodeDecodeError:
+            print(
+                f"bugteam_code_rules_gate: skipping staged path with non-UTF-8 filename: {each_raw_path!r}",
+                file=sys.stderr,
+            )
+            continue
+        resolved_paths.append(repository_root / relative_path)
+    return resolved_paths
+
+
+def staged_file_line_count(
+    repository_root: Path,
+    relative_path_posix: str,
+) -> int:
+    show_result = subprocess.run(
+        ["git", "show", f":{relative_path_posix}"],
+        cwd=str(repository_root),
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        check=False,
+    )
+    if show_result.returncode != 0:
+        return 0
+    staged_content = show_result.stdout
+    if not staged_content:
+        return 0
+    return len(staged_content.splitlines())
+
+
+def is_staged_file_newly_added(
+    repository_root: Path,
+    relative_path_posix: str,
+) -> bool:
+    status_result = subprocess.run(
+        ["git", "diff", "--cached", "--name-status", "--", relative_path_posix],
+        cwd=str(repository_root),
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        check=False,
+    )
+    if status_result.returncode != 0:
+        return False
+    for each_line in status_result.stdout.splitlines():
+        stripped_line = each_line.strip()
+        if stripped_line:
+            return stripped_line.startswith("A")
+    return False
+
+
+def added_lines_for_staged_file(
+    repository_root: Path,
+    relative_path_posix: str,
+) -> set[int]:
+    diff_result = subprocess.run(
+        ["git", "diff", "--cached", "--unified=0", "--", relative_path_posix],
+        cwd=str(repository_root),
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        check=False,
+    )
+    if diff_result.returncode != 0:
+        print(
+            f"bugteam_code_rules_gate: git diff --cached --unified=0 failed for {relative_path_posix}:\n"
+            f"{diff_result.stderr}",
+            file=sys.stderr,
+        )
+        raise SystemExit(2)
+    if diff_result.stdout.strip():
+        return parse_added_line_numbers(diff_result.stdout)
+    if is_staged_file_newly_added(repository_root, relative_path_posix):
+        total_lines = staged_file_line_count(repository_root, relative_path_posix)
+        if total_lines > 0:
+            return set(range(1, total_lines + 1))
+    return set()
+
+
+def added_lines_by_file_staged(
+    repository_root: Path,
+    file_paths: list[Path],
+) -> dict[Path, set[int]]:
+    resolved_root = repository_root.resolve()
+    added_by_path: dict[Path, set[int]] = {}
+    for each_path in file_paths:
+        try:
+            resolved = each_path.resolve()
+        except OSError:
+            continue
+        try:
+            relative = resolved.relative_to(resolved_root)
+        except ValueError:
+            continue
+        relative_posix = str(relative).replace("\\", "/")
+        added_numbers = added_lines_for_staged_file(resolved_root, relative_posix)
+        added_by_path[resolved] = added_numbers
+    return added_by_path
+
+
 def paths_from_git_diff(repository_root: Path, base_reference: str) -> list[Path]:
     merge_base = resolve_merge_base(repository_root, base_reference)
     name_result = subprocess.run(
@@ -337,6 +461,16 @@ def parse_arguments(argv: list[str]) -> argparse.Namespace:
         default="origin/main",
         help="Merge-base ref for git diff (default: origin/main).",
     )
+    parser.add_argument(
+        "--staged",
+        action="store_true",
+        default=False,
+        help=(
+            "Scope to staged changes only (git diff --cached). "
+            "Blocks on violations introduced on staged-added lines; "
+            "reports pre-existing violations in touched files as advisory."
+        ),
+    )
     parser.add_argument(
         "--only-under",
         action="append",
@@ -368,6 +502,22 @@ def main(argv: list[str] | None = None) -> int:
     if arguments.paths:
         file_paths = [repository_root / path for path in arguments.paths]
         return run_gate(validate_content, file_paths, repository_root, added_lines_map=None)
+    if arguments.staged:
+        staged_file_paths = paths_from_git_staged(repository_root)
+        staged_file_paths = filter_paths_under_prefixes(
+            staged_file_paths,
+            repository_root,
+            arguments.only_under,
+        )
+        if not staged_file_paths:
+            return 0
+        staged_added_lines = added_lines_by_file_staged(repository_root, staged_file_paths)
+        return run_gate(
+            validate_content,
+            staged_file_paths,
+            repository_root,
+            added_lines_map=staged_added_lines,
+        )
     file_paths = paths_from_git_diff(repository_root, arguments.base)
     file_paths = filter_paths_under_prefixes(
         file_paths,