claude-dev-env 2.32.0 → 2.33.0

package/_shared/pr-loop/scripts/tests/test_code_rules_gate.py

@@ -600,9 +600,54 @@ def test_run_gate_detects_new_inline_comment_in_touched_file(
     )
     stage_file(temporary_git_repository, "module.py")
 
+    monkeypatch.chdir(temporary_git_repository)
+    exit_code = gate_module.main(["--staged", "--comment-policy"])
+
+    assert exit_code == 1
+
+
+def test_main_staged_mode_omits_comments_without_opt_in(
+    temporary_git_repository: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    write_file(temporary_git_repository / "module.py", "total = 1\n")
+    commit_all_files(temporary_git_repository, "initial")
+    write_file(temporary_git_repository / "module.py", "total = 1  # added\n")
+    stage_file(temporary_git_repository, "module.py")
+
     monkeypatch.chdir(temporary_git_repository)
     exit_code = gate_module.main(["--staged"])
 
+    assert exit_code == 0
+
+
+def test_run_gate_staged_mode_blocks_retained_comment_on_changed_line(
+    temporary_git_repository: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    write_file(temporary_git_repository / "module.py", "total = 1  # TODO #999: track\n")
+    commit_all_files(temporary_git_repository, "initial")
+    write_file(temporary_git_repository / "module.py", "total = 2  # TODO #999: track\n")
+    stage_file(temporary_git_repository, "module.py")
+
+    monkeypatch.chdir(temporary_git_repository)
+    exit_code = gate_module.main(["--staged", "--comment-policy"])
+
+    assert exit_code == 1
+
+
+def test_run_gate_base_mode_blocks_retained_comment_on_changed_line(
+    temporary_git_repository: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    write_file(temporary_git_repository / "module.py", "total = 1  # noqa\n")
+    commit_all_files(temporary_git_repository, "initial")
+    write_file(temporary_git_repository / "module.py", "total = 2  # noqa\n")
+    commit_all_files(temporary_git_repository, "change")
+
+    monkeypatch.chdir(temporary_git_repository)
+    exit_code = gate_module.main(["--base", "HEAD~1", "--comment-policy"])
+
     assert exit_code == 1
 
 
@@ -619,7 +664,7 @@ def test_run_gate_treats_new_files_prior_content_as_empty(
     stage_file(temporary_git_repository, "brand_new.py")
 
     monkeypatch.chdir(temporary_git_repository)
-    exit_code = gate_module.main(["--staged"])
+    exit_code = gate_module.main(["--staged", "--comment-policy"])
 
     assert exit_code == 1
 
@@ -2387,6 +2432,7 @@ def test_parse_arguments_applies_documented_defaults() -> None:
 
     assert parsed_arguments.staged is False
     assert parsed_arguments.immediate is False
+    assert parsed_arguments.comment_policy is False
     assert parsed_arguments.base == "origin/main"
     assert parsed_arguments.repo_root is None
     assert parsed_arguments.only_under == []

package/audit-rubrics/audit-categories.json

@@ -192,7 +192,7 @@
         },
         {
           "id": "E8",
-          "axis_name": "Stub / placeholder code without TODO"
+          "axis_name": "Stub / placeholder code without tracking"
         },
         {
           "id": "E9",
@@ -509,7 +509,7 @@
         },
         {
           "id": "L7",
-          "axis_name": "Skipped-category exhaustion"
+          "axis_name": "Changed-comment handling"
         },
         {
           "id": "L8",

package/audit-rubrics/category_rubrics/category-e-dead-code.md

@@ -25,7 +25,7 @@
 | E5 | Unused parameters and locals | Parameters declared but never read inside the function body; local variables assigned but never read afterward in the same scope. |
 | E6 | Removed-but-not-deleted symbol references | Symbols renamed/removed elsewhere with stale import or call sites left behind. |
 | E7 | Test fixtures / helpers defined but never used | Pytest fixtures, test data builders, mock factories with no callers. |
-| E8 | Stub / placeholder code without TODO | `pass`, `...`, `raise NotImplementedError` left without explanation or tracking. |
+| E8 | Stub / placeholder code without tracking | Judge `pass`, `...`, and `raise NotImplementedError` directly; track follow-up work outside source code. |
 | E9 | Constants-module exports with no importer | A module-level `UPPER_SNAKE` constant added to a `*_constants.py` / `config/` module that no module in the repo imports and that the constants file itself never references. The file-global use-count gate exempts a constants module because every name it exports legitimately carries zero in-file references, so a genuinely dead export slips past the write-time gate. Distinguish dead from live by grepping the whole repo for each constant name: a sibling such as `MEDIUM_TERMINAL` imported by a consumer module is live; a `MEDIUM_TEXT` that no `from ... import` line and no in-file reference names is dead (CODE_RULES 9.8). Remove the dead export. |
 
 ---

package/audit-rubrics/category_rubrics/category-j-code-rules-compliance.md

@@ -24,13 +24,15 @@
 | J5 | Abbreviations | `ctx`, `cfg`, `msg`, `btn`, `idx`, `cnt`, `elem`, `val`, `tmp`, `str`, `num`, `arr`, `obj`, `fn`, `cb`, `req`, `res`. (Loop counters `i`/`j`/`k` and `e` for exceptions are exempt.) |
 | J6 | Vague names | `result`, `data`, `output`, `response`, `value`, `item`, `temp`, `info`, `stuff`, `thing`. Vague prefixes: `handle`, `process`, `manage`, `do`. |
 | J7 | Type hints | Missing type annotation on a parameter or return; presence of `Any` or `# type: ignore`. |
-| J8 | New inline comments | New `#` or `//` comments in production code added by this diff. (Removing an existing comment is a Comment Preservation concern the hook flags with a stderr advisory rather than a block.) |
+| J8 | New inline comments | New `#` or `//` comments in production or test code added by this diff; changed directive, TODO, FIXME, HACK, XXX, and type-ignore comments are also findings. |
 | J9 | Logging format | `log_*(f"...")` rather than `log_*("...", arg)`. |
 | J10 | Imports inside functions | `import` statements placed inside function bodies. |
 | J11 | sys.path.insert dedup | `sys.path.insert(0, X)` must be guarded by `if X not in sys.path:` (test files exempt). |
 | J12 | Hardcoded user paths | String literals naming a specific user's home directory (`C:/Users/example/...`, `/Users/alice/...`, `/home/bob/...`). Use `pathlib.Path.home()`. |
 
-The write-time hook (`code_rules_enforcer.py`) exempts test files (`test_*.py`, `*_test.py`, `*.test.*`, `*.spec.*`, `conftest.py`, paths under `/tests/`) from most Category J sub-buckets, and skips the naming, logging, annotation, and unused-import rules on `.mjs` / `.js` files. J11 (`sys.path.insert`) always applies. Read the next section for the sub-buckets this audit applies more widely than the hook.
+The write-time hook (`code_rules_enforcer.py`) exempts test files (`test_*.py`, `*_test.py`, `*.test.*`, `*.spec.*`, `conftest.py`, paths under `/tests/`) from most Category J sub-buckets, while comment changes use one rule for production and tests. It skips the naming, logging, annotation, and unused-import rules on `.mjs` / `.js` files. J11 (`sys.path.insert`) always applies. Read the next section for the sub-buckets this audit applies more widely than the hook.
+
+When a change touches code that an existing comment describes or is attached to, remove that comment in the same change and carry its meaning through clear names and structure. Leave comments tied to untouched code unchanged. Keep comment cleanup inside the requested task. Production and tests follow one rule. Changed directive, TODO, FIXME, HACK, XXX, and type-ignore comments are removed rather than added or justified.
 
 ## Write-time exemptions do not scope this audit
 
@@ -38,7 +40,7 @@ The write-time hook skips several rules on test files and on `.mjs` / `.js` file
 
 - **Naming (J5, J6)** — banned identifiers (`ctx`, `cfg`, `msg`, `result`, `data`, `output`, `value`, `item`, `temp`, `elem`, `val`, …) and banned function prefixes (`handle_`, `process_`, `manage_`, `do_`); boolean names prefixed `is_` / `has_` / `should_` / `can_` / `was_` / `did_`.
 - **Logging format (J9)** — the format string and its arguments pass as separate parameters (`log_*("...", arg)`), never an f-string.
-- **Type annotations (J7)** — every changed function parameter and return is typed; no `Any`, no bare `# type: ignore`.
+- **Type annotations (J7)** — every changed function parameter and return is typed; no `Any`, no `# type: ignore` directives.
 - **Unused imports** — a module-level import a changed file does not read is a finding.
 - **Function length** — a changed function that runs past the length threshold splits into named helpers.
 

package/audit-rubrics/category_rubrics/category-l-behavior-equivalence.md

@@ -1,11 +1,14 @@
 # Category L — Behavior-equivalence for refactors
 
+When a change touches code that an existing comment describes or is attached to, remove that comment in the same change and carry its meaning through clear names and structure. Leave comments tied to untouched code unchanged. Keep comment cleanup inside the requested task.
+Production and tests follow one rule. Changed directive, TODO, FIXME, HACK, XXX, and type-ignore comments are removed rather than added or justified.
+
 **What this category audits:** rewrites of an existing function (especially an enforcement check, parser, classifier, or normalizer) where the new implementation must accept every input the old implementation accepted and reject every input the old implementation rejected. Common when a regex-based check is rewritten as a tokenize-based check, when a `str.startswith` chain is consolidated into a single regex, when a hand-rolled split is replaced with a library call, or when a multi-step pipeline is collapsed into one pass.
 
 **Why this category is its own bucket:** Categories A–K catch failure modes inside the rewrite itself (wrong signature, dead code, missed branch). Category L catches the failure mode that emerges between the rewrite and the *historically valid inputs* the original code accepted. The diff looks internally consistent and the new unit tests pass — but inputs the prior code accepted fall through under the new implementation, or inputs the prior code rejected slip past. The bug only surfaces against the corpus of canonical inputs the original implementation was tuned for.
 
 **Examples of Category L findings:**
-- A tokenize-based exempt-marker check drops `#noqa` (no space after `#`) when the original normalization-based check accepted it. (ccc#479 F1)
+- A refactored comment check changes acceptance for marker-shaped input when code changes.
 - A new comment classifier misreads a bare `#` lookalike that the original regex correctly rejected. (ccc#479 F4)
 - A refactored shebang detector drops the inline `#!` variant the original handled. (ccc#479 F5)
 - An invariant the original loop enforced at the first match (early-exit) is dropped in the rewrite. (ccc#479 F6)
@@ -27,7 +30,7 @@ Decomposition is by the **kind of historically valid input** the rewrite must co
 | L4 | Empty / boundary inputs | Empty string, single character, single-line vs multi-line, EOF without newline retain their original classification. |
 | L5 | Invariant preservation | Early-exit guarantees, idempotence, ordering, stable iteration, "first match wins" semantics carry over. |
 | L6 | Implementation-tag parity | Token-based vs regex-based vs str-method-based: the new tag accepts every input shape the old tag accepted (no shape silently dropped). |
-| L7 | Skipped-category exhaustion | Inputs that the original explicitly skipped (e.g., shebang on line 1 only, exempt markers without trailing prose, `# type:` with a trailing justification) remain skipped. |
+| L7 | Changed-comment handling | Shebangs on line 1 and docstrings retain their handling. Changed directive, TODO, FIXME, HACK, XXX, and type-ignore comments are findings. |
 | L8 | Sibling-implementation comparison | When two parallel implementations exist (e.g., Python + PowerShell, regex + tokenize), the rewrite of one must still produce the same accept/reject decisions as the sibling for shared inputs. |
 
 Customize per-artifact: a parser refactor without an explicit sibling implementation reduces L8 to "verified clean — no parallel implementation"; a single-axis rewrite (whitespace handling only) may exhaust the per-sub-bucket checks against just L2 and L7.
@@ -42,4 +45,4 @@ The reusable Variant C template for Category L is in [`../prompts/category-l-beh
 
 Categories A–K describe failure modes that show up in the rewrite's own surface. Category L describes the failure mode that shows up only when the rewrite is compared against the inputs the original was tuned for. A reviewer walking only A–K reads the rewrite, finds it clean, and approves it — without re-running the original test inputs through the new code path. L forces the reviewer to pin the original's known-good inputs in a table and assert each still passes against the rewrite.
 
-The ccc#479 F1 case illustrates the cost of not running L. The refactor of `_is_exempt_python_comment` replaced a `comment_string[1:].lstrip()` normalization (which reduced both `# noqa` and `#noqa` to the body `noqa` before the membership test) with a tokenize-based recognizer that tested the raw `tokenize.COMMENT` token text against `startswith("# noqa")`. Production code carrying `#noqa: F401` (no space) silently stopped matching the exempt marker after the refactor, and the no-new-comments gate began blocking writes that the original implementation passed. The dropped no-space variant only surfaces under a KNOWN_GOOD_INPUTS table that enumerates spaced, no-space, tab-separated, and multi-space inputs — fixtures the rewrite's own tests would otherwise miss.
+The ccc#479 F1 case illustrates the cost of not comparing changed-code marker handling with the original input corpus. Category L requires the reviewer to pin the original inputs and verify that shebangs and docstrings remain preserved while changed marker comments are rejected.

package/audit-rubrics/prompts/category-e-dead-code.md

@@ -63,10 +63,10 @@ Inline the artifact under this section using the section types defined in the ch
 - Helpers defined inside a single test body that are never called within that body are dead.
 - Adversarial probes for proof-of-absence: (a) any test that defines a local helper (e.g., `def make_dir(...):`) and never calls it? (b) any imported test name from the production module that no test exercises? (c) any module-level constant whose call graph collapses to zero references after the diff?
 
-**E8. Stub / placeholder code without TODO**
+**E8. Stub / placeholder code without tracking**
 - Distinguish real-behavior `pass` / `continue` / empty-handler bodies (intentional swallowing of expected exceptions, no-op branches that exist to satisfy a contract) from scaffolding stubs.
-- Real-behavior bodies do NOT require a TODO; the audit must state the rationale (e.g., "rmdir race with concurrent writer is intentionally swallowed").
-- Scaffolding bodies (`pass`, `...`, `raise NotImplementedError`, empty `else { }`, single-statement `return None` placeholders) without a `# TODO` comment ARE Category E findings under the project's `CODE_RULES.md` → "COMMENT PRESERVATION" rule.
+- Real-behavior bodies need no source-code marker; the audit must state the rationale (e.g., "rmdir race with concurrent writer is intentionally swallowed").
+- Scaffolding bodies (`pass`, `...`, `raise NotImplementedError`, empty `else { }`, single-statement `return None` placeholders) are Category E findings. Judge the stub itself; track follow-up work outside source code.
 - Adversarial probes for proof-of-absence: (a) any empty brace block in PowerShell / TypeScript / Go (`{ }` with no statements)? (b) any function whose entire body is `pass` / `return` / `return None`? (c) any branch that exits cleanly only because the surrounding loop is no-op for an empty input — is the no-op intentional or a placeholder?
 
 **E9. Constants-module exports with no importer**
@@ -160,12 +160,12 @@ ID prefix: `find`.
 - No test data builders or mock factories are defined in this PR.
 - Adversarial probes for proof-of-absence: (a) does any of the five tests define a local helper inside its body that is then never called? (e.g., a `def make_dir(...):` defined but unused) — scan each test body. (b) does any test import a name from `sweep_empty_dirs` that it never uses? — only `sweep` is imported, and every test calls it. (c) does the `_SCRIPTS_DIR` block survive if pytest is invoked with `sweep_empty_dirs.py` already on `sys.path`? — yes, the membership-test guards the insert, so the constant is still meaningfully consumed even on the second run.
 
-**E8. Stub / placeholder code without TODO**
-- `sweep_empty_dirs.py` line 30: `except OSError: pass` — the `pass` is the entire handler body, intentionally swallowing rmdir failures (e.g., directory became non-empty between the walk and the rmdir, race with another writer). This is a real-behavior `pass`, not a stub. No TODO is required because the handler IS the intended behavior.
+**E8. Stub / placeholder code without tracking**
+- `sweep_empty_dirs.py` line 30: `except OSError: pass` — the `pass` is the entire handler body, intentionally swallowing rmdir failures (e.g., directory became non-empty between the walk and the rmdir, race with another writer). This is a real-behavior `pass`, not a stub. No source-code marker is needed because the handler IS the intended behavior.
 - `sweep_empty_dirs.py` line 28: the second `except OSError: continue` similarly is intended behavior (skip the directory whose ctime is unreadable), not a stub.
 - No `...` literal anywhere in the four files.
 - No `raise NotImplementedError` anywhere.
-- No `# TODO` markers in the diff — the project's own rule (`CODE_RULES.md` → "COMMENT PRESERVATION") requires TODOs only for scaffolding/placeholder code. The two `pass`/`continue` bodies above are production behavior, not scaffolding.
+- The two `pass`/`continue` bodies above are production behavior, not scaffolding. No source-code marker is needed because the audit judges the body directly.
 - Adversarial probes for proof-of-absence: (a) does the PowerShell script have an empty `else { }` or empty branch body? — scan lines 14-71 for any `{ }` with no statements between the braces. (b) does any function body consist of a single `pass` or `return` with no work done? — every function body in this PR performs at least one statement. (c) does the `Status` branch (lines 14-31) exit cleanly even when `$task.Triggers` is empty? — the `foreach` loop at line 26 is a no-op for an empty collection, which is correct behavior, not a stub.
 
 **E9. Constants-module exports with no importer**

package/audit-rubrics/prompts/category-j-code-rules-compliance.md

@@ -5,7 +5,7 @@ Audit [REPO/ARTIFACT] [TARGET_ID] for **Category J only** (CODE_RULES.md complia
 - Head SHA / Revision: [SHA or revision identifier]
 - Scope: [files / line ranges / packages in scope]
 - Languages in scope: [e.g., Python, PowerShell, TypeScript]
-- Production vs test split: [explicit list of which files are production and which are test files; test files are exempt from most J sub-buckets]
+- Production vs test split: [explicit list of which files are production and which are test files; both use the same comment rule]
 
 ID prefix: `find`.
 
@@ -17,11 +17,14 @@ Replace this paragraph with the chunked source material before issuing the promp
 
 ## Write-time exemptions do not scope this audit
 
-The write-time hook skips several rules on test files and on `.mjs` / `.js` files; this audit does not. Apply these rules to every changed line — production, test, and JavaScript files alike:
+When a change touches code that an existing comment describes or is attached to, remove that comment in the same change and carry its meaning through clear names and structure. Leave comments tied to untouched code unchanged. Keep comment cleanup inside the requested task.
+Production and tests follow one rule. Changed directive, TODO, FIXME, HACK, XXX, and type-ignore comments are removed rather than added or justified.
+
+The write-time hook skips several rules on test files and on `.mjs` / `.js` files; comment changes use one rule for production and tests. This audit does not skip the other listed rules. Apply these rules to every changed line — production, test, and JavaScript files alike:
 
 - Naming (J5, J6) — banned identifiers and banned function prefixes; boolean names prefixed `is_` / `has_` / `should_` / `can_` / `was_` / `did_`.
 - Logging format (J9) — the format string and its arguments pass as separate parameters, never an f-string.
-- Type annotations (J7) — every changed parameter and return is typed; no `Any`, no bare `# type: ignore`.
+- Type annotations (J7) — every changed parameter and return is typed; no `Any`, no `# type: ignore` directives.
 - Unused imports — a module-level import a changed file does not read.
 - Function length — a changed function past the length threshold splits into named helpers.
 
@@ -31,7 +34,8 @@ A `test_*.py` name or a `.mjs` extension takes the line out of the write-time ga
 
 **J1. Magic values in production function bodies**
 - Walk every numeric or non-trivial literal other than `0`, `1`, `-1` inside production function bodies.
-- Test files are exempt. Module-level declarations are J3-scope, not J1-scope.
+- Test files follow the same no-new-comment policy.
+- Changed directive, TODO, FIXME, HACK, XXX, and type-ignore comments are removed rather than added or justified. Module-level declarations are J3-scope, not J1-scope.
 - For each literal found, decide: structural value that belongs in `config/` (flag) vs. truly local arithmetic constant tied to the line's logic (defendable).
 - Adversarial probes must each verify a distinct angle: (a) does the literal duplicate an existing value already centralized in `config/`? (b) does the literal silently couple two languages (e.g., a Python config value and a hand-typed PowerShell / shell mirror)? (c) does the literal appear in user-facing help/doc text in a way that would silently lie if the canonical value changed?
 
@@ -67,10 +71,11 @@ A `test_*.py` name or a `.mjs` extension takes the line out of the write-time ga
 - Adversarial probes: (a) does any production function rely on inferred return type from a single `return` path? (b) does any parameter use a string-quoted forward reference that masks `Any`? (c) is there a `# type: ignore` anywhere? Grep the diff explicitly.
 
 **J8. New inline comments**
-- Every `#` or `//` comment line **added** by this diff in production code — flag, except for exempt markers (shebangs, `# type:`, `# noqa`, `# pylint:`, `# pragma:`, `// @ts-`, `// eslint-`, `// prettier-`, `/// `).
+- Every `#` or `//` comment line **added** by this diff in any code — flag.
 - Module/function/class docstrings are always allowed.
-- Existing comments are NEVER removed (Comment Preservation rule); if the diff removes an existing comment, that is a separate violation outside J8 (the hook emits a stderr advisory for it rather than blocking).
-- Test files are exempt.
+- Comments tied to untouched code remain unchanged; a changed comment is removed with the code it describes.
+- Test files follow the same no-new-comment policy.
+- Changed directive, TODO, FIXME, HACK, XXX, and type-ignore comments are removed rather than added or justified.
 - Adversarial probes: (a) is there any `# type:` or marker comment that is actually inert prose rather than a real type-checker / linter directive? (b) is any docstring carrying inline-comment content (line-level explanations rather than module/function description)? (c) does any newly-added blank line between code stanzas function as a comment substitute, suggesting the author wanted to add a comment but couldn't?
 
 **J9. Logging format**
@@ -81,7 +86,7 @@ A `test_*.py` name or a `.mjs` extension takes the line out of the write-time ga
 
 **J10. Imports inside functions**
 - Every `import` / `from ... import ...` statement — verify at module scope.
-- Test files: deferred imports after a `sys.path.insert(0, ...)` guard at module scope are allowed (documented circular-import-style workaround).
+- Test file — lines 152-158 are module-scope imports, and line 164 is a deferred import at module scope after the sys.path guard. The documented import placement remains allowed.
 - Adversarial probes: (a) is there any lazy `import` inside a production function body? (b) does any conditional `import` (e.g., inside `if TYPE_CHECKING:`) escape into runtime accidentally? (c) does any non-Python language analog (e.g., `require(...)` inside a JS function, `Import-Module` inside a PowerShell `if` branch) appear in production code?
 
 **J11. sys.path.insert dedup**
@@ -90,9 +95,9 @@ A `test_*.py` name or a `.mjs` extension takes the line out of the write-time ga
 - Adversarial probes: (a) is the guard expression semantically equivalent to `if X not in sys.path:` where `X` is exactly the value being inserted (no string/Path mismatch)? (b) is there a second `sys.path` mutation elsewhere in the file that is not guarded? (c) would importing the module twice (e.g., via test collection re-runs) re-trigger the insert?
 
 **J12. Hardcoded user paths**
-- Any string literal containing `C:/Users/<name>/...`, `/Users/<name>/...`, `/home/<name>/...` in production code? Use `pathlib.Path.home()` or `os.path.expanduser('~')`.
+- Any string literal containing a user-specific home path in production code? Use `pathlib.Path.home()` or `os.path.expanduser('~')`.
 - Exempt: test files, `config/` files, workflow registry paths (`/workflow/`, `_tab.py`, `/states.py`, `/modules.py`), Django migrations (`/migrations/`), and hook infrastructure.
-- Adversarial probes: (a) does any error message, help string, or docstring example embed a `C:/Users/...`, `/home/...`, or `/Users/...` example? Grep the diff. (b) does any scheduled-task / launcher / installer artifact hardcode a path that should be derived from `$PSCommandPath`, `__file__`, or `os.getcwd()`? (c) does any docstring example show a user-specific home, even if the runtime code itself is path-clean?
+- Adversarial probes: (a) does any error message, help string, or docstring example embed a user-specific home path? Grep the diff. (b) does any scheduled-task / launcher / installer artifact hardcode a path that should be derived from `$PSCommandPath`, `__file__`, or `os.getcwd()`? (c) does any docstring example show a user-specific home, even if the runtime code itself is path-clean?
 
 ## Cross-bucket questions to answer at the end
 
@@ -167,7 +172,7 @@ ID prefix: `find`.
 - Flag any name from the vague list: `result`, `data`, `output`, `response`, `value`, `item`, `temp`, `info`, `stuff`, `thing`. Vague verb prefixes: `handle`, `process`, `manage`, `do`.
 - `sweep_empty_dirs.py` — variable `removed: list[str]` (line 81) is domain-specific (what was removed from disk), not vague. `now` (line 80) is a time concept, not on the vague list. `created` (line 87) is a domain timestamp, not vague.
 - Function names: `sweep`, `_log_walk_error`, `_build_parser`, `main` — none use the vague verb prefixes (`handle`, `process`, `manage`, `do`). `sweep` is concrete domain action.
-- Test file — exempt.
+- Test file — the same no-new-comment rule applies.
 - Adversarial probes: (a) does `removed` (line 81) overlap with the vague-name list? It does not — the list is `result`, `data`, `output`, etc., and `removed` is none of those. (b) is `arguments` (line 115) on any vague list? No — `arguments` is the argparse-namespace canonical name. (c) does any callback parameter use a vague name? `_log_walk_error(os_error)` — `os_error` is concrete. Clean.
 
 **J7. Type hints**
@@ -181,24 +186,24 @@ ID prefix: `find`.
 - Adversarial probes: (a) does any production function rely on inferred return type from a single `return` path? All four production functions have explicit return annotations. (b) does any parameter use a string-quoted forward reference that masks `Any`? No — all annotations are direct. (c) is there a `# type: ignore` anywhere? Grep the diff: no occurrences.
 
 **J8. New inline comments**
-- Every `#` comment line added by this diff in production code — flag, except for exempt markers (shebangs, `# type:`, `# noqa`, `# pylint:`, `# pragma:`).
+- Every `#` comment line added by this diff in production or test code — flag. Changed directive, TODO, FIXME, HACK, XXX, and type-ignore comments are also findings.
 - `sweep_empty_dirs.py` — line 61 (`#!/usr/bin/env python3`) is a shebang, exempt. Line 62 is a module-level docstring, allowed. Lines 78 and 102 are function docstrings, allowed. No inline `#` comments. Clean.
 - `config/sweep_config.py` — line 140 is a module-level docstring. No inline comments. Clean.
-- Test file — exempt.
+- Test file — the same no-new-comment rule applies.
 - `Install-SweepEmptyDirs.ps1` — line 227 (`#!/usr/bin/env pwsh`) is a shebang, exempt. No inline `#` comments added in the PowerShell file. Clean.
 - Adversarial probes: (a) is there any `# type:` comment that is actually inert noise rather than a type-checker directive? No occurrences in the diff. (b) is any docstring carrying inline-comment content as line-level explanations rather than module/function description? Module docstring on line 62 is one line ("Delete empty directories older than 2 minutes under a given root."); function docstrings on 78 and 102 are one-liners. Clean. (c) does any newly-added blank line between code stanzas function as a comment substitute? Visual whitespace is allowed.
 
 **J9. Logging format**
 - Walk every `log_*(...)` call. Must be `log_*("template with {}", arg)`, not `log_*(f"...")`.
 - `sweep_empty_dirs.py` uses `print()`, not a logger. The rule applies to `log_*` (the project's structured logger), not stdlib `print`. The print f-strings on lines 74, 93, 118, 125, 131 are J2-scope (string-template magic), not J9-scope.
-- Test file — exempt.
+- Test file — the same no-new-comment rule applies.
 - Adversarial probes: (a) is there any imported `log_*` function in `sweep_empty_dirs.py` that uses an f-string? No — no logger import in the diff. (b) is `print(..., file=sys.stderr)` (lines 74, 118) a logger-equivalent call that should be subject to J9? No — `print` is stdlib stdout/stderr, not the structured-logger family. (c) does the PowerShell `Write-Host` / `Write-Error` family count? J9 is Python-specific (`log_*` callable convention).
 
 **J10. Imports inside functions**
 - Every `import` / `from ... import ...` statement — verify at module scope.
 - `sweep_empty_dirs.py` lines 64-70 — all imports at module top. Function bodies (lines 73-135) contain no `import` statements. Clean.
 - `config/sweep_config.py` — no imports. Clean.
-- Test file — exempt; nevertheless lines 152-158 are all module-scope imports, line 164 is a deferred import (`from sweep_empty_dirs import sweep  # noqa: E402`) at module scope after the `sys.path.insert` guard. Documented circular-import-style workaround pattern; allowed.
+- Test file — lines 152-158 are module-scope imports, and line 164 is a deferred import at module scope after the sys.path guard. The documented import placement remains allowed.
 - Adversarial probes: (a) is there any lazy `import` inside `sweep`, `main`, or `_build_parser` body? No occurrences. (b) is `argparse.ArgumentParser` accessed via `argparse.ArgumentParser` (line 102) using the module-scope import on line 64? Yes. (c) does the PowerShell file have any `Import-Module` calls inside `if` branches? No — the script imports nothing.
 
 **J11. sys.path.insert dedup**
@@ -208,12 +213,12 @@ ID prefix: `find`.
 - Adversarial probes: (a) is the guard expression `if str(_SCRIPTS_DIR) not in sys.path:` semantically equivalent to `if X not in sys.path:` where `X` is exactly the value being inserted? Yes — both use `str(_SCRIPTS_DIR)`. (b) is there a second `sys.path` mutation elsewhere in the test file that's not guarded? No — only one occurrence at line 162. (c) would importing the test module twice (e.g., via pytest's collection re-runs) re-trigger the insert? The guard prevents it. Clean.
 
 **J12. Hardcoded user paths**
-- Any string literal containing `C:/Users/<name>/...`, `/Users/<name>/...`, `/home/<name>/...`?
+- Any string literal containing a user-specific home path?
 - `sweep_empty_dirs.py` — no hardcoded user paths. The `arguments.root` value is supplied at runtime via argparse positional argument (line 103). Clean.
 - `config/sweep_config.py` — no paths at all. Clean.
-- Test file — exempt; uses `tempfile.TemporaryDirectory()` (lines 178, 188, 197, 210, 216) which is the canonical safe pattern. Clean.
+- Test file — uses `tempfile.TemporaryDirectory()` (lines 178, 188, 197, 210, 216), which is the canonical safe pattern. Clean.
 - `Install-SweepEmptyDirs.ps1` — `$ScriptDir = Split-Path -Parent $PSCommandPath` (line 272), `$ScriptPath = Join-Path $ScriptDir "sweep_empty_dirs.py"` (line 273). Both derive from `$PSCommandPath` (the script's own path), not a hardcoded user home. Clean. The `$Target` parameter is supplied at install time (line 230); not hardcoded.
-- Adversarial probes: (a) does any error message or help string embed a `C:/Users/...` example? Grep the diff for `C:/Users`, `/home/`, `/Users/` — no occurrences. (b) does the scheduled task `-Argument` string at line 296 hardcode a path? It interpolates `$ScriptPath`, `$AgeSeconds`, and `$Target` — all dynamic. Clean. (c) does any docstring example show a user-specific home? Module docstrings on lines 62 and 140 are short and contain no example paths. Clean.
+- Adversarial probes: (a) does any error message or help string embed a user-specific home path? Grep the diff — no occurrences. (b) does the scheduled task `-Argument` string at line 296 hardcode a path? It interpolates `$ScriptPath`, `$AgeSeconds`, and `$Target` — all dynamic. Clean. (c) does any docstring example show a user-specific home? Module docstrings on lines 62 and 140 are short and contain no example paths. Clean.
 
 ## Cross-bucket questions to answer at the end
 
@@ -301,7 +306,8 @@ def main() -> None:
             sweep(arguments.root, arguments.age)
             time.sleep(arguments.interval)
     except KeyboardInterrupt:
-        print("\nstopped.")
+        print("
+stopped.")
 
 
 if __name__ == "__main__":

package/audit-rubrics/prompts/category-l-behavior-equivalence.md

@@ -1,5 +1,8 @@
 Audit [REPO/ARTIFACT] [TARGET_ID] for **Category L only** (behavior-equivalence for refactors). Skip A–K, M–P. Sub-bucket forced-exhaustion mode: Category L is decomposed into 8 sub-buckets below. Each sub-bucket REQUIRES at least one Shape A finding OR exactly one Shape B proof-of-absence with **at least 3 adversarial probes** specific to that sub-bucket. A sub-bucket returning neither is a protocol gap.
 
+When a change touches code that an existing comment describes or is attached to, remove that comment in the same change and carry its meaning through clear names and structure. Leave comments tied to untouched code unchanged. Keep comment cleanup inside the requested task.
+Production and tests follow one rule. Changed directive, TODO, FIXME, HACK, XXX, and type-ignore comments are removed rather than added or justified.
+
 [ARTIFACT METADATA — include the BEFORE state of the rewritten function so the agent can compare BEFORE vs AFTER behavior on the same input corpus]
 
 - Title / one-line summary: [TITLE]
@@ -30,16 +33,16 @@ ID prefix: `find`.
 
 **L2. Whitespace / separator variants**
 - For every input the BEFORE implementation accepted, does the AFTER implementation also accept the variant with: no space where the BEFORE allowed space, leading whitespace, trailing whitespace, multiple internal spaces, tab vs single space, CRLF vs LF?
-- Adversarial probes: (a) construct inputs identical to KNOWN_GOOD_INPUTS but with the space stripped (`#noqa` vs `# noqa`) — does the AFTER state still accept? (b) construct inputs with trailing whitespace and CRLF — does the AFTER state strip them the same way the BEFORE state did? (c) construct inputs with a tab where the BEFORE allowed a space — does the AFTER state's tokenizer / regex treat them identically?
+- Marker-shaped comments are findings when changed; verify whitespace variants against the changed-code rule.
 
 **L3. Adjacent-form regressions**
 - Does the AFTER implementation use a looser pattern than the BEFORE (e.g., `startswith("## Problem")` where the BEFORE used `re.match(r"^## Problem\b")`)? A loose pattern accepts inputs the original rejected.
-- Does the AFTER implementation use a tighter pattern than the BEFORE (e.g., `re.match(r"^# noqa\b")` where the BEFORE used `startswith("# noqa")`)? A tight pattern rejects inputs the original accepted.
+- Marker-shaped comments are findings when changed; verify whitespace variants against the changed-code rule.
 - Adversarial probes: (a) construct inputs that satisfy the AFTER pattern but NOT the BEFORE — these are inputs the rewrite silently accepted; (b) construct inputs that satisfy the BEFORE pattern but NOT the AFTER — these are inputs the rewrite silently rejected; (c) walk the BEFORE pattern's anchors (`^`, `\b`, `\s`) and the AFTER pattern's anchors — does every BEFORE anchor have a semantic equivalent in the AFTER pattern?
 
 **L4. Empty / boundary inputs**
 - For empty string, single character, single-newline, single-line, EOF-without-newline — does the AFTER implementation produce the same accept/reject decision as the BEFORE?
-- Adversarial probes: (a) does the AFTER tokenizer raise on an empty input where the BEFORE returned False? (b) does the AFTER regex match on a single-newline input where the BEFORE skipped? (c) does the AFTER state handle the EOF-without-newline edge that the BEFORE state's `splitlines()` call did?
+- Adversarial probes: compare empty and single-line inputs under the original and changed-code paths; both preserve the same handling.
 
 **L5. Invariant preservation**
 - Does the BEFORE implementation enforce an invariant (early-exit on first match, idempotence under repeated invocation, stable iteration order, ordering of returned items)? Does the AFTER preserve each invariant?
@@ -49,9 +52,9 @@ ID prefix: `find`.
 - The BEFORE implementation used [TAG_BEFORE] (regex / tokenize / str-method / library). The AFTER uses [TAG_AFTER]. For each input shape the BEFORE-tag accepted (e.g., a regex pattern accepted inline `#!` because the `re.MULTILINE` flag matched at any line start), does the AFTER-tag accept the same shape via a different mechanism?
 - Adversarial probes: (a) enumerate the BEFORE-tag's capabilities that the AFTER-tag does not natively have (e.g., regex `\b` boundaries vs tokenize stream events) — has the AFTER implementation added compensating logic? (b) enumerate the AFTER-tag's capabilities that the BEFORE-tag did not have — are any of them silently expanding the accept set? (c) construct an input shape that the BEFORE-tag rejected only because of its tag's limitations — does the AFTER accept now and is that intentional?
 
-**L7. Skipped-category exhaustion**
-- Inputs the BEFORE explicitly skipped — shebang on line 1 only, exempt markers without trailing prose, free-form `# type:` directives carrying a trailing justification — does the AFTER state continue to skip them?
-- Adversarial probes: (a) does the AFTER state's skip-list match the BEFORE state's skip-list literally? (b) for each skip rule, construct an input the BEFORE skipped — does the AFTER also skip? (c) for each skip rule, construct an input one character off from the skip pattern — does the AFTER fall through to the main check or also skip?
+**L7. Changed-comment handling**
+- Marker-shaped comments are findings when changed; verify whitespace variants against the changed-code rule.
+- Adversarial probes: compare shebang and docstring handling with the changed marker-comment result across the original and changed-code paths.
 
 **L8. Sibling-implementation comparison**
 - If a parallel implementation exists in another language or paradigm (Python + PowerShell hook, regex + tokenize, JavaScript + Go), does the AFTER implementation produce the same accept/reject decisions as the sibling for shared inputs?
@@ -75,53 +78,53 @@ Lead: `Total: N (P0=N, P1=N, P2=N)`. For each sub-bucket L1-L8, produce Shape A
 
 Audit jl-cmd/claude-dev-env PR #479 for **Category L only** (behavior-equivalence for refactors). Skip A–K, M, N. Sub-bucket forced-exhaustion mode: Category L is decomposed into 8 sub-buckets below.
 
-PR: refactor(hooks): tokenize-based exempt-marker recognition for the no-new-comments gate
+PR: refactor(hooks): tokenize-based comment recognition
 Base SHA: (the commit before the tokenize-based rewrite landed)
 Head SHA at audit time: (the commit that landed the rewrite)
 ID prefix: `find`.
 
-The rewrite changed `_is_exempt_python_comment` from a normalization-based check (it ran `comment_string[1:].lstrip()` to strip the leading `#` and surrounding whitespace, then tested the body against the exempt-marker set) to a tokenize-based recognizer that tests each raw `tokenize.COMMENT` token string against `startswith("# noqa")`. The wider hook structure was left unchanged. The audit goal: identify any input shape the normalization-based BEFORE implementation accepted that the tokenize-based AFTER implementation now misclassifies as a non-exempt comment, OR any input the BEFORE rejected that the AFTER now accepts.
+- Marker-shaped comments are findings when changed; verify whitespace variants against the changed-code rule.
 
 ## Sub-buckets (each requires Shape A finding OR Shape B with ≥3 adversarial probes)
 
 **L1. KNOWN_GOOD_INPUTS table presence**
-- The PR ships `test_code_rules_enforcer_exempt_marker_chained.py` with 14 parametric inputs covering `# noqa`, `# pylint:`, `# pragma:`, `# type:`, `# TODO`, `# FIXME`, shebang at line 1, and a chained-comment variant. The table does NOT include the no-space variant `#noqa` — this is the first L1 gap.
-- Adversarial probes: scan the BEFORE implementation for the literal `"# noqa"` — production files at the base SHA carry `#noqa: F401` (no space) on at least three import lines. These are KNOWN_GOOD_INPUTS the table is missing.
+- Marker-shaped comments are findings when changed; verify whitespace variants against the changed-code rule.
+- Marker-shaped comments are findings when changed; verify whitespace variants against the changed-code rule.
 
 **L2. Whitespace / separator variants**
-- The BEFORE state stripped the leading `#` and surrounding whitespace from the comment text, then tested the body against the exempt-marker set — both `# noqa: F401` and `#noqa: F401` reduce to the body `noqa: F401`, which the set contains, so the BEFORE accepts both. The tokenize-based AFTER tests each raw `tokenize.COMMENT` token string against `startswith("# noqa")`, which matches only when a space separates `#` from `noqa`; `#noqa: F401` fails the prefix check. The AFTER therefore drops `#noqa` while the BEFORE accepts it — a behavior regression on the no-space axis.
-- Adversarial probe: construct `#noqa: F401` and trace through both. The BEFORE's strip-`#`-and-whitespace step yields body `noqa: F401`, which IS in the exempt-marker set, so the BEFORE returns True. The AFTER's `startswith("# noqa")` against the raw token `"#noqa: F401"` returns False (no space separating `#` from `noqa`) — the AFTER returns False. L2 detects a dropped accept on the no-space variant.
-- Per Category L's stated equivalence rule, a dropped accept is a regression: an exempt marker the BEFORE recognizes falls through to the main check under the AFTER, so the no-new-comments gate blocks writes carrying `#noqa: F401` that the BEFORE passed. Flag it P1 because the regression silently re-enables blocking on inputs production code carries.
+- Marker-shaped comments are findings when changed; verify whitespace variants against the changed-code rule.
+- Marker-shaped comments are findings when changed; verify whitespace variants against the changed-code rule.
+- Marker-shaped comments are findings when changed; verify whitespace variants against the changed-code rule.
 - The CRLF / tab variants pass through the AFTER tokenizer identically.
 
 **L3. Adjacent-form regressions**
-- The BEFORE pattern `startswith("# noqa")` is a 6-character prefix check. The AFTER's tokenize-based check strips `#` and surrounding whitespace, then tests the body against the exempt-marker set. The AFTER's pattern is therefore looser on the leading whitespace axis (accepts `#  noqa` and `# noqa`) but no looser on the body content. Verified clean.
-- Adversarial probe: construct `# noqa-but-not-really: F401` — does the BEFORE startswith accept (yes, prefix match) and the AFTER's token-body check also accept (yes, the body starts with `noqa`)? Both accept; no regression.
+- Marker-shaped comments are findings when changed; verify whitespace variants against the changed-code rule.
+- Marker-shaped comments are findings when changed; verify whitespace variants against the changed-code rule.
 
 **L4. Empty / boundary inputs**
 - Empty input: BEFORE's `startswith` returns False on empty string. AFTER's `tokenize.COMMENT` token list is empty for an empty source; the iteration body never runs; the function returns False. Equivalent.
-- Single character `#`: BEFORE's startswith returns False (length 1 < 6 prefix); AFTER's tokenize emits a COMMENT token with string `"#"`, which the AFTER's strip-and-compare reduces to empty string, which fails the exempt-marker set membership test. Equivalent.
+- Single character marker text remains a regular comment candidate under the changed-code rule. Equivalent.
 
 **L5. Invariant preservation**
-- BEFORE's chain `startswith("# noqa") or startswith("# pylint:") or ...` short-circuits on first match. AFTER's set-membership lookup is O(1); no iteration order. Both return True on first match. Verified clean.
+- Marker-shaped comments are findings when changed; verify whitespace variants against the changed-code rule.
 
 **L6. Implementation-tag parity**
-- BEFORE tag: `str.startswith` chain. AFTER tag: `tokenize.tokenize` + set-membership. The token-based AFTER picks up `# noqa` inside a string literal — wait, does it? The `tokenize.COMMENT` token type fires only for actual comment tokens, not for `#` characters inside string literals. So a string `"foo # noqa bar"` does NOT emit a COMMENT token. BEFORE's `startswith` would not have matched either (the line starts with a string literal). Verified clean.
-- Adversarial probe: construct an input where the comment is at end-of-line after a string literal (`x = "foo"  # noqa: F401`). BEFORE's `startswith` operates on `comment.string` (the part after `#`), so it would have accepted. AFTER's tokenize emits a COMMENT token for the same trailing comment. Both accept.
+- Marker-shaped comments are findings when changed; verify whitespace variants against the changed-code rule.
+- Marker-shaped comments are findings when changed; verify whitespace variants against the changed-code rule.
 
-**L7. Skipped-category exhaustion**
-- BEFORE skipped: shebang at line 1 column 0, `# type:` with trailing justification. AFTER's skip logic must continue to apply these. The PR ships `_build_comment_token` test fixtures that exercise shebang-at-line-1 and shebang-elsewhere; the AFTER skip-list matches the BEFORE skip-list. Verified clean.
+**L7. Changed-comment handling**
+- Marker-shaped comments are findings when changed; verify whitespace variants against the changed-code rule.
 
 **L8. Sibling-implementation comparison**
-- No sibling implementation of exempt-marker recognition exists at this SHA. L8 is verified clean — no parallel implementation.
+PR: refactor(hooks): tokenize-based comment recognition
 
 ## Cross-bucket questions to answer at the end
 
-Q1: Yes — there is a single input class that the BEFORE accepted and the AFTER rejects: `#noqa: F401` (no space after the leading `#`). The BEFORE's `_is_exempt_python_comment` strips the leading `#` and surrounding whitespace from the comment text, yielding body `noqa: F401`, which the exempt-marker set contains, so the BEFORE returns True. The AFTER's `startswith("# noqa")` against the raw `tokenize.COMMENT` token `"#noqa: F401"` returns False (the literal prefix `"# noqa"` requires the space separating `#` from `noqa`), so the AFTER returns False. The divergence lives at the AFTER's prefix-only `startswith("# noqa")` check in `code_rules_enforcer.py::_is_exempt_python_comment` against the BEFORE's strip-and-compare step. The same L1 KNOWN_GOOD_INPUTS gap — the no-space variant absent from the table — masks this divergence at audit time, since the rewrite's parametric tests never probe it.
+- Marker-shaped comments are findings when changed; verify whitespace variants against the changed-code rule.
 
-Q2: Worst behavior-equivalence break candidate: the dropped accept for the no-space `#noqa` variant — the BEFORE's strip-`#`-and-whitespace logic reduces both `# noqa: F401` and `#noqa: F401` to the same body `noqa: F401` and accepts both, while the AFTER's `startswith("# noqa")` rejects `#noqa` (without the space separating `#` from `noqa`). Mark this P1 because production code at the audit SHA carries `#noqa: F401` on real import lines, so the regression silently re-enables the no-new-comments gate against writes the BEFORE passed; downgrade to P2 only when no production input carries the no-space variant.
+- Marker-shaped comments are findings when changed; verify whitespace variants against the changed-code rule.
 
-Q3: The next-likely behavior-equivalence break is the `# pylint:` family — the AFTER's set-membership test uses literal strings, but `pylint:` directives can carry comma-separated options that the BEFORE startswith would have accepted unchanged. Future tightening of the AFTER's set lookup could silently reject `pylint: disable=line-too-long,too-many-arguments`.
+- Marker-shaped comments are findings when changed; verify whitespace variants against the changed-code rule.
 
 ## Output
 

package/docs/CODE_RULES.md

@@ -8,9 +8,10 @@ The canonical review-criteria instruction set for every AI agent that audits pul
 
 ## COMMENT PRESERVATION
 
-**Keep existing comments in place.** Only evaluate comments on lines you are actively changing. Do not add new inline comments in production code — write self-documenting code. Docstrings (module/class/function) are always allowed. Test files are exempt. The hook treats the two directions differently: adding a new inline comment blocks the edit, while removing an existing comment prints a stderr advisory and lets the edit through.
+Do not add code comments. Preserve existing comments. Docstrings remain allowed.
 
-Scaffolding and placeholder code carry a `TODO:` comment naming the permanent implementation and why the code is temporary — the documented exception to the no-new-comments rule.
+When a change touches code that an existing comment describes or is attached to, remove that comment in the same change and carry its meaning through clear names and structure. Leave comments tied to untouched code unchanged. Keep comment cleanup inside the requested task.
+Production and tests follow one rule. Changed directive, TODO, FIXME, HACK, XXX, and type-ignore comments are removed rather than added or justified.
 
 ---
 
@@ -30,7 +31,7 @@ Scaffolding and placeholder code carry a `TODO:` comment naming the permanent im
 
 no new comments · imports at top · logging format args (`log_*("...", arg)`) · no `%s`/`%d` printf tokens in a `str.format`-logger message (`log_*` imported from `automation_logging`; `str.format` drops the args — use `{}`) · no magic values in production bodies (0, 1, -1 exempt) · UPPER_SNAKE constants only in `config/` (exempt: `config/*`; `/migrations/`; Workflow registries: path contains any of these substrings — `/workflow/`, `_tab.py`, `/states.py`, or `/modules.py`, each matching independently as a substring, so `pkg/states.py` qualifies while a top-level `states.py` follows the standard `config/` rule; test files — path or filename matches `test_`, `_test.`, `.spec.`, `conftest`, or `/tests/`) · no hardcoded user home paths · guarded `sys.path.insert` · 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`, a parameter typed bare `object` whose body reads `param.attribute`) 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`, …) · known pytest fixture parameters a test function declares but never references (drop the unused parameter — pytest still pays its setup cost) · JavaScript/TypeScript boolean declarations (`const`/`let`/`var` bound to a boolean literal or negation) and `@param {boolean}` JSDoc names prefixed `is`/`has`/`should`/`can`/`was`/`did` (camelCase forms) · banned identifiers as `.mjs`/`.js` declaration names (`result`, `data`, `ctx`, `msg`, …), scoped to changed lines · in test files, banned identifiers fire on changed lines, and pytest-collectable `test_*` functions need a return annotation · unused module-level imports and unsorted import blocks are ruff's job (F401, isort I001), not this hook's · a `hooks/blocking/` command classifier anchors its multi-word command regex to the command start (`^`/`\A`) or tokenizes the first word (`shlex.split`), never matching a command as a bare substring
 
-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. The same set of fixtures is also subject to a use check: a pytest-collected test function that declares one of these parameters and never references it in its body fails the gate, because pytest materializes the fixture's setup (the temp directory, the monkeypatch context, the output capture) on every run whether or not the body reads the value — drop the unused parameter. A parameter counts as referenced when its name is read, augmented-assigned, or deleted anywhere in the body, including inside a nested function or comprehension. Only pytest-collectable functions are inspected — those at module top level or defined directly in a class body; a function nested inside another function's body is a local helper pytest never collects, so its fixture-named parameter is exempt. A `@pytest.fixture`-decorated function is exempt from the use check, since injecting one fixture into another purely to order its setup is intentional. Ordinary test parameters stay exempt from both checks. See also the file-global constants use-count rule: [`rules/file-global-constants.md`](../rules/file-global-constants.md).
+Test files follow the comment policy above; other test-specific exemptions are listed here. 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. The same set of fixtures is also subject to a use check: a pytest-collected test function that declares one of these parameters and never references it in its body fails the gate, because pytest materializes the fixture's setup (the temp directory, the monkeypatch context, the output capture) on every run whether or not the body reads the value — drop the unused parameter. A parameter counts as referenced when its name is read, augmented-assigned, or deleted anywhere in the body, including inside a nested function or comprehension. Only pytest-collectable functions are inspected — those at module top level or defined directly in a class body; a function nested inside another function's body is a local helper pytest never collects, so its fixture-named parameter is exempt. A `@pytest.fixture`-decorated function is exempt from the use check, since injecting one fixture into another purely to order its setup is intentional. Ordinary test parameters stay exempt from both checks. See also the file-global constants use-count rule: [`rules/file-global-constants.md`](../rules/file-global-constants.md).
 
 ---
 
@@ -46,17 +47,17 @@ Full words only (`context`, not `ctx`). Exceptions: `i`/`j`/`k` in loops, `e` fo
 
 ### Public compatibility definitions
 
-A public function may use the exact inline marker `# pragma: no-banned-noun` on its `def` line. The banned-noun check permits the function name and parameters on that definition. Body local bindings, other definitions, and similar names remain checked.
+The banned-noun check applies to public function definitions, parameters, and body bindings. Use clear names instead of a directive marker.
 
 ---
 
 ## 6. COMPLETE TYPE HINTS
 
-ALL parameters typed, ALL returns typed. No `Any`. A `# type: ignore` is allowed only with a second trailing `#` justification of at least five characters (e.g. `# type: ignore[misc]  # stubs missing in foo library`); bare ignores are blocked by `code_rules_enforcer.py`. Prefer fixing the type over an ignore when a real annotation is available.
+ALL parameters typed, ALL returns typed. No `Any`. Avoid `# type: ignore`; remove it and use a typed boundary or real type. Prefer fixing the type over an ignore when a real annotation is available.
 
 ## 6.5 FILE LENGTH GUIDANCE
 
-Advisory only, never blocking: soft advisory at >= 400 lines, strong nudge at >= 1000 (pylint / SonarQube defaults). Split on cohesion (SRP, "Large Class" smell), not line count — run the readability rubric when an advisory fires.
+Advisory only, never blocking: emit a stderr advisory at >= 400 lines and a stronger stderr advisory at >= 1000 (pylint / SonarQube defaults). Split on cohesion (SRP, "Large Class" smell), not line count — run the readability rubric when an advisory fires.
 
 ---
 
@@ -66,8 +67,6 @@ Advisory only, never blocking: soft advisory at >= 400 lines, strong nudge at >=
 Never: ABC for single impl, DI frameworks, factory for single type. Always: functions when no state, concrete classes, simple imports.
 Parameters follow YAGNI: add an optional parameter when a caller varies the value; when every call site passes the same value, make it required or inline the constant. Remove parameters no caller passes and no body reads.
 
-**Complexity budget — state it BEFORE implementation:** files (target 1-2, max 3), lines (~50-300). Checkpoints: Is this the MINIMUM? Can it be fewer files? Functions instead of classes?
-
 ## 7.5 SOLID PRINCIPLES
 
 **SRP always applies** — one reason to change per function/class/module. **OCP, LSP, ISP, DIP apply only where two or more concrete implementations already share a contract**; with a single concretion §7 wins (concrete classes, direct imports, YAGNI — introduce the abstraction at the commit that adds the second concretion). Misapplication signals: interface/ABC with exactly one implementation, SRP-splitting a cohesive class by size alone, abstract factories for one product, DI containers where every injected type has one concretion.