claude-dev-env 2.32.0 → 2.33.0

package/hooks/blocking/test_code_rules_enforcer_comment_string_awareness.py

@@ -14,6 +14,7 @@ a string still flag.
 from __future__ import annotations
 
 import sys
+import importlib
 from pathlib import Path
 from types import SimpleNamespace
 
@@ -31,12 +32,12 @@ from code_rules_comments import (  # noqa: E402
     check_comments_python,
     extract_comment_texts,
 )
-
 code_rules_enforcer = SimpleNamespace(
     check_comment_changes=check_comment_changes,
     check_comments_python=check_comments_python,
     extract_comment_texts=extract_comment_texts,
 )
+code_rules_enforcer_module = importlib.import_module("code_rules_enforcer")
 
 
 def test_python_check_should_not_flag_hex_color_literal() -> None:
@@ -121,7 +122,7 @@ def test_check_comment_changes_skips_removal_when_old_python_un_parseable() -> N
     assert issues == []
 
 
-def test_check_comment_changes_advises_without_blocking_on_removal_on_parseable_python(
+def test_check_comment_changes_allows_comment_removal_without_advisory(
     capsys: pytest.CaptureFixture[str],
 ) -> None:
     old_content = 'x = 1  # existing comment\n'
@@ -129,7 +130,7 @@ def test_check_comment_changes_advises_without_blocking_on_removal_on_parseable_
     issues = code_rules_enforcer.check_comment_changes(old_content, new_content, "foo.py")
     assert not any("Existing comment removed" in each_issue for each_issue in issues)
     captured = capsys.readouterr()
-    assert "[CODE_RULES advisory] Existing comment removed" in captured.err
+    assert captured.err == ""
 
 
 def test_python_check_should_exempt_directive_without_space_after_hash() -> None:
@@ -194,3 +195,189 @@ def test_extract_should_classify_inline_shebang_lookalike_as_inline_comment() ->
     inline, standalone = code_rules_enforcer.extract_comment_texts(content, "foo.py")
     assert inline != set()
     assert standalone == set()
+
+
+def test_full_gate_blocks_python_inline_comment_in_test_file() -> None:
+    context = code_rules_enforcer_module._ValidationContext(
+        content="total = 1  # added\n",
+        old_content="total = 1\n",
+        effective_content="total = 1  # added\n",
+        file_path="test_totals.py",
+        all_changed_lines=None,
+        defer_scope_to_caller=False,
+        sibling_directory=None,
+        phase="edit",
+    )
+    issues = code_rules_enforcer_module.validate_content_for_full_gate(context.content, context.file_path, context.old_content)
+    assert any("Inline comment added" in each_issue for each_issue in issues)
+
+
+def test_full_gate_blocks_javascript_inline_comment_in_test_file() -> None:
+    context = code_rules_enforcer_module._ValidationContext(
+        content="const total = 1; // added\n",
+        old_content="const total = 1;\n",
+        effective_content="const total = 1; // added\n",
+        file_path="totals.test.js",
+        all_changed_lines=None,
+        defer_scope_to_caller=False,
+        sibling_directory=None,
+        phase="edit",
+    )
+    issues = code_rules_enforcer_module.validate_content_for_full_gate(context.content, context.file_path, context.old_content)
+    assert any("Inline comment added" in each_issue for each_issue in issues)
+
+
+def test_full_gate_blocks_javascript_inline_block_comment_in_test_file() -> None:
+    context = code_rules_enforcer_module._ValidationContext(
+        content="const total = 1; /* added */\n",
+        old_content="const total = 1;\n",
+        effective_content="const total = 1; /* added */\n",
+        file_path="totals.test.js",
+        all_changed_lines=None,
+        defer_scope_to_caller=False,
+        sibling_directory=None,
+        phase="edit",
+    )
+    issues = code_rules_enforcer_module.validate_content_for_full_gate(context.content, context.file_path, context.old_content)
+    assert any("Inline comment added" in each_issue for each_issue in issues)
+
+
+def test_full_gate_blocks_javascript_directive_comment_in_test_file() -> None:
+    context = code_rules_enforcer_module._ValidationContext(
+        content="const total = 1; // eslint-disable-next-line\n",
+        old_content="const total = 1;\n",
+        effective_content="const total = 1; // eslint-disable-next-line\n",
+        file_path="totals.test.js",
+        all_changed_lines=None,
+        defer_scope_to_caller=False,
+        sibling_directory=None,
+        phase="edit",
+    )
+    issues = code_rules_enforcer_module.validate_content_for_full_gate(context.content, context.file_path, context.old_content)
+    assert any("Inline comment added" in each_issue for each_issue in issues)
+
+
+def test_full_gate_blocks_python_directive_comment_in_test_file() -> None:
+    context = code_rules_enforcer_module._ValidationContext(
+        content="total = 1  # noqa\n",
+        old_content="total = 1\n",
+        effective_content="total = 1  # noqa\n",
+        file_path="test_totals.py",
+        all_changed_lines=None,
+        defer_scope_to_caller=False,
+        sibling_directory=None,
+        phase="edit",
+    )
+    issues = code_rules_enforcer_module.validate_content_for_full_gate(context.content, context.file_path, context.old_content)
+    assert any("comment added" in each_issue.lower() for each_issue in issues)
+
+
+@pytest.mark.parametrize(
+    "each_marker", ("# TODO #999: track", "# FIXME #999: track", "# HACK #999: track", "# XXX #999: track", "# type: ignore[misc]")
+)
+def test_full_gate_blocks_changed_marker_comments_in_test_file(each_marker: str) -> None:
+    context = code_rules_enforcer_module._ValidationContext(
+        content=f"total = 1  {each_marker}\n",
+        old_content="total = 1\n",
+        effective_content=f"total = 1  {each_marker}\n",
+        file_path="test_totals.py",
+        all_changed_lines=None,
+        defer_scope_to_caller=False,
+        sibling_directory=None,
+        phase="edit",
+    )
+    issues = code_rules_enforcer_module.validate_content_for_full_gate(context.content, context.file_path, context.old_content)
+    assert any("comment added" in each_issue.lower() for each_issue in issues)
+
+
+def test_full_gate_blocks_standalone_comment_in_test_file() -> None:
+    context = code_rules_enforcer_module._ValidationContext(
+        content="# added\ntotal = 1\n",
+        old_content="total = 1\n",
+        effective_content="# added\ntotal = 1\n",
+        file_path="test_totals.py",
+        all_changed_lines=None,
+        defer_scope_to_caller=False,
+        sibling_directory=None,
+        phase="edit",
+    )
+    issues = code_rules_enforcer_module.validate_content_for_full_gate(context.content, context.file_path, context.old_content)
+    assert any("Standalone comment added" in each_issue for each_issue in issues)
+
+
+def test_full_gate_preserves_shebang_and_docstring_in_test_file() -> None:
+    context = code_rules_enforcer_module._ValidationContext(
+        content='#!/usr/bin/env python3\n"""Describe totals."""\ntotal = 1\n',
+        old_content="#!/usr/bin/env python3\n",
+        effective_content='#!/usr/bin/env python3\n"""Describe totals."""\ntotal = 1\n',
+        file_path="test_totals.py",
+        all_changed_lines=None,
+        defer_scope_to_caller=False,
+        sibling_directory=None,
+        phase="edit",
+    )
+    issues = code_rules_enforcer_module.validate_content_for_full_gate(context.content, context.file_path, context.old_content)
+    assert not any("comment added" in each_issue.lower() for each_issue in issues)
+
+
+def test_full_gate_allows_existing_comment_removal_without_advisory(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    context = code_rules_enforcer_module._ValidationContext(
+        content="total = 1\n",
+        old_content="total = 1  # existing\n",
+        effective_content="total = 1\n",
+        file_path="test_totals.py",
+        all_changed_lines=None,
+        defer_scope_to_caller=False,
+        sibling_directory=None,
+        phase="edit",
+    )
+    issues = code_rules_enforcer_module.validate_content_for_full_gate(context.content, context.file_path, context.old_content)
+    assert not any("Existing comment removed" in each_issue for each_issue in issues)
+    assert capsys.readouterr().err == ""
+
+
+@pytest.mark.parametrize(
+    ("file_path", "old_content", "new_content"),
+    (
+        ("totals.py", "total = 1\n", "total = 2  # TODO #999: track\n"),
+        ("test_totals.py", "total = 1\n", "total = 2  # TODO #999: track\n"),
+        ("totals.js", "const total = 1;\n", "const total = 2; // eslint-disable-next-line\n"),
+        ("totals.test.js", "const total = 1;\n", "const total = 2; // eslint-disable-next-line\n"),
+    ),
+)
+def test_edit_lane_does_not_report_comment_policy(
+    file_path: str, old_content: str, new_content: str
+) -> None:
+    issues = code_rules_enforcer_module.validate_content_for_edit_lane(
+        new_content, file_path, old_content
+    )
+    assert not any("comment" in each_issue.lower() for each_issue in issues)
+
+
+@pytest.mark.parametrize(
+    ("file_path", "old_content", "new_content"),
+    (
+        ("totals.py", "total = 1  # TODO #999: track\n", "total = 2  # TODO #999: track\n"),
+        ("totals.py", "# TODO #999: track\ntotal = 1\n", "# TODO #999: track\ntotal = 2\n"),
+        ("totals.py", "total = 1  # noqa\n", "total = 2  # noqa\n"),
+        (
+            "totals.js",
+            "const total = 1; // eslint-disable-next-line\n",
+            "const total = 2; // eslint-disable-next-line\n",
+        ),
+    ),
+)
+def test_check_comment_changes_blocks_retained_comments_on_changed_code(
+    file_path: str, old_content: str, new_content: str
+) -> None:
+    issues = code_rules_enforcer.check_comment_changes(old_content, new_content, file_path)
+    assert any("retained on changed code" in each_issue for each_issue in issues)
+
+
+def test_check_comment_changes_accepts_distant_untouched_comment() -> None:
+    old_content = "# TODO #999: distant note\n\ntotal = 1\n"
+    new_content = "# TODO #999: distant note\n\ntotal = 2\n"
+    issues = code_rules_enforcer.check_comment_changes(old_content, new_content, "totals.py")
+    assert not any("retained on changed code" in each_issue for each_issue in issues)

package/hooks/blocking/test_code_rules_enforcer_javascript_comments.py

@@ -0,0 +1,44 @@
+"""Tests for JavaScript comment extraction and diff occurrence reporting."""
+
+from __future__ import annotations
+
+import importlib
+import sys
+from pathlib import Path
+
+_BLOCKING_DIRECTORY = str(Path(__file__).resolve().parent)
+_HOOKS_DIRECTORY = str(Path(__file__).resolve().parent.parent)
+if _BLOCKING_DIRECTORY not in sys.path:
+    sys.path.insert(0, _BLOCKING_DIRECTORY)
+if _HOOKS_DIRECTORY not in sys.path:
+    sys.path.insert(0, _HOOKS_DIRECTORY)
+
+check_comment_changes = importlib.import_module(
+    "code_rules_comments"
+).check_comment_changes
+
+
+def test_check_comment_changes_ignores_javascript_url_string() -> None:
+    issues = check_comment_changes(
+        "", 'const docsUrl = "https://example.com/guide";\n', "docs.js"
+    )
+
+    assert issues == []
+
+
+def test_check_comment_changes_reports_javascript_comment_line() -> None:
+    issues = check_comment_changes(
+        "", 'const total = 1;\nconst next = 2; // added\n', "totals.js"
+    )
+
+    assert any("Line 2: Inline comment added" in each_issue for each_issue in issues)
+
+
+def test_check_comment_changes_reports_duplicate_identical_comment_occurrence() -> None:
+    issues = check_comment_changes(
+        "total = 1  # repeated\n",
+        "total = 1  # repeated\ntotal = 2  # repeated\n",
+        "totals.py",
+    )
+
+    assert any("Line 2: Inline comment added" in each_issue for each_issue in issues)

package/hooks/blocking/test_code_rules_enforcer_join_separator_magic.py

@@ -74,7 +74,6 @@ def test_should_grandfather_unchanged_join_separator_in_wide_edit() -> None:
     )
     proposed_fragment = (
         "def render(all_paths: list) -> str:\n"
-        "    # keep the join separator the same\n"
         "    return ', '.join(str(each_path) for each_path in all_paths)\n"
     )
     issues = code_rules_enforcer.validate_content_for_full_gate(

package/hooks/git-hooks/pull_request_handoff.py

@@ -28,5 +28,5 @@ def get_pull_request_url(repo_dir: Path) -> str | None:
 
 
 def build_pull_request_reminder(url: str) -> str:
-    prompt = "Review this pull request: <PR link>\n\nRead the PR and its full diff. Do not use the branch name, commit message, labels, current title, or a shallow summary.\n\nFind the main thing this adds for a user, caller, or operator.\n\nWrite like the reader is smart but knows nothing about this code. Pretend they asked you to explain it like they are five and feel stupid. If a word needs another sentence to explain it, replace the word — or turn it into a tiny story.\n\nYour job is not a dry API blurb. Your job is an illustrative before/after a person can picture.\n\nGold voice for titles and “What this adds”:\n\nThe theme package has a phone icon somewhere. We need to find it.\n\nBefore: yell “anyone know how to find icons?” and wait for a hand.\n\nAfter: call the finder by its name tag: “icon finder, go.”\n\nThat’s all “operation id” is — the finder’s name tag.\n\nRules for that voice:\n\nStart from a concrete scene (what’s in someone’s hand, what they’re hunting for).\nPrefer Before / After when the change is “how you ask” or “how you look it up.”\nUse picture words: hand it, open, find, check, save, skip, stop, call by name, name tag.\nPrefer spoken results: “found it,” “missing,” “duplicated,” “couldn’t.”\nWhen the diff uses an abstract word (operation id, registry, envelope, adapter, digest, schema), do one of two things:\nDrop it and say what the person does with their hands, or\nKeep it once, then gloss it in the same breath with a name-tag / mailbox / checklist metaphor — like the “finder’s name tag” line above.\nNever leave jargon unexplained. Never write as if the reader already knows the jargon.\nAdd a tiny concrete example in parentheses when a name is abstract (like “the phone icon”).\nFew words. Small words. Clear on first read.\nReturn:\n\nRecommended title\n\nFew words. Small words. Clear on first read.\nSay what you hand it, what it does, and what you get back — or the Before/After of how you ask.\nPrefer picture words and spoken results.\nGood title: “Call the icon finder by its name tag instead of asking around”\nGood title: “Given a theme STP and an asset name, report whether that asset was found, missing, or duplicated”\nBad title: anything that only says operation id / registry / typed envelope / adapter / digest / schema with no picture.\nUse “Add” only if it helps. Do not force it.\nNo vague words like “improve,” “enhance,” or “update.”\nReturn one title only.\nWhy this title fits\n\n1–2 short sentences in the same voice.\nIf needed, one Before / After beat, then what you get back.\nIf this section is needed to decode the title, rewrite the title.\nEvidence\n\nKey files or functions that support the title.\nIf you cannot read the PR or full diff, say so and do not propose a title.\n\nThen write a short, paste-ready PR description.\n\nUse this structure:\n\nWhat this adds\n1–2 short paragraphs in that illustrative voice. Lead with a scene when you can (“The theme package has a phone icon somewhere…”). If the change is a new way to ask, use Before / After. Say what you give it, what it does with its hands, and what you get back. If an abstract machine-word must appear, gloss it immediately (“That’s all X is — …”). Describe the job people can see. Do not describe inner machinery. Mention a check only if it is central to the feature. If there are many changes, keep the main one. Mention others only if they explain the main one.\n\nWhy\nOne short paragraph. Same plain level. Say who needs this and what goes wrong without it (the “yell and wait for a hand” problem). If this is needed to decode the feature, rewrite “What this adds.”\n\nVerification\nList only proof from the PR, CI, or your own checks.\n\nReported in the PR\n\n…\nChecked by you / CI here\n\n…\nRules:\n\nFew words. Small words. Clear on first read. ELI5 I-am-stupid mark.\nDo not invent behavior, tests, or benefits.\nStrip branch names, hashes, draft notes, agent notes, and merge notes.\nNo vague words like “improve,” “enhance,” or “update.”\nIllustrative first. Abstract labels only if glossed in the same breath.\nUse the recommended title and paste-ready description to run `gh pr edit <PR link> --title ... --body-file ...`, then run `gh pr view <PR link> --json title,body` to confirm the saved title and body. Report the saved result."
+    prompt = "Review this pull request: <PR link>\n\nRead the PR and its full diff. Do not use the branch name, commit message, labels, current title, or a shallow summary.\n\nBefore writing, inventory every independently observable behavior in the full diff. A behavior is independent when a user, caller, operator, automation, output, error, exit status, fallback, or side effect can observe it separately. Lead with the central behavior for readability, then give every other behavior its own short paragraph or bullet.\n\nFor each behavior, state the trigger or observer, the Before -> After result, the affected surface/caller when shared, and focused proof. Include important preserved behavior and fallback paths when they help a coder rule a regression in or out. Describe outcomes, not line-by-line implementation, and do not hide multiple behaviors under vague umbrella wording.\n\nWrite like the reader is smart but knows nothing about this code. Pretend they asked you to explain it like they are five and feel stupid. If a word needs another sentence to explain it, replace the word — or turn it into a tiny story.\n\nYour job is not a dry API blurb. Your job is an illustrative before/after a person can picture.\n\nGold voice for titles and “What this adds”:\n\nThe theme package has a phone icon somewhere. We need to find it.\n\nBefore: yell “anyone know how to find icons?” and wait for a hand.\n\nAfter: call the finder by its name tag: “icon finder, go.”\n\nThat’s all “operation id” is — the finder’s name tag.\n\nRules for that voice:\n\nStart from a concrete scene (what’s in someone’s hand, what they’re hunting for).\nPrefer Before / After when the change is “how you ask” or “how you look it up.”\nUse picture words: hand it, open, find, check, save, skip, stop, call by name, name tag.\nPrefer spoken results: “found it,” “missing,” “duplicated,” “couldn’t.”\nWhen the diff uses an abstract word (operation id, registry, envelope, adapter, digest, schema), do one of two things:\nDrop it and say what the person does with their hands, or\nKeep it once, then gloss it in the same breath with a name-tag / mailbox / checklist metaphor — like the “finder’s name tag” line above.\nNever leave jargon unexplained. Never write as if the reader already knows the jargon.\nAdd a tiny concrete example in parentheses when a name is abstract (like “the phone icon”).\nFew words. Small words. Clear on first read.\nReturn:\n\nRecommended title\n\nFew words. Small words. Clear on first read.\nSay what you hand it, what it does, and what you get back — or the Before/After of how you ask.\nPrefer picture words and spoken results.\nGood title: “Call the icon finder by its name tag instead of asking around”\nGood title: “Given a theme STP and an asset name, report whether that asset was found, missing, or duplicated”\nBad title: anything that only says operation id / registry / typed envelope / adapter / digest / schema with no picture.\nUse “Add” only if it helps. Do not force it.\nNo vague words like “improve,” “enhance,” or “update.”\nReturn one title only.\nWhy this title fits\n\n1–2 short sentences in the same voice.\nIf needed, one Before / After beat, then what you get back.\nIf this section is needed to decode the title, rewrite the title.\nEvidence\n\nKey files or functions that support the title.\nIf you cannot read the PR or full diff, say so and do not propose a title.\n\nThen write a short, paste-ready PR description.\n\nUse this structure:\n\nWhat this adds\n1–2 short paragraphs in that illustrative voice. Lead with a scene when you can (“The theme package has a phone icon somewhere…”). If the change is a new way to ask, use Before / After. Say what you give it, what it does with its hands, and what you get back. If an abstract machine-word must appear, gloss it immediately (“That’s all X is — …”). Describe the job people can see. Do not describe inner machinery. Mention a check only if it is central to the feature.\n\nWhy\nOne short paragraph. Same plain level. Say who needs this and what goes wrong without it (the “yell and wait for a hand” problem). If this is needed to decode the feature, rewrite “What this adds.”\n\nVerification\nList only proof from the PR, CI, or your own checks.\n\nReported in the PR\n\n…\nChecked by you / CI here\n\n…\nRules:\n\nFew words. Small words. Clear on first read. ELI5 I-am-stupid mark.\nDo not invent behavior, tests, or benefits.\nStrip branch names, hashes, draft notes, agent notes, and merge notes.\nNo vague words like “improve,” “enhance,” or “update.”\nIllustrative first. Abstract labels only if glossed in the same breath.\nUse the recommended title and paste-ready description to run `gh pr edit <PR link> --title ... --body-file ...`, then run `gh pr view <PR link> --json title,body` to confirm the saved title and body. Report the saved result."
     return prompt.replace("<PR link>", url)

package/hooks/git-hooks/test_post_commit.py

@@ -242,6 +242,14 @@ def test_pull_request_reminder_prints_url(
     assert output.startswith("Review this pull request: https://github.com/example/repo/pull/1\n")
     assert "<PR link>" not in output
     assert "Do not use the branch name, commit message, labels, current title" in output
+    assert (
+        "Before writing, inventory every independently observable behavior in the full diff."
+        in output
+        and "Lead with the central behavior for readability, then give every other behavior its own short paragraph or bullet."
+        in output
+        and "For each behavior, state the trigger or observer, the Before -> After result" in output
+        and "OVERRIDE:" not in output
+    )
     assert "gh pr edit https://github.com/example/repo/pull/1" in output
     assert output.rstrip().endswith("Report the saved result.")
 

package/hooks/hooks_constants/stale_comment_reference_blocker_constants.py

@@ -60,14 +60,13 @@ STALE_COMMENT_DENY_TEMPLATE: str = (
     "The comment above the changed line in {file_path} names "
     "'{orphaned_name}', which this edit removes from the line below. "
     "The comment left in place reads: {contradicted_comment}. "
-    "Update or remove the comment in the same edit."
+    "Remove the comment in the same edit."
 )
 
 STALE_COMMENT_ADDITIONAL_CONTEXT: str = (
     "A standalone comment directly above an edited line describes that "
-    "line. When the edit drops a name the comment carries, rewrite the "
-    "comment to describe the rewritten line, or delete the comment, inside "
-    "the same Edit call."
+    "line. When the edit drops a name the comment carries, remove the "
+    "comment inside the same Edit call."
 )
 
 STALE_COMMENT_SYSTEM_MESSAGE: str = (

package/hooks/hooks_constants/test_unused_module_import_constants.py

@@ -9,7 +9,15 @@ _HOOKS_ROOT = Path(__file__).resolve().parent.parent
 if str(_HOOKS_ROOT) not in sys.path:
     sys.path.insert(0, str(_HOOKS_ROOT))
 
-from hooks_constants.unused_module_import_constants import line_suppresses_unused_import_via_noqa
+from hooks_constants.unused_module_import_constants import (
+    UNUSED_IMPORT_GUIDANCE,
+    line_suppresses_unused_import_via_noqa,
+)
+
+
+def test_unused_import_guidance_uses_comment_free_side_effect_remediation() -> None:
+    assert "noqa" not in UNUSED_IMPORT_GUIDANCE
+    assert "importlib.import_module" in UNUSED_IMPORT_GUIDANCE
 
 
 def test_line_suppresses_bare_noqa() -> None:

package/hooks/hooks_constants/unused_module_import_constants.py

@@ -11,7 +11,7 @@ NOQA_DIRECTIVE_PATTERN: re.Pattern[str] = re.compile(
 )
 MAX_UNUSED_IMPORT_ISSUES: int = 25
 UNUSED_IMPORT_GUIDANCE: str = (
-    "remove unused import; if kept for side effects, mark with `# noqa: F401`"
+    "remove unused import; if side effects are required, call importlib.import_module explicitly"
 )
 TYPE_CHECKING_IDENTIFIER: str = "TYPE_CHECKING"
 

package/hooks/validators/comment_checks.py

@@ -1,4 +1,4 @@
-"""Comment detection validator.
+"""Comment detection helpers used by the opt-in diff-aware linter.
 
 Implements check 26: No comments in code (self-documenting code principle).
 
@@ -12,7 +12,7 @@ Exceptions (NOT flagged):
 - Docstrings (triple-quoted strings for function contracts)
 
 Note: Docstrings documenting function Args/Returns/Raises are acceptable
-per CODE_RULES.md. This validator only flags # and // style comments.
+per CODE_RULES.md. The save-path validator does not invoke these helpers.
 """
 
 import re

package/hooks/validators/fast_save_validators.py

@@ -42,7 +42,6 @@ from .test_safety_checks import (
     check_debug_guard_in_dev_scripts,
     check_no_skip_decorators,
 )
-from .todo_checks import validate_file as validate_todo_file
 from .type_safety_checks import validate_file as validate_type_safety_file
 from .useless_test_checks import validate_file as validate_useless_test_file
 from .validator_base import ValidatorResult
@@ -153,14 +152,6 @@ def _all_fast_save_validator_specifications() -> (
             _violation_lines_from(validate_magic_literal_file),
             NO_PYTHON_FILES_MESSAGE,
         ),
-        # Python code quality and TODO tracking.
-        _FastSaveValidatorSpecification(
-            "TODO Tracking",
-            "36",
-            _is_python_file,
-            _violation_lines_from(validate_todo_file),
-            NO_PYTHON_FILES_MESSAGE,
-        ),
         _FastSaveValidatorSpecification(
             "Security",
             "27,28,29",

package/hooks/validators/git_checks.py

@@ -6,12 +6,6 @@ import sys
 from dataclasses import dataclass
 from typing import List
 
-try:
-    from .validator_defaults import DEFAULT_BASE_BRANCH_WHEN_UNKNOWN
-except ImportError:
-    from validator_defaults import DEFAULT_BASE_BRANCH_WHEN_UNKNOWN
-
-
 SUBPROCESS_TIMEOUT_SECONDS = 30
 
 
@@ -38,83 +32,6 @@ def get_current_branch() -> str:
         return ""
 
 
-def check_single_commit_when_pr_exists() -> List[Violation]:
-    """
-    Check that a PR branch has exactly 1 commit ahead of its base.
-
-    Returns empty list if:
-    - No PR exists for current branch
-    - gh CLI or git is not available
-    - gh/git times out
-    - Branch is exactly 1 commit ahead of base
-    - git rev-list output is non-numeric
-
-    Returns violation if:
-    - Branch is 0 commits ahead of base
-    - Branch is more than 1 commit ahead of base
-    """
-    branch = get_current_branch()
-    if not branch:
-        return []
-
-    try:
-        pr_info = subprocess.run(
-            ["gh", "pr", "list", "--head", branch, "--json", "baseRefName,number"],
-            capture_output=True,
-            text=True,
-            check=True,
-            timeout=SUBPROCESS_TIMEOUT_SECONDS,
-        )
-    except FileNotFoundError:
-        return []
-    except subprocess.CalledProcessError:
-        return []
-    except subprocess.TimeoutExpired:
-        return []
-
-    try:
-        pr_data = json.loads(pr_info.stdout)
-    except json.JSONDecodeError:
-        return []
-
-    if not pr_data:
-        return []
-
-    base_branch = pr_data[0].get("baseRefName", DEFAULT_BASE_BRANCH_WHEN_UNKNOWN)
-
-    try:
-        rev_list = subprocess.run(
-            ["git", "rev-list", "--count", f"{base_branch}..HEAD"],
-            capture_output=True,
-            text=True,
-            check=True,
-            timeout=SUBPROCESS_TIMEOUT_SECONDS,
-        )
-    except FileNotFoundError:
-        return []
-    except subprocess.CalledProcessError:
-        return []
-    except subprocess.TimeoutExpired:
-        return []
-
-    commit_count_text = rev_list.stdout.strip()
-    try:
-        commit_count = int(commit_count_text)
-    except ValueError:
-        return []
-
-    if commit_count == 1:
-        return []
-
-    return [
-        Violation(
-            file="",
-            line=0,
-            message=f"Branch must have exactly 1 commit ahead of {base_branch}, found {commit_count} commits",
-        )
-    ]
-
-
 def check_draft_pr_state() -> List[Violation]:
     """
     Check that PR is in draft state.
@@ -175,7 +92,6 @@ def main() -> None:
     """Run all git checks and exit with appropriate code."""
     violations: List[Violation] = []
 
-    violations.extend(check_single_commit_when_pr_exists())
     violations.extend(check_draft_pr_state())
 
     if violations:

package/hooks/validators/run_all_validators.py

@@ -410,18 +410,12 @@ def run_git_checks() -> ValidatorResult:
 
 
 def run_comment_checks(files: List[Path]) -> ValidatorResult:
-    """Comment preservation is enforced by code_rules_enforcer hook.
-
-    The hook compares old vs new content to block NEW comments and
-    print a stderr advisory when an existing comment is removed. This
-    standalone validator is disabled because it flags ALL comments in
-    existing files, which forces agents to remove them to pass validation.
-    """
+    """Report that comment policy runs through the explicit diff-aware linter."""
     return ValidatorResult(
         name="No Comments",
         checks="26",
         passed=True,
-        output="Handled by code_rules_enforcer hook (old vs new comparison)",
+        output="Run code_rules_gate.py with --comment-policy",
     )
 
 
@@ -1675,7 +1669,6 @@ def main() -> int:
             ("Security", lambda: run_security_checks(files)),
             ("Code Quality", lambda: run_code_quality_checks(files)),
             ("Python Anti-patterns", lambda: run_python_antipattern_checks(files)),
-            ("TODO Tracking", lambda: run_todo_checks(files)),
             ("Type Safety", lambda: run_type_safety_checks(files)),
         ]
 

package/hooks/validators/test_fast_save_validators.py

@@ -9,7 +9,6 @@ from .fast_save_validators import run_fast_save_validators
 from .magic_value_checks import validate_file as read_magic_literal_violations
 from .react_checks import check_no_class_components
 from .test_safety_checks import check_no_skip_decorators
-from .todo_checks import validate_file as read_todo_violations
 
 MAGIC_LITERAL_SOURCE = "def compute_total(unit_price: int) -> int:\n    return unit_price * 199\n"
 _UNTRACKED_TODO_MARKER = "#" + " TODO"
@@ -24,7 +23,6 @@ _ALL_EXPECTED_FAST_SAVE_VALIDATOR_NAMES = frozenset(
         "Python Style",
         "Abbreviations",
         "Magic Values",
-        "TODO Tracking",
         "Security",
         "Code Quality",
         "Python Anti-patterns",
@@ -103,16 +101,12 @@ def test_magic_values_outcome_matches_direct_validate_file_call(
     assert magic_values_outcome.output == "\n".join(expected_lines)
 
 
-def test_todo_outcome_matches_direct_validate_file_call(tmp_path: Path) -> None:
+def test_todo_comments_do_not_run_on_save_path(tmp_path: Path) -> None:
     target_file = tmp_path / "legacy_module.py"
     target_file.write_text(TODO_SOURCE, encoding="utf-8")
-    expected_lines = [str(each) for each in read_todo_violations(target_file)]
-    assert expected_lines != []
-
     all_outcomes = run_fast_save_validators([target_file])
 
-    todo_outcome = next(each for each in all_outcomes if each.name == "TODO Tracking")
-    assert todo_outcome.output == "\n".join(expected_lines)
+    assert all(each.name != "TODO Tracking" for each in all_outcomes)
 
 
 def test_abbreviations_outcome_reports_clean_for_a_clean_file(tmp_path: Path) -> None: