claude-dev-env 2.8.0 → 2.10.0

package/docs/references/prose-style-enforcement.md

@@ -0,0 +1,25 @@
+# Prose-style enforcement
+
+Opinionated prose gates (heavy-word swaps, hedging, historical state phrasing, intent-only endings, hook prose-detector consistency) are **off by default**.
+
+## Opt-in
+
+Set `CLAUDE_PROSE_STYLE_ENFORCEMENT` to `1`, `true`, `yes`, or `on` (case and spaces ignored). Any other value, and an unset variable, leave those gates off.
+
+The flag is `PROSE_STYLE_ENFORCEMENT_ENABLED` in `hooks/blocking/config/prose_style_enforcement_constants.py`.
+
+## Always on
+
+Structural AskUserQuestion lean-block validation in `plain_language_blocker` (chat detail, length caps on question blocks) stays active regardless of the flag. Code-rules and security blockers are out of scope for this switch.
+
+## Advisory precision measurement (OP-07B)
+
+When the flag is off, heavy-word and hedging hits still emit privacy-safe advisory candidates to `~/.claude/logs/prose-matcher-advisory.jsonl` (matcher id, surface, hashed context fingerprint, optional label). Classification (`keep` / `narrow` / `drop` / `advisory`) uses a labeled sample floor of 30 and precision floors 0.7 / 0.4. Matchers below the floor stay advisory. No matcher becomes hard-blocking from historical labels alone. See `hooks/observability/prose_matcher_advisory.py`.
+
+## Explicit uncertainty (OP-07C)
+
+With enforcement on, a hedge word in a sentence that also labels the claim (`unverified`, `I don't know`, `no source for this claim`, …) passes. A bare hedge in a different sentence still blocks. Detail: `rules/hedging-claims.md`.
+
+## Plain-language advisory (OP-07D)
+
+Heavy-word matches never hard-deny a Write/Edit or AskUserQuestion. With enforcement on, the hook allows the call and returns a `systemMessage` that names everyday swaps for both AskUserQuestion and `.md` writes. Lean-block structure denials stay hard. Detail: `rules/plain-language.md`.

package/docs/references/team-advisor-skill.md

@@ -1,14 +1,20 @@
-# Team-Advisor Skill Invocation
+# Team-Advisor Skill
 
-`/team-advisor` spawns a standing review agent for the session at the strongest reachable model tier, run at the highest reasoning effort. Use it to get a second opinion from a distinct model line than the one driving the session. For example:
+`/team-advisor` binds one standing warm advisor for this session at the strongest reachable tier. Use it when `advisor()` is absent, or when you want a standing four-signal reviewer across many decision points.
 
-- Claude session -> consult Fable xhigh
-- Codex session -> consult Sol xhigh
+## Refs
 
-## When to use it
+| Doc | Holds |
+|---|---|
+| `skills/team-advisor/SKILL.md` | Sole-consumer bind wiring and constraints |
+| `advisor-tool.md` | Consult timing, hard rule, how to treat advice |
+| `~/.claude/_shared/advisor/advisor-protocol.md` | Host bind, floor, lifecycle |
+| `agents/session-advisor.md` | ENDORSE / CORRECTION / PLAN / STOP |
 
-Consult the spawned advisor before big decisions, before declaring work complete, before any commit, when a failure repeats, or when reconsidering a chosen approach.
+## When to use
 
-## Relationship to the advisor tool
+Follow the call rules in `advisor-tool.md` (orientation first, then consult before substantive work; durable deliverable before the completion consult; stuck or reapproach; long tasks twice).
 
-`/team-advisor` works standalone; it needs no `advisor()` tool present. When both are available (see `advisor-tool.md` in this directory), use `advisor()` for a fast, history-forwarding check before substantive work, and `/team-advisor` for a standing reviewer consulted at decision points.
+## Relation to `advisor()`
+
+`/team-advisor` works with no `advisor()` tool. When both exist: `advisor()` for a fast history-forwarded check; `/team-advisor` for a standing named reviewer consulted at the same cadence.

package/hooks/blocking/CLAUDE.md

@@ -82,16 +82,16 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | `destructive_command_blocker.py` | PreToolUse (Bash/PowerShell) | Shell commands with destructive literals (`rm -rf`, `git reset --hard`, etc.) |
 | `docstring_rule_gate_count_blocker.py` | PreToolUse (Write/Edit/MultiEdit) | A stale spelled-out gate-validator count in `docstring-prose-matches-implementation.md` — the "N more gate validators" / "M gated slices" count drifting from the `check_docstring_*` validators the prose names |
 | `duplicate_rmtree_helper_blocker.py` | PreToolUse (Write/Edit) | A local re-definition of the Windows-safe rmtree helper trio (`_strip_read_only_and_retry`, `_force_remove_tree` / `force_rmtree`) in place of importing a shared helper |
-| `eli11_reply_enforcer.py` | Stop | Final replies breaking the `eli11-replies` shape — more than 120 reader-visible words, more than 6 bullet lines, more than 2 lines carrying over 20 words each, or instruction lines telling the user to act with no numbered step among the lead lines. Code fences, inline code, blockquotes, table rows, and link targets come off before the reply is judged, replies under 60 words always pass, and a reply opening with `Long form:` opts out entirely |
+| `eli11_reply_enforcer.py` | Stop | Final replies breaking the `eli11-replies` shape — more than 6 bullet lines, more than 2 list lines over 20 words each, or multi-line instructions with no numbered step among the lead lines. Code fences, inline code, blockquotes, table rows, and link targets come off before the reply is judged. |
 | `env_var_table_code_drift_blocker.py` | PreToolUse (Write/Edit/MultiEdit) | A markdown env-var summary table row attributing an environment variable to a code file whose source never references that variable name |
 | `es_exe_path_rewriter.py` | PreToolUse | Rewrites paths referencing `.exe` under the Everything search path |
 | `fable_spawn_gate.py` | PreToolUse (Agent/Task) | An `Agent` or `Task` spawn whose prompt carries no `FABLE-SPAWN-AUTHORIZED` token and whose model field reads `fable` in any letter case — the bare alias, or a delimiter segment of a full model id, so `claude-fable-5` is denied too |
 | `gh_body_arg_blocker.py` | PreToolUse (Bash) | `gh` commands passing `--body`/`-b` directly (requires `--body-file` instead) |
 | `gh_pr_author_enforcer.py` | PreToolUse | Enforces PR author identity rules |
 | `gh_pr_author_restore.py` | PostToolUse | Restores PR author after a tool call |
-| `hedging_language_blocker.py` | Stop | Responses with hedging words (`likely`, `probably`, `appears to`) |
-| `hook_prose_detector_consistency.py` | PreToolUse (Write/Edit) | Hook docstrings/messages that claim a trigger the detector cannot fire on |
-| `intent_only_ending_blocker.py` | Stop | Responses that end on a plan or intent without doing the work |
+| `hedging_language_blocker.py` | Stop | Responses with hedging words (`likely`, `probably`, `appears to`); armed only when `CLAUDE_PROSE_STYLE_ENFORCEMENT` is on (default off) |
+| `hook_prose_detector_consistency.py` | PreToolUse (Write/Edit) | Hook docstrings/messages that claim a trigger the detector cannot fire on; armed only when `CLAUDE_PROSE_STYLE_ENFORCEMENT` is on (default off) |
+| `intent_only_ending_blocker.py` | Stop | Responses that end on a plan or intent without doing the work; armed only when `CLAUDE_PROSE_STYLE_ENFORCEMENT` is on (default off) |
 | `open_questions_in_plans_blocker.py` | PreToolUse (Write/Edit) | Plan documents with unresolved open questions |
 | `nas_ssh_binary_enforcer.py` | PreToolUse (Bash) | A bare `ssh`/`scp`/`sftp` command word targeting the NAS (Git Bash's MSYS ssh stalls on an interactive password prompt), or the full `System32/OpenSSH` binary to that host without `-o BatchMode=yes` |
 | `package_inventory_stale_blocker.py` | PreToolUse (Write) | A new production code file created in a directory whose `README.md`/`CLAUDE.md` inventory (or a parent skill's `SKILL.md` Layout table mapping the `scripts/` subdirectory) names two or more sibling files but no entry for the new file |
@@ -100,7 +100,7 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | `pii_prevention_blocker.py` | PreToolUse (Write/Edit/MultiEdit/Bash/PowerShell/MCP GitHub) | Entry hook — content that carries high-confidence personal data or secrets (real emails, home-dir paths, private IPs, credential material) on write, durable GitHub posts, or staged commit paths; resolves the staged-commit repository from the command it gates (via `pii_prevention_blocker_parts`), not the session working directory |
 | `pii_scanner.py` | library | Pure text scanners shared by `pii_prevention_blocker.py` |
 | `piped_pytest_blocker.py` | PreToolUse (Bash) | A pytest run whose output feeds a pipe, where the pipeline reports the exit code of the command on the right |
-| `plain_language_blocker.py` | PreToolUse (Write/Edit/AskUserQuestion) | Heavy or jargon words in user-facing prose |
+| `plain_language_blocker.py` | PreToolUse (Write/Edit/AskUserQuestion) | Heavy or jargon words in user-facing prose when `CLAUDE_PROSE_STYLE_ENFORCEMENT` is on (default off); AskUserQuestion lean-block structure stays always on |
 | `pr_converge_bugteam_enforcer.py` | PreToolUse | Enforces that bugteam runs in parallel with bugbot in pr-converge loops |
 | `pr_description_enforcer.py` | PreToolUse (Bash) | `gh pr create`/`edit`/`comment` bodies that fail the Anthropic claude-code style audit, proof-shaped `gh pr comment` bodies missing proof-of-work parts, and `gh pr ready` while the PR carries no passing proof comment |
 | `precommit_code_rules_gate.py` | PreToolUse (Bash) | Staged changes that fail the CODE_RULES gate at commit time |
@@ -113,7 +113,7 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | `session_handoff_blocker.py` | Stop | Responses suggesting a new session mid-task |
 | `shell_substitution_blocker.py` | PreToolUse (Bash) | A command carrying `$(...)`, a live backtick, or `<(...)`/`>(...)` process substitution, which the allowlist matcher cannot descend into |
 | `stale_comment_reference_blocker.py` | PreToolUse (Edit) | An Edit that rewrites a Python code line while keeping the standalone comment directly above it, when that comment names an identifier the rewrite removes from the line |
-| `state_description_blocker.py` | PreToolUse (Write/Edit) | Historical/comparative language in documentation |
+| `state_description_blocker.py` | PreToolUse (Write/Edit) | Historical/comparative language in documentation; armed only when `CLAUDE_PROSE_STYLE_ENFORCEMENT` is on (default off) |
 | `subprocess_budget_completeness.py` | PreToolUse | Subprocess calls missing required budget arguments |
 | `tdd_enforcer.py` | PreToolUse (Write/Edit) | Production code written without a matching failing test |
 | `unscoped_search_blocker.py` | PreToolUse (Bash/PowerShell) | A `find` or recursive listing that walks from the filesystem root, a drive root, bare home, or a network share root |

package/hooks/blocking/_path_setup.py

@@ -1,13 +1,17 @@
-"""Add the hooks directory to sys.path for sibling entry-point dispatchers.
+"""Add the hooks and blocking directories to sys.path for sibling imports.
 
 Importing this module inserts the hooks directory (this file's parent's parent)
-at the front of sys.path so a dispatcher that runs as a standalone script from
-blocking/ can import hooks_constants with every import kept at module top.
+and the blocking directory (its own parent) at the front of sys.path, so a
+module that runs as a standalone script from blocking/ can import both
+``hooks_constants`` and its blocking-directory siblings while every import stays
+at module top.
 """
 
 import sys
 from pathlib import Path
 
+_blocking_directory = str(Path(__file__).resolve().parent)
 _hooks_directory = str(Path(__file__).resolve().parent.parent)
-if _hooks_directory not in sys.path:
-    sys.path.insert(0, _hooks_directory)
+for each_directory in (_blocking_directory, _hooks_directory):
+    if each_directory not in sys.path:
+        sys.path.insert(0, each_directory)

package/hooks/blocking/code_rules_docstrings.py

@@ -13,6 +13,7 @@ if _hooks_directory not in sys.path:
     sys.path.insert(0, _hooks_directory)
 
 from code_rules_shared import (  # noqa: E402
+    _scope_violations_to_changed_lines,
     _statement_is_docstring,
     _walk_skipping_nested_functions,
     _walk_skipping_type_checking_blocks,
@@ -2664,18 +2665,53 @@ def _runon_sentences(narrative_text: str) -> list[str]:
     return flagged_sentences
 
 
+def _docstring_owner_span(owner_node: ast.AST, anchor_lineno: int) -> range:
+    """Lines from the owner's anchor through the end of its docstring statement.
+
+    ::
+
+        def clean_helper() -> str:              <- anchor (def / class line)
+            '''run-on narrative across lines''' <- docstring end
+            return "ok"                         <- outside the span
+
+        An edit that only rewrites the docstring body intersects this span and
+        re-grades the finding. An edit to the return line does not.
+    """
+    body = getattr(owner_node, "body", None) or []
+    if not body:
+        return range(anchor_lineno, anchor_lineno + 1)
+    first_statement = body[0]
+    end_lineno = getattr(first_statement, "end_lineno", None) or first_statement.lineno
+    return range(anchor_lineno, end_lineno + 1)
+
+
 def _documentable_docstring_targets(
     parsed_tree: ast.Module,
-) -> list[tuple[int, str, str]]:
-    documentable_targets: list[tuple[int, str, str]] = []
+) -> list[tuple[int, str, str, range]]:
+    documentable_targets: list[tuple[int, str, str, range]] = []
     module_docstring = ast.get_docstring(parsed_tree)
     if module_docstring and parsed_tree.body:
-        documentable_targets.append((parsed_tree.body[0].lineno, "module", module_docstring))
+        module_anchor = parsed_tree.body[0].lineno
+        documentable_targets.append(
+            (
+                module_anchor,
+                "module",
+                module_docstring,
+                _docstring_owner_span(parsed_tree, module_anchor),
+            )
+        )
     for each_node in _walk_skipping_type_checking_blocks(parsed_tree):
         if isinstance(each_node, ast.ClassDef):
             class_docstring = ast.get_docstring(each_node)
             if class_docstring:
-                documentable_targets.append((each_node.lineno, each_node.name, class_docstring))
+                documentable_targets.append(
+                    (
+                        each_node.lineno,
+                        each_node.name,
+                        class_docstring,
+                        _docstring_owner_span(each_node, each_node.lineno),
+                    )
+                )
             continue
         if not isinstance(each_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
             continue
@@ -2686,34 +2722,58 @@ def _documentable_docstring_targets(
         function_docstring = _function_docstring_text(each_node)
         if function_docstring:
             documentable_targets.append(
-                (each_node.lineno, f"{each_node.name}()", function_docstring)
+                (
+                    each_node.lineno,
+                    f"{each_node.name}()",
+                    function_docstring,
+                    _docstring_owner_span(each_node, each_node.lineno),
+                )
             )
     return documentable_targets
 
 
-def check_docstring_runon_sentence(content: str, file_path: str) -> list[str]:
+def check_docstring_runon_sentence(
+    content: str,
+    file_path: str,
+    all_changed_lines: set[int] | None = None,
+    defer_scope_to_caller: bool = False,
+) -> list[str]:
     """Flag a docstring narrative sentence that reads as a dense run-on wall.
 
     A readable docstring breaks its narrative into short sentences a general
     developer follows on the first read. The one mechanical mark of a wall is a
     single sentence that runs past the word limit while chaining clauses with an
     em-dash, a double-hyphen, or a semicolon. This check inspects the narrative prose of module,
-    class, and public-function docstrings — the text before the first structured
+    class, and public-function docstrings - the text before the first structured
     section header (``Args:``, ``Arguments:``, ``Returns:``, ``Yields:``,
-    ``Raises:``, ``Note:``, ``Notes:``, ``Example:``, or ``Examples:``) — and
+    ``Raises:``, ``Note:``, ``Notes:``, ``Example:``, or ``Examples:``) - and
     reports a sentence that is both over the word limit and joined by one of those
     marks.
     Whether the prose paints a concrete, illustrative picture is judgment the
     plain-illustrative-docstrings audit lane carries; this gate catches only the
     run-on mark.
 
+    The caller passes the reconstructed full file as *content* so ``ast.parse``
+    sees a complete module. Findings are then scoped to *all_changed_lines* so an
+    Edit blocks on a run-on it just introduced while a pre-existing far-away
+    run-on on an untouched definition does not block the edit.
+
     Args:
-        content: The source text to inspect.
+        content: The source text to inspect - the reconstructed full file on an
+            Edit so the parse succeeds.
         file_path: The path the source will be written to, used for exemptions.
+        all_changed_lines: Post-edit line numbers the current edit touched, or
+            None to treat the whole file as in scope. When provided, a finding
+            blocks only when its definition-through-docstring span intersects
+            the changed lines.
+        defer_scope_to_caller: When True, return every violation so the
+            commit/push gate's ``split_violations_by_scope`` can scope by added
+            line.
 
     Returns:
         One issue per docstring whose narrative carries a run-on sentence, capped
-        at the module limit.
+        at the module limit and scoped to the changed lines unless
+        *defer_scope_to_caller* is True or *all_changed_lines* is None.
     """
     if is_test_file(file_path) or is_hook_infrastructure(file_path):
         return []
@@ -2721,25 +2781,37 @@ def check_docstring_runon_sentence(content: str, file_path: str) -> list[str]:
         parsed_tree = ast.parse(content)
     except SyntaxError:
         return []
-    issues: list[str] = []
-    for each_line_number, each_label, each_docstring in _documentable_docstring_targets(
-        parsed_tree
-    ):
+    all_violations_in_walk_order: list[tuple[range, str]] = []
+    for (
+        each_line_number,
+        each_label,
+        each_docstring,
+        each_span,
+    ) in _documentable_docstring_targets(parsed_tree):
         flagged_sentences = _runon_sentences(_docstring_narrative_text(each_docstring))
         if not flagged_sentences:
             continue
         run_on_word_count = _sentence_word_count(flagged_sentences[0])
-        issues.append(
+        message = (
             f"Line {each_line_number}: {each_label} docstring carries a {run_on_word_count}-word "
-            "run-on sentence — break the narrative into short, illustrative sentences a general "
+            "run-on sentence - break the narrative into short, illustrative sentences a general "
             "developer reads in one pass (plain-illustrative-docstrings)"
         )
-        if len(issues) >= MAX_DOCSTRING_RUNON_SENTENCE_ISSUES:
-            break
-    return issues[:MAX_DOCSTRING_RUNON_SENTENCE_ISSUES]
+        all_violations_in_walk_order.append((each_span, message))
+    scoped_issues = _scope_violations_to_changed_lines(
+        all_violations_in_walk_order,
+        all_changed_lines,
+        defer_scope_to_caller,
+    )
+    return scoped_issues[:MAX_DOCSTRING_RUNON_SENTENCE_ISSUES]
 
 
-def check_docstring_prose_wall_without_illustration(content: str, file_path: str) -> list[str]:
+def check_docstring_prose_wall_without_illustration(
+    content: str,
+    file_path: str,
+    all_changed_lines: set[int] | None = None,
+    defer_scope_to_caller: bool = False,
+) -> list[str]:
     """Flag a summary that tells for many sentences and shows nothing.
 
     A reader trusts the opening to paint a scene. A run of short sentences with
@@ -2754,13 +2826,28 @@ def check_docstring_prose_wall_without_illustration(content: str, file_path: str
     Past the prose-line limit with no ``::`` listing and no ``>>>`` doctest, this
     fires. A narrative that shows a worked example, or one at the limit, passes.
 
+    The caller passes the reconstructed full file as *content* so ``ast.parse``
+    sees a complete module. Findings are then scoped to *all_changed_lines* so an
+    Edit blocks on a wall it just introduced while a pre-existing far-away wall
+    on an untouched definition does not block the edit.
+
     Args:
-        content: The source text to inspect.
+        content: The source text to inspect - the reconstructed full file on an
+            Edit so the parse succeeds.
         file_path: The path the source will be written to, used for exemptions.
+        all_changed_lines: Post-edit line numbers the current edit touched, or
+            None to treat the whole file as in scope. When provided, a finding
+            blocks only when its definition-through-docstring span intersects
+            the changed lines.
+        defer_scope_to_caller: When True, return every violation so the
+            commit/push gate's ``split_violations_by_scope`` can scope by added
+            line.
 
     Returns:
         One issue per summary that runs a wall of sentences with no worked
-        example, capped at the issue limit for the rule.
+        example, capped at the issue limit for the rule and scoped to the
+        changed lines unless *defer_scope_to_caller* is True or
+        *all_changed_lines* is None.
     """
     if is_test_file(file_path) or is_hook_infrastructure(file_path):
         return []
@@ -2768,25 +2855,32 @@ def check_docstring_prose_wall_without_illustration(content: str, file_path: str
         parsed_tree = ast.parse(content)
     except SyntaxError:
         return []
-    issues: list[str] = []
-    for each_line_number, each_label, each_docstring in _documentable_docstring_targets(
-        parsed_tree
-    ):
+    all_violations_in_walk_order: list[tuple[range, str]] = []
+    for (
+        each_line_number,
+        each_label,
+        each_docstring,
+        each_span,
+    ) in _documentable_docstring_targets(parsed_tree):
         prose_lines, has_illustration = _docstring_narrative_partition(each_docstring)
         if has_illustration:
             continue
         prose_line_count = len(prose_lines)
         if prose_line_count <= DOCSTRING_NARRATIVE_PROSE_LINE_LIMIT:
             continue
-        issues.append(
+        message = (
             f"Line {each_line_number}: {each_label} summary runs {prose_line_count} "
             "narrative lines with no worked example - show, don't tell: swap the wall for a "
             "'::' listing (a sample input, an annotated outcome, ok/flag contrast rows) and "
             "keep the narrative to a few short lines (plain-illustrative-docstrings)"
         )
-        if len(issues) >= MAX_DOCSTRING_PROSE_WALL_ISSUES:
-            break
-    return issues[:MAX_DOCSTRING_PROSE_WALL_ISSUES]
+        all_violations_in_walk_order.append((each_span, message))
+    scoped_issues = _scope_violations_to_changed_lines(
+        all_violations_in_walk_order,
+        all_changed_lines,
+        defer_scope_to_caller,
+    )
+    return scoped_issues[:MAX_DOCSTRING_PROSE_WALL_ISSUES]
 
 
 def _raises_section_text(docstring_text: str) -> str:

package/hooks/blocking/code_rules_enforcer.py

@@ -18,6 +18,7 @@ concern focused. The separate ``tdd_enforcer.py`` hook accepts any
 import json
 import sys
 from collections import Counter
+from collections.abc import Callable
 from pathlib import Path
 from typing import TextIO
 
@@ -285,7 +286,15 @@ def validate_content(
         all_issues.extend(check_logging_adjacent_string_literals(content, file_path))
         all_issues.extend(check_windows_api_none(content))
         all_issues.extend(check_naive_datetime_construction(content, file_path))
-        all_issues.extend(check_magic_values(content, file_path))
+        all_issues.extend(
+            _fragment_or_deferred_check(
+                check_magic_values,
+                old_content,
+                content,
+                file_path,
+                defer_scope_to_caller,
+            )
+        )
         all_issues.extend(check_fstring_structural_literals(content, file_path))
         all_issues.extend(check_constants_outside_config(content, file_path))
         all_issues.extend(check_config_duplicate_path_anchor(content, file_path))
@@ -358,9 +367,21 @@ def validate_content(
         all_issues.extend(
             check_class_docstring_names_public_methods(effective_content, file_path)
         )
-        all_issues.extend(check_docstring_runon_sentence(effective_content, file_path))
         all_issues.extend(
-            check_docstring_prose_wall_without_illustration(effective_content, file_path)
+            check_docstring_runon_sentence(
+                effective_content,
+                file_path,
+                all_changed_lines,
+                defer_scope_to_caller,
+            )
+        )
+        all_issues.extend(
+            check_docstring_prose_wall_without_illustration(
+                effective_content,
+                file_path,
+                all_changed_lines,
+                defer_scope_to_caller,
+            )
         )
         all_issues.extend(
             check_module_docstring_names_public_checks(effective_content, file_path)
@@ -508,8 +529,24 @@ def validate_content(
         all_issues.extend(check_polarity_name_contradiction(content, file_path))
         all_issues.extend(check_inline_literal_collections(content, file_path))
         all_issues.extend(check_inline_tuple_string_magic(content, file_path))
-        all_issues.extend(check_join_separator_string_magic(content, file_path))
-        all_issues.extend(check_string_literal_magic(content, file_path))
+        all_issues.extend(
+            _fragment_or_deferred_check(
+                check_join_separator_string_magic,
+                old_content,
+                content,
+                file_path,
+                defer_scope_to_caller,
+            )
+        )
+        all_issues.extend(
+            _fragment_or_deferred_check(
+                check_string_literal_magic,
+                old_content,
+                content,
+                file_path,
+                defer_scope_to_caller,
+            )
+        )
         all_issues.extend(check_whitespace_indentation_magic(content, file_path))
         all_issues.extend(check_orphan_css_classes(effective_content, file_path))
         check_incomplete_mocks(content, file_path)
@@ -723,6 +760,124 @@ def _without_line_prefix(violation_text: str) -> str:
     return violation_text
 
 
+def _issues_absent_from_prior_bodies(
+    all_candidate_issues: list[str],
+    all_prior_issues: list[str],
+) -> list[str]:
+    """Return candidates whose message bodies are not covered by prior issues.
+
+    Matching is line-number-agnostic with per-occurrence accounting: each prior
+    entry consumes exactly one candidate carrying the same body.
+
+    ::
+
+        prior:    ["Line 1: magic 'X'"]
+        candidates: ["Line 4: magic 'X'", "Line 9: magic 'Y'"]
+        -> ["Line 9: magic 'Y'"]
+
+    Args:
+        all_candidate_issues: Findings from the scan under review.
+        all_prior_issues: Findings that already account for a body.
+
+    Returns:
+        Candidates not consumed by a matching prior body.
+    """
+    remaining_prior_counts = Counter(
+        _without_line_prefix(each_issue) for each_issue in all_prior_issues
+    )
+    all_uncovered_issues: list[str] = []
+    for each_issue in all_candidate_issues:
+        message_body = _without_line_prefix(each_issue)
+        if remaining_prior_counts[message_body] > 0:
+            remaining_prior_counts[message_body] -= 1
+            continue
+        all_uncovered_issues.append(each_issue)
+    return all_uncovered_issues
+
+
+def _fragment_or_deferred_check(
+    check_function: Callable[[str, str], list[str]],
+    old_content: str,
+    new_content: str,
+    file_path: str,
+    defer_scope_to_caller: bool,
+) -> list[str]:
+    """Run a check with fragment baselining, or full-file when the gate owns scope.
+
+    The commit/push gate sets ``defer_scope_to_caller`` and passes HEAD as
+    ``old_content`` while scanning the current file (often the same blob on a
+    clean worktree). Fragment baselining would grandfather every finding there,
+    so the gate path runs the check on ``new_content`` alone and classifies by
+    added line afterward. PreToolUse Edit keeps baselining against the prior
+    fragment.
+
+    ::
+
+        defer=True, old==new with magic 9999
+            -> [Line 2: Magic value 9999 ...]  gate still sees it
+        defer=False, old and new both carry the same magic
+            -> []  grandfathered for wide Edit
+
+    Args:
+        check_function: A ``(content, file_path) -> list[str]`` check.
+        old_content: Prior fragment or gate HEAD blob.
+        new_content: Proposed fragment or current full file.
+        file_path: Destination path used for path-based exemptions.
+        defer_scope_to_caller: True when the gate will scope by added line.
+
+    Returns:
+        Findings from the check, baselined against ``old_content`` only when
+        ``defer_scope_to_caller`` is False.
+    """
+    if defer_scope_to_caller:
+        return check_function(new_content, file_path)
+    return _issues_introduced_in_fragment(
+        check_function, old_content, new_content, file_path
+    )
+
+
+def _issues_introduced_in_fragment(
+    check_function: Callable[[str, str], list[str]],
+    old_content: str,
+    new_content: str,
+    file_path: str,
+) -> list[str]:
+    """Return fragment findings that are new relative to the pre-edit fragment.
+
+    Grades both the prior and proposed Edit fragments with the same check, then
+    subtracts findings whose message body already appears in the prior scan.
+    Per-occurrence accounting keeps a second identical new finding when only
+    one matching body existed before. Line numbers on kept findings come from
+    the proposed fragment so diagnostics point at the introduced location.
+
+    ::
+
+        old:  def f(): return os.environ['STRIPE_SECRET']
+        new:  def f(): return os.environ['STRIPE_SECRET']  # same body
+              -> []  grandfathered
+        old:  def f(): return 0
+        new:  def f(): return os.environ['STRIPE_SECRET']
+              -> [Line ...: string magic value 'STRIPE_SECRET' ...]
+
+    Args:
+        check_function: A ``(content, file_path) -> list[str]`` check.
+        old_content: The Edit's prior ``old_string`` fragment, or empty when
+            there is no prior region to baseline against.
+        new_content: The Edit's ``new_string`` fragment (or Write body).
+        file_path: Destination path used for path-based exemptions.
+
+    Returns:
+        Findings present in ``new_content`` that are absent from ``old_content``
+        under line-number-agnostic body matching. When ``old_content`` is empty,
+        every finding from ``new_content`` is returned.
+    """
+    all_new_issues = check_function(new_content, file_path)
+    if not old_content:
+        return all_new_issues
+    all_old_issues = check_function(old_content, file_path)
+    return _issues_absent_from_prior_bodies(all_new_issues, all_old_issues)
+
+
 def _forecast_full_file_violations(
     full_file_content_after_edit: str,
     file_path: str,
@@ -763,17 +918,7 @@ def _forecast_full_file_violations(
     all_full_file_issues = validate_content(
         full_file_content_after_edit, file_path, prior_full_file_content
     )
-    remaining_blocking_counts = Counter(
-        _without_line_prefix(each_issue) for each_issue in all_blocking_issues
-    )
-    forecast_issues: list[str] = []
-    for each_issue in all_full_file_issues:
-        message_body = _without_line_prefix(each_issue)
-        if remaining_blocking_counts[message_body] > 0:
-            remaining_blocking_counts[message_body] -= 1
-            continue
-        forecast_issues.append(each_issue)
-    return forecast_issues
+    return _issues_absent_from_prior_bodies(all_full_file_issues, all_blocking_issues)
 
 
 def _precheck_hint() -> str: